Token Saver Skill

智能 Token 优化工具，通过分析、压缩、缓存、预算执行四大策略显著降低 AI 代理的 Token 消耗。

核心理念

Token 成本 = 输入 Tokens × 单价 + 输出 Tokens × 单价
优化目标: 在不损失任务质量的前提下，最小化 Token 消耗

能力矩阵

快速命令

1. Token 分析

# 分析当前对话的 Token 使用情况
bash ~/.claude/skills/token-saver/scripts/analyze-tokens.sh

# 分析特定文件的 Token 开销
bash ~/.claude/skills/token-saver/scripts/analyze-tokens.sh --file path/to/file

# 模拟不同策略的节省效果
bash ~/.claude/skills/token-saver/scripts/analyze-tokens.sh --simulate

2. 上下文压缩

# 压缩文本（保留关键信息）
bash ~/.claude/skills/token-saver/scripts/compress.sh --text "你的文本"

# 压缩文件
bash ~/.claude/skills/token-saver/scripts/compress.sh --file path/to/file

# 批量压缩目录
bash ~/.claude/skills/token-saver/scripts/compress.sh --dir path/to/dir

3. 智能摘要

# 生成结构化摘要
bash ~/.claude/skills/token-saver/scripts/summarize.sh --file path/to/file

# 提取关键信息点
bash ~/.claude/skills/token-saver/scripts/summarize.sh --extract --file path/to/file

4. 预算执行 (核心差异化功能)

# 检查当前预算状态
bash ~/.claude/skills/token-saver/scripts/budget-enforce.sh --check --tokens 5000 --budget 100000

# 估算提示词 Token 和成本
bash ~/.claude/skills/token-saver/scripts/budget-enforce.sh --estimate --prompt "你的提示词"

# 执行前检查，超预算则拦截
bash ~/.claude/skills/token-saver/scripts/budget-enforce.sh --enforce --command "要执行的命令"

# 实时监控模式
bash ~/.claude/skills/token-saver/scripts/budget-enforce.sh --watch

# 设置预算
export TOKEN_BUDGET=50000
bash ~/.claude/skills/token-saver/scripts/budget-enforce.sh --set default_budget 50000

5. 实时告警

# 启动实时监控
bash ~/.claude/skills/token-saver/scripts/alert.sh --watch

# 设置警告阈值
bash ~/.claude/skills/token-saver/scripts/alert.sh --set thresholds.warning 60

# 查看告警历史
bash ~/.claude/skills/token-saver/scripts/alert.sh --history

6. 成本分析报告

# 生成成本报告 (默认7天)
bash ~/.claude/skills/token-saver/scripts/cost-report.sh report

# 查看30天报告
bash ~/.claude/skills/token-saver/scripts/cost-report.sh report 30

# 记录本次使用
bash ~/.claude/skills/token-saver/scripts/cost-report.sh save session123 5000 2000 claude-3-5-sonnet

# 导出数据
bash ~/.claude/skills/token-saver/scripts/cost-report.sh export csv usage.csv

压缩策略详解

策略 A: 关键信息提取 (Extract)

从大量文本中提取核心信息，丢弃冗余内容。

输入 (5000 tokens):
[长篇技术文档，包含大量示例、重复说明、格式化内容]

输出 (1500 tokens):
## 核心概念
- 概念1: 定义
- 概念2: 定义

## 关键参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| param1 | value1 | desc1 |

## 必知 API
- function1(params) → return_type

策略 B: 增量更新 (Delta)

对于已缓存的上下文，只传递变化部分。

缓存 (首次): 完整代码库结构 + 关键函数签名 (3000 tokens)
增量 (后续): 仅变化的 3 个文件 diff (200 tokens)
总计: 3200 vs 每次 3000 = 节省 89%

策略 C: 分层加载 (Layered)

根据相关性分层，只加载需要的层级。

# Level 1: 文件列表和结构 (50 tokens)
files = ["auth.py", "routes.py", "models.py"]

# Level 2: 相关文件摘要 (200 tokens)
auth.py: JWT认证模块，3个主要函数

# Level 3: 完整内容 (按需加载)
auth.py → get_token(), verify_token(), refresh_token()

缓存系统

缓存目录结构

~/.claude/skills/token-saver/cache/
├── file-hashes/          # 文件内容哈希
├── summaries/            # 生成的摘要
├── api-docs/             # API 文档缓存
└── index.json            # 缓存索引

缓存命中规则

1. 文件哈希匹配 → 直接返回缓存摘要
2. 语义相似度 > 0.85 → 返回相似结果
3. 增量变化 → 仅更新变化部分

输出模板

紧凑模式 (Compact)

{"t":"任务类型","s":"状态","r":"结果摘要","tokens":{"in":100,"out":50}}

标准模式 (Standard)

任务: [任务描述]
状态: [完成/进行中/失败]
结果: [简要结果]
Token 使用: 入 100 / 出 50 / 节省 60%

集成指南

与 Agent 协作

在你的 agent 提示词中添加:

---
TOKEN_OPTIMIZATION:
- 使用 token-saver 技能压缩长输入
- 优先返回结构化输出
- 对重复内容启用缓存
---

与任务系统集成

# 在任务执行前分析 Token 预算
export TOKEN_BUDGET=10000
bash ~/.claude/skills/token-saver/scripts/budget.sh --check

最佳实践

✅ 应该做

1. 大文件先摘要 → 再决定是否需要完整内容
2. 使用结构化输出 → JSON/表格比自然语言更紧凑
3. 缓存重复查询 → 相同问题不重复计算
4. 增量更新 → 只传递变化部分
5. 相关度过滤 → 只加载必要的上下文

❌ 避免做

1. 全文复制 → 除非必要，否则摘要替代
2. 重复系统提示 → 使用缓存或引用
3. 冗余格式 → 避免过多换行、空格、注释
4. 完整历史 → 只保留必要的对话历史

Token 节省计算器

# 计算潜在节省
bash ~/.claude/skills/token-saver/scripts/calculate.sh \
  --input 10000 \
  --strategy extract \
  --ratio 0.3
# 输出: 预计节省 7000 tokens (70%)

调试与监控

# 查看缓存统计
bash ~/.claude/skills/token-saver/scripts/stats.sh

# 清理缓存
bash ~/.claude/skills/token-saver/scripts/clear-cache.sh

# 导出使用报告
bash ~/.claude/skills/token-saver/scripts/report.sh --output report.json

核心差异化：预算执行 vs 竞品监控

竞品只能看数据，我们能在执行前拦截！

预算执行工作流

1. 设置预算: export TOKEN_BUDGET=100000
2. 执行检查: budget-enforce.sh --check --tokens 5000
3. 如果 OK  → 继续执行
4. 如果 WARNING → 提示确认
5. 如果 CRITICAL → 拦截执行

告警阈值配置

注意: Token 优化不应以损失任务质量为代价。当不确定时，优先保证任务正确性。