從外洩原始碼拆解 Claude Code /insights — 安裝與使用指南
Claude Code 的 /insights 是一個非常實用的內建指令 — 它會分析你過去 30 天的對話記錄，產生一份互動式 HTML 報告，告訴你使用模式、摩擦點、甚至幫你寫好 CLAUDE.md 建議。
問題是，它是一個封裝在 CLI 內部的黑箱。你沒辦法自訂分析維度、指定專案範圍、或調整時間區間。
現在原始碼外洩了，我拿到完整的 3,200 行 TypeScript，把它拆出來重新設計，包裝成兩個版本。這篇記錄拆解的思路與最終的安裝方式。
關於這次外洩事件的完整報導，請看新聞：Claude Code 原始碼全面外洩。
/insights 到底做了什麼？
先理解原版的運作流程，才知道我們在拆什麼。原始碼揭露了四個階段：
Phase 1 — Lite Scan： 掃描 ~/.claude/projects/ 下所有 .jsonl session 檔案，只讀 filesystem metadata，快速篩選。
Phase 2 — 建立 SessionMeta： 對每個 session 提取量化統計 — duration、tool 使用次數、程式語言、token 用量、git activity、response times、甚至 multi-clauding timestamps（同時跑多個 Claude 的行為）。
Phase 3 — Facet Extraction： 用 LLM 對每個 session 做語意分析，提取 goals、friction、satisfaction 等結構化 JSON。原版用的是 Opus，每次完整執行要 50-60 次 API 呼叫。
Phase 4 — Insights Generation： 並行呼叫 LLM 產生 6-9 個 insight 區段，最後組裝成互動式 HTML 報告，輸出到 ~/.claude/usage-data/report.html。
報告包含的區塊：
| 區塊 | 內容 |
|---|---|
| At a Glance | 哪些做得好、哪些卡住了、快速改善建議 |
| Session 統計 | 總 session 數、訊息數、時數、commit 數，附圖表 |
| 工作內容 | 各專案的 session 分佈和摘要 |
| 摩擦點分析 | 所有摩擦點分類排序，附實際對話範例 |
| CLAUDE.md 建議 | 可直接複製貼上的規則，基於你重複給過的指示 |
| Skill & Hook 建議 | 把重複性多步驟操作轉成自訂 Skill 或 Hook |
拆解的思路
Step 1 — 取得完整原始碼
GitHub 上的外洩原始碼用 WebFetch 直接抓會被截斷或摘要，最後用 curl 下載完整的 insights.ts（3,200 行），再分段讀取分析。
Step 2 — 分析依賴與可複用度
不是所有程式碼都需要動。分析後發現：
- ~60% 可直接複用 — 純邏輯函式：
extractToolStats、aggregateData、detectMultiClauding、generateHtmlReport等 - ~40% 需替換 — 內部依賴：
queryWithModel（LLM 呼叫封裝）、session file 讀取、各種 internal utility
Step 3 — 關鍵架構決策：誰來當 LLM？
這是整個拆解最重要的一步。原版的 Phase 3 和 Phase 4 大量呼叫 LLM API，如果寫成獨立腳本，每次執行要自己付 API 費用（50-60 次 Opus 呼叫，不便宜）。
解法：包裝成 Skill + Sub-agent，讓 Claude Code 本身當 LLM。
| 獨立腳本 | Skill + Sub-agent | |
|---|---|---|
| 誰是 LLM | 你自己呼叫 API | Claude Code 本身 |
| API Key | 需要額外設定 | 不需要 |
| 額外費用 | 有（50-60 次 API call） | 零 |
最終架構：
- 純計算（掃描、統計、HTML 渲染）→ Node.js 腳本，用
Bashtool 執行 - 語意分析（facet extraction、insight generation）→ Claude Code Sub-agent 處理
Step 4 — 加入兩個維度
原版只能分析「所有專案、最近 30 天」。我加了兩個篩選維度：
- 專案維度 —
--project <name>模糊匹配目錄名稱 - 時間維度 —
--days <N>指定天數
這讓報告可以聚焦在特定專案的特定時段，而不是被所有對話的噪音淹沒。
Step 5 — 拆成兩個版本
根據使用情境拆成兩個版本：
| Command 版 | Skill 版 | |
|---|---|---|
| 安裝位置 | 全域（~/.claude/commands/） | 專案內（.claude/skills/） |
| 專案維度 | 有（可跨專案指定） | 無（自動偵測當前專案） |
| 時間維度 | 有 | 有 |
| 用法 | /insights emilwu-tw-site 7d | /insights 7d |
安裝方式
這兩個版本已經打包成 Claude Code Plugin，發布在統一的 Plugin Marketplace。
第一步：加入 Marketplace（每台電腦只需一次）
/plugin marketplace add emilwu/emilwu-plugins第二步：安裝你要的版本
# Command 版 — 跨專案分析
/plugin install claude-insights-command@emilwu-plugins
# Skill 版 — 當前專案分析
/plugin install claude-insights-skill@emilwu-plugins第三步：使用
# Command 版：指定專案 + 天數
/claude-insights-command:insights emilwu-tw-site 7d
# Skill 版：當前專案，指定天數
/claude-insights-skill:insights 7d第一次執行時，SessionStart hook 會自動執行 npm install 和 tsc 編譯 TypeScript，之後就不需要了。
關於打包成 Plugin 的過程和踩坑紀錄，我寫了另一篇實戰文章詳細說明，包含 Plugin 結構設計、驗證流程、以及統一 Marketplace 的建立。請看：實戰 Tips 2：把 Skill 打包成 Plugin 發布。
為什麼要用拆解版？
原版 /insights 很好，但它是一個封閉系統。拆解版的價值在於：
- 專案聚焦 — 可以只看某個專案的分析，不被其他專案的噪音干擾
- 時間控制 — 7 天、14 天、30 天，你決定
- 零額外費用 — 語意分析由 Claude Code 本身處理，不需要額外 API 呼叫
- 可學習 — 看到完整的實作，理解 Anthropic 怎麼設計 session 分析 pipeline
或許最有價值的不是工具本身，而是拆解過程中學到的東西 — 看到一個頂級 AI 團隊怎麼設計分析系統，然後用 Skill + Sub-agent 架構把它變成零成本版本，這本身就是一次很好的 Context Engineering 實踐。
相關資源：
- 新聞：Claude Code 原始碼全面外洩 — 外洩事件的完整報導
- 實戰 Tips 2：把 Skill 打包成 Plugin 發布 — Plugin 打包流程與踩坑紀錄
- GitHub: emilwu-plugins — 統一 Plugin Marketplace
- Claude Code usage analytics — 官方文件
支持這個系列
如果這系列文章對你有幫助，考慮請我喝杯咖啡
請我喝杯咖啡
