DeepSeek Harness 命令注册子系统解析

斜杠命令是 agent 产品的标配交互，但多数实现都把它当成一条普通消息发给模型，让模型去猜用户的意图。DeepSeek 开源的 agent 框架 DeepSeek Harness 给出了不同的答案：命令由插件注册、由界面直接执行，全程不产生模型消息。本文基于它的官方文档，拆解这套用户命令注册子系统的设计。

先交代背景。DeepSeek Harness 在 GitHub 上以 MIT 协议开源，架构口号是把一切做成插件，底层运行在 Cordis 插件框架之上，目前处于开发者预览阶段，官方明确提示后续会有兼容性破坏。命令子系统由仓库里的 interaction/commands 包提供，是交互式适配器与插件之间的契约层：适配器通过它发现插件拥有的命令，并针对确切的某个 agent 直接执行，而不是把这些命令包装成消息交给模型。

一、插件如何登记一条命令

命令的注册入口是 CommandDefinition 接口。name 是不带斜杠的小写命令名，description 面向发现界面展示，两者构成命令的公开身份。input 是可选字段，里面只有一个 hint 字符串，用于在用户输入自由内容之前给出占位提示，只有支持这类输入的客户端才会拿到它。

真正干活的是 handler：它接收一次调用上下文，直接对收到命令的那个 agent 执行，返回同步或异步的结果。另有一个容易被忽略的开关 recordInput，默认为 true，控制 command/run 事件是否记录用户原始输入；如果命令对应的领域事件本身已经拥有这份负载，插件应把它设为 false，避免同一份数据在会话日志里存两遍。

注册表收到定义后并非原样保存，而是先做校验，再冻结出一份与原注册对象脱离的生效定义。插件手里那份对象此后怎么改，都影响不到注册表里的版本。

二、直达界面的执行与结果

适配器掌握取消权：调用时要传入确切的目标 agent 和一个 AbortSignal，信号的生命周期归发起调用的那次 UI 请求所有。rawInput 从解析出的命令名之后开始，保留适配器交付的分隔符与后缀，handler 拿到的是未经二次加工的原文。

执行结果 CommandResult 只有 success 与 error 两种，它直接交给发起调用的界面渲染，既不是工具结果，也不是会话事件。成功结果上有一个可选的 sourceEventSeq 字段，指向接收会话日志里更早的一条非命令事件；command/done 会持久化同一引用，客户端因此能把命令的生命周期与那条领域投影拼在一起，不必解析文本，也不必依赖相邻行。

三、先语法解析，再作用域解析

命令的处理分两个阶段。适配器拿到的视图是 CommandDescriptor：一份不含 handler 的不可变描述，由名称、描述和输入提示组成，供发现界面使用。用户敲入一行命令后，parseCommand 先做纯语法的解析，产出 ParsedCommand；此时注册表还没参与，所以语法有效的输入仍可能指向一个不可用的命令。两个视图的拆分，把界面上能看到什么和点了之后能执行什么干净地分开了。

四、CommandRuntime 的四个方法与作用域遮蔽

在 Cordis 的语境里，这套服务暴露为 ctx.commands 上的 CommandRuntime，共四个方法。register 负责注册，返回值正是注销这条命令的 effect 清理函数。list 返回某个 agent 视角下按名称排序的全部生效描述符。find 解析单个名字，返回作用域遮蔽后的定义或全局定义。execute 接收完整的斜杠命令行和取消信号，返回已结算的执行结果；语法不通过或名字解析不到时返回 undefined。

作用域规则只有一条但很关键：在普通上下文注册的命令是全局的；如果插件通过某个 agent 上下文的命令注入子上下文注册命令，那么这些命令只为这个 agent 生效，并遮蔽同名全局命令。

五、生命周期日志与不对称的失败语义

一条命令一旦解析成功，日志就跟着走：handler 被调用前追加 command/run，结算之后追加 command/done，handler 抛出异常或被中止都结算为 error。这两条事件是纯日志追加，没有 turn 把它们包起来，持久化在常规检查点排出。准入失败，也就是语法错误或命令名不存在，什么都不记，因为执行根本没进 handler。

失败语义是刻意不对称的：command/run 追加失败会让整个执行响亮地失败；而 command/done 在 handler 已经失败的路径上追加失败时被悄悄抑制，保证最终上报的错误仍然是 handler 自己的错误。命令的注册与注销则通过 commands/change 事件广播，这是一条不做过滤的通知，因为全局或作用域变更可能影响任何界面视图；观察者的失败会被抑制，不能否决注册表本身的变更。

六、值得借鉴的三个设计取向

回看整个子系统，有三个取向值得做 agent 界面的开发者借鉴。其一，命令被当作 UI 层资产，语义由代码定义，结果直达界面，不消耗一次模型调用。其二，会话日志采用事件溯源的思路，command/run 与 command/done 用成对的 pairing id 串起来，命令生命周期与领域事件各归其位。其三，作用域组合复用了 Cordis 的上下文树，全局与单 agent 遮蔽不需要额外的配置面。当然，项目仍在开发者预览阶段，照着做集成之前，记得以当时的官方文档为准。