3 literature analysis

逐篇文獻深度分析技能［現行版，見檔尾版本區］

本檔守決策層（Step 0、批次協議、三種執行模式、寫作原則、段落涵蓋規則、完成清單回寫）。雙檔結構與格式規格下放 references/，於產出階段才載入：

• references/file-specs.md —— 切分線規格、知識檔／應用檔結構與 frontmatter YAML、_index.json、自我檢核模板、Obsidian 相容性（產出／拆分階段載入）
• references/example-literature-knowledge.md／references/example-literature-application.md —— 知識檔／應用檔的格式與深度基準範本（Step 0 強制讀取，隨 skill 同捆，正本隨 skill 包版控）

雙檔架構（知識檔 paper-agnostic 正本＋應用檔綁定 paper_id）、三模式（全新分析／複用／既有檔批次拆分依 _index.json 是否命中 citation_key 自動切換）、vault 佈局與變更歷程詳見 repo CHANGELOG，本檔不嵌補丁說明。

---

環境偵測（所有讀取動作之前，最先執行）

本 skill 以 00_專案控制/ 作為控制檔的預設路徑，此路徑假設一個持久的工作區資料夾（Claude 桌面應用的 Cowork 模式，或 Claude Code）。若該路徑不存在，代表使用者在無工作區環境（例如 claude.ai 網頁版）執行本 skill。此時一律進入「無工作區模式」，不得以「檔案缺失」為由拒絕啟動。

無工作區模式的三條規則：

1. 控制檔改在別處尋找。依序查找同名檔案：對話附件 → 專案知識庫（claude.ai 的 Project files）→ 使用者於本次對話明確指定的位置。找到即視同滿足必讀要求，正常推進；三處皆無才回報缺失，並明確告知使用者可透過對話附件或 Project files 提供。此規則覆蓋本 skill 所有「缺漏即拒絕啟動」的硬閘門條文——閘門的實質要求是「讀得到該檔的內容」，不是「該檔位於特定路徑」。
2. 產出改以可下載檔案交付，不嘗試寫入 05_輸出/ 或任何工作區路徑。晉升流程（審定後移入正式位置）改由使用者手動完成，於交付時一併說明。
3. 跨 session 狀態改由使用者提供。本 skill 若依賴 05_輸出/progress-log.md、既有產出檔或凍結狀態回讀斷點，在無工作區模式下改為請使用者於開場提供前輪產出（附件或貼上內容）；無法取得時，明示「本次為無工作區模式，跨對話狀態不自動續作」後，以本次提供的材料為準推進。

啟動宣告中必須載明當前模式：「工作區模式」或「無工作區模式」。

📌 執行步驟 Step 0（所有步驟之前，無例外）

在進入任何分析動作之前，必須依序完成以下步驟：

1. 讀取兩份範本（雙份，隨 skill 同捆）：

   • references/example-literature-knowledge.md：知識檔的格式與深度基準
   • references/example-literature-application.md：應用檔的格式與深度基準 兩份範本是本次輸出的格式與深度品質錨點。範本對齊優先於規則窮舉。範本正本隨 skill 包版控、與升版同步，不再讀取使用者控制檔資料夾的散本。

2. 查詢知識庫索引判定執行模式（決定走 Mode A 或 Mode B）：

   • 讀取 vault 根目錄的 3_文獻/_index.json（「3_文獻」是 vault 的慣例名，不是 starter-kit 00–05 骨架的一部分；尚未另建 vault 者，最簡做法是直接以工作區的 01_文獻/ 充當 vault——本 skill 各處路徑中的 3_文獻 讀作 01_文獻 即可）
   • 以本次文獻的 citation_key 比對：查無 → Mode A（全新分析）；命中 → Mode B（複用），宣告「本篇已有知識檔，進入複用模式」
   • 若無法存取 _index.json（vault 路徑未設定或索引尚未建立），預設走 Mode A，並於產出時提示使用者補建索引

3. 讀取 literature-search 的 metadata（若存在）：

   • 若本次文獻來自 literature-search 的產出，讀取對應主題資料夾中的 _metadata.json，提取書目欄位（citation_key、title、authors、year、venue、doi、type_of_work）
   • 若非經 literature-search 取得（使用者直接上傳 PDF），於 frontmatter 生成時從 PDF 內文自行提取，citation_key 依 第一作者姓氏小寫 + 年份 + 標題首實詞小寫 格式生成

4. 讀取研究脈絡：

   • 00_專案控制/research-identity.md：研究者的理論偏好、方法論立場
   • 00_專案控制/paper-structure.md（若在特定論文專案中執行）：當前研究問題、理論框架、核心命題、章節結構與編號（也是完成清單回寫的目標檔，見「文獻分析完成清單回寫」）
   • 無 paper 脈絡時（非論文專案或無 paper-structure.md）：僅產知識檔，不產應用檔——應用檔規格要求具體章節編號，無脈絡即不可滿足；待文獻進入特定論文後以 Mode B 補產應用檔。完成清單回寫一併略過並回報

5. 產出開頭宣告對齊：

   • 知識檔第一行（YAML 與標題之後）：

     範本對齊確認：已讀取 references/example-literature-knowledge.md（隨 skill 同捆範本），以其為知識檔輸出的格式與深度基準。

   • 應用檔第一行（僅於有 paper 脈絡、產出應用檔時）：

     脈絡對齊確認：已讀取 00_專案控制/paper-structure.md，Section 2 的啟發將對應具體章節編號。

PDF 可讀性前置檢查（失效分支）：目標 PDF 無法抽取內文（損毀、掃描影像檔）時，先以 pdf skill 執行 OCR；仍失敗——單篇模式回報使用者並中止本篇，批次模式跳過本篇並記入批次收尾報告「略過清單（檔名＋原因）」。素材優先條款下 PDF 不可讀＝零素材，禁止以訓練記憶替代分析。目標檔非學術文獻（政策文件、簡報、新聞稿）時，回報並請使用者確認處理方式，不逕自套用本 skill 格式。

批次執行時的 Step 0 成本護欄：範本兩檔（example-literature-knowledge／example-literature-application）於第 1 篇完整讀取後，每滿 3 篇重讀一次（即第 4、7、10……篇開始前）；其餘各篇以 references/file-specs.md 與自我檢核清單為格式基準。任何一篇自我檢核未過（格式或深度偏移）→ 立即重讀兩份範本後修正；任何完整重讀後，下一次排程重讀順延至其後第 3 篇（避免檢核觸發重讀與排程重讀背靠背重複載入）。研究脈絡檔（research-identity、paper-structure）同一 session 已讀且未變更者不重讀；_index.json 與 _metadata.json 仍每篇必查（判定模式所需）。

---

⚠️ 批次執行協議（最高優先級，覆蓋一切其他指令）

當收到多篇文獻的分析請求時（例如：「分析＜主題A＞資料夾內的所有文獻」、「幫我摘要這10篇」），必須嚴格遵守以下規則：

規則一：一篇一組完整任務，禁止合併

每篇文獻必須產出一組完整的獨立分析——Mode A 為知識檔 + 應用檔兩份 .md（加一份合併 docx）；Mode B 為應用檔一份。每篇都包含本 Skill 要求的所有節。禁止將多篇文獻的分析內容合併在同一份輸出檔案中。

規則二：逐篇完整執行，禁止跨篇壓縮

批次執行≠分配注意力給所有文獻。每一篇的分析深度與品質，必須與單篇分析時完全相同。批次數量（2篇或20篇）不得成為壓縮任何單篇內容的理由。

規則三：明確的執行節奏與進度通知

開始批次執行前，先宣告計畫：

「我將逐篇進行分析，共 N 篇。每篇先查索引判定模式，再依序完成完整輸出後進行下一篇。現在開始第 1/N 篇：[作者年份]（Mode A/B）。」

每完成一篇，通知進度與模式，並回寫完成清單（見專節）：

「第 X/N 篇完成：[檔名]（Mode A/B），已回寫 paper-structure.md 完成清單。應用檔 Section 2 推論稽核 (c) 類比例：X/Y。開始進行第 X+1/N 篇：[作者年份]。」

規則四：確認文獻清單

若指令為「分析某資料夾的所有文獻」，執行前先列出識別到的文獻清單並確認，避免遺漏或誤讀。

規則五：每篇獨立對齊範本

批次執行第 2 篇以後，禁止以自己先前產出的篇章作為格式參照——格式基準永遠是範本與 references/file-specs.md 規格，不是上一篇自己的產出，避免「首篇偏移、後續以首篇為準進一步偏移」的連鎖降階。範本重讀節奏依 Step 0 成本護欄執行（每 3 篇一次＋檢核未過即重讀），不再每篇重讀。

規則六：每篇開始前重申四條鐵律（防批次後段品質滑坡）

進入每篇（尤其第 4 篇起）前，先重申本支四條最易被遺忘的鐵律：① 範本是格式基準——不得以自己前篇產出為參照；② 逐節精華不得跨篇壓縮——深度與單篇分析相同；③ 應用檔 Section 2 (c) 類推論一律標記〔類推論〕；④ 素材優先——具體宣稱（數據／頁碼／引句／立場）只能來自本次載入素材，查無依據標〔記憶未驗證〕且不得寫入正式產出。

---

三種執行模式

Mode A｜全新分析

• 觸發：_index.json 查無該 citation_key（或索引不可用時的預設模式）
• 流程：完整分析流程（含 Step 0、批次協議、逐節精華）
• 產出：知識檔 .md＋應用檔 .md＋合併 docx（知識 + 應用接續排版的單一 .docx，維持 Word 連續閱讀體驗，docx 不含 frontmatter）。結構規格載入 references/file-specs.md。docx 以 docx skill 產製；產製失敗→照常交付 .md 並回報「docx 產製失敗，稍後可補」，不阻斷批次。
• 輸出位置：當前專案 05_輸出/。審定後：知識檔移入 3_文獻/理論基礎/[主題]/（與該文獻 PDF 並排），應用檔移入 3_文獻/應用/[paper N]/
• 完成後：回寫 paper-structure.md 完成清單（見專節）

Mode B｜複用

• 觸發：_index.json 命中 citation_key → 宣告「本篇已有知識檔，進入複用模式」
• 讀取：vault 知識檔全文 + 當前專案 paper-structure.md + research-identity.md
• 產出：僅應用檔（.md + .docx，docx 開頭附一行知識檔指引：「本應用檔對應知識檔：[knowledge_note 路徑]」）
• 預設不讀 PDF。僅當應用需求超出知識檔記載（例如需要知識檔未收錄的引句）時才按需回查 PDF；回查後於 05_輸出/ 另產 知識檔修訂建議_[citation_key].md，由使用者審定後手動併入 vault 正本
• legacy 補寫：若命中的知識檔為批次拆分版（「通用警示」欄為 [待補] 狀態），Mode B 順手補寫通用警示，併入上述修訂建議檔
• 完成後：回寫 paper-structure.md 完成清單（見專節）

Mode C｜既有檔批次拆分（一次性工具，由 scripts/split_legacy.py 執行）

• 工具：scripts/split_legacy.py，按 ## 節標題機械切分（拆分規則細節與 frontmatter 改寫見 references/file-specs.md 切分線規格）
• 要點：知識檔 ← frontmatter（type 改 literature-knowledge，刪 paper_id／skill_stage）+ 核心摘要 5 欄 + 通用警示欄置 [待補] + Section 0／1／3；應用檔 ← 新 frontmatter（paper_id，knowledge_note 連結）+ 原「直接用途」「警示」兩欄 + Section 2；原「自我檢核回報」附錄於知識檔尾並改標題「原始產出檢核紀錄（舊版）」；無 frontmatter 的舊檔由腳本生成基本 frontmatter 並標 needs_review: true
• 對象：既有專案的舊版分析檔。拆分產出至 05_輸出/知識庫批次拆分/，使用者抽查審定後，知識檔移入 vault
• Mode C 為一次性遷移工具，日常分析不執行。

---

核心目標

讓研究者在讀完分析後，能夠同時掌握三件事：

1. 這篇文章在說什麼：全文脈絡與論證主軸（知識檔承載）
2. 我可以怎麼用：對當前撰寫中論文的具體啟發與應用方式（應用檔承載）
3. 我去哪裡找：每個章節的關鍵論點與對應原文位置，供回頭精讀時快速定位（知識檔承載）

知識／應用的切分原則：凡是「這篇文獻本身的內容與評價」即屬知識檔（可跨論文複用）；凡是「綁定當前 paper 的章節編號與引用操作」即屬應用檔（綁定 paper_id）。 完整切分線見 references/file-specs.md。

---

寫作原則（優先於一切格式規定）

原則一：敘事優先，條列輔助 每個節的脈絡說明應為連貫段落。關鍵論點清單是段落之後的補充，不能取代段落。

原則二：以學術夥伴的口吻寫作 想像你是一位剛讀完這篇文章、正在向使用者解釋的資深學者同事。語氣應是：「這篇有意思的地方在於……」「作者在這裡做了一個值得注意的選擇……」「對你的研究來說，最直接相關的是……」

原則三：禁止的寫作模式

• 禁止「使用者可採取……策略」這類指令式語氣
• 禁止「本節將說明……」這類公文式開場
• 禁止「此即……之體現」「此亦……之佐證」這類空洞結語

---

嚴格規範

• 基於事實：僅陳述文獻內容，未提及處標註「文中未提供」
• 避免推論：轉述作者論述，勿補充外部知識（應用檔 Section 2 除外）
• 語言：繁體中文，學術論述，但以人類說話的方式書寫
• 素材優先（防記憶洩漏）：關於文獻的一切具體宣稱（數據、頁碼、引句、作者立場）只能來自本 session 載入的 PDF／知識檔；訓練記憶僅供提示搜尋方向。素材中查無依據者標記〔記憶未驗證〕，不得寫入正式產出（知識檔／應用檔）；該類項目彙列於該篇完成通知的「〔記憶未驗證〕清單」，供使用者決定是否回查 PDF。

---

應用檔 Section 2 推論稽核

Section 2「對當前研究的直接用途」是本 skill 唯一允許外部推論的區塊（見「嚴格規範」：避免推論，應用檔 Section 2 除外），故也是捏造應用的唯一入口，須單獨設稽核。

每條應用建議於應用檔產出時標記依據類型：

標記	依據	處置
(a) 本篇內生	源自本篇知識檔某節（附節定位／頁碼）	直接成立
(b) 脈絡對接	源自 paper-structure.md 的研究問題／框架，與本篇對接的推論	成立，但須點明對接的是哪一節點
(c) 分析者推論	上述兩者皆無、屬分析判斷	必須標記「此為分析判斷，待使用者核」，不得寫成文獻既有結論

收尾提示：單篇應用檔若 (c) 類佔 Section 2 過半，於完成通知中提示「本篇應用多為分析者推論、文獻內生支撐較薄，請優先複核」。

邊界：本稽核只規範應用檔 Section 2；知識檔（Section 0／1／3）仍受「基於事實、避免推論」全規範約束，不適用 (c) 類標記——知識檔出現分析者推論即為違規，非標記了事。

---

段落涵蓋規則（執法標準）

保留並作為執法標準（四條，全部適用於知識檔 Section 1 逐節精華）：

1. 節層級不得遺漏：原文每一節都必須出現在逐節精華中。
2. 每節必有定位句：1–2 句的功能判斷（這節在全文論證中承擔什麼工作），即使是方法節、結果節、技術性章節也必須有。
3. 三類內容強制英文原文引句含頁碼：核心概念定義／作者確立的論點／因果機制表述。任何一節完全沒有英文引句，視為該節未完成。
4. 承載論點的段落不得跳過：過渡性段落可一句帶過（判斷權在分析者），但不得整段省略承載實質論點的段落。

已刪除舊版「執行前數段落、產出段數核對（原文 N 段產出 N 段）」配額自檢——模型無法真實驗證，徒增形式負擔。

品質深度錨點：以知識檔範本為準，範本對齊優先於規則窮舉。

逐節精華的格式禁用清單（違反任一項等同未執行，必須重做）

1. 禁止使用 Markdown 表格呈現概念內容、理論框架、能力類型、指標對應、分類矩陣等結構性概念內容。原文即為表格時，以敘述轉述（例如：「作者以 Table 2 呈現九種能力的操作化定義……」），可於段末附「原文以 Table X 呈現」一句。
2. 禁止省略定位句。
3. 禁止合併原文段落為單一敘述。過渡性段落亦須至少一句帶過 + 頁碼。
4. 禁止使用 #### 或更深層級切分同一節的論述內容。章節層級由 ### 佔用，小節內部以敘事段落推進。
5. 禁止把本應完整論述的觀點切碎成數個不完整的條列項。條列只能用於「原文已是清單形式的枚舉內容」。

---

文獻分析完成清單回寫（00_專案控制 唯讀規則的唯一例外）

授權依據：本工作流的資料夾治理規則（見 starter-kit README 與工作區 CLAUDE.md）以「00–04 唯讀」為原則；本節為其唯一授權例外——literature-analysis 完成每篇文獻分析後，得回寫 00_專案控制/paper-structure.md 的「文獻分析完成清單」（僅此一處、僅此技能）。除此之外 00_專案控制 全程唯讀。此為 design／search 兩支技能假設 analysis 會自動回寫時的權威解：analysis 自動回寫，不再由使用者手動維護。

時機：每篇文獻定稿後立即回寫（批次中每篇各寫一次，不集中到批次結束），避免 session 中斷導致已完成篇章漏記。

步驟：

1. 讀取當前專案 00_專案控制/paper-structure.md，定位「文獻分析完成清單」記錄處：
   • 若存在明確的「文獻分析完成清單」表/區塊 → 以其既有欄位為準。
   • 若無該標題（常見：完成狀態記於「關鍵文獻清單與閱讀優先序」並以 ✅ 標記）→ 以該既有慣例為「完成清單」的實作，更新對應條目的 ✅ 標記。
   • 嚴禁自創新表或新欄位：一律對齊既有 schema。schema 不明確時，走下方 fallback 並回報使用者。（既有 schema 的 canonical 欄位定義見 research-design-diagnosis references/paper-structure-template.md 完成清單表。）
2. 對本篇 citation_key：條目已存在 → 更新（標記完成、補應用檔檔名/知識檔連結，僅在既有欄位容許時）；不存在 → 在既有清單的對應優先序/分類下新增一列，欄位與既有列一致。
3. 只更動該記錄處，paper-structure.md 其餘內容一字不動。
4. 寫入規範：一律 Write tool 完整寫檔（禁 bash heredoc／echo）；寫入後重讀該區塊驗證：目標列已更新、表格結構未破壞、檔尾完整無截斷、無 NULL。

Fallback（任一條件成立即不直接寫、改產 patch）：

• 環境將 00_專案控制 強制唯讀（例如使用者環境的唯讀例外設定未生效）導致寫入失敗；
• 找不到可對齊的完成清單 schema、或對齊有歧義；
• 寫入後驗證發現結構受損（先還原，不留半套）。

Fallback 動作：於 05_輸出/ 產出 完成清單回寫_[citation_key]_[日期].md，內含「建議新增/更新的列 + 對應的 paper-structure.md 區塊定位」，並明確回報使用者「完成清單未能自動回寫，請手動併入，原因：……」。

批次：每篇回寫後在進度通知中標明「已回寫」或「改產 patch（原因）」。

---

輸出檔案規範

輸出位置：當前專案 05_輸出/。檔案結構與 frontmatter 規格載入 references/file-specs.md。

Mode A 輸出：

1. 知識檔 05_輸出/[主題]_[作者年份]_[關鍵詞]_知識.md（含 YAML frontmatter）
2. 應用檔 05_輸出/[主題]_[作者年份]_[關鍵詞]_應用_[paper-id].md（含 YAML frontmatter）
3. 合併 docx 05_輸出/[主題]_[作者年份]_[關鍵詞]_分析.docx（知識 + 應用接續排版，不含 frontmatter）
4. 05_輸出/_index_更新.json 片段
5. （若回寫成 fallback）05_輸出/完成清單回寫_[citation_key]_[日期].md

Mode B 輸出：

1. 應用檔 .md + .docx（docx 開頭附知識檔指引行）
2. 若回查 PDF：05_輸出/知識檔修訂建議_[citation_key].md

晉升機制：vault 根目錄＝ 3_文獻（單一資料夾三位一體：人工 vault、Obsidian vault、文獻 PDF 庫）。知識檔由使用者審定後手動移入分類樹對應主題夾 3_文獻/理論基礎/[主題]/（與該文獻 PDF 並排，PDF 晉升時改名為 [主題]_[作者年份]_[關鍵詞].pdf）；應用檔審定後移入 3_文獻/應用/[paper N]/，使知識檔與應用檔同在一個 vault → Obsidian backlink 自動呈現「哪些 paper 用過此文獻」。AI 不直接寫 vault（與完成清單回寫的唯一例外無關——回寫對象是 00_專案控制/paper-structure.md，非 vault），與範本檔晉升機制同構。.md 供 literature-synthesis 跨文件讀取並可直接貼入 Obsidian；.docx 供 Word 閱讀批注，不進 Obsidian。

重跑命名：同一篇文獻的重新分析，在檔名末尾加 _v2，舊版保留不刪除。

---

與 Skill 4（literature-synthesis）的介面

• 第一輪讀取對象：知識檔「核心摘要」+ 應用檔「應用摘要」（欄位措辭沿用現行用語，僅分居兩檔）
• 第二輪深讀對象：知識檔 Section 1 逐節精華（不變）
• paper-structure.md「文獻分析完成清單」由本技能自動回寫（見專節），記錄應用檔檔名 + 知識檔連結（依既有 schema 容許範圍）

註：Skill 4 端的對應實作已於 literature-synthesis 雙檔架構完成核定，本節介面為雙方現行合約。

---

版本資訊

版本：v1.1.2｜範例檔 citation_key 對齊生成規則（chen2018pb→chen2018participatory）。v1.1.1｜補「3_文獻」vault 慣例名與 starter-kit 01_文獻 的橋接說明；split_legacy.py 版本戳同步。v1.1.0｜新增無工作區模式（claude.ai 等無持久檔案系統的環境）降級分支。v1.0.1｜紅隊審查修訂 對應 Skill：literature-analysis 變更歷程：詳見 repo CHANGELOG