---
name: academic-search
description: Grant Master 文献调研阶段的多源检索、两遍筛选、开放全文获取和元数据合并方法。
---

# Grant Master 学术检索

来源：参考并改编自 [ustc-ai4science/academic-search](https://github.com/ustc-ai4science/academic-search)，MIT，Copyright (c) 2026 Chengmingyue。本项目检索协议、站点经验和工具从 Grant Master 提交 34e28f7 恢复；许可全文与改编范围见 [NOTICE.md](NOTICE.md)。

本方法是五阶段中的文献调研执行规则，由 auto 调用。`gm method --project ID` 返回本入口和 [完整搜索协议](search-protocol.md)，并绑定内容回执；先读最新用户修改，再研究。协议涉及的参考路径以插件根目录为准，研究输出以 context.root 为准，不能写进插件目录。

## 从问题到检索计划

读取课题准备、用户最新输入、总字数、现有文献及最新视角，确定本轮希望支持或推翻的问题。首轮形成计划，后续只补影响方案判断的证据缺口。将可读计划通过 gm publish 保存为 stage=1、id=research-plan。

每个 query 记录 query_id、问题、同义词/缩写、学科、平台、年份范围、纳入/排除标准、目标数量。先读对应 disciplines 文件，再按任务读取 API 与 site-patterns；无需把整个目录塞入上下文。按研究对象、体量及用户要求设定范围，不能用机械数量替代相关性。

## 两遍检索与全文

第一遍轻量获取题名、作者、年份、venue、引用数及采集来源/日期、稳定链接、开放全文状态，分重要和一般文献。第二遍针对核心论文核验摘要、全文、代码与 BibTeX。保留代表作、新工作和相反证据；实际无法达到目标时记录检索范围及不足，不补造条目。

默认由当前 AI 执行并合并独立 API 请求；没有必须创建的专用 worker。只有用户要求或当前任务明确允许且独立子任务值得分工时，才按有限批次分派。任务说明只传目标、输入输出路径和筛选条件，返回摘要及文件路径，不重复粘贴论文正文。

合法 OA PDF 用 ../../scripts/academic-search/oa-pdf-download.mjs 下载至 `<项目>/literature/papers/`；输入用 metadata-schema.md 定义的 JSON results。访问受限则保留 DOI/摘要和状态。用户提供的本地论文原件也先发布为 stage=1 的 PDF 资产，再用 paper 的 pdfId 关联。CDP 工具仅在当前宿主允许、且确需该访问方式时使用；可用的内置浏览器或 API 不要求额外启动代理。

## 合并与可追溯交付

以 DOI、arXiv ID、规范标题和年份依次去重，保留所有 query_id 与来源；相关性优先，再比较证据质量、venue、引用及时间，不混用不同来源引用计数。

每轮在 `<项目>/literature/search/round-N/` 保存 search_summary.md、candidate_papers.md、search_results.json、download_queue.json（下载 manifest）。使用 gm publish stage=1 注册这些报告；逐篇使用 gm paper 登记题名、作者、年份、sourceUrl（DOI 或发表页）、pdfId 与 reportId，再 publish 对应阅读报告。paper 不接受直接 PDF 路径。所有路径显式传项目内路径，更新已有报告必须使用其版本。JSON 是检索结果，不能作为工作台状态文件写入。

PDF 与论文登记示例（将 `<项目绝对路径>` 替换为 context.root；ID 在项目内唯一）：

先将以下 JSON 保存到项目内参数文件，再执行 `python3 <插件根>/workbench/gm.py publish --project ID --json <参数文件>`。`source` 是项目 downloads 候选目录中尚未登记的本地文件，`path` 是不同的、尚未存在的目标路径；已由扫描登记的 PDF 应复用 context.docs 中的 ID，不能再用新 ID 重复登记同一路径。

```json
{"id":"pdf-example","stage":1,"title":"论文原文","path":"literature/papers/example.pdf","source":"<项目绝对路径>/downloads/example.pdf","base_revision":null}
```

随后用以下参数执行 `gm.py paper --project ID --json <参数文件>`：

```json
{"id":"paper-example","title":"论文题名","authors":"作者姓名","year":"2026","venue":"发表来源","sourceUrl":"https://doi.org/实际DOI","pdfId":"pdf-example","reportId":"reading-example","status":"待精读"}
```

最后通过 `gm.py publish --project ID --id reading-example --stage 1 --file <阅读报告.md>` 发布阅读报告；已有报告附带 `--base` 当前版本。无全文时省略 pdfId，并明确摘要证据范围。

完成检索后继续按本阶段研究经验精读与综合，通过 publish id=perspective 更新最新判断。只有实际达到该阶段资料要求才调用 finish。遇到研究方向、范围或全文缺口需要用户决策，向统一待办中心投递并等待，用户拒绝不视为确认。

## 按需参考

- [search-protocol.md](search-protocol.md)：检索步骤、筛选、下载与核实，method 一并返回。
- [metadata-schema.md](metadata-schema.md)：字段、去重、下载清单与引用导出。
- [api-cookbook.md](api-cookbook.md)：官方 API 调用模板。
- disciplines/：学科平台、术语和证据规则。
- site-patterns/：目标站点经验；运行前确认时效，不把历史接口可用性当作事实。
- [venue-rankings.md](venue-rankings.md)、rankings/：按学科核验评级，不把 CS 分级套到其它领域。
- workflows/：用户需要系统综述时读取。
- [cdp-api.md](cdp-api.md)：使用可选 CDP 工具时读取。