技能 Token 预算器（Skill Token Budget）

给大技能配 token_budget.json、量化「加载前后 token 差值」、验证懒加载价值。

本技能自包含：脚本位于 scripts/measure_token_budget.py，纯 Python 标准库实现，无需任何第三方依赖、无需建 venv、无需 pip install。与 skill-inventory、skill-orchestrator 同款形态。

何时用

• 某个技能 .md 文件很多（如 mc-integrated 有 35 张方法卡），怀疑加载时 token 太重。
• 想给技能加「token 预算 + 跳过低频模块 / 文件内截断」策略，但先要用数据证明值得做。
• 想把预算从「写死数字」升级为「按会话剩余 token 自动推算」（动态预算）。

调用方式（直接用托管 Python）

PY="C:/Users/13301/.workbuddy/binaries/python/versions/3.13.12/python.exe"
SKILL="C:/Users/13301/.workbuddy/skills/skill-token-budget"
TARGET="C:/Users/13301/.workbuddy/skills/mc-integrated"   # 被测技能目录

# 1) probe：先看全量 token（无预算）
"$PY" "$SKILL/scripts/measure_token_budget.py" --skill-dir "$TARGET" --probe

# 2) 正式测量：读被测技能目录里的 token_budget.json（推荐，先给它写好配置）
"$PY" "$SKILL/scripts/measure_token_budget.py" --skill-dir "$TARGET" --out ./TOKEN_REPORT.md

# 3) 动态预算：按会话剩余 token 自动推算（覆盖写死数字）
"$PY" "$SKILL/scripts/measure_token_budget.py" --skill-dir "$TARGET" --session-remaining 20000 --out ./TOKEN_DYN.md

# 4) 手动覆盖预算/策略（不依赖 json 配置）
"$PY" "$SKILL/scripts/measure_token_budget.py" --skill-dir "$TARGET" --budget 6000 --strategy truncate_in_file

参数

被测技能需提供的配置：token_budget.json（放在被测技能目录根）

{
  "total_budget_tokens": 12000,
  "dynamic": {"enabled": true, "ratio": 0.5},
  "strategy": "skip_low_priority",
  "priority": [
    "SKILL.md",
    "references/cards/cluster1-strategy-external.md",
    "references/cards/cluster2-strategy-internal.md"
  ]
}

• priority[0] 视为核心（如 SKILL.md 路由引擎），动态预算下永远完整可载，不被截断。
• 优先级越靠前越先加载；超预算后整文件跳过（skip）或按剩余比例截断（truncate）。
• 未在 priority 表的文件排最后，触发时再 Read。

两种截断策略

动态预算公式

预算 = min(全量, max(会话剩余 × ratio, 核心))

• 会话充裕 → 预算 ≥ 全量 → 全载（零浪费）
• 会话紧张 → 自动收紧到「核心 + 高频」，避免写死预算的两种浪费（小会话硬塞 / 大会话误截）
• 核心（路由引擎）始终保底，技能不失效

关键实现坑（已修复，备忘）

• token 是确定性启发式估算（CJK 每字~1；英文词每 4 字符~1；其他每 4 字符~1），用于测相对差值，非 tiktoken 精确计数。
• Windows 路径 \U：命令里渲染 OUT 时务必转正斜杠，否则 python -c 触发 unicodeescape 报错。
• 动态预算缺省：不传 --session-remaining 且没环境变量时回退静态配置，不会崩。
• Windows 控制台：stdout 加 reconfigure(utf-8, errors="replace") 防 GBK 编码炸。

产出

• 控制台：预算内/全量 token、节省比例、已加载/跳过/截断清单。
• --out 时：报告 md（含 [TOC]、结论、预算推算、文件 token 排行、已加载/跳过/截断明细、方法说明）。
• 被测技能目录新增 token_budget.json（由使用者编写，本技能只读取并量化）。

批量模式（一键扫多个大技能）

对一批技能批量出 token 报告，支持自动生成配置并验证节省。脚本 scripts/batch_token_report.py（同样纯 stdlib，subprocess 调 measure_token_budget.py）。

PY="C:/Users/13301/.workbuddy/binaries/python/versions/3.13.12/python.exe"
SKILL="C:/Users/13301/.workbuddy/skills/skill-token-budget"
# 扫指定技能 + 自动纳入全量>8000 的大技能；无配置者自动生成 token_budget.json 并测节省
"$PY" "$SKILL/scripts/batch_token_report.py" \
  --only industry-research-pro,material-deep-analysis \
  --auto-min 8000 --auto-config --out ./TOKEN_BATCH_REPORT.md

参数：
| 参数 | 默认 | 说明 |
|------|------|------|
| --only | industry-research-pro,material-deep-analysis | 逗号分隔技能名列表 |
| --auto-min | 8000 | 全量 token 超此值自动纳入（0=关） |
| --auto-config | 关 | 对无 token_budget.json 的技能，按「SKILL.md 必载 + 其余按 token 降序」自动生成配置并测节省 |
| --budget-ratio | 0.63 | 目标预算比例（假设值，可配）：自动生成配置时 预算=全量×ratio。改这个值验证不同瘦身力度（如 0.5=目标砍一半），实测节省仍以报告「节省%」为准 |
| --all-skills | 关 | 关闭「仅自制技能」安全过滤，处理所有技能（含官方/市场）。默认仅处理自制技能 |
| --skills-root | ~/.workbuddy/skills | 技能根目录 |
| --out | ./token_batch_report_<日期>.md | 汇总 md |

安全默认（self-only，重要）：批量模式默认仅处理 自制技能（SKILL.md frontmatter 含 agent_created: true）。官方/市场技能（如 ppt-generator-skill、excel-auto-zh 等）默认被跳过，绝不向其中写入 token_budget.json。若确实要处理非自制技能，显式加 --all-skills。

行为：有配置→测节省（existing）；--auto-config 且无配置→自动生成后测（auto-generated）；否则仅 probe 体量（probe only）；非自制且未加 --all-skills→跳过（skipped）。汇总表按全量 token 降序，含模式/全量/预算内/节省%/已载跳过；明细展开已载跳过清单与建议。

⚠️ 目标预算 vs 实测节省（不要循环论证）：自动配置的预算 = 全量 × --budget-ratio（默认 0.63）是人为设定的目标假设，不是"验证出来的 37% 规律"。报告里的「节省%」是实测值——由 skip_low_priority 整文件跳过粒度决定，随技能文件分布而变，通常 ≥ (1-ratio)，不会恰好等于 37%。想比较不同瘦身力度就改 --budget-ratio（如 --budget-ratio 0.5）再看实测节省怎么变。生成的 token_budget.json 会记录本次用的 budget_ratio_assumed，便于事后区分"这是预设目标"还是"这是实测结果"。

衔接

• 配合 skill-inventory：先治理后编排——台账理清资产后，对大技能做 token 瘦身。
• 配合 skill-orchestrator：DAG 编排的 out 产物若需二次处理，可用本技能评估编排脚本自身加载成本。
• 与下一篇 Skills 工程文章互证：Token 预算 / 上下文动态修剪 / 脚本增强结构化。