| name | academic-ref-check |
| description | 学术参考文献的端到端检查、验证与修复。解析原始文献列表，去重，按APA第七版(APA 7th edition)格式化，通过OpenAlex和Semantic Scholar数据库验证每条文献的准确性，自动修复DOI、年份、标题等问题，并生成人工审核清单和Word文档。Use this skill whenever you need to: 参考文献检查, 参考文献格式调整, APA格式化, 文献去重, DOI验证, 参考文献修复, 参考文献整理, reference check, APA formatting, bibliography verification, DOI validation, citation formatting, or reference list cleanup. |
| license | PolyForm-Noncommercial-1.0.0 AND CC-BY-NC-SA-4.0 |
Reference Check
学术参考文献的完整检查、验证、修复、格式化流程。从原始文献列表到格式规范、数据库验证通过、附带人工审核清单的终版文献输出。
核心规则
以下五条规则是整个流程的基石。违反任何一条都会导致下游产出错误，且错误难以被后续阶段发现。
1. 使用作者+年份指纹ID，不用序号
所有阶段引用文献时使用内容指纹（作者姓_年份_标题关键词），不使用位置序号（如中[3]、英[218]）。这是因为去重、修复、重排序都会改变文献位置，位置序号在第一次修改后就会指向错误的文献，而指纹ID与文献内容绑定，无论如何重排都保持有效。
指纹ID生成规则：
- 英文：
{第一作者姓}_{年份}_{标题前3个实词}（跳过a/an/the/of/in/on/for/and/with/to）
- 中文：
{第一作者姓}_{年份}_{标题前5个字}
- 示例：
Harding_2025_Musical_neurodynamics、安心_2017_高海拔驻留时间对
2. 有数据库依据才能修复
学术引用必须精确——不能基于猜测修改文献内容。自动修复仅限于数据库置信度高且修复方向无歧义的场景（如DOI补充、明显年份错误）。涉及作者增删、标题实质性差异等情况，只报告不修改，留给用户判断。具体判断标准见 references/fix_decision_matrix.md。
3. 终版文件是唯一权威来源
人工审核清单（或任何面向用户的文档）中引用的"当前内容"必须从终版文献文件中逐字复制。中间阶段的验证报告只用于确定"哪些条目需要关注"，不用于提供条目的具体内容。这条规则存在的原因是：验证阶段记录的文献快照会在后续修复中过时，如果清单从旧快照中复制内容，会出现清单描述与终版文件完全不一致的严重错误。
4. 规则性检查和判断性评审分离
Sentence case、&号、DOI格式等规则性问题由全量扫描式SubAgent逐条检查，确保100%覆盖。期刊真实性、引用准确性等需要判断力的问题由领域专家评审。两者并行运行但职责不重叠。混合使用会导致规则性问题被专家式抽检遗漏（首次执行中58条sentence case问题被4位专家全部漏掉，就是这个教训）。
5. 清单是流水线的终端产物
人工审核清单必须在所有自动修复和专家评审完成后、作为最终阶段独立生成。过早生成会包含已被后续修复的问题，导致清单与终版文件不一致。
SubAgent 角色与操作指南
每个SubAgent加载本Skill后，根据自己被分配的角色，阅读对应的操作指南和reference文件。
解析器（Parser）
职责： 将原始文献文本解析为结构化数据，为每条文献分配指纹ID。
操作要点：
- 识别多行断裂的文献条目（标题和期刊名被分割成多行的情况），合并为完整条目
- 识别非标准引用格式（Nature风格、编号格式
[2]、中文[J]标注等）
- 为每条文献生成指纹ID（规则见核心规则第1条）
- 提取结构化字段：作者、年份、标题、来源、卷期页码、DOI、文献类型、语言
- 标记已识别的格式问题（DOI格式错误、全角标点混用、注释残留等）
去重规则：
- DOI完全相同 → 保留更完整的版本
- 标题相似度>90%且年份相同 → 保留更完整版本
- 预印本vs正式发表版 → 保留正式发表版
格式化器（Formatter）
职责： 将结构化文献数据按APA第七版格式输出。
Before formatting, read references/apa7_rules.md for the complete APA 7th edition formatting rules.
操作要点：
- 作者格式：
姓, 名首字母.，1-20位全列，21+使用省略号规则
- 标题：sentence case（仅首字母和专有名词大写）
- 期刊名：title case + 斜体（Markdown中用
*期刊名*标记）
- DOI统一为
https://doi.org/前缀格式
- 排序：中文文献按拼音在前，英文文献按字母在后
- 中文文献也使用
&连接最后两位作者
验证器（Verifier）
职责： 通过学术数据库验证每条文献的准确性。
Before verifying, read references/verification_guide.md for the complete database query workflow and result classification rules.
核验主路径 = scripts/verify_http.py（OpenAlex + CrossRef 公开 HTTP API，无需 key）。 若运行环境未提供 semantic-scholar / openalex MCP server（常见默认情况），原"强制加载 SS/OpenAlex MCP"路径会空转。本 Skill 接受这一降级，核验改走 HTTP 脚本：
python3 scripts/verify_http.py --in refs.json --out-dir <dir>
python3 scripts/verify_http.py --in-text refs.md --out-dir <dir>
- 产物：
L11_ref_verify_report.md（人读，绿/黄/红/unverified 四态）+ L11_ref_verify_report.json（机读）。
- 退出码（可直接接 SP7 preflight 门）：有红→1 / 否则有 unverified→3 / 否则有黄→2 / 全绿→0。
- 铁律（不可破）：网络失败 / 查无匹配 绝不伪装通过——不假绿。 一切"不确定"落黄或红，绝不落绿；网络失败标 unverified（渲染为黄，须重跑，不可当通过）。匹配只信自算 title 相似度，不信 API 的"有结果"/score/total-results。中文文献国际库未覆盖→黄（非幻觉，非红）。
MCP 通道（可选 · 仅当环境中存在 SS/OpenAlex MCP 时）： 若所在环境确实装有 semantic-scholar / openalex MCP server，可将其作为补充核验通道与 HTTP 脚本交叉印证（用 ToolSearch 加载 mcp__semantic-scholar__* / mcp__openalex__* 后调用，工具用法见 references/verification_guide.md）。这是条件分支，不是前置必需步骤——若环境不具备这些 MCP，直接走 HTTP 主路径即可，无需尝试加载。
验证策略： 主路径下由 verify_http.py 内部完成「DOI 优先 → 标题搜索 → 自算相似度判定」并按绿/黄/红/unverified 分类（见下方 ABCD 类对照）；MCP 在场时可对黄/红条目再交叉印证。两库（HTTP 或 MCP）都查不到才标记为 D 类。
结果分类：
| 类别 | 含义 | 后续处理 |
|---|
| A | 验证通过 | 无需处理 |
| B | 可自动修复（置信度高） | 交给修复器 |
| C | 需人工判断 | 列入审核清单 |
| D | 未查到 | 根据文献类型决定是否列入清单 |
中文文献特殊处理： OpenAlex和Semantic Scholar对中文文献覆盖有限。中文文献查不到是正常的，不应被视为信息可能有误的信号，除非文献本身存在格式异常。
修复器（Fixer）
职责： 汇总验证结果，对B类条目执行自动修复。
Before fixing, read references/fix_decision_matrix.md for the auto-fix vs report-only decision rules.
操作要点：
- 仅修复B类中置信度为"高"的条目。中/低置信度一律转入C类报告
- 每次修复必须同时在修复操作记录中记录：指纹ID、修复类型、修复前值、修复后值、修复依据
- 修复完成后校验文献总数守恒（修复不应增删文献）
- 更新修复状态汇总表
典型可自动修复的场景： DOI补充/格式修正、明显年份错误（如2026→2025）、sentence case转换、期刊名PubMed注释去除、标点符号修正、排序修正。
典型仅报告的场景： 作者列表大幅变动、标题实质性差异、卷期页码大幅不一致、数据库未收录的文献。
规则扫描器（Rule Scanner）
职责： 对终版文献执行全量逐条规则检查，确保100%覆盖。
Before scanning, read references/apa7_rules.md for the complete checklist of rules to verify.
与专家评审的区别： 规则扫描器检查的是可程序化判断的格式规则（有明确的对/错标准），专家评审处理的是需要学术判断力的问题。
必须逐条扫描的规则（每条文献都检查）：
- Sentence case（英文标题仅首字母和专有名词大写）
- 作者间的
&号（中英文文献均需检查）
- DOI格式（
https://doi.org/前缀，无多余空格/重复前缀）
- 期刊名斜体标记（
*期刊名*）
- 标点符号规范（半角、句末句号、逗号位置）
- 年份格式（括号内，逗号后）
- 排序正确性（中文拼音、英文字母）
- 21+作者省略号规则
领域专家（Domain Expert）
职责： 执行需要学术判断力的非规则性审查。
审查维度：
- 期刊真实性：期刊是否存在、是否为掠夺性期刊
- 引用准确性：文献是否与论文主题领域一致
- 内容合理性：年份、卷期、页码是否在合理范围内
- 特殊格式判断：会议论文、预印本等有多种合理格式的情况
不负责的事项： sentence case、&号等规则性检查（由规则扫描器负责）。
清单生成器（Checklist Generator）
职责： 生成面向用户的人工审核清单。这是整个流程中对准确性要求最高的环节。
Before generating, read references/checklist_spec.md for the complete checklist format specification, category definitions, and validation rules.
强制执行的生成流程：
- 读取终版文献文件，建立指纹ID→终版内容的完整映射表
- 读取验证总报告，提取C类和D类条目
- 读取修复状态汇总表，排除已修复的条目
- 读取专家评审报告，提取未修复的问题
- 合并得到"待审核项目池"
- 对每个待审核项目，通过指纹ID从步骤1的映射表中提取终版内容（不从验证报告复制）
- 按五类分类组织清单
- 执行一致性校验（使用
scripts/validate_checklist.py）
五类分类：
- 必须处理（Must Fix）
- 数据库未覆盖（Not Found）
- 自动修正需复核（Auto-fixed, Please Verify）
- 信息补充建议（Suggested Additions）
- 仅供知晓（FYI）
Word转换器（Word Converter）
职责： 将终版Markdown文献文件转换为符合博士论文排版标准的Word文档。
使用 scripts/convert_refs.py 执行转换：
python scripts/convert_refs.py <input.md> [output.docx]
格式规范：
- 标题：黑体三号(16pt)居中加粗
- 条目：宋体+TNR五号(10.5pt)，固定行距20pt，悬挂缩进2字符
- 期刊名：斜体（通过
*期刊名*标记自动识别）
- 页面：A4，页边距上3/下2.5/左3/右2.5cm
依赖： pip install python-docx
APA 第七版格式速查表
以下是最常用的10条规则，完整规则见 references/apa7_rules.md。
| # | 规则 | 正确示例 |
|---|
| 1 | 作者格式：姓, 名首字母. | Zhang, L. M. |
| 2 | 多作者用,分隔，最后两位用& | Li, A., Wang, B., & Chen, C. |
| 3 | 21+作者：前19位...最后1位 | Author, A., Author, B., ... Author, U. |
| 4 | 年份在作者后括号内 | Smith, J. (2023). |
| 5 | 文章标题sentence case | Effects of music on cognitive development in children |
| 6 | 期刊名title case+斜体 | *Journal of Experimental Psychology* |
| 7 | 卷号斜体，期号不斜体括号内 | *12*(3), 45-67 |
| 8 | DOI用https://doi.org/前缀 | https://doi.org/10.1037/rev0000106 |
| 9 | 书名斜体+sentence case | *Cognitive psychology: A student's handbook* |
| 10 | 条目末尾无句号（如以DOI结尾） | DOI链接后不加句号 |
中文文献补充规则：
- 中文文献也使用
&连接最后两位作者（不用"和"）
- 博士论文格式：
作者. (年份). *标题* [博士学位论文, 院校名称]. 数据库名称.
- 中文期刊名不斜体
脚本使用指南
convert_refs.py — Markdown转Word
python scripts/convert_refs.py input.md output.docx
python scripts/convert_refs.py input.md
脚本自动处理：元数据跳过、分类标题识别、期刊名斜体渲染、方括号注释清理。
validate_checklist.py — 清单校验
python scripts/validate_checklist.py checklist.md final_refs.md
执行五项校验：
- 内容一致性：清单引用的文献内容与终版文件逐字匹配
- 分类准确性：D类标注与验证总报告一致
- 完整性：所有C类和未修复问题都已覆盖
- 编号连续性：每类内序号连续，总数与统计表一致
- 统计交叉验证：总文献数 = 无需审核数 + 需审核数
Performance Notes
- 验证阶段是耗时最长的环节。每批25-30条文献分配一个SubAgent，最多12个并行，每批使用双数据库（Semantic Scholar + OpenAlex）交叉验证
- 质量优先于速度：不跳过任何验证步骤，不因为数据库响应慢就放弃第二个数据库的查询
- 评审循环控制在1-2轮：通过规则扫描器+专家评审并行的首轮全覆盖设计，争取首轮发现90%+问题，减少迭代轮数
- 所有SubAgent必须使用Opus 4.6模型
变更记录
- S7（2026-06-23，Lane C）：Verifier 角色整体重写为 HTTP 主路径（
scripts/verify_http.py）/ MCP 在场时可选补充——运行环境无 SS/OpenAlex MCP，接受降级走 OpenAlex/CrossRef 公开 HTTP API。清除原强制加载 MCP 块中"环境中 MCP 一定可加载"的过度断言与"必须先加载 MCP 才能核验"的前置强制，并移除 S3 留下的本节待办标注。verification_guide.md §1 同步收口。
