Cordis Skill：登顶 GitHub Trending 的 AI Agent 时空可组合性元框架

Cordis 是一个面向 AI Agent 开发者的 TypeScript 元框架，核心解决「时空可组合性」——让插件、服务、事件在复杂智能体系统中以声明式、可复用、可逆向的方式协同工作。今日（2026-08-15）以 4,031 Stars、616 Stars 今日增量登顶 GitHub Trending 全榜，是当前 AI Agent 基础设施层最受关注的新项目之一。

功能与原则

Cordis 的设计哲学是 「一切皆插件，插件即服务」。它将 AI Agent 的各个功能模块（工具链、LLM 流式输出、Agent 协调、会话管理）抽象为统一的可插拔单元，开发者通过声明式 API 定义依赖关系和事件流向，而非手动编排启动顺序或通信协议。

核心原则三条：

• 依赖声明优于手动编排：通过 inject 声明服务依赖，Cordis 自动解析加载顺序
• 事件驱动优于直接调用：模块间通过类型化事件（typed events）通信，支持 emit / waterfall / parallel / serial 四种分发模式
• 副作用可逆：所有注册操作（工具 schema、提示词片段、监听器）均可撤销，reload 和 teardown 时按预期清理

认可度

同组织下还有 cordis/database（类型驱动数据库框架）、cordis/server（HTTP/WebSocket 服务）等配套包，形成了一套完整的基础设施生态。

链接

GitHub：https://github.com/cordiverse/cordis

原作者

项目由 shigma 和 Hieuzest 主导开发（均为 cordiverse 组织核心成员），采用 MIT 许可证。配套论文《A Programming Paradigm for Spatiotemporal Composability》可在 GitHub 获取，为这一编程范式提供了理论支撑。

介绍

传统的 Agent 框架在扩展时往往面临「模块之间强耦合」和「生命周期管理混乱」的问题——每当需要新增一个工具或拦截器，开发者就得手动在多个位置修改代码，且难以保证加载顺序和资源清理的正确性。

Cordis 从根本上重新设计了插件的挂载机制：每个插件都是一个 Service，通过 ctx.inject 声明自己依赖哪些服务，Cordis 会自动等待所有依赖就绪后再启动。服务之间不直接引用，而是通过类型化事件通信——服务 A 发出一条 tools.loaded 事件，服务 B 和服务 C 各自注册监听器做出响应，彼此解耦且顺序清晰。

事件分发支持四种模式：emit（不等待、观察者各自处理）、waterfall（瀑布式，每个监听器可以对结果进行包装后传给下一个）、parallel（所有监听器并行执行）和 serial（监听器按注册顺序逐个执行）。这种设计覆盖了从「记录日志」到「多层策略决策」的全部场景。

此外，所有注册操作都是可逆的副作用——通过 ctx.effect() 或 ctx.on() 安装的组件，在 reload 或 teardown 时会被自动清理。这解决了 Agent 在长周期运行中常见的「内存泄漏」和「状态残留」问题。

特点

• 统一的插件模型：工具、LLM、Agent 协调器、会话管理器全部是 Service，共享同一套生命周期管理
• 声明式依赖注入：inject 字段声明服务依赖，Cordis 自动解析加载拓扑，无需手动编排启动顺序
• 类型化事件系统：事件名通过 TypeScript 声明合并注册，编译期检查，运行时提供 emit / waterfall / parallel / serial 四种分发语义
• 可逆副作用：所有注册均生成 disposer，reload / teardown 时自动清理，避免资源泄漏
• 多分发模式：覆盖观察（emit）、包装（waterfall）、并行（parallel）、串行（serial）四种事件处理范式
• 与 DeepSeek Harness 深度集成：Cordis 是 DeepSeek Harness 的底层插件框架，有完整文档和教程

使用方法

Cordis 目前主要面向框架开发者，典型接入方式如下：

安装

npm install @cordis/core
# 或使用 yarn / pnpm
yarn add @cordis/core

定义一个 Service（插件）

import { Service } from '@cordis/core'

// 定义事件（TypeScript 声明合并）
declare module '@cordis/core' {
  interface Events {
    'tools:loaded': { tools: string[] }
  }
}

class MyToolsService extends Service {
  // 声明依赖：等待 ctx.tools 就绪后才启动
  static inject = ['tools'] as const

  // 应用到上下文
  async apply(ctx: Context) {
    ctx.on('tools:loaded', (args, next) => {
      console.log('tools loaded:', args.tools)
      return next() // waterfall 模式，传递给下一个监听器
    })
  }
}

// 挂载到 Agent 上下文
ctx.plugin(new MyToolsService())

核心 API 速查

使用场景与人群

适用场景：

• 构建需要多种工具/拦截器协同的 AI Agent（如同时接入 RAG、MCP 工具、代码执行器）
• 开发 Agent 框架或中间件，需要统一生命周期管理
• 需要在 Agent 运行过程中动态加载/卸载插件
• 基于 DeepSeek Harness 的定制化 Agent 开发

目标用户：

• AI Agent 框架开发者
• 需要构建复杂多模块 Agent 系统的工程师
• 对插件化架构有兴趣的 TypeScript 开发者

输入与输出案例

案例 1：工具加载与日志记录

// 输入：Agent 启动时加载多个工具
ctx.plugin(new ToolsPlugin(['search', 'code-exec', 'web-scrape']))

// Cordis 内部发出事件
ctx.waterfall('tools:loaded', { tools: ['search', 'code-exec', 'web-scrape'] })

// 输出：日志插件拦截并打印
// → [LOG] tools loaded: search, code-exec, web-scrape
// → [VERIFY] tools count: 3, all valid

案例 2：策略决策的瀑布流

// 输入：用户请求穿越一个安全检查
ctx.waterfall('security:check', { userId: 'u123', action: 'delete_resource' })

// 监听器 1（安全插件）：检查黑名单
const blockIfNeeded = async (args, next) => {
  if (await isBlacklisted(args.userId)) return { blocked: true, reason: 'blacklist' }
  return next() // 继续传给下一个
}

// 监听器 2（权限插件）：检查资源权限
const checkPermission = async (args, next) => {
  const permitted = await hasPermission(args.userId, args.action)
  if (!permitted) return { blocked: true, reason: 'no_permission' }
  return next()
}

// 监听器 3（审计插件）：记录操作
const auditLog = async (args, next) => {
  await saveAuditLog(args)
  return next()
}

// 输出：瀑布流层层传递，最终返回 { blocked: false }

GitHub: https://github.com/cordiverse/cordis