Codex-v0.4(fixed)

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-10-05 20:02:13 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：原有附件字节未变。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

Codex-v0.4(fixed)

For-Codex 修复发行版。发布标签精确为 codex-v0.4.0(fixed)；程序内部版本仍为 0.4.1，构建标识为 auto-probe-fixed-20261005。此前 codex-v0.4.0 发布保持不变。

这是 MeteorNOX 所有的 DeepSeek-Balance-Whale-Widget 独立 For-Codex 适配线，由协作者 Yang-huai406 维护。保留 1llysviel 的 macOS PR #128 及已有署名、许可；不替代 DSH 主线 Latest。

本次 fixed 解决什么

• 多提供商与 profile/project 局部配置按表递归合并，未知 provider 明确报错；命名连接绑定来源、地址和认证，防止沿用另一服务的 URL/key。
• 已保存配置处于自动模式时，普通用户直接点击“重新检测接口”。可信协议直接使用；编辑过的草稿仍须保存，重新检测不会将显式协议切换为自动模式。完整候选显示币种、单位和范围假设，并提供“确认并使用”，不必先编辑 JSON。
• 确认接受绑定本次来源的一次性预览凭据，五分钟过期；更改来源、重新预览、关闭重开或迟到响应不能复用旧确认。预览不保存、不记账，也不顺带保存未提交的模型价格。
• 13 个来源注册项包含双请求账单、单位元数据与显式管理接口；不是 13 个品牌，不拿普通推理 key 盲探管理接口。有界探测、命中缓存、单位复核及限流退避减少无效请求。
• 正确区分 NewAPI 原始 quota、占位累计量与兼容账单不限额哨兵；不把巨额 key 哨兵当账户资金，不把未知变成 0。协议/单位/计数器变化重建基准，不猜测重算历史。
• 保留独立 GET/POST JSON、专用环境变量认证及自定义字段/单位映射。概览与默认气泡使用简短范围标题，完整解释保留在提示中。

旧版账户新增消耗去重、任务/token 提示、订阅窗口、角色音效、位置记忆、本地工坊和汇率继续保留。部分 issue 的修复范围及未完成项见 状态表，不能全部标为解决。

使用与升级

安装包：Codex-v0.4(fixed).zip；源码包：Codex-v0.4(fixed)-source.zip。配套 SHA-256 与 JSON 清单用于核验成品，不包含 Electron 离线运行时。

Windows 需要支持插件注册的 Codex、Node.js 24+（含 npm）及首次下载 Electron 的网络。完整解压后运行 安装插件.cmd，保存本次私有回执，再在 API 设置中重新检测。已有暂停意图会保留。安装、成功检查、日常操作和高级示例见完整 README。

有候选却没有确认按钮，通常缺少单位或范围依据，应按服务商说明自定义，或选“不查询余额”。官方 OpenAI 普通 key 没有本插件已验证的余额接口；ChatGPT 订阅使用单独视图。自动检测不承诺覆盖任意服务商。

验证记录与边界

已验证的当前运行构建	结果
自动测试	482 项通过
独立隐私门禁	9 项通过
真实 Electron	6 组流程、7 个布局样本、8 张截图，渲染错误 0

Electron 覆盖原生配额自动验证、普通候选直接确认并保存重载、独立认证 POST、连接方式/单位变化、迟到结果、切换删除和金额语义布局。使用隔离合成服务，不代表全部真实站点或所有设备实测。

本轮 ZIP 隐私清理、解压核验、文件范围及哈希以 release-manifest.json、verification-report.json 为准，成品通过隐私检查、完整性校验和中文空格路径安装预检。Mac 实机、其它硬件、多屏与长期稳定性仍需对应环境验证。

本地账本不是服务商完整流水，无法仅靠余额拆分并发消费、充值和退款；跨日未观测区间归再次观测日，历史错误口径不自动重算。见 已知限制 和 fixed 自动检测说明。

隐私与回滚

公开包排除个人配置、凭据、账本、会话、原始日志、截图录屏、私有回执、缓存及 Git 历史。每位接收者安装时生成自己的 installation.json 和 recovery-scripts/rollback-package.ps1；先用本次回执 -Receipt ... -CheckOnly 核对恢复目标，再执行回滚。前后可能都是 0.4.1，还须核对备份构建标识。

回滚恢复程序和启动配置，保留最新设置、素材和账本；旧程序可能不理解新连接，恢复后核对实际来源。不要使用别人的回执，也不要删除账本代替回滚。Mac 入口只安装桌面组件/LaunchAgent，不自动注册技能/MCP，见 macOS 文档。

发行标识

目标分支为 For-Codex，标签 codex-v0.4.0(fixed)，标题 Codex-v0.4(fixed)。本发行版设置 makeLatest: false，保留 DSH 主线 Latest 与旧发布。

下载文件名与校验

GitHub 会自动将附件文件名中的括号替换为点号。安装包在 Assets 中的实际文件名为 Codex-v0.4.fixed.zip，源码包为 Codex-v0.4.fixed.-source.zip；产品名称仍为 Codex-v0.4(fixed)，标签仍为 codex-v0.4.0(fixed)。文件内容与本地发行包一致。

直接下载附件后，使用 SHA256SUMS.downloads.txt 按实际下载名称核验；原 SHA256SUMS.txt 和独立 .sha256 保留构建时含括号的原文件名。清单中的 published: false 是上传前构建快照，实际发布状态以本页为准。

Codex-v0.4

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-10-05 03:47:35 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：原有附件字节未变。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

Codex-v0.4 — API 余额小鲸鱼

For-Codex v0.4.0 发布说明，标签 codex-v0.4.0。

程序版本为 0.4.0，内部插件标识保持 api-balance-whale，发布标签为 codex-v0.4.0。For-Codex 是独立适配线，不替代 DSH 主线 Latest。上游作者与仓库所有者为 MeteorNOX，Codex 适配协作者为 Yang-huai406。

这版最重要的变化

不配置模型单价，也能看到“账户新增消耗”。 有效余额/累计用量采样发现新增扣费后，按账户、币种和计量上下文累计为独立通知；它不归属某个成功或失败对话。实际呈现后确认，重复采样、多个任务结束与确认重试不重复分配同笔增量。

第一次有效样本只建立通知基准，不追报旧历史。关闭或隐藏提示期间合并新增累计，重新启用后显示；后台最多一个未确认批次加一个待显示累计，不积成无限长队列。余额后台通常约 60 秒采样，任务起止及主动刷新也可查询；服务商入账延迟可能令通知稍后出现。

单轮继续保留 token 和状态，有完整模型价格时显示估算。失败或取消不等于免费，账户通知本身不播放任务成功音。内部高精度累计、展示两位小数，小额正值另有提示。

连续点击角色不再在回弹间隙误点背后。 人物命中、输入路由和原生窗口区域共享有限稳定轮廓；取消、失焦、移远、换角色或模式切换会释放。真正透明区仍穿透，过期原生按键样本不能覆盖刚完成的松手。

累计修复

• #181：筛选 Codex 账户额度，5 小时/周窗口分别合并，避免其他额度类型或部分快照覆盖。
• #172/#195：气泡队列与异步场景所有权统一，失败释放、旧回调失效、后续通知继续显示。
• #159：共用椭圆安全区排版，长文字、图片和金额不靠裁剪来适配。
• #88/#97：严格区分缺失与损坏配置，合并字段、顺序保存并显式报告失败。
• #79：修复共用拖动取消分支；不宣称 Android 触屏问题全部解决。
• #108：只修屏名/候选名保留，未实现共享台词池；#135 修音频生命周期，未做 Mac 睡眠实机验收。
• 保留位置记忆、历史账户 #163、气泡截止时间 #188、B 版分页、角色音效、本地工坊、汇率和适用范围内的峰谷提示。

完整分类见 issue 状态表。#177 全局空白点击关闭继续主动不采用；#118 输入框/侧栏避让未实现；#121 长期偶发显示仍需跨设备观察。

验证结果

当前 v0.4 检查	结果
本次发布源码自动测试	重新运行 341 项，全部通过
本次独立隐私拒绝门禁	重新运行 9 项，全部通过
先前同一运行实现的 Windows 边缘连击	6 组共 120 次真实原生输入，零误点宿主；本次未重跑
先前透明区对照	18 次正常穿透；本次未重跑
先前同一运行实现的账户通知端到端	5 组通过：无单价并行、去重、丢失确认后刷新、提示开关、模式切换；本次未重跑

连击矩阵涉及 0.6/1.2/2.0 大小、左右翻转和 20/50/100ms 间隔的六种组合，不宣称所有组合或所有硬件均测试。测试仅使用专用无害宿主和隔离数据。

较早的 52 个通用气泡布局场景及位置重启测试作为相关实现的基线证据，本版不计为新重跑。成品哈希、版本与解压核验见发行目录的 release-manifest.json、verification-report.json。自动检查不能替代用户验收。

安装与回滚

• Codex-v0.4.zip：插件安装包。
• Codex-v0.4-source.zip：源码、测试和发布材料。
• 对应 .sha256 及 JSON 清单：完整性与验证结果。

Windows 完整解压后运行 安装插件.cmd。需要支持插件的 Codex、Node.js 24+（含 npm）与首次下载 Electron 的网络；不是离线 EXE。回滚运行 回滚本次安装.cmd，使用安装私有回执恢复旧程序并保留新增设置、素材和账本。详见 README。

保留 1llysviel 的 macOS PR #128 实现与署名；Mac 安装入口和未验证范围见 平台文档。

仍需留意

当前账本累加正向观测消费，退款导致的累计值回退或余额回升不会冲减旧累计；余额模式也无法分离同时发生的充值/退款与消费。它不是退款后净额账本。跨日观测间隔归恢复日，无法精确分摊各天。

Mac、其他鼠标/触控设备、多屏、高负载和长期稳定性仍待实测。公开包排除个人配置、凭据、账本、聊天、原始日志、截图录屏与私有回执。完整限制和操作见 已知问题 与 验收清单。

本版发布至 For-Codex，标签为 codex-v0.4.0，保留旧发布与 DSH 主线 Latest。

下载与完整性

下载插件包 · 下载源码包

源码提交：c86b055e8f24473ca76324d6e67145d65c596c41。附件与此提交逐文件核对；安装包不包含历史归档、私有配置或运行数据。附件报告的 published: false 描述本地生成时点，不表示当前 Release 状态。

文件	SHA-256
Codex-v0.4.zip	f4c3b58c39b7d868d75d391966c67922716b9bb88ca040bbe2ba12d705c61638
Codex-v0.4-source.zip	f42828664e595591a4b14e03c694c4bcc1f4adf3a6a2ed02fbaf8e2a01b5430c

Codex-v0.3(fixed)

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-09-30 02:07:24 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：原有附件字节未变。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

API 余额小鲸鱼 v0.3(fixed)

For-Codex 分支发布，标签 codex-v0.3.0-fixed.2。 本次按维护者授权发布；内部构建为 0.3.0+codex.20260929173027。协作者 Yang-huai406 维护 Codex 适配，仓库所有者仍为 MeteorNOX。

修复内容

• 气泡收起不再提前被 Windows 原生窗口区域裁切；文字、主泡泡及小尾泡按完整动画淡出。快速关开不受旧结束回调影响。
• 鼠标从人物经过透明缝隙移向菜单按钮时，按钮保持可达；透明范围只保留悬停显示，仍让底层软件接收点击。
• 保留条件式窗口层级纠正、Ctrl+Alt+Shift+F10 静默诊断，以及 Windows 鼠标移动不转发和软件合成兼容措施。
• 明确失败或意外中断也显示中性消耗提示；不把未知/待记账金额当零，不播放成功音效，重试中不提前结算。

关于 Issue #177

点击组件外空白关闭菜单、人物气泡和账户卡片 是合理的便利性建议。本版最终撤回新增的全局空白点击关闭：挂件覆盖其他软件，宿主正常点击可能误清尚未阅读的人物、任务和消耗提示；“二级菜单”的范围也容易造成理解差异。保持点击穿透的同时监听外部点击，还会增加跨平台事件处理和排查成本。

当前沿用已有控件内关闭、人物点击和提示超时规则。这是交互取舍，不表示技术不可实现，不代表 Issue 已被关闭。详见 决定说明。

保留功能与来源

B 版概览/用量/设置、API/订阅模式、角色和气泡、音效与手感、本地创意工坊、桌面/跟随切换、余额与 token 统计、官方端点适用时的 DeepSeek 峰谷均保留。

保留 macOS PR #128 的平台代码、来源和贡献者署名；不以旧整包覆盖当前修复。

验证和限制

238 项单元测试通过；16 次 Windows 原生区域采样覆盖关闭与快速重开，慢/快悬停及原生点击穿透、当前 B 版 Electron 界面审计通过。最新成品解压验证和哈希见随附 verification-report.json、release-manifest.json。

长期偶发显示稳定性、其他设备、Mac 实机及真实订阅账号端到端仍待验证；发布授权不等于这些场景已全部验收。专项置顶隔离窗口测试用于动画裁剪，不证明日常跟随层级始终正确。旧版布局脚本的既有断言不适配 B 版，具体范围见 验证记录。

安装附件

• api-balance-whale-v0.3-fixed.zip：完整解压后安装的插件包。
• api-balance-whale-v0.3-fixed-source.zip：源码、测试、README 和 GitHub 准备材料。
• 两份 .sha256、release-manifest.json、verification-report.json：校验及验证摘要。

Windows 完整解压后运行“安装插件.cmd”；需要 Node.js 24+（含 npm）、支持插件的 Codex 及首次下载 Electron 的网络。此包不是包含运行时的离线 EXE。Mac 安装范围、Swift 工具与未验证限制见 平台说明。安装和按本次私有回执回滚见 README。

公开包不包含个人凭据、配置、账本、日志、截图、录屏、回滚回执或 Git 历史。公开署名、第三方许可和兼容来源保留。本次使用新标签 codex-v0.3.0-fixed.2，不覆盖既有 codex-v0.3.0-fixed tag，不变更主线 Latest。

对应提交：5a36d6442d272cd7fea255206f2abcd697a87563。完整安装包、源码包及校验材料共 6 个附件。

GitHub 附件采用连字符文件名，避免平台改写括号；tag 内脚本的本地输出仍使用 (fixed)。两份 ZIP 内容不变，清单以 sourceBuildName 记录对应关系，校验文件使用实际下载名称。

Codex-v0.3

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-09-29 03:29:34 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：原有附件字节未变。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

API 余额小鲸鱼 · Codex v0.3.0

For-Codex 分支发布，标签 codex-v0.3.0-fixed。由仓库协作者 Yang-huai406 发布，仓库所有者仍为 MeteorNOX。

维护者：Yang-huai406。保留上游版权与 macOS PR #128 的代码、链接和贡献者署名。

本版内容

• B 版“概览 / 用量 / 设置”分页，保留角色、素材、气泡、音效、账本、预警、预算和高级 API 设置。
• 顶部切换 API 余额 / Codex 订阅，保留菜单及当前页，不改变登录或连接配置。
• 订阅模式报告本轮 token，分别显示 5 小时与每周额度快照、重置时间和过期状态；无快照时显示未观测。
• 跟随 Codex / 独立桌面模式，默认右下角，位置记忆与重置。
• 三种按压手感、原创合成短音、独立事件音量；本地 JSON 创意工坊导入、预览、导出及失败回滚。
• DeepSeek 峰谷仅对识别出的官方 API 端点展示。

用户确认的光标修复

Windows 透明挂件不再向 Chromium 转发穿透区域的鼠标移动，使用独立的原生位置采样处理悬停；避免挂件参与宿主光标的处理。用户已确认本机修复生效，并授权继续发布。Mac 鼠标路径保持原状。

显示与输入修复

分离监督器心跳延迟与窗口隐藏；处理模式切换、旧坐标写回、加载竞争、销毁后 IPC 和缺失素材。Windows 原生区域排除透明空白，dialog/mask 只在实际卡片内接收鼠标。Windows 挂件默认软件合成，作为透明表面偶发不显示的兼容措施，不改变 Codex 本体，不增加周期性重启或重绘。

验证与限制

当前运行代码通过 223 项自动测试、真实 Electron 界面回归、16 次模式切换及不抬高窗口的 12 次实际屏幕像素采样。详见 验证记录。

本机光标修复已经用户确认；其他设备及长期显示稳定性仍需验证，不作全平台根治保证。 Mac 实机和真实订阅账号端到端验证尚未完成。官方额度百分比不能换算成固定剩余 token。本地工坊不是在线市场；桌面模式不含 CC Switch 路由或壁纸层嵌入。

附件

• api-balance-whale-v0.3.0.zip：可解压安装的插件包。
• api-balance-whale-v0.3.0-source.zip：源码、测试和 GitHub 文档材料。
• 对应 .sha256、release-manifest.json：校验值、内容清单、候选状态。

Windows 完整解压后双击“安装插件.cmd”。需要 Codex、Node.js 24+（含 npm）与可联网下载 Electron 的环境；这不是包含运行时的离线 EXE。Mac 安装范围见 平台说明。安装与回滚见 README。

展示版本 v0.3.0；保留当前已测试的内部构建号，具体值见清单。本次使用独立标签 codex-v0.3.0-fixed，不覆盖已用于主线的 v0.3.0 标签，也不替换主线 Latest 标记。

Codex-v0.2(fixed)

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-09-28 19:26:12 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：api-balance-whale-v0.2-fixed.zip、api-balance-whale-v0.2-fixed.zip.sha256、release-manifest.json。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

面向 Windows Codex 桌面应用，不是主分支的 DSH 网页插件。内部版本 0.2.0，tag v0.2.0-fixed，来源分支 For-Codex。

更新内容

• API 设置默认脱敏，未编辑保存保留原连接和模型价格。
• 汇率说明通过刷新右侧灰色感叹号点击展开，支持外部点击和 Esc 收起。
• 运行中取消仍报告中性消耗，不说“挤不进去...”，不播放成功音；金额未确认显示待记账/未知与 token。
• 只有指定拥挤错误造成最终失败时使用“挤不进去...”，抑制重试期间的过时提示。
• 修复最小化/还原、模态窗口恢复和越界锚点；追加显式显示及返回 Codex 的恢复，托盘新增“恢复显示小鲸鱼”。
• 提供依赖、版本检查和带本机回执的安装/回滚，分享包不含个人运行数据。

下载和安装

下载 api-balance-whale-v0.2-fixed.zip，解压后进入 api-balance-whale，双击“安装插件.cmd”。

需要 Windows x64、Codex、含 npm 的 Node.js 24+；首次安装 Electron 44.3.0 需要联网。安装后新建 Codex 聊天。回滚使用“回滚本次安装.cmd”和本机安装回执，保留最新数据。

附件 .sha256 用于校验下载，release-manifest.json 列出 ZIP 内文件哈希。GitHub 自动提供的 Source code 包属于完整分支源码，含后续平台归档；普通用户应下载上面的安装 ZIP。

验证

• 179 项自动测试通过。
• 本次窗口回归：100 次最小化/还原、50 次原生另存为打开/取消、3 次显式显示恢复、5 次返回宿主恢复；均核对实际屏幕像素。
• 既有 UI 基线 14 项通过；安装新恢复代码后，用户确认挂件重新显示。

未宣称覆盖全部显卡、多屏/DPI或保存成功业务流程。发现偶发不显示时可用托盘“恢复显示小鲸鱼”，并提供脱敏复现信息。API 观测金额不是服务商逐请求最终账单，ChatGPT 订阅额度不属于本插件余额。

协作和范围

由项目协作者 Yang-huai406 上传，仓库所属账号和上游作者仍为 MeteorNOX。保留 1llysviel 的 macOS 贡献及完整历史；0.2.4/macOS 文件归档供后续整合，不属于本次 Windows 安装包。

代码沿用 MIT；图片、动图和音频按上游 as-is 条款随挂件分发，不扩大素材再许可。本 Release 不设为整个仓库的 Latest，不变更 main 或既有 Release。

Codex v0.2.4（新增 macOS 支持）

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-09-22 18:46:20 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：api-balance-whale-0.2.4-codex.zip。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

api-balance-whale 0.2.4（Codex 桌面版 · 新增 macOS 支持）

跟着 Codex 桌面应用走的小鲸鱼：显示当前 API 余额、今日已观测用量、每轮消耗，没有独立网页、没有本地网页端口。本版是 DSH 网页版 dsh-whale-widget 的 Codex 特化分支（For-Codex）。

⚠️ 与主分支用途不同：这是 Codex 桌面插件，不能用 dsh plugin … add 装进 DSH 网页；主分支的 DSH 网页插件也不能在 Codex 里运行。

本版主题：把 For-Codex 从 Windows 专用扩展到 Windows + macOS（合并 PR #128），并统一版本号为 0.2.4。

下载

附件	说明	SHA-256
api-balance-whale-0.2.4-codex.zip	解压即用，顶层目录已是 api-balance-whale/，内含 SHA256SUMS.txt（逐文件校验清单）	36a3d953066a042485d3ca2124c0e0cbdefeab12f9f291d04d0f5ec70961c0c4

校验：

Get-FileHash .\api-balance-whale-0.2.4-codex.zip -Algorithm SHA256
# 期望 36a3d953066a042485d3ca2124c0e0cbdefeab12f9f291d04d0f5ec70961c0c4

安装

Windows 10/11 x64

1. 解压到 %USERPROFILE%\plugins\api-balance-whale（不要多套一层同名目录）；
2. node scripts\install-desktop.mjs（首次会联网下载 Electron 44.3.0）；
3. node scripts\install-follow.ps1（编译 GUI 启动器并注册计划任务 Codex API Balance Whale）；
4. 打开或重开 Codex，小鲸鱼自动出现。快捷键 Ctrl+Alt+W。

macOS（Apple Silicon / Intel）

1. 解压到 ~/plugins/api-balance-whale；
2. 双击 安装 Mac 自动跟随.command（等价于 node scripts/install-macos.mjs）。它会优先使用 Homebrew 的 Node/npm，把 Electron 44.3.0 装到 ~/.codex/whale-widget/desktop-runtime，用 xcrun swiftc 本机编译窗口探针并 ad-hoc 签名，然后写入并加载用户级 LaunchAgent；
3. 打开 Mac 版 Codex（应用名显示为 ChatGPT/Codex，bundle id com.openai.codex；可用环境变量 WHALE_CODEX_BUNDLE_ID 覆盖），小鲸鱼自动出现。快捷键 Cmd+Option+W。

停用：Windows 用 停用自动跟随.cmd，macOS 用 停用自动跟随.command（或 npm run uninstall:mac）。两者都只停用自动跟随，保留设置、素材与账本。

逐条步骤、装完必查项与回滚命令见分支内 docs/INSTALL-AND-ROLLBACK-0.2.4.md 与 docs/MACOS.md。

0.2.4 更新内容

• 新增 macOS 支持：Swift 窗口探针（proc_listpids + proc_pidpath 校验可执行文件路径、CGWindowList 读取 layer 0 窗口几何、优先前台 Codex 窗口、过滤过小/不可见/辅助层窗口、PID 扫描缓存 250ms）；Node supervisor 通过本地 Unix socket 回传 hostAlive/hostPid/window/bounds/visible/attached，Codex 最小化时隐藏、恢复时显示、退出后挂件退出而 LaunchAgent 待命；探针异常退出 1.5 秒重启、5 秒无输出强制重建；目录锁 + sessionId 防重复实例；stale socket 检查后清理。
• macOS 浮窗与命令：Electron 使用独立 bundle id com.api-balance-whale.codex.desktop、LSUIElement 隐藏 Dock、透明无边框固定尺寸、floating 层级且跨 Space/全屏可见、acceptFirstMouse 首次点击即生效；macOS 托盘「命令」子菜单与鲸鱼 ☰ 菜单新增命令区（刷新余额 / 查看用量记录 / 查看运行状态 / API 设置 / 停止当前挂件），renderer 未 ready 时进入去重队列。
• macOS 安装与恢复：scripts/install-macos.mjs 优先使用 /opt/homebrew/bin/node、/usr/local/bin/node，避免依赖登录 shell 的 PATH；安装完成前校验 installId 匹配、heartbeat 新鲜、supervisor PID 存活且 platform=darwin，不通过就不报成功；LaunchAgent 用 RunAtLoad/KeepAlive/ThrottleInterval/LimitLoadToSessionType=Aqua 常驻。
• Windows 不受影响：本次 macOS 改动没有触碰任何 *.cmd/*.ps1/*.cs；非 macOS 分支仍使用 type:'toolbar'、screen.screenToDipRect(...)、Control+Alt+W；runtime/process.mjs 的 macOS 逻辑受 process.platform === 'darwin' 保护、runtime/bridge.mjs 的 Unix socket 清理受 process.platform !== 'win32' 保护，Windows 命名管道路径不变。
• 版本号统一为 0.2.4：package.json、package-lock.json、.codex-plugin/plugin.json、runtime/paths.mjs 的 VERSION、desktop/main.cjs 的启动标记 revision。

0.2.0 相对 0.4.0 的四项改动（汇率说明收进灰色 !、失败/暂停取消改中性扣费提示、显示判定自愈、去除服务商痕迹）见 docs/CHANGELOG-0.2.0.md。

致谢

• @1llysviel：本版全部 macOS 适配工作由其提交（PR #128）——宿主识别、自动跟随、常驻恢复、Electron 浮窗、安装流程与菜单命令，并保持了 Windows 路径零改动。感谢。
• @MeteorNOX：上游项目与 dsh-whale-widget 主线的全部基础工作，以及本分支的角色、气泡与音效素材。
• 历史贡献者（按合入顺序）：@ztzpro（#1 改造成标准 DSH 插件包）、@under-the-ocean（#6/#7 自动发布 npm 与 OIDC）、@21253soursweetlemon（#16/#18 gif 降级、锚点位置记忆）、@fangbm（#15/#19/#31/#33/#46 多币种、消耗泡泡、周末谷价、币种感知账本、自动 Release）、@xiaolinnnnnnn（#26 Windows 桌面端重构、#130 win 桌面版 2.0.0）、@Yang-huai406（充值记账修复方案，0.3.1 合并）、@ELFsay（#99 OpenCode Go 订阅额度与多窗口额度）。
• 本分支 0.2.0 → 0.2.4 的合并、版本统一与发布由 @Yang-huai406 维护。

验证情况

• Windows：0.2.0 阶段实测通过 141 项单元与回归测试、Electron 隔离夹具测试与退出压力测试；0.2.4 未在 Windows 真机重跑（版本号与文档改动不影响运行逻辑，macOS 改动受平台条件保护）。详见 docs/VERIFICATION-0.2.4.md。
• macOS（来自 PR #128 作者的实机结果）：node --check 11 个改动文件通过、zsh -n 4 个 .command 通过、xcrun swiftc 编译与 ad-hoc 签名成功且探针返回 hostAlive/hostPid/visible/attached、plutil -lint 通过、launchctl print 显示 running 且 last exit code = 0、node scripts/control.mjs status 返回 ok:true / platform:darwin / followMode:macos-cgwindow-poll、runtime.json 权限 0600。
• 未覆盖：Intel Mac 与 macOS 13/14/15 的安装-升级-卸载矩阵、多显示器与 Spaces/全屏、长时间 CPU 占用、macOS 侧故障注入（SIGKILL / 输出卡死 / launchctl bootout 失败 / socket 损坏 / PID 复用），以及 Windows 侧的动态 smoke test 未在真机重跑。

安全与隐私

• 密钥只从本机 Codex 配置或指定环境变量读取，插件设置只保存密钥环境变量名，不保存密钥；不发送聊天内容；除公开汇率接口与用户配置的 API 外不主动联网。
• macOS 的 ~/.codex/whale-widget/runtime.json 含本地 IPC token，不要上传到 issue、PR 评论或故障报告；Windows 侧同理。
• 安全问题请不要开公开 issue，按 SECURITY.md 私密报告。

说明

• 本 Release 标记在 For-Codex 分支的 codex-v0.2.4 tag 上，与主分支（DSH 网页版）的正式发行互不影响。
• 金额为观测估算，不等于服务商正式账单；今日/历史用量按同一密钥观测，可能包含并行调用的扣费。
• 逐项来源与许可边界见 PROVENANCE.md：代码 MIT；assets/ 美术素材不在 MIT 覆盖范围，随插件 as-is 分发；vendor/smol-toml 为 BSD-3-Clause；Electron 由安装脚本单独下载。

Codex-v0.2.0

素材分发补充（2026-10-05）：来源、许可范围与署名。提供者允许其有权授权的素材随 For-Codex 仓库、安装包和历史版本继续分发，保留署名、可清元数据、不声明为适配者原创、不授予再许可，按 as-is 提供不作担保，收到权利主张时替换或移除。DSH2.png 已确认由提供者自行制作、可分发；个人角色动画使用 EmoteLab 制作。四个 MP3 按维护者确认继续保留，本次没有改动任何附件或标签。

历史版本净化副本，非原始字节保证。 原始发布：2026-09-18 00:04:53 +08:00，发布者 Yang-huai406；原发行。
本页GitHub日期为净化副本创建日期。提交和标签已经映射至净化历史，作者、日期、消息和拓扑保留。原说明、测试记录、旧SHA/下载链接/文件名描述原始版本，不代表本次功能重测。
本版本变化：api-balance-whale-0.2.0-codex.zip。仅清理非渲染PNG元数据及相应校验；像素、运行逻辑不变。
下载使用本页Assets，统一核验 SHA256SUMS.sanitized.txt；新旧摘要见 SANITIZATION.json。原旧校验与报告只在仍匹配时适用，不用原哈希校验已净化附件。
净化范围与提交映射 · 发行时间线。素材分发范围已按提供者回复与维护者确认补充记录，本仓库已于 2026-10-05 经维护者授权公开。

---

跟着 Codex 桌面应用走的小鲸鱼：显示当前 API 余额、今日已观测用量、每轮消耗，没有独立网页、没有本地网页端口。本版是 DSH 网页版 dsh-whale-widget 的 Codex 特化分支（For-Codex） 重新起算的 0.2.0。

⚠️ 与主分支用途不同：这是 Codex 桌面插件，不能用 dsh plugin … add 装进 DSH 网页；主分支的 DSH 网页插件也不能在 Codex 里运行。

下载（也可以丢给Codex让她自己装喵~）

附件	说明	SHA-256
api-balance-whale-0.2.0-codex.zip	解压即用，顶层目录已是 api-balance-whale/，内含 SHA256SUMS.txt	af020ed1cf38145c8d707c49a41575c55b95046692b57ac2df444f6034eb0b87
api-balance-whale-for-codex-branch.zip	与 For-Codex 分支根一致的文件树（不含 .git）	796fa601d0607df50dc255c9cbd4e0ac94db61c23c2a70229fcc755c4276fe59

校验：

Get-FileHash .\api-balance-whale-0.2.0-codex.zip -Algorithm SHA256
# 应等于 af020ed1cf38145c8d707c49a41575c55b95046692b57ac2df444f6034eb0b87

安装

需要 Windows 10/11 x64 与 Node.js 24+：

1. 解压到 %USERPROFILE%\plugins\api-balance-whale（不要多套一层同名目录）；
2. node scripts\install-desktop.mjs（首次会联网下载 Electron 44.3.0）；
3. node scripts\install-follow.ps1（编译 GUI 启动器并注册计划任务 Codex API Balance Whale）；
4. 打开或重开 Codex，小鲸鱼自动出现。

完整步骤、装完必查的四项与回滚命令见分支内的 docs/INSTALL-AND-ROLLBACK-0.2.0.md。

0.2.0 更新内容

很多喵，待统计喵~

逐条细节见 docs/CHANGELOG-0.2.0.md。

保留自上游的能力

角色/拖动/吸附翻转/300 毫秒翻转动画、气泡快照与随机语、音效与音效组、素材管理器、余额预警与今日预算、账本与用量记录、USD/CNY 显示换算（金额一律两位小数）、失败轮次的已观测消耗仍入账。

验证情况

• 单元与回归测试 141 项通过；桌面隔离测试（Electron 真机渲染）与退出压力测试（渲染器真的卡死时仍按期限保存并退出）通过；
• 原生 WindowApi.cs 现场编译并成功探测真实 Codex 窗口；回滚脚本在副本上完成 158/158 文件按哈希恢复的演练；
• 发布包解压往返校验 0 处不匹配，包内文本隐私扫描 0 命中；
• 已知未覆盖：冷启动、断网、多显示器未逐一验证；

完整报告：docs/VERIFICATION-0.2.0.md。

安全与隐私

• 密钥只从本机 Codex 配置或指定环境变量读取，插件设置只保存密钥环境变量名，不保存密钥；不读取也不输出 auth.json / config.toml 原文；不发送聊天内容；除公开汇率接口外不主动联网。
• 安全问题请不要开公开 issue，按 SECURITY.md 私密报告。

说明

• 本 Release 为预发布（pre-release），标记在 For-Codex 分支的 tag 上，与主分支（DSH 网页版）的正式发行互不影响。
• 金额为观测估算，不等于服务商正式账单；今日/历史用量按同一密钥观测，可能包含并行调用的扣费。
• 逐项来源与许可边界见 PROVENANCE.md：代码 MIT；assets/ 美术素材不在 MIT 覆盖范围，随插件 as-is 分发；vendor/smol-toml 为 BSD-3-Clause；Electron 由安装脚本单独下载。