第 36 章

发布到 ClawHub / 插件市场

第36章：发布到 ClawHub / 插件市场

ClawHub 是 Hermes Agent 生态的官方 Skill 发布市场，类似 Python 生态的 PyPI 或 Node.js 的 npm，但专为 AI Agent Skill 设计。一个高质量的 Skill 如果只在本地使用，就像一个绝佳的发明被锁在抽屉里。本章从账号注册到 Skill 上架，完整演示发布流程，并深入讲解如何通过 SEO 优化让你的 Skill 被更多用户发现。

36.1 ClawHub 生态概览

ClawHub 的定位

┌──────────────────────────────────────────────────────────────┐
│                        ClawHub 生态                           │
├──────────────────────┬───────────────────────────────────────┤
│    对 Skill 开发者    │         对 Hermes 用户                 │
├──────────────────────┼───────────────────────────────────────┤
│ • 发布和分发 Skill    │ • 搜索和安装 Skill                     │
│ • 版本管理            │ • 查看文档和示例                        │
│ • 收集用户反馈        │ • 评分和评论                           │
│ • 分析下载数据        │ • 报告 Bug                            │
│ • 商业化（付费 Skill）│ • 请求新功能                           │
└──────────────────────┴───────────────────────────────────────┘

ClawHub 与 OpenClaw 生态关系

OpenClaw 生态
├── ClawHub（官方市场）— Skill 发布、审核、分发
├── OpenClaw SDK（工具集）— Skill 开发、测试、打包
├── ClawHub CLI（命令行）— 自动化发布工具
└── ClawHub API（REST API）— 程序化管理 Skill

36.2 发布前准备：包结构与清单

标准 Skill 包结构

my-awesome-skill/
├── skill.yaml              # 必须：Skill 清单文件
├── README.md               # 必须：文档（Markdown 格式）
├── LICENSE                 # 必须：许可证
├── CHANGELOG.md            # 推荐：变更历史
│
├── src/
│   └── my_awesome_skill/
│       ├── __init__.py
│       ├── skill.py        # 主 Skill 实现
│       ├── tools.py        # 工具实现
│       └── schemas.py      # 输入输出 Schema
│
├── tests/
│   ├── test_skill.py
│   ├── test_tools.py
│   └── fixtures/
│
├── examples/
│   ├── basic_usage.py
│   └── advanced_usage.py
│
└── .clawhubignore          # 发布时忽略的文件（类似 .gitignore）

.clawhubignore 示例

# 开发文件
.env
.env.local
*.pyc
__pycache__/
.pytest_cache/
.mypy_cache/

# 测试和 CI
tests/
.github/
.gitlab-ci.yml

# 编辑器配置
.vscode/
.idea/
*.swp

# 大型媒体文件
*.mp4
*.zip
dataset/

完整的 skill.yaml 清单

# skill.yaml — 发布用完整清单
name: smart-summarizer-skill
version: "1.2.0"
description: |
  使用多模型融合策略生成高质量中英文摘要，支持长文档（10万字以内），
  自动识别文档类型（学术/新闻/技术/商业），并针对不同类型采用专属摘要策略。
  
  特性：
  - 支持 PDF、Word、Markdown、HTML 等格式输入
  - 中英文双语摘要生成
  - 可调节摘要长度（50-500字）
  - 关键词自动提取
  
author:
  name: "Zhang Wei"
  email: "[email protected]"
  url: "https://zhangwei.dev"

maintainers:
  - name: "Li Ming"
    email: "[email protected]"

license: "Apache-2.0"
homepage: "https://clawhub.ai/skills/smart-summarizer"
repository: "https://github.com/zhangwei/smart-summarizer-skill"
documentation: "https://smart-summarizer-skill.readthedocs.io"
issues: "https://github.com/zhangwei/smart-summarizer-skill/issues"

# 类别标签（影响搜索排名）
categories:
  - "text-processing"
  - "summarization"
  - "nlp"
  - "productivity"

# 关键词（影响搜索）
keywords:
  - "summarize"
  - "abstract"
  - "text summary"
  - "document processing"
  - "NLP"
  - "摘要"
  - "文本摘要"
  - "文档处理"

hermes_runtime: ">=1.5.0"
python: ">=3.10"

dependencies:
  core-nlp-skill: "^2.0.0"
  pdf-reader-skill: "^1.3.0"

# 支持的 MCP 工具
mcp_tools:
  - name: "summarize_text"
    description: "对给定文本生成摘要"
  - name: "summarize_document"
    description: "对文件路径指向的文档生成摘要"
  - name: "extract_keywords"
    description: "从文本中提取关键词列表"

# 演示截图（显示在 ClawHub 详情页）
screenshots:
  - url: "https://raw.githubusercontent.com/.../screenshot1.png"
    caption: "基础用法示例"
  - url: "https://raw.githubusercontent.com/.../screenshot2.png"
    caption: "批量文档处理"

36.3 发布流程：从账号到上架

步骤一：创建 ClawHub 账号并初始化

# 安装 ClawHub CLI
pip install clawhub-cli

# 登录（浏览器 OAuth 授权）
clawhub login

# 验证登录状态
clawhub whoami
# 输出: Logged in as zhangwei ([email protected])

# 初始化 API Token（用于 CI/CD）
clawhub token create --name "github-actions" --scope "publish"
# 输出: Token: chub_tok_xxxxxxxxxxxx（保存到 GitHub Secrets）

步骤二：验证 Skill 包

# 进入 Skill 目录
cd smart-summarizer-skill/

# 运行本地验证
clawhub validate

验证器会检查以下内容：

ClawHub Skill 验证报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ skill.yaml 格式正确
✓ 所有必填字段已填写
✓ 版本号符合 SemVer 规范
✓ README.md 存在且不为空 (2847 字)
✓ LICENSE 文件存在 (Apache-2.0)
✓ 代码测试通过 (23/23)
✓ 依赖可以正常解析
✓ 包大小在限制内 (4.2 MB / 50 MB)
✓ 无已知安全漏洞

⚠ 警告:
  - CHANGELOG.md 不存在（建议添加）
  - 测试覆盖率 72%（建议 >80%）

✗ 错误（必须修复后才能发布）:
  无

验证通过，可以发布。

步骤三：构建发布包

# 构建 .skill 包文件
clawhub build

# 查看包内容
clawhub build --list
# 输出:
# smart-summarizer-skill-1.2.0.skill
#   skill.yaml                  2.1 KB
#   README.md                   8.3 KB
#   LICENSE                     11.2 KB
#   src/                        42.1 KB
#   examples/                   3.8 KB
# 总大小: 67.5 KB

步骤四：提交发布

# 发布到 ClawHub
clawhub publish

# 发布预发布版本（不显示在默认搜索中）
clawhub publish --tag beta

# 发布到私有注册中心（企业用户）
clawhub publish --registry https://private.registry.company.com

# 带版本说明的发布
clawhub publish --release-notes "修复了大型 PDF 处理的内存溢出问题"

步骤五：发布后验证

# 验证发布成功
clawhub info smart-summarizer-skill
# 输出: 版本 1.2.0 已发布，审核中...

# 查看审核状态
clawhub status [email protected]
# 输出: 状态: 审核中（预计 24-48 小时）

# 安装自己的 Skill 测试
hermes skill install [email protected]

36.4 审核标准与常见拒绝原因

ClawHub 对所有提交的 Skill 进行自动审核（即时）和人工审核（1-3 个工作日）。

审核维度

ClawHub 审核标准
├── 技术合规
│   ├── Skill 可以正常安装和运行
│   ├── 所有声明的 MCP 工具实际可用
│   ├── 无恶意代码（静态扫描 + 沙箱执行）
│   └── 依赖无已知高危漏洞（CVE 扫描）
│
├── 内容质量
│   ├── README 清晰描述功能和使用方法
│   ├── 有至少一个可运行的代码示例
│   ├── 版本号变更有对应说明
│   └── 功能与描述一致（不夸大宣传）
│
├── 合规性
│   ├── 有明确的开源或商业许可证
│   ├── 不包含违法内容
│   ├── 数据收集已明确告知用户
│   └── 不侵犯他人知识产权
│
└── 生态规范
    ├── 名称不与已有 Skill 冲突或混淆
    ├── 不恶意刷关键词（SEO 作弊）
    └── 不包含无关功能（捆绑软件）

常见拒绝原因与解决方案

拒绝原因	频率	解决方案
README 太简短（<500 字）	35%	添加功能说明、快速开始、API 参考
无代码示例	28%	在 README 和 examples/ 中添加示例
依赖有高危漏洞	15%	运行 `clawhub audit --fix` 升级依赖
Skill 安装后无法运行	12%	本地用 `hermes skill test` 验证
描述与功能不符	6%	如实描述，去掉夸大内容
名称与已有 Skill 相似	4%	使用更具区分度的名称

加速审核的技巧

# 提交时附上测试报告
clawhub publish --attach-test-report

# 提供在线 Demo（加快审核员验证）
clawhub publish --demo-url "https://demo.smart-summarizer.com"

# 联系审核员（首次发布推荐）
clawhub review --request-human --message "首次发布，请重点验证 PDF 解析功能"

36.5 SEO 优化：让你的 Skill 被搜索到

ClawHub 的搜索算法综合考虑以下因素：

搜索排名权重（近似）
├── 文本相关性（35%）
│   ├── Skill 名称匹配
│   ├── description 关键词
│   └── keywords 字段
├── 质量信号（25%）
│   ├── 下载量
│   ├── 用户评分（1-5星）
│   └── 活跃维护（最近更新时间）
├── 文档质量（20%）
│   ├── README 长度和结构
│   ├── 有代码示例
│   └── 有截图
└── 社区信号（20%）
    ├── GitHub Star 数
    ├── Issue 响应速度
    └── 社区讨论活跃度

高质量 README 结构模板

# Smart Summarizer Skill

> 一句话描述 Skill 的核心价值

智能摘要 Skill，使用多模型融合策略生成高质量中英文摘要，支持 PDF/Word/HTML 等主流格式。
平均比单模型摘要质量提升 40%，处理速度 3x 于同类方案。

## 快速开始

\```python
import asyncio
from hermes import Agent

async def main():
    agent = Agent()
    result = await agent.run_skill(
        "smart-summarizer-skill",
        action="summarize_text",
        text="...",
        max_length=200,
        language="zh"
    )
    print(result.summary)

asyncio.run(main())
\```

## 功能特性

- **多格式支持**：PDF、Word、Markdown、HTML、纯文本
- **双语输出**：中英文摘要同时生成
- **长度控制**：50-500字可调
- **类型识别**：自动识别学术/新闻/技术/商业文档

## 安装

\```bash
hermes skill install smart-summarizer-skill
\```

## MCP 工具参考

### `summarize_text`

**输入参数：**
| 参数 | 类型 | 必须 | 说明 |
|------|------|------|------|
| text | string | 是 | 要摘要的文本 |
| max_length | integer | 否 | 摘要最大长度（默认200字）|
| language | string | 否 | 输出语言（zh/en/auto）|

**返回值：**
\```json
{
  "summary": "摘要文本",
  "keywords": ["关键词1", "关键词2"],
  "document_type": "academic",
  "confidence": 0.92
}
\```

## 基准测试

| 文档大小 | 处理时间 | 摘要质量（ROUGE-L）|
|---------|---------|------------------|
| 1000字  | ~2s     | 0.68             |
| 10000字 | ~8s     | 0.72             |
| 50000字 | ~25s    | 0.71             |

## 许可证

Apache 2.0 — 详见 [LICENSE](LICENSE)

关键词策略

# skill.yaml 关键词优化
keywords:
  # 功能类关键词（用户最常搜索）
  - "text summarization"
  - "document summary"
  - "abstract generation"
  - "tldr"
  
  # 技术类关键词
  - "NLP"
  - "natural language processing"
  - "transformer"
  - "extractive summarization"
  - "abstractive summarization"
  
  # 中文关键词（中文用户搜索）
  - "文本摘要"
  - "自动摘要"
  - "文档总结"
  - "内容提炼"
  
  # 场景类关键词
  - "research paper"
  - "PDF processing"
  - "content creation"
  - "knowledge management"

36.6 版本更新流程

版本更新的最佳实践

# 1. 更新版本号（根据变更类型）
# Bug 修复：1.2.0 → 1.2.1
# 新功能：1.2.0 → 1.3.0
# 破坏性变更：1.2.0 → 2.0.0

# 2. 更新 CHANGELOG.md
cat >> CHANGELOG.md << 'EOF'
## [1.2.1] - 2024-11-20

### 修复
- 修复处理超过 100MB PDF 时的内存溢出问题 (#42)
- 修复英文 RTL 文本摘要错误 (#38)

### 改进
- 大型文档处理速度提升 20%
EOF

# 3. 更新 skill.yaml 中的版本号
sed -i 's/version: "1.2.0"/version: "1.2.1"/' skill.yaml

# 4. 验证并发布
clawhub validate && clawhub publish --release-notes "修复内存溢出和 RTL 文本问题"

自动化发布（GitHub Actions）

# .github/workflows/publish.yml
name: Publish to ClawHub

on:
  push:
    tags:
      - 'v*'   # 推送 tag 时触发

jobs:
  publish:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      
      - name: Install ClawHub CLI
        run: pip install clawhub-cli
      
      - name: Run tests
        run: |
          pip install -e ".[dev]"
          pytest tests/ --tb=short
      
      - name: Validate Skill
        run: clawhub validate
      
      - name: Build package
        run: clawhub build
      
      - name: Publish to ClawHub
        env:
          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
        run: |
          clawhub login --token $CLAWHUB_TOKEN
          clawhub publish --release-notes "$(git log -1 --pretty=%B)"
      
      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body_path: CHANGELOG.md

36.7 用户反馈处理

反馈处理工作流

# 自动化反馈处理脚本
# scripts/process_feedback.py
import asyncio
from clawhub_sdk import ClawHubClient

async def process_feedback():
    client = ClawHubClient(token="your_token")
    
    # 获取最新反馈
    feedback_list = await client.get_feedback(
        skill="smart-summarizer-skill",
        status="open",
        since_days=7
    )
    
    for feedback in feedback_list:
        print(f"[{feedback.type}] {feedback.title}")
        print(f"  用户: {feedback.user}")
        print(f"  内容: {feedback.body[:100]}...")
        print(f"  影响: {feedback.affected_users} 用户")
        
        # 自动分类
        if feedback.type == "bug" and feedback.severity == "critical":
            # 严重 Bug：立即创建 GitHub Issue
            await create_github_issue(feedback)
            # 回复用户
            await client.reply_feedback(
                feedback.id,
                "感谢您的报告！这是一个严重 Bug，我们将在 24 小时内发布修复。"
            )
        
        elif feedback.type == "feature_request":
            # 功能请求：记录到 Roadmap
            await add_to_roadmap(feedback)


# 反馈响应模板
RESPONSE_TEMPLATES = {
    "bug_ack": """
感谢您报告此问题！

我已经能够复现该问题。这将在下一个补丁版本（{next_version}）中修复。
预计发布时间：{eta}

作为临时解决方案：{workaround}

如有更多问题，请随时联系。
""",
    
    "feature_planned": """
感谢您的功能建议！

这个功能已在我们的路线图中（预计 {planned_version} 版本实现）。
您可以在 GitHub 上关注进展：{issue_url}
""",
    
    "cannot_reproduce": """
感谢您的报告！

我无法复现您描述的问题。能否提供以下信息以帮助诊断？
1. Hermes 版本（`hermes --version`）
2. Python 版本
3. 完整的错误堆栈跟踪
4. 触发问题的具体输入（可脱敏）
"""
}

本章小结

ClawHub 发布不只是"把代码上传"，而是一个完整的产品化过程：

包结构规范：标准化的目录结构、清单文件和文档让审核更顺畅
五步发布流程：账号 → 验证 → 构建 → 提交 → 发布后验证
审核标准：技术合规、内容质量、合规性和生态规范四个维度
SEO 优化：关键词策略、高质量 README、社区活跃度共同决定搜索排名
自动化发布：GitHub Actions 实现 tag 触发的零手动发布
反馈闭环：系统化处理用户反馈，持续提升 Skill 质量

思考题

如果你的 Skill 包含对第三方 API 的调用，用户在安装时如何配置自己的 API Key？如何在 ClawHub 页面上清晰说明这一点？
一个 Skill 发布后发现严重安全漏洞，你需要立即下架。ClawHub 是否应该提供"紧急下架"功能？下架后已安装该版本的用户如何处理？
如何设计一个"Skill 推荐算法"，让刚发布的高质量 Skill 也能被曝光，而不是总被老 Skill 霸占排名？
付费 Skill 的商业模式有哪些（一次性购买/订阅/按使用量计费），Hermes 如何在技术层面支持这些模式？

本章评分

4.6 / 5 (3 评分)

发布到 ClawHub / 插件市场

第36章：发布到 ClawHub / 插件市场

36.1 ClawHub 生态概览

ClawHub 的定位

ClawHub 与 OpenClaw 生态关系

36.2 发布前准备：包结构与清单

标准 Skill 包结构

.clawhubignore 示例

完整的 skill.yaml 清单

36.3 发布流程：从账号到上架

步骤一：创建 ClawHub 账号并初始化

步骤二：验证 Skill 包

步骤三：构建发布包

步骤四：提交发布

步骤五：发布后验证

36.4 审核标准与常见拒绝原因

审核维度

常见拒绝原因与解决方案

加速审核的技巧

36.5 SEO 优化：让你的 Skill 被搜索到

高质量 README 结构模板

关键词策略

36.6 版本更新流程

版本更新的最佳实践

自动化发布（GitHub Actions）

36.7 用户反馈处理

反馈处理工作流

本章小结

思考题

💬 留言讨论