DSH plugin 用户命令怎么注册？DeepSeek Harness 的 CommandDefinition 规范

DSH plugin 想给用户加一条斜杠命令，走的是与工具完全不同的注册表：dsh-commands 提供的用户命令服务让交互式适配器发现插件拥有的命令，并针对确切的 agent 直接执行，而不创建任何模型消息**（来源）。** 本文面向 DSH插件 / DeepSeek插件 作者，讲清 CommandDefinition 的字段规范、仅日志的命令生命周期、作用域阴影与 ctx.commands 的 API；事件分发五模式见 DSH plugin 事件系统，工具的注册与契约见 工具 execute 契约。

DSH plugin 的 CommandDefinition：注册用户命令要填什么

CommandDefinition 是由插件编写的注册定义，注册表会校验并冻结一份与原始注册对象脱离的生效定义（来源）。 字段规范如下：

1. name — 小写命令名，不含前导斜杠。/plan 注册时写 plan。
2. description — 供发现 UI 使用的人类可读摘要。
3. input（可选） — 一个 CommandInputDescriptor，目前只有 hint：在用户提供自由输入前显示的占位说明，向有能力的客户端公布。命令的可用性由插件组合决定——每个消费注册表的适配器都会看到全部生效定义。
4. recordInput（可选，默认 true） — 是否让 command/run 记录 rawInput。当命令的领域事件已经拥有该 payload 时，把它设为 false，避免在会话日志里重复记录同一份 payload。
5. handler — (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>，针对接收 agent 直接执行，不把命令发给模型。

DSH plugin 用户命令的调用与结果：不经模型的直接执行

取消由适配器负责，适配器会传入确切的目标 agent；结果直接呈现给 UI，而不是工具结果或会话事件（来源）。 handler 收到的 CommandInvocation 有四个字段：

1. commandId — 已经写入本次调用 command/run 事件的配对 id。
2. agent — 其 UI 收到该命令的确切 agent。
3. rawInput — 紧跟注册命令名之后的原始文本，保留适配器传入的分隔符与后缀空白。
4. signal — 由分发 UI 请求持有的取消信号。

返回的 CommandResult 是两个分支之一：{ kind: 'success', text?, sourceEventSeq? } 或 { kind: 'error', text }。其中 sourceEventSeq 是可选字段，且只用于成功结果：存在时它指向接收会话日志中更早的一条非命令事件，command/done 会持久化同一引用，让客户端能把命令生命周期与该领域投影合并，而无须解析 text 或依赖相邻行。

DSH plugin 用户命令的发现、作用域与生命周期日志

作用是分层的，生命周期是仅日志的（来源）。

1. 作用域与阴影 — 普通 context 上的定义是全局的；通过注入了 commands 的 agent context 子作用域注册的定义，会针对该 agent 阴影全局定义。ctx.commands.register(definition) 返回精确的 effect disposer；ctx.commands.list(agent) 返回按名字排序、经作用域阴影后的不可变 CommandDescriptor（不含 handler）；ctx.commands.find(agent, name) 返回阴影或全局定义。
2. 仅日志的生命周期 — ctx.commands.execute(agent, line, signal) 解析并执行已知命令：command/run 在 handler 调用前追加，command/done 在结算后追加（抛异常或中止的 handler 结算为 kind: 'error'）。两者都是直接的仅日志追加，没有轮次包裹它们，持久化在普通检查点排空。
3. 准入与失败语义 — 准入未命中（语法错误或未知命令名）不记录任何东西，因为从未进入 handler；command/run 追加失败会让执行大声失败；handler 失败路径上的 command/done 追加失败被包含，让 handler 自身的错误保持为上报失败。
4. 解析视图 — parseCommand() 在注册表解析前返回 ParsedCommand，因此语法有效的输入仍可能指向一个当前不可用的命令。
5. 注册表变更通知 — commands/change 是未过滤的注册表通知（全局或作用域变更可能影响任意 UI 视图），观察者失败被包含，不能否决注册表变更。

写完自检三项：name 是否小写且没有前导斜杠；领域事件已经承载 payload 时 recordInput 是否设成了 false；handler 是否直接返回 CommandResult 而没有试图把命令塞进模型轮次。想找命令类插件的社区实现，你可以在 DSH Plugin Hub 检索；命令与工具的分工判据见 功能→机制映射。