Cordis：时空可组合性的元框架

Mon, 17 Aug 2026 00:00:00 +0000

今天 GitHub Trending 榜单第一名的项目是 cordiverse/cordis，一个 TypeScript 编写的元框架，主打"时空可组合性"（Spatiotemporal Composability）。截至发稿，该项目已获得 5,222 stars，今日新增 720 stars，281 forks，采用 MIT 许可证。

Cordis 是什么？

Cordis 是一个元框架——不是用来写应用的框架，而是用来写框架的框架。它的核心理念是将经典的 effect（副作用）和 coeffect（协效）概念从编译时类型系统提升为运行时机制，从而为动态组合提供正式的理论基础。

该项目由 shigma 等开发者维护，已有 550+ 次提交，最早的提交可追溯到 2022 年 5 月。目前 Cordis 处于活跃开发阶段，API 尚未稳定，但已被 DeepSeek Harness 以 vendor 方式引入作为底层插件框架。

论文地址：A Programming Paradigm for Spatiotemporal Composability（2026 年 8 月 13 日草稿）

核心理论：时空两个维度

论文提出了动态组合问题的两个正交维度：

时间可组合性（Temporal Composability）

组件被移除时，其所有副作用可以完全撤销。Cordis 通过可逆效应（Revertible Effects）实现——每一次上下文变换都携带一个逆操作，由运行时跟踪。

空间可组合性（Spatial Composability）

组件可以声明并响应式管理彼此之间的依赖关系。Cordis 通过响应式协效（Reactive Coeffects）实现——上下文的每次变更都会根据组件的协效规格通知相关组件。

这两种机制被统一到一个单一的上下文类型（Context Type）中，构成了一种编程范式。

五个核心概念

从实践角度看，Cordis 的设计围绕五个关键概念：

1. 插件是实现 Service 的对象

插件可以是一个带有可选 inject 和 apply(ctx) 字段的函数，也可以是一个 Service 子类。其生命周期由 Cordis 挂载到当前上下文中管理。

import type { Context } from '@deepseek-ai/cordis'

// 函数式插件
function myPlugin(ctx: Context) {
  // 插件逻辑
  ctx.effect(() => {
    console.log('插件启动')
    return () => console.log('插件卸载') // disposer
  })
}

2. 上下文是服务的容器

一个服务占据一个稳定的 ctx.<key>（如 ctx.tools、ctx.llm、ctx.sessions）。其他插件通过 key 查找服务，而非导入具体实现。这实现了松耦合。

3. 通过 `inject` 声明服务依赖

插件声明所需的服务后，会等待这些服务就绪才启动。加载顺序通过服务依赖自动推导，而非手动编排启动序列。

function myPlugin(ctx: Context, config: Config) {
  // 通过 inject 声明依赖
  ctx.effect(() => {
    const result = ctx.someService.doSomething()
    return () => ctx.someService.cleanup()
  })
}

myPlugin.inject = ['someService'] // 等待 someService 就绪

4. 类型化事件用于通信

服务通过 TypeScript 声明合并注册事件名，然后以不同模式分发：

模式	是否 await	分发顺序	是否有返回值
`emit`	否	注册顺序	否
`waterfall`	否	注册顺序	是
`parallel`	是	并行	否
`serial`	是	注册顺序	是

Waterfall 模式特别值得一提：它是一种环绕中间件模式。监听器接收 (...args, next)，调用 next() 会执行下游监听器，下游返回值通过 next() 返回当前包装层。不调用 next() 则短路——这对于单决策事件是设计意图。

// Waterfall 示例：拦截式中间件
ctx.on('my-event', (data, next) => {
  console.log('前置处理')
  const result = next(data) // 委托下游
  console.log('后置处理')
  return result
})

5. 注册是可逆的副作用

提示词片段、工具 schema、适配器、提供方和监听器通过 ctx.effect() 或 ctx.on() 安装，在 reload 和 teardown 时会按预期撤销。每个注册都应有对应的 disposer（资源释放函数）。

实际应用：DeepSeek Harness

Cordis 目前最引人注目的应用是 DeepSeek Harness——一个 Agent 开发框架。在 DeepSeek Harness 中，每项能力（工具、LLM 适配器、文件访问、agent loop 本身）都是挂载到共享上下文中的插件。

教程体系

DeepSeek Harness 提供了一个逐步实践的 Cordis 教程，共 7 章：

你的第一个插件 — 插件是函数，由 loader 挂载
生命周期与 effect — Cordis 管理的注册会在卸载时撤销
服务 — 在 ctx 上公开能力，通过 inject 依赖
事件 — 类型化事件、广播分发和 waterfall 短路行为
配置 — 读取 YAML 中经过校验的配置
组合与 HMR — 配置文件作为插件树，热模块替换
进入 harness — 基于真实服务注册可由模型调用的工具

快速开始

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

# 创建临时目录
mkdir -p tmp/cordis-tutorial
cd tmp/cordis-tutorial

# 运行启动器
node --import tsx ../../vendor/cordis/bin.js

这个单文件启动器会创建根 Context、挂载 Loader 插件，并从当前目录加载 ./cordis.yml 配置。所有插件和配置都来自你编写的 YAML 文件，--import tsx 让 Node 无需构建步骤即可运行 TypeScript。

架构设计亮点

配置协调（Configuration Reconciliation）

Cordis 的声明式组件加载器支持配置协调和热模块替换（HMR）。@deepseek-ai/cordis-plugin-include 插件将 !!js 解析为表达式节点，基于插件上下文插值配置，并在每次挂载决策时基于 loader 上下文插值 disabled 字段。

实践规则

Cordis 团队推荐以下实践：

将行为封装为插件：工具流水线事件属于 ctx.tools，模型流式输出属于 ctx.llm，Agent 协调属于 ctx.agents
拦截和策略优先使用事件；直接能力调用优先使用服务方法
每个注册都应有对应的 disposer：从 ctx.effect() 返回，或使用辅助方法自动处理
teardown 顺序有要求时，将相关工作放在同一个 effect 中

为什么值得关注？

理论与实践结合

Cordis 不是一个简单的插件系统，它有完整的形式化理论支撑。论文从 effect/coeffect 类型论出发，建立了可逆效应和响应式协效的元理论，再将其统一为上下文类型。这种从理论到实现的完整闭环在开源项目中相当罕见。

AI Agent 时代的底座

随着 AI Agent 系统越来越复杂，“动态组合"成为核心需求——插件需要随时加载/卸载，组件之间需要声明依赖，副作用需要可靠撤销。Cordis 正是为这种场景设计的。

DeepSeek 生态背书

被 DeepSeek Harness 采用作为底层框架，意味着 Cordis 已经在大型生产级 AI Agent 系统中得到了验证。

项目信息

属性	值
仓库	cordiverse/cordis
语言	TypeScript
Stars	5,222 (+720 today)
Forks	281
许可证	MIT
论文	A Programming Paradigm for Spatiotemporal Composability
文档	Cordis Primer
教程	Cordis Tutorial
状态	活跃开发中，API 未稳定

本文基于 2026-08-17 GitHub Trending 数据生成。Cordis 处于早期开发阶段，API 可能发生变化，请以官方仓库为准。

Cordis on AI