> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 排除 mod 的故障

> 找出 Claude Code mod 為什麼沒有作用：將症狀或訊息與其原因相符，查詢拒絕訊息，並閱讀偵錯日誌。

當 mod 的模組或其中一個 hook 失敗時，Claude Code 會跳過它，工作階段會繼續進行，因此損壞的 mod 看起來可能像沒有作用的 mod。首先檢查 Claude Code 從您的 mod 讀取了什麼，以及它在哪裡報告問題，然後找到您遇到的症狀或訊息。

<h2 id="find-out-why-a-mod-does-nothing">
  找出 mod 為什麼沒有作用
</h2>

當 mod 沒有作用時，請檢查 Claude Code 從 mod 的檔案讀取的內容，以及它在跳過某些內容時寫入的那一行。對於第一項，在您的 shell 中執行 [`claude plugin validate`](/docs/zh-TW/plugins/mods/create#check-what-claude-code-reads-from-your-mod)，並使用 mod 的目錄，例如 `claude plugin validate ./first-mod`。它會捕捉拼寫錯誤的事件、不良的資訊清單和 Claude Code 無法讀取的模組，而無需啟動工作階段。

當模組未載入、hook 被跳過或另一個 mod 拒絕您的 mod 時，Claude Code 會寫入一行，其中命名您的 mod。您讀取該行的位置取決於工作階段：

* **熱重新載入 plugin 目錄的工作階段**：文字記錄中的暗淡行。這是您使用 `--plugin-dir` 啟動的互動式工作階段，或您[為 Claude 編寫的 mod 啟用熱重新載入](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)的工作階段。
* **任何其他互動式工作階段，例如執行您從市場安裝的 mod 的工作階段**：[偵錯日誌](#read-the-debug-log)只有。若要取得一個，請使用 `claude --debug` 啟動工作階段。
* **`claude -p` 執行 `--plugin-dir`**：stderr，採用預設文字輸出格式。另一個 mod 的拒絕只會進入偵錯日誌。

<h2 id="check-whether-mods-can-load">
  檢查 mod 是否可以載入
</h2>

若要檢查您的設定是否允許 mod 載入，而無需安裝一個，請在您的 shell 中執行 `claude plugin test`，從不包含 mod 的目錄執行。您不需要工作階段。它列印的訊息會告訴您狀態：

| 訊息包含 | 這表示什麼 |
| :- | :- |
| `no hooks module to load` | Mod 可以載入。該命令在此目錄中找不到要測試的 mod。 |
| `hooks modules are turned off here` | 設定正在阻止您的 mod：您自己設定中的 `disableAllHooks`，或您的組織的原則 |
| `hooks modules are turned off in this process: the rollout switch served off` | Anthropic 已遠端關閉已安裝的 mod。 |
| `hooks modules are turned off in this process: the rollout switch was saved off by an earlier session` | 該命令使用了先前工作階段儲存的值，該值可能已過時。請啟動 `claude` 一次以重新整理它，然後再次執行該命令。 |

組織也可以設定 `allowManagedModsOnly` 以僅允許其自己的 mod，此命令不會報告。在這種情況下，Claude Code 會拒絕您安裝的 mod，並且[訊息會說明原因](/docs/zh-TW/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。

<h2 id="the-mod-doesn’t-load">
  mod 不載入
</h2>

mod 新增的任何內容都不會出現：沒有命令、沒有繪圖，也沒有行為變化。

<h3 id="your-version-is-too-old">
  您的版本太舊
</h3>

請參閱[應使用哪個版本以及如何檢查您的版本](/docs/zh-TW/plugins/mods/overview#turn-mods-on-or-off)。

<h3 id="the-mods-active-line-doesn’t-name-the-mod">
  `mods active` 行不命名 mod
</h3>

mod 新增的任何內容都不會出現，並且 `/plugin` 中的 [`mods active` 行](/docs/zh-TW/plugins/mods/overview#see-which-mods-a-session-loaded)不命名它。hooks 模組未載入。當 Claude Code 拒絕它時，偵錯日誌有一行以 `hooks module`、mod 的名稱和 `not loaded:` 開頭，例如 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`，用於使用 `--plugin-dir` 載入的 mod。

讀取冒號後的原因。[拒絕訊息](#refusal-messages)部分列出每一個。如果日誌沒有這樣的行，請逐一檢查此群組中的其他項目。

部分設定會停用 mod，但讓其外掛的其餘部分繼續運作。[開啟或關閉 mod](/docs/zh-TW/plugins/mods/overview#turn-mods-on-or-off) 列出了這些設定。

<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">
  `claude -p` 執行列印 `hooks module not loaded`
</h3>

該行以 mod 的名稱開頭，並進入 stderr。hooks 模組被拒絕。非互動式執行沒有文字記錄，因此訊息進入 stderr。

讀取冒號後的原因。[拒絕訊息](#refusal-messages)部分列出每一個。

<h3 id="refusal-messages">
  拒絕訊息
</h3>

每一個都遵循偵錯日誌中的 `hooks module`、mod 的名稱和 `not loaded:`。

| 訊息開頭為 | 這表示什麼 |
| :- | :- |
| `hooks modules are turned off for installed plugins in this process: the rollout switch served off` | Anthropic 已遠端關閉已安裝的 mod。 |
| `hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session` | 該工作階段使用了先前工作階段儲存的值，該值可能已過時。請重新啟動 Claude Code 以重新整理它。 |
| `disableAllHooks in managed settings` | 您的組織關閉了已安裝 plugin 的 hooks |
| `only managed plugins and built-in plugins run` | 設定了 `allowManagedHooksOnly`，或在受管設定以外的設定檔中設定了 `disableAllHooks` |
| `installed plugins that are not managed load no hooks module in this mode (--bare)` | 您使用 `--bare` 啟動了 Claude Code |
| `another plugin of that name loads first` | 另一個已啟用的外掛與您的 mod 同名，並[佔有該名稱](/docs/zh-TW/plugins/loading#hooks-when-two-enabled-plugins-share-a-name)，因此您的 hook 模組不會載入 |

<h3 id="messages-from-the-built-in-guard">
  來自內建防護的訊息
</h3>

在具有受管設定的機器上，或對於使用 Team 或 Enterprise 方案登入的使用者，[內建防護](/docs/zh-TW/plugins/mods/admin#know-what-happens-by-default)可以拒絕 mod 或其中一個答案。每條訊息都命名您的組織管理員設定以變更規則的選項。

| 訊息包含 | 這表示什麼 | 它出現在哪裡 |
| :- | :- | :- |
| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 您的組織僅允許[其自己的 mod](/docs/zh-TW/plugins/mods/admin#install-your-organizations-mods)，因此您的 mod 被拒絕 | 偵錯日誌，以及[熱重新載入外掛目錄的工作階段](#find-out-why-a-mod-does-nothing)中的逐字稿 |
| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-TW/plugins/mods/reference#tools) hook 批准了 `deny` 規則拒絕的呼叫。呼叫保持被拒絕。 | 文字記錄和偵錯日誌，每個工作階段中的每個 mod 一次。在 `claude -p` 執行中，僅偵錯日誌。 |
| `the deny rules in your settings could not be checked for this call, so it is refused` | 防護在檢查 mod 批准的呼叫時失敗，因此它拒絕了呼叫 | Claude 為被拒絕的呼叫讀取的原因 |

<h3 id="validate-passes-and-lists-no-hooks-line">
  `validate` 通過且不列出 `hooks` 行
</h3>

`hooks/hooks.json` 沒有 `modules` 鍵，或鍵拼寫錯誤。

新增 `"modules": ["./register.js"]`。

<h3 id="hooks-module-did-not-load">
  `hooks module did not load`
</h3>

該行以 mod 的名稱開頭，然後是 `hooks module did not load:` 和一個原因，當問題在您的程式碼中時，該原因會給出檔案和行。Claude Code 無法載入模組，例如因為其頂級程式碼拋出。

修復原因命名的錯誤。

<h3 id="options-do-not-fit-plugin-json-userconfig">
  `options do not fit plugin.json userConfig`
</h3>

該行以 mod 的名稱開頭，然後是 `hooks module did not load: options do not fit plugin.json userConfig:` 和一個原因。選項未通過其 [`userConfig`](/docs/zh-TW/plugins/components#user-configuration) 欄位的驗證，例如高於欄位 `max` 的數字，或必填欄位沒有值。

設定或變更值。該行的末尾命名其在 `settings.json` 中的 `pluginConfigs` 項目。

<h3 id="code-nested-too-deep-to-scan-more-than-2000-scopes">
  `code nested too deep to scan: more than 2000 scopes`
</h3>

該行以 mod 的名稱開頭，然後是 `hooks module did not load:`、檔案，以及 `code nested too deep to scan: more than 2000 scopes`。hook 模組中的檔案不能將作用域（例如函式、區塊和迴圈）巢狀超過 [2,000 層](/docs/zh-TW/plugins/mods/reference#limits)。[`claude plugin validate`](/docs/zh-TW/plugins/mods/create#check-what-claude-code-reads-from-your-mod) 會回報相同的原因。

重寫程式碼，以減少其作用域的巢狀深度。

<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">
  沒有 mod 在您首次開啟的目錄中載入
</h3>

您尚未回答該目錄的信任提示。

使用 `claude` 在該目錄中啟動互動式工作階段，並接受它開啟的信任提示。

<h3 id="no-installed-plugin-loads-at-all">
  沒有已安裝的 plugin 載入
</h3>

您使用 `--safe-mode` 啟動了 Claude Code。

啟動時不使用該旗標。

<h3 id="claude-code-stops-asking-to-enable-hot-reloading">
  Claude Code 不再詢問是否啟用熱重新載入
</h3>

Claude 在互動式工作階段中撰寫 mod，但沒有任何內容載入，而且 Claude Code 不再詢問[是否啟用熱重新載入](/docs/zh-TW/plugins/mods/create#ask-claude-for-a-mod)。如果該問題有三次在未選擇答案的情況下結束，熱重新載入會保持關閉。例如，當您設定了 [`askUserQuestionTimeout`](/docs/zh-TW/settings-reference#askuserquestiontimeout)，且在您回答之前時間已到，問題就會以這種方式結束。該設定在此適用，是因為 Claude Code 是在[與 `AskUserQuestion` 相同的問題對話框](/docs/zh-TW/tools-reference#question-auto-continue-timeout)中詢問。您自行關閉的問題不計入這三次。

若要執行該 mod，請[將其目錄從 mods 資料夾複製出來](/docs/zh-TW/plugins/mods/create#use-the-mod-in-other-sessions)，然後在 shell 中使用 `--plugin-dir` 啟動新的工作階段，例如 `claude --plugin-dir ~/mods/git-branch`。

<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">
  hook 被跳過或 mod 被卸載
</h2>

mod 已載入，然後 Claude Code 跳過了其中一個 hook 或卸載了它。

<h3 id="hook-skipped">
  `hook skipped`
</h3>

該行命名 mod 和事件，然後說 `hook skipped:` 和一個原因，例如 `first-mod: tool.call hook skipped: threw Error: boom`。hook 拋出、執行超過其[時間限制](/docs/zh-TW/plugins/mods/reference#limits)，或返回了錯誤形狀的結果。該行針對每個事件和失敗類型出現一次，直到 mod 重新載入。

修復錯誤。偵錯日誌對每次發生都有一行。

<h3 id="no-command-run-hook-answered-it">
  `no command.run hook answered it`
</h3>

您執行 mod 新增的命令，回覆命名 mod 和命令，例如 `first-mod registered /tally but no command.run hook answered it`，然後告訴您新增 hook。Claude Code 在命令到達鏈的末端且沒有答案時列印該回覆，這在兩種情況下發生：

* **沒有 hook 回答命令**：模組沒有 `command.run` hook、hook 的[篩選器](/docs/zh-TW/plugins/mods/events#filter-which-events-a-hook-handles)命名不同的命令，或 hook 返回 `next(e)`
* **Claude Code 跳過了 hook**：[`hook skipped`](#hook-skipped) 列出了原因。將 `focus: false` 傳遞給 [`$.ui.open`](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time) 是到達那裡的一種方式。

如果模組已經有回覆描述的 hook，請尋找命名 `command.run` 的 `hook skipped` 行，它會給出原因。執行命令的[測試](/docs/zh-TW/plugins/mods/test)會因相同原因失敗。

<h3 id="it-crashed-the-hooks-worker">
  `it crashed the hooks worker`
</h3>

該行以 mod 的名稱開頭，例如 `first-mod was unloaded: it crashed the hooks worker`。已安裝的 mod 共享一個工作執行緒。工作執行緒停止回應或崩潰，Claude Code 將其追蹤到此 mod 並卸載了它。阻止執行緒的 hook（例如永不等待的迴圈）是一個原因。

修復 hook。

<h3 id="its-session-start-ran-again-in-a-fresh-copy">
  `its session.start ran again in a fresh copy`
</h3>

該行以 mod 的名稱開頭，並命名一個 `$.prompt.submit`、`$.command.run` 或 `$.agent.spawn` 呼叫，例如 `first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again`。Claude Code 再次載入了 mod 的模組，例如在 hook 工作執行緒崩潰並被取代之後，而新副本的 [`session.start`](/docs/zh-TW/plugins/mods/reference#session) hook 執行了。該行命名的呼叫以其第一次執行的結果解析，而不是再次執行，因此您的 mod 不會重複提交提示詞、執行命令或啟動 subagent。hook 的其餘部分照常執行。

無需修復任何內容。

在 v2.1.292 之前，該呼叫會執行第二次，因此提示詞會被提交兩次、命令會被執行兩次，或 subagent 會被啟動兩次。

<h3 id="$-agent-register-refused-the-hooks-module-that-made-the-call-is-no-longer-loaded">
  `$.agent.register refused: the hooks module that made the call is no longer loaded`
</h3>

該行以您的 mod 名稱開頭，例如 `first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed)`，且該 agent 不會被註冊。您的 mod 在此呼叫之前已被重新載入或卸載。重新載入會載入 hook 模組的新副本，而此呼叫來自仍在舊副本中執行的程式碼，例如尚未返回的 hook。

如果該 hook 未捕捉此拒絕，它會失敗，Claude Code 會[跳過它](#hook-skipped)。若要讓保持載入的副本註冊該 agent，請在您的 [`session.start`](/docs/zh-TW/plugins/mods/reference#session) hook 中進行呼叫，該 hook 會在重新載入後於每個新副本中再次執行。

<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">
  `mods that run in the hooks worker are off for this session`
</h3>

該行讀取 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`。工作執行緒停止了三次，Claude Code 無法將停止追蹤到一個 mod，因此它卸載了每個不是內建的 mod，包括您的組織安裝的 mod。此行到達每個互動式工作階段中的文字記錄。

執行 `/reload-plugins` 以再次載入它們。

<h2 id="a-tool-call-is-denied">
  工具呼叫被拒絕
</h2>

mod 已載入，其 hook 執行，它接觸的工具呼叫被拒絕。

<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">
  `a hook changed this call's input after the model wrote it`
</h3>

在自動模式中，被拒絕的工具呼叫會給出此原因。hook 在[伺服器端分類器](/docs/zh-TW/permission-modes#server-side-classifier-review)檢查後變更了工具呼叫的輸入，因此該檢查不涵蓋將執行的內容。hook 可以是 mod 的 [`tool.call`](/docs/zh-TW/plugins/mods/reference#tools) 或 [`turn.step`](/docs/zh-TW/plugins/mods/reference#turns) hook，或 [`PreToolUse`](/docs/zh-TW/hooks#pretooluse) 設定 hook。訊息不會說明是哪一個。

訊息告訴 Claude 再次發出記錄的呼叫。如果也被拒絕，hook 每次都會變更輸入，因此關閉 mod 或 hook，或離開自動模式並自己批准呼叫。

<h3 id="a-message-about-the-deny-rules-in-your-settings">
  關於您設定中的拒絕規則的訊息
</h3>

`tried to lift a deny rule in your settings` 和 `the deny rules in your settings could not be checked for this call, so it is refused` 都來自內建防護。

在[來自內建防護的訊息](#messages-from-the-built-in-guard)中查詢它們。

<h2 id="a-drawing-doesn’t-appear-or-respond">
  繪圖不出現或不回應
</h2>

mod 已載入，其窗格、帶狀、toast 或控制項的行為不符合您的預期。

<h3 id="another-mods-band-shows-and-yours-doesnt">
  顯示的是另一個 mod 的帶狀，而不是您的
</h3>

提示詞上方只有一個帶狀，所有 mod 共用。在[您的 mod 之前](/docs/zh-TW/plugins/mods/events#the-order-mods-run-in)執行的 mod，若返回的樹中不包含 `next(e)` 的結果，就會取代您的帶狀。若要同時顯示兩個帶狀，請修改該 mod 的 hook，或請其作者修改：

* **保留其後的帶狀**：將 `await next(e)` 的結果放在其樹中某個 `Box` 的子元素之間，如[選擇繪製位置](/docs/zh-TW/plugins/mods/interface#pick-where-to-draw)中「提示詞上方的帶狀」分頁所示
* **保持樹有效**：不要為該 `Box` 或其外圍的任何 `Box` 指定 `width`、`height`、`minWidth`、`minHeight`、`position`、`top`、`left`、`right`、`bottom`、`display` 或 `overflow` prop

若要找出該 mod，請[寫入偵錯日誌](#read-the-debug-log)，並在其中搜尋 `answered ui.render without next()`。像 `other-mod (user) answered ui.render without next()` 這樣的行會指出某個未呼叫 `next(e)` 就返回其樹的 mod。該行不會指出[轉譯位置](/docs/zh-TW/plugins/mods/reference#render-sites)，因此僅使用窗格的 mod 也可能出現。呼叫了 `next(e)` 但捨棄其結果的 mod 不會產生任何行，因此也請檢查在您之前的 hook。

變更之後，若任何 mod 返回未通過驗證的樹，帶狀中將不會顯示任何內容。若要讀取原因，請在 `--plugin-dir` 工作階段的逐字稿中尋找 `ui.render (AbovePrompt) refused:` 行，或在偵錯日誌中搜尋 `does not validate`。當帶狀中有多個 mod 時，這兩行都不會指出是哪個 mod，因此請檢查每個 mod 的樹。

<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">
  窗格或帶狀為空或顯示 Claude Code 的常見內容
</h3>

您的 hook 返回的[樹](/docs/zh-TW/plugins/mods/interface#build-a-tree-from-elements)未通過驗證。使用 `--plugin-dir` 時，逐字稿會顯示 `ui.render (Pane) refused:` 並附上原因，例如 `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`。偵錯日誌中會有 `a hook returned a tree that does not validate` 並附上相同的原因。

讀取該行上的原因。常見原因是元素不接受的 prop 和應用程式沒有的元素。

<h3 id="a-ui-render-line-says-threw-while-drawn">
  `ui.render` 行顯示 `threw while drawn`
</h3>

該行會指出[轉譯位置](/docs/zh-TW/plugins/mods/reference#render-sites)，接著顯示 `threw while drawn:` 與錯誤，例如 `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`。Claude Code 在繪製您的 [`ui.render`](/docs/zh-TW/plugins/mods/reference#interface) hook 返回的樹時，或在根據[您的 hook 傳給 `next` 的 `props`](/docs/zh-TW/plugins/mods/interface#change-what-claude-code-already-draws) 繪製該位置時，遇到了該錯誤。結尾的 `the engine drew its own` 表示該位置顯示 Claude Code 的常見內容。

讀取該錯誤，並修正您的 hook 中導致錯誤的值。

在 v2.1.289 之前，逐字稿列中的此錯誤會以 [`Claude Code exited after an unrecoverable interface error`](/docs/zh-TW/errors#exited-after-an-unrecoverable-interface-error) 結束工作階段。

<h3 id="the-module-failed-without-a-message">
  `the module failed without a message`
</h3>

某個 [`Client`](/docs/zh-TW/plugins/mods/interface#when-a-client-fails) 因沒有訊息的錯誤而失敗，例如 `throw new Error()`。在其位置顯示的那一行類似 `my-mod: Client client/spinner.js: the module failed without a message`。

在您的 `Client` 程式碼中找到該 throw，並為錯誤加上訊息。該行隨後便會顯示該訊息。

在 v2.1.289 之前，該行會改為顯示 `Error` 作為原因。

<h3 id="$-ui-open-runs-and-no-pane-appears">
  `$.ui.open` 執行且沒有窗格出現
</h3>

呼叫不是來自使用者所做的操作，並且終端機的寬度小於[該窗格所需的寬度](/docs/zh-TW/plugins/mods/interface#when-a-pane-waits-for-a-wider-terminal)。

從命令或按鈕開啟窗格，或檢查呼叫的 `isPlaced` 結果。請參閱[在正確的時間開啟窗格](/docs/zh-TW/plugins/mods/interface#open-a-pane-at-the-right-time)。

<h3 id="a-toast-doesn’t-appear">
  toast 未出現
</h3>

您的 mod 在互動式終端機工作階段中呼叫 [`$.ui.toast`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，但您沒有看到 toast。若要確認該呼叫已執行，請在[偵錯日誌](#read-the-debug-log)中尋找包含您的 mod 名稱與 toast 文字的行，例如 `$.ui.toast (first-mod): build finished`。接著檢查以下可能原因：

* **缺少該呼叫的行**：尋找說明 Claude Code 拒絕該呼叫原因的行，例如 `first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000`。
* **有窗格正在保留 toast**：您的 mod 或其他 mod 在開啟目前顯示的窗格時傳入了 [`holdToasts`](/docs/zh-TW/plugins/mods/interface#hold-toasts-behind-a-dialog)。關閉該窗格即可結束保留。如果該窗格是您的，且應保持開啟，請從其 `$.ui.open` 呼叫中移除 `holdToasts`，然後重新開啟窗格。
* **toast 位於提示詞下方**：在[傳統轉譯器](/docs/zh-TW/fullscreen#enable-fullscreen-rendering)中，請查看提示詞下方的右側。該處的 toast 是以 mod 名稱開頭的一行文字，而不是右上角的方框。
* **您的 mod 發出了較新的 toast**：在傳統轉譯器中，您的 mod 發出的較新 toast 可能會取代正在顯示或等待顯示的 toast。偵錯日誌中會有較舊 toast 的另一行，若該 toast 正在顯示，結尾為 `gave way, cut short`；若從未出現，結尾為 `gave way, unseen`。若要同時顯示兩則訊息，請將它們放在同一個 toast 中。
* **toast 在繪製前逾時**：在全螢幕轉譯中，Claude Code 一次最多繪製三個 toast，因此 toast 可能在繪製前就已逾時。偵錯日誌中會有該 toast 的另一行，結尾為 `left the stack, never drawn`。當您的 mod 同時發出多個 toast 時，請將訊息放在同一個 toast 中。

在 v2.1.290 之前，Claude Code 會捨棄在其為您的 mod 顯示上一個 toast 後兩秒內發出的 toast，且被捨棄 toast 的偵錯日誌行會顯示 `within 2000ms of the last; dropped`。

<h3 id="hotkeys-do-nothing">
  快捷鍵沒有作用
</h3>

您的窗格沒有鍵盤焦點，或繪圖位於 VS Code 擴充功能中，而該處的按鈕沒有快捷鍵。請執行相符的操作：

* **沒有鍵盤焦點**：按 Ctrl+X 然後 Tab，或按一下窗格。若要讓窗格在開啟時取得焦點，請從命令以 `focus: true` 開啟它。
* **在 VS Code 擴充功能中**：按一下按鈕，或在按鈕取得焦點後按 Enter

<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app-or-vs-code">
  繪圖在終端機中有效，但在 Desktop 應用程式或 VS Code 中無效
</h3>

可能是該應用程式不繪製該位置或元素，或是該工作階段屬於 VS Code 擴充功能不會為 mod 繪製任何內容的情況。mod 的其他 hook 仍會執行。請檢查以下原因：

* **該位置或元素未在該應用程式中繪製**：在[轉譯位置](/docs/zh-TW/plugins/mods/reference#render-sites)表中查詢您的位置，並在[元素](/docs/zh-TW/plugins/mods/reference#elements)表中查詢您的元素。對於該應用程式缺少的元素，請在 hook 中檢查 `e.surface`，並返回該應用程式可繪製的樹。
* **VS Code 擴充功能版本早於 2.1.299**：聊天面板從[擴充功能版本](/docs/zh-TW/vs-code#install-the-extension) 2.1.299 起會為 mod 繪製內容。請在 VS Code 的 Extensions 檢視中檢查版本，並在該處更新擴充功能。
* **VS Code 工作階段不擷取功能旗標**：在聊天面板中繪製需要擷取功能旗標。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的工作階段，或透過 [Claude apps 閘道](/docs/zh-TW/claude-apps-gateway)的工作階段，會略過此步驟，[需要擷取功能旗標的功能](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)中列出的其他情況亦同。若要在此類工作階段中看到繪圖，請改為在終端機中執行 `claude`，例如 VS Code 的整合式終端機。

<h2 id="an-edit-or-a-value-is-lost">
  編輯或值遺失
</h2>

mod 執行，您所做的變更或它保留的值不存在。

<h3 id="your-edits-don’t-take-effect">
  您的編輯不生效
</h3>

您正在編輯您安裝的 plugin。Claude Code 執行已安裝版本的快取副本。

使用指向您的工作副本的 `--plugin-dir` 進行開發，例如 `claude --plugin-dir ./first-mod`，它在您儲存時重新載入。

<h3 id="a-value-resets-when-the-module-reloads">
  模組重新載入時值重設
</h3>

模組級變數在每次重新載入時重新初始化。

[將值保留在 `$.state` 或 `$.store`](/docs/zh-TW/plugins/mods/interface#keep-state)。

<h3 id="a-value-resets-after-/clear-/resume-or-/branch">
  `/clear`、`/resume` 或 `/branch` 後值重設
</h3>

值重設，或儲存的值被其預設值取代。這些命令中的每一個都將 `$.state` 重設為其預設值，並且 `session.start` 不會再次觸發。

[在 `classic.SessionStart` hook 中再次載入儲存的值](/docs/zh-TW/plugins/mods/interface#load-a-saved-value-again-after-clear)。

<h2 id="read-the-debug-log">
  讀取偵錯日誌
</h2>

偵錯日誌對 Claude Code 載入或拒絕的每個模組、失敗的每個 hook 和它拒絕的每個結果都有一行，因此當逐字稿顯示沒有內容時，這是要查看的地方。若要寫入一個，在您的 shell 中使用 `--debug` 啟動 Claude Code，或使用 `--debug-file <path>` 選擇它的位置：

```bash theme={null}
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
```

在另一個終端機中，跟蹤檔案並篩選您的 mod 的名稱：

```bash theme={null}
tail -f ./mod-debug.log | grep first-mod
```

已載入的 mod 有一行，其命名它並列出它處理的事件。使用 `--plugin-dir` 載入的 mod 出現在其名稱後跟 `@inline` 下：

```text theme={null}
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
```

未驗證的繪圖計為被拒絕的結果，也會得到一行。若要在日誌中寫入您自己的行，請呼叫 [`$.ui.log`](/docs/zh-TW/plugins/mods/api#show-something-without-starting-a-turn)，並帶有第二個引數，例如 `$.ui.log('message', { to: 'debug' })`。沒有第二個引數，`$.ui.log` 會在逐字稿中新增暗淡行。

當您編輯使用 `--plugin-dir` 載入的 mod 時，逐字稿會為每次重新載入顯示一行，其命名 mod 並列出其 hook。如果儲存破壞了模組，該行說 `reload failed, the previous version stays loaded:` 並帶有原因，最後一個可運作的版本會保持執行，直到 Claude Code 下次重新載入外掛為止，例如當您執行 `/reload-plugins` 時。

<h2 id="next-steps">
  後續步驟
</h2>

* [測試 mod](/docs/zh-TW/plugins/mods/test)：在問題到達工作階段之前捕捉它們
* [排除 plugin 的故障](/docs/zh-TW/plugins/troubleshooting)：安裝和載入 plugin 的問題，不特定於 mod