light-chain-open-ui 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,233 @@
+# light-chain-open-ui
+
+LightChain Open UI 是一组用于发起 AI 任务 workflow 的 Web Components、React 组件和前端任务客户端。
+
+它适合两种接入方式：
+
+- 使用 `lc-task-workflow` / `LcTaskWorkflowReact` 自动收集表单、校验字段、提交任务和轮询结果。
+- 使用 `LightChainClient` 手动提交多个任务，并让同一个客户端合并轮询。
+
+## 安装
+
+```bash
+npm install light-chain-open-ui
+```
+
+React 项目需要同时安装 React：
+
+```bash
+npm install react react-dom
+```
+
+## 导入入口
+
+```ts
+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 自动任务
+
+自动任务适合单个独立任务。组件内部会创建任务客户端，收集子组件字段并完成提交和轮询。
+
+```tsx
+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 赋值。
+
+```ts
+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)
+})
+```
+
+```html
+<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)` 会基于同一个客户端合并轮询。
+
+```ts
+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`。
+
+```ts
+const customRequest = async (input: RequestInfo | URL, init?: RequestInit) => {
+  const endpoint = typeof input === 'string' ? input : input.toString()
+  const url = new URL(endpoint, 'https://api.example.com')
+
+  return fetch(url.toString(), {
+    ...init,
+    headers: {
+      ...init?.headers,
+      'client-secret': getClientSecret(),
+    },
+  })
+}
+```
+
+`customUploadRequest` 用于把 `File` 上传成 URL，再提交给任务接口。
+
+```ts
+const customUploadRequest = async ({ formData }) => {
+  const response = await fetch('/upload', {
+    method: 'POST',
+    body: formData,
+  })
+  const data = await response.json()
+  return data.url
+}
+```
+
+## 枚举参数
+
+枚举选择器可以直接使用 `light-chain-open-ui/options` 导出的参数。
+
+```tsx
+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={JSON.stringify(OPTIONS_ASPECT_RATIO)}
+/>
+```
+
+## 主题
+
+默认样式会随组件一起工作。需要切换暗色主题时，引入主题样式并在页面上添加主题标记。
+
+```ts
+import 'light-chain-open-ui/src/styles/themes/default.css'
+import 'light-chain-open-ui/src/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[] }`。
+
+响应示例：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "taskId": "task_123"
+  }
+}
+```
+
+进度结果示例：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": [
+    {
+      "aiTaskId": "task_123",
+      "aiTaskStatus": "done",
+      "queuePos": null,
+      "taskProgress": 1,
+      "aiTaskResult": null,
+      "imgInfo": "https://example.com/result.png"
+    }
+  ]
+}
+```
+
+## 打包与发布
+
+```bash
+npm run build
+npm publish --access public
+```
+
+如果 npm 开启了双因素认证，需要使用支持 publish 的 automation token，或在发布时输入 OTP。