@local/dsh-plugin-authoring

Readme

# dsh-plugin-authoring

一个**纯技能插件**：给 agent 装上「怎么写 DSH 插件、怎么推上 GitHub、怎么被 dsh 插件市场收录」这套知识。

它**不注册任何工具**，只通过 `ctx.skills.registerProvider` 提供两个技能。零依赖，没有构建步骤。

## 为什么是独立插件

DSH 自带一份权威的插件开发文档，在 asar 内：

```
dsh/node_modules/@deepseek-ai/dsh-agent-preset/skills/cordis-plugin-development/
```

它是随包发行的，**会被 DSH 升级覆盖**，而且只有 Host 自己的文件读取能打开
（shell / glob / grep / node 都读不到）。

本插件把官方契约 + 实测踩到的坑 + 市场投稿的全套流程沉淀成一份**可随自己升级、也可被 agent 直接读**的技能。
两者不冲突：官方那份讲设计原则，这份讲「在这台机器上真能跑起来」的操作细节。

## 提供的两个技能

### `dsh-plugin-authoring` —— 写插件

| 主题 | 要点 |
|---|---|
| 决策 | 这个需求到底该写插件，还是丢个 `SKILL.md` 到磁盘就够 |
| 最小可用插件 | 5 个文件的全文：`package.json` / `cordis.patch.yml` / `index.js` / 一个工具 / 一个技能 |
| 三条铁律 | 不手写 profile 的 `package.json`；patch 行的 `name` 必须等于真实包名；**`link:` 装载的插件不能 import 任何 `@deepseek-ai/*`** |
| 注册工具 | `ctx.tools.register(defineTool({...}))`、参数 DSL、返回值与 `render`、策略链、审批三级 |
| 注册技能 | `ctx.skills.registerProvider()` 的 provider 契约、frontmatter、catalog 截断行为 |
| 安装与验证 | `install_bundle` → 必须看到 `application: "applied"`；`list_plugins` 看 `fiberPhase`；`set_plugin` 关再开修 `ambiguous-install` |
| 热重载 | 什么改动能免重启、什么必须重启 |

参考文件：`references/{manifest,tools,skills,pitfalls}.md`

其中 `pitfalls.md` 是**本机实测**的坑，不是文档转述 —— 每一条都附了症状原文和定位过程。

### `dsh-plugin-publish` —— 发出去

| 路线 | 说明 |
|---|---|
| 推 GitHub | 本机认证现状、取 token 的正确姿势、建仓库、topics、`.gitattributes` 防 CRLF 假 diff |
| 市场收录 | 条目文件形态、字段、分类、一个 PR 最多 3 条、提 PR |
| CI 与排错 | 两道 check 各查什么、年龄门槛为什么红灯、**为什么不能重提/push/close-reopen**、本地预检 |
| 打包 | 本机没有 npm/npx；node 与 pnpm 的绝对路径 |

参考文件：`references/{github-upload,market-listing,market-ci,entry-template.yml}`

## 安装

把插件目录加到 profile：

```
plugin_manager({ action: 'install_bundle',
                 target: 'C:\\Users\\lishuo\\Documents\\deepseek-harness\\default-workspace\\dsh-plugin-authoring' })
```

它会自动往 profile 的 `dependencies` 写 `link:` 记录、往 `dsh.profile.bundles` 追加包名。
返回里 **`application: "applied"` 才算生效**；若是 `failed`，先修源码再用
`set_plugin` 关一次再开一次（`install_bundle` 第二次调用不会重试导入）。

确认：

```
plugin_manager({ action: 'list_plugins', target: 'authoring' })   # fiberPhase 应为 active
```

## 自检

```sh
& "C:\Users\lishuo\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe" \
  "C:\Users\lishuo\Documents\deepseek-harness\default-workspace\dsh-plugin-authoring\_selftest.mjs"
```

四组用例：语法检查、**无宿主依赖**（递归扫 `.js`/`.mjs` 的裸 import 说明符，必须全部以 `.` 或
`node:` 开头）、技能发现（2 个 SKILL.md 被解析、`complete === true`、块标量描述可用、
`control.signal` 取消生效）、技能正文（frontmatter 已剥离、含关键小节、references 文件都在）。

> ⚠️ **必须用绝对路径调用**。`workdir` 通常不是插件目录，相对路径会 `MODULE_NOT_FOUND`。

## 目录结构

```
dsh-plugin-authoring/
├── package.json                 # 插件 manifest（dsh.bundle.patch 指向下面这个文件）
├── cordis.patch.yml             # 一行 insert：id + name
├── index.js                     # apply()：注册技能 provider
├── lib/
│   ├── skills.js                # 递归找 skills/**/SKILL.md 并解析 frontmatter
│   ├── frontmatter.js           # 最小 YAML frontmatter 解析（支持 | 和 > 块标量）
│   └── define-tool.js           # defineTool 的零依赖等价实现（随包分发，供使用者拷走）
├── skills/
│   ├── dsh-plugin-authoring/SKILL.md + references/{manifest,tools,skills,pitfalls}.md
│   └── dsh-plugin-publish/SKILL.md + references/{github-upload,market-listing,market-ci,entry-template.yml}
└── _selftest.mjs
```

## 设计说明

### 为什么自带 `lib/define-tool.js`

本插件目前以 `link:` 方式装载。`cordis-plugin-loader` 对**裸说明符**走 Node 原生
`import(name)`，而 Node 按**插件真实路径**向上找 `node_modules` —— 宿主包
（`@deepseek-ai/dsh-tools` 等）只存在于 `app.asar` 内部，磁盘上根本没有，于是报：

```
Cannot find package '@deepseek-ai/dsh-tools' imported from ...\lib\tools.js
| ERR_MODULE_NOT_FOUND
```

本插件本身**不注册工具**，用不到 `defineTool`；它把这份零依赖实现随包带上，是为了让读者
（和 agent）有一个能直接抄走、在 `link:` 场景下真能跑的最小实现。

### 为什么 `rank: 600`

文件系统技能 provider 占 rank 100–500。随包发行的技能用 `BUNDLED_SKILL_RANK = 600`，
排在用户自己的技能后面 —— 同名时用户的可覆盖它。

## 参考实现来源

- 官方契约：`dsh-agent-preset/skills/cordis-plugin-development/`（随 DSH 发行，asar 内）
  本机可读副本：`_dsh-asar-probe/DSH-PLUGIN-AUTHORING.md`
- 技能 provider 最小范例：`@deepseek-ai/dsh-skill-badge/lib/index.js`（53 行）
- 工具注册范例：`dsh-meme`
- 市场规则：`awesome-dsh-plugin/awesome-dsh-plugin` 的 `contributing.md` 与
  `scripts/lib/entries.mjs`、`scripts/check-submission.mjs`
  本机副本：`_dsh-market-contributing.md`、`_dsh-market-entries.mjs`、`_dsh-market-check-submission.mjs`
- 同类实测插件：`dsh-enet-review`（工具 + 技能同插件、自带 `define-tool.js`）