dsh-quick-session

Readme

# dsh-quick-session

点侧栏底部那只鲸鱼尾，就能**不挑项目**开始一次会话。

插件只做两件事：准备一个共用的临时目录，再把它登记成一个名为「快捷会话」的 Workspace 并打开空白会话。剩下的全部交给 DSH 官方的输入框（composer）。

## 更新记录

### 0.2.0 —— 从自研弹窗改成「专用工作区」

0.1.0 是自研弹窗：自己收第一句话、自己建会话。这条路的尽头是天花板 —— 官方 composer 的权限档位、Plan 模式、模型与思考强度、图片、`@` 引用文件都能自己接，**但其它插件挂在对话栏上的开关接不了**（每个开关都是插件自绘组件 + 自有宿主路由，只有官方 composer 会渲染它们）。

所以 0.2.0 把弹窗整个删掉，改成：

- 宿主半边准备 `%DSH_HOME%\scratch`（不再每会话一个子目录），浏览器半边把它登记成 Workspace「快捷会话」并打开其空白会话；
- 输入框就是官方 composer：权限四档、Plan、模型/思考强度、拖拽粘贴图片、`@` 引用文件、dsh-genui 与 dsh-vision-router 等第三方开关，全部原生可用；
- 每个快捷会话共享同一个沙箱根 `~/.dsh/scratch`，而不是各自一个临时目录；
- 失败时在底部弹一条 toaster（不再有对话框）。
- 新增 `test/run.mjs`（21 条断言，宿主 + 客户端）。

### 0.2.0 之后 —— 把 0.1.0 的旧快捷会话迁进「快捷会话」分组

0.1.0 建出来的会话 cwd 是 `~/.dsh/scratch/quick-*`，所以它们不匹配任何 Workspace，一直躺在侧栏「未分组」。0.2.0 上线后可以把它们真正迁进「快捷会话」——细节见下方[会话迁移](#把-010-的旧快捷会话迁入快捷会话工作区)。

> 最后还是走到了单独设置一个工作区的情况啊，~但是这样和我手动设置一个工作区有什么区别~还是有区别的，不用自己开路径（

## 它做什么

1. 在 `%DSH_HOME%\scratch` 准备一个共用的临时目录（Host 半边的一个已鉴权 POST 路由负责，幂等）；
2. 把它登记成一个名为**快捷会话**的 Workspace（已存在则复用，不改标题），并打开它的空白会话。

于是输入框就是**官方 composer**：权限档位、Plan 模式、模型与思考强度、拖拽/粘贴图片、`@` 引用文件，以及其它插件挂在对话栏上的开关（如 dsh-genui 的提示词开关、dsh-vision-router 的识图开关）全都可用，不需要本插件复刻任何一项。

再点一次鲸鱼尾会复用该工作区里现成的空白会话，不会堆一堆空会话。

## 为什么是「工作区」而不是「真·无工作区」

官方 Conversation 对**空白且不属任何 Workspace** 的会话会禁用输入框：

```js
// @deepseek-ai/dsh-client-ui-conversation/lib/client.js
const inert = sessionId === void 0 || hero && chipTitle === void 0
```

`chipTitle` 只能来自待选工作区或会话所属工作区，所以无工作区的空白会话永远 `inert`（占位文案「选择一个工作区开始」）。会话有了第一条消息后 `hero` 变 false、原生输入框恢复，但那已经晚了 —— 第一句话都没地方打。

而第三方插件开关由各自插件自绘、只注册在 `conversation.input.*` 这些 **session 作用域**槽位上，只有官方 composer 会渲染它们 —— 自研弹窗无论做多复杂都拿不到这些开关。

结论：捷径是让快捷会话**属于一个真实 Workspace**，借它的官方 composer。代价是侧栏会多出一个「快捷会话」分组（所有快捷任务共享它、共享同一个沙箱根目录，而不是每个任务一个分组）。

## 安装

桌面版只接受发布到 npm 的插件，本地开发用 `link:` 装：

```powershell
& "<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add link:"C:\Users\asus\.dsh\profiles\desktop\plugins\dsh-quick-session"
```

或在 GUI 的插件管理里启用/禁用 `dsh-quick-session`。包声明了 `dsh.bundle`（`patch: ./cordis.patch.yml`）与 `dsh.client`（`platform: web`），纯 ESM、无需构建。

卸载：

```powershell
& "<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop remove dsh-quick-session
```

卸载后**目录与会话都保留**：`~/.dsh/scratch`，以及侧栏里的「快捷会话」分组（在侧栏右键删分组不会删文件）。

## 架构

**宿主半边**（`lib/host.js`，`inject: ['webServer']`）注册一条路由：

    POST /plugins/dsh-quick-session/prepare  ->  { cwd }

它 `mkdir -p` 出 `%DSH_HOME%\scratch` 并返回绝对路径。请求先过请求栅栏：

```js
const connection = ctx.get('connection')             // 可选访问，缺服务时为 undefined
const rejection = connection?.requestRejection(req)  // 403 主机/来源不符，401 未通过浏览器会话鉴权
```

被拒绝时**不写任何东西**。这里必须用 `ctx.get(...)`：在 Cordis 里直接读未注入的服务属性会**抛异常**，而 web 服务器对路由处理函数的异常统一回 400（这正是早期版本每个请求都 400 的原因）。

**浏览器半边**（`lib/client.js`）：

```js
const cwd = await prepareScratchDirectory()                  // POST 上面的路由
let workspace = await ctx.workspaces.create({ path: cwd })   // 幂等，已存在则复用
if (workspace.title !== '快捷会话')
  workspace = await ctx.workspaces.rename(workspace.workspaceId, '快捷会话')
await ctx.uiWorkspace.openWorkspace(workspace.workspaceId)   // 复用/新建空白会话并打开
```

UI 只有两处：`sidebar.footer.action`（id `dsh-quick-session`，order 45）的按钮，和 `shell.overlay`（id `dsh-quick-session-toast`，order 850）的失败提示。

## 沙箱与权限

会话 `cwd` 就是沙箱边界，因此快捷会话的文件写入落在 `~/.dsh/scratch`。权限沿用当前四档预设，默认仍是「工作区写入 + 变更前确认」。

## 把 0.1.0 的旧快捷会话迁入「快捷会话」工作区

**结论先行：只改 `workspace.json` 的 `sessionIds` 没有用，必须改会话存储头里的 `cwd`。**

会话归属是校验出来的，不是一张可编辑的名单（`@deepseek-ai/dsh-workspace/lib/index.js`）：

```js
get sessionIds() {                                   // 每次读取都按 cwd 过滤
  return this.record.sessionIds.filter((id) => this.host.candidateMatches(id, this.record.path))
}
// attachSession(): cwd 必须 realpath 后等于 workspace.path，否则抛
if (cwd !== this.record.path) throw new Error(`cannot attach session '${id}' ... its cwd resolves to '${cwd}'`)
// mutate(): 每次写入都把不匹配的 id 剪掉
const sessionIds = changed.sessionIds.filter((id) => this.host.candidateMatches(id, changed.path))
```

而 `candidateMatches` 认的 `sessionPaths` 来自会话**存储头**（`%DSH_HOME%\sessions\<项目桶>\<sessionId>\session.v4.jsonl.zstd` 的第一行），只在宿主启动时建立索引。所以流程是：

1. **备份**：把要动的会话日志与 `%DSH_HOME%\storages\workspace.json` 复制一份；
2. **改头**：解压多帧 zstd、把首行 header 的 `cwd` 改成 `%DSH_HOME%\scratch`、重压成单帧（带 checksum），逐行回读校验（除 `cwd` 外事件零改动）；
3. **挪桶**：项目桶名是 cwd 的编码 —— `projectKey(cwd)` 把 `/ \ :` 压成 `-`、其它不安全字符转 `~XXXX`、再加 `--…--` 包边，例如 `C:\Users\asus\.dsh\scratch` → `--C-Users-asus-.dsh-scratch--`。会话目录要挪进新桶，否则后续写入会分裂到另一处；
4. **登记**：把这些 sessionId 加进 `workspace.json` 里「快捷会话」工作区的 `sessionIds`（前置，`updatedAt` 同步）；
5. **重启 DSH**：注册表只在 `Service.init` 里 `listStoredHeaders()` → `replaceHeaderIndex()`，运行中的进程仍持有旧索引。

迁移前后都要注意：**运行中不要点开待迁移的旧会话**，它的日志已经换目录，而进程还记着旧路径。

## 改代码与重新加载

安装位置：`%DSH_HOME%\profiles\desktop\plugins\dsh-quick-session`，依赖写作 `link:./plugins/dsh-quick-session`。

bundle 行用的是**相对说明符** `./lib/host.js`（相对**本包目录**解析，不是 profile 目录），这是为了让运行中的宿主能重新加载，原因有两条：

1. `dsh-hmr` 的 `ignored` 默认含 `**/node_modules`，插件经 node_modules 符号链接进来，文件改动不会触发重载；
2. 即使能触发，Node 会按 URL 永久缓存 ESM 模块，并且**进程内对 package.json 的 `exports` 映射也有缓存**，所以改 `main`/`exports`、改入口文件名、换子路径导出（`pkg/host`）都不会被运行中的宿主看到。

于是改宿主半边的正确姿势是：

1. 把 `lib/host.js` 复制成**新文件名**（例如 `lib/host-2.js`）并改内容；
2. 把 `cordis.patch.yml` 里的 `name` 指向新文件名；
3. 关闭再打开组合包（插件管理页 / `plugin_manager` 的 `set_bundle` 先 false 再 true）。

新文件 URL 从未被导入过，加载器会真正 import 它。改完记得同步 `package.json` 的 `main`/`exports`，供下次启动时使用；若宿主判定 `restart-required`（reason `package-moved`），直接重启 DSH 即可。

只改 `lib/client.js` 时不需要上面这套：客户端 bundle 会重新下发，刷新页面即可。

## 图标

侧栏按钮的鲸鱼尾来自 https://www.bilibili.com/video/BV1fQaX6FE8b/ 评论区一位同好制作的 GIF。那张 GIF 的 59 帧逐像素完全相同，内容上是一张静图，所以按静图处理，没有丢动画。

原图是**不透明深色底**（#16181B）加浅色线稿，直接使用会在浅色主题下变成一个深色方块。因此：

1. 按原图自身的亮度直方图定阈值（底色峰值 luma 24），把底色抠成透明、保留线稿抗锯齿；
2. 紧贴图形裁剪并缩放到长边 96 px；
3. 编码为约 3.3 KB 的 PNG，base64 内联在 `lib/client.js` 的 `TAIL_MASK`；
4. 用 `mask-image` + `background-color: currentColor` 渲染 —— **颜色跟随主题**（浅色主题深线条、深色主题浅线条），按钮尺寸 20 px。

回退阶梯，保证按钮永远不会是空的：
`TAIL_MASK`（同好制作的鲸鱼尾巴）→ 官方 `@deepseek-ai/dsh-client-ui-primitives` 的 `FISH_LOGO_PATH` 尾鳍裁切（viewBox `16.2 0 6.96 8.4`）→ `🐋` 字形。

### 换图或调尺寸

- **复现所装图标**：`DSH_MASK_KEY_HI=191 node tools/make-mask.mjs <图片>` —— 该阈值下输出与 `lib/tail-mask.base64` 逐字节相同，它就是所装遮罩的权威副本。
- **换图**：`node tools/make-mask.mjs <图片>` 会打印一行 `const TAIL_MASK = ...`，替换 `lib/client.js` 里的同名常量即可。
  该脚本用应用内自带的 sharp，需要指向应用模块目录并用应用的 Electron 运行：

      $env:ELECTRON_RUN_AS_NODE = 1
      & "<安装目录>\DeepSeek Harness.exe" tools/make-mask.mjs "C:\path\to\tail.gif"

- **调尺寸**：改 `QuickSessionAction` 里的 `react.createElement(WhaleTailIcon, { size: 20 })`。

## 测试

```powershell
node test/run.mjs
```

宿主半边用桩 `ctx` 验证路由注册、POST 落盘、`GET` → 405 + `allow`、鉴权拒绝不写盘、`ctx.get` 抛异常不炸 400；客户端半边在 `vm` 沙箱里加载 bundle，验证槽位注册、目录准备、工作区创建/改名/打开、失败提示与图标回退。测试把 `DSH_HOME` 指向临时目录，不碰真实 profile 状态。

## License

MIT