dsh-tool-authoring

name	dsh-tool-authoring
description	写或改 dsh 里模型可调用的工具时使用——defineTool、parameters/output schema、execute 契约、exec.signal/exec.agent、后台任务（run_in_background + ctx.jobs）、UI 卡片（presentCall/presentResult/presentationMeta）、以及该用哪个执行策略钩子（tools/pre-execute、ctx.tools.guard、tools/execute、tools/post-execute、tools/result）。也用于排查工具没被模型调用、参数校验、isError 语义、Code Mode 兼容性。

写 dsh 工具

先运行 python3 tools/check-harness-drift.py。目标版本的语义真源是 vendor/deepseek-harness/docs/cookbook/adding-a-tool.zh.md（完整字段见 docs/subsystems/tools.zh.md），实际签名以目标插件安装的 .d.ts 为准。生产级实现可查 上游 packages/tool/tool-bash/；本地插件只在依赖版本相同且测试通过时作为参考。

最小形态

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx: Context): void {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',        // 模型看到的就是这句
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },                 // 默认可选
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      // args 由 schema 推导出类型：{ path: string; limit?: number }
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

注册是副作用：dispose 插件 fiber 就注销工具。schema 自动流进系统提示词组装。

defineTool 是第一方工具用的类型化辅助函数；ctx.tools.register() 也直接吃原始 JSON Schema 的 ToolDefinition（MCP 来源的工具就走这条），但那种要自己负责 输入校验。

execute 契约

• 参数已经替你校验过。 类型、必填、字面量、联合（恰好匹配一个分支）、嵌套值 都在 execute 前校验完。schema DSL 表达不了的仍要手查：非空字符串、正数、 跨字段规则。显式对象节点必须声明 additionalProperties: true | false。
• 把 args 当只读。 注册表会把 arguments 物化成分离的无损 JSON 并在策略开始 前冻结，同时分配不透明的 exec.token。
• 返回规范 JSON 值，不返回内容块。 output.schema 用 ValueSchemaSpec，根可以 是对象/数组/标量/null。注册表快照 → 校验 → 冻结 → 才交给 output.render(args, value)。别让调用方从自然语言里解析 id 和字段。
• 抛异常或返回非法值 = isError。 基础设施故障就抛。领域上的坏结果不算 错误——进程非零退出这类，要写进规范值，由 render 去解释。
• 遵守 exec.signal。 信号触发就取消。
• exec.agent 用来发异步通知： agent.inject({ content, source: { kind: 'plugin', plugin: '<name>' } }) 追加 持久上下文，下一次模型请求会看到。这不是唤醒——空闲的 agent 保持空闲。要 防 agent 已 dispose（try/catch）。
• 注册借用你的只读定义。 注册后不要改 schema 或换回调。要热替换工具就 dispose 它所在的 effect 再注册替代品。

描述怎么写

description 是模型判断工具用途的主要触发面。把用户真会说的话写进去；面向中英 用户的插件可以同时给出两种语言和明确触发词：

description:
  'Save a manual snapshot of the current profile configuration '
  + 'into the configuration history. Trigger words: "保存快照", '
  + '"save a snapshot", "记下当前配置". Snapshots are never auto-cleaned.',

长时间运行的工作

用 producer 配置开 run_in_background，再 ctx.jobs.start({ kind, label, owner: exec.agent, run })。

• 预先中止的调用判失败（此时没有 job，id 满足不了成功输出 schema）。
• 成功的后台分支返回类型化句柄，如 { kind: 'background', jobId }。渲染器可以 输出 started background job bash-1 这种人话，但 Code Mode 绝不能靠解析 这段文本拿 id。
• ctx.jobs.start() 发布 id 之后，用 job 自己的取消信号，不要用 exec.signal：之后取消外层调用只停止等待，不终止已发布的工作。那段生命周期 归 job_kill、owner dispose 和服务 teardown。前台工作仍与 exec.signal 耦合。

别把部署策略写进工具

按需要的语义选钩子，别默认选第一个：

需求	用
可扩展的允许/拒绝/询问策略	tools/pre-execute（waterfall，返回类型化决策）
不变式要求的单调最终拒绝，后续监听器无法撤销	ctx.tools.guard()
包裹实际分派生命周期：超时/重试/指标	tools/execute（只有它能替换 exec.signal）
显式变换展示或返回值、阻止结果、附加模型可见上下文	tools/post-execute
只观察不可变最终结果（指标/审计/捕获）	tools/result
过滤模型可见工具集（展示/查找/执行三者对齐）	ctx.tools.restrict()

工具绝不 import UI 或传输类型。

Code Mode 会自动碰到你的工具

Code Mode 下每个可见工具都能 await tools.<name>(args)，无需额外集成；生成的 ToolArgsMap / ToolOutputMap 从同一组 schema 派生。成功调用解析为策略处理后 的规范 JSON 值（不是渲染后的内容），失败以 ToolCallError reject（程序只能看 name、toolName、message）。

所以：把 output.schema 设计成好用的程序化 API——直接返回句柄和字段，人话 解释放 output.render。

UI 卡片

模型可见内容（output.render）和 UI 卡片是两件独立的事。卡片通过可选的 presentCall(args) / presentResult(args, result) 声明，选匹配行为的卡片类型：

• { card: 'generic', title, kind?, rawInput?, content?, locations? } —— 默认。 locations: [{ path, line? }] 让编辑器能跟随跳转。
• { card: 'terminal', title, description?, cwd? } —— 调用本身是 shell 命令。
• { card: 'diff', title, diffs, locations? } —— 创建/修改文件；新文件 oldText: null。
• 结果侧还有 search（shape: 'matches' | 'paths' + truncated/total）和 web（kind: 'search' | 'fetch'）。

硬性规则（违反会出问题）：

1. 展示器必须是纯函数。 实时流和会话日志回放都会跑它——不做 I/O、不读会话 状态、不用时钟/随机数。想在 presentCall 里读文件旧内容或 cwd 就是信号： 那属于持久结果元数据或适配器，不属于展示器。
2. UI 格式不许进模型结果。 ```console 围栏、diff、相对化路径都不该为了 UI 进规范值或 Native 内容。
3. 展示路径是软校验：畸形或旧日志参数让包装器返回 undefined（回退到通用 卡片），而不是抛异常——展示绝不能让回放崩溃。

需要在回放里重现的结果期事实（write/edit 的已应用 hunk 之类），用 output.presentationMeta(args, value) 投影出可回放 JSON，核心会持久化在 tool/result 上。嵌套 Code 分派没有卡片，会跳过这个投影器。

自查

• description 带用户真会说的触发词（中英都给）
• 目标 Harness 版本、工具文档和 .d.ts 来自同一 preview 面
• 显式对象节点声明了 additionalProperties
• execute 返回规范值而非内容块；领域坏结果没被当成异常抛
• 前台工作透传 exec.signal；后台工作发布 id 后改用 job 的信号
• output.schema 对程序化调用方够用（Code Mode 不需要解析人话）
• 展示器是 args（+ result）的纯函数，没有 I/O
• 策略没写死在工具里，而是挂在正确的钩子上
• 有会话审计需求的调用往 exec.agent?.session.append(...) 追加了事件