Dev Team

开发团队（Dev Team）

使用 Levi 作为编排器（orchestrator）实现单人开发团队的自动化协同。

主 Agent 规则（入口摘要）

主 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）

首次使用

# 运行环境与配置检查
scripts/setup-check.sh

启动内置 dev-board 控制面板

dev-team 已内置 scripts/dev-board/，可直接启动：

./scripts/run-dev-board.sh

默认访问地址：http://localhost:4310

启动一个 Agent（Spawn an Agent）

正式功能开发（推荐 PR 流程）：

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 模式）：

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

查看 Agent 当前状态

cat assets/active-tasks.json

监控所有 Agent 运行状态

scripts/check-agents.sh

强制要求：合并前必须执行 Post-task Review（后置审查门禁）

当 SubAgent 报告完成（例如触发 TASK_*_DONE 事件）后，主 Agent 必须执行以下三步审查：

# 1) 查看任务整体状态与日志摘要
scripts/check-agents.sh

# 2) 审核 subagent 提交内容（示例）
git -Cshow --name-only --oneline -n 1# 3) 在目标仓库中执行 DoD 所定义的真实验证命令（示例）
# 如：真实 ingestion/validate、真实 API 调用、非 mock 链路

✅ 通过标准：

• 所有 DoD 条款均已满足
• 至少 1 条真实链路验证通过（禁止使用 mock）
• 关键指标达到任务预设阈值（如 successRate / evidenceBindingRate / citationNonEmptyRate / fallbackRate）

❌ 未通过处理：

• 禁止合并
• 立即派发 fixup 任务（同分支或新建分支）
• 在 docs/ 中记录“未通过项 + 对应修复输入”

脚本说明（Scripts）

spawn-agent.sh

创建新任务并启动对应 SubAgent。

必需参数：

• --agent：codex | claude | gemini | cursor | auto（推荐）

• --repo 或 --repo-path（二选一）：

  • --repo：仓库名（适用于 skill 上级目录结构）
  • --repo-path：仓库绝对/相对路径（推荐；支持 skill 根目录外的任意仓库）
• --branch：目标分支名（必需）
• --description：任务描述（必需）

提示词输入（三选一，推荐 --prompt-file）：

• --prompt：短文本提示词（适合简单指令）
• --prompt-file：从文件读取提示词（推荐，规避 shell 转义问题，尤其含反引号、$()、多行内容）
• --prompt-b64：Base64 编码提示词（适合 CI/CD 等脚本化调用）

可选参数：

• --agent-model：指定模型（例如 --agent cursor --agent-model composer-1.5）

• --cursor-mode：dev（默认）| plan（仅对 cursor 生效）

  • plan 模式将自动使用模型 gpt-5.3-codex，用于只读规划分析
• --phase：build（默认）| review | fixup；受 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
• --cleanup-after-seconds：临时 worktree 清理 TTL；session 模式默认 3600

check-agents.sh

持续监控所有运行中的 SubAgent 及其关联 PR 状态。

核心能力：

• 检查 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）
• 获取 review 决策状态（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 编号（如 #123）

可选参数：

• --reviewers：指定 reviewer 列表（默认 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--.aggregate.json

• 聚合策略综合 reviewer 权重、issue severity 和角色偏好，输出决策信号：

  • 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 的审查输出，生成统一决策（通过 / 需修改 / 人工关注）。

示例：

./scripts/aggregate-reviews.sh --file assets/logs/reviews/review-1-1234567890.json

request-fixup.sh

根据 review-agent 的聚合结果，为原 PR 对应的 subagent 生成结构化返工提示，并优先发送回原 subagent（若其会话仍活跃）。

参数：

• --branch 或 --pr：定位任务上下文
• --dry-run：仅生成返工 prompt，不实际执行
• --spawn-if-dead：若原 subagent 已退出，则按同 branch 重新派工（谨慎启用）

行为逻辑：

• 读取 checks.reviewAggregate 或 checks.reviewAggregateFile
• 若 fixupSuggested=true，按 severity 排序生成结构化返工 prompt
• 写回 checks.fixupRequestedAt / checks.fixupRequestMode
• 默认优先路由至原 subagent（同 branch owner）处理

任务注册中心（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：自动派工简要理由（关键词匹配 / 健康回退等）

故障排查（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 将在启动前直接失败并提示：

cursor agent login

你常用模型 composer 1.5，已在 config/agents.json 中设为 Cursor 默认模型（composer-1.5）。  
如需显式覆盖：

./scripts/spawn-agent.sh --agent cursor --agent-model composer-1.5 ...

Cursor plan 模式（用于版本前差异分析）：

./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