btrainee/literature-review-skill

生物資訊學文獻系統性回顧

目的

將原始英文研究論文PDF轉換為一套標準化、高品質的中文審閱資料：嵌入並解釋每張主圖的Word深度閱讀報告、PPT分享簡報，以及可選的科普文章。專為需要可重現、深度優先文獻解讀的生物資訊研究人員設計。

使用時機

當使用者提供科學論文PDF（或要求審閱特定論文）並希望獲得以下任一項時觸發：

• Word深度閱讀報告（10個章節的結構化分析）
• 圖片提取 — 提取PDF中每張主圖作為圖像並逐一解釋
• PPT組會分享資料
• 微信公眾號科普文章
• 以上全部（完整流程）

典型的使用者語句：

• "解讀這篇論文" / "解析這篇文章"
• "幫我做個文獻精讀"
• "把每張主圖提取出來講解" / "每張Figure都要配圖解讀"
• "生成Word解讀 + PPT"
• "整理成科普文章"

先決條件

Python 環境

任何 Python >= 3.9 均可使用。可以使用代理執行環境自帶的直譯器，或使用自己的虛擬環境。

安裝依賴（一次性）：

pip install pdfplumber pymupdf python-docx python-pptx

如果PyPI速度慢（在中國大陸常見），請使用鏡像源：

pip install pymupdf -i https://mirrors.cloud.tencent.com/pypi/simple

• pymupdf (PyMuPDF) 用於圖片提取 — 它提供頁面渲染和座標級別的文本/圖形檢查。
• pdfplumber 用於提取純文字。
• python-docx / python-pptx 用於生成交付物。

專案結構慣例

每篇論文在工作目錄根目錄下建立一個獨立的資料夾：

NN_YYYY-Journal-Topic/
  Original_Paper.pdf
  Journal_YYYY_Topic_LiteratureReview.docx
  Journal_YYYY_Topic_ArticleSharing.pptx
  full_text.txt              （提取的文字，中間產物）
  figures/                   （提取的主圖PNG，中間產物）
    fig1.png, fig2.png, ...
    captions.json            （圖號 -> 標題/頁面/邊界框清單）
  Topic_PopularScience.html   （可選，用於微信公眾號）

• NN：零填充的序號（01, 02, 03...）
• YYYY：出版年份
• Journal：期刊縮寫名稱（Nature, Cell, Science...）
• Topic：簡短的中文主題描述

工作流程

步驟 1：設定與 PDF 文字提取

1. 根據上述命名慣例建立輸出資料夾
2. 將原始PDF複製到新資料夾中
3. 執行 scripts/extract_pdf_text.py 提取全文：

   python scripts/extract_pdf_text.py "<pdf_path>" "<output_txt_path>"
   

   這會產生一個帶有頁碼分隔的 full_text.txt 檔案。

步驟 2：從 PDF 提取主圖

執行 scripts/extract_figures.py 提取每張主圖為高解析度PNG（預設300 DPI）：

python scripts/extract_figures.py "<pdf_path>" --out "<paper_folder>/figures" --dpi 300

• 加上 --include-ed 參數同時提取擴展數據/補充圖。
• 腳本會定位標題（"Fig. 1", "Figure 1", "圖1"），確定欄寬，合併標題上方的圖形區域，並渲染該區域。
• 已處理的版面變體（已在 Nature / Cancer Cell PDF 上驗證）：
  • 標題在插圖下方（最常見）；
  • 標題在插圖旁邊（標題在欄頂部，圖形在另一欄）；
  • 標題在插圖上方；
  • Cell Press "圖例在下一頁"：插圖在 N-1 頁，標題在 N 頁頂部 — 腳本檢測到標題上方沒有圖形時，會自動渲染前一頁的插圖（status: prev-page）。
  • 期刊橫幅：Cell Press / Cancer Cell 在頁面頂部的全寬彩色條會被過濾掉（status: above 不應包含它）。
• 如果圖像仍包含頁首，請提高 --header-frac 參數值（例如 Cancer Cell / Cell Genomics 使用 0.13，Nature 預設為 0.055）。
• 正文吸收防護：在"標題在插圖旁邊"模式下，圖像可能會滲入下方流動的正文段落。只有當文字區塊緊湊（高度短或寬度窄）且 ≦ 4 行，並且在 beside 模式下僅從圖形底部邊緣或以上開始時，才會吸收文字區塊。如果圖像最後仍包含一段散文，這就是需要收緊的規則。
• 輸出：figures/figN.png + figures/captions.json（標題文字、頁面、captions_page、邊界框、每張圖的提取狀態）。
• 務必檢視提取出的 PNG（使用 ViewImage）：檢查每張圖片是否為完整的圖形（所有圖版，未被裁剪，無混合正文）。如果圖片裁剪錯誤，請使用 PyMuPDF，以 captions.json 中的 bbox 為起點，手動重新渲染該區域。請勿靜默嵌入有缺陷的圖片。

步驟 3：深度閱讀論文

分段閱讀提取的文字（每次200行）。對於每張主圖，同時檢視提取的PNG以了解圖版和佈局。專注於提取：

• 標題、作者、期刊、DOI、出版日期
• 摘要和關鍵發現
• 所有圖表（編號、標題、圖版、每個圖版的內容）— 將 captions.json 中的標題與實際圖像進行交叉比對
• 方法（定序平台、軟體工具、演算法、參數）
• 樣本資訊（隊列規模、組織類型、定序類型）
• 關鍵結果與統計顯著性
• 作者提及的限制

步驟 4：生成 Word 深度閱讀報告

遵循 references/word_structure.md 中定義的10個章節結構。

使用 scripts/generate_word_report.py 作為模板。將其複製到論文資料夾中（例如 generate_word_report.py），將 CONTENT 區塊替換為實際分析內容，然後使用輸出路徑執行：

python generate_word_report.py "<paper_folder>/Journal_YYYY_Topic_LiteratureReview.docx"

該腳本示範了：

• 使用 python-docx 建立帶有樣式標題的文件
• 為基本資訊和術語設定表格格式
• 分析管線的項目符號列表
• 關鍵發現的彩色重點提示框
• add_figure_block()：嵌入每張提取的圖PNG + 標題 + 4部分分析（研究問題 / 方法 / 關鍵結果 / 解讀）

第7節（主要研究內容）必須嵌入提取的圖像檔案（figures/figN.png）— 每張圖一個圖像，每個圖像後接其逐圖分析。圖像路徑和標題來自 figures/ 和 captions.json。

關鍵格式規則：

• 標題使用 Heading 1/2/3 樣式並自訂格式
• 表格使用 "Light Grid Accent 1" 並加上明確的深色頁首填充（shade_cell(cell, "1A3A5C")）— 內建樣式在應用白色文字時會保留頁首行未填充狀態，使頁首在Word中不可見
• 圖像調整為寬度15.5公分，最大高度約18.5公分（透過PIL保持長寬比）。一個橫向的4圖版曼哈頓圖以全頁寬（21+公分高）呈現時會超出頁面並在底部被裁切 — 務必限制高度
• 超過一頁的表格：keep_rows_together(table) 將頁首行標記為 w:tblHeader（在每頁重複），並將每一行標記為 w:cantSplit，確保表格不會在中間斷行或遺失頁首
• 技術術語保留英文縮寫，後接中文解釋
• 無資料捏造：不確定的項目標記為"需確認"
• 透過匯出為PDF（Word COM SaveAs(..., 17)）驗證輸出，並檢視2–3頁：頁首行可見、圖形完整、無溢出

步驟 5：生成 PPT 分享簡報

遵循 references/ppt_structure.md 中定義的投影片結構。

使用 scripts/generate_ppt_slides.py 作為模板：

python scripts/generate_ppt_slides.py

該腳本示範了：

• 使用 python-pptx 建立帶有自訂版式的投影片
• Nature/Cell 風格的極簡設計（白色背景，深色文字）
• 逐圖投影片：在投影片上嵌入提取的 figures/figN.png，然後是圖標題 → 研究問題 → 方法 → 結果 → 意義
• 最終的關鍵發現 + 科學影響投影片

步驟 6：生成科普文章（可選）

當使用者需要微信公眾號文章時，撰寫一個HTML檔案，包含：

• 內聯CSS（微信會移除 <style> 標籤）
• 行動裝置優先設計（最大寬度：680px）
• 以隱喻為導向的科學傳播
• 數據卡片、比較表格、時間軸
• 所有數據必須來自原始論文，不得捏造

詳細寫作指南請參見 references/popular_science_style.md。

步驟 7：品質檢查

驗證：

• 所有技術術語都有英文縮寫 + 解釋
• 所有圖表在Word和PPT中都已涵蓋
• Word報告中的每張主圖都已驗證其嵌入圖像（圖版完整、無裁剪、無混入正文）
• 無捏造數據或推測性結論
• 分析管線完整（軟體 → 演算法 → 輸入/輸出）
• 統計值與原始論文一致

解讀原則

所有生成的內容均遵循 references/interpretation_principles.md。核心規則：

1. 保留英文縮寫 — 請勿直接翻譯成中文
2. 解釋技術原理 — 不僅說明是什麼，還要說明為什麼以及如何運作
3. 深度優先 — 回答"為什麼用這個方法？"、"數據顯示了什麼？"、"這意味著什麼？"
4. 目標讀者：生物資訊工程師、基因組研究人員
5. 無捏造 — 不確定的資訊標記為"需確認"

文件參考

文件	用途
scripts/extract_pdf_text.py	使用 pdfplumber 從 PDF 提取全文
scripts/extract_figures.py	使用 PyMuPDF 提取主圖為高解析度 PNG + captions.json 清單
scripts/generate_word_report.py	Word 文件生成的模板腳本（包含圖像嵌入）
scripts/generate_ppt_slides.py	PPT 投影片生成的模板腳本
references/word_structure.md	10章節 Word 報告結構規範（包含逐圖區塊格式）
references/ppt_structure.md	PPT 投影片結構規範
references/interpretation_principles.md	AI 解讀原則與規則
references/popular_science_style.md	科普文章寫作指南