RTK Analytics 模块解析：用 rtk gain、cc-economics 与 session 构建只读节省量仪表盘

RTK（Rust 编写的 CLI 代理）通过压缩常见开发命令的输出，减少进入 LLM 上下文的 token 数量；src/analytics/ 模块则是这套机制的“账房”——它对 tracking 数据库做只读查询，产出三类仪表盘：rtk gain（token 节省量）、rtk cc-economics（结合 Claude Code 花费的成本化估算）和 rtk session（Claude Code 会话的 RTK 采用率分析）。读完本文，你能理解 RTK 各项节省指标的确切含义（尤其是“字节比例而非账单占比”这一关键语义边界）、掌握三个命令的完整用法与导出格式，并了解如何按照模块规范为 analytics 新增一个只读分析视图。

模块定位：只读仪表盘，永不写库

模块定义来自 src/analytics/README.md，它用几段话划清了 analytics 在整个 RTK 中的位置：

• 职责（Owns）：rtk gain（节省量仪表盘）、rtk cc-economics（成本化节省估算）、rtk session（采用率分析），以及对 Claude Code 用量数据的解析（ccusage）。
• 非职责（Does not own）：记录 token 节省是 core/tracking 的事（由 cmds/ 各命令调用）；命令过滤本身属于 cmds/ 模块。
• 边界规则：如果新模块要写 tracking DB，它属于 core/ 或 cmds/，而不属于 analytics。工具特化的分析是允许的——例如 cc_economics 读取 Claude Code 数据完全合规，因为边界是“只读呈现”，而不是“工具无关”。

模块的入口声明在 src/analytics/mod.rs，只有四行：

pub mod cc_economics;
pub mod ccusage;
pub mod gain;
pub mod session_cmd;

对应关系清晰：gain.rs 对应 rtk gain，cc_economics.rs + ccusage.rs 对应 rtk cc-economics，session_cmd.rs 对应 rtk session。

README 还强调了模块的目的与一个必须牢记的语义细节：

Bash output reduction analytics, economic modeling, and adoption metrics. The stored percentages measure output bytes; token counts are bytes / 4 estimates, not billed tokens.

即：存储的百分比度量的是 bash 输出字节 的削减；所有 token 数都是 bytes / 4 的估算值，不是计费 token。这个约束贯穿所有子命令的输出解读，后文会反复出现。

数据底座：tracking 数据库与 bytes/4 估算

analytics 的一切查询都来自 SQLite tracking 库。按 docs/usage/TRACKING.md 的记载：

• 存储位置：Linux 为 ~/.local/share/rtk/tracking.db，macOS 为 ~/Library/Application Support/rtk/tracking.db，Windows 为 %APPDATA%\rtk\tracking.db；
• 保留策略：超过 90 天的记录在每次写入时自动清理，防止数据库无限增长；
• 核心表 commands 的字段包括 timestamp（RFC3339 UTC）、original_cmd、rtk_cmd、input_tokens、output_tokens、saved_tokens、savings_pct、exec_time_ms，并对 timestamp 建了索引。

数据流是单向的：命令执行时由 TimedExecution::track() 调 Tracker::record() 写入；analytics 侧只通过 Tracker 的聚合 API（get_summary_filtered、get_all_days_filtered、get_by_week_filtered、get_by_month_filtered 等，见 src/core/tracking.rs）读取。

token 估算公式（与 docs/guide/analytics/gain.md 一致）：

Input Tokens  = estimate_tokens(raw_command_output)
Output Tokens = estimate_tokens(rtk_filtered_output)
Saved Tokens  = Input - Output
Savings %     = (Saved / Input) × 100

RTK 刻意不内置真实 tokenizer：那会增加启动开销，且需要逐模型选择 tokenizer 或按会话查模型，RTK 均不实现。因为原始输出与过滤后输出使用同一估算器，百分比是可靠的；绝对 token 数是近似值，不会与供应商账单吻合。bash 输出只是输入 token 的一个来源（还有你的 prompt、系统提示词与对话历史），而输入 token 也只是账单的一部分——所以 savings_pct 是一个 bash 输出字节比，不是费用占比。

rtk gain：节省量仪表盘

rtk gain 的实现位于 src/analytics/gain.rs，run() 函数签名即完整参数表：

pub fn run(
    project: bool,   // --project：按当前项目作用域过滤
    graph: bool,     // --graph：近 30 天 ASCII 图
    history: bool,   // --history：最近 10 条命令
    quota: bool,     // --quota：月度配额节省估算
    tier: &str,      // -t pro | 5x | 20x
    daily: bool,     // --daily
    weekly: bool,    // --weekly
    monthly: bool,  // --monthly
    all: bool,      // --all：一次输出全部时间维度
    format: &str,   // --format text | json | csv
    failures: bool, // --failures：解析失败统计
    reset: bool,    // --reset：清零统计
    yes: bool,      // --yes：跳过 reset 确认
    _verbose: u8,
) -> Result<()>

快速参考

# 默认汇总
rtk gain

# 时间维度
rtk gain --daily          # 全部有数据的天
rtk gain --weekly         # 按周聚合（周日起始）
rtk gain --monthly        # 按月聚合
rtk gain --all            # 一次输出全部维度

# 视图增强
rtk gain --graph          # ASCII 图，近 30 天
rtk gain --history        # 最近 10 条命令
rtk gain --quota          # 月度配额节省估算
rtk gain --quota -t pro   # 使用 Pro 档 token 预算做估算

# 导出
rtk gain --all --format json > savings.json
rtk gain --all --format csv  > savings.csv

# 作用域与诊断
rtk gain --project        # 只看当前项目的记录
rtk gain --failures      # 解析失败率与恢复率
rtk gain --reset --yes   # 清零（有确认交互）

默认汇总视图

不带时间标志时输出 KPI 式汇总：Total commands、Input tokens、Output tokens、Tokens saved（含平均节省率）、Total exec time，外加一个 Efficiency meter 进度条。命令名为空数据时会提示 "No tracking data yet."。

“By Command” 表按节省量排序展示 Top 命令（命令、次数、Saved、Avg%、Time、Impact 迷你条），百分比按阈值着色：>=70% 绿色加粗、>=40% 黄色、其余红色（见 src/analytics/gain.rs 的 colorize_pct_cell）。所有着色都是 TTY 感知的——非终端（管道/重定向）下自动退化为纯文本，这对脚本化使用很重要。

汇总视图还会输出三类健康警告（写到 stderr，不污染 stdout 数据流）：

1. Hook 状态检查（hook_check::status()）：hook 缺失或过时时提示运行 rtk init -g——hook 失效会让节省“静默归零”；
2. RTK_DISABLED 滥用扫描（check_rtk_disabled_bypass，src/analytics/gain.rs）：扫描最近 7 天的 Claude Code 会话（超过 200 个会话则跳过以免拖慢），若带 RTK_DISABLED=1 前缀的 bash 命令占比超过 10%，提示运行 rtk discover 查看被绕过的命令；
3. 未信任过滤器警告：来自 hooks::trust，提示有 N 个自定义过滤器因未信任而未生效，建议 rtk trust。

--history 追加 “Recent Commands” 列表，每条带节省档位符号：▲（≥70%）、■（≥30%）、•（其余）。

时间维度视图与导出

--daily/--weekly/--monthly/--all 走 print_period_table 统一渲染，列含义（与 docs/guide/analytics/gain.md 一致）：

列	含义
Cmds	执行的 RTK 命令数
Input	原始命令输出的估算 token（bytes / 4）
Output	过滤后的估算 token（bytes / 4）
Saved	Input − Output
Save%	Saved / Input × 100，bash 输出字节比，不是账单占比

周视图按周日起始的周聚合，月视图按日历月聚合。

JSON 导出结构（ExportData，src/analytics/gain.rs）：

{
  "summary": {
    "total_commands": 196,
    "total_input": 1276098,
    "total_output": 59244,
    "total_saved": 1220217,
    "avg_savings_pct": 95.62,
    "total_time_ms": 0,
    "avg_time_ms": 0
  },
  "daily":   [ /* DayStats，按 --daily 或 --all 出现 */ ],
  "weekly":  [ /* WeekStats */ ],
  "monthly": [ /* MonthStats */ ]
}

未请求的维度通过 #[serde(skip_serializing_if = "Option::is_none")] 自动省略。CSV 导出则分三段输出，每段带注释头与表头，例如 daily 段：

# Daily Data
date,commands,input_tokens,output_tokens,saved_tokens,savings_pct,total_time_ms,avg_time_ms
2026-02-03,42,15420,3842,11578,75.08,8450,201

这意味着 CSV 是“多表拼接”格式，用 pandas 消费时按 # Daily Data 等标记切段即可（guide 中给出了完整示例）。

配额估算（--quota）

--quota 把累计节省的 token 表示为月度订阅预算的占比。源码（src/analytics/gain.rs）中三档预算为硬编码估算：

档位	月预算（估算 token）	说明
pro	6,000,000	Pro（约 $20/月）基线，约 44K tokens / 5 小时
5x	30,000,000	Max 5×（约 $100/月）
20x	120,000,000	Max 20×（约 $200/月）

代码输出中明确声明这是启发式估算，实际限额使用滚动 5 小时窗口而非月度上限；且如 guide 所强调，它与所有 rtk gain 数字一样源自 bytes / 4，应视为数量级参考而非账单预测。

解析失败诊断（--failures）与重置（--reset）

--failures 走 show_failures()（src/analytics/gain.rs），展示总失败数、恢复率（fallback 成功占比）、按频率排序的 Top 命令，以及最近 10 条失败记录（含 ok/FAIL 状态与 16 字节安全截断的时间戳前缀）。--reset 清空全部统计，交互确认默认 No，非交互（管道）环境直接视为拒绝，需显式 --yes。

rtk cc-economics：把节省量换算成成本

rtk cc-economics（src/analytics/cc_economics.rs）是 analytics 中“工具特化”的样板：它把 ccusage（Claude Code 花费侧数据）与 RTK tracking（节省侧数据）按周期关联合并，产出双指标经济报告。

数据来源：ccusage 解析层

解析层在 src/analytics/ccusage.rs。它优先使用 PATH 中的 ccusage 二进制，不存在时回退到 npx --yes ccusage（先探测 --help 是否可用），对 ccusage 完全缺失的情况做优雅降级。它解析日/周/月三种粒度的 JSON，其中 CcusageMetrics 结构保留了输入、输出、缓存写入、缓存读取四类 token 及总成本：

pub struct CcusageMetrics {
    pub input_tokens: u64,
    pub output_tokens: u64,
    pub cache_creation_tokens: u64,
    pub cache_read_tokens: u64,
    pub total_tokens: u64,
    pub total_cost: f64,
}

一个值得注意的兼容性细节：新旧版 ccusage 的周期字段名不同（date/week/month → period），解析结构体用 #[serde(alias = "period")] 同时接受两种命名（src/analytics/ccusage.rs）。

核心算法：加权输入 CPT

合并后每个周期（PeriodEconomics）计算三类成本换算：

1. 加权输入 CPT（主指标）：利用 Claude API 的价格比（源码注释标注 2026-02 验证，适用于 ≤200K 上下文的 Claude 模型）：

const WEIGHT_OUTPUT: f64 = 5.0;      // 输出 = 5× 输入
const WEIGHT_CACHE_CREATE: f64 = 1.25; // 缓存写 = 1.25× 输入
const WEIGHT_CACHE_READ: f64 = 0.1;    // 缓存读 = 0.1× 输入

加权单位 = input + 5×output + 1.25×cache_write + 0.1×cache_read，再用 总成本 / 加权单位 推出“等效输入单价”，节省金额 = rtk_saved_tokens × 该单价。这是默认展示的 Savings 列——它把“省下的 bash 输出 token”按输入 token 的价格口径折算成美元。

2. Blended CPT（参考，偏低估）：成本 / 总 token（含缓存）。缓存读占大头时分母被稀释，会低估。

3. Active CPT（参考，高估）：成本 / (input + output)。忽略了廉价缓存 token，会高估。

后两者仅在 --verbose 下展示，并在输出中明确标注 OVERESTIMATES / UNDERESTIMATES。

周期对齐的坑：周六变周一

周视图的合并有个巧妙的修正：ccusage 的周起始是 ISO 周一，而 RTK tracking 的历史约定是周六起始。merge_weekly 调用 convert_saturday_to_monday()（周六 +2 天 = 周一）把 RTK 侧的 key 对齐到 ISO 周一再入表（src/analytics/cc_economics.rs），并有单元测试锁定 2026-01-18 (Sat) -> 2026-01-20 (Mon) 的行为。合并本身基于 HashMap<String, PeriodEconomics>，任一侧缺失的字段都是 Option，天然支持“只有花费没有 RTK 数据”或反向的单侧场景。

用法与输出

rtk cc-economics                  # 月度汇总视图
rtk cc-economics --daily          # 逐日
rtk cc-economics --weekly         # 逐周
rtk cc-economics --monthly        # 逐月
rtk cc-economics --all            # 全部
rtk cc-economics --all --format json > economics.json
rtk cc-economics --all --format csv > economics.csv

汇总视图打印 Claude Code 花费、四类 token 明细、RTK 命令数、节省 token 数，以及折算后的美元节省（含占花费百分比）。CSV 导出列包括 period,spent,input_tokens,output_tokens,cache_create,cache_read,active_tokens,total_tokens,saved_tokens,weighted_savings,active_savings,blended_savings,rtk_commands——三种口径的节省金额都落在列里，方便自行交叉验证。测试（同文件 mod tests）覆盖了双指标计算、零 token 边界、单侧数据合并与排序等路径。

rtk session：Claude Code 采用率分析

rtk session（src/analytics/session_cmd.rs）回答另一个问题：你的 Claude Code 会话里，有多少 bash 命令实际上走了 RTK？

流程：

1. 通过 ClaudeProvider::discover_sessions(None, Some(30)) 发现最近 30 天的会话 JSONL；
2. 过滤掉 subagent 文件（路径含 subagents），按修改时间降序取前 10 个；
3. 对每个会话提取 bash 命令，用 count_rtk_commands() 统计“被覆盖”的命令：命令以 rtk 开头，或者按 classify_command() 判定会被 hook 重写为 RTK 命令（Classification::Supported）。链式命令（如 cd ./path && rtk ls）先用 split_command_chain 拆分再逐段判定，与 discover 模块行为一致——这个判定复用 src/discover/ 的规则注册表；
4. 输出表含 Session ID（8 字符前缀）、日期（Today/Yesterday/Nd ago）、Cmds、RTK 数、Adoption 百分比与 @ 进度条、输出 token 量，最后一行给出平均采用率，并提示运行 rtk discover 寻找遗漏机会。

adoption_pct = rtk_cmds / total_cmds × 100，分母为 0 时安全返回 0。

与 discover 的分工：已省下的 vs 漏掉的

analytics 只呈现“已发生”的指标。若想计算那些绕过 RTK 运行的命令“损失”了多少 token，那是 rtk discover 的职责（见 docs/guide/analytics/discover.md 与 src/discover/README.md）——rtk session 的输出尾部也会给出这条提示。两个模块共享 discover/ 的会话解析与命令分类基础设施，但 discover 做的是“反事实”扫描，不属于 analytics 的只读呈现范畴。

开发指南：如何新增一个 analytics 视图

README 给出的四步扩展流程（src/analytics/README.md）值得原样保留：

1. 在 src/analytics/ 下新建 *_cmd.rs 文件；
2. 通过 core/tracking 现有的 TrackingDb API 查询所需指标；
3. 在 src/main.rs 的 Commands 枚举中注册命令（现有注册点：analytics::gain::run(...)、analytics::cc_economics::run(...)、analytics::session_cmd::run(...)，均在 main.rs 的命令分发处）；
4. 添加 #[cfg(test)] 单元测试，使用样例 tracking 数据。

并重申约束：analytics 模块对 tracking 数据库只读，永不修改它。若要写库，模块应放在 core/ 或 cmds/。这个约束在源码中可以被验证——gain.rs 等文件全部经由 Tracker 的 get_* 查询方法访问数据，唯一例外是 --reset 显式调用 tracker.reset_all()，而这属于用户显式请求的维护操作。

小结：语义边界决定指标解读

回顾 src/analytics/README.md 的定义，analytics 模块的价值在于三点收敛：

• 单一数据源：所有节省指标来自同一个 SQLite tracking 库，由 core/tracking 写入、analytics 只读消费，聚合口径（bytes / 4、savings_pct 语义）全局一致；
• 多视角呈现：gain 给 token 视角，cc-economics 给成本视角（用 API 价格比折算，主指标为加权输入 CPT），session 给采用率视角；
• 诚实的不确定性：从 “bytes/4 不是计费 token” 的声明，到 quota 的“数量级参考”标注，再到 blended/active CPT 的高低估标签，每个可能误导的输出处都有显式免责声明。

如果你要基于这些指标做仪表盘或 CI 报表，最稳妥的姿势是：用 rtk gain --all --format json / rtk cc-economics --all --format json 取数，按本文的字段语义（尤其 savings_pct 是 bash 输出字节比）解读，并避免把估算 token 数直接对账到供应商账单。