★ 实现状态 ✅ 全部上线
本方案各项已于 2026-06-25 实现、补测试并经 launchd daemon 端到端实跑验证；下表为「优化点 → 实现 → 提交」对照。线上实测捕获并修复了 3 个单测未覆盖的 bug（DB 迁移漏列 / fable-5 不可用未触发回退 / autoApproveExec 传错 id）。
| 优化点 | 实现要点 | 状态 | 提交 |
|---|---|---|---|
| Agent 记忆注入 L1–L4 | L1 上次失败原因（重试任务）· 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.depsspec 增加验收标准必填 + 可选影响文件清单 |
扩展 |
| 是否审批 | 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 前的检查链
| # | 检查 | 当前性质 | 优化后 |
|---|---|---|---|
| 1 | executor 完成 + commit 含 task ID | 硬闸 | 不变 |
| 2 | verify（project.verifyCmd，10min，未配=通过） | 硬闸（可选） | 不变 |
| 3 新 | 执行前 sync main + 分歧度量 | 无 | 新增：merge main 进 worktree；冲突/改动面过大→重评估/needs_attention |
| 4 新 | 分项 lint/typecheck/build 闸 | 无 | project 可配 checks；分项报告；任一非0=硬失败 |
| 5 新 | diff 越界/体量闸 | 无 | 改了声明外文件 / diff 行数超阈值 → 拦截或告警 |
| 6 | code review（maxTurns40，15min） | 仅建议 | reject → 硬闸：退回重执行（带复审意见）而非进 exec_review |
| 7 | security review（与 code 串行） | 仅建议 | reject → 硬闸；改并行跑（Promise.all，总耗≤15min） |
| → | exec_review 人审 | 强制 | 补完硬闸后：auto-approved+全绿+双approve → 自动合并（默认关） |
| merge | git 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；本轮新建完整解冲突流程
现状硬伤
- executor 白名单没有 git merge——补救任务被要求 git merge 却跑不了，CC 只能 Read/Edit 硬模拟，极易丢改动
- 解冲突标 easy→sonnet，最弱档，认知难度远超单文件改动
- 补救 worktree 从 defaultBranch 新建分支，operations 文字写"已从 targetBranch 检出"，文案与实际不符
| 维度 | 现状 | 优化决策 | 变更 |
|---|---|---|---|
| 触发 / 调度 | 合并冲突→建 P0 easy 补救任务；按 score 排队等领取 |
触发不变（自动建补救任务，幂等） 调度按最高优先级（P0）插队：补救任务以 P0 入队，rankByScore 即排队首、名额空出时优先领取；不中断在途任务（维持 No-preemption 架构） |
✅ 维持 |
| 执行流程 | 复用 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'；可按项目配置，默认 opus-4.8（fable-5 已移出内置默认）
orchestrator.ts
无需改：补救任务 P0 入队，rankByScore 即排队首；不中断在途（No-preemption 不变）
store.ts · ensureMergeRemediationTask
complexity 不再固定 easy；operations 改用 conflict runKind 标记，修正 worktree 文案
④ 任务通用规则（13条，全部采纳）
跨三类的横切规则；蓝色=本轮新引入；灰色=已有不变量明文固化
-
1新增 执行期锁：任务有在途 run（planner/executor/reviewer/conflict）即锁只读——禁改 title/spec/complexity/deps 等任何字段，禁再调度；run 结束（finishRun/failAttempt/reap）解锁。实现：store mutation 入口 + API 层加"在途即拒"校验；orchestrator.claimable 已天然排除，保持
-
2固化 worktree 隔离：写类 run（executor/conflict）在独立 worktree 内，禁碰 worktree 外文件；planner/reviewer 只读，不建 worktree。
-
3固化 不 push / 不部署：任何 run 都不得
git push/ 对外发布 / 部署；解冲突的 merge 是受控本地合并，不 push。 -
4固化 commit 含 task ID：所有产出 commit message 必带任务 ID；
ensureCommitted兜底。 -
5改进 模型回退链：模型不可用 →
fable-5 → opus-4-8 → sonnet-4-6回退（fable 置链首），单 run 内只重试一次。实现：models.tsMODEL_FALLBACK_CHAIN改为['claude-fable-5','claude-opus-4-8','claude-sonnet-4-6'] -
6固化 重试退避 + 上限升级：失败按退避（backoff，间隔递增）自动重试；超
max_retries（项目配，默认2）→ 转needs_attention（需人工介入）。needs_attention = 任务卡住不再自动重试，等人改/requeue/取消。触发：①失败超重试上限 ②合并冲突 ③歧义 -
7新增 自动放行默认关：所有"跳过人审自动放行"（plan/exec）默认关闭，须项目级开关 +
auto-approvedautonomy 才生效。 -
8固化 审批 reject 必带意见：plan/spec/exec 的 reject 必须带 reason，按状态机回流。plan_review→analyzing · spec_review→speccing · exec_review→ready
-
9强化 复审独立性：复审只读、与执行分离、用最强模型（fable-5）；复审不被 project.model 降档；任一 verdict=reject 变硬闸（退回重执行，不进 exec_review）。
-
10固化 daemon 唯一 DB 写者 / worker 不碰 DB：进程模型铁律；状态变更只经
transition()守卫（canTransition）。 -
11新增 统一输出锚点：每类 run 固定输出模板——planner=表格+JSON · executor=自述 · reviewer=模板+VERDICT · conflict=解冲突自述，便于机器解析 + 人审。
-
12固化 超时分层：planner/executor/conflict 30min（共用
project.timeout_ms，项目级可配）· verify 10min · 复审 15min（并行）· 分项 checks 单项 10min——后三者为固定常量（合理默认，暂不单列项目配置）。 -
13✅ 已实现 执行前同步 main + 分歧重评估：任务正式执行前，先把 defaultBranch 最新代码 merge 进 worktree；若改动过大 / 耦合过深 / 存在逻辑冲突，则触发方案重评估（转 needs_attention 待人工）而非盲目继续。实现：sync main 前先跑
reevalScopeGate——以git diff HEAD...origin/main取 main 自分支点以来改动的文件，与任务声明范围scopeFiles求交集；非空即 emitneeds-reeval→ daemonmarkReeval直接转needs_attention（不重试、不计失败次数、run 收尾 cancelled）。与③协同：执行前同步冲突=早发现；执行后合并冲突=③兜底
⑤ 任务状态机流转图
据 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 (P0 插队)
→(解决+复审)
exec_review
→(approve)
done
→自动收口原任务
完整状态机（自包含 SVG · 圆节点）
⊙ = 人审闸（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?旧·单项目级模型覆盖（仅 exec/planner）
modelsTEXT?🆕 按角色×复杂度模型配置 JSON（executor/planner/reviewer/conflict；默认 opus-4.8）
agent_rulesTEXT?🆕 项目级 agent 规范（注入 4 处 prompt，记忆 L2）
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 二次映射后写入
scope_filesTEXT?🆕 声明改动范围 glob JSON；越界硬闸 + 规则13 分歧重评估据此判定
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 等结构化数据
表关系（ER · 主外键）
projects 1—N tasks（项目下多任务）· tasks 自引用 parent_id（Hard 拆解树）· tasks 1—N runs / approvals（每任务多次运行与审批）· projects/tasks 1—N events（审计日志，task_id 可空）。
🆕 标注的列是本轮优化新增字段（projects/tasks 表 schema 经 ensureColumn 幂等迁移）；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角色（默认opus-4.8）；调度无需改：补救任务 P0 插队、不中断在途
第四批（DB schema migration）
projects 表加 checks/auto_approve_plan/auto_approve_exec 列；schema.sql + store.ts 读写；版本迁移脚本