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:
Ziya
@@ -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-immutable-public-surfaces.md: 68472d9817f0de22777314927f05f90949903723
|
||||
2026-06-11-immutable-public-surfaces.zh.md: e067b48d9a936133abdf149fbb9ff626c9411851
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: Deep-readonly public surfaces
|
||||
|
||||
English | [中文](2026-06-11-immutable-public-surfaces.zh.md)
|
||||
|
||||
Status: rejected — the pervasive `DeepReadonly<T>` type flip is replaced by source-owned runtime immutability in `Session` plus relational development assertions. See [source-owned session immutability and dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# RFC：深度只读的公开接口
|
||||
|
||||
[English](2026-06-11-immutable-public-surfaces.md) | 中文
|
||||
|
||||
Status: rejected — the pervasive `DeepReadonly<T>` type flip is replaced by source-owned runtime immutability in `Session` plus relational development assertions. See [source-owned session immutability and dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
|
||||
|
||||
## 问题
|
||||
|
||||
被否决的提案针对的是一个所有权漏洞：仅靠 `readonly SessionEvent[]` 类型无法封堵该漏洞，因为数组元素在运行时仍然可变，一次类型断言或纯 JavaScript 就能改写嵌套的历史记录。最终实现的设计在 `Session` 中通过物化并深度冻结每个已接受的事件、返回冻结的数组快照来封堵该漏洞。进行中的 prompt waterfall（瀑布式事件）被有意保留为可变，因此不可变性是一条所有权边界，而非一条覆盖全局的类型规则。
|
||||
|
||||
## 提案
|
||||
|
||||
> **实际实现方式不同——见 Status 行与 [source-owned session immutability and dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md)。** 下文的 `DeepReadonly<T>` 设计已被否决：它仅在编译期生效、对消费方噪音大、且可被 cast 绕过。`Session` 改为在每次组合中对已接受的事件和公开日志快照进行快照与深度冻结；`deriveMessages()` 返回分离的冻结投影；开发插件检查跨记录与跨 seam 的关系约束。
|
||||
|
||||
在类型层面将不可变性施加于「变异即腐败」的位置：
|
||||
|
||||
- `SessionEvent` 数据在从会话**输出**时（`events`、`session/event` 监听器）变为 `DeepReadonly`；`append()` 仍接受普通可变输入。一个 `DeepReadonly<T>` 工具类型放入 dsh-llm，与 brand/never 辅助类型并列。
|
||||
- `deriveMessages()` 返回深度只读的消息；agent loop（智能体循环）在将可变请求交给 `agent/request` waterfall 之前先克隆一份（在 waterfall 中变异是被允许的——克隆使边界显式且廉价，每步仅一次）。
|
||||
- `PromptAssembly` 在其 waterfall 流程中保持可变（被允许），但注册表的内部 section 列表在每次组装时被克隆（已有此行为）。
|
||||
|
||||
## 计划
|
||||
|
||||
引入 `DeepReadonly`，翻转会话的读取路径，并修复消费方由此产生的编译错误。
|
||||
|
||||
## 风险
|
||||
|
||||
`DeepReadonly` 类型会在 waterfall 边界处产生噪音错误——因为变异在那里正是 API 的一部分。应将可变/只读边界严格限定在「已记录 vs 进行中」，并在会话 README 中加以说明。
|
||||
|
||||
<!-- 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-20-providerless-example-base.md: be5122ec6665dcea15619f3cb4b3ed3a2fa03972
|
||||
2026-06-20-providerless-example-base.zh.md: 011636bbdfb782a5b6e4c03695cd0a4a428993d5
|
||||
@@ -1,5 +1,7 @@
|
||||
# RFC: Make the shared example base providerless
|
||||
|
||||
English | [中文](2026-06-20-providerless-example-base.zh.md)
|
||||
|
||||
Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-spine-demo` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# RFC：使共享示例基础配置不依赖提供方
|
||||
|
||||
[English](2026-06-20-providerless-example-base.md) | 中文
|
||||
|
||||
Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-spine-demo` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
|
||||
|
||||
## 问题
|
||||
|
||||
示例曾有两个共享基础文件：`examples/base-core.yml` 不依赖任何模型提供方，而 `examples/base.yml` 在此核心之上加入了真实的 `llm-deepseek` 适配器。快照回放需要搭配 `llm-replay` 使用那个提供方无关的核心，因为在没有 key 的情况下加载真实适配器会抛错。常规演示则需要真实适配器。结果是命名倒挂：名为 `base.yml` 的文件并非所有示例的可复用基础，而真正的基础反而叫 `base-core.yml`。
|
||||
|
||||
这种拆分可以理解，但它让每次解释配置都变得更长。它还导致了别扭的测试搭建方式：keyless 冒烟测试需要携带一个假 API key 才能让适配器启动，尽管模型根本不会被调用。
|
||||
|
||||
## 提案
|
||||
|
||||
将提供方无关的核心重命名为 `examples/base.yml`，让适配器选择在每个具体示例中显式声明。编码与 ACP 真实配置添加一小段 `llm-deepseek` include 或本地块；快照配置添加 `llm-replay`。删除 `examples/base-core.yml`。
|
||||
|
||||
共享基础应当只包含提供方无关的服务与工具：`llm`、会话、系统提示词、工具、agent、不变式、bash 执行器与 bash 工具 schema。任何选择模型提供方的内容都属于叶子配置。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `examples/base.yml` 不依赖任何提供方。
|
||||
- `examples/base-core.yml` 已删除。
|
||||
- 真实演示配置显式添加 DeepSeek 适配器。
|
||||
- 快照回放配置引入同一个提供方无关的基础及其回放适配器。
|
||||
- [examples README](../../../../examples/README.md)、各示例的 README 与 RFC 引用不再解释"base = base-core 加适配器"。
|
||||
|
||||
## 放弃了什么
|
||||
|
||||
真实演示失去了一层便利：每个都必须显式引入适配器。对示例而言这是正确的默认值，因为适配器选择是可变部分，而提供方无关的接线才是共享的产品核心。
|
||||
|
||||
<!-- rfc-format: alternatives-not-recorded (pre-format RFC) -->
|
||||
Reference in New Issue
Block a user