dsh-command-palette

Readme

# dsh-command-palette

中文 | [English](README.en.md)

[![npm](https://img.shields.io/npm/v/dsh-command-palette)](https://www.npmjs.com/package/dsh-command-palette)
[![stars](https://img.shields.io/github/stars/chenyangcun/dsh-command-palette?style=flat)](https://github.com/chenyangcun/dsh-command-palette)

适用于标准版 DeepSeek Harness（DSH）的键盘优先命令面板。连续快速按两次 Shift，即可搜索和打开会话、工作区、设置页面、已安装功能或可复用的自定义指令。

![DSH 命令面板：最近会话与工作区](docs/images/command-palette.png)

## 安装

```sh
dsh plugin --profile web add dsh-command-palette
```

安装后重启当前 DSH Web 进程，然后打开 **设置 → 命令面板** 管理自定义指令。

## 功能

- **双 Shift 唤起**——只监听当前获得焦点的 DSH Web 窗口，不注册系统级全局快捷键
- **最近会话**——默认展示最近更新的六个有效会话
- **会话搜索**——按标题、工作目录、Agent 预设或会话 ID 搜索
- **工作区切换**——从命令面板直接在目标工作区启动会话
- **设置页跳转**——自动读取 DSH 已注册的设置菜单，搜索后直接打开对应设置页面
- **自定义指令**——保存常用 Prompt，可选择每次新建会话或复用专属会话
- **工作区绑定**——为自定义指令的新会话指定目标工作区
- **扩展 Provider**——其他 Client 插件可以注册自己的命令或触发面板

## 使用

1. 在 DSH Web 窗口内连续快速按两次 Shift。
2. 输入关键词筛选命令。
3. 使用 `↑` / `↓` 选择，按 Enter 执行，按 Esc 关闭。
4. 在 **设置 → 命令面板** 中添加、编辑或删除自定义指令。

插件会在每次打开面板时读取当前已注册的设置页面，因此其他插件新增的设置菜单也会自动出现在“设置”分组中。

自定义指令启用“复用专属会话”后，首次执行会创建会话并保存绑定；后续执行继续向同一会话发送内容。如果绑定会话已经归档或不可用，插件会自动创建新会话。

## 标准 DSH 与扩展接口

本包不依赖 Electron、DSH Desktop preload 或任何 `window.dshDesktopCommandPalette` 全局对象。会话、工作区、设置和 UI 均通过标准 DSH Client 服务实现。

插件在 Client Context 中提供 `commandPalette` 服务，后续增强插件可以注册附加命令：

```js
exports.inject = ['commandPalette']

exports.apply = (ctx) => {
  ctx.inject(['commandPalette'], (scope) => {
    scope.effect(() => scope.commandPalette.registerProvider({
      id: 'my-plugin',
      collect: () => [{
        id: 'open-dashboard',
        group: 'features',
        icon: '⌘',
        title: '打开控制台',
        subtitle: '由扩展插件提供',
        keywords: ['dashboard'],
        run: () => openDashboard()
      }]
    }))
  })
}
```

服务接口：

| 方法 | 说明 |
| --- | --- |
| `registerProvider(provider)` | 注册命令 Provider，返回卸载函数 |
| `collect(context?)` | 收集当前所有扩展命令 |
| `open()` | 打开命令面板 |
| `close()` | 关闭命令面板 |
| `toggle()` | 切换命令面板 |
| `isOpen()` | 返回当前打开状态 |
| `subscribe(listener)` | 监听打开状态或 Provider 变化，接收 `{ open, revision, reason }` 快照 |

Provider ID 必须唯一。命令至少需要 `id`、`title` 和 `run()`；最终命令 ID 会自动加上 Provider 前缀。

动态 Provider 可以额外实现 `subscribe(invalidate)`。当外部状态变化时调用 `invalidate()`，命令面板会重新收集命令；`subscribe` 返回的卸载函数会在 Provider 注销时自动执行：

```js
{
  id: 'dynamic-plugin',
  collect: () => buildCommands(currentState),
  subscribe: (invalidate) => externalStore.subscribe(() => invalidate())
}
```

Desktop 原生浏览器标签、Electron IPC 和原生视图协调不属于本包，后续可以由独立 Desktop 增强插件通过上述接口接入。

## 数据存储

自定义指令通过 DSH 设置系统保存在 `command-palette.commands`，不单独创建数据库或读取模型凭据。

## 兼容性

- 标准版 DeepSeek Harness（DSH）
- `@deepseek-ai/dsh` `0.1.1-rc.2`
- 标准 Web Profile

## 开发验证

```sh
npm test
npm run check
npm pack --dry-run
```

## 许可证

[MIT](LICENSE)

欢迎通过 [Issues](https://github.com/chenyangcun/dsh-command-palette/issues) 反馈问题或建议。