63 lines
3.7 KiB
Markdown
63 lines
3.7 KiB
Markdown
|
# @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` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。
|