插件开发技能 RayYeung1989/dsh-plugin-development

dsh-plugin-development

通用 dsh 插件开发 Skill —— 任何 agent 工具加载即会开发符合 DeepSeek Harness 的 dsh 插件

license
[dsh]()
skill
!

一个与 agent 工具无关的 Skill（SKILL.md）：Claude Code、Codex、Hermes、OpenClaw、DeepSeek Harness 内置 agent……任何 agent 只要加载本 Skill，就能按照 DeepSeek Harness（DSH）的真实插件契约开发、注册、安装、调试 dsh 插件（dsh插件）。

所有契约内容均基于 dsh 0.1.0-rc.6 安装的实测：@deepseek-ai/ 包内的 .d.ts、dsh web --dump-config 组合树、dsh CLI 源码，并参考了已验证的 claude-parchment-theme 插件（本仓库客户端模板的母版）。

特性

- ✅ 与 agent 工具无关：不依赖任何 DSH 内部工具，任何 agent 用文件 + shell 工具即可照做
- ✅ Ground truth 优先：Skill 明确要求 agent 读取本机已安装版本的 .d.ts 与组合树，杜绝臆造 API，天然抗版本漂移
- ✅ 三种插件形态全覆盖：宿主侧（服务端）/ 浏览器侧（客户端主题、UI）/ 双面插件
- ✅ 可直接运行的模板：templates/ 下三个脚手架，node --check 全部通过
- ✅ 已实测验证：新鲜子代理加载本 Skill 后正确产出双面插件，并据此修复了 Skill 初稿的契约错误

目录结构

dsh-plugin-development/
SKILL.md # 主 Skill（agent 加载入口，含标准工作流/决策表/排查表） README.md # 本说明（中文） README.en.md # English readme LICENSE # MIT references/ plugin-package.md # 完整契约：包结构/入口/manifest/patch/CLI/模块解析 services-events.md # 服务与事件面 + 如何运行时枚举 templates/ server-plugin/ # 仅宿主（服务端）插件模板（Config + 事件 + timer） client-plugin/ # 仅浏览器（客户端）插件模板（主题 token + CSS，已验证模式） dual-half-plugin/ # 双面插件模板（宿主 Service 类 + 浏览器 remote.$on）

安装到各 agent 运行时

把整个目录复制到目标运行时的 skill 目录，或在 ~/.agents/skills/（跨运行时中央仓库，DSH 默认直读）放一份，再用 skill 分发工具软链到各 agent 工具目录：

| 运行时 | 目录 |
| Codex / Copilot CLI / Gemini CLI / DSH 自身 | ~/.agents/skills/dsh-plugin-development/ |
| Claude Code | ~/.claude/skills/dsh-plugin-development/ |
| DeepSeek Harness（home 级） | $DSH_HOME/skills/dsh-plugin-development/ |
| Hermes / OpenClaw / 其它 | 放到该工具扫描 SKILL.md 的任意 skill 目录 |

DSH 的 skill 根优先级（数字越小越优先）：项目 .dsh/skills(100) → 项目 .agents/skills(200) → customSkillDirs(300) → ~/.dsh/skills(400) → ~/.agents/skills(500) → 内置 bundled。同名 Skill 放高优先级根即可覆盖。

快速上手

加载 Skill 后，agent 会按 8 步标准流程执行：

1. 定位本机 dsh 安装与目标 profile（echo $DSH_HOME、dsh --version）
2. 读组合树 dsh web --dump-config，找到要新增/覆盖的 row id
3. 用决策表判断宿主侧还是浏览器侧
4. 从 templates/ 复制脚手架，按真实 .d.ts 写代码
5. 在 cordis.patch.yml 注册：- insert: - id: xxx name: '@dsh-local/xxx'
6. 安装：dsh plugin --profile web add
7. 验证：dsh web --dump-config 出现新行 → 重启 dsh web → 客户端插件在 设置 → 插件管理 可见
8. 按排查表调试

插件契约速览（详见 references/）

| 面 | 契约 |
| 宿主入口 | ESM；export { name, inject, Config, apply } / 默认导出函数 / 默认导出 Service 子类（static Config，schemastery z.object） |
| 浏览器半身 | package.json 声明 dsh.client = { platform, inject, immediately } + 导出 ./client；lib/client.js 用 window.__ModuleLoader__.load({ id, factory }) 注册，纯 JS 无 import/JSX |
| 事件面 | turn/start\|end（{turn, reason}）、step/start\|end、user/message、assistant/message（content 为 blocks 数组）、tool/call\|result、assistant/chunk |
| 服务面 | 宿主：sessions、llm、agents、skills、settings、subagents、goals、timer；浏览器：theme、slots、modules、remote |
| 注册 | patch 行按 id 寻址，后写胜出，config 整体替换不合并；!!js 表达式可取 env/ctx 值 |

版本基线

- dsh / @deepseek-ai/：0.1.0-rc.6
- DSH 是 0.1.0-rc.*，接口会变；Skill 明确要求 agent 以已安装版本的 .d.ts 为准，本 README 表格仅作方向性参考

相关项目

- deepseek-ai/deepseek-harness — DeepSeek Harness 本体
- RayYeung1989/claude-parchment-theme — 已上线的 dsh 主题插件（本 Skill 客户端模板的母版）

许可证

MIT © RayYeung1989