流程持久契约

本页记录维护者需要保持的持久流程行为，不作为发布历史或内部字段清单。 用户阶段和取舍见流程指南，格式保留规则见 格式参考，包所有者与依赖边界见架构。

所有权与执行

Orchestrator 是准备、翻译、注释、Review、Autofix 和收尾服务之上的薄 façade。 Runtime 提供配置、冻结语言计划、存储及一个路由模型客户端。 领域服务拥有自己的并发和检查点；agent 不拥有流程状态，也不选择 provider。

并发结果必须按稳定输入顺序归并，不能让完成顺序改变章节内容、初稿身份、 注释、术语顺序或 Review 结果。模型路由、校验和推理身份使用统一操作注册表。 传输重试由共享层负责；关闭 SDK 内置重试，不在外侧叠加重复重试循环。

初始化与原文身份

解析完成与翻译初始化完成是不同状态。

• parsed_document.json 将原文哈希、解析配置与仅含原文的文档绑定。 它支持 AI 准备前及准备失败后的只读预览，不授权编辑暂存译文，也不表示 manifest 已提交。
• 初始化先建立原文身份、暂存章节和语言策略产物，再生成必需的章节梗概及文风分析， 最后提交已初始化的 manifest。全书概览在初始化之后生成， 不是初始化成功的必要条件。
• manifest 绑定 source_sha256、源语言和目标语言。 不同内容不能因文件名或书名相同而续跑；解析和导出前后的哈希检查检测期间的原文替换。
• 重试保留兼容的原文解析、完整章节梗概、已付费文风分析及累计用量。 缺少某阶段不能成为重置它们的理由。未完成章节内部的摘要分块不逐块保存检查点。

开启全书理解时，每个非空章节都需完整梗概才能开始正文。 任一原文块或归并失败都不得发布局部章节梗概。 全书概览的任一组失败会使整个概览失效；保留下来的旧分析不能作为当前有效概览注入。 准备阶段从不抽取或预建术语。

稳定状态与翻译检查点

target is None 表示待译。保存的空字符串可能是 MinerU 有意完成的译文， 不得用真假判断决定是否重译。导出时回退原文是独立决策，不能反写正式 target。

保留章节索引、片段索引、续段边界、EPUB/HTML 锚点与注释 ID、DOCX 样式元数据、 babeldoc_id。批次拆分、续跑、Review 和导出均不能改变这些身份。 只在需要完整逻辑段落的操作中回并长段续段，再将结果映射回原有稳定片段。

每个正文批次：

1. 冻结原文、完整有序术语库及实际使用的上下文。
2. 翻译并按需润色，发布前校验结构。
3. 保存正式译文，再对齐注释／样式。
4. 从已完成原译文对抽取术语，并保存抽取检查点。
5. 术语变化后，在下一待译批次前刷新快照。

已有完整 target 但缺少术语检查点的批次需要补抽取，不需要重译。 检查点齐全则两者都跳过。章节完成状态在所需批次和章级工作完成后发布。 译文保存、对齐与术语检查点之间都应保留中断恢复测试。

最近上下文按全书顺序从正式译文重建，不另存滚动上下文字符串。 遇待译片段停止，跳过有意保存的空译文。 后文参考是只读原文邻居，不属于编号输入或输出段数。 BabelDOC 的角色／章节边界进一步限制正文上下文，但不能删除非正文翻译单元。

全量术语库拥有名称映射，条目保持稳定插入顺序，新 Reviewer 请求共享最终完整快照。 选择性取证和 Fixer 可以使用相关子集。 日文读音是有明确原文依据的源语言元数据，不是目标语言音译； 非日文来源的结构化术语渲染不注入该字段。

实验性术语证据同时要求配置开启和操作级授权。 只有获准的 CLI 准备／翻译入口授予生产权限，准备本身仍不抽取术语； 普通 Runtime/API 调用方不能仅凭 YAML 获取权限。 人物证据在所需组完整成功后发布，绑定当前词条身份， 保留受保护人工字段和权威名称映射。

Storage、Artifact 与锁

领域流程通过 Storage 和 ArtifactStorage 持久化可变状态， 不得从 artifact key 推断本地文件语义，也不得直接打开数据库绕过注入的适配器。

适配器	状态所有权
CLI 文件存储	按目标语言隔离的章节／分析／账本文件及本地术语库
Desktop SQLite	独立项目数据库与工作区，不迁移 CLI/Web 状态
Web PostgreSQL	按项目隔离的可变状态；上传／缓存／导出目录不是 JSON 或 SQLite 状态镜像

Artifact key 在所有后端都使用运行内相对路径和 / 分隔符。 前缀查询限制在相关子树，避免扫描无关原文缓存。 精翻档案、语言计划和 Review 轨迹属于产物，不是可跨平台复用的绝对文件路径。 Storage 中路径形态的身份属性不授权领域层绕过端口写文件。

保持以下锁职责：

• 书级运行锁串行化长时间修改流程及恢复。
• 短状态锁／事务保护一致读写和日志准备。
• 事件追加与产物组装使用各自专用同步。
• 独立导出在短锁下获取一致 manifest／章节快照，渲染期间不持有长翻译锁。

文件 JSON 使用同目录临时文件和原子替换发布；SQL 适配器提供对应的事务及锁契约。 内存更新成功不等于持久提交。存储所有者在成功和失败路径都关闭资源。 独立本地 Review 读取包含已提交 WAL 数据的术语快照，不修改正式术语数据库。

缓存身份与失效

命中缓存表示实际输入及语义契约仍兼容，而非“文件存在”。 其他阶段失败时保留成功记录，绝不能把诊断产物当成成功结果。

缓存工作	需要绑定的输入
原文解析	原文内容与解析配置
章节梗概／文风／全书概览	实际原文或摘要、任务策略、模型配置；概览还绑定实际使用的指导信息
精翻	原文和稳定片段计划、上下文、术语、翻译策略与有效推理身份
注释／样式定位	完整逻辑段落的目标摘要及原始条目身份
Review	被审内容、含全部元数据的有序完整术语库、指导信息、策略、Review 选项及可达推理身份
术语请求	词条／原文身份、精确请求输入、策略和路由；发布前重新检查当前词条身份

流程提供有效操作快照时，只绑定适用的推理输入。 例如，无关路由或纯并发变化不应使 Review 失效。 模型、端点、实际选项或语义提示词变化可能确实需要重新请求； 派生缓存不兼容不意味着自动丢弃完成的正式译文。

无效 provider／JSON／语义响应是失败，不是“没有证据”的缓存。 成功校验但无法支持映射的响应不同：历史术语对齐可以为精确请求缓存这种未决结论， 不重复调用或诊断。不得用缓存中的不确定性覆盖人工术语决定。

精翻检查点与回执

精翻执行器拥有三份独立并发初稿及一次综合润色； 只有章节服务负责发布最终 target。启动各分支前冻结共享原文／上下文前缀， 按 T1/T2/T3 顺序汇合，而非完成时间。 target_before_polish 保存 T1，target 保存综合润色结果。

批次指纹绑定原文哈希、稳定片段计划、上下文、术语、语言策略，以及 translation.body／polish.body 的有效推理身份。 逐阶段检查点和完成调用回执支持在“调用成功但上层检查点未写入”时恢复。 一个初稿失败时仍保留其他成功分支。

严格校验输出数量、字符串类型和允许空译文的策略。 不需翻译的输入保留原文。每个失败初稿或综合润色拥有一次初始尝试加 align_retry_limit 次输出重试：结构错误追加被拒回复和纠错反馈， 截断则保持请求不变。 不得静默拆批、通过 zip 丢失片段、用另一初稿替代，或另加准确性裁判。 Provider 与存储失败不能触发精翻专属的嵌套传输重试。

正式写入前准备可恢复发布记录；提交时校验原文哈希、片段身份和预期 target。 ready→published 之间中断时，以已保存文本核实并恢复。 ready 表示结构有效的综合润色，不是语义准确性认证。

precision/ 档案把不可变共享对象、术语版本和批次进度分开。 保留精确的历史请求构造、校验前原始回复、有效输出、可获得的模型元数据及逐调用用量／事件。 缺失信息保持未知而非零；失败调用仍是失败，缓存复用不算新模型调用。 历史已付费输出兼容时保持可复用，即使重放元数据不完整。

档案含私有原文和译文，不含凭据。它支持检查及输入重建，不保证模型重复响应一致； 采样和服务端模型变化都会影响再请求结果。

Review 影子状态与发布

Review 引擎只能修改本次运行的影子译文和产物。 同轮所有 Fixer 读取同一份不可变快照，完成后统一应用补丁； 盲审读取新影子文本，不接收旧问题解释。取证和仲裁建议不修改术语库。

Reviewer 输出需包含与实际被审片段数相符的完成回执。 不得通过补造 JSON 内容接受截断输出。 回执无效时只拆分受影响块，单段输出重试有界。 未确认候选和未解决仲裁不能绕过发布校验。 not_rereported 只记录后续观察，不证明修订正确。

只有会话身份全部匹配时才复用已完成 Review。 匹配的未完成轮次、块、取证步骤和成功 Fixer 轨迹可续跑， 也包括已存轨迹但尚未提交整轮的情况。 可恢复的 provider／取消停止记为 interrupted；本地／协议失败记为 failed 以便诊断。 两者在身份匹配时均可恢复。

Autofix 是独立且显式受控的发布服务。 随产品提供的 review_autofix 默认为 true； 关闭它会阻止新发布，但不改变 Review 引擎只能写影子状态的契约。发布器：

1. 在工作译文中叠加折叠后的 Review 修改。
2. 对剩余确认问题复用有界取证循环和 Fixer。
3. 先在 autofix/index.json 保存前后版本链、判定、target 哈希和写入状态， 再写正式译文。
4. 仅在预期 target 仍匹配时应用完整片段替换，识别已应用的替换，并刷新受影响对齐元数据。

它不给章节新增 Review 历史字段，不修改 manifest 或术语库。 无关人工译文编辑必须形成冲突，不能被覆盖。 额外问题修复失败不会撤销已经有效的直接修改。 已提交但中断的发布索引优先于新 Review 或修订计划恢复； 即使调用方现在关闭 Autofix 也一样，该选项不是回滚。 恢复仍可能补做对齐并产生相应模型用量。

结果、轮次、诊断和发布历史保留在对应 Review 的产物前缀下。 原始轨迹可能含私有书籍文本和模型回复。

用量与事件账本

事件采用追加语义，用量采用累计语义。 Review 保存自身增量，各增量只合并进书籍总账一次； 重试或续跑不得再次添加已经合并的增量。

用量协调器在状态锁下串行恢复、读基线和准备日志。 先将账本绝对快照持久写入 usage-pending.json，再推进内存检查点。 SQL 日志准备事务在检查点推进前提交，真正发布使用另一个短事务。 发布或事件失败后仍有可恢复日志；下次 flush 先恢复旧工作，再准备自身增量。

成功及失败的付费尝试都记录实际可取得的用量。 不能用批次数推算用量、把缓存复用计为调用，或将 provider 未报告的值当成零。 缓存读取、缓存写入、普通输入和分类未知输入共同组成总提示词 token。 命中率按已报告读取除以全部输入计算；没有读取计数时保持未知。 这些数字不是报价，也不是 provider 物理缓存存在的证明。

耗时与 token 独立。一次调用的时长只累计一次，包含内部阶段，排除两次续跑间的停机时间。 强制终止可能来不及保存时长；未写入的事件不能从日志重建。

语言策略生命周期

i18n/policy/ 是纯类型注册表／解析器，源语言与目标语言绑定分开； 语言配置按根到叶继承，精确注册的语言对规则参与选择。 Agent 消费冻结提示词计划，领域适配器执行选中的文本／writer 能力， 流程服务通过 Storage 持久化阶段身份。

计划只冻结实际消费的提示词资源和能力。 保存不可变 language-policies/<fingerprint>.json 产物及阶段检查点。 语义策略变化或缺少历史身份时，在待译工作前重建受影响的派生分析。 任务级指纹保留未变的章节梗概／文风缓存； 重建中断不能提前提交新检查点。已完成 target 和术语备注保留。

导出身份独立，绑定实际格式／后端及一致原译文快照。 标点、字体和 ruby 变化只需重新导出，无需重译。 在仅用于导出的副本上按完整逻辑段落规范文本，注释／样式偏移只重映射一次， 打开输出前先验证完整视图。保留待译、有意为空及原文回退的不同身份。

任务指令使用英语，生成正文和描述性元数据遵循目标语言； 原文名称和 aliases 仍是匹配身份。 摘要保留原文身份，不与实时术语库争夺名称映射。 JSON 键及类型／性别标识符保持稳定。

策略绑定是源码资源，不是用户 YAML 中的操作覆盖选项。 以下只读诊断使用相同解析器，不调用模型：

uv run wenyi language-policy --source ja --format docx --backend native

未知的内置操作、选项或 handler 必须在消费工作前失败。

提示词体裁合成

任务、共享和语言资源使用可信 ${genre_*} 插槽。 i18n/genres.py 将 genres/literary/fragments.json 默认值与所选体裁覆盖值合成， 然后才进行语言变量替换及策略冻结。 学术片段替换或清空文学专属指令；语法、输出协议和原文证据安全规则保持共享。 不得对不可信书籍文本执行这种替换，也不能引入进程全局体裁选择器。

两个入口的契约不同：

• CLI 的正式选项 --prompt-genre 通过 Config.set_prompt_genre() 设置单次调用内、 非序列化的 override，经 PolicyContext 传递；续跑需再次提供相同选择。 Core YAML 没有 pipeline.prompt_genre。
• Web/Desktop 将创建时选择保存为项目文档及完整任务快照中的 pipeline.prompt_genre， 执行时还原为运行时 override。项目编辑、恢复默认及续跑保留此值； 历史缺省值按 literary 处理。它不属于全局配置。

新增体裁需注册名称和可信片段。遗漏插槽会继承文学默认，因此应显式清空不适用指令。 测试应覆盖各语言方向的合成资源、缓存指纹及项目／任务往返持久化； 质量比较使用独立状态，不混用已完成译文。

诊断与验证

区分 provider／账户失败、输出契约失败和持久化失败。 网络或额度停止不是候选错误的证据。 可预期用户错误应给出可操作说明，而不是 traceback。

术语校验诊断记录操作 ID、固定原因码、数量、局部索引和请求缓存键， 不保存被拒名称、模型说明、不可信引用或原始响应正文。 不能把失败请求伪装成有效空结果，也不应在缓存命中时重复发出拒绝审计。 这套安全诊断规则不表示完整事件流、Review 轨迹或精翻档案可直接分享； 它们可能包含原文和译文。

按变更影响的边界验证：

• 在 manifest 提交前中断准备，确认续跑复用已付费成功工作。
• 在 target 保存、术语抽取、精翻回执、Review 轮次、Autofix 索引和用量日志 提交处中断，验证幂等恢复。
• 检查内容、术语、策略和模型变化仅使相应范围失效。
• 存储改动覆盖 File、SQLite 和 PostgreSQL 适配器，包括锁与并发导出快照。
• 使用 fake 模型／解析服务和临时数据，遵循仓库要求的架构、编排、存储及受影响领域测试。

离线检查验证契约，不验证模型质量。 提示词、术语、上下文或 Review 语义变化，需要说明质量取舍， 在宣称改进前用代表性公版文本比较。