对比/读懂 dsh
心智模型:一棵在 boot 时长出来的插件树
dsh 的架构可以压缩成一句话:一个运行中的 dsh 是一棵插件树,由有序的层在启动时组合而成。
这句话原文就在架构文档第二段(docs/architecture.md:15)。
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 集成代码路径,
它和内置工具走同一道执行管线。
turn 契约:日志先行
dsh 把「一次交互」拆成两个词,定义写得很死:
step = 一次模型请求 + 它调用的工具;turn = 0 个或多个 step
(docs/architecture.md:81)。
三个事件域,别混用
session/event 广播。需要活过重载的事实用它。agent/*Agent:inbox、step、status、request、validation、continuation。观察或拦截在途工作用它。fs/*·tools/*·telemetry/*agent/pre-step、agent/request、llm/stream、tools/* 是 waterfall,监听者必须调 next() 才放行;agent/turn-stopping 是串行且没有 next()。一条硬规则
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;
已提交的代际路径永不重命名、替换或删除,写入时先编码、校验,再把新代际发到源文件旁边。
seam:一个能力要三角色齐全才算数
文档里对 seam 的定义很严格:Service Definition(声明接口)+ Service Provider(实现)+ Consumer(使用方,通常是模型可见的工具)。一个包可以兼任多个角色, 但只占一个角色就不叫 seam——要加一个能力,得把三个角色都设计出来。
| seam | 定义 / 注册点 | 换掉它会怎样 |
|---|---|---|
ctx.llm | abstract class LlmAdapter(packages/llm/llm/src/index.ts:208),registerAdapter() 在 :401 | 换模型厂商,不动循环 |
ctx.tools | ToolsService(packages/core/tools/src/index.ts:99) | 换工具集,schema 自动进入 prompt 组装 |
ctx.sessions | Session(packages/core/session/src/index.ts:525)与 SessionStore(:1064) | 换存储后端(SessionPersistence:create/open/stat/list/export) |
ctx.fs / ctx.subprocess | abstract class FileSystem(packages/fs/fs/src/index.ts:87)、abstract class SubprocessRuntime(packages/subprocess/subprocess/src/index.ts:117) | 整个执行世界搬家:Bash、PTY、LSP 跟着走,provider 不用分叉 |
ctx.sandbox | SandboxPolicyService(packages/sandbox/sandbox-policy/src/index.ts:134) | 改约束策略,消费方在 spawn 前包住 argv |
「新行为该放哪」是一张表
架构文档最后有一张 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 边界 fork | ctx.agents.create({ sessionId, seed, inheritedEventCount, … })(:165) |
两张可校验的图
同样钉死 revision 22ddee3,每个组件都绑定 path:line,
并且通过了 schema 校验、布局校验、浏览器渲染校验与视觉包含校验四道门。
画布 1510px,栏位 898px:1× 最小字号 3.7px,2× 7.9px,3× 12.1px(实测)。
注意左侧 profile · bundle · patch 在 region 之外——它是「树的输入」,不在树里。
画布 1080px,时序图比架构图好读得多:1× 5.2px、2× 11.0px、3× 16.9px。
看点:append turn/start 发生在模型请求之前;工具调用没有旁路,必须过三道 waterfall。
代价:它为什么这么重
dsh 不是「顺便变复杂」的。每一项复杂度都能对上一个能力,而这些能力都有明确的使用者。 问题只在于:你是不是那个使用者。
| 复杂度 | 换来了什么 | 谁在付账 |
|---|---|---|
| 插件树 + 生命周期 + 作用域注册 | 核心每一层都能从配置替换 | 想换循环、换存储、换执行世界的平台方 |
| profile / bundle / patch 三层 | 产品形态靠配置组合,出厂 5 种外壳 | 要分发插件、要打包桌面端/发行版的人 |
| 会话格式代际 + 迁移链 | 格式可以演进而不丢历史会话 | 把会话当长期资产、要后处理的人 |
| 三个事件域 + waterfall/serial 区分 | 策略能挂在正确的位置上,而不是塞进工具内部 | 要写企业级策略/审计的人 |
| Web 前端 17.4 万行(不含测试)+ Electron + Python SDK | 同一个核心支撑四种外壳 | 要 GUI、要桌面端、要非 Node 调用方的人 |
还有一个现实成本:dsh 明确处于 developer preview,README 用大写写着
«THERE WILL BE COMPATIBILITY-BREAKING CHANGES»,并要求先读 SAFETY.md。
对平台方这是可接受的;对手里有一套稳定工作流的人,这是硬伤。