召回体检官（skill-recall-doctor）

> 把《技能开发者痛点与 Skill 产品方案报告》中的 S2 落地为可运行 Skill。
> 对应痛点：P2「检索召回失效」——平台检索层退化成"按热度兜底"，长尾技能在检索里等于不存在。
> 服务对象：所有 SkillHub 技能作者（尤其改过 description / 触发词后想验证效果的人）。

一、适用场景与触发条件（when_to_use / 边界）

用本技能当：
- 你怀疑"用户搜某个词找不到我的技能"——想用证据确认，而不是靠猜；
- 你刚改完 description / 触发词 / 类目，想验证"这次改动到底有没有让召回变好"；
- 你想知道"用户搜 XX 会找到我吗、我排第几、被谁挡住了"；
- 你的技能发布后长期零下载，想排查是不是"根本搜不到"这一层的问题。

不用本技能当（边界）：
- 本工具不改平台算法、不承诺排名——它只测、只报告、只给可粘贴的改写稿；
- 归因 B 是启发式（基于语义重叠度），不是平台内部因果，作方向性参考；
- 官方 skillhub search CLI 不返回 downloads / 曝光 / 点击等字段，本工具不臆测这些指标；
- "改写稿再验证"是可选的闭环步骤，需要你重新执行 search；本工具不自动发布。

二、输入参数格式

运行本技能前，智能体（Agent）需先收集并组装一个输入 JSON（字段含义如下）：

> * target 用 slug / publicSlug / name 任一可定位即可，多条齐备更稳。
> queries 建议 8–15 条，覆盖你最在意的用户说法；太少则健康分统计意义弱。

输入取数方式（均为真实可取得的方式，不臆造接口）：
1. 粘贴（推荐、最稳）：Agent 对每条 query 执行
skillhub search "<query>" --search-limit <top_n> --json，把返回 JSON 的 results 字段填入；
2. 自动（可选）：把输入文件交给 scripts/recall_doctor.py --auto，它会调用官方 CLI 自动取数
（路径可用环境变量 SKILLHUB_PY / SKILLHUB_CLI 覆盖，缺省自动探测；探测不到则回退到方式 1）。

三、诊断维度与判定口径、评分标准

分析引擎 scripts/recall_doctor.py 按以下五个维度做确定性计算（不依赖大模型，结果可复现）。

维度 1 · 相关性（Relevance）

• 判定口径：在每条 query 的 TopN 结果里，能否按 slug/publicSlug/name 定位到目标技能。
• 命中 = 找到且 rank < top_n；否则记为 MISS。

维度 2 · 覆盖率（Coverage）

• 指标：recall@N = 命中查询数 / 总查询数（0–1）。
• 含义：用户这些说法里，有几成能找到你。这是健康分的主成分。

维度 3 · 排序质量（Ranking）

• 指标：首位率 = (rank==1 的命中数) / 命中数（0–1，无命中则为 0）。
• 含义：找到你的时候，你是不是排第一。排第一 vs 排第五，点击天差地别。

维度 4 · 冗余重复（Redundancy）

• 判定口径：统计多条 MISS 查询的 Top1 是否高度集中在同一批无关高人气技能上。
• 信号：若 ≥3 条 MISS 的 Top1 是同一个"万能兜底技能"，说明是系统性召回失效，而非你单个词没写好。

维度 5 · Bad Case 归因（Attribution，A/B/C）

对每条 MISS 查询分类（启发式，依据查询意图 bigram 与 Top3 结果 description 的 Jaccard 重叠度）：
- A 类 · 真实同类竞品：Top 结果里存在语义相近的同类技能 → 真竞争，需做差异度改写；
- B 类 · 无关兜底：Top 结果与你意图重叠度极低、属高人气通用技能 → 平台语义召回失效，需靠显式触发词而非语义；
- C 类 · 空结果：该查询返回空 → 需补关键词与标签，提高被索引/召回概率。

健康分与等级（评分标准）

健康分 = round( 100 × (0.7 × recall@N + 0.3 × 首位率) , 1 )

• 权重依据：覆盖率是"能不能被找到"的首要门槛（70%），首位率是"找到后是否优先点你"的增益（30%）。
  详见 references/recall_methodology.md。
• 等级：≥80 健康 ｜ 50–79 亚健康 ｜ 1–49 危险 ｜ 0 失联（全部 MISS）。

四、输出报告模板

Agent 运行脚本后，按以下结构产出最终报告（脚本已生成"召回矩阵 + 健康分 + 改写参考"的 Markdown 骨架，Agent 据此补全改写稿与结论）：

# 召回体检报告 · <技能名>

- 查询数：N ｜ Top<top_n> 召回率：X% ｜ 首位率：Y%
- **健康分：S / 100（等级）**
- 归因分布：A 真实同类=a ｜ B 无关兜底=b ｜ C 空结果=c

## 召回矩阵
| 用户查询 | 排名 | Top 结果 | 归因 | 说明 |
|---|---|---|---|---|
| <query> | <rank 或 MISS> | <top1 名> | <A/B/C/- > | <说明> |
| ... | | | | |

## 诊断结论
- 核心问题：<一句话，如"7/7 查询全部 MISS，且均被无关高人气技能兜底（系统性 B 类失效）">
- 主因：<A 真竞争 / B 平台兜底失效 / C 索引缺失 / 混合>

## 可执行的改写建议（粘贴即用）
- 针对 <失败 query>：新 description 首句改写为「……」，新增触发词「……」（差异点：竞品均未覆盖 <角度>）
- 针对 <失败 query>：……

## 闭环验证（可选）
- 应用改写后，对相同 query 重跑 skillhub search，目标应进入 TopN；若仍 MISS，回到 A/B/C 重判。

完整真实示例（对瑞阳真实技能 skill-monetization-audit 跑通）

输入：target = skill-monetization-audit；queries = 7 条用户原话
（技能该不该收费 / 技能怎么定价 / WorkBuddy 技能变现 / 付费技能怎么卖钱 / 这个技能值多少钱 / 买断还是订阅 / 技能商业化）；top_n = 5。

脚本输出（节选）：

# 召回体检报告 · 技能变现审核
- 查询数：7 ｜ Top5 召回率：0% ｜ 首位率：0%
- **健康分：0.0 / 100（失联）**
- 归因分布：A 真实同类=0 ｜ B 无关兜底=7 ｜ C 空结果=0

## 召回矩阵
| 用户查询 | 排名 | Top 结果 | 归因 | 说明 |
|---|---|---|---|---|
| 技能该不该收费 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| 技能怎么定价 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| WorkBuddy 技能变现 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| 付费技能怎么卖钱 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| 这个技能值多少钱 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| 买断还是订阅 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |
| 技能商业化 | MISS | 编程大神.Skill | B | 被无关高人气技能兜底（平台语义召回失效） |

## 改写参考
- 同类竞品语料条数：0（本例 Top 结果均为无关兜底，无同类竞品语料）
- 查询意图中、竞品均未覆盖的角度（优先写进新 description）：
  付费、定价、变现、商业化、买断、订阅、值多少钱、怎么卖钱……
- 你已说、竞品没说的差异化点（保留并前置）：
  六维加权、准入闸门、一票否决红线、价格锚点、买断/订阅建议……

Agent 据此合成的改写建议（示例）：
> 结论：7/7 全部 MISS 且归因 B —— 不是你单个词没写好，是平台语义召回把"付费/变现"类长尾查询统一兜底给了高人气通用技能。语义层面救不回来，只能靠显式触发词 + description 首句强信号。
> 建议：① 在 description 首句直接写"判断一个技能该不该收费、怎么定价、买断还是订阅"；② triggers 增加 技能该不该收费 / 技能怎么定价 / 买断还是订阅 / 技能值多少钱 等原话；③ 这些词本身就是高重叠度的用户原话，优先前置。应用后重跑相同 7 条 query，目标应至少进入部分 Top5（闭环验证）。

> 该示例为真实运行结果（2026-10-25，官方 skillhub search 取数），证明示例可实际跑通。

五、与其他技能的复用关系

• 与 skill-trigger-tuner 的分工：trigger-tuner 是纯静态的文案层优化（不联网、不验证）；本技能是联网真测。两者必然串联：先 tuner 改稿 → 再 doctor 验证。
• 数据反哺：每次召回结果可沉淀为本地样本，用于刷新 category-supply-demand-radar 的样本库。
• 下游衔接：验证通过的改写稿自动归档，作为 skill-regression-checker 的回归基线（证明"这次改写没把旧召回改坏"）。
• 边界声明：本技能不做"发布前静态包体检"（归 skill-package-check）、不做"已发布后的全面调用率诊断"（归 diagnose-skill-callrate）。

六、边界限制（必读）

1. 只测不编：本工具输出的是基于真实 search 结果的诊断与建议，不伪造任何下载/曝光/排名数据。
2. 字段受限：官方 skillhub search 不返回 downloads / 曝光 / 点击，涉及这些的"提升幅度"无法量化，只做方向性判断。
3. 归因是启发式：B 类靠"语义重叠度过低"判定，可能把"冷门但相关的长尾竞品"也判成 B；遇此情况以人工复核为准。
4. 闭环需手动：改写稿的"再验证"需要你重新执行 search，本工具不会自动发布或自动改写你的 SKILL.md。
5. 零依赖：分析引擎 scripts/recall_doctor.py 为纯 Python 标准库实现，无网络请求、无第三方包；自动取数仅在 --auto 且探测到官方 CLI 时触发。