Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
#!/usr/bin/env python3
"""
devflow Auto-Dispatch Hook (PreToolUse)
拦截 team member 的 send_message 调用。若消息是 *_completed 事件且
routing_table 中有确定性下一目标,则用 modifiedInput 把 recipient 从 "main"
改成下一个角色,并注入 dispatch_prompt——消息直达下游,main 不被唤醒。
Fallback(仍发 main)的场景:
- *_failed(需 main 判断 retry_count)
- manual_gates 事件(auto_mode=false 时需用户确认)
- workflow_completed(需 main 执行清理)
- SOLO_overflow(需 main 重新 Phase 0)
- shutdown_request / shutdown_response
- payload 缺少 dispatch_prompt 或 next_target
"""
import json
import os
import re
import sys
from datetime import datetime, timezone
from pathlib import Path
# ── 诊断日志 ──
# 写入 .codebuddy/hooks/logs/auto-dispatch.log(JSONL,每行一条事件)
# 记录每次 hook 拦截的:tool_name / sender / recipient / event / 决策(dispatch|fallback|passthrough)/ 原因 / 时间戳
# 便于排查"消息送达但 member 不执行"等问题
def _project_root() -> str:
return os.environ.get("CODEBUDDY_PROJECT_DIR") or os.getcwd()
_LOG_DIR = Path(_project_root()) / ".codebuddy" / "hooks" / "logs"
def _log_hook(record: dict) -> None:
"""追加一条 JSONL 诊断日志。失败静默,绝不影响派发流程。"""
try:
_LOG_DIR.mkdir(parents=True, exist_ok=True)
log_path = _LOG_DIR / "auto-dispatch.log"
record.setdefault("ts", datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f%z"))
with open(log_path, "a", encoding="utf-8") as f:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
except Exception:
pass
# ── routing_table(与 devflow.defaults.yaml 同步,SSOT 副本) ──
ROUTING_TABLE = {
"TASK-01_completed": "architect",
"TASK-02_completed": "developer",
"TASK-03_completed": "code-reviewer",
"CODE-REVIEW_passed": "test-engineer",
"TASK-04_completed": "knowledge-engineer",
"TASK-05_completed": "leader",
}
# manual_gates(与 devflow.defaults.yaml 同步)
MANUAL_GATES = {
"TASK-02_completed",
"CODE-REVIEW_passed",
"TASK-04_completed",
}
# 必须回 main 的事件(不可自动派发)
FALLBACK_EVENTS = {
"workflow_completed",
"SOLO_overflow",
}
def _read_auto_mode_without_yaml(text: str):
"""Read only a plain multi.auto_mode block without a YAML dependency.
Unsupported syntax raises ValueError. Manual gates then stay with main.
"""
in_multi = False
seen_multi = False
mode = None
child_indent = None
for raw in text.splitlines():
if raw.lstrip().startswith("#"):
continue
line = re.split(r"\s+#", raw, maxsplit=1)[0].rstrip()
if not line.strip():
continue
if "\t" in line:
raise ValueError("Unsupported YAML indentation")
indent = len(line) - len(line.lstrip(" "))
if indent == 0:
match = re.fullmatch(r"([A-Za-z_][A-Za-z_0-9-]*):(?:\s+(.*))?", line)
if not match:
raise ValueError("Unsupported YAML mapping")
in_multi = match.group(1) == "multi"
if in_multi:
if seen_multi or match.group(2):
raise ValueError("Unsupported multi mapping")
seen_multi = True
child_indent = None
continue
if not in_multi:
continue
# Complex multi settings need a full YAML parser.
if any(char in line for char in "&*|>{}[]"):
raise ValueError("Unsupported multi syntax")
if child_indent is None:
child_indent = indent
if indent != child_indent:
raise ValueError("Unsupported multi indentation")
match = re.fullmatch(r"([A-Za-z_][A-Za-z_0-9-]*):(?:\s+(.*))?", line.strip())
if not match:
raise ValueError("Unsupported multi setting")
if match.group(1) == "auto_mode":
value = (match.group(2) or "").lower()
if mode is not None or value not in ("true", "false", "yes", "no", "on", "off"):
raise ValueError("Invalid auto_mode")
mode = value in ("true", "yes", "on")
return mode
def _read_auto_mode() -> bool:
"""Read defaults and the project override. Read errors reach the caller."""
root = Path(_project_root())
paths = [root / ".codebuddy/assets/devflow.defaults.yaml",
root / ".codebuddy/devflow.config.yaml"]
try:
import yaml # type: ignore
except ImportError:
yaml = None
auto_mode = True
for path in paths:
try:
text = path.read_text(encoding="utf-8")
except FileNotFoundError:
continue
if yaml is None:
mode = _read_auto_mode_without_yaml(text)
else:
data = yaml.safe_load(text)
if data is None:
continue
if not isinstance(data, dict):
raise ValueError("Config must be a mapping")
multi = data.get("multi", {})
if not isinstance(multi, dict):
raise ValueError("multi must be a mapping")
mode = multi.get("auto_mode")
if "auto_mode" in multi and not isinstance(mode, bool):
raise ValueError("auto_mode must be a boolean")
if mode is not None:
auto_mode = mode
return auto_mode
def _append_decision(state_path: str, event: str, action: str) -> None:
"""向 workflow-state.json 的 decisions[] 追加审计记录。"""
if not state_path:
return
try:
p = Path(state_path)
if not p.is_file():
return
with open(p, "r", encoding="utf-8") as f:
state = json.load(f)
if not isinstance(state, dict):
return
decisions = state.setdefault("decisions", [])
decisions.append({
"kind": "auto_dispatch",
"event": event,
"action": action,
"ts": _now_iso(),
})
state["updated_at"] = _now_iso()
with open(p, "w", encoding="utf-8") as f:
json.dump(state, f, ensure_ascii=False, indent=2)
except Exception:
pass # 审计失败不阻塞派发
def _now_iso() -> str:
return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S%z")
def main() -> int:
# ── 解析 hook 输入 ──
try:
data = json.loads(sys.stdin.read())
except (json.JSONDecodeError, IOError) as e:
_log_hook({"decision": "passthrough", "reason": "stdin_json_parse_failed", "error": str(e)})
print(json.dumps({"continue": True}))
return 0
tool_name = data.get("tool_name", "")
if tool_name not in ("send_message", "SendMessage"):
# 非 send_message 工具,不干预
print(json.dumps({"continue": True}))
return 0
tool_input = data.get("tool_input", {})
msg_type = tool_input.get("type", "")
sender = tool_input.get("from", "") or data.get("agent_name", "") or "unknown"
original_recipient = tool_input.get("recipient", "")
# shutdown_request / shutdown_response 照常发给 main
if msg_type != "message":
_log_hook({
"decision": "passthrough", "reason": f"non_message_type:{msg_type}",
"sender": sender, "recipient": original_recipient,
})
print(json.dumps({"continue": True}))
return 0
content_raw = tool_input.get("content", "")
if not isinstance(content_raw, str):
_log_hook({
"decision": "passthrough", "reason": "content_not_string",
"sender": sender, "recipient": original_recipient,
})
print(json.dumps({"continue": True}))
return 0
# 解析 content JSON
try:
payload = json.loads(content_raw)
except (json.JSONDecodeError, ValueError) as e:
_log_hook({
"decision": "passthrough", "reason": "content_json_parse_failed",
"sender": sender, "recipient": original_recipient,
"error": str(e), "content_preview": content_raw[:200],
})
print(json.dumps({"continue": True}))
return 0
if not isinstance(payload, dict):
_log_hook({
"decision": "passthrough", "reason": "content_not_dict",
"sender": sender, "recipient": original_recipient,
})
print(json.dumps({"continue": True}))
return 0
event = str(payload.get("event", ""))
# ── 判定是否可自动派发 ──
# 1. event 必须在 routing_table 中
next_role = ROUTING_TABLE.get(event)
if not next_role:
_log_hook({
"decision": "passthrough", "reason": "event_not_in_routing_table",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# 2. failed 事件 → 回 main
if event.endswith("_failed"):
_log_hook({
"decision": "fallback_to_main", "reason": "failed_event_needs_main_retry",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# 3. fallback 事件 → 回 main
if event in FALLBACK_EVENTS:
_log_hook({
"decision": "fallback_to_main", "reason": f"fallback_event:{event}",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# 4. 读配置:检查 auto_mode 和 manual_gates
try:
auto_mode = _read_auto_mode()
except Exception:
auto_mode = False
if event in MANUAL_GATES:
_log_hook({
"decision": "fallback_to_main", "reason": "config_unreadable",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# auto_mode=false 时,manual_gates 事件需回 main 等用户确认
if not auto_mode and event in MANUAL_GATES:
_log_hook({
"decision": "fallback_to_main", "reason": "manual_gate_auto_mode_off",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# 5. payload 必须含 dispatch_prompt
dispatch_prompt = payload.get("dispatch_prompt")
if not dispatch_prompt or not isinstance(dispatch_prompt, str):
_log_hook({
"decision": "fallback_to_main", "reason": "missing_dispatch_prompt",
"sender": sender, "recipient": original_recipient, "event": event,
})
print(json.dumps({"continue": True}))
return 0
# 6. next_target.subagent_name 必须与 routing_table 一致
next_target = payload.get("next_target") or {}
payload_target = next_target.get("subagent_name", "")
if payload_target != next_role:
_log_hook({
"decision": "fallback_to_main", "reason": "next_target_mismatch",
"sender": sender, "recipient": original_recipient, "event": event,
"expected": next_role, "actual": payload_target,
})
print(json.dumps({"continue": True}))
return 0
# ── 自动派发:modifiedInput 重定向 recipient + 注入 dispatch_prompt ──
state_path = payload.get("workflow_state_path", "")
_append_decision(state_path, event, f"auto-dispatched → {next_role}")
modified = dict(tool_input)
modified["recipient"] = next_role
modified["content"] = dispatch_prompt
modified["summary"] = f"[auto-dispatch] {event} → {next_role}"
_log_hook({
"decision": "auto_dispatch",
"sender": sender,
"original_recipient": original_recipient,
"redirected_to": next_role,
"event": event,
"dispatch_prompt_length": len(dispatch_prompt),
"workflow_state_path": state_path,
})
output = {
"continue": True,
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "allow",
"modifiedInput": modified,
},
}
print(json.dumps(output))
return 0
if __name__ == "__main__":
sys.exit(main())