为什么你的Claude Code插件悄悄烧Token?skills的ModSmith提示缓存成本审查完整指南
为什么你的Claude Code插件悄悄烧Token?skills的ModSmith提示缓存成本审查完整指南
skills 仓库中的 ModSmith 是一套专门审查 Claude Code 插件(Claude Mods)Token 成本与提示缓存(prompt cache)影响的方法、脚本和模板。如果你的插件装完就开始悄悄烧 Token、账单莫名上涨,这篇指南带你用「成本审查」5 步找出原因:什么会击穿提示缓存、每轮对话到底花多少钱,以及安装别人的插件前如何审查它的权限。🔍
Claude Mod 是什么:插件为什么会在每轮对话里收费
先对齐概念:Claude Mod 是 Claude Code 的插件,它直接修改 Claude Code 本身的行为——提示框上方显示什么、Claude 有哪些工具、每一轮(turn)结束后运行什么。
关键就一句话:mod 的 hook 挂在每个 turn 上。一次小错误(比如每轮都调用一次模型),就会在会话剩下的每一轮持续收费;一个更粗心的 mod 甚至能碰到用户能碰到的任何东西。
Claude Code 自带的 plugin-authoring 技能教你写 mod 的 API,但它不会告诉你"这个 mod 值不值得装、每轮花多少钱"。ModSmith 补上的正是这部分,modsmith/README.md 概括了它的三大件:
- 现成可用的 6 个模板 mod;
- 成本与提示缓存审查:每轮花多少 token、什么会击穿缓存;
- 装别人插件前的安全审查:风险、成本、权限一页纸报告。
提示缓存原理:改动前缀为什么让账单翻倍
大模型的提示缓存是一个前缀,按固定顺序排列:工具定义 → 系统提示 → 消息。缓存只认前缀——只要靠前的一部分变了,后面所有内容全部作废,要按全价重新写入。
- 一个 mod 只改一次前缀:付一次重写费;
- 一个 mod 每轮都改前缀:这个会话从此再也没能读过缓存,全程全价。
这就是"悄悄烧 Token"最常见的根源:你根本没意识到某个 hook 正在每轮改写前缀。
7 种最常见的提示缓存击穿点
完整对照表见 cost-review.md 第 1 节,新手先记住这几条:
| 谁在改前缀 | 后果 | 正确做法 |
|---|---|---|
prompt.section 的答案每次调用都不一样(里面藏了时钟、计数器、用量统计) |
每次调用都击穿提示缓存 | 整个会话返回同一段文本 |
tool.describe 的描述在变 |
击穿模型的提示缓存 | 描述固定;易变信息放进工具的返回结果里 |
会话中途才 $.tool.register 新工具 |
工具列表排在系统提示之前,整段重写 | 在 session.start 注册,第一轮就列出 |
$.ui.invalidate('prompt.*') |
下一轮起缓存 miss | 只在用户操作时触发,绝不放定时器 |
切换模型(/model) |
前缀全价重付 | 路由一次就固定,别每请求都换 |
turn.step 每个请求改 model / effort |
每次请求都读冷缓存 | 只在 index === 0 时决定一次 |
$.session.append 追加的行 |
缓存保留,但每行都会在之后每轮重发 | 只写短且真的有用的行 |
fork 还是 complete:两种模型调用的计费区别
mod 里要"问一次模型",通常有两个选择,计费方式完全不同:
$.model.fork |
$.model.complete |
|
|---|---|---|
| 能看到什么 | 完整对话(复用主线程的缓存) | 只有你传入的 prompt |
| 怎么计费 | 缓存读价 + 未缓存尾部 + 输出 | prompt 按全价输入 |
| 什么时候变贵 | 缓存过期(TTL 5 分钟/1 小时)或切模型后 | 没有冷热之说,但上下文小 |
| 适合问什么 | "这次对话"的问题:任务做完了吗?做了什么假设? | 分类、打标、总结一小段文字 |
两条实用判断:
- 问"这轮干了什么"用 fork,而且要在 turn 刚结束、缓存还热的时候问;
- 如果你发现自己在往
complete里粘贴整个对话——说明你其实想要的是fork。
⚠️ 注意:fork 命中缓存不等于免费。长上下文加贵模型的一次 fork,同样要按"缓存读 + 输出"收费,所以要像任何调用一样加门控。
ModSmith 成本审查 5 步走
完整流程在 cost-review.md,核心顺序如下:
第 1 步:用 validate 看引擎视角
claude plugin validate <mod>
列出引擎实际看到的 hook、它读写哪些状态、挂在哪些事件上——这是成本审查的地基。
第 2 步:audit-mod.ts 静态扫描
bun scripts/audit-mod.ts <mod>
# 或:node --experimental-strip-types --no-warnings scripts/audit-mod.ts <mod>
audit-mod.ts 会列出:hook 了哪些事件(带触发频率,如 turn.step = "每轮的每次模型请求")、每处模型调用(model.fork / agent.spawn / prompt.submit…)、缓存风险、越权能力($.process.run、$.fs.write、$.mcp.call…)和风险等级。
它只是指向值得读的行,不是结论——它看不见改名或解构的 $ 调用,也看不见运行时才算出来的值。
第 3 步:逐行读被标记的 hook,重点看门控
每轮事件的触发频率比你想的高得多:turn.complete 连子 agent 的 turn 也会触发,turn.step 则每次模型请求都触发(一个含 20 次工具调用的 turn 就是 20 次)。一个在 turn.complete 里调模型的 hook,合格的门控长这样:
e.agentId === undefined——只处理主循环,否则 mod 会去"审"自己 spawn 的子 agent;e.reason === 'answer'且未中断——出错、被打断时不调用;- 发生了值得检查的事——本轮没有工具调用、只回了一行字,直接跳过;
- 有斜杠命令可以关掉,开关存进
$.store(重启后依然关着); - fire-and-forget:先
await next(e),再发起调用并.catch,别让用户等 hook 阻塞。
第 4 步:测量而非猜测
同一组 turn,mod 关/开各跑一遍,读三个数(模板代码见 cost-review.md 末尾):
- 每轮:
turn.complete的e.usage。缓存击穿的指纹:cache_creation暴涨、cache_read骤降; - 每次 fork:拿 fork 的
usage.cache_read_input_tokens除以$.session.usage()的context.tokens——接近 1 说明命中缓存(便宜),接近 0 说明全价付了整段前缀; - 整个会话:
$.session.usage()的cost.usd,和/cost同源,随叫随取。
第 5 步:输出一页纸成本报告
审查结束必须交给用户一份固定格式的报告(模板见 cost-review.md 末尾):
Mod: <名称> <版本> <作者>
Risk: 低|中|高:<一句话原因>
Tokens per turn: 0 | ~N(满足X时)| 一次 fork(缓存读 + ≤maxTokens 输出)
Cache impact: 无 | 一次性(某事件)| 每轮(哪个 hook 改前缀)
Off switch: /命令 | 无
It can touch: <能力清单:能碰什么、窄化到哪>
风险分级:只画 UI、只存自己状态、无或仅有门控的模型调用,算低;有门控的每轮模型调用、定向 $.http.fetch、tool.call 拒绝,算中;无门控的每轮/每步模型调用、会改写模型读到的内容、$.process / $.fs.write / $.mcp.call、tool.check 直接 allow,都是高。
安装前审查别人的插件:权限检查清单
mod 的一切行为都经过 $,所以源码就是它的"权限声明"。用 cost-review.md 第 6 节的审查表逐项过:
| 能力 | 它能做什么 | 你要问的 |
|---|---|---|
$.process.run / .spawn |
以你的身份跑宿主机命令 | 哪些 argv?有没有来自模型输出的部分? |
$.fs.write |
写你能写的任何文件 | 哪个根目录下?路径校验了吗? |
$.http.fetch |
访问机器能到达的任何 http(s) 主机 | 哪个主机?请求体里装了什么? |
$.mcp.call |
用你的凭据调用 MCP 工具(邮件、日历…),无权限提示 | 哪个服务器、哪个工具? |
$.session.authorize |
拿到你的认证句柄 | 为什么需要凭据? |
tool.check 返回 allow |
跳过权限提示 | 窄化到哪个工具和输入? |
prompt.section / prompt.context 等改写 |
改变模型读到的内容(注入通道) | 逐字读它加的每个字符串 |
从不调 next(e) 的 hook |
吞掉下面所有 mod 和引擎行为 | 这是它的设计目的吗? |
更严格的流程:读完整模块和它 import 的一切(包括 Client 模块)→ claude plugin validate + audit-mod.ts → 在临时项目里 claude --debug --plugin-dir <dir> 单独加载 → 把报告交给用户,由用户决定装不装,而不是替用户装。
ModSmith 自带模板的真实价格表
ModSmith 的现成 mod 都遵循"只在干了实事的 turn 才花 Token",每个模板的 README 有逐场景价格表(如 quiz-after/README.md):
| Mod | 功能 | 每轮成本 |
|---|---|---|
quiz-after |
任务完成后在提示框上方弹 2-3 道理解题 | 纯聊天/只读/子 agent 轮为 0;有效轮一次缓存 fork(约 350 新输入 + 200-700 输出,估算值) |
next-steps-supervisor |
检查这轮是否达标、哪里偷懒、哪需要批准 | 同上,约 250 问题 token + 100-300 输出 |
assumption-ledger |
给 Claude 一个 register_assumption 工具记账假设 |
无模型调用;约 200 缓存输入,每条记录 40-80 输出 |
mode-registry |
任何 mod 都能加入的 /mode 开关 |
无模型调用 |
effort-modes |
ui / api / review 三档 effort |
无模型调用;每次切换重建一次缓存(实测 37k 会话约 10k token 重写) |
artifact-dashboard |
多会话共享的看板摘要 | 0 模型 token;约 130 token/会话 |
minimal |
空白起点 | 0 |
💰 最生动的实测数据来自 effort-modes/README.md:在一个 37k token 的会话里,一次 /mode review 切换让缓存读从 33,323 掉到 23,387、缓存写涨到 13,528——那一轮花费约 $0.11,而平稳轮只要 $0.009。按此比例外推到 200k 上下文,切一次约 $1。结论:切换只发生在任务边界("现在开始 review 这个分支"),绝不每轮切。
如何安装并使用 ModSmith
在 Claude Code 里一次性添加市场:
/plugin marketplace add DannyMac180/skills
然后安装全量(skill + 全部 mod):
/plugin install modsmith-all@modsmith
装完直接用自然语言提问(完整工作流见 modsmith/SKILL.md):
- "What does this mod cost per turn?"(这个 mod 每轮花多少?)
- "Vet this mod before I install it"(装之前帮我审查这个 mod)
- "Make me a mod that quizzes me after each task"(做一个每轮考我的 mod)
⚠️ 提醒:quiz-after 和 next-steps-supervisor 各在"有效 turn"之后花一次缓存 fork,预期会有一点额外 Token 用量;每个 mod 都配了斜杠命令(/quiz、/supervisor)可以随时关掉。
小结:把"悄悄烧 Token"变成一张可审计的账单
- 缓存是前缀:改前缀一次付一次重写费,每轮都改等于全程全价;
- 每个模型调用都要门控:事件频率比直觉高,
turn.step一轮能触发几十次; - 先审后装:validate + audit + 权限清单 + 单独加载,出报告再决定;
- 测量而非猜测:
cache_creation/cache_read的比例就是缓存健康度; - README 第一屏写清成本和开关:多 mod 共存的这套规矩,composition.md 称之为 cache etiquette。
更多实战细节:常见坑按症状查 gotchas.md,多 mod 如何共享站点、状态与缓存看 composition.md。