# dsh-plugin-dev-02

**Repository Path**: my_friends/dsh-plugin-dev-02

## Basic Information

- **Project Name**: dsh-plugin-dev-02
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-29
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

<p align="center">
  <img src="assets/logo.png" alt="dsh-plugin-dev logo" width="110" style="vertical-align: middle;">
  <img src="assets/banner.png" alt="dsh-plugin-dev banner" width="720" style="vertical-align: middle;">
</p>

> 一个给 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 以目录包形式存放，最终结构应为 `<skills目录>/dsh-plugin-dev/SKILL.md`。

### 方式一：手动安装

**Windows（PowerShell）：**

```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：**

```bash
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 目录、复制并验证（你只需要最后新开一个会话）：

````text
请帮我安装这个 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 目录
   （最终结构应为 <skill目录>/dsh-plugin-dev/SKILL.md）；
4. 验证安装：
   - <skill目录>/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](https://github.com/deepseek-ai/deepseek-harness) — 官方仓库
- [dsh-plugin topic](https://github.com/topics/dsh-plugin) — DSH 插件生态列表页
- [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) — DSH 插件精选列表

## License

MIT