baoyu-translate

Translator

三模式翻译技能：quick 用于直接翻译，normal 用于结合分析进行翻译，refined 用于通过审校和润色完成完整的出版级工作流。

用户输入工具

此技能向用户提问时，请遵循以下工具选择规则（按优先级排序）：

1. 优先使用当前 Agent 运行时提供的内置用户输入工具，例如 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	main.ts 使用的 Markdown 分块实现，同时兼容直接调用

偏好设置（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	用户主目录

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

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

配置结构：references/config/extend-schema.md。

首次设置（阻塞）

重要：如果未找到 EXTEND.md，则在进行任何翻译之前，必须先执行首次设置。这是一项阻塞操作。

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

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

默认值

所有可配置值集中在此处。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. 组装翻译提示词：
   • 主 Agent 读取 01-analysis.md（如果存在），并使用 references/subagent-prompt-template.md 的第 1 部分组装共享上下文——内嵌目标风格、内容背景、合并后的术语表以及翻译难点
   • 将其保存为输出目录中的 02-prompt.md（仅包含共享上下文，不含任务说明）
5. 通过子 Agent 起草译文（如果 Agent 工具可用）：
   • 为每个分块启动一个子 Agent，并行处理（模板第 2 部分）
   • 每个子 Agent 读取 02-prompt.md 以获取共享上下文，接收分块位置信息（第 N 块，共 M 块，并简要说明其在论述中的位置），翻译该分块，并将其保存为 chunks/chunk-NN-draft.md
   • 通过共享的 02-prompt.md（包含术语表、比喻表达映射、理解难点、原文风格以及分析中发现的翻译难点）确保一致性
   • 如果没有分块（内容低于阈值），则启动一个子 Agent 翻译整个源文件
   • 如果 Agent 工具不可用，则使用 02-prompt.md 在主流程中依次翻译各分块
6. 合并：所有子 Agent 完成后，按顺序合并已翻译的分块。如果存在 chunks/frontmatter.md，则将其置于开头。精修模式下保存为 03-draft.md，普通模式下保存为 translation.md
7. 所有中间文件（源分块和已翻译的分块）都会保留在 chunks/ 中

分块草稿合并后，将控制权交还主 Agent，以便进行严格审阅、修订和润色（第 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。

子 Agent（若在第 3.1 步使用）仅负责初稿。之后的所有步骤（批判性审阅、修订、润色）均由主 Agent 负责，主 Agent 可自行决定是否委派给子 Agent。

步骤及保存的文件（均位于输出目录中）：

1. 分析 → 01-analysis.md（领域、语气、术语、翻译难点）
2. 组装提示词 → 02-prompt.md（内嵌上下文的翻译说明）
3. 起草 → 03-draft.md（包含译者注释的初稿；分段翻译时由子 Agent 提供）
4. 批判性审阅 → 04-critique.md（仅诊断：准确性、欧洲化表达、策略执行情况、表达问题）
5. 修订 → 05-revision.md（根据所有审阅意见修订译文）
6. 润色 → translation.md（达到最终出版质量的译文）

每一步都要读取上一步的文件，并在此基础上继续。

第 5 步：输出

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

写入最终译文后，进行一次简单的图片语言检查：

1. 收集译文中的图片引用
2. 找出可能包含大量文字的图片，例如封面、截图、图表、框架图和信息图
3. 如果任何图片可能包含与译文语言不一致的主要文本语言，请主动提醒用户
4. 提醒内容只能是列表。除非用户提出要求，否则不要自动本地化这些图片

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

Possible image localization needed:
- ![example cover](attachments/example-cover.png): likely still contains source-language text while the article is now in target language
- ![example diagram](attachments/example-diagram.png): likely text-heavy framework graphic, check whether labels need translation

显示摘要：

**Translation complete** ({mode} mode)

Source: {source-path}
Languages: {from} → {to}
Output dir: {output-dir}/
Final: {output-dir}/translation.md
Glossary terms applied: {count}

如果发现语言不匹配的候选图片，在摘要后附上一条简短说明，告知用户部分嵌入图片可能仍需本地化图片文字，并列出候选图片。

扩展支持

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