DSH Commands Plugin（通用斜杠命令加载器）

让 DeepSeek Harness (DSH) 拥有 opencode 风格的自定义斜杠命令。 项目 .agents/commands/*.md（或 .dsh/commands/*.md）中的每个 Markdown 文件 都会注册为一条 / 斜杠命令：命令正文作为用户消息提交给 AI。

工作方式

输入 /opsx-explore 我的想法 时：

1. 插件读取 .agents/commands/opsx-explore.md 的正文
2. 正文含 $ARGUMENTS → 原位替换为参数；否则参数以空行拼接到正文末尾
3. 用官方工厂 createUserMessage()（@deepseek-ai/dsh-llm）构造消息并 agent.steer() 提交给当前会话的 AI（与 DSH 内置 /plan 同机制）
4. 命令行与执行结果不进入模型历史

命令目录与优先级

| 优先级 | 目录 | |---|---| | 高 | <项目根>/.dsh/commands/*.md | | 低 | <项目根>/.agents/commands/*.md |

• 项目根 = 最近含 .git 的祖先目录（无则用 cwd）
• 同名命令：高优先级目录覆盖低优先级
• 文件名（去 .md）即命令名，必须匹配 ^[a-z][a-z0-9_-]*$（首字符必须小写字母， DSH 不支持冒号，opencode 的 /opsx:explore 对应 /opsx-explore）
• 非法文件名或不可读文件跳过并 warn，不影响其他命令

frontmatter（可选）

---
description: 命令描述（缺省用文件名）
argument-hint: "[想法]"      # 可选，UI 输入框占位提示
---

命令正文……$ARGUMENTS……

只解析单行 key: value；其余字段忽略；无 frontmatter 或未闭合均合法（视为纯正文）。

安装

本插件通过 npm 发布，可安装到任意 DSH 项目中。推荐用 DSH 自带的插件命令安装。

Node ≥22.19（DSH developer preview 要求）。

方式一：DSH 插件命令（推荐）

dsh plugin 会把参数转发给指定 profile 目录下的 pnpm，把装进该 profile 并自动加入 dsh.profile.bundles。本插件以 DSH bundle 形式分发（package.json 声明 dsh.bundle.patch），安装后无需手动注册，直接启动即可：

# 安装到 web profile
dsh plugin --profile web add dsh-plugin-commands@latest

# 启动
dsh web     # 等价于 dsh --profile web

启动后，在 Web UI 对话框输入 / 即可看到插件从命令目录加载出的全部斜杠命令。

如何给命令补充参数

DSH 的 UI 交互：输入 /命令名 后按空格（不是回车、也不是从菜单点选）， 命令名会保留在输入框，此时可以继续补充参数文字，输入完按回车提交：

/opsx-explore 我想探索多模态支持      ← 按空格后在这里补文字

• 从 / 菜单点选命令会立即执行，无法补参数
• 直接输入 /命令名 后按回车则不带参数执行
• 命令正文里的 $ARGUMENTS 会被替换为你输入的文字；无占位符时参数拼在正文末尾

坑点：dsh plugin add 需写 ~/.dsh（凭证目录）。在终端沙箱（TRAE/EDR 等）里会报 EPERM ... pnpm-lock.yaml。请在普通 Terminal 运行；或临时 HOME=$PWD/.fake-home dsh plugin --profile web add ...（假宿主目录，需重新登录 DSH）。 若升级过插件版本，用 dsh plugin --profile web up dsh-plugin-commands 更新到含 dsh.bundle 的最新版。

方式二：npm 手动安装

# npm / pnpm / bun 均可
npm install dsh-plugin-commands
# 或
pnpm add dsh-plugin-commands
# 或
bun add dsh-plugin-commands

然后在项目根的 cordis.yml 中注册，name 指向安装后的构建产物：

- insert:
    - id: dsh-plugin-commands
      name: '<你的项目根>/node_modules/dsh-plugin-commands/dist/index.js'

启动：

dsh web --patch ./cordis.yml

两种方式对比

| | 方式一 dsh plugin add | 方式二 npm install | |---|---|---| | 安装范围 | 装进 DSH profile | 装进当前项目 | | 是否需手动注册 | ❌ 不需要（bundle 自动注册） | ✅ 需在项目 cordis.yml 手写 name | | 启动命令 | dsh web | dsh web --patch ./cordis.yml | | 适用 | 个人全局使用、多项目共享 | 锁定在某个项目里 | | 换机/换目录 | 无路径问题（包名解析） | 需改 cordis.yml 里的绝对路径 |

一句话：个人日常用方式一（零配置）；项目内固定用方式二（显式声明）。

放置命令文件

插件扫描项目根（最近含 .git 的祖先目录）下的两个目录：

| 优先级 | 目录 | |---|---| | 高 | <项目根>/.dsh/commands/*.md | | 低 | <项目根>/.agents/commands/*.md |

每个 Markdown 文件就是一条命令，例如新建 .dsh/commands/hello.md：

---
description: 打个招呼
argument-hint: "[名字]"
---

向用户打个友好的招呼。如果提供了名字，用 $ARGUMENTS 里的名字称呼对方。

重启 DSH 后即可用 /hello 触发。

本地开发加载（源码方式）

bun install
bun run build                    # 产出 dist/index.js
dsh web --patch ./cordis.yml     # 在普通终端运行，见下方坑点

• cordis.yml 的 name 必须指向构建产物 dist/index.js 的绝对路径； 换机器/目录需同步修改。不能直接指向 TS 源码（Node ESM 不支持源码中 无扩展名的相对导入；bundle 已打平）
• 若启动报 EPERM ... ~/.dsh/profiles/web/cordis.yml：是终端沙箱 （如 TRAE/EDR）拦截 node 子进程写 ~/.dsh。在普通 Terminal 启动即可； 或临时 HOME=$PWD/.fake-home dsh web --patch ./cordis.yml

开发

bun run test        # bun:test 单元测试
bun run typecheck   # tsc --noEmit
bun run build       # bun build → dist/

依赖：运行时仅 @deepseek-ai/dsh-llm 的 createUserMessage（构建 --external，由项目 node_modules 解析）；cordis / dsh-commands 仅类型。

已知限制

• 命令启动时一次性加载，无热重载（改 md 后需重启 DSH）
• 不支持用户级 ~/.agents/commands/ 全局命令
• 不支持 opencode 的高级模板（$1 位置参数、agent/model frontmatter 字段）

License

MIT