From c0eec9d9e20bd00d254c24ab0113c520861f8969 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Tue, 28 Jul 2026 01:59:51 +0800 Subject: [PATCH] docs: bilingual counterparts for the projection-cache README and the touched pair records MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The base's bilingual gate now covers this branch's new README: add the Chinese counterpart of the session-projection-cache package README, the cache row on the group README's Chinese side, and re-record the touched pairs (group, cache, session-persistence — whose English side gained the readFrom rows earlier on this branch). verify-translation-pairing: 541 pairs consistent. --- packages/session-projection/README.i18n.yaml | 4 +- packages/session-projection/README.zh.md | 1 + .../session-projection-cache/README.i18n.yaml | 6 ++ .../session-projection-cache/README.md | 2 + .../session-projection-cache/README.zh.md | 62 +++++++++++++++++++ 5 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 packages/session-projection/session-projection-cache/README.i18n.yaml create mode 100644 packages/session-projection/session-projection-cache/README.zh.md diff --git a/packages/session-projection/README.i18n.yaml b/packages/session-projection/README.i18n.yaml index a850031e0b..eb131c5d8b 100644 --- a/packages/session-projection/README.i18n.yaml +++ b/packages/session-projection/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/session-projection/README.md -README.md: 81c67d56e136ba4853e86d889b485d4df80ac1fe -README.zh.md: 72e23b78a48a989f355f9be3d34d81a440ca1d04 +README.md: ae80a905705d205adb4a1ee66c72fa28d0d8b6d6 +README.zh.md: 97e25dd16caeeb444f5f5309eed3341d422fa1b1 diff --git a/packages/session-projection/README.zh.md b/packages/session-projection/README.zh.md index 72e23b78a4..97e25dd16c 100644 --- a/packages/session-projection/README.zh.md +++ b/packages/session-projection/README.zh.md @@ -7,3 +7,4 @@ | 包 | ctx 键 | 职责 | |---|---|---| | [`session-projection`](session-projection/README.md) | `sessionProjections` | 接口包（package）：merge-extensible 的 `SessionProjectionMap` 类型表、`ProjectionDefinition` 单元契约，以及供载体同步读取的正向驱动注册表 | +| [`session-projection-cache`](session-projection-cache/README.md) | `sessionProjectionCache` | 持久投影缓存：基于域数据形态的按会话单元 checkpoint 持久化、带 turn/end + detach 两个必写点的节流后写，以及冷读阶梯（缓存行 + 持久化尾部重放） | diff --git a/packages/session-projection/session-projection-cache/README.i18n.yaml b/packages/session-projection/session-projection-cache/README.i18n.yaml new file mode 100644 index 0000000000..57df7abd74 --- /dev/null +++ b/packages/session-projection/session-projection-cache/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-cache/README.md +README.md: 81d6094c19538f5559becbff51b00a7bfacb4206 +README.zh.md: f403ac1a897f5bac840b43dab6fc0f98bf7b7a46 diff --git a/packages/session-projection/session-projection-cache/README.md b/packages/session-projection/session-projection-cache/README.md index 8bb8efe4cd..81d6094c19 100644 --- a/packages/session-projection/session-projection-cache/README.md +++ b/packages/session-projection/session-projection-cache/README.md @@ -1,5 +1,7 @@ # @deepseek-ai/dsh-session-projection-cache +English | [中文](README.zh.md) + The persisted projection cache (`ctx.sessionProjectionCache`): durable checkpoints of every registered projection unit's state, one record per session on the domain data form (`session_projcache` domain — the shipped json backend lands it beside `workspace.json` under the configured storage root). Design authority: the [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) (persisted projection cache section). A stored row `(key → {stateVersion, observedSeq, state})` is a fold shortcut, never an authority: possibly stale (`observedSeq` says exactly how stale) but never wrong. Consequences the implementation commits to: diff --git a/packages/session-projection/session-projection-cache/README.zh.md b/packages/session-projection/session-projection-cache/README.zh.md new file mode 100644 index 0000000000..f403ac1a89 --- /dev/null +++ b/packages/session-projection/session-projection-cache/README.zh.md @@ -0,0 +1,62 @@ +# @deepseek-ai/dsh-session-projection-cache + +[English](README.md) | 中文 + +持久投影缓存（`ctx.sessionProjectionCache`）：把每个已注册投影单元的状态持久化为检查点（checkpoint），基于域数据形态（domain data form）每会话一条记录（`session_projcache` 域——出厂 json 后端将其落在配置的存储根目录下、`workspace.json` 旁边）。设计权威：[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)（persisted projection cache 一节）。 + +一条存储行 `(key → {stateVersion, observedSeq, state})` 是折叠捷径，绝不是权威：可能陈旧（`observedSeq` 精确说明陈旧到哪），但绝不会错。实现据此承诺： + +- **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部重放，绝不是错误的值。 +- **`stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。 +- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 契约的单元状态会大声失败。 + +## 写策略 + +两个必写点，其间节流： + +| 触发 | 性质 | +|---|---| +| `turn/end` | 必写——冷读要的正是轮次终值。 | +| 会话销毁（detach） | 必写——live 转 cold 的时刻；此后冷读阶梯接管该会话。 | +| 累计 `writeEveryEvents` 个已提交事件 | 配置节流（条数）。 | +| 距首个脏事件 `writeIntervalMs` 毫秒 | 配置节流（间隔）。 | + +两个 `Config` 字段均必填（无默认值）：写入节奏是部署选择，没有普适正确值，由 cordis.yml 明示。 + +## 冷读（`coldSnapshot(id, signal?)`） + +读取阶梯，快乐路径零全量日志加载：缓存行 → `sessionProjections.restoreFloor`（锚在最低可用水位下一格）→ 持久化 `readFrom(id, floor)` → `sessionProjections.restore` → 刷新行的 fail-soft 写回。这个锚使缩短的日志（崩溃修复截断）可被证明：越界的行恰好触发一次从 seq 0 的全量重读，而不是把幽灵值当现值服务。无已注册单元时直接服务 `{asOfSeq: -1, values: {}}`，不触碰持久化；无持久日志的会话以 seam 的 `not found` 拒绝。 + +`write(session)` 是两个必写点共用的同步切面检查点；载体可以直接调用（非 fail-soft——由 fail-soft 包装层负责遏制）。 + +## 组合 + +```yaml +- id: session-projection-cache + name: '@deepseek-ai/dsh-session-projection-cache' + config: + writeEveryEvents: 200 + writeIntervalMs: 5000 +``` + +注入 `storageDomain`、`sessionProjections`、`sessionPersistence`、`sessions`。没有这一行时，投影系统只跑 live（水位缓存；冷读在实现了它的载体处退回全量日志加载）。 + +## 模型体验 + +### 模型看到什么 + +什么都看不到。缓存是 host 侧读模型加速器；没有提示词、schema 或工具表面。 + +### Token 影响 + +零。 + +### KV 缓存影响 + +无——不改变任何请求内容。 + +## 已知局限与延后工作 + +- **没有淘汰或保留面**——记录按会话累积；清理存储的检查点是带外维护，与会话持久化本身同一立场。 +- **间隔节流按会话粗粒度**——计时器在一次干净写入后的首个脏事件时武装；持续的低于阈值的涓流每个间隔写一次，不是滑动窗口。 +- **`coldSnapshot` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。