TokenCut-Lite
> 让每一枚 token 都花在刀刃上。
> 轻量版：只留最核心的「算账 + 选模型」，去掉全部进阶模块。
30 秒验证（零依赖）
所有脚本只用 Python 3 标准库，不用 pip install、不用建 venv。
python scripts/积分自检.py --days 30 --demo # 内置样例数据，无需任何环境
python scripts/积分自检.py --days 30 --demo --show-cost # 顺便算人民币成本
python scripts/推荐模型.py "帮我写一篇论文" # 这个任务用哪个模型最省
> Windows 用户：命令用 python（不是 python3），其余完全相同。
> 脚本已内置 Windows 编码兼容层，输出重定向到文件也不会崩。
它解决什么
AI 的 token 消耗有三个典型黑洞，而且都是事后才发现：
| 黑洞 | 典型场景 | 代价 |
|---|---|---|
| 小事用大模型 | 让 AI 做一条命令就能完成的事 | 单次多花几千 token |
| 整包投喂 | 200 页 PDF 直接丢给 AI | 单次近 10 万 token，还可能超窗白跑 |
| 重复不做模板 | 同样的任务每天手动做一遍 | 一年多烧 20 万+ token |
TokenCut-Lite 用两个脚本堵住这三个洞：开工前算账，结束后自检。
怎么用：四步流程
① 开工前预估 这个任务大概烧多少 token？给低/中/高三档
② 动手前选模型 用 推荐模型.py 看有没有更便宜且够用的模型
③ 执行中拦坑 遇到整本 PDF / 逐帧视频 / 批量爬虫 / 长网页全文 → 当场叫停换本地工具
④ 交付后记账 真实消耗进账单，定期跑 积分自检.py 看钱花哪了
第 ③ 步的替代方案（记住这张表就够）
| 高消耗陷阱 | 该用什么替代 |
|---|---|
| 整本 PDF 精读 | 先 pdftotext 提取，AI 只读关键章节 |
| 逐帧分析视频 | ffmpeg 抽关键帧，AI 只整理结果 |
| 长网页全文爬取 | curl + html2text，AI 只消化摘要 |
| 批量文件重命名/数据清洗 | 写个脚本跑，AI 只生成规则 |
| 重复图片处理 | 本地 Pillow / ImageMagick，AI 只给参数 |
脚本说明
| 脚本 | 作用 | 常用参数 |
|---|---|---|
scripts/积分自检.py |
看钱花在哪：任务/模型分布、TOP 最费任务、重复任务、节流建议 | --days 30、--show-cost、--demo、--json、--task-type-only |
scripts/推荐模型.py |
给定任务描述，排出最省模型 + 省多少 % | "任务描述"、--task-type L2、--json |
scripts/_win_compat.py |
内部依赖：Windows 输出兼容层，不用手动调用 | — |
示例输出（--show-cost）
【总成本（近 30 天）】
总消耗: 685,967 token
折算人民币: ¥ 1.37 元
年预估（365天）:¥ 71.54 元
示例输出（推荐模型.py "帮我写一篇论文"）
【候选模型(综合分排序)】
# 模型 tier 预估成本 积分 匹配
1 glm-5.2 L2 ¥0.009 0.9 50.0%
2 auto L2 ¥0.011 1.1 40%
相比默认模型，最优候选「glm-5.2」预估省 18.3%
任务分类
积分自检.py 会把你的任务自动归到这些通用类别：
翻译 / 代码 / 分析 / 资料整理 / 文档处理 / 运维 / 创意 / 写作 / 其他。
想改成自己的分类：编辑 scripts/积分自检.py 里的 classify_task() 规则表即可，
格式是 ([关键词列表], "类别名")，越靠前优先级越高。
配置（可选，不配也能用）
| 文件 | 作用 |
|---|---|
~/.workbuddy/tokencut_cost.json |
自定义「token → 人民币」单价（默认按 1 元 = 50 万 token） |
~/.workbuddy/tokencut_models.json |
添加你自己的模型（格式见下） |
tokencut_models.json 是扁平结构（顶层直接写模型名，不要套 {"models": ...}）：
{
"my-model": {
"tier": "L2",
"cost": 0.04,
"cny": 0.0004,
"domains": ["代码", "数学", "技术推理"]
}
}
- 数据库路径默认
~/.workbuddy/workbuddy.db，可用--db /你的路径.db覆盖。 - WorkBuddy 用户把本文件夹放进
~/.workbuddy/skills/即可。
完整版 vs 精简版
本版由 完整版 TokenCut v1.7.0 精简而来 —— 核心脚本同源，砍掉进阶模块。
| 精简版（本文件） | 完整版 v1.7.0 | |
|---|---|---|
| 文件数 | 6 | 31 |
| 脚本数 | 2（+1 内部依赖） | 8 |
| 上手时间 | 3 分钟 | 30 分钟+ |
| 账单自检 / 模型推荐 | ✅ | ✅ |
| 自动化账单体检 | — | ✅ |
| skill 库匹配 / 发现 | — | ✅ |
| 自动模式常驻守则 | — | ✅ |
| 深度文档 | — | 13 份 |
| 任务分类 | 通用 8 类 | 可自定义（含个人场景分类） |
怎么选：先装精简版，跑一次 --demo 看账单长什么样。觉得确实有用、还想再往下压，
再上完整版 —— 两版可共存，脚本互不冲突。
常见问题
Q：没有 WorkBuddy 能用吗？
A：能。加 --demo 跑内置样例数据看效果。真实账单功能需要 ~/.workbuddy/workbuddy.db。
Q：成本数字准吗？
A：默认按「1 元 = 50 万 token」估算，只用于比较量级。要精确就改 tokencut_cost.json。
Q：Windows 下输出乱码/报错？
A：v1.0.0 已内置编码兼容层。若某个符号仍显示异常，说明它是 GBK 写不下的字符，不影响数据本身。
许可证：MIT — 自由使用、修改、二次分发，保留原作者署名即可。
