1

2026-01-05 17:41:00 +08:00
parent 0db59a9173
commit 24cebd2179
13 changed files with 569 additions and 536 deletions
--- a/cursor.md
+++ b/cursor.md
@ -1,178 +1,204 @@
-# AI Code Generation Prompts: Startup Website Clone
-**Tech Stack:** Vite + Vue 3 (Script Setup) + Tailwind CSS + Lucide Icons
+# Web3D 场景 SDK 使用说明
+
+本 SDK 用于在 Web 场景中快速完成三维展示与交互，核心能力包括：相机修改、灯光调参、环境贴图切换、按配置渲染热点、热点驱动抛出事件、模型热加载/热销毁/热替换，以及按部件切换材质。

 ---

-## 🟢 Step 0: Project Setup (Global System Prompt)
-*在开始编写具体页面前，先发送这条指令，建立全局的设计规范和技术栈。*
-
-**Prompt:**
-
-> **Role:** Senior Frontend Developer specializing in Pixel-Perfect UI cloning.
->
-> **Tech Stack Requirements:**
-> - **Framework:** Vue 3 (Composition API with `<script setup>`) + typescript.
-> - **Build Tool:** Vite.
-> - **Styling:** Tailwind CSS (Mobile-first approach).
-> - **Icons:** `lucide-vue-next` (You must use this library).
-> - **Language:** TypeScript.
->
-> **Design System (Strict Adherence):**
-> - **Visual Style:** Minimalist, "Vercel-like" aesthetic. High contrast, clean lines.
-> - **Typography:** Inter or system-ui. Headings must use `tracking-tight` (letter-spacing: -0.025em).
-> - **Colors:**
->   - Background: `#ffffff` (White).
->   - Surface/Card: `#ffffff` (White) with `border-gray-200`.
->   - Primary Text: `#0f172a` (Slate-900).
->   - Muted Text: `#64748b` (Slate-500).
->   - Accents: Black buttons, Light gray backgrounds (`bg-gray-50`) for secondary elements.
-> - **Borders & Radius:** Delicate borders (`border`, `border-gray-100`). Card radius is `rounded-xl` or `rounded-2xl`.
-> - **Shadows:** Very subtle `shadow-sm`, hover states use `shadow-md`.
->
-> **Instruction:** I will provide tasks to build 3 specific pages. You must replicate the layout, spacing, and Chinese copy exactly as described.
+## 功能概览
+- 相机控制：支持位置/目标点/FOV/远近裁剪的即时更新，带缓动动画。
+- 灯光调参：主光、辅光、环境光强度、颜色、方向、阴影开关与软硬度。
+- 环境贴图：HDRI 切换、曝光度、旋转（偏航/俯仰）、模糊度。
+- 热点系统：基于配置渲染热点 UI，可按 click/hover/focus 抛出事件。
+- 模型热更新：按 ID 进行加载、销毁、替换，支持队列并行与完成回调。
+- 材质切换：按部件或分组应用/还原材质，支持预设表与回滚。
+- 事件总线：统一事件接口，便于业务侧订阅热点/相机/模型状态。

 ---

-## 🟡 Step 1: Pricing Page (定价页)
-*复制此段生成定价页面组件。*
+## 快速开始
+```bash
+npm install your-web3d-sdk
+```

-**Prompt:**
+```ts
+import { createViewer } from 'your-web3d-sdk'

-> **Task:** Create a **`PricingPage.vue`** component. Clone the provided "Pricing" design exactly.
->
-> **1. Page Header:**
-> - Layout: Centered.
-> - Overline: "PRICING" (uppercase, tracking-widest, text-xs, text-gray-400).
-> - Title: "产品购买页面" (text-3xl font-bold tracking-tight).
-> - Subtitle: "按需套餐付费，尊享 Codex 与 Claude Code 两大产品线" (text-gray-500 mt-2).
->
-> **2. Section 1: Codex Plans (2-Column Grid):**
-> - **Heading:** "Codex 套餐" (Bold, text-lg, mb-4).
-> - **Layout:** Grid `grid-cols-1 md:grid-cols-2 gap-6`.
-> - **Card Design:** `bg-white border border-gray-200 rounded-xl p-6 relative`.
-> - **Left Card (Standard):**
->   - Top: Icon + "Codex" + "codex标准套餐". Badge: "工效效率" (Top Right, gray bg, text-xs).
->   - Price: "¥79.9/月" (text-4xl font-bold). Subtext: "性价比首选 | 强大智能".
->   - Features: List with blue bullet points (daily budget $90, etc.).
-> - **Right Card (Enterprise):**
->   - Price: "¥ 999". Badge: "定制高频版".
->   - Features: "个人/企业 定制高险套餐", "高频需求首选".
->
-> **3. Section 2: Claude Code Plans (3-Column Grid):**
-> - **Heading:** "Claude Code 套餐" (Bold, text-lg, mt-10 mb-4).
-> - **Layout:** Grid `grid-cols-1 md:grid-cols-3 gap-6`.
-> - **Cards:**
->   - Card 1: ¥228/月. Badge: "轻量性价比".
->   - Card 2: ¥398/月. Badge: "适合中等规模". (Highlight: slightly darker border or shadow).
->   - Card 3: ¥520/月. Badge: "深度运算".
-> - **Bottom Wide Card:** A full-width card for "Claude Code 定制套餐" (¥999).
->
-> **4. CRITICAL COMPONENT - Bottom Action Button:**
-> - Inside EVERY card, pinned to the bottom.
-> - Container: `bg-gray-50` (light gray), `rounded-lg`, `p-4`, `mt-6`.
-> - Layout: Flex row, `justify-between`, `items-center`.
-> - Text Left: "联系顾问" (font-medium text-sm).
-> - Text Right: Small gray caption (e.g., "codex标准套餐 · ¥79.9/月").
-> - Icon: Small `ChevronDown` or `ChevronRight` on the right side.
->
-> **5. Copy:** Use the exact Chinese text provided in the description.
+const sdk = await createViewer({
+  container: '#viewer',
+  assetsBase: '/assets',
+  background: '#0f172a',
+})
+
+// 加载初始场景或模型
+await sdk.model.load({ id: 'scene', url: '/models/showroom.glb' })
+```
+
+### 基础生命周期
+1. 初始化 viewer：`createViewer({ container })`
+2. 加载模型或场景：`sdk.model.load(...)`
+3. 设置环境贴图/灯光：`sdk.environment.setHDRI(...)`、`sdk.lights.update(...)`
+4. 渲染热点：`sdk.hotspot.render(config.hotspots)`
+5. 订阅事件：`sdk.on('hotspot:click', handler)`
+6. 在业务侧按需调用相机/材质/模型热更新 API

 ---

-## 🔵 Step 2: Documentation Page (使用文档页)
-*复制此段生成文档页面组件。*
+## 相机控制
+```ts
+// 直接设置视角
+sdk.camera.set({
+  position: [2.5, 1.6, 3.2],
+  target: [0, 0.8, 0],
+  fov: 45,
+  near: 0.1,
+  far: 200,
+})

-**Prompt:**
-
-> **Task:** Create a **`DocsPage.vue`** component. Clone the "Usage Guide" design exactly.
->
-> **1. Header & Controls:**
-> - Title: "使用说明". Subtitle: "新产品与插件安装的快速指南".
-> - **Tabs (Model):** A pill-shaped toggle container. Items: [Codex | Claude Code | GLM].
->   - Active State: Black background, White text.
->   - Inactive State: Transparent background, Gray text.
-> - **Tabs (OS):** Underline style. [Windows | macOS | Linux]. Active item has a black underline.
->
-> **2. Vertical Stepper Layout (The Core Visual):**
-> - **Container:** Max-width 800px, centered.
-> - **Structure:** A vertical list of steps.
-> - **Left Column:** A Step Indicator.
->   - A black circle (`w-6 h-6 bg-black text-white rounded-full flex items-center justify-center text-xs font-bold`) with the number (1, 2, 3).
->   - A thin gray vertical line (`w-px bg-gray-200`) connecting the numbers.
-> - **Right Column:** The content.
->
-> **3. Step Content Details:**
-> - **Step 1 (Install Node.js):**
->   - Title: "安装 Node.js 18+ (通用)".
->   - Link: "官网下载 (推荐)" in blue.
->   - Warning Box: A `bg-gray-50` rounded box containing bullet points about permissions.
->   - Version Check: A dark bar `node --version`.
-> - **Step 2 (Install CLI):**
->   - Title: "安装 Codex CLI".
->   - **Code Block:** A dark container (`bg-[#0f172a]`), `rounded-lg`, `p-4`, `shadow-inner`.
->   - Text: `npm install -g @openai/codex` (White text, font-mono).
-> - **Step 3 (Config):**
->   - Title: "配置环境 (CodeX)".
->   - **File Editor UI:** Create a mock code editor.
->   - Filename: "config.toml文件" (gray text above block).
->   - Code Content: Multi-line TOML config. Use specific colors for syntax highlighting (e.g., Strings in green, Keys in purple/white).
->
-> **4. Component Abstraction:**
-> - Please create a separate `<CodeBlock :code="code" :lang="lang" />` component for reusability.
+// 平滑过渡到指定视角
+sdk.camera.animateTo(
+  { position: [1.2, 1, 2.4], target: [0, 0.8, 0], fov: 50 },
+  { duration: 0.8, easing: 'easeOutCubic' }
+)
+```

 ---

-## 🔴 Step 3: Features Page (功能特性页)
-*复制此段生成功能着陆页组件。*
+## 灯光调参
+```ts
+// 更新主方向光
+sdk.lights.update('key', {
+  intensity: 1.5,
+  color: '#ffffff',
+  direction: [0.3, -1, 0.25],
+  castShadow: true,
+})

-**Prompt:**
-
-> **Task:** Create a **`FeaturesPage.vue`** component. Clone the "Features" design exactly.
->
-> **1. Hero Section:**
-> - Alignment: Center.
-> - Headline: "更快、更智能地构建软件" (text-5xl font-bold tracking-tight mb-6).
-> - Subheadline: "聚合多模型，深度理解你的代码库..." (text-gray-500 max-w-2xl mx-auto).
-> - Action Buttons:
->   - Primary: "开始使用" (Black bg, white text, rounded-full, px-8 py-2.5).
->   - Secondary: "查看文档" (White bg, border border-gray-200, black text, rounded-full, px-8 py-2.5).
->
-> **2. The Bento Grid (Critical Visual):**
-> - Section Title: "覆盖从编码到交付的全流程".
-> - **Grid System:** `grid-cols-1 md:grid-cols-3 gap-6`.
-> - **Card Anatomy:**
->   - `bg-white border border-gray-200 rounded-xl p-6 flex flex-col h-full overflow-hidden hover:shadow-md transition-all`.
->   - **Icon:** Top-left. Small Lucide icon inside a square `bg-gray-50` rounded container.
->   - **Text:** Title (font-bold mt-4) + Description (text-sm text-gray-500 mt-2).
->   - **The Mockup Area (Must Have):** At the bottom of each card, create a visual placeholder.
->   - *Implementation:* A `div` with `bg-gray-50/50 mt-6 h-32 w-full rounded border border-dashed border-gray-200`. Put a small "skeleton" UI inside (e.g., a few gray bars representing code lines) to mimic the screenshots.
->
-> **3. Stats Bar:**
-> - Layout: Flex row, wide container.
-> - Items:
->   - "2x" (交付效率提升)
->   - "40%" (Bug 修复加速)
->   - "60%" (重复劳动减少)
-> - Style: Numbers are huge (`text-5xl font-bold tracking-tighter`). Labels are small and gray.
->
-> **4. Footer CTA:**
-> - Text: "准备好升级研发效率了吗？"
-> - Button: "免费开始" (White button, border, rounded-full).
+// 环境光/辅光
+sdk.lights.update('fill', { intensity: 0.6, color: '#dfe8ff' })
+sdk.lights.update('ambient', { intensity: 0.25 })
+```

 ---

-## 💡 Developer Tips (For You)
+## 环境贴图
+```ts
+await sdk.environment.setHDRI('/envs/showroom_2k.hdr', {
+  exposure: 1.1,
+  rotation: [0, 45, 0], // yaw/pitch/roll
+  blur: 0.2,
+})
+```

-1.  **Global Font Fix:** To get the crisp look from the screenshots, add this to your `index.css` or `style.css`:
-    ```css
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif;
-      -webkit-font-smoothing: antialiased;
-      -moz-osx-font-smoothing: grayscale;
-    }
-    ```
-2.  **Icon Installation:** Ensure you have the icons installed:
-    ```bash
-    npm install lucide-vue-next
-    ```
-3.  **Refining:** If the AI output looks "too loose", tell it: *"Reduce the border-radius to 12px and make the text colors sharper (slate-900 instead of gray-800)."*
+---
+
+## 热点渲染与事件
+```ts
+const hotspots = [
+  {
+    id: 'engine',
+    position: [0.8, 0.6, -0.2],
+    icon: 'info',
+    label: '发动机舱',
+    event: 'show-engine',
+    payload: { part: 'engine' },
+  },
+  {
+    id: 'door',
+    position: [1.1, 0.9, 0.4],
+    icon: 'action',
+    label: '开启车门',
+    event: 'toggle-door',
+    payload: { side: 'left' },
+  },
+]
+
+sdk.hotspot.render(hotspots)
+
+sdk.hotspot.on('click', ({ id, payload }) => {
+  // 业务侧根据 id/payload 触发操作
+})
+
+sdk.hotspot.on('hover', ({ id, hovering }) => {
+  // hover 高亮或提示
+})
+```
+
+事件命名建议（可按需扩展）：
+- `hotspot:click`、`hotspot:hover`、`hotspot:focus`
+- `hotspot:rendered`（所有热点就绪）
+
+---
+
+## 模型热加载 / 热销毁 / 热替换
+```ts
+// 加载
+await sdk.model.load({ id: 'car', url: '/models/car.glb', draco: true })
+
+// 销毁
+await sdk.model.destroy('car')
+
+// 替换（内部自动销毁旧实例并加载新实例）
+await sdk.model.replace('car', { url: '/models/car-white.glb' })
+```
+
+可以通过 `sdk.model.on('loaded' | 'replaced' | 'destroyed', handler)` 监听模型状态。
+
+---
+
+## 材质切换
+```ts
+// 应用材质预设
+sdk.material.apply({
+  target: 'body',           // 部件或分组名称
+  material: 'paint/blue',   // 预设 Key
+})
+
+// 批量切换
+sdk.material.batch([
+  { target: 'wheel', material: 'rim/chrome' },
+  { target: 'glass', material: 'glass/clear' },
+])
+
+// 还原默认材质
+sdk.material.reset('body')
+```
+
+---
+
+## 推荐的配置结构
+```json
+{
+  "camera": { "position": [2.5, 1.6, 3.2], "target": [0, 0.8, 0], "fov": 45 },
+  "environment": { "hdr": "/envs/showroom_2k.hdr", "exposure": 1.1, "rotation": [0, 45, 0] },
+  "lights": {
+    "key": { "intensity": 1.5, "color": "#ffffff", "direction": [0.3, -1, 0.25] },
+    "fill": { "intensity": 0.6, "color": "#dfe8ff" },
+    "ambient": { "intensity": 0.25 }
+  },
+  "hotspots": [
+    { "id": "engine", "position": [0.8, 0.6, -0.2], "icon": "info", "label": "发动机舱", "event": "show-engine" },
+    { "id": "door", "position": [1.1, 0.9, 0.4], "icon": "action", "label": "开启车门", "event": "toggle-door" }
+  ]
+}
+```
+
+---
+
+## 事件清单（示例）
+- 相机：`camera:changed`
+- 热点：`hotspot:click`、`hotspot:hover`、`hotspot:rendered`
+- 模型：`model:loaded`、`model:replaced`、`model:destroyed`
+- 材质：`material:applied`、`material:reset`
+
+订阅方式：
+```ts
+sdk.on('hotspot:click', (evt) => console.log(evt))
+sdk.off('hotspot:click', handler) // 移除监听
+```
+
+---
+
+## 调试建议
+- 启用 `sdk.debug(true)` 查看加载、事件、帧率等日志。
+- 逐步应用配置：先确认相机与灯光，再添加环境贴图与热点，最后再做材质/模型热更新。
+- 热更新前后记录 ID/实例，避免重复销毁或遗漏解绑事件。