name: literature-skill description: | 学术文献一站式工具。主命令 /literature-skill，子命令作为参数传入：

/literature-skill -paper <DOI/URL> → 做全套：下载 PDF + 生成 QR 码 + 提取元数据 + 添加到 Zotero + 挂载附件。
/literature-skill -pdf <DOI/关键词> → 查找已下载的 PDF 文件路径，通过微信/Telegram 发送文件。
/literature-skill -qr <DOI> → 根据 DOI 生成 QR 码图片（指向 https://doi.org/xxx）。
/literature-skill -zot <DOI/URL> → 只加进 Zotero：提取元数据 + 创建条目 + 挂载 PDF（不触发下载）。
/literature-skill -people <Scholar_URL> → 批量下载某人全部论文 + 结构化文献消化报告。也支持从图片（PPT 拍照、截图）提取引用再走上述流程。触发词："extract citations from image", "这个图里的文献", "图片引用"。自然语言同义词也会触发："download paper", "get PDF", "fetch paper", "下载论文", "抓取论文", "批量下载" 走下载路径；"add to zotero", "save paper", "import paper", "收藏论文" 走 Zotero 路径；"二维码", "QR code" 走 QR 路径。 allowed-tools: Bash(uv:), Bash(python:), Bash(node:*)

CLI 命令

# === 注册（不下载 PDF）===
python -m lit scholar <URL>           # 抓取 Scholar → 批量注册 Zotero
python -m lit import <DOI/URL>        # 单篇注册 Zotero（DOI / URL / 图片 OCR）
python -m lit import <image_path>     # 图片 OCR → 注册 Zotero

# === 快速下载（多源链：Crossref TDM → Preprint → Unpaywall → Sci-Hub，秒级）===
python -m lit quick <DOI>             # 单篇：查缺口 → 多源快下（TDM/Preprint/Unpaywall/Sci-Hub）→ 挂载
python -m lit quick <collection>      # 批量：遍历 collection 缺 PDF 的条目
python -m lit quick <collection> --limit 5

# === Publisher adapter 兜底（分钟级，覆盖 Sci-Hub 拿不到的）===
python -m lit attach <DOI>            # 单篇：查缺口 → 出版商页面下载 → 挂载
python -m lit attach <collection>     # 批量
python -m lit attach <collection> --limit 5

# === 停止批量下载 ===
python -m lit stop                    # 优雅停止当前批量任务（sentinel file，当前论文完成后退出）
python -m lit stop --force            # 强杀整个进程树（taskkill /F /T，含 Edge 子进程）

# === 查找本地 PDF ===
python -m lit pdf <DOI>               # 查本地 PDF 路径（不下载）

# === 其他 ===
python -m lit digest <collection>     # 首次生成消化模板（全量）
# 增量更新 digest 不用命令——agent 读已有 digest.md → diff Zotero → 手术式更新
python -m lit parse <pdf> [--item-key <key>]  # MinerU 解析 PDF → Markdown
python -m lit maintain [--collection X] [--fix]  # 文件库健康检查
python -m lit qr <DOI>               # 生成 QR 码
python -m lit discover-s2 <author> [--save|--download]  # S2 profile 发现 + 全量审计
python -m lit track <author> [--download]  # 检测作者新论文（增量）
python -m lit build-affiliations <author> [--save] [--sample N]  # 构建年度 affiliation 数据库

旧版入口（people.py, zot.py, main.py）已弃用，代码保留兼容。

下载架构（两层）

PDF 下载是两个独立命令，agent 按需编排：

| 层 | 命令 | 原理 | 速度 | 覆盖率 | |----|------|------|------|--------| | 快速通道 | lit quick | 多源链：Crossref TDM → Preprint → Unpaywall → Sci-Hub native（4 源逐个尝试） | 秒级~10s/篇 | 70-95%（取决于领域/年份；TDM 加入后远高于早期 ~50%） || 兜底通道 | lit attach | 27 个出版商适配器，CDP 导航到出版商页面，机构登录态下载 | 分钟级 | 几乎全覆盖 |

两层都先检查本地是否已有 PDF（resolve_local_pdf），已有则跳过。

规则

把当前 SKILL.md 所在目录视为 <skill-base>。所有本地资源从 <skill-base> 解析，不依赖调用方工作目录。
Zotero 是唯一数据源。不再使用 papers.json 中间文件。所有状态读自 Zotero API。
Zotero 同步方式：config.yaml 的 zotero.sync_method 控制附件挂载方式。webdav（推荐）：JSON API 建条目 + 本地拷文件，不消耗 Zotero 云配额。cloud：API multipart 上传（走配额）。详见 references/webdav-setup.md。
DOI 是稳定 key：始终用 DOI 查找 Zotero 条目，不信任本地缓存的 key。
lit.core.zotero.check_duplicate() 内置去重：按 DOI/URL/title 搜索，已存在则返回现有 key。
Chromium 启动：推荐手动启动（有机构登录状态，--remote-debugging-port=19222）。lit attach 默认用 CDP 连接。
Elsevier 论文额外依赖 Foxit Reader（Print to PDF 虚拟打印机）。
Python 依赖：playwright, pyautogui, requests, pyyaml, rich, pyzotero。首次使用运行 <skill-base>/setup.bat。
支持的出版商由 <skill-base>/url_parser.py 的 PUBLISHER_PATTERNS 自动匹配。
下载失败时，先查 <skill-base>/error_log.md 该出版商的条目。深度调试读 references/architecture.md。
OCR DOI 和 CrossRef 匹配都不可全信。检查 crossref_score：<30 时匹配不可信。
Sci-Hub CAPTCHA 熔断：批量下载时 Sci-Hub 镜像可能连续 CAPTCHA 被拉黑（2/5 mirrors dead → 基本废了）。此时在 lit/download/quick_download.py 注释掉 try_scihub import 和 _METHODS 条目，等 IP 冷却（数小时~一天）后再恢复。quick 链即使没有 Sci-Hub 仍有 Crossref TDM + Unpaywall 两个有效源。
SPIE adapter 已修复（2026-06-29）：citation_pdf_url meta 标签返回 HTML interstitial 非 PDF。改用 /Proceedings/Download?urlId={DOI_URL_ENCODED} 直链。已从 _PUBLISHER_BLACKLIST 移除。注意：部分 SPIE 会议论文（如 PC12855 2024）只有视频演示无 PDF，应移出 collection。
has_pdf_attachment() 在 WebDAV 模式下不可靠：imported_file 附件不走 Zotero API 的标准 attachment 标记，会误报所有论文缺 PDF。批量查缺口一律用 resolve_local_pdf(doi) 做文件系统级检查（collect_missing() 已用此方法）。手动检查缺口也用它。
SPIE 在 _PUBLISHER_BLACKLIST 中：engine.py 的 _PUBLISHER_BLACKLIST 包含 "spie"（标记为 paywall）。如需尝试 SPIE 下载，需临时移除黑名单条目。SPIE adapter 代码存在（publisher/spie.py），用 citation_pdf_url meta 标签定位 PDF。
_PUBLISHER_BLACKLIST 静默跳过：engine.py 有 _PUBLISHER_BLACKLIST = {"spie"}，被列入的出版商 adapter 根本不执行，输出只有 ✗ Publisher: no PDF，没有错误日志。排查 "no PDF" 但 error_log.md 无条目时，第一时间查这个集合。SPIE（10.1117/ 会议论文）是最常见的静默跳过源。要解除：注释掉黑名单条目 + 用 CDP recording 录一遍手动下载确认选择器。
has_pdf_attachment 不可信：WebDAV 本地存储模式下 has_pdf_attachment() 可能误报（ghost 附件）。collect_missing() 内部用 resolve_local_pdf() 做磁盘检查才是准确的。手动排查缺口也用 resolve_local_pdf(doi)。
Sci-Hub 模块已迁移：scihub_cdp.py（Playwright CDP + 多方法下载链）已废弃，现由 scihub_native.py 替代（page.goto 直连，无 fetch/JS 注入）。_METHODS 中函数名仍为 try_scihub。
Publisher 黑名单：engine.py 的 _PUBLISHER_BLACKLIST 含 "spie"（paywall HTML interstitial）。SPIE 论文（10.1117/12.* 会议论文）即使有 adapter 也不会执行下载。批量下载发现 SPIE 缺口时，需手动处理或临时移除黑名单条目测试。

工作流程

判定任务类型

| 用户意图 | 命令编排 | |---------|---------| | "下载这篇论文" | lit import <DOI> → lit quick <DOI> → lit attach <DOI> | | "只加进 Zotero" | lit import <DOI> | | "帮我填满这个库的 PDF" | lit quick <collection> → lit attach <collection> | | 收集某学者所有论文 | lit scholar <URL> → 清洗 → lit quick → lit attach → lit digest | | 追踪新论文 | lit discover-s2 <author> --save → lit track <author> → lit build-affiliations <author> --save → 汇报轨迹 + 主动索要 bio page 手动补缺（详见 references/tracking-architecture.md） | | 降噪清理 collection | debug/collection_audit.py（OpenAlex 逐篇审计）→ debug/remove_from_collections.py（移除假阳性，item 留库）→ 用户在 Unfiled 复查 | | "更新 digest" | 读已有 digest.md → diff Zotero 找新论文 → 逐篇深读 → 手术式更新（详见 references/digest-workflow.md） | | "精读这篇论文" | lit parse <pdf> → 深读全文 → paper digest（详见 references/paper-digest-workflow.md） | | 图片 OCR 导入 | lit import <image_path> → lit quick <DOI> → lit attach <DOI> | | "读读吸收一下" | 加入 Zotero → 提炼可执行改进（见下方原则），不是输出思想总结 |

下载编排（Agent 责任）

内容吸收 ≠ 思想总结

当用户分享文章/综述让你"读一读、吸收一下"时，不要只输出思想总结和要点概括。用户自己会读原文——他需要的是 agent 从外部视角提炼的增量价值：

从"这能怎么改进我们现有的工具和流程"角度提炼可执行操作
每条建议必须具体到：改哪个文件的哪个部分、新增什么字段/规则/步骤
区分"值得现在动手"和"记到 draft 以后看"
用户筛选后，agent 立即执行获批的改动（增量 append，保持原有信息）

教训（2026-06-25）：AI4Research 综述分享后，agent 先输出了纯思想总结（六层架构、核心论点），被用户纠正"别光总结思想，想一想可以提炼出哪些可执行操作的"。

三个命令各做一件事，agent 按场景编排：

单篇论文（最常见的场景）

lit import <DOI>     # 注册到 Zotero
lit quick <DOI>      # 快速尝试 Sci-Hub（秒级）
lit attach <DOI>     # 兜底（如果 quick 没拿到）

Agent 默认连续执行 quick → attach。quick 成功则跳过 attach（attach 内部会检查已有 PDF）。

覆盖率实测（2026-06-26 Garth Simpson, 170 篇缺口）：quick 单层拿到 160 篇（94%），attach 兜底再拿 8 篇，最终 168/170 = 98.8%。quick 的主要命中源是 Crossref TDM（许多 ACS/RSC论文有 TDM link），Sci-Hub CDP 作为末位兜底。领域为化学/物理非线性光学，年份 1995-2026。

批量填满（条目已在 Zotero，只差 PDF）

lit quick <collection>    # 先快速批量
lit attach <collection>   # 再兜底批量

仅注册（不下载）

lit import <DOI>          # 只注册

下载排查 & 适配器

排查修复

先查 error_log.md。运行时错误（超时/导航）→ 检查 Chrome；页面结构变化 → 读 references/maintain.md 流程 A；"Access denied" 但有订阅 → 查 error_log 中 check_access 误报条目。

添加新出版商

读 references/maintain.md 流程 B 完整执行
必须用 Playwright CDP 探测页面，不能只靠 DevTools
创建适配器后注册到 lit/download/adapters/__init__.py + url_parser.py + engine.py 的 _ADAPTERS
常见 bug：find_download_url(self, page) 签名不能多参数；OA 出版商必须覆盖 check_access() 返回 True（JCI Insight、bioRxiv）；url_parser.py 正则用 \\. 转义 dot

人机合作流程（大型学者）

分阶段执行，人在中间清洗数据：

Phase 1：Agent — 建文件夹 + 注册条目

python -m lit scholar "SCHOLAR_URL"

Phase 2：用户手动清洗数据

在 Zotero People/<学者名> 文件夹中修元数据、删不相关、去重、补遗漏。

Phase 3：Agent — 补 PDF + 解析 + 消化

python -m lit quick "学者名"              # 批量快速下载（TDM/Unpaywall/Sci-Hub）
python -m lit attach "学者名"             # 批量 publisher adapter 兜底
python -m lit parse <pdf> --item-key <key>  # 解析 PDF
python -m lit digest "学者名"             # 生成消化报告

为什么不一把走完？

Scholar 数据很脏（截断作者名、专利/会议混入、重复），人机合作把清洗放中间，agent 只负责机械重复的工作。

Phase 2 补充：SI DOI 清洗（Agent 可在注册后自动做）

Scholar→CrossRef 匹配经常给论文配上补充材料 DOI（.s001, .s012 等），这些 DOI 指向 SI 文件不是正文，下载永远失败且污染去重。

清洗逻辑（注册后、下载前执行）：

扫 collection 找 DOI 匹配 \.s\d{2,3}$ 的条目
去掉后缀得到 base DOI
如果 base DOI 已在 collection 中（正式版已注册）→ 删除 SI 条目（重复）
如果 base DOI 不在但 CrossRef 验证有效 → 修改 DOI 为 base DOI（去掉后缀）
如果 base DOI 在 CrossRef 也无效 → 删除条目

实测（Zhiwei Huang, 235 篇）：11 个 SI DOI，其中 6 个 base 已存在（删 SI 条目），3 个 base 有效（改 DOI），2 个 base 重复（删多余条目）。

批量下载的启动与停止

启动批量下载（agent 用 Hermes terminal(background=true)）：

python -m lit quick "学者名"     # 或 lit attach

停止批量下载 — 必须用 lit stop，不要用 Hermes process kill：

python -m lit stop              # 优雅：创建 .batch.stop sentinel file
python -m lit stop --force      # 强杀：taskkill /F /T（含 Edge 子进程）

为什么不能用 process kill：Hermes process kill 只杀 tee 管道进程，Python 子进程（python -m lit attach）变成孤儿继续运行，还会通过 engine.py 的 CDP auto-launch 逻辑自动拉起 Edge。lit stop 用 sentinel file 机制让批量循环在当前论文完成后干净退出，并自动清理 PID 文件。

Windows 注意：os.kill(pid, SIGTERM) 在 Windows 上等于 TerminateProcess()（=kill -9），不走信号处理器。sentinel file 是可靠的优雅停止路径。Ctrl+C 在前台终端仍然有效（SIGINT handler）。

旧版命令（兼容）

PYTHONIOENCODING=utf-8 python "main.py" "URL"           # 下载
PYTHONIOENCODING=utf-8 python "zot.py" "URL"            # Zotero
PYTHONIOENCODING=utf-8 python "people.py" "URL"         # 学者
PYTHONIOENCODING=utf-8 python "pdf_parser.py" "path"    # 解析

支持的出版商（27 家）

| 出版商 | 域名 | |--------|------| | AAAS (Science) | science.org | | ACS Publications | pubs.acs.org | | AIP (Silverchair) | pubs.aip.org | | Annual Reviews | annualreviews.org | | APS (Physical Review) | journals.aps.org | | bioRxiv / medRxiv | biorxiv.org, medrxiv.org | | BMJ | bmj.com | | eLife | elifesciences.org | | Elsevier (ScienceDirect) | sciencedirect.com | | Frontiers | frontiersin.org | | IEEE | ieeexplore.ieee.org | | IOP Publishing | iopscience.iop.org | | JCI Insight | insight.jci.org | | LWW (Lippincott) | journals.lww.com | | MDPI | mdpi.com | | Nature Publishing Group | nature.com | | Optica (OSA) | opg.optica.org | | PNAS | pnas.org | | PMC | ncbi.nlm.nih.gov | | Royal Society | royalsocietypublishing.org | | RSC | pubs.rsc.org | | SAGE | journals.sagepub.com | | SPIE | spiedigitallibrary.org | | Springer / SpringerLink | springer.com, link.springer.com | | Taylor & Francis | tandfonline.com | | Wiley | onlinelibrary.wiley.com | | 物理学报 | wulixb.iphy.ac.cn |

参考文档

| 文档 | 内容 | |------|------| | references/architecture.md | 代码架构、lit/ 包结构、适配器详解 | | references/legacy.md | 旧版入口参考（已弃用）| | references/maintain.md | 添加/修复 publisher 流程模板 | | references/cron-automation.md | 批量下载 cron 格式规范 + 模板（创建 cron 前必读） | | references/people-guide.md | 人机合作流程详细说明 | | references/digest-workflow.md | Scholar digest 填充方法论 + 增量消化工作流 | | references/paper-digest-workflow.md | Paper digest 单篇精读工作流 | | references/webdav-setup.md | WebDAV 配置说明 | | references/mineru-api.md | MinerU PDF 解析 API 说明 | | references/tracking-architecture.md | S2+CrossRef+OpenAlex 论文追踪系统：discover-s2, track, build-affiliations (OpenAlex), 置信度分层, collection 审计与降噪, Zotero 重合率验证 | | references/openalex-exploration.md | OpenAlex vs S2 API 对比 + PoC（作者级 institution 数据，潜在第三数据源） | | references/s2-discovery.md | DOI 反查法发现 S2 profile（含 Unicode 连字符归一化） | | references/s2-batch-registration.md | S2 DOI → CrossRef 元数据 → Zotero 批量注册 | | references/scihub-mirrors.md | Sci-Hub 多镜像轮转 + captcha 熔断 + 4 方法下载链 | | references/local-sqlite-lookup.md | 本地 SQLite DOI 查找（避免 API 延迟） | | references/import-architecture.md | import 管线：CrossRef → Zotero item 创建 | | references/doi-index.md | DOI 索引缓存机制 | | references/storage-file-gap.md | 存储路径解析 + PDF 缺口检测 | | references/oa-sources.md | 开放获取 PDF 源列表 | | references/zotero-batch-optimization.md | Zotero 批量操作优化 | | references/zotero-storage-audit.md | Zotero 存储空间审计 | | references/merge-notes.md | Scholar 合并/去重笔记 |

开发模式

单目录开发（2026-06-25 起）：此 skill 目录（prod skill dir）就是唯一工作目录。remote origin → GitHub。

# 改完代码/文档后：
cd <this-skill-dir>
git add -A && git commit -m "描述" && git push origin main

不需要 dev/prod sync。GitHub 做备份。旧 dev repo (OneDrive/Hermes_workspace/Literature_skill) 已废弃归档。

skill_manage 使用注意

skill_manage 写入的文件（SKILL.md patches、references/ 新文档）直接落在此目录。改完后记得 git add && commit && push，否则是 untracked 文件，git clean -fd 会删。

历史教训：18 个 reference 文档曾同时只存在于 untracked，因为之前的 session 用 skill_manage 写 prod 但从不 commit。单目录模式后不再有此问题——只要记得 commit。

Outil de littérature académique

Recommandé pour