Token Optimizer

面向 Claude Code / OpenClaw / Codex 的上下文 token 优化与可视化工具，提供 Active Compression、Smart Compaction、质量评分与成本仪表盘，零上下文消耗、零网络调用。

问题域#

AI 编程助手在长会话中面临两类 token 浪费——"运行时浪费"（冗余读取、大工具输出未归档等）和"结构性浪费"（重复配置、未使用技能前置信息、孤立 memory 条目、死 MCP 服务器等，据称占 75-85% token 消耗）。此外，auto-compact 触发时 60-70% 对话内容被摘要丢弃导致上下文丢失；长会话质量从 256K 到 1M 区间 MRCR 可从 93% 降至 76%，用户缺乏实时退化感知。

核心能力#

Active Compression (v5)#

7 个独立可切换的压缩特性，默认全部开启：

特性	说明	风险等级	预估节省
Quality Nudges	质量提示	无风险	—
Loop Detection	循环检测	无风险	—
Delta Mode	智能 re-read	低风险	~20%
Structure Map	大文件 re-read 优化	低风险	最高 99%/文件
Bash Compression	16 个处理器	低风险	~10%
Activity Mode Detection	活动模式检测	待确认	待确认
Decision Extraction	决策提取	待确认	—

Smart Compaction 与会话连续性#

在 auto-compact 触发前自动建立检查点，压缩后恢复被摘要丢弃的内容
注入大工具输出的摘要，避免模型重新读取
Progressive Checkpoints：在上下文填充 20%/35%/50%/65%/80% 及质量分数降至 80/70/50/40 时自动快照，恢复时选择最丰富的可用检查点

工具结果管理#

Tool Result Archive：>4KB 的工具结果自动归档到磁盘，替换为内联预览 + [expand <id>] 提示
模型可在压缩后自行调用 expand 恢复完整内容

质量评估#

7-Signal Quality Scoring：上下文填充(20%)、过期读取(20%)、臃肿结果(20%)、压缩深度(15%)、重复(10%)、决策密度(8%)、Agent 效率(7%)
输出 S/A/B/C/D/F 效率等级

可视化与成本追踪#

单文件 HTML 仪表盘在每次 SessionEnd 后自动生成，覆盖：

每轮 token 分解（input/output/cache-read/cache-write + 峰值检测）
缓存分析（TTL 混合、命中率）
4 个定价层成本（Anthropic API、Vertex Global、Vertex Regional、AWS Bedrock）
质量分数叠加（绿/黄/红）
子 Agent 成本分解
技能采用趋势 & 模型混合（Opus/Sonnet/Haiku）
CLAUDE.md / MEMORY.md 健康卡片
配置漂移检测 & 累计节省追踪

结构性优化#

处理重复配置、未使用技能前置信息、孤立 memory 条目、死 MCP 服务器等结构性浪费。

架构要点#

外部进程模型：不注入 LLM 上下文、不增加 MCP 开销、无网络调用（零 phone-home）
核心入口：measure.py（纯 Python stdlib）；OpenClaw 部分使用纯 Node.js stdlib
存储：本地 SQLite（~/.claude/_backups/token-optimizer/trends.db 等）
Hook 机制：基于各目标平台的 hook 系统（hooks/ 目录）
检查点：无 LLM 调用，纯确定性提取 + 后台守护
零运行时依赖：纯标准库，无需 pip/npm 安装

安装与上手#

Claude Code（推荐，全平台）：

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

macOS / Linux 替代： 使用仓库根目录 install.sh 脚本

仪表盘启动：

python3 measure.py setup-daemon           # 守护进程
python3 measure.py dashboard --serve      # 一次性 HTTP 服务

Smart Compaction 启用：

python3 measure.py setup-smart-compact

适用场景#

重度 Opus 用户的高频长会话（引用案例：30 天 942 sessions、6.13B input tokens，月节省约 $590）
需要逐轮成本可见性与子 Agent 成本归属的团队或个人
因 compaction 导致上下文丢失而需要恢复能力的场景

支持平台#

Claude Code（.claude-plugin）
OpenClaw（openclaw/ 目录，Node.js）
Codex beta（.codex-plugin）
Windsurf / Cursor：计划中，无时间线

待确认信息#

具体版本号需通过 git tag/commit 确认
Windows 支持细节不完整
Activity Mode Detection / Decision Extraction 的节省数据与风险等级未给出
$590 月节省为单一用户快照，非系统性基准测试
与 Claude Code hook 系统的最低版本要求未说明