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

首次使用

# 執行設定檢查
scripts/setup-check.sh

啟動內建 dev-board 控制面板

dev-team 已內建 scripts/dev-board/，可直接啟動：

./scripts/run-dev-board.sh

預設地址：http://localhost:4310

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

Check Agent Status

cat assets/active-tasks.json

Monitor Agents

scripts/check-agents.sh

Mandatory: Post-task Review Gate (合併前必做)

當 SubAgent 報告完成（例如 TASK_*_DONE）後，主 Agent 必須執行：

# 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

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

  7w4.net小蔥技能站，你的AI助手技能庫。

• --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 的審查產物，輸出單一決策（通過 / 需修改 / 人工關注）。

示例：

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

./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（含理由）。

示例：

./scripts/recommend-agent.sh \
  --description "dev-board 前端 UI 產品化改版，最佳化篩選與日誌面板" \
  --prompt-file /tmp/task-prompt.txt \
  --format json

list-agent-models.sh

列出 agent 模型（當前主要用於 Cursor）。

示例：

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

示例：

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

補充欄位（新任務會記錄）：

• requestedAgent: 使用者請求的 agent（可能是 auto）
• agentModel: 實際使用模型（如 composer-1.5）
• agentSelectionReason: 自動派工的簡要理由（關鍵詞/健康回退等）

References

• 狀態機: references/state-machine.md
• CLI / tmux: references/cli-reference.md
• Prompt 模板: references/prompt-templates.md（推薦 Subagent Task Contract）
• 完成後驗收清單: references/post-task-review-checklist.md
• 初始化 / Cron: 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 會在啟動前直接失敗並提示：

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

說明：

• 該模式等價於 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

tmux new-session -d -s <name> -c <dir> "command"
tmux send-keys -t <session> "text" Enter
tmux list-sessions
tmux kill-session -t <session>

這個 Skill 質量不錯，是一個功能完整的 AI 開發團隊自動化工具。它能自動派發任務、監控進度、審查程式碼、處理修復，配套的視覺化面板讓狀態一目瞭然。最關鍵的是它有嚴格的質量門禁，不會讓不達標的程式碼輕易通過。不過它依賴多個外部 AI 工具（codex、gemini 等），配置起來有點門檻，部分功能可能因為工具版本不同而出現相容問題。對普通使用者來說，需要一定的技術基礎才能用好。總體適合有一定開發經驗、想用 AI 協作提升效率的團隊。