# Codex 用量挂件

在「Codex 增强 → 常用增强 → 挂件与桌宠」打开「Codex 用量挂件」并保存。Codex 应通过包含此功能的 Codex++ 启动器启动；已经运行的旧版启动器需要更新后重新启动。运行中的新版支持通过设置同步开启和关闭，无需重新安装插件。

挂件以 Codex 的本机会话 token、任务状态和订阅额度快照为主要数据。鲸鱼是默认角色，可以换成自己的图片；API 余额是可选功能，与 Codex 订阅额度分别展示。

## 使用

- 点击鲸鱼打开原版轮廓的用量气泡；拖动鲸鱼改变位置，支持鼠标和触摸。按压时底部固定并 Q 弹回弹，贴左时角色和气泡镜像，文字保持正向。
- 悬停鲸鱼点击 ☰ 菜单（触屏常显），或右键鲸鱼，打开原版菜单。隐藏菜单按钮后仍可右键或长按约 1.5 秒打开。
- 默认角色使用参考项目的原始 `DSniang1.png` 鲸鱼娘，保留原图像素与透明通道。自定义角色仅接受有大小限制的 PNG、JPEG、WebP、GIF 图片，保存在当前 Codex 界面的本地存储中。
- 「音效与提示 → 全局设置」分别配置按压、松开、每轮完成、提问和授权事件。每个事件可单独静音、调整音量、试听和设置泡泡；编辑后点击保存生效，取消会还原。
- 「声音总开关与按压音效」控制整个挂件的声音。总开关关闭时，完成、提问、授权及试听都不会出声；先勾选总开关，再选择对应事件音效、试听并保存。升级会保留旧版的明确静音选择。
- 内置原版「小黄鸭」「音效1」按压/松开音，以及经验球、A 两种完成音；可导入音频、查看波形并裁剪，组装自定义音效组。
- 「按压泡泡设置」支持点击序列、并列加权、随机文字/图片、模块化排版、字体与渐变样式、模块库。点鲸鱼或气泡推进序列，支持鼠标拖放与触摸长按排序。
- 「资源管理」集中管理角色、泡泡图片、音频片段与音效组。内置 petpet、money1 动图可直接用于泡泡，自定义角色支持裁剪与翻转。
- 「吸附与翻转」可配置四边的像素或比例吸附区域、翻转线和角落组合；可关闭吸附自由摆放，并独立设置滚动条避让。
- 关闭挂件或增强总开关后停止查询并移除界面，已保存的角色、位置与提醒设置保留。

## 统计口径

| 内容 | 数据来源与含义 |
| --- | --- |
| 账户余额 | 当前 Codex++ 供应商提供的余额接口；复用该供应商已保存的凭据，不在挂件中输入密钥 |
| 账户今日观测消费 | 本机当天有效余额样本的下降额累计；首次样本建立基准，充值不冲减已记录消费 |
| 当前会话今日 / 累计 token | 当前本机会话 JSONL 中的累计 usage 差值；重复事件不重复计数 |
| 全机用量与模型费用 | 全机本地会话按日期、模型和轮次汇总；费用仅按用户填写的单价估算，不是账户账单 |
| 最近一轮状态 | 会话日志及当前窗口任务事件中的开始、完成、失败和取消状态 |
| 订阅额度 | 日志中实际观测到的额度窗口快照；显示记录时间，超过重置时间标为已过期；没有快照时不推算剩余额度 |

「今日」使用本机时区。账户余额覆盖共享该账户的调用；它与当前会话 token 是不同口径。余额变化无法完整拆分同一观测区间内同时发生的充值和扣费，也不会补回挂件关闭期间的完整账单。每日预算提醒基于今日观测消费，不会自动阻止模型调用。

官方登录或没有余额接口的供应商可以直接使用角色、本地用量和已观测的订阅额度；未知余额显示为不可查询。查询失败时保留最近成功余额并标为旧数据，旧数据不用于触发新的金额提醒。

首次读取大日志时按预算逐步追平；尚未读完或没有有效 usage 时显示未观测，避免把部分数据误认为完整统计。完成提醒只针对挂件开启期间观察到的运行轮次，切换到历史会话不会重新播放完成提示。

「用量记录」提供今日、近 7 天、更多消费记录、模型占比、日期/模型搜索和逐轮明细。全机索引按预算增量读取，明细保留 90 天、日聚合保留 365 天，累计按模型聚合继续保留。已经归档的记录不冒充仍有完整逐轮明细。

账户账本把余额下降和到账增加分别记录；余额增加后标记待核对。余额校正按当天累计到账金额与非调用扣减修正，保存时检查 revision，避免多窗口覆盖较新的观测。

## API 供应商余额（可选）

开启挂件后，管理工具中可展开「API 余额（可选）」：

- **仅显示 Codex 用量**：不请求余额接口，适合 Codex 官方订阅或只需要 token 统计。
- **自动识别已支持的接口**：当前包含 DeepSeek 官方余额适配；未识别的供应商显示未配置，不猜测私人账单路径。
- **自定义供应商余额接口**：根据当前供应商文档填写同域 GET 接口路径、余额字段路径、币种和倍率。无需再次填写密钥。

例如供应商文档明确说明 `/account/balance` 返回 `{"data":{"balance":12345}}`，数值单位为美分，则路径填 `/account/balance`，字段填 `data.balance`，币种 `USD`，倍率 `0.01`，显示余额为 123.45 USD。此示例不是任何供应商的默认协议。

自定义路径仅用于当前供应商的同源 HTTPS 地址，禁止完整外部网址、查询参数、片段和重定向。支持 `data.accounts[0].balance` 这样的数组字段。接口字段不存在或不是有效金额时返回不可用，不能按零记账。更换凭据、计量字段、币种或倍率会建立新的余额基准。

原版挂件的模型菜单另提供多供应商模板、余额或订阅窗口、探活、自定义 HTTP、用户单价与资源包额度。选择 Codex++ 已保存的供应商配置来复用凭据，挂件不重新保存另一份 API Key。未提供公开余额接口的供应商仍可使用本机 token 和自定义费用估算。峰谷模块保留原版配置与显示，只为具有对应价目/时段的供应商使用，不把其他厂商价格套给 Codex。

## 实现与数据

- 挂件界面：上游完整引擎 `assets/inject/upstream/whale-widget/full-widget.js`；适配产物由 `scripts/assemble-whale-runtime.mjs` 生成。`96-whale-compat.js` 提供词法宿主，`97-whale-widget.js` 管理开关与生命周期。
- 持久开关：`codexAppWhaleWidgetEnabled`，默认 `false`，同时受 `enhancementsEnabled` 控制。
- 内部桥接：`/whale/balance`、`/whale/session`、`/whale/history` 和 `/whale/full`，未加入第三方拓展的路由白名单。
- 余额账本：Codex++ 设置目录内的 `whale-balance.sqlite3`，按凭据指纹及币种隔离，金额以八位定点数累计。
- 角色/泡泡图库、音频和挂件设置：本机 SQLite；交互位置及事件去重标记使用当前 Codex 界面的 localStorage，不上传服务器。
- 凭据留在 Rust 后端；返回界面的余额数据不包含密钥、认证内容或供应商配置原文。

## 参考来源

功能参考 [MeteorNOX/DeepSeek-Balance-Whale-Widget](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget)。本实现适配 Codex++ 的 Rust 后端与内置注入层，没有依赖 DSH 服务或另外启动 Electron 挂件进程。

完整界面引擎、默认角色、气泡、音效和动图来自固定版本 `fce34e3abd1fe8b616e287b9864305c7f0be81a0`。原始源码、素材以及上游 LICENSE / PROVENANCE 保存在 `assets/inject/upstream/whale-widget/`；美术、音频与动图不属于其 MIT 代码许可范围，原始声明随文件保留，不重新声明为本项目原创或 AGPL 素材。

启动器将内置素材嵌入，离线可用，不依赖 DSH 服务或单独的 Electron 挂件。关闭或重复注入时清理节点、事件监听、计时器、观察器和音频上下文。功能核对见 [完整功能验收](whale-parity.md)。

内置音频直接从嵌入字节解码，不依赖 `fetch(data:)`，兼容宿主的 `connect-src` 限制。挂件自己的勾选框与滑块具有独立样式，避免宿主表单样式使声音开关和轨道不可见。