1. 从一次插件加载失败说起：Cordis 架构到底解决了什么问题
我第一次接触 DeepSeek Harness 的插件体系，是因为一个很具体的需求：团队内部有一个自研的代码审查流程，想在 Harness 每次生成补丁之后自动跑一遍静态检查，再把结果回注到对话上下文里。最直觉的做法是改主程序源码，但那样每次上游更新都要重新合并，维护成本极高。于是我转向了它的插件机制，也就顺理成章地撞上了 Cordis 这套架构。
Cordis 是 DeepSeek Harness 用来组织扩展能力的底层框架，核心目标只有一个：让功能模块以插件的形式被动态加载、卸载和组合，而不需要侵入宿主程序。它用 TypeScript 写成，围绕“服务（Service）—插件（Plugin）—上下文（Context）”三个概念展开。你可以把它理解成一个微型的依赖注入容器加上生命周期管理器：每个插件声明自己需要什么、提供什么，Cordis 负责在合适的时机把它们串起来。
这套东西适合谁？如果你只是把 Harness 当黑盒用，那完全不需要了解它。但只要你动了“想加个自定义工具”“想拦截某类请求”“想把内部系统接进来”的念头，Cordis 就是绕不开的一层。它解决的核心问题是扩展性与稳定性的平衡：插件可以热插拔，单个插件崩溃不会拖垮整个 Agent 会话，插件之间的依赖关系由框架统一调度，而不是靠开发者手动 new 来 new 去。
我踩过的第一个坑，就是没搞清楚“插件”和“服务”的区别，把一个应该注册成 Service 的能力写成了普通函数导出，结果别的插件根本拿不到它。后面会详细讲这个。先把整体设计思路拆开。
2. Cordis 插件架构的整体设计与选型考量
2.1 为什么是“上下文 + 服务”而不是传统事件总线
很多 Agent 框架的扩展机制走的是事件总线路线：宿主抛出事件，插件监听并处理。这种方式上手快，但有两个硬伤。第一，事件是匿名的，插件之间想互相调用能力只能再发一个事件，链路一长就变成“事件地狱”，调试时根本追不清谁触发了谁。第二，事件监听器没有明确的生命周期，插件卸载时如果忘了取消监听，就会留下悬挂引用，时间一长内存泄漏。
Cordis 选择了另一条路：以Context为中心，能力通过ctx.xxx暴露。插件在加载时拿到一个 Context 实例，可以往上面挂服务，也可以从上面取服务。这本质上是一个带作用域的依赖注入。好处很直接：依赖关系是显式的，谁用了谁一眼能看出来；作用域决定了服务的可见范围，子上下文拿不到父上下文没暴露的东西；卸载插件时，框架知道该清理哪些注册。
提示：如果你之前用过 Angular 的 DI 或者 NestJS 的 Provider，Cordis 的心智模型和它们非常接近，只是更轻量，没有装饰器和模块系统那套重装备。
2.2 TypeScript 在这套架构里扮演的角色
Cordis 用 TypeScript 不是图个类型好看，而是因为插件架构天然需要契约先行。宿主和插件之间、插件和插件之间，靠的就是类型声明来约定接口。没有类型，你根本不知道ctx.foo上到底有哪些方法，只能翻源码或者猜。
这里有个关键机制叫声明合并（Declaration Merging）。Cordis 的 Context 类型是一个接口，插件可以通过declare module把新服务的方法合并进去。这样你在写ctx.myService.doThing()的时候，编辑器能给出完整补全，编译期就能发现拼写错误。这也是为什么热词里会出现“typescript types 文件夹的声明文件如何使用”“typescript 类型声明文件 .d.ts 怎样编写”——写 Cordis 插件，绕不开给 Context 扩展类型。
我个人的经验是：先把 .d.ts 写对，再写实现。很多人反过来，先写一坨 JS 逻辑，最后补类型，结果补到一半发现接口设计有问题，返工成本极高。契约先行的思路在插件开发里尤其重要，因为你的插件可能被别人的插件依赖，接口一旦发布就很难改。
2.3 插件生命周期：加载、就绪、卸载三段式
Cordis 的插件生命周期可以粗略分成三段。加载阶段，框架调用插件的入口函数，传入 Context，插件在这里注册服务和监听。就绪阶段，所有依赖都满足后，插件可以开始对外提供服务。卸载阶段，框架触发清理，插件需要释放自己占用的资源。
这个三段式设计的关键在于依赖解析的时机。如果插件 A 依赖插件 B 提供的服务，Cordis 会保证 B 先就绪，A 才会进入就绪状态。这就避免了“A 启动时 B 还没准备好”的经典竞态问题。相比之下，事件总线方案里你只能靠 setTimeout 或者轮询去等，非常不优雅。
2.4 与主流 Agent 框架扩展机制的对比
| 维度 | Cordis（Harness） | 事件总线型框架 | 重量级 DI 框架 |
|---|---|---|---|
| 依赖声明 | 显式，通过 Context | 隐式，靠事件约定 | 显式，装饰器/配置 |
| 生命周期 | 框架统一管理 | 开发者手动管理 | 框架统一管理 |
| 类型支持 | 声明合并，强类型 | 弱，事件 payload 常为 any | 强，但配置繁琐 |
| 热插拔 | 原生支持 | 需自行实现 | 部分支持 |
| 上手成本 | 中等 | 低 | 高 |
这张表不是要证明谁绝对更好，而是说明选型逻辑。Harness 的场景是“一个长期运行的 Agent 进程，需要不断接入新能力”，这种场景下显式依赖和生命周期管理带来的收益，远大于上手成本。如果你只是写个一次性脚本，那确实没必要上 Cordis。
3. 核心概念拆解与实操要点
3.1 Context：一切能力的入口
Context 是 Cordis 里最重要的对象。你可以把它想象成插件的“工作台”：上面摆着各种工具（服务），你从上面取工具用，也可以把自己的工具放上去给别人用。每个插件拿到的 Context 可能不同，因为框架会根据作用域做隔离。
Context 上最常用的几个能力：ctx.plugin()用来加载子插件，ctx.on()用来监听事件，ctx.effect()用来注册需要在卸载时清理的副作用。这里要特别说ctx.effect()，它是防止内存泄漏的关键。任何你注册的定时器、监听器、外部连接，都应该包在 effect 里，这样插件卸载时框架会自动帮你清理。
我见过太多插件作者直接setInterval而不清理，结果插件热重载几次之后，同一个逻辑跑了五遍。用ctx.effect()包一层，这个问题就不存在了。
3.2 Service：可被依赖的能力单元
Service 是插件对外暴露能力的标准方式。定义一个 Service 通常要继承框架提供的基类，然后通过ctx.provide()注册。注册之后，其他插件就能通过ctx.xxx拿到它。
这里有个容易混淆的点：Service 和普通导出的区别。普通导出是一个模块级的函数或对象，谁 import 谁就能用，但它没有生命周期，也不受作用域控制。Service 则挂在 Context 上，随插件的加载卸载而存在或消失。如果你的能力需要被其他插件依赖，或者需要在卸载时清理状态，那就必须做成 Service。
注意：Service 的命名要加前缀避免冲突。我建议用
ctx.myPluginName.xxx这种形式，而不是直接ctx.xxx，否则多个插件都想注册ctx.logger的时候就会打架。
3.3 Plugin：功能的最小封装单位
Plugin 就是一个函数或者一个带apply方法的对象，接收 Context 作为参数。框架加载插件时调用它，插件在里面完成服务注册和事件监听。
写 Plugin 有几个实操要点。第一，入口函数应该是幂等的，重复加载不应该产生副作用叠加。第二，不要在入口函数里做耗时操作，比如同步读大文件，这会阻塞整个加载流程。第三，善用ctx.plugin()加载子插件，把复杂功能拆成多个小插件，而不是写一个巨型插件。
3.4 类型声明文件的编写要点
给 Cordis 插件写类型声明，核心是声明合并。假设你的插件提供了一个ctx.codeReview服务，需要这样写：
declare module 'cordis' { interface Context { codeReview: CodeReviewService } } interface CodeReviewService { run(files: string[]): Promise<ReviewResult> registerRule(rule: ReviewRule): void }这段声明告诉 TypeScript：Context 上多了一个codeReview属性，类型是CodeReviewService。写完之后，任何拿到 Context 的地方都能正确补全。
有个细节要注意：声明文件里的模块名必须和框架实际导出的模块名一致，否则合并不会生效。我一开始写成了相对路径，结果死活不生效，排查了半天才发现是模块名对不上。
3.5 依赖注入的边界与作用域
Cordis 的作用域是树状的。根 Context 上的服务对所有子 Context 可见，子 Context 上的服务只对它的后代可见。这个设计让你可以做一些精细的隔离，比如给每个会话创建一个子 Context，会话级别的服务就不会泄漏到其他会话。
实操中我建议：全局能力放根 Context，会话能力放会话 Context。比如日志服务、配置服务放根上，而对话历史、临时缓存放会话上。这样既保证了共享，又避免了串数据。
4. 从零实现一个 Harness 插件：完整实操流程
4.1 环境准备与项目初始化
先确认你的 Harness 版本支持插件机制，然后建一个独立的插件项目。目录结构我习惯这样组织：
my-harness-plugin/ src/ index.ts # 插件入口 service.ts # 服务实现 types.d.ts # 类型声明 package.json tsconfig.jsonpackage.json里关键的是main指向编译产物，types指向声明文件。tsconfig.json里declaration要设为 true，否则不会生成 .d.ts。
4.2 编写插件入口与服务
入口函数长这样：
import { Context } from 'cordis' import { CodeReviewService } from './service' export const name = 'code-review' export const inject = ['logger'] export function apply(ctx: Context) { const service = new CodeReviewService(ctx) ctx.provide('codeReview', service) ctx.effect(() => { const timer = setInterval(() => service.cleanup(), 60000) return () => clearInterval(timer) }) }inject字段声明了这个插件依赖logger服务，框架会等 logger 就绪后再加载它。ctx.provide注册服务，ctx.effect注册需要清理的定时器。
4.3 参数计算与配置项设计
插件通常需要配置项，比如审查规则的阈值、超时时间等。我建议把配置设计成带默认值的对象，而不是一堆散参数。这样后续加配置项不会破坏已有调用。
超时时间的设定有个经验公式：超时 = 单文件平均处理时间 × 文件数 × 1.5。单文件平均处理时间可以先跑一次基准测试测出来。比如单文件 200ms，一次审查 20 个文件，那超时设 6 秒比较合理。设太短会误杀，设太长会拖慢整体流程。
4.4 加载插件与验证
把插件目录放到 Harness 的插件搜索路径下，或者通过配置显式指定路径。加载后先看日志确认插件进入就绪状态，再写个最小用例验证服务可用：
const result = await ctx.codeReview.run(['test.ts']) console.log(result.issues)如果这里报ctx.codeReview is undefined，八成是类型声明没生效或者服务没注册成功，按后面排查表的顺序查。
4.5 代码回退场景下的插件行为
热词里出现了“deepseek harness 代码回退”，这其实和插件架构有交集。当 Harness 回退到某个历史状态时，插件注册的服务和监听器需要跟着回退，否则会出现状态不一致。Cordis 的做法是：回退时卸载相关插件再重新加载，而不是试图修改插件内部状态。这个设计很务实，因为让插件自己实现状态回滚几乎不可能做对。
实操建议：插件内部不要保存跨会话的持久状态，需要持久化的东西放到外部存储，插件只做无状态的转换逻辑。这样回退时直接重载插件即可，不会丢数据。
5. 常见问题与排查技巧实录
5.1 服务拿不到：undefined 的五种可能
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| ctx.xxx 为 undefined | 服务未注册 | 检查 provide 是否执行 |
| 类型报错但运行正常 | 声明合并未生效 | 检查模块名是否匹配 |
| 偶发 undefined | 依赖未就绪 | 检查 inject 声明 |
| 子上下文拿不到 | 作用域隔离 | 确认服务注册在正确的 Context |
| 热重载后失效 | 未清理旧注册 | 用 ctx.effect 管理 |
这张表是我实际排查中总结的，覆盖了九成以上的“服务拿不到”问题。按顺序查，基本能定位。
5.2 插件加载顺序导致的竞态
如果插件 A 在加载时就去调用插件 B 的服务，而 B 还没就绪，就会报错。正确做法是通过inject声明依赖，让框架保证顺序。如果确实需要在运行时动态等待，可以用ctx.on('ready')监听就绪事件。
我踩过的一个坑是：在插件入口函数里直接await某个异步初始化，结果框架认为插件还没加载完，一直卡着。后来改成在 effect 里做异步初始化，入口函数保持同步返回，问题就解决了。
5.3 内存泄漏的典型模式
最常见的泄漏模式有三种：定时器没清理、事件监听没取消、外部连接没关闭。这三种都可以用ctx.effect()统一管理。判断有没有泄漏，可以在插件卸载后打印一下活跃的定时器数量，如果没归零就是有问题。
5.4 类型声明冲突的处理
两个插件都想往 Context 上加同名属性，就会冲突。解决办法是加命名空间前缀，比如ctx.reviewA.xxx和ctx.reviewB.xxx。如果实在无法避免冲突，可以在声明时用更具体的类型，让 TypeScript 报错时能看出是哪个插件的问题。
提示：类型冲突在编译期就能发现，比运行时才发现好得多。所以务必开启严格模式，别为了省事关掉类型检查。
6. 插件架构的扩展玩法与个人体会
Cordis 这套架构真正有意思的地方，在于它支持插件组合。你可以写一个基础插件提供通用能力，再写若干上层插件基于它做具体业务。比如一个“代码分析基础插件”提供 AST 解析服务，上面挂“安全审查插件”“风格检查插件”“复杂度分析插件”。每个上层插件只关心自己的规则，基础能力复用。
另一个玩法是按会话动态加载插件。给每个会话创建子 Context，根据会话配置决定加载哪些插件。这样不同用户可以有不同的能力组合，互不干扰。这个模式在多租户场景下特别有用。
我个人的体会是，插件架构的价值不在于“能加功能”，而在于“能安全地加功能”。动态加载谁都会做，难的是加载之后不出乱子、卸载之后不留尾巴。Cordis 通过 Context 作用域、显式依赖声明和 effect 清理机制，把这三件事都兜住了。写插件的时候多花十分钟把类型和生命周期理清楚，后面能省下几小时的调试时间。
最后分享一个小技巧：调试插件时，在入口函数和 effect 清理函数里各打一条带插件名的日志。这样加载卸载的顺序一目了然，排查依赖问题时特别管用。我现在的每个插件都保留这两条日志，已经成了肌肉记忆。
