PaperSpine 引文阶段实战指南:构建可验证的引文支撑库(Citation Support Bank)

原创2026-10-12 11:28:261,636 阅读
文章标签:人工智能AI 技能AI 写作

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):

  1. Literature MCP 工具(首选):若 host 配置了 MCP 服务器,优先使用,并为每条引文记录渠道标记:MCP-CNKI、MCP-IEEE、MCP-PubMed、MCP-Crossref、web、local 或 unknown。
  2. Host WebSearch / 浏览工具(后备):渠道标记为 web。
  3. 本地文件:渠道标记为 local。
  4. 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

  1. 采集轮(Collection pass):构建初始候选池,每行填好 Source Channel。
  2. 验证轮(Verification pass):逐行验证所有外部来源,填写 Verified 与 Verification Note;在适用处运行 citation_quality_audit.py 与 citation_verification_en.py。
  3. 覆盖检查(Coverage check):严格区分 unique_source_count 与 claim_use_count。若最终目标出现缺口,应寻找并整合相关的、已验证的支撑来弥补,不得静默降低请求的覆盖度;若确因显式语料限制或投稿规则无法达成,则报告冲突与实际覆盖情况。CLOSED_CORPUS_EXHAUSTIVE 只是 legacy 检查器用来标记“供给语料已穷尽”,不是另一个写作门槛。两种模式下都禁止复制 use 行来充数。
  4. 策展(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

但手册同时给出了两个务实口径:

  1. 在使用一条引文之前,先确立其身份以及它支撑了什么;已存在的已验证笔记即可复用,“单独命名一个 bank”并非写作前置条件。
  2. 最终对账不可被候选库规模替代:按 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/ 相对路径引用。

登录后查看全文
PaperSpine