Prior Art Scout

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

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

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

必读契约

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

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

铁律

1. 尽力证明“有人做过”。 发现高度重叠的成熟方案是成功，不得为了支持开工而弱化重叠。
2. 存疑候选不得无记录丢弃。 全部进入卡片；超出深验预算时标为 relevantnotdeep_verified，明确“相关但未深验”，不得伪装成已验证结论。
3. 每源深验不超过 5 个。 总上限 = 启用来源数 × 5；不足不补，禁止突破上限。Phase 4 前必须运行 scripts/validate_workspace.py。
4. 淘汰必留痕。 different_domain 写入 rejected.json，必须说明“它解决 X，我的问题是 Y”。
5. 每个判断挂证据。 成熟性、核心机制、失败路线、可借鉴点和建议必须引用 raw/、cards/ 或 clones/ 中的具体路径。
6. 判路线不可行必须有死因证据。 需要弃坑声明、Issue 失败讨论或明确技术瓶颈；项目停更不等于路线不可行。
7. 成熟/借鉴结论必须深验。 maturereference 和 partialborrow 只能授予 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 宣称。

工作区

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

主流程

Phase 1：锚点、任务拆分与查询规划 → ⛔ 确认点 1

写入 queries.json，结构遵循 schemas/query-plan.json：

1. 工作区写 research_contract_version: 3，定义用户问题的一句话锚点和 2～3 个核心技术难点；旧版本或缺失版本直接报错。
2. 用户提供项目、URL、工具、技术路线或供应商方向时，写入 project.user_directions；为每个适用来源先写 user_direction 查询。没有方向时不创建。
3. 把“要完成的事情”拆成 3～6 个流程环节，每个环节写清输入、动作、输出。
4. 对每个启用来源写至少一条 direct 查询，搜索最接近完整问题的方案。
5. 为各流程环节写 workflow_step 查询，搜索该环节可独立复用的工具、流程或技术。
6. 列出本题相关的 project.provider_shapes，用 provider_shape 查询补查托管 API、开源客户端加闭源后端、MCP、浏览器/私有 API、外部索引等容易漏掉的形态。
7. 需要调查失败经验时再添加 failure_signal 查询。
8. 每条查询写 id、query、intent、querytype；按类型补 directionid、workflowstepid、providershapeid。GitHub 查询还写 search_mode。

平台方言：

• GitHub：全文查询使用领域词 + tool/cli/agent/sdk/api/mcp 等实现词；另用 topic 交叉搜索 data-api、private-api、crawler 等相关主题，并检查组织、homepage 和同组织项目。
• Web：完整问题句、how-to、替代术语和环节问题；Google 只是可能的 provider/engine，不是来源名。
• X：通过 TikHub 搜场景、抱怨、演示和经验表达；每条查询填写 search_type，默认 Top，近期经验和失败信号用 Latest；按弱信号处理。

⛔ 硬停。 展示锚点、流程拆分和查询集，邀请用户修改。用户明确确认前禁止搜索。

Phase 2：确定性抓取

逐个启用来源：

1. 读取 adapters/.md。
2. 逐条执行查询并保存 raw//。
3. 映射到 schemas/candidate.json，追加 candidates.json。
4. 保留所有结果、查询顺序和 matched_queries；抓取阶段不筛选、不总结。

先执行 user_direction 查询，再执行 direct、workflowstep、providershape 和 failure_signal。GitHub 发现阶段每条查询默认最多收集 100 个元数据结果，不批量拉 README、commit 或 Issue；100 是 API 结果窗口的安全上限，不是深验名额。

Web 来源执行 adapters/web.md：优先使用当前宿主原生 Web Search，每条查询写入符合 schemas/web-capture.json 的 raw/web/.json，保存实际 provider、transport、抓取时间、结果顺序和 ok/no_results/error 状态。搜索摘要只用于发现，重要结论必须继续打开一手页面。宿主不可导出完整工具响应时写 raw_response_exportable=false，不得伪造 raw envelope；失败时不得静默换 provider。

X 来源执行 adapters/x.md：API key 优先读取环境变量，macOS 可从 Keychain 兜底；禁止写入仓库、.env、命令参数或日志。运行 scripts/tikhub_x_run.py research/ 按计划顺序抓取缺失的第 1 页并归一化，已有捕获必须复用，避免重复计费；覆盖不足时才显式用 tikhub_x_fetch.py 传 cursor 翻页，再重新归一化。HTTP/业务失败、data=null、字段漂移或查询覆盖不完整时必须停止，不得手工猜字段或静默产出空候选。

适配器不存在则说明该源尚不可执行并跳过，不得假装已搜索。

Phase 3：全量卡片与限额选择

对每个候选填写 schemas/scheme-card.json：

• problem_solved：它具体试图解决什么。
• solution：用了什么工具、什么流程、什么关键技术，产出什么。
• observed_pitfalls：已经实际发生的坑，包括触发条件、影响、规避方式和证据。
• unresolved_problems：该候选仍未解决的问题，以及为什么现有机制不够。
• overlap / difference：与锚点及流程环节的重叠和差异。
• delivery_assessment：交付形态、实现可见性、上游访问方式、平台政策状态、是否真实在线验证；无法证明时写 UNKNOWN/unknown。
• usability_assessment：可能直接使用、组合使用、只借鉴思想或不建议采用；初筛只能写暂定判断。
• 信息不够的字段写 UNKNOWN，禁止编造。

然后生成 selection.json，结构遵循 schemas/selection.json：

1. 按 user_direction、complete_problem、workflow_gap、route_diversity、failure_or_unique_evidence 顺序竞争名额；每个入选项在 selection_basis 记录实际依据。
2. 对前三类的少量竞争候选读取一手安装页、Quick Start、API 使用页或 README 使用章节；不 clone、不读核心实现、Issue 或 commit。
3. 前三类只有同时满足 usable_now=true、documentation_quality=detailed、integration_complexity 不为 extreme/unknown，并提供文档证据时才能入选；写入 adoption_readiness。
4. 第 4、5 类可以因路线增益或失败证据入选，不要求假装可直接用；报告必须说明其入选价值。
5. 用户方向候选降级、低排或未入选时填写 priorityoverridereason；命中方向且入选时 selection_basis 必须包含 user_direction。
6. 每源最多 5 个；star 和活跃度不参与排序。
7. 将 SKILL_DIR 设为当前 prior-art-scout/SKILL.md 所在目录，然后运行：

~~~bash python3 "$SKILLDIR/scripts/validateworkspace.py" research/ ~~~

入选候选保持 pendingdeepverify。未入选但相关的候选落 relevantnotdeepverified；伪相关候选落 differentdomain 并进入 rejected.json。

Phase 4：深度验证

只深验 selection.json.selected，不得临时扩大数量。

对 GitHub 候选：

1. clone 到 clones//。
2. 对照锚点和 coveredworkflowsteps 定位核心入口、状态、依赖与调用链。
3. 阅读 README、核心代码、相关 Issue/commit，主动查找失败、降级、误判、扩展性和维护问题。
4. 判断仓库是完整实现还是 SDK/插件入口；闭源后端能力只能由 API 实测和一手文档验证，不能由客户端代码代替。
5. 回填问题、工具、流程、关键技术、产物、取舍、已踩坑、未解问题、可用性和证据路径。
6. 落到 maturereference、partialborrow、routeinvalidated 或 differentdomain。

对 X 候选，按 adapters/x.md 使用 TikHub 补全原帖和必要讨论；帖子链接到 GitHub、官方文档或产品页时回到一手材料核验。其他来源按其 adapter 定义的一手材料完成等价深验。若深验候选失效或明显偏航，可以在同来源预算内用 not_selected 候选替换；必须更新 selection.json，记录替换原因并重新校验，仍不得超过 5 个。

入选前 adoption_readiness 只证明有明确、不过度复杂的使用路径，不等于实现可靠或已经适合生产。Phase 4 必须重新核验真实接入条件、核心实现和运行边界。

Phase 5：报告合成 → ⛔ 确认点 2

按 templates/report.md 输出，正文按以下顺序：

1. 结论摘要：能否直接用、应借鉴什么、是否需要自研。
2. 用户指定方向核验：结果、证据、优先级判断；无结果写 no_results。
3. 别人怎么解决：逐个深验候选说明问题、工具、流程、关键技术和产物。
4. 可用性判断：逐项给出当前是否可用、详细使用文档、前置条件、接入复杂度，以及直接使用 / 组合使用 / 只借鉴思想 / 不建议采用的结论。
5. 综合评估：供应形态、证据强度、覆盖、代价、风险和缺口。
6. 前人踩坑与共性未解问题：区分已发生事实和跨候选仍未解决的缺口。
7. 参考建议：推荐组合、实施顺序、待验证问题。
8. 附录：查询覆盖、方向优先级覆盖、相关但未深验、淘汰项和证据索引。

正文只展开深验候选。不得用几十个候选清单挤占结论；全量候选放附录或单独 JSON。

再次运行 validate_workspace.py。任何判断没有证据路径就删除或补证据。

⛔ 硬停。 交付报告并等待用户裁决。用户对候选结论有异议时，回到卡片和原始证据复核。

终态

| 终态 | 含义 | 条件 | |---|---|---| | maturereference | 可直接采用或作为主要参考 | 已入选、已深验、实现与边界清楚 | | partialborrow | 某工具、流程或技术可借鉴 | 已入选、已深验、指出具体借鉴点 | | routeinvalidated | 路线已有不可行证据 | 有死因证据 | | differentdomain | 问题域不同 | 有明确差异陈述并进入 rejected | | relevantnotdeepverified | 相关但未进入本轮深验预算 | 说明未选原因，禁止成熟性结论 | | pendingdeep_verify | 已入选、等待深验 | 非终态，Phase 4 后必须消除 |

自检

• 是否先搜完整问题，再搜拆分环节？
• 用户是否提供了明确方向；若有，方向查询是否最先执行，候选降级是否留下 priorityoverridereason？
• GitHub 是否同时做全文与 topic 搜索，并覆盖托管 API、SDK+闭源后端、MCP 等相关供应形态？
• Web 是否使用 source=web 并记录实际 provider/transport；宿主原生搜索不可用时是否诚实停止，而非自动接第三方？
• Web 每条查询是否保存符合 web-capture schema 的记录，失败、零结果和 raw 不可导出是否明确区分？
• X 查询是否全部声明 TikHub search_type，原始响应是否脱敏落盘，失败与零结果是否分开？
• X 帖子中的自述是否仍按弱证据处理，并回到链接的一手材料核验？
• 初搜是否只抓轻量元数据；入选前是否只对前三类竞争候选读取使用文档；Issue/clone 是否仅用于入选深验候选？
• 前三类入选项是否证明 usable_now、详细使用文档、非 extreme/unknown 接入复杂度并留下证据？
• 每个流程环节是否至少有查询覆盖？
• 每个来源的 selection.json.selected 是否 ≤ 5？
• 主报告是否直接回答“问题—工具/流程/技术—能否使用/借鉴—评估—建议”？
• 已踩坑是否写清触发条件、影响、规避方法和证据？
• 共性未解问题是否至少由两个深验候选支持，并使用“本轮尚未解决”的准确措辞？
• maturereference / partialborrow 是否都已入选且读到核心实现？
• relevantnotdeep_verified 是否明确写成未验证，而非隐性淘汰？
• 搜索失败、零结果和问题域不同是否分开记录？

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tlzmw001
• Source: tlzmw001/naiyue-skills
• License: MIT

Install and usage instructions live in the source repository linked above.