夜雨聆风学习资料网

ARTICLE · 1364433

万物皆插件:上手 DeepSeek 开源 Agent 框架

万物皆插件:上手 DeepSeek 开源 Agent 框架
DeepSeek 官方开源的 Agent 框架 DeepSeek Harness(简称 dsh),三个月冲到 28 万 star。核心理念只有一句:万物皆插件——从模型适配器、工具注册表到 Agent 循环本身,全部可插拔。这篇带你真机跑一遍,再亲手写一个工具插件,接本机 Ollama 真跑一轮调用。

01它是什么:连 Agent 循环都是插件

dsh 是 DeepSeek 官方的 agent harness,npm 包名 @deepseek-ai/dsh,MIT 协议。底层是插件框架 Cordis(以 vendor 方式内置),每个插件导出一个 apply(ctx) 函数,向共享上下文注册服务、事件和副作用。

官方架构文档说得直白:不存在需要打补丁的特权内核。模型适配器、工具、会话日志、agent 循环都是插件,所以每一个都能从配置里替换;注册是可逆副作用,插件卸载时自动清理。

数据核对:GitHub API 显示它是 TypeScript 项目,281,301 star / 34,760 fork(核对于 2026 年 11 月 15 日),2026-08-13 创建,最近一次推送 11 月 13 日,1.2K 人 watching。

02为什么值得前端工程师学

第一,它是 TypeScript 写的。插件就是一个导出函数的 .ts 文件,心智模型和写 Vue、React 插件几乎一致:声明依赖、注册能力、自动清理。

第二,中文文档是一等公民。docs 目录里插件教程、架构文档、工具编写参考全都有 .zh.md 版本,读起来不吃力,这在一线开源项目里相当少见。

第三,依赖注入、类型化事件、副作用回收这套设计,正是前端工程化里最少被练到、而在 AI Agent 时代最吃香的部分。写完一个 dsh 插件,你对插件化架构的理解会上一个台阶。

03三步跑起来

官方 README 给的姿势最简单:装好 Node.js,一条命令起 Web UI。npm 上最新版 0.2.2-rc.1(2026-11-04 发布,已累计 44 个版本),包体不小,全新环境实测装了 656 个包、约 9 分钟,缓存命中后约 3 分钟。

mkdir -p /tmp/p && cd /tmp/pnpm init -ynpm i @deepseek-ai/dsh
npx @deepseek-ai/dsh web

默认监听 127.0.0.1:3080 并自动打开浏览器,启动日志打印一条带 token 的地址,用它访问即可;无桌面环境加 --no-open。

实测提示:官方 engines 要求 Node >= 24.9.0,我本机是 v22.22.2,--version、web、headless 全部正常跑通。毕竟是 developer preview,遇到奇怪报错先怀疑 Node 版本。

Web UI 是中文界面:左侧是插件、自动化任务和工作区,首次进入会弹预览版说明,右下角是模型选择器。选好工作区就能开聊,但想让 Agent 干活,还得先配模型。

04看懂你的插件树

dsh 启动不是"跑一个程序",而是组装一棵插件树:profile 定义叠放顺序,bundle 是分发单元,你的 patch 永远排最后一层。内置 profile 有 web、headless、sdk、sdk-minimal、acp。

npx @deepseek-ai/dsh --profile web \  --dump-config
- id: llm  name: '@deepseek-ai/dsh-llm'- id: session  name: '@deepseek-ai/dsh-session'- id: agent  name: '@deepseek-ai/dsh-agent'

打印出来的每个条目都可以被你自己的 patch 替换——这就是万物皆插件的操作面:覆盖即扩展,不需要 fork 源码。

05写一个真正的工具插件

来点真的:写一个 greet 工具注册给模型。插件就是一个 TS 文件,导出 name、inject、apply 三样;inject: ['tools'] 声明依赖,框架会等工具注册表就绪再加载你。

// src/my-plugin.tsimport type { Context } from  '@deepseek-ai/cordis'import { defineTool } from  '@deepseek-ai/dsh-tools'export const name = 'greet-tool'export const inject = ['tools']export function apply(ctx: Context) {  console.log(    '[greet-tool] plugin loaded!')  ctx.tools.register(defineTool({    name: 'greet',    description:      'Greet someone by name.',    parameters: {      name: {        type: 'string',        required: true,        description:          'The name to greet',      },    },    output: {      schema: { type: 'string' },      render: (_a, v) =>        [{ type: 'text', text: v }],    },    async execute(args) {      return `Hello, ${args.name}!`    },  }))}

几个关键点:defineTool 会在 execute 之前按 parameters 校验模型生成的参数;返回值必须符合 output.schema 声明的规范值;output.render 把规范值转成模型可见文本。

然后写一份 patch 文件把插件插进配置树,注意插件路径必须是绝对路径:

- insert:    - id: greet      name: '/tmp/p/src/my-plugin.ts'
踩坑一:patch 里的插件路径必须写绝对路径,相对路径会解析到 profile 目录而不是当前目录。踩坑二:插件 import 的包按 Node 规则从插件文件所在目录向上找 node_modules,插件必须放在 npm i @deepseek-ai/dsh 的项目里,放错位置会报 ERR_MODULE_NOT_FOUND,而且启动日志只有一行 1 entry did not activate,很容易漏看。

06接上本机模型,零密钥真跑一轮

模型配置写在同一份 patch 里:llm-pi-ai 插件接受自定义 provider,OpenAI 兼容端点选 openai-completions 协议。我用本机 Ollama 的 qwen3.5:9b-ctx32k,一个 API Key 都不用填:

- insert:    - id: greet      name: '/tmp/p/src/my-plugin.ts'- id: llm-pi-ai  config:    providers:      ollama:        apiKeyEnv: DSH_OLLAMA_KEY        api: openai-completions        baseURL: >-          http://localhost:11434/v1        models:          - id: qwen3.5:9b-ctx32k- id: agent-default-model  config:    provider: ollama    model: qwen3.5:9b-ctx32k

改配置不用重启——YAML 接管 HMR,配置变更会触发插件热替换。用 headless profile 一条命令跑通端到端:

DSH_OLLAMA_KEY=ollama npx \  @deepseek-ai/dsh headless \  --patch ./cordis.yml \  "Use the greet tool to greet Ada."
[greet-tool] plugin loaded!dsh: reasoning: The user is asking me to use the greet tool to greet Ada. This is a simple task that doesn't require any skills or complex analysis. I'll just call the greet tool with the name "Ada".dsh: reasoning: The greet tool worked successfully. It returned "Hello, Ada!" as the greeting for Ada. I should share this result with the user.Hello, Ada!

以上是真实终端输出:插件加载日志、模型两段 reasoning、最后工具结果 Hello, Ada!。Web UI 里同样成立——发送同一句话,1 分 32 秒后回复 Hello, Ada! 👋,用量 18.7K tok,底部状态栏显示 1 轮 2 步,模型已切到 qwen3.5:9b-ctx32k。

9B 小模型一轮推理要一分钟左右,干活嫌慢,但验证插件链路绰绰有余:工具 schema 自动注入系统提示词,模型自主决定调用,结果按规范值回传,整条链路和接 DeepSeek 官方 API 完全一致。

07工具 DSL 里最值得抄的设计

参数校验前置。defineTool 在执行前按统一 schema 校验类型、必填键和联合类型分支,插件作者不用再写防御式判空,args 直接带类型。

展示与模型解耦。output.render 返回模型可见内容;UI 卡片走独立的 presentCall / presentResult,内置 terminal、diff、read、search、web 五种卡片语义,且都是纯函数,回放永不崩溃。

后台任务有完整生命周期。长时间工作用 ctx.jobs.start() 注册,同步拿到 cancel、done 和拉取式 output,取消信号与会话围栏由运行时保证,不靠解析自然语言拿任务 id。

配置即热更。插件导出 Schemastery schema,用户改 cordis.yml 就触发热替换,非法配置在加载期就响亮报错:

export const Config: Schema<Config> =  Schema.object({    greeting: Schema.string()      .default('Hello'),    maxRetries: Schema.number()      .default(3),  })

副作用回收同理,用 ctx.effect() 返回清理函数,插件卸载时自动执行,不用手写 removeListener:

ctx.effect(() => {  const timer = setInterval(    () => console.log('heartbeat'),    5000)  return () => clearInterval(timer)})
npx @deepseek-ai/dsh plugin \  --profile tui add <package>
npx @deepseek-ai/dsh tui \  --patch ./extra.yml

彩蛋:PTC 模式下所有已注册工具自动变成程序化 API,插件内直接 await tools.greet(args) 即可调用。想装别人的插件也是一条命令:npx @deepseek-ai/dsh plugin --profile tui add <package>。

08它不适合什么场景

它还在 developer preview,官方明说会有兼容性破坏变更,生产环境先观望。另外概念比同类框架多一层:profile、bundle、patch、overlay,上手成本实打实存在。

如果只想给现有应用加个聊天窗口,官方 SDK 或现成 UI 库更省事;如果你想真正掌控 Agent 的每个环节——工具、权限、持久化、遥测——dsh 这套插件架构是我目前见过表达力最强的方案之一。

09参考资料清单

▪︎ 项目地址:github.com/deepseek-ai/deepseek-harness

▪︎ 官方文档:deepseek-harness.github.io/deepseek-harness

▪︎ 插件教程:仓库内 docs/user/develop/basic/index.zh.md

▪︎ 工具编写参考:docs/cookbook/adding-a-tool.zh.md

▪︎ npm 包:@deepseek-ai/dsh,MIT 协议

▪︎ 数据说明:star/fork/版本号来自 GitHub API 与 npm registry,核对于 2026 年 11 月 15 日

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料