Agent 开发中，上下文窗口是硬约束。指令文件、Skill、MCP 工具定义和 Memory 都会消耗 Token。其中，Skill 的 catalog（每次请求都存在）和 body（按需加载）是两种不同的成本。此外，MCP 工具定义会带来“永久税”。
前言¶
在 Agent 跑起来之前，它的上下文要花多少钱？这是模型推理阶段必须确认的问题。ctx-budget 作为一个 DSH 插件，用于在 Agent 运行前审计上下文成本。它找出 Agent 会加载的文本——指令文件、Skill、MCP 工具定义、Memory——逐项测量，并且分清每次请求都要付的（catalog）和只有加载时才付的（body）。最后，它提供可以卡在 CI 里的退出码。
它是什么¶
ctx-budget 是一个由 liyixuan201211 维护的 DSH 插件，开源协议为 MIT。它主要解决三个问题：
- 区分两种成本：指令文件和 Skill 的 catalog 在每次请求中都存在，而 Skill body 只在加载时存在。大多数工具无法区分这两者，导致无法定位预算危机。
- MCP 工具的永久税：工具定义会添加 Token 到每一次模型请求中，无论模型是否调用该工具。
- 描述截断：过长的描述会被截断，导致有用的信息丢失。
插件通过读取文件来测量，不涉及进程、socket 或写操作。
核心功能¶
- 按来源审计：逐项测量指令文件、Skill、MCP 工具模式和 Memory 的消耗。
- 运行前测量：在 Agent 运行前就能得到上下文成本预估。
- 分层统计：分离 always-on（catalog）与 on-demand（body）的成本。
- 去重检测：检测重复的文本块，并按其消耗层级标记。
- CI 退出码：提供退出码，允许在 CI 流程中强制执行预算。
- CJK 感知分词：使用 4 字符/token（ASCII）和 1.5 字符/token（CJK）的比率进行估算，避免中文被低估约 2.44 倍。
- 安全读取：仅读取文件，不执行进程、不建立 socket 或写入文件。
安装与启用¶
使用 DSH CLI 安装插件：
dsh plugin --profile web add github:liyixuan201211/ctx-budget
安装后，技能会被加载到当前的 DSH 环境中。
典型用法¶
插件安装后，可以直接在命令行运行：
ctx-budget
设置最大预算阈值：
ctx-budget --max 40000
指定特定的 MCP 工具文件进行审计：
ctx-budget --mcp-tools tools.
审计指定项目根目录：
ctx-budget --root ./chinese-project --
查看帮助信息：
npx --yes github:liyixuan201211/ctx-budget --help
适用场景与注意事项¶
适用场景：需要在 CI 中强制执行上下文预算的项目；希望优化 Skill 设计以减少 Token 消耗的开发者；处理多语言（含中文）项目。
注意事项：
- 中文估算：中文的字符数统计比英文更敏感。如果不使用 CJK 感知的估算，4 字符/token 的规则会导致中文内容被低估约 2.44 倍。插件默认对 ASCII、CJK 和其他非 ASCII 使用不同的比率（默认为 4.0、1.5、2.5）。
- 退出码含义：退出码
5表示“无法确定”（could not determine），通常发生在 MCP 服务器声明了工具但未导出工具定义时。此时报告的是下界，不代表预算一定通过。 - 安全机制：插件仅读取文件，不会进行任何进程调用、网络通信或文件写入，适合在 CI 环境中安全运行。
总结¶
ctx-budget 提供了一种在运行前量化 Agent 上下文成本的方法。通过区分 always-on 和 on-demand 成本，并检测重复文本块，开发者可以更精确地控制 Token 消耗。配合 CI 退出码，它可以将上下文管理融入开发流程。
