跳轉到主要內容
查詢 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 接受事件名稱、選用的 matcher(針對事件欄位的篩選條件),以及 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 中,讀取這些欄位即可區分 subagent 的呼叫與主對話的呼叫,並查看您的組織是否要求連接器工具須經核准: 在 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 再次執行。並從該 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 自身的讀取,以及對合併設定的讀取中則不存在

回合

回合事件從頭到尾追蹤一次回答,包括其中每個對模型的請求:

工作階段

工作階段事件標示工作階段的開始、結束、壓縮,以及與其他工作階段交換訊息:

Subagent

subagent 事件在 subagent 類型提供給 Claude 時,以及 subagent 或 agent team 隊員即將啟動時觸發: 當已完成或已停止的 subagent 即將再次執行時,例如 Claude 使用 SendMessage 工具傳送訊息給它時,您的 agent.spawn hook 也會執行。在該事件上,e.resume 為 { agentId }。若您的 hook 會計算 subagent 數量,請略過設定了 e.resume 的事件,以免恢復的 subagent 被重複計算。 回傳 { deny: reason } 即可拒絕恢復的執行。該執行不會開始,subagent 會維持原狀。當該執行是由 SendMessage 呼叫所要求時,Claude 會讀取 a plugin declined the resume: 後接您的原因,作為該呼叫的結果。若您針對恢復的執行將變更後的事件傳遞給 next,例如不同的 model,Claude Code 會忽略該變更。
恢復執行的事件需要 Claude Code v2.1.299 或更新版本。在 v2.1.299 之前,subagent 恢復時您的 agent.spawn hook 不會執行。在這些版本上,若要拒絕恢復 subagent 的 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 呼叫。在已載入內建防護的情況下,除非您的 mod 被視為您組織的 mod,否則您的 hook 不會收到這些事件。 在這些事件上,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' 區塊會顯示差異的原始文字
  • 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。方括號表示選用的引數。