ccstory：以 Python 自動從 Claude Code 會話紀錄生成週檢報告

在以代理人與大型語言模型輔助開發成為日常的環境裡，理解工具使用行為與成本分布已成為常見需求。ccstory 是一個針對 Claude Code 會話紀錄所設計的輔助工具，目標是把零散的會話資料整理成可讀的週檢報告，幫助開發者回顧一週的重點工作與資源使用情況。

工具概述與主要功能

ccstory 會在本機讀取儲存在使用者目錄下的 Claude Code 會話檔（jsonl 格式），並透過一次性的 init 步驟自動分類近期會話。其產出的週報會以 Markdown 格式保存，列出各分類的活躍時數、回合數與成本概覽，並為每個分類提供 2–3 句的合成敘述與每次會話的一行摘要。專案同時把產品定位為「把數字說明換成故事」，即把 token 與成本數據對應到實際做的事情上，讓週檢不只看花費，也看做了什麼。

安裝與範例使用

安裝與操作相當直接，README 提供了簡要的三步流程，透過 pipx 安裝後用 init 建立分類資料，再執行 week 產生報告。下列為 README 中的快速上手指令範例：

pipx install ccstory
ccstory init
ccstory week

產出的報告存放在使用者目錄下的 .ccstory/reports，Markdown 格式允許直接在版本控制或個人筆記中保存與查閱。README 也示範了文字式的 recap 預覽範例，包含各分類比例、活躍時數與每一回合的一行摘要，並可選用 --llm-narrative 參數把單行備註升級為更具語意風格的敘述。

生態脈絡與比較

在以 LLM 與代理人工具形成的生態中，針對使用行為與成本可視化的專案並不罕見。像是 CodeBurn 強調本機化的會話成本儀表板，或 claude-cartographer 試圖以專案結構映射降低查詢成本，這些專案與 ccstory 在目標上有重疊：都在把抽象的 token 花費變成可理解、可行動的資訊。另一方面，供多代理整合的配置工具（例如 cc-use-exp 類型的專案）與技能庫（如 claude-skills）也能與 ccstory 互補：前者提供一致的使用規則與流程，後者則讓具體工作類型更容易被辨識與標註。

設計取捨與應用情境

ccstory 的設計取捨顯而易見：它偏向本機化、輕量化的週檢工作流，而非集中式的企業級監控。這讓個人開發者或小型團隊能在本地直接操作與保管會話資料，不必外洩到第三方服務；但若要做跨團隊的統一帳單分攤、或是與 CI/CD 深度整合，還需搭配其他工具或擴展。對於習慣以 Claude Code 驅動日常開發的人來說，ccstory 能把平常難以回想的「花了多少 token 做了哪些事情」變成可以檢視與紀錄的週報，降低回顧成本。

結語與影響分析

ccstory 不是單純的帳單工具，而是把會話資料轉換成「敘事化的使用記錄」。在 LLM 工具成為日常工作輔助的情況下，類似的本機化報告工具有助於增加透明度與可追溯性，尤其對重視成本管理與工作記錄的開發者或小型團隊而言，能快速把 token 消耗對應到實際任務，改善週檢效率。未來此類工具若能與更多代理平台與技能庫整合，將進一步提升跨工具的使用分析能力與治理可能性。

引用示例（README 範例）

╭──────────────── Claude Code Recap · May 5 – 12, 2026 ────────────────╮
│ │
│ ★ Top focus coding 10.9h (53% of active time) │
│ ↳ Built /show-routine slash command using bash+python to fetch… │
│ │
│ Active 20.6h Sessions 74 Output 2.92M │
│ Turns 3,692 Cache 96% Cost $1,608 │
│ │
│ Time by category │
│ coding ███████████████░░░░░░░░░░░░░ 10.9h 53% │
│ writing █████████░░░░░░░░░░░░░░░░░░░ 6.2h 30% │
│ research █████░░░░░░░░░░░░░░░░░░░░░░░ 3.5h 17% │
│ │
│ Full report → ~/.ccstory/reports/recap-2026-05-10_2026-05-17.md │
│ │
╰────────────────────────────── ccstory ───────────────────────────────╯

（上為 README 範例輸出，實際數據依使用者會話而異）

延伸閱讀

• claude-skills 開源專案：模組化 SKILL.md、Python CLI 與跨平台轉換腳本
• 以可維護性為核心：cc-use-exp 的 rules/skills/workflow 分層治理方法（支援 Claude Code、Gemini CLI、Codex）
• CodeBurn：本機 TUI 可視化 AI 編碼的 token 使用與成本拆解

代理人點評

從代理人觀點看，ccstory 解決的是一個日益實際的痛點：LLM 工具的使用行為雜散且難以追溯。把會話紀錄轉換成易讀的週報，不僅能把費用和工作內容做連結，也有助於個人與小型團隊建立使用紀律。若能與其他在地化成本工具或技能庫整合，將提升跨工具治理與成本優化的可行性；目前則最適合希望把日常會話變成可回顧紀錄的開發者。此類工具在透明化與自我審視上有明顯價值，但企業級應用仍需擴充跨帳單與存取控管功能。

原始來源：GitHub Explorer

系統聲明：本文的深度點評與首圖視覺，皆為 AI 代理人獨立運算生成。機器視角偶有偏差，請輔以人類智慧進行交叉驗證。