企业官网建设流程全解析

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/rtk

rtk gain是 RTK 内置的节省量审计入口：它把每一次命令执行前后的输出字节数换算成估算 token，记录到本地 SQLite 数据库，并支持按日/周/月聚合、JSON/CSV 导出、配额估算和一键重置。读完本文，你将掌握如何读取 RTK 的节省统计、用源码级依据理解其估算原理与数据保留策略，并能把rtk gain接入 cron、CI 和数据科学工作流，形成可复制的 Token 成本审计方案。

一、概览：统计数据的存储位置、保留策略与统计范围

rtk gain命令提供跨时间段的综合 Token 节省分析。三项基础事实决定了你如何审计数据：

• 数据库位置：~/.local/share/rtk/history.db（Linux/macOS 数据目录下的rtk/history.db）
• 保留策略：90 天（每次插入记录后自动清理更早的记录）
• 统计范围：全局，跨所有项目、worktree 和 Claude 会话

1.1 数据库路径的三级解析

从源码结构看，路径解析并非写死。get_db_path 的实现按优先级取路径：环境变量覆盖、用户自定义目录、最后才是平台默认数据目录（data_local_dir()/rtk/history.db）。单测test_custom_db_path（src/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_mode=WAL，见 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, --project（src/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 时间序列标志

周的定义在源码里有明确落点：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 经典标志（仍可用）

从 src/main.rs 的 clap 定义可以看到各标志的短选项与约束：-g/--graph、-H/--history、-q/--quota、-t/--tier（default_value = "20x"，且requires = "quota"，即不带--quota单独使用--tier会报参数错误）、-d/--daily、-w/--weekly、-m/--monthly、-a/--all、-f/--format（默认text）、-F/--failures（输出解析失败日志，src/main.rs 中有对应的参数解析单测）、--reset、--yes（requires = "reset"）。

配额档位的具体取值在 src/analytics/gain.rs 中实现：Pro 基线为每月 6,000,000 估算 token（ESTIMATED_PRO_MONTHLY），5x = 5 倍、20x = 20 倍，配额保留率 =total_saved / quota_tokens × 100。输出末尾还附带提示：这是基于 "Pro 基线约 44K tokens/5h" 的启发式估算，真实限额使用滚动 5 小时窗口而非月度上限——因此配额视图应理解为数量级参考，不是账单预测。

2.4 重置标志

警告：--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 导出格式

格式分发的处理逻辑在 src/analytics/gain.rs：json走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：来自原始命令输出的估算 token
• Output：经 rtk 过滤后的实际 token
• Saved：Input − Output（被挡在 LLM 上下文之外的 token）
• Save%：降低百分比（Saved / Input × 100）

3.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 结构可以确认两点细节：

1. daily/weekly/monthly字段都带#[serde(skip_serializing_if = "Option::is_none")]，即rtk gain --format json（不带时间标志）时 JSON 里只有summary，不会出现空数组；
2. 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.62

CSV 采用"带注释头的分段文件"形式：# 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_tokens：

pub 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) × 100

Savings %本质是bash 输出的字节比值。这些字节只是输入 token 的贡献者之一，而输入 token 又只是账单的一部分（输出 token 也计费）。这一点与 README.md 中 "How Savings Work" 一节的表述一致：RTK 削减的是"agent 读取的 bash 输出"，该削减在"bash 输出 → 输入 token → 总账单"的链条上逐级稀释。

5.3 典型命令的节省幅度

这些百分比衡量的是 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_DISABLED=1前缀命令占比超过 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 commands"

7.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 -3

8.2 月度成本分析

# 导出月度数据用于预算评审（分母 6,000,000 即 Pro 档位月度估算配额） rtk gain --monthly --format json | jq '.monthly[] | {month, saved_tokens, quota_pct: (.saved_tokens / 6000000 * 100)}'

8.3 数据科学分析（pandas）

import pandas as pd import subprocess # 获取 CSV 数据 result = subprocess.run(['rtk', 'gain', '--all', '--format', 'csv'], capture_output=True, text=True) # 解析每日数据段 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(x='date', y='savings_pct', kind='line')

8.4 Excel 分析

1. 导出 CSV：rtk gain --all --format csv > rtk-data.csv
2. 在 Excel 中打开
3. 建立数据透视表：每日趋势（折线图）、每周总量（柱状图）、节省率分布（直方图）

8.5 构建仪表盘

# 通过 cron 每日生成仪表盘数据 0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json # 静态页面展示（chart.js 自行本地部署，避免外部依赖） cat > index.html <<'EOF' <script src="chart.umd.js"></script> <canvas id="savings"></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> EOF

8.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/checkout@v3 - 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 push

8.7 Slack 机器人推送

import subprocess import json import requests def send_rtk_stats(): result = subprocess.run(['rtk', 'gain', '--format', 'json'], capture_output=True, text=True) 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 2>&1 | tee /tmp/rtk-debug.log | jq . # 使用 release 构建避免调试构建的告警干扰 cargo build --release ./target/release/rtk gain --format json

一个容易踩的细节：rtk gain属于 RTK 元命令（meta command），src/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(f'Actual tokens: {len(enc.encode(text))}') print(f'rtk estimate: {len(text) // 4}') "

十、最佳实践

1. 定期导出：rtk gain --all --format json > monthly-$(date +%Y%m).json——90 天保留策略下，快照是唯一的历史长期凭证；
2. 趋势分析：周对周对比节省率，识别优化空间（例如某命令 Save% 突然下降，往往意味着该命令的输出形态发生了变化）；
3. 命令画像：用--history查看哪些命令节省最多，用默认视图的 "By Command" 表看全局 Top 命令与 Impact 条；
4. 清理前先备份：任何手动数据库操作前，先拷贝history.db；
5. CI 集成：把 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