• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用

本篇技术指南围绕 PaperSpine5 学术写作工作流中的「本地参考文献摄入（Local Reference Ingestion）」机制展开，讲解 Agent 如何在撰写论文前优先建立本地文献索引、正确处理付费数据库、图书馆导出、CNKI/CAJ 文件与私有文献文件夹等无法从开放网络合法获取的资料，并产出可被后续引用环节复用的source_index.md索引。读完本文，你将掌握三种文献摄入模式的选择逻辑、reference_inventory.py索引脚本的完整用法与参数语义、Source Index 表结构规范，以及本地文献在证据边界上的正确使用方式。

一、为什么需要「本地优先」的文献摄入

PaperSpine 的核心原则是local-first, evidence-bound：论文的证据必须可追溯、有据可依。然而研究过程中很大一部分资料并不存在于开放网络：

• 付费数据库（paywalled databases）收录的期刊全文；
• 图书馆数据库导出的文献记录；
• 用户自行下载的 PDF；
• 中国知网（CNKI）的 CAJ 格式文件，以及 KDH、NH 等衍生格式；
• 课程资料、竞赛手册（competition handbooks）、私有参考文献文件夹。

这些资料 Agent 无法（或不应）从开放网页合法获取，却是文献综述、引用扩充与目标期刊风格学习的重要素材。PaperSpine 的应对策略是强制要求 Agent 优先读取用户提供的本地参考文献，仅当本地资料存在缺口时，才使用网络检索进行补充。这一规则记录于 local-reference-ingestion.md，并在整个 Skill 编排中通过 SKILL.md 的 Research 阶段（# 2. Research, target learning and citations）强制引用执行。

二、三种摄入模式（Modes）与选择逻辑

关联文档定义了三种文献摄入模式，其语义与适用场景如下：

需要注意的一点（来自 intake.md 的遗留配置字段表）：reference_mode与reference_paths是 intake 阶段可保存的配置项，reference_mode默认值即local_first，reference_paths默认值为["."]。而 current-method-routing.json 中对本地参考的封装说明明确指出：specified_paths不等于禁止联网——它只规定摄入的先后顺序，并不关闭公开文献检索；同理，固定路径source_index.md也可按任务需要替换。

三、强制行为规范（Required Behavior）

关联文档列出了六条 Agent 必须遵守的行为规范，构成本地文献摄入的完整操作契约：

1. 创建输出目录：先建立paper_rewriting_output/reference_materials/，作为本地文献索引的固定落盘位置。
2. 运行或模拟索引脚本：在本地默认路径上运行scripts/reference_inventory.py（或等价地完成其行为）。
3. 写出索引文件：生成reference_materials/source_index.md。
4. 记录本地路径：每个本地来源都必须在其Origin/URL/Path与Local File/Note两列中记录自身的本地路径。
5. 证据边界隔离：不得把本地参考文献当作本稿研究结果（results）的用户证据；本地文献仅可用于支撑文献背景、引用扩充、目标风格学习与背景性论断。
6. 不绕过付费墙：绝不绕过 paywall 或登录限制。若某篇论文无法合法获取，应请用户提供合法本地副本或引文元数据（citation metadata）。

其中第 5 条在 research.md 的文献研究章节被进一步强化：References teach method and visual communication and may support attributed background, methods and mechanisms. Their empirical findings must never be presented as this study's results.（参考文献可以教授方法、视觉表达，并支撑署名引用的背景、方法与机制；但其实证结论绝不能被呈现为本研究的结果）。

3.1 索引是整个审计链的硬性前置条件

source_index.md并非可有可无的中间产物，而是 PaperSpine 审计阶段的强制检查项。在 audit.md 的 Required Checks 列表中，第 2 条明确要求：Reference material workspace has source_index.md（参考资料工作区必须存在source_index.md）。这意味着本地文献摄入环节的缺失会直接阻断后续审计通过。

四、Source Index 表结构规范

关联文档给出了索引文件的核心表结构：

Source ID 稳定性要求：应使用稳定的来源编号（如REF001、REF002），并保证这些编号在research_dossier.md、citation_support_bank.md和writing_rationale_matrix.md中可复用。

• citation_support_bank.md的候选表把Source ID作为「引用库身份标识」，配合Claim Use ID建立「来源 → 论断用途」的映射（见 citation-support-bank.md）；
• writing_rationale_matrix.md的逐行写作决策表通过Reference/SOTA Pattern Learned与User Evidence or Citation Anchor两列引用这些编号，使每个写作单元都能锚定具体文献（见 writing-rationale-matrix.md）。

这种「一处编号、多处复用」的设计，保证了文献来源在「研究 → 引用库 → 写作决策」全链路中的可追溯性。

五、reference_inventory.py：索引脚本源码级解析

关联文档要求「运行或模拟scripts/reference_inventory.py」。该脚本位于 reference_inventory.py（dist下的多宿主发布版本内容一致，如 dist/openclaw 版本），其职责是：把本地参考材料索引为source_index.md。

5.1 命令行参数

python scripts/reference_inventory.py [paths ...] [--output-dir DIR] [--mode MODE] [--max-files N] [--json]

5.2 文件类型分类表（REFERENCE_EXTENSIONS）

脚本通过扩展名将本地文件归类为七种kind，这一分类会直接写入 Source Index 的Type列：

可以看到，脚本对 CNKI 生态（CAJ/KDH/NH）、文献管理工具导出（BibTeX/RIS/EndNote）、LaTeX 模板三件套（.tex/.cls/.bst）都做了专门分类，覆盖了本地学术资料的绝大多数形态。

5.3 索引生成的实现细节

• 扫描逻辑（iter_files）：对每个根路径递归展开（rglob("*")），仅收录扩展名命中的文件；跳过paper_rewriting_output与.git目录（避免把输出和版本库当成文献）；按path.resolve()去重；达到--max-files上限即停止。
• 条目生成（make_items）：source_id从REF001起顺序编号（f"REF{index:03d}"）；title取自文件名主干，并把下划线与连字符替换为空格；origin与local_file均记录文件的绝对/相对路径；why_included依模式不同自动生成——web模式为User-provided local seed for web-supported reference research.，specified_paths为User-specified local reference material.，其余为Local/current-folder reference material collected before web supplementation.；used_for固定为reference reading, source indexing, citation support, or target-scene learning。
• Markdown 输出（to_markdown）：文件头写入# Source Index、Reference mode与Indexed items计数，随后输出与关联文档一致的七列表格。
• 落盘与退出（main）：创建输出目录、写文件；--json时打印 JSON 数组（ensure_ascii=False），否则打印Wrote ... with N indexed reference items.。

5.4 测试验证

仓库测试 test_scripts.py 中的test_reference_inventory_indexes_local_paths用例直接验证了该脚本的端到端行为：在临时目录构造refs/paper.pdf与refs/notes.txt，以--mode specified_paths运行脚本，断言返回码为 0、source_index.md存在于out/reference_materials/下，且索引文本同时包含specified_paths模式标记与paper.pdf的路径。此外 test_skill_structure.py 与 test_artifact_check.py 也涉及该机制的完整性/工件检查。

六、本地文献在下游环节的正确用法

6.1 引用库的 Source Channel 标记

在 citation.md 的文献检索优先级协议中，本地文件是第三优先级来源，且必须在citation_support_bank.md中把Source Channel标记为local。与网络来源不同的是，local渠道本身不构成验证证据——citation-support-bank.md 明确要求：Local sources still require bibliographic identity and cited-context checks. Record what the actual file supports and any unresolved provenance; a local channel or a blank verification field is not evidence of verification.也就是说，本地 PDF 同样需要核实书目身份与引用上下文，不能因为「文件在本地」就默认可信。

6.2 与 closed_corpus 的区别

一个常见误区是「本地文献 = 封闭语料库」。关联文档与 citation.md 都强调：仅当用户显式把可用文献限制为已提供的来源时，才把引用库解析为closed_corpus。local_first、specified_paths、rewrite_existing或materials_only等设置本身都不会关闭公开文献通道——它们只改变摄入顺序。这保证了「本地优先」不会演变成「只看本地」的视野收窄。

6.3 本地文献可用于哪些用途

综合关联文档、citation-support-bank.md 与 research.md，本地参考文献的合法用途包括：

• 支撑引言（Introduction）、相关工作（Related Work）、讨论（Discussion）中的文献背景论断；
• 扩充引用库（citation expansion）与目标风格/目标场景学习（target style learning）；
• 支撑背景性、方法论与机制类论断（需注明出处）。

禁止用途：把本地文献的实证结论当成当前研究的结果；把未验证的候选文献用于支撑最终论断（应显式标记[VERIFY]或pending）。

6.4 翻译包的本地化副本

当output_language为en且translation_package为zh时，整个工作流需要输出中文阅读辅助包，其中就包含本地索引的翻译副本reference_materials/source_index.zh.md——见 translate.md 的通用文件清单与 translation-package.md 的目录结构要求。这印证了source_index.md是贯穿「研究 → 写作 → 审计 → 交付」全流程的基础产物。

七、实践要点小结

1. 默认即本地优先：reference_mode默认local_first，任何论文生产任务都应先建立paper_rewriting_output/reference_materials/source_index.md。
2. 用脚本而非手工：直接运行python scripts/reference_inventory.py <path> --mode <mode>，脚本会自动完成扩展名分类、REF001编号、去重与 Markdown 表格生成。
3. 稳定编号跨文档复用：REF001等编号要在research_dossier.md、citation_support_bank.md、writing_rationale_matrix.md中保持一致，保证文献来源全程可追溯。
4. 严格证据边界：本地文献支持文献背景与风格学习，绝不充当本研究结果证据；本地来源仍需书目身份与引用上下文核验。
5. 不绕过访问限制：付费墙与登录限制不可绕过，缺失全文时应请求用户提供合法副本或引文元数据。
6. 审计硬门槛：缺少source_index.md会直接违反 audit.md 的强制检查项，导致工作流无法通过审计。

• AI 技能
• AI 写作
• 人工智能
• 深度研究
• AI 应用