ClawHub Publisher

自动化ClawHub技能发布流程，确保版本一致性和代码质量。

核心理念

"先检查后发布，智能整合，避免覆盖"

发布前必须：

检查ClawHub/GitHub现有版本
对比实现思路和代码差异
智能整合重要变更
更新版本号后发布

工作流程

完整发布流程（推荐）

# 1. 检查现有版本
bash scripts/check-existing.sh <skill-name>

# 2. 对比差异（如果存在）
bash scripts/compare-versions.sh <skill-name>

# 3. 智能整合（如果有差异）
# 手动审查并合并重要变更

# 4. 发布/更新
bash scripts/publish.sh <skill-name> <version>

快速发布（新技能）

# 跳过检查，直接发布（仅适用于新技能）
bash scripts/publish.sh <skill-name> 1.0.0

更新现有技能

# 1. 检查+对比+下载
bash scripts/update.sh <skill-name>

# 2. 手动整合差异
# 3. 更新版本号后发布
bash scripts/publish.sh <skill-name> x.y.z

脚本说明

1. check-existing.sh - 检查现有版本

功能：

检查ClawHub是否存在该技能
检查GitHub仓库是否存在该技能
返回版本信息和所有者

用法：

bash scripts/check-existing.sh <skill-name>

输出示例：

ClawHub: 已存在
  - 版本: 3.4.0
  - 所有者: zhaog100
  - Package ID: k97d4m6m5hpwd33g64j2g12zxs82ezj1

GitHub: 未找到

退出码：

0：不存在（可以发布）
1：存在且所有者是当前用户（需要更新）
2：存在但所有者不是当前用户（需要换slug或放弃）

2. compare-versions.sh - 对比版本差异

功能：

下载ClawHub最新版本到临时目录
对比本地版本和远程版本
生成差异报告（文件、行数、功能）

用法：

bash scripts/compare-versions.sh <skill-name>

输出示例：

=== 版本对比报告 ===
本地版本: 3.5.0
远程版本: 3.4.0

=== 文件差异 ===
+ scripts/new-feature.sh (新增)
~ SKILL.md (+45 -12)
~ scripts/main.sh (+120 -80)

=== 功能差异 ===
+ 新增功能A
- 移除功能B
~ 优化功能C

=== 建议 ===
需要整合：远程版本有重要的bug修复

3. publish.sh - 发布技能

功能：

验证技能结构（SKILL.md必需）
检查版本号格式
自动添加acceptLicenseTerms
上传到ClawHub

用法：

bash scripts/publish.sh <skill-path> <version>

示例：

# 发布新技能
bash scripts/publish.sh ./skills/my-skill 1.0.0

# 更新现有技能
bash scripts/publish.sh ./skills/my-skill 2.1.0

注意事项：

需要修改 /usr/lib/node_modules/clawhub/dist/cli/commands/publish.js 添加 acceptLicenseTerms: true
详细步骤见 references/clawhub-api.md

4. update.sh - 更新技能

功能：

一键检查+对比+下载
自动合并简单差异
标记复杂冲突

用法：

bash scripts/update.sh <skill-name>

版本管理规范

版本号格式

MAJOR.MINOR.PATCH

MAJOR：重大更新（不兼容的API变更）
MINOR：功能更新（向后兼容）
PATCH：Bug修复（向后兼容）

更新规则

首次发布：1.0.0
功能更新：x.y.0 → x.(y+1).0
Bug修复：x.y.z → x.y.(z+1)
重大更新：x.0.0 → (x+1).0.0

命名规范

官方技能：<功能名>（如：github、weather）
个人定制：miliger-<功能名>（如：miliger-playwright-scraper）

整合策略

优先级判断

远程优先：远程版本有重要bug修复或安全更新
本地优先：本地版本有新功能或重大改进
合并：两者都有重要更新，需要智能合并

整合步骤

下载远程版本：clawhub install <slug>
对比差异：bash scripts/compare-versions.sh <slug>
审查变更：手动审查每个差异文件
合并重要变更：保留重要的bug修复和新功能
更新版本号：根据变更类型更新版本
测试验证：测试整合后的功能
发布更新：bash scripts/publish.sh <path> <version>

常见场景处理

场景1：发布新技能

# 1. 检查是否存在
bash scripts/check-existing.sh my-skill
# 输出：不存在

# 2. 直接发布
bash scripts/publish.sh ./skills/my-skill 1.0.0

场景2：更新自己的技能

# 1. 检查现有版本
bash scripts/check-existing.sh my-skill
# 输出：存在，所有者是zhaog100

# 2. 对比差异
bash scripts/compare-versions.sh my-skill

# 3. 整合变更
# （手动审查并合并）

# 4. 发布更新
bash scripts/publish.sh ./skills/my-skill 2.0.0

场景3：发现同名技能（非自己）

# 1. 检查现有版本
bash scripts/check-existing.sh my-skill
# 输出：存在，所有者不是zhaog100

# 2. 选择方案
# 方案A：使用不同slug
bash scripts/publish.sh ./skills/my-skill 1.0.0 --slug miliger-my-skill

# 方案B：放弃发布（避免重复）
echo "已存在同名技能，放弃发布"

参考文档

references/clawhub-api.md - ClawHub CLI详细使用指南
references/git-workflow.md - Git协作工作流程
references/best-practices.md - 技能发布最佳实践

注意事项

发布前必检查：避免覆盖他人工作
版本号规范：遵循语义化版本规范
测试验证：发布前务必测试
文档更新：重要变更需更新CHANGELOG
备份本地：整合前备份本地版本

故障排除

问题1：acceptLicenseTerms错误

原因：ClawHub CLI v0.7.0 缺少此字段

解决：修改 publish.js 添加 acceptLicenseTerms: true

详细步骤见 references/clawhub-api.md

问题2：文件过多导致发布失败

原因：包含venv、node_modules等大目录

解决：创建 .clawhubignore 文件

venv/
node_modules/
__pycache__/
*.log
logs/

问题3：版本冲突无法合并

原因：远程和本地都有重大变更

解决：

手动审查每个冲突文件
保留重要功能
测试整合后的版本
发布为新的MAJOR版本

示例：完整发布流程

# 场景：发布 session-memory-enhanced v4.0.1

# 1. 检查现有版本
cd /root/.openclaw/workspace/skills/clawhub-publisher
bash scripts/check-existing.sh session-memory-enhanced
# 输出：存在，所有者zhaog100，版本4.0.0

# 2. 对比差异
bash scripts/compare-versions.sh session-memory-enhanced
# 输出：本地有新功能（+3个文件），远程无更新

# 3. 发布更新
bash scripts/publish.sh ../session-memory-enhanced 4.0.1
# 输出：发布成功，Package ID: k97carwxs0htme5y071ye69ykx82mmwg

# 4. 验证
clawhub inspect session-memory-enhanced
# 输出：版本4.0.1，已发布

clawhub-publisher

Safety Notice

Copy this and send it to your AI assistant to learn