手把手写一个 DeepSeek Harness 插件挂上 dsh-plugin 生态前四篇把 Harness 从「是什么」讲到「怎么用 SDK 驱动」。这一篇回到它最核心的承诺——「一切皆插件」——用一次真实的插件开发证明这句话对第三方开发者意味着什么你可以在不碰 Harness 源码的前提下给它加一个全新的能力。开写。一、先搞懂什么是一个「插件」在 Cordis 的语境里一个插件就是一个向共享上下文ctx贡献服务、监听事件、并声明可逆副作用的模块。用大白话说一个 Harness 插件要回答三个问题贡献什么向ctx注册一个服务比如一个工具、一个模型适配器、一个会话后端监听什么监听并拦截某些事件比如tools/*、agent/turn-stopping怎么清理卸载时如何撤销自己做的所有副作用。官方文档给了一张「如何扩展」的速查表非常实用你想做的事怎么做添加模型提供方在ctx.llm注册其适配器添加工具在ctx.tools注册其 schema 加入提示词组装拥有不同能力集合的 Agent组装一个 agent preset服务行需要isolaterealm添加 shell 执行注册ctx.shell本地后端通过ctx.subprocessspawn 进程添加持久化终端执行注册ctx.terminals后端 dsh-tool-terminal添加用户命令在ctx.commands注册无需模型轮次即可分派添加后台工作在ctx.jobs注册job_*工具负责收集或停止添加文件系统访问或策略注册ctx.fs提供方或监听fs/*事件限制所启动的进程使用ctx.sandbox后端拦截请求、工具或轮次使用相应事件如tools/*、agent/turn-stopping二、最小插件一个「今日新闻」工具我们写一个最简单的工具插件给 Agent 加一个get_today_news工具让它能查询「今日 AI 头条」。1. 目录结构dsh-plugin-today-news/ ├── package.json ├── tsconfig.json └── src/ └── index.ts2. package.json关键是把 scope 设对并声明对deepseek-ai/cordis的 peer dependency这是 DSH 插件的约定{name:dsh-plugin-today-news,version:0.1.0,type:module,main:dist/index.js,files:[dist],peerDependencies:{deepseek-ai/cordis:*},scripts:{build:tsc}}3. src/index.ts核心思路定义一个 Cordis 插件向ctx.tools注册一个工具。工具的 schema 会被自动加入系统提示词的组装模型就能「看见」并调用它importtype{Context}fromdeepseek-ai/cordis// 工具 schema告诉模型这个工具长什么样、怎么用consttodayNewsSchema{name:get_today_news,description:获取今日 AI 行业头条新闻按热度排序,input_schema:{type:object,properties:{limit:{type:number,description:返回的新闻条数默认 5,},},},}exportfunctionapply(ctx:Context){// 向工具注册表贡献一个工具ctx.tools.register({...todayNewsSchema,asyncexecute(params:{limit?:number}){constlimitparams.limit??5// 这里可以是任何逻辑调 API、读文件、查库……constnewsawaitfetchTopNews(limit)return{content:news.map(n-${n.title}热度${n.heat}).join(\n),}},})}asyncfunctionfetchTopNews(limit:number){// 示意实际接一个新闻源 APIreturn[{title:DeepSeek Harness 45 小时 14 万 Star,heat:9999},{title:DeepSeek V4-Pro 正式版发布,heat:8888},].slice(0,limit)}这个插件做完后装进 HarnessAgent 就能在对话里被「激活」出get_today_news工具调用——因为它已经通过ctx.tools.register进入了工具的 schema 组装流程。三、如何安装插件官方提供了dsh plugin命令来管理插件。两种安装方式从 npm 安装dsh plugin--profileheadlessadddsh-plugin-today-news从 GitHub 源码安装dsh plugin--profileheadlessaddgithub:yourname/dsh-plugin-today-news安装后验证插件是否成功挂载dsh--profileheadless --dump-config|grepdsh-plugin-today-news如果能看到你的插件出现在配置里就说明挂载成功了。四、给插件加事件拦截做一个「命令白名单」工具注册是最简单的。更有价值的插件是拦截型的——监听事件在不改其他插件的前提下插入自己的逻辑。比如写一个「命令白名单」插件只允许 Agent 执行git、ls、cat等安全命令其他命令一律拦截importtype{Context}fromdeepseek-ai/cordisconstALLOWEDnewSet([git,ls,cat,grep,wc,find])exportfunctionapply(ctx:Context){// 监听工具执行事件在 Bash 工具真正跑命令前拦截ctx.on(tools/pre-execute,(payload){if(payload.toolNamebash){constargvpayload.argv??[]constcmdargv[0]??if(!ALLOWED.has(cmd)){// 阻断执行返回一个错误给模型payload.deny(Command ${cmd} is not allowed by policy.)}}})}这个例子展示了 Cordis「事件 拦截」的威力你没有改动 Bash 工具插件的一行代码却成功地在它的执行链路上插了一层安全策略。这正是官方文档说的「拦截请求、工具或轮次使用相应的tools/*事件」。五、发布到生态dsh-plugintopic要让你的插件被社区发现官方给出了明确指引给你的插件仓库添加dsh-plugintopic。在 GitHub 仓库的 About 区域添加dsh-plugintopic 后你的仓库就会进入官方的 topic 聚合页github.com/topics/dsh-plugin被各种 awesome 索引和自动扫描工具收录。目前生态的几类索引索引说明awesome-dsh-plugin人工精选中英双语awesome-dsh-plugins自动扫描收录所有 dsh 插件候选awesome-deepseek-harness精选插件、工具、基础设施dsh-handbook从 0 到 1 的深度手册发布插件时建议README 写清楚插件装了什么工具/技能、依赖什么、怎么配置加dsh-plugintopic提交到精选索引提 PR进 Discord 社区宣传官方鼓励插件开发者加入讨论。六、生态的想象空间从「聊天机器人插件」到「Agent 插件」这一节的最后说一个更宏观的判断。DeepSeek Harness 的插件机制不是凭空发明而是「Koishi 聊天机器人生态」在 Agent 领域的复刻。当年 Koishi 靠 Cordis 把 QQ、Discord、Telegram、微信的几十个插件拼在一起成了聊天机器人圈的现象级项目。如今同一个 Cordis 内核被搬进 Agent 产品通讯工具插件已经出现——飞书机器人、QQ 机器人、Telegram、桌面通知……当年那条「插件生态」的路正在 DSH 上重演。区别只有一个这一回底层自带一条 Agent Loop。这意味着什么意味着插件不再是「给机器人加一个发消息的渠道」而是「给一个能自主干活、调用工具、派发子任务的智能体加一种新的能力」。插件生态的天花板从「聊天机器人能做什么」抬高到了「Agent 能做什么」。七、小结这一篇我们完整走了一遍第三方插件开发的最小闭环注册工具→ 向ctx.tools贡献schema 自动进提示词组装监听事件→ 用tools/*事件在不改源码的前提下插入策略安装挂载→dsh plugin add--dump-config验证发布生态→ 加dsh-plugintopic进精选索引。这就是「一切皆插件」对开发者的真实含义你不用等官方实现某个能力你自己就能实现而且不用改 Harness 的一行源码。五篇写到这里DeepSeek Harness 的「是什么 → 架构 → 对比 → 驱动 → 扩展」已经完整。它是一个还没有长出「人皮」的 Agent 骨架但它把最关键的「定义权」交还给了开发者。下一个 Agent 时代的地基可能正在这里浇筑。标签#DeepSeek #Cordis #插件开发 #AI Agent #dsh-plugin