一切皆插件的 agent harness

dsh 是 DeepSeek AI 开源的 agent harness。它的架构主张只有一句：一切皆插件——模型适配器、工具注册表、会话日志、乃至 agent 主循环本身，都是可以从配置里替换掉的插件行。没有需要打补丁的特权内核。

先记住这七个数字

三条学习路径

掌握度自测

勾选记录在浏览器本地，刷新不丢。

读懂 dsh 的前提。Cordis 不是「插件 + ctx」两件套——专家脑子里装的是五个对象：Context、Service、Fiber、Effect、Event。

五种 dispatch 模式

waterfall 到底怎么走

next() 按位置消费链条，而且你不能向下游传新参数。若要改下游看到的东西，改的是被传递对象的内容，不是参数列表。

!!js 的真实作用域

配置值和一行的 disabled 支持 !!js（不是 !js）。它在 ESM 环境里求值，作用域里只有 process 和启动器注入的 dshHomePath()——没有 require，没有 import。实测写 !!js require('node:path')… 会在加载期报 ReferenceError: require is not defined。

# 能用
mode: !!js "process.env.DSH_PERMISSION_MODE ?? 'workspace-write'"
root: !!js dshHomePath('sessions')
dir:  !!js (process.env.HOME ?? process.env.USERPROFILE) + '/.claude/skills'
disabled: !!js process.platform !== 'win32'

# 加载期直接炸
dir: !!js require('node:path').join(...)

!!js 通过 internal/config 这个惰性配置 waterfall 解析，时机是每次激活、在该行自己的 fiber 里、且在注入生效之后——这正是 port: !!js ctx.webStartup.port ?? 3080 能让命令行 flag 打败写在旁边的字面值的机制。

一个运行中的 dsh 是组合出来的，不是配置出来的。层按顺序盖在一个空列表上，后面的层逐行覆盖前面的。

三种 patch 形式

# ① 覆盖配置 —— 替换整个 config 值，没有深合并，保留的字段必须重写一遍
- id: agent-default-model
  config:
    provider: deepseek-official
    model: deepseek-v4-pro

# ② 关掉一行 —— config 原样保留
- id: tool-web
  disabled: true

# ③ 插入新行
- id: my-plugin
  name: '@scope/my-dsh-plugin'
  config:
    threshold: 3

命令行边界

dsh --profile web --port 8080     # --port 属于 web app
dsh --profile web --help          # web app 自己的 help，不启动任何东西
dsh --help                        # 启动器自己的 help
dsh --profile headless "task"     # task 是 headless app 的位置参数

启动器只解析自己的 flag，第一个它不认识的 token 就开始 app 参数。三个后果值得记住：

• 打错的启动器 flag 会静默变成 app 参数，并且照常把整棵树启动起来——不会报错。
• 启动器只吃一个 --；要传字面量 -- 给 app 得写 -- --。
• 第一个 app 参数如果正好等于 web 或 plugin，会劫持成那个子命令。

验证与恢复

node apps/cli/lib/bin.js --profile headless --dump-config          # 含用户层与 --patch
node apps/cli/lib/bin.js --profile headless --dump-default-config  # 只有 bundle 层 —— 恢复用诊断
node apps/cli/lib/bin.js --profile web --patch ./x.yml --dump-config

--dump-default-config 是恢复诊断：它两个用户层都不解析，所以当你的 patch 文件把启动搞坏时，用它确认基线还是好的。两种 dump 都不发模型请求。

另有两个 dump 的盲区：dump 模式完全跳过 loadLayeredEnv，所以 dump 里的 !!js 环境表达式只反映你继承的环境；--dump-config 无法告诉你有效的 tools mode，它打印的是未求值的 !!js 表达式。

一个 step = 一次模型请求 + 它调的那些工具。一个 turn = 零个或多个 step：它在第一份输入被 claim 之前打开，在「什么都不欠」时关闭。

顺序上容易搞反的几处

取消与错误恢复

• 一个 turn 一个 AbortController。取消会清 inbox、latch 住 wake、并合成工具结果补齐未闭合的调用。
• abort 之后到来的唤醒输入被静默改投到 next-turn——你调的 steer() 可能实际变成了 followup()。
• agent/request-error 是唯一的模型失败修补接缝；其它任何异常都直接关闭 turn。
• step/end 和 turn/end 写在 finally 里——失败的 step 仍会闭合自己的边界；但失败的 turn/start 不会。
• agent/turn-stopping 被检查两次，而且决定权在数据，不在监听器顺序。

作用域：registrations 向下继承，events 向上准入

agent.ctx 是 scope.ctx.extend({ agent: this })，而那个 scope 是从 loop 的 context 铸出来的，不是调用方的。作用域键构成一条父链，两个方向相反：

model-visible ⟺ logged。凡是能到达一次模型请求的东西，都必须能从这条 append-only 日志重建出来——而且有一个运行时断言在强制它，不只是约定。这就是「新增一个模型可见输入必须新增一个 session event」的原因。

磁盘现实：三个会让你读错数据的坑

落盘时机：三个语义屏障，不是「turn 结束」

「每个 turn 结束才 flush」是 2026-06 的原始设计，2026-07-21 被判定「作为唯一崩溃恢复点太粗」而修掉。现役是一个独立于持久化的零配置插件 dsh-session-checkpoint-policy，在三个语义屏障上 await ctx.sessions.flush()，且失败关闭：

1. agent/pre-step——在下一次请求被推导之前，把 prompt 输入或上一轮的响应/结果批次刷下去；
2. llm/stream 内部——request/header 已记录、但适配器流尚未构造之时；
3. turn 边界。

另一条纪律：session/flush 必须走 ctx.sessions.flush()；裸调 ctx.parallel('session/flush') 是不变量违规。写入批处理窗口是固定截止时间——后来的事件不会重置它。

fork / resume 的锐边

• fork(source, boundary?, childSessionId?) 的 boundary 是包含式的，而且必须结束在一个 open turn 之外——它绝不静默裁剪，会直接拒绝。
• 被中断的 turn 是被关闭的，不是被截断——靠合成的 closer 事件。
• session/end-seed：读最后一个，别假设有一个正好坐在 firstLiveSeq。
• resume 和 fork 的 seedLength 含义不同，而 firstLiveSeq 也不是 header.seedLength。
• deriveMessages() 会跳过两样常被忘记的东西：raw chunks，以及内容为空的 assistant message。

其它硬事实

# 本门户配套 skill 里的读取器，7 种视图，无 zstd CLI 也能跑
~/.claude/skills/dsh/scripts/dsh-log.mjs --workspace DIR                # 时间线
~/.claude/skills/dsh/scripts/dsh-log.mjs --workspace DIR --view tools   # 调用+完整结果
~/.claude/skills/dsh/scripts/dsh-log.mjs --workspace DIR --view prompt  # 模型真正看到的 prompt 与 schema
~/.claude/skills/dsh/scripts/dsh-log.mjs --workspace DIR --view stats   # 事件直方图 + 注入字节数

这一章是全门户最省钱的一章。结论先说：headless 首个请求约 13,633 token，其中 91% 是 harness 自己写的、每次请求一模一样——而 system prompt 只占 7.4%。任何只展示「system prompt」的说明都把成本低估了一个数量级。

实测成本构成（headless profile，98 个 skill 进目录）

# 方案二：保留 skill，但把目录压瘦
- id: tool-skill
  config:
    catalogDescriptionMaxLength: 120

system prompt 与 runtime context 是两种东西

这是最容易混淆的一处：runtime context 不是 prompt 文本，它是一条 role: user 的消息，source 为 {kind:'plugin'}。

推论：一次 裸 assemble() 什么 runtime context 都拿不到；而一次会话中途的策略变更会产生两条模型可见消息，来自两个不同的插件名。

prompt section 的实际 order 带

-100  身份（harness identity）
   0  persona          # 出货的 base 是 persona-less，由 profile 供一行
  50  plan mode
  99  tools:code-only  # 只有 mode: code 会渲染出内容
 100–149  工具指引段（11 段）
 115  tool:report      # 只在 continuable 子代理作用域里存在
 150  Code Mode SDK 块
 110  沙箱策略  ┐ 这两条走 runtime-context
 115  审批策略  ┘ （user message，不是 system 文本）

装配还有两个细节：每个 step 都会深拷贝每个工具的 parameters；toolOrder 在 waterfall 之前应用。

AGENTS.md / CLAUDE.md 的真实行为

• 渲染预算 65,536 字节，界定的是完整渲染后的消息，并且有一条六级降级阶梯——最后两级会把 <system-reminder> 外框都丢掉。
• 发现过程做按目录的内容去重，跨信任边界跟随 symlink，而且没有 watcher。
• 工作区指令是持久的 user message，靠文件系统触碰来刷新。
• 指令状态完全活在消息的 typed source 里，绝不在模型可见文本里；而且只有当某个内容字节存活下来时，变更才会被记录。

工具注册表 + 三段 waterfall 受控管线。这一章合并两件事：管线怎么运作（改行为时要懂），和出货了哪些工具（用它时要懂）。

受控管线

出货的 24–25 个工具（headless，实测自真实 request/header）

先说清边界，因为它比大多数人以为的窄：dsh 的沙箱是一套 文件写入 策略。读、网络、进程可见性完全不受约束——它不是防外泄的安全边界。

出货的预设表有三个，不是两个

文档里说的「默认两项表」只是服务 Config 的兜底，不是出货组合。

钉死在会话创建时刻

实测每一份真实日志的 seq 0/1/2 就是这三件事，顺序固定：

{"type":"permission/preset","seq":0,"data":{"preset":"workspace-write"}}
{"type":"sandbox/mode",      "seq":1,"data":{"mode":"workspace-write"}}
{"type":"approval/policy",   "seq":2,"data":{"policy":"ask"}}

钉死之后，后续任何设置变更都不会改动已存在的会话。三个补充事实：pinInitialPermission 有三条不同路径，其中一条根本不写 preset 事件；set() 不产生模型可见的切换通告，只有 /permission 命令会；custom 是派生的，它读活的服务配置作兜底，所以可能在没有任何新事件的情况下翻转。

升权重试：完整的失败阶梯

模型撞到拒绝后可以带 sandbox_permissions 重试。那次重试本身就是同意提示，而且加宽是严格检查的——但检查在执行时，不在 schema 里。

平台后端的真实差异

ctx.llm 是一个适配器注册表加一个流式调用 API。写适配器只需继承 LlmAdapter 并实现 stream()——其余都是共享的折叠逻辑。

换模型 / 换供应商的旋钮在哪

# $DSH_HOME/settings.yaml —— 自建端点 + 声明视觉能力
llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      defaultInput: [text]          # 兜底，不是覆盖；默认 [text]
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]      # 只作用于这一个模型

modelOverrides 和 models 设计上互斥，写错会响亮拒绝。手写的 route 只能到达三种 wire 协议，其余是 catalog-only。

压缩（compaction）的真实行为

• 三个比率（thresholdRatio/retainRatio/retainTokens）都是相对实际路由到的模型的上下文窗口缩放的，不是相对某个常量。
• 保留是头部锚定的，并且总是至少留一个节点；retainTokens=0 就是「恰好留一个」。
• 压缩决策有两条不同入口，锁与容量要求也不同。溢出重试的计账是按 Agent 存在 WeakMap 里的，任何一次成功的 assistant message 都会把它重置。
• 摘要请求省略了 reasoningEffort——于是 thinking token 会吃掉那个 8192 的上限。
• 摘要必须严格变短；图片输出是被拒绝而不是丢弃。
• 压缩刻意复用温缓存前缀：那条指令是最后一条 user 消息，而不是一个 summarizer 的 system prompt。
• 一个孤儿的 compaction/start 就是预期的崩溃信号，不是 bug。

subagent 是全仓唯一带命名多 provider 注册表的能力接缝。同一个接口后面可以是：进程内新子代理、完成前缀 fork、独立进程的 dsh SDK runtime、甚至委派给 Codex 或 Claude Code 的一个 turn。

两个轴不要混：providerName vs toolName

子代理的结果怎么回到父代理

关键认知：子代理的会话事件从不进入父代理的模型上下文。存在的是四个独立的观察平面和七条有界通道，而不是「事件流上浮」。

• report 是每个 child 单独安装的，不是全局注册——所以它能存活于全局 toolFilter 之外，但必须在 host 平面恰好注册一次（重复注册会 throw）。
• report 的接受不等于投递；一次失败的 report 调用仍可能已经到达。
• send_message 永远无法操纵正在飞行中的工作；list_agents 的 depth-1 就是 send_message 的作用前沿。
• interrupt() 的权限刻意比投递更宽，且是 fire-and-return，只停当前 turn。
• list_agents 是投影支撑的读取，三级服务阶梯 + 一个 null 哨兵，不加载任何 Agent、不需要查询服务。注意它的模型词汇是服务词汇的精化：ready 意思是可恢复，不是「完成了」。

workflow / ralph / goal

DSH_TOOLS_MODE 选进程级的工具呈现方式：native（默认）/ code / both。任何其它值在启动时失败——包括空字符串，且大小写敏感。

安全性不打折

嵌套调用重新进入完整的受控管线：沙箱、审批、guard、事件全都照常。而且塌缩是在执行器里强制的，不是靠 schema 省略：模型若直接点名一个 native 工具，会在策略之前就得到 UNKNOWN_TOOL。升权在 Code Mode 里同样可用，字段以 TypeScript 可选属性出现。

并发的真相（和一个让人失望的数字）

• 提交顺序的启动保证 + maxParallelSubCalls + 「函数体必须并发安全」规则。
• 并发安全的工具只有 8 个——对一个 coding agent 来说，Promise.all 基本什么也没帮上。
• 一条单车道 driver 拥有所有有序阶段：程序里一次审批提示会冻结其它所有 sub-call 的启动与提交。
• 分类在启动时重新读取，不是提交时——一次注册表变更能把已排队的调用翻成独占。
• run_code 自身在 native loop 里是独占的，所以 both 模式永不让两个程序重叠。

# 离线看组合（但不能确认 mode）
DSH_TOOLS_MODE=code node apps/cli/lib/bin.js --profile headless --dump-config
# 跑一次后从日志确认（真相在这里）
~/.claude/skills/dsh/scripts/dsh-log.mjs --workspace DIR --view tools

如果你在用 Claude Code，这一章最实用：两边的 skill 格式几乎一样，但 dsh 的校验严得多，会静默丢掉你一大批 skill。

五个默认根，以及两个不是根的 rank

~/.claude/skills 不在其中——源码与实测双重确认（那里有 147 个目录，零个进入目录）。项目根检测只认 .git。

# 让 dsh 看见 Claude Code 的 skill（rank 300）
- id: skill-filesystem
  config:
    providerName: filesystem
    includeDefaultRoots: true
    customSkillDirs:
      - !!js (process.env.HOME ?? process.env.USERPROFILE) + '/.claude/skills'
      - !!js process.cwd() + '/.claude/skills'
    watch: true

# 用真实会话日志做 ground truth，逐条报出被丢的原因（含精确 YAML 错误）
~/.claude/skills/dsh/scripts/dsh-run.sh --keep-skills -w /tmp/probe "Reply: ok"
~/.claude/skills/dsh/scripts/dsh-skills-audit.mjs --workspace /tmp/probe

出货的命令：六个，且文档里的名字是错的

命令派发完全不经过模型，并记两个 log-only 事件（command/run + command/done）。

还有一个文档里没写的用户手势

/name 可以出现在消息的任何位置（以空白为界），这是 disable-model-invocation: true 的 skill 唯一的门。

最反直觉的一件事先说：浏览器里也挂了一个 vendored Cordis Loader，客户端的组合完全由宿主推来的图决定，外壳自己不做任何组合决策。

两阶段启动

• window.__DSH_BOOT__ 是宿主推送的入口图——Node 与浏览器两半之间唯一的 wire 源。它被解析成两个视图，其中 inject 边只是信息性的（有一条边甚至指向一个非 row）。
• immediately 层是硬屏障，不是提示；但单行的 prefetch 失败是刻意被吞掉的。
• settle 门是在补偿 cordis 没有 inject 超时——assertEntriesActive() 是唯一的响亮失败点。
• 有两个 entry 是外壳注入的、不是宿主图的行，遍历时必须跳过 MODULES_ID。
• HMR 的重载序列有一个承重的顺序陷阱：registry.delete 必须在 fiber dispose 之前。
• 启动图里可能包含 --dump-config 里没有的行（directory-picker-auto 在运行时挂一个）。

Typert API Gateway 与浏览器信任围栏

• @Remote / @RemoteScope 决定哪些方法过 wire。构建期为每个贡献包生成五个文件，写到 lib/ 而不是 src/。
• TypertLookupMap 让一个 Agent 参数变成 wire 上的 agentId 字段。
• 单一 /api 路由跑在 Connection RPC 之上，带一个「path 必须等于 method」的防混淆检查；Gateway 只认两段式端点。
• 围栏的主锚是 Host 头，不是 Origin（实测：Host 必填、无 marker 捷径，Origin 可选，跨站被拒）。
• 围栏里还有第二道更严的围栏：PRIVILEGED_METHODS（16 个）通过用空信任列表调用同一个函数，被钉在 loopback。
• 围栏只守 /api：index.html 和启动清单对任何 Host 头都提供。events.mux/events.host 是纯 WebSocket，GET 返回 426，没有 SSE 兜底。

node apps/cli/lib/bin.js web --port 3096 &
sleep 10
curl -s -o /dev/null -w "index:%{http_code}\n" http://127.0.0.1:3096/
curl -s -o /dev/null -w "api:%{http_code}\n"   http://127.0.0.1:3096/api
curl -s -o /dev/null -w "mux:%{http_code}\n"   http://127.0.0.1:3096/events.mux
kill %1

四条路都驱动同一棵组合好的插件树。差别只在：轮数、谁决定沙箱、你必须装什么。

copy-paste：TypeScript

import { DeepSeekHarness } from '@deepseek-ai/dsh-sdk-client'

await using harness = new DeepSeekHarness({
  launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
  provider: 'deepseek-official',
  model: 'deepseek-v4-flash',
  maxTokens: 49_152,
  cwd: '/abs/workspace',
})
const a = await harness.run('第一步', { sessionId: 's1' })
const b = await harness.run('接着上一步', { sessionId: 's1' })  // 复用同一会话
console.log(b.finalResponse)

close()（或 await using）是必须的，它走一条四级阶梯：协议 shutdown → stdin EOF → SIGTERM → SIGKILL，三个各自独立默认的计时器，Windows 跳过 SIGTERM，只有在进程真的退出后才 resolve。

copy-paste：Python（零配置）

python -m pip install deepseek-harness-sdk   # import 名仍是 deepseek_harness

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(cwd="/abs/workspace", session_root="/abs/sessions") as h:
    r = h.run("修好失败的测试", session_id="task-001")
print(r.final_response, r.finish_reason)

ACP：唯一能按轮回答权限的接口

• session/new 带一个每会话的绝对 cwd——这就是它的多租户全部故事；additionalDirectories 或 mcpServers 非空会被拒。
• session/request_permission 只提供两个一次性选项（allow_once/reject_once），其它任何情况失败关闭。
• stopReason 不是 prompt 的结果：触到 token 上限也 settle 成 end_turn，被丢弃的准入 settle 成 cancelled。
• 生命周期：一个被记忆化的 teardown，由客户端断连和 Cordis 释放共享，作用域限于本连接自己的 agent。

这一章是整个架构的导航底座。一个能力接缝有三个角色，缺一不成缝：Service Definition 声明接口、Service Provider 实现它、Consumer 使用它（通常是一个模型可见的工具）。给 dsh 加一个能力，意味着三个都要设计。

接缝目录（按 ctx 键）

事件：三个域，五种模式

词汇是生成并守卫的：KNOWN_SESSION_EVENT_TYPES 是一份生成的 44 项白名单，磁盘拒绝按词汇判定而不仅按版本。事件 JSDoc 必须带 @mode，生成的目录会把声明与实际 dispatch 点对账。

这一章来自 4 篇正式 postmortem + 154 篇 bug-fix 笔记 + docs/defensive-patterns.md。每一条都是真的发生过的缺陷，不是理论风险。

八条防御性规则（每一条都对应一个出过货或差点出货的缺陷）

十个最值得记住的具体陷阱

一个成熟项目最有价值的部分，常常是它刻意不做的那些事。dsh 把这些记在 .agents/notes/rejected/，并配了一条硬规矩。

被明确否决的提案（部分）

十一条「删除法则」（简化笔记里反复出现的判据）

1. 要有当前的 owner 和当前的需求——带牙齿的 YAGNI。
2. 绝不广告一个没有任何路径履行的能力。
3. 一个 owner、一条路径、一种表示。
4. 兜底层只为「OS 提供且可能缺失」的工具而存在。
5. 没有兼容 shim、没有迁移、没有墓碑——预发布立场。
6. 呈现、外框、遥测都不是日志的职责。
7. 一个 turn 意味着一次模型循环执行；不要为了记账合成一个 turn。
8. 把可观察的机器收缩到「每个扩展职责一个边界」。
9. 在出 v1 之前删掉新功能里投机的那一半。
10. 不要拥有第二个生命周期，如果包管理器或 OS 已经拥有它。
11. 能力边界：策略从 provider 里拿出来，模型可见概念从存储里拿出来。

两个防止「简化变成破坏」的配重：每篇删除笔记都必须写「Alternatives considered」，并且每个删除都要写清自己的「返程票」（reintroduction condition）。

dsh 明确禁止的反模式

测试：你的改动需要什么证据

硬规矩：每一个非平凡的、模型可见或用户可见的行为变更，都必须在同一个 PR 里通过一个真实可运行的 example 增加或更新一份无 key 快照。包测试、只在 e2e 里的断言、纯 mock 的 fixture 都不能替代那份组装好的应用转写。fixture 必须在 macOS 和 Linux 上都能重放——修 fixture，不要修 normalizer。

还有一条容易忽略的：测试通过 tsconfig.base.json 的 paths 解析源码平面，因为一份过期的 lib/ 会加载模块单例的第二份副本。e2e 测试自己拥有资源（在测试里创建、在 afterEach 里释放，即使失败/重试/超时；绝不 import 另一个 *.e2e.ts——那会重复注册它的 describe 并重复真实 API 调用）。

这一章可以单独打印。命令、环境变量、术语、以及一条按天推进的路径。

装好并跑起来（本机实测过的完整序列）

# ① 方案 A：npm，不需要 checkout。除多轮 SDK 外一切可用
npx -y @deepseek-ai/dsh --version
npx -y @deepseek-ai/dsh web

# ② 方案 B：源码 checkout（推荐 —— 多轮只能走这条）
git clone https://github.com/deepseek-ai/deepseek-harness.git && cd deepseek-harness
CI=true pnpm install         # CI=true 是这台机器的硬性前提，见下方警告
CI=true pnpm run build

# ③ 验证（都不发模型请求，不花钱）
node apps/cli/lib/bin.js --help
node apps/cli/lib/bin.js --profile headless --dump-config | grep -c '^- id:'   # 期望 81
ls apps/web/dist/index.html
CI=true pnpm exec vitest run packages/bundle/headless

# ④ 用起来
node apps/cli/lib/bin.js --profile headless "run the tests and fix what fails"
node apps/cli/lib/bin.js web --port 3080

环境变量（harness 读 的那些）

术语卡

最佳实践（可复制为 prompt 喂给任何 AI）

行动清单

scripts/dsh-run.sh          # 一次性委派；stdout 只有答案，可管道
scripts/dsh-session.mjs     # 多轮共享会话（带沙箱的组合）
scripts/dsh-log.mjs         # 会话日志阅读器，7 种视图，无 zstd CLI 也能跑
scripts/dsh-skills-audit.mjs # 用真实日志做 ground truth 审计 skill 掉落
assets/lean.patch.yml       # 关掉 skill 目录的三行 patch
assets/share-claude-skills.patch.yml  # 让 dsh 读 ~/.claude/skills