为什么你的Claude Code插件悄悄烧Token?skills的ModSmith提示缓存成本审查完整指南

原创2026-11-01 14:20:251,887 阅读

为什么你的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 概括了它的三大件:

  1. 现成可用的 6 个模板 mod;
  2. 成本与提示缓存审查:每轮花多少 token、什么会击穿缓存;
  3. 装别人插件前的安全审查:风险、成本、权限一页纸报告。

提示缓存原理:改动前缀为什么让账单翻倍

大模型的提示缓存是一个前缀,按固定顺序排列:工具定义 → 系统提示 → 消息。缓存只认前缀——只要靠前的一部分变了,后面所有内容全部作废,要按全价重新写入。

  • 一个 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 小时)或切模型后 没有冷热之说,但上下文小
适合问什么 "这次对话"的问题:任务做完了吗?做了什么假设? 分类、打标、总结一小段文字

两条实用判断:

  1. 问"这轮干了什么"用 fork,而且要在 turn 刚结束、缓存还热的时候问;
  2. 如果你发现自己在往 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 末尾):

  1. 每轮:turn.complete 的 e.usage。缓存击穿的指纹:cache_creation 暴涨、cache_read 骤降;
  2. 每次 fork:拿 fork 的 usage.cache_read_input_tokens 除以 $.session.usage() 的 context.tokens——接近 1 说明命中缓存(便宜),接近 0 说明全价付了整段前缀;
  3. 整个会话:$.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。

登录后查看全文
skills