接缝实地笔记 YeKui7/dsh-seams

dsh-seams

DeepSeek Harness (dsh) 的接缝实地笔记。

dsh 是「一切皆插件」架构，官方把可扩展点叫 capability seams。这份笔记记录三件事：

- 能切进去的地方在哪——路径、waterfall、事件名，以及各自能改什么、不能改什么
- 一套能跑的干预配方——不写 TS、不构建 monorepo，挂个 shell 脚本就能往会话上下文里加内容
- 四个会静默失败的坑——都不报错，只会让你得到错误的结论

验证于 @deepseek-ai/dsh@0.1.5-rc.1 / Node v24.21.0 / WSL2。dsh 处于 developer preview， README 原话 "THERE WILL BE COMPATIBILITY-BREAKING CHANGES"——遇到对不上的地方以你装的版本为准。

作者：@YeKui7 · MIT License 内容全部来自实机验证；每条结论都能用下面的「复现」小节重跑一遍。

🔴 四个静默失败的坑

不报错、不打印、退出码 0。踩中一个就够浪费半天。

1. Node < 22.16 根本跑不起来，且什么都不说

入口 lib/bin.js 末尾：

if (import.meta.main) await runCli();

import.meta.main 是 Node 22.16+ 的特性。在 Node 20 上它是 undefined → runCli() 永不执行 → 整个 CLI 静默退出 0、不打印任何东西、不报任何错。

$ node --input-type=module -e "console.log(typeof import.meta.main)"
undefined # Node 20 → dsh 完全不可用 boolean # Node 22.16+ → 正常

npm 安装时只有 EBADENGINE 警告（commander@15 要 >=22.12.0、undici@8 要 >=22.19.0），
很容易当成无害提示略过。先查 Node 版本，再怀疑别的。

2. cordis.patch.yml 的条目格式：写错不报错，只是不生效

profile 补丁层只有两种合法形状：

① 覆盖已有行
- id: system-prompt
config: { ... }

② 追加新行
- insert:
- id: my-plugin
name: '@scope/pkg'
config: { ... }

直接写行的形状（- name: '@scope/pkg'）是无效的：不报错，--dump-config 里看不到，插件就是不加载。

官方文档的 "smallest working setup" 小节给的是行的形状，不是补丁条目的形状——照抄会踩。

每次改完补丁都该验证：

dsh --profile <name> --dump-config | grep -A3 '<你的 id>'

3. 会话日志是多帧 zstd，常规解压只出第一帧

会话写在 ~/.dsh/sessions/--<cwd 用 - 连接>--/<session-id>/session.v3.jsonl.zstd， 每步追加一个独立的 zstd 帧（实测一次 3 步会话 16 帧）。

zlib.zstdDecompressSync() 与 zlib.createZstdDecompress() 都只解第一帧——只会拿到一条
session 头事件（约 189 字节），看起来就像「dsh 不落盘」。必须按帧魔数 28 B5 2F FD 切开逐帧解：

node tools/unzstd.mjs ~/.dsh/sessions/--/session-/session.v3.jsonl.zstd out.jsonl

4. --json 在发布版里可能还没有

仓库 main 分支的 headless 文档描述了 dsh --profile headless --json（NDJSON 事件流，含 tool_call / tool_result），但 npm 上的 0.1.5-rc.1 没有这个旗标（error: unknown option '--json'）。

即便有了也要注意：文档写明「every other string and object key is capped at 8 KiB and flagged with truncated」——长输出会被截断，只有 final 不截。要无损数据就读会话日志，别依赖 --json。

能切进去的地方

| 接缝 | 能做什么 | 不能做什么 |
| agent/pre-step | 请求派生前唯一的 waterfall：reject 本步，或替换进入本步的消息 | — |
| agent/request | 替换调用配置 | 不能改消息 |
| tools/pre-execute | 放行 / 拒绝一次工具调用 | 不能改工具输入（updatedInput 未实现） |
| tools/post-execute | 变换工具返回 | — |
| tools/result | 只读观察冻结后的最终结果 | 不能改 |
| agent/inject() | 往下一个 pre-step 排队投喂内容 | 可能错过已认领批次的请求 |
| agent/turn-stopping | 停止前做检查、或再推一步 | — |
| agent/request-error | 出错后修状态或要求重试 | — |

⚠️ 自写插件往 agent/pre-step 塞消息时：有第三方插件记录过，直接 splice 看起来生效、其实被静默丢弃（后续 listener 从 payload 重建答案，不报错）。正确写法是 ctx.on(..., {prepend: true}) 且先 await next() 再 append。

干预配方：不写 TS 也能注入上下文

dsh 把 Claude Code 的 hook 协议 桥接成了扩展点。
包 @deepseek-ai/dsh-hooks-claude-code 已是 @deepseek-ai/dsh 的直接依赖（装 dsh 时就装好了）， 挂一个 shell 脚本就能注入，不需要写 TS 插件、不需要构建。

三步（hooks/ 与 examples/ 里是可跑的最小样例）：

1. 写一份 Claude Code 格式的 hooks.json，把 UserPromptSubmit 指到一个命令
2. 命令往 stdout 打：
{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"<要注入的文本>"}}

只认 JSON，plain stdout 不支持
3. 在 profile 的 cordis.patch.yml 里 insert 一行 @deepseek-ai/dsh-hooks-claude-code， configPath 指到那份 hooks.json

验证注入真的到达模型：注入一句哨兵句，任务写成「复述以某前缀开头的那句话」——模型若说得出来、而任务文本里并没有这句，就是注入生效。实测模型会逐字复述， thinking 流里也会出现 There's an injection test embedded。会话日志里有 hook/invoked 与 hook/result 事件可交叉验证。

桥的能力边界（来自包文档）：

- PreToolUse 的 additionalContext 被忽略；allow 不预授权
- PostToolUse 的 tool_response 被拍平成文本
- transcript_path 恒为空——zstd 压缩的会话日志 hook 脚本读不了
- 只跑 shell 形式的命令处理器；http / mcp_tool / prompt / agent 处理器被跳过
- 30 个 Claude Code 事件里有 23 个不支持

可重复运行：沙盒要自己造

dsh 的文件工具真改工作区，而 workspace 没有快照/回滚。最省事的做法是一次性 git 仓库当沙盒，
每轮之间：

git checkout . && git clean -fd

实测重置后文件哈希与提交基线逐字节一致。

环境事实速查

| 项 | 值 |
| 会话日志 | ~/.dsh/sessions/--<cwd 用 - 连接>--/<session-id>/session.v3.jsonl.zstd（多帧 zstd） |
| 正文位置 | assistant/message → .data.message.content[]，块类型 reasoning / text / tool-call |
| 事件类型 | session turn/start turn/end step/start step/end user/message system/message assistant/message tool/call tool/result request/header request/context hook/invoked hook/result agent/inbox/spliced session/title approval/ permission/preset sandbox/mode |
| 模型配置 | request/header 事件里可读到实际生效的 provider / model / maxTokens / reasoningEffort |
| profile 位置 | ~/.dsh/profiles/<name>/（cordis.yml 是空壳，实际改 cordis.patch.yml） |
| 组合后的配置树 | dsh --profile <name> --dump-config |
| 插件生态 | GitHub topic dsh-plugin |
| 工具名 | 小写、集合比 Claude Code 大：read bash edit write glob grep todo_write web_fetch web_search subagent skill workflow … 另有 task / job_ / _goal 一族 |

按工具名判别「返回里有没有新内容」，别按返回的字节数——读一个小文件的返回可能比一次编辑的确认还短。

复现

npm install # 装 dsh（Node ≥ 22.16）
./hooks/inject.sh # 自测 hook 脚本输出把一个一次性 git 目录当沙盒，cd 进去跑：
npx dsh --profile headless "读 a.txt，把行数写进 b.txt"
解会话日志（多帧 zstd）
node tools/unzstd.mjs ~/.dsh/sessions/--/session-/session.v3.jsonl.zstd out.jsonl

没验证的

- dsh 的 web / tui / SDK 等其它运行形态
- hooks 桥除 UserPromptSubmit 外的事件
- DeepSeek 以外的 provider
- Windows 原生（本机是 WSL2）
- 工具分类表里的语义划分（按工具名推的，没做统计验证）

官方资料

- deepseek-ai/deepseek-harness
- docs/agent-lifecycle.md — 回合 / 步生命周期时序图，一张图说清所有 waterfall 的位置
- docs/subsystems/core.md — 各 waterfall 的完整签名（搜 agent/pre-step）
- docs/capability-seams.md — 能力接缝总图
- packages/hooks/hooks-claude-code/README.md — 桥的能力边界与已知限制
- packages/bundle/headless/README.md — headless 运行器与 --json 契约