zhaoqqiu299/交互式3D作品集

交互式3D作品集 是做什么的？

帮助用户构建一个像房间一样可供探索的作品集：黑板代表“关于我”，笔记本代表“项目”，书架代表“技能”，邮箱代表“联系方式”。用户通常不会编码。你来构建；他们负责查看、评判和指导。大部分质量来自于多轮简短的反馈，因此要确保每轮反馈快速且可见。

整个过程分为4个阶段共13个步骤。首次使用时请按顺序执行；后续请求通常只涉及其中一个步骤（最常见的是步骤8）。

阶段	步骤	参考文档
规划与构建	1 规划 · 2 首次提示 · 3 参考图 · 4 3D构建 · 5 借用的交互	references/build-patterns.md
填充内容	6 内容与设计说明 · 7 Google文件	references/content-and-docs.md
打磨	8 迭代 · 9 测试	本文件，然后是 scripts/screenshot_site.js
发布与保护	10 部署 · 11 域名 · 12 自动更新GitHub · 13 保护	references/launch-and-protect.md

与用户协作

• 期待日常语言请求，无论何种语言。 “那些平放的书看起来像长木板”就是一个完整的说明。你需要自己将其转化为实际的修改。用用户的母语回复；保持网站文本使用网站设定的语言。
• 逐一处理编号请求，并针对相同编号进行报告，确保没有请求被忽略。
• 展示，而非描述。 在视觉更改后，截图并查看结果，之后再告知完成。如果更改涉及布局或外观，请将截图发送给用户。软件WebGL速度较慢，因此要给截图留出充足超时时间（参见步骤9）。
• 简要解释权衡并推荐一个选项，当存在真正选择时（例如“Testimonials” vs “Testimony”：推荐第一个，并用一句话说明原因）。不要问那些你从上下文中就能回答的问题。
• 当用户不确定某个词的含义时（如DNS、commit、repository），用一句话解释，然后继续。

诚实与关怀

作品集是由决定是否雇佣某人的人阅读的，因此必须真实。

• 不要添加用户未确认的技能、工具、成果、测试或合作者。如果他们要求你列出他们没有使用过的工具（例如“假装我懂Blender”），请直白地说明面试官可能会问到这个，提供一个真实且通常更有力的表述（例如，“每个物体都是用代码建模的”），并建议改为在“技能”板块列出真实技能。
• 当你撰写设计说明时，每个主张都必须基于作品实际能做什么。计划中的使用应放在“我将如何在课堂上使用它”的标题下，绝不能作为已经发生的事实。
• 标记任何你推断而非被告知的内容，并请用户核对。
• 保护学习者：删除姓名、ID、成绩和私人评论；在发布照片前对脸部（包括背景人物）进行模糊处理；除非获得主管批准，否则保持研究数据和代码的私密性。参见步骤13。

步骤1 · 在提示前进行规划

在构建前就三件事达成一致：目标受众及其目标（例如，“招聘团队寻找学习设计实习生，每位候选人浏览3到5分钟”）、作品集板块列表，以及一个房间地图，其中每个物体的日常功能与其对应的板块相匹配。如果一个物体及其含义不匹配，更换该物体（手提箱暗示“离开”；邮箱暗示“写信”）。每个板块还必须能从普通菜单中访问。

步骤2至5 · 构建房间

在编写场景前阅读 references/build-patterns.md。默认架构：

• 一个 index.html 文件，通过导入映射从固定CDN版本加载Three.js，每个物体都用代码从基本几何体建模（无模型文件），使用画布生成的纹理，并包含一个左上角菜单。
• 经常变化的内容（项目文件夹、图库项目）存放在 index.html 旁边的JSON小文件中，这样用户可以添加项目或照片而无需接触3D代码。
• 如果用户提供了参考图（步骤3），首先匹配其布局、调色板和光照；样式细节稍后添加。如果他们提供了示例交互（如React Bits、Codrops），则以网站自身风格构建一个原创版本，不要粘贴有许可限制的代码。

首次构建清单：每个板块都有一个悬停时发光并显示标签的物体；点击后，相机移动到该物体处并打开板块；菜单在无3D房间的情况下也能工作；大约5秒内加载完成；支持手机宽度。

步骤6和7 · 填充真实内容

阅读 references/content-and-docs.md。简要来说：索要真实材料（简历、LinkedIn文本、项目文件），据此起草，然后让用户修正。将真实作品放在首位，其背后的推理作为带编号的设计说明，指出决策及其背后的学习理论。删除过时的日期，除非它们至关重要。对于Google链接，检查共享权限是否为“知道链接的任何人可以查看”；如果文件需要大学账户登录，则改为托管在网站上。

步骤8 · 迭代

这是大部分工作发生的地方。从实际轮次中总结的规则：

• “可点击”的单一信号。 所有可点击的物体在悬停时发光；没有装饰性的物体发光或看起来可点击。消除错误信号（发光的纸张、漂浮的公式、随意放置的便利贴）。
• 为隐藏交互设置路标。 如果访客可以在黑板上画画，则当鼠标移到黑板上时将指针变成粉笔，将工具放在黑板正下方，并让它们发光直到首次使用。如果某个图库可以滚动，则显示一个小图例（方向键、滚轮、双指滑动、触摸拖动）。当某个板块打开时，使其中的下一个可点击物体微弱发光（一个脉动的轮廓），以便人们注意到它。
• 将交互元素放在人们视线附近。 当面板在右侧打开时，将可与之交互的物体放在场景的右侧。
• 真实比例。 按真实比例放置的书籍、杯子和家具看起来正确；拉伸的形状会立即显得不对劲。
• 仅在点击后播放声音（浏览器阻止自动播放）：提供一个“进入”按钮来启动音乐，外加一个静音选项。
• 按故事顺序排列内容。 在推荐语中，文字（信件、笔记、消息）排在照片之前；最个人化的物品放在最前面。
• 板块名称要直白。 菜单标签应说明里面有什么（“研究”，而不是“下一章节”）。
• 检查什么会阻挡点击。 Three.js 的 Line 和 LineSegments 对象默认会在大约一米外捕捉到射线；在装饰性线框上设置 obj.raycast = () => {}，否则附近的点击会作用于错误的对象。

每轮迭代后，对更改的视图进行截图，一次性修复肉眼可见的错误，并用平实的语言报告更改的内容。

步骤9 · 测试

运行 scripts/screenshot_site.js <site_dir> <out_dir> about projects contact（板块ID是菜单按钮的 data-go 值）来捕获桌面和手机视图，并打印页面错误。然后引导用户进行手动检查：每个物体和菜单项都能打开，每个链接在隐私窗口中都能工作，联系表单能收到（FormSubmit需要通过一次性激活邮件），静音仍然有效，仅键盘导航可行，以及让一位朋友无需帮助就能访问。

步骤10至13 · 发布与保护

阅读 references/launch-and-protect.md。内容涵盖GitHub加Vercel部署（主页面必须在顶层目录下命名为 index.html；GitHub网站上传单次最多100个文件）、自定义域名、通过Claude GitHub应用推送更改，以及保护措施：私有仓库、针对AI爬虫的 assets/robots.txt 和 assets/vercel.json 文件、Vercel的AI机器人拦截，以及版权声明。请坦诚地告知，任何公开发布的内容都无法防止复制。

可选交付物

完成整个过程的人通常希望教授这个流程。可以制作一份讲义和一套幻灯片，遵循13个步骤；使用他们网站的真实截图（前后对比）而非库存图片，并以他们的口吻撰写演讲者备注。scripts/html_to_docx.py 可以将包含设计说明的项目文档转换为Word格式。

常见故障

症状	原因	修复
Vercel上出现404	主文件不是 index.html，或位于文件夹内	重命名并移动到顶层目录
笔记本电脑文件夹或图库在线为空	projects/ 或其他文件夹未上传	将它们上传到 index.html 旁边
显示旧版本	缓存或部署仍在运行	等待状态变为Ready，然后强制刷新
“Cannot access X before initialization”	函数或纹理在使用之前未定义（const 声明之前）	提升声明（使用 function 声明）或将使用位置后移
点击一个物体打开了相邻物体	装饰性线框物体捕捉了射线	obj.raycast = () => {}
推送到GitHub被拒绝	Claude GitHub应用未安装在此仓库上	为此仓库安装该应用；可能需要新的会话