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

手册/第 01 章

01

没有特权内核

读 dsh 最先要换掉的直觉是:它没有一个「主程序」。 模型适配器、工具注册表、会话日志、甚至 agent 循环本身,在架构上都是插件。

"There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads."
没有可打补丁的特权核心:你通过在同一层旁边再挂一个插件来扩展 dsh,而注册是「副作用」,插件卸载时会自行回滚。
— docs/architecture.md:11

这句话有两个半句,各自都是一个设计决定:

Ⅰ「没有特权核心」
不存在「框架代码」与「用户代码」的分界。内建的会话日志和你写的插件遵守同一套规则, 都通过 ctx 注册、都能被配置替换。所以「改行为」不是打补丁,而是替换提供者。
Ⅱ「注册是副作用」
插件通过 ctx 做的一切——监听事件、注册工具、起定时器——在卸载时自动撤销。 这让「热插拔」和「按需组合」成为可能,而不是靠开发者自觉清理。

一棵在启动时被组合出来的树

"A running dsh is a plugin tree composed at boot from ordered layers."
一个运行中的 dsh,是一棵在启动时由有序层组合出来的插件树。
— docs/architecture.md:15

「有序层」是关键:同一份内核,靠层的顺序决定最终形态。出厂有 5 个 profile 模板—— web、headless、sdk、sdk-minimal、acp, 它们不是 5 个程序,而是 5 份组合清单。

插件的最小形态:两个导出

一个插件就是一个导出 apply(ctx) 的 TypeScript 模块。要依赖别的服务,就再加一行 inject:

typescript · packages/mcp/mcp-client/src/index.ts:30-34, 154(原文)
/** 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 专用路径」。

推而广之 dsh 里每一种能力都是「声明依赖 → 注册实现」这两个动作。理解这一点之后, 剩下的问题就变成:你想改的那一层,它的注册点叫什么名字?(第 08 章有一张 20 行的清单。)

三个事件域

事件既是扩展点,也是「该改哪儿」的第一道分诊(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

本章学习记录

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