Deepseek harness

内容纲要

一 概念

源码部署的版本: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 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。
  • 当操作在当前权限策略下需要审批时,界面会先询问用户。

file

图中可以看到,<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+。

可以选择以下两种运行方式。

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

  1. 按下 Command + 空格,打开 Spotlight。
  2. 输入 Terminal 或 终端。
  3. 回车打开终端。
  4. 也可以从访达进入:应用程序 → 实用工具 → 终端。

Windows

  1. 按下 Windows 键 + R,打开 "运行" 对话框。
  2. 输入 <code>powershell</code> 或 <code>cmd</code>。
  3. 回车打开 PowerShell 或命令提示符。
  4. 也可以点击 "开始" 菜单,搜索 PowerShell、终端 或 命令提示符 后打开。
  5. 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 时,需要先配置模型。
操作:

  1. 打开 设置 → 模型。
  2. 在 DeepSeek 卡片中找到 API 密钥输入框。
  3. 输入 DeepSeek API Key。
  4. 点击保存。
  5. 确认模型选择器已经出现可用模型。
    保存后,模型路由会立即可用,不需要重启服务器。密钥是只写的:保存后页面只会显示脱敏信息,不会再次显示明文密钥。

如果是用源码部署,直接改源码

路径: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 可以读取和编辑的项目目录。选中工作区之前,会话输入框不可用,因此必须先完成工作区选择。
操作:

  1. 点击 选择工作区。
  2. 添加启动 dsh 时所在的项目目录。
  3. 选中这个目录。
  4. 确认会话输入框已经变为可用状态。

第 4 步:发送第一个任务

启动一个会话并发送任务。可以先用这个任务验证 Web UI 是否正常工作:你好, 你是谁?!
Agent 可以读取和编辑工作区文件、运行命令、委派工作并维护计划。当操作在当前权限策略下需要审批时,Web UI 会先询问你。
操作:

  1. 在会话输入框中发送上面的任务。
  2. 观察 Agent 是否开始读取文件和执行命令。
  3. 如果 Web UI 弹出审批请求,根据任务内容选择允许或拒绝。
  4. 等待 Agent 输出最终回复。
    确认收到 Agent 的回复后,操作完成。

三 CLI 入门:用命令完成任务

前面已经通过 Web UI 完成了一次图形界面操作。这里解决一个更简单的问题:不打开浏览器,也能用一条命令让 dsh 完成项目任务。 学会打开终端和确认命令可用,然后认识两个日常入口—— dsh web 是打开网页版, dsh –profile headless "任务" 是直接提交一个一次性任务。接着明确这两种模式分别适合什么场景,再运行一次 headless 任务,观察最终答案和退出码。最后用“运行方案”的类比理解 profile。

实操步骤

file

上图是完整路径:打开终端后,只需要在“图形界面”和“一次性命令”之间选择一种方式,然后观察结果。下面按这张图逐步操作。
这里命令统一使用 npx @deepseek-ai/dsh 。如果源码运行,并且安装了 pnpm ,也可以把npx @deepseek-ai/dsh 换成 pnpm dsh ,后面的参数完全相同。

第 1 步:打开终端

macOS

  1. 按下 Command + 空格 ,打开 Spotlight。
  2. 输入 Terminal 或 终端 ,回车打开终端。
  3. 也可以从访达进入: 应用程序 → 实用工具 → 终端 。
    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 的场景

  1. 第一次配置模型、API Key 或工作区。
  2. 需要观察 Agent 的思考、计划和工具调用过程。
  3. 需要审批 Agent 的文件修改、命令执行等操作。
  4. 需要调试 Agent 为什么没有按预期完成任务。
  5. 你正在手工使用 Agent,随时可能和它继续对话。

优先使用 headless 的场景

  1. 任务明确,不需要人工逐步审批。
  2. 你只想要最终答案,不关心中间的图形界面。
  3. 要在脚本、CI/CD、定时任务或批处理中调用 dsh 。
  4. 要通过 stdout 和退出码把结果交给另一个程序继续处理。
  5. 运行环境没有浏览器或图形界面,例如远程服务器、容器、自动化流水线。

简单记法:

  1. 需要人看着、批着、调试着,选 web 。
  2. 给一个任务、拿回一个结果、交给脚本用,选 headless 。
  3. 如果任务运行过程中会不断弹出需要你确认的操作,先使用 web 完成;确认流程稳定、可以被当前权限策略自动处理后,再改成 headless 放入自动化。

第 5 步:用 CLI 打开 Web UI

执行:

pnpm dsh web

默认服务地址是:

http://127.0.0.1:3080

操作:

  1. 在浏览器中打开命令打印的地址。
  2. 确认页面可以正常打开。
  3. 回到终端,按 Ctrl+C 停止 Web UI。
    这里只是把启动入口从图形操作改成了命令行。

第 6 步:运行 Headless 一次性任务

现在尝试不打开浏览器,直接让 dsh 完成一个任务。
执行:

pnpm dsh  --profile headless "用一句话说明当前目录下项目的主要功能"

这条命令会:

  1. 把运行命令时所在的目录作为默认 workspace 根目录。
  2. 创建一个全新的持久化 Agent。
  3. 提交任务,并等待 Agent 完成。
  4. 在 stdout 打印最终答案。
    第一次使用 headless 时,它会自动初始化这个运行方案。成功运行时不会打开监听端口。
    如果任务失败且提示与模型凭据有关,请确认秘钥模型是否正确配置

第 7 步:查看退出码

任务完成后,检查命令是否成功:
macOS / Linux

echo $?

Windows PowerShell

echo $LASTEXITCODE

Windows CMD

echo %ERRORLEVEL%

退出码含义:
0 :最终原因是 completed ,任务正常完成。
1 :最终原因不是 completed 。

第一个插件

核心讲解与实操步骤

file

上图是本章的完整路径:认识课程目录 → 查看已有插件 → 创建本地项目 → 编写插件 → 注册到 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 运行。
观察要点:

  1. 每个插件的 id 是配置树里的稳定标识。
  2. 每个插件的 name 是实际要加载的模块名。
  3. 后面我们自己创建的 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 步:验证终端日志和浏览器
依次检查:

  1. 浏览器能正常打开 http://127.0.0.1:3080 。
  2. 终端中出现 [hello-plugin] plugin loaded! 。
  3. 页面本身仍能正常使用;这个插件只输出日志,不会改变界面。

验证完成后,回到终端按 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 步:先建立整体心智模型
先看下面这张图,它会贯穿本章和后续章节:

file

这张图包含三层信息:

  1. Profile 组装:一个 profile 不是单个配置文件,而是多层叠加的结果。 dsh-base 先提供模型、工具、会话等基础插件, dsh-web-app 或 dsh-headless 再增加运行形态,个人 profile patch 和 –patch overlay最后覆盖。

  2. 运行时插件树:模型适配器、工具注册表、Agent 主循环、会话日志、Web UI 运行,都是同一棵树上的插件。它们不是“外围扩展”,而是产品本体。

  3. 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 的阅读方法可以总结为下面这张图:
按这个顺序读:

  1. 先找 – id: 行,确认插件的稳定标识。
  2. 再看 name ,确认它加载的是 npm 模块还是本地文件 URL。
  3. 接着看 config 、 inject 和 disabled 。
  4. 遇到 disabled: true ,说明这一行在本次运行中不参与。
  5. 其余行判断它的关系: 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 | Select￾String -Pattern ‘hello|scratch-plugin’
      第 10 步:完成本章自检
      最后确认你已经能回答:
  6. 为什么 dsh 的模型适配器、工具注册表和 Web UI 都可以说是插件?
  7. profile 经过哪几层叠加,形成最终插件树?
  8. 插件通过什么对象注册服务和监听事件?
  9. inject 和 ctx.get() 分别适用于什么场景?
  10. cordis.yml 中 id 、 name 、 config 、 inject 、 disabled 各表示什么?
  11. 如何用 –dump-config 找到一个插件是服务提供方还是服务消费方?
  12. 如何验证 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 ,并判断该插件在树中的关
    系。

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部
黔ICP备2025064559号 | 贵公网安备52022202000316号