Crisp Reading

所有路徑一律走完全流程，產出 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

大型書籍的分析策略：

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。

第四步：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 消耗。

分析流程（內部）

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

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 報告中，不影響分析深度——所有書籍一律執行完整深度分析。

評分速查：

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

總分解讀：

核心不變量

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

腳本工具

參考檔案載入表

載入原則：

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