DeepSeek Harness 用户命令子系统解析

DeepSeek Harness 是 DeepSeek 开源的 agent 框架，主打一切皆插件，底层由 Cordis 驱动。在它的交互层里，除了送给模型的工具调用，还有一类完全不走模型的入口：以斜杠开头的用户命令。官方文档 docs/subsystems/commands.zh.md 描述的正是这套用户命令注册表服务，代码位于 packages/interaction/commands。它的定位一句话就能说清：交互式适配器用它发现插件拥有的命令，并针对确切的 agent 直接执行，而不创建模型消息。

命令是插件资产，注册即冻结

插件通过 CommandDefinition 注册一条命令，字段不多：name 是小写命令名，不带前导斜杠；description 供发现界面展示；可选的 input 提供输入占位提示，展示给支持自由输入的客户端；handler 负责对收到命令的 agent 直接执行。

有两个细节体现了设计的谨慎。其一，注册表会验证并冻结一份与原始注册对象脱离的生效定义，插件之后改动自己手里的对象，不会影响已注册的命令。其二，recordInput 默认为 true，也就是 command/run 事件会记录原始输入；但如果命令对应的领域事件自己持有完整 payload，就应把它设为 false，避免同一份数据在会话日志里重复存两遍。

结果直接给 UI，不进会话流

handler 收到的 CommandInvocation 带四样东西：commandId 是已经写入本次 command/run 事件的配对 id；agent 是确切接收命令的目标；rawInput 是命令名之后的原始文本，保留适配器传入的分隔符、空白与后缀；signal 是由派发 UI 请求持有的取消信号，取消逻辑由适配器负责。

命令的返回值类型刻意做得很小，只有成功与失败两种形态：

type CommandResult =
  | { kind: 'success'; text?: string; sourceEventSeq?: number }
  | { kind: 'error'; text: string }

结果直接呈现给 UI：它不是工具结果，也不是会话事件。成功结果里可选的 sourceEventSeq 是整套设计里最巧的一笔。它指向接收会话日志中更早的一条非命令领域事件，command/done 会持久化同一个引用，客户端因此能把命令生命周期与那条领域投影直接合并，不必解析 text 文本，也不用靠相邻日志行去猜。

两种作用域，描述符与执行分离

ctx.commands 是一个 CommandRuntime 服务，暴露四个方法：register 注册命令并返回精确的注销函数；list 按名称排序返回某个 agent 生效的命令描述符；find 解析单个定义；execute 解析并执行一整行斜杠命令。

作用域分两层。在普通上下文里注册的定义是全局命令，所有消费注册表的适配器都能看到；通过 agent 上下文的 command-injected 子上下文注册的定义只对该 agent 生效，并且遮蔽同名全局命令，遮蔽结果会体现在 list 返回的视图里。

值得注意的是，适配器从 list 拿到的是不含 handler 的不可变描述符，只有名称、描述和输入提示，执行逻辑不会泄漏给发现接口。真正的执行入口 execute 之前还有个更前置的 parseCommand，它在注册表解析之前就返回解析结果：语法有效并不等于命令可用，名字仍可能指向一个不存在的命令。

从 command/run 到 command/done 的完整记账

execute 的执行过程被完整记录：解析成功后先追加 command/run 事件，再调用 handler；handler 落定后追加 command/done，抛错或被中止都落定为 error 形态。两次追加都是直接的日志写入，没有 turn 包裹，持久化在普通检查点将它们排干落盘。

错误处理分了两个方向：command/run 追加失败会让整个执行大声失败；而 handler 已经失败时，command/done 的追加失败会被包含住，保证最终上报的是 handler 本身的错误，不会被日志故障掩盖。至于语法错误或未知命令这类根本没进入 handler 的准入失败，则一行日志都不写，execute 直接返回 undefined。

命令的注册与注销还会发出 commands/change 事件。这是一个无过滤的注册表通知，因为全局或 scoped 的变化可能影响任何界面视图；观察者的失败会被包含，不能否决注册表变更本身。

一套值得参考的取舍

回头看，这套命令系统的每个决策都在回答同一个问题：命令是给人用的确定性操作，不该和模型路径混在一起。不创建模型消息，斜杠命令就不会变成一次推理开销；生命周期独立记账，界面渲染与事后审计都有据可查；描述符与 handler 分离，发现接口就不会把执行细节泄漏出去；准入失败不写日志，会话流里也就不会留下噪音。

对任何要做斜杠命令、面板快捷操作的 agent 产品来说，这份子系统文档都是很好的设计参考。DeepSeek Harness 采用 MIT 协议开源，当前处于开发者预览阶段，完整代码见 GitHub 仓库 deepseek-ai/deepseek-harness 的 packages/interaction/commands。