# Cordis 框架调研 > **归档更正（2026-08-13 下载复核）**：本报告撰写时子代理沙箱禁网，未验证 cordis.io。知识库下载脚本实测：`https://cordis.io/` 返回 **308 永久重定向到自身**（curl 跟随即死循环；`www.`/`http` 变体亦不可达）——该站点当前无法访问或已改址。上游权威以 **GitHub 仓库**（`downloads/github/cordis/`：README、package.json、仓库树、全部 md 文档）+ **DSH vendored 源码**（`vendor/cordis/src/*`）为准；cordis.js.org 是否 301 至 cordis.io 仍标 [unverified]。 > 目标读者：DeepSeek Harness 插件开发者。本文为 Cordis 插件框架（https://github.com/cordiverse/cordis）的基础知识调研，作为 DSH 插件开发的知识底座。 > > 语言约定：中文叙述，保留英文技术术语（`ctx.effect`、`Service`、`Fiber`、`waterfall`、`inject` 等）。 > > 标注约定：每条事实尽量给出**精确 URL**。凡无法通过一手来源（源码 / 官方文档 / 仓库元数据）核实的论断，标注 **[unverified]**。 --- ## 0. 关键结论先行（务必先读） Cordis 存在**两个明显不同的 API 谱系**，调研时必须区分，否则会混淆： | 谱系 | 版本 | 代表 API | 状态 | |---|---|---|---| | **经典 Cordis**（Koishi 时代） | `cordis` v1–v3，`@cordisjs/core` v3 | `ctx.scope`、`ctx.select`、`ctx.using`、`ctx.provide/inject/get/set`、`ctx.effect/on/root/plugin`；`ctx.loader`（`@koishijs/loader`）、`ctx.registry`（`@koishijs/registry`） | 历史版本，npm 上仍可查（`cordis` 1.5.2 / 2.1.1 / 2.3.1，`@cordisjs/core` 3.17.7） | | **Cordis v4（重写版）** | `cordis` 4.x，即 DSH 所 vendored 的版本 | `ctx.effect/on/root/plugin/inject`、`ctx.get/set/provide`、`ctx.extend/isolate/intercept`（取代 `scope/select`）、`ctx.registry`（内置）、`ctx.reflect/fiber/events/logger`、`ctx.mixin/accessor`；`ctx.loader` 来自 `@cordisjs/plugin-loader`（loader 本身已是插件） | 当前上游 master 与 DSH 使用 | **这是本调研最重要的一个事实**：用户问题清单里的 `ctx.scope` 与 `ctx.select/selector` 属于**经典谱系**；DSH 所 vendored 的 v4 已经用 `ctx.extend()` / `ctx.isolate()` / `ctx.intercept()` 取代了它们。`ctx.loader` 在 v4 不再是核心内置，而是 `@cordisjs/plugin-loader` 提供的一个 **Service**（见 §5）。`ctx.registry` 在 v4 变为核心内置（`ctx.registry` 永远存在），不再需要单独安装 registry 包。 - 上游仓库：https://github.com/cordiverse/cordis ，仓库描述为 "Meta-Framework of Spatiotemporal Composability"（时空可组合性的元框架）。作者为 Shigma（Koishi 作者）。 - 上游论文仓库：https://github.com/cordiverse/paper —— "A Programming Paradigm for Spatiotemporal Composability"（《一种时空可组合性的编程范式》）。 - 官方文档站：https://cordis.io/ （当前，v4 API；例如 https://cordis.io/zh-CN/api/core/context.html 、https://cordis.io/zh-CN/api/std/loader.html 、https://cordis.io/zh-CN/guide/starter/config.html ）。经典文档站为 https://koishi.js.org/ （Koishi 文档中的 Context 页，如 https://koishi.js.org/api/core/context.html ）以及更早的 cordis.js.org。 - DSH 对 Cordis 的 vendored 快照与本地文档（一手、权威）： - vendor 源码与同步清单：https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/README.md - 概念入门：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md - API 参考（生成式）：`docs/cordis-api/{context,events,fiber,registry,service,inherited}.md` - 动手教程：`docs/cordis-tutorial/01…07` - 术语表：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/glossary.md --- ## 1. 核心插件范式：一切皆插件（Everything is a Plugin） ### 1.1 为什么“一切皆插件” Cordis 的定义性观点是：**应用完全由插件组合而成**。DSH 的 `AGENTS.md` 第一句即是 "DeepSeek Harness is a plugin-based agent harness on vendored Cordis: **everything is a plugin**"。上游将其提炼为“时空可组合性（Spatiotemporal Composability）”：一个应用 = 若干插件（空间维度，谁和谁并存）在时间轴上的挂载/卸载（时间维度，何时生效）。 由此得到三个推论（见 DSH `docs/cordis-primer.md` 的 “Cordis In Five Ideas”）： 1. **插件是一个实现 Service 的对象**：可以是带 `inject` / `apply(ctx)` 字段的函数，也可以是 `Service` 子类（其生命周期由 Cordis 挂载进当前 context）。 2. **context 是服务的仓库**：服务通过稳定键 `ctx.`（如 `ctx.tools`、`ctx.llm`、`ctx.sessions`）被声明；其它插件**通过键名而非 import 具体实现**来获取服务。 3. **依赖通过 `inject` 声明**：插件列出所需服务，并在这些服务存在前一直等待，因此**加载顺序由服务依赖表达，而非手工 boot 序列**。 这意味着：没有“框架引导代码（bootstrap glue）”——插件只描述它贡献什么，`cordis.yml` 负责组合出整个应用。DSH 教程第一章的表述：“There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application.”（https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-tutorial/01-first-plugin.md） ### 1.2 插件 = 函数（或类 / 对象），可返回 disposer `ctx.plugin()` 接受三种插件形态（vendored 源码 `vendor/cordis/src/registry.ts`，`Plugin` 类型）： ```ts // 1. 函数插件：直接调用 callback(ctx, config) export function apply(ctx: Context, config: Config) { /* ... */ } // 2. 对象插件：带 apply(ctx, config) 方法 export const objectPlugin = { name: 'object-plugin', apply(ctx: Context, config: Config) { /* ... */ }, } // 3. 类插件：Service 子类，用 new (ctx, config) 构造 export class MyService extends Service { constructor(ctx: Context) { super(ctx, 'myService') } } ``` - 函数插件最常见的形态是**具名导出 `apply`**（loader 从模块读取 `apply`），但 `ctx.plugin(fn)` 直接接受函数本身。 - 插件可以返回一个 **disposer**（或 disposer 的数组/迭代器/async 迭代器，见 §2.1 的 `Effect`），在插件卸载时释放资源——这正是“插件 = `function(ctx) → disposer`”这一经典表述的准确含义。注意：v4 中 disposer 的登记被统一收敛进 `ctx.effect()`（见 §2.1），插件主体（`apply`）的返回值与 `ctx.effect` 的执行体共享同一套 `Effect` 形状处理逻辑（`vendor/cordis/src/fiber.ts` 的 `Effect` 类型与 `_execute`）。 ### 1.3 Fiber：一个已加载插件实例的运行时句柄 `ctx.plugin()` 返回一个 **Fiber**（同时是 thenable，`await fiber` 等待其完成加载）： - 状态机（`vendor/cordis/src/fiber.ts` 的 `FiberState`）：`PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED`，旁路 `FAILED`。 - `PENDING`：已声明，但某个 `inject` 的服务尚不可用。 - `LOADING / ACTIVE`：`apply` 正在执行 / 已执行完成。 - `FAILED`：`apply` 或 config 校验抛错。 - `UNLOADING / DISPOSED`：disposer 正在运行 / 全部拆除。 - `fiber.uid`：registry 内唯一 id，根 fiber 为 `0`，dispose 后为 `null`。 - `fiber.dispose()`：卸载插件，resolve 时全部清理（含 async disposer）已结束，并**递归卸载其挂载的子插件**。 - `fiber.restart()` / `fiber.update(config)`：按当前/新 config 重载。 - `fiber.getEffects()`：返回当前效果的 `EffectMeta` 诊断树。 - `fiber.name`：展示名，取自最近的具名祖先，否则 `'root'`。 教程第二章（https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-tutorial/02-lifecycle-and-effects.md ）给出完整状态机与示例。 --- ## 2. Context API `Context` 是核心对象：一切 service / event / 生命周期 API 都经 `ctx` 到达。运行时 `Context` 是一个 **Proxy**：普通属性读取走 service 解析器（`ReflectService.handler`），而 `extend()` / `isolate()` / `intercept()` 派生作用域子 context，**不修改父 context**（`vendor/cordis/src/context.ts`）。 ### 2.1 生命周期与 effect - `ctx.effect(execute, label?)`：登记一个带清理语义的副作用。`execute` 立即执行，产生的 disposer 被收集，并在「返回的 disposer 被调用」或「所属 fiber 卸载」二者先发生时运行。**disposer 以注册逆序运行**；可以是 async（卸载时 await 它们）。执行体返回形状 `Effect`： - 单个 disposer `() => T` - 一个 disposer 的 `Promise` - （async）可迭代的多个 disposer——**generator effect 每 yield 一个 disposer 就立即登记一个** - 在已 dispose 的 fiber 上调用会抛 `CordisError('INACTIVE_EFFECT')`；返回非法形状抛 `TypeError`。 - `ctx.fiber`：当前 fiber（拥有此 context 的插件实例）。`ctx.effect()` 委托给它。 - **disposer 逆序执行、多个 async disposer 并发**：教程第二章明确提醒“如果拆除步骤必须顺序执行，把它们放进同一个 disposer 并在此 await”（https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-tutorial/02-lifecycle-and-effects.md ）。 > **经典谱系对照**：`ctx.effect()` 在经典 Cordis 中即存在，语义一致（“返回 disposer，随插件卸载而回收”）。v4 额外把 `ctx.on()`、`ctx.plugin()`、`ctx.provide()` 等全部实现为 effect（见下），即 AGENTS.md 的 “**Registrations are effects**”。 ### 2.2 作用域派生（v4 取代 scope/select 的机制） - `ctx.extend(meta?)`：创建继承当前 scope 的子 context，叠加额外元数据；子 context 原型继承父的所有属性，`meta` 自有属性遮蔽继承项；**父不受影响**。 - `ctx.isolate(name, label?)`：为服务 `name` 创建独立服务作用域的子 context。在该子 context 之下，对服务 `name` 的读写解析到新 label 而非父的 label，因此可在不影响父作用域的前提下提供不同实现。传相同 `label` 给两次 `isolate()` 会**合并这两个作用域**（默认 label 是全新 symbol）。 - `ctx.intercept(name, config)`：为在其下启动的插件追加服务专属 intercept config（见 §3.3）。该 config 会被 merge 进服务的解析后 config（祖先条目优先，见 `Service[symbols.resolveConfig]`）；父 context 不受影响。 > **`ctx.scope` / `ctx.select` 的说明**：这是**经典 Cordis（v2/v3）**的作用域 API——`ctx.scope` 派生隔离作用域、`ctx.select(name)` 创建在所选服务作用域中运行的选择器。它们在 v4 被 `extend/isolate/intercept` 取代。本文在 vendored v4 源码（`vendor/cordis/src/context.ts`）中**未找到** `scope`/`select` 属性（grep 仅命中注释里的普通英文 “scope”），因此 DSH 实际使用的 v4 无此二者。经典 API 的精确语义请以 Koishi 文档为准（https://koishi.js.org/api/core/context.html 、https://deepwiki.com/koishijs/koishi/2.1-context ）；下文对该二 API 的转述标注 **[unverified]**：`ctx.scope` 创建隔离作用域（服务提供在作用域内隔离），`ctx.select(name)` 返回一个可在选中服务作用域中消费/提供该服务的 `Selection` 对象（用于隔离多个同名服务的实例）。另有提交 `feat: support ctx.inject(), deprecate ctx.using()`（https://github.com/cordiverse/cordis/commit/b5cd65aa27a18b90aeb6c8f036570cf1a374277a ）表明经典 `ctx.using()` 被 `ctx.inject()` 取代。**[unverified 部分如上]** ### 2.3 环境句柄与混合成员 `ctx` 上的环境句柄（`vendor/cordis/src/context.ts` 的 `Context` 接口）： - `ctx.root`：应用根 context（每个子 context 共享它）。标注 `@experimental`。 - `ctx.events`：事件总线 `EventsService`，其方法也 mixin 到 `ctx`（`ctx.on/emit/…`）。 - `ctx.logger`：日志服务 `LoggerService`，可 `ctx.logger(name)` 生成具名 logger，也可直接 `ctx.logger.info(...)`。 - `ctx.registry`：插件注册表 `RegistryService`，其方法 mixin 到 `ctx`（`ctx.plugin/inject`）。 - `ctx.reflect`：反射层 `ReflectService`，支撑 context proxy 与 `ctx.get/provide/…`。 - `ctx.baseUrl?`：解析相对插件/模块 specifier 的 base URL（运行时设定）。 - 静态符号：`Context.effect / filter / isolate / intercept`（对应 `symbols.effect/filter/isolate/intercept`，键为 `Symbol.for('cordis.*')`）。`Context.is(value)` 跨 realm/多份 cordis 判定是否为 context（以全局 symbol 品牌，而非 `instanceof`）。 `ctx` 上由 `ReflectService` mixin 出的方法（`vendor/cordis/src/reflect.ts` 构造器）： ```ts this.mixin('reflect', ['get', 'set', 'provide', 'accessor', 'mixin']) this.mixin('fiber', ['runtime', 'effect']) this.mixin('registry', ['inject', 'plugin']) this.mixin('events', ['on', 'once', 'parallel', 'emit', 'serial', 'bail', 'waterfall']) ``` - `ctx.get(name, strict?)`：无需 inject 直接从 store 读服务；`strict=true`（默认）只返回 provider fiber 当前 ACTIVE 的实现，否则可能返回 `undefined`。这是“可选依赖”的读取方式。 - `ctx.set(name, value)`：覆写某已提供服务的值；**只有提供该服务的 fiber 才能 set**，set 未提供名抛错。 - `ctx.provide(name, value)`：以当前 fiber 为所有者登记一个服务实现；fiber ACTIVE 后对同 isolation 作用域的依赖方可见；disposer 运行或 fiber 卸载时注销（唤醒依赖方）。同作用域重名抛错。 - `ctx.accessor(name, { get, set? })`：定义由 get/set 钩子支撑的计算型 context 属性；随 fiber 卸载移除。 - `ctx.mixin(name, keys)` / `ctx.mixin(source, keys)`：把服务成员直接暴露到 `ctx`（如 `ctx.on` 转发到 `ctx.events.on`，方法绑定到该服务）；随 fiber 卸载移除。 > 来源（一手）：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-api/context.md 与 `vendor/cordis/src/{context,reflect}.ts`。 ### 2.4 scope forking 与 dispose 语义小结 - “作用域分叉（scope forking）”在 v4 = `extend()` 派生原型子 context；服务隔离 = `isolate()`；配置拦截 = `intercept()`。三者都不改动父 context（copy-on-write 原型链）。 - 事件监听过滤也通过 context 实现：每个 context 可携带一个 **listener filter**（`Context.filter` symbol，`ctx[Context.filter]`），每次事件分发都会查询它（见 §4.4）。 - dispose 语义：所有注册都是 effect；卸载按 fiber 为单位，disposer 逆序、async 并发；子插件随父插件递归卸载。 --- ## 3. Services（服务） ### 3.1 服务定义与提供 - 基类 `Service`（`vendor/cordis/src/service.ts`）：在 `ctx` 上暴露具名 API 的抽象基类。子类在构造器调用 `super(ctx, name)`——服务**立即注册**，并随所属 fiber 自动移除。 - `super(ctx, name)` 内部调用 `ctx.reflect.provide(name, this, this[Service.check])`（`service.ts` 构造器），等价于 `ctx.provide(name, value)`。 - `name ??= this.constructor['provide']`：服务名默认取静态 `provide` 字段。 - 若服务带 `[Service.invoke]` 执行体，则实例变为**可调用对象**（如 `ctx.logger()`）。 - 消费方通过 `inject` 或 `ctx.get(name)` 获取；类型上通过 `declare module '@deepseek-ai/cordis' { interface Context { : } }` 的 **declaration merging** 把键加进 `Context` 接口（编译期，无运行时代码）。 DSH 教程第三章的完整例子（https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-tutorial/03-services.md ）： ```ts import { Service, type Context } from '@deepseek-ai/cordis' declare module '@deepseek-ai/cordis' { interface Context { greeter: GreeterService } } export class GreeterService extends Service { constructor(ctx: Context) { super(ctx, 'greeter') } greet(who: string) { return `Hello, ${who}!` } } export const name = 'greeter' export function apply(ctx: Context) { ctx.plugin(GreeterService) } ``` 消费方： ```ts export const name = 'consumer' export const inject = ['greeter'] export function apply(ctx: Context) { console.log(ctx.greeter.greet('world')) } ``` ### 3.2 `inject`：声明依赖 - `inject` 有数组/对象两种形式（`Inject` 类型，`vendor/cordis/src/registry.ts`）：数组形式仅请求服务；对象形式把每个服务名映射到可选 intercept config。 - `ctx.inject(deps, callback)` 是 `ctx.plugin({ inject, apply: callback })` 的简写：当所需服务可用时执行 callback，且**每当所需服务变化时卸载并重跑**。 - **依赖在加载后仍被跟踪**：若所需服务在运行中消失（其 provider 被卸载或被热替换），所有依赖方插件也会被卸载，并在服务恢复时重新加载——从而避免运行中的消费者持有不可用服务的引用。这也是“服务替换”可配置化的基础。 - 可选依赖：不用 `inject`，在 `apply` 内部用 `ctx.get(name)`（返回 `undefined` 表示未提供）。 ### 3.3 intercept（配置拦截 / provider 无关的服务配置） - `inject` 的对象形式 / `ctx.intercept(name, config)` / loader entry 的 `intercept` 字段，都会把一段 config 合并进该服务在插件 context 下的“解析后 config”。 - 合并规则（`Service[symbols.resolveConfig]`）：祖先条目优先（更靠近根的条目先合并），`base` 前置、`head` 后置；服务若声明 `Config.merge` 则用其合并，否则浅 `Object.assign`。 - 典型用途：loader 服务自身声明 `Loader.Intercept = { await?: boolean }`，让依赖 `loader` 的插件在 loader entries 尚在加载时保持 PENDING（`vendor/loader/src/index.ts` 的 `[Service.check]`）。 ### 3.4 隔离状态 vs 共享状态 - 默认：同一服务名在一个作用域内**唯一**（同作用域重名 `provide` 抛错 `service "x" has been registered at `）。 - 隔离通过 `ctx.isolate(name)` 或 loader 的 `isolate` entry 字段实现：不同 label 各持一份实现。 - Loader 层有 `LocalRealm`（entry 本地隔离，label 后缀 `#`）与 `GlobalRealm`（具名共享隔离，label 后缀 `@