RTKrtk gain审计指南从 SQLite 存储到时间序列导出的 Token 节省分析实战【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtkrtk gain是 RTK 内置的节省量审计入口它把每一次命令执行前后的输出字节数换算成估算 token记录到本地 SQLite 数据库并支持按日/周/月聚合、JSON/CSV 导出、配额估算和一键重置。读完本文你将掌握如何读取 RTK 的节省统计、用源码级依据理解其估算原理与数据保留策略并能把rtk gain接入 cron、CI 和数据科学工作流形成可复制的 Token 成本审计方案。一、概览统计数据的存储位置、保留策略与统计范围rtk gain命令提供跨时间段的综合 Token 节省分析。三项基础事实决定了你如何审计数据数据库位置~/.local/share/rtk/history.dbLinux/macOS 数据目录下的rtk/history.db保留策略90 天每次插入记录后自动清理更早的记录统计范围全局跨所有项目、worktree 和 Claude 会话1.1 数据库路径的三级解析从源码结构看路径解析并非写死。get_db_path 的实现按优先级取路径环境变量覆盖、用户自定义目录、最后才是平台默认数据目录data_local_dir()/rtk/history.db。单测test_custom_db_pathsrc/core/tracking.rs 内tests模块验证了这一点设置RTK_DB_PATH环境变量后get_db_path()会返回自定义路径取消设置后回落到以rtk/history.db结尾的默认路径。这意味着你可以为测试环境指定独立数据库例如RTK_DB_PATH/tmp/rtk-test.db rtk git status而不污染真实统计。另外注意数据库启用 WAL 模式PRAGMA journal_modeWAL见 src/core/tracking.rs 的new()初始化批次因此磁盘上会伴随history.db-wal和history.db-shm两个同目录sidecar文件备份时只拷贝主文件即可但拷贝前建议先确保没有写入正在进行。1.2 90 天保留策略的实现保留策略不是定期任务而是插入驱动的清理cleanup_old 在每次record()之后执行以Utc::now() - DEFAULT_HISTORY_DAYS为界对commands和parse_failures两张表分别执行DELETE ... WHERE timestamp ?1。保留天数由 src/core/constants.rs 中的DEFAULT_HISTORY_DAYS常量定义即 90 天。审计含义rtk gain默认只能回答最近 90 天的问题更早的聚合值只能依赖你此前导出的 JSON/CSV 快照。1.3 全局范围与按项目过滤rtk gain的 CLI 定义中还有一个文档速查表未强调的标志-p, --projectsrc/main.rs它把统计范围收窄到当前工作目录。实现上resolve_project_scope 取std::env::current_dir()并canonicalize()得到规范路径随后所有查询get_summary_filtered、get_all_days_filtered等都带上项目过滤条件SQL 里通过project_path ?1 OR project_path GLOB ?2匹配精确路径及其子目录。默认视图的标题会随之显示 RTK Token Savings (Project Scope) 还是 (Global Scope)src/analytics/gain.rs。二、快速参考与完整命令选项2.1 快速参考# 默认摘要视图 rtk gain # 时间序列分解 rtk gain --daily # 自跟踪开始的所有天 rtk gain --weekly # 按周聚合 rtk gain --monthly # 按月聚合 rtk gain --all # 一次性展示全部分解 # 导出格式 rtk gain --all --format json savings.json rtk gain --all --format csv savings.csv # 组合标志 rtk gain --graph --history --quota # 经典视图 附加信息 rtk gain --daily --weekly --monthly # 多种分解同时输出 # 重置全部跟踪数据 rtk gain --reset # 删除前弹出 [y/N] 确认 rtk gain --reset --yes # 跳过确认CI/脚本场景2.2 时间序列标志标志说明输出--daily逐日分解每一天含完整指标--weekly逐周分解按周日—周六周聚合--monthly逐月分解按日历月聚合--all全时间段分解日 周 月合并输出周的定义在源码里有明确落点get_by_week_filtered 使用 SQLite 日期函数DATE(timestamp, weekday 0, -6 days)生成week_start、DATE(timestamp, weekday 0)生成week_end——即以周日为一周起点SQLite 默认周制回退 6 天作为周一。WeekStats 的文档注释也写明 Weeks start on Sunday (SQLite default)。2.3 经典标志仍可用标志说明--graph最近 30 天的 ASCII 柱状图--history最近 10 条命令记录--quota月度配额分析Pro/5x/20x 档位--tier TIER配额档位pro、5x、20x默认 20x从 src/main.rs 的 clap 定义可以看到各标志的短选项与约束-g/--graph、-H/--history、-q/--quota、-t/--tierdefault_value 20x且requires quota即不带--quota单独使用--tier会报参数错误、-d/--daily、-w/--weekly、-m/--monthly、-a/--all、-f/--format默认text、-F/--failures输出解析失败日志src/main.rs 中有对应的参数解析单测、--reset、--yesrequires reset。配额档位的具体取值在 src/analytics/gain.rs 中实现Pro 基线为每月 6,000,000 估算 tokenESTIMATED_PRO_MONTHLY5x 5 倍、20x 20 倍配额保留率 total_saved / quota_tokens × 100。输出末尾还附带提示这是基于 Pro 基线约 44K tokens/5h 的启发式估算真实限额使用滚动 5 小时窗口而非月度上限——因此配额视图应理解为数量级参考不是账单预测。2.4 重置标志标志说明--reset永久删除全部跟踪数据commands parse_failures 两表--yes跳过确认提示用于 CI/脚本警告--reset不可逆。它在单个事务里原子地清空commands与parse_failures两张表——对应 reset_all 的BEGIN; DELETE FROM commands; DELETE FROM parse_failures; COMMIT;。交互式终端下默认弹出[y/N]确认在非交互环境stdin 被管道接管中自动按N处理除非传入--yes。这一行为由 confirm_reset 实现io::stdin().is_terminal()为假时直接返回false并打印 (non-interactive mode, defaulting to N)。2.5 导出格式格式标志适用场景text--format text默认终端展示json--format json程序化分析、API 集成csv--format csvExcel、数据分析、绘图格式分发的处理逻辑在 src/analytics/gain.rsjson走export_json()csv走export_csv()其余值一律回落到终端文本渲染。三、输出示例逐日、逐周、逐月3.1 逐日分解rtk gain --daily Daily Breakdown (3 days) ════════════════════════════════════════════════════════════════ Date Cmds Input Output Saved Save% ──────────────────────────────────────────────────────────────── 2026-01-28 89 380.9K 26.7K 355.8K 93.4% 2026-01-29 102 894.5K 32.4K 863.7K 96.6% 2026-01-30 5 749 55 694 92.7% ──────────────────────────────────────────────────────────────── TOTAL 196 1.3M 59.2K 1.2M 95.6%指标含义Cmds执行的 rtk 命令条数Input来自原始命令输出的估算 tokenOutput经 rtk 过滤后的实际 tokenSavedInput − Output被挡在 LLM 上下文之外的 tokenSave%降低百分比Saved / Input × 1003.2 逐周分解rtk gain --weekly Weekly Breakdown (1 weeks) ════════════════════════════════════════════════════════════════════════ Week Cmds Input Output Saved Save% ──────────────────────────────────────────────────────────────────────── 01-26 → 02-01 196 1.3M 59.2K 1.2M 95.6% ──────────────────────────────────────────────────────────────────────── TOTAL 196 1.3M 59.2K 1.2M 95.6%周的定义周日到周六SQLite 默认周制从周日 00:00 开始。3.3 逐月分解rtk gain --monthly Monthly Breakdown (1 months) ════════════════════════════════════════════════════════════════ Month Cmds Input Output Saved Save% ──────────────────────────────────────────────────────────────── 2026-01 196 1.3M 59.2K 1.2M 95.6% ──────────────────────────────────────────────────────────────── TOTAL 196 1.3M 59.2K 1.2M 95.6%月份格式YYYY-MM日历月。四、导出格式详解4.1 JSON 导出{ summary: { total_commands: 196, total_input: 1276098, total_output: 59244, total_saved: 1220217, avg_savings_pct: 95.62 }, daily: [ { date: 2026-01-28, commands: 89, input_tokens: 380894, output_tokens: 26744, saved_tokens: 355779, savings_pct: 93.41 } ], weekly: [...], monthly: [...] }对照 ExportData / ExportSummary 的 serde 结构可以确认两点细节daily/weekly/monthly字段都带#[serde(skip_serializing_if Option::is_none)]即rtk gain --format json不带时间标志时 JSON 里只有summary不会出现空数组summary中还额外包含total_time_ms与avg_time_ms两个执行耗时字段见 src/analytics/gain.rs可用于分析 rtk 过滤本身的开销分布。适用场景API 集成、自建仪表盘、自动化报告、数据管道摄入。4.2 CSV 导出# Daily Data date,commands,input_tokens,output_tokens,saved_tokens,savings_pct 2026-01-28,89,380894,26744,355779,93.41 2026-01-29,102,894455,32445,863744,96.57 # Weekly Data week_start,week_end,commands,input_tokens,output_tokens,saved_tokens,savings_pct 2026-01-26,2026-02-01,196,1276098,59244,1220217,95.62 # Monthly Data month,commands,input_tokens,output_tokens,saved_tokens,savings_pct 2026-01,196,1276098,59244,1220217,95.62CSV 采用带注释头的分段文件形式# Daily Data/# Weekly Data/# Monthly Data标记各段起点段间以空行分隔。注意 export_csv 实际输出的表头还比上面示例多出total_time_ms,avg_time_ms两列执行耗时下游解析时建议按表头取列而不是硬编码列数。适用场景Excel 分析、Python/R 数据科学、Google Sheets 仪表盘、Matplotlib/seaborn 绘图。五、理解 Token 节省估算原理与计算公式5.1 Token 估算bytes / 4且刻意不内置分词器rtk gain的 token 数按bytes / 4估算实现见 estimate_tokenspub fn estimate_tokens(text: str) - usize { // ~4 chars per token on average (text.len() as f64 / 4.0).ceil() as usize }RTK 按设计不内置真正的分词器嵌入分词器会增加启动开销并且需要为每个模型配备一个分词器、或做按会话的模型查找这些 RTK 都没有实现。由于原始输出和过滤后输出使用同一个估算器百分比结果可靠绝对 token 数是近似值不会与服务商账单上的 token 数精确一致。仓库内单测test_estimate_tokens验证了该比例estimate_tokens(abcd) 1、estimate_tokens(abcde) 2向上取整。5.2 节省量计算Input Tokens estimate_tokens(raw_command_output) Output Tokens estimate_tokens(rtk_filtered_output) Saved Tokens Input - Output Savings % (Saved / Input) × 100Savings %本质是bash 输出的字节比值。这些字节只是输入 token 的贡献者之一而输入 token 又只是账单的一部分输出 token 也计费。这一点与 README.md 中 How Savings Work 一节的表述一致RTK 削减的是agent 读取的 bash 输出该削减在bash 输出 → 输入 token → 总账单的链条上逐级稀释。5.3 典型命令的节省幅度命令Bash 输出削减幅度机制rtk git status77–93%紧凑 stat 格式rtk eslint84%按规则分组rtk jest94–99%只显示失败用例rtk vitest94–99%只显示失败用例rtk find75%树形格式rtk pnpm list70–90%紧凑依赖列表rtk grep70%截断 分组这些百分比衡量的是 bash 输出字节的削减量不是费用削减量。六、源码级数据模型两张表、一个事务6.1 表结构history.db的 schema 在 Tracker::new 中初始化包含两张表commands每次受跟踪命令的执行记录字段包括timestamp、original_cmd原命令如ls -la、rtk_cmd如rtk ls、input_tokens、output_tokens、saved_tokens、project_path、exec_time_ms等并建有(project_path, timestamp)复合索引以支持项目过滤与时间范围查询parse_failures解析失败回退记录raw_command、error_message、fallback_succeeded对应rtk gain --failures视图。--failures视图输出失败总数、恢复率fallback 成功率、出现频率最高的前 10 个失败命令以及最近 10 条明细show_failures是排查哪些命令没有享受过滤的审计入口。6.2 一条值得注意的审计提示默认摘要视图除了 KPI 数字外还会通过hook_check::status()检测 hook 安装状态hook 缺失或过期时向stderr输出[warn] No hook installed — run rtk init -g...提示src/analytics/gain.rs。此外还有一个轻量旁路检测 check_rtk_disabled_bypass扫描最近 7 天的 Claude Code 会话若RTK_DISABLED1前缀命令占比超过 10%会提示运行rtk discover查看明细。做节省审计时这两类提示往往比数字本身更早暴露问题。七、数据库管理7.1 检查原始数据# 位置 ls -lh ~/.local/share/rtk/history.db # 查看 schema sqlite3 ~/.local/share/rtk/history.db .schema # 最近记录 sqlite3 ~/.local/share/rtk/history.db \ SELECT timestamp, rtk_cmd, saved_tokens FROM commands ORDER BY timestamp DESC LIMIT 10 # 库内统计 sqlite3 ~/.local/share/rtk/history.db \ SELECT COUNT(*), SUM(saved_tokens) as total_saved, MIN(DATE(timestamp)) as first_record, MAX(DATE(timestamp)) as last_record FROM commands7.2 备份与恢复# 备份 cp ~/.local/share/rtk/history.db ~/backups/rtk-history-$(date %Y%m%d).db # 恢复 cp ~/backups/rtk-history-20260128.db ~/.local/share/rtk/history.db # 导出用于迁移 sqlite3 ~/.local/share/rtk/history.db .dump rtk-backup.sql由于 90 天保留策略会自动删除旧记录定期导出 JSON/CSV 快照或备份 db 文件是保持长期审计能力的唯一途径。7.3 清理# 手动清理超过 90 天的数据与内置保留策略一致 sqlite3 ~/.local/share/rtk/history.db \ DELETE FROM commands WHERE timestamp datetime(now, -90 days) # 重置全部数据 rm ~/.local/share/rtk/history.db # 下一条 rtk 命令会自动重建数据库八、分析工作流8.1 每周进度跟踪# 每周一生成周报 rtk gain --weekly --format csv reports/week-$(date %Y-%W).csv # 对比本周与上周 rtk gain --weekly | tail -38.2 月度成本分析# 导出月度数据用于预算评审分母 6,000,000 即 Pro 档位月度估算配额 rtk gain --monthly --format json | jq .monthly[] | {month, saved_tokens, quota_pct: (.saved_tokens / 6000000 * 100)}8.3 数据科学分析pandasimport pandas as pd import subprocess # 获取 CSV 数据 result subprocess.run([rtk, gain, --all, --format, csv], capture_outputTrue, textTrue) # 解析每日数据段 lines result.stdout.split(\n) daily_start lines.index(# Daily Data) 2 daily_end lines.index(, daily_start) daily_df pd.read_csv(pd.StringIO(\n.join(lines[daily_start:daily_end]))) # 绘制节省趋势 daily_df[date] pd.to_datetime(daily_df[date]) daily_df.plot(xdate, ysavings_pct, kindline)8.4 Excel 分析导出 CSVrtk gain --all --format csv rtk-data.csv在 Excel 中打开建立数据透视表每日趋势折线图、每周总量柱状图、节省率分布直方图8.5 构建仪表盘# 通过 cron 每日生成仪表盘数据 0 0 * * * rtk gain --all --format json /var/www/dashboard/rtk-stats.json # 静态页面展示chart.js 自行本地部署避免外部依赖 cat index.html EOF script srcchart.umd.js/script canvas idsavings/canvas script fetch(rtk-stats.json) .then(r r.json()) .then(data { new Chart(document.getElementById(savings), { type: line, data: { labels: data.daily.map(d d.date), datasets: [{ label: Daily Savings %, data: data.daily.map(d d.savings_pct) }] } }); }); /script EOF8.6 GitHub Actions CI/CD 集成# .github/workflows/rtk-stats.yml name: RTK Stats Report on: schedule: - cron: 0 0 * * 1 # 每周一 jobs: stats: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Install rtk run: cargo install --path . - name: Generate report run: | rtk gain --weekly --format json stats/week-$(date %Y-%W).json - name: Commit stats run: | git add stats/ git commit -m Weekly rtk stats git push8.7 Slack 机器人推送import subprocess import json import requests def send_rtk_stats(): result subprocess.run([rtk, gain, --format, json], capture_outputTrue, textTrue) data json.loads(result.stdout) message f *RTK Token Savings Report* Total Saved: {data[summary][total_saved]:,} tokens Savings Rate: {data[summary][avg_savings_pct]:.1f}% Commands: {data[summary][total_commands]} requests.post(SLACK_WEBHOOK_URL, json{text: message})九、故障排查9.1 看不到数据# 确认数据库存在 ls -lh ~/.local/share/rtk/history.db # 检查记录数 sqlite3 ~/.local/share/rtk/history.db SELECT COUNT(*) FROM commands # 执行一条受跟踪命令以生成数据 rtk git status另外确认两点一是 hook 是否安装rtk gain默认视图自带 hook 缺失/过期警告二是若使用过RTK_DB_PATH覆盖检查是否指向了别的文件。9.2 导出失败# 捕获管道错误 rtk gain --format json 21 | tee /tmp/rtk-debug.log | jq . # 使用 release 构建避免调试构建的告警干扰 cargo build --release ./target/release/rtk gain --format json一个容易踩的细节rtk gain属于 RTK 元命令meta commandsrc/main.rs 中明确元命令解析失败时直接展示 Clap 错误绝不回退到从$PATH执行同名命令。因此rtk gain --badtypo会报参数错误而不是执行异常排查导出问题时参数拼写错误是最常见原因。9.3 统计值与账单对不上Token 估算本身是启发式的。需要精确值时用tiktoken交叉验证# 安装 tiktoken pip install tiktoken # 对比估算值 rtk git status output.txt python -c import tiktoken enc tiktoken.get_encoding(cl100k_base) text open(output.txt).read() print(fActual tokens: {len(enc.encode(text))}) print(frtk estimate: {len(text) // 4}) 十、最佳实践定期导出rtk gain --all --format json monthly-$(date %Y%m).json——90 天保留策略下快照是唯一的历史长期凭证趋势分析周对周对比节省率识别优化空间例如某命令 Save% 突然下降往往意味着该命令的输出形态发生了变化命令画像用--history查看哪些命令节省最多用默认视图的 By Command 表看全局 Top 命令与 Impact 条清理前先备份任何手动数据库操作前先拷贝history.dbCI 集成把 JSON 导出接入共享仪表盘跟踪团队整体节省情况。延伸阅读README.md — RTK 完整文档含 How Savings Work 节省口径说明CLAUDE.md — Claude Code 集成指南docs/contributing/ARCHITECTURE.md — 技术架构【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考