<站名>

第0章 零基础起步：一个 agent 到底是什么

这一章回答一个问题：当别人说「我写了个 agent」，他到底写了什么？答案会让很多人失望——他写的那部分，基本没有 AI。

0.1 先说清楚：没有 agent 的时候，人是怎么干活的

假设你想让 AI 帮你把电脑里一个叫 report.txt 的文件改一下。2023 年你会这么干：打开聊天窗口，手动把文件内容复制进去，问它该怎么改，它给你一段新文字，你再手动复制回文件里。中间每一次「复制、粘贴、切窗口」，都是你在当搬运工。

你会发现你干的活其实特别机械：把外面世界的东西喂给模型，再把模型说的话拿到外面世界去执行。既然机械，就能写成程序。这个程序就是 agent 的全部。

agent（智能体）：一个能自己循环调用模型、并且能真的动手（读写文件、执行命令、访问网络）的程序。它不是一个模型，是一个围着模型转的程序。

harness（智能体运行框架）：承载 agent 的那一层框架。DeepSeek Harness 的 README 第一句就是这么自我介绍的（README.zh.md）：一个开源的 agent harness。harness 这个词本站不翻译——中文里没有一个不别扭的对应词，「框架」太泛，「外壳」又太轻。你可以先把它理解成：模型是马，harness 是马身上那套挽具。

0.2 大语言模型：一个吃文字吐文字的函数，而且它没有记忆

要理解后面所有东西，你只需要接受一个极度简化但基本正确的模型图像：

「没有记忆」这四个字，是这一章、也是这个站最重要的一句话，所以要讲透。

你在聊天软件里跟 AI 连聊十轮，感觉它记得你说过什么。真相是：你的聊天软件在第十轮时，把前面九轮的全部内容重新发了一遍。模型这一侧根本不知道有「第十轮」这回事，它只是收到了一大段文字（里面碰巧包含了九轮对话的抄本），然后续写了一段。

注意式 0-1 右边的括号里：第 n 轮的输入，包含了前面所有轮的输入和输出。这就是「没有记忆」的精确写法。所谓记忆，是括号里那一长串东西——而那一长串东西，是你的程序负责保存和重发的，不是模型。

这一条会在后面变成两整章。第一，既然对话要整段重发，那这份「整段」必须被完整、可靠地存下来——那就是会话日志（session log）。DeepSeek Harness 把这条写成了一条运行时不变量，原话是「模型可见即已记录」（docs/architecture.zh.md）：任何抵达模型请求的东西，都必须能从日志重建。第二，既然要整段重发、而单次长度有上限，那对话总有一天塞不下——那就是压缩（compaction）。

0.3 token：为什么按字算钱，为什么装不下

模型不是按「字」处理文字的，它按 token 处理。

token（不译）：模型把一段文字切碎之后的最小单位。英文里一个常见单词大致是 1 个 token，长单词会被切成两三个；中文里一个汉字大致是 0.5 到 1 个 token 之间。切法由模型自带的一张词表决定，不同厂商的切法不一样。

给你几个尺度感（下面这组换算是粗略量级，不同模型差 20% 很正常）：

那么单次上限到底是多少？这个数不在仓库里。DeepSeek Harness 把它做成了模型目录里的一个可选字段 contextWindow（见 packages/llm/llm-deepseek/src/index.ts，字段注释写的是「已知的请求／响应合计上下文容量；部署元数据不可用时省略」）。也就是说，harness 自己不假定这个数，它由你接的那个模型告诉它。现实中的量级从几万到几十万 token 都有。

有意思的是，DeepSeek Harness 自己也不精确数 token。它在 packages/llm/token-meter/src/estimate.ts 里写死了一个常数：

/** Fixed text-density estimate used until exact tokenization is needed. */
const CHARS_PER_TOKEN = 4

/** Per-block structural overhead for JSON framing and type tags. */
const BLOCK_OVERHEAD = 4

四个字符算一个 token，每个内容块再加 4 个 token 的结构开销。这是一个故意粗糙的估计：它只用在「还没有真实用量数据时」的兜底上，一旦提供方返回了真实的 usage 数字，harness 就改用真实值当锚点（docs/subsystems/token-meter.zh.md）。

顺便，这条常数对中文是系统性低估的：4 个汉字算 1 个 token，而实际大约是 1 到 2 个汉字就 1 个 token。所以用中文跑这个 harness 时，它对压力的估计会偏乐观。仓库没有讨论这一点，这是本站读源码时注意到的。

现在把 0.2 和 0.3 拼起来，会得到一个不太好的结论。假设每一轮对话新增的内容量差不多是常数 c，因为每轮都要把之前的全部重发一遍，那么聊到第 n 轮为止，你累计发送的总量是：

关键是 n²：轮数翻一倍，花的钱变四倍。10 轮对话的成本是 1 轮的 55 倍，而不是 10 倍。这就是为什么 agent 跑长任务时账单会突然失控，也是为什么后面会有一整章专门讲怎么把历史剪短。

0.4 工具调用：全站的地基

到这里为止，模型还是只会说话。让它能动手的那个机制叫工具调用（tool call）。这一节是整个站的地基，请慢读。

很多人第一次听到「模型可以调用工具」，脑子里的图像是：模型内部长了一双手，能伸出来碰文件。这是错的，而且错得很重要。真实的机制是这样四步：

1. 你在发请求的时候，除了对话内容，还附上一张工具清单：每个工具叫什么名字、干什么用、需要哪些参数。这张清单本身也是文字，也占 token。
2. 模型读完，如果它觉得该动手，就吐出一段结构化的文字，大意是「我要调用 read_file，参数是 {path: 'report.txt'}」。注意：它只是说了这句话，什么都没发生。
3. 你的程序解析这段文字，发现是个工具调用请求，于是真的去打开那个文件、读出来。这一步是纯粹的普通编程，一点 AI 都没有。
4. 你的程序把读到的内容包成一条新消息，接在对话后面，然后把整段对话再发一次给模型（回到式 0-1）。模型这才「看到」文件内容。

这不是本站的比喻，是仓库里的类型定义。packages/llm/llm/src/types.ts 里，一条消息由若干「内容块」组成，块的种类是这样一张表（docs/subsystems/llm-streaming.zh.md 摘录）：

interface ContentBlockMap {
  'text': TextBlock
  'reasoning': ReasoningBlock
  'image': ImageBlock
  'tool-call': ToolCallBlock
  'tool-result': ToolResultBlock
}

其中 ToolCallBlock 带三个字段：一个调用 id、一个工具名 name、一串原始 JSON 文本 arguments。ToolResultBlock 带一个 toolCallId（配对用）、嵌套的结果内容和一个 isError 标记。它们都只是消息里的文字块——模型产出前者，你的程序产出后者。

而「真的去执行」那一步，在仓库里长这样（packages/core/tools/src/index.ts，注释已简化）：

interface ToolDefinition extends ToolSchema {
  /** 跑一次被接受的调用，只返回它的规范 JSON 值。 */
  execute(args: unknown, exec: ToolRunContext): Promise<unknown>
}

一个普通的 execute 函数，参数是模型给的 JSON，返回值是普通的 JSON。里面写的是 fs.readFile 这种最普通不过的代码。DeepSeek Harness 一共注册了 52 个这样的工具，名字都很朴素：bash、read、write、edit、glob、grep、web_search、todo_write……

0.5 JavaScript 最小够用集

DeepSeek Harness 是用 TypeScript 写的（TypeScript 就是加了类型标注的 JavaScript）。你不需要会写，但要看得懂后面章节里的代码片段。这一节只讲六样东西。

对象：一袋带名字的东西

const call = {
  id: 'call_001',
  name: 'read',
  arguments: '{"path":"report.txt"}'
}

call.name        // 'read'

大括号里是若干「名字: 值」。取值用点。上面这个恰好就是一个 ToolCallBlock 的样子。

数组：一排有顺序的东西

const messages = []
messages.push({ role: 'user', text: '你好' })
messages.length   // 1

整段对话在程序里就是这么一个数组。式 0-1 括号里那一长串，落到代码里就是 messages。

函数：一段能被叫起来的代码

function add(a, b) { return a + b }
const add2 = (a, b) => a + b      // 同一件事的简写，叫箭头函数

async / await：为什么要等

有些事情是要花时间的：向模型发一次请求要几秒，读一个大文件要几十毫秒。JavaScript 遇到这类事情不会傻等——它会先记下「这件事在办」，然后继续跑后面的代码。

async function step(messages) {          // 函数里要用 await，函数自己得标 async
  const reply = await callModel(messages)  // 在这儿停住，等模型答完
  return reply                             // 拿到真东西才往下走
}

回调：把一段代码交给别人，让别人替你在合适的时候跑

function onEachTool(calls, handle) {   // handle 是别人传进来的一段代码
  for (const c of calls) handle(c)     // 我不知道它要干什么，我只负责在对的时候叫它
}

onEachTool(reply.toolCalls, (c) => console.log('模型想调用', c.name))

这个想法后面会被放大成整个架构：DeepSeek Harness 里所有的扩展，本质上都是「把一段代码交给框架，让框架在某个时刻替你跑」。

事件：on 和 emit

ctx.on('tool/call', (call) => {         // 订阅：我关心这件事
  console.log('有人要调用', call.name)
})

ctx.emit('tool/call', someCall)          // 广播：这件事发生了

仓库里 56 个事件，全都是这套写法。举一个真实的例子（packages/todo/tool-todo/src/index.ts，删去了类型标注和长文本）：

export const name = 'tool-todo'
export const inject = ['tools']

export function apply(ctx, config) {
  ctx.tools.register(defineTool({
    name: 'todo_write',
    description: '记录并更新当前工作的结构化任务列表……',
    parameters: { todos: { type: 'array', required: true, /* … */ } },
    async execute(args, exec) { /* 真正干活的地方 */ },
  }))
}

整个插件就是两样东西：一行 inject 声明「我需要什么」，一个 apply 函数说明「给我上下文，我就去注册点东西」。这就是所谓「一切皆插件」在代码上的样子——第 1 章会展开讲它的代价。

0.6 依赖：为什么「谁先启动」会变成一个问题

「依赖」这个词的意思很朴素：A 要用 B 提供的东西，那就说 A 依赖 B。

问题出在启动顺序上。如果 A 在启动的时候就要用 B，那 B 必须先准备好。两个模块时你手写顺序就行；三个五个还行；219 个的时候，手写启动顺序是不可能完成的任务——你改一个模块的依赖，可能要重排整张表，而且漏了不会立刻报错，只会在某个罕见路径上炸。

DeepSeek Harness 底下那个框架 Cordis 的做法是：不排顺序，只声明依赖。docs/cordis-primer.zh.md 的原话是「插件声明所需的服务后，会等待这些服务就绪才启动；加载顺序通过服务依赖表达，而非手动编排启动序列」。

落到代码上就是那一行 export const inject = [...]。看几个真实的声明：

看第一行：那个「agent 循环」——也就是你马上要写的 20 行的真身——需要六项服务才能启动。框架会自己算出：先起 session，再起 tools（因为 tools 需要 sessions），再起 agent-loop。你不用管。

0.7 状态机：几个格子，加上格子之间的箭头

最后一个前置概念。状态机（state machine）的定义简单到有点可疑：一样东西在任何时刻处于有限个状态中的某一个，并且只能沿着规定好的箭头从一个状态转到另一个。

不用编例子，仓库里就有一个。Cordis 里管理一个插件实例的东西叫 fiber（不译；它是「一个已加载插件实例的运行时句柄」）。它的状态在 vendor/cordis/src/fiber.ts 里明明白白写着六个：

export const enum FiberState {
  PENDING,     // 在等依赖，还没开始
  LOADING,     // 正在启动
  ACTIVE,      // 跑着呢
  FAILED,      // 起崩了
  DISPOSED,    // 被拿掉了，回不来了
  UNLOADING,   // 正在拆
}

对照 0.6 节那个「P2 永远停在等待」的例子——它就是卡在 PENDING。PENDING 和 FAILED 是两件完全不同的事：前者是「条件还没满足，条件满足了我就起」，后者是「我试过了，我起不来」。如果只用一个 isBroken 布尔值，这两件事就混成一件，你永远搞不清该去装个依赖还是该去修个 bug。

第1章 全景：那 20 行为什么变成了 20 万行

你刚写完一个能跑的 agent，感觉没什么难的。这一章的任务是把那 20 行放进真实世界里，然后一条一条告诉你它会怎么死。

1.1 九种死法：把你那 20 行放进真实世界

先把靶子摆好。第 0 章末尾那个循环，干净利落：发请求、执行工具、塞回结果、再发一次。它在你的笔记本上、对着一个小任务，能跑。

下面九个场景，每一个都足以让它当场报废。请注意：没有一个跟模型聪不聪明有关。

死法一：对话越来越长，直到发不出去

你让它改一个中等大小的项目。它读了 package.json、读了三个源文件、跑了一次测试（输出 200 行）、又读了两个文件。第 9 次请求发出去，服务端返回一个错误：输入超长。你的循环在 await 那一行抛异常退出。更糟的是——你重新跑一遍，它对刚才做过的一切一无所知，从头再来一遍，然后在同一个地方再死一次。

这一条第 0 章已经算过账了（式 0-2，平方增长）。解药：上下文压缩，第 12 章。那一章会让你看到，压缩不是「删掉旧消息」这么简单——删哪些、什么时候删、删了之后模型会不会重新去读同一个文件，每一条都是取舍。

死法二：模型中途改主意

它说：「我先读 a.ts，然后改 b.ts。」读完 a.ts，它发现里面写着「b.ts 已废弃，请改 c.ts」。于是它转头去改 c.ts。这本身没问题，循环本来就允许它一步步来。

问题出在你想给这件事划边界的时候。用户此刻插了一句「等等，先别改」——这句话应该接在当前这一串动作里，还是另起一段新对话？你的 20 行循环里没有「一串动作」这个概念，只有一次次请求。所以你无处安放这句话。

DeepSeek Harness 把这件事切成两层：一个步骤（step）是一次模型请求加上它调用的工具；一个轮次（turn）包含零个或多个步骤，它在领取第一条输入之前打开，在不再欠下任何工作时关闭（docs/architecture.zh.md）。解药：轮次与步骤，第 7 章（「循环 · Agent 的心脏」那一组）。

死法三：工具跑到一半，用户想停

模型调了 bash npm install。跑到第 40 秒你发现它装错了包，按 Ctrl+C。

你的 20 行版本会发生什么？Ctrl+C 杀掉整个 Node 进程。messages 数组在内存里，没了。npm install 那个子进程可能还活着，变成孤儿继续往 node_modules 里写东西。下次你启动，看到一个被写了一半的目录，而且完全不知道刚才发生过什么。

「停止」不是一个瞬间动作——这一点第 0 章的 q0-8 已经埋过了。真实系统需要：一个能传下去的取消信号、一个「已经喊停但还没停干净」的中间状态、以及一条规矩说明还没开始的工作要不要保留。DeepSeek Harness 的 Agent 句柄上就有个 cancel(cause, options)，其中 keepInbox 决定排队中的工作是一起丢掉还是留着（docs/subsystems/core.zh.md）。

解药：取消与错误恢复，同样在第 7 章。

死法四：两个工具同时改一个文件

模型一次回复里发了两个工具调用，都是编辑 config.json。你为了快，并发执行。两个都读到了同一份旧内容，各自改各自的那行，后写的把先写的覆盖掉。两个工具都返回 ok，模型以为两处都改成功了，接着往下做。

这是最阴险的一类失败：没有任何一处报错。程序继续运行，只是结果是错的。DeepSeek Harness 的处理方式是让工具自己声明能不能并发——ToolDefinition 上有个 isConcurrencySafe(args) 方法（docs/subsystems/tools.zh.md），注意它接收参数：同一个工具，改不同文件时可以并发，改同一个文件时不行。

解药：工具执行流水线，第 9 章；并发调度在第 12–15 章那一组「规模 · 让它撑得住」。

死法五：模型要求删掉整个磁盘

不用想象一个恶意模型。真实场景通常是这样：模型想清理构建产物，生成了 rm -rf $BUILD_DIR/*，而 BUILD_DIR 这个变量恰好是空的。于是命令变成 rm -rf /*。

你的 20 行版本会老老实实执行它。第 0 章讲过：模型只是输出了一段文字，是你的程序去执行的，所以责任在你的程序。

DeepSeek Harness 在「模型说要调用」和「真的执行」之间塞了一整条流水线：先跑 tools/pre-execute（钩子、权限、沙箱），再跑注册的单调守卫（monotonic guard），然后才是 tools/execute（docs/tool-execution-pipeline.zh.md）。守卫有一条奇怪的规矩：只许否决，不许放行。为什么要这么设计，第 10 章会让你把它拆掉，亲眼看越权发生。

解药：守卫与审批，第 10 章。

死法六：要换一家模型厂商

你的 callModel 里写死了：某家的接口地址、某家的鉴权头、某家的流式响应格式、某家的 tool-call 字段名。现在要换一家。你全文搜索改一遍——改完之后，原来那家跑不了了。要两家都支持？那就在 callModel 里加 if。三家呢？五家呢？再加一个「A 家超时就自动切 B 家」的需求呢？

DeepSeek Harness 把「跟模型说话」这件事变成了一个可替换的接缝：ctx.llm 定义词汇和适配器接口，llm-deepseek、llm-pi-ai、llm-mock-server、llm-replay 是并列的提供方，还有一个 llm-retry 专门管重试。换厂商是改配置，不是改代码。

解药：Cordis 的服务与注入，第 2 章起的那一组；能力 seam 的完整讲法在第 9–11 章那一组。

死法七：要在别人的机器上跑

你想让 agent 在一个云端沙箱里干活，别碰你的笔记本。可你的工具实现里写的是 fs.readFileSync——它硬编码了「文件系统就是本机文件系统」这个假设。bash 工具也一样，它直接 spawn 了本机进程。

DeepSeek Harness 对这件事的说法很值得记住（docs/architecture.zh.md 原话）：文件系统与进程提供方共享同一个执行世界，因此把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需提供方专用 fork。仓库里 fs-local 和 fs-e2b 是同一个接口的两个实现，subprocess-e2b 同理。

解药：能力 seam，第 9–11 章那一组。

死法八：崩了之后没法恢复现场

跑了 40 分钟，笔记本睡眠了，进程没了。messages 是个内存里的数组，它跟着进程一起消失。你损失的不只是时间——你损失的是「它到底做过哪些改动」这个信息，而工作区里的文件已经被改了一半。

DeepSeek Harness 的答案是把对话变成一份仅追加的事件日志：每一件事都是一条 SessionEvent，日志是模型所见上下文的唯一来源，模型历史是从日志投影出来的（docs/architecture.zh.md）。有了日志，恢复、fork、回放、遥测就全都是同一份数据的不同读法。仓库里光是 session 这一组就有 13 个包，两种持久化后端（JSONL 和 SQLite）。

解药：会话日志，第 6 章；持久化与恢复在第 12–15 章那一组。

死法九：想加个新功能，得改核心循环

这一条最不起眼，但它是前面八条的公因数。

你想加一个小功能：每次工具调用前，往公司的监控系统打一条日志。你只能改循环体。第二个人想加「工具超时就中断」，也改循环体。第三个人想加「某些工具需要人工确认」，还是改循环体。三个月后，那个 20 行的循环变成 300 行，里面缠着监控、超时、审批、重试、压缩，谁都不敢动，因为改一处会莫名其妙影响另一处。

DeepSeek Harness 把这件事写成了一条硬规矩（AGENTS.md）：新行为放在插件里，不改循环；确实要改 agent-loop 的话，必须同时更新架构文档。这条规矩换来的东西就是下一节的主题。

解药：一切皆插件，第 2–5 章那一组「Cordis · 把一切变成插件」。

1.2 DeepSeek Harness 有多大

DeepSeek Harness（命令行叫 dsh）是 DeepSeek AI 开源的 agent harness，MIT 许可证。它自己的一句话介绍是：采用一切皆插件的架构，由 Cordis 驱动（README.zh.md）。

本站依据的是 commit 47f9438（2026-08-13）。下面这些数字是从那个 commit 现场数出来的：

现在把它跟你的 20 行放一起比。198,402 ÷ 20 ≈ 一万倍。

但这个比法有点耍赖，因为那 20 万行里绝大部分不是循环。真正对应你那个循环的包叫 packages/core/agent-loop，它有 1,643 行——是你那 20 行的 95 倍，占全仓的 0.89%。

换句话说：agent 的「心脏」只占不到百分之一，剩下 99% 都是围着它的那些事。这个比例本身就是这个站要讲的东西。

上面那张图是从各个包的 package.json 里现抽出来的真实依赖关系，不是示意图。转两下你会注意到几件事：有几个节点被特别多的箭头指着（那是枢纽，比如 invariants、session、tools）；边上有一大圈几乎没人依赖的叶子（那多半是某个具体的提供方或某个工具）；整张图没有环——不然按第 0 章讲的依赖解析，成环的那几个包谁都启动不了。

最后一行值得停一下。很多人以为 agent 系统的难点在算法，实际上这个仓库里最大的一块是界面——因为要把一个会自己动手的东西的行为，实时、可理解地摊给人看，本身就是件难事。

1.3 「一切皆插件」到底在说什么，以及它的代价

这句话在 README.zh.md 和 AGENTS.md 里都是加粗的。它的意思比字面激进得多。

docs/architecture.zh.md 是这么解释的：插件向共享上下文贡献服务、类型化事件和可逆的副作用；产品的每一部分都是插件，包括模型适配器、工具注册表、会话日志，以及 agent loop 本身，因此每一部分都可以从配置替换。紧接着一句更狠的：不存在需要打补丁的特权内核。

把这两句翻译成人话：这个系统没有主程序。你在 packages/ 下找不到一个「一切从这里开始」的 main()。启动时发生的事情是——按配置把一堆插件挂到一棵树上，它们各自声明需要什么、提供什么，框架算出顺序，然后一切自己长起来。

连那个 agent 循环也不例外。core/agent 定义了 Agent 接口，core/agent-loop 只是「实现该接口的默认驱动器」（docs/architecture.zh.md 的表格里就是这么写的）。你可以写一个自己的驱动器把它换掉，配置里改一行。

具体怎么组装？docs/architecture.zh.md 说：运行中的 dsh 是一棵插件树，由启动时按序叠加的各层组合而成。

profile（profile）：一份具名的组装方案，它列出自己叠放哪些组合包。仓库随发行版交付两个模板：web（带浏览器界面）和 headless（一次性运行器，完全不带服务器）。

组合包（bundle）：Cordis 配置项及其挂载代码的分发格式。dsh-base 是每个 profile 的第一层——模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测都在里面。

各层的叠加顺序是明确的：先按 profile 列出的顺序应用每个组合包，然后是 profile 自己的 cordis.patch.yml，然后是 home 级的那份，最后是命令行给的 --patch。一条 patch 按 id 定位某个条目，替换它整个 config，或者插入一个新条目。

所以「从配置替换」不是一句漂亮话，它是一套有明确优先级的覆盖机制。想知道你的机器实际启动了什么，仓库给了一条命令：

dsh --profile web --dump-config

文档紧跟着一句：它打印出的任何条目，都可以由你自己的 patch 替换。

那么代价是什么

这一段仓库没写。下面是本站读完源码之后的判断。

代价一：没有主函数，就没有入口。读一个传统程序，你从 main() 往下读。读这个仓库，你从哪读？答案是没有「从哪读」，只有「你想知道什么」。这就是为什么仓库自己在 docs/architecture.zh.md 里建议：建议使用 agent 探索代码库并理解其架构——一个 20 万行、没有单一入口的代码库，作者自己也认为人力顺序阅读不是好办法。

代价二：一个功能散在三个包里。仓库把「可替换能力」正式化成了一个叫 seam（本站译「能力 seam」，seam 不译，意思是「可替换能力的接缝」）的东西，它规定必须有三种角色：声明接口的 Service Definition、实现它的 Service Provider、使用它的 Consumer（docs/glossary.zh.md）。范例是 shell 这一组：dsh-shell（定义）、dsh-bash-local / dsh-bash-sandbox（两个提供方）、dsh-tool-bash（消费方）。

好处是替换提供方就能改变整个产品。代价是：你想搞清「模型执行一条 bash 命令时到底发生了什么」，得同时打开四个包。而且术语表明确写着seam 是完整能力，绝不是其中一个角色——也就是说，理解其中任何一个包，都不等于理解这项能力。

代价三：启动失败从「崩溃」变成「静默地什么都没发生」。第 0 章 q0-7 已经演示过：一个插件缺依赖，它不会报错，它会安安静静停在 PENDING。219 个包互相声明依赖时，这类问题的排查方式跟传统程序完全不同——你不是去看堆栈，是去 --dump-config 看树。

代价四：抽象本身要花钱。Cordis 内核 2,693 行、事件系统 56 个事件、seam 三角色的样板、每个注册都要配一个释放函数……这些代码不实现任何用户能看见的功能，它们只是为了让别的代码能被替换。如果你只是要写一个自己用的脚本，这笔钱不值得花。这不是黑话——判断一套架构值不值，就是在判断「未来要替换的次数」乘以「每次替换省下的工夫」，够不够抵消这笔固定开销。

1.4 本站怎么用：五个模式

这一节看着像使用说明，但它其实是这个站最重要的一节——因为不知道有这个功能，就等于没有这个功能。

每一章的顶部有一条模式切换栏，五个模式。它们不是五种排版，是五种不同的学习动作。

另外三件事，也是不知道就等于没有的：

提示是阶梯，请按顺序用。每道题下面有四级提示：第一级只告诉你往哪个方向想，第二级给关键思路，第三级给第一步怎么走，第四级才是完整答案。用到第几级会被记下来，直接影响这道题下次什么时候再问你——一上来就点开第四级，系统会认为你没掌握，很快就会再考你一遍。这不是惩罚，是让复习时间花在真的不会的地方。

选中就能划线。正文里选中一段文字，会浮出一条四色工具条：不懂 / 重要 / 存疑 / 深挖。键盘 1 到 4 直接上色，N 写批注，C 把这段连同上下文打包成一个可以直接粘给任意大模型的提问。划过的东西都汇总在「笔记」页。

两种判分。机判题（选择、排序、数值）机器直接给分；开放题有一个「让 AI 批改」按钮，它把题干、参考答案、评分标准和你的作答一起打包复制走，你粘到任意大模型里，再把分数填回来。进度存在这台设备的浏览器里——顶栏那个小圆点变黄就说明存不了，记得去「进度」页导出。

1.5 证据分级：怎么读一份「我们的设计更好」的技术文档

你正在读的这个站，内容来自一个开源仓库的源码和文档。这里有一个诚实问题必须摊开讲：仓库的文档是它的作者写的。作者会讲自己的设计好在哪，很少会系统地讲它差在哪。这不是不诚实，这是所有技术文档的常态。

所以本站把每一条陈述分成三档，并且在页面上用不同方式标出来。

拿本章和上一章的具体例子对号入座：

• 仓库明文：CHARS_PER_TOKEN = 4（packages/llm/token-meter/src/estimate.ts 里的一行代码）；FiberState 有六个取值；52 个工具、56 个事件、219 个包（这三个是本站数的，但数的是明文事实，可以复现）。
• 作者设计意图：「不存在需要打补丁的特权内核」；「seam 是完整能力，绝不是其中一个角色」；「新行为放在插件里，不改循环」。这些都是作者主张的设计原则——它们说明了作者想要什么，但没有给出对照实验说明这样比别的做法好。
• 本站推断：式 0-2 那个平方增长；1.1 的「九种死法」这个分类；1.3 那四条代价；以及一切以「你可以把它理解成……」开头的比喻。

学会分这三档，你就有了一套读任何技术文档的方法。遇到一份声称「我们的设计更好」的文档，问三个问题：

问题一：它有没有说自己拒绝了什么？一个只讲自己好的设计文档，往往意味着作者没有认真考虑过替代方案，或者考虑过但不想写。DeepSeek Harness 在这一点上部分及格——比如它明确写了「seam 只做一个角色不算 seam」「waterfall 监听器不调 next() 就是短路，而这在单决策事件里是设计意图」，这些都是在划边界。但它没有一处系统讨论「如果不做成插件会怎样」。

问题二：它有没有说代价？1.3 那四条代价，是本站补的，不是仓库给的。你读到任何一份只有收益没有成本的文档，都应该自己把成本那一栏补上——补不出来，说明你还没真懂这个设计。

问题三：这句话是「可验证的事实」还是「我们认为更好」？判据很简单：能不能设计一个实验证伪它。「ToolDefinition 有个 isConcurrencySafe 字段」可以证伪（去看源码）。「一切皆插件的架构更好」不能证伪——「更好」在哪个指标上、对谁而言、多大规模下，一个都没定义。这不是说它错，而是说它属于另一类陈述，不能用读事实的方式去读。

第2章 上下文与服务：为什么不用 import

这一章回答一个几乎每个人第一眼都会问的问题：我要用别的模块的功能，import 一下不就行了？为什么 DeepSeek Harness 的插件之间几乎不互相 import，全都写成 ctx.某个名字？

2.1 先看看只有 import 的世界

假设你已经写好了一个 agent（智能体），它能调用大模型来总结一段文字。你的总结插件里大概会有这么一行：

// 简化示意，不是仓库代码
import { deepseek } from './llm-deepseek.ts'

export async function summarize(text) {
  return deepseek.chat([{ role: 'user', content: '总结：' + text }])
}

这行 import 干了两件事，而它们本来是两件事：第一，声明我需要一个能跟大模型说话的东西；第二，指定这个东西就是 llm-deepseek.ts 里那一个。import 把这两句话焊在了同一行代码里。

焊死的代价，要等你想换实现的时候才会显形。设想下面这个具体场景：你的 harness（智能体运行框架）跑了三个月，有十四个插件调用模型——总结、起标题、压缩历史、给子 agent 分派任务、给工具生成参数……现在公司说，海外用户要走另一家厂商的接口，国内还留在原来的。于是你得把这十四个文件全部打开，把 import { deepseek } 改成某种能二选一的写法。改完，测试全部重跑。下个月又要接第三家，再来一遍。

更难受的是另一半：有些调用在启动时就能定，有些要按用户当前的设置来定。import 是模块加载时就结算完的，它没有「等一下再决定」这个档位。你只能在它之外再手写一层工厂函数、一个全局变量、一张注册表——写着写着，你就在重新发明这一章要讲的东西，只是发明得更糙。

这在 DeepSeek Harness 里是能看见的实物。packages/bundle/base/cordis.patch.yml 是每个部署的第一层配置，里面有这样几行（各行不相邻，我把它们摘到一起）：

- id: llm
  name: '@deepseek-ai/dsh-llm'          # 定义「llm 这个能力长什么样」
- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek' # DeepSeek 原生适配器
- id: llm-pi-ai
  name: '@deepseek-ai/dsh-llm-pi-ai'    # 多厂商适配器

能力的定义和能力的具体实现是三行独立的配置，不是一行 import。想换厂商，改的是这份 YAML，不是那十四个插件。

2.2 上下文：一个装着服务的容器

服务（service）：一个插件对外公开的、有名字的能力。别的插件通过这个名字拿到它，不需要知道它是哪个文件、哪个类实现的。

上下文（context，代码里一律写作 ctx）：装服务的容器。每个插件启动时都会收到一个 ctx，它贡献的一切也都挂在这个 ctx 上。

在 harness 里，ctx.llm 是模型能力，ctx.tools 是工具注册表，ctx.sessions 是会话日志（这三个分别来自 packages/llm/llm、packages/core/tools、packages/core/session，见 docs/architecture.zh.md 的核心包表）。消费方写的是 ctx.llm——它只说了要哪个名字，没说要谁的实现。

谁把服务挂上去的？提供方自己。Cordis 提供了一个 Service 基类，构造函数的第二个参数就是名字（vendor/cordis/src/service.ts）：

import { Service, type Context } from '@deepseek-ai/cordis'

export class GreeterService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'greeter')   // 从这一刻起，别人写 ctx.greeter 就能拿到它
  }

  greet(who: string) {
    return `Hello, ${who}!`
  }
}

这段代码来自 docs/cordis-tutorial/03-services.zh.md。注意 super(ctx, 'greeter') 做的事：它不是把实例存进全局变量，而是向当前上下文登记「名字 greeter 由我提供」。登记本身是可撤销的——第 3 章会讲这为什么至关重要。

2.3 inject：声明依赖，顺序自己会长出来

消费方这样声明自己需要什么：

export const name = 'consumer'
export const inject = ['greeter']

export function apply(ctx: Context) {
  console.log(ctx.greeter.greet('world'))
}

inject 是一个字符串数组，列出这个插件必须拿到的服务名。Cordis 的承诺很硬：apply 被调用时，inject 里的每一个服务都保证已经就绪。在那之前，这个插件一动不动。

真实的 harness 插件长得完全一样。packages/web/tool-web/src/index.ts 里就是一行：

/** Services required by the web tool suite. */
export const inject = ['tools', 'web', 'systemPrompt']

这行代码说的是：我要一个工具注册表、一个网页能力、一个提示词组装器；至于网页能力是谁提供的（仓库里至少有 web-search-exa、web-search-perplexity、web-search-deepseek 三种），我不管，也不想知道。

把两行对调，输出一样

教程第 3 章给的组合是这样：

- name: './greeter.ts'
- name: './consumer.ts'

运行输出 Hello, world!。现在把两行对调，让消费方排在提供方前面，再跑一遍——输出一模一样。我不是照抄文档说的，我把仓库那份 Cordis 打包进浏览器，在两种顺序下各跑了一次，两次都打印 consumer says: Hello, world!。

为什么？因为消费方在 greeter 就绪之前，只是安静地待着；提供方一登记，Cordis 立刻把等着这个名字的插件全部唤醒。决定加载顺序的是依赖关系，不是文件里的行号。

仓库自己把这件事写进了配置文件的注释里。packages/bundle/base/cordis.patch.yml 开头有一句：

# Row order carries no load semantics (activation is service-availability
# driven); the grouping is for readers.
# （行的顺序不携带任何加载语义，激活由服务是否可用驱动；分组只是给人看的。）

2.4 PENDING 是合法状态，不是错误

现在把提供方整个删掉，只留消费方。你觉得会怎样？大部分人的直觉是「报错」，或者至少「打印一条警告」。

都不是。它什么也不会发生：不崩溃，不报错，不输出，也不会只执行一半。这个插件停在一个叫 PENDING 的状态里，安静地等着。

PENDING：已经声明、但所需服务尚不可用的状态。它是六种合法生命周期状态之一（完整状态机是第 3 章的主题），不是错误码。

为什么设计成不报错？因为 Cordis 无法判断这是不是错误。提供方可能三秒后才挂载完，可能由用户在界面上点一下才启用，也可能这次部署压根就不需要这个功能。「现在没有」和「永远不会有」在运行时是分不开的两件事，框架选择不替你猜。

还有一个会把人绕进去的现象：PENDING 的插件不会让 Node 的事件循环保持活跃。所以如果你的组合里没有别的东西在跑，进程会静静地以状态码 0 退出——看起来就像「程序正常结束了」，而实际上你的插件一次都没运行过。

怎么确认它是不是 PENDING

直接去问注册表。每个上下文都能枚举所有已挂载的插件实例，教程第 6 章给了一段可以直接抄的诊断代码：

import { FiberState, type Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  setTimeout(() => {
    for (const runtime of ctx.registry.values()) {
      for (const fiber of runtime.fibers) {
        if (fiber.state === FiberState.PENDING) {
          console.log(`${fiber.name} is PENDING — a required service is missing`)
        }
      }
    }
  }, 500)
}

为什么要包一层 setTimeout？因为挂载是并发的，立刻去查会查到一堆还在加载中的东西。等半秒再看，剩下的 PENDING 才是真的缺东西。

2.5 依赖是一直盯着的，不是启动时查一次

到这里为止，你可能把 inject 理解成了「启动前的一道检查」：查一遍，通过就放行，之后各过各的。不是。

它是持续追踪的。docs/user/develop/framework/service.zh.md 把规则写得很直白：如果运行期间某项必需服务消失（比如它的提供方被卸载了），依赖它的插件会自动卸载；当服务重新出现时，插件自动重新加载。

我把这条规则在浏览器里跑了一遍：挂一个英文版的 greeter 提供方 + 一个消费方，输出 Hello, world!；然后卸掉英文提供方、挂上一个中文版的，消费方没有任何改动，自己重新执行了一次，这回打印的是 你好，world！。它不知道自己被换了实现，也不需要知道。

这条规则解释了一件很重要的事：为什么配置里能换实现。教程原话是——卸载 dsh-bash-local 这个配置项，挂上另一个 shell 提供方，所有 inject 了 'shell' 的插件都会重新启动并使用新实现。没有一个插件需要为此改一行代码。

但它也带来一个必须马上回答的问题：一个插件被卸载的时候，它之前注册过的东西——监听器、定时器、往工具表里塞的那条记录——怎么办？如果这些东西撤不干净，那么「卸载再加载」就不是刷新，而是叠加：监听器留了两份，定时器还在跑，工具表里躺着一个指向已死代码的条目。整套依赖追踪机制会立刻变成灾难制造机。

所以第 3 章的主题不是可选的锦上添花，而是这一章能成立的前提：注册必须可逆。

2.6 可选依赖，和一个扁平的命名空间

inject 表达的是硬依赖：没有就不启动。但有些功能是「有更好，没有也能活」——比如你想在有埋点服务时记一笔，没有就算了。这时候不写 inject，改在用的地方探测：

export function apply(ctx: Context) {
  // 没有提供方时返回 undefined；插件照常运行
  const greeter = ctx.get('greeter')
  console.log(greeter?.greet('maybe') ?? 'no greeter available')
}

ctx.get(name) 是探测式读取，不参与依赖判定，所以它不会让你的插件进 PENDING。我实测过：有提供方时返回实例，没有时返回 undefined，不抛错。

服务名是全局共用的一张平表

教程第 3 章说得很明确：每个应用中的服务名称共用一个扁平命名空间。没有 com.yourteam.metrics 这种分层，只有 metrics。harness 已经占掉了 tools、llm、sessions、web 这些很普通的名字。

撞名会怎样？我试了：让两个不同的类都去 super(ctx, 'greeter')，第二个插件直接进 FAILED 状态，错误原文是 service "greeter" has been registered at <Greeter>（抛出点在 vendor/cordis/src/reflect.ts 的 provide 里）。

好消息是它失败得很响，不会静默覆盖；坏消息是这是运行时才发现的，而且失败的是后来者——两个第三方插件撞名时，谁该改名并没有机制来裁决。仓库给的办法是约定：给自有服务加一个有辨识度的前缀。这是纪律，不是机制。

第3章 副作用为什么必须可逆

这一章回答上一章留下的那个问题：一个插件被卸载了，它注册过的东西怎么办？答案听起来平淡——每一次注册都要能撤销——但整套热重载、整套「从配置里换掉任何一个实现」，全都压在这一条上。

3.1 先看看不可逆注册留下的现场

先把场景摆具体。你写了一个插件，它干三件事：注册一个叫 read_file 的工具、监听 tool/result 事件做统计、每五秒把统计结果打一条日志。代码大概是这样：

// 反面教材，别照着写
export function apply(ctx) {
  toolRegistry.push(readFileTool)                    // 塞进全局工具表
  eventBus.on('tool/result', countIt)                // 挂个监听器
  setInterval(() => console.log(stats), 5000)        // 起个定时器
}

看起来没问题。现在你改了一行代码保存，热重载触发：旧的插件实例被卸载，新的被加载。由于这三行谁都没有撤销的办法，卸载什么也没干。于是新实例又跑了一遍 apply。现场变成这样：

工具表里现在有两条 read_file。模型看到的工具清单里出现了重复项，而且第一条指向的是已经被替换掉的旧代码——那份代码还活着，因为工具表还引用着它。tool/result 上挂了两个统计监听器，每次工具返回结果，统计数字加两次，你会以为工具被调用了两遍。定时器有两个在跑，日志每五秒出现两条，内容还不一样，因为它们各自持有各自那份 stats。

改第三次代码，就是三份。而这一切没有任何一条错误信息。

这不是我编的场景。我把仓库那份 Cordis 打包进浏览器，挂了一个插件，apply 里就一行裸的 setInterval，不做任何包装。等它跑一会儿，调用 dispose() 把插件卸载掉，然后继续观察：卸载之后的 100 毫秒里，这个定时器又触发了 5 次。插件已经不在了，它留下的东西还在跑。

3.2 ctx.effect()：拿资源的时候，就把钥匙交回来

Cordis 给的解法只有一个动作：凡是获取资源，都在 ctx.effect() 里做，并返回一个能释放它的函数。

副作用（effect，代码里保留原文 ctx.effect()）：一段「获取资源」的代码，外加它配套的释放动作。

释放函数（disposer）：effect 体返回的那个函数。Cordis 在插件卸载时替你调用它。

下面这段是仓库教程里的真代码（docs/cordis-tutorial/02-lifecycle-and-effects.zh.md）：

function heartbeat(ctx: Context) {
  console.log('heartbeat plugin loading')
  ctx.effect(() => {
    const timer = setInterval(() => console.log('tick'), 200)
    return () => {
      clearInterval(timer)
      console.log('heartbeat cleaned up')
    }
  })
}

结构就两层：外面那个函数是 effect 体，加载时立刻执行；里面 return 的那个函数是释放函数，卸载时执行。教程给出的实际输出是 heartbeat plugin loading、三个 tick、heartbeat cleaned up、disposed——定时器确实停了。

什么东西必须包 ctx.effect()？判据很简单：凡是 Cordis 不知道的资源——定时器、网络连接、文件监听、你自己维护的一张表。Cordis 管不着它，就得你把钥匙交给它。

3.3 哪些操作已经自带 effect（读者最常犯的错在这里）

看到这里很容易过度紧张，把每一行注册都裹一层 ctx.effect()。不用。教程写得很直接：你很少需要亲自编写 ctx.effect()，因为内置注册 API 本身已经是 effect。

换句话说，3.1 那个反面教材里的三行，有两行在真 Cordis 里根本不需要你操心：ctx.on('tool/result', countIt) 和 ctx.tools.register(readFileTool) 天生可逆。只有 setInterval 那一行是 Cordis 不认识的资源，需要你包一层。

3.4 Fiber：一个插件实例的六种状态

fiber（不译）：一个已加载插件实例的运行时句柄。同一个插件被挂载三次，就有三个 fiber，各有各的配置、各有各的 effect 列表、各有各的状态。ctx.plugin(...) 的返回值就是它。

教程给的状态图是这样：

PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
                 ↘ FAILED

状态是算出来的，不是设出来的

读源码时最容易看漏的一点：fiber.state 不是某处 state = 'ACTIVE' 赋值出来的，而是由三个事实推出来的（vendor/cordis/src/fiber.ts 的 _getState()）：句柄被清空了就是 DISPOSED，记着一个错误就是 FAILED，依赖凑齐了就是 ACTIVE，否则就是 PENDING。

「依赖凑齐了」这个判断本身也有意思。Cordis 会把当前依赖状况拼成一个字符串，源码里叫 epoch：遍历 inject 里的每个名字，把提供它的那个 fiber 的编号拼进去；只要有一个名字没人提供，整个 epoch 就退化成一个表示「不可用」的特殊值。

为什么要把编号拼进去，而不是只记一个「够不够」的布尔值？因为这样一来，提供方换了人也会被发现。上一章那个把英文 greeter 换成中文 greeter 的实验，从服务名的角度看什么都没变（还是叫 greeter，还是有人提供），但 epoch 字符串里的编号变了，于是消费方老老实实地卸载、重载了一次。这一行拼接就是上一章「依赖持续追踪」的全部实现。

卡住了怎么诊断

三种「没反应」要分清，处理方式完全不同：

停在 PENDING：缺服务。用上一章那段遍历 ctx.registry.values() 的诊断代码，看它 inject 了什么、谁该提供。停在 FAILED：启动时抛过异常，去日志里找那条错误；注意 Cordis 是通过 logger 服务报告的，没挂控制台导出器就看不见。停在 UNLOADING：某个释放函数没有结束——这一节的下半段就是它。

还有一个信号很好认：如果你在某处调用 ctx.effect() 或 ctx.on() 时收到 cannot create effect on inactive context，说明你拿着的这个 ctx 属于一个已经被卸载（或正在卸载）的插件。我实测过这条报错，来源是 fiber.ts 的 assertActive()。最常见的成因是把 ctx 存进了闭包，在一个晚到的回调里用它注册东西。

3.5 释放顺序：逆序启动，并发推进

教程里有一句很容易被扫过去的话：disposer 会按注册顺序的逆序启动，但多个异步 disposer 会并发运行。

这句话每一个字都是精确的，而误读它的代价很实在。我把三个释放函数按 A、B、C 的顺序注册，A 的释放要 120 毫秒、B 要 60 毫秒、C 是同步的，然后卸载插件，打出每一步的时刻（毫秒）：

C sync  28      ← 最后注册的，最先启动
B start 28      ← 三个都在同一时刻启动了
A start 28
B done  92      ← 60ms 的先结束
A done  160     ← 120ms 的后结束

看清楚两件事。第一，启动确实是逆序：C、B、A。第二，它们是同时启动的——B 没有等 A，A 也没有等 B。整个卸载耗时约等于最慢那个（120 毫秒），不是三个之和。

源码里就两行：vendor/cordis/src/utils.ts 的 DisposableList.clear() 把释放函数列表倒过来返回，fiber.ts 的 _unload() 拿它去做 Promise.all(...)。倒序决定了启动次序，Promise.all 决定了并发。

还有一条相关的硬规矩，写在 docs/defensive-patterns.zh.md 里：dispose 必须达到完全停稳，而不仅仅是请求停止。清理逻辑如果只发了个终止信号就返回，不等对方真的停下来，就会留下孤儿进程。所以异步释放函数不是特例，是常态——该等就得等。

3.6 热重载凭什么可能

热模块替换（HMR）听起来像魔法：改一行代码保存，程序不重启，新代码就生效了。教程第 6 章把它拆开了，结论平淡得让人失望——因为卸载会释放 effect，加载会遵循依赖，所以 HMR 可以先卸载、再加载。

就这两条。它们正好是第 2 章和第 3 章各自的主题：

卸载能真的卸干净（这一章）：旧实例的每一项注册都随它回卷，工具表里没有残留，监听器没有留两份，定时器停了。所以新实例接手的是一张干净的桌子。

加载遵循依赖（上一章）：新实例不需要有人告诉它「在谁之后启动」，它 inject 了什么，就等什么。所以重载一个插件不会打乱其他插件的加载关系。

这两条都成立时，HMR 就不是新机制，而是这两条的推论——它只是一个监视文件变化、在合适的时机调 dispose 再调 plugin 的插件（@deepseek-ai/cordis-plugin-hmr）。教程给出的实际输出是：

hello from my first plugin
2026-07-22 15:44:36 [I] hmr watching [ '.' ]
2026-07-22 15:44:39 [I] hmr reload plugin at hello.ts
hello from my EDITED plugin

dispose 会递归，而且会等

教程明确写了 fiber.dispose() 的两条承诺：它会递归卸载该插件挂载的所有子插件，并且等所有清理工作（包括异步释放函数）完成之后才结束。

我搭了一个三层结构验证：父插件挂子插件，子插件再挂孙插件，每层各注册一个会打日志的释放函数。调用父的 dispose() 并 await 之后，三条日志全部出现了，父的状态是 DISPOSED。没有一层被漏掉。

第4章 事件：五种分发模式与洋葱

这一章回答一个看起来很蠢、其实很要命的问题：上一章已经能让插件互相直接调用了，为什么还要再搞一套事件？答完这个，再把 Cordis 的五种分发方式拆开，最后停在 waterfall（瀑布式事件）——整个 harness（智能体运行框架）里最难懂、也最值钱的那一个。

4.1 有了服务能直接调用，为什么还需要事件

上一章的结论是：一个服务占据上下文里一个固定的名字，比如 ctx.tools、ctx.llm。谁要用工具注册表，就写 inject: ['tools']，等它就绪，直接 ctx.tools.register(...)。既然这么好用，为什么还要事件？

试着不用事件，看会怎样。

场景：一次工具调用刚跑完，结果拿到了。谁需要知道这件事？在 DeepSeek Harness 里答案不止一个，而且这份名单不归工具包管：会话日志要把它记成持久事实，遥测要计一次数，对接 Claude Code 和 Codex 的钩子插件要转发给外部脚本，子 agent（智能体）驱动要看看是不是自己派出去的孩子回话了。

不用事件，工具包就得自己去调这些人。要调就得先 import 进来；可这些包反过来也依赖工具包（它们要用 ctx.tools 的类型）——互相 import，就是循环依赖。更糟的是这份名单每加一个插件就要改一次工具包的源码，而这正是整个 harness 想避免的事。docs/architecture.zh.md 第 13 行那句话说得很硬：不存在需要打补丁的特权内核，扩展的方式是把插件挂到别的插件旁边。

事件（event）：一个带名字的通知。发出方喊一声名字和几个参数，框架负责找出当前所有登记了这个名字的监听器并挨个交过去。发出方不知道有谁在听，也不需要知道有没有人在听。

教程里有句话把这层意思讲得很干净。docs/cordis-tutorial/07-into-the-harness.zh.md 第 94 行说的是一个工具插件和一个日志插件跑在同一棵树上：两个插件都不知道对方存在，它们是被注册表服务和事件连起来的。这就是事件的全部意义——把「谁在听」这个决定从代码里搬到配置里。在 cordis.yml 里多列一行就多一个监听方，删掉那行监听方就消失，被监听的包一个字都不用改。

4.2 五种分发模式，一个一个来

「分发」就是「把一次通知交给所有监听器」的那个动作。听起来只有一种做法，其实有五种，区别在三件事：等不等（监听器是异步的话，发出方要不要等它跑完）、收不收返回值、能不能互相打断。五种在 vendor/cordis/src/events.ts 第 32 行写成了一个类型：

export type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'

一个事件用哪种模式不是调用方临时决定的，而是这个事件约定的一部分：声明时就定死，之后只能用对应方法分发。仓库在每个事件的注释里写一个 @mode 标签记录它（packages/core/agent/src/runtime-types.ts 里有一堆 @mode waterfall）。

emit：喊一嗓子就走

ctx.emit('stats/report', name, count)

同步广播，按注册顺序挨个调，不等、不收返回值。源码就三行（第 194–196 行）。有个细节值得记住：那三行里没有 try/catch。所以第一个监听器要是同步抛了异常，后面的一个都不会跑，异常还会冲回发出方；而 async 监听器里抛的异常因为没人 await，会变成一个没人处理的 promise 拒绝静静飘走。这两条都是从源码直接读出来的，文档没有专门提醒。

parallel：一起跑，一起等

await ctx.parallel('session/flush')

所有监听器同时开跑，一起等到全部结束。用的是 Promise.allSettled 而非 all——有人失败也要等所有人停下，最后把失败打包成 AggregateError 抛出（第 183–187 行）。用它的时机是「你要的是所有人都收工了这个时刻」。仓库 56 个事件里只有一个 parallel：session/flush，监听方是持久化和遥测（docs/event-producer-consumer.zh.md 第 46 行）。语义很贴切——把没落盘的都写下去，我等着。换成 emit，进程可能在落盘前就退出了。

serial：排队跑，谁先给出答案谁赢

const result = await ctx.serial('agent/turn-stopping', payload)

按注册顺序一个个跑，每个都 await。一旦某个监听器返回「有效值」，立刻停下，把这个值当作整次分发的结果，后面的不再执行。什么叫有效值？第 13–15 行给了确切定义：

export function isBailed(value: any) {
  return value !== null && value !== false && value !== undefined
}

只有 null、false、undefined 算「我没意见，下一位」。其他一切都算有意见——包括 0，包括空字符串。这两个在 JavaScript 里是假值，凭直觉很容易以为会被跳过，实际上它们会停住整条链。

bail：serial 的同步版

const result = ctx.bail('slash/input-begin-command', request)

规则和 serial 一模一样，唯一区别是不 await、全程同步（第 217–222 行）。只适合监听器都是同步函数的场合，好处是能在同步代码里直接拿到结果，不用把整条调用链染成 async。

waterfall：环绕中间件

const config = await ctx.waterfall('agent/request', payload, async () => defaultConfig)

这一个和前四个都不同：调用形式里多了一样东西，最后一个参数是「本来该干的事」。监听器不是被叫到说句话就完，而是套在这件事外面，一层层往里进、再一层层往外出。下一节整节讲它。

把仓库自己的用量摊开看，这五种远不是平均使用的。docs/event-producer-consumer.zh.md 那张矩阵列了 56 个 harness 自有事件，分布是 41 个 emit、13 个 waterfall、1 个 serial、1 个 parallel。四分之三的事件只是在广播事实，剩下的几乎全是 waterfall——正好对应上一节那条判据：事件要么用来告知，要么用来拦截。

4.3 少了一种：本站在核对源码时发现的文档不一致

写这一节时我们做了件很笨的事：把仓库里所有讲分发模式的地方摊开逐字对。结果对出一处不一致，而且不是翻译问题——中英两份一样。

更有意思的是「为什么会漏」。我们把那 56 个事件的模式数了一遍：41 emit、13 waterfall、1 serial、1 parallel，bail 一个都没有。如果一个人靠读 harness 的事件目录来总结分发模式，他会自然得到四种——第五种在那份目录里根本不出现。这大概就是那张表少一格的来源。

但必须补一句，否则本站自己就成了新的不准确来源：bail 在这个仓库里确实有人用，只是不在那份矩阵覆盖的范围内。查到三处：Cordis 自己就用（events.ts 第 296 行注册监听器时先 this.bail(this.ctx, 'internal/listener', ...) 问一圈有没有人要接管，第 348–349 行的注释直接标着这是 bail 事件）；浏览器那一侧用得更多（packages/client/ui-input-trigger/src/types.ts 第 231、238、245、253 行声明了四个 slash/input-* 事件，注释都写着 @mode bail，分发点在同包 src/client/controller.ts 第 322–327 行和 packages/client/ui-commands/src/client/service.ts 第 210、428 行）；还有测试里的 test/scope-probe。

那份矩阵在文件末尾自述是「生成内容」，由仓库的 TypeScript Program 解析，覆盖的是 harness 自有事件；浏览器端插件跑在另一个上下文里，用的是 actx.bail(...) 这种带 this 参数的调用形式，没有进表。所以准确说法是：那 56 个 harness 事件里没有一个用 bail，但 bail 在这个仓库里是活的。

async parallel(...args: any[]) {
  const results = await Promise.allSettled(this.dispatch('emit', args).map(...))
}

4.4 waterfall：洋葱是怎么回事

前四种模式里，监听器都是「被叫到、说句话、坐下」。waterfall 不是——它的监听器把后面所有人都套在自己里面。

先看形状。一个 waterfall 监听器收到的参数是 (...args, next)，最后多一个 next。它可以做三件事：

1. 调用 next()：往里走，让后面的监听器（以及最里面那个默认逻辑）跑起来。next() 的返回值就是「里面那层给出的结果」。
2. 拿到那个结果，包一层再返回出去：加个前缀、改个字段、记一笔。
3. 不调用 next()，直接返回自己的结果。后面所有监听器和最里面的默认逻辑一个都不会跑。Cordis 文档把这个行为叫否决（docs/cordis-tutorial/04-events.zh.md 第 96 行）。

教程里有个能直接跑的例子（docs/cordis-tutorial/04-events.zh.md 第 98–126 行），关键是这两个监听器：

// 监听器 1：把下游的结果包一层
ctx.on('demo/transform', async (input, next) => {
  const downstream = await next()
  return downstream.toUpperCase()
})

// 监听器 2：轮到我做主时，直接短路
ctx.on('demo/transform', async (input, next) => {
  if (input.includes('blocked')) return '** blocked **'
  return next()
})

分发两次，输出是 HELLO 和 ** BLOCKED **。第二行怎么来的？监听器 1 先跑并调 next()，监听器 2 跑起来；它看见输入里有 blocked，直接返回、没有调 next()——最内层那个默认逻辑从头到尾没执行过；返回值往外走回到监听器 1 手里，它老老实实转成大写。于是 ** blocked ** 变成 ** BLOCKED **。

这里有件很重要的事：监听器 1 完全不知道自己包住的是「默认逻辑」还是「监听器 2 的否决」。它拿到的只是一个字符串。这正是中间件模型的力量——每层只跟相邻的内外两侧打交道，谁也不需要知道整条链有多长。

实现只有十行，但有个反直觉的地方

waterfall(...args: any[]) {
  const cbs = this.dispatch('waterfall', args)   // 这次要跑的监听器队列
  const inner = args.pop()                        // 最后一个参数是最内层默认逻辑
  const next = () => {
    const cb = cbs.shift() ?? inner               // 队列空了才落到默认逻辑
    return cb(...args)
  }
  args.push(next)                                 // 参数末尾换成 next 本身
  return next()
}

反直觉的地方是：next 只有一个。它不是为每层各造一个，而是一个共享闭包，每被调用一次就从队列头 shift 掉一个监听器。后果值得现在就记下：在同一个监听器里调两次 next()，第二次跑的不是同一个下游，而是再下一个监听器。队列是一次性的，走过就没了。

4.5 一条必须背下来的纪律：只观察也要调 next()

请把「静默」两个字圈起来，这是这条坑最恶劣的地方。假设你写了个日志插件：

// 错的。它看起来只是打了行日志。
ctx.on('tools/pre-execute', async (exec, next) => {
  console.log('[log] 准备执行', exec.name)
})

没有语法错误，类型检查也过得去，运行起来日志照打。但从它被挂上那一刻起，所有工具都不会真的执行了——它没调 next()，整条链在这儿断了，最内层那个「真的去跑工具」的默认逻辑再没被叫起来。没有异常，没有警告，日志里一切正常，你只会看到 agent 变得很奇怪。正确写法就是把 next() 的结果交出去，多一行 return next() 而已。

这不是本站编的规矩。它同时写在三个地方：教程第 138 行（「如果日志监听器忘记调用 next()，会悄无声息地吞掉所有下游的默认行为」）、docs/cordis-primer.zh.md 第 38 行（「仅做标注或观察的监听器则必须委托」）、以及仓库根目录 AGENTS.md 约定清单里那条全大写的 Waterfall listeners MUST call next()。一条规则被写三遍，通常说明它被踩过。

反过来说，短路在 waterfall 里是设计意图而非滥用。docs/cordis-primer.zh.md 第 38 行的原话是：对于单决策事件，短路是设计意图；策略监听器在拥有决策权时可以不调用 next() 直接返回。仓库里两个典型例子：approval/request（审批请求，packages/interaction/user-approval/src/index.ts 第 30 行）——策略插件能自己拍板就直接返回决定，用户根本不会被弹窗打扰；agent/request-error（packages/core/agent/src/runtime-types.ts 第 260 行）——重试插件决定接管就返回 { kind: 'retry' } 而不调 next()，否则委托给别人。

所以真正的判据只有一句：你是这次决策的主人吗？是——可以短路；不是（你只是路过看一眼）——必须委托。

ctx.on('agent/request', async (payload, next) => {
  const t0 = Date.now()
  const config = await next()
  console.log('耗时', Date.now() - t0)
})

4.6 prepend：谁排在最外层

监听器的顺序就是注册顺序——先 ctx.on 的先跑，在 waterfall 里就是更靠外那层。但注册顺序你其实控制不了：插件的挂载顺序是由服务依赖解析出来的（第3章讲过），不是 cordis.yml 里的行序。所以偶尔需要一个开关：不管别人什么时候注册，我要排在最前面。

ctx.on('some/event', myListener, { prepend: true })
ctx.on('some/event', myListener, true)          // 布尔值是 prepend 的简写

实现很朴素（第 254–260 行）：prepend 为真就 unshift 进数组头部，否则 push 到尾部。EventOptions 一共只有两个字段（第 112–117 行）：prepend，以及 global（无视上下文过滤照收不误，给框架内部用）。docs/cordis-primer.zh.md 第 36 行给的口径很克制：仅当监听器必须在普通注册之前运行时才使用。Cordis 自己用它的地方是 internal/update（第 148–155 行）。

4.7 让事件有类型：declare module 到底在干什么

类型（type）：对「这个位置可以放什么」的一句声明，比如「这个参数必须是字符串」。JavaScript 本身不管这些，你把数字塞进要字符串的地方它照跑，直到某一行崩掉。TypeScript 是 JavaScript 加上类型，它在你写代码的时候就检查这些声明——写错了编辑器当场标红，不用等到运行。

为什么值得为它多写几行？因为事件名就是一个字符串。ctx.emit('stats/report', ...) 里的 'stats/report'，对 JavaScript 来说和拼错的 'stats/reprot' 没有任何区别——后者不会报错，只会永远没人响应。参数写反顺序、少传一个、多传一个，同样不报错。事件是整个 harness 里最容易悄悄写错的地方，因为它天生没有调用点检查：发出方和监听方根本不认识彼此。

Cordis 的解法叫声明合并（declaration merging）：你在自己的文件里往框架的类型里加一条。

declare module '@deepseek-ai/cordis' {
  interface Events {
    'stats/report'(name: string, count: number): void
  }
}

这段代码在运行时什么都不做，编译之后整个消失。它只对 TypeScript 说一句话：事件表里还有一个叫 stats/report 的事件，监听器长这样。加上之后 ctx.emit 和 ctx.on 就都有了完整类型——名字打错标红，参数类型不对标红，监听器少写一个参数也标红。它和第3章的 interface Context 合并是一对（教程第 44 行）：一个往上下文里加服务名，一个往事件表里加事件名，用的是同一个 TypeScript 机制。

还有个容易忽略的小动作。要让另一个文件也享受到这些类型，需要写一行看起来很怪的导入：import type {} from './stats.ts'。大括号是空的，什么都没导入；它在运行时同样什么都不做，唯一作用是让 TypeScript 去看一眼那个文件，从而发现里面的 declare module（教程第 65 行专门解释了这行）。包与包之间也一样：教程第7章用 import type {} from '@deepseek-ai/dsh-tools' 让 'tools/result' 有类型。

最后一个约定：事件名统一用「命名空间／动作」的形式，比如 tools/pre-execute、agent/pre-step、session/created。事件名是一个扁平的全局命名空间，加个前缀能让它读起来还像有结构。

第5章 组装：一棵可以被别人改的插件树

前四章讲的都是「怎么写一个插件」。这一章换个尺度：几百个插件怎么变成一个能跑的产品，以及——更要紧的——别人怎么在不改你一行代码的前提下改你的产品。

5.1 一棵树，不是一个内核加一堆插件

先把话说白：绝大多数你见过的「支持插件」的软件，结构是内核 + 插件。内核是核心逻辑，插件挂在内核开好的口子上。想改内核行为？要么求作者加个口子，要么给内核打补丁自己维护一个分支。

DeepSeek Harness 不是这样。docs/architecture.zh.md 第 11–13 行写得很直白：产品的每一部分都是插件，包括模型适配器、工具注册表、会话日志，以及 agent loop（智能体循环）本身；不存在需要打补丁的特权内核，扩展的方式是把插件挂载到其他插件旁边。

这句话的分量要掂一下。它意味着「agent 循环」和「你昨天写的那个小工具」在框架眼里是同一种东西——都是配置文件里的一行。你想换掉 agent 循环，不需要 fork 仓库，只要在自己的 patch 里把那一行换成别的实现。反过来，你写的插件也享有同样的地位：没人能绕过你，也没人需要绕过你。

5.2 一个配置项都有什么

Cordis 配置项（entry）：cordis.yml 里 YAML 数组的一项，描述「挂载哪个插件、用什么配置」。整个应用就是一个配置项的列表，列表可以嵌套。

字段一共不多，vendor/loader/src/config/entry.ts 第 9–22 行的 EntryOptions 就是全部：

- id: greeter              # 这一项的稳定身份（下一节整节讲它）
  name: './greeter.ts'     # 挂哪个插件：包名，或相对路径
  config:                  # 传给插件的配置，交给插件的 schema 校验
    greeting: 'Hello'
  disabled: true           # 保留这一项，但不挂载
  inject: ['timer']        # 追加声明这一项需要的服务
  group: true              # 这一项是个组，它的 config 是一份子列表

逐个说：

name 是唯一必需的实体信息——挂什么。可以是 npm 包名（@deepseek-ai/dsh-tools），也可以是相对路径（./greeter.ts）。

config 是给插件的配置块，会先过插件声明的校验器再交给 apply（5.7 节）。

disabled: true 的语义很特别：保留这一项，但不挂载它。它和「把这一行删掉」不一样——删掉之后别人就没法按 id 找到它了，而留着并禁用，后面的层还能把它再打开。docs/cordis-tutorial/06-composition-and-hmr.zh.md 第 19 行说：改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。

group: true 让这一项变成一个组：它的 config 不再是配置，而是一份嵌套的子列表，整组作为一个单元加载和卸载。组还有一个更重要的用途——isolate，5.6 节讲。

- id: tool-bash
  disabled: true

5.3 id：loader 唯一认得的身份

这一节是全章最实用的一节。

loader 每次读配置文件，都要回答一个问题：这次读到的东西，和上次跑着的东西，哪些是同一个？没有答案就只能全拆了重装——那 HMR（热模块替换）就没意义了。它给的答案是 id。

vendor/loader/src/config/group.ts 第 60–83 行的 update() 把新旧两份列表各建一张 id 索引表，然后：新表里有、旧表里没有的，挂上；旧表里有、新表里没有的，卸掉；两边都有的，比一比字段有没有变。vendor/loader/src/config/entry.ts 第 157–159 行就是那个「比一比」：

const diff = Object.keys({ ...candidate, ...legacy })
  .filter(key => !deepEqual(candidate[key], legacy[key]))
if (!diff.length && !force) return          // 一字未改：什么都不做

问题来了：如果你没写 id 呢？vendor/loader/src/config/tree.ts 第 66–73 行的 ensureId 会给你现造一个：

if (!options.id) {
  do {
    options.id = Math.random().toString(16).slice(2, 10)
  } while (this.store[options.id])
}

随机八位十六进制。每次读文件都重新造。后果 docs/cordis-tutorial/06-composition-and-hmr.zh.md 第 59 行说得很清楚：不带 id 的配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使它自身文本一个字都没变，它也会被当成「先删掉旧的、再加一个新的」，然后重新挂载。

「重新挂载」不是无害的。第2章讲过，卸载会回卷这个插件的所有副作用：它注册的工具没了、监听器没了、它提供的服务消失了，而依赖那个服务的插件会跟着掉回 PENDING、再跟着重启。改一行注释，半棵树抖一下。这就是为什么组合包里每一行都带 id——packages/bundle/base/cordis.patch.yml 插入的 78 行，一行不落全有 id。

还有一条硬规则：同一层里 id 不能重复。group.ts 第 62–67 行发现重复会直接抛 duplicate loader entry id。这是「misconfiguration fails loud（配错就大声报错）」在这里的体现。

const replace = diff.some(key => key === 'name' || key === 'inject' || key === 'group')

5.4 profile 与组合包：一个产品是怎么被叠出来的

到这里为止我们只谈了一个文件。真实的 dsh 启动时，那棵树是叠出来的。

组合包（bundle）：一个 npm 包，它带着一份 cordis.patch.yml。它的 package.json 里用 dsh.bundle.patch 字段指向那份文件。组合包是「一组配置项 + 它们的代码」的分发格式。

profile：一份具名装配，放在 Harness home 里（$DSH_HOME/profiles/<名字>，$DSH_HOME 没设就是 ~/.dsh）。它的 package.json 用 dsh.profile.bundles 列出自己要叠哪些组合包，另外还放用户自己的 cordis.patch.yml。

发行版带两个 profile 模板（packages/boot/app-boot/src/profile.ts 第 114–117 行）：

web:      ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']
headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless']

三个组合包各干什么，去数一下它们的 patch 文件就知道了：

headless 只有 3 加 3 行——这个数字很说明问题。「无界面跑一个任务」和「浏览器里的完整应用」共享的是同一个 78 行的底座，差别小到能写在一页纸上。

四层，按顺序叠

层的顺序在 docs/architecture.zh.md 第 27 行写着，代码在 apps/cli/src/profile-boot.ts 第 151 行：

composeEntries([bundlePatches, profile.patches, homePatches, overlays])

注意一个容易搞反的地方：home 级的那份排在 profile 自己那份之后，也就是说 home 级更晚应用、优先级更高。packages/boot/app-boot/README.md 第 43 行给了理由：home 级是「适用于每一个 profile 的机器本地偏好」，所以它压过单个 profile 的设置。

5.5 patch：按 id 定位，替换整个 config

patch 的全部语义在一个函数里：vendor/include/src/index.ts 第 58–128 行的 applyEntryPatches。它不长，规则有五条：

1. 非 insert 的 patch 必须带 id，否则跳过并警告（第 105–108 行）。
2. 按 id 找目标行；找不到就跳过并警告（第 110–113 行）。注意——只是警告，不是报错。
3. name 是守卫不是修改：patch 里写了 name 且和目标行对不上，整条 patch 跳过并警告（第 116–119 行）。这是防止你打错行的保险。
4. 剩下的字段整键覆盖（第 121–124 行）：config、disabled、inject 各自被整个替换，没有深度合并。
5. insert 加新行：不带 id 就追加到根列表，带 id 就插进那个组的子列表里（目标必须是组，否则警告跳过，第 80–102 行）。插进来的行会立刻被登记进索引，所以同一份 patch 列表里更靠后的条目可以再去改它（第 96–100 行的注释专门解释了这一点：没有这条，插入的行就永远打不上补丁）。

把这五条和 5.1 节那句「不存在需要打补丁的特权内核」合起来看，才能明白它的分量：整棵树上没有任何一行是特殊的。dsh-base 插进来的 78 行里，agent-loop、tools、session——这些听起来像内核的东西——和 tool-todo 一样，都只是带 id 的一行，都能被后面任何一层按 id 改掉或关掉。

把你自己的产品打印出来

这是本章给你的实操出口。装了 dsh 之后：

dsh --profile web --dump-config

docs/architecture.zh.md 第 35 行的原话是：它打印出的任何条目，都可以由你自己的 patch 替换。打印出来的每一行都带注释标明它来自哪个组合包、哪个 patch 层（apps/cli/src/dump-config.ts 第 30–50 行）。挑一行你想改的，记下它的 id，在 $DSH_HOME/cordis.patch.yml 里写：

- id: 你记下的那个 id
  config:
    # 这一行原来有的字段，你要保留的全部重述一遍
    某个字段: 新值

再 dump 一次，看它变了没有。这个循环——dump、改、再 dump——是你以后调这个产品的主要方式。

5.6 isolate：让两个组各看到一个自己的 shell

先说不用它会怎样。服务是按名字放在上下文里的，ctx.shell 只有一个。如果两个插件都想提供 shell，第二个挂载时会直接抛错（vendor/cordis/src/reflect.ts 第 289–290 行：service "shell" has been registered at ...）——packages/bundle/base/README.zh.md 里就有一句实例：在 fs-sandbox 旁边再挂一个 dsh-fs-local 会重复注册 ctx.fs 并在加载时失败。

可有时候你就是需要两份。最典型的场景是子 agent（subagent）要有不同的能力集：主 agent 能跑任意命令，派出去做调研的子 agent 只能读文件、不能写；或者一个子 agent 的 shell 指向远程沙箱，另一个指向本地。它们跑在同一个进程里，却必须看到不同的 ctx.shell。

isolate 就是干这个的。写法（真实例子在 packages/preset/agent-presets/tests/fixtures/user/isolated/agent.cordis.yml）：

- id: 组A
  group: true
  isolate:
    shell: true          # 这个组里的 shell 是它自己的
  config:
    - id: shell-本地
      name: '@deepseek-ai/dsh-bash-local'
    - id: 用 shell 的工具
      name: './my-tool.ts'

原理在 vendor/cordis/src/context.ts 第 121–124 行：每个上下文都带一张「服务名 → 符号」的隔离表，isolate(name) 给这个名字换一个新的符号，然后基于新表派生出一个子上下文。组里的插件查 shell 时查到的是新符号，组外的还是旧符号。两边同名不同物，互不打扰。

docs/architecture.zh.md 第 116 行把这件事写成了一条路由规则：让某个会话拥有不同的能力集合 → 组装一个 agent preset；其中的服务行需要 isolate realm。packages/bundle/web-app/cordis.patch.yml 里那一大片 disabled: true 就是这个设计的后果——浏览器界面把工具行从全局关掉，改由每个会话自己的 preset 在自己的隔离域里挂载。

5.7 配置校验，以及 !!js 能写在哪

回到单个插件。它怎么保证拿到的 config 是对的？

docs/cordis-tutorial/05-config.zh.md 第 11–34 行的做法是：插件导出一个叫 Config 的东西，而这个名字同时是两样东西——一个 TypeScript 接口，和一个同名的运行时校验器。

export interface Config {
  greeting: string
  targets: string[]
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  targets: Schema.array(String).default(['world']),
})

「同名」不是巧合，是 TypeScript 允许一个名字既是类型又是值。消费方拿到类型，Cordis 拿到校验器。仓库用的是 Schemastery；Cordis 本身接受任何 Standard Schema 校验器——但导出一个普通对象是不行的（教程第 34 行明确写了这句）。

配错了会怎样？教程第 57–68 行给了实例：

ValidationError: invalid config:
  - $.targets expected array but got not-an-array (at targets)

然后这个插件的 fiber 进入 FAILED 状态。FAILED 是 vendor/cordis/src/fiber.ts 第 147–154 行那个六态枚举里的一个（PENDING / LOADING / ACTIVE / FAILED / DISPOSED / UNLOADING）。关键在于：apply 根本不会被调用。

这一条比它看起来重要。没有它，一个配错的插件可能跑到一半才发现某个字段是 undefined，那时候它已经注册了三个工具、开了两个连接。校验前置意味着失败是干净的。教程第 68 行还补了半句作者的说法：如果配置通过了 schema 校验、但里面指定的资源或提供方不可用，插件也应当在能解析该引用时立即拒绝。

!!js：哪里能算，哪里不能

有些配置值必须在加载时算出来，比如从环境变量取。loader 支持一个 YAML 标签：

- name: './config-demo.ts'
  config:
    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'

!!js 只在 config 里、以及条目的 disabled 字段里有效（教程第 80 行；注意是 !!js 不是 !js）。其余元数据——name、id、inject——保持字面值，写在里面的表达式只是普通字符串数据。想按环境选插件，得用 overlay（docs/cordis-primer.zh.md 第 44 行）。

两者的求值时机也不同：config 在这一项声明的注入激活之后、基于该插件的上下文求值（所以你能写 ctx.webStartup.host 这种东西）；disabled 在每次挂载决策时基于 loader 上下文求值。

仓库里最漂亮的一个 !!js 用法是平台门控。packages/bundle/base/cordis.patch.yml 给 bash 那一套写 disabled: !!js process.platform === 'win32'，给 pwsh 那一套写取反的表达式——同一份 patch 文件，每台机器恰好挂载一个 shell 栈。两套执行器注册的都是同一个 ctx.shell 服务（packages/shell/shell/src/index.ts 第 67 行 super(ctx, 'shell')），同一个进程里只能活一个；用 disabled 表达式而不是两份文件，意图和条件都留在了同一个地方。

5.8 HMR，以及怎么找出卡住的插件

第2章说卸载会释放副作用，第3章说加载遵循依赖关系。把这两件事接起来就是 HMR（热模块替换）：先卸载、再加载，替换一个正在运行的插件。@deepseek-ai/cordis-plugin-hmr 监视文件，保存时执行这个过程（docs/cordis-tutorial/06-composition-and-hmr.zh.md 第 23–57 行）。

要注意的是：编辑 cordis.yml 本身也会触发更新。loader 按 id 比较配置项，只挂载、卸载或重新配置发生变化的部分（第 59 行）——这正是 5.3 节那件事的正面用途。

诊断：一个既不干活也不报错的插件

依赖驱动加载有个阴暗面。如果一个插件 inject 了没人提供的服务，它就一直等，不输出任何内容。这不是错误——PENDING 是合法状态，提供方可能稍后才挂上（教程第 63 行）。

教程第 42 行给了一个真实的坑：HMR 插件自己要 inject timer 服务来做去抖。你如果只装了 HMR 没装 @deepseek-ai/cordis-plugin-timer，它就永远停在 PENDING，而且不发出任何提示——你会以为 HMR 坏了。

查法是直接去看状态。每个上下文都能枚举插件注册表（教程第 65–83 行的 diagnose.ts）：

import { FiberState, type Context } from '@deepseek-ai/cordis'

export const name = 'diagnose'

export function apply(ctx: Context) {
  setTimeout(() => {
    for (const runtime of ctx.registry.values()) {
      for (const fiber of runtime.fibers) {
        if (fiber.state === FiberState.PENDING) {
          console.log(`${fiber.name} is PENDING — a required service is missing`)
        }
      }
    }
  }, 500)
}

为什么要 setTimeout 等 500 毫秒？因为启动过程本身是异步的，刚开始所有插件都可能在 PENDING，等一会儿再看，剩下的才是真卡住的。教程第 109 行还提醒：不加 PENDING 过滤直接遍历，你会看到 loader 自己的插件（Loader、Include）处于 ACTIVE——因为配置文件本身也是通过插件挂载的。这句话值得多想一秒：连「读配置文件」这件事都是一个插件。

第6章 会话日志：模型可见即已记录

一句话导语：这一章回答「这段对话到底存在哪」——答案不是一个消息数组，而是一份只往后加、从不修改的事件日志；模型看到的历史是从它算出来的，而且有代码在运行时盯着这件事。

6.1 一个消息数组，五件它做不到的事

第0章讲过一件反直觉的事：模型没有记忆。你和它聊到第十句，它并不记得前九句；是你的程序每次都把前九句连同第十句一起打包发过去，它才显得像记得。

那么这段对话由谁保管？最自然的写法只有两行：

const messages = []
messages.push({ role: 'user', content: '帮我把这个函数改成异步的' })

一个数组，来一条推一条，要发请求时整个丢过去。第0章那个循环就是这么干的，而且它真的能跑起来。问题是它撑不过第二天。下面五件事，每一件都能把它按死。

第一件：用户中途反悔。他说「刚才那句我说错了，撤回」。你从数组里 pop 掉最后一条——然后呢？模型基于那句话已经调用过一次工具、已经动过一个文件。数组里没有任何东西记着「那次工具调用是因为哪句话发生的」，所以你既不知道该连带撤掉什么，也没法向用户交代到底撤到了哪。

第二件：想 fork 一个分支重试。同一段历史，你想试两种不同的后续走法。数组能 slice 出一个前缀——但那是模型历史的前缀，不是发生过的事的前缀。切出来之后你丢掉了：这次尝试当时用的是哪个模型、系统提示词长什么样、上一个轮次是正常结束还是被打断的。两个分支跑出来的结果没法比较，因为你不确定它们的起点真的一样。

第三件：界面要回放打字过程。模型是一个字一个字流出来的。数组里躺着的是组装好的整段文本。你想让「重新打开这个会话」看起来和当时一模一样——文字逐字浮现、工具卡片从等待变成完成——数组里根本没有这些信息，它只有终局。

第四件：崩溃之后恢复现场。进程挂了，内存里的数组跟着没了。就算你每次都把它写进文件，写的也是当前状态，是覆盖式的。崩在半路时文件里是一个说不清的中间态：可能工具调用记下了、结果还没记，也可能反过来。你没法判断该从哪儿接着走。

第五件：算清楚花了多少钱。token 用量得有地方放。你可以在每条 assistant 消息上挂一个用量字段——但失败的那次请求怎么办？它没产出任何消息，token 却是真的花掉了。数组里压根没有它的位置：数组只装消息，而那次尝试没有消息。

6.2 只往后加，从不修改

仅追加日志（append-only log）：一个只允许在末尾添加条目、永远不修改也不删除已有条目的列表。

规则就这一条，简单到有点像废话。但「从不修改」这四个字是整章的承重墙，它换来三样东西。

可回放。任何时刻的状态，都等于从第 0 条开始重新走一遍。这句话成立的唯一前提就是条目不会变——如果第 3 条今天是 A、明天被人改成了 B，那「当时的状态」就永远算不回来了。dsh 把这件事做到了物理层面：事件在被接受时会被深冻结，源码注释的原话是，这样一来「无论是类型断言还是普通 JavaScript，都改不动已经落库的历史」（packages/core/session/src/index.ts）。

可审计。出了事故要追问「模型当时到底看到了什么」，答案就在日志里，而且没有任何人能事后修改它来圆自己的说法。

可 fork。fork 就是取一段前缀当作新会话的种子。前缀不会变，所以两个分支共享的那段历史逐字节相同。若允许修改，父会话改一下，子会话的来路就被悄悄改写了，而它自己毫不知情。

这套做法在软件工程里有个名字，叫事件溯源(event sourcing)。名字不重要，那条规则才重要——记住「只往后加」，比记住术语有用得多。

dsh 里的这份日志

它叫 Session（packages/core/session/src/index.ts）。每条条目是一个 SessionEvent，四个必备字段：

事件类型的清单叫 SessionEventMap。核心声明了 13 种：turn/start、turn/end、step/start、step/end、user/message、assistant/chunk、assistant/message、tool/call、tool/result、todo/write、request/header、request/context、session/end-seed。插件可以往这张表里加自己的类型（第7章会讲这件事的分寸）。

两个不起眼但很硬的约定。其一，seq 必须连续且恒等于日志长度，这意味着你不能「过滤掉一些事件再存」——持久化后端必须把每一条都无损保存，包括那些又碎又多的 assistant/chunk。

其二，data 必须能无损序列化成 JSON，而且 Session.append 在写入那一刻就校验：塞进去一个 Map、一个 Date、一个函数、一个 NaN，当场抛异常，坏事件根本进不了日志。为什么这么急着炸？因为日志是真源。如果放它进去、等到几秒后刷盘时才失败，那时内存里的日志和磁盘上的日志已经分叉了，而分叉的那一刻你毫无察觉。

6.3 投影：模型历史是算出来的，不是存着的

日志里现在什么都有了：轮次边界、每一个流式碎片、请求头、待办清单。但发给模型的请求只需要一串规规矩矩的消息。中间那一步怎么走？

先看一个诱人的错误答案：一边往日志里追加，一边顺手维护一个 messages 数组，发请求时直接拿现成的。它错在你现在有两份数据在描述同一件事。任何一处代码只更新了其中一份，两者就分叉；而分叉之后，「哪一份是对的」这个问题没有答案——它们都自称是对的。

投影（projection）：从一份数据算出另一份数据的过程。这里是：日志 → 模型历史。它是一个函数，输入日志，输出消息列表；不存第二份，只在需要时算。

这个函数叫 deriveMessages()。规则（据 docs/subsystems/session.zh.md）：

注意 user/message 那一行的「原样」：仓库在源码注释里专门警告过，不要在这里给注入的上下文补一层 <context> 之类的外壳——包装归生产方所有，谁产生的内容谁自己包好再写进日志，投影必须是逐字透传。为什么这么较真？因为一旦投影开始加工内容，日志里的字节就不再等于模型看到的字节，「从日志重建请求」这件事就有了灰色地带。

一份日志，多个读法

投影不止一种，这才是「存过程」真正的回报：

• 模型历史：deriveMessages()，上面那张表。
• 人类看的 transcript（文本记录）：读的是日志中追加来源的那些事件（源码里的 isAppendSurfaceEvent）。它和模型历史故意不同——压缩会把一大段对话遮蔽成一条摘要，模型看摘要，人想看原文，而原文一直在日志里。
• 账单：token 记账读每个步骤的 assistant/chunk { type: 'usage' }；没有用量分片时，退回 assistant/message.usage。
• 会话投影 seam（ctx.sessionProjections）：各领域插件各注册一个纯函数单元 apply(state, event) → state，框架只订阅一次 session/event，把每条已提交事件喂给所有单元。领域自己不持有任何订阅，只负责算。

6.4 surface：不是每个事件都到得了模型

假设我们偷懒，把日志里所有事件一股脑发给模型。会发生什么？模型会收到几千条 assistant/chunk（它自己上一句话的碎片）、一堆 turn/start 和 step/end（纯结构标记）、还有 request/header（它自己的系统提示词）。这些是噪音，而且按 token 计费。

所以必须有一层筛选。dsh 没有把它做成运行时的 if 判断，而是做进了类型里：只有三种事件类型有资格产生消息，它们叫 SurfaceEventType。

type SurfaceEventType =
  | 'user/message'
  | 'assistant/message'
  | 'tool/result'

surface（不译，「模型能看到的那一层投影」）：一个有序的 seq 列表，列出当前对模型可见的那些事件，顺序就是模型看到的顺序。session.surface 返回 { nodes, replaceGeneration }——nodes 是那串序号，replaceGeneration 是发生过多少次位置替换。

surface 和日志的区别，三条，值得逐条对照：

那个声明叫 surfaceOp，只有两种取值：

type SurfaceOp =
  | 'append'                                        // 加到尾巴上，常规路径
  | { op: 'replace'; start: number; end: number }   // 用这一条替换掉 start 到 end（含两端）

replace 是给压缩用的：对话太长顶不住上下文窗口时，把中间几十条替换成一条摘要。关键在于——被替换掉的事件仍然原封不动地躺在日志里，只是不在 surface 上了。所以人类还能翻到原文，遥测还能算出原始用量，只有模型看到的是摘要。这正是 6.3 里「一份日志多个读法」的具体兑现。

再看一个类型层面的巧劲：session.append() 对这三种类型强制要求传 surfaceOp，对其余类型则在编译期拒绝这个参数。也就是说，你没法「顺手」加一个产生消息的事件却忘了声明它怎么进 surface——编译就过不去。这比写在文档里靠人记要可靠得多。

6.5 「模型可见即已记录」：一条会被代码检查的规矩

现在到了这一章最值钱的部分。仓库架构文档里有这么一句（docs/architecture.zh.md，逐字）：

运行时不变量（runtime invariant）：一条在程序运行期间必须始终为真的性质，并且有代码在运行时反复检查它——一旦不成立就当场抛异常，而不是留着让它慢慢发酵。

断言长什么样

它就在 packages/core/agent-loop/src/invariant.ts。做法是在 llm/stream 这个 waterfall（瀑布式事件 / waterfall）上挂一个监听器，而且带 prepend: true——挂到最前面。源码注释解释了为什么要抢第一位：防止某个会短路的回放监听器把这项检查静默掉。

每次循环发出的请求经过这里时，它逐项核对：请求必须是冻结的；必须带 sessionId，而且那个会话还活着；日志里必须已经有 step/start，必须已经有 request/header。然后是核心的那三行（真实源码）：

const expected = session.deriveMessages()
if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
  fail(`llm request for session "${String(session.id)}" diverges from the dispatch-time durable derivation (log-reconstruction desync)`)
}

翻译成人话：这次真正要发给模型的消息，必须和「此刻从日志算出来的消息」逐字符相等。不等就报错，错误信息里那个词很直白——log-reconstruction desync，日志重建失步。

紧接着它还核对请求头：model、system、temperature、maxTokens、stop、tools 六项，必须和从日志折叠出来的 request/header 逐项相等。

那条推论：你没有别的入口

现在设想你要给模型加一样新东西。比如：当前打开的文件列表、刚才 git 的改动摘要、用户在编辑器里选中的那段代码。

最省事的写法当然是——在组装请求的时候，往 messages 数组里临时拼一条进去。

这个写法在 dsh 里跑不起来。不是「风格不好」，是那条断言会当场炸：你拼进去的东西不在日志里，deriveMessages() 算不出它，两个 JSON 字符串不相等。

于是你只剩下一条路，三步：

1. 通过声明合并扩展 SessionEventMap，声明一个新的事件类型（要给模型看，它就得是 SurfaceEventType；只是记录用，就做成仅日志事件）；
2. 在合适的时机 session.append() 它；
3. 让投影从日志渲染它。

这就把「要不要记日志」从一个可选的好习惯，变成了硬约束。你不是被说服的，你是被堵死的。

实际操作里，dsh 已经给这件事准备好了官方入口：agent.inject()（架构文档的「新行为的归属位置」表里写着：「添加模型可见上下文 → 调用 agent.inject()；它会落到下一次获准的请求中」）。注入进去的东西最终以 user/message 事件落进日志，靠 source 字段区分它到底是人类的提示词、还是合成的上下文（文件变更通知、子目录的 AGENTS.md、技能内容、定时任务通知……）。三者都逐字投影出 content，谁产生的由 source 说了算。

6.6 为什么连碎片都要留着

assistant/chunk 记的是模型流式返回时的每一个原始分块。分块协议 StreamChunk 有七种变体：block-start、text-delta、reasoning-delta、tool-call-delta、block-end、usage、finish。模型说一句话，日志里可能就多出好几百条。

既然组装好的 assistant/message 已经有了，为什么还要留着碎片？三个理由，都很实在：

回放保真。重新打开一个会话时，界面能一模一样地重演当时的过程——文字逐字浮现、推理块和正文交错出现、工具调用的参数一点点流出来。因为每个 delta 的内容和先后顺序都在。

记账。usage 本身就是一种 chunk。失败的模型请求不会产生 assistant/message（源码里那次 append 在错误分支之后），但它的用量分片还在日志里——那是这次尝试唯一的持久记账记录。6.1 的第五件事，就是在这儿被解决的。

溯源。assistant/message 带一个 sourceEventSeqs，逐条列出自己由哪些 chunk 拼成。这里有个精细到值得停一下的区分：存在但为空的数组 [] 表示「提供方的流确实是空的，而且我们确知这一点」；字段整个缺失表示「没有记录这条消息由哪些早先事件产生」。空数组不等于没这个字段。

代价当然是日志又大又碎。仓库承认这件事，并且把边界划得很清楚：日志的语义不许省——持久化约定要求「无损保存每个事件，包括 assistant/chunk；seq 必须连续，因此不能从规范日志中过滤分片」——但存储的编码可以优化，JSONL 后端默认就把分片行打包存，load 返回的事件与追加时完全一致。

6.7 fork、恢复、崩溃：从同一条流派生

前面说了这么多约束，回报集中体现在这一节：三件看起来完全不同的事，实现上是同一件事——拿一段事件流当种子。

fork

ctx.sessions.fork(source, boundary?, childSessionId?)

boundary 是源日志里的一个 seq（含这一条），省略就是当前最后一条。子会话拿到深克隆的种子事件，加上自己的元数据：parentSession、seedLength、继承的 cwd。

有一条限制特别能说明设计口味：这段前缀结束时不能有开放的轮次，停在轮次中间的前缀会被拒绝而不是被悄悄截断。为什么宁可报错？因为悄悄截断意味着调用方以为 fork 到了 A 点、实际拿到的是 B 点，而他不会知道，直到某天两个分支的行为莫名其妙地不同。

恢复

从持久化后端把整份日志读回来，作为构造种子。种子之后的第一条实时写入是 session/end-seed——payload 是空的（Record<string, never>），位置和 time 就是它的全部含义。

为什么要这么一条空事件？因为种子历史和实时工作在字节层面完全相同。想象一个压缩插件，它有一对开闭括号 compaction/start … compaction/end。日志里现在有一个没配对的 compaction/start：是上次崩在压缩中途留下的，还是此刻正在压缩？光看字节，一模一样。有了这条边界，答案就明确了——在 session/end-seed 之前的未配对开括号，一律属于一个已经结束的生命周期，无论它是怎么结束的。

一个容易踩的细节：要找存储历史里最后一条 session/end-seed，而不能假定 firstLiveSeq 那个位置一定有一条——已经以它结尾的种子不会被重复标记，所以重新打开一个没被改动过的会话，日志不会因此变长。

崩溃

后端重新加载一份崩在轮次中途的日志时，会发现有 turn/start 却没有 turn/end。它不截断——长任务的一个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已经真的落盘了，扔掉就是扔掉真实历史。它改为合成一条 turn/end { reason: { kind: 'interrupted' } }，在不动前后任何独立事件的前提下配平这次被中断的执行。

interrupted 是唯一一个循环永远不会自己发出的结束原因。看到它，就知道这条是恢复路径补的。

第7章 轮次与步骤：循环真正的样子

一句话导语：这一章把第0章那个 20 行的 while 循环拆开，换成真实版本——它多出来的每一样东西，都是为了回答一个「没有它会怎样」的问题。

7.1 那个 while 循环缺了什么

第0章的循环大致长这样：

while (true) {
  const reply = await callModel(messages)
  messages.push(reply)
  if (!reply.toolCalls) break
  for (const call of reply.toolCalls) messages.push(await runTool(call))
}

它能跑，而且是对的——真实的循环骨架就是这个形状。dsh 的实现在 packages/core/agent-loop/src/agent.ts，一个叫 ReactLoopAgent 的类，不到五百行。多出来的东西可以归成四类：

一、输入不是一条一条同步来的。人类会在模型正思考时又打一句；插件会往里塞上下文（文件变了、定时任务到点了）；工具执行完还会带回额外上下文。这些得排队，得有规矩决定谁在什么时候进来。

二、得有人能在请求发出之前拦一下。审批要问「这一步能不能做」，压缩要在上下文顶不住时先动手，钩子要能直接否掉一次尝试。

三、得记账。第6章讲的日志需要边界事件：这一段从哪开始、到哪结束、为什么结束。没有边界，日志就是一锅粥。

四、得能被取消、能从错误里爬起来。用户按了 Esc、模型请求超时、上下文溢出——每一样都得有确定的收场方式。

要把这四类东西安放好，首先需要一套能精确说出「现在在哪」的词。这就是轮次和步骤。

7.2 轮次、步骤、Round：三个不能混的词

仓库的术语表（docs/glossary.zh.md）给了三个定义，一字不差抄在这里：

轮次（turn）：会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束。

步骤（step）：一次模型请求，以及由模型响应引发的工具执行；一个轮次包含零个或多个步骤。

Round：承载一个轮次的外层策略迭代，例如一个 Goal Round 或一次使用全新 agent 的 Ralph 尝试。Round 计数器归该策略所有，并不统计会话中的每个轮次。

架构文档（docs/architecture.zh.md）给的是更好上手的操作化说法：「一个步骤是一次模型请求加上它调用的工具。一个轮次包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。」

三者的关系要一次说清楚：Round 不是轮次的复数，也不是轮次的同义词。Round 是外层策略的计数——一个目标（goal）允许自动续跑几次、一次 Ralph 工作流跑了几个全新子会话。一个 Round 会具体化成一个轮次，但同一个会话里那些无关的人类轮次不消耗 Goal Round 上限。所以「跑了 5 个 Round」和「日志里有 5 个 turn/start」是两句不同的话，混着说会把上限算错。

「零个步骤」为什么必须存在

正常情况下一个轮次至少有一个步骤：问一次模型，可能再调几个工具。但被拒绝的输入仍然会留下一个不含步骤的轮次。

直觉上这很别扭：既然什么都没做，为什么还要开一个轮次、往日志里写两条事件？

因为日志要记录这次尝试。设想一个权限钩子：用户发了一句危险的指令，钩子在 agent/pre-step 里直接拒绝。如果什么都不记，日志上这句话就像从来没发生过——可它确实发生了：消息进过 inbox，被领取了，然后被挡下来了。第二天有人问「我明明发了消息，为什么什么都没有」，日志得能回答。

看真实源码里 turn() 的骨架（packages/core/agent-loop/src/agent.ts）：

this.session.append('turn/start', { turn })          // 先写边界，再去领输入
...
const decision = await this.preStep(target, { turn, step })
if (decision.kind === 'reject') {
  turnEnds = { kind: 'blocked' }
  return false
}
if (turnEnds && decision.messages.length === 0) break
// A removed waking message or an enter decision rewritten to empty
// still owns the initial turn boundary, but it spends no model call.
if (phase.step === 0 && decision.messages.length === 0) {
  turnEnds = { kind: 'completed' }
  return false
}

三个细节值得咬一咬：

其一，turn/start 写在最前面——在 claim 之前、在 pre-step 之前。这是刻意的：边界必须先于任何可能失败的动作存在，否则失败就没地方记。

其二，两条早退路径的结束原因不一样：被拒绝的记 { kind: 'blocked' }，被改写为空的记 { kind: 'completed' }。因为这是两件事——一个是被人挡下，一个是本来就没内容可说。

其三，两条路径都从 return false 走掉，而 turn/end 写在 finally 里。也就是说轮次一定会闭合，哪怕中间抛了异常。

还有一层更细的：被领取的消息在被拒绝之后就到此为止了。agent/inbox/claimed 的文档原话是：「如果拟进入的步骤被拒绝，被领取的消息就在此结束：它既不会被标为 discarded，也不会重新作为 user/message 发出，轮次不含步骤就关闭。」被拒绝既不等于被丢弃、也不等于被消费，它是第三种结局。

7.3 inbox 与 claim：输入怎么排队进来

如果输入直接写进历史，「模型正在生成时用户又发了一句」就没有安放的地方（7.1 那道题）。所以需要一个队列。

inbox（收件箱）：agent 拥有的两条有序待处理消息列表。所有输入都通过它抵达驱动器。

type InboxTarget = 'next-turn' | 'next-step'

next-turn 是「等一个属于自己的新轮次」，next-step 是「等最近的一个步骤边界」。Agent 接口上有三个固定预设的别名方法（packages/core/agent/src/types.ts），它们都是 send(message, target, wakeup) 的特例：

inject 那个「否」是这一节最值得停下来想的地方。它的 JSDoc 原话是：「在不唤醒驱动器的前提下，为下一次 pre-step 排入面向模型的上下文。运行中的驱动器会在最近的后续步骤边界领取它；空闲的驱动器则让它一直待着，直到 followup 或 steering 把自己唤醒。它可能错过一次 pre-step 已经领走批次的请求。」

为什么要这样设计？因为注入的上下文本身不构成一件要做的事。文件被改了、cron 到点了、子目录里发现一份 AGENTS.md——这些是「下次说话时顺带告诉模型」的背景，不是「现在就去干活」的理由。如果 inject 也唤醒，agent 会因为你在编辑器里保存了一下文件就自己醒过来发一次请求，白花钱还可能自作主张改点什么。这一条正是理解 steering（中途引导）与注入区别的钥匙：两者走同一条列表，区别只在唤不唤醒。

claim：一次领走多少

claim（领取）：在步骤边界上，驱动器从 inbox 里取走这一步要用的那一批消息。

claim(target, turn) {
  const claimed = this.mutate('next-step', 0, this.nextStep.length, [], false)   // 全部 next-step
  if (target === 'next-turn') {
    claimed.push(...this.mutate('next-turn', 0, 1, [], false))                   // 外加一条 next-turn
  }
  for (const message of claimed) this.notifications.claimed(message, turn)
  return claimed
}

读法：全部 next-step 输入，外加轮次边界上的一条 next-turn 消息。

这两个数量不对称，是故意的。next-step 里装的是「顺带带上的东西」——steering、注入上下文、工具带回的额外上下文——它们都是给同一次请求当背景的，一次带完才合理。next-turn 里装的是「一件要做的事」，followup 的文档写得很死：「该条目成为它自己那个轮次里唯一的普通消息。」两件事就两个轮次，不合并——合并了你就分不清模型是在回应哪一件。

还有一层容易被忽略：inbox 本身也是持久的。append、prepend、replace、remove、clear、splice 和 claim 都会往会话日志里记一条规范化的 agent/inbox/spliced（这个事件类型由 dsh-agent 包通过声明合并加进 SessionEventMap——正是第6章那条推论的实例）。而 claim 记的是纯删除的 splice，并且不发 discarded 通知，循环另外逐条发 agent/inbox/claimed。为什么要区别对待？因为「被领走去执行」和「被取消掉」在界面上是完全不同的两件事，一个进入运行、一个直接消失。

7.4 agent/pre-step：决定模型看到什么的那道闸

架构文档只用了一句话：「agent/pre-step 决定模型看到什么。」这句话的分量在于——它是请求推导之前唯一的串行监听器链。

waterfall（瀑布式事件 / waterfall）：一串监听器排成一队，每个都拿到当前的值，然后二选一——调 next() 把决定权交给下一个（并拿到下游的结果），或者直接返回一个值不调 next()，从而短路，后面的全都不跑。

它的返回类型只有两种可能：

type PreStepDecision =
  | { kind: 'reject' }                              // 不开步骤
  | { kind: 'enter'; messages: UserMessage[] }      // 用这批消息进入步骤

payload 里带着：已领取的批次 messages（独占，别人拿不到）、拟进入步骤的坐标 turn 和 step、当前轮次的取消 signal。三种用法：

• 放行：调 next()。文档明说「调用 next() 会保留当前的消息」。
• 改写：返回 { kind: 'enter', messages: [...] }，换一批进去。dsh-compaction-basic 就是在这里处理上下文压力的——在派生请求之前动手，而不是等请求失败了再补救。
• 拒绝：返回 { kind: 'reject' }。不开步骤，轮次以 blocked 收场（7.2）。

两条容易被忽略的规则：最终决策省略掉的已领取消息保持已删除——你改写时丢掉的那条不会自己飘回 inbox；而领取之后才插进来的输入仍留待后续处理——它没被这一批带走，会等下一次 claim。

默认行为是什么？看真源码里的 preStep()：没有任何监听器时，决策是「领到什么就进什么，外加一条运行时上下文（如果有）」。也就是说这道闸默认全开。

最后划一个重点：steering 和注入的上下文经过同一个 waterfall。它们不是走后门进来的。等下一次 claim 把它们收进批次，它们和人类的提示词一样要过这道闸。这跟第6章那条不变量是同一套思路——只留一个入口，所以只需要在一个地方拦。

7.5 一次轮次的完整流程

下面这张图和后面那张表，是这一章的核心。先看整体形状，再逐环问「没有它会怎样」。

现在逐环追问。这张表建议对照上面的图读一遍，每一行都试着自己先答，再看右边那一栏。

关于 turn/end 的 reason，多说一句：它是一个可合并扩展的和类型，核心给了六种——completed、aborted、blocked、error、max-tokens、interrupted。其中 max-tokens 是粘性的：只要轮次里任何一个步骤撞上了输出上限，整个轮次就以 max-tokens 结束，哪怕后面还有步骤正常完成（源码注释：截断这个事实优先）。而 interrupted 是唯一一个循环永远不会自己发出的原因——它由崩溃恢复合成。

7.6 三个事件域：大多数改动的第一个决定

架构文档里有一句话，值得当成口诀：「事件就是扩展点，而选对事件域是大多数改动的第一个决定。」

三个域（逐字引自 docs/architecture.zh.md）：

• 会话事件是追加到日志并通过 session/event 广播的持久事实。当某个事实必须在重新加载后仍然存在时，使用它。
• Agent 事件（agent/*）携带活跃 Agent：inbox、步骤、状态、请求、验证、续跑。要观察或拦截进行中的工作时，使用它。
• 能力事件无需导入循环即可向某个 seam（fs/*、tools/*、telemetry/*）附加策略和适配器。

为什么说这是「第一个决定」？因为选错了域，你写的东西会在某个时刻静默消失或静默变质，而且不会报错：

该持久的写成了 agent 事件——进程一重启，那件事就没了。日志里没有它，fork 出来的会话不知道它，恢复回来的会话当它从没发生。而你在开发时完全看不出问题，因为进程一直没重启。

该实时的写成了会话事件——它进了日志，从此就要跟着 fork、跟着回放、跟着持久化格式版本走。一个本来只是「界面要闪一下」的东西，变成了磁盘格式的一部分；以后想删掉它，是一次破坏性的格式变更。

该挂在能力 seam 上的写成了 agent 事件——你的插件被迫依赖 agent-loop 包，而仓库的规矩是「扩展插件依赖 agent，绝不直接依赖 agent-loop」，为的就是让循环保持可替换。一旦有插件直接依赖了具体循环，换循环这件事就做不成了。

那么，流程上哪些是持久的？架构文档给了名单：turn/*、step/*、user/message、assistant/* 和 tool/* 是持久会话事件；其余是分属三个事件域的实时扩展点。

waterfall 与 serial

同一条流程上还有第二个维度：这个事件的监听器怎么被调用。

waterfall 的坑在 7.4 那道题里已经踩过：忘了调 next() 是一个安静的 bug，不报错，只是后面所有监听器都没跑。仓库把它写进了全仓约定，大写强调：Waterfall 监听器 MUST call next()。

7.7 记账和给模型看，是两件事

assistant/message 会记录每一次成功的提供方调用——包括返回空内容的，以及以 max-tokens 结束的（撞上输出上限，一个字都没吐完整）。

而 deriveMessages() 的规则是：内容为空的 assistant/message 跳过。

两条规则放一起，意思是：这条事件存在，但它不进模型历史。

为什么要这么拧巴？因为它同时要满足两个互相冲突的需求。

记账那边：这次调用真的发生了、真的消耗了 token。用量、提供方、模型都得留下来。丢了它，账就对不上，而且是永久对不上——日志是唯一的账本。

给模型看那边：一条没有内容的 assistant 消息塞进 transcript，对某些提供方直接就是非法请求，对所有提供方都是噪音。源码注释写得很直白：无内容的 assistant 轮次不得进入提供方 transcript。

sourceEventSeqs 在这里还有一个精细区分（第6章提过，这里是它真正派上用场的地方）：assistant/message 可以带一个存在但为空的数组，表示「提供方的流确实是空的，而且我们确知这一点」；字段整个缺失表示「没有记录这条消息由哪些早先事件产生」。空数组不等于没这个字段。

更极端的是失败的模型请求：它连 assistant/message 都不会有（源码里那次 append 排在错误分支之后）。但它的 assistant/chunk { type: 'usage' } 还在日志里——那是这次尝试唯一的持久记账记录。

第8章 提示词与工具 schema：模型看到的那一页纸

一句话导语：这一章回答一个看起来很傻、其实决定整个 harness 形状的问题——模型怎么知道它能调哪些工具？

8.1 模型其实什么都不知道

先把一件事说透，因为后面所有设计都从它长出来：你在用的这个模型，不是一个住在服务器里、能看见你硬盘的小人。它是一个函数——你塞给它一大段文本，它吐回来一大段文本。它没有记忆（上一轮说过什么，全靠你这次再原样发一遍），没有手（没法自己打开文件），甚至不知道今天几号，除非你在文本里告诉它。

不用系统提示词会怎样？你直接问它「把这个目录里的临时文件删掉」，它会回你一段非常礼貌的自然语言：「你可以运行 rm *.tmp」。然后没有然后了。没有任何东西去执行那一行，因为模型压根不知道「执行」这个动作在它这里是可以发生的。

系统提示词（system prompt）：每次向模型发请求时，放在最前面的一段固定说明文本。它不是用户说的话，是部署方替模型写的「岗前须知」——你是谁、你能做什么、做的时候注意什么。

工具 schema（tool schema）：一个工具的说明书，三样东西——名字、一句人话描述、参数的结构描述（JSON Schema）。模型读到它，才知道自己可以发出一个「我要调用 read，参数是 {file_path: "/tmp/a.txt"}」这样的请求块。

所以整件事没有魔法：模型能调工具，是因为你把工具说明书写进了它读的那页纸。这一章讲那页纸是怎么拼出来的。

8.2 那页纸是拼出来的，不是写死的

最容易犯的直觉错误是：把系统提示词想成源码里一个大字符串常量，要改就去编辑那个常量。

不这么做会怎样？回想前面讲插件的那一章：这个 harness 里一切都是插件。你事先不知道这次部署装了哪些工具——装了 bash 吗？装了子 agent 吗？沙箱开了没有？如果提示词是常量，你就得为每种组合各写一份常量，然后祈祷没人漏改。装 20 个可选插件，理论上是 2²⁰ 份常量。

仓库的做法是反过来的：谁提供能力，谁自己带一段说明。每个插件把自己那一小段注册进去，真正要发请求时再把所有片段汇总、排序、拼成一页纸。这个注册表就是 ctx.systemPrompt 服务，源码在 packages/core/system-prompt/src/index.ts。

它收四种东西：

注意第二行那个设计：会变的东西不写进系统提示词。审批策略从「问我」切成「一律拒绝」，harness 不去改请求头里的系统提示词，而是在历史后面追加一份新的完整快照。packages/interaction/user-approval/src/index.ts 里那行注释把理由写得很直白：完整的当前值走在保留历史之后，这样切换策略不会重写稳定的系统提示词缓存前缀。8.6 节会讲这个「缓存前缀」值多少钱。

order：一份不成文但写在类型里的排版约定

section 按 order 升序拼接。仓库把约定直接写在 PromptSection.order 的 JSDoc 里：-100 是 harness 身份，0 是部署人格，工具指引用 100–199。这不是强制的，是一条大家都遵守的车道线。下面是我从源码里逐个抄出来的真实占位：

为什么 tools:code-only 特意排在 99、抢在所有工具指引前面？源码注释给了理由，而且这个理由值得记住：每个工具都贡献一段「我叫什么、怎么用」，没有一个会说明「你到底能不能直接调我」。如果没有那条排在前面的规则，模型读到一整本工具目录，却读不到「只有 run_code 可以直接调」，于是它发出一个原生调用、收到 UNKNOWN_TOOL——一个提示词刚刚声明过的工具居然不存在——然后它会得出结论：这个部署坏了。顺序在这里不是排版，是语义。

组装是一次 waterfall，每一步都能改写

assemble(context) 干的事，按源码顺序是：解析变量（作用域内的覆盖全局的）→ 合并 section 与 context（同样是作用域覆盖全局）→ 调用所有工具 provider 收集 schema →按配置的 toolOrder 排序 → 然后跑 system-prompt/assemble 这个 waterfall。

waterfall 的返回值是权威的：监听器可以增、删、改这次组装的任何部分。但有一个例外：如果某个 section 声明了 complete: true（意思是「我就是整份系统提示词」），waterfall 跑完之后 harness 会把它恢复成唯一的 section。文档写得很清楚——监听器无法给那个作用域的系统提示词添加或替换内容。

到底有多少个包在往这页纸上写字

我数了一下：仓库 219 个包里，有 25 个在生产代码里调用 systemPrompt.section() 或 systemPrompt.context()（用 grep 统计，排除测试）。下面这个实验室把 219 个包和它们的依赖关系全翻给你，你可以自己去验证这个数，也可以看看这 25 个都是谁。

8.3 工具 schema 从哪来：一个 provider，52 份说明书

工具作者要做的事少得出奇。这是 docs/cookbook/adding-a-tool.zh.md 里的最小形态，一字未改：

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',          // what the model sees
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },                     // optional by default
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

然后文档补一句话：「注册基于副作用：dispose 插件 fiber 即注销该工具。schema 会自动流入系统提示词的组装过程。」——工具作者从头到尾没碰过提示词。

「自动流入」是怎么实现的？我去全仓库搜了一遍 systemPrompt.tools(，生产代码里只有一处，在 packages/core/tools/src/index.ts 的 ToolRuntime 构造函数里：

ctx.systemPrompt.tools(context => this.wireSchemas(context.scope))

工具注册表在自己出生的时候，就把「本次组装该看到哪些工具」这个问题接了过来。每次组装，提示词注册表回头问工具注册表一句：这个作用域看得见什么？工具注册表按那个作用域算一遍，把答案交回去。两个注册表之间只有这一根线。

那条绝不能越过的线：白名单投影

一个 ToolDefinition 身上挂着一大堆东西：execute（函数本体）、output（规范输出声明与渲染器）、timeoutMs、isConcurrencySafe、presentCall／presentResult（UI 卡片怎么画）……而模型只该看到三个字段。docs/subsystems/tools.zh.md 用了很重的措辞：这些字段绝不能泄漏到模型请求中。

实现方式不是「小心别写错」，而是显式允许列表——schemas() 拿到定义之后，只挑出 name、description、parameters 三个字段重新造一个对象出来。多一个字段都进不去，因为根本没人去拷贝它。

模型最终读到的那份 schema 长什么样？这是 read 工具的真实 schema，抄自 docs/tool-catalog.zh.md：

{
  "type": "object",
  "properties": {
    "file_path": { "type": "string",
      "description": "Path to read, resolved by the filesystem backend." },
    "offset": { "type": "number",
      "description": "1-based first line to return. Defaults to 1." },
    "limit": { "type": "number",
      "description": "Maximum number of lines to return. Defaults to 2000." }
  },
  "required": ["file_path"]
}

顺带一提 ToolProviderResult 里那个不起眼的 knownNames 字段：它是 provider 在过滤之前的名字全集。有了它，harness 才能区分两种长得一样的错误——「配置里把工具名拼错了」和「这个工具确实存在，只是在这个作用域被有意藏起来了」。前者该报错，后者是正常的。

8.4 为什么要作用域化：不是每个 agent 都该看到全部

不作用域化会怎样？你的主 agent 派出一个子 agent 去「读一读这三个文件，总结一下」。如果子 agent 继承了全套工具，它手里就握着 bash、握着 write、握着再派子 agent 的能力。它大概率不会乱来，但「大概率」在安全上等于零。你想要的是：这个孩子手里就只有 read 和 grep。

仓库的机制是 ctx.tools.restrict(filter)，行为在 docs/subsystems/tools.zh.md 里定义得很细：

• 它作用于该作用域继承来的工具——部署全局层，加上它这条链上的每个祖先作用域。
• 多个限制取交集：链上任何一个作用域都能把某个名字对它内部的一切遮掉。
• 它不动这个作用域自己注册的工具。原因很实在：被委派的子 agent 需要保留它用来汇报的那几个工具（report 之类），过滤器如果把这些也削掉，孩子就没法把结果交回来了。
• 只写 deny 的过滤器允许以后新增的、未列出的继承工具通过；写 allow 列表则把它们统统排除。
• restrict() 必须在带作用域的上下文（agent.ctx）里调用；名字拼错会大声报错，不会静默忽略。

这一章最该记住的一句话

packages/subagent/subagent/src/types.ts 里，toolFilter 字段的 JSDoc 只用一句话就说清了整个安全模型（我逐字翻译）：被点名的工具会从孩子的提示词里消失，并且拒绝执行（一处可见性），并带有大声的未知名校验。

把这句话拆开看，它其实是三个承诺：

1. 从提示词里消失。组装时调用的 wireSchemas(scope) 和查找时调用的 get(name, scope)，走的是同一个内部方法 view(scope)——同一次层遍历同时算出「可见的定义表」。所以提示词里有什么，就是这个作用域能看见什么，两者不可能对不上。
2. 拒绝执行。分发时解析工具也走同一个 view。被过滤掉的名字在这个作用域里解析不出定义，于是执行阶段报 UNKNOWN_TOOL——和一个真正不存在的工具名收到的错误一模一样。
3. 与不存在的工具无法区分。这是前两条的合力结果，也是它作为安全设计的关键。

8.5 shadowing：最具体者胜出

shadowing（遮蔽）：同一个名字在多个层里都有注册时，最靠近使用者的那一层赢，其他层的同名注册被「遮住」。你可能在编程语言的变量作用域里见过同一个词——局部变量遮住全局变量，是一回事。

在这个 harness 里，工具、提示词 section、提示词变量都遵守这条规则：带作用域的注册替换同名的全局注册。ctx.tools.register() 的文档写得很直接：「带作用域的工具遮蔽全局工具；同一层内的重复名字和保留的 run_code 名字会失败。」

注意「同一层内重复会失败」这半句。跨层重名是遮蔽（正常操作），同层重名是错误（大声抛异常）。这个区分很讲究：跨层重名一定是有人在表达「我要为这个 agent 换一个实现」，同层重名一定是两个插件撞车了，谁都没打算让对方赢。

实际用途很多：子 agent 换一个受限版的 bash；给某个 agent 的 deployment:persona 换一份人格（packages/subagent/subagent/src/child-agent.ts 就是这么给孩子换人格的——注册一个同名的 deployment:persona section，仅为这个孩子遮蔽部署人格）。

8.6 提示词的成本：每加一句都在花钱

这是本章最容易被忽略、也最花钱的一节。

回到 8.1：模型没有记忆。所以在一个任务里，模型走的每一步——每一次「思考→调工具→看结果→再思考」——都是一次全新的请求，而每一次请求都要把系统提示词和整份工具目录原样重发一遍。不是发一次就存在那儿了，是每一步都发。

给你尺度感。我统计了 docs/tool-catalog.md（这份目录是仓库的生成器真的启动每个工具插件、读 ctx.tools.schemas() 抄出来的，所以它就是模型看到的东西）：

差不多 3 万字符。换算成日常可感知的东西：一篇一万字的中文长文那么长，你每走一步就完整重发一遍。一个跑 20 步的任务，光工具目录就发了 60 万字符——而这还不含提示词正文、不含用户消息、不含会话历史。

省钱的机制：缓存前缀，以及它怎么被弄坏

KV 缓存（KV cache）：模型服务端的一个优化——如果这次请求的开头和上次一模一样，那部分的计算结果可以直接复用，不必重算。关键词是开头：它是前缀匹配，从第一个不同的 token 起，后面全部作废。

packages/core/tools/README.md 把工具目录的缓存行为写得非常明确（我逐字翻译）：「只要可见的定义及其顺序不变，前缀就是稳定的。注册、释放或作用域限制的变化，可能从第一个改变的 schema token 起使复用失效。」

把这句话和前面几节连起来，很多设计选择一下子就说得通了：

• 为什么工具顺序要可配置。SystemPrompt 有个 toolOrder 配置，还有个保留标记 <unlisted-tools> 表示「没列出的工具插在这里」。不配的话默认按名字字典序排——而且源码里特意注明用的是「code-unit 比较，与语言环境无关，所以每台机器上顺序都一样」。顺序必须是确定的，否则同样的工具集在两台机器上会生成两个不同的前缀。
• 为什么会变的事实走 context() 而不是 section()。快照追加在历史后面是纯追加，前缀不动；改系统提示词是改前缀。
• 为什么动态挂载插件要谨慎。运行到一半装一个新工具插件，这个 agent 的下一次请求前缀就变了。（tool-cordis 那段部署说明里写着：运行中的 Package 可以注册额外的模型可见工具，发生这类工具集变化时系统会记录完整且有变动的请求头。）

8.7 模型没看到的东西就不存在

最后一节讲一个工程上非常反直觉的事实。

你花两周写了一个特别好的工具：正确、快、边界处理完美、测试 100% 覆盖。然后你给它写了一句 description：「Process the input.」这个工具等于不存在。模型读不懂它是干嘛的，永远不会挑中它——你那两周唯一的产出，是给每一次请求增加了几十个字符的成本。

这是 harness 工程和普通软件工程最不一样的地方之一。普通软件里接口文档写得烂，调用方是人，人会去读源码、去问你、去试。harness 里调用方是模型，它只有你写的那一句话，没有别的渠道，也不会来问你。schema 的描述不是文档，它是产品界面。

仓库把这件事写成了包级规矩（packages/AGENTS.md）：「从模型的视角撰写面向模型的约定。提示词、工具 schema、结果和诊断信息里只包含与任务相关的概念，不包含 UI、传输层或实现层的词汇。」——不要在 description 里写「本工具通过 ctx.fs seam 调用后端」，模型不知道什么是 seam，也不该关心。

几个可以直接抄的正面例子，都来自仓库真实的 schema：

• bash 的 description 参数（这是个参数，要求模型自己填一句话描述这条命令）里，直接给了三个例子：「ls」→「List files in current directory」、「git status」→「Show working tree status」，并且规定 5–10 个词。与其解释规格，不如给样例。
• read 的 offset 参数描述写的是「1-based first line to return. Defaults to 1.」——把「从 1 开始数」和默认值都写死在描述里。不写的话，模型会自己猜是 0 还是 1，而且不同时候猜得不一样。
• run_code 的描述里有一句：「只有打印或返回的内容会传回，请谨慎筛选。」——这是在描述里直接预防一类错误行为，而不是等它犯了再报错。

反过来，tools:code-only 那段前面提过的注释，正是一个「没写清楚导致模型自我怀疑」的实例：模型读到一整本工具目录却读不到「只有 run_code 能直接调」，于是它发出一个原生调用、收到 UNKNOWN_TOOL，然后得出结论说这个部署不一致。修法不是让报错更详细，而是把那条规则排在工具目录前面。

第9章 一次工具调用要过七道关

一句话导语：模型说「删掉这个文件」，到文件真的没了，中间发生了什么——这一章把这条路上的每一个路口都走一遍。

9.1 从「删掉这个文件」到文件真的没了

模型这一步的回复里，除了自然语言，还夹着一个结构化的块：工具名 bash，参数 { command: "rm -rf build/" }。

最朴素的实现会怎样？你在循环里写：看到工具调用块，就查表找到函数，把参数传进去，执行，把返回值发回给模型。二十行搞定，能跑。

然后需求陆续来了：删文件前弹窗问一句；某些目录永远不能被写；每个工具都要有超时；记录每次调用花了多久；结果太大时截断；合规插件在特定命令上一律拒绝——而且这六件事来自六个团队，谁都不该去改另外五个人的工具代码。

这就是流水线存在的理由。它把「一次调用」从一个函数调用，变成一条有编号的、每一段都能挂东西的路。仓库把这张图画在 docs/tool-execution-pipeline.zh.md；下面这张是我按那张流程图重画的，把它归成七道关。

下面这个实验室把这七道关做成了七个可以单独关掉的开关。建议你读一节、去关一关——正文里我会点名让你关哪一个。

9.2 开场两步：先记录，再点亮卡片

模型的调用块到手，harness 做的第一件事不是执行，也不是问权限，而是往会话日志里写一条 tool/call。

源码在 packages/core/agent-loop/src/tool-calls.ts，那段调度代码里的顺序一眼可见：

const startCall = async (index: number): Promise<void> => {
  const call = group[index]!
  callSeqs[index] = appendToolCall(session, turn, step, call.block)  // 先记
  started++
  const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)  // 再走策略
  ...
}

appendToolCall 追加的事件里带着 turn、step、callId、工具名和模型原样发来的参数。

紧接着，UI 拿这条事件点亮一张 pending 卡片：调用 presentCall(args)，得到一个带 card 标签的渲染意图——bash 返回 { card: 'terminal', title: 命令 }，write 返回 { card: 'diff', diffs: [...] }。用户于是在这次调用还在排队时就看见了「它要干什么」。

这里有一条硬规矩，docs/cookbook/adding-a-tool.zh.md 用了加粗：presentCall 必须是 args 的纯函数——不做 I/O、不读会话状态、不用时钟和随机数。为什么？因为它既在实时流式输出时被调用，又在你事后回放会话日志时被调用。如果它偷偷读了当前的文件内容，那么回放三个月前的会话时，它读到的是今天的文件——同一条日志，两次渲染，画出两张不一样的卡片。

9.3 第 1 关：tools/pre-execute——所有策略挂靠的地方

第一道关是一个 waterfall。每个监听器拿到 (exec, next)，返回一个决定：

type PreToolDecision =
  | { kind: 'allow' }
  | { kind: 'deny'; reason: string }
  | { kind: 'ask'; reason?: string }

调 next() 就是「我没意见，交给下一个」，最后没人有意见就默认 allow；直接返回一个决定就是短路，后面的监听器不再运行。钩子插件、权限插件、沙箱策略全都挂在这一关。

有一件它做不到的事，而且是故意的：前置策略不能改写参数。类型里就没有这个选项。docs/subsystems/tools.zh.md 给的理由是一句话：「参数不可被改写，因为历史记录、审计、UI 和执行必须保持一致。」

想想 9.2：参数已经写进 tool/call 了，也已经画在用户屏幕上的卡片里了。这时候如果某个监听器悄悄把 rm -rf build/ 改成 rm -rf /，日志说的、用户看见的、真正执行的，就是三件不同的事。

去实验室试试：把第 1 关关掉（或者让它固定返回 deny），看会话日志里出现了什么、没出现什么。你应该会看到工具本体没跑，但日志里照样有 tool/call 和一条 tool/result——这正是 9.2 的设计在起作用。

9.4 第 2 关：ctx.approval——一次性询问，默认拒绝

如果第 1 关有人返回了 ask，harness 就去问人。

问的方式是 ctx.approval.request(req)：请求里有 agent、工具名、callId、一句「为什么要问」的理由和一个 signal。它有意不带工具参数——callId 已经指向那条画成卡片的调用，UI 把弹窗挂上去即可，不必再渲染一份可能漂移的副本。

结果类型是闭合的四选一：

type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'

只有 allowed-once 放行，而且只授权所问的那一个操作。其余三个都拒绝。

「默认拒绝」到底默认在哪

这四个字要拆开看，因为它在这条链路上被写了不止一次。我把 packages/core/tools/src/index.ts 里 serviceAsk 的分支和 docs/subsystems/approval.zh.md 的规定合起来列成一张表：

注意这张表没有「超时后放行」「没人管就当同意」这样的行。文档的措辞是：缺失、不负责该请求、抛异常或不合规的应答者会产生 unavailable，而非放行。

还有两个细节值得单独点出来：

其一，四个理由字符串是不一样的。源码注释解释了为什么要费这个劲：「三个非授予结果以不同的理由拒绝，这样模型能分辨一个人类说的『不』和一个不存在的审批通道。」模型收到「用户拒绝了这个工具」应该换个方案；收到「没有可用的审批通道」则应该知道再问一百次也是这个结果——这是给模型的可操作信息，不是给人看的日志。

其二，never 策略在服务内部、waterfall 分发之前就执行了。文档明说这样做的原因：即使后来用 prepend 注册的应答者也无法绕过它。如果 never 是靠「注册一个总是返回 rejected 的应答者」实现的，那么任何人只要把自己的应答者插到更前面，就能把它架空。把不可协商的策略放在协商机制之外——这个套路你在下一节会再看到一次。

最后，审批留下一对只进日志、不进模型 transcript（文本记录）的审计事件：approval/asked 与 approval/decided，靠一个全新的 ApprovalRequestId 配对。而且 request() 要求发起请求的会话处于一个尚未结束的轮次内——因为这对审计事件必须被持久日志的提交／回放边界包住；空闲时发起的询问会在追加任何东西之前就被拒绝。

9.5 第 3 关：单调守卫——只能拒绝，不能放行

过了审批，还有最后一道预分派检查：已注册的单调守卫。

单调守卫（monotonic guard）：一个同步函数，看一眼这次调用，要么返回一个拒绝理由（字符串），要么返回 undefined 表示弃权。它没有「允许」这个返回值。「单调」在这里的意思是：权限只会朝一个方向走——越走越少，绝不回头。

type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

这个类型少了一个分支，威力却很大。ToolGuard 的 JSDoc 把理由写在了签名旁边：「因为守卫没有允许结果，监听器的顺序无法把一个拒绝变回许可。」

对比一下第 1 关：那是个 waterfall，谁先注册谁先跑，一个监听器可以短路掉后面所有人。这意味着顺序决定结果——而顺序取决于插件加载顺序，那是配置文件的事。你的安全策略如果依赖「我一定排在他前面」，那它其实依赖的是别人没改过 cordis.yml。

守卫这一层把顺序从等式里拿掉了：任何一个匹配的守卫返回理由，这次调用就死了，谁也救不回来。全局守卫先跑，然后是作用域链上的（从最远的祖先开始），第一个拒绝就是最终答案。

身份受保护是什么意思

守卫拿到的是 Readonly<ToolExecution>，而且这不只是 TypeScript 的类型标注。在策略开始之前，注册表已经做了三件事（docs/cookbook/adding-a-tool.zh.md 明文）：把 arguments 在一次递归遍历中物化成分离的无损 JSON、深度冻结它、分配一个不透明的 exec.token。callId、name、arguments、agent、token、调用方的 signal 在整个分发过程中保持不可变。

所以守卫看到的参数，就是写进日志的那份、画进卡片的那份、待会儿真正传给工具本体的那份。它不可能被谁在中间掉包。一个守卫如果不能确信自己检查的东西就是待会儿要执行的东西，它的检查毫无意义。

为什么审批排在守卫之前

这是本章最容易问反的一个设计问题。直觉上「问人」应该是最后一道，人说了算嘛。

仓库的顺序是相反的，docs/tool-execution-pipeline.zh.md 用一句话给了理由：「ctx.approval 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册守卫。」

把它翻成人话：问人是可协商的，所有者策略是不可协商的。

先问人，人说「允许这一次」；然后守卫仍然可以说「不行」。结果是：人的同意不能推翻所有者策略。这正是你要的——一个部署方写的「这个目录永远不许写」的守卫，不应该因为某个用户在弹窗上点了「允许」就失效。

反过来排会怎样？就会出现「守卫拒绝了，但审批放行了」这种组合，而 allowed-once 是一个授予。一旦授予排在拒绝之后，你就必须回答「谁赢」，而任何答案都会让某一方的语义变脏（下面那道题会逼你把两个答案都算一遍）。仓库的排法从结构上消灭了这个问题：能授予的那一层排在前面，只能拒绝的那一层排在后面，链条整体只会越走越紧。

第 10 章会专门讲守卫这一层——它怎么和 agent 作用域配合、单调性在实践中意味着什么、以及为什么这层的可测试性比 waterfall 好得多。这里先记住它在流水线上的位置和那个「没有 allow 分支」的类型。

9.6 第 4、5 关：环绕分发与工具本体

三道策略关都过了，才轮到执行。

第 4 关：tools/execute，一个「环绕」的 waterfall

环绕分发（around dispatch）：这一层的监听器不是「在执行前跑一下」，而是把执行包在自己里面——它调用 next() 得到结果，next() 前后都是它的地盘。所以它能测时间（前后各取一次时钟）、能重试（next() 失败了再调一次）、能加超时（起一个定时器，到点就中止）。

它能改的东西只有一样：exec.signal（取消信号）。而且只能替换，不能移除。文档写得很死：注册表会在调用工具本体之前，把原始调用方的 signal 和包装层替换的那个重新融合起来。

为什么？因为超时插件的做法是「换一个 5 秒后自动中止的 signal」。如果这个替换真的把调用方原来的 signal 顶掉了，那么用户按 Ctrl-C 取消整个任务时，这个工具收不到通知——它会安安静静地跑完那 5 秒。融合之后，两个 signal 任一触发都能中止。包装层可以让取消更早发生，但不能让取消不发生。

第 8 章那个「timeoutMs 不进 schema」的伏笔在这里收：定义上的 timeoutMs 是声明性的，注册表自己从不执行截止时间——README 的已知限制里明说了，执行要靠 @deepseek-ai/dsh-tool-call-timeout-policy 这个 tools/execute 包装层。工具声明预算，策略插件执行预算，两件事分在两个包里。

第 5 关：工具本体，以及它路上的两个小门

工具的 execute(args, exec) 终于跑了。它只该返回一样东西：自己声明的那个规范 JSON 值——不是内容块，不是给人看的字符串。注册表接过来之后按 output.schema 校验、冻结，再调用纯渲染器 output.render(args, value) 变成模型可见的内容。

如果工具要动文件，路上还有一道文件系统的门：fs/write-intent 或 fs/edit-intent。这两个是单槽决策 waterfall——和前面几个不一样，工具分发时给的默认 thunk 直接返回 undefined（意思是「裸提供方，无条件放行」），而监听器不调 next()，自己把决定做完；第一个返回决定的监听器拥有这次决策。

先读后编辑的策略就住在这里（插件 @deepseek-ai/dsh-fs-observation-policy）：它记录你读过哪些文件、读到的是哪个版本，然后在你要编辑一个没读过、或者读完之后已经被别人改过的文件时拦下来。注意这条策略完全不在工具流水线的七道关里——它挂在文件系统这一层，因此对所有走 ctx.fs 的工具一视同仁，不需要每个工具各写一遍。

工具还会在这一步写下自己的会话事件：fs/observed（我确认这个文件在这个版本存在／不存在）、todo/write、hook/invoked 与 hook/result、以及 Code Mode 的 tool/code-dispatch。这些是工具私有的账，和统一的 tool/result 是两回事。

9.7 第 6 关：tools/post-execute——结果出来了，还能改

工具跑完了，结果先不急着交给模型。第三个 waterfall 拿到 (exec, result, next)，返回四选一：

type PostToolDecision =
  | { kind: 'accept'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
  | { kind: 'accept'; value: JsonValue;         additionalContexts?: UserMessage[] }
  | { kind: 'block';  feedback: ContentBlock[]; additionalContexts?: UserMessage[] }

• 接受：原样放行（调 next() 就是这个）。
• 替换内容：换掉模型看到的那份文本，规范值和元数据保留。典型用途是结果太长时截断成「预览 + 一个定位符」。
• 替换值：换掉规范值，注册表会重新校验、重新渲染内容和元数据。内容和值只能替换其中一个，两个都给会抛错。
• 阻止：把纠正性的反馈变成一个 isError 结果。比如「你写的这个文件没通过 lint，先修好再说」——模型收到的是一次失败加一段能照着改的反馈。

还有一个横跨三种决定的能力：additionalContexts，往下一次请求里塞一条带来源标注的用户消息。

另一个容易忽略的细节：被前面几关拒绝的调用，也会走到第 6 关（看图 9-1 那条紫线）。这不是随手连的——它意味着一个「记录所有工具调用最终去向」的插件只需要挂在 tools/post-execute 或 tools/result 上，就能同时看到成功的、失败的和被拒的，不必去每一道关上各挂一个监听器。

但流水线自己抛出的异常不走这条路（图上的虚线）：如果第 1 关的某个监听器抛了异常，或者审批服务抛了异常，那个失败已经是最终结果，直接进第 7 关归一化，跳过第 6 关。

去实验室试试：只关掉第 6 关，让一个会被 block 的调用通过。观察模型收到的东西从「一段纠正反馈 + isError」变成了「工具的原始成功结果」——然后想想，如果这个 block 原本是你的安全策略，这一关被关掉意味着什么。

9.8 第 7 关：收尾的四件事，一件都不能少

最后这一关看起来像是「把结果发出去」，其实是四个独立动作，顺序固定。

其一：注册表外层规范化

流水线里任何地方抛出的异常——前置监听器炸了、审批服务炸了、包装层炸了、工具本体炸了、结果快照失败了、渲染器抛了、元数据投影器抛了、返回值不符合 output.schema——全部变成一个结构化的 isError 结果。

这一条的价值在于它给了上层一个极强的保证：ctx.tools.execute() 这个 Promise 只会 resolve，不会因为工具的问题 reject。调用它的循环不需要写 try/catch 去猜可能出什么错，它拿到的永远是一个 ToolExecutionResult，只要看 isError。未知工具映射成 UNKNOWN_TOOL，调用失败但不终止当前轮次——模型收到一条错误，可以自己纠正后重试。

其二：finalizeContent——工具自己的最后一道内容不变式

这是唯一一处由工具定义自己控制的收尾钩子，而它的约定很特别，值得逐条读：

• 注册表在执行开始时就把这个回调快照下来（源码注释说明了原因：参数物化过程中的 getter 有可能替换掉已注册的回调）。
• 它恰好被调用一次，对每一种归一化结果——包括那些绕过了第 6 关的流水线失败。
• 返回 undefined 表示保留原内容；其他所有结果字段仍归注册表所有，它改不了。
• 它必须是全函数，且不得抛异常。

为什么要给工具留这么一个位置？因为有些不变式只有工具自己知道。比如一个工具规定「我的输出永远不超过 N 行、永远带一个固定的结尾标记」——这条规矩必须对所有出口成立，包括「参数非法」「被拒绝」「超时中止」这些工具本体根本没跑的情况。第 6 关是别人对你的结果说话，finalizeContent 是你对自己的结果说最后一句话。

其三：tools/result——冻结的权威结果

结果被物化、冻结，然后通过 tools/result 同步通知所有观察者。这是通知，不是 waterfall：观察者只能看，不能改；观察者自己抛异常会被隔离（注册表记一条 warn 日志），不影响结果。

还有一个容易漏的点：规范值 value 只活在执行期间。循环持久化的只有 content、error 和 meta。文档说得很直白：回放可以重现展示，却无法重建规范的中间值。

其四：tool/result 会话事件，与 additionalContexts 的 FIFO 注入

最后写进会话日志的 tool/result，是面向模型的单一结果——不管中间经过了多少层改写，模型只会读到这一份。它通过 sourceEventSeqs 引用回 9.2 那条 tool/call 的序号，一问一答成对。

然后才轮到 additionalContexts：整批工具结果都记录完之后，按先进先出的顺序，把它们作为用户角色的消息注入。

为什么必须排在所有结果之后？因为模型的历史里，「工具调用块」和「工具结果」是严格配对的。如果在两条工具结果中间插一条用户消息，这对配对关系就断了。所以规矩是：先把这一批的结果按模型顺序全部记完，再统一追加上下文。

9.9 Code Mode 也走同一条路，以及这一章的落点

第 8 章提过 Code Mode：模型不直接调工具，而是写一段程序，程序里 await tools.read(...)。

那么问题来了——程序里的那些调用，是不是绕开了这七道关？

不是。docs/tool-execution-pipeline.zh.md 最后一段专门交代了这件事：Code Mode 会把保留的 run_code 传输及其序列化子调用都送进同一条流水线。子调用有四个特殊之处：

1. 携带父级 token。子调用的 parent 字段是外层 run_code 执行的不透明 token。它有两个作用：让「等外层结果」这类观察者能关联，同时标记这是一次传输子分派而不是模型直呼——在 mode: 'code' 下，只有带 parent 的调用才可以执行原生工具名，模型直呼（没有 parent）会在策略流水线之前就被判为 UNKNOWN_TOOL。
2. 记录 tool/code-dispatch。每个已结算的子调用都留一条日志，存的是渲染后的内容和 isError。这条日志的内容还能被 tools/code-dispatch-log waterfall 改写（比如结果太大时换成预览加定位符）——只改日志副本，程序拿到的值和模型看到的结果都不受影响。
3. 拒绝呈现为具有约束力的驳回。子调用被守卫拒了，程序里那次 await 会以一个真正的 ToolCallError reject，程序可以 try/catch 继续；但它拿不到内部错误码，只能读工具名和给人看的消息。
4. 省略 additionalContexts。理由写在文档里：为了保持调用与结果相邻。外层 run_code 是一次调用、一个结果；如果每个子调用都能往历史里插消息，模型看到的就是一堆插在调用和结果之间的东西。

第10章 权限：只许说不，不许说是

一句话导语：这一章不问「怎么拦住 rm -rf /」，而问一个更难的问题——凭什么保证拦截逻辑本身不会因为多装了一个插件而失效。

10.1 黑名单是错的答案

先把问题摆正。模型这一步吐出一个工具调用：bash，参数 { command: "rm -rf /" }。你要拦住它。

最朴素的做法：写一张黑名单。命令里出现 rm -rf / 就拒绝。十行代码，今天下午就能上线。

然后你会花掉接下来的一整年：rm -rf /* 不在名单上；rm -fr / 换了参数顺序；find / -delete 根本不叫 rm；python3 -c "import shutil,os;shutil.rmtree('/')" 连 shell 命令都不是；echo cm0gLXJmIC8K | base64 -d | sh 把它藏进了一串字母。你在做的事情，本质上是**猜一个比你更会写命令的东西下一步会怎么写**。这场比赛你赢不了。

最小权限原则（principle of least privilege）：只给完成当前这一件事所必需的权力，一点都不多给。不用它会怎样？你只有两种状态——「全权」和「没权」。一旦给了全权，之后每一次判断失误都是灾难性的：模型想删 build/ 却把路径拼错成 /，没有任何一层会替你兜住。

难点在于，最小权限听起来像一句正确的废话。真正难的是工程化：谁来判断「必需」？这个判断由多少段代码共同做出？当第五个团队往里塞第五段判断逻辑时，前四段的结论会不会被冲掉？

下面这张图是本章的地图。它把一次调用要穿过的几层画成同心的几道墙——这种叫法有个名字，纵深防御（defense in depth）：不指望任何一道墙是完美的，而是让每一道墙的失效方式互相不重叠。

10.2 加法只有一个方向

现在进入本章的核心。仓库里有一行类型定义，整章的重量都压在它身上（packages/core/tools/src/index.ts）：

export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined

一个单调守卫（monotonic guard）是一个函数：给它一次已经冻结好的调用（工具名、参数、callId、token 都不可改），它返回一个字符串表示「拒绝，理由是这个」，或者返回 undefined 表示「我没意见」。

注意这里没有的东西：没有 'allow'，没有 true，没有任何一种「我批准了」的返回值。这不是作者忘了写。仓库在同一处的注释里点明了原因：因为守卫没有 allow 结果，监听器顺序无法把一次拒绝重新变回许可。

组合：为什么「只能减，不能加」是一个可以证明的性质

把每个守卫看成一次对「允许集合」的操作。守卫只能拒绝或弃权，意味着它对这个集合只能做一件事：拿掉一些元素，或者什么都不做。永远不会往里加。

于是，无论你装多少个插件、它们以什么顺序注册、谁先谁后，最终的允许集合都是所有守卫各自结果的交集。交集有一个小学生就能验证的性质：再交一个集合，只会更小或不变，绝不会变大。

这就是「单调」二字的含义：沿着「注册的守卫越来越多」这个方向，「被允许的调用」这个集合单调不增。你不需要读懂那五个插件各自写了什么，就能对整体下这个结论。在一个由不同团队、不同来源的插件拼起来的系统里，这种「不用读就能下的结论」贵得离谱。

反例：如果守卫能放行会怎样

不要接受一句抽象的「那样就不安全了」。我们把它具体化。假设 ToolGuard 的返回类型改成 'allow' | string | undefined，第一个给出非 undefined 答案的守卫说了算。现在有两个守卫：

• 守卫 A（安全团队装的）：如果命令里带 --force，返回 '禁止强制推送'。
• 守卫 B（某个「效率插件」装的）：如果当前 agent 是它自己创建的子 agent，返回 'allow'——作者的想法很朴素：「我自己的子 agent 我信得过，别老弹窗打断它。」

两个作者各自都写得没错，都通过了自己的测试。装到一起之后，发生的事情取决于注册顺序：

请盯住最后一列。安全团队读自己的代码读不出问题；效率插件的作者读自己的代码也读不出问题。故障只存在于「两者拼装时的顺序」里，而顺序取决于 cordis.yml 里那几行的先后，也取决于谁先被 HMR（热模块替换）重载过一次。这种 bug 的排查成本极高，因为它不在任何一个人的代码里。

更糟的是它的失败方向：拼错顺序的后果是放行，而且没有任何一处会报错。系统安安静静地变得更松，直到有人事后从日志里发现。

把 allow 从类型里删掉，这一整类 bug 就在类型层面消失了。没有 allow 分支，就没有「谁的 allow 盖过了谁的 deny」这个问题；顺序不再影响结果，只影响你先看到哪一条拒绝理由。仓库里 guardReason() 的实现因此只有五行：从头走一遍，谁先返回字符串就用谁的理由，全都返回 undefined 就放过——它甚至不需要知道「放过」意味着什么，因为那不是它的决定。

下面这个实验室把守卫这一层单独拎了出来，并且给了你一个危险开关：把「单调」这条约束关掉，让守卫能返回 allow。请务必去点它。先注册一个拒绝的守卫，确认调用被拦下；然后打开开关，再加一个总是 allow 的守卫，把它拖到前面——看着刚才那条拒绝被吃掉。你需要亲眼见一次「越权」长什么样，后面所有关于顺序的讨论才有分量。

10.3 答不上来的时候，锁死还是敞开

守卫解决了「策略之间不打架」，但它有一个先天限制：它是同步函数。ToolGuard 的返回类型是 string | undefined，不是 Promise。同步意味着它不能等：不能等网络，不能等磁盘，更不能等一个人抬头看屏幕。

可是「问人」恰恰是权限系统里最重要的一件事。于是仓库把它单独做成一层：ctx.approval（源码 packages/interaction/user-approval/src/index.ts，全文 347 行）。

一次性询问（one-shot approval）：服务把一个请求发给已组合的应答者链，拿回一个结果。结果的类型只有四个取值，而其中只有一个是许可：

type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'

allowed-once——名字里就写着 once。它只授权所询问的那一个操作：这一个 callId、这一次调用。它不是一张通行证，不会被记住，下一次同样的命令要重新问。另外三个值，调用方一律当作拒绝。

fail-closed 与 fail-open：两个词，两种世界观

默认拒绝（fail closed）：当系统无法得到答案时，按拒绝处理。默认放行（fail open）：无法得到答案时，按允许处理。

这两个词的分界线不在「有人说不」，而在「没人说话」。真正决定一套权限系统性格的，正是它在沉默时的选择。仓库把这四种沉默逐一钉死，全部倒向拒绝：

把第三列连起来读一遍，你会发现 fail-open 的共同特征：让系统更容易出错的那一方，同时也是获得更多权限的那一方。这在安全设计里是最不该出现的激励结构。仓库源码里那两行注释直白得几乎是在喊：a missing or throwing answerer yields 'unavailable' (fail closed)；a throwing answerer must fail the QUESTION closed, not the caller's tool call open——应答者炸了，炸的是这个问题，不是把调用方的工具调用敞开。

10.4 为什么问人这一步排在守卫前面

第 9 章给过顺序：第 2 关是 ctx.approval，第 3 关才是单调守卫。为什么不反过来？直觉上，「人都同意了」听起来应该是最高权威，理应排在最后一锤定音。

仓库把这句话写在 docs/tool-execution-pipeline.zh.md 里：「ctx.approval 在单调守卫之前处理询问，而不得重新排序的所有者策略仍作为已注册的守卫。」

拆开这句话。它说的是两件事的分工：

• 可以被人推翻的东西，放在审批之前或之中——比如某个钩子说「这个操作有风险，问一下」，人说「可以」，那就继续。
• 不该被人推翻的东西，放在审批之后，也就是守卫这一层。这些是所有者策略（owner policy）：部署方、平台方定下的红线。

如果顺序反过来会怎样？守卫先跑，弃权；然后弹窗问人，人点了「允许」——于是这次调用带着一个已经作废的守卫结论走进了工具本体。整条红线形同虚设，因为红线的判定发生在获得许可之前。反过来，守卫排在审批之后，人的「允许」只能把调用送到守卫面前，送不过去。

同一个「顺序不能被绕过」的执念，在审批服务内部又出现了一次。会话的审批策略有两个取值，其中 'never' 表示确定性拒绝。这个判断写在服务自己的 request() 路径里，在 waterfall 分发之前。源码注释解释了为什么不能把它做成一个监听器：

// The 'never' policy is decided HERE, before any dispatch: a listener
// registered with `prepend: true` after this service mounts would sit
// ahead of any gate LISTENER, so a listener-shaped gate cannot keep the
// documented promise that 'never' rejects deterministically regardless
// of registration order — only the service's own request path can.

翻译成人话：Cordis 允许一个后来的插件用 prepend 把自己插到监听器链的最前面。如果 'never' 只是链上的一个监听器，那么任何一个后加载的插件都能抢在它前面把请求认领走，「永不询问」的承诺当场作废。所以它必须待在链之外。

10.5 预设：把两个开关捆成一句人话

到这里你已经见到两个互相独立的旋钮：

• 沙箱模式（sandbox/mode）：read-only / workspace-write / danger-full-access——管的是文件效果。
• 审批策略（approval/policy）：ask / never——管的是要不要问人。

两个旋钮各三档和两档，组合起来六种。现在把它们摆到一个真实用户面前，让他自己选——大部分人会在第一个下拉框就卡住，因为 workspace-write 这个词对他来说不是一个决定，是一道题。

权限预设（permission preset）：一组预先配好的旋钮取值，起一个人能看懂的名字，客户端把它做成一个选择器。仓库的默认表只有两项（packages/interaction/permission-presets）：workspace-write（沙箱 workspace-write + 审批 ask）和 danger-full-access（沙箱 danger-full-access + 审批 never）。

要抓住的关键是：预设自己不执行任何强制。执行、提示词叙述、回放，读的仍然是各自旋钮折叠出来的结果。预设只是一层「组合与命名」。这一点值得记住——一个只做命名、不做强制的层，替换或删掉它都不会让系统变得更松。

10.6 第二堵墙：就算做了也跑不出去

前面所有机制都在回答同一个问题：要不要做。它们共享同一个前提——harness 能够看到并拦住这次操作。这个前提有一个明显的缺口：一旦 bash 真的把一个进程 spawn 起来了，那个进程接下来干什么，harness 就管不着了。它可以自己再 fork，可以读任何它有权读的文件，可以把你的 ~/.ssh 打包发出去。

所以需要第二类防线，它不回答「要不要做」，只回答「做了能跑多远」。这就是沙箱。

进程沙箱（process sandbox，ctx.sandbox）：消费方交出即将 spawn 的那一串确切 argv，沙箱提供方把它包装成另一串 argv 还给你，你 spawn 包装后的那一串。真正的强制不在 JavaScript 里，在操作系统内核里——Linux 上是 bwrap 或 Landlock，macOS 上是 Seatbelt，Windows 上是 ACL 受限令牌。

「包装 argv」这个做法值得多看一眼。它意味着沙箱层完全不需要理解命令的语义：不解析 shell 语法，不识别危险模式，不做任何猜测。它只是把 ['bash','-c','rm -rf /'] 变成 ['bwrap','--ro-bind','/','/', '--bind', workspaceRoot, workspaceRoot, '--', 'bash','-c','rm -rf /'] 这样的东西（示意，实际参数由提供方与平台决定）。命令照跑，删除照做，但内核在系统调用那一层把写操作挡掉。

三件必须知道的事实

一、这一层同样是 fail-closed。没有可用后端时，confine() 抛 SandboxUnavailableError（错误码 SANDBOX_UNAVAILABLE），执行被拒绝。仓库的原话是：对于受限策略，静默的无隔离透传永远不合法。也就是说，「沙箱装不上，那就先不隔离跑着吧」这条路被明确封死了。

二、强制的完整度是一个要如实上报的事实。后端返回的 enforcement 有两档：full 表示这个模式承诺的文件效果全都管住了；partial 表示当前后端或较旧的内核 ABI 只管住了一部分。仓库要求「需要绝对保证的消费方必须拒绝或把这个区别向上暴露，不得当作 full」。当前已知的 partial 情形包括较旧的 Landlock ABI，以及 Windows ACL runner 的 Everyone 与硬链接边界。

三、模式只管文件效果。SandboxMode 的三档管的是文件读写，网络与进程可见性不在这套词汇的定义范围内。这句话必须原样记住：在 read-only 沙箱里跑起来的进程，仍然可能访问网络。如果你的威胁模型里包含「把数据外传」，沙箱模式这一层不解决它。

10.7 没读过就不许改，以及看不见的工具

先读后改

还有一类风险，前面所有机制都拦不住：模型凭想象改文件。它以为某个配置文件长什么样，直接 write 一份新的覆盖上去——文件其实早就变了，或者内容跟它想的完全不同，于是一次「修改」变成了一次静默的数据丢失。这不是权限问题，是新鲜度问题。

仓库的做法是把这件事做成两个单槽决策 waterfall（packages/fs/fs）：fs/write-intent 和 fs/edit-intent。工具在真正调用 ctx.fs.writeText() / editText() 之前分发它们，由策略插件 dsh-fs-observation-policy 认领并给出一个守卫值。策略插件内部维护一张「谁看过哪个文件的哪个版本」的表，规则是：

为什么 write 和 edit 待遇不同？因为语义不同。write 是「我给出全文」——如果文件本来就不存在，模型不需要读过它也能安全地创建；只有在文件已存在时才要求版本匹配，避免覆盖掉别人的改动。edit 是「把这段文本换成那段」——它的正确性完全依赖于模型对当前内容的认知，没读过就编辑，本质上是在猜。所以未见即拒绝，没有安全的降级方式。

看不见的工具

最后一件事，也是最容易误解的一件。tools.restrict() 可以为单个 agent 过滤全局工具集合（多个 restriction 取交集），而 scope-local 注册在过滤之后合并。glossary 里这句话要一字一句地读：

restriction / scope-local 注册：被过滤掉的全局工具既不出现在提示词中，也拒绝执行，与不存在的工具无法区分。

「无法区分」这四个字是设计目标，不是实现巧合。它意味着模型收到的错误是 UNKNOWN_TOOL（未知工具），跟它调用一个纯粹拼错的名字得到的错误一模一样。为什么要这样？因为任何形如「这个工具存在，但你没有权限用」的回答，都在向模型泄露它本不该知道的信息，而且会诱导它去反复尝试、去请求提权、去绕路——把一次干净的「没这个东西」变成一场拉锯。

10.8 这一章里五件不牢靠的事

前面七节讲的都是「设计上应该怎样」。这一节讲实际怎样。以下五条每一条我都回仓库核实过，也给了路径，你应该自己再验一遍——它们全都是那种「读文档读不出来、出事时才发现」的东西。

一、never 的命名坑（前面已埋，这里钉死）

ApprovalPolicy 的 'never' = 永不询问 = 一律拒绝，是更严的一档。源码：packages/interaction/user-approval/src/index.ts 的 ApprovalPolicy 注释与 decide()。把它读成「不用问，直接过」的人会在生产环境里得到一台什么都做不了的机器，而且日志里全是「用户拒绝」。

二、isConcurrencySafe 是工具的自我声明，无人校验

工具定义里可以带一个 isConcurrencySafe(args) 分类器，只有它恰好返回 true 时这次调用才允许并发执行，其他一切结果（未声明、返回非 true、抛异常）都按独占处理——这一半是稳的（fail-closed）。不稳的那一半是：没有任何人检查这个 true 是不是在说谎。工具说自己并发安全，注册表就信；它不做静态分析，不做运行时检测。仓库在 packages/core/tools/README.zh.md 的「已知限制与暂缓事项」里明说：并发策略不是事件门禁——executionMode() 直接读已解析的工具定义，插件只能在自己拥有的定义上声明分类器，别人管不着。所以一个写错的 isConcurrencySafe 造成的数据竞争，权限层一点忙都帮不上。

三、timeoutMs 是声明性的，不装策略包就完全没有超时

工具定义上的 timeoutMs 只是策略元数据。同一份 README 的限制清单里写着：注册表绝不会强制执行截止时间；要真的有超时，必须把 @deepseek-ai/dsh-tool-call-timeout-policy 这个包装层加进组合。也就是说，你可以有一个声明了 timeoutMs: 5000 的工具，在一个没加载该插件的部署里跑上一整天，没有任何警告。而且即便加载了，它也只是协作式的：派生信号只负责通知，工具自己不转发 exec.signal 就不会停——该包 README 的原话是「声明 timeoutMs 意味着与 exec.signal 协作」。

四、fs 单槽的归属是部署约定，不是强制不变式

docs/subsystems/filesystem.zh.md 的原话：fs/write-intent 与 fs/edit-intent 是单槽决策 waterfall，监听方完全决策而不调用 next()，该 slot 按注册顺序先到先得——由策略插件占据是部署约定，而非强制不变式。翻译一下：先注册的插件可以抢走这个决策位，让先读后改的检查整个不生效，而系统不会报任何错。同一份文档还提醒：加载了 dsh-tool-fs 的部署也应加载 dsh-fs-observation-policy——「应」是建议语气，不是强制。少装一个插件，write 就退回无条件覆盖、edit 退回无条件替换。

五、被拒绝的调用不会执行守卫

这条是我在源码里读出来的，文档没有专门讲。packages/core/tools/src/index.ts 的 prepareExecution() 里只有一行：

const denialReason = decision.kind === 'allow'
  ? this.guardReason(exec)
  : decision.reason

看清楚这个三元表达式：只有在前面的决定是 allow 时，才会去跑守卫。如果 tools/pre-execute 已经拒绝了，或者审批没通过，guardReason() 根本不会被调用。这有它的道理（已经拒了就没必要再问一遍），但它有一个不显然的后果：守卫不是一个能统计所有被拒调用的观察点。如果你想写一个「记录所有被拦下的危险尝试」的插件，把它写成守卫是错的——它只能看到那些「通过了前面所有关卡、最后被自己拦下」的调用。要看全，得挂到 tools/post-execute（第 9 章讲过，被拒的调用仍然会进这一关）或者读会话日志里的 tool/call / tool/result 对。仓库自带的 dsh-repeat-tool-reminder 就是这么干的，它的 README 明确写着「被拒绝的调用也计数。检测位于 tools/post-execute」。

第11章 能力 seam：换一个提供方，等于换一个世界

一句话导语：怎么让「在我的电脑上跑一条命令」和「在一台远程沙箱里跑同一条命令」变成同一件事，而调用它的那段代码一个字符都不用改。

11.1 一件小事：把命令跑到别的地方去

你的 harness 里有一个 bash 工具。今天它在你的笔记本上跑命令。现在来三个需求：

1. 公司要求：所有命令必须在沙箱里跑（第 10 章那套）。
2. 某个客户要求：命令必须跑在一台远程 Linux 机器上，本地一个进程都不许起。
3. Windows 用户要求：用 PowerShell，不是 bash。

最朴素的做法：在 bash 工具里加分支。

// 反面教材
async function execute(args) {
  if (config.remote) {
    return runOnRemote(args.command)          // 远程
  } else if (config.sandbox) {
    return runSandboxed(args.command)         // 沙箱
  } else if (process.platform === 'win32') {
    return runPowerShell(args.command)        // pwsh
  }
  return runLocal(args.command)               // 本机
}

今天它能跑。问题在明天。

第一个问题：分支会传染。不只是 bash 工具需要知道「现在在哪跑」。持久终端（PTY）需要知道，语言服务器（LSP）需要知道，读写文件的工具需要知道，跑测试的后台任务需要知道。每一个都要抄一遍这套 if。四个消费方 × 四种执行环境 = 十六段几乎一样但细节各有出入的代码，而且它们会各自演化，直到没有人敢说清「远程 + Windows」这一格到底是什么行为——因为那一格从来没有人跑过。

第二个问题：加一种环境要改所有人。客户明天说要跑在容器里。你得回到这四个文件，各加一个分支，各写一遍测试。而这四个文件很可能不归你管。

第三个问题：也是最要命的——你无法只替换一部分。「远程执行 + 本地沙箱策略」这种组合，在 if 的写法里是表达不出来的，因为分支是互斥的。

接口与实现分离（separating interface from implementation）：把「能做什么」和「怎么做到」拆成两样东西。调用方只对着「能做什么」编程，永远不知道也不需要知道背后是谁在做。不用它会怎样？就是上面那三个问题：分支传染、改动扩散、组合爆炸。

11.2 定义：三种角色，缺一个就不成立

这个词在仓库里有严格定义，写在 docs/glossary.zh.md 的 capability-seam 一节。下面这段是原文照抄，一个字没改——请先读一遍，再看拆解。

把它拆成三块。

一、Service Definition（服务定义）。它拥有一个 ctx.<key>——比如 ctx.shell——以及这项能力的全部词汇：请求长什么样、结果长什么样、失败有哪几种。它不实现任何东西。

二、Service Provider（服务提供方）。真正干活的那个。一个或多个。

三、Consumer（消费方）。注入并使用这项能力的人。一个或多个。通常是一个面向模型的工具。

为什么「绝不是 TypeScript interface」

这句话在定义里被特意加粗强调，值得单独讲——它是整章最容易被略过、也最容易被做错的一句。

TypeScript 的 interface 是一个纯编译期的东西。tsc 一编译，它就消失了，运行时的 JavaScript 里没有任何痕迹。你不能问「这个 interface 现在的实现是谁」，因为运行时压根没有「它」。

而 seam 需要的恰恰是运行时的能力：

• 能被查到。消费方在运行时通过 ctx.shell 拿到当前实现；换了提供方，同一个表达式拿到的是另一个对象。
• 能被注入。inject: ['shell'] 声明的是一种依赖关系：没有提供方时消费方插件不启动，有了才启动，提供方走了它再停掉。这套生命周期只有运行时的服务才有（第 2、3 章讲过）。
• 能拒绝重复。ShellExecutor 的类注释写着：一个上下文只能有一个实现，装第二个会抛——这是 Cordis 对重复服务的标准行为。TypeScript 的 interface 不可能提供这条保证，因为它连「装」这个动作都没有。
• 能有生命周期。提供方被 HMR（热模块替换）换掉时，依赖它的消费方要一起重启；后台进程要不要被杀，取决于边界画在哪。

所以定义里说它是「一个 Cordis Service」——可以是抽象类（ShellExecutor extends Service，提供方去继承它），也可以是具体的注册表（像 WebRuntime 那样，提供方往里注册条目）。两种形态的共同点是：它在运行时真实存在，占着一个 ctx 的键。

11.3 规范范例：packages/shell 的四个包

定义里点名说 packages/shell 是规范范例。我们把它翻开，一个包一个包看。下面的行数是我自己数的：src/ 目录下所有 .ts 文件的总行数，含注释与 JSDoc（这个仓库的 JSDoc 密度很高，行数里有相当一部分是文档）。

dsh-shell —— Service Definition，350 行，4 个文件

它拥有 ctx.shell，什么都不实现。350 行里：

• types.ts（183 行）：全是词汇。ShellExecRequest（调用方的请求）、ShellExecSpec（解析后的规格）、ShellRunResult（前台运行的结果）、ShellProcess（后台进程句柄）、ShellSandboxInfo（沙箱事实）。一行可执行逻辑都没有。
• index.ts（103 行）：抽象类 ShellExecutor extends Service，构造函数只有一句 super(ctx, 'shell')；三个抽象方法 resolve / run / start；一个能力事实 get sandboxMode()（默认返回 undefined，表示「我不做隔离」）；外加这项能力的 settings 命名空间。
• render.ts（42 行）：parseExitStatus——两个 shell 工具共享的退出状态解析。
• invariant.ts（22 行）：运行时不变量检查。