designer-skills

LlamaFarm 的 Designer 技能

针对 Designer 子系统的框架专属模式和检查清单（React 18 + TanStack Query + TailwindCSS + Radix UI）。

概述

Designer 是一个基于浏览器的项目工作台，用于构建 AI 应用。它提供配置编辑、聊天测试、数据集管理、RAG 配置和模型选择功能。

技术栈

技术	版本	用途
React	18.2	启用 StrictMode 的 UI 框架
TypeScript	5.2+	类型安全
TanStack Query	v5	服务端状态管理
TailwindCSS	3.3	实用优先的 CSS
Radix UI	1.x	无障碍组件基础
Vite	6.x	构建工具和开发服务器
React Router	v7	客户端路由
Vitest	1.x	测试框架
axios	1.x	HTTP 客户端
framer-motion	12.x	动画

目录结构

designer/src/
  api/          # API service modules (axios-based)
  assets/       # Static assets and icons
  components/   # Feature-organized React components
    ui/         # Radix-based primitive components
  contexts/     # React Context providers
  hooks/        # Custom hooks (TanStack Query wrappers)
  lib/          # Utilities (cn, etc.)
  types/        # TypeScript type definitions
  utils/        # Helper functions
  test/         # Test utilities, factories, mocks

前置要求：共享技能

在应用 Designer 专属模式之前，请确保符合以下要求：

• TypeScript 技能 - 严格类型、模式、安全性
• React 技能 - 组件模式、钩子、状态管理

框架专属指南

指南	描述
tanstack-query.md	查询/变更模式、缓存、失效处理
tailwind.md	TailwindCSS 模式、主题化、响应式设计
radix.md	Radix UI 组件模式、无障碍性
performance.md	前端优化、包体积、延迟加载

关键模式

API 客户端配置

// Centralized client with interceptors
export const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: { 'Content-Type': 'application/json' },
  timeout: 60000,
})

// Error handling interceptor
apiClient.interceptors.response.use(
  response => response,
  (error: AxiosError) => {
    if (error.response?.status === 422) {
      throw new ValidationError('Validation error', error.response.data)
    }
    throw new NetworkError('Request failed', error)
  }
)

查询客户端配置

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,
      gcTime: 5 * 60_000,
      retry: 2,
      retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30_000),
      refetchOnWindowFocus: false,
    },
    mutations: { retry: 1 },
  },
})

类名合并工具

// lib/utils.ts - Always use cn() for Tailwind classes
import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

主题提供程序模式

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

// Apply via Tailwind dark mode class strategy
useEffect(() => {
  document.documentElement.classList.toggle('dark', theme === 'dark')
}, [theme])

组件约定

功能组件

• 位于 components/{Feature}/ 目录中
• 每个文件包含一个组件，并以组件名称命名
• 与功能专属类型和工具放在一起

UI 基础组件

• 位于 components/ui/
• 使用 Tailwind 样式封装 Radix UI 基础组件
• 使用 forwardRef 转发 ref
• 为 DevTools 设置 displayName

图标

• 位于 assets/icons/
• 接受 SVG 属性的函数组件
• 标准图标使用 lucide-react

测试

// Use MSW for API mocking
import { server } from '@/test/mocks/server'
import { renderWithProviders } from '@/test/utils'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

test('renders with query data', async () => {
  renderWithProviders(<MyComponent />)
  await screen.findByText('Expected text')
})

检查清单摘要

类别	严重	高	中	低
TanStack Query	3	4	3	2
TailwindCSS	2	3	4	2
Radix UI	3	3	2	1
性能	2	4	3	2