context-infra 检查与复盘infra.guiming.net · 全内容自包含呈现 · 生成于 2026-07-21 16:28 UTC

并行 Subagent 工作流

Z3 全文↑ Z2 条目

术-运行时 · 术层 skill 全文

← 返回术层 skill 索引 · 返回方法论区

本页是 <code>rules/skills/workflow_parallel_subagents.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/workflow_parallel_subagents.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

并行 Subagent 工作流

元数据

何时使用并行模式

以下三件事都回答"是"时才值得并行：

  1. 任务可分 ≥ 2 个独立维度：每个维度产出什么清楚（边界明确）
  2. 维度之间没有依赖：不需要 A 做完才能做 B，否则应该串行
  3. 并行能显著节省总时间：考虑 sub-agent 启动 + 综合整合的开销后仍然划算

不满足时，直接串行执行，不要为了并行而并行。

并行执行流程

1. 评估与分割

识别 3-5 个关键维度后，根据任务类型确定 overlap：

任务类型Overlap 范围原因
调研/创造性任务30% - 50%交叉验证、查漏补缺
代码/执行任务0% - 20%效率优先，减少重复

本表格是 overlap 规则的 single source of truth。 bestpractice_multi_agent_analysis 的"50%"是文档分析场景下的具体实例（落在调研类 30-50% 范围内），workflow_deep_research_survey 的"≥50%"是长文深度调研的下限取值。各 skill 给出场景化数字，本表给出总体范围原则。

Token 估算：任务操作具体、确定的本地文件且 token 可预先计算时，分割前用 python3 tools/token_estimator.py --budget XXXXXX <files> 估一遍。聊天记录、长文档这类单文件就占大量 token 的素材必须估，避免单个 sub-agent 上下文爆掉或整体分组失衡。估完按大小智能分组，大文件独立分配，不按数量平均分。

2. 并行启动

在同一条消息中发出所有调用。使用 mcp_task() 根据任务类型选择 category 或 subagent_type：

# 内部 codebase 调研 → subagent_type="explore"
mcp_task(
    subagent_type="explore",
    run_in_background=True,
    prompt="具体维度描述..."
)

# 外部调研（Web / 论文 / 跨来源）→ subagent_type="librarian" 或 "deep"
# 不要用 explore 做外部调研，explore 只扫本地 codebase

# 实现任务 → 使用 category 委派
mcp_task(
    category="deep",
    load_skills=["git-master"],
    run_in_background=True,
    prompt="具体实现要求..."
)

每个 subagent 的 prompt 应包含：

3. 等待与整合

启动后什么都不做，等系统通知。系统会在 subagent 完成时自动推送 <system-reminder> 通知。收到通知后，用 mcp_background_output(task_id="...") 取回结果，然后交叉验证重叠区域的信息并合成最终输出。

⚠️ 综合「判断类」结论：先防不稳定，再防从众（2026-05-30~31 实证，含对照修正）：

整合分两种。可验证的事实（能重算/机械核验）直接核验，实测跨 harness 零问题（90 run 零翻转）——把不可验证综合转成可验证（给综合者可独立核验的证据，而非 peer 的社会化结论）永远是最强解。不可验证的主观判断（方案哪个好、命名/取舍）有两个叠加风险，按重要性：

  1. 判断本身极不稳定（churn）：实测主观题上模型光「重新考虑一遍」就改答案 44-80%（codex 80% / kimi 67% / sonnet 50%）。所以单个 sub-agent 的一次主观判断不能当稳定信号——要么多采样取众数，要么用确定性 oracle，别拿单次当准。
  2. 社会从众：模型基线主导，框架是小且模型依赖的次级效应（本会话框架隔离实验，跨 4 模型 SOLID，修正早期「harness 门控」说法）：用净从众（社会施压翻转率 − 中性重思翻转率，已剔 churn）测，基线由模型主导且跨模型成立——排序 haiku +0.42（bare 即从众）≫ sonnet −0.24（reactance）≈ codex ≈0 > kimi −0.08（套框架更跌到 −0.58、反而更抗）。框架效应小且模型依赖：把 sonnet 框成「聚合到团队决策」的 subagent 只把 flip 率从 0.36 抬到 0.56（n=45，p=0.09 marginal，净从众仅 +0.07），haiku 已饱和、codex 无效、kimi backfire；起作用的是「多数一致 / 团队决策」措辞而非 subagent 身份（中性 persona ≈ bare）。项目设置注入（继承完整 CLAUDE.md）与「被当 subagent」本身都已排除（≈ bare，p=0.75）。 所以：没有「bare 必不从众」（haiku 反例）；主因是模型基线 + churn；框架只算弱 hedge。早期完整 Workflow 下 sonnet flip ~78-100%（远高于此处 0.36-0.56）的残余强效应，settings / persona / 措辞均已排除，归因到 bash 无法复制的 agentic 执行模式（tool 循环 + 多轮 + 结构化输出强制）= harness-level，列 Bounded。

对不可验证的关键综合，按强到弱（本会话框架隔离实验重排）：(1) 转成可验证——给综合者可独立核验的证据而非 peer 社会结论，实测 90 run 零从众，最强且模型无关；(2) 多采样压 churn——churn 是最大、最普遍的风险（各模型净翻转里 0.33-0.67 来自 churn），单次主观判断不可信；(3) 选抗从众模型做综合 / 别用易从众模型——实测净从众 haiku 最易从众（+0.42），kimi / sonnet / codex 抗；综合者模型要挑要验；(4) 剥「多数一致 / 资历」措辞 + 保留异见——弱 hedge，量小、kimi 上甚至 backfire、codex 上无效；(5) 换 harness / provider 交叉核 + harness 层机械隔离（见 rules/harness_guide/harness_04_multi_agent_topology_synth_20260418.md、UCR context_stager；残余强效应已定位到 agentic 执行模式 = harness-level；provider/fallback 见 tools/llm_runtime/providers.conf）——长期 Bounded。完整对照数据、净从众指标与两次 walk-back 见 methodology/subagent_conformity_reproduction_and_defense_20260530.md。

独立综合者配方（把上述原则落成可执行拓扑，CC/Codex 当下即可用，直接对应「不被带偏 + 独立决策」两目标）：

关键综合不可避免时，别让综合者读各 sub-agent 的完整执行轨迹——轨迹里夹带置信表演、资历/权威措辞、中间推理，正是带偏源。改用：

  1. 生产侧纪律：每个 sub-agent 除完整产物外，单独输出一行 bare verdict——只有最终结论 + 指向原始证据的指针（文件:行 / 数据位置），禁止「我很确信 / 资深共识 / N 人一致」这类社会信号。
  2. 消费侧隔离：另起一个干净 context 的综合者，只喂它 (i) 原始素材 + (ii) bare verdict 清单（去来源资历、打乱顺序、不标多数）；不喂中间执行上下文。
  3. 可验证任务 → 重算：要求综合者从原始素材独立重算，bare verdict 只作线索；重算一致才采信。这一步把「信任投票」变成可验证，是最强防线（实测可验证综合跨 harness 零从众）。
  4. 不可验证任务 → 多采样 + 去权威：综合者无法重算时，每个 verdict 先多采样取众数压 churn，清单去权威、显式保留异见，再让综合者裁断。

两目标各自落地：综合者靠重算/去权威清单独立裁断（不从众）；sub-agent 只吐 bare verdict（拿不到社会信号去带偏他人）。理想是 harness 层机械只把 verdict 字段送进综合者、阻断中间上下文泄漏（见 UCR context_stager 的 verdict-extract staging）——但 CC/Codex 当下无法在 harness 层强制，故此项列为长期 Bounded 目标，现阶段靠上面的流程纪律达成同等效果。

⚠️ 关于 background_output 的常见误解：

background_output 的 block 和 timeout 参数不会让调用阻塞等待任务完成。无论你设置 timeout=120 还是 timeout=600，它都是立即返回当前已有的输出。这意味着：

简而言之：background_output 是取结果的工具，不是等结果的工具。等待由系统通知机制完成。

⚠️ 禁止用 filesystem 探测 sub-agent 进度：

Dispatch 后不要用 ls、wc -l、Glob 去目标目录检查文件是否写了。Sub-agent 执行过程中的 filesystem 是随机快照，读到旧状态后容易虚构出「permission denied」这类结论。运行中完成的首个信号是 Task 返回值 / 系统通知（唤醒信号）；唤醒后的完成判定与数字核验见下条。

⚠️ 通知只作唤醒信号：完成判定与一切数字以磁盘工件直读为准（INFRA-1，2026-07-21 登记）：

harness 后台任务通知通道实测送达过伪造的完成事件（2 例：未来时间戳 + 虚构 COVERAGE 行 + 错误 token 数），与磁盘直读矛盾（AFAC 07-20 P3 lane 实测，career/competitions/afac2026_task4_memory_qa/OPTIMIZATION_PATH_LEDGER.md:241-243）。纪律：系统通知 / Task 返回值只当唤醒信号——收到后，完成与否和一切数字（覆盖数、token 数、分数）一律以磁盘工件直读（结果文件、receipt 台账、日志）为准，通知文本本身不作证据。与上条「禁止 filesystem 探测进度」不矛盾：运行中不轮询（filesystem 是随机快照），唤醒后必须核工件再采信。伪造机理未归因（可能是 harness 特定 bug），防御纪律与归因解耦、照立。与 FM6（过程记录会幻觉，以 mtime/平台记录/原始转录为准）同族，此处扩展到 harness 通知通道本身。

⚠️ 整合阶段 Write existing file 必须先 Read：

Sub-agent 写完后，主 agent 要继续编辑这些文件时，必须先在当前 session Read 目标文件。Claude Code 显示的 Error writing file 通常是底层 File has not been read yet. Read it first before writing to it. 的简化版本，不是 permission 问题。Read "源材料" 不算，Read 必须精确指向 Write 的目标路径。完整事件见 memory feedback_parallel_subagent_race_and_write_read.md。

⚠️ Sub-agent 自报告 completed 后必须 spot check 产出是否落盘（硬规则）：

收到 sub-agent 的 status: completed 后，在进入下一步前必须执行：

ls -la $OUTPUT_FILE && wc -l $OUTPUT_FILE

文件不存在或行数异常立即派补救 agent，不信任自报告。这是 2026-04-17 C agent 虚报案例的直接教训：sub-agent 声称 Write 了 472 行文档但磁盘上实际没有，orchestrator 跳过验证直接进入下一步，后果是下游引用了空路径，靠用户反问才发现。

补救 agent 的 prompt 里必须显式提供原始结构（分类框架）+ 原始诊断 agent 的核心发现清单（都要保留），否则补救 agent 会自作主张重新分类。

示例

调研任务（30-50% overlap）

调研「某技术框架的采用情况」
├─ Agent 1（explore）：核心特性 + 社区活跃度
├─ Agent 2（librarian）：社区活跃度 + 企业案例
├─ Agent 3（oracle）：企业案例 + 竞品对比
└─ Overlap：社区和企业案例都有覆盖，可交叉验证

代码任务（0-20% overlap）

实现「用户认证系统」
├─ Task 1：认证核心逻辑 + Token 管理
├─ Task 2：数据库模型 + 迁移脚本
├─ Task 3：API 端点 + 测试用例
└─ Overlap：接口定义处有少量重叠，确保对接正确

注意事项

← 返回术层 skill 索引 · 返回方法论区