# 多代理流水线实战经验蒸馏（2026-10-03）

> 来源：上下文管理任务两天接力（10-02 至 10-03），13+ 代理批、多次会话重启、跨会话协调实战。
> 四个角度：编排 / 技术 / UX / 流程。每条都是实战检验过的，非理论推演。

## 一、编排角度

### 1.1 派工颗粒 = 一轮自证
单代理任务必须一轮内带验收证据（命令+结果）回来；超一轮=颗粒过大拆批。实测 13+ 批无一超轮，关键是任务书里给足锚点（文件:行 或 符号名）+ 明确禁改清单 + 验收命令。

### 1.2 文件零交集矩阵
派工前用 grep 把每个子项的**真实落点文件**定位出来（不是按想象的功能域），按文件分组派路：
- 同文件子项 → 合并给同一路（串行在同代理内）
- 跨路文件 → 各自禁改清单写死
- 实测：「结构不符需请示」类中断仅 2 次，均为锚点与实际结构偏差（不是互踩）

### 1.3 双碰文件错峰授权
两路先后都要碰同一文件（如 AiChat.vue）：前路**收口确认后**，主代理向候路代理 SendMessage 显式解锁。不预共享、不口头约定。候路代理遇未授权文件主动请示而非越界。

### 1.4 主代理独立核查三件套
子代理自验 ≠ 完成。主代理必做：
1. **全量测试**：`cargo test --workspace`，与基线计数对比（防「新测试绿了旧测试红了」）
2. **锚点实锤**：报告声称的每个 文件:行号 grep 验证存在且语义吻合
3. **语义抽查**：关键设计裁决读一眼（如「删除侧单点 emit 覆盖 9 出口」——判断是否真比逐处 patch 优）

### 1.5 勘察反转：零命中 ≠ 空白
S2 勘察反转案例：sub_agent.rs grep "approval" 零命中，看起来是「审批语义空白=安全债」；实际是审批以 `deny` 命名的 fail-closed 双层防线（Medium/High 一律就地拒绝）。**「缺失」类结论必须勘察先行再定性**，否则会为伪需求开三批工。

### 1.6 残留进程判活
会话重启后接手：45s 双 stat 观察 mtime 是否推进 + 特征锚点 grep（目标改动是否在增长），确认无活跃写入者再动手。重启通知 ≠ 代理死亡（前代教训）。

## 二、技术角度（代码库层面的可复用裁决）

### 2.1 单点覆盖优于逐处 patch
删除族终态事件：与其在 9 处 loop 早退路径逐个补 emit（每处还要区分「已删」与「接管」），不如在删除侧单点补发——epoch 递增使所有早退路径自然被守卫压制。**先找不变量（owner 守卫），让分支自然消失**。

### 2.2 兼容性设计的「缺席不占位」
tool_signature 补参：补参键不在 args 时签名串与旧格式**逐字一致**——8 处既有逐字断言零破坏。改共享格式前先 grep 逐字断言消费方。

### 2.3 字面任务书会杀人
execute_with_heartbeat「不在 pending 即退出」按字面实现会腰斩**全部已批准执行**（现网先 remove 后 execute）。入口快照（was_pending_at_entry）守卫救场。派工书描述机制时，代理必须先读现场调用方再动手。

### 2.4 测试锁死旧行为的连带改写
修 bug 时若既有测试断言的正是 bug 行为，改写测试是**必要偏离**——但要如实报告（sanitize 盲区修复改写 1 测试）。反例警示：测试与 helper 失配的半成品测试（v21 断点续迁）会带病潜伏。

### 2.5 fail-closed 是底线
子代理 Medium/High 工具一律就地拒绝（零挂起零放行）被证明是正确架构——「拒绝」可以后补结构化与报告协议，但「放行」收不回来。

## 三、UX 走查角度

### 3.1 系统性缺陷按模式全仓 grep
「输入法组词回车直发」不是一个个页面看出来的——grep `isComposing` 全仓零命中 = 系统性缺失，一次修 3 文件。走查先找「某模式全仓缺失」类系统债，收益大于逐页面挑刺。

### 3.2 三域拆分 + 防重复清单
对话/管理/设置三域并行走查，各自带「刚修过清单」（防重复登记）与「已登记清单」（防池子膨胀）。52 项中 P1×8 集中在「事件仲裁（Esc/Enter）、状态反馈缺失、配置静默丢失」三类母题。

### 3.3 UX P1 三母题
- **输入事件仲裁缺失**：IME 组词、Esc 冒泡、快捷键无焦点守卫——同一类
- **操作无反馈**：静默失败、切换无过渡、点击像失灵——同一类
- **配置/状态静默丢失**：探测重拉覆盖用户配置、错误态顶掉可用按钮——同一类
修母题 > 修表象。

## 四、流程角度

### 4.1 唯一等令点
全流程只在 T0（提交+换装）一处等用户令，其余自主流水。攒批规模随每批汇报透出，用户随时可下令。避免频繁请示打断流水。

### 4.2 门禁基线演进
624 → 629 → 631 → 1871（全 workspace）。每批销账记录基线，验收=「不低于基线+新增」。基线漂移即红灯。

### 4.3 攒批分组提交
多批混工作区时（本批+前批+六路），提交须按批分组——主代理维护各批文件清单（进度文件），提交时可机械分组。

### 4.4 进度文件是多会话接力的唯一事实源
两次会话压缩、多次重启，全靠 `temp/*-进度.md` 分段追加接续。写进度=对下代会话交钥匙。