prior-art-scout

Prior-Art Scout：开工前技术方案调研

回答：别人试图解决什么问题，用什么工具、流程和技术解决；我能否直接使用或借鉴；前人踩过什么坑；多个方案共同还有什么没有解决；基于证据应如何决策？

这是技术方案调研，不是产品热度排行。star、用户量和活跃度只能作为参考信号。

必读契约

执行 Phase 1、3、4、5 时读取 references/research-design.md。其中定义：

• 先搜完整问题，再按流程环节拆分查询。
• 用户提供明确方向时，先搜该方向并提高其候选优先级；覆盖其他候选时必须说明原因。
• 候选发现覆盖不同供应形态；GitHub 同时执行全文和 topic 搜索。
• 每个来源最多 5 个候选进入深度分析。
• 前三类选择依据必须先通过可采用性门槛；路线差异和失败证据候选单独标识。
• 报告先回答决策问题，候选全集放附录。

铁律

1. 尽力证明“有人做过”。 发现高度重叠的成熟方案是成功，不得为了支持开工而弱化重叠。
2. 存疑候选不得无记录丢弃。 全部进入卡片；超出深验预算时标为 relevant_not_deep_verified，明确“相关但未深验”，不得伪装成已验证结论。
3. 每源深验不超过 5 个。 总上限 = 启用来源数 × 5；不足不补，禁止突破上限。Phase 4 前必须运行 scripts/validate_workspace.py。
4. 淘汰必留痕。 different_domain 写入 rejected.json，必须说明“它解决 X，我的问题是 Y”。
5. 每个判断挂证据。 成熟性、核心机制、失败路线、可借鉴点和建议必须引用 raw/、cards/ 或 clones/ 中的具体路径。
6. 判路线不可行必须有死因证据。 需要弃坑声明、Issue 失败讨论或明确技术瓶颈；项目停更不等于路线不可行。
7. 成熟/借鉴结论必须深验。 mature_reference 和 partial_borrow 只能授予 selection.json 中已入选且 deep_verified=true 的候选；GitHub 候选必须 clone 并读核心代码，不能只转述 README。
8. 两个确认点必须真正停下。 用户明确确认前禁止继续下一阶段。
9. 区分“已踩坑”与“尚未解决”。 已踩坑必须有具体发生记录；共性未解问题必须至少由两个深验候选的证据共同支持。只能写“本轮深验方案中尚未解决”，不得从有限样本推导“行业无法解决”。
10. 用户方向优先但不免证。 方向查询先执行；方向候选相关性或证据不足时可以降级，但必须留下 priority_override_reason，不得因用户提到就直接判成熟。
11. 广搜不等于多读。 初搜只抓轻量元数据；GitHub 不在发现阶段批量读取 README/commit/Issue。只有每源最多 5 个入选候选进入 clone 或一手材料深验。
12. 区分客户端与后端。 开源 SDK 连接闭源服务时标为 open_client_closed_backend，不得写成开源抓取实现。
13. 前三类先证明能用。 用户方向、完整方案、流程补位候选必须在入选前证明当前有可用产物、使用文档详细且接入复杂度不是 extreme/unknown；否则不能靠这三类理由占用深验名额。
14. Web 优先使用宿主原生搜索。 读取 adapters/web.md；source=web，实际后端写入 provider，MCP 只作为 transport。宿主无搜索时不得假装执行，也不得自动安装 MCP、索要新 key 或静默切换 provider。
15. X 默认走 TikHub 但仍是弱证据。 读取 adapters/x.md；TikHub 负责可复现抓取，不把帖子自述升级为事实。线上 OpenAPI、真实响应和一手落地链接优先于 SDK 宣称。

工作区

research/<项目名>/
├── queries.json        # 锚点、任务环节、分来源查询；确认点 1
├── raw/<源>/           # 适配器原始结果
├── candidates.json     # 全量归一化候选
├── cards/              # 每候选一张卡
├── selection.json      # 每源最多 5 个深验候选及选择理由
├── rejected.json       # 问题域不同的候选
├── clones/             # GitHub 深验 clone
└── report.md           # 聚焦决策的最终报告；确认点 2