| name | search-pi-extensions |
| description | 按需求从 npm pi-package 生态检索符合的 Pi Agent 扩展/技能/主题/prompt 包，采集 npm 元数据与 GitHub 信号，质量评估后整理成表格。与 pi-trending 互补（后者做热度发现）。 |
| disable-model-invocation | true |
Search Pi Extensions
按用户需求从 npm pi-package 生态中检索符合的 Pi Agent 包（extension / skill / theme / prompt），采集 npm 元数据与 GitHub 信号，经质量评估后整理成 Markdown 表格 + 风险提示。
与 pi-trending 互补：pi-trending 回答「生态里火什么」（热度发现），本技能做需求驱动检索（「我要找做 X 的包」）。
工作流程
手动触发（disable-model-invocation: true）：键入技能名加载后，LLM 主导 grilling、质量评估与整理，脚本只负责检索与数据采集。
阶段 ① Grilling 澄清需求 + 生成关键词（LLM）
用户通常给模糊需求（如「找个能读 PDF 的 pi 扩展」）。LLM 先简短提问澄清：
- 具体用途：要解决什么问题、预期行为
- 类型偏好：extension / skill / theme / prompt，或不限
- 约束：是否需要 GitHub 仓库、是否接受实验性/低下载包
澄清后生成 2-5 个英文搜索关键词，覆盖目标包在 name / description / keywords 中可能出现的用词（如 pdf document reader）。关键词是 npm 全文检索词，不必精确，脚本会取相关度 Top 窗口。每个关键词作为独立位置参数传入脚本；多词短语应拆成多个单词关键词，避免 shell 引号转义问题。
阶段 ② 检索 + 采集（脚本）
uv run --script scripts/search_pi_extensions.py <kw1> <kw2> ... [--max-candidates N]
脚本一次完成检索与采集：
- 对每个关键词调 npm search API（
text=keywords:pi-package <kw>），取相关度 Top 250 窗口，合并去重
- 硬过滤：无 repository 或 月下载 < 10（统计分原因计数）
- 按 命中关键词数 / 最高 searchScore / 月下载 初排，截断到
--max-candidates（默认 50）
- 并发
gh api 取 GitHub 信号（stars / pushed_at / open_issues）；失败或非 GitHub repo 保留候选，github 置 null
- stdout 输出 JSON，诊断与警告写 stderr
⚠️ npm 检索特性：附加全文词不缩小 total，仅改变排序（见 query_stats.npm_total，通常仍是全量 5304）。脚本只取相关度 Top 窗口，是排序检索而非严格筛选，语义相关度需 LLM 在阶段 ③ 判断。
阶段 ③ 质量评估（LLM）
读 JSON，结合字段综合判断相关度与质量，过滤低质或不相关包：
- 相关度：
literal_keywords（字面命中）> matched_keywords（进入窗口）> description 语义
- 使用量：
downloads.monthly（近 30 天）
- 社区活跃：
github.stars / github.pushed_at / open_issues（github=null 的包无法评估，降权或标注）
- 类型匹配：
types 是否符合用户偏好
- npm 信誉：
dependents（被依赖数）、npm_score
脚本已硬过滤无 repository / 月下载 < 10 的包，LLM 在此基础上做语义相关度与质量判断。告知用户被过滤的数量（含硬过滤 + LLM 评估过滤）。
阶段 ④ 整理表格 + 风险提示（LLM）
按相关度排序（不打分），输出 Markdown 表格：
| # | 包名 | 类型 | 一句话说明 | 安装命令 |
|---|------|------|-----------|----------|
| 1 | `pi-mcp-adapter` | extension | MCP 协议适配器 | bunx pi extension install pi-mcp-adapter |
- 一句话说明：根据
description 翻译为中文并精简到 ≤20 字
- 类型：取
types（多类型包用 / 连接，如 extension/skill；package 表示无明确类型 keyword）
- 安装命令：按类型生成（见下方「安装命令」）
- 可选附月下载量列
末尾风险提示（按实际情况取舍）：
- 已过滤 N 个低质包（无 repository 或 月下载 < 10）+ M 个不相关包
- npm 检索为排序检索，
npm_total 远大于返回数，可能漏掉未命中关键词但语义相关的包
github=null 的包无法评估社区活跃度- pi 生态很新（所有包近 6 个月内发布），质量参差，建议优先选有 repo、有 star、近期 push 的包
- 数据时效：下载量为近 30 天，GitHub 信号为查询时刻
安装命令
按 types 生成（参考 pi-trending）：
| 类型 | 安装命令 |
|---|
| extension | bunx pi extension install <name> |
| skill | bunx skills add <name> |
| theme | bunx pi theme install <name> |
| prompt | bunx pi prompt install <name> |
| package（无类型） | 提示用户查看包说明确认类型后再安装 |
多类型包展示主要类型的命令。<name> 含 @scope/ 前缀时原样保留。
CLI 参考
uv run --script scripts/search_pi_extensions.py <kw>... [选项]
| 选项 | 作用 | 默认 |
|---|
keywords（位置参数） | 搜索关键词，至少一个；重复词按大小写不敏感去重 | - |
--max-candidates N | GitHub 请求前截断的候选数上限 | 50 |
--max-results-per-keyword N | 每关键词采相关度窗口上限 | 250 |
--verbose | 采集进度、分页、统计输出到 stderr | 关 |
stdout 仅输出 JSON（可管道给 jq），诊断与警告写 stderr。
JSON 字段说明（供阶段 ③ 质量评估）
顶层：
| 字段 | 说明 |
|---|
keywords | 去重后的查询关键词 |
query_stats | 每关键词 {npm_total, retrieved_unique} |
found_unique | 合并去重后的候选总数 |
quality_filtered | 硬过滤掉的数量 |
filter_reasons | {no_repository, low_downloads} 分原因计数 |
eligible_before_limit | 硬过滤后、截断前的候选数 |
returned | 实际返回的包数（截断后） |
truncated | 是否因 --max-candidates 截断 |
github_stats | {success, failed, skipped} GitHub 信号采集统计 |
packages | 候选包数组 |
每个 package：
| 字段 | 说明 |
|---|
name | npm 包名（含 scope） |
description | npm 描述（英文原文） |
types | 类型数组（extension/skill/theme/prompt，无类型为 ["package"]） |
keywords | npm keywords |
matched_keywords | 该包进入了哪些关键词的相关度窗口（排序信号） |
literal_keywords | 查询词字面出现在 name/description/keywords（相关度信号） |
version / date | 最新版本与发布时间 |
downloads | {monthly, weekly} 下载量 |
dependents | 被依赖数 |
npm_score | npm 综合评分 |
search_scores | 各关键词的 searchScore |
repository | 仓库 URL |
github | {stars, pushed_at, open_issues}，失败/非 GitHub 为 null |
脚本位置
scripts/search_pi_extensions.py - 基于 uv 的 PEP 723 单文件脚本，零依赖（仅标准库 + gh CLI）。
前置条件：gh CLI 已认证（用于 GitHub 信号）。未认证时限流 60 req/hour，可能批量失败。检查：gh auth status。
