contextbudget

contextbudget

contextbudget 用于估算目录树在 Agent 上下文窗口中的 Token 开销。它会遍历目录树，估算每个文本文件的开销，将总量与预算进行比较，并报告最大的文件和跳过的子树，方便你在目录树占满整个窗口之前决定排除哪些内容。

诚实地说说估算器

此工具给出的 Token 数是启发式估算值，并非分词器统计结果。contextbudget 会将每个统计的文件解码为 UTF-8 文本，并应用一条确定性规则：tokens = ceil(chars / 4)，其中 chars 是解码后文本的长度。不同模型的实际分词器会以不同方式拆分文本，因此同一个文件经实际分词器处理后会得到不同的数字，有时更高，有时更低。请用这些数字比较不同文件、排出占用最大的文件，并检查目录树是否在大致预算范围内。不要将其视为任何特定模型实际计费或接受内容的精确预测。

安装

npx @reneturcios/contextbudget budget [path]

或者将其作为依赖项安装到你自己的工具中，并使用下方的 MCP 服务形式。此软件包需要 Node 20 或更高版本。

CLI 用法

contextbudget budget [path] [--json]
contextbudget mcp
contextbudget --version

• budget [path]：检查 path 处的目录树，默认值为当前目录。打印易读报告；使用 --json 可打印完整 JSON 报告。
• mcp：通过 stdio 运行 MCP 服务。
• --version：打印版本号。

退出代码：

• 0：判定结果为 WITHIN-BUDGET。
• 1：其他任何判定结果，目前为 OVER-BUDGET。
• 2：用法错误，或目标不存在。
• 141：读取方提前关闭了输出管道（Shell 中可见的 SIGPIPE 等效情况）。

预算

默认预算为 200000 个估算 Token。设置环境变量 CONTEXTBUDGET_BUDGET 为正整数，即可使用其他预算：

CONTEXTBUDGET_BUDGET=50000 contextbudget budget ./src

如果未设置此变量、无法解析其值，或其值不是正数，则使用默认值 200000。

判定规则

• 当估算 Token 总数小于或等于预算时，判定结果为 WITHIN-BUDGET；否则为 OVER-BUDGET。
• 默认情况下，遍历会跳过以下目录，且不会进入这些目录：node_modules、.git、dist、coverage、.next、vendor。
• 超过 1 MiB（1048576 字节）的文件会被跳过且不计入统计。
• 通过检查前 4 KiB 中是否存在 NUL 字节来识别二进制文件；此类文件会被跳过且不计入统计。
• 不会跟随符号链接。

发现项：

• 对每个估算 Token 数超过预算 10% 的统计文件，生成一条高优先级发现项，规则为 large-file。
• 对每个因超过 1 MiB 限制而跳过的文件，生成一条中优先级发现项，规则为 skipped-large。
• 对默认跳过列表中的每个目录，生成一条信息级发现项，规则为 skipped-dir。

排序是确定性的：文件按估算 Token 数降序排列，相同时按路径升序排列；目录条目按名称排序后访问。报告不包含时间戳。

报告结构

JSON 报告包含 tool、version、target、verdict、counts、findings 和 summary。主要数值位于 counts 中：

• files：统计的文件数。
• totalTokens：所有统计文件的估算 Token 总数。
• totalChars：所有统计文件的字符总数。
• budgetTokens：当前生效的预算。
• remainingTokens：预算减去总量；超出预算时为负数。
• skippedDirs、skippedBinary、skippedLarge：跳过项计数。
• findings、findingsHigh、findingsMedium、findingsInfo、findingsLow：发现项计数。
• ext:<extension>:files 和 ext:<extension>:tokens：按扩展名统计的总量，例如 ext:.ts:tokens。
• top:<relative path>：排名前 10 的最大文件各自的估算 Token 数。

MCP

MCP 服务提供一个工具：

• budget_path：接收一个 path 字符串，并返回与 contextbudget budget <path> --json 相同的 JSON 报告。

使用 contextbudget mcp 运行，或通过 server.json 中的注册项运行。

限制

• 仅处理文本文件：二进制文件和超过 1 MiB 的文件会被跳过，因此报告中不会显示它们的实际开销，只会显示跳过计数；对于较大的文件，还会显示中等严重程度的发现。
• 如上所述，估算器采用启发式方法。它不是分词器，也不了解任何特定模型的词汇表。
• 跳过列表是固定的。在此版本中，没有用于自定义跳过项或为每个目录设置自定义预算的标志或配置文件；唯一的预算控制项是 CONTEXTBUDGET_BUDGET。
• 计数仅反映文件内容。不会估算文件名、目录名，以及 Agent 工具框架在文件内容周围添加的任何封装内容。

开发

npm install
npm run build
npm test