Codex 用量账本 · Codex Usage Ledger
把一个本地 Codex deeplink 解析成 thread ID,以只读方式检查 SQLite 快照和 rollout JSONL,给出整个线程、最新计数段和 token 类型的可核验统计。
Triggers
Activate when
- 用户说“查这个 Codex 任务消耗”“这个 deeplink 用了多少 token”或“统计 thread tokens”。
- The user asks to “inspect Codex thread usage” or “calculate tokens for this Codex deeplink”.
- 输入是
codex://threads/<uuid>或 Codex thread UUID,并要求 token 明细或统计口径。
Do not activate when
- 用户询问账户订阅额度、五小时/周限额或 reset credits;这些是账户 rate limit,不是单线程 token 统计。
- 用户要求估算 API 账单金额;本 Skill 不内置会变化的模型价格,也不把 cached token 当作免费 token。
- 用户只想打开或导航到 deeplink;应使用宿主的任务导航能力。
User Profile (cross-session)
Read skill.yaml on every run and resolve the shared user-profile/v1 context.
Current request and explicit flags take precedence over Skill records and shared
preferences. Persist only direct durable user statements through
scripts/profile_store.py; never persist thread IDs, transcripts, credentials,
or inferred private paths.
Skill Group Composition
Read references/skill-composition.md before composing adjacent capabilities.
This Skill owns the local deeplink-to-usage result and has no required sibling
Skill dependency.
Workflow (MANDATORY)
Step 0: Resolve runtime
- Resolve
SKILL_DIRfrom the active Skill context. - Read
skill.yaml,references/token-semantics.md, andreferences/skill-composition.mdcompletely. - Confirm Python 3.9+ and
scripts/codex_thread_usage.pyare available.
Step 1: Restate the requested metric
Distinguish these values before reporting:
historical.total_tokens: processed input plus output across all detected monotonic counter segments in the rollout.state_snapshot.tokens_used: the most recent SQLite cumulative snapshot; it can reset after resume or a new Codex process.cached_input_tokens: a subset of input, not an additional quantity.reasoning_output_tokens: a subset of output, not an additional quantity.tui_style_total_tokens: non-cached input plus output; useful for parity with the Codex TUI display, but not a billing estimate.
Step 2: Run the deterministic inspector
Text report:
python3 "$SKILL_DIR/scripts/codex_thread_usage.py" \
'codex://threads/<uuid>' --details
Machine-readable report:
python3 "$SKILL_DIR/scripts/codex_thread_usage.py" \
'<thread-uuid>' --json
Use --codex-home <directory> only when the user explicitly supplies a
non-default Codex data directory. The script reads message envelopes and token
fields but never emits message bodies.
Step 3: Evaluate evidence and boundaries
- Verify the rollout
session_meta.payload.idmatches the deeplink UUID. - Compare
state_snapshot.tokens_usedwith the last segment total. - If there is more than one segment, explain that the SQLite value is only the latest counter, while the historical value sums segment terminals.
- If
estimated_segmentsis nonzero, label the total as accumulated or estimated rather than exact billing usage. - If
raw_response_completed.eventsis nonzero, report it separately; it is exact per event but may be incomplete for older or provider-specific runs.
Step 4: Answer concisely
Lead with historical processed tokens, then show input, cached input, output,
reasoning output, the latest SQLite snapshot, segment/reset count, and quality.
Never add cached or reasoning subsets to total_tokens. Do not infer money or
subscription quota from these fields.
Validation
PYTHONDONTWRITEBYTECODE=1 python3 "$SKILL_DIR/scripts/test_codex_thread_usage.py"
python3 "$SKILL_DIR/scripts/validate_skill.py" "$SKILL_DIR"
The documented activation phrase must route here; “查看 Codex 账户剩余额度” must remain outside this Skill.
Dependencies
- Python 3.9+ standard library only.
- Read access to the local Codex data directory.
- No credentials, network access,
jq, or SQLite CLI required at runtime.
