SpyBara
Go Premium

plugins/mods/reference.md 2026-10-01 23:59 UTC to 2026-10-02 16:57 UTC

This page contains 326 additions and 0 deletions.

2026
Fri 2 18:59

Mods 參考資料

Claude Code mod 的完整參考資料：hook 模組配置、事件、mods API 方法、轉譯位置、各使用介面的元素、限制與設定。

查詢 mod 可處理的任何事件、可呼叫的任何 mods API 方法，或可繪製的任何轉譯位置，適用於 v2.1.287 版起的 Claude Code CLI 與 Desktop 應用程式。每個項目皆提供名稱與一行說明，若有對應的指南章節，亦會連結至該處。

檔案

mod 是包含下列檔案的外掛目錄：

檔案 必要 內容
.claude-plugin/plugin.json 是 外掛資訊清單。mod 不會新增任何必要欄位。
hooks/hooks.json 是 modules：一個陣列，內含一個相對於此檔案、指向 hook 模組的路徑，例如 "modules": ["./register.js"]。也可以在 hooks 下存放設定 hook。
hook 模組，例如 hooks/register.js 是 mod 的進入點。匯出 register(on, options)。檔名為 .js、.mjs、.cjs、.jsx、.ts、.mts、.cts 或 .tsx。為 ES 模組。
types/index.d.ts，由資訊清單中的 types 指定 當 mod 使用 $.state 或在 mods API 中新增命名空間時 宣告 PluginState 值以及 mod 新增的任何命名空間
檔名以 .test.ts 或 .test.tsx 結尾的檔案 否 claude plugin test 執行的測試

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 的錯誤處理常式。

引數 說明
$ mods API：mods API 方法中的每個方法。每次呼叫請完整寫出，先命名空間再方法，例如 $.fs.read('notes.md')。
e 事件的輸入，為深度凍結的純資料。若要變更，請將副本傳給 next。
next(e) 下一個處理常式，如同中介軟體。會執行此 hook 之後的 hook，接著執行 Claude Code 的行為。解析為事件的結果。
next.signal 一個 AbortSignal，在事件被放棄時中止
next.origin 觸發事件者的 { plugin, tier }。Claude Code 本身為 { plugin: 'engine', tier: 'core' }。mod 的 tier 是它在 mod 執行順序中的優先群組：prepend、user、append 或 builtin。
next.budget hook 的時間限制（毫秒）：next.budget.ms 為整體限制，next.budget.remainingMs 為目前剩餘時間
next.to(e, tier) 跳至較後面的層級，即 append、builtin 或 core。next.to(e, 'append') 會略過使用者安裝的 mod。只有 prependPlugins 或 appendPlugins 中的 mod 可以呼叫它。
next.error、next.called 僅限 .catch 處理常式中。next.error.kind 為 throw 或 timeout，next.error.message 為錯誤文字，當失敗的 hook 曾呼叫 next 時，next.called 為 true。

事件

事件依其相關內容分組，並列出每個事件的觸發時機，以及其上的 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 讀取的說明，到是否執行該呼叫的決定：

事件 觸發時機 hook 可回傳
tool.call 工具即將執行時 next(e)、{ deny: reason } 或 { result }
tool.check Claude Code 在 tool.call 與 PreToolUse hook 之後，決定工具呼叫是否可以執行時。next(e) 會解析為規則、權限模式與這些 hook 所得出的決定。 { decision }，值為 allow、ask 或 deny
tool.describe 每個工具一次，在其說明首次傳送給 Claude 時 { description }

提示詞與 Claude 讀取的內容

提示詞事件涵蓋使用者輸入的文字，以及 Claude Code 自行傳送給 Claude 的文字，例如系統提示詞與提醒：

事件 觸發時機 hook 可回傳
prompt.submit 提交提示詞時 next({ ...e, text })、next({ ...e, context }) 或 { drop: reason }
prompt.fill、prompt.suggest 文字即將以草稿或淡色建議的形式放入提示詞輸入框時 變更了文字的 next(e)
prompt.edit 使用者編輯提示詞輸入框時 next(e)
prompt.compose Claude Code 轉譯系統提示詞時 { sections }，即依傳送順序排列的 { id, text, scope } 清單
prompt.section 系統提示詞的每個具名區段各一次。e.name 是該區段在 prompt.compose 中的 id。 { text }，或以 { text: null } 省略該區段
prompt.context 每個對話一次，針對隨第一則訊息傳送的上下文 { blocks }
prompt.attachment Claude Code 為 Claude 新增一則自己的訊息時，例如提醒。e.type 指出種類，對於型別有宣告的種類，e.detail 存放撰寫該文字所依據的事實。 { text }，或以 { text: null } 省略
skill.prompt skill 的文字為 Claude 展開時 { text }
attribution.text Claude Code 撰寫提交或 pull request 的歸屬文字時 { text }

命令與設定

命令與設定事件在命令執行或被列出時，以及 /config 列被顯示或變更時觸發：

事件 觸發時機 hook 可回傳
command.run 命令即將執行時 { text }、{} 或 next(e)
command.describe 每個命令一次，用於命令清單 { description, argumentHint, isHidden }
config.set /config 列即將變更時 next({ ...e, value }) 或 { deny: reason }
config.describe 每個 /config 列一次 { label, description, isHidden }

回合

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

事件 觸發時機 hook 可回傳
turn.start 回合開始時 next(e)
turn.step 一個請求即將傳送給模型時 yield* next(e)，或 next({ ...e, model })、next({ ...e, effort })
turn.complete 回合結束時 next(e)，或以 { text } 在回答下方顯示一行

工作階段

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

事件 觸發時機 hook 可回傳
session.start 每個已載入的 mod 一次，在第一個提示詞之前，並在該 mod 重新載入後再次觸發。/clear、/resume 或 /branch 之後不會觸發。 next(e)
session.end 工作階段結束，或執行 /clear、/resume 或 /branch 時。e.reason 為 clear、resume、logout、prompt_input_exit 或 other。/branch 會回報 resume。 next(e)
session.compact 對話即將被壓縮時 { skip: reason }
session.receive、session.send 訊息從另一個 agent 或工作階段送達，或即將傳送至另一個 agent 或工作階段時。請參閱在工作階段之間傳送與接收訊息。 receive 為 { consumed: reason }，send 為 { isDelivered: false, reason }
session.append 對話保留的每一列各一次，例如提示詞、回應區塊、工具結果或通知，在其儲存之前 以 next({ ...e, message }) 改寫該列的 content
session.attach、session.detach 另一個應用程式連線至工作階段或與其中斷連線時 next(e)
session.measure 每個回合之後，以及方案限制的使用百分比變更時 next(e)

Subagent

subagent 事件在 subagent 類型提供給 Claude 時，以及 subagent 即將啟動時觸發：

事件 觸發時機 hook 可回傳
agent.offer subagent 類型提供給 Claude 時 以 { isOffered: false } 保留不提供
agent.spawn subagent 即將啟動時 { model } 或 { deny: reason }

介面

介面事件在 Claude Code 繪製轉譯位置時，以及使用者使用 mod 所繪製的控制項時觸發。在介面中繪製說明 ui.render hook 回傳的內容：

事件 觸發時機
ui.render 轉譯位置即將被繪製時
ui.resolve mod 載入時，每個應用程式、轉譯位置與 mod 各一次。結果是 $.ui.resolve(e) 讀取的元素表。
ui.press、ui.input、ui.select mod 所繪製的 Button、Input 或 Select 被使用時
ui.focus、ui.scroll 焦點所在的控制項，或窗格或橫帶的捲動位置即將變更時
ui.close 窗格即將關閉時。e.id 為該窗格，e.origin.kind 為 plugin、person 或 unload。
ui.message Client 元素將資料傳送給其 mod 時

其他 mod

這些事件讓 mod 能在其他 mod 載入時對其採取行動，例如拒絕某個 mod，或變更它所接收的 mods API：

事件 觸發時機 hook 可回傳
plugin.register hook 模組即將載入時。e.uses 列出其事件、mods API 呼叫、環境變數與狀態，與 claude plugin validate 印出的內容相同。每個呼叫都不含 $. 前綴，例如 fs.read。 { refuse: reason }
engine.create 正在為此 mod 建置 mods API 時 變更後的 mods API，用以新增或保留某個命名空間

遙測

遙測事件針對 Claude Code 記錄的使用紀錄觸發：

事件 觸發時機 hook 可回傳
telemetry.log、telemetry.mark 遙測紀錄即將被記錄，或標記某項功能的一次使用時。在您安裝的 mod 中，請為遙測 hook 加上篩選條件 { to: 'collector' }，例如 on('telemetry.log', { to: 'collector' }, hook)。若沒有此篩選條件，該 mod 將無法通過 claude plugin validate。* 不會比對這些事件。 next(e) 或 { deny: reason }

設定 hook 事件

每個設定 hook 事件都是名為 classic.<Event> 的事件，例如 classic.Stop 或 classic.PostToolUse。e 是該 hook 的 stdin JSON。

mods API 呼叫

每個 mods API 方法也是一個事件，以其命名空間與方法命名，例如 fs.read、model.complete 或 ui.open。其上的 hook 會攔截在它之後執行之 mod 的呼叫，並可回傳 next(e)、{ deny: reason } 或 { value }。

Mods API 方法

mods API 是每個 hook 接收的 $ 引數。其方法依命名空間分組，例如 $.ui。此表依名稱列出每個命名空間的方法，因此 $.ui 列中的 open 即為呼叫 $.ui.open(...)。指南會示範常用方法的用法，而您建置版本的型別則以範例記錄每個方法。

命名空間 方法
$.plugin name、root：此外掛的名稱與目錄
$.ui resolve、invalidate、open、close、panes、focus、scroll、toast、status、log、notice、ask、copy、blit
$.command register、run、list
$.tool register、call、check、list
$.agent register、spawn、list
$.model complete、fork、classify
$.prompt submit、read、fill、suggest、compose。Claude 會在一個指明您的 mod 為傳送者的句子之後，讀取來自 submit({ text }) 的文字。submit({ text, asUser: true }) 會將文字當作使用者本人的話傳送，不附帶該句子。
$.turn abort
$.session messages、cwd、root、model、turns、id、repo、surfaces、usage、version、compact、send、append、authorize。usage() 回傳 { startedAt, context, rateLimits, cost }：context 包含 tokens、window 與 percent，rateLimits 是 { kind, percentUsed, resetsAt } 的清單。
$.config list、set
$.settings read
$.env get、set
$.fs read、write、list、exists、stat、ancestors。write 不是不可分割的操作：它會就地取代檔案內容，因此其他程序可能讀到寫入一半的檔案。多個工作階段都會變更的資料，請存放在 $.store 中。
$.store get、set、delete、keys。由機器上每個工作階段共用的鍵值儲存區。請參閱從多個工作階段儲存。
$.state 反應式狀態：get、set，以及從 claude-code 匯入的輔助函式 atom、read、update、derive 與 memberOf
$.clock now、sleep、after、every
$.http fetch
$.process run、spawn
$.mcp call、connect。connect(server) 會連線至您自己外掛的資訊清單所列出的 MCP 伺服器。
$.audio play、speak
$.telemetry log、mark。只有當 Claude Code 或內建 mod 發出呼叫時，才會傳送紀錄。

轉譯位置

轉譯位置是 Claude Code 介面中的擴充點。每一列都是 ui.render hook 中 e.component 的一個值，並列出 e.props 的欄位以及轉譯它的應用程式。e.surface 為 terminal 或 desktop。變更 Claude Code 既有的繪製內容說明 hook 能在某個位置做什麼，並為每種選擇提供範例。

位置 e.props e.requestId 轉譯於
Pane title、isFocused、bodyColumns、placement、scroll、view 窗格的 id 終端機、Desktop
AbovePrompt hasSurvey、isWorking、maxRows、bodyColumns、scroll、view 單一實例 終端機、Desktop
UserMessage text、origin、isExpanded，以及依來源而定的 task 或 from 訊息 id 終端機、Desktop
AssistantMessage 回覆的文字 訊息 id 終端機、Desktop
ToolUse、ToolResult、ToolGroup 工具的名稱、輸入與結果 工具呼叫 id 終端機、Desktop
CommandOutput command、text 訊息 id 終端機、Desktop
AskUserQuestion 問題與選項 工具呼叫 id 終端機、Desktop
ToolProgress kind 工具呼叫 id 終端機
Spinner word、message、suffix、mode agent id 終端機、Desktop
TurnDuration word、durationMs 訊息 id 終端機
InfoNotice text、command 訊息 id 終端機
SessionMode modes 單一實例 終端機、Desktop
PromptHint isDraft、isWorking、hint 單一實例 終端機、Desktop

e.viewport 存放 columns、rows 與 isFullscreen。在應用程式量測其視窗之前，它不會存在。其 rows 是整個視窗的高度，而非您窗格的高度。

若要讓樹狀結構符合其位置，請在 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) 取得。從元素建立樹狀結構會展示常用元素以及終端機如何繪製它們，介面圖庫則提供大多數元素的螢幕截圖。勾號表示該應用程式可以繪製此元素。

元素 主要 prop 終端機 Desktop
Box key、flex 版面配置、gap、padding、margin、width、height、borderStyle、backgroundColor、position、hover ✓ ✓
Text color、backgroundColor、bold、italic、underline、dimColor、inverse、wrap ✓ ✓
Button key、label、onPress、hotkey、plain、dimColor、autoFocus、action ✓ ✓
Link href、label ✓ ✓
Code 程式碼，最多 10,000 個字元 ✓ ✓
Markdown text（最多 10,000 個字元）、key、dimColor、onLinkPress、pressableLinks ✓ ✓
Input key、label、placeholder、value、submitLabel、onSubmit、onInput、autoFocus ✓ ✓
Select key、label、options、value、onSelect、autoFocus ✓ ✓
Svg SVG 文件，最多 131,072 個字元 ✓
Client module、key ✓ ✓
Raster key、最多 512 的 columns、最多 256 的 rows、cells。請參閱繪製彩色儲存格網格。 ✓
Image 最多 2 MiB 的 PNG 或 RGBA 位元組，或檔案路徑 ✓

更多 Button 規則：action 指定 Claude Code 本身的某個快捷鍵動作，當使用者對該動作的綁定為組合鍵或修飾鍵時，該綁定會按下此按鈕。橫帶中按鈕上的數字 hotkey，在使用者於空白提示詞中單獨輸入該數字並停頓時也會觸發。當同一次繪製中有兩個按鈕指定相同的 hotkey 時，由後者取得。autoFocus 在任何控制項上都只接受 true，因此若要關閉，請省略此 prop。

限制

hook 與 mods API 呼叫都在時間與大小限制下執行。Claude Code 會略過超過時間限制的 hook，並拒絕超過大小限制的呼叫。

限制 值
hook 針對單一事件本身的執行時間，不計入 next 內部或 $.clock.sleep 以外之 mods API 呼叫內部的時間 10 秒
.catch 處理常式的執行時間 1 秒
所有 session.end hook 合計 1.5 秒
$.process.run 逾時 預設 30 秒，最多 10 分鐘
$.model.complete maxTokens 預設 1024，最多 64,000 或模型的輸出上限
$.fs.read 與 $.fs.write 單一檔案 4 MiB
Text 的單一字串子項 10,000 個字元
$.store 總計 4 MiB 的 JSON
$.session.messages() 最新的 4,096 個項目
$.ui.invalidate('ui.render') 重新繪製 節流為每秒 10 次，在終端機中針對可見窗格、展開的橫帶與提示詞下方的提示行則為每秒 30 次。更早到來的呼叫會被合併。
$.ui.toast 顯示 4 秒，除非您傳入 { timeoutMs }
未經使用者要求而開啟的窗格 自 144 個終端機欄寬起放置，使用者開啟過一次後則為 110
命令、工具、subagent 類型與窗格名稱 字母、數字、_ 與 -，最多 64 個字元
單一 claude plugin test 測試 5 秒，除非測試設定了 timeoutMs

設定與環境變數

以下是影響 mod 的設定與環境變數。「位置」欄說明每一項是從哪個設定檔或環境讀取：

名稱 位置 作用
CLAUDE_CODE_PLUGIN_DIRS 環境，或 ~/.claude/settings.json 中的 env 以 --plugin-dir 的方式載入的外掛目錄，供無法傳入旗標的應用程式使用。以 : 分隔的絕對路徑，在 Windows 上則以 ; 分隔。
CLAUDE_CODE_PLUGIN_DIR_WATCH 環境 1 會讓長時間執行的非互動式工作階段在儲存時重新載入 --plugin-dir mod
prependPlugins、appendPlugins 受管設定。僅在沒有受管設定的機器上、且使用者未以 Team 或 Enterprise 方案登入時，才可使用使用者設定。 外掛 id 的清單，例如 acme-guard@acme-tools。prependPlugins 中的 mod 會在使用者安裝的每個 mod 之前執行，appendPlugins 中的 mod 則在之後執行，並依列出的順序。請參閱 mod 執行順序。
allowManagedModsOnly 受管設定，作為內建防護的選項 只有屬於您組織的 mod，以及內建於 Claude Code 的 mod 會載入。使用者的設定 hook 會繼續執行。
allowModsToOverrideDenyRules 受管設定，作為內建防護的選項 允許使用者安裝的 mod 核准遭 deny 規則拒絕的工具呼叫
allowManagedHooksOnly 受管設定 封鎖不屬於您組織的 hook 與已安裝的 mod。請參閱哪些會繼續執行。
disableAllHooks 任何設定檔 在受管設定中，已安裝外掛的任何 mod 或 hook 都不會執行。在您自己的設定中，您組織所管理的內容會繼續執行。請參閱 disableAllHooks。
disableSideloadFlags 受管設定 在啟動時拒絕 --plugin-dir 與 --plugin-url
pluginConfigs 使用者或受管設定 存放 mod 的 userConfig 值，以外掛 id 為鍵，例如 acme-guard@acme-tools；若是以 --plugin-dir 載入的外掛，則以其名稱加上 @inline 為鍵，例如 first-mod@inline

sec-default@builtin 是內建於 Claude Code 的防護，在 /plugin 與偵錯日誌中列為 cc-plugin-sec-default。在具有受管設定的機器上，或對於以 Team 或 Enterprise 方案登入的使用者，它會在使用者安裝的每個 mod 之前載入。若設定了受管 prependPlugins，則只有在該清單列出此防護時才會載入，並位於所列的位置。其原始碼位於 Claude Code 儲存庫的 mods/sec-default 目錄。

命令

這些命令與旗標用於載入、檢查與測試 mod。claude 命令在您的 shell 中執行，/ 命令則在 Claude Code 提示詞輸入處執行。表格中的 <directory> 代表您輸入的路徑，例如 claude plugin validate ./first-mod。方括號表示選用的引數。

命令 作用
/plugin 當非內建的 mod 已載入時，在其分頁下方顯示如 1 mod active · first-mod 的一行
claude plugin validate <directory> 讀取外掛的資訊清單與 hook 模組，並回報錯誤、其處理的事件，以及其發出的 mods API 呼叫。--strict 會將警告視為錯誤，--json 會印出機器可讀的報告。
claude plugin test [directory] 執行該目錄下（未指定時則為目前目錄）所有檔名以 .test.ts 或 .test.tsx 結尾的檔案。測試失敗時以狀態 1 結束。
claude --plugin-dir <directory> 為單一工作階段載入外掛目錄，並在您儲存時重新載入其 hook 模組。重複使用此旗標可載入多個目錄。
/reload-plugins 在您執行時重新載入外掛