01.4 Artifacts 工件深度用法

[Artifacts] (工件) 把对话变成了可运行的交付物面板。

读完你能做什么：可靠地触发工件、知道可以 import 哪些库、避开会导致工件白屏的陷阱。

一、什么是 Artifact

普通回复是一段文本；[Artifacts] (工件) 是一个独立的、可迭代编辑的文件，显示在对话右侧面板中，可预览、可下载、可跨轮次修改。

1.1 会渲染的文件类型

类型	扩展名	渲染效果
Markdown	`.md`	富文本预览
HTML	`.html`	直接运行（含 JS/CSS）
React	`.jsx`	实时渲染组件
Mermaid	`.mermaid`	流程图/时序图
SVG	`.svg`	矢量图
PDF	`.pdf`	内嵌预览

其他类型（.py、.json、.csv 等）也能作为工件生成和下载，只是不带预览渲染。

二、可靠触发工件的方法

工件不是每次都会自动出现。触发规则大致是「内容具备独立性且值得复制到对话之外」。

2.1 会触发的

原创的长文写作（文章、报告、邮件、方案）
完整的代码文件（超过约 10 行）
可交互的原型、图表、计算器
结构化文档（含标题层级、超过 20 行的 Markdown）

2.2 不会触发的

列表、排名、对比（无论多长）
剧情概述、内容解释
对话式的解答
短代码片段

2.3 强制触发

如果你需要它，直接说：

text

把结果生成为一个 artifact，文件名 report.md

text

生成一个单文件 HTML artifact，实现一个带排序和筛选的表格组件。
所有 CSS 和 JS 内联在同一个文件里。

三、React 工件的技术约束（重要）

这是踩坑最多的地方。React 工件运行在一个受限沙箱中。

3.1 可用的库

jsx

import { useState, useEffect, useMemo } from "react";
import { Camera, ChevronDown } from "lucide-react";           // 图标 v0.383.0
import { LineChart, XAxis, YAxis, Tooltip } from "recharts";  // 图表
import * as math from "mathjs";                                // 数学
import _ from "lodash";                                        // 工具函数
import * as d3 from "d3";                                      // 数据可视化
import * as Plotly from "plotly";                              // 交互图表
import * as THREE from "three";                                // 3D (r128)
import * as Chart from "chart.js";                             // 图表
import * as Tone from "tone";                                  // 音频
import Papa from "papaparse";                                  // CSV 解析
import * as XLSX from "xlsx";                                  // Excel 读写（SheetJS）
import * as mammoth from "mammoth";                            // docx 转换
import * as tf from "tensorflow";                              // 机器学习

shadcn/ui 也可用：

jsx

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

3.2 三条铁律

铁律 1：禁止使用任何浏览器存储 API

jsx

// ❌ 会导致工件直接失败
localStorage.setItem("key", "value");
sessionStorage.getItem("key");

// ✅ 用 React state 代替
const [data, setData] = useState({});

这是最常见的工件白屏原因。沙箱不提供 localStorage / sessionStorage。

铁律 2：Tailwind 只能用核心工具类

沙箱里没有 Tailwind 编译器，只有预编译的基础样式表。

jsx

// ❌ 任意值语法不生效
<div className="w-[437px] text-[#1a2b3c]">

// ✅ 用预设类
<div className="w-96 text-slate-800">

// ✅ 需要精确值时用内联 style
<div style={{ width: 437, color: "#1a2b3c" }}>

铁律 3：组件不能有必填 props

jsx

// ❌ 无法渲染
export default function Chart({ data }) { ... }

// ✅ 给默认值
export default function Chart({ data = SAMPLE_DATA }) { ... }

3.3 Three.js 的版本陷阱

沙箱固定使用 r128。以下 API 在 r128 中不存在：

不可用	替代方案
`THREE.CapsuleGeometry`（r142+）	用 `CylinderGeometry` + 两个 `SphereGeometry` 组合
`THREE.OrbitControls`	不在 CDN 中，需手写简易相机控制

正确的 CDN 地址：

text

https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js

四、HTML 工件

比 React 更灵活，适合做完整页面或需要非标准库的场景。

html

<!-- 单文件：HTML + CSS + JS 全部内联 -->
<div id="app"></div>
<style>
  #app { font-family: system-ui; padding: 2rem; }
</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/chart.js/4.4.0/chart.umd.min.js"></script>
<script>
  // 你的逻辑
</script>

外部脚本只能从 https://cdnjs.cloudflare.com 引入。 其他 CDN 会被阻断。

五、迭代编辑的正确姿势

工件的核心价值在于可以持续修改而不重新生成整个文件。

5.1 精确指令 vs 模糊指令

text

❌ 「改得好看一点」
   → 可能整体重写，你满意的部分也被改掉

✅ 「只修改 header 部分：把背景色改成深灰 #1f2937，字体加大到 24px。
    其他部分不要动。」
   → 定点修改

5.2 分阶段构建复杂工件

不要一次要求一个 500 行的复杂应用。分阶段：

text

第 1 轮：先做一个静态布局，三栏结构，用假数据填充，不要任何交互逻辑。
第 2 轮：现在给左栏加上筛选功能。
第 3 轮：把假数据换成从 props 传入，并给出示例数据结构。

理由：一次生成的代码量越大，出错概率越高，而且出错时你很难定位是哪一块的问题。

六、常见故障排查

症状	最可能的原因	修复
工件白屏	用了 `localStorage`	换成 `useState`
样式完全不生效	用了 Tailwind 任意值语法 `w-[437px]`	换预设类或内联 style
组件不渲染	有必填 props / 没有 `export default`	补默认值和默认导出
图标不显示	`lucide-react` 图标名拼错	图标名是 PascalCase，如 `ChevronDown`
3D 场景报错	用了 r128 之后才有的 API	换等价实现
外部库加载失败	用了非 cdnjs 的 CDN	改用 cdnjs，或内联该库代码
内容没变成工件	内容属于"列表/解释"类	显式要求「生成为 artifact」

七、被低估的用法

7.1 用 Mermaid 工件快速画架构图

text

根据我刚才描述的系统，生成一个 mermaid artifact，画出服务间调用关系。
用 flowchart LR 方向，把外部依赖标成虚线框。

7.2 用 HTML 工件做一次性数据处理工具

text

生成一个 HTML artifact：我粘贴一段 CSV 进去，它帮我按第 3 列去重，
输出结果并提供下载按钮。全部在浏览器本地处理，不发送任何数据。

7.3 用 Markdown 工件写长文档

Markdown 工件可以直接下载为 .md 文件，比从对话里复制粘贴保真度高得多（对话中的格式在复制时经常丢失）。

八、Artifact 的局限

局限	说明	替代方案
无法访问你的本地文件	沙箱隔离	用 Cowork 或 Claude Code
无法发起真实网络请求到任意域名	安全限制	在本地环境运行代码
无持久化存储	刷新即丢失	数据下载到本地
单文件	不能拆成多模块	复杂项目用 Claude Code

一旦你的需求超出这些边界，就该切换入口。见 01.1 产品矩阵与形态选择。

01.4 Artifacts 工件深度用法 ​

一、什么是 Artifact ​

1.1 会渲染的文件类型 ​

二、可靠触发工件的方法 ​

2.1 会触发的 ​

2.2 不会触发的 ​

2.3 强制触发 ​

三、React 工件的技术约束（重要） ​

3.1 可用的库 ​

3.2 三条铁律 ​

铁律 1：禁止使用任何浏览器存储 API ​

铁律 2：Tailwind 只能用核心工具类 ​

铁律 3：组件不能有必填 props ​

3.3 Three.js 的版本陷阱 ​

四、HTML 工件 ​

五、迭代编辑的正确姿势 ​

5.1 精确指令 vs 模糊指令 ​

5.2 分阶段构建复杂工件 ​

六、常见故障排查 ​

七、被低估的用法 ​

7.1 用 Mermaid 工件快速画架构图 ​

7.2 用 HTML 工件做一次性数据处理工具 ​

7.3 用 Markdown 工件写长文档 ​

八、Artifact 的局限 ​

延伸阅读 ​

01.4 Artifacts 工件深度用法

一、什么是 Artifact

1.1 会渲染的文件类型

二、可靠触发工件的方法

2.1 会触发的

2.2 不会触发的

2.3 强制触发

三、React 工件的技术约束（重要）

3.1 可用的库

3.2 三条铁律

铁律 1：禁止使用任何浏览器存储 API

铁律 2：Tailwind 只能用核心工具类

铁律 3：组件不能有必填 props

3.3 Three.js 的版本陷阱

四、HTML 工件

五、迭代编辑的正确姿势

5.1 精确指令 vs 模糊指令

5.2 分阶段构建复杂工件

六、常见故障排查

七、被低估的用法

7.1 用 Mermaid 工件快速画架构图

7.2 用 HTML 工件做一次性数据处理工具

7.3 用 Markdown 工件写长文档

八、Artifact 的局限

延伸阅读