插件发布助手 Gty2408/dsh-plugin-publish

dsh-plugin-publish

一条命令把 DSH 插件发布到 GitHub——创建仓库、上传目录树、设置必需的 topic，并写好 awesome-dsh-plugin 目录条目，供你提交 PR。

npx dsh-plugin-publish # publish the plugin in the current directory

为什么需要它

发布 DSH 插件要把四件事做对，而 harness 一件都不帮你做：

1. 清单结构。 awesome-list 的 CI 会拒绝任何 package.json 只声明 dsh.client 的仓库——它要求有 dsh.bundle，旁边还得有 cordis.patch.yml。这是最常见的拒绝原因。
2. 三个必须一致的标识符。 package.json 的 name、cordis.patch.yml 里那一行的 name，以及浏览器 bundle 里的 __ModuleLoader__.load({ id })。三者不一致，浏览器那一半就会静默地永不加载。
3. dsh-plugin topic。 硬性要求，CI 会检查。
4. 目录条目。 一个 YAML 文件，其中 description.en 含 : 时必须加引号，否则解析器会把它读成嵌套键。

这个工具在联网之前会先检查这四项，然后再上传。

它做什么

| 步骤 | 详情 |
| 预检 | 校验清单、三个标识符、topic 和测试 |
| 认证 | GitHub device flow——不用粘贴 token，不共享密码 |
| 创建 | 创建公开仓库（或复用已有仓库） |
| 上传 | 一次提交推送整棵目录树，保留目录结构 |
| Topic | 设置 dsh-plugin 及相关 topic |
| 目录 | 写出 <owner>__<repo>.yml，供 awesome-list 提 PR |

安全护栏

- 默认 dry run 吗？ 不——但 --dry-run 会校验并打印计划，不碰网络。
- 绝不 force-push。 如果分支已有提交，它会拒绝，除非传入 --force，而且会先展示哪些内容会被覆盖。
- 绝不发布密钥。 匹配常见凭据模式的文件会被报告并跳过。
- token 处理。 device-flow token 写到仓库外的 0600 文件，运行结束即删除。绝不打印。
- 吊销提醒。 每次运行结束都会告诉你到哪里吊销访问权限。

安装

作为 DSH 插件——在 harness 内加一个 /publish-plugin 命令，包办全部工作：

dsh plugin --profile desktop add github:Gty2408/dsh-plugin-publish

然后，在任意会话里：

/publish-plugin # validate the plugin in the workspace
/publish-plugin --push # validate, then publish it
/publish-plugin ./my-plugin --push --category ui

token 从 ~/.dsh/.github-token 读取（带 repo scope 的 classic token），或从插件的 token 配置读取。

作为独立命令行工具，在 harness 之外使用：

npx dsh-plugin-publish ./my-plugin --token <token> --yes
npx dsh-plugin-publish --help

两种认证方式

| 方式 | 何时使用 |
| 设备流（默认） | 交互式。打印一个短代码，你在浏览器里授权。不用粘贴 token。 |
| --token | 非交互式，或者 github.com 连不上但 api.github.com 能用时。 |

设备流访问 github.com；API 调用访问 api.github.com。
这两个主机的可达性可能不同，所以才有了 token 这条路。

插件命令做什么

/publish-plugin [directory] [--push] [--repo name] [--category name]

不带 --push 时，它只校验并打印将要提交的目录条目。
带 --push 时，它先校验，然后创建仓库、上传目录树、设置必需的 topic，并写入目录条目文件。

校验始终先跑，而且不碰网络，所以清单有问题不会把仓库发布到一半。

安全护栏

- 任何网络操作之前先校验。 清单有问题就在本地中止。
- 绝不 force-push，除非配置里设了 force: true。
- 绝不发布密钥。 匹配凭据模式的文件会被报告出来。
- 报告部分进度。 中途失败会留下一个仓库，所以输出会说明已经发生了什么。
- token 处理。 设备流 token 写入仓库外一个 0600 文件，运行结束时删除。绝不打印。
- 吊销提醒。 每次运行结束都会指向吊销页面。

已知限制

- repo scope 不能删除仓库 —— 那需要 delete_repo。所以工具从不提供清理；删除是手动步骤。
- 目录条目写在插件旁边，不会提交：提交它是对 awesome-dsh-plugin 发 PR，工具不会替你开。
- 目标仓库必须至少存在 1 天，那个 PR 才能通过 CI。

要求

- Node.js 20+
- 一个 GitHub 账号

许可证

MIT