diff --git a/CLAUDE.md b/CLAUDE.md index eb957a8..b962e0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,14 +77,20 @@ score = P(self) + Σ P(completed deps) + Σ P(tasks blocked by self) ### Model Tier Assignment -| Role | Easy | Medium | Hard | -|---|---|---|---| -| executor | claude-sonnet-4-6 | claude-opus-4-8 | claude-opus-4-8 | -| planner | claude-sonnet-4-6 | claude-opus-4-8 | claude-fable-5 | -| reviewer | claude-fable-5 | claude-fable-5 | claude-fable-5 | -| conflict | claude-fable-5 | claude-fable-5 | claude-fable-5 | +Built-in default for **every role × every complexity** is `claude-opus-4-8` (`DEFAULT_MODEL` in `src/executor/models.ts`). Models are **configurable per project** via `projects.models` (JSON). -Reviewer/conflict use the strongest tier (fable-5) and are NOT downgraded by project-level `model` (preserves self-review/conflict-resolution rigor). Project-level `model` overrides executor/planner env vars; env vars override built-in defaults. Model fallback chain on unavailability: `fable-5 → opus-4-8 → sonnet-4-6`. +**Resolution order** (`resolveModel`, highest → lowest): +1. **`project.models[role]`** — per-project per-scenario config. Value is either a model id string (applies to all complexities) or `{easy,medium,hard}` (per-complexity). Applies to **all** roles incl. reviewer/conflict. +2. **legacy `project.model`** — single override, **executor/planner only** (NOT reviewer/conflict, preserving self-review/conflict-resolution independence). +3. **env vars** — `MAESTRO_MODEL_{EASY,MEDIUM,HARD}` (executor), `MAESTRO_MODEL_REVIEW_*` (reviewer), `MAESTRO_MODEL_PLAN_*` (planner). +4. **`DEFAULT_MODEL`** = `claude-opus-4-8`. + +Example `projects.models`: +```json +{"executor":{"easy":"claude-sonnet-4-6","hard":"claude-opus-4-8"},"reviewer":"claude-fable-5"} +``` + +Model fallback chain on unavailability: `opus-4-8 → sonnet-4-6 → fable-5` (`MODEL_FALLBACK_CHAIN`). Note: `claude-fable-5` is no longer a built-in default (it is unavailable in some environments); configure it explicitly per project if desired. ### Data Directory diff --git a/docs/index.html b/docs/index.html index 5c162e7..47fc465 100644 --- a/docs/index.html +++ b/docs/index.html @@ -52,13 +52,19 @@ body{font-family:'IBM Plex Mono',monospace;background:var(--bg);color:var(--text
-
设计 设计方案 / 架构设计 · 1
+
设计 设计方案 / 架构设计 · 2
MAESTRO · 架构设计
docs/architecture.html
系统整体架构设计：进程模型（daemon 唯一 DB 写者 / worker 文件协议）、前后端、数据流、调度与执行管道总览。
架构HTML
 + +
三类任务执行方法优化方案 · 含实现状态
+
docs/optimization-plan.html
+
三类后台 agent（① 拆解 / ② 执行+双复审 / ③ 解冲突）的六维优化定稿 + 通用规则 + 状态机/ER 图 + Agent 记忆注入 L1–L4。顶部 ★ 实现状态表给出每个优化点 → 提交对照（2026-06-25 全部上线，含 3 个线上实测 bug 修复）。含模型按项目可配置（默认 opus-4.8）与 diff 声明外文件硬闸。
+
优化方案HTML
+
diff --git a/docs/optimization-plan.html b/docs/optimization-plan.html new file mode 100644 index 0000000..4bb1134 --- /dev/null +++ b/docs/optimization-plan.html @@ -0,0 +1,967 @@ + + + + + +Maestro 三类任务执行方法优化方案 + + + + + +
+

Maestro · 三类任务执行方法优化方案

+

2026-06-14 定稿 · 2026-06-25 全部实现并上线 · 含实现状态

+
+ + + +
+ + +
+

★ 实现状态 ✅ 全部上线

+

本方案各项已于 2026-06-25 实现、补测试并经 launchd daemon 端到端实跑验证；下表为「优化点 → 实现 → 提交」对照。线上实测捕获并修复了 3 个单测未覆盖的 bug（DB 迁移漏列 / fable-5 不可用未触发回退 / autoApproveExec 传错 id）。

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
优化点实现要点状态提交
Agent 记忆注入 L1–L4L1 上次失败原因（重试任务）· L2 项目级 agent 规范（DB 列）· L3 拆解背景（父意图+兄弟状态）· L4 全局规范文件，注入 4 处 prompt 头部✅ecea1ae fe7923a 74be3ec
① plan 自动放行autoApprovePlan：全 easy 子任务 + ≤5 个时跳过 plan_review（项目级开关，默认关）✅73f80d2
② approve 前硬闸分项 lint/typecheck/build 闸 + diff 体量闸 + 复审并行（Promise.all）✅2d12769
② exec 自动放行autoApproveExec：双复审 approve 后跳过 exec_review 自动 --no-ff 合并；抽出共享合并流程 exec-merge.ts✅1f318c2 4c09186
模型可配置（项目维度）projects.models（JSON，按角色×复杂度覆盖）；默认统一 opus-4.8；优先级 models > 旧 project.model（仅 exec/planner）> env > 默认；回退链 opus→sonnet→fable✅ff2d7c2 59ce391
② diff 声明外文件闸tasks.scope_files（glob/路径）；scopeFileGate 改动越界=硬闸；planner 拆解出 files 自动填充；executor prompt 注入范围约束✅59ce391
线上实测 bug 修复ensureColumn 漏迁移补列 · isModelError 识别「issue with the selected model」触发回退 · autoApproveExec 传错 id✅1bf3fec a9c5102 4c09186
+

注：③ 解冲突专用 conflict run / 模型固定档 等部分按方案落地，conflict 模型同样走「项目可配置 + 默认 opus-4.8」。fable-5 在本机不可用，已从内置默认移除，仅在项目级显式配置时使用。

+
+ + +
+

① 任务拆解类 (planner) ✅ 定稿

+

Hard 任务拆解(decompose) · Medium 写方案(spec) · 只读主仓、不建 worktree

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
维度现状优化决策变更
触发 / 执行期锁Hard→analyzing / Medium→speccing；无写保护 + 执行期锁（通用规则）：任务有在途 run 即锁只读；禁改 title/spec/complexity/deps，禁再调度；run 结束解锁。
+ 覆盖 AUTO 占位回填竞态；store mutation 入口 + API 层加"在途即拒"校验。 + 		新增
调度并发与 executor 共用 concurrency 池维持共用池，不改并发模型不变
执行流程纯只读 Read/Glob/Grep；maxTurns=60 固定 + ① 加 Bash(git log/*) Bash(git diff/*) Bash(git show/*)（读历史/演化）
+ ② decompose prompt 注入 tasks.depth + 剩余可拆层数（≤3层），防无限拆 hard
+ ③ maxTurns 按复杂度：hard=90 / medium=60 / easy=40 + 		改进
模型 / 档位一律 claude-opus-4-8 + 按复杂度分档：hard fable-5 + medium opus-4-8 + easy sonnet-4-6
+ env MAESTRO_MODEL_PLAN_EASY/MEDIUM/HARD 三档可独立覆盖 + 		改进
输出格式spec=3段md；decompose=分析+fenced JSON
{plan, subtasks:[{title,complexity}]}		 + decompose 扩展为：
+  ① 正文先输出子任务 Markdown 表格（标题/复杂度/优先级/依赖序号）供人审
+  ② 末尾 JSON 扩展：{plan, subtasks:[{title,complexity,priority,deps:[序号]}]}
+  ③ 解析向后兼容（缺 deps/priority 给默认值）；deps 序号→taskId 二次映射后写 tasks.deps
+ spec 增加验收标准必填 + 可选影响文件清单 + 		扩展
是否审批decompose→plan_review；spec→spec_review；均强制人审 + 默认仍人审；可选自动放行（默认关）：
+ auto-approved + 拆解全 easy + 子任务数≤N → 跳过 plan_review 直接 ready
+ 项目级开关 autoApprovePlan 控制；高风险，默认关 + 		新增选项
+ +

实现涉及文件

+
+
+
models.ts
+
planner 档位表三档分化：sonnet/opus/fable（当前三档同值 opus）
+
+
+
runner.ts · runPlanner
+
allowedTools 加3条 git 只读；maxTurns 改按复杂度取值
+
+
+
runner.ts · buildPlannerPrompt
+
decompose 分支：注入 depth/剩余层数；改要求表格+扩展 JSON
+
+
+
pipeline.ts · parseDecompose
+
解析扩展 JSON 字段 priority/deps，兼容旧格式
+
+
+
ingest.ts · decompose-result
+
priority 落 createTask；deps 序号→taskId 二次映射后 setDeps；判定 autoApprovePlan
+
+
+
store.ts + api/server.ts
+
执行期锁：所有 mutation 入口加"在途即拒"校验
+
+
+
+ +
+ + +
+

② 执行类 (executor + verify + 双复审) ✅ 定稿

+

执行 → verify → 双复审（code+security）→ exec_review 人审 → 合并

+ +

当前 approve 前的检查链

+
+ + + + + + + + + + + + + + + +
#检查当前性质优化后
1executor 完成 + commit 含 task ID硬闸不变
2verify（project.verifyCmd，10min，未配=通过）硬闸（可选）不变
3 新执行前 sync main + 分歧度量无新增：merge main 进 worktree；冲突/改动面过大→重评估/needs_attention
4 新分项 lint/typecheck/build 闸无project 可配 checks；分项报告；任一非0=硬失败
5 新diff 越界/体量闸无改了声明外文件 / diff 行数超阈值 → 拦截或告警
6code review（maxTurns40，15min）仅建议reject → 硬闸：退回重执行（带复审意见）而非进 exec_review
7security review（与 code 串行）仅建议reject → 硬闸；改并行跑（Promise.all，总耗≤15min）
→exec_review 人审强制补完硬闸后：auto-approved+全绿+双approve → 自动合并（默认关）
mergegit merge --no-ff（approve后）硬闸不变（冲突→③解冲突）
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
维度现状优化决策变更
触发ready/queued → claimOne runKind=executor同上 + 执行前 sync main（通用规则13）改进
调度并发共用 concurrency 池；复审在 worker 内串行，不占名额维持不变不变
执行流程建 worktree → executing → verifying → diff → reviewing(串行) → exec_review + ① 新增 sync main 步骤（verify 前）
+ ② 新增 分项检查 + diff 越界闸（verify 后）
+ ③ code+security 双复审改 Promise.all 并行
+ ④ reject 变硬闸（不进 exec_review，退回/needs_attention） + 		改进
模型 / 档位reviewer easy=sonnet/medium=opus/hard=opus；code+security 共用档；project.model 覆盖全角色 + 复审统一 fable-5（三档全升）
+ 复审不被 project.model 降档（保自审独立性） + 		升档
输出格式verdict 二元 approve/reject；均为建议verdict 仍二元；但 reject 变硬闸（ingest 分流，不再无条件进 exec_review）硬化
是否审批双复审后一律 exec_review 强制人审 + 分阶段：先补完三项硬闸，再开自动合并
+ 条件：auto-approved + verify全过 + 分项检查全过 + diff合规 + 双approve → 跳过 exec_review 自动合并（默认关） + 		新增选项
+ +

实现涉及文件

+
+
+
pipeline.ts
+
双复审改 Promise.all；新增 sync main 步骤；加 diff 越界判定
+
+
+
models.ts · reviewer 档
+
三档全改 fable-5；pickModel 对 reviewer 角色跳过 project.model
+
+
+
ingest.ts · result 分支
+
按 code/security verdict 分流：reject→退回重执行；双approve+开关→自动合并
+
+
+
verify.ts / pipeline
+
分项 lint/typecheck/build 闸（新 project.checks 配置）
+
+
+
worktree.ts / pipeline
+
执行前 git merge main 进 worktree；分歧度量超阈值→重评估信号
+
+
+
protocol.ts
+
新增 phase=sync-main，emit 新信号类型（重评估/diff越界）
+
+
+
+ +
+ + +
+

③ 解冲突类 (conflict agent) 🆕 新实现

+

当前仅检测冲突+abort，无专用 agent；本轮新建完整解冲突流程

+ +

现状硬伤

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
维度现状优化决策变更
触发 / 调度合并冲突→建 P0 easy 补救任务；按 score 排队等领取 + 触发不变（自动建补救任务，幂等）
+ 调度改为优先抢占：conflict run 插队，先于普通 executor 领取 + 		改进
执行流程复用 executor pipeline；CC 靠 Read/Edit 猜着解冲突；无专用模板 + 专用 conflict pipeline：
+ 1. worker 在补救 worktree 内真正发起 git merge <branch> 制造冲突态
+ 2. CC 以只读+Edit 逐个解冲突文件（白名单加 Bash(git merge:*)）
+ 3. CC commit 沿用合并 commit message
+ 4. 走双复审（同②）
+ 5. exec_review 通过后自动收口原任务 + 		新建
模型 / 档位easy → sonnet（最弱）固定 fable-5（不随原任务复杂度，恒最强）大幅升档
输出格式无专用；executor 自述 + 专用解冲突自述模板：
+ 解了哪些文件 / 各文件取舍策略 / 保留了双方哪些意图 / 测试结果 + 		新增
是否审批走 exec_review + 合并成功自动收口原任务保持；可选纳入②的自动放行条件不变
+ +

实现涉及文件

+
+
+
protocol.ts
+
runKind 加 'conflict'；新增 conflict-related OutboxPayload 类型
+
+
+
pipeline.ts
+
新增 runConflictPipeline 分支：git merge 触发冲突态 → CC 解 → commit → 双复审
+
+
+
runner.ts · buildConflictPrompt
+
专用解冲突 prompt 模板（冲突文件列表/取舍原则/禁丢任一方改动/commit规范）
+
+
+
models.ts
+
ModelRole 加 'conflict'；pickModel for conflict 直返 fable-5
+
+
+
orchestrator.ts
+
conflict 补救任务优先抢占（claimOne 按 runKind=conflict 优先）
+
+
+
store.ts · ensureMergeRemediationTask
+
complexity 不再固定 easy；operations 改用 conflict runKind 标记，修正 worktree 文案
+
+
+
+ +
+ + +
+

④ 任务通用规则（13条，全部采纳）

+

跨三类的横切规则；蓝色=本轮新引入；灰色=已有不变量明文固化

+ + +
+ +
+ + +
+

⑤ 任务状态机流转图

+

据 src/model/status.ts TRANSITIONS 真实表绘制；paused/cancelled 通用终态图中略去

+ +

主干流转（按复杂度）

+ +
+

Hard 任务

+
+ init→ + analyzing→(拆解完成) + plan_review ⊙→(accept) + decomposed→(子全done) + done +
+
+ reject(+意见)↙ + analyzing +
+
+ +
+

Medium 任务

+
+ init→ + speccing→(方案完成) + spec_review ⊙→(accept) + ready +
+
+ +
+

Easy 任务

+
+ init→ + ready +
+
+ +

执行主链（所有复杂度共用，从 ready 开始）

+
+ ready→(调度) + queued→(worker起跑) + executing + →(完成) + exec_review ⊙ + →(accept+合并) + done +
+
+ reject(+意见)↓ + ready + （带复审意见重做） +
+ +

失败 / 重评估链

+
+ executing→ + failed + →(退避重试) + queued +
+
+ failed→(超限) + needs_attention + →(人工requeue) + ready / queued / analyzing / speccing +
+ +

合并冲突链（③）

+
+ exec_review + →(approve but 冲突) + conflict run 抢占 + →(解决+复审) + exec_review + →(approve) + done + →自动收口原任务 +
+ +

完整 Mermaid 图

+
+
+stateDiagram-v2 + direction LR + [*] --> init + init --> analyzing : hard + init --> speccing : medium + init --> ready : easy + + analyzing --> plan_review : 拆解完成 + analyzing --> needs_attention : 失败超限 + plan_review --> decomposed : accept + plan_review --> analyzing : reject+意见 + decomposed --> done : 子任务全done + decomposed --> analyzing : 重拆 + + speccing --> spec_review : 方案完成 + speccing --> needs_attention : 失败超限 + spec_review --> ready : accept + spec_review --> speccing : reject+意见 + + ready --> blocked : 依赖未满足 + blocked --> ready : 依赖满足 + ready --> queued : 编排器领取 + queued --> executing : worker启动 + queued --> ready : 退回 + + executing --> exec_review : 执行完成 + executing --> failed : 执行失败 + failed --> queued : 退避重试 + failed --> needs_attention : 超重试上限 + + exec_review --> done : accept合并 + exec_review --> ready : reject返工 + + needs_attention --> ready + needs_attention --> queued + needs_attention --> analyzing + needs_attention --> speccing + + done --> [*] +
+
+ +
+ ⊙ = 人审闸（plan_review / spec_review / exec_review） ·  + paused ↔ 所有活跃态互通（图中略） ·  + cancelled = 所有活跃态均可取消（图中略） +
+
+ +
+ + +
+

⑥ 数据库结构（单一 SQLite · ~/.maestro/）

+

WAL 模式，外键开。三类任务是 tasks 表上按 complexity+status+run.kind 区分的行为，不是独立表。schema 见 src/store/schema.sql

+ +
+
+
+ projects + 项目配置 +
+
+
idTEXT PK唯一标识
+
autonomyTEXTmanual | auto-easy | auto-approved
+
concurrencyINTEGER并发 run 上限（默认1）
+
max_retriesINTEGER失败最大重试次数（默认2）
+
timeout_msINTEGER单次执行超时毫秒（默认30min）
+
verify_cmdTEXT?验证命令（未配=视为通过）
+
modelTEXT?项目级模型覆盖（最优先）
+
checksTEXT?🆕 分项检查配置 JSON（lint/typecheck/build）
+
auto_approve_planINTEGER🆕 全easy子任务自动放行（0=关）
+
auto_approve_execINTEGER🆕 双approve自动合并（0=关）
+
+
+ +
+
+ tasks + 任务主表（三类共用） +
+
+
idTEXT PK
+
parent_idTEXT?Hard 拆解的父任务
+
depthINTEGER1..4；cat1 直接读此值注入 decompose prompt
+
complexityTEXThard | medium | easy（决定 run 类型和模型档）
+
statusTEXT见状态机（16种）
+
priorityINTEGERP0=最高 / P1=中 / P2=最低；cat1 planner 可直接输出
+
depsTEXTJSON ids；cat1 planner 可直接产出，序号→id 二次映射后写入
+
planTEXT?Hard：分析+拆解（decompose 写入）
+
specTEXT?Medium：改动方案（spec 写入）
+
operationsTEXT?Easy：操作说明
+
resultTEXT?JSON TaskResult（branch/worktree/diffSummary/verdict/securityVerdict/mergeTaskId…）
+
retry_baselineINTEGER上次手动重投时的失败数基线（重置重试计数用）
+
next_eligible_atTEXT?退避截止时间；早于此不被调度（null=即刻可领）
+
+
+ +
+
+ runs + 每次 agent 运行记录 +
+
+
kindTEXTplanner | executor | reviewer | security + conflict（本轮新增）
+
statusTEXTstarted | succeeded | failed | cancelled
+
worktreeTEXT?executor/conflict 有；planner/reviewer 无
+
worker_pidINTEGER?daemon 判活用
+
last_seqINTEGER已 ingest 的 outbox 最大 seq（幂等游标）
+
transcript_refTEXT?转录 .jsonl 路径
+
+
+ +
+
+ approvals + 审批闸记录（不可变日志） +
+
+
gateTEXTplan | spec | exec
+
actionTEXTaccept | reject
+
reasonTEXT?reject 时必填
+
+
+ +
+
+ events + 追加型事件日志（审计 + 看板实时推送源） +
+
+
typeTEXTtask.updated · merge.failed · merge.remediated · …
+
payloadTEXTJSON；包含冲突文件列表、verdict 等结构化数据
+
+
+
+ +
+ 🆕 标注的列是本轮优化新增字段（projects 表 schema 需 migration）；runs.kind 无 CHECK 约束，加 'conflict' 兼容老数据。 +
+
+ +
+ +
+

实现顺序

+

每类先 typecheck + build + test 验证，通过后再进下一类

+
+
+
第一批（① 任务拆解类）
+
models.ts 档位分化 → runner.ts（git工具+maxTurns+prompt改） → pipeline.ts（parseDecompose扩展） → ingest.ts（priority/deps落库+autoApprovePlan） → store.ts+api（执行期锁）
+
+
+
第二批（② 执行类）
+
pipeline.ts（sync main+并行复审+分项检查+diff闸） → models.ts reviewer改fable → ingest.ts（reject硬闸+自动合并条件） → protocol.ts（新信号类型）
+
+
+
第三批（③ 解冲突类）
+
protocol.ts runKind+conflict → pipeline.ts conflict分支 → runner.ts buildConflictPrompt → models.ts conflict角色 → orchestrator.ts 优先抢占
+
+
+
第四批（DB schema migration）
+
projects 表加 checks/auto_approve_plan/auto_approve_exec 列；schema.sql + store.ts 读写；版本迁移脚本
+
+
+
+ +
+ + + +