# Literature Review

> Skill: literature-review

- Skill: `kaito41418-ux/literature-review` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add kaito41418-ux/literature-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaito41418-ux/literature-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: kaito41418-ux (https://skillmd.com/u/kaito41418-ux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaito41418-ux/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 使用

然後調用組裝函數：
```python
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：

```python
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 供報告展示
```

**後端對比**：

| 後端 | 覆蓋 | 穩定性 | Rate limit | 適用場景 |
|---|---|---|---|---|
| `semantic_scholar` | 200M+ 論文，跨學科 | 高（官方 API） | shared pool ~1 req/s，可 x-api-key 提升 | **默認主力** |
| `scholarly` | Google Scholar 全庫 | 低（易 CAPTCHA） | 隨機延遲避免限流 | Semantic Scholar 覆蓋不足時 fallback |

**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` 欄位：
```python
for p in papers:
    if not p.get("relevant", True):
        continue
    p["summary_zh"] = "**研究目的**：...\n**使用方法**：...\n**核心結論**：..."
```

### Step 4 — 匯出 Word 報告

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

```python
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；跳過該篇的總結，或標記「摘要缺失，建議查閱原文」