# sillyspec 效率优化整体方案 v3（2026-09-21 整合版）

> 靶子（R4 实测，账单当量口径 = 新入 1× / 缓存 ~0.1× / 输出 3–5× 折算）：
> **大任务账单当量 2.4×（8.04 当量差）＝ 缓存体量差 55%（4.45）+ 扇出冷启动 26%（2.09）+ 输出差 19%（1.50，其中 77% 是子代理代码/测试产出＝交付厚度，不砍）**。
> 墙钟：大 2×、小 1.3×，差距全在非模型时间（门禁循环 + 编排等待）。
> 红线：**不动四道防线**（审查/门禁/核验/资产）；不砍交付厚度（输出差是产品）。所有优化只打三样：冗余重读、冷启动、等待。

## 战线 A：已落地，待 R5 验收（不重规划）

| 项 | 状态 |
|---|---|
| 门禁四项：模块粒度范围化 / fail-fast 前置 / lint 归属降档两门 / 超时帽 | 已提交（83d91cd4 / 2eba595c，模块粒度 v3.24 在场） |
| ~~增量复用~~ | **正式摘出（2026-09-21 R5 准备核对）**：src/ROADMAP/终报/batch2 四处查无落码与定义，承办无着落；疑即 ROADMAP 延后项「探针增量缓存」（quick-4af1acc3 D②：失效面广需独立失效契约）——按延后项处理，不计入战线 A，R5 验收不背此项 |
| gate verify lint parity / module-impact 引号+多map / Wave 并发帽 ≤3 | 已提交 61995a32 |
| 缺陷 A/B（资产尾 export + --linked-changes 管道） | 已提交 954946ae |

**R5 前置核对（2026-09-21 落盘）**：①对撞仓基线 50736b6ef / 53c67e02a 经 git cat-file 实证均在（multi-agent-platform 主树干净）；Temp 残留一批 prunable gate worktree——R5 跑前 `git worktree prune`。②account.mjs 已加三分+当量列（v2），基线钉死：R4-L 当量@3× 13.89M / R4-O-L 5.87M / **比值 2.37×**（@5× 口径 2.47×，复现终报 2.4×）；R5 判定一律用同脚本同口径复算，不比绝对值。③**B-④ 接线缺口**：材料包机制已落地但 execute 主链未主动生成（task-02 接线最小化，仅 options.materials 传入时渲染）——R5 的 B-④ on/off 对照前需补接线（小 quick 一项，或并入 batch2 M3 派发分组落点）。

**R5 验收点**：门禁轮次 ≤2；模块粒度下真拦率不降（用 gate-value-audit 的 12 次真拦案例回归）；大任务墙钟无额度事故（并发帽生效）。前置对账（v3.2）：五项中四项已核已交（模块粒度 v3.24 在场 / fail-fast+lint 归属 83d91cd4 / 超时降档 2eba595c），「增量复用」src 与终报均无落码痕迹——详 v3.2 第 4 条，R5 前与承办会话对齐状态，勿按「已在办」默认计入。

## 战线 B：扇出账单治理（打 55%+26% 的差额）

### B-① 读取范围引导（打冷启动 + 重读体量）——**已验靶：不实，实现项砍（2026-09-21，详 round4/b1-b1-target-validation.md）**
- **前置验证（先做，30min）**：读 task-08 的 transcript，判定 8.6M 是越界读还是任务规模相称——**靶子不实不立项**。
- **验靶结论**：越界读零发生（62 次调用全在契约链内）；8.6M = 58 轮 × 148K 轮均上下文的缓存重发（新鲜输入仅 186K）；全扇出 19 子代理名义 41.77M 中新鲜仅 1.34M（3.2%）。读上界太小，读清单注入无钱可省——**第 2 批实现项下线**，allowed_paths 现状约束维持。
- 杠杆换位到 **B-⑥ 轮数纪律**（见下）与 B-④。

### B-② 调研摘要共享（打实现侧重读）
- **做法**：调研产出追加一份 CLI 盖章 digest（两页，**每条契约事实带 file:line 锚点 + 「关键契约回源核对」条款**）；实现子代理读 digest 替代重读原始源码。
- **红线**：digest 转错一处 = 内部版错键正典（我们刚批判完的模式）——**走完整流程**，设计决策落盘（锚点格式 / 失效时机 / 回源义务）。
- 预期：实现侧重读降（调研段自身的 9.4M 压不动，靠 B-③ 摊）。

### B-③ batch 默认前置到 plan（打重复重建）
- **证据**：R4-S-F 5 任务 2 batch → execute 仅 6M/17min。
- **做法**：batch 粒度决策放 **plan 阶段**（文件正交 + 无契约链的任务默认并批，2–4/批）；execute 不加推力——**保 Wave 内并发 ≥3 的墙钟亮点**，不拿墙钟换 token。
- 属性：提示词级 + plan-postcheck 可加机械提醒。

### B-④ 材料包机制扩展到 execute（打冷启动）
- 复用 `assembleStageReviewMaterials` 基建：实现子代理拿 CLI 裁好的合同摘录（design 相关节 + 接口签名 + 目标文件锚点），不自行通读全量文档。
- **加分机制**：统一材料包 = 统一前缀 → 缓存命中更稳（面值之外的真实账单收益）。
- **装配顺序契约（v3.2）**：跨任务稳定内容（design 通摘 / 接口签名）在前、任务专属内容（任务卡 / 变更面摘录）在后——统一前缀的缓存命中依赖稳定段先行，混排则任务差异打断前缀、面值收益折半。
- 可直接进（机制在，低风险）。

### B-⑤ 子代理模型分级（打单价，不动 token）
- **必须先 A/B**：同任务双档各跑——便宜档若多轮返工（turn↑→重发↑）token 反升，且核验行为可能弱化（错键正是核验拦的）。**审查/verify 保持旗舰档是红线**。
- 只在 A/B 证实「实现档返工率不升」后启用。

### B-⑥ 轮数纪律（打轮数乘数；B-① 验靶换位新增，2026-09-21）
- **证据**：扇出名义体量 = Σ(轮数 × 轮均上下文)，新鲜内容仅 3.2%——轮数是另一半杠杆。task-08 的 58 轮里 Edit×7（相邻同文件逐个改）+ TodoWrite×4（每条占一轮重发全上下文）+ 测试 Bash 多次循环。
- **做法**（提示词级，execute 派发 prompt 两三行）：① 相邻同文件的多个改动合并为一次 Edit 批量提交；② TodoWrite 降频（阶段边界用，不在实现中途连发）；③ 测试验证合并跑（一次 Bash 串行多查），不逐文件跑。
- 属性：提示词级；R5 用子代理请求数验收（扇出 522req 基线）。

### 战线 B 预期（保守）
扇出段 42.3M → **28–32M**（上界 25M 需 ①②③ 全中且提示词被遵守）；账单当量比 2.4× → **~1.7–1.9×**。到不了 parity 也不该到——剩余差额 = 上下文保险 + 独立审查 + 交付厚度的价格。

## 战线 C：编排会话上下文治理（打主会话 56.8M 的一部分）

### C-1（P1，quick 可落）
- **B1 子代理返回契约**：返回体 ≤25 行结构化摘要（verdict / 触碰文件数 / 测试一行 / 偏差），细节落盘按需 Read——真相由门禁对账，不靠返回体转述。
- **B2 审查回收瘦身**：verdict 回一行 + blockers + review.json 路径（稳定路径已在），主代理按需 Read 工件。
- **B3a prompt 审计先行**：只读脚本统计 R4 五份 transcript 各步 prompt 规则的「引用/遵守/从未触发」，产出瘦身候选——**测量完再删**（四律这轮刚实证有效，承重规则不动）。

### C-2（P2，CLI 小刀）
- **B4a `sillyspec handoff --change <名>`**：进度库机械生成 ≤80 行交接包（阶段/Wave 状态/blockers/决策 ID/下一步命令）——把「任务太大爆窗」从硬墙变成操作规程。零状态机改动。
- B3b 依据 B3a 审计瘦身步骤 prompt。

### C-3（P3，立项评估，勿直接开码）
- B4b 编排自动分段：先让 B4a 人工规程跑两个真实超大变更，再决定自动化。
- 目标：R4-L 量级任务主会话峰值 **377K → <250K**，>150K 请求占比 81% → <50%。

## 执行顺序（依赖排序）

```
第 1 批（并行，本周）：
  B-①前置验证(30min) ──不实则砍①
  B-③ plan batch 默认（提示词+postcheck 提醒）
  B-④ 材料包扩展（复用基建，含装配顺序契约）
  C-1 B1/B2 返回契约+回收瘦身（提示词）
  C-1 B3a prompt 审计（只读脚本）
  R5 探针套件：错键类+审查钳用例（verify-probes 基建增量造）──防线回归硬门的判法依赖（v3.2）
第 2 批（依据第 1 批）：
  B-⑥ 轮数纪律（提示词，B-① 验靶换位顶替原「读清单注入」）
  C-2 B4a handoff 命令
  B-⑤ 模型分级 A/B
第 3 批（完整流程立项）：
  B-② 调研 digest（锚点/失效/回源契约设计）
  C-2 B3b prompt 瘦身（依据审计）
  C-3 自动分段评估
```

## R5 验收协议（一等指标升级）

| 指标 | R4 基线 | 目标 | 判法 | 依赖批次 |
|---|---|---|---|---|
| **账单当量比（大任务）** | 2.4× | ≤1.8×（拉伸） | account.mjs 加折算列（三分已有查询） | ④ 机制 + ①②③ 概率 |
| 扇出段 tokens | 42.3M | ≤32M（硬门） | 子会话聚合 | ④ 机制 + ①③ 概率 |
| 门禁轮次 | 9（S-F 病理）/ 2（稳态） | ≤2（硬门） | 进度库 | 战线 A |
| 大任务墙钟·不劣化 | 156min | ≤156min（硬门） | 会话时间戳 | 全体——「不拿墙钟换 token」可检化 |
| 大任务墙钟·进取 | 156min | ≤120min（拉伸） | 会话时间戳 + **阶段级拆账** | ①④+C-1，概率项无机制保票 |
| 主会话峰值单请求 | 377K | <250K | MAX() 查询 | 第 3 批 B3b——R5 只记录不判罚 |
| >150K 请求占比 | 81% | <50% | 计数查询 | 第 3 批 B3b——R5 只记录不判罚 |
| 防线回归 | — | 错键类案例仍被拦；审查钳仍达标 | **探针套件（第 1 批交付）** + transcript | 第 1 批探针 |

场景：50736b6ef / 53c67e02a 同基线重放（两 SHA 是对撞仓 multi-agent-platform 的基线、非本仓对象——跑前核那边基线与 worktree 卫生），小 ×2 + 大 ×1，版本钉死首步回显。**R5 时点 = 第 1+2 批完成后**；250K / 50% 两行押第 3 批 B3b，R5 只记录不判罚，第 3 批后复测。**2 跑取分布，不外推；提示词级项不达标即升级机制化（路径：CLI 截断注入/机械组装）。** 墙钟 ≤120min 无 per-item 机制预算——R5 必须落盘阶段级墙钟拆账（调研 / plan / execute 扇出 / verify / 归档 / 门禁等待），作为 R6 的预算基线，先测后诺（同 B3a 纪律）。

## 诚实边界

- B-①②③⑤ 全含概率性或前提验证，百分比是方向估计，唯一承诺是 R5 可测；
- 55% 的缓存体量差不可能清零——隔离上下文的语义就是重读，治理目标是「去冗余」不是「去重读」；
- 剩余 ~1.7× 账单差 + 墙钟差里，含交付厚度（输出 19% 差额）与独立审查的固定成本——这部分是定价，不是缺陷，对外口径已按此表述。

---

# 评审修订 v3.1（2026-09-21，外部评审采纳记录）

## 采纳并修订的六处

1. **B4a 改为 enrich handoff（已验证属实）**：`src/handoff.js` 已存在（113 行，`buildHandoff`/`nextStageSuggestion`），现产出为 session 导出 + 下一阶段建议的瘦包。C-2 第 2 批工作量修正为「进度库多抽几段进现有 buildHandoff」（Wave 状态 / 未决 blockers / 决策 ID / 下一步命令行，≤80 行封顶），**不是新命令立项**。
2. **R5 验收拆硬门/拉伸**：
   - **硬门**（不达标即失败）：扇出 ≤32M · 门禁轮次 ≤2 · 防线回归（错键类仍被拦 + 审查钳达标）· 大任务墙钟 ≤120min（稳态口径）
   - **拉伸**（①②全中才承诺）：账单当量 ≤1.8×
   - 对外口径维持 1.7–1.9×；不再把拉伸当硬门。
3. **墙钟基线钉死**：比较一律用**稳态 156min**（门禁单轮重构口径），毛墙钟 185min 仅作背景。「额度事故不再发生」是并发帽的验收项（R5 零事故），不从基线剔除。
4. **判定路径统一显式勾掉**：gate verify PASS vs verify --done FAIL 的口径矛盾**已修**（61995a32：runGate verify 补 verify-lint，与 --done 同引擎同归属降档）；tail 截断→失败明细稳定路径**已修**（794529e5）。两项归战线 A 待 R5 验收，第 1 批不重开。
5. **B-③ 加并发护栏**：plan-postcheck 增机械提醒——**并批后单 Wave 在飞子代理数 ≥ min(3, 该 Wave 任务数)**；batch 决策只在 plan 定，execute 不加推力。外推边界写明：S-F 5→2 batch/6M 是小任务证据；大任务 12 实现代理并批**收益在 token、成本在墙钟**，R5 大任务跑单独归因。
6. **B-④ 预期收窄 + 升第 1 批必达**：材料包只压「design/合同文档通读」，压不动「要改的源码本身」——与 B-① 互补但**不得双重算账**。

## 优先级调换（接受）

**第 1 批必达改为：B-④ 材料包扩面 + C-1（B1 返回契约 / B2 回收瘦身 / B3a 审计）+ B-③（plan 默认 + postcheck 护栏）**——机制确定收益优先于又一条 hint。**B-① 降级为仅保留 30min 验靶**，验证属实再排实现。

## 新增纪律（三条，全部采纳）

- **prompt 注入上限**：每加一段注入必须写明「替换哪段旧文」或配 CLI 截断上限——防优化文案自己吃掉 377K→250K 指标。
- **互斥实验标签**：①②④ 都声称「少读」，R5 至少 B-④ on/off 同基线各一跑，归因可分。
- **A 先于 B**：R5 小任务两跑**先判门禁 ≤2**，再谈扇出 tokens——门禁稳态前账单优化会被墙钟噪声淹没。

## B-⑤ 验收补一维（采纳）

A/B 双档除返工率外，加测**事实核验类工具调用密度**（联网搜真名 / 读 SDK d.ts 的次数）——错键故事里「会不会核验」比「会不会写完」更关键；便宜档核验密度显著下降即否决。

## 对反馈的一处澄清（非驳回）

反馈第 4 条「第 1 批缺确定 ROI 墙钟项」的时态已过：判定路径统一与 tail 稳定路径在评审前已提交（61995a32 / 794529e5），本次修订将其从隐含改为显式勾掉（见上第 4 条）。其余五处修订 + 优先级调换 + 三条纪律全部接受。

---

# 评审修订 v3.2（2026-09-21，第二外部评审采纳记录——验收协议三硬伤修复）

前置：本轮评审先核事实后评方案，承重声明全部属实——handoff.js 113 行（buildHandoff/nextStageSuggestion，src/handoff.js:23/48）、assembleStageReviewMaterials 复用面（review-material-pack.js，plan/execute/brainstorm 三处引用）、account.mjs 三分查询 + db.model_usage 本有 cache_creation/cache_read 列（折算列是小改）、review.json 稳定路径（src/index.js:664）、gate-value-audit 12 真拦/36 超时 34%/227 门禁、42.3M/156min 在 r4-final-report.html 落盘、三提交号（61995a32/954946ae/794529e5）在。方案地基为实，三红线与三纪律不动。与 v3.1 的纯追加不同，本次对 R5 验收表与执行顺序**就地重写**（表是操作性章节，留旧表加补丁会迫使读者自行对账），修订记录在此。

## 三处验收协议修复

1. **墙钟 ≤120min 从硬门降为拉伸，换入「不劣化 ≤156min」硬门**。依据：基线 156 本是门禁单轮重构口径（v3.1 第 3 条），门禁收益已折入基线；B-③ 明确不拿墙钟换 token，B-①/④/C-1 全为概率项——120 无任何 per-item 机制保票，硬门失败时无法区分「方案失效」与「归一化基线乐观」。不劣化硬门把「不拿墙钟换 token」从口号变成可检承诺；R5 落盘阶段级墙钟拆账（六段），R6 才有真预算基线。**硬门集合相应改定：扇出 ≤32M · 门禁轮次 ≤2 · 防线回归 · 墙钟不劣化 ≤156min（另：并发帽 R5 零事故维持）；拉伸：账单当量 ≤1.8× + 墙钟进取 ≤120min。**对外口径同步。
2. **防线探针套件排入第 1 批**。「探针 + transcript」判法依赖的用例集原先不在任何批次——12 次真拦来自两个月 227 次历史门禁，R5 三跑自然撞不到。基于 verify-probes 基建（src/verify-probes.js 在场）增量造错键类 + 审查钳用例，硬门才有可执行判法。错键形态以 r4-final-report「错键生产 no-op、测试全绿掩护」为准。
3. **验收表增「依赖批次」列 + R5 时点钉死**。377K→<250K、81%→<50% 实押第 3 批 B3b（B3a 只审计不删）——R5 时点定为第 1+2 批完成后，此两行只记录不判罚，第 3 批后复测；消除「表行达标承诺」与「批次排期」的错位。

## 两处状态对账（操作性，非方案缺陷）

4. **战线 A「增量复用」状态存疑**：五项中四项已核已交（模块粒度 v3.24 在场 / fail-fast+lint 归属 83d91cd4 / 超时降档 2eba595c），唯「增量复用」在 src 与 r4-final-report 均无落码/定义痕迹，changes/ 亦无活跃变更；ROADMAP 登记的延后项「探针增量缓存」（quick-4af1acc3 D②：失效面广需独立失效契约）疑为同物——若同物则已延后，应从战线 A 摘出重归属。R5 前与承办会话对齐，勿按「已在办」默认计入（已同步批注到战线 A 验收点）。
5. **重放基线在对撞仓**：50736b6ef / 53c67e02a 经 git cat-file 验证非本仓对象；worktree 路径实证基线在 multi-agent-platform 仓——R5 跑前核那边基线 SHA 与 worktree 卫生（防未来提交泄露规则沿用 R4 prompt 既有一套）。

## 一处实现注记

6. **B-④ 装配顺序契约**（已写入 B-④ 条目）：统一前缀的缓存命中依赖稳定段先行——跨任务稳定内容（design 通摘/接口签名）在前、任务专属内容（任务卡/变更面摘录）在后；混排则任务差异打断前缀，面值收益折半。