用 Mods 扩展 Claude Code 的事件与界面
文章介绍在 Claude Code 内运行的 JavaScript 或 TypeScript 扩展,可响应会话事件并绘制交互界面,同时解释其与外部脚本 hooks 的区别。教程给出最小文件结构、加载及校验方式,并提醒扩展继承用户权限且不受沙箱隔离。
AI 深度解读
作者在 Claude Code 的输入框上方加了一条周额度进度条。它会在额度变化时刷新,剩余 25% 时变黄,10% 时变红。他原来跑着 70 个 settings hooks,能拦截命令、补充上下文,却一直缺一个随会话刷新的显示位置。这个位置是用 mod 加进去的。
对前端和全栈开发者来说,值得借鉴的是这条进度条的实现。三个事件就能把数据读取、状态更新和界面渲染串起来。选型时真正要算的账是,你是否需要会话内的状态和界面,以及这个需求是否值得引入一段拥有本机访问权限的代码。
为什么 70 个 hooks 也画不出一条进度条
原文援引 Anthropic 2026 年 10 月 1 日的官方博客,把 mod 定义为在 Claude Code 会话内部运行的 JavaScript 或 TypeScript 事件处理器。它随插件一起加载,在一次会话里可以持续保存状态、调用 Claude Code 提供的 API,还能在输入框上方或会话记录旁绘制界面。原文给出的起步版本是 Claude Code v2.1.287。文中提到终端、Desktop app 和 VS Code 扩展的聊天面板支持 mod,具体到 AbovePrompt 这个区域,文中明确列出的是终端和 Desktop app。

作者的 70 个 hooks 都是 shell 脚本,但 settings hooks 的能力比这更宽。它们可以调用 shell 命令、HTTP、MCP 工具,也可以交给模型或 agent 处理。它们能拦工具调用、改参数和结果、补上下文。以 shell hook 为例,事件发生时,Claude Code 启动命令,通过 stdin 和 stdout 交换 JSON。mod 的生命周期则更像一段常驻的应用代码,拿到新状态就可以刷新自己的界面。
mod 用 on(event, matcher?, ($, e, next) => ...) 注册处理器。$ 是 mods API,e 是当前事件,next(e) 把它交给链上的下一个处理器,最终可以走到 Claude Code 的默认行为。写过 Node 中间件的人可以用这套心智模型来读代码。处理器可以旁观、改写或直接回答事件,也可以监听以 classic.<Event> 暴露的 settings hook 事件,例如 classic.Stop。同一个插件还可以同时装 mod、skill 和 MCP server,分别处理会话内交互、可复用的工作流程和工具接入。
周额度进度条用了哪三个事件
作者在日本经营公司 22 年,团队每天并行开多个 Claude Code 会话制作视频、帖子和文章。这些会话共享同一份周额度,用完会一起停。原文截图里的剩余 62%、2d 5h 后重置,以及剩余 8% 时显示红色,都是展示用数字。作者实际使用的是下面这条 20 格进度条。
hooks/register.tsx 把首次取数、额度变化和界面渲染接到了三个事件上。
import { atom, read, update } from 'claude-code'
import type { Register, SessionRateLimit } from 'claude-code'
import type { WeeklyUsage } from '../types'
const weekly = atom({ plugin: 'weekly-usage-meter', key: 'weekly' } as const, null)
const METER_CELLS = 20
function pickWeekly(limits: readonly SessionRateLimit[]): WeeklyUsage | null {
const window = limits.find(limit => limit.kind === 'seven_day')
if (!window) {
return null
}
return { percentUsed: window.percentUsed, resetsAt: window.resetsAt ?? null }
}
function resetsIn(resetsAt: string | null, now: number): string {
if (!resetsAt) {
return ''
}
const ms = Date.parse(resetsAt) - now
if (!Number.isFinite(ms) || ms <= 0) {
return ''
}
const hours = Math.floor(ms / 3_600_000)
const days = Math.floor(hours / 24)
return days > 0 ? `resets in ${days}d ${hours % 24}h` : `resets in ${hours}h`
}
export const register: Register = on => {
on('session.start', async ($, e, next) => {
const usage = await $.session.usage()
const picked = pickWeekly(usage.rateLimits)
if (picked) {
await update($, weekly, () => picked)
}
return next(e)
})
on('session.measure', async ($, e, next) => {
if (e.changed.includes('rateLimits')) {
const picked = pickWeekly(e.rateLimits)
if (picked) {
await update($, weekly, () => picked)
}
}
return next(e)
})
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
const value = await read($, weekly)
if (e.props.hasSurvey || value === null) {
return next(e)
}
const { Box, Text } = $.ui.resolve(e)
const used = Math.min(100, Math.max(0, value.percentUsed))
const left = Math.max(0, Math.round(100 - used))
const filled = Math.round((left / 100) * METER_CELLS)
const empty = METER_CELLS - filled
const color = left <= 10 ? 'error' : left <= 25 ? 'warning' : 'success'
const reset = resetsIn(value.resetsAt, await $.clock.now())
return (
<Box gap={1}>
<Text dimColor>Weekly</Text>
<Text>
<Text color={color}>{'█'.repeat(filled)}</Text>
<Text dimColor>{'░'.repeat(empty)}</Text>
</Text>
<Text color={color} tabular>{left}% left</Text>
<Text dimColor>{reset}</Text>
</Box>
)
})
}
看 if (e.changed.includes('rateLimits')) 这一行。session.measure 在每轮结束以及套餐额度使用比例变化时都会触发,仪表只在变更字段包含 rateLimits 时尝试更新。启动时,$.session.usage() 返回 startedAt、context、rateLimits 和 cost,模块从额度列表里挑出 kind 为 seven_day 的记录。渲染时,atom、read 和 update 操作的 $.state 能跨模块热重载保留,而且状态变化会让读取它的界面重绘。碰到问卷或状态为空,渲染处理器用 next(e) 把位置交回处理链。
从写出第一个 mod 到给同事试用,要过哪些关
最小 mod 有三个文件。.claude-plugin/plugin.json 写插件元数据,hooks/hooks.json 用 "modules": ["./register.tsx"] 指向处理器,hooks/register.tsx 实现逻辑。作者的 weekly-usage-meter 版本是 0.1.0,因为用了 $.state,还要在清单里加 "types": "./types/index.d.ts",在声明文件里扩展 PluginState。实际目录还有 tsconfig.json,Claude Code 加载时会把当前构建的类型声明写入 .claude-plugin/types/。如果文档和本机声明对不上,原文建议以本机声明为准。
可以让 Claude 用内置的 /plugin-authoring skill 起草。它会把文件写到 ~/.claude/dev-mods/ 下以会话 ID 命名的目录。首次保存时选择 Enable for this session,mod 会在这轮结束时加载。这个临时目录受 cleanupPeriodDays 管理,要留用就复制到自己的目录,用 claude --plugin-dir ~/mods/your-mod 加载,保存文件即可热重载。
发布前跑 claude plugin validate。它静态列出注册的事件和 API 调用,教程里的 /tally 示例会列出 command.run{command=tally}、ui.render{component=Spinner},以及 $.command.register、$.ui.invalidate。为了让校验器识别这些信息,事件名用 'tool.call' 这样的字符串字面量,API 调用写全,例如 $.store.get('notes')。模块使用 ES import,本地导入留在插件目录内,唯一允许的裸导入是 claude-code。
团队分发可以在仓库放 .claude-plugin/marketplace.json。原文示例依次运行 /plugin marketplace add your-org/my-mods、/plugin install token-weather@my-mods 和 /reload-plugins。也可以从 shell 用 claude plugin install token-weather@my-mods,通过 --scope 选 user、project 或 local。安装副本按版本缓存,开发时继续用 --plugin-dir,发新版时提升版本号,并在 README 里写清测试过的 Claude Code 版本。校验还会拒绝 claude- 这类容易与官方插件混淆的名称。
我的判断
作者给出了自己在用的完整模块,也交代了并行会话为什么需要这条进度条。文章没有给出对照数据,无法判断它节省了多少查询时间,或者帮团队减少了多少次因额度耗尽而中断。共享周额度、频繁切换会话的团队有明确的使用动机。偶尔查一次额度的人,用现有查询方式就够了。类似的,若需求只是每次提交提示时补一段上下文,可以先看 settings hook 能否覆盖。
安装第三方 mod 时,要把它当作有本机访问权限的依赖来审。按原文描述,它可以读取环境变量、配置和会话内容,也可以写文件、启动程序、发网络请求并消耗模型额度。Claude Code 的 Bash 沙箱只隔离 Claude 发起的 Bash 命令,mod 启动的进程在该沙箱之外。原文还指出,在没有 managed settings,且会话没有用 Team 或 Enterprise 凭据登录时,已安装的 mod 可能批准原先被 deny rule 或 PreToolUse 拒绝的调用。有 managed settings 或使用这两类凭据时,这些拒绝默认保留。claude plugin validate 的 calls: 可以辅助审查。实际代码和组织权限配置才决定你愿意让这个插件做什么。
能拿来做什么
- 如果团队反复手查当前 Git 分支或会话额度,先给自己做一个只读的
AbovePrompt小组件。用--plugin-dir本地试跑,实际看一次热重载、状态变化和无数据时的显示效果。 - 如果需求是复核 Claude 上一轮改了哪些前端文件,可以参考 Replay Theater 的
/replay,一次看一个 diff。若只想知道还有多少上下文可用,可以先看约 80 行的 Token Weather,用一个显示位置验证需求。 - 如果要把 mod 发给同事,先核对
claude plugin validate列出的事件和calls:,再检查入口模块及其导入。把测试过的 Claude Code 版本写进 README,并用安装后的版本跑一遍/reload-plugins。