DeepSeek Harness 包级规范拆解

DeepSeek 开源的智能体框架 DeepSeek Harness（下称 dsh）主张"一切皆插件"，底层由 Cordis 插件框架驱动，目前仍处于开发者预览阶段。在使用文档之外，仓库还为开发参与者准备了一份包级工程规范：一份放在 packages 目录下的智能体约定文件，用十四条通用规则加六条命名规则，约束在这个多包仓库里新增或修改任何包时的行为。这份文件最鲜明的特点是，它的第一读者是 AI 编码智能体，其次才是人类贡献者。本文逐条拆解这些规则的动机与落地方式。

一、导出形态先定死：导出即契约

第一条纪律关于插件的导出形态。dsh 里有两类插件：服务包默认导出自己的服务类；函数插件则只用具名导出，必须提供 name、inject、Config、apply 四件套，不允许出现默认导出。规范明确警告，混用两种形态会让加载器直接丢弃函数插件的命名空间。这条规则后面挂着一份事故复盘，标题直译过来就是"默认导出弄丢了 inject"。

与之配套的第二条规则是可选服务的读取方式：想拿一个可能不存在的服务，用 ctx.get(name) 这种严格读法，它直通全局服务表；ctx.名字 这种属性代理只保留给已声明的注入。理由写在规则里：属性代理的行为与拓扑相关，用错位置排查起来非常隐蔽，而严格读取永远指向全局服务表。

二、真实组装与注册纪律

第三条规则管测试形态：凡是产品可见的插件，必须做真实组装测试。手工拼装的插件测试套不算数，要在测试里通过加载器真正启动一份测试专用的 cordis.yml 配置，只允许 mock 外部服务或非确定性输入，断言的必须是模型可见、持久化或用户可见的输出。可选项也不许悄悄塞进出厂默认配置。

注册侧有两条硬约束。其一，任何注册进注册表的贡献都要能证明自己可以被正确释放：用热更新安全测试验证，释放之后必须观察到条目真的消失。其二，每个包都要拥有自己的不变量检查，注册时登记清单名；如果某个包的检查器是空的，必须给出包级理由说明"为什么为空"，生成的配套文件和不解释的空检查都会被机械校验直接拦下。

三、抽象的克制：有主、有据、有消费者

这套规范里最有味道的是一组反过度设计条款。抽象必须有主：每个抽象、状态机、配置项、防御性拷贝和兼容路径，都要挂在一个当前存在的契约或生产消费者上，行为留在拥有它的插件或服务里。公共选择要有证据：可配置本身不构成理由，一个没有依据的默认值、公开操作集或格式，要么拿出当前消费者作证，要么显式指定取值，要么先不做这个选择。

服务定义要为所有当前消费者设计：工具模式、加载器、界面、传输层和特定提供方的差异，留在消费者一侧，不能让某一个消费者绑架整个服务契约。规范还写明了反向坏味道：一个只有一个内部调用者的公开服务方法，应该改成私有能力闭包传进去。发起方私有的调用链则要先派生再捕获：在编排入口恢复 Agent、派生会话，让操作内的辅助函数闭包持有会话；同时在生命周期、会话日志、服务、权限、工作进程、持久化和网络这些边界上，把 Agent 与会话当显式参数传，别为了少写一个参数，把叶子函数的入参从会话放宽成整个上下文。

四、面向模型的契约与状态的提交点

第四组规则围绕模型与状态展开。面向模型的契约，包括提示词、工具模式、结果和诊断信息，只能包含任务相关概念，不能混入界面、传输或实现词汇；模型可见的稳定文本要逐字固定，动态行为用快照或端到端覆盖钉住。

决定的执行要放在做决定的那个操作里：靠省略字段、过滤提示词、包一层门面来执行决定都不算数，因为直接调用方或替代调用方总能绕过去，拒绝必须在执行器里测到。一次异步操作只配一个生命周期控制器或事务：就绪、取消、释放、预留这些状态要么交给独立的归属者，要么折进同一个控制器，同时保留回滚、回调收口与静默能力。状态的发布只能发生在提交点：操作成功后才发通知、才更新派生状态，缓存、提示词、界面回显、重放与查询视图都从同一个权威来源派生。

结果边界还要算总账：字节、条目、时间这些限制，应该加在"完整结果"已知的地方，把包装和元数据都算进去；测试要覆盖极小值、恰好超限的单个大块以及多字节边界这些刁钻情形。

五、命名规则与文档纪律

规范的后半段是六条命名与布局规则。每个包的 tsconfig 继承基础配置（客户端包用专门的客户端基础配置），源码根目录固定为 src，产物进 lib/types，引用每个工作区依赖外加运行时诊断包，并且只登记进一个聚合工程；只有生成契约才允许拆分条目。src/types.ts 只放类型，不放运行时代码；测试放在包级 tests 目录，而不是 src 下的测试目录。

文档与代码同步被当成硬性要求：改了行为，README 和 JSDoc 必须在同一个提交里更新，配置键、默认值、错误码、网络字段都在此列，有专门的校验脚本把关。README 还要用统一的格式，写清楚包对模型、token 与 KV 缓存的影响；已知限制与延期工作必须落在专门的小节里，一个限制都没有的包，要进一份有理由的豁免清单。

六、可以抄走的三件事

对想管好自己仓库的人，这套规范至少有三点可借鉴。第一，把事故变成条款：这些规则背后几乎都有一次真实踩坑，规则写清动机，才不会被当成形式主义绕开。第二，把 AI 智能体当成第一读者：与其事后逐个纠正生成代码的风格，不如把约定写成机器可校验的清单，让智能体在提交前自查。第三，克制要可审计：要不要抽象、要不要加配置项，都要求拿当前消费者当证据，这套标准对任何规模的项目都适用。

dsh 的这份包级约定文件本身，就是"用工程规范驯服智能体"的一个现成范本：规矩先写下来，人和机器才守得住。