From 5c68bb93246c2e0d6dc27214f0adf08fe3ed707f Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Mon, 29 Jun 2026 23:32:30 +0800 Subject: [PATCH] =?UTF-8?q?docs(task-rules):=20=E6=96=B0=E5=A2=9E=E4=BB=BB?= =?UTF-8?q?=E5=8A=A1=E6=89=A7=E8=A1=8C=E8=A7=84=E5=88=99=E5=8F=82=E8=80=83?= =?UTF-8?q?=20HTML=20+=20=E7=99=BB=E8=AE=B0=20docs/index=20=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=BA=93=E5=88=86=E7=B1=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/index.html | 9 +- docs/task-rules.html | 229 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+), 2 deletions(-) create mode 100644 docs/task-rules.html 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 只读

+
+
触发 + 执行环境
+
    +
  • 仅 HARD 任务拆解；编排器把它领进 analyzing 态，起一个 planner run。
    • +
  • 只读：cwd = 主仓（不建 worktree、不改任何文件）；工具白名单仅 Read / Glob / Grep + Bash(git log/diff/show)。
    • +
  • 模型：planner 档，默认 claude-opus-4-8（项目可配）；maxTurns=90。
    • +
  • 触发前提：叶子任务 · 不在退避冷却 · 依赖全 done · 项目 autonomy ≠ manual。
    • +
+
+
+
拆解约束（prompt 硬性要求）
+
    +
  • 拆成 2–6 个更小、可独立交付的子任务。
    • +
  • 层级闸：depth ≤ 4（根=1），prompt 注入「剩余可拆层数」；子任务只有在剩余层数 > 0 时才允许再标 hard（防无限拆）。
    • +
  • 每个子任务 5 个字段：title · complexity(easy/medium/hard) · priority(0/1/2) · deps(依赖本列表的 0-based 序号) · files(文件范围 glob)。
    • +
  • files = 该子任务预计改动的文件范围；执行时改越界文件会被硬闸拦截，故须尽量精确，不确定留空数组（不限）。
    • +
+
+
+
输出格式（三段）
+
    +
  1. Markdown 表格总览（序号 / 标题 / 复杂度 / 优先级 / 依赖 / 文件范围）——给人审看；
    2. +
  2. 一段分析与拆解理由正文；
    3. +
  3. 末尾唯一一个 fenced JSON {plan, subtasks:[…]}——给机器解析。解析失败 = planner 失败、退避重试。
    4. +
+
+
+
落库（ingest 处理结果）
+
    +
  • JSON 的 plan（一句话理由）→ 存父任务 plan 字段（即评审界面的「说明」）；
    • +
  • 每个 subtask 建成子任务：priority、files→scopeFiles 直接落库；deps 先全建好子任务再做「序号→taskId」二次映射写依赖；
    • +
  • ⚠ 表格 + 分析正文那两段被丢弃，只留在该 run 的 transcript 里（评审界面「拆解轨迹」可展开查看）。
    • +
+
+
+
审批 + 之后调度
+
    +
  • 默认 → 转 plan_review 人审。
    • +
  • 可选自动放行（默认关）：项目 auto-approved + autoApprovePlan 开 + 拆解结果全 easy + 子任务数 ≤ 5，四条全满足才跳过人审直接 decomposed。
    • +
  • 父任务在 plan_review / analyzing 期间，子任务被冻结（不可领取，UI 显示「待拆解确认」）。
    • +
  • 批准后（plan_review→decomposed），子任务解冻，按 deps + priority 调度，各自独立 worktree（都从 main 拉出）执行、独立合并回 main。
    • +
+
+
+
失败 + 收口
+
    +
  • 解析失败 / run 失败 → failPlanAttempt 退避重试，超 maxRetries（默认 2）→ 转 needs_attention 待人工；
    • +
  • 父任务 decomposed 后，子任务全 done → 父任务自动 done。
    • +
+
+ + +

② 方案撰写（spec）MEDIUM 只读

+ + + +

③ 任务执行（executor）改代码

+
+
执行环境
+
    +
  • 每个任务独立 worktree（分支 maestro/<taskId>，从 defaultBranch(main) 拉出）；permissionMode=acceptEdits。
    • +
  • 工具：Read/Edit/Write/Glob/Grep + git(status/diff/log/add/commit，无 push) + 测试/构建（npm/go/pytest/make…，仍关在 worktree、不发包）；maxTurns=100。
    • +
  • 模型：executor 档（默认 opus-4-8，项目可配；旧 project.model 也覆盖 executor）。
    • +
  • 必须 commit，message 带任务 ID（ensureCommitted 兜底）。
    • +
+
+
+
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. +
+
+
+
审批 + 合并
+
    +
  • 全绿 → 转 exec_review 人审；accept 触发 --no-ff 自动合并回 main（merge:false 可跳过合并）。
    • +
  • 可选自动放行（默认关）：auto-approved + autoApproveExec 开 + 双复审均 approve → 跳过人审自动合并。
    • +
  • 合并冲突 → 自动建 P0 解冲突补救任务（见 ④），原任务留 exec_review，补救成功后自动收口。
    • +
+
+ + +

④ 解冲突（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 · 本文档描述当前线上规则，随实现演进更新 · 与代码不符以代码为准。
+
+ +