DSH plugin 插件开发的交互选型:审批、提问、命令与工具各管什么场景、怎么组合才不返工
插件开发做到要和人打交道时,选错入口比写错逻辑更难修。 审批、提问、命令、工具,四个入口看起来都能“让用户做点什么”,但发起者、回答者与是否阻塞完全不同。DSH插件 里这四条路径各有闭合语义,混用会让流程变得既不可测也不可审。
DSH plugin 四个交互入口的判定表
先看谁发起、谁回答,再决定用哪个。(来源)
| 入口 | 谁发起 | 谁回答 | 是否阻塞 | 进模型上下文 |
|---|---|---|---|---|
| 审批 | 工具执行前 | 用户或自动化桥接 | 阻塞该次操作 | 否,只写审计 |
| 提问 | 工具或命令内 | 用户 | 可计时、可后补 | 是,作为用户消息 |
| 命令 | 用户 | 插件 handler | 否 | 否 |
| 工具 | 模型 | 插件 execute | 是,占一轮 | 是 |
表里最容易被忽视的是最后两列。审批不产生模型可见内容,所以“用户批准了”这件事要靠工具结果转述;提问会进入会话历史,所以不该用它承载纯授权。
审批:DSH plugin 唯一能给“一次性放行”的入口
审批的语义是“这一次可以”,不是“以后都可以”。(来源)
ApprovalOutcome 是闭合四值,只有 allowed-once 允许继续。缺失、不负责该请求、抛异常或返回词表外值的应答者,都会被归为 unavailable 并按拒绝处理。
三个使用要点:
- 执行前申请 — 审批挂在具体操作之前,而不是事后补一条记录。
- 不带参数 — 审批请求刻意省略工具参数,用
callId关联到已流式展示的调用,避免重渲染漂移。 - 不开轮次就拒绝 — 空闲时发起审批会直接失败,因为审计对必须落在未结束的轮次里。
还需要区分会话策略:never 会在分发之前就拒绝,应答者根本看不到请求。插件不要把“用户会批准”当成流程假设。
提问:DSH plugin 要信息,不要授权
提问回答的是“选哪个”,不是“能不能做”。(来源)
提问支持结构化选项、自由文本与多选,答案里带的是标签字符串而不是索引。计时提问在窗口内等待,超时后返回 pending。
pending 的语义必须记牢:它表示问题仍可回答,不是空答案、拒绝、确认或授权。把 pending 当成“用户放弃了”,是迟到回复类问题的常见起点。
适合提问的场景:参数取值不确定、需要在两个方案里选、需要用户补充一段说明。不适合:权限判断(用审批)、需要模型自己推断的默认值(用工具参数默认值)。
命令:用户主动触发,DSH plugin 不消耗轮次
用户知道自己要做什么时,命令比工具更直接。(来源)
命令直接针对确切的 agent 执行,不创建模型消息,也没有轮次包裹。注册时声明名称、描述与可选输入,结果直接呈现给 UI,只把 command/run 与 command/done 写进日志。
两条边界值得注意。第一,附件准入在 execute 里强制执行,未声明 input.attachments 的命令收到附件会在 handler 运行前失败。第二,rawInput 保留分隔符与后缀,命令自己决定怎么解析,不要期待框架替你切参数。
适合命令的场景:用户明确要做的动作、调试入口、需要立即反馈的查询。不适合:需要模型理解自然语言的请求。
命令还有一个隐性好处:它不占轮次。用户执行十次查询就是十次轻量调用,不会把会话历史撑长;反过来,用工具做同样的事,每轮都要带上 schema 与结果,成本高得多。
工具:模型主动调用,DSH plugin 占一轮
绝大多数“让模型做事”的需求,最终都落在工具上。(来源)
工具由模型在轮次中调用,defineTool 根据 parameters 推导并校验参数,execute 返回 output.schema 声明的规范值,output.render 再转成面向模型的内容。
工具与前三者的关系是“组合”而不是“替代”:工具内部可以发起审批(危险操作前),可以发起提问(缺参数时),也可以通过命令暴露一个用户手动入口。
组合时的顺序也有讲究:先拿信息、再拿授权、最后执行。反过来先授权后补参数,用户批准的和实际执行的可能不是同一件事。
DSH plugin 的入口组合与三个反面例子
用错的症状很有辨识度,认出来就能改。(来源)
- 用提问代替审批 — 症状:用户点了“同意”,但系统没有审计记录,也无法证明只授权了一次。
- 用工具报错代替提问 — 症状:模型连续重试三次,每次换一个猜的参数,用户被迫看三轮失败。
- 用命令代替工具 — 症状:用户得自己记住命令语法,而模型明明能从上下文推断出参数。
反过来也有三个:用审批代替提问(拿不到参数值)、用命令做需要模型判断的事(用户要背语法)、用工具做纯确定性操作(白占一轮)。
这三种错法的共同点是“入口和发起者不匹配”。判断时不要问“哪个更好用”,而要问“这一步是谁发起的、谁应该回答”。
验证:同一需求四种实现
把“删除一批文件”分别用四个入口实现,差异会立刻显现。(来源)
- 用工具实现:模型调用,参数是路径列表,执行前发起审批,断言只有
allowed-once才真正删除。 - 用提问实现:先问用户确认哪一批,断言返回的是结构化选择,且进入会话历史。
- 用命令实现:用户输入命令名触发,断言不产生模型消息,结果直接回 UI。
- 用审批策略实现:会话设
never,断言请求在分发前就被拒绝,应答者一次都没被调用。 - 把 1 与 2 串起来:先提问拿参数,再审批拿授权,断言两步各自闭合且
callId对应同一次调用。
如果第 1 步删除发生了但审计里没有记录,说明审批被放到了执行之后;第 5 步参数与执行不一致,通常是审批请求里塞了参数而不是用 callId 关联。
审批的会话策略细节可以对照用户审批与会话策略;提问的超时与迟到回复见用户提问与计时窗口;命令注册见用户命令。
一句话收束: 授权找审批、取值找提问、用户主动找命令、模型主动找工具;四者可以组合但不能互相顶替,判断标准永远是“谁发起、谁回答、要不要留痕”。
常见问题
走审批,这是 DSH plugin 里唯一能给一次性授权的入口。审批只有 allowed-once 才放行,其余结果调用方一律拒绝,正好对应“这一次操作是否允许”;让工具直接失败则没有给出让用户确认的通道。删除这类不可逆动作应当先拿一次性授权,再执行。
需要人给信息时用提问,DSH plugin 的提问返回的是用户真实选择。用户交互 seam 支持结构化选项、自由文本与计时窗口,返回的是用户真实选择;靠工具报错让模型猜,会把一次明确询问变成多轮试错,还容易猜错。
DSH plugin 里用户主动触发、不需要模型参与时做成命令。命令直接针对确切 agent 执行,不创建模型消息,也不会消耗轮次;需要模型判断参数、读取上下文的场景才应该做成工具。
可以,DSH plugin 的审批与提问能串起来,但要按顺序且各自闭合。提问返回用户选择,审批返回一次性放行,两者是独立 seam;先拿到参数再发起审批,审批请求里不带工具参数,用 callId 关联到具体调用,避免用户确认的和实际执行的不一致。
相关术语
- ApprovalOutcome
- ApprovalOutcome 是闭合的审批结果,只有 allowed-once 允许继续,rejected、cancelled 与 unavailable 都会被调用方按拒绝处理。— DeepSeek Harness 官方参考 - 用户审批
- AskUserQuestionIntent
- AskUserQuestionIntent 是提问的呈现意图,只有 plan-review 与 approval 两种,决定展示形态而不改变答案编码。— DeepSeek Harness 官方参考 - 用户交互
- CommandDefinition
- CommandDefinition 是用户命令的注册定义,含名称、描述、可选输入描述与 handler,执行时不创建模型消息。— DeepSeek Harness 官方参考 - 用户命令
- ToolDefinition
- ToolDefinition 是工具注册定义,包含面向模型的 schema、必填的输出声明与 execute 函数,由模型在轮次中调用。— DeepSeek Harness 官方参考 - 工具
来源
- DeepSeek Harness 官方参考 - 用户审批· deepseek-ai
- DeepSeek Harness 官方参考 - 用户交互· deepseek-ai