# 适配 DSH 0.2.x

插件 0.2.0 适配 DSH 0.2.x（alpha 线）。0.1.x 在 0.2.x 上**不是功能退化，而是直接坏掉**：
capture 读不到对话内容而静默不写，注入的记忆消息带着已被移除的 source kind。

下面是 0.2 改掉的三处契约，以及本插件的对应改法。

## 1. `session.events` 取消，改用 session projection

0.2 删掉了同步读取完整事件日志的 `session.events` getter，
并把 `eventAt()` / `snapshotEvents()` / `ownEvents()` 全部标记 `@deprecated`、
禁止新调用（见仓库 agent note `2026-09-09-deprecate-synchronous-session-event-reads`）。
原因是运行时不再保证整条日志常驻内存，历史事件未来要走存储 I/O。

旧实现在 `turn/end` 时扫 `session.events` 找本轮区间：

```js
const events = session?.events          // 0.2 里是 undefined
if (!Array.isArray(events)) return null // → 静默返回，永不写记忆
```

官方替代是 **projection**：一个纯同步 fold，框架在每个事件提交时驱动它，
插件读「已维护好的状态」而不是回头翻历史。
新增 [`src/projection.mjs`](../src/projection.mjs) 注册单元 `localMemoryTurn`，
随事件累积当轮的 `[User]` / `[Assistant]` 文本与工具计数，在 `turn/end` 时产出成品。

契约要点（都已在实现与测试中遵守）：

- `apply` 必须同步、纯函数；不关心的事件要返回**同一个引用**（`Object.is` 不变即零下游开销）。
- `state` 必须是 plain JSON，这是持久化缓存的前提。
- `stateVersion` 改状态结构或语义时必须递增，否则旧缓存行会被前向应用成垃圾数据。
- 需要在 `inject` 里声明 `sessionProjections`。

## 2. 不再有公共的 `plugin` message source kind

0.2 把消息来源改成可合并扩展的 `MessageSourceMap`，每个生产者声明自己的 `kind`，
明确「没有共享的兜底 `plugin` kind」。旧写法：

```js
source: { kind: 'plugin', plugin: 'local-memory', form: 'snapshot', ... }
```

现在用插件名自己作为 kind（`SOURCE_KIND`）：

```js
source: { kind: 'local-memory', form: 'snapshot', sections: [...] }
```

`form: 'snapshot'` 保持不变——它表示同一生产者的新快照顶替旧快照，
这正是重复注入的记忆不会在上下文里层层堆积的原因。

capture 过滤真实人类输入时也跟着改：只认 `source.kind === 'user'`，
其余（包括本插件注入的记忆）一律跳过，避免记忆自我喂养。

## 3. `SessionPersistence.locate()` 退出公共接口

锚点里的 `db:` 字段原先用 `ctx.sessionPersistence.locate(header).path` 取会话日志路径。
0.2 里 `locate` 在 jsonl 后端变成私有方法，公共抽象类只剩
`create` / `open` / `flush` / `stat` / `list`，异步替代 `resolveCurrentLog()` 属于后端特有实现。

锚点只需要一个能回溯原会话的稳定句柄，因此改为记录会话 id：

```
<!-- session:ses_xxx turn:3 db:session:ses_xxx -->
```

字段名仍叫 `db:`，保持与 opencode memsearch 插件的锚点格式逐字节兼容，
两边继续互读、互不覆盖。

## peerDependencies 里的 prerelease 陷阱

旧 manifest 写的是 `"@deepseek-ai/dsh-tools": "*"`。
按 semver 规则，`*` **匹配不到任何预发布版本**：

```
semver.satisfies('0.2.1-alpha.1', '*')  // false
semver.satisfies('0.2.1', '*')          // true
```

也就是说原来的 peer 范围从来没真正匹配过 alpha 构建。
现在显式带上 prerelease 下界：

```json
"@deepseek-ai/dsh-tools": ">=0.2.1-alpha.0 <0.3.0"
```

这样 `0.2.1-alpha.1`、后续 `0.2.1`、`0.2.x` 都能匹配，`0.3.0` 之外则不匹配。

## 升级后验证

```bash
npm test       # 单元测试（含 projection 折叠）
npm run build  # 重新生成已提交的 lib/
npm run smoke  # 用 0.2.x 形状的假 ctx 跑通注册 → 折叠 → 检索
```

插件在 DSH 启动时加载，升级后需要**重启 DSH 并新开会话**；
浏览器端还要硬刷新（Cmd/Ctrl+Shift+R）。