變更集通道
ahp-changeset:/<id> 通道的參考資料 — 伺服器端持有的檔案變更檢視（未提交、工作階段範圍、每回合等），用戶端可訂閱並對其叫用操作。模型概觀請參閱變更集指南。
JSON Schema: state.schema.json
狀態類型
Changeset
目錄項目，描述伺服器可為工作階段產生的單一變更集。
目錄項目刻意保持輕量 — 僅足以在未訂閱的情況下呈現晶片或清單列。 完整的每個變更集詳情（{@link ChangesetState}）位於可透過展開 {@link uriTemplate} 取得的可訂閱 URI 上。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
label | string | 是 | 人類可讀的標籤，例如 "Uncommitted Changes"。 |
uriTemplate | string | 是 | RFC 6570 URI 樣板。用戶端使用標準的 {name} 語法直接從樣板中 解析變數 — 變數不在此重新宣告。本協定僅定義以下樣板形式；任何其他變數名稱 MUST 被用戶端忽略 （沒有協定定義的方式可取得未知變數的值）： | 樣板中的變數 | 意義 | | ------------------------------------------- | ------------------------------------------------------------------------------------ | | (無) | 靜態的、整個工作階段範圍的變更集。樣板本身即為可訂閱的 URI。 | | {turnId} | 每回合切片。以工作階段中的 Turn.id 展開。 | | {originalTurnId} 與 {modifiedTurnId} | 兩個回合間的差異。兩個變數 MUST 同時存在。 |未來的協定版本 MAY 新增新的已知變數。 |
description | string | 否 | 選用的較長描述。 |
changeKind | string | 是 | 建議性提示，描述此變更集的種類，讓用戶端可以在不解析 {@link uriTemplate} 的情況下分組、排序或呈現適當的圖示。已知的值包含： - 'session'：靜態的、整個工作階段範圍的變更集，涵蓋代理程式 在此工作階段中產生的所有變更。 - 'branch'：相對於基準分支的變更（例如將功能分支與 main 做 差異比對）。 - 'uncommitted'：工作區當前未提交的變更。 - 'turn'：由單一回合產生的變更。通常與 {@link uriTemplate} 中的 {turnId} 變數搭配。 - 'compare-turns'：兩個回合間的差異。通常與 {@link uriTemplate} 中的 {originalTurnId} 與 {modifiedTurnId} 變數搭配。實作 MAY 提供額外的值；當遇到未知值時，用戶端 SHOULD 退回到 合理的預設值。 |
capabilities | ChangesetCapabilities | 否 | 此變更集的選用能力宣告。不存在（或為空物件）表示此變更集未公告任何 選用能力。 由於目錄項目會預先隨 {@link ChangesetState | 工作階段的變更集清單} 傳遞，用戶端可在未先訂閱變更集 URI 的情況下決定是否呈現受能力閘控的 UI（例如審核勾選框）。這反映了 ClientCapabilities 的 存在旗標慣例。 |
ChangesetCapabilities
變更集在其目錄 {@link Changeset} 項目上公告的選用能力。
每個欄位都是一個存在旗標：空物件 {} 表示「支援」， 不存在表示「不支援」。個別能力上的子欄位保留供未來的個別能力選項使用。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
review | Record<string, never> | 否 | 此變更集支援每檔案的 審核 工作流程。宣告後，用戶端 MAY 對每個檔案 呈現 GitHub 風格的 "Viewed" 切換器，並分派 {@link ChangesetFilesReviewChangedAction | changeset/filesReviewChanged} 來設定每個檔案的 {@link ChangesetFile.reviewed} 旗標。未處理此項的 用戶端 MUST 將此變更集視為不可審核。 |
ChangesetStatus
{@link ChangesetState} 的運算生命週期。
| 成員 | 值 | 說明 |
|---|---|---|
Computing | 'computing' | 伺服器仍在運算此變更集的內容。 |
Ready | 'ready' | 此變更集已完整運算且為最新狀態。 |
Error | 'error' | 運算失敗。原因由 {@link ChangesetState.error} 描述。 |
ChangesetState
單一變更集的完整狀態，於用戶端訂閱展開後的變更集 URI 時回傳。
用戶端已知其訂閱的 URI，因此此狀態不會冗餘地攜帶它（或目錄的 id、label 等）。彙總計數（additions、deletions、files） 也同樣省略：用戶端可輕易地從 files[].edit.diff 計算它們。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
status | ChangesetStatus | 是 | 運算生命週期。 |
error | ErrorInfo | 否 | 若且唯若 status === ChangesetStatus.Error 時存在。 |
files | ChangesetFile[] | 是 | 此變更集中的檔案，以 {@link ChangesetFile.id} 為鍵。 |
operations | ChangesetOperation[] | 否 | 用戶端可對此變更集叫用的操作。當沒有可用操作時省略。 |
ChangesetFile
{@link ChangesetState} 內的單一檔案項目。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
id | string | 是 | 變更集內的穩定識別碼。通常為 after.uri （刪除時則為 before.uri）。 |
edit | FileEdit | 是 | 重用既有的 {@link FileEdit} 形狀。用戶端從中推導出新增行、刪除行， 以及重新命名/建立/刪除的語意。 |
reviewed | boolean | 否 | 審核者是否已將此檔案標記為已審核（GitHub 風格的 "Viewed" 勾選框）。 不存在等同於 false — 用戶端 MUST 將缺少的值視為尚未審核。需要變更集公告 {@link ChangesetCapabilities.review}。用戶端透過分派 {@link ChangesetFilesReviewChangedAction | changeset/filesReviewChanged} 來切換它；伺服器 MAY 也自行產生它（例如代理程式自我審核其自身的 輸出）。協定中沒有內容版本，因此當檔案內容在穩定識別碼下變更時，審核 不會 自動重設。伺服器是變更內容的權威者，會明確地重設審核 — 作法是 重新發出檔案（透過 {@link ChangesetFileSetAction} 或 {@link ChangesetContentChangedAction}）而不帶 reviewed: true，或是 分派 changeset/filesReviewChanged 並帶 reviewed: false。 |
_meta | Record<string, unknown> | 否 | 伺服器定義的不透明中繼資料，會呈現給操作與工具， 但不會由協定詮釋。 |
ChangesetOperationStatus
{@link ChangesetOperation} 的執行生命週期。
操作是透過 invokeChangesetOperation 命令式地叫用，但其進度與結果 會反映回變更集狀態，讓每個訂閱者都觀察到一致的檢視（例如 "Create Pull Request" 按鈕上的旋轉圖示，或失敗 "revert" 後的內嵌錯誤）。
| 成員 | 值 | 說明 |
|---|---|---|
Idle | 'idle' | 此操作已就緒可被叫用。當 {@link ChangesetOperation.status} 省略時， 這是預設值。 |
Running | 'running' | 此操作的叫用目前正在進行中。 |
Error | 'error' | 最近一次叫用失敗。原因由 {@link ChangesetOperation.error} 描述。 |
Disabled | 'disabled' | 此操作目前已停用且無法被叫用。 |
ChangesetOperationScope
{@link ChangesetOperation} 可被叫用的位置。
| 成員 | 值 | 說明 |
|---|---|---|
Changeset | 'changeset' | 套用至整個變更集。 |
Resource | 'resource' | 套用至變更集內的單一檔案。 |
Range | 'range' | 套用至單一檔案內的行範圍。 |
ChangesetOperation
伺服器宣告、用戶端可對變更集、檔案或範圍執行的可叫用動詞 — "stage"、"revert"、"create-pr" 等等。
刻意使用「操作」一詞，以避免與協定層級中變動狀態的 操作 衝突。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
id | string | 是 | 穩定識別碼，在此變更集內唯一。 |
label | string | 是 | 人類可讀的按鈕/選單標籤。 |
description | string | 否 | 選用的較長描述，於滑鼠停留或工具提示時顯示。 |
scopes | ChangesetOperationScope[] | 是 | 此操作可被叫用的位置。 |
confirmation | StringOrMarkdown | 否 | 叫用前顯示的選用確認提示。存在時，用戶端 MUST 將此訊息顯示給 使用者（通常在確認對話框中），且僅在使用者接受後才叫用此操作。 此欄位的存在也表示此操作具破壞性 — 用戶端 SHOULD 據此為確認 按鈕套用樣式（例如使用警告色彩）。 |
icon | string | 否 | 選用的通用圖示提示，例如 "check"、"trash"。 |
group | string | 否 | 選用的群組識別碼，用於將相關操作分組在一起。 |
status | ChangesetOperationStatus | 是 | 目前的執行狀態。當叫用正在進行時，伺服器會設定為 {@link ChangesetOperationStatus.Running | Running}；當最近一次叫用 失敗時設為 {@link ChangesetOperationStatus.Error | Error}；其餘情況 設為 {@link ChangesetOperationStatus.Idle | Idle}。 用戶端 SHOULD 在 UI 中反映此狀態 — 例如在 Running 時停用控制項 或顯示旋轉圖示，並在 Error 時呈現 {@link error}。 |
error | ErrorInfo | 否 | 失敗原因。若且唯若 status === ChangesetOperationStatus.Error 時存在；否則省略。 |
操作
變動 ChangesetState。透過外層的 ActionEnvelope.channel 限定於某個變更集 URI。
JSON Schema: actions.schema.json
changeset/statusChanged
此變更集的 {@link ChangesetState.status} 已轉換（例如 computing → ready）。每當轉換為 {@link ChangesetStatus.Error | Error} 時，錯誤有效負載會與 status 一併設定。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | ActionType.ChangesetStatusChanged | 是 | |
status | ChangesetStatus | 是 | 新的運算生命週期狀態。 |
error | ErrorInfo | 否 | 當 status === ChangesetStatus.Error 時的原因；否則省略。 |
changeset/fileSet
在變更集中插入或更新 {@link ChangesetFile} — 新增新項目，或 取代由 {@link ChangesetFile.id} 識別的既有項目。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.ChangesetFileSet | |
file | ChangesetFile | 新增或用來取代的檔案項目。 |
changeset/fileRemoved
依識別碼從變更集中移除 {@link ChangesetFile}。
通常於檔案被還原、暫存移出，或因其他原因不再屬於範圍時分派 （例如重新命名的檔案被新項目取代）。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.ChangesetFileRemoved | |
fileId | string | 要移除之檔案的 {@link ChangesetFile.id}。 |
changeset/filesReviewChanged
為一個或多個檔案設定 {@link ChangesetFile.reviewed} 旗標 — GitHub 風格的 "Viewed" 切換器，於單一批次中套用。
依檔案的 {@link ChangesetFile.id} 為目標。{@link files} 中與變更集內 目前存在之檔案不符的識別碼會被忽略；若無相符者，此操作為 no-op。 僅每個相符檔案的 {@link ChangesetFile.reviewed} 欄位會受影響；檔案的 {@link ChangesetFile.edit | edit} 與 {@link ChangesetFile._meta | _meta} 則保持不變。
僅對公告 {@link ChangesetCapabilities.review} 的變更集有意義。與其他 所有 changeset/* 操作不同，此操作是 用戶端可分派 的：審核者直接 切換審核狀態，透過預寫入 reducer 樂觀地套用它，並讓伺服器在正常的 action 信封串流上回應它。伺服器 MAY 也自行產生它（例如代理程式將 其自身的輸出標記為已審核）。
協定層級沒有內容版本，因此當檔案內容在穩定識別碼下變更時，審核不會 自動重設。伺服器是變更內容的權威者，會明確地重設審核 — 作法是 重新發出檔案而不帶 reviewed: true，或是分派此操作並帶 reviewed: false。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.ChangesetFilesReviewChanged | |
files | string[] | 審核狀態已變更之檔案的 {@link ChangesetFile.id | ids}。 |
reviewed | boolean | 套用至每個列出檔案的新審核狀態：已審核時為 true，清除時為 false。 |
changeset/contentChanged
變更集的完整內容已變更。完整取代語意：files 取代先前的檔案清單， 而 operations 存在時取代先前的操作清單。
產生者 SHOULD 將此操作用於初始快照與大量重新整理；至於增量更新， 請使用 {@link ChangesetFileSetAction}、{@link ChangesetFileRemovedAction} 與 {@link ChangesetOperationsChangedAction}。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | ActionType.ChangesetContentChanged | 是 | |
files | ChangesetFile[] | 是 | 完整取代的檔案清單。 |
operations | ChangesetOperation[] | 否 | 完整取代的操作清單。當操作未變更時省略。 |
error | ErrorInfo | 否 | 錯誤資訊（若變更集內容變更失敗）。 |
changeset/operationsChanged
此變更集上可用操作的集合已變更。完整取代語意：operations 取代先前 的清單（或當 operations 為 undefined 時將其完全移除）。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.ChangesetOperationsChanged | |
operations | ChangesetOperation[] | undefined | 更新後的操作清單。傳入 undefined 以清除所有操作。 |
changeset/operationStatusChanged
單一操作的 {@link ChangesetOperation.status} 已轉換（例如 idle → running → idle，或 running → error）。每當轉換為 {@link ChangesetOperationStatus.Error | Error} 時，錯誤有效負載會與 status 一併設定，並在任何其他轉換時清除。
依其 {@link ChangesetOperation.id} 為單一操作的目標。若變更集中目前 沒有該識別碼的操作，此操作為 no-op。請使用 {@link ChangesetOperationsChangedAction} 來新增、移除或以其他方式 取代操作清單本身。
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
type | ActionType.ChangesetOperationStatusChanged | 是 | |
operationId | string | 是 | 狀態已變更之操作的 {@link ChangesetOperation.id}。 |
status | ChangesetOperationStatus | 是 | 新的執行狀態。 |
error | ErrorInfo | 否 | 當 status === ChangesetOperationStatus.Error 時的原因；否則省略。 |
changeset/cleared
從變更集中捨棄所有檔案。
有兩種情況會用到此操作：
- 底層來源已變動（分支切換、分叉點失效等等），而伺服器正從頭重新 運算 — 後續的 {@link ChangesetFileSetAction} 項目會重新填入它。
- 擁有它的工作階段已結束，而 URI 正變為不可訂閱 — 伺服器會在 分派此操作後不久取消所有用戶端的訂閱。
用戶端 SHOULD 在收到時釋放任何參照，且 SHOULD NOT 僅從此操作就區分 這兩種情況 — 請改為對「即將消失」的情況反應對應的工作階段層級生命 週期信號（例如 root/sessionRemoved）。
| 欄位 | 類型 | 說明 |
|---|---|---|
type | ActionType.ChangesetCleared |
指令
JSON Schema: commands.schema.json
invokeChangesetOperation
對變更集、單一檔案或行範圍叫用伺服器定義的 {@link ChangesetOperation}。
伺服器會驗證 operationId 存在於變更集目前的 operations 清單中， 且請求的 target.kind 包含在操作的 scopes 內。無效的組合會產生 JSON-RPC 錯誤。
叫用所產生的狀態變更會透過相關變更集 URI 上正常的 changeset/* 操作 串流流回。除非伺服器透過未來的能力明確加入，否則用戶端 SHOULD NOT 為叫用合成在地的樂觀變更。
| 屬性 | 值 |
|---|---|
| 方向 | 用戶端 → 伺服器 |
| 類型 | 請求 |
參數：
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
channel | URI | 是 | 展開後的變更集 URI。 |
operationId | string | 是 | 與變更集 operations 清單中的 {@link ChangesetOperation.id} 相符。 |
target | ChangesetOperationTarget | 否 | 操作的目標。若且唯若所選範圍為 'resource' 或 'range' 時為必要。 變更集範圍的操作請省略。 |
結果：
| 欄位 | 類型 | 必要 | 說明 |
|---|---|---|---|
message | StringOrMarkdown | 否 | 描述結果的選用人類可讀訊息。 |
followUp | ChangesetOperationFollowUp | 否 | 選用的後續：要開啟的 URI（例如 PR）、內容參照等等。 |