{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$comment": "Generated from types/state.ts — do not edit", "$id": "https://microsoft.github.io/agent-host-protocol/schema/state.schema.json", "title": "AHP State Types", "description": "All state types in the Agent Host Protocol.", "$defs": { "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" ] }, "StringOrMarkdown": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "markdown": { "type": "string" } }, "required": [ "markdown" ] } ], "description": "可選擇以 Markdown 呈現的字串。\n\n- 純 `string` 會原樣呈現（不進行 Markdown 處理）。\n- 帶有 `{ markdown: string }` 的物件會以 Markdown 格式呈現。" }, "JsonPrimitive": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "基本 JSON 值：字串、數字、布林值或 `null`。" }, "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` 移除該項目。" }, "ChildCustomizationType": { "oneOf": [ { "const": "agent" }, { "const": "skill" }, { "const": "prompt" }, { "const": "rule" }, { "const": "hook" }, { "const": "mcpServer" } ], "description": "作為 {@link PluginCustomization} 或 {@link DirectoryCustomization} 子項\n出現的自訂類型。" }, "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} 內的子自訂。" }, "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}。" }, "McpServerState": { "oneOf": [ { "$ref": "#/$defs/McpServerStartingState" }, { "$ref": "#/$defs/McpServerReadyState" }, { "$ref": "#/$defs/McpServerAuthRequiredState" }, { "$ref": "#/$defs/McpServerErrorState" }, { "$ref": "#/$defs/McpServerStoppedState" } ], "description": "所有 MCP 伺服器生命週期狀態的判別聯集。\n以 `kind`（一個 {@link McpServerStatus} 值）作為判別。" }, "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 保持兩者一致。" }, "ChatInputQuestion": { "oneOf": [ { "$ref": "#/$defs/ChatInputTextQuestion" }, { "$ref": "#/$defs/ChatInputNumberQuestion" }, { "$ref": "#/$defs/ChatInputBooleanQuestion" }, { "$ref": "#/$defs/ChatInputSingleSelectQuestion" }, { "$ref": "#/$defs/ChatInputMultiSelectQuestion" } ], "description": "聊天輸入請求中的單一問題。" }, "ChatInputAnswerValue": { "oneOf": [ { "$ref": "#/$defs/ChatInputTextAnswerValue" }, { "$ref": "#/$defs/ChatInputNumberAnswerValue" }, { "$ref": "#/$defs/ChatInputBooleanAnswerValue" }, { "$ref": "#/$defs/ChatInputSelectedAnswerValue" }, { "$ref": "#/$defs/ChatInputSelectedManyAnswerValue" } ] }, "ChatInputAnswer": { "oneOf": [ { "$ref": "#/$defs/ChatInputAnswered" }, { "$ref": "#/$defs/ChatInputSkipped" } ], "description": "單一問題的草稿、已提交或已跳過答案。" }, "MessageAttachment": { "oneOf": [ { "$ref": "#/$defs/SimpleMessageAttachment" }, { "$ref": "#/$defs/MessageEmbeddedResourceAttachment" }, { "$ref": "#/$defs/MessageResourceAttachment" }, { "$ref": "#/$defs/MessageAnnotationsAttachment" }, { "$ref": "#/$defs/MessageChatAttachment" } ], "description": "與 {@link Message} 關聯的附件。" }, "ResponsePart": { "oneOf": [ { "$ref": "#/$defs/MarkdownResponsePart" }, { "$ref": "#/$defs/ResourceReponsePart" }, { "$ref": "#/$defs/ToolCallResponsePart" }, { "$ref": "#/$defs/ReasoningResponsePart" }, { "$ref": "#/$defs/SystemNotificationResponsePart" }, { "$ref": "#/$defs/InputRequestResponsePart" } ] }, "ToolCallRiskAssessment": { "oneOf": [ { "$ref": "#/$defs/ToolCallRiskAssessmentLoadingState" }, { "$ref": "#/$defs/ToolCallRiskAssessmentCompleteState" } ] }, "ToolCallContributor": { "oneOf": [ { "$ref": "#/$defs/ToolCallClientContributor" }, { "$ref": "#/$defs/ToolCallMcpContributor" } ] }, "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)。" }, "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} 呈現。" }, "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 擴充）。" }, "TerminalClaim": { "oneOf": [ { "$ref": "#/$defs/TerminalClientClaim" }, { "$ref": "#/$defs/TerminalSessionClaim" } ], "description": "描述目前誰持有終端機。終端機可由已連線的用戶端或工作階段聲明（例如在工具呼叫期間）。" }, "TerminalContentPart": { "oneOf": [ { "$ref": "#/$defs/TerminalUnclassifiedPart" }, { "$ref": "#/$defs/TerminalCommandPart" } ], "description": "終端機輸出中的內容片段。" }, "URI": { "type": "string", "description": "URI 字串（例如 `ahp-root://`、`ahp-session:/` 或 `ahp-chat:/`）。" }, "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": "工作階段初始化狀態。" }, "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定義的三種失敗模式。" }, "ChatInteractivity": { "enum": [ "full", "read-only", "hidden" ], "type": "string", "description": "使用者可如何與聊天互動。\n\n- `Full` — 使用者可傳送訊息並觀看（缺省時為預設）\n- `ReadOnly` — 使用者可觀看但無法傳送訊息（例如代理程式團隊工作者）\n- `Hidden` — 完全不顯示在 UI 中的內部工作者\n\n支援代理程式團隊模式，其中主導聊天為完全互動，而工作者聊天為唯讀\n（可見以供可觀測性）或隱藏（內部實作細節）。框架根據聊天的角色\n設定此值；UI 使用它來顯示適當的控制項。" }, "TurnState": { "enum": [ "complete", "cancelled", "error" ], "type": "string", "description": "回合如何結束。" }, "MessageKind": { "enum": [ "user", "agent", "tool", "systemNotification" ], "type": "string", "description": "{@link MessageOrigin} 的判別欄位 — 識別訊息的產生者。" }, "ChatInputResponseKind": { "enum": [ "accept", "decline", "cancel" ], "type": "string", "description": "用戶端如何完成輸入請求。" }, "ToolCallRiskAssessmentKind": { "enum": [ "judge" ], "type": "string", "description": "將模型評審器識別為確認需求的來源。" }, "ConfirmationOptionKind": { "enum": [ "approve", "deny" ], "type": "string", "description": "確認選項是否代表核准或拒絕動作。" }, "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": "工具呼叫為何被取消。" }, "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} 的判別欄位。" } } }