DeerFlow systematic-literature-review 的 APA 7th 引用模板详解：arXiv 预印本引注规则与 SLR 报告骨架实战

APA（American Psychological Association）第 7 版是社会科学及绝大多数非 IEEE 会刊计算机科学期刊的默认引用格式。在 DeerFlow 开源项目中，内置的 systematic-literature-review 技能通过 templates/apa.md 这一份模板文件，为"跨多篇论文的主题综述（SLR）"规定了完整的 APA 引注规则与报告结构。读完本文，你将掌握如何依据 arXiv API 返回的论文元数据，把"作者列表 + 发布日期 + abs_url"转换成合规的 APA 行内引用与参考文献条目，并按模板骨架产出一份含 Executive Summary、Themes、Per-Paper Annotations 的完整 SLR 报告，同时理解 DeerFlow 技能运行时为何对这套格式规则做了硬性约束。

模板在技能工作流中的定位：何时触发 APA

在写出任何引用之前，先要弄清楚 apa.md 在整个技能中的触发时机。该技能的执行主体是 SKILL.md，它把一次系统化文献综述拆成五个阶段：

• Phase 1（Plan）：与用户确认 Topic、Scope（论文数默认 20、硬上限 50）、Citation format 与输出位置。模板明确规定：当用户请求 APA 格式，或者没有指定任何格式时，一律走 APA 7th——这是 APA 模板成为默认模板的直接依据。
• Phase 2（Search arXiv）：调用内置搜索脚本获取论文 JSON 元数据。
• Phase 3（Extract metadata）：把论文按每批约 5 篇拆包，通过 task 工具委派给 subagent 并行抽取结构化元数据。
• Phase 4（Synthesize and format）：进行跨论文主题综合，并根据用户偏好只读取与请求格式对应的那一份模板文件——APA 请求只读 templates/apa.md，而不是同时读 IEEE 与 BibTeX 模板。这一约束也体现在 evals.json 的评测预期中：评测用例 1 明确检查"templates/apa.md 被读取""参考文献使用带 arXiv URL 的 APA 7th 格式"。
• Phase 5（Save and present）：报告以 slr-<topic-slug>-<YYYYMMDD>.md 命名保存到输出目录并调用 present_files 交给用户。

因此 apa.md 回答的是两个问题：APA 格式下"怎么引用"（行内引用 + 参考文献条目规则），以及 "引用往哪里填"（一份可逐字沿用的报告骨架）。它是 Phase 4 合成阶段的直接依据文件，而不是给人类用户看的产品手册。

与其他两种模板的分工

技能目录下并列存放三份模板：templates/apa.md（APA 第 7 版，默认）、templates/ieee.md（IEEE 数字编号引用）与 templates/bibtex.md（BibTeX @misc 条目）。判断口径是：用户投向 IEEE 会议/期刊或明确要求 IEEE 时用 ieee.md；用户提到 BibTeX / LaTeX / 机器可读文献时用 bibtex.md；其余场景（含未指定格式）全部落到 APA。三者共享同一套 Phase 2 → Phase 5 工作流，只是引用语法与报告正文的编号方式不同。

行内引用（In-text Citations）规则

apa.md 首先规定的是一套"随文引用"规则，覆盖从单人作者到多人协作的所有情况：

• 单作者：(Vaswani, 2017)，或在行文中作为叙述主语写作 Vaswani (2017) showed that...。
• 两位作者：括号内使用 &，即 (Vaswani & Shazeer, 2017)；若在行文叙述中使用 "and" 连接，如 Vaswani and Shazeer (2017) found...。
• 三位及以上作者：从第一次引用起就使用 et al.，即 (Vaswani et al., 2017)。模板特别标注这是 APA 第 7 版相对第 6 版的规则变化——旧版允许前几次列出全部作者、之后才缩写为 et al.，新版则要求首次引用即缩写，省去在超长作者名单上耗费的字数。
• 多条文献并列引用：(Vaswani et al., 2017; Devlin et al., 2018)——同一括号内多篇文献按首作者姓氏字母序排列，用分号分隔。

这一系列规则直接决定了后面"Per-Paper Annotations"与正文 Themes 段落的书写方式：在 Theme 讨论中引用论文时用叙述式（Vaswani et al. (2017) introduced X）还是括号式，取决于句子结构，但作者缩写与排序规则始终一致。

arXiv 预印本参考文献条目：核心格式

APA 模板把读者最易写错的部分单独拎出来强调：arXiv 论文是预印本（preprint），不是正式发表的期刊文章，必须按预印本格式引用并携带 arXiv 标识符。其通用模板为：

Author, A. A., Author, B. B., & Author, C. C. (Year). Title of the paper. arXiv. https://arxiv.org/abs/ARXIV_ID

模板给出的真实示例来自论文元数据 {id: "1706.03762", title: "Attention Is All You Need", authors: [...] , published: "2017-06-12"}：

Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., Kaiser, Ł., & Polosukhin, I. (2017). Attention is all you need. arXiv. https://arxiv.org/abs/1706.03762

请注意：这里的"真实示例"并非随意编造，而是直接由搜索脚本返回的 JSON 字段驱动生成的。下一节将从源码角度拆解每个字段的映射关系。

逐字段格式规则

• 作者姓名：一律写作 LastName, FirstInitial. 形式（中间名首字母可选），例如 Vaswani, A.。多位作者用逗号连接，最后一位作者前加 &（不是 "and"）。这是参考文献条目与人名书写习惯最大不同的地方：先姓后名缩写。
• 年份：取论文元数据 published 字段的年份，置于括号中紧跟作者之后。
• 标题：使用句首大写（sentence case），即只有首词与专有名词大写（如上述 "Attention is all you need" 中仅首词大写）。排版输出中标题应使用斜体；在纯 Markdown 环境下按模板要求保持不加粗不加斜的纯文本即可。
• 来源标识：字面量 arXiv，后跟完整的 abs 页 URL（https://arxiv.org/abs/... 形态）。
• DOI：除非论文同时已在带 DOI 的正式场合发表，否则不写 DOI。纯 arXiv 预印本一律用 URL 而非 DOI。

作者数目的特殊情形

APA 参考文献对作者人数有两个边界规则：

• 不超过 20 位作者：全部列出，逗号分隔，最后一位前加 &（上面的 Vaswani 例子的 8 位作者即完整列出）。
• 21 位及以上作者：列出前 19 位，接着写省略号 ...，再写最后一位作者。

需要强调一条与 arXiv 检索强相关的边界事实："无 DOI 且无 URL"的条目在本文档工作流中不可能出现——因为所有论文元数据都来自 arXiv API，abs_url 必然存在，参考文献条目始终使用论文元数据中的 abs_url。这也是质检清单里"不允许悬挂引用、不允许缺失来源"能够成立的前提。

SLR 报告骨架：可逐字沿用的结构模板

apa.md 的主体并非零散的格式片段，而是一份要求"逐字沿用时"（follow this structure verbatim）的完整报告骨架。文档要求作者把 Phase 3 抽取的结构化元数据与 Phase 4 的综合结果填入占位符。整体结构如下：

# Systematic Literature Review: <Topic>

**Date**: <YYYY-MM-DD>
**Papers surveyed**: <N>
**Scope**: <arXiv search query, category, time window>
**Citation format**: APA 7th edition

## Executive Summary
<3-5 句话综合评述该主题的文献现状：被调查论文共同说明了什么、领域形态如何。不要罗列论文——要综合。>

## Methodology
<说明检索时间、query、分类过滤、时间窗、排序方式与纳入篇数；说明元数据抽取由语言模型 agent 执行、跨论文综合由主 agent 执行。>
**Limitations of this review**: arXiv 预印本未经同行评审，部分论文可能与最终正式版本不一致；覆盖面仅限于 arXiv，不含未上传预印本的正式发表论文。

## Themes
<3-6 个主题小节。每个主题是被调查论文中反复出现的研究方向、问题框架或方法论路径。>

### Theme 1: <Theme name>
<2-4 段描述该主题，随文引用论文，如 "Vaswani et al. (2017) introduced X, while subsequent work (Devlin et al., 2018; Liu et al., 2019) extended it to Y." 不要只罗列论文，要描述串联它们的思想脉络。>

### Theme 2: <Theme name>
<...>

## Convergences and Disagreements
**Convergences**: <多篇论文达成一致的发现，附证据来源。>
**Disagreements**: <论文得出不同结论之处，说明分歧条件。>

## Gaps and Open Questions
<现有文献尚未解决之处。从 Phase 3 抽取的 limitations 字段中归纳模式——若 5 篇论文都提到同一缺失，就是值得标注的 gap。>

## Per-Paper Annotations
<每篇论文一个小节，按年份再按首作者姓氏排序。每小节是该论文贡献的微型总结。>

### Vaswani et al. (2017)
**Research question**: <1 句，取自 Phase 3 元数据>
**Methodology**: <1-2 句>
**Key findings**:
- <要点>
**Limitations**: <1-2 句>

## References
<按首作者姓氏字母序排列，使用上述 APA 7th 格式。>

Devlin, J., Chang, M.-W., Lee, K., & Toutanova, K. (2018). BERT: Pre-training of deep bidirectional transformers for language understanding. arXiv. https://arxiv.org/abs/1810.04805

Vaswani, A., ... (2017). Attention is all you need. arXiv. https://arxiv.org/abs/1706.03762

<...更多条目，每篇论文一条...>

各环节的写作要点

报告的各部分扮演不同角色，模板对其语义有清晰限定：

1. 头部元信息：报告名采用 <Topic> 占位；Date、Papers surveyed（N）、Scope（query + 分类 + 时间窗）、Citation format（APA 7th edition）四行必须齐全，保证报告可追溯、可复现。
2. Executive Summary：3-5 句话给出整体判断，核心要求是"综合而非罗列"——描述领域形态与集体结论，禁止把论文清单搬进来。
3. Methodology：交代检索口径（日期、query、分类、时间窗）、排序方式（relevance 或 submitted date）、纳入前 N 篇的截断方式，并声明两条方法论局限：arXiv 预印本未经同行评审、覆盖面限于 arXiv。SKILL.md 的 Phase 3 说明同步证实元数据抽取由语言模型 agent 完成、综合由主 agent 完成，与这里的方法论声明互为印证。
4. Themes（3-6 个）：每个主题 2-4 段，主题必须是贯穿多篇论文的研究方向/问题框架/方法论路径；要求"描述连接论文的思想线索"，而非逐篇罗列。若论文集太小或异质到无法支撑主题综合（如 5 篇主题迥异的论文），SKILL.md 明确要求在报告中如实说明、绝不强行捏造主题。
5. Convergences and Disagreements：分别汇总"多篇论文一致认可"与"论文结论相左"之处，且分歧往往要给出条件限定（"在条件 Y 下 X 不成立"）。
6. Gaps and Open Questions：从 Phase 3 的 limitations 字段中归纳模式性缺失——多条论文同时提到的空白即值得标注的 gap。
7. Per-Paper Annotations：每篇一个小节，含 Research question / Methodology / Key findings / Limitations 四要素，排序规则是先按年份、同年再按首作者姓氏，与 References 的字母序形成互补的两种查阅视角。
8. References：全部论文按首作者姓氏字母序排列，作为与行内引用一一对应的收束。

定稿前质量检查清单

模板在骨架末尾给出 6 条硬性检查项，用于捕获"引用-条目失配""格式漂移"这类 SLR 报告最常见的缺陷。这正是把格式规则落到验收动作上的关键一环：

• 被调查集中的每篇论文同时出现在 Per-Paper Annotations 与 References 中；
• 每个行内引用都能在参考文献中找到对应条目（无悬挂引用，dangling citations）；
• 作者书写为 LastName, FirstInitial. 而非 FirstName LastName；
• 年份在行内置于括号中，在参考文献条目中紧跟作者；
• 参考文献标题使用句首大写（仅首词与专有名词大写）；
• arXiv URL 一律使用 abs_url 形态（https://arxiv.org/abs/...），不得使用 pdf_url；
• 参考文献按首作者姓氏字母序排列。

其中"用 abs_url 而非 pdf_url"这条与下一节的元数据映射直接相关，也在 evals.json 中被固化为自动化评测预期。

源码级佐证：arXiv 元数据字段如何驱动 APA 引用

apa.md 中的格式规则之所以能可靠执行，前提是 Phase 2 的搜索脚本输出了结构规整、字段齐全的 JSON。该脚本为 scripts/arxiv_search.py，它调用 arXiv 官方 API（http://export.arxiv.org/api/query），无需 API key，返回的每条论文记录包含 id、title、authors、abstract、published、updated、categories、pdf_url、abs_url 九个字段。逐字段对照 APA 规则，可以看到清晰的映射链：

模板规则（apa.md）	驱动字段（arxiv_search.py）	处理细节
年份 (Year)	published	解析逻辑见 _parse_entry：arXiv 返回 ISO 8601 时间戳（如 2017-06-12T17:57:34Z），脚本按 T 截断只保留日期部分，APA 取其中的 4 位年份
来源 URL	abs_url	在 _parse_entry 中遍历 Atom <link>：rel="alternate" 的 href 作为 abs_url，title="pdf" 的 href 单独存入 pdf_url——两者被刻意分开，正是为了满足"引用只用 abs_url"的约束
作者全名单	authors（字符串列表）	如 ["Ashish Vaswani", ...]，由 atom:author/atom:name 抽取并剔除空项，供 APA 阶段转换为 Vaswani, A. 形态
标题	title	抽取后做空白归一（" ".join(title.split())），APA 阶段再降为句首大写
id（IEEE/BibTeX 用）	id	_normalise_arxiv_id 把 http://arxiv.org/abs/1706.03762v5 归一化为裸 id 1706.03762，同时剥掉 v5 版本后缀、兼容 hep-th/9901001 老式前缀——这与 apa.md 中"引用用 abs URL、IEEE 模板中才用 arXiv:<id>"的分工一致

从源码注释还可以看到一条与 APA 场景直接相关的设计约束：max_results 被钳制在 50（arxiv_search.py），对应 SKILL.md 声明的"50 篇硬上限"——若综述规模超过 50 篇，Phase 3 的批处理并发策略（每轮最多 3 个 subagent、每批约 5 篇）将不堪重负，综合质量快速劣化，此时应建议用户按子主题拆分。换句话说，References 列表的规模边界在检索阶段就已由脚本兜底。

此外，脚本在 构建查询串 时会把含空格的多词主题自动包裹成短语 all:"..."，并支持 --category、--start-date/--end-date（转换为 arXiv 的 submittedDate:[... TO ...] 区间语法）与 --sort-by。这些参数直接决定了报告头部 Scope 一行的内容——APA 报告的 Methodology 需要如实写出 query、分类、时间窗，而它们恰好与脚本入参一一对应。

与 DeerFlow 技能生态的衔接与常见误区

最后汇总几个从模板与源码中可以直接推断、但新手极易踩中的点，便于把这套模板真正用对：

1. 默认即 APA，别漏读模板：用户未指定格式时默认 APA。Phase 4 只读与请求格式匹配的那一份模板文件，绝不三份同读，避免格式交叉污染。
2. arXiv 论文 ≠ 期刊论文：参考文献条目中来源写 arXiv + abs URL；除非有正式发表 venue 与 DOI，否则不写 DOI、不伪装成期刊出处。
3. et al. 的规则以第 7 版为准：3 位及以上作者从首次引用起就用 et al.，不要沿用第 6 版的"先全列后缩写"习惯。
4. 行内与条目形态不同：行内用 (Vaswani et al., 2017)，条目则完整展开为 Vaswani, A., Shazeer, N., ...——二者并存的根源是 APA 的"叙述时省、检索时全"设计。
5. 排序规则相反：References 按首作者姓氏字母序；Per-Paper Annotations 按年份→首作者姓氏排序。若把两者都用字母序或都用时间序，就是格式漂移。
6. Runtime 路径与仓库路径的差异：SKILL.md 中的示例命令以运行时挂载路径书写（/mnt/skills/public/systematic-literature-review/scripts/arxiv_search.py，输出目录默认 /mnt/user-data/outputs/），而在本仓库中同一技能位于 skills/public/systematic-literature-review/ 目录下——阅读源码与运行技能的路径口径不同，但格式规则完全一致。

小结

apa.md 是一份"规则 + 骨架 + 验收"三位一体的模板：行内引用与参考文献条目规则决定了 APA 7th 的书写语法；报告骨架规定了 Executive Summary、Methodology、Themes、Convergences/Disagreements、Gaps、Per-Paper Annotations 与 References 的完整章节与各自语义；质量检查清单则把"禁止悬挂引用、标题句首大写、abs_url 而非 pdf_url、按字母序排列"等约束变成可勾验的动作。配合 SKILL.md 的五阶段流程与 arxiv_search.py 的结构化 JSON 输出，DeerFlow 得以让 Agent 在数十篇 arXiv 论文上稳定产出格式合规、结构自洽、可追溯的系统化文献综述——而 APA 正是这条流水线默认且最常被触发的输出格式。