Cordis 教程总览:环境搭建与七章路线图

Cordis 是 DeepSeek Harness 底层的插件框架:一个小型运行时,工具、LLM 适配器、文件访问乃至 agent loop(智能体循环)本身,都是挂载到共享上下文里的插件。围绕它,DeepSeek Harness 仓库内置了一套七章的动手教程,每一章都是一个可运行的示例,从写出第一个插件开始,一路做到把模型工具接进真实的 harness 服务。本文是这套教程的总览:先讲清它是什么,再给出环境搭建步骤与启动器原理,最后过一遍七章路线图,读完就能上手。

它是什么,适合谁读

Cordis 的设计思路是把所有能力都做成插件,由统一的机制挂载和管理,教程的全部示例都建立在这个模型上。它面向 agent 开发者,但不要求你精通 TypeScript:教程附有一节语法说明,解释示例中可能陌生的写法;每一章也都给出确切的命令和预期输出,照着敲就能得到同样的结果。

除了这份逐步实践的教程,仓库里还有一份精简的概念参考(Cordis 入门),以及子系统页面上自动生成的 cordis-surface API 区块,想先建立整体认识再动手的读者可以搭配着看。需要注意,教程中的插件跑在一个独立的启动器上;而要为 harness 本身编写插件,也就是由 cordis.yml 加载、在 Web UI 中驱动的那类,则应从仓库的第一方插件文档入手,那是另一条路径。

准备工作:三条命令

教程不需要 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 插件,再让 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。import type { Context } from '@deepseek-ai/cordis' 只导入类型信息,运行时会完全消失,因此仅为类型注解而使用 Context 的插件文件,不会增加任何运行时依赖。

第三是声明合并。declare module '@deepseek-ai/cordis' { ... } 会把你的条目添加进 Cordis 已经声明的接口,比如给新的 ctx.greeter 属性补上类型,或者登记事件名称。但要注意,它不会生成任何运行时接线:插件必须另行提供服务或发出事件,声明才会落到实处。第 3 章会完整展示这个模式。第 5 章还会用 interface 描述配置对象的字段,并用 Schema<Config> 这类泛型表示 schema 校验哪些字段,照抄即可,周围正文会解释每一项声明连接了什么。

小结

这套教程的设计相当克制:无需 API 密钥,不设 TypeScript 门槛,试验代码全部隔离在 gitignore 掉的 tmp/ 目录,每章命令与预期输出成对出现。七章从「插件是函数」起步,依次经过生命周期、服务、事件、配置与热重载,最终把一个真正的模型工具接进 harness。想理解一个 agent harness 为什么选择一切皆插件的架构,把这七章亲手跑一遍,是最直接的路径。