全本/第 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
全本/第 02 章
为什么是「可替换」而不是「删减」
pi 的答案是「我不需要的东西不造」。dsh 的答案是「我需要的每个东西都可替换」。 两者都在对抗同一个敌人——不可预期的 harness——但用的是反向手段。
底层是一个通用插件框架,不是自研内核
dsh 没有自己发明组合机制,它用 Cordis——其设计写在论文
A Programming Paradigm for Spatiotemporal Composability(arXiv 2608.25512)里。
官方 docs/cordis-primer.md 把需要的概念压成五条,值得逐条读:
| 想法 | 含义 |
|---|---|
| 插件是实现了 Service 的对象 | 可以是一个带 inject / apply(ctx) 的函数,也可以是 Service 子类。 |
| 上下文是服务的仓库 | 服务占一个稳定的 ctx.<key>(ctx.tools、ctx.llm、ctx.sessions),别人按 key 找,不 import 具体实现。 |
依赖用 inject 声明 | 加载顺序由「服务需求」表达,而不是手写启动序列。 |
| 用类型化事件通信 | 事件名通过 TypeScript 声明合并定义,派发方式有 5 种。 |
| 注册是可逆副作用 | prompt section、工具 schema、适配器、监听器都经 ctx.effect() / ctx.on() 安装,重载与拆卸时可预测地展开。 |
五种派发模式:事件的「公开契约」
这是 Cordis 与常见事件总线最大的差别——派发方式是事件契约的一部分,不是调用方的自由选择
(docs/cordis-primer.md:19–27):
| 模式 | 是否等待 | 顺序 | 有返回值 |
|---|---|---|---|
emit | 否 | 按注册顺序观察 | 无 |
waterfall | 否 | 按注册顺序包裹 | 有 |
parallel | 是 | 并行触发所有监听者 | 无 |
serial | 是 | 按注册顺序依次执行 | 有 |
bail | 否 | 依次执行,直到有人放弃 | 有 |
(...args, next)。调 next() → 把(可能被改写过的)结果交给下一个;
不调 next() 直接返回 → 短路。所以在 dsh 里,「拒绝一个请求」不是一个特殊 API,
而是一个不调 next() 的监听者。
三种范式税的付法
可替换不是免费的。dsh 把成本明确摊到三层上,每一层都对应一类人:
cordis-primer.md,理解 ctx / inject / effect / 五种派发。
否则看到的只是散落的 ctx.on,看不出执行顺序。
和 pi 的分歧其实只有一句
| pi | dsh | |
|---|---|---|
| 不确定性放哪 | 消灭在源头:不做没用的功能,所以没有意外的行为 | 转移到组合层:每个部分都可换,所以意外的行为可以换掉 |
| 你信任谁 | 作者删得对 | 框架组合得对 |
| 扩展的形态 | 同进程 TS 扩展(一个文件) | 插件树上的节点(可被配置替换、可卸载回滚) |
| 失败模式 | 想要的功能它没有 | 能做的事太多,不知道哪个在起作用 |
这两条路线都自洽。真正的判断依据是你的角色:如果你既是作者又是唯一用户,删减更划算; 如果你要在 harness 上长出产品,可替换才有回报。第 09 章会把这条分歧落到具体数字上。
architecture.md:9 · 每一部分都是插件 cordis-primer.md:7 · 五个想法 cordis-primer.md:19 · 五种派发模式
全本/第 03 章
运行时架构:14 个零件,16 条连接
前两章讲的是规则,这一章讲零件。下面这张图是 dsh 运行时主干: 从 profile 解析开始,到插件树里的服务互相找到对方为止。
这张图的画布是 1510px 宽,在内嵌栏里 1× 会把最小字号压到约 3.7px,基本无法阅读。 请点 2×(约 7.9px)或直接用「新窗口 ↗」。这是画布密度与阅读栏宽的物理冲突,不是渲染问题。
怎么读这张图
| 区块 | 它是什么 |
|---|---|
| boot / app-boot | 不在树里——它是「树的构建者」:解析 profile、叠 patch、按 inject 拓扑挂载、审计启动条目。 |
| 插件树(虚线框内) | 运行中的 dsh 本体。框内每个节点都是插件,都通过 ctx 注册。 |
| core 服务 | session / tools / system-prompt / agent-loop / agent registry——循环与状态的所在地。 |
| exec(沙箱 · fs · subprocess) | 一个合并节点:三者共享同一个执行世界,拆开画会误导。 |
| llm / adapter | LlmAdapter 抽象 + 具体适配器;换厂商不动循环。 |
| web app | 浏览器前端(packages/client,17 万行),只是插件树上的一支。 |
四个画图时做的判断
app-boot 画进了框里,校验器报「非成员落在 frame 内」。
但这不是排版问题,是语义问题:boot 是把树搭起来的那双手,不是树上的节点。
registry → tools,那条线穿过了 prompt 与 loop,
且与 loop ↔ llm 共用走廊。改成 tools → mcp:
MCP 客户端的 inject 就是 ['tools'],语义更准。
goal / schedule / jobs /
spill / agent-team 等都没有画——它们的接入方式与图上已有节点同构,
画上去只会让主干难以辨认。
validate 0 error / 0 warning,
finalize --browser-check 全部 pass,visual-check 带 provenance 校验通过。
每个组件与连接都绑定 path:line,行号逐条核对过。
app-boot/src/index.ts:317 · reconcileProfilePatches agent-loop/src/index.ts:291 · class AgentLoop llm/src/index.ts:208 · abstract class LlmAdapter
全本/第 04 章
一次提问:turn 与 step 的契约
架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 dsh 把这件事写成了契约——不是实现细节,而是文档正文。
画布 1080px,1× 下最小字号约 5.2px 勉强、2× 到 11px 舒适。
自上而下四段:① 认领输入与 agent/pre-step,② 组装与请求,③ 工具三道闸,④ 收束与 turn/end。
两个词定死了整件事
注意「零个 step」这个措辞。它不是为了严谨而加的:如果一个 turn 的第一份输入在
agent/pre-step 被拒绝、或被改写为空,这个 turn 会正常关闭,一个模型请求都不发。
这是 dsh 与「先发请求再说」那类实现的根本差别。
权威流程(文档原文)
docs/architecture.md:83–104 用一段缩进文本把整个 turn 写死了,
这也是读 agent-loop 源码前最好的地图:
turn/start
claim next-step input plus one queued message
snapshot Session model selection; assemble prompt sections + step-admitted tool schemas
-> agent/pre-step; project runtime context at fallback
reject | enter(messages, startsRequestSeries?)
reject, or a first enter rewritten empty -> close the turn with no step
step/start
agent/request -> prepareCall (cancellation commits neither system nor users)
reconcile system/message using the prepared call capability
append entered messages as user/message; reconcile retained runtime context
log request/header and request/context as needed
derive and freeze model history from the log
stream the bound prepared call -> llm/stream -> agent/assistant-stream start
agent/assistant-stream chunk*
assistant/message | assistant/attempt -> agent/assistant-stream end
tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
step/end
tools owe another request, or next-step input arrived -> claim -> next step
-> agent/turn-stopping
turn/end
五个与直觉不同的地方
turn/start 是追加进会话日志的事件
(agent-loop/src/agent.ts:329 的 this.session.append('turn/start', …)),
不是内存里的一个标记。turn 一开始就是持久事实。
next() 就委托,不调就直接短路。
所以「这条消息不让它进模型」的实现方式,就是不调 next()。
tools/pre-execute → tools/execute → tools/post-execute
三道 waterfall(architecture.md:106)。
策略、审计、改写参数可以分别挂在不同的闸上。
assistant/message 是成功落定;assistant/attempt 保留失败、重试、取消、
流错误,但不进模型历史。落定前的硬死则不留半条 attempt。
agent/turn-stopping 是 serial 且没有 next()——
你不能在这里改写决定,只能观察。这是与三道工具闸刻意不同的设计。
architecture.md:81 · step / turn 定义 architecture.md:106 · 哪些是 waterfall agent.ts:329 · session.append('turn/start')
全本/第 05 章
五个机制:dsh 真正跑起来靠什么
前四章建立了「插件树 + turn 契约」。这一章拆开五个反复出现的机制——
你在 dsh 源码里见到的绝大多数 ctx.xxx 调用,都属于其中之一。
机制一:事件域决定「该用什么方式改」
三个域的边界不是按「模块」划的,是按事实的性质划的(architecture.md:71–73):
session/event 广播。判断标准只有一条:
这件事必须活过一次重启吗?是 → Session 事件。
agent/* 携带一个活着的 Agent:inbox、step、status、request、validation、
continuation。要观察或拦截在飞的工作,用它。
fs/*、tools/*、telemetry/*。
能在不 import 循环的前提下挂上策略或适配器。
机制二:waterfall 是「可被包裹的决策」
dsh 里有 4 组事件是 waterfall,全部集中在「请求发出前」这条线上
(architecture.md:106):agent/pre-step、
agent/request、llm/stream、以及三个 tools/*。
与之相对,agent/turn-stopping 是 serial 且无 next()。
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 必须三角齐全
| seam | 定义在哪 | 换掉它会发生什么 |
|---|---|---|
ctx.llm | llm/src/index.ts:208(abstract class LlmAdapter)、:401(registerAdapter) | 换模型厂商,循环一行不改 |
ctx.tools | core/tools/src/index.ts:99(ToolsService) | 换工具注册表与执行调度 |
ctx.sessions | core/session/src/index.ts:525(Session)、:1064(SessionStore) | 换会话存储后端(含格式代际) |
ctx.fs | fs/fs/src/index.ts:87(abstract class FileSystem) | 文件访问指向别处(本地 / 远端沙箱) |
ctx.subprocess | subprocess/subprocess/src/index.ts:117(abstract class SubprocessRuntime) | 进程也在同一个新世界里跑 |
ctx.sandbox | sandbox/sandbox-policy/src/index.ts:134(SandboxPolicyService) | 换成另一套限制/审批策略 |
机制四:工具管线拿的是「原始批次」
一个容易忽略的设计:ctx.tools.execute() 接收的是原始批次与并发上限
(architecture.md:120),不是单次调用。意味着调度(并行几个、失败怎么收)属于 seam,
而不是散在循环里。
pre-execute 管准入(能不能跑);execute 管执行;
post-execute 管结果(要不要改写/审计)。三者都是 waterfall。
architecture.md:116),
所以模型下一轮看到的历史是完整可读的,而不是缺一条 toolResult。
机制五:执行世界是共享的
这条是 dsh 最容易被低估的设计。fs 与 subprocess 的 provider
共享同一个执行世界(architecture.md:138):
这就是为什么架构图里 sandbox / fs / subprocess 被画成一个合并节点: 它们不是三个可独立替换的能力,而是同一个「你在这里干活」的世界的三个面。
architecture.md:110)。而 AgentLoop 的 inbox 是持久投影,
所以没有活着的 Agent 时,也能看出还有哪些输入在排队。
architecture.md:106 · waterfall 清单 architecture.md:136 · seam 三角色 tools/src/pipeline.ts:200 · pre-execute
全本/第 06 章
会话:日志即真相,还带版本代际
在 dsh 里,会话不是「聊天的记录」,而是模型所见上下文的唯一来源。 这条规则被写成一句硬话,值得先看它,再看实现。
三句话讲完数据流
deriveMessages() 把模型历史从日志投影出来。历史不是被「维护」的,
是被「推导」的——所以不存在「内存和日志不一致」这种状态。
assistant/message 是成功落定,内嵌产生它的紧凑带时序流;
assistant/attempt 保留失败/重试/取消/流错误,但不进模型历史。
agent/assistant-stream 这条活的事件通道。
这也是为什么 dsh 敢说「硬死也不会留下半条 attempt 流」—— 落定之前,什么都不算数。
投影 seam:客户端看到的不是全部
dsh-session-projection 拥有 ctx.sessionProjections
(architecture.md:130)。注册进去的单元会增量折叠已提交事件,
载体再用 snapshot() 批量取裁剪后的客户端视图。
| 谁 | 职责 |
|---|---|
ctx.sessionProjections | 注册折叠单元;释放注册即退出全局参与,但已有句柄仍继续折叠。 |
AgentRegistry | 拥有 turn / step 状态,对外只给 turnBoundaryOf(session)。 |
AgentLoop | 拥有 modelSelection,并为每个 Agent 构造 model 实例与 inbox。 |
这个设计解决了一个具体问题:前端要的是裁剪过的视图,不是完整日志。 把「折叠」做成可注册的投影,前端就不需要理解每一种事件的语义。
代际迁移:格式如何演化而不丢历史
「Model-visible means logged」有一条硬推论:会话格式必须能变, 否则加一个新的模型可见输入,就等于把旧会话全废掉。dsh 的解法是代际:
| 代 | 文件名 | 说明 |
|---|---|---|
| v0 | session.jsonl[.zstd] | 无版本号的历史格式 |
| v1 及以后 | session.v<N>.jsonl[.zstd] | 小写 vN,代际显式入名 |
规则本身很短,但每条都有代价意识(architecture.md:126):
- 相邻两代恰好一个迁移包,每个包只负责
vN → vN+1一步——链式,不做笛卡尔积。 - 已提交的代际路径永不重命名、替换或删除(原文:"committed generation paths are never renamed, replaced, or deleted")。
- 写打开时先编码、校验,再独占发布一个版本命名的后继文件,源文件保持不动。
- 遇到未来版本直接拒绝,而不是猜着解析。
- 只读打开不发布后继,迁移结果只在内存里用一次。
顺手一个坑:中断的尾巴
进程被杀,日志末尾可能缺一条 turn/end。普通修复是 handle 消费方的责任;
迁移只在一种受限情形下补:那段被中断的 turn 已经被后来的 turn/start 封住了
(architecture.md:126)。这条边界划得很克制——不猜、不乱补。
architecture.md:128 · Model-visible means logged architecture.md:126 · 代际与迁移 session-projection/src/index.ts:252
全本/第 07 章
它明确不做的事
一个项目的边界,写在它愿意承认「这不是我的责任」的地方。 dsh 在这方面异常直白——直白到如果只看 README 的头 15 行,你可能会以为它在劝你别用。
不做承诺一:稳定性
这句话和「万物皆插件」是一条链上的两端。既然插件树要不断重组,接口就必然要动。 dsh 没有选择「先冻结核心 API 再长生态」,而是选择「先让组合能力成立,再让生态跟上」。
不做承诺二:安全隔离
SAFETY.md 的措辞比大多数项目更狠,且区分了三层责任:
这是第 05 章「执行世界」的另一面:沙箱是可替换的策略,不是安全承诺。
项目明确说「不要把 dsh 当作不可信工作负载的唯一安全控制」(SAFETY.md:15),
并建议扔进一次性虚拟机或容器里跑。
ctx.sandbox 这一层的价值就不在「更安全」,
而在「策略可以换、可以组合、可以审计」。评估它时该问的是「能不能表达我的规则」,
而不是「它能不能挡住一切」。
不做承诺三:「那个界面」
dsh 没有「主界面」。web、headless、sdk、sdk-minimal、
acp 是五个平级 profile,不是「主程序 + 若干模式」。
连 dsh-base 里也只有模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测——
没有 UI。
| profile | 它多了什么 |
|---|---|
web | dsh-web-app:浏览器应用(packages/client,17 万行) |
headless | dsh-headless:无服务端的一次性 runner |
sdk | dsh-sdk-app:SDK 的 JSON-RPC 服务端 |
acp | dsh-acp-app:只做自动化的 ACP 服务端 |
sdk-minimal | 刻意例外:自己拥有完整显式树,不套用 dsh-base |
不做承诺四:替你决定
dsh 把「怎么配」摊开给你看,而不是替你选:
dsh --profile web --dump-config
打印出这台机器实际启动的插件树,它打印的每一行都可以被你自己的 patch 替换
(architecture.md:37)。此外还有 --dump-config-schema(打印 JSON Schema,不挂载)
和 --dump-default-config(去掉用户层与 --patch 后的裸树)。
这是一种「不做承诺」的正面版本:不承诺某个推荐配置,但承诺你可以看到并改掉每一层。
边界清单
| 它不做 | 因为 |
|---|---|
| 承诺 API 稳定 | 组合层的自由度优先于生态的稳定性 |
| 承诺安全隔离 | 沙箱是策略,不是保证(SAFETY.md:13) |
| 定义「官方界面」 | 五种 profile 平级,UI 只是一个插件分支 |
| 替你选配置 | 换成「让你看得见并可改」 |
| 替你决定策略 | 审批/沙箱是插件,规则写在插件里 |
把这些连起来看,dsh 的自我定位就清楚了:它是一个「组合能力的提供者」,不是一个「开箱即用的产品」。
产品由上层(apps/web、第三方桌面端、你的 SDK 调用方)来定义。
README.md:13 · developer preview SAFETY.md:13 · 沙箱不保证隔离 architecture.md:23 · dsh-base 的内容
全本/第 08 章
扩展与集成:三层组合 + 20 个扩展点
这一章是操作性的:你要改 dsh,先要判断「改哪一层」,再查「注册点叫什么」。 两件事都有明确答案,不需要读完整棵插件树。
三层:profile → bundle → patch
层序是写死的(architecture.md:25):
profile 的有序 bundle → 该 profile 的 cordis.patch.yml → home patch → --patch 覆盖层。
层的作用对象是空的条目列表——不是修改某个已存在的程序,而是一层层往上叠。
| 层 | 是什么 | 怎么声明 |
|---|---|---|
| profile | Harness home 里的一份具名组合:用哪些 bundle、装哪些树外插件、以及用户自己的 cordis.patch.yml | package.json 的 dsh.profile 列出它的 bundle |
| bundle | Cordis 配置行 + 它挂载的代码的分发格式;插进去之后仍可被上层 patch | package.json 的 dsh.bundle 指向它的 patch 文件 |
| patch | 按行 id 定位并整块替换它的 config,或插入新行;preset 则在某个声明的 config.plugins 内做同样操作 | YAML;--patch 可重复叠加 |
关键推论:bundle 里插进去的东西永远可被上层替换。所以「官方实现」在你的 profile 里不占特殊地位—— 你可以在 patch 里把它的 config 整个换掉,而不用 fork。
看树、改树、装插件
# 打印这台机器实际启动的插件树(每一行都能被 patch 替换) dsh --profile web --dump-config # 只看 schema,不挂载 dsh --profile web --dump-config-schema # 去掉用户层与 --patch 之后的裸树 dsh --profile web --dump-default-config # 临时叠一层 patch 启动 dsh tui --patch ./extra.yml # 往某个 profile 里装插件(转发给该 profile 目录下的 pnpm) dsh plugin --profile tui add <package> # 用出厂模板重置一个坏掉的 profile dsh rescue --from-default-profile web
注意 dsh plugin 的语义:它不是自定义包管理器,而是把参数转发给
profile 目录下的 pnpm(cli-help.md:69–70)。所以插件就是普通的 npm 包,
依赖解析、锁文件、私有 registry 全都沿用生态。
20 个扩展点:目标 → 机制
架构文档的最后一张表(architecture.md:146–167)是 dsh 最实用的一页。
下表把它完整译出——左边是「你想做什么」,右边是「在哪注册」:
| 你想做的事 | 机制 |
|---|---|
| 加一个模型供应商 | 在 ctx.llm 上注册它的 adapter |
| 加一个模型可见能力 | 在 ctx.tools 上注册;它的 schema 会进入 prompt 组装 |
| 给某个会话不同的能力集 | 组合一个 agent preset;其中的服务行需要 isolate realm |
| 加 shell 执行 | 注册 ctx.shell 后端;本地实现经 ctx.subprocess 起进程 |
| 加持久终端执行 | 注册 ctx.terminals 后端 + dsh-tool-terminal |
| 加一个人工命令 | 在 ctx.commands 注册;它不经过模型 turn 直接派发 |
| 管后台任务 | 在 ctx.jobs 注册;job_* 工具负责读/停 |
| 从外部 webhook 起一个会话 | 在 ctx.webhookRuntime 注册可信规则并挂一个 provider adapter |
| 加文件系统访问或策略 | 注册 ctx.fs provider,或监听 fs/* 事件 |
| 约束生成的进程 | 用 ctx.sandbox 后端;消费方在 spawn 前包装 argv |
| 拦截请求 / 工具 / turn | 用对应的 agent/* 或 tools/* 事件;agent/turn-stopping 可停 turn |
| 加模型可见上下文 | 调 agent.inject();它落在下一次被准入的请求里 |
| 加 UI 或编辑器集成 | 驱动 ctx.agents,从 session/event 渲染 |
| 加一个 Web 聊天节点 | 注册 ConversationNodeDefinition + 带 key 的 renderer |
| 加持久会话状态 | 扩展 SessionEventMap;从日志渲染与重放 |
| 生成会话标题 | 注册唯一的 ctx.sessionTitle provider |
| 管理同会话内的目标 | 用 ctx.goals;经 agent/* 续跑 |
| 在 turn 边界分叉 | ctx.agents.create({ sessionId, seed, inheritedEventCount, meta: { isSeeded: true } });只有 agent-loop 发布的会话会持久化 |
| 把会话存到新后端 | 实现 SessionPersistence(create/open/stat/list/export),复用共享的 handle 脚手架 |
| 把注册限定到某一个 agent | 用那个 agent 的 agent.ctx |
ctx.* 或事件名。
如果找不到接近的行,通常意味着你该做的是一个新 seam(定义 + 提供者 + 消费方),
而不是硬塞进已有的某一层。
集成的三条外部通道
inject: ['tools'] 的普通插件。
MCP 工具命名 mcp__<serverName>__<rawName>,走同一道执行管线。
sdk profile 里的 dsh-sdk-app 提供 JSON-RPC 服务端;
仓库还带 python/sdk,非 Node 调用方走这条路。
acp profile 的 dsh-acp-app 是「只做自动化」的服务端——
同一份内核的第四种外壳。
architecture.md:25 · 层序 architecture.md:146 · 20 个扩展点 cli-help.md:41 · --patch
全本/第 09 章
与 pi 的对照,以及一个不对称的事实
dsh 和 pi 常被放在一起讨论,因为它们对「harness 该有多大」给出了相反答案。 这一章把分歧落到数字和代码上,不靠印象。
规模:两种口径,结论同向
规模对比最容易被写错的地方是口径:算不含算测试、「包」怎么数、统计到哪一层。 下表把两种口径都列出来,左右两侧用**同一条 `find` 命令**跑出,可以自己复现。
| 指标 | pi | dsh | 倍数 |
|---|---|---|---|
| workspace 包 | 11 | 363(52 组)+ 5 apps | 33× |
packages/ 下 TS/TSX,含测试 | 419,908 行 | 1,112,305 行 | 2.65× |
packages/ 下 TS/TSX,不含测试 | 217,943 行 | 504,068 行 | 2.31× |
agent 内核(*/src,不含测试) | packages/agent/src 6 文件 / 2,541 行 | packages/core/*/src 10 包 / 14,562 行 | 5.73× |
| agent 内核(整包,含测试) | 16 文件 / 6,929 行 | 133 文件 / 49,142 行 | 7.09× |
| 最大单包(含测试) | coding-agent 164,445 行 | client(Web 前端)363,080 行 | 2.21× |
| Markdown 篇数 | 142 | 4,763 | 33.5× |
| revision | 531340f(2026-10-27) | 22ddee3(2026-10-23) | — |
复现命令:find <repo>/packages -type f \( -name '*.ts' -o -name '*.tsx' \) ! -path '*/node_modules/*' | xargs cat | wc -l;
不含测试再追加 ! -name '*.test.*' ! -name '*.spec.*' ! -path '*/__tests__/*' ! -path '*/fixtures/*' ! -path '*/e2e/*'。
包数取 packages/*/package.json(pi 扁平)与 packages/*/*/package.json(dsh 两层)。
读懂这张表的关键:几种口径给出同一个故事——总量差 2.3–2.7 倍, 内核差 5.7–7.1 倍。也就是说 dsh 的体积不在循环里,而在外围: Web 前端 17.4 万行、实验区 7.3 万行、脚本 4.5 万行(均不含测试)。
方向:一个往下删,一个往外长
| pi | dsh | |
|---|---|---|
| 核心循环 | 就是代码,12 个文件(不含测试)读得完 | class AgentLoop extends Service,可换实现 |
| 上下文 | 静态短 prompt(<1000 token)+ 4 工具 | section 组装 + 工具 schema 准入 + agent/pre-step 闸门 |
| 工具 | 一处五段管线 | 三道 waterfall,任何插件可挂策略 |
| 会话 | JSONL + 12 种 entry,jq 可分析 | append-only 事件 + 投影 seam + 代际迁移链 |
| 安全 | 明写 YOLO,不做权限系统 | ctx.sandbox + 审批策略,但明确不保证隔离 |
| 稳定承诺 | 为保住工作流而稳定 | 明写会破坏兼容 |
| 扩展成本 | 一个 TS 文件 | 一个 Cordis 插件 + 理解三层组合 |
| 失败模式 | 想要的功能它没有 | 能做的太多,不知道哪个在起作用 |
一个不对称的事实
这条在对比文章里几乎没人写,但它是 dsh 仓库里的一行依赖:
"name": "@deepseek-ai/dsh-llm-pi-ai", "version": "0.2.1-rc.3", "description": "pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (design-verification twin of dsh-llm-deepseek)", "dependencies": { "@earendil-works/pi-ai": "^1.3.0" }
dsh 把 pi 的模型层当成自己的一个 LLM 适配器在用。这段 description 里的
「design-verification twin」值得逐字读:它是 dsh-llm-deepseek 的设计验证孪生体——
用一个完全独立的实现(pi-ai)落在同一个 LlmAdapter 接口上,
来证明这层抽象是真的成立,而不是为某一家厂商量身定做。
反方向不成立:pi 不会用 dsh 的任何东西,它的设计前提就是「不引入别人的框架」。 这条不对称,恰好就是两种哲学最纯粹的体现。
怎么选:四个问题
| 如果你的答案是 | 选 |
|---|---|
| 我要能被一个人完全理解,发版后行为不变 | pi |
| 我要在 harness 上长出一个产品,多种外壳共享内核 | dsh |
| 我的会话要活过多次版本升级,还要被别的系统消费 | dsh(代际设计) |
| 我不能接受破坏性变更,也不想要插件市场 | pi |
llm-pi-ai/package.json · 依赖 pi-ai llm/src/index.ts:208 · LlmAdapter README.md:13
全本/第 10 章
动手:从跑起来到写第一个插件
这一章的所有命令都来自仓库文档,可以照抄。 顺序刻意设计成「先看树,再改树」——这样你写的第一个插件不会挂在错误的层上。
第一步:跑起来
npx @deepseek-ai/dsh web
默认在 http://127.0.0.1:3080 起 Web UI 并打开浏览器;加 --no-open 只起服务不开浏览器。
从源码跑则是(README.md:33–39):
git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web
pnpm run build 准备产物;pnpm dsh web 直接使用这些已构建产物,不会重新构建。
改前端源码时用 pnpm run dev:web(构建 + 起服务 + 监听源码变化重建,README.md:57)。
第二步:把树打印出来
在看任何源码之前,先看你这台机器实际启动了什么:
dsh --profile web --dump-config
它会打印组合出来的 profile 树然后退出。看三件事:
idid 定位并整块替换 config 的。
记住你想改的那行的 id,比记住包名有用。
dsh-base,哪几行来自 dsh-web-app。
你的 patch 会盖在它们之上。
配套的两个命令:--dump-default-config 打印去掉用户层与 --patch 之后的裸树
(用来判断「这是官方默认还是我改过的」);--dump-config-schema 只打印 JSON Schema,不挂载
(写 patch 时查字段用)。
第三步:写第一个插件
官方教程的路径最短,直接照它走(docs/user/develop/basic/index.md)。
先建一个草稿项目:
mkdir -p scratch-plugin/src
插件就是一个导出 apply 的 TypeScript 模块:
import type { Context } from '@deepseek-ai/cordis' export const name = 'hello-plugin' export function apply(ctx: Context) { // Required dependencies are ready before apply runs. console.log('[hello-plugin] plugin loaded!') }
然后用一份 overlay 把它插进 web profile。注意路径必须是绝对路径:
- insert:
- id: hello
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
pnpm dsh web --patch ./scratch-plugin/cordis.yml
打开 http://127.0.0.1:3080,启动时终端会打印 [hello-plugin] plugin loaded!。
第四步:理解「自动清理」与 inject
通过 ctx 注册的一切——事件监听、工具、定时器——在插件卸载时自动清理,
不需要你手写 removeListener。需要显式释放的资源(比如网络连接)用 ctx.effect() 交出 disposer:
export function apply(ctx: Context) { ctx.effect(() => { const timer = setInterval(() => { console.log('heartbeat') }, 5000) // The returned function runs when the plugin unloads. return () => clearInterval(timer) }) }
要用别的服务(tools、llm),就声明 inject——
框架会等这些服务就绪再加载你,所以加载顺序不需要你操心:
export const name = 'my-tool-plugin' export const inject = ['tools'] export function apply(ctx: Context) { // ctx.tools is ready here. }
自检清单:我到底改对层了吗
| 现象 | 多半是 |
|---|---|
| 插件没被加载 | cordis.yml 的 name 用了相对路径(必须绝对) |
加载了但拿不到 ctx.tools | 漏了 inject: ['tools'] |
| 你改的 config 没生效 | 被上层 patch 覆盖了——用 --dump-config 看最终值 |
| 下游插件静默失效 | waterfall 里没调 next() 却本意只是观察 |
| 重启后你的状态丢了 | 你把它做成了 Agent 事件,而它应该是一个 Session 事件 |
| 改了行为但前端看不到 | 只发了 live 事件,没有落成 Session 事件(违反「Model-visible means logged」) |
docs/user/develop/basic/index.md · 第一个插件 architecture.md:34 · --dump-config README.md:33 · 从源码运行
全本/第 11 章
延伸阅读:按「你想搞清楚什么」排序
dsh 有 4,763 篇 Markdown。按目录读会迷路,按问题读不会。 下面每一行都是「一个问题 → 一篇文档」,路径都相对仓库根目录。
六条最短路径
| 你想搞清楚 | 读这篇 | 大概要多久 |
|---|---|---|
| 整体架构与「新行为放哪」 | docs/architecture.md | 20 分钟,必读 |
| Cordis 那套插件/作用域怎么运作 | docs/cordis-primer.md | 15 分钟,读代码前必读 |
| 一次 turn 的完整生命周期 | docs/agent-lifecycle.md | 15 分钟 |
| 工具调用到底经过哪些环节 | docs/tool-execution-pipeline.md | 10 分钟 |
| 某个事件谁发谁收 | docs/event-producer-consumer.md | 查表,随时 |
| 六个 seam 的全景图 | docs/capability-seams.md | 10 分钟 |
按角色读
README.md → docs/user/guide/index.md → SAFETY.md(务必读)。
不需要碰架构文档。
docs/user/develop/basic/index.md(第一个插件)→
docs/cordis-primer.md →
docs/cookbook/extension-cookbook.md →
按需看 adding-a-tool.md / adding-an-llm-adapter.md。
docs/architecture.md 全文 →
docs/cordis-primer.md →
docs/subsystems/core.md →
packages/core/agent-loop/README.md(那里写了实现顺序)。
docs/architecture.md 的 Profiles and bundles →
packages/boot/app-boot/README.md →
docs/cli-help.md(patch / profile / plugin 子命令)。
百科式入口
| 文件 | 它是什么 |
|---|---|
docs/config-catalog.md | 生成的配置字段目录(写 patch 时查字段用) |
docs/cli-help.md | 完整的启动器/子命令/出厂 profile 帮助 |
docs/subsystems/*.md | 分子系统深挖:core、tools、session、subagent、agent-team、conversation、working-directory… |
docs/cordis-tutorial/index.md | 把 primer 的概念动手做一遍 |
docs/development.md | 开发流程、构建目标、Web/Desktop 命令表 |
AGENTS.md | 给 agent 读的仓库约定(如果你让 agent 帮你改 dsh) |
外部链接
- 文档站:deepseek-harness.github.io
- Cordis 仓库:cordiverse/cordis
- 范式论文:A Programming Paradigm for Spatiotemporal Composability(arXiv 2608.25512)
- Discord:DeepSeek Harness community
- 插件发现:给仓库打
dsh-plugintopic
读完这本手册之后
如果你只记三件事,记这三条:
- dsh 是一棵组合出来的树。没有特权核心,改行为 = 换提供者或挂监听,不是打补丁。
- 日志是唯一真相。模型可见的东西必须被记录;格式有代际,已发布文件不可变。
- 扩展之前先分诊。持久事实 → Session 事件;在飞的活儿 → Agent 事件;策略 → Capability 事件或 seam。
剩下的都是细节,而细节都在 docs/architecture.md 里,且写得比大多数项目都清楚。
docs/cookbook/extension-cookbook.md docs/event-producer-consumer.md docs/capability-seams.md