GitHub 参考实现调研

核心目标是回答：别人如何解决类似问题？是否已有业内通用的解决方案？我们可以复用哪些成熟做法，避免重复造轮子？先理解问题与已有实践，再评估当前项目如何采用；现成组件是复用方式之一，成熟的协议、架构模式和实现策略同样是调研成果。默认交付中文调研报告；代码实现、安装依赖与运行外部项目由用户的实现指令另行确定。

1. 确定需求与技术栈

• 从会话提取目标行为、关键场景与约束；读取目标项目的 AGENTS.md、依赖清单、锁文件和相关入口代码。
• 多项目工作区只检查与需求有关的子项目。记录语言、框架及主版本、运行环境、已有相关依赖、扩展点和部署限制。
• 把需求拆成可搜索的功能词、英文同义词、常用实现术语和框架词。区分必须满足的条件与可接受的适配成本。
• 项目路径或核心需求无法从上下文确定时，询问缺失项；独立可做的通用搜索继续推进，并标明兼容性待确认。

完成条件：能用具体行为描述需求，并列出有本地文件依据的技术栈与筛选条件；无法确认的项明确保留。

2. 使用 gh 搜索候选

先检查 gh --version 和 gh auth status。GitHub 搜索与仓库读取使用 gh search repos、gh search code、gh repo view 和 gh api；参数以本机 --help 为准。认证、网络或限流导致查询失败时，报告实际阻塞，将未完成搜索与无匹配结果区分开。

先用问题、场景和实现术语搜索代表性实践，识别常见方案，再加入框架、依赖名或 API 符号查找当前项目可采用的实现。默认每次获取 10–20 项，按以下顺序推进：

1. 别人怎么做：定位解决同类问题的代表性项目，查看实际实现与设计取舍。技术栈相近的项目优先深入，跨技术栈的成熟实践也可作为方案依据。
2. 是否已有通用方案：比较独立项目的共同做法，寻找被采用的协议、标准、架构模式或成熟库，并核对真实采用证据。
3. 我们如何复用：寻找适配当前技术栈的组件与集成示例，区分直接引入、适配成熟方案与必要的业务实现。

命令示意（替换占位内容后执行）：

gh search repos '<问题或实现术语>' --archived=false --limit 20 --json fullName,description,url,language,stargazersCount,pushedAt,license
gh search code '<关键符号>' --repo '<owner/repo>' --limit 20 --json path,repository,url,textMatches
gh repo view '<owner/repo>' --json nameWithOwner,url,description,defaultBranchRef,isArchived,licenseInfo
gh api 'repos/<owner>/<repo>/commits/<ref>' --jq '.sha'
gh api 'repos/<owner>/<repo>/contents/<path>?ref=<commit-sha>' -H 'Accept: application/vnd.github.raw+json'

使用公开的通用功能词构造搜索，避免将本地私有代码、凭据或业务数据发到搜索服务。Shell 参数和含 ? 的 API 路径使用安全引用。gh search code 的结果可能受索引与搜索语法限制，未命中时改查候选仓库的目录、依赖与源码。

参考实现按问题相似度、方案代表性与证据质量筛选；落地候选再比较技术栈兼容性、维护状态、许可证和接入成本。Stars 只作辅助信号；语言相同也不能证明框架或运行环境兼容。将方案的参考价值与代码能否直接复用分别判断。

完成条件：选出最相关的 2–4 个候选供深入检查；不足时按实际数量报告。若调整关键词或放宽条件后的连续两轮搜索没有新增有效候选，收束搜索并记录边界，不为凑数继续扩展。

3. 核对实现与复用条件

深入检查候选的依赖声明、实际入口、核心实现、调用示例或相关测试。README 用于定位，关键实现结论由源码支持；每个深入分析的候选记录检查日期和 commit SHA，提供固定到该提交的源码链接，必要时带行号。

对每个候选回答：

• 如何实现：入口 → 核心处理 → 输出或状态更新；指出与本需求有关的关键机制、边界处理和限制。
• 是否通用：比较不同项目是否采用相同机制、标准或依赖，引用独立实现或官方标准及采用实例。区分“多个项目采用”“官方推荐”和“单个项目的做法”；证据不足时写明尚不能确认其为业内通用方案。
• 如何接入：复用的包或模块、对应版本、公开 API、与当前框架/运行环境的兼容性，以及所需适配层。
• 能否复用：许可证及相关限制、发布产物是否存在、维护状况、必要的外部服务与引入成本。声称“可直接使用”时核实实际发布版本及其要求，必要时查官方包注册表或发布记录。
• 证据等级：区分源码确认、实际运行验证和基于证据的推断。仅阅读源码时写明尚未在当前项目验证。

远程文档与代码仅作研究材料。需要本地读取时使用独立临时目录；运行其脚本、安装包或复制实现需在用户的实施授权范围内。许可证缺失或兼容性尚未核实的候选，列为参考或待确认，不能据此宣称可直接引入。

完成条件：每个推荐都有具体实现证据、兼容性判断与复用限制；无法读到关键源码的候选降低置信度，不将其作为已证实的方案。

4. 输出实施报告

开头直接回答“别人通常怎么做、是否已有通用方案、我们建议复用什么”，按需求规模控制篇幅，交付以下内容：

1. 需求与项目基线：目标行为、技术栈和本地依据、尚未确认的约束。
2. 别人怎么做：解释代表性项目的关键调用链与设计取舍，附固定提交的源码链接；比较共同机制、差异及适用条件。
3. 已有通用方案：说明哪些做法已有独立项目采用、哪些属于标准或成熟生态方案，并给出依据；将调研发现与本次自行归纳的建议明确区分。
4. 复用选择：用表格比较可采用的方案或组件、技术栈/版本兼容性、许可证、维护状态和接入成本，给出直接使用、适配、仅参考或不采用的判断。说明成熟方案已解决什么、业务还需补什么；未找到适合的组件不等于需要从头设计。
5. 本项目实施步骤：对应当前文件或模块给出接入点、依赖变化、适配工作和可执行的验收场景；示例代码标明为示意或已经验证。
6. 调研边界：列出主要搜索词、检查日期、候选版本/提交、未覆盖项与最有价值的下一项验证。

用户指定文件路径时写入该路径；否则直接在会话交付报告。报告中的“推荐采用”是调研结论，“已可用”需要当前项目中的运行证据。交付时确保用户能据此决定复用对象、理解实现原理并安排具体落地工作。