DSH plugin 用户命令:定义、调用结果与发现解析视图到底该怎么对齐、怎么验证才不乱
命令是最容易被误当成“特殊工具”的能力:它不进模型、不产生工具结果,也不被轮次包裹。 DSH plugin 的用户命令注册表服务把发现、解析与执行串成一条独立通道。理解这条通道,才能解释“注册了却看不见”和“执行了却没痕迹”。 DSH插件 的命令不进模型、不产生工具结果,也不被轮次包裹。
命令不走模型,走注册表
执行直接针对确切的 agent,不创建模型消息。(来源)
dsh-commands 提供的用户命令注册表服务,供交互式适配器发现插件拥有的命令,并针对确切的 agent 直接执行这些命令,而不创建模型消息。
分层规则与技能类似:普通上下文的定义是全局的;通过 agent 上下文的命令注入子级注册的定义,会为该 agent 遮蔽全局定义。所以“同一个命令在不同 agent 下表现不同”可以是设计,而不是冲突。
定义:字段少但各有边界
recordInput 决定要不要把原始输入再写一遍。(来源)
CommandDefinition 包含:
- 可选
definitionId— 稳定的插件自有身份;没有基于身份的客户端行为时可省略; name— 小写命令名,不含前导斜杠;description— 用于发现 UI 的人类可读摘要;- 可选
input— 非结构化输入描述符,含hint与attachments标志; - 可选
recordInput— 是否让command/run记录rawInput,默认true;若领域事件已经拥有该载荷,设为false可避免在会话日志里重复; handler— 针对接收 agent 执行,不把命令发给模型。
注册表会验证并冻结一份与原始注册对象脱离的生效定义。所以你在注册之后修改原对象,不会影响已生效的定义。
还有一个注册入口容易被忽略:registerFileReceiptResolver(resolver) 注册唯一的暂存文件回执解析权威,返回移除该解析器的 disposer。命令想接收暂存文件时,这条解析链必须存在,否则附件准入会以缺少存储失败。
附件准入在 execute 里强制
组合器只是提前拦一道,真正的判定在服务里。(来源)
input.attachments 为真时,handler 会收到已准入的持久块,并拥有后续所有语法决策,包括拒绝那些用不上附件的子命令。省略或为假时,执行器会拒绝携带附件的调用,能干的组合器也会在派发前拒绝提交。
三类失败都在 handler 运行前以错误结果结算:向未声明 input.attachments 的命令发送附件、缺少附件存储、超过图片上限。验证拒绝不会启动任何附件写入;而存储失败可能只留下无法访问的内容寻址对象,等待延迟回收。
这条顺序很重要:先准入、再执行。handler 不会看到半截附件状态。
调用与结果:直接给 UI
rawInput 保留分隔符与后缀,不做二次解析。(来源)
CommandInvocation 有五个字段:commandId(已写入本次 command/run 的配对 id)、agent(收到命令的确切 agent)、rawInput(紧接注册名之后的完整文本,含分隔空白)、attachments 与 signal。
取消由适配器负责,适配器会传入确切的目标 agent。结果会直接呈现给 UI,而不是工具结果或会话事件。
CommandResult 只有两种:success(可选 text 与可选 sourceEventSeq)与 error(必填 text)。
sourceEventSeq 是可选字段,且只用于成功结果。存在时,它指向接收会话日志中更早的一条非命令事件;command/done 会持久化同一引用,让客户端把命令生命周期与该领域投影合并,而无须解析 text 或依赖相邻行。
这条设计解决了一个实际痛点:命令的结果可能是一段渲染,也可能是“请看那条事件”。后者用引用表达,比复制文本稳。
生命周期日志:run 前 done 后
两条事件直接追加,没有轮次包裹,但顺序仍是承诺。(来源)
execute 解析并执行已知命令而不发给模型。一个已解析命令的生命周期会被记录:command/run 在 handler 被调用之前追加,command/done 在结算之后追加——抛出或中止的 handler 以 kind: 'error' 结算。
两者都是直接的仅日志追加,没有轮次包裹它们,持久化会在普通检查点排空。准入失败(语法错误或未知名称)什么都不记录,因为它们从未进入 handler。
两个失败语义要分清:command/run 追加失败会让执行显式失败;而在 handler 失败路径上,command/done 的追加失败会被兜住,以便 handler 自身的错误保持为被报告的失败。
发现与解析视图
parseCommand 只判语法,find 才判可用性。(来源)
作用域解析后,适配器会获得不含处理器的不可变描述符 CommandDescriptor。list(agent) 返回按名称排序、经过作用域遮蔽的描述符;find(agent, name) 返回遮蔽后的定义或全局定义。
parseCommand() 在注册表解析前返回 ParsedCommand(只有 name 与 rawInput),所以语法有效的输入仍可能指向不可用的命令。补全列表与执行可用性因此不是同一份数据。
commands/change 是不带过滤的注册表通知:全局或作用域变更可能影响任何 UI 视图,所以不做过滤;观察者失败会被兜住,不能否决这次变更。
验证:一条带参数的命令
验证要覆盖注册、可见性、附件准入与日志顺序。(来源) 六步:
- 注册一条
name: "deploy"的命令,断言list(agent)里有它且描述正确。 - 在某个 agent 的上下文注册同名命令,断言该 agent 看到遮蔽版本,其他 agent 仍看全局。
- 调
execute传完整行deploy prod --fast,断言rawInput保留prod --fast的分隔空白。 - 向未声明
input.attachments的命令传一张图片,断言 handler 未运行且结果是 error。 - 断言日志里先出现
command/run、后出现command/done,且没有 turn 包裹。 - 用一个不存在的命令名调
execute,断言返回undefined且日志没有新增事件。
如果第 4 步 handler 仍被调用,说明附件准入被放到了 handler 里,那会让“先准入再执行”的保证失效。
命令的注册与提示词衔接,可以对照用户命令注册;命令与审批的关系见审批策略。
一句话收束: 命令不进模型、recordInput 只控制日志重复、附件先准入再执行、结果直接给 UI、run/done 无轮次但有序、语法有效不等于可执行。
常见问题
不会,DSH plugin 的命令直接针对确切的 agent 执行。DSH plugin 的交互适配器用它发现插件拥有的命令并执行,不创建模型消息。
只有声明了 input.attachments 的命令可以。DSH plugin 在 execute 里强制准入:未声明却带附件、缺少附件存储或超过图片上限,都会在 handler 运行前以错误结果结算。
不一定,DSH plugin 的 parseCommand 只判断语法。DSH plugin 让语法有效的输入仍可能指向不可用的命令,注册表解析之后才知道能否执行。
不会,DSH plugin 的结果直接呈现给 UI。DSH plugin 只把 command/run 与 command/done 两条生命周期事件写入日志,而且没有轮次包裹它们。
相关术语
- CommandDefinition
- CommandDefinition 是插件编写的命令注册定义,含可选身份、名称、描述、输入描述、recordInput 与 handler。— packages/interaction/commands/src/index.ts
- CommandInvocation
- CommandInvocation 是传给 handler 的调用信息,含 commandId、agent、rawInput、附件与取消信号。— packages/interaction/commands/src/index.ts
- CommandResult
- CommandResult 是直接由派发 UI 渲染的结果,只有 success 与 error 两种形态。— packages/interaction/commands/src/index.ts
- ParsedCommand
- ParsedCommand 是注册表解析前的语法有效斜杠命令,只有 name 与 rawInput 两项。— packages/interaction/commands/src/index.ts
来源
- DeepSeek Harness 官方参考 - 用户命令· deepseek-ai
- packages/interaction/commands/src/index.ts· deepseek-ai