architecture-viz-studio

架构可视化工作室

打造能让人切身感受软件架构与理念，而不只是把它们画成图的页面。目标是让观者觉得“我从没见过公司的工作成果呈现成这样”——精致、动态、专业，不带 AI 垃圾感。这项技能集结了长期真实构建过程中积累的代码与经验，让你能从经过验证的组件开始组装，而不必重新摸索。

两项交付成果（通常会组合在同一页面中）

1. 滚动叙事 — 一个固定的 3D 低多边形世界（Three.js），用户滚动页面时，相机会穿行其中（GSAP ScrollTrigger）。一个请求或对象在这个世界中移动；各个章节逐步呈现。让利益相关者切身感受产品。→ 模板位于 assets/scene/ + assets/scroll/。
2. 架构地图 — 一张深色“蓝图”风格的 SVG 系统地图，带有可切换的叠加视图（一张地图，N 种视角：系统 / 数据流 / 归属 / 可靠性 / …）、可点击节点（点击后打开组件图深入查看），以及用于呈现数据模型的 ERD。供架构师探索。→ 位于 assets/diagrams/。

两者都支持设计系统（适配提供的品牌色、字体和 Logo；缺省时则使用雅致的中性默认样式），并提供编辑模式（assets/edit-mode/）。

工作流

按以下流程进行：构思叙事 → 搭建框架 → 基于模板组装 → 精修 → 验证 → 启用编辑模式。

1. 了解系统并选择隐喻。 阅读用户提供的设计文档 / PRD。确定滚动叙事要讲述什么（让一个实体在系统中经历完整旅程是一个不错的默认选项），以及架构地图的节点 / 视图。如果 3D“世界”隐喻不适合该领域，请说明原因，并侧重 2D 图表（参阅 references/diagram-catalog.md →“3D 世界隐喻：有意义的场景，而非噱头”）。

2. 构建之前，先确立设计系统——主动询问，不要擅自假设。 一致的视觉效果来自事先一次性确定设计变量。除非用户已提供品牌 / 设计系统，否则一开始就询问（简短、具体地了解需求，不要让用户撰写规范）：

   • 品牌色？ 主色 / 点缀色的十六进制值，或可供提取配色的 Logo / 网站。（如果没有，你可以提议一种专属点缀色 + 中性灰。）
   • 字体？ 一组标题字体 + 正文字体，或品牌字体。（如果没有，你可以提议一组雅致的搭配——不要到处都用 Inter，那会显得像 AI 垃圾。）
   • Logo / 品牌字标？ 用于导航栏。
   • 美学风格？ 两种适合专业呈现的风格：深色“蓝图”（架构地图）和浅色低多边形 3D 世界（滚动叙事）。请确认选择哪一种，或两种都选。
   • 有没有可供参考的现有页面 / 截图？ 这是最快实现一致性的方式——提取其配色、字体层级、间距和圆角并加以复现。

   如果用户没有任何素材，不要默默采用默认值——提出一套具体的设计系统（展示点缀色 + 字体搭配）并征求同意，或者引导他们参考 references/finding-layout-inspiration.md 选择方向。然后在构建任何组件之前，将确认好的设计变量写入 assets/page-shell/styles.css 中的 :root 代码块（--primary-500、--neutral-*、字体变量），确保从第一行开始所有部分都保持一致。现在阅读 references/styling-and-anti-slop.md——它决定了成果是专业还是粗制滥造，而且很容易弄错。在页面旁边用简短的 DESIGN-SYSTEM.md 记录设计决策，以确保后续修改（以及下一次会话）保持一致——变量检查清单见 references/styling-and-anti-slop.md →“设计系统需求收集”。

3. 从页面框架搭建，并先研读示例。 sample/ 是一个小巧但完整且经过全面调试的滚动叙事页面，正确应用了所有惯例（按需渲染 3D 场景、为每个文本元素添加标签、在背景上设置 vizSelectable:false、接入编辑模式和清单，以及避免劣化的样式）。开始构建前先阅读它——这是了解各部分如何配合的最快方式，而且它已经避开了 references/gotchas-and-lessons.md 中的错误。然后复制 assets/page-shell/index.html 和 styles.css 作为骨架（包含区块结构、importmap、模态框框架和令牌区块），再按需引入模块：

   • 3D 世界 → assets/scene/scene-setup.js、primitives.js、render-loop.js。这些模块默认采用工作室级配置——scene-setup.js 已搭好 Biggest-5 灯光基础（sRGB+ACES、PMREM/RoomEnvironment IBL、包含轮廓光的三点布光、FogExp2、用于强调效果的 glowMat()，以及深沉而富有氛围的默认配色）。不要简化成单个太阳光加环境光——这种扁平布光是业余作品最明显的标志。调整参数（根据世界尺寸调整视锥体，根据品牌调整配色），但保留整体结构。
   • ⭐ 后期处理（Biggest-5 #3）→ assets/scene/post-processing.js——可选的选择性泛光 + 颗粒 + 暗角 + SMAA。使用 setComposer() 接入（页面框架中的导入关系图展示了这 3 行代码）。它需要 postprocessing importmap 条目（page-shell/index.html 中已配置；必须使用原始的 build/index.js，不能用 /+esm，否则会产生两个 three 实例并导致泛光失效）。这是营造“惊艳感”的最后 20%——用于主视觉场景，轻量页面则可跳过。
   • 滚动编排 → assets/scroll/scroll-journey.js——默认提供 Lenis 平滑滚动层（lenis importmap 条目已在 page-shell/index.html 中配置）。它能让鼠标滚轮滚动顺滑，而不是卡顿或冻结——仅靠 scrub 无法解决这个问题。调整 duration 来控制手感；在减少动态效果模式下会关闭。原理请参见操作指南 →“平滑滚动”。
   • 架构图镜头 → assets/diagrams/overlay-lens-system.js（initOverlays → drill 标记）
   • 下钻组件图 → assets/diagrams/component-detail-modal.js（initDrill——data-drill 节点）
   • ERD → assets/diagrams/erd-diagram.js（initErd——data-erd 节点；内置完整的打开/关闭、双 rAF 绘制和暂停生命周期，无需重新推导；传入 intro/columns 以适配你的架构）
   • 为任意图表添加平移/缩放 → assets/diagrams/pan-zoom-viewport.js
   • 可选中的箭头 → assets/diagrams/edge-hit-proxies.js（tagSvgEdges）——为每条较细的 SVG 边缘添加宽大的透明点击区域，使其在编辑模式下可点击（否则，几乎不可能选中 2px 的箭头）。每个 SVG 调用一次（主图以及每个下钻/ERD 模态框中，渲染后调用）。 这些模块各用一行即可接入——请参见 assets/page-shell/index.html 中的导入关系图，以及 sample/ 中完整的通用化示例（使用中性的 CDN 域名——复制接线方式，替换文案/数据）。

4. 从一开始就采用可由 AI 调整的约定进行构建。 这不是可有可无的润色，而是让页面可修改的关键。每个 DOM 组件都要添加 data-viz-id="dotted.name"；每个 3D 对象都要调用 registerVizObject(obj, 'scene.name')。 并且要为每个文本元素添加标记，而不只是容器——标题、段落、导航链接、页脚／页眉文本、徽章／数字都要有各自的点分隔 ID（card.audit.title、footer.copyright）。编辑模式只能选择带有自身 ID 的节点，因此没有标记的文本无法被单独选中——悬停时只会选中整个卡片。使用小型命名构建函数（每个对象一个），在顶部归组布局常量，并优先使用配置对象，避免深层嵌套。阅读 references/ai-collaboration-protocol.md。原因是：用户之后提供反馈时，编辑模式工具会提供精确 ID，你可以将每个 ID 直接对应到其构建函数——无需猜测他们指的是哪个“框”。

5. 有意识地选择布局。 不要默认使用通用排布。对于每种图表，都要查阅 references/diagram-catalog.md——其中列出了各种情形对应的合适布局（例如，ERD → 中心辐射布局，确保连线不会交叉；管线图 → 带注释的水平带状布局，注释放在下方；系统图 → 区域分栏 + 叠加视图）。连线布线规则（锚点均匀分布、“多”端使用乌鸦脚符号、端点标注基数、标签沿箭头方向排列）也在该文档中——这些规则是经过多轮修改总结出来的。

6. 在真实浏览器中验证，并运行检查。 这是强制要求；这些页面具有视觉效果且依赖动画时序，因此不能只读代码来确认效果。在本地启动服务（python3 -m http.server），并使用 chrome-devtools 工具驱动浏览器：为每种滚动状态和每个叠加层／模态框截图，确认控制台没有错误。然后运行随附的检查，验证截图无法覆盖的客观指标：

   • node scripts/verify.mjs <url> --out report.json --shots shots/ — 检查控制台、3 种视口下的布局探测（溢出／重叠／文本裁切）、axe-core 无障碍与对比度 JSON、WebGL 画布是否确实渲染，以及滚动卡顿／CPU（而非 FPS——无头浏览器的 FPS 不具代表性）。
   • node scripts/slop-lint.mjs <url> --json slop.json — 检查机械式 AI 味痕迹（参见反 AI 味标准）。
   • node scripts/text-audit.mjs <url> — 如果任何文本元素没有自己的 data-viz-id 就会报错（这样用户可以指向每个标题／段落／页脚行，而不仅是容器）。⚠️ 它只能检查静态页面——不会打开 drill／ERD 模态框，因此这些模态框中由 JS 渲染且未加标记的内容也会被判定为干净。也要实时审查弹出窗口（打开每个模态框，逐一检查是否有文本节点缺少自己的 ID；不同的 drill 选项卡可能使用各自独立的轨道构建函数）——参见 visual-verification。
   • 遇到 3D 几何问题时（头部偏离尖端、出现间隙、封盖未覆盖、对象放置错误），不要只凭截图目测——直接检查实时场景并进行测量（获取页面的 {THREE,scene,camera,renderer} ctx，比较世界坐标／屏幕坐标位置；自定义相机取景前先冻结渲染循环）。具体方法见 references/visual-verification.md → “Reaching INTO the live scene”；它能让你结束反复猜测和检查的过程。
   • 使用强制重新加载（绕过缓存）重新检查——页面会缓存 main.js／styles.css，普通重新加载会加载过期的 bundle，让你刚应用的修复看起来毫无效果。 检查全部通过只是底线（“没有机械性故障，也没有 AI 味痕迹”），而非上限。审美判断——比喻是否贴切、整体是否显得高端、动效是否得体——仍然需要你和用户亲自把关。阅读 references/visual-verification.md，了解确切的工具链和需要人工判断的边界。 （脚本需要 Playwright：npm i -D @playwright/test axe-core && npx playwright install chromium。） 如果页面包含 Three.js 场景，在宣布完成之前，必须通过两项检查清单：

   ⭐ (a) WOW 质量门槛（references/wow-quality-bar.md → "The Biggest-5"）。「没有错误／验证干净」只是底线，而不是标准——用户期待的是专业 3D 设计师会交付、能让人惊叹的作品。正确但平淡的场景（只有环境光、原始 MeshStandardMaterial、默认线性渲染、没有后期处理、线性摄像机）看起来像学生作业，算不合格。至少落实 Biggest-5：（1）色调映射 + sRGB + DPR≤2；（2）通过 PMREM 使用 HDRI/RoomEnvironment IBL；（3）pmndrs/postprocessing — 选择性泛光 + 景深；（4）三点布光，包含轮廓光 + 柔和接触阴影；（5）带缓动的分阶段 GSAP 揭示效果 + FogExp2。然后亲自看看：它真的能让人「惊叹」吗？如果看起来平平无奇，就还没完成——这需要你（和用户）做出审美判断。

   ⚡ (b) 性能检查清单（references/gsap-threejs-playbook.md → "Mandatory performance checklist"）。惊艳效果不能牺牲性能，否则就称不上惊艳。按需渲染，让空闲 GPU 占用≈0（或者，对于持续动画的场景，当舞台位于屏幕外／标签页隐藏／模态框打开时暂停——观察滚动到固定画布上方的内容，而不是画布本身）；在 GSAP 的单一计时器上将帧率限制为 60，DPR ≤2，重复网格使用实例化，后期处理链合并为一个 EffectPass，阴影贴图 ≤2048，烘焙静态内容，不在每帧分配内存。测量性能（verify.mjs 会报告卡顿）——绝不要相信「看起来很流畅」。场景很漂亮但卡顿，(b) 不合格；场景流畅但平淡，(a) 不合格。

7. **生成 viz-manifest（可选但推荐）。**运行 node scripts/gen-viz-manifest.mjs <pageDir> --as-js，生成一个 viz-manifest.json（+ .js），将每个 data-viz-id / userData.vizId 映射到其 {file, line, builderFn, cssRule}。在 edit-mode 之前加载它。这是从「用户指向的内容」到「创建它的代码」的一跳桥梁——也是 Three.js 对象的唯一桥梁（它们没有 DOM 节点可供 grep）。随后，edit-mode 会在每条注释中标记其 source，而 window.__viz（assets/edit-mode/viz.js）可让你在运行时查询 id。

8. 启用编辑模式并交接。 接入 assets/edit-mode/edit-mode.js + .css（接线分为 3 步，见文件头部）；也可以选择加入 assets/edit-mode/viz.js。告诉用户：点击 ✎ 按钮或按 e 切换；工具栏包含 Normal/Expert 视图（Normal 会在悬停时显示组件的矩形框和 id；Expert 会一次性显示所有 id——适用于 DOM 和 3D 对象），以及四种工具——Pointer（正常与页面交互——不显示高亮，点击会穿透；适用于用户想在工具栏保持显示时操作页面的情况）、Select（点击元素，将其添加为评论；ctrl/⌘+点击可创建多选——继续按住 ctrl/⌘+点击以添加更多元素，再按 ctrl/⌘+点击移除元素，然后按 Enter/普通点击，将整个集合转为一条包含多个目标的评论）、Snip（拖动矩形框选）和 Brush（用手绘方式涂出一个区域）。评论会汇总在一个（可拖动的）侧边面板中。 如何将反馈传回给你——“Copy for AI”只有一个按钮，bridge 让它更智能：

   • 使用 scripts/serve.sh 启动服务（推荐）： ./scripts/serve.sh <pageDir> 会同时启动页面服务（8800）和 feedback-bridge（8910），因此页面运行时 bridge 始终处于运行状态——无需担心忘记启动另一个进程。使用 { bridge: 'http://localhost:8910' } 初始化 edit-mode。现在点击 “Copy for AI” 会同时复制 Markdown，并将批次 + snip PNG 发送到 bridge，由它们写入 /tmp/viz-edit/。用户只需说“读取反馈”——你读取 edit-feedback.json（每条评论都包含一个绝对路径的 imagePath）和 PNG 即可。如果 bridge 未运行，“Copy for AI”会静默回退为普通剪贴板复制。（另一种直接方式：自行运行 node scripts/feedback-bridge.mjs 和 python3 -m http.server。）
   • 不使用 bridge： “Copy for AI”会将 Markdown 复制到聊天中——适用于 id/text 评论，但不会包含 snip 图片。也可以使用 Download（edit-feedback.json + snip-N.png），然后运行 node scripts/receive-feedback.mjs，将文件保存到 /tmp/viz-edit/ 中 JSON 指定的路径。 处理这个批次时，先将每个 id 解析到对应的构建器（使用 source 字段，或 grep 该 id），读取任何 imagePath 以了解视觉上下文，并使用 sceneContext 复现准确的 3D 时刻。

9. 导出可分享的独立 HTML。 始终提供单文件导出，方便用户发送或在没有服务器的情况下打开：运行 node scripts/bundle-standalone.mjs index.html，将所有本地 CSS/JS 内联到一个 .html 文件中。默认会移除 Edit-mode（导出文件用于发布）。添加 --vendor 可同时内联 CDN 库（three/gsap），生成完全离线的文件；添加 --keep-edit 可保留创作工具。

按需查阅的操作知识

• references/gotchas-and-lessons.md — ⚠️ 请先阅读。 汇总了实际发生过的错误，每个都曾让之前的构建多花一轮调试时间：SVG .hidden 无效、[hidden] 被 display 类覆盖、调用 contains(window) 抛出错误、DOM 悬浮效果抢占 3D 悬停、无法进行射线检测的细管、未注册的 vizId 对象、GPU 空闲时仍持续渲染、readPixels 报黑色的陷阱、失效的 swiftshader 标志、ESM 模块解析，以及“每段文本都要加标签”规则。在编写编辑模式连线、3D 选择、渲染循环或验证脚本前，请先浏览本文——这是最省力的返工预防方式。
• references/gsap-threejs-playbook.md — GSAP + Three.js 技巧与注意事项：ScrollTrigger scrub、分段式相机参数重映射、getPointAt（弧长）与 getPoint 的区别及各自的适用场景、绘制式管道、InstancedMesh、画布纹理标签、贝塞尔切线标签旋转，以及 性能／暂停渲染模式（当 3D 场景离开视口或模态框打开时暂停循环——这是最显著的 CPU/GPU 优化）。编写任何场景或滚动逻辑前请阅读。
• references/wow-quality-bar.md — ⭐ 工作室级质量门槛。“没有 Bug”不是标准，“令人惊艳”才是。 专业 3D 主视觉与学生练习的差距所在：色调映射／sRGB 流程、HDRI/PMREM 环境光照、pmndrs/postprocessing（选择性泛光 + 景深 + 调色）、三点布光 + 轮廓光 + 柔和接触阴影、经过缓动与分阶段编排的 GSAP 相机及显现效果、氛围效果（雾／粒子／上帝光线），以及按优先级排列的 最重要 5 项清单。主视觉场景只有通过最重要 5 项检查才算完成。构建任何 3D 场景前后都请阅读。
• references/styling-and-anti-slop.md — 品味与克制、防粗制滥造检查清单，以及如何采用设计系统。开始样式设计前请阅读。
• references/diagram-catalog.md — 各类图表的布局模式 + 通用连线规则 + 覆盖镜头模型。布局任何图表前请阅读。
• references/finding-3d-models.md — 为模型对象添加真实细节，不要堆叠通用方块（服务器应由机架 + 栅格 + LED 组成，而不是三个立方体）；程序化优先的决策树；经过审核的免费模型来源目录（Kenney/Quaternius/KayKit CC0、Poly Pizza、Sketchfab、Poly Haven HDRI，以及 three.js-examples-are-NOT-MIT 注意事项），附各许可证的发布规则；AI 生成器（许可证因等级而异）；GLTFLoader → 重新着色 → glTF-Transform 优化流程。构建／导入任何 3D 对象时，以及在线查找模型时请阅读。
• references/finding-layout-inspiration.md — 在线查找滚动叙事和图表灵感的渠道（Awwwards、vectrfl/Stripe/Linear 滚动叙事类型、C4、Oxygen-Not-Included 覆盖层隐喻），以及如何借鉴结构而非外观。
• references/ai-collaboration-protocol.md — data-viz-id / userData.vizId 约定、易读如自然语言的代码结构，以及编辑模式工具输出的精确 JSON/markdown 合约，让你了解如何使用反馈。编写组件前，以及收到编辑模式反馈时请阅读。
• references/visual-verification.md — 如何像机器一样读取和验证页面：scripts/verify.mjs 工具链（布局探测、axe 对比度、画布渲染检查、GSAP .progress() 帧固定、卡顿／CPU）、scripts/slop-lint.mjs 规则集、viz-manifest 往返流程，以及仍需人工检查的完整清单。验证前，以及连线 manifest / window.__viz 时请阅读。

捆绑的模板库（复制，不要重写）

assets/ 中的所有内容都提取自一个经过打磨的真实构建项目（约 30 轮），并已通过语法检查。每个文件 都包含头部注释，说明其用途、依赖项以及如何接入。通用化的内容标记为 EXAMPLE / PLACEHOLDER。**复制前先阅读文件头部。**忠实复用其中的数学计算—— 尤其是 ERD 字形几何、以光标为锚点的平移/缩放、摄像机重新映射，以及渲染暂停循环；从头实现时很容易在这些地方出现细微错误。

sample/            ← a COMPLETE working reference page (read this first — all conventions applied correctly)
                     includes a filled-in DESIGN-SYSTEM.md worked example
assets/
├── page-shell/    index.html · styles.css · DESIGN-SYSTEM.md   ← start here: skeleton + token block + intake template
├── scene/         scene-setup · primitives · render-loop · post-processing   ← the Three.js world (studio-grade defaults)
├── scroll/        scroll-journey                  ← GSAP ScrollTrigger choreography
├── diagrams/      overlay-lens-system · component-detail-modal · erd-diagram · pan-zoom-viewport · edge-hit-proxies
└── edit-mode/     edit-mode.js · edit-mode.css · viz.js   ← visual-feedback tool (Pointer/Select+multi-select/Snip/Brush) + window.__viz query API
scripts/           ← run these to verify and to wire the id→source round-trip (need Node; verify/lint/audit need Playwright)
├── verify.mjs           console · layout probes · axe a11y/contrast · canvas-rendered · jank/CPU
├── slop-lint.mjs        the mechanical AI-slop tells (DOM + computed styles)
├── text-audit.mjs       flags any text element missing its own data-viz-id (the tag-every-text rule)
├── gen-viz-manifest.mjs build-time vizId → {file,line,builderFn,cssRule} map (the one-hop bridge)
├── bundle-standalone.mjs  inline the page into ONE shareable .html (edit-mode STRIPPED by default)
├── feedback-bridge.mjs    makes "Copy for AI" also write comments+snips to /tmp/viz-edit (read by absolute path)
├── receive-feedback.mjs   offline fallback: move downloaded edit-feedback.json + snips into /tmp/viz-edit
└── serve.sh               start the page server + the feedback-bridge together (so the bridge is always up)

关于运行 Playwright 脚本的说明：ESM 会从脚本所在的位置解析 node_modules（而 NODE_PATH 不适用），因此请将 scripts/ 复制到要测试的项目中，并在该项目的 node_modules 旁运行。只需安装一次：npm i -D @playwright/test axe-core pngjs && npx playwright install chromium。

收到编辑模式反馈时（修订循环）

用户会粘贴一批类似这样的内容：

## 1. component: hero.title
   make this 20% smaller and tighten the line height
## 2. area snip — components inside: arch.node.api, arch.edge.cdc
   (screenshot snip-2.png attached)
   these two are too close, add breathing room
## 3. object: scene.service-core
   make it taller and more imposing

对于每一项：解析 id → 找到对应的构建函数/CSS 规则（一个稳定 id 只对应一个位置），进行修改，然后在浏览器中重新验证该特定位置。应用整批修改后，对受影响的区域截图。这正是这种约定旨在实现的快速路径——从“他们指出的问题”一步直达“实现它的代码”。

标准（核心目标）——两方面：杜绝粗制滥造，打造惊艳效果

第一方面——不要粗制滥造（2D/页面）。 如果结果看起来像通用的 AI 生成页面——所有内容都居中、紫色渐变、表情符号标题、玻璃拟态、默认间距、彩虹色节点——那就不合格。坚持标准：**只用一种克制的强调色，其他地方使用中性灰色，建立真实的字体层级，留出充足的空白，界面装饰保持扁平，动效有所节制，圆角/阴影保持一致。**详情请见 references/styling-and-anti-slop.md。

第二方面——打造惊艳效果（3D/主视觉）。 避免粗制滥造只是底线；上限是做出让专业 3D 设计师也引以为豪、令人惊叹的作品。一个仅仅正确的 3D 场景（平淡的环境光、未经处理的材质、默认线性渲染、没有后期处理、线性摄像机）即使毫无错误，看起来也像是学生练习——这就不合格。验收标准见 references/wow-quality-bar.md（最关键的 5 项：色调映射/sRGB 流程、HDRI/PMREM 环境光照、带选择性泛光和景深的后期处理、带柔和接触阴影的三点式 + 轮廓光照，以及经过缓动/分阶段处理的 GSAP 动效）。惊艳效果来自光线、深度、氛围和调色后的最终图像——而不是几何体。对这一标准的要求应与反粗制滥造的标准同样严格。

无论采用哪种风格，这里展示的两种专业视觉风格都是深色的“蓝图”建筑美学和浅色的低多边形 3D 世界——都达到了惊艳效果的标准。遵循所有这些要求，才能让人说出“我不知道我们还能做出这么棒的作品”。

为了在人类发现之前捕捉机械式粗制滥造的迹象，请运行 node scripts/slop-lint.mjs <url>——它会标记色相范围为 250–300° 的靛蓝/紫罗兰色 CTA、渐变文本主视觉、霓虹发光阴影、统一的圆角/内边距、居中且使用 Inter 的主视觉、过于繁杂的配色/字体层级、玻璃拟态、表情符号导航/标题、一模一样的图标卡片网格，以及深色低对比度正文。Lint 检查通过是必要条件，但并非充分条件：这只表示“没有明显的粗制滥造标记”，不代表“设计优秀”——审美判断仍需要你和用户亲自把关。