@dsh-plugin/hotkeys

Readme

# dsh-hotkeys

[![CI](https://github.com/csiroqa/dsh-hotkeys/actions/workflows/ci.yml/badge.svg)](https://github.com/csiroqa/dsh-hotkeys/actions/workflows/ci.yml)

DeepSeek Harness（DSH）的**全局快捷键**插件：会话切换、发送/清空草稿、停止生成、复制与归档会话——动作全部基于 `dsh-client-runtime` 公开服务，不依赖宿主 DOM 结构。

English: [README.en.md](README.en.md)

## 功能

### 会话导航

- **会话切换**：按侧栏顺序环绕切换（按住可连续切换）
- **新会话**：与侧栏"新建会话"同一入口，快速开始新对话

### 草稿与发送

- **发送草稿**：`send` 等价 composer 加速 Enter（草稿为空且有排队消息时把排队消息推入运行中的回合），发送/受理进行中自动拦截
- **清空草稿**：只清文本、保留已附加图片

### 会话管理

- **停止生成**：停止当前会话运行中的回合（与 composer 一致：仅普通会话与 continuable 子代理可打断）；未运行给出页面内提示
- **复制会话**：fork 当前会话（标题递增）并跳转到新会话
- **归档会话**：原生 `workspaces.archiveSession`（当前会话移入"已归档"）

### 快捷键清单

- `/hotkeys` 命令：在会话中列出全部 8 个动作的当前生效键位（含用户自定义覆盖）

### 守卫

- IME 组合输入中、AltGr 键击、已被消费（defaultPrevented）的按键不触发；纯按键组合（无 Ctrl/Cmd/Alt）在输入框/文本域内不触发（`ignoreInputs`）；按住不放只放行导航类动作；非法/重复键位在控制台 `warn` 并指明动作名

## 配置

键位、`sendMode`、`ignoreInputs` 经 **settings 命名空间**持久化配置（host 半区注册 schema，浏览器半区 `settingsScope` 同步，值变化即时重建绑定，无需重启）。两种方式：

1. **设置 > 通用 > 快捷键**：可视化编辑全部键位（**一个动作支持多个键位**，逗号分隔，如 `mod+enter, ctrl+shift+enter`；输入空串禁用该动作、重置回默认）、`sendMode` 下拉、`ignoreInputs` 开关
2. 编辑 `$DSH_HOME/settings.yaml` 的 `hotkeys:` 段（键位字段同样支持数组）：

```yaml
hotkeys:
  newSession: 'mod+alt+n'
  prevSession: 'mod+alt+['
  nextSession: 'mod+alt+]'
  stop: 'mod+.'
  send: 'mod+enter'
  clearComposer: 'mod+shift+u'
  fork: 'mod+shift+f'
  archive: 'mod+alt+a'
  sendMode: 'auto'
  ignoreInputs: true
```

内置默认键位（即上表；值为空字符串 `''` 禁用该动作）：

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `newSession` | `mod+alt+n` | 新会话（与侧栏"新建会话"同一入口；`mod+n` 是浏览器保留快捷键无法拦截） |
| `prevSession` / `nextSession` | `mod+alt+[` / `mod+alt+]` | 上一个 / 下一个会话（`mod+shift+[ ]` 在 macOS 上是浏览器标签切换） |
| `stop` | `mod+.` | 停止当前会话运行中的回合 |
| `send` | `mod+enter` | 发送当前草稿（等价 composer 加速 Enter 语义） |
| `sendMode` | `auto` | 忙碌时的提交模式：`auto`（与 composer 加速 Enter 完全一致，见下）/ `queue` / `steer` |
| `clearComposer` | `mod+shift+u` | 清空草稿文本（避开 Firefox 的 `mod+shift+k`） |
| `fork` | `mod+shift+f` | 复制当前会话 |
| `archive` | `mod+alt+a` | 归档当前会话（原生 `workspaces.archiveSession`；避开 Chrome 的 `mod+shift+a` 搜索标签页） |
| `ignoreInputs` | `true` | 纯按键组合在输入框/文本域内不触发 |

键位写法：修饰键（`mod`/`ctrl`/`alt`/`shift`，可任意组合）+ 单键或具名键（`enter`/`esc`/`up`/`pageup`/`f5`/…）。`mod` 在 Windows/Linux 上为 Ctrl，macOS 上为 ⌘。默认键位已避开浏览器保留快捷键。

注意：`cordis.patch.yml` 的 insert `config` 段不达浏览器半区（patch config 只到 host），键位配置请写 `settings.yaml`。

## 安装

前置：Node.js >= 22、pnpm、本机 `deepseek-harness` 源码检出（依赖以 `link:` 指向 `../deepseek-harness`）。

```sh
git clone https://github.com/csiroqa/dsh-hotkeys.git
cd dsh-hotkeys
pnpm install
pnpm build

# 安装进 web profile（link: 指向本目录）
dsh plugin --profile web add link:$(pwd)        # POSIX
dsh plugin --profile web add link:D:\path\to\dsh-hotkeys   # Windows
```

重启 `dsh web`，浏览器 **Ctrl+F5** 硬刷新。

## 使用

1. 打开任意会话，`Ctrl+Alt+[` / `Ctrl+Alt+]` 切换会话；`Ctrl+Alt+N` 新建会话
2. 输入草稿后 `Ctrl+Enter` 发送；`Ctrl+.` 停止生成；`Ctrl+Shift+F` 复制会话
3. `Ctrl+Alt+A` 归档当前会话（移入侧栏"已归档"）
4. 输入 `/hotkeys` 查看当前生效的全部快捷键
5. 配置错误的键位会在浏览器控制台打印 `[hotkeys]` 警告

## 兼容性

- **平台**：Windows / macOS / Linux（Node >= 22）—— 三平台构建与冒烟测试经 [GitHub Actions CI](https://github.com/csiroqa/dsh-hotkeys/actions) 验证
- 针对 DSH `0.1.1-rc.2` 源码检出开发验证，并在 `@deepseek-ai/dsh@0.1.1-rc.2`（npm 全局/npx 安装）环境实测可用；依赖 `sessions` / `workspaces` 两个公开服务（bundle 声明 `inject`）与一处 untyped 的 `conversation.input` 运行时面（ui-conversation 缺席时相关动作静默降级）
- 键位按 **US 键盘布局**假设（shift 上档字符还原）；`mod` 平台判定优先 `userAgentData.platform`，回退 `navigator.platform`
- **已知限制**：slash 菜单打开时的拾取仲裁由 composer 私有持有，`send` 直接提交草稿而非拾取高亮项；`sendMode: 'auto'` 与 composer 加速 Enter **完全一致**（读取 `ui-conversation` 命名空间的 `busyEnter` 偏好并按取反语义解析）
- 构建产物：`tsdown`（host 半区 `lib/index.js` + browser 半区 `lib/client.js`，标准 `window.__ModuleLoader__.load` 闭包工厂格式）

## 安全说明

- **快捷键只在本机页面上生效**（DSH 默认回环绑定），不涉及任何网络监听
- **键位配置写入 `$DSH_HOME/settings.yaml`**（本机文件），请勿把 DSH 端口暴露到公网
- 插件以 `link:` 指向本仓库目录安装，改动源码后重新构建（`pnpm build`）并硬刷新即可生效

## 许可与使用声明

**MIT License**（见 [LICENSE](LICENSE)）。

欢迎任何人**使用、修改、引用、或把本项目收录进自己的插件合集**，只需：

- 保留 `LICENSE` 文件与版权声明
- 标明出处（本仓库链接）

## 相关

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
- 同系列插件：[dsh-schedule](https://github.com/csiroqa/dsh-schedule)（定时任务 + 状态监控）
- 插件形态参考 [dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)（`dsh.bundle.patch` + `dsh.client` 声明 + 槽位注册 + tsdown 双半区构建）