★ FEATURED ARTICLE AI 应用NLPCLI【免费下载链接】bilingual_book_makerMake bilingual epub books Using AI translate项目地址https://gitcode.com/gh_mirrors/bi/bilingual_book_maker点击查看免费下载本篇文章聚焦 bilingual_book_maker 的 plan 模式bbm-plan 技能下一阶段的核心设计——Book Brief书籍简报 Glossary术语表静态上下文注入方案。该方案针对--parallel-workers并行翻译时人名、地名等专有名词前后译法漂移的问题提出一次计算、处处注入的并行安全上下文机制。读完本文你将掌握该设计的动机、sidecar 文件格式、名称挖掘策略、两条注入路线prompt.json零改动路线与--book-brief一等公民路线以及分阶段实施路线图并能结合仓库源码理解其与--use_context、--prompt、plan JSON 校验体系的衔接方式。本文所依据的设计文档位于仓库 .agents/skills/bbm-plan/references/next-phase.md其状态标注为planned, not built已设计、尚未实现设计日期 2026-08-05。文中涉及的全部仓库源码均为当前已实现内容用于印证设计所依赖的现有机制设计本身属于路线图性质实现细节以文档为准。一、问题背景顺序上下文的代价与并行化的瓶颈bbm-plan 技能见 .agents/skills/bbm-plan/SKILL.md的核心工作流是plan贪心分区 agent 人工分类→ smoke廉价冒烟→ full完整可续跑三步。其中术语一致性依赖一个关键开关--use_context。从 book_maker/cli.py 第 424-428 行的参数定义可以看到其机制--use_context adds an additional paragraph for global, updating historical context of the story to the models input, improving the narrative consistency for the AI model (this uses ~200 more tokens each time)也就是说--use_context会把全局累积的历史上下文段落追加到每个请求里让模型记住前面章节已经确定的人名、地名译法。这正是 SKILL.md 中consistency一行的选择依据fiction with recurring names/terms; costs extra tokens。但它的代价同样写在该行里in parallel runs context is chapter-local (until the phase-2 brief exists)。原因在于--use_context的上下文是顺序累积的——每个请求都要基于前一个请求的翻译结果生成新上下文而--parallel-workers Ncli.py 第 479-484 行默认 1建议 2-4会把各章节同时派发出去并行场景下每个 worker 只能拿到章节局部上下文per-chapter translator clones无法共享全局的历史信息。结果是并行快了但名字和术语的一致性只能靠模型自身能力维持顺序能保持一致但整个流程被串行化。这就是设计文档要解决的核心矛盾。二、方案总览Book Brief——静态共享上下文设计的核心洞察是把上下文从运行时的顺序状态变成翻译前一次性计算好的静态数据。具体来说在翻译开始之前先为整本书生成一份Book Brief书籍简报然后把它注入到每一个翻译请求中。这样所有并行 worker 获得完全相同的共享上下文并行安全由构造保证parallel-safe by construction——不存在竞态或先后依赖不需要预热no warmup不需要处理克隆cloning subtleties这类实现细节。Book Brief 由两部分组成部分内容说明Intro引言2-4 句对这本书的概述书名、体裁、时代背景、语言风格registerGlossary术语表全书出现频率最高的约 20 个专有名词人物、地名及其固定目标语言译法在翻译开始前一次性确定后续所有请求共用引言与术语表的信息来源Intro 的信息来源是前言preface/ 扉页title page/ 第一章first chapter——具体取哪一处由执行 agent 自行判断设计文档特别指出plan JSON 里的 samples 通常已经包含了足够的信息不必额外翻书。Glossary 则来自名称挖掘name mining详见下文第四节。谁来起草分类阶段的顺带产出两份内容都由coding agent编码智能体在既有的classify 交接环节SKILL.md 第 3 步起草。设计文档给出的理由非常务实agent 在这个阶段本来就要阅读每个 signature 的 samples此时顺手做名称挖掘几乎是零边际成本nearly free。用户审核/编辑 brief 的方式与审核 plan 中每个 action 的方式完全一致——同一个工作流同一个审核心智模型。三、Sidecar 文件格式book_brief.json设计采用**旁车文件sidecar**方案brief 不写进 plan JSON而是作为独立文件与 plan 并存路径就在 plan 旁边。{ language: zh-hans, intro: This is a historical novel set in early 19th-century France..., glossary: { Napoleon: 拿破仑, Marseille: 马赛, Dantès: 唐泰斯 } }三个字段各司其职language目标语言与--language保持一致供 agent 起草译法时参照intro注入每个请求的书籍概述glossary专有名词原文 → 固定译法的映射键是原文拼写值是目标语言译法。选择 sidecar 而非并入 plan JSON 的原因可以从 plan JSON 的现有结构推断plan JSON见 book_maker/loader/plan.py 的TranslationPlan.to_dict第 775-821 行承载的是schema_version、coverage、signatures每行的signature/units/chars/pct/mean_chars/samples/action以及用于校验的book_sha256。它是一份分区与判定契约与术语上下文是两种不同生命周期、不同审核粒度的数据拆开存放更清晰也避免污染既有的 fail-closed 校验逻辑。与 plan 校验体系的一致性预期值得一提的推断plan JSON 的加载是fail-closed默认拒绝的——load_plan_overridesplan.py 第 843-931 行会对缺失book_sha256、哈希不匹配、schema 版本不一致、非法 action、残留 null action 等情形逐一硬报错。设计文档在第 3 步实施清单中明确要求--book-brief的校验采用like the plan sidecar与 plan 相同的 fail-closed 风格即brief 文件损坏或 schema 不合法时翻译必须拒绝启动而不是静默降级。四、名称挖掘Name Mining频率排序 agent 人工修剪Glossary 的候选词从哪来设计给出的算法骨架是在分区后的所有单元文本partitions unit texts上扫描重复出现的大写 tokenrecurring capitalized tokens按出现频率降序排序取前约 20 个作为候选由 agent 人工修剪误报false positives并逐个确定目标语言译法。设计文档特别强调最后一步的不可替代性音译transliteration还是采用既有通行译法established translation这是一个判断问题judgment call——这正是交给 agent 而不是正则表达式regex的原因。同一个词在不同语境下可能有不同的惯用译名纯规则无法可靠决策。已知局限高屈折语言的过生成设计文档在诚实局限一节明确警告对高度屈折变化heavily inflected的语言——例如拉丁语、梵语这类词形变化丰富的古代语言——名称挖掘会过度生成over-generate同一个专有名词会因为主格、属格、宾格等不同词形被识别成多个不同的 token。此时 agent 的修剪步骤是承重墙load-bearing——没有人工修剪候选词表会被同一名字的多个变体撑爆术语表质量急剧下降。这是该方案适用边界的真实刻画而非缺陷掩饰。五、注入路线 v2.0零仓库改动方案通过--prompt设计的第一个落地路线刻意追求最小侵入不修改 bilingual_book_maker 仓库任何代码。实现机制技能侧skill-side把 Book Brief 渲染进一个prompt.json的system message运行时通过--prompt prompt.json传入现有代码无需任何改动即可工作。为什么现有代码就能支持两条证据链证据一--prompt的文件契约。从 book_maker/cli.py 的parse_prompt_arg第 20-111 行看JSON 格式的 prompt 文件只允许两个键user必填用户模板必须包含字面占位符{text}{language}可选system可选系统消息。任何其他键都会被直接拒绝prompt can only contain the keys of user and system。也就是说brief 的 intro 和 glossary 恰好可以合法地放进system键而user模板保持逐单元发送的翻译指令不变。这正是设计文档断言custom system message 可流入的契约基础。补充--prompt还支持.txt作为 user 模板原文和.md按 PromptDown 解析可提取 developer/system message 与 conversation见parse_prompt_arg第 26-64 行以及直接传 JSON 字符串第 78-85 行。证据二sys_content的两条结构化路径。设计文档明确指出chatgptapi_translator.py在单条路径和 batch 结构化路径两条路径上都从prompt_sys_msg构建sys_content。在 book_maker/translator/chatgptapi_translator.py 中可以找到两处同构代码第 589 行sys_content self.system_content or self.prompt_sys_msg.format(crlf\n)单条路径第 973 行同一条表达式batch 结构化路径prompt_sys_msg在构造器第 284、301-302 行中接收并保存。也就是说只要把 brief 渲染进 system message 并传入--prompt无论走单条还是批量结构化路径模型都会在每个请求里看到同一份 brief——并行 worker 因此获得一致的共享上下文。成本核算设计文档给出的估算一个 20 名词的术语表每个请求大约增加~200 tokens的开销。与每请求实际翻译的正文 token 相比这只是噪音noise next to the text being translated。这个数字与--use_context的文档标注约 200 tokens/次cli.py 第 427 行量级一致可作为成本参考。六、注入路线 v2.1一等公民--book-brief标志升级项v2.0 路线有一个结构性缺陷brief 占用了用户的--prompt——如果用户自己已经用--prompt定制了翻译风格例如 SKILL.md 中voice/style一行的--prompt prompt.json用法brief 就没有地方放了两者会发生冲突collision。v2.1 的解法是在 bbm 仓库中新增一个一等公民first-class标志--book-brief path它的三个关键设计约束schema 校验brief 文件按既定 schema 校验损坏即 fail-closed与 plan sidecar 一致组合而非占用brief 与用户自己的--prompt并存composed alongside各自注入而不是互相顶替升级项而非前置条件文档明确标注 Upgrade, not prerequisite——v2.0 的prompt.json注入在任何仓库版本下都可用--book-brief只是把这条路径变成正式接口不阻塞早期采用。七、并行收益--parallel-workers默认化设计文档给出的终局形态brief 就位后大书large books的完整运行可以默认--parallel-workers N同时关掉--use_context。这意味着 bbm-plan 技能在两种模式之间完成了一次根本性切换维度现状--use_context目标Book Brief 并行上下文来源运行时顺序累积的历史段落翻译前静态计算的书籍简报并行安全性章节局部上下文并行时失效所有 worker 同一份共享上下文上下文开销~200 tokens/请求随进度增长~200 tokens/请求恒定不变停止/续跑语义受顺序累积影响与并行 pool 兼容结合 SKILL.md 的说明当前 plan 模式之所以能安全并行是因为plan mode isolates per-chapter state每个章节状态隔离brief 补齐了并行时全局术语一致性这块短板让并行 一致同时成立。八、诚实局限设计者的自我约束这一节是文档最有价值的部分之一——设计者明确划定了不做的事防止方案被过度工程化1. Glossary 是建议性的不是强制性的prompt 注入的术语表本质上是advisory建议性的——模型仍然可能偏离术语表中的既定译法。真正的强制需要事后检查post-check扫描输出中是否出现了未按 glossary 译出的专有名词unglossed renderings。设计文档给出的决策准则是Do not build enforcement speculatively.不要投机性地预先构建强制机制。事后检查脚本只有在实际观察到漂移drift之后才值得写属于更晚的迭代later iteration。这是一条明确的按需建设纪律没有实测证据之前不为想象中的问题付工程成本。2. 高屈折语言的过生成如前文第四节所述拉丁语、梵语类来源会让名称挖掘过度生成agent 修剪步骤是承重墙。3. 状态定位文档开头即声明本方案planned, not builtPhase 1SKILL.md 本身必须先在真实使用中赚回它的位置earning its keep——即先验证既有工作流确实被采纳、确实产生价值再投入 Phase 2。这是一种务实的路线图排序。九、实施步骤路线图设计文档给出了明确的分步实施清单when picked up第 1 步技能侧改造skill-side在 classify 步骤中加入 brief 起草指令agent 在阅读 samples 时顺带产出 intro glossary实现 brief →prompt.json的渲染逻辑v2.0 路线大书默认开启--parallel-workers。第 2 步A/B 冒烟验证A/B smoke用相同的 2 个章节分别做带 brief与不带 brief的翻译肉眼检查跨章节边界chapter boundary处的人名一致性差异这是成本最低的实证手段与 bbm-plan 既有的 smoke test 文化一脉相承SKILL.md 第 4 步先花几分钱验证再投入完整运行。第 3 步按需补建conditional仅当实际观察到漂移drift时才编写 post-check 脚本仅当--prompt冲突真实困扰了用户才实现--book-brief仓库标志含测试与 plan sidecar 同款的 fail-closed 校验。注意最后一条的措辞--book-brief的实现不是v2.0 的前置条件而是以真实用户痛点prompt 冲突作为触发条件。这与禁止投机性建设的原则完全一致——每个增量功能都有明确的、来自真实使用的触发信号。十、与现有 bbm-plan 工作流的衔接从 .agents/skills/bbm-plan/SKILL.md 的完整工作流credentials → intake → endpoint probe → plan → classify → smoke → full run → deliver看brief 机制插入的位置非常自然plan 阶段--plan-classify agent生成book_plan.jsonsignature 行带samples、units、chars、pct、mean_chars、actionnull 表示待裁决见 classify/agent.py 第 36-43 行的行字段说明classify 阶段agent 逐个裁决 null action 的同时顺带起草 brief名称挖掘基于每个 signature 的 samples与裁决共用同一份阅读工作注入阶段brief 渲染进prompt.json的 system message随--prompt注入每个请求v2.0或通过--book-brief与用户自定义--prompt并存v2.1运行阶段大书默认--parallel-workers N关闭--use_context交付阶段与现有 deliver 流程一致覆盖/跳过统计、分类决策报告、book_bilingual.epub交付。关于 prompt 文件的 git 卫生references/prompt-files.md 已有明确约定prompt 文件属于用户个人声音常含角色名或术语内容应与.env同等待遇——通过git check-ignore检查并加入.git/info/exclude绝不修改项目追踪的.gitignore。brief 文件含 glossary 内容显然也应遵循同样的卫生规则且该文档还提醒了一个成本细节user模板在每个单元请求中都会发送其中的每个词都要为整本书的每个请求付费——因此风格指令应放在system消息中一次说清而不是在user模板里逐段落重复。brief 注入遵循的正是这一原则。十一、总结Book Brief 方案解决的是一个精确的工程问题在保持--parallel-workers并行速度的同时恢复只有顺序上下文才能提供的术语一致性。其核心方法论值得借鉴把上下文从运行时状态变成静态数据——一次计算、处处注入并行安全由构造保证让最贵的人工判断发生在最便宜的时机——名称挖掘搭 classify 阶段的便车agent 的阅读工作零额外成本复用用注入而非强制解决问题——glossary 是建议性的强制手段按需建设没有漂移证据就不写 post-check升级路径清晰——v2.0 零仓库改动先用起来v2.1 一等公民标志按真实痛点再落地绝不投机性建设。对于正在使用 bbm-plan 翻译小说类 EPUB 的读者本文的实用价值在于理解--use_context与--parallel-workers当前的行为边界cli.py 的--use_context帮助文本与 SKILL.md 的 flag guide 是最直接的依据并预见到下一阶段方案落地后并行 一致两全的运行形态。该设计当前仍处于 planned 状态实现与否、何时实现取决于 Phase 1 技能在真实使用中的表现——这是仓库自身的演进节奏而非本文可以承诺的内容。赞分享AI 应用NLPCLI【免费下载链接】bilingual_book_makerMake bilingual epub books Using AI translate项目地址https://gitcode.com/gh_mirrors/bi/bilingual_book_maker点击查看免费下载相关推荐LobeHub 术语翻译对照与国际化一致性实践Glossary 参考、约定与自动化校验LobeHub 术语翻译对照与国际化一致性实践Glossary 参考、约定与自动化校验 LobeHub 是一个把 AI 团队编排为 7×24 运营的智能体平台人工智能AI 应用大模型AI Agent多智能体工具调用前端后端CMake文档本地化术语统一技术术语翻译一致性保障方案CMake文档本地化术语统一技术术语翻译一致性保障方案 引言多语言协作中的术语困境 在开源项目本地化过程中技术术语翻译不一致是困扰开发者和翻译者的常见痛点文档突破 EPUB 翻译瓶颈bilingual_book_maker 错误全景分析与解决方案突破 EPUB 翻译瓶颈bilingual_book_maker 错误全景分析与解决方案 在数字化阅读时代EPUB电子出版物已成为跨平台内容分发的标准格AI 应用NLPCLI上一篇【亲测免费】 推荐项目Point·E——3D点云生成系统下一篇深入解析 Espresso运行在宿主 JVM 之上的 GraalVM Java 虚拟机实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
