1. 从一次插件加载失败说起：Cordis 架构到底解决了什么问题

我第一次接触 DeepSeek Harness 的插件体系，是因为一个很具体的需求：团队内部想把代码审查的规则引擎挂到 Harness 的对话流程里，让模型在生成代码之后自动跑一遍自定义的静态检查。当时想得很简单，写个脚本监听输出就行。结果真动手才发现，Harness 的执行链路是分阶段的，模型输出、工具调用、上下文注入、结果回写各自处在不同的生命周期节点上，如果只是在外层包一层，根本拿不到中间态的数据。

这就是 Cordis 插件架构存在的意义。它不是一个简单的“加载器”，而是一套围绕Fiber（纤程）构建的依赖注入与生命周期管理系统。你可以把它理解成 Harness 的“神经系统”：每个插件是一个神经元，Fiber 是神经纤维，负责把信号按正确的顺序、正确的依赖关系传递下去。插件之间不需要互相 import，而是通过声明式的方式注册能力、消费能力，由 Cordis 在运行时完成装配。

用 TypeScript 写 Cordis 插件，核心心智模型只有三个词：Context（上下文）、Plugin（插件）、Fiber（纤程）。Context 是插件运行时的“世界”，里面挂着所有已注册的服务；Plugin 是一个函数或对象，接收 Context 并往里面注册东西；Fiber 则是插件的一次运行实例，它记录了插件的状态、依赖、子插件树，以及销毁时的清理逻辑。这三者构成了整个架构的骨架。

这套设计适合谁？如果你只是想用 Harness 跑几个提示词，那完全不需要碰 Cordis。但如果你要做的是：给 Harness 增加新的工具能力、接入私有模型、改写上下文组装逻辑、在对话流程中插入自定义阶段、或者把多个插件组合成一个可复用的功能包——那 Cordis 就是你绕不开的一层。它解决的核心问题是可组合性与可撤销性：插件可以热插拔，加载失败不会污染全局，卸载时能干净地回收资源。

我踩过的第一个坑，就是没理解 Fiber 的父子关系。当时写了一个插件，在apply里直接ctx.on('some-event', handler)，结果插件被卸载后事件监听还在，导致内存泄漏和重复触发。后来才明白，Cordis 的 Context 是有作用域的，通过ctx.on注册的监听会自动绑定到当前 Fiber，Fiber 销毁时监听一并清除。但前提是你得用对 API——用全局的ctx.root.on就不会自动清理。这个细节后面会展开讲。

2. Cordis 核心概念拆解：Context、Plugin 与 Fiber 的三角关系

2.1 Context：不是普通的对象，而是带作用域的服务容器

很多人第一眼看到 Cordis 的 Context，会以为它就是个普通的依赖注入容器，类似 NestJS 的 Provider 或者 Angular 的 Injector。但 Cordis 的 Context 有一个关键区别：它是可派生的，派生出来的子 Context 继承父 Context 的所有服务，同时拥有独立的生命周期。

import { Context } from 'cordis' const root = new Context() root.provide('config', { debug: true }) const child = root.extend() child.provide('logger', console) // child 能访问 config 和 logger // root 只能访问 config，访问不到 logger

这个派生机制是 Fiber 树的基础。每个插件在加载时，Cordis 会基于当前 Context 创建一个子 Context，插件内部所有provide的服务都挂在这个子 Context 上。插件卸载时，子 Context 被销毁，上面挂的服务、监听、定时器全部失效。这就是为什么 Cordis 能做到“干净卸载”——它靠的是作用域隔离，而不是手动清理。

注意：ctx.provide注册的服务默认是覆盖式的。如果子 Context 提供了同名服务，会遮蔽父 Context 的版本。这个特性可以用来做插件级别的配置覆盖，但也容易造成“为什么我拿到的 config 不对”的困惑。排查时优先检查 Context 层级。

2.2 Plugin：函数式与对象式两种写法，选哪个有讲究

Cordis 插件有两种形态。函数式插件就是一个接收 Context 的函数：

export function myPlugin(ctx: Context, options: { threshold: number }) { ctx.on('message', (msg) => { if (msg.length > options.threshold) { ctx.emit('message-too-long', msg) } }) }

对象式插件则是一个带apply方法的对象，可以声明name、inject、reusable等元信息：

export const myPlugin = { name: 'length-guard', inject: ['config'], apply(ctx: Context, options: { threshold: number }) { // ... } }

两者的核心差异在于元信息的表达能力。对象式插件可以声明inject，告诉 Cordis “我需要 config 服务，没有它就别加载我”。Cordis 会等待依赖就绪后再执行apply，这就是所谓的依赖注入。函数式插件没有这个能力，它会在加载时立即执行，如果此时依赖还没注册，就会拿到 undefined。

我个人的选择标准是：如果插件有外部依赖、需要被其他插件引用、或者需要控制加载顺序，就用对象式；如果只是一个简单的副作用注册，函数式就够了。但即便是函数式，也建议用ctx.inject(['config'], (ctx) => { ... })来包裹依赖逻辑，这样能获得同样的等待语义。

2.3 Fiber：插件的运行时实例，也是排查问题的关键线索

Fiber 是 Cordis 里最容易被忽视、但在排查问题时最有用的概念。每次插件被加载，Cordis 都会创建一个 Fiber 对象，它包含：

当插件加载失败时，Cordis 不会直接抛异常中断整个应用，而是把 Fiber 标记为disposed并记录错误。你可以通过ctx.registry遍历所有 Fiber，找到状态异常的节点。这个机制在开发插件时特别有用——你可以写一个诊断插件，在启动后打印整棵 Fiber 树，一眼就能看出哪个插件没加载上。

export function diagnose(ctx: Context) { ctx.on('ready', () => { for (const fiber of ctx.registry.values()) { console.log(`${fiber.name}: ${fiber.state}`) } }) }

3. 插件加载全流程：从注册到就绪的六个阶段

3.1 阶段一：插件注册与依赖解析

当你调用ctx.plugin(myPlugin, options)时，Cordis 做的第一件事不是执行插件，而是解析依赖。它会读取插件的inject声明，检查当前 Context 及其祖先链上是否已经提供了这些服务。如果依赖缺失，插件会被挂起，Fiber 状态为pending，等待依赖注册后再自动激活。

这个“等待”机制是 Cordis 区别于普通 DI 容器的关键。普通容器在依赖缺失时通常直接报错，而 Cordis 允许插件以任意顺序注册，由框架负责编排。这意味着你可以先注册消费方，再注册提供方，只要在应用启动完成前都注册好就行。

// 先注册消费者 ctx.plugin(consumerPlugin) // inject: ['database'] // 后注册提供者 ctx.provide('database', createDatabase()) // 此时 consumerPlugin 自动激活

实操心得：依赖解析是递归的。如果 A 依赖 B，B 依赖 C，而 C 还没注册，那么 A 和 B 都会处于 pending。排查“插件不生效”时，先沿着 inject 链往上找，看最底层的依赖是否缺失。

3.2 阶段二：Context 派生与作用域创建

依赖就绪后，Cordis 会基于当前 Context 创建一个子 Context，作为该插件的运行作用域。这个子 Context 继承父级所有服务，同时预留了插件自己provide的空间。派生过程是浅拷贝加原型链继承，开销很小，但语义很重要：插件内部注册的一切都归属于这个子 Context。

这里有个容易混淆的点：ctx.plugin返回的是 Fiber，不是 Context。如果你想拿到插件的作用域 Context，需要通过fiber.ctx访问。很多新手会写成const childCtx = ctx.plugin(...)，然后发现 childCtx 上没有 provide 方法——因为它根本不是 Context。

3.3 阶段三：apply 执行与副作用注册

这是插件真正“干活”的阶段。Cordis 调用插件的apply方法，传入子 Context 和配置项。插件在这个阶段完成所有副作用注册：监听事件、注册命令、提供 API、启动定时器、加载子插件。

关键约束是：apply 应该是同步的，或者返回一个 Promise 表示异步初始化完成。如果 apply 是异步的，Cordis 会等待 Promise resolve 后才把 Fiber 标记为 active。这意味着你可以在 apply 里做异步的资源加载，比如读取配置文件、连接数据库，但要确保异常被正确捕获，否则 Fiber 会进入 disposed 状态。

export const asyncPlugin = { name: 'async-init', async apply(ctx: Context) { const config = await loadConfig() ctx.provide('config', config) // 异步完成后 Fiber 才 active } }

3.4 阶段四：子插件递归加载

如果插件内部调用了ctx.plugin，Cordis 会为子插件创建新的 Fiber，挂在当前 Fiber 的 children 下。这就形成了一棵 Fiber 树。父 Fiber 销毁时，会递归销毁所有子 Fiber，这就是“级联卸载”的实现方式。

这个机制让插件可以组合成功能包。比如一个“代码审查套件”插件，内部加载了语法检查、风格检查、安全检查三个子插件。卸载套件时，三个子插件自动清理，不需要手动逐个卸载。

3.5 阶段五：就绪事件与激活通知

当整棵 Fiber 树都进入 active 状态后，Cordis 会触发ready事件。这是插件做“启动后初始化”的时机，比如打印日志、注册全局快捷键、开始监听外部输入。注意ready只触发一次，且在所有同步插件加载完成后触发。

3.6 阶段六：销毁与资源回收

调用fiber.dispose()时，Cordis 按后序遍历 Fiber 树：先销毁子 Fiber，再销毁父 Fiber。每个 Fiber 销毁时，会清除该作用域 Context 上的所有监听、定时器、服务注册。如果插件在 apply 时返回了一个清理函数，Cordis 也会调用它。

export function cleanupPlugin(ctx: Context) { const timer = setInterval(() => { /* ... */ }, 1000) return () => clearInterval(timer) // 返回清理函数 }

注意：返回清理函数的写法只对函数式插件有效。对象式插件需要在 apply 内部用ctx.on('dispose', ...)注册清理逻辑。两种方式等价，选一种保持团队统一即可。

4. TypeScript 类型系统在 Cordis 插件中的实战用法

4.1 用声明合并扩展 Context 类型

Cordis 最强大的类型特性是声明合并（Declaration Merging）。当你通过ctx.provide('myService', ...)注册服务后，TypeScript 并不知道ctx.myService存在。你需要通过模块扩展告诉编译器：

declare module 'cordis' { interface Context { myService: MyServiceType } }

这段声明通常放在插件的index.ts或单独的.d.ts文件里。声明之后，所有引用该插件的代码都能获得ctx.myService的类型提示和自动补全。这是 Cordis 插件开发体验的核心——服务即类型，类型即文档。

我建议每个插件都维护一个types.ts，集中存放声明合并和导出的接口类型。这样使用者只需要 import 插件，类型自动生效，不需要额外配置。

4.2 inject 的类型推导与泛型约束

对象式插件的inject数组会影响 apply 中 ctx 的类型。Cordis 的类型定义会根据 inject 列表推导出 ctx 上可用的服务。但这个推导有前提：被注入的服务必须已经在某个地方做了声明合并。如果 inject 了一个未声明的服务，TypeScript 会报错，这其实是好事——它在编译期就帮你发现了依赖声明缺失。

export const plugin = { inject: ['database', 'logger'], apply(ctx) { // ctx.database 和 ctx.logger 都有类型 ctx.database.query('...') } }

4.3 插件配置的类型安全

插件配置通过第二个参数传入，类型由插件自己定义。推荐用泛型约束 apply 的签名：

interface MyPluginOptions { threshold: number mode: 'strict' | 'loose' } export const myPlugin = { name: 'my-plugin', apply(ctx: Context, options: MyPluginOptions) { // options 有完整类型 } }

这样调用ctx.plugin(myPlugin, { threshold: 10, mode: 'strict' })时，TypeScript 会检查配置项。如果传错类型或漏传必填项，编译期就会报错，避免运行时才发现配置问题。

4.4 .d.ts 声明文件的组织策略

对于发布给他人使用的插件包，声明文件的组织很关键。我的做法是：

• src/index.ts：插件主逻辑，包含声明合并
• src/types.ts：导出的接口、类型别名
• package.json的types字段指向dist/index.d.ts

如果插件包有多个入口（比如核心插件和可选插件分开导出），用typesVersions字段做路径映射。这样使用者import { corePlugin } from 'my-package'和import { optionalPlugin } from 'my-package/optional'都能获得正确的类型。

踩坑记录：声明合并必须在使用者的编译单元内可见。如果插件包的.d.ts没有被 tsconfig 的include覆盖，声明合并不会生效，ctx 上就没有服务类型。解决办法是在插件的package.json里正确配置types，并确保使用者通过模块导入而非相对路径引用。

5. 手把手实现一个 Cordis 插件：从零到可运行

5.1 环境准备与项目初始化

先确认 Harness 的版本和 Cordis 的版本匹配。Cordis 的 API 在不同大版本间有变化，尤其是 Context 的派生方法和 Fiber 的访问方式。我用的组合是 Harness 最新稳定版加 Cordis 对应版本，通过npm ls cordis确认实际安装的版本。

mkdir harness-plugin-demo && cd harness-plugin-demo npm init -y npm install cordis typescript @types/node --save-dev npx tsc --init

tsconfig 需要开启experimentalDecorators（如果用到装饰器）和strict。模块系统建议用ESNext或NodeNext，Cordis 对 ESM 支持良好。

5.2 编写插件骨架与声明合并

创建一个“消息长度守卫”插件，功能是监听对话消息，超过阈值时触发警告事件。先写类型声明：

// src/types.ts import 'cordis' declare module 'cordis' { interface Context { lengthGuard: { threshold: number check: (msg: string) => boolean } } interface Events { 'length-warning': (msg: string, length: number) => void } }

这里同时扩展了Context和Events。Events的扩展让ctx.emit('length-warning', ...)和ctx.on('length-warning', ...)都有类型检查，避免事件名拼写错误。

5.3 实现 apply 逻辑与事件注册

// src/index.ts import { Context } from 'cordis' import './types' export interface LengthGuardOptions { threshold?: number } export const lengthGuard = { name: 'length-guard', apply(ctx: Context, options: LengthGuardOptions = {}) { const threshold = options.threshold ?? 500 ctx.provide('lengthGuard', { threshold, check: (msg: string) => msg.length > threshold, }) ctx.on('message', (msg: string) => { if (msg.length > threshold) { ctx.emit('length-warning', msg, msg.length) } }) ctx.on('dispose', () => { // 清理逻辑，如果有外部资源需要释放 }) }, }

注意ctx.provide注册的服务会自动挂到当前 Fiber 的作用域 Context 上。其他插件通过inject: ['lengthGuard']就能拿到这个服务。

5.4 注册插件并验证加载状态

// src/main.ts import { Context } from 'cordis' import { lengthGuard } from './index' const app = new Context() app.plugin(lengthGuard, { threshold: 100 }) app.on('ready', () => { console.log('插件加载完成') for (const fiber of app.registry.values()) { console.log(`Fiber: ${fiber.name}, 状态: ${fiber.state}`) } }) app.emit('message', '这是一条很长的消息...'.repeat(20))

运行后应该能看到 Fiber 状态为 active，并且 length-warning 事件被触发。如果状态是 pending，检查是否有未满足的 inject 依赖；如果是 disposed，检查 apply 里是否抛了异常。

5.5 参数计算与阈值选择经验

阈值设多少合适？这取决于你的使用场景。对话消息的 token 数和字符数不是线性关系，中文大约 1 字符对应 0.6 到 1 个 token，英文大约 4 字符对应 1 个 token。如果阈值是为了控制上下文长度，建议按 token 估算再乘以安全系数。

我的经验值是：如果模型上下文窗口是 8K token，留给历史消息的预算大约是 60%，即 4.8K token。按中文估算约 5000 到 8000 字符。设阈值时取偏小值，比如 5000 字符，留出余量给系统提示词和工具调用结果。

6. 插件调试与常见故障排查实录

6.1 插件不生效的五种典型原因

6.2 用诊断插件打印 Fiber 树

写一个通用的诊断插件，在开发环境自动加载：

export function fiberDiagnose(ctx: Context) { ctx.on('ready', () => { const print = (fiber: any, depth = 0) => { const indent = ' '.repeat(depth) console.log(`${indent}${fiber.name} [${fiber.state}]`) for (const child of fiber.children) { print(child, depth + 1) } } for (const fiber of ctx.registry.values()) { if (!fiber.parent) print(fiber) } }) }

这个输出能直观展示插件的层级关系和加载状态。我把它放在所有插件的最后注册，确保能捕获完整的 Fiber 树。

6.3 热重载场景下的状态残留问题

开发时经常需要热重载插件。如果直接重新ctx.plugin，旧的 Fiber 不会被自动销毁，会导致重复监听和内存泄漏。正确做法是先 dispose 旧 Fiber，再注册新的：

let currentFiber: Fiber | null = null function reload(ctx: Context) { currentFiber?.dispose() currentFiber = ctx.plugin(myPlugin) }

Cordis 的ctx.registry是 Map 结构，key 是 Fiber ID。你也可以通过遍历 registry 找到同名 Fiber 并 dispose，实现按名称重载。

6.4 异步初始化的竞态问题

如果插件 A 和插件 B 都依赖服务 C，而 C 是异步提供的，可能出现 A 先于 C 就绪的情况。Cordis 的 inject 机制会等待 C 注册后才激活 A，但如果 C 的 provide 发生在异步回调里，inject 无法感知。解决办法是用ctx.inject包裹异步逻辑：

ctx.inject(['config'], async (ctx) => { const data = await loadAsyncConfig() ctx.provide('config', data) })

这样 config 的 provide 发生在 inject 回调内，依赖 config 的插件会正确等待。

7. 插件组合与架构扩展的进阶思路

7.1 用 reusable 标记可复用插件

Cordis 支持reusable标记，允许同一个插件被多次加载，每次生成独立的 Fiber。默认情况下，同名插件重复加载会被忽略。如果你的插件设计成可配置的多实例（比如多个不同阈值的守卫），需要显式声明：

export const guard = { name: 'guard', reusable: true, apply(ctx, options) { /* ... */ } }

加载时用ctx.plugin(guard, { threshold: 100 })和ctx.plugin(guard, { threshold: 200 })会创建两个独立 Fiber，各自维护状态。

7.2 插件间的通信模式

插件之间不应该直接 import 对方的内部模块，而应该通过 Context 服务通信。提供方ctx.provide('serviceName', api)，消费方inject: ['serviceName']。这种松耦合让插件可以独立替换和测试。

如果通信是双向的，可以用事件。提供方ctx.emit('service-event', data)，消费方ctx.on('service-event', handler)。事件的类型通过 Events 声明合并来保证。

7.3 把多个插件打包成功能套件

一个套件插件本质上是一个父插件，在 apply 里加载多个子插件：

export const codeReviewSuite = { name: 'code-review-suite', apply(ctx: Context) { ctx.plugin(syntaxCheck) ctx.plugin(styleCheck) ctx.plugin(securityCheck) } }

卸载套件时，三个子插件级联销毁。套件可以暴露统一的配置接口，在 apply 里分发给子插件。这种模式适合把一组相关能力打包发布，使用者只需要加载一个插件。

7.4 与 Harness 主流程的集成点

Harness 在对话流程中暴露了多个扩展点：消息预处理、上下文组装、工具调用前后、结果后处理。Cordis 插件通过监听对应事件接入这些扩展点。具体事件名需要查阅 Harness 的 Events 声明，不同版本可能有差异。

我的做法是写一个“事件探针”插件，在开发阶段打印所有触发的事件名和参数，快速摸清可用的扩展点。这个探针插件本身也是用 Cordis 写的，监听通配符事件（如果框架支持）或逐个注册已知事件。

8. 离线与局域网环境下的插件部署要点

8.1 依赖打包与离线安装

在离线环境部署 Harness 插件，需要提前把所有依赖打包。用npm pack生成 tarball，或者用npm install --production后整体拷贝 node_modules。注意 Cordis 本身也是依赖，要一并打包。

如果插件依赖原生模块（比如某些数据库驱动），需要确保目标环境的 Node 版本和架构匹配。我一般会在目标环境先跑一个最小验证脚本，确认 Cordis 能正常加载，再部署完整插件。

8.2 插件配置的外部化

离线环境不方便改代码，配置应该外部化。Cordis 插件可以通过环境变量或配置文件读取参数。推荐用ctx.provide('config', loadConfigFromFile())的方式，把配置加载做成一个独立插件，其他插件 inject 它。

配置文件格式用 JSON 或 YAML 都行，关键是加载失败时要有合理的默认值，不能让整个应用起不来。我的做法是配置加载插件永远不抛异常，缺失的配置项用默认值填充，同时 emit 一个警告事件。

8.3 版本兼容性检查

Harness 和 Cordis 的版本升级可能引入破坏性变更。在插件包的package.json里用peerDependencies声明兼容的 Cordis 版本范围，安装时 npm 会检查。如果目标环境已经装了不兼容的版本，安装会失败并提示，避免运行时才发现问题。

{ "peerDependencies": { "cordis": "^2.0.0" } }

实操心得：离线环境升级插件时，先备份旧的 node_modules 和配置文件。新版本加载失败可以快速回退。我一般会保留最近两个版本的插件包，出问题直接切换。

9. 我踩过的那些坑与最终沉淀下来的经验

第一个坑是在 apply 里直接访问未声明的服务。TypeScript 编译能过，因为声明合并让 ctx 上有了类型，但运行时服务可能还没注册。Cordis 不会在访问时抛错，而是返回 undefined，导致后续逻辑静默失败。后来我养成了习惯：所有服务访问前先检查，或者用 inject 确保依赖就绪。

第二个坑是事件监听的重复注册。热重载时旧 Fiber 没销毁，新 Fiber 又注册了一遍监听，导致一个事件触发两次处理。排查时用诊断插件打印 Fiber 树，发现有两个同名 Fiber 同时 active。解决办法是重载前先 dispose 旧 Fiber。

第三个坑是异步 apply 的异常处理。apply 返回的 Promise reject 时，Cordis 会把 Fiber 标记为 disposed，但错误信息可能被吞掉。需要在 apply 内部 try-catch，把错误 emit 出来或者记录到日志，否则排查时只能看到“插件没加载”，不知道具体原因。

第四个坑是声明合并的作用域问题。插件包的.d.ts如果没被使用者的 tsconfig include，声明合并不生效，ctx 上就没有服务类型。解决办法是在插件包的package.json里正确配置types字段，并确保使用者通过模块导入而非相对路径引用。

沉淀下来的经验就几条：插件保持单一职责，一个插件只做一件事；依赖通过 inject 声明，不要隐式依赖；清理逻辑一定要写，哪怕现在看起来不需要；诊断插件是开发必备，能省下大量排查时间；配置外部化，离线环境尤其重要。

这套 Cordis 插件架构用下来，最大的感受是它把“可组合”这件事做得很彻底。插件之间通过 Context 解耦，通过 Fiber 管理生命周期，通过 inject 编排依赖。刚开始会觉得概念多、绕，但一旦理解了 Context 派生和 Fiber 树这两个核心机制，后面写插件就是套模板。我现在写一个新插件，从骨架到可运行大概二十分钟，大部分时间花在业务逻辑上，架构层面的东西 Cordis 已经兜住了。