literature-search

文献检索（共享工具链）

此技能不是一个循环，而是多个循环用于论文发现和新颖性检查的文献检索依赖项。它整合了 tools/lit_search.py（仅使用标准库的入口）和 tools/lit/ 包：Semantic Scholar（S2）用于语义搜索、片段和引文图谱，arXiv 用于全文阅读（核心功能无需密钥）；此外，在设置相应密钥后，还可使用 OpenAlex、Perplexity Sonar（ask）和 bgpt.pro（bgpt）。每个子命令都会输出 JSON；如果终端调用失败，则会输出 {"error","fallback"} 并以非零状态码退出，以便调用方退回内置的WebSearch/WebFetch。无需安装，Python ≥3.9。

循环如何使用

使用此工具的循环会在设置时解析以下路径，并重复使用：

• <lit_skill_dir> — 此技能的安装位置。执行 cp -r loops/* ~/.claude/skills/ 后，它会与调用它的循环位于同级目录，例如 ~/.claude/skills/literature-search/（请根据主机环境调整）。如果无法解析此路径，调用方会退回 WebSearch/WebFetch——依赖此技能绝不会导致循环彻底中断，只会为其提供补充。
• <lit> — 文献 CLI，作为单个命令令牌：<lit_skill_dir>/tools/lit_search.py。入口文件具有可执行权限，并包含 #!/usr/bin/env python3 shebang，因此可以直接运行，无需添加 python3 前缀。若要在多次调用之间复用缓存，请在子命令之后添加 --cache-dir <sandbox_root>/literature/.cache（这是针对单个子命令的标志，不是全局标志）。
• <lit_py> — 仅在主机不支持可执行权限位时，才需要使用备用形式：<lit_py> <lit_skill_dir>/tools/lit_search.py，其中 <lit_py> = python3（任何 ≥3.9 的解释器均可）。

将 <lit> 作为一个命令调用——保持为单个 Shell 令牌。 尤其是，zsh 不会对未加引号的变量进行分词，因此将两个单词 python3 .../lit_search.py 存入变量后调用 $VAR，会尝试执行一个不存在的长文件名。请使用上文的单令牌可执行形式，直接调用脚本路径，或显式拆分（在 zsh 中使用 ${=VAR}）。

子命令

子命令	用途
<lit> search "<q>" [--year 2020-] [--min-citations N] [--limit N] [--source s2|openalex|both] [--sort relevance|citations|recent]	语义发现——查找相关论文（标题、TLDR、摘要、引文数、arxiv_id）。默认使用 --source s2（按相关性排序）；添加 openalex/both 可扩大检索范围
<lit> snippet "<q>" [--limit N]	全文段落搜索——无需阅读全文，即可定位逐字引用的事实或数值
<lit> cite <paperId> --direction references|citations|recommend	遍历引文图谱（向后 / 向前 /“相似论文”）
<lit> fulltext <arxivId> [--mode auto|latex|pdf]	深入阅读一篇论文的方法和结果（HTML > LaTeX > PDF）
<lit> ask "<question>" [--model sonar|sonar-pro|sonar-reasoning]	Perplexity Sonar 综合分析——提供带引文的高层次回答（需要 OPENROUTER_API_KEY；否则请使用 WebSearch）
<lit> bgpt "<q>" [--num N] [--days-back N]	bgpt.pro 结构化提取实验结果和局限性（前 50 个结果免费，之后需要 BGPT_API_KEY）
<lit> keys [--init]	报告哪些 API 密钥已配置（仅显示布尔值）；--init 会写入或扩展 keys.env

S2 + arXiv 核心功能（search/snippet/cite/fulltext）无需密钥。可选功能（search --source openalex|both、ask、bgpt）会在配置相应密钥后扩大检索和综合分析范围。

API 密钥（共享约定——可选，绝不阻断）

此技能是项目密钥约定的权威出处（该约定由已安装的代码实现）。密钥保存在项目根目录下一个被 gitignore 忽略的 keys.env 文件中（工作目录最近的 .git 祖先目录；若没有，则为 CWD），供项目中的所有技能共用。

• 普通的 KEY=VALUE 行；# 注释；忽略空行；权限为 0600。
• 真实的 OS 环境变量始终优先于文件中的值（CI／高级用户只需执行 export 即可）。
• 所有密钥都是可选的——缺少某个密钥时，对应功能会优雅降级，直至使用 WebSearch。
• 机密绝不会进入对话——用户自行编辑 keys.env；技能只读取密钥是否存在这一布尔状态，绝不读取其值。

引导流程：<lit> keys（报告哪些密钥已配置）→ <lit> keys --init（创建／追加密钥项，只追加，绝不覆盖；打印路径）→ 用户打开 keys.env，粘贴所需密钥（在会话中：! $EDITOR ./keys.env）→ 再次执行 <lit> keys，然后继续。绝不因密钥阻断流程。

• S2_API_KEY（免费）——最值得设置的密钥；可专门用于 search／snippet／cite，速率为 1 req/s。
• OPENALEX_EMAIL（免费，任意邮箱）——使用 OpenAlex 的“礼貌池”，加快 --source openalex|both。
• OPENROUTER_API_KEY（付费）——启用 ask（Perplexity Sonar）；没有该密钥时，ask 会被禁用。
• BGPT_API_KEY（50 条结果以内免费，之后付费）——免费额度用完后，可继续使用 bgpt。

限制

• 仅使用标准库——绝不添加依赖，也不假设任何依赖已安装；必须能在原生 python3 环境下运行。
• 自包含——所有内容都位于此文件夹下；不得通过 ../ 越界，也不得链接到 docs/。
• 失败时安全地回退——任何数据源出错时，输出 {"error","fallback"} 并以非零状态码退出，而不是抛出异常，以便调用方平稳降级。