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 纯本地切块），唯一依赖 [email protected]，行为是读一个本地文件、写出 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.