宁夏大学—TokenCut

> 让每一枚 token 都花在刀刃上。

它解决什么问题

积分（token）是 WorkBuddy 里最不经花的资源。几个真实例子：

• 一个「创建桌面快捷方式」的小事，AI 全包能烧 62,435 token（≈¥0.12），一条 PowerShell 就够；
• 一本 200 页 PDF 整包投喂 AI，单次 9.5 万 token 起步，还容易超窗截断、白跑重跑；
• 同一个重复任务每天手动做、不做模板，一年下来多烧 20 万+ token 而不自知。

TokenCut 是一套精算型使用流程：在每次任务开工前预估消耗、基于用户历史使用记录给出个性化分档路径（档位数不固定，见第 2 步），执行中识别陷阱、拦截重活，结束后记账并沉淀规则。它不解决某个具体业务问题，而是让"怎么省着用 AI"这件事，从拍脑袋变成一套可复用的流程。

> 效果的证据不写在开头——它写在你自己跑一遍的结果里。下方 30 秒就能验证。

🚀 30 秒验证（零依赖）

TokenCut 所有脚本只用 Python 3 标准库，不需要 pip install、不需要 venv、不需要 WorkBuddy 环境。想先看它输出什么：

# 在 skill 目录下运行（--demo = 内置样例数据，无数据库也能跑）
python3 scripts/积分自检.py --days 30 --demo
python3 scripts/积分自检.py --days 7  --demo --show-cost    # 连人民币成本一起算
python3 assets/生成图表.py --days 30 --demo --output 我的诊断图.md

> 修 #8 Windows 提示：上面是 macOS/Linux 的 python3 命令。
> Windows 用户请把 python3 换成 python（PowerShell / CMD 都行），其余路径与参数完全相同。
> 建议先用 python --version 确认 Python ≥ 3.8（脚本最低要求 3.7+，含 f-string / dataclasses）。

装了 WorkBuddy 的用户，把本文件夹放入 ~/.workbuddy/skills/，新对话里用 /token-cut 开头说任务即可。

完整上手路径见 quickstart.md（30 秒、分场景、含常见问题）。

🎯 适用场景

触发条件（满足任一即可调用）：

不适用场景：
- 简单问答（< 200 字输出）
- 已确定路径的自动化任务
- 用户明确要求"不要优化，给我最高质量"

🧩 它怎么干活：六步解决流程

TokenCut 对任何任务都走同一套流程——这是它的核心内容结构：

0 先扫 skill 库   看下 ~/.workbuddy/skills/(已装)+ ~/.workbuddy/plugins/cache/(可装) 有没有正好适用的 skill
                 命中就用 skill 链路（让 dedicated skill 干专长活）—— 避免 AI 自己硬扛出低质量
                 python scripts/技能匹配.py "你的任务" → 已装命中 / 可装推荐
                 每天扫描结果落 data/skill_inventory.json：python scripts/技能发现.py
① 开口前预估    任务大概烧多少积分？给低/中/高三档
② 动手前给路    路径条数按"任务复杂度 + 用户历史习惯"灵活定，不锁死三条：
                - 简单/用户常做的任务 → 1 条推荐路径，经用户同意后直接执行
                - 常规任务 → 2~3 条（默认 3 条：暴力 / 推荐 / 极简）
                - 复杂/高消耗/用户没做过的任务 → 4~5 条不同特色路径
                每条都明码标价（预估积分），让用户选
③ 执行中拦坑    遇到高消耗陷阱（整本 PDF / 逐帧视频 / 批量爬虫…）当场叫停换路
④ 交付后记账    真实消耗写进历史，供每周自检与月度报告
⑤ 结束后沉淀    新规则写回知识库，下次同类型任务直接复用

支撑这套流程的，是五个知识模块：

① 积分精算引擎（对应第 1 步）

• 任务开始前预估消耗，给"低/中/高"三档提示，并对照本月剩余积分警告占比
• 积分换算（--show-cost）：token → 积分 → 人民币/日月年成本，让"省了多少"可量化

② 模型路由器（对应第 2 步）

• 比较 lite / 默认 / reasoning 的成本-质量比，按任务分级路由：
• L1 简单（查资料、改语法、短摘要）→ lite（省 60-70%）
• L2 中等（常规写作、分析、代码）→ 默认模型
• L3 复杂（架构设计、深度推理、长文创作）→ reasoning
• 结合用户历史偏好加权（如"我对这个话题要求高"）
• 方案个性化：经用户允许后，读取 conversation_search 历史对话检索、~/.workbuddy/MEMORY.md 与工作区 .workbuddy/memory/ 日志，让分档方案贴合用户既有习惯（常做的任务类型、偏好的输出格式、可接受的消耗水平），而不是每次都给同一套模板

③ 工具替代建议器（对应第 3 步）

识别"高积分陷阱"，推荐本地或免费工具替代（这些工具是推荐给用户按需安装的，TokenCut 自身脚本零依赖）：

④ 大消耗预警（贯穿第 3、4 步）

• 阈值默认 lite 500 / 默认 1500 / reasoning 3000，用户可改
• 超阈值主动暂停，给出 4 个选项：「继续 / 选替代 / 缩小范围 / 换便宜模型」
• 每次任务结束写入历史（积分自检.py 据此生成周报）

⑤ 个性化学习器（对应第 5 步）

• 记录用户偏好（长度/详略/表格偏好/习惯时段），下次减少重复提问
• 写入 ~/.workbuddy/MEMORY.md 的 TokenCut 段，不污染主记忆
• 隐私开关：数据清理工具.py 一键查看/清空全部个人数据

🚀 自动加载模式（v1.6.0 新增｜推荐）

> 核心问题：以前要打 /token-cut [任务] 才生效，嫌麻烦？
> 新做法：启用一次后，任何任务开工前自动走 TokenCut 五步流程，不必打字。

工作原理（双轨叠加）

启用 / 关闭 / 查询（一行命令）

# 启用：把"五步守则"写进 ~/.workbuddy/MEMORY.md
python3 scripts/启用自动模式.py --on              # 等价于不加参数（默认开启）

# 关闭：从 MEMORY.md 精确删除该章节，其他记忆条目不受影响
python3 scripts/启用自动模式.py --off

# 查询当前状态
python3 scripts/启用自动模式.py --status

# 预览要写入的内容（不动文件）
python3 scripts/启用自动模式.py --dry-run

> Windows 用户把 python3 换成 python。脚本 0 依赖，仅用标准库。

自动触发的场景（description 命中即触发）

✅ 长文写作（论文、综述、报告 ≥ 1000 字） ✅ 批量任务（批量改文件、批量数据处理）
✅ PDF / 视频 / 图片处理 ✅ 网页爬取 / 长网页全文解析
✅ 拿不准要消耗多少时 ✅ 模型选型没确定
✅ 历史账单异常、积分跑太快 ✅ 重复任务 Skill 化判断
✅ 节流技巧 / 模型路由咨询

不触发的场景（避免打扰轻问答）

⭕ 短问答 < 200 字 ⭕ 闲聊 / 打招呼 / 查事实
⭕ 用户明确说"别管 token，给我最高质量"
⭕ 已在执行已确定路径的自动化任务

想保留显式调用怎么办？

自动模式不替代 /token-cut 触发词——两者共存：
- 自动模式负责「任务开工前预估 + 给路 + 拦坑」
- /token-cut 仍可用于「主动咨询节流技巧 / 查模型路由 / 跑 --show-cost」等场景

🚀 调用方式

方式 A：作为 Skill 调用（对话内）

/token-cut [你的任务]

TokenCut 先返回「预估消耗 + 推荐路径 + 分档选择」——档位数按任务复杂度与用户历史习惯灵活调整（1~5 档均可；只有 1 条明显最优路径时，经用户同意后直接执行），确认后再执行。

方式 B：脚本自检（量化效果）

# 看积分花哪了（基础报告）——先跑 --demo 预览，再跑真数据
python3 scripts/积分自检.py --days 30 --demo          # 演示模式（无数据库）
python3 scripts/积分自检.py --days 7                  # 真实数据
python3 scripts/积分自检.py --days 7 --show-cost      # 折算积分/人民币
python3 scripts/积分自检.py --days 30 --task-type-only # 只看类型分布
python3 scripts/积分自检.py --days 30 --json           # JSON 输出
python3 scripts/积分自检.py --db 其他.db              # 指定数据库路径（或设 TOKENCUT_DB）

# 自动化会话自动归因（v1.5.2，自动生效）：自动化运行自动带出所属自动化名，不再混进「未命名」
# 闭环度量：把"省多少"从估算变实测（v1.5.1）
python3 scripts/积分自检.py --measure 优化前          # 节流前打基线
python3 scripts/积分自检.py --measure 优化后          # 节流一段时间后复查
python3 scripts/积分自检.py --measure-report          # 输出实测节省报告

方式 C：定时自检（自动化）

通过 WorkBuddy 自动化每日/每周运行，报告推送到微信/桌面。

示例输出（--show-cost）：

💰 TokenCut 积分换算（按 用户校准：1元=50万token）
【总成本（近 7 天）】
  总消耗:        685,967 token
  折算积分:        137.2 分
  折算人民币:    ¥    1.37 元
  年预估（365天）:¥    71.54 元

📂 文件结构

宁夏大学—TokenCut/                        📁 v1.7.0，31 个文件
├── SKILL.md                        ← 本文件（入口）
├── README.md                       ← 全景说明
├── quickstart.md                   ← 30 秒零依赖上手（第一站）
├── references/                     # 13 份深度文档
│   ├── FAQ.md                      # 30+ 条 Q&A（出错先看这个）
│   ├── 端到端实战记录.md            # 2 个真实任务完整流程（先看这个）
│   ├── interactive_demo.md         # 对话示范：跟 TokenCut 聊天的样子
│   ├── 对照实验模板.md             # 闭环度量：--measure 实测节省流程
│   ├── 模型路由决策树.md            # L1/L2/L3 任务分级 + Step 2.5 自配模型
│   ├── 节流prompt模板.md            # 10 条核心原则 + 高频场景模板
│   ├── 任务Skill化清单.md           # Skill 化候选 + ROI 计算器
│   ├── 积分黑洞清单.md              # TOP 20 高消耗陷阱 + 替代方案
│   ├── 个性化学习模型.md            # 用户画像 + 隐私保护
│   ├── 优化前后对比案例.md          # 7 个真实案例 + 节省明细
│   ├── 30天数据解读.md              # 30 天账单深度解读
│   ├── 建议池.md                    # 社区贡献机制
│   └── 社区贡献案例.md              # 已收录贡献（带署名 + 代码）
├── assets/                        # 6 份实用模板/工具
│   ├── 生成图表.py                  # 零依赖图表生成器（支持 --demo）
│   ├── 30天诊断图.md                # ASCII 诊断图（可重新生成）
│   ├── 积分自检表.md                # 每周/每月手填模板
│   ├── 节流报告模板.md              # 月度报告自动生成
│   ├── 模型路由表.md                # 关键词速查表
│   └── 建议收集表模板.csv           # 示例贡献（可一键导入）
├── data/                          # 运行时数据（脚本自动生成）
│   ├── skill_inventory.json        # 技能发现扫描结果
│   ├── skill_inventory.history.jsonl
│   └── measures.jsonl              # --measure 对照实验快照
└── scripts/                       # 8 个可执行脚本（均零依赖）
    ├── 积分自检.py                 # 积分花哪了（--demo / --show-cost / --measure…）
    ├── 自动化体检.py               # 🆕 按自动化维度拆账（趋势 + ROI 建议）
    ├── 推荐模型.py                 # 任务 → 最省模型 + 省多少%
    ├── 技能匹配.py                 # Step 0：开工前先扫 skill 库
    ├── 技能发现.py                 # 扫描 skill 库落 inventory
    ├── 启用自动模式.py             # 守则写进 ~/.workbuddy/MEMORY.md
    ├── 数据清理工具.py             # 一键清空个人数据（隐私开关，支持 --yes）
    └── _win_compat.py              # 🆕 Windows 输出兼容层（供上面各脚本引用）

推荐阅读顺序：quickstart.md（30 秒跑通）→ references/端到端实战记录.md（看它怎么解决问题）→ references/interactive_demo.md（看对话长什么样）→ 按需查阅其余 references。

⚙️ 配置说明

用户级配置（写入 ~/.workbuddy/skills/宁夏大学—TokenCut/config.json）：

{
  "thresholds": { "lite": 500, "default": 1500, "reasoning": 3000 },
  "personal_data": { "enabled": true, "auto_clear_after_days": 90 },
  "router": { "auto_select": true, "prefer_quality": false },
  "alerts": { "wechat_push": false }
}

详细配置项见 references/个性化学习模型.md。

📋 输入格式说明（v1.6.3 新增｜FAQ 精简版）

> 出错时不知道传什么参数、配置文件长什么样？看这里就够。完整版见 references/FAQ.md（30+ 条 Q&A）。

配置文件格式速查

tokencut_models.json 模板

> v1.7.0 重要修正：旧版文档给的模板是 {"models": {...}, "cost_per_1k": ...} ——
> 照它写不会生效。脚本实际读的是扁平结构：顶层直接是「模型名 → 配置」，
> 且字段名是 cost / cny / domains（不是 cost_per_1k / strengths）。
> 写错轻则配置被忽略，重则在 dict(cfg) 处抛异常。正确写法如下：

{
  "my-deepseek": {
    "tier": "L2",
    "cost": 0.04,
    "cny": 0.0004,
    "domains": ["代码", "数学", "技术推理"]
  }
}

字段说明：tier = L1/L2/L3；cost = 每 1k token 折合积分；cny = 每 1k token 折合人民币；
domains = 擅长域（与任务擅长域做交集匹配，要写完整词，如「长文创作」不能只写「长文」）。
已存在于内置库的模型会被覆盖，新名字则新增。

命令行参数速查

数据库路径

• 默认：~/.workbuddy/workbuddy.db
• 覆盖：python scripts/积分自检.py --db /实际/路径.db（或设 TOKENCUT_DB 环境变量）
• v1.7.0 修正：本文件旧版此处写作 --db-path，脚本实际参数是 --db，照旧版抄会报「无法识别的参数」
• 注意：备份必须用 sqlite backup API，不能直接复制 .db（会丢 -wal 最新提交）

路径约定

• 绝对路径优先：C:\Users\zengs\.workbuddy\... 或 /c/Users/zengs/.workbuddy/...
• Windows 中文路径若乱码：把 Skill 移到纯英文路径（如 C:\skills\tokencut\）
• Bash 路径用 /c/Users/... 风格，PowerShell 用 C:\Users\...

必填文件清单（Skill 目录）

~/.workbuddy/skills/宁夏大学—TokenCut/
├── SKILL.md                  ← 必备：frontmatter description 触发自动加载
├── scripts/                  ← 必备：5 个 .py
├── references/               ← 可选：手册/FAQ
└── assets/                   ← 可选：路由表/模板

🌟 社区贡献机制

TokenCut 不是一个人的 Skill，是社区共建的"省积分百科"。 任何你验证过的省积分方法都可以提交：

提交流程：提交 5 字段（场景/原方法/新方法/节省估算/署名）→ 勾选"同意公开" → 作者 24h 初筛 → 复现验证 → 收录进 references/ 并署名。详细规则见 references/建议池.md。

🔗 可搭配的 Skill

TokenCut 不替代其他 Skill，而是让它们更省：

📜 许可证

MIT License — 自由使用、修改、二次分发，但请保留原作者署名。

作者：曾帅（zengs）｜学校：宁夏大学（211）｜专业：新能源材料与器件
一句话：先让"省积分"从口号变成一套流程——每个用过它的人，下一单都比上一单便宜。