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 退出碼，它可以將上下文管理融入開發流程。
