wiki-ingest-book 是做什麼的？
在首次攝入之前，請先閱讀工具包中的
docs/GOTCHAS.md（操作上的注意事項，包括書籍的頁碼偏移校正）。
將 LLM-wiki 攝入模式擴展至學術書籍。書籍上下文密集，無法一次性攝入，因此此技巧採用兩階段方法：先建立書籍總覽，再按需攝入章節。
角色與界限
會做：建立書籍筆記、建立章節筆記、將發現傳播至概念和方法筆記、更新索引和日誌。
不會做：一次性讀取整本書（有上下文限制風險）、發明元資料或章節標題、或複製論文攝入工作流程（章節遵循與論文相同的概念傳播規則）。
檔案儲存位置
路徑來自 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:前置內容）能捕捉最常見的書籍攝入漂移。
必需的契約（每次攝入後必須遵守）
- 每個章節筆記（位於
books/{book}_ChNN.md）的前置內容中必須有book: "[[{book_basename}]]"，且目標必須能解析到一個已存在的書籍筆記。寫入後請驗證；若缺少，wiki-lint檢查項目 9 會標記。 - 每次章節攝入都必須將章節編號附加到父書籍筆記的
chapters_ingested:列表中。附加後，列出{book}_Ch*.md並確認兩組相符；否則wiki-lint檢查項目 8 會標記漂移。 - 初始狀態遵循
wiki-ingest狀態表：僅有定義的為stub，進行中的為draft，而有兩個或更多有來源發現的章節筆記為final（章節本身就是一個來源）。衍生的概念和方法筆記遵循嚴格的提升規則：final需要 N 個不同的來源作品（min_distinct_sources_for_final，預設為 2），因此僅從本書建立的概念會保持在draft狀態，直到第二個獨立來源確認它。 - 索引路由使用
field_titlecase_map將新概念和方法放置在正確的 Title Case 領域子區段下，絕不放在帶有日期的通用區塊中。
前置步驟（必做，在模式A或模式B之前）
- 讀取
WIKI_SCHEMA.md。 - 讀取範本：模式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」工具無法開啟，例如 Git Bash on Windows 將/tmp映射到 Windows 工具無法看見的位置）。
頁碼偏移校正（書籍頁面不等於 PDF 頁面）
書籍的目錄列出的是書籍頁碼；pdftotext -f/-l 指定的是 PDF 頁碼。兩者之間存在偏移量（由前言、插圖頁造成），且該偏移量在整本書中非線性增長（圖表、表格、部分分隔頁）。直接將目錄數字傳給 pdftotext 會萃取到錯誤的頁面，這是章節攝入中最常見的時間消耗點。每本書請校正一次，在萃取任何章節之前：
- 選擇一個已知書籍起始頁的章節。估算
pdf_start = book_page + offset_guess（前言部分通常為 20 到 60 頁）。 - 僅萃取其第一頁，確認章節標題出現。調整最多 5 頁，直到正確定位。
- 將校正後的偏移量記錄在書籍筆記中（例如在目錄附近寫上
> [!note] PDF 偏移量：book_pg + N = pdf_pg（區域：第X部分）），以便後續章節重複使用。 - 對於較長的書籍，請按區域或部分重新校正：單一固定偏移量會漂移（例如在一本教科書中，第 3 章偏移 +36，第 21 章偏移 +56）。對於文字層 PDF，根據換頁符分割文字可提供快速頁面對映，其中包含準確的起始頁。
模式A：書籍總覽
觸發條件：/wiki-ingest-book [書名]
- 在參考管理工具中解析：依標題搜尋，然後擷取元資料（標題、作者、編輯、年份、出版社、ISBN、版本、DOI、引用鍵）。
- 年份後綴引用鍵注意事項（多卷或部分系列）：像
...2019a/...2019b這樣的 Better BibTeX 引用鍵不能可靠地對應到同一作者、同年份系列的卷1與卷2（後綴是消歧順序，而非意義）。在命名筆記或確認您擁有的卷冊之前，始終先從元資料中確認實際的標題（和副標題或「第N部分」）。
- 年份後綴引用鍵注意事項（多卷或部分系列）：像
- 為目錄解析全文（串聯；請參閱「本地 PDF 解析」）：
- 主要：
pdftotext -enc UTF-8 -f 1 -l 20 "<local_path>" -（約 3 到 8k tokens）。 - 備用1：參考管理工具全文，僅在本地 PDF 不可用且輸出少於 2,000 字時使用。
- 備用2：要求使用者貼上目錄；將其標記為「來源：使用者提供」。
- 備用3：對於知名教科書使用模型知識；每個條目標記為
[!note]。
- 主要：
- 決定檔案名稱：
FirstAuthor_Year_Keyword.md（第一作者的姓氏，僅限 ASCII；關鍵字是關於書籍主要主題的 1 到 3 個單詞）。如果books/{filename}.md已存在，則就地更新。 - 建立或更新書籍筆記於
books/{filename}.md，使用templates/book.md。將last_verified設定為今天的日期。 - 從步驟2填入目錄。如果不確定，將章節標記為
?並記錄限制。 - 萃取 3 到 5 個高階主題（僅書籍層級，不包含特定章節的主張）。輕量傳播：僅當主題是某研究線的核心且維基中已有 2 篇或更多論文觸及時，才更新
concepts/筆記；否則僅將其列出在書籍筆記中。達到筆記的主題遵循證據表規則：模式B步驟6b和8b。 - 治理檢查：應用
wiki-ingest步驟5中的研究線匹配和概念與方法路由。在總覽層級，僅記錄哪些章節可能產生方法筆記與概念筆記；完整傳播在模式B中進行。 index.md：如果索引嵌入了 Bases 視圖，請勿加入書籍條目；僅在完成新的父書籍攝入時更新## Quick Stats中的「Books (ingested)」計數。在manual模式中，加入條目。絕不觸碰凍結的舊版索引。- 附加到
log.md：## [YYYY-MM-DD] ingest-book | {Title}: overview。 - 報告：書籍筆記路徑、已識別的主題，以及可用於深度攝入的章節（
/wiki-ingest-book [書名] > 第N章）。
模式B：章節攝入
觸發條件：/wiki-ingest-book [書名] > 第N章（或 > 章節：[章節標題]）
-
讀取現有的書籍筆記於
books/FirstAuthor_Year_Keyword.md。- 如果不存在：停止。先執行模式A，然後重試。
- 如果該章節未列在目錄中：新增一行
status: pending，在最終報告中註明，然後繼續。 - 如果該章節已標記為
ingested：在使用者確認後再覆寫（預設：就地更新，保留現有的[[wikilinks]]）。
-
解析章節內容（串聯；請參閱「本地 PDF 解析」）：
- 從書籍筆記目錄中獲取章節頁面範圍，並使用記錄的偏移量將書籍頁面轉換為 PDF 頁面。僅在目錄頁碼本身未知時才詢問使用者。
- 主要：
pdftotext -enc UTF-8 -f <pdf_start> -l <pdf_end> "<local_path>" -（一個典型章節約 1k 到 8k tokens）。 - 備用1：如果該章節是帶有自身庫條目的
bookSection項目，則使用該項目的全文。 - 備用2：從參考管理工具取得全書全文，僅在本地 PDF 不可用且書籍少於 5,000 字時使用。
- 備用3：要求使用者貼上章節文字。
- 備用4：模型知識，每個主張加上
[!warning]。它永遠不會達到概念或方法筆記，也不會獲得印章。
-
章節檔案名稱：
FirstAuthor_Year_Keyword_ChNN.md（例如Knuttgen_1987_Strength_Ch03.md）。 -
建立章節筆記於
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。測量品質保持在發現中的行內，永遠不在前置內容中。
- 必需的契約：在前置內容中輸出
-
萃取 3 到 8 個概念和 1 到 4 個方法：與
wiki-ingest相同的萃取規則（請參閱references/BOOK-INGEST-WORKFLOW.md）。 -
治理檢查：與
wiki-ingest步驟5相同的研究線匹配和概念與方法路由。為此章節明確決定：概念筆記（經驗發現）、方法筆記（框架、協議）、或兩者。一般教學內容通常僅產生方法筆記；不要強迫為屬於methods/的內容建立概念。 6b. 證據表與檢查，在傳播之前：將wiki-ingest步驟5b和5c應用於此章節，為該章節建立暫存表。針對書籍有三個補充：- 頁面欄給出PDF頁面和印刷頁面兩者，並且您落腳的頁面上確認了章節標題（錯誤的偏移量會引用另一個章節）。
- 教科書採用嚴格解讀：檢查發現所命名的每個機制和標記。章節中列出的原因或標準清單，除非該項目就在頁面上，否則不能作為每個項目的證據。
- 說明誰在發言：章節交給另一位作者的聲明應寫為「X，as reported by [[chapter]]」，而章節的臨床意見不應寫成試驗結果。 只有通過的列才能進入步驟7和8。從渲染的頁面中讀取跡象。
-
傳播至概念筆記，與論文攝入相同：將帶有
[[chapter_note]]反向連結的發現附加到現有的concepts/{Concept}.md，或根據與wiki-ingest/references/CONCEPT-PROPAGATION.md相同的建立規則從templates/concept.md建立一個新的。 -
如果適用，傳播至方法筆記。 8b. 為章節筆記蓋章：將
wiki-ingest步驟8b應用於該章節（在source_verification中記錄驗證：庫金鑰、ISBN、已檢查的章節和頁面、日期）。 -
向前參照存根（自動）：在章節主體寫入後，為尚不存在的同層級章節實例化任何向前參照：
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 和引用鍵（{doi_base}_{N}、{citekey_base}_ch{N}），並寫入帶有status: stub的 UTF-8 存根。沒有目錄列的向前參照將被跳過並報告（需要手動攝入）。操作記錄到_temp/wiki_ingest_book_stubs_created.md。wiki-lint檢查項目 8 會識別status: stub，因此這些存根不會導致chapters_ingested不同步，後者仍保留為實際已攝入章節的規範清單。⚠️ 絕不要在章節的正文中寫入攝入狀態標記。 不要在
## Related Papers、在 see also 清單或任何其他地方對同層級章節寫*(pending ingest)*或「尚未攝入」。攝入狀態是可變的，且只有一個家：書籍中心的## Table of Contents列，步驟11會將其從pending切換為ingested。複製到正文中的標記會將可變的事實複製到不可變的位置：同層級章節被攝入後，目錄更新，而正文卻永遠宣稱相反。在一次審計中，這在58個筆記中產生了68個陳舊標記，每個依賴項都已被攝入。沒有 lint 檢查能看到這一類問題，因為每個檔案自身是一致的，矛盾僅存在於檔案之間。只需連結同層級章節；如果作品在維基之外，請用純文字命名。 -
缺失概念報告（自動）：在存根建立後，
python skills/wiki-ingest-book/scripts/missing_concept_report.py \
<wiki_root>/books/{book}_Ch{NN}.md --inventory <wiki_root>/concepts/ \
[--dry-run] >> _temp/missing_concepts_report.md
該腳本從定義了 concept: 前置內容的章節發現中收集概念金鑰，然後將其與 concepts/ 庫存進行比較。缺失的概念會被報告（不建立它們；建立由 wiki-ingest 步驟6處理）。用於審計追蹤。
- 最終的治理檢查（章節與書籍同步）：
- 更新
Table of Contents中該章節的狀態列為ingested。 - 將章節編號附加到
chapters_ingested:。 - 使用
ls books/{book}_Ch*.md | sort列出事實上的章節筆記；如果它們與chapters_ingested:不同步，則重新附加。 - 如果
chapters_ingested:中有任何條目不是books/{book}_Ch*.md中的檔案，則將其標記為## Missing並從清單中移除。
- 更新
index.md：遵循模式A步驟8。last_verified：將書籍筆記和章節筆記兩者中的last_verified更新為今天的日期。- 附加到
log.md：## [YYYY-MM-DD] ingest-book | {Title}: Chapter N。 - 報告：章節筆記路徑、提取的概念/方法及其狀態、
evidence_level（如果被覆寫）、建立的存根數量、以及/wiki-ingest-book [title] > Chapter N以獲取更多章節。