Cordis 教程

准备工作

你需要克隆本仓库并安装依赖；开发指南列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。

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

创建各章使用的临时目录。tmp/ 已被 git 忽略，因此你在其中写入的任何内容都不会进入版本控制：

mkdir -p tmp/cordis-tutorial
cd tmp/cordis-tutorial

每一章都从该目录运行同一条命令：

node --import tsx ../../vendor/cordis/bin.js

这个单文件启动器（见 vendor/cordis/bin.js）会创建根 Context、挂载 Loader 插件，并让它从当前目录加载 ./cordis.yml。其余所有内容，包括有哪些插件以及如何配置它们，都来自你稍后将编写的 YAML 文件。--import tsx 标志让 Node 无需构建步骤即可运行配置所指向的 TypeScript 文件。

章节

1. 你的第一个插件：插件是函数，由 loader 挂载。
2. 生命周期与 effect：由 Cordis 管理的注册会在所属插件卸载时撤销。
3. 服务：在 ctx 上公开一项能力，并通过 inject 依赖它。
4. 事件：类型化事件、广播分发和 waterfall（瀑布式事件）的短路行为。
5. 配置：读取 cordis.yml 中经过校验的配置，并在输入错误时明确报错。
6. 组合与 HMR（热模块替换）：把配置文件作为插件树，使用热重载，并诊断始终无法加载的插件。
7. 进入 harness：基于真实的 harness 服务注册一个可由模型调用的工具。

TypeScript 说明

这些示例使用了普通现代 JavaScript 之外的三项 TypeScript 功能：

• 类型注解描述值，但不会改变运行时行为：ctx: Context 表示 ctx 具备 Cordis 上下文 API，who: string 接受文本，而 string[] 表示字符串数组。
• import type { Context } from '@deepseek-ai/cordis' 只导入类型信息。它在运行时会消失，因此仅为类型注解使用 Context 的插件文件不会增加运行时依赖。
• 声明合并（declare module '@deepseek-ai/cordis' { ... }）会为 Cordis 已经声明的接口添加你的条目，例如新 ctx.greeter 属性的类型或事件名称。它不会生成任何运行时接线；插件必须另行提供服务或发出事件。第 3 章会完整展示该模式。

第 5 章还会使用 interface 描述配置对象的字段，并使用 Schema<Config> 这类泛型表示 schema 校验哪些对象字段。你可以直接照写这些声明；周围的正文会解释每项声明连接了什么。