docs(i18n): re-translate RFC batch with the prompt-v4 pipeline

146 篇 RFC 译文按 v4 基线（#348）重出：v4 模板+术语表、金标 few-shot、三段协议、切换行后处理；全量机械核对零异常（一处 task id 术语违规已修）。三篇超长 RFC（code-mode 已入，web-seam/ agent-scope/sandbox/cds-core 仍在长文档通道产出）随后补。
2026-07-22 03:07:36 -07:00
parent 839b88a53a
commit 8ea5cdd894
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-06-11-api-extractor-reports.md: 0f3f736ba662fd6366eb8d7f26887fb319b2b563
-2026-06-11-api-extractor-reports.zh.md: 3c472d64bc96c7fffa784c091f8a7a70bb0beb56
+2026-06-11-api-extractor-reports.zh.md: cf0eb3f9edbcfb2ae862f075af0628e716693a86
@@ -4,29 +4,29 @@

 Status: proposed

-> 从最初的「Doc-sync 与 API 报告」RFC（2026-06-11）中拆出。第 1、2 部分（文档块类型检查、事件分类体系校验）已交付——见 [doc-sync 强制](../../implemented/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。
+> 从最初的「Doc-sync 与 API 报告」RFC（2026-06-11）中拆出。第 1–2 部分（文档块类型检查、事件分类体系校验）已交付，见 [doc-sync 强制](../../implemented/process/2026-06-11-doc-sync-enforcement.md)。本文是被推迟的第 3 部分，作为独立提案保留。

 ## 问题

-公开 API 的变更是不可见的：没有任何机制让「这个 commit 改变了公开接口」成为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏一个导出类型新增了字段或方法签名发生了变化。
+公开 API 的变更是不可见的：没有任何机制将「此次提交改变了公开接口」变为一个显式、可评审的事实。评审者阅读 diff 时可能遗漏某个导出类型新增了字段，或某个方法签名发生了变化。

 ## 提案

-使用 api-extractor（或 `tsc --emitDeclarationOnly` 加一份归一化的公开接口导出）为每个包（package）生成一份签入仓库的 `etc/<pkg>.api.md`；如果重新生成的结果与签入版本不同，CI 失败。这样每一次公开 API 变更都会变成评审者（或评审 agent）必须看到的一行 diff。
+使用 api-extractor（或 `tsc --emitDeclarationOnly` 加一份规范化的公开接口导出）为每个包（package）生成一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已签入报告不一致时失败。这样，每一次公开 API 变更都会成为评审者（或评审 agent（智能体））必须看到的一行 diff。

 ## 曾考虑的替代方案

-**`tsc --emitDeclarationOnly` 加一份归一化的公开接口导出**：如果 api-extractor 被证明过重，这是更轻量的机制；两者都满足本提案所需的「签入仓库、可 diff」的报告形态。
+**`tsc --emitDeclarationOnly` 加规范化的公开接口导出**：如果 api-extractor 过于笨重，这是更轻量的机制；两者都能满足提案所需的「签入仓库、可 diff」的报告形态。

 ## 验收标准

- 每个包有一份签入仓库的 `etc/<pkg>.api.md`；重新生成结果与已提交报告不同时 CI 失败。
+- 每个包都有一份签入仓库的 `etc/<pkg>.api.md`；CI 在重新生成结果与已提交报告不一致时失败。
 - 公开 API 变更（新增导出、字段放宽、签名变化）在评审中以报告 diff 行的形式可见。

 ## 风险

-该依赖重且难伺候——这正是它被推迟的原因——且报告格式会随编译器升级而变动，在各包尚未发布的阶段增加了一个收益甚微的维护面。
+该依赖笨重且难以调教（这正是它被推迟的原因），且报告格式会随编译器升级而变动，增加一个维护面；在各包尚未发布的阶段，收益有限。

 ## 推迟原因

-在 doc-sync 落地时被推迟：对于评审者已经能看到源码 diff 的内部 monorepo 而言价值有限，且依赖重、难伺候。如果这些包将来对外发布，届时一份稳定、可 diff 的公开接口报告才值得其维护成本。
+在 doc-sync 落地时被推迟：对于一个内部 monorepo，评审者已经能看到源码 diff，价值不高；且依赖笨重、难以调教。如果各包将来对外发布，再重新评估——届时一份稳定、可 diff 的公开接口报告才值得其维护成本。
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-06-11-architectural-conformance.md: 40858d049af2df1928e27280238d0b198a5202f7
-2026-06-11-architectural-conformance.zh.md: d61751210ef78b26e05a05efae4d5abccbfd2e5c
+2026-06-11-architectural-conformance.zh.md: b68355dc1c04a4f807efdb95f813159cb7f9f178
@@ -6,31 +6,31 @@ Status: proposed

 ## 问题

-两项架构保证目前仅存在于行文中：（1）任何包不得依赖具体的 loop 包（[微内核承诺](../../implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）；（2）每个 LlmAdapter 都正确地遵循 chunk 协议。两者都应当机械化（[质量门禁原则](../../implemented/process/2026-06-11-quality-gates.md)）。
+目前有两项架构保证仅存在于行文中：（1）没有任何东西依赖具体的 loop 包（[微内核承诺](../../implemented/architecture/2026-06-11-microkernel-event-taxonomy.md)）；（2）每个 LlmAdapter 都正确地遵循 chunk 协议。二者都应当是机械化的（[质量门禁原则](../../implemented/process/2026-06-11-quality-gates.md)）。

 ## 提案

 **dependency-cruiser** 配合以下规则：

- `packages/*`（agent-loop 自身的测试和 examples/ 除外）禁止导入 `@deepseek-ai/dsh-agent-loop`。
+- `packages/*`（除 agent-loop 自身的 tests 和 examples/ 外）禁止导入 `@deepseek-ai/dsh-agent-loop`。
 - 禁止跨包深层导入（`@deepseek-ai/dsh-*/src/...` 路径）——只允许使用公开入口点。
- packages/ 内禁止任何导入循环。
+- packages/ 内禁止导入循环。
 - `vendor/*` 禁止从 `packages/*` 导入。
- 分层：dsh-llm 不导入其他 dsh 包；dsh-session 只导入 dsh-llm；以此类推（即 packages/README.md 中的依赖表，强制执行）。
+- 分层：dsh-llm 不导入其他 dsh 包；dsh-session 仅导入 dsh-llm；以此类推（packages/README.md 中的依赖表，强制执行）。

-**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个可复用的 vitest 套件，以适配器工厂为参数，断言 chunk 协议契约——每个 block 的 index 单调递增、`block-end` 之后该 index 不再有 delta、恰好一个 `finish`、usage 至多出现一次、每个 `tool-call-delta` 携带 call id、abort 被及时响应。当前对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。可选地提供一个 dev 模式的 `strictAdapter()` 包装层，在 debug flag 下于运行时强制执行相同约束（与 [dev 模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md)配对）。
+**适配器一致性套件**位于 dsh-llm（`@deepseek-ai/dsh-llm/conformance`）：一个可复用的 vitest 套件，以适配器工厂为参数，断言 chunk 协议契约——每个 block 内 index 单调递增、`block-end` 之后该 index 不再有 delta、恰好一个 `finish`、usage 至多出现一次、每个 `tool-call-delta` 携带 call id、abort 被及时响应。当前对 mock 运行；DeepSeek V4 适配器从第一天起继承该套件。可选地提供一个 dev 模式的 `strictAdapter()` 包装层，在 debug flag 下于运行时强制执行相同规则（与 [dev 模式不变式](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md) 配对）。

 ## 计划

-先落地 dependency-cruiser 配置与 CI 步骤（约一小时工作量，永久保证）；一致性套件随其首个消费方测试（针对 MockAdapter）一起落地，并作为 V4 适配器阶段的前置条件。
+先落地 dependency-cruiser 配置与 CI 步骤（约一小时工作量，换来永久保证）；一致性套件随其首个消费方测试（针对 MockAdapter）一起落地，并作为 V4 适配器阶段的前置条件。

 ## 验收标准

 - dependency-cruiser 在 CI 中运行上述规则族；违规导入导致构建失败。
- 一致性套件对 mock 适配器和两个正式适配器运行通过；新适配器包通过调用该套件并传入自己的工厂即可继承测试。
+- 一致性套件对 mock 适配器和两个正式适配器运行，新适配器包通过调用该套件并传入自己的工厂即可继承测试。

 ## 风险

-随着包的增加需要维护 dep-cruiser 规则——应保持规则基于模式（`dsh-*`）而非逐一枚举。
+随着包的增加，dep-cruiser 规则需要维护——规则应基于模式（`dsh-*`）而非逐一枚举。

 <!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-06-11-supply-chain-and-vendor-drift.md: 306e185e9175e3e7af24455cf95167f54b3d1c17
-2026-06-11-supply-chain-and-vendor-drift.zh.md: 1aeb0a8eff3f335bc87c05742acc4502a19bf3c5
+2026-06-11-supply-chain-and-vendor-drift.zh.md: a840e766c49182d7a9ca648acbbab1a2762688f5
@@ -1,4 +1,4 @@
-# RFC：供应链检查与 vendor 漂移校验
+# RFC：供应链检查与 vendor 漂移验证

 [English](2026-06-11-supply-chain-and-vendor-drift.md) | 中文

@@ -6,30 +6,30 @@ Status: proposed

 ## 问题

-vendor manifest（[vendor 化决策](../../implemented/process/2026-06-11-vendor-cordis-as-source.md)）在提交时只做*正向*强制（vendor 代码变更 ⇒ manifest 更新），但没有任何机制校验 manifest 的*声明*：即 vendor/ 确实等于「上游指定 SHA 的代码 + 日志中记录的修改」。此外，少量真正的 npm 依赖也没有安全公告监控或更新节奏。
+vendor manifest（元数据清单）（见[引入 vendor 的决策](../../implemented/process/2026-06-11-vendor-cordis-as-source.md)）在提交时仅在**正向**强制执行（vendor 变更 ⇒ manifest 更新），但没有任何机制验证 manifest 的**声明**：即 vendor/ 确实等于上游指定 SHA 的内容加上所记录的修改。此外，少量真正的 npm 依赖也没有安全公告监控或更新节奏。

 ## 提案

-1. **Vendor 漂移检查**（夜间 CI）：以 manifest 中的 SHA 浅克隆上游仓库，复制对应 package 的源码，与 `vendor/*/src` 做 diff。除非 diff 与日志中的本地修改一致（每项修改保存为一个入库的 patch 文件，使日志条目成为可校验的产物而非纯文字），否则 job 失败。
-2. **依赖安全公告**：对 lockfile 运行 osv-scanner（或 `pnpm audit`），按计划调度 + 在涉及 lockfile 的 PR 上触发。
-3. **许可证清单**：一个脚本断言每个 vendor 化的 package 都携带 LICENSE 文件，且 package.json 的 `license` 字段与 vendor/README.md 中的清单一致（我们混合了 vendor 化的 MIT 与自有的 BSD-3）。作为 CI 步骤运行。
-4. **Renovate**（或一个定时 agent 任务）以小 PR 提议 npm 依赖更新，这些 PR 走完整门禁套件；vendor 化的 package 排除在外（它们的更新遵循 manifest 同步流程，理想情况下作为半自动化的 agent 工作流：拉取上游、重新应用 patch、运行门禁、打开 PR 并更新 manifest 表格）。
+1. **Vendor 漂移检查**（夜间 CI）：以 manifest 中记录的 SHA 浅克隆上游仓库，复制对应的 package 源码，与 `vendor/*/src` 做 diff。除非 diff 与已记录的本地修改一致（每项修改以签入的 patch 文件保存——日志条目从行文描述变为可验证的产物），否则任务失败。
+2. **依赖安全公告**：对 lockfile 运行 osv-scanner（或 `pnpm audit`），按计划定期执行，并在涉及 lockfile 变更的 PR 上触发。
+3. **许可证清单**：一个脚本断言每个 vendor 包都携带其 LICENSE 文件，且 package.json 的 `license` 字段与 vendor/README.md 中的清单一致（我们混合了 vendor 的 MIT 与自有的 BSD-3）——作为 CI 步骤运行。
+4. **Renovate**（或定时 agent 任务）以小 PR 的形式提议 npm 依赖更新，这些 PR 走完整门禁套件；vendor 包不在其列（它们的更新遵循 manifest 同步流程，理想情况下是半自动化的 agent 工作流：拉取上游、重新应用 patch、运行门禁、以更新后的 manifest 表格开 PR）。

 ## 计划

-3 最简单，先做。1 需要 CI 能通过网络访问上游仓库（私有镜像，需要 token），并将现有两项已记录的修改转为 patch 文件。2 和 4 属于配置工作。
+第 3 项最简单，先做。第 1 项需要 CI 能通过网络访问上游仓库（私有仓库，需要 token），并将现有两项已记录的修改转换为 patch 文件。第 2 项和第 4 项是配置工作。

 ## 曾考虑的替代方案

- **用 `pnpm audit` 代替 osv-scanner**：两者都满足安全公告扫描的需求；具体选择推迟到实现阶段决定。
- **用定时 agent 任务代替 Renovate**：在「以小 PR 提议更新并走完整门禁」这件事上效果等价；vendor 化的 package 无论哪种方案都排除在外（它们的更新遵循 manifest 同步流程）。
+- **用 `pnpm audit` 替代 osv-scanner**：两者都满足安全公告扫描的需求；具体选择推迟到实现阶段决定。
+- **用定时 agent 任务替代 Renovate**：在提议小型更新 PR 并走完整门禁套件方面效果等价；vendor 包无论哪种方案都不在其列（它们的更新遵循 manifest 同步流程）。

 ## 验收标准

- 许可证清单脚本在 CI 中运行，缺少 LICENSE 或 `license` 字段与 `vendor/README.md` 清单矛盾时失败。
- 夜间漂移 job 从 manifest SHA 加入库 patch 文件重建 `vendor/`，出现任何无法解释的 diff 时失败。
- 安全公告扫描按计划对 lockfile 运行，并在涉及 lockfile 的 PR 上运行。
+- 许可证清单脚本在 CI 中运行，缺少 LICENSE 或 `license` 字段与 `vendor/README.md` 中的清单矛盾时失败。
+- 夜间漂移任务从 manifest SHA 加签入的 patch 文件重建 `vendor/`，出现任何无法解释的 diff 时失败。
+- 安全公告扫描按计划定期运行，并在涉及 lockfile 变更的 PR 上运行。

 ## 风险

-上游仓库是私有镜像；CI 凭证与可用性是漂移检查的主要阻力。如果受阻，改为本地定时 agent 任务而非 CI 运行。
+上游仓库是私有镜像；CI 凭证与可用性是漂移检查的主要阻力。如果受阻，可改为本地定时 agent 任务而非 CI。
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
 2026-06-20-discover-package-inventory.md: 22b3e9acbe4dad8ef829d0dd30415c516031d66b
-2026-06-20-discover-package-inventory.zh.md: 8b62d42d2d514f60016690ba55d5ce77a50b3aff
+2026-06-20-discover-package-inventory.zh.md: 4eeaed9ed6b390608095281775883f8e7a52e954
@@ -1,36 +1,36 @@
-# RFC：通过发现机制获取包清单，取代静态列表维护
-
-[English](2026-06-20-discover-package-inventory.md) | 中文
+# RFC：通过发现机制获取包清单，而非维护静态列表

 Status: proposed

+[English](2026-06-20-discover-package-inventory.md) | 中文
+
 ## 问题

-包（package）与门禁的清单在 TypeScript project references、package 文档、CI 行文、Knip 覆盖项以及快照场景元数据中反复出现。其中大部分只是重述包布局、manifest 数据、聚合命令内容或 fixture（测试前置数据）文件。每新增一个包或场景，都会产生本可避免的同步点。
+包（package）与门禁清单在 TypeScript project references、包文档、CI 描述、Knip 覆盖项以及快照场景元数据中反复出现。大多数只是重述包布局、manifest 数据、聚合命令内容或 fixture（测试前置数据）文件。因此每新增一个包或场景都会产生本可避免的同步点。

-[包层级结构](../../implemented/architecture/2026-06-20-package-hierarchy.md)已经手动消除了其中若干：`scripts/publint-all.ts` 现在从 `packages/<group>/<pkg>` 布局推导清单，两份 `tsconfig` 的 `paths` 映射也合并为一个 `@deepseek-ai/dsh-*` 通配符。剩下的是无法用 glob 消除的清单——主要是 `tsconfig.build.json` 的 project `references`，TypeScript 要求它是一个显式数组（没有通配符形式）。
+[包层级结构](../../implemented/architecture/2026-06-20-package-hierarchy.md)已经手动消除了其中若干：`scripts/publint-all.ts` 现在从 `packages/<group>/<pkg>` 布局推导列表，两份 `tsconfig` 的 `paths` 映射也合并为一个 `@deepseek-ai/dsh-*` 通配符。剩下的是无法用 glob 消除的清单，主要是 `tsconfig.build.json` 的 project `references`——TypeScript 要求它是显式数组（没有通配符形式）。

-静态列表在编码策略时是合理的；当它们只是重复 `package.json`、workspace glob 或包层级结构中已有的 manifest 数据或布局事实时，就是无谓的摩擦。
+当静态列表编码的是策略时，它们是合理的；当它们只是重复 `package.json`、workspace glob 或包层级结构中已有的 manifest 数据或布局事实时，就是不必要的摩擦。

 ## 提案

-让剩余的包/门禁清单可被发现。一个唯一的权威来源——`packages/<group>/<pkg>` 层级结构加上 package manifest——应当驱动 `tsconfig.build.json` 的 `references`、模块图以及任何全量包列表，并配合一个生成加校验步骤（沿用现有的 `gen-module-graph` / `gen-cordis-catalog` 模式：生成器写入产物，`--check` 模式在 `hygiene`/`doc-sync` 中检测已提交副本是否陈旧）。模块图生成器已经在读取 package manifest。`doc-sync` 应当成为定义并打印其子门禁的唯一命令，文档链接到该命令而非重述第二份清单。
+让剩余的包/门禁清单可被发现。一个唯一的权威来源——`packages/<group>/<pkg>` 层级结构加上包 manifest（元数据清单）——应当驱动 `tsconfig.build.json` 的 `references`、模块图以及任何全量包列表，并配合一个生成加校验步骤（沿用现有的 `gen-module-graph` / `gen-cordis-catalog` 模式：生成器写出产物，`hygiene`/doc-sync（文档同步门禁）中的 `--check` 模式在提交副本陈旧时报错）。模块图生成已经在读取包 manifest。`doc-sync` 应当成为定义并打印其子门禁的唯一命令，文档链接到该命令而非重述第二份列表。

-层级结构不需要编码一个包的所有信息，但应当编码宽泛的维护策略：core/product 包、集成包、能力 seam 包与 support/test/example 包不应在脚本能区分它们之前先要求一份手工维护的例外清单。
+层级结构不需要编码关于包的所有事实，但应当编码宽泛的维护策略：core/product 包、集成包、能力 seam 包与 support/test/example 包不应在脚本能区分它们之前先要求一份手工维护的例外列表。

-有两项被编目的内容根本不需要生成器：把 e2e 入口 glob 折入 knip 的默认 stanza 即可直接删除各包的重述；`childSessions` 可以从每个场景的 fixture 目录发现，让场景表只声明策略（`recorded`、`hasModelTurn`、`comparesLog`）。而即便这些策略字段，今天也在追踪可从 fixture 推导的事实（`comparesLog` ⟺ 已提交的日志在表头行之后有内容；`recorded` ⟺ `hasModelTurn` 且没有 `replay.override.json` 兄弟文件），因此每个新场景类别都在不断添加 fixture 目录已经能回答的开关。
+有两类编目项根本不需要生成器：将 e2e 入口 glob 折入 knip 的默认配置段即可直接删除逐包的重复声明；`childSessions` 可从每个场景的 fixture 目录发现，使场景表只需声明策略（`recorded`、`hasModelTurn`、`comparesLog`）。而且即便是这些策略字段，今天也在追踪可从 fixture 推导的事实（`comparesLog` ⟺ 已提交的日志在头行之后还有条目；`recorded` ⟺ `hasModelTurn` 且没有 `replay.override.json` 兄弟文件），因此每个新场景类都在不断添加 fixture 目录本身已经能回答的开关。

 ## 验收标准

- `tsconfig.build.json` 的 project `references` 由层级结构生成（生成器输出它们；`--check` 门禁在已提交副本陈旧时失败），而非手工维护。
- 新增一个包不需要为任何门禁编辑静态包列表。
+- `tsconfig.build.json` 的 project `references` 由层级结构生成（生成器输出它们；`--check` 门禁在提交副本陈旧时报错），而非手工维护。
+- 新增一个包时，不需要为任何门禁编辑静态包列表。
 - 文档描述真源，而非重复生成的清单。
 - CI 调用聚合命令，由这些命令自行管理其子门禁列表。
- `knip.json` 仅在编码真实信息（额外入口文件、被忽略的依赖）时才携带 per-package 覆盖项，绝不重述默认 stanza。
+- `knip.json` 仅在编码真实信息（额外入口文件、被忽略的依赖）时才携带逐包覆盖项，绝不重述默认配置段。
 - 快照场景只声明策略，不声明可从其 fixture 目录发现的事实。

 ## 风险

-发现脚本可能变得过于精巧。实现应保持朴素：读取 manifest、按显式字段过滤、打印解析后的列表、出错时大声报错。收益在于消除手工清单漂移，而非发明一套构建系统。
+发现脚本可能变得过于精巧。实现应当保持朴素：读取 manifest、按显式字段过滤、打印解析后的列表、出错时大声报错。收益在于消除手工清单的漂移，而非发明一套构建系统。

 <!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->