1. 从一次插件加载失败说起Cordis 架构到底解决了什么问题我第一次接触 DeepSeek Harness 的插件系统是因为一个很具体的需求团队内部有个自研的代码审查工具想把它挂到 Harness 的工作流里让模型在生成代码之后自动跑一遍静态检查。当时想得很简单写个脚本调用一下不就行了结果真动手才发现Harness 的插件机制不是简单的“挂个钩子”它背后有一套完整的依赖注入和生命周期管理体系这套体系的核心就是Cordis。Cordis 是 DeepSeek Harness 用来组织插件、管理依赖、控制生命周期的底层框架。你可以把它理解成一个“插件操作系统”——每个插件都是一个独立的模块声明自己需要什么、提供什么Cordis 负责在合适的时机把它们组装起来、启动起来、在不需要的时候干净地卸载掉。这个设计思路在 Node.js 生态里其实不算新鲜但 Cordis 有几个自己的特点基于TypeScript的类型系统做依赖声明、用Fiber概念管理插件的执行上下文、支持热插拔和代码回退。为什么 Harness 要费这么大劲搞一套插件架构因为 Harness 本身是一个面向 LLM 工作流的编排工具它的能力边界必须能随时扩展。今天你可能需要一个提示词优化插件明天可能要接入一个本地知识库后天又要换一个模型供应商。如果每次扩展都要改核心代码、重新打包、重启服务那这个工具就没法用了。Cordis 的价值就在于让插件像积木一样即插即用而且插拔过程不影响正在运行的其他部分。这篇文章适合几类人看一是想给 Harness 写插件但不知道从哪下手的开发者二是对 TypeScript 依赖注入和插件架构感兴趣、想看看实际项目怎么落地的人三是已经在用 Harness、想搞清楚插件加载失败时该怎么排查的运维同学。我会从架构设计讲到实操步骤再到踩坑经验尽量把每个环节的“为什么”说清楚。2. Cordis 插件架构的核心设计拆解2.1 为什么是 Cordis 而不是直接写中间件很多人第一反应是插件系统嘛不就是 Express 那种中间件模式注册一堆函数按顺序执行我一开始也这么想。但实际用下来发现中间件模式有几个硬伤。第一中间件没有明确的依赖关系。A 中间件依赖 B 中间件先执行这个顺序只能靠注册顺序来保证一旦有人插队就乱了。第二中间件没有生命周期概念你没法在“插件卸载时”做清理工作。第三中间件之间共享状态只能靠挂载在 request 对象上类型安全很差。Cordis 的做法是引入服务Service和依赖声明。每个插件在注册时明确声明“我需要哪些服务”和“我提供哪些服务”Cordis 根据这些声明自动计算加载顺序。这就像乐高积木的凸点和凹槽——你不需要告诉别人“先拼哪块”只要凸凹匹配自然就能拼上。注意Cordis 的依赖注入是“按需注入”而不是“全局注册”。这意味着一个插件只有在被真正需要时才会实例化不会浪费内存和启动时间。2.2 Fiber插件的执行上下文Fiber 是 Cordis 里最容易被忽略但最重要的概念。简单说每个插件实例都运行在一个独立的 Fiber 里。Fiber 记录了插件的状态、它注册的服务、它订阅的事件、它创建的资源。当插件被卸载时Cordis 只需要销毁对应的 Fiber所有关联的资源就会被自动回收。这个设计的好处在于隔离性。假设你写了一个插件里面有个定时器每 30 秒跑一次。如果没有 Fiber插件卸载后定时器还在跑就变成了内存泄漏。有了 FiberCordis 在卸载时会自动清理这个 Fiber 下所有注册的副作用你不需要手动去 clearInterval。从实现角度看Fiber 本质上是一个上下文对象它持有一个disposables列表。每次你在插件里调用ctx.on()、ctx.setInterval()、ctx.provide()这类方法Cordis 都会把对应的清理函数塞进这个列表。卸载时遍历执行一遍干干净净。2.3 TypeScript 类型系统在插件架构中的角色Cordis 对 TypeScript 的利用程度很深不只是“用 TS 写代码”那么简单。它通过声明合并Declaration Merging让插件可以扩展核心的类型定义。比如你写了一个新插件提供了一个ctx.database服务你可以在自己的.d.ts文件里声明declare module cordis { interface Context { database: DatabaseService } }这样在其他插件里访问ctx.database时TypeScript 就能给出完整的类型提示和检查。这个机制让插件之间的接口契约变得可验证——如果你的插件声明依赖ctx.database但运行时没有这个服务Cordis 会在加载阶段就报错而不是等到运行到那一行才崩。2.4 插件加载的完整流程Cordis 加载一个插件的流程大致分四步解析依赖读取插件的inject声明确定它需要哪些服务。拓扑排序根据所有插件的依赖关系计算出一个无环的加载顺序。创建 Fiber为每个插件创建独立的执行上下文。执行 apply 函数调用插件的入口函数传入上下文对象。如果某一步失败Cordis 会回滚已经加载的插件保证系统回到加载前的状态。这个回滚机制在开发阶段特别有用——你改了一个插件导致加载失败不会把整个 Harness 搞崩。3. 手把手写一个 Cordis 插件3.1 环境准备与项目结构在开始写代码之前先把环境搭好。你需要 Node.js 18 以上版本以及一个能跑 TypeScript 的构建工具链。我习惯用tsx做开发时的即时运行用tsup做打包。mkdir harness-plugin-demo cd harness-plugin-demo npm init -y npm install cordis typescript tsx tsup -D npx tsc --init项目结构建议这样组织harness-plugin-demo/ ├── src/ │ ├── index.ts # 插件入口 │ ├── service.ts # 服务实现 │ └── types.d.ts # 类型声明扩展 ├── package.json └── tsconfig.jsontsconfig.json里需要开启strict和declaration因为 Cordis 的类型扩展依赖声明文件的正确生成。3.2 插件入口的写法与参数解析一个最简的 Cordis 插件长这样import { Context } from cordis export const name my-plugin export const inject [logger] export function apply(ctx: Context, config: PluginConfig) { ctx.logger.info(my-plugin loaded with config: %o, config) ctx.on(harness/before-generate, async (event) { // 在模型生成之前做一些事情 }) }这里有几个关键点。name是插件的唯一标识不能重复。inject声明依赖的服务列表Cordis 会确保这些服务在apply执行前已经就绪。apply函数是插件的入口接收上下文和配置两个参数。配置参数从哪来从 Harness 的配置文件里读。你可以在harness.config.json里这样写{ plugins: { my-plugin: { enabled: true, options: { threshold: 0.8, model: deepseek-chat } } } }Cordis 会把options里的内容作为第二个参数传给apply。这个设计让插件的行为可以通过配置调整而不需要改代码。3.3 服务注册与依赖注入的实操细节假设我们要写一个“提示词优化”插件它需要提供一个服务给其他插件调用。服务注册的写法import { Service, Context } from cordis export class PromptOptimizer extends Service { static inject [logger] constructor(ctx: Context, private config: OptimizerConfig) { super(ctx, promptOptimizer) } optimize(prompt: string): string { // 实际的优化逻辑 return prompt.replace(/\s/g, ).trim() } } export const name prompt-optimizer export const inject [logger] export function apply(ctx: Context, config: OptimizerConfig) { ctx.plugin(PromptOptimizer, config) }这里Service基类的构造函数第二个参数是服务名注册后其他插件就可以通过ctx.promptOptimizer访问。static inject声明这个服务自身依赖哪些其他服务。实操心得服务名建议用驼峰命名和 TypeScript 的属性访问风格保持一致。不要用prompt_optimizer这种下划线风格访问起来很别扭。3.4 生命周期钩子的正确使用姿势Cordis 提供了几个关键的生命周期钩子用对了能省很多事钩子触发时机典型用途ctx.on(ready)所有插件加载完成启动后台任务ctx.on(dispose)插件即将卸载清理外部资源ctx.on(config)配置热更新重新读取配置我见过最常见的错误是在apply里直接启动一个无限循环的任务然后忘了在dispose时停掉。正确做法是用ctx.setInterval而不是原生setInterval这样 Fiber 会自动管理清理。export function apply(ctx: Context) { ctx.setInterval(() { // 定期任务 }, 60000) // 不需要手动 clearIntervalFiber 会处理 }4. 插件加载失败的排查与代码回退4.1 常见加载错误与定位方法插件加载失败时Harness 的日志会给出错误堆栈但有时候信息不够明确。我整理了几种典型情况和排查思路错误信息可能原因排查方法service not found: xxx依赖的服务未注册检查inject声明和服务提供方是否都启用circular dependency detected插件间循环依赖用cordis graph命令输出依赖图plugin already registered插件名重复检查name导出是否唯一apply is not a function入口导出格式错误确认导出了apply函数而非默认导出如果日志不够用可以在启动时加DEBUGcordis:*环境变量Cordis 会输出详细的加载过程。4.2 代码回退的触发条件与操作步骤Harness 的代码回退功能在插件开发阶段特别有用。当你改了一个插件导致系统起不来不需要手动去改文件直接触发回退就行。回退的触发条件通常有三种插件加载超时、apply函数抛出未捕获异常、依赖解析失败。操作步骤在 Harness 启动参数里加--rollback-on-failure。系统检测到加载失败后会自动恢复到上一次成功的插件快照。快照文件默认存在.harness/snapshots/目录下按时间戳命名。注意回退只恢复插件加载状态不会恢复插件产生的数据。如果你的插件在加载时写了数据库回退不会撤销那些写入。所以插件的初始化逻辑要尽量幂等。4.3 离线局域网环境下的插件部署有些团队的内网环境不能访问外部 npm 源这时候插件部署需要提前把依赖打包好。我的做法是在有网的环境下执行npm pack把插件打成 tarball。把 tarball 和它的所有依赖一起拷贝到内网。在内网用npm install ./plugin.tgz --offline安装。如果插件依赖了 Harness 的核心包需要确认内网环境的 Harness 版本和开发时一致。版本不匹配是离线部署最常见的坑。5. 几个实战中踩出来的经验5.1 插件粒度怎么控制我一开始写插件喜欢“大而全”一个插件里塞了提示词优化、日志记录、结果缓存三件事。后来发现这样很不好维护——想单独关掉缓存功能就得改代码。正确的做法是按职责拆分每个插件只做一件事。Cordis 的依赖注入机制让插件间通信成本很低没必要为了“少写几个文件”而牺牲灵活性。5.2 类型声明文件的编写要点前面提到用声明合并扩展 Context 类型这里补充几个细节。.d.ts文件必须被tsconfig.json的include覆盖到否则类型不生效。另外声明合并的模块名必须和实际导入的包名完全一致大小写都不能错。我遇到过因为写成Cordis而不是cordis导致类型扩展失效的情况排查了半天。5.3 热重载时的状态保持开发阶段用热重载能省很多重启时间但要注意热重载会销毁旧 Fiber 创建新 Fiber插件里的内存状态会丢失。如果你的插件需要保持状态比如缓存要么把状态存到外部Redis、文件要么在dispose时序列化、在apply时反序列化。我一般建议前者更可靠。5.4 性能上的一个反直觉发现我原本以为插件越多启动越慢实测下来发现影响启动时间的主要是依赖解析的复杂度而不是插件数量本身。十个互不依赖的插件加载速度和三个有链式依赖的插件差不多。所以设计插件时尽量让依赖关系扁平化避免 A→B→C→D 这种长链。6. 插件生态的扩展方向Cordis 这套架构最让我满意的地方是它的扩展性没有上限。你可以写一个插件来管理其他插件也可以写一个插件来动态生成插件。我最近在尝试的一个方向是根据用户的自然语言描述自动生成一个简单的插件骨架然后让用户在此基础上修改。这个思路如果跑通插件开发的门槛会进一步降低。另一个值得关注的方向是插件的版本管理。目前 Cordis 对插件版本没有强制约束两个插件依赖同一个服务的不同版本时可能会出问题。社区里有人在讨论引入语义化版本约束但还没形成标准方案。如果你在生产环境用 Harness建议对插件版本做手动锁定避免自动升级带来的意外。最后分享一个我常用的调试技巧在apply函数的第一行加ctx.logger.debug(plugin %s applying, name)然后在启动时开 debug 日志。这样能清楚看到每个插件的加载顺序和耗时定位性能瓶颈很直观。 
长河君 · 2026/10/26 21:57:05 · 阅读 1.2k DeepSeek Harness 插件架构解析：Cordis 依赖注入与生命周期管理实战
1. 从一次插件加载失败说起Cordis 架构到底解决了什么问题我第一次接触 DeepSeek Harness 的插件系统是因为一个很具体的需求团队内部有个自研的代码审查工具想把它挂到 Harness 的工作流里让模型在生成代码之后自动跑一遍静态检查。当时想得很简单写个脚本调用一下不就行了结果真动手才发现Harness 的插件机制不是简单的“挂个钩子”它背后有一套完整的依赖注入和生命周期管理体系这套体系的核心就是Cordis。Cordis 是 DeepSeek Harness 用来组织插件、管理依赖、控制生命周期的底层框架。你可以把它理解成一个“插件操作系统”——每个插件都是一个独立的模块声明自己需要什么、提供什么Cordis 负责在合适的时机把它们组装起来、启动起来、在不需要的时候干净地卸载掉。这个设计思路在 Node.js 生态里其实不算新鲜但 Cordis 有几个自己的特点基于TypeScript的类型系统做依赖声明、用Fiber概念管理插件的执行上下文、支持热插拔和代码回退。为什么 Harness 要费这么大劲搞一套插件架构因为 Harness 本身是一个面向 LLM 工作流的编排工具它的能力边界必须能随时扩展。今天你可能需要一个提示词优化插件明天可能要接入一个本地知识库后天又要换一个模型供应商。如果每次扩展都要改核心代码、重新打包、重启服务那这个工具就没法用了。Cordis 的价值就在于让插件像积木一样即插即用而且插拔过程不影响正在运行的其他部分。这篇文章适合几类人看一是想给 Harness 写插件但不知道从哪下手的开发者二是对 TypeScript 依赖注入和插件架构感兴趣、想看看实际项目怎么落地的人三是已经在用 Harness、想搞清楚插件加载失败时该怎么排查的运维同学。我会从架构设计讲到实操步骤再到踩坑经验尽量把每个环节的“为什么”说清楚。2. Cordis 插件架构的核心设计拆解2.1 为什么是 Cordis 而不是直接写中间件很多人第一反应是插件系统嘛不就是 Express 那种中间件模式注册一堆函数按顺序执行我一开始也这么想。但实际用下来发现中间件模式有几个硬伤。第一中间件没有明确的依赖关系。A 中间件依赖 B 中间件先执行这个顺序只能靠注册顺序来保证一旦有人插队就乱了。第二中间件没有生命周期概念你没法在“插件卸载时”做清理工作。第三中间件之间共享状态只能靠挂载在 request 对象上类型安全很差。Cordis 的做法是引入服务Service和依赖声明。每个插件在注册时明确声明“我需要哪些服务”和“我提供哪些服务”Cordis 根据这些声明自动计算加载顺序。这就像乐高积木的凸点和凹槽——你不需要告诉别人“先拼哪块”只要凸凹匹配自然就能拼上。注意Cordis 的依赖注入是“按需注入”而不是“全局注册”。这意味着一个插件只有在被真正需要时才会实例化不会浪费内存和启动时间。2.2 Fiber插件的执行上下文Fiber 是 Cordis 里最容易被忽略但最重要的概念。简单说每个插件实例都运行在一个独立的 Fiber 里。Fiber 记录了插件的状态、它注册的服务、它订阅的事件、它创建的资源。当插件被卸载时Cordis 只需要销毁对应的 Fiber所有关联的资源就会被自动回收。这个设计的好处在于隔离性。假设你写了一个插件里面有个定时器每 30 秒跑一次。如果没有 Fiber插件卸载后定时器还在跑就变成了内存泄漏。有了 FiberCordis 在卸载时会自动清理这个 Fiber 下所有注册的副作用你不需要手动去 clearInterval。从实现角度看Fiber 本质上是一个上下文对象它持有一个disposables列表。每次你在插件里调用ctx.on()、ctx.setInterval()、ctx.provide()这类方法Cordis 都会把对应的清理函数塞进这个列表。卸载时遍历执行一遍干干净净。2.3 TypeScript 类型系统在插件架构中的角色Cordis 对 TypeScript 的利用程度很深不只是“用 TS 写代码”那么简单。它通过声明合并Declaration Merging让插件可以扩展核心的类型定义。比如你写了一个新插件提供了一个ctx.database服务你可以在自己的.d.ts文件里声明declare module cordis { interface Context { database: DatabaseService } }这样在其他插件里访问ctx.database时TypeScript 就能给出完整的类型提示和检查。这个机制让插件之间的接口契约变得可验证——如果你的插件声明依赖ctx.database但运行时没有这个服务Cordis 会在加载阶段就报错而不是等到运行到那一行才崩。2.4 插件加载的完整流程Cordis 加载一个插件的流程大致分四步解析依赖读取插件的inject声明确定它需要哪些服务。拓扑排序根据所有插件的依赖关系计算出一个无环的加载顺序。创建 Fiber为每个插件创建独立的执行上下文。执行 apply 函数调用插件的入口函数传入上下文对象。如果某一步失败Cordis 会回滚已经加载的插件保证系统回到加载前的状态。这个回滚机制在开发阶段特别有用——你改了一个插件导致加载失败不会把整个 Harness 搞崩。3. 手把手写一个 Cordis 插件3.1 环境准备与项目结构在开始写代码之前先把环境搭好。你需要 Node.js 18 以上版本以及一个能跑 TypeScript 的构建工具链。我习惯用tsx做开发时的即时运行用tsup做打包。mkdir harness-plugin-demo cd harness-plugin-demo npm init -y npm install cordis typescript tsx tsup -D npx tsc --init项目结构建议这样组织harness-plugin-demo/ ├── src/ │ ├── index.ts # 插件入口 │ ├── service.ts # 服务实现 │ └── types.d.ts # 类型声明扩展 ├── package.json └── tsconfig.jsontsconfig.json里需要开启strict和declaration因为 Cordis 的类型扩展依赖声明文件的正确生成。3.2 插件入口的写法与参数解析一个最简的 Cordis 插件长这样import { Context } from cordis export const name my-plugin export const inject [logger] export function apply(ctx: Context, config: PluginConfig) { ctx.logger.info(my-plugin loaded with config: %o, config) ctx.on(harness/before-generate, async (event) { // 在模型生成之前做一些事情 }) }这里有几个关键点。name是插件的唯一标识不能重复。inject声明依赖的服务列表Cordis 会确保这些服务在apply执行前已经就绪。apply函数是插件的入口接收上下文和配置两个参数。配置参数从哪来从 Harness 的配置文件里读。你可以在harness.config.json里这样写{ plugins: { my-plugin: { enabled: true, options: { threshold: 0.8, model: deepseek-chat } } } }Cordis 会把options里的内容作为第二个参数传给apply。这个设计让插件的行为可以通过配置调整而不需要改代码。3.3 服务注册与依赖注入的实操细节假设我们要写一个“提示词优化”插件它需要提供一个服务给其他插件调用。服务注册的写法import { Service, Context } from cordis export class PromptOptimizer extends Service { static inject [logger] constructor(ctx: Context, private config: OptimizerConfig) { super(ctx, promptOptimizer) } optimize(prompt: string): string { // 实际的优化逻辑 return prompt.replace(/\s/g, ).trim() } } export const name prompt-optimizer export const inject [logger] export function apply(ctx: Context, config: OptimizerConfig) { ctx.plugin(PromptOptimizer, config) }这里Service基类的构造函数第二个参数是服务名注册后其他插件就可以通过ctx.promptOptimizer访问。static inject声明这个服务自身依赖哪些其他服务。实操心得服务名建议用驼峰命名和 TypeScript 的属性访问风格保持一致。不要用prompt_optimizer这种下划线风格访问起来很别扭。3.4 生命周期钩子的正确使用姿势Cordis 提供了几个关键的生命周期钩子用对了能省很多事钩子触发时机典型用途ctx.on(ready)所有插件加载完成启动后台任务ctx.on(dispose)插件即将卸载清理外部资源ctx.on(config)配置热更新重新读取配置我见过最常见的错误是在apply里直接启动一个无限循环的任务然后忘了在dispose时停掉。正确做法是用ctx.setInterval而不是原生setInterval这样 Fiber 会自动管理清理。export function apply(ctx: Context) { ctx.setInterval(() { // 定期任务 }, 60000) // 不需要手动 clearIntervalFiber 会处理 }4. 插件加载失败的排查与代码回退4.1 常见加载错误与定位方法插件加载失败时Harness 的日志会给出错误堆栈但有时候信息不够明确。我整理了几种典型情况和排查思路错误信息可能原因排查方法service not found: xxx依赖的服务未注册检查inject声明和服务提供方是否都启用circular dependency detected插件间循环依赖用cordis graph命令输出依赖图plugin already registered插件名重复检查name导出是否唯一apply is not a function入口导出格式错误确认导出了apply函数而非默认导出如果日志不够用可以在启动时加DEBUGcordis:*环境变量Cordis 会输出详细的加载过程。4.2 代码回退的触发条件与操作步骤Harness 的代码回退功能在插件开发阶段特别有用。当你改了一个插件导致系统起不来不需要手动去改文件直接触发回退就行。回退的触发条件通常有三种插件加载超时、apply函数抛出未捕获异常、依赖解析失败。操作步骤在 Harness 启动参数里加--rollback-on-failure。系统检测到加载失败后会自动恢复到上一次成功的插件快照。快照文件默认存在.harness/snapshots/目录下按时间戳命名。注意回退只恢复插件加载状态不会恢复插件产生的数据。如果你的插件在加载时写了数据库回退不会撤销那些写入。所以插件的初始化逻辑要尽量幂等。4.3 离线局域网环境下的插件部署有些团队的内网环境不能访问外部 npm 源这时候插件部署需要提前把依赖打包好。我的做法是在有网的环境下执行npm pack把插件打成 tarball。把 tarball 和它的所有依赖一起拷贝到内网。在内网用npm install ./plugin.tgz --offline安装。如果插件依赖了 Harness 的核心包需要确认内网环境的 Harness 版本和开发时一致。版本不匹配是离线部署最常见的坑。5. 几个实战中踩出来的经验5.1 插件粒度怎么控制我一开始写插件喜欢“大而全”一个插件里塞了提示词优化、日志记录、结果缓存三件事。后来发现这样很不好维护——想单独关掉缓存功能就得改代码。正确的做法是按职责拆分每个插件只做一件事。Cordis 的依赖注入机制让插件间通信成本很低没必要为了“少写几个文件”而牺牲灵活性。5.2 类型声明文件的编写要点前面提到用声明合并扩展 Context 类型这里补充几个细节。.d.ts文件必须被tsconfig.json的include覆盖到否则类型不生效。另外声明合并的模块名必须和实际导入的包名完全一致大小写都不能错。我遇到过因为写成Cordis而不是cordis导致类型扩展失效的情况排查了半天。5.3 热重载时的状态保持开发阶段用热重载能省很多重启时间但要注意热重载会销毁旧 Fiber 创建新 Fiber插件里的内存状态会丢失。如果你的插件需要保持状态比如缓存要么把状态存到外部Redis、文件要么在dispose时序列化、在apply时反序列化。我一般建议前者更可靠。5.4 性能上的一个反直觉发现我原本以为插件越多启动越慢实测下来发现影响启动时间的主要是依赖解析的复杂度而不是插件数量本身。十个互不依赖的插件加载速度和三个有链式依赖的插件差不多。所以设计插件时尽量让依赖关系扁平化避免 A→B→C→D 这种长链。6. 插件生态的扩展方向Cordis 这套架构最让我满意的地方是它的扩展性没有上限。你可以写一个插件来管理其他插件也可以写一个插件来动态生成插件。我最近在尝试的一个方向是根据用户的自然语言描述自动生成一个简单的插件骨架然后让用户在此基础上修改。这个思路如果跑通插件开发的门槛会进一步降低。另一个值得关注的方向是插件的版本管理。目前 Cordis 对插件版本没有强制约束两个插件依赖同一个服务的不同版本时可能会出问题。社区里有人在讨论引入语义化版本约束但还没形成标准方案。如果你在生产环境用 Harness建议对插件版本做手动锁定避免自动升级带来的意外。最后分享一个我常用的调试技巧在apply函数的第一行加ctx.logger.debug(plugin %s applying, name)然后在启动时开 debug 日志。这样能清楚看到每个插件的加载顺序和耗时定位性能瓶颈很直观。