How andyhuo520/aetherviz-master works
项目类型与目的(从 README + 文件树推断)
AetherViz Master 本质上不是传统“有后端/有数据库”的 Web App,而是一个 AI 驱动的教学可视化 HTML 生成器(Claude Skill / 模板化生成工具):
• 生成阶段(Design-time / Build-time):用户在 *Claude Code*(或 Claude 的 Skill 机制)里输入“教学主题”,LLM 根据 SKILL.md 的规则/提示词,把主题“编译”为一个完整可运行的单页 HTML(包含 Three.js + SVG + UI + 控件逻辑)。
• 运行阶段(Run-time):用户用任意静态服务器(python -m http.server / npx serve / php -S)打开生成的 HTML;所有交互与渲染都在浏览器端完成(WebGL + DOM/SVG)。
> 关键点:AI 是外部依赖(Claude/LLM),仓库本身更像“Skill 定义 + 文档”,而不是完整源代码工程。你的系统设计图要把“生成系统”和“运行系统”分开画,否则会误导读者以为有后端服务。
文件结构解读(如何映射到架构图)
从你给的完整文件树来看,仓库只有:
• README.md:产品/能力说明、运行方式、技术栈与渲染策略(关键词→渲染模式)
• SKILL.md:最关键的“架构驱动文件”(定义 Claude 如何把主题生成 HTML;相当于编译器的规格/提示词/规则)
• LICENSE
README 中提到 docs/skill.md,但在你提供的 file tree 里并不存在;因此图中可以标注为:
• “可选文档(README 提及,但仓库当前未包含)”,避免画出不存在的组件。
你应该画的“最准确”架构图:建议分 4 张(C4 风格)
为了“最细 + 不过度脑补”,建议你产出 4 个视图:Context → Container → Component → Sequence。这对 Principal 读者最清晰。
目标:说明谁在用它、依赖谁、输出是什么。
建议组件拆分(尽量多拆):
Third-party Libraries(通常来自 CDN 或内联)
• Three.js r134
• OrbitControls(内联简化版)
• Tailwind CSS v3.4+
• KaTeX 0.16.11
• D3.js v7(可选)
GPU/WebGL(浏览器依赖的渲染能力)
关系/箭头(务必画方向):
• User → Claude Code:输入“主题”
• Claude Code ↔ Skill Definition:读取规则/提示词(SKILL.md)
• Claude Code → Generated HTML:产出 HTML
• User → Static Server:启动静态服务并访问
• Static Server → Browser:提供 HTML
• Browser → GPU/WebGL:WebGL 渲染调用
• Browser → CDN(可选):拉取 Three.js/Tailwind/KaTeX/D3(若生成物引用外链)
> 这一张图要明确:AI 平台是“生成阶段依赖”,不是运行时后端。
目标:把“生成端”和“运行端”的部署边界画清楚。
建议容器分组(用边框框起来):
“生成端”(AI/工具链侧)
• Claude Code Client(用户本地或云端)
• Claude LLM Service(外部)
• Skill Spec(本仓库:SKILL.md)
• Output: HTML file(生成物,落地到用户本地文件系统)
数据流:
• Topic text → Subject/Keyword analysis → Render mode decision → HTML templating/codegen → HTML 文件输出
“运行端”(纯前端)
• Static Server(仅文件服务)
• Browser SPA(生成的 HTML/JS/CSS)
• Rendering Subsystems
• WebGL/Three.js pipeline
• SVG overlay pipeline
• KaTeX math rendering
• UI (Tailwind) + Panels/HUD
> 容器图里不要画数据库/后端 API(除非 SKILL.md 明确生成的页面会调用某 API)。从 README 看它是离线可运行的教学页面。
目标:即使没有源代码,也能基于 README 的功能承诺,画出运行时组件拆分;这是最有价值的一张。
你可以把“Generated HTML App”当作一个容器,然后拆组件(建议按职责分层):
UI Layer(界面层)
• Sidebar / Control Panel(参数滑块、播放控制、速度控制)
• HUD Overlay(实时数据展示)
• Quiz Panel(可折叠)
• Learning Objectives Checklist
Orchestration / State(状态与编排)
• App State Store(当前主题、参数、播放状态、语言)
• Mode Controller(渲染模式:Three-only / SVG-only / Hybrid)
• Time Controller(播放/暂停/单步/速度)
Domain Logic(教学/仿真逻辑)
• Simulation Engine(物理运动、粒子、天体等)
• Scenario/Scene Builder(根据“主题类别”构建场景对象)
• Subject Theme Resolver(学科识别→配色主题/文案风格)
Rendering Layer(渲染层:强烈建议画成 2 条管线)
• Three.js Renderer
• Scene / Camera / Lights
• Meshes/Particles/Helpers
• OrbitControls(输入控制)
• SVG Renderer
• Axes/Function plots/Flow charts
• D3-driven charts(可选)
• Sync Bridge(3D-2D 坐标同步机制) ← README 强调“实时同步”,这是架构关键点
Content Rendering
• KaTeX Renderer(公式)
• Localization(中/英语言适配)
关键交互箭头(要画清):
• UI events → State Store → Simulation/Render updates
• Time Controller → Simulation tick → Three.js frame render
• Simulation state → Sync Bridge → SVG overlay update
> 你要把“混合渲染模式”画成显式分支:Mode Controller 决定走 Three、SVG 或两者并行,并通过 Sync Bridge 保证一致性。
建议至少两条序列:
LLM 依据 SKILL.md 进行:
• 学科识别(Physics/Math/…)
• 关键词检测
• 渲染方案选择(Three / SVG / Hybrid)
• 输出 HTML(内联或引用依赖)
requestAnimationFrame 循环:
• Time Controller 更新 dt
• Simulation 更新状态
• Three.js 渲染
• Sync Bridge 更新 SVG
图中必须强调的架构模式/设计原则(贴合本项目)
• Two-phase architecture(生成阶段 vs 运行阶段):这是本项目最大结构特征。
• Strategy Pattern(渲染策略选择):根据关键词选择 Three/SVG/Hybrid。
• Dual pipeline rendering(3D WebGL + 2D SVG):并通过 Sync Bridge 保证坐标/状态一致。
• Client-only deployment(无后端):静态托管即可;性能与兼容性取决于浏览器 WebGL。
标签建议(统一命名)
• 用明确名词:Mode Controller, Simulation Engine, SVG Overlay, 3D-2D Sync Bridge, KaTeX Renderer
• 用括号标技术栈:Three.js Renderer (WebGL), UI (Tailwind)
箭头建议(区分数据流 vs 控制流)
• 实线箭头:控制调用(init/update/render)
• 虚线箭头:数据流/状态同步(state → svg, theme → ui)
颜色/形状建议(强制区分)
• 蓝色:运行时前端组件(Browser App)
• 橙色:生成端(Claude/Skill)
• 绿色:第三方依赖(Three.js/KaTeX/D3/CDN)
• 灰色:基础设施(Static server / GPU / WebGL)
不要过度脑补的边界(保持“最准确”)
• 不要画数据库、后端 API、消息队列:README 没有任何证据表明存在。
• AI/LLM 画成外部系统:不是本仓库提供的服务。
• docs/skill.md:README 提及但 file tree 不含;可以用“(optional / mentioned in README)”标注,或在图注中说明缺失。
每个箭头标注:topic text、render mode、scene graph updates、svg sync、user input events
只要按上述拆分画出来,并在图注中说明“仓库只有 SKILL.md/README(生成规则)”,你的系统设计图就会既细又准确,并且与该项目的真实形态高度一致。