Tongfang UI Kit - 砼方云鲲鹏基础前端组件库

面向砼方云鲲鹏产品的基础前端组件库，为低代码拖拽生成页面提供通用、参数化、可配置的 UI / 表单 / 布局 / AI 增强能力。

项目定位

| 层级 | 定位 | 复用范围 | |------|------|----------| | 组件库 | 砼方云鲲鹏产品基础前端组件库 | 鲲鹏产品与低代码搭建场景 | | 低代码基础设施 | 拖拽生成页面的组件物料与元数据 | Playground 演示、业务页面搭建、lowcode-agent 消费 |

核心原则：组件必须通用、参数化、可配置，不服务单一页面硬编码；业务差异通过 props、slots、composables、Design Tokens 和低代码元数据表达。

技术栈

| 类别 | 选型 | 说明 | |------|------|------| | 框架 | Vue 3 + TypeScript | 与鲲鹏产品前端技术栈对齐 | | 构建工具 | Vite 5 | 组件库与 Playground 构建 | | 样式方案 | Tailwind CSS + CSS Variables / Design Tokens | 原子化样式 + 可配置主题令牌 | | 单元测试 | Vitest + @vue/test-utils | 组件与 composables 稳定性保障 | | 文档/演示 | Playground (Vite) | 组件演示、开发沙箱、低代码验证入口 | | 低代码元数据 | @tongfun/ui/lowcode-agent | 独立入口导出组件注册表，供低代码/AI 生成链路消费 |

当前规模（扫描口径）

• 约 90+ 组件/模块：包含表单体系、通用 UI、布局、导航、AI 增强组件与 composables。
• 约 70+ Playground 演示路由/页面：用于组件示例、组合场景和低代码物料验证。
• 组件数量会随扫描口径变化，文档避免使用固定旧口径。

安装与使用

import { TfButton, useAiStateMachine } from '@tongfun/ui'
import '@tongfun/ui/style.css'
import registry from '@tongfun/ui/lowcode-agent'

console.log(registry.components)

<template>
  <TfButton type="primary">提交</TfButton>
</template>

目录结构

tongfang-ui-kit/
├── packages/
│   └── ui/
│       ├── components/        # 约 90+ 组件/模块（当前扫描口径）
│       │   ├── form/          # 表单核心、基础控件、复合项、容器
│       │   ├── layout/        # 页面、网格、分栏、侧栏等布局组件
│       │   ├── ai-overlay/    # 字段级 AI 浮层
│       │   ├── form-ai-status/# 表单级 AI 状态汇总
│       │   ├── form-ai-toolbar/# 表单级 AI 工具栏
│       │   └── ai-state-flow/ # AI 状态流程可视化
│       ├── src/               # composables + 共享类型
│       ├── lowcode-agent/     # 低代码/AI 生成元数据独立入口
│       ├── styles/            # Tailwind + Design Tokens
│       └── index.ts
├── playground/                # 约 70+ 演示路由/页面
├── docs/                      # 项目文档与扫描分析
├── scripts/                   # 构建/发布脚本
└── package.json

AI 增强能力

AI API 按基础控件、复合表单项、表单级编排分为三层，完整协议见 docs/ai-api-layering.md。核心边界：基础控件使用 ai?: AiConfig，复合表单项使用 ai?: boolean + resolver/prompt 等字段级 props，表单级 AI 通过 toolbar/status/registry 聚合编排。

| 层级 | 模块 | 职责 | |------|------|------| | 基础控件 AI | TfInput / TfTextArea / TfSelect 等 | 独立控件 AI，API 为 ai?: AiConfig，仅对象形态启用；不接收 FormItem/FormField 的 boolean ai 透传。 | | 字段级 AI | useAiStateMachine / useFormAi / TfAiOverlay | 字段旁触发 AI 生成、识别、检查、润色、翻译等动作，resolver 由业务注入，组件不绑定具体模型或业务接口。 | | 表单级 AI | TfFormAiToolbar / TfFormAiStatus / useFormAiRegistry | 通过 Registry 聚合字段状态，支持一键识别、批量应用、确认、检查、拒绝等表单级操作。 | | 可视化 | TfAiStateFlow | 展示 AI 状态流转，便于演示、调试与解释生成过程。 | | 低代码/AI 元数据 | @tongfun/ui/lowcode-agent | 独立入口导出组件注册表，描述组件、props、slots、AI 能力和容器关系。 |

顶层导出包含 useAiStateMachine、useFormAi、useFormAiRegistry，可按需在业务或低代码运行时中直接引用。

字段级示例：

<TfFormInput
  v-model="form.title"
  label="标题"
  ai
  :ai-resolver="callAiApi"
  ai-prompt="改写为正式公文风格"
/>

开发原则

1. 通用优先：组件面向低代码拖拽生成页面，避免为单一页面写死结构、文案或数据。
2. 参数化配置：业务差异优先通过 props、slots、事件、composables 和 Design Tokens 表达。
3. 类型优先：全量 TypeScript，公开 API 尽量提供类型定义。
4. 主题可定制：Tailwind CSS 与 CSS Variables / Design Tokens 协同，支持品牌与场景定制。
5. AI 解耦：AI 能力只定义交互、状态和扩展点，真实推理通过 resolver / registry / lowcode-agent 注入。

当前能力概览

• 基础 UI、表单、布局、导航、反馈、数据展示等组件物料。
• 表单字段级 AI 与表单级 AI Toolbar / Status / Registry。
• AiOverlay、AiStateFlow、useAiStateMachine 等 AI 交互基础设施。
• lowcode-agent 独立入口，为低代码拖拽与 AI 生成页面提供组件元数据。
• Playground 覆盖约 70+ 演示路由/页面，用于验证组件用法与组合能力。