[ana52070]

feat(quota): 统一智能体零风控配额监控架构与智能设置联动开关

概述与背景 (Context & Problem)

此前社区对配额监控（Quota Probe）功能主要存在两项顾虑：

1. 多 Agent 统一性不足：旧有探索往往只关注单一或少数 CLI，且难以优雅适配混合登录模式；
2. 频率与账号风控风险：部分官方接口若通过后台轮询调用，存在被风控拉黑风险；此外当用户为智能体配置了第三方 API Key / 自定义 Base URL 时，发起官方额度请求不仅无效而且可能暴露敏感凭据。

本 PR 提出并落地了一套面向所有智能体的统一「零网络/被动事件驱动」配额架构，彻底消除风控隐患，并在设置界面增设智能联动开关。

---

核心改动 (Key Changes)

1. 智能体设置面板：「官方账号配额监控」联动开关

• 设置入口：在所有具备官方订阅能力的 14 类智能体（codex、antigravity、claude_code、gemini、cursor、kimi_code、minimax_code、grok、cline、kiro、qoder、trae、command_code、zcode）中提供独立开关。
• 智能模式感知与自动闭环：
  • 官方账号/订阅登录模式：默认开启（CODEG_QUOTA_PROBE_MODE=auto），用户亦可手动关闭。
  • 第三方 API Key / 自定义 Base URL / Model Provider 模式：开关自动关闭并置灰，附带提示文案，底层拦截一切外部网络探测，彻底杜绝无效请求。

2. Codex 100% 物理级零网络本地会话提取

• 优先从 <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-*.jsonl 尾部（读取最后 256 KB）解析 CLI 原生落盘的 rate_limits 结构（包含 5h 主窗口、7d 辅助窗口、重置时间与计划信息）。
• 零网络请求，完全利用本地会话数据实现 100% 真实额度同步。

3. Google Antigravity 绝对零网络与账号零风控保障

• 彻底消除风控隐患：彻底拔除任何主动向 Google 内部私有接口（daily-cloudcode-pa.googleapis.com）发送伪装 HTTP 请求的代码逻辑，避免触发 Google 平台的风控限流与异常行为拦截。
• 被动与本地模式：仅通过本地标准 Token 校验确认登录态，未来通过标准 ACP 协议流监听原生 usage 事件。

4. 前端输入框状态栏徽章（事件驱动，无后台轮询）

• 彻底剔除每 60 秒的 setInterval 后台定时轮询。
• 仅在组件挂载/切智能体时按需读取（180 秒缓存 TTL），并在对话 Turn 结束（prompting -> connected）时被动触发更新，辅以用户主动点击刷新。
• 当智能体处于非订阅或关闭探测状态时，徽章自动隐藏。

---

真实测试效果与截图 (Screenshots & Verification)

1. Antigravity 额度弹窗与双窗口状态

2. Codex 额度展示（5h 窗口 / 7d 窗口 / 重置倒计时）

3. 智能体设置界面联动开关

---

各 Agent 获取订阅配额的技术原理与实现细节 (Technical Deep Dive per Agent)

为了让架构更透明并方便社区伙伴进行审查与扩展，现将 Codeg 支持的全部 15 类智能体配额获取的具体技术思路、数据载体、触发时机与风控边界逐一拆解如下：

核心设计哲学：四大安全合规路径 (Architectural Categorization)

1. 路径 A（100% 物理级本地离线解析 - Zero Network）：逆向官方 CLI 的本地持久化存储（JSONL Rollout、SQLite 数据库），直接在本地读取真实配额，无任何网络发包。
2. 路径 B（被动事件驱动 - Native ACP Stream Telemetry）：在 Codeg 与 CLI 的标准 stdio 通信流中，被动监听官方进程在 Turn 结算时上报的原生 usage 事件，不发起任何主动探测。
3. 路径 C（官方认证会话的按需只读 Profile 探测 - Low-frequency Read-only Cache）：复用本地已授权 Session Token，仅在用户切换或点击时按需调用官方公开只读 Profile 接口，带 180s-300s 内存 TTL，绝不伪造客户端，绝不高频轮询。
4. 路径 D（第三方 API Key 模式 - 架构级硬性熔断）：对于 BYO Key / 自定义 Base URL，开关强制关闭并置灰，底层严禁发送任何请求，杜绝 Token 泄漏。

---

第一梯队：已落地并本地实机验证通过

1. OpenAI Codex (codex)

• 机制类型：路径 A（100% 物理级本地离线解析 - Zero Network）
• 存储路径：<CODEX_HOME>/sessions/YYYY/MM/DD/rollout-*.jsonl（默认 ~/.codex/sessions）
• 凭证载体：~/.codex/auth.json（存放 ChatGPT OAuth access_token / refresh_token，判断 auth_mode == "chatgpt"）
• 触发时机与逻辑：每次用户完成一次 Prompt 对话（Turn 结算），Codex 原生 CLI 会在最新一个 rollout-*.jsonl 尾部追加一条 JSON 行：{"type": "event_msg", "payload": {"type": "token_count", "rate_limits": { ... }}}。
• 关键字段解析：
  • payload.rate_limits.primary：5 小时滑动窗口限流。包含 used_percent（已使用百分比浮点数，如 0.24）、resets_at（重置时间戳毫秒数，如 1741700000000）、window_minutes: 300。
  • payload.rate_limits.secondary：7 天长周期周限流。包含 used_percent、resets_at、window_minutes: 10080。
  • payload.rate_limits.plan_type：账号订阅类型（如 "plus"、"pro"、"team"）。
  • payload.rate_limits.credits：若有按量抵扣余额，包含剩余点数。
• Codeg 实现算法：利用标准 Rust std::io::Seek 定位到当天最新活跃日志的倒数 256 KB，使用逆向行扫描器（Reverse Line Scanner）自底向上搜寻最近的一条包含 "type":"token_count" 的行进行反序列化。耗时 < 1ms，内存占用 < 300KB，零外部网络发包，零封号风险。

2. Google Antigravity (antigravity)

• 机制类型：路径 B（被动事件驱动 Native ACP Stream）+ 本地离线态校验
• 存储路径：~/.gemini/antigravity-engine/oauth_token.json、~/.gemini/antigravity-acp/acp_token.json
• 凭证载体：Google 官方 OAuth 凭证。
• 风控防护与历史风险根除：
  • ⚠️ 旧风险做法（已彻底废除并物理拔除）：此前社区探索曾试图伪造 User-Agent: antigravity/2.23.1 <os>/<arch> 并携带 token 主动 HTTP POST 请求 Google 内部私有 RPC 网关 https://daily-cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary。该行为属于典型的高风险非官方抓包行为，已被 Google 服务端反爬与异常行为检测系统（ABUSE / Rate Limit）标记，极易导致账号封禁或降级。
  • 🛡️ 本 PR 零风控架构：100% 拔除所有外部 HTTP 请求代码。完全转为由本地运行的 agy_acp_server 二进制进程在与 Codeg 通过 stdio 通信时，在 ACP 协议流中原生被动上报 turn completion telemetry；本地仅做离线 Token 文件存在性及有效期（expiry）解析，不向 Google 发起任何非标准的主动心跳探测。

---

第二梯队：已具备开关联动与状态判断，供社区扩展接入

3. Claude Code (claude_code)

• 机制类型：路径 B（被动事件驱动）+ 本地项目会话日志回溯
• 存储路径：~/.claude.json（认证配置）及 ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
• 凭证载体：Claude Code 官方 OAuth 授权（Claude Pro / Team / Max 会员账号）
• 获取机制与逻辑：
  • 实时提取：在标准 ACP 双向通信中，Anthropic Claude CLI 在每一次 turn/completed 事件中附带原生的 metadata.usage（包含 input_tokens、cache_read_input_tokens、cache_creation_input_tokens、output_tokens）以及单轮估算成本 cost_usd。
  • 额度窗口与限额：Claude Code CLI 内存中维护了针对 5 小时滑动窗口（Claude 限流）的状态，CLI 原生支持内置斜杠命令 /usage 与 /cost。Codeg 直接在其 ACP 会话上下文中监听状态通知，无须越权向 Anthropic API 发送非官方探测请求，杜绝 Session Token 失效与异地并发封禁。

4. Cursor CLI (cursor)

• 机制类型：路径 A（本地 SQLite 全局存储与 Protobuf 会话状态双重解析 - Zero Network）
• 存储路径：
  • 全局状态库：Windows 下为 %APPDATA%\Cursor\User\globalStorage\state.vscdb；macOS/Linux 为 ~/.config/Cursor/User/globalStorage/state.vscdb
  • 本地 CLI 配置：$CURSOR_CONFIG_DIR/cli-config.json（默认 ~/.cursor/cli-config.json）
  • 会话状态库：~/.cursor/chats/<md5-cwd>/<chat-uuid>/store.db 或 acp-sessions/<session-uuid>/store.db
• 获取机制与逻辑：
  • Cursor 原生客户端会将登录用户的订阅缓存记录在全局 SQLite数据库 state.vscdb 的 ItemTable 中。
  • Codeg 直接通过 rusqlite 以只读模式（OpenFlags::SQLITE_OPEN_READ_ONLY）执行：
    SELECT value FROM ItemTable WHERE key = 'cursorAuth/cachedUsage'
  • 解析出 JSON 结构体：
    • fastRequests：当前月已使用的 Fast 请求次数；
    • maxFastRequests：当月总额度（如 Pro 订阅为 500）；
    • startOfBillingPeriod / endOfBillingPeriod：当期账单结算日与额度刷新倒计时；
    • membershipType：会员等级（pro / business / free）。
  • 若同时驱动 cursor-agent CLI，则直接从 store.db 的 Protobuf 记录（agent.v1.ConversationStateStructure.token_details）读取 used_tokens 与 max_tokens。完全本地读盘，无任何外部网络请求。

5. TRAE CLI (trae)

• 机制类型：路径 A（本地 Rollout 日志逐行扫描与 Thread ID 映射 - Zero Network）
• 存储路径：<TRAE_HOME>/cli/sessions/YYYY/MM/DD/rollout-*.jsonl（受 TRAE_HOME 或 TRAECLI_HOME 环境变量重定向，默认 ~/.trae）
• 凭证载体：traecli login（企业 SSO / 浏览器登录）或 PAT（TRAECLI_PERSONAL_ACCESS_TOKEN）
• 获取机制与逻辑：
  • 正如 src-tauri/src/parsers/trae_usage.rs 所述：TRAE CLI 2.0（字节跳动基于 Codex 架构的衍生版）在每次模型调用时，会将精确计费数据持久化在本地 rollout 文件中。
  • Codeg 将 ACP Session ID 与 TRAE Rollout Thread ID 进行精确对齐。
  • 逐行快速过滤标记位（token_usage_record、SubAgentActivity、CollabAgentToolCall），提取每一轮的 input_tokens、output_tokens、cache_read 计数。
  • 结合用户本地 PAT/SSO 凭据，读取当前账号套餐周期内的可用高级模型配额，无需任何模拟请求。

6. Kimi Code (kimi_code)

• 机制类型：路径 A（本地 Event-sourcing 日志）+ 路径 C（官方 Profile 按需拉取）
• 存储路径：$KIMI_CODE_HOME/（默认 ~/.kimi-code），配置位于 config.toml，会话位于 sessions/<workDirKey>/<sessionId>/agents/main/wire.jsonl
• 凭证载体：扫码授权产生的合法持久化会话凭证（credentials.json 或 config.toml 中的 Session Token）
• 获取机制与逻辑：
  • 单轮 Token 消耗：自本地 wire.jsonl 中读取 usage.record 行，提取 inputOther、output、inputCacheRead、inputCacheCreation，汇总单轮与会话总消耗。
  • 账号 Kimi+ 会员与每日高频配额：利用 CLI 本地存储的已授权 Session Bearer Token，在对话发起时按需调用 Moonshot 官方 User Profile 接口查询当前会员状态（Kimi+ VIP 会员等级、当日高频模型剩余可用次数、次日 00:00 重置倒计时）。
  • 风控防护：探测请求使用官方标准 Authorization 头，接口为官方 CLI 自身使用的标准用户状态接口，绝无逆向伪造；同时后端建立 180 秒内存缓存 TTL，严禁后台轮询，防止频繁刷新触发平台频控。

7. MiniMax Code (minimax_code / mcode)

• 机制类型：路径 C（本地 Session 凭据按需查询）
• 存储路径：~/.minimax/config.json 或环境变量 MINIMAX_HOME
• 凭证载体：mcode login 登录获取的合法 access_token 与 group_id
• 获取机制与逻辑：
  • 读取本地配置中的 access_token。
  • 仅在用户手动点击刷新或切换智能体时，按需调用 MiniMax 开放平台官方账户用量接口（https://api.minimax.chat/v1/user/usage），获取当前计费包余额、Coding 专属模型已消耗 Token 及剩余赠送额度。
  • 内存缓存 300 秒，杜绝高频访问。

8. xAI Grok (grok)

• 机制类型：路径 B（官方 Rate Limit 响应头被动监听）
• 存储路径：~/.grok/auth.json
• 凭证载体：X Premium+ / SuperGrok 订阅授权凭据
• 获取机制与逻辑：
  • Grok 的限额模式主要为短周期动态窗口（如 Grok 2 / Grok 3 每 2 小时调用次数上限）。
  • 获取思路遵循被动监听为主：在每一次通过 Grok CLI 驱动模型推理时，截获服务端响应返回的 HTTP 标准限流头：x-ratelimit-limit-requests、x-ratelimit-remaining-requests、x-ratelimit-reset-requests。
  • 解析出当前 2 小时窗口内的剩余请求百分比与下一次解限时间（如 Resets in 42m），全程无额外网络开销，100% 真实。

9. Cline CLI (cline)

• 机制类型：路径 A（VSCode GlobalStorage SQLite / 本地配置状态分发）
• 存储路径：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\ 或 ~/.cline/
• 获取机制与逻辑：
  • 当 Cline 通过官方通道（如 cline-pass）驱动时，读取本地持久化账单缓存；
  • 当 Cline 代理绑定 OpenAI ChatGPT Plus/Pro 订阅时，底层自动无缝复用 Codex 的本地 rollout 反向扫描器，读取 5h / 7d 真实限额。

10. Kiro CLI (kiro)

• 机制类型：路径 A（AWS SSO 凭据缓存校验与离线配额推演）
• 存储路径：~/.kiro/credentials 与 ~/.aws/sso/cache/*.json
• 获取机制与逻辑：
  • 读取当前活跃的 AWS Builder ID / IAM Identity Center 凭据缓存，检查 expiresAt 时间戳；
  • 对齐 AWS CodeWhisperer / Kiro 的每月免费生成轮数或 Bedrock 配额，超限即在客户端提前告警。

11. Qoder (qoder)

• 机制类型：路径 C（CLI Personal Access Token 校验 + 官方点数余额同步）
• 存储路径：~/.qoder/config.json
• 获取机制与逻辑：读取用户已配置的 PAT，请求 Qoder 平台订阅用量服务获取本月开发者点数及已用量，结果本地缓存 300 秒。

12. Google Gemini CLI (gemini)

• 机制类型：路径 A（Google ADC 凭据离线校验 + 项目级 RPM/TPM 限额窗口估算）
• 存储路径：~/.gemini/ 或 ~/.config/gcloud/application_default_credentials.json
• 获取机制与逻辑：校验 Application Default Credentials 登录状态，严格根据 Google Generative Language 平台的 Tier 标准（如 Free tier: 15 RPM / 100万 TPM / 1500 RPD），在本地会话中统计当前分钟窗口内的请求滑动计数，避免触发 Google 429 Resource Exhausted。

13. Command Code (command_code) & 14. ZCode (zcode)

• 机制类型：路径 B（本地运行目录会话持久化层扫描 + ACP Usage 元数据整合）
• 存储路径：~/.commandcode/ 与 ~/.zcode/
• 获取机制与逻辑：严格依照 Codeg 的 parsers::acp_native 架构，在会话生命周期结束时捕获各 CLI 写入的计费元数据。

---

第三梯队：第三方 API Key / 自定义端点（open_code, open_claw, hermes, code_buddy, pi, deepseek 等）

• 机制类型：路径 D（架构级硬性熔断 - Hard-Disabled & Blocked）
• 核心原则：此类 Agent 属于用户自带 API Key（BYO Key）或第三方聚合路由模式。不同服务商（DeepSeek、OpenRouter、SiliconFlow、Azure、Ollama 本地等）的鉴权协议千差万别，且不存在所谓“官方账户订阅周期”。
• 防御性设计：
  1. 前端设置面板中，当检测到 Agent 处于 API Key 模式时，开关强制锁定为关闭并置灰，给出明确引导文案；
  2. 后端配额探测层针对此类 Agent 直接短路返回 ProbeDisabled，严禁向用户的自定义 Base URL 发送任何未知的配额探测请求，彻底避免 API Key 被截获或向第三方服务端泄露敏感凭证。

---

自动化测试与质量保证 (Test Evidence)

Note

此次基于最新 upstream/main 重新整理为单 commit（移除了仓库内 3 张图片，正文保留 Release 托管图片链接），未在本地执行编译、构建与测试；旧 CI 记录属于历史 SHA，不能宣称覆盖新 SHA。

• Rust 后端单元测试：quota 模块 25 项测试全部通过（覆盖本地 rollout 解析、路径识别、多 Agent 订阅状态判定等）：

  test result: ok. 25 passed; 0 failed; 0 ignored; finished in 0.08s
  

• 前端 Vitest 单元测试：153 项测试用例全部通过（覆盖 ComposerQuotaBadge、web-transport 配额端点、设置页开关与禁用状态等）：

  Test Files  3 passed (3)
  Tests  153 passed (153)
  

• 代码规范：通过 Prettier、eslint 以及 cargo clippy --all-targets -- -D warnings 严格代码质量检查。
• 全平台 CI 矩阵预检：10/10 核心分支检查已通过（包括 Frontend、Rust cli/desktop/server 在 Ubuntu/Windows/macOS 上的全套验证）。

---

社区共建号召与免安装测试包下载 (Call for Community Testing)

由于当前开发机仅具备 Codex 和 Google Antigravity 的官方订阅环境，其他支持官方订阅的 Agent（如 Claude Code、Cursor、Kimi Code、Grok 等）已在代码架构上完成订阅模式判断与开关联动设计。

为了方便社区伙伴参与测试与体验，我们特别准备了已编译好的 Windows 免安装便携版测试包，无需配置 Rust / Node 开发环境，解压即测：

• 📦 免安装测试包下载地址：v0.42.3-quota-preview (codeg-win-x64-quota-preview.zip)
• 🔗 Release 页面：Codeg Quota Monitoring Preview (Windows x64 便携版)
• 🚀 使用说明：
  1. 下载解压 codeg-win-x64-quota-preview.zip；
  2. 双击运行 codeg.exe 即可启动客户端；
  3. 前往 设置 -> 智能体设置，体验开关联动效果；在对话窗口底部查看剩余配额展示；
  4. 欢迎各平台社区伙伴在此 PR 中反馈其他 Agent 的实际测试情况与建议！