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 使用以下发布步骤：
- 独占创建
<file>.partial； - 串行追加
header、call/start、call/result； - 每帧同步到磁盘；
- 全部调用完成后写
complete； - 关闭文件，以 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。
No comments yet. Be the first to write one.