終端機通道
ahp-terminal:/<id> 通道的參考資料 — 可連結至用戶端及/或工作階段的長生命週期偽終端機。線路層級的概觀請參閱終端機通道規格。
JSON Schema: state.schema.json
狀態類型
TerminalInfo
在根狀態上公開的輕量終端機中繼資料。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
resource | URI | 是 | 終端機 URI（可訂閱以取得完整終端機狀態） |
title | string | 是 | 人類可讀的終端機標題 |
claim | TerminalClaim | 是 | 目前誰持有此終端機 |
exitCode | number | 否 | 行程結束代碼（若終端機行程已結束） |
TerminalClaimKind
終端機聲明種類的判別欄位。
| 成員 | 值 |
|---|---|
Client | 'client' |
Session | 'session' |
TerminalClientClaim
由已連線的用戶端聲明的終端機。
| 欄位 | 類型 | 說明 |
|---|---|---|
kind | TerminalClaimKind.Client | 判別欄位 |
clientId | string | 聲明此終端機之用戶端的 clientId |
TerminalSessionClaim
由工作階段聲明的終端機，可選擇性地限定到特定回合或工具呼叫。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
kind | TerminalClaimKind.Session | 是 | 判別欄位 |
session | URI | 是 | 聲明此終端機的工作階段 URI |
turnId | string | 否 | 工作階段內的選用回合識別碼 |
toolCallId | string | 否 | 回合內的選用工具呼叫識別碼 |
TerminalClaim
描述目前誰持有終端機。終端機可由已連線的用戶端或工作階段聲明（例如在工具呼叫期間）。
TerminalClientClaim | TerminalSessionClaim
TerminalState
單一終端機的完整狀態，當用戶端訂閱終端機的 URI 時載入。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
title | string | 是 | 人類可讀的終端機標題 |
cwd | URI | 否 | 終端機行程的當前工作目錄 |
cols | number | 否 | 終端機寬度（以欄為單位） |
rows | number | 否 | 終端機高度（以列為單位） |
content | TerminalContentPart[] | 是 | 具類型的內容片段，取代平坦的 content: string。只需要原始 VT 串流的簡易消費者可用以下方式重建它： content.map(p => p.type === 'command' ? p.output : p.value).join('')需要指令邊界的消費者可依片段類型篩選。 |
exitCode | number | 否 | 行程結束代碼，於終端機行程結束時設定 |
claim | TerminalClaim | 是 | 目前誰持有此終端機 |
supportsCommandDetection | boolean | 否 | 此終端機是否發出 terminal/commandExecuted 與 terminal/commandFinished 操作並填入 command 類型的片段。用戶端 MUST 在依賴指令偵測前檢查此旗標。 切勿以 command 片段的存在與否作為功能旗標 — 片段 在正常閒置狀態下是不存在的。 |
isPty | boolean | 否 | 此終端機風格資源是否由虛擬終端機支撐。 當值為 false 時，輸出為純文字，用戶端不需要解析 VT 序列。 |
TerminalContentPart
終端機輸出中的內容片段。
TerminalUnclassifiedPart | TerminalCommandPart
TerminalUnclassifiedPart
非結構化的終端機輸出 — 指令之前、之間或之後的內容， 或來自不支援指令偵測的終端機。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | 'unclassified' | 判別欄位 |
value | string | 累積的 VT 輸出。當沒有指令執行時，由 terminal/data 附加至此。 |
TerminalCommandPart
單一指令：其命令列與其產生的輸出。
當 isComplete 為 false 時，指令仍在執行；隨著 terminal/data 操作抵達，output 會增長。在 terminal/commandFinished 時，此片段 會就地變動為 isComplete: true 並帶有完成中繼資料。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | 'command' | 是 | 判別欄位 |
commandId | string | 是 | 穩定識別碼，與對應的 terminal/commandExecuted 與 terminal/commandFinished 操作上的 commandId 相符。 |
commandLine | string | 是 | 提交給 shell 的命令列。 |
output | string | 是 | 累積的 VT 輸出。當 isComplete 為 false 時，由 terminal/data 附加至此。 shell 整合逸出序列由伺服器剝除。 |
timestamp | number | 是 | 執行開始時的 Unix 時間戳記（毫秒），由伺服器回報。 |
isComplete | boolean | 是 | 指令是否已完成。 |
exitCode | number | 否 | shell 結束代碼。於完成時設定。未知時為 undefined。 |
durationMs | number | 否 | 實際耗時（毫秒）。於完成時設定。 |
操作
變動 TerminalState。透過外層的 ActionEnvelope.channel 限定於某個終端機 URI。
JSON Schema: actions.schema.json
terminal/data
終端機輸出資料（pty → 用戶端方向）。
在 reducer 中將 data 附加到終端機的 content。
terminal/data 與 terminal/input 是刻意分開的操作，因為標準的 預寫入協調對終端機 I/O 並不安全。pty 是有狀態、可變動的行程 — 樂觀地套用輸入或預測輸出會產生不正確的狀態。相反地，terminal/input 是僅具副作用的操作（用戶端 → 伺服器 → pty），而 terminal/data 是 伺服器權威的輸出（pty → 伺服器 → 用戶端）。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalData | |
data | string | 輸出資料（可能包含 ANSI 逸出序列） |
terminal/input
傳送給終端機行程的鍵盤輸入（用戶端 → pty 方向）。
這是僅具副作用的操作：伺服器將資料轉送到終端機的 pty。reducer 將此 視為 no-op，因為 terminal/data 操作會反映任何產生的輸出。
關於這兩個操作為何保持分開，請參見 terminal/data。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalInput | |
data | string | 要傳送給 pty 的輸入資料 |
terminal/resized
終端機尺寸已變更。
可由用戶端分派以請求調整大小，或由伺服器分派以告知用戶端實際的 終端機尺寸。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalResized | |
cols | number | 終端機寬度（以欄為單位） |
rows | number | 終端機高度（以列為單位） |
terminal/claimed
終端機聲明已變更。用戶端或工作階段轉移終端機的所有權。
若分派的用戶端目前未持有聲明，伺服器 SHOULD 拒絕。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalClaimed | |
claim | TerminalClaim | 新的聲明 |
terminal/titleChanged
終端機標題已變更。
當終端機行程更新其標題（例如透過逸出序列）時由伺服器引發， 或由用戶端分派以重新命名終端機。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalTitleChanged | |
title | string | 新的終端機標題 |
terminal/cwdChanged
終端機工作目錄已變更。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalCwdChanged | |
cwd | URI | 新的工作目錄 |
terminal/exited
終端機行程已結束。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | ActionType.TerminalExited | 是 | |
exitCode | number | 否 | 行程結束代碼。若行程被終止而未產生結束代碼則為 undefined。 |
terminal/cleared
終端機回捲緩衝區已清除。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalCleared |
terminal/commandDetectionAvailable
shell 整合已載入，終端機現在支援指令偵測。當 shell 整合變為可用時 （這可能在終端機建立後非同步地發生），伺服器會分派此操作。
在收到此操作（或 terminal/commandExecuted）之前，用戶端 MUST NOT 假設指令偵測可用。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalCommandDetectionAvailable |
terminal/commandExecuted
指令已提交給 shell 並正在執行。 所有後續的 terminal/data 操作（直到對應的 terminal/commandFinished）構成此指令的輸出。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.TerminalCommandExecuted | |
commandId | string | 此指令的穩定識別碼，範圍限定於終端機 URI。 允許將 commandExecuted → commandFinished 配對關聯起來。 |
commandLine | string | 已提交的命令列文字 |
timestamp | number | 指令開始執行時的 Unix 時間戳記（毫秒），於伺服器端量測。 |
terminal/commandFinished
指令已完成執行。
在先前的 terminal/commandExecuted（相同 commandId）與此操作 之間的 terminal/data 操作序列，構成該指令的完整輸出。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | ActionType.TerminalCommandFinished | 是 | |
commandId | string | 是 | 與對應的 commandExecuted 之 commandId 相符 |
exitCode | number | 否 | shell 結束代碼。若 shell 未回報則為 undefined。 |
durationMs | number | 否 | 指令的實際耗時（毫秒），由伺服器端的 shell 整合指令稿量測。 |
指令
JSON Schema: commands.schema.json
createTerminal
在伺服器上建立新的終端機。
建立後，用戶端應訂閱終端機 URI 以接收狀態更新。伺服器分派 root/terminalsChanged 以更新根終端機清單。
| 屬性 | 值 |
|---|---|
| 方向 | 用戶端 → 伺服器 |
| 類型 | 請求 |
參數：
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
channel | URI | 是 | 終端機 URI（由用戶端選擇）。 |
claim | TerminalClaim | 是 | 終端機的初始擁有者 |
name | string | 否 | 人類可讀的終端機名稱 |
cwd | URI | 否 | 初始工作目錄 URI |
cols | number | 否 | 初始終端機寬度（以欄為單位） |
rows | number | 否 | 初始終端機高度（以列為單位） |
結果： 成功時為 null。
disposeTerminal
處置終端機，若其行程仍在執行則予以終止。
伺服器分派 root/terminalsChanged 以從根終端機清單中移除該終端機。
| 屬性 | 值 |
|---|---|
| 方向 | 用戶端 → 伺服器 |
| 類型 | 請求 |
參數：
無參數。
結果： 成功時為 null。