plugin-release

English | 简体中文

plugin-release

安全发布已开发并测试的插件。发布是单向的外发操作——在实际发布或推送标签之前，先展示计划并获得确认；此技能不会替你决定版本号，也绝不会自动提升版本号。

第 0 步：确认目标版本和发布渠道

发布渠道	适用场景	关键事实
GitHub 直接安装	dsh plugin --profile <p> add github:owner/repo	使用者会解析默认分支的 HEAD；发布 = 推送到 main——推送前运行完整的发布检查
npm registry	npm publish	仅适用于官方发布线；带有 alpha/rc 前缀的 @deepseek-ai/* 版本不保证会发布到 npm——发布前通过 npm view <pkg> versions 验证
hub 列表	在 hub 目录中注册	注册是独立操作，不能替代打包验证
集合	将成员插件打包进集合产物	遵循所属集合仓库自身的流程

未发布的批次（例如从未发布到 npm 的某个批次版本——alpha.1 仅发布于 GitHub；alpha.2 到 alpha.4 则以 alpha dist-tag 发布）应按照 references/publish-playbook.md 中的覆盖流程处理。不要查找 npm 上不存在的版本，也不要因此切换包管理器。

第 1 步：打包并验证产物

1. 使用仓库指定的唯一包管理器和锁文件（package-lock.json → npm，pnpm-lock.yaml → pnpm）；
2. 运行完整的发布检查（见第 3 步），然后执行 npm pack / pnpm pack；
3. 解包并验证：files 覆盖所有运行时相对导入和资源；产物中没有遗留的 .ts 文件；cordis.patch.yml / dsh.plugin.json / SKILL.md 等清单文件均已包含；
4. 将 tarball 安装到隔离的 profile 中进行使用验证（插件条目会出现在 dsh --profile compat --dump-config 中 → 工具已真正注册并可以执行）。

第 2 步：版本依赖基线（alpha 阶段）

• devDependencies 使用 npm 发布线（当前为 0.1.1-rc.2）作为类型基线，确保公共仓库在任何机器上执行 npm install 后都能通过类型检查；
• peer 范围使用较宽的范围（例如 <0.2.0），以覆盖未发布的 alpha/rc 版本；
• 当代码必须同时兼容本地测试框架（GitHub 标签）和 npm 发布线时，使用 双兼容模式：保留 npm 发布线类型所要求的结构，同时确保 alpha 运行时语义保持不变（见 playbook 中的“双兼容模式”章节）；
• 绝不要在已提交的 package.json 中写入本地绝对路径（junction/file:）。

第 3 步：发布检查（逐层进行；较低层通过后才能进入下一层）

1. 依赖解析：锁文件的变更符合预期；没有混用不同批次；
2. 静态检查：类型检查 + 插件测试 + 构建；
3. 实际挂载：在隔离的 profile 上冷启动目标宿主，并固定到精确的 DSH 标签（绝不能让可变的 master/main 冒充验收版本）；确保入口处于启用状态，且没有未完成的服务。Web Client 插件还必须验证：宿主公布的资源（启动清单/启动列表中的 bundle 入口）可访问、bundle 注册成功、DOM 挂载完成，且没有页面错误——仅查看 --dump-config 并不能完成这一层的验证；
4. 行为验证：实际执行一条核心路径（对于工具插件：一条消息 → 工具 → 响应；或等效的专用流程）；
5. 包装器：验证退出代码以及 stdout/stderr 的归属。

第 4 步：发布语义门禁（任一检查失败即停止发布）

1. GitHub Release 标签必须与 v${package.json.version} 相同；
2. 版本是否带有预发布后缀（- 之后、+ 构建元数据之前的部分）必须与 GitHub Release 的预发布状态一致；
3. 预发布版本只能使用项目声明的非 latest dist-tag（名称由项目选择，例如 next 或 alpha——此技能不会硬编码特定名称）；只有不带后缀的稳定版本才能使用 latest；
4. 发布稳定版本之前，查询当前的 latest（npm view <pkg> dist-tags.latest），如果 semver 低于现有的 latest，则拒绝发布，以防 latest 回退到较低版本。

第 5 步：发布与回滚

• 发布之前：提交和标签都必须干净；记录 lockfile 和组合基线的哈希；
• 发布之后：以使用者身份重新安装一次并进行冒烟测试；
• 回滚：优先撤销发布（删除标签／将标签重新指向旧提交）；不要发布“兼容新旧两侧”的补丁来掩盖问题；
• 关于尚未发布 cohort 的 CI，请参阅操作手册中的“CI 和发布门禁”部分（cohort 存储缓存、NPM_PUBLISH_ENABLED 开关）。

安全边界

• 任何发布／推送标签／写入 hub 注册信息之前，都要展示计划并获得确认；绝不自动提升版本；
• 绝不发布包含凭据、.npmrc 内容、会话日志或私有路径的构件；
• 不要切换包管理器或改写其他 lockfile；如果失败，只回滚本次运行所管理的路径，并报告遗留内容。

参考资料

文件	内容
references/publish-playbook.md	尚未发布 cohort 的安装、双兼容模式、CI／发布门禁、真实问题列表和回滚方案
references/profile-dependency-management.md	Profile 安装／更新方案：GitHub 依赖锁缓存、重命名包时的三处同步、junction 清理和主机升级关联