Cordis仓库：https://github.com/cordiverse/cordis
Koishi官网：https://koishi.chat/zh-CN/
DeepSeek技术预览 ：Cordis入门
相关论文：《A Programming Paradigm for Spatiotemporal Composability》
一、什么是 Cordis
Cordis （拉丁语意为"心"）是一个元框架（Meta Framework） ------即"用于构建框架的框架"。它不耦合任何具体业务领域，只专注于解决一个核心问题：如何让软件的各个组件可以安全地组合、热插拔，并在卸载时完整逆转其所有副作用。
Cordis 最初从知名的聊天机器人框架 Koishi 中抽离出来，作为其底层插件系统独立发展。2025 年起，它因被 DeepSeek Harness（深度求索发布的 AI Agent 运行框架）采用而进入更广泛的开发者视野。2026 年 8 月，北京大学与 DeepSeek-AI 联合发表论文《A Programming Paradigm for Spatiotemporal Composability》，为 Cordis 的设计建立了形式化模型，将其核心理念概括为"时空可组合性"。
二、起源：从 Koishi 到通用元框架
Koishi 是一个支持多平台（QQ、微信、飞书、Telegram 等）的聊天机器人框架，其核心设计哲学是"插件即一切"------所有功能都通过插件实现，且支持运行时热更新。随着 Koishi 的发展，其插件系统逐渐成熟为一个与具体聊天场景无关的通用基础设施。
开发者意识到，这套插件系统所解决的问题------依赖管理、生命周期控制、副作用追踪与回滚------是几乎所有复杂软件系统都会面临的共性挑战。于是，他们将这部分能力从 Koishi 中剥离，形成了独立的 Cordis 项目，目标是"成为未来软件的心脏"。
三、核心理念：时空可组合性
Cordis 的设计哲学可以浓缩为两个词：时间可组合性（Temporal Composability）与空间可组合性（Spatial Composability）。
3.1 时间可组合性：副作用必须可逆
传统软件架构中，组件安装后往往难以干净地卸载。一个模块可能注册了事件监听器、打开了文件句柄、修改了全局状态，当它被移除时，这些副作用常常残留，导致内存泄漏、状态污染甚至系统崩溃。
Cordis 要求：任何组件在撤出时，必须能够完整逆转其产生的所有副作用。这通过以下机制实现：
- 可逆副作用（Reversible Effects） ：所有副作用操作（如
ctx.on()注册事件监听、ctx.effect()注册自定义资源）都会返回一个撤销函数（disposer）。Cordis 内部维护一个副作用栈，当插件被卸载时，自动按逆序调用所有 disposer。 - 事务化加载：配置更新时，Cordis 会尝试原子性地加载新配置。如果任何步骤失败，整个事务回滚，系统状态保持一致，不会出现"装了一半"的残局。
- Fiber 状态机 ：每个插件拥有独立的生命周期状态机（
PENDING → LOADING → ACTIVE → DISPOSED），确保状态转换的确定性。
这种设计使得 Cordis 系统可以长期运行而无需重启。据作者分享，基于 Cordis 构建的 Koishi 服务在三年间经历了无数次插件更新，进程从未重启。
3.2 空间可组合性：依赖必须声明
复杂系统中，组件之间存在大量隐式依赖。A 模块依赖 B 模块的某个功能，但如果没有显式声明，系统无法知道 B 必须在 A 之前加载，也无法在 B 不可用时优雅地处理 A 的行为。
Cordis 要求：任何组件必须显式声明其依赖的服务，系统据此自动编排加载顺序。
- 依赖注入（Dependency Injection） ：插件通过
inject属性声明所需服务（如inject: ['tools', 'llm']）。Cordis 会等待这些服务就绪后，才启动该插件。 - 服务隔离（Service Isolation）：可以为特定服务创建隔离上下文，使得上下文内外的插件无法相互感知。这在多租户场景或沙箱环境中尤为重要。
四、五大核心概念
根据 DeepSeek Harness 官方文档，使用 Cordis 需要理解五个核心概念：
4.1 插件（Plugin）
插件是实现 Service 接口的对象。它可以是：
- 一个带有
inject属性和apply(ctx)方法的函数 - 一个继承自
Service的类
插件是 Cordis 中功能的最小单元，所有能力都由插件提供。
4.2 上下文（Context）
上下文是服务的容器。每个服务占据一个稳定的上下文键，如 ctx.tools、ctx.llm、ctx.database。上下文提供了统一的命名空间，避免了全局污染。
4.3 依赖注入（inject）
插件通过 inject 声明所需服务。例如：
typescript
const myPlugin = {
inject: ['llm', 'tools'],
apply(ctx) {
// 此时 ctx.llm 和 ctx.tools 已保证可用
ctx.llm.chat(...)
}
}Cordis 会自动解析依赖图，确保服务按正确顺序加载。这消除了手动编排的繁琐和易错性。
4.4 类型化事件
Cordis 提供了强类型的事件系统，支持四种分发模式：
- emit：广播事件，不等待回调
- waterfall：瀑布式传递，每个监听器可以修改事件参数
- parallel：并行调用所有监听器
- serial：串行调用，前一个完成后才调用下一个
所有事件都通过 ctx.on() 注册，因此天然享受可逆副作用的保障------插件卸载时，所有事件监听自动移除。
4.5 可逆副作用
这是 Cordis 最独特的设计。任何副作用操作都通过上下文注册：
typescript
ctx.on('message', handler) // 事件监听
ctx.effect(() => { // 自定义副作用
const conn = createConnection()
return () => conn.close() // 返回 disposer
})当插件被卸载或重载时，Cordis 自动调用所有 disposer，确保资源完全释放。
五、技术架构
Cordis 的核心实现极为精简，约 2000 行 TypeScript 代码，主要包含以下模块：
| 模块 | 职责 |
|---|---|
| Service | 定义命名的上下文键，支持 provide（提供服务）与 consume（消费服务） |
| Fiber | 管理插件生命周期，处理状态转换与错误恢复 |
| Effect | 副作用注册与撤销管理，维护副作用栈 |
| Events | 类型化事件系统，支持多种分发策略 |
| Config | 增量配置加载与热模块替换（HMR），支持事务化回滚 |
这种精简性意味着 Cordis 的心智负担很低。开发者不需要学习庞大的 API，只需理解"插件-上下文-副作用"这一核心三角即可。
六、应用案例：DeepSeek Harness
Cordis 最具代表性的应用是 DeepSeek Harness，这是 DeepSeek 发布的 AI Agent 运行框架。Harness 采用"一切皆插件"的架构：
- 模型（Model） 、工具（Tool） 、技能（Skill） 、会话（Session） 、沙箱（Sandbox） 、存储（Storage） 、循环（Loop） 、调度（Schedule） 、UI 等所有 Agent 能力，均为 Cordis 插件。
- 开发者可以独立替换或扩展任一能力，无需改动 Harness 源码。
- 沙箱、远程渠道（QQ、微信、飞书、Telegram）等也是可插拔组件。
这种架构使得 Harness 具有极高的可定制性 和可维护性。研究团队可以专注于算法插件的开发，而无需关心底层生命周期管理；运维团队可以在运行时热更新插件，而无需重启整个 Agent 服务。
七、总结
Cordis 框架的核心价值在于，它将插件系统从传统的"能装不能卸"的静态模式，进化为可热插拔、副作用可逆、依赖可声明的动态模式。其"时空可组合性"的设计哲学，为构建长期运行、频繁更新、组件高度解耦的复杂系统提供了坚实的理论基础和技术实现。
无论是聊天机器人、AI Agent 运行时，还是任何需要模块化、可扩展架构的软件系统，Cordis 都提供了一个值得深入研究的范式。