Nightshift 预算追踪内幕：完整解析 rate_limits JSONL 与本地 Token 计数的双源机制

Nightshift 是一款利用你剩余的 Claude / Codex 订阅额度、在夜间自动巡检代码库并产出实用 PR 的开源工具。它最核心的设计之一，就是预算追踪：通过rate_limitsJSONL 与本地 Token 计数两套独立数据源交叉验证，判断今晚还能"安全地"花多少 token。这篇文章带你从数据格式到决策逻辑，完整拆解这套双源机制。

为什么需要"双源"预算追踪 🤔

Nightshift 的哲学是："你的 token 每周会重置，不用白不用"。但"用多少"必须精确——用多了，白天自己的 Codex/Claude 会话可能被限流；用少了，则浪费了本来会过期的额度。

问题在于：没有任何单一数据源能给出完美答案。

所以 Nightshift 的策略是：用官方百分比做预算决策（权威），用本地计数做校准与展示（透明），两套数据都显示出来，让用户一眼看清差异。

数据源一：rate_limits JSONL（权威百分比）

Codex CLI 会把每次会话记录到~/.codex/sessions/YYYY/MM/DD/*.jsonl。其中token_count事件内嵌了 OpenAI 返回的rate_limits对象：

{ "rate_limits": { "primary": { "used_percent": 19.0, "window_minutes": 300, "resets_at": 1738800000 }, "secondary": { "used_percent": 31.0, "window_minutes": 10080, "resets_at": 1739145600 } } }

三个字段各司其职：

• primary：5 小时滚动窗口（window_minutes: 300），对应"每日"维度；
• secondary：7 天滚动窗口（window_minutes: 10080），对应"每周"维度；
• resets_at：窗口重置的 Unix 时间戳，用来计算"还剩几天"。

Nightshift 解析时取最新一条rate_limits记录并缓存，源码在 codex.go。这正是"JSONL"命名的由来——不靠 API，纯靠读本地会话文件就能拿到权威数据。

数据源二：本地 Token 计数（billable 口径）

同一个 JSONL 文件里还有total_token_usage事件，记录了累计 token 数。Nightshift 的本地计数有两个关键细节：

1. 会话内取差值。total_token_usage是会话内累计值，所以 Nightshift 用"最后一个事件 − 第一个事件"得到本次会话的真实贡献；若计数器中途重置出现负值，则回退到最后一次绝对值。逻辑见 codex.go。

2. 只算 billable（计费）token。原始total_tokens包含cached_input_tokens，而缓存 token不计入限流额度——实践中缓存可占输入的 95% 以上，一个显示 6700 万 token 的会话，真实计费可能只有 160 万。Nightshift 的公式是：

billable = (input_tokens − cached_input_tokens) + output_tokens + reasoning_output_tokens

按日期目录扫描会话文件即可高效汇总"今天"和"近 7 天"的用量，详见 codex.go。

双源如何协同：daily / weekly 模式的选择逻辑

真正体现"双源"设计的地方，是GetUsedPercent的优先级策略（codex.go）：

daily 模式：本地优先，rate limit 兜底

• 首选本地 token 计数：今日 billable ÷ (周预算 / 7)。因为 5 小时滚动窗口并不能反映"今天"的真实用量；
• 本地无数据时，回退到primary.used_percent（5h 窗口百分比）。

weekly 模式：rate limit 优先，本地兜底

• 首选secondary.used_percent（7 天窗口百分比）。这是 OpenAI 的实际计费口径，包含服务端缓存、模型发布加成等本地无法感知的因素；
• 无 rate limit 数据时，回退到本地周 token 数除以周预算。

这个看似不对称的策略其实很讲究：周级决策信官方（避免被限流），日级决策信本地（口径对齐）。完整决策流程由 budget.go 中的CalculateAllowance串起来：

可用额度 = 剩余预算 × max_percent − 预留(reserve_percent) − 白天预测用量

Claude 侧的同构设计：stats-cache 与 JSONL fallback

Claude 提供方没有 rate limit，但用了同一套"主源 + fallback"思想（claude.go）：

1. 主源：~/.claude/stats-cache.json的dailyModelTokens——这是 Claude Code 官方聚合的口径，校准器也是按它训练的，保证比例一致；
2. fallback：直接扫描projects/下的会话 JSONL，按 assistant 消息的时间戳累加input_tokens + output_tokens。

注意源码中的注释：JSONL 累加值 ≠dailyModelTokens（Claude Code 有自己的聚合逻辑），所以 JSONL 路径只是近似。Nightshift 会记录本次数值来源（stats-cache或jsonl-fallback），并在nightshift budget输出中用[approx: JSONL fallback]明确标注，避免用户误读精度。

校准系统：用双源数据反推"真实的订阅预算"

订阅用户最大的痛点是：官方根本不告诉你总预算是多少。Nightshift 的 Calibrator 用一个巧妙公式解决它：

inferred_budget = 本地 token 数 ÷ (官方百分比 / 100)

例如：本地测得本周用了 50 万 billable token，rate limit 显示已用 31%，则推断周预算约为500K ÷ 0.31 ≈ 1.6M token。多次快照取中位数、用 MAD 过滤离群值，并按样本数与方差给出 low / medium / high 置信度，实现见 calibrator.go。没有足够样本时，自动回退到配置文件中的weekly_tokens。

这套推断逻辑的完整设计文档值得细读：budget-inference-plan.md。

读懂 nightshift budget 的输出 📊

所有信息最终汇聚到nightshift budget命令，Codex 部分会并排展示双源数据（输出逻辑见 budget.go）：

[codex] Mode: daily Weekly: 1.6M tokens (calibrated, high confidence, 7 samples) Daily: 228.6K tokens Used today: 43.4K (19.0%) Rate limit: 19% primary (5h) · 31% weekly ← 官方权威百分比 Local tokens: 451.9K today · 1.2M this week (billable) ← 本地实测 Nightshift: 185.1K remaining × 80% max = 148.1K − 11.4K reserve = 136.7K available

两行数据若有明显差异，通常说明存在服务端额外缓存、限流加权规则或窗口错位——这正是保留双源显示的价值：既让决策基于官方口径，又给你排查问题的抓手。更完整的格式说明见官方指南 codex-budget-tracking.md。

小结：双源机制的三条经验

1. 权威数据做决策，实测数据做透明：预算决策信服务商的 rate limit，用户展示信本地计数，各司其职；
2. fallback 必须标注：近似值（如 JSONL 扫描）要打上approx标记，让精度差异可感知；
3. 口径差异是特性而非 bug：缓存 token 的处理、滚动窗口与日历的错位，都会造成两源数值不一致，理解公式比迷信单一数字更重要。

想深入了解运行全貌，可以继续阅读 run-lifecycle 指南 与 provider-calibration 文档。