baoyu-translate

翻译器

三种模式的翻译技能：快速模式用于直接翻译，普通模式基于分析进行翻译，精细模式提供完整的出版级工作流，包含审校和润色。

用户输入工具

当此技能提示用户时，请遵循以下工具选择规则（优先级顺序）：

1. 优先使用当前代理运行时暴露的内置用户输入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 回退方案：如果不存在此类工具，则发出带编号的纯文本消息，并要求用户回复每个问题的所选编号/答案。
3. 批量处理：如果工具支持单次调用多个问题，则将所有适用问题合并为一次调用；如果仅支持单个问题，则按优先级顺序逐一询问。

以下具体的 AskUserQuestion 引用仅为示例——在其他运行时中请替换为本地等效工具。

脚本目录

脚本位于 scripts/ 子目录中。{baseDir} = 此 SKILL.md 所在的目录路径。解析 ${BUN_X} 运行时：如果已安装 bun → 使用 bun；如果 npx 可用 → 使用 npx -y bun；否则建议安装 bun。将 {baseDir} 和 ${BUN_X} 替换为实际值。

脚本	用途
scripts/main.ts	CLI 入口点。默认操作将 Markdown 分割为块；也支持显式的 chunk 子命令
scripts/chunk.ts	Markdown 分块实现，由 main.ts 使用，并保持兼容以支持直接调用

偏好设置 (EXTEND.md)

按优先级顺序检查 EXTEND.md——找到的第一个生效：

优先级	路径	范围
1	.baoyu-skills/baoyu-translate/EXTEND.md	项目
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-translate/EXTEND.md	用户主目录

结果	操作
找到	读取、解析、应用。在会话中首次使用时，简要提醒：“正在使用来自 [路径] 的偏好设置。您可以编辑 EXTEND.md 来自定义术语表、受众等。”
未找到	必须运行首次设置（见下文）——不要静默使用默认值

EXTEND.md 支持：默认目标语言、默认模式、目标受众、自定义术语表（内联或文件路径）、翻译风格、分块设置。

模式：references/config/extend-schema.md

首次设置（阻塞操作）

关键：当未找到 EXTEND.md 时，必须在任何翻译之前运行首次设置。这是一个阻塞操作。

完整参考：references/config/first-time-setup.md

使用 AskUserQuestion 在一次调用中包含所有问题（目标语言、模式、受众、风格、保存位置）。用户回答后，在所选位置创建 EXTEND.md，确认“偏好设置已保存至 [路径]”，然后继续。

默认值

所有可配置值集中在此。EXTEND.md 覆盖这些值；CLI 标志覆盖 EXTEND.md。

设置	默认值	EXTEND.md 键	CLI 标志	描述
目标语言	zh-CN	target_language	--to	翻译目标语言
模式	normal	default_mode	--mode	翻译模式
受众	general	audience	--audience	目标读者画像
风格	storytelling	style	--style	翻译风格偏好
分块阈值	4000	chunk_threshold	—	触发分块翻译的字数
每块最大字数	5000	chunk_max_words	—	每块最大字数

模式

模式	标志	步骤	使用时机
快速	--mode quick	翻译	短文本、非正式内容、快速任务
普通	--mode normal（默认）	分析 → 翻译	文章、博客文章、一般内容
精细	--mode refined	分析 → 翻译 → 审校 → 润色	出版质量、重要文档

默认模式：普通（可在 EXTEND.md 的 default_mode 设置中覆盖）。

风格预设——控制翻译的语气和语调（独立于受众）：

值	描述	效果
storytelling	引人入胜的叙事流（默认）	吸引读者，流畅过渡，生动措辞
formal	专业、结构化	中性语气，清晰组织，无口语化表达
technical	精确、文档风格	简洁，术语密集，极少修饰
literal	贴近原文结构	最小重组，保留源语句模式
academic	学术、严谨	正式语域，允许复杂从句，注意引用
business	简洁、结果导向	行动导向，适合高管，要点式思维
humorous	保留并改编幽默	机智、俏皮，在目标语言中重现喜剧效果
conversational	随意、口语化	友好、平易近人，如同向朋友解释
elegant	文学性、精炼散文	美学上精炼，富有节奏，精心选词

也接受自定义风格描述，例如 --style "poetic and lyrical"。

自动检测：

• “快翻”、“quick”、“直接翻译” → 快速模式
• “精翻”、“refined”、“publication quality”、“proofread” → 精细模式
• 否则 → 默认模式（普通）

升级提示：普通模式完成后，显示：

翻译已保存。如需进一步审校和润色，请回复“继续润色”或“refine”。

如果用户回复，则在现有输出上继续执行审校 → 润色步骤（与精细模式工作流 refined-workflow.md 中的步骤 4-6 相同）。

受众预设：

值	描述	效果
general	普通读者（默认）	平实语言，对术语添加更多译者注
technical	开发者/工程师	对常见技术术语注释较少
academic	研究人员/学者	正式语域，精确术语
business	商务专业人士	商务友好语气，解释技术概念

也接受自定义受众描述，例如 --audience "AI感兴趣的普通读者"。

工作流

步骤 1：加载偏好设置

1.1 检查 EXTEND.md（见上方偏好设置部分）

1.2 如果可用，加载语言对的内置术语表：

• EN→ZH：references/glossary-en-zh.md

1.3 合并术语表：EXTEND.md 的 glossary（内联）+ EXTEND.md 的 glossary_files（外部文件，路径相对于 EXTEND.md 位置）+ 内置术语表 + --glossary 文件（CLI 覆盖所有）

步骤 2：物化源文件并创建输出目录

物化源文件（原样文件，内联文本/URL → 保存到 translate/{slug}.md），然后创建输出目录：{source-dir}/{source-basename}-{target-lang}/。如果未指定 --from，则检测源语言。

完整详情：references/workflow-mechanics.md

输出目录内容（所有中间文件和最终文件均存放于此）：

文件	模式	描述
translation.md	所有	最终翻译（始终为此名称）
01-analysis.md	普通、精细	内容分析（领域、语气、术语）
02-prompt.md	普通、精细	组装的翻译提示
03-draft.md	精细	审校前的初稿
04-critique.md	精细	批评性审校结果（仅诊断）
05-revision.md	精细	基于审校的修订翻译
chunks/	分块	源块 + 翻译块

步骤 3：评估内容长度

快速模式不分块——无论长度如何直接翻译。翻译前，估算字数。如果内容超过分块阈值（默认 4000 词），主动警告：“本文约 {N} 词。快速模式一次性翻译，不分块——对于长内容，--mode normal 模式能通过术语一致性获得更好效果。”然后如果用户不切换，则继续。

对于普通和精细模式：

内容	操作
< 分块阈值	作为单个单元翻译
>= 分块阈值	分块翻译（见步骤 3.1）

3.1 长内容准备（仅普通/精细模式，>= 分块阈值）

在翻译块之前：

1. 提取术语：扫描整个文档，提取专有名词、技术术语、重复短语
2. 构建会话术语表：将提取的术语与已加载的术语表合并，建立一致的翻译
3. 分割为块：使用 ${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words <chunk_max_words>] [--output-dir <output-dir>]
   • 解析 Markdown 块（标题、段落、列表、代码块、表格等）
   • 在 Markdown 块边界处分割以保留结构
   • 如果单个块超过阈值，则回退到行分割，然后是词分割
4. 组装翻译提示：
   • 主代理读取 01-analysis.md（如果存在），并使用 references/subagent-prompt-template.md 的第 1 部分组装共享上下文——内联：目标风格、内容背景、合并的术语表以及翻译挑战
   • 保存为输出目录中的 02-prompt.md（仅共享上下文，无任务指令）
5. 通过子代理起草翻译（如果 Agent 工具可用）：
   • 为每个块生成一个子代理，全部并行（模板的第 2 部分）
   • 每个子代理读取 02-prompt.md 获取共享上下文，接收块位置信息（第 N 个块，共 M 个块，以及其在论证中的位置简要上下文），翻译其块，保存到 chunks/chunk-NN-draft.md
   • 通过共享的 02-prompt.md（术语表、比喻语言映射、理解挑战、源语气以及来自分析的翻译挑战）保证一致性
   • 如果没有块（内容低于阈值）：为整个源文件生成一个子代理
   • 如果 Agent 工具不可用，则使用 02-prompt.md 顺序内联翻译块
6. 合并：所有子代理完成后，按顺序合并翻译后的块。如果存在 chunks/frontmatter.md，则将其前置。保存为 03-draft.md（精细模式）或 translation.md（普通模式）
7. 所有中间文件（源块 + 翻译块）保留在 chunks/ 中

分块草稿合并后，将控制权返回给主代理，进行批评性审校、修订和润色（步骤 4）。

步骤 4：翻译与精炼

翻译原则（适用于所有模式）：

• 重写，而非翻译：将内容重写为自然、引人入胜的目标语言，如同熟练的母语作者从头创作。质量测试：“读起来是否像最初就是用目标语言写的？”
• 准确性优先：事实、数据和逻辑必须与原文完全一致
• 自然流畅：使用地道的目标语言语序。将长句拆分为更短、更自然的句子。根据意图解释比喻和习语，而非逐字翻译
• 术语：一致使用标准翻译。专业术语首次出现时：在括号中标注原文
• 保留格式：保留所有 Markdown 格式（标题、粗体、斜体、图片、链接、代码块）
• 主动解释：对于目标受众可能缺乏背景的行话或概念，在粗体括号 （**解释**） 中添加简洁解释。保持注释少量——仅在真正需要理解时添加
• Frontmatter：如果源文件有 YAML frontmatter，将源元数据字段重命名为带 source 前缀（驼峰式：url→sourceUrl，title→sourceTitle 等），将翻译后的值添加为新的顶级字段（如果正文有 H1，则跳过 title），其他字段保持不变

快速模式

直接翻译 → 保存到 translation.md。应用上述所有翻译原则。

普通模式

1. 分析 → 01-analysis.md（领域、语气、术语、翻译挑战）
2. 组装提示 → 02-prompt.md（包含上下文、术语表、挑战的翻译指令）
3. 翻译（遵循 02-prompt.md） → translation.md

完成后，提示用户：“翻译已保存。如需进一步审校和润色，请回复 继续润色 或 refine。”

如果用户继续，则执行批评性审校 → 修订 → 润色（与精细模式步骤 4-6 相同），保存 03-draft.md（重命名当前 translation.md）、04-critique.md、05-revision.md 和更新后的 translation.md。

精细模式

完整的出版级工作流。有关每个步骤的详细指南，请参阅 references/refined-workflow.md。

子代理（如果在步骤 3.1 中使用）仅处理初始草稿。所有后续步骤（批评性审校、修订、润色）由主代理处理，主代理可自行决定委托给子代理。

步骤和保存的文件（均在输出目录中）：

1. 分析 → 01-analysis.md（领域、语气、术语、翻译挑战）
2. 组装提示 → 02-prompt.md（包含内联上下文的翻译指令）
3. 草稿 → 03-draft.md（包含译者注的初始翻译；如果分块则来自子代理）
4. 批评性审校 → 04-critique.md（仅诊断：准确性、欧化语言、策略执行、表达问题）
5. 修订 → 05-revision.md（应用所有审校发现，生成修订翻译）
6. 润色 → translation.md（最终出版级翻译）

每个步骤读取前一步骤的文件并在此基础上构建。

步骤 5：输出

最终翻译始终位于输出目录中的 translation.md。

写入最终翻译后，进行轻量级图片语言检查：

1. 收集翻译后文章中的图片引用
2. 识别可能包含大量文字的图片，例如封面、截图、图表、框架图和信息图
3. 如果任何图片可能包含与翻译后文章语言不匹配的主要文本语言，主动提醒用户
4. 提醒必须仅为列表形式。除非用户要求，否则不要自动本地化这些图片

提醒格式（使用文章已使用的任何图片语法——标准 Markdown 或 wikilink）：

可能需要本地化的图片：
- ![示例封面](attachments/example-cover.png)：可能仍包含源语言文本，而文章现在已是目标语言
- ![示例图表](attachments/example-diagram.png)：可能是文字密集的框架图，检查标签是否需要翻译

显示摘要：

**翻译完成**（{mode} 模式）

源文件：{source-path}
语言：{from} → {to}
输出目录：{output-dir}/
最终文件：{output-dir}/translation.md
应用的术语表条目数：{count}

如果发现不匹配的图片语言候选，在摘要后添加简短说明，告知用户某些嵌入图片可能仍需图片文本本地化，后跟候选列表。

扩展支持

通过 EXTEND.md 进行自定义配置。有关路径和受支持选项，请参阅偏好设置部分。