": …`——**违规可归属，而注册表不需要 import 任何产品包**。
- 检查在专属子 fiber 里跑，`installer.inject` 声明该 fiber 能访问哪些服务。
- 可用正则白/黑名单选择启用哪些包的检查，**黑名单胜过白名单**；配置非法（空串、带空格、重复、正则无效）在服务启动时**抛错而不是跳过**。
最讲究的是**它规定了检查可以断言什么**（`AGENTS.md`）：
> **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, **not** service or method presence, plugin metadata or effects, or fixed pure examples. Without a plausible relationship, an explained empty companion is correct.
翻译：不许写"检查 `ctx.shell` 是否存在"这种**假装在检查**的断言。没有可断言的真实关系时，**正确做法是导出一个空的 installer，并用注释解释为什么这个包没什么可检查的**——注释必须以 `No runtime invariant:` 开头。
而且这条也被机器守着：`pnpm run verify-package-invariants` 会拒绝「生成的占位标记」「没解释的空 installer」「非空 installer 却忽略了 reporter」「注册名写错」。
这就是为什么 `dsh-invariants` 被 **218 个包**依赖——241 个包里 90%。我在本系列 21 个项目里没见过第二个这么做的。
### 怎么验收
不变量的验收方式很特别：**你得先违反它，看它变红**。这正是 dsh 测试宪法里那条（`docs/testing.md:34`）：
> A guard only guards if the regression actually fails it. … introduce the regression, watch red, revert.
```ts
// 故意绕过日志
request.messages.push({ role: 'user', content: '偷偷加的' })
try {
assertModelVisibleIsLogged(session, request)
console.assert(false, '不变量没抓到违规——它是假的')
} catch (e) { /* 期望：抓到 */ }
```
---
Part 3 · 第 8–13 步造循环：turn 与 step
第 8 步 · turn 与 step：一个循环，两级边界
### 为什么
第 0 步那个 `main()` 的 while 只有一级。一级不够，因为有两个不同的问题要回答：
1. "这次模型请求之后还要不要再请求？"（工具跑完了要把结果喂回去）
2. "这一整轮对话结束了吗？"（用户还有没有新输入、插件还欠不欠事情）
混成一级的后果是：你没法表达"这一轮结束了，但因为有插件塞了新东西，所以要继续"。
dsh 的定义（`docs/architecture.md:65`）：
> A **step** is one model request plus the tools it calls. A **turn** is zero or more steps: it opens before its first input is claimed and closes once nothing is owed.
**"a turn is zero or more steps"** —— 零个 step 的 turn 是合法的，这是个刻意的设计（下一步会讲为什么）。
### 完整流水线
```mermaid
sequenceDiagram
participant IN as inbox
participant D as driver（循环）
participant SP as systemPrompt
participant L as 会话日志
participant M as ctx.llm
participant T as ctx.tools
D->>L: append turn/start
loop 每个 step
D->>IN: claim(target, turn)
D->>SP: assemble()（提示段 + 工具 schema）
D->>D: agent/pre-step（waterfall：reject | enter）
Note over D: reject 或首次 enter 被改空
→ 关掉这个「零 step」的 turn
D->>L: append step/start
D->>L: append user/message ×N
D->>L: deriveMessages()
D->>D: agent/request（waterfall：定 provider/model/参数）
D->>M: stream(request)
M-->>L: append assistant/chunk ×N（每片都记）
D->>L: append assistant/message（带 sourceEventSeqs）
alt 命中 max-tokens
D->>D: 结束（sticky）
else 没有 tool call
D->>D: completed
else 有 tool call
D->>T: 执行（三道 waterfall，见第 11 步）
T-->>L: append tool/call + tool/result
end
D->>L: append step/end
D->>D: agent/turn-stopping（serial）—— 插件最后的机会
Note over D,IN: 还欠事情？（inbox.nextStep 非空）→ 继续下一 step
end
D->>L: append turn/end（结构化 reason）
```
### 最小实现
```ts
// minidsh/loop.ts
type TurnEndReason =
| { kind: 'completed' } | { kind: 'max-tokens' } | { kind: 'blocked' }
| { kind: 'aborted' } | { kind: 'error'; error: unknown }
export class Loop {
private turnNo = 0
constructor(private ctx: Context, private session: Session, private inbox: Inbox) {}
/** 外层：turn 返回 true 表示 inbox 还有东西，继续开新 turn。 */
async run(): Promise {
while (await this.turn()) { /* 空 body 是故意的：条件即语义 */ }
}
private async turn(): Promise {
const turn = ++this.turnNo
this.session.append('turn/start', { turn })
let reason: TurnEndReason | null = null
let target: InboxTarget = 'next-turn'
let stepNo = 0
try {
while (true) {
const step = stepNo + 1
const decision = await this.preStep(target, turn, step)
if (decision.kind === 'reject') { reason = { kind: 'blocked' }; return false }
if (reason && decision.messages.length === 0) break
// 被清掉的唤醒消息、或被改写成空的 enter，仍然拥有这个 turn 边界，
// 但它不花模型调用——日志因此记下了「这次尝试」。
if (stepNo === 0 && decision.messages.length === 0) {
reason = { kind: 'completed' }; return false
}
this.session.append('step/start', { turn, step })
stepNo = step
try {
for (const m of decision.messages) this.session.append('user/message', m)
const stepEnd = await this.step(decision.assembly, turn, step)
// max-tokens 是 sticky 的：后面正常完成的 step 不能把它降级。
if (reason === null || reason.kind !== 'max-tokens') reason = stepEnd ?? reason
} finally {
this.session.append('step/end', { turn, step })
}
// 停之前给插件最后一次机会往 inbox 塞东西（goal / continuation 靠它）
if (reason && this.inbox.nextStep.length === 0) {
await this.ctx.bus.serial('agent/turn-stopping', { turn })
}
if (reason && this.inbox.nextStep.length === 0) break
target = 'next-step'
}
} catch (error) {
reason = { kind: 'error', error }
throw error
} finally {
this.session.append('turn/end', { turn, reason: reason ?? { kind: 'completed' } })
}
return this.inbox.hasPending
}
}
```
### 四个刻意的设计，逐个解释
**① 零 step 的 turn 也要记进日志。**
```ts
if (stepNo === 0 && decision.messages.length === 0) { reason = { kind: 'completed' }; return false }
```
用户按了发送，但某个插件把消息拦空了。这时**仍然开一个 turn 并正常关掉它**。为什么？因为「用户发起过一次尝试」本身是一个需要被记录的事实。architecture.md 明写：「*a rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt*」。
如果不这么做，UI 上会出现"我明明发了消息，但什么都没发生"的鬼故事，而日志里查不到任何痕迹。
**② `max-tokens` 是 sticky 的。**
真实源码里这条注释出现了两遍（`agent.ts:285-289`），可见作者很在意：
> max-tokens is sticky: once any step hits the ceiling, later steps that complete normally must not downgrade the turn outcome.
一个 turn 里第 3 步撞了输出上限，第 4 步正常结束——这个 turn 的结论必须是"撞了上限"，不能是"完成"。因为下游（UI 提示、重试策略、评测）要据此判断结果是否可信。
**③ `agent/turn-stopping` 检查两次。**
```ts
if (reason && this.inbox.nextStep.length === 0) { await serial('agent/turn-stopping', …) }
if (reason && this.inbox.nextStep.length === 0) break // ← 再查一次
```
第一次判断"要停了"，于是发 serial 事件；发完**再查一次** inbox。因为 `agent/turn-stopping` 的 listener 完全可以往 inbox 里塞新东西——这正是 goal 插件让循环继续的机制（第 18 步）。
这是"如何在不改循环的前提下让循环继续"的标准答案：**给循环一个"我要停了"的公告时刻，任何人都能在这一刻提出异议。**
**④ `turn/end` 在 `finally` 里，reason 是结构化的。**
无论正常结束、被取消、还是抛异常，`turn/end` 必发。而且失败是结构化的（`agent.ts:307-314`）：`LlmError` 保留它的事实，其它一切 flatten 成 `errorChain` 文本 + `code: 'UNKNOWN'`。
**永远不要让一个 turn 在日志里没有结尾。**否则重放逻辑要处理"半个 turn"，而那是无底洞。
### 真实 dsh 在哪儿
`packages/core/agent-loop/src/agent.ts`（496 行）。外层 `while (await this.turn()) {}` 在 `:212`，`turn()` 在 `:246`，`step()` 在 `:332`。
顺带一个彩蛋：源码里能看到 `/* v8 ignore next -- private callers establish the running phase before executing a step */` 这类注释（`agent.ts:333`）。这是 **100% 逐文件覆盖率门禁**留下的痕迹——不可达的防御分支必须显式标注**并说明理由**。见第 20 步。
---
第 9 步 · inbox：两个投递口决定"欠不欠"
### 为什么
第 8 步的循环里反复出现 `inbox.nextStep.length === 0`。这个 inbox 是什么？
它解决一个很具体的问题：**输入不是只从用户来**。至少有四个来源：
1. 用户敲的消息 → 应该立刻唤醒循环
2. 工具执行产生的附加上下文（比如"文件已被外部修改"）→ 应该在下一个 step 就被看到
3. 后台作业完成通知 → 不该打断当前 step，但要尽快
4. 插件注入的上下文（`agent.inject()`）→ 应该等到有别的消息时一起进去
第 4 种最微妙。architecture.md 这句话点出了区别（`:86`）：
> Input reaches the driver through one inbox. Some messages wake it immediately; **injected context waits in the inbox until another message does**.
**注入的上下文不主动唤醒循环**——否则你每注入一句"当前分支是 main"就会触发一次模型调用，那会烧钱且莫名其妙。
### 最小实现
```ts
// minidsh/inbox.ts
export type InboxTarget = 'next-turn' | 'next-step'
export class Inbox {
/** 下一个 turn 开始时才领取的（普通用户消息）。 */
private turnQueue: Message[] = []
/** 当前 turn 的下一个 step 就要领取的（工具上下文、后台通知）。 */
readonly nextStep: Message[] = []
/** 唤醒型投递：进 turn 队列，并请求唤醒 driver。 */
send(message: Message): void {
this.turnQueue.push(message)
this.onWake?.()
}
/** 注入型投递：进 turn 队列但不唤醒——等别的消息把它带进去。 */
inject(message: Message): void {
this.turnQueue.push(message)
}
/** step 内投递：当前 turn 的下一个 step 立刻可见。 */
spliceNextStep(message: Message): void {
this.nextStep.push(message)
}
/** 领取。两个投递口对应两种 target。 */
claim(target: InboxTarget, _turn: number): Message[] {
if (target === 'next-step') return this.nextStep.splice(0, this.nextStep.length)
return this.turnQueue.splice(0, this.turnQueue.length)
}
get hasPending(): boolean {
return this.turnQueue.length > 0 || this.nextStep.length > 0
}
onWake?: () => void
}
```
于是第 8 步循环里 `target` 的变化就有了意义：
```ts
let target: InboxTarget = 'next-turn' // turn 的第一个 step 领 turn 队列
// …一个 step 结束后…
target = 'next-step' // 后续 step 领 step 队列
```
### 工具怎么往里塞东西
真实 dsh 的 `executeToolCalls` 第六个参数就是这个投递回调（`agent.ts:395-398`）：
```ts
const { concluded } = await executeToolCalls(
this.loopCtx, turn, step, toolCalls, signal,
context => this.inbox.splice('next-step', this.inbox.nextStep.length, 0, [context]),
)
return concluded ? { kind: 'completed' } : null
```
这就是工具流水线里 `tools/post-execute` 的 "add context" 决策落地的地方：工具跑完可以说"顺便告诉模型一件事"，这句话变成 inbox 的 next-step 项，**在记录的工具结果之后**注入。
`concluded ? completed : null` 也值得看：返回 `null` 表示"工具还欠一次请求"，于是外层 while 继续下一 step。**"欠不欠"是工具批次自己报告的**，不是循环猜的。
### 怎么验收
三种投递的行为差异必须能测出来：
```ts
const inbox = new Inbox()
let woke = 0; inbox.onWake = () => { woke++ }
inbox.inject({ role: 'user', content: '当前分支 main' })
console.assert(woke === 0, 'inject 不该唤醒')
inbox.send({ role: 'user', content: '修 bug' })
console.assert(woke === 1, 'send 应该唤醒')
console.assert(inbox.claim('next-turn', 1).length === 2, '一起被领走')
inbox.spliceNextStep({ role: 'user', content: '文件被外部改了' })
console.assert(inbox.claim('next-step', 1).length === 1, 'step 口独立')
```
### 真实 dsh 在哪儿
`Inbox` 在 `packages/core/agent/src/`（由 `dsh-agent` 导出，`agent.ts:18` 引入）。
真实实现还有一层我在 minidsh 里简化掉了的东西：**wake latch**（`agent.ts:164-193`）。当 driver 处于 maintenance 阶段或已被 abort 时，它无法投递唤醒，于是把唤醒**latch 住**，等收敛时重放；而 **disposal 从不 latch**——"so teardown waits on no model turn"（拆卸不等任何模型轮次）。
这类"拆卸不能被业务逻辑拖住"的细节，是长期跑在生产里的 harness 和 demo 的分水岭。
---
第 10 步 · `agent/pre-step`：决定模型看什么
### 为什么
现在循环会领消息了。但"领到的消息"和"发给模型的消息"之间需要一道闸门，理由：
- 权限：这个 agent 在计划模式下，不许提交任何变更
- 改写：把用户的相对路径补成绝对路径
- 注入：把当前工作目录、git 分支、待办列表拼成一段上下文
- 拦截：这个会话被管理员暂停了，直接拒
architecture.md 的定位（`:88`）：
> `agent/pre-step` decides what the model sees. Listeners may rewrite the claimed messages or reject them outright.
### 最小实现
```ts
// minidsh/loop.ts（续）
type PreStepDecision =
| { kind: 'reject' }
| { kind: 'enter'; messages: Message[] }
private async preStep(target: InboxTarget, turn: number, step: number) {
const claimed = this.inbox.claim(target, turn)
// 每个 step 都重新装配：工具集与提示段可能已经变了（见第 13 步）
const assembly = await this.ctx.get('systemPrompt').assemble()
const context = this.runtimeContext.project(assembly.sections)
const decision = await this.ctx.bus.waterfall(
'agent/pre-step',
{ messages: claimed, turn, step },
async () => ({
kind: 'enter',
messages: context === undefined ? claimed : [...claimed, context],
}),
)
return decision.kind === 'reject' ? decision : { ...decision, assembly }
}
```
三个要点：
**① seed 函数才是默认行为。** waterfall 的第三个参数是"没有任何 listener 干预时会发生什么"。默认行为 = 领到的消息 + 一段运行时上下文。这个写法让"默认"变得**显式**，而不是藏在某个 `?? default` 里。
dsh 的宪法专门有一条讲这个（`AGENTS.md`）：
> **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()`.
**② 运行时上下文是"投影"出来的，不是拼字符串拼进 system prompt 的。** 它作为一条额外消息跟在 claimed 后面。这样它就是**日志可见**的（第 7 步的不变量要求）。
**③ 每个 step 重新 assemble。** 不是每个 turn 一次。因为工具集可能在 turn 中途变化（一个子 agent 起来了、计划模式退出了、动态插件挂载了新工具）。
### 怎么验收
```ts
// 一个"计划模式"插件：拒绝一切写操作请求
ctx.bus.on('agent/pre-step', async (arg, next) => {
if (planMode.active && arg.messages.some(m => /提交|commit/.test(m.content))) {
return { kind: 'reject' }
}
return next()
})
```
验收点：`reject` 之后日志里应该出现一个 `turn/start` + `turn/end{reason:'blocked'}`，中间**没有** `step/start`。
### 真实 dsh 在哪儿
`packages/core/agent-loop/src/agent.ts:225-243`。真实版本比我这个多两处：`signal.throwIfAborted()` 在 assemble 前后各一次（取消要尽早生效），以及 `assembly` 会被一路带到 `step()` 里去（避免重复装配）。
---
第 11 步 · 工具注册表与三道 waterfall
### 为什么
工具执行是 agent 里最需要插拔的地方。要挂在这条路上的东西太多了：权限、审批、沙箱、超时、重试、指标、结果改写、UI 渲染、文件读写策略、hook 桥接……
如果全塞进 `runTool()`，那个函数会变成一千行的泥球。
dsh 的做法是把工具执行拆成**三道 waterfall + 一道单调守卫 + 一次冻结通知**。生成的流水线图（`docs/tool-execution-pipeline.md`）开头一句话点明设计目标：
> This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run **without changing the loop**.
### 完整流水线
```mermaid
flowchart TD
A["assistant 消息里有 tool-call"] --> B["append tool/call
（执行前就记日志）"]
B --> C["UI：presentCall(args) 待处理卡片"]
B --> D["tools/pre-execute（waterfall）
hooks · 权限 · 沙箱"]
D -->|allow| E["注册的单调守卫
只能 deny 或弃权"]
D -->|deny| X["跳过工具体"]
D -->|ask| F["ctx.approval 一次性询问"]
F -->|allowed-once| E
F -->|拒绝/取消/不可用| X
E -->|allow| G["tools/execute（waterfall · around）
超时 · 重试 · 指标"]
E -->|deny| X
G --> H["工具 execute() 本体"]
H --> I["fs/write-intent · fs/edit-intent 门"]
H --> J["工具自有事件
todo/write · fs/observed · hook/*"]
H --> G
G --> K["tools/post-execute（waterfall）
accept · block · replace · add context"]
X --> K
K --> L["注册表外层规范化
抛出 → isError"]
L --> M["finalizeContent
最后的 content-only 不变量"]
M --> N["tools/result（emit · 冻结）
只能观察，不能改"]
N --> O["append tool/result
单一模型可见结果"]
O --> P["additionalContexts FIFO
→ inbox.next-step"]
```
### 最小实现
```ts
// minidsh/tools.ts
type PreToolDecision = { kind: 'allow' } | { kind: 'deny'; reason: string } | { kind: 'ask' }
type PostToolDecision =
| { kind: 'accept' } | { kind: 'block'; reason: string }
| { kind: 'replace'; content: string } | { kind: 'context'; message: Message }
export class ToolRegistry {
private tools = new Map()
/** 单调守卫：只能拒，不能放。见第 12 步。 */
private guards: ((exec: ToolExecution) => 'deny' | undefined)[] = []
register(def: ToolDefinition): Disposer {
if (this.tools.has(def.name)) throw new Error(`tool "${def.name}" already registered`)
this.tools.set(def.name, def)
return () => this.tools.delete(def.name)
}
registerGuard(guard: (exec: ToolExecution) => 'deny' | undefined): Disposer {
this.guards.push(guard)
return () => { const i = this.guards.indexOf(guard); if (i >= 0) this.guards.splice(i, 1) }
}
/** 模型能看到的 schema 列表——直接进系统提示装配。 */
schemas(): ToolSchema[] {
return [...this.tools.values()].map(t => ({ name: t.name, description: t.description, parameters: t.parameters }))
}
async execute(exec: ToolExecution, session: Session, bus: EventBus): Promise {
session.append('tool/call', { callId: exec.callId, name: exec.name, args: exec.args })
// ① 可扩展的前置决策
let pre = await bus.waterfall('tools/pre-execute', exec, async () => ({ kind: 'allow' }))
if (pre.kind === 'ask') {
pre = (await this.askApproval(exec)) ? { kind: 'allow' } : { kind: 'deny', reason: 'user rejected' }
}
// ② 单调守卫：在可扩展前置之后，谁也放宽不了
if (pre.kind === 'allow') {
for (const guard of this.guards) {
if (guard(exec) === 'deny') { pre = { kind: 'deny', reason: 'guard denied' }; break }
}
}
// ③ around：超时 / 重试 / 指标都是包在本体外面的
let result: ToolResult
if (pre.kind === 'deny') {
result = { isError: true, content: `denied: ${pre.reason}` }
} else {
try {
result = await bus.waterfall('tools/execute', exec,
() => this.tools.get(exec.name)!.execute(exec.args))
} catch (error) {
// 规范化：流水线里的任何抛出都变成模型可读的错误结果，而不是崩掉循环
result = { isError: true, content: errorChain(error) }
}
}
// ④ 后置：接受 / 拦 / 换内容 / 追加上下文
const post = await bus.waterfall('tools/post-execute',
{ exec, result }, async () => ({ kind: 'accept' }))
if (post.kind === 'replace') result = { ...result, content: post.content }
if (post.kind === 'block') result = { isError: true, content: post.reason }
if (post.kind === 'context') this.inbox.spliceNextStep(post.message)
// ⑤ 定稿：冻结后只广播，不再接受修改
const frozen = Object.freeze({ ...result })
bus.emit('tools/result', Object.freeze(exec), frozen)
session.append('tool/result', { callId: exec.callId, content: frozen.content, isError: frozen.isError })
return frozen
}
}
```
### 五个值得抄的细节
**① `tool/call` 在执行之前就记日志。** 万一工具执行时进程崩了，日志里仍然有"我曾经要调这个工具"。事后能查。
**② 抛出被规范化成 `isError` 结果，而不是崩循环。** 工具作者写错代码不该让整个 agent 死掉；模型应该看到一条错误并自己决定怎么办。
**③ `tools/result` 是 `emit` + 冻结。** 结果定稿后只能被观察。前面已经讲过，这里再强调一次：**dsh 甚至用运行时不变量守着"发布前必须冻结"**（`packages/core/tools/src/invariant.ts:23`）。
**④ 事件顺序也被不变量守着。** `packages/core/tools/src/invariant.ts:94-115` 里能看到这些断言：
```ts
if (stages.has(exec)) fail('tools/pre-execute repeated for one execution')
if (stages.get(exec) !== 'pre') fail('tools/execute must follow tools/pre-execute')
if (…) fail('tools/post-execute must follow tools/pre-execute or tools/execute')
```
**"流水线阶段的顺序"本身是一条运行时契约**，而不是靠代码结构隐含保证。
**⑤ UI 渲染意图是工具设计的一部分。** dsh 的宪法（`AGENTS.md`）：
> **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args`.
工具要在定义时就说清"我该被渲染成普通卡片、终端输出、还是 diff"，而且渲染函数必须是 `args` 的**纯函数**（所以待处理卡片能在执行前就画出来）。
### 真实 dsh 在哪儿
`packages/core/tools`（13 743 行，全仓单包第二大）。`@module` 一句话：
> Tool registry, model presentation modes, and pre/guard/around/post/result execution pipeline.
47 个模型可见工具全部走这条流水线，完整 schema 目录在 `docs/tool-catalog.md`（1 873 行，**由脚本 boot 每个工具插件后读 `ctx.tools.schemas()` 生成**——因为工具 schema 不是静态可知的：有运行时展开的枚举、拼接的描述、配置驱动的名字、原始 JSON-Schema 的 MCP 工具）。
---
第 12 步 · 单调守卫：审批为什么不能被后面的插件放宽
### 为什么
第 11 步的流水线里有一处看起来多余的设计：既然有了 `tools/pre-execute` waterfall，为什么还要额外一层"单调守卫"？
因为 waterfall 有一个致命的灵活性：**后注册的 listener 可以覆盖前面的决定**。
```ts
// 一个善意的插件
ctx.on('tools/pre-execute', async (exec, next) => {
const decision = await next()
if (decision.kind === 'deny' && isProbablySafe(exec)) {
return { kind: 'allow' } // ← 它"帮"你放宽了权限
}
return decision
})
```
这段代码能通过 code review（它看起来在做合理的事），但它把整个权限系统变成了摆设。**任何能注册 listener 的插件都能提权。**
dsh 的解法：在可扩展的 waterfall **之后**再跑一层**只能拒绝、不能批准**的守卫。
流水线文档的描述（`docs/tool-execution-pipeline.md`）：
> Registered monotonic guards
**deny or abstain; identity protected**
「deny or abstain」——只有两个选项：拒，或者不表态。**没有"允许"这个返回值**，所以它在数学上不可能放宽任何东西。这就是"单调"的意思：安全性只能单向增强。
### 最小实现
关键在**类型**上就不给放宽的可能：
```ts
// ✅ 守卫的返回类型里没有 'allow'
type GuardVerdict = 'deny' | undefined // deny 或弃权，就这两种
registerGuard(guard: (exec: ToolExecution) => GuardVerdict): Disposer
// 执行时：任何一个 deny 就终局
for (const guard of this.guards) {
if (guard(exec) === 'deny') { pre = { kind: 'deny', reason: 'guard denied' }; break }
}
```
对比一下如果用 waterfall 会怎样：
| | waterfall | 单调守卫 |
|---|---|---|
| 能改写别人的决定 | 能 | 不能 |
| 顺序敏感 | 是（后者赢） | 否（任一 deny 即终局） |
| 新插件能不小心提权 | **能** | **不可能** |
| 适合 | 策略协作、上下文补充 | 安全边界 |
### 一个真实案例：读前必写策略
dsh 用这个机制实现"读之前不许写"（`docs/tool-catalog.md` 的 `dsh-tool-fs` 行）：
> The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-observation-policy` (an `fs/*` event-gate plugin, **no schema change**); a deployment that loads these tools is expected to also load it.
注意 **"no schema change"**：策略是挂在事件上的，模型看到的工具 schema 完全不变。这意味着你可以在不同部署里换掉这条策略，而模型的行为契约保持稳定——**提示词缓存不会失效**。
### 怎么验收
按第 7 步那条"先违反再看红"的规矩：
```ts
// 写一个想提权的恶意/善意插件
ctx.bus.on('tools/pre-execute', async (exec, next) => {
const d = await next()
return d.kind === 'deny' ? { kind: 'allow' } : d // 试图放宽
})
registry.registerGuard(exec => exec.name === 'bash' && /rm -rf/.test(exec.args.command) ? 'deny' : undefined)
const r = await registry.execute({ name: 'bash', args: { command: 'rm -rf /' }, callId: '1' }, session, bus)
console.assert(r.isError, '守卫必须挡住，waterfall 的放宽不该生效')
```
### 真实 dsh 在哪儿
`packages/core/tools/src/index.ts:704` 与 `:1101` 的 JSDoc：
> A monotonic execution guard evaluated **after** every `tools/pre-execute` …
> Register a monotonic guard **after the extensible** `tools/pre-execute` …
"after the extensible" 这个措辞很精确：**可扩展的部分先跑，不可放宽的部分后跑**。顺序本身就是安全设计。
---
第 13 步 · 系统提示：每一步重新装配
### 为什么
系统提示在多数项目里是一个模板字符串加几个插值。在 harness 里它必须是**注册表**，因为贡献者太多了：
- 核心身份与规则
- 工具 schema（第 11 步的 `schemas()`）
- 当前工作目录、git 状态
- 技能清单（一技能一行）
- 待办列表
- 计划模式的额外约束
- 子 agent 的专属段
- 用户自定义的家规
而且这些贡献者**会来会走**：子 agent 起来了就多一段，计划模式退出了就少一段。
### 最小实现
```ts
// minidsh/system-prompt.ts
interface Section { key: string; order: number; render: () => string | undefined }
export class SystemPrompt {
private sections: Section[] = []
private variables = new Map string>()
/** 注册一段。返回 disposer——所以段落可以随插件来去。 */
section(key: string, order: number, render: () => string | undefined): Disposer {
this.sections.push({ key, order, render })
return () => { const i = this.sections.findIndex(s => s.key === key); if (i >= 0) this.sections.splice(i, 1) }
}
/** 每个 step 调一次：顺序固定，内容动态。 */
async assemble(): Promise {
const rendered = this.sections
.slice().sort((a, b) => a.order - b.order) // 顺序由 order 决定，不由注册时机决定
.map(s => ({ key: s.key, text: s.render() }))
.filter((s): s is { key: string; text: string } => Boolean(s.text))
return { sections: rendered, tools: this.ctx.get('tools').schemas() }
}
}
```
**`order` 而不是注册顺序**是关键。注册顺序取决于插件加载顺序，而插件加载顺序取决于 `inject` 依赖图——那是不该泄漏到提示词布局里的实现细节。用显式 `order` 把两者解耦。
### 一个容易忽略的收益：缓存友好
提示段有稳定顺序 + 稳定内容 = 前缀可缓存。本系列里 Reasonix 花了大力气做「稳定前缀 + turn tail」；dsh 靠"注册表 + order"天然拿到一半。
### 真实 dsh 在哪儿
`packages/core/system-prompt`（1 582 行）的 `@module`：
> Registry for ordered system sections, dynamic context, tool schemas, and prompt variables.
四类贡献：**有序系统段 / 动态上下文 / 工具 schema / 提示变量**。被 30 个包依赖，`inject` 入度第二（20 次）——半个仓库都要往提示词里塞东西，这正是它必须是注册表的原因。
真实装配在循环里的调用点是 `agent.ts:230`：
```ts
const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))
```
`assembleContextFor(this, signal)` 把"哪个 agent 在问"和取消信号一起传进去——**装配是 per-agent 的**（第 14 步的 scope 会解释为什么）。
---
Part 4 · 第 14–17 步造能力：seam 三角色
第 14 步 · capability seam：Definition / Provider / Consumer
### 为什么
到这里，你的 harness 已经能跑了。现在要加"执行 bash 命令"的能力。
最直接的写法是写一个 `tool-bash`，里面 `child_process.spawn`。能用。但三个月后你会遇到：
- 想在远程沙箱里跑（E2B / 容器）→ 得改 `tool-bash`
- Windows 用户要 PowerShell → 再写一个 `tool-pwsh`，两份逻辑
- 想给命令加超时/审批 → 又改 `tool-bash`
- LSP 和文件读写也要在同一个远程环境里 → 每个工具都得改一遍
dsh 的答案是把每个能力做成一个**三角色的缝**（`docs/architecture.md:100`）：
> A **seam** is a swappable capability with three roles: a **Service Definition** declaring the interface, a **Service Provider** implementing it, and a **Consumer** using it, commonly a model-facing tool. A package may combine roles, but **one role alone is not a seam**; adding a capability means designing all three.
glossary 里的定义更严格（`docs/glossary.md:9`）：Service Definition 必须是 Cordis 的 `Service`（抽象类或具体注册表），**never a TypeScript `interface`**。
### 三角色长什么样
以 shell 为例，这是 dsh 自己指定的范本：
```mermaid
flowchart LR
subgraph def["① Service Definition：dsh-shell（476 行）"]
D["abstract class ShellExecutor
declare ctx.shell
+ 词汇类型 ShellExecRequest/Spec/Process"]
end
subgraph prov["② Service Provider（四个，同一接口）"]
P1["dsh-bash-local
本机 bash"]
P2["dsh-bash-sandbox
沙箱 bash"]
P3["dsh-pwsh-local
本机 PowerShell"]
P4["dsh-pwsh-sandbox"]
end
subgraph cons["③ Consumer（模型可见工具）"]
C1["dsh-tool-bash → bash"]
C2["dsh-tool-pwsh → pwsh"]
C3["dsh-tool-bash-persistent → bash（PTY）"]
end
D -.实现.- prov
D -.注入.- cons
cons --> M["模型只看到工具名与 schema"]
```
三个角色的分工非常清楚：
| 角色 | 回答什么问题 | 它**不**回答什么 |
|---|---|---|
| Definition | 这个能力**是什么**（接口 + 词汇） | 怎么实现、谁来用 |
| Provider | **怎么实现**（本机 / 沙箱 / 远程） | 模型怎么看到它 |
| Consumer | **模型怎么用**（工具名、schema、渲染） | 底下是本机还是远程 |
### 最小实现
```ts
// ① Definition：只声明接口与词汇，不含任何实现
// minidsh/shell/definition.ts
export interface ShellExecRequest { command: string; cwd?: string; timeoutMs?: number }
export interface ShellExecSpec extends ShellExecRequest { cwd: string; timeoutMs: number } // 默认值已解析
export interface ShellRunResult { stdout: string; stderr: string; exitCode: number }
export abstract class ShellExecutor {
/** 显式的默认值解析步骤——不是藏在 run() 里的 ?? 默认。 */
abstract resolve(request: ShellExecRequest): ShellExecSpec
abstract run(spec: ShellExecSpec): Promise
}
export const definition: Plugin = (ctx) => {
// Definition 包本身只贡献词汇与设置命名空间，不 provide 实现
ctx.provide('shellSettingsNamespace', 'shell')
}
```
```ts
// ② Provider：实现它
// minidsh/shell/bash-local.ts
class BashLocal extends ShellExecutor {
resolve(request: ShellExecRequest): ShellExecSpec {
return { ...request, cwd: request.cwd ?? process.cwd(), timeoutMs: request.timeoutMs ?? 120_000 }
}
async run(spec: ShellExecSpec): Promise {
const { execFile } = await import('node:child_process')
return new Promise(resolve => {
execFile('bash', ['-lc', spec.command], { cwd: spec.cwd, timeout: spec.timeoutMs },
(err, stdout, stderr) => resolve({ stdout, stderr, exitCode: err ? 1 : 0 }))
})
}
}
export const bashLocal: Plugin = (ctx) => ctx.effect(() => ctx.provide('shell', new BashLocal()))
```
```ts
// ③ Consumer：把它变成模型可见的工具
// minidsh/shell/tool-bash.ts
export const toolBash: Plugin = (ctx) => {
const shell = ctx.get('shell') // 只知道键，不知道实现
return ctx.get('tools').register({
name: 'bash',
description: 'Run a bash command.',
parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
render: 'terminal', // UI 渲染意图（第 11 步）
execute: async (args) => {
const spec = shell.resolve({ command: args.command }) // 先显式解析
const r = await shell.run(spec) // 再执行
return { content: r.stdout + r.stderr, isError: r.exitCode !== 0 }
},
})
}
toolBash.inject = ['tools', 'shell']
```
### 那个 `resolve(request): Spec` 分裂为什么重要
dsh 把 shell 这个 request/spec 分裂当作宪法级模板（`AGENTS.md`）：
> **Explicit > implicit at package boundaries**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()`（the `dsh-shell` request/spec split is the template）.
为什么这么讲究？考虑一个具体场景：**超时默认值是多少？**
- 藏在 `run()` 里的 `?? 120_000`：调用方无法知道实际用了什么；日志里没有；换 provider 后默默变了；测试断言不了。
- 显式 `resolve()`：`Spec` 是完整的、无 optional 的对象。**它可以被记录、被断言、被展示给用户**。
这就是 `ShellExecRequest`（字段可选）和 `ShellExecSpec`（字段齐全）分成两个类型的意义——**"未解析"和"已解析"在类型层面不同**，你不可能把一个没解析完的东西传进 `run()`。
### 真实 dsh 在哪儿
我做的普查里，shell 组共 9 个包 / 10 405 行：
| 包 | 角色 | 说明 |
|---|---|---|
| `shell` | Definition | `ctx.shell`，476 行，只有接口与词汇 |
| `bash-local` / `bash-sandbox` | Provider | 本机 / 沙箱 |
| `pwsh-local` / `pwsh-sandbox` | Provider | Windows 组合 |
| `shell-env` | 支撑 | `ctx.shellEnv`，托管 `DSH_*` 环境 |
| `tool-bash` / `tool-pwsh` | Consumer | 模型可见 `bash` / `pwsh` |
| `tool-bash-persistent` | Consumer | 走 `ctx.terminals` 的 PTY 版 |
Definition 的 JSDoc 里还有一句很能说明"边界感"的话（`packages/shell/shell/src/index.ts:1-5`）：
> Service Definition for the `ctx.shell` capability seam, covering foreground commands and background process handles. **Job ids, ownership, polling, and notices belong to `@deepseek-ai/dsh-jobs`, keeping executors independent of sessions.**
**执行器不该知道会话的存在**。后台作业的 id、归属、轮询、通知全部归 `ctx.jobs`。所以同一个执行器既能给聊天用，也能给自动化协议用，也能给子 agent 用。
---
第 15 步 · 换一个 provider，搬走整个执行世界
### 为什么
第 14 步做完 seam，收益还只是"bash 能换实现"。真正的杠杆在下一层：**多个 seam 共享同一个执行世界**。
architecture.md 的这句话是整个架构最强的卖点（`:102`）：
> Seams are why one provider swap changes the whole product. **Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks.**
翻译：把 `ctx.fs` 和 `ctx.subprocess` 指向远程沙箱，那么 **bash、持久终端、语言服务全都自动搬到了远程**——因为它们都建在这两个原语之上，而不是各自 spawn 自己的进程。
### 依赖方向决定了这件事成不成
```mermaid
flowchart TB
subgraph prim["两个原语 seam"]
FS["ctx.fs
读写文件"]
SP["ctx.subprocess
起进程"]
end
subgraph built["建在原语之上的能力"]
SH["ctx.shell → bash / pwsh"]
TM["ctx.terminals → 持久 PTY"]
LSP["ctx.lsp → 语言服务"]
SEARCH["glob / grep（打包的 ripgrep）"]
CR["ctx.codeRuntime → 代码模式"]
end
FS --> built
SP --> built
subgraph swap["换 provider = 换整个世界"]
L["本机：node:fs + child_process"]
E["远程：dsh-e2b（沙箱 FS/subprocess 适配器）"]
end
L -.任选其一.-> prim
E -.任选其一.-> prim
```
这张图的关键是**箭头方向**：没有任何一个上层能力直接 import `node:child_process`。它们全都注入 `ctx.subprocess`。
我在普查里验证了这一点——`subprocess` 被 8 个包 inject（入度第 7），而 `glob`/`grep` 这两个搜索工具的目录描述明确写着（`docs/tool-catalog.md`）：
> glob and grep are unconditional discovery tools that **spawn the packaged ripgrep binary (`@vscode/ripgrep`) through ctx.subprocess** as ordinary foreground calls (never background jobs) — **no host `rg` install and no shell layer**.
注意 "no shell layer"：搜索不经过 shell，直接走 subprocess。所以搜索能力不依赖"机器上有没有 bash"，也就能在远程沙箱、Windows、精简容器里一致工作。
### 最小实现：一个远程 provider
```ts
// minidsh/e2b/remote-subprocess.ts
class RemoteSubprocess extends SubprocessRunner {
constructor(private client: SandboxClient) { super() }
async spawn(spec: SpawnSpec): Promise {
return this.client.exec(spec.argv, { cwd: spec.cwd, env: spec.env }) // 走 HTTP 到沙箱
}
}
class RemoteFs extends FileSystem { /* 同理：把读写代理到沙箱 */ }
export const remoteWorld: Plugin = (ctx) => {
const client = new SandboxClient(ctx.get('settings').get('e2b.apiKey'))
const d1 = ctx.provide('subprocess', new RemoteSubprocess(client))
const d2 = ctx.provide('fs', new RemoteFs(client))
return () => { d1(); d2() }
}
remoteWorld.inject = ['settings']
```
挂上这一个插件（替掉本机那两个），你的 bash / PTY / LSP / 搜索**全部**跑在远程沙箱里，而这四个包**一行代码都没改**。
### 怎么验收
这个论断值得写一个真正的测试来钉住：
```ts
// 同一个工具调用，在两个世界里跑，断言它落在正确的世界
for (const world of [localWorld, remoteWorld]) {
const ctx = await bootHarness([world, toolBash, toolFsSearch, lspStdio])
const r = await callTool(ctx, 'bash', { command: 'hostname' })
console.assert(r.content.trim() === expectedHostname[world.name], `${world.name} 应落在对应执行世界`)
}
```
### 真实 dsh 在哪儿
`packages/e2b`（3 包 / 6 630 行）就是这个论断的实证。`AGENTS.md` 里它的定位是：
> `e2b/` E2B POC: sandbox + FS/subprocess adapters
一个 POC 用 6 630 行证明了架构承诺——**换两个 provider，五种能力跟着搬家**。
相关的执行世界包体量（我的普查）：`fs` 7 包 13 044 行、`shell` 9 包 10 405 行、`terminal` 3 包 5 721 行、`lsp` 3 包 5 496 行、`subprocess` 2 包 4 256 行、`code-runtime` 2 包 3 963 行。**这六组共 26 包、42 885 行，全部建在两个原语 seam 上。**
---
第 16 步 · 沙箱：把 argv 包起来
### 为什么
工具能跑任意命令了，现在要限制它。
多数项目的做法是在工具里做检查：正则黑名单、路径白名单。问题是**这类检查在同一个进程里，模型只要绕过工具（比如用 `bash` 跑一个脚本去做被禁的事）就失效了**。
真正的隔离必须由操作系统提供。dsh 的做法是把沙箱做成一个 seam，让**消费者在 spawn 之前把 argv 包一层**（`docs/architecture.md` 扩展点表）：
> Confine spawned processes | use a `ctx.sandbox` backend; **consumers wrap argv before spawning**
### 最小实现
沙箱不执行命令，它只**改写 argv**：
```ts
// minidsh/sandbox/definition.ts
export abstract class Sandbox {
/** 把原始 argv 包成"受限执行"的 argv。 */
abstract wrap(argv: string[], policy: SandboxPolicy): string[]
/** 如实上报自己真正提供的隔离强度——不许谎报。 */
abstract readonly level: 'system' | 'application' | 'off'
}
// Linux Landlock 后端
class LandlockSandbox extends Sandbox {
readonly level = 'system' as const
wrap(argv: string[], policy: SandboxPolicy): string[] {
return [
'landlock-run',
...policy.readPaths.flatMap(p => ['--ro', p]),
...policy.writePaths.flatMap(p => ['--rw', p]),
...policy.allowNetwork ? [] : ['--no-net'],
'--', ...argv,
]
}
}
```
消费者侧只多一行：
```ts
// bash-sandbox provider
async run(spec: ShellExecSpec): Promise {
const raw = ['bash', '-lc', spec.command]
const argv = this.sandbox.wrap(raw, this.policy.for(spec)) // ← 就这一行
return this.subprocess.spawn({ argv, cwd: spec.cwd })
}
```
### 三个设计要点
**① 沙箱不执行，只包装。** 这让它能和任何 provider 组合：本机 bash、远程 subprocess、LSP 子进程，谁都能在 spawn 前包一层。如果沙箱自己负责执行，就会和执行器争夺同一个职责。
**② 隔离强度是一个可查询的值，不是一个假设。** `level` 字段让上层能据此**分级授权**。本系列里 DeepTutor 也用了同一招（SYSTEM 级对所有人开放、APPLICATION 级仅管理员）。这比"假装所有部署一样安全"诚实得多。
**③ 部分失败必须分类正确。** dsh 有一篇专门的事后复盘讲这个：`docs/postmortem/0004-landlock-partial-notice-misclassified-child-failures.md`——**Landlock 的"部分生效"通知曾把子进程的失败错误分类**。
这个 postmortem 值得所有写沙箱的人读：当你的沙箱只能部分生效（老内核不支持某些 rule），你发出的"部分生效"提示不能把**子进程自己的失败**也算进去，否则用户会以为是沙箱问题而去关掉沙箱。
### 真实 dsh 在哪儿
- `packages/sandbox`（4 包 / 9 040 行）：Definition + 策略 + 后端
- `native/landlock-run`：`@deepseek-ai/node-addon-landlock-run` 的源码所在地，按平台分包（`-linux-x64` / `-linux-arm64`）
- `pnpm-workspace.yaml` 里对它有一句注释：*"The Landlock launcher is developed with its harness consumers but keeps its native build and publication scripts under native/landlock-run."*
`ctx.sandboxPolicy` 是独立的服务键（我的普查里 `sandbox` 与 `sandboxPolicy` 是两个键）——**"能力"和"策略"分开**，所以策略可以按部署替换而不换沙箱实现。
---
第 17 步 · 上下文经济：compaction 与 spill
### 为什么
两个不同的溢出问题，需要两个不同的机制。
**问题 A：对话太长了。** 20 轮之后历史超过窗口。要压缩。
**问题 B：单次工具输出太大了。** `grep` 匹配了 3 万行，`cat` 了一个 5MB 的文件。这一条就能撑爆窗口。
很多项目只做 A（压缩历史），于是 B 发生时整个会话直接崩。或者只做 B（截断输出），于是模型永远看不到被截掉的部分。
dsh 把两者做成两个 seam：`ctx.compaction` 和 `ctx.spillStore`。
### spill：把超量输出落盘，给模型一个可取回的定位符
`packages/spill` 的 Definition JSDoc 说得很清楚：
> Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a spill backend does — **persist a tool's oversized text and return a model-facing locator plus retrieval guidance**.
三个词是关键：**persist（落盘）+ locator（定位符）+ retrieval guidance（怎么取回的说明）**。
不是简单截断，而是：完整内容存起来，给模型一条"我把完整结果存在这里了，你可以这样读它"的消息。
```ts
// minidsh/spill.ts
export abstract class SpillStore {
abstract save(text: string, meta: { tool: string; callId: string }): Promise
}
/** 一个 post-execute 插件：超过阈值就溢出 */
export const spillPolicy: Plugin = (ctx) => {
const store = ctx.get('spillStore')
return ctx.bus.on('tools/post-execute', async ({ exec, result }, next) => {
if (result.content.length <= 20_000) return next()
const locator = await store.save(result.content, { tool: exec.name, callId: exec.callId })
return {
kind: 'replace',
content:
`${result.content.slice(0, 2_000)}\n\n` +
`[输出过长，完整 ${result.content.length} 字符已保存]\n` +
`完整内容：${locator.path}（可用 read 工具按行区间读取）`,
}
})
}
spillPolicy.inject = ['spillStore']
```
真实 dsh 的 `glob`/`grep` 就是这么用的（`docs/tool-catalog.md`）：
> Capped results save the complete formatted list through the optional `ctx.spillStore` backend; **returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments**.
**"可后续读取/搜索的定位符"**——溢出的内容不是坟墓，它还能被 `read` 和 `grep` 继续处理。
### compaction：压缩历史，但结果必须回到日志
压缩的难点不是"怎么摘要"，而是**"压缩结果算不算模型可见"**。
按第 7 步的宪法：算。所以压缩产物必须成为一个 session event，而不是内存里的一个变量。
```ts
// 压缩后 append 一个事件，deriveMessages 据此改变投影
session.append('compaction/applied', {
replacedRange: [firstSeq, lastSeq],
summary: summaryText,
})
// deriveMessages 遇到它就跳过被替换的区间，改用摘要
deriveMessages() {
const compactions = this.events.filter(e => e.type === 'compaction/applied')
// …被覆盖区间的原始消息不再投影，改投影摘要…
}
```
这样一来：压缩是**可审计**的（能看到压了哪一段、摘要是什么）、**可重放**的（重放日志能得到同样的模型输入）、**可撤销的**（删掉那个事件就恢复原状）。
### 真实 dsh 在哪儿
- `packages/compaction`（4 包 / 8 032 行）：Definition + basic provider
- `packages/spill`（3 包 / 1 473 行）：Definition + backend + policy
- `docs/subsystems/compaction.md` / `spill.md` 是各自的子系统文档
- 还有一个 `ctx.toolResultPruner` 和 `ctx.tokenMeter`（我的普查里都是独立服务键）——**结果修剪**和**token 计量**也各自成缝
四个独立的服务键（`compaction` / `spillStore` / `toolResultPruner` / `tokenMeter`）管同一件事的四个侧面。这是本系列里对"上下文经济学"拆得最细的一家。
---
Part 5 · 第 18–20 步造产品：装配与纪律
第 18 步 · 让循环继续：`agent/turn-stopping` 与 goal
### 为什么
第 8 步埋了一个钩子：turn 要停之前发一个 serial 事件，然后**再查一次 inbox**。现在用它。
场景：用户说"把测试跑到全绿"。模型改了一版，跑测试，还有 3 个失败，然后它说"我改好了一部分"就停了。
你希望它继续。怎么办？
- ❌ 改循环：加一个"如果目标没达成就继续"的判断 → 违反"Plugins, not loop changes"
- ❌ 在提示词里说"不要中途停" → 模型不听话，而且没有客观判据
- ✅ 挂一个 `agent/turn-stopping` 插件：检查目标状态，没达成就往 inbox 塞一条消息
### 最小实现
```ts
// minidsh/goal.ts
export const goalContinuation: Plugin = (ctx) => {
const goals = ctx.get('goals')
return ctx.bus.on('agent/turn-stopping', async ({ turn }) => {
const goal = goals.active()
if (!goal || goal.status !== 'open') return
if (goal.round >= goal.maxRounds) return // 有界：不能无限续
goals.bumpRound()
ctx.inbox.spliceNextStep({
role: 'user',
content: `目标未完成：${goal.objective}\n当前第 ${goal.round}/${goal.maxRounds} 轮，请继续。`,
})
})
}
goalContinuation.inject = ['goals']
```
循环那边**一行都不用改**——它在第 8 步就已经写好了"发公告 → 再查 inbox"的逻辑。
### dsh 的 goal 做得比这狠：权限分级 + 有界
看 `docs/tool-catalog.md` 里 `dsh-tool-goal` 的部署说明：
> `create_goal`, `get_goal`, `update_goal` … **create, edit, pause, and resume require direct-human root authority**; complete and blocked also accept the exact current goal round. **The default blocked lower bound is three admitted rounds.**
三个设计值得抄：
**① 创建/编辑/暂停/恢复目标需要"直接人类根权限"。** 模型不能给自己派目标，也不能悄悄改目标。否则"把测试跑绿"会被模型改成"把测试注释掉"。
**② `complete` 和 `blocked` 需要带上"确切的当前轮次"。** 这是一个 compare-and-set：模型说"我完成了第 5 轮的目标"，如果实际已经是第 6 轮，这个声明就失效。防的是过期声明。
**③ `blocked` 有下界：至少 3 个已准入轮次。** 模型不能第一轮就说"我被卡住了"。必须真的试过三轮。
`packages/goal` 的 `@module` 一句话：
> Same-session goal domain: **event-sourced state, compare-and-set mutations, and process-local continuation activation**.
**event-sourced + compare-and-set** —— 目标状态也是从日志派生的，变更是乐观并发控制的。
### 与本系列其它项目对照
| 项目 | 防"模型自称完成"的机制 |
|---|---|
| MiMo Code | Goal 独立裁判 + 四道死循环闸门 |
| grok-build | Goal Mode 五件套 |
| Reasonix | Delivery Profile 证据签收 + readiness 门禁 |
| DeepTutor | 掌握度门禁 / 计划 done 门禁沉进工具 |
| **DeepSeek Harness** | **`agent/turn-stopping` + event-sourced goal + CAS + 人类根权限 + 有界轮次** |
共同点是那句话：**凡是能被算准的，就别让模型自由心证。** dsh 的特点是把这件事做成了**一个事件 + 一个插件**，循环本身对"目标"一无所知。
### 真实 dsh 在哪儿
`packages/goal`（4 包 / 5 786 行，`ctx.goals`）。扩展点表里的一行（`docs/architecture.md`）：
> Manage a same-session objective | use `ctx.goals`; continue through `agent/*`
---
第 19 步 · bundle 与 profile：把装配做成可打补丁的层
### 为什么
你现在有 40 个插件。用户要跑 Web 界面，需要其中 35 个；跑一次性无头任务，需要 22 个；跑自动化协议服务，需要 25 个。
怎么表达"哪些插件 + 什么配置"？
- ❌ 三个 `main.ts` → 行为漂移，改一处忘两处
- ❌ 一个巨大的 if/else → 无法被第三方扩展
- ✅ **配置即装配**，而且分层可打补丁
### dsh 的两个概念
`docs/architecture.md:19-21`：
> A **profile** is a named composition stored in the Harness home. It lists the bundles it stacks, holds any out-of-tree plugins it installs, and keeps the user's own `cordis.patch.yml`.
> A **bundle** is a distribution format for Cordis config rows and the code they mount, **so whatever it inserts stays patchable by the layers above it**.
两者都在自己的 `package.json` 里用 `dsh` 字段自述：`dsh.profile` 列出 profile 的 bundle，`dsh.bundle` 指向 bundle 的 patch 文件。
### 分层顺序
```mermaid
flowchart LR
E["空 entry 列表"] --> B1["bundle 1（按 profile 声明顺序）"]
B1 --> B2["bundle 2"]
B2 --> B3["bundle N"]
B3 --> PP["profile 的 cordis.patch.yml"]
PP --> HP["home 级 cordis.patch.yml"]
HP --> CLI["--patch 命令行覆盖层"]
CLI --> FINAL["最终插件树"]
```
规则（`docs/architecture.md:27`）：
> Layers apply to an empty entry list in this order: each bundle in the profile's listed order, then the profile's `cordis.patch.yml`, then the home-level one, then any `--patch` overlay. **A patch targets a row by id and replaces its whole config, or inserts new rows.**
**"replaces its whole config"** 而不是深合并。这是个刻意选择：深合并的语义在嵌套配置下极难预测（数组怎么合？null 表示删除还是设空？），整体替换虽然啰嗦，但**你永远知道最终值是什么**。
### 最小实现
```ts
// minidsh/boot.ts
interface ConfigRow { id: string; plugin: string; config?: Record; disabled?: boolean }
/** 分层：按序应用每一层的 patch，靠 id 替换整行 config 或插入新行。 */
export function composeTree(bundles: ConfigRow[][], patches: ConfigRow[][]): ConfigRow[] {
let rows: ConfigRow[] = []
for (const bundle of bundles) rows = rows.concat(bundle)
for (const patch of patches) {
for (const row of patch) {
const i = rows.findIndex(r => r.id === row.id)
if (i >= 0) rows[i] = { ...rows[i], config: row.config, disabled: row.disabled } // 整体替换
else rows.push(row) // 插入新行
}
}
return rows.filter(r => !r.disabled)
}
/** 把行变成插件树。 */
export async function boot(rows: ConfigRow[]): Promise {
const ctx = new Context()
for (const row of rows) {
const mod = await import(row.plugin)
const plug: Plugin = mod.apply ?? mod.default
if ('default' in mod && !mod.apply) {
// 见第 2 步那个 postmortem：default 导出会丢掉 inject
throw new Error(`plugin "${row.plugin}" must use named exports (apply/inject), not default`)
}
await ctx.plugin(withConfig(plug, row.config))
}
ctx.assertSettled()
return ctx
}
```
### 一个必须有的调试出口
dsh 提供了 `dsh --profile web --dump-config`，并且文档明确承诺（`:29-35`）：
> To see the tree your machine actually boots … **Any row it prints can be replaced by a patch of your own.**
**"打印出来的每一行都能被你自己的 patch 替换"** ——这句话是可配置性的验收标准。如果你的框架做不到"打印实际装配 + 每一行都可覆盖"，那它的可配置性是假的。
给 minidsh 加上：
```ts
if (process.argv.includes('--dump-config')) {
console.log(JSON.stringify(composeTree(bundles, patches), null, 2))
process.exit(0)
}
```
### 真实 dsh 在哪儿
- `packages/bundle`（3 包）：`dsh-base`（每个 profile 的第一层：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测）、`dsh-web-app`、`dsh-headless`
- `packages/boot`（2 包 / 4 081 行）：组合机制
- `packages/preset`（2 包 / 3 794 行）：**逐会话**装配——`ctx.agentPresets`，让一个会话拥有不同能力集，其中的 service 行需要 `isolate` realm
- `examples/` 是可运行的 `cordis.yml` 叶子
有趣的是 `dsh-base` 这个包的 `@module` JSDoc（我的普查抓到的）：
> package's substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch` manifest field and resolved by the profile composer through that field; **this module carries no runtime API**.
**一个 117 行、没有运行时 API 的包**，它的全部实质是一个 YAML 文件。这就是"配置即架构"的字面意思。
---
第 20 步 · 把纪律写成门禁：100% 覆盖 + `verify-*`
### 为什么
前 19 步立了很多规矩：waterfall 必须调 `next()`、注册必须可逆、模型可见必须已记录、seam 必须三角色齐全、默认值必须显式解析……
**规矩写在文档里 = 迟早被违反。** 尤其当协作者是 AI 时——它读了 20 页文档，但第 21 次改动就会忘掉第 3 页那条。
dsh 的态度是：**能机械检查的不变量，全部接到一个会被执行的顶层门禁上**。宪法原文（`AGENTS.md`）：
> **Wire mechanically checkable invariants into an executed top-level gate and prove each changed acceptance path rejects an invalid case.**
### 六层测试
`docs/testing.md`：
| 层 | 命令 | 关键点 |
|---|---|---|
| 单元 | `pnpm run test` | **每个注册表都要有 HMR 安全测试**（拆掉贡献 fiber，断言清理干净） |
| 覆盖率门禁 | `pnpm run test:coverage` | **`packages/*/*/src` 逐文件 100%** |
| 真实 API e2e | `pnpm run test:e2e` | 带 key 打真实模型；无 key 自跳过 |
| 快照 | `pnpm run test:snapshot` | **keyless**：重放录制的会话，diff 规范化后的 JSON-RPC + 重新持久化的日志 |
| 浏览器快照 | `pnpm run test:web` | Chromium 对比重放输出（Linux PR 必过） |
| 门禁集合 | `pnpm run doc-sync` / `hygiene` / `duplication` | 见下 |
**逐文件 100% 覆盖率**这条我要单独说，因为 dsh 对它的解读和大多数团队完全不同：
> An uncovered line is often **dead code the gate is correctly flagging for deletion**, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped.
**"未覆盖的行往往是死代码，门禁正确地在提示你删掉它"** ——这是把覆盖率当**删代码的工具**，而不是当写测试的 KPI。
这也解释了第 8 步看到的那些注释：
```ts
/* v8 ignore next -- private callers establish the running phase before executing a step */
if (this.phase.kind !== 'running') throw new Error(...)
```
不可达的防御分支不能默默放过，必须**显式豁免 + 写清理由**。而 `scripts/coverage-exempt.ts` + `coverage-exempt.spec.ts` 又在守着这些豁免本身。
### 三条我认为最该抄的测试规矩
**① 验证世界，不验证自述**（`docs/testing.md:29`）：
> An e2e assertion **re-runs the command or re-reads the file externally**; a keyword probe on the agent's own output lets a cheating agent pass. **Assert untouched files are byte-identical.**
"对 agent 自己的输出做关键词探测会让作弊的 agent 通过"——这句话应该刻在每个 agent 项目的测试文件顶部。
**② 守卫必须被证明有效**（`:34`）：
> A guard only guards if the regression actually fails it. … add an explicit assertion, **and prove it: introduce the regression, watch red, revert.**
**③ 测真实入口路径**（`:35`）：
> "Real entry path" means the published artifact: a package `bin` runs built `lib/bin.js` **under plain `node`**, exposing failures tsx masks (settle races, module resolution, swallowed load failures).
用 tsx 跑源码会掩盖三类真实故障。所以关键路径必须用**发布产物**测一遍。
### 28 个 `verify-*`：把文档也焊住
`scripts/` 下有 124 个 `.ts`，其中 28 个是 `verify-*`。我挑几个说明它们把什么变成了机器可检查的：
| 门禁 | 它守什么 |
|---|---|
| `verify-export-jsdoc` | 每个导出都有 JSDoc，函数类导出必须有 `@param`/`@returns` |
| `verify-cordis-config` | `cordis.yml` 里的裸插件必须出现在 resolver manifest 的 `dependencies` |
| `verify-package-invariants` | 每个包都有 `./invariant` 伴生；空 installer 必须以 `No runtime invariant:` 开头解释 |
| `verify-type-equiv` | 文档里的 `ts type-equiv` 代码块必须与源码类型**等价** |
| `verify-mermaid` | 图必须能渲染 |
| `verify-md-links` / `verify-doc-refs` | 链接与引用不许烂 |
| `verify-md-wrap` | markdown 换行纪律（一段一物理行） |
| `verify-doc-budgets` | **文档字数预算**（想超要改 manifest 里的上限） |
| `verify-package-readme-limitations` | **每个包 README 必须写清"局限"** |
| `verify-package-readme-model-experience` | **必须写清"模型体验"** |
| `verify-agent-note-classification` / `-format` | 设计文档的分类与格式 |
| `verify-translation-pairing` / `-prompt` | 双语文档逐段配对 |
| `verify-runtime-closure` | 运行时依赖闭包 |
| `verify-dsh-package-licenses` | 许可证 |
最后两行的 `verify-package-readme-limitations` / `-model-experience` 是我在本系列里没见过第二家做的：**它强制每个包的 README 都要有"局限"和"模型体验"两节**。前者防止过度宣传，后者要求作者站在模型的视角描述自己的包。
而且——**这些门禁脚本自己也有 `.spec.ts`**（`coverage-exempt.spec.ts`、`run-gates.spec.ts`、`gen-doc-graphs.spec.ts`…）。守卫也要被守卫。
### 生成而非手写的文档
`docs/` 里有 8 177 行是**生成**的：`config-catalog.md`（3 151）、`tool-catalog.md`（1 873）、`module-graph.md`（1 638）、`persistence-catalog.md`（944）、`capability-seams.md`（471）……全部由 `scripts/gen-*.ts` 产出，并由 `doc-sync` 验证新鲜度。
`tool-catalog.md` 的生成方式尤其讲究（文件头注释）：
> Unlike the cordis catalog (a pure source-AST pass), this generator **BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`**, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). **A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented.**
**"新工具不可能被静默地漏掉文档"** ——这是把"文档完整性"变成了编译期问题。
### 怎么在自己项目里落地
不需要 124 个脚本。先抄这四条，投入产出最高：
1. **每个注册表一个 HMR 测试**（拆掉再断言清理干净）——挡住整类内存泄漏和幽灵注册。
2. **e2e 断言必须从外部重读世界**——挡住"agent 自述完成"。
3. **新守卫必须先看它变红**——挡住假守卫。
4. **一条 `verify-` 脚本查你最在意的那条不变量**，接进 CI。
---
Part 6收尾：回放 · 验收 · 翻车清单
🎬 完整回放：一句"帮我改个 bug"到底跑了什么
把 20 步串起来。用户说：
> 帮我把 `src/parser.ts` 里那个把空字符串当合法输入的 bug 修掉，改完跑测试。
```mermaid
sequenceDiagram
participant U as 用户
participant IN as inbox
participant D as 循环（插件）
participant SP as systemPrompt
participant L as 日志
participant M as ctx.llm
participant T as ctx.tools
participant G as 守卫/沙箱
participant FS as ctx.fs / ctx.shell
U->>IN: send(消息) → 唤醒
D->>L: turn/start {turn:1}
D->>IN: claim('next-turn')
D->>SP: assemble()（段落按 order + 47 个工具 schema）
D->>D: agent/pre-step waterfall → enter
D->>L: step/start {1,1} + user/message
D->>L: deriveMessages()
D->>D: agent/request waterfall → {provider, model, maxTokens}
D->>M: stream()
M-->>L: assistant/chunk ×N
D->>L: assistant/message（sourceEventSeqs 指回那些 chunk）
Note over D: 有 tool_call: read(src/parser.ts)
D->>T: execute
T->>L: tool/call（执行前先记）
T->>G: tools/pre-execute → allow
T->>G: 单调守卫 → 弃权
T->>FS: read
T->>L: fs/observed（读过了，写策略据此放行）
T->>L: tool/result（冻结）
D->>L: step/end {1,1}
Note over D,IN: 工具还欠一次请求 → target='next-step'
D->>L: step/start {1,2}
D->>M: stream()（历史里已有文件内容）
Note over D: tool_call: edit(...) + bash(pnpm test)
T->>G: pre-execute → ask（写操作要审批）
G-->>U: 审批：允许一次
T->>FS: edit → fs/edit-intent 门 → 写入
T->>G: bash 走沙箱：argv 被 landlock-run 包装
FS-->>T: 测试输出 12 万字符
T->>T: tools/post-execute → 超阈值 → spill
T->>L: tool/result（前 2000 字 + 定位符）
D->>L: step/end {1,2}
D->>M: stream()（第 3 步：看测试结果）
Note over D: 没有 tool_call → completed
D->>D: agent/turn-stopping（serial）
Note over D: goal 插件检查：目标达成，不续
D->>L: turn/end {turn:1, reason:{kind:'completed'}}
```
这一趟里，**循环代码没有一行是为"审批""沙箱""溢出""目标"写的**。它们分别是：一个 `tools/pre-execute` listener、一个 argv 包装器、一个 `tools/post-execute` listener、一个 `agent/turn-stopping` listener。
这就是 harness 型架构的全部意义：**新行为长在扩展点上，不长在循环里。**
---
附录 A · 验收断言（每步怎么验）
| 步 | 做完之后，这个断言必须过 |
|---|---|
| 1 | 重复 `provide` 抛错；`get` 未注册的键抛错 |
| 2 | 乱序挂载后依赖自动排好；`inject` 拼错时 `assertSettled()` 报出该插件 |
| 3 | 两个 effect 的撤销顺序是注册顺序的逆序；disposer 调两次不炸 |
| 4 | `emit` 无返回、`waterfall` 能改写、`parallel` 等全部、`serial` 按序 |
| 5 | 观察型 listener 忘了 `next()` 时，下游策略确实失效（写一个测试钉住这个后果） |
| 6 | 日志 4 条、`deriveMessages()` 2 条；`assistant/message` 带得到它的 chunk seq |
| 7 | 手工往 request 里 push 一条消息 → 不变量抛 `InvariantError` |
| 8 | 空 enter：日志有 `turn/start` + `turn/end`，**没有** `step/start`；`max-tokens` 不被后续 step 降级 |
| 9 | `inject` 不唤醒、`send` 唤醒；两个投递口互不干扰 |
| 10 | `reject` 后 `turn/end.reason.kind === 'blocked'` |
| 11 | 工具抛错变成 `isError` 结果而非崩循环；`tools/result` 的参数被冻结 |
| 12 | 存在一个试图放宽的 `pre-execute` listener 时，守卫仍然挡住 |
| 13 | 两个乱序注册的段落，按 `order` 输出 |
| 14 | `resolve()` 产出的 `Spec` 无 optional 字段；`run()` 里没有 `??` 默认 |
| 15 | 同一个 `bash` 工具在 local/remote 两套 provider 下落在正确的执行世界 |
| 16 | 沙箱 `wrap()` 后 argv 首元素是启动器；`level` 如实反映隔离强度 |
| 17 | 超阈值输出被替换成"摘要 + 定位符"，且完整内容可从定位符读回 |
| 18 | 目标未达成时 turn 自动续；达成后不续；轮次到上限停 |
| 19 | `--dump-config` 打印的每一行都能被一个 patch 按 id 换掉 |
| 20 | 覆盖率门禁能指出你故意留的一段死代码；新守卫先红后绿 |
---
附录 B · 十四个最容易翻的车
1. **waterfall listener 忘了 `next()`**。不报错，下游全静默失效。写一个"观察者必须委托"的 lint 或测试。
2. **`export default` 吞掉 `inject`**。dsh 的 postmortem 0001 就是这个。用命名导出，并在测试里断言 `'default' in mod === false`。
3. **disposer 不幂等**。拆卸路径调两次就炸，而那是最难复现的路径。
4. **拆卸顺序写成注册顺序**。C 依赖 B 的状态，却先撤 B。
5. **绕过日志给模型加上下文**。功能正常，重放和审计静默失真。上不变量。
6. **零 step 的 turn 不记日志**。UI 出现"我发了消息但什么都没发生"的鬼故事。
7. **`max-tokens` 被后续 step 降级**。下游据此判断结果可信度，降级=撒谎。
8. **`turn/end` 不在 `finally` 里**。异常路径留下半个 turn，重放逻辑变成无底洞。
9. **注入型消息也唤醒循环**。每注入一句就烧一次模型调用。
10. **用 waterfall 做安全边界**。任何插件都能提权。安全用单调守卫。
11. **默认值藏在 `run()` 的 `??` 里**。无法记录、无法断言、换 provider 后默默变了。
12. **上层能力直接 import `child_process`**。执行世界从此搬不走，远程沙箱变成幻想。
13. **超量输出直接截断**。模型永远看不到被截掉的部分，也无法要求重看。用 spill：落盘 + 定位符 + 取回说明。
14. **把覆盖率当 KPI 而不是删码工具**。为不可达分支硬写测试，代码越来越肿。未覆盖的行先问"这行是不是死的"。
---
附录 C · 源码对照索引
| 你想理解… | 读真实 dsh 的这里 |
|---|---|
| 五个观念 | `docs/cordis-primer.md`（44 行，5 分钟） |
| 架构全景 | `docs/architecture.md`（129 行，必读） |
| 硬规则清单 | `AGENTS.md`（根，也是 `CLAUDE.md` 的符号链接目标） |
| turn/step 循环 | `packages/core/agent-loop/src/agent.ts:212`（外层）`:246`（turn）`:332`（step） |
| Agent 接口与 inbox | `packages/core/agent/` |
| 会话日志 | `packages/core/session/`（`deriveMessages`、`SessionEventMap`） |
| 工具流水线 | `packages/core/tools/src/index.ts`；图见 `docs/tool-execution-pipeline.md` |
| 流水线顺序不变量 | `packages/core/tools/src/invariant.ts:94-115` |
| 系统提示装配 | `packages/core/system-prompt/` |
| per-agent scope | `packages/core/scope/` |
| seam 范本（三角色） | `packages/shell/`（definition / 4 providers / 3 consumers） |
| 一个执行世界 | `packages/fs/` + `packages/subprocess/`，实证在 `packages/e2b/` |
| 沙箱 | `packages/sandbox/` + `native/landlock-run/` |
| 上下文经济 | `packages/compaction/` `packages/spill/` |
| 目标续跑 | `packages/goal/` |
| 装配分层 | `packages/boot/` `packages/bundle/` `packages/preset/` |
| 不变量制度 | `docs/subsystems/invariants.md` + `packages/runtime-diagnostics/invariants/` |
| 测试宪法 | `docs/testing.md`（49 行，全是干货） |
| 门禁脚本 | `scripts/verify-*.ts`（28 个）、`scripts/run-gates.ts` |
| 设计决策考古 | `.agents/notes/{proposed,implemented,archived,rejected}/`（686 篇） |
| 事故复盘 | `docs/postmortem/0001-0004` |
| 生成的目录 | `docs/config-catalog.md` `tool-catalog.md` `module-graph.md` `capability-seams.md` |
### 本地复现
```bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git rev-parse --short HEAD # 本教程基线 47f9438
pnpm install # node ^22.19 || >=24
pnpm run build
pnpm dsh web # http://127.0.0.1:3080
# 看你的机器真正启动了什么（第 19 步）
pnpm dsh --profile web --dump-config
# 一次性无头任务（需要 DEEPSEEK_API_KEY）
pnpm dsh --profile headless "列出仓库里最大的三个包"
# 让 agent 修改自己的运行时（第 19 步的极端形态）
pnpm run demo:cordis
```
---
结语：这条路线适合谁
**适合你，如果：**
- 你在做一个要活很久的 agent 产品，已经被"每加一个功能都要改主循环"折磨过；
- 你需要同时支持多个前端（CLI / Web / 自动化协议 / SDK），并且受不了行为漂移；
- 你想让第三方写扩展，而不是让他们 fork；
- 你要把 agent 交给团队（或 AI）长期维护，需要把口头约定变成机器门禁。
**不适合你，如果：**
- 你要在一周内验证一个想法。20 步的地基对 demo 是纯负担，第 0 步那个 `main()` 更合适。
- 你的产品形态已经确定且不会长出插件生态。那么这套间接层只是税。
- 你的团队没有维护门禁的意愿。**门禁不跑就是死代码**，而死代码比没有门禁更糟——它给人虚假的安全感。
**一个中间路线**（我推荐大多数人从这里起步）：
只抄前 8 步 + 第 20 步的四条测试规矩。也就是：服务仓库 + inject + 可逆注册 + 四种 dispatch + append-only 日志 + turn/step 双层循环 + "验证世界不验证自述"。
这套组合大约 400 行，能挡住 agent 项目里最贵的那几类返工：上下文丢失、权限被绕过、拆卸泄漏、以及"绿测试坏产品"。剩下的 seam / 沙箱 / spill / bundle，等你真的撞到那个问题时再加——**而这套地基保证了你到时候不用改循环**。
---
> **配套阅读**：[DeepSeek Harness 源码分析](./项目分析/DeepSeek-Harness-源码分析.md)——241 个包的完整名册、协作图谱、73 个服务键、47 个工具、686 篇设计决策文档背后的工程制度。
> **同系列对照**：[Open Design](./项目分析/open-design-源码分析.md)（不写主循环，把别人的 CLI 当引擎）· [Reasonix](./项目分析/DeepSeek-Reasonix-源码分析.md)（同一家公司的另一条路：单二进制 + 缓存优先）· [Claude Code](./Claude-Code-工作原理科普-深入版.md)（工具循环的经典形态）