SkillHub Finder —— 查找并推荐 skillhub 中的 skill
> Goal: 当用户想"找某个能完成某事的 skill"时，根据自然语言意图在 skillhub 中检索，并基于安全评估与用户下载量给出可信的、排序后的推荐列表。
When to Use
当用户表达"想用/找/有什么 skill 来做某事"时触发，例如：
- "有什么 skill 能帮我处理 PDF / 生成 Excel / 做 PPT？"
- "我想定时提醒写日报，用哪个 skill？"
- "有没有能连 GitHub、抓 Figma 设计稿的技能？"
- "帮我找一个发邮件的技能"（涉及安全筛选，本 skill 会标注风险）
When NOT to Use
- 用户已经在用某个具体 skill（如正在调用 pdf 技能处理文件）——此时不要跳出来推荐。
- 用户的请求是直接执行任务而非"找 skill"（如"把这个 PDF 合并"应直接走 pdf 技能）。
- 用户明确指名了某个 skill 并要直接使用（如"用 github-connector 克隆仓库"）。
核心原则
- 安全优先于热度：任何被安全评估为 C 级（高风险）的技能默认不推荐，除非用户显式要求（
--allow-risky）。下载量高不等于安全。 - 意图驱动：先识别用户意图（目标类别 + 动作），再做检索，避免关键词误匹配。
- 三维加权：
相关度 0.5 + 安全 0.3 + 下载量 0.2（详见references/security_rubric.md）。 - 透明可解释：每个推荐都给出安全等级、下载量、分项分数与简介，绝不黑箱。
- 凭据安全：输出中绝不包含 Token / 密钥；仅提示安装前置（如"需 GitHub OAuth 授权"）。
工作方式
用户自然语言
│
▼
1. 意图识别：提取 目标类别(文档/代码/设计/自动化…) + 动作(创建/编辑/搜索/发布…)
│
▼
2. 候选检索：在 catalog 中按 token 重叠（中英文混合）+ 类别命中匹配
│
▼
3. 安全过滤：剔除 C 级（除非 allow-risky）；可按 --min-security 提高门槛
│
▼
4. 三维打分：relevance + security_norm + download_norm(log 缩放)
│
▼
5. 排序输出：Top-K 推荐，附安全等级 / 下载量 / 分项分数 / 安装前置
脚本使用
脚本位置：<skill-directory>/scripts/find_skill.py
目录数据：<skill-directory>/data/catalog.json（可在 references/security_rubric.md 查看评级规则）
基础查询
python3 <skill-directory>/scripts/find_skill.py "我想把几张 PDF 合并并加水印"
python3 <skill-directory>/scripts/find_skill.py "做个每天提醒写日报的定时任务" --top-k 3
从管道读取（多轮对话汇总）
echo "生成一份 Excel 周报并转成 PPT" | python3 <skill-directory>/scripts/find_skill.py -
安全选项
# 包含高风险(C级)技能（仅当用户明确要求时）
python3 <skill-directory>/scripts/find_skill.py "发邮件通知团队" --allow-risky
# 提高安全门槛：只返回 S/A 级
python3 <skill-directory>/scripts/find_skill.py "自动化操作桌面" --min-security A
机器可读输出
python3 <skill-directory>/scripts/find_skill.py "联网调研竞品" --json
接真实 skillhub（可选）
设置环境变量后，脚本优先从实时端点拉取目录，回退本地：
export SKILLHUB_API_URL="https://your-skillhub.example.com/api/skills"
python3 <skill-directory>/scripts/find_skill.py "生成图像"
目录维护（校验 / 拉取 / 合并）见 scripts/update_catalog.py。
参数说明（find_skill.py）
| 参数 | 默认 | 说明 |
|---|---|---|
query |
必填 | 自然语言查询；- 表示读 stdin |
--catalog |
data/catalog.json |
本地目录路径 |
--top-k |
5 |
返回前 K 个推荐 |
--min-security |
无 | 最低安全等级 S/A/B/C |
--allow-risky |
关 | 含 C 级高风险技能 |
--w-relevance/security/download |
0.5/0.3/0.2 | 三维权重 |
--json |
关 | 输出结构化 JSON |
示例
示例 1：文档处理意图
用户："有没有能合并 PDF 并加水印的技能？"
执行：
python3 <skill-directory>/scripts/find_skill.py "合并 PDF 并加水印"
预期：返回 pdf（S 级，相关度高），并展示安全等级与安装提示。
示例 2：涉及安全筛选
用户："帮我找个发邮件的技能"
执行：
python3 <skill-directory>/scripts/find_skill.py "发邮件通知团队"
默认不返回 C 级的 email-sender（高风险、未验证），或仅在 --allow-risky 时返回并明确标注 verified: false 与风险说明。
示例 3：多意图
用户："把内容生成 PPT 并发布成在线应用"
执行：
python3 <skill-directory>/scripts/find_skill.py "生成 PPT 并发布成在线应用"
预期：同时命中 pptx（S）与 发布为应用（B，会提示数据外发风险），按综合分排序。
目录数据维护
data/catalog.json 为种子数据（含安全评级与下载量示例）。接入真实 skillhub：
# 校验本地目录
python3 <skill-directory>/scripts/update_catalog.py --validate
# 从真实 skillhub 拉取并覆盖
SKILLHUB_API_URL="https://your-skillhub.example.com/api/skills" \
python3 <skill-directory>/scripts/update_catalog.py --fetch
# 合并外部增量（本地优先，不覆盖）
python3 <skill-directory>/scripts/update_catalog.py --merge other_catalog.json
每条技能字段见 references/security_rubric.md 第 1 节。
