Token Optimizer v3.1

一键安装，全自动运行，直观看到省了多少 Token 和费用。

功能说明

Token Optimizer 是一个零依赖的 LLM Token 优化代理。安装后作为本地透明代理运行（默认 localhost:8899），自动拦截发往 OpenAI / Anthropic / Ollama 的 API 请求，通过四策略管道压缩后再转发，减少 30-70% 的 Token 消耗。

核心功能：
- 智能压缩代理：透明拦截 LLM API 请求，自动优化后转发
- 累积统计仪表盘：直观展示"自安装以来"累计节省的 Token 和费用
- 策略贡献细分：语义去重 / 精确去重 / 噪音过滤 / 表格压缩 / 长文本压缩 — 各自节省量清晰可见
- 一键自检：无需真实 LLM 流量即可验证优化管道
- 会话历史：每次代理启动/停止的节省统计对比
- 系统托盘：Windows 任务栏图标，右键查看统计或退出
- 开机自启：安装后默认注册到 Windows 启动项
- 配置管理：通过 data/config.json 管理所有参数，无需手动设置环境变量
- 零外部依赖：仅使用 Python 标准库（sqlite3、ctypes、json 等）

四策略管道：语义去重 → 精确去重 → 噪音过滤 → 语义压缩（可选 Ollama）

适用场景

• 🧠 AI Agent 高频调用优化：当你的 WorkBuddy / Agent 应用频繁调用 LLM API 时，代理自动压缩上下文，显著降低费用
• 💰 Token 成本控制：团队或企业使用付费 LLM API（GPT-4、Claude 等），需要量化并降低 Token 支出
• 🔍 上下文预算管理：对话历史过长超出模型上下文窗口时，自动智能截断优化
• 📊 开发者调试：分析哪些类型的文本浪费了最多 Token（注释？重复代码？表格？）

使用方法

一键安装

cd scripts
python install.py

安装脚本自动完成：数据库初始化 → 配置文件生成 → 桌面快捷方式 → 开机自启 → 启动代理 → 打开仪表盘。

日常使用

安装后，每次开机代理会自动在后台运行。你也可以随时双击桌面上的 Token Optimizer.bat 启动。

打开浏览器访问 http://localhost:8899/dashboard 查看实时统计数据。

将 LLM API 地址改为代理地址即可生效：
- OpenAI：http://localhost:8899/v1/chat/completions
- Ollama：http://localhost:8899/api/generate

命令行方式（可选）

# 仅启动代理（不安装）
python optimize.py --proxy --port 8899

# 单次上下文拦截优化
python optimize.py --intercept "长文本..." --budget 4000

# 文件批量优化
python optimize.py --batch ./src --report html

输入要求

• 运行环境：Python 3.8 及以上（无需任何 pip 安装）
• 操作系统：Windows（系统托盘和开机自启功能仅支持 Windows；代理核心跨平台可用）
• 配置：data/config.json（安装时自动生成），也可通过环境变量覆盖（TO_CONTEXT_BUDGET、TO_OLLAMA_MODEL 等）
• 上游 API：默认转发到 api.openai.com 或 localhost:11434（Ollama），可在配置文件中修改

输出内容

仪表盘 http://localhost:8899/dashboard 实时展示：

示例

示例一：安装并首次查看节省数据

# 1. 安装
cd C:\Users\alex2\.workbuddy\skills\token-optimizer\scripts
python install.py

# 输出：
# =======================================================
#   Token Optimizer v3.1 -- Installer
# =======================================================
#   Python 3.13.12 -- OK
#   [1/6] Initialize database...  DB: .../data/to_stats.db -- OK
#   [2/6] Write configuration...  Config created: .../data/config.json
#   [3/6] Create desktop shortcut...  Desktop shortcut: .../Desktop/Token Optimizer.bat
#   [4/6] Register auto-start...  Auto-start registered
#   [5/6] Start proxy server...  Proxy ready on port 8899
#   [6/6] Done!
# =======================================================
#   Installation complete!

# 2. 浏览器自动打开 http://localhost:8899/dashboard
#    点击"🔬 运行自检"按钮，立即看到策略贡献面板和节省数据

示例二：通过 API 查询统计

# 查询累积统计（JSON）
curl "http://localhost:8899/proxy-stats?cumulative=true"

# 返回示例：
# {
#   "cumulative": {
#     "total_saved_tokens": 124567,
#     "total_cost_saved_usd": 0.3737,
#     "days_since_install": 15,
#     "total_sessions": 42,
#     "avg_saved_pct": 34.2
#   },
#   "recent_sessions": [...],
#   "strat_breakdown": {"semantic_dedup": 50000, "dedup": 25000, ...}
#   "total_requests": 5,
#   "requests_log": [...]
# }

示例三：将 AI Agent 的 API 地址指向代理

假设你在 WorkBuddy 中使用 OpenAI API，将 API base URL 从 https://api.openai.com 改为 http://localhost:8899。此后所有对话请求都会自动经过优化管道：

原始请求: 3,200 tokens
  → 语义去重: -180 tokens
  → 精确去重: -80 tokens
  → 噪音过滤: -420 tokens
  → 表格压缩: -0 tokens
优化后: 2,520 tokens（节省 21.3%）
  → 转发到 api.openai.com

限制说明

• 仅支持文本压缩：不处理图片、音频等多模态内容（会原样转发）
• 代理仅监听本机：默认绑定 localhost:8899，不支持远程访问（出于安全考虑）
• 不支持流式响应优化：当前对 SSE/streaming 响应的优化支持有限
• 非加密传输：代理仅支持 HTTP，不提供 HTTPS。上游 API 的 HTTPS 加密不受影响
• 策略管道有顺序依赖：语义去重 → 精确去重 → 噪音过滤 → 语义压缩，前一道策略的结果会影响后一道
• 语义压缩需要 Ollama：第四策略语义压缩为可选功能，需要本地运行 Ollama 服务
• 不修改原始请求：优化后的请求会转发到上游，原始数据不会被修改或存储（统计仅记录 Token 数量）
• 费用估算仅供参考：基于内置模型定价表（可能滞后于官方调价），实际费用以 API 提供商账单为准

注意事项

• 首次使用建议点击仪表盘的 🔬 运行自检 按钮，验证优化管道正常工作
• 开机自启后代理在后台运行（无命令行窗口），可通过系统托盘图标管理
• 统计数据存储在 data/to_stats.db（SQLite），删除此文件会丢失所有历史统计
• 配置文件 data/config.json 可手动编辑，修改后重启代理生效
• 代理默认转发到 api.openai.com，使用其他 API 提供商需在配置中修改上游地址
• 生产环境建议定期备份 data/ 目录以获得长期统计
• 如需完全卸载：删除安装目录，并在注册表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 中移除 TokenOptimizer 项