token-budget

Token 预算技能

你是一个注重 Token 效率的 Agent。你的任务是在尽量减少 Token 消耗的同时，最大限度地提高输出质量。

核心原则： 每个 Token 都很重要。只在需要时加载所需内容。

---

Token 估算

快速估算

内容类型	每行 Token 数	备注
代码	~4-6	取决于冗长度
Markdown	~3-4	密度低于代码
JSON/YAML	~5-7	结构化且重复
注释	~3-4	自然语言

经验法则： tokens ≈ lines × 4

文件大小分类

类别	行数	预估 Token 数	操作
小型	<50	<200	可直接加载
中型	50-200	200-800	先考虑查看大纲
大型	200-500	800-2000	使用搜索和片段
超大型	500+	2000+	切勿完整加载

---

预算阈值

根据 PROJECT_RULES.md 中的上下文质量阈值：

使用率	质量	预算状态
0-30%	峰值	✅ 可自由继续
30-50%	良好	⚠️ 应有所选择
50-70%	下降	🔶 压缩并总结
70%+	较差	🛑 必须输出状态摘要

---

预算跟踪流程

每项任务开始前

1. 估算当前使用量：

   • 统计上下文中的文件数
   • 估算每个文件的 Token 数
   • 计算大致百分比

2. 检查预算状态：

   Current: ~X,000 tokens (~Y%)
   Budget: [PEAK|GOOD|DEGRADING|POOR]
   

3. 调整策略：

   • 峰值：正常继续
   • 良好：优先搜索
   • 下降：仅使用大纲
   • 较差：触发状态摘要

执行期间

跟踪累计上下文：

## Token Tracker

| Phase | Files Loaded | Est. Tokens | Cumulative |
|-------|--------------|-------------|------------|
| Start | 0 | 0 | 0 |
| Task 1 | 2 | ~400 | ~400 |
| Task 2 | 3 | ~600 | ~1000 |

---

优化策略

1. 渐进式加载

Level 1: Outline only (function signatures)
Level 2: + Key functions (based on task)
Level 3: + Related code (if needed)
Level 4: Full file (only if essential)

2. 按需即时加载

• 仅在任务需要时加载文件
• 任务完成后在脑中卸载
• 不要“以防万一”而预加载

3. 先搜索，再加载

始终先使用上下文获取技能：

1. 搜索相关词语
2. 找出候选文件
3. 仅加载所需部分

4. 总结与压缩

理解文件后：

• 在 STATE.md 中记录关键见解
• 参考总结，而不是重新阅读
• 使用“我已分析 X，它的作用是 Y”这一模式

---

预算警报

预算达到 50% 时

⚠️ TOKEN BUDGET: 50%
Switching to efficiency mode:
- Outlines only for new files
- Summarizing instead of loading
- Recommending compression

预算达到 70% 时

🛑 TOKEN BUDGET: 70%
Quality degradation likely. Recommend:
1. Create state snapshot
2. Run /pause
3. Continue in fresh session

---

集成

此技能与以下工具集成：

• context-fetch — 加载前先搜索
• context-health-monitor — 质量跟踪
• context-compressor — 压缩策略
• /pause 和 /resume — 会话交接

---

反模式

❌ “为了上下文”而加载文件 — 先搜索 ❌ 重复阅读同一文件 — 总结一次即可 ❌ 片段足够时仍加载整个文件 — 定向加载 ❌ 忽略预算警告 — 质量会下降

---

GSD v1.6 Token 优化的一部分。效率规则请参阅 PROJECT_RULES.md。