1. 从 Cordis 说起为什么一个插件架构值得单独拿出来聊第一次接触 DeepSeek Harness 的时候我其实是被它的插件机制吸引住的。市面上大部分 AI 工具类项目插件系统要么是简单的注册回调要么干脆就是硬编码的 if-else 分支能真正做到热插拔、可组合、生命周期可控的并不多。而 DeepSeek Harness 底层用的 Cordis 插件架构恰好把这几个点都做到了而且做得相当优雅。Cordis 是一个基于 TypeScript 的轻量级插件框架核心思想可以用一句话概括一切皆插件插件通过 Fiber 管理生命周期通过 Context 共享能力。你在 DeepSeek Harness 里看到的每一个功能模块——不管是 LLM 接入、提示词优化、代码回退还是桌面端的综述生成——本质上都是一个 Cordis 插件。它们各自独立又能通过 Context 互相调用整个系统像搭积木一样灵活。这篇文章适合谁看如果你正在用 DeepSeek Harness想搞清楚它的插件到底是怎么跑起来的怎么自己写一个插件接进去那这篇就是给你写的。如果你只是对 Cordis 这个插件架构本身感兴趣想借鉴它的设计思路用到自己的 TypeScript 项目里同样能拿到东西。我会从架构设计思路讲起然后拆解核心概念再给出一套完整的插件开发实操流程最后把我踩过的坑和排查经验整理出来。需要提前说明的是Cordis 的官方文档比较精简很多细节需要读源码才能理解。我下面讲的内容一部分来自官方文档一部分来自我读源码和实际写插件时的总结涉及具体实现的地方我会标注清楚哪些是文档明确的、哪些是我基于常见实践推断的。2. Cordis 插件架构的整体设计思路拆解2.1 为什么选择插件化而不是模块化很多人会把插件化和模块化混为一谈觉得都是把代码拆开嘛。但在 Cordis 的设计里这两者有本质区别。模块化是编译期的概念——你在写代码的时候把功能拆成不同的文件、不同的包通过 import 引入。一旦编译完成模块之间的关系就固定了。而插件化是运行期的概念——插件可以在运行时动态加载、卸载、替换插件之间的依赖关系是运行时解析的。DeepSeek Harness 选择 Cordis 而不是自己写一套模块系统核心原因在于它需要运行时动态扩展的能力。举个例子用户可能今天只想用基础的对话功能明天想加一个提示词优化插件后天又想接入一个本地的 LLM。如果这些功能都是编译期固定的模块那每次变更都要重新构建整个应用。而用 Cordis这些插件可以按需加载加载了就能用卸载了就不影响其他部分。另一个关键考量是依赖注入。Cordis 的 Context 本质上是一个依赖注入容器插件通过声明自己需要什么服务、提供什么服务由框架自动完成装配。这样做的好处是插件之间不需要硬编码彼此的引用降低了耦合度。你写一个提示词优化插件不需要知道 LLM 插件具体是哪个实现只需要声明我需要一个 llm 服务框架会自动把可用的 LLM 服务注入进来。2.2 FiberCordis 生命周期管理的核心Fiber 是 Cordis 里最核心也最容易被忽略的概念。简单说每个插件实例都对应一个 FiberFiber 负责管理这个插件的生命周期。为什么需要 Fiber 而不是直接用插件的对象因为插件是有状态的而且状态需要在加载、运行、卸载的不同阶段保持一致。Fiber 就像插件的监护人记录着插件的当前状态、它依赖了哪些服务、它提供了哪些服务、它注册了哪些副作用比如事件监听、定时器。当插件需要卸载时Fiber 会负责清理这些副作用确保不会留下内存泄漏或者悬空引用。我用一个生活化的类比来解释插件好比是租客Fiber 好比是房东。租客住进来的时候要登记加载住的过程中水电煤气都要正常供应依赖注入搬走的时候要结清账目、交还钥匙卸载清理。房东不直接参与租客的生活但负责整个流程的管理。Fiber 的状态机大致是这样的PENDING等待加载→LOADING加载中→ACTIVE运行中→DISPOSING卸载中→DISPOSED已卸载。每个状态转换都有对应的钩子函数插件可以在这些钩子里做初始化或清理工作。2.3 Context插件之间通信的唯一通道Context 是 Cordis 里插件获取服务和注册服务的入口。你可以把它理解成一个服务总线所有插件都通过它来交换能力。Context 有几个关键方法ctx.provide(name, service)注册一个服务其他插件可以通过名字获取ctx.inject(deps, callback)声明依赖当依赖的服务都就绪时执行回调ctx.consume(name)获取一个已注册的服务ctx.on(event, handler)监听事件ctx.emit(event, ...args)触发事件这套机制的好处是插件之间完全解耦。A 插件提供llm服务B 插件消费llm服务但 A 和 B 互相不知道对方的存在。如果有一天你把 A 换成了 A只要 A 也提供llm服务B 完全不需要改动。注意Context 是有作用域的。每个插件拿到的 Context 是它自己的子 Context通过ctx.provide注册的服务默认只在当前插件及其子插件中可见。如果想让服务全局可见需要用ctx.root.provide或者声明为全局服务。这个设计是为了避免命名冲突但也容易让新手困惑——为什么我注册了服务别的插件却拿不到大概率就是作用域的问题。3. 核心概念深度解析与实操要点3.1 插件的三种形态函数、对象、类Cordis 支持三种插件写法各有适用场景。函数式插件是最简单的形态import { Context } from cordis export function myPlugin(ctx: Context) { ctx.on(message, (msg) { console.log(收到消息:, msg) }) } myPlugin.inject [llm]这种写法适合功能单一、不需要维护复杂状态的插件。inject是函数的静态属性声明这个插件依赖哪些服务。对象式插件适合需要暴露多个方法的场景export const myPlugin { name: my-plugin, inject: [llm], apply(ctx: Context) { ctx.provide(myService, { doSomething() { /* ... */ } }) } }类式插件适合需要维护实例状态、有复杂生命周期的场景export class MyPlugin { static inject [llm] private ctx: Context constructor(ctx: Context) { this.ctx ctx ctx.on(dispose, () this.cleanup()) } private cleanup() { // 清理资源 } }我个人的选择标准是能用函数就用函数需要暴露服务用对象需要维护状态用类。不要为了看起来专业就无脑用类函数式插件在 Cordis 里是一等公民性能也更好。3.2 依赖注入的时机与顺序问题依赖注入是 Cordis 最容易踩坑的地方。很多人写完插件发现回调不执行八成是依赖没满足。Cordis 的依赖注入遵循就绪即执行原则当插件声明的所有依赖服务都注册完成后插件的apply或函数体才会执行。如果某个依赖一直没出现插件就一直处于等待状态。这里有个关键细节依赖的解析是异步的。也就是说你不能假设插件加载后立即就能拿到依赖。正确的做法是把依赖相关的逻辑放在inject回调里ctx.inject([llm, config], (ctx) { // 这里 llm 和 config 一定已经就绪 const llm ctx.llm const config ctx.config // 开始你的逻辑 })实操心得我建议把所有依赖服务的获取都放在inject回调里而不是在插件顶层直接ctx.llm。虽然后者在依赖已就绪时也能工作但一旦依赖加载顺序变化就会出问题。用inject回调是最稳妥的写法。另一个坑是循环依赖。A 插件依赖 BB 插件又依赖 ACordis 会检测到这种情况并报错。解决办法是引入一个中间服务或者把公共部分抽出来作为独立插件。3.3 服务的注册与消费命名规范很重要Cordis 的服务是通过字符串名字来标识的。这意味着命名冲突是真实存在的风险。我见过有人用service、util这种过于宽泛的名字结果两个插件注册了同名服务后注册的覆盖了先注册的排查了半天才发现。我的建议是采用命名空间前缀llm.openai、llm.local、llm.mock而不是llmprompt.optimizer、prompt.template而不是promptcode.rollback、code.diff而不是code这样既避免了冲突也让服务的用途一目了然。DeepSeek Harness 内置的插件基本都遵循这个规范你写自己的插件时最好也保持一致。服务注册时还可以声明服务类型方便 TypeScript 做类型推导declare module cordis { interface Context { llm.openai: OpenAIProvider prompt.optimizer: PromptOptimizer } }这段声明合并declaration merging写在你的插件入口文件里其他插件消费这些服务时就能获得完整的类型提示。这是 TypeScript 项目里非常实用的一个技巧强烈建议用上。3.4 事件系统插件间松耦合通信的利器除了服务注册/消费Cordis 还提供了事件系统用于插件间的松耦合通信。服务适合请求-响应模式事件适合发布-订阅模式。比如提示词优化插件需要在每次 LLM 调用前介入它不需要直接调用 LLM 服务而是监听一个llm:before-call事件ctx.on(llm:before-call, (payload) { payload.prompt optimizePrompt(payload.prompt) })LLM 插件在调用前触发这个事件所有监听者都有机会修改 payload。这种模式的好处是扩展点明确——LLM 插件不需要知道有哪些插件会介入只需要在合适的时机触发事件。事件命名我建议用模块:动作的格式比如llm:before-call、llm:after-call、plugin:loaded、plugin:disposed。这样一眼就能看出事件的来源和时机。注意事件监听器是有执行顺序的。Cordis 默认按注册顺序执行但你可以通过ctx.on(event, handler, { prepend: true })把监听器插到最前面。如果多个插件都监听同一个事件执行顺序可能会影响最终结果这点在设计时要考虑清楚。4. 完整实操从零写一个 DeepSeek Harness 插件4.1 环境准备与项目结构假设你已经装好了 DeepSeek Harness现在想写一个提示词优化插件。先看一下推荐的项目结构my-prompt-plugin/ ├── src/ │ ├── index.ts # 插件入口 │ ├── optimizer.ts # 核心逻辑 │ └── types.d.ts # 类型声明 ├── package.json ├── tsconfig.json └── README.mdpackage.json里关键字段{ name: deepseek-harness-prompt-optimizer, version: 1.0.0, main: dist/index.js, types: dist/index.d.ts, peerDependencies: { cordis: ^3.0.0 }, devDependencies: { typescript: ^5.0.0 } }注意cordis放在peerDependencies而不是dependencies因为宿主环境DeepSeek Harness已经提供了 Cordis你的插件不应该再打包一份否则会出现两个 Context 实例服务注册全部失效。这个坑我踩过排查了整整一个下午。tsconfig.json建议开启declaration: true这样编译时会生成.d.ts文件其他插件引用你的服务时能获得类型提示。4.2 插件入口的编写先写类型声明定义你要提供的服务接口// src/types.d.ts export interface PromptOptimizer { optimize(prompt: string, context?: Recordstring, unknown): Promisestring registerRule(name: string, rule: OptimizeRule): void } export interface OptimizeRule { name: string priority: number apply(prompt: string): string | Promisestring } declare module cordis { interface Context { prompt.optimizer: PromptOptimizer } }然后写核心逻辑// src/optimizer.ts import type { PromptOptimizer, OptimizeRule } from ./types export function createOptimizer(): PromptOptimizer { const rules: OptimizeRule[] [] return { async optimize(prompt, context) { const sorted [...rules].sort((a, b) b.priority - a.priority) let result prompt for (const rule of sorted) { result await rule.apply(result) } return result }, registerRule(name, rule) { const idx rules.findIndex(r r.name name) if (idx 0) rules[idx] rule else rules.push(rule) } } }最后是插件入口// src/index.ts import { Context } from cordis import { createOptimizer } from ./optimizer export const name prompt-optimizer export const inject [llm] export function apply(ctx: Context) { const optimizer createOptimizer() // 注册服务 ctx.provide(prompt.optimizer, optimizer) // 注册一个内置规则去除多余空白 optimizer.registerRule(trim-whitespace, { name: trim-whitespace, priority: 100, apply(prompt) { return prompt.replace(/\s/g, ).trim() } }) // 监听 LLM 调用前事件自动优化提示词 ctx.on(llm:before-call, async (payload) { payload.prompt await optimizer.optimize(payload.prompt) }) ctx.logger.info(提示词优化插件已加载) }4.3 在 DeepSeek Harness 中加载插件插件写好了怎么让 DeepSeek Harness 加载它有两种方式。方式一配置文件加载。在 Harness 的配置文件里加上插件路径{ plugins: [ ./plugins/my-prompt-plugin, deepseek-harness-prompt-optimizer ] }本地路径和 npm 包名都支持。Harness 启动时会按顺序加载这些插件。方式二运行时动态加载。如果你的 Harness 版本支持运行时 API可以这样await harness.loadPlugin(./plugins/my-prompt-plugin)动态加载的好处是不用重启整个应用适合开发调试阶段。但要注意动态加载的插件在应用重启后不会自动恢复需要你自己持久化插件列表。实操心得开发阶段我强烈建议用动态加载 热重载。改完代码后调用harness.reloadPlugin(prompt-optimizer)插件会先卸载再重新加载几秒钟就能看到效果。比每次重启整个 Harness 快太多了。不过热重载有个前提——你的插件必须正确实现了dispose清理逻辑否则旧实例的副作用会残留导致行为异常。4.4 参数计算与性能考量提示词优化插件的性能开销主要在两个地方规则排序和规则执行。规则排序用的是Array.prototype.sort时间复杂度 O(n log n)。规则数量一般不会超过几十个这点开销可以忽略。但如果你有几百个规则建议在registerRule时就维护好有序数组避免每次optimize都重新排序。规则执行是串行的因为后面的规则可能依赖前面规则的结果。如果你的规则之间没有依赖关系可以考虑并行执行const results await Promise.all(sorted.map(r r.apply(prompt)))但这样会丢失规则之间的传递性只适合独立变换类的规则。我实测下来对于提示词优化这种场景串行执行更符合直觉性能也完全够用——单次优化通常在 1ms 以内相比 LLM 调用的几百毫秒完全可以忽略。真正需要注意的是异步规则的超时控制。如果某个规则调用了外部服务比如查词典可能会卡住整个优化流程。建议给每个规则加超时const result await Promise.race([ rule.apply(prompt), new Promise((_, reject) setTimeout(() reject(new Error(规则 ${rule.name} 超时)), 1000) ) ])这样单个规则出问题不会拖垮整个插件。5. 常见问题与排查技巧实录5.1 插件加载了但功能不生效这是最常见的问题排查思路按以下顺序来排查项检查方法常见原因插件是否真的加载看日志有没有插件的启动输出路径写错、包名拼错依赖是否满足检查inject声明的服务是否都已注册依赖的插件没加载服务是否注册成功在另一个插件里ctx.consume试试作用域问题、命名冲突事件是否触发在事件回调里打日志事件名拼错、触发时机不对执行顺序是否对检查监听器的注册顺序被其他插件覆盖了结果我遇到最多的是作用域问题。插件 A 用ctx.provide注册了服务插件 B 却拿不到。原因是 A 和 B 不在同一个 Context 树上。解决办法是用ctx.root.provide注册全局服务或者在加载插件时指定相同的父 Context。5.2 插件卸载后残留副作用Cordis 的 Fiber 会自动清理通过ctx.on、ctx.setTimeout等 API 注册的副作用但如果你用了原生的addEventListener、setInterval就需要手动清理export function apply(ctx: Context) { const timer setInterval(() { /* ... */ }, 1000) ctx.on(dispose, () { clearInterval(timer) }) }dispose事件是 Cordis 提供的卸载钩子插件被卸载时会触发。所有需要手动清理的资源都应该在这里处理。踩坑记录我曾经写过一个插件在apply里给全局对象挂了一个属性卸载时忘了删。结果热重载几次后全局对象上挂了一堆重复属性内存泄漏不说行为也变得诡异。后来养成习惯——凡是apply里做的修改都要在dispose里撤销。5.3 TypeScript 类型声明不生效如果你在插件里用了declare module cordis扩展 Context 类型但消费方拿不到类型提示通常是这几个原因.d.ts文件没有被包含在tsconfig.json的include里package.json的types字段指向错误消费方的tsconfig.json没有开启skipLibCheck: false排查方法在消费方代码里把鼠标悬停在ctx.上看 IDE 提示的类型里有没有你扩展的服务。如果没有就是声明合并没生效。另一个常见问题是类型声明文件的位置。declare module必须写在模块文件里有 import/export 的文件如果写在全局脚本文件里没有 import/export会变成全局声明而不是模块扩展。这个细节很容易忽略我见过好几个项目栽在这上面。5.4 插件间循环依赖的处理A 依赖 BB 依赖 ACordis 会报循环依赖错误。解决办法有三种方案一抽公共部分。把 A 和 B 共同依赖的逻辑抽成插件 CA 和 B 都依赖 C不再互相依赖。方案二延迟消费。A 不直接依赖 B而是在需要的时候通过ctx.consume动态获取// A 插件里 ctx.inject([b.service], (ctx) { // 这里才真正使用 b.service })方案三事件解耦。A 和 B 不直接互相调用而是通过事件通信。A 触发事件B 监听B 触发事件A 监听。这样两者之间没有直接的依赖关系。我一般优先用方案一因为最干净。方案二适合依赖关系确实存在但可以延迟的场景。方案三适合两者是通知关系而非调用关系的场景。5.5 离线局域网环境下的插件加载有朋友问过 DeepSeek Harness 能不能在离线局域网用。答案是能但插件加载方式要调整。离线环境下没法从 npm 拉包所有插件必须提前下载好放在本地。配置文件里用相对路径或绝对路径引用{ plugins: [ /opt/harness/plugins/prompt-optimizer, /opt/harness/plugins/local-llm ] }如果插件本身还有 npm 依赖需要提前npm install好把node_modules一起打包进去。或者用npm pack打成 tarball在目标机器上npm install ./plugin.tgz。实操心得离线部署时我建议把所有插件放在同一个目录下用一个plugins.json统一管理。这样迁移环境时只需要拷贝一个目录不用到处找插件文件。另外记得检查插件的peerDependencies确保宿主环境的 Cordis 版本满足要求版本不匹配会导致各种奇怪的运行时错误。6. 插件架构的扩展玩法与个人体会Cordis 这套插件架构真正有意思的地方在于它支持插件组合。你可以写一个元插件在它的apply里加载其他插件export function apply(ctx: Context) { ctx.plugin(PromptOptimizerPlugin) ctx.plugin(LocalLLMPlugin) ctx.plugin(CodeRollbackPlugin) }这样用户只需要加载一个插件就能获得一整套功能。DeepSeek Harness 的实用插件包就是这么做的。另一个玩法是插件配置。Cordis 支持给插件传配置ctx.plugin(MyPlugin, { timeout: 5000, rules: [trim, expand] })插件在apply里通过第二个参数接收配置。这让同一个插件可以在不同场景下有不同的行为而不需要写多个插件。我自己在实际项目里最深的体会是插件架构的价值不在于能拆而在于能合。拆开容易难的是拆开之后还能优雅地组合起来。Cordis 通过 Context 和 Fiber 这两个抽象把合的问题解决得相当漂亮。你在设计自己的插件时也要多想一步——这个插件将来会和谁组合组合时会不会有冲突把这些问题想在前面插件生态才能健康发展。最后分享一个小技巧写插件时养成写README.md的习惯把插件的依赖、提供的服务、监听的事件、配置项都列清楚。Cordis 生态里插件多了之后光看代码很难快速理解一个插件的作用一份好的 README 能省下大量沟通成本。我现在写插件README 和代码是同步写的写完代码顺手就把文档补上后面维护起来轻松很多。