自定义命令与用户交互
除了工具(模型自己调),DSH 还支持两类"人的触达":斜杠命令(用户在界面里敲 /xxx)和向用户提问(模型卡住时问人)。
1. 自定义命令(ctx.commands)
@deepseek-ai/dsh-commands 是插件拥有的人类命令注册表,由交互式 UI 适配器消费。插件注册一个命令,用户在 Web UI 敲 /命令名 触发。
import { Context } from '@deepseek-ai/cordis'
export const name = 'command-demo'
export const inject = ['commands']
export function apply(ctx: Context) {
ctx.commands.register({
name: 'deploy', // 小写命令名
description: '部署当前分支',
input: { hint: '可选的非结构化输入提示' },
recordInput: true, // 默认 true;权威域事件持有时设 false
handler: async ({ agent, rawInput, signal }) => {
// rawInput = 命令名之后的原始文本（包含分隔空白）
signal.throwIfAborted()
return { kind: 'success', text: `已为 ${agent.id} 触发部署：${rawInput.trim()}` }
},
})
}
关键点(源码 README):
parseCommand()识别:第 0 字节是/,小写名字含[a-z0-9_-],后接行尾或空白;名字后所有字节作为rawInput- 同层重名 → 注册失败;
agent.ctx下的注册会遮蔽同名全局命令(按 agent 作用域) - 生命周期以只读的
command/run→command/done事件对记入接收 agent 的会话日志(都是独立 append,不被 turn 包裹) - 结果由适配器直接渲染,不进入模型历史
- 注册/注销会通知
commands/change观察者,让在线适配器刷新
dsh 的 base 已装载这个服务,Web client 也走它;自定义交互组合/ACP 自动化不默认提供命令适配器。
内置斜杠命令
dsh 自带几个全局命令(都经 ctx.commands 注册,人触发、不走模型轮次):
| 命令 | 作用 | 详见 |
|---|---|---|
/goal | 查看 / 创建 / 编辑 / 暂停 / 恢复长期目标 | 目标、作业与待办 |
/plan [消息] | 进入规划协作状态(不切换模型) | Agent 预设与 Persona |
/feedback | 追加一条反馈记录 | 反馈 |
/compact | 手动触发一次上下文压缩 | 上下文系统 |
/permission [preset] | 查看或切换权限预设 | 权限 |
/export | Web 中下载当前会话及后代的日志 ZIP；不接受路径参数 | Web UI 架构 |
/export 只挂在 Web 组合中。提交命令的浏览器在成功回执后请求 GET /api/session.export?sessionId=<id>&includeDescendants=true，由浏览器下载管理器选择保存位置；Header 的 Session log 按钮复用同一控制器。
注册表本身不向模型提交任何东西:命令输入、元数据、直接输出都不进模型请求、不影响 cache;只有命令产出者显式经 Agent 调度的工作才计 token(如 /plan 的可选消息)。
2. 向用户提问(ask_user_question)
@deepseek-ai/dsh-tool-ask-user 让模型在需要确认、选择或缺少信息时,向人问一个简明问题。
ask_user_question
questions 必填,非空数组
id 每题必填的稳定 id(答案里会回显)
question 必填的题目文字
header 可选短标题
options 可选选项,每个 { label, description };推荐项放第一并标 (Recommended)
对应服务 seam 是 ctx.userQuestions(见 内置工具 里的 tool-ask-user)。
# 一个典型提问的 shape
questions:
- id: confirm-deploy
question: 确认把当前分支部署到生产吗?
options:
- { label: 部署(Recommended), description: 会触发生产发布流程 }
- { label: 只预演, description: 干跑,不真正发布 }
命令 vs 工具 vs 提问
| 谁触发 | 典型用途 | |
|---|---|---|
| 工具 | 模型 | 执行操作 |
| 命令 | 用户(敲 /) | 让人主动触发操作 |
| ask_user | 模型 | 模型需要人确认/选/补信息 |
三者互补:命令给人一个"插一脚"的稳定入口,提问让模型在关键处停下来问人。
验证
# 会话日志里看 command 生命周期
zstdcat ~/.dsh/sessions/*/*/session.jsonl.zstd | grep -E '"command/' | head
# 确认命令服务已装载
dsh web --dump-config | grep commands