MinorBaek/wiki-ingest

wiki-ingest 是做什麼的？

實作 LLM-wiki 擷取模式，用於科學知識庫。 每篇擷取的論文都能建立可追溯、可累積的知識，而非僅是孤立的筆記。

在首次擷取前，請先閱讀工具包中的 docs/GOTCHAS.md（關於擷取、綜合與語法檢查的操作注意事項）。

模式

• 預設（擷取）：/wiki-ingest <paper> 會建立或更新論文筆記，並傳播至概念與方法（預設工作流程）。
• 驗證模式：/wiki-ingest verify:<PaperNote> 會針對現有筆記重新比對全文，並報告差異，但不會重新產生或覆寫任何內容（詳見 references/VERIFY-DIFF-MODE.md）。此模式為唯讀，除非使用者確認每項編輯。

角色與範圍

會做的事：建立或更新論文筆記、傳播至概念與方法筆記、更新索引與日誌、報告每項變更。

不會做的事：發明引用、為一次性概念建立概念筆記、或寫入資料庫。所有寫入皆透過主機的檔案工具（讀取/寫入/編輯）。

檔案位置

路徑來自 wiki.config.json（知識庫根目錄、維基根目錄、資料夾名稱、語言、閾值）。預設值：

<vault_root>/
  <wiki_root>/            # 預設：wiki/
    papers/  concepts/  methods/  books/  fields/  debates/
    WIKI_SCHEMA.md        # 前端協定、命名規則、分類法、擷取協定
    index.md  log.md
  templates/              # paper.md, concept.md, method.md, book.md, chapter.md, submoc.md, synthesis.md

下面的 <kit> 指的是 science-wiki-kit 的簽出目錄，其中包含 tools/（seal.py、pmc_tables.py）。其路徑為 wiki.config.json 中的 kit_dir 鍵，由安裝程式寫入；若缺少該鍵，則為此技能目錄上兩層的資料夾（當技能從簽出目錄連結時）。

開始前請務必閱讀 WIKI_SCHEMA.md。 它定義了此維基的前端協定、命名規則與領域分類法。

相關技能

• wiki-lint：共用 wiki.config.json（用於索引更新的 kebab-case 轉 Title Case 欄位對應）。建議每次擷取後執行，以確認未引入偏差。
• wiki-ingest-book：用於書籍與章節的配套技能。相同的狀態規則與索引路由皆適用。
• wiki-synthesize：會使用此技能產生的筆記。

初始狀態決定（適用於每則新筆記）

請審慎設定 status。請勿保留範本的預設值。下方的 N 為設定檔中的 min_distinct_sources_for_final（預設為 2）。

筆記類型	條件	初始 status
論文	摘要 + 至少提取出 2 項有來源的發現	read
論文	僅有 DOI/標題元資料，無全文	stub + > [!warning] 暫存：待擷取全文。 標註
概念	至少有 2 項有來源的發現，來自 N 個或更多不同的來源作品	final
概念	至少有 2 項有來源的發現，但全部來自 單一來源作品	draft（單一來源綜合）
概念	定義 + 1 項有來源的發現	draft
概念	僅有定義，無關鍵發現	stub + > [!warning] 暫存：尚未有來源發現。 標註
方法	定義 + 在「使用此方法的論文」下有 N 個或更多不同的來源作品	final
方法	定義且僅有 1 個來源作品	draft（單一來源）
方法	定義但無來源引用	draft
方法	僅有骨架	stub

晉升至 final 需要 N 個不同的來源作品。「不同」指的是獨立的論文或書籍：一本書的主筆記及其自己的章節筆記（Author_2025 + Author_2025_Ch01 + Author_2025_Ch02）會合併為 一個 作品，同一本書的多個章節亦然。一個豐富的單一來源（系統性回顧、教科書章節）可能建立一個概念並產生數項發現，但該筆記仍會保持 draft 狀態，直到第二個獨立來源加以證實。在向 draft 筆記新增發現時，請在編輯後計算不同的作品數量，僅在數量達到 N 時才晉升，並在擷取報告中記錄此晉升。單一來源的 draft 筆記會在內文中附帶一行簡短的「單一來源綜合，請在擷取第二個來源時加以證實」。

預設工作流程

1. 讀取綱要

讀取 WIKI_SCHEMA.md。

2. 解析論文來源

依序嘗試，使用環境提供的任何工具：

• 參考文獻管理器（支援 Zotero MCP）：先搜尋，再取得元資料，最後取得全文。搜尋順序與注意事項詳見 references/INGEST-WORKFLOW.md。
• 出版商 XML 表格（PMC 的開放獲取文章）：若 DOI 有 PMCID，則可從 Europe PMC JATS 逐格提取表格，不受 PDF 文字層干擾：python <kit>/tools/pmc_tables.py <DOI> --out _temp/<stem>_pmc.md --body（回傳碼 2 表示無 PMCID）。在開啟頁面圖片前，請先核對表格編號與 JATS；若 JATS 與 PDF 不一致，以列印版 PDF 為準，並記錄此不一致。無 PMCID：則使用 PDF。
• PubMed MCP（論文不在參考文獻管理器中）：先用關鍵字搜尋，再用 PMID 提取（DOI 可能回傳空的 full_text）。將 PMID 儲存在論文筆記的 notes: 欄位中。僅供生醫論文使用，且需經使用者確認該論文不在其資料庫中。
• 僅有 DOI：記錄此情況；請勿憑空編造元資料。
• 網路文章（開放獲取 HTML/URL）：先使用網頁轉 Markdown 工具（例如 defuddle 技能）將其轉換為乾淨的 Markdown，再將輸出視為摘要與內文處理。若無 DOI，則使用 URL 作為引用來源。
• 手動輸入：使用者貼上摘要或文字。提取元資料，並標記未知的欄位。

PDF 的存放位置很重要：筆記不得引用將被清理的工作資料夾（如 Downloads/、暫存目錄）。請在撰寫筆記前，先將 PDF 整理至您團隊所使用的資料庫位置，並在 source_verification 中記錄。若論文不在資料庫中，或不清楚應歸類於哪個集合，請在移動任何檔案前先詢問使用者。

3. 決定論文筆記檔名

格式：FirstAuthor_Year_Keyword.md

• FirstAuthor = 第一位作者的姓氏（僅限 ASCII，無變音符號，無空格）
• Year = 4 位數字
• Keyword = 1 到 3 個詞的描述詞（CamelCase 或底線，無空格）
• 範例：Smith_2023_Eccentric_Training.md

重複與身分檢查（在任何寫入前執行；可防止無聲的資料遺失）：

1. 透過內容搜尋基礎名稱來確認是否存在，或使用 test -f "<wiki_root>/papers/{filename}.md"。請勿信任單一 glob 傳回的「未找到檔案」：檔案 glob 工具曾對已存在的筆記傳回假陰性，而之後的盲目 Write 將會覆寫一則已完整傳播的筆記。若 Write 報錯「檔案尚未被讀取」，這證明筆記存在：請讀取並就地更新，切勿從頭重寫。
2. 若現有筆記的狀態為 status: stub，請勿假設它是同一篇論文。 從另一篇論文的引用脈絡建立的暫存筆記帶有暫時性的元資料，有時會是不同篇論文（年份錯誤、論文與書籍章節混淆、兩篇相關論文被混用）。請先解析真正的來源，並將作者、年份與期刊與暫存筆記及引用筆記的參考文獻列表進行比對。若是不同篇論文，請將其擷取為新筆記，並保留或改進暫存筆記。
3. 若確認是同一篇論文，請就地更新；切勿建立重複。一旦取得全文，檔案名稱可能會合理地變更為更具描述性的關鍵字。若如此，請重新連結每個 [[OldName]] 並刪除孤立的暫存筆記，然後重新執行 wiki-lint 以確認沒有殘餘的斷開連結。
4. 引用鍵身分防護。 同一篇論文的兩則筆記可能使用不同的檔名，因此乾淨的基礎名稱探測並不能證明身分。在參考文獻管理器解析該項目後，請搜尋 papers/ 中您即將撰寫的確切引用鍵（grep -l '^citekey: "\?{citekey}"\?$' papers/*.md）。若在另一個檔名中找到相符項，表示該論文已擷取：請更新該筆記。使用確切字串比對，因此不會有誤判。

4. 建立或更新論文筆記

從 templates/paper.md 寫入 <wiki_root>/papers/{filename}.md。從已解析的元資料填入每個前端欄位。將 last_verified 設定為今天的日期（擷取即是一次驗證事件）。從 WIKI_SCHEMA.md 中的分類法 slug 分配 research_lines。

5. 提取與評估

一次性地掃過摘要、結果與討論，同時完成以下所有事項：

• 識別 3 到 8 個領域概念（經驗構念、變數）和 1 到 4 個主要方法。啟發式規則詳見 references/INGEST-WORKFLOW.md。
• 分類 evidence_level：研究設計，來自 WIKI_SCHEMA.md 中的控制詞彙（SR-MA、RCT、cohort……）。這是活躍綜合層級加權的設計軸。測量品質軸則維持內嵌於每項發現中（如 (MRI)、(anthropometric estimate)），絕不放在前端。
• 研究路線路由：將論文與 WIKI_SCHEMA.md 中的研究路線比對。若相關內容沒有符合的路線，請在傳播前先新增一條到綱要中（附加 slug + 標籤配對；切勿重新命名或移除現有路線）。若難以抉擇，請使用最接近的路線並在報告中標記。
• 概念與方法路由：經驗發現歸入 concepts/；統計工具、研究設計與測量協定歸入 methods/。在此決定。
• 純方法論捷徑：若論文未提出經驗主張，則跳過步驟 6，直接前往步驟 7。

5b. 證據表格，進行任何傳播之前

對於每項將被寫入 concepts/ 或 methods/ 筆記的發現（包括「使用此方法的論文」下的主張），在暫存檔案中撰寫一行（切勿寫入維基）：

| 目標筆記 | 發現，將如何撰寫 | 來源的逐字引述 | 頁碼（PDF/列印版） | 章節、表格或圖表 |

• 來源是 PDF（表格儲存格則是 JATS）。僅有摘要或無 PDF：請在發現的文字中標記 abstract only，並在報告中說明。
• 每個具體細節都需要其引述：每個圖表、族群、裝置、機制、命名實體與強度動詞。請拆分發現，或使用多個引述，直到完全涵蓋。
• 請閱讀命中點周圍的整個段落或表格行，而不只是相符的數字。
• 表格、圖表、正負號、信賴區間與 ±：請渲染該頁面並查看。文字提取只是一個假設，圖像才是證據。某些 PDF 會在文字層中遺失負號（-5.2% 提取為 25.2%），產生看似合理的錯誤數字。
• 對於「不存在」的宣稱需要進行正向搜尋，在版面文字與非版面文字中，並嘗試不同拼寫，才可寫入「論文並未……」。

5c. 在寫入前檢查表格

在觸碰任何筆記前，請針對每個引述閱讀每一行。如果是由子代理提取的論文，請在 PDF 中重新閱讀每一行，而不僅是包含圖表或符號的行。需判斷的缺陷類別包括：超出來源的推論、歸因錯誤、數字錯誤、遺失的修飾語、無根據的誇大、錯誤的實體、發明的細節、遺漏。

• 引述不支援的行應向下調整至引述所述內容，或捨棄。來源筆記並非證據：它來自相同的提取過程。
• 保留來源的修飾語（「可能」、「似乎」、「可能是由於」）及其族群。
• 維基本身的解讀應標記為維基的；切勿將其寫為來源的行為或結論。

只有通過檢查的行才會進入步驟 6 和 7。

6. 傳播至概念筆記

對於步驟 5 中的每個概念：

1. 檢查 concepts/{Concept_Name}.md 是否存在。
2. 存在：在「關鍵發現」下附加該發現，並附上 [[paper_note]] 反向連結。若出現新連結，請更新 related_concepts。
3. 不存在：先套用 references/CONCEPT-PROPAGATION.md 中的建立規則。

7. 傳播至方法筆記

對於步驟 5 中的每個方法：

1. 檢查 methods/{Method_Name}.md 是否存在。
2. 存在：在「使用此方法的論文」下新增該論文。
3. 不存在：從 templates/method.md 建立。

8. 更新論文筆記前端

使用已建立或更新的概念與方法筆記填寫 concepts_touched。

寫入後驗證：concepts_touched 中的每個名稱都必須能解析為 concepts/ 或 methods/ 中的現有筆記。寫入後，請重新檢查每個基礎名稱。若有無法解析的名稱，請立即建立缺少的暫存筆記或移除該名稱。懸空的引用會變成無聲的語法偏差。

8b. 封存來源筆記

在論文筆記的 source_verification 中記錄驗證（一行：參考文獻管理器鍵、日期、檢查了什麼與什麼進行比對）。然後，為每個接收到發現且其行數通過 5c 檢查的（筆記，作品）配對進行封存：撰寫一個小型 JSON 規格，並執行 python <kit>/tools/seal.py spec.json --dry-run，然後在不加 --dry-run 的情況下執行（格式與規則詳見 docs/SEALS.md）。僅根據摘要檢查的作品不予封存。日期請使用系統時鐘（date +%F），切勿自行估計。

9. 結案

進行三次編輯，然後產出報告。使用 wiki.config.json 中的 field_titlecase_map 來找到每個新概念或方法所屬的正確小節；切勿附加到章節末尾的過時綜合區塊。

• index.md：若索引嵌入了 Obsidian Bases 視圖（設定檔中的 index_mode: bases），請勿維護每則筆記的清單；僅更新策展的 ## Quick Stats 計數和相關的 ## Coverage by Field 行，然後重新讀取表格（全新的維基兩者都沒有：跳過此步驟，直到您新增它們之前都不會產生偏差）。在 manual 模式下，將筆記新增至按字母順序排列的正確位置。切勿觸碰已凍結的舊版索引。
• 子 MOC 路由（見 WIKI_SCHEMA.md，子 MOC 架構）：解析筆記的 field + subfield，計算 fields/{field-slug}/MOC_{Title_Case_Underscore(subfield)}.md（kebab-case 轉 Title_Case，具確定性，無需對應表）。若不存在，則從 templates/submoc.md 建立，並在領域 MOC 的子 MOC 索引中新增一行。在子 MOC 的正確章節下新增筆記（概念筆記、方法筆記、論文、書籍）。

…

[為翻譯而截斷]