第 52 章

Plugin 中的 Hook 系统：注入生命周期事件实现确定性工程控制

第五十二章：发布到 Skills 市场：打包、审核与版本管理

52.1 clawhub.ai：Claude 生态的应用市场

clawhub.ai 是 Claude 官方 Plugin 和 Skill 市场（简称"市场"或"Hub"）。它扮演着与 npm、PyPI、VS Code Marketplace 相似的角色，是开发者发布、用户发现和安装扩展的中心平台。

截至 2026 年 4 月，clawhub.ai 已托管超过 12,000 个 Plugin 和 85,000 个独立 Skill，月活跃安装次数超过 200 万次。理解其发布流程和审核标准，是每一个 Claude 生态开发者的必修课。

市场的主要功能

发现：分类浏览、关键词搜索、精选推荐
安装：一键安装到本地 Claude Code 或组织工作区
版本管理：查看更新日志、回滚到历史版本
评价体系：用户评分和使用量统计
依赖解析：自动安装 Plugin 所依赖的其他 Plugin

52.2 发布前准备

注册开发者账号

在发布之前，你需要在 clawhub.ai 注册一个开发者账号：

# 通过 CLI 登录（会打开浏览器完成 OAuth 授权）
claude-plugin login

# 验证登录状态
claude-plugin whoami
# 输出：
# Logged in as: [email protected]
# Publisher namespace: janedoe
# Verified: ✓

注意：发布需要账号完成邮件验证。企业开发者还需要通过组织认证流程，获得组织发布命名空间（如 acmecorp）。

最终检查清单

在打包发布前，对照以下清单进行最终检查：

□ plugin.json 版本号已更新
□ 所有 TypeScript 源码已编译（npm run build）
□ claude-plugin validate 通过（无错误）
□ README.md 已编写（市场展示页必须内容）
□ CHANGELOG.md 已更新（记录本版本变更）
□ 许可证文件（LICENSE）存在
□ 不包含任何 .env 或含有 secrets 的文件
□ 敏感配置项已标记 "secret": true
□ 测试在本地通过
□ 已在 Claude Code 本地安装并手动验证

README.md 要求

市场展示页面直接渲染 Plugin 根目录下的 README.md。一份好的 README 应包含：

# Weather Plugin

A Claude Plugin that provides real-time weather data and forecasts.

## Features

- Current weather conditions for any city worldwide
- 1-7 day forecasts with temperature, precipitation, and wind data
- Automatic city name geocoding (supports Chinese and English names)

## Installation

```bash
claude plugin install weather-plugin

Configuration

Field	Type	Required	Description
defaultCity	string	No	Default city (default: Beijing)
temperatureUnit	string	No	celsius or fahrenheit (default: celsius)

Included Skills

weather-query: Query current weather or forecasts for any city

Requirements

Claude Code >= 1.0.0
Internet access (for Open-Meteo API)

Privacy

This plugin makes outbound HTTP requests to:

geocoding-api.open-meteo.com — for city name geocoding
api.open-meteo.com — for weather data

No personal data is transmitted to these services.


## 52.3 打包流程

### 打包命令

```bash
# 基本打包
claude-plugin pack

# 指定输出路径
claude-plugin pack --output ./releases/weather-plugin-1.0.0.clpkg

# 包含源码映射（便于调试，会增大包体积）
claude-plugin pack --include-sourcemaps

# 验证模式（打包前运行完整验证）
claude-plugin pack --strict

.clpkg 包格式

.clpkg（Claude Plugin Package）是一种特殊的 ZIP 格式，包含以下内容：

weather-plugin-1.0.0.clpkg（实质上是 ZIP）
├── manifest.json          ← 从 plugin.json 生成，含额外元数据
├── dist/                  ← 编译后的 JavaScript 文件
│   ├── mcp/server.js
│   ├── hooks/pre-tool.js
│   └── monitor/collector.js
├── skills/                ← Skill 文件（原始 Markdown）
│   └── weather-query.md
├── README.md
├── CHANGELOG.md
├── LICENSE
└── signature.sig          ← 包签名（用你的开发者私钥生成）

签名机制确保了包的完整性：用户安装时，Claude Code 会验证签名，防止包在传输过程中被篡改。

检查包内容

# 列出包内所有文件
claude-plugin pack inspect weather-plugin-1.0.0.clpkg

# 输出：
# manifest.json (3.2 KB)
# dist/mcp/server.js (28.5 KB)
# dist/hooks/pre-tool.js (4.1 KB)
# skills/weather-query.md (1.8 KB)
# README.md (2.3 KB)
# CHANGELOG.md (0.9 KB)
# LICENSE (1.1 KB)
# signature.sig (0.5 KB)
# ─────────────────────
# Total: 42.4 KB (compressed: 16.2 KB)

52.4 发布流程

提交到市场

claude-plugin publish weather-plugin-1.0.0.clpkg

发布命令执行以下步骤：

1. 本地预校验（格式、签名、必要文件）
2. 上传到 clawhub.ai CDN
3. 触发自动化审核流程
4. 返回审核追踪 URL

成功提交后输出：

✓ Package validated locally
✓ Uploaded to clawhub.ai (16.2 KB)
✓ Automated checks started

Package ID: janedoe/[email protected]
Review URL: https://clawhub.ai/publisher/reviews/abc123
Status: pending_automated_checks
Estimated review time: 2-4 hours

自动化审核阶段

自动化审核在 Anthropic 的安全环境中运行，通常在 1-2 小时内完成：

自动化审核清单：

□ 静态代码分析
  ├── 无已知恶意代码模式
  ├── 无硬编码的 API 密钥或密码
  └── 依赖包无已知 CVE（高危及以上）

□ 权限合规性检查
  ├── 实际使用的权限与 plugin.json 声明一致
  ├── 无超出声明范围的网络请求
  └── 无未声明的文件系统访问

□ MCP 协议合规
  ├── 工具定义符合 JSON Schema 规范
  ├── 响应格式符合 MCP 标准
  └── 无协议版本不兼容问题

□ Skill 文件质量
  ├── YAML frontmatter 语法正确
  ├── required 字段完整
  └── 无明显的恶意指令注入尝试

人工审核阶段

通过自动化审核后，部分 Plugin 会进入人工审核队列。触发人工审核的条件包括：

请求了高敏感权限（execute:arbitrary-code, access:credentials）
包含外部网络请求到未知域名
自动化工具标记了需要判断的边界情况
这是开发者发布的第一个 Plugin（新开发者首发审核）

人工审核通常在 24-48 小时内完成。审核人员会检查：

Skill 文件的行为指令是否有安全风险
Plugin 描述是否与实际功能一致
是否存在误导性命名（仿冒官方或知名 Plugin）

审核结果处理

# 查看审核状态
claude-plugin review status abc123

# 可能的状态：
# pending_automated_checks  - 等待自动化审核
# automated_passed           - 自动化通过，等待人工
# under_manual_review        - 人工审核中
# approved                   - 审核通过，已发布
# changes_requested          - 需要修改后重新提交
# rejected                   - 拒绝（附有理由）

如果审核返回 changes_requested，你会收到具体的修改意见：

Review feedback for janedoe/[email protected]:

[REQUIRED] Network access transparency
  Your plugin makes requests to api.open-meteo.com, but your README
  does not mention this. Please add a Privacy section documenting all
  external endpoints your plugin communicates with.

[SUGGESTED] Skill quality improvement
  The weather-query skill's "Edge Cases" section does not cover the
  scenario where the Open-Meteo API is temporarily unavailable.
  Consider adding guidance for this case.

修改完成后，更新版本号（修订号即可），重新打包并发布：

# 修改 plugin.json: "version": "1.0.1"
npm run build
claude-plugin pack
claude-plugin publish weather-plugin-1.0.1.clpkg

52.5 版本管理策略

语义化版本的实践

在 clawhub.ai 生态中，版本号不只是数字——它是对用户的承诺：

1.0.0 → 1.0.1  修订版本：修复 bug，改善文档，无功能变更
1.0.0 → 1.1.0  次版本：新增功能，向下兼容
1.0.0 → 2.0.0  主版本：破坏性变更，需要用户迁移

何时发布破坏性变更（主版本升级）：

删除或重命名了已有的 MCP 工具（依赖该工具的 Skill 会失效）
修改了 Skill 的 required 参数（现有调用会报错）
修改了工具的返回格式（依赖旧格式的代码会崩溃）
删除了 Hook 实现（之前依赖该 Hook 副作用的行为会改变）

CHANGELOG.md 格式规范

遵循 Keep a Changelog 格式：

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.0] - 2026-04-28

### Added
- `get_weather_alerts` tool for severe weather warnings
- `weather-alerts` skill for alert notifications
- Support for Fahrenheit in forecast tool

### Changed
- Improved geocoding accuracy for Chinese city names

### Fixed
- Fixed crash when city name contains special characters

## [1.0.1] - 2026-04-10

### Fixed
- Fixed README missing Privacy section (per review feedback)

## [1.0.0] - 2026-04-01

### Added
- Initial release
- `get_current_weather` tool
- `get_weather_forecast` tool
- `weather-query` skill

多版本并存策略

clawhub.ai 支持同时维护多个主版本。当你发布 2.0.0 时，1.x 版本不会自动失效，用户可以选择停留在 1.x。

在 plugin.json 中通过 deprecation 字段标记旧版本：

{
  "version": "1.0.1",
  "deprecation": {
    "message": "Please upgrade to v2.x for improved performance",
    "since": "2026-05-01",
    "sunset": "2026-11-01"
  }
}

sunset 日期后，旧版本将从市场下架，但已安装的用户不受影响（可以继续使用，只是无法新安装）。

52.6 私有发布与企业选项

并非所有 Plugin 都适合公开发布。clawhub.ai 提供三种可见性级别：

可见性	说明	适用场景
`public`	所有人可搜索和安装	开源工具、通用 Skill
`unlisted`	有链接可安装，不在搜索结果中显示	内部工具、测试版本
`private`	仅组织成员可见（需企业账号）	企业内部 Plugin

设置可见性：

# 发布为未列出（unlisted）
claude-plugin publish weather-plugin-1.0.0.clpkg --visibility unlisted

# 发布为私有（需要企业账号）
claude-plugin publish weather-plugin-1.0.0.clpkg --visibility private \
  --org acmecorp

企业私有注册表的详细配置将在第五十六章介绍。

52.7 自动化发布流程（CI/CD）

在 GitHub Actions 中配置自动化发布：

# .github/workflows/publish.yml
name: Publish to clawhub.ai

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build
        run: npm run build
        
      - name: Install Claude Plugin CLI
        run: npm install -g @claude/plugin-cli
        
      - name: Validate
        run: claude-plugin validate --strict
        
      - name: Pack
        run: claude-plugin pack
        
      - name: Publish
        env:
          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
        run: |
          claude-plugin login --token $CLAWHUB_TOKEN
          claude-plugin publish *.clpkg

在 GitHub 仓库的 Secrets 中配置 CLAWHUB_TOKEN（从 clawhub.ai 开发者设置页面生成）。

52.8 发布后运营

监控安装数据

# 查看 Plugin 统计数据
claude-plugin stats weather-plugin

# 输出：
# Package: janedoe/weather-plugin
# ─────────────────────────────
# Total installs:     3,847
# Active this month:  1,204
# Rating:             4.7 / 5.0 (89 reviews)
# 
# Version distribution:
#   1.1.0:  68%
#   1.0.1:  28%
#   1.0.0:   4%

响应用户反馈

clawhub.ai 的 Issues 功能允许用户提交 Bug 报告和功能请求。开发者有责任：

在 7 天内对 P1（崩溃类）Bug 作出响应
在 30 天内对一般 Bug 作出响应
对功能请求给出明确的接受/拒绝理由

响应质量影响 Plugin 在市场中的排名权重。

紧急下架

如果发现严重安全漏洞，可以立即下架：

# 紧急下架指定版本
claude-plugin unpublish [email protected] --reason "Security vulnerability in geocoding"

# 下架所有版本
claude-plugin unpublish weather-plugin --all --reason "Critical security issue"

下架后，已安装的用户会收到安全警告提示，建议他们更新或卸载。

小结

clawhub.ai 的发布流程覆盖了从代码到用户手中的完整链路：打包（生成签名的 .clpkg）→ 提交（触发自动化+人工审核）→ 发布（在市场上线）→ 运营（监控数据、响应反馈、版本迭代）。语义化版本号不只是惯例，而是对用户的兼容性承诺。CHANGELOG.md 是发布文化的重要组成部分。CI/CD 自动化发布是持续迭代的最佳实践。下一章将转向一个特殊类型的 Plugin：主题与外观插件。

本章评分

4.5 / 5 (3 评分)