docs: bilingual counterparts for the projection READMEs; review-driven RFC precision

New zh pairs for the session-projection group and package READMEs (both gained their missing language-switcher lines); the packages/README rows, apiproxy README, and tool-todo README zh sides catch up with their edited English; the group README's stale ProjectionProvider name becomes ProjectionDefinition. RFC precision from review: asOfSeq is the last event's seq (session.seq - 1, -1 empty; subscribed.lastSeq vocabulary) and a new risk names the accepted dev-only staleness window when registry churn changes the key set mid-session. Pairing re-recorded; 540 pairs consistent.
2026-07-28 01:19:30 +08:00
parent c10edbbc85
commit 4d7b30ab72
15 changed files with 98 additions and 18 deletions
--- a/packages/README.i18n.yaml
+++ b/packages/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/README.md
-README.md: d16e395a42e491461c0862227205931894c27e39
-README.zh.md: 3fb4181ce7ae7b0d79a13ca4358b9df39d83ef1f
+README.md: f5420b6f2f30837b030a0e832a438c34674a6f23
+README.zh.md: 7beeaadf380a742cbdb6447553f42692a97fad10
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -28,22 +28,22 @@
 | [`workflow/`](workflow/README.md) | 工作流能力系列：脚本引擎 seam、worker 线程引擎、面向模型的 `workflow` 与新 agent `ralph` 工具 | 产品：稳定表面 |
 | [`web/`](web/README.md) | Web 能力系列：seam、搜索／获取提供方实现和面向模型的 Web 工具 | 产品：稳定表面 |
 | [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
-| [`todo/`](todo/README.md) | Todo／规划系列：面向模型的 `todo_write` 工具 | 产品：稳定表面 |
+| [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
 | [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
 | [`timeout/`](timeout/README.md) | 工具调用超时策略：`tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
 | [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 | 产品：稳定表面 |
 | [`cordis/`](cordis/README.md) | 自指运行时工具集：检查实时运行时的插件与服务，挂载／卸载模型所写插件（[设计](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)） | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
-| [`session-persistence/`](session-persistence/README.md) | 持久化能力系列：seam + JSONL/SQLite 后端 | 产品：稳定表面 |
-| [`session-projection/`](session-projection/README.md) | 会话投影缝：域 host 插件向客户端载体供给日志衍生的每会话状态完整当前值 | 产品：稳定表面 |
+| [`session-persistence/`](session-persistence/README.md) | 持久化 seam + JSONL/SQLite 后端 | 产品：稳定表面 |
+| [`session-projection/`](session-projection/README.md) | 投影 seam：领域折叠单元供给全量值 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
-| [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务、共享 LLM 策略和选用提供方 | 产品：稳定表面 |
+| [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务与选用 LLM 提供方 | 产品：稳定表面 |
 | [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |
 | [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
 | [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
-| [`ui/`](ui/README.md) | 人类／客户端集成：TUI 与 JSON-RPC、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
+| [`ui/`](ui/README.md) | TUI 与 JSON-RPC 集成、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
 | [`examples/`](examples/README.md) | 演示组合包（agent-spine + TUI/CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
 | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
 | [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # 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 packages/host/apiproxy/README.md
-README.md: e450f7081998ce0810fc06ac688fd7214c362363
-README.zh.md: 6658f88ee3b37d1c487abb38456579ddaaba4b61
+README.md: 83a0b07773fd2d3e5eb40e0b33cc01df78a6eab6
+README.zh.md: dd0c68d54a7da9f8ec9f44bef37260ef514437f0
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -10,7 +10,9 @@

 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。

-mux 流会在每个已附加会话的订阅基线之后，以及对应的实时原始标题事件之后，立即把基于日志的最新标题投影为经过校验的 `session/title` 控制帧。该投影不会把标题加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。
+`session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
+
+会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。

 Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.create` 会创建唯一名称或接纳现有目录，`workspace.delete` 只移除 Workspace 注册记录，`session.create` 接受可选的预分配 Session id，`host/workspace-changed`、`host/workspace-removed` 与 `host/session-added` 则以任意到达顺序携带已提交的增量。删除注册记录会保留目录和会话日志；相关 Session 仍留在 `session.list` 中，并进入 Ungrouped。`SessionSummary.blank` 与 `host/session-added` 帧携带派生的零事件位：客户端隐藏空白会话并按 workspace 复用它们，在首个 `host/session-status(running:true)` 时翻转 blank，并以 `session.list` 作为重连权威；冷会话摘要永远不是空白：惰性持久化让从未追加过事件的会话根本不出现在 `list()` 中。

--- a/packages/session-projection/README.i18n.yaml
+++ b/packages/session-projection/README.i18n.yaml
@@ -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 packages/session-projection/README.md
+README.md: 81c67d56e136ba4853e86d889b485d4df80ac1fe
+README.zh.md: 72e23b78a48a989f355f9be3d34d81a440ca1d04
--- a/packages/session-projection/README.md
+++ b/packages/session-projection/README.md
@@ -1,7 +1,9 @@
 # session-projection/

+English | [中文](README.zh.md)
+
 Session-projection capability family: the seam through which domain host plugins serve whole current values of log-derived per-session state to client carriers.

 | Package | ctx key | Role |
 |---|---|---|
-| [`session-projection`](session-projection/README.md) | `sessionProjections` | The interface package: the merge-extensible `SessionProjectionMap` type table, the `ProjectionProvider` contract, and the provider registry carriers walk synchronously |
+| [`session-projection`](session-projection/README.md) | `sessionProjections` | The interface package: the merge-extensible `SessionProjectionMap` type table, the `ProjectionDefinition` unit contract, and the eagerly driven registry carriers read synchronously |
--- a/packages/session-projection/README.zh.md
+++ b/packages/session-projection/README.zh.md
@@ -0,0 +1,9 @@
+# session-projection/
+
+[English](README.md) | 中文
+
+会话投影能力家族：领域 host 插件经由此 seam，把日志派生的按会话状态的当前全量值供给客户端载体。
+
+| 包 | ctx 键 | 职责 |
+|---|---|---|
+| [`session-projection`](session-projection/README.md) | `sessionProjections` | 接口包（package）：merge-extensible 的 `SessionProjectionMap` 类型表、`ProjectionDefinition` 单元契约，以及供载体同步读取的正向驱动注册表 |
--- a/packages/session-projection/session-projection/README.i18n.yaml
+++ b/packages/session-projection/session-projection/README.i18n.yaml
@@ -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 packages/session-projection/session-projection/README.md
+README.md: 2e026aab55933c96ba961481f9597bc18cbbe910
+README.zh.md: a3e0b0f46466d19321b0950dc41d06473a54a1ce
--- a/packages/session-projection/session-projection/README.md
+++ b/packages/session-projection/session-projection/README.md
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-session-projection

+English | [中文](README.zh.md)
+
 Session-projection seam. It owns `ctx.sessionProjections`, the registry that DRIVES every registered projection unit forward over committed session events and serves finished whole values to carriers (the api-proxy history tail page and `session/projection` push frame today; TUI/ACP/headless consumers later). A domain registers pure mathematics; the framework owns the drive. Design authority: the [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).

 ## Service: `SessionProjectionRegistry` (ctx key: `sessionProjections`)
--- a/packages/session-projection/session-projection/README.zh.md
+++ b/packages/session-projection/session-projection/README.zh.md
@@ -0,0 +1,47 @@
+# @deepseek-ai/dsh-session-projection
+
+[English](README.md) | 中文
+
+会话投影 seam。它拥有 `ctx.sessionProjections`——该注册表驱动每个已注册的投影单元在已提交会话事件上前进，并向载体供给成品全量值（今天是 api-proxy 历史尾页与 `session/projection` 推送帧；日后是 TUI、ACP（Agent Client Protocol）、headless 消费方）。领域注册的只是纯数学；驱动权归框架。设计权威：[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)。
+
+## 服务：`SessionProjectionRegistry`（ctx 键：`sessionProjections`）
+
+### 公开 API
+
+- `ctx.sessionProjections.register(definition): () => void` 注册一个领域的单元。key 重复或 `stateVersion` 非法都会 throw；注册是挂在调用方 fiber 上的 effect，领域插件卸载后其 key（连同缓存的 cell）从后续驱动与快照中消失——客户端将其读作能力缺失。
+- `ctx.sessionProjections.onChanged(listener): () => void` 订阅变更流：每个已提交事件、每个状态引用发生变化的单元各回调一次，携带经 schema 校验的 view 与致因 seq。与 `register` 一样绑定 effect。
+- `ctx.sessionProjections.snapshot(session): ProjectionSnapshot` 对全部已注册单元做一次一致的同步切面——`{ asOfSeq, values }`，其中 `asOfSeq` = 所有值共同反映到的最后一个事件的 seq（空日志为 `-1`）。
+
+### 关键类型
+
+- `SessionProjectionMap`——整条链路唯一的 merge-extensible 类型表（host 侧单元、协议块、React 钩子）。值是协议层 JSON 全量值；渲染归 slot 体系管，永远不归本层。
+- `ProjectionDefinition<K, S>`——`{ key, schema, init(), apply(state, event), view(state), stateVersion }`：由三个纯同步函数外加若干声明构成的状态驱动计算单元（state-driven computation unit），绝不是一个不透明的 getter。
+
+## 契约
+
+- **框架负责驱动，领域负责计算。** 注册表只订阅一次 `session/event`；每个已提交事件都正向经过每个单元的 `apply`。领域不持有任何订阅。cell（每会话每单元一份 `{state, observedSeq}`，以 WeakMap 为键）惰性构建——在事件流过之后才注册的单元，或读取一个早于该注册的会话，都在首次触达时从 `init` 出发在内存日志上折叠。
+- **同引用即无工作。** 对与单元无关的事件，`apply` 必须返回同一个状态引用；驱动以 `Object.is` 把守变更流，因此不匹配的事件只花一次调用，不产生任何下游工作。
+- **全量值事件规则（承重）。** 携带状态的日志事件必须携带变更后的完整状态，绝不携带裸增量——这让每次状态转移始终足够廉价，也让每个被供给的值自描述（对消费方即 last-wins）。
+- **单元的同步纪律。** `init`/`apply`/`view` 必须是同步的；载体在切出页面切片的同一 tick 内读取 `snapshot()`，`asOfSeq` 之所以是一个一致切面正系于此。误写成异步的 `view` 会返回 Promise，让边界的 `schema.parse` 当场大声失败。
+- **状态是纯 JSON，`stateVersion` 是其失效锚点。** 持久投影缓存（persisted projection cache，后续阶段）存储 `(sessionId, key, stateVersion, observedSeq, stateJson)` 行；状态形状或折叠语义一旦变化就递增 `stateVersion`，使陈旧行被丢弃，而不是被正向 apply 成垃圾。
+- **本层没有协议词汇。** 注册表只暴露变更流与快照读取面；载体（api-proxy）据此自铸各自的帧（`session/projection`）与块。
+- **可选 seam。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
+
+## 职责
+
+这是能力 seam 拆分中「接口 + 驱动」的那个包：领域 host 插件（如 `dsh-tool-todo`）贡献单元，载体（`dsh-host-apiproxy`）消费快照与变更流，两侧互不相识。
+
+## 模型体验
+
+无——注册表只对已入日志的会话状态计算面向客户端的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+
+#### KV Cache 影响
+
+无；投影从不组装或发送提供方请求。
+
+## 已知限制与延期工作
+
+- **每个尾页携带每个已注册的 key**——尚无逐 key 的 opt-out 或惰性 key 请求形状；在值都是 UI 量级的全量状态（一张 todo 清单、一份 goal 快照）时可以接受，若某领域的值变大再重议。
+- **正向驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，契约不变。
+- **持久投影缓存属于后续阶段**——cell 目前只活在内存里；重启后首次触达时靠折叠内存日志重建。`stateVersion` 字段是为该阶段预先声明的失效锚点。
+- **单元同步纪律只有部分可机械把关**——边界 `schema.parse` 能拒绝返回 Promise 的 `view`，但阻塞的 `apply`、或读取撕裂的非会话状态的 `apply`，只能靠评审把关；invariant 配套记载了为何不存在运行时检查。
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/README.i18n.yaml
@@ -1,6 +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
-README.md: 3615f68953cfe6cdc0e6fc41bf75b8dfdf90a310
-README.zh.md: c4a7d829cc1583b65d2c8afa1683d957f68722e9
+#   pnpm run verify-translation-pairing --write packages/todo/tool-todo/README.md
+README.md: 5d748e981e8cc75a189916ab87e5d486ba916603
+README.zh.md: ddd22eb13fde81ddd05465ca789b302bb33bb8d9
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -22,6 +22,10 @@

 规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久列表：[TUI 应用](../../examples/tui-demo)将其显示为持久计划，[web 客户端](../../client/ui-conversation)则基于 `ConversationSnapshot.todos` 渲染计划横条与专属工具行（[Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)）。

+## 会话投影
+
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session-projection/session-projection/README.md)）时，本包在一个注入式子插件下注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表（last-wins；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 1。key 在本包合并进 `SessionProjectionMap`（经接口包的 `/types` 出口）；框架驱动该单元，载体在历史尾页与 `session/projection` 推送帧上供给该值。未装注册表的组合不受影响。
+
 ## 导出形状

 函数／命名空间插件：导出 `name`/`inject`/`apply`，不提供默认导出。意外的 `export default` 会通过 Loader 的 `unwrapExports` 折叠模块并丢弃 `inject`（参见 [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）。