# Prior Art Scout

> 项目开工前的技术方案调研引擎——给定项目想法,优先核验用户明确提供的项目、URL、工具或技术方向,再搜索最相关的整体方案并把任务拆成流程环节;从 GitHub、Web、X 等来源广泛保留轻量候选,覆盖开源、托管 API、SDK+闭源后端、MCP 等供应形态,对方向命中、完整方案和流程补位候选先核验是否真实可用、文档是否详细、接入是否不过度复杂,每个来源最多选择 5 个做代码或一手材料深验,最终聚焦回答别人解决什么问题、使用什么工具/流程/技术、能否直接使用或借鉴,并给出证据可追溯的评估与建议。当用户说“我想做一个 XX,先调研一下”“优先看看这个项目/方向”“看看有没有人做过类似的”“找现有方案/竞品/prior art”“开工前查一查”时使用。

- **Type:** Skill
- **Install:** `agentstack add skill-tlzmw001-naiyue-skills-prior-art-scout`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tlzmw001](https://agentstack.voostack.com/s/tlzmw001)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tlzmw001](https://github.com/tlzmw001)
- **Source:** https://github.com/tlzmw001/naiyue-skills/tree/main/skills/prior-art-scout

## Install

```sh
agentstack add skill-tlzmw001-naiyue-skills-prior-art-scout
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

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

## 必读契约

执行 Phase 1、3、4、5 时读取 [references/research-design.md](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 宣称。

## 工作区

~~~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、query_type；按类型补 direction_id、workflow_step_id、provider_shape_id。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、workflow_step、provider_shape 和 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. 用户方向候选降级、低排或未入选时填写 priority_override_reason；命中方向且入选时 `selection_basis` 必须包含 user_direction。
6. 每源最多 5 个；star 和活跃度不参与排序。
7. 将 `SKILL_DIR` 设为当前 `prior-art-scout/SKILL.md` 所在目录，然后运行：

~~~bash
python3 "$SKILL_DIR/scripts/validate_workspace.py" research/
~~~

入选候选保持 pending_deep_verify。未入选但相关的候选落 relevant_not_deep_verified；伪相关候选落 different_domain 并进入 rejected.json。

### Phase 4：深度验证

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

对 GitHub 候选：

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

对 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。任何判断没有证据路径就删除或补证据。

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

## 终态

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

## 自检

- 是否先搜完整问题，再搜拆分环节？
- 用户是否提供了明确方向；若有，方向查询是否最先执行，候选降级是否留下 priority_override_reason？
- 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？
- 主报告是否直接回答“问题—工具/流程/技术—能否使用/借鉴—评估—建议”？
- 已踩坑是否写清触发条件、影响、规避方法和证据？
- 共性未解问题是否至少由两个深验候选支持，并使用“本轮尚未解决”的准确措辞？
- mature_reference / partial_borrow 是否都已入选且读到核心实现？
- relevant_not_deep_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](https://github.com/tlzmw001)
- **Source:** [tlzmw001/naiyue-skills](https://github.com/tlzmw001/naiyue-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tlzmw001-naiyue-skills-prior-art-scout
- Seller: https://agentstack.voostack.com/s/tlzmw001
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.