search-lit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Literature Search Skill

文献检索 Skill

Every reference you produce must come from a live database result — never generate a citation from memory alone, because a recalled citation can look real and not exist.

每条你生成的参考文献都必须来自实时数据库检索结果——绝不能仅凭记忆生成引文，因为凭记忆回想出的引文可能看似真实，实际上却并不存在。

Search Tools: MCP (Primary) + E-utilities (Fallback)

检索工具：MCP（主要方式）+ E-utilities（备用方式）

Primary: MCP Tools (Claude.ai Remote)

主要方式：MCP 工具（Claude.ai Remote）

Database	MCP Tool	Purpose
PubMed	`mcp__claude_ai_PubMed__search_articles`	Search by query, MeSH terms
PubMed	`mcp__claude_ai_PubMed__get_article_metadata`	Full metadata for a PMID
PubMed	`mcp__claude_ai_PubMed__find_related_articles`	Related articles for a PMID
PubMed	`mcp__claude_ai_PubMed__lookup_article_by_citation`	Verify a citation
PubMed	`mcp__claude_ai_PubMed__convert_article_ids`	Convert between PMID/DOI/PMCID
Semantic Scholar	`mcp__claude_ai_Scholar_Gateway__semanticSearch`	Semantic search across all fields
bioRxiv/medRxiv	`mcp__claude_ai_bioRxiv__search_preprints`	Search preprint servers
bioRxiv/medRxiv	`mcp__claude_ai_bioRxiv__get_preprint`	Full preprint metadata
CrossRef	WebFetch with `https://api.crossref.org/works/{DOI}`	DOI verification

数据库	MCP 工具	用途
PubMed	`mcp__claude_ai_PubMed__search_articles`	按查询词、MeSH 术语检索
PubMed	`mcp__claude_ai_PubMed__get_article_metadata`	获取 PMID 对应的完整元数据
PubMed	`mcp__claude_ai_PubMed__find_related_articles`	查找与某个 PMID 相关的文章
PubMed	`mcp__claude_ai_PubMed__lookup_article_by_citation`	验证引文
PubMed	`mcp__claude_ai_PubMed__convert_article_ids`	在 PMID/DOI/PMCID 之间转换
Semantic Scholar	`mcp__claude_ai_Scholar_Gateway__semanticSearch`	在所有字段中进行语义检索
bioRxiv/medRxiv	`mcp__claude_ai_bioRxiv__search_preprints`	检索预印本服务器
bioRxiv/medRxiv	`mcp__claude_ai_bioRxiv__get_preprint`	获取完整的预印本元数据
CrossRef	使用 `WebFetch` 调用 `https://api.crossref.org/works/{DOI}`	验证 DOI

Fallback: NCBI E-utilities (Direct API via Bash)

备用方式：NCBI E-utilities（通过 Bash 直接调用 API）

If any

mcp__claude_ai_PubMed__*

call returns an error containing "terminated", "not found", "not available", or "not connected", switch ALL subsequent PubMed calls in this session to the bundled E-utilities scripts. Do not retry MCP after a disconnect — it will not recover within the same conversation.

bash

EUTILS="${CLAUDE_SKILL_DIR}/references/pubmed_eutils.sh"
PARSER="${CLAUDE_SKILL_DIR}/references/parse_pubmed.py"

如果任何

mcp__claude_ai_PubMed__*

调用返回包含

terminated

、

not found

、

not available

或

not connected

的错误，应将本次会话中后续所有 PubMed 调用切换至随附的 E-utilities 脚本。断开连接后不要重试 MCP，因为同一对话中它不会恢复。

bash

EUTILS="${CLAUDE_SKILL_DIR}/references/pubmed_eutils.sh"
PARSER="${CLAUDE_SKILL_DIR}/references/parse_pubmed.py"

Search PubMed (returns PMIDs)

bash "$EUTILS" search "diagnostic test accuracy meta-analysis radiology" 20
| python3 "$PARSER" esearch

Get article summaries as markdown table

bash "$EUTILS" fetch_json "16168343,16085191,31462531"
| python3 "$PARSER" esummary

Get detailed metadata

bash "$EUTILS" fetch "16168343"
| python3 "$PARSER" efetch

Generate BibTeX entries

bash "$EUTILS" fetch "16168343,16085191"
| python3 "$PARSER" bibtex

Verify a citation by exact title

bash "$EUTILS" cite_lookup "Bivariate analysis of sensitivity and specificity"
| python3 "$PARSER" esearch

Find related articles for a PMID

bash "$EUTILS" related "16168343" 10
| python3 "$PARSER" esummary


The script sleeps 350 ms between calls (NCBI allows 3 requests/s without an API key, 10/s with
`NCBI_API_KEY`); keep batch calls sequential.

| MCP Tool | E-utilities Command | Parser Mode |
|----------|-------------------|-------------|
| `search_articles` | `search <query> [retmax]` | `esearch` |
| `get_article_metadata` | `fetch <pmids>` | `efetch` or `bibtex` |
| `find_related_articles` | `related <pmid> [retmax]` | `esummary` |
| `lookup_article_by_citation` | `cite_lookup <title>` | `esearch` → `fetch` |
| `convert_article_ids` | Not available (use CrossRef DOI lookup) | — |

---

bash "$EUTILS" related "16168343" 10
| python3 "$PARSER" esummary


脚本在每次调用之间休眠 350 ms（未提供 API key 时，NCBI 允许每秒 3 次请求；提供 `NCBI_API_KEY` 时允许每秒 10 次）；批量调用应保持顺序执行。

| MCP 工具 | E-utilities 命令 | 解析器模式 |
|----------|-------------------|-------------|
| `search_articles` | `search <query> [retmax]` | `esearch` |
| `get_article_metadata` | `fetch <pmids>` | `efetch` 或 `bibtex` |
| `find_related_articles` | `related <pmid> [retmax]` | `esummary` |
| `lookup_article_by_citation` | `cite_lookup <title>` | `esearch` → `fetch` |
| `convert_article_ids` | 不可用（使用 CrossRef DOI 查询） | — |

---

Workflow

工作流

Phase 1: Search Strategy

阶段 1：检索策略

Get the research topic, question, or manuscript section that needs references.
Build the query from the key concepts (Population, Intervention/Exposure, Comparison, Outcome), with MeSH terms for PubMed:
```
(concept1 OR synonym1) AND (concept2 OR synonym2)
```
.
Set scope: date range (default: last 10 years unless the user specifies), article types, and language (default: English).
Present the Boolean query, databases, and filters to the user.

Gate: Wait for user approval before running searches.

获取需要参考文献的研究主题、问题或手稿章节。
根据关键概念构建检索式（人群 Population、干预/暴露 Intervention/Exposure、对照 Comparison、结果 Outcome），并为 PubMed 使用 MeSH 术语：
```
(concept1 OR synonym1) AND (concept2 OR synonym2)
```
。
设置范围：日期范围（默认最近 10 年，除非用户另有说明）、文章类型和语言（默认英语）。
向用户展示布尔检索式、数据库和筛选条件。

关卡： 运行检索前必须等待用户批准。

Phase 2: Execute Search

阶段 2：执行检索

Search PubMed (
```
search_articles
```
, Boolean query), Semantic Scholar (
```
semanticSearch
```
, natural language query), and bioRxiv/medRxiv (
```
search_preprints
```
) when preprints are relevant.
Deduplicate across databases by DOI or title similarity.
Present the results in this table, and write the same rows to
```
references/search_results.tsv
```
:

| # | Title | Authors (first + last) | Year | Journal | PMID/DOI | Relevance |
|---|-------|----------------------|------|---------|----------|-----------|
| 1 | ...   | Kim J, ... Lee S     | 2024 | Radiology | 12345678 | High      |

Ask the user to select which papers to include.

搜索 PubMed（
```
search_articles
```
，布尔检索式）、Semantic Scholar（
```
semanticSearch
```
，自然语言查询），并在预印本相关时搜索 bioRxiv/medRxiv（
```
search_preprints
```
）。
按 DOI 或标题相似度进行跨数据库去重。
按下表展示结果，并将相同的行写入
```
references/search_results.tsv
```
：

| # | Title | Authors (first + last) | Year | Journal | PMID/DOI | Relevance |
|---|-------|----------------------|------|---------|----------|-----------|
| 1 | ...   | Kim J, ... Lee S     | 2024 | Radiology | 12345678 | High      |

请用户选择要纳入的论文。

Record what the source said existed, not only what you downloaded

记录来源声称存在的数量，而不只记录下载到的数量

A wrong haul raises no error, and a PRISMA flow built on a wrong number is fiction that nothing downstream contradicts. Check both of these:

A count that equals a page cap exactly. Every source reports a total:
```
esearchresult.count
```
,
```
opensearch:totalResults
```
,
```
meta.count
```
. Record
api_total
beside
downloaded
, and fail loudly when
downloaded < api_total
, or when
downloaded
equals a page or loop cap exactly (e.g. a loop's own
```
if start >= 2000: break
```
reporting 2,000 records). Print
```
TRUNCATED
```
and refuse to write the search record.
A boolean that was never applied. OpenAlex's
```
search=
```
is a relevance-ranked free-text parameter that silently ignores AND/OR;
```
filter=title_and_abstract.search:
```
honours them. Run the query once more with one mandatory clause negated. If the hit count does not drop, the boolean is being ignored — the engine is ranking, not filtering.

PubMed via E-utilities is the one place where the naive pattern is safe. Everywhere else, do both.

错误的检索结果不会触发报错，而建立在错误数字之上的 PRISMA 流程图则是一种虚构，下游流程无从发现并纠正。必须检查以下两项：

数量恰好等于分页上限。 每个来源都会报告总数：
```
esearchresult.count
```
、
```
opensearch:totalResults
```
、
```
meta.count
```
。要在
downloaded
旁记录
api_total
；当
```
downloaded < api_total
```
，或
```
downloaded
```
恰好等于分页或循环上限时（例如循环自身的
```
if start >= 2000: break
```
报告了 2,000 条记录），必须明确报错。打印
```
TRUNCATED
```
并拒绝写入检索记录。
布尔条件从未生效。 OpenAlex 的
```
search=
```
是按相关性排序的自由文本参数，会静默忽略 AND/OR；
```
filter=title_and_abstract.search:
```
则会遵循这些布尔条件。再运行一次查询，并否定一个必需子句。如果命中数量没有下降，说明布尔条件被忽略——该引擎执行的是相关性排序，而不是筛选。

通过 E-utilities 访问 PubMed 是唯一可以安全采用上述朴素模式的地方。其他地方都要同时执行这两项检查。

A DOI in a screening row is not necessarily that row's DOI

筛选表中的 DOI 不一定就是该记录对应的 DOI

When the pipeline filled a

doi

column (matched against Crossref by title similarity) rather than receiving it with the record, a wrong match is a valid, resolvable DOI for a different paper. Resolve it and read the title back before any decision rests on it:

bash

python3 "${CLAUDE_SKILL_DIR}/scripts/check_doi_record_match.py" --table 2_Screening/round3.tsv \
        --email <contact> --json qc/doi_record_match.json

DOI_NOT_THIS_RECORD

is a DOI that resolves to another paper;

DOI_IS_CONTAINER

resolves to an issue, supplement or proceedings rather than an article;

DOI_IS_UPDATE_NOTICE

resolves to a correction, erratum or retraction notice (Crossref

update-to

) rather than to the article it updates;

DOI_UNRESOLVED

is reported rather than dropped. This runs at screening, where a wrong DOI is still cheap;

/verify-refs

audits a finished reference list.

当流水线通过标题相似度与 Crossref 匹配来填充

doi

列，而不是从记录中直接获得 DOI 时，错误匹配也可能是另一篇论文的有效且可解析 DOI。在任何决策依赖该 DOI 之前，应解析它并读回标题：

bash

python3 "${CLAUDE_SKILL_DIR}/scripts/check_doi_record_match.py" --table 2_Screening/round3.tsv \
        --email <contact> --json qc/doi_record_match.json

DOI_NOT_THIS_RECORD

表示 DOI 指向另一篇论文；

DOI_IS_CONTAINER

表示它指向期刊、增刊或会议论文集，而非具体文章；

DOI_IS_UPDATE_NOTICE

表示它指向更正、勘误或撤稿通知（Crossref

update-to

），而非被更新的文章；

DOI_UNRESOLVED

会被报告而不是丢弃。此检查应在筛选阶段运行，此时修复错误 DOI 的成本仍然较低；

/verify-refs

则用于审核已完成的参考文献列表。

Phase 2.5: Citation Searching (Snowballing)

阶段 2.5：引文检索（滚雪球式检索）

Optional; recommended for systematic reviews and thorough background work (PRISMA item 7, "records identified through citation searching"). Expand a seed set along the citation graph with the Semantic Scholar Graph API helper:

bash

python3 "${CLAUDE_SKILL_DIR}/references/snowball.py" \
  --seed DOI:10.1000/synthetic.example,PMID:00000000 \
  --direction all \
  --pool references/library.bib \
  --out references/library.bib

Directions:
```
backward
```
(references the seeds cite),
```
forward
```
(papers citing the seeds),
```
similar
```
(S2 recommendations), or
```
all
```
(default). Dedup is against the
```
--pool
```
and within the harvested set, by DOI and normalized title.
Trust flag: candidates are written
```
verified=false
```
+
```
verified_by=semantic_scholar
```
. Run
```
/verify-refs
```
(or Phase 4 verification) on each before citing it.
Output contract: appends to
```
references/library.bib
```
only; the script hard-refuses
```
manuscript/_src/refs.bib
```
.

PRISMA line: the script prints

Records identified through citation searching (snowballing): N raw (backward=…, forward=…, similar=…); after dedup against existing pool: M new candidates.

Record M in the PRISMA flow's citation-searching box.

Incomplete runs: when any seed/direction fetch fails, or the source says more records exist past
```
--limit
```
(a
```
next
```
page), the script prints a
```
FAILED
```
or
```
TRUNCATED
```
line per seed/direction, ends the PRISMA line with
```
INCOMPLETE
```
, and exits 1. Those counts are a lower bound. Do not record them; re-run (or raise
```
--limit
```
) until the run exits 0.

此项检索为可选操作；对于系统性综述和详尽的背景调研（PRISMA 第 7 项，“通过引文检索识别的记录”）建议使用。使用 Semantic Scholar Graph API 辅助工具沿引文图扩展种子文献集合：

bash

python3 "${CLAUDE_SKILL_DIR}/references/snowball.py" \
  --seed DOI:10.1000/synthetic.example,PMID:00000000 \
  --direction all \
  --pool references/library.bib \
  --out references/library.bib

方向：
```
backward
```
（种子文献引用的参考文献）、
```
forward
```
（引用种子文献的论文）、
```
similar
```
（S2 推荐）或
```
all
```
（默认）。按 DOI 和标准化标题，与
```
--pool
```
及已收集的集合进行去重。
信任标记：候选文献写入
```
verified=false
```
+
```
verified_by=semantic_scholar
```
。在引用每条候选文献前，先运行
```
/verify-refs
```
（或阶段 4 验证）。
输出约定：仅追加到
```
references/library.bib
```
；脚本会强制拒绝写入
```
manuscript/_src/refs.bib
```
。

PRISMA 行：脚本会打印

Records identified through citation searching (snowballing): N raw (backward=…, forward=…, similar=…); after dedup against existing pool: M new candidates.

将 M 记录在 PRISMA 流程图的引文检索框中。

运行不完整：如果任一种子或方向的获取失败，或者来源表明在
```
--limit
```
之后仍有更多记录（存在
```
next
```
页面），脚本会针对每个种子和方向打印
```
FAILED
```
或
```
TRUNCATED
```
行，在 PRISMA 行末尾添加
```
INCOMPLETE
```
，并以状态码 1 退出。这些计数只是下限。不要记录它们；重新运行（或提高
```
--limit
```
），直至脚本以状态码 0 退出。

Phase 3: Deep Read

阶段 3：深入阅读

For each selected paper, retrieve full metadata (

get_article_metadata

for PubMed,

get_preprint

for bioRxiv) and extract the study design, sample size/dataset, key methods, primary findings (with specific numbers), and the authors' stated limitations. For several papers, present a literature matrix for review:

| Paper | Design | N | Key Finding | Limitation | Relevance to Our Study |
|-------|--------|---|-------------|------------|----------------------|

对于每篇选定的论文，获取完整元数据（PubMed 使用

get_article_metadata

，bioRxiv 使用

get_preprint

），并提取研究设计、样本量/数据集、关键方法、主要发现（包含具体数字）以及作者明确陈述的局限性。对于多篇论文，展示文献矩阵以便审阅：

| Paper | Design | N | Key Finding | Limitation | Relevance to Our Study |
|-------|--------|---|-------------|------------|----------------------|

Phase 4: Citation Management

阶段 4：引用管理

Verification

验证

NEVER fabricate a DOI or PMID. If you cannot find one, mark the reference
```
[UNVERIFIED - NEEDS MANUAL CHECK]
```
.
Cross-check every reference against the API result: first and last author, publication year, journal, article title (exact, not paraphrased), and volume/pages when available. Flag each field that does not match.
Confirm each DOI resolves with WebFetch
```
https://api.crossref.org/works/{DOI}
```
(on CrossRef errors, follow Error Handling).

绝不捏造 DOI 或 PMID。 如果无法找到，应将参考文献标记为
```
[UNVERIFIED - NEEDS MANUAL CHECK]
```
。
将每条参考文献与 API 结果交叉核对：首作者和末作者、出版年份、期刊、文章标题（必须完全一致，不得改写），以及可用时的卷号和页码。标记每个不匹配的字段。
使用 WebFetch
```
https://api.crossref.org/works/{DOI}
```
确认每个 DOI 均可解析（遇到 CrossRef 错误时，按照错误处理部分执行）。

BibTeX Generation

BibTeX 生成

Generate an entry for every reference, verified or not, with an explicit

verified

flag:

bibtex

@article{FirstAuthorLastName_Year_ShortKey,
  author    = {Last1, First1 and Last2, First2 and Last3, First3},
  title     = {Full Title As Retrieved From Database},
  journal   = {Journal Name},
  year      = {2024},
  volume    = {310},
  number    = {2},
  pages     = {e234567},
  doi       = {10.1001/jama.2024.12345},
  pmid      = {12345678},
  verified  = {true},
  verified_by = {pubmed+crossref},
  verified_on = {2026-04-24},
}

`verified` (required on every entry)	Meaning
`true`	DOI or PMID confirmed via PubMed/CrossRef; title, authors, year all match
`false`	Parsed from text, but the API lookup failed or returned a mismatch; the manuscript MUST show `[UNVERIFIED - NEEDS MANUAL CHECK]`
`manual`	User explicitly added it despite the lookup failure; still unverified

verified_by

lists the confirming sources (

pubmed

crossref

semantic_scholar

, or a combination);

verified_on

is the ISO date of the most recent successful verification. No downstream script reads these fields —

/verify-refs

re-checks every entry — so they record trust rather than grant it.

BibTeX key convention:

FirstAuthorLastName_Year_OneWord

(e.g.,

Kim_2024_Validation

). The key is provisional: Better BibTeX assigns the citable key when

/lit-sync

imports the entry into Zotero.

为每条参考文献生成条目，无论其是否已验证，并明确设置

verified

标记：

bibtex

@article{FirstAuthorLastName_Year_ShortKey,
  author    = {Last1, First1 and Last2, First2 and Last3, First3},
  title     = {Full Title As Retrieved From Database},
  journal   = {Journal Name},
  year      = {2024},
  volume    = {310},
  number    = {2},
  pages     = {e234567},
  doi       = {10.1001/jama.2024.12345},
  pmid      = {12345678},
  verified  = {true},
  verified_by = {pubmed+crossref},
  verified_on = {2026-04-24},
}

`verified` （每条条目必填）	含义
`true`	DOI 或 PMID 已通过 PubMed/CrossRef 确认，且标题、作者和年份全部匹配
`false`	从文本中解析而来，但 API 查询失败或返回不匹配；手稿必须显示 `[UNVERIFIED - NEEDS MANUAL CHECK]`
`manual`	用户在查询失败后明确添加；仍未验证

verified_by

列出确认来源（

pubmed

、

crossref

、

semantic_scholar

，或这些来源的组合）；

verified_on

是最近一次成功验证的 ISO 日期。没有下游脚本会读取这些字段——

/verify-refs

会重新检查每个条目——因此它们只是记录信任状态，并不能赋予信任。

BibTeX 键命名约定：

FirstAuthorLastName_Year_OneWord

（例如

Kim_2024_Validation

）。该键为临时键；当

/lit-sync

将条目导入 Zotero 时，由 Better BibTeX 分配可引用键。

Output

输出

Append the entries to
```
references/library.bib
```
(do not overwrite) — the candidate pool
```
/lit-sync
```
imports into Zotero. NEVER write to
```
manuscript/_src/refs.bib
```
, because
```
/lit-sync
```
(via Better BibTeX) is its sole writer.
Print a summary with verification status:

Verified:    12 references (verified=true)
Unverified:   1 reference  (verified=false) [NEEDS MANUAL CHECK]
Total:       13 references

将条目追加到
```
references/library.bib
```
（不要覆盖）——这是
```
/lit-sync
```
导入 Zotero 的候选池。绝不写入
```
manuscript/_src/refs.bib
```
，因为该文件只能由
```
/lit-sync
```
（通过 Better BibTeX）写入。
打印带有验证状态的摘要：

Verified:    12 references (verified=true)
Unverified:   1 reference  (verified=false) [NEEDS MANUAL CHECK]
Total:       13 references

Phase 4b: Zotero Library Integration

阶段 4b：Zotero 库集成

Importing into Zotero belongs to

/lit-sync

, which owns Zotero writes and

references/zotero_collection.json

: hand it

references/library.bib

. If a Zotero MCP server is connected, you may read from it here —

zotero_search_items

(by DOI) to mark candidates already in the library,

zotero_get_annotations

to reference the user's prior reading notes.

导入 Zotero 属于

/lit-sync

的职责范围，该命令负责 Zotero 写入以及

references/zotero_collection.json

：将

references/library.bib

交给它即可。如果已连接 Zotero MCP server，可以在此处从中读取数据——使用

zotero_search_items

（按 DOI）标记库中已有的候选项，使用

zotero_get_annotations

引用用户先前的阅读笔记。

Phase 5: Full-Text Retrieval

阶段 5：全文获取

Delegate to

/fulltext-retrieval

, the single home of the open-access cascade; do not re-implement OA fetching here. Pass the verified candidate DOIs from

references/library.bib

bash

ENGINE="${CLAUDE_SKILL_DIR}/../fulltext-retrieval/fetch_oa.py"

将任务委托给

/fulltext-retrieval

，由它统一处理开放获取（OA）级联流程；不要在此重新实现 OA 获取逻辑。传入来自

references/library.bib

的已验证候选 DOI：

bash

ENGINE="${CLAUDE_SKILL_DIR}/../fulltext-retrieval/fetch_oa.py"

extract DOI + Title (and PMID/FirstAuthor when available) → worklist.tsv

python3 "$ENGINE" worklist.tsv -o pdfs/ -e <contact-email> --report pdfs/retrieval_report.json


Put the verified bibliographic title in the worklist rather than a DOI-only list. Keep
`source_identity` and `file_sha256` from the retrieval report with the record. Download success and
title agreement alone do not verify the PDF: inspect conflicts, unresolved/unavailable evidence, and
files whose hashes have changed before citing them. Missing identity fields in older reports mean
unassessed; even `consistent` is advisory front-matter corroboration, not verification of the
paper's claims.

For Zotero-resident PDFs and proxy-aware retrieval, use `/lit-sync` Phase 2.7. For DOIs in
`pdfs/manual_needed.txt`, use only institutional access (your library's own subscriptions, proxy or
VPN), interlibrary loan, or the corresponding author. Never bypass paywalls or publisher access
controls, and do not configure unauthorized PDF mirrors.

python3 "$ENGINE" worklist.tsv -o pdfs/ -e <contact-email> --report pdfs/retrieval_report.json


在 worklist 中放入已验证的文献标题，而不只是 DOI 列表。保留获取报告中的 `source_identity` 和 `file_sha256`，并与记录一同保存。下载成功且标题一致并不足以验证 PDF：引用前应检查冲突、未解决或不可用的证据，以及哈希已变化的文件。旧报告缺少身份字段意味着尚未评估；即使状态为 `consistent`，它也只是首页信息的辅助佐证，而不是对论文论点的验证。

对于 Zotero 中已有的 PDF 和需要代理支持的获取，请使用 `/lit-sync` 阶段 2.7。对于 `pdfs/manual_needed.txt` 中的 DOI，只能使用机构访问权限（所在图书馆的订阅、代理或 VPN）、馆际互借或通讯作者提供的方式。绝不绕过付费墙或出版商访问控制，也不要配置未经授权的 PDF 镜像。

Phase 6: Gap Analysis

阶段 6：差距分析

When called during manuscript writing, extract the manuscript's inline citations, compare them with the search results, and report specific gaps: key papers not cited, outdated references with newer versions, and missing methodological references (statistical methods, reporting guidelines).

在手稿写作过程中调用时，提取手稿中的文内引用，与检索结果进行比较，并报告具体差距：未引用的关键论文、已有更新版本的过时参考文献，以及缺失的方法学参考文献（统计方法、报告指南）。

Specialized Search Modes

专项检索模式

Mode: Manuscript Paper Reference Pool

模式：手稿论文参考文献池

Supplies a manuscript's reference pool — typically invoked by

/write-paper

Step 7.3c (or

/self-review

Phase 2.5c-2) when the reference-adequacy gate finds the draft under target or a named method uncited; usable directly for an original-research bibliography.

For an original-research article, return 25–40 verified candidates, not the ~10 a quick search settles on. If the field is genuinely sparse, say so explicitly rather than returning a thin list silently. Respect a narrower journal reference cap or user scope when one is given.

Cover six candidate categories:

Background / disease burden / clinical context — why the question matters.
Gap-defining prior studies — the work the manuscript extends or contradicts.
Comparator / comparable-design cohorts — studies the Results will be measured against.
Methods / statistical canonical sources — the originating reference for every named method, model, score, equation, or diagnostic criterion (e.g. competing-risk model, multiple imputation, E-value, eGFR equation, concordance statistic). This category clears Methods named-method gaps.
Reporting-guideline sources — STROBE, TRIPOD(+AI), CONSORT, PRISMA(-DTA), STARD, etc.
Interpretation / mechanism / limitation support — grounds Discussion claims.

For each candidate, report PMID/DOI, verification status, candidate category, the target manuscript section, and a one-line why it is needed. Entries go through Phase 4 into

references/library.bib

only. This mode produces candidates: the user decides inclusion, and it does not insert references into the manuscript bib.

为手稿提供参考文献池——通常由

/write-paper

步骤 7.3c（或

/self-review

阶段 2.5c-2）在参考文献充分性关卡发现草稿未达到目标，或某个指定方法缺少引用时调用；也可直接用于原创研究的参考文献表。

对于原创研究论文，应返回 25–40 篇已验证的候选文献，而不是快速检索通常得到的约 10 篇。如果该领域确实文献稀少，应明确说明，而不是默默返回一份数量不足的列表。用户给出了更窄的期刊参考文献上限或范围时，应遵循该限制。

应覆盖以下六类候选文献：

背景／疾病负担／临床环境——说明问题为何重要。
界定研究空白的前序研究——手稿所扩展或反驳的工作。
对照／可比设计队列——Results 将据以衡量和比较的研究。
方法／统计学经典来源——每项具名方法、模型、评分、方程或诊断标准的原始出处（例如 competing-risk model、multiple imputation、E-value、eGFR equation、concordance statistic）。这一类别可弥补 Methods 中具名方法缺少引用的缺口。
报告指南来源——STROBE、TRIPOD(+AI)、CONSORT、PRISMA(-DTA)、STARD 等。
解释／机制／局限性支持——为 Discussion 中的论断提供依据。

对于每篇候选文献，报告 PMID/DOI、验证状态、候选类别、目标手稿章节以及一行 纳入理由。条目仅通过阶段 4 写入

references/library.bib

。此模式生成候选文献：由用户决定是否纳入，且不会将参考文献插入手稿的 bib 中。

Mode: Crowding Check

模式：研究拥挤度检查

Run before a study is designed. A background search ("what has been written about this topic") leaves the trap open; ask four narrower questions instead:

Ask of	Verdict
the research question	taken / partly taken / open
the sampling frame (what population, which records, which years)	taken / partly taken / open
the measurement axis (what is being coded or measured, and at what granularity)	taken / partly taken / open
the target journal	already published there / adjacent / open

Give each its own verdict: a design can be original on one axis and fully occupied on another, and collapsing the four into one answer hides that. The journal row is not vanity: a design once matched an existing paper on frame, coding axis and journal — its own first choice. Most of the time this mode narrows a claim rather than ending a project (e.g. from "nobody has looked at this" to "nobody has decomposed it by provenance"), and the narrowed claim survives review.

Search the way a competitor would: the exact frame, the exact measure, and the journal's own site, not only the topic. Report the four verdicts and the papers behind each, then let the user decide.

应在研究设计之前运行。背景检索（“这个主题已经有哪些研究？”）会留下陷阱；应改为提出以下四个更具体的问题：

询问内容	结论
研究问题	已有人做过／部分有人做过／尚无人做过
抽样框（研究对象总体、哪些记录、哪些年份）	已有人做过／部分有人做过／尚无人做过
测量维度（编码或测量什么，以及测量粒度）	已有人做过／部分有人做过／尚无人做过
目标期刊	已在该期刊发表／相邻领域／尚无

每一项都要单独给出结论：一个设计可能在一个维度上是原创的，而在另一个维度上已被完全占据；若将四项合并成一个结论，就会掩盖这种差异。期刊这一行并非虚荣指标：一个设计若在研究框架、编码维度和期刊三个方面都已有完全对应的论文，那它就是该设计的第一选择。大多数情况下，此模式的作用是收窄主张，而不是终止项目（例如，从“没人研究过这个”改为“没人按来源分解研究过”），而收窄后的主张仍能通过评审。

像竞争者一样进行检索：使用确切的研究框架、确切的测量指标以及期刊官网，而不只是检索主题。报告四项结论及支撑每项结论的论文，然后交由用户决定。

Mode: Systematic Search

模式：系统检索

For systematic reviews or comprehensive literature sections:

Document the full search strategy (PRISMA-compliant).
Record: database, date of search, query string, number of results.
Track inclusion/exclusion at each screening step.
Output a PRISMA flow diagram data summary.

对于系统性综述或综合性文献部分：

记录完整的检索策略（符合 PRISMA 要求）。
记录数据库、检索日期、查询字符串和结果数量。
跟踪每个筛选步骤中的纳入与排除情况。
输出 PRISMA 流程图数据摘要。

Mode: Quick Cite

模式：快速引用

For a single reference the user describes ("that 2023 paper by Smith about AI in chest X-ray"): search PubMed and Semantic Scholar with the details, present the top 3 candidates, and generate the BibTeX entry for the one the user confirms.

对于用户描述的单篇参考文献（例如“那篇由 Smith 于 2023 年发表的关于 AI in chest X-ray 的论文”）：搜索 PubMed 和 Semantic Scholar，并结合这些细节，展示前 3 篇候选文献，再为用户确认的那一篇生成 BibTeX 条目。

Mode: Related Papers

模式：相关论文

From a PMID or DOI, get related papers with

find_related_articles

plus Semantic Scholar citation-based recommendations, ranked by relevance. For a structured, dedup-aware, PRISMA-countable expansion (backward + forward + similar), use Phase 2.5: Citation Searching with

references/snowball.py

instead.

从 PMID 或 DOI 获取相关论文，使用

find_related_articles

加上 Semantic Scholar 基于引文的推荐，并按相关性排序。如果需要结构化、可去重且可计入 PRISMA 数量的扩展（backward + forward + similar），应改用阶段 2.5：引文检索中的

references/snowball.py

。

Mode: Embase Browser Automation

模式：Embase 浏览器自动化

Embase has no public API. Read

${CLAUDE_SKILL_DIR}/references/embase_browser.md

when the search must include Embase — it has the Chrome-automation export steps, the CSV row format, and the PubMed → Embase query translation.

Embase 没有公共 API。当检索必须包含 Embase 时，读取

${CLAUDE_SKILL_DIR}/references/embase_browser.md

；其中包含 Chrome 自动化导出步骤、CSV 行格式，以及从 PubMed 到 Embase 的查询转换。

Error Handling

错误处理

If a search returns 0 results, broaden the query (remove one concept or use broader MeSH terms) and retry.
CrossRef HTTP errors (token-saving rules):
- 403 (rate-limited): Do NOT retry. Skip CrossRef → verify via PubMed title search instead.
- 303 (redirect): Follow the redirect if possible. If not, skip CrossRef → PubMed fallback.
- After the first CrossRef 403/303 in a session, skip CrossRef for ALL remaining references and go directly to PubMed title verification, to avoid N×retry token waste.
- Do not print raw error messages ("Request failed with status code 403."). Report one summary line at the end:
```
CrossRef unavailable for {N} references (rate-limited). Verified via PubMed instead.
```
If a DOI does not resolve via CrossRef (after the rules above), search PubMed by title to confirm the reference exists.
If a reference cannot be verified by any method, state: "This reference could not be verified. Please check manually before submission." Never silently include an unverified reference.

如果检索返回 0 条结果，应扩大查询范围（移除一个概念或使用更宽泛的 MeSH 术语）并重试。
CrossRef HTTP 错误（节省 token 规则）：
- 403（限流）： 不要重试。跳过 CrossRef，改用 PubMed 标题搜索进行验证。
- 303（重定向）： 尽可能跟随重定向。如果无法跟随，则跳过 CrossRef，使用 PubMed 备用方案。
- 会话中首次出现 CrossRef 403/303 后，所有剩余参考文献都应跳过 CrossRef，直接使用 PubMed 标题验证，以避免 N× 重试浪费 token。
- 不要打印原始错误消息（
```
Request failed with status code 403.
```
  ）。在结束时报告一行摘要：
```
CrossRef unavailable for {N} references (rate-limited). Verified via PubMed instead.
```
如果 DOI 无法通过 CrossRef 解析（遵循上述规则后），则通过标题搜索 PubMed，以确认该参考文献确实存在。
如果无法通过任何方法验证参考文献，应说明：“This reference could not be verified. Please check manually before submission.”绝不静默纳入未验证的参考文献。

Known limits

已知限制

```
check_doi_record_match.py
```
compares titles at a similarity threshold and reads structured Crossref fields (
```
type
```
,
```
update-to
```
). A study protocol, or part 2 of a multi-part paper, whose title differs from the row's by a word or a number is not separated from the paper the row describes; no structured field marks it. Treat a silent run as "no mismatch detected", not as proof that every DOI is right.

check_doi_record_match.py

以相似度阈值比较标题，并读取结构化 Crossref 字段（

type

、

update-to

）。标题与表格行仅相差一个词或一个数字的研究方案，或多部分论文的第 2 部分，可能不会被与该行所述论文区分开；没有结构化字段可以标记这种情况。将静默运行理解为“未检测到不匹配”，而不是每个 DOI 都正确的证明。