Token 预算器

要解决的具体问题

一个技能目录下的 .md 文件多了之后，加载成本会悄悄失控。比如 mc-integrated 带着 35 张方法卡，整包载入时 token 消耗远高于实际用到的部分；用户只想取其中一两张卡，却要为全部文本付上下文代价。更麻烦的是，当你怀疑「这个技能太重」，想引入预算控制时，手上往往没有任何数据支撑——要么凭感觉写死一个数字，要么砍完发现省得不够、还误伤了高频路径。

Token 预算器要回答的就是这个问题：先量化，再决策。它给技能配一份 token_budget.json，测量「全量载入」与「预算内载入」的 token 差值，用相对数字证明懒加载是否值得做。

核心能力与工作方式

• 配置驱动：在被测技能根目录放置 token_budget.json，用 priority 数组声明加载顺序，priority[0] 视为核心（如 SKILL.md 路由引擎），在动态预算下永远完整载入、不被截断；未列入的文件排最后，触发时再按需 Read。
• 两种瘦身策略：skip_low_priority 按优先级累计，超预算的整文件跳过（真正的懒加载，适合模块间独立的技能）；truncate_in_file 按剩余预算比例截取文件前 N 字符（适合单文件内含多张卡、但必须保留头部的场景）。
• 静态与动态预算：静态预算由 --budget 或配置文件的 total_budget_tokens 给出；传 --session-remaining（或环境变量 SESSION_REMAINING_TOKENS）后转为动态推算，预算 = 会话剩余 × dynamic.ratio（默认 0.5）。会话充裕时预算 ≥ 全量，全量载入零浪费；会话紧张时自动收紧到「核心 + 高频」，避免写死预算的两种典型浪费：小会话硬塞、大会话误截。
• 脚本零依赖：scripts/measure_token_budget.py 用纯 Python 标准库实现，直接调用托管 Python 即可运行，无需建 venv、无需 pip install。控制台输出预算内/全量 token、节省比例、已加载/跳过/截断清单；加 --out 输出带目录的 Markdown 报告。
• 批量模式：scripts/batch_token_report.py 用 subprocess 批量扫描多个技能，--auto-config 可对无配置的技能自动生成预算（按「SKILL.md 必载 + 其余按 token 降序」）并实测节省。

适用边界与注意点

• token 是启发式估算，不是精确计数：CJK 每字约 1 token、英文与其他每 4 字符约 1 token，只适合测相对差值，别拿它当 tiktoken 的精确结果用。
• 目标预算不等于实测节省：自动配置里的 --budget-ratio（默认 0.63）是人为设定的目标假设；报告里的「节省%」才是实测值，由跳过粒度决定，通常 ≥ (1 - ratio)，不会恰好等于某个固定百分比。想比较不同瘦身力度，改 --budget-ratio（如 0.5）再看实测变化。
• 批量模式默认只处理自制技能：SKILL.md frontmatter 含 agent_created: true 的自制技能才会被扫描和写配置，官方/市场技能默认跳过，需显式加 --all-skills。
• 环境坑已修：Windows 路径需渲染为正斜杠，否则 python -c 触发 unicodeescape 报错；动态预算缺省时回退静态配置，不会崩。

适用前提：你有权限在被测技能目录内放置 token_budget.json；技能文件之间的独立性（适合 skip）或头部依赖性（适合 truncate）需要你自行判断，脚本只负责量化，不做架构决策。