dsh-plugin-development

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

一个与 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 步标准流程执行：

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

插件契约速览（详见 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 表格仅作方向性参考

Dsh Plugin Development

At a glance

README