@skopon-cool/form-sdk 0.3.2 → 0.4.1

package/dist/runtime/buildFormRuntimeSnapshot.d.ts

@@ -0,0 +1,16 @@
+import type { FormBlock, FormBlockOption } from '../types/index';
+import type { FormRuntimeDataPayload } from './types';
+export type LiveOptionsMap = ReadonlyMap<string, FormBlockOption[]>;
+export interface BuildFormRuntimeSnapshotInput {
+    title?: string;
+    description?: string;
+    blocks: FormBlock[];
+    values: Record<string, unknown>;
+    liveOptions?: LiveOptionsMap;
+    formChange?: string[];
+}
+/**
+ * 构建 form_runtime_data 快照：form_schema（block 格式）+ 扁平 form_values + form_change。
+ */
+export declare function buildFormRuntimeSnapshot(input: BuildFormRuntimeSnapshotInput): FormRuntimeDataPayload;
+//# sourceMappingURL=buildFormRuntimeSnapshot.d.ts.map

package/dist/runtime/buildFormRuntimeSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildFormRuntimeSnapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/buildFormRuntimeSnapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAErD,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;AA0BnE,MAAM,WAAW,6BAA6B;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,6BAA6B,GACnC,sBAAsB,CAiBxB"}

package/dist/runtime/formLiveOptionsContext.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from 'react';
+import type { FormBlockOption } from '../types/index';
+export type PublishLiveOptionsFn = (fieldName: string, options: FormBlockOption[]) => void;
+export interface FormLiveOptionsContextValue {
+    publishLiveOptions: PublishLiveOptionsFn;
+    /** 当前 live options 的不可变快照（供读取）。 */
+    liveOptions: ReadonlyMap<string, FormBlockOption[]>;
+    /** 最近一次签名变化导致的变更字段（debounce 归集前由 Provider 消费后清空）。 */
+    pendingChangeFields: readonly string[];
+    /** 版本号：live options 有实质变更时递增，用于触发上报 effect。 */
+    version: number;
+    clearPendingChangeFields: () => void;
+}
+export interface FormLiveOptionsProviderProps {
+    children: ReactNode;
+}
+export declare function FormLiveOptionsProvider({ children }: FormLiveOptionsProviderProps): import("react").JSX.Element;
+/** 无 Provider 时 no-op（编辑器预览不受影响）。 */
+export declare function useFormLiveOptions(): FormLiveOptionsContextValue;
+//# sourceMappingURL=formLiveOptionsContext.d.ts.map

package/dist/runtime/formLiveOptionsContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formLiveOptionsContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formLiveOptionsContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,MAAM,MAAM,oBAAoB,GAAG,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,EAAE,KACvB,IAAI,CAAA;AAET,MAAM,WAAW,2BAA2B;IAC1C,kBAAkB,EAAE,oBAAoB,CAAA;IACxC,mCAAmC;IACnC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;IACnD,qDAAqD;IACrD,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAA;IACf,wBAAwB,EAAE,MAAM,IAAI,CAAA;CACrC;AAsBD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,EAAE,4BAA4B,+BA6DjF;AAED,qCAAqC;AACrC,wBAAgB,kBAAkB,IAAI,2BAA2B,CAEhE"}

package/dist/runtime/formRuntimeConnection.d.ts

@@ -0,0 +1,35 @@
+import type { FormAutoControlEventData, FormRuntimeEnvelope, FormRuntimeOutboundType } from './types';
+export type FormAutoControlHandler = (data: FormAutoControlEventData, envelope: FormRuntimeEnvelope<FormAutoControlEventData>) => void;
+/** 测试用：清空所有单例连接。 */
+export declare function resetFormRuntimeConnectionsForTests(): void;
+export declare function acquireFormRuntimeConnection(url: string): FormRuntimeConnection;
+export declare class FormRuntimeConnection {
+    private readonly url;
+    private ws;
+    private refCount;
+    private connectRequested;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private releaseTimer;
+    private sendQueue;
+    private readonly handlers;
+    constructor(url: string);
+    acquire(): void;
+    release(): void;
+    /** 强制关闭（测试用），跳过宽限期。 */
+    forceClose(): void;
+    subscribe(askUserMessageId: string, handler: FormAutoControlHandler): () => void;
+    /** 懒建连：首个会话 connect() 时才真正打开 socket。 */
+    connect(): void;
+    send(askUserMessageId: string, type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
+    private openSocket;
+    private teardown;
+    private disposeSocket;
+    private enqueue;
+    private flushQueue;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private clearReleaseTimer;
+    private handleMessage;
+}
+//# sourceMappingURL=formRuntimeConnection.d.ts.map

package/dist/runtime/formRuntimeConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formRuntimeConnection.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeConnection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,SAAS,CAAA;AAMhB,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,KACpD,IAAI,CAAA;AAIT,oBAAoB;AACpB,wBAAgB,mCAAmC,IAAI,IAAI,CAK1D;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAS/E;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,gBAAgB,CAAQ;IAChC,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,YAAY,CAA6C;IACjE,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;gBAE9D,GAAG,EAAE,MAAM;IAIvB,OAAO,IAAI,IAAI;IAKf,OAAO,IAAI,IAAI;IAcf,uBAAuB;IACvB,UAAU,IAAI,IAAI;IAQlB,SAAS,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAiBhF,wCAAwC;IACxC,OAAO,IAAI,IAAI;IASf,IAAI,CACF,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,OAAO,CAAC,UAAU;IA2BlB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,aAAa;CAyBtB"}

package/dist/runtime/formRuntimeContext.d.ts

@@ -1,9 +1,9 @@
 import { type ReactNode } from 'react';
 import type { FormRuntimeWsClient } from './formRuntimeWs';
-import type { FormRuntimeEventData } from './types';
+import type { FormRuntimeDataPayload, FormRuntimeEventData } from './types';
 export interface FormRuntimeContextValue {
     reportEvent: (event: FormRuntimeEventData) => void;
-    reportData: (values: Record<string, unknown>) => void;
+    reportData: (payload: FormRuntimeDataPayload) => void;
     /**
      * 在自动控上下文中执行 fn。若 fn 返回 Promise，depth 保持到 settle，
      * 使异步 submit 内的 reportEvent 仍为 form_auto_control_bac_event。

package/dist/runtime/formRuntimeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formRuntimeContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEnD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACrD;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AA6BD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAClC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,+BAkE1B;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,uBAAuB,CAExD"}
+{"version":3,"file":"formRuntimeContext.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE3E,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,UAAU,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAA;IACrD;;;OAGG;IACH,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AA+BD,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAClC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,+BAkE1B;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,uBAAuB,CAExD"}

package/dist/runtime/formRuntimeWs.d.ts

@@ -1,29 +1,22 @@
-import type { FormAutoControlEventData, FormRuntimeEnvelope, FormRuntimeOutboundType } from './types';
-export type FormAutoControlHandler = (data: FormAutoControlEventData, envelope: FormRuntimeEnvelope<FormAutoControlEventData>) => void;
+import { type FormAutoControlHandler } from './formRuntimeConnection';
+import type { FormRuntimeOutboundType } from './types';
+export type { FormAutoControlHandler } from './formRuntimeConnection';
 export interface FormRuntimeWsClientOptions {
     url: string;
     askUserMessageId: string;
     onAutoControl?: FormAutoControlHandler;
 }
+/**
+ * Per-card runtime 会话：绑定 ask_user_message_id，代理到按 URL 的全局单例连接。
+ */
 export declare class FormRuntimeWsClient {
-    private readonly url;
     private readonly askUserMessageId;
-    private readonly onAutoControl?;
-    private ws;
+    private readonly connection;
+    private readonly unsubscribe;
     private closed;
-    private reconnectAttempt;
-    private reconnectTimer;
-    private sendQueue;
     constructor(options: FormRuntimeWsClientOptions);
     connect(): void;
     send(type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
     close(): void;
-    /** 关闭当前 socket 且不触发重连（清掉 onclose），建新连或主动 close 时用。 */
-    private disposeSocket;
-    private enqueue;
-    private flushQueue;
-    private scheduleReconnect;
-    private clearReconnectTimer;
-    private handleMessage;
 }
 //# sourceMappingURL=formRuntimeWs.d.ts.map

package/dist/runtime/formRuntimeWs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formRuntimeWs.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeWs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,SAAS,CAAA;AAKhB,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,mBAAmB,CAAC,wBAAwB,CAAC,KACpD,IAAI,CAAA;AAET,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwB;IACvD,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,cAAc,CAA6C;IACnE,OAAO,CAAC,SAAS,CAAe;gBAEpB,OAAO,EAAE,0BAA0B;IAM/C,OAAO,IAAI,IAAI;IA2Bf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,KAAK,IAAI,IAAI;IAOb,sDAAsD;IACtD,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;CAgBtB"}
+{"version":3,"file":"formRuntimeWs.d.ts","sourceRoot":"","sources":["../../src/runtime/formRuntimeWs.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAE5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAErE,MAAM,WAAW,0BAA0B;IACzC,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAY;IACxC,OAAO,CAAC,MAAM,CAAQ;gBAEV,OAAO,EAAE,0BAA0B;IAS/C,OAAO,IAAI,IAAI;IAKf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAKP,KAAK,IAAI,IAAI;CAMd"}

package/dist/runtime/types.d.ts

@@ -17,4 +17,15 @@ export interface FormRuntimeEnvelope<T = Record<string, unknown>> {
     ask_user_message_id: string;
     data: T;
 }
+/** form_runtime_data 的 data 载荷（Init / Refresh / Submit）。 */
+export interface FormRuntimeDataPayload {
+    form_schema: {
+        title?: string;
+        description?: string;
+        blocks: unknown[];
+    };
+    form_values: Record<string, unknown>;
+    /** 本次被更新的字段名；Init/Submit 为空数组。 */
+    form_change: string[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/runtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAElF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,iBAAiB,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,uBAAuB,GAC/B,mBAAmB,GACnB,oBAAoB,GACpB,6BAA6B,CAAA;AAEjC,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,MAAM,CAAA;IAC3B,IAAI,EAAE,CAAC,CAAA;CACR"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAA;AAElF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,iBAAiB,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,iBAAiB,CAAA;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,uBAAuB,GAC/B,mBAAmB,GACnB,oBAAoB,GACpB,6BAA6B,CAAA;AAEjC,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,MAAM,CAAA;IAC3B,IAAI,EAAE,CAAC,CAAA;CACR;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE;QACX,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,MAAM,EAAE,OAAO,EAAE,CAAA;KAClB,CAAA;IACD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB"}

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Skopon form rendering SDK (A2UI + form_definition) with submit helpers",
   "type": "module",
   "sideEffects": [

package/src/catalog/skoponCaseSelect.tsx

@@ -5,6 +5,7 @@ import type { ComponentContext } from '@a2ui/web_core/v0_9'
 import { createBinderlessComponentImplementation } from '@a2ui/react/v0_9'
 import { z } from 'zod'
 import type { FormCaseFilter } from '../types/index'
+import { useFormLiveOptions } from '../runtime/formLiveOptionsContext'
 import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import { asStringArray, clampStringArraySelection, isCardSelectionDisabled, readOptionalSelectCount, toggleStringArraySelection, useSkoponBoundField } from './useSkoponBoundField'
 import { type CaseSearchItem, useCaseSearch } from './caseSearchContext'
@@ -110,6 +111,7 @@ function CaseCard({
 function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const caseSearch = useCaseSearch()
+  const { publishLiveOptions } = useFormLiveOptions()
   const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
     component: 'SkoponCaseSelect',
     changeAction: 'click',
@@ -167,6 +169,15 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
         setTotal(result.total)
         setPage(result.page)
         setPageSize(result.pageSize)
+        if (fieldName) {
+          publishLiveOptions(
+            fieldName,
+            result.list.map((item) => ({
+              value: item.caseUniqueId,
+              label: item.name || item.caseUniqueId,
+            })),
+          )
+        }
       } catch (err) {
         if (seq !== requestSeqRef.current) return
         setItems([])
@@ -176,7 +187,7 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
         if (seq === requestSeqRef.current) setLoading(false)
       }
     },
-    [caseSearch, filterSig],
+    [caseSearch, filterSig, fieldName, publishLiveOptions],
   )
 
   useEffect(() => {

package/src/catalog/skoponResumeSelect.tsx

@@ -5,6 +5,7 @@ import type { ComponentContext } from '@a2ui/web_core/v0_9'
 import { createBinderlessComponentImplementation } from '@a2ui/react/v0_9'
 import { z } from 'zod'
 import type { FormResumeFilter } from '../types/index'
+import { useFormLiveOptions } from '../runtime/formLiveOptionsContext'
 import { useA2uiPreviewMode } from './a2uiPreviewContext'
 import { asStringArray, clampStringArraySelection, isCardSelectionDisabled, readOptionalSelectCount, toggleStringArraySelection, useSkoponBoundField } from './useSkoponBoundField'
 import {
@@ -163,6 +164,7 @@ function ResumeCard({
 function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const resumeSearch = useResumeSearch()
+  const { publishLiveOptions } = useFormLiveOptions()
   const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
     component: 'SkoponResumeSelect',
     changeAction: 'click',
@@ -213,6 +215,15 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
         setTotal(result.total)
         setPage(result.page)
         setPageSize(result.pageSize)
+        if (fieldName) {
+          publishLiveOptions(
+            fieldName,
+            result.list.map((item) => ({
+              value: item.resumeUniqueId,
+              label: item.name || item.resumeUniqueId,
+            })),
+          )
+        }
       } catch (err) {
         if (seq !== requestSeqRef.current) return
         setItems([])
@@ -222,7 +233,7 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
         if (seq === requestSeqRef.current) setLoading(false)
       }
     },
-    [resumeSearch, filterSig],
+    [resumeSearch, filterSig, fieldName, publishLiveOptions],
   )
 
   useEffect(() => {

package/src/components/AskUserFormCard.tsx

@@ -31,10 +31,17 @@ import { FormRuntimeProvider, useFormRuntime } from '../runtime/formRuntimeConte
 import { FormRuntimeWsClient } from '../runtime/formRuntimeWs'
 import { executeFormAutoControl } from '../runtime/formAutoControl'
 import type { FormAutoControlEventData } from '../runtime/types'
+import { buildFormRuntimeSnapshot } from '../runtime/buildFormRuntimeSnapshot'
+import {
+  FormLiveOptionsProvider,
+  useFormLiveOptions,
+} from '../runtime/formLiveOptionsContext'
 import SkoponFormRenderer, { type SkoponFormRendererRef } from './SkoponFormRenderer'
 import CurlSubmitBlock from './CurlSubmitBlock'
 import SkoponFormProvider from './SkoponFormProvider'
 
+const REFRESH_REPORT_DEBOUNCE_MS = 80
+
 function formatSubmitErrorMessage(status: number, body: unknown): string {
   if (body && typeof body === 'object' && body !== null && 'message' in body) {
     const msg = (body as { message: unknown }).message
@@ -101,6 +108,9 @@ function AskUserFormCardBody({
   const onNotifyRef = useRef(onNotify)
   onNotifyRef.current = onNotify
   const runtime = useFormRuntime()
+  const liveOptionsCtx = useFormLiveOptions()
+  const lastInitKeyRef = useRef('')
+  const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const resolvedFormUniqueId = formUniqueId?.trim() ?? ''
   const resolvedAskUserMessageId = askUserMessageId?.trim() ?? ''
@@ -122,6 +132,10 @@ function AskUserFormCardBody({
     mountedRef.current = true
     return () => {
       mountedRef.current = false
+      if (refreshTimerRef.current != null) {
+        clearTimeout(refreshTimerRef.current)
+        refreshTimerRef.current = null
+      }
     }
   }, [])
 
@@ -193,12 +207,25 @@ function AskUserFormCardBody({
       .map((block) => block.name!.trim())
   }, [usePayloadFallback, payloadDef, renderBlocks])
 
+  const surfaceTitle = intersection?.title ?? payloadDef?.title ?? ''
+  const surfaceDescription = intersection?.description ?? payloadDef?.description ?? ''
+
   const surfaceDoc = useMemo(() => {
     if (renderBlocks.length === 0) return null
-    const title = intersection?.title ?? payloadDef?.title ?? ''
-    const description = intersection?.description ?? payloadDef?.description ?? ''
-    return buildAskUserSurface({ title, description }, renderBlocks)
-  }, [intersection, payloadDef, renderBlocks])
+    return buildAskUserSurface(
+      { title: surfaceTitle, description: surfaceDescription },
+      renderBlocks,
+    )
+  }, [surfaceTitle, surfaceDescription, renderBlocks])
+
+  const docKey = useMemo(() => {
+    if (!surfaceDoc) return ''
+    try {
+      return JSON.stringify(surfaceDoc)
+    } catch {
+      return String(surfaceDoc)
+    }
+  }, [surfaceDoc])
 
   const surfaceId = resolvedFormUniqueId
     ? `ask-user-${resolvedFormUniqueId}`
@@ -211,6 +238,76 @@ function AskUserFormCardBody({
     return () => onSurfaceReadyChange(false)
   }, [hasFormSurface, onSurfaceReadyChange])
 
+  const collectAnswer = useCallback(() => {
+    const cardValues = rendererRef.current?.getValues(fieldNames) ?? {}
+    return { ...cardValues, ...extraValues }
+  }, [fieldNames, extraValues])
+
+  // live options 走 ref，避免 options 刷新导致 reportSnapshot 引用变化、打断 Init 定时器
+  const liveOptionsRef = useRef(liveOptionsCtx.liveOptions)
+  liveOptionsRef.current = liveOptionsCtx.liveOptions
+  const pendingChangeRef = useRef(liveOptionsCtx.pendingChangeFields)
+  pendingChangeRef.current = liveOptionsCtx.pendingChangeFields
+
+  const reportSnapshot = useCallback(
+    (formChange: string[]) => {
+      const snapshot = buildFormRuntimeSnapshot({
+        title: surfaceTitle,
+        description: surfaceDescription,
+        blocks: renderBlocks,
+        values: collectAnswer(),
+        liveOptions: liveOptionsRef.current,
+        formChange,
+      })
+      runtime.reportData(snapshot)
+    },
+    [surfaceTitle, surfaceDescription, renderBlocks, collectAnswer, runtime],
+  )
+  const reportSnapshotRef = useRef(reportSnapshot)
+  reportSnapshotRef.current = reportSnapshot
+
+  // Init：surface 就绪或 doc 内容变化时上报（form_change: []）
+  // lastInitKey 仅在实际上报后写入；定时器被取消时不占位，避免 Init 被永久跳过。
+  useEffect(() => {
+    if (!hasFormSurface) {
+      lastInitKeyRef.current = ''
+      return
+    }
+    if (!docKey) return
+    const initKey = `${surfaceId}::${docKey}`
+    if (lastInitKeyRef.current === initKey) return
+    const timer = setTimeout(() => {
+      if (!mountedRef.current) return
+      if (lastInitKeyRef.current === initKey) return
+      lastInitKeyRef.current = initKey
+      reportSnapshotRef.current([])
+    }, 0)
+    return () => clearTimeout(timer)
+  }, [hasFormSurface, surfaceId, docKey])
+
+  // Refresh：live options 变更后 debounce 上报（form_change 为变更字段）
+  useEffect(() => {
+    if (!hasFormSurface || liveOptionsCtx.version === 0) return
+    if (pendingChangeRef.current.length === 0) return
+    if (refreshTimerRef.current != null) {
+      clearTimeout(refreshTimerRef.current)
+    }
+    refreshTimerRef.current = setTimeout(() => {
+      refreshTimerRef.current = null
+      if (!mountedRef.current) return
+      const changed = [...pendingChangeRef.current]
+      liveOptionsCtx.clearPendingChangeFields()
+      if (changed.length === 0) return
+      reportSnapshotRef.current(changed)
+    }, REFRESH_REPORT_DEBOUNCE_MS)
+    return () => {
+      if (refreshTimerRef.current != null) {
+        clearTimeout(refreshTimerRef.current)
+        refreshTimerRef.current = null
+      }
+    }
+  }, [hasFormSurface, liveOptionsCtx.version, liveOptionsCtx.clearPendingChangeFields])
+
   const handleSubmit = useCallback(async () => {
     if (submitting) return
     setSubmitting(true)
@@ -229,8 +326,7 @@ function AskUserFormCardBody({
           onNotifyRef.current?.('error', 'callback_url 为空，无法提交')
           return
         }
-        // 确认可 POST 后再上报，避免空 callback 仍发 data/submit
-        runtime.reportData(answer)
+        reportSnapshot([])
         runtime.reportEvent({
           action: 'submit',
           component: 'SubmitButton',
@@ -258,7 +354,7 @@ function AskUserFormCardBody({
         onNotifyRef.current?.('error', agentError)
         return
       }
-      runtime.reportData(answer)
+      reportSnapshot([])
       runtime.reportEvent({
         action: 'submit',
         component: 'SubmitButton',
@@ -281,6 +377,7 @@ function AskUserFormCardBody({
     fieldNames,
     renderBlocks,
     extraValues,
+    reportSnapshot,
     runtime,
     submitMode,
     callbackUrl,
@@ -407,7 +504,7 @@ export default function AskUserFormCard(props: AskUserFormCardProps) {
     [],
   )
 
-  // 有 URL + id 即创建 client 并挂到 Provider：表单刚可交互时 send 可入队，
+  // 有 URL + id 即创建会话并挂到 Provider：表单刚可交互时 send 可入队，
   // 不必等 setState(surfaceReady) / connect 完成。
   const wsClient = useMemo(() => {
     if (!realtimeWsUrl || !resolvedAskUserMessageId) return null
@@ -435,11 +532,13 @@ export default function AskUserFormCard(props: AskUserFormCardProps) {
   return (
     <SkoponFormProvider>
       <FormRuntimeProvider client={wsClient}>
-        <AskUserFormCardBody
-          {...props}
-          onSurfaceReadyChange={onSurfaceReadyChange}
-          onAutoControlReady={onAutoControlReady}
-        />
+        <FormLiveOptionsProvider>
+          <AskUserFormCardBody
+            {...props}
+            onSurfaceReadyChange={onSurfaceReadyChange}
+            onAutoControlReady={onAutoControlReady}
+          />
+        </FormLiveOptionsProvider>
       </FormRuntimeProvider>
     </SkoponFormProvider>
   )

package/src/runtime/buildFormRuntimeSnapshot.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { buildFormRuntimeSnapshot } from './buildFormRuntimeSnapshot'
+import type { FormBlock } from '../types/index'
+
+describe('buildFormRuntimeSnapshot', () => {
+  const blocks: FormBlock[] = [
+    {
+      id: 'b1',
+      type: 'text',
+      name: 'title',
+      label: '标题',
+      required: true,
+    },
+    {
+      id: 'b2',
+      type: 'select',
+      name: 'city',
+      label: '城市',
+      options: [
+        { value: 'sh', label: '上海' },
+        { value: 'bj', label: '北京' },
+      ],
+    },
+    {
+      id: 'b3',
+      type: 'resume_multiselect',
+      name: 'resumes',
+      label: '简历',
+      options: [],
+    },
+  ]
+
+  it('builds flat form_values and schema blocks', () => {
+    const snapshot = buildFormRuntimeSnapshot({
+      title: 'Ask',
+      description: 'desc',
+      blocks,
+      values: {
+        title: 'hello',
+        city: 'sh',
+        resumes: ['r1'],
+        unused: undefined,
+      },
+      formChange: [],
+    })
+    expect(snapshot.form_schema.title).toBe('Ask')
+    expect(snapshot.form_schema.description).toBe('desc')
+    expect(snapshot.form_schema.blocks).toHaveLength(3)
+    expect(snapshot.form_values).toEqual({
+      title: 'hello',
+      city: 'sh',
+      resumes: ['r1'],
+    })
+    expect(snapshot.form_change).toEqual([])
+  })
+
+  it('overrides resume/case options from live registry', () => {
+    const live = new Map([
+      [
+        'resumes',
+        [
+          { value: 'r1', label: 'Alice' },
+          { value: 'r2', label: 'Bob' },
+        ],
+      ],
+    ])
+    const snapshot = buildFormRuntimeSnapshot({
+      blocks,
+      values: { resumes: ['r1'] },
+      liveOptions: live,
+      formChange: ['resumes'],
+    })
+    const resumeBlock = snapshot.form_schema.blocks[2] as FormBlock
+    expect(resumeBlock.options).toEqual([
+      { value: 'r1', label: 'Alice' },
+      { value: 'r2', label: 'Bob' },
+    ])
+    expect(snapshot.form_change).toEqual(['resumes'])
+  })
+
+  it('does not mutate static select options via live map for other types', () => {
+    const live = new Map([['city', [{ value: 'gz', label: '广州' }]]])
+    const snapshot = buildFormRuntimeSnapshot({
+      blocks,
+      values: { city: 'sh' },
+      liveOptions: live,
+    })
+    const cityBlock = snapshot.form_schema.blocks[1] as FormBlock
+    expect(cityBlock.options).toEqual([
+      { value: 'sh', label: '上海' },
+      { value: 'bj', label: '北京' },
+    ])
+  })
+})

package/src/runtime/buildFormRuntimeSnapshot.ts

@@ -0,0 +1,61 @@
+import type { FormBlock, FormBlockOption } from '../types/index'
+import type { FormRuntimeDataPayload } from './types'
+
+export type LiveOptionsMap = ReadonlyMap<string, FormBlockOption[]>
+
+function omitUndefinedValues(
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+function applyLiveOptions(
+  block: FormBlock,
+  liveOptions: LiveOptionsMap | undefined,
+): FormBlock {
+  const name = block.name?.trim()
+  if (!name || !liveOptions) return { ...block }
+  const live = liveOptions.get(name)
+  if (!live) return { ...block }
+  if (block.type !== 'resume_multiselect' && block.type !== 'case_multiselect') {
+    return { ...block }
+  }
+  return { ...block, options: live.map((opt) => ({ ...opt })) }
+}
+
+export interface BuildFormRuntimeSnapshotInput {
+  title?: string
+  description?: string
+  blocks: FormBlock[]
+  values: Record<string, unknown>
+  liveOptions?: LiveOptionsMap
+  formChange?: string[]
+}
+
+/**
+ * 构建 form_runtime_data 快照：form_schema（block 格式）+ 扁平 form_values + form_change。
+ */
+export function buildFormRuntimeSnapshot(
+  input: BuildFormRuntimeSnapshotInput,
+): FormRuntimeDataPayload {
+  const blocks = (input.blocks ?? []).map((block) =>
+    applyLiveOptions(block, input.liveOptions),
+  )
+  const form_schema: FormRuntimeDataPayload['form_schema'] = {
+    blocks,
+  }
+  const title = input.title?.trim()
+  const description = input.description?.trim()
+  if (title) form_schema.title = title
+  if (description) form_schema.description = description
+
+  return {
+    form_schema,
+    form_values: omitUndefinedValues(input.values ?? {}),
+    form_change: [...(input.formChange ?? [])],
+  }
+}