literature-review

文献综述

根据研究问题，撰写一份以主题为线索、以引文为依据的综述文档。 本技能负责协调各项工作：搜索、获取全文和引文核验由配套技能完成；本技能负责工作区、筛选语料库、论点提取、主题综合，以及最终覆盖度检查。

适用场景

• “针对 X 做一份文献综述”／“调查 X 的近期研究”
• “自 2023 年以来，X 的最新进展是什么？”
• “阅读这 N 篇论文，并按主题综合”
• 需要一份独立的综述。若要撰写论文的「相关工作」章节，请先在此处完成语料库构建阶段，然后交由 draft-related-work 处理。

输入

• 研究问题或主题，最好包含年份范围，并可选择指定目标会议。
• 为配套技能导出的 CONTACT_EMAIL，用于遵守 API 礼貌请求约定。
• 可选：用户已有的论文／DOI 列表。

本技能委托的配套技能

阶段	委托给	提供内容
搜索	find-papers	dblp_search.py、crossref_search.py、s2_search.py、arxiv_search.py（位于该技能的脚本目录中）——无需密钥、限速、带缓存
全文	fetch-paper	resolve_oa.py——一个 DOI/arXiv ID 对应一份合法的开放获取副本，临时获取
引文核验	verify-citations	根据 Crossref/DBLP/S2 核验每条 BibTeX 条目，并标记撤稿论文

切勿在此处重新实现这些功能（不要临时用 curl 调用学术 API）； 配套脚本负责处理限速、退避、缓存和 User-Agent 约定。

流程

阶段 1 — 确定范围

1. 与用户确认：研究问题、年份范围、纳入和排除标准（各 2–4 条），以及目标规模（10–15 篇是稳妥的默认值；超过 30 篇需取得用户明确同意）。
2. 运行 python3 scripts/init_review.py "TOPIC"——创建 lit-review/<slug>/，其中包含 corpus.json、themes.yml、notes/ 和 review.md 骨架。
3. 将双方确认的标准写入 corpus.json 的 criteria 字段。

阶段 2 — 搜索（委托给 find-papers）

1. 按照 references/methodology.md 设计查询、 枚举会议，并进行滚雪球检索。
2. 如果范围指定了会议，请读取 venues/conferences/<id>.yml 中的 aliases 区块（DBLP 键、S2 会议名称、Crossref 容器标题）——这可以解决会议别名问题。配置文件中的信息仅供起步参考：如果某项信息会成为综述的关键依据（例如包含哪些 tracks），则在使用前，必须通过实时的 cfp_url 再次核验。
3. 记录每批搜索结果： python3 scripts/corpus.py --corpus <ws>/corpus.json import hits.json --source dblp --query "..."（接受 find-papers --json 输出； 按 DOI 去重）。单篇论文使用 corpus.py add 添加。
4. 从多个主题各异的种子论文开始滚雪球检索——每个主题各一篇，而非只选一篇方便的论文（否则采集的论文集会偏向某个子领域，遗漏其他领域）。仅当你能说明每篇相邻论文在研究问题论证中的作用时才纳入（我们将扩展的方法／基线／评估任务／基础研究脉络），并在筛选前进行共同引文合理性检查。完整流程见 references/methodology.md。
5. 搜索结果不完整，就视为尚未完成。 find-papers 中的 resolve_papers.py 会为每次扇出搜索标记 COMPLETE 或 PARTIAL，并标记仅由单一索引确认的结果。如果某个主题的搜索结果为 PARTIAL（某个提供方受到限速），或核心论文仅由单一索引收录，那么引文图谱阶段已悄然退化——该主题的查全率只能碰运气。应等待一段时间后重新运行受限的搜索环节（添加 S2_API_KEY），或改用其他提供方，再宣布该主题已覆盖；在 corpus.json 中记录哪些论文只能通过备用路径找回，以便审查这一缺口。

阶段 3 — 筛选

1. 对每篇待处理论文，根据书面标准，结合标题 + 发表场所 +（按需获取的）摘要，决定纳入或排除。使用 find-papers 中的 s2_search.py 获取摘要——切勿将摘要粘贴到任何已提交的文件中。
2. 记录每项决定及其理由： python3 scripts/corpus.py --corpus ... set KEY --screened excluded --reason "out of scope: no spatial component"。
3. 在阅读全文之前，向用户展示 corpus.py stats 和纳入列表。确认该集合。

阶段 4 — 获取与提取（委派给 fetch-paper）

1. 每次处理一篇论文，从仓库根目录运行 fetch-paper 的解析器： FP=skills/fetch-paper/scripts; python3 "$FP/resolve_oa.py" <DOI-or-arXiv-ID>。 临时阅读开放获取（OA）版本——优先使用 arXiv HTML，否则直接阅读 PDF。如果不存在合法的 OA 版本（退出代码为 3），则标记该论文，仅根据已核实的元数据进行综合，或请用户提供其馆藏副本。切勿使用影子图书馆。
2. 按照 references/claim-extraction.md 中的论点记录格式，将有依据的笔记写入 notes/<key>.md：每条论点都要标注锚点（章节/页码）、强度标签，并且只写转述（逐字引用少于 25 个单词，且始终加引号）。切勿保存摘要或论文正文——笔记必须用你自己的话撰写。
3. 标记进度：corpus.py set KEY --fetched yes --extracted yes。

阶段 5 — 按主题整理

1. 将提取出的论点归纳为 3–6 个主题；在 themes.yml 中记录主题，并为论文添加标签：corpus.py set KEY --theme <slug>。
2. 按照 references/review-structure.md 构建综合矩阵（论文 × 主题 × 方法 × 评估 × 结果）。

阶段 6 — 核验引用（委派给 verify-citations）

1. 生成 BibTeX 框架： python3 scripts/corpus.py --corpus ... bibtex > <ws>/references.bib。 corpus.py 是引用键的唯一真实来源——bibtex 会使用语料库中的确切键生成 .bib。切勿手动编辑 .bib 中的键；应在语料库中更改它（corpus.py add --update）并重新生成，这样语料库、.bib 和综述中的 [@key] 就不会不一致。
2. 对 references.bib 运行 verify-citations 技能，始终使用 --json，以生成可供核对的机器可读文件： check_bibtex.py <ws>/references.bib --json <ws>/citecheck.json。修复或删除所有无法解析的条目；如有撤稿，向用户标明。
3. 根据该文件而非手动设置已核验标记： python3 scripts/corpus.py --corpus <ws>/corpus.json verify-audit --report <ws>/citecheck.json。审计只会对报告确认的键（状态为 VERIFIED）标记 verified:yes，清除报告未确认的任何标记，记录 verified_via 来源信息和日期，并逐字回显报告的结论行。命令在 PARTIAL-PASS 或 FAIL 时以非零状态码退出——因此，未完成的运行不会被误认为通过。
   • 如果改为手动设置标记，corpus.py set KEY --verified yes 现在需要 --source <provider>（确认该条目的索引所对应的规范记录），并会记录此信息；不带参数的 --verified yes 将被拒绝。
   • “已核验”表示权威索引在本次会话中确实返回了该条目的规范记录——不能仅凭某个 API 曾返回过一次 ID，也绝不能用于 fetched:false 的条目。没有来源信息却标记为 verified:yes 的键属于无效门禁；corpus.py stats 现在会在发现此类情况时发出警告。
   • 在综述正文及任何摘要/README 中，逐字复述 verify-citations 的结论行：准确写出结论（PASS / PARTIAL-PASS / FAIL）及原始计数（N verified、M warnings by flag、K skipped checks）。切勿将 PARTIAL-PASS 升格为“已核验”，也切勿把“PARTIAL-PASS, 11 WARN, 1 skipped”简化为“已核验，0 个错误”。

阶段 7 — 起草

1. 按照 references/review-structure.md 中的结构模板编写 review.md。
2. 关于先前工作的每项事实性主张都要引用语料库键：[@key] 或 \cite{key}。主张必须可追溯到笔记锚点——如果没有笔记，就不要写这项主张。

阶段 7b — 核对前向引用

草稿（以及任何相关工作计划）会在正文中将方法、基线和骨干网络作为待填项提及，例如“我们扩展了 X”“与 Y 对比”“基于 W 骨干网络构建”。确保这些内容都有依据：

1. 运行 python3 scripts/forward_refs.py <ws>/review.md [plan.md] --corpus <ws>/corpus.json。该脚本会提取所有命名的方法／基线／骨干网络，与经过验证的语料库进行比对，并将未解决项列为检索工作清单。
2. 对每项确实缺失的工作，重新走一遍完整流程（find-papers → screen → fetch-paper → extract → verify-citations），然后再将语料库标记为完整。仅排除不可引用的条目（用户自己的系统、数据集、指标）——绝不要为了清除清单而编造引用。
3. 反复运行，直到工作清单中不再有真实参考文献。

阶段 8 — 检查门槛

1. 确认语料库键与 references.bib 中的键完全一致： python3 scripts/corpus.py --corpus <ws>/corpus.json check-keys <ws>/references.bib。如果失败，则从语料库重新生成 .bib（corpus.py bibtex）——绝不要通过手动编辑键来协调。
2. 运行 python3 scripts/check_review.py <ws>/review.md --bib <ws>/references.bib。遇到未知键、未经验证或已排除的引用、.bib 中缺少被引用的键（键不一致）、占位符标记，以及超过 40 个词的逐字引文时，该脚本会报错；对于未引用的已纳入论文和未引用的长段落，则会发出警告。
3. 修正并重新运行，直到显示 RESULT: PASS。只交付通过检查的文档，并告知用户综述已通过覆盖范围检查。

输出

• lit-review/<slug>/review.md — 主题综述，所有主张均有引用，并通过 check_review.py 检查。
• lit-review/<slug>/corpus.json — 可审计的记录：检索、带原因的筛选决定、验证状态。
• lit-review/<slug>/references.bib — 已验证的 BibTeX。
• lit-review/<slug>/notes/ — 每篇论文的依据充分的笔记（仅限释义）。

防护措施

• 绝不捏造或夸大引用。论文只有通过真实检索结果才能纳入综述；引用只有通过 verify-citations 验证后才能使用。若缺少支持某项主张的证据，应明确说明。
• 版权：按需获取论文正文和摘要，并进行临时处理——绝不将其写入工作区、代码库或综述。元数据（DOI、标题、作者、BibTeX 字段）可以保留。引用少于 25 个词的原文，并标注出处。
• 礼貌：所有网络访问都通过配套技能的脚本进行（每个主机每秒不超过 1 个请求、使用 CONTACT_EMAIL User-Agent、对 429 进行退避、使用 .cache/）。
• 绝不代表用户提交或发布任何内容。
• 将筛选决定和最终主题结构提交用户审批——范围判断由用户负责。

参考资料

• references/methodology.md — 查询设计、会议论文集枚举模式、按角色纳入的多种子滚雪球检索及共被引合理性检查、停止标准、筛选流程、前向引用核对。
• references/claim-extraction.md — 有依据的笔记格式、锚点和强度标签、笔记的版权规则。
• references/review-structure.md — 综述文档模板、综合矩阵、引用语法，以及移交给 draft-related-work 和 write-abstract 的事项。