wangjia
3172718a94
- src/model: 复杂度分级、16 状态状态机、实体类型 - src/store: better-sqlite3 接 schema，transition 受 canTransition 守卫， decide 审批闸(reject 必带改进意见)，事件订阅广播，nextExecutable - src/api: Fastify REST + ws 事件广播(/ws) - src/daemon: maestrod 入口(env 配置，默认 ~/.maestro :4517) - test: 9 个生命周期单测全过；typecheck/build 干净；REST+WS 端到端实跑验证 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
101 lines
7.5 KiB
Markdown
101 lines
7.5 KiB
Markdown
# 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。
|