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

手册/第 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 · 五种派发模式

本章学习记录

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