dsh-tool-cassette

给 Agent 的工具调用开启“飞行模式”：一次录下规范结果，随后在 DeepSeek Harness 中离线、精确地回放；回放期间，被选工具的真实正文调用次数为零。

非官方社区插件。 本项目由社区成员独立开发和维护，与 DeepSeek 官方无隶属关系，也未获得官方审核或背书。

当前版本为 0.1.0，兼容边界固定在 DeepSeek Harness 0.1.0-rc.8。

它解决什么问题

Agent 测试常同时依赖模型与外部工具。官方 dsh-llm-replay 可以回放模型流，HTTP、MCP、数据库、Python、Go、Java 等工具正文仍会真实执行。dsh-tool-cassette 补上工具边界：录制真实工具的规范结果，随后在无网络、无服务和正文 tripwire 环境中回放。

Record
Agent -> tools/execute -> 真实 HTTP / MCP / DB / 本地程序
                         -> DSH 规范 value/error -> cassette

Replay
Agent -> tools/execute -> cassette 精确命中 -> 当前 schema / renderer / post policy
                         真实工具正文调用 = 0

演示先启动纯本地 HTTP 工具并录制一次，再关闭服务进行回放。最终证据固定为：录制阶段工具正文与网络请求各 1 次；回放阶段两者均为 0；结果完全一致；记录全部消费。演示不调用模型或付费 API。

录制阶段先缓存 tools/post-execute 的输入边界，再用 rc.8 的最终 tools/result 快照核对调用。一般结果保存后置策略处理前的规范 value/error 与 additionalContexts；后置阶段触发取消时保存 DSH 最终取消结果。回放时仍需注册同名工具，保存的成功 value 会重新经过当前输出 schema、renderer、presentation meta 和后置策略。

快速开始

前置条件：已安装 pnpm。本插件固定兼容 DeepSeek Harness 0.1.0-rc.8；该版本当前位于 npm next 标签。安装插件与运行该 profile 时请持续使用同一 rc.8 CLI：

pnpm dlx --package @deepseek-ai/dsh@0.1.0-rc.8 dsh plugin --profile headless add dsh-tool-cassette

从源码构建并安装本地包：

pnpm install
pnpm run demo
pnpm pack
pnpm dlx --package @deepseek-ai/dsh@0.1.0-rc.8 dsh plugin --profile headless add .\dsh-tool-cassette-0.1.0.tgz

安装包会通过 cordis.patch.yml 注入默认禁用的 tool-cassette 条目。在 profile 的 cordis.patch.yml 中覆盖该条目，明确启用并填写模式、文件和叶子工具范围：

- id: tool-cassette
  name: dsh-tool-cassette
  disabled: false
  config:
    mode: record
    file: .dsh-cassettes/weather.tool-cassette.jsonl
    include:
      - weather_lookup
      - mcp_*_read

完成一次录制后，将 mode 改为 replay 并保持同一调用轨迹：

config:
  mode: replay
  file: .dsh-cassettes/weather.tool-cassette.jsonl
  include:
    - weather_lookup
    - mcp_*_read

相对路径基于 DSH 进程工作目录解析。include 必须非空，支持精确名称和 * 通配符。空范围、空路径和重复模式都会在插件启动时失败。

配置

interface Config {
  mode: 'record' | 'replay'
  file: string
  include: string[]
}

字段	含义
mode	record 执行真实工具并写制品；replay 精确命中并跳过正文
file	正式 cassette 文件；录制期间使用同路径加 .partial 后缀
include	显式选择叶子工具；* 匹配任意长度字符

严格匹配与失败关闭

每次调用使用以下信息匹配：

• 工具在调用树中的结构路径；
• 工具名称；
• 递归排序对象键后的无损 JSON 参数；
• 按调用开始顺序分配的 ordinal。

对象键顺序变化可以命中。数组顺序、参数值、调用顺序或结构路径变化会立即产生 CASSETTE_MISMATCH。第一次偏差会使回放器进入 poisoned 状态，后续选中工具持续失败，真实正文保持不执行。错误诊断只显示工具、路径、ordinal 和参数指纹。

每个被选调用都必须经过 cassette 的 tools/execute 监听器，并在最终 tools/result 中完成核对。更高优先级的包装器发生短路、结果缺失或轨迹绕过时，录制保留 partial，回放进入 poisoned 状态。

被选调用若在 DSH 的 pre-execute 或 guard 阶段被拒绝，也会按未进入 cassette 的轨迹失败关闭。录制与回放时，当前权限策略必须允许 include 中实际发生的调用进入 tools/execute。

tools/result 是 DSH 的只读观察事件。若更高优先级的插件同时短路 tools/execute 与 tools/post-execute，当前调用可能已经返回该插件的结果；cassette 会在最终观察点阻止录制发布或 poison 回放，并将进程退出码设为非零。

制品协议与完整性

cassette 是版本化 NDJSON。每帧包含连续 seq、前一帧哈希和本帧 SHA-256，最后一帧为 complete。

哈希链用于发现传输损坏、截断和普通篡改。它不包含数字签名，因此无法证明面对能够重写全部帧及哈希的攻击者时仍保持真实性；需要跨信任边界分发时，应由制品库另行提供签名或不可变存储。

Record 使用以下发布步骤：

1. 独占创建 <file>.partial；
2. 串行追加 header、call/start、call/result；
3. 每帧同步到磁盘；
4. 全部调用完成后写 complete；
5. 关闭文件，以 create-only 原子发布正式文件，再删除 partial。

正式文件或 partial 已存在时，录制器拒绝启动。执行中失效、待完成调用、concludesTurn、多个 Agent、选中复合工具及其子工具都会保留 partial，供排查使用。

CLI

dsh-tool-cassette verify .dsh-cassettes/weather.tool-cassette.jsonl
dsh-tool-cassette inspect .dsh-cassettes/weather.tool-cassette.jsonl

verify 完整验证协议、帧配对、连续 ordinal、哈希链和完成尾帧，并用退出码表达结果。inspect 只显示协议版本、工具数、调用数、完整性和消费说明，不显示工具名、参数或结果正文。校验失败只输出结构性原因，不回显原始行或绝对路径。

回放消费状态只存在于当前进程。所有记录消费完毕时卸载成功；poison、额外调用或未消费记录会让 headless/CI 进程退出码变为 1，同时由 Cordis 记录关闭错误。

安全说明

V1 为了精确回放，会原样保存规范化后的参数、成功 value、失败信息、渲染内容和附加上下文。cassette 应按密钥或测试数据库快照的安全等级处理：

• 默认 .gitignore 排除 cassette 与 partial；
• 只在隔离的本地或 CI 工作目录录制；
• 分享前人工检查全部内容；
• 录制结束后关闭不再需要的真实凭据；
• 参数指纹没有盐，低熵参数仍可能被猜测。

V1 不提供自动脱敏、加密、签名或远端制品库。

V1 边界

支持：

• 单 Agent、单场景；
• 显式选择的叶子工具；
• 成功、结构化失败和 additionalContexts；
• 并发调用按开始 ordinal 配对，完成顺序可以相反；
• 调用前取消不消费记录。
• 回放调用命中 cassette 后即消费对应记录；随后发生的 post 阶段取消不回滚消费位置。

明确拒绝或留待后续版本：

• 多 Agent 与并发 subagent；
• 同时选择复合工具及其子工具；
• concludesTurn: true；
• 模糊匹配、参数忽略规则和自动更新 fixture；
• 延迟、hang、流式输出和取消时序仿真；
• UI、云端制品库、benchmark DSL 与模型 judge。

LLM 流回放由官方 dsh-llm-replay 负责。本插件只承诺被选工具正文边界的确定性回放。

相邻项目

项目	边界
dsh-llm-replay	回放模型流
dsh-subagent-cassette	回放 one-shot subagent provider
dsh-tool-idempotency	在线调用去重与并发 join
dsh-tool-cassette	保存工具规范 value/error，离线跳过真实工具正文

开发与验收

pnpm install --frozen-lockfile
pnpm run lint
pnpm run typecheck
pnpm run test:coverage
pnpm run build
pnpm run demo
pnpm run test:tarball

测试只使用本地假工具与本地 HTTP 服务，模型调用和付费 API 调用均为零。CI 矩阵配置为 Ubuntu、Windows、Node 22.19 与 Node 24。

许可证

MIT