---
slug: token-guard-pro
name: token-guard-pro
version: 1.0.1
displayName: Token守护者
summary: "解决压缩损质、缓存命中低、无模型路由、预算失控的Token成本守护器。面向 AI Agent 的 token 成本优化系统，直击压缩损质、缓存命中低、无模型路由、预算失控四大痛点。适用于长会"
license: Proprietary
description: 面向 AI Agent 的 token 成本优化系统，直击压缩损质、缓存命中低、无模型路由、预算失控四大痛点。适用于长会话治理、高频问答缓存、多模型混合调用、企业预算管控等场景。核心能力含分级上下文压缩、三层语义缓存、自适应模型路由、预算守护、Prefix
  Cache 支持。适用关键词：token优化、成本降低、语义缓存、上下文压缩、模型路由、预算控制、token saver、semantic cache.
tags:
  - Token优化
  - 成本控制
  - 语义缓存
  - 模型路由
  - AI代理
  - 自动化
  - 智能
  - token
  - cache
  - prefix
  - 缓存
  - 适用
tools:
  - read
  - exec
  - write
  - glob
  - grep
homepage: ""
# 定价元数据
category: "Agents"
---
# Token 守护者（Token Guard Pro）

面向 AI Agent 的 **token 成本优化系统**，用三层缓存 + 自适应压缩 + 模型路由 + 预算守护，在不牺牲响应质量的前提下降低 50-80% 的 token 成本。代码块、错误消息、关键决策永不压缩，质量下降 > 15% 时自动回滚.
## 核心能力

### 1. 智能上下文压缩
按重要度分级压缩，保护关键内容。最近 3-5 条消息完整保留；较早消息按重要度评分压缩（高重要度如决策/代码/错误完整保留，中重要度如讨论/推理摘要压缩，低重要度如寒暄/重复极度压缩）。代码块、错误消息与堆栈、用户标记的重要消息永不压缩。节省效果：50-70% 上下文 token 减少，关键内容零损失.
**输入**: 用户提供智能上下文压缩所需的指令和必要参数.
**处理**: 解析智能上下文压缩的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回智能上下文压缩的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 2. 三层语义缓存
L1 精确查询匹配（100% 节省，高频重复 FAQ）、L2 语义相似度 >= 0.85（80% 节省，客服问答/相似问题）、L3 模式匹配（50% 节省，同类任务不同参数）。L2 通过 embedding 计算 cosine 相似度，告别"完全相同才命中"的低效。综合命中率 50-90%（视场景）.
**输入**: 用户提供三层语义缓存所需的指令和必要参数.
**处理**: 解析三层语义缓存的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回三层语义缓存的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 3. 自适应优化与模型路由
按 token 压力分 5 阶段调整压缩强度（< 3K 不压缩 → > 15K 极限压缩+建议开新会话）。按任务复杂度自动路由：简单（< 500 token 非推理）→ 小模型，中等（500-2000 token）→ 平衡模型，复杂（> 2000 token 深度推理）→ 大模型。路由后综合成本再降 30-40%.
**输入**: 用户提供自适应优化与模型路由所需的指令和必要参数.
**处理**: 解析自适应优化与模型路由的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回自适应优化与模型路由的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 4. 预算守护
设置日/周/月预算上限，超限自动告警与降级。80% 预算告警提示并切换 save 模式，95% 严重告警并强制用小模型，100% 停止非必要调用仅保留缓存响应。杜绝月底才发现超支的预算失控.
**输入**: 用户提供预算守护所需的指令和必要参数.
**处理**: 解析预算守护的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回预算守护的响应数据,包含状态码、结果和日志.
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
### 5. Prefix Cache 与成本可视化
利用大模型的 prefix cache 能力（Anthropic Claude prompt caching / OpenAI 自动 prefix cache / Google Gemini context cache），重复前缀输入成本降至 1/10，首 token 延迟降低 50-85%（需前缀 >= 1024 token 且 5 分钟内复用）。实时仪表盘展示节省率、缓存命中率、模型分布、成本趋势.
**输入**: 用户提供Prefix Cache 与成本可视化所需的指令和必要参数.
**处理**: 解析Prefix Cache 与成本可视化的输入参数,完成核心逻辑,返回结构化响应.
**输出**: 返回Prefix Cache 与成本可视化的响应数据,包含状态码、结果和日志.
**技术参数**：使用`input_params`和`output_format`参数控制执行行为,支持`json`/`text`/`csv`输出格式.
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：解决压缩损质、缓存命中低、无模型路由、预算失控的、成本守护器、Agent、成本优化系统、直击压缩损质、预算失控四大痛点、适用于长会话治理、高频问答缓存、多模型混合调用、企业预算管控等场、核心能力含分级上、自适应模型路由、适用关键词、成本降低、预算控制、saver、semantic等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.
## 快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

## 适用场景

| 场景类型 | 输入 | 输出 | 是否适用 |
|----|---|---|----|
| 长会话 token 治理 | 20+ 轮技术讨论 | 压缩后上下文 + 节省报告 | ✅ 适用 |
| 高频问答缓存 | 客服场景大量相似问题 | L2 语义缓存命中 + 响应加速 | ✅ 适用 |
| 多模型混合调用 | 不同复杂度任务 | 按复杂度路由到合适模型 | ✅ 适用 |
| 企业级预算管控 | 月预算上限 | 超限告警 + 自动降级 | ✅ 适用 |
| 研究探索类任务 | 100+ 轮长会话 | 极限压缩 + 缓存 + 小模型 | ✅ 适用 |
| 代码审查场景 | 代码密集会话 | 代码不压缩 + 模型路由节省 | ✅ 适用 |

**不适用场景**：
- 极短会话（< 10 条消息，< 3K token）→ 压缩未启动，收益有限
- 需要完整上下文的精确任务（如法律/医疗分析）→ 用 quality 模式或关闭优化
- 无 LLM API 的纯本地推理 → 模型路由与 prefix cache 依赖云端 API 能力
- 单一模型且无缓存需求的简单问答 → 优化开销大于收益

## 使用流程

### Step 1：配置模式（默认 balance 平衡模式）

## 输入格式
| 参数名 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:-----|
| input | string | 是 | Token守护者处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

```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" },
  "budget": { "daily": 5.0, "weekly": 30.0, "monthly": 100.0, "currency": "USD", "on_exceed": "degrade" }
}
```

**国内模型路由示例**（智谱 GLM / 百度文心 / 通义千问 / DeepSeek，按复杂度分层）：
```json
{
  "model_routing": {
    "enabled": true,
    "simple_model": "deepseek-chat",
    "medium_model": "qwen-plus",
    "complex_model": "glm-4"
  }
}
```
国内模型分层建议：简单任务（< 500 token 非推理）→ DeepSeek-Chat 或 ERNIE-Speed（低成本高吞吐）；中等任务（500-2000 token）→ 通义千问 Qwen-Plus 或 ERNIE-4.0（平衡）；复杂任务（> 2000 token 深度推理）→ 智谱 GLM-4 或 DeepSeek-Reasoner（强推理）。各模型通过 OpenAI 兼容接口接入，仅需替换 `base_url` 与 `api_key`（如 `https://open.bigmodel.cn/api/paas/v4`、`https://aip.baidubce.com`、`https://dashscope.aliyuncs.com`、`https://api.deepseek.com`）.
### Step 2：选择工作模式

| 用户说 | 执行命令 | 模式 | 压缩强度 |
|---:|---:|---:|---:|
| "用激进模式" | `/tokensave` | save | 重度，相似度阈值 0.80 |
| "用平衡模式" | `/tokenbalance` | balance | 中度，相似度阈值 0.85 |
| "优先质量" | `/tokenquality` | quality | 轻度，相似度阈值 0.92 |
| "禁用优化" | `/tokenoff` | off | 无 |

### Step 3：会话中自动优化

代理在每次交互中自动执行：评估 token 压力 → 分级压缩（保护代码/错误/决策）→ 检查三层缓存 → 路由到合适模型 → 记录成本.
### Step 4：监控预算与报告

| 用户说 | 执行命令 | 响应 |
|:---:|:---:|:---:|
| "Token 报告" | `/tokenreport` | 生成详细使用报告（节省率、缓存命中、模型分布） |
| "Token 状态" | `/tokens` | 快速查看当前状态 |
| "设预算" | `/tokenbudget` | 配置日/周/月预算上限 |
| "清缓存" | `/tokencache clear` | 清空所有缓存 |

**节省率实测方法（基于实际会话）**：用对照测量法获得真实节省率，而非依赖经验估值：(1) 基线组——关闭优化（`/tokenoff`），记录同一会话的原始 token 消耗 `T_raw`（输入+输出，含重复前缀）；(2) 实验组——开启优化（`/tokenbalance`），重放相同会话，记录优化后 token 消耗 `T_opt` 与缓存命中次数 `H`；(3) 节省率 `S = (T_raw - T_opt) / T_raw × 100%`；(4) 拆解贡献——压缩节省 `= (压缩前 - 压缩后) / T_raw`、缓存节省 `= H × 平均响应 token / T_raw`、路由节省 `= Σ(大模型单价 - 实际模型单价) × token / 总成本`。建议连续测 3-5 个典型会话取中位数，排除首次缓存冷启动会话。报告会自动输出三部分贡献占比，便于定位优化短板.
### Step 5：质量守护与回滚

每次压缩前保存快照，质量下降 > 15% 时自动回滚到未压缩版本。可一键恢复到任意压缩前的快照.
### Step 6：缓存敏感信息自动检测与脱敏

缓存写入前自动扫描敏感信息，命中则脱敏或拒绝缓存，防止敏感数据在缓存层留存：

| 检测类型 | 识别规则 | 处理方式 |
|:------|------:|:------|
| 身份证件 | 身份证号（18 位校验）、护照号 | 命中即拒绝缓存该条目，仅走实时调用 |
| 金融信息 | 银行卡号、CVV、支付密码 | 拒绝缓存，日志记录脱敏事件 |
| 凭据密钥 | API Key、`AWS_SECRET_ACCESS_KEY`、私钥头 | 拒绝缓存，并告警可能的凭据泄露 |
| 个人隐私 | 手机号、邮箱、住址 | 脱敏后缓存（如 `138****1234`），命中还原时不可逆 |
| 医疗数据 | 病历号、诊断码 | 默认拒绝缓存，可配置脱敏白名单 |

机制说明：检测在 embedding 之前执行（避免敏感内容生成向量留存）；脱敏条目的缓存 key 使用脱敏后文本计算，保证命中率；`sensitive_keywords` 配置支持自定义正则；命中敏感信息时不影响实时响应，仅跳过缓存写入。可在 `/tokencache` 报告中查看被脱敏/拒绝的条目计数.
## 示例

### 示例(补充)

**输入**：用户进行 20 轮 Python 技术讨论，累计 15K token

**输出**（代理执行）：

```text
1. 阶段 2 压缩激活（6-10K token 区间）
2. 代码块完整保留（永不压缩）
3. 早期讨论摘要化（中重要度压缩）
4. 模型路由：简单问题用小模型（gpt-4o-mini）
5. 重复问题命中 L2 缓存（相似度 >= 0.85）
# ...
结果：15K → 4.5K token（节省 70%），代码零损失
```

代理响应："本会话已优化：原始 15K token 压缩至 4.5K（节省 70%）。代码块完整保留，5 次命中 L2 语义缓存，8 次路由到小模型。"

### 示例 2：预算管控降级（输入→输出）

**输入**：企业场景，月预算 $100，第 20 天累计消耗 $85

```text
1. 检测到累计 $85（85%），触发 80% 告警
2. 自动切换到 save 模式（激进节省）
3. 第 25 天累计 $95（95%），触发严重告警
4. 强制使用小模型（gpt-4o-mini）
5. 月末累计 $98，未超预算
```

代理响应："预算告警：本月已用 $85（85%），已自动切换到激进节省模式。预计月末消耗 $98，未超 $100 预算。建议下周继续使用 save 模式。"

## 错误处理

| 场景 | 原因 | 处理方式 |
|---:|:---|---:|
| 节省率低 | 会话太短（< 3K token） | 压缩需 > 3K token 启动，长会话效果明显；短会话用 quality 模式 |
| 节省率低 | quality 模式压缩轻 | 切换到 balance 或 save 模式 |
| 缓存不命中 | 首次查询无缓存 | 缓存需积累，重复查询才命中；首次查询正常处理后写入缓存 |
| 缓存不命中 | L2 相似度阈值过高 | 降低 L2 阈值到 0.80（save 模式默认） |
| 代码被压缩 | 配置错误未加入保护列表 | 确认代码块在永不压缩列表，检查 compression 配置 |
| 质量下降明显 | 压缩过度 | 切换到 quality 模式，启用质量守护（rollback_threshold: 0.15） |
| 预算告警频繁 | 预算设置过低 | 调高预算或切换到 save 模式降低消耗 |
| 模型路由不准 | 复杂度评估错误 | 手动指定模型或关闭路由，用 quality 模式全用大模型 |
| Prefix Cache 未生效 | 前缀 < 1024 token 或超 5 分钟 | 确保前缀 >= 1024 token 且 5 分钟内复用;执行排查步骤后恢复操作 |
| 缓存隐私担忧 | 缓存含敏感信息 | 配置不缓存含敏感关键词的查询，或用本地 embedding |

## 依赖说明

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

**运行环境**：Windows / macOS / Linux；支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）.
**API Key**：核心功能无需额外 API Key（LLM 由 Agent 平台提供）。语义缓存增强（可选）：云端 Embedding 需配置对应服务 Key（如 OPENAI_API_KEY），本地 Embedding 用 Transformers.js 无需 Key.
**可用性分类**：MD+EXEC（纯 Markdown 指令，部分功能需 exec 执行缓存与统计操作）.
## 常见问题

**Q1：压缩会不会影响代码质量？**
A：不会。代码块、错误消息、关键决策永不压缩。压缩只针对讨论性内容（寒暄、重复推理等）。质量守护机制在质量下降 > 15% 时自动回滚.
**Q2：语义缓存会不会返回错误答案？**
A：L2 语义缓存相似度阈值默认 0.85，可调到 0.92 更保守。命中时会标注"来自缓存"，用户可要求重新生成。可配置不缓存含敏感信息的查询.
**Q3：模型路由会不会降低复杂任务质量？**
A：不会。路由基于任务复杂度评估，复杂任务自动用大模型。用户也可在 quality 模式下禁用路由，全部用大模型.
**Q4：预算超限后会怎样？**
A：80% 告警并切换 save 模式，95% 严重告警并强制小模型，100% 停止非必要调用仅保留缓存响应。用户可临时调高预算或切换模式.
**Q5：Prefix Cache 怎么启用？**
A：自动检测平台支持。Anthropic/OpenAI/Gemini 均支持。需前缀 >= 1024 token 且 5 分钟内复用。System Prompt 固定场景效果最佳，输入成本降至 1/10，首 token 延迟降低 50-85%.
## 已知限制

1. **短会话收益有限**：压缩在 token 超过 3K 后才启动，极短会话（< 10 条消息）无优化收益。首次查询无法缓存，缓存需积累.
2. **语义缓存依赖 Embedding 服务**：L2 语义缓存需要 embedding 服务（本地 Transformers.js 或云端 OpenAI）。无 embedding 服务时仅能用 L1 精确匹配 + L3 模式匹配.
3. **模型路由受平台模型可用性限制**：路由策略中的模型名（gpt-4o-mini/gpt-4o/gpt-4o-pro）为示例，实际需根据 Agent 平台可用的模型调整。不支持模型选择的平台无法使用路由功能.
4. **节省比例为经验估值**：50-80% 的节省率基于典型场景，实际效果取决于会话类型、数据分布、缓存命中率。代码密集会话主要靠模型路由与 prefix cache 节省，缓存命中率较低.
5. **缓存默认本地存储**：缓存数据默认存储在本地，大规模场景需接入向量数据库。如用云端 embedding 服务，仅传输查询文本（不含用户身份），但仍有数据出境考量.