帮你省token · Token Saver

> 输入你的任务描述，告诉你哪些工具调用是浪费——杀鸡别用牛刀。

§0 你一定经历过这个场景

你让 Agent 帮你翻译一句话。Agent 想了想，加载了翻译 Skill。翻译 Skill 想了想，调了 LLM 做翻译。最后你拿到了翻译结果——但这个过程多花了不止一倍的 token。

更隐蔽的浪费：你问 Agent "CAP 定理是什么意思"，Agent 觉得这是个"深度问题"，帮你调了 search-agent 去搜索。search-agent 搜了一圈，用 LLM 总结了一下，告诉你答案。但 CAP 定理是计算机科学的常识——Agent 自己就知道答案，根本不需要搜索。

这就是 Token Saver 要解决的问题。它不是事后诸葛亮，而是在你派发任务之前，先帮你分析：这个任务里哪些部分根本不需要工具，LLM 自己就能做。

§Q 快速上手

触发方式

• "帮我分析一下这个任务能不能省 token"
• "检查这个需求是否需要那么多工具"
• "这任务有必要调 file-agent 吗"
• "看看能不能精简一下工具调用"
• "帮我省 token"

工作模式

§1 核心能力

Token Saver 是一款纯本地运行的命令行分析工具。核心脚本 scripts/token_analyzer.py 完成全部分析逻辑。

它怎么工作

用户输入任务描述
      │
      ▼
加载工具清单 (skills_registry.json)
      │
      ▼
特征匹配引擎
├── LLM 原生能力检测（7 大类：知识问答/文本处理/代码解释/方案设计/逻辑推理/格式转换/简单计算）
├── 工具触发词匹配（逐个工具检测是否有匹配的触发特征词）
└── 特殊规则覆盖（翻译内容在输入中→跳过翻译Skill；文件路径无操作→跳过file-agent）
      │
      ▼
逐工具判断：需要 OR 可省略
      │
      ▼
输出分析报告（可读 + JSON）

输出的报告包含什么

严重程度分级

§R 核心铁律

1. 只建议不强制执行：标记"可省略"不代表禁止调用，最终决定权在 Agent 或用户
2. 宁可漏判不可误判：不确定时标记为"需要调用"，避免误删必要工具导致任务失败
3. 规则可解释：每一条建议必须附带具体理由，不说"可能可以省略"
4. 零网络零依赖：纯本地运行，不联网、不装第三方包
5. 清单可扩展：新增工具只需编辑 skills_registry.json，不改代码

§A 结构化异常处理

§B 常见错误与纠正

§C 能力边界

Token Saver 能做到的：
- 基于关键词匹配判断任务是否需要外部工具
- 识别 LLM 原生能力范围内的任务
- 输出结构化的省 token 建议报告

Token Saver 做不到的：
- 不保证 100% 准确——关键词匹配有局限性
- 不感知对话上下文——只分析单条任务描述，不知道历史对话中已有哪些信息
- 不替代 Agent 的路由决策——Agent 可能有其他理由必须调用某个工具
- 不计算实际 token 数量——只给相对节省建议
- 不自动拦截工具调用——是一个分析建议工具，不是拦截器

§D 避坑指南

§E FAQ

Q：分析结果说"可省略"，我该不该省？
A：建议优先省。但如果该工具的输出是后续步骤的输入，保留它。Token Saver 只看单任务，不知道你的完整工作流。

Q：为什么翻译有时候建议省、有时候不省？
A：取决于翻译内容在哪。内容已经在你的输入里 → LLM 直接翻 → 省。内容是文件或网页 → 需要先读取 → 不省。

Q：能分析历史对话里已经完成的任务吗？
A：当前版本只分析你输入的任务描述文本。把历史任务的描述粘贴进来就可以分析。

Q：怎么添加新的工具到分析清单？
A：编辑 scripts/skills_registry.json，按已有条目的格式添加新工具即可。需要填：name / type / triggers / cost / llm_can_do / replaceable_scenarios。

§F 版本历史

§G 完整演示

命令行调用

# 单任务分析
python scripts/token_analyzer.py "帮我总结一下CAP定理，然后保存到桌面"

# 批量审计
echo -e "翻译：Hello World\n搜索2024年GDP数据\n设计一个数据库表结构" | python scripts/token_analyzer.py --stdin

# 交互模式
python scripts/token_analyzer.py --interactive

分析报告示例

输入：翻译这段英文：The quick brown fox jumps over the lazy dog，然后保存到桌面

============================================================
📊 Token 消耗分析报告
============================================================

📝 任务: 翻译这段英文：The quick brown fox jumps over the lazy dog，然后保存到桌面

📌 结论: ⚠️ 可省 2 个调用：1 个无需工具 + 1 个LLM可替代。

----------------------------------------
🟢 LLM 原生能力（不需要任何工具）
----------------------------------------
  • [文本处理] → 内容已在对话上下文中时，LLM直接处理

----------------------------------------
🔍 工具级分析
----------------------------------------

  🟢 各种Skill（翻译等）(skill, 消耗: medium)
     触发词: 翻译
     建议: 🟢 可跳过，LLM直接处理
     理由: 翻译内容已在用户输入中，LLM可直接翻译，无需调用翻译Skill

  🔴 file-agent (agent, 消耗: high)
     触发词: 保存到
     建议: 🔴 需要调用（文件系统操作与文档处理，需要物理文件访问）

----------------------------------------
💰 节省建议
----------------------------------------
  严重程度: significant
  可省略调用数: 2
  建议: 发现 1 个子任务属于LLM原生能力（无需工具），1 个工具调用可被LLM替代。
============================================================

解读：翻译这一步完全不需要调翻译 Skill——LLM 已经看到了要翻译的内容，直接翻就行。但"保存到桌面"这一步确实需要 file-agent，因为要物理写入文件系统。最终建议：翻译 Skill 可以省，file-agent 必须留。

文件结构

token-saver/
├── SKILL.md                          # 本文件（路由层）
├── 需求说明书.md                      # 需求文档
├── README.md                         # 快速概述
└── scripts/
    ├── skills_registry.json           # 工具清单配置（可扩展）
    └── token_analyzer.py              # 核心分析引擎（可直接运行）

（内容由AI生成，仅供参考）