0a2ac90617
The VitePress config declared no position for the subsystem or other-interface sections, so `indexOf` returned -1 and sorted them ahead of every declared group: the reference landing page's own sidebar entry sat 1549px below the fold. Four subsystem pages also shared `order` values with pages in the same section, resolved only by sort stability and array concatenation order. Section placement and collapse move into the manifest as a per-locale declaration, and `sectionSpec` throws for an undeclared section instead of sorting it silently to the top. Subsystem pages are grouped by concern, the six topical groups collapse until one holds the page being read, and page order derives from array position. The projector drops the language-switcher line and repository badge the canonical pages carry for their GitHub readers. The navigation bar gains the DeepSeek wordmark, a release-stage tag, and a favicon; the sidebar scrollbar rests invisible and appears while scrolling. Subsystem pages carry a two-level outline, and the two plugin-development tracks now cross-link.
4.2 KiB
Cordis 教程
English | 中文
Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行时，其中的每项能力，包括工具、LLM（大语言模型）适配器、文件访问乃至 agent loop（智能体循环）本身，都是挂载到共享上下文中的插件。本教程通过动手实践讲解 Cordis：每一章都是一个可以运行的示例，你将在本仓库内的临时目录中逐步构建它，最后把一个插件接入真实的 harness 服务。
本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 TypeScript 说明会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
如果你想阅读精简的概念参考，而不是逐步实践，请参阅 Cordis 入门。详尽的 API 参考见子系统页面上生成的 cordis-surface 区块，以及 Cordis 核心 API页面。
如果你要为 harness 本身编写插件——由 cordis.yml 加载、在 Web UI 中驱动，而不是下面这个启动器——请从第一个 Harness 插件开始。
准备工作
你需要克隆本仓库并安装依赖；开发指南列出了前置条件。本教程不需要 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 文件。
章节
- 你的第一个插件：插件是函数，由 loader 挂载。
- 生命周期与 effect：由 Cordis 管理的注册会在所属插件卸载时撤销。
- 服务：在
ctx上公开一项能力，并通过inject依赖它。 - 事件：类型化事件、广播分发和 waterfall（瀑布式事件）的短路行为。
- 配置：读取
cordis.yml中经过校验的配置，并在输入错误时明确报错。 - 组合与 HMR（热模块替换）：把配置文件作为插件树，使用热重载，并诊断始终无法加载的插件。
- 进入 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 校验哪些对象字段。你可以直接照写这些声明；周围的正文会解释每项声明连接了什么。
