github-repo-search

name	github-repo-search
description	帮助用户搜索和筛选 GitHub 开源项目，输出结构化推荐报告。当用户说"帮我找开源项目"、"搜一下GitHub上有什么"、"找找XX方向的仓库"、"开源项目推荐"、"github搜索"、"/github-search"时触发。

GitHub 开源项目搜索助手

用途

从用户自然语言需求出发，经过需求挖掘、检索词拆解、GitHub 检索、过滤分类、深度解读，最终产出结构化推荐结果。

目标不是"给很多链接"，而是"给用户可理解、可比较、可决策、可直接行动的候选仓库列表"。

适用范围（V1.1）

• 数据源：GitHub 公开仓库。
• 默认不授权（不使用用户 Token）。
• 默认硬过滤：stars >= 100、archived=false、is:public。
• 默认输出：单榜单（Top N），榜单内按"仓库归属类型"标注。
• 本流程默认不包含安装与落地实施（除非用户单独提出）。

配额说明（必须知晓）

• 未授权 Core API：60 次/小时。
• Search API：10 次/分钟（独立于 Core 额度）。
• 需要在报告中注明检索时间与配额状态，避免结果不可复现。

工作流程

环节一：需求收敛（必须完成，不可跳过）

硬性门控：环节一是整个流程的前置条件。无论用户的需求描述多么清晰，都必须走完本环节并获得用户明确确认后，才能进入环节二。禁止根据用户的初始描述直接推断需求并开始检索。即使用户说"直接搜就行"，也要先输出需求摘要让用户确认。

第一步：需求挖掘与对齐

目标：把"我想看看 XX"转成可执行、可排序、可解释的检索目标。

需确认信息（最少）：

1. 主题（如：agent 记忆、RAG、浏览器自动化）
2. 数量（Top 10 / Top 20）
3. 最低 stars（默认 100）
4. 排序模式（必须二选一）：相关性优先 / 星标优先（默认：相关性优先）
5. 目标形态（必须二选一或多选）： 可直接使用的产品 / 可二次开发的框架 / 资料清单/方法论

建议补充信息（可选）：

1. 偏好技术栈（Python/TS/Go 等）
2. 使用场景（学习、生产、对标）
3. 排除项（教程仓库、归档仓库、纯论文复现等）
4. 部署偏好（本地优先/云端优先/混合）

阶段输出（固定格式）：

核心诉求：
- 主题：xxx
- 数量：Top N
- 最低 stars：>= 100
- 排序模式：相关性优先 / 星标优先（默认：相关性优先）
- 目标形态：xxx
- 偏好：xxx（可空）
- 排除：xxx（可空）

向用户确认以上信息。用户明确确认后才能进入环节二，否则停在这里继续对齐。

---

环节二：检索执行（以下环节由模型自主执行，无需用户介入，直到环节四交付报告）

第二步：检索词拆解（5-10 组）

目标：平衡"召回率"和"相关性"，避免只靠单词硬搜导致偏题。

拆词规则（按优先级排序）：

第一优先级 - 项目名直接匹配（必须完成，不可跳过）：

⚠️ 强制执行规则（违反会导致精确匹配项目被遗漏）：

在调用任何其他搜索之前，必须先完成以下步骤，并等待结果返回后，才能进入第二优先级。禁止并行执行其他搜索。

必须执行的搜索（按顺序）：

⚠️ 重要提示：按名称匹配时必须使用 GitHub API，不要 WebSearch。WebSearch 不支持 in:name 语法，会遗漏精确匹配的项目（如 jamiepine/voicebox）。

【第一优先级】直接使用 GitHub API（必须执行）

Query-1-API:

curl -s "https://api.github.com/search/repositories?q={主题}+in:name&sort=stars&order=desc&per_page=30" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Total found: {data.get(\"total_count\", 0)}')
for repo in data.get('items', []):
    print(f\"{repo['full_name']}: {repo['stargazers_count']}⭐\")
    print(f\"  描述: {repo.get('description', 'N/A')}\")
    print(f\"  链接: {repo['html_url']}\")
"

目的：直接调用 GitHub API 按仓库名称精确匹配（in:name），最可靠的方式，可发现所有名称匹配的项目

Query-1-API-增强（可选，用于过滤）：

curl -s "https://api.github.com/search/repositories?q={主题}+in:name+stars:>100&sort=stars&order=desc&per_page=30"

目的：按名称匹配 + 最低 stars 过滤

GitHub API 搜索语法参考：

• in:name - 仅在仓库名称中搜索
• in:description - 在描述中搜索
• in:readme - 在 README 中搜索
• stars:>100 - stars 大于 100
• language:python - 指定编程语言
• archived:false - 排除归档仓库

补充策略（可选执行）：

1. 直接 URL 构造尝试：
   • 尝试访问 https://github.com/{主题} —— 检查是否存在与主题同名的仓库
   • 示例：主题"voicebox" → https://github.com/voicebox（不存在）→ 但 https://github.com/jamiepine/voicebox 存在

如果用户提供了具体仓库路径（如 owner/repo）：

• 直接访问 https://github.com/{owner}/{repo}
• 将该仓库作为第一结果输出

硬性检查点（模型自检）：

• 是否已使用 GitHub API 执行 in:name 精确匹配搜索？（必须首先完成）
• API 返回的结果中是否包含 xxx/{主题} 格式的仓库？
• 是否已将名称完全匹配的项目优先记录到候选池顶部？

⚠️ 常见错误（必须避免）：

• ❌ 使用 WebSearch 进行名称精确匹配（WebSearch 不支持 in:name 语法，会遗漏如 jamiepine/voicebox 这样的项目）
• ❌ 并行执行主题搜索和同义词搜索（必须先完成名称匹配）
• ❌ 看到 API 结果不相关就放弃，未检查所有返回项目
• ❌ 错误使用 in:name 等 GitHub 专用语法在 WebSearch 中

项目名匹配优先输出规则：

• 如果仓库名与主题完全匹配（如主题"voicebox"匹配到 jamiepine/voicebox），则必须优先输出到结果列表顶部
• 完全匹配的项目不受 stars 门槛限制（即使 stars < 100 也应列出，但需标注）
• 其他流程（过滤、排序、分类）保持不变

第二优先级 - 关键词组合： 4. 核心词：用户目标词 5. 同义词：替代表达（如 long-term memory / stateful memory） 6. 场景词：coding、mcp、tool、platform、awesome、curated 7. 技术词：agent、sdk、framework、database、os 8. 排除思路：不在 query 里硬写过多负例，放到后续过滤阶段

产出格式（必须按顺序执行）：

=== 第一优先级：项目名直接匹配（必须完成）===

【必须执行】直接使用 GitHub API：
Query-1-API: 
curl -s "https://api.github.com/search/repositories?q={主题}+in:name&sort=stars&order=desc&per_page=30" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'Total found: {data.get(\"total_count\", 0)}')
for repo in data.get('items', []):
    print(f\"{repo['full_name']}: {repo['stargazers_count']}⭐\")
    print(f\"  描述: {repo.get('description', 'N/A')}\")
    print(f\"  链接: {repo['html_url']}\")
"
目的：直接调用 GitHub API 按仓库名称精确匹配（in:name），最可靠的方式

【可选】带过滤条件的 API 查询：
Query-1-API-增强: curl -s "https://api.github.com/search/repositories?q={主题}+in:name+stars:>100&sort=stars&order=desc&per_page=30"
目的：按名称匹配 + 最低 stars 过滤

=== 检查点 ===
[ ] 是否已使用 GitHub API 执行 in:name 精确匹配？（必须首先完成）
[ ] API 返回的结果数量和质量是否满足需求？
[ ] 结果中是否出现 xxx/{主题} 格式的仓库？
[ ] 是否已将名称完全匹配的项目优先记录到候选池顶部？

=== 第二优先级：关键词组合（确认以上完成后执行）===
Query-2: "xxx"
目的：高召回核心主题

Query-3: "xxx"
目的：补同义词盲区

重要：

1. 必须首先使用 GitHub API 执行 in:name 精确匹配，这是发现精确匹配项目的唯一可靠方式
2. 禁止在名称匹配阶段使用 WebSearch 替代 GitHub API
3. 禁止一次性并行执行所有搜索

第三步：执行检索与候选召回

执行原则：

1. 第一优先级使用 GitHub API 进行名称匹配（必须首先完成）：

   • 使用 curl 调用 GitHub Search API 进行 in:name 精确匹配
   • 命令示例：curl -s "https://api.github.com/search/repositories?q={主题}+in:name&sort=stars&order=desc&per_page=50"
   • 解析 JSON 响应，提取仓库信息

2. 第二优先级使用 WebSearch 进行关键词组合搜索（名称匹配完成后执行）：

   • 每组 WebSearch query 都执行检索（建议每组 30-50 条）
   • 仔细分析搜索结果中的仓库链接，提取 owner/repo 格式

3. 合并结果形成候选池。

4. 按 owner/repo 去重。

5. 记录检索时间与 API 额度信息。

API 响应处理最佳实践（仅用于名称匹配）：

# 基础查询
curl -s "https://api.github.com/search/repositories?q={主题}+in:name&sort=stars&order=desc&per_page=50"

# 格式化输出（使用 Python）
curl -s "https://api.github.com/search/repositories?q={主题}+in:name&sort=stars&order=desc&per_page=20" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"Total found: {data.get('total_count', 0)}\")
for repo in data.get('items', []):
    print(f\"{repo['full_name']}: {repo['stargazers_count']}⭐\")
    print(f\"  Desc: {repo.get('description', 'N/A')[:80]}...\")
    print(f\"  Lang: {repo.get('language', 'N/A')} | Updated: {repo['updated_at'][:10]}\")
    print(f\"  URL: {repo['html_url']}\")
    print()
"

# 带过滤条件的查询
curl -s "https://api.github.com/search/repositories?q={主题}+in:name+stars:>100+archived:false&sort=stars&order=desc&per_page=20"

候选池字段（最少）：

1. owner/repo
2. stars
3. description
4. repo_url
5. archived
6. language
7. updated_at
8. topics
9. license

第四步：去重与硬过滤

硬过滤（默认）：

1. stars >= 100
2. archived = false
3. is:public

可选硬过滤（按需）：

1. fork = false
2. 指定语言：language:xxx
3. 更新时效：最近 6-12 个月

---

环节三：质量精炼

第五步：噪音剔除与相关性重排

目标：解决"命中 memory 但其实不是 agent memory"的噪音问题。

噪音剔除规则（示例）：

1. 与主题无关的通用工程仓库（即使 stars 很高）
2. 关键词误命中仓库（仅描述中偶然出现 memory/agent）
3. 无实质内容或异常仓库

排序原则（V1.1）：

star 不再作为主排序，只作为召回门槛之一。 建议综合排序权重：

1. 需求相关性：35%
2. 场景适用性：30%
3. 活跃度（更新时效）：15%
4. 工程成熟度（文档/示例/可维护）：15%
5. stars：5%

第六步：仓库归属类型分类（必须）

目标：让用户一眼看懂"这个仓库到底是什么角色"，避免把框架、应用、目录混为一谈。

推荐类型字典：

1. 通用框架层
2. 应用产品层（可直接使用）
3. 记忆层/上下文基础设施
4. MCP 服务层
5. 目录清单层（awesome/curated）
6. 垂直场景方案层
7. 方法论/研究层

第七步：深读与项目介绍撰写（必须）

目标：不是"仓库简介复述"，而是输出"对用户有决策价值"的详细介绍。

深读最低要求：

每个入选仓库至少查看：

1. README 核心定位段
2. 快速开始/功能章节标题
3. 近期维护信号（更新时间、Issue/PR 活跃）

项目介绍写作要求（固定）：

"项目介绍"必须包含两部分并写细：

1. 这是什么：它在系统架构中的角色和边界
2. 为什么推荐：它在用户当前目标下的价值（不是泛泛优点）

可补充：

1. 典型适用场景（1-2 条）
2. 限制或不适用场景（1 条）

---

环节四：交付与迭代

第八步：单榜生成与报告交付（最终）

交付结构（固定）：

1. 需求摘要
2. 检索词清单（5-10 组 + 目的）
3. 筛选与重排规则（明确写出）
4. 结果总览（原始召回/去重后/过滤后）
5. Top N 单榜（表格）
6. 结论与下一步建议

Top N 表格字段（固定）：

仓库	星标	仓库归属类型	项目介绍（是什么 + 推荐理由）	其它信息补充	链接

"其它信息补充"建议内容：

• 语言 / License / 最近更新时间
• 上手复杂度（低/中/高）
• 风险提示（若有）

第九步：用户确认与迭代（可选）

迭代触发条件：

用户反馈"太泛/太窄/不够准/解释不够细"。

迭代动作：

1. 调整检索词（增加场景词或同义词）
2. 调整 stars 门槛（100 -> 200/500）
3. 增加限定（语言/方向/更新时间）
4. 调整类型权重（例如优先应用层或优先框架层）

---

默认参数（V1.1）

1. 最低 stars：100
2. 默认输出：Top 10
3. 默认过滤：archived=false
4. 默认必须分类：是
5. 默认项目介绍粒度：详细（至少"是什么 + 为什么推荐"）

质量检查清单（交付前自检）

1. 是否优先执行了项目名直接匹配（第一优先级不可跳过）
2. 是否完成需求对齐并明确"目标形态"
3. 是否有 5-10 组 query 且每组有目的
4. 是否记录了检索时间与配额状态
5. 是否执行了去重、硬过滤和噪音剔除
6. 是否完成仓库归属类型分类
7. 是否每个推荐都有详细项目介绍（不是一句话）
8. 是否使用固定表格字段交付
9. 是否避免把安装实施混入本流程