实时抓取 GitHub Trending + Search,发现 AI / 开发者工具的早期创业机会。 纯网页抓取,无 API、无 Token、无 mock 数据。
- Live public first:所有数据来自 github.com/trending + github.com/search 的实时网页抓取
- 无 API:不使用 GitHub REST API / GraphQL,不依赖任何 Token
- 无 Mock:所有数据都是真实的,缓存只是加速,不替代
git clone https://github.com/YOUR_USER/github-opportunity-radar
cd github-opportunity-radar
pip install -r requirements.txt
python app.py web
# 浏览器访问 http://127.0.0.1:7860详细入门请见 docs/quickstart.md 示例命令请见 docs/examples.md
# 最小扫描
python app.py scan
# 自定义关键词、范围
python app.py scan --keywords "ollama,mcp,comfyui,gradio" --target 15 --min-stars 300
# 详细扫描(推荐)
python app.py scan --keywords "ollama,mcp,comfyui,gradio,ai agent,local llm,ai video,workflow automation" --target 15 --min-stars 300输出包含:
- Scanned repos / Scored repos / Issues fetched
- 数据质量分布 (high/medium/low)
- 决策分布 (strong_candidate / niche_candidate 等)
- LLM success/failed
- Top 5 排名表(分数、数据质量、决策、推荐、MVP)
- Ranking Diagnostics 标记(service_first / plugin_first 等)
- CSV/JSON/MD 三种报告
LLM 默认不启用,不会影响核心扫描和评分。
| Provider | 连接方式 | JSON Schema | 需要 Key | 典型场景 |
|---|---|---|---|---|
ollama |
/api/chat + /v1/chat/completions |
❌ | 否 | 本地方案 |
openai_compatible |
/chat/completions |
✅ (可选) | 是 | OpenAI / Groq / DeepSeek 等 |
litellm_proxy |
/chat/completions (lite mode) |
✅ (可选) | 是 | LiteLLM 代理服务器 |
# 启用 Ollama(本地)
python app.py scan --enable-llm --llm-provider ollama --llm-model llama3.2
# 启用 OpenAI 兼容(API Key 从参数传入)
python app.py scan --enable-llm --llm-provider openai_compatible \
--llm-base-url https://api.openai.com/v1 --llm-model gpt-4o-mini \
--llm-api-key sk-xxx
# 或从环境变量读取 API Key(安全,不泄露到终端历史)
# set LLM_API_KEY=sk-xxx (PowerShell)
# export LLM_API_KEY=sk-xxx (bash)
python app.py scan --enable-llm --llm-provider openai_compatible \
--llm-base-url https://api.openai.com/v1 --llm-model gpt-4o-mini
# 高级参数
python app.py scan --enable-llm --llm-provider ollama \
--llm-timeout 300 --llm-max-repos 5 --llm-use-json-schema \
--llm-force-json-mode --llm-no-cache
# 关闭 LLM(纯规则分析)
python app.py scan# 测试 Ollama
python app.py llm-test --llm-provider ollama
# 测试 OpenAI 兼容
python app.py llm-test --llm-provider openai_compatible \
--llm-base-url https://api.openai.com/v1 --llm-model gpt-4o-mini \
--llm-api-key sk-xxx
# 带 JSON Schema 测试
python app.py llm-test --llm-provider ollama --llm-use-json-schema- 不要将 API Key 写入脚本或配置文件。使用环境变量
LLM_API_KEY或 CLI 参数传入。 - 系统不会打印、记录或导出 API Key。
- 环境变量优先级:CLI 参数 > 环境变量。
LLM 不可用时自动降级为 rule-based scan,不会中断主流程:
LLM status: unavailable / fallback to rule-based
扫描结果状态包括:
completed_with_llm_errors— 扫描完成但部分 LLM 分析失败completed— 全部正常
新参数控制:
--llm-continue-on-error(默认 true):LLM 失败时继续扫描其余仓库--llm-no-cache:禁用 LLM 结果缓存(默认根据readme_hash + issue_titles_hash + model + prompt_version + schema_version缓存)
| 维度 | 满分 | 数据来源 | 说明 |
|---|---|---|---|
| Hot Score | 25 | Trending ★/wk + stars | 真实周增长 + Stars 边际递减 |
| Issue Score | 25 | Issues 页面直接抓取 | Issue 数量 + 评论 + 标签 |
| Early Score | 20 | README 分析 | alpha/beta/experimental/roadmap/v0.x |
| Commercial Gap | 20 | README 分析 | 无 pricing/enterprise/sales 信号越多分越高 |
| MVP Feasibility | 10 | Issue 分类 | 安装/UI/文档类痛点易产品化 |
数据质量评分(0-100)独立于机会评分,用于评估抓取数据的可靠性:
| 分数区间 | 标签 | 含义 |
|---|---|---|
| 75-100 | high | 基础信息完整、README 可读、Issue 数据充足 |
| 45-74 | medium | 部分信息缺失或 Issue 数量不足 |
| 0-44 | low | 严重缺失,结果不可靠 |
5 个组成部分:
- 基础信息 (20pt):full_name、description、stars、language 是否齐全
- README (20pt):是否成功抓取完整 README
- Issue 数据 (30pt):抓到的 Issue 数量和丰富度
- Issue 分类 (15pt):Issue 是否覆盖多个痛点分类
- LLM 分析 (15pt):LLM 是否成功分析(可选)
重要:不要只看 opportunity_score。如果 data_quality_score < 45,排名可能不可靠。
决策(opportunity_verdict)是对机会的定性判断:
| 决策 | 含义 |
|---|---|
| strong_candidate | ⭐ 机会评分高且数据质量高,值得重点研究 |
| niche_candidate | 🔍 有机会但方向较窄,需要进一步验证 |
| service_opportunity | 🛠 安装/文档/新手痛点集中,适合做服务而非产品 |
| plugin_opportunity | 🔌 工作流/API 集成需求集中,适合做插件或 MCP |
| weak_candidate | ⚠ 暂不值得做,需求不够明确 |
| avoid | ❌ 已有成熟商业方案或数据质量过低 |
最终建议(final_recommendation)是规则引擎独立生成的行动建议,不需要 LLM:
| 建议 | 触发条件 |
|---|---|
| build_prototype_now | strong_candidate + DQ >= 75 + issue_score >= 15 |
| research_manually_first | niche_candidate 或 DQ < 60 |
| good_for_service_business | service_opportunity |
| good_for_plugin_business | plugin_opportunity |
| add_to_watchlist | weak_candidate 或高热度低需求 |
| skip | avoid 或 DQ < 40 + 弱候选 |
判定逻辑严格基于规则,LLM 不可用时 final_recommendation 仍然正常生成。
排名诊断(ranking_flags)标记每个 repo 的潜在问题:
| 标记 | 含义 |
|---|---|
| score_may_be_unreliable | 高分低数据质量 |
| commercial_risk | 高分但商业化信号强 |
| weak_issue_evidence | Issue 少但分数高 |
| hype_without_pain | 热度高但 Issue 需求弱 |
| niche_but_painful | 痛点明确但热度低 |
| service_first | 安装/文档类痛点占比高 |
| plugin_first | 工作流/API 类痛点占比高 |
Watchlist 支持 7 天连续观察:
- 加入 Watchlist:在 WebUI 中输入 "owner/repo" → 点击"加入 Watchlist"
- 自动记录:每次扫描自动更新 stars、issues、分数变化
- 手动复盘:填写 hypothesis、target_user_guess、monetization_guess
- Needs Review:当 star 增长快 / 分数大幅变动时自动标记
- 导出报告:
python app.py scan后,WebUI 中点击"导出 Watchlist 报告"
| 字段 | 说明 |
|---|---|
| user_hypothesis | 我认为这个机会是什么 |
| target_user_guess | 目标用户是谁 |
| monetization_guess | 可能怎么收钱 |
| validation_next_step | 下一步验证动作 |
| validation_result | 验证结果记录 |
- stars_delta_since_last_scan > 100
- issues_delta_since_last_scan > 5
- opportunity_score 比上次增加 >= 10
- data_quality_score 从 low/medium 变成 high
- final_recommendation 从 watchlist/research 变成 build_prototype_now
opportunity_score 是综合热度、需求、早期度、商业空白和可行性的分数,但它有局限性:
- 数据质量低时分数不可靠:如果 data_quality_score < 50,分数不能反映真实情况
- 高热度 ≠ 真实需求:hot_score 高但 issue_score 低的项目可能只是围观
- 商业化信号不一定是坏事:commercial_gap 扣分但说明项目已经验证了商业模式
- 痛点分布决定产品形态:安装部署痛点适合做服务,工作流痛点适合做插件
建议:始终结合 verdict + final_recommendation + ranking_flags 综合判断。
python app.py daily-scan作用:
- 只扫描 Watchlist 中的 repo
- 更新 stars / open issues / README / scores
- 自动计算 deltas 和 needs_review
触发 needs_review 条件:
- star 增长 >= 100
- issues 增长 >= 5
- opportunity_score 增长 >= 10
- recommendation 变化
- 新增 issue 中出现 pricing / enterprise / self-host / deploy / api / integration / windows / cuda / oom / plugin / mcp / workflow 关键词
python app.py daily-report生成 outputs/daily_watchlist_report.md,包含:
- Summary(repo 总数、更新数、需要 review 数、最大 star 增长、最大 issue 增长)
- Needs Review(每个需要 review 的 repo 的详细 delta)
- No Major Change(无明显变化的 repo)
# 基础版本
python app.py validation-pack --repo owner/name
# 带 LLM 增强
python app.py validation-pack --repo owner/name --enable-llm --llm-provider ollama生成 outputs/validation_packs/owner__name/,包含 7 个文件:
- opportunity_brief.md — 机会摘要、目标用户、痛点证据、最小验证方式
- landing_page_copy.md — 标题、副标题、3 个痛点、3 个卖点、CTA、FAQ
- mvp_scope.md — MVP 做什么/不做什么、7 天计划、技术栈建议
- issue_reply_drafts.md — 针对代表性 issues 的回复草稿(不自动发送)
- user_interview_questions.md — 10 个用户访谈问题
- 7_day_validation_plan.md — Day 1-7 验证计划 + 成功标准
- launch_post_drafts.md — GitHub Discussion / Reddit / HN / X / 小红书发布草稿
- 所有草稿都标记为
DRAFT - 不自动评论 GitHub issue
- 不自动发 Reddit / HN / X
- 不泄露 API key 到任何报告
# Day 1: 扫描并加入 Watchlist
python app.py scan --keywords "ollama,mcp,comfyui" --target 15
python app.py web # 打开 WebUI,候选 repo 加入 Watchlist,填写复盘字段
# Day 2-7: 每日扫描和报告
python app.py daily-scan
python app.py daily-report
# 在 WebUI 中查看变化
python app.py web
# 为有潜力的 repo 生成验证包
python app.py validation-pack --repo owner/name- 有真实 issue:至少 5+ 条相关 issue,不是自嗨
- 有重复痛点:多条 issue 提到同一个问题
- 有增长:star / issue 在增加(Watchlist 自动追踪)
- 7 天可做 demo:MVP 范围足够小(见 mvp_scope.md)
- 能找到明确目标用户:issue 作者就是潜在用户
- 有可能收费:痛点够痛,用户愿意付费解决
可能的原因和解决:
- 频率限制:扫描频率控制在 2s/次,如果持续失败,增大
--delay参数 - 页面结构变化:GitHub 偶尔更新 HTML 结构,检查
scraper.py的选择器是否需要更新 - 网络问题:确保能访问 github.com,部分网络环境需要代理
LLM 默认不启用。如果 --enable-llm 但 Ollama 不可用:
- 系统会自动降级为 rule-based 分析
- 扫描结果不受影响,只是没有 LLM 增强内容
- 输出明确显示
LLM status: unavailable / fallback to rule-based
使用 llm-test 诊断:
python app.py llm-test --llm-provider ollama
# Connection: ok → Ollama 正在运行
# Connection: error → 先运行 ollama serve
# Model 'qwen2.5:14b' not pulled yet → 先运行 ollama pull qwen2.5:14b如果模型未下载,可以先手动拉取或使用 Preload 功能:
ollama pull qwen2.5:14b
# 或在 WebUI 中点击「预加载 Ollama 模型」V0.2.2 新增预加载机制(client.preload()),可在扫描前预热模型减少冷启动延迟。
超时从 120s 提升到 300s,有足够时间等待模型首次加载。
- Trending 页面只显示 25 个项目,过滤关键词后可能只剩几个
- Search 也有频率限制,快速多次搜索可能被拦截
- 系统会组合 trending (daily/weekly/monthly/language) + search fallback 尽量凑够数量
PowerShell 控制台对 UTF-8 中文的显示可能不正确,输出类似:
Rec: �ʺ�������/�̳�
但文件内容是正确的 UTF-8。请用以下方式确认:
cat outputs/latest_report.csv(输出到文件显示正确)- 在 VS Code 中打开 CSV/JSON/MD 文件
- 浏览器打开 WebUI 页面(中文正常)
建议将 PowerShell 编码设为 UTF-8:
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()- Trending 页面显示的 "X stars this week" 是 GitHub 估算值
- 部分 repo 没有 delta 数据,显示为 N/A
- 跨语言、跨周期的 trending 来源使用对应字段 (1d/7d/30d)
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ github.com/ │ │ github.com/ │ │ raw │
│ trending │ │ search │ │ content │
│ (★/wk 增量) │ │ (关键词搜索) │ │ (README) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────┐
│ HTTP 文件缓存 + SQLite 数据库 (8 表) │
│ scan_runs / repos / repo_snapshots │
│ star_history / issues / scores / llm_analyses │
│ watchlist │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 评分引擎 (5 维度, 满分 100) │
│ Hot(25) + Issue(25) + Early(20) │
│ + CommercialGap(20) + MVPFeasibility(10) │
│ + data_quality_score(100) + ranking_flags │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 决策引擎 (6 级 verdict + final_recommendation)│
│ strong_candidate / niche_candidate / │
│ service_opportunity / plugin_opportunity / │
│ weak_candidate / avoid │
└─────────────────────┬───────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ MVP 推荐引擎 (规则驱动, 无 LLM) │
│ 安装器 / 插件 / WebUI / SaaS │
└─────────┬───────────────────────────┬───────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ LLM 增强分析 │ │ 导出 CSV/JSON/MD│
│ (可选, 不覆盖规则)│ │ + Watchlist 报告 │
└────────┬─────────┘ └──────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ Gradio Web UI │
│ 扫描 + 排行榜 + 详情 + Watchlist + 复盘字段 │
└──────────────────────────────────────────────┘
github-opportunity-radar/
├── app.py # CLI 入口 (scan / export / web)
├── Run.bat # Windows 启动器
├── requirements.txt # 依赖
├── src/
│ ├── scraper.py # HTTP 抓取 + 重试 + 缓存 + 限速
│ ├── trending_scraper.py # github.com/trending (daily/weekly/monthly/language)
│ ├── github_search_scraper.py # github.com/search
│ ├── repo_page_scraper.py # 仓库详情 + README + /issues 直接抓取
│ ├── repo_search.py # 搜索编排 (trending + search fallback)
│ ├── readme_analyzer.py # README 信号检测
│ ├── issue_classifier.py # Issue 8 维度分类
│ ├── scorer.py # 5 维度评分 + data_quality_score + verdict + final_recommendation
│ ├── ranking_diagnostics.py # 排名诊断 (7 种标记 + 行动建议)
│ ├── mvp_recommender.py # 规则引擎 MVP 推荐
│ ├── database.py # SQLite 8 表 (含 watchlist)
│ ├── report.py # CSV/JSON/MD 导出 + Watchlist 报告
│ ├── daily_watchlist.py # 每日 Watchlist 扫描 (v0.3)
│ ├── daily_report.py # 每日 Watchlist 报告 (v0.3)
│ ├── validation_pack.py # 创业验证包生成器 (v0.3)
│ ├── webui.py # Gradio 中文界面
│ ├── config.py # 配置项
│ └── llm/ # LLM 增强分析层
│ ├── base.py # LLMConfig + LLMClient 抽象 + chat_json()
│ ├── provider_router.py # 客户端工厂 (v0.2.2 新增)
│ ├── ollama_client.py # Ollama (预加载 + 3 层 fallback + 300s 超时)
│ ├── openai_compatible_client.py # JSON Schema → JSON Mode → Text fallback
│ ├── litellm_proxy_client.py # LiteLLM 代理客户端
│ ├── prompts.py # 中文/英文提示词模板 + 测试提示词
│ ├── schemas.py # LLM 输出 pydantic 模型
│ ├── json_repair.py # JSON 提取/修复/校验
│ └── analyzer.py # LLM 分析编排器 (provider_router + 缓存 + status_detail)
├── data/
│ └── radar.sqlite # SQLite 数据库
├── cache/ # HTTP 响应缓存
└── outputs/ # CSV/JSON/MD 导出
suggested_next_action 是 ranking_diagnostics 根据 ranking_flags 组合生成的具体行动建议:
| 触发条件 | 建议 |
|---|---|
| 热度虚高 + 分数不可靠 | 先不要做产品,手动验证 Issue 是否真实代表付费需求 |
| 商业化风险 | 存在成熟竞品,建议做差异化定位 |
| 服务优先 + 插件优先 | 痛点混合,建议先发布服务/教程,再考虑产品化 |
| 服务优先 | 考虑做部署服务、教程模板、咨询,而非 SaaS 产品 |
| 插件优先 | 考虑做插件、MCP Server、Chrome 扩展、n8n 节点 |
| 小而痛 | 适合小团队深耕细分领域,不要急于扩展 |
| Issue 证据不足 | Issue 数据不足,建议手动调研 Reddit/Discord 确认需求 |
top_pain_cluster 是 Issue 分类中数量最多的痛点类别。通过痛点聚类,可以快速知道用户最需要什么:
| 聚类 | 含义 | 变现路径 |
|---|---|---|
| install_deploy | 安装部署痛点 | 适合做一键安装器、Docker 模板、Windows 启动器或付费部署服务 |
| performance_gpu | 显存/性能痛点 | 适合做显存配置推荐器、量化工具、云 GPU 启动器 |
| workflow_integration | 工作流断点 | 适合做 API 连接器、MCP Server、Chrome 扩展、n8n 节点 |
| newbie_docs | 新手不会用 | 适合做中文教程包、WebUI 封装、模板市场或付费部署文档 |
| feature_request | 功能请求 | 适合做功能投票平台、插件市场或定制开发服务 |
| enterprise_team | 企业/团队需求 | 适合做私有化部署脚手架、SSO 集成、权限管理 |
| compatibility_upgrade | 兼容性/迁移问题 | 适合做迁移工具、兼容层或升级辅助工具 |
| mobile_ui | 移动端/前端UI机会 | 适合做移动端 WebApp、PWA 封装或移动端监控面板 |
top_pain_cluster_name 是中文名称,top_pain_cluster_count 是对应的 Issue 数量。
needs_review 和 review_reason 是 Watchlist 的自动提醒机制。当以下情况发生时,Watchlist 项会被自动标记为需要人工复盘:
stars_delta_since_last_scan > 100— 快速增长,需要确认原因issues_delta_since_last_scan > 5— 需求爆发,需要检查新 Issue 类型opportunity_score比上次增加 >= 10 — 评分大幅提升data_quality_score从 low/medium 变成 high — 数据质量改善final_recommendation从 watchlist/research 变成 build_prototype_now — 机会升级
在 WebUI Watchlist 表格中,"需Review"列会显示 ⚠ 标记。导出 Watchlist 报告时,标记项会额外显示提醒。
Watchlist 的设计目标是 7 天连续观察同一批候选项目:
# Day 1:首次扫描
python app.py scan --keywords "ollama,mcp,comfyui,gradio" --target 15 --min-stars 300
# Day 1 后续:打开 WebUI,把候选 repo 加入 Watchlist
python app.py web
# 在 WebUI 中输入 "owner/repo" → 点击"加入 Watchlist"
# 手动填写复盘字段(user_hypothesis / target_user_guess / monetization_guess / validation_next_step)
# Day 2-7:每天重新扫描
python app.py scan --keywords "ollama,mcp,comfyui,gradio" --target 15 --min-stars 300
# 每次扫描后,打开 WebUI → 加载 Watchlist
# 查看:
# - stars_delta_since_last_scan(本周新增 Stars)
# - stars_delta_since_first_seen(累计增量)
# - needs_review(是否需要手动复盘)
# - 分数变化
# - 决策/建议变化
# 填写验证结果
# 在 WebUI 中更新 validation_result 字段
# Day 7:导出 Watchlist 报告
# 在 WebUI 中点击"导出 Watchlist 报告"
# 输出文件:outputs/watchlist_YYYYMMDD_HHMMSS.md报告包含:每个 repo 的机会评分、数据质量、决策、建议、累计增长、复盘字段内容、Needs Review 状态。
python app.py smoke-testsmoke-test 执行 7 项代码健康检查:
- 所有核心模块 import
- 数据库初始化 + 8 表检查
- 评分引擎对最小 repo dict 评分
- ranking_diagnostics 返回 flags
- 报告导出器生成临时 CSV/JSON/MD
- Watchlist DB 函数(add/load/remove)
- scores 表 watchlist 表新增列检查
不需要网络,不修改扫描数据。输出 "Smoke test passed." 表示全部正常。
编辑 src/config.py 可调整:
| 参数 | 默认值 | 说明 |
|---|---|---|
request_delay_seconds |
2.0 | 请求间隔,防止限流 |
cache_max_age_hours |
6 | HTTP 缓存有效期 |
default_target_count |
15 | 默认扫描仓库数 |
default_min_stars |
100 | 最小 Stars |
enable_raw_readme_fetch |
True | 从 raw.githubusercontent 获取 README |
enable_github_search_fallback |
True | Trending 不足时用 search 补充 |
llm_provider |
"none" | LLM 提供商 |
llm_model |
"qwen2.5:14b" | LLM 模型 |
llm_timeout |
300 | LLM 请求超时(秒) |
llm_cache_enabled |
True | 是否启用 LLM 结果缓存 |
llm_use_json_schema |
False | JSON Schema 严格模式 |
llm_force_json_mode |
False | 强制 json_object 模式 |
llm_preload_model |
False | 扫描前预加载 Ollama 模型 |
- 抓取延迟:每次请求间隔 2s,完整扫描约 1-3 分钟
- Rate Limit:GitHub 对无认证请求有限制(约 60 req/hr),缓存有效期内不会重复请求
- LLM 独立性:LLM 失败不会影响核心评分和 recommendation;所有 final_recommendation 由规则独立生成
- 分数 ≠ 决策:不要只看 opportunity_score,结合 verdict + final_recommendation + ranking_flags 综合判断
- 7 天观察:用 Watchlist 持续扫描同一批 repo,观察 stars 和分数变化
- Watchlist 导出:支持
watchlist_report模式,包含用户复盘字段和系统建议