docs(i18n): adopt jingtingxiang's calibrated terminology table and five gold pairs

术语表整体采用 jingtingxiang 的重构版（PR #244）：按缩写类/英文类/
双语类分节、通用规则前置、首次出现与不要译作独立列；保留本 stack
的 mock/package/counterpart 与 agent 组合词裁定行。五组金标译文按
其定稿采用（development、i18n README、translation-rules、双语 RFC、
根 README），README.zh 吸收 PR #249 的两处措辞（「智能体辔架」括注
与其自身新表冲突，未采用）。translation-prompt.md 增补 Few-shot 金
标一节：声明这 5 组配对即流水线的整文档级 few-shot，注入方式为多轮
示例对话。style-samples 的 blob hash 译法按新表回改为保留英文。

Supersedes the .zh.md content of #244/#249/#264.

README.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 README.md: 7ddf68bab06ecf891856e6d1393ccdefd9eeba38
-README.zh.md: 59a0419164f2dfee6f66903cc93d7b35da1d9063
+README.zh.md: ad568c808d4c8003a84734bc8035fac9a07d27b4

README.zh.md

@@ -6,7 +6,7 @@
 
 ## 开发
 
-本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：一切皆插件。
+本 monorepo 基于 [Cordis](https://github.com/cordiverse/cordis) 框架构建（以源码形式收录在 `vendor/` 下），采用微内核风格：所有功能都以插件形式提供。
 
 ```sh
 pnpm install
@@ -15,6 +15,6 @@ pnpm run demo:repl     # REPL agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```
 
-面向人类读者：先读[开发指南](docs/development.md)了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。
+面向开发者：先读[开发指南](docs/development.md)，了解本地环境搭建、钩子、环境变量与质量门禁，动手改 package 之前再读[架构设计](docs/architecture.md)。局部上下文见 [packages/](packages/) 与 [vendor/](vendor/)。
 
 面向 agent：遵循 [AGENTS.md](AGENTS.md)。

docs/development.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 development.md: 28babca2b59c844690750d767c242c08c37bf702
-development.zh.md: b34c52cebd3f333b6554ca2b5ebd66463e436572
+development.zh.md: 91b63d7511f856f21162f8ab66eae6e25d925059

docs/development.zh.md

@@ -2,14 +2,14 @@
 
 [English](development.md) | 中文
 
-本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你理解本地钩子、日常检查与 CI 门禁。
+本指南覆盖参与 DeepSeek Harness 开发所需的本地环境搭建，并帮助你了解本地钩子、日常检查与 CI 门禁。
 
 ## 前置条件
 
-- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上跑矩阵。
-- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中钉住 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，先运行 `corepack enable`。
+- Node.js 24 或更新版本。仓库声明 `node >=24`；CI 在 Node 24 和 26 上运行矩阵测试。
+- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。
 - Git。
-- 可选：一个 DeepSeek API key，用于 REPL/ACP agent（智能体）演示和真实 API 的 e2e 测试。
+- 可选：一个 DeepSeek API key，用于 REPL/ACP agent 演示和真实 API 的 e2e 测试。
 
 ## 首次搭建
 
@@ -19,23 +19,23 @@
 pnpm install
 ```
 
-安装同时会运行根目录的 `postinstall` 脚本，它通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook；该包装脚本使用 lefthook 经过评审的 `--force` 模式，使已存在 `core.hooksPath` 的关联 worktree 不会让正常的 `pnpm run …` 命令失败。
+安装过程同时会运行根目录的 `postinstall` 脚本，该脚本通过 `scripts/install-lefthook.mjs` 从仓库 dev 依赖安装 lefthook。包装脚本使用 lefthook 经过评审的 `--force` 模式，确保已存在 `core.hooksPath` 的关联 worktree 不会导致正常的 `pnpm run …` 命令失败。
 
-如果因为依赖是从缓存恢复或 `postinstall` 被跳过而缺少钩子，手动安装：
+如果依赖是从缓存恢复或 `postinstall` 被跳过而导致缺少钩子，请手动安装：
 
 ```sh
 pnpm exec lefthook install --force
 ```
 
-新克隆后先跑一次类型检查：
+新克隆后请先运行一次类型检查：
 
 ```sh
 pnpm run typecheck
 ```
 
-这次首跑会构建 package/vendor 构建图，并跑根目录 no-emit `tsconfig.json` 图（覆盖 examples、tests 和 scripts）。根图使用同一份源码 `paths` 映射，但依赖 project references，因此 vendor 代码在它自己的 tsconfig 设置下被检查。
+首次类型检查会执行 package/vendor 的构建图，以及根目录下用于示例、测试和脚本的 no-emit `tsconfig.json` 项目图。根图使用同一份源码 `paths` 映射，但依赖 project references，因此 vendor 代码在它自己的 tsconfig 设置下被检查。
 
-如果准备从新克隆或新 worktree 推送，还要构建一次：
+如果准备从新克隆或新 worktree 推送，还需要构建一次：
 
 ```sh
 pnpm run build
@@ -45,29 +45,29 @@ pnpm run build
 
 ## 环境变量
 
-真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 读取凭证：
+真实的 DeepSeek 适配器和需要密钥的 agent 演示从环境变量或仓库根目录一个被 gitignore 的 `.env` 文件读取凭证：
 
 ```sh
 DEEPSEEK_API_KEY=sk-...
 DEEPSEEK_BASE_URL=https://... # optional
 ```
 
-`DEEPSEEK_BASE_URL` 可选，默认为公开 API。绝不要提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。
+`DEEPSEEK_BASE_URL` 可选，默认为公开 API。请勿提交真实凭证。未设置 `DEEPSEEK_API_KEY` 时，真实 API 的 e2e 套件会自动跳过。
 
 ## Git 钩子
 
 lefthook 在 `lefthook.yml` 中配置，作为评审前的本地早期检查点：
 
-- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫。
+- `pre-commit` 运行对暂存文件的 ESLint 修复、`pnpm run typecheck` 和 vendor manifest 守卫；
 - `pre-push` 运行 `pnpm run test`、`pnpm run test:snapshot`、`pnpm run hygiene`、`pnpm run doc-sync` 和 `pnpm run verify-module-graph`。
 
-vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。编辑 vendor 代码前先看 `vendor/README.md`。
+vendor manifest 守卫检查 `vendor/*/src` 下的改动是否连同对应的 `vendor/README.md` manifest 更新一起暂存。请在编辑 vendor 代码前先阅读 `vendor/README.md`。
 
-这些钩子并不与 CI 完全一致。特别是：`pre-push` 跑不带覆盖率的单元测试，而 CI 跑 `pnpm run test:coverage`；CI 还会跑 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上跑矩阵。
+这些钩子并不与 CI 完全一致。特别是：`pre-push` 运行不带覆盖率的单元测试，而 CI 运行 `pnpm run test:coverage`；CI 还会运行 echo-agent 和 built-bin 冒烟测试，并在 Node 24 和 26 上运行矩阵。
 
 ## CI 门禁
 
-GitHub 工作流在每个 pull request 上运行这些门禁：
+GitHub 工作流在每个 Pull Request 上运行以下门禁：
 
 - `pnpm install --frozen-lockfile`
 - `pnpm run constraints`
@@ -82,7 +82,7 @@ GitHub 工作流在每个 pull request 上运行这些门禁：
 - 一个 echo-agent 冒烟测试，检查演示的工具调用、工具结果和 JSONL 输出
 - built-bin 冒烟测试，用纯 `node` 运行发布产物 `lib/bin.js` 入口
 
-`pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会把 `pnpm run constraints` 作为更早的快速失败步骤单独跑一次，然后在 `pnpm run build` 之后跑完整的 hygiene 脚本。
+`pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会将 `pnpm run constraints` 作为更早的快速失败步骤单独运行一次，然后在 `pnpm run build` 之后运行完整的 hygiene 脚本。
 
 ## 日常命令
 
@@ -96,9 +96,13 @@ pnpm run typecheck      # build package/vendor outputs, then typecheck examples,
 pnpm run lint           # eslint .
 pnpm run lint:fix       # eslint . --fix
 pnpm run doc-typecheck  # compile checked TypeScript snippets in Markdown docs
-pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events-and-services.md from source
-pnpm run verify-cordis-catalog  # fail if the cordis events/services catalog is stale
+pnpm run gen-cordis-catalog     # regenerate docs/cordis-catalog/events.md + services.md from source
+pnpm run verify-cordis-catalog  # fail if either cordis catalog is stale
+pnpm run gen-doc-graphs     # regenerate generated relationship docs from source and curated graph definitions
+pnpm run verify-doc-graphs  # fail if generated relationship docs are stale
+pnpm run gen-rfc-index          # regenerate the docs/rfc/README.md index tables from the RFC tree
 pnpm run verify-md-wrap  # fail on hard-wrapped prose paragraphs in docs/README markdown
+pnpm run verify-mermaid  # fail if a ```mermaid diagram has invalid Mermaid syntax
 pnpm run verify-type-equiv  # fail if a ```ts type-equiv doc block drifts from its source type
 pnpm run verify-doc-budgets  # fail if a budgeted standing doc exceeds its word ceiling
 pnpm run doc-sync       # all Markdown/doc gates; see the doc-sync script in package.json for the full list
@@ -109,7 +113,7 @@ pnpm run verify-node-next-types  # fail if built declarations are not NodeNext-c
 pnpm run hygiene        # knip, publint, workspace constraints, and NodeNext declaration check
 ```
 
-改动 package 的公开行为时，在同一个变更里更新相关 README 或 JSDoc。`pnpm run doc-sync` 能抓住被检查的 TypeScript 片段、cordis 事件/服务目录漂移和硬折行的 markdown 段落，但更广泛的行文/API 同步仍需评审把关。
+修改 package 的公开行为时，请在同一个变更中更新相关 README 或 JSDoc。`pnpm run doc-sync` 能检测到被检查的 TypeScript 片段、生成文档的新鲜度、Markdown 换行/链接漂移、type-equiv、翻译配对、Mermaid 语法和文档预算，但更广泛的行文/API 同步仍需评审把关。
 
 ## 演示
 
@@ -133,24 +137,24 @@ pnpm run demo:acp
 
 ## TODO 标记
 
-用三种注释标签之一标记代码中的已知问题，按紧急程度排序：
+请使用以下三种注释标签之一标记代码中的已知问题，按紧急程度排序：
 
-- `FIXME`——应当阻塞新版本发布的问题。除非评审者明确同意可以照常合入，发布不应带着未解决的 `FIXME` 出门。
-- `TODO`——应当尽快修复的问题，等资源到位就处理。
-- `XXX`——也许某天会修的问题；优先级最低，不作承诺。
+- `FIXME`：应当阻塞新版本发布的问题。除非评审者明确同意该更改可以合并，否则发布版本不应包含未解决的 `FIXME`；
+- `TODO`：应当尽快修复的问题，等资源到位即可处理；
+- `XXX`：也许某天会修复的问题，优先级最低，不作承诺。
 
-选择与紧急程度匹配的标签，让扫代码的人一眼分清「发布阻塞」和「有空再说」。
+请选择与紧急程度匹配的标签，让浏览代码的人一眼分清「发布阻塞」和「有空再说」。
 
 ## 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，把它围栏成 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[核心数据结构](core-data-structures/core.md)文档粘贴真实的类型定义，让读者看到确切的形状。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义，语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然，因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型，门禁会失败直到你更新粘贴内容；当你增删一个块，在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明，并断言文档块与之一致（对空白和注释不敏感，因此文档块可以展示干净的定义，语义由行文承载）。它还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然；因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个被记录的类型时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。
 
 ## 架构上下文
 
-改动 `packages/` 下的任何东西之前先读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam（扩展点）与显式扩展点构建。
+在修改 `packages/` 目录下的任何内容之前，请先阅读 `docs/architecture.md`。这套代码围绕 Cordis 插件、事件溯源的会话、类型化的服务 seam 与显式扩展点构建。

docs/i18n/style-samples.md

@@ -54,7 +54,7 @@
 
 > Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. The recorded hash also recovers the exact last-confirmed text of either side (`git cat-file -p <hash>`), so an out-of-sync pair is updated by diffing the edited side against its last-confirmed state and patching the counterpart minimally — never by re-translating whole files.
 
-系统采用文件 blob 哈希而非提交哈希记录状态。同一 PR 内修改文件时，可通过 `git hash-object foo.md` 直接算出对应哈希，仅对比文件内容即可判断双语文档是否同步。通过记录的哈希值，可使用 `git cat-file -p <hash>` 还原上次确认对齐时两侧的原文。当双语文档不一致时，只需对比修改版本与上次确认版本的差异，最小幅度同步修改另一侧译文，无需全文重新翻译。
+系统采用文件 blob hash 而非 commit hash 记录状态。同一 PR 内修改文件时，可通过 `git hash-object foo.md` 直接算出对应 blob hash，仅对比文件内容即可判断双语文档是否同步。通过记录的 blob hash，可使用 `git cat-file -p <hash>` 还原上次确认对齐时两侧的原文。当双语文档不一致时，只需对比修改版本与上次确认版本的差异，最小幅度同步修改另一侧译文，无需全文重新翻译。
 
 ## ⑤ 政策声明
 

docs/i18n/terminology.md

@@ -1,148 +1,165 @@
 # Terminology
 
-本表约定本仓库的中英术语统一译法。各列语义：
+本表约定本仓库的中英术语统一译法。
 
-- **中文** — 正文中的固定译法；写「保留英文」表示不译。
-- **首次出现** — 术语在一篇文档中第一次出现时的完整写法（含括注）；之后只写「中文」列的形式。组合词已括注过的成分，单独出现时不再括注。
-- **不要译作** — 禁用译法，逐项列出；出现任何一项即评审阻断。
-- **备注** — 语境区分、裁定出处等自由说明；不承载可执行规则。
+**通用规则：**
+- "中文"列为中文译文的正文默认用词。若该列为英文，则中文译文的正文中保留英文不翻译。
+- 首次出现按"首次出现"列书写（带括号注释）；后续出现只写括号前的部分（可能为中文，也可能为英文），不出现括号内的注释。
+- "不要译作"列为严格禁止的译法。
+- 如果某术语已经作为另一个术语的组成部分被括注过（如 `agent loop（智能体循环）` 中已包含 `agent` 的括注），则该术语后续单独出现时无需再次括注。
+
+## 缩写类（中英文文本中均使用缩写）
+
+| English | 中文 | 首次出现 | 不要译作 | 备注 |
+|---|---|---|---|---|
+| ACP | ACP | ACP（Agent Client Protocol） | | |
+| AI | AI | AI（人工智能） | | |
+| API | API | | | |
+| CI | CI | | | |
+| CLI | CLI | CLI（命令行界面） | | |
+| e2e | e2e | | | |
+| HMR | HMR | HMR（热模块替换） | | |
+| JSON Schema | JSON Schema | | | |
+| JSONL | JSONL | | | |
+| LLM | LLM | LLM（大语言模型） | | |
+| MCP | MCP | | | |
+| PR | PR | PR（Pull Request） | | |
+| RAG | RAG | RAG（检索增强生成） | | |
+| SDK | SDK | | | |
+| SSE | SSE | SSE（Server-Sent Events） | | |
+
+## 英文类（中英文文本中均使用英文）
+
+| English | 中文 | 首次出现 | 不要译作 | 备注 |
+|---|---|---|---|---|
+| agent | agent | agent（智能体） | | |
+| agent harness | agent harness | | | agent 组合词（agent harness/workflow/loop/skill 等）整体保留英文；未括注过 agent 时首现按 agent 行处理 |
+| agent loop | agent loop | agent loop（智能体循环） | | |
+| backlog | backlog | backlog（待翻清单） | | 仅在双语翻译语境里括注`待翻清单` |
+| blob hash | blob hash | | | `git hash-object` 的结果 |
+| Cordis | Cordis | | | |
+| dispose | dispose | dispose（资源释放） | | |
+| doc-sync | doc-sync | doc-sync（文档同步门禁） | | |
+| fiber | fiber | fiber（插件运行时） | | |
+| fixture | fixture | fixture（测试前置数据） | | |
+| fork | fork | | | |
+| Function Calling | Function Calling | Function Calling（函数调用） | | |
+| harness | harness | | | |
+| harness engineering | harness engineering | | | |
+| lint | lint | | | |
+| mock | mock | | | 保留英文；指测试替身 |
+| loader | loader | | | |
+| manifest | manifest | manifest（元数据清单） | | |
+| monorepo | monorepo | | | |
+| package | package | | | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） |
+| schema | schema | | | |
+| schema DSL | schema DSL | | | |
+| seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` |
+| skill | skill | skill（技能） | | |
+| spawn | spawn | | | |
+| steering | steering | steering（中途引导） | | |
+| subagent | subagent | | | |
+| thinking | thinking | | | API 字段保留英文；描述模型模式时译为`思考` |
+| transcript | transcript | transcript（文本记录） | | 指会话渲染给用户或编辑器的完整文本，区别于事件日志 |
+| waterfall | waterfall | waterfall（瀑布式事件） | | |
+| worktree | worktree | | | git 工作区概念 |
+
+## 双语类（中英文文本各自使用中英文）
 
 | English | 中文 | 首次出现 | 不要译作 | 备注 |
 |---|---|---|---|---|
-| ACP | ACP | ACP（Agent Client Protocol） |  |  |
-| AI | AI | 人工智能（AI） |  |  |
-| API | API |  |  | real-API 作定语时可译「真实接口」（如 real-API tests → 真实接口测试） |
-| CI | CI |  |  |  |
-| CLI | CLI | 命令行界面（CLI） |  |  |
-| Cordis | Cordis |  |  | 保留英文 |
-| Function Calling | Function Calling | Function Calling（函数调用） |  |  |
-| HMR | HMR | 热模块替换（HMR） |  |  |
-| JSON Schema | JSON Schema |  |  |  |
-| JSONL | JSONL |  |  |  |
-| lint | lint |  |  |  |
-| loader | loader |  |  |  |
-| LLM | LLM | 大语言模型（LLM） |  |  |
-| MCP | MCP |  |  |  |
-| PR | PR | PR（pull request） |  |  |
-| RAG | RAG | 检索增强生成（RAG） |  |  |
-| SDK | SDK |  |  |  |
-| SSE | SSE | SSE（Server-Sent Events） |  |  |
-| agent | agent | agent（智能体） |  | 括注只落在 agent 单独首现处；组合词见下行 |
-| agent harness, agent workflow, agent loop, agent skill | 保留英文 |  |  | agent 组合词整体保留英文、不括注；其中的 workflow/loop/skill 不单独拆译；未列出的 agent 组合词同此处理 |
-| backlog | backlog |  |  | 双语翻译语境指待翻清单 |
-| blob hash | blob 哈希 |  |  | git 对象哈希；`git hash-object` 的结果 |
-| commit hash | 提交哈希 |  |  |  |
-| hash | 哈希 |  |  | 代码与命令中保留英文（如 `git hash-object`、`<hash>` 占位符） |
-| doc-sync | doc-sync |  |  | 仓库门禁名，保留英文 |
-| e2e | e2e |  |  |  |
-| fiber | fiber | fiber（插件运行时） |  |  |
-| fixture | fixture |  |  | 指测试前置数据或环境 |
-| fork | fork |  |  | 保留英文 |
-| harness | harness |  |  | 保留英文 |
-| manifest | manifest |  |  | 描述模块或工具元数据的文件 |
-| monorepo | monorepo |  |  |  |
-| package | package |  |  | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） |
-| schema DSL | schema DSL |  |  |  |
-| schema | schema |  |  | 保留英文 |
-| seam | seam | seam（扩展点） |  | 同句已出现「扩展点」（extension point）时不加括注，直接写 seam，避免一词两指 |
-| skill | skill | skill（技能） |  |  |
-| spawn | spawn |  |  | 保留英文 |
-| steering | steering | steering（中途引导） |  |  |
-| subagent | subagent | subagent（子 agent） |  |  |
-| transcript | transcript | transcript（文本记录） |  | 指会话渲染给用户或编辑器的完整文本，区别于事件日志（event log） |
-| waterfall | waterfall | waterfall（瀑布式事件） |  |  |
-| worktree | worktree |  |  | git 工作区概念，保留英文 |
-| wire format | 协议格式 | 协议格式（wire format） |  |  |
-| adapter contract | 适配器契约 | 适配器契约（adapter contract） |  |  |
-| adapter | 适配器 |  |  |  |
-| append-only | 仅追加 |  |  |  |
-| artifact | 产物 |  |  |  |
-| block | 块 |  |  |  |
-| background task | 后台任务 |  |  |  |
-| backend | 后端 |  |  |  |
-| capability | 能力 |  |  |  |
-| cancel | 取消 |  |  |  |
-| checkpoint | 检查点 |  |  |  |
-| chunk | 分片 |  |  |  |
-| compaction | compaction | compaction（上下文压缩） |  | 正文优先保留英文 |
-| consumer | 消费方 |  |  |  |
-| counterpart | 对侧文件 |  | 对应物、配对物 | 双语配对语境；泛指“另一侧”时可写「另一侧」 |
-| content block | 内容块 |  |  |  |
-| config | 配置 |  |  |  |
-| context | 上下文 |  |  |  |
-| context compaction | 上下文压缩 | 上下文压缩（context compaction） |  |  |
-| contract | 契约 |  |  | 如：配对契约（pairing contract）；另见 adapter contract |
-| coverage | 覆盖率 |  |  |  |
-| crash recovery | 崩溃恢复 |  |  |  |
-| dispose | dispose | dispose（释放资源） |  | 正文优先保留英文 |
-| durability | 持久性 |  |  |  |
-| enforcement frontier | 强制边界 |  |  | i18n 机制词：manifest `required` 清单所划的门禁生效范围 |
-| event log | 事件日志 |  |  |  |
-| event | 事件 |  |  |  |
-| event stream | 事件流 |  |  |  |
-| event-sourced | 事件溯源 |  |  | DDD 社区通行译法 |
-| executor | 执行器 |  |  |  |
-| extension | 扩展 |  |  |  |
-| fail-fast | 快速失败 |  |  |  |
-| fenced code block | 围栏代码块 |  |  | MDN 中文同译 |
-| finish reason | 结束原因 |  |  |  |
-| fingerprint | 指纹 |  |  | i18n 机制词：`.zh.md` 首行记录英文源 blob hash 的 `i18n-source` 注释 |
-| foreground run | 前台运行 |  |  |  |
-| freshness | 新鲜度 |  |  | MDN HTTP 缓存中文同译（freshness lifetime → 新鲜度生命周期）；指译文相对英文源的同步状态 |
-| hook | 钩子 |  |  |  |
-| implementation | 实现 |  |  |  |
-| inference | 推理（inference） |  |  | 每次提及时保留英文括注，避免与 reasoning 混淆 |
-| info string | 信息字符串 |  |  | CommonMark 中文同译；代码围栏 ``` 之后的语言标注 |
-| injection | 注入 |  |  |  |
-| interface | 接口 |  |  |  |
-| integration | 集成 |  |  |  |
-| language switcher | 语言切换行 |  |  | i18n 机制词：双语配对文件顶部的互链行 |
-| memory | memory / 记忆 / 内存 |  |  | 按上下文区分：agent memory 译为“记忆”；resource/memory usage 译为“内存” |
-| message | 消息 |  |  |  |
-| mock | mock |  |  | 保留英文；指测试替身 |
-| mod | 模组 |  |  | 区别于 module（模块）；plugin 译作「插件」 |
-| model provider | 模型提供方 |  |  |  |
-| module | 模块 |  |  |  |
-| orphan | 孤立 |  | 孤儿 | git 官方中文同译（如「孤立分支」）；指英文源已不存在的 `.zh.md`；进程语境按 OS 惯用语译「孤儿进程」 |
-| pairing | 配对 |  |  |  |
-| permission | 权限 |  |  |  |
-| persistence | 持久化 |  |  |  |
-| pipeline | 流水线 |  |  |  |
-| plugin | 插件 |  |  | mod 对应“模组” |
-| prompt | 提示词 |  |  |  |
-| provider | 提供方 |  |  |  |
-| provider-neutral | 提供方无关 |  |  |  |
-| quality gate | 质量门禁 |  |  |  |
-| registry | 注册表 |  |  |  |
-| reasoning | 推理（reasoning） |  |  | 需要和 inference 区分时保留英文括注；`reasoning_content` 译为“思考内容” |
-| replay | 回放 |  |  |  |
-| resume | 恢复 |  |  |  |
-| runtime | 运行时 |  |  |  |
-| sandbox | 沙箱 |  |  |  |
-| service | 服务 |  |  |  |
-| session | 会话 |  |  |  |
-| session event | 会话事件 |  |  |  |
-| sidecar record | 伴随记录 |  | 旁挂记录 | 指 `.i18n.yaml` 这类随主文件存放的记录文件 |
-| smoke test | 冒烟测试 |  |  |  |
-| snapshot | 快照 |  |  |  |
-| source of truth | 真源 | 真源（source of truth） |  | 评审裁定译法；如后续裁定调整，改此表即可 |
-| spine | 主干 |  |  |  |
-| staged | 暂存 |  |  | git 官方中文同译 |
-| stale | 陈旧 |  |  | MDN HTTP 缓存中文同译，与「新鲜（fresh）」成对；门禁输出保留英文 `stale`；expired 才译「过期」 |
-| step | 步骤 |  |  |  |
-| stream | 流 |  |  |  |
-| streaming | 流式输出 |  |  |  |
-| structural signature | 结构签名 |  |  | i18n 机制词：配对门禁比对的有序结构序列 |
-| system prompt | 系统提示词 |  |  |  |
-| taxonomy | 分类体系 |  |  |  |
-| token usage | token 用量 |  |  |  |
-| thinking | thinking |  |  | API 字段保留；模型模式译为“思考” |
-| tool | 工具 |  |  |  |
-| tool call | 工具调用 |  |  |  |
-| tool result | 工具结果 |  |  |  |
-| tool schema | 工具 schema |  |  |  |
-| toolkit | 工具包 |  |  |  |
-| turn | 轮次 |  |  |  |
-| typecheck | 类型检查 |  |  |  |
-| vocabulary | 词汇 |  |  |  |
-| workflow | 工作流 |  |  |  |
+| adapter | 适配器 | | | |
+| adapter contract | 适配器契约 | 适配器契约（adapter contract） | | |
+| append-only | 仅追加 | | | |
+| artifact | 产物 | | | |
+| backend | 后端 | | | |
+| background task | 后台任务 | | | |
+| block | 块 | | | |
+| cancel | 取消 | | | |
+| capability | 能力 | | | |
+| checkpoint | 检查点 | | | |
+| chunk | 分片 | | | |
+| compaction | 压缩 | 压缩（compaction） | | |
+| config | 配置 | | | |
+| consumer | 消费方 | | | |
+| content block | 内容块 | | | |
+| context | 上下文 | | | |
+| counterpart | 对侧文件 | | 对应物、配对物 | 双语配对语境；泛指"另一侧"时可写「另一侧」 |
+| context compaction | 上下文压缩 | 上下文压缩（context compaction） | | |
+| contract | 契约 | | | 如：`pairing contract` →`配对契约` |
+| coverage | 覆盖率 | | | |
+| crash recovery | 崩溃恢复 | | | |
+| durability | 持久性 | | | |
+| enforcement frontier | 强制边界 | | | i18n 配对机制用语：manifest `required` 清单所划的门禁生效范围 |
+| event | 事件 | | | |
+| event log | 事件日志 | | | |
+| event stream | 事件流 | | | |
+| event-sourced | 事件溯源 | | | 沿用 DDD 社区通行译法 |
+| executor | 执行器 | | | |
+| extension | 扩展 | | | |
+| extension point | 扩展点 | | | 注意与 `seam` 区分 |
+| fail-fast | 快速失败 | | | |
+| fenced code block | 围栏代码块 | | | 沿用 MDN 中文翻译 |
+| fingerprint | 指纹 | | | i18n 配对机制用语：`.zh.md` 首行记录英文源 blob hash 的注释 |
+| finish reason | 结束原因 | | | |
+| foreground run | 前台运行 | | | |
+| freshness | 新鲜度 | | | 沿用 MDN 中文翻译；在本项目中指译文相对源文的同步状态 |
+| hook | 钩子 | | | |
+| implementation | 实现 | | | |
+| inference | 推理 | 推理（inference） | | 需要和 `reasoning` 区分时保留英文括注 |
+| info string | 信息字符串 | | | 沿用 CommonMark 中文翻译；指代码围栏 ``` 之后的语言标注 |
+| injection | 注入 | | | |
+| integration | 集成 | | | |
+| interface | 接口 | | | |
+| language switcher | 语言切换行 | | | i18n 配对机制用语：双语配对文件顶部的互链行 |
+| memory | 记忆 / 内存 | | | 与 `agent` 搭配时译为`记忆`（如 `agent memory` →`智能体记忆`）；指系统资源时译为`内存` |
+| merge | 合并 | | | |
+| message | 消息 | | | |
+| mod | 模组 | | | |
+| model provider | 模型提供方 | | | |
+| module | 模块 | | | |
+| orphan | 孤立 | | 孤儿 | 指英文源已不存在的 `.zh.md` |
+| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
+| pairing | 配对 | | | |
+| permission | 权限 | | | |
+| persistence | 持久化 | | | |
+| pipeline | 流水线 | | | |
+| plugin | 插件 | | | |
+| prompt | 提示词 | | | |
+| provider | 提供方 | | | |
+| provider-neutral | 提供方无关 | | | |
+| quality gate | 质量门禁 | | | |
+| reasoning | 推理 | 推理（reasoning） | | 需要和 `inference` 区分时保留英文括注 |
+| reasoning_content | 思考内容 | | | |
+| registry | 注册表 | | | |
+| replay | 回放 | | | |
+| resume | 恢复 | | | |
+| runtime | 运行时 | | | |
+| sandbox | 沙箱 | | | |
+| service | 服务 | | | |
+| session | 会话 | | | |
+| session event | 会话事件 | | | |
+| sidecar record | 伴随记录 | | 旁挂记录 | 指与文档同目录的伴随记录文件 |
+| smoke test | 冒烟测试 | | | |
+| snapshot | 快照 | | | |
+| source of truth | 真源 | | | |
+| spine | 主干 | | | |
+| staged | 暂存 | | | 沿用 git 官方中文翻译 |
+| stale | 陈旧 | | 过期 | 与 `fresh`（`新鲜`）成对；门禁输出中保留英文 `stale` 不翻译；`expired` 才译为`过期` |
+| step | 步骤 | | | |
+| stream | 流 | | | |
+| streaming | 流式输出 | | | |
+| structural signature | 结构签名 | | | i18n 配对机制用语：门禁比对两侧文件时提取的有序结构序列（标题层级、代码块、列表等） |
+| system prompt | 系统提示词 | | | |
+| taxonomy | 分类体系 | | | |
+| token usage | token 用量 | | | |
+| tool | 工具 | | | |
+| tool call | 工具调用 | | | |
+| tool result | 工具结果 | | | |
+| tool schema | 工具 schema | | | |
+| toolkit | 工具包 | | | |
+| turn | 轮次 | | | |
+| typecheck | 类型检查 | | | |
+| vocabulary | 词汇 | | | |
+| wire format | 协议格式 | 协议格式（wire format） | | |
+| workflow | 工作流 | | | |

docs/i18n/translation-prompt.md

@@ -14,6 +14,18 @@
 
 历史模板的 `{{to}}`、`{{title_prompt}}`、`{{summary_prompt}}`、`{{terms_prompt}}`、`{{imt_style_guide}}` 占位符与 `%%` 分段协议已废弃：本模板按整文档翻译（非分段），输出协议为下方三段 XML。
 
+## Few-shot 金标
+
+流水线的 few-shot 是**整文档级**的中英对照，不是模板内嵌的句子级正误例（那是最小抽样）。few-shot 集取自以下 5 组人工定稿的配对文档，以仓库当前版本为准、随仓库更新：
+
+- `README.md` ↔ `README.zh.md`
+- `docs/development.md` ↔ `docs/development.zh.md`
+- `docs/i18n/README.md` ↔ `docs/i18n/README.zh.md`
+- `docs/i18n/translation-rules.md` ↔ `docs/i18n/translation-rules.zh.md`
+- `docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md` ↔ 对应 `.zh.md`
+
+注入方式：在系统消息（本模板）之后、待译文档之前，每组作为一轮示例对话——user 消息为源文档全文，assistant 消息为定稿译文全文（不带三段 XML 包装；只有真实请求要求三段输出）。上下文紧张时按上列顺序从后往前裁剪组数。这 5 组也是评审校准锚点（见 [style-samples.md](style-samples.md)），改动任何一组即改变流水线行为。
+
 ## 模板正文
 
 ````text

docs/i18n/translation-rules.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 translation-rules.md: 3e99aa5432ccd904f702238e9b802a9ed9bf6832
-translation-rules.zh.md: 78778907f959d62dad2c9b4c02baf1f664791a43
+translation-rules.zh.md: 0ff2ab43d59c6e0dd07e20e2f1a0a1c28c2f245c

docs/i18n/translation-rules.zh.md

@@ -2,13 +2,13 @@
 
 [English](translation-rules.md) | 中文
 
-本文规定如何在本仓库文档配对的两侧之间进行翻译。两种语言同权（见 [README.md](README.md)）：一次变更用任一语言撰写，那一侧就是这次更新的源——本文的规则约束的是产出或更新另一侧。这些规则对人和 agent（智能体）同等生效；应用它们的进仓 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）**／**禁止（MUST NOT）**会卡门禁或评审；**应当（SHOULD）**偏离时要说明理由；**可以（MAY）**自行裁量。
+本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 [README.md](README.md)）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效；应用这些规则的仓库内置 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ／ **禁止（MUST NOT）** 会卡门禁或评审；**应当（SHOULD）** 偏离时要说明理由；**可以（MAY）** 自行裁量。
 
 ## 忠实性
 
-- 另一侧必须说撰写侧所说的话——不添加行为、前置条件、警告、版本声明或示例，也不丢弃任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜：改正错的那一侧，并在同一个变更里把另一侧带上。
-- 另一侧应当读起来是其语言自然的技术文字，而不是逐词对照。翻译语义，在目标语言语法需要处重组句子，并保持原作者的语域——简练的保持简练。
-- 不要翻译不可译的东西：一句话如果依赖源语言的习语而无法自然转换，就翻译它的意思，而不是习语本身。
+- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。
+- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。
+- 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。
 
 ## 行文
 
@@ -23,47 +23,47 @@
 
 形状由配对门禁强制，译者不需要用流畅度去换结构——在框架内自然行文即可。配对的两个文件必须在以下方面一一对应：
 
-- 标题层级（相同级别、相同顺序——标题的**文字**要翻译），
-- 列表形态与编号，
-- 表格（相同的列、相同的行序；表头单元格按术语表翻译），
-- 围栏代码块——**逐字节一致，包括注释**；代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移，
-- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）——原样保留，从不翻译或重排，
-- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标——按约定是 `.md` 路径而非 `.zh.md` 兄弟文件——这样某对文档先于相邻文件落地时，链接也永不悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。
+- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；
+- 列表形态与编号；
+- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；
+- 围栏代码块：**逐字节一致，包括注释**。代码属于受验证的范围（` ```ts ` 块要通过 `doc-typecheck` 编译），而被改动的注释是代码块计数门禁看不见的漂移；
+- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；
+- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。
 
 本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。
 
 ## 术语
 
-- [terminology.md](terminology.md) 是双向的术语真源。翻译前先加载它；翻译中，表内的每个术语都必须严格按表规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文另一侧同样按表中英文列使用术语。
-- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才可以翻译。在 PR 中注明先例出处。
-- **没有**成型先例的术语，译文中必须保留英文，并且必须在 PR 描述的「待定术语」下列出、附上建议译法交评审者定夺。禁止就地发明中文译法——无先例的翻译恰恰制造了术语表要防止的歧义。定下来的术语随后在同一个 PR 或后续 PR 进入 [terminology.md](terminology.md)。
+- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；翻译过程中，表内的每个术语都*必须*严格按表中规定的译法呈现，包括首次出现的括注（如首现写 `agent（智能体）`，之后写 `agent`）与「不要译作」的禁项。中文先行撰写时，英文对侧同样按表中英文列使用术语。
+- 表中**没有**的技术术语，只有当某个主要中文 OSS 或厂商文档已有成型译法时（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档）才*可以*翻译。请在 PR 中注明先例出处。
+- **没有**成型先例的术语，译文中*必须*保留英文，并且*必须*在 PR 描述的「待定术语」下列出，附上建议译法交评审者定夺。*禁止*就地发明中文译法，因为无先例的翻译恰恰会制造术语表要防止的歧义。确定下来的术语随后在同一个 PR 或后续 PR 中进入 [terminology.md](terminology.md)。
 
 ## 排版
 
-本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。下面的中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：
+本节规则约束中文一侧；英文一侧遵循仓库常规的 Markdown 约定（根 `AGENTS.md`）。以下中西文混排规则遵循 [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)、[Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)、[Vue.js 中文翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5) 与[中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)的跨项目共识，其根据是 [W3C clreq](https://www.w3.org/TR/clreq/) 与 GB/T 15834—2011：
 
-- 必须在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
-- 中文行文必须使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
-- 并列顿开：中文的并列项之间用顿号（、），不用逗号。
-- 禁止使用全角数字或全角拉丁字母——永远不写 `１２３`，永远写 `123`。
-- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek——除非引用代码，否则绝不写 `github`／`Github`。
+- *必须*在中文与拉丁词之间、中文与数字之间各留一个半角空格：`每个 plugin 注册 3 个 tool`。全角标点与任何字符之间不加空格。
+- 中文行文*必须*使用全角（中文）标点：`，。：；？！（）「」`。半角标点保留在代码内、按原样引用的完整英文句子内、以及数字内（`3.5`、`1,024`）。
+- 顿号：中文的并列项之间使用顿号（、），而非逗号。
+- *禁止*使用全角数字或全角拉丁字母：永远不写 `１２３`，永远写 `123`。
+- 专有名词保持规范大小写：GitHub、TypeScript、DeepSeek。除非引用代码，否则绝不写 `github`／`Github`。
 - 第二人称用「你」，不用「您」（与 Vue、Kubernetes 中文约定及本仓库的直接语气一致）。
-- 强调标记（`**加粗**`、`*斜体*`）落在与另一侧相同的文字段上；中文没有斜体，渲染效果可能看不出差别——不要用引号或其他装饰替代。
+- 强调标记（`**加粗**`、`*斜体*`）落在与对侧相同的文字段上。中文没有斜体，渲染效果可能看不出差别，不要用引号或其他装饰替代。
 
-## 质量线
+## 质量标准
 
-- 一对文档的完成标准：一位双语工程师只读其中任一文件，得到与另一文件读者完全相同的信息——相同的事实、相同的告诫、相同的语气——并且没有任何多余的内容。
-- 交付前，对照本文自查一遍，并**只读另一侧**再通读一遍、不看源侧对照；没有源文锚着，别扭的表述更容易被听出来。
-- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查——跑门禁；门禁覆盖的不要手工核对。
+- 一对文档的完成标准：一位双语工程师只读其中任一文件，能获得与另一文件读者完全相同的信息（相同的事实、相同的告诫、相同的语气），并且没有任何多余的内容。
+- 交付前，请对照本文自查一遍，并**单独通读对侧文件**，不与源侧对照；不对照原文时，更容易察觉别扭的表达。
+- 机械契约（一致性记录、切换行、结构、折行、链接）由 `pnpm run verify-translation-pairing` 和 `doc-sync` 的其余门禁检查。请运行门禁；门禁已覆盖的内容无需手工核对。
 
 ## 参考资料
 
 本文各规则引用的权威出处，供想了解底层依据的人和 agent 查阅：
 
-- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)——中西文混排空格与标点的社区事实标准。
-- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)——与本文同形态的进仓翻译规则文件；空格、标点与术语表实践。
-- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)——最大的中文本地化团队的术语首现与标点实践。
-- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)——逐术语的译／留决策与语气。
-- [zh-style-guide](https://zh-style-guide.readthedocs.io)——社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
-- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides)——排版学与厂商本地化的正式基线。
-- GB/T 19682-2005《翻译服务译文质量要求》——国家标准；本文「忠实性」与「术语」两节把它的三项基本要求（忠实原文、术语统一、行文通顺）落成可操作规则。
+- [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)：中西文混排空格与标点的社区事实标准。
+- [MDN 简体中文翻译指南](https://github.com/mdn/translated-content/blob/main/docs/zh-cn/translation-guide.md)：与本文同形态的仓库内置翻译规则文件；空格、标点与术语表实践。
+- [Kubernetes 中文本地化指南](https://kubernetes.io/zh-cn/docs/contribute/localization_zh/)：最大的中文本地化团队的术语首现与标点实践。
+- [Vue.js docs-zh-cn 翻译须知](https://github.com/vuejs-translations/docs-zh-cn/wiki/%E7%BF%BB%E8%AF%91%E9%A1%BB%E7%9F%A5)：逐术语的译／留决策与语气。
+- [zh-style-guide](https://zh-style-guide.readthedocs.io)：社区中文技术文档写作规范，本文借用了它的规则级别分类体系（与 RFC 2119 关键词分级）；它聚合了 GB/T 15834/15835、clreq 与各厂商指南。
+- [W3C clreq](https://www.w3.org/TR/clreq/) 与[微软简体中文风格指南](https://learn.microsoft.com/en-us/globalization/reference/microsoft-style-guides)：排版学与厂商本地化的正式基线。
+- GB/T 19682-2005《翻译服务译文质量要求》：国家标准；本文「忠实性」与「术语」两节将其三项基本要求（忠实原文、术语统一、行文通顺）落实为可操作的规则。

docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-07-02-bilingual-docs-and-pairing-gate.md: 764ad5a9345c2a138b56e9cedb54848a5f7d6054
-2026-07-02-bilingual-docs-and-pairing-gate.zh.md: f039fbe3fa44cb379905bbea9a4692af19d71230
+2026-07-02-bilingual-docs-and-pairing-gate.zh.md: c752d76f12f556ce190bf80c4f3a531c0821be8e

docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.zh.md

@@ -1,36 +1,38 @@
-# 通过配对兄弟文件与配对门禁实现双语文档
+# RFC：通过配对兄弟文件与配对门禁实现双语文档
+
+Status: implemented
 
 [English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文
 
-## 背景
+## 问题
 
-本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。没有机制、纯靠手工维护第二语言，正是译文腐烂的方式：一侧继续演进，另一侧默默地说谎，而没有门禁会注意到。对这类不变式，本仓库一贯的答案是把它编码成机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。
+本仓库的 README 与 docs 目录树会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。
 
 ## 决策
 
-- **配对兄弟文件，两种语言同权。**一对文档是三个兄弟文件：英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典——一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束这对文件的是两侧必须说同样的话，且配对整体合入（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
-- **旁挂记录两侧 blob hash，使一致性可检查。**`foo.i18n.yaml` 保存两侧文件在上一次确认一致状态下各自的完整 git blob hash。此后改了任一侧而没重新确认配对，都能被机械检测出来——纯内容比较、无需查询历史——而且同一个 PR 里改动的文件也能算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）产生一份可评审的 yaml diff：确认一致在 PR 里是一个显式、可见的动作。
-- **`verify-translation-pairing` 加入 `doc-sync`。**门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行：required 的配对存在；任何已存在的配对完整（三个文件齐全）且一致（两个 hash 都匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单是一个棘轮：每个合入的翻译批次把自己的文件加进去，覆盖面只增不减。
-- **翻译是 agent 的工作，由人评审。**进仓的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 同一模式：skill 承载工作流，并把真源让给文档。
+- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../i18n/terminology.md)。
+- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR 内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。
+- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：required 的配对必须存在；任何已存在的配对必须完整（三个文件齐全）且一致（两个 hash 匹配、切换行双向互链、结构签名一致）；被排除的文件（生成物或本身即双语的）保持不配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 中的 `required` 清单只进不退：每个合并的翻译批次将自己的文件加入其中，覆盖面只增不减。
+- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../../.agents/skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../../.agents/skills/dsh-code-review/SKILL.md) 模式相同：skill 承载工作流，并将文档作为真源。
 
 ## 曾考虑的替代方案
 
-- **英文为正典源、指纹放在译文内**——本 RFC 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 RFC，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的旁挂记录取代了文件内的单向指纹；blob hash 的机制原样保留。
-- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**——否决：本仓库没有把 locale 映射到路由的文档站框架，挪动每个英文文件会搅动所有既有交叉引用，且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑而不是原样工作。
-- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**——否决：适合有独立发布节奏的文档产品，对 monorepo 自己的文档而言过重；还会把译文置于本仓库门禁够不到的地方。
-- **中英混排单文件（一个文件、两种语言）**——否决：每个 diff 都翻倍，破坏一段一行约定的 diff 工效，且局部不一致不可见。
-- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**——否决，改用 blob hash：同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。
-- **比较配对两侧的 git 时间戳（无记录）**——否决：纯格式化的改动会误报，一次无关改动之后提交的另一侧会漏报；只有内容同一性这个信号与门禁的承诺名实相符。
+- **英文为正典源、指纹放在译文内**：本 RFC 最初提出的设计：`.zh.md` 文件携带一条 HTML 注释记录英文源的 blob hash，翻译只沿 EN → ZH 单向流动。评审中修订：团队需要中文先行的撰写方式（先写、先审中文 RFC，再译英文），两种语言同权，而单向正典模型无法表达这一点。覆盖**两侧**的伴随记录取代了文件内的单向指纹；blob hash 的机制本身保持不变。
+- **语言目录（`docs/en/` + `docs/zh/`，Kubernetes/ECharts 模式）**：否决。本仓库没有将 locale 映射到路由的文档站框架；如果移动所有英文文件，所有既有交叉引用都要随之修改；且 `verify-md-links`/`verify-doc-refs` 将需要路径映射逻辑，而非原样工作。
+- **独立翻译仓库（PingCAP `docs`/`docs-cn` 模式）**：否决。适合有独立发布节奏的文档产品，对 monorepo 自身的文档而言过重；还会把译文置于本仓库门禁触及不到的地方。
+- **中英混排单文件（一个文件、两种语言）**：否决。每个 diff 都翻倍，破坏一段一行约定的 diff 易读性，且局部不一致不可见。
+- **Commit hash 式记录（MDN `l10n.sourceCommit` 模式）**：否决，改用 blob hash。同一个 PR 内的改动还没有 commit hash，MDN 模式无法表达「与本 PR 引入的状态一致」，且校验它需要 git 历史而非文件内容。
+- **比较配对两侧的 git 时间戳（无记录）**：否决。纯格式化的改动会误报，一次无关改动之后提交的对侧文件会漏报；只有内容同一性这个信号才与门禁的承诺名实相符。
 
 ## 业界先例
 
-带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`）——但这些仓库都没有在 CI 里**强制**配对或一致性；约定纯靠评审维系。一致性自动化存在于中国之外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit、为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计把两者结合：中文生态的文件布局，加 hash 对门禁，再加一个进仓 agent skill（技能）替代 bot 服务。
+带语言后缀的配对兄弟文件是中国大厂的主流约定（ant-design 的 `index.zh-CN.md`/`index.en-US.md`；arco-design 的 `README.zh-CN.md` 加顶部切换行；Apache ShardingSphere 的 387 对 `.cn.md`/`.en.md`），但这些仓库都没有在 CI 中**强制**配对或一致性检查；约定纯靠评审维系。一致性自动化存在于中国以外：MDN 的 `l10n.sourceCommit` front-matter 指纹、Vue 的 Ryu-Cho action（监视上游 commit，为陈旧译文自动开 issue/PR）、Kubernetes 的本地化漂移脚本、微软 Azure co-op-translator（CI 中由源 hash 驱动的 LLM 重译）。本设计将两者结合：中文生态的文件布局，加上 hash 配对门禁，再加一个仓库内置的 agent skill 替代 bot 服务。
 
 ## 后果
 
-- 修改已配对文档的任一侧，同一个 PR 就有义务更新另一侧并重新记录配对——门禁把 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。
-- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对一致」可以从 yaml 的 git blame 直接回答。
-- 两侧说法冲突时，没有机械规则裁决谁赢——由 PR 评审裁决。这是同权的代价，是有意接受的：另一个选项（正典语言）禁止中文先行撰写。
-- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让它们的生成器在输出英文的同时输出中文，届时移出排除清单。
-- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），不是红的 CI，因此配对按可评审的批次落地，无需一个巨型 PR。新文档是例外——文件名日期在 manifest `requiredSince` 当天或之后的文档，要么连同配对一起合入，要么不合入，因此 backlog 只会缩小。
-- 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），所以这套机制从不强迫整篇重译。
+- 修改已配对文档的任一侧，同一个 PR 就有义务更新对侧并重新记录配对。门禁将 doc-sync 规则双语化，不变式由 CI（而非评审者的记忆）承载。
+- 每个配对给目录树多添一个文件。记录由机器写入（`--write`），代价是目录噪音而非维护负担；换来的是「谁在何时确认过这对文档一致」可以从 yaml 的 git blame 直接回答。
+- 两侧说法冲突时，没有机械规则裁决谁赢，由 PR 评审裁决。这是同权的代价，且是有意接受的：另一个选项（正典语言）会禁止中文先行撰写。
+- 生成文档（`cordis-catalog/`、`tool-catalog/`、`module-graph.md`）暂被排除；计划中的后续工作是让生成器在输出英文的同时输出中文，届时将这些文件移出排除清单。
+- 推进天然是渐进的：`required` 之外的文档是可见的 backlog（`--list`），而非红色的 CI；因此配对按可评审的批次落地，无需一个巨型 PR。
+- 记录的 hash 兼作更新工具（`git cat-file -p <hash>` 能还原任一侧上次确认的文本，用于基于 diff 的最小更新），因此这套机制从不强迫整篇重译。