书籍翻译 Agent —— 管理者模式（Orchestration）

源文件：chapter10/book-translation/README.md

实验 10-3：书籍翻译 Agent —— 管理者模式（Orchestration）

配套代码，演示如何用管理者模式把长文档翻译拆给多个专职 Agent。核心是
上下文隔离与控制 Manager 上下文膨胀：Manager 只保存任务、计划、各
Agent 调用记录和文件索引，完整译文全部落盘到文件系统，因此无论书有多长，
Manager 的上下文都基本恒定。

目的

对比「单 Agent 一条对话翻完整本书」与「管理者模式多 Agent 协作」两种方案，用
真实 token 数说明后者如何控制主/Manager 上下文膨胀，并用共享术语表保证
全书术语一致。

架构：四种 Agent

数据流：Manager 调度 Glossary → 逐章 Translation（共享同一份术语表文件）→
Proofreading → Manager 依据报告决定是否把个别章节发回 Translation 修订。译文与
术语表都通过文件系统传递，Manager 只在上下文里保存文件路径。

关键设计：Manager 把「编辑部指定术语」（house style，如 token→词元、
prompt→提示词、latency→时延）强制写入共享术语表，下发给每个 Translation Agent，
从而把指定译法贯彻到全书。单 Agent 看不到术语表，只能用自己的默认译法。

目录

book-translation/
├── agents.py          # 四种 Agent + 两种运行方式 + token 追踪
├── consistency.py     # 术语一致性 / 术语表遵从率（确定性字符串匹配）
├── demo.py            # 一键演示：跑管理者模式 + 单 Agent 对照，打印对比表
├── sample_book/       # 自带英文技术小书（4 个短章节，含术语与代码）
│   ├── chapter1.md ... chapter4.md
├── output/            # 运行时生成：术语表 / 各章译文 / 审校报告（已 gitignore）
├── requirements.txt
└── env.example
​

运行

pip install -r requirements.txt
cp env.example .env      # 填入 OPENAI_API_KEY
python demo.py
​

python demo.py 会先打印四 Agent 协作的实时轨迹（Manager 制定计划 → 调度
Glossary → 逐章 Translation → Proofreading → 依报告决定修订），再打印各 Agent 的
token 消耗与管理者模式 vs 单 Agent 的核心对比表。

• 模型默认 gpt-5.6-luna（当前便宜旗舰），可用 OPENAI_MODEL 覆盖；如需自建/代理端点，设 OPENAI_BASE_URL。
• Key 与通用回退：优先用 OPENAI_API_KEY 直连 OpenAI；若未设置该变量但设了
  OPENROUTER_API_KEY，则自动改走 OpenRouter，并把模型名映射到其命名空间
  （gpt-5.6-luna → openai/gpt-5.6-luna）。提示：gpt-5.6 系列直连 OpenAI 需组织验证，
  只填 OPENROUTER_API_KEY（不填 OPENAI_API_KEY）即可强制走 OpenRouter，更省事。
• 任务规模刻意很小（4 个短章节），一次运行成本约几百分之一美元。
• 不带任何参数运行与旧版行为完全一致。

命令行参数（python demo.py --help）

注意：内置的术语一致性 / 遵从率统计（consistency.py）针对 英文→中文 调校；
改翻译方向仍可正常翻译，但该统计表意义有限。

无 Key / 离线快速查看架构：

python demo.py --dry-run     # 打印四 Agent 协作图 + Manager 计划 + token 预算，不联网
​

该模式用 tiktoken 离线估算各 Agent 会读到的上下文规模，直观印证「Manager 上下文
只随章节数加几行记录、与每章正文长度无关」，而单 Agent 的累积上下文随书长线性膨胀。

token 统计口径

• 子 Agent / 单 Agent 的输入、输出 token 取 OpenAI 返回的真实 usage。
• 「上下文峰值」= 某 Agent 所有调用中，单次输入上下文（prompt tokens）的最大值，
  用来衡量上下文膨胀。
• Manager 上下文峰值：Manager 状态（任务/计划/调用记录/文件索引）序列化后用
  tiktoken 统计的 token 数峰值 —— 它从不包含完整译文。

结论（真实运行结果，gpt-5.6-luna，4 章）

1. 控制上下文膨胀：单 Agent 的主上下文随章节累积，峰值达 2320 tokens；管理者
   模式下 Manager 上下文峰值仅 697 tokens（约 3.3 倍差距）。更重要的是，Manager
   上下文与书的长度基本无关（只加一行调用记录/文件索引），而单 Agent 的累积
   上下文会随章节线性增长——书越长，差距越大。子 Agent 的上下文各自隔离、互不污染
   （每个 Translation 实例峰值仅约 547 tokens）。
2. 术语一致性：管理者模式把编辑部指定术语写入共享术语表并强制下发，4 个指定
   术语在全书的遵从率 100%；单 Agent 看不到术语表，遵从率仅 53%。换用更强
   的 gpt-5.6-luna 后，单 Agent 会自发采用部分「常识译法」（token→词元、
   prompt→提示词都命中了指定译法），但对没有唯一标准的术语仍各行其是（latency 全书
   译成「延迟」而非规定的「时延」，embedding 译成「嵌入」而非「嵌入向量」，各 0/4、
   0/3 遵从）。更关键的是，单 Agent 即便同一个术语也会跨章漂移——token 在部分章
   译成「词元」、另一些章直接留「token」，术语内部一致率因此掉到 89%；管理者模式靠
   共享术语表把这两类问题一起消除（内部一致率 100%、遵从率 100%）。
3. 代价：管理者模式花了明显更多 token（11849 vs 6886，额外的术语表抽取、审校、
   调度调用，且推理模型输出更长），换来的是主上下文可控与术语可强制统一——
   这正是长文档翻译真正需要的性质。

说明：术语一致性用确定性字符串匹配统计（见 consistency.py），不是让模型自评。
具体数字每次运行会有小幅波动，但上述量级与结论稳定复现。

局限

• 上表在 gpt-5.6-luna 上验证；换更强/更弱的模型，两种模式的差距会变化——越强的
  单 Agent 越容易自发命中部分常识译法（遵从率从更弱模型的近 0% 升到本次的 53%），
  但仍无法覆盖没有唯一标准的术语，也仍会跨章漂移，管理者模式的共享术语表始终 100%。
• 样例书刻意做得很小（4 个短章节），目的是清晰暴露机制，不代表大规模真实书籍的
  绝对 token 数值。
• 术语表遵从率、术语一致性都用确定性字符串匹配（consistency.py），不是模型自评，
  可能漏判措辞更灵活的译法变体。
• 每次运行的具体数字会因模型输出的随机性小幅波动（上表为最近一次真实运行结果），
  但量级与结论稳定复现。