web-artifact-studio

|---| | 交互式演示 | 演示需求 + 交互逻辑 | React 应用 + 事件处理 + 可点击演示 | | 数据仪表盘 | 数据源 + 图表需求 + 过滤器 | 状态管理仪表盘 + 图表 + 交互筛选 | | 表单工作流 | 表单字段 + 校验规则 + 分步 | 多步表单 + 路由 + 状态校验 | | 组件展示 | 设计系统/组件库 | shadcn/ui 组件预览 + 代码示例 | | 单页应用原型 | 页面结构 + 路由 | SPA + 路由 + 状态 + 持久化 | 不适用于:

• 简单单文件 HTML(无状态/无路由,直接写 HTML 即可)
• 完整生产级 Web 应用(需要后端、数据库、认证等,使用 Next.js/Nuxt)
• 移动端原生 App(使用 React Native/Flutter)
• 桌面应用(使用 Electron/Tauri)
• 静态文档站点(使用 VitePress/Docusaurus)
• 大型电商网站(需要完整架构,非单工件)

操作步骤

Step 1: 需求分析

1. 明确工件目标:展示什么?交互什么?数据从哪来?
2. 复杂度评估:
   • 简单展示 → 单文件 HTML 即可
   • 需要状态/路由/多组件 → 使用本工作室
3. 技术选型确认:React 18 + TypeScript + Tailwind + shadcn/ui
4. 交付模式选择:Vite 多文件 / 单 HTML 文件(内联)

Step 2: 项目搭建

1. 目录结构:

参数说明

artifact/
├── index.html          # 入口
├── src/
│   ├── main.tsx        # 挂载点
│   ├── App.tsx         # 根组件
│   ├── components/      # 业务组件
│   ├── ui/              # shadcn/ui 组件
│   ├── hooks/           # 自定义 Hook
│   ├── lib/             # 工具函数
│   └── styles/          # 全局样式
└── package.json

2. 依赖引入:React、Tailwind、shadcn/ui、按需引入图表/路由库
3. 构建配置:Vite 或内联打包

Step 3: 组件设计

1. 组件拆分:按职责拆分,单一职责
2. shadcn/ui 组合:优先使用 shadcn/ui 组件(Button/Card/Dialog/Table 等)
3. 状态管理:
   • 局部状态:useState
   • 跨组件:Context 或 Zustand
   • 持久化:localStorage
4. 路由:React Router(如需多页面)

Step 4: 样式与交互

1. Tailwind 优先:用工具类,少写自定义 CSS
2. 响应式:移动优先,sm/md/lg/xl 断点
3. 无障碍:语义化 HTML、ARIA 标签、键盘导航
4. 动效:CSS transition / Framer Motion(按需)

Step 5: 打包与交付

1. 构建产物:单 HTML 文件(内联 JS/CSS)或多文件
2. 资源处理:图片转 base64 或 CDN
3. 可移植性:确保工件可独立运行,无外部依赖
4. 验证:在浏览器中打开测试,确认功能正常

设计原则

1. 组件化:一切皆组件,可复用可组合
2. 类型安全:TypeScript,props 有类型定义
3. 无障碍优先:WCAG 2.1 AA 合规
4. 性能考虑:懒加载、虚拟列表(长数据)
5. 避免过度工程:工件不是产品,够用即可

示例展示

示例1: 数据仪表盘工件(输入→输出)

输入:

需求: 销售数据仪表盘
数据: JSON 数组(产品/销售额/地区/月份)
功能: 1) 柱状图展示月度销售 2) 表格展示明细 3) 筛选器按地区过滤
交付: 单 HTML 文件

输出(目录结构 + 关键代码):

artifact/
├── index.html
├── src/
│   ├── main.tsx
│   ├── App.tsx              # 主组件 + 状态
│   ├── components/
│   │   ├── SalesChart.tsx   # 图表组件
│   │   ├── DataTable.tsx    # 表格组件
│   │   └── RegionFilter.tsx # 筛选器
│   └── data/sales.json      # 模拟数据
└── package.json
tsx
// App.tsx 核心代码
import { useState, useMemo } from 'react';
import { Card, CardHeader, CardContent } from '@/ui/card';
import { Select, SelectContent, SelectItem } from '@/ui/select';
import { SalesChart } from './components/SalesChart';
import { DataTable } from './components/DataTable';
import salesData from './data/sales.json';
export default function App() {
  const [region, setRegion] = useState<string>('all');
  const filteredData = useMemo(() => {
    if (region === 'all') return salesData;
    return salesData.filter(item => item.region === region);
  }, [region]);
  return (
    <div className="p-6 space-y-6">
      <h1 className="text-2xl font-bold">销售数据仪表盘</h1>
      <Select value={region} onValueChange={setRegion}>
        <SelectContent>
          <SelectItem value="all">全部地区</SelectItem>
          <SelectItem value="华东">华东</SelectItem>
          <SelectItem value="华北">华北</SelectItem>
        </SelectContent>
      </Select>
      <Card>
        <CardHeader>月度销售趋势</CardHeader>
        <CardContent>
          <SalesChart data={filteredData} />
        </CardContent>
      </Card>
      <Card>
        <CardHeader>销售明细</CardHeader>
        <CardContent>
          <DataTable data={filteredData} />
        </CardContent>
      </Card>
    </div>
  );
}

示例2: 多步表单工件(输入→输出)

输入:

需求: 用户注册多步表单
步骤: 1)基本信息 2)联系方式 3)确认提交
校验: 必填、邮箱格式、手机号格式
交付: 单 HTML 文件 + 状态持久化(localStorage)

输出(关键代码):

// MultiStepForm.tsx
import { useState } from 'react';
import { Button } from '@/ui/button';
import { Input } from '@/ui/input';
import { Label } from '@/ui/label';
const STEPS = ['基本信息', '联系方式', '确认提交'];
export function MultiStepForm() {
  const [step, setStep] = useState(0);
  const [formData, setFormData] = useState(() => {
    const saved = localStorage.getItem('form-data');
    return saved ? JSON.parse(saved) : { name: '', email: '', phone: '' };
  });
  const updateField = (field: string, value: string) => {
    const newData = { ...formData, [field]: value };
    setFormData(newData);
    localStorage.setItem('form-data', JSON.stringify(newData));
  };
  const next = () => step < STEPS.length - 1 && setStep(step + 1);
  const prev = () => step > 0 && setStep(step - 1);
  return (
    <div className="max-w-md mx-auto p-6">
      <div className="flex gap-2 mb-6">
        {STEPS.map((s, i) => (
          <div key={i} className={`flex-1 h-2 rounded ${i <= step ? 'bg-blue-500' : 'bg-gray-200'}`} />
        ))}
      </div>
      <h2 className="text-xl font-bold mb-4">{STEPS[step]}</h2>
      {step === 0 && (
        <div className="space-y-4">
          <div>
            <Label>姓名</Label>
            <Input value={formData.name} onChange={e => updateField('name', e.target.value)} />
          </div>
      )}
      {step === 1 && (
        <div className="space-y-4">
          <div>
            <Label>邮箱</Label>
            <Input type="email" value={formData.email} onChange={e => updateField('email', e.target.value)} />
          </div>
          <div>
            <Label>手机号</Label>
phone} onChange={e => updateField('phone', e.target.value)} />
          </div>
      )}
      {step === 2 && (
        <div className="space-y-2">
          <p>姓名: {formData.name}</p>
          <p>邮箱: {formData.email}</p>
          <p>手机: {formData.phone}</p>
        </div>
      )}
      <div className="flex justify-between mt-6">
        <Button variant="outline" onClick={prev} disabled={step === 0}>上一步</Button>
        {step < STEPS.length - 1 ? (
          <Button onClick={next}>下一步</Button>
        ) : (
          <Button onClick={() => alert('提交成功!')}>提交</Button>
        )}
      </div>
  );
}

示例3: 单文件交付构建(输入→输出)

输入:

需求: 将 React 工件打包为单 HTML 文件,无外部依赖
工具: Vite + vite-plugin-singlefile

输出(配置代码):

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteSingleFile } from 'vite-plugin-singlefile';
// ...
export default defineConfig({
  plugins: [react(), viteSingleFile()],
  build: {
    target: 'esnext',
    assetsInlineLimit: 100000000, // 100MB,内联所有资源
    cssCodeSplit: false,
    rollupOptions: {
      output: {
        inlineDynamicImports: true,
      },
});
bash
npm run build

异常处理指引

运行环境

运行环境

• Agent平台: Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持SKILL.md的任意Agent
• 操作系统: Windows / macOS / Linux
• 运行时: Node.js 18+ + npm/pnpm

第三方依赖

API Key 配置

• 本Skill无需额外API Key配置
• 安全要求:
  • 工件中不硬编码任何 API Key 或敏感凭证
  • 如需调用外部 API,通过环境变量注入(VITE_ 前缀)
  • 构建产物中不包含 .env 文件

可用性分类

• 分类: MD+EXEC
• 说明: 纯Markdown方法论,需 exec 能力运行 npm/Vite 命令

案例展示

以下案例展示了skill的工作流程和预期输出效果，由LLM按照skill定义的流程生成。

案例1: 销售数据仪表盘(Zustand全局状态+Recharts图表+筛选器)

输入:

需求: 销售数据仪表盘工件
数据: JSON数组(产品/销售额/地区/月份/同比增长)
功能:
  1) 柱状图展示月度销售趋势
  2) 数据表格展示明细(支持排序)
  3) 地区筛选器+产品筛选器联动
  4) KPI卡片展示总销售额/平均增长率/最高地区
交付: 单HTML文件(Vite打包)

LLM生成输出 (output/sales-dashboard/src/App.tsx):

import { useState, useMemo } from 'react';
import { create } from 'zustand';
import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, CartesianGrid } from 'recharts';
import { Card, CardHeader, CardContent, CardTitle } from '@/ui/card';
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/ui/select';
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/ui/table';
// Zustand 全局状态
interface DashboardStore {
  region: string;
  product: string;
  setRegion: (r: string) => void;
  setProduct: (p: string) => void;
}
const useDashboardStore = create<DashboardStore>((set) => ({
  region: 'all',
  product: 'all',
  setRegion: (r) => set({ region: r }),
  setProduct: (p) => set({ product: p }),
}));
// KPI 卡片组件
function KPICard({ title, value, subtitle }: { title: string; value: string; subtitle: string }) {
  return (
    <Card>
      <CardHeader><CardTitle className="text-sm text-gray-500">{title}</CardTitle></CardHeader>
      <CardContent>
        <div className="text-2xl font-bold">{value}</div>
        <div className="text-xs text-gray-400 mt-1">{subtitle}</div>
      </CardContent>
    </Card>
  );
}
export default function App() {
  const { region, product, setRegion, setProduct } = useDashboardStore();
  const filteredData = useMemo(() => {
      (region === 'all' || item.region === region) &&
      (product === 'all' || item.product === product)
    );
  }, [region, product]);
  // KPI 计算
  const totalSales = filteredData.reduce((sum, d) => sum + d.amount, 0);
  const avgGrowth = filteredData.length > 0
    ? (filteredData.growthRate, 0) / filteredData.length).toFixed(1)
    : '0';
  const topRegion = useMemo(() => {
    const regionMap: Record<string, number> = {};
    filteredData.forEach(d => { regionMap[d.region] = (regionMap[d.region] || 0) + d.amount; });
    return Object.entries(regionMap).sort((a, b) => b[1] - a[1])[0]?.[0] || '-';
  }, [filteredData]);
  // 图表数据(按月份聚合)
  const chartData = useMemo(() => {
    const monthMap: Record<string, number> = {};
    filteredData.forEach(d => { monthMap[d.month] = (monthMap[d.month] || 0) + d.amount; });
    return Object.entries(monthMap).map(([month, amount]) => ({ month, amount }));
  }, [filteredData]);
  return (
    <div className="p-6 space-y-6 max-w-6xl mx-auto">
      <h1 className="text-2xl font-bold">销售数据仪表盘</h1>
      {/* KPI 卡片 */}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        <KPICard title="总销售额" value={`¥${totalSales.toLocaleString()}`} subtitle={`${filteredData.length} 条记录`} />
        <KPICard title="平均增长率" value={`${avgGrowth}%`} subtitle="同比" />
        <KPICard title="最高地区" value={topRegion} subtitle="按销售额" />
      </div>
      {/* 筛选器 */}
      <div className="flex gap-4">
        <Select value={region} onValueChange={setRegion}>
          <SelectTrigger className="w-40"><SelectValue 示例值="选择地区" /></SelectTrigger>
          <SelectContent>
            <SelectItem value="all">全部地区</SelectItem>
            <SelectItem value="华东">华东</SelectItem>
            <SelectItem value="华北">华北</SelectItem>
            <SelectItem value="华南">华南</SelectItem>
          </SelectContent>
        </Select>
        <Select value={product} onValueChange={setProduct}>
          <SelectTrigger className="w-40"><SelectValue 示例值="选择产品" /></SelectTrigger>
          <SelectContent>
            <SelectItem value="all">全部产品</SelectItem>
            <SelectItem value="产品A">产品A</SelectItem>
            <SelectItem value="产品B">产品B</SelectItem>
            <SelectItem value="产品C">产品C</SelectItem>
          </SelectContent>
        </Select>
      </div>
      {/* 图表 */}
      <Card>
        <CardHeader><CardTitle>月度销售趋势</CardTitle></CardHeader>
        <CardContent>
          <ResponsiveContainer width="100%" height={300}>
            <BarChart data={chartData}>
              <CartesianGrid strokeDasharray="3 3" />
              <XAxis dataKey="month" />
              <YAxis />
              <Tooltip formatter={(v: number) => `¥${v.toLocaleString()}`} />
              <Bar dataKey="amount" fill="#1a56db" radius={[4, 4, 0, 0]} />
            </BarChart>
          </ResponsiveContainer>
        </CardContent>
      </Card>
      {/* 数据表格 */}
      <Card>
        <CardHeader><CardTitle>销售明细</CardTitle></CardHeader>
        <CardContent>
          <Table>
            <TableHeader>
              <TableRow>
                <TableHead>产品</TableHead>
                <TableHead>地区</TableHead>
                <TableHead>月份</TableHead>
                <TableHead className="text-right">销售额</TableHead>
                <TableHead className="text-right">增长率</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              {filteredData.map((item, i) => (
                <TableRow key={i}>
                  <TableCell>{item.product}</TableCell>
                  <TableCell className="text-right">¥{item.amount.toLocaleString()}</TableCell>
                  <TableCell className={`text-right ${item.growthRate >= 0 ? 'text-green-600' : 'text-red-600'}`}>
                    {item.growthRate >= 0 ? '+' : ''}{item.growthRate}%
                  </TableCell>
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </CardContent>
      </Card>
    </div>
  );
}

效果验证: ✓Zustand全局状态管理(地区+产品双筛选器) ✓useMemo性能优化(筛选/KPI/图表数据缓存) ✓Recharts柱状图含网格/坐标轴/Tooltip ✓3个KPI卡片(总销售/增长率/最高地区) ✓shadcn/ui Table组件展示明细含正负增长率着色 ✓响应式布局(grid-cols-1 md:grid-cols-3)

疑问解答集锦

Q1: Web工件工作室支持哪些输入格式？

A1: React+Tailwind+shadcn构建复杂交互Web工件,状态路由组件全搞定。Web工件工作室——用现代前端技术栈(React/TypeScript/T。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

安全提示

安全风险防范

故障处理体系

针对Web工件工作室使用中可能遇到的常见问题,提供以下排查方案:

Web工件工作室通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

注: 本SKILL.md超过500行上限, 已截断尾部非核心章节以满足L1格式要求。完整内容见版本库历史。

用户问题解答

首次设置

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

Q1: 本技能支持哪些输入格式？

能力速览

• 自动化执行: 基于指令驱动的自动化流程
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

使用场景

适用于需要专业工具支持的开发、运维和内容创作场景。

• 开发者日常工具调用
• 团队协作中的自动化处理
• 内容生产与格式转换

Q1: Web Artifact Studio支持哪些输入格式？

A1: Web Artifact Studio专业技能工具。