Token守护者

Token 守护者是面向 AI Agent 的 token 成本优化系统，针对"压缩过度损失质量、语义缓存命中率低、缺乏模型路由、预算不可见不可控"四大高频痛点而设计。它用三层缓存（精确匹配/语义匹配/模式匹配）+ 自适应压缩 + 模型路由 + 预算守护，在不牺牲响应质量的前提下降低 50-80% 的 token 成本。 核心能力：智能上下文压缩（按重要度分级压缩，代码块与关键决策永不压缩）、三层语义缓存（L1 精确匹配 100% 节省/L2 语义相似 80% 节省/L3 模式匹配 50% 节省）、自适应优化（按 token 压力分阶段调整）、模型路由（按任务复杂度路由到合适模型）、预算守护（设置预算上限，超限告警与降级）、成本可视化（实时报告与趋势分析）、Prefix Cache 支持（重复前缀输入成本降至 1/10）。 适用场景：长会话 token 治理、高频问答场景缓存、多模型混合调用成本优化、企业级 token 预算管控、客服 Agent 成本降低、研究探索类任务的最大化节省。 差异化：相比仅做"上下文压缩"的浅层优化器，本技能新增 (1) 三层语义缓存，L2 语义匹配（cosine 相似度 >= 0.85）显著提升缓存命中率，告别"完全相同才命中"的低效；(2) 模型路由，按任务复杂度自动路由到合适模型（简单任务用小模型，复杂任务用大模型），成本再降 30%；(3) 预算守护，设置日/周/月预算上限，超限自动告警与降级，杜绝预算失控；(4) Prefix Cache 支持，重复前缀输入成本降至 1/10，首 token 延迟降低 50-85%；(5) 成本可视化仪表盘，实时展示节省率、缓存命中率、模型分布、成本趋势。 触发关键词：token优化、成本降低、语义缓存、上下文压缩、模型路由、预算控制、token saver、cost optimization、semantic cache、model routing

Token 守护者（Token Guard Pro）

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

设计动机：四大高频痛点

痛点	典型表现	本技能对策
压缩过度损失质量	关键代码被压缩、决策上下文丢失	按重要度分级压缩，代码块与关键决策永不压缩
语义缓存命中率低	只有完全相同才命中，相似问题重复消耗	三层缓存：L1 精确/L2 语义（cosine>=0.85）/L3 模式
缺乏模型路由	所有任务都用最贵模型，简单任务浪费	按复杂度路由：简单→小模型，复杂→大模型
预算不可见不可控	月底才发现超支，无法实时干预	预算守护：日/周/月上限，超限告警与降级

核心能力

1. 智能上下文压缩

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

text

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

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

2. 三层语义缓存

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

层级	匹配方式	节省比例	适用场景
L1	精确查询匹配	100%	高频重复 FAQ
L2	语义相似度 >= 0.85	80%	客服问答、相似问题
L3	模式匹配（同类型问题）	50%	同类任务不同参数

text

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 压力分阶段调整压缩强度：

阶段	Token 量	压缩策略	模式建议
阶段 0	< 3K	不压缩	quality
阶段 1	3-6K	轻度压缩（仅低重要度）	balance
阶段 2	6-10K	中度压缩（低+中重要度）	balance
阶段 3	10-15K	重度压缩（仅保留高重要度）	save
阶段 4	> 15K	极限压缩 + 建议开新会话	save

4. 模型路由

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

text

任务复杂度评估：
- 输入长度 < 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. 预算守护

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

json

{
  "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"
}

超限处理：

阈值	动作
80% 预算	告警提示，切换到 save 模式
95% 预算	严重告警，强制用小模型
100% 预算	停止非必要调用，仅保留缓存响应

6. Prefix Cache 支持

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

text

适用场景：
- 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. 成本可视化仪表盘

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

text

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 秒）

自然语言命令

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

用户说	执行命令	响应
"配置 Token 守护者"	显示配置	展示当前模式、缓存、预算设置
"用激进模式"	/tokensave	切换到激进节省模式（最高 80%）
"用平衡模式"	/tokenbalance	切换到平衡模式（50-70%）
"优先质量"	/tokenquality	切换到质量优先模式（最小压缩）
"禁用优化"	/tokenoff	临时禁用，可随时恢复
"Token 报告"	/tokenreport	生成详细使用报告
"Token 状态"	/tokens	快速查看当前状态
"清缓存"	/tokencache clear	清空所有缓存
"设预算"	/tokenbudget	配置预算上限

四种工作模式

模式	压缩强度	缓存策略	模型路由	适用场景
激进（save）	重度	激进（相似度阈值 0.80）	激进（多用小模型）	研究探索、长技术讨论
平衡（balance）	中度	标准（相似度阈值 0.85）	标准	日常通用（默认）
质量（quality）	轻度	保守（相似度阈值 0.92）	保守（多用大模型）	调试、代码审查、精确任务
关闭（off）	无	无	无	需要完整上下文时

安全保障

永不压缩的内容：

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

质量守护：

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

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

场景一：长编程会话

text

用户：20 轮 Python 讨论

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

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

场景二：高频客服问答

text

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

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

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

场景三：预算管控

text

企业场景：月预算 $100

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

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

预期效果

会话类型	Token 节省	质量影响	缓存命中
技术讨论（50 轮）	70%	极小	20%
代码审查	80%	无	10%
客服问答	75%	无	65%
闲聊	75%	无	30%
快速问答	30-50%	无	15%
研究探索（100+ 轮）	80%	轻微	25%

配置示例

json

{
  "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 服务，仅传输查询文本（不含用户身份）。可配置不缓存含敏感信息的查询。

故障排查

症状	可能原因	解决方案
节省率低	会话太短	压缩需 > 3K token 启动，长会话效果明显
节省率低	quality 模式	切换到 balance 或 save 模式
缓存不命中	首次查询	缓存需积累，重复查询才命中
缓存不命中	阈值过高	降低 L2 相似度阈值到 0.80
代码被压缩	配置错误	确认代码块在永不压缩列表
质量下降	压缩过度	切换到 quality 模式，启用质量守护
预算告警频繁	预算过低	调高预算或切换到 save 模式
模型路由不准	复杂度评估错	手动指定模型或关闭路由

与其他技能协同

协同技能	关系
记忆蒸馏器	互补：蒸馏器管日志压缩，Token 守护者管实时上下文
记忆编排器	互补：编排器管记忆存储，Token 守护者管 token 成本
代理副驾驶	互补：副驾驶管 Prompt 质量，Token 守护者管 Prompt 成本

依赖说明

运行环境

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

第三方依赖

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由 Agent 内置 LLM 提供
Embedding 服务（可选）	API	可选	用于 L2 语义缓存，可用本地（Transformers.js）或云端（OpenAI）
向量数据库（可选）	外部依赖	可选	用于大规模缓存存储，如 Chroma/Qdrant

API Key 配置

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

可用性分类

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