maestro/README.md

maestro

多项目 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：

1. Code Review（kind=reviewer）：正确性/可维护性逐条问题 → VERDICT: approve|reject
2. 安全审计（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
MAESTRO_SANDBOX	worker OS 级沙箱总开关（on/off）	关闭
MAESTRO_SANDBOX_PROFILE	是否套 sandbox-exec（仅 macOS；off 则仅留 ulimit）	开启
MAESTRO_SANDBOX_NET	是否放行网络（SDK 需连 Anthropic；off 隔离）	放行
MAESTRO_SANDBOX_CPU	CPU 时间上限（秒），0=不限	0
MAESTRO_SANDBOX_MEM	虚拟内存上限（MB），0=不限（macOS 对 -v 支持不稳定）	0
MAESTRO_SANDBOX_NOFILE	打开文件描述符上限	4096
MAESTRO_SANDBOX_FSIZE	单文件大小上限（MB），0=不限	0
MAESTRO_SANDBOX_WRITE_EXTRA	额外放行写的绝对路径（冒号分隔）	空

worker 沙箱（OS 级硬隔离，可选）

进程隔离（独立 worker 进程 + env 收敛，密钥/DB/API 与 daemon 隔开）之上，再加一层 OS 级硬隔离，默认关闭，开启后对每个 worker 生效：

• 文件写围栏（macOS sandbox-exec）：基线 allow default（放行读 / exec / 网络 / mach——keychain 鉴权所需），仅对写收口，逐条放行 worker 必需的写目标：任务 worktree、主仓 .git/node_modules、runs/<runId>、transcripts、$TMPDIR 与常用工具缓存（~/.npm、~/Library/Caches、GOCACHE 等）。越界写（改系统、污染其它仓库、动 maestro 自身 DB）被内核拒绝。为什么不 deny default 全围栏：合法的 git/npm/go/node 需读海量系统/缓存路径，全围栏极易误伤——真正的破坏向量是「写」。
• 资源上限（ulimit）：CPU 时间 / 虚拟内存 / 打开文件数 / 单文件大小，防失控 agent 拖垮机器；超限由内核杀进程，daemon 的 reaper 据此回收并重试/转 needs_attention。
• 生效的策略会在 daemon 启动日志打一行；每个 run 的实际 profile 落在 runs/<runId>/sandbox.sb（清晰记录）。

先在一个项目灰度：开 MAESTRO_SANDBOX=on 后跑一轮含 npm/go/git 的真实任务，确认能跑通、越界写被拒、超限被杀且日志清晰，再逐步铺开。个别项目若有特殊写路径，用 MAESTRO_SANDBOX_WRITE_EXTRA 放行。