批量仓库与批量任务的组织方式

当任务由大量同构、可独立验证、彼此不强耦合的小单元组成时，串行逐个处理效率低且上下文易污染；批量 fan-out 通过清单驱动与并行隔离提升吞吐。本节讲清两种并行形态、标准组织步骤与适用边界。

一、两种并行组织形态

形态	机制	隔离特点
会话内子代理 fan-out	使用 /batch <instruction> 让主会话把变更拆分给多个子代理，通常为 5–30 个，各自在独立工作副本中工作	上下文独立、改动互不覆盖、由主会话汇总
脚本驱动多会话循环	先生成任务清单文件，再由脚本对每个单元调用一次非交互 claude -p	每个调用独立无状态，易控制授权、失败项与重试

并行会话还可配合独立工作副本（worktree）使不同改动互不干扰；需要跨会话传递发现时，用文件或指定任务作为交换媒介，而非依赖同一会话历史。

二、脚本 fan-out 三步法

1. 生成任务清单：先让代理列出需要处理的对象（如待迁移文件清单）写入清单文件，让后续循环读取，避免在循环逻辑里硬编码对象。
2. 逐单元循环调用：脚本遍历清单，每个单元调用一次 headless 命令，用 --allowedTools 限定本类任务所需工具、用 --permission-mode dontAsk 收敛越界动作，统一提示模板与验收要求。
3. 先小样例再全量：先跑前 2–3 个单元，依据真实报错修正提示词与授权，确认输出格式与稳定性后再铺开全量；失败单元单独记录、择机重试。

三、设计批量任务时的关键要求

• 单元同构且可判定：每个单元的输入、处理规则、成功标准一致，能自动通过测试/检查判定，适合自动 fan-out。
• 统一验收命令：每个处理单元自带最小验证；整体结束后再跑全量构建/测试，确认并行改动没有相互破坏。
• 结果可汇总：统一输出字段（OK/FAIL、改动对象、原因、证据），便于脚本聚合、去重与生成汇总报告。
• 隔离降低偏见：写作者与审查者使用不同会话/子代理；审查在新鲜上下文进行，比作者自查更能发现边界与遗漏。

四、适用与不适用清单

适合批量并行	不适合批量并行
大批量文件的规则化迁移、格式统一、补齐说明文档	强耦合、需要全局协调与统一设计的改动
跨多文件的相似搜索与分析并汇总结论	依赖视觉确认、需人工操作界面的功能
按固定模板生成审查建议、测试草稿	架构选型、兼容性风险高的不可逆变更

五、成本、收敛与最终把关

• 并行会成倍消耗上下文与运行时间，按机器并发能力分批，避免资源争抢；优先短而明确的单元。
• 每个子调用应自带停止条件与验收信号；主汇总环节负责合并冲突、去重与完整性核对。
• 批量产出不等于质量完成：全量测试、构建与关键 diff 的人工复核仍是最终把关，尤其涉及公共行为与边界条件时。

六、脚本 fan-out 的最小组织思路

脚本驱动多会话适合单元同构、结果可判定的场景，组织上遵循"清单驱动、模板统一、结果结构化、失败可重试"四原则，不依赖特定脚本框架：

1. 清单先行：把待处理对象（文件、模块、条目）写入清单文件，脚本逐条读取，避免把对象列表硬编码进循环逻辑。
2. 统一提示模板：每个单元复用同一份任务说明、成功标准与输出格式；对象名作为变量替换，保证各单元处理口径一致。
3. 收敛授权：非交互调用用 --allowedTools 限定本类任务所需工具，用 --permission-mode dontAsk 拒绝一切待批准动作；只读分析类任务不授予写权限。
4. 结构化结果：每个单元输出统一字段（对象标识、状态 OK/FAIL、改动摘要、证据或失败原因）；需要机器汇总时可用 JSON 输出格式读取结果，需要逐行事件时可用流式事件输出，具体输出格式以当前版本官方文档为准。
5. 小样先行、失败隔离：先跑 2–3 个单元验证提示与授权，再全量；失败单元单独记录、单独重试，不让一个失败中断整批。
6. 汇总与把关：脚本聚合成功/失败清单，主会话或人工做合并、去重、冲突核对与全量回归。

七、FAQ

问题	处理建议
哪些任务不该 fan-out	强耦合、需统一架构决策、依赖界面人工确认或不可逆高风险变更不适合并行批量；这类任务串行推进并由人把关。
并行单元改到同一文件互相覆盖	让各单元在独立工作副本中工作，或按文件归属拆分批次；主汇总阶段统一合并，禁止多个写者直接并发改同一文件。
批量跑完测试发现格式不统一	说明模板缺少统一约束；补充输出格式与命名规则后重跑失败单元，不要手工逐个修补掩盖模板缺陷。
如何控制批量运行的上下文与时间成本	单元尽量短而明确、自带停止条件；按机器并发能力分批；优先只读分析类批量，写操作类批量缩小批次并加强复核。
会话内 /batch 与脚本循环如何选择	需要多个子代理在独立工作副本并行变更、由主会话汇总时用会话内批量拆分；需要无状态、可重试、结果易聚合的流水线时用脚本循环调用非交互命令。

八、动手练习

• 练习 1：选 5–8 个结构相似的文件，先手工处理 1 个沉淀统一提示模板，再按"清单 + 模板 + 结果字段"组织批量处理，最后用全量检查验证一致性。
• 练习 2：为一批只读分析任务设计结果汇总表（对象、结论、证据位置、置信度/待确认项），练习把并行结论收敛成一份可决策的汇总报告。