# dsh-plugin-development

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

[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6-blue)]()
[![skill](https://img.shields.io/badge/skill-AGENTS.md-orange)](SKILL.md)
[![中文](https://img.shields.io/badge/readme-中文-red)](README.md)
[![English](https://img.shields.io/badge/readme-English-blue)](README.en.md)

一个**与 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](https://github.com/RayYeung1989/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 <插件路径或 github spec>`
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](https://github.com/deepseek-ai/deepseek-harness) — DeepSeek Harness 本体
- [RayYeung1989/claude-parchment-theme](https://github.com/RayYeung1989/claude-parchment-theme) — 已上线的 dsh 主题插件（本 Skill 客户端模板的母版）

## 许可证

[MIT](LICENSE) © RayYeung1989