AtomCode v5.0.9 新子系统深度分析 — Review 组装、Scope 限定与预算控制

基于 strings 工具契约 + 系统提示注入 + 环境变量 + WebUI i18n 的还原分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md 姊妹报告：33_ReviewDeep_Resume_Headless.md、40_Execution_Policy_Intervention.md

---

1. 源码模块（全新）

crates/atomcode-review/src/
  ├── assemble.rs       ← 组装：provider 槽位填充 + runtime 组装
  ├── confine.rs        ← 工具调用限定（review scope confinement）
  ├── fanout.rs         ← 扇出：reviewer 并行分发
  ├── impact_plan.rs    ← 影响面规划（确定性、code-graph 引导）
  └── round_budget.rs   ← 轮次预算：round 截止 + 强制收尾

→ assemble.rs 是 /review 的子代理运行器组装器；confine.rs 是全新安全边界。

---

2. Review 组装（assemble.rs）

2.1 Provider 槽位填充

provider slot filled at assemble before any turn
agent provider slot filled at assemble before any turn
team provider slot filled at assemble before any turn
coding runtime assemble failed:

→ 三种 slot 面（agent / team / 通用），在第一个 turn 之前由 assemble 阶段完成 provider 绑定； 任何 turn 中缺失即视为内部错误（"internal error" 语义）。

2.2 运行时组装

coding runtime assemble failed:

→ 与 31 号报告的子代理运行器（subagent runtime）对应：/review 的审查子代理同样走 assemble → 绑定 provider → 起 turn 的生命周期。

---

3. Review Scope 限定（confine.rs）— 全新安全边界

3.1 显式互斥作用域（ScopeArg）

explicit mutually-exclusive review scope. Omit for working-tree changes.
Optional repo-relative path filters.
paths / confirm_scope
internally tagged enum ScopeArg (WorkingTree / ...)

ScopeArg 是一个 internally tagged enum，变体含：

• WorkingTree — 工作树改动（默认）
• Range — 分支区间 {base, head}
• Staged — 暂存区改动
• （Paths 路径过滤器为独立可选字段）

3.2 作用域互斥约束

`base` and `staged` are mutually exclusive
`scope` cannot be combined with legacy `base` or `staged`
working tree vs HEAD --count

→ 新旧两代参数面共存：新 scope 枚举与旧 base/staged 参数互斥； working tree vs HEAD --count 暗示内部用 git diff --count 计算改动规模。

3.3 工具调用限定（核心机制）

path is required under review scope confinement;
  pass a path within the changed/reviewable files
'<path>' is outside the review scope;
  tools may only access the changed/reviewable files (and their parent directories)

→ 审查子代理的所有路径型工具被 confine：只允许访问"改动/可审阅文件及其父目录"， 越界路径直接被拒。这是 /review 独立子代理在隔离边界的工具级强制。

3.4 作用域预检（Preflight）

Large scopes return a preflight instead of starting;
  only echo `confirm_scope` after the user explicitly accepts that exact scope.
Opaque token from a preflight. Pass only after explicit user confirmation.
invoke this tool without pre-reviewing the diff
code_review: scope confirmation required; reviewer was NOT started.
code_review: invalid scope:
  call `code_review` again with `"confirm_scope":"<token>"`

→ 大范围审查先返回 preflight 令牌，不直接启动；用户确认后回传 confirm_scope 才真正拉起 reviewer。防一次性扫描整个仓库。

3.5 作用域语义错误串

code_review: invalid arguments:
code_review: review provider is not wired (internal error)

---

4. 轮次预算（round_budget.rs）— 强制收尾协议

4.1 预算变量

ATOMCODE_REVIEW_MAX_ROUNDS          ← 最大轮次
ATOMCODE_REVIEW_MAX_DURATION_SECS   ← 最大时长（秒）

4.2 轮次截止注入

[review budget] You have used round <N>/<MAX>.
  Stop broad exploration. For every issue you are ALREADY confident about,
  call `report_finding` immediately, then write your closing summary.
  Only open a new file when it directly confirms a specific suspected issue.
  Do not start new exploration.

[review budget] FINAL round (<MAX>). This is your last chance to report.
  Call `report_finding` for every issue you have not yet reported NOW,
  then write your closing summary.
  After this round the review is cut off and any unreported finding is lost.

→ 渐进收窄：每轮递减探索宽度（N → FINAL → cut off），FINAL round 强制 report_finding 全部落盘，未上报即丢失。

4.3 与 Tool 循环阈值联动

ATOMCODE_TOOL_LOOP_WARNING_THRESHOLD
ATOMCODE_TOOL_LOOP_STOP_THRESHOLD
tool-loop warning threshold must be lower than stop threshold

→ 工具循环有独立的 warning/stop 双阈值（防死循环），与轮次预算互补。

---

5. 影响面规划（impact_plan.rs）— 确定性 code-graph 引导

5.1 规划头

## Review impact plan (deterministic, code-graph guided)
Use this plan to keep exploration bounded.
Prefer code-intelligence tools over broad grep/read loops.
The DIFF remains authoritative.

5.2 高价值目标推演

High-risk review targets. For each target, first inspect the changed hunk,
then use `list_symbols`/`read_symbol` for local context and
`find_references` + `trace_callers`/`trace_callees` or
`file_dependencies`/`blast_radius` for the affected path.
Do not conclude clean until these target contracts are checked:
  - ` <symbol> ` in ` <file> `
  - why:
  - code-graph recipe: `list_symbols`/`read_symbol` in this file;
    `find_references` for `<symbol>`;
    `trace_callers`/`trace_callees` if the graph has this symbol;
    `file_dependencies` or `blast_radius` for the file when symbol graph is unavailable.

No high-risk symbol targets were inferred. Review the changed hunks and only use
deeper code-graph tools if a hunk changes runtime behavior, dependency resolution,
or public contracts.

→ 确定性影响面清单：从 diff 的 hunk 推断高风险符号（符号→文件→原因→recipe）， 把探索限制在 code-graph 引导的路径上；无可推断符号时明示回退策略。

5.3 code-graph 工具族（confine 允许面）

list_symbols / read_symbol / find_references
trace_callers / trace_callees / trace_chain
blast_radius / file_dependencies

→ 与 confine 配合：路径型工具受限，但符号级工具自由——这是影响面规划的执行底座。

---

6. 扇出（fanout.rs）

crates/atomcode-review/src/fanout.rs

• 负责将 review 工作扇出到多个 reviewer 并行执行（维度/文件并行）
• 与 33 号报告的 ReviewRequest { reviewer_depth, reviewer_model, verify, ... } 请求面及 4 维透镜（bugs/perf/security/...)配合
• 命名与 31 号报告的子代理并行编辑（parallel subagents）同族

---

7. 生命周期事件（WebUI 侧联动）

state/lifecycle
finish_turn / turncomplete / phasechange
GoalUpdatePhaseChange / tokenusage

→ review 子代理与主 agent 共享 Turn/Lifecycle 事件协议； report_finding 工具一次性上报单条 finding，由内核聚合为最终报告。

---

8. 分层总结

层	机制	模块/证据
组装	provider slot 填充 + runtime assemble	assemble.rs
范围	ScopeArg 互斥 + preflight 确认	confine.rs / confirm_scope
边界	工具级路径 confine	'<path>' is outside the review scope
预算	轮次/时长双上限 + FINAL 强制收尾	round_budget.rs / ATOMCODE_REVIEW_*
规划	确定性 code-graph 影响面	impact_plan.rs
并行	reviewer 扇出	fanout.rs
汇总	report_finding 单条上报 + 聚合	report_finding 契约

---

9. 逆向方法论备注

1. path is required under review scope confinement 一字不漏暴露工具级限定规则
2. internally tagged enum ScopeArg 直接给出 Rust 序列化形态（枚举名 + 标签）
3. Large scopes return a preflight... 还原人工确认门槛（防整仓扫描）
4. [review budget] FINAL round... any unreported finding is lost 是强制收尾协议的逐字证据
5. ATOMCODE_REVIEW_MAX_ROUNDS / _MAX_DURATION_SECS 环境变量暴露预算上限可配置
6. ## Review impact plan (deterministic, code-graph guided) 明确该规划是确定性引导而非 LLM 自由探索
7. trace_callers/trace_callees/blast_radius/file_dependencies 工具族补齐 code-graph 六件套

---

本报告由持续分析循环生成 — v5.0.9 Review 组装、Scope 限定与预算控制深度分析