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 的唯一必要依賴）：
pip install pymupdf4llm # 若尚未安裝第二步：評估書籍大小
使用者提供 PDF 時，先執行：
python scripts/extract-text.py book.pdf --info輸出範例：
{
"title": "The Almanack of Naval Ravikant",
"page_count": 242,
"estimated_tokens": 95000,
"needs_chunking": true,
"suggested_chunks": 2
}第三步：文字提取（依大小決定策略）
小型書籍（estimated_tokens < 80,000）：一次提取全書
python scripts/extract-text.py book.pdf -o book.md大型書籍（estimated_tokens ≥ 80,000）：分批處理
# 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大型書籍的分析策略：
- 先讀目錄 + 前言 + 結論（掌握全貌），完成 TIPS 評分
- 分批讀取章節，每批產出局部分析筆記（論點、概念、引句、批判）
- 全部章節讀完後，整合所有局部筆記，合併重複概念、統一論點層次、補充跨章節的批判視角
- 產出一份完整 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={書名}（僅英文書）
流程：
- 用 WebFetch 搜尋 Gutendex API（中文書記得加
languages=zh） - 若找到匹配結果，下載 TXT 格式（優先
text/plain; charset=utf-8） - 用 extract-text.py 提取文字（或直接讀取 TXT）
- 進入標準分析流程（第二～五步）
- HTML 報告標註：「書籍來源：Project Gutenberg（公共領域版本）」
限制與回退：
- 公開書庫僅收錄公共領域書籍（多為 1928 年前出版）
- 搜尋無結果 → 回退到「依公開資料」模式，不阻塞流程
- WebFetch 不可用 → 直接跳過，走「僅書名」標準路徑
- 不強制：若使用者明確說「不需要下載」或「用你的知識就好」，跳過此步驟
詳細書庫清單與 API 用法見 references/ebook-library.md。
第四步：Claude 分析 → 輸出 JSON
Claude 讀取提取後的文字，執行分析流程（見下方），最終產出分析 JSON 檔案。JSON 結構定義見 references/json-schema.md。
第五步：渲染 HTML 報告
python scripts/render-report.py analysis.json -o reading-report-{slug}.html腳本讀取 JSON、套用 HTML 模板、輸出完整報告。零 token 消耗。
分析流程（內部）
使用者不需要知道階段名稱。按以下順序執行：
- 評估：TIPS 四維度快速評分（見下方速查表），作為評價指標顯示在報告中
- 結構解析：萃取全書骨架、核心提問、主論點、論證架構
- 深度分析：Adler 四問 + 樊登四問、底層假設萃取、Self-Explanation、思維模型萃取與認知差距捕捉
- 批判評估：Adler 三類反對、Steel-Manning、品質評估六維度
- 外部驗證（選用）：僅在使用者明確要求時才用 WebSearch 搜尋公眾討論
- 內化與行動：Zettelkasten 三層筆記結構、行動承諾（三要素）
- 產出 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 | 非常值得深讀 |
核心不變量
- 來源誠實 — 確認確實掌握書籍內容才開始分析。僅憑書名時，不確定的部分明確標示「依公開資料判斷」，絕不編造細節
- 方法論不外露 — 使用者永遠不會看到 Phase 編號、JSON 結構、方法論名稱（如 Adler、Zettelkasten）。TIPS 評分數字會顯示在 HTML 報告中
- 批判不缺席 — 證據越薄弱批判越深，但一律用自然語言表達
- 行動要具體 — 時間 + 對象 + 具體行動，缺一不可
- 留白引思考 — 報告中主動留下開放式提問，引導讀者形成自己的判斷，而非給出定論
特殊情境處理
- 部分閱讀：針對已讀部分分析，未讀部分標記為待補，不猜測
- 多語言書籍：始終用繁體中文輸出；引述原文時附中文翻譯。目標讀者為繁體中文使用者，書名處理規則：
- 英文書有中文譯名 → 中文書名（原文書名），例：「大亨小傳（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/analysis.md |
| HTML 報告設計規範（僅修改模板時需要） | references/design-spec.md |
| 公開電子書來源（書名模式下搜尋書庫時） | references/ebook-library.md |
載入原則：
- json-schema.md 在產出 JSON 前載入（不需讀 render-report.py）
- analysis.md 在進入分析階段時載入
- design-spec.md 通常不需載入（render-report.py 直接套用模板）；僅在需要理解或修改 HTML 結構時才載入