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

自检

& "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）