fable-delegate

Fable Delegate

仅当确实存在独立性时才使用并行工作者，不要仅仅因为任务不止一个就使用。

使命

委派工作应缩短延迟，而不是增加歧义。父级仍负责任务分解、契约稳定性、集成和最终验证。

工作者不是用来倾倒上下文的地方。它应接收一项边界明确的职责，以及足够的证据，使其能够独立行动；还应有一份返回契约，让集成过程便于审查。

适用情形

• 两个或更多任务卡可以独立推进，无需等待彼此的决策；
• 专业视角可以并行调查相互独立的假设；
• 不同组件具有稳定的接口和独立的验收检查；
• 独立审查或研究可以并行开展，且不会产生共同修改。

不适用情形

• 多个工作者会修改同一项尚不稳定的契约或不变量；
• 一张任务卡的设计结果会改变另一张任务卡的需求；
• 一项小任务的说明和集成成本高于直接执行成本；
• 父级尚未掌握足够上下文，无法编写精确的工作者契约；
• 所有工作者都依赖同一个尚未解决的架构决策。

独立性分类

对于每一对候选任务，判断其耦合程度：

耦合	并行？	原因
不同文件 + 不同契约	通常可以	语义重叠较少
不同文件 + 共享的不稳定契约	不可以	即使路径分离，仍存在语义冲突
同一个集成文件 + 独立组件	视情况而定，但集成应串行进行	组件工作可以并行；集成不可以
共享只读证据	可以	不存在所有权冲突
相同的数据库架构／不变量	通常不可以	一个工作者可能使另一个工作者的假设失效
独立的研究假设	可以	合并结论，而非源代码修改
两者都需要父级决策	不可以	先解决决策

委派流程

阶段 1 — 确认独立性

检查：

• 写入所有权；
• 共享契约／不变量；
• 依赖顺序；
• 生成的工件；
• 迁移／状态耦合；
• 集成瓶颈；
• 一个工作者失败是否会改变另一个工作者的假设。

如果无法用一小段话说明独立性，就先不要并行处理。

阶段 2 — 编写工作者契约

每份契约都应包括：

• 目标；
• 已确认的上下文／证据；
• 负责的路径或语义范围；
• 禁止涉及的范围；
• 假定稳定的依赖项；
• 需要提供的验收证据；
• 预期返回内容；
• 停止／升级处理的条件。

不要只让工作者“处理 X”，却把整个代码库交给它，而且不设边界。

阶段 3 — 确定修改所有权

优先为每个语义范围指定一名写入者。多名只读调查者可以查看重叠的文件；多个写入者不应各自重新定义同一份契约。

对于共享的集成文件，应由父级负责集成，或在组件工作汇合后指定一名工作者负责。

阶段 4 — 派发并按异常情况监督

不要事无巨细地干预每条命令。出现以下情况时再介入：

• 工作者发现了会影响整体的未知事项；
• 需要扩大负责范围；
• 无法满足验收要求；
• 契约假设不成立；
• 工作者停滞／反复失败。

阶段 5 — 检查返回内容，而不只看摘要

要求提供具体产物：差异／路径、命令／结果、证据、未解决的风险。仅以文字表示“已完成”并不能作为集成证据。

阶段 6 — 集中集成

父级检查：

• 合并后的差异；
• 契约兼容性；
• 跨工作者行为；
• 生成的工件；
• 集成测试；
• 合并／集成修改后，工作者本地提供的证据是否仍然有效。

决策规则

• 不同文件既非独立性的必要条件，也非充分条件。
• 契约稳定且实现隔离时，可以并行；契约不稳定时，即使文件分开也不应并行。
• 如果工作者提出相互竞争的方案，在父级作出选择前，应让这些方案保持只读；不要盲目合并两种实验方案。
• 如果工作者需要跨越所有权边界，应暂停该工作者并重新协商契约，而不是悄悄扩大范围。
• 工作者失败或卡住，并不意味着应该自动用同一提示词重新运行；应先判断失败类型，再将任务卡交给 fable-recover 或在本地执行。
• 只要委派工作影响了某项用户可见行为，就必须进行父级集成验证。

不变条件

• 每个可变部分都有明确的所有权。
• 工作者只获得作出其有限范围内决策所需的上下文。
• 工作者完成工作不等于全局完成。
• 共享契约的变更由一名集成负责人负责。
• 所有集成修改完成后，必须验证组合后的工作区。

失败分类

所有权冲突

两名工作者需要修改同一个可变契约或文件。停止并行修改，重新规划所有权。

语义冲突

文件不同，但都更改了同一个不变条件或架构。应将其视为耦合工作。

上下文不足

工作者反复询问本应由父级解决的问题。完善契约，或将任务退回发现／规划阶段。

范围越界

工作者发现所有权范围之外的必要工作。暂停任务，评估后再明确扩展范围或重新规划。

工作者本地通过／集成失败

本地检查通过，但组合后的行为失败。由父级负责诊断；不要盲目地将问题推回给工作者。

工作者停滞

没有实质进展或反复失败。应终止或恢复任务，而不是无限消耗预算。

反模式

• “两个任务 = 两个 Agent”；
• 仅以路径不重叠作为并行判断标准；
• 将整个宽泛任务交给每位工作者；
• 允许每位工作者独立更新共享清单／路由；
• 不查看差异／证据就接受文字摘要；
• 未检查假设就合并工作者的输出；
• 认为子 Agent 会替父级承担责任；
• 仅仅为了回避决策，就委派父级尚未作出的决策。

强制 TOON 委派协议

所有子 Agent 委派契约和工作者返回数据包都必须使用 TOON（Token-Oriented Object Notation）。这可确保：

1. 节省 Token：与冗长的 Markdown／JSON 相比，Token 数量减少 35-70%。
2. 确定性解析：显式长度标签 [N] 让父级 Agent 能立即检测任务是否被截断或遗漏。
3. 结构化架构：字段标头 {fields} 确保遵守契约。

Boss → Worker 委派契约（TOON）

contract:
  workerId: worker-1
  targetCard: CARD-101
  objective: "Implement JWT authentication guard"
ownedPaths[2]: src/auth/guard.ts,test/auth/guard.test.ts
forbiddenPaths[2]: src/config/keys.ts,.env
acceptanceChecks[2]: "bun test test/auth/guard.test.ts","bun run typecheck"
rules[2]: "Do not touch files outside ownedPaths","Use TOON format for the return packet"

Worker → Boss 返回数据包（TOON）

result:
  workerId: worker-1
  targetCard: CARD-101
  status: complete
  allChecksPassed: true
mutations[2]{path,action}:
  src/auth/guard.ts,modified
  test/auth/guard.test.ts,created
verifications[2]{command,result,durationMs}:
  "bun test test/auth/guard.test.ts",pass,120
  "bun run typecheck",pass,340
notes[1]: Successfully implemented guard with full test coverage

完成标准

满足以下条件时，委派才算完成：

• 每份工作者契约都明确规定了所有权和验收标准；
• 已检查返回的产物／证据；
• 所有权／契约冲突均已解决；
• 当前工作区中的组合差异通过了集成验证；
• 对剩余失败均已明确安排后续处理，而非在工作者摘要中隐瞒。

延伸资源

• 深入指南：references/parallelism-and-integration.md
• 现有契约指南：references/subagent-contracts.md
• 模板：templates/delegation-contract.template.md
• 示例：examples/parallel-workers-walkthrough.md