ai-context-kit

ai-context-kit

如何衡量上下文的 Token 成本？

你花了数小时编写完美的 .md 上下文文件，结果却发现 Agent 变差了。
这不是 Bug。没人衡量上下文成本时，就会发生这种情况。

     

 

---

你编写了一个 CLAUDE.md。接着有人添加了 .cursor/rules/。然后一位队友放进一个 AGENTS.md。之后又有人从博客文章里复制了一个 .cursorrules 文件。旧文件却一个也没人删除。

六个月后，你的项目里有四个相互重叠、彼此矛盾的上下文文件，每次对话都会塞入 8,000 个 Token 的目录列表和“遵循最佳实践”之类的内容。你的 Agent 全都照做。它变得更慢，也更困惑。你却怪罪模型。

一项苏黎世联邦理工学院的研究（2026 年 2 月）测量了向 Agent 提供上下文文件时实际会发生什么：

• 与不提供任何内容相比，自动生成的上下文文件会让任务成功率降低
• 人工编写的文件仅将准确率提高了 4%
• 浪费的 Token 让推理成本增加了 20% 以上
• 某些模型的性能会下降，因为 Agent 变得过于顺从——遵循不必要的指令，而不是解决实际问题

我在自己的项目中也反复遇到这个问题，于是构建了 ai-context-kit——一个将上下文视为预算的工具包。衡量它、精简它，只注入当前任务所需的内容。

import { loadRules, measure, lint, select } from "ai-context-kit";

const rules = await loadRules("./");

measure(rules, 4000); // what does your context cost?
lint(rules); // conflicts? duplicates? dead weight?
select(rules, {
  task: "fix auth bug", // only inject what matters
  budget: 2000, // stay within token budget
});

---

快速开始

npm install ai-context-kit

在任意项目中运行 CLI，查看你实际注入了什么：

npx ai-context-kit measure

ai-context-kit measure - 6 rule file(s)

  Total: 4,821 tokens

  ############ 2,100 tokens (44%) - .cursor/rules/conventions.mdc
  ######## 1,200 tokens (25%) - CLAUDE.md
  ##### 890 tokens (18%) - .cursor/rules/api-patterns.mdc
  ## 340 tokens (7%) - AGENTS.md
  ## 180 tokens (4%) - .cursor/rules/testing.mdc
  # 111 tokens (2%) - .github/copilot-instructions.md

然后运行 lint：

npx ai-context-kit lint

ai-context-kit lint - 6 rule file(s)

  [!] .cursor/rules/conventions.mdc
      Rule is 2100 tokens. Consider splitting to keep each file under 2000 tokens.

  [x] CLAUDE.md
      Conflicts with AGENTS.md: "always use semicolons" vs "never use semicolons"

  [!] CLAUDE.md
      Duplicated line also found in .cursor/rules/conventions.mdc. Duplicates waste tokens.

  [i] AGENTS.md
      Contains vague instruction matching "follow best practices".
      Specific instructions produce better results than general advice.

  Score: 70/100 (FAILED)

这就是猜测与掌握事实的区别。

---

有何不同

	其他方案	ai-context-kit
上下文成本	无人衡量	统计每个文件的 token 数，并检查预算
冲突	Agent 做出奇怪的操作时，你才会发现	自动检测所有文件中的矛盾
重复内容	同一条规则出现在 3 个文件中，消耗 3 倍 token	标记重复内容并评分
任务相关性	每次都注入所有规则	select() 只选取与当前任务相关的内容
多工具支持	被限制在某个 IDE 的格式中	兼容 Cursor、Claude Code、Copilot、Windsurf、Cline
CI	听天由命	lint 遇到错误时以代码 1 退出。可直接加入流水线

---

可以解答哪些问题

1. 我注入了多少上下文？ 统计每个文件的 token 数、占比，并检查预算
2. 规则之间是否相互冲突？ 检测所有文件和格式中的冲突
3. 哪些内容在浪费 token？ 目录列表、重复内容、含糊的建议
4. 哪些规则与当前任务相关？ 根据任务选择相关规则，并遵守 token 预算

---

工作原理

ai-context-kit 会读取生态系统中的每种上下文文件格式，解析 frontmatter，估算 token 成本，并提供用于分析和管理这些文件的工具。

loadRules()	自动检测 .cursor/rules/、.cursorrules、CLAUDE.md、AGENTS.md、copilot-instructions.md、.windsurfrules、.clinerules
measure()	统计每条规则的 token 成本、占总量的比例，并检查预算
lint()	检测冲突、重复内容、冗余、含糊指令和无用的目录树。评分范围为 0-100
select()	选取与当前任务相关的规则，并遵守 token 预算。优先选择 alwaysApply 规则，其次按相关性选择
sync()	维护唯一可信来源。在 .cursor/rules/ 中编写一次，即可同步到 CLAUDE.md、AGENTS.md 等文件
init()	根据研究成果提供包含实用建议的入门模板

---

API

loadRules(rootDir?)

const rules = await loadRules("./");
// Finds every context file in the project

const rules = await loadRules(".cursor/rules/");
// Or load from a specific directory

返回 RuleFile[]，其中包含已解析的 frontmatter、正文、格式、路径和 token 数。

measure(rules, budget?)

const report = measure(rules, 4000);

report.totalTokens; // 3847
report.overBudget; // false
report.rules; // sorted by size, each with tokens + percentage

lint(rules)

const report = lint(rules);

report.score; // 85/100
report.passed; // true (no errors, warnings don't fail)
report.issues; // array of { rule, path, severity, message }

Lint 会检测以下问题：

规则	严重程度	检测内容
token-budget	警告/错误	超过 2,000 个 token（警告）或 5,000 个 token（错误）的文件
empty-rule	警告	过短、无法发挥作用的文件
duplicate-content	警告	多个文件中重复出现的相同指令
conflict	错误	一个文件中写着“始终使用 X”，另一个文件中却写着“绝不使用 X”
directory-listing	警告	Agent 无需查看、行数达到 10 行以上的目录树
vague-instruction	信息	“遵循最佳实践”“编写干净的代码”“保持一致”等指令

select(rules, options)

研究的核心结论：不要注入所有内容，只挑选重要的内容。

const relevant = select(rules, {
  task: "fix auth bug in /api/auth",
  budget: 2000,
  tags: ["security", "api"],
  exclude: ["style"],
});

评分规则：frontmatter 中的 alwaysApply: true 优先级最高。接下来，根据任务词与文件路径和内容的匹配情况评分。然后是标签匹配。预算会得到遵守——按评分从高到低纳入规则，直到预算用完。

sync(options)

规则只写一次，随处同步。

await sync({
  source: ".cursor/rules/",
  targets: ["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md"],
});

支持使用 dryRun: true 在不写入的情况下预览更改。

init(options?)

await init({ format: "cursor-rules" });
// Creates .cursor/rules/conventions.mdc with research-backed starter template

---

命令行

npx ai-context-kit lint                    # find issues
npx ai-context-kit lint --json             # machine-readable output
npx ai-context-kit measure                 # token cost breakdown
npx ai-context-kit measure --budget 4000   # check against budget
npx ai-context-kit sync --source .cursor/rules/ --target CLAUDE.md,AGENTS.md
npx ai-context-kit init                    # scaffold starter rules
npx ai-context-kit init --format claude-md

所有命令都支持 --path <dir>，用于指定其他项目根目录。出现错误时，lint 会以代码 1 退出（警告不会导致退出）。

---

与 Vercel AI SDK / LangChain / 自定义 Agent 配合使用

这不只是为 Cursor 准备的。如果你使用 Vercel AI SDK、LangChain 或自己的框架来构建 Agent，ai-context-kit 可以解决同样的问题：你在系统提示词中塞入了多少上下文？这些上下文究竟是在帮忙还是在添乱？

import { loadRules, select } from "ai-context-kit";
import { generateText } from "ai";

const allRules = await loadRules("./rules");

const relevant = select(allRules, {
  task: userMessage,
  budget: 3000,
});

const systemPrompt = relevant.map((r) => r.body).join("\n\n");

const { text } = await generateText({
  model: openai("gpt-4o"),
  system: systemPrompt,
  prompt: userMessage,
});

任何接受系统提示词字符串的框架都适用。任何以 Markdown 文件存储的规则都适用。

---

支持的格式

格式	文件	使用者
Cursor（现代）	.cursor/rules/*.mdc	Cursor IDE
Cursor（旧版）	.cursorrules	Cursor IDE
Claude Code	CLAUDE.md	Claude Code
AGENTS.md	AGENTS.md	跨 Agent 标准
GitHub Copilot	.github/copilot-instructions.md	GitHub Copilot
Windsurf	.windsurfrules	Windsurf
Cline	.clinerules	Cline

ai-context-kit 会根据文件路径检测格式，无需配置。

---

为什么不直接编写更好的规则？

苏黎世联邦理工学院的研究测试了人工编写和大模型生成的上下文文件。人工编写的文件表现更好，但优势只有 4%。真正的问题不在于质量，而在于数量。更多上下文意味着要消耗更多 token 来处理当前任务并不需要的指令。最佳策略是减少规则，只保留与任务相关的规则，而不是润色文字。

Token 估算有多准确？

ai-context-kit 使用每 4 个字符约等于 1 个 token 的近似值。这种方法刻意设计得简单快速，足以用于预算控制和比较（GPT-4 处理英文文本时平均约为每 4 个字符 1 个 token）。如果需要精确计数，可以将输出通过管道传给 tiktoken 或模型的 tokenizer。

这能在 CI 中使用吗？

可以。npx ai-context-kit lint 遇到错误时返回退出代码 1，通过时返回 0。你可以像添加 eslint 一样将它加入 CI 流水线。--json 标志会输出机器可读的结果，方便自定义报告。

---

技术栈

组件	技术
语言	严格模式
测试
打包器	ESM + CJS
依赖项	零运行时依赖

---

参与贡献

欢迎提交 PR。无论是新增 lint 规则、格式检测器还是修复 bug，都请查看贡献指南。

---

作者

---

_{此 README 使用 README Builder 构建}

许可证

MIT © Ofer Shapira

---

为此仓库点星 · 复刻此仓库 · 报告 bug · 参与讨论