- 项目目录：
codexbar-apk - 产品展示名：
CodexMeter - 中文称呼：
Codex 用量仪 - 目标平台：Android 12+
- 分发方式：自用 / 小范围侧载 APK
- 文档状态：MVP PRD 初稿
Codex 的用量窗口会影响日常开发节奏，但当前在手机端缺少一个足够轻量、随时可见的额度查看工具。
用户希望在 Android 手机上快速查看 Codex 当前额度状态，尤其是：
- 桌面微件上一眼看到当前主额度剩余百分比。
- App 首页查看 5小时额度与 1周额度。
- 通知栏保留一个低打扰的当前状态提示。
- 额度接近耗尽时能收到提醒。
- 不依赖桌面端服务，不做本地 token/cost 估算。
CodexMeter 是一个面向自用和小范围侧载的 Android 工具 App，用于查看多个 AI 服务商官方用量额度。
核心定位：
- 快速查看，而不是完整账号管理器。
- 本地优先，而不是云端同步服务。
- 官方数据源，而不是客户端估算。
- 微件和首页优先，而不是复杂分析系统。
- 多 Provider 统一管理（Codex / DeepSeek / z.ai Coding Plan / z.ai API / MiniMax / Cursor / Kimi / Kimi Code API / Claude / Antigravity / Grok），而不是单一服务商工具。
- 同时使用多个 AI 服务商的高频开发者。
- 需要随时掌握当前额度状态、余额和 reset 时间的用户。
- 接受 APK 侧载和本地会话配置的高级用户。
- 打开手机桌面，直接通过微件判断各服务商额度还能不能继续用（可配置 1–4 个字段）。
- 打开 App 首页，查看当前账号的额度、余额、reset 时间和最近趋势。
- 额度进入紧张或耗尽状态时，通过通知提醒及时调整使用节奏。
- 登录失效或采集失败时，明确知道当前数据不可信，并能通过对应认证方式重新登录。
- 查看余额型 Provider（DeepSeek / z.ai API等）的余额和充值 / 赠送明细。
- 多 Provider 账号接入（Codex device-code；Grok 设备码登录；DeepSeek / z.ai Coding Plan / z.ai API / MiniMax / Kimi Code API Key；Cursor / Kimi Cookie WebView；Claude OAuth WebView 拦截；Antigravity OAuth loopback）。
ProviderSelectionSheet底部选择器，统一入口添加任意 Provider 账号。AuthScaffold统一认证页 Chrome。- 既有 OAuth 会话兼容，包括历史上从
auth.json导入后已保存的会话。 - Codex 5小时额度与 1周额度展示。
- 多 Provider 额度窗口展示（百分比 / 余额 / 次数 / 多模型分桶）。
- 货币转换（余额型 Provider 自动按目标货币换算，保留原始货币注释）。
- DeepSeek 余额明细（赠送额度 / 充值额度拆分）。
- 首页仪表盘（Provider 自适应小时级使用趋势图）。
- 可调整大小桌面微件（3×1 / 4×1 / 3×2 / 4×2，最多 4 个可配置字段）。
- 常驻通知。
- 阈值告警。
- 多账号添加与全局当前账号切换。
- 本地历史保存与 24 小时极简趋势。
- 设置页。
- 简体中文 / English 国际化。
- 本地加密保存敏感会话信息。
- 失败降级和脱敏诊断。
- App 浅色 / 深色 / 跟随系统外观切换（独立持久化，仅作用于 App；桌面微件始终跟随系统深浅色）。
- 可选的电池优化豁免引导，提升后台刷新可靠性。
- 不上架公开分发。
- 不支持 Android 12 以下。
- 不支持平板、折叠屏、Wear OS。
- 后台刷新支持已保存 Active 账号的有界多账号刷新，但不做实时监控。
- 不区分模型、场景、Local / Cloud / Review（Antigravity 多模型只在趋势图聚合使用，不分场景拆分）。
- 不做 token / cost 本地估算。
- 不做 Cookie Header 或 token 手填。
- Codex 验证页只通过 device-code 外部浏览器 handoff 打开，不嵌 WebView。
- 不做网页数据解析。
- 不做锁屏额度展示。
- 不做独立历史页。
- 不做数据导出报表。
- 不做云端同步或第三方中转服务。
- 不保存账号密码。
- 不绕过任何服务商风控。
CodexMeter 只使用各 Provider 官方接口返回的数据。
允许的数据来源：
- 通过各 Provider 认证流程（device-code / API Key / Cookie WebView / OAuth PKCE）建立的合法会话。
- 迁移前已保存的 OAuth 会话，包括历史上从 Codex CLI
auth.json导入后归一化保存的会话。 - 通过合法会话调用各 Provider 官方 usage / quota / balance API 返回的数据。
- Grok 通过 SuperGrok 设备码登录会话调用官方 billing 端点（
GET https://cli-chat-proxy.grok.com/v1/billing?format=credits）获取周额度使用百分比、重置时间与预付余额。
不允许的数据来源：
- 本地 token 日志扫描。
- cost usage 估算。
- 根据历史消耗推算额度。
- Cookie Header 手动填写。
- 网页正文或页面结构解析。
- 第三方服务中转计算。
MVP 需要展示：
- 5小时剩余额度百分比。
- 5小时额度 reset 时间 / 倒计时。
- 1周剩余额度百分比。
- 1周额度 reset 时间 / 倒计时。
- 当前账号名。
- 最近刷新时间。
- 数据状态。
如果官方接口缺失某个字段：
- 对应字段显示“暂不可用”。
- 不使用估算值补齐。
- 不对缺失字段触发告警。
- 记录脱敏诊断信息。
添加账号通过统一的 ProviderSelectionSheet 底部选择器进入：用户先选择 Provider，再进入该 Provider 对应的认证流程。当前支持 11 个 Provider，按认证类型分为四类：
- Codex / Grok：device-code 外部浏览器登录（Codex 为 Hermes 对齐流程，详见 §7.2；Grok 为 SuperGrok 订阅的 xAI 设备码登录，登录与校验形态同 §7.2，额度数据来自 Grok billing 端点）。
- DeepSeek / z.ai Coding Plan / z.ai API / MiniMax / Kimi Code API：应用内 API Key 输入（
ApiKeyAuthScreen）。Kimi Code API 使用 Kimi Code 控制台长期有效的 API Key，调GET /coding/v1/usages；与 Kimi Cookie 接入面（短期 JWT）互相独立，已存 Kimi Cookie 账号不受影响。 - Cursor / Kimi：内嵌 WebView 登录后由
CookieManager自动提取目标 Cookie（WebViewAuthScreen）。 - Claude / Antigravity：OAuth PKCE 登录（Claude 走 WebView 拦截回调 code；Antigravity 走外部浏览器 + 127.0.0.1 loopback 短连接）。
所有 Provider 均不提供 auth.json 文件选择、粘贴 JSON、token 手填或 Cookie Header 手填入口。各认证类型的组件与边界以 docs/ARCHITECTURE.md §6 / §11 为准。
Codex 使用 device-code 外部浏览器登录，定义如下：
- App 请求 Codex device code，并通过外部浏览器打开普通 verification 页面。
- 页面顶部显示紧凑的一行 device code + 复制按钮，通知可辅助复制 code。
- App 轮询授权结果，成功后换取候选 OAuth 会话。
- 候选会话必须使用 official usage API 校验成功后，才保存账号、session 和初始快照。
完整状态机、通知行为和账号不匹配处理以 docs/CODEX_DEVICE_CODE_LOGIN_SPEC.md 为准。
Device-code 外部浏览器登录不是：
- 抓取普通网页登录 Cookie。
- 保存账号密码。
- 绕过 passkey、验证码或风控限制。
失败处理：
- 显示失败原因：用户取消、device code 过期、授权轮询失败、token exchange 失败、usage API 校验失败等。
- 提供
重试登录/重新生成授权码行为，不提供导入文件或粘贴 JSON 兜底。 - 诊断信息必须脱敏，不包含 device auth id、auth code、code verifier、token、Cookie 或原始响应体。
auth.json 兼容仅针对 Codex（其他 Provider 无此历史路径）。MVP 不再支持新的 auth.json 文件 / JSON 导入方式：
- 不提供文件选择器导入入口。
- 不提供粘贴完整 JSON 的入口。
- 不提供 access token / refresh token 单字段表单。
- 不提供 Cookie Header 输入。
兼容要求：
- 迁移前已经保存的账号和 OAuth 会话不自动删除。
- 历史上从
auth.json导入后已归一化保存的会话继续按统一 refresh 逻辑保活。 - 删除账号仍按普通账号删除流程执行。
安全要求：
- 不明文展示已保存凭据。
- legacy raw
auth.json内容必须只作为需要脱敏的敏感内容处理，不能持久化、缓存、进入诊断、日志或截图。 - 新实现不得新增导入 UI、文件 picker、粘贴 JSON 或其他手动凭据路径。
所有 Provider 的会话统一保存为「通用 envelope + Provider 私有加密 payload」：公共层只持有 envelope 元数据（providerId、accountId、状态、时间戳），凭据原文由各 Provider 私有 payload 持有并经 AES-GCM 加密落库（详见 docs/ARCHITECTURE.md §7.2 / §10）。
以 Codex 为例，无论来源是 device-code 外部浏览器登录还是迁移前已保存的 OAuth 会话（含历史从 auth.json 导入后归一化的会话），私有 payload 都视为统一的 Codex OAuth 会话，包含：
- access token
- refresh token
- id token
- account id
- last refresh
- account email，如果可解析
- plan，如果官方返回
不同认证类型的私有 payload 字段不同（API Key / Cookie / OAuth token），但后续刷新逻辑不区分来源，统一执行：
- token / 凭据 refresh（如适用）
- official usage / quota / balance API 请求
- 数据解析
- 本地历史保存
登录、重新登录或既有会话更新成功后：
- 立即保存账号。
- 默认账号名优先使用邮箱 / Provider 返回的账号标识。
- 如果不可得，使用按 Provider 命名的默认名（如
Codex 账号 1、DeepSeek 账号 1）。 - 不要求保存前命名。
- 账号别名在账号管理页修改。
- 默认设为当前账号。
- 如果检测到同一个 account id 已存在，则更新已有账号会话，不创建重复账号。
- 保存成功后回首页，并显示新账号额度。
- 保存成功后主动触发一次微件刷新。
MVP 支持添加多个账号，后台周期刷新会刷新所有 Active 账号。
刷新策略：
- 周期任务按有界并发刷新 Active 账号，避免多个账号过多时堆积。
- 同一账号仍必须 single-flight，避免 refresh token 并发轮换。
- 非 Active / 需要重新登录 / 已禁用账号不参与周期刷新。
当前账号影响：
- 首页显示。
- 未单独配置的桌面微件默认显示。
MVP 不做：
- 多账号聚合。
- 多账号对比。
允许：
- 每个桌面微件可独立指定一个已保存账号用于展示；展示读取本地最新快照。
- 未独立配置的微件默认使用当前账号 + 5小时额度。
- 常驻通知可独立选择跟随当前账号或指定某个已保存账号，并可选择显示 5小时额度或 1周额度。
当前实现中，首页顶部和玻璃摘要区只展示当前账号，不提供首页内快速切换 Bottom Sheet。
首页账号摘要显示：
- 当前账号名。
- 圆形纯色首字头像。
- 当前数据状态。
- plan 类型，如果官方返回。
- credits 余量，如果官方返回。
账号切换和账号管理统一放在 Account Tab，避免首页和账号页形成两套账号操作入口。
账号管理为二级页面。
每个账号卡片显示：
- 账号别名 / 默认名。
- 当前账号标记。
- plan 类型，如果官方返回。
- credits 余量，如果官方返回。
- 采集状态。
- 最近刷新时间。
- 5h / 1-week 剩余百分比摘要。
账号卡片默认折叠；折叠态只显示账号身份、当前/状态标记、采集状态和最近刷新摘要，点击卡片后展开显示 plan、credits、额度摘要、告警开关和账号管理操作。
每个账号支持：
- 设为当前账号。当前账号不可再设为当前时，按钮仍保留可见描边。
- 重命名。
- 重新登录。
- 删除账号。删除按钮使用与其它账号操作一致的描边按钮，仅文字使用危险色。
- 5小时额度告警开关。
- 1周额度告警开关。
安全要求：
- 删除账号必须确认。
- 删除账号同时删除该账号会话和历史数据。
- 不展示 token、auth.json 或 OAuth 原文。
首页是仪表盘优先。
已登录时显示：
- 顶部区域：
- App 标题：
CodexMeter - 当前数据状态说明
- 手动刷新图标按钮
- App 标题：
- 当前账号玻璃摘要：
- 当前账号名与头像
- 当前数据状态
- plan 类型
- credits 余量
- 5小时额度卡：
- 剩余百分比
- 状态
- reset 倒计时
- 1周额度卡：
- 剩余百分比
- 状态
- reset 时间 / 倒计时
- 最近 24 小时极简趋势：
- 默认跟随主额度配置
- 可切换 5h / Weekly
- 刷新区域：
- 最后刷新时间
- 当前刷新状态
首页不做：
- 主额度大卡。
- 卡片点击展开详情。
- 独立详情页入口。
- 模型/场景拆分。
- 完整历史列表。
未登录时：首页卡片显示为配置 / 登录引导。
需要提供：
- 登录引导卡。
- 主按钮：
添加账号（进入统一的 Provider 选择 / 添加流程）。 - 简短说明：添加账号后可在微件和通知中查看额度。
MVP 趋势只做最近 24 小时极简圆顶柱状图。
要求：
- 显示最近 24 小时数据。
- 默认展示 5小时额度。
- 可在 5h / Weekly 间切换。
- 固定 24 个小时槽位；同一小时多条成功采样取剩余百分比平均值。
- 不支持缩放。
- 不支持 tooltip。
- 不做复杂图表交互。
- 数据不足时显示“数据积累中”。
- 首尾柱保留半个柱宽，避免贴边裁切。
MVP 做一个可调整大小并自适应布局的桌面微件，按可用尺寸在四种布局变体（WidgetLayoutVariant）间自适应。
支持尺寸（参考尺寸见 docs/ARCHITECTURE.md §15）：
- 3×1（约 180×60dp）：紧凑主额度，1 个字段。
- 4×1（约 300×60dp）：双额度横条，2 个字段。
- 3×2（约 180×150dp）：网格，3 个字段。
- 4×2（约 300×150dp）：网格，4 个字段。
3×1 紧凑布局（1 字段）：
- 左侧第一行：
<Provider> · 状态。 - 左侧第二行：账号名。
- 左侧第三行：主额度重置（短日期 + 时间）/ 最近刷新时间。
- 右侧：主额度类型标签和大号剩余百分比，例如
5小时额度 62%；正常态百分比使用主文字色，注意 / 紧张 / 耗尽才使用语义重点色。
4×1 横条布局（2 字段）：
- 顶部：
<Provider> · 账号名与当前主额度状态。 - 下方并排展示两个字段（默认
5小时额度与1周额度）。 - 每个额度显示标签、对应重置时间（短日期 + 时间）和大号剩余百分比；正常态百分比使用主文字色，注意 / 紧张 / 耗尽才使用语义重点色。
3×2 / 4×2 网格布局（3 / 4 字段）：
- 头部行显示 Provider 品牌图标、账号名与状态，下方按 2 列网格展示 3 或 4 个字段。
- 字段内容与上一致；完整布局细节见
DESIGN.md。
第二行规则：
- 正常 / 注意 / 紧张 / 耗尽：优先显示 reset 倒计时 + 状态。
- 可能过期 / 已过期：优先显示最后刷新时间 + 过期状态。
- 刷新失败：显示最后成功刷新时间 + 失败状态。
- 会话失效：显示
需要重新登录。 - 未登录：显示
点按连接 Codex。
示例：
1h 24m 后恢复 · 正常周一 08:00 重置 · 注意35 分钟前刷新 · 可能过期需要重新登录
- 已登录时点击微件：打开 App 首页。
- 未配置 / 未登录时点击微件：同样打开 App 首页，由首页无账号态承载添加账号引导；微件不再深链单一 Provider 的添加账号页（已支持多 Provider）。
- 长按微件进入系统配置入口时，可通过紧凑浮层窗口选择此微件显示的账号和小尺寸主额度窗口；浮层只保留账号、主额度两个可展开选项，不覆盖整个桌面。
- MVP 不做微件内按钮。
- MVP 不做微件内账号切换。
未单独配置的微件默认使用当前账号 + 5小时额度。
微件独立配置可覆盖某个微件的小尺寸主额度窗口，不改变 App 内其它配置。
小尺寸主额度选项：
- 5小时额度，默认。
- 1周额度。
默认影响范围：
- 可调整大小的桌面微件：3×1 显示微件自己的主额度（1 字段）；4×1 显示 2 字段（默认 5小时额度 + 1周额度）；3×2 / 4×2 显示 3 / 4 字段。
不影响：首页始终同时显示 5h 和 Weekly 两张额度卡；常驻通知使用自己的账号与显示额度配置。
常驻通知用于辅助微件，不作为主体验。
可配置：
- 常驻通知开关。
- 通知账号：默认跟随当前账号，也可指定已保存账号。
- 通知显示额度：5小时额度或 1周额度，默认 5小时额度。
内容：
- 标题：
Codex 62% - 正文：
- 正常：
1h 24m 后恢复 · 主号 - 过期：
35 分钟前刷新 · 数据可能已过期 - 失效：
需要重新登录
- 正常：
交互：
- 点击通知打开首页。
- 常驻通知可在设置中关闭。
- 通知权限未授予时，不阻塞 App 首页和微件。
不做：
- 通知内按钮。
- 通知内直接刷新。
- 锁屏额度展示。
- 多账号并排显示。
MVP 使用 3 个通知渠道：
- 状态通知：
- 常驻通知使用。
- 默认静默。
- 低打扰。
- 额度告警：
- 紧张 / 耗尽阈值提醒。
- 同一额度窗口同一阈值只提醒一次。
- 账号与错误：
- 会话失效。
- 连续刷新失败。
- 需要重新登录。
默认阈值按剩余额度百分比判断：
- 正常：剩余 31–100%。
- 注意：剩余 11–30%。
- 紧张：剩余 1–10%。
- 耗尽：剩余 0%。
可配置：
- 注意阈值：剩余 2%–99%。
- 紧张阈值：剩余 1%–98%。
- 注意阈值必须高于紧张阈值。
- 耗尽固定为剩余 0%。
- 配置后的阈值同时影响首页、微件状态文案 / 颜色和通知告警。
- 每个账号的 5小时额度和 1周额度可在账号管理中独立开启或关闭告警。
告警策略：
- 对每个已开启告警的账号额度窗口评估。
- 注意状态只改变 App / Widget 状态颜色和文案，不弹通知。
- 紧张和耗尽发通知。
- 同一额度窗口同一阈值只提醒一次。
- reset 后重新允许提醒。
- 额度刷新成功、阈值调整、开启某个账号窗口告警时都必须重新评估告警。
MVP 使用省电后台刷新策略。
- 后台约 15 分钟刷新一次所有 Active 账号。
- 不提供刷新间隔配置。
- 后台刷新默认开启。
- 用户可关闭后台刷新。
以下行为触发立即刷新：
- 点击首页右上角手动刷新图标按钮（或首页下拉刷新）。
- 添加 / 切换账号后。
打开 App、从微件或通知进入首页不再触发网络刷新，仅展示已保存的最近快照，避免频繁切页造成高频 API 调用；新鲜度由手动刷新与周期后台刷新保证。
如果系统限制导致刷新不稳定：
- 设置页显示诊断提示。
- 不强制用户关闭电池优化，但在后台刷新开启且尚未豁免时，刷新卡片提供一个可选的「提升后台刷新可靠性 / 去允许」入口，引导用户把 App 加入电池优化白名单（系统对话框，用户可拒绝）。
- 不因后台刷新失败清空旧数据。
- 0–30 分钟内刷新成功：正常。
- 超过 30 分钟未成功刷新：数据可能已过期。
- 超过 2 小时未成功刷新：已过期，显示灰色失效态。
- 401 / 403 或明确认证错误：会话失效。
- 离线：显示最近一次成功数据 + 离线标记。
采集成功：
- 更新首页。
- 更新微件。
- 更新通知。
- 写入历史。
网络失败：
- 保留最近一次成功数据。
- 标记网络异常 / 离线。
- 不覆盖历史成功数据。
认证失败：
- 标记需要重新登录。
- 首页显示登录引导。
- 微件和通知显示灰色失效态。
- 仍允许手动刷新对该账号发起重试；若刷新成功（例如此前仅为临时网络问题），自动清除需要重新登录标记并恢复正常。周期后台刷新仍跳过需要重新登录账号。
解析失败 / 字段缺失：
- 显示数据解析失败或字段暂不可用。
- 保留最近一次成功数据。
- 提供复制诊断信息入口。
服务端异常 / 限流：
- 显示暂时无法刷新。
- 下一轮按正常间隔重试。
连续失败：
- 设置页诊断卡显示失败次数和最后错误时间。
每次采集保存：
- 账号 ID。
- 采集时间。
- 5h 官方使用百分比与派生剩余百分比。
- 5h reset 时间。
- 1-week 官方使用百分比与派生剩余百分比。
- Weekly reset 时间。
- 采集状态：成功 / 失败 / 认证失效等。
默认保留 30 天。
可选：
- 7 天。
- 30 天。
- 90 天。
- 永久。
后台刷新后自动清理过期记录。
设置页支持：
- 清空当前账号历史。
- 清空全部账号历史。
要求：
- 清空全部账号历史必须二次确认。
- 清空历史不影响账号登录态、当前账号、设置项。
- 删除账号时自动删除该账号历史。
设置页使用分组卡片组织。
设置页不包含账号分组。
账号相关操作统一在 Account Tab：
- 添加账号。
- 切换当前账号。
- 重命名账号。
- 重新登录。
- 删除账号。
- 提供外观切换卡片：浅色 / 深色 / 跟随系统三选一（默认跟随系统），独立持久化、立即生效；仅作用于 App，桌面微件始终跟随系统深浅色。
- 不提供全局主额度选择；首页始终同时显示 5小时额度与 1周额度。
- 字体方案固定为 Mono Focus，不提供 App 内字体方案配置入口。
- App 内不提供语言切换入口，默认跟随系统语言；系统语言不在支持范围时显示英文。
- 后台刷新开关。
- 最近刷新时间。
- 最近后台刷新结果，来自当前账号最近一次周期后台刷新尝试。
- 后台限制提示，仅异常时显示。
- 电池优化豁免入口「去允许」，仅在后台刷新开启且 App 尚未被加入电池优化白名单时显示。
- 常驻通知开关。
- 通知账号选择。
- 通知显示额度：5小时额度 / 1周额度。
- 账号与错误提醒开关。
- 注意阈值。
- 紧张阈值。
额度告警开关不在设置页全局控制；它们位于账号管理页的每个账号卡片内，分别控制 5小时额度和 1周额度。
- 历史保留周期。
- 清空当前账号历史。
- 清空全部账号历史。
设置页底部提供折叠诊断卡。
正常时默认折叠，异常时提示查看。
显示（按分组段落，时间带可读时间和相对时长）：
- 运行环境：App / 系统 / 设备信息、电池优化与后台限制状态、网络类型。
- 后台调度：WorkManager 状态与最近调度信息、通知权限。
- 应用配置：保留天数、刷新间隔、告警阈值、Widget 数量。
- 全部账号一行摘要：脱敏账号哈希、状态、最近刷新结果。
- 当前账号：脱敏信息、数据来源 OAuth API、最近刷新时间、最近成功刷新时间、连续失败次数、最近错误类型。
操作：
- 复制诊断信息。
- 重新检测诊断摘要。
诊断内容必须脱敏，不包含：
- access token
- refresh token
- id token
- auth code
- Cookie
- 完整 auth.json
关于区显示：
- App 名称：CodexMeter。
- 版本号。
- 构建号。
- 数据来源说明。
- 简短隐私说明。
- 检查更新按钮：查询 GitHub Releases 最新版本；仅当存在更高版本且包含 APK 资产时弹窗提示。
- 开源/致谢入口，P1 可完善。
隐私说明需要明确：
- 账号会话仅保存在本机。
- 敏感会话信息使用系统安全能力加密保存。
- 不上传凭据到第三方服务。
- 不保存账号密码。
- 不做本地 token 估算。
MVP 支持：
- 简体中文。
- English。
默认语言：跟随系统；系统语言不支持时显示英文。
规则：
- 所有用户可见文案必须资源化。
- App 内不提供手动语言选择；旧版本残留的系统级 App 专属语言覆盖必须在启动时清理，不得继续覆盖系统语言。
- 禁止硬编码展示文案。
Codex、OpenAI、auth.json等专名不翻译。- 其他语言放远期考虑。
- 通知权限可选。
- 拒绝通知权限不影响首页和微件。
- 电池优化豁免（
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS）为可选项，仅在设置页主动引导，用户可拒绝；不强制、不作为后台刷新前提。 - 后台刷新默认开启。
- 常驻通知可关闭。
- 阈值告警可关闭。
- 不提供锁屏额度展示。
PRD 只定义产品级原则，具体技术实现放架构文档。
原则：
- 本地优先。
- 敏感信息本地加密保存。
- 不上传凭据到第三方服务。
- 不依赖云端账号系统。
- 卸载 App 后数据随 App 删除。
- 用户可清空历史、删除账号、退出登录。
MVP 完成时，应满足以下标准。
- 能通过 Hermes 对齐的 device-code 外部浏览器登录接入账号。
- 不提供新的
auth.json文件选择、粘贴 JSON 或手动 token / Cookie 登录路径。 - 迁移前已保存的 OAuth 会话，包括历史上从
auth.json导入的会话，继续可刷新且不会被自动删除。 - 登录后能调用 official usage API 完成校验。
- 能获取 5h 官方使用百分比、派生剩余百分比和 reset 时间。
- 能获取 1-week 官方使用百分比、派生剩余百分比和 reset 时间。
- 能处理认证失效、网络失败、字段缺失。
- 不做本地估算。
- 显示当前账号。
- 显示 5h / Weekly 两张额度卡。
- 显示最近 24h 极简趋势。
- 支持手动刷新。
- 未登录时显示登录引导。
- 3×1 微件显示主额度剩余百分比；3×2 / 4×2 网格显示 3 / 4 个字段。
- 4×1 微件显示 5小时额度与 1周额度。
- 显示
<Provider> · 账号名与 Provider 品牌图标。 - 显示状态文案与重点色。
- 未配置 / 未登录时点击微件打开 App 首页，由首页无账号态引导添加账号。
- 微件随系统深浅色切换玻璃材质。
- 常驻通知显示主额度剩余百分比。
- 常驻通知可关闭。
- 常驻通知可选择显示账号和额度窗口。
- 紧张 / 耗尽阈值告警可用。
- 每个账号的 5小时额度和 1周额度可独立开关告警。
- 同一窗口同一阈值去重提醒。
- 支持常驻通知账号和显示额度选择。
- 默认跟随系统语言，不提供 App 内语言选择；系统语言不支持时显示英文。
- 支持账号管理。
- 支持历史保留和清空。
- 支持脱敏诊断。
- 会话本地加密保存。
- 不明文展示 token / auth.json。
- 诊断信息脱敏。
- 简中和英文完整覆盖。
- 更丰富的大尺寸微件。
- 历史详情页：24h / 7d / 30d。
- CodexBar 多账号配置导入。
- 每个微件独立配置主额度。
- 更完整的开源许可页面。
- 多账号聚合 / 对比。
- 更多语言。
- 平板 / 折叠屏适配。
- 其他 AI coding 工具额度监控。
- 云端同步，仅在明确需要时重新评估。
以下能力如果未来要做，必须重新评估安全、合规和维护成本：
- 公开分发。
- 云端同步。
- 多用户账号体系。
- 第三方服务中转。
- 其他 provider 的账号凭据接入。
以下内容不在 PRD 中展开，进入 ARCHITECTURE.md：
- Android 技术栈。
- Device-code 外部浏览器登录实现细节。
- 本地加密方案。
- 数据库和设置存储方案。
- 后台刷新任务实现。
- 微件实现方案。
- 通知渠道实现。
- 测试策略。