Multi-agent development team orchestration. Use when managing coding agents (Codex, Claude Code, Gemini, Cursor) for automated software development: (1) Spaw...
--- name: dev-team description: "Multi-agent development team orchestration. Use when managing coding agents (Codex, Claude Code, Gemini, Cursor) for automated software development: (1) Spawning agents for tasks, (2) Monitoring agent status, (3) Managing git worktrees, (4) Automated code review, (5) Handling notifications via Feishu." --- # Dev Team One-person dev team orchestration using Levi as the orchestrator. ## Main Agent Rules (入口摘要) 主 Agent 是编排器(orchestrator),不是默认主力编码器。 关键准则: - `PR` 优先:正式开发默认使用 `--completion-mode pr` - 禁止 SubAgent 在 `main/master` 上直接开发(`spawn-agent.sh` 已拦截) - 主 Agent 使用最小上下文:优先看状态机与聚合结果,而不是全量日志 - 阶段化编排:明确 `--phase build|review|fixup` - 自动化负责推进与收口(`check/review/fixup/cleanup/prune`),人工保留最终产品决策与 GitHub `approve` - `SubAgent DONE` 不等于任务完成:合并前必须做 post-task review(DoD + 真实验证 + 指标门禁) 详细说明见: - `references/AGENTS.md`(主 Agent 行动准则) - (已合并入 `references/AGENTS.md`)编排模型与状态机 - (已合并入 `references/AGENTS.md`)主 Agent 最小上下文操作手册 ## Quick Start ### 首次使用 ```bash # 运行设置检查 scripts/setup-check.sh ``` ### 启动内置 dev-board 控制面板 `dev-team` 已内置 `scripts/dev-board/`,可直接启动: ```bash ./scripts/run-dev-board.sh ``` 默认地址:`http://localhost:4310` ### Spawn an Agent 正式功能开发(推荐 `PR` 流程): ```bash scripts/spawn-agent.sh \ --agent auto \ --phase build \ --repo-path ./scripts/dev-board \ --branch feat/auth-timeout-fix \ --description "修复登录超时错误" \ --completion-mode pr \ --prompt-file /tmp/task-prompt.txt ``` 本地 smoke / 临时探索(仅无 PR 场景使用 `session`): ```bash scripts/spawn-agent.sh \ --agent auto \ --repo-path ./scripts/dev-board \ --branch fix/auth-error \ --description "修复登录超时错误" \ --phase build \ --completion-mode session \ --prompt-file /tmp/task-prompt.txt ``` ### Check Agent Status ```bash cat assets/active-tasks.json ``` ### Monitor Agents ```bash scripts/check-agents.sh ``` ### Mandatory: Post-task Review Gate (合并前必做) 当 SubAgent 报告完成(例如 `TASK_*_DONE`)后,主 Agent 必须执行: ```bash # 1) 看任务状态与日志摘要 scripts/check-agents.sh # 2) 审核 subagent 提交内容(示例) git -C <subagent-worktree> show --name-only --oneline -n 1 <commit> # 3) 在目标仓库执行任务 DoD 规定的真实验证命令(示例) # 例如:真实 ingestion/validate、真实 API 调用、非 mock 链路 ``` 通过标准: - DoD 条款全部满足 - 至少 1 条真实链路验证通过(非 mock) - 指标达到任务阈值(如 successRate/evidenceBindingRate/citationNonEmptyRate/fallbackRate) 不通过处理: - 不合并 - 立即派发 fixup(同分支或新分支) - 在 docs 中记录“未通过项 + 修复输入” --- ## Supported Agents | Agent | Use Case | Command | |-------|----------|---------| | **Codex** | 后端逻辑、复杂 bug、多文件重构 | `codex exec --dangerously-bypass-approvals-and-sandbox -C "/path" "prompt"` | | **Claude Code** | 前端、git 操作、快速任务 | `claude --dangerously-skip-permissions -p "prompt"` | | **Gemini** | UI 设计、生成规范 | `gemini -p "prompt"` 或 `gemini -y -p "prompt"` (YOLO 模式) | | **Cursor** | 前端产品化、IDE 协同、界面 polish;版本前差异分析(plan) | `cursor agent -f -p --workspace "/path" --model composer-1.5 "prompt"` | --- ## Scripts ### spawn-agent.sh 创建新任务并启动代理。 **参数:** - `--agent` (必需): codex | claude | gemini | cursor | auto(推荐) - `--repo` (必需二选一): 仓库名(位于 skill 上级目录时使用) - `--repo-path` (必需二选一,推荐): 仓库绝对/相对路径;用于 skill 根目录外的仓库 - `--branch` (必需): 分支名 - `--description` (必需): 任务描述 - `--prompt` (三选一): 代理提示词(短文本时可用) - `--prompt-file` (三选一,推荐): 从文件读取提示词,避免 shell 转义问题(尤其包含反引号、`$()`、多行内容) - `--prompt-b64` (三选一): Base64 提示词,适合脚本自动化调用 - `--agent-model` (可选): 指定模型(例如 `--agent cursor --agent-model composer-1.5`) - `--cursor-mode` (可选): `dev|plan`(仅 cursor 生效,默认 `dev`) - `plan` 时会自动使用模型 `gpt-5.3-codex` - `--phase` (可选): `build|review|fixup`(默认 `build`);会受 `config/user.json.agentPolicy` 限制 - `--completion-mode` (可选): `pr`(默认) | `session`;本地测试仓库无 PR 时建议用 `session` - `--auto-merge` (可选,`pr` 模式): 当 CI 与 review 满足条件后触发 `gh pr merge --auto` - `--merge-method` (可选,`pr` 模式): `squash|merge|rebase`,默认 `squash` - `--cleanup-after-seconds` (可选): 临时 worktree 清理 TTL;`session` 模式默认 `3600` ### check-agents.sh 监控所有运行中的代理。 **功能:** - 检查 tmux 会话是否存活 - 检查 PR 是否已创建(`completionMode=pr`) - 跟踪 PR 状态机(`waiting_checks` / `checks_failed` / `waiting_review` / `changes_requested` / `merge_ready` / `merge_queued` / `merged`) - 检查 required CI checks(`gh pr checks --required`) - 检查 reviewDecision(`gh pr view --json reviewDecision`) - 可选自动触发 `gh pr merge --auto`(任务级 `autoMerge` 或 `config/user.json.pr.autoMerge`) - 失败自动重试(按配置延迟,最多3次;依赖任务记录中的命令元数据) - 写入通知到 `notifications.json` (由 OpenClaw 发送飞书通知) - 结束后可自动触发 `cleanup-worktrees.sh` 与 `prune-history.sh`(避免 worktree / active-tasks 膨胀) 注意: - `session exit mode` 仅表示会话结束,不代表质量达标。 - 质量达标必须由主 Agent 的 post-task review 判定。 ### review-agent.sh 多 reviewer 代码审查(默认三审:`codex + gemini + claude`)。 **参数:** - `--repo` (必需): 仓库名 - `--branch` (必需): 分支名或 PR 号 - `--reviewers`: 审查者 (默认: codex,gemini,claude;默认要求至少 3 个) - `--allow-fewer-reviewers`: 调试用,允许少于 3 个 reviewer - `--no-post`: 只生成本地审查产物,不回写 PR 评论 **行为(新版):** - 每个 reviewer 生成结构化审查结论(Verdict / Findings / Validation / Next Steps) - 自动抓取 `gh pr diff` 并注入 reviewer prompt(截断版) - 每个 reviewer 单独在 PR 下发表评论(正文带 `[dev-team][reviewer=...]` 标识) - 会按 `config/user.json.agentPolicy` 过滤禁用/阶段不允许的 reviewer - 生成聚合结果 `assets/logs/reviews/review-<pr>-<ts>.aggregate.json` - 聚合策略会结合 reviewer 权重、severity 和 reviewer 角色偏好,输出: - `waiting_human_approve` - `review_changes_requested` - `review_human_attention` - 写回 `assets/active-tasks.json`: - `checks.reviewAggregate` - `checks.reviewSummary` - `checks.fixupSuggested` - `checks.fixupTarget`(用于后续优先回原 subagent 返工) ### aggregate-reviews.sh 聚合多 reviewer 的审查产物,输出单一决策(通过 / 需修改 / 人工关注)。 示例: ```bash ./scripts/aggregate-reviews.sh --file assets/logs/reviews/review-1-1234567890.json ``` ### request-fixup.sh 根据 `review-agent` 聚合结果,为原 PR 负责 subagent 生成返工 prompt,并优先发回原 subagent(如会话仍存活)。 **参数:** - `--branch <branch>` 或 `--pr <number>`:定位任务 - `--dry-run`:只生成返工 prompt,不执行 - `--spawn-if-dead`:原 subagent 会话已退出时,按同 branch 重新派工(谨慎使用) **行为:** - 读取 `checks.reviewAggregate` / `checks.reviewAggregateFile` - 若 `fixupSuggested=true`,生成结构化返工 prompt(按 severity 排序) - 写回 `checks.fixupRequestedAt` / `checks.fixupRequestMode` - 默认优先回原 subagent(同 branch owner)处理 --- ## Agent Adaptation & Policy - 统一 agent 适配与全流程使用建议:`references/agent-adapters.md` - 可配置 agent 启用开关与阶段允许列表:`config/user.json` -> `agentPolicy` - 推荐器支持阶段参数(会过滤禁用 agent): ```bash ./scripts/recommend-agent.sh --description "前端看板优化" --phase build ./scripts/recommend-agent.sh --description "PR 代码审核" --phase review ``` ### cleanup-worktrees.sh 清理已合并的 worktree。 补充说明: - 对 `completionMode=session` 且 `cleanupMode=session_ttl` 的任务,会在 `cleanupEligibleAt` 到期后自动清理 worktree - 清理后任务状态会写回为 `cleaned`(保留历史记录) ### prune-history.sh 归档 `assets/active-tasks.json` 中过旧的已完成任务(`done/failed/cancelled/cleaned/...`),避免注册表无限增长。 常用参数: - `--keep-days <days>`: 仅归档早于 N 天的记录(当前默认配置为 `0`,更偏热数据) - `--keep-count <n>`: 无论时间如何,至少保留最近 N 条非失败/取消终态记录(当前默认配置为 `12`) - `--keep-fail-cancel-days <days>`: `failed/cancelled` 独立归档天数(默认可更激进) - `--keep-fail-cancel-count <n>`: 至少保留最近 N 条 `failed/cancelled` - `--dry-run`: 预览归档数量,不落盘 自动化建议: - `cleanup-worktrees.sh` 执行后自动触发 `prune-history.sh`(可在 `config/user.json.archive` 配置) - 也可单独配置每日归档 cron 说明: - `cleanup-worktrees.sh` 会清理孤儿 worktree(任务已归档但同级目录仍残留) - `session_ttl` 会受全局 TTL 上限约束,避免历史任务长时间占用磁盘 ### setup-check.sh 首次使用检查脚本,验证配置完整性。 ### recommend-agent.sh 根据任务描述/提示词关键词、当前运行负载、CLI 健康状态推荐最合适的 agent(含理由)。 示例: ```bash ./scripts/recommend-agent.sh \ --description "dev-board 前端 UI 产品化改版,优化筛选与日志面板" \ --prompt-file /tmp/task-prompt.txt \ --format json ``` ### list-agent-models.sh 列出 agent 模型(当前主要用于 Cursor)。 示例: ```bash ./scripts/list-agent-models.sh cursor ``` ### enqueue-task.sh / list-queue.sh / claim-task.sh Queue/Claim 模式(推荐演进路径,现已提供最小可用版本): - `enqueue-task.sh`:主 Agent 添加任务到队列(`assets/tasks.json`) - `list-queue.sh`:查看队列(支持状态/阶段过滤) - `claim-task.sh`:认领一个 queued 任务并调用 `spawn-agent.sh` 派工 - `sync-queue-status.sh`:根据 `assets/active-tasks.json` 回写队列任务状态(`running/done/cleaned/...`) - `prune-queue-history.sh`:归档 `assets/tasks.json` 中过旧终态队列任务到 `assets/logs/archives/queue-history-YYYY-MM.jsonl` 示例: ```bash ./scripts/enqueue-task.sh \ --repo-path ./scripts/dev-board \ --branch feat/dev-board-action-history \ --description "dev-board 操作历史列表" \ --phase build \ --completion-mode pr \ --prompt-file /tmp/task.txt ./scripts/list-queue.sh --status queued ./scripts/claim-task.sh --agent auto ``` --- ## Task Registry 位置:`assets/active-tasks.json` 编码约定: - 所有任务与通知 JSON 文件统一使用 UTF-8 保存 - 写入时使用 `ensure_ascii=False`,中文会以可读形式保存(不再显示 `\\uXXXX`) 归档约定: - `assets/active-tasks.json` 保存热数据(运行中 + 近期终态任务) - 历史记录归档到 `assets/logs/archives/task-history-YYYY-MM.jsonl` 任务状态以脚本实现为准,详见 [references/state-machine.md](references/state-machine.md)。 补充字段(新任务会记录): - `requestedAgent`: 用户请求的 agent(可能是 `auto`) - `agentModel`: 实际使用模型(如 `composer-1.5`) - `agentSelectionReason`: 自动派工的简要理由(关键词/健康回退等) --- ## References - **状态机**: [references/state-machine.md](references/state-machine.md) - **CLI / tmux**: [references/cli-reference.md](references/cli-reference.md) - **Prompt 模板**: [references/prompt-templates.md](references/prompt-templates.md)(推荐 Subagent Task Contract) - **完成后验收清单**: [references/post-task-review-checklist.md](references/post-task-review-checklist.md) - **初始化 / Cron**: [references/initialization.md](references/initialization.md) --- ## Troubleshooting ### 1) Claude 子任务启动失败(常见于复杂 prompt) 常见根因: - 在 shell 中直接使用 `--prompt "..."`,内容包含反引号、`$()` 等,导致 shell 提前展开,实际传给脚本的 prompt 被污染。 修复方式(推荐顺序): 1. 使用 `--prompt-file`(首选) 2. 自动化调用使用 `--prompt-b64` 3. 仅短 prompt 使用 `--prompt` ### 2) Cursor agent 无法使用 / 很少被选中 如果 `cursor agent status` 显示 `Not logged in`,`spawn-agent` 会在启动前直接失败并提示: ```bash cursor agent login ``` 你提到常用模型 `composer 1.5`,当前已在 `config/agents.json` 中设为 Cursor 默认模型(`composer-1.5`)。 如需覆盖: ```bash ./scripts/spawn-agent.sh --agent cursor --agent-model composer-1.5 ... ``` Cursor plan 模式(用于版本前差异分析): ```bash ./scripts/spawn-agent.sh \ --agent cursor \ --cursor-mode plan \ --repo-path /path/to/repo \ --branch feat/version-plan \ --description "版本规划与差异分析" \ --completion-mode session \ --prompt-file /tmp/plan.txt ``` 说明: - 该模式等价于 `cursor agent --mode plan`(只读规划,不改代码) - `spawn-agent` 会强制模型为 `gpt-5.3-codex` ### 3) PR / CI / review 流程不推进 必要前置条件: 1. 仓库已配置 GitHub `origin` remote 2. `gh auth status` 有效(token 未过期) 3. subagent 的 prompt 明确要求: - 提交 commit - `git push -u origin <branch>` - `gh pr create ...` 如果缺一项,`check-agents.sh` 无法推进 PR 状态机。 ### tmux ```bash tmux new-session -d -s <name> -c <dir> "command" tmux send-keys -t <session> "text" Enter tmux list-sessions tmux kill-session -t <session> ```
don't have the plugin yet? install it then click "run inline in claude" again.