DeepSeek Harness 学习手册 第 05 / 11 章 总目录 单页全本 架构图 GitHub

手册/第 05 章

05

五个机制:dsh 真正跑起来靠什么

前四章建立了「插件树 + turn 契约」。这一章拆开五个反复出现的机制—— 你在 dsh 源码里见到的绝大多数 ctx.xxx 调用,都属于其中之一。

机制一:事件域决定「该用什么方式改」

三个域的边界不是按「模块」划的,是按事实的性质划的(architecture.md:71–73):

SSession:持久事实
追加进日志并经 session/event 广播。判断标准只有一条: 这件事必须活过一次重启吗?是 → Session 事件。
AAgent:在飞的活儿
agent/* 携带一个活着的 Agent:inbox、step、status、request、validation、 continuation。要观察或拦截在飞的工作,用它。
CCapability:给 seam 挂策略
fs/*、tools/*、telemetry/*。 能在不 import 循环的前提下挂上策略或适配器。
为什么这个划分重要 同一个需求换个域实现会坏:把「必须持久」的事实做成 Agent 事件,重载后它消失了; 把「只是策略」做进 Session 事件,你的日志里全是噪音,而且会污染模型可见历史。

机制二:waterfall 是「可被包裹的决策」

dsh 里有 4 组事件是 waterfall,全部集中在「请求发出前」这条线上 (architecture.md:106):agent/pre-step、 agent/request、llm/stream、以及三个 tools/*。 与之相对,agent/turn-stopping 是 serial 且无 next()。

typescript · packages/experimental/hooks-claude-code/src/index.ts:243-249(原文)
ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
  const turn = lastTurn(ctx, exec.agent)
  const merged = await runPoint('PreToolUse', exec.name, preToolPayload(exec), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal })
  if (merged.decision === 'deny') return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' }
  if (merged.decision === 'ask') return { kind: 'ask', ...merged.reason !== undefined ? { reason: merged.reason } : {} }
  return next()
})

这段不是教学示例,是仓库里 hooks-claude-code 插件的真实代码——它把 Claude Code 的 PreToolUse hook 映射到 dsh 的 waterfall 上。三种出口正好展示了 waterfall 的全部用法: deny(短路拒绝)、ask(短路转人工)、next()(委托给下游,让后面的监听者 仍能 block 或替换)。它在注释里把这条规矩写明了:"Our hooks did not block. DELEGATE so a later listener can still block/replace."

Cordis 的明确规定是:协作型监听者改共享对象再委托;拥有决策的监听者直接返回;只做标注的必须委托。 (docs/cordis-primer.md:33–35)这条规则如果违反,表现是「后面的插件静默失效」—— 很难查,所以写插件时值得刻意检查。

机制三:seam 必须三角齐全

"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… one role alone is not a seam."
seam 是一种可替换能力,含三个角色:声明接口的服务定义、实现它的服务提供者、使用它的消费方……只占一个角色不叫 seam。
— docs/architecture.md:136
seam定义在哪换掉它会发生什么
ctx.llmllm/src/index.ts:208(abstract class LlmAdapter)、:401(registerAdapter)换模型厂商,循环一行不改
ctx.toolscore/tools/src/index.ts:99(ToolsService)换工具注册表与执行调度
ctx.sessionscore/session/src/index.ts:525(Session)、:1064(SessionStore)换会话存储后端(含格式代际)
ctx.fsfs/fs/src/index.ts:87(abstract class FileSystem)文件访问指向别处(本地 / 远端沙箱)
ctx.subprocesssubprocess/subprocess/src/index.ts:117(abstract class SubprocessRuntime)进程也在同一个新世界里跑
ctx.sandboxsandbox/sandbox-policy/src/index.ts:134(SandboxPolicyService)换成另一套限制/审批策略

机制四:工具管线拿的是「原始批次」

一个容易忽略的设计:ctx.tools.execute() 接收的是原始批次与并发上限 (architecture.md:120),不是单次调用。意味着调度(并行几个、失败怎么收)属于 seam, 而不是散在循环里。

Ⅰ三道闸,各管一段
pre-execute 管准入(能不能跑);execute 管执行; post-execute 管结果(要不要改写/审计)。三者都是 waterfall。
Ⅱ失败也在契约里
失败的 step 会补记缺失的工具结果(architecture.md:116), 所以模型下一轮看到的历史是完整可读的,而不是缺一条 toolResult。

机制五:执行世界是共享的

这条是 dsh 最容易被低估的设计。fs 与 subprocess 的 provider 共享同一个执行世界(architecture.md:138):

"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."
文件系统与子进程 provider 共享一个执行世界,所以把它们指向远端沙箱时,Bash、PTY、LSP 会一起搬走,provider 不需要分叉。
— docs/architecture.md:138

这就是为什么架构图里 sandbox / fs / subprocess 被画成一个合并节点: 它们不是三个可独立替换的能力,而是同一个「你在这里干活」的世界的三个面。

顺带一个 inbox 细节 一个 inbox 喂一个 driver;注入的上下文要等到一条能唤醒它的消息才生效 (architecture.md:110)。而 AgentLoop 的 inbox 是持久投影, 所以没有活着的 Agent 时,也能看出还有哪些输入在排队。

architecture.md:106 · waterfall 清单 architecture.md:136 · seam 三角色 tools/src/pipeline.ts:200 · pre-execute

本章学习记录

记录仅保存在当前浏览器。