wangjiamaestro
多项目 TODO 管理与 Agent 执行系统（本地优先 daemon · Node/TypeScript）。
按任务复杂度（Hard / Medium / Easy）分级驱动审批闸，用后台 agent（Claude Code）在隔离 git worktree 自动执行可执行任务，执行后自动跑 code review + 安全审计，accept 时 --no-ff 自动合并，改动不自动 push。
- 完整设计见 DESIGN.md。
- 当前状态：Phase 1 + Phase 2 + Phase 3 核心均已落地（编排器 + score 调度 + 双复审 + 自动合并 + macOS 通知 + 额度透传 + 归档）。
结构
src/
model/ 复杂度、状态机、实体类型、score 调度算法
store/ SQLite schema + 访问层（状态机守卫 + 审批闸）
api/ REST + WebSocket API + logo 解析
mcp/ MCP server（给 Claude Code）
executor/ Agent SDK 封装（cc.ts）、worktree 管理、verify、
runner（executor run）、reviewer（双复审）、merge、模型分级
daemon/ maestrod 入口、编排器、macOS 通知、额度透传、配置
sync/ 旧 todo.json → maestro 单向同步引擎
web/ 看板（多项目·实时 WS·内联审批·归档详情）
scripts/ poc-exec.mjs（执行闭环验证脚本）
开发
npm install
npm run typecheck # tsc --noEmit
npm run build # → dist/
npm run dev # 启动 daemon（默认 http://127.0.0.1:4517）
npm test # 运行全量测试（node --test）
接入 Claude Code（MCP）
先 npm run build，并保证 maestrod 在跑（npm run dev，默认 http://127.0.0.1:4517）。两种接法：
# 方式一：claude mcp add（在要接入的项目里执行）
claude mcp add maestro -e MAESTRO_URL=http://127.0.0.1:4517 -- node /绝对路径/maestro/dist/mcp/index.js
// 方式二：项目根放 .mcp.json（模板见本仓库 .mcp.json.example）
{ "mcpServers": { "maestro": {
"command": "node",
"args": ["/绝对路径/maestro/dist/mcp/index.js"],
"env": { "MAESTRO_URL": "http://127.0.0.1:4517" } } } }
MCP 工具：list_projects / create_project / list_tasks / get_task / create_task / decompose_task / write_plan / write_spec / write_operations / update_status / get_next_executable / get_pending_approvals（accept/reject 在 Web 看板操作）。
核心功能速览
Score 调度
编排器按 score 降序领任务（不抢占，领取时现算）：
score = P(自身优先级) // P0=3 / P1=2 / P2=1
+ Σ P(已完成依赖) // 链条惯性：前置投入越重越优先出活
+ Σ P(等我解锁的 blocked 任务) // 解锁效应：解锁面越广越优先
双复审 PR 流程
执行成功后顺序起两个只读 headless Claude Code：
- Code Review（kind=reviewer）：正确性/可维护性逐条问题 →
VERDICT: approve|reject - 安全审计（kind=security）：凭证泄露/注入/权限/UI红线词/部署风险 →
VERDICT: approve|reject
任一复审失败不挡任务进 exec_review；看板展示两份 markdown 报告 + verdict 徽章。
模型分级
| 角色 | Easy | Medium | Hard |
|---|---|---|---|
| executor | claude-sonnet-4-6 | claude-opus-4-8 | claude-fable-5 |
| reviewer | claude-sonnet-4-6 | claude-opus-4-8 | claude-opus-4-8 |
project.model（看板设置）最高优先；环境变量次之（见下）；内置默认最低。模型不可用时自动回退 opus-4-8 → sonnet-4-6。
归档与运行历史
GET /api/tasks/:id/events— 状态流转时间线GET /api/tasks/:id/runs— executor / reviewer / security run 历史（含转录引用）
macOS 通知
进入审核闸（plan/spec/exec_review）、执行失败、复审建议拒绝、合并完成时推送原生通知。MAESTRO_NOTIFY=0 关闭。
额度透传
GET /api/agents 附带 Claude 订阅额度（5h 窗口 + 7天窗口），读取 ~/.claude/.credentials.json 或 macOS keychain，60s 缓存。
自动合并
exec_review accept 时自动 --no-ff 合并：若 defaultBranch 在主检出且工作区干净 → 直接合并；否则临时 worktree 合并后销毁。冲突时 abort 返回冲突文件列表，任务保留在 exec_review。merge:false 逃生口可仅通过不合并。
环境变量
| 变量 | 说明 | 默认 |
|---|---|---|
MAESTRO_URL |
daemon 地址（MCP 客户端侧） | http://127.0.0.1:4517 |
MAESTRO_PORT |
daemon 监听端口 | 4517 |
MAESTRO_DATA_DIR |
SQLite + worktree 数据目录 | ~/.maestro |
MAESTRO_ORCH_INTERVAL |
编排器轮询间隔（秒），0=关闭 |
15 |
MAESTRO_NOTIFY |
0 关闭 macOS 通知 |
开启 |
MAESTRO_MODEL_EASY |
executor Easy 模型覆盖 | claude-sonnet-4-6 |
MAESTRO_MODEL_MEDIUM |
executor Medium 模型覆盖 | claude-opus-4-8 |
MAESTRO_MODEL_HARD |
executor Hard 模型覆盖 | claude-fable-5 |
MAESTRO_MODEL_REVIEW_EASY |
reviewer Easy 模型覆盖 | claude-sonnet-4-6 |
MAESTRO_MODEL_REVIEW_MEDIUM |
reviewer Medium 模型覆盖 | claude-opus-4-8 |
MAESTRO_MODEL_REVIEW_HARD |
reviewer Hard 模型覆盖 | claude-opus-4-8 |