根通道

ahp-root:// 通道的參考資料 — 每個用戶端最先訂閱的單一主機層級通道。線路層級的概觀請參閱根通道規格。

JSON Schema: state.schema.json

狀態類型

`PolicyState`

模型的策略組態狀態。

成員	值
`Enabled`	`'enabled'`
`Disabled`	`'disabled'`
`Unconfigured`	`'unconfigured'`

`RootState`

與每個訂閱 ahp-root:// 的用戶端共享的全域狀態。

欄位	類型	必要	說明
`agents`	AgentInfo[]	是	可用的代理程式後端及其模型
`activeSessions`	`number`	否	伺服器上作用中（未處置）工作階段的數量
`terminals`	TerminalInfo[]	否	伺服器上已知的終端機。訂閱個別終端機 URI 以取得完整狀態。
`config`	RootConfigState	否	代理主機的組態結構描述與目前值
`_meta`	`Record<string, unknown>`	否	關於代理主機本身的額外實作定義中繼資料。用戶端 MAY 在此尋找公認的鍵以提供增強的 UI。

`AgentInfo`

欄位	類型	必要	說明
`provider`	`string`	是	代理程式提供者 ID（例如 `'copilot'`）
`displayName`	`string`	是	人類可讀名稱
`description`	`string`	是	描述字串
`models`	SessionModelInfo[]	是	此代理程式可用的模型
`protectedResources`	ProtectedResourceMetadata[]	否	此代理程式要求驗證的受保護資源。每個項目使用 RFC 9728 語意描述一個 OAuth 2.0 受保護資源。用戶端應從宣告的 `authorization_servers` 取得權杖，並在以此代理程式建立工作階段之前，透過 `authenticate` 指令推送這些權杖。
`customizations`	Customization[]	否	與此代理程式相關聯的自訂項目。可能是容器自訂項目 —— 即代理程式隨附的 {@link PluginCustomization \| `PluginCustomization`} 項目，加上它在所使用的任何工作區中監視的 {@link DirectoryCustomization \| `DirectoryCustomization`} 項目 —— 或是代理主機直接宣告的頂層 {@link McpServerCustomization \| `McpServerCustomization`} 項目。當以此代理程式建立工作階段時，這些項目會被增強（例如將目錄 URI 解析為相對於工作區、解析子項）並傳播至工作階段的 `customizations` 清單。
`capabilities`	AgentCapabilities	否	代理程式關於自身所宣告的靜態能力。用戶端使用這些能力來控制功能（多聊天、分支）的啟用，而不是依提供者 id 切換。

`AgentCapabilities`

{@link AgentInfo} 所宣告的靜態能力。仿照 MCP 能力建模：每個欄位都是選用加入，其存在（一個空物件 {}）表示支援，而缺席表示不支援該功能且對應的用戶端指令 MUST NOT 被使用。子欄位承載各能力專屬的選項。

欄位	類型	必要	說明
`multipleChats`	MultipleChatsCapability	否	代理程式可在每個工作階段中託管多個並行聊天。缺席時，用戶端 MUST NOT 呼叫 `createChat` 來開啟工作階段啟動時所伴隨預設聊天以外的聊天。空物件 `{}` 宣告多聊天但不支援基於來源的建立；設定 {@link MultipleChatsCapability.fork} 或 {@link MultipleChatsCapability.sideChat} 以允許對應的模式。
`multipleWorkingDirectories`	MultipleWorkingDirectoriesCapability	否	工作階段的代理程式可被授予對多個工作目錄的工具存取權。這些目錄被視為同等對等項目，除非代理程式宣告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} （某些後端需要將一個目錄指定為主要根）。缺席時，用戶端 MUST NOT 變動工作階段或聊天的工作目錄集合，且 MUST NOT 在 {@link CreateSessionParams.workingDirectories} 中設定多於一個項目。

`MultipleChatsCapability`

{@link AgentCapabilities.multipleChats} 能力的選項。

欄位	類型	必要	說明
`fork`	`boolean`	否	代理程式可從特定回合分支聊天。缺席或 `false` 時，用戶端 MUST NOT 將帶有 `kind: "fork"` 的 {@link ChatSource} 傳給 `createChat`。分支一律表示支援多聊天。
`sideChat`	`boolean`	否	代理程式可從特定回合建立側邊聊天。缺席或 `false` 時，用戶端 MUST NOT 將帶有 `kind: "sideChat"` 的 {@link ChatSource} 傳給 `createChat`。側邊聊天會以來源回合作為脈絡，而不會將來源對話記錄複製到自身可見的歷程中。來源由穩定的 `turnId` 識別，主機會將其解析為相對於來源聊天目前的 `activeTurn` 或保留的歷程。當其指名為目前作用中的回合時，主機會在建立時對可用的部分代理程式回應建立快照。側邊聊天支援一律表示支援多聊天。

`MultipleWorkingDirectoriesCapability`

{@link AgentCapabilities.multipleWorkingDirectories} 能力的選項。

欄位	類型	必要	說明
`requiresPrimary`	`boolean`	否	代理程式要求每個聊天將其工作目錄之一指定為主要 —— 即聊天所圍繞的區別根（例如該聊天代理程式的程序根、相對路徑的預設位置）。主要是一個每個聊天的概念，固定於聊天建立之時。為 `true` 時，用戶端 SHOULD 提供 {@link CreateChatParams.primaryWorkingDirectory}（以及 {@link CreateSessionParams.primaryWorkingDirectory}，其為工作階段預設聊天播種）；主機 MAY 拒絕省略它的建立，或退回至聊天工作目錄的第一個項目。所選的主要目錄會在 {@link ChatState.primaryWorkingDirectory} 上（唯讀）回報。缺席或 `false` 時，代理程式沒有主要目錄 —— 所有目錄皆為同等對等項目，用戶端無須指定。

`SessionModelInfo`

欄位	類型	必要	說明
`id`	`string`	是	模型識別碼
`provider`	`string`	是	此模型所屬的提供者
`name`	`string`	是	人類可讀的模型名稱
`maxContextWindow`	`number`	否	上下文視窗大小上限
`maxOutputTokens`	`number`	否	模型可產生的輸出權杖數上限
`maxPromptTokens`	`number`	否	模型接受的提示（輸入）權杖數上限
`supportsVision`	`boolean`	否	模型是否支援視覺
`policyState`	PolicyState	否	策略組態狀態
`configSchema`	ConfigSchema	否	描述模型專屬選項（例如思考等級）的組態結構描述。用戶端將此呈現為表單，並在建立或變更工作階段時，將解析後的值傳入 {@link ModelSelection.config}。
`_meta`	`Record<string, unknown>`	否	此模型的額外提供者專屬中繼資料。用戶端 MAY 在此尋找公認的鍵以提供增強的 UI。例如，`pricing` 鍵可承載模型定價中繼資料。

`ModelSelection`

模型選擇：所選的模型 ID 連同任何模型專屬組態值，這些值的鍵對應於模型的 {@link SessionModelInfo.configSchema}。

欄位	類型	必要	說明
`id`	`string`	是	模型識別碼
`config`	Record<string, JsonPrimitive>	否	模型專屬組態值。值為 JSON 基本型別：大多數挑選器產生字串，但有些（例如數值上下文大小挑選器）產生數字或布林值，這些會原樣傳遞。

`RootConfigState`

即時代理主機組態中繼資料。

結構描述描述可用的組態屬性，而值包含每個已解析屬性的目前值。

欄位	類型	說明
`schema`	ConfigSchema	描述可用組態屬性的 JSON Schema
`values`	`Record<string, unknown>`	目前的組態值

操作

變動 RootState。所有根操作僅限伺服器端。

JSON Schema: actions.schema.json

`root/agentsChanged`

當可用的代理程式後端或其模型變更時觸發。

欄位	類型	說明
`type`	ActionType.RootAgentsChanged
`agents`	AgentInfo[]	更新後的代理程式清單

`root/activeSessionsChanged`

當作用中工作階段的數量變更時觸發。

欄位	類型	說明
`type`	ActionType.RootActiveSessionsChanged
`activeSessions`	`number`	目前作用中工作階段的計數

`root/terminalsChanged`

當已知終端機清單變更時觸發。

全替換語意：terminals 陣列完全取代先前的 terminals。

欄位	類型	說明
`type`	ActionType.RootTerminalsChanged
`terminals`	TerminalInfo[]	更新後的終端機清單（全替換）

`root/configChanged`

當代理主機組態值變更時觸發。

依預設，化簡器會將新值合併進 state.config.values。將 replace 設為 true 以取代所有值，而不是合併。

欄位	類型	必要	說明
`type`	ActionType.RootConfigChanged	是
`config`	`Record<string, unknown>`	是	更新後的組態值
`replace`	`boolean`	否	為 `true` 時，取代所有組態值而不是合併

指令

JSON Schema: commands.schema.json

`listSessions`

傳回工作階段摘要的清單。用於填入工作階段清單與側邊欄。

工作階段清單不是狀態樹的一部分，因為它可能任意龐大。用戶端以命令式方式取得它，並維護一個由 root/sessionAdded 與 root/sessionRemoved 通知更新的本機快取。

大型目錄可透過 {@link PaginatedParams} 的 limit/cursor 輸入以漸進方式取得（完整的分頁合約請參見該型別）。伺服器 SHOULD 先傳回最近修改的項目，使第一頁成為立即可用的一頁。root/session* 通知讓已取得的頁面保持最新；分頁僅控管初始與回填的取得。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	說明
`channel`	`'ahp-root://'`

結果：

欄位	類型	說明
`items`	SessionSummary[]	工作階段摘要的清單。伺服器 SHOULD 將其以最近修改優先排序。

範例：

jsonc

// Client → Server (fetch the first page of up to 50 sessions)
{ "jsonrpc": "2.0", "id": 4, "method": "listSessions",
  "params": { "channel": "ahp-root://", "limit": 50 } }

// Server → Client (a cursor signals more entries exist)
{ "jsonrpc": "2.0", "id": 4, "result": {
  "items": [ { "id": "s1", ... }, { "id": "s2", ... } ],
  "nextCursor": "eyJvIjo1MH0="
}}

// Client → Server (fetch the next page)
{ "jsonrpc": "2.0", "id": 5, "method": "listSessions",
  "params": { "channel": "ahp-root://", "limit": 50, "cursor": "eyJvIjo1MH0=" } }

`resolveSessionConfig`

反覆解析工作階段組態結構描述。用戶端傳送目前的部分工作階段組態與任何使用者填入的中繼資料值。伺服器傳回一個屬性結構描述，說明在目前選取的脈絡下還需要哪些額外中繼資料。

每當使用者變更重大輸入（例如挑選工作目錄、切換屬性）時，用戶端就會呼叫此指令。每次回應都會傳回完整的目前屬性集合（而非差異）。所傳回的 values 包含伺服器解析後的預設值，以傳遞給 createSession。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	必要	說明
`channel`	`'ahp-root://'`	是
`provider`	`string`	否	代理程式提供者 ID
`workingDirectory`	URI	否	工作階段的工作目錄
`config`	`Record<string, unknown>`	否	目前使用者填入的組態值

結果：

欄位	類型	說明
`schema`	SessionConfigSchema	描述給定目前脈絡下可用組態屬性的 JSON Schema
`values`	`Record<string, unknown>`	目前的組態值（回送並套用伺服器解析後的預設值）

範例：

jsonc

// Step 1: Client picks a working directory
// Client → Server
{ "jsonrpc": "2.0", "id": 5, "method": "resolveSessionConfig",
  "params": { "workingDirectory": "file:///home/user/my-project" } }

// Server → Client (git repo detected, offers worktree option)
{ "jsonrpc": "2.0", "id": 5, "result": {
  "schema": {
    "type": "object",
    "properties": {
      "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] }
    }
  },
  "values": {}
}}

// Step 2: User enables worktree
// Client → Server
{ "jsonrpc": "2.0", "id": 6, "method": "resolveSessionConfig",
  "params": { "workingDirectory": "file:///home/user/my-project",
              "config": { "target": "worktree" } } }

// Server → Client (now requires branch selection)
{ "jsonrpc": "2.0", "id": 6, "result": {
  "schema": {
    "type": "object",
    "properties": {
      "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] },
      "baseBranch": { "type": "string", "title": "Base Branch",
                      "enum": ["main", "develop"],
                      "enumLabels": ["main", "develop"] }
    },
    "required": ["baseBranch"]
  },
  "values": { "target": "worktree" }
}}

`sessionConfigCompletions`

向伺服器查詢動態工作階段組態屬性的允許值。

用於 resolveSessionConfig 傳回之結構描述中的屬性具有 enumDynamic: true 時。用戶端傳送搜尋查詢，並接收帶有顯示中繼資料的相符值。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	必要	說明
`channel`	`'ahp-root://'`	是
`provider`	`string`	否	代理程式提供者 ID
`workingDirectory`	URI	否	工作階段的工作目錄
`config`	`Record<string, unknown>`	否	目前使用者填入的組態值（為查詢提供脈絡）
`property`	`string`	是	要為其查詢值的結構描述屬性 id
`query`	`string`	否	搜尋篩選文字（空白或省略時傳回預設/最近值）

結果：

欄位	類型	說明
`items`	SessionConfigValueItem[]	相符的值項目

範例：

jsonc

// Client → Server (user types "ma" in branch picker)
{ "jsonrpc": "2.0", "id": 7, "method": "sessionConfigCompletions",
  "params": { "workingDirectory": "file:///home/user/my-project",
              "config": { "target": "worktree" },
              "property": "baseBranch", "query": "ma" } }

// Server → Client
{ "jsonrpc": "2.0", "id": 7, "result": {
  "items": [
    { "value": "main", "label": "main", "icon": "git-branch" },
    { "value": "main-v2", "label": "main-v2", "icon": "git-branch" }
  ]
}}

通知

JSON Schema: notifications.schema.json

`root/sessionAdded`

當建立新工作階段時，廣播給所有訂閱根通道的用戶端。

屬性	值
方向	伺服器 → 用戶端
類型	通知

參數：

欄位	類型	說明
`channel`	URI	此通知所屬的通道 URI（根通道）
`summary`	SessionSummary	新工作階段的摘要

範例：

json

{
  "jsonrpc": "2.0",
  "method": "root/sessionAdded",
  "params": {
    "channel": "ahp-root://",
    "summary": {
      "resource": "ahp-session:/<uuid>",
      "provider": "copilot",
      "title": "New Session",
      "status": 1,
      "createdAt": "2024-03-09T16:00:00.000Z",
      "modifiedAt": "2024-03-09T16:00:00.000Z"
    }
  }
}

`root/sessionRemoved`

當工作階段被處置時，廣播給所有訂閱根通道的用戶端。

屬性	值
方向	伺服器 → 用戶端
類型	通知

參數：

欄位	類型	說明
`channel`	URI	此通知所屬的通道 URI（根通道）
`session`	URI	已移除工作階段的 URI

範例：

json

{
  "jsonrpc": "2.0",
  "method": "root/sessionRemoved",
  "params": {
    "channel": "ahp-root://",
    "session": "ahp-session:/<uuid>"
  }
}

`root/sessionSummaryChanged`

當現有工作階段的摘要變更（標題、狀態、modifiedAt、模型、工作目錄、已讀/完成狀態或差異統計）時，廣播給所有訂閱根通道的用戶端。

此通知讓維護快取工作階段清單的用戶端（例如先前 listSessions() 呼叫的結果）能與進行中的工作階段保持同步，而無須個別訂閱每個工作階段 URI。它是 root/sessionAdded 與 root/sessionRemoved 的補充，而非取代：後兩者發出生命週期（建立/處置）訊號，而此通知發出已知工作階段上的摘要層級變動訊號。

語意：

僅存在於 changes 中的欄位具有新值；省略的欄位在用戶端快取的摘要中未變更。
身分識別欄位（resource、provider、createdAt）永不變更且不予承載。
如同所有協定通知，此通知為短暫的：它不會在重新連線時重播。在重新連線時，用戶端應如常透過 listSessions() 重新取得完整目錄。
每當伺服器已透過 listSessions() 或 root/sessionAdded 呈現之工作階段的 {@link SessionSummary | SessionSummary} 上任何可變欄位變更時，伺服器 SHOULD 發出此通知。伺服器 MAY 自行斟酌合併或去抖動頻繁變動欄位的更新（例如回合串流時的 modifiedAt 更新）。
對 session 沒有快取項目的用戶端 MAY 忽略此通知；它不是 root/sessionAdded 的替代品。

屬性	值
方向	伺服器 → 用戶端
類型	通知

參數：

欄位	類型	說明
`channel`	URI	此通知所屬的通道 URI（根通道）
`session`	URI	摘要變更之工作階段的 URI
`changes`	Partial<SessionSummary>	已變更的可變摘要欄位；省略的欄位未變更。身分識別欄位（`resource`、`provider`、`createdAt`）永不變更且傳送者 MUST 予以省略；接收者若收到 SHOULD 忽略它們。

範例：

json

{
  "jsonrpc": "2.0",
  "method": "root/sessionSummaryChanged",
  "params": {
    "channel": "ahp-root://",
    "session": "ahp-session:/<uuid>",
    "changes": {
      "title": "Refactor auth middleware",
      "status": 8,
      "modifiedAt": "2024-03-09T16:02:03.456Z"
    }
  }
}

`root/progress`

長時間執行作業的通用進度通知。

用戶端透過在請求中納入 progressToken 來選擇加入該請求的進度（目前： createSession 上的 progressToken 欄位）。若伺服器為服務該請求而執行長時間執行的工作 —— 例如在該提供者之工作階段首次具體化時，延遲下載代理程式的原生 SDK —— 它會發出帶有相同權杖的 progress 通知。

此通知與作業無關：它對什麼正在進展不予說明。用戶端將 progressToken 關聯回其發起的請求（因而關聯至等待它的 UI 介面），並呈現自身本地化的指示器。同一通道可服務未來任何長時間執行的作業，而無需新的方法。

語意：

對給定的 progressToken，progress 為單調非遞減。
total 僅在伺服器事先知道大小（例如 Content-Length）時存在；缺席時用戶端 SHOULD 顯示不定指示器。
當 progress === total 時作業完成。伺服器 MUST 發出滿足 progress === total 的結尾訊框；當大小從未知時，它會在該訊框上將 total 設為最終的 progress。之後不會有其他訊框參照該權杖。
伺服器 MAY 完全不發出進度（例如工作已完成）；則用戶端永不顯示指示器。
如同所有通知，此通知為短暫的且不會在重新連線時重播。從未收到結尾訊框的用戶端 SHOULD 在閒置逾時後讓指示器過期。

屬性	值
方向	伺服器 → 用戶端
類型	通知

參數：

欄位	類型	必要	說明
`channel`	URI	是	此通知所屬的通道 URI（根通道）。
`progressToken`	`string`	是	回應用戶端在發起請求上提供的 `progressToken`（例如 `createSession` 的 `progressToken` 欄位），將此訊框關聯至該呼叫。在用戶端作用中的請求間為唯一。
`progress`	`number`	是	目前為止的進度，以作業定義的單位表示（例如已接收位元組）。對給定的 `progressToken` 為單調非遞減。
`total`	`number`	否	事先知道大小時的總計（例如來自 `Content-Length`）；省略 ⇒ 不定。一旦 `progress === total` 時作業即完成。
`message`	`string`	否	選用的人類可讀進度訊息。用戶端擁有自身衍生自發起請求的（本地化）呈現；不追蹤權杖的通用用戶端 MAY 改為顯示此訊息。

範例：

json

{
  "jsonrpc": "2.0",
  "method": "root/progress",
  "params": {
    "channel": "ahp-root://",
    "progressToken": "9b2c1f7e-4a0d-4e2b-8b1a-2f7e4a0d4e2b",
    "progress": 18874368,
    "total": 41957498
  }
}

根通道 ​

狀態類型 ​

PolicyState ​

RootState ​

AgentInfo ​

AgentCapabilities ​

MultipleChatsCapability ​

MultipleWorkingDirectoriesCapability ​

SessionModelInfo ​

ModelSelection ​

RootConfigState ​

操作 ​

root/agentsChanged ​

root/activeSessionsChanged ​

root/terminalsChanged ​

root/configChanged ​

指令 ​

listSessions ​

resolveSessionConfig ​

sessionConfigCompletions ​

通知 ​

root/sessionAdded ​

root/sessionRemoved ​

root/sessionSummaryChanged ​

root/progress ​

根通道

狀態類型

`PolicyState`

`RootState`

`AgentInfo`

`AgentCapabilities`

`MultipleChatsCapability`

`MultipleWorkingDirectoriesCapability`

`SessionModelInfo`

`ModelSelection`

`RootConfigState`

操作

`root/agentsChanged`

`root/activeSessionsChanged`

`root/terminalsChanged`

`root/configChanged`

指令

`listSessions`

`resolveSessionConfig`

`sessionConfigCompletions`

通知

`root/sessionAdded`

`root/sessionRemoved`

`root/sessionSummaryChanged`

`root/progress`