Research Scan

research-scan

Research Scan 会为一个研究问题、项目或决策找出并核实最重要的 5–10 篇近期论文。从一份简报或一个问题出发，它会检索文献、沿引文图谱扩展、衡量覆盖度、对照实时记录核实每个 DOI，并生成证据对象——与此同时，驱动它的 Agent 会规划查询、筛选候选论文并为入围名单排序。这是面向推理 Agent 的证据管道，而不是回答问题的助手。

文档：https://researchscan.synectic.org

这项工作有意拆分为两部分。

CLI 是确定性的，不依赖模型。 它会检索 OpenAlex、Semantic Scholar 和 arXiv，遍历引文图谱、去重、统计各项标准的覆盖度、筛选入围论文、对照实时记录核实每个 DOI、应用筛选规则并生成结果。它不包含 LLM SDK，也不会对论文作出判断。

Agent 负责认知工作。 规划查询、为每篇候选论文打 0–3 分、在覆盖度不足时编写缺口查询，以及为入围名单重新排序，都是模型决策。技能包将这些决策依据的评分标准以纯 Markdown 形式放在 skills/research-scan/references/ 中；由承载该技能的 Agent 执行这些标准。

文件是两部分之间的接口：文件系统是推理与执行之间的协议边界，而不只是存储细节。因此，Claude Code、Codex、Cursor 或纯 Python 循环都能通过相同的工件驱动同一条链路。

brief ─▶ [plan queries] ─▶ retrieve ─▶ [screen 0–3] ─▶ expand ─▶ [screen] ─▶ coverage
      ─▶ [gap round, if coverage is thin] ─▶ shortlist ─▶ [rerank] ─▶ verify ─▶ emit

方括号中的步骤由 Agent 执行；其余步骤是 CLI 阶段。

有两个因素决定结果的边界。目的——build、research 或 orient——决定一篇论文必须满足什么条件才能入选。配置档——quick、standard 或 deep——决定扫描的成本。这两项都在工作原理中介绍。

输出是一个运行目录，其中包含经过验证的 JSON，以及一份可交给他人阅读的 Markdown 简报；其中每篇论文的 DOI、标题、年份和第一作者都已对照实时记录核实。

安装

Python ≥ 3.11 和 uv。

uvx research-scan doctor          # run any command without installing
uv tool install research-scan     # or put it on PATH permanently

配置

configure 会逐项询问凭据、显示已设置的内容、以 0600 权限写入 ~/.config/research-scan/.env（该文件位于权限为 0700 的目录中），最后运行 doctor。

research-scan configure          # `setup` is an alias for the same command

输入密钥时不会回显。可以安全地重复运行：每个变量都会显示其当前值，除最后四个字符外其余部分均会遮蔽；按 Enter 保留原值，输入内容则会替换它。文件中任何 configure 未询问的内容——包括注释——都会原样保留。如果 stdin 不是终端，它会打印待写入的文件内容并以状态码 2 退出，而不会卡住；这正适用于 Dockerfile 或配置脚本。

变量	用途
OPENALEX_API_KEY	OpenAlex，主要来源。必需；没有此项时 doctor 会以状态码 3 退出。
OPENALEX_MAILTO	强烈建议设置。可将 OpenAlex 的请求速率提高至 5 req/s，并加入 Crossref 的礼貌请求池。
S2_API_KEY	建议设置。没有此项也能使用 Semantic Scholar 搜索和引文图谱扩展，但请求速率会限制在约三分之一；doctor 会发出警告。
NCBI_API_KEY	可选。仅用于 PubMed：请求速率从 3 提高至 10 req/s。

如果要手动编写文件，仓库中的 .env.example 是模板。进程环境变量的优先级高于 ~/.config/research-scan/.env，而后者高于仓库本地的 ./.env。

检查是否正常运行

doctor 会实时调用每个来源并绕过缓存，而不是列出它认为已配置的来源。

research-scan doctor             # a four-line summary and a verdict
research-scan doctor --verbose   # every check, with timings and paths
research-scan doctor --json      # machine-readable; this is the CI/agent interface

Research Scan <version>
✓ configuration
✓ OpenAlex   ✓ Semantic Scholar   ✓ Crossref   ✓ arXiv   ○ PubMed
  PubMed: endpoint reachable; source routed for biomed but not built
✓ writable run store
Ready.

退出码为 0 表示一切就绪。退出码为 3 表示某项强制检查失败；请参阅故障排除。三种输出模式的检查内容和退出码完全相同，只有呈现方式不同。

○ 表示已路由到某个来源，但没有检索适配器 — 请参阅来源表。探测仍会运行，并如实报告：PubMed 对应的行表示 E-utilities 端点有响应，这与能够从中检索内容是两回事。doctor --json 会通过 sources_not_built 携带同一事实，此外还有一个键和值均保持不变的 providers 映射。

首次扫描

安装技能后，在 Agent 中发起扫描：

/research-scan "I am designing a financial education product for young adults. 
Research question: What interventions have the strongest recent evidence for increasing 
long-term savings behavior?

Context:
- I am interested in mechanisms that change real-world behavior, not just 
financial literacy scores.
- Prioritize randomized trials, large field studies, and strong causal evidence.
- Include evidence that challenges the assumption that education alone works.

Find the 10 papers that should shape our product decisions. Explain why each paper matters, what it 
found, and what evidence gaps remain." --profile standard

一句话提问即可。提供包含背景的简报效果更好，因为规划步骤会将简报的每个部分映射到搜索计划的特定部分。模板位于 skills/research-scan/examples/brief.example.md — 这是一个完整的 build 简报；而 brief.research-example.md 是同一模板，其中 Purpose: research。

/research-scan research/my-brief.md --profile standard --top 10

简报部分	对应内容
Purpose: 行	计划推导哪些子标准，以及 why_it_matters 必须论证什么。可填写 build、research 或 orient；省略时由 Agent 推断。
主题背景	brief_summary 和领域路由。请说明具体场景，而不只是主题。
需要做出的决定或回答的问题	每篇论文都要据此评分的子标准。请列出实际待决选项或具体问题。
我们目前的看法（前提）	contradictory 查询。只确认前提的扫描不构成证据。
排除项	queries.json.must_not，在代码中按词边界强制执行 — 绝不作为 NOT 词项写入查询文本。
已知论文或作者	anchors：固定加入候选池，不受筛选条件和数量上限限制，并始终用作扩展种子。

结果会保存到 research/scans/<YYYY-MM-DD>-<slug>/。请参阅输出。

完整参数列表：

/research-scan <brief.md | "question"> [--profile quick|standard|deep] [--top N] [--foundational N]
                                       [--from YYYY-MM] [--to YYYY-MM] [--slug name]
                                       [--domain behavioral|cs|biomed|general]
                                       [--max-candidates N] [--per-query N]

连接 Agent

同一条流水线的两个入口。技能中包含评分标准，因此由它负责筛选和重排的认知工作；MCP 服务则将相同的四个决策点作为工具提供给所有支持 MCP 的客户端。

Claude Code — 技能

任选一种；三种方式都指向同一个 skills/research-scan/。

# 1. symlink a clone — edits to the rubrics take effect immediately
ln -s "$PWD/skills/research-scan" ~/.claude/skills/research-scan

# 2. load the repo as a plugin, per invocation (it carries .claude-plugin/plugin.json)
claude --plugin-dir /path/to/research-scan

# 3. skills CLI
npx skills add Synectic-Research/research-scan

Claude Code — 插件

插件可一步安装技能并配置 uvx MCP 服务；对于 Claude Desktop 和 Cursor 等非插件客户端，请使用下方的 .mcp.json 方式。

/plugin marketplace add Synectic-Research/research-scan
/plugin install research-scan@synectic

任意 MCP 客户端 — stdio

research-scan mcp 仅通过 stdin/stdout 使用 MCP，不做其他操作。它不会读取令牌，也不需要令牌：因为客户端启动了该进程，所以该进程受到信任。无需额外安装 — 服务随软件包一同提供。

{
  "mcpServers": {
    "research-scan": {
      "command": "uvx",
      "args": ["research-scan", "mcp"]
    }
  }
}

客户端	配置位置
Claude Code	项目根目录下的 .mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json

共有四个工具，对应流水线所需的四项模型决策：scan_start（由你提供查询计划）、scan_continue（筛选评分、缺口查询或一页重排条目）、scan_verify 和 scan_result。它们不是流水线上的聊天端点：每个工具都是一个需要判断的决策点，由客户端模型提供技能原本会执行的全部认知工作 — 阶段顺序相同，产物相同。适配器会将 CLI 作为子进程运行并读取其退出码。运行 research-scan mcp --help 可查看其他传输方式。

工作原理

每个阶段都是幂等的，也可以重新运行：修改 queries.json 或传入标志，然后从受影响的阶段重新运行。CLI 管理 candidates.json、shortlist.json、manifest.json 和 evidence.*；Agent 管理 queries.json、screen.json 和 ranked.json。双方都不会编辑对方的文件。

目的

在简报的 Purpose: 行中声明，或根据内容推断。目的决定计划会衍生出哪些子标准、筛选如何判定相关性，以及 why_it_matters 需要论证什么。

目的	论文值得入选的理由	示例
build	推动设计或计划决策	“设计注册流程之前，我们应该了解什么？”
research	改变我们的认知、测试方案或衡量方式	“默认注册会如何影响人们的储蓄金额？近期最有力的证据是什么？”
orient	是新手必须了解的内容，优先选择近期资料	“我刚接触机制可解释性——有哪些必读资料？优先看近期的。”

配置档案

一个标志即可设定扫描成本。--profile 属于 init，并会记录在清单中；显式传入的标志仍会覆盖配置档案——无论配置档案如何设置，--per-query 60 都表示每个查询 60 条。

配置档案	每个查询	池上限	窗口外总量	补缺轮次
quick	20	250	12	从不
standard（默认）	40	450	20	覆盖不均时
deep	40	450 × 来源数 ÷ 2	30	总是

窗口外总量是整个运行的预算，而不是每个阶段的额度。从 standard 开始；想了解“有哪些资料”时使用 quick，漏掉资料代价较高时使用 deep。各配置档案的实测召回率见实测结果。

补缺轮次

补缺轮次最多运行一次；对于 standard，仅当 coverage 显示各标准的覆盖不均，或某个查询几乎没有结果时才会运行——否则会跳过，并在报告中说明。coverage 会统计每个子标准对应的筛选保留论文数量；Agent 会针对覆盖最少的标准编写一到两个查询；retrieve --round 2 和 expand --round 2 会补充找到的内容。第 1 轮的论文及其评分不会丢弃——资料池只会扩大。

支持的来源

来源	用途	状态
OpenAlex	主要搜索、元数据、撤稿标记、图谱备用来源	已实现。需要密钥。
Semantic Scholar	搜索，以及基于参考文献、引用和推荐的引用图谱扩展	已实现。密钥可选；不提供密钥时会受到限流。
arXiv	cs 的额外来源，以及查询属于方法类查询时 general 的额外来源	已实现。
PubMed	为 biomed 路由	已路由但尚未构建。 biomed 扫描会使用 OpenAlex + Semantic Scholar，并在 manifest.json 中记录 unavailable: true——已路由但缺失的来源会被记录，绝不会悄然丢弃。
Crossref	仅用于验证 DOI；绝不作为检索来源	已实现。如果无法访问，则验证会退回到 OpenAlex。

--domain 用于选择路由：behavioral 和 general → OpenAlex + Semantic Scholar；cs → 上述来源加 arXiv；biomed → 上述来源加 PubMed。--sources 会完全覆盖该映射。

测量结果

两个精心挑选的黄金主题——行为经济学和 LLM 文献检索 Agent——在候选项阶段进行评分，并由独立评审模型评估。这是两个主题，并非与其他工具进行基准比较。

配置	筛选的候选项	召回率（主题 1 · 主题 2）	≈ 用时
quick	~355	7/10 · 4/6	20–25 分钟
standard	~570	8/10 · 5/6	35–40 分钟
deep	575–805	9/10 · 5/6	40–55 分钟

由独立评审模型评估，窗口内排名前 10 的精确率为：两个主题均为 0.875。

随着候选池扩大，召回率会上升，效率则会下降：在主题 1 上，quick 每筛选 100 个候选项可获得 0.199 的召回率，而 deep 为 0.157。各配置之间最大的区别在于窗口外预算（12 / 20 / 30）——主题 1 剩余未命中的都是窗口前的经典论文，每提升一个档位，就会多纳入一篇。

完整表格、尝试后又撤回的内容，以及这些数字遵循的规则： docs/measurements.md。

输出

所有文件都会写入 research/scans/<YYYY-MM-DD>-<slug>/：

文件	内容
evidence.json	交付内容：每篇论文一个 EvidencePacket——包括元数据、重排评分、关键发现、重要性说明、局限性和验证记录。
evidence.md	同一列表的人类可读版本。基础经典论文排在当前研究之后，排名连续递增，因此 2004 年的论文会作为背景呈现，而不是作为答案。
evidence.bib	已输出论文的 BibTeX。使用 --no-bib 可禁用。
manifest.json	审计记录。所有丢弃项——撤稿、must_not、类型筛选、候选池上限——以及所有重试后仍失败的来源都会在此统计。不会静默截断任何内容。
coverage.json	按子标准统计覆盖该标准的保留论文数量，并按查询类型和来源细分；还包括每个查询的产出量和每个种子的扩展精确率。每轮生成一份快照，因此差距轮次找回的内容会作为增量呈现。并在 evidence.md 中渲染为 Coverage 部分。
queries.json、candidates.json、screen.json、expanded.json、shortlist.json、ranked.json	中间阶段文件，全部经过架构验证。
retrieval.log.jsonl、expansion.log.jsonl、verify.log.jsonl	各阶段的结构化日志。

如果论文的 DOI 无法解析，或者标题、年份或第一作者与实时记录不符，系统会标记，而不会静默修正：输出中会包含 mismatches[] 和 [UNVERIFIED — check manually] 标记。只有撤稿才会移除论文。

使用 research-scan schema --name <Model> 可打印任意数据契约；使用 research-scan schema --md 可将所有数据契约打印为 Markdown。

成本与耗时

墙上时钟耗时取决于候选池大小，因为筛选是最耗时的阶段。端到端测量结果（counts.wall_clock_s，从 init 到 emit）：

候选池	筛选批次	墙上时钟耗时
~675 个候选项——cs，默认上限下的 3 个来源	~27	37 分钟
~250 个候选项——默认上限下的 2 个来源	~10	22 分钟
~120 个候选项——--max-candidates 120	5	19 分钟

无论哪种情况，OpenAlex 的费用约为 $0.008——per_page 可免费增加深度，因此候选池大小几乎不会增加 API 费用。

Agent 令牌才是真正的成本，而且它们的降幅并不像候选池那样大：120 个候选项的运行仍花费约 $5.70 的前沿模型令牌成本，比 250 个候选项的运行只快了 3 分钟，因为当筛选规模较小时，重排（无论候选池大小如何，均处理 52 条完整记录）和固定阶段开销占据了主导。对于失控的 cs 候选池，--max-candidates 是合适的调节参数，但它并不能让扫描变得便宜。

默认上限会根据已构建的来源数量缩放（450 × n/2，因此 cs 为 675，两个来源时为 450）。--max-candidates 和 --per-query 属于 retrieve，可在每次运行时覆盖此上限。两者都是运行标志，不属于配置。

无头模式

该技能会返回 ScanSummary，因此扫描可以在无人值守的情况下运行，并将结构化 JSON 交给后续环节：

claude -p "Use the research-scan skill to scan brief.md with --slug nightly --top 5. \
           When it finishes, return its ScanSummary as your final answer." \
  --plugin-dir /path/to/research-scan \
  --allowedTools "Bash(research-scan *),Read,Write,Edit,Glob,Grep" \
  --output-format json \
  --json-schema "$(research-scan schema --name ScanSummary)" \
  > scan.json

jq '.structured_output.counts' scan.json

请用自然语言描述来请求该技能；此处不要直接使用 /research-scan … 斜杠命令。 该技能声明了 context: fork，因此直接使用斜杠命令会让整个过程都在分叉会话中运行，而会话返回 num_turns: 0 和 result: "Command completed"——扫描成功并写入了运行目录，但没有顶层助手轮次可供 --json-schema 绑定，structured_output 返回 null。将请求表述为指令，会让会话调用该技能、接收分叉会话的报告，并自行输出 ScanSummary，而这正是架构所绑定的内容。已于 2026-08-19 通过两种方式验证。

还有两个标志需要正确设置：

• 如果该技能已安装在 ~/.claude/skills/ 下，则不需要 --plugin-dir。绝不要将其与 --bare 一起使用：裸模式会跳过 --plugin-dir，因此技能根本不会加载。
• --allowedTools 必须包含 Bash(research-scan *)、Read、Write、Edit、Glob 和 Grep。Glob 不是可选项——该技能会对 screen-batches/ 使用 glob，以查找需要评分的批次。

不适用于

系统综述。 没有 PRISMA 流程记录，也没有筛选数千条记录的工作流。

稿件引文管理。 evidence.bib 只是附带提供，并非文献库。请使用引文管理器。

全文研究。 检索和筛选基于标题、摘要和元数据。不会获取、解析或阅读 PDF。

Google Scholar、Scopus、Web of Science、PsycInfo 不是数据源，未来也没有计划支持：它们都不提供个人密钥 API，也没有符合服务条款的途径。

故障排除

doctor 以状态码 3 退出。 某项必需检查失败了——请查看检查名称并修复问题，而不是绕过它。缺少 OPENALEX_API_KEY 属于 FAIL；因此 OpenAlex 探测会报告为 SKIP，而非通过，因为这些探测根本没有运行。缺少 S2_API_KEY 或 NCBI_API_KEY 仅属于 WARN：扫描仍会运行，但会受到限流。默认输出会说明该怎么做；--verbose 会提供包含耗时的完整检查列表，--sources openalex,s2 则会缩小检查范围。

通过脚本或 Agent 读取 doctor。 应使用 doctor --json 接口，其键名稳定。ready 是布尔值；providers 会将每个已检查的数据源映射为 ok / warn / fail / skip——skip 表示探测从未运行，绝不等同于通过；checks 包含每项检查结果。三种输出模式的退出码相同。

arxiv HTTP 429, cs/physics routing skipped。 arXiv 的限流很严格（客户端已控制为每 3 秒 1 个请求），负载较高时会返回 429。这属于 WARN，而非失败：cs 扫描会改用 OpenAlex + Semantic Scholar，它们本来也收录 arXiv 预印本——你失去的是当天的列表和一个来源信号，而非覆盖范围。如果时效性很重要，请稍后重试；每个来源的查询次数和失败记录位于 manifest.json 的 retrieval.per_source 下。

Semantic Scholar 积压。 队列较深时，S2 会返回 429/503。http.py 会重试，随后返回最后一个响应，而非抛出异常——错误状态也是数据。图谱扩展会回退到 OpenAlex 的纯 ID 参考文献列表；该列表可用，但无法排序（排序需要为每条参考文献获取一次元数据），因此扩展召回率会降低。expansion.log.jsonl 会逐次记录相关情况。

某个阶段以状态码 2 退出。 Agent 编写的文件未通过验证。错误会列出所有不合规的路径；所有位置都会拒绝未知键，因此拼写错误会显现，而不会被忽略。修复文件后重新运行该阶段。

research-scan mcp 无法导入服务。 fastmcp 是核心依赖，因此这表示安装不完整，而非缺少某个选项——请使用 uv tool install research-scan 重新安装。在完整安装中，research-scan version --json 会报告 "mcp": "enabled"。

Shell 补全

eval "$(research-scan completion bash)"   # add to ~/.bashrc
eval "$(research-scan completion zsh)"    # add to ~/.zshrc
research-scan completion fish > ~/.config/fish/completions/research-scan.fish

开发

git clone https://github.com/Synectic-Research/research-scan
cd research-scan
uv sync
uv run ruff check && uv run pytest -q     # the before-commit gate
uv run pytest -m live                     # the only tests that touch the network
uv tool install --editable .              # put research-scan on PATH, tracking the working tree

src/research_scan/schema.py 是事实来源：它会生成 JSON Schema、Agent 读取的契约文档（skills/research-scan/references/schemas.md——请在同一个提交中重新生成，测试会对比两者），以及 exit-2 错误消息。

AGENTS.md 包含操作准则，docs/measurements.md 记录了当前默认值背后的实测结果，eval/ 则包含黄金集测试框架（research-scan eval --topic <t> --run <dir>）。

drivers/ 包含认知引擎的实验性参考实现——这类代码会生成扫描所需的判断结果，供希望使用托管 Agent 以外的方案来驱动认知引擎的人参考。它们仅存在于代码库中：软件包不会安装或导入其中的任何内容，也不会将其打包到 sdist 或 wheel 中；此版本不会发布任何引擎协议。

文档 · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md · CODE_OF_CONDUCT.md · CITATION.cff · LICENSE（Apache-2.0）

依赖项各自保留其许可证；THIRD_PARTY_LICENSES.md 说明了这些许可证的内容，以及如何重新生成表格。