alexgreensh/token-optimizer

English · 한국어 · 简体中文 · 日本語

砍掉你浪费的 token。留住你本会丢失的工作。

它在后台自动运行。你照常工作。想要全貌时运行审计即可。

30 秒版本

Token Optimizer 砍掉你的 AI 编程助手浪费的 token，让你的工作在会话和压缩(compaction)之间存活，并在实时仪表盘上展示每一美元去了哪里。大部分自动运行。你安装它，运行一次审计，剩下的交给 hook。

为什么不直接用 Headroom 或 RTK? 它们压缩命令输出，只覆盖你上下文的 15-25%。Token Optimizer 覆盖这部分加上另外 75%:臃肿的配置、未使用的 skill、陈旧的记忆、压缩损失、模型误路由、行为浪费。每一项节省都对缓存安全且经过测量。仪表盘在每个会话后自动更新。

Devin 是路线图的下一站。

你得到什么

每个会话自动运行,你什么都不用做:

• 🔄 智能压缩(Smart Compaction):自动压缩前检查点,之后恢复
• 🗄️ 会话连续性(Session Continuity):跨会话提示、冷恢复、检查点评分
• 📦 主动压缩(Active Compression):9 项功能,全部默认开启(delta diff、骨架、bash/搜索压缩、精简输出提示、质量提示、循环检测、活动模式、决策提取)
• 📊 质量评分(Quality Scoring):7 个信号,实时,S–F 字母等级
• 🗃️ 会话数据库(Session Database):SQLite,15 张表,完整审计追踪,零网络
• 🔍 渐进式披露(Progressive Disclosure):大输出归档,按需展开
• 🧠 上下文情报摘要(Context Intel Digest):压缩后无需重读的重新定位
• 🔀 模型路由提示(Model Routing Nudges):引导到适合任务的层级

你主动要求时:

• 🩺 /token-optimizer:带引导修复的完整审计
• 📈 /token-coach:带具体修复的 30 天趋势分析
• ⚡ quick:10 秒健康检查
• 🎯 route:在你花钱之前,这个任务实际需要的模型和力度
• 🔧 doctor:安装检查
• 💰 savings:美元节省报告
• 📋 report:按组件的 token 分解
• 🌐 dashboard:打开完整仪表盘
• 📝 memory-review:MEMORY.md 结构审计
• 📂 expand:检索归档的工具结果
• 🔙 resume-lean:重开一个冷会话

安装,运行一次 /token-optimizer,其余全部自动运行。

Claude 桌面应用里的状态栏

_{30 秒预览。 观看带声音的完整影片（50 秒）。}

Claude Code 现在允许插件添加自己的界面元素，称为 mod。Token Optimizer 用它把会话的健康状况放在输入框正上方：质量等级、上下文已用多少、缓存还能保持多久，以及两项用量限额。一句话告诉你现在需要注意什么，一个按钮就能解决。橙色的小吉祥物 Clawd 会演出会话正在做的事，让你一眼看出 Claude 是在阅读、编辑、等待你的许可，还是已经完成。

它随插件一起提供，无需额外安装。了解详情。

安装

Claude Code(推荐):

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer

然后在 Claude Code 中:/token-optimizer

安装后请启用自动更新。 Claude Code 默认以自动更新关闭来分发第三方市场。/plugin → Marketplaces 标签 → 选择 alexgreensh-token-optimizer → Enable auto-update。一次性,10 秒。

安装后,运行一次 /token-optimizer 来设置 hook。此后一切自动运行:压缩、检查点、质量评分、仪表盘更新。除非你想要审计,否则无需再运行任何命令。

codex plugin marketplace add alexgreensh/token-optimizer

{ "$schema": "https://opencode.ai/config.json", "plugin": ["token-optimizer-opencode"] }

openclaw plugins install github:alexgreensh/token-optimizer

git clone https://github.com/alexgreensh/token-optimizer.git
token-optimizer/install.sh --hermes

git clone --depth 1 https://github.com/alexgreensh/token-optimizer.git
cd token-optimizer
bash install.sh --copilot

git clone --depth 1 https://github.com/alexgreensh/token-optimizer.git
cd token-optimizer
bash install.sh --cursor

tmp="$(mktemp -d)"
release_json="$(curl -fsSL https://api.github.com/repos/alexgreensh/token-optimizer/releases/latest)"
tag="$(python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])' <<<"$release_json")"
git clone --branch "$tag" --depth 1 https://github.com/alexgreensh/token-optimizer.git ~/.claude/token-optimizer
bash ~/.claude/token-optimizer/install.sh
rm -rf "$tmp"

sed -i 's/\r$//' ~/.claude/token-optimizer/install.sh
# 已经有仓库了?就地重新规范化换行:
git -C ~/.claude/token-optimizer add --renormalize . && git -C ~/.claude/token-optimizer checkout -- .

/plugin uninstall token-optimizer@alexgreensh-token-optimizer

不同之处

大多数 token 工具压缩命令输出。那覆盖你上下文的 15-25%。另外 75% 无人触及。

压缩覆盖面。 Headroom、RTK 和 JFrog Boost 压缩 bash 和命令输出。Token Optimizer 压缩输出栈的八个面。状态:🟢 支持,🟡 部分,🔴 不支持。

RTK 和 Boost 到达第一个面。Headroom 到达第一个和第三个。Token Optimizer 覆盖全部八个,然后继续深入压缩周围发生的事:

• 三种浪费,不是一种。 结构性(臃肿配置、未用 skill、陈旧记忆)、运行时(冗长输出、重读)和行为性(模型误路由、缓存过期、重试循环)。各自如何工作 →
• 节省在压缩中存活。 自动压缩前检查点,之后恢复。没有这个,压缩节省在压缩触发的瞬间消失。
• 测量是否有帮助。 前后 token 差值、跨四个定价层级的美元节省、追踪退化的质量评分。不只是"我们压缩了东西"。
• 零基线开销。 外部进程,上下文中没有常开指令,没有 MCP 服务器,没有依赖,没有遥测。

这十行是 Token Optimizer 是该行唯一 🟢 的行:在压缩之外存活的东西,以及没有压缩器去寻找的浪费。压缩机制、成本和安全,以及我们输的两行在折叠部分之后。

仪表盘

一个 HTML 页面,通过 SessionEnd hook 在每个会话后自动重新生成,无需手动触发。可书签的 URL http://localhost:24842/token-optimizer 是 opt-in:只有在运行 python3 skills/token-optimizer/scripts/measure.py setup-daemon 启动本地服务器后才工作。在那之前,打开 measure.py dashboard 在 Dashboard: 行打印的文件路径。

每轮 token 分解、跨四个定价层级的成本、带 TTL 混合和命中率的缓存分析、叠加在每个会话上的质量评分、子代理成本分解、已计量与估算分开的节省追踪器。安装后零设置。完整仪表盘文档 →

节省什么

截至 2026-11-01 的30天快照，按API价格换算的合计价值约为 $597.72。这是可定价部分的小计。 各组成部分分别标明依据。

• 已记录的动作：$78.59。 4,945 个事件中计量的token变化，按API价格换算。
• 模型路由：$422.88。 使用固定的启用前模型组合和固定参照模型价格表进行估算比较。
• 避免的重复读取：$60.69。 根据实际观测的轮次建模，止于下一次真实压缩，并使用已知的逐轮费率。
• 其他估算：$35.56。 方法学列出全部8个估算类别，包括值为零的类别。

定价覆盖不完整。 未定价的重复读取收益与扣减均未计入，无法确定完整净值。四个组成部分之和与合计一致。

同一快照的token卡显示 节省 24,797,356 个token，其中计量 9,831,072、估算 14,966,284。已用 286,218,848 + 节省 24,797,356 = 311,016,204，节省部分占 约 8%。范围为已记录的token，加上MCP上限、提示引导读取、精简输出和精简恢复的估算（快照基于 v5.13.63 规则生成；检查点恢复此后已移至估算层级）。建模的重复读取与模型路由不计入此token总数；美元小计的范围更广。

基于 1,644 个主要工作会话和 3 个委派会话。仪表盘使用你自己的历史记录计算，结果会有所不同。方法学 →

主动压缩

九项主动减少上下文的功能,全部默认开启,全部自动,全部可从仪表盘或 CLI 切换。

底层,PreToolUse hook 在每次 Read 和 Bash 调用进入你的上下文之前拦截。如果文件已被读取,只返回 diff。如果是代码文件重读,结构骨架替换完整内容。如果是 CLI 命令,输出被压缩。PostToolUse hook 把完整原始归档到磁盘并记录压缩事件到 SQLite。没有东西丢失,一切可检索。你什么都不用做。hook 处理一切。

从仪表盘 Manage 标签、CLI(measure.py v5 enable|disable <feature>)或环境变量切换。v5 动词是控制当前功能的遗留命令名。

阅读每项功能如何工作 →

python3 measure.py compression-stats --days 30

会话数据库

Token Optimizer 所做的一切由两个本地 SQLite 数据库支撑。没有东西离开你的机器。零网络调用。

每会话 DB(~/.claude/token-optimizer/snapshots/session-store/<session>.db)持有 8 张表,追踪文件读取、工具输出、命令输出、缓存内容、上下文情报事件、活动日志、决策日志和提示服务。WAL 模式用于 hook 进程的并发读/写。每会话 50MB 上限。

趋势 DB(~/.claude/token-optimizer/snapshots/trends.db)持有 7 张表,追踪会话历史、每日聚合、skill/模型/子代理使用、节省事件和压缩事件。按会话 UUID 索引以实现 O(log n) 连接。这就是仪表盘、coach 模式和 30 天趋势分析的驱动力。

每个压缩事件、每笔节省、每次质量测量都是一行你可查询的数据。仪表盘是此数据的只读视图。measure.py compression-stats 是一条 SQL 查询。你的数据是你的。

渐进式披露

大型工具结果(>4KB)归档到磁盘并替换为简短预览加检索指针。完整输出在压缩中存活。当模型需要它,通过 expand 拉取原始,无需命令重跑,无丢失输出。

这不只是存储。系统追踪多少结果被归档 vs 重新展开,这样你能看到保持折叠的净 token。重新展开从节省总额中扣除,所以你只算实际保持压缩的。

python3 measure.py expand --list          # 列出归档的工具结果
python3 measure.py expand <tool-use-id>   # 检索特定结果

一些 MCP 工具被文档化为返回大型逐字载荷(来源抓取器、文档检索器),其中元数据预览会破坏要点。把它们加入允许列表,使完整结果到达上下文而非被替换(仍然归档,所以 expand 工作)。设置一个针对完整工具名匹配的 fnmatch glob 的逗号分隔列表:

TOKEN_OPTIMIZER_ARCHIVE_EXEMPT_TOOLS="mcp__context7__*,*github_repository_file"

默认为空,除非你 opt-in 一个工具,否则没有东西被豁免。

会话连续性

压缩很重要,但 Token Optimizer 做的最重要的事是自动让你的工作在会话和压缩之间存活。

当你结束一个会话,Token Optimizer 把你的状态检查点到 SQLite:活动任务、关键决策、修改的文件、git 分支、最近读取。当你开始新会话,它针对你的提示给所有最近检查点评分,并浮现最相关的一个作为提示。你带着上下文恢复,而非从零开始。

自动发生什么:

• 跨会话提示:相关性评分的检查点在你开始新会话时浮现。提示包括前一个会话的任务、决策、文件和分支。全部以 RECOVERED DATA 围栏,绝非指令。
• 冷恢复精简:无需支付完整转录成本重开一个陈旧会话。Token Optimizer 从其检查点重建精简上下文。无 LLM 调用,无完整转录冷恢复。从 SQLite 免 token 重建。
• 提示跟随估算:当连续性提示浮现文件路径而模型随后读取其中一个,Token Optimizer 估算一笔避免的探索性搜索。提示→读取配对是观测到的;回避的探索性搜索规模是固定估算,报告在估算层级,不计入计量合计。

python3 measure.py resume-lean                    # 列出可重开的冷会话
python3 measure.py resume-lean <#|session_id> --print  # 输出精简上下文块

压缩节省只有在你的会话在压缩中存活时才粘住。会话连续性使之发生。

智能压缩

当自动压缩触发,60-70% 的对话消失。决策、错误修复序列、代理状态,全部消失。

Token Optimizer 在压缩前检查点你的会话,并通过 hook 自动恢复摘要丢掉的内容。它还注入一个上下文情报摘要:模型已处理的大型工具输出的启发式摘要(触及的文件路径、见到的错误、行数)。压缩后,模型知道它看过什么而无需重读一切。

活动模式检测用最近 10 次工具调用实时分类你的会话(代码、调试、审查、基础设施、通用)。该模式进入压缩指导,使 PRESERVE/DROP 优先级适配你现在正在做的事,而非通用启发式。

决策提取在决策语句从工具输出发生时捕捉并存入会话 DB。压缩时,这些作为 CRITICAL DECISIONS 注入,摘要必须逐字保留。每会话上限 10 条。

压缩节省只有在你的会话在压缩中存活时才粘住。在 git status 上节省 token,如果下一次自动压缩抹掉让你运行它的决策,就毫无帮助。

python3 measure.py setup-smart-compact    # 检查点 + 恢复 hook

输出 token:精简 vs 冗长

输出 token 是你会话中最昂贵的部分。在 Opus 上它们比输入 token 贵 5 倍,按生成计费而非按缓存读取。对简单问题的冗长回答烧掉你从不需要花的美元。

Token Optimizer 用精简输出提示自动处理这个。当你的上下文填过 25%,一段简短提示告诉模型深度推理但保持可见输出精简。填充是唯一触发;上下文质量不是条件。减少估算为 10-15% 且非反事实计量,所以在估算层级报告,与计量节省分开。

如何工作:

• 提示作为 additionalContext 注入,从不修改现有前缀,所以你的缓存保持完整
• 只在上下文填满时触发,而非你有大量空间时
• 模型仍然思考问题;它只是产生更精简的可见答案
• 今天没有开关;用 TOKEN_OPTIMIZER_VERBOSITY_MIN_FILL(默认 25)调整触发点

这是 9 项主动压缩功能之一,也是节省输出侧的那项,token 在那里最贵。

质量评分

质量评分追踪两件事:资源健康(你离退化悬崖多近)和会话效率(你的 token 是否在做有用的工作)。从 S 到 F 的字母等级让分诊即时。

随着上下文填充,质量下降。MRCR 在 256K 和 1M 上下文之间从 93% 降到 76%。你的 AI 随窗口填充可测量地变笨。质量评分向你展示那何时发生。

状态栏随质量退化变色:绿、黄、橙、红。当质量跌破 75,会话时长作为警告出现。运行的子代理显示其模型和经过时间。

python3 measure.py setup-quality-bar      # 一次性安装

阅读评分如何工作 →

python3 measure.py setup-quality-bar --uninstall

Coach 模式

> /token-coach

告诉它你的目标。拿回具体的、带优先级的修复,附精确 token 节省。它读取你 30 天的会话数据并浮现单个会话无法展示的:质量向下漂移、会话变长、缓存命中率下降、每会话成本攀升。

每个洞察都基于你的真实数字。"你的短会话得分 68 对长会话 60"比"考虑更短的会话"更扎心。Coach 模式还识别项目级优化机会(你从不使用的 skill、急切加载的 MCP 服务器、破坏你缓存的 CLAUDE.md 模式)并教你如何修复,使未来会话从更精简开始。

阅读 Coach 模式 →

python3 measure.py keepwarm-enable          # opt-in(仅 API 计费)
python3 measure.py keepwarm-report            # 净节省、支出、绊线状态
python3 measure.py keepwarm-disable           # 随时 opt-out

python3 measure.py inject-routing --dry-run   # 预览
python3 measure.py inject-routing              # 注入

FAQ

所有命令

许可证

PolyForm Noncommercial 1.0.0,另附书面的小型企业许可。源码可见。

个人 / 爱好 / 研究 / 教育?

放手去做。完整源码,本地运行,无需购买许可证。你自己的开源业余项目也包括在内。关键在于这项工作为谁而做,而不是在哪里运行:为雇主做的工作,即使在家里做,也属于雇主的使用。

小型企业(少于 5 人 且 月收入低于 $20k)?

免费商业许可证,以书面形式授予:LICENSE-SMALL-BUSINESS.md。两个条件都针对整个公司(包括母公司和关联公司),而不是团队或使用人数。大公司里的小团队需要商业许可证。

从个人开始,现在要变成生意了?

你过去的使用完全没问题。不再符合条件后,你有 32 天时间办理商业许可证。

更大的公司 / 商业使用?

联系 Alex Greenshpun 或 [email protected]。条款合理,并按公司规模确定。

由 Alex Greenshpun 创建。