docs(zh-CN): sync Chinese docs with latest upstream changes

This commit is contained in:
neo
2026-03-21 12:55:58 +08:00
parent 0af0fbf40b
commit e73c2ffa34
85 changed files with 11028 additions and 747 deletions

View File

@@ -0,0 +1,143 @@
---
name: context-budget
description: 审核Claude Code上下文窗口在代理、技能、MCP服务器和规则中的消耗情况。识别膨胀、冗余组件并提供优先的令牌节省建议。
origin: ECC
---
# 上下文预算
分析 Claude Code 会话中每个已加载组件的令牌开销,并提供可操作的优化建议以回收上下文空间。
## 使用时机
* 会话性能感觉迟缓或输出质量下降
* 你最近添加了许多技能、代理或 MCP 服务器
* 你想知道实际有多少上下文余量
* 计划添加更多组件,需要知道是否有空间
* 运行 `/context-budget` 命令(本技能为其提供支持)
## 工作原理
### 阶段 1清单
扫描所有组件目录并估算令牌消耗:
**代理** (`agents/*.md`)
* 统计每个文件的行数和令牌数(单词数 × 1.3
* 提取 `description` 前言长度
* 标记:文件 >200 行(繁重),描述 >30 词(臃肿的前言)
**技能** (`skills/*/SKILL.md`)
* 统计 SKILL.md 的令牌数
* 标记:文件 >400 行
* 检查 `.agents/skills/` 中的重复副本 — 跳过相同副本以避免重复计数
**规则** (`rules/**/*.md`)
* 统计每个文件的令牌数
* 标记:文件 >100 行
* 检测同一语言模块中规则文件之间的内容重叠
**MCP 服务器** (`.mcp.json` 或活动的 MCP 配置)
* 统计配置的服务器数量和工具总数
* 估算模式开销约为每个工具 500 令牌
* 标记:工具数 >20 的服务器,包装简单 CLI 命令的服务器 (`gh`, `git`, `npm`, `supabase`, `vercel`)
**CLAUDE.md**(项目级 + 用户级)
* 统计 CLAUDE.md 链中每个文件的令牌数
* 标记:合并总数 >300 行
### 阶段 2分类
将每个组件归入一个类别:
| 类别 | 标准 | 操作 |
|--------|----------|--------|
| **始终需要** | 在 CLAUDE.md 中被引用,支持活动命令,或匹配当前项目类型 | 保留 |
| **有时需要** | 特定领域(例如语言模式),未在 CLAUDE.md 中引用 | 考虑按需激活 |
| **很少需要** | 无命令引用,内容重叠,或无明显的项目匹配 | 移除或延迟加载 |
### 阶段 3检测问题
识别以下问题模式:
* **臃肿的代理描述** — 前言中描述 >30 词,会在每次任务工具调用时加载
* **繁重的代理** — 文件 >200 行,每次生成时都会增加任务工具的上下文
* **冗余组件** — 重复代理逻辑的技能,重复 CLAUDE.md 的规则
* **MCP 超额订阅** — >10 个服务器,或包装了可免费使用的 CLI 工具的服务器
* **CLAUDE.md 臃肿** — 冗长的解释、过时的部分、本应成为规则的指令
### 阶段 4报告
生成上下文预算报告:
```
Context Budget Report
═══════════════════════════════════════
Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)
Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component │ Count │ Tokens │
├─────────────────┼────────┼───────────┤
│ Agents │ N │ ~X,XXX │
│ Skills │ N │ ~X,XXX │
│ Rules │ N │ ~X,XXX │
│ MCP tools │ N │ ~XX,XXX │
│ CLAUDE.md │ N │ ~X,XXX │
└─────────────────┴────────┴───────────┘
⚠ Issues Found (N):
[ranked by token savings]
Top 3 Optimizations:
1. [action] → save ~X,XXX tokens
2. [action] → save ~X,XXX tokens
3. [action] → save ~X,XXX tokens
Potential savings: ~XX,XXX tokens (XX% of current overhead)
```
在详细模式下,额外输出每个文件的令牌计数、最繁重文件的行级细分、重叠组件之间的具体冗余行,以及 MCP 工具列表和每个工具模式大小的估算。
## 示例
**基本审计**
```
User: /context-budget
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)
```
**详细模式**
```
User: /context-budget --verbose
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
MCP tool list with per-tool sizes, duplicated rule lines side by side
```
**扩容前检查**
```
User: I want to add 5 more MCP servers, do I have room?
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
Recommendation: remove 2 CLI-replaceable servers first to stay under 40%
```
## 最佳实践
* **令牌估算**:对散文使用 `words × 1.3`,对代码密集型文件使用 `chars / 4`
* **MCP 是最大的杠杆**:每个工具模式约消耗 500 令牌;一个 30 个工具的服务器开销超过你所有技能的总和
* **代理描述始终加载**:即使代理从未被调用,其描述字段也存在于每个任务工具上下文中
* **详细模式用于调试**:需要精确定位导致开销的确切文件时使用,而非用于常规审计
* **变更后审计**:添加任何代理、技能或 MCP 服务器后运行,以便及早发现增量