GitHub Explorer

用自然语言发现并分析 GitHub 上的优质开源项目。帮用户解决两个痛点：不知道去哪找、看不懂项目是干什么的。

⚠️ 数据外发提醒：搜索关键词、仓库名会发送至 GitHub API（api.github.com）。GitHub 可能不会返回私密仓库信息。

⚠️ 限额提醒：未配置 Token 时 GitHub Search API 每分钟仅 10 次请求；设置 GITHUB_TOKEN 环境变量可提升到 30 次/分钟。超过会提示限流。

⚠️ 缓存持久化：搜索结果和仓库分析会缓存到 ~/.cache/github-explorer/（1 小时有效期），加速重复查询。加 --no-cache 跳过缓存。

核心能力

Triggers

用户明确表达想找 GitHub 项目或了解某个仓库时触发：

• "找一下做 [领域] 的开源项目" / "有什么好的 [领域] 项目"
• "GitHub 上 [领域] 有哪些优质仓库"
• "帮我看看 [owner/repo] 这个项目" / "[项目名] 是干什么的"
• "新兴的 [领域] 项目有哪些" → 用 trending 模式

不要触发：用户只是聊技术话题、提到公司名但不涉及找项目。

💡 自助查参数：脚本自带 --help（如 search --help、analyze --help），用户也可以直接跑 help / cache status / cache clear 查看或管理缓存。对于复杂的筛选需求，AI 可以直接拼接参数执行。

行为规则

1. 找项目（search）

用户说 "找 LLM 推理加速的项目" / "有什么好的向量数据库"：

python3 scripts/github_explorer.py search "<领域关键词>" [--mode classic|trending] [--lang python] [--topic <主题>] [--limit 10] [--stars >1000] [--created-after 2024-01-01] [--created-before 2024-06-01] [--license mit] [--sort stars|forks|updated] [--no-cache]

💡 中文自动翻译：脚本内置中英技术关键词映射表，用户直接说中文也能搜。如 "大模型 推理加速" 自动翻译为 "large language model inference acceleration"。不在映射表中的中文词会原样保留传给 GitHub（部分场景仍能匹配）。

• classic（默认）：经典优质，按 star 排序 + 近 6 个月有更新
• trending（启发式）：新兴热门，按 star 排序 + 近 1 年创建。注意：GitHub 无"涨最快"原生排序，这是"近期创建且已积累高 star"的近似，并非真实增速排名

返回后格式化为排行列表（用用户的语言输出）：

🔍 [领域] 相关优质项目 (共找到 N 个，显示前 10)

1. owner/repo ⭐ 52.3k
   📝 一句话描述
   🏷️ 语言 · 主题标签
   🔗 https://github.com/owner/repo

2. ...

引导："要我深入分析其中哪个项目吗？或者换个关键词/模式再搜？"

2. 析项目（analyze）

用户说 "帮我看看 langchain-ai/langchain" / "这个仓库是干啥的"：

python3 scripts/github_explorer.py analyze <owner/repo> [--readme-full] [--no-cache]

💡 桥接规则：如果用户只给了项目名（如"看看 langchain"）而没有 owner/repo，先跑一次 search 找到精确仓库，再对搜到的 full_name 调 analyze。不要凭猜测拼 owner/repo。

💡 README 长度：默认截断 8000 字符给 LLM 分析，避免溢出上下文。加 --readme-full 获取完整 README。

脚本返回结构化 JSON（stars/forks/语言/license/topics/README）。

你（LLM）负责分析，输出结构化解读（用用户的语言）：

📦 owner/repo
⭐ 52.3k · 🍴 8.1k · 🏷️ Python · MIT

一句话定位：
  [用大白话说明这是什么]

核心特点：
  · [特点1]
  · [特点2]
  · [特点3]

能为你做什么：
  · [结合用户语境，说明实际用途]
  · [适用场景]

上手难度：⭐⭐☆☆☆（[简单/中等/偏难]）

分析要点：

• 从 README + description 提炼"是什么"，避免堆术语
• "能为你做什么"要结合用户刚才提到的需求/领域
• 如果 README 很长，抓核心能力和典型用例

配置（可选）

export GITHUB_TOKEN="ghp_你的token"

不配置也能用（限流更严格）。Token 在 GitHub → Settings → Developer settings → Personal access tokens 生成，只需 public_repo 只读权限。

命令参考

search <query> [--mode classic|trending] [--lang <语言>] [--topic <主题>] [--limit N] [--stars <过滤>] [--created-after <日期>] [--created-before <日期>] [--license <类型>] [--sort stars|forks|updated] [--no-cache]
analyze <owner/repo> [--readme-full] [--no-cache]
cache [status|clear]
help

cache 子命令：

错误处理