手册/第 01 章
没有特权内核
读 dsh 最先要换掉的直觉是:它没有一个「主程序」。 模型适配器、工具注册表、会话日志、甚至 agent 循环本身,在架构上都是插件。
这句话有两个半句,各自都是一个设计决定:
ctx 注册、都能被配置替换。所以「改行为」不是打补丁,而是替换提供者。
ctx 做的一切——监听事件、注册工具、起定时器——在卸载时自动撤销。
这让「热插拔」和「按需组合」成为可能,而不是靠开发者自觉清理。
一棵在启动时被组合出来的树
dsh is a plugin tree composed at boot from ordered layers."
「有序层」是关键:同一份内核,靠层的顺序决定最终形态。出厂有 5 个 profile 模板——
web、headless、sdk、sdk-minimal、acp,
它们不是 5 个程序,而是 5 份组合清单。
插件的最小形态:两个导出
一个插件就是一个导出 apply(ctx) 的 TypeScript 模块。要依赖别的服务,就再加一行 inject:
/** Cordis plugin name used by loader diagnostics. */ export const name = 'mcp-client' /** Services required by this plugin. */ export const inject = ['tools'] // …略… export async function apply(ctx: Context, config: Config): Promise<void> {
这不是伪代码——MCP 客户端的声明部分就是上面这两行常量
(packages/mcp/mcp-client/src/index.ts:31 与 :34),
而 apply 在 :154。它的工具命名也能看出接入思路:
mcp__<serverName>__<rawName>(:56–58)——
MCP 工具就是被注册进 ctx.tools 的普通工具,走同一道执行管线,不存在「MCP 专用路径」。
三个事件域
事件既是扩展点,也是「该改哪儿」的第一道分诊(docs/architecture.md:67–73):
| 域 | 例子 | 什么时候用它 |
|---|---|---|
| Session 事件 持久事实 | turn/* step/* user/message assistant/message tool/* | 这件事必须活过一次重启。它们追加进日志并经 session/event 广播。 |
Agent 事件agent/* | agent/pre-step agent/request agent/turn-stopping | 你要观察或拦截正在进行的活儿,且手里要有一个活着的 Agent。 |
Capability 事件fs/* tools/* telemetry/* | tools/pre-execute fs/read | 你要给某个 seam 挂策略或适配器,但不想 import 循环。 |
分诊口诀:要活过重启 → Session;要碰活 Agent → Agent;只挂策略 → Capability。 选错域是 dsh 里最常见的返工原因。
architecture.md:11 · 没有特权核心 architecture.md:67 · 三个事件域 mcp-client/src/index.ts:31