跳转到主要内容
查阅 mod 可以处理的任何事件、可以调用的任何 mods API 方法,或可以在其中绘制的任何渲染位置。条目涵盖 v2.1.290 起的 Claude Code CLI 和 Desktop 应用,以及 v2.1.299 起的 VS Code 扩展。每个条目给出名称和一行描述,如有相应的指南章节,还会链接到该章节。
完整的参考是 Claude Code 的 mod TypeScript 声明,其中描述了每个事件、方法和元素,并附有示例。GitHub 上的副本可能比您安装的 Claude Code 版本更旧。两者不一致时,请以 Claude Code 为您的版本写入的副本为准。

文件

mod 是一个包含以下文件的插件目录: register 接收 on 和 options。options 包含清单所声明的 userConfig 字段的值,并已填入默认值。

hook 函数

mod 通过在 register 内调用 on 来注册它的每个 hook(即事件处理程序)。on 接受事件名称、一个可选的匹配器(即对事件字段的过滤条件)以及 hook,如 on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))。on 返回一个注册对象,它只有一个方法 .catch(handler),用于设置该 hook 的错误处理程序。

事件

事件按其涉及的内容分组,每个事件都列出了触发时机以及其上的 hook 可以返回的内容。turn.step 和 process.spawn 上的 hook 是异步生成器,其他 hook 是异步函数。 每个表格的最后一列使用简写。next(e) 原样传递事件。next({ ...e, text }) 传递一个更改了指定字段的副本,如 next({ ...e, text: e.text.trim() })。对象表示不调用 next 而直接应答该事件,而 reason 之类的词代表您编写的字符串,如 { deny: 'Use the file tools.' }。

工具

工具事件围绕 Claude 发出的每个工具调用触发,涵盖从 Claude 读取的描述到是否运行该调用的决定:

tool.check 上的 Agent 和组织字段

在 tool.check hook 中,读取以下字段可区分子代理的调用与主对话的调用,并查看您的组织是否要求对某个连接器工具进行批准: 在 tool.check 上,e.agentId 和 e.ceiling 需要 Claude Code v2.1.290 或更高版本。

tool.check 上的 e.isReadOnly 字段

在 tool.check hook 中,当工具报告此次调用为只读时,e.isReadOnly 为 true。否则该字段不存在,而不是 false。该值是工具自身的报告,因此在仅凭此字段批准某个调用之前,请先阅读检查工具调用是否为只读。 在 tool.check 上,e.isReadOnly 需要 Claude Code v2.1.304 或更高版本。

提示词以及 Claude 读取的内容

提示词事件涵盖用户输入的文本,以及 Claude Code 自行发送给 Claude 的文本,例如系统提示词和提醒:

skill.prompt 上的来源和 frontmatter 字段

在 skill.prompt hook 中,除了 e.skill 中的 skill 名称和 e.text 中 Claude 读取的文本之外,您还可以读取以下字段: hook 可以将更改后的 text 或 frontmatter 传给 next:其后的 hook 会读取这两者,而 Claude 读取最终的 text。更改任何其他字段的 hook 会失败。 在 skill.prompt 上,e.source、e.pluginName、e.path、e.frontmatter 和 e.frontmatterProblem 需要 Claude Code v2.1.299 或更高版本。

使用 breakPromptCache 发送更改后的系统提示词部分或工具描述

要在正在运行的对话中更改某个部分或工具描述,请调用 $.ui.invalidate('prompt.section') 或 $.ui.invalidate('tool.describe'),使您的 hook 再次运行,并从中返回 { text, breakPromptCache: true } 或 { description, breakPromptCache: true }。如果没有该字段,对于某个部分或预先加载的工具,Claude 会继续读取随对话保存的文本,直到开始新对话或进行压缩。 更改后的文本会在下一轮次传达给 Claude,并且提示缓存会重新开始,因此该轮次会更慢且成本更高。该字段需要 Claude Code v2.1.321 或更高版本。从 v2.1.299 到 v2.1.321 之前,正在运行的对话会在下一轮次获得更改后的文本。

命令和配置

settings.read 上的 e.layers 和 e.source

  • e.layers:每个正在使用且包含设置的来源对应一个 { source, settings } 对象,优先级最低的排在最前。请参阅settings.read hook 接收的内容。
  • e.source:mod 所请求的那一个来源,如 $.settings.read({ source: 'policy' })。在 Claude Code 自身的读取以及对合并设置的读取中不存在

轮次

轮次事件从头到尾跟踪一次回答,包括其中每个发往模型的请求:

会话

会话事件标记会话的开始、结束、压缩,以及与其他会话交换消息:

子代理

子代理事件在向 Claude 提供某个子代理类型时,以及子代理或 agent team 队友即将启动时触发: 当已完成或已停止的子代理即将再次运行时,例如 Claude 使用 SendMessage 工具向其发送消息时,您的 agent.spawn hook 也会运行。在该事件中,e.resume 为 { agentId }。如果您的 hook 会统计子代理数量,请跳过设置了 e.resume 的事件,以免恢复的子代理被重复计数。 返回 { deny: reason } 可拒绝恢复的运行。该运行不会开始,子代理保持原样。当运行是由 SendMessage 调用请求的时,Claude 读取到的该调用结果为 a plugin declined the resume: 后跟您给出的原因。如果您为恢复的运行向 next 传递更改后的事件,例如不同的 model,Claude Code 会忽略该更改。
恢复运行的事件需要 Claude Code v2.1.299 或更高版本。在 v2.1.299 之前,子代理恢复时您的 agent.spawn hook 不会运行。在这些版本上,要拒绝恢复子代理的 SendMessage 调用,请在 tool.call hook 中匹配该工具。

界面

界面事件在 Claude Code 绘制渲染位置时,以及用户使用 mod 绘制的控件时触发。在界面中绘制展示了 ui.render hook 返回的内容:

其他 mod

这些事件让 mod 在其他 mod 加载时对其进行操作,以拒绝某个 mod 或更改它收到的 mods API: 当另一个 mod 的 hook 调用您在 engine.create 中添加的命名空间上的方法时,在该事件上的所有 hook 返回之前,您的方法发出的 $ 调用都在该 hook 的上下文中运行。例如,相对路径基于该 hook 的工作目录解析,而当轮次正在等待该 hook 时,$.prompt.submit 会被拒绝。在此之后您的方法发出的调用将在您的 mod 自身的上下文中运行。

遥测

遥测事件针对 Claude Code 记录的使用情况记录触发:

设置 hook 事件

每个设置 hook 事件都是一个名为 classic.<Event> 的事件,如 classic.Stop 或 classic.PostToolUse。e 是该 hook 的 stdin JSON。

mods API 调用

每个 mods API 方法也是一个事件,以其命名空间和方法命名,如 fs.read、model.complete 或 ui.open。其上的 hook 可以返回 next(e)、{ deny: reason } 或 { value }。 其中一些事件也会针对 Claude Code 自身的操作触发,因此在拒绝某个事件之前,请先检查 next.origin.plugin 是否为 engine。

Claude Code 自身 http.fetch 请求上的字段

在 http.fetch hook 中,值为 { plugin: 'engine', tier: 'core' } 的 next.origin 标记的是 Claude Code 自身的请求(例如模型请求),而不是 mod 的 $.http.fetch 调用。在加载了内置守卫的情况下,您的 hook 不会收到这些事件,除非您的 mod 被视为您组织的 mod。 在这些事件中,e.init 以及 next(e) 解析得到的 value 可以包含以下字段等: 这些事件和字段需要 Claude Code v2.1.321 或更高版本。

mods API 方法

mods API 是每个 hook 接收的 $ 参数。它的方法按命名空间分组,例如 $.ui。此表按名称列出每个命名空间的方法,因此 $.ui 行中的 open 就是调用 $.ui.open(...)。指南展示了常用方法的用法,而您的构建版本的类型记录了每个方法并附有示例。

渲染位置

渲染位置是 Claude Code 界面中的扩展点。每一行是 ui.render hook 中 e.component 的一个值,并列出了 e.props 的字段以及渲染它的应用。e.surface 指明正在绘制的应用,例如 terminal、desktop 或 vscode。更改 Claude Code 已绘制的内容展示了 hook 在某个位置可以做什么,并为每种选择提供了示例。 在 VS Code 扩展中进行渲染需要扩展版本 2.1.299 或更高版本。不获取功能标志的会话需要 2.1.304 或更高版本。在 VS Code 扩展中绘制列出了该扩展在绘制上的不同之处。 e.viewport 包含 columns、rows 和 isFullscreen。在终端和 Desktop 应用中,在应用测量其窗口之前,它不存在。在这两处,它的 rows 是整个窗口的高度,而不是您的窗格的高度。在 VS Code 扩展中,它始终存在。 要使树适配其所在位置,请在 hook 中读取以下 prop:
  • Pane 或横栏的宽度:按 e.props.bodyColumns 绘制
  • 会话记录旁的 Pane 的高度:当 e.props.placement 为 'dock' 时,e.props.scroll.bodyRows 是该窗格可供您的树使用的行数
  • 输入框上方的 Pane 的高度:当 e.props.placement 为 'inline' 时,窗格会随您的树增高,直到达到上限,而 bodyRows 就是该上限。如需请求不同的上限,请参阅 $.ui.open 的 rows 字段。
比窗格更高的树会整体滚动。

元素

元素是 ui.render hook 所返回的树的构建块,您可以从 $.ui.resolve(e) 获取它们。用元素构建树展示了常用元素以及终端如何绘制它们,界面图库提供了大多数元素的截图。对勾表示该应用可以绘制该元素。 更多 Button 规则:
  • action:指定 Claude Code 自身的某个快捷键操作,当用户为该操作设置的绑定是组合键或带修饰键的按键时,该绑定会按下此按钮
  • 横栏上的数字 hotkey:当用户在空的输入框中只输入某个数字并停顿时,横栏中设置了该数字 hotkey 的按钮也会触发
  • 折叠的横栏:当横栏处于折叠状态时,action 绑定和 hotkey 都不会按下其中的按钮
  • 两个按钮使用同一 hotkey:当您在同一次绘制中的两个按钮指定相同的 hotkey 时,由后一个按钮获得它。关于另一个 mod 的按钮使用同一按键的情况,请参阅Hotkey 不起作用。
  • variant:primary 或 secondary,其他任何值都会抛出错误。在终端中,primary 按钮会以强调色绘制,除非它设置了 plain。
  • role:dismiss 将按钮标记为关闭按钮,其他任何值都会抛出错误。请在您的 onPress 中执行关闭操作。在包含文本和一行按钮的横栏中,Desktop 应用可以将该行的第一个 dismiss 按钮绘制为其自身的关闭控件。终端会像未设置 role 时一样绘制该按钮。
Button 可以用 children 代替 label:
  • children 可以是什么:字符串和 Text 元素,例如名称后跟一段暗淡的详细信息,或一个彩色标签。Claude Code 会拒绝 Button 内的任何其他元素。
  • 为按钮命名:label 为按钮命名,默认为其 children 的文本。对于 children 不是单个字符串的按钮,请为其提供 key 或 label。
  • 在终端中:children 绘制在 label 原本所在的位置,在其上任意位置按下都算作一次按下,因此您可以将列表的每一行做成单个按钮
  • 在 Desktop 应用和 VS Code 扩展中:按钮绘制其 label
children 不是单个字符串的 Button 需要 Claude Code v2.1.295 或更高版本。
autoFocus 在任何控件上都只接受 true,因此要关闭它,请省略该 prop。 VS Code 扩展会忽略某些元素 prop,并像您省略了这些 prop 一样绘制该元素:
  • Box:position 及其 top、left、right 和 bottom,alignSelf、borderDimColor 和 hover
  • Text:size、mono、tabular 和 hover
  • Button:hotkey、plain、autoFocus、action 和 hover,因此用户在其中通过点击来按下按钮,或在按钮获得焦点后按 Enter。该扩展也会忽略 variant 和 role。
  • Code:language、path、startLine、format 和 wrap,因此代码绘制时不带颜色或行号,而 format: 'diff' 代码块会显示 diff 的原始文本
  • Input 和 Select:autoFocus,以及 Input 上的 rows
  • Svg:isInteractive

Box 边框样式

要在 Box 周围绘制边框,请将其 borderStyle 设置为以下名称之一,例如 borderStyle: 'round'。每一行说明终端针对该名称绘制的内容,并展示边框的上边缘。 如果 Box 的 borderStyle 指定的是其他名称(例如 'rounded'),则绘制时不带边框。

Box 间距步长

Box 的间距 prop 包括 gap、columnGap、rowGap、padding、margin,以及 padding 和 margin 的单边和单轴形式,例如 paddingX 和 marginTop。每个 prop 都接受以终端单元格为单位的数字(例如 gap: 1),或步长名称(例如 gap: 'md')。在终端和 VS Code 扩展中,每个步长对应的单元格数如下: 如果将 gap、padding 或 margin 设置为某个步长,该步长会同时应用于横向和纵向。例如,在终端和 VS Code 扩展中,padding: 'md' 表示左右两侧各两个单元格,上下各一行。 步长名称需要 Claude Code v2.1.299 或更高版本。在更早的版本中,使用了步长名称的树不会绘制。

Text 排版 prop

在 Text 上设置 size、weight、mono 或 tabular,可以请求绘制您的树的应用使用某种文字大小、字重、等宽字体或等宽数字。在依赖某个 prop 之前,请先确认终端和 VS Code 扩展如何处理它。如果某个应用忽略了您设置的 prop,您的树仍会在其中绘制,文本显示效果与您省略该 prop 时相同。 这四个 prop 需要 Claude Code v2.1.299 或更高版本。在更早的版本中,设置了 size、weight、mono 或 tabular 的树不会绘制。

用 weight 替换 bold

Text 上的 bold 已弃用,建议改用 weight,但它仍然可用。要在未设置 weight 的 Text 上替换它,请将 bold: true 改为 weight: 'semibold',在 Claude Code v2.1.299 或更高版本上效果相同。 在早于 v2.1.299 的版本中,设置了 weight 的树不会绘制。如果您在 Text 上同时设置了 bold 和 weight,则 bold 不起作用。

限制

hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。超出嵌套、元素、Raster 单元格或 Image 字节限制的树不会被绘制。

设置和环境变量

以下是影响 mod 的设置和环境变量。“位置”列说明每一项从哪个设置文件或环境中读取: sec-default@builtin 是 Claude Code 内置的守卫,在 /plugin 和调试日志中显示为 cc-plugin-sec-default。在它会加载的情况下,它会在用户安装的每个 mod 之前运行。如果设置了托管的 prependPlugins,则只有当该列表指定了该守卫时它才会加载,并位于列出的位置。 其源代码位于 Claude Code 仓库的 mods/sec-default 目录中。

命令

这些命令和标志用于加载、检查和测试 mod。claude 命令在您的 shell 中运行,/ 命令在 Claude Code 输入框中运行。表中的 <directory> 代表您输入的路径,如 claude plugin validate ./first-mod。方括号表示可选参数。