AI 用量监控开发文档

这个项目是什么

「AI 用量监控」是一个 Chrome / Edge（Manifest V3）侧边栏浏览器插件，把多家 AI 厂商的用量、余额、订阅窗口额度汇到一屏里实时查看：CommandCode、OpenCode Go、OpenRouter、DeepSeek、Kimi (Moonshot)、硅基流动、MiniMax 编码套餐，同一厂商可加多个账号，每账号一张统计卡。除用量外，各厂商卡片下方还会展示该厂商的模型价格/免费额度信息（最便宜 3 个模型 + 免费模型限制），帮用户做省钱选型。当前版本 v2.6.0。

设计原则是「只用官方接口、纯本地运行」：直接镜像官方 CLI/官方 API 端点取数，数据只存本机 chrome.storage.local，无遥测、无第三方上报、无更新检查。

技术栈与架构

纯原生 JavaScript（Manifest V3），零构建——没有 package.json、没有打包器，改完文件 reload 扩展即生效。
单一 Service Worker（worker.js）+ 侧边栏页面（sidepanel.html）两层结构，用 chrome.alarms 做定时刷新、chrome.storage.local 存账号与配置、chrome.sidePanel 打开侧边栏。

数据流：worker.js 后台按 alarm 周期拉取各厂商官方接口 → 结果归一化后写入 storage → 侧边栏读 storage 渲染。用户填的 API Key 也只存在本机 storage。

仓库结构

├── manifest.json     # MV3 清单：权限、host_permissions、sidePanel、图标
├── worker.js         # Service worker：定时刷新、拉取各厂商用量
├── sidepanel.html    # 侧边栏结构
├── sidepanel.js      # 侧边栏逻辑（账号管理、渲染、备份恢复）
├── sidepanel.css     # 侧边栏样式
├── providers.js      # 多厂商适配层：每个厂商一个适配器
├── models.js         # 模型价格/免费额度信息
├── lib.js            # 公共工具（ccGet 请求、ccStripSlash 等）
├── icons/            # 16/32/48/128 图标
├── CHANGELOG.md      # 更新日志
└── README.md

厂商适配层（providers.js）

每个厂商是一个适配器，键名即厂商 id（commandcode / opencodego / openrouter / deepseek / kimi / siliconflow / minimax 一类，以代码为准），统一返回归一化结构：

{ bigLabel, bigValue, percent|null, windows:[{label,percent,resetAt}], stats:[{label,value}], note }

bigLabel / bigValue：卡片主数字（如「每月窗口剩余 62%」「总余额 ¥12.34」）。
percent：0–100 的用量百分比，工具栏徽标显示最差账号的数值；没有明确限额的厂商传 null。
windows：限额窗口列表（如 OpenCode Go 的 5 小时/每周/每月窗口，带重置时间戳）。
stats：附加统计行（如 DeepSeek 的总余额/赠送/充值三段）。
适配器里用 ccGet(base, path, key) 发请求，noBase: true 表示厂商无自定义 API 地址。

新增一个厂商的步骤：在 providers.js 的 CC_REF 里加一个适配器（label、hint 提示 Key 怎么拿、fetch 归一化数据），再在 models.js 里补该厂商的价格/免费额度信息即可，侧边栏的账号表单与卡片是数据驱动的，不用改 UI 代码。

配置与存储

插件没有服务端配置项，所有配置在侧边栏「设置」里完成，落在 chrome.storage.local：

配置	说明
账号列表	每条含厂商 id、API Key、备注（显示尾号）、可选自定义 API 地址（CommandCode 等支持）
自动刷新间隔	1–120 分钟任选，到点后台静默更新
`ccModels`	唯一的持久缓存：厂商模型价目快照，24 小时刷新

manifest.json 权限：storage、alarms、sidePanel；host_permissions 覆盖厂商官方 API 域名与 http/https 通配（请求全部由 Service Worker 发出，绕开页面 CORS）。

本地开发

没有构建步骤：

下载仓库目录（或 Releases 的 zip 解压）。
chrome://extensions（Edge 为 edge://extensions）打开右上角开发者模式。
「加载已解压的扩展程序」选中本目录（manifest.json 在根）。
改代码后点该扩展的 🔄 重新加载，再关掉重开侧边栏——侧边栏不会热更新，不重开会继续跑旧脚本。

调试：Service Worker 页可看后台日志；侧边栏右键「检查」打开 DevTools。注意 sidepanel.js 与 worker.js 之间靠 storage + chrome.runtime 消息通信，改 storage 键名要两边同步。

二次开发要点

Key 只存本机：任何改动都不要引入第三方上报，这是这个插件的立身之本；备份导出的 JSON 含全部 Key，提示用户妥善保管。
厂商接口漂移：厂商 CLI/API 常改字段，适配器里对缺失字段一律降级（percent 传 null、显示 --），不要让一个厂商挂掉拖垮整面板。
价格快照要标来源：DeepSeek/Kimi/硅基流动用官方价目快照、OpenRouter 走实时 API，界面上要标注来源与日期，避免误导。
合规边界：只做只读统计，不代理、不破解；免费档限制（如 OpenCode 免费模型仅限客户端内使用）在界面上直接说明白。
sidepanel.js 是最大的单文件（约 30KB），改动账号表单逻辑时留意 v2.4.1 修过的坑：API 地址行显隐层级写错会导致整个「添加账号」表单被误隐藏，现在 API 地址行是独立容器按 id 显隐。

AI 用量监控 开发文档