一 概念
源码部署的版本:0.1.5-rc.2
查询地址:deepseek-harness-master\apps\cli\package.json
或者根目录控制台执行命令:pnpm dsh –version
I 什么是 Agent Harness
DeepSeek Harness(dsh)是由 DeepSeek AI 开发的开源 agent harness,即 "智能体框架"。
它的核心特征是:
- 采用 “一切皆插件” 的架构。
- 由 Cordis 驱动。
- 提供 Web UI 与 CLI 等使用入口。
- Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。
- 当操作在当前权限策略下需要审批时,界面会先询问用户。

图中可以看到,<code>dsh</code> 位于用户入口、模型提供方和工作区之间:
- 用户通过 Web UI、CLI 或 Python SDK 与 Harness 交互。
- Harness 内部组合 Agent Loop、Tools、LLM、Session 等插件能力。
- Agent 调用模型,并操作工作区中的文件和命令。
II DeepSeek Harness 解决什么问题
一个能执行编码任务的 Agent,不只是调用大模型生成文本,还需要:
- 读写工作区文件。
- 执行命令。
- 组织多轮工具调用。
- 维护会话状态。
- 处理权限与审批。
- 允许开发者扩展工具和模型能力。
<code>dsh</code> 把这些能力组织成一个可运行的 Harness。学习者可以把重点放在 "如何使用它完成任务" 和 "如何扩展它",而不必从零实现一整套 Agent 运行环境。
需要特别注意:DeepSeek Harness 目前处于开发者预览阶段,正在快速迭代,未来可能出现破坏兼容性的变更。学习时应以当前版本的实际行为为准。
III 运行方式
1 环境要求
需要满足以下版本要求:
- 包管理器:<code>pnpm@11.7.0</code>
- Node.js:<code>^22.19.0 || >=24.0.0</code>
因此开始前需要确认:
node -v
pnpm -v
如果 Node.js 版本不在支持范围内,应切换到 22.19.0+ 或 24.0.0+。
- Node.js 下载地址:https://nodejs.org/
- pnpm 安装说明:https://pnpm.io/installation
可以选择以下两种运行方式。
2 方式一:通过 npm 运行
安装 Node.js 后,直接运行:
npx @deepseek-ai/dsh web
该命令会启动 Web UI,默认地址为 http://127.0.0.1:3080。
这种方式适合快速体验,不需要克隆仓库。
3 方式二:从源码运行
如果需要在源码仓库中开发、调试或修改插件,使用源码运行:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
V 实操步骤
1. 打开终端(macOS / Windows)
后续所有命令都要在终端窗口中执行。
macOS
- 按下 Command + 空格,打开 Spotlight。
- 输入 Terminal 或 终端。
- 回车打开终端。
- 也可以从访达进入:应用程序 → 实用工具 → 终端。
Windows
- 按下 Windows 键 + R,打开 "运行" 对话框。
- 输入 <code>powershell</code> 或 <code>cmd</code>。
- 回车打开 PowerShell 或命令提示符。
- 也可以点击 "开始" 菜单,搜索 PowerShell、终端 或 命令提示符 后打开。
- Windows 11 用户也可以右键点击 "开始" 按钮,选择 "终端"。
2. 检查环境
在终端中执行:
node -v
pnpm -v
确认 Node.js 版本满足 <code>^22.19.0 || >=24.0.0</code>。
3. 选择运行方式
快速体验:
npx @deepseek-ai/dsh web
源码运行:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
4. 验证启动
观察终端输出。正常情况下,命令会打印 Web UI 访问地址,默认是:
http://127.0.0.1:3080
二 Web-UI基础使用
整个操作流程分为四步:打开 Web UI、配置 DeepSeek 模型、选择工作区、发送第一个任务并处理审批。
第 1 步:打开 Web UI
启动 Web UI 后,命令会打印访问地址。默认地址是:http://127.0.0.1:3080
dsh 进程会把调用命令时所在的目录作为默认文件系统位置,但新的 Web UI 在添加工作区之前不会选中任何工作区。
第 2 步:配置 DeepSeek 模型(改源码)
第一次使用 Web UI 时,需要先配置模型。
操作:
- 打开 设置 → 模型。
- 在 DeepSeek 卡片中找到 API 密钥输入框。
- 输入 DeepSeek API Key。
- 点击保存。
- 确认模型选择器已经出现可用模型。
保存后,模型路由会立即可用,不需要重启服务器。密钥是只写的:保存后页面只会显示脱敏信息,不会再次显示明文密钥。
如果是用源码部署,直接改源码
路径:deepseek-harness-master\packages\bundle\base\cordis.patch.yml
在根目录创建环境文件 .env ,编辑文件内容,定义字段API_KEY = 第三方鉴权秘钥key
改动 1:默认模型从 DeepSeek 切到公司模型
现在 cordis.patch.yml:75-79 是:
- id: agent-default-model
name: '@deepseek-ai/dsh-agent-default-model'
config:
provider: deepseek-official
model: deepseek-flash
改成:
- id: agent-default-model
name: '@deepseek-ai/dsh-agent-default-model'
config:
provider: company-qwen
model: Qwen3.6-35B-A3B
改动 2:激活 pi-ai 并内联公司网关路由
现在 cordis.patch.yml:107-108 是:
- id: llm-pi-ai
name: '@deepseek-ai/dsh-llm-pi-ai'
改成:
- id: llm-pi-ai
name: '@deepseek-ai/dsh-llm-pi-ai'
config:
providers:
company-qwen:
apiKeyEnv: API_KEY
api: openai-completions
baseURL: http://ai-network-qwen.top/v1
models:
- id: Qwen3.6-35B-A3B
第 3 步:选择工作区
工作区是 Agent 可以读取和编辑的项目目录。选中工作区之前,会话输入框不可用,因此必须先完成工作区选择。
操作:
- 点击 选择工作区。
- 添加启动 dsh 时所在的项目目录。
- 选中这个目录。
- 确认会话输入框已经变为可用状态。
第 4 步:发送第一个任务
启动一个会话并发送任务。可以先用这个任务验证 Web UI 是否正常工作:你好, 你是谁?!
Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作在当前权限策略下需要审批时,Web UI 会先询问你。
操作:
- 在会话输入框中发送上面的任务。
- 观察 Agent 是否开始读取文件和执行命令。
- 如果 Web UI 弹出审批请求,根据任务内容选择允许或拒绝。
- 等待 Agent 输出最终回复。
确认收到 Agent 的回复后,操作完成。
三 CLI 入门:用命令完成任务
前面已经通过 Web UI 完成了一次图形界面操作。这里解决一个更简单的问题:不打开浏览器,也能用一条命令让 dsh 完成项目任务。 学会打开终端和确认命令可用,然后认识两个日常入口—— dsh web 是打开网页版, dsh –profile headless "任务" 是直接提交一个一次性任务。接着明确这两种模式分别适合什么场景,再运行一次 headless 任务,观察最终答案和退出码。最后用“运行方案”的类比理解 profile。
实操步骤

上图是完整路径:打开终端后,只需要在“图形界面”和“一次性命令”之间选择一种方式,然后观察结果。下面按这张图逐步操作。
这里命令统一使用 npx @deepseek-ai/dsh 。如果源码运行,并且安装了 pnpm ,也可以把npx @deepseek-ai/dsh 换成 pnpm dsh ,后面的参数完全相同。
第 1 步:打开终端
macOS
- 按下 Command + 空格 ,打开 Spotlight。
- 输入 Terminal 或 终端 ,回车打开终端。
- 也可以从访达进入: 应用程序 → 实用工具 → 终端 。
Windows
打开 PowerShell 或者 cmd
第 2 步:确认命令可用
在任意目录执行:
pnpm dsh --help
pnpm dsh --version
或者
npx @deepseek-ai/dsh --help
npx @deepseek-ai/dsh --version
–help 打印启动器自身的帮助信息。
–version 打印启动器版本。
第一次使用 npx 时,它可能会询问是否安装 @deepseek-ai/dsh 包,输入 y 或按提示确认即可。
如果已经从源码运行并安装了 pnpm ,对应命令是 pnpm dsh –help 和 pnpm dsh –version 。
能看到帮助或版本号,说明 dsh 命令已经可以使用。
第 3 步:认识两种日常入口
暂时只需要记住两个命令:
| 命令 | 用途 |
|---|---|
| npx @deepseek-ai/dsh web | 打开网页版,适合浏览、审批和观察 Agent 的完整过程。 |
| npx @deepseek-ai/dsh –profile headless "任务文本" | 不打开网页,直接提交一个任务,适合自动化和脚本调用。 |
其中, dsh web 是 –profile web 的别名。可以把 profile 先理解成一种“运行方案”:
web :带网页界面的方案。
headless :无界面、一次性执行的方案。
第 4 步:明确两种模式的应用场景
学会使用方式后,关键是要知道什么时候选哪一种。选择标准是:这个任务是否需要你全程看着、点着、批着。
优先使用 web 的场景
- 第一次配置模型、API Key 或工作区。
- 需要观察 Agent 的思考、计划和工具调用过程。
- 需要审批 Agent 的文件修改、命令执行等操作。
- 需要调试 Agent 为什么没有按预期完成任务。
- 你正在手工使用 Agent,随时可能和它继续对话。
优先使用 headless 的场景
- 任务明确,不需要人工逐步审批。
- 你只想要最终答案,不关心中间的图形界面。
- 要在脚本、CI/CD、定时任务或批处理中调用 dsh 。
- 要通过 stdout 和退出码把结果交给另一个程序继续处理。
- 运行环境没有浏览器或图形界面,例如远程服务器、容器、自动化流水线。
简单记法:
- 需要人看着、批着、调试着,选 web 。
- 给一个任务、拿回一个结果、交给脚本用,选 headless 。
- 如果任务运行过程中会不断弹出需要你确认的操作,先使用 web 完成;确认流程稳定、可以被当前权限策略自动处理后,再改成 headless 放入自动化。
第 5 步:用 CLI 打开 Web UI
执行:
pnpm dsh web
默认服务地址是:
http://127.0.0.1:3080
操作:
- 在浏览器中打开命令打印的地址。
- 确认页面可以正常打开。
- 回到终端,按 Ctrl+C 停止 Web UI。
这里只是把启动入口从图形操作改成了命令行。
第 6 步:运行 Headless 一次性任务
现在尝试不打开浏览器,直接让 dsh 完成一个任务。
执行:
pnpm dsh --profile headless "用一句话说明当前目录下项目的主要功能"
这条命令会:
- 把运行命令时所在的目录作为默认 workspace 根目录。
- 创建一个全新的持久化 Agent。
- 提交任务,并等待 Agent 完成。
- 在 stdout 打印最终答案。
第一次使用 headless 时,它会自动初始化这个运行方案。成功运行时不会打开监听端口。
如果任务失败且提示与模型凭据有关,请确认秘钥模型是否正确配置
第 7 步:查看退出码
任务完成后,检查命令是否成功:
macOS / Linux
echo $?
Windows PowerShell
echo $LASTEXITCODE
Windows CMD
echo %ERRORLEVEL%
退出码含义:
0 :最终原因是 completed ,任务正常完成。
1 :最终原因不是 completed 。
第一个插件
核心讲解与实操步骤

上图是本章的完整路径:认识课程目录 → 查看已有插件 → 创建本地项目 → 编写插件 → 注册到 cordis.yml → 使用 –patch 启动 Web UI → 观察终端日志。下面按这张图逐步操作。
第 1 步:认识本次课程目录
本章所有操作都在课程工作目录中完成,不要进入 dsh 源码仓库修改官方文件。
Windows 示例路径为:
D:\docker\course-maker\43-deepseek-harness
进入后,你会看到:
43-deepseek-harness/
├─ 课程大纲.md
├─ 讲义/
├─ deepseek-harness-master/ # 官方仓库,只阅读,不修改
└─ scratch-plugin/ # 练习目录,用来放我们自己的插件
第 2 步:理解什么是 dsh 插件
在 dsh 中,插件是一个导出 apply 函数的 TypeScript 模块。框架加载插件时会调用 apply ,并传入一个上下文对象 ctx 。你通过 ctx 注册能力,例如工具、事件监听、服务、定时器等。
最小插件模板如下:
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'
export function apply(ctx: Context) {
// Register capabilities here.
}
它的三部分是:
name :插件名称。
apply :插件入口函数,框架加载时调用。
ctx :上下文对象,用来注册能力或声明清理。
dsh 自己也有大量插件,例如模型适配、Agent 主循环、Web 界面、文件工具等。因此“插件”不是 dsh 之外的特殊概念,而是整个 dsh 的组成方式。
第 3 步:查看一个已经存在的插件
在课程工作目录执行:
pnpm dsh --profile web --dump-config
这条命令不会启动 Web UI,而是打印默认 web 运行方案已经加载的插件列表。输出中可以看到许多 name 字段,例如:
- id: llm
name: '@deepseek-ai/dsh-llm'
- id: agent
name: '@deepseek-ai/dsh-agent'
- id: web-runtime
name: '@deepseek-ai/dsh-web-app'
这些就是已经存在的 dsh 插件:
@deepseek-ai/dsh-llm :负责模型调用。
@deepseek-ai/dsh-agent :负责 Agent 主循环。
@deepseek-ai/dsh-web-app :负责 Web UI 运行。
观察要点:
- 每个插件的 id 是配置树里的稳定标识。
- 每个插件的 name 是实际要加载的模块名。
- 后面我们自己创建的 hello-plugin ,也会以同样的结构出现在这个配置树里。看完后,可以继续往下创建自己的插件。
第 4 步:创建本地插件项目
在课程工作目录执行:
macOS
mkdir -p scratch-plugin/src
Windows PowerShell
New-Item -ItemType Directory -Path scratch-plugin -Force | Out-Null
New-Item -ItemType Directory -Path scratch-plugin\src -Force | Out-Null
Windows CMD
mkdir scratch-plugin\src
执行后,你会得到一个 scratch-plugin/src 目录。它只是临时练习项目,不需要改动 dsh 源码仓库。
第 5 步:编写 hello-plugin
创建 scratch-plugin/src/my-plugin.ts ,内容如下:
import type { Context } from '@deepseek-ai/cordis'
export const name = 'hello-plugin'
export function apply(ctx: Context) {
console.log('[hello-plugin] plugin loaded!')
}
这个插件目前只做一件事:被加载时打印一行日志。虽然能力很小,但它已经具备 dsh 插件的最小结构。
第 6 步:注册到 cordis.yml
现在创建 scratch-plugin/cordis.yml 。它是插入本地插件的 Web 覆盖层。
先取得当前课程工作目录的绝对路径:
macOS
pwd
Windows PowerShell
(Get-Location).Path
Windows CMD
cd
然后把输出路径填到下面的 YAML 中。 name 必须完整指向 my-plugin.ts :macOS/Linux 填绝对路径,Windows 在盘符路径前加 file:/// 并改用 / 分隔。
通用模板:
- insert:
- id: hello
name: '/absolute/path/to/course/scratch-plugin/src/my-plugin.ts'
macOS 示例
- insert:
- id: hello
name: '/Users/yourname/43-deepseek-harness/scratch-plugin/src/my-plugin.ts'
Windows 示例
- insert:
- id: hello
name: 'file:///D:/docker/course-maker/43-deepseek-harness/scratch-plugin/src/my-plugin.ts'
用编辑器保存为 scratch-plugin/cordis.yml :
macOS
touch scratch-plugin/cordis.yml && open -e scratch-plugin/cordis.yml
Windows PowerShell / CMD
New-Item -ItemType File -Path scratch-plugin\cordis.yml -Force | Out-Null
notepad scratch-plugin\cordis.yml
cordis.yml 本身只提供配置覆盖,不会改变插件模块的解析方式。 name 必须指向插件文件。macOS/Linux可以直接使用绝对路径;Windows 必须写成 file:/// URL,例如 file:///D:/docker/… ,不能写成D:\docker… ,也不能因为 cordis.yml 放在 scratch-plugin 目录里就写成相对路径。
第 7 步:使用 –patch 启动 Web UI
回到课程工作目录,执行:
pnpm dsh web --patch ./scratch-plugin/cordis.yml
这个命令表示:启动 web 运行方案,并把 scratch-plugin/cordis.yml 作为覆盖层合并进去。等待启动完成后,在浏览器打开:
http://127.0.0.1:3080
启动期间,终端会打印:
[hello-plugin] plugin loaded!
看到这行日志,就说明你的插件已经被 Web UI 加载。
第 8 步:验证终端日志和浏览器
依次检查:
- 浏览器能正常打开 http://127.0.0.1:3080 。
- 终端中出现 [hello-plugin] plugin loaded! 。
- 页面本身仍能正常使用;这个插件只输出日志,不会改变界面。
验证完成后,回到终端按 Ctrl+C 停止 Web UI。
如果终端没有出现日志,重点检查:
- cordis.yml 中的 name 是否正确指向插件文件;Windows 是否写成 file:///D:/… 。
- 路径是否完整写到 scratch-plugin/src/my-plugin.ts 。
- 文件名是否真的是 my-plugin.ts ,而不是 .txt 。
- 是否在工作目录运行 pnpm dsh web –patch ./scratch-plugin/cordis.yml 。
- cordis.yml 中的路径是否用单引号包裹。
第 9 步:了解自动清理
通过 ctx 注册的东西,例如事件监听、工具、定时器,在插件卸载时会被自动清理。你不需要手动removeListener 或 clearInterval 。
如果插件中有自己创建、无法由 ctx 自动管理的资源,例如一个网络连接,就用 ctx.effect() 告诉框架如何清理:
import type { Context } from '@deepseek-ai/cordis'
export function apply(ctx: Context) {
ctx.effect(() => {
const timer = setInterval(() => {
console.log('heartbeat')
}, 5000)
return () => clearInterval(timer)
})
}
ctx.effect() 中返回的函数会在插件卸载时运行。本章的 hello-plugin 不需要这个机制,但后续开发更复杂插件时会用到。
第 10 步:了解依赖声明
如果插件需要使用其他服务,例如 tools 、 llm ,要声明 inject :
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-tool-plugin'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(/* ... */)
}
声明 inject 后,框架会确保依赖的服务就绪,再加载你的插件。此时在 apply 中访问 ctx.tools 才是安全的。
这里写的 hello-plugin 不依赖任何服务,所以不需要 inject 。
第 11 步:认识三种插件形态
除了函数形式,插件还支持对象形式和类形式。
函数形式
这是本文已经使用过的写法:
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'
export function apply(ctx: Context) {
// ...
}
对象形式
import type { Context } from '@deepseek-ai/cordis'
export default {
name: 'my-plugin',
inject: ['tools'],
apply(ctx: Context) {
// ...
},
}
类形式
import { Service, type Context } from '@deepseek-ai/cordis'
export default class MyService extends Service {
static inject = ['tools']
constructor(ctx: Context) {
super(ctx, 'myService')
}
}
大多数情况下,函数形式已经足够。当插件需要向其他插件提供服务时,再考虑类形式。
一切皆插件:Cordis 心智模型
核心讲解与实操步骤
第 1 步:先建立整体心智模型
先看下面这张图,它会贯穿本章和后续章节:

这张图包含三层信息:
-
Profile 组装:一个 profile 不是单个配置文件,而是多层叠加的结果。 dsh-base 先提供模型、工具、会话等基础插件, dsh-web-app 或 dsh-headless 再增加运行形态,个人 profile patch 和 –patch overlay最后覆盖。
-
运行时插件树:模型适配器、工具注册表、Agent 主循环、会话日志、Web UI 运行,都是同一棵树上的插件。它们不是“外围扩展”,而是产品本体。
-
Context 上的三类契约:插件通过 ctx 提供服务;需要其他服务时用 inject 声明依赖;插件之间松耦合通信时使用事件。注册的监听器、服务和其他副作用都可以在插件卸载时自动撤销。
从这里可以得到一句话:dsh 的扩展方式不是“改内核”,而是“把你的插件挂到其他插件旁边”。
再用一句话说清三者的关系:profile 是“组装图纸”,运行时插件树是“按图纸搭起来的机架”,Context是让这些插件互相插线、互相调用和通信的共享底板。
第 2 步:把“一切皆插件”落到可观察的配置树
在工作目录执行:
pnpm dsh --profile web --dump-config
这条命令不启动 Web UI,而是打印 web profile 最终形成的配置树。输出不是“一个程序的功能列表”,而是一行行插件条目。每一行都是一个插件在树中的挂载点。
输出会按来源分块,例如:
# == @deepseek-ai/dsh-base
- id: llm
name: '@deepseek-ai/dsh-llm'
- id: agent
name: '@deepseek-ai/dsh-agent'
- id: tools
name: '@deepseek-ai/dsh-tools'
# == @deepseek-ai/dsh-web-app
- id: webserver
name: '@deepseek-ai/dsh-host-webserver'
inject:
- webStartup
config:
host: !!js ctx.webStartup.host ?? '127.0.0.1'
port: !!js ctx.webStartup.port ?? 3080
观察要点:
- 配置树里的每一行,都是一个可替换的“零件”,而不是主程序里写死的功能。
- @deepseek-ai/dsh-llm 负责“和大模型对话”, @deepseek-ai/dsh-agent 负责“按任务一步步调用能力”, @deepseek-ai/dsh-tools 负责“提供具体工具”。
- id 可以理解为零件编号, name 表示这个编号当前实际使用哪个模块;同一个编号以后可以换成别的模块。
- webserver 只是负责打开网页界面的插件,并不是特殊存在;它需要 webStartup 这个服务,所以用inject 声明。
通俗地说,可以把 dsh 想成一个插满功能模块的机架:模型、工具、Agent、网页界面都是插在机架上的模
块,配置树就是“当前插了哪些模块、每个模块用哪条线路”。要换模型,就把 llm 这个编号下的模块换成
llm-deepseek ;要换命令执行方式,就把 shell 这个编号下的模块换成另一个实现。使用这些模块的其他插
件不需要知道背后换成了谁,只要接口还在,就照常工作。
图上可以直观看出:左边是机架上的固定插槽,中间是当前插入的模块,右边是后层可以替换的实现。同一个
id 可以指向新的 name ,其他插件仍按原来的 id 或服务使用能力。
第 3 步:理解插件的最小结构
第 04 章的 hello-plugin 已经使用函数形式:
import type { Context } from ‘@deepseek-ai/cordis’
export const name = ‘hello-plugin’
export function apply(ctx: Context) {
console.log(‘[hello-plugin] plugin loaded!’)
}
它的三个基本部分分别是:
name :插件的名字,用来在日志、配置树和错误信息中识别它。
apply(ctx) :插件入口。Cordis 挂载插件时调用它。
ctx :当前上下文对象。插件通过它注册服务、监听事件或声明清理。
除函数形式外,插件还支持对象形式和类形式。对象形式适合把 name 、 inject 、 apply 放在一个默认导出
里;类形式适合插件本身提供一个服务。第 04 章已经看过它们的形态,本章的重点是理解这些形态都在表达
同一件事:插件是挂载到 Context 上的一段可逆行为。
第 4 步:把 Context 理解成服务容器
ctx 不是普通的“配置对象”,它是当前插件树共享的服务容器。一个插件可以提供服务,其他插件通过固定
的 key 找到服务,而不是通过 import 直接导入具体实现。
dsh 中常见服务包括:
ctx.tools // 工具注册表服务
ctx.llm // 模型服务
ctx.agents // Agent 服务
ctx.sessions // 会话日志服务
例如 @deepseek-ai/dsh-tools 负责提供 ctx.tools , @deepseek-ai/dsh-agent 负责提供 ctx.agents 。某个
工具插件只需要声明自己需要 tools ,框架就会把实际提供者注入进来。
这种设计的直接后果是:提供方是可替换的。 只要后层配置把某个服务的提供者换掉,依赖该服务的插件不需
要修改代码。
第 5 步:用 inject 声明依赖
如果插件在 apply 中要使用 ctx.tools ,它必须先声明依赖:
import type { Context } from ‘@deepseek-ai/cordis’
export const name = ‘my-tool-plugin’
export const inject = [‘tools’]
export function apply(ctx: Context) {
ctx.tools.register(/ … /)
}
inject 的含义不是“建议先加载”,而是硬性依赖:
声明 inject: [‘tools’] 后, apply 执行时 ctx.tools 一定已经存在。
插件在依赖服务就绪之前会保持等待状态,不会执行一半。
如果运行期间服务消失,例如提供者被卸载,依赖它的插件也会卸载;服务恢复后,插件会重新加载。
因此,配置行顺序不重要,服务依赖才决定加载时机。
如果某项服务是可选的,插件可以不写 inject ,而是在使用处探测:
export function apply(ctx: Context) {
const metrics = ctx.get(‘metrics’)
metrics?.record(‘plugin_loaded’, 1)
}
第 09 章会进一步展开服务与依赖,本章先记住“必需依赖用 inject ,可选依赖用 ctx.get() ”即可。
第 6 步:区分“服务调用”和“事件通信”
服务和事件解决两类不同的问题:
服务适合直接调用某个能力。消费方明确知道要调用什么,例如 ctx.tools.register() 。
事件适合松耦合通信。发出方不需要知道谁在监听,监听方也不需要知道事件由谁发出。
Cordis 事件通过 ctx.on() 监听、通过 ctx.emit() 等分派。常见事件名使用 namespace/action 形式,例如
tools/result 、 agent/request 。
一个最简单的事件监听如下:
export const name = ‘tool-logger’
export function apply(ctx: Context) {
ctx.on(‘tools/result’, (exec, result) => {
console.log(<code>[tool] ${exec.name}</code>)
})
}
ctx.on() 注册的监听器本身就是可逆副作用:插件卸载时,监听器会被自动移除。事件还有多种分派模式,包
括 emit 、 bail 、 serial 、 parallel 和 waterfall 。本章只需要知道“服务用于直接调用,事件用于松耦合
通信”;具体分派模式会在第 10 章展开。
第 7 步:学习阅读 cordis.yml 的方法
cordis.yml 的阅读方法可以总结为下面这张图:
按这个顺序读:
- 先找 – id: 行,确认插件的稳定标识。
- 再看 name ,确认它加载的是 npm 模块还是本地文件 URL。
- 接着看 config 、 inject 和 disabled 。
- 遇到 disabled: true ,说明这一行在本次运行中不参与。
- 其余行判断它的关系: inject 表示它消费服务;如果某个插件提供了服务,其他插件可以按服务名
inject ; config 表示传给该插件的参数。
以第 04 章的 scratch-plugin/cordis.yml 为例:- insert:
- id: hello
name: ‘file:///D:/docker/course-maker/43-deepseek-harness/scratch-plugin/src/my-plugin.ts’
这里 – insert: 表示插入一个新条目, id: hello 是稳定标识, name 指向本地插件文件。它没有 config 和
inject ,说明这个插件不依赖服务,也不接收参数。
第 8 步:在 web 配置树中找出服务提供方和消费方
运行完整配置导出后,可以从输出中识别几组典型关系。
服务提供方
插件 提供的服务
@deepseek-ai/dsh-tools ctx.tools
@deepseek-ai/dsh-llm ctx.llm
@deepseek-ai/dsh-agent ctx.agents
@deepseek-ai/dsh-session ctx.sessions
服务消费方
webserver 声明 inject: [webStartup] ,并从 ctx.webStartup.host 和 ctx.webStartup.port 读取启动
参数。
web-runtime 也声明 inject: [webStartup] ,并使用 ctx.webStartup.trustedHosts 。
第 04 章的 hello-plugin 没有 inject ,所以它不依赖任何服务,只在自己被加载时打印日志。
你可以用一条命令只查看关键字段,避免完整输出过长。
macOS / Linux
npx @deepseek-ai/dsh –profile web –dump-config | grep -E ‘id:|name:|inject:|disabled:’
Windows PowerShell
npx @deepseek-ai/dsh –profile web –dump-config | Select-String -Pattern
‘id:|name:|inject:|disabled:’
第 9 步:验证 hello-plugin 是否成为配置树中的一行
在第 04 章的 scratch-plugin/cordis.yml 存在的情况下,执行:
npx @deepseek-ai/dsh –profile web –dump-config –patch ./scratch-plugin/cordis.yml
在输出的末尾,你会看到类似内容:== D:\docker\course-maker\43-deepseek-harness\scratch-plugin\cordis.yml
- id: hello
name: >-
file:///D:/docker/course-maker/43-deepseek-harness/scratch-plugin/src/my-plugin.ts
这证明:
–patch 是配置树上的最后一层 overlay。
scratch-plugin/cordis.yml 插入的 hello 行已经进入最终配置树。
你的本地插件与 dsh-base 、 dsh-web-app 中的插件处在同一套结构中。
如果还是觉得抽象,可以把它想象成“打印最终菜单”而不是“启动服务”:
–dump-config 只负责把最终配置树打印出来,不启动 Web 服务。
–patch ./scratch-plugin/cordis.yml 只是临时把本地这一层“贴”到配置树最上面。
因此输出末尾多出的 – id: hello ,就是你的插件已经站到了和内置插件同一张菜单里。
图里左边是配置层,从下到上分别是 dsh-base 、 dsh-web-app 、你的 –patch 层;后一层会覆盖前一层。右
边是叠加后的最终配置树, hello 这一行和 llm 、 tools 、 webserver 一样,都是同一个结构中的普通一行。
如果只看最后几行,可以使用:
macOS / Linux
npx @deepseek-ai/dsh –profile web –dump-config –patch ./scratch-plugin/cordis.yml | grep -E
‘hello|scratch-plugin’
Windows PowerShell
npx @deepseek-ai/dsh –profile web –dump-config –patch ./scratch-plugin/cordis.yml | SelectString -Pattern ‘hello|scratch-plugin’
第 10 步:完成本章自检
最后确认你已经能回答:
- 为什么 dsh 的模型适配器、工具注册表和 Web UI 都可以说是插件?
- profile 经过哪几层叠加,形成最终插件树?
- 插件通过什么对象注册服务和监听事件?
- inject 和 ctx.get() 分别适用于什么场景?
- cordis.yml 中 id 、 name 、 config 、 inject 、 disabled 各表示什么?
- 如何用 –dump-config 找到一个插件是服务提供方还是服务消费方?
- 如何验证 hello-plugin 已经在 –patch 后的配置树中?
本章小结
“一切皆插件”不是宣传语,而是运行结构:模型、工具、Agent、会话、Web UI 都是插件,都可以从配
置替换。
profile 是分层叠加的组装结果;后层通过 id 覆盖前层条目, –patch 是最后一层 overlay。
插件通过 name + apply(ctx) 定义;它挂载到共享 Context 上,注册服务、监听事件或声明清理。
Context 是服务容器,消费方按服务 key 使用能力,而不是导入具体实现。
inject 表达硬性服务依赖;依赖就绪后插件才执行 apply ,服务消失时插件卸载并可在恢复后重载。
服务适合直接调用,事件适合松耦合通信; ctx.on() 注册的监听器会随插件卸载自动移除。
阅读 cordis.yml 时,先找 id 和 name ,再看 config 、 inject 、 disabled ,并判断该插件在树中的关
系。