Token守护者

SKILL.md

---
slug: token-guard-pro
name: token-guard-pro
version: "1.0.0"
displayName: Token守护者
summary: 解决压缩损质、缓存命中低、无模型路由、预算失控的Token成本守护器
license: MIT
description: |-
  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
tags:
- Token优化
- 成本控制
- 语义缓存
- 模型路由
tools:
- read
- exec
---

# 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 成本