MCP 录制回放bleakbelladonnals/dsh-echo

面向 DeepSeek Harness 的非官方 MCP 确定性录制与回放插件。
真实调用只录一次；无需凭据和网络即可离线回放；每次命中、差异与契约变化都能在 DSH 中检查。

English ·
项目主页 ·
GitHub Action ·
安装 ·
快速开始 ·
架构 ·
安全边界

[!NOTE]
DSH Echo 不隶属于 DeepSeek，也未获得 DeepSeek 或上游作者的官方背书。
v0.1 可从源码安装，但尚未发布到 npm。

为什么是 DSH Echo？

MCP 工具背后往往连接 API、数据库和真实业务系统。直接用它们测试 Agent，
容易受到网络、凭据、费用、限流和副作用影响。DSH Echo 在 DSH 与 MCP Server
之间放入一盘 Cassette：先对真实世界录制一次，以后在本地确定性回放。

| 录下真实调用 | 安全离线回放 |
| --- | --- |
| stdio 与 Streamable HTTP/SSE | 按方法和参数确定性匹配 |
| 追加式、版本化 JSONL | 未录制调用默认失败关闭 |
| 落盘前默认脱敏 | 普通回放不启动真实 Server |
| 保存结果与耗时 | miss 显示最近参数差异 |

| 看清发生了什么 | 守住工具契约 |
| --- | --- |
| Session 范围内的 Web 检查器 | Contract Snapshot |
| 参数、结果、hit/miss 状态 | Schema Drift 分类 |
| 精简 Trajectory 标注 | Breaking Change CI 门禁 |
| 进入 UI 前二次脱敏 | Fixture 导出前 Secret Scan |

GitHub Marketplace Action

可以把同一套健康检查、安全检查和契约检查直接接入 Pull Request。这个 Composite
Action 会启动指定的 MCP Server、对比已提交的契约快照、写入 Job Summary，并在每次
重新运行时更新同一条 PR 评论。

~~~yaml
- uses: bleakbelladonnals/dsh-echo@v0.1.0
with:
server-command: node dist/server.js
snapshot-file: mcp-contract.snapshot.json
fail-on: breaking
~~~

在 GitHub Marketplace 查看 DSH Echo MCP Contract Gate。

安装到 DSH

环境要求：

- Node.js 22.19+（Node 22 系列）或 Node.js 24+
- 兼容性基线：DeepSeek Harness 0.1.1-rc.2
- 一个全新或明确指定的 DSH Profile

推荐先安装到隔离 Profile：

~~~bash
git clone https://github.com/bleakbelladonnals/dsh-echo.git
cd dsh-echo
npm ci
npm run build
npm pack --ignore-scripts

export DSH_HOME="$(mktemp -d)"
dsh plugin --profile web add ./dsh-echo-0.1.0.tgz
dsh --profile web --no-open
~~~

进入任意 Session 后，可以看到 Echo / 录制回放 页签。安装时
bindings: []，所以仅安装插件不会拦截或改变任何 MCP Server。

卸载：

~~~bash
dsh plugin --profile web remove dsh-echo
~~~

只有在你明确要安装到日常 DSH Profile 时，才应省略临时
DSH_HOME。

录制与离线回放

录制 stdio MCP Server，默认开启脱敏：

~~~bash
dsh-echo record -o .dsh-echo/demo.cassette.jsonl -- \
node examples/fixture/server.mjs
~~~

离线回放同一段交互：

~~~bash
dsh-echo replay .dsh-echo/demo.cassette.jsonl
~~~

未录制请求返回 JSON-RPC -32601 并以非零状态退出，且不会启动
真实 Server。只有同时显式指定 --on-miss passthrough 和真实
Server 命令时，才允许实时回退。

Streamable HTTP 通过 loopback 端点工作：

~~~bash
录制
dsh-echo record -o .dsh-echo/http.cassette.jsonl \
--http http://127.0.0.1:3000/mcp \
--listen 127.0.0.1:6402

回放
dsh-echo replay .dsh-echo/http.cassette.jsonl \
--listen 127.0.0.1:6402
~~~

连接一个 DSH MCP Server

当前 DSH 会直接构造 MCP Transport，因此 DSH Echo 使用可撤销 Profile
Overlay，不修改 DSH 源码，也不原地编辑你的源 Profile：

~~~bash
dsh-echo profile patch \
--source ./cordis.yml \
--out ./cordis.echo.yml \
--recovery ./cordis.echo.recovery.json \
--root ./.dsh-echo \
--server-row mcp-demo \
--cassette-id demo \
--cassette demo.cassette.jsonl \
--mode replay
~~~

生成的 replay 行不含原 Server 命令；record/passthrough 使用 argv 数组，
不拼接 Shell 字符串。源文件保持不变。恢复记录可写入另一个文件：

~~~bash
dsh-echo profile restore \
--recovery ./cordis.echo.recovery.json \
--out ./cordis.restored.yml
~~~

应用前请人工检查生成的 YAML。v0.1 支持 HTTP record/replay，有意不提供
HTTP passthrough。

DSH 中能看到什么

对于名称形如 mcp__<serverName>__<tool> 的工具，Host
插件会写入精简的 tool/result.meta.dshCassette 引用。完整结果留在
Cassette 内，不会重复写入 Session Log。

Echo / 录制回放 页签展示：

- Cassette ID、模式、Transport、格式与脱敏状态；
- 每次交互的参数、结果、耗时与来源；
- recorded、hit、miss、passthrough、error；
- miss 与最近录制调用之间的结构化差异；
- Contract / Schema Drift 和 Snapshot 操作；
- 当前 Session/Trajectory 中的关联标注。

Host API 只接受已配置的 Cassette ID，不接受任意路径。所有 Cassette 与
Snapshot 必须位于指定 Root 下，数据进入浏览器前还会再次脱敏。

契约门禁

先保存基线：

~~~bash
dsh-echo snapshot --stdio "node examples/fixture/server.mjs" \
-f mcp-contract.snapshot.json
~~~

删除工具或出现 Breaking Schema Change 时让 CI 失败：

~~~bash
dsh-echo snapshot --check --fail-on breaking \
--stdio "node examples/fixture/server.mjs" \
-f mcp-contract.snapshot.json
~~~

仓库 CI 自带会删除工具并新增必填参数的 Fixture，并断言门禁确实失败。

安全导出 Fixture

原始录制默认位于 Git 已忽略的 .dsh-echo/。导出是独立、显式的
步骤：

~~~bash
dsh-echo export-fixture \
.dsh-echo/demo.cassette.jsonl \
--root ./fixtures \
--out demo.cassette.jsonl
~~~

命令会拒绝 Root 之外的路径，并在发现 Secret 时阻止复制。扫描通过仍需人工
复核：基于模式的自动脱敏是纵深防御，不等于“可以直接公开”。

架构

~~~mermaid
flowchart LR
DSH["DeepSeek Harness"] --> Adapter["DSH Echo Profile Adapter"]
Adapter --> Core["Record / Replay Core"]
Core --> Live["真实 MCP Server"]
Core --> Tape[("版本化 Cassette")]
Tape --> Core
Core --> Session["Session 标注"]
Session --> UI["Echo Web 检查器"]
~~~

通用 Transport 引擎仍可独立作为 CLI 使用；DSH 适配集中在
src/dsh/。生命周期、信任边界和集成取舍见
架构说明。

开发与验收

~~~bash
npm ci
npm run lint
npm run typecheck
npm test
npm run test:e2e
npm run audit:pack
npm pack --dry-run --ignore-scripts
~~~

当前共 463 项测试，覆盖真实 stdio 录制/回放、无 Server 回放
Tripwire、Profile 恢复、路径限制、UI 二次脱敏、契约漂移、生命周期清理和
Tarball 审计。验收只使用临时 HOME、loopback、隔离 npm cache 和隔离 DSH
Profile，不读写真实用户配置。

- 完整验收记录
- 安全模型
- 上游审计
- DSH 集成方案对比
- Fixture Server

上游与许可证

DSH Echo 派生自
ivermin1123/mcp-cassette，
导入 Commit 为 9e48be26cbf1f7fca5edde142673a9b102a25e86
（上游 0.4.0）。保留的引擎提供 stdio、Streamable HTTP/SSE、
匹配、脱敏、Contract Diff、安全 Lint 和 Vitest 集成。

精确归属与修改记录见 UPSTREAM.md 和 NOTICE。
项目采用 Apache-2.0 许可证。