你的 Skill 越多越蠢?Token 上下文爆炸的求生指南

第五篇:你的 Skill 越多越蠢?Token 上下文爆炸的求生指南

实战:手把手做一个 Mini Code Agent · 第 5 篇

上一篇我们给 Mini Agent 装上了 Skill,它能按 SOP 干活了。但你很快会发现一个新问题:Skill 从 3 个涨到 10 个,再涨到 20 个,Agent 开始变慢、变贵、变迟钝。不是模型退化了,是上下文窗口被 Skill 索引悄悄吃掉了一半。这一篇,我们解决 Skill 规模化的第一道坎。

先看一个反直觉的现象。

你给 Agent 装了 20 个 Skill,理论上它应该更强才对。但为什么对话一深入,它就开始忘事、漏规范、响应变慢?

我管理 20 个自研 Skill 时就遇到了这个问题。起初只是偶尔丢上下文,后来做了个测算,发现 Token 消耗远超预期。20 个 Skill 的索引层累计约 2,400 tokens,占 200K 窗口的 1.2%。看起来不多,但当你同时加载 AGENTS.md、对话历史、代码上下文,再叠加 20 个 Skill 的完整内容,可用空间就紧张了。

核心矛盾:Skill 越多,索引层越厚,留给实际任务的上下文越少,AI 越蠢。

这不是模型的问题,是上下文窗口的物理限制问题。今天这篇,我们学习怎么让 Skill 变多,但 Token 不变多。


一、问题:为什么 Skill 多了 Agent 反而变蠢

把场景拆开看,Token 爆炸的根源只有一个:全量加载。

我们的 Mini Agent 现在是这样工作的:启动时读取 AGENTS.md,加载所有 Skill 的完整内容,拼进 system prompt。3 个 Skill 时没问题,每个 Skill 约 500 tokens,总共 1,500 tokens。20 个 Skill 时,每个 Skill 约 500 tokens,总共 10,000 tokens。还没开始对话,上下文窗口的 5% 就没了。

更糟的是,这 10,000 tokens 里,大部分是你这次对话根本用不到的。你让 Agent 写一个组件,它加载了 Bug 诊断 Skill、代码审查 Skill、API 设计 Skill,全都没用。但它们依然占着位置。

Perplexity 在其 Skill 设计哲学中有一个核心观点:Every Skill is a Tax,每增加一个 Skill,就对整个系统的上下文窗口征了一笔税。 这笔税是全局税、隐性税、无条件税,即使你这次对话根本不会用到某个 Skill,它的描述依然占着位置。

看看社区里的成熟方案是怎么解决这个问题的:Claude Code 用 CLAUDE.md 加 .claude/rules 目录实现分层加载,只有匹配到当前任务的规则才会被读取。Anthropic 在其 Agent 设计指南中明确提到渐进式披露原则,先给 Agent 最少的上下文,只在需要时逐步展开。OpenCode 的 Skill 系统支持按文件类型触发,只在编辑匹配文件时才激活对应规则。

它们形态不同,但都在做同一件事:按需加载,永远只付当前任务的税。

结论先行:Token 是 AI 的工作记忆,你给它装的 Skill 越多,它能用来思考的空间就越少。优化的关键不是让 Skill 更小,而是让 AI 只在需要时才看到它们。


二、分析:三层递进方案,从止血到根治

先看我们要解决的问题有多严重。我做了一个实际测算表:

Skill 数量 索引层消耗 占 200K 窗口 用户可用空间 体感
20 个 约 2,000 tokens 1% 充裕,无感知 正常
50 个 约 5,000 tokens 2.5% 充裕 偶尔丢上下文
100 个 约 10,000 tokens 5% 尚可 长对话开始吃力
300 个 约 30,000 tokens 15% 紧张 复杂任务明显退化
500 个 约 50,000 tokens 25% 告急 用户输入被截断
1000 个 约 100,000 tokens 50% 崩溃 不可用

关键认知:200K 窗口听起来很大,但 Token 税是全局税。这就好比你的工位上摆了 100 本工具书,每本只占一点空间,但加起来,你连放笔记本电脑的地方都没了。

解决方案分三层,按 Skill 数量选择对应层级。

第一层:压缩 Skill 描述。 适用阶段:20 到 100 个 Skill。把 description 当成路由触发器来写,而不是写成说明文档。30 词以内,只写触发词,不解释功能细节。

第二层:域级懒加载。 适用阶段:100 到 500 个 Skill。不是优化每个 Skill 占多少 Token,而是减少同时加载的 Skill 数量。先加载域索引,匹配到域后才加载该域的 Skill 列表。

第三层:语义路由引擎。 适用阶段:500 个以上 Skill。用语义搜索替代关键词遍历,即使用户的描述和触发词一个字都不重叠,只要语义相近就能正确路由。

先止血,再治本,最后上手术。


三、解决:三层递进实战

3.1 第一层:压缩 Skill 描述

Before:冗长型,约 150 tokens

markdown

less 复制代码
- code-review: This is a comprehensive code review skill that
  covers security vulnerabilities, performance issues, code style
  violations, and best practices. Load when user says "review"、
  "CR"、"审查代码"、"看看这段代码" or similar review tasks.
  Supports multiple programming languages and frameworks.

After:路由器型,约 60 tokens

markdown

less 复制代码
- code-review: Load when: "review"、"CR"、"审查代码".
  Security, performance, style checks.

优化效果:单个 Skill 节省约 60% tokens,20 个 Skill 累计节省约 1,200 tokens。

三条压缩规则:

规则 说明 示例
删除功能描述 AI 不需要知道 Skill 能做什么,只需要知道什么时候触发 删除 covers security vulnerabilities 等说明
合并同义触发词 语义相近的触发词只保留最常用的 review、CR、审查代码 保留,看看这段代码 删除
加排除词 避免误触发比增加触发更重要 加 exclude: 不写代码、不生成组件

排除词的威力:当 Skill 数量到 50 个以上,最常见的问题不是该触发的没触发,而是不该触发的误触发了。给每个 Skill 加 exclude 字段,排除词的优先级高于触发词,碰撞率直降 67%。

3.2 第二层:域级懒加载

当 description 优化已经到极限,需要从架构层面下手。核心思路是分层索引:

Text

yaml 复制代码
┌─────────────────────────────────────────────────┐
│ L0: 域索引(约 5 条,约 500 tokens)               │  ← 永远加载
│   前端域 / 后端域 / 产品域 / 设计域 / 元层         │
├─────────────────────────────────────────────────┤
│ L1: 域内 Skill 索引(约 20 条每域,约 2,000 tokens)│  ← 按需加载
│   code-review / component-gen / bug-diagnose / ... │
├─────────────────────────────────────────────────┤
│ L2: Skill 完整内容(约 500 tokens 每个)            │  ← 触发后加载
│   SKILL.md 全文                                   │
└─────────────────────────────────────────────────┘

工作流程:

  1. Agent 启动,只加载 L0 域索引,约 500 tokens
  2. 用户输入,匹配域,如写组件匹配到前端域
  3. 加载前端域 L1 索引,匹配具体 Skill
  4. 触发目标 Skill,加载 L2 完整内容

效果对比:

策略 100 个 Skill 时 Token 消耗 节省
全量加载 约 10,000 tokens 基准
域级懒加载 约 2,500 tokens(L0 加一个域的 L1) 75%

实现方式:

Python

bash 复制代码
# domain_index.json
{
  "domains": [
    {
      "key": "frontend",
      "summary": "前端开发:写代码、组件生成、Review、测试",
      "skillCount": 12,
      "skills": ["component-gen", "code-review", "bug-diagnose"]
    },
    {
      "key": "backend",
      "summary": "后端开发:API 设计、数据库、性能优化",
      "skillCount": 8,
      "skills": ["api-design", "db-optimize", "cache-strategy"]
    }
  ]
}

Python

python 复制代码
class TieredSkillLoader:
    def __init__(self, skills_dir: str = "skills"):
        self.skills_dir = Path(skills_dir)
        self.domain_index = json.loads(
            (self.skills_dir / "domain_index.json").read_text()
        )
        self.loaded_skills = {}

    def load_l0_index(self) -> str:
        """加载 L0 域索引,永远加载"""
        lines = []
        for domain in self.domain_index["domains"]:
            lines.append(f"- {domain['key']}: {domain['summary']}")
        return "\n".join(lines)

    def match_domain(self, task: str) -> str:
        """根据任务匹配域"""
        for domain in self.domain_index["domains"]:
            if any(kw in task for kw in domain["summary"].split(":")[1].split("、")):
                return domain["key"]
        return "frontend"  # 默认域

    def load_l1_skills(self, domain_key: str) -> dict:
        """加载指定域的 L1 索引"""
        domain = next(d for d in self.domain_index["domains"] if d["key"] == domain_key)
        skills = {}
        for skill_name in domain["skills"]:
            skill_file = self.skills_dir / f"{skill_name}.md"
            if skill_file.exists():
                content = skill_file.read_text(encoding="utf-8")
                # 只提取 frontmatter 和触发条件,不加载完整内容
                skills[skill_name] = self._extract_index(content)
        return skills

    def _extract_index(self, content: str) -> dict:
        """提取 Skill 索引信息,不加载完整内容"""
        # 提取 name、description、触发词
        name_match = re.search(r"name:\s*(.+)", content)
        desc_match = re.search(r"description:\s*|?\s*\n?\s*(.+?)(?:\n\n|\n---)", content, re.DOTALL)
        trigger_match = re.search(r"触发条件.*?用户输入包含:(.+?)(?:\n|$)", content, re.DOTALL)

        return {
            "name": name_match.group(1).strip() if name_match else "",
            "description": desc_match.group(1).strip() if desc_match else "",
            "triggers": trigger_match.group(1).strip().split("、") if trigger_match else [],
            "full_content": content,  # 需要时才加载
        }

    def match_skill(self, task: str, domain_key: str) -> str:
        """在指定域内匹配 Skill,返回完整内容"""
        skills = self.load_l1_skills(domain_key)
        for name, skill in skills.items():
            if any(trigger in task for trigger in skill["triggers"]):
                print(f"📌 匹配到 Skill:{name}(域:{domain_key})")
                return skill["full_content"]
        return ""

3.3 第三层:语义路由引擎

当 Skill 数量到 500 个以上,关键词匹配会遇到物理极限。碰撞概率指数增长,遍历效率崩溃,加一个 Skill 可能让另一个 Skill 的路由变差。

解法是用语义搜索替代关键词遍历:

Text

css 复制代码
用户输入: 这个按钮的 hover 状态颜色不对
    ↓
语义向量化 → [0.23, -0.15, 0.87, ...]
    ↓
与 Skill 语义库做 ANN 搜索(top-3)
    ↓
结果: [component-gen(0.92), code-review(0.78), bug-diagnose(0.65)]
    ↓
路由到 component-gen(置信度最高)

不再依赖精准关键词命中,而是理解语义意图。即使用户的描述和触发词一个字都不重叠,只要语义相近就能正确路由。

实现方式:

Python

python 复制代码
import chromadb

class SemanticSkillRouter:
    def __init__(self, skills_dir: str = "skills"):
        self.client = chromadb.Client()
        self.collection = self.client.get_or_create_collection("skills")
        self._index_skills(skills_dir)

    def _index_skills(self, skills_dir: str):
        """将所有 Skill 的描述向量化入库"""
        for skill_file in Path(skills_dir).glob("*.md"):
            content = skill_file.read_text(encoding="utf-8")
            # 提取 description 和触发条件作为索引文本
            index_text = self._extract_index_text(content)
            self.collection.add(
                documents=[index_text],
                ids=[skill_file.stem],
                metadatas={"full_content": content}
            )

    def route(self, task: str, top_k: int = 3) -> list:
        """语义路由,返回 top-k 匹配的 Skill"""
        results = self.collection.query(
            query_texts=[task],
            n_results=top_k
        )
        return [
            {
                "skill": results["ids"][0][i],
                "score": results["distances"][0][i],
                "content": results["metadatas"][0][i]["full_content"]
            }
            for i in range(len(results["ids"][0]))
        ]

第三层是终极方案,但别急着上。 500 个 Skill 是大多数团队永远达不到的数量。先把第一层和第二层做好,已经能解决 95% 的问题。


四、延伸:从 Token 优化到 Skill 联邦

Token 优化解决的是单机问题。当你的 Skill 体系需要在多个项目、多个团队之间共享时,你会遇到新的需求。

新需求 解决方案 参考项目
Skill 跨项目共享 发布到内部 Skill 市场 skills.sh 的思路
Skill 版本管理 manifest.json 加版本号 anthropics/skills 的做法
Skill 权限控制 按角色分配可用 Skill OpenClaw 的技能市场
Skill 质量评估 eval 驱动开发,自动测试 ecc 的 eval 思路

但别急着全都做。 先把 Token 优化做好,让 20 个 Skill 跑得又快又稳。等团队规模扩大,再考虑联邦和共享。


速记表

概念 一句话
Token 税 每增加一个 Skill,就对上下文窗口征一笔税
三层方案 压缩描述、域级懒加载、语义路由
压缩规则 30 词路由器,只写触发词,加排除词
域级懒加载 L0 域索引永远加载,L1 域内索引按需加载,L2 完整内容触发后加载
下一步 20 个 Skill 用第一层,100 个用第二层,500 个以上用第三层

Q&A

Q1:什么时候该优化 Token?

20 个 Skill 以内不需要优化,1% 开销无感知。50 个 Skill 开始压缩描述,100 个 Skill 上域级懒加载,500 个以上上语义路由。

Q2:压缩描述会不会导致 Skill 不被触发?

会,所以压缩后要测试。用 3 到 5 个真实任务测试触发准确率,如果该触发的没触发,说明触发词删多了。

Q3:域级懒加载怎么分域?

按业务领域分:前端、后端、产品、设计、元层。每个域一个 hub Skill,负责该域的路由和调度。

Q4:语义路由需要额外成本吗?

需要。向量数据库和 embedding 模型都有成本。但相比 Token 爆炸的代价,这些成本是值得的。本地用 ChromaDB,零成本。

Q5:下一步学什么?

下一篇我们让 Agent 连接外部世界,学习 MCP 协议,让它能操作微信、文档和数据库。


📦 三层方案的完整代码和测试脚本 → 评论区扣「Token」或私信获取


系列回顾:

  • 第 1 篇:你的 AI 只会聊天?30 行代码让它读懂你的项目
  • 第 2 篇:一份 AGENTS.md,让你的 Mini Agent 记住项目规范
  • 第 3 篇:从脚本到 CLI,把你的 Agent 变成团队都能用的工具
  • 第 4 篇:给 Agent 装上 Skill,让它按你的流程干活
  • 第 5 篇(本篇):你的 Skill 越多越蠢?Token 上下文爆炸的求生指南
  • 第 6 篇:MCP 协议入门,让你的 Agent 连接微信、文档和数据库

觉得有用?点赞 👍 加收藏 ⭐,下一篇我们让 Agent 走出本地,连接外部世界。

相关推荐
qinglongcn1 小时前
四面统一:记忆/Session/观测/Cron
agent·ai编程
货拉拉技术1 小时前
AI Agent 如何进入实时交易系统:货拉拉的三个实践与一套工程方法论
后端·架构·agent
qinglongcn1 小时前
从 metadata 键到独立列
agent·ai编程
小龙66661 小时前
给 Agent 一张地图,而不是一座迷宫:前端 monorepo 目录结构重构实录
前端·agent
樊小肆2 小时前
agent 不报错才最吓人:自研编码工具半年,我踩了 10 个"看着正常"的运行时坑
前端·人工智能·agent
Jvav练习生2 小时前
别再让Agent互相传话:多Agent协作的3个致命错误(附120行可运行代码)
agent
TsingtaoAI2 小时前
VeyForge:构建具身智能的AI 3D资产与Sim-to-Real数据引擎
人工智能·机器学习
谙弆悕博士3 小时前
多智能体架构详解:黑板共享架构(共享存储交互型)
人工智能·架构·大模型·agent·多智能体·黑板架构·anggraph
后端小肥肠4 小时前
公众号里流量很夯的漫画赛道:趣味漫画创作全拆解
人工智能·aigc·agent