第4讲 · Cordis 插件框架极速入门

《DeepSeek Harness 从上手到精通》系列 · 第二阶核心概念篇

🎯 目标：建立"一切皆插件"心智模型，看懂 Cordis 核心词汇难度 ★☆☆ ⏱ 约 20 分钟前置：第 1–3 讲已跑通 dsh

从本讲起，我们进入核心概念篇。dsh 的底座是 Cordis——一个插件框架。本讲不要求你写代码，重点是建立"一切皆插件"的心智模型。系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT）。

一、什么是插件树：ctx、事件、effect

在 Cordis 里，整个 dsh 运行时就是一棵插件树（plugin tree）。每个插件（plugin）是一个节点，节点挂在根 ctx 上，互相通过接口而非硬编码依赖协作。三个核心词汇先混个脸熟：

ctx（上下文）：全局服务总线，所有插件共享的"插座面板"，你通过 ctx.xxx 取用能力；
事件（event）：插件之间、插件与运行时之间用事件通信，解耦且可观测；
effect（可逆副作用）：插件挂载时"装上"的东西（注册工具、加菜单），卸载时"撤销"。这是 dsh 能做热插拔、回退的底层机制。

Cordis 插件树与 ctx/effect — **图 1** 插件树：根 ctx 上挂着各插件节点，effect 让挂载/卸载可逆。

一句话记牢：dsh 不是"一个程序"，而是"一棵正在生长的插件树"，你看到的每个功能，都来自某个插件插在了 ctx 上。

二、服务定位：按接口找，不 import

传统写法是 import { llm } from '...' 把依赖写死。Cordis 反过来：插件只声明"我需要一个 LLM 能力"，运行时把实现了该接口的插件注入进来。常见内置插座：

插座	它是什么	谁来提供
`ctx.llm`	对话/推理引擎	LLM 适配插件
`ctx.tools`	工具注册表	各工具插件
`ctx.sessions`	会话管理	会话插件

服务定位与依赖注入 — **图 2** 中心化的 ctx 按"接口"向各插件派发能力，而非互相 import。

好处是：换实现只需换插件，消费方代码一行不用改——这正是第 7 讲"能力 Seam"的伏笔。

三、inject 声明依赖 → 加载顺序自动推导

插件通过 inject 声明自己要用哪些服务。Cordis 据此自动推导加载顺序：被依赖的先加载，依赖者后加载。你不必手动排依赖树，框架帮你搞定。

// 在插件里声明依赖，框架自动排好加载顺序
const plugin = (ctx) => {
  ctx.inject(['llm', 'tools'], (llm, tools) => {
    // 这里能安全使用 llm 与 tools，
    // 因为 Cordis 保证它们已就绪
  });
};

这是 dsh 能"一行 YAML 换脑"的底层原因：依赖关系由框架编排，而不是散落在各处 require 里。

四、官方 Cordis 教程 7 讲 · 导读地图

官方 docs/cordis-tutorial/ 有 7 讲。本系列"先用后学"，给你一张跳过地图：

官方讲次	主题	本系列建议
第 1–2 讲	插件与 ctx 基础	必读（对应本讲）
第 3–4 讲	事件与生命周期	必读（第 6 讲会用到）
第 5 讲	高级装配	路线 B/C 选读
第 6–7 讲	插件调试与发布	路线 C（第 20 讲）再读

五、动手练习：手画插件树简图

本讲产出不写代码，而是一张手绘插件树简图——它会在后续每讲当"地图"用。请画出来并标注：

中心一个 ctx 根节点；
挂上至少 4 个插件：llm、tools、sessions、fs；
用箭头标出谁 inject 了谁（例如 tools 依赖 llm）；
在右下角写一句："effect 让挂载/卸载可逆"。

六、常见坑

把 import 思维带进来：别再想"从哪 import"，先想"我需要哪个 ctx 服务"；
依赖顺序想手动排：交给 inject，手写顺序易出循环依赖；
忽略 effect 可逆性：卸载插件时你"装上"的东西会被自动撤掉，不必手动清理；
教程版本漂移：官方 7 讲可能随版本重组，认准 docs/cordis-tutorial/ 入口即可。

七、官方文档对应章节

docs/cordis-tutorial/ 第 1–2 讲（插件与 ctx 基础）
架构文档中"Plugin & Service"相关章节
建议阅读顺序：先本讲建立地图，再按上表跳读官方 1–2 讲

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第4讲 Cordis 插件框架极速入门