DeepSeek Harness 学习手册 单页全本 总目录 回到开头 架构图 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

全本/第 02 章

02

为什么是「可替换」而不是「删减」

pi 的答案是「我不需要的东西不造」。dsh 的答案是「我需要的每个东西都可替换」。 两者都在对抗同一个敌人——不可预期的 harness——但用的是反向手段。

"Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration."
产品的每一个部分都是插件,包括模型适配器、工具注册表、会话日志,以及 agent 循环本身——所以每一个都能从配置里替换掉。
— docs/architecture.md:9

底层是一个通用插件框架,不是自研内核

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否依次执行,直到有人放弃有
waterfall 是 around-middleware 监听者收到 (...args, next)。调 next() → 把(可能被改写过的)结果交给下一个; 不调 next() 直接返回 → 短路。所以在 dsh 里,「拒绝一个请求」不是一个特殊 API, 而是一个不调 next() 的监听者。

三种范式税的付法

可替换不是免费的。dsh 把成本明确摊到三层上,每一层都对应一类人:

Ⅰ读代码的人
得先读 cordis-primer.md,理解 ctx / inject / effect / 五种派发。 否则看到的只是散落的 ctx.on,看不出执行顺序。
Ⅱ做产品的人
得理解 profile → bundle → patch 三层,否则不知道自己的改动会被哪一层覆盖。 出厂 5 个 profile 不是 5 个程序,是 5 份可被上层 patch 的清单。
Ⅲ用产品的人
得接受 developer preview 的破坏性变更——这是「不断重组插件树」的直接代价, 不是没做完的借口,是路线的必然结果。

和 pi 的分歧其实只有一句

pidsh
不确定性放哪消灭在源头:不做没用的功能,所以没有意外的行为转移到组合层:每个部分都可换,所以意外的行为可以换掉
你信任谁作者删得对框架组合得对
扩展的形态同进程 TS 扩展(一个文件)插件树上的节点(可被配置替换、可卸载回滚)
失败模式想要的功能它没有能做的事太多,不知道哪个在起作用

这两条路线都自洽。真正的判断依据是你的角色:如果你既是作者又是唯一用户,删减更划算; 如果你要在 harness 上长出产品,可替换才有回报。第 09 章会把这条分歧落到具体数字上。

architecture.md:9 · 每一部分都是插件 cordis-primer.md:7 · 五个想法 cordis-primer.md:19 · 五种派发模式

全本/第 03 章

03

运行时架构:14 个零件,16 条连接

前两章讲的是规则,这一章讲零件。下面这张图是 dsh 运行时主干: 从 profile 解析开始,到插件树里的服务互相找到对方为止。

dsh 运行时架构 · 14 components / 16 edges / 5 cards 新窗口 ↗

这张图的画布是 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 / adapterLlmAdapter 抽象 + 具体适配器;换厂商不动循环。
web app浏览器前端(packages/client,17 万行),只是插件树上的一支。

四个画图时做的判断

Ⅰ把 boot 移出插件树
第一版把 app-boot 画进了框里,校验器报「非成员落在 frame 内」。 但这不是排版问题,是语义问题:boot 是把树搭起来的那双手,不是树上的节点。
Ⅱ把 sandbox / fs / subprocess 合成一个节点
它们共享同一执行世界:把 fs 指向远端沙箱,Bash、PTY、LSP 会一起搬走。 画成三个节点会让人以为可以单独替换其中一个。
ⅢMCP 接的是 tools,不是 core
原本画了一条 registry → tools,那条线穿过了 prompt 与 loop, 且与 loop ↔ llm 共用走廊。改成 tools → mcp: MCP 客户端的 inject 就是 ['tools'],语义更准。
Ⅳ只画主干,不画全
363 个包里上图的是 14 个(按能力分层,不按包数量)。goal / schedule / jobs / spill / agent-team 等都没有画——它们的接入方式与图上已有节点同构, 画上去只会让主干难以辨认。
这张图的校验状态 Archify v3.2 产出: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 章

04

一次提问:turn 与 step 的契约

架构图回答「有哪些零件」,时序图回答「它们按什么顺序说话」。 dsh 把这件事写成了契约——不是实现细节,而是文档正文。

dsh 单轮时序 · 8 participants / 14 messages / 4 fragments 新窗口 ↗

画布 1080px,1× 下最小字号约 5.2px 勉强、2× 到 11px 舒适。 自上而下四段:① 认领输入与 agent/pre-step,② 组装与请求,③ 工具三道闸,④ 收束与 turn/end。

两个词定死了整件事

"A step is one model request plus the tools it calls. A turn is zero or more steps: it opens before its first input is claimed and closes once nothing is owed."
一个 step 是一次模型请求加上它调用的工具。一个 turn 是零个或多个 step:它在第一份输入被认领之前开始,在不再欠任何东西时关闭。
— docs/architecture.md:81

注意「零个 step」这个措辞。它不是为了严谨而加的:如果一个 turn 的第一份输入在 agent/pre-step 被拒绝、或被改写为空,这个 turn 会正常关闭,一个模型请求都不发。 这是 dsh 与「先发请求再说」那类实现的根本差别。

权威流程(文档原文)

docs/architecture.md:83–104 用一段缩进文本把整个 turn 写死了, 这也是读 agent-loop 源码前最好的地图:

text · docs/architecture.md:83-104
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 一开始就是持久事实。
Ⅱpre-step 能拒绝,不只是能改
它是 waterfall:监听者调 next() 就委托,不调就直接短路。 所以「这条消息不让它进模型」的实现方式,就是不调 next()。
Ⅲ工具过三道闸,不是一道
tools/pre-execute → tools/execute → tools/post-execute 三道 waterfall(architecture.md:106)。 策略、审计、改写参数可以分别挂在不同的闸上。
Ⅳ失败也有座位
assistant/message 是成功落定;assistant/attempt 保留失败、重试、取消、 流错误,但不进模型历史。落定前的硬死则不留半条 attempt。
Ⅴ模型至少被调用两次
工具结果也是消息。第一次请求返回「我要调 bash」,工具跑完后结果作为新历史必须再请求一次。 循环条件就是:工具还欠一次请求 → 认领 → 下一个 step。
Ⅵ收尾是串行的,没有 next
agent/turn-stopping 是 serial 且没有 next()—— 你不能在这里改写决定,只能观察。这是与三道工具闸刻意不同的设计。

architecture.md:81 · step / turn 定义 architecture.md:106 · 哪些是 waterfall agent.ts:329 · session.append('turn/start')

全本/第 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

全本/第 06 章

06

会话:日志即真相,还带版本代际

在 dsh 里,会话不是「聊天的记录」,而是模型所见上下文的唯一来源。 这条规则被写成一句硬话,值得先看它,再看实现。

"Model-visible means logged. Every model request must be reconstructable from the log. New model-visible inputs require session events."
模型看得见的,就必须被记录。每一次模型请求都必须能从日志重建;任何新的、模型可见的输入,都必须先成为会话事件。
— docs/architecture.md:128

三句话讲完数据流

Ⅰ日志 → 历史
deriveMessages() 把模型历史从日志投影出来。历史不是被「维护」的, 是被「推导」的——所以不存在「内存和日志不一致」这种状态。
Ⅱ两次落定,语义不同
assistant/message 是成功落定,内嵌产生它的紧凑带时序流; assistant/attempt 保留失败/重试/取消/流错误,但不进模型历史。
Ⅲ一切都从落定推导
fork、resume、transcript、telemetry、持久化全部由这些持久落定推导; 只有「UI 增量」走 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 的解法是代际:

代文件名说明
v0session.jsonl[.zstd]无版本号的历史格式
v1 及以后session.v<N>.jsonl[.zstd]小写 vN,代际显式入名

规则本身很短,但每条都有代价意识(architecture.md:126):

  1. 相邻两代恰好一个迁移包,每个包只负责 vN → vN+1 一步——链式,不做笛卡尔积。
  2. 已提交的代际路径永不重命名、替换或删除(原文:"committed generation paths are never renamed, replaced, or deleted")。
  3. 写打开时先编码、校验,再独占发布一个版本命名的后继文件,源文件保持不动。
  4. 遇到未来版本直接拒绝,而不是猜着解析。
  5. 只读打开不发布后继,迁移结果只在内存里用一次。
为什么值得单独一章 这是 dsh 与「一个 JSONL 一把梭」最实质的差别。两者都用 JSONL, 但 dsh 把它当成需要长期演进的协议:要有版本、要能前向拒绝、要能链式迁移、要保证已发布文件不可变。 这些东西在只服务自己的工具里是纯负担,在要活过多年的产品里是必需品。

顺手一个坑:中断的尾巴

进程被杀,日志末尾可能缺一条 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 章

07

它明确不做的事

一个项目的边界,写在它愿意承认「这不是我的责任」的地方。 dsh 在这方面异常直白——直白到如果只看 README 的头 15 行,你可能会以为它在劝你别用。

"DeepSeek Harness is in developer preview and iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES."
DeepSeek Harness 处于开发者预览阶段,正在快速迭代。一定会有破坏兼容性的变更。
— README.md:13

不做承诺一:稳定性

这句话和「万物皆插件」是一条链上的两端。既然插件树要不断重组,接口就必然要动。 dsh 没有选择「先冻结核心 API 再长生态」,而是选择「先让组合能力成立,再让生态跟上」。

Ⅰ代价是真实的
你今天写的插件,下次发版可能要改。这不是 bug,是路线:他明确写了会破坏兼容。 参考上一章——会话格式反而有严格代际保证,因为历史数据丢了没法重建,而插件代码可以改。
Ⅱ反过来说
如果你需要「发版不改变我的工作流」,dsh 现在就不是那个选择—— 这正是 pi 存在的理由(见第 09 章)。

不做承诺二:安全隔离

SAFETY.md 的措辞比大多数项目更狠,且区分了三层责任:

"It has not undergone a security audit and must not be treated as secure or production-ready."
它没有经过安全审计,不得被视为安全的或可用于生产。
— SAFETY.md:7
"Sandboxing, approval prompts, and permission controls can reduce risk, but they do not guarantee isolation or prevent damage."
沙箱、审批提示与权限控制能降低风险,但不能保证隔离,也不能阻止损害。
— SAFETY.md:13

这是第 05 章「执行世界」的另一面:沙箱是可替换的策略,不是安全承诺。 项目明确说「不要把 dsh 当作不可信工作负载的唯一安全控制」(SAFETY.md:15), 并建议扔进一次性虚拟机或容器里跑。

这条对读代码的人也有用 既然沙箱不做保证,那 ctx.sandbox 这一层的价值就不在「更安全」, 而在「策略可以换、可以组合、可以审计」。评估它时该问的是「能不能表达我的规则」, 而不是「它能不能挡住一切」。

不做承诺三:「那个界面」

dsh 没有「主界面」。web、headless、sdk、sdk-minimal、 acp 是五个平级 profile,不是「主程序 + 若干模式」。 连 dsh-base 里也只有模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测—— 没有 UI。

profile它多了什么
webdsh-web-app:浏览器应用(packages/client,17 万行)
headlessdsh-headless:无服务端的一次性 runner
sdkdsh-sdk-app:SDK 的 JSON-RPC 服务端
acpdsh-acp-app:只做自动化的 ACP 服务端
sdk-minimal刻意例外:自己拥有完整显式树,不套用 dsh-base

不做承诺四:替你决定

dsh 把「怎么配」摊开给你看,而不是替你选:

sh · docs/architecture.md:33-35
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 章

08

扩展与集成:三层组合 + 20 个扩展点

这一章是操作性的:你要改 dsh,先要判断「改哪一层」,再查「注册点叫什么」。 两件事都有明确答案,不需要读完整棵插件树。

三层:profile → bundle → patch

层序是写死的(architecture.md:25): profile 的有序 bundle → 该 profile 的 cordis.patch.yml → home patch → --patch 覆盖层。 层的作用对象是空的条目列表——不是修改某个已存在的程序,而是一层层往上叠。

层是什么怎么声明
profileHarness home 里的一份具名组合:用哪些 bundle、装哪些树外插件、以及用户自己的 cordis.patch.ymlpackage.json 的 dsh.profile 列出它的 bundle
bundleCordis 配置行 + 它挂载的代码的分发格式;插进去之后仍可被上层 patchpackage.json 的 dsh.bundle 指向它的 patch 文件
patch按行 id 定位并整块替换它的 config,或插入新行;preset 则在某个声明的 config.plugins 内做同样操作YAML;--patch 可重复叠加

关键推论:bundle 里插进去的东西永远可被上层替换。所以「官方实现」在你的 profile 里不占特殊地位—— 你可以在 patch 里把它的 config 整个换掉,而不用 fork。

看树、改树、装插件

sh · docs/cli-help.md
# 打印这台机器实际启动的插件树(每一行都能被 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(定义 + 提供者 + 消费方), 而不是硬塞进已有的某一层。

集成的三条外部通道

MMCP
不是特殊协议层,而是一个 inject: ['tools'] 的普通插件。 MCP 工具命名 mcp__<serverName>__<rawName>,走同一道执行管线。
SSDK(JSON-RPC)
sdk profile 里的 dsh-sdk-app 提供 JSON-RPC 服务端; 仓库还带 python/sdk,非 Node 调用方走这条路。
AACP
acp profile 的 dsh-acp-app 是「只做自动化」的服务端—— 同一份内核的第四种外壳。

architecture.md:25 · 层序 architecture.md:146 · 20 个扩展点 cli-help.md:41 · --patch

全本/第 09 章

09

与 pi 的对照,以及一个不对称的事实

dsh 和 pi 常被放在一起讨论,因为它们对「harness 该有多大」给出了相反答案。 这一章把分歧落到数字和代码上,不靠印象。

规模:两种口径,结论同向

规模对比最容易被写错的地方是口径:算不含算测试、「包」怎么数、统计到哪一层。 下表把两种口径都列出来,左右两侧用**同一条 `find` 命令**跑出,可以自己复现。

指标pidsh倍数
workspace 包11363(52 组)+ 5 apps33×
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 篇数1424,76333.5×
revision531340f(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 万行(均不含测试)。

方向:一个往下删,一个往外长

pidsh
核心循环就是代码,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 仓库里的一行依赖:

json · packages/llm/llm-pi-ai/package.json
"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-ai 是可复用的
那套多协议适配层(4 种 API 协议、跨 provider 上下文交接)能作为组件塞进别人的架构, 而不是只能整体使用。
Ⅱ说明 seam 设计经得起对照
两个毫不相关的实现能落在同一个接口上——这是「seam 不是装饰」的最硬证据。

反方向不成立:pi 不会用 dsh 的任何东西,它的设计前提就是「不引入别人的框架」。 这条不对称,恰好就是两种哲学最纯粹的体现。

怎么选:四个问题

如果你的答案是选
我要能被一个人完全理解,发版后行为不变pi
我要在 harness 上长出一个产品,多种外壳共享内核dsh
我的会话要活过多次版本升级,还要被别的系统消费dsh(代际设计)
我不能接受破坏性变更,也不想要插件市场pi
一句提醒:不要因为 dsh 的 star 数高就假设它更「正确」。 两者的代码量差 2.3–2.7 倍,差 33 倍的是文档与生态。 它们的差别不是成熟度,是目标函数不同。

llm-pi-ai/package.json · 依赖 pi-ai llm/src/index.ts:208 · LlmAdapter README.md:13

全本/第 10 章

10

动手:从跑起来到写第一个插件

这一章的所有命令都来自仓库文档,可以照抄。 顺序刻意设计成「先看树,再改树」——这样你写的第一个插件不会挂在错误的层上。

第一步:跑起来

sh · README.md:22-25
npx @deepseek-ai/dsh web

默认在 http://127.0.0.1:3080 起 Web UI 并打开浏览器;加 --no-open 只起服务不开浏览器。 从源码跑则是(README.md:33–39):

sh · 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)。

第二步:把树打印出来

在看任何源码之前,先看你这台机器实际启动了什么:

sh · docs/architecture.md:34
dsh --profile web --dump-config

它会打印组合出来的 profile 树然后退出。看三件事:

Ⅰ共多少行
这就是「一个 web 形态的 dsh」实际挂载的插件条目数量。 对着第 08 章的表,你能认出每一行大概负责什么。
Ⅱ每行的 id
patch 是按 id 定位并整块替换 config 的。 记住你想改的那行的 id,比记住包名有用。
Ⅲ层与层的边界
哪几行来自 dsh-base,哪几行来自 dsh-web-app。 你的 patch 会盖在它们之上。

配套的两个命令:--dump-default-config 打印去掉用户层与 --patch 之后的裸树 (用来判断「这是官方默认还是我改过的」);--dump-config-schema 只打印 JSON Schema,不挂载 (写 patch 时查字段用)。

第三步:写第一个插件

官方教程的路径最短,直接照它走(docs/user/develop/basic/index.md)。 先建一个草稿项目:

sh
mkdir -p scratch-plugin/src

插件就是一个导出 apply 的 TypeScript 模块:

typescript · scratch-plugin/src/my-plugin.ts
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。注意路径必须是绝对路径:

yaml · scratch-plugin/cordis.yml
- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
sh · 带上 overlay 启动
pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开 http://127.0.0.1:3080,启动时终端会打印 [hello-plugin] plugin loaded!。

第四步:理解「自动清理」与 inject

通过 ctx 注册的一切——事件监听、工具、定时器——在插件卸载时自动清理, 不需要你手写 removeListener。需要显式释放的资源(比如网络连接)用 ctx.effect() 交出 disposer:

typescript
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—— 框架会等这些服务就绪再加载你,所以加载顺序不需要你操心:

typescript
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」)
下一步去哪 官方有一份 extension cookbook,按「功能 → 能力」索引了分步指南: 加一个包、加一个工具、加一个 LLM 适配器、加一张设置卡片。 路径见第 11 章。

docs/user/develop/basic/index.md · 第一个插件 architecture.md:34 · --dump-config README.md:33 · 从源码运行

全本/第 11 章

11

延伸阅读:按「你想搞清楚什么」排序

dsh 有 4,763 篇 Markdown。按目录读会迷路,按问题读不会。 下面每一行都是「一个问题 → 一篇文档」,路径都相对仓库根目录。

六条最短路径

你想搞清楚读这篇大概要多久
整体架构与「新行为放哪」docs/architecture.md20 分钟,必读
Cordis 那套插件/作用域怎么运作docs/cordis-primer.md15 分钟,读代码前必读
一次 turn 的完整生命周期docs/agent-lifecycle.md15 分钟
工具调用到底经过哪些环节docs/tool-execution-pipeline.md10 分钟
某个事件谁发谁收docs/event-producer-consumer.md查表,随时
六个 seam 的全景图docs/capability-seams.md10 分钟

按角色读

A我只想用它
README.md → docs/user/guide/index.md → SAFETY.md(务必读)。 不需要碰架构文档。
B我要写插件
docs/user/develop/basic/index.md(第一个插件)→ docs/cordis-primer.md → docs/cookbook/extension-cookbook.md → 按需看 adding-a-tool.md / adding-an-llm-adapter.md。
C我要改内核
docs/architecture.md 全文 → docs/cordis-primer.md → docs/subsystems/core.md → packages/core/agent-loop/README.md(那里写了实现顺序)。
D我要做发行版/桌面端
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)

外部链接

读完这本手册之后

如果你只记三件事,记这三条:

  1. dsh 是一棵组合出来的树。没有特权核心,改行为 = 换提供者或挂监听,不是打补丁。
  2. 日志是唯一真相。模型可见的东西必须被记录;格式有代际,已发布文件不可变。
  3. 扩展之前先分诊。持久事实 → Session 事件;在飞的活儿 → Agent 事件;策略 → Capability 事件或 seam。

剩下的都是细节,而细节都在 docs/architecture.md 里,且写得比大多数项目都清楚。

docs/cookbook/extension-cookbook.md docs/event-producer-consumer.md docs/capability-seams.md