ainiee-translate

name	ainiee-translate
description	Use when the user wants to translate a novel/epub end-to-end on the coding agent itself (Claude Code or Codex; no AiNiee app), AiNiee-style — parse, build a locked glossary, translate chapter by chapter following rules (names preserved, title 3-way, term consistency), write back and export. Triggers on "用 agent 翻译这本书", "agent 版 aniee 翻译", "把这本 epub 翻译了" and similar.

ainiee-translate 技能指南

总览

本技能让 编码 agent 本身（Claude Code / Codex 等） 充当翻译引擎，配合一组确定性 Python 管道脚本，把一本 epub/txt 小说端到端翻译：

parse → 构建锁定词汇表 → 逐章翻译（agent 按规则） → 写回缓存 → 导出成品

• Agent IS 翻译引擎：无需调用任何外部 API；翻译质量由 agent 按规则实时应用保证。
• 不限于中译：支持任意源语言 → 目标语言（{source_language} 解析时自动检测、{target_language} 由用户指定）；本指南以中文为例，其他目标语言同理。
• 进度状态驱动（translation_status）：中断后重跑自动从首个未译段继续，天然可恢复。
• 每批写回前自动备份（时间戳）：cache.json.bak.YYYYMMDD_HHMMSS。

本技能自带管道脚本（scripts/ainiee_translate/），无需单独 pip install 本包；唯一外部依赖是一份本地 AiNiee 仓库（用作解析/导出库）及其 venv。

---

前置依赖与安装（重要）

parse/export 现在自包含：解析/导出模块随技能打包在 scripts/ainiee_translate/_vendor/ 下（改写自 AiNiee、剥离了其 App 框架），无需克隆 AiNiee 仓库，只需一个装了几个轻量库的 Python。自带格式：epub/txt/md/docx/xlsx/pptx/csv/srt/vtt/ass/lrc/po/json 系列等。仅 PDF 与 Windows Office 转换未自包含——要用时设 AINIEE_REPO 回退到 AiNiee。

一次性准备：

1. 确认本技能的安装位置。把本 ainiee-translate/ 文件夹放进 agent 的 skills 目录：

   ~/.claude/skills/ainiee-translate/     # Claude Code
   ~/.codex/skills/ainiee-translate/      # Codex（OpenAI Codex CLI）
   

   下文用 $SKILL_DIR 指代它。在 Codex 等非 Claude Code 平台使用、以及工具名（Bash/Task/TodoWrite…）对照见 references/codex-tools.md。

2. 建一个 venv 并装依赖（任意 Python ≥ 3.12）：

   python3 -m venv ~/.venvs/ainiee-translate
   ~/.venvs/ainiee-translate/bin/pip install \
     msgspec beautifulsoup4 lxml rich openpyxl polib python-pptx chardet
   

3. 设置两个路径变量（每个新终端；或写入 shell profile）：

   export SKILL_DIR=~/.claude/skills/ainiee-translate            # 本技能安装目录
   export AINIEE_PY=~/.venvs/ainiee-translate/bin/python         # 上面 venv 的 python
   # 可选：仅翻 PDF / Office(Windows) 这类未自包含格式时，回退到 AiNiee：
   # export AINIEE_REPO=/path/to/AiNiee
   

命令前缀（后文用 <PFX> 代替）：

PYTHONPATH="$SKILL_DIR/scripts" "$AINIEE_PY"

管道脚本以 ainiee_translate 包形式打包在 $SKILL_DIR/scripts/ 下，PYTHONPATH 指向该 scripts 目录即可 -m ainiee_translate.<module> 调用。AINIEE_REPO 只有 PDF/Office 回退才需要；不设也能跑自带格式。

自检命令（确认环境就绪）：

PYTHONPATH="$SKILL_DIR/scripts" "$AINIEE_PY" \
  -c "from ainiee_translate import io_dispatch; print('formats OK:', io_dispatch.supported_extensions())"

---

步骤 1：准备工作目录

每个翻译项目独立一个工作目录（下文用 $WORK 指代）：

export WORK=~/my-book          # 自取
mkdir -p "$WORK/work" "$WORK/out"

---

步骤 2：解析输入书籍

将 epub/txt 解析成 cache.json（AiNiee CacheProject 格式）：

<PFX> -m ainiee_translate.parse \
  --input /path/to/book.epub \
  --type AutoType \
  --out "$WORK/work/cache.json"

• --type：AutoType（自动检测）、Epub、Txt 等，默认 AutoType。
• 成功后打印：parsed N items -> .../cache.json。

---

步骤 2 替代：导入已有项目（含 AiNiee 缓存）

不必每次从头解析。若已有一个翻译缓存——AiNiee 的工程缓存（AinieeCacheData.json）或另一个 ainiee-translate 项目的 cache.json（同为 CacheProject 格式）——可直接导入，再续翻/润色/校验/导出。

• 列出可导入的 AiNiee 工程（扫描 ~/Library/Application Support/AiNiee/ProjectCache，可用 AINIEE_CACHE_DIR 覆盖）：

  <PFX> -m ainiee_translate.project list
  

  每项给出 project_id、project_name、input_path（原书）及状态计数（未译/已译/已润色/已排除）。

• 导入到项目（项目 ID 用 --ainiee，缓存文件路径用 --cache）：

  <PFX> -m ainiee_translate.project import --ainiee <项目ID> --work "$WORK"
  # 或：--cache /path/to/AinieeCacheData.json --work "$WORK"
  

  把缓存规范化进 $WORK/work/cache.json（已存在则先时间戳备份），并打印 input_path 与状态计数。

导入后按状态接续：还有未译段→步骤 5 续翻；已译待润色→步骤 6.5 润色；直接出成品→步骤 6 导出（原书路径见 input_path）；查残留→步骤 7。

---

步骤 3：构建并锁定词汇表

从 AiNiee 公共术语表（prompt_dictionary_data）和可选的项目分析缓存（analysis_v1）生成锁定表：

<PFX> -m ainiee_translate.glossary \
  --config "<AiNiee config.json 路径>" \
  --analysis "<项目分析缓存路径（可选）>" \
  --out "$WORK/work/glossary.locked.json"

• --config：AiNiee 的 config.json，路径随平台而异：
  • macOS：~/Library/Application Support/AiNiee/config.json
  • Windows：%APPDATA%\AiNiee\config.json
  • Linux：~/.config/AiNiee/config.json
  • 找不到时，在 AiNiee 应用的设置/数据目录里定位 config.json。
• --analysis 可省略（无项目分析时跳过），形如 .../ProjectCache/<project_id>/AinieeCacheData.json。
• 生成后，必须人工 review 并锁定：检查人名分类（是否保留原文）、地名/种族译法、音译唯一性。复核时特别注意：自动清洗按姓氏末词归并同一角色，可能把同姓的不同角色误并为一条——检查每条的 aliases 里没有混入另一个人。
• 锁定表格式：

{
  "characters": [
    {"canonical": "James Marlow", "render": "James Marlow",
     "aliases": ["Marlow", "Jim"], "gender": "M", "note": "船长"}
  ],
  "terms": [
    {"src": "the Ravensguard", "dst": "鸦卫军", "category": "faction"},
    {"src": "Highmark", "dst": "Highmark", "keep_source": true}
  ],
  "non_translate": [{"marker": "<i>", "category": "tag"}]
}

---

模块（可选）：一套设置应对不同书

「模块」= 一个可复用的任务设置包，存于 ~/.ainiee-translate/modules/<名字>/，含：翻译提示词、润色提示词、词汇表、禁翻表、风格/世界观/角色、源/目标语言。同一个技能/插件靠切换模块应对不同小说/文档。

• 导入 AiNiee profile 为模块：<PFX> -m ainiee_translate.profile import --profile <profile.json> --name <名字>
• 新建空模块：<PFX> -m ainiee_translate.module create <名字> [--source-language X --target-language Y]
• 列出/查看：<PFX> -m ainiee_translate.module list / show <名字>
• 加载进项目：<PFX> -m ainiee_translate.module load <名字> --work ~/my-project

加载只是把模块的 translate_prompt.md→work/user_prompt.md、polish_prompt.md、glossary.locked.json 拷进项目 work/——即后续步骤本就在读的文件。不用模块的项目，流程与下文完全一致。 此外 prompt.py 还能从 AiNiee 配置/profile 提取所选系统提示词（--translate-system）与润色提示词（--polish）。命令行入口见附录 C。

---

步骤 3+：用户自定义提示词（可选，像 AiNiee 一样自己写规则）

翻译规则分两层，领域/风格规则不写死在技能里——和 AiNiee 一样由用户自己写：

• 通用层（技能自带）：references/translation_rules.md，即 AiNiee 原生标准提示词（逐行、保留标记、忠实准确）。
• 项目层（用户自己写）：人名怎么处理、头衔怎么摆、对话风格、世界观、示例等，全由用户提供。

两种来源：

1. 复用 AiNiee app 的提示词设置（推荐）：你在 AiNiee 里配的「自定义系统提示词 / 角色介绍 / 写作风格 / 世界观 / 翻译示例」都存在 config.json，按各自开关汇总成一份：

   <PFX> -m ainiee_translate.prompt --config "<AiNiee config.json>" --out ~/my-project/work/user_prompt.md
   

   （读取 translation_user_prompt_data / characterization_data / writing_style_content / world_building_content / translation_example_data，仅纳入开关打开的部分。）
2. 手写项目提示词：直接在 ~/my-project/work/user_prompt.md 写你的规则（如「人名保留原文」「军衔后置」等）。

翻译时 agent 遵循：AiNiee 原生原则（translation_rules.md）＋ 用户自定义提示词（user_prompt.md，若有）＋ 锁定表（术语表/角色表）。技能本身不预设任何特定题材的规则。

---

步骤 4：选择介入模式

开始翻译前，与用户确认介入模式：

模式	行为	适用场景
A 抽样自动（默认）	先译约 1 章展示给用户确认风格和规则对齐；之后自动逐章。遇到锁定表外的歧义新实体时停下询问。	第一次翻译新书
B 每章过目	每章译完后展示给用户，点头确认后写回，再译下一章。歧义实体停下询问。	用户想细粒度监控
C 全自动	整本一次性译完写回，歧义实体不停止，记入 needs_review 列表，最后统一报告。	已熟悉风格、快速跑完

---

步骤 5：翻译循环

5a. 读取未译批次

<PFX> -m ainiee_translate.batch read \
  "$WORK/work/cache.json" \
  --size 100

输出：JSON 数组，每项包含 text_index（段落编号）和 source_text（源文）：

[
  {"text_index": 1, "source_text": "The room fell silent."},
  {"text_index": 2, "source_text": "Marlow studied the letter."}
]

恢复机制：read 只返回 translation_status = UNTRANSLATED 的段落。重跑时自动跳过已译段，从断点继续。

5b. Agent 翻译

Agent 本身就是翻译引擎。 读取上一步的 JSON，逐段按以下规则翻译：

1. 通用规则见 references/translation_rules.md（AiNiee 原生：逐行对应、保留标记、忠实准确）。
2. 项目规则（人名保留、头衔摆放、风格等）见用户自定义提示词（步骤 3+，由用户自己写，不写死在技能里）。
3. 人名/术语 以锁定表（术语表/角色表）为唯一真相源；render 为英文则保留原文。
4. 遇到锁定表外的新实体：模式 A/B 停下询问用户；模式 C 用锁定表最近匹配或保留原文，并记入待审列表。

将翻译结果写成 JSON 文件：

[
  {"text_index": 1, "translated_text": "房间里一片寂静。"},
  {"text_index": 2, "translated_text": "Marlow 端详着那封信。"}
]

保存为 $WORK/work/translations_batch_001.json（命名自取）。

5c. 写回缓存

<PFX> -m ainiee_translate.batch write \
  "$WORK/work/cache.json" \
  "$WORK/work/translations_batch_001.json"

• 写回前自动创建带时间戳的备份：cache.json.bak.YYYYMMDD_HHMMSS。
• 成功后打印：applied N translation(s)。
• 重复执行步骤 5a → 5c 直到 batch read 返回空数组（[]）为止。

---

步骤 5+：多 agent 并行翻译（可选，大书加速）

书很大、章节相互独立、且风格已用模式 A 锁定后，可派多个 subagent 并发翻译不同章节范围， 墙钟时间≈最慢的 agent（实测 11 章 1704 段用 7 个 agent 约 9 分钟译完）。

唯一铁律：subagent 绝不写 cache.json（并发「读改写」会损坏文件）。subagent 只产出译文 JSON 文件， 由主控 agent 串行 batch write 回写。各 agent 共享同一份锁定表 + references/translation_rules.md + 项目级 STYLE_GUIDE.md（用 references/style_guide_template.md 生成）以保证风格一致；新实体一律「保留原文 + 记录」。

完整流程（拆分、抽取、派发模板、风格漂移归一化、串行写回、收尾 verify）见 references/parallel_translation.md。

---

步骤 6：导出成品

<PFX> -m ainiee_translate.export \
  --cache "$WORK/work/cache.json" \
  --output "$WORK/out/" \
  --input /path/to/book.epub

• 使用 AiNiee 的 FileOutputer 保留原书结构和富文本标签。
• 输出文件名带 _translated 后缀（默认），例如 book_translated.epub。

---

步骤 6.5：润色（可选）

若当前模块带 polish_prompt.md（已随加载落到 work/），可对已译文本做润色 pass：状态 TRANSLATED→POLISHED，可断点续跑；导出读 final_text，自动采用润色后的文本。模块无润色提示词则跳过本步。

循环直到 batch read-translated 返回 []：

1. <PFX> -m ainiee_translate.batch read-translated work/cache.json --size 100 → {text_index, source_text, translated_text} 数组。
2. agent 按 work/polish_prompt.md + 锁定词汇表润色每段（逐行 1:1、保留标记、人名/术语依词汇表），写 work/polished_NNN.json（{text_index, polished_text}）。
3. <PFX> -m ainiee_translate.polish write work/cache.json work/polished_NNN.json（写回并置 POLISHED）。

---

步骤 7：验证残留规则违规

<PFX> -m ainiee_translate.verify \
  "$WORK/work/cache.json" \
  "$WORK/work/glossary.locked.json"

输出 JSON 格式的问题列表，并打印问题总数。两类检测：

• empty_translation：源段有内容但译文为空（漏译）。
• name_not_preserved：源段含锁定表英文人名但译文中该名消失（人名汉化）。

verify 检查**已译（status 1）和已润色（status 2）**两类段（润色文本就存在 translated_text）。对每个问题，使用 batch write（已译段）/ polish write（已润色段，保住状态）修正对应 text_index 的译文后重新跑 verify，直到无问题。

⚠️ verify 的局限：为什么「verify 干净」≠「没有翻译错误」

verify 是词汇表执行器，不是发现器。它只能发现「锁定表里登记过的人名」消失的情况，因此天然漏掉下面这些（实战中绝大多数漏网错误都属于此）：

1. 词汇表覆盖不全（头号原因）：verify 只查 glossary.locked.json 的 characters。没进表的名字它根本不知道要查——配角、地名、舰名，尤其当词汇表是从「上一本书」或 AiNiee 分析缓存里种出来、没针对当前书补全时。一份「2 个问题」的干净报告，往往只是因为表里恰好只有 2 个相关名字。→ 对策：词汇表必须随当前书补全（见下方 scan 发现流程）。
2. 整段成员检查，漏「同段对错并存」：若同一段里某名字一处保留英文、另一处被音译（例：Keru 看着…后来克鲁离开），verify 看到「Keru 在」就不报。
3. 「全程音译」的名字无信号：若某名字在全书每一处都被音译（例 Tenmei→天明、Rianu→里亚努），它从没以英文出现过，"时而对时而错"的不一致信号为零。
4. 区分不了「音译错误」与「合理代词省略 / 合法意译」：补全词汇表后，那些把名字合理处理成「他/她」的段会被误报；Vulcan→瓦肯 这种合法意译它也无法识别。
5. 完全不覆盖的错误类型：①「张冠李戴」——表外名字被换成别的名字（Dax→萨姆、Gard→Vic）；② OCR/解析丢空格的粘连词漏进译文（thenaiskosfragment）；③ 整句未翻译的英文残留留在译文里；④ 模型幻觉插入的短乱码（顶替源文的 Lt/Vic）。

步骤 7+：用 scan 发现词汇表缺口与解析瑕疵（补 verify 盲区）

<PFX> -m ainiee_translate.scan \
  "$WORK/work/cache.json" \
  --locked "$WORK/work/glossary.locked.json" \
  --mode all        # all | discover | terms | strays | merges

• discover：找不在词汇表、原文有但译文中消失的专名（语言无关、不依赖词汇表、逐出现处、覆盖 status 1+2）。
  • inconsistent（高置信，优先处理）：同名时而保留英文、时而消失——单点滑落 / 同段对错并存（如 Rio Grande、Keru）。
  • never_preserved（需人眼判断）：从不以英文出现，含「全程被音译的真名」（Tenmei→天明、Rianu→里亚努）与「合法意译的术语」（Vulcan→瓦肯）两类混在一起。
• terms：反向漏译——词汇表里有中文译名（dst、非 keep_source）的术语，却在个别段被留成了英文（Starfleet→星际舰队 全书都译了、唯独某段漏成 "Starfleet"）。
• strays：模型幻觉插入——译文里出现、但该段原文里没有的英文 token（凭空写出的错名 Vic/Sam/Sef、顶替"the guard"的 Lt）。是复查列表非合格门：含解析粘连词（theRio→Rio）与一贯保留的外星术语，需人眼筛；真信号是无来由的短错名。
• merges：原文里超长 Latin 串或 camelCase 跳变的丢空格粘连词（thenaiskosfragment、speciesDraco、TheAlexandria）；调小 --min-merge-len 可挖更短的。

推荐校对闭环：verify（清掉表内硬伤）→ scan --mode all（discover→inconsistent 全改、never_preserved 挑真名；terms→补回被漏成英文的术语；strays→揪幻觉错名；merges→收粘连词）→ 把确认的真名/地名补进 glossary.locked.json 的 characters，保留英文的通名补进 terms（keep_source:true），有中文译名的术语进 terms（带 dst） → 再 verify（这下表全了，能守住；忽略代词省略类误报）。改已润色段一律用 polish write 以保住状态。

经验：写自查脚本做名字比对时，先归一化撇号（弯/直撇号 '/' 统一），否则 Mak'ala、Quark's、O'Brien 会因撇号不同被误判为「消失」。verify/scan 内部已统一处理。

---

附录 A：命令速查

# 路径变量（每次新终端）
export SKILL_DIR=~/.claude/skills/ainiee-translate
export AINIEE_PY=~/.venvs/ainiee-translate/bin/python   # venv with: msgspec bs4 lxml rich openpyxl polib python-pptx chardet
export WORK=~/my-book
# 可选：export AINIEE_REPO=/path/to/AiNiee   # 仅 PDF / Office 回退

# 命令前缀
PFX="PYTHONPATH=$SKILL_DIR/scripts $AINIEE_PY"

# 解析
$PFX -m ainiee_translate.parse --input book.epub --type AutoType --out "$WORK/work/cache.json"

# 词汇表
$PFX -m ainiee_translate.glossary --config "<config.json>" --out "$WORK/work/glossary.locked.json"

# 用户自定义提示词（汇总 AiNiee 配置里的自定义提示词）
$PFX -m ainiee_translate.prompt --config "~/Library/Application Support/AiNiee/config.json" --out work/user_prompt.md

# 批次读取
$PFX -m ainiee_translate.batch read "$WORK/work/cache.json" --size 100

# 批次写回
$PFX -m ainiee_translate.batch write "$WORK/work/cache.json" "$WORK/work/translations_001.json"

# 导出
$PFX -m ainiee_translate.export --cache "$WORK/work/cache.json" --output "$WORK/out/" --input book.epub

# 验证
$PFX -m ainiee_translate.verify "$WORK/work/cache.json" "$WORK/work/glossary.locked.json"

# 发现（补 verify 盲区：表外被音译/丢失的专名 + 术语漏译 + 幻觉错名 + OCR 粘连词）
$PFX -m ainiee_translate.scan "$WORK/work/cache.json" --locked "$WORK/work/glossary.locked.json" --mode all

---

附录 B：常见问题

Q: parse / import 报 ModuleNotFoundError（bs4 / lxml / openpyxl / polib / pptx）？ A: 缺依赖。在 $AINIEE_PY 的 venv 里 pip install msgspec beautifulsoup4 lxml rich openpyxl polib python-pptx chardet，并确认 PYTHONPATH 指向 $SKILL_DIR/scripts。不再需要 AINIEE_REPO（仅 PDF/Office 回退才设）。

Q: batch read 返回空数组 []？ A: 所有段落均已翻译完毕（translation_status = TRANSLATED），可以进行导出步骤。

Q: 导出后 epub 没有内容？ A: 检查 cache.json 中是否有 translation_status = 1 的段落（即已译段）。可用 batch read 确认剩余未译数量。

Q: 如何重做某段译文？ A: 直接用 batch write 写入新的 translated_text（按 text_index 覆盖），write_back 会用新值替换旧值。

Q: 如何跳过不需要翻译的段落（如纯数字章节号）？ A: 在 translations.json 中将 translated_text 设为源文原样，或在生成时 agent 判断后直接复制源文。

Q: verify 报 0 问题，但书里明明还有人名被音译 / 错译，为什么？ A: verify 只执行锁定表里登记过的人名，且无法识别张冠李戴、OCR 粘连词、未译残留、幻觉插入。「0 问题」常常只说明表内名字没丢。用 scan --mode all 发现表外被音译/丢失的专名（discover）、被漏译成英文的术语（terms）、幻觉错名（strays）、粘连词（merges），把确认的真名补进词汇表后再 verify。详见步骤 7「verify 的局限」。

---

附录 C：斜杠命令（菜单）

安装为插件后，所有操作都可用 /ainiee-translate:<命令> 完成（/ 选择器即菜单，或 /ainiee-translate:menu 看清单）：

命令	作用
menu	显示命令菜单
translate <输入> [模块]	端到端翻译（解析→词汇表→翻译→导出→校验）
import-profile <profile.json> <模块>	导入 AiNiee profile 为模块
module list|show|create|load …	管理模块
gen-prompt translate|polish [模块]	让 agent 起草翻译/润色提示词
switch-prompt [模块] / show-prompt [模块]	切换 / 查看模块
polish [批大小]	润色 pass
glossary / export <输入> / verify / status	词汇表 / 导出 / 校验 / 状态
scan [discover|terms|strays|merges|all]	补 verify 盲区：表外被音译/丢失的专名(discover)、被漏译成英文的术语(terms)、幻觉插入的错名(strays)、OCR 粘连词(merges)

命令脚本路径用 ${CLAUDE_PLUGIN_ROOT}/skills/ainiee-translate/scripts，并需用户设好 AINIEE_REPO/AINIEE_PY。