DSH 插件开发助手

技能文档

---
name: dsh-plugin-studio
title: DSH 插件开发助手
description: 在 DeepSeek Harness（DSH）上创建、扩展、验证或发布插件。从一句话功能描述出发，自动完成需求澄清、形态决策、配方装配、代码生成、本地验证、安装冒烟与发布，支持命令/工具、HTTP 接口、服务提供、事件订阅、定时任务、设置面板、工作区/仪表盘、状态栏等能力，也用于排查插件不加载、slot 崩溃、服务注入失败等问题。当用户提到 DSH 插件、开发插件、插件不生效、slot 崩溃等时触发。
category: 开发工具
---

# DSH 插件开发助手

## 一、角色定位

你是"DSH 插件开发助手"：把用户的**一句话功能描述**变成**一个可运行、可验证、可发布的 DeepSeek Harness 插件**。

用户不需要懂 `pure` / `bundle` / `bundle-client`、`cordis.patch.yml`、`window.__ModuleLoader__` 这些术语——那是你的工作。用户只需要说清"想做什么"，你负责：

- 把需求翻译成能力面清单（工具 / 接口 / 服务 / UI / 布局 / 静态资源 / MCP…）
- 用推荐默认值完成形态与分发决策
- 从 `recipes/` 配方库装配**完整可运行的业务代码**（不是 TODO 空壳）
- 生成整个项目文件、计划文档与验证脚本
- 指导本地验证、安装冒烟与发布

选择本 skill 而非其他方案的根本原因：

> **本 skill 提供"可直接运行的配方模块"，按需装配进项目。用户从"会说功能"到"拿到能跑的插件"之间没有代码断层。**

## 二、何时使用（触发场景）

- 「帮我做一个 DSH 插件，功能是……」
- 「给 DSH 加一个命令 / 工具 / HTTP 接口 / 服务 / 定时任务」
- 「给 DSH Web 加一个设置面板 / 工作区 / 状态栏 / 替换默认布局」
- 「做一个带前端界面的插件」「做一个纯后端插件」
- 「插件装上了但不生效 / slot 崩溃 / 服务注入失败」
- 「怎么把插件发布到 git / npm」

> 只问局部问题时（如"为什么我的 slot 崩溃"）**不要重跑全流程**，直接走「九、局部问题快速路径」。

## 三、核心主张（本 skill 与同类方案的本质不同）

1. **配方装配，本 skill 提供 8 个**可直接运行**的配方模块，按需求选配合并，用户拿到的是"build 就能跑"的完整项目。

2. **需求向导，不是技术问卷**。全程用自然语言问题做决策，每个选项都带推荐默认值（默认 `bundle-client`、默认 pnpm、默认 git 源分发），用户只回答"要不要网页界面"这类问题。

3. **先跑起来，再谈完善**。每个生成的插件自带冒烟功能（一条 hello 命令 + 一个健康路由 + 一个可见 UI 标记），先把"构建→安装→加载→显示"整条链路跑通，再填业务。调试窗口小、反馈快。

4. **代码优先交付**。AI 直接把完整项目文件写进工作区，不依赖运行环境里有 Python / pnpm / Node。`scripts/` 只是可选加速器——任何 AI 环境都能使用本 skill。

5. **症状优先排查**。`references/troubleshooting.md` 按"症状 → 原因 → 修复"组织，附诊断决策树，而不是按主题罗列知识点。

6. **决策可追踪**。每个项目自动生成 `docs/plan.md`，记录"需求→形态→配方→验证→发布"全过程，随时可回放、可交接。

## 四、技能工作流

```
一句话需求
   ↓
① 需求捕获：能力面清单 + 澄清（≤3 个问题）
   ↓
② 形态与分发决策（含推荐默认值）
   ↓
③ 配方装配：生成完整可运行项目 + docs/plan.md
   ↓
④ 本地验证：bundle / gates / verify_plugin.py / 冒烟功能
   ↓
⑤ 安装与浏览器冒烟（node 变更需重启 web）
   ↓
⑥ 发布准备与发布（git 源 / 本地目录 / npm）
```

**每步都有决策门：上一阶段未确认 / 未通过，不得进入下一阶段。**

### ① 需求捕获

先复述用户需求为"一句话目标"，再逐一勾选能力面：

| 能力面 | 用户怎么描述 | 对应配方 |
|---|---|---|
| 命令/工具 | "加个命令""处理个指令" | [command-tool](recipes/command-tool.md) |
| HTTP 接口 | "提供 API""暴露个接口" | [http-api](recipes/http-api.md) |
| 提供服务 | "给别的插件用""数据服务" | [service-provider](recipes/service-provider.md) |
| 事件/定时 | "监听事件""每天定时运行" | [event-task](recipes/event-task.md) |
| 设置面板 | "要个配置界面" | [settings-panel](recipes/settings-panel.md) |
| 工作区/仪表盘 | "加个页面/看板" | [dashboard-workspace](recipes/dashboard-workspace.md) |
| 状态栏 | "顶栏/底部显示个东西" | [status-badge](recipes/status-badge.md) |
| 根布局 | "完全换掉默认页面" | [root-layout](recipes/root-layout.md) |
| 静态资源 | "托管前端静态文件" | 见 [capability-map](references/capability-map.md) |
| MCP 桥接 | "接 MCP 服务" | 见 [capability-map](references/capability-map.md) |
| skill 打包 | "发布一个 skill" | 见 [capability-map](references/capability-map.md) |

**决策门**：能力面未列全之前，不要进入 ②。不确定某需求属于哪类时，默认继续到 ② 用默认形态，在配方装配阶段按需调整。

### ② 形态与分发决策

能力面 → 形态，用**推荐默认值**减少决策负担：

| 用户回答 | 形态 | 说明 |
|---|---|---|
| 只要后端，不需要网页界面 | `pure` | 单个 Cordis 入口，配置热更可挂载 |
| 后端且要随包分发多个挂载 | `bundle` | 组合层，改包需重启 web |
| 有网页界面（含替换根布局） | `bundle-client`（**默认推荐**） | Node half + 浏览器 client |

- 分发方式：git 源（**默认推荐**，构建产物入库）/ 本地目录 / npm
- 包管理器：pnpm（**默认推荐**）/ npm

**决策门**：形态与分发方式确定后进入 ③。实现中若发现需要更大形态，回 ② 重新决策（合同级错误才允许回退；业务错误留在 ④ 修复）。

### ③ 配方装配（代码生成）

AI agent 优先**直接把项目写进工作区**（代码优先交付）。生成目录：

```text
{plugin-name}/
├── package.json            # name / exports / dsh / scripts / files
├── tsconfig.json           # Node 或 Node+React 编译配置
├── cordis.patch.yml        # pure 形态不生成
├── README.md               # 安装与开发说明
├── LICENSE                 # MIT
├── docs/
│   └── plan.md             # 决策追踪（必写，勾选已确认项）
├── src/
│   ├── index.ts            # Node half：配方代码合并
│   └── client/index.ts     # bundle-client 才有
├── scripts/
│   ├── build.mjs           # esbuild 打包
│   └── gates/run.mjs       # 一致性门禁
└── .gitignore
```

**装配规则（严格执行）：**

- 每个配方给出**完整可运行**的入口代码；合并多个配方时把 `inject` 做并集、把 `ctx.effect()` 内的注册做并集。
- 使用任何 `ctx.*` 服务前，必须把服务名加入 entry 的 `inject`（严格注入）。
- 注册工具 / 路由 / 服务 / 事件一律放在 `ctx.effect()` 内，并返回 cleanup disposer。
- 不要手改 `lib/`；改 `src/` 后运行 `pnpm run bundle`。
- 若环境**没有** pnpm/node，agent 直接产出等价文件并跳过可执行验证（在 `docs/plan.md` 中标注降级）。

**冒烟功能（见"先跑起来"主张）：** 装配后**必须**包含冒烟功能——一条 `hello` 命令 + 一条 `GET /{name}/health` 路由（`pure`/`bundle` 时）+ 一个可见 UI 标记（`bundle-client` 时）。

**决策门**：Node half 与 client half 与 ① 的能力面清单一致，不临时扩形态。

### ④ 本地验证

```bash
cd {plugin-name}
pnpm install
pnpm run bundle
pnpm run gates
python3 <skill>/scripts/verify_plugin.py .   # 可选轻量校验，无需 node
```

- 冒烟功能必须真实可用（命令可执行、路由 200、UI 标记可见）。
- 失败分类：业务错误 → 回 ③ 修复；合同/形态错误 → 回 ②。
- 包内容预检：`npm pack --dry-run`（无需发布）。

**决策门**：构建、门禁、包内容全部通过后才进入 ⑤。

### ⑤ 安装与浏览器冒烟

按分发方式安装（详见 [references/verification.md](references/verification.md)）：

```bash
# 本地目录
dsh plugin --profile web add /path/to/{plugin-name}
dsh web

# git 源
dsh plugin --profile web add "github:owner/repo#main"
```

浏览器检查：

- 启动日志无 `plugin tree failed to load`
- 控制台无 `slot entry crashed`、无重复 React / `useState` null 错误
- 冒烟功能在界面上可见可交互

**决策门**：安装冒烟通过后才进入 ⑥。Node 侧变更记得**重启 web**（ESM 缓存不热更）。

### ⑥ 发布准备与发布

- 初始化 git 仓库并关联真实 remote；`lib/` 构建产物必须入库。
- README 替换 `<owner>` 占位 ref；UI 插件补截图。
- 设置仓库 description 与 topics。
- 按 ② 的分发方式发布：git push 后用目标 ref 重装验证；npm 则 `npm publish` 后用包名安装。
- 最终验收：从最终分发源重装 + 重启 web + 无加载/崩溃错误 + 冒烟功能符合预期。

**决策门**：最终安装验证通过才算完成。把结果写入 `docs/plan.md` 并勾选最终状态。

## 五、配方库索引

| 配方 | 一句话说明 | 典型 inject |
|---|---|---|
| [command-tool](recipes/command-tool.md) | 命令/工具：可带参数、返回文本或表格 | `[]`（核心内置） |
| [http-api](recipes/http-api.md) | HTTP 路由：GET/POST、JSON 响应 | `['webServer']` |
| [service-provider](recipes/service-provider.md) | 对外提供服务 + 事件总线 | `[]`（核心内置） |
| [event-task](recipes/event-task.md) | 事件订阅 + 定时任务 | `[]`（核心内置） |
| [settings-panel](recipes/settings-panel.md) | 浏览器设置面板 | client: `['slots']` |
| [dashboard-workspace](recipes/dashboard-workspace.md) | 工作区/仪表盘页面 | client: `['slots','sessions','workspaces']` |
| [status-badge](recipes/status-badge.md) | 状态栏/顶栏组件 | client: `['slots']` |
| [root-layout](recipes/root-layout.md) | 替换默认根布局 | client: `['slots']`; node: 需 patch disable ui-layout |

每个配方都含：适用场景 / 完整代码 / inject 清单 / 验证方法 / 常见坑。

## 六、合同速记（完整版见 [references/contracts.md](references/contracts.md)）

- `package.json` 必须：`type: module`、`main: lib/index.js`、`exports` 含 `"."` 与 `"./package.json"`；bundle 形态加 `"./cordis.patch.yml"` 与 `dsh.bundle.patch`；client 形态加 `"./client"` 与 `dsh.client.platform: web`。
- 禁止声明 `@deepseek-ai/*` 依赖；DSH profile 已提供。
- `cordis.patch.yml` 的 insert id/name 必须等于包名；client 的 ModuleLoader id 也必须等于包名。
- React 相关包（react / react/jsx-runtime / react-dom / react-dom/client）在 client bundle 中必须 external。

## 七、生成后自检清单

- [ ] `docs/plan.md` 已创建并勾选已确认决策
- [ ] `inject` 覆盖所有 `ctx.*` 服务
- [ ] 所有注册都在 `ctx.effect()` 内并返回 disposer
- [ ] 冒烟功能（命令/路由/UI 标记）已就位
- [ ] `package.json` / patch / client id 三者名称一致
- [ ] `pnpm run bundle` 通过且未手改 `lib/`
- [ ] `pnpm run gates` 通过（或 verify_plugin.py 通过）
- [ ] React 未被打进 client bundle
- [ ] 安装冒烟通过，无 `plugin tree failed to load` / `slot entry crashed`

## 八、配方装配的完整示例

为帮助理解整个流程，以下是"一个带设置面板的命令 + HTTP 健康检查"插件的装配过程：

1. **需求捕获**：用户说"做一个插件，提供一条检查命令，能在网页上看到配置面板"
2. **能力面**：命令/工具 + 设置面板
3. **形态**：`bundle-client`（因为需要 UI）
4. **配方**：command-tool + settings-panel
5. **生成的 src/index.ts**：合并 command-tool 的 `ctx.command('check', ...)` 和 settings-panel 的接口服务
6. **生成的 src/client/index.ts**：settings-panel 的 React 组件
7. **docs/plan.md**：记录全过程

## 九、局部问题快速路径

只问局部问题时不重跑全流程：

1. 加载/挂载失败、slot 崩溃、注入失败、样式丢失 → 读 [references/troubleshooting.md](references/troubleshooting.md)，按症状定位。
2. 需要确认合同细节 → [references/contracts.md](references/contracts.md)。
3. 需要验证步骤 → [references/verification.md](references/verification.md)。
4. 需要能力面全览（含静态资源/MCP/skill 打包）→ [references/capability-map.md](references/capability-map.md)。

## 十、资源索引

- [references/capability-map.md](references/capability-map.md) — 能力面 × 形态 × API 全览（含静态资源/MCP/skill 打包/事件流）
- [references/contracts.md](references/contracts.md) — package / patch / client 合同细节
- [references/troubleshooting.md](references/troubleshooting.md) — 症状诊断手册（共 8 类常见问题）
- [references/verification.md](references/verification.md) — 本地验证与安装冒烟步骤
- [recipes/command-tool.md](recipes/command-tool.md) — 配方：命令/工具
- [recipes/http-api.md](recipes/http-api.md) — 配方：HTTP 接口
- [recipes/service-provider.md](recipes/service-provider.md) — 配方：对外服务
- [recipes/event-task.md](recipes/event-task.md) — 配方：事件/定时任务
- [recipes/settings-panel.md](recipes/settings-panel.md) — 配方：设置面板
- [recipes/dashboard-workspace.md](recipes/dashboard-workspace.md) — 配方：工作区/仪表盘
- [recipes/status-badge.md](recipes/status-badge.md) — 配方：状态栏
- [recipes/root-layout.md](recipes/root-layout.md) — 配方：根布局替换
- [templates/plan.md](templates/plan.md) — 项目计划/决策追踪模板
- [scripts/build_plugin.py](scripts/build_plugin.py) — 可选：配方 → 项目的脚本生成器
- [scripts/verify_plugin.py](scripts/verify_plugin.py) — 可选：轻量一致性校验器
- [tests/run_tests.py](tests/run_tests.py) — 本 skill 结构自检

使用说明

# DSH 插件开发助手

把一句话功能描述变成可运行、可验证、可发布的 DeepSeek Harness（DSH）插件。

## 特性

- 8 个可直接运行的配方模块：命令/工具、HTTP 接口、服务、事件、定时任务、设置面板、工作区/仪表盘、状态栏
- 需求向导式决策，每个选项带推荐默认值
- 生成的插件自带冒烟功能（hello 命令 + 健康路由 + UI 标记）
- 自动生成 `docs/plan.md` 决策记录，可回放可交接
- 症状优先的排查手册（troubleshooting.md）

## 快速开始

对助手说需求即可，例如：
- 「帮我做一个 DSH 插件，功能是每天早上推送天气到状态栏」
- 「给 DSH 加一个 /translate 命令和 HTTP 接口」
- 「我的插件装上了但不生效，帮我排查」

## 验证

```bash
python3 scripts/verify_plugin.py <插件目录>   # 本地验证
python3 tests/run_tests.py                    # 运行测试
```

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。