diff --git a/docs/index.html b/docs/index.html index 47fc465..4382495 100644 --- a/docs/index.html +++ b/docs/index.html @@ -86,8 +86,13 @@ body{font-family:'IBM Plex Mono',monospace;background:var(--bg);color:var(--text
-
调研 知识库调研 · 0
-
（暂无）
+
调研 知识库调研 · 1
+ +
任务执行规则参考 · 当前实现
+
docs/task-rules.html
+
后台 agent 处理任务的当前线上规则（非提案）：复杂度路由（easy/medium/hard）+ 四类执行路径——① 任务拆解（HARD，只读 planner，2–6 子任务·depth≤4·5 字段·三段输出·落库·审批·子任务调度）· ② 方案撰写（MEDIUM）· ③ 任务执行（executor，worktree + verify/checks/diff/双复审硬闸 + auto-merge）· ④ 解冲突（conflict，真 git merge + P0 插队）。含跨类通用规则、模型档位（默认 opus-4-8 + 项目可配 + 回退链）、关键状态转移表。
+
HTML规则参考
+
diff --git a/docs/task-rules.html b/docs/task-rules.html new file mode 100644 index 0000000..61e58cd --- /dev/null +++ b/docs/task-rules.html @@ -0,0 +1,229 @@ + + + + + +Maestro · 任务执行规则参考 + + + + +
+ MAESTRO + · 任务执行规则参考 + ← 文档索引 +
+
+

Maestro 后台 agent 处理任务的当前实现规则（非设计提案，是线上真实行为）。按复杂度路由分四类执行路径：① 任务拆解（HARD）· ② 方案撰写（MEDIUM）· ③ 任务执行（executor）· ④ 解冲突（conflict），外加跨类通用规则与模型档位。

+

真相源：src/executor/runner.ts · src/daemon/orchestrator.ts · src/daemon/ingest.ts · src/executor/pipeline.ts · src/executor/models.ts · src/model/status.ts。如与代码不符，以代码为准。

+ + +

0 复杂度 → 生命周期路由

+

任务按 complexity（可由 auto 让模型判定）走不同路径；只有产生代码改动的任务才过 exec_review（双复审 + 合并）。

+ + + + + + + +
复杂度路径人审闸谁来做
EASYinit → ready → queued → executing → exec_review → doneexec_reviewexecutor（直接执行）
MEDIUMinit → speccing → spec_review → ready → … → exec_review → donespec_review + exec_reviewplanner 写方案 → executor 执行
HARDinit → analyzing → plan_review → decomposed →（子任务各自跑）→ doneplan_review +（各子任务的闸）planner 拆解 → 子任务递归
+
三种 run 类型（runs.kind）：planner（拆解 HARD / 写 MEDIUM 方案，只读）· executor（worktree 内改代码）· reviewer / security（执行后双复审，只读）· conflict（解合并冲突，本会话新增）。
+ + +

① 任务拆解（decompose）HARD only 只读

+
+
触发 + 执行环境
+ +
+
+
拆解约束（prompt 硬性要求）
+ +
+
+
输出格式（三段）
+
    +
  1. Markdown 表格总览（序号 / 标题 / 复杂度 / 优先级 / 依赖 / 文件范围）——给人审看；
    2. +
  2. 一段分析与拆解理由正文；
    3. +
  3. 末尾唯一一个 fenced JSON {plan, subtasks:[…]}——给机器解析。解析失败 = planner 失败、退避重试。
    4. +
+
+
+
落库（ingest 处理结果）
+ +
+
+
审批 + 之后调度
+ +
+
+
失败 + 收口
+ +
+ + +

② 方案撰写（spec）MEDIUM 只读

+ + + +

③ 任务执行（executor）改代码

+
+
执行环境
+ +
+
+
approve 前的硬闸（任一不过 = 不进 exec_review）
+
    +
  1. 执行前同步 main + 分歧重评估（规则13）：起跑前把最新 origin/main 并进 worktree；若撞上本任务声明范围内的文件改动 → 转 needs_attention 待重评估（不盲目硬解）。
    2. +
  2. verify 闸：项目 verifyCmd 在 worktree 内跑（10min，exit 0 才过；未配=视为通过）。
    3. +
  3. 分项检查闸 checks：独立的 lint / typecheck / build（项目可配，分项报告哪项挂）。
    4. +
  4. diff 闸：体量超阈值、或改了声明范围外文件（task.scopeFiles 非空时）→ 拦截。
    5. +
  5. 双复审硬闸：code review + security audit 并行跑（各只读、最强档不被 project.model 降档）；任一 verdict=reject → 退回重执行（带复审意见），不进 exec_review。
    6. +
+
+
+
审批 + 合并
+ +
+ + +

④ 解冲突（conflict）改代码

+ + + +

⑤ 跨类通用规则

+ + + + + + + + + + + + + + +
规则说明
执行期锁任务一旦有在途 run（planner/executor/reviewer/conflict）→ 锁定只读：禁改 title/spec/complexity/deps、禁再调度；run 结束（finish/fail/reap）解锁。
worktree 隔离写类 run 只在自己 worktree 内改动，禁碰 worktree 外文件；planner/reviewer 只读、不建 worktree。
不 push / 不部署任何 run 都不得 git push / 对外发布；解冲突的 merge 是受控本地合并。
commit 含 task ID所有产出 commit message 必带任务 ID，ensureCommitted 兜底。
重试退避 + 升级失败按退避重试，超 maxRetries（默认 2）→ needs_attention 转人工（planner 留原态、executor 走 failed）。
自动放行默认关所有「跳过人审」（plan/exec）默认关闭，须项目级开关 + auto-approved 才生效。
reject 必带意见plan/spec/exec 的驳回必须带 reason，按状态机回流重做。
复审独立性复审只读、与执行分离、用最强模型、不被 project.model 降档；verdict=reject 是硬闸。
daemon 唯一 DB 写者worker 不碰 DB，只读 job.json、写 outbox.ndjson；状态变更只经 transition() 守卫。
超时分层planner/executor 30min（可配）· verify 10min · 复审 15min（并行）· conflict 给足强档时间。
+ + +

⑥ 模型档位

+

内置默认：每个角色 × 每个复杂度都是 claude-opus-4-8（DEFAULT_MODEL）。可按项目经 projects.models(JSON) 配置。

+

解析优先级（高→低）：① project.models[role]（per-role，含 reviewer/conflict）→ ② 旧 project.model（仅 executor/planner）→ ③ env（MAESTRO_MODEL_* / _REVIEW_* / _PLAN_*）→ ④ DEFAULT_MODEL。

+

四角色：executor / planner / reviewer / conflict。不可用回退链：opus-4-8 → sonnet-4-6 → fable-5（单 run 内只重试一次）。

+
注：claude-fable-5 在部分环境不可用，已移出内置默认；原「按复杂度分档（hard=fable / medium=opus / easy=sonnet）」的设计因此改为统一 opus-4-8 + 项目可配。
+ + +

⑦ 关键状态转移

+ + + + + + + + + + + + + + + +
从到触发
initanalyzing / speccing / ready按 hard / medium / easy 路由
analyzingplan_review拆解完成
plan_reviewdecomposed / analyzingaccept / reject(+意见)
speccingspec_review方案完成
spec_reviewready / speccingaccept / reject(+意见)
readyqueued / blocked领取 / 依赖未满足
queuedexecutingworker 起跑
executingexec_review / failed执行完成 / 失败
exec_reviewdone / readyaccept(合并) / reject(返工)
failedqueued / needs_attention重试 / 超阈值
decomposeddone子任务全 done
+

完整合法转移表见 src/model/status.ts 的 TRANSITIONS；状态机/ER 全图见 优化方案文档 ⑤⑥ 节。

+ +
单一入口见 docs/index.html · 本文档描述当前线上规则，随实现演进更新 · 与代码不符以代码为准。
+
+ +