SkillHub团队报表 · SkillHub Team Report

抓取团队在 SkillHub 上的技能下载数据，沉淀为 JSON 时序，并输出一份按下载次数排序的 HTML 报表。
Scrape your team's SkillHub skill download data into a JSON time-series and render a download-ranked HTML report.

始终使用与用户相同的语言回复（中文环境用简体中文）。

何时使用 / When to use

• 用户想统计团队在 SkillHub 上的技能下载情况、生成每日/定期下载报表。
• 用户给出形如 https://www.skillhub.cn/skills/xxx/xxx 的技能详情页链接，要求批量抓取下载数。
• 用户提到「团队报表」「SkillHub 团队报表」「技能下载统计」「下载次数报表」等关键词。

运行环境与安装引导 / Environment & Setup

跨平台 / Cross-platform：脚本仅依赖 Python 3 标准库，无任何第三方依赖与平台耦合（无 subprocess / 系统命令 / 硬编码路径，路径统一 os.path.join，读写显式 UTF-8），
Windows / macOS / Linux / HarmonyOS 均可运行——唯一前提是环境中存在 Python 3（HarmonyOS 基于 Linux 内核，安装 Python 3 后同样可用；脚本输出文件名不含 Windows 非法字符）。

本 Skill 的抓取脚本基于 Python 3 标准库实现，运行前需确认环境中存在 python3。
触发后、执行抓取命令前，务必先校验 Python 是否可用：

python3 --version || python --version

• 若命令成功输出版本号（如 Python 3.x.x），继续「主流程」步骤 2。
• 若报错 command not found / 不是内部或外部命令，说明未安装 Python 3，请按用户所在系统给出下方对应安装引导，
  并把安装步骤回显给用户，不要直接以「脚本无法运行」结束。

各系统安装引导（缺失时给出 / Install guide per OS）

• macOS：通常已自带 python3。若缺失，二选一：
• 安装 Homebrew 后执行 brew install python
• 或到 https://www.python.org/downloads/macos/ 下载官方安装包
• Windows：
• 推荐用包管理器：winget install Python.Python.3.12（或到 https://www.python.org/downloads/windows/ 下载）
• 务必勾选安装界面的 "Add python.exe to PATH"，否则命令行仍找不到命令
• 安装后重新打开终端，用 python --version 验证（Windows 上命令常叫 python 而非 python3）
• Linux（Debian/Ubuntu）：sudo apt update && sudo apt install -y python3
• Linux（CentOS/RHEL）：sudo yum install -y python3 或 sudo dnf install -y python3

> 说明：脚本本身仅用 Python 标准库、无任何第三方依赖，装好 Python 3 即可直接运行，
> 无需 pip install 任何包。唯一额外前提是运行环境能访问 api.skillhub.cn（抓取 SkillHub 数据所需）。

主流程 / Workflow

步骤 1 · 初始化：收集链接与保存文件夹（必须 / Required）

进入本 Skill 后，先完成两项初始化采集，再开始抓取：

1. 收集 SkillHub 链接：向用户索取至少一个 SkillHub 技能详情页完整链接
   （格式如 https://www.skillhub.cn/skills/xxx/xxx）。提取页面下载数据的唯一依据是页面上的「次下载」文字，
   链接需指向技能详情页（而非列表页），否则抓取不到下载数字。用户可一次提供多个链接，逐个抓取。
   - 采集话术示例：
   > 请提供至少一个 SkillHub 技能详情页的完整链接（形如 https://www.skillhub.cn/skills/xxx/xxx），
   > 可一次给多个，我会逐个统计「次下载」之前的数字。

2. 询问保存文件夹：向用户确认数据保存到哪个本地文件夹。
   - 采集话术示例：
   > 这些统计数据要保存在哪个文件夹下？（例如 /Users/jake/workspace/skill_factory_space/skillhub-data）
   > 我会把 group_skill_statics.json 和 HTML 报告写到这里。
   - 若用户未指定，给出默认建议并请其确认，不要擅自写入系统/个人敏感目录。

两项都拿到后，进入步骤 2。

步骤 2 · 执行抓取并写入 JSON

本 Skill 自带抓取脚本，用 Python 标准库实现（无需安装依赖）。运行前请先按上文「运行环境与安装引导」校验 python3 是否可用，缺失则先引导安装再继续。<skill_dir> 指本 Skill 所在目录
（即 SKILL.md 所在的目录；在 WorkBuddy 中调用方已知该绝对路径，请用真实路径替换）。

运行命令（将链接与文件夹替换为实际值）：

python3 "<skill_dir>/scripts/scrape_skillhub.py" \
  --out-dir "<第1步确认的保存文件夹>" \
  "<URL1>" ["<URL2>" "<URL3>" ...]

脚本对每个 URL 自动完成：

• 抓取页面：用浏览器 UA 请求详情页，兼容 UTF-8 / GBK 解码。
• 解析字段（SkillHub 走 API，其他站点走 HTML / SkillHub uses API, others use HTML）：
• SkillHub 详情页是 JS 渲染的 SPA，静态 HTML 里不含「次下载」文字；脚本优先调用官方 API
  https://api.skillhub.cn/api/v1/skills/<slug>?namespace=<handle>（<slug> = URL 末尾路径段，<handle> = URL 倒数第二段命名空间），
  直接读取 skill.stats.downloads——这正是页面上展示为「次下载」的那个数字。
  注意：/skills/<ns>/<slug> 双段 URL 必须带 namespace 参数请求——同名 slug 可能存在于多个命名空间
  （如团队发布版与 ClawHub 同步版），不带 namespace 会命中错误对象（曾导致 knowledge-card 误抓成
  @clawhub_jackyken 的 647 次，实际 @xh-ai 版为 0）。单段 URL（/skills/<slug>）无 namespace 时维持原行为。
• 非 SkillHub 站点 / API 不可用时，回退为从页面静态 HTML 提取「次下载」之前的数字，
  支持千分位逗号与「万」单位（如 1.2万次下载 → 12000）。
• skillName（技能名）：API 取 skill.displayName；HTML 回退优先 og:title → <title>（去「 - SkillHub」后缀）→ <h1>。
• id（技能 ID）：取 URL 末尾路径段并做 URL 解码（如 .../skills/xh-ai/yyy → yyy）。
• namespace（命名空间）：取 URL 倒数第二段（如 .../skills/xh-ai/yyy → xh-ai），单段 URL 为 null，随记录写入 JSON 便于溯源。
• time（统计时间）：抓取时的本地时间，格式 YYYY-MM-DD HH:MM:SS。
• 写入 JSON：将本批记录追加到 <保存文件夹>/group_skill_statics.json
  （文件不存在则新建；已存在则在原数组后追加，形成每日时序）。该文件为一个 JSON 数组，
  每项结构见下方「数据格式」。

可选参数：

• --reset：覆盖已有 JSON（不从历史追加），用于重新统计。
• --urls-file urls.txt：从文本文件读取 URL（每行一个，# 开头为注释）。
• --json-name：自定义 JSON 文件名（默认 group_skill_statics.json）。
• --report-only：仅基于已有 JSON 重新生成看板与所有单独页，不抓取任何页面（见步骤 4 回退场景）。
• 主看板文件名规则：group_skill_report_{yyyyMMdd}.html，当天重复运行自动覆盖当日文件。

步骤 3 · 生成并交付 HTML 看板（排名 + 7 天走势）

脚本在写 JSON 的同时，自动生成一份自包含、无外部依赖（纯 SVG，可离线打开）的时序看板：

• 主看板 <保存文件夹>/group_skill_report_{yyyyMMdd}.html（按生成日期命名，当天多次运行覆盖同名文件）：
• 顶部卡片：技能数、总下载、统计天数。
• 总下载走势（近 7 天）：折线图，纵轴为每日各技能下载数之和（缺失天前向填充）。
• 技能排名表：按当前下载次数从高到低排序（同一 id 取最新一天的值），技能名可点击跳转单独页。
• 每个技能每日走势对比（标签化切换）：位于同一 section，顶部两个标签：
  • 「下载走势图」：每个技能一张小折线图（点击「查看大图」跳转单独页）。
  • 「周环比对比图」：每个技能一张周环比小折线图——本周每日增量（实线，技能配色）vs 上周同日增量（灰色虚线），可直观对比本周与上周同期的下载动能（数据不足 14 天时上周虚线部分缺失属正常冷启动）。
• 下载日历：位于走势网格下方；周日起始（日/一/二/三/四/五/六），上方可切换年份与月份（默认进入为当年当月），每个日期格显示当天总下载数（全历史聚合，无记录日期显示 —，「今天」金色高亮）。
• 每技能单独页 <保存文件夹>/group_skill_report_<id>.html：
• 每日走势对比（同样标签化切换）：「下载走势图」为近 7 天每日下载大折线图；「周环比对比图」为本周每日增量 vs 上周同日增量大图；下方为每日明细表 + 「返回总看板」链接。

走势口径：所有记录按 id 聚合为「每天一条」——每天取该技能当天 time 最新一条的 downloadCount
（下载数只增不减，取最新即为当日终值）；图表展示最近 7 天窗口，不足 7 天时显示已有天数。

交付：将 group_skill_report_{yyyyMMdd}.html（当天主看板）与对应的 group_skill_report_<id>.html 通过 present_files
打开预览交给用户，并在对话中说明本次技能数、总下载、是否有页面解析失败。

> 想让报表持续更新？可建一个每 2 小时的 recurring 自动化，固定调用本 Skill 脚本对上述链接
> 追加抓取（不 --reset），看板会随真实天数累积出 7 天走势。见末尾「自动出报」。

步骤 4 · 失败回退（页面为 JS 动态渲染时 / Fallback）

若某 URL 返回 downloadCount: null（脚本会打印 [WARN] 并标注「页面可能为 JS 动态渲染」），
用 WebFetch 作为回退抓取该页面：

• 提示词示例：
  > 请提取这个 SkillHub 技能页面的：技能名、技能 ID、以及「次下载」前面的下载次数数字。
  > 按 skillName=... / id=... / downloadCount=... 返回。

拿到数值后，直接编辑 group_skill_statics.json 把对应记录的 downloadCount 补上（或新增一条记录），
再运行以下命令仅重新生成报告（不重复抓取）：

python3 "<skill_dir>/scripts/scrape_skillhub.py" \
  --out-dir "<保存文件夹>" --report-only

数据格式 / Data schema

group_skill_statics.json 内容为一个 JSON 数组，每项结构如下：

[
  {
    "skillName": "技能名",
    "id": "技能ID",
    "namespace": "命名空间（可选，双段 URL 才有）",
    "downloadCount": 1234,
    "time": "2026-08-20 15:37:35"
  }
]

• skillName：技能名 / skill name
• id：技能 ID（取自 URL 末尾路径段）/ skill id from URL
• namespace：命名空间（取自 URL 倒数第二段，单段 URL 为 null，v1.1+ 写入）/ namespace from URL (null for single-segment URLs, written since v1.1)
• downloadCount：下载次数（整数；抓取失败时为 null）/ download count (int; null on failure)
• time：本次统计的本地时间 / local time of this statistic

资源清单 / Resources

自动出报 / Scheduled reporting

为获得「近 7 天走势」，需要多次运行让数据跨天累积。推荐建一个 recurring 自动化，每 2 小时运行一次：

• 调度：scheduleType=recurring，rrule=FREQ=HOURLY;INTERVAL=2（每 2 小时；当天多次运行会刷新当天记录，跨天后自然形成每日序列）。
• 任务提示词（自包含，需写明链接与输出目录）：
  > 使用 skillhub-team-report Skill 的脚本，对以下团队 SkillHub 链接执行一次抓取与看板更新（追加模式，不要 --reset）：
  > <把 10 个链接贴在此处>
  > 输出目录固定为 <保存文件夹>。脚本路径：<skill_dir>/scripts/scrape_skillhub.py。
  > 命令示例：python3 <skill_dir>/scripts/scrape_skillhub.py --out-dir <保存文件夹> <URL1> ... <URL10>
  > 完成后简要回报本次新增/更新的记录数与看板路径。