拆解claude-usage VS Code扩展Python服务器启动、端口分配与状态保持的完整原理【免费下载链接】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.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usageclaude-usage是一个本地 Claude Code 令牌用量统计仪表盘它的 VS Code 扩展版把完整的 Python Web 仪表盘一键嵌入编辑器侧边栏自动定位 Python 解释器与安装位置、启动本地 HTTP 服务器、分配空闲端口并在 Webview 中展示 token 用量、花费与会话历史——全程数据不出本机无 API 调用、无遥测。一键启动Python 服务器是如何跑起来的点击活动栏的量表图标后扩展实际执行了一条四步流水线定位仪表盘启动方式 → 定位 Python 解释器 → 分配端口 → 派生进程并探测就绪。整条流程集中在 extension.ts 的doStartup()中。安装模式判定五级优先级兜底install-mode.ts 中的resolveInstallMode()负责回答第一个问题——用什么程序来跑仪表盘按顺序尝试你在设置中显式配置的claudeUsage.cliPath显式配置永远优先扩展包内自带的python/cli.py——打包时由 copy-python.js 从仓库根目录复制进去是市场安装用户最常命中的路径只需系统装有 Python 即可PATH 上的claude-usage命令Homebrew 公式安装的用户当前工作区文件夹里的cli.py旧版把克隆仓库作为工作区的用法扩展目录同级目录的cli.py开发者从源码 F5 调试的场景。全部落空时才显示友好的错误提示而不是静默崩溃。找不到 Python 时提示语还会按平台给出针对性建议——比如提醒 Windows 用户安装时勾选 Add Python to PATH。定位 Python 解释器不经过 shell 的 PATH 遍历clone 模式下需要python3 /path/to/cli.py dashboard ...这样的调用解释器得自己找。python-locator.ts 不启动任何 shell而是手动遍历PATH环境变量的每个目录依次尝试python3、pythonWindows 上补.exe变体。这样做既避开了命令注入风险又让单测可以直接打桩。唯一硬性要求是 Python 3.8。进程派生状态机与不被骗的就绪探测server-manager.ts 用一个清晰的状态机管理 Python 进程的生命周期stopped → starting → ready超时或进程提前退出则转入failedready后进程退出转exiteddispose()统一回到stopped。三个细节值得展开 就绪探测严于返回 200defaultProbe 只认 200 OK 且响应 JSON 里含有仪表盘/api/data端点特有键如all_models防止被恰好占用同一端口的其他本地服务骗过并发调用合并快速双击图标时startupInFlight 这个 Promise 会把重复的启动请求合并到同一次避免双进程互踩、留下孤儿进程只绑定 127.0.0.1代码注释写明了原因——历史上暴露过0.0.0.0配置但那会把你的用量数据暴露到局域网属于隐私问题。服务器 Python 侧的入口是 cli.py配套 scanner.py 扫描本机 JSONL 会话日志、dashboard.py 渲染页面。扩展派生时附带--no-browser参数阻止它按 CLI 习惯再弹出一个系统浏览器窗口。端口分配从每次随机到稳定复用这是整个扩展最微妙的设计点。端口选择看似简单实则有两个陷阱写死端口会与其他程序冲突每次随机取端口虽不冲突但端口一变副作用就来了——仪表盘是以 iframe 嵌入侧边栏的而 Webview 的 localStorage折叠卡片状态、更新检查缓存以 iframe 的源http://127.0.0.1:端口为键。端口一变本地状态就被无声清空。port-allocator.ts 用两级策略解决首选稳定复用resolveStablePort() 先读 workspaceState 里保存的上次端口extension.ts 中的LAST_PORT_KEY试探绑定确认它仍空闲就直接复用兜底交给操作系统没有缓存或缓存被占用时pickFreePort() 用标准手法——把临时服务器绑定到端口 0让 OS 现场分配一个空闲端口后读出。配置里手动钉住的端口会被原样尊重normalizeConfiguredPort()还会把越界值如 80、65536宽容地视为自动分配而非报错。对应的 port-allocator.test.ts 覆盖了四条路径钉住的端口原样返回、空闲的缓存端口被复用、缓存端口被占用时换新端口、无缓存时全新分配。状态保持状态机、Webview 与 localStorage 的三层配合状态保持在这里横跨三个层面各由不同机制负责层面机制位置进程状态stopped/starting/ready/exited/failed五态状态机进程退出自动流转server-manager.ts侧边栏 UI 状态就绪后 iframe 指向本地服务器失败时渲染状态页 Retry 按钮sidebar.ts浏览器级状态复用端口 → iframe 源稳定 → localStorage 跨窗口重载存活extension.ts侧边栏本身是一个 Webview只有两种形态iframe 指向本地服务器或状态/错误页。iframe 带沙箱属性CSP 的frame-src只放行 127.0.0.1 与 localhost并开了allow-downloads让仪表盘的 CSV 导出能正常下载。四个内置命令则与状态流转一一对应声明见 package.jsonClaude Usage: Open Dashboard启动或聚焦服务器已是ready时直接刷新不重复派生Claude Usage: Restart Server先等待进行中的启动落定再杀旧进程重启避免杀掉半路进程留下孤儿Claude Usage: Rescan Transcripts重载 iframe 触发增量扫描Claude Usage: Show Logs打开输出通道可看到 Python 路径、安装模式、完整派生命令与 stdout/stderr——排障第一入口。故障兜底启动失败时会发生什么失败路径同样被精心设计进程在就绪前提前退出、或 20 秒内未响应较默认 10 秒特意放宽——首次启动要建库、回填历史会话主题冷启动可能偏慢状态转failed进程被dispose()清理侧边栏随即显示错误 Retry / Show Logs按钮弹窗也给出同款选项——用户无需去命令面板里翻找ServerManager整体回到stopped干净状态保证任何失败之后都能原样重试。小结claude-usage VS Code 扩展把扩展里托管本地服务器这件事中最容易翻车的部分做成了三层保险五级安装模式判定保证找得到程序稳定复用 OS 分配两级端口策略保住本地状态五态状态机让进程生命周期随时可控。下次点击量表图标时这一整套流程会在几秒内静默完成——而你的用量数据从未离开过这台电脑 延伸阅读install-mode.test.ts安装模式优先级单测、server-manager.test.ts用假进程驱动状态机的单元测试、python-locator.test.ts。【免费下载链接】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.项目地址: https://gitcode.com/gh_mirrors/cl/claude-usage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考