claude-usage開發(fā)者指南3個(gè)Python文件、零依賴背后的完整架構(gòu)與測試體系【免費(fèi)下載鏈接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cl/claude-usageclaude-usage 是一個(gè)用于追蹤 Claude Code token 用量、成本與會(huì)話歷史的本地儀表盤只需 3 個(gè) Python 文件、零第三方依賴即可運(yùn)行。本文從架構(gòu)設(shè)計(jì)、數(shù)據(jù)流、SQLite 存儲(chǔ)到測試體系完整拆解這個(gè)極簡項(xiàng)目的實(shí)現(xiàn)邏輯幫助你理解如何用純標(biāo)準(zhǔn)庫構(gòu)建一個(gè)實(shí)用的用量監(jiān)控工具。項(xiàng)目定位為什么零依賴是核心賣點(diǎn)Claude Code 會(huì)在本地寫入詳細(xì)的 JSONL 用量日志——token 數(shù)、模型、會(huì)話、項(xiàng)目無論你的訂閱計(jì)劃是什么。claude-usage 讀取這些日志將其轉(zhuǎn)化為圖表和成本估算并支持 API、Pro 和 Max 三種計(jì)劃。它的關(guān)鍵設(shè)計(jì)哲學(xué)是任何在跑 Claude Code 的人都已經(jīng)裝了 Python。因此項(xiàng)目只使用標(biāo)準(zhǔn)庫sqlite3、http.server、json、pathlib無需pip install、無需虛擬環(huán)境、無構(gòu)建步驟。這個(gè)承諾在 pyproject.toml 中被顯式固化dependencies []并注釋說明the tool stays stdlib-only at runtime該工具在運(yùn)行時(shí)保持純標(biāo)準(zhǔn)庫。核心架構(gòu)3 個(gè) Python 文件的職責(zé)劃分整個(gè)項(xiàng)目主體由 3 個(gè)扁平的頂層模塊組成這也是pyproject.toml中py-modules [cli, scanner, dashboard]的由來文件職責(zé)scanner.py解析 JSONL 會(huì)話記錄寫入 SQLite 數(shù)據(jù)庫cli.py提供scan/today/week/stats/dashboard終端命令dashboard.py單文件 HTTP 服務(wù)器 內(nèi)嵌 HTML/JS 單頁儀表盤數(shù)據(jù)流全景項(xiàng)目的數(shù)據(jù)流在 AGENTS.md 中有一條清晰的鏈路~/.claude/projects/**/*.jsonl → scanner.parse_jsonl_file() 聚合 → upsert_sessions() insert_turns() ↓ ~/.claude/usage.db (SQLite) ↓ cli.py 查詢 ←──────────→ dashboard.py /api/datascanner.pyparse_jsonl_file 解析每條assistant類型記錄中的 token 字段input、output、cache_read、cache_creation與模型名scan 函數(shù)負(fù)責(zé)增量掃描cli.py終端報(bào)表calc_cost按 turn 逐條計(jì)費(fèi)后求和dashboard.pyDashboardHandler 基于http.server.BaseHTTPRequestHandler提供兩個(gè)端點(diǎn)——GET /api/data返回 JSON 快照和POST /api/rescan刪除數(shù)據(jù)庫并全量重掃整個(gè) UI 以HTML_TEMPLATE原始字符串形式內(nèi)嵌Chart.js 從 CDN 加載每 30 秒自動(dòng)刷新存儲(chǔ)設(shè)計(jì)3 張表撐起增量掃描SQLite 數(shù)據(jù)庫位于~/.claude/usage.db由 scanner.py 的init_db創(chuàng)建并自動(dòng)遷移turns表——每個(gè) assistant API 響應(yīng)一行是 token 數(shù)與模型歸屬的事實(shí)來源sessions表——按會(huì)話聚合的冗余匯總總額 主模型processed_files表——增量掃描跟蹤記錄(path, mtime, lines)mtime 不變則跳過文件增長時(shí)只處理新增行這使得重復(fù)運(yùn)行python cli.py scan非?？?。此外turns.message_id上的條件唯一索引讓INSERT OR IGNORE能低成本地跨重掃去重。三個(gè)必須知道的非顯而易見不變量AGENTS.md 特別列出了三個(gè)容易踩坑的設(shè)計(jì)點(diǎn)流式去重Claude Code 每個(gè) API 響應(yīng)會(huì)寫多條 JSONL 記錄只有同一message.id的最后一條才有最終用量統(tǒng)計(jì)。解析器只保留每個(gè) message_id 的最后一條記錄切勿跨記錄累加會(huì)話總額重算增量掃描中 token 是累加的掃描結(jié)束時(shí)會(huì)用turns表重算sessions總額防止重復(fù) turn 導(dǎo)致數(shù)據(jù)漂移會(huì)話主模型優(yōu)先級(jí)opus sonnet haiku見 _model_priority避免子代理的 haiku turn 覆蓋會(huì)話的 opus 模型成本計(jì)算按 turn 計(jì)費(fèi)而非按總量一個(gè)常見錯(cuò)誤是先聚合 token 再用單一價(jià)格計(jì)費(fèi)——這對(duì)跨多模型的會(huì)話是錯(cuò)誤的。claude-usage 的做法是每個(gè) turn 都知道自己的模型逐條計(jì)費(fèi)后求和。價(jià)格表在 cli.py 的PRICING字典Python和 dashboard.pyHTML_TEMPLATE內(nèi)的PRICING常量JavaScript中各存一份測試test_prices_match強(qiáng)制兩者保持一致。測試體系純 unittest 覆蓋全部關(guān)鍵路徑項(xiàng)目測試只依賴標(biāo)準(zhǔn)庫unittest完整測試套件運(yùn)行方式簡單python -m unittest discover -s tests -vCI 在 Python 3.9 / 3.11 / 3.12 三個(gè)版本上運(yùn)行。測試目錄 tests/ 的分工測試文件覆蓋內(nèi)容test_scanner.py解析、去重、增量掃描、schema 遷移、標(biāo)題回填test_dashboard.pyAPI 數(shù)據(jù)結(jié)構(gòu)、HTML 模板完整性、前后端價(jià)格表同步test_cli.py定價(jià)解析的三級(jí)匹配精確 → 前綴 → 子串、成本計(jì)算、數(shù)字格式化test_subagent.py子代理識(shí)別sidechain 標(biāo)記、agent_id、路徑判斷與 dispatch 提取test_cli_subagent.py終端命令在舊 schema 下不崩潰test_dashboard_subagent.py子代理 token 數(shù)據(jù)接口test_version.py三處版本號(hào)強(qiáng)同步校驗(yàn)其中 test_version.py 值得單獨(dú)一提它校驗(yàn)scanner.py中的VERSION當(dāng)前為1.5.5、CHANGELOG 標(biāo)題、以及 VS Code 擴(kuò)展 package.json 三處版本一致——這正是發(fā)布流程三處版本 lockstep的守護(hù)。測試約定同樣記錄在 AGENTS.mdscanner 和 dashboard 測試使用tempfile.NamedTemporaryFile建立隔離數(shù)據(jù)庫絕不觸碰用戶真實(shí)的~/.claude/usage.db/api/rescan測試通過 monkey-patchdashboard.DB_PATH和scanner.DEFAULT_PROJECTS_DIRS工作這個(gè)契約必須保持Windows 上全新檢出可能沒有~/.claude/目錄get_db的mkdir(parentsTrue, exist_okTrue)不可移除否則sqlite3.connect會(huì)在 CI 中失敗周邊生態(tài)Docker 與 VS Code 擴(kuò)展Dockerscripts/run-docker.sh 構(gòu)建鏡像并以只讀方式掛載~/.claude容器可讀不可改用命名卷持久化 SQLite 數(shù)據(jù)庫儀表盤運(yùn)行在 http://localhost:9898鏡像定義見 DockerfileVS Code 擴(kuò)展vscode-extension/ 將同一 UI 以活動(dòng)欄側(cè)邊欄形式嵌入編輯器Python 源碼直接打包進(jìn).vsix最終用戶只需 PATH 上有 Python 3.8。其中 port-allocator.ts 通過workspaceState記住并復(fù)用上次端口保證 iframe 內(nèi)的localStorage狀態(tài)在窗口重載后不丟失快速上手克隆并跑起來git clone https://gitcode.com/gh_mirrors/cl/claude-usage cd claude-usage python3 cli.py dashboard瀏覽器將自動(dòng)打開 http://localhost:8080看到會(huì)話數(shù)、輸入/輸出 token、緩存讀寫、估算成本等統(tǒng)計(jì)卡片以及按模型過濾、按日期范圍縮放的交互圖表?？偨Y(jié)值得借鑒的極簡工程范式claude-usage 展示了幾個(gè)對(duì)獨(dú)立開發(fā)者很有參考價(jià)值的做法約束驅(qū)動(dòng)設(shè)計(jì)把零依賴寫成pyproject.toml里的硬約束空依賴 注釋說明讓每個(gè)貢獻(xiàn)者都無法繞開文檔即契約AGENTS.md 不只寫怎么做更寫哪些不變量不能破壞把踩坑經(jīng)驗(yàn)固化為團(tuán)隊(duì)與 AI 編碼代理共享的知識(shí)單一事實(shí)來源 校驗(yàn)測試版本號(hào)、價(jià)格表這類容易漂移的數(shù)據(jù)都配有強(qiáng)制同步的測試守護(hù)扁平優(yōu)于分層3 個(gè)頂層模塊、無包目錄與倉庫結(jié)構(gòu)一一對(duì)應(yīng)閱讀路徑極短一個(gè)工具3 個(gè) Python 文件17 個(gè)測試類——這正是小項(xiàng)目也要有完整工程體系的最好示范?！久赓M(fèi)下載鏈接】claude-usageA local dashboard for tracking your Claude Code token usage, costs, and session history. Pro and Max subscribers get a progress bar. This gives you the full picture.項(xiàng)目地址: https://gitcode.com/gh_mirrors/cl/claude-usage創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考