abab996/dsh-plugin-dev

dsh-plugin-dev — DSH 插件开发规范 Skill（防崩溃指南）

一个给 AI 看的 Skill：教模型安全、规范地开发 DeepSeek Harness（DSH）插件，把「操作失误 → 整个 DSH 崩溃」的常见陷阱固化成注意事项。这不是一个 npm 插件包，而是一份会随会话自动加载进模型上下文的开发规范。

痛点：为什么需要这个 Skill

在 DSH 中开发插件时，模型常常因为操作失误，把整个 DSH 搞崩溃：

- 直接改 node_modules 里的 DSH 核心包：为了给新 settings namespace 加白名单，手改 dsh-host-apiproxy 的源码，升级即失效，改错即崩；
- client 插件打成裸 ESM：浏览器端插件必须打成 window.__ModuleLoader__.load(...) 手接格式，直接用 tsdown 默认产物会让 web 端直接崩溃；
- cordis.patch.yml 格式写错：新增插件行必须用 - insert: 嵌套格式，写成裸的顶层 - id: 行会解析失败；
- dsh.client.inject 漏列服务：apply 里用了 settings / UI 原语却没把提供包写进 inject，加载顺序错、服务未就绪即崩；
- 手搓 div/input：WebUI 必须用 DSH 的 UI 原语（Menu / Button / Input / DisclosureRow / Pill…），否则与主题割裂、行为不一致；
- 类型当值导入：import type 与 import 混用导致构建 MISSING_EXPORT 失败；
- 重复注册：settings namespace / systemPrompt section / command name 重复注册直接抛错；
- 安装方式错误：改了插件代码还反复 uninstall / reinstall，而不是用本地 file: junction 软链部署。

这些错误往往不会只报一个温和的错误——轻则插件加载失败，重则整个 DSH 崩溃、当前会话中断、配置损坏，开发体验被彻底打断。

本 Skill 解决的就是这个问题：把「防崩溃注意事项 + 正确开发流程」固化为模型必读的规范，让模型在动手写代码之前就被告知这些陷阱，按规范开发、按流程验证，而不是靠试错把 DSH 搞崩。

它是什么

- 一个 Agent Skill（目录包：SKILL.md + references/ + scripts/），DSH 会在会话中自动发现并加载；
- 加载后，模型会自动遵循其中的规范：三大核心事实（Cordis 插件契约 / host 与 agent 双平面 / agent preset 机制）、8 条崩溃陷阱、7 步开发流程；
- 内置两份可直接复用的脚本：scripts/build-client.mjs（client 手接打包）与 scripts/deploy.ps1（构建 + 装包 + patch + 白名单 + preset 一键部署）。

安装

安装 = 把 dsh-plugin-dev 文件夹放进 DSH 的 skill 扫描目录。DSH 会扫描以下位置（按优先级）：

| 作用域 | 路径 |
|---|---|
| 用户级（推荐） | ~/.agents/skills/（Windows：%USERPROFILE%\.agents\skills\） |
| 用户级（DSH 专用） | ~/.dsh/skills/ |
| 项目级 | /.dsh/skills/ 或 /.agents/skills/ |

提示：~/.agents/skills 目录可用环境变量 DSH_AGENTS_HOME 覆盖；skill 以目录包形式存放，最终结构应为 /dsh-plugin-dev/SKILL.md。

方式一：手动安装

Windows（PowerShell）：

1. 克隆仓库
git clone https://github.com/abab996/dsh-plugin-dev.git
2. 复制到用户级 skill 目录（推荐）
Copy-Item -Recurse .\dsh-plugin-dev $HOME\.agents\skills\
（可选）DSH 专用目录：Copy-Item -Recurse .\dsh-plugin-dev $HOME\.dsh\skills\
3. 验证
Test-Path $HOME\.agents\skills\dsh-plugin-dev\SKILL.md

macOS / Linux：

git clone https://github.com/abab996/dsh-plugin-dev.git
cp -r dsh-plugin-dev ~/.agents/skills/
验证
ls ~/.agents/skills/dsh-plugin-dev/SKILL.md

验证安装：新开一个 DSH 会话（skill 在会话启动时发现），让模型加载它，例如直接说：

加载 dsh-plugin-dev skill，并简述开发 DSH 插件时的核心陷阱。

模型应能列出 client 打包格式、settings 白名单、patch insert 格式等关键规范。

方式二：让 AI 自动安装（推荐）

不想敲命令？在 DSH 中新开一个会话，把下面这段提示词整段复制发给 AI 即可。AI 会自己完成克隆、定位 skill 目录、复制并验证（你只需要最后新开一个会话）：

请帮我安装这个 Agent Skill 仓库：https://github.com/abab996/dsh-plugin-dev

这是一个给 AI 使用的「DSH 插件开发规范」skill（目录包格式：SKILL.md + references/ + scripts/）。
请按以下步骤操作，每完成一步简要汇报一次：

1. 把仓库克隆到一个临时目录（例如工作区下的 dsh-plugin-dev-tmp）；
2. 确定目标 skill 目录（按优先级）：
- 用户级：$HOME/.agents/skills（Windows 为 %USERPROFILE%\.agents\skills）
若环境变量 DSH_AGENTS_HOME 已设置，则为 $DSH_AGENTS_HOME/skills；
- 或 DSH 专用目录：~/.dsh/skills；
- 如果都没有，就创建 ~/.agents/skills；
3. 把克隆下来的 dsh-plugin-dev 文件夹完整复制到目标 skill 目录
（最终结构应为 /dsh-plugin-dev/SKILL.md）；
4. 验证安装：
- /dsh-plugin-dev/SKILL.md 存在；
- SKILL.md 开头有合法的 YAML frontmatter（name: dsh-plugin-dev、description: ...）；
- references/ 与 scripts/ 子目录完整复制；
5. 若目标位置已存在同名 dsh-plugin-dev 文件夹，先询问我是否覆盖，不要擅自删除；
6. 除复制该 skill 外，不要改动其他任何文件；
7. 汇报结果，并提醒我：需要新开一个 DSH 会话（skill 在会话启动时发现），
之后说「加载 dsh-plugin-dev skill」即可使用。

使用

- 开发新插件：在新会话里直接说「帮我开发一个 DSH 插件 / agent preset」，模型会自动加载本 skill 并遵循规范开发；
- 排查崩溃：把崩溃报错或日志贴给模型，让它按 skill 的「崩溃陷阱」清单逐条排查（client 打包格式、白名单、patch 格式、inject、重复注册…）；
- 关键流程：镜像现有插件 → 写代码 → tsc 类型检查 → tsdown / build → mock 冒烟测试 → deploy.ps1 部署 → 重启 host 端到端验证。

仓库结构

dsh-plugin-dev/
├── SKILL.md                    # skill 主文件（frontmatter + 规范正文）
├── README.md                   # 本文件（安装与使用说明）
├── LICENSE
├── social-preview.png          # GitHub 社交分享封面（1280×640，自动用作 og:image）
├── assets/
│   ├── banner.png              # README 横幅（1280×400）
│   └── logo.png                # 仓库头像/图标（512×512）
├── references/
│   ├── DSH插件开发规范.md        # 完整规范（极致详细版，含 omd/vision-read 逐文件解读）
│   ├── architecture.md         # 架构、服务 API、preset 格式、slot 名
│   ├── deployment.md           # 部署步骤、patch / 白名单 / junction 细节
│   ├── gotchas.md              # 高级注意事项（子代理、isolate、session projection…）
│   └── spec-supplement.md      # 对照源码的事实纠偏与增量（必读）
└── scripts/
├── build-client.mjs        # client 手接打包（window.__ModuleLoader__）
└── deploy.ps1              # 构建 + 装包 + patch + 白名单 + preset 一键部署

相关链接

- DeepSeek Harness — 官方仓库
- dsh-plugin topic — DSH 插件生态列表页
- awesome-dsh-plugin — DSH 插件精选列表

License

MIT