@heeweelee/dsh-session-plugin

Readme

# @heeweelee/dsh-session-plugin

一个可安装的 DeepSeek Harness（DSH）插件，把「输入框历史回填」和「会话右键归档（删除）」作为发布包提供。

- **输入框历史**：在输入框聚焦时按 `↑` 回填上一条你发过的消息，继续 `↑/↓` 切换（↓ 走到底会落到空输入框）；会话标题栏会多一个 `↑ 历史` 按钮。
- **右键删除（归档）**：在工作区左侧会话列表里右键某个会话 →「删除该会话…」→ 二次确认后执行，走 DSH 原生 `archiveSession`（归档隐藏，不破坏磁盘文件）。

## 快速上手

1. 安装本包（见「安装」），重启 DSH 使其生效。
2. 把光标点到输入框，按 `↑` 回填上一条你发过的话；再按 `↑`/`↓` 在历史里上下切换；按 `↓` 到最后会清空输入框。
3. 想删掉一个会话，到左侧会话列表右键它 →「删除该会话」。这是**归档**（从列表隐藏），不是物理删除文件，可放心用。

## 安装

```bash
dsh plugin add @heeweelee/dsh-session-plugin@0.1.6
```

或在 DSH Desktop 的 **设置 > 插件** 市场中安装。安装后重启 DSH 使新包生效。

## 卸载

```bash
dsh plugin remove @heeweelee/dsh-session-plugin
```

或从 **设置 > 插件** 里禁用/移除；随后重启 DSH。卸载只移除本插件，不会影响你已归档（隐藏）的会话数据。

## 配置

可选：在 `DSH_HOME`（默认 `~/.dsh`）下放一个 `dsh-session-plugin.json`，把回填历史
条数窗口调大/调小：

```json
{ "historyLimit": 200 }
```

- 未提供该文件时默认保留最近 **100** 条用户消息；改完需重启 DSH 生效。
- 插件还会在同目录写一个缓存文件 `dsh-session-plugin-history-cache.json`，
  用于重启后加速首次召回，可随时删除，会自动重建。

## 权限与数据

- 本包没有运行期 npm 依赖，运行时代码是你的本地用户权限。
- Host 三个路由是同源、无鉴权的进程内接口：
  - `GET  /api/dsh-session-plugin/history?sessionId=` — 只读该会话 `user/message` 文本历史；
  - `GET  /api/dsh-session-plugin/sessions` — 只读会话 `{id, title}` 列表；
  - `POST /api/dsh-session-plugin/archive` — `{sessionId}` 归档会话。
- `archive` 只归档（隐藏）会话，**不删除磁盘文件**；历史读取是只读操作。
- 防 CSRF：`archive` 要求请求同时携带自定义头 `x-dsh-csrf: 1` 且
  `Origin` 为空或与本机同源——跨站页面发出的简单 POST 无法满足，会被 403 拒绝。
- 「删除该会话」默认二次确认后才执行。

## 兼容性

- 依赖 DSH `0.1.0-rc.7` 运行时（`@deepseek-ai/dsh-host-webserver`、`@deepseek-ai/dsh-session-query`、`@deepseek-ai/dsh-workspace` 都以 `0.1.0-rc.7` 精确固定）；旧的非 scoped `cordis` 会被商店受管安装器拒绝。该固定值是**最低验证版本**，不是上限：`0.1.2-alpha.1`（DSH Desktop 2.0.4）上本包依赖的 Host 契约 `sessionQuery.readSession/listSessions`、`workspaceRegistry.archiveSession`、`webServer.register({kind:'exact'})` 与 slot `conversation.session.header.actions` / `shell.overlay` 及标准 props `useInput` / `inputActions` / `sessionId` 均保持不变。
- **输入框形态跨版本兼容**：DSH 2.0.4 起 composer 是 shell 所有的 Lexical 编辑器（`div[contenteditable][role=textbox][data-composer-input][data-phase]`），此前是受控 `<textarea data-phase>`。本包 0.1.6 起两种形态都识别（见 `isComposerSurface`），所以 ↑/↓ 在新旧 DSH 上都工作。若你维护的是 0.1.5 及更早版本，升级到 2.0.4 后 ↑/↓ 会静默失效。
- Node `^22.19.0 || >=24`（与 DSH Desktop 内置 Node 运行时一致）。

## 架构

这是从动态 Cordis 插件 `sess-7/pkg-9`（"Session Input History + Archive"）1:1 移植而来的发布包，二者共用同一套 Cordis 模型（`apply(ctx)`），只有 RPC 传输方式改变：

| 动态插件 | 本发布包 |
| --- | --- |
| `harness.handle(...)` / `host.call(...)` | Host `webServer` JSON 路由 + Client `fetch('/api/dsh-session-plugin/...')` |
| `ctx.get('slots')` | `ctx.slots`（`inject: ['slots', 'timer']`） |

### Host（`index.js`）

- `inject: ['sessionQuery', 'workspaceRegistry', 'webServer']`
- 注册三个路由（见「权限与数据」）。

### Client（`dist/client.js`）

- `inject: ['slots', 'timer']`
- 注册 `conversation.session.header.actions`（`↑ 历史` 按钮 + `↑/↓` 键盘监听）和 `shell.overlay`（toast + 右键菜单）。
- 输入框表面统一由 `isComposerSurface` / `findComposerSurface` 判定（`data-phase` + `<textarea>` 或 `div[data-composer-input]`），`domForceWrite` 只服务于 textarea 形态；Lexical 形态下写入只走 `inputActions.setDraft()`。

## 目录结构与发布

```
index.js             Host 入口（ESM，直接可运行）
dist/client.js       Client 入口（window.__ModuleLoader__ 预打包格式）
cordis.patch.yml     bundle patch（插入到 profile 组合）
package.json         声明 dsh.bundle.patch / dsh.client / exports
```

`dist/client.js` 是手写的模块加载器 bundle（与内置插件 `lib/client.js` 相同的
`window.__ModuleLoader__.load({ id, factory })` 线格式）。发布前建议用 DSH 插件
构建链重新生成该文件，并核对 `id` 等于包名 `@heeweelee/dsh-session-plugin`。

## 故障排查

- **重启后按钮/回填不出现**：确认 `@heeweelee/dsh-session-plugin` 在 profile 的 `dsh.profile.bundles` 里，且已重启 DSH。
- **按 `↑`/`↓` 没反应**：先点一下输入框让光标聚焦；只有当输入框为空（或正处于回填状态）时才会接管 `↑/↓`，输入法候选中的方向键一律放行。若输入框里已有内容，请先清空。用 0.1.5 及更早版本 + DSH 2.0.4+ 时按键必然无响应（只认 `<textarea>`），请升级到 0.1.6。
- **区分「插件没挂载」和「按键守卫不匹配」**：点会话标题栏的「↑ 历史」按钮——它不走按键守卫。能回填或弹出提示说明插件已挂载、Host 路由正常，问题只在按键那侧；按钮本身不出现，则去 **设置 > 插件 > 插件清单** 看该条目的状态圆点是否处于已挂载 phase。
- **回填的历史不完整**：历史来源是 `user/message` 事件文本；图片、引用等非文本内容不进入回填文本。含 `@文件` 的引用在发送时即拍平成 `@path` 字面文本，回填时会以 `@path` 文本形式还原。
- **打完字没发送、手动清空后还出现在历史里**：0.1.3 及以前版本存在该问题；0.1.4 起改为「发送后与 Host 日志对账 + 10 秒兜底过期」，未真正发送的内容不会留存。
- **「删除该会话」点了没反应**：需在工作区**左侧会话列表**的条目上右键触发；二次确认后才执行归档，归档后列表刷新即消失。

## 安全边界

本包没有运行期 npm 依赖，Host 三个路由为同源、无鉴权的进程内接口；`archive`
只归档（隐藏）会话，不删除磁盘文件。商店收录/安装不构成安全背书——安装后代码以
本地用户权限运行。

## 许可证

MIT