{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$comment": "Generated from types/errors.ts — do not edit", "$id": "https://microsoft.github.io/agent-host-protocol/schema/errors.schema.json", "title": "AHP Error Codes", "description": "Error codes used in the Agent Host Protocol.", "$defs": { "JsonRpcErrorCode": { "description": "Standard JSON-RPC 2.0 error codes.", "type": "number", "enum": [ -32700, -32600, -32601, -32602, -32603 ] }, "AhpErrorCode": { "description": "AHP application-specific error codes.", "type": "number", "enum": [ -32001, -32002, -32003, -32004, -32005, -32006, -32007, -32008, -32009, -32010 ] }, "AuthRequiredErrorData": { "type": "object", "description": "在 `AuthRequired`（-32007）錯誤之 `data` 欄位中承載的詳細資料。\n\n將受保護資源清單包裝在 `{ resources: [...] }` 中，而非回傳裸陣列，\n如此一來未來版本可新增額外欄位而不破壞線路格式。", "properties": { "resources": { "type": "array", "items": { "$ref": "#/$defs/ProtectedResourceMetadata" }, "description": "需要驗證的受保護資源。" } }, "required": [ "resources" ] }, "PermissionDeniedErrorData": { "type": "object", "description": "在 `PermissionDenied`（-32009）錯誤之 `data` 欄位中承載的詳細資料。\n\n接收端 MAY 宣佈一個 `resourceRequest` 有效負載，描述若獲准將可解鎖該操作的存取。\n呼叫端接著 MAY 以該有效負載發出 `resourceRequest` 來協商存取。", "properties": { "request": { "$ref": "#/$defs/ResourceRequestParams", "description": "若透過 `resourceRequest` 獲准則可解鎖該操作的資源存取。當沒有任何特定的存取\n授權能解決此拒絕時省略（例如當資源根本無法存取時）。" } } }, "UnsupportedProtocolVersionErrorData": { "type": "object", "description": "在 `UnsupportedProtocolVersion`（-32005）錯誤之 `data` 欄位中承載的詳細資料。", "properties": { "supportedVersions": { "type": "array", "items": { "type": "string" }, "description": "伺服器願意使用的協定版本。\n\n每個項目若非 [SemVer](https://semver.org) `MAJOR.MINOR.PATCH` 字串\n（例如 `\"0.1.0\"`），即為 [SemVer 範圍](https://semver.org/#spec-item-11)\n限制式（例如 `\">=0.1.0 <0.3.0\"` 或 `\"^0.2.0\"`）。" } }, "required": [ "supportedVersions" ] }, "AhpErrorDetailsMap": { "type": "object", "description": "將每個帶有結構化 `data` 的 AHP 錯誤碼對應到該資料的類型。\n\n未出現在此對應中的錯誤碼，若非沒有 `data` 有效負載，即為帶有未指定的\n有效負載，呼叫端 SHOULD 將其視為 `unknown`。", "properties": { "[AhpErrorCodes.AuthRequired]": { "$ref": "#/$defs/AuthRequiredErrorData" }, "[AhpErrorCodes.PermissionDenied]": { "$ref": "#/$defs/PermissionDeniedErrorData" }, "[AhpErrorCodes.UnsupportedProtocolVersion]": { "$ref": "#/$defs/UnsupportedProtocolVersionErrorData" } }, "required": [ "[AhpErrorCodes.AuthRequired]", "[AhpErrorCodes.PermissionDenied]", "[AhpErrorCodes.UnsupportedProtocolVersion]" ] }, "Icon": { "type": "object", "description": "可選擇指定大小的圖示，可在使用者介面中顯示。", "properties": { "src": { "$ref": "#/$defs/URI", "description": "指向圖示資源的標準 URI。可以是 HTTP/HTTPS URL，或是帶有 Base64 編碼影像資料的\n`data:` URI。\n\n消費者 SHOULD 採取步驟，確保提供圖示的 URL 來自與用戶端／伺服器相同的網域或受信任的網域。\n\n消費者 SHOULD 在使用 SVG 時採取適當的防護措施，因為 SVG 可能包含可執行的 JavaScript。" }, "contentType": { "type": "string", "description": "選用的 MIME 類型覆寫值，用於來源 MIME 類型缺失或為通用型別時。\n例如：`\"image/png\"`、`\"image/jpeg\"` 或 `\"image/svg+xml\"`。" }, "sizes": { "type": "array", "items": { "type": "string" }, "description": "選用的字串陣列，指定圖示可使用的尺寸。\n每個字串應為 WxH 格式（例如 `\"48x48\"`、`\"96x96\"`），或可縮放格式（如 SVG）使用 `\"any\"`。\n\n若未提供，用戶端應假設該圖示可用於任何尺寸。" }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "選用的指定值，說明此圖示所設計的主題。`\"light\"` 表示圖示設計用於淺色背景，\n`\"dark\"` 表示圖示設計用於深色背景。\n\n若未提供，用戶端應假設該圖示可用於任何主題。" } }, "required": [ "src" ] }, "ProtectedResourceMetadata": { "type": "object", "description": "使用 [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)（OAuth 2.0\n受保護資源中繼資料）語意，描述受保護資源的驗證需求。\n\n欄位名稱使用 snake_case，以符合 RFC 9728 的 JSON 格式。", "properties": { "resource": { "type": "string", "description": "REQUIRED. 受保護資源的資源識別碼，一個使用 `https` 配置且不含片段元件的\nURL（例如 `\"https://api.github.com\"`）。" }, "resource_name": { "type": "string", "description": "OPTIONAL. 受保護資源的人類可讀名稱。" }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. OAuth 授權伺服器識別碼 URL 的 JSON 陣列。" }, "jwks_uri": { "type": "string", "description": "OPTIONAL. 受保護資源的 JWK Set 文件之 URL。" }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "description": "RECOMMENDED. 用於授權請求的 OAuth 2.0 範圍值之 JSON 陣列。" }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. 受支援之 Bearer Token 呈現方法的 JSON 陣列。" }, "resource_signing_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. 受支援之 JWS 簽章演算法的 JSON 陣列。" }, "resource_encryption_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. 受支援之 JWE 加密演算法（alg）的 JSON 陣列。" }, "resource_encryption_enc_values_supported": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL. 受支援之 JWE 加密演算法（enc）的 JSON 陣列。" }, "resource_documentation": { "type": "string", "description": "OPTIONAL. 資源之人類可讀文件的 URL。" }, "resource_policy_uri": { "type": "string", "description": "OPTIONAL. 資源之資料使用政策的 URL。" }, "resource_tos_uri": { "type": "string", "description": "OPTIONAL. 資源之服務條款的 URL。" }, "required": { "type": "boolean", "description": "AHP 擴充功能。此資源是否需要驗證。\n\n- `true`（預設） — 沒有有效的令牌就無法使用代理程式。\n 若用戶端在未驗證的情況下嘗試使用代理程式，伺服器 SHOULD 回傳\n `AuthRequired`（`-32007`）。\n- `false` — 代理程式無須驗證即可運作，但當提供令牌時 MAY 提供增強的能力。\n\n用戶端 SHOULD 將缺失的欄位視同 `true`。" } }, "required": [ "resource" ] }, "ConfigPropertySchema": { "type": "object", "description": "相容於 JSON Schema 的屬性描述器，附帶顯示擴充功能。\n\n標準 JSON Schema 欄位（`type`、`title`、`description`、`default`、\n`enum`）讓驗證器能處理該結構描述。顯示擴充功能（`enumLabels`、\n`enumDescriptions`）為平行的陣列，為每個 `enum` 值提供 UI 中繼資料。\n\n這是通用基底類型。關於工作階段專屬的擴充功能，請參見 {@link SessionConfigPropertySchema}。", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object" ], "description": "JSON Schema：屬性類型" }, "title": { "type": "string", "description": "JSON Schema：屬性的人類可讀標籤" }, "description": { "type": "string", "description": "JSON Schema：描述／工具提示" }, "default": { "description": "JSON Schema：預設值" }, "enum": { "type": "array", "items": { "$ref": "#/$defs/JsonPrimitive" }, "description": "JSON Schema：允許的值。可為任一 JSON 類型的基本值。" }, "enumLabels": { "type": "array", "items": { "type": "string" }, "description": "顯示擴充功能：每個列舉值的人類可讀標籤（平行陣列）" }, "enumDescriptions": { "type": "array", "items": { "type": "string" }, "description": "顯示擴充功能：每個列舉值的描述（平行陣列）" }, "readOnly": { "type": "boolean", "description": "JSON Schema：當 `true` 時，屬性會顯示但使用者無法修改" }, "items": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema：陣列項目的結構描述（當 `type` 為 `'array'` 時使用）" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema：物件屬性的屬性描述器（當 `type` 為 `'object'` 時使用）" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema：必要屬性 id 的清單（當 `type` 為 `'object'` 時使用）" }, "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema：未列於 `properties` 中之額外屬性的結構描述（當 `type` 為 `'object'` 時使用）。" } }, "required": [ "type", "title" ] }, "ConfigSchema": { "type": "object", "description": "描述可用設定屬性的 JSON Schema 物件。\n\n這是通用基底類型。關於工作階段專屬的用法，請參見 {@link SessionConfigSchema}。", "properties": { "type": { "type": "string", "enum": [ "object" ], "description": "JSON Schema：永遠為 `'object'`" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema：以屬性 id 為索引鍵的屬性描述器" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema：必要屬性 id 的清單" } }, "required": [ "type", "properties" ] }, "TextPosition": { "type": "object", "description": "文字文件中以零為基底的某個位置。", "properties": { "line": { "type": "number", "description": "以零為基底的行號。" }, "character": { "type": "number", "description": "該行內以零為基底的字元偏移量。" } }, "required": [ "line", "character" ] }, "TextRange": { "type": "object", "description": "文字文件中的一個範圍。", "properties": { "start": { "$ref": "#/$defs/TextPosition", "description": "範圍的起始位置。" }, "end": { "$ref": "#/$defs/TextPosition", "description": "範圍的結束位置。" } }, "required": [ "start", "end" ] }, "TextSelection": { "type": "object", "description": "文字資源中的一個選取範圍。\n\n這僅對文字資源有意義。二進位資源仍可使用資源或內嵌資源附件，但不應使用此\n文字選取欄位。", "properties": { "range": { "$ref": "#/$defs/TextRange", "description": "選取範圍所涵蓋的範圍。" } }, "required": [ "range" ] }, "ContentRef": { "type": "object", "description": "對儲存於狀態樹外之大型內容的參照。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "內容 URI" }, "sizeHint": { "type": "number", "description": "以位元組為單位的近似大小" }, "contentType": { "type": "string", "description": "內容 MIME 類型" }, "nonce": { "type": "string", "description": "內容 nonce" } }, "required": [ "uri" ] }, "FileEdit": { "type": "object", "description": "描述檔案修改的先後狀態與差異中繼資料。\n\n支援建立（僅 `after`）、刪除（僅 `before`）、重新命名／移動\n（`before` 與 `after` 中 `uri` 不同），以及編輯（`uri` 相同、內容不同）。", "properties": { "before": { "type": "object", "properties": { "uri": { "$ref": "#/$defs/URI" }, "content": { "$ref": "#/$defs/ContentRef" } }, "required": [ "uri", "content" ], "description": "編輯前的檔案狀態。檔案建立或就地檔案編輯時不存在。" }, "after": { "type": "object", "properties": { "uri": { "$ref": "#/$defs/URI" }, "content": { "$ref": "#/$defs/ContentRef" } }, "required": [ "uri", "content" ], "description": "編輯後的檔案狀態。檔案刪除時不存在。" }, "diff": { "type": "object", "properties": { "added": { "type": "number" }, "removed": { "type": "number" } }, "description": "選用的差異顯示中繼資料" } } }, "UsageInfo": { "type": "object", "properties": { "inputTokens": { "type": "number", "description": "已消耗的輸入令牌" }, "outputTokens": { "type": "number", "description": "已產生的輸出令牌" }, "model": { "type": "string", "description": "使用的模型" }, "cacheReadTokens": { "type": "number", "description": "從快取讀取的令牌" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此用量報告的額外提供者專屬中繼資料。\n用戶端 MAY 在此尋找已知的選用索引鍵，以提供增強的 UI。" } } }, "ErrorInfo": { "type": "object", "properties": { "errorType": { "type": "string", "description": "錯誤類型識別碼" }, "message": { "type": "string", "description": "人類可讀的錯誤訊息" }, "stack": { "type": "string", "description": "堆疊追蹤" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此錯誤的額外提供者專屬中繼資料。\n用戶端 MAY 在此尋找已知的選用索引鍵，以提供增強的 UI\n（例如用於更豐富、本地化訊息的結構化聊天擷取錯誤）。" } }, "required": [ "errorType", "message" ] }, "Snapshot": { "type": "object", "description": "已訂閱資源狀態的某個時間點快照，由 `initialize`、`reconnect` 與\n`subscribe` 回傳。", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "已訂閱的通道 URI（例如 `ahp-root://`、`ahp-session:/` 或 `ahp-chat:/`）" }, "state": { "oneOf": [ { "$ref": "#/$defs/RootState" }, { "$ref": "#/$defs/SessionState" }, { "$ref": "#/$defs/TerminalState" }, { "$ref": "#/$defs/ChangesetState" }, { "$ref": "#/$defs/ResourceWatchState" }, { "$ref": "#/$defs/AnnotationsState" }, { "$ref": "#/$defs/ChatState" } ], "description": "資源的目前狀態" }, "fromSeq": { "type": "number", "description": "取此快照時的 `serverSeq`。後續操作將具有 `serverSeq > fromSeq`。" } }, "required": [ "resource", "state", "fromSeq" ] }, "RootState": { "type": "object", "description": "與每個訂閱 `ahp-root://` 的用戶端共享的全域狀態。", "properties": { "agents": { "type": "array", "items": { "$ref": "#/$defs/AgentInfo" }, "description": "可用的代理程式後端及其模型" }, "activeSessions": { "type": "number", "description": "伺服器上作用中（未處置）工作階段的數量" }, "terminals": { "type": "array", "items": { "$ref": "#/$defs/TerminalInfo" }, "description": "伺服器上已知的終端機。訂閱個別終端機 URI 以取得完整狀態。" }, "config": { "$ref": "#/$defs/RootConfigState", "description": "代理主機的組態結構描述與目前值" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "關於代理主機本身的額外實作定義中繼資料。\n\n用戶端 MAY 在此尋找公認的鍵以提供增強的 UI。" } }, "required": [ "agents" ] }, "AgentInfo": { "type": "object", "properties": { "provider": { "type": "string", "description": "代理程式提供者 ID（例如 `'copilot'`）" }, "displayName": { "type": "string", "description": "人類可讀名稱" }, "description": { "type": "string", "description": "描述字串" }, "models": { "type": "array", "items": { "$ref": "#/$defs/SessionModelInfo" }, "description": "此代理程式可用的模型" }, "protectedResources": { "type": "array", "items": { "$ref": "#/$defs/ProtectedResourceMetadata" }, "description": "此代理程式要求驗證的受保護資源。\n\n每個項目使用 [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)\n語意描述一個 OAuth 2.0 受保護資源。用戶端應從宣告的\n`authorization_servers` 取得權杖，並在以此代理程式建立工作階段之前，\n透過 `authenticate` 指令推送這些權杖。" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/Customization" }, "description": "與此代理程式相關聯的自訂項目。\n\n可能是容器自訂項目 —— 即代理程式隨附的\n{@link PluginCustomization | `PluginCustomization`} 項目，加上它在所使用的\n任何工作區中監視的 {@link DirectoryCustomization | `DirectoryCustomization`}\n項目 —— 或是代理主機直接宣告的頂層\n{@link McpServerCustomization | `McpServerCustomization`} 項目。當以此代理程式\n建立工作階段時，這些項目會被增強（例如將目錄 URI 解析為相對於工作區、解析\n子項）並傳播至工作階段的 `customizations` 清單。" }, "capabilities": { "$ref": "#/$defs/AgentCapabilities", "description": "代理程式關於自身所宣告的靜態能力。用戶端使用這些能力來控制功能\n（多聊天、分支）的啟用，而不是依提供者 id 切換。" } }, "required": [ "provider", "displayName", "description", "models" ] }, "AgentCapabilities": { "type": "object", "description": "{@link AgentInfo} 所宣告的靜態能力。仿照 MCP 能力建模：每個欄位都是選用加入，\n其存在（一個空物件 `{}`）表示支援，而缺席表示不支援該功能且對應的用戶端指令\nMUST NOT 被使用。子欄位承載各能力專屬的選項。", "properties": { "multipleChats": { "$ref": "#/$defs/MultipleChatsCapability", "description": "代理程式可在每個工作階段中託管多個並行聊天。缺席時，用戶端 MUST NOT 呼叫\n`createChat` 來開啟工作階段啟動時所伴隨預設聊天以外的聊天。空物件 `{}`\n宣告多聊天但不支援基於來源的建立；設定\n{@link MultipleChatsCapability.fork} 或\n{@link MultipleChatsCapability.sideChat} 以允許對應的模式。" }, "multipleWorkingDirectories": { "$ref": "#/$defs/MultipleWorkingDirectoriesCapability", "description": "工作階段的代理程式可被授予對多個工作目錄的工具存取權。這些目錄被視為同等\n對等項目，除非代理程式宣告\n{@link MultipleWorkingDirectoriesCapability.requiresPrimary}\n（某些後端需要將一個目錄指定為主要根）。\n\n缺席時，用戶端 MUST NOT 變動工作階段或聊天的工作目錄集合，且 MUST NOT 在\n{@link CreateSessionParams.workingDirectories} 中設定多於一個項目。" } } }, "MultipleChatsCapability": { "type": "object", "description": "{@link AgentCapabilities.multipleChats} 能力的選項。", "properties": { "fork": { "type": "boolean", "description": "代理程式可從特定回合分支聊天。缺席或 `false` 時，用戶端 MUST NOT 將帶有\n`kind: \"fork\"` 的 {@link ChatSource} 傳給 `createChat`。\n分支一律表示支援多聊天。" }, "sideChat": { "type": "boolean", "description": "代理程式可從特定回合建立側邊聊天。缺席或 `false` 時，用戶端 MUST NOT 將帶有\n`kind: \"sideChat\"` 的 {@link ChatSource} 傳給 `createChat`。\n\n側邊聊天會以來源回合作為脈絡，而不會將來源對話記錄複製到自身可見的歷程中。\n來源由穩定的 `turnId` 識別，主機會將其解析為相對於來源聊天目前的\n`activeTurn` 或保留的歷程。當其指名為目前作用中的回合時，主機會在建立時\n對可用的部分代理程式回應建立快照。側邊聊天支援一律表示支援多聊天。" } } }, "MultipleWorkingDirectoriesCapability": { "type": "object", "description": "{@link AgentCapabilities.multipleWorkingDirectories} 能力的選項。", "properties": { "requiresPrimary": { "type": "boolean", "description": "代理程式要求每個聊天將其工作目錄之一指定為 **主要** —— 即聊天所圍繞的\n區別根（例如該聊天代理程式的程序根、相對路徑的預設位置）。主要是一個\n**每個聊天** 的概念，固定於聊天建立之時。為 `true` 時，用戶端 SHOULD\n提供 {@link CreateChatParams.primaryWorkingDirectory}（以及\n{@link CreateSessionParams.primaryWorkingDirectory}，其為工作階段預設聊天\n播種）；主機 MAY 拒絕省略它的建立，或退回至聊天工作目錄的第一個項目。所選\n的主要目錄會在 {@link ChatState.primaryWorkingDirectory} 上（唯讀）回報。\n\n缺席或 `false` 時，代理程式沒有主要目錄 —— 所有目錄皆為同等對等項目，\n用戶端無須指定。" } } }, "SessionModelInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "模型識別碼" }, "provider": { "type": "string", "description": "此模型所屬的提供者" }, "name": { "type": "string", "description": "人類可讀的模型名稱" }, "maxContextWindow": { "type": "number", "description": "上下文視窗大小上限" }, "maxOutputTokens": { "type": "number", "description": "模型可產生的輸出權杖數上限" }, "maxPromptTokens": { "type": "number", "description": "模型接受的提示（輸入）權杖數上限" }, "supportsVision": { "type": "boolean", "description": "模型是否支援視覺" }, "policyState": { "$ref": "#/$defs/PolicyState", "description": "策略組態狀態" }, "configSchema": { "$ref": "#/$defs/ConfigSchema", "description": "描述模型專屬選項（例如思考等級）的組態結構描述。用戶端將此呈現為表單，\n並在建立或變更工作階段時，將解析後的值傳入\n{@link ModelSelection.config}。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此模型的額外提供者專屬中繼資料。\n\n用戶端 MAY 在此尋找公認的鍵以提供增強的 UI。\n例如，`pricing` 鍵可承載模型定價中繼資料。" } }, "required": [ "id", "provider", "name" ] }, "ModelSelection": { "type": "object", "description": "模型選擇：所選的模型 ID 連同任何模型專屬組態值，這些值的鍵對應於模型的\n{@link SessionModelInfo.configSchema}。", "properties": { "id": { "type": "string", "description": "模型識別碼" }, "config": { "type": "object", "additionalProperties": { "$ref": "#/$defs/JsonPrimitive" }, "description": "模型專屬組態值。值為 JSON 基本型別：大多數挑選器產生字串，但有些\n（例如數值上下文大小挑選器）產生數字或布林值，這些會原樣傳遞。" } }, "required": [ "id" ] }, "RootConfigState": { "type": "object", "description": "即時代理主機組態中繼資料。\n\n結構描述描述可用的組態屬性，而值包含每個已解析屬性的目前值。", "properties": { "schema": { "$ref": "#/$defs/ConfigSchema", "description": "描述可用組態屬性的 JSON Schema" }, "values": { "type": "object", "additionalProperties": {}, "description": "目前的組態值" } }, "required": [ "schema", "values" ] }, "SessionMetadata": { "type": "object", "description": "完整 {@link SessionState}（當用戶端訂閱工作階段 URI 時傳遞）與輕量級\n{@link SessionSummary}（承載於根通道工作階段目錄中）之間共用的中繼\n資料。\n\n這些欄位一覽地描述工作階段，且同時出現於兩處。\n`SessionState` 擁有已訂閱工作階段的權威值；\n`SessionSummary` 將其鏡射至目錄中，讓僅呈現工作階段清單的用戶端不必\n訂閱每個工作階段 URI。主機透過 `root/sessionSummaryChanged` 保持目錄\n同步。", "properties": { "provider": { "type": "string", "description": "代理程式提供者 ID" }, "title": { "type": "string", "description": "工作階段標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前工作階段狀態" }, "activity": { "type": "string", "description": "工作階段目前正在做什麼的人類可讀描述" }, "project": { "$ref": "#/$defs/ProjectInfo", "description": "此工作階段的伺服器擁有專案" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "工作階段代理程式具有工具存取權的工作目錄，由\n`session/workingDirectorySet` / `session/workingDirectoryRemoved` 操作\n維護。目錄為**平等的同儕** — 工作階段沒有主要目錄。個別聊天 MAY\n透過 {@link ChatSummary.workingDirectories | 其自身的 `workingDirectories`} 限制為子集，並將其自身的某個目錄指定為主要目錄（見\n{@link ChatState.primaryWorkingDirectory}）；未設定子集的聊天會對此完整集合運作。" }, "annotations": { "$ref": "#/$defs/AnnotationsSummary", "description": "此工作階段內嵌註解通道（`ahp-session://annotations`）的\n輕量級摘要。公開以便徽章 UI 無需訂閱即可呈現註解/項目計數。\n當工作階段未公開註解通道時不存在。" } }, "required": [ "provider", "title", "status" ] }, "SessionState": { "type": "object", "description": "單一工作階段的完整狀態，當用戶端訂閱工作階段 URI 時載入。\n\n將每個 {@link SessionMetadata} 欄位直接內嵌（反正規化）至自身，讓\n訂閱者收到一個扁平物件而非巢狀摘要。輕量級目錄表示法為\n{@link SessionSummary}，公開於根通道；主機透過\n`root/sessionSummaryChanged` 保持兩者同步。", "properties": { "provider": { "type": "string", "description": "代理程式提供者 ID" }, "title": { "type": "string", "description": "工作階段標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前工作階段狀態" }, "activity": { "type": "string", "description": "工作階段目前正在做什麼的人類可讀描述" }, "project": { "$ref": "#/$defs/ProjectInfo", "description": "此工作階段的伺服器擁有專案" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "工作階段代理程式具有工具存取權的工作目錄，由\n`session/workingDirectorySet` / `session/workingDirectoryRemoved` 操作\n維護。目錄為**平等的同儕** — 工作階段沒有主要目錄。個別聊天 MAY\n透過 {@link ChatSummary.workingDirectories | 其自身的 `workingDirectories`} 限制為子集，並將其自身的某個目錄指定為主要目錄（見\n{@link ChatState.primaryWorkingDirectory}）；未設定子集的聊天會對此完整集合運作。" }, "annotations": { "$ref": "#/$defs/AnnotationsSummary", "description": "此工作階段內嵌註解通道（`ahp-session://annotations`）的\n輕量級摘要。公開以便徽章 UI 無需訂閱即可呈現註解/項目計數。\n當工作階段未公開註解通道時不存在。" }, "lifecycle": { "$ref": "#/$defs/SessionLifecycle", "description": "工作階段初始化狀態" }, "creationError": { "$ref": "#/$defs/ErrorInfo", "description": "建立失敗時的錯誤詳細資訊" }, "serverTools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "伺服器（代理主機）為此工作階段提供的工具" }, "activeClients": { "type": "array", "items": { "$ref": "#/$defs/SessionActiveClient" }, "description": "目前為此工作階段提供工具與互動能力的用戶端。若同一作用中用戶端\n提供多個工具或自訂，代理主機 MAY 在公開給模型時對其去重，並優先\n採用起始回合的用戶端。\n\n成員資格由主機管理：用戶端以 `session/activeClientSet` 新增（或重新\n整理）自身，且主機在其取消訂閱、未及時重新連線的斷線，或重新連線\n但未重新訂閱工作階段時，以 `session/activeClientRemoved` 移除它們。" }, "chats": { "type": "array", "items": { "$ref": "#/$defs/ChatSummary" }, "description": "此工作階段中的聊天目錄。" }, "defaultChat": { "$ref": "#/$defs/URI", "description": "當使用者在不選取特定聊天的情況下對工作階段發話時，接收輸入的\n聊天。這是 UI 路由提示，而非階層標記 — 在協定層級聊天仍是平等的\n同儕。主機 MAY 在工作階段生命週期中變更此值。" }, "config": { "$ref": "#/$defs/SessionConfigState", "description": "工作階段設定綱要與目前值" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/Customization" }, "description": "此工作階段中作用中的頂層自訂。\n\n永遠是 {@link Customization} 變體之一：\n\n- 容器自訂（{@link PluginCustomization}、\n {@link DirectoryCustomization}），其子項 — 代理程式、技能、\n 提示、規則、掛鉤、MCP 伺服器 — 存在於每個容器的\n {@link ContainerCustomizationBase.children | `children`} 陣列中。\n- 主機直接公開的頂層 {@link McpServerCustomization} 項目（例如\n 全域設定的 MCP 伺服器，未隨附於外掛或目錄中）。MCP 伺服器也可\n 作為容器的子項出現。\n\n用戶端發布的外掛透過\n{@link SessionActiveClient.customizations | `activeClients[].customizations`}\n抵達，主機將其傳播至此清單（通常會設定容器的 `clientId` 並填入\n`children`）。用戶端僅以容器形式發布；頂層的單獨 MCP 伺服器為\n伺服器發起。" }, "changesets": { "type": "array", "items": { "$ref": "#/$defs/Changeset" }, "description": "伺服器可為此工作階段產生的變更集目錄。每個項目通告一個可訂閱的\n檔案變更檢視（未提交、工作階段範圍、每回合等）以及用戶端在訂閱前\n展開的 URI 範本。完整形狀見 {@link Changeset}，模型概覽見\n{@link /guide/changesets | Changesets}。" }, "inputNeeded": { "type": "array", "items": { "$ref": "#/$defs/SessionInputRequest" }, "description": "工作階段受阻的待處理輸入，跨每個聊天彙總，讓用戶端能單從工作\n階段通道發現並回答，而無需訂閱個別聊天。\n\n每個項目皆自足：它承載擁有聊天的 URI 加上用戶端回應所需的所有\n識別碼。用戶端透過將普通的 `chat/*` 操作分派至該聊天的通道來回答\n— 各變體的回應路徑見 {@link SessionInputRequest}。存在且非空的\n清單隱含 {@link SessionSummary.status} 上的\n{@link SessionStatus.InputNeeded}。\n\n主機管理：主機以 `session/inputNeededSet` 在聊天提出請求時 upsert\n項目，並在底層請求解決後以 `session/inputNeededRemoved` 移除它們。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工作階段的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找知名鍵以提供增強的 UI。例如，`git` 鍵可提供\n關於工作階段工作目錄的額外 git 中繼資料。" } }, "required": [ "provider", "title", "status", "lifecycle", "activeClients", "chats" ] }, "SessionActiveClient": { "type": "object", "description": "目前為工作階段提供工具與互動能力的用戶端。\n\n一個工作階段 MAY 同時有多個作用中用戶端；{@link SessionState.activeClients}\n中的項目以 `clientId` 為鍵。伺服器 SHOULD 在該用戶端斷線時自動移除\n作用中用戶端。", "properties": { "clientId": { "type": "string", "description": "用戶端識別碼（與 `initialize` 中的 `clientId` 相符）" }, "displayName": { "type": "string", "description": "人類可讀的用戶端名稱（例如 `\"VS Code\"`）" }, "tools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "此用戶端為工作階段提供的工具" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/ClientPluginCustomization" }, "description": "此用戶端為工作階段貢獻的外掛自訂。\n\n用戶端以 [Open Plugins](https://open-plugins.com/) 格式發布 — 即\n永遠為容器形式的外掛。它們 MAY 在記憶體中合成虛擬外掛，並依賴\n主機將其展開為 {@link SessionState.customizations} 內的具體子項。" } }, "required": [ "clientId", "tools" ] }, "SessionInputRequestBase": { "type": "object", "description": "每個 {@link SessionInputRequest} 變體共用的欄位。", "properties": { "id": { "type": "string", "description": "此項目的穩定鍵，在工作階段的 {@link SessionState.inputNeeded} 清單中\n唯一。主機以任何其偏好方式推導（例如從聊天 URI 加上底層請求或\n工具呼叫 id）；消費者 MUST 將其視為不透明。它是\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert 慣例的\n鍵。" }, "chat": { "$ref": "#/$defs/URI", "description": "底層請求所在的聊天。這是用戶端將其回應分派至的通道 — 它不需要先\n訂閱該聊天。" } }, "required": [ "id", "chat" ] }, "SessionChatInputRequest": { "type": "object", "description": "在工作階段層級公開的使用者輸入引出，鏡射自擁有聊天中未解決的\n{@link InputRequestResponsePart} 請求。\n\n透過分派 `chat/inputCompleted`（或以 `chat/inputAnswerChanged` 同步草稿）\n至 {@link SessionInputRequestBase.chat | `chat`} 來回應，以\n{@link ChatInputRequest.id | `request.id`} 為鍵。", "properties": { "id": { "type": "string", "description": "此項目的穩定鍵，在工作階段的 {@link SessionState.inputNeeded} 清單中\n唯一。主機以任何其偏好方式推導（例如從聊天 URI 加上底層請求或\n工具呼叫 id）；消費者 MUST 將其視為不透明。它是\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert 慣例的\n鍵。" }, "chat": { "$ref": "#/$defs/URI", "description": "底層請求所在的聊天。這是用戶端將其回應分派至的通道 — 它不需要先\n訂閱該聊天。" }, "kind": { "const": "chatInput" }, "request": { "$ref": "#/$defs/ChatInputRequest", "description": "鏡射的聊天輸入請求。" } }, "required": [ "id", "chat", "kind", "request" ] }, "SessionToolConfirmationRequest": { "type": "object", "description": "因確認而阻塞的工具呼叫 — 可能是執行前的參數確認或之後的結果確認 —\n在工作階段層級公開。\n\n透過分派 `chat/toolCallConfirmed`（對\n{@link ToolCallPendingConfirmationState}）或\n`chat/toolCallResultConfirmed`（對\n{@link ToolCallPendingResultConfirmationState}）至\n{@link SessionInputRequestBase.chat | `chat`} 來回應，以 `turnId` 與\n`toolCall.toolCallId` 為鍵。", "properties": { "id": { "type": "string", "description": "此項目的穩定鍵，在工作階段的 {@link SessionState.inputNeeded} 清單中\n唯一。主機以任何其偏好方式推導（例如從聊天 URI 加上底層請求或\n工具呼叫 id）；消費者 MUST 將其視為不透明。它是\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert 慣例的\n鍵。" }, "chat": { "$ref": "#/$defs/URI", "description": "底層請求所在的聊天。這是用戶端將其回應分派至的通道 — 它不需要先\n訂閱該聊天。" }, "kind": { "const": "toolConfirmation" }, "turnId": { "type": "string", "description": "工具呼叫所屬的回合。" }, "toolCall": { "$ref": "#/$defs/ToolCallConfirmationState", "description": "等待確認的工具呼叫。" } }, "required": [ "id", "chat", "kind", "turnId", "toolCall" ] }, "SessionToolClientExecutionRequest": { "type": "object", "description": "執行委派給作用中用戶端的執行中工具。公開以便提供該工具的用戶端能\n接手工作而無需訂閱擁有聊天。\n\n{@link toolCall} 永遠是 {@link ToolCallRunningState}（處於 `running`\n狀態的 {@link ToolCallState}），其\n{@link ToolCallRunningState.contributor | `contributor`} 為用戶端\n{@link ToolCallClientContributor}，其 `clientId` 與此處反正規化的\n{@link clientId} 相符。透過分派 `chat/toolCallComplete`（並選擇性地以\n`chat/toolCallContentChanged` 串流）至 {@link SessionInputRequestBase.chat |\n`chat`} 來執行並回報結果，以 `turnId` 與 `toolCall.toolCallId` 為鍵。", "properties": { "id": { "type": "string", "description": "此項目的穩定鍵，在工作階段的 {@link SessionState.inputNeeded} 清單中\n唯一。主機以任何其偏好方式推導（例如從聊天 URI 加上底層請求或\n工具呼叫 id）；消費者 MUST 將其視為不透明。它是\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert 慣例的\n鍵。" }, "chat": { "$ref": "#/$defs/URI", "description": "底層請求所在的聊天。這是用戶端將其回應分派至的通道 — 它不需要先\n訂閱該聊天。" }, "kind": { "const": "toolClientExecution" }, "turnId": { "type": "string", "description": "工具呼叫所屬的回合。" }, "clientId": { "type": "string", "description": "預期執行該工具的 `clientId`。與工具呼叫之用戶端\n{@link ToolCallContributor} 的 `clientId` 相符。" }, "toolCall": { "$ref": "#/$defs/ToolCallState", "description": "工作階段希望擁有用戶端執行的執行中工具呼叫。主機僅會以\n{@link ToolCallRunningState}（即處於 `running` 狀態的\n{@link ToolCallState}）填入此欄位。" } }, "required": [ "id", "chat", "kind", "turnId", "clientId", "toolCall" ] }, "SessionToolAuthenticationRequest": { "type": "object", "description": "執行中途因 MCP 驗證而阻塞的工具呼叫，在工作階段層級公開。\n\n{@link toolCall} 永遠是 {@link ToolCallAuthRequiredState}（處於\n`auth-required` 瀑態的 {@link ToolCallState}）。與\n{@link SessionToolConfirmationRequest} 不同，這**不是**透過直接分派\n`chat/*` 操作來回答：用戶端為\n{@link ToolCallAuthRequiredState.auth | `toolCall.auth`}`.resource` 取得\n權杖，並透過現有的 `authenticate` 指令推送（見\n{@link /specification/authentication | Authentication}）。主機在權杖被\n接受後恢復工具呼叫並分派 `chat/toolCallAuthResolved`，此時它也會以\n`session/inputNeededRemoved` 移除此項目。", "properties": { "id": { "type": "string", "description": "此項目的穩定鍵，在工作階段的 {@link SessionState.inputNeeded} 清單中\n唯一。主機以任何其偏好方式推導（例如從聊天 URI 加上底層請求或\n工具呼叫 id）；消費者 MUST 將其視為不透明。它是\n`session/inputNeededSet` / `session/inputNeededRemoved` upsert 慣例的\n鍵。" }, "chat": { "$ref": "#/$defs/URI", "description": "底層請求所在的聊天。這是用戶端將其回應分派至的通道 — 它不需要先\n訂閱該聊天。" }, "kind": { "const": "toolAuthentication" }, "turnId": { "type": "string", "description": "工具呼叫所屬的回合。" }, "toolCall": { "$ref": "#/$defs/ToolCallAuthRequiredState", "description": "等待驗證的工具呼叫。" } }, "required": [ "id", "chat", "kind", "turnId", "toolCall" ] }, "ProjectInfo": { "type": "object", "description": "工作階段的伺服器擁有專案中繼資料。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "專案 URI" }, "displayName": { "type": "string", "description": "人類可讀的專案名稱" } }, "required": [ "uri", "displayName" ] }, "SessionSummary": { "type": "object", "description": "摘要單一工作階段的輕量級目錄項目。透過\n{@link RootChannelCommands.listSessions | `root/listSessions`} 與\n`root/sessionAdded`/`root/sessionSummaryChanged` 通知公開。\n\n**跨聊天彙總。** 一旦工作階段包含多個聊天，若干 `SessionSummary` 欄位\n衍生自底層的 {@link SessionState.chats | 聊天目錄}。生產者 SHOULD 遵循\n這些規則，讓僅消費工作階段摘要的用戶端（例如工作階段清單）仍能看到\n有意義的狀態：\n\n- `status`：當 {@link SessionState.defaultChat | 預設聊天}存在時取其活動\n 位元（`Idle` / `InProgress` / `InputNeeded` / `Error` — 位元 0–4），\n 否則取最近修改的聊天。當工作階段中任何聊天需要輸入時**提升**為\n `InputNeeded`，且當任何聊天處於錯誤狀態時**提升**為 `Error` — 兩者皆\n 覆寫預設聊天位元。正交旗標位元（`IsRead`、`IsArchived`）保持工作\n 階段範圍。\n- `activity`：鏡射預設聊天的活動字串，或當非預設聊天勝出時（例如\n 引發 `InputNeeded` 的聊天）鏡射目前驅動已提升狀態位元之聊天的活動\n 字串。\n- `modifiedAt`：所有聊天 `modifiedAt` 的最大值。\n- `workingDirectories`：工作階段層級集合。個別聊天 MAY 透過\n {@link ChatSummary.workingDirectories} 限制為子集；將這些向上彙總毫無\n 意義，且 SHOULD NOT 嘗試。\n- `changes`：跨所有聊天的選用彙總。生產者 MAY 對每個聊天的變更集\n 統計加總，或回報最昂貴聊天的統計 — 視何者對主機計算更便宜而定。\n\n具有單一聊天的工作階段會簡單滿足上述所有條件（聊天的值原樣通過）。\n這些規則僅在工作階段帶有多個聊天時才有意義。", "properties": { "provider": { "type": "string", "description": "代理程式提供者 ID" }, "title": { "type": "string", "description": "工作階段標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前工作階段狀態" }, "activity": { "type": "string", "description": "工作階段目前正在做什麼的人類可讀描述" }, "project": { "$ref": "#/$defs/ProjectInfo", "description": "此工作階段的伺服器擁有專案" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "工作階段代理程式具有工具存取權的工作目錄，由\n`session/workingDirectorySet` / `session/workingDirectoryRemoved` 操作\n維護。目錄為**平等的同儕** — 工作階段沒有主要目錄。個別聊天 MAY\n透過 {@link ChatSummary.workingDirectories | 其自身的 `workingDirectories`} 限制為子集，並將其自身的某個目錄指定為主要目錄（見\n{@link ChatState.primaryWorkingDirectory}）；未設定子集的聊天會對此完整集合運作。" }, "annotations": { "$ref": "#/$defs/AnnotationsSummary", "description": "此工作階段內嵌註解通道（`ahp-session://annotations`）的\n輕量級摘要。公開以便徽章 UI 無需訂閱即可呈現註解/項目計數。\n當工作階段未公開註解通道時不存在。" }, "resource": { "$ref": "#/$defs/URI", "description": "工作階段 URI" }, "createdAt": { "type": "string", "description": "建立時間戳記（ISO 8601，例如 `\"2025-03-10T18:42:03.123Z\"`）" }, "modifiedAt": { "type": "string", "description": "上次修改時間戳記（ISO 8601，例如 `\"2025-03-10T18:42:03.123Z\"`）" }, "changes": { "$ref": "#/$defs/ChangesSummary", "description": "與此工作階段關聯之檔案變更的彙總摘要。伺服器 MAY 填入此欄位以\n提供用戶端工作階段足跡的快速一覽檢視（例如用於清單呈現），而\n無需用戶端訂閱變更集。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "伺服器定義的輕量級中繼資料，用戶端可用於工作階段呈現。協定不\n解譯這些值；生產者 SHOULD 保持有效負載小巧，因為摘要出現於\n工作階段清單與工作階段通知中。" } }, "required": [ "provider", "title", "status", "resource", "createdAt", "modifiedAt" ] }, "ChangesSummary": { "type": "object", "description": "描述與工作階段關聯之檔案變更的彙總計數。\n\n所有欄位皆為選用，讓伺服器能僅填入其成本低廉可得的指標。", "properties": { "additions": { "type": "number", "description": "跨所有變更檔案的新增行總數。" }, "deletions": { "type": "number", "description": "跨所有變更檔案的刪除行總數。" }, "files": { "type": "number", "description": "有變更的檔案數。" } } }, "AgentSelection": { "type": "object", "description": "工作階段的已選自訂代理程式。\n\n`uri` 識別特定的自訂代理程式（與透過工作階段有效自訂公開的\n{@link AgentCustomization.uri | `AgentCustomization.uri`} 相符）。消費者\n透過在工作階段的自訂樹中查找 `uri` 來解析代理程式的顯示名稱。\n\n未選取 `agent` 的訊息使用提供者的預設行為。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "穩定的代理程式 URI（與 {@link AgentCustomization.uri} 相符）。" } }, "required": [ "uri" ] }, "SessionConfigPropertySchema": { "type": "object", "description": "工作階段設定屬性描述器。\n\n以工作階段特定的顯示延伸擴充通用的 {@link ConfigPropertySchema}。", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object" ], "description": "JSON Schema：屬性類型" }, "title": { "type": "string", "description": "JSON Schema：屬性的人類可讀標籤" }, "description": { "type": "string", "description": "JSON Schema：描述／工具提示" }, "default": { "description": "JSON Schema：預設值" }, "enum": { "type": "array", "items": { "$ref": "#/$defs/JsonPrimitive" }, "description": "JSON Schema：允許的值。可為任一 JSON 類型的基本值。" }, "enumLabels": { "type": "array", "items": { "type": "string" }, "description": "顯示擴充功能：每個列舉值的人類可讀標籤（平行陣列）" }, "enumDescriptions": { "type": "array", "items": { "type": "string" }, "description": "顯示擴充功能：每個列舉值的描述（平行陣列）" }, "readOnly": { "type": "boolean", "description": "JSON Schema：當 `true` 時，屬性會顯示但使用者無法修改" }, "items": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema：陣列項目的結構描述（當 `type` 為 `'array'` 時使用）" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema" }, "description": "JSON Schema：物件屬性的屬性描述器（當 `type` 為 `'object'` 時使用）" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema：必要屬性 id 的清單（當 `type` 為 `'object'` 時使用）" }, "additionalProperties": { "$ref": "#/$defs/ConfigPropertySchema", "description": "JSON Schema：未列於 `properties` 中之額外屬性的結構描述（當 `type` 為 `'object'` 時使用）。" }, "enumDynamic": { "type": "boolean", "description": "顯示延伸：為 `true` 時，完整允許值集合過大而無法靜態列舉。用戶端\nSHOULD 使用 `sessionConfigCompletions` 根據使用者輸入取得相符值。\n`enum` 中的任何值為初始顯示用的種子/近期值。" }, "sessionMutable": { "type": "boolean", "description": "為 `true` 時，使用者可在工作階段建立後變更此屬性" } }, "required": [ "type", "title" ] }, "SessionConfigSchema": { "type": "object", "description": "描述可用工作階段設定中繼資料的 JSON Schema 物件。", "properties": { "type": { "type": "string", "enum": [ "object" ], "description": "JSON Schema：永遠為 `'object'`" }, "properties": { "type": "object", "additionalProperties": { "$ref": "#/$defs/SessionConfigPropertySchema" }, "description": "JSON Schema：以屬性 id 為鍵的屬性描述器" }, "required": { "type": "array", "items": { "type": "string" }, "description": "JSON Schema：必要屬性 id 的清單" } }, "required": [ "type", "properties" ] }, "SessionConfigState": { "type": "object", "description": "即時工作階段設定中繼資料。\n\n綱要描述可用設定屬性，而 values 包含每個已解析屬性的目前值。", "properties": { "schema": { "$ref": "#/$defs/SessionConfigSchema", "description": "描述可用設定屬性的 JSON Schema" }, "values": { "type": "object", "additionalProperties": {}, "description": "目前設定值" } }, "required": [ "schema", "values" ] }, "ToolDefinition": { "type": "object", "description": "描述工作階段中可用的工具，由伺服器或作用中用戶端提供。", "properties": { "name": { "type": "string", "description": "唯一工具識別碼" }, "title": { "type": "string", "description": "人類可讀的顯示名稱" }, "description": { "type": "string", "description": "工具功能描述" }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": { "type": "object" } }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "description": "定義預期輸入參數的 JSON Schema。\n\n選用，因為用戶端提供的工具可能沒有正式綱要。鏡射 MCP\n`Tool.inputSchema`。" }, "outputSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "object" ] }, "properties": { "type": "object", "additionalProperties": { "type": "object" } }, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "description": "定義工具輸出結構的 JSON Schema。\n\n鏡射 MCP `Tool.outputSchema`。" }, "annotations": { "$ref": "#/$defs/ToolAnnotations", "description": "關於工具的行為提示。所有屬性皆為建議性。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "額外的提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。" } }, "required": [ "name" ] }, "ToolAnnotations": { "type": "object", "description": "關於工具的行為提示。所有屬性皆為建議性，且不保證能如實描述工具\n行為。\n\n鏡射 Model Context Protocol 規範中的 MCP `ToolAnnotations`。", "properties": { "title": { "type": "string", "description": "替代的人類可讀標題" }, "readOnlyHint": { "type": "boolean", "description": "工具不修改其環境（預設：false）" }, "destructiveHint": { "type": "boolean", "description": "工具可能執行破壞性更新（預設：true）" }, "idempotentHint": { "type": "boolean", "description": "以相同引數重複呼叫沒有額外效果（預設：false）" }, "openWorldHint": { "type": "boolean", "description": "工具可能與外部實體互動（預設：true）" } } }, "CustomizationBase": { "type": "object", "description": "每個自訂變體共用的欄位。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" } }, "required": [ "id", "uri", "name" ] }, "CustomizationLoadingState": { "type": "object", "description": "容器正由主機載入。", "properties": { "kind": { "const": "loading" } }, "required": [ "kind" ] }, "CustomizationLoadedState": { "type": "object", "description": "容器載入成功。", "properties": { "kind": { "const": "loaded" } }, "required": [ "kind" ] }, "CustomizationDegradedState": { "type": "object", "description": "容器部分載入但有警告。", "properties": { "kind": { "const": "degraded" }, "message": { "type": "string", "description": "警告的人類可讀描述。" } }, "required": [ "kind", "message" ] }, "CustomizationErrorState": { "type": "object", "description": "容器載入失敗。", "properties": { "kind": { "const": "error" }, "message": { "type": "string", "description": "人類可讀的錯誤訊息。" } }, "required": [ "kind", "message" ] }, "ContainerCustomizationBase": { "type": "object", "description": "容器自訂共用的欄位。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此容器目前是否啟用。" }, "clientId": { "type": "string", "description": "貢獻此容器之用戶端的 `clientId`。伺服器發起的項目不存在。" }, "load": { "$ref": "#/$defs/CustomizationLoadState", "description": "主機回報的載入狀態。不存在表示主機尚未回報此容器的載入狀態。" }, "children": { "type": "array", "items": { "$ref": "#/$defs/ChildCustomization" }, "description": "在此容器內發現的子項。\n\n不存在表示主機尚未解析此容器。空陣列表示主機已解析容器且其未\n貢獻任何內容。" } }, "required": [ "id", "uri", "name", "enabled" ] }, "PluginCustomization": { "type": "object", "description": "一個 [Open Plugins](https://open-plugins.com/) 外掛。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此容器目前是否啟用。" }, "clientId": { "type": "string", "description": "貢獻此容器之用戶端的 `clientId`。伺服器發起的項目不存在。" }, "load": { "$ref": "#/$defs/CustomizationLoadState", "description": "主機回報的載入狀態。不存在表示主機尚未回報此容器的載入狀態。" }, "children": { "type": "array", "items": { "$ref": "#/$defs/ChildCustomization" }, "description": "在此容器內發現的子項。\n\n不存在表示主機尚未解析此容器。空陣列表示主機已解析容器且其未\n貢獻任何內容。" }, "type": { "const": "plugin" }, "version": { "type": "string", "description": "外掛版本，取自 [Open Plugins](https://open-plugins.com/) 資訊清單的\n選用 `version` 欄位（semver，例如 `\"1.2.0\"`）。當資訊清單未宣告版本\n— 該欄位在那裡為選用 — 或來源沒有版本概念時不存在。僅供出處/\n顯示之用：主機既不解析也不強制執行它。" } }, "required": [ "id", "uri", "name", "enabled", "type" ] }, "ClientPluginCustomization": { "type": "object", "description": "由用戶端發布的 {@link PluginCustomization}。以不透明的 `nonce` 擴充\n伺服器面向的形狀，讓主機能偵測用戶端的外掛檢視何時變更，並僅在\n需要時重新解析。\n\n用戶端 SHOULD 包含 `nonce`。發布時通常省略\n{@link ContainerCustomizationBase.children | `children`} 與\n{@link ContainerCustomizationBase.load | `load`} 等伺服器端欄位，\n並在解析後的外掛出現於 {@link SessionState.customizations} 時由主機\n填入。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此容器目前是否啟用。" }, "clientId": { "type": "string", "description": "貢獻此容器之用戶端的 `clientId`。伺服器發起的項目不存在。" }, "load": { "$ref": "#/$defs/CustomizationLoadState", "description": "主機回報的載入狀態。不存在表示主機尚未回報此容器的載入狀態。" }, "children": { "type": "array", "items": { "$ref": "#/$defs/ChildCustomization" }, "description": "在此容器內發現的子項。\n\n不存在表示主機尚未解析此容器。空陣列表示主機已解析容器且其未\n貢獻任何內容。" }, "type": { "const": "plugin" }, "version": { "type": "string", "description": "外掛版本，取自 [Open Plugins](https://open-plugins.com/) 資訊清單的\n選用 `version` 欄位（semver，例如 `\"1.2.0\"`）。當資訊清單未宣告版本\n— 該欄位在那裡為選用 — 或來源沒有版本概念時不存在。僅供出處/\n顯示之用：主機既不解析也不強制執行它。" }, "nonce": { "type": "string", "description": "主機用來偵測變更的不透明版本權杖。" } }, "required": [ "id", "uri", "name", "enabled", "type" ] }, "DirectoryCustomization": { "type": "object", "description": "主機為此工作階段監視的目錄。\n\n其存在於自訂清單中表示主機可從此目錄發現自訂。當 `writable` 為\n`true` 時，用戶端 MAY 使用\n[`resourceWrite`](/reference/common#resourcewrite) 將新自訂持久化至\n該目錄；主機接著會透過自訂操作公開產生的子項。\n\n該目錄在磁碟上可能尚未存在。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此容器目前是否啟用。" }, "clientId": { "type": "string", "description": "貢獻此容器之用戶端的 `clientId`。伺服器發起的項目不存在。" }, "load": { "$ref": "#/$defs/CustomizationLoadState", "description": "主機回報的載入狀態。不存在表示主機尚未回報此容器的載入狀態。" }, "children": { "type": "array", "items": { "$ref": "#/$defs/ChildCustomization" }, "description": "在此容器內發現的子項。\n\n不存在表示主機尚未解析此容器。空陣列表示主機已解析容器且其未\n貢獻任何內容。" }, "type": { "const": "directory" }, "contents": { "$ref": "#/$defs/ChildCustomizationType", "description": "此目錄持有的子自訂類型。" }, "writable": { "type": "boolean", "description": "用戶端是否可寫入此目錄。" } }, "required": [ "id", "uri", "name", "enabled", "type", "contents", "writable" ] }, "ChildCustomizationBase": { "type": "object", "description": "容器內子項自訂共用的欄位 — {@link AgentCustomization}、\n{@link SkillCustomization}、{@link PromptCustomization}、\n{@link RuleCustomization} 與 {@link HookCustomization}。\n\n{@link McpServerCustomization} 也是子項但不擴充此基礎：它永遠承載\n明確的 {@link McpServerCustomization.enabled}，因為它也可作為頂層\n自訂出現。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" } }, "required": [ "id", "uri", "name" ] }, "AgentCustomization": { "type": "object", "description": "由外掛或目錄貢獻的自訂代理程式。\n\n鏡射 [Open Plugins agent](https://open-plugins.com/agent-builders/components/agents)\n格式：一個帶有 YAML frontmatter 的 markdown 檔案，其中本文為代理\n程式的系統提示。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" }, "type": { "const": "agent" }, "description": { "type": "string", "description": "代理程式專精於什麼以及何時叫用它的簡短描述。取自代理程式檔案\nfrontmatter 的 `description`。" }, "model": { "type": "string", "description": "代理程式釘選的模型，取自代理程式檔案 frontmatter 的 `model`。\n不存在表示代理程式繼承工作階段的預設模型。" }, "tools": { "type": "array", "items": { "type": "string" }, "description": "代理程式範圍限制的工具名稱允許清單，取自代理程式檔案 frontmatter\n的 `tools`。非空清單將代理程式限制為確切那些工具。不存在 — 或\n空清單 — 不施加工作階段預設之外的任何限制：代理程式可使用任何\n可用工具。生產者透過省略該欄位而非傳送空陣列來表示「無限制」，\n因此空清單不承載與不存在不同的意義。" }, "disableModelInvocation": { "type": "boolean", "description": "為 `true` 時，代理程式不會自動委派至此自訂代理程式作為子代理程式；\n它只能由使用者選取。不存在或 `false` 表示代理程式 MAY 委派給它。" }, "disableUserInvocation": { "type": "boolean", "description": "為 `true` 時，使用者無法選取此自訂代理程式（例如在選擇器中）；\n它仍可供代理程式自動委派。不存在或 `false` 表示使用者 MAY 選取\n它。" } }, "required": [ "id", "uri", "name", "type" ] }, "SkillCustomization": { "type": "object", "description": "由外掛或目錄貢獻的技能。\n\n涵蓋兩種 [Open Plugins skill 格式](https://open-plugins.com/agent-builders/components/skills)\n— `skills/` 目錄佈局（每個技能一個子目錄，各含一個\n`SKILL.md`）與較扁平的 `commands/` 斜線指令技能目錄。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" }, "type": { "const": "skill" }, "description": { "type": "string", "description": "用於說明文字與自動叫用比對的簡短描述。取自技能 frontmatter 的\n`description`。" }, "disableModelInvocation": { "type": "boolean", "description": "為 `true` 時，僅使用者可叫用此技能 — 代理程式不會自動叫用它。\n取自指令技能 frontmatter 的 `disable-model-invocation` 旗標。" }, "disableUserInvocation": { "type": "boolean", "description": "為 `true` 時，使用者無法直接叫用此技能（例如作為斜線指令）；\n它仍可供代理程式自動叫用。不存在或 `false` 表示使用者 MAY 叫用\n它。" } }, "required": [ "id", "uri", "name", "type" ] }, "PromptCustomization": { "type": "object", "description": "由外掛或目錄貢獻的提示。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" }, "type": { "const": "prompt" }, "description": { "type": "string", "description": "提示功能的簡短描述。" } }, "required": [ "id", "uri", "name", "type" ] }, "RuleCustomization": { "type": "object", "description": "由外掛或目錄貢獻的規則。\n\n鏡射 [Open Plugins rule](https://open-plugins.com/agent-builders/components/rules)\n格式：一個 markdown 檔案（例如 `.mdc`），其本文在規則作用時注入至\n上下文。此類型也涵蓋工具特定的「instruction」格式（例如 VS Code\nCopilot 的 `.github/instructions/*.md`），其僅在命名上不同 — 它們\n共用 `description`、選用的常駐啟用與選用的 glob 範圍限制的相同語意。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" }, "type": { "const": "rule" }, "description": { "type": "string", "description": "規則所強制執行之內容的描述。" }, "alwaysApply": { "type": "boolean", "description": "為 `true` 時，規則永遠作用（受 `globs` 約束，若有）。為 `false` 或\n不存在時，由代理程式或使用者決定是否套用該規則。" }, "globs": { "type": "array", "items": { "type": "string" }, "description": "規則適用的 glob 模式。存在時，規則僅對相符檔案作用。" } }, "required": [ "id", "uri", "name", "type" ] }, "HookCustomization": { "type": "object", "description": "由外掛或目錄貢獻的掛鉤資訊清單。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "enabled": { "type": "boolean", "description": "此子項是否個別啟用。不存在表示啟用，因此生產者只需設定它即可公開\n存在但自身被關閉的子項。\n\n此旗標獨立於父容器：子項的**有效**啟用狀態為\n`container.enabled && (child.enabled ?? true)`，因此停用的容器會\n停用每個子項，無論各子項自身的旗標為何。\n\n子項以 id 透過\n{@link SessionCustomizationToggledAction | `session/customizationToggled`}\n開啟或關閉。" }, "type": { "const": "hook" } }, "required": [ "id", "uri", "name", "type" ] }, "McpServerCustomization": { "type": "object", "description": "由外掛或目錄貢獻的 MCP 伺服器。\n\n當伺服器內嵌宣告於包含的外掛資訊清單時，`uri` 指向資訊清單檔案，\n而 {@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。\n\nMCP 伺服器自訂也反映其目前狀態。", "properties": { "id": { "type": "string", "description": "工作階段內唯一的不透明識別碼。由每個以特定自訂為目標的操作使用。\n由發布該自訂的一方（通常為代理主機）鑄造。" }, "uri": { "$ref": "#/$defs/URI", "description": "此自訂的來源 URI。可以是外掛 URL、檔案 URI 或目錄 URI。\n\n對於存在於較大檔案中的宣告 — 例如內嵌於 `plugins.json` 資訊清單的\nMCP 伺服器 — `uri` 指向包含檔案，而\n{@link CustomizationBase.range | `range`} 將其縮窄至宣告的跨度。" }, "name": { "type": "string", "description": "人類可讀名稱。" }, "icons": { "type": "array", "items": { "$ref": "#/$defs/Icon" }, "description": "用於 UI 顯示的圖示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "當此自訂為較大檔案的子集時（例如 `plugins.json` 資訊清單中內嵌\n`mcpServers` 區塊的一個項目），在\n{@link CustomizationBase.uri | `uri`} 內的選用跨度。當自訂涵蓋整個\n資源時不存在。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此自訂的額外提供者特定中繼資料。\n\n鏡射 MCP `_meta` 慣例。對協定為選用且不透明；生產者與消費者\n在帶外就其內容達成共識。" }, "type": { "const": "mcpServer" }, "enabled": { "type": "boolean", "description": "此 MCP 伺服器目前是否啟用。" }, "state": { "$ref": "#/$defs/McpServerState", "description": "MCP 伺服器的目前生命週期狀態。" }, "channel": { "$ref": "#/$defs/URI", "description": "用戶端用來將流量側通道傳入上游 MCP 伺服器本身的 `mcp://` 協定\n通道。該通道並非全新的原始 MCP 連線：它搭載於 AHP 傳輸上並跳過\nMCP `initialize` 序列。\n\n代理主機 MAY 僅在此通道上提供 MCP 的子集；所提供的子集由\n領域特定能力描述，例如\n{@link McpServerCustomizationApps.capabilities} 中的那些。\n\n通道 URI SHOULD 在伺服器生命週期內穩定，但代理主機 MAY 變更它\n（例如跨重新啟動），且 MAY 僅在伺服器處於\n{@link McpServerStatus.Ready | `Ready`} 時公開它。不存在表示目前\n沒有可用的側通道。" }, "mcpApp": { "$ref": "#/$defs/McpServerCustomizationApps", "description": "MCP App 支援。對支援 apps 的 MCP 伺服器，SHOULD 公開此屬性。" } }, "required": [ "id", "uri", "name", "type", "enabled", "state" ] }, "McpServerCustomizationApps": { "type": "object", "description": "代理主機為呈現由此 MCP 伺服器提供之 MCP Apps 所需的資訊。", "properties": { "capabilities": { "$ref": "#/$defs/AhpMcpUiHostCapabilities", "description": "AHP 主機能為由此伺服器支援的 Views 滿足的 MCP App\n[`HostCapabilities`](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)\n子集。用戶端將其直接送入傳遞給 View 的 `ui/initialize` 回應的\n`hostCapabilities` 中。" } }, "required": [ "capabilities" ] }, "AhpMcpUiHostCapabilities": { "type": "object", "description": "AHP 主機可從上游 MCP 伺服器（及 AHP 自身的轉送管線）推導出的 MCP\nApp\n[`HostCapabilities`](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)\n子集。公開於 {@link McpServerCustomizationApps.capabilities}，讓用戶端\n能將其直接送入傳遞給 MCP App View 的 `ui/initialize` 回應的\n`hostCapabilities` 中。\n\n欄位名稱與 MCP Apps 規範完全一致，讓 AHP 端生產者能將其直接送入\n傳遞給 View 的 `ui/initialize` 回應的 `hostCapabilities` 中。\n\n此集合之外的能力（`openLinks`、`downloadFile`、`sandbox`、\n`experimental`）由呈現 View 的 AHP 用戶端在本機決定，且不屬於此\nAHP 層級通告的一部分 — 僅有伺服器推導的子集屬於。\n\n代理主機 MUST 僅在其確實於 `mcp://` 通道上接受對應方法/通知時通告\n某項能力：\n\n- {@link serverTools}：主機代理 `tools/list` 與 `tools/call` 至 MCP\n 伺服器。當 `listChanged` 為 `true` 時，主機也轉送\n `notifications/tools/list_changed`。\n- {@link serverResources}：主機代理 `resources/read`、\n `resources/list` 與 `resources/templates/list` 至 MCP 伺服器。當\n `listChanged` 為 `true` 時，主機也轉送\n `notifications/resources/list_changed`。\n- {@link logging}：主機接受來自 App 的 `notifications/message` 日誌\n 項目並透過 `mcpNotification` 轉送（並將 `logging/setLevel` 呼叫\n 轉送至伺服器）。\n- {@link sampling}：主機透過 `mcpMethodCall` 提供\n `sampling/createMessage`。當 `sampling.tools` 存在時，主機也接受\n `CreateMessageRequest` 內的 SEP-1577 `tools` / `toolChoice` /\n `tool_use` 內容區塊。", "properties": { "serverTools": { "type": "object", "properties": { "listChanged": { "type": "boolean" } }, "description": "生產者將 MCP `tools/*` 方法代理至上游伺服器。" }, "serverResources": { "type": "object", "properties": { "listChanged": { "type": "boolean" } }, "description": "生產者將 MCP `resources/*` 方法代理至上游伺服器。" }, "logging": { "type": "object", "additionalProperties": {}, "description": "生產者透過 `mcpNotification` 接受來自 App 的 `notifications/message` 日誌項目。" }, "sampling": { "type": "object", "properties": { "tools": { "type": "object", "additionalProperties": {} } }, "description": "生產者透過 `mcpMethodCall` 提供 `sampling/createMessage`。" } } }, "McpServerStartingState": { "type": "object", "description": "伺服器已向主機註冊但尚未啟動。", "properties": { "kind": { "const": "starting" } }, "required": [ "kind" ] }, "McpServerReadyState": { "type": "object", "description": "伺服器執行中並提供請求服務。", "properties": { "kind": { "const": "ready" } }, "required": [ "kind" ] }, "McpOAuthClient": { "type": "object", "description": "預先註冊的 OAuth 用戶端，用戶端在解決 MCP 驗證挑戰時使用它，而非\n動態用戶端註冊。", "properties": { "clientId": { "type": "string", "description": "向授權伺服器註冊的 OAuth 用戶端識別碼。" }, "clientSecret": { "type": "string", "description": "機密用戶端的 OAuth 用戶端密碼。不存在表示用戶端為公開用戶端，並\n使用如授權碼搭配 PKCE 的無密碼流程。" } }, "required": [ "clientId" ] }, "McpAuthRequirement": { "type": "object", "description": "可重複使用的 MCP 驗證挑戰 — 用戶端取得權杖並透過 `authenticate` 指令\n推送所需的 RFC 9728 探索資訊。刻意**不承載權杖**：此處描述的是所\n請求的內容，從不包含 ****** 本身。\n\n由兩個描述同一 OAuth 挑戰不同觀點的獨立狀態機共用：\n\n- {@link McpServerAuthRequiredState} — MCP 伺服器本身在用戶端驗證前\n 無法服務*任何*請求。\n- {@link ToolCallAuthRequiredState} — 特定的進行中工具呼叫因等待\n 驗證而暫停（通常為\n {@link McpAuthRequiredReason.InsufficientScope} 執行中途的提升\n 授權）。伺服器狀態與工具呼叫狀態刻意保持分離：伺服器說「我需要\n 驗證」與工具呼叫說「我正在等待該驗證」是可獨立為真的不同事實。", "properties": { "reason": { "$ref": "#/$defs/McpAuthRequiredReason", "description": "為何需要驗證。" }, "oauthClient": { "$ref": "#/$defs/McpOAuthClient", "description": "用於授權的預先註冊 OAuth 用戶端。存在時，用戶端 MUST 使用這些\n憑證而非動態用戶端註冊。" }, "resource": { "$ref": "#/$defs/ProtectedResourceMetadata", "description": "RFC 9728 Protected Resource Metadata。`resource` 欄位為依 RFC 8707\n的標準 MCP 伺服器 URI，用作 OAuth `resource` 指示器。\n`authorization_servers` 為 MCP authorization 規範所 REQUIRED。" }, "requiredScopes": { "type": "array", "items": { "type": "string" }, "description": "目前挑戰所需的範圍，解析自\n`WWW-Authenticate: ******\"…\"` 標頭（或 `scopes_supported`\n回退值）。對下次授權請求具權威性 — 用戶端 MUST NOT 假設與\n`resource.scopes_supported` 有任何子集/超集關係。" }, "description": { "type": "string", "description": "人類可讀的提示，通常來自 OAuth `error_description`。" } }, "required": [ "reason", "resource" ] }, "McpServerAuthRequiredState": { "type": "object", "description": "伺服器可連線但在用戶端驗證前無法服務請求。鏡射\n[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)\n（Protected Resource Metadata）定義的探索流程，以及 MCP authorization\n規範所需的 OAuth 2.1 / RFC 6750 挑戰語意。\n\n用戶端透過以現有的 `authenticate` 指令呼叫，並帶上此處承載的\n{@link ProtectedResourceMetadata.resource | resource} 來回應此狀態。\nMCP 伺服器**沒有** `notify/authRequired` 通知 — 操作串流是唯一\n真相來源。\n\n當轉換是由回合期間發出的請求觸發 — 最常見為\n{@link McpAuthRequiredReason.InsufficientScope | `InsufficientScope`}\n在工具呼叫中途出現 — 主機 SHOULD 一併在工作階段上引發\n{@link SessionStatus.InputNeeded}，讓阻塞在摘要層級可見。用戶端\nSHOULD 監看任何支援執行中工具呼叫之 MCP 伺服器上的此狀態，並呈現\n與該工具呼叫繫結的明確介面（例如「授予額外存取權」提示），而非\n仰賴使用者注意到自訂的狀態徽章。", "properties": { "reason": { "$ref": "#/$defs/McpAuthRequiredReason", "description": "為何需要驗證。" }, "oauthClient": { "$ref": "#/$defs/McpOAuthClient", "description": "用於授權的預先註冊 OAuth 用戶端。存在時，用戶端 MUST 使用這些\n憑證而非動態用戶端註冊。" }, "resource": { "$ref": "#/$defs/ProtectedResourceMetadata", "description": "RFC 9728 Protected Resource Metadata。`resource` 欄位為依 RFC 8707\n的標準 MCP 伺服器 URI，用作 OAuth `resource` 指示器。\n`authorization_servers` 為 MCP authorization 規範所 REQUIRED。" }, "requiredScopes": { "type": "array", "items": { "type": "string" }, "description": "目前挑戰所需的範圍，解析自\n`WWW-Authenticate: ******\"…\"` 標頭（或 `scopes_supported`\n回退值）。對下次授權請求具權威性 — 用戶端 MUST NOT 假設與\n`resource.scopes_supported` 有任何子集/超集關係。" }, "description": { "type": "string", "description": "人類可讀的提示，通常來自 OAuth `error_description`。" }, "kind": { "const": "authRequired" } }, "required": [ "reason", "resource", "kind" ] }, "McpServerErrorState": { "type": "object", "description": "伺服器啟動失敗、崩潰或以其他方式轉換至無法恢復的錯誤。驗證失敗\n請使用 {@link McpServerStatus.AuthRequired}。", "properties": { "kind": { "const": "error" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "錯誤詳細資訊。" } }, "required": [ "kind", "error" ] }, "McpServerStoppedState": { "type": "object", "description": "伺服器已關閉。主機 MAY 在此狀態後不久將伺服器從工作階段中完全\n移除。", "properties": { "kind": { "const": "stopped" } }, "required": [ "kind" ] }, "ChatState": { "type": "object", "description": "單一聊天的完整狀態，於用戶端訂閱該聊天的 URI 時載入。\n\n聊天的輕量目錄表示為 {@link ChatSummary}，承載於\n{@link SessionState.chats | `SessionState.chats`}。`ChatState` 將每個\n{@link ChatSummary} 欄位直接 **反正規化** 到自身，讓訂閱者收到單一\n扁平物件，而不需合併巢狀的 `summary` 子物件。產生者 MUST 保持兩個\n表示一致：下方內嵌欄位的任何變更，也 SHOULD 透過相符的\n{@link SessionChatUpdatedAction | `session/chatUpdated`} 操作在父工作階段上發布。", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "聊天 URI" }, "title": { "type": "string", "description": "聊天標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前的聊天狀態（沿用 SessionStatus 形狀）" }, "activity": { "type": "string", "description": "此聊天目前正在做什麼的人類可讀描述" }, "modifiedAt": { "type": "string", "description": "上次修改時間戳記（ISO 8601，例如 `\"2025-03-10T18:42:03.123Z\"`）" }, "origin": { "$ref": "#/$defs/ChatOrigin", "description": "此聊天如何產生" }, "interactivity": { "$ref": "#/$defs/ChatInteractivity", "description": "使用者可如何與此聊天互動。參見 {@link ChatInteractivity}。\n\n支援代理程式團隊模式，其中工作者聊天為唯讀或隱藏。當此欄位缺省時，\n為向後相容預設為 {@link ChatInteractivity.Full}。" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "此聊天的代理程式具有工具存取權的工作階段\n{@link SessionState.workingDirectories | `workingDirectories`} 子集。每個\n項目 MUST 存在於所屬工作階段的 `workingDirectories` 中；伺服器 MUST 拒絕\n違反此限制的 `chat/workingDirectorySet` 操作。\n\n當缺省時，聊天會繼承完整的工作階段集合。當存在但為空（不建議）時，\n聊天完全沒有工作目錄工具存取權。\n\n分派 `chat/workingDirectorySet` / `chat/workingDirectoryRemoved` 以\n更新執行中聊天上的子集。" }, "primaryWorkingDirectory": { "$ref": "#/$defs/URI", "description": "聊天的主要工作目錄 — 此聊天所居中的特殊根目錄（例如此聊天的代理程式\n行程根目錄、相對路徑的預設位置）。MUST 為此聊天的有效工作目錄之一\n（{@link workingDirectories}，或當缺省時為工作階段的集合）。當代理程式\n廣告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時存在。\n\n**建立時即為唯讀且固定。** 其值取自\n{@link CreateChatParams.primaryWorkingDirectory}（或對於工作階段的預設\n聊天，取自 {@link CreateSessionParams.primaryWorkingDirectory}），且在\n聊天生命週期內不會改變 — 沒有操作可變動它，且它不參與\n`session/chatUpdated`。" }, "turns": { "type": "array", "items": { "$ref": "#/$defs/Turn" }, "description": "已完成的回合" }, "turnsNextCursor": { "type": "string", "description": "用於將較舊的已完成回合載入此聊天狀態的游標。\n\n存在時表示 `turns` 為尾端視窗，且有更多歷史回合可用。將此不透明\n游標傳遞給 `fetchTurns`；主機 MUST 在回應前將載入的回合插入狀態，\n並更新或清除此游標。缺省時表示狀態包含所有保留的回合。" }, "activeTurn": { "$ref": "#/$defs/ActiveTurn", "description": "目前進行中的回合" }, "steeringMessage": { "$ref": "#/$defs/PendingMessage", "description": "在適當時機注入目前回合的訊息" }, "queuedMessages": { "type": "array", "items": { "$ref": "#/$defs/PendingMessage" }, "description": "在目前回合結束後自動作為新回合傳送的訊息" }, "draft": { "$ref": "#/$defs/Message", "description": "使用者對此聊天進行中的草稿輸入 — 他們正在撰寫但尚未傳送的訊息，\n包含其 {@link Message.model | model} / {@link Message.agent | agent}\n選擇與附件。\n\n用戶端 MAY 定期將其本地輸入狀態同步到此欄位，讓草稿在重新載入後存活，\n且對檢視相同聊天的其他用戶端可見。並 **不** 需要積極同步 — 用戶端\nSHOULD 去抖動，且 MAY 僅在適當時機同步。在為既有聊天呈現輸入 UI 時，\n用戶端 SHOULD 使用任何 `draft` 來初始化其輸入狀態。一旦訊息傳送即清除\n（設為 `undefined`）。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此聊天的額外提供者特定中介資料。" } }, "required": [ "resource", "title", "status", "modifiedAt", "turns" ] }, "ChatSummary": { "type": "object", "description": "聊天的輕量目錄項目，承載於 {@link SessionState.chats | `SessionState.chats`}。\n完整對話存在於 {@link ChatState}，其內嵌（反正規化）了下方所有欄位。", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "聊天 URI" }, "title": { "type": "string", "description": "聊天標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前的聊天狀態（沿用 SessionStatus 形狀）" }, "activity": { "type": "string", "description": "此聊天目前正在做什麼的人類可讀描述" }, "modifiedAt": { "type": "string", "description": "上次修改時間戳記（ISO 8601，例如 `\"2025-03-10T18:42:03.123Z\"`）" }, "origin": { "$ref": "#/$defs/ChatOrigin", "description": "此聊天如何產生" }, "interactivity": { "$ref": "#/$defs/ChatInteractivity", "description": "使用者可如何與此聊天互動。參見 {@link ChatInteractivity}。\n\n支援代理程式團隊模式，其中工作者聊天為唯讀或隱藏。當此欄位缺省時，\n為向後相容預設為 {@link ChatInteractivity.Full}。" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "此聊天使用的工作階段工作目錄子集。\n完整語意請參見 {@link ChatState.workingDirectories}。" }, "primaryWorkingDirectory": { "$ref": "#/$defs/URI", "description": "聊天的主要工作目錄。\n完整語意請參見 {@link ChatState.primaryWorkingDirectory}。" } }, "required": [ "resource", "title", "status", "modifiedAt" ] }, "SideChatSelection": { "type": "object", "description": "建立側邊聊天時擷取的不可變選取文字快照。\n\n主機在接受 `createChat` 時記錄此確切文字；之後對來源聊天的變更不會\n改變它。", "properties": { "text": { "type": "string", "description": "在接受 `createChat` 時擷取的確切選取文字快照。\n\nMUST 非空。" }, "responsePartId": { "type": "string", "description": "主機拍攝快照時，包含 {@link text} 的回應部分的選用出處資訊。\n\n僅供參考：這不是即時範圍或位移，且 MUST NOT 用於重新計算 `text`。" } }, "required": [ "text" ] }, "PendingMessage": { "type": "object", "description": "已排入佇列、待未來傳遞給代理程式的訊息。\n\n引導訊息會在進行中注入目前回合。佇列訊息會在目前回合自然結束後\n自動作為新回合啟動。", "properties": { "id": { "type": "string", "description": "此待處理訊息的唯一識別碼" }, "message": { "$ref": "#/$defs/Message", "description": "將啟動下一回合的訊息" } }, "required": [ "id", "message" ] }, "ChatInputOption": { "type": "object", "description": "選擇式問題中的一個選項。", "properties": { "id": { "type": "string", "description": "穩定的選項識別碼；對 MCP 列舉值而言此為列舉字串" }, "label": { "type": "string", "description": "顯示標籤" }, "description": { "type": "string", "description": "選用的次要文字" }, "recommended": { "type": "boolean", "description": "此選項是否為建議／預設選擇" } }, "required": [ "id", "label" ] }, "ChatInputQuestionBase": { "type": "object", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" } }, "required": [ "id", "message" ] }, "ChatInputTextQuestion": { "type": "object", "description": "聊天輸入請求中的文字問題。", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" }, "kind": { "const": "text" }, "format": { "type": "string", "description": "文字問題的格式提示，例如 `email`、`uri`、`date` 或 `date-time`" }, "min": { "type": "number", "description": "最小字串長度" }, "max": { "type": "number", "description": "最大字串長度" }, "defaultValue": { "type": "string", "description": "預設文字" } }, "required": [ "id", "message", "kind" ] }, "ChatInputNumberQuestion": { "type": "object", "description": "聊天輸入請求中的數值問題。", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" }, "kind": { "oneOf": [ { "const": "number" }, { "const": "integer" } ] }, "min": { "type": "number", "description": "最小值" }, "max": { "type": "number", "description": "最大值" }, "defaultValue": { "type": "number", "description": "預設數值" } }, "required": [ "id", "message", "kind" ] }, "ChatInputBooleanQuestion": { "type": "object", "description": "聊天輸入請求中的布林值問題。", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" }, "kind": { "const": "boolean" }, "defaultValue": { "type": "boolean", "description": "預設布林值" } }, "required": [ "id", "message", "kind" ] }, "ChatInputSingleSelectQuestion": { "type": "object", "description": "聊天輸入請求中的單選問題。", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" }, "kind": { "const": "single-select" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ChatInputOption" }, "description": "使用者可從中選取的選項" }, "allowFreeformInput": { "type": "boolean", "description": "使用者是否可改為輸入文字而不選取選項" } }, "required": [ "id", "message", "kind", "options" ] }, "ChatInputMultiSelectQuestion": { "type": "object", "description": "聊天輸入請求中的多選問題。", "properties": { "id": { "type": "string", "description": "穩定的問題識別碼，作為 `answers` 中的索引鍵" }, "title": { "type": "string", "description": "簡短顯示標題" }, "message": { "type": "string", "description": "顯示給使用者的提示" }, "required": { "type": "boolean", "description": "使用者是否必須回答此問題才能接受請求" }, "kind": { "const": "multi-select" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ChatInputOption" }, "description": "使用者可從中選取的選項" }, "allowFreeformInput": { "type": "boolean", "description": "使用者是否可在選取選項之外另輸入文字" }, "min": { "type": "number", "description": "最小選取項目數" }, "max": { "type": "number", "description": "最大選取項目數" } }, "required": [ "id", "message", "kind", "options" ] }, "ChatInputRequest": { "type": "object", "description": "由 {@link InputRequestResponsePart} 承載的請求有效負載。\n\n伺服器會以 `chat/inputRequested` 建立或取代包含的回應部分。用戶端以\n`chat/inputAnswerChanged` 同步草稿，並以 `chat/inputCompleted` 提交回應。", "properties": { "id": { "type": "string", "description": "穩定的請求識別碼" }, "message": { "type": "string", "description": "整個請求的顯示訊息" }, "url": { "$ref": "#/$defs/URI", "description": "使用者應檢閱或開啟的 URL，用於 URL 式引出" }, "questions": { "type": "array", "items": { "$ref": "#/$defs/ChatInputQuestion" }, "description": "要詢問使用者的有序問題" }, "answers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ChatInputAnswer" }, "description": "目前的草稿或已提交答案，以問題 ID 為索引鍵" } }, "required": [ "id" ] }, "ChatInputTextAnswerValue": { "type": "object", "description": "為單一答案擷取的值。", "properties": { "kind": { "const": "text" }, "value": { "type": "string" } }, "required": [ "kind", "value" ] }, "ChatInputNumberAnswerValue": { "type": "object", "properties": { "kind": { "const": "number" }, "value": { "type": "number" } }, "required": [ "kind", "value" ] }, "ChatInputBooleanAnswerValue": { "type": "object", "properties": { "kind": { "const": "boolean" }, "value": { "type": "boolean" } }, "required": [ "kind", "value" ] }, "ChatInputSelectedAnswerValue": { "type": "object", "properties": { "kind": { "const": "selected" }, "value": { "type": "string" }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "改為輸入而非選取選項的自由格式文字" } }, "required": [ "kind", "value" ] }, "ChatInputSelectedManyAnswerValue": { "type": "object", "properties": { "kind": { "const": "selected-many" }, "value": { "type": "array", "items": { "type": "string" } }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "除了選取選項之外另輸入的自由格式文字" } }, "required": [ "kind", "value" ] }, "ChatInputAnswered": { "type": "object", "properties": { "state": { "oneOf": [ { "const": "draft" }, { "const": "submitted" } ], "description": "答案狀態" }, "value": { "$ref": "#/$defs/ChatInputAnswerValue", "description": "答案值" } }, "required": [ "state", "value" ] }, "ChatInputSkipped": { "type": "object", "properties": { "state": { "const": "skipped", "description": "答案狀態" }, "freeformValues": { "type": "array", "items": { "type": "string" }, "description": "跳過時擷取的自由格式原因或值（若有）" } }, "required": [ "state" ] }, "Turn": { "type": "object", "description": "已完成的請求／回應循環。", "properties": { "id": { "type": "string", "description": "回合識別碼" }, "startedAt": { "type": "string", "description": "此回合開始時的 ISO 8601 時間戳記。" }, "duration": { "type": "number", "description": "回合持續時間，以毫秒為單位。" }, "message": { "$ref": "#/$defs/Message", "description": "啟動此回合的訊息" }, "responseParts": { "type": "array", "items": { "$ref": "#/$defs/ResponsePart" }, "description": "所有回應內容依串流順序排列：文字、工具呼叫、推理與內容參照。\n\n消費者應透過串接 markdown 部分來衍生顯示文字，並透過篩選\n`ToolCall` 部分來尋找工具呼叫。" }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "權杖使用資訊" }, "state": { "$ref": "#/$defs/TurnState", "description": "回合如何結束" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "當狀態為 `'error'` 時的錯誤細節" } }, "required": [ "id", "message", "responseParts", "usage", "state" ] }, "ActiveTurn": { "type": "object", "description": "進行中的回合 — 助理正在主動串流。", "properties": { "id": { "type": "string", "description": "回合識別碼" }, "startedAt": { "type": "string", "description": "此回合開始時的 ISO 8601 時間戳記。" }, "message": { "$ref": "#/$defs/Message", "description": "啟動此回合的訊息" }, "responseParts": { "type": "array", "items": { "$ref": "#/$defs/ResponsePart" }, "description": "所有回應內容依串流順序排列：文字、工具呼叫、推理與內容參照。\n\n當權限等待使用者核准時，工具呼叫部分會包含 `pendingPermissions`。" }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "權杖使用資訊" } }, "required": [ "id", "startedAt", "message", "responseParts", "usage" ] }, "MessageOrigin": { "type": "object", "description": "識別 {@link Message} 的起源 — 由誰產生。對於啟動回合的訊息\n（{@link Turn.message}），這也是回合的起源；對於引導或佇列訊息，\n則僅為該訊息的起源。", "properties": { "kind": { "$ref": "#/$defs/MessageKind", "description": "產生此訊息的行為者種類。" } }, "required": [ "kind" ] }, "Message": { "type": "object", "description": "啟動或引導回合的訊息。訊息可來自使用者、代理程式、工具，或由系統\n產生（參見 {@link MessageOrigin}）。\n\n附件 MAY 透過其 {@link MessageAttachmentBase.range} 欄位在\n{@link Message.text} 中被參照。沒有範圍的附件仍與訊息關聯，但不\n對應文字中的特定跨度。", "properties": { "text": { "type": "string", "description": "訊息文字" }, "origin": { "$ref": "#/$defs/MessageOrigin", "description": "訊息的起源" }, "attachments": { "type": "array", "items": { "$ref": "#/$defs/MessageAttachment" }, "description": "檔案／選取範圍附件" }, "model": { "$ref": "#/$defs/ModelSelection", "description": "此訊息已（或將）用來傳送的模型。\n\n對於歷史使用者／代理程式訊息，此記錄實際使用的模型，讓編輯或重送\n訊息的用戶端可保留該選擇。對於 {@link ChatState.draft | draft}，\n它承載使用者為其正在撰寫的訊息所挑選的模型。缺省表示套用代理主機\n的預設模型。" }, "agent": { "$ref": "#/$defs/AgentSelection", "description": "此訊息已（或將）用來傳送的自訂代理程式。\n\n對於歷史訊息，此記錄實際使用的代理程式；對於\n{@link ChatState.draft | draft}，它承載使用者挑選的代理程式。缺省\n表示無自訂代理程式 — 套用提供者的預設行為。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此訊息的額外提供者特定中介資料。\n\n用戶端 MAY 在此尋找已知的索引鍵以提供增強 UI，代理主機 MAY 用它\n承載不符合任何其他欄位的情境。鏡像 MCP 的 `_meta` 慣例。" } }, "required": [ "text", "origin" ] }, "MessageAttachmentBase": { "type": "object", "description": "所有 {@link MessageAttachment} 變體共用的欄位。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" } }, "required": [ "label" ] }, "SimpleMessageAttachment": { "type": "object", "description": "簡單、不透明的附件，其模型表示由產生者描述。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" }, "type": { "const": "simple", "description": "判別欄位" }, "modelRepresentation": { "type": "string", "description": "附件應顯示給模型的表示。\n\n若附件由用戶端產生，此屬性 MUST 已定義，讓代理主機可正確解讀附件。\n當附件源自 `completions` 回應時，MAY 省略此屬性。" } }, "required": [ "label", "type" ] }, "MessageEmbeddedResourceAttachment": { "type": "object", "description": "資料以 base64 字串內嵌的附件。\n\n將此用於應隨使用者訊息本身傳遞而非另行擷取的小型二進位有效負載\n（例如貼上的影像）。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" }, "type": { "const": "embeddedResource", "description": "判別欄位" }, "data": { "type": "string", "description": "Base64 編碼的二進位資料" }, "contentType": { "type": "string", "description": "內容 MIME 類型（例如 `\"image/png\"`、`\"application/pdf\"`）" }, "selection": { "$ref": "#/$defs/TextSelection", "description": "附加文字資源內的選用選取範圍。\n\n僅對文字資源有意義。" } }, "required": [ "label", "type", "data", "contentType" ] }, "MessageResourceAttachment": { "type": "object", "description": "依 URI 參照資源的附件。內容不會內嵌傳遞；消費者可在需要時透過\n`resourceRead` 擷取它。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" }, "uri": { "$ref": "#/$defs/URI", "description": "內容 URI" }, "sizeHint": { "type": "number", "description": "以位元組為單位的近似大小" }, "contentType": { "type": "string", "description": "內容 MIME 類型" }, "nonce": { "type": "string", "description": "內容 nonce" }, "type": { "const": "resource", "description": "判別欄位" }, "selection": { "$ref": "#/$defs/TextSelection", "description": "被參照文字資源內的選用選取範圍。\n\n僅對文字資源有意義。" } }, "required": [ "label", "uri", "type" ] }, "MessageAnnotationsAttachment": { "type": "object", "description": "參照工作階段之註解通道上之註解的附件（參見 {@link AnnotationsState}）。\n\n當 {@link annotationIds} 缺省時，附件參照通道上的每個註解；當存在時，\n僅參照列出的 {@link Annotation.id | 註解識別碼}。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" }, "type": { "const": "annotations", "description": "判別欄位" }, "resource": { "$ref": "#/$defs/URI", "description": "註解通道的 URI（通常為 `ahp-session://annotations`）。\n符合 {@link AnnotationsSummary.resource}。" }, "annotationIds": { "type": "array", "items": { "type": "string" }, "description": "要參照的特定 {@link Annotation.id | 註解識別碼}。當缺省時，附件\n參照通道上的所有註解。" } }, "required": [ "label", "type", "resource" ] }, "MessageChatAttachment": { "type": "object", "description": "透過固定已完成回合參照聊天轉錄的附件。\n\n被參照的聊天 MUST 與訊息的聊天屬於同一工作階段。主機在接受訊息時，\n從其第一個保留回合到 `endTurn`（含）解析轉錄。之後的回合不會變更\n已傳送附件所代表的情境。\n\n主機 MUST NOT 遞迴展開在參照轉錄內找到的聊天附件。用戶端 SHOULD 在\n被參照聊天之後被修剪時持續轉譯 `label`，並將開啟 `resource` 視為\n盡力而為。", "properties": { "label": { "type": "string", "description": "附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。" }, "range": { "$ref": "#/$defs/TextRange", "description": "若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字\n範圍，不是位元組範圍。" }, "displayKind": { "type": "string", "description": "轉譯此附件的用戶端的建議顯示提示。可辨識的值包含：\n\n- `'image'`：附件為影像\n- `'document'`：附件為文字文件\n- `'symbol'`：附件為程式碼符號（例如函式或類別）\n- `'directory'`：附件為資料夾\n- `'selection'`：附件為文件內的選取範圍\n\n實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的\n預設值。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "附件的額外實作定義中介資料。\n\n若附件由 `completions` 指令產生，用戶端在傳送包含已接受補全的\n使用者訊息時，MUST 保留代理主機原先傳回的 `_meta` 的每個屬性。" }, "type": { "const": "chat", "description": "判別欄位" }, "resource": { "$ref": "#/$defs/URI", "description": "被參照聊天的 URI。" }, "endTurn": { "type": "string", "description": "被參照轉錄中包含的最後一個已完成回合。" } }, "required": [ "label", "type", "resource", "endTurn" ] }, "MarkdownResponsePart": { "type": "object", "properties": { "kind": { "const": "markdown", "description": "判別欄位" }, "id": { "type": "string", "description": "部分識別碼，由 `chat/delta` 用來指定此部分進行內容附加" }, "content": { "type": "string", "description": "Markdown 內容" } }, "required": [ "kind", "id", "content" ] }, "ResourceReponsePart": { "type": "object", "description": "作為對儲存於狀態樹外之大型內容參照的內容部分。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "內容 URI" }, "sizeHint": { "type": "number", "description": "以位元組為單位的近似大小" }, "contentType": { "type": "string", "description": "內容 MIME 類型" }, "nonce": { "type": "string", "description": "內容 nonce" }, "kind": { "const": "contentRef", "description": "判別欄位" } }, "required": [ "uri", "kind" ] }, "ToolCallResponsePart": { "type": "object", "description": "表示為回應部分的工具呼叫。\n\n工具呼叫為回應串流的一部分，與文字與推理交錯。`toolCall.toolCallId`\n作為指定此部分之操作的識別碼。", "properties": { "kind": { "const": "toolCall", "description": "判別欄位" }, "toolCall": { "$ref": "#/$defs/ToolCallState", "description": "完整工具呼叫生命週期狀態" } }, "required": [ "kind", "toolCall" ] }, "ReasoningResponsePart": { "type": "object", "description": "來自模型的推理／思考內容。", "properties": { "kind": { "const": "reasoning", "description": "判別欄位" }, "id": { "type": "string", "description": "部分識別碼，由 `chat/reasoning` 用來指定此部分進行內容附加" }, "content": { "type": "string", "description": "累積的推理文字" } }, "required": [ "kind", "id", "content" ] }, "InputRequestResponsePart": { "type": "object", "description": "回合回應串流中的作用中或已解決輸入請求（引出）。\n\n伺服器以 `chat/inputRequested` 插入此部分。當 {@link response} 缺省時，\n用戶端可以 `chat/inputAnswerChanged` 更新答案草稿，並以\n`chat/inputCompleted` 提交回應。完成時會就地更新此部分，使其串流\n位置穩定，且完整互動保持持久並可透過 `fetchTurns` 回填。\n\n若回合在未提交回應的情況下結束，未解決的部分會留在已完成的回合\n轉錄中，且 {@link response} 缺省。", "properties": { "kind": { "const": "inputRequest", "description": "判別欄位" }, "request": { "$ref": "#/$defs/ChatInputRequest", "description": "請求，承載其 `id`、`message`、`url`、`questions` 與目前的草稿或\n已提交 `answers`。" }, "response": { "$ref": "#/$defs/ChatInputResponseKind", "description": "請求如何被解決。在用戶端以 `chat/inputCompleted` 提交 `accept`、\n`decline` 或 `cancel` 之前為缺省。" } }, "required": [ "kind", "request" ] }, "SystemNotificationResponsePart": { "type": "object", "description": "作為回應串流一部分呈現的系統通知。\n\n系統通知是由代理程式框架撰寫的訊息，需要對代理程式（供情境感知）\n與使用者（供轉錄連續性）皆可見。例如「背景子代理程式 X 已完成」\n或「任務 Y 已取消」。", "properties": { "kind": { "const": "systemNotification", "description": "判別欄位" }, "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "系統通知的文字" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此通知的額外提供者特定中介資料。\n\n主機 MAY 附加觸發通知之項目的機器可讀描述子，讓用戶端可在不解析\n`content` 的情況下對其分類、加圖示、分組、篩選或在地化。用戶端\nMAY 在此尋找已知的索引鍵以提供增強 UI，且當 `_meta` 缺省或無法\n辨識時，MUST 單獨從 `content` 一致地轉譯。" } }, "required": [ "kind", "content" ] }, "ToolCallRiskAssessmentBase": { "type": "object", "properties": { "kind": { "$ref": "#/$defs/ToolCallRiskAssessmentKind" } }, "required": [ "kind" ] }, "ToolCallRiskAssessmentLoadingState": { "type": "object", "description": "模型評審器仍在評估工具呼叫。", "properties": { "kind": { "$ref": "#/$defs/ToolCallRiskAssessmentKind" }, "status": { "const": "loading" } }, "required": [ "kind", "status" ] }, "ToolCallRiskAssessmentCompleteState": { "type": "object", "description": "模型評審器已完成其評估。", "properties": { "kind": { "$ref": "#/$defs/ToolCallRiskAssessmentKind" }, "status": { "const": "complete" }, "reason": { "$ref": "#/$defs/StringOrMarkdown" }, "safety": { "type": "number", "description": "評審器的正規化安全分數，其中 `0` 為不安全，`1` 為安全。" } }, "required": [ "kind", "status", "reason", "safety" ] }, "ConfirmationOption": { "type": "object", "description": "伺服器為等待核准的工具呼叫所提供的確認選項。允許超出簡單\n核准／拒絕的更豐富選擇 — 例如「在此工作階段中核准」或\n「附帶原因拒絕」。", "properties": { "id": { "type": "string", "description": "選項的唯一識別碼，於確認操作中傳回" }, "label": { "type": "string", "description": "顯示給使用者的人類可讀標籤" }, "kind": { "$ref": "#/$defs/ConfirmationOptionKind", "description": "此選項是否代表核准或拒絕" }, "group": { "type": "number", "description": "用於視覺分類的邏輯群組編號。\n\n用戶端 SHOULD 依選項定義的順序顯示選項，且 MAY 使用不同的群組\n編號在選項的邏輯叢集之間插入分隔線。" } }, "required": [ "id", "label", "kind" ] }, "ToolCallClientContributor": { "type": "object", "properties": { "kind": { "const": "client" }, "clientId": { "type": "string", "description": "若此工具由用戶端提供，為所屬用戶端的 `clientId`。伺服器端工具\n為缺省。\n\n設定時，所識別的用戶端負責執行工具並以結果分派\n`chat/toolCallComplete`。" } }, "required": [ "kind", "clientId" ] }, "ToolCallMcpContributor": { "type": "object", "properties": { "kind": { "const": "mcp" }, "customizationId": { "type": "string", "description": "在 {@link SessionState.customizations} 中對應 MCP 伺服器的自訂 ID。" } }, "required": [ "kind", "customizationId" ] }, "ToolCallBase": { "type": "object", "description": "所有工具呼叫狀態共用的中介資料。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" } }, "required": [ "toolCallId", "toolName", "displayName" ] }, "ToolCallParameterFields": { "type": "object", "description": "工具呼叫參數完全接收後可用的屬性。", "properties": { "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" } }, "required": [ "invocationMessage" ] }, "ToolCallResult": { "type": "object", "description": "工具執行結果細節，於執行完成後可用。", "properties": { "success": { "type": "boolean", "description": "工具是否成功" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "工具已執行之事的過去式描述" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "非結構化結果內容區塊。\n\n這鏡像 MCP `CallToolResult` 的 `content` 欄位。" }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "選用的結構化結果物件。\n\n這鏡像 MCP `CallToolResult` 的 `structuredContent` 欄位。" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "當工具失敗時的錯誤細節" } }, "required": [ "success", "pastTenseMessage" ] }, "ToolCallStreamingState": { "type": "object", "description": "LM 正在串流工具呼叫參數。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "status": { "const": "streaming" }, "partialInput": { "type": "string", "description": "目前為止累積的部分參數" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "參數串流時顯示的進度訊息" } }, "required": [ "toolCallId", "toolName", "displayName", "status" ] }, "ToolCallPendingConfirmationState": { "type": "object", "description": "參數已完整，或執行中的工具需要重新確認（例如執行中的權限檢查）。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "status": { "const": "pending-confirmation" }, "confirmationTitle": { "$ref": "#/$defs/StringOrMarkdown", "description": "確認提示的簡短標題（例如 `\"Run in terminal\"`、`\"Write file\"`）" }, "riskAssessment": { "$ref": "#/$defs/ToolCallRiskAssessment", "description": "促成此確認需求的風險評估。" }, "edits": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/FileEdit" } } }, "required": [ "items" ], "description": "此工具呼叫將執行的檔案編輯，供確認前預覽" }, "editable": { "type": "boolean", "description": "代理主機是否允許用戶端在確認前編輯工具的輸入參數" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ConfirmationOption" }, "description": "伺服器為此確認提供的選項。當存在時，用戶端 SHOULD 改為轉譯這些\n選項，而非單純的核准／拒絕 UI。每個選項屬於一個\n{@link ConfirmationOptionGroup}，讓用戶端仍可分類這些選擇。" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "status" ] }, "ToolCallPostConfirmationFields": { "type": "object", "description": "存在於確認已解決 **之後** 之每個工具呼叫狀態上的欄位：\n{@link ToolCallRunningState}、{@link ToolCallAuthRequiredState}、\n{@link ToolCallPendingResultConfirmationState} 與\n{@link ToolCallCompletedState}。`ToolCallPendingConfirmationState`\n（尚未確認）與 `ToolCallCancelledState`（拒絕路徑 — 從未執行）不\n滿足此不變式，因此它們獨立保留自己的 `selectedOption` 欄位，而非\n擴充此欄位。", "properties": { "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具如何被確認執行" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" } }, "required": [ "confirmed" ] }, "ToolCallRunningState": { "type": "object", "description": "工具正在主動執行。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具如何被確認執行" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" }, "status": { "const": "running" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "工具仍在執行時產生的部分內容。\n\n例如，終端機內容區塊讓用戶端可在工具完成前訂閱即時輸出。" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "confirmed", "status" ] }, "ToolCallAuthRequiredState": { "type": "object", "description": "執行中的工具呼叫暫停，因為支援它的 MCP 伺服器需要驗證 — 最常見為\n由 `tools/call` 請求本身觸發的 {@link McpAuthRequirement.reason |\n`insufficientScope`} 步進式驗證。只能從 {@link ToolCallRunningState}\n到達，且通常在驗證後返回該處：`running` → `auth-required` →\n`running` → …。用戶端也可改為不分派驗證，透過分派帶有 **失敗**\n結果的 `chat/toolCallComplete` 來取消呼叫，且一律直接移至\n{@link ToolCallCompletedState} — 此路徑上 `requiresResultConfirmation`\n會被忽略，因此永遠不會進入 {@link ToolCallPendingResultConfirmationState}。\n從此狀態分派的 **成功** 結果為無效，且 MUST 被化簡器作為 no-op\n拒絕／忽略，因為挑戰後執行從未恢復。\n\n這是 {@link McpServerAuthRequiredState} 的工具呼叫層級對應 — 該狀態\n表示 MCP *伺服器* 無法服務任何請求；此狀態表示 *此特定呼叫* 正在\n等待相同種類的挑戰。兩者獨立分派，且 MAY 同時為真或不同時：例如，\n由單一工具呼叫觸發的 `insufficientScope` 挑戰不必封鎖整個伺服器。\n\n由於挑戰一律透過現有的 `authenticate` 指令推送權杖來解決，此狀態\n只能源自 {@link ToolCallContributorKind.MCP | 由 MCP 伺服器貢獻} 的\n工具呼叫 — `contributor` 因此被窄化（與其他工具呼叫狀態上選用、\n多種類的 `contributor` 不同）。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallMcpContributor", "description": "貢獻此工具呼叫的 MCP 伺服器 — 一律為 MCP，絕非用戶端工具。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具如何被確認執行" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" }, "status": { "const": "auth-required" }, "auth": { "$ref": "#/$defs/McpAuthRequirement", "description": "封鎖此呼叫的驗證挑戰。" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "呼叫為驗證暫停前產生的部分內容。" } }, "required": [ "toolCallId", "toolName", "displayName", "contributor", "invocationMessage", "confirmed", "status", "auth" ] }, "ToolCallPendingResultConfirmationState": { "type": "object", "description": "工具已完成執行，等待用戶端核准結果。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "success": { "type": "boolean", "description": "工具是否成功" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "工具已執行之事的過去式描述" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "非結構化結果內容區塊。\n\n這鏡像 MCP `CallToolResult` 的 `content` 欄位。" }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "選用的結構化結果物件。\n\n這鏡像 MCP `CallToolResult` 的 `structuredContent` 欄位。" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "當工具失敗時的錯誤細節" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具如何被確認執行" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" }, "status": { "const": "pending-result-confirmation" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "success", "pastTenseMessage", "confirmed", "status" ] }, "ToolCallCompletedState": { "type": "object", "description": "工具已成功完成或發生錯誤。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "success": { "type": "boolean", "description": "工具是否成功" }, "pastTenseMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "工具已執行之事的過去式描述" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "非結構化結果內容區塊。\n\n這鏡像 MCP `CallToolResult` 的 `content` 欄位。" }, "structuredContent": { "type": "object", "additionalProperties": {}, "description": "選用的結構化結果物件。\n\n這鏡像 MCP `CallToolResult` 的 `structuredContent` 欄位。" }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ], "description": "當工具失敗時的錯誤細節" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具如何被確認執行" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" }, "status": { "const": "completed" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "success", "pastTenseMessage", "confirmed", "status" ] }, "ToolCallCancelledState": { "type": "object", "description": "工具呼叫在執行前被取消。", "properties": { "toolCallId": { "type": "string", "description": "唯一的工具呼叫識別碼" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯／記錄）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之事的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "對被呼叫工具之貢獻者的參照。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中介資料。\n\n這 MAY 包含對應至 MCP 工具呼叫中 MCP Apps (SEP-1865)\n`McpUiToolMeta` 的 `ui` 欄位，可與 {@link contributor} 結合使用以\n服務 MCP Apps。" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行什麼的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "status": { "const": "cancelled" }, "reason": { "$ref": "#/$defs/ToolCallCancellationReason", "description": "工具為何被取消" }, "reasonMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "解釋取消的選用訊息" }, "userSuggestion": { "$ref": "#/$defs/Message", "description": "使用者建議改為執行的動作" }, "selectedOption": { "$ref": "#/$defs/ConfirmationOption", "description": "使用者所選的確認選項（若有提供確認選項）" } }, "required": [ "toolCallId", "toolName", "displayName", "invocationMessage", "status", "reason" ] }, "ToolResultTextContent": { "type": "object", "description": "工具結果中的文字內容。\n\n鏡像 MCP `TextContent`。", "properties": { "type": { "const": "text" }, "text": { "type": "string", "description": "文字內容" } }, "required": [ "type", "text" ] }, "ToolResultEmbeddedResourceContent": { "type": "object", "description": "內嵌於工具結果的 Base64 編碼二進位內容。\n\n鏡像 MCP `EmbeddedResource`（用於內嵌二進位資料）。", "properties": { "type": { "const": "embeddedResource" }, "data": { "type": "string", "description": "Base64 編碼的資料" }, "contentType": { "type": "string", "description": "內容類型（例如 `\"image/png\"`、`\"application/pdf\"`）" } }, "required": [ "type", "data", "contentType" ] }, "ToolResultResourceContent": { "type": "object", "description": "對儲存於工具結果外之資源的參照。\n\n包裝 {@link ContentRef} 以延遲載入大型結果。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "內容 URI" }, "sizeHint": { "type": "number", "description": "以位元組為單位的近似大小" }, "contentType": { "type": "string", "description": "內容 MIME 類型" }, "nonce": { "type": "string", "description": "內容 nonce" }, "type": { "const": "resource" } }, "required": [ "uri", "type" ] }, "ToolResultFileEditContent": { "type": "object", "description": "描述工具執行的檔案修改。", "properties": { "before": { "type": "object", "properties": { "uri": { "$ref": "#/$defs/URI" }, "content": { "$ref": "#/$defs/ContentRef" } }, "required": [ "uri", "content" ], "description": "編輯前的檔案狀態。檔案建立或就地檔案編輯時不存在。" }, "after": { "type": "object", "properties": { "uri": { "$ref": "#/$defs/URI" }, "content": { "$ref": "#/$defs/ContentRef" } }, "required": [ "uri", "content" ], "description": "編輯後的檔案狀態。檔案刪除時不存在。" }, "diff": { "type": "object", "properties": { "added": { "type": "number" }, "removed": { "type": "number" } }, "description": "選用的差異顯示中繼資料" }, "type": { "const": "fileEdit" } }, "required": [ "type" ] }, "ToolResultTerminalContent": { "type": "object", "description": "對輸出與此工具結果相關之終端機的參照。\n\n用戶端可訂閱終端機的 URI 以即時串流其輸出，在工具執行時提供即時\n回饋。\n\n當指令結束時，{@link result} 會填入完成的結果中，為未訂閱的用戶端\n保留結果。這記錄的是指令的結束，而非終端機的結束 — 終端機之後\n可能會繼續執行。", "properties": { "type": { "const": "terminal" }, "resource": { "$ref": "#/$defs/URI", "description": "終端機 URI（可訂閱以取得完整終端機狀態）" }, "title": { "type": "string", "description": "終端機內容的顯示標題" }, "isPty": { "type": "boolean", "description": "此終端機式資源是否由偽終端機支援。當 `false` 時，輸出為純文字，\n且用戶端不需解析 VT 序列。" }, "result": { "$ref": "#/$defs/TerminalCommandResult", "description": "指令的結果，於其結束後存在。" } }, "required": [ "type", "resource", "title" ] }, "TerminalCommandResult": { "type": "object", "description": "在終端機式工具中執行之指令的結果，於指令結束時填入\n{@link ToolResultTerminalContent.result}。", "properties": { "exitCode": { "type": "number", "description": "已完成指令的結束代碼（若執行階段有回報）" }, "preview": { "type": "string", "description": "指令輸出的預覽，供未訂閱終端機或在其處置後才抵達的用戶端使用。\n當 `isPty` 為 `true` 時，預覽可能包含 VT 序列；當 `false` 時為\n純文字。" }, "truncated": { "type": "boolean", "description": "`preview` 是否已知為不完整或已截斷" } } }, "ToolResultSubagentContent": { "type": "object", "description": "內嵌於工具結果中的參照，指向由工具呼叫產生的工作者聊天（子代理程式\n委派），由聊天 URI（`ahp-chat:/...`）參照。\n\n這是產生工具呼叫對工作者的正向檢視。工作者聊天透過其\n{@link ChatOrigin}（`kind: 'tool'`）反向記錄相同的邊，其 `toolCallId`\n識別發出此內容的工具呼叫。", "properties": { "type": { "const": "subagent" }, "resource": { "$ref": "#/$defs/URI", "description": "工作者聊天 URI（可訂閱以取得完整聊天狀態）" }, "title": { "type": "string", "description": "子代理程式的顯示標題" }, "agentName": { "type": "string", "description": "內部代理程式名稱" }, "description": { "type": "string", "description": "子代理程式任務的人類可讀描述" } }, "required": [ "type", "resource", "title" ] }, "TerminalInfo": { "type": "object", "description": "在根狀態上公開的輕量終端機中繼資料。", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "終端機 URI（可訂閱以取得完整終端機狀態）" }, "title": { "type": "string", "description": "人類可讀的終端機標題" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "目前誰持有此終端機" }, "exitCode": { "type": "number", "description": "行程結束代碼（若終端機行程已結束）" } }, "required": [ "resource", "title", "claim" ] }, "TerminalClientClaim": { "type": "object", "description": "由已連線的用戶端聲明的終端機。", "properties": { "kind": { "const": "client", "description": "判別欄位" }, "clientId": { "type": "string", "description": "聲明此終端機之用戶端的 `clientId`" } }, "required": [ "kind", "clientId" ] }, "TerminalSessionClaim": { "type": "object", "description": "由工作階段聲明的終端機，可選擇性地限定到特定回合或工具呼叫。", "properties": { "kind": { "const": "session", "description": "判別欄位" }, "session": { "$ref": "#/$defs/URI", "description": "聲明此終端機的工作階段 URI" }, "turnId": { "type": "string", "description": "工作階段內的選用回合識別碼" }, "toolCallId": { "type": "string", "description": "回合內的選用工具呼叫識別碼" } }, "required": [ "kind", "session" ] }, "TerminalState": { "type": "object", "description": "單一終端機的完整狀態，當用戶端訂閱終端機的 URI 時載入。", "properties": { "title": { "type": "string", "description": "人類可讀的終端機標題" }, "cwd": { "$ref": "#/$defs/URI", "description": "終端機行程的當前工作目錄" }, "cols": { "type": "number", "description": "終端機寬度（以欄為單位）" }, "rows": { "type": "number", "description": "終端機高度（以列為單位）" }, "content": { "type": "array", "items": { "$ref": "#/$defs/TerminalContentPart" }, "description": "具類型的內容片段，取代平坦的 `content: string`。\n\n只需要原始 VT 串流的簡易消費者可用以下方式重建它：\n `content.map(p => p.type === 'command' ? p.output : p.value).join('')`\n\n需要指令邊界的消費者可依片段類型篩選。" }, "exitCode": { "type": "number", "description": "行程結束代碼，於終端機行程結束時設定" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "目前誰持有此終端機" }, "supportsCommandDetection": { "type": "boolean", "description": "此終端機是否發出 `terminal/commandExecuted` 與\n`terminal/commandFinished` 操作並填入 `command` 類型的片段。\n\n用戶端 MUST 在依賴指令偵測前檢查此旗標。\n切勿以 `command` 片段的存在與否作為功能旗標 — 片段\n在正常閒置狀態下是不存在的。" }, "isPty": { "type": "boolean", "description": "此終端機風格資源是否由虛擬終端機支撐。\n當值為 `false` 時，輸出為純文字，用戶端不需要解析\nVT 序列。" } }, "required": [ "title", "content", "claim" ] }, "TerminalUnclassifiedPart": { "type": "object", "description": "非結構化的終端機輸出 — 指令之前、之間或之後的內容，\n或來自不支援指令偵測的終端機。", "properties": { "type": { "type": "string", "enum": [ "unclassified" ] }, "value": { "type": "string", "description": "累積的 VT 輸出。當沒有指令執行時，由 `terminal/data` 附加至此。" } }, "required": [ "type", "value" ] }, "TerminalCommandPart": { "type": "object", "description": "單一指令：其命令列與其產生的輸出。\n\n當 `isComplete` 為 false 時，指令仍在執行；隨著 `terminal/data`\n操作抵達，`output` 會增長。在 `terminal/commandFinished` 時，此片段\n會就地變動為 `isComplete: true` 並帶有完成中繼資料。", "properties": { "type": { "type": "string", "enum": [ "command" ] }, "commandId": { "type": "string", "description": "穩定識別碼，與對應的 `terminal/commandExecuted` 與\n`terminal/commandFinished` 操作上的 `commandId` 相符。" }, "commandLine": { "type": "string", "description": "提交給 shell 的命令列。" }, "output": { "type": "string", "description": "累積的 VT 輸出。當 `isComplete` 為 false 時，由 `terminal/data` 附加至此。\nshell 整合逸出序列由伺服器剝除。" }, "timestamp": { "type": "number", "description": "執行開始時的 Unix 時間戳記（毫秒），由伺服器回報。" }, "isComplete": { "type": "boolean", "description": "指令是否已完成。" }, "exitCode": { "type": "number", "description": "shell 結束代碼。於完成時設定。未知時為 `undefined`。" }, "durationMs": { "type": "number", "description": "實際耗時（毫秒）。於完成時設定。" } }, "required": [ "type", "commandId", "commandLine", "output", "timestamp", "isComplete" ] }, "Changeset": { "type": "object", "description": "目錄項目，描述伺服器可為工作階段產生的單一變更集。\n\n目錄項目刻意保持輕量 — 僅足以在未訂閱的情況下呈現晶片或清單列。\n完整的每個變更集詳情（{@link ChangesetState}）位於可透過展開\n{@link uriTemplate} 取得的可訂閱 URI 上。", "properties": { "label": { "type": "string", "description": "人類可讀的標籤，例如 `\"Uncommitted Changes\"`。" }, "uriTemplate": { "type": "string", "description": "RFC 6570 URI 樣板。用戶端使用標準的 `{name}` 語法直接從樣板中\n解析變數 — 變數不在此重新宣告。\n\n本協定僅定義以下樣板形式；任何其他變數名稱 MUST 被用戶端忽略\n（沒有協定定義的方式可取得未知變數的值）：\n\n| 樣板中的變數 | 意義 |\n| ------------------------------------------- | ------------------------------------------------------------------------------------ |\n| _(無)_ | 靜態的、整個工作階段範圍的變更集。樣板本身即為可訂閱的 URI。 |\n| `{turnId}` | 每回合切片。以工作階段中的 `Turn.id` 展開。 |\n| `{originalTurnId}` 與 `{modifiedTurnId}` | 兩個回合間的差異。兩個變數 MUST 同時存在。 |\n\n未來的協定版本 MAY 新增新的已知變數。" }, "description": { "type": "string", "description": "選用的較長描述。" }, "changeKind": { "type": "string", "description": "建議性提示，描述此變更集的種類，讓用戶端可以在不解析\n{@link uriTemplate} 的情況下分組、排序或呈現適當的圖示。已知的值包含：\n\n- `'session'`：靜態的、整個工作階段範圍的變更集，涵蓋代理程式\n 在此工作階段中產生的所有變更。\n- `'branch'`：相對於基準分支的變更（例如將功能分支與 `main` 做\n 差異比對）。\n- `'uncommitted'`：工作區當前未提交的變更。\n- `'turn'`：由單一回合產生的變更。通常與 {@link uriTemplate} 中的\n `{turnId}` 變數搭配。\n- `'compare-turns'`：兩個回合間的差異。通常與 {@link uriTemplate} 中的\n `{originalTurnId}` 與 `{modifiedTurnId}` 變數搭配。\n\n實作 MAY 提供額外的值；當遇到未知值時，用戶端 SHOULD 退回到\n合理的預設值。" }, "capabilities": { "$ref": "#/$defs/ChangesetCapabilities", "description": "此變更集的選用能力宣告。不存在（或為空物件）表示此變更集未公告任何\n選用能力。\n\n由於目錄項目會預先隨 {@link ChangesetState | 工作階段的變更集清單}\n傳遞，用戶端可在未先訂閱變更集 URI 的情況下決定是否呈現受能力閘控的\nUI（例如審核勾選框）。這反映了 `ClientCapabilities` 的\n存在旗標慣例。" } }, "required": [ "label", "uriTemplate", "changeKind" ] }, "ChangesetCapabilities": { "type": "object", "description": "變更集在其目錄 {@link Changeset} 項目上公告的選用能力。\n\n每個欄位都是一個存在旗標：空物件 `{}` 表示「支援」，\n不存在表示「不支援」。個別能力上的子欄位保留供未來的個別能力選項使用。", "properties": { "review": { "type": "object", "additionalProperties": {}, "description": "此變更集支援每檔案的 **審核** 工作流程。宣告後，用戶端 MAY 對每個檔案\n呈現 GitHub 風格的 \"Viewed\" 切換器，並分派\n{@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`}\n來設定每個檔案的 {@link ChangesetFile.reviewed} 旗標。未處理此項的\n用戶端 MUST 將此變更集視為不可審核。" } } }, "ChangesetState": { "type": "object", "description": "單一變更集的完整狀態，於用戶端訂閱展開後的變更集 URI 時回傳。\n\n用戶端已知其訂閱的 URI，因此此狀態不會冗餘地攜帶它（或目錄的\n`id`、`label` 等）。彙總計數（`additions`、`deletions`、`files`）\n也同樣省略：用戶端可輕易地從 `files[].edit.diff` 計算它們。", "properties": { "status": { "$ref": "#/$defs/ChangesetStatus", "description": "運算生命週期。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "若且唯若 `status === ChangesetStatus.Error` 時存在。" }, "files": { "type": "array", "items": { "$ref": "#/$defs/ChangesetFile" }, "description": "此變更集中的檔案，以 {@link ChangesetFile.id} 為鍵。" }, "operations": { "type": "array", "items": { "$ref": "#/$defs/ChangesetOperation" }, "description": "用戶端可對此變更集叫用的操作。當沒有可用操作時省略。" } }, "required": [ "status", "files" ] }, "ChangesetFile": { "type": "object", "description": "{@link ChangesetState} 內的單一檔案項目。", "properties": { "id": { "type": "string", "description": "變更集內的穩定識別碼。通常為 `after.uri`\n（刪除時則為 `before.uri`）。" }, "edit": { "$ref": "#/$defs/FileEdit", "description": "重用既有的 {@link FileEdit} 形狀。用戶端從中推導出新增行、刪除行，\n以及重新命名/建立/刪除的語意。" }, "reviewed": { "type": "boolean", "description": "審核者是否已將此檔案標記為已審核（GitHub 風格的 \"Viewed\" 勾選框）。\n不存在等同於 `false` — 用戶端 MUST 將缺少的值視為尚未審核。\n\n需要變更集公告 {@link ChangesetCapabilities.review}。用戶端透過分派\n{@link ChangesetFilesReviewChangedAction | `changeset/filesReviewChanged`}\n來切換它；伺服器 MAY 也自行產生它（例如代理程式自我審核其自身的\n輸出）。\n\n協定中沒有內容版本，因此當檔案內容在穩定識別碼下變更時，審核 **不會**\n自動重設。伺服器是變更內容的權威者，會明確地重設審核 — 作法是\n重新發出檔案（透過 {@link ChangesetFileSetAction} 或\n{@link ChangesetContentChangedAction}）而不帶 `reviewed: true`，或是\n分派 `changeset/filesReviewChanged` 並帶 `reviewed: false`。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "伺服器定義的不透明中繼資料，會呈現給操作與工具，\n但不會由協定詮釋。" } }, "required": [ "id", "edit" ] }, "ChangesetOperation": { "type": "object", "description": "伺服器宣告、用戶端可對變更集、檔案或範圍執行的可叫用動詞 —\n`\"stage\"`、`\"revert\"`、`\"create-pr\"` 等等。\n\n刻意使用「操作」一詞，以避免與協定層級中變動狀態的\n[操作](/guide/actions) 衝突。", "properties": { "id": { "type": "string", "description": "穩定識別碼，在此變更集內唯一。" }, "label": { "type": "string", "description": "人類可讀的按鈕/選單標籤。" }, "description": { "type": "string", "description": "選用的較長描述，於滑鼠停留或工具提示時顯示。" }, "scopes": { "type": "array", "items": { "$ref": "#/$defs/ChangesetOperationScope" }, "description": "此操作可被叫用的位置。" }, "confirmation": { "$ref": "#/$defs/StringOrMarkdown", "description": "叫用前顯示的選用確認提示。存在時，用戶端 MUST 將此訊息顯示給\n使用者（通常在確認對話框中），且僅在使用者接受後才叫用此操作。\n此欄位的存在也表示此操作具破壞性 — 用戶端 SHOULD 據此為確認\n按鈕套用樣式（例如使用警告色彩）。" }, "icon": { "type": "string", "description": "選用的通用圖示提示，例如 `\"check\"`、`\"trash\"`。" }, "group": { "type": "string", "description": "選用的群組識別碼，用於將相關操作分組在一起。" }, "status": { "$ref": "#/$defs/ChangesetOperationStatus", "description": "目前的執行狀態。當叫用正在進行時，伺服器會設定為\n{@link ChangesetOperationStatus.Running | Running}；當最近一次叫用\n失敗時設為 {@link ChangesetOperationStatus.Error | Error}；其餘情況\n設為 {@link ChangesetOperationStatus.Idle | Idle}。\n\n用戶端 SHOULD 在 UI 中反映此狀態 — 例如在 `Running` 時停用控制項\n或顯示旋轉圖示，並在 `Error` 時呈現 {@link error}。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "失敗原因。若且唯若\n`status === ChangesetOperationStatus.Error` 時存在；否則省略。" } }, "required": [ "id", "label", "scopes", "status" ] }, "AnnotationsSummary": { "type": "object", "description": "註解通道的輕量級每工作階段摘要，公開於\n{@link SessionSummary.annotations}，讓徽章 UI 無需訂閱通道本身\n即可呈現註解／條目計數。", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "擁有工作階段的可訂閱註解通道 URI\n（通常為 `ahp-session://annotations`）。即使可從工作階段\nURI 衍生而來也明確公開，讓徽章 UI 不需要知道衍生規則。" }, "annotationCount": { "type": "number", "description": "通道中 {@link Annotation} 條目的總數。" }, "entryCount": { "type": "number", "description": "跨所有註解的 {@link AnnotationEntry} 條目總數。" } }, "required": [ "resource", "annotationCount", "entryCount" ] }, "AnnotationsState": { "type": "object", "description": "工作階段註解通道的完整狀態，於用戶端訂閱\n`ahp-session://annotations` URI 時回傳。", "properties": { "annotations": { "type": "array", "items": { "$ref": "#/$defs/Annotation" }, "description": "此通道中的註解，以 {@link Annotation.id} 為鍵。" } }, "required": [ "annotations" ] }, "Annotation": { "type": "object", "description": "錨定於特定回合所產生之特定檔案的對話，\n可選擇縮小至該檔案內的某個範圍。\n\n{@link turnId} 將註解錨定至該回合所產生的檔案版本，\n如此一來，後續重寫同一檔案的回合不會悄悄使註解的錨點\n失效——用戶端可根據該回合的變更集解析 {@link resource} 與\n{@link range}。省略 {@link range} 時，註解錨定至整個檔案。\n\n每個註解 MUST 至少包含一個 {@link AnnotationEntry}。因此，\n建立註解的 {@link AnnotationsSetAction} 會攜帶其必要的第一個\n條目，而移除最後一個剩餘條目會透過 {@link AnnotationsRemovedAction}\n摺疊該註解，而非留下空的註解。", "properties": { "id": { "type": "string", "description": "註解通道內的穩定識別碼。由分派建立它的\n{@link AnnotationsSetAction} 的用戶端指派。" }, "turnId": { "type": "string", "description": "產生此註解所錨定之檔案版本的回合。\n與擁有工作階段上的 {@link Turn.id} 相符。" }, "resource": { "$ref": "#/$defs/URI", "description": "註解所錨定的檔案。" }, "range": { "$ref": "#/$defs/TextRange", "description": "註解所錨定 {@link resource} 內的範圍。省略時，\n註解錨定至整個檔案。" }, "resolved": { "type": "boolean", "description": "註解是否已解決。新建的註解一律為未解決\n（`false`）；用戶端透過分派攜帶更新旗標的\n{@link AnnotationsUpdatedAction} 將註解標記為已解決（或重新開啟），\n或在替換整個註解時使用 {@link AnnotationsSetAction}。" }, "entries": { "type": "array", "items": { "$ref": "#/$defs/AnnotationEntry" }, "description": "此註解中的條目，依分派順序排列（最舊者在前）。\nMUST 至少包含一個條目。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "由產生者定義的不透明中繼資料，公開供工具使用，\n但不由協定解讀。" } }, "required": [ "id", "turnId", "resource", "resolved", "entries" ] }, "AnnotationEntry": { "type": "object", "description": "{@link Annotation} 內的單一條目。", "properties": { "id": { "type": "string", "description": "所屬註解內的穩定識別碼。由分派引入該條目之\n{@link AnnotationsEntrySetAction}（或所屬\n{@link AnnotationsSetAction}）的用戶端指派。" }, "text": { "$ref": "#/$defs/StringOrMarkdown", "description": "條目主體。裸 `string` 會以純文字呈現；傳入\n`{ markdown: \"…\" }` 以選擇 Markdown 呈現。詳見\n{@link StringOrMarkdown}。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "由產生者定義的不透明中繼資料，公開供工具使用，\n但不由協定解讀。" } }, "required": [ "id", "text" ] }, "TelemetryCapabilities": { "type": "object", "description": "代理主機發出的 OTLP 遙測通道。\n\n每個欄位出現時，不是字面通道 URI，就是\n[RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) URI 範本，\n由用戶端展開後訂閱。缺少的欄位表示主機不發出該信號。\n\n通道 URI 使用 `ahp-otlp:` 方案。此方案識別協定\n（AHP 上的 OpenTelemetry），讓用戶端能單憑 URI 識別通道類型；\n主機可自由選擇對其實作有意義的任何授權／路徑。用戶端 MUST\n將 URI 視為不透明（除了展開下方定義的任何已知範本變數外），\n並以產生的具體 URI 訂閱。\n\n這些通道上傳遞的有效負載為 OTLP/JSON 值——\n線路形狀（`ExportLogsServiceRequest`、\n`ExportTraceServiceRequest`、`ExportMetricsServiceRequest`）詳見\n[opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)。", "properties": { "logs": { "$ref": "#/$defs/URI", "description": "OTLP 日誌記錄（`otlp/exportLogs` 通知）的通道 URI\n（或 RFC 6570 URI 範本）。\n\n下列範本變數由此協定定義；任何其他變數名稱 MUST 被用戶端\n忽略（沒有協定定義的方式可取得未知變數的值）：\n\n| 範本中的變數 | 意義 |\n| --------------------- | ------------------------------------------------------------------------------------------------------- |\n| _(無)_ | 主機不支援訂閱者端的嚴重性過濾。範本本身即為可訂閱的 URI。 |\n| `{level}` | 要傳遞的最小 OTLP 嚴重性。展開為其中一個 [OTLP `SeverityNumber`](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) 簡短名稱（不區分大小寫）：`trace`、`debug`、`info`、`warn`、`error`、`fatal`。伺服器傳遞 `severityNumber` 落在對應頻帶或以上的日誌記錄。 |\n\n主機 SHOULD 遵守展開後的 `{level}`；用戶端 MUST 仍防禦性地\n過濾，以防主機忽略該參數。未公告 `{level}` 的主機會傳遞所有\n嚴重性。\n\n未來的協定版本 MAY 新增新的已知變數（例如範圍或屬性過濾器）。" }, "traces": { "$ref": "#/$defs/URI", "description": "OTLP 追蹤（`otlp/exportTraces` 通知）的通道 URI。此協定\n版本未定義任何範本變數。" }, "metrics": { "$ref": "#/$defs/URI", "description": "OTLP 指標資料點（`otlp/exportMetrics` 通知）的通道 URI。\n此協定版本未定義任何範本變數。" } } }, "ResourceWatchState": { "type": "object", "description": "單一資源監視的完整狀態，於用戶端訂閱 `ahp-resource-watch:`\nURI 時回傳。\n\n監視器本身是無狀態的：監視器的存在是為了傳遞\n{@link ResourceWatchChangedAction} 事件。狀態僅攜帶被監視\n內容的描述子，讓重新訂閱的用戶端能在重新連線後恢復監視\n設定。", "properties": { "root": { "$ref": "#/$defs/URI", "description": "被監視的 URI。對於遞迴監視，這是子樹的根；對於非遞迴\n監視，這是單一檔案或目錄。" }, "recursive": { "type": "boolean", "description": "若監視器回報 `root` 後代的變更則為 `true`；\n若僅回報 `root` 本身的變更（且當 `root` 為目錄時，其直接\n子項）則為 `false`。" }, "excludes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "description": "選用的 glob 模式或相對於 `root` 的路徑，用於從變更回報中\n排除。" }, "includes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "description": "選用的 glob 模式或相對於 `root` 的路徑，用於限制變更回報\n範圍。省略以回報 `root` 下受 `excludes` 限制的每個變更。" } }, "required": [ "root", "recursive" ] }, "ResourceChange": { "type": "object", "description": "資源監視器觀察到的單一變更。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "變更之資源的 URI。" }, "type": { "$ref": "#/$defs/ResourceChangeType", "description": "觀察到的變更類型。" } }, "required": [ "uri", "type" ] }, "BaseParams": { "type": "object", "description": "每個指令的 params 所擴充的基底形狀。\n\n`channel` 識別該指令所針對的通道，與每個協定通知上的 `channel` 欄位互相對應。\n對於操作特定通道（工作階段、終端機或變更集）的指令，`channel` 為該通道的 URI。\n對於連線層級而非通道範圍的指令（例如 {@link InitializeParams | `initialize`}、\n{@link PingParams | `ping`}、{@link ListSessionsParams | `listSessions`}、\n`resource*` 檔案系統指令，以及 {@link AuthenticateParams | `authenticate`}），\n其 params 類型會將 `channel` 縮窄為字面根 URI `'ahp-root://'`。\n\n此不變性讓實作能藉由檢查 `params.channel` 來路由每個傳入訊息 —\n無論是請求、回應或通知 — 而無需知道各 method 的 params 形狀。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此指令所針對的通道 URI。" } }, "required": [ "channel" ] }, "PaginatedParams": { "type": "object", "description": "基於游標的分頁輸入，混入任何能對大型結果集分頁的清單指令之 params 中\n（例如 {@link ListSessionsParams | `listSessions`}）。配對的輸出為\n{@link PaginatedResult}。\n\n分頁是**不透明且基於游標的**，映照 `fetchTurns` 已用於聊天歷史記錄的形狀：\n伺服器擁有排序與鍵集，用戶端藉由在前一次請求中回傳\n{@link PaginatedResult.nextCursor} 的游標來逐頁瀏覽。\n\n每個分頁指令共用的合約：\n\n- 若要取得第一頁，請省略 `cursor`。提供 `limit` 來限制分頁大小。\n- 若結果帶有 {@link PaginatedResult.nextCursor}，表示還有更多項目 —\n 將其作為 `cursor` 回傳以取得下一頁。缺少 `nextCursor` 即代表集合已到結尾。\n- 游標是**伺服器定義且不透明的**：用戶端 MUST NOT 解析、修改或跨連線保留它們。\n 無法識別的游標 SHOULD 以 `InvalidParams` 錯誤拒絕。\n- 分頁是**完全附加的**：省略 `limit`／`cursor` 並忽略 `nextCursor` 的用戶端\n 會看到分頁前的行為（受伺服器施加的任何上限限制），而不分頁的伺服器則會忽略\n 這些輸入，並在單一頁面中回傳所有內容。", "properties": { "limit": { "type": "number", "description": "此頁面要回傳的項目數上限。伺服器 SHOULD 遵守此界限，但 MAY 回傳較少的項目，\n也 MAY 施加自己的上限。省略以讓伺服器選擇分頁大小。" }, "cursor": { "type": "string", "description": "來自前一個 {@link PaginatedResult.nextCursor} 的不透明分頁游標。省略以\n取得第一頁。游標是伺服器定義的，且 MUST 視為不透明 — 請勿解析、修改或\n跨連線保留它們。無法識別的游標 SHOULD 以 `InvalidParams` 錯誤拒絕。" } } }, "PaginatedResult": { "type": "object", "description": "基於游標的分頁輸出，由任何能對大型結果集分頁的清單指令之 result 擴充\n（例如 {@link ListSessionsResult | `listSessions`}）。關於每個分頁指令\n共用的完整分頁合約，請參見 {@link PaginatedParams}。", "properties": { "nextCursor": { "type": "string", "description": "下一頁的不透明游標。當回傳頁面之外還有更多項目時出現；缺少即代表集合已到\n結尾。將其作為 {@link PaginatedParams.cursor} 回傳以取得下一頁。" } } }, "Implementation": { "type": "object", "description": "識別一個協定實作 — 連線某一端的軟體（與組建），有別於它所承載的\n{@link AgentInfo | 代理程式角色}。在用戶端以\n{@link InitializeParams.clientInfo | `clientInfo`} 承載，在伺服器以\n{@link InitializeResult.serverInfo | `serverInfo`} 承載，映照 LSP 的\n`clientInfo`／`serverInfo` 與 MCP 的 `Implementation`。\n\n此為**僅供參考**：用於日誌、遙測、關於／狀態的呈現，以及 — 作為最後手段 —\n針對特定有問題組建的已知問題權宜措施。它**不是**功能偵測機制。功能可用性取決於\n能力模型（{@link ClientCapabilities} 與各個 `*.capabilities` 宣告）；實作\nSHOULD NOT 根據解析 {@link Implementation.version | `version`} 來決定協定行為。", "properties": { "name": { "type": "string", "description": "實作名稱，例如產品或套件識別碼。" }, "version": { "type": "string", "description": "實作版本。建議使用 [SemVer](https://semver.org) 字串，但非必要。" }, "title": { "type": "string", "description": "選用的人類可讀顯示名稱。" } }, "required": [ "name" ] }, "InitializeParams": { "type": "object", "description": "建立新連線並協商協定版本。\n這 MUST 是用戶端傳送的第一個訊息。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "protocolVersions": { "type": "array", "items": { "type": "string" }, "description": "用戶端願意使用的協定版本，依最偏好到最不偏好排序。每個項目為一個\n[SemVer](https://semver.org) `MAJOR.MINOR.PATCH` 字串（例如 `\"0.1.0\"`）。\n\n伺服器會選取一個項目，並以 `InitializeResult.protocolVersion` 回傳。\n若伺服器無法使用提供的任何版本，它 MUST 回傳錯誤碼 `-32005`\n（`UnsupportedProtocolVersion`）。" }, "clientId": { "type": "string", "description": "唯一的用戶端識別碼" }, "clientInfo": { "$ref": "#/$defs/Implementation", "description": "選用的用戶端實作識別（名稱與版本）。僅供參考 — 關於其可用與不可用的方式，\n請參見 {@link Implementation}。有別於 {@link InitializeParams.clientId | `clientId`}，\n後者是每個連線用於重新連線的不透明識別碼，而非人類可讀的實作名稱。" }, "initialSubscriptions": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "握手期間要訂閱的 URI" }, "locale": { "type": "string", "description": "IETF BCP 47 語言標籤，指出用戶端的偏好地區設定（例如 `\"en-US\"`、`\"ja\"`）。\n伺服器 SHOULD 使用此值來本地化面向使用者的字串，例如確認選項標籤。" }, "capabilities": { "$ref": "#/$defs/ClientCapabilities", "description": "選用的用戶端能力宣告。\n\n伺服器 SHOULD 僅宣佈其對應用戶端能力在此處已設定的功能。缺少代表\n「未宣告」— 伺服器 MUST 假設用戶端不支援該功能。" } }, "required": [ "channel", "protocolVersions", "clientId" ] }, "ClientCapabilities": { "type": "object", "description": "用戶端在 `initialize` 期間宣告的選用能力。\n\n每個欄位是一個存在性旗標：空的物件 `{}` 代表「支援」，缺少則代表「不支援」。\n個別能力上的子欄位保留供未來的各能力選項使用。", "properties": { "mcpApps": { "type": "object", "additionalProperties": {}, "description": "用戶端可呈現\n[MCP Apps](https://github.com/modelcontextprotocol/ext-apps) — 亦即\n它可承載 View 沙盒、對其執行 `ui/*` 協定，並代表 App 轉送 `mcp://` 通道流量。\n\n主機 SHOULD 僅在此能力被宣告時填入\n{@link McpServerCustomization.mcpApp | `McpServerCustomization.mcpApp`}\n（並公開對應的 {@link McpServerCustomization.channel | `mcp://` 通道}）。\n省略此能力的用戶端 MUST 將帶有 App 的工具呼叫視為一般的 MCP 工具呼叫。" } } }, "InitializeResult": { "type": "object", "description": "`initialize` 指令的結果。\n\n`protocolVersion` 是伺服器從用戶端的 `protocolVersions` 清單中選取的版本。\n用戶端與伺服器 MUST 在連線的其餘部分使用此版本。若伺服器無法使用提供的任何\n版本，它 MUST 回傳錯誤碼 `-32005`（`UnsupportedProtocolVersion`）而非結果。", "properties": { "protocolVersion": { "type": "string", "description": "伺服器選取的協定版本。MUST 是 `InitializeParams.protocolVersions` 中的其中\n一個項目。格式為 [SemVer](https://semver.org) `MAJOR.MINOR.PATCH` 字串\n（例如 `\"0.1.0\"`）。" }, "serverSeq": { "type": "number", "description": "目前的伺服器序號" }, "serverInfo": { "$ref": "#/$defs/Implementation", "description": "選用的伺服器實作識別（名稱與版本）。僅供參考 — 關於其可用與不可用的方式，\n請參見 {@link Implementation}。相對於\n{@link InitializeResult.protocolVersion | `protocolVersion`} 識別已協商的協定，\n`serverInfo` 則識別其背後的主機軟體。" }, "snapshots": { "type": "array", "items": { "$ref": "#/$defs/Snapshot" }, "description": "每個 `initialSubscriptions` URI 的快照" }, "defaultDirectory": { "$ref": "#/$defs/URI", "description": "建議用於遠端檔案系統瀏覽的預設目錄" }, "completionTriggerCharacters": { "type": "array", "items": { "type": "string" }, "description": "在 {@link Message} 輸入中輸入時，SHOULD 讓用戶端發出帶有\n{@link CompletionItemKind.UserMessage} 之 `completions` 請求的字元。\n通常包含如 `'@'` 或 `'/'` 等字元。" }, "terminalCommandPrefix": { "type": "string", "description": "主機在使用者 {@link Message.text} 開頭識別的前綴，作為將剩餘部分當作終端機\n指令執行的速記。目前標準化的慣例為 `\"!\"`；缺少代表主機不支援指令前綴。" }, "telemetry": { "$ref": "#/$defs/TelemetryCapabilities", "description": "主機發出的 OTLP 遙測通道（若有）。每個已填入的欄位若非字面的 `ahp-otlp:`\n通道 URI，即為用戶端在訂閱前展開的 RFC 6570 URI 範本（目前只有 `logs`\n通道定義了範本變數 `{level}`，供訂閱端進行嚴重性篩選）。用戶端 MAY 忽略\n其無法處理的訊號。" } }, "required": [ "protocolVersion", "serverSeq", "snapshots" ] }, "PingParams": { "type": "object", "description": "驗證 AHP 連線是否仍存活，並避免被閒置逾時的中介者（代理伺服器、負載平衡器等）\n關閉。\n\n無論用戶端是否已完成 `initialize` 或持有任何訂閱，伺服器都 MUST 回應。Ping 在\n任一方向都不帶有效負載；回應本身即為訊號。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] } }, "required": [ "channel" ] }, "ReconnectParams": { "type": "object", "description": "重新建立已中斷的連線。伺服器會重播遺漏的操作或提供新的快照。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "clientId": { "type": "string", "description": "原始連線的用戶端識別碼" }, "lastSeenServerSeq": { "type": "number", "description": "用戶端收到的最後一個 `serverSeq`" }, "subscriptions": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "用戶端已訂閱的 URI" } }, "required": [ "channel", "clientId", "lastSeenServerSeq", "subscriptions" ] }, "ReconnectReplayResult": { "type": "object", "description": "當伺服器能從請求的序列重播時的重新連線結果。\n\n伺服器 MUST 在回應中包含所有重播的資料。", "properties": { "type": { "const": "replay", "description": "判別欄位" }, "actions": { "type": "array", "items": { "$ref": "#/$defs/ActionEnvelope" }, "description": "自 `lastSeenServerSeq` 以來遺漏的操作信封" }, "missing": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "`ReconnectParams.subscriptions` 中伺服器無法恢復的 URI。這包括已不存在的資源\n（例如已處置的工作階段或終端機），以及用戶端不再獲許觀察的資源。用戶端\nSHOULD 將這些從其本地訂閱集合中捨棄。" } }, "required": [ "type", "actions", "missing" ] }, "ReconnectSnapshotResult": { "type": "object", "description": "當間隔超過重播緩衝區時的重新連線結果。", "properties": { "type": { "const": "snapshot", "description": "判別欄位" }, "snapshots": { "type": "array", "items": { "$ref": "#/$defs/Snapshot" }, "description": "每個訂閱的新快照" } }, "required": [ "type", "snapshots" ] }, "SubscribeParams": { "type": "object", "description": "訂閱以 URI 識別的通道。\n\n通道 MAY 帶有相關聯的狀態（例如根、工作階段、終端機），或是無狀態的\n（純粹用於串流資料的發佈／訂閱）。對於帶有狀態的通道，結果會包含快照；\n對於無狀態的通道則省略 `snapshot`。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此指令所針對的通道 URI。" }, "delivery": { "$ref": "#/$defs/SubscriptionDeliveryOptions", "description": "此訂閱的選用傳遞偏好。\n\n伺服器 MAY 使用這些偏好來緩衝並合併高頻率的更新，同時保留相同的縮減狀態。\n省略此欄位則採用伺服器的預設傳遞行為。" }, "view": { "$ref": "#/$defs/SubscribeView", "description": "針對回傳快照的選用用戶端請求形狀。\n\n不理解所請求 view 的伺服器會忽略它並回傳其預設快照。用戶端 MUST 容忍收到\n比請求更多的狀態。" } }, "required": [ "channel" ] }, "SubscribeView": { "type": "object", "description": "訂閱快照的選用用戶端請求形狀。", "properties": { "turns": { "type": "number", "description": "建議在聊天快照中公開的最近已完成回合數。\n\n伺服器 MAY 回傳比請求更多或更少的回合。省略時，主機 MUST 回傳所有保留的回合。\n當仍有較舊的回合可用時，回傳的 {@link ChatState} 會帶有 `turnsNextCursor`；\n用戶端將該游標傳給 `fetchTurns`，以要求主機將更多回合分頁納入聊天狀態。" } } }, "SubscriptionDeliveryOptions": { "type": "object", "description": "單一訂閱的建議傳遞偏好。", "properties": { "maxLatencyMs": { "type": "number", "description": "伺服器在為此訂閱緩衝／合併更新時，可刻意延遲傳遞的最大時間（以毫秒為單位）。\n\n值為 `0` 時請求立即傳遞，不進行任何刻意合併。" } } }, "SubscribeResult": { "type": "object", "description": "`subscribe` 指令的結果。\n\n當已訂閱的通道帶有相關聯的狀態時 `snapshot` 會出現，無狀態的通道則省略。", "properties": { "snapshot": { "$ref": "#/$defs/Snapshot", "description": "已訂閱通道狀態的快照（無狀態的通道會省略）" } } }, "UnsubscribeParams": { "type": "object", "description": "停止接收某個通道的更新。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "要取消訂閱的通道 URI" } }, "required": [ "channel" ] }, "DispatchActionParams": { "type": "object", "description": "射後即忘的操作分派（預寫入）。用戶端將操作樂觀地套用到本地狀態，而伺服器一旦\n接受就會以 {@link ActionEnvelope} 回傳它們。\n\n用戶端 → 伺服器的 method 名為 `dispatchAction`；伺服器的回覆會透過\n伺服器 → 用戶端的 `action` 通知抵達（params：{@link ActionEnvelope}）。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此操作所針對的通道 URI" }, "clientSeq": { "type": "number", "description": "用戶端序號" }, "action": { "$ref": "#/$defs/StateAction", "description": "要分派的操作" } }, "required": [ "channel", "clientSeq", "action" ] }, "ResourceReadParams": { "type": "object", "description": "依 URI 讀取資源的內容。\n\n內容參照以參照而非內嵌的方式儲存大型資料（影像、冗長的工具輸出），藉此讓狀態\n樹保持小巧。\n\n二進位內容（影像等）MUST 使用 `base64` 編碼。文字內容 MAY 使用 `utf-8` 編碼。\n\n如同所有 `resource*` method，`resourceRead` 是對稱的，MAY 在任一方向傳送。\n主機用它來從用戶端發佈的 URI（例如 `virtual://my-client/...` 外掛）擷取內容；\n用戶端用它來讀取主機端的檔案。無論由哪一端發起，接收端都透過相同的\n權限／`resourceRequest` 流程來強制執行存取。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "type": "string", "description": "來自 `ContentRef` 的內容 URI" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "回傳資料的偏好編碼（預設：由伺服器選擇）" } }, "required": [ "channel", "uri" ] }, "ResourceReadResult": { "type": "object", "description": "`resourceRead` 指令的結果。\n\n伺服器 SHOULD 遵守 params 中請求的 `encoding`。若伺服器無法提供請求的編碼，\n它 MUST 退回使用 `base64` 或 `utf-8`。", "properties": { "data": { "type": "string", "description": "編碼為字串的內容" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "`data` 的編碼方式" }, "contentType": { "type": "string", "description": "內容類型（例如 `\"image/png\"`、`\"text/plain\"`）" } }, "required": [ "data", "encoding" ] }, "ResourceWriteParams": { "type": "object", "description": "將內容寫入伺服器檔案系統上的檔案。\n\n二進位內容（影像等）MUST 使用 `base64` 編碼。文字內容 MAY 使用 `utf-8` 編碼。\n\n若檔案不存在，會予以建立。若檔案已存在，對現有位元組的影響取決於\n{@link ResourceWriteParams.mode}：`truncate`（預設）從所選偏移量開始覆寫、\n`append` 保留所有現有位元組並在以 EOF 為基準的位置加入 `data`，而 `insert`\n保留所有現有位元組並在以檔案開頭為基準的偏移量處拼接 `data`。\n\n如同所有 `resource*` method，`resourceWrite` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "伺服器檔案系統上的目標檔案 URI" }, "data": { "type": "string", "description": "編碼為字串的內容" }, "encoding": { "$ref": "#/$defs/ContentEncoding", "description": "`data` 的編碼方式" }, "contentType": { "type": "string", "description": "內容類型（例如 `\"text/plain\"`、`\"image/png\"`）" }, "createOnly": { "type": "boolean", "description": "若為 `true`，當檔案已存在時伺服器 MUST 失敗，而非覆寫它。適用於安全地\n建立新檔案。" }, "mode": { "$ref": "#/$defs/ResourceWriteMode", "description": "`data` 在目標檔案中的放置方式。省略時預設為 `'truncate'`（完整覆寫）。\n關於各模式的意義及其對 {@link position} 的解讀，請參見 {@link ResourceWriteMode}。" }, "position": { "type": "number", "description": "依 {@link mode} 解讀的位元組偏移量。預設為 `0`。\n- `truncate`：從檔案開頭起算，要在寫入前截斷的偏移量。\n- `append`：從 EOF 往回起算，要插入 `data` 的位元組數。\n- `insert`：從檔案開頭起算，要拼接 `data` 的偏移量。" }, "ifMatch": { "type": "string", "description": "先前由 {@link ResourceResolveResult.etag} 回傳的樂觀並行令牌。設定後，若目前\n的 `etag` 不相符，伺服器 MUST 以 `Conflict` 失敗 — 以防止 `resourceResolve`\n與後續 `resourceWrite` 之間的更新遺失。" } }, "required": [ "channel", "uri", "data", "encoding" ] }, "ResourceWriteResult": { "type": "object", "description": "`resourceWrite` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "ResourceListParams": { "type": "object", "description": "列出伺服器檔案系統上某個檔案 URI 的目錄項目。\n\n這是為了遠端資料夾挑選器及類似的 UI 而設計，這類 UI 需要讓使用者瀏覽伺服器\n的本地檔案系統。\n\n伺服器 MUST 僅在目標存在且為目錄時回傳成功。若目標不存在、不是目錄或無法\n存取，伺服器 MUST 回傳 JSON-RPC 錯誤。\n\n如同所有 `resource*` method，`resourceList` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "伺服器檔案系統上的目錄 URI" } }, "required": [ "channel", "uri" ] }, "DirectoryEntry": { "type": "object", "description": "由 `resourceList` 回傳的目錄項目。", "properties": { "name": { "type": "string", "description": "項目的基底名稱" }, "type": { "type": "string", "enum": [ "file", "directory" ], "description": "項目是檔案還是目錄" } }, "required": [ "name", "type" ] }, "ResourceListResult": { "type": "object", "description": "`resourceList` 指令的結果。", "properties": { "entries": { "type": "array", "items": { "$ref": "#/$defs/DirectoryEntry" }, "description": "直接包含在所請求目錄中的項目" } }, "required": [ "entries" ] }, "ResourceCopyParams": { "type": "object", "description": "將資源從某個 URI 複製到另一個 URI（位於伺服器的檔案系統）。\n\n若目的地已存在，除非設定了 `failIfExists`，否則會被覆寫。\n\n如同所有 `resource*` method，`resourceCopy` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "source": { "$ref": "#/$defs/URI", "description": "要從中複製的來源 URI" }, "destination": { "$ref": "#/$defs/URI", "description": "要複製到的目的地 URI" }, "failIfExists": { "type": "boolean", "description": "若為 `true`，當目的地已存在時伺服器 MUST 失敗，而非覆寫它。" } }, "required": [ "channel", "source", "destination" ] }, "ResourceCopyResult": { "type": "object", "description": "`resourceCopy` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "ResourceDeleteParams": { "type": "object", "description": "刪除伺服器檔案系統上位於某個 URI 的資源。\n\n如同所有 `resource*` method，`resourceDelete` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "要刪除的資源 URI" }, "recursive": { "type": "boolean", "description": "若為 `true` 且目標為目錄，則遞迴刪除它及其所有內容。若為 `false`（預設），\n刪除非空目錄時 MUST 失敗。" } }, "required": [ "channel", "uri" ] }, "ResourceDeleteResult": { "type": "object", "description": "`resourceDelete` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "ResourceRequestParams": { "type": "object", "description": "請求存取接收端檔案系統上某個資源的權限。\n\n`resourceRequest` 是對稱的，MAY 在任一方向傳送：用戶端要求伺服器授予對伺服器端\n資源的存取權，或伺服器要求用戶端授予對用戶端端資源的存取權。接收端決定要允許、\n拒絕，還是針對所請求的存取提示使用者。\n\n若接收端拒絕存取，它 MUST 以 `PermissionDenied`（-32009） 回應。錯誤資料 MAY\n包含一個 `ResourceRequestParams` 值，描述呼叫端需要被授予哪些存取權該操作才會\n成功；請參見 `types/errors.ts` 中的 `PermissionDeniedErrorData`。\n\n在 `resourceRequest` 成功後，呼叫端 MAY 使用對應的 `resource*` 指令（例如\n`resourceRead`、`resourceWrite`）來執行該操作。接收端 MAY 隨時撤銷存取權，只需\n在後續操作中回傳 `PermissionDenied`。\n\n`read`、`write` 或兩者 SHOULD 至少有一個設為 `true`。兩個旗標皆未設定的請求，\n接收端會視為 `read: true`。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "所請求的資源 URI。通常是接收端檔案系統上的 `file:` URI，但任何由接收端仲介\n存取的 URI 配置皆可。" }, "read": { "type": "boolean", "description": "呼叫端是否需要對該資源的讀取權。" }, "write": { "type": "boolean", "description": "呼叫端是否需要對該資源的寫入權。" } }, "required": [ "channel", "uri" ] }, "ResourceRequestResult": { "type": "object", "description": "`resourceRequest` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "ResourceMoveParams": { "type": "object", "description": "將資源從某個 URI 移動（重新命名）到另一個 URI（位於伺服器的檔案系統）。\n\n若目的地已存在，除非設定了 `failIfExists`，否則會被覆寫。\n\n如同所有 `resource*` method，`resourceMove` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "source": { "$ref": "#/$defs/URI", "description": "要從中移動的來源 URI" }, "destination": { "$ref": "#/$defs/URI", "description": "要移動到的目的地 URI" }, "failIfExists": { "type": "boolean", "description": "若為 `true`，當目的地已存在時伺服器 MUST 失敗，而非覆寫它。" } }, "required": [ "channel", "source", "destination" ] }, "ResourceMoveResult": { "type": "object", "description": "`resourceMove` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "ResourceResolveParams": { "type": "object", "description": "解析資源 — 結合 POSIX 的 `stat` 與 `realpath`。\n\n`resourceResolve` 回傳資源的中繼資料，以及符號連結解析後的標準 URI。請以此\n取代任何 `resourceExists` 的權宜措施：缺少的資源 MUST 以 `NotFound` JSON-RPC\n錯誤呈現，而非帶有哨兵值的成功回應。真正需要布林檢查的呼叫端應嘗試\n`resourceResolve`，並將 `NotFound` 視為「不存在」。\n\n如同所有 `resource*` method，`resourceResolve` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "要解析的 URI" }, "followSymlinks": { "type": "boolean", "description": "當為 `true`（預設）時，跟隨符號連結並回報連結目標的中繼資料 — 並將結果中的\n`uri` 設為標準（realpath）URI。當為 `false` 時，對連結本身執行 stat\n（lstat 語意）並回報 `type: 'symlink'`。" } }, "required": [ "channel", "uri" ] }, "ResourceResolveResult": { "type": "object", "description": "`resourceResolve` 指令的結果。", "properties": { "uri": { "$ref": "#/$defs/URI", "description": "符號連結解析後的標準 URI。當 `followSymlinks` 為 `false` 或該 URI 未穿越\n符號連結時，等於所請求的 URI。" }, "type": { "$ref": "#/$defs/ResourceType", "description": "資源種類。" }, "size": { "type": "number", "description": "以位元組為單位的大小。當提供者無法廉價地計算時，對目錄省略。" }, "mtime": { "type": "string", "description": "上次修改時間，採 ISO 8601 格式（已知時）。" }, "ctime": { "type": "string", "description": "建立時間，採 ISO 8601 格式（已知時）。" }, "contentType": { "type": "string", "description": "嗅探得到的 MIME 類型（已知時，例如 `\"text/plain\"`、`\"image/png\"`）。" }, "etag": { "type": "string", "description": "不透明的各提供者版本令牌。出現時，請將其作為 {@link ResourceWriteParams.ifMatch}\n傳入後續的 `resourceWrite`，以偵測並行的修改。" } }, "required": [ "uri", "type" ] }, "ResourceMkdirParams": { "type": "object", "description": "以 `mkdir -p` 語意在伺服器的檔案系統上建立目錄。\n\n伺服器 MUST 建立任何缺少的父目錄。建立已存在的目錄為無操作的成功。若 `uri`\n已存在但**不是**目錄，伺服器 MUST 以 `AlreadyExists` 失敗。\n\n如同所有 `resource*` method，`resourceMkdir` 是對稱的，MAY 在任一方向傳送。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "要建立的目錄 URI（視需要建立父目錄）。" } }, "required": [ "channel", "uri" ] }, "ResourceMkdirResult": { "type": "object", "description": "`resourceMkdir` 指令的結果。\n\n成功時為一個空物件。", "properties": {} }, "AuthenticateParams": { "type": "object", "description": "為受保護資源推送 ******。`resource` 欄位 MUST 符合用戶端從伺服器發現的受保護\n資源識別碼 — 無論是靜態宣告於 `AgentInfo.protectedResources`，或是從即時的\n`McpServerAuthRequiredState.resource` 或 `ToolCallAuthRequiredState.auth.resource`\n動態發現（後兩者僅在對應的 MCP 伺服器或工具呼叫實際挑戰驗證時才會浮現）。\n伺服器 MUST 接受其透過這三種機制之一所自行宣佈的任何 `resource` 值。\n\n令牌使用 [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)\n（****** 使用）語意傳遞。用戶端從資源中繼資料所列的授權伺服器取得令牌，\n並透過此指令將其推送給伺服器。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "resource": { "type": "string", "description": "受保護資源識別碼。MUST 符合伺服器已宣佈的 `resource` 值 — 透過\n`AgentInfo.protectedResources` 中的 `ProtectedResourceMetadata`，或是透過\n即時的 `McpServerAuthRequiredState.resource`／`ToolCallAuthRequiredState.auth.resource`。" }, "token": { "type": "string", "description": "從資源的授權伺服器取得的" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "令牌所授予的 OAuth 範圍（已知時）。讓伺服器能判斷某個特定挑戰 — 例如即時\n`McpServerAuthRequiredState` 或 `ToolCallAuthRequiredState.auth` 上的\n`requiredScopes` — 是否已滿足，而無需解碼（不透明、伺服器專屬的）令牌本身。\n當用戶端未將已授予的範圍與令牌分開追蹤時省略。" } }, "required": [ "channel", "resource", "token" ] }, "AuthenticateResult": { "type": "object", "description": "`authenticate` 指令的結果。\n\n成功時為一個空物件。若令牌無效或資源無法識別，伺服器 MUST 回傳 JSON-RPC\n錯誤（例如 `AuthRequired` `-32007` 或 `InvalidParams` `-32602`）。", "properties": {} }, "ListSessionsParams": { "type": "object", "description": "傳回工作階段摘要的清單。用於填入工作階段清單與側邊欄。\n\n工作階段清單 **不** 是狀態樹的一部分，因為它可能任意龐大。用戶端以命令式\n方式取得它，並維護一個由 `root/sessionAdded` 與 `root/sessionRemoved` 通知\n更新的本機快取。\n\n大型目錄可透過 {@link PaginatedParams} 的 `limit`/`cursor` 輸入以漸進方式取得\n（完整的分頁合約請參見該型別）。伺服器 SHOULD 先傳回最近修改的項目，使第一頁\n成為立即可用的一頁。`root/session*` 通知讓已取得的頁面保持最新；分頁僅控管\n初始與回填的取得。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "limit": { "type": "number", "description": "此頁面要回傳的項目數上限。伺服器 SHOULD 遵守此界限，但 MAY 回傳較少的項目，\n也 MAY 施加自己的上限。省略以讓伺服器選擇分頁大小。" }, "cursor": { "type": "string", "description": "來自前一個 {@link PaginatedResult.nextCursor} 的不透明分頁游標。省略以\n取得第一頁。游標是伺服器定義的，且 MUST 視為不透明 — 請勿解析、修改或\n跨連線保留它們。無法識別的游標 SHOULD 以 `InvalidParams` 錯誤拒絕。" } }, "required": [ "channel" ] }, "ListSessionsResult": { "type": "object", "description": "`listSessions` 指令的結果。", "properties": { "nextCursor": { "type": "string", "description": "下一頁的不透明游標。當回傳頁面之外還有更多項目時出現；缺少即代表集合已到\n結尾。將其作為 {@link PaginatedParams.cursor} 回傳以取得下一頁。" }, "items": { "type": "array", "items": { "$ref": "#/$defs/SessionSummary" }, "description": "工作階段摘要的清單。伺服器 SHOULD 將其以最近修改優先排序。" } }, "required": [ "items" ] }, "ResolveSessionConfigParams": { "type": "object", "description": "反覆解析工作階段組態結構描述。用戶端傳送目前的部分工作階段組態與任何\n使用者填入的中繼資料值。伺服器傳回一個屬性結構描述，說明在目前選取的脈絡\n下還需要哪些額外中繼資料。\n\n每當使用者變更重大輸入（例如挑選工作目錄、切換屬性）時，用戶端就會呼叫此\n指令。每次回應都會傳回完整的目前屬性集合（而非差異）。所傳回的 `values`\n包含伺服器解析後的預設值，以傳遞給 `createSession`。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "provider": { "type": "string", "description": "代理程式提供者 ID" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "工作階段的工作目錄" }, "config": { "type": "object", "additionalProperties": {}, "description": "目前使用者填入的組態值" } }, "required": [ "channel" ] }, "ResolveSessionConfigResult": { "type": "object", "description": "`resolveSessionConfig` 指令的結果。", "properties": { "schema": { "$ref": "#/$defs/SessionConfigSchema", "description": "描述給定目前脈絡下可用組態屬性的 JSON Schema" }, "values": { "type": "object", "additionalProperties": {}, "description": "目前的組態值（回送並套用伺服器解析後的預設值）" } }, "required": [ "schema", "values" ] }, "SessionConfigValueItem": { "type": "object", "description": "`sessionConfigCompletions` 傳回的單一值項目。", "properties": { "value": { "type": "string", "description": "要儲存於組態中的值" }, "label": { "type": "string", "description": "人類可讀的顯示標籤" }, "description": { "type": "string", "description": "選用的次要描述" } }, "required": [ "value", "label" ] }, "SessionConfigCompletionsParams": { "type": "object", "description": "向伺服器查詢動態工作階段組態屬性的允許值。\n\n用於 `resolveSessionConfig` 傳回之結構描述中的屬性具有\n`enumDynamic: true` 時。用戶端傳送搜尋查詢，並接收帶有顯示中繼資料的相符\n值。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "provider": { "type": "string", "description": "代理程式提供者 ID" }, "workingDirectory": { "$ref": "#/$defs/URI", "description": "工作階段的工作目錄" }, "config": { "type": "object", "additionalProperties": {}, "description": "目前使用者填入的組態值（為查詢提供脈絡）" }, "property": { "type": "string", "description": "要為其查詢值的結構描述屬性 id" }, "query": { "type": "string", "description": "搜尋篩選文字（空白或省略時傳回預設/最近值）" } }, "required": [ "channel", "property" ] }, "SessionConfigCompletionsResult": { "type": "object", "description": "`sessionConfigCompletions` 指令的結果。", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/SessionConfigValueItem" }, "description": "相符的值項目" } }, "required": [ "items" ] }, "SessionForkSource": { "type": "object", "description": "以指定的代理程式提供者建立新工作階段。\n\n若工作階段 URI 已存在，伺服器 MUST 回傳代碼為\n`-32003`（`SessionAlreadyExists`）的錯誤。\n\n建立後，用戶端應訂閱工作階段 URI 以接收狀態更新。伺服器也會向\n所有用戶端廣播 `root/sessionAdded` 通知。", "properties": { "session": { "$ref": "#/$defs/URI", "description": "要從中分叉的現有工作階段 URI" }, "turnId": { "type": "string", "description": "來源工作階段中的回合 ID；至並包含此回合回應為止的內容會被複製" } }, "required": [ "session", "turnId" ] }, "CreateSessionParams": { "type": "object", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "工作階段 URI（由用戶端選擇，例如 `ahp-session:/`）" }, "provider": { "type": "string", "description": "代理程式提供者 ID" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "工作階段代理程式被授予工具存取權的工作目錄。一個工作階段可跨越多個\n目錄；它們是平等的同儕，除非代理程式通告了\n{@link MultipleWorkingDirectoriesCapability.requiresPrimary}，此時\n應透過 {@link primaryWorkingDirectory} 將其中之一指定為主要目錄。\n\n除非代理程式通告了\n{@link AgentCapabilities.multipleWorkingDirectories}，否則用戶端 MUST NOT\n提供多個項目；不具此能力的伺服器僅將第一個項目視為工作階段的工作\n目錄，並忽略其餘項目。在工作階段啟動後，分派\n`session/workingDirectorySet` / `session/workingDirectoryRemoved` 來\n變更此集合。\n\n分叉的工作階段會忽略此欄位 — 分叉會從 `fork` 所識別的來源工作階段\n繼承其工作目錄。" }, "primaryWorkingDirectory": { "$ref": "#/$defs/URI", "description": "工作階段**預設聊天**的主要工作目錄。\n\n工作階段本身沒有主要目錄 — 主要目錄是每個聊天的概念（見\n{@link ChatState.primaryWorkingDirectory}）。但 `createSession` 會隱含\n建立工作階段的預設聊天，且沒有獨立的 `createChat` 呼叫可承載該聊天的\n建立時間欄位。因此，此欄位是用戶端唯一能在誕生時指定**預設聊天**\n主要目錄之處；它會被複製到該聊天唯讀的\n`primaryWorkingDirectory`。對任何非預設聊天，請改為傳遞\n{@link CreateChatParams.primaryWorkingDirectory}。\n\n設定時，它 MUST 是 {@link workingDirectories} 之一。當代理程式通告\n{@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時，用戶端\nSHOULD 提供此欄位；主機 MAY 拒絕省略它的建立請求，或退回使用\n`workingDirectories` 的第一個項目。分叉的工作階段會忽略此欄位\n（分叉會繼承來源工作階段的聊天及其主要目錄）。" }, "fork": { "$ref": "#/$defs/SessionForkSource", "description": "從現有工作階段分叉。新工作階段會以來源工作階段的內容填入，範圍至\n並包含指定回合的回應為止。" }, "config": { "type": "object", "additionalProperties": {}, "description": "透過 `resolveSessionConfig` 收集的代理程式特定設定值。鍵與值對應於\n伺服器回傳的綱要。" }, "activeClient": { "$ref": "#/$defs/SessionActiveClient", "description": "為新工作階段主動認領作用中用戶端角色。\n\n提供時，伺服器會以此用戶端作為作用中用戶端初始化工作階段，等同於\n在建立後立即分派 `session/activeClientSet` 操作。`clientId` MUST\n與建立用戶端在 `initialize` 中提供的 `clientId` 相符。" }, "progressToken": { "type": "string", "description": "選擇加入的進度權杖。設定時，用戶端表示願意接收伺服器為帶起此工作\n階段所做任何長時間執行工作的 `progress` 通知（見 `ProgressParams`）\n— 最顯著的是提供者原生 SDK 的延遲首次使用下載。伺服器會在每個\n`progress` 框架上回應此確切權杖，讓用戶端能將其與此\n`createSession` 呼叫（及等待它的 UI）關聯。\n\n權杖 MUST 在用戶端的作用中請求間是唯一的。伺服器 MAY 忽略它\n（例如當不需要任何長時間執行的工作時），此情況下不會發出任何\n`progress` 通知。" } }, "required": [ "channel" ] }, "DisposeSessionParams": { "type": "object", "description": "處置工作階段並清理伺服器端資源。\n\n伺服器會向所有用戶端廣播 `root/sessionRemoved` 通知。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此指令所針對的通道 URI。" } }, "required": [ "channel" ] }, "FetchTurnsParams": { "type": "object", "description": "請求主機將較舊的歷史回合載入聊天狀態。\n\n指令結果不承載回合。相反地，在回應前，主機 MUST 分派\n`chat/turnsLoaded`，將任何已載入的回合插入聊天通道的 `turns`\n狀態，置於已載入視窗之前，並更新或清除 `turnsNextCursor`。\n\n在套用任何參照目前載入視窗外回合的操作前，主機 MUST 主動將足夠的\n舊回合載入狀態，讓該操作能對有效狀態進行歸約。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "聊天 URI" }, "cursor": { "type": "string", "description": "來自 `ChatState.turnsNextCursor` 的不透明游標。\n\n主機 MUST 以 `InvalidParams` 拒絕無法辨識的游標。僅在要求主機為\n聊天（若有的話）順勢載入其下一個較舊分頁時才省略。" } }, "required": [ "channel" ] }, "FetchTurnsResult": { "type": "object", "description": "`fetchTurns` 指令的結果。", "properties": {} }, "CompletionsParams": { "type": "object", "description": "為部分輸入的內容請求補全項目（例如使用者目前正在撰寫的使用者\n訊息）。用於驅動 `@` 提及選擇器、檔案/符號參照，以及類似的內嵌\n補全體驗。\n\n伺服器 SHOULD 將此指令視為盡力而為並迅速回傳。用戶端 SHOULD 對呼叫\n進行去抖動，以避免在每次按鍵時用請求淹沒伺服器。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "請求補全的聊天 URI。" }, "kind": { "$ref": "#/$defs/CompletionItemKind", "description": "所請求的補全種類。" }, "text": { "type": "string", "description": "正在補全之輸入的完整文字（例如目前為止輸入的完整使用者訊息文字）。" }, "offset": { "type": "number", "description": "在 `text` 中請求補全的字元偏移量，以 UTF-16 碼單位測量。MUST 滿足\n`0 <= offset <= text.length`。" } }, "required": [ "channel", "kind", "text", "offset" ] }, "CompletionItem": { "type": "object", "description": "`completions` 指令回傳的單一補全項目。\n\n當使用者接受項目時，用戶端 SHOULD：\n1. 以 `insertText` 取代輸入中 `[rangeStart, rangeEnd)` 範圍\n （或省略範圍時在游標處插入 `insertText`）。\n2. 將項目的 `attachment` 與產生的 {@link Message} 關聯。", "properties": { "insertText": { "type": "string", "description": "接受此項目時插入到輸入中的文字。" }, "rangeStart": { "type": "number", "description": "若已定義，為輸入 `text` 中被 `insertText` 取代的範圍起點。此範圍\n為字元偏移量的半開區間 `[rangeStart, rangeEnd)`，以 UTF-16 碼單位\n測量。\n\n省略時，用戶端 SHOULD 在游標處插入 `insertText`。\n\n注意：此範圍參照的是*目前*輸入中的位置。附件自身的\n`rangeStart`/`rangeEnd`（若存在）參照的是項目被接受後最終\n{@link Message.text} 中的位置。" }, "rangeEnd": { "type": "number", "description": "輸入 `text` 中被 `insertText` 取代的範圍終點。見\n{@link rangeStart}。" }, "attachment": { "$ref": "#/$defs/MessageAttachment", "description": "與此補全項目關聯的附件。" } }, "required": [ "insertText", "attachment" ] }, "CompletionsResult": { "type": "object", "description": "`completions` 指令的結果。", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/CompletionItem" }, "description": "補全項目，按伺服器建議顯示的順序排列。" } }, "required": [ "items" ] }, "ForkChatSource": { "type": "object", "description": "將通過已完成回合的來源歷史複製到新聊天。", "properties": { "kind": { "const": "fork", "description": "判別欄位" }, "chat": { "$ref": "#/$defs/URI", "description": "現有來源聊天的 URI。" }, "turnId": { "type": "string", "description": "來源聊天中已完成回合的識別碼。\n\n通過此回合的內容會被複製到新聊天的可見 `turns`。" } }, "required": [ "kind", "chat", "turnId" ] }, "SideChatSource": { "type": "object", "description": "將來源上下文提供給新的側邊聊天，而不將其複製到側邊聊天的可見歷史。", "properties": { "kind": { "const": "sideChat", "description": "判別欄位" }, "chat": { "$ref": "#/$defs/URI", "description": "現有來源聊天的 URI。" }, "turnId": { "type": "string", "description": "來源聊天中穩定的來源回合識別碼。\n\n主機在接受 `createChat` 時，會將此識別碼對照來源聊天目前的 `activeTurn` 或其保留的 `turns` 來解析。若它命名的是目前的活動回合，主機會對來源聊天保留的歷史加上該回合目前的使用者訊息，以及任何已可用的部分助理回應進行快照。一旦該回合稍後成為歷史回合，仍會以這個相同的識別碼參照。" }, "selection": { "$ref": "#/$defs/SideChatSelection", "description": "選用的不可變選取文字快照，帶入所建立側邊聊天的起源。\n\n若存在，主機 MUST 在接受 `createChat` 時對此確切的選取範圍進行快照並保留；之後的來源回合差異不會改變它。" } }, "required": [ "kind", "chat", "turnId" ] }, "CreateChatParams": { "type": "object", "description": "在工作階段中建立新聊天。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "包含新聊天的工作階段 URI。" }, "chat": { "$ref": "#/$defs/URI", "description": "聊天 URI（由用戶端選擇，例如 `ahp-chat:/`）。" }, "initialMessage": { "$ref": "#/$defs/Message", "description": "新聊天的選用初始訊息。" }, "source": { "$ref": "#/$defs/ChatSource", "description": "選用的來源聊天與來源回合。\n\n來源聊天 MUST 屬於此工作階段。用戶端 MUST 僅在所選代理程式公告\n`capabilities.multipleChats.fork` 時請求 `kind: \"fork\"`，並僅在所選代理程式公告\n`capabilities.multipleChats.sideChat` 時請求 `kind: \"sideChat\"`。兩種來源形式都帶有穩定的頂層 `turnId`。分叉的目標為已完成回合。側邊聊天也帶有穩定的 `turnId`，由主機對照來源聊天目前的活動回合或保留的歷史來解析。若它解析為活動回合，主機在接受 `createChat` 時會對目前可用的部分回應進行快照。當 `source.kind === \"sideChat\"` 且 `source.selection` 存在時，主機也會在所建立聊天的起源中對該確切選取文字進行快照並保留；其中的任何 `responsePartId` 僅作為出處，並非即時範圍。" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "此聊天的初始工作目錄子集。每個項目 MUST 存在於所屬工作階段的 `workingDirectories` 中；伺服器 MUST 拒絕任何不存在的項目。若省略，聊天會繼承完整的工作階段集合。分叉聊天（`source.kind` 為 `\"fork\"` 的聊天）會繼承來源聊天的 `workingDirectories`；此欄位對分叉會被忽略。\n\n除非代理程式公告 {@link AgentCapabilities.multipleWorkingDirectories}，否則用戶端 MUST NOT 提供此欄位。" }, "primaryWorkingDirectory": { "$ref": "#/$defs/URI", "description": "聊天的主工作目錄 — 此聊天所置中的顯著根目錄。設定時，它 MUST 是聊天的有效工作目錄之一（{@link workingDirectories}，或省略時的工作階段集合）。當代理程式公告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時，用戶端 SHOULD 提供此項；主機 MAY 拒絕省略它的建立，或退回聊天的第一個目錄。建立時固定，並在 {@link ChatState.primaryWorkingDirectory} 上回報（唯讀）。對分叉會被忽略（`source.kind` 為 `\"fork\"` 的聊天會繼承來源聊天的主工作目錄）。" } }, "required": [ "channel", "chat" ] }, "DisposeChatParams": { "type": "object", "description": "處置聊天並清理伺服器端資源。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此指令所針對的通道 URI。" } }, "required": [ "channel" ] }, "CreateTerminalParams": { "type": "object", "description": "在伺服器上建立新的終端機。\n\n建立後，用戶端應訂閱終端機 URI 以接收狀態更新。伺服器分派\n`root/terminalsChanged` 以更新根終端機清單。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "終端機 URI（由用戶端選擇）。" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "終端機的初始擁有者" }, "name": { "type": "string", "description": "人類可讀的終端機名稱" }, "cwd": { "$ref": "#/$defs/URI", "description": "初始工作目錄 URI" }, "cols": { "type": "number", "description": "初始終端機寬度（以欄為單位）" }, "rows": { "type": "number", "description": "初始終端機高度（以列為單位）" } }, "required": [ "channel", "claim" ] }, "DisposeTerminalParams": { "type": "object", "description": "處置終端機，若其行程仍在執行則予以終止。\n\n伺服器分派 `root/terminalsChanged` 以從根終端機清單中移除該終端機。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此指令所針對的通道 URI。" } }, "required": [ "channel" ] }, "ChangesetOperationFollowUp": { "type": "object", "description": "操作完成後由伺服器呈現的選用後續 — 用戶端可擷取並顯示的\n{@link ContentRef}。\n\n將 `external` 設為 `true` 以在使用者偏好的外部處理器（例如瀏覽器）\n中開啟內容；否則用戶端應將其內嵌呈現。", "properties": { "content": { "$ref": "#/$defs/ContentRef" }, "external": { "type": "boolean", "description": "當值為 `true` 時，於外部處理器而非內嵌開啟。" } }, "required": [ "content" ] }, "InvokeChangesetOperationParams": { "type": "object", "description": "對變更集、單一檔案或行範圍叫用伺服器定義的 {@link ChangesetOperation}。\n\n伺服器會驗證 `operationId` 存在於變更集目前的 `operations` 清單中，\n且請求的 `target.kind` 包含在操作的 `scopes` 內。無效的組合會產生\nJSON-RPC 錯誤。\n\n叫用所產生的狀態變更會透過相關變更集 URI 上正常的 `changeset/*` 操作\n串流流回。除非伺服器透過未來的能力明確加入，否則用戶端 SHOULD NOT\n為叫用合成在地的樂觀變更。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "展開後的變更集 URI。" }, "operationId": { "type": "string", "description": "與變更集 `operations` 清單中的 {@link ChangesetOperation.id} 相符。" }, "target": { "$ref": "#/$defs/ChangesetOperationTarget", "description": "操作的目標。若且唯若所選範圍為 `'resource'` 或 `'range'` 時為必要。\n變更集範圍的操作請省略。" } }, "required": [ "channel", "operationId" ] }, "InvokeChangesetOperationResult": { "type": "object", "description": "{@link InvokeChangesetOperationParams | `invokeChangesetOperation`}\n指令的結果。\n\n成功是隱含的：伺服器在接受操作時回傳此結果。失敗則是透過以適當的錯誤\n代碼拒絕 JSON-RPC 請求來表示，而非由此結果上的任何欄位表示。此操作\nMAY 仍透過 {@link ChangesetStatusChangedAction | `changeset/statusChanged`}\n串流產生後續的失敗回饋。", "properties": { "message": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述結果的選用人類可讀訊息。" }, "followUp": { "$ref": "#/$defs/ChangesetOperationFollowUp", "description": "選用的後續：要開啟的 URI（例如 PR）、內容參照等等。" } } }, "CreateResourceWatchParams": { "type": "object", "description": "在接收端的檔案系統上建立資源監視器。\n\n接收端配置一個 `ahp-resource-watch:/` 通道 URI 並\n於 {@link CreateResourceWatchResult.channel} 回傳。呼叫端接著\n[`subscribe`](./subscriptions) 至該通道，以透過標準操作信封接收\n`resourceWatch/changed` 操作。\n\n監視生命週期與訂閱繫結：當每個訂閱者都已取消訂閱（或底層連線\n中斷）時，接收端 MUST 釋放監視器。沒有明確的 dispose 指令——\n`unsubscribe` 是呼叫端所需的唯一控制柄。\n\n如同 `resource*` 家族的其餘部分，`createResourceWatch` 是對稱的，\nMAY 在任一方向傳送。存取透過與 `resourceRead`／`resourceWrite`\n相同的權限流程管制。", "properties": { "channel": { "type": "string", "enum": [ "ahp-root://" ] }, "uri": { "$ref": "#/$defs/URI", "description": "要監視的 URI。" }, "recursive": { "type": "boolean", "description": "若為 `true`，接收端 MUST 回報 `uri` 後代的變更。\n若為 `false`（預設），僅回報 `uri` 本身的變更——且當 `uri`\n為目錄時，回報其直接子項。" }, "excludes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "description": "相對於 `uri` 的 glob 模式或路徑，用於從回報中排除。\n為向前相容而包裝於 `{ items }`。" }, "includes": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string" } } }, "required": [ "items" ], "description": "相對於 `uri` 的 glob 模式或路徑，用於限制回報範圍。\n省略以回報 `uri` 下受 `excludes` 限制的每個變更。\n為向前相容而包裝於 `{ items }`。" } }, "required": [ "channel", "uri" ] }, "CreateResourceWatchResult": { "type": "object", "description": "`createResourceWatch` 指令的結果。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "接收端指派的監視通道 URI（`ahp-resource-watch:/`）。\n呼叫端訂閱此 URI 以開始接收變更事件，並取消訂閱以釋放\n監視器。" } }, "required": [ "channel" ] }, "URI": { "type": "string", "description": "URI 字串（例如 `ahp-root://`、`ahp-session:/` 或 `ahp-chat:/`）。" }, "JsonPrimitive": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "基本 JSON 值：字串、數字、布林值或 `null`。" }, "Customization": { "oneOf": [ { "$ref": "#/$defs/PluginCustomization" }, { "$ref": "#/$defs/DirectoryCustomization" }, { "$ref": "#/$defs/McpServerCustomization" } ], "description": "工作階段中作用中的頂層自訂。可以是容器（{@link PluginCustomization}\n或 {@link DirectoryCustomization}），其葉自訂存在於其\n{@link ContainerCustomizationBase.children | `children`} 陣列中，或是\n主機直接公開的單獨 {@link McpServerCustomization}。" }, "PolicyState": { "enum": [ "enabled", "disabled", "unconfigured" ], "type": "string", "description": "模型的策略組態狀態。" }, "SessionStatus": { "enum": [ 1, 2, 8, 24, 32, 64 ], "type": "number", "description": "摘要層級工作階段狀態旗標的位元集。\n\n對非終結活動使用位元檢查而非相等性檢查。例如，\n`status & SessionStatus.InProgress` 同時比對普通的進行中回合與\n暫停等待輸入的回合。" }, "SessionLifecycle": { "enum": [ "creating", "ready", "creationFailed" ], "type": "string", "description": "工作階段初始化狀態。" }, "SessionInputRequest": { "oneOf": [ { "$ref": "#/$defs/SessionChatInputRequest" }, { "$ref": "#/$defs/SessionToolConfirmationRequest" }, { "$ref": "#/$defs/SessionToolClientExecutionRequest" }, { "$ref": "#/$defs/SessionToolAuthenticationRequest" } ], "description": "工作階段受阻的單一待處理輸入，跨 {@link SessionState.inputNeeded} 中\n所有聊天彙總。\n\n每個項目皆自足：它承載擁有的\n{@link SessionInputRequestBase.chat | `chat`} URI 加上建構回應所需的所有\n識別碼，讓用戶端能透過將普通的 `chat/*` 操作（`chat/inputCompleted`、\n`chat/toolCallConfirmed`、`chat/toolCallComplete`、…）分派至該聊天的\n通道來回答，**而無需先訂閱該聊天** — {@link SessionToolAuthenticationRequest}\n除外，它改為透過 `authenticate` 指令解決。主機在底層請求解決後以\n`session/inputNeededRemoved` 移除該項目。" }, "ToolCallConfirmationState": { "oneOf": [ { "$ref": "#/$defs/ToolCallPendingConfirmationState" }, { "$ref": "#/$defs/ToolCallPendingResultConfirmationState" } ], "description": "會因用戶端確認而封鎖的兩個工具呼叫狀態：執行前的參數確認\n（{@link ToolCallPendingConfirmationState}）與執行後的結果確認\n（{@link ToolCallPendingResultConfirmationState}）。\n\n{@link ToolCallAuthRequiredState} 刻意 **不** 屬於此聯集：它不因\n`chat/toolCallConfirmed` 式的用戶端決定而封鎖，而是因用戶端完成\nOAuth 流程並呼叫 `authenticate` 而封鎖。其工作階段層級呈現請參見\n{@link SessionToolAuthenticationRequest}。\n\n在工作階段層級由 {@link SessionToolConfirmationRequest} 呈現。" }, "ToolCallState": { "oneOf": [ { "$ref": "#/$defs/ToolCallStreamingState" }, { "$ref": "#/$defs/ToolCallPendingConfirmationState" }, { "$ref": "#/$defs/ToolCallRunningState" }, { "$ref": "#/$defs/ToolCallAuthRequiredState" }, { "$ref": "#/$defs/ToolCallPendingResultConfirmationState" }, { "$ref": "#/$defs/ToolCallCompletedState" }, { "$ref": "#/$defs/ToolCallCancelledState" } ], "description": "所有工具呼叫生命週期狀態的判別聯集。\n\n完整狀態機圖請參見\n[狀態模型指南](/guide/state-model.html#tool-call-lifecycle)。" }, "CustomizationLoadState": { "oneOf": [ { "$ref": "#/$defs/CustomizationLoadingState" }, { "$ref": "#/$defs/CustomizationLoadedState" }, { "$ref": "#/$defs/CustomizationDegradedState" }, { "$ref": "#/$defs/CustomizationErrorState" } ], "description": "容器自訂（{@link PluginCustomization} 或\n{@link DirectoryCustomization}）的判別聯集載入狀態。" }, "ChildCustomization": { "oneOf": [ { "$ref": "#/$defs/AgentCustomization" }, { "$ref": "#/$defs/SkillCustomization" }, { "$ref": "#/$defs/PromptCustomization" }, { "$ref": "#/$defs/RuleCustomization" }, { "$ref": "#/$defs/HookCustomization" }, { "$ref": "#/$defs/McpServerCustomization" } ], "description": "存在於 {@link PluginCustomization} 或\n{@link DirectoryCustomization} 內的子自訂。" }, "ChildCustomizationType": { "oneOf": [ { "const": "agent" }, { "const": "skill" }, { "const": "prompt" }, { "const": "rule" }, { "const": "hook" }, { "const": "mcpServer" } ], "description": "作為 {@link PluginCustomization} 或 {@link DirectoryCustomization} 子項\n出現的自訂類型。" }, "McpServerState": { "oneOf": [ { "$ref": "#/$defs/McpServerStartingState" }, { "$ref": "#/$defs/McpServerReadyState" }, { "$ref": "#/$defs/McpServerAuthRequiredState" }, { "$ref": "#/$defs/McpServerErrorState" }, { "$ref": "#/$defs/McpServerStoppedState" } ], "description": "所有 MCP 伺服器生命週期狀態的判別聯集。\n以 `kind`（一個 {@link McpServerStatus} 值）作為判別。" }, "McpAuthRequiredReason": { "enum": [ "required", "expired", "insufficientScope" ], "type": "string", "description": "MCP 伺服器目前為何處於 {@link McpServerStatus.AuthRequired} 狀態。\n鏡射 [MCP authorization 規範](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization.md)\n定義的三種失敗模式。" }, "ChatOrigin": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "user" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "const": "fork" }, "chat": { "$ref": "#/$defs/URI" }, "turnId": { "type": "string" } }, "required": [ "kind", "chat", "turnId" ] }, { "type": "object", "properties": { "kind": { "const": "sideChat" }, "chat": { "$ref": "#/$defs/URI" }, "turnId": { "type": "string" }, "selection": { "$ref": "#/$defs/SideChatSelection" } }, "required": [ "kind", "chat", "turnId" ] }, { "type": "object", "properties": { "kind": { "const": "tool" }, "chat": { "$ref": "#/$defs/URI" }, "toolCallId": { "type": "string" } }, "required": [ "kind", "chat", "toolCallId" ] } ], "description": "聊天如何產生。用戶端 MAY 使用它來呈現情境 UI（父項指標、分岔標記、\n「由工具產生」徽章）。\n\n分岔與側邊聊天起源兩者都帶有穩定的頂層 `turnId`，伴隨其判別\n`kind` 值，而非快照建立時該回合為作用中或歷史的狀態。消費者視需要將\n識別碼解析為來源聊天目前的 `activeTurn` 或保留的 `turns`。\n\n當主機接受從來源聊天目前作用中回合建立側邊聊天時，它會快照保留的\n歷史，加上該回合目前的使用者訊息與任何已可用的部分代理程式回應。\n之後來源回合的差異不會回溯變更所建立側邊聊天的起始情境，且一旦\n來源回合完成，它仍由相同的 `turnId` 參照。側邊聊天起源 MAY 也保留\n在接受時擷取的不可變 {@link SideChatSelection | 選取文字快照}；其中\n的任何 `responsePartId` 僅為出處，不是範圍。\n\n`tool` 變體從工作者側記錄工具產生的工作者：其 `chat`/`toolCallId`\n識別父聊天中產生的工具呼叫。這是產生關係的標準記錄。相同的邊從父側\n由 {@link ToolResultSubagentContent} 呈現，其 `resource` 為此聊天的\nURI；主機 MUST 保持兩者一致。" }, "ChatInteractivity": { "enum": [ "full", "read-only", "hidden" ], "type": "string", "description": "使用者可如何與聊天互動。\n\n- `Full` — 使用者可傳送訊息並觀看（缺省時為預設）\n- `ReadOnly` — 使用者可觀看但無法傳送訊息（例如代理程式團隊工作者）\n- `Hidden` — 完全不顯示在 UI 中的內部工作者\n\n支援代理程式團隊模式，其中主導聊天為完全互動，而工作者聊天為唯讀\n（可見以供可觀測性）或隱藏（內部實作細節）。框架根據聊天的角色\n設定此值；UI 使用它來顯示適當的控制項。" }, "ChatInputQuestion": { "oneOf": [ { "$ref": "#/$defs/ChatInputTextQuestion" }, { "$ref": "#/$defs/ChatInputNumberQuestion" }, { "$ref": "#/$defs/ChatInputBooleanQuestion" }, { "$ref": "#/$defs/ChatInputSingleSelectQuestion" }, { "$ref": "#/$defs/ChatInputMultiSelectQuestion" } ], "description": "聊天輸入請求中的單一問題。" }, "ChatInputAnswer": { "oneOf": [ { "$ref": "#/$defs/ChatInputAnswered" }, { "$ref": "#/$defs/ChatInputSkipped" } ], "description": "單一問題的草稿、已提交或已跳過答案。" }, "ChatInputAnswerValue": { "oneOf": [ { "$ref": "#/$defs/ChatInputTextAnswerValue" }, { "$ref": "#/$defs/ChatInputNumberAnswerValue" }, { "$ref": "#/$defs/ChatInputBooleanAnswerValue" }, { "$ref": "#/$defs/ChatInputSelectedAnswerValue" }, { "$ref": "#/$defs/ChatInputSelectedManyAnswerValue" } ] }, "ResponsePart": { "oneOf": [ { "$ref": "#/$defs/MarkdownResponsePart" }, { "$ref": "#/$defs/ResourceReponsePart" }, { "$ref": "#/$defs/ToolCallResponsePart" }, { "$ref": "#/$defs/ReasoningResponsePart" }, { "$ref": "#/$defs/SystemNotificationResponsePart" }, { "$ref": "#/$defs/InputRequestResponsePart" } ] }, "TurnState": { "enum": [ "complete", "cancelled", "error" ], "type": "string", "description": "回合如何結束。" }, "MessageKind": { "enum": [ "user", "agent", "tool", "systemNotification" ], "type": "string", "description": "{@link MessageOrigin} 的判別欄位 — 識別訊息的產生者。" }, "MessageAttachment": { "oneOf": [ { "$ref": "#/$defs/SimpleMessageAttachment" }, { "$ref": "#/$defs/MessageEmbeddedResourceAttachment" }, { "$ref": "#/$defs/MessageResourceAttachment" }, { "$ref": "#/$defs/MessageAnnotationsAttachment" }, { "$ref": "#/$defs/MessageChatAttachment" } ], "description": "與 {@link Message} 關聯的附件。" }, "ChatInputResponseKind": { "enum": [ "accept", "decline", "cancel" ], "type": "string", "description": "用戶端如何完成輸入請求。" }, "StringOrMarkdown": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "markdown": { "type": "string" } }, "required": [ "markdown" ] } ], "description": "可選擇以 Markdown 呈現的字串。\n\n- 純 `string` 會原樣呈現（不進行 Markdown 處理）。\n- 帶有 `{ markdown: string }` 的物件會以 Markdown 格式呈現。" }, "ToolCallRiskAssessmentKind": { "enum": [ "judge" ], "type": "string", "description": "將模型評審器識別為確認需求的來源。" }, "ConfirmationOptionKind": { "enum": [ "approve", "deny" ], "type": "string", "description": "確認選項是否代表核准或拒絕動作。" }, "ToolCallContributor": { "oneOf": [ { "$ref": "#/$defs/ToolCallClientContributor" }, { "$ref": "#/$defs/ToolCallMcpContributor" } ] }, "ToolResultContent": { "oneOf": [ { "$ref": "#/$defs/ToolResultTextContent" }, { "$ref": "#/$defs/ToolResultEmbeddedResourceContent" }, { "$ref": "#/$defs/ToolResultResourceContent" }, { "$ref": "#/$defs/ToolResultFileEditContent" }, { "$ref": "#/$defs/ToolResultTerminalContent" }, { "$ref": "#/$defs/ToolResultSubagentContent" } ], "description": "工具結果中的內容區塊。\n\n鏡像 MCP `CallToolResult.content` 中的內容區塊，加上用於延遲載入大型\n結果的 `ToolResultResourceContent`、用於檔案編輯差異的\n`ToolResultFileEditContent`、用於即時終端機輸出與指令完成中介資料的\n`ToolResultTerminalContent`，以及用於工具產生工作者聊天的\n`ToolResultSubagentContent`（AHP 擴充）。" }, "ToolCallRiskAssessment": { "oneOf": [ { "$ref": "#/$defs/ToolCallRiskAssessmentLoadingState" }, { "$ref": "#/$defs/ToolCallRiskAssessmentCompleteState" } ] }, "ToolCallConfirmationReason": { "enum": [ "not-needed", "user-action", "setting" ], "type": "string", "description": "工具呼叫如何被確認執行。\n\n- `NotNeeded` — 無需確認（自動核准）\n- `UserAction` — 使用者明確核准\n- `Setting` — 由持續性使用者設定核准" }, "ToolCallCancellationReason": { "enum": [ "denied", "skipped", "result-denied" ], "type": "string", "description": "工具呼叫為何被取消。" }, "TerminalClaim": { "oneOf": [ { "$ref": "#/$defs/TerminalClientClaim" }, { "$ref": "#/$defs/TerminalSessionClaim" } ], "description": "描述目前誰持有終端機。終端機可由已連線的用戶端或工作階段聲明（例如在工具呼叫期間）。" }, "TerminalContentPart": { "oneOf": [ { "$ref": "#/$defs/TerminalUnclassifiedPart" }, { "$ref": "#/$defs/TerminalCommandPart" } ], "description": "終端機輸出中的內容片段。" }, "ChangesetStatus": { "enum": [ "computing", "ready", "error" ], "type": "string", "description": "{@link ChangesetState} 的運算生命週期。" }, "ChangesetOperationScope": { "enum": [ "changeset", "resource", "range" ], "type": "string", "description": "{@link ChangesetOperation} 可被叫用的位置。" }, "ChangesetOperationStatus": { "enum": [ "idle", "running", "error", "disabled" ], "type": "string", "description": "{@link ChangesetOperation} 的執行生命週期。\n\n操作是透過 `invokeChangesetOperation` 命令式地叫用，但其進度與結果\n會反映回變更集狀態，讓每個訂閱者都觀察到一致的檢視（例如\n\"Create Pull Request\" 按鈕上的旋轉圖示，或失敗 \"revert\" 後的內嵌錯誤）。" }, "ResourceChangeType": { "enum": [ "added", "updated", "deleted" ], "type": "string", "description": "{@link ResourceChange.type} 的判別欄位。" }, "ActionEnvelope": { "type": "object", "description": "每個操作都包裝在 `ActionEnvelope` 中。\n\n此信封識別該操作所屬的通道（例如根操作使用 `ahp-root://`、工作階段操作\n使用工作階段 URI、終端機操作使用終端機 URI）。個別操作的有效負載只帶有\n該操作本身固有的欄位；通道來自信封，這使得任何可訂閱的資源都能統一地\n路由其操作。", "properties": { "channel": { "$ref": "#/$defs/URI", "description": "此操作所屬的通道 URI。" }, "action": { "$ref": "#/$defs/StateAction" }, "serverSeq": { "type": "number" }, "origin": { "$ref": "#/$defs/ActionOrigin" }, "rejectionReason": { "type": "string" } }, "required": [ "channel", "action", "serverSeq", "origin" ] }, "StateAction": { "oneOf": [ { "$ref": "#/$defs/RootAgentsChangedAction" }, { "$ref": "#/$defs/RootActiveSessionsChangedAction" }, { "$ref": "#/$defs/RootTerminalsChangedAction" }, { "$ref": "#/$defs/RootConfigChangedAction" }, { "$ref": "#/$defs/SessionReadyAction" }, { "$ref": "#/$defs/SessionCreationFailedAction" }, { "$ref": "#/$defs/SessionChatAddedAction" }, { "$ref": "#/$defs/SessionChatRemovedAction" }, { "$ref": "#/$defs/SessionChatUpdatedAction" }, { "$ref": "#/$defs/SessionDefaultChatChangedAction" }, { "$ref": "#/$defs/SessionTitleChangedAction" }, { "$ref": "#/$defs/SessionServerToolsChangedAction" }, { "$ref": "#/$defs/SessionActiveClientSetAction" }, { "$ref": "#/$defs/SessionActiveClientRemovedAction" }, { "$ref": "#/$defs/SessionWorkingDirectorySetAction" }, { "$ref": "#/$defs/SessionWorkingDirectoryRemovedAction" }, { "$ref": "#/$defs/SessionInputNeededSetAction" }, { "$ref": "#/$defs/SessionInputNeededRemovedAction" }, { "$ref": "#/$defs/SessionCustomizationsChangedAction" }, { "$ref": "#/$defs/SessionCustomizationToggledAction" }, { "$ref": "#/$defs/SessionCustomizationUpdatedAction" }, { "$ref": "#/$defs/SessionCustomizationRemovedAction" }, { "$ref": "#/$defs/SessionMcpServerStateChangedAction" }, { "$ref": "#/$defs/SessionMcpServerStartRequestedAction" }, { "$ref": "#/$defs/SessionMcpServerStopRequestedAction" }, { "$ref": "#/$defs/SessionIsReadChangedAction" }, { "$ref": "#/$defs/SessionIsArchivedChangedAction" }, { "$ref": "#/$defs/SessionActivityChangedAction" }, { "$ref": "#/$defs/SessionChangesetsChangedAction" }, { "$ref": "#/$defs/SessionConfigChangedAction" }, { "$ref": "#/$defs/SessionMetaChangedAction" }, { "$ref": "#/$defs/ChatTurnStartedAction" }, { "$ref": "#/$defs/ChatDeltaAction" }, { "$ref": "#/$defs/ChatResponsePartAction" }, { "$ref": "#/$defs/ChatToolCallStartAction" }, { "$ref": "#/$defs/ChatToolCallDeltaAction" }, { "$ref": "#/$defs/ChatToolCallReadyAction" }, { "$ref": "#/$defs/ChatToolCallConfirmedAction" }, { "$ref": "#/$defs/ChatToolCallCompleteAction" }, { "$ref": "#/$defs/ChatToolCallResultConfirmedAction" }, { "$ref": "#/$defs/ChatToolCallContentChangedAction" }, { "$ref": "#/$defs/ChatToolCallAuthRequiredAction" }, { "$ref": "#/$defs/ChatToolCallAuthResolvedAction" }, { "$ref": "#/$defs/ChatTurnCompleteAction" }, { "$ref": "#/$defs/ChatTurnCancelledAction" }, { "$ref": "#/$defs/ChatErrorAction" }, { "$ref": "#/$defs/ChatActivityChangedAction" }, { "$ref": "#/$defs/ChatWorkingDirectorySetAction" }, { "$ref": "#/$defs/ChatWorkingDirectoryRemovedAction" }, { "$ref": "#/$defs/ChatUsageAction" }, { "$ref": "#/$defs/ChatReasoningAction" }, { "$ref": "#/$defs/ChatPendingMessageSetAction" }, { "$ref": "#/$defs/ChatPendingMessageRemovedAction" }, { "$ref": "#/$defs/ChatQueuedMessagesReorderedAction" }, { "$ref": "#/$defs/ChatDraftChangedAction" }, { "$ref": "#/$defs/ChatInputRequestedAction" }, { "$ref": "#/$defs/ChatInputAnswerChangedAction" }, { "$ref": "#/$defs/ChatInputCompletedAction" }, { "$ref": "#/$defs/ChatTruncatedAction" }, { "$ref": "#/$defs/ChatTurnsLoadedAction" }, { "$ref": "#/$defs/ChangesetStatusChangedAction" }, { "$ref": "#/$defs/ChangesetFileSetAction" }, { "$ref": "#/$defs/ChangesetFileRemovedAction" }, { "$ref": "#/$defs/ChangesetFilesReviewChangedAction" }, { "$ref": "#/$defs/ChangesetContentChangedAction" }, { "$ref": "#/$defs/ChangesetOperationsChangedAction" }, { "$ref": "#/$defs/ChangesetOperationStatusChangedAction" }, { "$ref": "#/$defs/ChangesetClearedAction" }, { "$ref": "#/$defs/AnnotationsSetAction" }, { "$ref": "#/$defs/AnnotationsUpdatedAction" }, { "$ref": "#/$defs/AnnotationsRemovedAction" }, { "$ref": "#/$defs/AnnotationsEntrySetAction" }, { "$ref": "#/$defs/AnnotationsEntryRemovedAction" }, { "$ref": "#/$defs/TerminalDataAction" }, { "$ref": "#/$defs/TerminalInputAction" }, { "$ref": "#/$defs/TerminalResizedAction" }, { "$ref": "#/$defs/TerminalClaimedAction" }, { "$ref": "#/$defs/TerminalTitleChangedAction" }, { "$ref": "#/$defs/TerminalCwdChangedAction" }, { "$ref": "#/$defs/TerminalExitedAction" }, { "$ref": "#/$defs/TerminalClearedAction" }, { "$ref": "#/$defs/TerminalCommandDetectionAvailableAction" }, { "$ref": "#/$defs/TerminalCommandExecutedAction" }, { "$ref": "#/$defs/TerminalCommandFinishedAction" }, { "$ref": "#/$defs/ResourceWatchChangedAction" } ], "description": "所有狀態操作的判別聯集。" }, "ContentEncoding": { "enum": [ "base64", "utf-8" ], "type": "string", "description": "已擷取內容資料的編碼。" }, "ResourceWriteMode": { "enum": [ "truncate", "append", "insert" ], "type": "string", "description": "{@link ResourceWriteParams.data} 在目標檔案中的放置方式。\n\n每個模式對 {@link ResourceWriteParams.position} 的解讀不同：\n\n- `truncate`（預設）：以檔案的**開頭**為基準。檔案會在 `position`（預設為 0）\n 處截斷，並從該偏移量寫入 `data`，因此產生的檔案為\n `existing[0..position] + data`。省略 `position` 時即為完整覆寫。\n- `append`：以檔案的**結尾**為基準。`position` 從 EOF 往回計算位元組，因此\n `position: 0`（預設）會在 EOF 處寫入 — POSIX append — 而 `position: 5` 則在\n 目前 EOF 前 5 個位元組處插入 `data`，並將那結尾的 5 個位元組移到插入區域之後。\n 伺服器 MUST 評估有效的 EOF，並相對於其他附加者以原子方式寫入，使並行的\n `append` 寫入不會互相覆蓋。\n- `insert`：以檔案的**開頭**為基準。`position`（預設為 0）是 `data` 拼接進去的\n 位元組偏移量；位於或超過 `position` 的位元組會向右移動 `data.length`。\n `insert` 永遠會使檔案增長 — 請使用 `truncate` 來就地覆寫位元組。" }, "ResourceType": { "enum": [ "file", "directory", "symlink" ], "type": "string", "description": "{@link ResourceResolveResult.type} 的判別欄位。" }, "CompletionItemKind": { "enum": [ "userMessage" ], "type": "string", "description": "所請求的補全項目種類。" }, "ChatSource": { "oneOf": [ { "$ref": "#/$defs/ForkChatSource" }, { "$ref": "#/$defs/SideChatSource" } ], "description": "識別新聊天的來源聊天。" }, "ChangesetOperationTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "resource" }, "resource": { "$ref": "#/$defs/URI" }, "side": { "type": "string", "enum": [ "before", "after" ] } }, "required": [ "kind", "resource" ] }, { "type": "object", "properties": { "kind": { "const": "range" }, "resource": { "$ref": "#/$defs/URI" }, "side": { "type": "string", "enum": [ "before", "after" ] }, "range": { "$ref": "#/$defs/TextRange" } }, "required": [ "kind", "resource", "range" ] } ], "description": "識別 {@link ChangesetOperation} 應作用於的檔案或範圍。\n\n`kind` MUST 與操作所宣告的 {@link ChangesetOperation.scopes} 其中之一\n相符。" }, "ActionOrigin": { "type": "object", "description": "識別最初分派該操作的用戶端。", "properties": { "clientId": { "type": "string" }, "clientSeq": { "type": "number" } }, "required": [ "clientId", "clientSeq" ] }, "RootAgentsChangedAction": { "type": "object", "description": "當可用的代理程式後端或其模型變更時觸發。", "properties": { "type": { "const": "root/agentsChanged" }, "agents": { "type": "array", "items": { "$ref": "#/$defs/AgentInfo" }, "description": "更新後的代理程式清單" } }, "required": [ "type", "agents" ] }, "RootActiveSessionsChangedAction": { "type": "object", "description": "當作用中工作階段的數量變更時觸發。", "properties": { "type": { "const": "root/activeSessionsChanged" }, "activeSessions": { "type": "number", "description": "目前作用中工作階段的計數" } }, "required": [ "type", "activeSessions" ] }, "RootTerminalsChangedAction": { "type": "object", "description": "當已知終端機清單變更時觸發。\n\n全替換語意：`terminals` 陣列完全取代先前的 `terminals`。", "properties": { "type": { "const": "root/terminalsChanged" }, "terminals": { "type": "array", "items": { "$ref": "#/$defs/TerminalInfo" }, "description": "更新後的終端機清單（全替換）" } }, "required": [ "type", "terminals" ] }, "RootConfigChangedAction": { "type": "object", "description": "當代理主機組態值變更時觸發。\n\n依預設，化簡器會將新值合併進 `state.config.values`。將 `replace` 設為\n`true` 以取代所有值，而不是合併。", "properties": { "type": { "const": "root/configChanged" }, "config": { "type": "object", "additionalProperties": {}, "description": "更新後的組態值" }, "replace": { "type": "boolean", "description": "為 `true` 時，取代所有組態值而不是合併" } }, "required": [ "type", "config" ] }, "SessionReadyAction": { "type": "object", "description": "工作階段後端初始化成功。", "properties": { "type": { "const": "session/ready" } }, "required": [ "type" ] }, "SessionCreationFailedAction": { "type": "object", "description": "工作階段後端初始化失敗。", "properties": { "type": { "const": "session/creationFailed" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "錯誤詳細資訊" } }, "required": [ "type", "error" ] }, "SessionChatAddedAction": { "type": "object", "description": "聊天已加入此工作階段的目錄。Upsert 語意：若已存在具有相同\n`summary.resource` 的聊天，則取代現有項目。\n\n鏡射根通道的 `root/sessionAdded` 通知。", "properties": { "type": { "const": "session/chatAdded" }, "summary": { "$ref": "#/$defs/ChatSummary", "description": "新增（或 upsert）之聊天的完整摘要。" } }, "required": [ "type", "summary" ] }, "SessionChatRemovedAction": { "type": "object", "description": "聊天已從此工作階段的目錄中移除。無相符項目時為 no-op。\n\n鏡射根通道的 `root/sessionRemoved` 通知。", "properties": { "type": { "const": "session/chatRemoved" }, "chat": { "$ref": "#/$defs/URI", "description": "要移除的聊天 URI。" } }, "required": [ "type", "chat" ] }, "SessionChatUpdatedAction": { "type": "object", "description": "一個現有聊天的摘要欄位已變更。\n\n部分更新語意：僅寫入 `changes` 中出現的欄位；省略的欄位會被保留。\n識別欄位（`resource`）MUST NOT 隨附於 `changes`。無相符 `chat` 項目時\n為 no-op — 用戶端 SHOULD 接著等待 {@link SessionChatAddedAction | `session/chatAdded`}。\n\n鏡射根通道的 `root/sessionSummaryChanged` 通知。", "properties": { "type": { "const": "session/chatUpdated" }, "chat": { "$ref": "#/$defs/URI", "description": "摘要已變更的聊天 URI。" }, "changes": { "type": "object", "properties": { "resource": { "$ref": "#/$defs/URI", "description": "聊天 URI" }, "title": { "type": "string", "description": "聊天標題" }, "status": { "$ref": "#/$defs/SessionStatus", "description": "目前的聊天狀態（沿用 SessionStatus 形狀）" }, "activity": { "type": "string", "description": "此聊天目前正在做什麼的人類可讀描述" }, "modifiedAt": { "type": "string", "description": "上次修改時間戳記（ISO 8601，例如 `\"2025-03-10T18:42:03.123Z\"`）" }, "origin": { "$ref": "#/$defs/ChatOrigin", "description": "此聊天如何產生" }, "interactivity": { "$ref": "#/$defs/ChatInteractivity", "description": "使用者可如何與此聊天互動。參見 {@link ChatInteractivity}。\n\n支援代理程式團隊模式，其中工作者聊天為唯讀或隱藏。當此欄位缺省時，\n為向後相容預設為 {@link ChatInteractivity.Full}。" }, "workingDirectories": { "type": "array", "items": { "$ref": "#/$defs/URI" }, "description": "此聊天使用的工作階段工作目錄子集。\n完整語意請參見 {@link ChatState.workingDirectories}。" }, "primaryWorkingDirectory": { "$ref": "#/$defs/URI", "description": "聊天的主要工作目錄。\n完整語意請參見 {@link ChatState.primaryWorkingDirectory}。" } }, "description": "已變動的可變摘要欄位；省略的欄位保持不變。\n\n識別欄位（`resource`）永不變更，且傳送端 MUST 省略；接收端若收到\n則 SHOULD 忽略。" } }, "required": [ "type", "chat", "changes" ] }, "SessionDefaultChatChangedAction": { "type": "object", "description": "此工作階段的預設聊天輸入路由提示已變更。", "properties": { "type": { "const": "session/defaultChatChanged" }, "defaultChat": { "$ref": "#/$defs/URI", "description": "新的預設聊天 URI，或 `undefined` 以清除提示。" } }, "required": [ "type" ] }, "SessionTitleChangedAction": { "type": "object", "description": "工作階段標題已更新。當標題從對話自動產生時由伺服器引發，或由\n用戶端分派以重新命名工作階段。", "properties": { "type": { "const": "session/titleChanged" }, "title": { "type": "string", "description": "新標題" } }, "required": [ "type", "title" ] }, "SessionServerToolsChangedAction": { "type": "object", "description": "此工作階段的伺服器工具已變更。\n\n完全取代語意：`tools` 陣列完全取代先前的 `serverTools`。", "properties": { "type": { "const": "session/serverToolsChanged" }, "tools": { "type": "array", "items": { "$ref": "#/$defs/ToolDefinition" }, "description": "已更新的伺服器工具清單（完全取代）" } }, "required": [ "type", "tools" ] }, "SessionActiveClientSetAction": { "type": "object", "description": "此工作階段的作用中用戶端已新增或更新。\n\n以 {@link SessionActiveClient.clientId | `clientId`} 為鍵的 Upsert\n語意：用戶端以自己的 `SessionActiveClient` 分派此操作以加入工作\n階段的作用中用戶端或重新整理其項目，取代任何具有相同\n`clientId` 的現有項目。多個用戶端可同時作用中。這也是用戶端更新\n其已發布工具或自訂的方式 — 以完整、已更新的項目重新分派。使用\n{@link SessionActiveClientRemovedAction | `session/activeClientRemoved`}\n來離開。當作用中用戶端斷線時，伺服器 SHOULD 自動分派該移除操作。", "properties": { "type": { "const": "session/activeClientSet" }, "activeClient": { "$ref": "#/$defs/SessionActiveClient", "description": "要新增或更新的作用中用戶端，以 `clientId` 比對。" } }, "required": [ "type", "activeClient" ] }, "SessionActiveClientRemovedAction": { "type": "object", "description": "此工作階段的作用中用戶端已移除。\n\n從 {@link SessionState.activeClients} 移除以 `clientId` 識別的用戶端\n項目；無相符項目時為 no-op。\n\n當用戶端停止參與工作階段時，主機 SHOULD 自動分派此操作 — 例如\n當其取消訂閱工作階段通道、斷線且未在主機定義的寬限期內重新連線，\n或 `reconnect` 指令的 `subscriptions` 省略了用戶端仍在作用中的工作\n階段時。移除用戶端時，主機 SHOULD 一併取消該用戶端的進行中工具\n呼叫 — 即工具呼叫狀態承載具有相符 `clientId` 之用戶端\n`ToolCallContributor` 的那些呼叫 — 作法是分派 `chat/toolCallComplete`\n並設定 `result.success = false`。（沒有每個工具呼叫的伺服器取消；\n失敗的補全即為取消機制，呼叫以失敗結果結束於 `completed` 狀態。）", "properties": { "type": { "const": "session/activeClientRemoved" }, "clientId": { "type": "string", "description": "要移除的作用中用戶端之 `clientId`。" } }, "required": [ "type", "clientId" ] }, "SessionWorkingDirectorySetAction": { "type": "object", "description": "工作目錄已加入工作階段的\n{@link SessionState.workingDirectories} 集合。\n\n以目錄 URI 為鍵的成員資格語意：當集合尚不包含 `directory` 時\nreducer 會附加它（若集合不存在則建立），且已存在時為 no-op。\n僅在代理程式通告 {@link AgentCapabilities.multipleWorkingDirectories}\n時有效。", "properties": { "type": { "const": "session/workingDirectorySet" }, "directory": { "$ref": "#/$defs/URI", "description": "要授予工作階段代理程式工具存取權的工作目錄。" } }, "required": [ "type", "directory" ] }, "SessionWorkingDirectoryRemovedAction": { "type": "object", "description": "工作目錄已從工作階段的\n{@link SessionState.workingDirectories} 集合中移除。\n\n從集合中移除 `directory`；不存在時為 no-op。沒有原子的後端「移除\n一個」基本操作 — 主機將其代理程式重新設定為縮減後的集合 — 因此\n此操作可安全地建模為冪等。主機 MAY 拒絕套用移除（例如某個目錄\n仍被指定為某個聊天的\n{@link ChatState.primaryWorkingDirectory | 主要目錄}）；此時它會保持\n集合不變。", "properties": { "type": { "const": "session/workingDirectoryRemoved" }, "directory": { "$ref": "#/$defs/URI", "description": "要撤銷工作階段代理程式工具存取權的工作目錄。" } }, "required": [ "type", "directory" ] }, "SessionInputNeededSetAction": { "type": "object", "description": "工作階段層級的輸入請求已新增或更新。\n\n以 {@link SessionInputRequest.id | `request.id`} 為鍵的 Upsert 語意：\n主機以完整的 {@link SessionInputRequest} 分派此操作以將新項目附加至\n{@link SessionState.inputNeeded} 或取代具有相同 `id` 的現有項目。\n\n伺服器發起：主機將聊天層級的請求（引出、工具確認、用戶端工具\n執行）鏡射至工作階段彙總中，讓僅訂閱工作階段通道的用戶端能發現\n它們。用戶端透過將普通的 `chat/*` 操作分派至項目的 `chat` 通道來\n回應 — 見 {@link SessionInputRequest}。", "properties": { "type": { "const": "session/inputNeededSet" }, "request": { "$ref": "#/$defs/SessionInputRequest", "description": "要新增或更新的輸入請求，以 `id` 比對。" } }, "required": [ "type", "request" ] }, "SessionInputNeededRemovedAction": { "type": "object", "description": "工作階段層級的輸入請求已移除。\n\n從 {@link SessionState.inputNeeded} 移除以 `id` 識別的項目；無相符\n項目時為 no-op。\n\n伺服器發起：主機在底層請求解決後（使用者回答、工具呼叫確認、或\n用戶端回報結果）分派此操作。", "properties": { "type": { "const": "session/inputNeededRemoved" }, "id": { "type": "string", "description": "要移除之輸入請求的 `id`。" } }, "required": [ "type", "id" ] }, "SessionCustomizationsChangedAction": { "type": "object", "description": "工作階段的自訂已變更。\n\n完全取代語意：`customizations` 陣列完全取代先前的\n`customizations`。", "properties": { "type": { "const": "session/customizationsChanged" }, "customizations": { "type": "array", "items": { "$ref": "#/$defs/Customization" }, "description": "已更新的自訂清單（完全取代）。" } }, "required": [ "type", "customizations" ] }, "SessionCustomizationToggledAction": { "type": "object", "description": "用戶端將某個自訂啟用或停用。\n\n先以 `id` 比對每個頂層自訂 — 外掛或目錄容器，或單獨的頂層 MCP\n伺服器 — 再比對每個容器內的子項（技能、代理程式或其他項目），\n並設定相符項目的 `enabled` 旗標。停用容器仍會停用其所有子項 —\n子項的有效狀態為 `container.enabled && (child.enabled ?? true)` —\n因此切換子項僅在其容器啟用時才有意義。沒有自訂具有給定 `id` 時\n為 no-op。", "properties": { "type": { "const": "session/customizationToggled" }, "id": { "type": "string", "description": "要切換的容器或子項之 id。" }, "enabled": { "type": "boolean", "description": "要啟用或停用目標自訂。" } }, "required": [ "type", "id", "enabled" ] }, "SessionCustomizationUpdatedAction": { "type": "object", "description": "Upsert 頂層自訂（外掛或目錄）。\n\nreducer 以 `customization.id` 定位現有項目：\n\n- 若找到，項目會完全以 `customization` 取代，包含其 `children`\n 陣列。要保留現有子項，主機必須在有效負載中包含它們。\n- 若未找到，則附加該項目。", "properties": { "type": { "const": "session/customizationUpdated" }, "customization": { "$ref": "#/$defs/Customization", "description": "要 upsert 的自訂（以 `customization.id` 比對）。" } }, "required": [ "type", "customization" ] }, "SessionCustomizationRemovedAction": { "type": "object", "description": "以 id 移除自訂。\n\n在每個容器及其子項中搜尋該項目。若項目是容器，其子項會一併移除。\n沒有相符 id 時為 no-op。", "properties": { "type": { "const": "session/customizationRemoved" }, "id": { "type": "string", "description": "要移除的自訂之 id。" } }, "required": [ "type", "id" ] }, "SessionMcpServerStateChangedAction": { "type": "object", "description": "更新現有 {@link McpServerCustomization} 的執行時期欄位 — 針對高頻率的\n`starting` ↔ `ready` ↔ `authRequired` 轉換，是\n{@link SessionCustomizationUpdatedAction} 的窄替代方案。\n\n以 `id` 定位目標項目，搜尋頂層自訂清單與每個容器的 `children`\n陣列。取代項目的\n{@link McpServerCustomization.state | `state`} 與\n{@link McpServerCustomization.channel | `channel`}\n（完全取代語意：省略 `channel` 以清除現有通道 URI）。自訂的其他\n欄位會被保留。\n\n找不到相符的 `McpServerCustomization` 時為 no-op。要更新任何其他\n欄位（名稱、圖示、`mcpApp` 能力等），請改用\n{@link SessionCustomizationUpdatedAction}。\n\n當轉換至 {@link McpServerStatus.AuthRequired} 是因回合中途發出的\n請求所致時，主機 SHOULD 一併在工作階段上引發\n{@link SessionStatus.InputNeeded} — 見 {@link McpServerAuthRequiredState}\n的理由說明。", "properties": { "type": { "const": "session/mcpServerStateChanged" }, "id": { "type": "string", "description": "要更新的 {@link McpServerCustomization} 之 id。" }, "state": { "$ref": "#/$defs/McpServerState", "description": "新的生命週期狀態。" }, "channel": { "$ref": "#/$defs/URI", "description": "已更新的 `mcp://` 側通道 URI。完全取代：省略以清除現有通道\n（離開 {@link McpServerStatus.Ready | `Ready`} 時的典型做法）。" } }, "required": [ "type", "id", "state" ] }, "SessionMcpServerStartRequestedAction": { "type": "object", "description": "請求主機啟動或重新啟動現有的\n{@link McpServerCustomization}。\n\n以 `id` 定位目標項目，搜尋頂層自訂清單與每個容器的 `children`\n陣列。reducer 樂觀地將伺服器移至\n{@link McpServerStatus.Starting | `starting`} 並清除任何先前的\n{@link McpServerCustomization.channel | `channel`}；主機仍具權威性，\nSHOULD 在伺服器就緒、需要驗證、失敗或被拒絕後，接著分派\n{@link SessionMcpServerStateChangedAction | `session/mcpServerStateChanged`}。\n找不到相符的 `McpServerCustomization` 時為 no-op。", "properties": { "type": { "const": "session/mcpServerStartRequested" }, "id": { "type": "string", "description": "要啟動的 {@link McpServerCustomization} 之 id。" } }, "required": [ "type", "id" ] }, "SessionMcpServerStopRequestedAction": { "type": "object", "description": "請求主機停止現有的 {@link McpServerCustomization}。\n\n以 `id` 定位目標項目，搜尋頂層自訂清單與每個容器的 `children`\n陣列。reducer 樂觀地將伺服器移至\n{@link McpServerStatus.Stopped | `stopped`} 並清除任何先前的\n{@link McpServerCustomization.channel | `channel`}。以 `stopped`\n取代 {@link McpServerStatus.AuthRequired | `authRequired`} 生命週期\n狀態會解除伺服器等待驗證的阻塞。若主機僅為該 MCP 伺服器引發了\n工作階段層級的待處理輸入狀態，則在接受停止時 SHOULD 移除該待處理\n輸入項目。\n\n主機仍具權威性，且 MAY 拒絕該操作，或在最終生命週期狀態不同時接著\n分派 {@link SessionMcpServerStateChangedAction | `session/mcpServerStateChanged`}。\n找不到相符的 `McpServerCustomization` 時為 no-op。", "properties": { "type": { "const": "session/mcpServerStopRequested" }, "id": { "type": "string", "description": "要停止的 {@link McpServerCustomization} 之 id。" } }, "required": [ "type", "id" ] }, "SessionIsReadChangedAction": { "type": "object", "description": "工作階段的已讀狀態已變更。\n\n由用戶端分派以將工作階段標記為已讀（例如檢視後）或未讀（例如自\n用戶端上次檢視後有新活動）。", "properties": { "type": { "const": "session/isReadChanged" }, "isRead": { "type": "boolean", "description": "工作階段是否已讀" } }, "required": [ "type", "isRead" ] }, "SessionIsArchivedChangedAction": { "type": "object", "description": "工作階段的封存狀態已變更。\n\n由用戶端分派以封存工作階段（例如工作完成）或解除封存。", "properties": { "type": { "const": "session/isArchivedChanged" }, "isArchived": { "type": "boolean", "description": "工作階段是否已封存" } }, "required": [ "type", "isArchived" ] }, "SessionActivityChangedAction": { "type": "object", "description": "工作階段的活動描述已變更。\n\n由伺服器分派以指出工作階段目前正在做什麼（例如執行工具、\n思考）。設為 `undefined` 以清除活動。", "properties": { "type": { "const": "session/activityChanged" }, "activity": { "type": "string", "description": "目前活動的人類可讀描述，或 `undefined` 以清除" } }, "required": [ "type", "activity" ] }, "SessionChangesetsChangedAction": { "type": "object", "description": "代理主機為此工作階段所通告的 {@link Changeset | 變更集目錄}已變更。\n完全取代 {@link SessionState.changesets | `state.changesets`}\n（完全取代語意）— 設為 `undefined` 以清除目錄。\n\n生產者在新增或移除項目時分派此操作。展發透過此操作進行，讓\n觀察者能在其已追蹤的檔案層級更新所用的同一個\n{@link ChangesetAction | 每個變更集} 操作串流中看到目錄變動。", "properties": { "type": { "const": "session/changesetsChanged" }, "changesets": { "type": "array", "items": { "$ref": "#/$defs/Changeset" }, "description": "新目錄，或 `undefined` 以清除" } }, "required": [ "type", "changesets" ] }, "SessionConfigChangedAction": { "type": "object", "description": "用戶端在工作階段中途變更了可變的設定值。\n\n只有設定綱要中具有 `sessionMutable: true` 的屬性可被變更。伺服器驗證\n並廣播此操作；reducer 將新值合併至 `state.config.values`。", "properties": { "type": { "const": "session/configChanged" }, "config": { "type": "object", "additionalProperties": {}, "description": "已更新的設定值" }, "replace": { "type": "boolean", "description": "為 `true` 時，取代所有設定值而非合併" } }, "required": [ "type", "config" ] }, "SessionMetaChangedAction": { "type": "object", "description": "工作階段的 `_meta` 側通道已變更。完全取代 `state._meta`\n（完全取代語意）。生產者 SHOULD 在分派前將任何想保留的鍵合併至\n新值中。", "properties": { "type": { "const": "session/metaChanged" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "新的 `_meta` 有效負載，或 `undefined` 以清除" } }, "required": [ "type", "_meta" ] }, "ChatTurnStartedAction": { "type": "object", "description": "新訊息已傳送給代理程式，且新回合開始。\n\n用戶端僅被允許傳送 {@link MessageKind.User} 訊息。", "properties": { "type": { "const": "chat/turnStarted" }, "turnId": { "type": "string", "description": "回合識別碼" }, "startedAt": { "type": "string", "description": "此回合開始時的 ISO 8601 時間戳記。" }, "message": { "$ref": "#/$defs/Message", "description": "新訊息" }, "queuedMessageId": { "type": "string", "description": "若此回合是從佇列訊息自動啟動，該訊息的 ID" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "startedAt", "message" ] }, "ChatDeltaAction": { "type": "object", "description": "來自助理的串流文字區塊，附加到特定回應部分。\n\n伺服器 MUST 先發出 `chat/responsePart` 以建立目標部分（markdown 或推理），再使用此操作將文字附加到它。", "properties": { "type": { "const": "chat/delta" }, "turnId": { "type": "string", "description": "回合識別碼" }, "partId": { "type": "string", "description": "要附加到的回應部分識別碼" }, "content": { "type": "string", "description": "文字區塊" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "partId", "content" ] }, "ChatResponsePartAction": { "type": "object", "description": "附加到回應的結構化內容。", "properties": { "type": { "const": "chat/responsePart" }, "turnId": { "type": "string", "description": "回合識別碼" }, "part": { "$ref": "#/$defs/ResponsePart", "description": "回應部分（markdown 或內容參照）" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "part" ] }, "ChatToolCallStartAction": { "type": "object", "description": "工具呼叫開始 — 參數正從 LM 串流傳入。\n\n伺服器設定 {@link ToolCallContributor | `contributor`} 以識別工具的起源。對於用戶端提供的工具，具名用戶端負責在工具到達 `running` 狀態時執行它，並分派 `chat/toolCallComplete`。對於 MCP 伺服器提供的工具，伺服器會針對具名的 `McpServerCustomization` 執行呼叫。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallStart" }, "toolName": { "type": "string", "description": "內部工具名稱（用於除錯/日誌）" }, "displayName": { "type": "string", "description": "人類可讀的工具名稱" }, "intention": { "type": "string", "description": "工具呼叫意圖執行之動作的人類可讀描述" }, "contributor": { "$ref": "#/$defs/ToolCallContributor", "description": "所呼叫工具之貢獻者的參照。對於非由用戶端或 MCP 伺服器貢獻的伺服器端工具則不存在。" } }, "required": [ "turnId", "toolCallId", "type", "toolName", "displayName" ] }, "ChatToolCallDeltaAction": { "type": "object", "description": "工具呼叫的串流部分參數。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallDelta" }, "content": { "type": "string", "description": "要附加的部分參數內容" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "更新的進度訊息" } }, "required": [ "turnId", "toolCallId", "type", "content" ] }, "ChatToolCallReadyAction": { "type": "object", "description": "工具呼叫參數已完成，或執行中的工具需要重新確認。\n\n當針對 `streaming` 工具呼叫分派時，會轉換到 `pending-confirmation`，或若設定了 `confirmed` 則直接轉換到 `running`。\n\n當針對 `running` 工具呼叫分派時（例如執行中途需要權限），會轉換回 `pending-confirmation`。`invocationMessage` 與 `_meta` SHOULD 被更新以描述所需的特定確認。用戶端使用標準 `chat/toolCallConfirmed` 流程來核准或拒絕。\n\n對於用戶端提供的工具，伺服器通常會將 `confirmed` 設為 `'not-needed'`，讓工具直接轉換到 `running`，讓擁有用戶端能立即開始執行。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallReady" }, "invocationMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "描述工具將執行之動作或所需確認的訊息" }, "toolInput": { "type": "string", "description": "原始工具輸入" }, "confirmationTitle": { "$ref": "#/$defs/StringOrMarkdown", "description": "確認提示的簡短標題（例如 `\"Run in terminal\"`、`\"Write file\"`）" }, "riskAssessment": { "$ref": "#/$defs/ToolCallRiskAssessment", "description": "促成確認需求的風險評估。" }, "edits": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/FileEdit" } } }, "required": [ "items" ], "description": "此工具呼叫將執行的檔案編輯，用於確認前的預覽" }, "editable": { "type": "boolean", "description": "代理主機是否允許用戶端在確認前編輯工具的輸入參數" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "若設定，工具已自動確認並直接轉換到 `running`" }, "options": { "type": "array", "items": { "$ref": "#/$defs/ConfirmationOption" }, "description": "伺服器為此確認提供的選項。若存在，用戶端 SHOULD 改為渲染這些選項，而非單純的核准/拒絕 UI。每個選項屬於一個 {@link ConfirmationOptionGroup}，讓用戶端仍能將選擇分類。" } }, "required": [ "turnId", "toolCallId", "type", "invocationMessage" ] }, "ChatToolCallConfirmedAction": { "oneOf": [ { "$ref": "#/$defs/ChatToolCallApprovedAction" }, { "$ref": "#/$defs/ChatToolCallDeniedAction" } ], "description": "用戶端確認或拒絕待處理的工具呼叫。" }, "ChatToolCallCompleteAction": { "type": "object", "description": "工具執行完成。若 `requiresResultConfirmation` 為 `true`，轉換到 `completed` 或 `pending-result-confirmation`。\n\n對於用戶端提供的工具（其工具呼叫狀態帶有含 `clientId` 的用戶端\n`ToolCallContributor`），擁有用戶端會帶著執行結果分派此操作。若分派的用戶端與貢獻者的 `clientId` 不符，伺服器 SHOULD 拒絕此操作。\n\n等待用戶端工具呼叫的伺服器 MAY 在實作用戶端中斷連線或變得無回應後，於合理持續時間後逾時，並帶著 `result.success = false` 與適當錯誤分派此操作。\n\n用戶端 MAY 也針對目前處於 `auth-required`\n狀態的工具呼叫，以 **失敗** 的結果（`result.success: false`）分派此操作，以在不完成待處理 MCP\n驗證挑戰的情況下取消該呼叫。這永遠會將工具呼叫直接轉換到 `completed`，保留它在暫停以進行驗證前的欄位；\n`requiresResultConfirmation` 在此轉換會被忽略；取消永遠無法進入\n`pending-result-confirmation`，因為沒有可檢閱的實際結果。\n\n**成功** 的結果（`result.success: true`）對處於 `auth-required` 狀態的工具呼叫是無效的 — 執行在挑戰後從未恢復，因此沒有任何事物能產生它。reducer\nMUST 將其作為 no-op 拒絕/忽略，讓工具呼叫留在 `auth-required`。用戶端必須在成功完成前先解決驗證挑戰（`chat/toolCallAuthResolved`）。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallComplete" }, "result": { "$ref": "#/$defs/ToolCallResult", "description": "執行結果" }, "requiresResultConfirmation": { "type": "boolean", "description": "若為 true，結果在完成前需要用戶端核准" } }, "required": [ "turnId", "toolCallId", "type", "result" ] }, "ChatToolCallResultConfirmedAction": { "type": "object", "description": "用戶端核准或拒絕工具的結果。\n\n若 `approved` 為 `false`，工具會以原因 `result-denied` 轉換到 `cancelled`。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallResultConfirmed" }, "approved": { "type": "boolean", "description": "結果是否已核准" } }, "required": [ "turnId", "toolCallId", "type", "approved" ] }, "ChatToolCallContentChangedAction": { "type": "object", "description": "工具仍在執行時產生的部分內容。\n\n取代執行中工具呼叫狀態上的 `content` 陣列。用戶端可使用它在工具完成前顯示即時回饋（例如終端機參照）。\n\n對於用戶端提供的工具（其工具呼叫狀態帶有含 `clientId` 的用戶端\n`ToolCallContributor`），擁有用戶端會在執行時分派此操作以串流傳入中繼內容。若分派的用戶端與貢獻者的\n`clientId` 不符，伺服器 SHOULD 拒絕此操作。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallContentChanged" }, "content": { "type": "array", "items": { "$ref": "#/$defs/ToolResultContent" }, "description": "執行中工具呼叫的目前部分內容" } }, "required": [ "turnId", "toolCallId", "type", "content" ] }, "ChatToolCallAuthRequiredAction": { "type": "object", "description": "執行中的工具呼叫已暫停，等待 MCP 驗證。將工具呼叫從 `running` 轉換到 `auth-required`。\n\n伺服器在支援呼叫的 MCP 伺服器於執行中途以 401/403 挑戰回應時分派此操作（見\n{@link McpAuthRequirement.reason | `insufficientScope`}）。主機 SHOULD\n將此與 `session/inputNeededSet`（kind `toolAuthentication`）配對，讓區塊在工作階段摘要層級可見，鏡像\n{@link McpServerAuthRequiredState} 自身的 `InputNeeded` 指引。\n\n僅對由 MCP 伺服器貢獻的工具呼叫有效 — 若工具呼叫的 `contributor` 不是\n{@link ToolCallContributorKind.MCP | MCP-kind}，reducer 為 no-op。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallAuthRequired" }, "auth": { "$ref": "#/$defs/McpAuthRequirement", "description": "阻擋此呼叫的驗證挑戰。" } }, "required": [ "turnId", "toolCallId", "type", "auth" ] }, "ChatToolCallAuthResolvedAction": { "type": "object", "description": "阻擋工具呼叫的驗證挑戰已解決（用戶端透過 `authenticate` 推送權杖且主機已驗證它）。將工具呼叫從 `auth-required` 轉換回 `running`，保留它在暫停前的欄位。\n\n主機 SHOULD 在此分派後移除對應的 `session/inputNeededSet` 項目（kind `toolAuthentication`）。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallAuthResolved" } }, "required": [ "turnId", "toolCallId", "type" ] }, "ChatTurnCompleteAction": { "type": "object", "description": "回合完成 — 助理已閒置。", "properties": { "type": { "const": "chat/turnComplete" }, "turnId": { "type": "string", "description": "回合識別碼" }, "duration": { "type": "number", "description": "以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "duration" ] }, "ChatTurnCancelledAction": { "type": "object", "description": "回合已中止；伺服器停止處理。", "properties": { "type": { "const": "chat/turnCancelled" }, "turnId": { "type": "string", "description": "回合識別碼" }, "duration": { "type": "number", "description": "以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "duration" ] }, "ChatErrorAction": { "type": "object", "description": "回合處理期間發生錯誤。", "properties": { "type": { "const": "chat/error" }, "turnId": { "type": "string", "description": "回合識別碼" }, "duration": { "type": "number", "description": "以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "錯誤詳細資料" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "duration", "error" ] }, "ChatActivityChangedAction": { "type": "object", "description": "此聊天的活動描述已變更。\n\n由伺服器分派以指出聊天目前正在做什麼（例如執行工具、思考）。透過省略它或將它設為 `undefined` 來清除活動。產生者 SHOULD 也以 `session/chatUpdated` 更新父工作階段的聊天目錄，讓 `ChatSummary.activity` 保持同步。", "properties": { "type": { "const": "chat/activityChanged" }, "activity": { "type": "string", "description": "目前活動的人類可讀描述；省略或設為 `undefined` 以清除" } }, "required": [ "type" ] }, "ChatWorkingDirectorySetAction": { "type": "object", "description": "工作目錄已新增到此聊天的 {@link ChatState.workingDirectories} 子集。\n\n以目錄 URI 為鍵的成員資格語意：當聊天的子集尚未包含 `directory` 時，reducer 會附加它（若不存在則建立子集），且當它已存在時為 no-op。`directory` MUST 是所屬工作階段 {@link SessionState.workingDirectories} 之一；主機 MUST 拒絕非如此的目錄。僅在代理程式公告 {@link AgentCapabilities.multipleWorkingDirectories} 時有效。", "properties": { "type": { "const": "chat/workingDirectorySet" }, "directory": { "$ref": "#/$defs/URI", "description": "要新增到此聊天子集的工作目錄。" } }, "required": [ "type", "directory" ] }, "ChatWorkingDirectoryRemovedAction": { "type": "object", "description": "工作目錄已從此聊天的 {@link ChatState.workingDirectories} 子集中移除。\n\n從聊天的子集中移除 `directory`；當它不存在時為 no-op。具冪等性，鏡像 `session/workingDirectoryRemoved`。僅影響聊天的子集 — 目錄仍保留在工作階段的集合中。", "properties": { "type": { "const": "chat/workingDirectoryRemoved" }, "directory": { "$ref": "#/$defs/URI", "description": "要從此聊天子集中移除的工作目錄。" } }, "required": [ "type", "directory" ] }, "ChatUsageAction": { "type": "object", "description": "回合的權杖使用量報告。", "properties": { "type": { "const": "chat/usage" }, "turnId": { "type": "string", "description": "回合識別碼" }, "usage": { "$ref": "#/$defs/UsageInfo", "description": "權杖使用量資料" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "usage" ] }, "ChatReasoningAction": { "type": "object", "description": "來自模型的推理/思考文字，附加到特定推理回應部分。\n\n伺服器 MUST 先發出 `chat/responsePart` 以建立目標推理部分，再使用此操作將文字附加到它。", "properties": { "type": { "const": "chat/reasoning" }, "turnId": { "type": "string", "description": "回合識別碼" }, "partId": { "type": "string", "description": "要附加到的推理回應部分識別碼" }, "content": { "type": "string", "description": "推理文字區塊" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此操作的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP `_meta` 慣例。" } }, "required": [ "type", "turnId", "partId", "content" ] }, "ChatPendingMessageSetAction": { "type": "object", "description": "待處理訊息已設定（upsert 語意：建立或取代）。\n\n對於引導訊息，這永遠會取代單一引導訊息。對於佇列訊息，若具有給定 `id` 的訊息已存在，它會就地更新；否則會附加到佇列。若設定佇列訊息時聊天處於閒置狀態，伺服器 SHOULD 立即取用它並開始新回合。\n\n用戶端僅被允許傳送 {@link MessageKind.User} 訊息。", "properties": { "type": { "const": "chat/pendingMessageSet" }, "kind": { "$ref": "#/$defs/PendingMessageKind", "description": "這是引導訊息還是佇列訊息" }, "id": { "type": "string", "description": "此待處理訊息的唯一識別碼" }, "message": { "$ref": "#/$defs/Message", "description": "訊息內容" } }, "required": [ "type", "kind", "id", "message" ] }, "ChatPendingMessageRemovedAction": { "type": "object", "description": "待處理訊息已移除（引導或佇列）。\n\n由用戶端分派以取消待處理訊息，或由伺服器在它取用訊息時分派（例如從佇列訊息開始回合，或將引導訊息注入目前回合）。", "properties": { "type": { "const": "chat/pendingMessageRemoved" }, "kind": { "$ref": "#/$defs/PendingMessageKind", "description": "這是引導訊息還是佇列訊息" }, "id": { "type": "string", "description": "要移除的待處理訊息識別碼" } }, "required": [ "type", "kind", "id" ] }, "ChatQueuedMessagesReorderedAction": { "type": "object", "description": "重新排序佇列訊息。\n\n`order` 陣列包含佇列訊息的 ID，依其新的所需順序排列。不存在於目前佇列中的 ID 會被忽略。ID 不在 `order` 中的佇列訊息會以原始相對順序附加到結尾（讓具有過時佇列檢視的用戶端永遠不會靜默捨棄訊息）。", "properties": { "type": { "const": "chat/queuedMessagesReordered" }, "order": { "type": "array", "items": { "type": "string" }, "description": "依所需順序排列的佇列訊息 ID" } }, "required": [ "type", "order" ] }, "ChatDraftChangedAction": { "type": "object", "description": "聊天的草稿輸入已變更。\n\n用戶端 MAY 定期將其本地輸入狀態 — 使用者正在撰寫的訊息，包括其 {@link Message.model | 模型} /\n{@link Message.agent | 代理程式} 選擇與附件 — 同步到聊天的\n{@link ChatState.draft | `draft`}，讓它在重新載入後仍留存，且對檢視相同聊天的其他用戶端可見。積極同步 **not** 必要；\n用戶端 SHOULD 去抖動，且 MAY 僅在方便的時刻同步。將 `draft`\n設為 `undefined` 以清除它（例如訊息傳送後）。\n\n用戶端僅被允許草擬 {@link MessageKind.User} 訊息。", "properties": { "type": { "const": "chat/draftChanged" }, "draft": { "$ref": "#/$defs/Message", "description": "新的草稿訊息，或 `undefined` 以清除它" } }, "required": [ "type" ] }, "ChatInputRequestedAction": { "type": "object", "description": "工作階段向使用者請求輸入。\n\n在活動回合中建立未解決的 {@link InputRequestResponsePart}，或以具有相同請求 `id` 的未解決部分取代它。除非提供 `request.answers`，否則答案草稿會被保留。", "properties": { "type": { "const": "chat/inputRequested" }, "request": { "$ref": "#/$defs/ChatInputRequest", "description": "要建立或取代的輸入請求" } }, "required": [ "type", "request" ] }, "ChatInputAnswerChangedAction": { "type": "object", "description": "用戶端已更新、提交、跳過或移除單一進行中的答案。\n\n以 `answer: undefined` 分派會移除該問題的答案草稿。", "properties": { "type": { "const": "chat/inputAnswerChanged" }, "requestId": { "type": "string", "description": "輸入請求識別碼" }, "questionId": { "type": "string", "description": "輸入請求中的問題識別碼" }, "answer": { "$ref": "#/$defs/ChatInputAnswer", "description": "已更新的答案，或 `undefined` 以清除答案草稿" } }, "required": [ "type", "requestId", "questionId" ] }, "ChatInputCompletedAction": { "type": "object", "description": "用戶端已提交對輸入請求的接受、拒絕或取消回應。\n\n若接受，伺服器會使用 `answers`（若提供）加上請求的同步答案狀態來恢復受阻的操作。reducer 會在現有的 {@link InputRequestResponsePart} 上記錄回應與最終答案。", "properties": { "type": { "const": "chat/inputCompleted" }, "requestId": { "type": "string", "description": "輸入請求識別碼" }, "response": { "$ref": "#/$defs/ChatInputResponseKind", "description": "完成結果" }, "answers": { "type": "object", "additionalProperties": { "$ref": "#/$defs/ChatInputAnswer" }, "description": "選用的最終答案取代，以問題 ID 為鍵" } }, "required": [ "type", "requestId", "response" ] }, "ChatTruncatedAction": { "type": "object", "description": "截斷工作階段的歷史。若提供 `turnId`，該回合之後的所有回合都會被移除，且保留指定的回合。若省略 `turnId`，所有回合都會被移除。\n\n若有活動回合，它會被靜默捨棄，且聊天狀態回到 `idle`。\n\n常見使用案例：截斷舊資料，然後以編輯過的訊息分派新的\n`chat/turnStarted`。", "properties": { "type": { "const": "chat/truncated" }, "turnId": { "type": "string", "description": "保留到並包含此回合為止的回合。省略以清除所有回合。" } }, "required": [ "type" ] }, "ChatTurnsLoadedAction": { "type": "object", "description": "將較舊的已完成回合載入此聊天的狀態。\n\n主機在回應 `fetchTurns` 之前，以及在套用任何參照比目前載入視窗更舊之回合的操作之前，分派此操作。`turns` 依最舊優先排序，並前置到目前的 `turns` 視窗。`turnsNextCursor` 取代狀態的游標；當所有保留回合現在都已載入時，省略它。", "properties": { "type": { "const": "chat/turnsLoaded" }, "turns": { "type": "array", "items": { "$ref": "#/$defs/Turn" }, "description": "載入狀態的較舊已完成回合，依最舊優先排序。" }, "turnsNextCursor": { "type": "string", "description": "用於載入下一個較舊頁面的不透明游標，若還有剩餘。" } }, "required": [ "type", "turns" ] }, "ChangesetStatusChangedAction": { "type": "object", "description": "此變更集的 {@link ChangesetState.status} 已轉換（例如\n`computing → ready`）。每當轉換為 {@link ChangesetStatus.Error | Error}\n時，錯誤有效負載會與 `status` 一併設定。", "properties": { "type": { "const": "changeset/statusChanged" }, "status": { "$ref": "#/$defs/ChangesetStatus", "description": "新的運算生命週期狀態。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "當 `status === ChangesetStatus.Error` 時的原因；否則省略。" } }, "required": [ "type", "status" ] }, "ChangesetFileSetAction": { "type": "object", "description": "在變更集中插入或更新 {@link ChangesetFile} — 新增新項目，或\n取代由 {@link ChangesetFile.id} 識別的既有項目。", "properties": { "type": { "const": "changeset/fileSet" }, "file": { "$ref": "#/$defs/ChangesetFile", "description": "新增或用來取代的檔案項目。" } }, "required": [ "type", "file" ] }, "ChangesetFileRemovedAction": { "type": "object", "description": "依識別碼從變更集中移除 {@link ChangesetFile}。\n\n通常於檔案被還原、暫存移出，或因其他原因不再屬於範圍時分派\n（例如重新命名的檔案被新項目取代）。", "properties": { "type": { "const": "changeset/fileRemoved" }, "fileId": { "type": "string", "description": "要移除之檔案的 {@link ChangesetFile.id}。" } }, "required": [ "type", "fileId" ] }, "ChangesetFilesReviewChangedAction": { "type": "object", "description": "為一個或多個檔案設定 {@link ChangesetFile.reviewed} 旗標 — GitHub\n風格的 \"Viewed\" 切換器，於單一批次中套用。\n\n依檔案的 {@link ChangesetFile.id} 為目標。{@link files} 中與變更集內\n目前存在之檔案不符的識別碼會被忽略；若無相符者，此操作為 no-op。\n僅每個相符檔案的 {@link ChangesetFile.reviewed} 欄位會受影響；檔案的\n{@link ChangesetFile.edit | edit} 與 {@link ChangesetFile._meta | _meta}\n則保持不變。\n\n僅對公告 {@link ChangesetCapabilities.review} 的變更集有意義。與其他\n所有 `changeset/*` 操作不同，此操作是 **用戶端可分派** 的：審核者直接\n切換審核狀態，透過預寫入 reducer 樂觀地套用它，並讓伺服器在正常的\n`action` 信封串流上回應它。伺服器 MAY 也自行產生它（例如代理程式將\n其自身的輸出標記為已審核）。\n\n協定層級沒有內容版本，因此當檔案內容在穩定識別碼下變更時，審核不會\n自動重設。伺服器是變更內容的權威者，會明確地重設審核 — 作法是\n重新發出檔案而不帶 `reviewed: true`，或是分派此操作並帶 `reviewed: false`。", "properties": { "type": { "const": "changeset/filesReviewChanged" }, "files": { "type": "array", "items": { "type": "string" }, "description": "審核狀態已變更之檔案的 {@link ChangesetFile.id | ids}。" }, "reviewed": { "type": "boolean", "description": "套用至每個列出檔案的新審核狀態：已審核時為 `true`，清除時為 `false`。" } }, "required": [ "type", "files", "reviewed" ] }, "ChangesetContentChangedAction": { "type": "object", "description": "變更集的完整內容已變更。完整取代語意：`files` 取代先前的檔案清單，\n而 `operations` 存在時取代先前的操作清單。\n\n產生者 SHOULD 將此操作用於初始快照與大量重新整理；至於增量更新，\n請使用 {@link ChangesetFileSetAction}、{@link ChangesetFileRemovedAction}\n與 {@link ChangesetOperationsChangedAction}。", "properties": { "type": { "const": "changeset/contentChanged" }, "files": { "type": "array", "items": { "$ref": "#/$defs/ChangesetFile" }, "description": "完整取代的檔案清單。" }, "operations": { "type": "array", "items": { "$ref": "#/$defs/ChangesetOperation" }, "description": "完整取代的操作清單。當操作未變更時省略。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "錯誤資訊（若變更集內容變更失敗）。" } }, "required": [ "type", "files" ] }, "ChangesetOperationsChangedAction": { "type": "object", "description": "此變更集上可用操作的集合已變更。完整取代語意：`operations` 取代先前\n的清單（或當 `operations` 為 `undefined` 時將其完全移除）。", "properties": { "type": { "const": "changeset/operationsChanged" }, "operations": { "type": "array", "items": { "$ref": "#/$defs/ChangesetOperation" }, "description": "更新後的操作清單。傳入 `undefined` 以清除所有操作。" } }, "required": [ "type", "operations" ] }, "ChangesetOperationStatusChangedAction": { "type": "object", "description": "單一操作的 {@link ChangesetOperation.status} 已轉換（例如\n`idle → running → idle`，或 `running → error`）。每當轉換為\n{@link ChangesetOperationStatus.Error | Error} 時，錯誤有效負載會與\n`status` 一併設定，並在任何其他轉換時清除。\n\n依其 {@link ChangesetOperation.id} 為單一操作的目標。若變更集中目前\n沒有該識別碼的操作，此操作為 no-op。請使用\n{@link ChangesetOperationsChangedAction} 來新增、移除或以其他方式\n取代操作清單本身。", "properties": { "type": { "const": "changeset/operationStatusChanged" }, "operationId": { "type": "string", "description": "狀態已變更之操作的 {@link ChangesetOperation.id}。" }, "status": { "$ref": "#/$defs/ChangesetOperationStatus", "description": "新的執行狀態。" }, "error": { "$ref": "#/$defs/ErrorInfo", "description": "當 `status === ChangesetOperationStatus.Error` 時的原因；否則省略。" } }, "required": [ "type", "operationId", "status" ] }, "ChangesetClearedAction": { "type": "object", "description": "從變更集中捨棄所有檔案。\n\n有兩種情況會用到此操作：\n1. 底層來源已變動（分支切換、分叉點失效等等），而伺服器正從頭重新\n 運算 — 後續的 {@link ChangesetFileSetAction} 項目會重新填入它。\n2. 擁有它的工作階段已結束，而 URI 正變為不可訂閱 — 伺服器會在\n 分派此操作後不久取消所有用戶端的訂閱。\n\n用戶端 SHOULD 在收到時釋放任何參照，且 SHOULD NOT 僅從此操作就區分\n這兩種情況 — 請改為對「即將消失」的情況反應對應的工作階段層級生命\n週期信號（例如 `root/sessionRemoved`）。", "properties": { "type": { "const": "changeset/cleared" } }, "required": [ "type" ] }, "AnnotationsSetAction": { "type": "object", "description": "在註解通道中 upsert 一個 {@link Annotation}——新增註解，\n或替換由 {@link Annotation.id} 識別的現有註解。\n\n由用戶端分派以建立註解（連同其必要的第一個條目），\n或重新錨定／解決現有註解；分派的用戶端指派\n{@link Annotation.id} 與任何新條目的 id。替換時，完整的註解\n有效負載（包含其 {@link Annotation.entries | entries} 清單）會被\n取代；產生者 SHOULD 偏好使用 {@link AnnotationsEntrySetAction}\n進行每條目編輯，並使用 {@link AnnotationsUpdatedAction} 來\n解決／重新錨定現有註解，以保持網路傳輸更新精簡。", "properties": { "type": { "const": "annotations/set" }, "annotation": { "$ref": "#/$defs/Annotation", "description": "新增或替換用的註解。MUST 至少包含一個條目。" } }, "required": [ "type", "annotation" ] }, "AnnotationsUpdatedAction": { "type": "object", "description": "部分更新現有 {@link Annotation} 的自身屬性——\n{@link AnnotationsSetAction} 的窄替代方案，適用於在不重新傳送\n{@link Annotation.entries | entries} 的情況下解決／重新開啟\n或重新錨定註解的常見情境。\n\n依其 {@link annotationId} 鎖定單一註解。僅寫入操作上出現的\n欄位；省略的欄位會讓對應的 {@link Annotation} 屬性保持不變。\n註解的 {@link Annotation.entries | entries}、\n{@link Annotation.id | id} 與 {@link Annotation._meta | _meta}\n絕不會被觸及——請分派 {@link AnnotationsSetAction} 來取代它們、\n清除 {@link range}（重新錨定至整個檔案），或使用\n{@link AnnotationsEntrySetAction}／\n{@link AnnotationsEntryRemovedAction} 編輯個別條目。\n\n若 {@link annotationId} 不符任何現有註解，則此操作為 no-op。", "properties": { "type": { "const": "annotations/updated" }, "annotationId": { "type": "string", "description": "要更新之註解的 {@link Annotation.id}。" }, "turnId": { "type": "string", "description": "將註解重新錨定至此回合產生的檔案版本。\n與擁有工作階段上的 {@link Turn.id} 相符。省略以保持\n現有的 {@link Annotation.turnId} 不變。" }, "resource": { "$ref": "#/$defs/URI", "description": "將註解重新錨定至此檔案。省略以保持現有的\n{@link Annotation.resource} 不變。" }, "range": { "$ref": "#/$defs/TextRange", "description": "將註解縮小至 {@link resource} 內的此範圍。省略以保持\n現有的 {@link Annotation.range} 不變；此操作無法清除現有\n範圍——請分派 {@link AnnotationsSetAction} 重新錨定至\n整個檔案。" }, "resolved": { "type": "boolean", "description": "將註解標記為已解決（`true`）或重新開啟（`false`）。省略以\n保持現有的 {@link Annotation.resolved} 狀態不變。" } }, "required": [ "type", "annotationId" ] }, "AnnotationsRemovedAction": { "type": "object", "description": "依 id 從通道移除 {@link Annotation}。\n\n分派以刪除整個註解及其包含的每個條目。因為協定禁止空註解，\n想要移除最後一個剩餘條目的用戶端會分派此操作——摺疊該\n註解——而非 {@link AnnotationsEntryRemovedAction}。", "properties": { "type": { "const": "annotations/removed" }, "annotationId": { "type": "string", "description": "要移除之註解的 {@link Annotation.id}。" } }, "required": [ "type", "annotationId" ] }, "AnnotationsEntrySetAction": { "type": "object", "description": "在現有註解中 upsert 一個 {@link AnnotationEntry}——新增條目，\n或替換由 {@link AnnotationEntry.id} 識別的條目。分派的用戶端\n指派新條目的 {@link AnnotationEntry.id}。若 {@link annotationId}\n不符任何現有註解，則此操作為 no-op。", "properties": { "type": { "const": "annotations/entrySet" }, "annotationId": { "type": "string", "description": "該條目所屬註解的 {@link Annotation.id}。" }, "entry": { "$ref": "#/$defs/AnnotationEntry", "description": "新增或替換用的條目。" } }, "required": [ "type", "annotationId", "entry" ] }, "AnnotationsEntryRemovedAction": { "type": "object", "description": "從註解移除單一 {@link AnnotationEntry} 而不摺疊註解本身。\n用於剩餘多個條目時——要移除最後一個條目，用戶端應改分派\n{@link AnnotationsRemovedAction}，因為協定禁止空註解。\n\n若 {@link annotationId} 或 {@link entryId} 不符目前狀態，\n則此操作為 no-op。", "properties": { "type": { "const": "annotations/entryRemoved" }, "annotationId": { "type": "string", "description": "該條目所屬註解的 {@link Annotation.id}。" }, "entryId": { "type": "string", "description": "要移除的 {@link AnnotationEntry.id}。" } }, "required": [ "type", "annotationId", "entryId" ] }, "TerminalDataAction": { "type": "object", "description": "終端機輸出資料（pty → 用戶端方向）。\n\n在 reducer 中將 `data` 附加到終端機的 `content`。\n\n`terminal/data` 與 `terminal/input` 是刻意分開的操作，因為標準的\n預寫入協調對終端機 I/O 並不安全。pty 是有狀態、可變動的行程 —\n樂觀地套用輸入或預測輸出會產生不正確的狀態。相反地，`terminal/input`\n是僅具副作用的操作（用戶端 → 伺服器 → pty），而 `terminal/data` 是\n伺服器權威的輸出（pty → 伺服器 → 用戶端）。", "properties": { "type": { "const": "terminal/data" }, "data": { "type": "string", "description": "輸出資料（可能包含 ANSI 逸出序列）" } }, "required": [ "type", "data" ] }, "TerminalInputAction": { "type": "object", "description": "傳送給終端機行程的鍵盤輸入（用戶端 → pty 方向）。\n\n這是僅具副作用的操作：伺服器將資料轉送到終端機的 pty。reducer 將此\n視為 no-op，因為 `terminal/data` 操作會反映任何產生的輸出。\n\n關於這兩個操作為何保持分開，請參見 `terminal/data`。", "properties": { "type": { "const": "terminal/input" }, "data": { "type": "string", "description": "要傳送給 pty 的輸入資料" } }, "required": [ "type", "data" ] }, "TerminalResizedAction": { "type": "object", "description": "終端機尺寸已變更。\n\n可由用戶端分派以請求調整大小，或由伺服器分派以告知用戶端實際的\n終端機尺寸。", "properties": { "type": { "const": "terminal/resized" }, "cols": { "type": "number", "description": "終端機寬度（以欄為單位）" }, "rows": { "type": "number", "description": "終端機高度（以列為單位）" } }, "required": [ "type", "cols", "rows" ] }, "TerminalClaimedAction": { "type": "object", "description": "終端機聲明已變更。用戶端或工作階段轉移終端機的所有權。\n\n若分派的用戶端目前未持有聲明，伺服器 SHOULD 拒絕。", "properties": { "type": { "const": "terminal/claimed" }, "claim": { "$ref": "#/$defs/TerminalClaim", "description": "新的聲明" } }, "required": [ "type", "claim" ] }, "TerminalTitleChangedAction": { "type": "object", "description": "終端機標題已變更。\n\n當終端機行程更新其標題（例如透過逸出序列）時由伺服器引發，\n或由用戶端分派以重新命名終端機。", "properties": { "type": { "const": "terminal/titleChanged" }, "title": { "type": "string", "description": "新的終端機標題" } }, "required": [ "type", "title" ] }, "TerminalCwdChangedAction": { "type": "object", "description": "終端機工作目錄已變更。", "properties": { "type": { "const": "terminal/cwdChanged" }, "cwd": { "$ref": "#/$defs/URI", "description": "新的工作目錄" } }, "required": [ "type", "cwd" ] }, "TerminalExitedAction": { "type": "object", "description": "終端機行程已結束。", "properties": { "type": { "const": "terminal/exited" }, "exitCode": { "type": "number", "description": "行程結束代碼。若行程被終止而未產生結束代碼則為 `undefined`。" } }, "required": [ "type" ] }, "TerminalClearedAction": { "type": "object", "description": "終端機回捲緩衝區已清除。", "properties": { "type": { "const": "terminal/cleared" } }, "required": [ "type" ] }, "TerminalCommandDetectionAvailableAction": { "type": "object", "description": "shell 整合已載入，終端機現在支援指令偵測。當 shell 整合變為可用時\n（這可能在終端機建立後非同步地發生），伺服器會分派此操作。\n\n在收到此操作（或 `terminal/commandExecuted`）之前，用戶端 MUST NOT\n假設指令偵測可用。", "properties": { "type": { "const": "terminal/commandDetectionAvailable" } }, "required": [ "type" ] }, "TerminalCommandExecutedAction": { "type": "object", "description": "指令已提交給 shell 並正在執行。\n所有後續的 `terminal/data` 操作（直到對應的\n`terminal/commandFinished`）構成此指令的輸出。", "properties": { "type": { "const": "terminal/commandExecuted" }, "commandId": { "type": "string", "description": "此指令的穩定識別碼，範圍限定於終端機 URI。\n允許將 `commandExecuted` → `commandFinished` 配對關聯起來。" }, "commandLine": { "type": "string", "description": "已提交的命令列文字" }, "timestamp": { "type": "number", "description": "指令開始執行時的 Unix 時間戳記（毫秒），於伺服器端量測。" } }, "required": [ "type", "commandId", "commandLine", "timestamp" ] }, "TerminalCommandFinishedAction": { "type": "object", "description": "指令已完成執行。\n\n在先前的 `terminal/commandExecuted`（相同 `commandId`）與此操作\n之間的 `terminal/data` 操作序列，構成該指令的完整輸出。", "properties": { "type": { "const": "terminal/commandFinished" }, "commandId": { "type": "string", "description": "與對應的 `commandExecuted` 之 `commandId` 相符" }, "exitCode": { "type": "number", "description": "shell 結束代碼。若 shell 未回報則為 `undefined`。" }, "durationMs": { "type": "number", "description": "指令的實際耗時（毫秒），由伺服器端的 shell 整合指令稿量測。" } }, "required": [ "type", "commandId" ] }, "ResourceWatchChangedAction": { "type": "object", "description": "監視器觀察到的一批資源變更。\n\n監視事件由伺服器合併為批次，以保持操作串流易於處理；\n空的 `changes.items` 清單 MUST NOT 被分派。reducer 不保留變更\n歷史——這些操作純粹是為了將事件傳遞給訂閱者，訂閱者直接\n從操作串流取用並套用各自的邏輯。", "properties": { "type": { "const": "resourceWatch/changed" }, "changes": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/$defs/ResourceChange" } } }, "required": [ "items" ], "description": "此批次中的變更集合，為向前相容而包裝。" } }, "required": [ "type", "changes" ] }, "ChatToolCallApprovedAction": { "type": "object", "description": "用戶端核准待處理的工具呼叫。工具轉換到 `running`。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallConfirmed" }, "approved": { "description": "工具呼叫已核准" }, "confirmed": { "$ref": "#/$defs/ToolCallConfirmationReason", "description": "工具確認的方式" }, "editedToolInput": { "type": "string", "description": "已編輯的工具輸入參數，若用戶端在確認前修改了它們" }, "selectedOptionId": { "type": "string", "description": "所選確認選項的 ID，若伺服器提供了選項" } }, "required": [ "turnId", "toolCallId", "type", "approved", "confirmed" ] }, "ChatToolCallDeniedAction": { "type": "object", "description": "用戶端拒絕待處理的工具呼叫。工具轉換到 `cancelled`。\n\n對於用戶端提供的工具，若擁有用戶端無法識別該工具或無法執行它，MUST 分派此操作。", "properties": { "turnId": { "type": "string", "description": "回合識別碼" }, "toolCallId": { "type": "string", "description": "工具呼叫識別碼" }, "_meta": { "type": "object", "additionalProperties": {}, "description": "此工具呼叫的額外提供者特定中繼資料。\n\n用戶端 MAY 在此尋找已知鍵以提供增強的 UI。\n例如，帶有 `{ input: string; output: string }` 的 `ptyTerminal` 鍵\n表示該工具在終端機上操作（`input` 與 `output` 都可能包含跳脫序列）。" }, "type": { "const": "chat/toolCallConfirmed" }, "approved": { "description": "工具呼叫已被拒絕" }, "reason": { "oneOf": [ { "const": "denied" }, { "const": "skipped" } ], "description": "工具取消的原因" }, "userSuggestion": { "$ref": "#/$defs/Message", "description": "使用者建議改為執行的動作" }, "reasonMessage": { "$ref": "#/$defs/StringOrMarkdown", "description": "拒絕的選用說明" }, "selectedOptionId": { "type": "string", "description": "所選確認選項的 ID，若伺服器提供了選項" } }, "required": [ "turnId", "toolCallId", "type", "approved", "reason" ] }, "PendingMessageKind": { "enum": [ "steering", "queued" ], "type": "string", "description": "待處理訊息種類的判別欄位。" } } }