plugin-publish - SKILL.md Agent Skill

name: plugin-publish description: "发布 Zhin.js 插件到 npm 和 Zhin 插件市场。Use when asked to publish a plugin, prepare for release, check publish readiness, or submit to the Zhin plugin marketplace. 引导完成发布前检查、版本管理和提交流程。" keywords: - 发布 - publish - npm - 插件市场 - marketplace - release - 版本 - version - changeset tags: - development - plugin - publish - release

Zhin 插件发布

引导将 Zhin.js 插件发布到 npm 和 Zhin 插件市场，确保包结构、元数据和质量符合社区标准。

适用场景

用户说"发布插件"、"提交到插件市场"、"准备发版"
插件开发完成需要分享给社区
需要检查插件是否满足发布条件

发布前检查清单

第 1 步：包元数据检查

验证 package.json 必需字段：

{
  "name": "zhin.js-{name}",          // ✅ 社区前缀
  "version": "0.1.0",                 // ✅ 语义化版本
  "type": "module",                    // ✅ ESM
  "description": "插件简介",           // ✅ 非空描述
  "main": "./lib/index.js",           // ✅ 入口指向编译产物
  "types": "./lib/index.d.ts",        // ✅ 类型声明
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "development": "./src/index.ts", // ✅ 开发条件导出
      "import": "./lib/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": [                           // ✅ 发布文件白名单
    "src", "lib", "client", "dist",
    "skills", "tools",
    "README.md", "CHANGELOG.md"
  ],
  "keywords": ["zhin.js", "plugin"],   // ✅ 包含 zhin.js 关键词
  "peerDependencies": {
    "zhin.js": ">=x.x.x"              // ✅ 声明框架兼容版本
  },
  "license": "MIT",                    // ✅ 开源协议
  "repository": { "url": "..." },      // 推荐：仓库地址
  "homepage": "...",                    // 推荐：文档地址
  "author": "..."                       // 推荐：作者信息
}

插件市场识别条件：

name 以 zhin.js- 开头（社区）或 @zhin.js/ 开头（官方）
keywords 包含 zhin.js
peerDependencies 包含 zhin.js

第 2 步：代码质量检查

# 1. 类型检查
pnpm build            # 确保 tsc 编译通过，无类型错误

# 2. 运行测试
pnpm test             # 确保所有测试通过

# 3. 覆盖率检查
pnpm test:coverage    # 确保覆盖率达标

质量底线：

tsc 编译零错误
所有测试通过
语句覆盖率 ≥ 60%
无 any 类型滥用
无未处理的 TODO/FIXME 阻塞发布

第 3 步：文档检查

README.md 必须包含：

插件功能简介
安装步骤（pnpm add zhin.js-{name}）
配置说明（配置项及默认值）
命令列表（如有）
AI 工具说明（如有）
使用示例

CHANGELOG.md 必须包含：

当前版本的变更记录
遵循 Keep a Changelog 格式

关键词： 有 skills/ 目录时，确认 SKILL.md 的 description 准确描述插件能力。

第 4 步：构建产物检查

# 确保 lib/ 目录存在且完整
ls lib/

# 检查将要发布的文件
npm pack --dry-run

确认 npm pack 输出的文件列表：

✅ 包含 lib/（编译后的 JS + d.ts）
✅ 包含 src/（源码，供开发模式使用）
✅ 包含 skills/（AI 技能描述）
✅ 包含 README.md、CHANGELOG.md
❌ 不包含 node_modules/、tests/、.env
❌ 不包含 coverage/、.DS_Store

第 5 步：版本管理

语义化版本规则：

patch (0.1.0 → 0.1.1)：bug 修复、文档更新
minor (0.1.0 → 0.2.0)：新增功能、新增命令
major (0.1.0 → 1.0.0)：破坏性变更、API 不兼容

# 更新版本号
npm version patch   # 或 minor / major

# 使用 Changesets（如项目已配置）
pnpm changeset      # 创建变更记录
pnpm changeset version  # 更新版本

第 6 步：发布

# 发布到 npm
npm publish --access public

# 如果是 scoped 包（@zhin.js/xxx），需要 --access public
npm publish --access public

首次发布：

确认已登录 npm：npm whoami
如未登录：npm login
确认包名未被占用：npm view zhin.js-{name}

第 7 步：发布后验证

# 1. 等待 npm 索引更新（通常 1-2 分钟）

# 2. 在新项目中测试安装
pnpm add zhin.js-{name}

# 3. 确认插件可正常加载
# 在 zhin.config 中添加插件名，启动 bot 验证

常见问题

包名已被占用

社区插件前缀固定为 zhin.js-
如果被占用，考虑更具体的名称如 zhin.js-music-search

发布时 files 不对

检查 .gitignore 和 .npmignore
使用 npm pack --dry-run 预检

peerDependencies 版本范围

使用 >=x.x.x 而不是精确版本
确保与当前 zhin.js 最新版本兼容

失败与兜底

触发条件	一线处理	仍失败
`tsc` / `test` 失败	停止发布，先修或交 `plugin-quality`	不得在红灯下 `npm publish`
`npm pack` 缺文件	修 `files` 白名单与 `.npmignore`	对照官方 adapter 的 `package.json`
包名已占用	换更具体名如 `zhin.js-music-search`	`npm view <name>` 确认
无 npm 登录	`npm whoami`；未登录则 `npm login`	仅输出发布检查报告，不代发

🔴 CHECKPOINT · 发布确认

npm publish 前向用户确认：版本号、CHANGELOG、是否已跑完 test/coverage、npm pack --dry-run 结果。

不要做什么

不要发布含密钥、.env、私服的 files 条目
不要跳过测试强行发 patch
不要把 tests/、coverage/ 打进 npm 包
不要对 scoped 包忘记 --access public
不要用本 skill 代替 Changeset 流程（monorepo 官方包）

检查清单（发布门禁）

name 遵循 zhin.js-{name} 命名规范
keywords 包含 zhin.js
peerDependencies 声明 zhin.js
type: "module" 已设置
exports 包含 types + development + import
files 白名单正确（含 src、lib、skills）
tsc 编译通过
所有测试通过
覆盖率达标（≥ 60% statements）
README.md 完整
CHANGELOG.md 更新
SKILL.md description 准确（如有 skills/）
npm pack --dry-run 文件列表正确
版本号已更新