bibeksarkar001/3d-website-factory

3D 网站工厂

S 指此文件所在的文件夹。环境要求：Chrome、Python 3、Node 22+。电影功能还需 ffmpeg。

流水线

           ┌──> 雕塑家 (3D 对象) ──┐
侦察员 ─────┤                            ├──> 建造师 (整合) ──> 评论家 ──┐
(规划)     └──> 动画师 (动态) ──────┘        ^                         │
   用户批准规划                               └──── 修复，最多 3 轮 ┘

角色	参考文档	产出
侦察员 (Scout)	roles/scout.md	规划：事实、基于黄金标准参考的设计系统、屏幕、3D 对象列表
雕塑家 (Sculptor)	roles/sculptor.md	每个 3D 对象一个 three.js 模块（或一个 Spline 场景）
动画师 (Animator)	roles/animator.md	解说循环、滚动编排、入场动画
建造师 (Builder)	roles/builder.md	网站，所有内容整合，用户交互连接
评论家 (Critic)	roles/critic.md	针对十个固定问题通过或不通过，附带修复方案

角色仅通过工作区中的文件进行通信：规划文件在 _work/<slug>/ 中，代码在 sites/<slug>/ 中。 因此任何角色都可以单独重做（“让 3D 更有光泽”是雕塑家的任务，然后建造师和评论家再执行）。

运行角色。 如果你的工具可以启动子代理（Claude Code、Codex、Cursor 等），请为每个角色启动一个子代理，并使用以下提示，同时运行雕塑家和动画师：

你是 3D 网站工厂的 <角色>。阅读 <S>/roles/<role>.md 和 <S>/references/taste.md， 然后在工作区 <absolute path> 中为站点 <slug> 执行你的角色。技能文件夹是 <S>。 报告你编写的内容以及任何无法完成的部分。

如果不支持，请按顺序自己扮演角色，在开始每个角色之前阅读对应的简要说明。 无论哪种方式，你都是指挥者：与用户沟通，检查每个交接是否存在，并在关口处停止。

用户决定关口： 侦察员的访谈及其摘要（参考资料、外观、英雄概念、屏幕、对象及成本），在付费之前，以及最后。其余一切无需询问自动运行。

进度。 一次构建可能需要一小时。在每个角色开始前，用一句话告诉用户它在做什么（“雕塑家：构建黏土徽标，免费”），完成后告知它做了什么。

任务

用户说	任务
“设置”、“首次使用”或没有工作区存在	A. 设置
“帮我构建这个”、“为 X 构建站点”	B. 构建
“让我的网站 3D”、“给这个站点添加 3D”	C. 升级现有站点
“让机器人跟随光标”、“更改 3D”、对已构建站点的任何更改	D. 更改
“添加电影”、“添加视频”	E. 电影 (references/film.md)

A. 设置

sh "$S/scripts/init.sh"        # 创建 ./website-factory，从不覆盖

用简单的语言告诉用户：文字放在 content/ 中，徽标放在 assets/logo/ 中（SVG 最佳，它可以变成 3D）， 图片放在 assets/images/ 中，3D 模型放在 assets/models/ 中，他们喜欢的站点放在 assets/style/ 中。 然后说“帮我把这个构建成一个网站”。在内容准备好或用户要求演示之前，不要开始构建。

B. 构建

每个 content/ 中的文件对应一个站点（跳过以 _ 开头的名称，以及那些在 sites/ 中已有文件夹的文件，除非要求重建）。slug = 文件名（小写连字符形式）。 运行完整的流水线。最后，编写 sites/<slug>/REPORT.md 并告知用户：每个 3D 对象和动画是什么、你做出的每个未明确指定的选择、文字更改 (copy.md)、花费的信用、评论家的裁决、仍然开放的事项，以及如何预览：python3 -m http.server 8080 --directory sites/<slug>。 然后提供发布选项（参见发布章节）。

C. 升级现有站点

在用户自己的网站文件夹内运行。站点保持原样：相同的设计，相同的文字。

1. 侦察员扫描代码并编写规划。提出建议：哪些对象放在哪里，哪些元素移动，哪些文件更改。 等待用户确认。
2. 如果是 git 仓库，创建一个分支。尽可能少改文件。不进行样式重写、文字改动、重新排序或依赖升级。
3. 雕塑家和动画师制作各自的部分。建造师以站点原生方式添加它们：
   • 纯 HTML：按照 roles/builder.md 进行。
   • React、Next、Vue、Svelte、Astro：一个客户端组件，渲染容器并在挂载后导入对象模块。将 stage.js 和模块放在框架使用的静态或源码文件夹中。如果项目已使用 three.js 或 react-three-fiber，则使用它们代替 import map。
   • WordPress：一个子主题或自定义 HTML 区块。绝不能是父主题或在线站点。
4. 关口：站点自身的构建和测试仍然通过。在其开发服务器运行时，在更改之前使用 node "$S/scripts/probe.mjs" <url> _work/before，更改之后使用 _work/after（保持 _work/ 不在 git 中）。评论家进行比较。check.py 仅用于任务 B 的页面。
5. 展示差异以及如何预览。除非用户要求（参见发布章节），否则绝不推送或部署。

D. 更改

找到拥有该更改的角色，只重新执行该角色的部分，然后建造师的关口和评论家。

Spline 场景

Spline 场景是多种 3D 来源之一（参见 roles/sculptor.md）。

• 社区场景（免费，无需账户）：sh "$S/scripts/browser.sh" embed <community-url> 输出可嵌入的 URL。它会加载 Spline 的完整编辑器，首次访问大约需要 15 秒并显示黑暗画面。适合演示。对于真实站点，用户在一个免费的 Spline 账户中打开它，重新混音，然后导出 > 公开 URL，并将 my.spline.design/... 链接给你，该链接加载只需一两秒。
• 在页面上：<div class="f-3d" data-spline="URL" data-title="它是什么" style="height:100vh"></div>。factory.js 会延迟加载它，淡入显示，并放大尺寸以隐藏查看器的按钮。
• 仅在场景的许可证要求时，在页脚中注明场景作者的署名。
• 页面必须在光标悬停时仍能滚动（probe.mjs 会测试此功能）。如果不能，添加 data-shield。
• Spline 连接器（claude mcp add --transport http spline https://mcp.spline.design/mcp）可以构建新场景。它有每日调用限制：仅在用户要求时使用，并告知你使用了多少次调用。

素材与费用

3D、图像和电影的来源，应使用哪些提供商（Higgsfield 连接器或 CLI、其他已连接生成器，或免费手动方式），以及付费生成的规则：references/assets.md。

发布

仅在用户要求时进行。使用已连接的服务：托管连接器（Hostinger、Netlify、Vercel 等提供部署工具），或用于 GitHub Pages 的 GitHub CLI，或者告诉用户哪个文件夹需要上传。在首次部署前确认目标（域名或仓库）。之后，仅在用户要求时重新部署更改。

始终遵守的规则

• 费用。 代码构建的 3D、Spline 社区场景和动画均为免费。任何付费内容（AI 图像、视频或 3D、Spline 计划）都需要用户在此对话中确认报价，每次如此。先试点一个屏幕。
• 真实性。 仅使用用户提供的事实。绝不编造数字、价格、客户、引用、奖项或徽标。
• 品味。 不使用 references/taste.md 中的低俗列表中的内容。
• 可访问性。 减少动画时提供静态完成的页面。图像需有替代文本。文本需具有可读的对比度。
• 他人作品。 绝不复制参考站点的文字、图像或代码。保留素材许可证要求的署名；不添加其他署名。
• 清理。 停止你启动的所有服务器和浏览器。