Loringtonian/usage2

# 使用方法2 一个 Claude Code 技能，能让智能体**可视化自身令牌消耗**——包括令牌计数、等效API美元成本、滚动5小时/7天配额窗口的百分比、子智能体归属，以及A/B比较工作流。 **面向Claude Code订阅用户**（Pro / Max 5x / Max 20x）。它报告的美元数字是*等效API成本*——如果在计量式API访问下，相同令牌会产生多少费用。您实际上支付的是固定月费。该技能旨在揭示两者之间的差距：您正在从中提取多少价值、价值流向何处，以及您距离所在等级硬限制的远近。 **核心目标**：让Claude Code智能体能够**自我评估令牌效率、规划高效的会话使用，并使令牌消耗可预测**。监控——令牌计数、美元成本、配额百分比——是手段；最终目标是让智能体能够自行回答“剩余多少会话预算”、“此操作将消耗多少成本”以及“方案A是否比方案B更经济”，并根据答案采取行动。该技能附带经验测量的各模型会话预算（[`research/per_model_cost_v5.md`](/.jsonl`。将其汇总可得到权威的逐操作归属。耗时约10毫秒。 2. **`/usage` 面板**——通过一个由tmux驱动的临时 `claude` 实例进行抓取。返回滚动5小时/7天/仅限Sonnet的配额百分比重置时间。缓存10分钟。耗时约12秒。 3. **校准历史**——每次配额捕获都与尾随窗口的令牌总数配对，因此 `usage2` 可以被动地随时间学习您所在等级每百分比对应的令牌数。经过≥2次采样后，它可以估算“这个50K令牌的操作将占您会话的约1%”。 ## 目标用户 适用于那些**在订阅制下使用Claude Code进行长时间自主工作**，并且希望智能体自身能够： - **实时推理令牌效率**——“我在该子智能体上消耗了50K令牌；这值得吗？实际消耗流向何处——输入、输出还是缓存写入？” - **运行A/B令牌实验**——“原生分辨率的图像是否真的比调整为1024×1024消耗更多令牌？标记两者，运行，检查差异。” - **在长时间运行中自我节流**——“每10分钟，运行 `/usage2 quick`。当会话达到75%或缓存命中率降至60%以下时暂停。” - **将成本归因于选择**——*哪个*子智能体分派，使用哪个提示词，消耗了多少哪个模型的令牌。 - **查看正在提取的价值**——“今天的会话相当于121美元的API等效价值——仅这次运行，我就获得了订阅费18倍的回报。” - **知道何时停止**——智能体可以看到自身会话和每周的百分比及重置时间，并决定是继续推进还是交还。 这将配额和令牌成本从用户必须照看的外部约束，转变为智能体可以自行推理的信号。 ## 订阅等级 | 等级 | 月费 | 说明 | |-------------|--------|---------------------------------------------------------------| | Pro | $20 | 入门等级 | | Max 5x | $100 | Pro配额信封的5倍 | | Max 20x | $200 | Pro配额信封的20倍 | Anthropic不公布各等级确切的令牌上限——`usage2` 通过校准经验性地学习它们。设置您的等级，以便“订阅价值百分比”行具有意义： ``` python3 meter.py tier max20x # or max5x, or pro ``` 此技能**不适用于API用户**——如果您使用计量式付费，您自己的账单页面更准确。这里的重点是弥补订阅定价所造成的可见性差距。 ## 包含内容 - **`meter.py`** — Python脚本（仅标准库）。包含以下所有模式。 - **`capture.sh`** — Bash + tmux，用于捕获内置的 `/usage` 面板（此技能的原始v1版本）。 - **`SKILL.md`** — Claude Code技能描述文件。 无需npm，无Python依赖，无API密钥。 ## 模式 | 模式 | 用途 | 成本 | |----------------------------|----------------------------------------------------------------------|---------| | `summary`（默认） | 令牌 + $ + 会话百分比 + 周百分比 + 校准 + 信号 | ~12秒* | | `quick` | 单行：令牌 · $ · 缓存% · 会话% · 周% | ~10毫秒 | | `agents` | 按子智能体归属（仅前台子智能体——见注意事项） | ~10毫秒 | | `mark <名称>` `[--quota]` | 保存检查点，可选择包含配额快照 | ~10毫秒/~12秒 | | `since <名称>` | 自检查点以来的令牌 + $ + 配额Δ | ~10毫秒 | | `marks` | 列出已保存的检查点 | ~1毫秒 | | `drop <名称>` | 删除检查点 | ~1毫秒 | | `raw` | 所有内容的JSON转储（供下游工具使用） | ~10毫秒 | | `quota` | 强制刷新配额面板 + 显示解析结果 | ~12秒 | | `sample` | `quota` 的别名（强制捕获 + 写入校准报告） | ~12秒 | | `calibrate` | 显示从干净（未污染）报告推导的 $/pp | ~1毫秒 | | `calibrate-account-scope` | 来自按时间顺序配对增量的 $/pp（适用于受污染数据） | ~1毫秒 | | `estimate --model X --tokens N [--bucket B]` | 计划操作的成本及会话/周百分比 | ~1毫秒 | | `reports` | 列出已保存的报告（自己的 + 众包的） | ~1毫秒 | | `contribute` | 打印匿名JSON以共享到公共仓库 | ~1毫秒 | | `reset-calibration` | 归档 `reports/` 以重新开始（例如，在限制更改后） | ~1毫秒 | | `tier [<等级>]` | 显示或设置订阅等级（pro / max5x / max20x） | ~1毫秒 | \* `summary` 在上一次配额捕获后10分钟内调用会复用缓存的百分比，并在约10毫秒内运行。 ### 标志 - `--no-quota` — 在 `summary` / `since` 中，跳过配额刷新并使用10分钟缓存。 - `--crowd` — 在 `summary` / `calibrate` / `since` 中，同时合并众包报告。 - `--quota` — 在 `mark <名称>` 中，在标记时捕获配额快照，以便 `since` 稍后可以报告面板百分比变化。 ## A/B工作流 ``` python3 meter.py mark approach-A --quota # ... 代理执行方法 A ... python3 meter.py since approach-A python3 meter.py mark approach-B --quota # ... 代理执行方法 B ... python3 meter.py since approach-B ``` 每个 `since` 报告消耗的令牌、等效API美元增量，以及（因为标记时保存了 `--quota` 快照）每个滚动窗口的百分比点变化。智能体比较两个增量，并告诉您哪种方法更经济、相差多少，以及差异所在（输入？输出？缓存？）。 ## 校准：经验性学习您的等级 Anthropic不公布各等级的令牌上限。因此 `usage2` 来学习您的上限： ``` python3 meter.py sample # take a sample now # ... 大约 15 分钟以上并产生一些实际使用量后 ... python3 meter.py sample # take another python3 meter.py calibrate # uses only clean (non-contaminated) reports python3 meter.py calibrate-account-scope # uses chronological pair-deltas — works on contaminated data too python3 meter.py estimate --model opus --tokens 1m # plan a specific action ``` 每次采样存储 `(配额百分比, 尾随5小时美元数, 尾随7天美元数)`。经过≥2次采样后，任一校准模式都通过连续配对斜率（为稳健性取斜率中位数）推导 $/pp。 **两种模式，两种用例：** - **`calibrate`** 仅使用采样期间账户为单实例的报告。信号最干净，但如果您通常运行多个Claude Code会话，可能没有可用报告。 - **`calibrate-account-scope`** 使用**所有**按时间顺序相邻的报告对，包括受污染的。前提：面板百分比反映的是整个账户的消费，因此账户范围的美元数与账户范围的面板变化之比在并行会话数量多少的情况下都有效。如果您运行多个会话，强烈推荐使用此模式。 **经验上限**（2026-05-19的Max 20x）通过 `claude -p` 子进程直接测量，每模型面板分辨率至少10个百分点。完整方法：[`research/per_model_cost_v5.md`](/` 中最近修改的 `*.jsonl` 文件。 3. **记录扫描** — 流式读取JSONL。每个 `type:"assistant"` 记录（`isSidechain` 为假）贡献 `message.usage`；每个带有 `toolUseResult.agentType` 的 `type:"user"` 记录是子智能体分派，贡献 `totalTokens` + `usage`。 4. **各模型费率** — `meter.py` 中的 `RATES` 字典反映了Anthropic的公开API定价。每轮成本根据其声明的模型计算。子智能体成本使用按 `agentType` 的模型假设。 5. **配额捕获** — `capture.sh` 在分离的tmux会话中启动 `claude`，关闭信任提示，发送 `/usage`，通过 `tmux capture-pane -p` 捕获渲染的面板。`meter.py` 解析百分比和重置时间。 6. **校准** — 每次配额捕获都与从记录推导的尾随窗口令牌总数配对。历史文件累积样本；每百分比令牌数是连续配对斜率的中位数。 ## 注意事项 - **并行Claude Code会话会扭曲*单会话*校准，但不会扭曲账户范围校准。** 当您在同一账户上并行运行多个CC实例时，面板百分比反映的是*整个账户*。`calibrate` 过滤出干净（未污染）的报告。`calibrate-account-scope` 适用于完整的报告集，因为账户范围的美元数 + 账户范围的面板变化仍然是一致的。污染标志现在使用“最近120秒内修改”（当前处于活动状态），而不是“在滚动窗口内任意位置修改”（后者会错误地将今天早上的历史残留标记为污染）。跨设备使用（claude.ai网页、其他机器）对于本地计量器仍然不可见；面板能看到它，计量器不能。 - **正在处理的轮次尚未写入JSONL。** 计量器总是比实时状态落后一个轮次。适用于轮次间的轮询。 - **子智能体归属仅限前台且低估每次生成的成本。** `agents` 模式仅为*前台*（非后台）Agent分派显示每次生成的成本——数据源是 `toolUseResult.totalTokens`，后台智能体不会在父级JSONL中填充它。后台子智能体仍然消耗真实配额（面板会计入）；它们只是没有出现在 `agents` 中。**更重要的是：** 显示的每次生成成本仅为子智能体自身的令牌。子智能体的*返回*将成为父智能体下一轮的 `cache_write_1h`，按父智能体的模型速率（在交互式Claude Code中始终为Opus），通常为子智能体自身成本的10–30倍。对于按模型的A/B测试，请改用 `claude -p --model X` 子进程——演示见 [`research/per_model_cost_v3.md`](research/per_model_cost_v3.md)。 - **钩子不单独归属。** 它们注入的上下文会出现在下一个助手轮次的输入计数中。 - **“订阅费天数”行仅供参考** — 它代表提取的等效API价值，而不是您实际支付的金额。 - **校准需要≥2次采样**，分布在足够的使用量上以观察到实际变化。Anthropic的配额窗口是滚动重置的；采样间隔太近可能会产生噪声斜率。 - **API费率可能会变化。** `RATES` 是硬编码的；当Anthropic公布新定价时更新。 ## 许可证 MIT。见 `LICENSE`。 ## 背景 于2026年5月构建，试图解决个人媒体归档项目中的一个令牌效率问题（照片上的传记细节子智能体：原生分辨率 vs 1024×1024？），并发现智能体无法回答。v1是内置 `/usage` 面板的tmux抓取。v2添加了来自会话记录的逐操作令牌归属。v3添加了等效API美元成本、按等级框架和被动校准。v3–v5是经验性研究轮次（`research/`），直接通过 `claude -p` 子进程测量Max 20x等级的实际会话上限。关键点——Claude Code已经将权威的逐消息使用块写入本地JSONL文件——是通用的：任何“让智能体看到它目前在Claude Code中看不到的东西”的问题可能都有类似的本地文件解决方案。

标签：A/B比较, AI代理管理, API等效成本, Claude Code技能, Token效率优化, 代理行为控制, 众包校准, 会话管理, 使用历史, 历史报告, 应用安全, 成本分析, 效率优化, 校准机制, 模型预算, 监控工具, 自我节流, 自我评估, 订阅用户优化, 资源监控, 逆向工具, 配额跟踪