Skill管家 - ClawHub + SkillHub 双源全生命周期管理

三个问题，一个skill全答（选/装/管全链路同时检索 ClawHub + SkillHub 双源）：
1. 装什么？ → 搜索/对比/场景匹配，帮你选对
2. 能不能装？ → 深度分析/坑点雷达/快速判定，帮你避坑
3. 装的还好吗？ → 体检/组合审计/替代推荐，帮你管着

触发场景

选（装之前）：
- "帮我找个处理PDF的skill" → 搜索选型
- "pdf和pdf-processor哪个好" → 功能对比
- "我要从QQ邮箱发邮件，用哪个skill" → 场景匹配
- "办公自动化有什么好skill推荐" → 搜索选型
- "选skill"、"skill推荐"、"skill对比"、"哪个skill好"

装（决策时）：
- "xxx这个skill靠谱吗" → 快速判定
- "详细分析一下xxx" → 深度分析
- "给我出个完整报告" → 选型报告

管（装之后）：
- "我装的skill都还健康吗"、"体检"、"检查已装skill"、"筛查" → 已装体检
- "有没有更好的替代"、"我装的xxx是不是过时了" → 已装体检
- "我装的skill有没有重复的"、"清理一下"、"组合审计" → 组合审计
- "哪些skill该卸载"、"skill太多了" → 组合审计
- "按类别分组"、"飞书类有哪些"、"分下类"、"归类看看" → 组合审计（自动按类别分组展示）
- "可视化展示"、"出个网页版"、"图形化"、"好看的报告"、"仪表盘"、"HTML报告" → 可视化报告（必须生成HTML文件并展示给用户，见下方⚡章节）

⚡ 可视化报告（用户要"可视化/网页版/好看的"时，照这个做）

只要用户话里带"可视化、网页版、图形化、仪表盘、HTML、好看的报告"这类意思，就要生成可视化报告。 跑 --html 时脚本会同时产出两样东西，对应两种交付场景：

• HTML文件（写入磁盘，stderr 打印绝对路径）→ 给能打开本地文件的用户
• 文字版摘要（stdout 直接输出）→ 给打不开本地文件的用户（云端/手机聊天）兜底

第一步 · 选对脚本跑 --html

# 体检/筛查/健康检查 → 体检仪表盘（按严重程度排序，谁该换一目了然）
python scripts/health_check.py --html=health_report.html

# 审计/重复/清理/组合优化 → 审计仪表盘（重叠检测+整合建议+健康率）
python scripts/portfolio.py --html=audit_report.html

拿不准选哪个时：用户说"筛查/体检/健康"用 health_check；说"重复/清理/审计"用 portfolio；想看全景就用 portfolio（它含每个skill的健康度，更全面）。

第二步 · 看用户环境，选交付方式（关键，别跳过）

• 用户能打开本地文件（桌面端、本地 agent）→ 把生成的 .html 文件呈现给用户（文件卡片/链接），说"浏览器打开即可查看，也可以分享给同事"。
• 用户打不开本地文件（云端/手机聊天、用户明说打不开、或你只能给路径递不到文件）→ 直接把 stdout 里那段文字版摘要发给用户，这就是兜底交付物；末尾补一句"完整仪表盘已生成在 <路径>，方便的话下载后用浏览器打开"。

❌ 两种情况都不要只甩一个文件路径了事——要么给文件，要么给文字摘要，用户必须能直接看到内容。

第一阶段：选

搜索选型（用户给出需求/关键词）

python scripts/report.py "关键词" --limit 8 --deep 5

输出完整Markdown报告（推荐结论+评分+对比+坑点+安装命令）。默认同时检索 ClawHub + SkillHub 双源，结果去重合并、每条标注来源；想只搜某一个源加 --source clawhub 或 --source skillhub（默认 both）。

功能对比（2-N个候选横评）

python -c "
import json,sys; sys.path.insert(0,'scripts')
import clawhub_api, capability_extractor as ce
details = [clawhub_api.get_skill_detail(s) for s in ['slug1','slug2','slug3']]
caps = [ce.extract_capabilities(d) for d in details]
comp = ce.compare_capabilities(caps)
print(ce.format_capability_comparison(comp))
"

输出：操作能力✅/❌矩阵 + 集成覆盖对比 + 各skill独有能力。

重点告诉用户：A能做X而B不能，而不是只比下载量。

场景精确匹配（"我要从QQ邮箱发邮件"）

python -c "
import json,sys; sys.path.insert(0,'scripts')
import clawhub_api, capability_extractor as ce
results = clawhub_api.search('email', 8)
for r in results:
    d = clawhub_api.get_skill_detail(r['slug'])
    caps = ce.extract_capabilities(d)
    match = ce.match_use_case(caps, '从QQ邮箱发邮件')
    if match['matched']:
        print(f\"✅ {caps['name']}: {match['score']}% | {match['matched_features']}\")
    else:
        print(f\"❌ {caps['name']}: {match['score']}% | 缺:{match['missing']}\")
"

告诉用户：只有X和Y支持你的具体需求，Z不支持。

第二阶段：装

快速判定（"xxx靠谱吗"，3行结论）

python scripts/quick_verdict.py "slug"

输出：判定+趋势+能力+风险+安装命令。不写完整报告。

深度分析（评分+坑点+能力全量）

python scripts/clawhub_api.py detail "slug" | python scripts/scorer.py --json
python scripts/clawhub_api.py detail "slug" | python scripts/pitfall_radar.py --json
python scripts/clawhub_api.py detail "slug" | python scripts/capability_extractor.py

完整选型报告

python scripts/report.py "关键词" --limit 10 --deep 5 -o report.md

第三阶段：管

已装体检（逐个健康检查）

python scripts/health_check.py --verbose

自动扫描 ~/.openclaw/skills/ 所有已装skill，逐个查 ClawHub + SkillHub 双源（先 ClawHub，未命中再 SkillHub）：
- 评分+趋势（是否停更/衰退）
- 版本检查（本地 vs 远程最新版）
- 坑点扫描（高风险预警）
- 替代搜索（有没有更强的同类skill）

输出按严重程度排序：🔄建议换 > 👀留意 > ⬆️可更新 > ✅健康 > ❓未收录

重点告诉用户：哪个该换、哪个该更新、哪个还能用。

想要可视化？加 --html=health_report.html 生成体检仪表盘（详见⚡章节）。

组合审计（整体优化）

python scripts/portfolio.py --verbose

对已装skill组合做全局分析：
- 重叠检测：哪两个skill功能重叠>50%，建议保留哪个
- 风险汇总：几个要付费API、几个停更、几个低分
- 整合建议：按优先级给出"卸载X保留Y"的具体建议
- 组合统计：平均分、最强/最弱、总下载量
- 类别分组：自动按"飞书类/AI生成类/数据分析类/开发运维类/办公文档类/工具类"分组展示，一眼看清装的都是啥

重点告诉用户：你装了3个PDF skill，留一个就够；那个180天没更新的该换了。

想要可视化？加 --html=audit_report.html 生成审计仪表盘（评分圆环/重叠条形图/行动卡片/类别分组，详见⚡章节）。

增量扫描：体检和审计默认都是增量——按 skill 本地指纹（SKILL.md修改时间+版本）缓存结果，只重扫"新增/改动过"的 skill，日常体检从几十秒缩到1秒内。想强制全量重扫加 --full。

自定义目录（测试用）：python scripts/health_check.py /path/to/skills --json

脚本清单

评分维度（5维/100分制）

• 活跃度 20%：最后更新距今天数
• 成熟度 30%：下载量60%+版本迭代15%+转化率25%
• 社区认可 20%：Stars60%+评论10%+比率30%
• 文档质量 15%：长度/代码块/标题/配置说明
• 依赖简洁 15%：API Key/OAuth/付费/外部服务

趋势判断标准

• 🔥 hot: 日均>500下载 + 30天内更新
• 📈 rising: 日均>100下载 + 60天内更新
• ➡️ stable: 日均10-100下载
• 📉 declining: 日均<10下载 或 >180天未更新

注意事项

• ClawHub / SkillHub API 均无需认证，无 rate limit
• 双源去重：同一 slug 同时出现在两个源时优先取 ClawHub（有 SKILL.md 全文，文档质量评分和功能提取更准）；SkillHub 独有的 skill 也会被纳入，覆盖更广
• SkillHub 限制：详情接口只返回 summary，没有 SKILL.md 全文，故文档质量评分(15%权重)用 summary 兜底，可能略偏低；SkillHub 还聚合了 ClawHub 的 skill 并附带腾讯安全报告(keen/sanbu)
• 搜索是语义搜索（向量），中英文结果不同，建议各搜一次
• 同名slug用explore API按downloads±5%匹配补全数据
• 缓存在cache/目录，搜索1h/详情24h（SkillHub 缓存 key 带 sh: 前缀，与 ClawHub 互不冲突）
• 所有脚本纯标准库，无需pip install
• Windows管道调用需stdin/stdout/stderr三端UTF-8包装

Pitfalls

• 歧义slug（同名多owner）：detail API返回409，用explore匹配补全
• 409响应体在HTTPError里，必须e.read()获取
• 纯slug路径（非@owner/slug），后者404
• Windows多模块TextIOWrapper冲突：只在__main__包装
• "format"等词在邮件/文本上下文不是危险操作，正则要精确
• 评论API不公开，坑点雷达靠文档分析+统计信号
• detail响应latestVersion在顶层（非skill内部）

Verification

# 选
python scripts/report.py "email" --limit 5 --deep 3
python scripts/report.py "calendar" --limit 5 --deep 3 --source skillhub   # 仅 SkillHub
python scripts/clawhub_api.py detail "pdf" | python scripts/capability_extractor.py
python scripts/skillhub_api.py detail "calendar"                            # SkillHub 详情(归一化)
# 装
python scripts/quick_verdict.py "gog"
# 管
python scripts/health_check.py --verbose
python scripts/portfolio.py --verbose
# 管·可视化
python scripts/health_check.py --html=health_report.html
python scripts/portfolio.py --html=audit_report.html
# 管·增量/全量（默认增量复用缓存，--full 强制全量重扫）
python scripts/portfolio.py --full