@skopon-cool/form-sdk

Skopon 表单渲染 SDK：基于 A2UI v0.9 + skopon 自定义 catalog，统一渲染 form_definition、A2UI surface 与增量 message 流，并提供 Ask User 提交能力（默认复制 curl，可选 POST JSON）。

安装

方式一：一键安装（推荐 Agent 客户端）

安装 meta 包，自动带上 SDK 及全部 peer 依赖（react、antd、@a2ui/* 等）：

npm install @skopon-cool/form-sdk-bundle

使用方式与主包相同，可从 bundle 直接 import：

import '@skopon-cool/form-sdk-bundle/styles.css'
import { AskUserFormCard, createFormClient } from '@skopon-cool/form-sdk-bundle'

方式二：手动安装主包 + peer

若宿主项目已有 React / Ant Design，只需补装 SDK 与 A2UI peer：

npm install @skopon-cool/form-sdk react react-dom antd @a2ui/react @a2ui/web_core @ant-design/icons

dayjs、zod 已作为 SDK 普通依赖随包安装，无需单独安装。

Peer dependencies 说明

| 包 | 说明 | |----|------| | react / react-dom | 须与宿主共用同一实例，不可由 SDK 内嵌 | | antd / @ant-design/icons | 表单控件与图标，须与宿主主题一致 | | @a2ui/react / @a2ui/web_core | A2UI 渲染栈（SDK 内部使用，宿主无需写 A2UI 代码） |

样式

主入口 import '@skopon-cool/form-sdk' 会在构建产物中自动加载 form-sdk.css（含 A2UI 预览样式）。

也可显式引入（推荐在生产环境双保险）：

import '@skopon-cool/form-sdk/styles.css'
// bundle 用户：import '@skopon-cool/form-sdk-bundle/styles.css'

渲染 form_definition

import { SkoponFormRenderer, blocksToA2ui, resolveSurfaceFromFormDefinition } from '@skopon-cool/form-sdk'

const surface = resolveSurfaceFromFormDefinition(formDefinition)
// 或
const surface = blocksToA2ui(formDefinition)

<SkoponFormRenderer doc={surface} interactive />

A2UI 增量流

import { SkoponA2uiStreamRenderer } from '@skopon-cool/form-sdk'

<SkoponA2uiStreamRenderer messages={incomingMessages} interactive />

Ask User（QA / 流程 AI 聊天）

payload 须为 blocksJson（{ title?, description?, blocks[] }），与表单编辑器 Blocks Json 同形。前端按 form_unique_id 拉取表单后与 payload.blocks 按 name 交集渲染卡片；payload 中表单外的块不在卡片展示，但提交 curl 时会合并进 body 并以注释标注为额外字段。

import { AskUserFormCard, createFormClient } from '@skopon-cool/form-sdk'

const client = createFormClient({
  baseUrl: '/api/v1',
  getHeaders: () => ({ Authorization: 'Bearer …' }),
})

<AskUserFormCard
  payload={message.payload}
  formUniqueId={message.form_unique_id}
  callbackUrl={message.callback_url}
  fetchFormDetail={client.fetchDetail}
  submitMode="curl"
/>

提交

• submitMode: 'curl'（默认）：复制 curl 到剪贴板（卡片填值 + 额外字段，extra 段含 // 额外字段（未在卡片展示） 注释）
• submitMode: 'post'：submitFormJson(callbackUrl, { ...cardValues, ...extraValues }) POST 合法 JSON

独立工具：

import { buildAskUserCurlStatement, buildCurlStatement, submitFormJson } from '@skopon-cool/form-sdk'

从 form_bp 拉取详情

import { createFormClient } from '@skopon-cool/form-sdk'

const client = createFormClient({
  baseUrl: '/api/v1',
  detailPath: '/dev/form/detail',
  getHeaders: async () => ({ Authorization: '…' }),
})

const detail = await client.fetchDetail({ formUniqueId: 'formuid-xxx' })

发布

cd sdk/front/form && npm publish --access public
cd sdk/front/form-bundle && npm publish --access public