litloop

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- 由 skills-src/ 生成：改那里的文件，再运行 python scripts/build_skills.py -->

# LitLoop — 学术论文下载与检索

20+ 数据源并行竞速,首个成功立即返回。数百篇以上的清单需要先分类摸底(OA/Sci-Hub/需机构)时,转用 `litloop-sort` skill。

## 环境检查

工具列表含 `litloop_*` → 用 MCP 工具;否则 CLI 兜底,先 `litloop check` 确认依赖。

## 策略选择规则(必读)

**用户指定了来源 = 只用那个来源:**

| 用户说的是 | 策略 | 说明 |
|-----------|------|------|
| "从 Sci-Hub 下载" | `scihub_only` | 只走 Sci-Hub |
| "优先 scihub" | `scihub_first` | OA 仍竞速——OA 更快时最终来源可能是 OA |
| "只要免费合法的" | `legal_only` | 排除 Sci-Hub / LibGen |
| 没指定 | `fastest`(默认) | 全源并行竞速 |

```bash
litloop config-cmd download_strategy scihub_only
```

## 单篇下载

```bash
litloop get <DOI>                    # 零配置竞速
litloop fetch <DOI> [--output DIR]   # 7 步机构级联
```

竞速分层:Tier1 出版商直链(4s) → Tier2 OpenAlex/Unpaywall(5s) → Tier3 EuropePMC/PMC/arXiv(8s) → Tier4 Sci-Hub/LibGen 无头浏览器(25s) → Tier5 WebVPN/CARSI(20s)。国内 Tor 常失败,直接不用。

单篇竞速默认是**对冲级联**(`race_mode=hedge`):车道按评分排序,最优源先发,`hedge_delay_seconds`(默认 1.5s)内无响应才加发下一车道,已发车道快速失败则立即加发——请求量/反爬触发率比齐发降 3-5 倍,尾延迟几乎不变。`config set race_mode full` 恢复旧版齐发竞速。

**换源重下必须清缓存**:`rm -f <out>/.doi_index.json && rm -rf ~/.litloop/cache/*`。

## 批量下载

```bash
litloop batch dois.txt --output <dir>            # 默认车道调度(见下)
litloop batch dois.txt --no-lanes                # 退回逐篇对冲竞速
litloop batch dois.txt --scihub                  # 灰源竞速引擎(scihub_only/grey_only/scihub_first 策略自动走此路)
```

**车道调度是批量默认**(CLI 默认开,MCP `batch_download` 对 ≥3 条标识符自动启用;`config set batch_default_lanes false` 全局关闭):先 **S2 批量预嗅探**(500 DOI/请求,直接拿到 OA PDF 直链,≥`lane_s2_batch_min`(10) 条才启用)→ **快车道并行 HTTP**(OA 直链 + Elsevier API + MDPI CDN 规律构造 `lane_mdpi_cdn`)→ 失败溢流 **灰色源竞速** → **机构级联**,最后瞬时失败冷却重试。MDPI(`10.3390`)走 mdpi-res.com CDN 直连(94% 命中,绕开主站反爬),不消耗嗅探请求。车道模式忽略 `batch_id` 断点(灰色道内部仍保留断点);需要断点续传用 `--no-lanes`。

⚠️ **>300 篇必须分批**——校验阶段并发 validate 会 TimeoutError 崩溃,一个都不下。断点续传:重跑同文件自动跳过已完成;MCP 用相同 `batch_id`。连续 Cloudflare 拦截时停下来排障(见下),不要硬冲。

## 检索与引文

```bash
litloop search "关键词" --limit 10 --sort cited_by_count   # 13源引擎,失败降级三源
```

搜作者优先用 `--author "Dabo Guan"` 或 OpenAlex `--author-id`,别把人名放 query(全文匹配会混入同名/被引提及)。引文格式(citation: bibtex/ris/endnote)仅 MCP 支持。发现层:CLI `plan → estimate → find --out <dir>`,再 `build-queue <dir> --out queue.txt` 接 batch。OpenAlex 配额按 IP 每日计(429 就降级 Unpaywall 单点并发);Unpaywall 批量端点常 500,自写单点并发脚本更稳。

## 首次使用：配置 Key 和联系邮箱

第一次用、或 `litloop_diagnostics(check="setup")` 显示缺项时，按影响大小逐项问用户要不要配置（都可以跳过，跳过时说明影响），用 `litloop_config(key=..., value=...)` 写入，不要替用户编造或回显完整的 Key：
1. `openalex_api_key`：检索的主要数据源；没有时每天只有约 1000 积分，深度检索可能中途用完。
2. `elsevier_api_key`：下载 Elsevier 全文、补摘要（Scopus 每周 10000 次）。
3. `springer_meta_api_key`：Springer Nature 的 Meta API Key（不是 Open Access API 那个），补 Springer、Nature 文章的摘要；免费每天 500 次；摘要仅限个人、非商业使用。
4. `email`：联系邮箱，只发给 Crossref、OpenAlex、Unpaywall；有它时 Crossref 允许同时 3 个请求。
5. 学校的 WebVPN / CARSI / EZProxy，以及 Zotero 推送的分类。
各接口用量和剩余额度用 `litloop_diagnostics(check="quota")` 查看；深度检索返回的 `api_warnings` 不为空时，转告用户。

## 检索与筛选（AI 给理由，用户决定）

用户要找文献时按这个流程，不要直接甩一个列表：

1. **定标准**：把问题拆成 2–5 条纳入标准（研究对象、关注性质或现象、方法、文章类型、年份）。
   - 快速查找：直接写在结果上方，不等确认。
   - 课题调研、综述等深度检索：先列出标准请用户确认或修改，再检索。
2. **检索**：`litloop_search` 用英文关键词；中文问题先译成英文检索词，必要时换 2–3 组同义词分别检索。插件会按术语表自动多搜几种写法（另一种英美拼写、用户的缩写和同义词、元素符号和名称），返回的 `glossary` 列出展开了什么，告诉用户；术语表里已有的写法不用再单独检索。用户在意期刊质量时用 `max_cas_zone` / `max_cas_sub_zone` / `max_jcr_quartile` / `exclude_warning`，不要擅自加过滤。
3. **逐篇判断**：读每篇的标题和 `abstract`，按标准给相关度 **高 / 中 / 低 / 不相关**，写一句中文理由，说明它对应哪条标准、缺了什么。`abstract_missing` 的文章在理由里注明“仅凭标题”。不要编造摘要里没有的内容。
   - **怎么分档**：研究对象、方法、关注点都符合 → 高；对象相同但方法或路线不同，或只覆盖问题的一部分，或与问题直接相关的综述 → 中；方法相同但对象是相邻体系，或泛泛的综述、书章 → 低；与问题无关 → 不相关。
   - **拿不准时往高评**：漏掉一篇相关文章的代价比多读一篇大得多。只有标题、但标题明确符合时也可以评高，理由里注明“仅凭标题”。
   - 用户定过的判定规则（如“某某路线算目标”）优先于上面的通用规则，并前后一致地用在所有批次上。
4. **保存**：`litloop_screening(action="save", question=..., criteria=[...], query=..., mode="quick"|"deep", items=[{doi, title, year, journal, journal_rank, cited_by_count, abstract_missing, retracted, concern, relevance, reason}, ...])`。同一课题的后续检索传 `session=` 合并进同一会话。
5. **呈现**：中文表格，列为 序号、相关度、文章、年份、期刊/分区、理由。**序号和顺序一律用 save 返回的 `numbering`**（保存时会按相关度重排），不要用自己发送时的顺序。`retracted` 标“⚠已撤稿”，`concern` 标“⚠关注声明”，`journal_warning` 标“⚠预警期刊”。不相关的文章也列出（可折叠在最后），**不替用户删除任何文章**。附上会话的 Markdown 文件路径。
6. **用户选择**：用户说“要 1、3、5”后调用 `litloop_screening(action="decide", session=..., selected=[...], rejected=[...], out_file=...)` 记录。每次 decide 记录的是**完整选择**，会覆盖上一次；用户追加或改选时传入全部选中项。把返回的 `chosen` 列表（序号 + 标题）念给用户核对，再按需要下载（`litloop_batch_download`）或推送 Zotero。

### 深度检索（要把一个课题查全时）

1. 标准确认后，请用户给 1–3 篇确定相关的种子文章（DOI）；没有时先用 `litloop_search` 找几篇请用户认。如果用户在 Zotero 里已经有这个课题的分类，用 `seed_collection="分类路径"`（如 `"1 陶瓷-金属复合材料/SiC/Al"`，也可以只写唯一的分类名）把其中有 DOI 的文献都当种子，可以和 `seeds` 一起用；返回的 `seed_collection` 报告用了几篇、几篇没有 DOI。分类较大时引用扩展会分几轮完成，额度上限照常生效。
2. `litloop_deep_search(action="start", question=..., queries=[4–8 组英文检索词], seeds=[DOI], core_terms=[1–3 个核心词], criteria=[...])`，返回第一批（默认 20 篇）和 `session`。**每个关键概念都要照顾缩写、全称、化学式和同义词**：很多文章只写缩写或化学式，或换一种说法。核心词里用 `|` 表示“任意一个”，例如 `PDC|polymer-derived|preceramic`、`EMW|electromagnetic|microwave`、`MMC|metal-matrix`、`3D-printing|additive-manufacturing`；检索词里也要有用缩写和用全称的各一组。**每条核心词是一个必须出现的概念，多条之间是“并且”**：`["lanthanide|rare-earth|europium|gadolinium", "drug|doxorubicin"]` 表示稀土并且药物；同一概念的不同说法用 `|` 写在同一条里，不要拆成两条。元素符号和普通单词撞车的（La、Ce、Er、Eu、In、As 等，检索不区分大小写）只写全称，开局返回的 `core_term_notes` 会提醒。英美拼写（aluminum/aluminium、fiber/fibre、-ize/-ise 等）、元素符号和名称（Al/aluminum）、用户术语表里的缩写和同义词由插件自动展开，不用写；返回的 `glossary` 列出这次展开了什么。**核心词要覆盖整个问题的范围，不要只写其中的重点**：问题是“先驱体陶瓷，尤其 SiBCN”时，核心词写 SiBCN 会把其他 PDC 体系挡在引用扩展之外；应写成 `SiBCN|SiCN|SiOC|polymer-derived|preceramic` 这类覆盖全题的写法，重点留给评分。用户给了必找文章时传 `must_find=[DOI]`，结果的 `coverage` 会报告每篇的状态。
3. 逐篇判断后用 `litloop_deep_search(action="rate", session=..., ratings=[{"n": 1, "relevance": "高", "reason": "..."}, ...])` 按编号保存，标题和 DOI 由插件补上。**这一批每篇都要评**，返回的 `not_rated` 列出漏评的编号；没评的下一批会再出现。
   只有在设置里把翻译服务选为 Agent 时，`rate` 的返回才会要求翻译：`next_step` 写明哪些评分要附 `abstract_zh`（中文摘要），漏掉的列在 `untranslated` 里，用 `litloop_screening(action="translate", session=..., items=[{"doi": ..., "abstract_zh": ...}])` 补上。没有要求时不要翻译（默认由 app 调用 DeepSeek / DeepL 翻译，不耗对话额度）。
4. `litloop_deep_search(action="next", session=...)` 取下一批。评为“高”的文章会自动成为新种子；从第二批起排序由模型根据全部评分学习（`ranked_by="model"`），所以“低 / 不相关”也要如实评。
5. 返回 `stop_suggested=true` 时，把 `stop_reason` 告诉用户并建议停止；用户要继续就接着 `next`。用户也可能在桌面 app 里自己评分并点「继续检索」生成了新的一批：**回到对话接着检索时先 `action="status"`**，返回里有 `unrated` 就按其中的编号用 `rate` 评完（用户在 app 里给的评分会保留），再 `next`。返回里的 `remaining_estimate` 是按每批高相关比例的下降趋势粗略外推的剩余数（`remaining` 约还有几篇高、`next_batch` 下一批约几篇），一并告诉用户供决定，但说明这是粗略估计；比例还在上升时没有 `remaining`，说明课题还没读到尽头。随时可以用 `action="status"` 看已筛篇数和各相关度数量。
6. 筛完后按上面第 5、6 步呈现和让用户选择。跨了多批之后编号会变，**decide 时优先传 DOI**。

## 场景 → 工具链(常见意图直接对号入座)

| 用户说 | 动作 |
|---|---|
| "下载这篇 <DOI/arXiv/文章页URL>" | `get <标识符>`;URL 直接喂,自动抽 DOI/arXiv;要补充材料加 `--si`,要 AI 可读全文加 `--md`(PDF 仍是默认交付物) |
| "某人的全部/近年论文" | `search --author "Name" --out queue.txt` → `batch queue.txt --lanes` |
| "某主题/关键词 + 年份/被引过滤" | `search "kw" --year-from 2023 --sort cited_by_count [--out queue.txt]` |
| "给一份清单(xlsx/csv/txt/bib/APA)" | `batch 文件 --lanes`(表格/队列自动识别;渠道按 DOI 前缀自动预测) |
| "上次有失败的,补齐" | `batch --retry <output>/batch_results.json`(自动读失败清单重跑) |
| "模糊引用('Wang 2023 CRISPR 那篇')" | 先 `search "Wang 2023 CRISPR"` 拿候选让用户确认,别硬猜 DOI |
| 系统性文献发现(PRSIMA/引文追链/高召回多源检索) | 装了 `scansci-find` skill/CLI → 用它;没装 → 本地降级链 `search → verify → resolve-oa → build-queue → batch --lanes`(Find 系 MCP 工具需要可选的 scansci-find CLI) |
| "帮我找某课题的文献/筛一筛" | 按上面“检索与筛选”流程：定标准 → `litloop_search` → 逐篇给相关度和理由 → `litloop_screening` 保存，用户挑选后 `decide` |
| "放进 Zotero" | `litloop_zotero_push`（经 zotero-mcp；授权本地写入后直接写进本机 Zotero，同步交给 Zotero） |
| "只要合法来源" | `legal_only` 策略或 `--scihub` 反选 |

队列文件格式(机器可读,人也能手编):`identifier<TAB>channel<TAB>oa_url`,channel ∈ oa/elsevier/grey/institution/auto;`search --out` 与 csv/xlsx 解析自动打标(10.1016→elsevier)。`batch --lanes` 按车道调度:Elsevier API/OA 快车道并行 HTTP → 灰色源竞速 → 机构级联串行,失败逐级溢流。

## 机构渠道(按 DOI 前缀路由,先快后慢)

1. **`10.1016`(Elsevier)→ Elsevier API**:key + 校园网 IP 即可,**无需 insttoken**,1–2 s/篇(需机构桶里常占一半以上)。
   ```bash
   litloop elsevier-setup --api-key YOUR_KEY --validate
   ```
2. **`10.1007`(Springer)→ Springer TDM API**(`litloop_springer_setup`):机构订阅+TDM 授权的 key(dev.springernature.com 注册,ORCID 关联机构),交付 **JATS XML 全文**(无 PDF 端点),1–2 s/篇。`test=true` 用已知付费文章探测权限:`entitled`=通,`not_entitled`=key 有效但机构无订阅/TDM 权限(此时走 WebVPN/CARSI),`invalid_key`=重生成。竞速引擎与车道模式都已接入;无 key 时该车道零成本让位。
3. **其余出版商 → WebVPN/CARSI**:`litloop schools 清华` → `setup 清华大学` → `login`(浏览器 CAS,cookie 自动保存,勿让用户手动复制)→ 正常 `get`。CARSI:`config-cmd carsi_idp_name <学校>` + `federated-login elsevier`。卡登录页 = session 过期,重新 login。

From dysprosium231/litloop-paper-agent, Apache-2.0.

More from dysprosium231/litloop-paper-agent