註解通道

ahp-session:/<uuid>/annotations 通道的參考資料 — 工作階段回合內錨定於檔案範圍的每個工作階段註解。用戶端（以及代理主機）透過分派用戶端可分派的 annotations/* 狀態操作來變動註解，預寫入 reducer 會在兩端對等地套用這些操作。

JSON Schema: state.schema.json

狀態類型

AnnotationsSummary

註解通道的輕量級每工作階段摘要，公開於 {@link SessionSummary.annotations}，讓徽章 UI 無需訂閱通道本身 即可呈現註解／條目計數。

欄位	類型	說明
resource	URI	擁有工作階段的可訂閱註解通道 URI （通常為 ahp-session:/<uuid>/annotations）。即使可從工作階段 URI 衍生而來也明確公開，讓徽章 UI 不需要知道衍生規則。
annotationCount	number	通道中 {@link Annotation} 條目的總數。
entryCount	number	跨所有註解的 {@link AnnotationEntry} 條目總數。

AnnotationsState

工作階段註解通道的完整狀態，於用戶端訂閱 ahp-session:/<uuid>/annotations URI 時回傳。

欄位	類型	說明
annotations	Annotation[]	此通道中的註解，以 {@link Annotation.id} 為鍵。

Annotation

錨定於特定回合所產生之特定檔案的對話， 可選擇縮小至該檔案內的某個範圍。

{@link turnId} 將註解錨定至該回合所產生的檔案版本， 如此一來，後續重寫同一檔案的回合不會悄悄使註解的錨點 失效——用戶端可根據該回合的變更集解析 {@link resource} 與 {@link range}。省略 {@link range} 時，註解錨定至整個檔案。

每個註解 MUST 至少包含一個 {@link AnnotationEntry}。因此， 建立註解的 {@link AnnotationsSetAction} 會攜帶其必要的第一個 條目，而移除最後一個剩餘條目會透過 {@link AnnotationsRemovedAction} 摺疊該註解，而非留下空的註解。

欄位	類型	必要	說明
id	string	是	註解通道內的穩定識別碼。由分派建立它的 {@link AnnotationsSetAction} 的用戶端指派。
turnId	string	是	產生此註解所錨定之檔案版本的回合。 與擁有工作階段上的 {@link Turn.id} 相符。
resource	URI	是	註解所錨定的檔案。
range	TextRange	否	註解所錨定 {@link resource} 內的範圍。省略時， 註解錨定至整個檔案。
resolved	boolean	是	註解是否已解決。新建的註解一律為未解決 （false）；用戶端透過分派攜帶更新旗標的 {@link AnnotationsUpdatedAction} 將註解標記為已解決（或重新開啟）， 或在替換整個註解時使用 {@link AnnotationsSetAction}。
entries	AnnotationEntry[]	是	此註解中的條目，依分派順序排列（最舊者在前）。 MUST 至少包含一個條目。
_meta	Record<string, unknown>	否	由產生者定義的不透明中繼資料，公開供工具使用， 但不由協定解讀。

AnnotationEntry

{@link Annotation} 內的單一條目。

欄位	類型	必要	說明
id	string	是	所屬註解內的穩定識別碼。由分派引入該條目之 {@link AnnotationsEntrySetAction}（或所屬 {@link AnnotationsSetAction}）的用戶端指派。
text	StringOrMarkdown	是	條目主體。裸 string 會以純文字呈現；傳入 { markdown: "…" } 以選擇 Markdown 呈現。詳見 {@link StringOrMarkdown}。
_meta	Record<string, unknown>	否	由產生者定義的不透明中繼資料，公開供工具使用， 但不由協定解讀。

操作

變動 AnnotationsState。透過外層的 ActionEnvelope.channel 限定於某個註解通道 URI。

JSON Schema: actions.schema.json

annotations/set

在註解通道中 upsert 一個 {@link Annotation}——新增註解， 或替換由 {@link Annotation.id} 識別的現有註解。

由用戶端分派以建立註解（連同其必要的第一個條目）， 或重新錨定／解決現有註解；分派的用戶端指派 {@link Annotation.id} 與任何新條目的 id。替換時，完整的註解 有效負載（包含其 {@link Annotation.entries | entries} 清單）會被 取代；產生者 SHOULD 偏好使用 {@link AnnotationsEntrySetAction} 進行每條目編輯，並使用 {@link AnnotationsUpdatedAction} 來 解決／重新錨定現有註解，以保持網路傳輸更新精簡。

欄位	類型	說明
type	ActionType.AnnotationsSet
annotation	Annotation	新增或替換用的註解。MUST 至少包含一個條目。

annotations/updated

部分更新現有 {@link Annotation} 的自身屬性—— {@link AnnotationsSetAction} 的窄替代方案，適用於在不重新傳送 {@link Annotation.entries | entries} 的情況下解決／重新開啟 或重新錨定註解的常見情境。

依其 {@link annotationId} 鎖定單一註解。僅寫入操作上出現的 欄位；省略的欄位會讓對應的 {@link Annotation} 屬性保持不變。 註解的 {@link Annotation.entries | entries}、 {@link Annotation.id | id} 與 {@link Annotation._meta | _meta} 絕不會被觸及——請分派 {@link AnnotationsSetAction} 來取代它們、 清除 {@link range}（重新錨定至整個檔案），或使用 {@link AnnotationsEntrySetAction}／ {@link AnnotationsEntryRemovedAction} 編輯個別條目。

若 {@link annotationId} 不符任何現有註解，則此操作為 no-op。

欄位	類型	必要	說明
type	ActionType.AnnotationsUpdated	是
annotationId	string	是	要更新之註解的 {@link Annotation.id}。
turnId	string	否	將註解重新錨定至此回合產生的檔案版本。 與擁有工作階段上的 {@link Turn.id} 相符。省略以保持 現有的 {@link Annotation.turnId} 不變。
resource	URI	否	將註解重新錨定至此檔案。省略以保持現有的 {@link Annotation.resource} 不變。
range	TextRange	否	將註解縮小至 {@link resource} 內的此範圍。省略以保持 現有的 {@link Annotation.range} 不變；此操作無法清除現有 範圍——請分派 {@link AnnotationsSetAction} 重新錨定至 整個檔案。
resolved	boolean	否	將註解標記為已解決（true）或重新開啟（false）。省略以 保持現有的 {@link Annotation.resolved} 狀態不變。

annotations/removed

依 id 從通道移除 {@link Annotation}。

分派以刪除整個註解及其包含的每個條目。因為協定禁止空註解， 想要移除最後一個剩餘條目的用戶端會分派此操作——摺疊該 註解——而非 {@link AnnotationsEntryRemovedAction}。

欄位	類型	說明
type	ActionType.AnnotationsRemoved
annotationId	string	要移除之註解的 {@link Annotation.id}。

annotations/entrySet

在現有註解中 upsert 一個 {@link AnnotationEntry}——新增條目， 或替換由 {@link AnnotationEntry.id} 識別的條目。分派的用戶端 指派新條目的 {@link AnnotationEntry.id}。若 {@link annotationId} 不符任何現有註解，則此操作為 no-op。

欄位	類型	說明
type	ActionType.AnnotationsEntrySet
annotationId	string	該條目所屬註解的 {@link Annotation.id}。
entry	AnnotationEntry	新增或替換用的條目。

annotations/entryRemoved

從註解移除單一 {@link AnnotationEntry} 而不摺疊註解本身。 用於剩餘多個條目時——要移除最後一個條目，用戶端應改分派 {@link AnnotationsRemovedAction}，因為協定禁止空註解。

若 {@link annotationId} 或 {@link entryId} 不符目前狀態， 則此操作為 no-op。

欄位	類型	說明
type	ActionType.AnnotationsEntryRemoved
annotationId	string	該條目所屬註解的 {@link Annotation.id}。
entryId	string	要移除的 {@link AnnotationEntry.id}。