docs: bilingual counterparts for the projection-cache README and the touched pair records
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.
This commit is contained in:
imccyu
@@ -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
|
||||
|
||||
@@ -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 两个必写点的节流后写，以及冷读阶梯（缓存行 + 持久化尾部重放） |
|
||||
|
||||
@@ -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
|
||||
@@ -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:
|
||||
|
||||
@@ -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` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。
|
||||
Reference in New Issue
Block a user