maestro/DESIGN.md

Maestro — 多项目 TODO 管理与 Agent 执行系统 · 设计方案 v0.1

本地优先的 daemon：管理多个本地 git 项目的任务，按复杂度分级驱动审批闸，并用后台 agent（Claude Code）自动执行可执行任务。

Context（为什么做）

前身是 ~/.claude/skills/todo（JSON + HTML 单机原型）：单项目、无真正后端、确认靠临时 http hack、无自动执行。它验证了「复杂度分级 + 确认闸 + 看板」的形态，但不可扩展。Maestro 把它升级为正式系统：多项目、任务层级化、复杂度驱动的审批闸、完整状态机、本地常驻 daemon、每项目一个后台执行 agent、与 Claude Code 深度集成（MCP + Agent SDK）。

0. 关键决策

维度	决策
运行时	Node / TypeScript
部署	本地优先 daemon（跑在用户机器，管理本地 git 项目）
Claude Code 集成	MCP 服务（任务读写）+ Claude Agent SDK（headless 自动执行）
Easy 自动化边界	改动隔离到 git worktree/分支，不自动合并

1. 系统总览

maestrod（核心 daemon，常驻）
 ├─ 任务存储 SQLite          ├─ 项目注册表
 ├─ REST + WebSocket API     ├─ MCP server（给任意 Claude Code 会话）
 ├─ 编排器 Orchestrator      └─ 每项目 worker 池（执行器）
        │                          │
   Web 看板（多项目·实时·页面内 accept/reject）   执行 agent：Agent SDK 在 worktree 跑 headless Claude Code

闭环：建任务 →（Hard 分析拆解 / Medium 写方案 / Easy 写操作）→ 前置审批闸 → ready → 编排器领取 → worktree 起 headless CC 执行 → verify → 结果闸（审/合）→ done。

2. 复杂度分级

Hard / Medium / Easy ↔ 旧 tier 1/2/3。每个任务（含子任务）都带 complexity，决定它走哪条「产出 + 审批」路径。（见 src/model/complexity.ts）

3. 任务层级

parent_id + depth；默认 ≤3 层，极复杂 ≤4 层（创建第 5 层时拒绝）。子任务各自带 complexity。叶子任务才可执行；被拆解的 Hard 是容器，进度由子任务汇总。

4. 三条产出路径与审批闸

复杂度	产出（执行前）	前置闸	reject 规则
Hard	强制进 plan 分析 → 产出「分析 + 任务拆解（子任务，各带复杂度）」	plan_review，accept 才进下一步	必须带改进意见 → 退回重做并附 feedback
Medium	写「具体方案 = 改动内容 + 为什么这么做」	spec_review，accept/reject	同上（必带意见）
Easy	写清「将执行的操作」记录在任务上	无前置闸，直接可执行	—

结果闸 exec_review（所有产生改动的执行后、合并前）：改动在隔离分支，用户审/合；reject 必带意见 → 返工。承载「不自动合并」边界。

5. 状态机（见 src/model/status.ts）

init · analyzing · plan_review · decomposed · speccing · spec_review · ready · blocked · queued · executing · exec_review · failed · needs_attention · done · paused · cancelled

主要流转：

• init →（Hard）analyzing → plan_review —accept→ decomposed —子全 done→ done；—reject(+意见)→ analyzing
• init →（Medium）speccing → spec_review —accept→ ready；—reject(+意见)→ speccing
• init →（Easy，写完操作）→ ready
• ready —deps 满足→ queued → executing → exec_review —accept(合并)→ done；—reject(+意见)→ 返工
• executing → failed —自动重试 n 次→ executing / needs_attention

合法流转表与守卫在 TRANSITIONS / canTransition()。

6. 数据模型（见 src/model/types.ts 与 src/store/schema.sql）

• Project：repo_path、default_branch、verify_cmd、autonomy、model、concurrency、status
• Task：project_id、parent_id、depth、complexity、status、deps[]、plan/spec/operations、result、assignee
• ApprovalRecord：gate(plan/spec/exec)、action、actor、reason(reject 必填)、at
• Run：kind(planner/executor)、worktree、branch、status、transcript_ref、claude_session_id
• Event（append-only）：审计 + 实时看板推送源

7. 编排器与执行 agent

• daemon 内编排循环 + 每项目 worker 池（并发可配，默认 1–2）。
• 选「可执行任务」（叶子、ready、deps 满足）：Easy 自动入队；Medium/Hard 子任务在 spec accept 后入队。
• 执行 = Claude Agent SDK 起 headless Claude Code：cwd=worktree，附 MCP、权限模式（worktree 内 acceptEdits）、任务 spec/operations 作指令、项目 CLAUDE.md 作上下文。
• 完成 → 跑 verify_cmd → exec_review（带分支 + diff 摘要）；失败 → failed → 重试 n 次 → needs_attention。
• Hard 拆解 / Medium 方案也可由 Agent SDK 起 planner run 自动产出 → 进前置闸：「自动产出，人工把关」。

8. Claude Code 集成

• MCP server（交互面）：项目里的 Claude Code 配 .mcp.json 接 maestro-mcp。工具：list/get tasks、create、decompose、write_spec、write_operations、update_status、attach_result、request_approval、get_next_executable、get_pending_approvals。
• Agent SDK（自动面）：编排器用 Claude Agent SDK 起 headless CC 跑可执行任务。
• approve/reject 是用户动作，走看板按钮。

• 以官方 Claude Agent SDK / MCP 当前能力为准，落地前用 PoC 校准具体 API 与包版本。

9. 后端架构与项目绑定

• 存储 SQLite（better-sqlite3，单文件零运维）；run 转录日志存文件，Run 表引用。
• API：REST（CRUD）+ WebSocket/SSE（实时看板）。
• 项目绑定：maestro project add <repo> 记录 repo 路径/默认分支/verify/autonomy/model/并发；repo 内 .maestro/config.json + daemon 中央 DB 行。
• worktree：执行在 repo 的 git worktree（隔离分支），不自动合并。

10. Web 看板

多项目切换 / 全局总览；任务树（层级折叠）、复杂度徽章、状态、内联审批闸（accept/reject，reject 必填意见）、实时执行状态、exec_review 的 diff/分支链接。实时 WS。

11. 从现有 skill 迁移

旧 todo.mjs/JSON 作为 v0 原型被取代。importer：读旧 todo/todo.json，tier1/2/3 → hard/medium/easy，导入为一个项目。/todo 改用 MCP + 看板。

12. 分期实施

• Phase 1 核心（可控、无自动执行）：daemon + SQLite + 项目注册 + 任务模型 + 状态机 + 看板 + MCP（读写 + 审批）。手动驱动。
• Phase 2 自动化：编排器 + Agent SDK 执行器（Easy 自动跑 worktree，结果闸）+ planner runs。
• Phase 3 打磨：并发/重试/通知/指标/可选远程看板。

13. 风险与未知

• Agent SDK headless 执行 + MCP 回写的可靠性（PoC 先验证）。
• 自动执行安全：worktree 隔离 + 不自动合并 + verify 把关 + needs_attention 人工兜底。
• 长任务上下文超限、并发资源、worktree 清理。
• Hard 自动拆解质量需人工把关（reject 带意见返工）。

14. 验证 / PoC

1. 最小执行闭环：注册项目 → 建 Easy 任务 → 编排器在 worktree 起 headless CC 改一个文件 → verify → 看板出现 exec_review → accept 合并。
2. MCP 往返：交互 CC 会话里 list/create/update 跑通。
3. 审批闸：Hard 自动拆解 → plan_review → 看板 reject(带意见) → 退回 analyzing → 重拆 → accept。