6d2e5a7cd7
CommandService.execute now returns a CommandExecution — the normalized result plus the commandId minted for its command/run/command/done records — and the wire admission value carries commandId exactly when matched, so the issuing client can correlate its RPC acknowledgment with the flow node the lifecycle events produce. apiproxy api/schema/handler, the connection fixture, and the TUI/plan/goal consumers follow the new shape.
4.4 KiB
@deepseek-ai/dsh-commands
English | 中文
由插件拥有、供交互式 UI 适配器使用的面向用户命令注册表。插件命令注册 Agent Note（agent 决策记录）定义了其边界与分发契约。
服务契约
ctx.commands.register(definition) 注册一个小写命令名称、描述、可选的非结构化输入提示，以及可中止的处理器。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 agent.ctx 下挂载的命令生产插件会声明自身的 commands 注入，并创建精确限定到该 agent 的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop 依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 commands/change 观察者，使实时适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
list(agent) 在应用作用域遮蔽后，返回按名称排序的不可变描述符。find(agent, name) 返回相应定义。execute(agent, line, signal) 使用 parseCommand()，且只运行已知命令，返回已结算的 CommandExecution（规范化结果加生命周期配对 commandId）；语法无效或名称未知时返回 undefined。已解析命令的生命周期会以 log-only 事件对的形式持久记录在接收 agent 的会话日志中：command/run（进入处理器前记录，携带铸造的 commandId、解析器的结构化 name/args 切分和发起方 CommandSource）与 command/done（结算时记录，携带结局种类与原样文本；处理器抛出或被中止时以 kind: 'error' 结算）。未通过准入的输入不记录任何事件。生命周期落账通过 SessionStore.appendOutOfBand 按会话串行化，因此本服务要求组合中存在 sessions 服务。
parseCommand() 识别位于字节零位置的斜杠、由小写字母、数字、_ 或 - 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 rawInput 返回，其中包括分隔空白；消费方拥有各命令专用的语法，只能执行该语法允许的规范化。
处理器返回 success 或 error，并可附带 UI 文本。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 rawInput 提交给 agent；命令生产方可以通过接收命令的 Agent 显式安排模型可见工作，此时该生产方拥有由此产生的消息契约。注册表会让处理器完成与所提供的中止信号竞速，但不协作的处理器可能在调用方停止等待后继续产生自身的外部副作用。
组合
终端应用组合包会将此服务与 dsh-tui 一起挂载；无 UI 的 agent 主干和 ACP（Agent Client Protocol）自动化应用不会挂载它。自定义交互式组合与命令生产方会显式挂载 @deepseek-ai/dsh-commands。
模型体验
直接面向用户的命令
模型看到的内容
注册表自身不会提交任何内容。已知斜杠命令在 UI 命令平面执行，其 CommandResult 文本不会作为用户消息提交。已交付的适配器会拒绝未知斜杠命令输入，而不是将其变成模型提示词。命令生产方可以显式使用接收命令的 Agent；例如，dsh-plan-mode在选择 plan mode 后，会提交 /plan [message] 中的可选消息。
Token 影响
命令发现、执行和 UI 输出不会增加模型 token。命令生产方显式安排的 agent 工作与相应 agent 输入具有相同的 token 影响。
KV Cache 影响
注册表元数据、命令输入和直接输出绝不会进入模型请求，也不会影响其缓存。被命令变更的领域拥有之后产生的所有缓存影响。
已知限制与延期工作
- 仅支持非结构化文本输入：表单、补全 schema 和类型化参数仍由各命令自行解析。
- 副作用采用协作式取消：中止后，分发会停止等待；处理器必须遵循信号，才能停止已经进入外部系统的工作。