@dsh-external/dsh-command-opt

Readme

# dsh-command-opt

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

DeepSeek Harness（DSH）的**命令优化**插件：Tab/Enter 补全命令名、参数格式引导与提示弹框、tool 开启会话（subagent）补丁、空对话命令输出修复。

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

## 功能

- **Tab/Enter 补全**：composer 中键入 `/前缀` 后按 Tab（或菜单高亮时按 Enter），按当前会话命令目录补全——草稿任意位置可用；前缀优先、无前缀命中回退菜单同款模糊打分，最近使用过的命令置顶；多匹配先补最长公共前缀，再按 Tab 轮转候选；菜单 ↑↓ 高亮优先，Tab 与 Enter 都补全为选中的命令
- **参数格式引导**：行首补全到带参数位的命令时直接进入 claim，参数格式（input hint）幽灵文本与输入对齐；claim 阶段按 Tab 轮转参数选项（hint 的 `|` 枚举，如 `/plan off|message`）
- **命令提示弹框**：`conversation.input.overlay` 槽位、与内置菜单同锚点同风格——输入命令参数时始终显示弹框并固定在对应命令下，高亮当前待填参数（多参数命令如 `/schedule` 输入参数后提示不再消失）；内置菜单未展示时兜底显示候选（命令后跟参数而非说明）
- **tool 开启的会话（subagent）补丁**：内置命令目录对 subagent 返回空，导致此类对话"没有选项"、无法执行 `/archive` 等操作——本插件目录直连宿主，提示弹框照常显示命令选项；回车时完整命令直接执行；会话头部注册"操作"菜单（归档 / 复制会话 / 定位父会话）
- **空对话命令输出修复**：空会话中执行 `/命令` 后输出正常渲染、头部选项按钮出现、不再被"新对话"复用扫描当作空会话合并
- **目录缓存**：键入 `/` 即预热、`commands/change` 与 `agent-preset/selected` 事件主动失效、TTL 兜底、同会话并发去重、会话删除时剪枝

## 配置

安装后，`cordis.patch.yml` 的 `command-opt` insert 行支持以下可选 config（注意：dsh 固有逻辑——浏览器半区收不到 patch config，默认值内置在代码里，修改 config 不会改变浏览器行为）：

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `tabComplete` | `true` | Tab/Enter 补全命令名 |
| `hintPopup` | `true` | 命令提示弹框（conversation.input.overlay） |
| `subagentPatch` | `true` | tool 开启的会话（subagent）补丁 |
| `blankEngage` | `true` | 空对话命令输出修复 |
| `catalogTtlMs` | `15000` | 命令目录缓存 TTL（毫秒） |

## 安装

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

```sh
git clone https://github.com/csiroqa/dsh-command-opt.git
cd dsh-command-opt
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-command-opt   # Windows
```

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

## 使用

1. 输入 `/` + 前缀，按 Tab 补全命令名（多候选先补公共前缀，再按 Tab 轮转；↑↓ 选中后 Tab/Enter 补全选中项）
2. 行首补全到带参数位的命令（如 `/schedule`）后直接进入参数位：幽灵提示显示参数格式，Tab 轮转 `|` 枚举选项，输入参数全程提示弹框常驻
3. 在 tool 开启的会话中：回车直接执行 `/archive` 等命令，头部"操作"菜单提供归档 / 复制会话 / 定位父会话
4. 空会话里执行命令后：输出正常渲染、选项按钮出现、不会被下一次"新建对话"复用

## 兼容性

- **平台**：Windows / macOS / Linux（Node >= 22）——三平台构建与冒烟测试经 [GitHub Actions CI](https://github.com/csiroqa/dsh-command-opt/actions) 验证
- 针对 DSH `0.1.1-rc.2` 源码检出开发验证；依赖 `dsh-client-runtime` 的公开面，少量内部面（会话激活的 `handleBlank`/`promptAttempted`、列表摘要的 `recordMutation`）以运行时特性检测保护，缺失时静默降级
- **已知限制**：空对话激活是浏览器侧行为，宿主 summary 仍报 blank，刷新页面后该会话会从列表消失（直到有真实 turn）；浏览器半区收不到 patch config，默认值内置在代码
- 构建产物：`tsdown`（host 半区 `lib/index.js` + browser 半区 `lib/client.js`，标准 `window.__ModuleLoader__.load` 闭包工厂格式）

## 安全说明

- 插件只在本机页面上生效，不涉及网络监听
- 插件代码以 `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-hotkeys](https://github.com/csiroqa/dsh-hotkeys)（全局快捷键）、[dsh-plugin-usage-report](https://github.com/csiroqa/dsh-plugin-usage-report)（用量统计）