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

我第一次接触 DeepSeek Harness 的插件体系，是因为一个很具体的需求：我想在 Harness 的对话流程里插入一个自定义的提示词预处理环节，把用户输入里的口语化表达先做一轮归一化，再交给后面的模型。当时想得很简单，写个函数挂上去就行，结果发现 Harness 的扩展点并不是"随便挂个回调"那么随意，它背后是一套完整的 Cordis 插件架构在支撑。

如果你也在做 Agent 相关的开发，或者正在研究 DeepSeek Harness 怎么接入自己的工具、怎么改提示词流程、怎么在离线环境里跑一套可控的智能体，那这套插件架构值得花时间吃透。它不是一个"配置项"，而是一套依赖注入 + 生命周期管理 + 服务注册的组合拳，理解了它，你就能把 Harness 从一个"能用的工具"改造成"贴合自己业务的工作台"。

Cordis 这个名字在社区里经常和 Harness 一起出现，很多人第一次看到会以为是某个新框架，其实它更像是 Harness 内部的一套插件运行时。它的核心思路和 TypeScript 生态里常见的依赖注入容器有相似之处，但针对 Agent 场景做了不少取舍。我踩过的坑主要集中在三个地方：插件注册时机不对导致服务拿不到、类型声明文件写错导致编译过但运行时报错、以及插件之间的依赖顺序没理清导致初始化顺序混乱。这篇文章就把这些问题拆开讲，顺带把 Cordis 的设计逻辑、实操步骤、排查技巧都过一遍。

适合读这篇的人大概分三类：一是想给 DeepSeek Harness 写实用插件但不知道从哪下手的开发者；二是正在搭 AI Agent、想参考一套成熟插件架构的工程师；三是面试里被问到 TypeScript 依赖注入、Agent 框架编排这类问题、想找个真实案例来理解的求职者。不管你是哪一类，下面的内容都会尽量落到"能直接抄"的层面。

2. Cordis 插件架构的整体设计与选型逻辑

2.1 为什么 Harness 不直接用现成的 DI 框架

TypeScript 生态里做依赖注入的库不少，比较有名的有 InversifyJS、tsyringe、Awilix 这些。它们功能都很全，装饰器、作用域、循环依赖检测一应俱全。但 Harness 没有直接拿来用，而是自己搞了一套 Cordis，这里面有几个很实际的考量。

第一是体积和启动速度。Harness 本身是一个要频繁启动、频繁加载插件的工具，如果引入一个功能大而全的 DI 框架，冷启动时反射元数据的解析会拖慢整体响应。Cordis 走的是更轻的路线，它不依赖reflect-metadata那套装饰器元数据机制，而是用显式的服务注册和声明来建立依赖关系。代价是写起来稍微啰嗦一点，但换来的是启动快、可预测。

第二是生命周期要和 Agent 场景对齐。普通的 DI 框架管的是"对象创建和销毁"，但 Agent 场景里插件要做的事情更复杂：有的插件要在对话开始前初始化上下文，有的要在每轮推理后做后处理，有的要注册工具供模型调用。这些不是简单的构造/析构能覆盖的，需要一套更贴近"阶段"的生命周期钩子。Cordis 把插件的生命周期拆成了几个明确的阶段，让插件作者能精确控制自己在什么时候做什么事。

第三是类型安全要贯穿始终。Harness 是 TypeScript 写的，插件体系自然也要享受类型系统的好处。Cordis 的设计里，服务接口是通过类型声明来约束的，插件消费某个服务时，编译器能直接告诉你这个服务提供了哪些方法、参数是什么。这一点在插件数量多了之后特别重要，否则你根本记不住每个服务长什么样。

提示：如果你之前用过 NestJS 那套 DI，刚接触 Cordis 会觉得"怎么这么朴素"。别急着下结论，等你看完生命周期那部分，会发现朴素是有意为之的。

2.2 核心概念：服务、插件、上下文三件套

Cordis 的模型其实就三个核心概念，理清了这三个，剩下的都是细节。

服务（Service）是能力的载体。一个服务就是一个对象，它暴露一组方法供别人调用。比如 Harness 里可能有一个"模型调用服务"，提供chat()方法；有一个"工具注册服务"，提供registerTool()方法。服务是插件之间协作的接口，插件不直接互相引用，而是通过服务来通信。

插件（Plugin）是功能的封装单元。一个插件可以注册服务、消费服务、注册生命周期钩子。插件是独立可装卸的，你装上它就有这个功能，卸掉它功能就消失，不会留下残留。这个特性在调试时特别有用，你可以通过禁用某个插件来快速定位问题是不是它引起的。

上下文（Context）是插件运行时的"环境句柄"。插件在初始化时会拿到一个 context 对象，通过它来访问其他服务、注册自己的服务、挂载生命周期钩子。context 是 Cordis 里最核心的抽象，你可以把它理解成"插件能看到的整个世界"。

这三者的关系可以用一个生活化的类比：服务是"插座"，插件是"电器"，上下文是"电路"。电器通过电路拿到插座的电，电器之间不直接连线。这样任何一个电器坏了或者被拔掉，不会影响其他电器，只要它们不依赖同一个插座。

2.3 依赖注入在这里的具体形态

Cordis 的依赖注入不是通过构造函数参数自动注入的，而是通过显式声明依赖 + 运行时解析。插件在定义时会声明自己需要哪些服务，Cordis 在加载插件时会检查这些服务是否已经注册，如果没注册就等待或者报错。

这种设计的好处是依赖关系是显式可见的。你打开一个插件的定义，一眼就能看出它依赖了什么、提供了什么，不需要去追构造函数或者装饰器。坏处是写起来多几行代码，但对于插件这种需要长期维护、可能由不同人编写的单元来说，显式比隐式更划算。

依赖解析的时机也很关键。Cordis 采用的是惰性解析 + 就绪通知：插件声明依赖后，如果依赖还没就绪，插件会处于"等待"状态，等依赖注册完成后再触发插件的初始化。这就避免了"插件加载顺序不对导致拿不到服务"的问题。我一开始没理解这个机制，手动调整插件加载顺序调了半天，后来才发现根本不需要，Cordis 自己会处理。

2.4 和主流 Agent 框架编排思路的对比

社区里讨论 Agent 框架时，经常拿 LangChain、Dify、CrewAI 这些来对比。它们的编排思路和 Cordis 有本质区别。

LangChain 走的是链式组合，把一个个组件串成 chain，数据在链上流动。这种方式直观，但链一长就难维护，而且组件之间的耦合比较紧。Dify 走的是可视化编排，用拖拽的方式连节点，适合非程序员，但灵活性受限于它提供的节点类型。CrewAI 走的是角色协作，定义几个 agent 角色让它们互相配合，适合模拟团队协作场景。

Cordis 走的是插件化 + 服务总线。它不预设数据怎么流动，而是提供一套机制让插件自己决定怎么协作。这种方式灵活度最高，但对插件作者的要求也最高，你得自己想清楚插件之间的边界。Harness 选择这条路，是因为它要支持的是"一个可被深度定制的 Agent 工作台"，而不是"一个开箱即用的固定流程"。

3. 核心细节解析：插件定义、服务注册与类型声明

3.1 一个最小插件的完整结构

先看一个最小可用的 Cordis 插件长什么样。下面这段代码是基于常见实践整理的，Harness 实际 API 可能略有差异，但结构逻辑是一致的。

import { Context, Service } from 'cordis' // 声明插件依赖的服务 export const inject = ['logger', 'config'] // 插件主体 export function apply(ctx: Context) { // 注册一个自己的服务 const myService = { greet(name: string) { ctx.logger.info(`hello, ${name}`) return `hello, ${name}` } } ctx.set('greeter', myService) // 挂载生命周期钩子 ctx.on('ready', () => { ctx.logger.info('greeter plugin ready') }) }

这段代码里有几个关键点。inject数组声明了这个插件依赖logger和config两个服务，Cordis 会确保这两个服务就绪后才调用apply。apply函数是插件的入口，它接收 context，在里面做服务注册和钩子挂载。ctx.set()用来注册服务，第一个参数是服务名，第二个是服务对象。ctx.on()用来挂载生命周期钩子，ready是其中一个阶段。

看起来很简单，但魔鬼在细节里。比如inject里声明的服务名必须和实际注册的名字完全一致，拼错一个字母就会导致插件一直处于等待状态，而且不会有明显的报错，只会"什么都不发生"。我第一次遇到这个问题时，排查了快一个小时才发现是服务名拼错了。

3.2 服务注册的两种方式和适用场景

Cordis 里注册服务有两种方式，用哪种取决于你的服务是什么性质。

第一种是对象式注册，就是上面例子里的ctx.set('name', obj)。适合无状态或者状态简单的服务，比如工具函数集合、配置读取器。这种服务注册后就是一个普通对象，谁拿到都能用。

第二种是类式注册，用Service基类派生。适合有状态、需要生命周期管理的服务，比如连接池、缓存、会话管理器。类式注册的服务可以定义start()和stop()方法，Cordis 会在合适的时机调用它们。

import { Service } from 'cordis' export class SessionService extends Service { private sessions = new Map<string, Session>() async start() { // 服务启动时的初始化 } async stop() { // 服务停止时的清理 this.sessions.clear() } get(id: string) { return this.sessions.get(id) } }

选哪种方式，我的经验是：只要服务持有需要清理的资源，就用类式。否则用对象式就够了，别为了"看起来规范"而过度设计。我见过有人把所有服务都写成类，结果每个类里都是空荡荡的 start/stop，纯属增加维护负担。

3.3 生命周期钩子的执行顺序与实战意义

Cordis 的生命周期钩子是这套架构里最容易被低估的部分。很多人以为钩子就是"初始化"和"销毁"两个，实际上它拆得更细，每个阶段都有明确的语义。

常见的钩子阶段包括：ready（插件就绪）、beforeChat（对话开始前）、afterChat（对话结束后）、beforeTool（工具调用前）、afterTool（工具调用后）、dispose（插件卸载）。不同阶段对应 Agent 运行的不同时点，插件可以按需挂载。

执行顺序上，Cordis 保证同一阶段的钩子按插件加载顺序执行，不同阶段之间严格串行。这个保证很重要，否则插件之间的行为会变得不可预测。比如两个插件都在beforeChat里修改用户输入，如果顺序不确定，最终结果就不确定。

实战中我常用的一个模式是：在beforeChat里做输入预处理，在afterChat里做输出后处理，在beforeTool里做参数校验，在afterTool里做结果缓存。这样一套下来，插件的职责非常清晰，每个钩子只做一件事。

注意：钩子函数里不要做耗时操作，尤其是同步阻塞的操作。钩子是串行执行的，一个插件卡住会拖慢整个流程。需要耗时处理的，应该丢到异步任务里，钩子里只做触发。

3.4 TypeScript 类型声明文件怎么写才不出错

Harness 是 TypeScript 项目，插件自然也要用 TypeScript 写。这里有个绕不开的话题：类型声明文件（.d.ts）怎么写。很多插件运行时报错，根源都是类型声明和实际实现不一致。

Cordis 的服务是通过名字访问的，TypeScript 默认不知道ctx.greeter是什么类型。要让编译器认识它，需要做模块增强（module augmentation）。具体做法是在一个.d.ts文件里声明 Context 接口的扩展：

import { Context } from 'cordis' declare module 'cordis' { interface Context { greeter: { greet(name: string): string } } }

这样写完之后，任何地方用ctx.greeter.greet()都会有类型提示和检查。关键点是declare module 'cordis'里的模块名必须和实际导入的模块名一致，接口名必须是Context，属性名必须和ctx.set()时用的名字一致。这三处任何一处对不上，类型增强就不生效。

我踩过的一个坑是：把.d.ts文件放在了types文件夹里，但tsconfig.json的include没覆盖到这个文件夹，导致声明文件根本没被加载。编译器不报错，但类型提示全没了。后来把types加进include才解决。所以写完声明文件后，一定要验证一下类型提示是否真的生效，别想当然。

3.5 插件之间的依赖顺序怎么理

插件依赖顺序是新手最容易翻车的地方。假设插件 A 依赖插件 B 提供的服务，那 B 必须先于 A 完成服务注册。Cordis 的惰性解析机制能处理大部分情况，但有两种场景需要手动干预。

第一种是循环依赖。A 依赖 B，B 又依赖 A，Cordis 会检测到并报错。这时候需要把公共部分抽出来做成第三个插件 C，让 A 和 B 都依赖 C。这是标准的解耦手法，但很多人第一反应是"能不能强行打破循环"，我的建议是别，循环依赖是设计问题的信号，硬解只会埋雷。

第二种是初始化顺序敏感。有些插件虽然不直接依赖，但初始化顺序会影响结果。比如一个插件在ready阶段读取配置，另一个插件也在ready阶段写配置，那读的那个必须在写的之后。这种情况 Cordis 不会自动处理，需要显式声明依赖，哪怕只是"顺序依赖"而非"服务依赖"。

4. 实操过程：从零写一个提示词优化插件

4.1 需求拆解与插件边界划定

假设我们要写一个"提示词优化插件"，功能是在用户输入交给模型之前，做一轮口语化归一化和敏感词过滤。这个需求听起来简单，但拆解下来有几个决策点。

第一，这个插件应该挂在哪个生命周期阶段？显然是beforeChat，因为要在对话开始前处理输入。第二，它需不需要注册服务？如果只是自己用，不需要；如果希望别的插件也能调用它的归一化能力，就需要注册成服务。第三，它的配置从哪来？应该从 Harness 的配置服务读取，所以它依赖config服务。

边界划清楚之后，插件的职责就很明确了：读取配置、在beforeChat阶段处理输入、可选地暴露归一化服务。不涉及模型调用、不涉及工具注册、不涉及输出处理。职责单一，后续维护和测试都容易。

4.2 目录结构与文件组织

一个规范的 Cordis 插件，目录结构大概是这样：

prompt-optimizer/ ├── src/ │ ├── index.ts # 插件入口 │ ├── normalizer.ts # 归一化逻辑 │ ├── filter.ts # 过滤逻辑 │ └── types.ts # 类型定义 ├── types/ │ └── cordis.d.ts # 模块增强声明 ├── package.json └── tsconfig.json

index.ts是插件入口，导出apply函数和inject数组。normalizer.ts和filter.ts是纯逻辑模块，不依赖 Cordis，方便单独测试。types.ts放插件自己的类型。types/cordis.d.ts放模块增强声明。

这个结构的好处是逻辑和框架解耦。归一化和过滤是纯函数，可以脱离 Cordis 单独跑测试。只有index.ts和 Cordis 耦合，耦合面越小，出问题的概率越低。

4.3 核心代码实现与参数说明

先写归一化逻辑。口语化归一化的核心是把一些常见的口语表达替换成更规范的表达，比如"咋"换成"怎么"、"啥"换成"什么"。这个映射表可以配置。

// normalizer.ts export interface NormalizeRule { pattern: RegExp replacement: string } export function normalize(text: string, rules: NormalizeRule[]): string { let result = text for (const rule of rules) { result = result.replace(rule.pattern, rule.replacement) } return result }

再写过滤逻辑。敏感词过滤用简单的包含检测就够了，复杂场景可以上 AC 自动机，但插件初期没必要。

// filter.ts export function filter(text: string, words: string[]): { text: string; hit: string[] } { const hit: string[] = [] let result = text for (const word of words) { if (result.includes(word)) { hit.push(word) result = result.replaceAll(word, '*'.repeat(word.length)) } } return { text: result, hit } }

然后是插件入口。这里要注意inject的声明和配置的读取方式。

// index.ts import { Context } from 'cordis' import { normalize, NormalizeRule } from './normalizer' import { filter } from './filter' export const inject = ['config', 'logger'] export function apply(ctx: Context) { const rules: NormalizeRule[] = ctx.config.get('promptOptimizer.rules', []) const sensitiveWords: string[] = ctx.config.get('promptOptimizer.sensitiveWords', []) ctx.on('beforeChat', (payload) => { const original = payload.input const normalized = normalize(original, rules) const { text, hit } = filter(normalized, sensitiveWords) if (hit.length > 0) { ctx.logger.warn(`sensitive words hit: ${hit.join(', ')}`) } payload.input = text }) }

参数说明上，rules是一个数组，每个元素有pattern和replacement。pattern用正则而不是字符串，是为了支持更灵活的匹配，比如"咋"可能出现在"咋样""咋办"里，用正则能精确控制。sensitiveWords是字符串数组，简单直接。

4.4 配置读取与默认值处理

配置读取这块有个细节值得说。ctx.config.get()的第二个参数是默认值，如果配置里没有这一项，就返回默认值。这个设计避免了到处写if (config.xxx)的判断。

但默认值的选择要谨慎。比如rules的默认值，如果给空数组，插件就什么都不做，用户会以为插件没生效。更好的做法是给一组内置的常用规则，让插件开箱即用，用户想改再改。sensitiveWords的默认值则应该是空数组，因为敏感词是业务相关的，内置一组反而可能误伤。

const DEFAULT_RULES: NormalizeRule[] = [ { pattern: /咋/g, replacement: '怎么' }, { pattern: /啥/g, replacement: '什么' }, { pattern: /咋样/g, replacement: '怎么样' } ] const rules = ctx.config.get('promptOptimizer.rules', DEFAULT_RULES)

注意DEFAULT_RULES里/咋样/g要放在/咋/g前面，否则"咋样"会先被"咋"替换成"怎么样"，然后"怎么样"里的"咋"已经没了，结果虽然对，但逻辑上是错的。这种顺序问题在规则多了之后很容易出，建议按 pattern 长度倒序排列。

4.5 插件加载与验证

插件写完之后，怎么加载到 Harness 里？通常是在 Harness 的配置文件里声明插件路径，或者把插件包安装到指定目录。具体方式取决于 Harness 的版本和部署形态，桌面版和命令行版的加载方式可能不同。

加载之后要验证几件事：插件是否真的被加载了（看日志里有没有插件的输出）、beforeChat钩子是否被触发（可以临时加一行日志）、配置是否被正确读取（改一下配置看行为是否变化）。这三步验证下来，基本能确认插件工作正常。

我习惯在插件里加一个ready钩子，输出一行带插件名的日志。这样每次启动 Harness，一眼就能看出哪些插件加载了、哪些没加载。这个习惯帮我省了很多排查时间。

5. 常见问题与排查技巧实录

5.1 插件不生效的排查路径

插件不生效是最常见的问题，原因可能有很多。我整理了一条排查路径，按顺序走基本能定位。

第一步看日志，如果插件加载了，通常会有输出。没有输出就往第二步查。第二步检查inject数组里的服务名，和实际注册的名字逐字对比。第三步确认钩子阶段名，Cordis 的阶段名是固定的，写错了不会报错，只是不触发。第四步检查配置读取，可以在钩子里打印配置值。第五步看有没有异步错误被 Promise 吞掉，加.catch()打印出来。

5.2 类型声明不生效的三种情况

类型声明不生效，表现是ctx.xxx没有类型提示，或者提示成any。三种常见情况：

第一种是声明文件没被tsconfig.json的include覆盖。解决方法是把声明文件所在目录加进include，或者用files显式列出。

第二种是模块名不匹配。declare module 'cordis'里的'cordis'必须和实际import的模块名完全一致。如果实际导入的是'@deepseek/cordis'，声明里也要写这个。

第三种是接口名不对。Cordis 的 Context 接口名就是Context，不能写成IContext或者别的。这个在文档里通常有说明，但容易看漏。

5.3 插件冲突与循环依赖的处理

两个插件都想注册同名服务，Cordis 会报错。这时候要么改服务名，要么让其中一个插件依赖另一个、复用它的服务。改服务名是最简单的，但要想清楚新名字是否合适。复用服务则需要评估两个插件的职责是否真的重叠。

循环依赖前面提过，标准解法是抽公共插件。但还有一种情况是"伪循环依赖"：A 依赖 B 的服务，B 依赖 A 的服务，但两者依赖的是不同的方法。这种情况可以把服务拆成两个，各取所需。拆的时候注意服务的粒度，太细会导致插件数量爆炸，太粗又回到循环依赖。

5.4 性能相关的注意事项

插件多了之后，性能问题会显现。几个注意点：

钩子函数要尽量轻。beforeChat和afterChat是每轮对话都触发的，里面做重活会明显拖慢响应。需要重活的，考虑缓存结果或者异步处理。

服务查找有开销。ctx.xxx每次访问都要走一遍解析，虽然开销不大，但在热路径上频繁访问还是建议缓存到局部变量。

插件加载顺序影响启动时间。依赖链越深，启动越慢。如果启动时间敏感，尽量减少插件间的依赖层级。

提示：如果发现 Harness 启动明显变慢，可以先禁用一半插件，看是否恢复，用二分法快速定位是哪个插件拖慢的。

5.5 离线环境下的插件部署

有些场景需要在离线局域网里跑 Harness，插件部署就成了问题。核心思路是提前把依赖打包好。插件的node_modules要完整，不能依赖运行时下载。如果插件依赖了外部服务，要确保这些服务在局域网内可达，或者用本地实现替代。

我做过一次离线部署，踩的坑是插件里用了某个 npm 包，本地开发时是全局安装的，打包时没带上，到了离线环境就报模块找不到。后来改成把依赖写进package.json的dependencies，用npm install --production装到插件目录里，才解决。所以离线部署前，一定要在干净环境里验证一遍。

6. 插件架构的扩展方向与个人实践体会

Cordis 这套架构的扩展性其实比表面看起来要强。除了常规的功能插件，还可以做几类有意思的扩展。

一类是可观测性插件。挂载在各个生命周期钩子上，记录每轮对话的耗时、工具调用次数、token 消耗等指标，输出到日志或者本地文件。这类插件对调试和优化特别有用，而且不侵入业务逻辑。

另一类是策略插件。比如在beforeTool阶段根据某些条件决定是否拦截工具调用，或者在afterChat阶段根据输出质量决定是否重试。这类插件把"策略"从"实现"里抽出来，让核心逻辑保持干净。

还有一类是适配插件。把 Harness 的服务暴露成其他系统能调用的接口，或者反过来把外部系统的能力包装成 Harness 的服务。这类插件是 Harness 和外部世界之间的桥梁，在集成场景里很有价值。

我自己在实际操作中的体会是，写 Cordis 插件最忌讳的是"什么都想塞进一个插件"。插件的粒度应该和职责对齐，一个插件做一件事，做透。插件之间的协作通过服务来完成，而不是通过插件内部互相调用。这样每个插件都能独立测试、独立替换，整个系统的可维护性会高很多。

另外一个小技巧：给插件写一个README.md，说明它依赖哪些服务、提供哪些服务、挂载哪些钩子、有哪些配置项。插件多了之后，这份文档就是你的"插件地图"，排查问题时能省大量时间。我现在的习惯是，插件写完先写 README，把接口和配置理清楚，再回头检查代码是否和文档一致，往往能发现一些设计上的疏漏。