DeepSeek Harness 插件 vs 技能:你到底需要哪个?
插件改变 harness 能做什么,技能改变 agent 知道什么。对照表、真实截图、两个完整实例,再加三个帮你拍板的问题。
最近更新: 2026-09-09
DeepSeek Harness 自带两套听起来很像的扩展机制:插件和技能。官方首页的口号是 "everything is a plugin",但 agent 同时也会老老实实读取你仓库里的 Markdown 技能文件。把这两者搞混,结果是要强制执行的地方写了个技能,或者一个 Markdown 文件就能解决的事造了个插件。
这一页用证据而非感觉来区分两者:下面每张截图都来自真实会话,并且回链到源视频的精确秒数;每条结论都来自这两支视频或 DeepSeek 官方首页原文。
技能是一个 Markdown 指令文件 —— 通常是 .agents/skills/<name>/SKILL.md —— 作用是补充上下文:agent 会读它、通常照着做,但没有任何机制强制。插件是接进 harness profile 的 Cordis 包,装在仓库之外:它能新增工具、替换审批策略,甚至能在工具调用执行前直接拦截。要引导,写技能;要保证,造插件。
官方定位,逐项对照
DeepSeek 官网用一句话讲清了架构:"Every capability is a plugin that can be swapped or recomposed: models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI." 注意细读:技能出现在"可替换物"的清单里,而插件是这一切的封装单元。
在一个跑起来的实例里,插件以设置面板里一排开关的形式出现 —— harness 本身就是散件交付的,每个部件都能关掉:
| 维度 | 插件 | 技能 |
|---|---|---|
| 本质 | Cordis 包,向 harness 本体注入一种能力 —— 工具、审批策略、定时任务,甚至 UI。 | Markdown 指令文件(SKILL.md),给 agent 补充上下文和步骤。 |
| 存放位置 | 仓库之外:软链到 ~/.dsh/profiles/<profile>/node_modules,并在 profile 的 cordis.patch.yml 里注册。 | 项目内 .agents/skills/<name>/SKILL.md —— 或全局技能目录,会话会自动拾取。 |
| 分发方式 | 走插件目录和 GitHub 仓库;安装进 profile,下次 harness 重启时加载。 | 把文件拷进仓库即可 —— 立刻出现在会话的技能目录里。 |
| 能力边界 | 能强制:插件 hook 可以在工具调用执行前直接拒绝(同步的 ctx.tools.guard() API)。 | 只能建议:agent 通常照步骤做,但没有任何东西强制它照做。 |
| 适用场景 | 改变 harness 能做什么:新工具、安全护栏、审批流程、定时任务。 | 教 agent 你希望一件重复的事怎么做:提交规范、SOP、检查清单。 |
还是拿不准?问自己三个问题
它必须被保证,还是大概率照做就行?
如果漏一步就是事故(碰生产数据库、破坏性 git 操作),你需要强制:插件 hook,或者让技能里的某一步跑确定性脚本。如果只是风格和流程 —— 提交信息、spec 工作流 —— 技能就够了。
它属于仓库,还是属于这台机器?
应该随仓库走、给全团队共享的团队约定,放进跟代码一起提交的技能文件。机器层面的能力 —— 拦直连 psql、加一个定时任务工具 —— 放进装在这台机器 profile 里的插件。
一个文件的英文说明能不能说清?
如果 Markdown 里几步白话就够了,就写技能 —— 并且让 agent 替你起草;crash course 的博主就让 AI 写他的技能,因为写得比他自己还周全。一旦需要保证执行,就升级:把那一步变成脚本,或者做成 hook 插件 —— 视频里走的正是这条升级路径。
实例一:commit 技能(写一个技能)
在 Agentic AI crash course 里,博主需要一个可复用的提交流程:全部提交、信息干净、绝不 push。一条提示词就产出一个技能 —— 整个过程在视频里只花了两三分钟。
- 1
一条消息把技能说清楚
提示词要求创建一个负责 commit 的技能:不署 AI 名、信息用简洁的要点列表、快速检查不该提交的东西、默认提交所有工作区文件、绝不 push 或部署。
整个需求就是一段白话消息 —— 没有 SDK,没有样板代码。看原视频 15:50 - 2
agent 写文件并当场注册
技能从 .agents/skills/<name>/SKILL.md 这类项目根路径被发现。新的 commit 技能立刻出现在会话的技能目录里 —— 输入框的斜杠菜单能看到 agent 可调用的所有技能。
保存为 .agents/skills/commit/SKILL.md —— 当场进入会话目录。看原视频 17:00 
敲一个斜杠,目录里就是 agent 能调用的所有技能。看原视频 10:55 - 3
当成 Markdown 来读:frontmatter、步骤、规则
生成的文件带 frontmatter(name、description、whenToUse),从 git status 到 verify 共六步,外加"不署名""绝不 push 或部署"这类规则。它就是个文件 —— 随时可以手动改。
技能就是 Markdown:frontmatter、编号步骤、规则。看原视频 18:00 
第二支视频用动画演示同一个结构:先描述,后步骤。看原视频 10:45 - 4
把模糊步骤升级成确定性脚本
"快速安全检查"原本靠模型判断,于是让 agent 把它转换成 scripts/check-commit-safety.sh,用退出码表示结论:0 安全、1 有问题、2 环境错误。当场实测:故意埋的 .env 文件被 deny 规则拦下 —— 相同的 git 状态进,相同的结论出。
模糊步骤变成了脚本:0 安全,1 有问题,2 环境错误。看原视频 19:30
实例二:git-protect 插件(造一个插件)
同一支视频的后半段,仓库需要一个"破坏性 git 命令永远跑不了"的保证 —— 光靠引导不行。agent 最终造了一个插件,整个过程把对照表里插件的特征全演了一遍。
- 5
要一个 hook;批准工作区外的写入
agent 找到了正确的扩展点:工具注册表暴露了 ctx.tools.guard() API —— 一个能在工具调用执行前拒绝它的同步 hook。接线需要写到工作区之外,所以屏幕上先弹出审批对话框。
插件装在仓库之外 —— 写入前 agent 会先请求批准。看原视频 24:30 - 6
造了什么:contract、profile 接线、重启
产物是真正的代码:.agents/git-protect/hook/index.mjs,带 Cordis contract(name、inject: ['tools']、apply),软链进 ~/.dsh/profiles/node_modules 并通过 cordis.patch.yml 注册。屏幕上的注意事项写明:web profile 关闭了 HMR,插件要等下次 harness 重启才生效。
插件是带 contract 的真代码 —— 而且要重启才加载。看原视频 25:00 - 7
验证强制力
重启之后,git reset --hard 和 git branch -D 探测都被拦下 —— 拒绝来自 hook 而不是 shell —— 而 git status、git log、git diff 正常通过,待提交的 spec.md 改动完好无损。
破坏性命令在 harness 层被拒 —— 不靠客气。看原视频 26:30
两者如何协作
这两种机制是分层,不是对手。视频里的同一个仓库最后两者都有:commit 技能让每次提交都干净,git-protect 插件保证破坏性命令在 harness 层就被拒绝 —— 不管对话里说了什么。
还有一个反方向:存在专门教 agent 造插件的技能。入门向那支视频里,agent 在 creator mode 搭建新插件时加载了 cordis-plugin-development 技能 —— 用技能生产出整套架构所依赖的插件。
The full guardrail stack is now active: the harness hook (tool-level deny), the commit skill (safety check → ignore resolution → clean local commits), and AGENTS.md policy.
crash course 视频约 26:30 处的屏幕总结
常见问题
这一页最常被问到的问题,答案全部来自视频与官方原文。
DeepSeek Harness 的技能文件放在哪?
项目技能放在仓库根目录的 .agents/skills/<name>/SKILL.md —— 视频里的 agent 说这是项目级、会被自动发现。也支持全局技能:第二支视频里,他原有 Claude Code 配置中的全局技能就被自动拾取进来了。
技能能执行工具和命令吗?
技能本身只是指令 —— 默认 agent 会读它并自行解释步骤。想要可预期的结果,学 crash course 的做法:附一个脚本(check-commit-safety.sh)让步骤去执行它,或者把检查绑成 hook,从"建议"升级成"强制"。
插件能做到哪些技能做不到的事?
改变 harness 本身。插件可以注入工具、在工具调用执行前拒绝它、替换审批策略、增加定时任务之类的能力;它接在仓库之外的 profile 上,重启时加载。技能只能给对话补充上下文。
官方对插件和技能的定位原话是什么?
官网首页写的是:"Every capability is a plugin that can be swapped or recomposed: models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI." 换句话说,技能是清单里的一项能力,而插件是这一切(包括技能)的出厂封装单元。
我从 Claude Code 迁移过来,技能还能用吗?
基本能用:技能就是纯 Markdown。crash course 提到,仓库里已有的本地技能 harness 应该能直接读;第二支视频里 Claude Code 的全局技能也被自动拾取了。插件是例外 —— 它绑定 Cordis,需要为 DeepSeek Harness 重新构建或安装。
为什么我的插件没有马上生效?
因为 web profile 关闭了 HMR,新接线的插件要等下次 harness 重启才生效 —— 视频里的注意事项原话就是这么说的。验证方法:让 agent 跑一条该插件应拦截的命令,你应该看到 hook 拒绝而不是 shell 结果。
相关攻略
分清要用哪个之后,接着读这些。
来源与署名
本页所有截图来自这两支视频攻略,每张图都深链回它被截取的精确秒数。上面的文字讲解是我们自己写的。