multi-source-paper-search

name

multi-source-paper-search

description

Search academic papers across multiple sources at once (OpenAlex, Semantic Scholar, arXiv/Valyu, Perplexity) from a single request, then cross-validate and cross-align the results into one cited synthesis report. Use this whenever the user wants to find papers / literature / prior work / studies on a topic and would benefit from MORE THAN ONE source — i.e. they want it comprehensive, corroborated, triangulated, or cross-checked, or they say things like "多源搜论文", "交叉搜论文", "跨源检索", "find papers on X across sources", "what does the literature say about X", "search arxiv and openalex for X", or ask which findings are agreed-upon vs contested. Strongly prefer this over any single source skill (openalex-paper-search / arxiv-search / perplexity-search / research-lookup) when the goal is a literature scan rather than fetching one specific known paper. The dedup/consensus/coverage alignment is the whole point — don't hand-roll it with one source.

Multi-Source Paper Search

Turn one request into a cross-source literature scan. The hard part isn't hitting four APIs — it's reconciling four differently-shaped result sets into a single honest picture: what's corroborated, what's contested, what only one source saw. This skill splits that cleanly:

• Deterministic work → scripts/fanout.py. Fan-out, normalization, and paper-level dedup (DOI / arXiv-id / title via union-find) are mechanical and must be exact. The script does them and emits one JSON object. Don't eyeball dedup yourself — it's unreliable and burns tokens.
• Semantic work → you. Query expansion, claim-level cross-validation, and writing the cited report need judgement. That's your half.

Procedure

1. Expand the query (light)

The academic sources are English-dominant, so translate a non-English request to English, then write up to 2 extra reformulations using method aliases / synonyms (e.g. "RAG" ↔ "retrieval-augmented generation"). More than ~3 total variants rarely adds recall and just costs API calls. Dedup across variants is free — the script handles it — so variants are cheap insurance for recall.

2. Fan out + align (run the script)

python scripts/fanout.py --depth 20 "variant 1" "variant 2" "variant 3"

If the user has a project .env with keys (e.g. OPENROUTER_API_KEY), load it first: set -a && source .env && set +a. The script auto-probes every source and skips any with a missing key/script — it never fails the run; OpenAlex needs no key and is always live. Read the JSON it returns: papers (deduped, ranked, each with consensus = # distinct sources and per_source_unique), sources_used, skipped_sources, and perplexity_narrative.

3. Cross-validate claims (semantic, lazy)

From the top deduped papers' abstracts and the perplexity_narrative, pull the key claims / numbers / conclusions. Compare across sources: what's echoed by multiple sources (→ consensus), what conflicts (→ divergence). Treat the Perplexity narrative as a lead to corroborate, not as settled truth. Only when the top-3 highest-consensus / highest-cited papers actually disagree on a claim, fetch those few papers' full text to adjudicate — arXiv hits carry full text in the content they were built from; otherwise open the url. Don't pull full text by default; it's expensive and usually unnecessary.

4. Write the report

Follow references/report-template.md exactly: 检索概况 → 共识发现 → 分歧高亮 → 每源独有贡献 → 论文排名表 → 参考文献. Match the user's language. Plain markdown, no charts (the reader pastes into Feishu). Always state "used X / 4 sources" so consensus counts are read in the right context. Be honest when recall is thin or sources were skipped — don't pad.

5. Offer to save

Print the report in the conversation first. 🔴 CHECKPOINT — do NOT write any file unprompted. Ask whether to save and where. Save by default is wrong here: the user usually just copies the markdown. Only after they say yes, write to the path they give.

Failure modes & fallbacks

Don't assume the happy path. Each row is trigger → first fix → if still stuck:

触发条件	一线修复	仍失败兜底
fanout.py 返回 papers: []（0 召回）	放宽 query（去专有缩写）/ 降 --depth / 多给 1 个变体重跑	报告如实写"未召回"，建议换检索术语；不要编造论文
skipped_sources 只剩 OpenAlex 一源	报告照出，但显式标注"单源，无交叉验证价值"	提示用户补 key（见 references/sources.md）后重跑
perplexity_narrative: []（key 失效/余额耗尽）	claim 级核验改用 OpenAlex/S2/arXiv 摘要，报告标注"无 Perplexity 叙事"	提示查 OpenRouter 余额；其余三源仍出报告
arXiv 报 JSON/Unterminated string	已由 fanout.py 临时文件兜底（Node pipe-flush）；正常应不再出现	仍失败则该源进 skipped_sources，报告标 3/4 源
所有 consensus 全 = 1（各源不重叠）	这不是 bug：各源 top-N 正交。改走 claim 级共识	报告"每源独有贡献"段说明覆盖正交，不硬凑 paper 级 consensus
fanout.py 直接报错/无法运行	检查 python 可用、.env 是否在 skill 根目录	报告失败原因给用户，不静默改用单源手搜冒充多源

Sources & keys

See references/sources.md for each source's invocation, key/env, the degradation contract, and how to add a fifth source. Quick map: OpenAlex (no key) · Semantic Scholar (optional S2_API_KEY) · arXiv (Valyu key via arxiv-search setup) · Perplexity (OPENROUTER_API_KEY).

Anti-patterns — do NOT do these

The whole value is honest cross-source reconciliation. These break it:

• ❌ 肉眼去重 / 手动合并论文 — 用 fanout.py 的确定性去重（DOI/arXiv-id/标题并查集）；人工去重不可靠且烧 token。
• ❌ 只跑一个源冒充多源 — 单源出的报告没有 consensus 意义，必须标注降级，不能包装成"多源已验证"。
• ❌ 把 Perplexity 叙事当已证结论 — 它是 web 合成的线索，需被其他源印证才进"共识"；只它提的进"分歧/独有"。
• ❌ 默认拉全文 / 默认存文件 / 默认出图 — 全文仅 top-3 冲突时拉；存盘要问；报告用 markdown 表不出图。
• ❌ 把 3 源跑出的 consensus 当 4 源口径 — consensus 是相对已跑源数的，2/2 弱于 2/4，概况里讲清。
• ❌ 粉饰稀疏召回 — 召回薄、源跳过多、共识弱时如实写，不堆砌、不补论文凑数。

Notes

• Depth default is 20/source ("standard"). Drop to ~10 for a quick scan, raise to 30+ for an exhaustive one.
• consensus is relative to the sources that actually ran — a 2 out of 2 live sources is weaker corroboration than 2 out of 4. Say so.
• fanout.py is pure stdlib; only the arXiv source shells out to the arxiv-search script (located dynamically). If that script moves, fix the locator in fanout.py.