DeepSeek Harness 架构解剖

同一套代码要跑出好几种形态：网页版、命令行一次性任务、给编辑器用的后台服务、给别的程序调用的 SDK。传统做法是加一堆 if 分支或者维护几个入口文件，时间一长谁也说不清某个形态到底装了什么。

一个完整的 AI 编程助手，就是一份 165 行的 YAML 清单——列出要装哪些插件、每个插件怎么配。启动时系统先把根配置清空成一个空列表，再按顺序叠加：

基础包 → 形态包（网页/命令行） → 用户的个人配置 → 机器级配置 → 命令行临时覆盖

每一层都是「补丁」：按 id 找到某一行，替换它的配置，或者插入新行。没有任何一层是「那个主配置文件」，它们地位平等。

插件系统的经典麻烦是启动顺序：A 要用 B，B 要用 C，谁先初始化？手工排序的清单一旦有人插队就崩。

每个插件只声明「我需要哪几个服务」。框架给每个插件算一个「就绪状态」——依赖全都在位就激活，任何一个消失就自动卸载。加载顺序不是被编排出来的，是从依赖声明里涌现出来的。

更进一步：这个就绪状态记的不只是「依赖在不在」，还包括「依赖是由哪个实例提供的」。所以把某个服务换成另一个实现时，即使服务名字没变，依赖它的插件也会自动重启一次。

插件卸载时最容易出事：注册的事件监听器没摘、开的文件没关、起的定时器没停。而且卸载可能发生在初始化还没跑完的时候。

框架规定：任何会改变世界的动作都必须通过统一的注册接口，它返回一张「退票」。卸载一个插件 = 把它的所有退票反序执行一遍。

嵌套的情况也处理了：在一个注册动作内部再注册，子退票会自动从插件的总清单里「转挂」到父退票名下——于是嵌套的清理天然按嵌套结构回收。异步初始化每一步之前都检查状态是否已变，所以卸载能中断进行中的初始化。

同一个工具注册表被读了两次，用途不同：第②步读它是为了把工具的说明书写进提示词（告诉模型有哪些工具可用），第⑥步读它是为了真的执行。

这不是冗余，而是一条重要的约束：两次读的必须是同一份清单。项目里所有和「可见性」有关的问题——提示词里列了什么、能执行什么、生成的 SDK 里有什么——都走同一个解析函数。否则就会出现「告诉模型有这个工具，实际调用时说不存在」这种让模型彻底放弃自我修正的状况。

右列那些插件不是「被通知一下」。以第③步为例：主循环把「我打算发给模型的这几条消息」交出去，每个监听的插件可以选择传给下一个、改写后传下去、或者直接否决这一步。压缩策略就是在这里发现上下文要满了，先去做一轮摘要。

这个模式在 Web 框架里叫中间件（洋葱模型），项目沿用了所用框架自带的名字 waterfall——不是它发明的概念。

注册不一定是全局的。每个活着的 agent 都有自己的一份注册作用域，插件可以只往某一个 agent 的作用域里注册。于是同名的东西会「就近覆盖」——某个会话的 bash 工具可以是一个受限版本，而其他会话看到的还是原来的。

这就是「一个会话换一套能力组合」的实现方式：一份预设配置只挂载一次，各个会话通过作用域的父子关系加入它，而不是每个会话各挂一份。

如果对话历史存在一个数组里，那么「重放一个会话」「fork 一个会话」「从崩溃恢复」「给 UI 渲染」就各自需要一套逻辑，而它们迟早会不一致——模型看到的和你在界面上看到的对不上，这类 bug 极难查。

只有一本流水账。要发请求时，把账从头折叠一遍算出消息列表。UI、重放、fork、持久化全都基于同一本账的不同折叠方式。

规矩写成一句话：「模型可见 ⟺ 已记录」。任何会进入模型请求的东西——包括工作区说明、时间信息、系统提示词本身——都必须先成为账上的一条记录。想加一种新的模型可见输入？先定义一种新的日志事件。

对话变长后必须压缩，否则塞不进模型的上下文窗口。但常见做法是把旧消息替换成摘要——于是用户已经看到的对话在界面上凭空消失了。

不撕账页。压缩时追加一条特殊记录：「以下第 12 到第 47 条，以这份摘要为准」。

然后同一本账有两种读法：模型面会尊重这条遮蔽记录，读到摘要；人类面只读「原本就是追加进来的」记录，完全无视遮蔽。

软件升级后，旧版本读到新版本写的日志怎么办？「跳过不认识的」是最常见的做法，也是最危险的——它会静默地恢复出一个被掏空的会话，而使用者毫无察觉。

默认相反：读到不认识的记录类型就拒绝重建整个会话，除非那条记录被作者显式标记为「可忽略」。

工具执行前要过一串安全检查（权限、沙箱、用户策略）。经典写法是一条「中间件链」，每个环节可以放行、拒绝，或者交给下一个。

但中间件链有个隐蔽的坑：顺序会影响结论。一个插件如果把自己插到队伍最前面，就能抢在别人的「拒绝」之前放行。这类 bug 不报错、无声无息，而且往往是安全相关的。

项目把安全检查拆成两种东西并存：

• 中间件链——保留，用来做需要「包裹」的事情：超时、重试、埋点。
• 守卫——一种新东西。它的类型只允许返回「拒绝理由」或者「我没意见」，压根没有「放行」这个选项。

于是守卫的组合就是一个无序集合上的「有一个说不行就是不行」。无论注册顺序如何、无论谁插队，结论完全相同。

「超时时间没传就用 60 秒」这种默认值，通常散落在实现内部（timeout ?? 60000）。结果没人说得清一次调用真正用了什么参数，调试时只能翻源码。

把「填默认值」提升成一个公开的、命名的转换步骤：从「请求」（字段大多可选）转成「规格」（字段全部必填）。执行函数的类型只接受规格，所以一个没填完的请求根本传不进去。

填默认值的那一步同时负责钳制上限——比如用户要求 10 小时超时，会被静默压到部署允许的最大值，而不是抛错或者放行。

后端要往浏览器转发一部分内部事件。哪些能转、哪些不能转，通常是一个数组加一句注释——然后转发代码和前端订阅代码各维护一份，慢慢就漂了。

白名单是一个常量数组，被类型系统约束（数组里的每一项必须是真实存在的事件、且形状符合可转发的要求）。运行时的转发循环和前端合法的订阅键集都从这一个数组派生。

这个项目吃过一次真实的亏：某个插件文件多写了一行「默认导出」。加载器的规则是「有默认导出就只取默认导出」，于是这个插件的依赖声明被连带丢弃，插件在一个「什么服务都没有」的环境里启动，服务一连上真实编辑器就崩。

当时这个包有 178 个绿色单元测试和 100% 行覆盖率。为什么没测出来？因为所有测试都是手工搭建插件对象的，而「取默认导出」那段逻辑只有真实加载器才会走。

事故之后加了两道防线。其一：一个检查脚本用 TypeScript 的语法分析器逐个解析每个包，强制它们满足一串结构要求——包括「不得有默认导出」。219 个包全部合规。

其二写进了测试规范：每个对外可见的插件必须有一个走「真实加载路径」的测试。手搭对象的测试不算数。

不同操作系统的进程隔离能力差别很大。假定「我调用了沙箱所以现在是安全的」会在某些平台上变成危险的错觉。

沙箱接口只有一个方法：把你正要执行的那串命令交出去，换回一串替换命令，外加三项事实：

• 约束力等级：完全 还是 部分。「部分」是真实存在的状态——Windows 上因为硬链接可以让一个文件从多个路径访问，被静态判定为部分；Linux 的内核级方案则按实际协商到的内核版本自行探测。
• 这个后端自己的「拒绝话术」。不同沙箱拒绝时输出的错误文本不一样，所以调用方只匹配本次实际使用的那个后端返回的话术——取所有后端的并集会声称某些后端根本产生不了的拒绝。
• 怎么区分「沙箱本身坏了」和「命令被拒了」。

包一个复杂协议（比如语言服务器协议）时，最省事的做法是「提供几个常用操作，再加一个通用的原始调用接口以防万一」。

语言服务接缝只暴露四个操作：跳转到定义、查找引用、跳转到实现、悬停信息。结果类型也是封闭的两种。没有原始协议调用，没有进程控制，没有文档管理。想加第五个操作，得同时改接口、所有实现和使用方，编译器会盯着你改完。

模型一次可能要求调用五个工具。串行跑太慢，并行跑又会打乱结果顺序——而模型是按它列出的顺序理解这些结果的。

派发可以重叠，但提交严格按序：调度器只沿着「连续完成」的位置往前推进。第三个先跑完也得等前两个。

两个额外的讲究：每次准备启动下一个调用前重新判定它能否并发——所以运行中如果工具注册表变了，能对尚未启动的调用形成一道屏障；被中断时给没来得及执行的调用补写一条合成的错误结果，保证这段日志重放时仍然完整（每个调用都有对应的结果）。

模型每调一个工具就要来回一轮：它输出调用请求 → 系统执行 → 结果塞回上下文 → 再问模型。做十件事就是十轮，token 消耗和延迟都很可观。

换一种呈现：给模型的工具列表里只有一个工具叫「运行代码」，同时在系统提示词里附上所有工具的 TypeScript（或 Python）接口声明。模型写一段程序，一次跑完全部十件事。

关键在于程序里的每个工具调用仍然回流到同一条安全管线——权限、沙箱、审批一个不少，且每次子调用都记进日志。但只有模型自己策展过的最终输出进入对话历史。

一次执行可能因为三种原因需要中止：用户按了停止、这个插件被卸载、整个系统在关闭。分开处理会漏掉组合情况，尤其是「初始化跑到一半时卸载」。

三个来源融进一个取消信号，而且在任何资源被创建之前就注册好，配一套「反序拆除」流程（且保证并发调用只执行一次）。

一个命令可以同时「超时了」并且「退出码是 0」——因为它捕获了终止信号然后正常退出。如果把「超时」这个标志嵌套在「失败」分支里报告，调用方会把一次被腰斩的运行读成干净的成功。

「是否超时」「收到什么信号」「退出码」各占一个独立字段，谁也不嵌套在谁的分支里。

从代码自动生成的文档（API 目录、依赖图、配置清单）总会过期。于是又要写一个检查器来验证它们是否最新——然后检查器自己和生成器慢慢漂移，出现「检查通过但文件是错的」。

不写第二个程序。检查 = 用同一个生成器加个参数，在内存里重新生成一遍，和仓库里的文件逐字节比对。

「所有公开函数都要写文档注释」这类检查，需要遍历代码里的各种导出形式。语言一升级冒出个新语法，检查器不认识，走进 default 分支——静默放行。从这一刻起它退化成抽样，而没人会发现。

遇到不认识的构造就报错，并在错误里说明「我不认识这个，请扩展我」。

测试 AI agent 很贵：每次都真调模型，慢且不确定。于是要「录制回放」，而这通常意味着发明一套录制格式。

不发明格式。会话日志本身就是回放素材。录制 = 真跑一次，把日志文件留下。

配三条经验：无法从日志推导时要大声报错并指明补救方式，不能悄悄降级；测试结束时断言「录制内容被完整消费」（少跑几次模型调用的测试仍然会通过所有输出比对，只是记录变短了）；系统提示词这类又大又常变的内容只在一个场景里逐字比对，其他场景重建后比对——否则改一次提示词会搅动上百个期望文件，评审就变成橡皮图章了。

「为什么当初这么设计」是最容易蒸发的知识。设计文档要么没人写，要么写完就过期变成误导。

每个非琐碎改动必须在同一个 PR 里附一篇决策记录。分类编码在文件路径里（状态/类别/日期-标题），两个维度都在代码里闭合——想加一个类别，得改代码。

三条硬规矩：「考虑过的替代方案」是必填章节；明令禁止建中央索引文件（那种文件必然过期）；已完成的历史记录进入密码学封存的归档区，所有文档检查跳过它，并声明「归档记录永远不是当前行为的依据」。