三模式翻译技能：快速 直接翻译，标准 分析后翻译，精翻 完整出版级工作流（含审查和润色）。

脚本目录

脚本位于 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	main.ts 使用的 Markdown 分块实现，保持兼容可直接调用

偏好设置（EXTEND.md）

检查 EXTEND.md 是否存在（按优先级顺序）：

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-translate/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-translate/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-translate/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md") { "user" }

路径	位置
.baoyu-skills/baoyu-translate/EXTEND.md	项目目录
$HOME/.baoyu-skills/baoyu-translate/EXTEND.md	用户主目录

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

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

Schema: 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 "诗意和抒情"。

自动检测：

• "快翻"、"quick"、"直接翻译" → 快速模式
• "精翻"、"refined"、"publication quality"、"proofread" → 精翻模式
• 其他 → 默认模式（标准）

升级提示：标准模式完成后，显示：

翻译已保存。如需进一步审查和润色，回复"继续润色"或"refine"。

如果用户回复，继续执行审查 → 润色步骤（与精翻模式步骤 4-6 相同）。

使用方法

/translate [--mode quick|normal|refined] [--from <语言>] [--to <语言>] [--audience <受众>] [--style <风格>] [--glossary <文件>] <来源>

• <来源>：文件路径、URL 或内联文本
• --from：源语言（省略则自动检测）
• --to：目标语言（来自 EXTEND.md 或默认 zh-CN）
• --audience：目标读者画像（来自 EXTEND.md 或默认 general）
• --style：翻译风格（来自 EXTEND.md 或默认 storytelling）
• --glossary：与 EXTEND.md 术语表合并的额外术语文件

受众预设：

值	说明	效果
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 长内容准备（标准/精翻模式，仅 >= 分块阈值时）

分块翻译前：

• 提取术语：扫描整个文档的专有名词、技术术语、重复短语
• 构建会话术语表：将提取的术语与已加载的术语表合并，建立一致翻译
• 分块：使用 ${BUN_X} {baseDir}/scripts/main.ts <文件> [--max-words ] [--output-dir <输出目录>]

- 解析 Markdown 块（标题、段落、列表、代码块、表格等） - 在 Markdown 块边界处分割以保留结构 - 如果单个块超过阈值，回退到按行分割，再按词分割

• 组装翻译提示：

- 主代理读取 01-analysis.md（如果存在），使用 references/subagent-prompt-template.md 第 1 部分组装共享上下文——内联：目标风格、内容背景、合并术语表和翻译挑战 - 保存为输出目录中的 02-prompt.md（仅共享上下文，无任务指令）

• 通过子代理翻译（如果 Agent 工具可用）：

- 每个块生成一个子代理，全部并行执行（模板第 2 部分） - 每个子代理读取 02-prompt.md 获取共享上下文，接收块位置信息（第 N 块/共 M 块 + 在文中的简要上下文），翻译其块，保存到 chunks/chunk-NN-draft.md - 通过共享的 02-prompt.md（术语表、比喻语言映射、理解挑战、源文语调和翻译挑战）保证一致性 - 如果没有分块（内容低于阈值）：为整个源文件生成一个子代理 - 如果 Agent 工具不可用，使用 02-prompt.md 按顺序内联翻译各块

• 合并：所有子代理完成后，按顺序合并翻译块。如果 chunks/frontmatter.md 存在，前置添加。保存为 03-draft.md（精翻）或 translation.md（标准）
• 所有中间文件（源文件块 + 翻译块）保留在 chunks/ 中

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

步骤 4：翻译与精炼

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

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

快速模式

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

标准模式

• 分析 → 01-analysis.md（领域、语调、术语、翻译挑战）
• 组装提示 → 02-prompt.md（带上下文、术语表、挑战的翻译指令）
• 翻译（遵循 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 中使用）仅处理初稿。所有后续步骤（批判性审查、修订、润色）由主代理处理，主代理可自行决定是否委派给子代理。

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

• 分析 → 01-analysis.md（领域、语调、术语、翻译挑战）
• 组装提示 → 02-prompt.md（带内联上下文的翻译指令）
• 初稿 → 03-draft.md（带译者注的初始翻译；分块时来自子代理）
• 批判性审查 → 04-critique.md（仅诊断：准确性、翻译腔、策略执行、表达问题）
• 修订 → 05-revision.md（应用所有审查发现，生成修订翻译）
• 润色 → translation.md（最终出版级翻译）

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

步骤 5：输出

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

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

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

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

可能需要图片本地化：
!示例封面：可能仍包含源语言文字，而文章已是目标语言
!示例图表：可能是文字密集的框架图，检查标签是否需要翻译

显示摘要：

翻译完成（{mode} 模式）
来源：{source-path}
语言：{from} → {to}
输出目录：{output-dir}/
最终文件：{output-dir}/translation.md
已应用术语：{count} 条

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

扩展支持

通过 EXTEND.md 自定义配置。路径和支持选项见偏好设置部分。

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-translate/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-translate/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-translate/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-translate/EXTEND.md") { "user" }

/translate [--mode quick|normal|refined] [--from ] [--to ] [--audience ] [--style