# Token Saver

> >

- **Type:** Skill
- **Install:** `agentstack add skill-wukai8289-token-saver-token-saver`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wukai8289](https://agentstack.voostack.com/s/wukai8289)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wukai8289](https://github.com/wukai8289)
- **Source:** https://github.com/wukai8289/token-saver

## Install

```sh
agentstack add skill-wukai8289-token-saver-token-saver
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Token Saver Skill

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

## 核心理念

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

## 能力矩阵

| 策略 | 节省幅度 | 适用场景 | 实现方式 |
|------|---------|---------|---------|
| **智能压缩** | 40-70% | 长文本处理、代码审查 | 关键信息提取、摘要替换 |
| **上下文缓存** | 60-90% | 重复查询、相似任务 | 语义缓存、增量更新 |
| **选择性加载** | 50-80% | 大型代码库分析 | 按需加载、相关度过滤 |
| **输出精简** | 30-50% | 结果返回 | 结构化输出、模板化 |
| **批量处理** | 20-40% | 多文件操作 | 请求合并、并行处理 |

## 快速命令

### 1. Token 分析
```bash
# 分析当前对话的 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
# 压缩文本（保留关键信息）
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
# 生成结构化摘要
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
# 检查当前预算状态
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
# 启动实时监控
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. 成本分析报告
```bash
# 生成成本报告 (默认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)
从大量文本中提取核心信息，丢弃冗余内容。

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

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

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

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

### 策略 B: 增量更新 (Delta)
对于已缓存的上下文，只传递变化部分。

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

### 策略 C: 分层加载 (Layered)
根据相关性分层，只加载需要的层级。

```python
# 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)
```json
{"t":"任务类型","s":"状态","r":"结果摘要","tokens":{"in":100,"out":50}}
```

### 标准模式 (Standard)
```markdown
任务: [任务描述]
状态: [完成/进行中/失败]
结果: [简要结果]
Token 使用: 入 100 / 出 50 / 节省 60%
```

## 集成指南

### 与 Agent 协作
```markdown
在你的 agent 提示词中添加:

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

### 与任务系统集成
```bash
# 在任务执行前分析 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
# 计算潜在节省
bash ~/.claude/skills/token-saver/scripts/calculate.sh \
  --input 10000 \
  --strategy extract \
  --ratio 0.3
# 输出: 预计节省 7000 tokens (70%)
```

## 调试与监控

```bash
# 查看缓存统计
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 竞品监控

| 功能 | 竞品 | token-saver |
|------|------|-------------|
| 成本监控 | ✅ | ✅ |
| 成本告警 | ✅ | ✅ |
| **执行前预算检查** | ❌ | ✅ |
| **超预算自动拦截** | ❌ | ✅ |
| **成本分析报告** | ❌ | ✅ |

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

### 预算执行工作流

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

### 告警阈值配置

| 级别 | 默认值 | 动作 |
|------|--------|------|
| WARNING | 70% | 提醒，仍可执行 |
| CRITICAL | 90% | 需确认后才执行 |
| EMERGENCY | 98% | 强制拦截 |

---

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [wukai8289](https://github.com/wukai8289)
- **Source:** [wukai8289/token-saver](https://github.com/wukai8289/token-saver)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wukai8289-token-saver-token-saver
- Seller: https://agentstack.voostack.com/s/wukai8289
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.