plugin-publish

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

首次发布：

1. 确认已登录 npm：npm whoami
2. 如未登录：npm login
3. 确认包名未被占用：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 文件列表正确
• 版本号已更新