Claude Code Mod 完整指南：介面擴充與事件處理入門（含工具計數器實作四步）

Claude Code Mod 是一種能改變 Claude Code 長相與行為的外掛：它用 JavaScript 或 TypeScript 寫成的事件處理函式，在工具被呼叫、提示詞送出、介面被繪製的瞬間介入，可以只看著事件經過、改寫它，或直接接管它。自 2.1.287 版起 Mod 預設開啟，這代表多數人已經具備使用條件，缺的只是一次親手做完的經驗。這篇指南把 Mod 的定位、能力邊界、與其他四種擴充方式的分工講清楚，再帶你用四個步驟做出第一個 Mod：一個掛在工作轉動圖示旁的工具呼叫計數器，做完你會經歷描述需求、核對檔案、熱重載、驗收結果的完整迴圈。

行文順序先給一分鐘答案；接著拆解 Mod 的三檔結構與「已經內建在你機器上」的事實，再把事件系統的五種能力與三種介入姿態攤開；然後用一張五路對照表處理「我到底該用 Mod 還是 Skills、MCP、設定檔掛鉤」的選擇題；實作四步是全文核心，包含提示詞怎麼下、熱重載同意框怎麼選、驗收條件怎麼定；後段處理三個實務議題：練習成果的生命週期與保存、沒反應時的三層排查（含 VS Code 殼的支援差異）、安裝別人的 Mod 前的安全查核；收在「誰該現在學、誰該再等」的判斷與行動清單。涉及版本號、指令與事件名稱的段落，都以 2026 年 10 月查閱的 Anthropic 官方文件為準。

一分鐘答案：Mod 是什麼、能做什麼、怎麼開始

Mod 是「裝了事件處理模組的外掛」。官方在 Mods 總覽文件的定義很直白：它以事件處理函式構成，Claude Code 在事件發生時呼叫你的函式，函式可以觀察、改寫或接管事件。它補上的是其他擴充機制都碰不到的兩塊：在終端機畫面裡繪製你自己的介面（側邊面板、輸入框上方的資訊帶、按鈕、文字輸入欄），以及攔截工具呼叫與提示詞的處理鏈。版本門檻是 2.1.287 以上，Claude Code v2.1.287 的版本發佈在第一條變更就寫著「Added Claude Mods：外掛從此可以修改更深層的行為」，且 Mod 功能預設開啟，無須翻任何實驗功能開關。

開始的方式有三條：用既有的（Claude Code 自己的某些功能就是 Mod，例如 /diff 指令的面板）、自己做（在對話裡描述需求，Claude 會載入內建的 plugin-authoring 技能替你寫）、安裝別人的（從市集或用指令裝）。第一次實作建議走「自己做」這條：目標選一個低風險、看得見的東西，工具計數器正是官方教學的起手式，計數掛在轉動圖示旁，做完立刻能驗證。整個過程不需要 Node.js、打包器或建置流程，因為 Claude Code 直接載入 .js 與 .ts 檔。還沒把 Claude Code 基本操作摸熟的讀者，先回Claude Code 上手指南把交辦與權限的概念補起來，這篇的討論假設你已經會啟動工作階段、輸入指令、看懂同意詢問。

Mod 的解剖：三個檔案，一個關鍵鍵值

名詞先對齊，後面的討論才不會打結。Mod 不是外掛體系之外的新物種，它就是外掛（plugin），只是多了一個特定檔案：hooks 目錄裡的 hooks.json 若含有一個 modules 鍵、指向你的程式檔，這個外掛就是 Mod。那個被指向的程式檔稱為 hooks module（事件處理模組），裡面匯出一個 register 函式，Claude Code 載入時會呼叫它一次，你則在函式裡用一連串的 on 呼叫，把每個事件繫結到對應的處理函式。對外掛體系還陌生的讀者，跟著下一段的結構說明走即可，外掛生態的全景會在後面的對照段補上。

一個最小的 Mod 只要三個檔案，官方教學用的是 first-mod 這個名字：

• .claude-plugin/plugin.json：外掛的清單檔（manifest），寫名稱、版本、描述與作者，這個範例裡沒有任何特殊欄位。
• hooks/hooks.json：裡面的 "modules": ["./register.js"] 指向你的程式碼。有沒有這個 modules 鍵，就是一個普通外掛與 Mod 的分界。
• hooks/register.js：你的程式碼本體。它註冊事件處理函式，決定 Mod 做什麼。

還有一個容易混淆的術語要先講：Claude Code 原本就有「掛鉤」（hooks）機制，那是寫在設定檔裡、以 shell 指令、HTTP 請求、prompt 或 agent 掛鉤回應事件的設定檔掛鉤；Mod 的處理函式也統稱 hook，但它是跑在 Claude Code 程式內部的函式。官方文件為了區分，把前者稱為 settings hook（設定檔掛鉤），把 Mod 的稱為 hook。兩者並存且不相斥，設定檔掛鉤沒有被淘汰，這點在組織管理的段落還會再出現。

你可能已經在用 Mod 而不自知。Claude Code 有幾個自家功能就是 Mod：/diff 指令的視覺化面板是 Mod，把 AGENTS.md 載入為專案指示的功能是 Mod。容易誤會的是 plugin-authoring：它也是內建項目，但本質是提供技能的外掛，負責把「教 Claude 寫外掛」的技能注入對話，本身不含 Mod 程式碼，並不是展示 Mod 事件能力的例子。還有一個預設停用、名為 you-should-know 的內建 Mod，會在較長任務進行時派一個側翼代理盯著你的背影，發現你可能漏看的事情就在輸入框上方提示你。在 /plugin 的 Installed 分頁可以看到這些內建項目；you-should-know 是否出現取決於你的組織與帳號，可用時會列在 Show disabled（顯示停用項目）清單裡，而不會直接出現在清單上。這個事實的意義在於：Mod 的能力等級是 Anthropic 自己也在用的等級，不是玩具介面。

Mod 能做什麼：五件其他機制做不到的事

設定檔掛鉤、技能（Skills）、狀態列、MCP 伺服器都在 Claude Code「外面」工作：它們執行一支腳本，或給 Claude 文字與工具。Mod 跑在 Claude Code 裡面，這個位置差異決定了它的五種獨門能力。

第一是畫出可互動的介面。官方介面繪製指南列出它能著手的繪製位置：對話紀錄旁的側邊面板、輸入框上方的資訊帶、快顯通知、對話紀錄裡的一行文字，面板裡可以有分頁、按鈕、文字輸入欄與下拉選單。第二是重繪 Claude Code 自己的介面：工具呼叫的顯示列、轉動圖示、Claude 發問的對話框，都能置換或加料。第三是踩進工具呼叫與請求：在工具執行前攔住它、向使用者提問後再決定放行與否、不執行工具直接代答、把某個請求改送到別的模型。第四是讓自訂指令直接跑你的程式碼：一個斜線指令立刻執行你的函式，不經過一輪 Claude 對話，Claude 忙碌中也能回應。第五是處理函式之間共享變數：一個函式記錄的數值，另一個函式可以直接拿去顯示，計數器正是靠這一條成立的。

介面背後是事件系統。官方事件指南把介入姿態分成三種：觀察（observe）做完自己的事後呼叫 next(e) 讓事件照原樣繼續；改寫（rewrite）把事件的副本改掉再傳下去，例如把送出的提示詞修剪空白；接管（answer）不呼叫 next、直接回傳結果，後續的處理鏈與 Claude Code 原本的行為都不會執行。多個 Mod 處理同一個事件時會串成中介軟體鏈，你的 next 其實是呼叫下一個 Mod 的處理函式，鏈的末端才是 Claude Code 自己的行為。註冊時可以用比對器（matcher）限定條件：比對值、陣列或正規表示式，例如只攔 Bash 工具、只攔名稱以某前綴開頭的 MCP 工具。

事件家族涵蓋整個工作階段。工具類有 tool.call（工具將被執行）、tool.check（Claude Code 正在決定准駁）、tool.describe（工具描述首次送出）。提示詞類有 prompt.submit（提示詞送出，可改文字、可加只有 Claude 讀得到的脈絡、可整個擋下）、prompt.section 與 prompt.context（系統提示與首則訊息的脈絡）。回合類有 turn.start、turn.step、turn.complete，其中 turn.step 能讀到每次請求的 token 用量、能把請求換模型送出。工作階段類有 session.start、session.end、session.compact 等。介面類以 ui.render 為核心，每次繪製位置要被畫出來時觸發。原生的設定檔掛鉤事件也各有對應：classic. 開頭加上事件名，例如 classic.Stop。想查自己版本的全部事件與欄位，官方參考手冊有完整表格。

把事件家族攤開後，幾個對知識工作者特別有價值的組合就浮出來了。其一是 prompt.submit 的脈絡注入：提示詞送出前，Mod 可以在不更動你打的字的情況下，附加只有 Claude 讀得到的背景資訊，官方例子是偵測到提示詞提到 PR 時自動附上目前的 Git 分支名，你看到的對話完全沒變，Claude 拿到的資訊卻更準。其二是 turn.step 的用量觀察：每次請求往模型送出時讀取快取讀取與寫入的 token 數，長任務跑完，對話紀錄裡就有一串淡字記錄每一輪的消耗，這比事後翻帳單更能定位「哪一輪開始變貴」。其三是 tool.check 的動態准駁：固定的准駁規則寫設定檔就好，但「只有在 main 分支上才擋 git push」這種取決於當下狀態的判斷，正是這個事件的舞臺。這三個組合都不必畫任何介面，卻已經是設定檔掛鉤做不太到的事。

上限也該一併知道，因為它們塑造了「好的 Mod」的形狀。一般處理函式對單一事件的執行時間限制是 10 秒，prompt.edit 更嚴，只有 50 毫秒，超時會被跳過；附掛的錯誤處理函式限 1 秒。Mod 透過介面呼叫跑程序，預設 30 秒逾時、最長可調到 10 分鐘；單檔讀寫上限 4 MiB；介面重繪有節流，一般每秒 10 次、終端機的可見面板可到 30 次，超出的呼叫會被合併，所以計數器這類高頻更新的設計不必擔心洗版，但也不該期待逐次動畫。這些數字告訴你 Mod 的定位是輕量、回應快的事件居民，不該拿來跑重運算。

五路對照：Mod、Skills、MCP、設定檔掛鉤、外掛容器

擴充方式一多，選擇就成了問題。我們站上的Claude Code 外掛實戰指南已經用「劇本、通道、容器」的比喻把 Skills、MCP、外掛三兄弟分清楚：Skill 是教 Claude 照固定步驟做事的劇本，MCP 是讓 Claude 碰得到外部資料的通道，外掛是把這些東西打包出貨的容器。Mod 加入後，這張地圖要多畫一層：Mod 是「住進 Claude Code 本體的程式」，而外掛容器照舊是載具，一個外掛可以同時裝著技能、MCP 連線與 Mod。

↔ 左右捲動檢視完整表格

擴充方式	本質	能畫介面嗎	典型情境
Mod	跑在 Claude Code 內部的事件處理函式	能	計數面板、工具呼叫守門、自訂狀態顯示
設定檔掛鉤	事件發生時執行的既有腳本或請求	不能	編輯後自動跑檢查、依規則擋下工具呼叫
Skill	一份 SKILL.md 指示文件	不能	每次都要照同一套格式整理報告
MCP 伺服器	提供外部系統工具連線的服務	不能	讀專案管理系統、資料庫或其他服務
外掛容器	把以上元件打包安裝與分享的單位	間接（裝了 Mod 就有）	讓團隊一次裝齊同一組擴充

我的建議順序是：需求能用 Skill 解就先寫 Skill（成本最低、可攜性最好），要碰外部資料就接 MCP，已經有現成腳本要掛上事件就用設定檔掛鉤，三者都涵蓋不了、而且需求真的落在「顯示」或「事件攔截」這兩層時，才輪到 Mod。判斷的試金石只有一問：這個需求是否需要「Claude Code 的畫面」或「事件處理鏈」？都不需要卻想寫 Mod，多半是被新名詞吸引，做出來的東西會比一個 Skill 更難維護。Skill 的完整教學看Claude Skills 指南，MCP 的底層邏輯看MCP 入門指南，這裡不重複。

升級路線通常有跡可循，認出那個瞬間再出手最省力。多數人是這樣走到 Mod 的：起先同一套指示天天貼，收斂成 Skill；後來需要後台數據，接了 MCP；再後來想在特定事件後自動跑腳本，掛上設定檔掛鉤。卡關的訊號有兩種：一種是「我想要它顯示某個數字，但它沒有地方可以顯示」，你需要的資訊其實都在，缺的是一塊介面；另一種是「我想要的判斷取決於事件當下的內容」，固定規則寫不出來，必須在事件流裡即時看、即時決定。這兩種訊號出現前的任何需求，用既有三件套處理都更快；出現後，計數器就是最好的第一課，因為它同時練到事件觀察、介面改寫與指令接管三種姿態，卻又不碰任何危險能力。

還有一個分工細節值得記住：在工具呼叫這條處理鏈上，設定檔掛鉤與 Mod 的處理函式會相遇（官方明確描述的是 PreToolUse 這個情境，其他事件的並存方式沒有同樣的保證，不要一體適用）。組織管理的設定檔掛鉤排在所有 Mod 之前，它擋下的東西是終局的；一般設定檔的 PreToolUse 掛鉤則排在這條鏈的後段，一個接管了工具呼叫的 Mod 可以讓它們根本不執行。換句話說，在公司環境裡，管理者的規則優先於你的 Mod；在個人環境裡，你的 Mod 優先於你自己的 PreToolUse 掛鉤。這個順序在排查「為什麼被擋」時非常有用。

實作四步：把工具計數器掛上轉動圖示

進入實作。目標沿用官方起手式：統計 Claude 使用工具的次數，把數字顯示在工作中的轉動圖示旁，並提供一個 /tally 指令隨時查閱。全程使用終端機裡的互動式 Claude Code；以斜線開頭的指令在 Claude Code 的輸入框裡打，其他指令在終端機打。跟著 官方建立教學的路線走，但每一步加上實務上該核對的點。

第一步：確認版本與練習環境

在終端機執行 claude --version，版本需為 2.1.287 以上。這個版本起 Mod 預設開啟，沒有額外的實驗開關要翻；早期嘗試階段使用的 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS 環境變數，在 2.1.287 之後一律被忽略，把它設為 0 並不會關掉 Mod，所以別再拿它判斷狀態。版本太舊就先更新 Claude Code。然後挑一個你信任的練習資料夾進去：第一次在某資料夾開啟工作階段時，Claude Code 會問你是否信任這個目錄，沒回答信任提示之前，任何 Mod 都不會載入，這是入門最常見的第一顆雷。

第二步：用自然語言描述你要的 Mod

在 Claude Code 對話框裡，用你自己的話描述需求。Claude 會自動載入內建的 plugin-authoring 技能來寫 Mod，也可以自己先執行 /plugin-authoring 把技能叫出來。描述的品質決定來回次數，我的提示詞模板把握四個元素：功能（計算工具呼叫次數並顯示在轉動圖示旁）、查詢方式（提供 /tally 指令）、邊界（只計數與顯示，不讀額外檔案、不連網、不呼叫模型）、交付要求（先說明會建立哪些檔案、怎麼確認生效）。

Claude 會把檔案寫進該次工作階段專屬的 Mod 資料夾：~/.claude/dev-mods/ 底下、以工作階段 ID 命名的子資料夾。因為 ~/.claude 是保護路徑，在 default 與 acceptEdits 權限模式下，每個檔案的建立都會跳出同意詢問，逐一核准即可。這裡有個容易被忽略的誠實點：提示詞裡寫的限制，約束的是 Mod 自己的行為；Claude 建立程式的過程仍可能需要讀開發說明或建立檔案，它提出的每個操作你還是要看。寫完後請它攤開三個檔案的內容，對照前面講的結構：plugin.json 是清單、hooks.json 的 modules 指向程式碼、register.js 註冊事件。官方範例的 register.js 註冊四個處理函式，值得逐個看懂。

↔ 左右捲動檢視完整表格

事件	觸發時機	做的事情
session.start	工作階段開始、Mod（重新）載入時	註冊 /tally 指令
tool.call	Claude 即將使用某個工具	計數加一，要求介面重繪
command.run	你輸入 /tally 時（比對器限定）	回傳要印出的計數文字
ui.render	轉動圖示被繪製時（比對器限定 Spinner 元件）	在原字樣後面加上計數

四個函式共用檔案頂端的一個 calls 變數：tool.call 負責加一，ui.render 負責顯示，這就是「處理函式共享變數」最具體的示範。兩個函式的介入姿態也不同：tool.call 與 session.start 是觀察，做完事呼叫 next 讓一切照舊；command.run 是接管，直接回傳文字、不往下傳；ui.render 是改寫，把帶著計數的副本傳下去，Claude Code 畫出來的還是它自己的轉動圖示，只是多了你的後綴。

第三步：核對熱重載的同意選項

Claude 存下第一個檔案時，Claude Code 會問你要不要為這個工作階段開啟熱重載。選 Enable for this session，這次對話產生的 Mod 會在回合結束時載入，之後每次有修改的回合結束時重新載入；選 Not now 則暫不載入，檔案留著，下次這個工作階段啟動時才載入。這個同意的本質是「同意讓 Claude 寫的程式碼在你的 Claude Code 裡執行」，所以如果還沒看懂它要做什麼，就先別開。開啟後留意兩個行為：回合結束才載入，所以對話進行中不會立刻生效；重新載入時 register 會再跑一次，檔案頂端的變數會歸零重算。

第四步：驗收，三個條件都過才算數

驗收要有客觀條件，我的標準三條：載入了、數字會動、查詢有回應。先輸入 /plugin 切到 Installed 分頁，確認新 Mod 列在其中；分頁下方有一行淡字列出作用中的 Mod 數量與名稱，沒被點名就是沒載入，直接跳排查段。然後請 Claude 做一件需要幾次工具呼叫的事，例如「列出這個資料夾的檔案，讀一下 README」：它工作時，轉動圖示的字樣後面應該出現遞增的計數，官方示範影片裡的樣子是隨著列目錄與讀檔從 1 數到 3。結束後輸入 /tally，對話紀錄會印出該 Mod 名稱開頭的計數句子。不想開互動式工作階段也能驗：終端機執行 claude -p "/tally" --plugin-dir ./first-mod，非互動模式會直接印出計數回覆。

驗收之外再補一道程式碼層的查核：終端機執行 claude plugin validate ./first-mod。它不執行你的程式，只做靜態檢查，輸出的 hooks: 行列出你處理的事件（含比對器條件），calls: 行列出程式呼叫的每個介面方法。若你以為有處理某事件卻沒出現在 hooks: 行，通常是事件名稱拼錯，指令會直接報「某某不是事件」。這個輸出還有第三方查核的用途，安全段落會再回來用它。

想把驗收再往前推一步，可以替 Mod 寫自動化測試：官方提供 claude plugin test，不開工作階段、不登入、不連網，直接對你的處理函式發射事件、假造 Claude Code 的回答、檢查回傳。以計數器為例，測試檔先代答兩次工具呼叫（所以沒有真的工具會跑），再執行 /tally，斷言回覆文字裡的數字是 2。單一測試有 5 秒上限。第一次實作不強求寫測試，但只要 Mod 開始進入你的日常流程，測試就是把「改一處壞一處」的焦慮換成綠燈紅燈的最短路徑，尤其熱重載會重置變數這類行為，用測試釘住比用記憶體記住可靠。

驗收段落還有兩個小而實用的規則值得記下。命名有硬性限制：指令、工具、子代理與面板的名稱只能用字母、數字、底線與連字號，最長 64 個字元，取了中文名稱會直接失敗。發佈到市集前，外掛名稱不能長得像 Anthropic 自家產品，以 claude- 開頭的名字會被驗證指令擋下，這是官方防止仿冒的底線。

計數器本身也該被正確理解。工具呼叫次數只代表呼叫發生了幾次：不同工具的成本不同，一次複雜的搜尋與一次輕量的讀檔都算一次，它既不是完成度的百分比，也不能直接換算費用。把它當「Claude 現在還在動、而且動了多少次」的觀察起點是恰當的，要估算成本得另行取得 token 用量，那是 turn.step 事件的領域。

生命週期：從一次練習變成長期資產

Claude 在對話中替你寫的 Mod，預設只在產生它的那個工作階段載入，而且那個工作階段的 Mod 資料夾會在超過保留天數後被清理（預設由 cleanupPeriodDays 設定控制）。想把一次練習留下來，把該 Mod 的資料夾整個複製到自己管理的地方，例如 ~/mods/git-branch 這類位置，之後有兩種載入法：臨時用，在終端機以 claude --plugin-dir ~/mods/你的mod 啟動，這個旗標會為單一工作階段載入資料夾，不安裝；長期用或給別人用，把它放進市集讓人安裝，或直接把資料夾壓縮成 zip 寄給少數同事，組織則能透過管理設定統一部署。

開發期有兩個反直覺的行為要先知道。其一，安裝版的外掛以版本為單位快取，你直接改安裝副本的檔案，修改不會生效，版本號沒遞增、沒重新安裝就看不到變化；持續開發一律對著工作資料夾用 --plugin-dir，它在存檔時熱重載，而且 Claude Code 會把該資料夾視為保護路徑，Claude 的每次修改都會先問你。其二，熱重載會重置模組層級的變數，register 重跑、計數歸零；想讓數值活過重載，官方提供 $.state 與 $.store 兩個存放機制。工作階段指令也有類似的坑：/clear、/resume、/branch 之後 $.state 會回到預設值，而且 session.start 不會再觸發，需要 persistence 的功能要在對應事件重新載入。

載入管道也有幾個環境變數等級的細節。--plugin-dir 是指令列旗標，有些入口沒地方傳旗標，這時改用環境變數 CLAUDE_CODE_PLUGIN_DIRS 指定資料夾清單，效果等同逐一直接載入；長時間跑的非互動工作階段預設不會監看檔案變化，把 CLAUDE_CODE_PLUGIN_DIR_WATCH 設為 1 才會存檔即重載，背景服務想邊改邊跑時記得打開。這些屬於進階配置，第一次實作用不到，但當你把 Mod 從手動開來玩推進到掛在常駐流程裡，它們就會派上用場。

想看別人怎麼寫，Anthropic 在 claude-code-playground 儲存庫的 範例 Mod 專區放了三個完整樣品：token-weather 在輸入框上方畫出 context 視窗的天氣預報圖、blast-radius 攔住危險的 shell 指令並顯示它會改動什麼再讓你按鈕決定、replay-theater 加了一個 /replay 指令逐步重播 Claude 上一回合的檔案編輯。官方明言這些範例按現狀分享、不提供支援，但它們是學習「介面、攔截、指令」三種路數的最佳起點。同時，每次以 --plugin-dir 載入或重載時，Claude Code 會在 Mod 資料夾的 .claude-plugin/types/ 底下生成 TypeScript 型別宣告檔，描述你這個版本的所有事件與方法，官方甚至建議：型別檔與文件不一致時，信型別檔。

沒反應怎麼辦：三層排查法

Mod 壞掉的樣子很有欺騙性：模組或某個處理函式出錯時，Claude Code 會跳過它、讓工作階段照常繼續，一個壞掉的 Mod 看起來就像一個沒反應的 Mod。官方排錯指南的資訊很完整，我把它整理成由外到內的三層。

第一層：載入了嗎

先跑 /plugin 看 Installed 分頁與作用中清單。沒列名，依序檢查版本是否 2.1.287 以上、資料夾信任提示是否答過、是否用了 --safe-mode 或 --bare 啟動、設定檔是否設了 disableAllHooks、組織政策是否限制載入。要進一步看原因，用 claude --debug（或 --debug-file 指定路徑）啟動，在除錯日誌裡過濾你的 Mod 名稱，拒載的原因會寫在「hooks module 未載入：」之後；以 --plugin-dir 載入的 Mod 在日誌裡會冠上 @inline 後綴。還有一個不用安裝任何東西的環境探測法：在一個沒有 Mod 的資料夾跑 claude plugin test，訊息說「no hooks module to load」代表環境允許載入，說「hooks modules are turned off」代表設定或組織政策擋住了你。

把第一層的常見症狀與第一個該做的動作整理成表，省下亂試的時間：

↔ 左右捲動檢視完整表格

症狀	第一個動作	常見原因
/plugin 清單裡完全沒有它	claude --version 對版本	版本低於 2.1.287
清單有、淡字行沒點名	claude --debug 看拒載原因	disableAllHooks、--bare、組織政策、同名外掛先載
第一次開某資料夾就沒反應	互動式啟動並回答信任提示	信任提示未回答，任何 Mod 都不載入
驗證通過卻列不出 hooks 行	檢查 hooks.json 的 modules 鍵	鍵名拼錯或整個漏掉
claude -p 印出未載入訊息	讀冒號後的拒載原因	非互動環境沒人能核准熱重載同意

第二層：是不是期待錯了畫面

Mod 的兩種能力在不同執行環境的支援度不同：事件處理函式在每種會載入外掛的環境都會跑，繪製只有終端機與桌面 App 顯示。這張矩陣是排查「功能好像沒反應」的關鍵，因為最常見的誤診就在這裡：VS Code 擴充功能裡 Mod 是活著的，只是畫不出面板。

↔ 左右捲動檢視完整表格

執行環境	事件處理函式	Mod 畫的介面
終端機（含編輯器內建終端機與 JetBrains 外掛）	執行	顯示
桌面 App 的 Code 分頁（WSL 工作階段除外）	執行	顯示，部分元件僅限終端機
桌面 App 的 WSL 工作階段	不執行（不支援外掛）	不顯示
VS Code 擴充功能的聊天面板	執行	不顯示
claude -p 與 Agent SDK	執行	不顯示
雲端工作階段	視外掛是否跟進雲端	不顯示

所以同一個計數器 Mod，在終端機裡看得到轉動圖示旁的數字，在 VS Code 聊天面板裡只剩 /tally 的文字回應能驗證，在桌面 App 的 WSL 工作階段裡則整個不存在。桌面 App 的定位與邊界，可以搭配Claude Desktop 指南的討論對照著看。會被多環境使用的 Mod，官方建議在程式裡檢查自己跑在哪個 App，遇到畫不出介面的環境就換一條出路：在對話紀錄加一行淡字，或讓指令以文字回覆，功能不至於整段消失。

第三層：處理函式本身出錯了嗎

載入了、環境也對，就往程式碼裡看。丟出例外、超過時間限制（一般處理函式 10 秒、prompt.edit 只有 50 毫秒）、回傳形狀不對，都會被跳過並在日誌留一行「hook skipped」與原因，同一事件同一種失敗只記一次，直到 Mod 重新載入。畫介面的樹狀結構沒通過驗證是另一種看起來安靜的失敗：使用者畫面上像沒反應，面板空著或顯示 Claude Code 原本的內容，但 transcript 與除錯日誌會留下 ui.render refused 的拒絕訊息與具體原因，例如某個排版屬性不在允許清單。最嚴重的是把共用的 hooks worker 執行緒弄掛：一個永不等待的無窮迴圈之類的阻塞寫法會讓 Claude Code 把該 Mod 卸載，worker 連續掛三次時所有非內建 Mod 都會被卸載，這時跑 /reload-plugins 可以重新載入。實務上最有效的一招是把錯誤訊息原文貼回對話，讓 Claude 讀著修，比反覆重裝有方向得多。

安裝別人的 Mod 前：三道查核

自己寫的 Mod 你看得懂，別人寫的就要靠查核。核心事實先記住：Mod 以你的使用者權限執行，而且沒有沙箱隔離。就算你開了 Claude Code 的沙箱功能，沙箱隔離的是 Claude 跑的 Bash 指令，Mod 自己啟動的行程不在隔離範圍內。載入之後它能做什麼？官方組織管理文件列得很白：以你的身分讀寫你碰得到的任何檔案、啟動程式、發網路請求；讀環境變數與設定檔裡的金鑰；看見你送出的每個提示詞與每個工具呼叫；改寫提示詞或工具呼叫、冒你之名送出提示詞、傳訊息給你的其他工作階段；在你被詢問之前先核准工具呼叫；用你的方案或 API 金鑰呼叫模型、消耗額度。一個看起來只是小面板的 Mod，背後能做的事遠超過畫圖。

第一道查核是靜態檢視。拿到第三方 Mod 的檔案後，先 claude plugin validate 它的資料夾：hooks: 行列出它處理哪些事件，calls: 行列出它要求哪些能力（讀檔、連網、呼叫模型都在這裡現形），讀寫環境變數或存取狀態的還會有額外的行。這個檢查不執行程式，所以安全；但它也只是檢查，不是認證，作者可不可信、功能是否真的需要這些能力，仍然要你判斷。對照判斷法很樸素：一個只顯示工具次數的小功能，若要求讀金鑰或把資料送往陌生網址，就值得停下來問原因。

第二道查核是權限互動的敏感性。Mod 改不了權限詢問框的顯示（它無法偽裝 Claude 問你的話），但 tool.check 事件的處理函式可以在詢問出現前代你核准，這表示「都會跳同意框」的直覺在 Mod 面前不成立。組織環境有內建的防護 Mod（sec-default）在前把關：在有管理設定的機器上，或使用者以 Team 或 Enterprise 方案登入時，它排在所有使用者安裝的 Mod 之前，使用者 Mod 預設不能核准被 deny 規則拒絕的工具呼叫；這道防線有一個管理端的例外，若管理者把防護選項 allowModsToOverrideDenyRules 設為 true，使用者 Mod 就能推翻 deny 規則的否決。但要注意 deny 規則管不到 Mod 自己的檔案與行程呼叫，即使你拒絕了某個讀檔權限，Mod 仍可用自己的管道讀那個檔；真正把關的手段是別讓可疑的 Mod 載入，或用政策 Mod 攔截。

組織面的控制項值得一張清單，因為它們決定「你的機器上 Mod 到底能活成什麼樣子」。網路政策管得到 Mod 透過介面發的 HTTP 請求，組織關掉網頁抓取或非必要流量時，這類請求會被拒；但 Mod 自己啟動的程序帶著你的網路權限出門，政策攔不到，這也是靜態查核裡 calls: 行要逐條看的原因。另一個容易被忽略的訊號是「本程序已關閉安裝版 Mod」：除錯訊息出現這句時，代表 Anthropic 從遠端暫時停用了安裝型 Mod，你本機的任何設定都救不回來，這不是你的環境壞了。管理者若要封鎖來路不明的 Mod，開關叫 allowManagedModsOnly，但它不是設定檔裡的頂層鍵，照直覽寫進 settings.json 不會有任何作用：它是內建防護外掛 cc-plugin-sec-default@builtin 的一個選項，必須放在唯讀的管理設定（managed settings）裡、掛在 pluginConfigs 底下才生效，使用者、專案或 --settings 傳入的設定檔都既設不了也放不掉它：

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  }
}

打開之後，被擋的只有使用者自己安裝的 Mod：組織自己部署的 Mod 與內建 Mod 照常運作（內建項目各有獨立開關），使用者的設定檔掛鉤也不受影響；換句話說這個開關砍的是「不明的程式碼」，不是自動化本身。

第三道查核是退出機制。裝了才發現不對勁，關掉的方法按範圍選：停用單一 Mod，在 /plugin 的 Installed 分頁處理；整個工作階段停用所有自訂，用 --safe-mode 啟動（它連你其他客製化也一併停掉，適合歸因測試）；永久停用你安裝的所有 Mod，在 ~/.claude/settings.json 設 disableAllHooks 為 true，注意這也會停掉你的設定檔掛鉤與自訂狀態列。管理者則可在管理設定打開 allowManagedModsOnly，只允許組織部署的 Mod。把「知道怎麼關」當成安裝前的前置知識，是對無沙箱世界最基本的敬意。

收尾判斷：誰該現在學，誰該再等

我的立場直接講：每天在終端機用 Claude Code 超過一小時、而且曾經因為「看不到它現在到底做到哪、用了多少」而困擾的人，值得現在就做一個計數器，一小時內你會對整個事件模型有體感；只是聽到新名詞想跟風、連 Skill 都還沒寫過的人，先回去把 Skill 與設定檔掛鉤用熟，Mod 的學習曲線對你沒有急迫性。Mod 的甜蜜點很明確：它是唯一能觸碰介面與事件鏈的機制，你的痛點若不在這兩處，它就只是比較難維護的 Skill。

時效面上要有正確認知。這套事件與方法仍在快速演進，官方明說事件與方法會隨版本變動、要以生成在你機器上的型別宣告檔為準，連官方文件都自認可能落後。所以這篇刻意把力氣花在變動慢的東西：三檔結構、介入姿態、驗收方法、排查層次，這些骨架在 API 微調時依然成立。跟著任何教學（包括這篇）做之前，都先跑一次 claude --version，對齊版本再動手。

行動清單給準備好的人，照序執行：

• 終端機跑 claude --version，不足 2.1.287 先更新；清掉殘留的 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS。
• 開一個信任的練習資料夾，用四元素模板（功能、查詢方式、邊界、交付要求）描述計數器需求。
• 逐檔核准、開啟 Enable for this session，回合結束後用 /plugin 的 Installed 分頁確認載入。
• 讓 Claude 列檔案讀 README，看轉動圖示旁的計數遞增，輸入 /tally 比對數字。
• 跑 claude plugin validate，把 hooks: 與 calls: 行讀懂，核對它只用你預期中的能力。
• 滿意的話把資料夾複製出 dev-mods，用 --plugin-dir 長期開發；要分享就進市集。
• 之後每次安裝別人的 Mod，先 validate 再說，並在心裡備好停用路徑。

從一個看得見的小功能開始，看得懂它做什麼、驗得出它對不對、關得掉它出錯的樣子，這三件事做到，你就已經站在 Mod 的正確起點上了。