Literature Review

Skill: literature-review

自動學術文獻檢索、篩選與綜述（Google Scholar via scholarly）與 Word 報告匯出。

Metadata

• Description: 從用戶的研究方向描述或示例文獻中提取關鍵字，組裝 Google Scholar 布爾檢索式，抓取論文元數據與摘要，逐篇撰寫中文三段式總結（目的 / 方法 / 結論），最終匯出含檢索策略、綜述精要、文獻詳解表、APA 7 引用列表的 .docx 報告。
• Version: 1.0.0
• Entrypoint: 純 Skill 模式 —— Claude 依 SOP 依序調用 tools/ 內函數；無 orchestrator.py。
• Related:
  • 統計假設檢驗：advanced-data-analytics
  • 迴歸建模：regression-analytics
  • 時間序列：time-series-analysis

觸發時機

當用戶說出以下任一意圖時觸發：

• 「幫我做一份 XX 主題的文獻綜述」
• 「我在研究 XX，幫我找 20 篇相關論文並總結」
• 「基於這篇論文的方向，找一批相關文獻寫綜述」
• 「開題報告的文獻部分，幫我先跑一輪 Google Scholar」

不觸發：單純問「XX 是什麼」（走一般問答）；要求下載 PDF 全文（本 skill 不做全文抓取）。

SOP（Claude 自我遵循的四步流程）

Step 1 — 提取關鍵字，組裝檢索式

閱讀用戶輸入（研究方向 / 示例論文標題+摘要），按以下 prompt 骨架自行產出 3–5 個英文核心術語：

關鍵字提取 prompt 骨架 從用戶描述中識別學術術語，遵循：

1. 英文為主（Google Scholar 對英文檢索效果最好）
2. 具體 > 抽象：「credit scoring」優於「finance」；「XGBoost」優於「machine learning」
3. 多詞術語不拆散："convolutional neural network" 作為一個 token
4. 產出 3–5 個，過少檢索面窄，過多會被 AND 收斂到零結果
5. 若用戶要求時間範圍（近五年 / 2020 以後），記住 year_from / year_to 供 Step 2 使用

然後調用組裝函數：

from tools.keyword_extractor import build_query
query = build_query(["XGBoost", "credit scoring", "imbalanced data"], mode="AND")
# → '"XGBoost" AND "credit scoring" AND "imbalanced data"'

Step 2 — 檢索學術資料庫（推薦 Semantic Scholar 為主力）

優先使用統一入口 search_papers（auto backend）：先試 Semantic Scholar 官方 API（穩定、無 CAPTCHA），失敗才 fallback 到 scholarly 爬 Google Scholar：

from tools.search_dispatcher import search_papers
result = search_papers(
    query,
    backend="auto",          # "semantic_scholar" | "scholarly" | "auto"
    max_results=20,
    year_from=2020,
)
if result["n_returned"] == 0:
    # 兩個後端都失敗，向用戶解釋並建議：
    # (1) 換更具體/更寬鬆的關鍵字
    # (2) 稍後重試（Semantic Scholar shared pool 429 是常見狀況）
    # (3) 若持續失敗，考慮申請 Semantic Scholar API key（免費）
    #     https://www.semanticscholar.org/product/api#api-key-form
    ...
papers = result["papers"]           # list of dict: title/authors/venue/year/citations/abstract/url
backend_used = result["backend"]    # 實際成功的後端，寫入 metadata 供報告展示

後端對比：

Tips：

• max_results=20 通常已足夠；一次拉太多會撞 rate limit 或觸發反爬
• 若用戶對特定期刊有偏好，關鍵字里明確帶進去（如 "Nature Machine Intelligence"）
• year_from / year_to 是強烈建議設置的，可以顯著收斂結果

Step 3 — 篩選並逐篇總結

逐條讀 abstract：

1. 相關性篩選：若 abstract 與用戶主題明顯偏離，將該 paper 從 papers 中移除或標記 relevant=False。給出簡短理由（供最終報告的 warnings 段落展示）
2. 中文三段式總結（Claude 按以下 prompt 骨架自行生成）：

論文總結 prompt 骨架 讀完 abstract 後，用繁體中文寫三段：

• 研究目的（≤3 句）：這篇論文想解答什麼問題？
• 使用方法（≤3 句）：資料來源、模型/方法、實驗設計。避免技術術語堆砌
• 核心結論（≤3 句）：具體發現、關鍵數字、局限性

禁止：整段複讀 abstract；虛構原文未提及的細節；使用「本文」「該研究」以外的主觀評價（如「非常有價值」）

將總結填入每個 paper 的 summary_zh 欄位：

for p in papers:
    if not p.get("relevant", True):
        continue
    p["summary_zh"] = "**研究目的**：...\n**使用方法**：...\n**核心結論**：..."

Step 4 — 匯出 Word 報告

先由 Claude 撰寫一段跨論文的融會貫通「綜述精要」（review_body），然後：

from tools.word_generator import generate_review_docx
docx_path = generate_review_docx(
    query=query,
    review_body=review_body_md,        # Markdown 段落，會按 \n\n 分段落
    papers=papers,                      # 已含 summary_zh
    output_path=r"./outcome-temp/Literature_Review.docx",
    metadata={
        "n_requested": 20,
        "n_returned": len(papers),
        "year_from": 2020,
        "backend": backend_used,           # 從 result["backend"] 讀出實際命中的後端
    },
)
print(f"報告完成：{docx_path}")

Output Location

預設輸出：./outcome-temp/Literature_Review.docx

Word 報告結構（章節順序固定）：

1. 檢索策略說明（布爾檢索式 + 後端 + 請求/返回數 + 時間過濾）
2. 文獻綜述精要（跨論文的融會貫通）
3. 核心文獻詳解表格（No / Title / Year / Citations / 中文總結）
4. 參考文獻列表（APA 7 風格 + URL）

Constraints

• 英文字體 Times New Roman 11pt，中文字體 宋體（fallback Microsoft YaHei）
• 布爾檢索式最多 5 個 AND 項，避免結果為零
• search_scholar 上限 30 篇 / 次；再多請分批
• abstract 缺失時仍保留 paper，但總結標「摘要缺失」

Dependencies

• Python 3.10+: scholarly>=1.7 python-docx>=1.0 requests>=2.28
• 無 R 依賴
• 可選：SEMANTIC_SCHOLAR_API_KEY 環境變數（申請免費 API key 可獲得更高速率上限）

Failure Modes（Claude 遇到時的應對）

• n_returned == 0 且 backend_attempts 兩個都失敗 → 建議用戶：換更具體或更寬鬆的關鍵字 / 稍後重試 / 申請 Semantic Scholar API key
• errors 含 HTTP 429 → Semantic Scholar shared pool 撞牆；本 skill 已自動指數退避重試 5 次，若仍失敗說明當前 IP 排隊嚴重，等 5-10 分鐘再試
• errors 含 CAPTCHA / Cannot Fetch → scholarly 被 Google Scholar 拒絕；auto 模式已自動優先走 Semantic Scholar，若仍 fallback 到 scholarly 表示 Semantic Scholar 也返回零
• abstract 全空 → 極少數 paper Semantic Scholar 沒有 abstract；跳過該篇的總結，或標記「摘要缺失，建議查閱原文」