prompt-compression

适用场景

在将文档、框架参考资料、API 索引、编码指南或任何结构化知识压缩为精简格式，以便纳入 AGENTS.md、CLAUDE.md 或系统提示词时，请使用此技能。目标是在尽可能减少 token 用量的同时，实现最高的信息密度。

背景

Vercel 的研究（2026 年 1 月）表明，在 AGENTS.md 中放入一个 8KB 的压缩文档索引，评测通过率达到 100%；相比之下，基线为 53%，带有明确触发说明的技能为 79%。被动上下文（始终加载）优于主动检索（由 Agent 决定是否调用），因为它消除了决策环节。压缩是关键推动因素——它让被动上下文变得可行，又不会撑爆上下文窗口。

关键规则

1. 文件引用使用竖线分隔的索引格式

错误（Agent 会这样做）：

## Documentation

- Getting Started: See docs/getting-started.md for installation instructions
- Routing: See docs/routing.md for route definitions
- API Routes: See docs/api-routes.md for API endpoint documentation

正确：

[Docs Index]|root: ./docs |getting-started:{installation.md,project-structure.md}
|routing:{defining-routes.md,dynamic-routes.md,middleware.md}
|api:{endpoints.md,auth.md,validation.md}

原因： 竖线分隔格式可减少 70-80% 的 token，同时仍能被所有主流大模型解析。需要时，Agent 仍可定位并读取具体文件。

2. 将规则压缩为单行指令

错误（Agent 会这样做）：

## Coding Standards

### Import Organization

When writing imports, always organize them in the following order:

1. Built-in Node.js modules (fs, path, etc.)
2. External dependencies (react, express, etc.)
3. Internal modules (relative imports)
4. Type imports

Make sure to separate each group with a blank line.

正确：

[Standards] |imports: builtin > external > internal > types (blank line between groups)

原因： Agent 不需要对话式解释。压缩后的指令只需 5% 的 token，就能传达相同的行为要求。

3. 删除解释性文字，只保留可执行内容

错误：

## Authentication

Our application uses JWT-based authentication. When a user logs in, the server generates a JWT token
that contains the user's ID and role. This token is sent back to the client and stored in an
httpOnly cookie. On subsequent requests, the middleware extracts the token from the cookie, verifies
it, and attaches the user object to the request.

The token expires after 24 hours, at which point the user must log in again. Refresh tokens are not
currently implemented but are planned for a future release.

正确：

[Auth]|JWT in httpOnly cookie|24h expiry|no refresh tokens |middleware: extract token > verify >
attach user to req |login flow: validate creds > generate JWT(id,role) > set cookie

原因： Agent 需要的是行为约定（该怎么做），而不是背景叙述（为何如此设计）。删除历史、动机和未来计划。

4. 使用缩写键和符号

错误：

- Required: true
- Type: string
- Default value: "production"
- Minimum length: 3
- Maximum length: 50

正确：

|env: required string="production" len:3-50

原因： 标准缩写（req、opt、str、int、bool、len、min、max、def）是大模型普遍理解的，可将结构化元数据压缩 80% 以上。

5. 展平嵌套层级

错误：

## Project Structure

### Source Code

#### Components

##### UI Components

- Button.tsx
- Input.tsx
- Modal.tsx

##### Layout Components

- Header.tsx
- Footer.tsx
- Sidebar.tsx

正确：

[Structure]|src/ |components/ui:{Button,Input,Modal}.tsx
|components/layout:{Header,Footer,Sidebar}.tsx

原因： Markdown 标题层级会因空白和重复内容浪费 token。花括号展开和路径前缀更加紧凑，Agent 也同样易于阅读。

6. 添加检索优先的推理指令

压缩后的上下文引用了可检索文件时，务必包含此指令：

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any [DOMAIN] tasks.

原因： 没有这条指令，Agent 会默认依赖训练数据（这些数据可能已经过时）。这一行指令就能将行为从“凭记忆猜测”转变为“查阅资料”，这是 Vercel 的通过率达到 100% 的关键因素。

7. 保留结构边界

错误：

routingdefiningdynamicmiddlewareapiendpointsauthvalidation

正确：

|routing:{defining,dynamic,middleware} |api:{endpoints,auth,validation}

原因： 过度压缩会破坏可解析性。使用分隔符（竖线、花括号、冒号）保留逻辑分组。Agent 必须能够定位到具体文件或章节。

8. 完整框架索引的目标大小为 8-15KB

完整框架文档索引（指向可检索文档的文件树）应压缩至 8-15KB。这个范围最为理想，因为它：

• 可轻松放入 AGENTS.md，与项目专属上下文并存
• 使每次请求的 token 成本保持在 2-4K token 以内
• 让 Agent 在框架相关任务上的准确率接近完美

如果压缩后的内容超过 15KB，应拆分为主索引（最常用的 API）和次级索引，供 Agent 按需读取。

压缩流程

1. 确定来源——文档目录、API 参考资料、编码指南、框架文档
2. 提取可执行内容——删除文字说明、动机、历史，以及重复阐述规则的示例
3. 选择格式——文件树使用竖线分隔索引，规则使用单行指令，配置或架构使用缩写键
4. 压缩——使用缩写、花括号展开、路径前缀和符号简写
5. 添加检索指令——如果输出引用了可读取的文件
6. 验证——确认 Agent 仍能定位任何具体信息
7. 测量——比较压缩前后的 token 数量，目标是减少 70-80%

输出格式

文件索引（用于文档目录）

[Topic Index]|root: ./path |IMPORTANT: Prefer retrieval-led reasoning over pre-training-led
reasoning for [TOPIC] |section-a/subsection:{file1.md,file2.md,file3.md}
|section-b:{file1.md,file2.md}

规则/标准（用于编码指南）

[Standards] |naming: camelCase vars, PascalCase components, UPPER_SNAKE constants |imports:
builtin > external > internal > types |errors: always use Result<T,E>, never throw in library code
|tests: colocate with source, name: \*.test.ts, min coverage 80%

API 参考（用于端点文档）

[API]|base: /api/v2 |GET /users?page,limit -> User[]|auth:bearer |POST /users {name,email,role?} ->
User|auth:admin |DELETE /users/:id -> void|auth:admin

配置/Schema（用于结构化元数据）

[Config] |db: host=localhost port=5432 pool:5-20 timeout:30s |cache: redis ttl:5m max:1000
prefix:"app:" |auth: jwt secret=$JWT_SECRET exp:24h algo:HS256

反模式

• 压缩 Agent 已经熟悉的内容（基本语言语法、标准库）
• 删除展示非显而易见的 API 用法的代码示例
• 压缩错误消息或边缘情况文档（Agent 需要原样获取这些内容）
• 过度压缩，以至于人类无法审核或维护
• 将完整文档内容放在 AGENTS.md 中，而不是放置指向各文件的索引
• 忘记检索式推理指令