d-date/retok

# retok(return-of-token)  **English** | [日本語](README.ja.md) 一款用于分析您的 AI 编程代理使用日志——**Claude Code** 和 **OpenAI Codex CLI**——的 CLI 工具，旨在衡量 **token 效率**、估算成本，并输出具有可操作性的建议。 仅需 Python 3 标准库即可运行——无其他依赖。 ``` ══════════════════════════════════════════════════════════════════════════ retok — Token Efficiency Report (last 30 days / 472 files) ══════════════════════════════════════════════════════════════════════════ ■ Overview Estimated cost $2,119.66 Claude Code / Codex $2,091.00 / $28.66 Cache hit rate 89.4% Cost per prompt $1.593 ... ■ Recommendations ! Re-caching after cache TTL expiry: ~135.0M tokens ($873.49) Returning to a session left idle beyond the cache TTL (usually 1 hour) re-caches the entire context at twice the input rate. ... ``` ## 安装说明 需要 Python 3.7+。无其他依赖。 ``` git clone https://github.com/d-date/retok.git cd retok ./retok ``` 要在任意位置运行它，可以将其软链接到您的 `PATH` 中（软链接会被解析，因此 `locales/` 中的翻译依然有效）： ``` ln -s "$(pwd)/retok" ~/.local/bin/retok # or /usr/local/bin/retok retok ``` 或者，直接获取该脚本——所有功能均可正常使用，但由于缺少 `locales/`，报告将默认输出为英文： ``` curl -fsSLo ~/.local/bin/retok https://raw.githubusercontent.com/d-date/retok/main/retok chmod +x ~/.local/bin/retok ``` ## 使用说明 ``` ./retok # report for the last 30 days ./retok --days 7 # change the window ./retok --project myapp # filter by project name (substring) ./retok --provider codex # only one provider (claude | codex) ./retok --lang en # report language (default: $LANG) ./retok --json # JSON output for other tools ./retok --top 20 # rows in ranking tables ./retok --dirs ~/somewhere/projects # override Claude Code roots ./retok --codex-dirs ~/somewhere/sessions # override Codex roots ``` 默认情况下，它会扫描 `~/.claude/projects`（设置了环境变量时还会包含 `$CLAUDE_CONFIG_DIR/projects`）中的 Claude Code 记录，以及 `~/.codex/sessions` 中的 Codex CLI rollouts。如果您将记录保存在其他位置（多个配置文件、自定义配置目录），请使用 `--dirs` / `--codex-dirs` 传入每个根目录。使用记录会进行全局去重，因此重叠的根目录永远不会被重复计算。 ## 衡量指标 | 指标 | 含义 | |---|---| | 预估成本 | 基于公布的各模型定价表估算的美元成本（见下表） | | 缓存命中率 | `cache_read / (input + cache_read + cache_write)` —— 越高越省钱 | | 每次提示成本 | 每条人类指令消耗的成本 | | Subagent 占比 | subagent（Task/Explore；`/subagents/agent-*.jsonl`）的消耗情况 | | maxCtx | session 内的峰值上下文大小——越大，每次请求的成本就越高 | ## 建议规则 - **Cache TTL 过期** —— 如果在比写入的 TTL（1小时/5分钟，从使用量分布中检测）更长的间隔之后立即出现大量缓存写入（占上下文的绝大部分），这意味着过期的前缀是从头重新缓存的。建议使用 `/compact` / `/clear` - **超大上下文** —— 超过 12 万 token 的 session。建议在任务间使用 `/clear` - **委派不足** —— 主线程中 Read/Grep/Glob 占比较高，但很少使用 subagent - **重试循环** —— 在一个 session 中，同一个 Bash 命令被执行了 5 次以上 - **频繁中断** —— 超过 12% 的提示中出现了 `[Request interrupted by user]`。建议使用更清晰的提示词并采用 Plan Mode - **小型 session 使用高级模型** —— 在 Opus/Fable 级别的模型上进行一次性的问答（Q&A） ## 成本模型 Claude 价格（美元 / 百万 token，截至 2026-06）： | 模型 | 输入 | 输出 | |---|---|---| | Fable 5 / Mythos 5 | $10 | $50 | | Opus 4.x | $5 | $25 | | Sonnet 4.x / 5 | $3 | $15 | | Haiku 4.5 | $1 | $5 | - 缓存读取 = **0.1×** 输入费率 - 缓存写入 = **1.25×** 输入费率（5 分钟 TTL）/ **2×**（1 小时 TTL）——从使用量中的 `cache_creation` 分布检测得出 - 一次 API 响应在记录中会被写入多条条目；使用量通过 `message.id` 进行去重 OpenAI (Codex) 价格（美元 / 百万 token，截至 2026-07）： | 模型 | 输入 | 输出 | |---|---|---| | gpt-5.5 | $5 | $30 | | gpt-5.4 | $2.50 | $15 | | gpt-5.3 / 5.2 (codex) | $1.75 | $14 | | gpt-5.1 / 5.1-codex-max / 5 | $1.25 | $10 | | gpt-5-mini / nano | $0.25 / $0.05 | $2 / $0.40 | - 缓存输入 = **0.1×** 输入费率（无缓存写入溢价）；`cached_input_tokens` 是 `input_tokens` 的子集，在计价前会进行拆分 - 使用量数据来自 `~/.codex/sessions` rollout 文件中的 `token_count` 事件，通过累积 token 计数器进行去重 ## 语言 报告语言优先级依次为 `--lang`、`RETOK_LANG`、然后是 `LC_ALL` / `LC_MESSAGES` / `LANG`，如果均未匹配，则默认回退为英文。 可用语言：`en`（内置）、`ja`、`zh-CN`、`zh-TW`、`ko`、`es`、`fr`、`de`、`pt-BR`。 ### 添加语言 1. 复制 `locales/ja.json` 为 `locales/.json`（符合 BCP 47 规范的标签，例如 `it`、`pt-PT`） 2. 翻译其中的值——请保持 `{placeholders}` 原样 3. 使用 `./retok --lang ` 进行测试，并提交 Pull Request 缺失的键会自动回退为英文，因此部分翻译也是完全可以的。 ## 许可证 [MIT](LICENSE)

标签：Python, SOC Prime, 人工智能, 动态分析, 开发工具, 成本分析, 文档结构分析, 无后门, 用户模式Hook绕过, 逆向工具