GitHub 开源项目选型（github-oss-scout）
目的
把"找开源轮子"这件事从碰运气变成可重复的工程流程：需求关键词提炼 → 多路检索 → 五维打分 → 深度评估 Top3 → 输出含二次开发成本与风险的选型报告。
何时使用
用户提出项目需求并希望复用现有开源方案，或明确提到"开源项目调研 / 选型 / GitHub 搜一搜 / 有没有现成的"。
工作流程
1. 需求澄清（必做，不可跳过）
在搜索前确认以下信息，缺失则向用户提问：
- 项目要解决的核心业务问题（一句话）
- 必备功能清单与可选功能清单
- 技术栈约束（语言、框架、数据库、部署环境：Windows/Linux/Docker/云）
- 许可证约束（是否商用、是否可接受 GPL 类传染性协议、是否需要闭源二次开发）
- 项目形态（库/SDK、完整应用、SaaS 替代品）
2. 关键词提炼与多路检索
- 从需求中提炼 3-5 组中英文搜索词（同义词、领域术语、竞品名）。
- 运行
scripts/github_search.sh "<query>"执行搜索；脚本自动选用ghCLI（已认证时）或回退到匿名 GitHub Search API（curl，限速 10 次/分钟，注意控制调用次数）。 - 每组关键词至少尝试两种排序：
stars（找主流方案）与updated（找活跃新方案），避免漏掉"新而快"的项目。 - 初筛保留 8-12 个候选进入打分。
3. 五维打分初筛
按 references/evaluation-rubric.md 中的评分细则对候选逐项打分（每项 1-5 分，带权重）：
1. 更新时间 / 活跃度（权重 25%）— 最近提交、issue 响应、release 频率
2. Star / 社区规模（权重 15%）— 注意区分"明星老项目"与"近期高增长"
3. 许可证（权重 20%，且为一票否决项）— 与用户商用/闭源诉求冲突即淘汰
4. 技术栈匹配度（权重 25%）— 语言、框架、依赖与用户环境的一致性
5. 部署难度（权重 15%）— 依赖复杂度、文档质量、是否提供 Docker/一键脚本
得分排序后取前 3 名进入深度评估。打分依据必须写明数据来源（API 字段、README、commit 历史），不允许凭印象打分。
4. Top3 深度评估
对每个入选项目，补充以下信息（来源：README、docs、issues、代码结构）：
- 功能覆盖度对照表：用户必备功能逐项标注"开箱即用 / 需配置 / 需二次开发 / 不支持"
- 二次开发点清单：每个需开发的功能给出工作量预估（人日）与改动位置（插件机制/配置文件/需改源码）
- 改造成本分级：低（配置即可）/ 中（写扩展代码，不动核心）/ 高（需 fork 改核心逻辑）
- 潜在风险：维护停滞迹象、核心贡献者单一、issue 积压、许可证附加条款、依赖陈旧、社区分裂（fork 分流）
5. 输出选型报告
使用 templates/report-template.md 作为输出骨架，结论先行：
- 第一段直接给出"哪个能直接用"的推荐结论与一句话理由
- 然后逐项目给出五维得分表、功能对照、二开清单、成本与风险
- 最后给出行动建议（直接部署 / 先 PoC 验证 / 放弃自研对比）
- 报告结尾必须注明数据采集日期与来源（GitHub API），数据有时效性
关键纪律
- 不编造数据：Star 数、更新日期、许可证必须来自 API 或仓库页面实际查询，禁止凭训练记忆填写。查不到就标注"未核实"。
- 许可证是红线：GPL/AGPL 对商用闭源场景的传染性必须显式提示，不可省略。
- 活跃度优先于 Star：一个 50k Star 但两年无提交的项目，优先级低于 5k Star 但周更的项目（除非它是协议/算法类稳定库）。
- 部署难度要实证：优先看仓库是否提供 Dockerfile、docker-compose.yml、一键脚本，而非只看文档宣称。
