name: daggerheart-translation-pipeline
description: Orchestrates the end-to-end Daggerheart translation flow: project setup, source-to-Markdown conversion, Markdown cleanup, glossary tagging, chunked translation with retained term markers, term review, marker stripping, validation, and JSON extraction.
Daggerheart Translation Pipeline
英文 Daggerheart PDF/DOCX 输入，中文 Markdown + 结构化 JSON 输出。
这是总编排 skill。它只负责：
- 步骤顺序
- 输入输出路径
- 人工确认节点
- 跨步骤硬规则
子步骤的实现细节，交给对应子 skill 或脚本本身，不在此重复展开。
依赖技能
daggerheart-md-converter：PDF/DOCX -> source/_raw.mddaggerheart-md-format-fixer：source/_raw.md -> source/_original.mddaggerheart-glossary-extractor：提取文档术语表daggerheart-chinese-writing：翻译 subagent 的写作规范daggerheart-term-checker：生成术语审阅报告，并在审阅后清理术语标记daggerheart-json-formatter：译文 MD -> 结构化 JSON
运行模式
在执行第 0 步前，必须先用 question 工具确认运行模式，不得跳过。
手动模式（推荐）
- 术语冲突时暂停，等用户处理
chunk 01 翻译后暂停，等用户审查- 并行翻译前再次确认
- 术语审阅报告由人工审阅
全自动模式
- 术语冲突按固定优先级自动裁决
chunk 01 自动检查后直接继续- 术语审阅报告由 AI 自动审阅并直接回写 chunk
- 并行翻译、术语审阅、清标记、合并、makeup、检查、JSON 提取连续执行
- 仅在最终汇报结果
固定优先级：
terms-14448.json > adversaries_*.json > glossary/_glossary.json
路径约定
所有命令在用户翻译项目根目录执行。
关键路径：
source/_raw.md：转换后的原始 Markdownsource/_original.md：修复后的原文 Markdownsource/temp/：临时产物source/temp/_tagged.md：内联术语标记后的原文source/temp/_translated_chunks/：保留术语标记的译文 chunksource/temp/_term_review_report.md：术语审阅 Markdown 报告source/temp/_term_review_report.json：术语审阅 JSON 报告source/temp/_translated_chunks_clean/：清除术语标记后的译文 chunksource/_translated.md：最终译文 Markdownglossary/_glossary.json：文档术语表data/：结构化 JSON 输出
命令里的路径分两类：
scripts/、resources/：相对于本 skill 根目录source/、source/temp/、glossary/、data/：相对于项目根目录
AI 执行时必须分别解析到正确绝对路径。
管线
前置. 确认运行模式（手动审阅 / 全自动）
0. 初始化项目结构
1. PDF/DOCX -> 原始 MD
2. 修复原文格式
3. 提取文档术语表
4. 内联术语替换
5. 分块
6. 翻译（chunk 01 确认 -> 并行）
7. 术语审阅报告
8. 清除术语标记
9. 合并
10. makeup
11. 自动检查 + 修正循环
12. JSON 提取
第 0 步：初始化项目结构
python scripts/setup_project.py <项目目录>
目标：确保项目目录结构符合标准布局。脚本应视为幂等初始化工具。
第 1 步：源文档 -> 原始 Markdown
调用 daggerheart-md-converter 技能，将 PDF/DOCX 转为项目 source/_raw.md。
第 2 步：修复原文格式
调用 daggerheart-md-format-fixer 技能，将 source/_raw.md 修为 source/_original.md。
第 3 步：提取文档术语表
调用 daggerheart-glossary-extractor 技能，扫描 source/_original.md，输出 glossary/_glossary.json。
第 4 步：内联术语替换
将全局术语表与本文档术语表合并，并对原文做内联标记。
python scripts/merge_terms.py --terms "resources/terms-14448.json" "resources/adversaries_features.json" "resources/adversaries_motivation.json" "resources/adversaries_name.json" "glossary/_glossary.json" --output "source/temp/_merged_terms.json" --original "source/_original.md"
python scripts/replace_terms.py "source/_original.md" "source/temp/_merged_terms.json" "source/temp/_tagged.md"
- 输出：
source/temp/_merged_terms.json、source/temp/_tagged.md
- 标记格式：
【原文｜推荐译文｜注释】
注释 可为空；若为空则标记退化为 【原文｜推荐译文】- 默认手动模式：若出现术语冲突，暂停，等待用户处理后再继续
- 全自动模式：给
merge_terms.py 增加 --auto-resolve，按固定优先级自动保留高优先级译名，并继续执行；最终汇报冲突结果
第 5 步：分块
python scripts/split_chunks.py "source/temp/_tagged.md" --min-chars 4000 --target-chars 5500 --max-chars 7000 --context-chars 1200
- 输出目录：
source/temp/_chunks/
- 分块脚本会自动加入
KILO_CONTEXT / KILO_TARGET 包装段，后续合并时只保留 KILO_TARGET
第 6 步：翻译
6.0 模型选择
优先使用快速便宜模型，并关闭或尽量降低 thinking。若当前环境没有合适快速模型，先向用户说明实际将使用哪种模型执行翻译 subagent。
6.1 翻译 chunk 01
先生成该 chunk 的完整翻译 prompt：
python scripts/translation_prompt.py "<chunk_file>"
硬约束：
- 该脚本会生成
_prompt_xxx.md
- 必须用
Read 工具读取该 prompt 文件
- 必须将读取到的完整内容原样作为 subagent 的 prompt 传入
- 不得删减、重写、概括、改写或替换其中规则
原因：翻译 prompt 是在启动 subagent 时才提供的，这个 prompt 本身就是 pipeline 的一部分，不是可自由压缩的附属说明。
翻译 subagent 负责：
- 读取当前 chunk 文件与
REFERENCE.md
- 产出对应译文到
source/temp/_translated_chunks/
- 保留所有
[[[KILO_...]]] 标记行原样不变
- 将
【原文｜推荐译文｜注释】 改写为 【当前译文｜推荐译文｜注释】
- 每个术语标记必须一一对应保留，不得删除、重排、合并、拆分
推荐译文 与 注释 仅作参考与审阅依据，默认保持原样
手动模式：
- 展示
chunk 01 原文与译文给用户审查
- 用户确认前，不得进入下一步
全自动模式：
- 完成
chunk 01 后，自动检查 KILO 结构与术语标记是否完整保留，再继续后续 chunk
6.2 并行翻译剩余 chunk
手动模式下，在 chunk 01 通过后，必须明确提示用户：
chunk 01 已确认，是否开始并行翻译剩余 N 个 chunk？
收到确认后，并行启动剩余 chunk 的翻译。
剩余 chunk 必须沿用 6.1 完全相同 的 prompt 生成与原样传递规则，不得自行编写缩略版 prompt。
全自动模式下，跳过该确认，直接并行执行。
第 7 步：术语审阅报告
调用 daggerheart-term-checker 技能，扫描 _chunks/ 与 _translated_chunks/，按术语出现位置生成逐条审阅报告。
python <term_checker_skill_root>/scripts/check_terms.py <项目目录>
- 默认输出：
source/temp/_term_review_report.mdsource/temp/_term_review_report.json
- 报告逐条列出：
chunk、原文、推荐译文、当前译文、是否采用推荐、原文上下文、译文上下文、注释、异常
是否采用推荐 仅是提示，不是硬规则；允许根据上下文保留非推荐译法- checker 优先按
推荐译文 + 注释 对位，不再把局部术语换序误判成结构损坏
- 若发现标记数量不一致、标记损坏、推荐译文槽位被改坏等结构异常，必须先修复再继续
手动模式：
- 向用户展示术语审阅报告
- 用户人工审阅每条术语后，直接修改
source/temp/_translated_chunks/ 中各标记的第一槽 当前译文
- 用户确认审阅通过前，不得进入下一步
全自动模式：
- AI 必须通读术语审阅报告，结合上下文与注释，自动决定每条术语是否采用推荐译文
- 若需修正，直接修改
source/temp/_translated_chunks/ 中各标记的第一槽 当前译文
- 修改后重新生成一次术语审阅报告，确认结构异常已消失，并将最终报告作为继续执行依据
第 8 步：清除术语标记
在术语审阅完成后，批量移除所有术语标记，只保留每个标记第一槽中的最终中文译文。
python <term_checker_skill_root>/scripts/strip_term_markers.py <项目目录>
- 输入：
source/temp/_translated_chunks/
- 输出：
source/temp/_translated_chunks_clean/
- 非破坏性：保留原始带标记译文 chunk，合并阶段只使用清理后的目录
第 9 步：合并
python scripts/split_chunks.py "source/temp/_translated_chunks_clean" --merge --output "source/_translated.md"
输出：source/_translated.md
第 10 步：makeup 后处理
python scripts/makeup.py "source/_translated.md" --suffix ""
第 11 步：自动检查 + AI 修正循环
python scripts/validate_translation.py "source/_translated.md"
若检查不通过：
- 根据脚本输出直接修改
source/_translated.md
- 重新运行检查脚本
- 重复直到检查通过
规则性错误可批量修正，不规则错误逐行修正。
若需要在清标记前对单个带标记 chunk 做结构检查，可使用：
python scripts/validate_translation.py "<chunk_file>" --allow-term-markers
第 12 步：JSON 提取
调用 daggerheart-json-formatter 技能，扫描 source/_translated.md，按内容类型提取为对应 JSON，输出到 data/。
结束条件
以下条件全部满足后，管线才算完成：
source/_translated.md 已生成- 术语审阅报告已生成
source/temp/_translated_chunks_clean/ 已生成- 校验脚本已通过
- JSON 已提取完成
