light-chain-open-ui

LightChain Open UI 是一组用于发起 AI 任务 workflow 的 Web Components、React 组件和前端任务客户端。

它适合两种接入方式：

• 使用 lc-task-workflow / LcTaskWorkflowReact 自动收集表单、校验字段、提交任务和轮询结果。
• 使用 LightChainClient 手动提交多个任务，并让同一个客户端合并轮询。

安装

npm install light-chain-open-ui

导入入口

import 'light-chain-open-ui'
import { LightChainClient } from 'light-chain-open-ui'
import { LcTaskWorkflowReact } from 'light-chain-open-ui/react'
import { OPTIONS_ASPECT_RATIO } from 'light-chain-open-ui/options'
import { TASK_WORKFLOW_TYPES } from 'light-chain-open-ui/contants'
import type { TaskWorkflowType } from 'light-chain-open-ui/types'

入口说明：

• light-chain-open-ui：注册 Web Components，并导出 LightChainClient 等核心能力。
• light-chain-open-ui/react：导出 React 封装组件。
• light-chain-open-ui/options：导出可选值参数，例如 OPTIONS_ASPECT_RATIO、OPTIONS_GENDER。
• light-chain-open-ui/contants：导出常量，例如 TASK_WORKFLOW_TYPES、WORKFLOW_DEFAULTS。
• light-chain-open-ui/types：导出 TypeScript 类型。

React 自动任务

自动任务适合单个独立任务。组件内部会创建任务客户端，收集子组件字段并完成提交和轮询。

import {
  LcButtonReact,
  LcImageUploaderReact,
  LcPromptInputReact,
  LcTaskWorkflowReact,
} from 'light-chain-open-ui/react'
import { TASK_WORKFLOW_TYPES } from 'light-chain-open-ui/contants'

export function FixFaceForm() {
  return (
    <LcTaskWorkflowReact
      type={TASK_WORKFLOW_TYPES.FIX_FACE}
      customRequest={customRequest}
      customUploadRequest={customUploadRequest}
      onSubmit={(event) => console.log(event.detail.taskId)}
      onSuccess={(event) => console.log(event.detail.images)}
      onError={(event) => console.error(event.detail.message)}
    >
      <LcImageUploaderReact name="imgUrl" label="模特图" required />
      <LcPromptInputReact name="prompt" label="修复要求" maxLength={500} />
      <LcButtonReact type="submit">开始生成</LcButtonReact>
    </LcTaskWorkflowReact>
  )
}

原生/Vue 自动任务

Web Components 通过属性和 DOM property 配置。函数类型参数需要通过 property 赋值。

import 'light-chain-open-ui'
import { TASK_WORKFLOW_TYPES } from 'light-chain-open-ui/contants'

const workflow = document.querySelector('lc-task-workflow')

workflow.type = TASK_WORKFLOW_TYPES.FIX_FACE
workflow.customRequest = customRequest
workflow.customUploadRequest = customUploadRequest

workflow.addEventListener('success', (event) => {
  console.log(event.detail.images)
})

<lc-task-workflow>
  <lc-image-uploader name="imgUrl" label="模特图" required></lc-image-uploader>
  <lc-prompt-input name="prompt" label="修复要求"></lc-prompt-input>
  <lc-button type="submit">开始生成</lc-button>
</lc-task-workflow>

手动任务客户端

手动模式适合批量任务或跨页面共享任务状态。LightChainClient 建议只创建一次，多个 submit(type, formData) 会基于同一个客户端合并轮询。

import { LightChainClient } from 'light-chain-open-ui'
import { TASK_WORKFLOW_TYPES } from 'light-chain-open-ui/contants'

const client = new LightChainClient({
  customRequest,
  customUploadRequest,
  onSubmit: ({ taskId }) => console.log('submitted', taskId),
  onPoll: ({ taskId, progress }) => console.log('polling', taskId, progress),
  onSuccess: ({ taskId, images }) => console.log('success', taskId, images),
  onError: ({ message }) => console.error(message),
})

await client.submit(TASK_WORKFLOW_TYPES.FIX_FACE, {
  imgUrl: 'https://example.com/model.png',
  prompt: '修复面部细节',
})

await client.submit(TASK_WORKFLOW_TYPES.SR, {
  imgUrl: 'https://example.com/image.png',
  scale: '2',
})

自定义请求

customRequest 用于接入业务后端。组件会根据 type 自动生成提交地址，例如 /task/submit/FixFace。 customRequest 只约定函数入参和返回结构，不限制内部用什么请求库。第一个参数是请求地址，第二个参数是请求数据；轮询请求没有请求数据。

const customRequest = async (url: string, data?: Record<string, unknown>) => {
  const endpoint = new URL(url, 'https://api.example.com')

  return fetch(endpoint.toString(), {
    method: data === undefined ? 'GET' : 'POST',
    body: data === undefined ? undefined : JSON.stringify(data),
    headers: {
      'content-type': 'application/json',
      'client-secret': getClientSecret(),
    },
  })
}

也可以使用 axios、umi-request 或业务封装请求。只要返回值符合 { data }、{ code, success, data }，或 axios 风格 { data: { code, success, data } } 即可：

const customRequest = (url: string, data?: Record<string, unknown>) => {
  return request(url, {
    method: data === undefined ? 'GET' : 'POST',
    data,
  })
}

customUploadRequest 用于把 File 上传成 URL，再提交给任务接口。

const customUploadRequest = async (file: File) => {
  const formData = new FormData()
  formData.append('file', file)

  const response = await fetch('/upload', {
    method: 'POST',
    body: formData,
  })
  const data = await response.json()
  return data.url
}

枚举参数

枚举选择器可以直接使用 light-chain-open-ui/options 导出的参数。

import { LcEnumSelectorReact } from 'light-chain-open-ui/react'
import { OPTIONS_ASPECT_RATIO } from 'light-chain-open-ui/options'

<LcEnumSelectorReact
  name="aspectRatio"
  label="宽高比"
  mode="select"
  options={OPTIONS_ASPECT_RATIO}
/>

主题

默认样式会随组件一起工作。需要切换暗色主题时，引入主题样式并在页面上添加主题标记。

import 'light-chain-open-ui/styles/themes/default.css'
import 'light-chain-open-ui/styles/themes/dark.css'

document.documentElement.dataset.theme = 'dark'

后端接入约定

前端提交任务后，业务后端应立即调用外部 AI 接口、落库任务记录，并返回任务 ID。前端随后通过轮询接口获取任务状态。

推荐接口：

• POST /task/submit/{type}：根据 type 调用对应外部接口，创建任务记录，返回 { code, success, data: { taskId } }。
• GET /task/progress?taskIds=a,b,c：批量查询任务状态，返回 { code, success, data: TaskProgressResult[] }。

响应示例：

{
  "code": 200,
  "success": true,
  "data": {
    "taskId": "task_123"
  }
}

进度结果示例：

{
  "code": 200,
  "success": true,
  "data": [
    {
      "aiTaskId": "task_123",
      "aiTaskStatus": "done",
      "queuePos": null,
      "taskProgress": 1,
      "aiTaskResult": null,
      "imgInfo": "https://example.com/result.png"
    }
  ]
}