joyco-lab

JOYCO Lab — 实验隔离与发布

自动完成完整工作流：从任意代码库中提取独立实验，使用合适的 JOYCO 模板搭建项目、安装依赖、部署到 Vercel，并发布到 JOYCO Lab 注册表。

---

前置条件清单

开始前，请确认用户的环境中具备以下条件：

• 已安装 joyco CLI（joyco --version）
• 已安装 vercel CLI（vercel --version）
• 已配置 GitHub 身份验证（joyco lab 用它来创建 PR）
• 用户已登录 Vercel（vercel whoami）

如果缺少任何一项，请告知用户并停止操作——此工作流依赖所有这些条件。

---

步骤 1 — 了解实验

阅读用户指定的代码。确定：

1. 它的作用 — 用一句话描述（你将用在 Lab 条目中）
2. 它的类型 — 使用下表选择模板
3. 它所需的依赖项 — 扫描导入项，记录模板基线中没有的依赖项

模板选择指南

代码中的信号	要使用的模板
three、@react-three/fiber、@react-three/drei、WebGLRenderer、OrbitControls、canvas 3D	3d
gsap、ScrollTrigger、@studio-freight/lenis、framer-motion、CSS 关键帧、SVG 动画、canvas 2D 绘图	motion

如果实验同时包含两者（例如，用 GSAP 为 Three.js 场景制作动画），优先选择 3d，并注明 GSAP 依赖项。

如果确实无法判断，请在继续前询问用户。

---

步骤 2 — 为实验命名

根据实验的作用拟定一个易读的名称。规则：

• 使用自然的标题式大小写，无需转换为 slug（CLI 会处理）
• 简短（最多 2–4 个词）
• 具有描述性，避免泛泛而谈（❌ Cool Animation ✅ Magnetic Cursor Trail）

提出名称，并在运行任何命令前征得用户确认。

---

步骤 3 — 使用 JOYCO CLI 搭建项目

joyco create --template <template-value> <experiment-name>

示例：

joyco create --template motion "Magnetic Cursor Trail"

这会创建一个新目录 <experiment-name>/，并在其中搭建模板项目。进入该目录后再执行后续步骤。

---

步骤 4 — 移植实验代码

1. 确定所需的最少文件集，包括入口文件、着色器、辅助文件和资源
2. 将它们复制到搭建好的项目中，并遵循模板的文件结构（通常是 src/ 或 app/）
3. 将实验接入模板的入口文件（通常是 src/main.ts、src/index.tsx 或 app/page.tsx——请检查模板）
4. 不要移入无关代码、全局状态、路由或后端依赖项

---

步骤 5 — 安装缺失的依赖项

将实验的导入项与模板已有内容进行比较。

检测包管理器

检查搭建好的模板中包含哪个锁文件，并使用相应的包管理器：

找到的锁文件	包管理器
bun.lockb 或 bun.lock	bun
pnpm-lock.yaml	pnpm
yarn.lock	yarn
package-lock.json	npm

如果存在多个锁文件，优先选择上表中最先匹配的项。如果没有锁文件，则默认使用 npm。

安装并验证

对于每个缺失的包，使用检测到的包管理器进行安装：

cd <experiment-name> && <pm> install <package>
# e.g. bun add three, pnpm add three, yarn add three, npm install three

然后运行开发服务器，确认没有导入错误：

<pm> run dev

继续之前，请先修复所有问题。常见问题包括：

• 缺少类型包（@types/three 等）
• 对等依赖不匹配
• 模板所假定的打包工具功能与实验的使用方式不同

---

步骤 6 — 部署到 Vercel

询问用户是否要立即部署到 Vercel。 如果用户拒绝，请跳至步骤 7——他们可以稍后部署，并在运行 joyco lab 时手动提供 URL。

如果用户确认，请在实验目录中运行：

vercel --prod

如果是首次部署，请按照提示操作（关联组织，将项目名称设为实验 slug）。复制生产环境 URL——你将在 Lab 条目中使用它。

---

步骤 7 — 发布到 JOYCO Lab

运行发布命令并按交互式提示操作：

joyco lab

CLI 会询问以下信息：

字段	需要提供的内容
名称	易于理解的标题（例如“磁性光标轨迹”）
描述	用一到两句话介绍它是什么，以及技术上有哪些有趣之处
标签	用逗号分隔（例如 gsap, cursor, magnetic, interaction）——请参阅下方的标签指南
预览链接	步骤 6 中的 Vercel 生产环境 URL
预览图片	可选——如果已生成 OG 图片或截图，请提供其 URL

CLI 会在 joyco-studio/lab 中创建一个 PR，将条目添加到 experiments.json。查看它输出的 PR URL，并分享给用户。

标签指南

请统一使用以下标签：

• 按类型： 3d、animation、interaction、shader、canvas、scroll、physics、generative
• 按库： three、gsap、r3f、framer-motion、lenis、matter-js
• 按视觉风格： typography、cursor、particles、geometry、noise、fluid

选择 3–6 个标签。不要添加过多标签。

---

步骤 8 — 收尾

告知用户：

1. 实验目录的位置
2. Vercel 在线 URL
3. Lab 注册表条目的 GitHub PR URL
4. 他们可能想要的后续操作：合并 PR、添加预览图片、在社交媒体上推广

---

特殊情况

实验使用私有/内部软件包： 停下来并告知用户。要让实验成为独立的公开仓库，必须先将依赖设为公开、内联或替换。

实验需要后端/API： 将范围缩小到仅包含前端视觉部分，或询问用户是否希望使用模拟数据。Lab 实验应完全采用静态/客户端实现。

用户想跳过 Vercel 部署： 他们可以提供其他 href 给 joyco lab——只需说明 Hub 会在 iframe 中渲染该链接，因此它必须是可公开访问的 URL。

没有明确匹配的模板： 询问用户。如果确实存在歧义，就不要猜测——选错模板会浪费设置时间。