/sn-search-academic

name: sn-search-academic
description: 用于学术调研、论文精读、相关工作梳理、百科知识查询和引用链追溯。

sn-search-academic - 学术搜索

凭证配置

API key、token 与 cookie 统一建议写在仓库根目录 `.env`（参考 `.env.example`），并由 runtime 或用户在执行前加载为同名环境变量。脚本仍只从环境变量或显式 CLI 参数读取凭证；不要把真实密钥写入 skill payload、报告、日志或提交。

使用三个统一入口完成学术调研：

• `search.py`：搜索论文和百科条目
• `paper.py`：列出论文章节，读取论文全文或指定章节
• `refTree.py`：查询论文的 references 和 citations

不要直接调用历史 provider 脚本；它们只是统一入口的内部实现细节。 需要 provider 回退链、参数分发或完整输出字段时，按需读取 `references/search.md`、`references/paper.md`、`references/refTree.md`。

可用脚本

| 脚本 | 用途 | 主要输入 | 主要输出 | |------|------|----------|----------| | `scripts/search.py` | 搜索论文/百科 | `query`，可选 `--source`、`--limit`、`--category`、`--lang` | 按 source 分组的论文/百科条目，位于 `source_results[*].items` | | `scripts/paper.py` | 列出章节，读取论文全文或章节 | 论文 ID，可选 `--source`、`--list_section`、`--section` | 章节列表位于 `sections`；全文或章节正文位于 `content` | | `scripts/refTree.py` | 查询引用树 | `--paper_id`、`--title`，可选 `--direction` | 参考文献与被引论文，位于 `source_results[*].references` / `source_results[*].citations` |

执行约定

本技能的 `scripts/...`、`requirements.txt`、`references/...` 路径均相对本 skill 目录；若当前工作目录不同，先解析为绝对路径，不要依赖 `${SKILL_DIR}` 运行时变量。

调用约定：

• 不要并行启动多个本技能脚本；`search.py` 和 `refTree.py` 内部已经处理并发、超时和 provider 回退链。
• 长结果优先加 `--output <path>` 写入文件，再读取必要字段，避免终端输出过长。
• `--provider-timeout` 表示单个 provider 超时；默认使用脚本内置超时。

依赖

首次运行或脚本提示缺库时，使用本技能的依赖清单安装到当前 Python 环境：

python3 -m pip install -r requirements.txt

不要在脚本内部自动安装依赖。若安装失败、网络不可用或包不可用，停止使用对应脚本并改用 WebSearch/browser-use，说明缺少依赖。

Crawler 回退还需要额外运行时环境：

python3 -m playwright install firefox

`arxiv_crawler_search.py` 和 `semantic_scholar_crawler_refTree.py` 还需要 Node.js，以及某个当前目录或祖先目录中已安装 `camoufox-js` 的 `node_modules`。缺少这些环境时，不要尝试绕过；改用非 crawler provider 或网页搜索。

参数说明

search.py

统一搜索入口。默认搜索所有支持的 source，并按 source 分组返回结果。

python3 scripts/search.py <query> [选项]

| 参数 | 说明 | 默认值 | |------|------|--------| | `query` | 搜索关键词，必填位置参数 | - | | `--source`, `--sources`, `-s` | 搜索源；支持重复传参或逗号分隔 | `all` | | `--limit`, `-n` | 每个 source 返回数量 | `10` | | `--category`, `-c` | ArXiv 分类过滤，只传给支持分类的 source | - | | `--lang`, `-l` | 语言提示，只传给支持语言参数的 source | - | | `--output`, `-o` | 将最终 JSON 写入文件 | - | | `--provider-timeout` | 每个 provider 的超时时间，单位秒；`0` 表示不限制 | `60` |

支持的 `--source`：

• `all`
• `arxiv`
• `semantic`
• `google_scholar`
• `pubmed`
• `wikipedia`

示例：

python3 scripts/search.py "retrieval augmented generation" --limit 5
python3 scripts/search.py "diffusion model" --source arxiv,semantic --category cs.CV --limit 5
python3 scripts/search.py "阿尔茨海默病 多模态诊断" --source pubmed,wikipedia --lang zh --limit 5
python3 scripts/search.py "agentic memory" --source all --limit 8 --output results/search.json

paper.py

统一论文阅读入口。默认按 arXiv 论文读取；读取 PMC 论文时显式传 `--source pmc`。不确定章节名时先用 `--list_section` 列出可用章节，再用 `--section` 精读。

python3 scripts/paper.py <id> [选项]

| 参数 | 说明 | 默认值 | |------|------|--------| | `id` | 论文 ID。arXiv 支持原始 ID、`arXiv:` 前缀、abs/pdf URL；PMC 支持 `PMC11119143`、`11119143`、PMC URL | - | | `--source` | 论文来源：`arxiv` 或 `pmc` | `arxiv` | | `--section`, `-s` | 读取指定章节；不填则读取全文 | - | | `--list_section`, `--list-section` | 列出论文可用章节，不返回正文；不能和 `--section` 同时使用 | false | | `--output`, `-o` | 将最终 JSON 写入文件 | - |

示例：

python3 scripts/paper.py 2603.00729
python3 scripts/paper.py 2603.00729 --list_section
python3 scripts/paper.py arXiv:2603.00729 --section introduction
python3 scripts/paper.py 2603.00729 --section method --output results/paper-method.json
python3 scripts/paper.py PMC11119143 --source pmc
python3 scripts/paper.py PMC11119143 --source pmc --list-section
python3 scripts/paper.py PMC11119143 --source pmc --section results

refTree.py

统一引用树入口。`--paper_id` 和 `--title` 都必填；标题用于回退时精确匹配。

python3 scripts/refTree.py --paper_id <paper_id> --title <title> [选项]

| 参数 | 说明 | 默认值 | |------|------|--------| | `--paper_id` | 论文 ID：Semantic Scholar ID、DOI、ArXiv ID、PMID 等 | - | | `--title` | 论文标题，必填 | - | | `--direction` | 查询方向：`references` 或 `citations`；不填则两者都查 | - | | `--source`, `--sources`, `-s` | 引用树 source；当前支持 `all`、`semantic` | `all` | | `--limit`, `-n` | 每个 source、每个 direction 返回数量 | `10` | | `--api-key` | Semantic Scholar API 密钥，可选 | - | | `--provider-timeout` | 每个 provider 的超时时间，单位秒；`0` 表示不限制 | `60` | | `--output`, `-o` | 将最终 JSON 写入文件 | - |

注意：参数名是 `--paper_id`，不是 `--paper-id`；`paper_id` 不支持位置参数。

示例：

python3 scripts/refTree.py --paper_id "2309.16609" --title "Qwen Technical Report"
python3 scripts/refTree.py --paper_id "2309.16609" --title "Qwen Technical Report" --direction references --limit 20
python3 scripts/refTree.py --paper_id "10.1038/s41586-024-07487-w" --title "AlphaFold 3" --direction citations
python3 scripts/refTree.py --paper_id "2309.16609" --title "Qwen Technical Report" --output results/refTree.json

输出格式

所有脚本都输出 JSON。先看顶层 `success`；失败时读取 `error`、`errors` 和 `attempts` 判断是无结果、超时还是 provider 失败。

search.py 输出

CLI 输出的顶层不包含 `items`，论文条目在 `source_results[*].items` 中：

{
  "success": true,
  "query": "retrieval augmented generation",
  "provider": "search.py",
  "sources": ["arxiv", "semantic"],
  "source_results": [
    {
      "source": "arxiv",
      "success": true,
      "provider": "arxiv_official",
      "items": [
        {
          "source": "arxiv",
          "provider": "arxiv_official",
          "title": "Example title",
          "abstract": "Example abstract",
          "citation_count": null,
          "arxiv_id": "2301.00001",
          "url": "https://arxiv.org/abs/2301.00001"
        }
      ],
      "attempts": [],
      "error": null
    }
  ],
  "errors": [],
  "error": null
}

常用 item 字段：

• 通用：`title`、`abstract`、`snippet`、`url`、`citation_count`、`doi`
• arXiv：`arxiv_id`、`pdf_url`、`categories`
• Semantic Scholar：`paper_id`、`venue`、`year`
• PubMed：`pmid`、`pmc_id`、`journal`、`pub_date`
• Wikipedia：`page_id`、`word_count`、`section_title`

paper.py 输出

默认读取全文；指定 `--section` 时读取章节。正文在顶层 `content`：

{