dsh-plugin-skills
给 AI agent 用的 DeepSeek Harness(DSH)技能包:怎么构建 DSH 插件,以及怎么写 DSH 技能。
⚠️ 时效性:所有"已实测"结论基于
dsh --version = 0.2.2-rc.1(2026-11,npmlatest/next通道)。DSH 每个版本都会翻转一些行为,本仓库会跟着版本重验并在 sources.md 里写明"这条适用于哪版"。0.2.1 → 0.2.2 的破坏性变更:补丁与 Include 的写入语义重写(EntryTree.write()移除,运行期改动写回父 patch)、session projection 的帧与快照语义变化、dsh.bundle新增platforms/listedByDefault、客户端资源改走./assets/*、文件工具策略默认关闭并新增apply_patch。0.2.0 → 0.2.1 的变更(engines.dsh强制且优先于 peer、子路径插件不再读package.json、图标可用exports["./icon"]、dsh plugin --profile位置固定)记录在同目录 sources.md 的历史对照里。升级后第一件事是读docs/upgrade-guide/<版本>/。
版本目录
按适配的 dsh 版本分目录,互不影响;scripts/install.sh 优先使用与本机 dsh --version 同名的目录,探测不到时回退到最高版本目录。
| 目录 | 状态 | 说明 |
|---|---|---|
| 0.2.2-rc.1/ | ✅ 已实测 | 当前推荐。本机安装版;事实表由安装产物生成(330 包 / 112 服务 / 102 事件 / 109 slot)。见 STATUS |
| 0.2.1-rc.2/ | ✅ 已实测 | 旧版运行时核对;事实表由安装产物生成 |
| 0.2.1-rc.3/ | 📐 静态分析 | 基于 tag 源码与文档差分。见 STATUS |
| 0.2.1-rc.4/ | 📐 静态分析 | docs/** 与 rc.3 零差异。见 STATUS |
| 0.2.1-rc.5/ | 📐 静态分析 | 插件作者六文件与 rc.4 零差异;新增 reasoning-body-props 升级指南。见 STATUS |
选版本 = 选与你 dsh --version 一致的目录。跨版本结论不保证成立(本仓库已记录过多次行为翻转)。
包含的技能
| 技能 | 用途 |
|---|---|
| dsh-plugin-construction | 构建/打包/安装/验证/排障 DSH 插件与 bundle:package.json 的 dsh 字段、cordis.patch.yml、Host 插件契约、Web UI 客户端插件、依赖解析与 profile 层序、静默失败排查 |
| dsh-skill-authoring | 编写/组织/验证 DSH 技能:发现根目录与优先级、frontmatter 校验规则、资源目录、调用策略、目录长度上限、"写完为什么没被加载" |
| dsh-plugin-construction/references/internals | DSH 内部结构解构:Cordis 基底、启动与组合、一次 turn 的运行时、服务地图、扩展缝阶梯、UI 半边、官方插件解剖与重构检查单 |
dsh-plugin-construction 的参考文件:
| 文件 | 内容 |
|---|---|
| plugin-package.md | dsh 字段与类型定义、bundle/profile 语义、加载层序、依赖解析、版本兼容门、分发形态 |
| host-plugin.md | 插件三种导出形态、生命周期与清理、Config、服务与依赖、事件模型、defineTool、会话红线 |
| client-plugin.md | dsh.client、window.__ModuleLoader__、slot 注册、主题与 locale、展示元数据、验证边界 |
| install-verify.md | dsh plugin 安装、三级验证阶梯、排障表、清理 |
| sources.md | 来源清单、版本差异对照、实测清单、未验证项、审查记录 |
| internals/ | DSH 内部结构:基底、启动链路、运行时、服务地图、扩展缝、UI、官方插件解剖 |
| internals/generated/ | 机器生成:服务 / 事件 / slot / 包四张表(随 dsh 版本变化) |
安装
DSH 的文件系统技能提供方按 <root>/<name>/SKILL.md 一层深发现技能,用户级根目录是 $DSH_HOME/skills(默认 ~/.dsh/skills)。
git clone https://github.com/Thatgfsj/dsh-plugin-skills.git
cd dsh-plugin-skills
bash scripts/install.sh --dry-run # 看会装哪个版本、装什么
bash scripts/install.sh # 默认装与本机 `dsh --version` 同名的目录
bash scripts/install.sh --version 0.2.2-rc.1 # 显式指定版本
也可以把某个版本目录加进配置的 customSkillDirs(rank 300),或手工把该版本下的技能目录拷进 ~/.dsh/skills/。装完新开一个会话即可在技能目录里看到它们。
CI 策略
不在每次 PR / push 时构建和跑检查。 这个仓库交付的是数据(Markdown 技能),不是要编译的代码;评审时本地跑两条命令即可:
node scripts/validate-skills.mjs # 技能格式与相对链接
node scripts/dsh-map.mjs --check # 内部结构生成表是否过期
CI 只在发布时跑:打 v* tag、发布 release,或手动 workflow_dispatch。注意 drift 检查(dsh-map.mjs --check)需要本机安装 dsh,GitHub runner 上会被跳过,只跑技能格式与链接校验;发布前请在本地跑一遍。
校验
node scripts/validate-skills.mjs
零依赖。FAIL 集合只放 DSH 真会拒绝、导致技能被静默丢弃的问题:bundle 形态、kebab-case 名、name/description 必填、调用布尔值合法、旧的驼峰调用键(disableModelInvocation 等,DSH 会直接报错丢弃)、相对 Markdown 链接失效。
WARN 集合放本仓库的风格规则:description 超过 500 字符(DSH 是截断不是丢弃,模型只看得到前 500)、frontmatter name 与目录名不一致(DSH 允许,本仓库要求一致)。这两类问题在本地跑 validate-skills.mjs 就能发现;CI 只在发布时执行(见上文「CI 策略」)。
维护:版本与元信息
版本号只写在会跟代码一起走的地方,升级 dsh 时必须同一次改完;会漂的元信息不写数字。
| 位置 | 写什么 | 升级 dsh 时 |
|---|---|---|
| README 顶部「时效性」段 | 基线版本 | 手工改 |
README 徽章 DSH-<版本> |
当前验证版本 | 手工改 |
<版本>/dsh-plugin-construction/references/sources.md |
版本差异表、实测清单 | 手工改(只改该版本目录) |
<版本>/.../internals/README.md |
版本基线 | 手工改 |
<版本>/.../internals/generated/* |
由 dsh-map.mjs 从本机生成 |
不要手改,重跑生成器 |
README.md 的版本目录表 |
各目录的适配状态 | 手工改 |
| 仓库 About / description | 只说"做什么" | 不写版本号、不写文档体量 |
改完自检:
node scripts/validate-skills.mjs
node scripts/dsh-map.mjs --check
证据纪律
本仓库的写法是:每条硬结论都标注来源与核实方式,并明确列出没验证到的部分。
这些技能由独立子代理做过只读事实审查(对照本机安装产物源码逐条核验),并跟着 DSH 版本重验:累计修掉 4 条阻断级与 17 条应修正问题,记录见 sources.md。外部资料(官方文档、第三方技能、博客)一律按"本机代码/产物 > 官方仓库对应 tag 的文档 > 第三方文档"取舍,冲突处写明分歧。
几个被实测推翻或补充的常见说法:
engines.dsh一旦声明就单独决定兼容性,同一份清单里的peerDependencies会被忽略——实测:兼容的engines.dsh+ 不兼容的 peer 能装上,反过来的组合被拒。- 图形插件不声明
peerDependencies时,@deepseek-ai/*import 会ERR_MODULE_NOT_FOUND,插件行不加载且很可能没有任何报错。 - 有
exports却不导出./package.json/./locale/*.json,图标与标题会静默丢失。 ctx.get()不要求inject,但默认只返回已激活的实现;返回undefined不等于服务不存在。- UI 半边不能靠
--help冒烟验证——客户端组合其实会跑,但失败被降级成logger.warn,看不到输出。 - 第三方
dsh-plugin-guide里"导出./icon"一条在 0.2.0-rc.2 上不成立、到 0.2.1-rc.2 又成立——这类"今天对的明天错"正是本仓库坚持标版本号的原因。
License
MIT
No comments yet. Be the first to write one.