AI 可操作介面契約
@astromer/core/contracts 提供純 TypeScript 的元件、狀態與操作契約,可以在 Node 或產品宿主中獨立使用,不必載入 Astro 元件或瀏覽器 Runtime。
這一版實作契約、請求建立及驗證。產品宿主提供真實選取狀態、授權、共用操作處理器、持久保存與復原;通過驗證不代表操作已執行。
從既有 Registry 取得元件定義
Section titled “從既有 Registry 取得元件定義”import { createComponentDefinitions, uiContractVersion, validateUIInstance,} from "@astromer/core/contracts";
const definitions = createComponentDefinitions();const hero = definitions.find((entry) => entry.componentRef.type === "Hero");if (!hero) throw new Error("Hero is not registered");
const checked = validateUIInstance({ contractVersion: uiContractVersion, instanceId: "hero-preview", componentRef: hero.componentRef, props: { title: "付款確認", align: "center" },}, definitions);ComponentDefinition.propsSchema、slots 與穩定度由既有 Registry 衍生。每次取得的資料都是獨立副本,修改它不會改動 Registry。此處 componentRef.version 採用 registrySchemaVersion,表示定義版本;它不是 npm 套件版本或視覺重現的 renderer 版本。
驗證使用 Astromer 現有的 AstromerPropSchema 格式,並非通用 JSON Schema 實作。物件有宣告 fields 時會檢查必要欄位與未知欄位;沒有 fields 的既有 opaque object 仍只保證 JSON 物件型別。原有契約沒有宣告的長度或業務限制,應由產品處理器補驗。
Select 尚未列入既有 Registry,Form 也尚未成為 Registry 元件;這個版本不為它們產生虛構定義。Input、Button 與其他既有項目沿用原本契約。
人與 Agent 共用明確的更新請求
Section titled “人與 Agent 共用明確的更新請求”宿主建立 RuntimeSnapshot,內容包含文件與 revision、選取 IDs、宿主發出的 scope、可寫欄位及合法值。null revision 表示尚無持久版本,不能省略 revision 欄位來跳過檢查。
import { type ActionDefinition, type RuntimeSnapshot, createNodeUpdateRequest, validateNodeUpdateRequest,} from "@astromer/core/contracts";
export function prepareProperties( snapshot: RuntimeSnapshot, definition: ActionDefinition,) { return createNodeUpdateRequest({ snapshot, definition, requestId: "attempt-001", idempotencyKey: "edit-intent-001", values: { title: "付款確認", align: "center" }, });}
export function checkAgentRequest( input: unknown, snapshot: RuntimeSnapshot, definition: ActionDefinition,) { return validateNodeUpdateRequest(input, definition, snapshot);}範例使用已存在的 Hero.title 與 Hero.align,沒有另加文件欄位。多選時只傳明確修改的 patch;未修改的 mixed/unset 欄位不會被當成空值送出。建立請求時會複製目標 IDs、revision 與 patch,之後改變選取或草稿不會改寫已建立的請求。
驗證結果為 { valid: true, value } 或 { valid: false, issues }。issue 包含穩定代碼、JSON Pointer 路徑、原因、相關節點/欄位、必要限制與 recovery。驗證不改寫輸入、不默認套用 default,也不執行任何寫入。
| 入口 | 驗證內容 |
|---|---|
validateUIInstance |
元件及契約版本、props、必要 slots、子元件唯一 ID、帶版本的 action 參照格式 |
validatePropValue |
依既有 Registry schema 驗證 JSON 值 |
validateActionRequest |
新操作的請求格式、動作版本、可用性、文件、revision 與宣告範圍 |
validateNodeUpdateRequest |
另檢查實際變更 IDs、欄位、可寫性與合法值,整份請求通過才回傳 value |
validateActionResult |
狀態對應的結果格式;可選擇套用動作的 output schema |
validatePresentationReceipt |
呈現狀態、請求/呈現 revision 與視覺檢查的區別 |
正式提交與畫面呈現
Section titled “正式提交與畫面呈現”六類共用契約為 ComponentDefinition、UIInstance、RuntimeSnapshot、ActionDefinition、ActionRequest、ActionResult;另外以 PresentationReceipt 回報畫面。
ActionResult 的 committed 必須攜帶正式 revision、受影響 IDs 與 persistence.status: "durable"。pending/unknown 不得附帶假定已提交的 revision;unknown 以原 requestId 與 idempotencyKey 追蹤,尚未取得服務端 operationId 時可以省略它。rejected/failed 必須提供結構化 error。格式驗證只檢查回報是否一致,真實持久性仍由宿主保證。
PresentationReceipt.status: "rendered" 必須對應請求的 revision。rendered 搭配 visualCheck: "not_run" 是合法的:已更新畫面不等於已通過視覺檢查。畫面失敗不應把已提交操作改成 failed 或重新寫入。
宿主接入順序
Section titled “宿主接入順序”- 從可信工作階段取得操作者與文件權限,解析宿主持有的 scope;不要採信模型回傳的 snapshot 作為授權。
- 先查原 idempotency key。已知操作沿用其結果;這個模組的 preflight 用於新操作,不能在重播前套用新的 revision 檢查。
- 驗證新請求,將人工表單與 Agent 入口接到同一個領域處理器。
- 在權威提交點重新檢查範圍、revision 與去重唯一性,並一致保存文件、版本與操作結果。
- 正式提交後分別回報
ActionResult與畫面 receipt;Undo/Redo/恢復沿用產品的版本機制。
這個模組不自行新增文件模型、資料庫、Agent 模型呼叫或 MCP/WebMCP adapter。