對話中途系統訊息

系統指令通常位於頂層的 system 欄位中，排在對話中所有訊息之前。這個位置非常適合 prompt caching（提示快取）：系統提示是穩定前綴的一部分，因此後續的對話回合都能命中快取。但對於您在會話進行到一半才發現需要的指令來說，這個位置並不理想，因為編輯頂層 system 欄位會改變提示的最開頭部分，並使其後所有內容的快取失效。

對話中途系統訊息彌補了這個缺口。您可以在對話中新指令變得相關的位置附加一個 {"role": "system"} 訊息，而不是編輯頂層 system 欄位。快取的前綴保持不變，因此下一個請求仍然可以從快取中讀取，而新指令仍會被當作系統指令套用，而非普通的使用者文字。

何時使用對話中途系統訊息

提示快取會依序對請求前綴進行雜湊：先是 tools，然後是 system，最後是 messages。快取命中要求前綴與最近的某個請求完全相符，逐位元組一致，直到快取斷點為止。

這種排序意味著頂層 system 欄位位於雜湊前綴的最開頭附近。對它的任何更改，即使只是附加一句話，都會產生不同的雜湊值，導致請求無法命中系統提示及其後所有已快取訊息的快取。

對話中途系統訊息讓您可以將指令新增到訊息歷史的末尾。新指令之前的所有內容都保持不變，因此現有的快取條目仍然匹配，只有新訊息會被當作全新輸入處理。

以下是幾種適用的情境：

• 會話中途的政策或角色變更。 一個長時間的代理會話在數十個已快取的回合之後需要新的約束（「從現在開始，所有 SQL 都寫成參數化查詢」）。將其新增到頂層 system 欄位會導致整個歷史記錄被重新處理。
• 必須具有權威性的每回合上下文。 您想要以系統層級的權重注入時效性說明、會話截止時間或工具可用性變更，而這些內容變化太頻繁，不適合放在快取的前綴中。
• 您的應用程式觀察到的狀態變化。 您的應用程式注意到某些 Claude 應該視為操作者層級事實的情況：磁碟上的檔案已變更、使用者切換了自動核准設定、可用工具已變更，或剩餘的 token 預算降到了某個閾值以下。
• 不應中斷代理迴圈的使用者輸入。 使用者在 Claude 仍在為前一個請求執行工具時輸入了後續內容。在下一個工具結果之後以系統訊息的形式轉發該輸入，可以讓 Claude 將新輸入整合到正在進行的工作中，而不是將其視為需要切換處理的全新請求。請參閱下方的工具結果之後的放置位置。
• 授予常設權限的模式切換。 會話層級的模式可以使用對話中途系統訊息來授予對某項高成本功能的常設同意，例如自動啟動多代理工作流程，並每隔幾個回合附上簡短的提醒，以及在模式關閉時發出退出通知。如需實際範例，請參閱建立協調模式。

在上述所有情況下，您都可以將指令放在一般的 user 訊息中，而 Claude 確實會遵循在使用者回合中到達的指令。差別在於優先順序：user 訊息被視為來自終端使用者，而 system 訊息被視為來自您，即應用程式操作者。當兩者衝突時，系統指令優先，因此請對操作者層級的事實和約束使用 system 角色，這些內容即使在終端使用者要求不同的情況下也應保持有效。對話中途系統訊息保留了這種操作者層級的優先順序，同時避免了編輯頂層 system 欄位所帶來的快取未命中成本。

運作方式

在 messages 陣列中新增一個 "role": "system" 的訊息。content 可以使用純字串或內容區塊，與 user 或 assistant 回合相同。該指令從對話中的該位置開始生效。當指令衝突時，較晚的系統訊息優先於較早的系統訊息，而對話中途系統訊息在其後的回合中優先於頂層 system 欄位。

您仍然可以設定頂層 system 欄位，用於應套用於整個對話的指令。將對話中途系統訊息保留給那些稍後才變得相關的指令，或是您想要新增但不希望使快取前綴失效的指令。

此範例使用頂層 cache_control 欄位啟用自動快取。提示快取是選擇性啟用的：如果請求沒有 cache_control 欄位（無論是自動快取還是明確斷點），則不會快取任何內容，每個請求都會為完整對話支付一般的輸入 token 價格。啟用快取後，附加系統訊息不會改變已快取的回合，因此攜帶新指令的請求仍會從快取中讀取這些回合，而不是重新處理它們。快取還要求對話達到最小可快取提示長度；像這樣簡短的範例低於該門檻，因此 cache_creation_input_tokens 和 cache_read_input_tokens 會保持為 0，直到對話增長為止。

對話中途系統訊息必須緊接在 user 回合（或以伺服器工具使用結尾的 assistant 回合）之後，並且必須是 messages 中的最後一個條目，或緊接著一個 assistant 回合。攜帶 tool_result 區塊的 user 訊息也算數：在代理迴圈中，您可以將系統訊息放在工具結果之後、Claude 的下一個回合之前。唯一不允許的位置是在 assistant 的 tool_use 區塊與回應它的 tool_result 之間。

工具結果之後的放置位置

在代理迴圈中，系統訊息放在傳遞工具結果的 user 訊息之後。這也是您的應用程式可以轉發使用者在 Claude 工作期間輸入內容的位置，讓新的上下文被吸收而無需重新開始該回合：

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

將系統內容表述為上下文，而非覆蓋使用者的命令。陳述事實（「使用者傳來了新輸入：X」、「剩餘的 token 預算現在是 Y」），讓 Claude 據此行動。Claude 經過訓練會抵制看似違背使用者意願的指令，這種保護機制同樣適用於系統角色，因此「忽略使用者所說的內容」這類措辭的效果不如直接陳述發生了什麼變化。

此模式用於轉發來自對話本身終端使用者的輸入。請勿用它來傳遞工具輸出、檢索到的文件或其他第三方內容；請將這些內容保留在 tool_result 區塊中（請參閱限制）。

與提示快取結合使用

對話中途系統訊息和提示快取的設計就是要搭配使用：

• 明確啟用快取。 只有當請求包含 cache_control 時才會進行快取，無論是頂層的自動快取欄位，還是內容區塊上的明確斷點。對話中途系統訊息本身不會建立快取條目，若未啟用快取，就沒有可保留的節省效益。
• 照常快取穩定的前綴。 將 cache_control 放在跨請求保持不變的最後一個區塊上，無論是頂層 system 欄位的末尾、工具定義的末尾，還是訊息歷史中的某個穩定位置。
• 在斷點之後附加系統訊息。 由於它位於快取前綴之後，因此不會改變前綴雜湊值，快取仍然會命中。
• 對話中途系統訊息本身也可以被快取。 一旦它進入對話，就成為穩定歷史的一部分。在下一個回合中，您可以將快取斷點移到它之後（或依靠自動快取來處理），系統訊息就會像其他回合一樣從快取中讀取。

避免編輯或移除已經發送的對話中途系統訊息。與對較早訊息的任何其他更改一樣，這會使從該點開始的快取失效。如果指令需要演變，請附加新的系統訊息，而不是重寫舊的。不允許連續的系統訊息；請將指令合併到一個訊息中，或等到下一個使用者回合再附加。

限制

• 不能作為第一個訊息。 system 訊息不能是 messages 中的第一個條目。對於從一開始就應套用的指令，請使用頂層 system 欄位。
• 放置位置受限。 system 訊息必須緊接在 user 回合（包括攜帶 tool_result 區塊的 user 回合）或以伺服器工具使用結尾的 assistant 回合之後，並且必須位於 assistant 回合之前或作為陣列的結尾。它不能位於 tool_use 區塊與其 tool_result 之間。放置在其他位置會回傳 400 錯誤。
• 不適合放置不受信任的內容。 Claude 將系統內容視為操作者指令並加以遵循。請勿將來自對話外部的文字（例如原始工具輸出、檢索到的文件或網頁內容）直接放入系統訊息中；這樣做會賦予該文字操作者層級的權限。請將這些資料保留在 tool_result 區塊中，並繼續遵循緩解越獄和提示注入的指引。

相關資源