Token 守护者（Token Guard Pro）

面向 AI Agent 的 token 成本优化系统，用三层缓存 + 自适应压缩 + 模型路由 + 预算守护，在不牺牲响应质量的前提下降低 50-80% 的 token 成本。

设计动机：四大高频痛点

核心能力

1. 智能上下文压缩

按重要度分级压缩，保护关键内容：

压缩策略：
- 最近 3-5 条消息：完整保留
- 较早消息：按重要度评分压缩
  - 高重要度（决策、代码、错误）：完整保留
  - 中重要度（讨论、推理）：摘要压缩
  - 低重要度（寒暄、重复）：极度压缩或删除
- 代码块：永不压缩
- 错误消息与堆栈：永不压缩
- 用户标记的重要消息：永不压缩

节省效果：50-70% 上下文 token 减少，关键内容零损失。

2. 三层语义缓存

告别"完全相同才命中"的低效缓存：

L2 语义缓存工作流：
1. 用户查询 → 生成 embedding
2. 与缓存中的查询 embedding 计算 cosine 相似度
3. 相似度 >= 0.85 → 命中，返回缓存答案
4. 相似度 < 0.85 → 未命中，正常处理
5. 处理结果写入缓存（含 embedding）

缓存命中率优化：

• L1 命中率：约 10-20%（完全重复）
• L2 命中率：约 30-50%（语义相似）
• L3 命中率：约 10-20%（模式匹配）
• 综合命中率：50-90%（视场景）

3. 自适应优化

按 token 压力分阶段调整压缩强度：

4. 模型路由

按任务复杂度自动路由到合适模型：

任务复杂度评估：
- 输入长度 < 500 token 且非推理任务 → 简单
- 输入长度 500-2000 token 或中等推理 → 中等
- 输入长度 > 2000 token 或深度推理 → 复杂

路由策略（示例）：
- 简单 → gpt-4o-mini / claude-haiku（成本低）
- 中等 → gpt-4o / claude-sonnet（平衡）
- 复杂 → gpt-4o-pro / claude-opus（质量高）

成本影响：
- 不路由：100% 用顶级模型
- 路由后：约 40% 简单 + 40% 中等 + 20% 复杂
- 综合成本降低：约 30-40%

5. 预算守护

设置预算上限，超限自动告警与降级：

{
  "budget": {
    "daily": { "limit": 5.0, "currency": "USD" },
    "weekly": { "limit": 30.0, "currency": "USD" },
    "monthly": { "limit": 100.0, "currency": "USD" }
  },
  "thresholds": {
    "warning": 0.8,
    "critical": 0.95
  },
  "on_exceed": "degrade"
}

超限处理：

6. Prefix Cache 支持

利用大模型的 prefix cache 能力，重复前缀输入成本降至 1/10：

适用场景：
- System Prompt 固定且长（>1000 token）
- 多次调用共享相同前缀（如 RAG 的固定上下文）
- 长文档的增量问答

支持的平台：
- Anthropic Claude：prompt caching（前缀缓存）
- OpenAI：自动 prefix cache
- Google Gemini：context cache

优化效果：
- 输入成本：降至 1/10
- 首 token 延迟：降低 50-85%
- 适用条件：前缀 >= 1024 token，5 分钟内复用

7. 成本可视化仪表盘

实时展示节省效果与成本趋势：

Token 守护者仪表盘
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

本会话：
- 原始 Token：12,450
- 优化后 Token：4,358
- 节省：8,092（65%）
- 预估成本节省：$0.016

节省来源分布：
1. 上下文压缩：-6,200 token（76%）
2. 语义缓存：-1,500 token（19%）
3. 模型路由：-392 token（5%）

缓存命中率：
- L1 精确：3 次
- L2 语义：5 次
- L3 模式：2 次
- 综合：50%

模型分布：
- 小模型：8 次（40%）
- 中模型：7 次（35%）
- 大模型：5 次（25%）

预算使用：
- 今日：$0.32 / $5.00（6.4%）
- 本周：$1.20 / $30.00（4.0%）
- 本月：$4.50 / $100.00（4.5%）

趋势：节省率稳定在 60-70%，缓存命中率上升中

快速开始（< 60 秒）

自然语言命令

用户可用自然语言或斜杠命令交互：

四种工作模式

安全保障

永不压缩的内容：

• 代码块（始终完整保留）
• 错误消息与堆栈跟踪
• 用户标记的重要消息
• 高交叉引用的消息
• 关键决策与待办

质量守护：

• 自动回滚：质量下降 > 15% 时回滚到未压缩版本
• 一键恢复：可恢复到任意压缩前的快照
• 快照机制：每次压缩前保存快照

典型工作流（3 个真实场景）

场景一：长编程会话

用户：20 轮 Python 讨论

Token 守护者处理：
1. 阶段 2 压缩激活（6-10K token）
2. 代码块完整保留
3. 早期讨论摘要化
4. 模型路由：简单问题用小模型
5. 重复问题命中 L2 缓存

结果：15K → 4.5K token（节省 70%），代码零损失

场景二：高频客服问答

用户：客服场景，大量相似问题

Token 守护者处理：
1. L2 语义缓存激活（相似度 >= 0.85）
2. "怎么退款" 与 "如何申请退款" 命中同一缓存
3. 缓存命中率：65%
4. 模型路由：简单 FAQ 用小模型

结果：综合成本降低 75%，响应延迟降低 60%

场景三：预算管控

企业场景：月预算 $100

Token 守护者处理：
1. 每日预算 $5，80% 告警，95% 严重告警
2. 第 20 天累计 $85（85%）
3. 触发告警，自动切换到 save 模式
4. 第 25 天累计 $95（95%）
5. 严重告警，强制用小模型
6. 月末累计 $98，未超预算

结果：预算可控，避免超支

预期效果

配置示例

{
  "mode": "adaptive",
  "compression": "balanced",
  "cache": {
    "enabled": true,
    "l1_enabled": true,
    "l2_enabled": true,
    "l2_threshold": 0.85,
    "l3_enabled": true,
    "ttl": 3600
  },
  "model_routing": {
    "enabled": true,
    "simple_model": "gpt-4o-mini",
    "medium_model": "gpt-4o",
    "complex_model": "gpt-4o-pro"
  },
  "prefix_cache": {
    "enabled": true,
    "min_prefix_tokens": 1024
  },
  "budget": {
    "daily": 5.0,
    "weekly": 30.0,
    "monthly": 100.0,
    "currency": "USD",
    "on_exceed": "degrade"
  },
  "quality_guard": {
    "enabled": true,
    "rollback_threshold": 0.15,
    "snapshot": true
  }
}

限制说明

• 压缩在 token 超过 3K 后才启动（短会话无收益）
• 首次查询无法缓存（缓存需积累）
• 极短会话（< 10 条消息）收益有限
• 代码密集会话主要靠模型路由与 prefix cache 节省
• 语义缓存需要 embedding 服务（可用本地或云端）

FAQ

Q1：压缩会不会影响代码质量？ A：不会。代码块、错误消息、关键决策永不压缩。压缩只针对讨论性内容（寒暄、重复推理等）。

Q2：语义缓存会不会返回错误答案？ A：L2 语义缓存相似度阈值默认 0.85，可调到 0.92 更保守。命中时会标注"来自缓存"，用户可要求重新生成。

Q3：模型路由会不会降低复杂任务质量？ A：不会。路由基于任务复杂度评估，复杂任务自动用大模型。用户也可在 quality 模式下禁用路由，全部用大模型。

Q4：预算超限后会怎样？ A：80% 告警，95% 严重告警并强制小模型，100% 停止非必要调用。用户可临时调高预算或切换到 save 模式。

Q5：Prefix Cache 怎么启用？ A：自动检测平台支持。Anthropic/OpenAI/Gemini 均支持。需前缀 >= 1024 token 且 5 分钟内复用。System Prompt 固定场景效果最佳。

Q6：缓存的数据会不会泄露隐私？ A：缓存默认存储在本地。如用云端 embedding 服务，仅传输查询文本（不含用户身份）。可配置不缓存含敏感信息的查询。

故障排查

与其他技能协同

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux

第三方依赖

API Key 配置

• 本技能核心功能无需额外 API Key（LLM 由 Agent 平台提供）
• 语义缓存增强（可选）：
  • 云端 Embedding：配置对应服务 Key（如 OPENAI_API_KEY）
  • 本地 Embedding：无需 Key，用 Transformers.js

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需 exec 执行缓存与统计操作）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 优化 token 成本