@skopon-cool/form-sdk 0.2.5 → 0.3.0

package/dist/runtime/formAutoControl.d.ts

@@ -0,0 +1,15 @@
+import type { FormAutoControlEventData, FormRuntimeEventData } from './types';
+export interface FormAutoControlTargets {
+    setValues: (values: Record<string, unknown>) => void;
+    getValues: (fieldNames?: string[]) => Record<string, unknown>;
+    submit: () => void | Promise<void>;
+    /** 卡片根节点，用于按 data-skopon-field 定位 DOM */
+    rootElement: HTMLElement | null;
+}
+export interface FormAutoControlHelpers {
+    reportEvent: (event: FormRuntimeEventData) => void;
+    runAutoControl: <T>(fn: () => T) => T;
+}
+/** 执行下行 form_auto_control_event；缺参或未知 action 时 warn 并忽略。 */
+export declare function executeFormAutoControl(data: FormAutoControlEventData, targets: FormAutoControlTargets, helpers: FormAutoControlHelpers): void;
+//# sourceMappingURL=formAutoControl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formAutoControl.d.ts","sourceRoot":"","sources":["../../src/runtime/formAutoControl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE7E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;IACpD,SAAS,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,yCAAyC;IACzC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAClD,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;CACtC;AAiCD,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,wBAAwB,EAC9B,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAyDN"}

package/dist/runtime/formRuntimeContext.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import type { FormRuntimeWsClient } from './formRuntimeWs';
+import type { FormRuntimeEventData } from './types';
+export interface FormRuntimeContextValue {
+    reportEvent: (event: FormRuntimeEventData) => void;
+    reportData: (values: Record<string, unknown>) => void;
+    runAutoControl: <T>(fn: () => T) => T;
+    isAutoControl: () => boolean;
+}
+export interface FormRuntimeProviderProps {
+    client: FormRuntimeWsClient | null;
+    children: ReactNode;
+}
+export declare function FormRuntimeProvider({ client, children, }: FormRuntimeProviderProps): import("react").JSX.Element;
+/** 无 Provider 时 no-op（表单管理端预览不受影响）。 */
+export declare function useFormRuntime(): FormRuntimeContextValue;
+//# sourceMappingURL=formRuntimeContext.d.ts.map

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

@@ -0,0 +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,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,aAAa,EAAE,MAAM,OAAO,CAAA;CAC7B;AAqBD,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,+BAwD1B;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,uBAAuB,CAExD"}

package/dist/runtime/formRuntimeWs.d.ts

@@ -0,0 +1,27 @@
+import type { FormAutoControlEventData, FormRuntimeEnvelope, FormRuntimeOutboundType } from './types';
+export type FormAutoControlHandler = (data: FormAutoControlEventData, envelope: FormRuntimeEnvelope<FormAutoControlEventData>) => void;
+export interface FormRuntimeWsClientOptions {
+    url: string;
+    askUserMessageId: string;
+    onAutoControl?: FormAutoControlHandler;
+}
+export declare class FormRuntimeWsClient {
+    private readonly url;
+    private readonly askUserMessageId;
+    private readonly onAutoControl?;
+    private ws;
+    private closed;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private sendQueue;
+    constructor(options: FormRuntimeWsClientOptions);
+    connect(): void;
+    send(type: FormRuntimeOutboundType, data: Record<string, unknown>): void;
+    close(): void;
+    private enqueue;
+    private flushQueue;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private handleMessage;
+}
+//# sourceMappingURL=formRuntimeWs.d.ts.map

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

@@ -0,0 +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;IA0Bf,IAAI,CACF,IAAI,EAAE,uBAAuB,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAqBP,KAAK,IAAI,IAAI;IAkBb,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;CAgBtB"}

package/dist/runtime/types.d.ts

@@ -0,0 +1,20 @@
+export type FormRuntimeAction = 'focus' | 'change' | 'select' | 'click' | 'submit';
+export interface FormRuntimeEventData {
+    action: FormRuntimeAction;
+    component: string;
+    field?: string;
+    value?: unknown;
+}
+export interface FormAutoControlEventData {
+    action: FormRuntimeAction;
+    field?: string;
+    value?: unknown;
+    component?: string;
+}
+export type FormRuntimeOutboundType = 'form_runtime_data' | 'form_runtime_event' | 'form_auto_control_bac_event';
+export interface FormRuntimeEnvelope<T = Record<string, unknown>> {
+    type: string;
+    ask_user_message_id: string;
+    data: T;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +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"}

package/package.json

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

package/src/catalog/a2uiCustomCatalog.tsx

@@ -242,7 +242,10 @@ const SkoponSelectApi = {
 
 function SkoponSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'SkoponSelect',
+    changeAction: 'select',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
   const placeholder = readString(props.placeholder)
@@ -251,11 +254,11 @@ function SkoponSelectPreview({ context }: { context: ComponentContext }) {
 
   useEffect(() => {
     const normalized = normalizeSelectStoredValue(value, isMultiple)
-    if (normalized !== null) setValue(normalized)
-  }, [isMultiple, value, setValue])
+    if (normalized !== null) setValueSilent(normalized)
+  }, [isMultiple, value, setValueSilent])
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       <Select
         mode={isMultiple ? 'multiple' : undefined}
@@ -279,7 +282,10 @@ const SkoponSelectImpl = createBinderlessComponentImplementation(
 
 function ChoicePickerPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'ChoicePicker',
+    changeAction: 'select',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
   const variant = readString(props.variant) || 'mutuallyExclusive'
@@ -301,11 +307,11 @@ function ChoicePickerPreview({ context }: { context: ComponentContext }) {
 
   useEffect(() => {
     const normalized = normalizeSelectStoredValue(value, isMultiplePicker)
-    if (normalized !== null) setValue(normalized)
-  }, [isMultiplePicker, value, setValue])
+    if (normalized !== null) setValueSilent(normalized)
+  }, [isMultiplePicker, value, setValueSilent])
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {effectiveType === 'select' ? (
         <Select
@@ -370,12 +376,15 @@ const ChoicePickerImpl = createBinderlessComponentImplementation(
 
 function ToggleSwitchPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'CheckBox',
+    changeAction: 'change',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       <Switch
         disabled={!interactive}
@@ -409,7 +418,10 @@ function toDateTimePickerValue(
 
 function DateTimeInputPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, fieldName, reportFocus } = useSkoponBoundField(context, 'value', {
+    component: 'DateTimeInput',
+    changeAction: 'change',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
   const placeholder = readString(props.placeholder)
@@ -434,7 +446,7 @@ function DateTimeInputPreview({ context }: { context: ComponentContext }) {
   }
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {!enableDate && enableTime ? (
         <TimePicker
@@ -444,6 +456,7 @@ function DateTimeInputPreview({ context }: { context: ComponentContext }) {
           placeholder={placeholder || '选择时间'}
           value={pickerValue}
           onChange={handleChange}
+          onFocus={reportFocus}
         />
       ) : (
         <DatePicker
@@ -457,6 +470,7 @@ function DateTimeInputPreview({ context }: { context: ComponentContext }) {
           }
           value={pickerValue}
           onChange={handleChange}
+          onFocus={reportFocus}
         />
       )}
     </div>
@@ -498,7 +512,10 @@ const FileUploadApi = {
 
 function FileUploadPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'FileUpload',
+    changeAction: 'change',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
   const accept = readString(props.accept)
@@ -524,7 +541,7 @@ function FileUploadPreview({ context }: { context: ComponentContext }) {
   const belowMinCount = selectedNames.length < minCount
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       <Upload.Dragger
         disabled={!interactive || atMaxLimit}
@@ -585,7 +602,11 @@ const FileUploadImpl = createBinderlessComponentImplementation(
 
 function TextFieldPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, fieldName, reportFocus } = useSkoponBoundField(context, 'value', {
+    component: 'TextField',
+    changeAction: 'change',
+    debounceChange: true,
+  })
   const props = context.componentModel.properties as Record<string, unknown>
   const label = readString(props.label)
   const placeholder = readString(props.placeholder)
@@ -624,6 +645,7 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
           setValue(next)
           validateFormat(next)
         }}
+        onFocus={reportFocus}
         onBlur={(e) => validateFormat(e.target.value)}
       />
     )
@@ -638,6 +660,7 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
         placeholder={placeholder || '数字'}
         value={numericValue}
         onChange={(next) => setValue(next == null ? '' : String(next))}
+        onFocus={reportFocus}
       />
     )
   } else if (variant === 'obscured') {
@@ -648,6 +671,7 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
         placeholder={placeholder}
         value={stringValue}
         onChange={(e) => setValue(e.target.value)}
+        onFocus={reportFocus}
       />
     )
   } else {
@@ -663,13 +687,14 @@ function TextFieldPreview({ context }: { context: ComponentContext }) {
           setValue(next)
           validateFormat(next)
         }}
+        onFocus={reportFocus}
         onBlur={(e) => validateFormat(e.target.value)}
       />
     )
   }
 
   return (
-    <div className="form-block-preview">
+    <div className="form-block-preview" data-skopon-field={fieldName || undefined}>
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {control}
       {formatError ? (

package/src/catalog/skoponCaseSelect.tsx

@@ -110,7 +110,10 @@ function CaseCard({
 function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const caseSearch = useCaseSearch()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'SkoponCaseSelect',
+    changeAction: 'click',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
 
   const label = readString(props.label)
@@ -134,8 +137,8 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
 
   useEffect(() => {
     const clamped = clampStringArraySelection(selectedIds, maxCount)
-    if (clamped !== null) setValue(clamped)
-  }, [maxCount, selectedIds, setValue])
+    if (clamped !== null) setValueSilent(clamped)
+  }, [maxCount, selectedIds, setValueSilent])
 
   const emptyHint = useMemo(() => {
     if (!caseSearch) return '未配置案例搜索服务'
@@ -202,7 +205,10 @@ function SkoponCaseSelectPreview({ context }: { context: ComponentContext }) {
   }
 
   return (
-    <div className="form-block-preview skopon-resume-select">
+    <div
+      className="form-block-preview skopon-resume-select"
+      data-skopon-field={fieldName || undefined}
+    >
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {loading && items.length === 0 ? (
         <div className="skopon-resume-select-status">

package/src/catalog/skoponResumeSelect.tsx

@@ -163,7 +163,10 @@ function ResumeCard({
 function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
   const { interactive } = useA2uiPreviewMode()
   const resumeSearch = useResumeSearch()
-  const { value, setValue } = useSkoponBoundField(context)
+  const { value, setValue, setValueSilent, fieldName } = useSkoponBoundField(context, 'value', {
+    component: 'SkoponResumeSelect',
+    changeAction: 'click',
+  })
   const props = context.componentModel.properties as Record<string, unknown>
 
   const label = readString(props.label)
@@ -187,8 +190,8 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
 
   useEffect(() => {
     const clamped = clampStringArraySelection(selectedIds, maxCount)
-    if (clamped !== null) setValue(clamped)
-  }, [maxCount, selectedIds, setValue])
+    if (clamped !== null) setValueSilent(clamped)
+  }, [maxCount, selectedIds, setValueSilent])
 
   const fetchPage = useCallback(
     async (targetPage: number) => {
@@ -250,7 +253,10 @@ function SkoponResumeSelectPreview({ context }: { context: ComponentContext }) {
   const emptyLabel = placeholder || '暂无匹配的简历'
 
   return (
-    <div className="form-block-preview skopon-resume-select">
+    <div
+      className="form-block-preview skopon-resume-select"
+      data-skopon-field={fieldName || undefined}
+    >
       {label ? <div className="form-block-preview-label">{label}</div> : null}
       {loading && items.length === 0 ? (
         <div className="skopon-resume-select-status">

package/src/catalog/useSkoponBoundField.ts

@@ -1,8 +1,12 @@
-import { useCallback, useSyncExternalStore } from 'react'
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react'
 import type { ComponentContext } from '@a2ui/web_core/v0_9'
+import { useFormRuntime } from '../runtime/formRuntimeContext'
+import type { FormRuntimeAction } from '../runtime/types'
 
 type DynamicBinding = Parameters<ComponentContext['dataContext']['resolveDynamicValue']>[0]
 
+const TEXT_CHANGE_DEBOUNCE_MS = 300
+
 function bindingPath(value: unknown): string | null {
   if (value && typeof value === 'object' && 'path' in value) {
     const path = String((value as { path: unknown }).path ?? '').trim()
@@ -11,6 +15,14 @@ function bindingPath(value: unknown): string | null {
   return null
 }
 
+/** 从 path（如 /fieldName）提取字段名。 */
+export function fieldNameFromBindingPath(path: string | null): string | undefined {
+  if (!path) return undefined
+  const trimmed = path.trim()
+  if (!trimmed) return undefined
+  return trimmed.startsWith('/') ? trimmed.slice(1) : trimmed
+}
+
 /** 从 A2UI 组件 context 读取当前绑定字段值（不订阅更新，适合事件回调内读最新值）。 */
 export function readBoundFieldValue(context: ComponentContext, field = 'value'): unknown {
   const props = context.componentModel.properties as Record<string, unknown>
@@ -20,11 +32,44 @@ export function readBoundFieldValue(context: ComponentContext, field = 'value'):
   return context.dataContext.resolveDynamicValue(binding)
 }
 
+export interface UseSkoponBoundFieldOptions {
+  /** catalog 组件名，用于 runtime event */
+  component?: string
+  /** setValue 上报的 action，默认 change */
+  changeAction?: Extract<FormRuntimeAction, 'change' | 'select' | 'click'>
+  /** TextField 等文本输入是否对 change 防抖 */
+  debounceChange?: boolean
+}
+
 /** 将 skopon 预览控件绑定到 A2UI surface dataModel（与 basicCatalog binder 行为一致）。 */
-export function useSkoponBoundField(context: ComponentContext, field = 'value') {
+export function useSkoponBoundField(
+  context: ComponentContext,
+  field = 'value',
+  options: UseSkoponBoundFieldOptions = {},
+) {
   const props = context.componentModel.properties as Record<string, unknown>
   const binding = props[field] as DynamicBinding | undefined
   const path = bindingPath(binding)
+  const fieldName = fieldNameFromBindingPath(path)
+  const runtime = useFormRuntime()
+  const {
+    component = 'Unknown',
+    changeAction = 'change',
+    debounceChange = false,
+  } = options
+
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const runtimeRef = useRef(runtime)
+  runtimeRef.current = runtime
+
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current != null) {
+        clearTimeout(debounceTimerRef.current)
+        debounceTimerRef.current = null
+      }
+    }
+  }, [])
 
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
@@ -42,7 +87,33 @@ export function useSkoponBoundField(context: ComponentContext, field = 'value')
 
   const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
-  const setValue = useCallback(
+  const reportValueChange = useCallback(
+    (next: unknown) => {
+      if (!fieldName) return
+      const emit = () => {
+        runtimeRef.current.reportEvent({
+          action: changeAction,
+          component,
+          field: fieldName,
+          value: next,
+        })
+      }
+      if (!debounceChange) {
+        emit()
+        return
+      }
+      if (debounceTimerRef.current != null) {
+        clearTimeout(debounceTimerRef.current)
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        debounceTimerRef.current = null
+        emit()
+      }, TEXT_CHANGE_DEBOUNCE_MS)
+    },
+    [fieldName, changeAction, component, debounceChange],
+  )
+
+  const setValueSilent = useCallback(
     (next: unknown) => {
       if (!path || !binding || typeof binding !== 'object' || !('path' in binding)) return
       context.dataContext.set(String((binding as { path: string }).path), next)
@@ -50,7 +121,32 @@ export function useSkoponBoundField(context: ComponentContext, field = 'value')
     [context, binding, path],
   )
 
-  return { value, setValue, hasBinding: !!path }
+  const setValue = useCallback(
+    (next: unknown) => {
+      setValueSilent(next)
+      reportValueChange(next)
+    },
+    [setValueSilent, reportValueChange],
+  )
+
+  const reportFocus = useCallback(() => {
+    if (!fieldName) return
+    runtimeRef.current.reportEvent({
+      action: 'focus',
+      component,
+      field: fieldName,
+    })
+  }, [fieldName, component])
+
+  return {
+    value,
+    setValue,
+    /** 写入 dataModel 但不上报（用于模式切换规范化等内部同步） */
+    setValueSilent,
+    hasBinding: !!path,
+    fieldName,
+    reportFocus,
+  }
 }
 
 export function asOptionalString(value: unknown): string | undefined {

package/src/client/authStorage.test.ts

@@ -4,9 +4,11 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import {
   DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD,
+  DEFAULT_AUTH_REALTIME_WS_URL_FIELD,
   DEFAULT_ANSWER_AGENT_CALLBACK_URL,
   DEFAULT_AUTH_STORAGE_KEY,
   resolveAnswerAgentCallbackUrl,
+  resolveRealtimeWsUrl,
   resolveSkoponAuthHeaders,
   resolveSubmitAuthHeaders,
 } from './authStorage'
@@ -129,3 +131,35 @@ describe('resolveAnswerAgentCallbackUrl', () => {
     expect(resolveAnswerAgentCallbackUrl()).toBe(DEFAULT_ANSWER_AGENT_CALLBACK_URL)
   })
 })
+
+describe('resolveRealtimeWsUrl', () => {
+  afterEach(() => {
+    sessionStorage.clear()
+    localStorage.clear()
+  })
+
+  it('reads realtime_ws_url from sessionStorage auth_user', () => {
+    sessionStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({
+        token: 'tok',
+        [DEFAULT_AUTH_REALTIME_WS_URL_FIELD]: 'wss://example.com/ws',
+      }),
+    )
+    expect(resolveRealtimeWsUrl()).toBe('wss://example.com/ws')
+  })
+
+  it('returns empty string when session is missing', () => {
+    expect(resolveRealtimeWsUrl()).toBe('')
+  })
+
+  it('returns empty string when field is missing or blank', () => {
+    sessionStorage.setItem(DEFAULT_AUTH_STORAGE_KEY, JSON.stringify({ token: 'tok' }))
+    expect(resolveRealtimeWsUrl()).toBe('')
+    sessionStorage.setItem(
+      DEFAULT_AUTH_STORAGE_KEY,
+      JSON.stringify({ token: 'tok', [DEFAULT_AUTH_REALTIME_WS_URL_FIELD]: '  ' }),
+    )
+    expect(resolveRealtimeWsUrl()).toBe('')
+  })
+})

package/src/client/authStorage.ts

@@ -10,6 +10,7 @@ export interface SkoponAuthStorageOptions {
 export const DEFAULT_AUTH_STORAGE_KEY = 'auth_user'
 export const DEFAULT_AUTH_TOKEN_FIELD = 'token'
 export const DEFAULT_AUTH_ANSWER_AGENT_CALLBACK_URL_FIELD = 'answer_agent_callback_url'
+export const DEFAULT_AUTH_REALTIME_WS_URL_FIELD = 'realtime_ws_url'
 /** 与 skopon-admin 登录写入的 mock answer-agent 路径一致 */
 export const DEFAULT_ANSWER_AGENT_CALLBACK_URL = '/api/v1/mock/ask_user_answer_mock'
 
@@ -74,6 +75,32 @@ export function resolveAnswerAgentCallbackUrl(
   return trimmed || DEFAULT_ANSWER_AGENT_CALLBACK_URL
 }
 
+/**
+ * 从宿主登录缓存读取 realtime_ws_url。
+ * 无 session / 无字段 / 空串时返回 ''（不建连）；SDK 不负责写入该字段。
+ */
+export function resolveRealtimeWsUrl(
+  options: SkoponAuthStorageOptions & {
+    realtimeWsUrlField?: string
+  } = {},
+): string {
+  const storageKind = options.storage ?? 'sessionStorage'
+  const storageKey = options.storageKey ?? DEFAULT_AUTH_STORAGE_KEY
+  const field = options.realtimeWsUrlField ?? DEFAULT_AUTH_REALTIME_WS_URL_FIELD
+
+  const storage = readStorage(storageKind)
+  if (!storage) return ''
+
+  const raw = storage.getItem(storageKey)
+  if (!raw) return ''
+
+  const parsed = readSessionJson(raw)
+  if (!parsed) return ''
+
+  const url = parsed[field]
+  return typeof url === 'string' ? url.trim() : ''
+}
+
 /** 合并 session 鉴权头与宿主显式 headers；显式 headers 优先。 */
 export function resolveSubmitAuthHeaders(
   explicit?: Record<string, string>,