Cordis框架: 为可逆软件系统而生的元框架-Day18

晴天16

613人浏览 · 2026-08-14 23:37:22

晴天16 · 2026-08-14 23:37:22 发布

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 声明所需服务。例如：

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 最独特的设计。任何副作用操作都通过上下文注册：

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）等也是可插拔组件。