SkillHub技能管理
概述
管理 SkillHub 技能广场（skillhub.cn）中的技能，覆盖三类核心任务：
1. 技能清单提取：从 SkillHub API 获取用户发布的全部技能及下载量
2. 安装状态梳理：对比线上技能与本地安装情况，识别已安装/未安装
3. 每日统计更新：更新 Excel 统计表，记录每日下载量与趋势分析
SkillHub API
端点
GET https://api.skillhub.cn/api/v1/users/{userId}/skills?page=1&pageSize=50
{userId}：SkillHub 用户 ID（如user_60120345），从记忆/日志中查找或询问用户- 返回 JSON，顶层字段：
total、totalDownloads、totalStars、skills（数组） - 每个技能字段：
slug、name、description、description_zh、downloads、stars、version、category、createdAt、updatedAt、iconUrl、labels、namespace、source
调用示例
import urllib.request, json
url = 'https://api.skillhub.cn/api/v1/users/{userId}/skills?page=1&pageSize=50'
req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
resp = urllib.request.urlopen(req, timeout=30)
data = json.loads(resp.read().decode('utf-8'))
# data['skills'] → 技能列表
# data['totalDownloads'] → 总下载量
本地数据源
| 数据源 | 路径 | 用途 |
|---|---|---|
| 技能元数据 | ~/.local/share/TeleAgent/skills-metadata.json |
本地已安装技能元信息（source、serverId、skillAuthorType、reviewStatus 等） |
| 技能安装目录 | ~/.config/TeleAgent/skills/ |
实际安装的技能文件夹，目录名即技能名 |
| SkillHub统计表 | 工作空间/每日统计/skillhub-stats.xlsx | 历史每日下载量统计（含趋势分析 sheet） |
⚠️ 关键陷阱：SkillHub slug 与本地目录名不一致
SkillHub API 返回的 slug 与本地技能目录名（~/.config/TeleAgent/skills/ 下的文件夹名）经常不一致。直接按 slug 精确匹配会大量误判"未安装"。
常见差异模式：
- 发布版加后缀：diagram-builder-pro → 本地 diagram-builder
- 发布版加版本后缀：report-generator-plus2 → 本地 report-generator
- 发布版缩短名称：xiao-pei → 本地 xiao-pei-quiz
- 完全不同命名：baoyu-skill-fuzhu → 本地 baoyu-skills-wrapper
详细映射表见 references/slug-mapping.md。每次新增技能时需同步更新该映射表。
匹配策略
- 先按 slug 精确匹配
skills-metadata.json的 key - 对未匹配的，检查本地
skills/目录中是否有前缀匹配的技能 - 参考
skills-metadata.json中description_cn字段做语义匹配 - 仍无法匹配的标记为"未安装"
工作流程
场景一：技能清单 + 安装梳理
- 确定 SkillHub 用户 ID（从记忆/日志查找或询问用户）
- 调用 API 获取技能列表
- 读取
skills-metadata.json和skills/目录 - 按匹配策略做 slug → 本地目录名映射
- 输出对比表格：slug、名称、下载量、Stars、版本、安装状态、本地目录名
场景二：每日统计更新
- 调用 API 获取最新下载量
- 读取现有
skillhub-stats.xlsx - 在"SkillHub每日统计" sheet 新增一列（当日日期），按 slug 匹配填入下载量
- 更新合计行公式：
=SUM(X2:Xn) - 重建"趋势分析" sheet：按总下载量降序，含排名/日均增速/近3日增量
- 全公式化，数据源引用明细 sheet，不硬编码数值
- 如有新增 skill（API 返回的 slug 在统计表中不存在），需新增行并补充历史数据
场景三：技能清单导出
- 调用 API 获取技能列表
- 按下载量降序排列
- 输出 Markdown 表格或 Excel 文件
- 可选：补充分类（category）、创建时间、版本等信息
输出规范
- 对话输出：Markdown 表格，按下载量降序
- Excel 统计表：双 sheet（每日统计 + 趋势分析），全公式化，双层嵌套表头，支持超链接
- 汇总报告：含技能总数、总下载量、总 Stars、已安装/未安装统计
验证要点
- API 返回的
total应等于skills数组长度 - 对比结果中"未安装"的技能需人工确认（可能因 slug 映射遗漏）
- 每日统计更新后检查公式无
#REF!或#VALUE!错误 - 新增 skill 时确认 slug 在统计表中无重复行
