DeepSeek Harness 学习手册 第 10 / 11 章 总目录 单页全本 架构图 GitHub

手册/第 10 章

10

动手:从跑起来到写第一个插件

这一章的所有命令都来自仓库文档,可以照抄。 顺序刻意设计成「先看树,再改树」——这样你写的第一个插件不会挂在错误的层上。

第一步:跑起来

sh · README.md:22-25
npx @deepseek-ai/dsh web

默认在 http://127.0.0.1:3080 起 Web UI 并打开浏览器;加 --no-open 只起服务不开浏览器。 从源码跑则是(README.md:33–39):

sh · README.md:33-39
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

pnpm run build 准备产物;pnpm dsh web 直接使用这些已构建产物,不会重新构建。 改前端源码时用 pnpm run dev:web(构建 + 起服务 + 监听源码变化重建,README.md:57)。

第二步:把树打印出来

在看任何源码之前,先看你这台机器实际启动了什么:

sh · docs/architecture.md:34
dsh --profile web --dump-config

它会打印组合出来的 profile 树然后退出。看三件事:

Ⅰ共多少行
这就是「一个 web 形态的 dsh」实际挂载的插件条目数量。 对着第 08 章的表,你能认出每一行大概负责什么。
Ⅱ每行的 id
patch 是按 id 定位并整块替换 config 的。 记住你想改的那行的 id,比记住包名有用。
Ⅲ层与层的边界
哪几行来自 dsh-base,哪几行来自 dsh-web-app。 你的 patch 会盖在它们之上。

配套的两个命令:--dump-default-config 打印去掉用户层与 --patch 之后的裸树 (用来判断「这是官方默认还是我改过的」);--dump-config-schema 只打印 JSON Schema,不挂载 (写 patch 时查字段用)。

第三步:写第一个插件

官方教程的路径最短,直接照它走(docs/user/develop/basic/index.md)。 先建一个草稿项目:

sh
mkdir -p scratch-plugin/src

插件就是一个导出 apply 的 TypeScript 模块:

typescript · scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // Required dependencies are ready before apply runs.
  console.log('[hello-plugin] plugin loaded!')
}

然后用一份 overlay 把它插进 web profile。注意路径必须是绝对路径:

yaml · scratch-plugin/cordis.yml
- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
sh · 带上 overlay 启动
pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开 http://127.0.0.1:3080,启动时终端会打印 [hello-plugin] plugin loaded!。

第四步:理解「自动清理」与 inject

通过 ctx 注册的一切——事件监听、工具、定时器——在插件卸载时自动清理, 不需要你手写 removeListener。需要显式释放的资源(比如网络连接)用 ctx.effect() 交出 disposer:

typescript
export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => {
      console.log('heartbeat')
    }, 5000)

    // The returned function runs when the plugin unloads.
    return () => clearInterval(timer)
  })
}

要用别的服务(tools、llm),就声明 inject—— 框架会等这些服务就绪再加载你,所以加载顺序不需要你操心:

typescript
export const name = 'my-tool-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools is ready here.
}

自检清单:我到底改对层了吗

现象多半是
插件没被加载cordis.yml 的 name 用了相对路径(必须绝对)
加载了但拿不到 ctx.tools漏了 inject: ['tools']
你改的 config 没生效被上层 patch 覆盖了——用 --dump-config 看最终值
下游插件静默失效waterfall 里没调 next() 却本意只是观察
重启后你的状态丢了你把它做成了 Agent 事件,而它应该是一个 Session 事件
改了行为但前端看不到只发了 live 事件,没有落成 Session 事件(违反「Model-visible means logged」)
下一步去哪 官方有一份 extension cookbook,按「功能 → 能力」索引了分步指南: 加一个包、加一个工具、加一个 LLM 适配器、加一张设置卡片。 路径见第 11 章。

docs/user/develop/basic/index.md · 第一个插件 architecture.md:34 · --dump-config README.md:33 · 从源码运行

本章学习记录

记录仅保存在当前浏览器。