docs(i18n): RFC tree batch — 146 bilingual pairs via the committed pipeline
implemented(除 4 篇超长文档随后补)、proposed、rejected 全树配对; 同一流水线 + 二遍校验(paraphrase-back + 仓库上下文一致性)产出。 docs/rfc/implemented/AGENTS.md 与其 CLAUDE.md 符号链接列入排除 (agent 指令文件,与根 AGENTS.md 同策略)。
This commit is contained in:
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# 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
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: API extractor reports
|
||||
|
||||
English | [中文](2026-06-11-api-extractor-reports.zh.md)
|
||||
|
||||
Status: proposed
|
||||
|
||||
> Split out from the original "Doc-sync and API reports" RFC (2026-06-11). Parts 1-2 (doc-block typechecking, event-taxonomy verification) shipped — see [doc-sync enforcement](../../implemented/process/2026-06-11-doc-sync-enforcement.md). This is the deferred part 3, kept as a standalone proposal.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# RFC:API extractor 报告
|
||||
|
||||
[English](2026-06-11-api-extractor-reports.md) | 中文
|
||||
|
||||
Status: proposed
|
||||
|
||||
> 从最初的「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-extractor(或 `tsc --emitDeclarationOnly` 加一份归一化的公开接口导出)为每个包(package)生成一份签入仓库的 `etc/<pkg>.api.md`;如果重新生成的结果与签入版本不同,CI 失败。这样每一次公开 API 变更都会变成评审者(或评审 agent)必须看到的一行 diff。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**`tsc --emitDeclarationOnly` 加一份归一化的公开接口导出**:如果 api-extractor 被证明过重,这是更轻量的机制;两者都满足本提案所需的「签入仓库、可 diff」的报告形态。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 每个包有一份签入仓库的 `etc/<pkg>.api.md`;重新生成结果与已提交报告不同时 CI 失败。
|
||||
- 公开 API 变更(新增导出、字段放宽、签名变化)在评审中以报告 diff 行的形式可见。
|
||||
|
||||
## 风险
|
||||
|
||||
该依赖重且难伺候——这正是它被推迟的原因——且报告格式会随编译器升级而变动,在各包尚未发布的阶段增加了一个收益甚微的维护面。
|
||||
|
||||
## 推迟原因
|
||||
|
||||
在 doc-sync 落地时被推迟:对于评审者已经能看到源码 diff 的内部 monorepo 而言价值有限,且依赖重、难伺候。如果这些包将来对外发布,届时一份稳定、可 diff 的公开接口报告才值得其维护成本。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# 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
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: Architectural conformance — dependency rules and the adapter kit
|
||||
|
||||
English | [中文](2026-06-11-architectural-conformance.zh.md)
|
||||
|
||||
Status: proposed
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# RFC:架构一致性——依赖规则与适配器套件
|
||||
|
||||
[English](2026-06-11-architectural-conformance.md) | 中文
|
||||
|
||||
Status: proposed
|
||||
|
||||
## 问题
|
||||
|
||||
两项架构保证目前仅存在于行文中:(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`。
|
||||
- 禁止跨包深层导入(`@deepseek-ai/dsh-*/src/...` 路径)——只允许使用公开入口点。
|
||||
- packages/ 内禁止任何导入循环。
|
||||
- `vendor/*` 禁止从 `packages/*` 导入。
|
||||
- 分层: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)配对)。
|
||||
|
||||
## 计划
|
||||
|
||||
先落地 dependency-cruiser 配置与 CI 步骤(约一小时工作量,永久保证);一致性套件随其首个消费方测试(针对 MockAdapter)一起落地,并作为 V4 适配器阶段的前置条件。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- dependency-cruiser 在 CI 中运行上述规则族;违规导入导致构建失败。
|
||||
- 一致性套件对 mock 适配器和两个正式适配器运行通过;新适配器包通过调用该套件并传入自己的工厂即可继承测试。
|
||||
|
||||
## 风险
|
||||
|
||||
随着包的增加需要维护 dep-cruiser 规则——应保持规则基于模式(`dsh-*`)而非逐一枚举。
|
||||
|
||||
<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# 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
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: Supply chain checks and vendor drift verification
|
||||
|
||||
English | [中文](2026-06-11-supply-chain-and-vendor-drift.zh.md)
|
||||
|
||||
Status: proposed
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# RFC:供应链检查与 vendor 漂移校验
|
||||
|
||||
[English](2026-06-11-supply-chain-and-vendor-drift.md) | 中文
|
||||
|
||||
Status: proposed
|
||||
|
||||
## 问题
|
||||
|
||||
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 表格)。
|
||||
|
||||
## 计划
|
||||
|
||||
3 最简单,先做。1 需要 CI 能通过网络访问上游仓库(私有镜像,需要 token),并将现有两项已记录的修改转为 patch 文件。2 和 4 属于配置工作。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **用 `pnpm audit` 代替 osv-scanner**:两者都满足安全公告扫描的需求;具体选择推迟到实现阶段决定。
|
||||
- **用定时 agent 任务代替 Renovate**:在「以小 PR 提议更新并走完整门禁」这件事上效果等价;vendor 化的 package 无论哪种方案都排除在外(它们的更新遵循 manifest 同步流程)。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 许可证清单脚本在 CI 中运行,缺少 LICENSE 或 `license` 字段与 `vendor/README.md` 清单矛盾时失败。
|
||||
- 夜间漂移 job 从 manifest SHA 加入库 patch 文件重建 `vendor/`,出现任何无法解释的 diff 时失败。
|
||||
- 安全公告扫描按计划对 lockfile 运行,并在涉及 lockfile 的 PR 上运行。
|
||||
|
||||
## 风险
|
||||
|
||||
上游仓库是私有镜像;CI 凭证与可用性是漂移检查的主要阻力。如果受阻,改为本地定时 agent 任务而非 CI 运行。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# 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
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: Discover package inventories instead of maintaining static lists
|
||||
|
||||
English | [中文](2026-06-20-discover-package-inventory.zh.md)
|
||||
|
||||
Status: proposed
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# RFC:通过发现机制获取包清单,取代静态列表维护
|
||||
|
||||
[English](2026-06-20-discover-package-inventory.md) | 中文
|
||||
|
||||
Status: proposed
|
||||
|
||||
## 问题
|
||||
|
||||
包(package)与门禁的清单在 TypeScript project references、package 文档、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 要求它是一个显式数组(没有通配符形式)。
|
||||
|
||||
静态列表在编码策略时是合理的;当它们只是重复 `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` 应当成为定义并打印其子门禁的唯一命令,文档链接到该命令而非重述第二份清单。
|
||||
|
||||
层级结构不需要编码一个包的所有信息,但应当编码宽泛的维护策略:core/product 包、集成包、能力 seam 包与 support/test/example 包不应在脚本能区分它们之前先要求一份手工维护的例外清单。
|
||||
|
||||
有两项被编目的内容根本不需要生成器:把 e2e 入口 glob 折入 knip 的默认 stanza 即可直接删除各包的重述;`childSessions` 可以从每个场景的 fixture 目录发现,让场景表只声明策略(`recorded`、`hasModelTurn`、`comparesLog`)。而即便这些策略字段,今天也在追踪可从 fixture 推导的事实(`comparesLog` ⟺ 已提交的日志在表头行之后有内容;`recorded` ⟺ `hasModelTurn` 且没有 `replay.override.json` 兄弟文件),因此每个新场景类别都在不断添加 fixture 目录已经能回答的开关。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `tsconfig.build.json` 的 project `references` 由层级结构生成(生成器输出它们;`--check` 门禁在已提交副本陈旧时失败),而非手工维护。
|
||||
- 新增一个包不需要为任何门禁编辑静态包列表。
|
||||
- 文档描述真源,而非重复生成的清单。
|
||||
- CI 调用聚合命令,由这些命令自行管理其子门禁列表。
|
||||
- `knip.json` 仅在编码真实信息(额外入口文件、被忽略的依赖)时才携带 per-package 覆盖项,绝不重述默认 stanza。
|
||||
- 快照场景只声明策略,不声明可从其 fixture 目录发现的事实。
|
||||
|
||||
## 风险
|
||||
|
||||
发现脚本可能变得过于精巧。实现应保持朴素:读取 manifest、按显式字段过滤、打印解析后的列表、出错时大声报错。收益在于消除手工清单漂移,而非发明一套构建系统。
|
||||
|
||||
<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
|
||||
Reference in New Issue
Block a user