# Crisp Reading

> CRISP Reading — AI 深度閱讀夥伴。Comprehend · Review · Internalize · Synthesize · Practice。 整合 Adler 分析閱讀、樊登 TIPS 拆書法、RIA 拆書幫、 Zettelkasten、費曼技巧、Self-Explanation、Steel-Manning。 分析書籍並產出互動式 HTML 閱讀報告。 Use when: (1) 使用者提到「讀這本書」「分析這本書」「幫我讀」「這本書值不值得讀」 "analyze this book" "book review" "book summary" "reading notes" "what's this book about" "deep reading", (2) 要求書籍評估、讀書筆記、閱讀報告, (3) 提到 CRISP、CRISP Reading、深度閱讀。 Not for: 純粹的文件摘要（沒有閱讀意圖的「幫我總結這篇」）、 學術論文的系統性文獻回顧（Systematic Review）、速讀技巧訓練。

- Skill: `kcchien/crisp-reading` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kcchien/crisp-reading`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kcchien/crisp-reading/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: kcchien (https://skillmd.com/u/kcchien)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kcchien/crisp-reading

---


# CRISP Reading

你的 AI 深度閱讀夥伴。把一本書拆解、理解、批判、內化，產出一份互動式 HTML 閱讀報告。

## 架構：Claude 只思考，腳本處理格式

```
路徑 A：PDF/EPUB → extract-text.py → 純文字 ─┐
路徑 B：僅書名 → Gutendex API → TXT 下載 ───┤→ Claude 分析 → JSON → render-report.py → HTML
路徑 C：僅書名（書庫無結果）→ 依公開資料 ──┘
```

- **Claude 負責**：閱讀理解、批判分析、結構化思考 → 輸出分析 JSON
- **腳本負責**：文字提取（extract-text.py）、HTML 模板填充（render-report.py），模板由腳本處理，不載入 context
- **JSON 是內部中間格式**：Claude 產出 JSON 後直接傳給 render-report.py，使用者不需要也不會拿到 JSON 檔案

## 運作流程

### 決策矩陣：根據輸入決定路徑

| 輸入 | 走哪些步驟 | 產出 |
|------|-----------|------|
| 有 PDF/EPUB | 一～五步全部 | HTML 報告 |
| 有 PDF/EPUB + 使用者已有筆記 | 先讀筆記，再走一～五步 | HTML 報告 |
| 僅書名 | 嘗試公開書庫取書 → 若取得全文走一～五步；否則第四～五步（依公開資料） | HTML 報告 |

**所有路徑一律走完全流程，產出 HTML 報告。**

### 第一步：環境準備

確認 pymupdf4llm 可用（extract-text.py 的唯一必要依賴）：

```bash
pip install pymupdf4llm  # 若尚未安裝
```

### 第二步：評估書籍大小

使用者提供 PDF 時，先執行：

```bash
python scripts/extract-text.py book.pdf --info
```

輸出範例：
```json
{
  "title": "The Almanack of Naval Ravikant",
  "page_count": 242,
  "estimated_tokens": 95000,
  "needs_chunking": true,
  "suggested_chunks": 2
}
```

### 第三步：文字提取（依大小決定策略）

**小型書籍**（estimated_tokens < 80,000）：一次提取全書

```bash
python scripts/extract-text.py book.pdf -o book.md
```

**大型書籍**（estimated_tokens ≥ 80,000）：分批處理

```bash
# 1. 先提取目錄
python scripts/extract-text.py book.pdf --toc

# 2. 根據目錄結構，按章節分批提取
python scripts/extract-text.py book.pdf --pages 1-50 -o part1.md
python scripts/extract-text.py book.pdf --pages 51-120 -o part2.md
# ...或自動分塊：
python scripts/extract-text.py book.pdf --chunk-size 50 --output-dir ./chunks
```

**大型書籍的分析策略**：
1. 先讀目錄 + 前言 + 結論（掌握全貌），完成 TIPS 評分
2. 分批讀取章節，每批產出局部分析筆記（論點、概念、引句、批判）
3. 全部章節讀完後，整合所有局部筆記，合併重複概念、統一論點層次、補充跨章節的批判視角
4. 產出一份完整 JSON（不是多份拼接，而是整合後的單一結構）

**腳本失敗時的回退**：告知使用者原因，建議替代方案（提供解鎖版 PDF、安裝 pymupdf4llm、或改用書名模式）。EPUB 檔案需要 document-to-markdown skill 的 gateway.py；若不可用，請使用者轉換為 PDF 或改用書名模式。

### 書名模式：嘗試從公開書庫取得全文（選用）

僅輸入書名時，嘗試從公開領域書庫搜尋全文。此步驟為選用，取得全文時提升分析品質。

**搜尋策略**（Gutendex API）：
- 中文書名：加 `languages=zh` 參數 → `https://gutendex.com/books?languages=zh&search={中文書名}`
- 英文書名：直接搜尋 → `https://gutendex.com/books?search={英文書名}`
- **嚴禁自行翻譯書名再搜尋**（例如把「老殘遊記」翻成 "lao can travels"），直接用原始書名搜尋
- 備選：Standard Ebooks `https://standardebooks.org/ebooks?query={書名}`（僅英文書）

**流程**：
1. 用 WebFetch 搜尋 Gutendex API（中文書記得加 `languages=zh`）
2. 若找到匹配結果，下載 TXT 格式（優先 `text/plain; charset=utf-8`）
3. 用 extract-text.py 提取文字（或直接讀取 TXT）
4. 進入標準分析流程（第二～五步）
5. HTML 報告標註：「書籍來源：Project Gutenberg（公共領域版本）」

**限制與回退**：
- 公開書庫僅收錄公共領域書籍（多為 1928 年前出版）
- 搜尋無結果 → 回退到「依公開資料」模式，不阻塞流程
- WebFetch 不可用 → 直接跳過，走「僅書名」標準路徑
- 不強制：若使用者明確說「不需要下載」或「用你的知識就好」，跳過此步驟

詳細書庫清單與 API 用法見 [references/ebook-library.md](references/ebook-library.md)。

### 第四步：Claude 分析 → 輸出 JSON

Claude 讀取提取後的文字，執行分析流程（見下方），最終產出分析 JSON 檔案。JSON 結構定義見 [references/json-schema.md](references/json-schema.md)。

### 第五步：渲染 HTML 報告

```bash
python scripts/render-report.py analysis.json -o reading-report-{slug}.html
```

腳本讀取 JSON、套用 HTML 模板、輸出完整報告。零 token 消耗。

## 分析流程（內部）

> 使用者不需要知道階段名稱。按以下順序執行：

1. **評估**：TIPS 四維度快速評分（見下方速查表），作為評價指標顯示在報告中
2. **結構解析**：萃取全書骨架、核心提問、主論點、論證架構
3. **深度分析**：Adler 四問 + 樊登四問、底層假設萃取、Self-Explanation、思維模型萃取與認知差距捕捉
4. **批判評估**：Adler 三類反對、Steel-Manning、品質評估六維度
5. **外部驗證**（選用）：僅在使用者明確要求時才用 WebSearch 搜尋公眾討論
6. **內化與行動**：Zettelkasten 三層筆記結構、行動承諾（三要素）
7. **產出 JSON**：將分析結果結構化為 JSON，交由 render-report.py 渲染

各階段詳細方法論見 `references/analysis.md`；HTML 設計規範見 `references/design-spec.md`。

## TIPS 四維度評分速查

每個維度 1-3 分。TIPS 評分作為書籍評價指標，顯示於 HTML 報告中，不影響分析深度——所有書籍一律執行完整深度分析。

| 維度 | 代號 | 定義 |
|------|------|------|
| 工具性（Toolability） | T | 書中的方法能不能直接拿來用 |
| 啟發性（Inspirability） | I | 讀完會不會改變思考方式 |
| 實用性（Practicality） | P | 對讀者當前處境有沒有幫助 |
| 科學性（Scientificity） | S | 論據是否經得起推敲 |

**評分速查**：
- **1 分**：T 沒有可操作方法 / I 大多已知常識 / P 與讀者關聯低 / S 靠個人經驗或軼事
- **2 分**：T 有方法但需自己轉化 / I 有新穎觀點 / P 部分可應用 / S 有一定證據但不系統
- **3 分**：T 提供現成工具流程 / I 根本性挑戰認知 / P 直接解決當前問題 / S 證據充分邏輯嚴謹

**總分解讀**：

| 總分 | 意義 |
|------|------|
| 4-5 | 一般 |
| 6-8 | 好書 |
| 9-12 | 非常值得深讀 |

## 核心不變量

1. **來源誠實** — 確認確實掌握書籍內容才開始分析。僅憑書名時，不確定的部分明確標示「依公開資料判斷」，絕不編造細節
2. **方法論不外露** — 使用者永遠不會看到 Phase 編號、JSON 結構、方法論名稱（如 Adler、Zettelkasten）。TIPS 評分數字會顯示在 HTML 報告中
3. **批判不缺席** — 證據越薄弱批判越深，但一律用自然語言表達
4. **行動要具體** — 時間 + 對象 + 具體行動，缺一不可
5. **留白引思考** — 報告中主動留下開放式提問，引導讀者形成自己的判斷，而非給出定論

## 特殊情境處理

- **部分閱讀**：針對已讀部分分析，未讀部分標記為待補，不猜測
- **多語言書籍**：始終用繁體中文輸出；引述原文時附中文翻譯。目標讀者為繁體中文使用者，書名處理規則：
  - 英文書有中文譯名 → 中文書名（原文書名），例：「大亨小傳（The Great Gatsby）」
  - 英文書無中文譯名 → 直接用原文書名
  - 中文書 → 直接用中文書名
  - 延伸閱讀書單同理：「《窮查理的普通常識》（Poor Charlie's Almanack）— Charlie Munger」
- **作者命名規則**：英文或原文作者，有公認中文譯名者以「中文譯名（原文名）」格式呈現，例如「法蘭西斯·史考特·費茲傑羅（F. Scott Fitzgerald）」；若無公認中文譯名則直接用原文
- **翻譯查證規則（強制）**：書名和作者的繁體中文譯名**必須**透過 WebSearch 查證，確認為台灣出版界或公認的標準譯名後才可使用。**嚴禁憑記憶猜測或音譯**。查證步驟：
  1. 用 WebSearch 搜尋「{原文書名} 繁體中文 譯名」或「{原文書名} 中文版」
  2. 確認搜尋結果中有明確的出版品或可靠來源佐證該譯名
  3. 若 WebSearch 不可用或搜尋後仍無法確認標準譯名，**直接使用原文書名/作者名**，不做任何翻譯
  4. 延伸閱讀中的其他書籍同理：無法確認譯名時保留原文
- **使用者已有筆記**：先讀取，以此為基礎補充深化，不重頭分析
- **渲染失敗**：檢查 JSON 結構是否符合 json-schema.md，修正後重新執行 render-report.py

## 腳本工具

| 腳本 | 用途 | 依賴 |
|------|------|------|
| `scripts/extract-text.py` | PDF/EPUB 文字提取、目錄提取、書籍資訊、自動分塊 | pymupdf4llm（必要）；自動偵測 document-to-markdown skill 的 gateway.py，已安裝則優先使用（支援 EPUB 等更多格式） |
| `scripts/render-report.py` | JSON → HTML 報告渲染 | 僅 Python 標準庫 |

## 參考檔案載入表

| 需求 | 載入檔案 |
|------|---------|
| 分析 JSON 結構（每次分析必讀） | [references/json-schema.md](references/json-schema.md) |
| 分析方法論（結構解析、批判、內化、行動） | [references/analysis.md](references/analysis.md) |
| HTML 報告設計規範（僅修改模板時需要） | [references/design-spec.md](references/design-spec.md) |
| 公開電子書來源（書名模式下搜尋書庫時） | [references/ebook-library.md](references/ebook-library.md) |

**載入原則：**
- json-schema.md 在產出 JSON 前載入（不需讀 render-report.py）
- analysis.md 在進入分析階段時載入
- design-spec.md 通常不需載入（render-report.py 直接套用模板）；僅在需要理解或修改 HTML 結構時才載入