@dsh-community/dsh-command-palette

Readme

# dsh-command-palette

> 给 DeepSeek Harness（DSH）加一个「命令面板」：
> 按一下 `Ctrl+Shift+K`，输入关键词，回车——就能完成各种操作，不用到处找按钮。

如果你用过 VS Code 的 `Ctrl+Shift+P`，就是那个感觉。

---

## 产品目标

DSH 的界面以图形化为主，但日常高频操作（新建/切换会话、切换 workspace、开关视图、执行命令、调用 skill）其实都可以**不碰鼠标**完成。本插件的目标是在保留图形化界面的同时实现「**去光标化**」：

- **纯键盘完成所有日常操作**：会话 / workspace / 视图 / 命令 / skill 的查找与执行都走一个面板，`↑↓` 选择、`Enter` 执行、`Esc` 退出，手不用离开键盘；
- **统一的键盘入口**：无论操作藏在哪个菜单/侧栏/插件里，都收敛到这一个入口，不用记入口在哪、也不用逐层点开；
- **鼠标只是可选**：需要时仍然可以点击面板按钮或列表项，但没有任何日常操作*必须*用鼠标。

命令面板就是这一切的入口：一个快捷键（或按钮）唤起，打字即搜，回车即达。

---

## 安装

### 第一步：确认你已经装好 DSH

- 已经装好 **DSH 0.1.0-rc.6**，并且能正常打开它的 Web 界面（Node.js ≥ 22）。
- 还没装好？先按 DSH 官方文档安装。这一步通常由维护 DSH 环境的人完成，普通使用者可以直接问他们要一个已装好的环境。

### 第二步：安装插件（复制一条命令）

在终端里，复制粘贴下面这一行，按回车：

```sh
dsh plugin --profile web add npm:@dsh-community/dsh-command-palette
```

这一行命令在做什么：

- `dsh plugin` → 让 DSH 管理插件
- `--profile web` → 装到「网页版」配置里
- `add npm:@dsh-community/dsh-command-palette` → 从 npm（一个软件商店）下载并安装本插件

**看到什么算成功：** 屏幕开始滚动一些文字，最后停下来，回到可以输入命令的状态（通常看到 Done 或类似字样）。整个过程一般不超过 1 分钟。

装好后重新打开（或刷新）DSH 网页：按 `Ctrl+Shift+K` 能弹出面板、输入框左侧出现面板按钮，就说明装好了。想逐项完整验收，照着 [docs/manual-inspection.md](./docs/manual-inspection.md) 勾一遍即可（约 30 分钟，不需要编程）。

### 没有发布 npm 包？想先在本机测试？

① 先在插件源码目录（有 `package.json` 的文件夹）打开终端，运行 `npm pack`，会生成一个 `dsh-community-dsh-command-palette-0.1.0-alpha.0.tgz` 文件；

② 然后用这条命令安装（把路径换成你的文件位置）：

```powershell
dsh plugin --profile web add "$PWD\dsh-community-dsh-command-palette-0.1.0-alpha.0.tgz"
```

（在插件源码目录里运行时，`$PWD` 会自动替换成当前目录路径；升级包时先删掉旧的 `.tgz` 再重新打包。）

> ⚠️ 如果粘贴后报 `ENOENT: no such file or directory`，且报错里的路径把 profile 目录和你的文件路径拼在了一起，说明从聊天软件/网页复制命令时混入了不可见字符。把命令**手动敲一遍**（或先粘到记事本再复制）即可解决。

### 卸载

在终端里复制粘贴这一行，按回车：

```sh
dsh plugin --profile web remove @dsh-community/dsh-command-palette
```

卸载后，按钮、快捷键和面板里的命令会自动消失，不留残留。

---

## 它能帮我做什么？

- **一个入口找所有操作**：新建会话、切换会话、切换 workspace、打开详情面板……不用记入口在哪。
- **只显示现在能用的命令**：用不了的命令会变灰，并直接告诉你为什么（例如「需要两个以上会话」）。
- **插件的命令也会自动出现**：其他 DSH 插件注册的命令，面板会自动收录，统一管理。
- **键盘全程可操作**：`↑` `↓` 选择，`Enter` 执行，`Esc` 关闭，手不用离开键盘。
- **执行结果看得见**：成功了有提示，失败了告诉你原因、可以一键重试，长时间任务可以取消。

## 怎么打开？

有三种方式，任选其一：

| 方式 | 说明 |
| --- | --- |
| 快捷键 | `Ctrl+Shift+K`，再按一次关闭（可在设置中修改） |
| 按钮 | 输入框左侧有一个命令面板按钮，点它（手机上用这个） |
| 设置里改了快捷键 | 以你自己的设置为准，见下文「设置」 |

> 💡 光标即使在输入框里，`Ctrl+Shift+K` 也能直接打开/关闭面板；普通打字（如直接敲字母）绝不会被抢占。

## 打开之后怎么用？

```text
┌──────────────────────────────────────┐
│ > 输入关键词搜索命令                  │
├──────────────────────────────────────┤
│  Recent（最近用过）                   │
│    新建会话                           │
│  Session                              │
│    下一个会话                         │
│    打开详情面板        （灰色=不可用） │
└──────────────────────────────────────┘
```

| 按键 | 作用 |
| --- | --- |
| `↑` / `↓` | 上下选择 |
| `Enter` | 执行选中的命令 |
| `Esc` | 关闭面板 |
| 直接打字 | 搜索命令（名称、关键词、分类都能搜，中文英文都行） |

什么都不输入时，列表会按分类分组，**最近用过的命令排在最上面**。

## 自带哪些命令？

| 命令 | 作用 | 什么时候是灰色的 |
| --- | --- | --- |
| 新建会话 | 连接最近的 workspace 并开一个新会话 | 没有可用 workspace 时 |
| 下一个会话 | 在会话列表里循环切换 | 只有不到两个会话时 |
| 下一个 workspace | 切换到下一个 workspace | 没有可用 workspace 时 |
| 打开详情面板 | 展开当前会话的详情侧栏 | — |
| 设置 | 打开 DSH 设置面板 | — |
| 聚焦输入框 | 把光标移到聊天输入框 | 没有活动会话时 |

### 主机命令与 Skills

DSH 中注册的斜杠命令（slash 命令）和当前会话项目里**用户可调用**的 skill 会直接列在面板里（分类「Commands」/「Skills」），选中回车即可执行，不用手动敲 `/`：

- **不带参数的命令**：选中 → 回车直接执行；
- **带参数的命令**（宿主声明了 input hint）与**任意 skill**：选中 → 回车进入「参数输入步」——输入框变为参数输入，回车以 `/名字 参数` 执行，`Esc` 返回命令列表。

另外，**其他插件注册的命令会自动出现在面板里**，不需要任何设置。

> 已知限制：由 Web 界面客户端注册的弹窗选择式命令（如 `/model`、`/mcp`）没有公开的列举 API，暂不会出现在面板里；这类命令仍可从输入框直接输入使用。

## 设置（可选）

配置保存在 DSH 的设置文件 **`~/.dsh/settings.yaml`** 中（也可在 DSH 设置界面找到 **command-palette** 一节）。直接编辑文件，加一段：

```yaml
command-palette:
  shortcut:
    open: ctrl+shift+k   # 打开面板的快捷键
    enabled: true            # 全局快捷键总开关；关掉后仍能用按钮打开面板
```

保存后**立即生效**，不用重启。两个选项：

| 设置项 | 默认值 | 说明 |
| --- | --- | --- |
| `shortcut.open` | `ctrl+shift+k` | 打开面板的快捷键。写法：`修饰键+键位`，如 `ctrl+shift+p`、`alt+k`。`mod` 表示 Windows/Linux 上的 `Ctrl`、macOS 上的 `Cmd`。默认值的选择理由：避开浏览器自带的 `Ctrl+K` 搜索键，也避开被输入法在系统层截获的 `Ctrl+Space` / `Ctrl+Shift+Space`（文本框聚焦时页面根本收不到这两组键，配了也无效） |
| `shortcut.enabled` | `true` | 全局快捷键总开关。关掉后仍能用按钮打开面板 |

- 填了不合法的快捷键会被拒绝并提示原因，原来的设置不受影响。
- 如果新快捷键和浏览器/面板自带按键冲突（比如 `Ctrl+K`、`Ctrl+Tab`），面板会给出提示。

## 常见问题

**Q：命令是灰的，点不了？**
A：灰色的命令旁边写了原因（例如「需要两个以上会话」）。满足条件后它就会恢复可用。

**Q：按快捷键没反应？**
A：两种可能：① 快捷键被浏览器或其他插件占用；② 配置了被输入法截获的组合（`Ctrl+Space`、`Ctrl+Shift+Space` 在文本框聚焦时会被输入法在系统层截获，页面根本收不到事件，这不是插件能修复的）。去 `~/.dsh/settings.yaml` 把 `shortcut.open` 换成别的组合（如默认的 `ctrl+shift+k`），或者用输入框左侧的按钮。

**Q：执行失败了怎么办？**
A：面板不会关，会显示失败原因和一个「重试」按钮，点重试即可。

**Q：命令跑很久？**
A：长时间任务会显示「正在运行」，不会卡住界面；不想等了可以点「取消」，命令会被真正取消（不是假装关掉）。

**Q：手机上能用吗？**
A：可以。屏幕较窄时面板会变成底部抽屉样式，按钮也会加大，方便手指点按。

**Q：它会把命令列表发给 AI 模型吗？**
A：不会。命令面板只为人服务，不占用模型的上下文额度，也不会把命令伪装成模型工具。

---

## 深入阅读

- 📖 设计与开发文档：[PROJECT_GUIDE.md](./PROJECT_GUIDE.md)
- 🔌 给自己的插件贡献命令：[docs/contributing-commands.md](./docs/contributing-commands.md)
- ✅ 人工检查手册（装机后逐项验收）：[docs/manual-inspection.md](./docs/manual-inspection.md)
- 🛠 开发者：`npm install` → `npm test` / `npm run typecheck` / `npm run build`

## 许可证

MIT