2885 2885
2886**工具名稱：** `Bash`2886**工具名稱：** `Bash`
2887 2887
28882888如需了解設定前景上限的內容，請參閱 [逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，請參閱 [背景命令](/docs/zh-TW/tools-reference#background-commands)。如需了解設定前景上限的內容，請參閱 [逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，請參閱 [背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。
2889 2889
2890**輸入：**2890**輸入：**
2891 2891
3123 工具輸入類型3123 工具輸入類型
3124</h2>3124</h2>
3125 3125
31263126所有內建 Claude Code 工具的輸入架構文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。所有內建 Claude Code 工具的輸入結構描述文件。這些類型從 `@anthropic-ai/claude-agent-sdk/sdk-tools` 匯出，可用於類型安全的工具互動。
3127 3127
3128<h3 id="toolinputschemas">3128<h3 id="toolinputschemas">
3129 `ToolInputSchemas`3129 `ToolInputSchemas`
3177 Agent3177 Agent
3178</h3>3178</h3>
3179 3179
31803180**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，[`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前仍將此工具列為 `Task` 以保持向後相容性。**工具名稱：** `Agent`。先前的名稱 `Task` 仍被接受為別名，[`SDKSystemMessage`](#sdksystemmessage) 初始化訊息中的 `tools` 陣列目前為了向後相容性將此工具列為 `Task`。
3181 3181
3182<Note>3182<Note>
3183 `mode` 欄位在 Claude Code v2.1.212 或更新版本上已棄用且被忽略。子代理在父工作階段的權限模式或其定義的 [`permissionMode`](#agentdefinition) 中執行，[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定使用哪一個。3183 `mode` 欄位在 Claude Code v2.1.212 或更新版本上已棄用且被忽略。子代理在父工作階段的權限模式或其定義的 [`permissionMode`](#agentdefinition) 中執行，[子代理繼承規則](/docs/zh-TW/agent-sdk/permissions#available-modes) 決定使用哪一個。
3219};3219};
3220```3220```
3221 3221
32223222在執行期間向使用者提出澄清問題。詳見[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以了解使用詳情。在執行期間詢問使用者澄清問題。詳見[處理核准和使用者輸入](/docs/zh-TW/agent-sdk/user-input#handle-clarifying-questions)以了解使用詳情。
3223 3223
3224<h3 id="bash">3224<h3 id="bash">
3225 Bash3225 Bash
3237};3237};
3238```3238```
3239 3239
32403240執行 Bash 命令，支援選擇性逾時和背景執行。工作目錄在命令之間保持不變，包括多輪工作階段後續執行的命令；shell 狀態（例如匯出的環境變數）則不會保持。如需了解哪些目錄變更會保留，詳見[命令之間保持的內容](/docs/zh-TW/tools-reference#what-persists-between-commands)。如需了解設定前景上限的因素，詳見[逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景時間限制，詳見[背景命令](/docs/zh-TW/tools-reference#background-commands)。執行 Bash 命令，支援選擇性逾時和背景執行。工作目錄在命令之間保持不變，包括多輪工作階段後續執行的命令；shell 狀態（例如匯出的環境變數）則不會保持。如需了解哪些目錄變更會保留，詳見[命令之間保持的內容](/docs/zh-TW/tools-reference#what-persists-between-commands)。如需了解前景上限的設定方式，詳見[逾時和輸出限制](/docs/zh-TW/tools-reference#timeout-and-output-limits)。如需了解背景命令的時間限制，詳見[背景命令的時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)。
3241 3241
3242<h3 id="monitor">3242<h3 id="monitor">
3243 Monitor3243 Monitor
3257};3257};
3258```3258```
3259 3259
32603260執行背景來源並將每個事件傳遞給 Claude，使其能夠做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。提供 `command` 或 `ws` 中的恰好一個。`ws` 來源需要 Claude Code v2.1.195 或更新版本。執行背景來源並將每個事件傳遞給 Claude，使其可以做出反應而無需輪詢：`command` 執行指令碼並每行 stdout 發出一個事件，`ws` 開啟 WebSocket 並每個文字框架發出一個事件。恰好提供 `command` 或 `ws` 其中之一。`ws` 來源需要 Claude Code v2.1.195 或更新版本。
3261 3261
32623262`timeout_ms` 是監視的截止時間（以毫秒為單位）。預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短到該值。在截止時間時，監視結束，Claude 收到一個通知，以便在仍需要時啟動新的監視。`timeout_ms` 是監視的截止時間（毫秒）。預設為 300000，接受最多 3600000 的值。有效截止時間最多為 1800000，即 30 分鐘，因此較大的接受值會縮短至該值。在截止時間時監視結束，Claude 收到一個通知，以便在仍需要時啟動新監視。
3263 3263
32643264匯出的類型將 `timeout_ms` 標記為必需，因為架構填入預設值；省略它的呼叫會驗證通過。匯出的類型將 `timeout_ms` 標記為必需，因為結構填入預設值；省略它的呼叫會驗證通過。
3265 3265
32663266Monitor 執行命令時，遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool)以了解行為和提供者可用性。當 Monitor 執行命令時，它遵循與 Bash 相同的權限規則；WebSocket 監視會單獨提示核准。詳見[Monitor 工具參考](/docs/zh-TW/tools-reference#monitor-tool)以了解行為和提供者可用性。
3267 3267
3268<h3 id="taskoutput">3268<h3 id="taskoutput">
3269 TaskOutput3269 TaskOutput
3270</h3>3270</h3>
3271 3271
32723272在 Claude Code v2.1.277 中移除，連同其 `TaskOutputInput` 類型一起移除。先前從執行中或已完成的背景任務中擷取輸出；Claude 改用 `Read` 讀取背景任務的輸出檔案。在 Claude Code v2.1.277 中移除，連同其 `TaskOutputInput` 類型一起移除。先前用於擷取執行中或已完成的背景任務的輸出；Claude 改用 `Read` 讀取背景任務的輸出檔案。
3273 3273
32743274仍命名 `TaskOutput` 的 `disallowedTools` 項目或拒絕規則會被忽略，不會發出警告。`disallowedTools` 項目或仍命名 `TaskOutput` 的拒絕規則會被忽略而不發出警告。
3275 3275
3276<h3 id="edit">3276<h3 id="edit">
3277 Edit3277 Edit
3307 3307
3308從本機檔案系統讀取檔案，包括文字、影片、PDF 和 Jupyter 筆記本。使用 `pages` 指定 PDF 頁面範圍（例如 `"1-5"`）。3308從本機檔案系統讀取檔案，包括文字、影片、PDF 和 Jupyter 筆記本。使用 `pages` 指定 PDF 頁面範圍（例如 `"1-5"`）。
3309 3309
33103310對於 PDF，Claude 在 Read 呼叫的 `tool_result` 內容中接收檔案的內容。傳回 `pdf` [輸出](#tool-output-types)的讀取會帶有摘要 `text` 區塊，後面跟著 `document` 區塊。傳回 `parts` 輸出的讀取會帶有摘要 `text` 區塊，後面跟著每個提取頁面的一個區塊：`image` 區塊，或當 Claude Code 無法將其呈現為影片時命名該頁面的 `text` 區塊。在 Agent SDK v0.3.242 之前，Claude Code 在工具結果後作為單獨的 `user` 訊息傳遞檔案的內容。對於 PDF，Claude 在 Read 呼叫的 `tool_result` 內容中接收檔案的內容。傳回 `pdf` [輸出](#tool-output-types)的讀取會帶有摘要 `text` 區塊，後面跟著 `document` 區塊。傳回 `parts` 輸出的讀取會帶有摘要 `text` 區塊，後面跟著每個擷取頁面的一個區塊：`image` 區塊，或當 Claude Code 無法將其呈現為影片時命名頁面的 `text` 區塊。在 Agent SDK v0.3.242 之前，Claude Code 在工具結果後將檔案的內容作為單獨的 `user` 訊息傳遞。
3311 3311
3312<h3 id="write">3312<h3 id="write">
3313 Write3313 Write
3449};3449};
3450```3450```
3451 3451
34523452執行[動態工作流程](/docs/zh-TW/workflows)：在背景中協調許多子代理並傳回一個統一結果的指令碼。Workflow 工具在 Agent SDK v0.3.149 及更新版本中可用。至少需要 `script`、`name` 或 `scriptPath` 中的一個。執行[動態工作流程](/docs/zh-TW/workflows)：在背景中協調許多子代理並傳回一個統一結果的指令碼。Workflow 工具在 Agent SDK v0.3.149 及更新版本中可用。至少需要 `script`、`name` 或 `scriptPath` 其中之一。
3453 3453
34543454| 欄位 | 類型 | 說明 || 欄位 | 類型 | 描述 |
3455| - | - | - |3455| - | - | - |
3456| `script` | `string` | 內嵌工作流程指令碼。必須以 `export const meta = { name, description }` 作為字面值開始，後面跟著使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的指令碼主體。`meta` 中的選擇性 `phases` 陣列在進度檢視中將代理分組到具名階段下 |3456| `script` | `string` | 內嵌工作流程指令碼。必須以 `export const meta = { name, description }` 作為字面值開始，後面跟著使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的指令碼主體。`meta` 中的選擇性 `phases` 陣列在進度檢視中將代理分組到具名階段下 |
3457| `name` | `string` | 內建工作流程的名稱或儲存在 `.claude/workflows/` 中的工作流程名稱。解析為指令碼 |3457| `name` | `string` | 內建工作流程的名稱或儲存在 `.claude/workflows/` 中的工作流程名稱。解析為指令碼 |
3458| `scriptPath` | `string` | 磁碟上工作流程指令碼檔案的路徑。優先於 `script` 和 `name`。Claude Code 保留每次呼叫的指令碼並在結果中傳回路徑，因此您可以編輯該檔案並使用相同的 `scriptPath` 重新呼叫以進行迭代 |3458| `scriptPath` | `string` | 磁碟上工作流程指令碼檔案的路徑。優先於 `script` 和 `name`。Claude Code 保留每次呼叫的指令碼並在結果中傳回路徑，因此您可以編輯該檔案並使用相同的 `scriptPath` 重新呼叫以進行迭代 |
3459| `args` | `unknown` | 輸入值，作為全域 `args` 公開給指令碼，用於參數化的具名工作流程，例如研究問題或檔案路徑清單。將陣列和物件作為實際 JSON 值傳遞，而不是 JSON 編碼的字串 |3459| `args` | `unknown` | 輸入值，作為全域 `args` 公開給指令碼，用於參數化的具名工作流程，例如研究問題或檔案路徑清單。將陣列和物件作為實際 JSON 值傳遞，而不是 JSON 編碼的字串 |
34603460| `resumeFromRunId` | `string` | 先前 `Workflow` 呼叫的執行 ID 以繼續。具有未變更輸入的已完成 `agent()` 呼叫通常傳回快取結果；其餘的執行即時。[暫停後繼續](/docs/zh-TW/workflows#resume-after-a-pause)涵蓋哪些已完成的呼叫重新執行。僅限同一工作階段 || `resumeFromRunId` | `string` | 先前 `Workflow` 呼叫的執行 ID 以繼續。具有未變更輸入的已完成 `agent()` 呼叫通常傳回快取結果；其餘的執行即時。[暫停後繼續](/docs/zh-TW/workflows#resume-after-a-pause)涵蓋哪些已完成的呼叫會重新執行。僅限同一工作階段 |
34613461| `title` | `string` | 已忽略；指令碼的 `meta` 區塊設定標題 || `title` | `string` | 被忽略；指令碼的 `meta` 區塊設定標題 |
34623462| `description` | `string` | 已忽略；指令碼的 `meta` 區塊設定說明 || `description` | `string` | 被忽略；指令碼的 `meta` 區塊設定描述 |
3463 3463
3464<h3 id="todowrite">3464<h3 id="todowrite">
3465 TodoWrite3465 TodoWrite
3577};3577};
3578```3578```
3579 3579
35803580退出 Plan Mode。`allowedPrompts` 欄位已棄用且被忽略；Claude Code 仍接受它以便現有呼叫者和文字記錄驗證。在 v2.1.205 之前，它要求基於提示的 Bash 權限以實施計畫。退出 Plan Mode。`allowedPrompts` 欄位已棄用且被忽略；Claude Code 仍接受它以便現有呼叫者和文字記錄驗證通過。在 v2.1.205 之前，它要求基於提示的 Bash 權限以實現計畫。
3581 3581
3582<h3 id="listmcpresources">3582<h3 id="listmcpresources">
3583 ListMcpResources3583 ListMcpResources
3648type EnterPlanModeInput = {};3648type EnterPlanModeInput = {};
3649```3649```
3650 3650
36513651進入 Plan Mode，其中 Claude 在進行變更前研究並呈現計畫。進入 Plan Mode，Claude 在其中研究並在進行變更前提出計畫。
3652 3652
3653<h3 id="croncreate">3653<h3 id="croncreate">
3654 CronCreate3654 CronCreate
3665};3665};
3666```3666```
3667 3667
36683668在本機時間的 5 欄位 cron 排程上排程提示執行。將 `recurring` 設定為 `false` 以在下一個符合時單次觸發。工作預設為工作階段範圍，啟動新對話會清除它們，使用 `--resume` 或 `--continue` 繼續會還原尚未過期的工作。詳見[排程任務](/docs/zh-TW/scheduled-tasks)。在本機時間的 5 欄位 cron 排程上排程提示執行。將 `recurring` 設定為 `false` 以在下一個符合時單次觸發。工作預設為工作階段範圍，使用 `--resume` 或 `--continue` 繼續時會還原尚未過期的工作。詳見[排程任務](/docs/zh-TW/scheduled-tasks)。
3669 3669
36703670將 `durable` 設定為 `true` 以要求持久化到 `.claude/scheduled_tasks.json`，使工作在重新啟動後存活。持久化排程並非在每個工作階段都可用：當不可用時，Claude Code 接受 `durable: true` 但建立工作階段專用工作。讀取輸出的 `durable` 欄位以查看工作是否已持久化。將 `durable` 設定為 `true` 以要求持久化至 `.claude/scheduled_tasks.json`，使工作在重新啟動後存活。並非每個工作階段都提供持久排程：當不提供時，Claude Code 接受 `durable: true` 但建立工作為僅工作階段。讀取輸出的 `durable` 欄位以查看工作是否已持久化。
3671 3671
3672<h3 id="crondelete">3672<h3 id="crondelete">
3673 CronDelete3673 CronDelete
3681};3681};
3682```3682```
3683 3683
36843684按從 `CronCreate` 傳回的 ID 刪除排程的 cron 工作。按 `CronCreate` 傳回的 ID 刪除排程的 cron 工作。
3685 3685
3686<h3 id="cronlist">3686<h3 id="cronlist">
3687 CronList3687 CronList
3693type CronListInput = {};3693type CronListInput = {};
3694```3694```
3695 3695
36963696列出排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久化工作和來自目前工作階段的工作階段專用工作。列出排程的 cron 工作：來自 `.claude/scheduled_tasks.json` 的持久工作和來自目前工作階段的僅工作階段工作。
3697 3697
3698<h3 id="schedulewakeup">3698<h3 id="schedulewakeup">
3699 ScheduleWakeup3699 ScheduleWakeup
3711};3711};
3712```3712```
3713 3713
37143714排程一次性喚醒，在延遲後觸發給定的提示。此工具支援自步調 `/loop` 命令。執行時間將 `delaySeconds` 限制在 60 到 3600 秒之間。除非 `stop` 為 true，否則 `delaySeconds`、`reason`、`prompt` 和 `noop` 欄位為必需。`noop: true` 報告沒有任何變更的喚醒。設定 `stop: true` 以取消待處理的喚醒並結束自步調 `/loop`。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。詳見[工具參考中的 ScheduleWakeup 列](/docs/zh-TW/tools-reference)。排程一次性喚醒，在延遲後觸發給定的提示。此工具支援自步調 `/loop` 命令。執行時間將 `delaySeconds` 限制在 60 到 3600 秒之間。除非 `stop` 為 true，否則 `delaySeconds`、`reason`、`prompt` 和 `noop` 欄位為必需。`noop: true` 報告沒有任何變更的喚醒。設定 `stop: true` 會取消待處理的喚醒並結束自步調 `/loop`。`stop` 欄位需要 Claude Code v2.1.202 或更新版本。詳見[工具參考中的 ScheduleWakeup 列](/docs/zh-TW/tools-reference)。
3715 3715
3716<h3 id="remotetrigger">3716<h3 id="remotetrigger">
3717 RemoteTrigger3717 RemoteTrigger
3739};3739};
3740```3740```
3741 3741
37423742管理[例行工作](/docs/zh-TW/routines)，即在雲端託管的排程和觸發 Claude Code 執行。此工具支援 `/schedule` 命令。`trigger_id` 對於 `get`、`update`、`run` 和 `list_runs` 動作為必需。`body` 對於 `create`、`update` 和 `create_webhook_trigger` 為必需，對於 `run` 為選擇性。管理[例行程序](/docs/zh-TW/routines)，即在雲端託管的排程和觸發 Claude Code 執行。此工具支援 `/schedule` 命令。`trigger_id` 對於 `get`、`update`、`run` 和 `list_runs` 動作為必需。`body` 對於 `create`、`update` 和 `create_webhook_trigger` 為必需，對於 `run` 為選擇性。
3743 3743
37443744`create_webhook_trigger` 將事件來源附加到現有例行工作，例如觸發它的 [GitHub 事件](/docs/zh-TW/routines#add-a-github-trigger)。`body` 命名來源、事件和要觸發的例行工作。需要 Claude Code v2.1.225 或更新版本。`create_webhook_trigger` 將事件來源附加到現有例行程序，例如觸發它的 [GitHub 事件](/docs/zh-TW/routines#add-a-github-trigger)。`body` 命名來源、事件和要觸發的例行程序。需要 Claude Code v2.1.225 或更新版本。
3745 3745
37463746`list_runs` 列出例行工作的最近執行，`get_run_log` 讀取一個執行的日誌。`session_id` 命名要讀取的執行，來自 `list_runs` 結果，`cursor` 透過任一動作的結果進行分頁。兩個動作都需要 Claude Code v2.1.227 或更新版本。`list_runs` 列出例行程序的最近執行，`get_run_log` 讀取一個執行的日誌。`session_id` 命名要讀取的執行（來自 `list_runs` 結果），`cursor` 分頁任一動作的結果。兩個動作都需要 Claude Code v2.1.227 或更新版本。
3747 3747
37483748此工具僅在工作階段使用啟用例行工作的計畫的 claude.ai 帳戶進行驗證時可用，當您的組織政策停用[網路上的 Claude Code](/docs/zh-TW/claude-code-on-the-web) 時不存在。在 Claude Code v2.1.227 或更新版本上，當所有者[為組織關閉例行工作](/docs/zh-TW/routines#routines-are-disabled-by-your-organizations-policy)時，該工具也不存在。在 v2.1.227 之前，僅關閉例行工作切換的工作階段仍顯示該工具，伺服器拒絕其呼叫。此工具僅在工作階段使用啟用例行程序的 claude.ai 帳戶進行驗證時可用，當您的組織政策停用[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)時不存在。在 Claude Code v2.1.227 或更新版本上，當擁有者[為組織關閉例行程序](/docs/zh-TW/routines#routines-are-disabled-by-your-organizations-policy)時，工具也不存在。在 v2.1.227 之前，僅關閉例行程序切換的工作階段仍顯示工具，伺服器拒絕其呼叫。
3749 3749
3750<h3 id="pushnotification">3750<h3 id="pushnotification">
3751 PushNotification3751 PushNotification
3760};3760};
3761```3761```
3762 3762
37633763向使用者傳送主動推播通知。將 `message` 保持在 200 個字元以下，因為行動作業系統會截斷較長的文字。詳見[工具參考中的 PushNotification 列](/docs/zh-TW/tools-reference)以了解提供者可用性；推播傳遞透過 Anthropic 託管的基礎設施執行，無法從 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取。向使用者傳送主動推播通知。將 `message` 保持在 200 個字元以下，因為行動作業系統會截斷較長的文字。詳見[工具參考中的 PushNotification 列](/docs/zh-TW/tools-reference)以了解提供者可用性；推播傳遞通過 Anthropic 託管的基礎設施進行，該基礎設施無法從 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 或 Microsoft Foundry 存取。
3764 3764
3765<h3 id="repl">3765<h3 id="repl">
3766 REPL3766 REPL
3767</h3>3767</h3>
3768 3768
37693769在 v2.1.275 中移除。透過 v2.1.274，實驗性 `REPL` 工具可以透過在 [`env` 選項](#options)中設定 `CLAUDE_CODE_REPL=1` 來開啟。在 v2.1.275 中移除。通過 v2.1.274，實驗性 `REPL` 工具可以通過在[`env` 選項](#options)中設定 `CLAUDE_CODE_REPL=1` 來開啟。
3770 3770
3771<h3 id="reportfindings">3771<h3 id="reportfindings">
3772 ReportFindings3772 ReportFindings
3790};3790};
3791```3791```
3792 3792
37933793將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有倖存時陣列為空。需要 Claude Code v2.1.196 或更新版本。將程式碼審查發現報告為結構化清單，以便 Claude Code 可以呈現它們而不是將其列印為文字。`level` 是審查執行的工作量級別。發現按最嚴重優先排序，每次呼叫最多 32 個，當沒有發現存活時陣列為空。需要 Claude Code v2.1.196 或更新版本。
3794 3794
3795每個發現包含這些欄位：3795每個發現包含這些欄位：
3796 3796
3797* `file`：發現所在的儲存庫相對路徑。選擇性 `line` 是它錨定到的 1 索引行。3797* `file`：發現所在的儲存庫相對路徑。選擇性 `line` 是它錨定到的 1 索引行。
3798* `summary`：缺陷的單句陳述。`failure_scenario` 描述導致錯誤輸出或當機的具體輸入和狀態。3798* `summary`：缺陷的單句陳述。`failure_scenario` 描述導致錯誤輸出或當機的具體輸入和狀態。
37993799* `short_summary`：選擇性的最多 60 個字元的壓縮標籤，用於緊湊顯示。需要 Claude Code v2.1.212 或更新版本。* `short_summary`：選擇性壓縮標籤，最多 60 個字元用於緊湊顯示。需要 Claude Code v2.1.212 或更新版本。
38003800* `category`：選擇性的發現類型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更新版本。* `category`：選擇性短 kebab-case 發現類型的 slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更新版本。
38013801* `verdict`：在驗證通過執行時設定；在僅內嵌審查中不存在。* `verdict`：在驗證通過執行時設定；在僅內嵌審查上不存在。
3802* `outcome`：僅在應用修復後重新報告時設定。3802* `outcome`：僅在應用修復後重新報告時設定。
3803 3803
3804<h3 id="artifact">3804<h3 id="artifact">
3825};3825};
3826```3826```
3827 3827
38283828將本機 `.html` 或 `.md` 檔案發佈為託管成品頁面，或列出使用者的已發佈成品。省略 `action` 或傳遞 `"publish"` 以發佈 `file_path`，這對於發佈動作為必需。每個以下欄位適用於發佈：將本機 `.html` 或 `.md` 檔案發佈為託管成品頁面，或列出使用者的已發佈成品。省略 `action` 或傳遞 `"publish"` 以發佈 `file_path`，這對於發佈動作為必需。以下每個欄位適用於發佈：
3829 3829
38303830* `icon`：成品瀏覽器標籤圖示的一個短通用詞，例如 `chart` 或 `map`。Claude 在首次發佈時包含它，在更新時省略它，這會保留成品的儲存圖示。* `icon`：成品瀏覽器標籤圖示的一個短通用詞，例如 `chart` 或 `map`。Claude 在首次發佈時包含它，在更新時省略它，這保留成品的儲存圖示。
38313831* `favicon`：已棄用，Claude 會省略它。* `favicon`：已棄用，Claude 省略它。
38323832* `title`：當 HTML 檔案沒有 `<title>` 標籤時，在瀏覽器標籤和圖庫中命名已發佈頁面。* `title`：在瀏覽器標籤和圖庫中命名已發佈頁面，當 HTML 檔案沒有 `<title>` 標籤時。
38333833* `url`：以現有成品為目標以就地更新，而不是建立新的。* `url`：目標是現有成品以就地更新，而不是建立新的。
3834 3834
38353835`force` 是最後手段的覆蓋，捨棄另一個工作階段發佈的較新版本。發生衝突時，失敗的發佈會傳回較新的內容；Claude 將其變更合併到該內容上，或重新讀取成品，然後再次發佈。僅當使用者明確要求捨棄該版本時才傳遞 `force`。`force` 是最後手段覆蓋，丟棄另一個工作階段發佈的較新版本。在衝突時，失敗的發佈傳回較新的內容；Claude 將其變更合併到該內容上，或重新讀取成品，並再次發佈。僅當使用者明確要求丟棄該版本時傳遞 `force`。
3836 3836
38373837傳遞 `"list"` 以列舉使用者的已發佈成品；只有 `limit` 和 `scope` 可能伴隨它。`scope` 預設為 `"mine"`，列出使用者擁有的成品；`"shared"` 列出其他人與使用者共享的成品，`"all"` 列出兩者。傳遞 `"list"` 以列舉使用者的已發佈成品；僅 `limit` 和 `scope` 可能伴隨它。`scope` 預設為 `"mine"`，列出使用者擁有的成品；`"shared"` 列出其他人與使用者共享的成品，`"all"` 列出兩者。
3838 3838
38393839* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，並在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。* `capabilities`：已發佈頁面使用的執行時功能，按功能名稱鍵入，例如[頁面可能呼叫的連接器](/docs/zh-TW/artifacts#pull-live-data-with-mcp-connectors)。成品服務驗證宣告並拒絕命名帳戶無法使用的功能或給予一個無效設定的發佈。傳遞 `{}` 以清除儲存的宣告，在重新部署時省略欄位以保留它。需要 Agent SDK v0.3.235 或更新版本。
3840* `contract`：已發佈頁面執行的執行時版本。省略它以保留成品的目前版本，傳遞 `"latest"` 以升級，或傳遞特定版本以釘選或回滾。需要 Agent SDK v0.3.235 或更新版本。3840* `contract`：已發佈頁面執行的執行時版本。省略它以保留成品的目前版本，傳遞 `"latest"` 以升級，或傳遞特定版本以釘選或回滾。需要 Agent SDK v0.3.235 或更新版本。
3841 3841
38423842類型已匯出，但該工具在 Agent SDK 工作階段中預設關閉。發佈還需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。類型已匯出，但工具在 Agent SDK 工作階段中預設為關閉。發佈也需要[成品可用性表](/docs/zh-TW/artifacts#availability)中的每個條件，使用 API 金鑰驗證的工作階段不符合。
3843 3843
3844<h3 id="projects">3844<h3 id="projects">
3845 Projects3845 Projects
3868 3868
3869* `project_info`：傳回專案中繼資料和文件清單。3869* `project_info`：傳回專案中繼資料和文件清單。
3870* `project_read`：按 `path` 讀取一個文件。3870* `project_read`：按 `path` 讀取一個文件。
38713871* `project_search`：使用 `query` 查詢專案的知識庫。`n` 限制點擊數，預設為 5。* `project_search`：使用 `query` 查詢專案的知識庫。`n` 限制點擊數並預設為 `5`。
38723872* `project_write`：在 `path` 建立或取代文件，來自 `content`（帶有內嵌文字）或 `local_path`（命名工作目錄內的檔案）中的恰好一個。`present_to_user: true` 將寫入的文件標記為使用者需要查看的可交付成果。* `project_write`：在 `path` 建立或替換文件，恰好來自 `content`（帶有內嵌文字）或 `local_path`（命名工作目錄內的檔案）其中之一。`present_to_user: true` 將寫入的文件標記為使用者需要查看的可交付成果。
3873* `project_delete`：按 `path` 刪除文件。3873* `project_delete`：按 `path` 刪除文件。
3874 3874
3875<h3 id="readmcpresourcedir">3875<h3 id="readmcpresourcedir">
3885};3885};
3886```3886```
3887 3887
38883888列出 MCP 伺服器上目錄資源的直接子項。僅可用於已宣告支援目錄列表的伺服器；列表不是遞迴的。目錄列表並非在每個工作階段都啟用：當關閉時，呼叫傳回空的 `resources` 清單，`error` 欄位報告目錄列表未啟用。列出 MCP 伺服器上目錄資源的直接子項。僅可用於已宣告支援目錄列表的伺服器；列表不是遞迴的。並非每個工作階段都啟用目錄列表：當關閉時，呼叫傳回空 `resources` 清單，`error` 欄位報告目錄列表未啟用。
3889 3889
3890<h3 id="refreshmcptools">3890<h3 id="refreshmcptools">
3891 RefreshMcpTools3891 RefreshMcpTools
3899};3899};
3900```3900```
3901 3901
39023902重新查詢已連接 MCP 伺服器的工具清單並應用任何變更。類型已匯出，但 Claude Code 僅在您在 [`env` 選項](#options)中設定 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 時註冊該工具，並且僅在至少有一個 MCP 伺服器的工作階段中。需要 Claude Code v2.1.211 或更新版本。重新查詢已連接 MCP 伺服器的工具清單並應用任何變更。類型已匯出，但 Claude Code 僅在您在[`env` 選項](#options)中設定 `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` 時註冊工具，且僅在至少有一個 MCP 伺服器的工作階段中。需要 Claude Code v2.1.211 或更新版本。
3903 3903
3904<h3 id="showonboardingrolepicker">3904<h3 id="showonboardingrolepicker">
3905 ShowOnboardingRolePicker3905 ShowOnboardingRolePicker
3911type ShowOnboardingRolePickerInput = {};3911type ShowOnboardingRolePickerInput = {};
3912```3912```
3913 3913
39143914在 Cowork 上線期間呈現可點擊的角色選擇器晶片列，以便使用者可以選擇其角色並取得相符的外掛程式安裝。不帶任何引數；角色清單由用戶端定義。呼叫會阻止直到使用者回應。在 Cowork 上線期間呈現可點擊的角色選擇器晶片列，以便使用者可以選擇其角色並取得相符的外掛程式安裝。不帶引數；角色清單由用戶端定義。呼叫會阻止直到使用者回應。
3915 3915
3916<h3 id="mcpinput">3916<h3 id="mcpinput">
3917 McpInput3917 McpInput
3925};3925};
3926```3926```
3927 3927
39283928MCP 工具引數是開放物件：每個伺服器定義自己的參數，因此類型對欄位名稱或值不施加任何限制。請查閱伺服器自己的工具架構以了解特定工具接受的欄位。MCP 工具引數是開放物件：每個伺服器定義其自己的參數，因此類型對欄位名稱或值不施加任何限制。請查閱伺服器自己的工具結構以了解特定工具接受的欄位。
3929 3929
3930<h2 id="tool-output-types">3930<h2 id="tool-output-types">
3931 工具輸出類型3931 工具輸出類型
4141 4141
4142`timedOutAfterMs` 是逾時（以毫秒為單位），當命令達到其逾時並移至背景而不是明確從那裡開始時設定。`backgroundCwdHint` 在背景化命令包含目錄變更內建函式（例如 `cd`、`pushd`、`popd` 或 `chdir`）時設定，並注意工作階段工作目錄未變更。兩個欄位都需要 Claude Code v2.1.210 或更新版本。4142`timedOutAfterMs` 是逾時（以毫秒為單位），當命令達到其逾時並移至背景而不是明確從那裡開始時設定。`backgroundCwdHint` 在背景化命令包含目錄變更內建函式（例如 `cd`、`pushd`、`popd` 或 `chdir`）時設定，並注意工作階段工作目錄未變更。兩個欄位都需要 Claude Code v2.1.210 或更新版本。
4143 4143
41444144當在前景執行的子代理擁有背景化命令時，該命令[在該子代理的執行結束時結束](/docs/zh-TW/tools-reference#background-commands)。Claude Code 在此類命令上將 `backgroundEndsWithFinalResponse` 設定為 `true`，並在命令存活該輪時省略欄位，如主對話或背景子代理啟動的命令一樣。此欄位需要 Claude Code v2.1.227 或更新版本。當在前景執行的子代理擁有背景化命令時，該命令[在該子代理的執行結束時結束](/docs/zh-TW/tools-reference#when-a-background-command-stops)。Claude Code 在此類命令上將 `backgroundEndsWithFinalResponse` 設定為 `true`，並在命令存活該輪時省略欄位，如主對話或背景子代理啟動的命令一樣。此欄位需要 Claude Code v2.1.227 或更新版本。
4145 4145
4146Claude Code 將 `gitOperation.commit.branch` 設定為 git 提交摘要行中命名的分支，並對在分離 HEAD 上進行的提交省略它。此欄位需要 Agent SDK v0.3.227 或更新版本。Claude Code 將 `gh pr reopen` 命令報告為 `reopened` PR 動作，需要 Agent SDK v0.3.234 或更新版本。4146Claude Code 將 `gitOperation.commit.branch` 設定為 git 提交摘要行中命名的分支，並對在分離 HEAD 上進行的提交省略它。此欄位需要 Agent SDK v0.3.227 或更新版本。Claude Code 將 `gh pr reopen` 命令報告為 `reopened` PR 動作，需要 Agent SDK v0.3.234 或更新版本。
4147 4147
8 8
9Agent view（使用 `claude agents` 開啟）是所有背景工作階段的一個螢幕：什麼正在執行、什麼需要您的輸入，以及什麼已完成。分派新工作階段，一目瞭然地查看它們的狀態，而不是滾動瀏覽記錄，並且只在需要時才介入。每個背景工作階段都是一個完整的 Claude Code 對話，在沒有終端連接的情況下持續執行，因此您可以隨時開啟、回覆和離開。9Agent view（使用 `claude agents` 開啟）是所有背景工作階段的一個螢幕：什麼正在執行、什麼需要您的輸入，以及什麼已完成。分派新工作階段，一目瞭然地查看它們的狀態，而不是滾動瀏覽記錄，並且只在需要時才介入。每個背景工作階段都是一個完整的 Claude Code 對話，在沒有終端連接的情況下持續執行，因此您可以隨時開啟、回覆和離開。
10 10
1111<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1772" height="780" data-path="images/agent-view-light.png" /><img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=d6905012bee31f3e6b3920b09c05dd02" className="dark:hidden" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1872" height="680" data-path="images/agent-view-light.png" />
12 12
1313<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1772" height="780" data-path="images/agent-view-dark.png" /><img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-dark.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=fc3c195bfc57e313ced1f1beb36cee93" className="hidden dark:block" alt="終端中的 Agent view：標題顯示 Claude Code v2.1.140、模型、工作目錄和摘要計數。工作階段分組在'需要輸入'、'執行中'和'已完成'下，底部有分派輸入，頁尾有快捷鍵提示。" width="1872" height="680" data-path="images/agent-view-dark.png" />
14 14
15當您有多個獨立任務 Claude 可以在不需要您監看每一步的情況下執行時，請使用 agent view。分派一個錯誤修復、一個拉取請求審查和一個不穩定測試調查作為三行，在另一個視窗中繼續工作，並在某一行顯示需要您或有結果時檢查。15當您有多個獨立任務 Claude 可以在不需要您監看每一步的情況下執行時，請使用 agent view。分派一個錯誤修復、一個拉取請求審查和一個不穩定測試調查作為三行，在另一個視窗中繼續工作，並在某一行顯示需要您或有結果時檢查。
16 16
84| `--dangerously-skip-permissions` | 跳過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)以了解此操作跳過和不跳過的內容。對於使用 `--bg` 啟動的工作階段，當主管重新啟動工作階段時，模式[會保留](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 跳過權限提示。等同於 `--permission-mode bypassPermissions`。請參閱[權限模式](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)以了解此操作跳過和不跳過的內容。對於使用 `--bg` 啟動的工作階段，當主管重新啟動工作階段時，模式[會保留](/docs/zh-TW/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |
85| `--debug` | 啟用偵錯模式，可選類別篩選，例如 `--debug='mcp,startup'` 或 `--debug='!1p'`。篩選僅在 `=` 形式中繫結；以空格分隔的篩選啟用偵錯模式而不進行篩選 | `claude --debug='mcp,startup'` |85| `--debug` | 啟用偵錯模式，可選類別篩選，例如 `--debug='mcp,startup'` 或 `--debug='!1p'`。篩選僅在 `=` 形式中繫結；以空格分隔的篩選啟用偵錯模式而不進行篩選 | `claude --debug='mcp,startup'` |
86| `--debug-file <path>` | 將偵錯日誌寫入特定檔案路徑。隱含啟用偵錯模式。優先於 `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |86| `--debug-file <path>` | 將偵錯日誌寫入特定檔案路徑。隱含啟用偵錯模式。優先於 `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |
87| `--desktop` | 在目前目錄上開啟 [Claude Desktop 應用程式](/docs/zh-TW/desktop)並結束而不在終端機中啟動工作階段。新增 `--continue` 或 `--resume` 搭配工作階段 ID，以[在 Desktop 中開啟該工作階段](/docs/zh-TW/desktop#coming-from-the-cli)。此處的 `--resume` 僅採用工作階段 ID，不採用名稱或文字記錄路徑。不採用提示和其他旗標，除了 `--verbose` 和 `--debug` 旗標，因為應用程式會自行啟動工作階段。在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。需要 Claude Code v2.1.285 或更新版本 | `claude --desktop` |
87| `--disable-slash-commands` | 為此工作階段停用所有 skills 和命令 | `claude --disable-slash-commands` |88| `--disable-slash-commands` | 為此工作階段停用所有 skills 和命令 | `claude --disable-slash-commands` |
88| `--disallowedTools`, `--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除相符的工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)`）會保留工具可用，並僅拒絕[如所寫](/docs/zh-TW/permissions#bash-rule-limits)相符的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |89| `--disallowedTools`, `--disallowed-tools` | 拒絕規則。裸工具名稱會從 Claude 的內容中移除相符的工具：`"Edit"` 移除 Edit、`"*"` 移除每個工具，`"mcp__*"` 移除每個 MCP 工具。範圍規則（例如 `Bash(rm *)`）會保留工具可用，並僅拒絕[如所寫](/docs/zh-TW/permissions#bash-rule-limits)相符的呼叫。命名 [`EndConversation`](/docs/zh-TW/tools-reference#endconversation-tool-behavior) 的規則在任何其他工具保持時無法移除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |
89| `--effort` | 為目前工作階段設定[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的等級取決於模型。`ultracode` 要求 `xhigh` 努力並[啟用 ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，不會保留 | `claude --effort high` |90| `--effort` | 為目前工作階段設定[努力等級](/docs/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用的等級取決於模型。`ultracode` 要求 `xhigh` 努力並[啟用 ultracode](/docs/zh-TW/workflows#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更新版本。覆蓋此工作階段的 [`modelSettings`](/docs/zh-TW/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-TW/settings-reference#effortlevel) 設定，不會保留 | `claude --effort high` |
116| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |117| `--permission-prompts` | 在列印模式中設定誰回答權限提示。使用預設 `host`，Claude Code 會將它們傳送到 Agent SDK 主機或 `--permission-prompt-tool` 工具。當沒有人可以回答時傳遞 `none`，Claude Code 會改為拒絕它們。請參閱[在無人值守執行中關閉權限提示](/docs/zh-TW/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更新版本 | `claude -p --permission-prompts none "query"` |
117| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |118| `--plugin-dir` | 從目錄或 `.zip` 封存載入 plugin，或從[plugins 資料夾](/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session)載入多個，僅供此工作階段使用。每個旗標採用一個路徑。重複旗標以取得更多路徑：`--plugin-dir A --plugin-dir B.zip`。傳遞 plugins 資料夾需要 Claude Code v2.1.265 或更新版本 | `claude --plugin-dir ./my-plugin` |
118| `--plugin-url` | 從 URL 為此工作階段僅擷取 plugin `.zip` 封存。重複旗標以取得多個 plugins，或在單一引用值中傳遞以空格分隔的 URL | `claude --plugin-url https://example.com/plugin.zip` |119| `--plugin-url` | 從 URL 為此工作階段僅擷取 plugin `.zip` 封存。重複旗標以取得多個 plugins，或在單一引用值中傳遞以空格分隔的 URL | `claude --plugin-url https://example.com/plugin.zip` |
119120| `--print`, `-p` | 列印回應而不進行互動模式（請參閱 [Agent SDK 文件](/docs/zh-TW/agent-sdk/overview)以取得程式設計使用詳細資訊） | `claude -p "query"` || `--print`, `-p` | 列印回應而不進行互動模式（請參閱 [Agent SDK 文件](/docs/zh-TW/agent-sdk/overview)以取得程式設計使用詳細資訊）。對於在仍在執行的背景工作階段上 `--resume`，請參閱[恢復工作階段](/docs/zh-TW/sessions#resume-a-running-background-session) | `claude -p "query"` |
120| `--prompt-suggestions` | 在產生提示建議的每個轉後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱[提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |121| `--prompt-suggestions` | 在產生提示建議的每個轉後發出 `prompt_suggestion` 訊息，其中包含預測的下一個使用者提示；非常短的對話可能不會產生任何提示。需要 `--print`、`--output-format stream-json` 和 `--verbose`。請參閱[提示建議](/docs/zh-TW/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |
121| `--ref <branch>` | 使用 `--environment`，根據命名的 ref 而不是本機 `HEAD` 為新工作階段的簽出建立基礎 | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |122| `--ref <branch>` | 使用 `--environment`，根據命名的 ref 而不是本機 `HEAD` 為新工作階段的簽出建立基礎 | `claude -p "Run the smoke test" --environment ccpool_abc123 --ref main` |
122| `--remote` | `--cloud` 的已淘汰別名，包括現有工作階段形式 | `claude --remote "Fix the login bug"` |123| `--remote` | `--cloud` 的已淘汰別名，包括現有工作階段形式 | `claude --remote "Fix the login bug"` |
124| `--remote-control-session-name-prefix <prefix>` | 當未設定明確名稱時，[遠端控制](/docs/zh-TW/remote-control)自動產生工作階段名稱的前置詞。預設為您機器的主機名稱，產生名稱如 `myhost-graceful-unicorn`。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以取得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |125| `--remote-control-session-name-prefix <prefix>` | 當未設定明確名稱時，[遠端控制](/docs/zh-TW/remote-control)自動產生工作階段名稱的前置詞。預設為您機器的主機名稱，產生名稱如 `myhost-graceful-unicorn`。設定 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以取得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |
125| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |126| `--replay-user-messages` | 從 stdin 重新發出使用者訊息回到 stdout 以進行確認。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |
126| `--restricted` | 以受限模式啟動。當評估工具在共用機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具以及 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設集。它也會將內建檔案工具限制在[工作目錄](/docs/zh-TW/permissions#working-directories)、僅載入[受管設定](/docs/zh-TW/managed-settings)和 `--settings`、拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，以及[拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |127| `--restricted` | 以受限模式啟動。當評估工具在共用機器上驅動 `claude` 且 Claude Code 不得執行命令或讀取該機器的使用者和專案設定時使用。Claude Code 會移除執行命令或程式碼的內建工具以及 WebFetch，除非您在 `--tools` 中個別命名它們，而不是透過 `default` 預設集。它也會將內建檔案工具限制在[工作目錄](/docs/zh-TW/permissions#working-directories)、僅載入[受管設定](/docs/zh-TW/managed-settings)和 `--settings`、拒絕 [`bypassPermissions`](/docs/zh-TW/permission-modes#skip-all-checks-with-bypasspermissions-mode)，以及[拒絕從受限工作階段建立雲端工作階段](/docs/zh-TW/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更新版本 | `claude --restricted -p "query"` |
127128| `--resume`, `-r` | 按 ID 或名稱恢復特定工作階段，或顯示互動選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中顯示，標記為 `bg` | `claude --resume auth-refactor` || `--resume`, `-r` | 按 ID 或名稱恢復特定工作階段，或顯示互動選擇器以選擇工作階段。代替 ID，您可以傳遞工作階段 `.jsonl` [文字記錄檔](/docs/zh-TW/sessions#where-transcripts-are-stored)的絕對路徑。選擇器和名稱搜尋包括使用 `/add-dir` 新增此目錄的工作階段。當您傳遞工作階段 ID 時，Claude Code 會搜尋目前專案目錄及其 git worktrees，然後搜尋此機器上的所有其他專案。在 v2.1.223 之前，ID 搜尋僅涵蓋目前專案目錄及其 git worktrees。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中顯示，標記為 `bg`。恢復仍在執行的工作階段[在此終端機中開啟該工作階段](/docs/zh-TW/sessions#resume-a-running-background-session)透過 `claude attach`，您在命令列上傳遞的提示會作為其下一個轉傳送給它。在 v2.1.285 之前，Claude Code 拒絕並列印 `claude attach` 命令以改為執行 | `claude --resume auth-refactor` |
128| `--safe-mode` | 以所有自訂停用開始以疑難排解損壞的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不適用。用於檢查自訂是否觸發[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |129| `--safe-mode` | 以所有自訂停用開始以疑難排解損壞的設定：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理程式、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態列和檔案建議命令、LSP 伺服器和自動記憶不會載入。驗證、模型選擇、內建工具和權限正常運作，這與 [`--bare`](/docs/zh-TW/headless#start-faster-with-bare-mode) 不同。受管設定原則仍適用，包括原則設定的 hooks、狀態列和檔案建議命令；受管 plugins、受管 skills、受管 CLAUDE.md 和原則設定的 MCP 伺服器不適用。用於檢查自訂是否觸發[自動模型回退](/docs/zh-TW/model-config#automatic-model-fallback)。設定 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-TW/env-vars) | `claude --safe-mode` |
129| `--session-id` | 為對話使用特定工作階段 ID（必須是有效的 UUID） | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |130| `--session-id` | 為對話使用特定工作階段 ID（必須是有效的 UUID） | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |
130| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](/docs/zh-TW/agent-view#what-carries-over-when-you-background)和[代理程式團隊](/docs/zh-TW/agent-teams#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |131| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](/docs/zh-TW/agent-view#what-carries-over-when-you-background)和[代理程式團隊](/docs/zh-TW/agent-teams#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |
439 439
440* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。440* **Claude 執行的命令**：雲端環境不會設定自己的命令逾時，因此 Bash 工具的預設值適用。Claude 預設等待前景命令 2 分鐘，最多可要求 10 分鐘。
441 441
442442 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。 當命令達到其[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)時，Claude Code [將其移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。以這種方式移動的命令可以繼續執行最多 30 分鐘，然後 Claude Code 在其[背景時間限制](/docs/zh-TW/tools-reference#time-limit-for-background-commands)處停止它。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為 `1800000` 毫秒以上會延長該限制以及前景預設值。
443* **SessionStart hooks**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。443* **SessionStart hooks**：Claude Code 在 600 秒後取消 `command` hook，除非您在 hook 項目上設定 [`timeout`](/docs/zh-TW/hooks#common-fields)（以秒為單位）。Claude Code 不會對您使用 [`async: true`](/docs/zh-TW/hooks#run-hooks-in-the-background) 執行的 hook 強制執行逾時。
444* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。444* **設定指令碼**：花費超過大約五分鐘的指令碼不會被快取。[指令碼需求](#script-requirements)涵蓋如何保持在該時間以下。
445* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。445* **閒置工作階段**：在幾分鐘沒有活動後，工作階段的 VM 會暫停並保存其檔案，稍後可以回收暫停的 VM。[設定環境變數](#set-environment-variables)描述工作階段在每種情況下會取得什麼，[環境已過期](/docs/zh-TW/claude-code-on-the-web#environment-expired)涵蓋如何重新開啟其 VM 已被回收的工作階段。
132| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |132| `/remote-control` | 使此工作階段可從 claude.ai 進行[遠端控制](/docs/zh-TW/remote-control)。在登出時運行它會列印遠端控制需要 claude.ai 訂閱並告訴您如何登入；在 v2.1.206 之前它報告 `Unknown command: /remote-control`。別名：`/rc` |
133| `/remote-env` | 為您從 CLI 啟動的雲端工作階段選擇預設[雲端環境](/docs/zh-TW/cloud-environments#select-an-environment-from-the-cli) |133| `/remote-env` | 為您從 CLI 啟動的雲端工作階段選擇預設[雲端環境](/docs/zh-TW/cloud-environments#select-an-environment-from-the-cli) |
134| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本。從每個重新命名表面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。一旦不可見字元被移除，如果名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本。如果此機器上的另一個活動工作階段已使用您傳遞的名稱，Claude Code 會改為應用[它的變體](/docs/zh-TW/sessions#name-your-sessions) |134| `/rename [name]` | 重新命名目前工作階段並在提示詞欄上顯示名稱。沒有名稱時，從對話歷史記錄自動生成一個。也可在非互動模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更新版本。從每個重新命名表面，包括 claude.ai 和桌面應用程式，Claude Code 會用空格替換新名稱中的控制和不可見字元，並將名稱上限設為 200 個字元。一旦不可見字元被移除，如果名稱為空，Claude Code 會拒絕它並顯示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字元替換和長度上限需要 Claude Code v2.1.221 或更新版本。如果此機器上的另一個活動工作階段已使用您傳遞的名稱，Claude Code 會改為應用[它的變體](/docs/zh-TW/sessions#name-your-sessions) |
135135| `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中標記為 `bg` 出現；仍在運行的工作階段無法在此恢復，因此從 `claude agents` 附加到它或先在那裡停止它。別名：`/continue` || `/resume [session]` | 按 ID 或名稱恢復對話，或打開工作階段選擇器。[背景工作階段](/docs/zh-TW/agent-view)在選擇器中標記為 `bg` 出現。恢復仍在運行的工作階段，從選擇器或按 ID 或名稱，[打開該工作階段](/docs/zh-TW/sessions#resume-a-running-background-session)：您目前的對話移動到背景，此終端附加到運行中的工作階段。在空提示詞上按 `←` 返回代理檢視，這也列出您留下的對話。在 v2.1.285 之前，Claude Code 拒絕並告訴您使用 `claude attach` 打開工作階段或先在那裡停止它。別名：`/continue` |
136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-TW/code-review#review-a-diff-locally) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的工作量級別和標誌。沒有給定級別時，檢查重複使用您最後輸入的 `low` 到 `max` 級別；有關確切規則，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。對於深度雲端檢查，使用 [`/code-review ultra`](/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub 拉取請求進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多代理引擎 |136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-TW/code-review#review-a-diff-locally) 的別名：檢查目前差異或您傳遞的 PR 編號、分支或路徑，例如 `/review 1234`，並採用相同的工作量級別和標誌。沒有給定級別時，檢查重複使用您最後輸入的 `low` 到 `max` 級別；有關確切規則，請參閱[本地檢查差異](/docs/zh-TW/code-review#review-a-diff-locally)。對於深度雲端檢查，使用 [`/code-review ultra`](/docs/zh-TW/ultrareview)。在 v2.1.223 之前，`/review` 是一個單獨的命令，按編號對 GitHub 拉取請求進行單次通過、唯讀檢查，在運行時不帶引數時列出打開的 PR 以選擇；從 v2.1.186 到 v2.1.201，它運行與 `/code-review medium` 相同的多代理引擎 |
137| `/rewind` | 倒帶對話和/或程式碼到上一個點，或從選定的訊息進行摘要。請參閱[檢查點](/docs/zh-TW/checkpointing)。別名：`/checkpoint`、`/undo` |137| `/rewind` | 倒帶對話和/或程式碼到上一個點，或從選定的訊息進行摘要。請參閱[檢查點](/docs/zh-TW/checkpointing)。別名：`/checkpoint`、`/undo` |
138| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 啟動並驅動您的專案應用程式以查看變更工作，而不僅僅是通過測試。請參閱[運行和驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app) |138| `/run` | **[Skill](/docs/zh-TW/skills#bundled-skills)。** 啟動並驅動您的專案應用程式以查看變更工作，而不僅僅是通過測試。請參閱[運行和驗證您的應用程式](/docs/zh-TW/skills#run-and-verify-your-app) |
967 967
968若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。968若要將 CLI 會話移至 Desktop，請在終端機中執行 `/desktop`。Claude 儲存您的會話並在桌面應用程式中開啟它，然後退出 CLI。此命令在 macOS 和 x64 Windows 上可用，當您使用 Claude 訂閱登入時。它不適用於 API 金鑰驗證或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。
969 969
970從您的 shell，[`claude --desktop`](/docs/zh-TW/cli-reference#cli-flags) 直接開啟 Desktop，無需啟動終端機會話。它需要 Claude Code v2.1.285 或更新版本，並具有與 `/desktop` 相同的平台和登入要求。沒有其他引數時，它會在目前目錄中開啟 Desktop。若要在 Desktop 中開啟現有的 CLI 會話，請為此目錄中最近的對話新增 `--continue`，或使用 `/status` 顯示的會話 ID 新增 `--resume`：
971
972```bash theme={null}
973claude --desktop --resume <session-id>
974```
975
976Claude Code 列印 `Opening session <session-id> in Claude Desktop`，會話在應用程式中開啟，命令退出。會話名稱不能代替 ID。Claude Code 不會移動在另一個終端機中開啟或仍在背景執行的會話。如果未安裝 Claude Desktop，命令會列印下載連結並退出。
977
970您也可以從 Desktop 內部使用 `/resume` 取得 CLI 會話。此命令在本機會話中可用，不在 SSH、WSL 或雲端會話中可用。978您也可以從 Desktop 內部使用 `/resume` 取得 CLI 會話。此命令在本機會話中可用，不在 SSH、WSL 或雲端會話中可用。
971 979
972若要在 Desktop 中繼續終端機會話：980若要在 Desktop 中繼續終端機會話：
3657 無法開啟 Claude Desktop3657 無法開啟 Claude Desktop
3658</h3>3658</h3>
3659 3659
36603660您執行了 [`/desktop`](/docs/zh-TW/desktop#coming-from-the-cli) 或其別名 `/app`，Claude Code 用來開啟 Claude Desktop 的系統命令失敗。工作階段保持在終端中。您執行了 [`/desktop`](/docs/zh-TW/desktop#coming-from-the-cli) 或其別名 `/app` 在工作階段中，或在您的 shell 中執行了 [`claude --desktop`](/docs/zh-TW/cli-reference#cli-flags)，Claude Code 用來開啟 Claude Desktop 的系統命令失敗。在 `/desktop` 後，工作階段保持在終端中；`claude --desktop` 列印訊息而沒有 `Error:` 前綴並以狀態 1 結束。
3661
3662括號中的文字命名失敗的命令，帶有其結束狀態和其錯誤輸出的第一行（如果它產生了）。在 macOS 上該命令是 `open`，如此範例；在 Windows 上它是 `rundll32`：
3661 3663
3662```text theme={null}3664```text theme={null}
36633665Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.
3664```3666```
3665 3667
3666**該怎麼做：**3668**該怎麼做：**
3667 3669
36683670* 自己開啟 Claude Desktop，然後再次執行 `/desktop`* 自己開啟 Claude Desktop，然後再次執行 `/desktop` 或 `claude --desktop`
36693671* 若要讀取該命令的完整錯誤輸出，使用 `/debug` 開啟偵錯日誌，再次執行 `/desktop`，並檢查偵錯日誌* 若要讀取該命令的完整錯誤輸出，使用 `/debug` 開啟偵錯日誌，再次執行 `/desktop`，或執行 `claude --desktop --debug-file <path>`，然後檢查偵錯日誌
3670 3672
36713673在 v2.1.275 之前，訊息是 `Failed to open Claude Desktop. Please try opening it manually.`，沒有說明什麼失敗。在 v2.1.285 之前，訊息以 `Open Claude Desktop and run /desktop again.` 結尾。在 v2.1.275 之前，它是 `Failed to open Claude Desktop. Please try opening it manually.`，沒有說明什麼失敗。
3672 3674
3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3675<h3 id="terminal-setup-left-your-zed-keymap-unchanged">
3674 /terminal-setup 保持您的 Zed 快捷鍵不變3676 /terminal-setup 保持您的 Zed 快捷鍵不變
1938| :- | :- |1938| :- | :- |
1939| `permissionDecision` | `"allow"` 跳過權限提示，除了 [任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，它們需要 [`updatedInput` 與它配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 無論 hook 返回什麼都會被評估 |1939| `permissionDecision` | `"allow"` 跳過權限提示，除了 [任何模式自動核准的動作](/docs/zh-TW/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，它們需要 [`updatedInput` 與它配對](#allow-with-updatedinput)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/docs/zh-TW/permissions#manage-permissions) 無論 hook 返回什麼都會被評估 |
1940| `permissionDecisionReason` | 對於 `"ask"`，顯示給使用者但不顯示 Claude。對於 `"deny"`，顯示給 Claude。對於 `"allow"` 和 `"defer"`，寫入 [debug log](#debug-hooks) 僅 |1940| `permissionDecisionReason` | 對於 `"ask"`，顯示給使用者但不顯示 Claude。對於 `"deny"`，顯示給 Claude。對於 `"allow"` 和 `"defer"`，寫入 [debug log](#debug-hooks) 僅 |
19411941| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 返回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#background-commands)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 || `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此在修改的欄位旁邊包含未變更的欄位。Claude Code 根據您的 hook 返回的輸入評估權限規則和 Bash 命令的 [自動背景資格](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是 Claude 傳送的輸入。與 `"allow"` 結合以自動核准，或與 `"ask"` 結合以向使用者顯示修改的輸入。對於 `"defer"`，忽略 |
1942| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。有關詳細資訊，請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |1942| `additionalContext` | 與工具結果一起新增到 Claude 背景資訊的字串。當 `permissionDecision` 為 `"defer"` 時忽略。有關詳細資訊，請參閱 [為 Claude 新增背景資訊](#add-context-for-claude) |
1943 1943
1944當多個 PreToolUse hooks 返回不同的決定時，優先順序為 `deny` > `defer` > `ask` > `allow`。1944當多個 PreToolUse hooks 返回不同的決定時，優先順序為 `deny` > `defer` > `ask` > `allow`。
346* 提示 Claude Code 在背景執行命令346* 提示 Claude Code 在背景執行命令
347* 按 `Ctrl+B` 將一般 Bash 工具叫用移至背景。Tmux 使用者必須按 `Ctrl+B` 兩次，因為 tmux 的前置鍵。347* 按 `Ctrl+B` 將一般 Bash 工具叫用移至背景。Tmux 使用者必須按 `Ctrl+B` 兩次，因為 tmux 的前置鍵。
348 348
349349當命令在完成前達到逾時時，Claude Code 會自動[將其移至背景](/docs/zh-TW/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 開頭。若要變更命令執行多久後才會發生這種情況，請設定 [Bash 逾時環境變數](/docs/zh-TW/tools-reference#timeout-and-output-limits)。當命令在完成前達到逾時時，Claude Code 會自動[將其移至背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 開頭。若要變更命令執行多久後才會發生這種情況，請設定 [Bash 逾時環境變數](/docs/zh-TW/tools-reference#timeout-and-output-limits)。
350 350
351**主要功能：**351**主要功能：**
352 352
358* 在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，Claude Code 會終止執行中的背景工作，前提是工作階段已閒置至少 30 分鐘且沒有執行任何轉向或子代理。需要 Claude Code v2.1.193 或更新版本358* 在 macOS 和 Linux 上，當作業系統發出記憶體壓力信號時，Claude Code 會終止執行中的背景工作，前提是工作階段已閒置至少 30 分鐘且沒有執行任何轉向或子代理。需要 Claude Code v2.1.193 或更新版本
359 * [偵錯日誌](/docs/zh-TW/debug-your-config)會說明為什麼工作被停止，或為什麼壓力事件讓它們繼續執行359 * [偵錯日誌](/docs/zh-TW/debug-your-config)會說明為什麼工作被停止，或為什麼壓力事件讓它們繼續執行
360 * 將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-TW/env-vars) 設定為 `1` 以關閉記憶體壓力停止360 * 將 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-TW/env-vars) 設定為 `1` 以關閉記憶體壓力停止
361361* 背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：30 分鐘，或 Claude 在啟動背景命令時要求的 `timeout`，最多 2 小時。使用 `Ctrl+B` 等方式在執行時移至背景的命令，從移動時起獲得 30 分鐘。當命令達到其限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動它（如果工作仍需要的話）。兩個環境變數會提高限制（以毫秒為單位），且都不能縮短限制：* 背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：30 分鐘，或 Claude 在啟動背景命令時要求的 `timeout`，最多 2 小時。使用 `Ctrl+B` 等方式在執行時移至背景的命令，從移動時起獲得 30 分鐘。當命令達到其限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動它（如果工作仍需要的話）。若要延長限制，請參閱工具參考中的[提高背景命令的時間限制](/docs/zh-TW/tools-reference#raise-the-time-limit-for-background-commands)
362362 * 將 [`BASH_DEFAULT_TIMEOUT_MS`](/docs/zh-TW/env-vars) 設定為高於 `1800000` 以用該值取代 30 分鐘的預設值，也適用於移動的命令* 由前景[子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的背景命令在該子代理的執行結束時結束，無論是完成、失敗或被中斷；請參閱工具參考中的[背景命令停止時](/docs/zh-TW/tools-reference#when-a-background-command-stops)
363 * 將 [`BASH_MAX_TIMEOUT_MS`](/docs/zh-TW/env-vars) 設定為高於 `7200000` 以提高 2 小時的最大值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 也會以相同方式提高它
364* 由前景[子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的背景命令在該子代理的執行結束時結束，無論是完成、失敗或被中斷；請參閱工具參考中的[背景命令](/docs/zh-TW/tools-reference#background-commands)
365 363
366若要停用所有背景工作功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。詳細資訊請參閱[環境變數](/docs/zh-TW/env-vars)。364若要停用所有背景工作功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。詳細資訊請參閱[環境變數](/docs/zh-TW/env-vars)。
367 365
868 868
869伺服器從捆綁的 manifest 中的 `name` 獲取其名稱。869伺服器從捆綁的 manifest 中的 `name` 獲取其名稱。
870 870
871捆綁的 manifest 可以在 `user_config` 區塊中宣告伺服器需要的設定。具有沒有已儲存值的必需設定的捆綁伺服器不會啟動。`/plugin` **Errors** 標籤顯示 `Bundled MCP server "<name>" was not started: it needs configuration`。
872
873使用者可以透過以下兩種方式之一提供值：
874
875* **在 `/plugin` 中**：在 **Installed** 標籤上選擇外掛程式並選擇 **Configure**
876* **在安裝時，從 shell**：傳遞 [`--config <server>.<key>=<value>`](/docs/zh-TW/plugins/cli-reference#plugin-install) 至 `claude plugin install`。需要 Claude Code v2.1.285 或更新版本，且僅適用於外掛程式內打包的捆綁。
877
871如需傳輸和驗證，請參閱 [MCP](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。878如需傳輸和驗證，請參閱 [MCP](/docs/zh-TW/mcp#plugin-provided-mcp-servers)。
872 879
873<h3 id="lsp-servers">880<h3 id="lsp-servers">
1071 設定對話方塊何時出現1078 設定對話方塊何時出現
1072</h3>1079</h3>
1073 1080
10741081對話方塊僅在互動式 `/plugin` 介面中出現。當使用者執行以下任何操作時，它會為任何尚未設定的選項開啟：對話方塊是互動式 `/plugin` 介面的一部分。當使用者執行以下任何操作時，它會為任何尚未設定的選項開啟：
1075 1082
1076* 在 `/plugin` 中安裝外掛程式1083* 在 `/plugin` 中安裝外掛程式
1077* 在工作階段內執行 `/plugin install <plugin>@<marketplace>`1084* 在工作階段內執行 `/plugin install <plugin>@<marketplace>`
1079 1086
1080若要在任何時間開啟相同的對話方塊，使用者執行 `/plugin configure <plugin>@<marketplace>`。1087若要在任何時間開啟相同的對話方塊，使用者執行 `/plugin configure <plugin>@<marketplace>`。
1081 1088
10821089`claude plugin install` shell 命令從不提示 `userConfig` 值。若要從 shell 設定值，將每個值作為 `--config KEY=VALUE` 傳遞。當選項保持未設定時，命令列印 `userConfig options not yet set` 行，命名兩種設定方式。[`userConfig` 對話方塊從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears) 引用該行。VS Code 擴充功能的 [管理外掛程式對話方塊](/docs/zh-TW/vs-code#install-plugins) 在安裝後會以表單形式要求未設定的選項，外掛程式列上的齒輪圖示會再次開啟表單，顯示每個選項。
1090
1091`claude plugin install` shell 命令從不提示 `userConfig` 值。若要從 shell 設定值，在安裝時將每個值作為 `--config KEY=VALUE` 傳遞，或之後將 JSON 物件管道傳輸到 [`claude plugin configure --values-stdin`](/docs/zh-TW/plugins/cli-reference#plugin-configure)。
1092
1093當選項保持未設定時，`claude plugin install` 列印 `userConfig options not yet set` 行。如需該行的確切文字，請參閱 [The `userConfig` 對話方塊從不出現](/docs/zh-TW/plugins/troubleshooting#the-userconfig-dialog-never-appears)。
1083 1094
1084如需選項欄位、每個值儲存的位置、元件如何參考已儲存的值以及哪些欄位拒絕 `${user_config.*}`，請參閱 [使用者設定](/docs/zh-TW/plugins/manifest-reference#user-configuration)。1095如需選項欄位、每個值儲存的位置、元件如何參考已儲存的值以及哪些欄位拒絕 `${user_config.*}`，請參閱 [使用者設定](/docs/zh-TW/plugins/manifest-reference#user-configuration)。
1085 1096
72 摘要的最後一句告訴您外掛程式在此工作階段中是否可用：72 摘要的最後一句告訴您外掛程式在此工作階段中是否可用：
73 73
74 * **Active now**：`Plugin is now active.` 不需要重新載入。74 * **Active now**：`Plugin is now active.` 不需要重新載入。
75 * **Active, but a server needs setup**：`Plugin is now active.` 後面跟著 `Its bundled MCP server needs configuration before it can start`。外掛程式的 [bundled MCP server](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server) 在您設定其選項之前無法啟動。在 `/plugin` 的 **Installed** 標籤上選擇外掛程式，然後選擇 **Configure** 以設定伺服器的選項。
75 * **Reload needed**：`Run /reload-plugins to activate.` 面板關閉，Claude Code 為您執行該重新載入。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留外掛程式待處理。執行 `/reload-plugins --force` 以無論如何啟動它，這會花費一個未快取的請求。76 * **Reload needed**：`Run /reload-plugins to activate.` 面板關閉，Claude Code 為您執行該重新載入。如果重新載入會 [使提示快取失效](/docs/zh-TW/prompt-caching#enabling-or-disabling-a-plugin)，它會警告並改為保留外掛程式待處理。執行 `/reload-plugins --force` 以無論如何啟動它，這會花費一個未快取的請求。
76 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中開啟 **Errors** 標籤以了解原因，然後請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。77 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中開啟 **Errors** 標籤以了解原因，然後請參閱 [安裝後：外掛程式無法運作](/docs/zh-TW/plugins/troubleshooting#plugin-installed-but-not-working)。
77 </Step>78 </Step>
248私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：249私人市集是您需要認證才能複製的儲存庫中的市集，在 GitHub 或任何其他 git 主機上。您使用與公開市集相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令新增它。Claude Code 使用機器上已有的 git 認證複製它，永遠不會提示，因此每種連接方式都有要求：
249 250
250* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。251* **HTTPS**：您的 git 認證助手適用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 設定的存取有效。互動式提示被抑制，因此您從未驗證過的主機會失敗而不是要求密碼。
251252* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作，因為主機指紋和密碼提示也被抑制。* **SSH**：主機必須已在您的 `known_hosts` 檔案中，金鑰必須在沒有密碼提示的情況下工作。如果您的 git 設定在 `GIT_SSH_COMMAND`、`GIT_SSH` 或您的 git 設定的 `core.sshCommand` 中命名 SSH 程式，Claude Code 會執行該程式。
252* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。253* **GitHub `owner/repo` shorthand**：Claude Code 檢查您的 SSH 金鑰是否驗證到 `github.com`，如果驗證則透過 SSH 複製，如果不驗證則透過 HTTPS 複製。設定 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-TW/env-vars#variables) 以跳過該檢查並始終透過 HTTPS 複製。
253 254
254當您執行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 時，相同的認證適用。255當您執行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 時，相同的認證適用。
288 289
289* 輸入以按名稱或描述篩選。290* 輸入以按名稱或描述篩選。
290* 按 **Space** 啟用或停用選定的外掛程式，按 **f** 將其加入最愛。291* 按 **Space** 啟用或停用選定的外掛程式，按 **f** 將其加入最愛。
291292* 按 **Enter** 開啟外掛程式的詳細資訊。那裡的選單提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。採用設定的外掛程式也提供 **Configure options**。* 按 **Enter** 開啟外掛程式的詳細資訊。
293
294外掛程式的詳細資訊功能表提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。採用設定的外掛程式會出現兩個額外項目，外掛程式可以同時顯示兩者：
295
296* **Configure options**：當外掛程式的資訊清單宣告 [`userConfig` 選項](/docs/zh-TW/plugins/manifest-reference#user-configuration) 時顯示。開啟這些選項的對話框
297* **Configure**：當外掛程式包含 [封裝的 MCP 伺服器](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server) 時顯示。設定該伺服器自己的 `user_config` 設定
292 298
293標籤也可以在 **Managed** 範圍顯示外掛程式。您的組織透過 [受管設定](/docs/zh-TW/settings#settings-files) 安裝了這些，您無法在此啟用、停用或卸載它們。299標籤也可以在 **Managed** 範圍顯示外掛程式。您的組織透過 [受管設定](/docs/zh-TW/settings#settings-files) 安裝了這些，您無法在此啟用、停用或卸載它們。
294 300
201 201
202成功的新增會列印 `Successfully added marketplace: <name>`。202成功的新增會列印 `Successfully added marketplace: <name>`。
203 203
204<h3 id="invalid-git-url">
205 `Invalid git URL`
206</h3>
207
208您新增了市集、安裝了外掛程式，或從 git 位址執行了更新，命令失敗，訊息中顯示 `Invalid git URL`。
209
210Claude Code 在執行 git 之前檢查每個 git 位址。它拒絕其協議不支援的位址。它也拒絕 git 可能讀取為命名不同伺服器或資料夾的位址，而不是位址顯示的位址。
211
212位址後面的文字命名要變更的內容。按照訊息所說重寫位址並再次執行命令。
213
214改為說 `is blocked by enterprise policy` 的拒絕來自您組織的設定。請參閱 [市集來源被企業政策阻止](#marketplace-source-is-blocked-by-enterprise-policy)。
215
204<h3 id="path-does-not-exist">216<h3 id="path-does-not-exist">
205 `Path does not exist: <path>`217 `Path does not exist: <path>`
206</h3>218</h3>
410 422
411`claude plugin install` 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。423`claude plugin install` 在您的 shell 中列印不同的訊息。對於已在目標範圍安裝的外掛程式，它列印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 並以退出代碼 0 退出。如果其快取目錄遺失，相同的命令會重新下載它。
412 424
425<h3 id="plugin-would-share-its-folder">
426 `"<plugin>" was not installed: it would share its folder with "<other>"`
427</h3>
428
429您透過 `claude plugin install`、`/plugin` 或工作階段中的安裝建議安裝了外掛程式，Claude Code 拒絕了它，並顯示此行或 `would share its saved data with`。
430
431被拒絕的外掛程式的 id 和已安裝的外掛程式的 id 對應到磁碟上的相同資料夾：一旦 `.` 和 `@` 被寫成 `-`，它們就是相同的。在 macOS 和 Windows 上，僅在大寫字母中不同的 id 也對應到相同的資料夾。安裝兩者會將一個外掛程式的檔案放在另一個的資料夾中，因此 Claude Code 拒絕，已安裝的外掛程式保留其檔案。
432
433訊息命名了解決方案：
434
435* **其他外掛程式已安裝**：訊息說 `Only one of the two can be installed.` 並命名 `claude plugin uninstall` 命令或 `/plugin` 中的卸載步驟，以移除其他外掛程式。執行它，然後再次安裝。對於卸載移除的內容，請參閱 [卸載刪除和保留的內容](/docs/zh-TW/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)。
436* **兩個 id 在一次安裝中到達**，例如外掛程式及其需要的依賴項：沒有安裝順序可以幫助。只有列出這兩個外掛程式的市集的維護者可以修復它，方法是重新命名其中一個。當兩者來自不同的市集時，任一個的維護者都可以。
437
413<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">438<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">
414 `This plugin uses a source type your Claude Code version does not support`439 `This plugin uses a source type your Claude Code version does not support`
415</h3>440</h3>
790* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 選項未設定。執行 `/plugin configure <plugin>` 以設定它815* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 選項未設定。執行 `/plugin configure <plugin>` 以設定它
791* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 `url` 或 `headersHelper`，或如果外掛程式不是您的，向外掛程式的作者報告。`headersHelper` 情況在 [外掛程式命令參考 user\_config](/docs/zh-TW/errors#plugin-command-references-user-config) 下有自己的條目816* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：外掛程式自己的配置有問題。修復您外掛程式的 MCP 配置中的 `url` 或 `headersHelper`，或如果外掛程式不是您的，向外掛程式的作者報告。`headersHelper` 情況在 [外掛程式命令參考 user\_config](/docs/zh-TW/errors#plugin-command-references-user-config) 下有自己的條目
792 817
818<h4 id="bundled-mcp-server-name-was-not-started-it-needs-configuration">
819 `Bundled MCP server "<name>" was not started: it needs configuration`
820</h4>
821
822外掛程式包括伺服器作為 [MCPB 套件](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server)，宣告 `user_config`，且必需的設定沒有已保存的值或已保存的值無法通過套件自己的驗證，因此 Claude Code 跳過啟動伺服器。外掛程式的其餘部分有效。
823
824在 `/plugin` 的 **Installed** 標籤上選擇外掛程式，並選擇 **Configure** 以提供值。保存後，`/plugin` 顯示 `Configuration saved.` 並關閉，Claude Code 重新載入外掛程式，如 [管理已安裝的外掛程式](/docs/zh-TW/plugins/install#manage-installed-plugins) 下所述。伺服器在該重新載入應用後啟動。在 v2.1.285 之前，Claude Code 跳過伺服器而不顯示此行。
825
793<h4 id="server-is-configured-but-never-connects">826<h4 id="server-is-configured-but-never-connects">
794 Server is configured but never connects827 Server is configured but never connects
795</h4>828</h4>
934 967
935您的外掛程式宣告 `userConfig` 選項，但安裝時不會出現設定對話框。968您的外掛程式宣告 `userConfig` 選項，但安裝時不會出現設定對話框。
936 969
937970互動式安裝會顯示對話框，而 shell 命令改為將值作為旗標：安裝是否要求這些值取決於您在何處執行它：
938 971
939* **在工作階段中的 `/plugin install`，或 `/plugin` 中的 Discover 標籤**：對話框是此互動式安裝的一部分972* **在工作階段中的 `/plugin install`，或 `/plugin` 中的 Discover 標籤**：對話框是此互動式安裝的一部分
973* **VS Code 擴充功能的管理外掛程式對話框**：在安裝後以表單形式要求未設定的選項。在 v2.1.285 之前，在該處安裝不會顯示選項表單，因此請使用 `/plugin configure <plugin>@<marketplace>` 從終端機工作階段設定值
940* **在您的 shell 中的 `claude plugin install`**：永遠不會提示 `userConfig` 值。它會儲存您傳遞的任何 `--config KEY=VALUE` 值，當選項保持未設定時，它會列印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 當任何未設定的選項是必需的時，`(M required)` 跟隨 `not yet set`。974* **在您的 shell 中的 `claude plugin install`**：永遠不會提示 `userConfig` 值。它會儲存您傳遞的任何 `--config KEY=VALUE` 值，當選項保持未設定時，它會列印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 當任何未設定的選項是必需的時，`(M required)` 跟隨 `not yet set`。
941 975
942如果您從 shell 安裝，請使用 `--config` 傳遞值，每個選項一個旗標：976如果您從 shell 安裝，請使用 `--config` 傳遞值，每個選項一個旗標：
945claude plugin install my-plugin@my-marketplace --config api_url=https://example.com979claude plugin install my-plugin@my-marketplace --config api_url=https://example.com
946```980```
947 981
948982當每個選項都設定時，安裝輸出不會包含 `not yet set` 行。若要之後改為開啟對話框，請在工作階段中執行 `/plugin configure my-plugin@my-marketplace`。當每個選項都設定時，安裝輸出不會包含 `not yet set` 行。
983
984若要之後改為開啟對話框，請在工作階段中執行 `/plugin configure my-plugin@my-marketplace`。從 shell，[`claude plugin configure`](/docs/zh-TW/plugins/cli-reference#plugin-configure) 顯示哪些選項仍未設定，並儲存在 stdin 上管道傳入的值。它需要 Claude Code v2.1.285 或更新版本。
949 985
950如果您傳遞資訊清單未宣告的 `--config` 鍵，外掛程式仍會安裝，命令會列印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 後面跟著外掛程式確實宣告的鍵。986如果您傳遞資訊清單未宣告的 `--config` 鍵，外掛程式仍會安裝，命令會列印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 後面跟著外掛程式確實宣告的鍵。
951 987
988對於運送[MCPB 套件檔案](/docs/zh-TW/plugins/components#include-a-packaged-mcpb-server)的外掛程式，該檔案宣告其自身的 `user_config`，訊息改為讀取 `isn't declared in this plugin's userConfig or by its bundled MCP servers.`，已知的鍵包括該伺服器的鍵，寫成 `<server>.<key>`。資訊清單按 URL 參考的套件在安裝時不會被讀取，因此其鍵不會被列出，訊息會說在 `/plugin` 中設定它。設定 `<server>.<key>` 鍵需要 Claude Code v2.1.285 或更新版本。
989
952<h3 id="claude-plugin-validate-reports-errors">990<h3 id="claude-plugin-validate-reports-errors">
953 `claude plugin validate` 報告錯誤991 `claude plugin validate` 報告錯誤
954</h3>992</h3>
29 29
30`claude --continue` 會開啟已完成的[背景 session](/docs/zh-TW/agent-view)，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在那裡執行，Claude Code 會以 `Your most recent conversation is running in the background` 和該 session 的 ID 退出。從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到 session，或執行 `claude --resume` 以選擇另一個。30`claude --continue` 會開啟已完成的[背景 session](/docs/zh-TW/agent-view)，但不會開啟仍在執行的 session；開啟已完成的背景 sessions 需要 Claude Code v2.1.257 或更新版本。如果您最近的對話是您[移到背景](/docs/zh-TW/agent-view#send-the-session-to-the-background)的對話，且它仍在那裡執行，Claude Code 會以 `Your most recent conversation is running in the background` 和該 session 的 ID 退出。從 [`claude agents`](/docs/zh-TW/agent-view#attach-to-a-session) 附加到 session，或執行 `claude --resume` 以選擇另一個。
31 31
32<span id="resume-a-running-background-session" />
33
34當您使用 `claude --resume` 或 `/resume` 恢復的對話屬於仍在執行的[背景 session](/docs/zh-TW/agent-view) 時，Claude Code 會開啟執行中的 session 本身。在命令列上使用 `--bg` 時，恢復是[背景分派](/docs/zh-TW/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 會拒絕並告訴您使用 `claude attach <id>` 開啟 session，或先使用 `claude stop <id>` 停止它。
35
36* **從您的 shell**：`claude --resume <session>` 在同一終端機中對該 session 執行 [`claude attach`](/docs/zh-TW/agent-view#attach-to-a-session)，而不是載入文字記錄本身。您在命令列上傳遞的提示，如 `claude --resume <session> "check the tests too"`，會先作為該 session 的下一個輪次進行。Claude Code 會列印 `Sent your prompt to the background session (<id>); opening it…` 然後附加。在終端機上輸入的 `claude -p --resume <session> "prompt"` 也會執行相同操作，因此 `-p` 不會保持該執行非互動式。
37
38 當命令列具有以下任何情況時，Claude Code 不會開啟 session：
39
40 * 管道或重新導向的輸入或輸出
41 * 設定 session 的旗標，例如 `--permission-mode`、`--model` 或 `--settings`
42 * 讀取輸出的旗標，例如 `--output-format json` 或 `--json-schema`
43 * 限制或倒帶執行的旗標，例如 `--max-turns` 或 `--max-budget-usd`
44
45 使用這些中的任何一個，或當[代理檢視已關閉](/docs/zh-TW/agent-view#turn-off-agent-view)時，Claude Code 不會傳送任何內容，並以狀態 1 退出，列印 session 在背景執行以及開啟它的 `claude attach <id>` 命令，或當它無法確定 ID 時告訴您在 `claude agents` 中找到它。新增 `--fork-session` 以恢復對話的副本。要在您自己的 session 中繼續對話本身，並套用您的旗標，請執行 `claude stop <id>`，然後重複該命令。
46
47 以 `/` 或 `!` 開頭的提示不會被傳送，當 session 等待您回答問題時也不會傳送任何提示。在這兩種情況下，Claude Code 都不會開啟 session，訊息會包含 `Your prompt was not sent to it` 以及原因。
48* **從 session 內**：`/resume` 將您目前的對話移到背景，並將此終端機附加到執行中的 session，列印 `Opening "<title>", running in the background (<id>)`。在空提示上按 `←` 以返回代理檢視，這也會列出您留下的對話。當目前的對話無法移到背景時（例如因為您已附加到背景 session 或 session 持久性已關閉），`/resume` 會列印要執行的 `claude attach` 命令。
49
32您可以從任何目錄執行 `claude --resume <session-id>`：Claude Code 會先在目前專案目錄及其 git worktrees 中查找 ID，然後在此機器上的所有其他專案中查找，因此它會找到在其他地方啟動或使用 [`/cd`](/docs/zh-TW/commands) 移動的 session。跨專案搜尋只有在恰好一個其他專案持有該 ID 的訊息文字記錄時才會解析 ID，因此手動複製的重複項會導致 Claude Code 報告找不到，而不是恢復任意副本。如果沒有儲存的 session 符合該 ID，Claude Code 會報告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktrees，因此您必須從 session 最後工作的目錄恢復。50您可以從任何目錄執行 `claude --resume <session-id>`：Claude Code 會先在目前專案目錄及其 git worktrees 中查找 ID，然後在此機器上的所有其他專案中查找，因此它會找到在其他地方啟動或使用 [`/cd`](/docs/zh-TW/commands) 移動的 session。跨專案搜尋只有在恰好一個其他專案持有該 ID 的訊息文字記錄時才會解析 ID，因此手動複製的重複項會導致 Claude Code 報告找不到，而不是恢復任意副本。如果沒有儲存的 session 符合該 ID，Claude Code 會報告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查詢會停在目前專案目錄及其 git worktrees，因此您必須從 session 最後工作的目錄恢復。
33 51
34<h3 id="what-a-resumed-session-restores">52<h3 id="what-a-resumed-session-restores">
35 恢復的 session 會復原什麼53 恢復的 session 會復原什麼
36</h3>54</h3>
37 55
3856恢復的 session 會復原對話以及儲存在其中的狀態：當 Claude Code 從其文字記錄載入對話時，恢復的 session 會復原對話以及儲存在其中的狀態：
39 57
40* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。58* 對話歷史記錄：完整歷史記錄，包括工具呼叫和結果。當前一個程序結束時仍在執行的工具（例如在當機中），在您恢復時不會完成或再次執行；Claude 會看到呼叫標記為在其結果被記錄之前被切斷，並被告知在再次執行之前檢查它是否生效，除非設定了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-TW/env-vars#variables)。在 v2.1.281 之前，Claude Code 會從對話中刪除被切斷的呼叫，或將其顯示為您中斷的呼叫。
41* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。59* 模型：session 會在其使用的模型上繼續。當模型已被淘汰或不被 `availableModels` 允許時，模型不會被復原；當 `--model` 旗標或 `ANTHROPIC_MODEL` 系列環境變數在啟動時選擇一個時；或在使用提供者特定部署 ID 的提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-TW/third-party-integrations)；請參閱[模型設定](/docs/zh-TW/model-config#setting-your-model)以了解解析順序。
51 恢復時的權限模式69 恢復時的權限模式
52</h4>70</h4>
53 71
5472Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復：Claude Code 啟動恢復的 session 所在的權限模式取決於您如何恢復。下面的情況適用於 Claude Code 從其文字記錄載入對話時；當您[開啟仍在執行的背景 session](#resume-a-running-background-session) 時，該 session 會保持它所在的權限模式。
55 73
56* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。74* 終端機：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（當名稱符合一個 session 時），不帶 `-p`。Claude Code 會復原 session 所在的權限模式，除了表格中的情況。傳遞 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆蓋復原的模式。
57* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。75* 非互動式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 會在新 `claude -p` 執行會啟動的權限模式中啟動執行，除了在[下面的條件](#resume-in-plan-mode-with-p)下以 Plan Mode 結束的 session 會在 Plan Mode 中恢復。
740 740
741* **工作目錄**：Claude Code 在工作階段 shell 的目前工作目錄中執行每個命令。當 Claude 執行 `cd` 時，該目錄會移動。在必須每次都以相同方式解析的路徑中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。741* **工作目錄**：Claude Code 在工作階段 shell 的目前工作目錄中執行每個命令。當 Claude 執行 `cd` 時，該目錄會移動。在必須每次都以相同方式解析的路徑中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。
742* **stderr**：使用預設 `bash` shell，Claude Code 會將 stderr 合併到 stdout。命令寫入 stderr 的任何內容都會出現在注入的文字中。742* **stderr**：使用預設 `bash` shell，Claude Code 會將 stderr 合併到 stdout。命令寫入 stderr 的任何內容都會出現在注入的文字中。
743743* **逾時**：每個命令在 Bash 工具的預設 2 分鐘[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)下執行。當 Bash 工具[將逾時命令移到背景](/docs/zh-TW/tools-reference#background-commands)時，技能仍會呈現。注入的文字會報告移動並命名背景工作和收集命令輸出的檔案。當命令是 Bash 工具永遠不會自動背景執行的命令時，Claude Code 會在逾時時終止它。該失敗會[中止呼叫](#when-an-injected-command-fails)。* **逾時**：每個命令在 Bash 工具的預設 2 分鐘[逾時](/docs/zh-TW/tools-reference#timeout-and-output-limits)下執行。當 Bash 工具[將逾時命令移到背景](/docs/zh-TW/tools-reference#foreground-commands-that-move-to-the-background)時，技能仍會呈現。注入的文字會報告移動並命名背景工作和收集命令輸出的檔案。當命令是 Bash 工具永遠不會自動背景執行的命令時，Claude Code 會在逾時時終止它。該失敗會[中止呼叫](#when-an-injected-command-fails)。
744* **輸出大小**：超過 Bash 工具內聯上限的輸出會作為檔案路徑加上簡短預覽到達，而不是截斷的文字。[輸出限制](/docs/zh-TW/tools-reference#output-limits)涵蓋上限以及如何調整每個邊界。744* **輸出大小**：超過 Bash 工具內聯上限的輸出會作為檔案路徑加上簡短預覽到達，而不是截斷的文字。[輸出限制](/docs/zh-TW/tools-reference#output-limits)涵蓋上限以及如何調整每個邊界。
745 745
746PowerShell 工具對其執行的命令應用相同的逾時、背景執行和輸出上限行為。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)部分以了解其具體內容。746PowerShell 工具對其執行的命令應用相同的逾時、背景執行和輸出上限行為。請參閱 [PowerShell 工具](/docs/zh-TW/tools-reference#powershell-tool)部分以了解其具體內容。
20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。20以下是一個[多行狀態列](#display-multiple-lines)的範例，在第一行顯示 git 資訊，在第二行顯示顏色編碼的 context 列。
21 21
22<Frame>22<Frame>
2323 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="776" height="212" data-path="images/statusline-multiline.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="1224" height="262" data-path="images/statusline-multiline.png" />
24</Frame>24</Frame>
25 25
26本頁面介紹[設定基本狀態列](#set-up-a-status-line)、說明[資料如何從 Claude Code 流向您的指令碼](#how-status-lines-work)、列出[您可以顯示的所有欄位](#available-data)，並提供[常見模式的現成範例](#examples)，例如 git 狀態、成本追蹤和進度列。26本頁面介紹[設定基本狀態列](#set-up-a-status-line)、說明[資料如何從 Claude Code 流向您的指令碼](#how-status-lines-work)、列出[您可以顯示的所有欄位](#available-data)，並提供[常見模式的現成範例](#examples)，例如 git 狀態、成本追蹤和進度列。
93這些範例使用 Bash 指令碼，適用於 macOS 和 Linux。在 Windows 上，請參閱 [Windows 設定](#windows-configuration)以取得 PowerShell 和 Git Bash 範例。93這些範例使用 Bash 指令碼，適用於 macOS 和 Linux。在 Windows 上，請參閱 [Windows 設定](#windows-configuration)以取得 PowerShell 和 Git Bash 範例。
94 94
95<Frame>95<Frame>
9696 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-quickstart.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=696445e59ca0059213250651ad23db6b" alt="狀態列顯示模型名稱、目錄和 context 百分比" width="726" height="164" data-path="images/statusline-quickstart.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-quickstart.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=88a7eab9c1038dd098ee8e284d96b7e6" alt="狀態列顯示模型名稱、目錄和 context 百分比" width="1224" height="224" data-path="images/statusline-quickstart.png" />
97</Frame>97</Frame>
98 98
99<Steps>99<Steps>
444顯示目前模型和 context window 使用情況，帶有視覺進度列。每個指令碼從 stdin 讀取 JSON，提取 `used_percentage` 欄位，並建立一個 10 字元的列，其中填充的塊（▓）代表使用情況：444顯示目前模型和 context window 使用情況，帶有視覺進度列。每個指令碼從 stdin 讀取 JSON，提取 `used_percentage` 欄位，並建立一個 10 字元的列，其中填充的塊（▓）代表使用情況：
445 445
446<Frame>446<Frame>
447447 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-context-window-usage.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=15b58ab3602f036939145dde3165c6f7" alt="狀態列顯示模型名稱和帶有百分比的進度列" width="448" height="152" data-path="images/statusline-context-window-usage.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-context-window-usage.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f3918a549912dc47e90f2b69e68bc847" alt="狀態列顯示模型名稱和帶有百分比的進度列" width="1224" height="224" data-path="images/statusline-context-window-usage.png" />
448</Frame>448</Frame>
449 449
450<CodeGroup>450<CodeGroup>
513顯示 git 分支，帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示終端顏色：`\033[32m` 是綠色，`\033[33m` 是黃色，`\033[0m` 重設為預設值。513顯示 git 分支，帶有暫存和修改檔案的顏色編碼指示器。此指令碼使用 [ANSI 逃逸碼](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示終端顏色：`\033[32m` 是綠色，`\033[33m` 是黃色，`\033[0m` 重設為預設值。
514 514
515<Frame>515<Frame>
516516 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-git-context.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e656f34f90d1d9a1d0e220988914345f" alt="狀態列顯示模型、目錄、git 分支和暫存和修改檔案的彩色指示器" width="742" height="178" data-path="images/statusline-git-context.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-git-context.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f13c190724d9ec7188c17cd2f98b7bf4" alt="狀態列顯示模型、目錄、git 分支和暫存和修改檔案的彩色指示器" width="1224" height="224" data-path="images/statusline-git-context.png" />
517</Frame>517</Frame>
518 518
519每個指令碼檢查目前目錄是否是 git 儲存庫，計算暫存和修改檔案，並顯示顏色編碼的指示器：519每個指令碼檢查目前目錄是否是 git 儲存庫，計算暫存和修改檔案，並顯示顏色編碼的指示器：
611每個指令碼將成本格式化為貨幣，並將毫秒轉換為分鐘和秒：611每個指令碼將成本格式化為貨幣，並將毫秒轉換為分鐘和秒：
612 612
613<Frame>613<Frame>
614614 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-cost-tracking.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e3444a51fe6f3440c134bd5f1f08ad29" alt="狀態列顯示模型名稱、工作階段成本和持續時間" width="588" height="180" data-path="images/statusline-cost-tracking.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-cost-tracking.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=925f7024c3b38be0f0eca63564bfb52f" alt="狀態列顯示模型名稱、工作階段成本和持續時間" width="1224" height="224" data-path="images/statusline-cost-tracking.png" />
615</Frame>615</Frame>
616 616
617<CodeGroup>617<CodeGroup>
672您的指令碼可以輸出多行以建立更豐富的顯示。672您的指令碼可以輸出多行以建立更豐富的顯示。
673 673
674<Frame>674<Frame>
675675 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="776" height="212" data-path="images/statusline-multiline.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="多行狀態列，在第一行顯示模型名稱、目錄、git 分支，在第二行顯示 context 使用進度列、成本和持續時間" width="1224" height="262" data-path="images/statusline-multiline.png" />
676</Frame>676</Frame>
677 677
678此範例結合了多種技術：基於閾值的顏色（70% 以下為綠色，70-89% 為黃色，90%+ 為紅色）、進度列和 git 分支資訊。每個 `print` 或 `echo` 陳述式建立單獨的行：678此範例結合了多種技術：基於閾值的顏色（70% 以下為綠色，70-89% 為黃色，90%+ 為紅色）、進度列和 git 分支資訊。每個 `print` 或 `echo` 陳述式建立單獨的行：
781此範例建立指向您的 GitHub 儲存庫的可點擊連結。按住 Cmd（macOS）或 Ctrl（Windows/Linux）並點擊以在瀏覽器中開啟連結。781此範例建立指向您的 GitHub 儲存庫的可點擊連結。按住 Cmd（macOS）或 Ctrl（Windows/Linux）並點擊以在瀏覽器中開啟連結。
782 782
783<Frame>783<Frame>
784784 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-links.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=4bcc6e7deb7cf52f41ab85a219b52661" alt="狀態列顯示指向 GitHub 儲存庫的可點擊連結" width="726" height="198" data-path="images/statusline-links.png" /> <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-links.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=4778a144a28cb498c99d5fa018bb374a" alt="狀態列顯示指向 GitHub 儲存庫的可點擊連結" width="1224" height="224" data-path="images/statusline-links.png" />
785</Frame>785</Frame>
786 786
787每個指令碼取得 git 遠端 URL，將 SSH 格式轉換為 HTTPS，並將儲存庫名稱包裝在 OSC 8 逃逸碼中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解釋反斜杠逃逸：787每個指令碼取得 git 遠端 URL，將 SSH 格式轉換為 HTTPS，並將儲存庫名稱包裝在 OSC 8 逃逸碼中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解釋反斜杠逃逸：
174* `BASH_DEFAULT_TIMEOUT_MS` — 當 Claude 不傳遞逾時時的預設值；預設為兩分鐘174* `BASH_DEFAULT_TIMEOUT_MS` — 當 Claude 不傳遞逾時時的預設值；預設為兩分鐘
175* `BASH_MAX_TIMEOUT_MS` — 使用預設值時，設定上限以限制 Claude 要求的任何內容：有效上限是兩者中較大的，預設為十分鐘175* `BASH_MAX_TIMEOUT_MS` — 使用預設值時，設定上限以限制 Claude 要求的任何內容：有效上限是兩者中較大的，預設為十分鐘
176 176
177177對於 Claude 在背景啟動的命令，`timeout` 改為設定命令在背景執行的時間長度，其中單獨的預設值和最大值在[背景命令](#background-commands)下描述。[PowerShell 工具](#powershell-tool)遵循相同的逾時規則並讀取相同的兩個變數。對於 Claude 在背景啟動的命令，`timeout` 改為設定命令在背景執行的時間長度，其中單獨的預設值和最大值在[背景命令時間限制](#time-limit-for-background-commands)下描述。[PowerShell 工具](#powershell-tool)遵循相同的逾時規則並讀取相同的兩個變數。
178 178
179<h4 id="output-limits">179<h4 id="output-limits">
180 輸出限制180 輸出限制
199 199
200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景工作啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。200對於長時間執行的程序（例如開發伺服器或監視建置），Claude 可以設定 `run_in_background: true` 以將命令作為背景工作啟動並在其執行時繼續工作。使用 `/tasks` 列出並停止背景工作。在您從那裡停止一個後，或從連接的用戶端（例如桌面應用程式）停止後，Claude 會繼續而不是等待。如果子代理啟動了命令，則是該子代理繼續。
201 201
202202[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景子代理啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其時間限制。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。<h4 id="when-a-background-command-stops">
203 背景命令何時停止
204</h4>
205
206[前景子代理](/docs/zh-TW/sub-agents#run-subagents-in-foreground-or-background)啟動的命令在該子代理的執行結束時停止，無論它完成、失敗或被中斷。主對話或背景子代理啟動的命令在最終回應後繼續執行，直到它退出、被停止或達到其[時間限制](#time-limit-for-background-commands)。在使用 `-p` 旗標的非互動模式中，[背景命令在執行的最終結果後不久結束](/docs/zh-TW/headless#background-tasks-at-exit)。
207
208<h4 id="time-limit-for-background-commands">
209 背景命令的時間限制
210</h4>
203 211
204背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：212背景 Bash 和 PowerShell 命令有時間限制，從命令進入背景的時刻開始計算：
205 213
206* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時214* Claude 在背景啟動的命令獲得 30 分鐘，或 Claude 使用 `run_in_background` 傳遞的 `timeout`，最多 2 小時
207* 在前景啟動然後移至背景的命令，例如使用 `Ctrl+B` 或在其逾時時，從移動時獲得 30 分鐘215* 在前景啟動然後移至背景的命令，例如使用 `Ctrl+B` 或在其逾時時，從移動時獲得 30 分鐘
208 216
217當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。
218
219<h4 id="raise-the-time-limit-for-background-commands">
220 提高背景命令的時間限制
221</h4>
222
209兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留 30 分鐘的預設值和 2 小時的最大值。223兩個[環境變數](/docs/zh-TW/env-vars)提高這些限制，對於 Bash 和 PowerShell 命令一樣。兩者都採用毫秒，且都不能縮短限制：較低的值會保留 30 分鐘的預設值和 2 小時的最大值。
210 224
211* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令225* 將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `1800000` 以用該值替換 30 分鐘的預設值，無論是對於 Claude 啟動時不帶 `timeout` 的命令還是對於移動的命令
212* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值226* 將 `BASH_MAX_TIMEOUT_MS` 設定為高於 `7200000` 以將 2 小時的最大值提高到該值。將 `BASH_DEFAULT_TIMEOUT_MS` 設定為高於 `7200000` 以相同方式提高最大值
213 227
214228當背景命令達到其時間限制時，Claude Code 會停止它並告訴 Claude 原因，Claude 可以使用更長的 `timeout` 重新啟動命令，如果工作仍然需要的話。停止通知讀作 `Background command "<description>" was stopped after reaching its background time limit`。<h4 id="foreground-commands-that-move-to-the-background">
229 移至背景的前景命令
230</h4>
215 231
216232當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的時間限制從移動時開始計算，前景子代理的移動命令仍然在該子代理的執行結束時停止。當前景命令在未完成的情況下達到其逾時時，Claude Code 會將其移至背景而不是停止它，除非命令以 `sleep` 開頭。移動的命令的[時間限制](#time-limit-for-background-commands)從移動時開始計算，前景子代理的移動命令仍然在該子代理的執行結束時停止。
217 233
218設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。234設定 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-TW/env-vars#variables) 會停用自動背景化以及其餘的背景工作功能。
219 235
362 362
363在 Plugins 標籤中：363在 Plugins 標籤中：
364 364
365365* **已安裝的 plugins** 顯示在頂部，並帶有切換開關以啟用或停用它們* **已安裝的 plugins** 顯示在頂部，並帶有切換開關以啟用或停用它們。
366 * 如果您關閉您專案的共享 `.claude/settings.json` 開啟的 plugin，擴充功能會先詢問：**為我停用**只為您關閉它，而**為所有人停用**會變更共享檔案。
366* **可用的 plugins** 來自您設定的 marketplaces，顯示在下方367* **可用的 plugins** 來自您設定的 marketplaces，顯示在下方
367* 搜尋以按名稱或描述篩選 plugins368* 搜尋以按名稱或描述篩選 plugins
368* 點擊任何可用 plugin 上的**安裝**369* 點擊任何可用 plugin 上的**安裝**
373* **為此專案安裝**：與專案協作者共享（專案範圍）374* **為此專案安裝**：與專案協作者共享（專案範圍）
374* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）375* **本機安裝**：僅供您使用，僅在此儲存庫中（本機範圍）
375 376
377安裝完成後，表單會要求任何尚未設定的 plugin [設定選項](/docs/zh-TW/plugins/components#user-configuration)。若要稍後檢閱或變更選項，請點擊 plugin 列上的齒輪圖示。
378
379敏感文字欄位會被遮罩，您之前儲存的密碼會顯示 **(未變更)**。將欄位留空以保留儲存的值。
380
381儲存變更後，開啟的工作階段會重新載入其 plugins，對話框會顯示**重新啟動 Claude 以套用 plugin 變更**。
382
383<h3 id="uninstall-plugins">
384 解除安裝 plugins
385</h3>
386
387每個已安裝的列都會命名它安裝的[範圍](/docs/zh-TW/plugins/install#choose-an-install-scope)。若要解除安裝該安裝，請點擊列的垃圾桶圖示。暗淡的垃圾桶圖示標記您無法從此工作區解除安裝的列，例如您的組織管理的 plugin 或為另一個專案安裝的 plugin。
388
389擴充功能在兩種情況下會先詢問：
390
391* **您專案的共享 `.claude/settings.json` 開啟的 plugin**：選擇**為我停用**，這會為您的協作者保留已安裝的 plugin，或**為所有人解除安裝**，這會移除專案的安裝並使用 [`--keep-data`](/docs/zh-TW/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)，因此 plugin 的已儲存資料目錄會保留。如果您已經為自己關閉了 plugin，垃圾桶圖示會移除您自己的安裝而不會出現問題。
392* **否則，具有已儲存資料的 plugin 的最後一個安裝**：選擇是否保留或刪除資料；**保留**是預設值
393
376<h3 id="share-a-plugin-install-link">394<h3 id="share-a-plugin-install-link">
377 分享 plugin 安裝連結395 分享 plugin 安裝連結
378</h3>396</h3>
407 425
408* 輸入 GitHub 儲存庫、URL 或本機路徑以新增 marketplace426* 輸入 GitHub 儲存庫、URL 或本機路徑以新增 marketplace
409* 點擊重新整理圖示以更新 marketplace 的 plugin 清單427* 點擊重新整理圖示以更新 marketplace 的 plugin 清單
410428* 點擊垃圾桶圖示以移除 marketplace* 點擊垃圾桶圖示以移除 marketplace。移除它會[解除安裝您從中安裝的每個 plugin](/docs/zh-TW/plugins/install#manage-marketplaces)，因此確認會先命名這些 plugins
429
430您在對話框中進行的 plugin 變更會立即套用到該 VS Code 視窗中開啟的 Claude Code 工作階段。
411 431
412432您在對話框中進行的 plugin 變更會立即套用到該 VS Code 視窗中開啟的 Claude Code 工作階段。如果您開啟對話框的工作階段無法重新載入其 plugins，對話框會提供重試或在該工作階段中重新啟動 Claude 的選項。如果您開啟對話框的工作階段無法重新載入其 plugins，對話框會提供重試或在該工作階段中重新啟動 Claude 的選項。
413 433
414<Note>434<Note>
415 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。435 VS Code 中的 plugin 管理在幕後使用相同的 CLI 命令。您在擴充功能中設定的 plugins 和 marketplaces 也可在 CLI 中使用，反之亦然。
