Top Token-Consuming — 本地 Skill Token 消耗体量审计
静态估算本地已安装 skill 的 token 消耗「体量」，按绝对阈值标红「偏胖 / 异常」skill，并展示每个 skill 的名称、功能、单次预估 token、区间使用次数、区间累计预估。
本技能只做「体量评估」，不做「真实账单」——它回答"哪些 skill 最可能吃 token"，而不是"历史上真实烧了多少 token"。
设计哲学：授权是第一道闸门
本技能会读取用户本地的 skill 文件与使用记录。因此任何扫描动作都必须在用户明确授权之后进行，未授权绝不读取任何文件。
流程一：触发 → 声明 → 授权（必须，先于一切扫描）
用户触发本技能后，不要立即扫描，先向用户说明：
- 将要只读扫描的路径（默认用户级
~/.workbuddy/skills/；若用户要求项目级，需其显式指定工作区）； - 将不会修改、删除、移动任何文件；
- 估算口径：单 skill 单次触发预估 token = 其
SKILL.md+references/+scripts/的静态体量（非真实账单）； - 询问范围：默认仅用户级，是否仅扫描用户级，还是也要包含某个项目级的
.workbuddy/skills？
> 若用户要求项目级：必须让其明确指出工作区路径，并在得到确认后再传入 --skills-dir；不得在未被授权时擅自扫描项目目录。
获得用户确认后，方可进入流程二。
流程二：执行扫描
使用环境中可用的 Python（managed Python 优先，否则 python3 / python）运行扫描脚本：
python "<SKILL_DIR>/scripts/scan.py" --skills-dir "<SKILLS_DIR>" [选项]
常用选项：
--threshold 6000：单次触发预估 token 异常阈值（默认 6000；支持 2000 / 2w / 2万 / 20k 等单位写法）。--range week|month|all：时间范围预设（默认 all）。--since 2026-07-03 --until 2026-07-10：自定义日期区间（YYYY-MM-DD）。--top 20：仅显示前 N 个（默认全部）。--hide-unused：隐藏时间范围内未被使用的 skill。--detail：追加每个 skill 最重文件明细。--output report.md/--json result.json：另存报告。
> <SKILL_DIR> 为本技能所在目录；<SKILLS_DIR> 为用户确认后的扫描根目录（默认 ~/.workbuddy/skills）。
脚本输出 Markdown 排行表，原样转呈给用户。
交互式阈值（自然语言）
用户不一定会说"--threshold 2000"，而会用自然语言指定阈值。agent 应先从用户的话里提取阈值数字与单位，换算成整数后传给 --threshold，再运行脚本：
- "查一下 token 消耗在 2000 的 skill" →
--threshold 2000 - "2w 的阈值" / "2万" →
--threshold 20000
换算规则（与脚本 --threshold 自身支持的写法一致）：
- 纯数字：原值（如 2000 → 2000）；
- 带 万 / w / W：×10000（如 2w / 2万 → 20000）；
- 带 k / K：×1000（如 20k → 20000）。
> 脚本本身也直接吃得进上述单位写法，因此无论 agent 是否已换算，传 2w 或 20000 都等价。
流程三：结果解读与下钻
转呈表格后，附上：
- 数据口径说明（见下方「数据源与限制」）；
- 一句引导：若某 skill 被标红（🔴），可追问"为什么 X 被标红"→ 用
--detail或说明其最重文件，给出瘦身建议（把大段内容拆到references/按需加载、压缩内嵌 prompt、精简脚本）。
输出表头（设计稿）
| 排名 | Skill | 功能 | 单次预估token | 区间使用次数 | 区间累计预估(估算) | 异常 |
|---|---|---|---|---|---|---|
| 1 | xxx | … | 8200 | 4 | 32800 | 🔴 |
- 单次预估 token：该 skill 触发一次注入上下文的体量估算（绝对阈值比对对象）。
- 区间使用次数：
usage-log.json的recentDates落在选定时间范围内的天数。 - 区间累计预估(估算) = 单次预估 × 区间使用次数（仅展示，不参与标红）。
- 异常（🔴）：仅当「单次预估 token ≥ 阈值」时标红。
数据源与限制（务必如实告知用户）
- 静态估算，非真实账单：本地没有任何「按 skill 维度的真实 token 账本」。
usage-log.json仅记录使用日期，session_usage是会话级哈希，traces是请求级——均不带 skill 标签。本技能估的是"体量"，真实消耗只在模型供应商账单中。 - 时间范围筛的是「使用活动日期」：基于
recentDates。它能告诉你"这段里哪些 skill 被用过、各几次、按体量估算占了多少"，但给不出"某天真实烧了 N 个 token"。 - recentDates 可能欠计数：usage-log 仅保留近期日期，过老的时间区间（如半年前）可能漏算。
- 已卸载的 skill 不可见：只扫描当前磁盘上已安装的 skill，历史装过又删掉的扫不到。
- 纯本地、只读、可移植：不读 WorkBuddy 内部数据库私有格式，不怕版本升级导致脚本失效；不联网、不写不改任何文件。
安全边界
- 全程只读；不执行任何删除、移动、修改其他 skill 的操作。
- 项目级扫描必须用户显式授权并指定路径，默认绝不越权。
- 若
usage-log.json缺失或技能目录不存在，脚本会优雅报错（退出码 1/2），不会崩溃或泄露。
