跨会话引用 lacemou/dsh-session-ref

dsh-session-ref

CI

DeepSeek Harness 的跨会话引用（mention）插件。

在任意会话（包括另一个工作区/文件夹的会话）里，粘贴 @label 引用，宿主就会把被引用会话的内容快照注入给当前模型阅读——跨文件夹的任务和对话可以直接 @ 引用，不再需要口头转述。

完整设计见 SPEC.md。英文版见 README.en.md。

版本支持(0.2.x)

| 插件版本 | DSH 宿主 | 说明 |
| 0.2.x(当前) | 0.1.2-rc.1(及同队列后续)| 面向最新队列;client 半对旧队列同构,理论上可回退运行 |
| 0.1.x | 0.1.0-rc.6 ~ 0.1.1-rc.2 | 旧队列发布线(迁移记录见 .agents/MIGRATION-0.1.2.md) |

0.1.2 队列拆除了 @deepseek-ai/dsh-client-runtime(插件 0.1.x 的 client 依赖), 因此 0.2.0 的 client 半改为零宿主值依赖:bundle 只 require react, dsh.client.inject 置空,类型全部指向 0.1.2-rc.1 的新域包(cordis / dsh-api-session-controller / dsh-session)。同一产物在 0.1.2+ 宿主上不会再因 phantom dependency 而不进入 boot graph。

特性（MVP）

- 宿主半：agent/pre-step 解析 @label 与裸 dsh-session:，调用原生 sessionReferenceResolver.prepare() 注入快照（转录中渲染为独立的 Session recall 行），并把 mention 改写为可读 @label。若部署未挂载 sessionReferenceResolver 服务（如 rc.6 profile），插件会自动注册它。
- 客户端半：composer 工具条「复制引用」按钮，一键复制当前会话的引用 mention（@标题）。
- 全部跨会话能力复用 DSH 原生 @deepseek-ai/dsh-session-reference 管线：并行读取、去重、预算（≤3 源 / ≤64KB）、自引用拒绝、untrusted 上下文警告。

重要限制

1. 社区插件：非 DSH 官方组件，由社区维护；依赖的宿主内部契约可能随版本调整而失效。
2. 快照语义：引用为 capture-time 快照，非实时会话；源会话的后续变更不向目标传播。
3. 上下文预算：单条消息至多 3 个源、单源快照上限 64KB；超限时截断或整体拒绝。
4. 自引用拒绝：引用当前会话被原生机制拒绝，以防止循环引用。
5. 内部依赖：依赖 agent/pre-step、sessionReferenceResolver 等宿主内部接口及会话日志格式，宿主升级后可能失效。
6. 能力边界：非无限上下文（注入快照计入目标会话上下文直至压缩），亦非自动协作（单向引用，不含消息投递或任务转交）。

安装

方式一：npm 安装（推荐）
dsh plugin --profile web add dsh-session-ref

方式二：git 安装（lib/ 已提交，无需构建）
git clone https://github.com/lacemou/dsh-session-ref
dsh plugin --profile web add /path/to/dsh-session-ref

方式三：本地开发安装
cd dsh-session-ref
npm install
npm run build
dsh plugin --profile web add /path/to/dsh-session-ref

安装后重启 web 进程（Ctrl-C 后重新 dsh web）才会加载新 bundle。

使用

1. 在会话 A（源）的输入框工具条点击 复制引用。
2. 剪贴板得到 @标题A。
3. 在会话 B（目标，可在另一个工作区）输入框粘贴并发送。
4. 转录中会出现一条独立的 Session recall 行（带来源标题与保留/省略统计），模型同时看到 ## Referenced sessions 快照内容与可读的 @标题A。

也可手写引用：@任意标签 或裸 dsh-session:。
自引用（引用本会话）被原生拒绝；超过 3 个不同源或快照超预算时原生拒绝，消息原样保留。

开发

npm run typecheck # tsc --noEmit
npm run test # vitest run（21 个测试：宿主半注入、URI 编码一致性、客户端复制）
npm run build # tsc --noEmit + tsdown → lib/index.js (node) + lib/client.js (browser)

lib/ 已提交，git 安装直接使用预构建产物。

验证状态（2026-08-18）

端到端已闭环（Web GUI 真实环境）：

- ✅ 宿主半解析 mention → 原生 prepare() 真实调用 → 快照注入为 session-reference / recall 上下文（转录出现 Session recall 行）
- ✅ 快照统计正确：originalMessages / retainedMessages / omittedMessages / omittedBytes / truncated（大会话触发预算截断，属设计行为）
- ✅ mention 改写为可读 @label
- ✅ composer 工具条出现 「复制引用」 按钮
- ✅ 19 个 vitest 单测全绿（解析/改写/注入顺序/失败降级/URI 编码一致性/客户端复制）
- ✅ URI 编码与原生 encodeSessionReferenceUri 逐字节一致

注意：安装插件后必须重启 web 进程——web 的 ESM 缓存不会自动更新，否则运行的仍是旧版插件代码（典型症状：mention 不注入、模型只看到原文）。

已知限制

- 无 @ 自动补全（见下方 Roadmap 的 M2；当前靠「复制引用 → 粘贴」闭环）。
- 快照仅文本投影；非文本块（图片/工具结果）不跨会话。
- 读取其他 DSH 版本写入的会话可能失败（原生限制），失败时消息原样降级。
- 引用当前宿主从未加载过的会话（跨进程）走 persistence 路径，部分部署（如 headless profile）可能不支持；引用 live 会话始终可用。

Roadmap（后续路线）

| 里程碑 | 内容 |
| M2 | 输入框 @ 自动补全：输入 @ 弹出会话候选列表（来自原生 listCandidates，按工作区亲和度排序），键盘选择后自动插入 @标题——把「复制-粘贴」升级为一步 @ 选择 |
| M3 | 跨工作区目录浏览 + 引用粒度选择（整会话 / 用户结点 / 区间） |
| M4 | 与 dsh-crosstalk 集成：引用 + 转交任务 |
| M5 | 把「复制 Session ID / 复制引用」贡献回上游核心 UI |

完整设计见 SPEC.md。

License

MIT