pi × DeepSeek Harness 读懂 dsh 总览 逐项深挖 读书指南 故障与恢复 dsh 学习手册 官方文档

对比/读懂 dsh

01

心智模型:一棵在 boot 时长出来的插件树

dsh 的架构可以压缩成一句话:一个运行中的 dsh 是一棵插件树,由有序的层在启动时组合而成。 这句话原文就在架构文档第二段(docs/architecture.md:15)。

"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

三层组合:profile → bundle → patch

这是 dsh 与绝大多数 harness 最不一样的地方:产品形态本身是配置出来的,不是编译进去的。

概念是什么证据
profile 一个具名组合,存在 Harness home 里。它列出要叠加的 bundle、自己安装的树外插件,以及用户自己的 cordis.patch.yml。出厂模板有 5 个:web、headless、sdk、sdk-minimal、acp。 docs/architecture.md:17
bundle Cordis 配置行 + 它挂载的代码的分发格式;插进去的东西仍然能被上层的 patch 改。 docs/architecture.md:19
patch 按行 id 定位,整块替换它的 config,或插入新行。层序:profile 的 bundle → cordis.patch.yml → home patch → --patch。 docs/architecture.md:25
# 看你这台机器实际会启动什么树
dsh --profile web --dump-config

--dump-config 打印出来的每一行,都可以被你自己的 patch 替换掉。 这就是「可替换性」的具体含义:不是 API 可替换,是启动配置可替换。 连 HMR 都由 YAML 控制——dsh-base 打开只改配置的 HMR,headless / SDK / ACP 关掉它。

插件长什么样

没有框架特有的基类要继承。一个 Cordis 插件的最小形态就是两个导出:

// packages/mcp/mcp-client/src/index.ts:31-34
export const name = 'mcp-client'
export const inject = ['tools']   // 声明依赖:我要用工具注册表

MCP 客户端整个的「接线」就是这一行 inject——它把外部工具服务器产出的工具, 注入到 ctx.tools 这个 seam 上。没有专门的 MCP 集成代码路径, 它和内置工具走同一道执行管线。

02

turn 契约:日志先行

dsh 把「一次交互」拆成两个词,定义写得很死: step = 一次模型请求 + 它调用的工具;turn = 0 个或多个 step (docs/architecture.md:81)。

三个事件域,别混用

SSession 事件
持久事实,追加进日志并经 session/event 广播。需要活过重载的事实用它。
AAgent 事件 agent/*
携带一个活着的 Agent:inbox、step、status、request、validation、continuation。观察或拦截在途工作用它。
CCapability 事件 fs/*·tools/*·telemetry/*
给 seam 挂策略与适配器,不需要 import 循环。
Wwaterfall vs serial
agent/pre-step、agent/request、llm/stream、tools/* 是 waterfall,监听者必须调 next() 才放行;agent/turn-stopping 是串行且没有 next()。

一条硬规则

"Model-visible means logged. Every model request must be reconstructable from the log. New model-visible inputs require session events."
对模型可见,就必须写进日志。每个模型请求都必须能从日志重建。任何新的、模型能看到的输入,都必须有对应的 session 事件。
— docs/architecture.md:122(Session log)

这条规则解释了很多实现细节:assistant/message 里内嵌了产生它的那段 紧凑带时序的流;assistant/attempt 保留失败/重试/取消的尝试但不进模型历史; 进程如果在落定前硬死,不会留下半条 attempt——这是刻意换来的可重建性。

格式还要自己迁移

pi 的会话就是一个 JSONL,坏了就坏在你手里。dsh 把会话格式做成了代际: session.jsonl[.zstd] 是 v0,v1 之后是 session.vN.jsonl[.zstd]; 相邻两代之间恰好一个迁移包负责 vN → vN+1; 已提交的代际路径永不重命名、替换或删除,写入时先编码、校验,再把新代际发到源文件旁边。

为什么值得单独提:这是「会话是可分析的资产」和「会话是运行时缓存」两种思路的分水岭。 dsh 选了前者,并为此付出了迁移链、代际选择、互斥发布这些复杂度。
03

seam:一个能力要三角色齐全才算数

文档里对 seam 的定义很严格:Service Definition(声明接口)+ Service Provider(实现)+ Consumer(使用方,通常是模型可见的工具)。一个包可以兼任多个角色, 但只占一个角色就不叫 seam——要加一个能力,得把三个角色都设计出来。

seam定义 / 注册点换掉它会怎样
ctx.llmabstract class LlmAdapter(packages/llm/llm/src/index.ts:208),registerAdapter() 在 :401换模型厂商,不动循环
ctx.toolsToolsService(packages/core/tools/src/index.ts:99)换工具集,schema 自动进入 prompt 组装
ctx.sessionsSession(packages/core/session/src/index.ts:525)与 SessionStore(:1064)换存储后端(SessionPersistence:create/open/stat/list/export)
ctx.fs / ctx.subprocessabstract class FileSystem(packages/fs/fs/src/index.ts:87)、abstract class SubprocessRuntime(packages/subprocess/subprocess/src/index.ts:117)整个执行世界搬家:Bash、PTY、LSP 跟着走,provider 不用分叉
ctx.sandboxSandboxPolicyService(packages/sandbox/sandbox-policy/src/index.ts:134)改约束策略,消费方在 spawn 前包住 argv
最容易忽略的一条:fs 与 subprocess 共用同一个执行世界。 所以「把文件系统指向远端沙箱」不是一半的迁移——Bash、PTY、LSP 会一起搬走。 这是 seam 设计得好的证据:换一个 provider 能改变整个产品。
04

「新行为该放哪」是一张表

架构文档最后有一张 20 行的表:左边是目标,右边是机制。 这在 harness 里很少见——大多数项目让你自己猜该改哪儿。它本质上是一份「扩展点清单」。 (docs/architecture.md:142 起)

目标机制
加一个模型厂商在 ctx.llm 上注册适配器
加一个模型可见的能力注册到 ctx.tools,schema 自动加入 prompt 组装(:149)
给某个会话换一套能力组合一个 agent preset;其中的服务行需要 isolate realm
加 shell 执行注册 ctx.shell 后端;本地实现走 ctx.subprocess spawn
加持久化终端注册 ctx.terminals 后端 + dsh-tool-terminal
加一个人工命令注册到 ctx.commands,不产生模型 turn
约束被 spawn 的进程用 ctx.sandbox 后端;消费方在 spawn 前包装 argv(:157)
拦截请求 / 工具 / turn用对应的 agent/* 或 tools/* 事件;agent/turn-stopping 能停掉整个 turn
给模型加上下文调 agent.inject(),它落在下一次被准入的请求里
在 turn 边界 forkctx.agents.create({ sessionId, seed, inheritedEventCount, … })(:165)
05

两张可校验的图

同样钉死 revision 22ddee3,每个组件都绑定 path:line, 并且通过了 schema 校验、布局校验、浏览器渲染校验与视觉包含校验四道门。

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

画布 1510px,栏位 898px:1× 最小字号 3.7px,2× 7.9px,3× 12.1px(实测)。 注意左侧 profile · bundle · patch 在 region 之外——它是「树的输入」,不在树里。

dsh 一次 turn 的调用链 · 8 participants / 14 messages / 4 segments 新窗口 ↗

画布 1080px,时序图比架构图好读得多:1× 5.2px、2× 11.0px、3× 16.9px。 看点:append turn/start 发生在模型请求之前;工具调用没有旁路,必须过三道 waterfall。

06

代价:它为什么这么重

dsh 不是「顺便变复杂」的。每一项复杂度都能对上一个能力,而这些能力都有明确的使用者。 问题只在于:你是不是那个使用者。

复杂度换来了什么谁在付账
插件树 + 生命周期 + 作用域注册核心每一层都能从配置替换想换循环、换存储、换执行世界的平台方
profile / bundle / patch 三层产品形态靠配置组合,出厂 5 种外壳要分发插件、要打包桌面端/发行版的人
会话格式代际 + 迁移链格式可以演进而不丢历史会话把会话当长期资产、要后处理的人
三个事件域 + waterfall/serial 区分策略能挂在正确的位置上,而不是塞进工具内部要写企业级策略/审计的人
Web 前端 17.4 万行(不含测试)+ Electron + Python SDK同一个核心支撑四种外壳要 GUI、要桌面端、要非 Node 调用方的人
反过来说:如果你想做的就是「一个能读完全部代码的 agent」,上面每一行都是净负担—— 这正是 pi 把它们全部砍掉的理由。两个项目的分歧不在工程能力,在对使用者的假设。

还有一个现实成本:dsh 明确处于 developer preview,README 用大写写着 «THERE WILL BE COMPATIBILITY-BREAKING CHANGES»,并要求先读 SAFETY.md。 对平台方这是可接受的;对手里有一套稳定工作流的人,这是硬伤。

本章学习记录

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