1整体形状

这张图要说明的是一个比例问题。19.9 万行代码里,负责"跟模型一来一回"的只占 0.8%。剩下的 99.2% 不是循环的实现细节,是循环周围的可替换层。

这是 dsh 最核心的判断:agent 的难点不在循环里。 ReAct 那一圈,任何人两天就能写对。难的是循环之外 —— 谁能改提示词、工具凭什么被允许执行、上下文压缩后还能不能重放、子 agent 该继承什么、模型看到的东西能不能审计。dsh 把这些全部做成了有名字的缝,而不是循环里的 if。

2它是怎么被拼起来的

dsh 没有主程序入口。你跑起来的那个进程,是五层配置叠出来的一棵 Cordis 插件树。想看你这台机器实际启动的树:

dsh --profile web --dump-config

打出来的每一行都能被你自己的补丁替换掉。这里有三个工程细节,决定了这套东西是"能用"还是"能长期用":

3一次 turn 的完整时序

先把词定死:一个 step = 一次模型请求 + 它调的那批工具。一个 turn = 零个或多个 step —— 它在第一份输入被认领之前就已经打开,直到"没有任何欠账"才关闭。

时序本身没有惊喜,ReAct 那一圈都在。有价值的是三个设计动作:

4工具流水线:灵活段与棘轮段

这条链上最值得抄的是第三段和第二段的关系。dsh 把"灵活"和"不可撤销"拆成了两种物理上不同的注册方式:

5模型可见 = 必须落日志(且当场校验)

文档里那句 "Model-visible means logged"(architecture.md:96)如果只是一句话,那就是空话。dsh 把它做成了一个真的会抛异常的运行时检查:每一次 loop 发出的 LLM 请求,都被用会话日志重新推导一遍,然后逐字节比对。

// Prepend prevents a short-circuiting replay listener from silencing the check.
ctx.on('llm/stream', (options, next) => {
  if (!isAgentLoopRequest(options)) return next()
  if (!Object.isFrozen(options))          fail('a loop-built request must be frozen')
  if (!Object.isFrozen(options.messages)) fail('...must carry a frozen messages array')

  const expected = session.deriveMessages()
  if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
    fail(`... diverges from the dispatch-time durable derivation (log-reconstruction desync)`)
  }
  ...
}, { global: true, prepend: true })

三个细节说明这不是装饰:

• prepend: true,并且注释直接写明理由 —— 防止某个会短路的 replay 监听器把检查静音掉。它假设自己会被别的插件绕过,并主动防了这一手。
• 不只比消息,还比折叠出来的请求头:model、system、temperature、maxTokens、stop、tools 六项逐一对(invariant.ts:44-49)。
• 请求对象和 messages 数组都必须 Object.isFrozen。不是"约定不要改",是改不了。

配套:每个包都必须自带一份 invariant

这条检查不是孤例,它是一套制度的一部分。包级宪法的最后一条规定:每个包都必须发布一个 ./invariant 伴生插件,注册自己的 npm 包名;能写出运行时检查就写,写不出来必须留一条以 No runtime invariant: 开头、且针对本包的具体理由。

"凑数的生成物、没解释的空实现、被忽略的报告"—— 一律让 scripts/verify-package-invariants.ts 挂掉。而 invariants 服务本身刻意不含任何产品逻辑:检查归各包所有,注册表只管调度和生命周期,每个启用的检查跑在自己的子 Cordis fiber 里,失败时原子回滚。

6scope:注册向下继承,事件向上冒泡

这是支撑"一个进程里跑多个 agent、各自有各自能力集"的底层原语。两个方向是反的,而且反得有道理:

• 注册向下 —— 所以一个 preset 的工具和提示词章节在整个进程里只需要挂一次,底下所有加入它的 session 自动都有。不是每个 session 复制一份。
• 事件向上 —— 所以祖先能观察后代,而后代碰不到祖先,兄弟之间完全隔离。一个 session 的事件不会漏进另一个 session 的监听器。

基于这一条,agent-presets 做到的效果是:preset 的工具、提示词章节、投影单元只存在一份,却覆盖所有加入它的 session —— 靠的是把每个 agent 的 scope key 认作它的子。插件自己按 Session/Agent 分状态,所以共用一份实例也不串。

README 里还标了这套机制的硬边界,很实在:如果一个 preset 真要拥有自己的服务,必须放进 isolate realm。否则第二个 preset 注册同名服务会直接撞车,"a host reader would resolve one preset's instance for every session"(agent-presets/README.md:123)。

7能力缝:为什么换一处能动全身

dsh 把"可替换能力"形式化成了三角色结构,并规定:一个包可以兼任多个角色,但只占一个角色不叫缝;新增一项能力意味着把三个角色都设计出来。

图右下是这套东西的实际收益。Bash 工具、PTY 终端、LSP 导航共用同一个执行世界(ctx.fs + ctx.subprocess),所以把这两个 provider 指向远端沙箱,三样工具自动跟着搬过去 —— 不需要给每个工具各写一个"远程版本"。

同一条设计还有一句反向约束,防止缝被某一个消费者绑架:

8把文档做成 CI 卡口

这是我读完最意外的地方。dsh 把几类文档变成了会让构建挂掉的硬约束:

"KV 缓存影响"这一项最能说明问题。看 ralph 工具 README 里那句:

在一个允许任意插件改系统提示词的架构里,提示词前缀稳定性是一个全局共享、且极易被单个插件破坏的资源。dsh 的应对不是禁止改,而是强制每个包声明自己的破坏范围 —— 写不清楚,CI 不让过。

这些看起来过度的纪律,前提是这一条立场:

9取舍(这一节是判断,不是源码事实)