企业官网建设流程全解析

CodexBar 中 T3 Chat 用量集成：cookie 认证、tRPC 端点与双用量窗口解析原理

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar

CodexBar 通过 cookie 认证的 tRPC 接口（无公开 API）追踪 T3 Chat 的 4 小时 Base 用量窗口与月度 Overage 超量（Overage）用量桶，并在菜单栏以 "Base / Overage" 双窗口形式展示。本文以仓库中 docs/t3chat.md 为主体，逐层拆解该集成的配置方式、请求构造、响应解析与错误处理，并结合 T3Chat 源码目录 的实现细节，帮助读者理解并调试这条 "非官方集成" 的完整链路。

集成定位与非官方边界

T3 Chat 没有为用量数据发布官方 API。CodexBar 的做法是读取其网站自身使用的 cookie 认证端点，因此文档明确标注这是一次非官方集成：上游任何响应结构或鉴权机制的变更都可能使其失效。这一风险在代码中也得到了体现——解析器、错误类型和 cURL 捕获解析都集中在 T3ChatUsageSnapshot.swift 与 T3ChatUsageFetcher.swift 中，便于在上游变动时快速定位修补。

从源码结构看，该 provider 还具备一条插件回退路径：T3ChatProviderDescriptor.swift 中定义的fetchPlan在ProviderPluginPrototype启用时，会优先尝试t3chat.js脚本抓取策略，失败或不可用时回退到原生 Swift 策略T3ChatWebFetchStrategy。两条路径都只依赖 cookie，且不会调用 tRPC 端点之外的其他 T3 Chat 接口。

配置方式

自动导入（推荐）

1. 在任意受支持的浏览器中登录 T3 Chat；
2. 在 CodexBar 的Settings → Providers中启用T3 Chat。

启用后 CodexBar 会自动导入浏览器会话 cookie，并且该 cookie 只会被发送到https://t3.chat。自动导入的实现在 T3ChatUsageFetcher.swift 的T3ChatCookieImporter中：它按BrowserCookieImportOrder依次探测已安装的浏览器，对t3.chat与www.t3.chat两个域名做 cookie 查询，将所有匹配记录拼成name=value; name2=value2形式的 header 返回，第一个非空来源即生效。

注意：浏览器 cookie 导入可能需要完全磁盘访问权限（Full Disk Access，Safari 尤其如此），Chromium 系浏览器则可能需要macOS 钥匙串（Keychain）授权。这也是为什么自动导入被#if os(macOS)包裹——非 macOS 平台下自动模式不可用，只能走手动模式（见T3ChatWebFetchStrategy.isAvailable的平台判断）。

手动粘贴

在 T3 Chat 的 provider 设置里把Cookie source切到Manual，然后在T3 Chat cookie字段中粘贴以下任一项：

• 从浏览器网络请求中复制的裸Cookie: ...header 值；
• 从 T3 Chat 设置页捕获的完整curl命令——解析器会处理所有-H标志，但只转发Cookieheader 和一组固定的安全请求头（白名单见 T3ChatUsageFetcher.swift：accept、referer、sec-fetch-*、trpc-accept、x-client-context、x-deployment-id、x-trpc-batch、x-trpc-source等）。

手动捕获 cookie 的标准步骤：

1. 在浏览器中打开https://t3.chat/settings/customization；
2. 打开开发者工具 → Network 标签；
3. 刷新页面，找到getCustomerDatatRPC 请求；
4. 右键 → Copy → Copy as cURL；
5. 把完整curl命令粘贴进 CodexBar 设置里的T3 Chat cookie字段。

解析入口是T3ChatUsageFetcher.requestContext(from:)（T3ChatUsageFetcher.swift）：它先用CurlCaptureParser提取 header 字段，取其中的Cookie值并归一化，再通过白名单挑出可转发的请求头。需要强调的是：T3 Chat 不支持独立的环境变量或--cookieCLI 参数，Settings 字段是唯一的手动通道。

设置界面本身由 T3ChatProviderImplementation.swift 提供：一个 "Cookie source" 选择器（Auto/Manual，不允许 Off）加上仅在 Manual 模式下可见的安全文本字段，字段旁还有 "Open T3 Chat Settings" 链接直接打开https://t3.chat/settings/customization。cookie 值经sanitizedCookieHeader存储、normalizedConfigValue归一化，持久化逻辑在 T3ChatSettingsStore.swift。

数据源：单次 GET 请求与 JSONL 响应

每次刷新，CodexBar 只发送一个 GET 请求：

GET https://t3.chat/api/trpc/getCustomerData?batch=1&input=...

请求构造的细节（T3ChatUsageFetcher.customerDataURL()与applyDefaultHeaders）：

• input参数是固定的 tRPC 入参{"0":{"json":{"sessionId":null},"meta":{"values":{"sessionId":["undefined"]}}}}，源码注释标明其形状捕获自 2026 年 5 月的getCustomerData请求；
• 默认请求头模拟浏览器环境：trpc-accept: application/jsonl、x-trpc-source: web-client、x-trpc-batch: true、Chrome User-Agent、Referer: https://t3.chat/settings/customization、一组Sec-Fetch-*头以及Origin: https://t3.chat。手动 cURL 捕获中的对应头会覆盖这些默认值。

响应体是JSONL（tRPC 的 jsonl 传输格式）。解析器 T3ChatUsageParser 逐行解析：对每一行尝试JSONSerialization，然后递归深度搜索（findCustomerData）内嵌的getCustomerDatatRPC 结果对象——判定条件是对象中包含usageFourHourPercentage、usageMonthPercentage，或同时包含subscription与usageBand的字典，找到后解码为T3ChatCustomerData结构体。这种 "扫描 + 深度查找" 策略让解析器对 tRPC 外层包装结构（batch 数组、result 包装等）的细微变化有一定容忍度，但也意味着上游彻底改变字段命名时仍会失败。

字段到用量窗口的映射

时间戳的归一化规则：T3ChatUsageSnapshot.date(fromMilliseconds:)中以100 亿（10_000_000_000）为阈值——大于该值按 JavaScript epoch 毫秒除以 1000 处理，否则按 Unix 秒处理。这与文档说明一致，也覆盖了 "T3 Chat 当前返回毫秒，而部分 subscription 字段可能是秒" 的混合情况。

双用量窗口的映射逻辑

映射实现在T3ChatUsageSnapshot.toUsageSnapshot()（T3ChatUsageSnapshot.swift）：

Base 窗口（主）：4 小时滚动限流桶，追踪窗口开启以来已消耗的小时级模型生成额度的百分比，按 T3 Chat 服务器时钟大约每 4 小时重置。代码中windowMinutes固定为4 * 60，重置时间取usageFourHourNextResetAt，缺失时回退到usageWindowNextResetAt；usageBand非空时拼进重置描述，形成如 "Base - standard" 的标签。

Overage 窗口（次）：月度超量预算，追踪超出套餐包含额度的消费。重置时间只来自活跃订阅的subscription.currentPeriodEnd。这里有一处刻意的防御逻辑（源码注释明确说明）：billingNextResetAt跟踪的是用量窗口重置而非超量账期，因此当订阅元数据缺失时，Overage 的重置时间直接留空（unknown），而不是错误地展示 Base 的重置时间——避免把 4 小时重置误标为月度重置。

次窗口百分比的取值同样带回退：usageMonthPercentage ?? usagePeriodPercentage，最终经min(100, max(0, raw ?? 0))夹紧到 0–100。套餐名planName的生成规则是：优先subscription.productName，否则subTier，并把连字符分隔的各段首字母大写（如team-plan→Team Plan），作为ProviderIdentitySnapshot的loginMethod展示在菜单中。

CLI 用法

# Show T3 Chat usage codexbar usage --provider t3chat # Or use the alias codexbar usage --provider t3-chat codexbar usage --provider t3

别名t3-chat、t3在 T3ChatProviderDescriptor.swift 的ProviderCLIConfig中声明。T3 Chat 不提供 token 成本数据：descriptor 中supportsTokenCost为false，usage --format json输出只包含用量与身份数据，而codexbar cost --provider t3chat不受支持（对应提示 "T3 Chat cost summary is not supported."）。

错误与排障

错误类型集中在T3ChatUsageError（T3ChatUsageSnapshot.swift），HTTP 状态码分支在fetchCustomerData中处理：401/403 映射为invalidCredentials，429 且响应头x-vercel-mitigated: challenge时映射为vercelChallenge，其余状态码包装为apiError("HTTP \(code)")。

排障时还可以利用T3ChatUsageFetcher.debugRawProbe（T3ChatUsageFetcher.swift）：它会打印一次完整探测，包含 cookie 名、转发头、以及subTier、usageBand、四个百分比/重置时间字段的原始值，失败时给出带本地化描述的错误行。对应的解析与请求行为在测试 T3ChatUsageFetcherTests.swift 中有覆盖。

关键文件索引

适用前提与限制

• 自动 cookie 导入依赖 macOS 的浏览器 cookie 读取能力（Full Disk Access / Keychain 授权），其他平台只能使用手动 cURL 粘贴模式；
• 该集成只依赖t3.chat的单个 tRPC 端点，请求默认超时 15 秒；
• T3 Chat 无 token 成本数据，成本类命令与统计（codexbar cost）对该 provider 不可用；
• 由于是非官方集成，input参数、默认请求头与响应字段都可能随上游改版失效，调试时应优先使用 Debug Probe 输出核对原始字段。

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar