手册/第 10 章
动手:从跑起来到写第一个插件
这一章的所有命令都来自仓库文档,可以照抄。 顺序刻意设计成「先看树,再改树」——这样你写的第一个插件不会挂在错误的层上。
第一步:跑起来
npx @deepseek-ai/dsh web
默认在 http://127.0.0.1:3080 起 Web UI 并打开浏览器;加 --no-open 只起服务不开浏览器。
从源码跑则是(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)。
第二步:把树打印出来
在看任何源码之前,先看你这台机器实际启动了什么:
dsh --profile web --dump-config
它会打印组合出来的 profile 树然后退出。看三件事:
idid 定位并整块替换 config 的。
记住你想改的那行的 id,比记住包名有用。
dsh-base,哪几行来自 dsh-web-app。
你的 patch 会盖在它们之上。
配套的两个命令:--dump-default-config 打印去掉用户层与 --patch 之后的裸树
(用来判断「这是官方默认还是我改过的」);--dump-config-schema 只打印 JSON Schema,不挂载
(写 patch 时查字段用)。
第三步:写第一个插件
官方教程的路径最短,直接照它走(docs/user/develop/basic/index.md)。
先建一个草稿项目:
mkdir -p scratch-plugin/src
插件就是一个导出 apply 的 TypeScript 模块:
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。注意路径必须是绝对路径:
- insert:
- id: hello
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
pnpm dsh web --patch ./scratch-plugin/cordis.yml
打开 http://127.0.0.1:3080,启动时终端会打印 [hello-plugin] plugin loaded!。
第四步:理解「自动清理」与 inject
通过 ctx 注册的一切——事件监听、工具、定时器——在插件卸载时自动清理,
不需要你手写 removeListener。需要显式释放的资源(比如网络连接)用 ctx.effect() 交出 disposer:
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——
框架会等这些服务就绪再加载你,所以加载顺序不需要你操心:
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」) |
docs/user/develop/basic/index.md · 第一个插件 architecture.md:34 · --dump-config README.md:33 · 从源码运行