craftfolio

# craftfolio 把「我是谁」做成一个可以玩的 3D 世界,而不是一页简历 PDF。 ## 何时使用 ✅ 用户要做个人网站 / portfolio / 简历站,尤其是 3D、游戏化、滚动叙事方向 ✅ 用户发了一个参考站/参考视频,想复刻其技术栈与动效并换成自己的内容 ✅ 用户提到 three.js / R3F / 物理引擎 / 水面 shader / 滚动叙事做个人展示 ❌ 纯后台/工具类网站(不在此 skill 范围) ❌ 用户明确要求「做个最简单的静态页」(直接做,不必走本流程) ## 核心原则:学技术,不学模版 cases/ 发布的是**技术拆解,不是可复制的源码**——每个 case 的实际实现文件不随本 skill 分发,只有技术要点清单、架构说明和可复用的第三方资产(CC0 模型、字体)。 你要学的是:3D 世界怎么搭、相机和滚动怎么接、物理引擎怎么写、水面和光影的质感怎么来、性能预算和降级怎么做——这些清单里都写了。 然后**用用户自己的信息和审美,把技术重新实现一遍,长成一个不存在于 cases 里的新世界**。 禁止说"抄一份 case 里的代码来改"——没有代码可抄,只有技术做法可学。 ## 工作流(四阶段) ### Phase 1 · 了解这个人 - 先跑 `scripts/find_profile_sources.py [目录...]` 找候选文件——它只按文件名扫描,**不读取任何内容**,输出一份清单。 - 把清单原样给用户看,确认「这些能读吗、要不要再加目录」,拿到明确同意再读正文;不读与简历无关的隐私文件,拿不准就先问。 - 输出一段「这个人是谁」的小结:身份、经历、代表项目、审美倾向、必须呈现的信息清单。 ### Phase 2 · 确认方向 - 给用户 2–4 个方向(可引用 cases/ 里的风格作示例),问清: - 要什么感觉(游戏?驾驶?档案?复古?还是发我一个参考站?) - 哪些信息必须上站、哪些不要 - 有无硬要求(可访问性、信息密度、部署目标) - 用户的回答可以先跑 `scripts/pick_archetype.py "<用户原话>"` 过一遍,拿到关键词命中的 archetype 建议——只是起点,排名念给用户确认,不替 TA 拍板。 - 用户给参考站时:先跑 `scripts/teardown_reference_site.py <URL>` 嗅探技术特征(GSAP/Lenis/Three.js/Vanta 等),再对照 cases/ 里最接近的 case 读技术点清单,拆解动效细节、信息架构,写成 brief 再动工——只学做法,不直接抓它的资产。 ### Phase 3 · 生成 - 定好方向对应的 archetype(game/drive/scroll/dom/archive/retro,对照见「内容索引」表)后,跑 `scripts/scaffold_project.sh <目录> <archetype>` 起工程壳——版本基线和依赖一次装好,`npm run dev` 立刻可用,不需要从 cases/ 里复制任何实现。 - 技术选型参照 references/stack.md;滚动叙事参照 references/scroll-narrative.md;步行角色/昼夜/互动物参照 references/walking-character.md。cases/ 里每个 case 的 README 是对应风格的技术拆解——**读技术点清单,自己重新实现**,不要照抄任何一个 case 曾经的版式(源码本身不随本 skill 分发,见下文说明)。 - `examples/` 下是所有风格共用的通用底层(滚动时间线、场景注册表、确定性随机、阻尼跟随、纹理生命周期)——这些是工程模式不是审美签名,可以直接复制进项目,不违反「学技术不学模版」。 - 资产优先级:CC0/自生成 > 用户自有素材;记录许可(参照 references/assets-license.md),每加一个资产就跑 `scripts/add_credit.py <项目目录> --file ... --desc ... --author ... --source ... --license ...` 补一条 CREDITS.md,别攒到 Phase 4 才补。 - 全程守住性能预算与降级策略(references/performance.md),动效手感纪律见 references/motion-handfeel.md(禁 Math.random、backOut 生长、氛围与进度分离)。 ### Phase 4 · 验收 - 站点能 `npm run dev` 跑起来;构建零错误零类型错误。 - 截图逐屏检查:信息准确、动效顺滑、无穿帮。手段:有浏览器/截图工具时自己截(如 playwright 脚本);没有就把本地地址给用户,请其人工过目关键屏,别卡在「无法截图」上。 - 跑 `scripts/perf_audit.py <项目目录>` 核对资产体积预算(GLB/贴图/视频/字体分类统计,对照 references/performance.md 的阈值);draw call 等运行时指标仍需在浏览器里读 `gl.info.render.calls` 手动核对。 - 跑 `scripts/license_check.py <项目目录>` 核对 references/assets-license.md §4 的清单:CREDITS.md 条目是否齐全、代码里有没有疑似第三方盗链。 - 移动端与 `prefers-reduced-motion` 有可用降级。 ## 内容索引 - `cases/` — 5 个风格的**技术拆解**(不是源码模版;每个 case 曾经的实现源码不随本 skill 分发,只发布技术要点、架构说明和可复用的第三方资产)。每个 case README 都有一份「可学的技术点清单」,是 Phase 3 重新实现时的主要参照: - `amber-little-world/`(archetype: `game`)— 3D 游戏小岛:WASD 角色控制、室内外场景、昼夜与互动物,独立 3D runtime 的 iframe 嵌入架构 - `alpine-drive/`(archetype: `drive`)— 山谷驾驶:车辆物理、程序化地形与植被、水面、信息站点空间化;`public/models/` 附带可直接复用的 CC0 GLB 资产 - `haaland-legacy/`(archetype: `dom`)— 滚动叙事:GSAP ScrollTrigger + Lenis + R3F,DOM/Canvas/滚动时钟统一;`TECHNICAL_BREAKDOWN.md` 是参考站技术反推的范本 - `personal-archive/`(archetype: `archive`)— 档案馆:纸质档案质感、文档式信息架构,零 3D - `retro-desktop/`(archetype: `retro`)— 复古桌面(system7 / xp-space):窗口系统、像素与古早 UI 还原,零 3D - 单一 3D 场景滚动叙事(archetype: `scroll`,如整站一条 scrub 主时间线的形态)参照 `references/scroll-narrative.md`,无对应 case - `references/` — 基础规范(`stack.md` 技术栈、`scroll-narrative.md` 滚动叙事、`walking-character.md` 步行角色、`performance.md` 性能、`assets-license.md` 资产许可、`motion-handfeel.md` 动效手感) - `examples/` — 6 个风格共用的通用底层实现(滚动时间线、场景注册表、确定性随机/噪声、阻尼跟随链、纹理持有器),对应哪份规范见 `examples/README.md`,可直接复制 - `scripts/` — 跑通四阶段的执行工具,按阶段分工: - Phase 1:`find_profile_sources.py` — 扫简历候选文件(只扫文件名,不读内容) - Phase 2:`pick_archetype.py` — 把「要什么感觉」的回答映射成 archetype 建议;`teardown_reference_site.py` — 嗅探参考站的技术栈特征 - Phase 3:`scaffold_project.sh` — 按 archetype 起工程壳,版本基线对齐 `stack.md`;`add_credit.py` — 追加一条格式规范的 CREDITS.md 记录 - Phase 4:`perf_audit.py` — 资产体积核对 `performance.md` 预算;`license_check.py` — CREDITS.md 齐全性 + 疑似盗链核对