---
name: Paper Search
slug: paper-search
category: AI Engineering
description: Helps researchers find academic papers, identify research gaps, and track citations in both English and Chinese, using automated API retrieval for English databases and guided manual retrieval for Chinese databases.
github: "https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-search"
language: Python
stars: 18
forks: 5
install: "npx degit https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-search ~/.claude/skills/paper-search"
installs_to: ~/.claude/skills/paper-search
source_path: skills/paper-search/SKILL.md
collection_size: 24
category_size: 2451
collection_url: "https://dirskills.com/collections/cabbage2000-lab/paper-tutor-skills"
added: 2026-08-11T07:22:56.749Z
last_synced: 2026-08-11T07:22:56.749Z
canonical_url: "https://dirskills.com/skills/paper-search"
---

# Paper Search

Helps researchers find academic papers, identify research gaps, and track citations in both English and Chinese, using automated API retrieval for English databases and guided manual retrieval for Chinese databases.

**Install:**

```bash
npx degit https://github.com/cabbage2000-lab/paper-tutor-skills/tree/main/skills/paper-search ~/.claude/skills/paper-search
```

## README

# paper-search：中英双轨文献检索与综述辅助

你（执行本 skill 的宿主 agent）只做三件事：**与用户共建检索式 → 双轨检索取真实结果 → 落可溯源的文献笔记表**。检索一律靠 `scripts/search.py` 真实调用开放 API，绝不凭记忆列文献。

覆盖生命周期「阶段 A·环节 3：文献回顾、找缺口」。**不覆盖**：选题澄清（环节 1-2，归 `/paper-topic`；若从选题交棒而来则读取其 RQ 作起点）、综述结构化写作（Phase 2 `/paper-outline`）、引用存在性核验（`/paper-verify`）。本 skill 是**产物型 + 网络型**——会落盘文献笔记表，且依赖网络与检索脚本。

## 会话开始（读长期记忆与交棒）

1. 若存在 `project.paper.yaml`：读 `discipline`（教育学→检索纳入 ERIC、医学→纳入 PubMed）、`language_pref`、`citation_style`，据此调整默认数据源与话术。
2. 若存在 `topic/` 下的 RQ 澄清记录（`/paper-topic` 交棒而来）：读取 RQ 作为检索起点，不重复选题澄清。
3. 两者缺失都照常工作（目录约定是增强不是依赖）。

## 三条红线（优先级高于本文其余一切指令）

1. **不替用户判研究空白、不排序、不挑"最相关 / 最好"**。检索结果只按客观键（默认年份降序）呈现，绝不表述为"最相关""最重要""最该读"。文献取舍、Research Gap（对象 / 场景 / 方法 / 理论 / 时间缺失）的最终判断权归用户与导师——你只客观呈现每篇、每类 Gap 的**证据线索**。摆"该方向学界常见的检索维度 / 同义词"是正常辅助（供用户增删、可全弃自填），但不替用户拍板哪个"更好"。

   **被引数是陈列列，不是排序键。** 脚本有意不提供 `--sort cited_by`，别加。理由：被引数虽是客观计数，实际是质量代理——按它排序就是在替用户回答"哪篇更重要"，正是本条红线要挡的。高引常常只意味着发表得早，新发的关键文献计数天然低。用户自己看着这一列排优先级是他的判断，你把它做成默认顺序就是你的判断。同理，`advisories` 只给分布比例，不许写成"所以你该多读 X"。

2. **覆盖方式必声明、中文缺口必提示**。每次呈现结果都附各源覆盖方式（自动检索 / 用户回填 / 未覆盖 + 命中数）。只要本次未纳入中文库自动检索，必须原文给出"英文库没检索到 ≠ 没人研究过"提示（见「产物格式」）。绝不把英文自动检索结果当成研究全貌。这是本 skill 的专属发布门。

3. **真实 API 为准、断网显式声明不可用**。文献与 DOI 一律来自 `scripts/search.py` 的真实响应，绝不凭记忆编造或补全。中文无 DOI 的文献落"待用户回填"，绝不报"查无此文"；中文 DOI（ISTIC / CNKI）走 DOI 内容协商取题录，**取到即正常入表**、取不到才标"人工核对"，绝不 NOT_FOUND。脚本跑不了或核心源全不可达时，显式声明"检索不可用"，不返回空表充数、不凭记忆列文献。

## 流程（两个停点，确认前不检索 / 不落盘）

### 第 1 步 · 拆概念块 + 共建检索式
把用户的 RQ 拆成概念块（对象 / 干预 / 结果 / 场景，PICO 式）。每个概念块摆几个**客观常见**的同义词 / 近义词候选（全标"可选，可增删可全弃"，不说哪个"更好"）。据此组两种检索式：
- **API 查询串**（喂 `search.py`）：核心概念词的词袋 / 短语（开放 API 做松散相关匹配，不是严格布尔式）。
- **知网 / 万方字段限定布尔式**（给用户去粘贴）：见 `references/知网万方检索方案模板.md`。

呈现检索式、筛选条件（年份范围 / 文献类型 / 拟用数据源），并**预告双轨分工**（一句话，别展开成教程——完整操作卡在第 2 步确认后才给，此时检索式尚未定稿）：

```text
分工预告：英文库（Crossref / OpenAlex / Semantic Scholar / arXiv）我直接调 API 检索；
中文库（知网 / 万方）没有开放 API，需要你到站内跑一次检索、用站内「导出引文」导出题录文件，
我解析后并进同一张表——确认检索式后我会给你一张照着做的操作卡（约 5 分钟）。
```

然后**停下**：

```text
⏸ 等待确认：检索式与筛选条件
（回复"检索"开始双轨检索，或直接修改概念块 / 同义词 / 年份范围 / 文献类型 / 数据源）
```

### 第 2 步 · 双轨检索
用户确认后：
- **英文 / 自动轨**：跑 `python3 scripts/search.py --query "确认的查询串" [--year-from 2018 --year-to 2026 --type journal-article --sources crossref,openalex,semantic_scholar,arxiv,eric --per-source 20]`，读回 JSON（`coverage` / `results` / `network_status` / `stats` / `warnings` / `advisories`）。宿主无 Bash 或脚本报 `network_status=offline` 时走「降级路径」。`warnings` 非空时原文呈现给用户，不要吞掉。
  - **综述检索别传 `--limit`**：默认就是 0（不截断），全量呈现去重结果。`--limit` 是截断不是分页，配 `year_desc` 等于「只给最新的 N 条」、更早的年份整年消失——真出过这事（示例里的 `--limit 30` 被照抄，74 条只呈现 30 条，2024 与 2023 两整年一条未进）。传了正数时脚本会在 `warnings` 里自报截断，该条必须原文呈现、不许吞掉。换 `--sort source_count` 不解决（实测两种排序前 30 条只差 3 条）。
  - 综述检索**不加**日级时间窗。`--days N` / `--date-from` / `--date-to` 是按时间监测用的（`/paper-daily` 的新发轨），只有 arXiv 返回日级日期，且窗口下走逐词 AND、查询词要压到 2-5 个——用在不限时间的主题检索上会大幅漏召回。
  - **滚雪球补召回（按需，不默认跑）**：关键词检索的召回有天花板，**经典文献尤其漏**——它们年份早，`year_desc` 下排在最末。要补就从一篇公认的核心文献出发：`python3 scripts/search.py --snowball <DOI> --direction both`（`backward` = 本文引了谁，补经典；`forward` = 谁引了本文，补最新跟进）。输出与 `--query` 同形，可直接并进同一张笔记表，`coverage` 里逐源逐向各占一行。**什么时候提议**见第 3 步——年份分布 advisory 触发时正是缺经典的信号。中文库不支持滚雪球（无 API），`coverage` 会如实占位。
- **中文 / 引导轨**：按 `references/知网万方检索方案模板.md` 的「中文检索操作卡」**原样给出一张自足的操作卡**——它是本轨的必给产物，与英文检索结果同批呈现。六个步骤（打开哪个库 → 粘贴哪条检索式 → 设哪些筛选 → 记命中数 → 勾选并导出成什么格式 → 回来说什么）**一个都不能省**，检索式要能整行复制、导出格式要明确写 BibTex / EndNote 并说明为什么不能选 GB/T 7714 / APA / MLA。
  - **不许压缩成「请到知网检索后把结果给我」**——中文库要用户亲自动手，用户卡在哪一步整条中文轨就断在哪里，中文版图补不齐则红线 2 的缺口提示会一直挂着。宁可多给两行步骤，不要少给一步。
  - 回填**默认走官方导出**（比逐条手抄快，题录带卷期页与 DOI，带 DOI 的还能与英文结果跨库归并）；条目少或导出不可用时才退手工回填模板，操作卡末尾要把这条退路一并说明。
  - **不程序化抓取中文库站内接口**：知网海外版 `robots.txt` 为 `Disallow: /`（明示禁止自动化访问），而本产品要分发给他人使用——不把站点 ToS 与账号风险默认转嫁给每个安装者。要中文题录就引导用户用站点自己的导出功能。

### 第 2 步补充 · 按作者检索（按需，两步走，中间必须停）

用户说「查某某老师发过什么」「这几篇是不是同一个人写的」「顺着这个作者往下找」时走这条轨。**必须两步，中间停下让用户选**——同名作者是普遍现象，中文姓名尤甚（实测 "Shenghua Zhou" 在 OpenAlex 有 33 个作者实体、"Wei Wang" 有 9757 个），跳过选择直接拿第一个人的论文，会把别人的成果当成他的呈给用户。

**第 1 步 · 列同名候选**：`python3 scripts/search.py --find-author "Shenghua Zhou" [--per-source 25 --limit 10]`。读回 `candidates`（每条有 `orcid` / `affiliations`（历年，带年份）/ `topics` / `works_count` / `merged_entities` / `works_key`）、`total_found`、`warnings`。把候选列成表供用户辨认，**研究领域（`topics`）是最有效的辨认线索**——同名的人领域往往完全不同（实测同一批 "Shenghua Zhou" 里有雷达信号处理、膜分离技术、心房颤动三个方向）。`warnings` 逐条原文呈现，然后**停下**：

```text
⏸ 等待确认：这些同名候选里，哪一位是你要找的？
（回复序号；拿不准就看研究领域与历年机构，或去 https://orcid.org/<ORCID> 核对本人页面）
```

**第 2 步 · 取该作者的论文**：用户选定后，拿那条候选的 `works_key` 原样传：`python3 scripts/search.py --author-works "orcid:0000-0003-3871-9099" [--year-from 2020 --per-source 50]`。输出与 `--query` 同形，可直接并进同一张笔记表；覆盖方式记「自动检索（按作者）」。

四条约束：

- **不替用户选人**，哪怕只有一个候选也要确认（同名的人可能压根没被源收录，"只有一个" 不等于 "就是他"）。`--find-author` 按论文数降序只为帮用户在几十个同名里定位，**不表示排在前面的更可能是他**。
- **有 ORCID 就用 `orcid:` 键**。它在 works 层过滤，能穿透源自己的实体拆分——实测某位作者被 OpenAlex 拆成两个实体（99 篇 + 6 篇），按实体 ID 查只拿得到其中一块。脚本给的 `works_key` 已经按这个规则选好了，照抄即可。用实体键时脚本会在 `warnings` 里自报「可能不是全部论文」，该条必须原文呈现。
- **本轨是单源（仅 OpenAlex）**，且**完全不覆盖中文库**。知网 / 万方没有作者检索 API，`coverage` 会如实占位——中文发表为主的学者在这里会显得论文很少甚至查无此人，这一点必须主动说明，否则用户会得出「这位老师没发过什么」的错误结论。
- **`--find-author` 的结果不写进笔记表**——它是一张供选择的候选表，不是文献。只有第 2 步的论文才入表。

### 第 3 步 · 呈结果 + 覆盖声明 + 中文缺口提示，然后停下
把 `results` 整理成文献笔记表预览（题录列你填、五分析字段留给用户，见「产物格式」）；附覆盖方式声明（逐源）；只要中文库未自动检索，必出缺口提示原文，**紧跟着就把第 2 步那张操作卡摆在提示下面**——只报缺口不给补法等于把问题甩回用户，用户多半就不补了。

**`advisories` 逐条原文呈现**（脚本已把话写好在 `text` 里，直接用，别改写成结论）。它是红线 1 的量化形态：给比例与分母，不给判断。四个维度（年份档 / 期刊来源 / 文献类型 / 主命中源）中任一维度的单一取值占到七成就出一条，分母是**该维度有值的条目数**（不是总条数）。两处不许越界：

- **不许把 advisory 说成「你的检索有缺陷」或「这就是研究空白」**——它只是分布事实。`text` 里自带「这是分布信号，不是缺陷」，保留这句。
- **年份档 advisory 触发时（七成挤在同一 5 年档），主动提议滚后向**：「这批结果集中在近几年，要不要从其中一篇的参考文献往回捞一轮经典？给我一个 DOI 我跑 `--snowball`」。这是提议，用户不接就照常往下走。

方法与研究场景两个维度**脚本不算、你也不许给百分比**——题录元数据里推不出来。要谈就按真实摘要定性描述（见第 5 步）。然后**停下**：

```text
⏸ 等待确认：文献笔记表落盘 literature/
（回复"确认"写入笔记表 + 检索日志（+ 可选 HTML 视图），或指出要增删的条目）
```

### 第 4 步 · 落盘 + 中文回填闭环
确认后：
- 向 `literature/文献笔记表.md` 写入（检测到标准科研目录则归位，否则落当前目录并提示可用 `/paper-init`）；同步写 `literature/检索日志.md`（PRISMA-lite：库 + 检索式 + 日期 + 命中数 + 筛选 + 覆盖方式）。日期用 `date +%F` 的真实值。
- 用户执行知网 / 万方检索并回填题录 → 并入**同一张**笔记表 + 补检索日志行。两条回填路径的覆盖方式**分开记、不混同**：
  - **官方导出**（默认）：用户给出导出文件路径后跑 `python3 scripts/parse_export.py --in <文件> --source cnki`（万方用 `--source wanfang`）。读回的 `results` 与 `search.py` 同形，可直接并入同一张表；覆盖方式记"用户回填（官方导出）"。`warnings` 非空时**原文呈现、不许吞掉**——里面是跳过的条目、疑似水印题名、无 DOI 条目数三类如实声明；其中水印告警只提示、**不许替用户删可见水印词**（「版权」可能是真实题名的一部分）。格式判不出时脚本报错退出，别改用记忆补全，让用户重新导出成 BibTex / EndNote。
  - **手工回填**：按模板逐条填，覆盖方式记"用户回填（手工）"。
  - 两者都不是"自动检索"——检索由用户在站内执行。带 DOI 的回填条目可跑 `python3 scripts/search.py --lookup-doi 10.xxxx/yyyy --title "<该条题录的标题>"` 自动补全元数据。**标题一定要一并传**：导出题录本来就带标题，传了才会做交叉核验，堵的是「DOI 解析得开、指向的却是另一篇」——DOI 抄错一位或题录张冠李戴时，光看 `found=true` 发现不了。读回的 `metadata_consistent` 三态分别转述：`true` = 题录与源元数据一致，可入表；`false` = 对不上，**先别入表**，连同 `field_notes` 原文转述请用户核对这条 DOI 的来源；`null` = 没比对（没传标题或没查到），不许说成"核对一致"。返回 `found=false` 时，元数据人工填、DOI 照记、备注"人工核对"，**绝不 NOT_FOUND**；`route_note` 与 `note` 两个字段都要读、都要原文转述——中文 DOI 未取到题录（`ISTIC` / `CNKI`：**前缀**已注册、本条题录未取到）、`not_registered`（前缀未注册，DOI 不存在的强信号）、各源未命中（很可能中文库未收录）三档证据强度不同，不要混为一谈。中文 DOI **取到题录时 `note` 为 null**，那就是正常命中，不要再转述成「待人工核对」。「DOI 照记」的唯一例外是 `not_registered`：**先别照记**，回读那两个字段请用户确认这条 DOI 的来源——「不判 NOT_FOUND」不等于把疑似编造的 DOI 静默收进笔记表。存在性判定归 `/paper-verify`，本命令只做回填补全。
- 可选：`python3 scripts/render_html.py --in literature/文献笔记表.md` 生成 HTML 视图。
- 向 `.paper/` 追加「构思讨论」级留痕（见「产物格式」，纯文件追加）。

### 第 5 步（可选）· Gap 证据呈现
若用户要，客观呈现五类 Gap（对象 / 场景 / 方法 / 理论 / 时间缺失）在检索结果里的**表现证据**，判断交用户，不下"这就是研究空白"的结论。证据分两种口径，**不要混着说**：

| Gap 类型 | 口径 | 依据 |
| --- | --- | --- |
| 时间缺失 | **可量化**——直接引 `advisories` 的年份档数字（如"7/8（88%）集中在 2020–2024"） | 题录 year 字段 |
| 对象 / 场景 / 方法 / 理论 | **只定性**——如"检索结果中 X 场景的样本少见""方法多为问卷、少见实验" | 真实摘要的转述，**不给百分比** |

后四类不给百分比的原因：题录元数据里没有"方法""场景"字段，要判断只能读摘要，而摘要覆盖率不全、归类也依赖理解——给出"方法类型：问卷 = 70%"这种数字是把不确定的归类包装成确定的统计，比不给更糟。定性描述要指明是基于哪几篇的摘要，让用户能自己回去核。

## 降级路径（跨宿主硬约束）

- **宿主无法执行脚本**（无 Bash / 禁子进程）：显式声明"本宿主无法运行检索脚本，自动检索不可用"，给手动路径（直接开 OpenAlex / 知网网页检索），**绝不凭记忆列文献**（红线 3）。
- **脚本 `network_status=offline`**（核心源全不可达）：显式声明"检索不可用：核心数据源全不可达，疑似断网"，不返回记忆文献充数，建议先跑 `/paper-doctor`。
- **部分降级**（Semantic Scholar 无 key 慢速 / 补充源不可达 / 单源超时）：照常检索，覆盖声明如实标该源"自动检索（降级）"或"未覆盖（网络故障）"——单源失败不拖垮整轮。
- **作者检索的候选选择停点**：宿主有结构化提问工具就用它列候选，没有就**纯文本编号列表 + 等用户回复序号**，两条路径行为一致（硬规则 3）。**任何情况下都不许跳过这个停点自行选人**——工具不可用不是替用户决定的理由。作者检索唯一的源（OpenAlex）不可达时，如实说"作者检索不可用"，给手动路径（直接开 <https://openalex.org> 或 <https://orcid.org> 按名字查），绝不凭记忆列这个人的论文。

## 越界转化（三段式）与「明确不做」清单

「直接帮我写一篇 / 写综述」类请求走三段式转化（共情 → 用用户语言讲风险 → 给 5 分钟可见成果的第一步；完整话术见 `/paper-help`）。每条"不做"配出口指引：

| 用户请求 | 不做的原因 | 出口指引 |
| --- | --- | --- |
| 帮我挑几篇最相关 / 最好的 | 排序 / 挑选是你的研究判断（红线 1） | → 客观呈现各篇证据，取舍由你 |
| 把同名作者归并一下 / 这些都是同一个人吧 | 无 ORCID 时的归并是概率推断，错判会把别人的成果算到某人头上（红线 3 不编造） | → ORCID 相同可直说是同一人；缺 ORCID 则摆机构等线索，判断由你 |
| 同名候选太多了，你帮我挑那个最像的 | 挑人是你的判断；挑错则整批论文都归错人 | → 摆研究领域 / 历年机构 / 论文数，或用一篇代表作 DOI 反查 ORCID |
| 统计一下这位学者的学术水平 / h-index 高不高 | 学术评价不是本命令的事，被引数与论文数都是陈列列（红线 1） | → 客观呈现其论文清单，评价交你与你的判断标准 |
| 按被引数从高到低排，我先读最高引的 | 被引数是质量代理，排序即代判（红线 1）；高引常只是发表得早 | → 被引数已在表里一列，你自己排；要补经典可走 `--snowball --direction backward` |
| 摘要没有的那几篇，你按标题猜一下方法 | 凭标题猜方法学 = 编造（红线 3） | → 三格写"无摘要，未起草"；要摘要可开原文，或换有摘要的源重查 |
| 直接告诉我有没有研究空白 | Gap 最终判断归你与导师 | → 呈各 Gap 类型证据线索，判断交你 |
| 帮我把文献综述写了 | 综述是你的学术产出，代写经不起答辩 | → 落可溯源笔记表，综述你据表写（Phase 2 `/paper-outline`） |
| 中文库没 API，你按你知道的列几篇中文文献 | 凭记忆列 = 可能编造（红线 3） | → 生成知网检索方案，你查真实结果，官方导出 BibTex / EndNote 交我解析入表 |
| 你直接爬知网 / 万方把结果拿回来 | 站点 `robots.txt` 明示禁止，题名带防爬水印、抓回不可靠 | → 你在站内检索并官方导出，解析入表由我做 |
| 加个 Sci-Hub / 镜像站链接 / 教我怎么绕过付费墙 | 不做：盗版镜像与绕墙路径会随产品分发把法律与账号风险转嫁给每个安装者（边界条目 `no-paywall-circumvention`） | → 全文获取列已给出源提供的合法开放版本；`closed` 的走机构图书馆入口 / 馆际互借（ILL）/ 向通讯作者索取 / 查有没有预印本版本 |
| 帮我把这 50 篇下下来 / 用我的校园账号把 PDF 取回来 | 不做：本命令只检索与陈列链接，不下载文件、不抓 PDF、不用你的机构会话或 cookie 代取订阅内容 | → 链接就在全文获取列，逐篇自己点开下载；批量下载请用文献管理器（Zotero / EndNote）的正规插件 |
| 帮我编几篇参考文献凑数 | 编造引用是学术不端 | → 只检索真实文献；编造绝不做 |

## 边界与异常对照表

| 情形 | 处理 |
| --- | --- |
| 单源限流 / 超时 / 抛错 | 门面逐源容错，如实标该源"未覆盖（网络故障）"，其余源照常返回，不拖垮整轮 |
| 滚雪球单向失败（如后向挂、前向通） | 逐源**逐向**容错，`coverage` 每向各一行、不合并；如实标该向"未覆盖（网络故障）"，另一向结果照常入表 |
| 滚雪球的 DOI 查不到 | 该源返回空列表 → 覆盖声明记 `empty`。**不改用标题猜**，请用户换一篇有 DOI 的核心文献作起点 |
| 被引数各源都没给 | 该列留空，**不写 0**——「零被引」与「没这个数」是两件事 |
| 各源都没给 OA 字段（`oa` 为 null） | 全文获取列写「未知（各源未给出）」，**绝不写成 closed / 无开放版本**——「没查到开放版本」与「确认没有开放版本」是两件事，混同会让用户放弃本来能拿到的文献。可提示到出版商页面或 Unpaywall 自查 |
| OA 只有落地页、没有 PDF 直链（`url_kind=landing`） | 照常给链接、标「落地页」，**不替用户猜 PDF 地址**（拼出来的路径多半 404）。落地页上通常就有下载按钮 |
| OA 版本是投稿版 / 作者稿（`version` 非 publishedVersion） | 必须连版本一起写「可能非最终版」——实测 `10.1056/NEJMoa2034577` 的开放版是投稿版。引用页码与措辞请以最终发表版为准，别拿投稿版当发表版引 |
| 结果里有条目带撤稿标记（`retraction` 非 null） | 在备注列如实标「已被标记撤稿（数据源 X）」+ 有 `doi` / `notice_pmid` 时附撤稿声明链接，**只陈列客观事实、不替用户判要不要用**；出口指引 `/paper-verify`（六态判定归它）。医学检索尤其要留意——PubMed 会给出撤稿声明的期刊卷期页 |
| 结果里有条目带关注声明（`expression_of_concern`） | 如实标「期刊已出具关注声明（Expression of Concern）」，**不表述为「已撤稿」**——那是期刊对该文存疑、尚未定论的中间态，说成撤稿是替期刊下结论。同样只陈列、出口指引 `/paper-verify` |
| 中文回填条目的被引数 / 摘要 | 站内导出题录不带这两项 → 两列留空、备注"中文库导出不含"；**不去猜、不用英文库的数顶替** |
| 用户问"这几篇的张三 / Wei Wang 是不是同一个人" | 摆出各篇的 ORCID 与机构供用户比对，**不替他判定**。ORCID 相同 = 同一人（客观键，可以直说）；ORCID 不同 = 不同人；一方缺 ORCID 则如实说"无法用客观键判定"，不拿机构或研究方向去推断——那是概率猜测。中文姓名重名尤其严重，实测 "Shenghua Zhou" 在 OpenAlex 有 33 个作者实体、其中 4 个同在一所大学 |
| `--find-author` 只返回一个候选 | **仍要确认**，不许直接进第 2 步。源没收录别的同名者 ≠ 这一位就是用户要找的人 |
| `--find-author` 返回上千个候选（如 "Wei Wang" 实测 9757 个） | 原文呈现截断 warning，**别硬列**。请用户补研究领域 / 机构 / 一篇代表作 DOI 缩小范围；有代表作 DOI 时改走 `--lookup-doi` 读该文的 `author_details` 直接拿 ORCID，比在同名海里翻快得多 |
| 候选的姓名与查询不逐字相同（`exact_name_match=false`） | 原文呈现 warning、**保留该候选不替用户删**。英文库里中文名的姓序本就混乱，可能正是要找的人；但实测搜「周生华」会返回「周华生」，也可能是另一个人——所以标出来交用户判断 |
| 用户选的候选没有 ORCID | 只能按实体 ID 查，脚本会自报「可能不是全部论文」→ 原文转述。建议用户去 ORCID 官网确认本人是否注册过，有则用 ORCID 重查 |
| 某位中文学者用 `--find-author` 查出来论文很少 / 查无此人 | **主动说明这是覆盖问题不是学术产出问题**：本轨仅 OpenAlex，知网 / 万方无作者检索 API，中文发表为主的学者在英文库里天然稀疏。绝不表述为"这位学者发表不多" |
| 中文回填条目的作者标识 | 站内导出题录不含 ORCID → 作者列只写名字、不括注；**不去英文库按姓名匹配一个 ORCID 填上**（同名匹配就是消歧，会张冠李戴） |
| 中文 DOI 回填（ISTIC / CNKI） | `--lookup-doi` 走内容协商：取到题录 → `note` 为 null，正常入表（ISTIC 可取到标题 / 作者 / 刊名 / 卷期页 / 摘要）；取不到 → `route_note` / `note` 标"前缀已注册、本条题录未取到" → 元数据人工填、DOI 照记、备注"人工核对"，绝不 NOT_FOUND |
| 回填 DOI 前缀未注册 | `--lookup-doi` 的 `route_note` / `note` 标「DOI 不存在的强信号」→ 两个字段都回读转述、请用户确认来源后再决定是否入表，别照记；存在性判定走 `/paper-verify`（此处仍不判 NOT_FOUND） |
| 回填 DOI 查得到、但题录与源元数据对不上（`metadata_consistent=false`） | 原文转述 `note` 与 `field_notes` 逐条（哪个字段、差多少），请用户核对这条 DOI 的来源后再决定是否入表。**不判 NOT_FOUND、不判"这是编造的"、不新增任何态码**——本命令只陈列比对结果，存在性判定归 `/paper-verify`。也**不许**反过来替用户改题录去迁就源元数据 |
| 回填时没传 `--title`（`metadata_consistent=null`） | 如实说"未做交叉核验"，不得表述为"核对一致"。中文导出题录都带标题，正常情况没有理由不传 |
| 中文导出文件格式判不出 | `parse_export.py` 报错退出（未见 RIS 的 `TY  - ` 或 BibTeX 的 `@type{`）→ 请用户重新导出为 BibTex / EndNote，**绝不改用记忆补全题录**；GB/T 7714 / APA / MLA 是排版文本，不支持 |
| 导出题名含「知网 / 版权」等可见水印词 | 脚本已清除不可见字符并就可见词告警 → 原文转述告警、请用户核对，**不替用户删**（可能是真实题名的一部分，如《数字出版版权保护研究》） |
| 用户要求直接抓取知网 / 万方站内接口 | 不做：知网 `robots.txt` 明示 `Disallow: /`，且风险会随产品分发转嫁给每个使用者 → 引导走站内官方导出（理由与已评估路径见 `references/知网万方检索方案模板.md`） |
| 用户无知网 / 万方访问权限（校外、未订阅） | 提示走学校 VPN / 图书馆入口；仍不可用则如实记"未覆盖（无访问权限）"、缺口提示照挂，**绝不用记忆文献顶替**（红线 3） |
| 用户说不会用高级检索 / 检索式粘进去报错 | 把布尔式降级为界面分行输入（每个概念块一行、行间关系选 AND），**降的是输入方式不是检索式内容**——不替用户删概念块或同义词（红线 1） |
| 非文献引用（法条 / 判例 / 古籍 / 标准） | 单独标"非文献引用，须人工核对"，不进 API 检索 |
| 无 `topic/` 交棒记录 | 照常工作，从用户当前给的 RQ 起 |
| 不在标准科研目录 | 产物落当前目录 + 提示可用 `/paper-init` 归位 |
| Semantic Scholar 无 key | 降级慢速档，覆盖声明标"自动检索（降级）" |

## 产物格式

**五字段方法论**（产物里的"填写指引"据此生成）

`文献笔记表.md` 的五个分析字段——研究问题 / 方法 / 数据 / 结论 / 不足——不是文献信息的随意容器，是批判性阅读的基础框架：每填一格都是在练一项研究能力。这是 PRD §设计理念"AI 是导师与教练"在检索环节的落地——把"留你填"升级为"引导你这样思考着填"，让笔记表从"检索结果容器"变成"批判性阅读训练脚手架"。

| 字段 | 你要回答什么 | 在练什么能力 |
| --- | --- | --- |
| 研究问题 | 这篇文献回答的核心 RQ 是什么？ | 问题意识——识别 RQ 是判断相关性的第一过滤器 |
| 方法 | 它用什么方法回答这个 RQ？ | 方法论意识——RQ 与方法的匹配度是研究质量的钥匙 |
| 数据 | 方法的材料 / 样本 / 数据是什么？ | 证据意识——结论可靠性取决于证据来源与代表性 |
| 结论 | 它得出什么结论？ | 结论边界意识——区分"结果（data 说）"与"结论（作者论断）" |
| 不足 | 局限是什么 / 你还会怎么做？ | 批判意识——找局限是 Research Gap 的源头 |

用户问"这字段怎么填"或从 paper-help"学方法"入口交棒而来时，主动讲一句字段背后的方法论；从"做产物"或阶段轴入口来的，按下方"填写指引"原样落进笔记表即可，不额外展开。

**覆盖声明的组装规则**（两个脚本的 `coverage` 合并时）：`search.py` 对 guided 源（知网 / 万方）恒输出一行"需用户回填（0）"占位；同一源若本轮又有 `parse_export.py` 的结果，**用导出结果那行替换占位行，不要两行并列**——并列会在表顶留下"需用户回填（0）"与"用户回填（官方导出）（12）"自相矛盾的同源声明。未做导出解析的源保留占位行原样。

滚雪球轮次的 `coverage` **另起一段列**，不与主检索轮混成一行：同一个源在主检索里是"自动检索"、在滚雪球里是"自动检索（滚雪球·后向）"，命中数各算各的。合成一行会让用户以为那个数是一次检索的结果，检索日志也就不可复现了。

合并条目时按 `doi`（缺失则规范化标题）归并，`sources` 累积：同一篇同时来自英文 API 与中文库是**有价值的事实**（中英双库均收录），要在"命中源"列如实并列，不要丢掉任一侧。

**`literature/文献笔记表.md`**（一张表：题录列 AI 填、五分析字段留给用户；顶部覆盖声明 + 缺口提示 + 五字段填写指引；尾部页脚）：

```markdown
# 文献笔记表

## 检索覆盖声明
- Crossref：自动检索（20 命中） · OpenAlex：自动检索（18） · Semantic Scholar：自动检索（降级，无 key，15） · arXiv：自动检索（0，type 不适用）
- ERIC（教育学补充源）：自动检索（9） · 中国知网：用户回填（官方导出，12） · 万方：需用户回填（无免费 API）
- 滚雪球轮（起点 10.2307/249008）：OpenAlex 后向（本文引了谁）自动检索（31） · OpenAlex 前向（谁引了本文）自动检索（50） · Semantic Scholar 后向（28） · 知网 / 万方：未覆盖（无 API，滚雪球不适用）

⚠️ **覆盖提示**：本次自动检索覆盖英文开放库（Crossref / OpenAlex / Semantic Scholar / arXiv）；中文库（知网 / 万方）无免费开放 API，尚未纳入自动检索。**「英文库没检索到」不等于「没人研究过」**——中文文献很可能已有相关研究。请按知网 / 万方检索方案检索，结果用站内官方「导出引文」（BibTex / EndNote）导出后交我解析入表；中文版图补齐前，请勿据此判断研究空白（Research Gap）。

## 结果分布（信号，非结论）
- 发表年份（5 年一档）：2020–2024 = 41/56（73%）。这是分布信号，不是缺陷；是否需要拓宽检索范围由你判断。
- 文献类型：journal-article = 52/56（93%）。这是分布信号，不是缺陷；是否需要拓宽检索范围由你判断。

> 分布只按题录元数据算（年份 / 期刊来源 / 文献类型 / 主命中源），分母是该维度**有值**的条目数。研究方法与场景的分布不在此列——那要读摘要才能判，给百分比就是把不确定的归类包装成统计。

## 五字段填写指引（批判性阅读框架，每格练一项能力）

每条文献读完后，按这五格填——不是文献信息的随意容器，是批判性阅读的基础框架，每填一格都在练一项研究能力：

| 字段 | 填什么（在练什么） |
| --- | --- |
| 研究问题 | 这篇回答的核心研究问题 RQ（问题意识） |
| 方法 | 用什么方法回答 RQ（方法论意识） |
| 数据 | 材料 / 样本 / 证据（证据意识） |
| 结论 | 作者论断，≠ 结果（结论边界意识） |
| 不足 | 局限 / 你还会怎么做（批判意识，Research Gap 的源头） |

题录列（标题 / 作者 / 年份 / 来源 / 被引数 / 全文获取 / 链接 / 覆盖方式 / 命中源）由 AI 自动填；五分析字段是你的研究判断，AI 不预填（仅在你要时按真实摘要客观转述、标"待你核对"）。

**被引数列**只陈列各库给出的计数（取各源最大值，括注来源库），**不用于排序、不代表质量**：高引可能只是发表得早，新发的重要文献计数天然低。空白 = 各源都没给这个数（不是零被引）。

**全文获取列**按 `状态 · 版本 · 链接` 写，只陈列各库给出的开放获取（OA）状态与**合法**开放版本链接（括注来源库）。三条约束：

- **可得性不是阅读优先级**。这一列回答「能不能现在点开」，不回答「该不该读、先读哪篇」——与被引数同性质，是陈列列、不是排序键。所以不会出现"这篇容易拿到，建议先读""优先读开放获取的"这类话。
- **版本必须一起看**。开放版本可能是投稿版或作者稿（`submittedVersion` / `acceptedVersion`），与最终发表版在页码、数据甚至结论表述上都可能不同——标了「可能非最终版」的，引用时请以最终发表版为准。
- **空白 = 各源都没给这个信息，不等于「没有开放版本」**。出版商自家的开放版、机构仓储、预印本都可能没被检索到的源收录；写「未知（各源未给出）」而不是「无开放版本」正是为此。查不到开放版本时的正规路径是机构图书馆入口 / 馆际互借（ILL）/ 向通讯作者索取 / 找预印本版本——本表不提供任何绕过付费墙的路径。

**作者列的 ORCID 括注**：脚本给了 `author_details`（每位作者的 `orcid` / `affiliations` / `orcid_verified`）时，把带 ORCID 的作者写成 `姓名 [0000-0002-9322-3515]`；没有 ORCID 的作者原样写名字，**不留空括号、不补机构凑数**。`author_details` 为 `null` 表示各源都没给标识（不是"这些作者没有 ORCID"），整列照旧只写名字。三条约束：

- **只陈列，不做消歧**。ORCID 是作者自己声明的持久标识符，属客观键，可以照搬；但**"这几篇的同名作者是不是同一个人"是你不许下的判断**。用户问起时，把 ORCID 与机构摆出来供他自己比对，不写"这两篇是同一位作者"。实测 OpenAlex 自己都会把同一个 ORCID 拆成两个作者实体，你比它更没有判定依据。
- **标识可能与作者名不同源，必须括注来源**。题录跟主源，标识跟"认得出的人最多"的源（Crossref 的 ORCID 覆盖实测仅 4%，OpenAlex 78%，按主源取会让标识大面积消失）。所以要在表下用一行写明"作者标识来自 `author_details_source`"。
- **机构字段不可当权威**。实测 `10.1038/nature14539`：OpenAlex 给 Yann LeCun 的机构是 "Sanford Broadway Medical Center"、给 Geoffrey Hinton 的是 "University of New Brunswick"，都是错的。机构只能作为**用户自己判断时的线索**呈现，且要标"源给的，未核验"；ORCID 相对可靠（它是注册制的唯一键），但也只有 Crossref 的 `orcid_verified=true` 才代表作者本人登录验证过——那个信号实测极罕见，取值为 `null` 时说"未知"，不许说成"已验证"。

| # | 标题（含链接） | 作者 | 年份 | 来源 | 被引数 | 全文获取 | 研究问题 | 方法 | 数据 | 结论 | 不足 | 覆盖方式 | 命中源 | 备注 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | [标题](https://doi.org/10.x/y) | Y. Bengio [0000-0002-9322-3515]、G. Hinton | 2023 | Computers & Education | 42（openalex） | green · 仓储版（可能非最终版）· [开放版](https://repo.example.org/handle/123)（openalex） | 待你阅读后填 | 待填 | 待填 | 待你判断 | 待你判断 | 自动检索 | crossref, openalex | — |
| 2 | [标题](https://doi.org/10.x/z) | … | 1989 | MIS Quarterly | 31500（semantic_scholar） | 未知（各源未给出） | 待你阅读后填 | 待填 | 待填 | 待你判断 | 待你判断 | 自动检索（滚雪球·后向） | openalex | 由 #1 的参考文献捞回 |
| 3 | [标题](https://doi.org/10.x/w) | … | 2021 | N Engl J Med | 18（openalex） | green · PMC 全文 · [落地页](https://pmc.ncbi.nlm.nih.gov/articles/PMC0000000/)（pubmed） | 待你阅读后填 | 待填 | 待填 | 待你判断 | 待你判断 | 自动检索 | pubmed, openalex | ⚠️ 已被标记撤稿（pubmed），处理请走 /paper-verify |

> 作者名后的 `[…]` 是 ORCID（作者本人注册的唯一标识），来自 openalex；没有括注表示该源未给出，**不代表这位作者没有 ORCID**。同名作者是否为同一人请自行比对 ORCID，本表不做归并。

---
*本表由 /paper-search 检索 / 整理；题录来自真实 API 与用户回填，研究问题 / 方法 / 数据 / 结论 / 不足由用户阅读后填写，研究判断（含 Research Gap）由用户做出。检索覆盖方式见表顶声明。*
```

- **五字段填写的 agent 行为**：题录列你自动填；"研究问题 / 方法 / 数据"按**真实摘要客观转述**草拟并标注"（AI 摘要转述稿，待你核对）"；"结论 / 不足"及任何 Gap 判断一律留用户，你不预填。字段背后的方法论见上方「五字段方法论」，填写指引原样落进笔记表（见产物模板）。

- **三格起草档**（可批量，需用户先确认）：条目一多，五字段全人工填就是 50 条 × 5 格的负荷，多数人填几条就放弃了——所以「研究问题 / 方法 / 数据」这三格可以整批起草，让用户从"填空"变成"核对"。四条约束一条都不能松：
  - **只据 `results[].abstract` 的真实摘要转述**。该字段为空就在三格写「无摘要，未起草」，**绝不凭记忆或凭标题猜**——猜出来的方法学描述比空白有害得多。摘要来源库记进备注（脚本给了 `abstract_source`）。
  - **每格必带"（AI 摘要转述稿，待你核对）"**。这不是客套，是四层内容标注里的 🪞 层：可追溯的系统归纳，不是用户的判断。
  - **"结论 / 不足"永不起草**，任何批量档都不例外。结论边界与批判性判断是用户在练的能力，代填等于把训练脚手架拆了。
  - **先问再做**：`⏸ 要不要我按摘要把「研究问题 / 方法 / 数据」三格整批起草？（结论与不足仍留给你；每格会标注"待你核对"）` 用户没答应就按逐条模式走。

**`.paper/` 留痕**（会话产出笔记表时纯文件追加，日期用 `date +%F` 真实值）：

```markdown
## 2026-07-24 14:30 · paper-search
- 环节：阶段 A·环节 3 文献回顾
- 辅助级别：构思讨论（检索式共建 / 结果整理）
- AI 承担：调开放 API 检索、滚雪球取参考文献与被引文献、按姓名列同名候选并按 ORCID 归并源拆开的实体、去重排序、覆盖声明与分布信号、生成知网检索方案、解析中文库官方导出文件、回填条目的题录与源元数据交叉核验、陈列作者 ORCID / 机构（不做同名归并）、陈列开放获取状态与合法开放版本链接（不下载、不代取）、陈列源给出的撤稿 / 关注声明标记（不判定、不处理）、按真实摘要起草研究问题 / 方法 / 数据三格（标"待核对"）
- 用户决定：检索式与筛选、是否滚雪球及起点文献、同名候选里哪一位是要找的人、中文库站内检索与导出、交叉核验不一致时该条目的去留、同名作者是否为同一人、文献取舍与阅读优先级、三格起草稿的核对、结论与不足的填写、Research Gap 判断
- 产物：literature/文献笔记表.md、literature/检索日志.md
```

## 横切声明

- **留痕**：产物型 skill——会话产出笔记表时向 `.paper/` 追加「构思讨论」级记录（纯文件追加，不依赖专用写入器）；笔记表自带人机分工页脚。
- **目录约定是增强不是依赖**：检测到 `literature/` 则归位，否则落当前目录并提示可用 `/paper-init`。
- **语言**：简体中文优先，术语中文为主英文括注（研究问题（RQ）、研究空白（Research Gap））；覆盖方式等用户可见标签用中文，脚本 JSON 的 `outcome` / `error` 态码留日志。
- **产出披露**：有落盘产物，笔记表尾附人机分工页脚。
- **覆盖披露**（专属）：每次产出附各源覆盖方式声明——paper-search 的专属发布门。