子代理并行：大规模任务的分治实践

串行赶不完的活

流水线里有两类任务的量级超出了单个模型会话的舒适区。业务需求生成：一个复杂页面动辄几十个事件函数，每个都要写输入参数表、输出结果、业务规则，全部串行处理，上下文窗口先撑不住，后半段的输出质量肉眼可见地下滑。数据字典精修：几百张业务表、每张几十个字段，十万级的字段描述，串行意味着无限超时。

上下文和超时是两堵墙，并行分治是同时翻越两堵墙的办法：每个子代理只领一小块任务，上下文干净；多个子代理同时干活，墙上的钟不再等某一个模型慢慢想。但并行不是免费的午餐，它引入三个新问题——子代理之间会不会互相踩、任务会不会发丢、结果质量参差怎么办。这一篇的全部设计都在回答这三个问题。

哪些任务适合拆

流水线里用子代理并行的场景有四类，共同特征是「任务可切块、块间无依赖、结果可拼装」：

不适合拆的也有明确判断：模块归类就不拆，几十份 .模块.txt 看似独立，但归类需要全局一致的模块口径，拆开并行必然口径漂移；索引对账更不能拆，它天生就是对全局的汇总。能拆的标准不是「看起来很多」，而是「块之间真的没有共享状态」。

分批上限与失败半径

并行不等于一次性全撒出去。业务需求生成的规则是分批启动子代理，每批最多 5 个，一批全部完成再启动下一批。

上限定在 5，是三个约束的交集。主代理的注意力：同时盯十几个子代理的返回，校验质量必然下降。失败半径：一批里某个子代理跑挂了，重试只损失这一批的等待时间；一次撒二十个，挂掉三个就要重排调度。资源竞争：子代理同时读大文件会放大 I/O 和 token 消耗峰值。数字 5 本身不神秘，重要的是「有上限、批次化」这个纪律。

等整批完成再走下一批，还带来一个隐性好处：每一批的校验结果能立刻反馈进下一批的任务描述——第一批普遍犯的错，第二批的指令里就补上针对性的反面案例，越跑越准。

写冲突规避：独立结果文件

多个子代理绝不允许写同一个文件，这是铁律。实现方式是每组结果写进独立文件，数据字典精修用的是 _result_<组名>.md，文件名即任务边界，一个子代理一个文件，物理上不存在互踩的可能。

所有结果文件由主代理统一合并。合并这一步看似多余，实则必要：格式统一只有合并时才能把关，任何一组的标题层级、表格列数漂移了，都会在合并时暴露；合并后的最终产物只有一个入口，下游消费者不用知道内部是并行生成的。

flowchart TD
    A[主代理 - 按规则分组] --> B[第 1 批: 子代理 1-5]
    B --> R1[独立结果文件 _result_组.md]
    R1 --> C{批次完成 校验}
    C -->|通过| D[第 2 批: 子代理 6-10]
    D --> R2[更多独立结果文件]
    C -->|某子代理不达标| E[退回重写 单个重试]
    E --> C
    R1 --> F[完整性核对 - 结果文件数 = 分组数]
    R2 --> F
    F -->|缺组| G[重新分派缺失组]
    F -->|齐全| H[主代理合并 + 格式统一 + 打印完成标志]

任务描述的模板化

发给子代理的任务描述是模板生成的，每份包含四要素：任务范围（处理哪个功能点或哪组表）、输出格式（从哪个标题层级开始写）、完整规则（含禁令和反面案例）、边界说明（不要写模块标题，那是主代理的事）。

两个细节值得注意。反面案例随任务下发：零合并的违规示例直接嵌进每份任务描述，子代理不用翻阅母文档，单份任务包自包含。输出范围限定到「从功能点名称开始、不含模块标题」：模块标题里的功能点编号由主代理统一分配，子代理如果自作主张编号，合并时必然撞号。任务包的模板化让「发出一百个任务」和「发出一个任务」的质量一致，不靠手写指令的临场发挥。

完整性核对：用数字收拢并行结果

所有批次跑完，主代理先不合并，先对账：结果文件的数量必须等于分组数量。缺哪组补哪组，重新分派只针对缺失部分，不重跑全部。

对账之后还有一遍内容级核对，工具还是输出质量控制一篇里的老三样：Grep 数标题，逐组检查功能点数与任务描述是否一致；查节号连续性，跳号即截断；查格式统一，每组的小节结构必须同构。数字对不上的组打回重写，对得上的才进合并队列。

并行结构里最容易发生「悄悄丢了三个子代理」的事故，每个子代理独立成功或失败，没人天然拥有全局视野。完整性核对就是人为补上的全局视野，它做的是一次减法：分组数减结果文件数，等于零才放行。

主代理的两阶段校验协议

并行放大了质量风险：一个子代理犯的错，乘以并发数就是错误总量。业务需求生成对此设计了最完整的一套协议——主代理对每个子代理的返回做两阶段校验。

阶段一校验输入参数：逐行查合并字段、模糊词、技术词，发现问题整个功能点退回该子代理重写，重写后重新过检。全批输入参数都过了，才进入阶段二：校验输出字段的列名列序、编号格式、输出完整性、业务规则质量。两阶段顺序固定，不许跳过，也不许混在一起查。

分阶段的好处是错误定位精确。输入参数错和输出字段错是两种病，前者的根因在代码阅读，后者的根因在语义翻译，混在一起校验，退回重写的指令必然含糊。分开校验，退回指令能精确到「输入参数第三行是合并字段」，子代理一次就能改对。这套协议加上每 30 秒一次的进度心跳，让主代理对「子代理还活着、干到哪了、质量如何」三个问题永远有答案。

分治的账

并行的收益是速度和上下文健康，成本同样明确：任务描述要花 token，一百个任务就是一百份模板；合并和校验是主代理的串行开销；批次间的等待让最优情况也快不过最慢的子代理。量小的任务走这套流程，开销可能超过收益——三五个功能点的页面直接串行更快。

判断标准回到前文：块数多、块间独立、单块自包含，三条全满足才值得分治。流水线把这套判断也固化成了规则：业务需求按页面规模决定是否启用子代理，数据字典按表数决定分组粒度。并行不是炫技，是量级逼出来的工程选择，选择权最终由数字说了算。

系列最后一篇盘点这条流水线攒下的全部资产，以及它们如何被消费：从逆向到正向：文档资产化的完整闭环。