ARTICLE · 1364433
万物皆插件:上手 DeepSeek 开源 Agent 框架
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/dshnpx @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 日














































































