文档与知识 · JimLiu/baoyu-skills
baoyu-translate
This skill should be used when the user asks to "translate", "翻译", "精翻", "translate article", "translate to Chinese", "translate to English", "改成中文", "改成英文", "convert to Chinese", "localize", "本地化", "refined translation", "精细翻译", "proofread translation", "快速翻译", "快翻", "这篇文章翻译一下", or provides a URL/file with translation intent. Supports three modes (quick/normal/refined) with custom glossary support.
L4 高权限 · 分级授权与审计V1 已固定执行命令联网读写文件Dual-pass Audit
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。
1实现原理 · 为什么它能做到
三档模式（quick / normal / refined）不是脚本参数，而是 prompt 编排的流水线：quick 直接译，normal 先分析再译，refined 走『分析→译→评审→修订→润色』并逐步落盘。
skills/baoyu-translate/SKILL.md
| Refined | `--mode refined` | Analyze → Translate → Review → Polish | Publication-quality, important documents |
这里在做什么：脚本只管切块，译文质量由 SKILL.md 定义的步骤与参考文件（refined-workflow.md）驱动；每一步的产物都留在输出目录，可回溯每一步做了什么。
长文切块是纯本地的 markdown 块级切分：chunk.ts 用 markdown-it 解析块边界，按字数（默认 5000）切，超长块再退化为按行、按词切。
skills/baoyu-translate/scripts/chunk.ts
const maxWords = options.maxWords ?? 5000
切在 markdown 块边界是为了不把标题/列表/表格/代码块切碎；CJK 字符单独计数，避免中文被低估字数。
跨块译名一致靠『共享上下文文件』而不是靠模型记忆：main agent 先把风格、背景、合并术语表、翻译难点写进 02-prompt.md，每个 chunk 的 subagent 读同一份。
skills/baoyu-translate/SKILL.md
Consistency is guaranteed by the shared `02-prompt.md`
这正是它敢并行翻译不产生术语漂移的原因：上下文是文件而非对话。
术语来源四级合并，优先级明确：EXTEND.md 内联 → EXTEND.md 外部术语文件 → 内置 EN→ZH 表 → CLI --glossary（最高）。
skills/baoyu-translate/SKILL.md
Merge glossaries: EXTEND.md `glossary` (inline) + EXTEND.md `glossary_files` (external files, paths relative to EXTEND.md location) + built-in glossary + `--glossary` file (CLI overrides all)
内置表 references/glossary-en-zh.md 提供开箱一致的技术/产品名词译法。
每个 chunk 起一个 subagent 并行翻译，subagent 无宿主工具也能退化为串行内联翻译。
skills/baoyu-translate/SKILL.md
Spawn one subagent **per chunk**, all in parallel
subagent 提示词模板在 references/subagent-prompt-template.md：读 {output_dir}/02-prompt.md 作为共享上下文，把译文写到 chunks/chunk-{NN}-draft.md。
首次使用是阻塞式设置：找不到 EXTEND.md 必须先问用户偏好并写入，不允许静默用默认值开跑。
skills/baoyu-translate/references/config/first-time-setup.md
**BLOCKING OPERATION**: This setup MUST complete before ANY translation.
避免『默认目标语言不是你想要的』这类静默错误；同时把偏好落到项目/XDG/家目录三档之一的 EXTEND.md。
URL 输入不联网的是脚本：SKILL.md 只要求 agent『物化来源』——把网页内容抓下来存成本地 md，脚本从头到尾只处理本地文件。
skills/baoyu-translate/references/workflow-mechanics.md
| URL | Fetch content, save to `translate/{slug}.md` |
这里在做什么：网络动作划归宿主 agent，skill 自带脚本保持零网络面（chunk.ts 只 import fs/path/markdown-it）。
输出目录约定固定、冲突时改名备份而不覆盖：`{source-dir}/{source-basename}-{target-lang}/`，已存在则先改名。
skills/baoyu-translate/references/workflow-mechanics.md
Create a subdirectory next to the source file: `{source-dir}/{source-basename}-{target-lang}/`
配合固定文件名（translation.md / 01-analysis.md … 05-revision.md），使多次翻译互不覆盖、可对比。
2核心能力
01三档翻译模式（quick 直译 / normal 分析后译 / refined 出版级评审润色）
029 种语气风格 + 4 种受众预设（可自定义文字描述）
03自定义术语表（内联 / 外部文件 / 内置 EN→ZH / CLI 四级合并）
04长文自动分块 + 每块一个 subagent 并行翻译（共享 prompt 保一致）
05分块阈值与块大小可配（EXTEND.md chunk_threshold / chunk_max_words）
06精翻留档：01-analysis / 02-prompt / 03-draft / 04-critique / 05-revision / translation.md
07翻译原则显式化：重写而非直译、术语一致、保留 markdown 结构、按需加解释性括注
08交付后做图片语言体检（列出可能仍含原文的图，只提醒不自动改图）
09偏好持久化 EXTEND.md（项目 / XDG / 家目录三档，首次阻塞式设置）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| package | markdown-it 14.1.1（唯一运行时依赖） |
| package | markdown-it 运行时 import |
| cli | bun（脚本 shebang 运行时） |
| cli | npx -y bun（无 bun 时的回退运行时） |
| network | homepage 元数据 URL（静态 frontmatter，任何步骤都不抓取） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: ${BUN_X} {baseDir}/scripts/main.ts <file> [--max-words N] [--output-dir D]（
- 网络端点: 声明外部网络访问: skill 自带脚本零网络调用：chunk.ts 只 import fs / path / markdown-it，package.json 无 ht
- 本地工作目录: 文件读写与工件输出: {source-dir}/{source-basename}-{target-lang}/ 输出目录（已存在则先改名为 {name}.backup-Y
审计说明： 。判级对象＝本 skill 目录：自带 scripts/main.ts + chunk.ts（markdown-it 纯本地切块），唯一依赖 markdown-it@14.1.1，行为是读一个本地文件、写出 chunks/ 与输出目录，全目录无网络端點、无凭证/环境变量读取、无子进程 spawn → 蓝（不是 green：自带脚本且主动写盘；不是 yellow：skill 自身不访问任何外部端點，出图/翻译后端一概不涉及）。URL 输入的抓取发生在宿主 agent 侧（SKILL.md 只要求物化来源），按批4 口径不作为档位依据，但已写入 risks。
5第二遍独立确认
- [ok] 脚本零网络、零凭证 — chunk.ts 仅 import fs/path/markdown-it，main.ts 仅 import node:process + ./chunk.js；grep http/fetch/curl/process.env/API_KEY 在两个脚本内零命中。
- [ok] 切块逻辑与 SKILL.md 描述一致 — chunk.ts 用 markdown-it 解析、在块边界切分、超长块退化处理，默认 maxWords 5000，与 SKILL.md『Splits at markdown block boundaries to preserve structure』一致；frontmatter 被单独抽出为 chunks/frontmatter.md。
- [ok] 依赖面 = markdown-it 单包 — package.json 仅声明 markdown-it 14.1.1，bun.lock 中的其余条目均为其传递依赖（argparse/entities/linkify-it/mdurl/punycode.js/uc.micro），无 postinstall、无网络行为。
- [ok] subagent 分工与模板内容 — subagent-prompt-template.md 明确 shared context → 02-prompt.md、每块产出 chunks/chunk-{NN}-draft.md；spawn 动作由 agent 执行，脚本不 spawn 任何进程。
- [ok] URL 输入的网络归属 — workflow-mechanics.md 把 URL 处理写成 agent 的『Fetch content』动作；本 skill 目录内无抓取代码，故网络面不落在 skill 自身。
- [ok] EXTEND.md 路径不一致（轻微） — SKILL.md 列三条路径（含 XDG），references/config/extend-schema.md 只列项目与家目录两条；属文档不一致，不影响判级，已在 traits/risks 采信 SKILL.md 的三档说法。
- [ok] 元数据与 pin — 本地 HEAD = 1567581c26ec29f4216c6e6835415bf30343b0e3；GitHub API MIT / 25926 stars / pushed_at 2026-09-10T15:13:43Z；仓库根 LICENSE 为 MIT。
6结论
适合： 适合需要『出版级』中文/英文长文的个人与团队：技术博客、教程、研究报告、书稿章节；也适合有固定术语表的团队（用 EXTEND.md 锁译名）、需要并行提速的长文（分块 + subagent）、以及希望保留每步产物以便审校的流程。
不适合： 不适合一句话短译（quick 之外的开销不值得）；不适合没有 Agent/subagent 能力又不愿串行等待长文的环境；不适合期望 skill 自动抓取任意网站内容的场景（抓取是宿主职责）；也不适合把不可信网页文本直接翻译后发布而无人复核的流程。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload baoyu-translate.tar.gz
sha256:
Option B · Copy Guide for Agent38c8846f411e3248…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 1567581c26.