PaperSpine 引文阶段实战指南:构建可验证的引文支撑库(Citation Support Bank)
PaperSpine 引文阶段实战指南:构建可验证的引文支撑库(Citation Support Bank)
导读:本文围绕 PaperSpine 编排器(paper-spine orchestrator)的官方引文阶段手册 citation.md 展开,系统讲解从文献检索、范围合约解析、支撑库建表到自动化验证的完整流程。你将掌握:按
literature_scope区分开放文献与封闭语料库的判定规则、14 列支撑库表格的规范写法、Source ID与Claim Use ID的计数语义,以及citation_bank_check.py、citation_quality_audit.py、citation_verification_en.py、citation_verification_zh.py四把验证工具的完整用法,最终能独立产出、核验并交付一份可被论文各章节直接采用的引文支撑库。
引文阶段在 PaperSpine 工作流中的定位
PaperSpine 的引文阶段(Citation Stage)是一份规范阶段手册(canonical stage playbook),其唯一使命是:构建一个经过验证的引文支撑库(citation support bank),用于支撑用户论文手稿中的文献陈述。它明确区别于示例学习(exemplar learning)——示例论文教的是写作结构与目标场景修辞,而引文支撑库中的论文支撑的是用户在 Introduction、Related Work、Discussion、limitations、applications 与 background 中具体的文献论断,两者互不替代(详见配套文档 citation-support-bank.md)。
从编排器视角看,引文阶段位于研究(Research)之后、语义确认(Semantic Confirmation)之前。在 orchestrator-branch-map.md 保留的 Legacy Runner 13 阶段合约中,第 3 阶段 citation 的产出物正是 citation_support_bank.md,对应 Gate 为 citation;而 SKILL.md 的“Research, target learning and citations”小节则把 citation.md 列为必读方法之一。需要特别指出的是:该阶段手册服务于当前 host 的正常写作,历史 Runner 的 bank 模式与配额并不为正常 host 写作增设门槛——这一点在原文开篇即被强调。
文献检索优先级协议(Literature Retrieval Priority Protocol)
采集文献时按以下优先级执行,并为每条引文记录来源渠道(Source Channel):
- Literature MCP 工具(首选):若 host 配置了 MCP 服务器,优先使用,并为每条引文记录渠道标记:
MCP-CNKI、MCP-IEEE、MCP-PubMed、MCP-Crossref、web、local或unknown。 - Host WebSearch / 浏览工具(后备):渠道标记为
web。 - 本地文件:渠道标记为
local。 - MCP 是增强而非依赖:当没有 MCP 时,完全可以从 web / local 来源构建支撑库,无需阻塞写作。
协议的要点在于渠道必须逐行落表。Source Channel 不是装饰性字段——它直接决定后续验证工具是否将该行视为“外部来源”并强制要求填写验证信息(详见下文“共享规则”)。
文献范围合约(Literature Contracts):open_literature 与 closed_corpus
在开始采集之前,必须先行解析 literature_scope,它只有两种合法取值:
| 取值 | 适用场景 | 行为约定 |
|---|---|---|
open_literature |
任务允许文献发现,或需要新的 SOTA / 领域地图 | 扩大候选池以填补 background、methods、close comparisons、interpretation 的实际覆盖缺口;已保存的最终参考文献目标不是候选池的乘数,也不是时效配额 |
closed_corpus |
仅允许引用供给材料(evidence-bounded rewrite) | 对可用文献做去重并穷尽盘点;尽量达到计划最终引文目标;当语料更小时标注 CLOSED_CORPUS_EXHAUSTIVE 并报告实际总数;不得因为固定语料偏旧或不足 3 倍而阻塞写作 |
判定规则有一条硬约束:只有当用户显式限制可用文献只能来自供给来源时,才解析为 closed_corpus。单独出现本地路径、specified_paths、rewrite_existing 或 materials_only 并不会把公开文献关闭成封闭语料库;显式的离线指令限制的是检索行为,而不是对已可得来源的身份核验。换言之,离线只影响“还能不能去查新文献”,不影响“已经拿到的文献能不能核验其身份与支撑点”。
这一判定逻辑在源码中同样存在:src/scripts/_paper_spine_utils.py 的 literature_scope() 函数会先读取显式配置,若为 auto 则依据 workflow == "rewrite_existing" 且 reference_mode == "specified_paths" 或需求文本含“no network / local only / 禁止联网 / 仅本地”等短语才收敛到 closed_corpus,否则默认返回 open_literature。这与 playbook 的“仅显式用户限制才关闭文献”口径完全一致。
引文支撑库的表结构与字段语义
手册定义了 Legacy 表格检查器接受的输入格式(14 列),这也是 citation-support-bank.md 中“供 legacy 检查器使用的可选表格”的标准骨架:
| Candidate ID | Source ID | Claim Use ID | Reference/BibTeX | Year | Recency | Supports Section | Support Claim Sentence | Why This Paper Fits | Source | Source Channel | Verified | Verification Note |
|---|
字段语义要点:
Source ID标识论文本身;Claim Use ID标识该论文在手稿中的一次具体使用。一篇论文可以支撑多条声明,但对 source-coverage、recency、diversity 配额只贡献一次。- 每行 = 一篇论文 + 一到两句可直接写入手稿的支撑句。支撑句不得虚构源元数据、摘要或用户提供的 PDF/文本中不可见的结果。
Reference/BibTeX列必须含一种可引用格式:BibTeX、DOI、URL、arXiv ID,或足以让用户核实完整书目元数据。- 手稿写作时只选取生成连贯 Introduction 与 Discussion 段落所需的最小子集,不能把全部候选倾倒进最终论文。
为便于理解,citation-support-bank.md 给出了一个完整示例行:
| Candidate ID | Source ID | Claim Use ID | Reference/BibTeX | Year | Recency | Supports Section | Support Claim Sentence | Why This Paper Fits | Source | Source Channel | Verified | Verification Note |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| C001 | S001 | U001 | Vaswani et al. "Attention Is All You Need." arXiv:1706.03762 | 2017 | foundational | Related Work | Prior work established self-attention as a replacement for recurrence. | Foundational transformer paper the method builds on. | arXiv | arxiv | yes | Confirmed via arXiv abstract page; arXiv:1706.03762 title matches. |
注意该示例行的 Verification Note 同时记录了稳定标识符(arXiv:1706.03762)和核验方式(title match on arXiv abstract page)——这正是外部渠道验证的最低要求(见下节)。
去重规则
按 DOI、PMID、arXiv ID、BibTeX key、URL 或归一化引文 去重。多条 claim-use 对 source coverage / recency / diversity 只计一次。开放文献模式下若检索无法达标,记录 SOURCE_COVERAGE_BLOCKED;封闭语料库模式下记录 CLOSED_CORPUS_EXHAUSTIVE 与实际来源总数。严禁克隆行充数。
去重逻辑在源码中有直接映射:src/scripts/citation_bank_check.py 的 source_identity() 按“DOI → arXiv → PMID → BibTeX key → URL → Source ID → 归一化文本”的优先级为每行提取稳定身份,其注释明确写道:Claim-use rows may legitimately repeat a paper, but repeated uses must never inflate source coverage or recency quotas,并刻意优先取书目标识符而非 agent 本地 Source ID,防止“给同一篇论文换标签”来虚增覆盖率。
共享规则(Shared Rules):验证纪律
支撑库的可用性取决于以下几组硬性规则,全部继承自原文:
Source Channel每行必填,取值包括MCP-CNKI、MCP-IEEE、web、local、unknown(citation-support-bank.md 扩充为MCP-CNKI、MCP-IEEE、MCP-PubMed、MCP-Crossref、web、arxiv、publisher、local、unknown)。- 外部渠道不得留空验证:对
web、MCP-*、Crossref、PubMed、Scholar、Semantic Scholar、IEEE、CNKI、WOS等外部渠道,Verified必须为yes/verified/pass/true,且Verification Note必须说明核验方式(DOI 匹配、标题匹配、Crossref/PubMed 页面、出版社页面、数据库记录或本地 PDF 元数据)。 Verified=yes本身不是验证:若未记录稳定标识符(DOI、arXiv ID 或 URL),仅凭一个标记属于自证(self-attestation),不会达到verified状态;标识符加核验方式缺一不可。- 本地来源同样需要核验:本地文件仍须做书目身份与引用语境检查,记录该文件实际支撑了什么、以及未解决的血统问题。
local渠道或空白的验证字段不是验证证据。 - 未决候选必须保持可见 pending 状态,与 adopted 来源分离:不能为了通过检查而更改来源渠道来掩盖疑问。Legacy 检查器可能拒绝 pending 行,那诊断的是输入 bank 本身的问题,不是停止已受支持写作的理由。
- 支撑库只是候选池,最终写作从中选出连贯的子集。
四步流程(Flow):Collection → Verification → Coverage → Curation
- 采集轮(Collection pass):构建初始候选池,每行填好
Source Channel。 - 验证轮(Verification pass):逐行验证所有外部来源,填写
Verified与Verification Note;在适用处运行citation_quality_audit.py与citation_verification_en.py。 - 覆盖检查(Coverage check):严格区分
unique_source_count与claim_use_count。若最终目标出现缺口,应寻找并整合相关的、已验证的支撑来弥补,不得静默降低请求的覆盖度;若确因显式语料限制或投稿规则无法达成,则报告冲突与实际覆盖情况。CLOSED_CORPUS_EXHAUSTIVE只是 legacy 检查器用来标记“供给语料已穷尽”,不是另一个写作门槛。两种模式下都禁止复制 use 行来充数。 - 策展(Curation):手稿只使用已验证、语境匹配的来源;未决候选保持独立,并继续基于已有的有效证据推进写作,不允许某个未用候选的空白字段阻塞全部写作。
候选库诊断与最终比对(Candidate-bank diagnostics)
引文目标的来源有两种:用户保存的 custom 计数,或 journal-learning.md 中统计的目标期刊样本。journal-learning.md 规定:venue_average 模式下应统计选定可比目标期刊论文的参考文献条数、记录观测均值,并至少达到 floor(mean) + 1 条有用引用(这是基于样本的估计而非期刊级精确平均值,禁止使用被引次数,用户可用 custom 覆盖)。
关键诊断口径:要把已解析目标与当前手稿中实际被引的不同条目做比对——而不是与 bank 规模、use 行数或未被引的 BibTeX 条目做比对。bank 检查并不执行这最后一层比对。若发现不足,应去定位有用但缺失的文献并整合其支撑点;真实的 scope / venue 冲突要如实报告,不能把一个结构性诊断的 PASS 静默当成“已满足偏好”。配套文档同样强调:大候选库无法替代这一步最终对账。
诊断命令全集(原文完整继承)
python scripts/citation_bank_check.py <existing-bank.md> --target-count <resolved-target> --scope open_literature --markdown
python scripts/citation_bank_check.py <existing-bank.md> --target-count <resolved-target> --scope closed_corpus --markdown
python scripts/citation_quality_audit.py paper_rewriting_output --write
python scripts/citation_verification_en.py paper_rewriting_output/citation_support_bank.md --markdown --write
以上命令从仓库根目录的 src/scripts/ 目录运行,脚本路径对应仓库内的 src/scripts/citation_bank_check.py 等实现。
验证工具链源码解析
1. citation_bank_check.py —— 候选库结构与唯一来源检查
src/scripts/citation_bank_check.py 定位为“Validate PaperSpine citation_support_bank.md”,即只检查候选库的结构与来源身份,不核验引文真伪、最终被引覆盖或手稿就绪度(该边界同时写在其 Markdown 报告与源码 docstring 中)。关键实现事实:
- 命令行参数:
path(默认paper_rewriting_output/citation_support_bank.md)、--target-count(默认 0,省略即不评估覆盖)、--multiplier(默认 1)、--recent-years(默认 3)、--recent-ratio(默认 0.0)、--scope(二选一)、--markdown/--json/--write。默认值设计体现“无通用期刊目标、无发现乘数、无时效配额”的取向。 - 表识别:
find_citation_table()要求表头同时含 reference/citation/bibtex 类词、claim与sentence词。 - 行质量:
has_claim_sentence()要求整行拼接后长度 ≥ 80 且含句末标点;has_reference_format()要求出现@、doi、http、arxiv、proceedings、journal之一(tests/test_scripts.py 中有大小写不敏感的回归测试,如"Conference proceedings"、"arxiv:2305.14314"均判定为有引用格式)。 - 配额逻辑:
required_candidates = target_count(closed_corpus)或target_count * multiplier(open_literature);unique_source_count按source_identity()去重后统计;重复 use 会以duplicated_source_uses曝光。closed_corpus 下 recency 与 3 倍发现广度转为建议性(见 tests/test_readiness_gates.py 的test_closed_corpus_accepts_real_local_pool_and_makes_recency_advisory:30 个本地来源、20 个目标、recent-ratio 0.8 依然 PASS,且警告中提示 recency 是 advisory)。 - 输出:
--write将citation_bank_check.md写到 bank 同目录;退出码 0 = PASS,1 = FAIL。
2. citation_quality_audit.py —— 教学导向的引文质量审计
src/scripts/citation_quality_audit.py 超越单纯的 DOI 核验,从**可解析性(resolvability)、时效性(recency)、领域相关性(relevance)**三个轴对每条引文打分,并产出多样性缺口分析与场景化引文策略。核心实现事实:
- 表读取:复用
_paper_spine_utils.markdown_tables(),要求同样的表头识别条件。 - DOI 核验:优先走
fetch_crossref()(Crossref REST API,https://api.crossref.org/works/<doi>);标题相似度title_similarity()采用 Jaccard 与 SequenceMatcher 各 50% 加权,≥ 0.75判 verified、0.50–0.75判 mismatched(疑似 DOI 张冠李戴)、更低判 mismatched(很可能 DOI 指错了论文);年份不一致会追加Year mismatch问题。 - 无 DOI 行:若
Verification Note记录了稳定标识符(arXiv ID 或 URL)且Verified取值合法,则给 resolvability 80 分并标记 pending(其 teaching note 强调:bank 记录的具体非 DOI 核验源,本次运行未重新核验,只是结构上可接受);若只有 verified 标记而无稳定标识符,判为 self-attestation,resolvability 仅 35 分且不得进入 verified 状态——这是对“验证纪律”的源码级落实。 - 类型分类与缺口分析:
classify_citation_type()将引文分为sota/foundational/benchmark/survey/application/critique六类;SCENE_CITATION_GUIDANCE针对 journal / conference / report_review / competition 四类场景给出差异化建议(例如会议评审“激进检查时效性”,综述型报告“survey 必不可少,3–5 篇”);某类型占比 < 5% 且非 critique 时生成缺口建议。 - 通过阈值:
--min-score(默认 60)、--max-error-ratio(默认 0.30)、--max-pending-ratio(默认 0.50);--no-api跳过网络仅做结构分析;--max-dois限制 API 调用数(默认 30)。 - 测试佐证:tests/test_citation_quality_audit.py 覆盖 DOI 提取、六类分类、时效打分、标题相似度、
--no-api下 DOI 行保持 pending 等行为。
3. citation_verification_en.py —— 英文引文 Crossref 核验
src/scripts/citation_verification_en.py 仅用标准库实现,将 citation_support_bank.md 中的候选引文与公开 Crossref REST API(免 key)对账。关键事实:
- 元数据提取:
_extract_doi()(10.xxxx/...正则)、_extract_year()(1900–2030)、_extract_author()(BibTeX key → “Surname, X.” → 首个像姓的大写词)、_extract_title_query()(带引号标题 → 年份与期刊标记之间的文本 → 最长句段)。 - 匹配规则:标题相似度阈值
MIN_TITLE_SIMILARITY = 0.6,年份容差 ±1(YEAR_TOLERANCE);优先 DOI 精确查询,无 DOI 时走query.bibliographic检索(返回 3 条候选,逐一匹配标题与年份)。 - 年份口径:优先使用
issued/published-print/published-online/published字段,仅在这些缺省时才退回created(注册年份可能与老文献出版年不同)——tests/test_citation_verification_en.py 的test_resolvable_doi_with_year_mismatch_is_matched_not_failed验证:本地 2018 年、Crossref 仅返回 created=2010 时,条目仍判matched但备注中写明 “year differs”。 - 渠道纪律:
local渠道行永不查询 Crossref,直接标记 skipped(“local source — not checked against Crossref”);--no-api完全离线,所有本应查询的条目标记 skipped 且永不失败(测试断言"ok": true)。 - 输出:
--write生成citation_verification_en.md;报告头部明确 PASS 不是完整的书目审计——skipped 条目、作者/venue 归属与 claim support 仍需人工复查。
4. citation_verification_zh.py —— 中文引文格式与 DOI 诊断
src/scripts/citation_verification_zh.py 面向中文参考文献,但刻意只做格式与 DOI 可用性诊断,不推断造假、不完成完整验证(docstring 与报告头均明确声明)。其启发式包括:中文作者名正则、《期刊名》 识别、4 位年份、卷号 \d+[卷\((]、页码区间 \d+[-~]\d+。诊断结果分为 INCOMPLETE(文本过短 / 缺作者、期刊、年份)、SUSPICIOUS(有 DOI 但 Crossref 查询失败,或 DOI 解析成功但“身份仍未验证”,或无 DOI 需经原始论文 / 出版社 / 权威中文索引核实)两类——注意这里 SUSPICIOUS 的语义是“待人工核实”,绝非“造假结论”。中文诊断报告写入 citation_verification_zh.md。
输出位置与配套文档衔接
引文支撑库的写入路径固定为:
paper_rewriting_output/citation_support_bank.md
但手册同时给出了两个务实口径:
- 在使用一条引文之前,先确立其身份以及它支撑了什么;已存在的已验证笔记即可复用,“单独命名一个 bank”并非写作前置条件。
- 最终对账不可被候选库规模替代:按 citation.md 所述方法,把最终实际被引条目与已保存目标调和一致。
就当前 host 工作而言,引文阶段与两份相邻 playbook 协同:公开文献范围由 journal-learning.md 定义(两个阅读集、venue_average 目标、PDF 学习要求),而发出文献的标记、书目链接与格式验证由 manuscript-format.md 负责(引用键、[@key]、CSL、Pandoc citeproc 等)。重写、本地材料路径或 materials_only 设置本身都不会把公开文献限制为封闭语料库——只有显式的用户限制才会,这一原则贯穿本文全部操作。
一次完整的引文阶段演练(综合示例)
综合以上所有规则,一次规范的引文阶段执行可以这样落地(在仓库根目录运行,脚本位于 src/scripts/):
# 1) 采集后先做候选库结构检查(开放文献模式,目标 20 篇)
python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md \
--target-count 20 --scope open_literature --markdown --write
# 2) 引文质量审计(含场景化引文策略,默认 scene=journal,写报告)
python src/scripts/citation_quality_audit.py paper_rewriting_output --write
# 3) 英文引文 Crossref 核验(含 --delay 限速、--max-checks 上限)
python src/scripts/citation_verification_en.py paper_rewriting_output/citation_support_bank.md \
--markdown --write --delay 0.5 --max-checks 30
# 4) 中文引文格式诊断
python src/scripts/citation_verification_zh.py paper_rewriting_output --write
执行顺序建议严格遵循 Flow 的“采集 → 验证 → 覆盖 → 策展”:先保证每行 Source Channel 齐全,再运行验证工具补齐 Verified 与 Verification Note,随后以 unique_source_count 对账目标并补缺,最后只把“已验证 + 语境匹配”的子集写进手稿——让引文支撑库真正成为手稿的可靠证据底座,而非一个自我满足的表格。
说明:本文所述 playbook citation.md 与配套文档 citation-support-bank.md 在仓库
paperspine5/core/01_PaperSpine4/src/skill/references/与src/skill/references/下各有一份同步副本;四把验证脚本同样以paperspine5/core/01_PaperSpine4/src/scripts/与src/scripts/双目录形式发布,本文统一以src/scripts/相对路径引用。