academic-ref-check

# 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。 **操作要点：** 1. 识别多行断裂的文献条目（标题和期刊名被分割成多行的情况），合并为完整条目 2. 识别非标准引用格式（Nature风格、编号格式`[2]`、中文`[J]`标注等） 3. 为每条文献生成指纹ID（规则见核心规则第1条） 4. 提取结构化字段：作者、年份、标题、来源、卷期页码、DOI、文献类型、语言 5. 标记已识别的格式问题（DOI格式错误、全角标点混用、注释残留等） **去重规则：** - DOI完全相同 → 保留更完整的版本 - 标题相似度>90%且年份相同 → 保留更完整版本 - 预印本vs正式发表版 → 保留正式发表版 ### 格式化器（Formatter） **职责：** 将结构化文献数据按APA第七版格式输出。 Before formatting, read `references/apa7_rules.md` for the complete APA 7th edition formatting rules. **操作要点：** 1. 作者格式：`姓, 名首字母.`，1-20位全列，21+使用省略号规则 2. 标题：sentence case（仅首字母和专有名词大写） 3. 期刊名：title case + 斜体（Markdown中用`*期刊名*`标记） 4. DOI统一为`https://doi.org/`前缀格式 5. 排序：中文文献按拼音在前，英文文献按字母在后 6. 中文文献也使用`&`连接最后两位作者 ### 验证器（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 脚本： ```bash python3 scripts/verify_http.py --in refs.json --out-dir <dir> # 结构化 JSON 输入 python3 scripts/verify_http.py --in-text refs.md --out-dir <dir> # 原始文本/Markdown 引用列表（自解析） ``` - 产物：`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. **操作要点：** 1. 仅修复B类中置信度为"高"的条目。中/低置信度一律转入C类报告 2. 每次修复必须同时在修复操作记录中记录：指纹ID、修复类型、修复前值、修复后值、修复依据 3. 修复完成后校验文献总数守恒（修复不应增删文献） 4. 更新修复状态汇总表 **典型可自动修复的场景：** DOI补充/格式修正、明显年份错误（如2026→2025）、sentence case转换、期刊名PubMed注释去除、标点符号修正、排序修正。 **典型仅报告的场景：** 作者列表大幅变动、标题实质性差异、卷期页码大幅不一致、数据库未收录的文献。 ### 规则扫描器（Rule Scanner） **职责：** 对终版文献执行全量逐条规则检查，确保100%覆盖。 Before scanning, read `references/apa7_rules.md` for the complete checklist of rules to verify. **与专家评审的区别：** 规则扫描器检查的是可程序化判断的格式规则（有明确的对/错标准），专家评审处理的是需要学术判断力的问题。 **必须逐条扫描的规则（每条文献都检查）：** 1. Sentence case（英文标题仅首字母和专有名词大写） 2. 作者间的`&`号（中英文文献均需检查） 3. DOI格式（`https://doi.org/`前缀，无多余空格/重复前缀） 4. 期刊名斜体标记（`*期刊名*`） 5. 标点符号规范（半角、句末句号、逗号位置） 6. 年份格式（括号内，逗号后） 7. 排序正确性（中文拼音、英文字母） 8. 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. **强制执行的生成流程：** 1. 读取终版文献文件，建立指纹ID→终版内容的完整映射表 2. 读取验证总报告，提取C类和D类条目 3. 读取修复状态汇总表，排除已修复的条目 4. 读取专家评审报告，提取未修复的问题 5. 合并得到"待审核项目池" 6. 对每个待审核项目，通过指纹ID从步骤1的映射表中提取终版内容（不从验证报告复制） 7. 按五类分类组织清单 8. 执行一致性校验（使用`scripts/validate_checklist.py`） **五类分类：** 1. 必须处理（Must Fix） 2. 数据库未覆盖（Not Found） 3. 自动修正需复核（Auto-fixed, Please Verify） 4. 信息补充建议（Suggested Additions） 5. 仅供知晓（FYI） ### Word转换器（Word Converter） **职责：** 将终版Markdown文献文件转换为符合博士论文排版标准的Word文档。 使用 `scripts/convert_refs.py` 执行转换： ```bash 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 ```bash # 基本用法 python scripts/convert_refs.py input.md output.docx # 默认输出（与输入同名.docx） python scripts/convert_refs.py input.md ``` 脚本自动处理：元数据跳过、分类标题识别、期刊名斜体渲染、方括号注释清理。 ### validate_checklist.py — 清单校验 ```bash python scripts/validate_checklist.py checklist.md final_refs.md ``` 执行五项校验： 1. 内容一致性：清单引用的文献内容与终版文件逐字匹配 2. 分类准确性：D类标注与验证总报告一致 3. 完整性：所有C类和未修复问题都已覆盖 4. 编号连续性：每类内序号连续，总数与统计表一致 5. 统计交叉验证：总文献数 = 无需审核数 + 需审核数 ## 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` 同步收口。