MinorBaek/wiki-ingest-book

wiki-ingest-book 是做什么的？

在首次录入前，请阅读工具包中的 docs/GOTCHAS.md（操作注意事项，包括书籍的页码偏移校准）。

将LLM维基的录入模式扩展到学术书籍。书籍上下文繁重，无法一次性录入，因此该技能采用两阶段方法：先进行书籍概览，再按需录入章节。

角色与边界

功能：创建书籍笔记，创建章节笔记，将发现传播到概念和方法笔记，更新索引和日志。

不做什么：不一次性阅读整本书（存在上下文限制风险），不发明元数据或章节标题，不重复论文录入流程（章节遵循与论文相同的概念传播规则）。

文件位置

路径来自 wiki.config.json（参见 wiki-ingest）。书籍和章节位于 <wiki_root>/books/ 目录。模板：templates/book.md 和 templates/chapter.md。存放PDF库的文件夹是配置中的 pdf_library_dir。

相关技能

• wiki-ingest：共享初始状态决策规则和用于索引路由的 field_titlecase_map。
• wiki-lint：每次章节录入后运行。检查项8（chapters_ingested 同步）和检查项9（章节 book: 前置元数据）可捕获最常见的书籍录入漂移。

必需契约（每次录入后必须保持）

1. 每个章节笔记位于 books/{book}_ChNN.md，其前置元数据必须包含 book: "[[{book_basename}]]"，且目标必须解析为现有的书籍笔记。写入后验证；如果缺失，wiki-lint 检查项9会标记。
2. 每次章节录入必须将该章节编号附加到父级书籍笔记的 chapters_ingested: 列表。附加后，列出 {book}_Ch*.md 并确认两个集合匹配；否则 wiki-lint 检查项8会标记漂移。
3. 初始状态遵循 wiki-ingest 状态表：仅定义时为 stub，进行中为 draft，章节笔记在有2个或更多有来源的发现时达到 final（章节本身就是一个来源）。派生的概念和方法笔记遵循严格的晋升规则：final 需要N个不同的源作品（min_distinct_sources_for_final，默认为2），因此仅基于这一本书构建的概念将保持 draft 状态，直到有第二个独立来源加以证实。
4. 索引路由使用 field_titlecase_map 将新概念和方法放置在正确的首字母大写字段子部分下，绝不会放在过时的汇总块中。

前言（在模式A或模式B之前始终执行）

1. 阅读 WIKI_SCHEMA.md。
2. 阅读模板：模式A使用 templates/book.md；模式B使用 templates/chapter.md（并参考 templates/book.md）。

工具：使用主机的文件工具（读取/写入/编辑）进行所有知识库写入。

---

本地PDF解析（全文优先）

默认文件夹：配置中的 pdf_library_dir（你的参考文献管理器的PDF存储位置）。 提取器：pdftotext（poppler）或，为获得更好的表格保真度，使用 docling。始终使用 -enc UTF-8 参数运行 pdftotext。

定位PDF：通过枚举和grep作者来定位，而不是使用glob工具，也不是使用 find -iname "*<author>*"；两者在某些文件系统上对已存在的文件有已知的假阴性：find "<pdf_library_dir>" -iname "*.pdf" | grep -i <first_author_lastname>。如果第一次搜索为空，则将根目录扩展到整个库（书籍也可能位于主题子文件夹中）。恰好1个匹配项：使用它。0个或超过1个：询问用户确切的路径。如果这也失败：回退到参考文献管理器的全文。

完整的解析算法、本地优先全文级联和MCP决策表、扫描PDF检测以及非ASCII文件名风险，请参见 references/BOOK-INGEST-WORKFLOW.md（第1节和第1bis节）。在首次提取新书之前阅读它。下面的主体仅保留每个章节使用的命令。

提取命令

• 目录/概览（模式A）：pdftotext -enc UTF-8 -f 1 -l 20 "<path>" -（前20页，标准输出）。
• 章节范围（模式B）：pdftotext -enc UTF-8 -f <pdf_start> -l <pdf_end> "<path>" -。-f/-l 参数使用PDF页码，而非书籍页码；使用偏移量从目录转换（下一节）。
• 将提取内容写入一个你将要 Read 的文件：长章节切片可能作为文件比作为标准输出更容易。将其写入项目内部（例如 _temp/{book}_Ch{NN}.txt），而不是写入操作系统特定的 /tmp 目录，因为Read工具可能无法打开该目录（Windows上的Git Bash将 /tmp 映射到Windows工具无法访问的位置）。

页码偏移校准（书籍页码不等于PDF页码）

书籍的目录列出的是书籍页码；而 pdftotext -f/-l 处理的是PDF页码。两者之间存在偏移（前页、图版），并且该偏移量在整本书中非线性增长（图表、表格、部分分隔符）。直接将目录页码传递给 pdftotext 会提取错误的页面，这是章节录入中最常见的时间消耗。在提取任何章节之前，每本书校准一次：

1. 选择一个已知书籍起始页的章节。估计 pdf_start = book_page + offset_guess（前页通常为20到60页）。
2. 仅提取其第一页，并确认章节标题出现。最多调整5页直到匹配。
3. 在书籍笔记中记录校准后的偏移量（例如 > [!note] PDF offset: book_pg + N = pdf_pg (zone: Part X) 位于目录附近），以便后续章节重用。
4. 对于长篇书籍，按区域或部分重新校准：单一固定偏移量会漂移（例如，某教科书第3章为+36，第21章为+56）。对于文本层PDF，按换页符分割文本可快速生成页面映射，包含准确的起始页。

---

模式A：书籍概览

触发指令：/wiki-ingest-book [标题]

1. 在参考文献管理器中解析：按标题搜索，然后获取元数据（标题、作者、编辑、年份、出版商、ISBN、版本、DOI、引用键）。
   • 年份后缀引用键注意事项（多卷或部分系列）：Better BibTeX 的引用键如 ...2019a / ...2019b 并不能可靠地映射到同一作者、同一年的系列的第1部分还是第2部分（后缀是消歧顺序，不是含义）。在命名笔记或信任你拥有的是哪一卷之前，务必从元数据中确认实际的标题（以及副标题或“第N部分”）。
2. 解析目录的全文（级联；参见“本地PDF解析”）：
   • 首选：pdftotext -enc UTF-8 -f 1 -l 20 "<local_path>" -（大约3到8k tokens）。
   • 回退1：参考文献管理器全文，仅当本地PDF不可用且输出少于2000词时使用。
   • 回退2：要求用户粘贴目录；标记为“来源：用户提供”。
   • 回退3：对知名教材使用模型知识；标记每个条目为 [!note]。
3. 确定文件名：FirstAuthor_Year_Keyword.md（第一作者的姓氏，仅限ASCII；关键词是书籍主要主题的1到3个词）。如果 books/{filename}.md 已存在，则就地更新。
4. 创建或更新书籍笔记位于 books/{filename}.md，使用 templates/book.md。将 last_verified 设置为今天的日期。
5. 填充目录来自步骤2。如果不确定，将章节标记为 ? 并注明限制。
6. 提取3到5个高层次主题（仅书籍层面，无章节特定声明）。轻度传播：仅当主题是研究线的核心且已有2篇或更多维基论文提及它时，才更新 concepts/ 笔记；否则仅在书籍笔记中列出。到达笔记的主题遵循证据表规则：模式B步骤6b和8b。
7. 治理检查：应用来自 wiki-ingest 步骤5的研究线匹配和概念与方法路由。在概览层面，仅注意哪些章节可能产生方法笔记与概念笔记；完整传播在模式B中进行。
8. index.md：如果索引嵌入了Bases视图，则不要添加书籍条目；仅当完成一个新的父级书籍录入时，才更新 ## Quick Stats 的“Books (ingested)”计数。在 manual 模式下，添加条目。切勿触碰冻结的旧索引。
9. 附加到 log.md：## [YYYY-MM-DD] ingest-book | {Title}: overview。
10. 报告：书籍笔记路径、已识别的主题以及可用于深度录入的章节（/wiki-ingest-book [标题] > 第N章）。

---

模式B：章节录入

触发指令：/wiki-ingest-book [标题] > 第N章（或 > Chapter: [章节标题]）

1. 读取现有的书籍笔记位于 books/FirstAuthor_Year_Keyword.md。

   • 如果不存在：停止。先运行模式A，然后重试。
   • 如果章节未列在目录中：追加状态为 pending 的行，在最终报告中说明，继续。
   • 如果章节已标记为 ingested：在覆盖前与用户确认（默认：就地更新，保留现有的 [[wikilinks]]）。

2. 解析章节内容（级联；参见“本地PDF解析”）：

   • 从书籍笔记的目录中获取章节页码范围，并使用记录的偏移量将书籍页码转换为PDF页码。仅当目录页码本身未知时才询问用户。
   • 首选：pdftotext -enc UTF-8 -f <pdf_start> -l <pdf_end> "<local_path>" -（典型章节为1k到8k tokens）。
   • 回退1：如果章节作为 bookSection 项拥有自己的库条目，则使用该项的全文。
   • 回退2：参考文献管理器中的整书全文，仅当本地PDF不可用且书籍少于5000词时使用。
   • 回退3：要求用户粘贴章节文本。
   • 回退4：模型知识，每个声明都使用 [!warning] 标记。此类内容永远不会到达概念或方法笔记，并且不会获得认证。

3. 章节文件名：FirstAuthor_Year_Keyword_ChNN.md（例如 Knuttgen_1987_Strength_Ch03.md）。

4. 创建章节笔记位于 books/{chapter_filename}.md，使用 templates/chapter.md。将 last_verified 设置为今天的日期。

   • 必需契约：在前置元数据中输出 book: "[[{parent_book_basename}]]" 并验证其可解析。如果不可解析，则父级笔记未录入：先运行模式A。
   • 初始状态：应用 wiki-ingest 状态表。仅填充了目录条目的框架章节为 stub；至少有2个有来源发现的章节为 final。
   • 证据级别：默认为 evidence_level: textbook。仅当章节本身是独立的系统评价或荟萃分析时，才覆盖为 SR-MA 或 SR。测量质量始终内联在发现中，绝不在前置元数据中。

5. 提取3到8个概念和1到4个方法：与 wiki-ingest 相同的提取规则（参见 references/BOOK-INGEST-WORKFLOW.md）。

6. 治理检查：与 wiki-ingest 步骤5相同的研究线匹配和概念与方法路由。为本章节明确决定：概念笔记（实证发现）、方法笔记（框架、协议）或两者兼有。一般的教学内容通常仅产生方法笔记；不要为属于 methods/ 的内容强制创建概念。 6b. 证据表与检查，在任何传播之前：将 wiki-ingest 步骤5b和5c应用于本章节，为章节创建一个临时表。书籍有三个附加项：

   • 页码列给出PDF页码和印刷页码，并且在你定位到的页面上确认章节标题（错误的偏移量会引用另一个章节）。
   • 对教材进行严格阅读：检查发现命名的每个机制和标记。章节列出的原因或标准列表并不构成列表中每项的证据，除非该项确实出现在该页面上。
   • 说明谁在说话：章节转述给另一位作者的声明应写为“X，如 [[chapter]] 所述”，章节中的临床意见不应写为试验结果。 只有通过的行的才进入步骤7和8。从渲染的页面中读取信号。

7. 传播到概念笔记，与论文录入相同：使用 [[chapter_note]] 反向链接将发现追加到现有的 concepts/{Concept}.md，或根据 wiki-ingest/references/CONCEPT-PROPAGATION.md 相同的创建规则从 templates/concept.md 创建一个新的概念笔记。

8. 传播到方法笔记（如适用）。 8b. 认证章节笔记：将章节作为作品应用 wiki-ingest 步骤8b（在 source_verification 中记录验证：库键、ISBN、检查的章节和页码、日期）。

9. 前向引用存根（自动）：在章节正文写入后，自动物化指向尚不存在的同级章节的前向引用：

   python skills/wiki-ingest-book/scripts/create_forward_ref_stubs.py \
     <wiki_root>/books/{book}_Ch{NN}.md  <wiki_root>/books/{book}.md   [--dry-run]
   

   该脚本扫描刚刚录入的章节中的 [[{book}_ChNN]] 链接（别名感知），读取目录集线器 ## Table of Contents 表以恢复每个缺失章节的标题和页码，从集线器前置元数据（{doi_base}_{N}，{citekey_base}_ch{N}）推导DOI和引用键，并写入UTF-8存根本，状态为 status: stub。没有目录行的前向引用将被跳过并报告（需要手动录入）。操作记录在 _temp/wiki_ingest_book_stubs_created.md。wiki-lint 检查项8尊重 status: stub，因此这些存根不会使 chapters_ingested 不同步，后者保持为实际已录入章节的规范列表。

   ⚠️ 切勿在章节的正文中写入录入状态标记。 在 ## Related Papers、*参见* 列表项或任何其他地方，不要写 *(pending ingest)* 或“尚未录入”等指示。录入状态是可变的，并且只有一个归属地：书籍集线器的 ## Table of Contents 行，步骤11将其从 pending 翻转为 ingested。复制到正文中的标记会将可变事实重复到不可变的位置：同级被录入后，目录会更新，但正文却永远断言相反的情况。在一次审计中，这导致在58个笔记中产生了68个过时标记，而所有依赖项都已经录入。没有 lint 检查能发现此类问题，因为每个文件内部保持一致，矛盾仅存在于文件之间。只需链接同级；如果某个作品在维基外部，请用纯文本命名。

10. 缺失概念报告（自动）：在脚本文本被截断后...

[为翻译而截断]