# 《我要当市长》3D 技术预研报告（DSH 独立对照实验）

> **本任务为 DSH 独立对照实验。MIMO 不得读取、修改或删除本目录。
> DSH 也不得读取或修改 MIMO 的工作目录。**

| | |
|---|---|
| 报告方 | DSH（deepseek-v4.1-flash） |
| 工作目录 | `/vol1/ai/projects/wyszz-new/3d-spike-ds/` |
| 报告日期 | 2026-10-08 |
| 实验性质 | 3D 技术预研 + 最小原型，**不是**游戏，**不是**微信小游戏成品 |
| 隔离状态 | 未读取 `app/`、`3d-spike/`、`3d-spike-mimo/`、`little-town/`；未读取任何其它模型的产物 |

**关于 MIMO**：按隔离规则，DSH 全程未读取 MIMO 的任何源码、报告、截图、日志或配置。
因此本报告第 10 节的对比表中，MIMO 一列**全部为"待主控方填入"**，没有任何推测、
编造或间接引用。

---

## 0. 结论速览

| 问题 | 结论 |
|---|---|
| 推荐方案 | **方案 A：Three.js + TypeScript + Vite** |
| 浏览器端技术可行性 | ✅ 已实测通过（类型检查 / 构建 / 14 项交互全部通过，控制台 0 错误） |
| 竖屏浮空岛观感 | ✅ 实测达标，岛底分层截面清晰 |
| 微信小游戏可行性 | ⚠️ **有公开适配链路，但本次微信端未验证**（无微信开发者工具） |
| 真机可行性 | ❌ **真机未验证** |
| 最大风险 | 微信小游戏无 DOM，需适配层；阴影 + 半透明在低端机有性能与渲染差异风险 |
| 包体 | 生产包 557 KB（gzip 139 KB），远低于微信小游戏主包 4 MB 限制 |
| 依赖数 | 运行时依赖 **1 个**（three）；含开发依赖共 52 个包 |

---

## 1. DSH 使用的方案和版本

### 1.1 选型

**方案 A：Three.js + TypeScript + Vite**（原生 WebGL 之上的一层场景图封装）

选它的直接理由：本次预研需要的四件事——3D 相机、拖动旋转、射线拾取、竖屏取景——
Three.js 全部开箱提供且无需自研数学库；同时它是纯 JS 库、无 IDE 绑定，
可以直接在 NAS 的 Docker 无头环境里用 `npm install` + `vite build` 跑完，
不需要图形界面。这两点恰好是本项目最硬的两个约束。

### 1.2 实际版本（均为实测安装版本）

| 包 | 版本 | 类型 | 用途 |
|---|---|---|---|
| `three` | **0.186.1**（r186） | 运行时依赖 | 3D 场景图 / 相机 / 射线 / 材质 |
| `typescript` | **5.9.3** | 开发依赖 | 类型检查 |
| `vite` | **8.3.3** | 开发依赖 | 构建 / 开发服务器 / 预览 |
| `@types/three` | **0.186.0** | 开发依赖 | three 类型声明 |
| `@types/node` | **24.19.1** | 开发依赖 | 仅 `vite.config.ts` 读环境变量用 |
| `puppeteer-core` | **25.12.0** | 开发依赖（仅测试） | 无头浏览器自动化验收 |

**运行时依赖只有 1 个：`three`。** 没有引入任何 UI 框架、状态库、数学库或加载器。

Node.js **v24.15.0**，npm **11.12.1**，宿主 Debian GNU/Linux 12 (bookworm)，16 核 / 15 GB。

### 1.3 关键技术决策（及理由）

1. **相机用低透视（FOV 35°），不用正交。**
   正交投影下"浮空岛"的纵深感会消失，建筑高度差读不出来；
   35° 已经足够接近正交观感，又保留了体积感。

2. **只用几何体，零贴图、零外部资源。**
   全部造型由 `BoxGeometry / CylinderGeometry / ConeGeometry / SphereGeometry /
   CapsuleGeometry / OctahedronGeometry / DodecahedronGeometry` 拼装。
   后果：没有任何资源加载器依赖，也就绕开了微信小游戏里最麻烦的
   图片/贴图加载适配问题。这是刻意的可移植性设计。

3. **材质统一 `MeshLambertMaterial` + `flatShading`。**
   低多边形简约风，且在低端 GPU / 软件渲染器上开销最小（比 PBR 便宜得多）。
   云是唯一例外，用不受光的 `MeshBasicMaterial`（原因见 2.3）。

4. **鼠标通路与触摸通路分开实现，而不是只用 Pointer Events。**
   这不是重复劳动：**微信小游戏根本没有鼠标事件**，只有
   `wx.onTouchStart / onTouchMove / onTouchEnd`。预先写好独立的触摸通路，
   等于把最关键的移植改造提前做完了。同时用时间戳抑制浏览器在触摸后补发的
   合成鼠标事件（否则一次触摸会被算成两次旋转）。

5. **射线拾取用 `THREE.Raycaster` 打真实几何体，不做任何屏幕坐标映射表。**
   杜绝"固定屏幕坐标伪造点击"。

6. **取景距离由内容实测尺寸 + 视口宽高比动态求解，不写死。**
   竖屏自动后退、横屏自动靠近（详见 5.2）。

---

## 2. 独立原型结构

### 2.1 文件清单

```
/vol1/ai/projects/wyszz-new/3d-spike-ds/
├── README.md                                  隔离声明 + 快速开始
├── index.html                                 竖屏 viewport + HUD + 名称反馈条
├── package.json
├── tsconfig.json
├── vite.config.ts
├── src/
│   ├── main.ts                                入口：渲染器/场景/主循环/视口自适应/错误收集
│   ├── style.css                              竖屏样式、安全区适配、名称反馈条
│   ├── scene/
│   │   ├── world.ts                           浮空岛+岛底截面+道路+市政厅+2建筑+居民+树+云
│   │   ├── cameraRig.ts                       低透视相机 + 视口自适应取景
│   │   ├── lighting.ts                        半球光 + 平行光(阴影) + 补光
│   │   ├── selection.ts                       选中指示环
│   │   └── palette.ts                         配色表 + 低多边形材质工具
│   ├── input/
│   │   ├── controls.ts                        鼠标/触摸双通路旋转 + 缩放 + 点击判定
│   │   └── picker.ts                          THREE.Raycaster 真射线拾取
│   ├── ui/
│   │   └── label.ts                           点击对象后的名称反馈
│   └── debug/
│       └── hook.ts                            仅测试用只读钩子（window.__SPIKE__）
├── scripts/
│   └── e2e.mjs                                无头浏览器验收脚本（472 行）
├── shots/
│   ├── 01-default-island.png                  验收截图 1：默认浮空岛
│   ├── 02-rotated-island.png                  验收截图 2：旋转后的浮空岛
│   └── 03-click-label.png                     验收截图 3：点击对象后的名称反馈
└── docs/
    ├── DSH-3D技术预研报告.md                   本报告
    └── e2e-results.json                       E2E 原始结果（机器可读）
```

**源码统计**：`src/` 下 **10 个 `.ts`** + 1 个 `.css`，共 **1355 行**；
加 `index.html`（34 行）与 `scripts/e2e.mjs`（472 行），源码合计约 **1861 行**。

### 2.2 场景规模（实测）

| 指标 | 实测值 |
|---|---|
| Group 节点 | 10 |
| Mesh 节点 | 64 |
| 可拾取对象 | 9 个（浮空岛、道路、市政厅、建筑·民居、建筑·商店、居民、树木 ×3） |
| 内容水平半径 | 6.20 |
| 内容竖直半高 | 6.30 |
| 整体包围球半径 | 10.51（仅参考，不用于取景） |
| 纹理 / 外部资源 | **0** |

### 2.3 14 项必需元素逐条对照

| # | 要求 | 实现位置 | 实测结果 |
|---|---|---|---|
| 1 | 悬浮岛地形 | `world.ts` `buildIsland()` | ✅ 9 边形低多边形圆盘，草皮 + 草缘 |
| 2 | 岛底截面 | 同上 | ✅ 草皮层 → 土层 → 黏土层 → 岩体锥 → 尖端，另有 5 块嵌岩 + 1 颗晶体 |
| 3 | 一条道路 | `buildRoad()` | ✅ 横贯全岛，含路缘石与 9 段中线虚线 |
| 4 | 一个市政厅 | `buildCityHall()` | ✅ 台阶 + 主楼 + 二层 + 门廊立柱 + 钟塔 + 双坡屋顶 + 窗 |
| 5 | 两个建筑 | `buildHouse()` / `buildShop()` | ✅ 民居（坡屋顶）、商店（平顶 + 遮阳棚 + 招牌） |
| 6 | 一个居民 | `buildResident()` | ✅ 胶囊身体 + 球头 + 头发 + 双腿 + 双臂，站在路上 |
| 7 | 简单光照和颜色 | `lighting.ts` + `palette.ts` | ✅ 半球光 + 平行光（1024² 阴影）+ 补光；15 色配色表 |
| 8 | 正交或低透视相机 | `cameraRig.ts` | ✅ 透视 FOV 35°（低透视） |
| 9 | 鼠标拖动旋转 | `controls.ts` `handleMouseDown/Move/Up` | ✅ E2E 实测 10 次 |
| 10 | 触摸拖动旋转 | `controls.ts` `handleTouchStart/Move/End` | ✅ E2E 实测 10 次 |
| 11 | 至少一种缩放 | `handleWheel` + `pinchActive` | ✅ **两种都有**：滚轮 + 双指捏合 |
| 12 | 3D 射线点击检测 | `picker.ts` `Raycaster.setFromCamera` | ✅ 真实射线，无坐标映射表 |
| 13 | 点击后显示对象名称 | `ui/label.ts` + `main.ts` `handleTap()` | ✅ 底部胶囊条显示名称 + 岛面高亮环 |
| 14 | 竖屏视口适配 | `style.css` + `main.ts` `resize()` + `cameraRig.ts` | ✅ 4 种竖屏尺寸实测无溢出 |

**附加实现**：3 棵树（可点击）、5 组云（装饰）、选中指示环、安全区适配
（`env(safe-area-inset-*)`）、错误可视化为页面底部红条。

### 2.4 交互链路（点击）

```
真实鼠标/触摸事件
  → controls.ts 判定位移 < 8px 且按住 < 600ms ⇒ 视为点击
  → handleTap(clientX, clientY)
  → getBoundingClientRect() 求画布内像素
  → 像素 → NDC 归一化坐标
  → THREE.Raycaster.setFromCamera(ndc, camera)
  → intersectObjects(pickables, recursive=true)  ← 与真实几何体求交
  → 沿 parent 链上溯找 userData.spikeName
  → label.showHit(name) + selection.showAt(object)
```

全程**没有任何**"屏幕坐标 → 对象名"的映射表或固定坐标判断。

---

## 3. 完整验证结果

验证环境：宿主机 Debian 12，Node v24.15.0，Chromium 154.0.8037.57（无头），
视口 414×896 竖屏 / DPR 2，WebGL 2.0（ANGLE / SwiftShader 软件渲染）。

### 3.1 类型检查

```
$ npx tsc --noEmit
（无输出）
TYPECHECK_EXIT=0
```

✅ **通过，0 错误**。`tsconfig.json` 启用了 `strict`、`noUnusedLocals`、
`noUnusedParameters`、`noImplicitOverride`、`verbatimModuleSyntax`、`isolatedModules`。

### 3.2 生产构建

```
$ npx vite build
dist/index.html                   1.33 kB │ gzip:   0.87 kB
dist/assets/index-CwFv4K4e.css    1.99 kB │ gzip:   0.96 kB
dist/assets/index-DNyDL5LV.js   557.73 kB │ gzip: 141.52 kB
✓ built in 295ms
```

✅ **通过**。构建耗时 0.3–0.4 秒（Vite 8 默认用 Rolldown 类原生打包，
没有走 babel/webpack 那条慢路径）。

> **关于 gzip 数字**：Vite 自带的 gzip 报告在多次运行间会在 **139–142 kB** 之间浮动
> （多次实测同一份产物出现过 139.37 / 141.32 / 141.52 三个值）。
> 下表采用 `gzip -9` 的**确定性复测值**，同一产物重复测量结果完全一致。

| 产物 | 原始 | gzip -9（确定性） |
|---|---|---|
| JS（含完整 three r186） | 557,730 B | **139,365 B** |
| CSS | 1,999 B | 979 B |
| HTML | 1,337 B | 882 B |
| **`dist/` 合计** | **564 KB** | **约 141 KB** |

`node_modules` 体积 130 MB（含 puppeteer-core，它本身不含浏览器二进制，
复用系统 `/usr/bin/chromium`）。

### 3.3 交互验收（无头真实输入事件）

`scripts/e2e.mjs` 全程使用 **CDP 真实输入事件**（`Input.dispatchMouseEvent` /
`Input.dispatchTouchEvent`），不是 JS 合成事件，也不是直接改对象属性。

| 验证项 | 要求 | 实测结果 | 判定 |
|---|---|---|---|
| 鼠标拖动旋转 | ≥10 次 | **10 次**，方位角累计变化 −0.868 rad | ✅ |
| 触摸拖动旋转 | ≥10 次 | **10 次**，方位角累计变化 −0.868 rad | ✅ |
| 旋转是否真的改变画面 | — | 市政厅屏幕投影移动 **70.9 px**（鼠标）/ **68.0 px**（触摸） | ✅ |
| 点击市政厅 | 名称正确 | 命中 `市政厅` | ✅ |
| 点击建筑·民居 | 名称正确 | 命中 `建筑·民居` | ✅ |
| 点击建筑·商店 | 名称正确 | 命中 `建筑·商店` | ✅ |
| 点击居民 | 名称正确 | 命中 `居民` | ✅ |
| 点击空白（负样本） | 必须不命中 | 射线返回 `null`，标签不显示，选中环隐藏 | ✅ |
| 滚轮缩放 | 至少一种缩放 | zoom 1 → 0.772（3 次滚轮） | ✅ |
| 双指捏合缩放 | 同上 | zoom 0.772 → 0.55（1 次捏合） | ✅ |
| 控制台错误 | 0 | **0**（首轮曾出现 1 个 favicon 404，已用内联 data-URI 图标消除） | ✅ |
| 页面异常 | 0 | **0** | ✅ |
| 运行期捕获错误 | 0 | **0**（456 帧后仍为 0） | ✅ |

**点击瞄准方式说明**（关系到"是否伪造点击"）：
脚本先调用页面内 `__SPIKE__.projectObject(name)` 把该对象的**真实世界包围盒中心**
经相机投影成屏幕像素，再用 `__SPIKE__.probeAt(x,y)` 在该像素附近螺旋搜索，
找到一个**确实能被真实射线命中该对象**的像素，最后用真实鼠标事件点击它。
脚本只负责"瞄准"，**命中判定完全由页面内的 `THREE.Raycaster` 完成**。
4 次点击的 `offsetFromCenter` 均为 `[0,0]`（即包围盒中心投影点直接命中）。

### 3.4 竖屏视口适配

| 设备 | 视口 | 宽高比 | 基准取景距离 | 横向溢出 | 纵向溢出 |
|---|---|---|---|---|---|
| iPhone 14 | 390×844 | 0.4621 | 48.94 | 无 | 无 |
| Android 常见竖屏 | 360×780 | 0.4615 | 49.00 | 无 | 无 |
| iPhone 15 Pro Max | 430×932 | 0.4614 | 49.01 | 无 | 无 |
| iPhone SE 1 | 320×568 | 0.5634 | 40.14 | 无 | 无 |

✅ 四种尺寸均无滚动溢出，相机按宽高比自动重新取景。
（表中"基准取景距离"= 实测距离 ÷ 缩放倍率，已剔除前序缩放测试的干扰。）

### 3.5 WebGL 能力实测

| 项 | 值 |
|---|---|
| 版本 | WebGL 2.0 (OpenGL ES 3.0 Chromium) |
| GLSL | WebGL GLSL ES 3.00 |
| Vendor / Renderer | Google Inc. / ANGLE (SwiftShader 软件渲染) |
| MAX_TEXTURE_SIZE | 8192 |
| 可用扩展数 | 30 |

**原型本身没有显式调用任何 WebGL 扩展**（不使用压缩纹理、浮点纹理、立体渲染等）。
渲染器只用了 WebGL2 核心能力：深度缓冲、阴影贴图、混合。
上表 30 个扩展是**环境提供**的，不是本原型**必需**的——这对微信适配是利好。

### 3.6 三张截图

| 截图 | 路径 | 字节 | 内容 |
|---|---|---|---|
| 1 默认浮空岛 | `shots/01-default-island.png` | 129,244 | 828×1792，默认方位角 0.62 / 极角 0.95，岛底分层截面清晰可见 |
| 2 旋转后浮空岛 | `shots/02-rotated-island.png` | 121,645 | 方位角 −1.116 / 极角 0.702，视角明显改变，道路呈对角线 |
| 3 点击名称反馈 | `shots/03-click-label.png` | 138,724 | 选中市政厅，岛面绿色高亮环 + 底部"市政厅"名称条 |

> 截图 1、2 的字节数在多次运行间完全一致（纯 canvas 渲染，确定性）。
> 截图 3 会有 ±1 KB 的浮动，因为名称反馈条带 140 ms 的 CSS 淡入过渡，
> 截图恰好落在过渡期的哪一帧会导致轻微像素差异；这不影响验收（E2E 只断言
> "三张截图互不相同"，不断言具体字节数）。

三张截图 MD5 互不相同（E2E 已内置此断言，防止"旋转了但画面没动"的假通过）。

### 3.7 构建期环境问题（NAS 无头环境的真实坑）

**现象**：`npm run dev` 启动时 Vite 文件监听报
`file watcher error: EMFILE: too many open files`。

**根因（实测）**：

```
fs.inotify.max_user_instances = 128
宿主上已存在的 inotify 实例 = 175   ← 已被其它进程/容器占满
ulimit -n = 524288                  ← 不是 fd 上限问题
```

**影响面**：只影响 `vite dev`（HMR 文件监听）。
`vite build` 与 `vite preview` **不依赖 inotify，完全不受影响**——
这一点很关键，说明 NAS 上的 CI / 无头构建链路是安全的。

**本次处置**：在 `vite.config.ts` 中加入 `SPIKE_POLL=1` 触发的轮询模式，
实测 `SPIKE_POLL=1 npm run dev` 启动干净、无 EMFILE 报错、页面 HTTP 200。
**没有**修改宿主机 sysctl（隔离规则禁止改动 NAS 配置）。

---

## 4. 失败项和未验证项

### 4.1 过程中真实出现并已修复的问题

| # | 问题 | 发现方式 | 处置 |
|---|---|---|---|
| 1 | **旋转只改了相机球坐标状态，从未重新写回相机 `position` / `lookAt`** —— 输入计数上涨、方位角状态变化，但**画面完全没转** | E2E 断言"三张截图必须互不相同"时发现截图 1 与截图 2 的**字节完全相同**（MD5 均为 `f02ca4f…`） | 在主循环每帧调用 `rig.update(viewAspect)` 把球坐标写回相机；并新增"市政厅屏幕投影必须移动 >20px"的断言 |
| 2 | favicon 404 导致控制台有 1 个错误 | E2E 断言控制台错误数为 0 | `index.html` 改为内联 data-URI SVG 图标，零网络请求 |
| 3 | 触摸后的鼠标点击被吞 | E2E 截图 3 的点击未产生名称反馈 | 定位为**代码本身正确**：触摸后 700 ms 内抑制合成鼠标事件是移动端必需行为；是测试脚本没等窗口过期。修正测试，并在代码中补注释说明 |
| 4 | 云渲染成灰黑色，看起来像石头 | 截图肉眼复核 | 改用不受光的 `MeshBasicMaterial` + 白色 + 平滑球体 |
| 5 | 取景过度留白，岛在画面里只占约 55% 宽 | 截图肉眼复核 | 用**真实顶点**实测内容尺寸（而非 AABB 角点）分别求解水平/竖直取景距离 |
| 6 | `vite.config.ts` 用 `process.env` 导致类型检查失败 | 最终验证 `tsc --noEmit` 报 TS2591 | 加 `@types/node` 并加入 tsconfig `types` |
| 7 | `vite dev` 在 NAS 上报 EMFILE | 启动开发服务器时 | 加轮询模式开关（见 3.7） |

> 第 1 项是本轮最有价值的发现：**只断言"交互计数器上涨"会放过严重渲染缺陷**。
> 因此 E2E 最终采用双重判定——计数正确 **且** 对象屏幕投影真的移动 **且** 截图字节不同。

### 4.2 未验证项（必须明确声明）

| 项 | 状态 | 说明 |
|---|---|---|
| **微信小游戏端** | ❌ **微信端未验证** | 环境中没有微信开发者工具（且任务明令禁止安装），**不能声称兼容** |
| **真机** | ❌ **真机未验证** | 没有真实手机；触摸是用 CDP 触摸事件模拟的，不是真手指 |
| 方案 B（原生 WebGL） | ❌ 未实测 | 仅做资料与工程分析，未写代码 |
| 方案 C（LayaAir 等） | ❌ 未实测 | 未安装 LayaAir，未做移植实验；Cocos Creator 属明令禁止安装项 |
| 移动端真实 GPU 性能 | ❌ 未验证 | 本次是 SwiftShader **软件**渲染，帧率不代表真机 |
| iOS Safari 兼容性 | ❌ 未验证 | 只在 Chromium 154 上验证 |
| 微信小游戏包体 / 分包策略 | ❌ 未验证 | 只有浏览器侧的 557 KB 数据 |
| 小游戏 WebGL1 降级路径 | ❌ 未验证 | 本原型运行在 WebGL2；小游戏部分机型可能只有 WebGL1 |
| 音频 / 存档 / 网络 | — | 按任务要求未实现，也不在本次预研范围 |

---

## 5. 方案比较（A / B / C）

> **证据标注约定**：
> 🟢 **实测** = 本次在本目录真实构建 / 运行 / 验证过的结论
> 🟡 **推断** = 基于公开官方资料与工程经验的分析，本次**未实测**
> 🔴 **未验证** = 没有依据，明确不知道

### 5.1 十项必比项

#### ① NAS Docker 无头环境构建难度

| 方案 | 结论 | 依据 |
|---|---|---|
| **A Three.js + TS + Vite** | 🟢 **容易**。`npm install` 50 个包 18 秒；`vite build` 0.4 秒；纯 JS，无原生模块、无图形界面依赖。唯一坑是 `vite dev` 的 inotify 上限（已用轮询绕过），`build`/`preview` 不受影响 | 本次实测 |
| **B 原生 WebGL + TS** | 🟡 **构建最容易**（几乎零依赖，只要 tsc + 一个打包器），但**开发成本最高**，见 ⑧⑨ | 推断 |
| **C LayaAir 等** | 🟡 **最难**。LayaAir 的典型工作流依赖图形化 IDE 导出，命令行/CI 化不如 A 成熟；Cocos Creator 同样重 IDE。在无头 NAS 上跑通"改代码 → 出小游戏包"闭环的摩擦明显更大 | 推断，**未实测** |

#### ② 是否支持 3D 相机

| 方案 | 结论 |
|---|---|
| **A** | 🟢 支持。`PerspectiveCamera` / `OrthographicCamera` 开箱即用，本次用 FOV 35° 透视相机实测通过 |
| **B** | 🟡 支持，但需自写矩阵与投影完备实现（`mat4` 透视/正交、`lookAt`、视锥体） |
| **C** | 🟡 支持（LayaAir 有 `Laya.Camera`，含 3D 场景） |

#### ③ 是否支持拖动旋转

| 方案 | 结论 |
|---|---|
| **A** | 🟢 支持。本次自写球坐标轨道控制器（未用 OrbitControls，以保持零额外依赖）。鼠标 10 次 + 触摸 10 次实测通过 |
| **B** | 🟡 支持，但旋转矩阵/四元数要自己维护，且没有 `OrbitControls` 这类现成件 |
| **C** | 🟡 支持，LayaAir 提供相机控制脚本 |

#### ④ 是否支持射线点击检测

| 方案 | 结论 |
|---|---|
| **A** | 🟢 支持。`THREE.Raycaster.setFromCamera()` + `intersectObjects(recursive)` 直接给出交点、距离、命中三角面。本次 4 个对象全部命中正确名称 |
| **B** | 🟡 支持，但要**自己实现**：屏幕坐标→NDC→逆投影→世界空间射线→与每个网格做三角形求交→取最近交点。对 Box/Cone/Capsule 这类非平凡几何，需要自己维护 BVH 或退化到包围盒近似，精度和性能都要自己兜 |
| **C** | 🟡 支持，LayaAir 有 `Physics.rayCast` / 射线检测 API |

#### ⑤ 微信小游戏适配难度

| 方案 | 结论 | 依据 |
|---|---|---|
| **A** | 🟡 **中等，且路径清晰**。Three.js 在小游戏上有两条公认链路：腾讯官方 `threejs-miniprogram` + `weapp-adapter`，以及社区 `three-platformize`（README 明确标注"小游戏真机 ✔️ 小游戏模拟器 ✔️"）。主要改造是替换 canvas 获取方式与触摸接口，不需改业务代码 | 🟡 公开资料，**微信端未验证** |
| **B** | 🟡 **中等偏低**。因为完全没有第三方库，只要自己把"canvas 来自 wx"和"触摸来自 wx"这两点抽象好即可，适配面最小 | 推断 |
| **C** | 🟡 **最低（若用 LayaAir）**。LayaAir/Cocos 本身就是为小游戏发布设计的，有官方发布链路，理论上"点一下出包"。代价是框架锁定与包体膨胀 | 🟡 公开资料，**未实测** |

#### ⑥ 是否依赖 DOM / window / document / 浏览器专属 API

**🟢 本次对 A 做了逐行清点（实测，非估计）**，`src/` 下全部依赖如下：

| 类别 | 具体依赖 | 出现位置 |
|---|---|---|
| `document` | `getElementById` ×5 | `main.ts` 取 `#app`/`#stage`/`#label`/`#label-text`/`#boot-error` |
| DOM 节点 | `HTMLCanvasElement`、`getBoundingClientRect()` | `main.ts`、`controls.ts`、`hook.ts` |
| DOM 布局 | `clientWidth` / `clientHeight` | `main.ts` 视口尺寸 |
| DOM 类名 | `classList.add/remove` | `controls.ts`（拖拽光标）、`label.ts`（反馈条显隐） |
| `window` | `addEventListener`(error / unhandledrejection / resize / orientationchange / mousemove / mouseup)、`innerWidth` / `innerHeight`、`devicePixelRatio`、`setTimeout` / `clearTimeout` | `main.ts`、`controls.ts`、`label.ts` |
| `performance` | `performance.now()` | `controls.ts` 点击/拖拽判定与触摸抑制 |
| `ResizeObserver` | 有，且带 `typeof !== 'undefined'` 降级到 `window.resize` | `main.ts` |
| CSS 专有 | `env(safe-area-inset-*)`、`touch-action: none`、`overscroll-behavior`、`linear-gradient` | `style.css` |
| `console` | `console.error` | `main.ts` 错误上报 |
| three.js 内部 | `requestAnimationFrame`（经 `renderer.setAnimationLoop`）、`canvas.getContext('webgl2')`；three 自身另有 `document.createElementNS` 等 DOM 假设 | 库内部 |

**结论**：A 方案的**业务代码**对 DOM 的依赖是**薄且集中**的——集中在
`main.ts`（DOM 查询 + resize）与 `controls.ts`（事件绑定）两个文件。
渲染核心（`world.ts` / `cameraRig.ts` / `lighting.ts` / `picker.ts` / `selection.ts`）
**完全不碰 DOM**，是纯 Three.js + 数学。这让移植改造面可控。

Three.js **库内部**确实假设了 `document` / `window`（如 `createElementNS`），
这正是必须引入 `weapp-adapter` 这类适配层的原因，**无法靠改业务代码消除**。

| 方案 | 结论 |
|---|---|
| **B** | 🟡 依赖面**最小且完全自主可控**——可以设计成"零 DOM 假设"，把 canvas 与输入作为参数注入。这是 B 的唯一真正优势 |
| **C** | 🟡 依赖 LayaAir 自身的平台抽象层，业务代码通常不直接碰 DOM；但框架内部的黑盒适配层不可控 |

#### ⑦ 包体和依赖数量

| 方案 | 运行时依赖 | 生产包（实测 / 估计） |
|---|---|---|
| **A** | 🟢 **1 个**（three） | 🟢 **实测 557 KB / gzip 139 KB**；含 CSS+HTML 共 564 KB / gzip 约 141 KB。`node_modules` 130 MB（其中 puppeteer-core 是测试用，不进生产包） |
| **B** | 🟡 **0 个**运行时依赖 | 🟡 估计 **60–120 KB**（无 gzip 时更小）。本次需要自研的矩阵/相机/射线/材质/阴影代码，估计 2000–4000 行 |
| **C** | 🟡 LayaAir 引擎本身 | 🟡 估计 **1–2 MB+**（LayaAir 3D 引擎比 tree-shake 后的 three 更重）。微信小游戏主包上限 4 MB，仍在限内但余量更小 |

> A 的 557 KB 里绝大部分是 three 的完整核心。若后续接入 tree-shaking 更激进的
> 构建配置，还有压缩空间。**557 KB / 4 MB = 14%**，微信小游戏包体不是瓶颈。

#### ⑧ 后续接入建筑升级 / 居民寻访 / 城市装扮的难度

| 方案 | 结论 |
|---|---|
| **A** | 🟢 **最容易**。本次原型已经天然给出了接入点：<br>• **建筑升级** — `world.ts` 里每个建筑是独立 `Group`，升级即替换/叠加子网格 + 改 `userData` 等级；射线拾取已经能区分对象，点击 → 升级面板是纯增量<br>• **居民寻访** — 居民已有独立 `Group` 与可拾取标签，寻访动画就是给它挂 `AnimationMixer` 或直接 tween `position`/`rotation`<br>• **城市装扮** — 装饰物（树、云）已经是独立构建函数，新增"皮肤"就是换 `palette.ts` 的色值或替换几何体；因为**全项目零贴图**，换肤成本极低<br>• 已有 `PICK_TAG` 统一标签机制，新对象只要打标签就自动可点击 |
| **B** | 🟡 **最难**。以上每一项都要先有自研的场景图、材质系统、拾取系统才谈得上；相当于先造一个 mini-three 再开始做游戏。对"3 个月内要能持续加内容"的项目，这是持续成本 |
| **C** | 🟡 **中等**。LayaAir 有场景/预制体/编辑器，美术与策划可参与，但需要团队学习其工作流；且强绑定其编辑器 |

#### ⑨ 维护成本

| 方案 | 结论 |
|---|---|
| **A** | 🟢 **低**。three 是 GitHub 上最活跃的 3D 库之一，r186 仍在常规发版；TypeScript 类型由 `@types/three` 维护，本次 `strict` 全开 0 错误。升级路径清楚（three 的破坏性变更会在 migration guide 里列出，如 r155 的光照单位改革） |
| **B** | 🟡 **最高**。自研渲染/数学代码的每一行都是团队自己的维护责任；图形学 bug 排查成本极高，且**没有社区兜底**。人一离职就是技术债 |
| **C** | 🟡 **中等**。官方维护，但生态与资料比 three 少；版本升级可能牵动编辑器工程文件，合并冲突面大 |

#### ⑩ 主要风险

| 方案 | 主要风险 |
|---|---|
| **A** | ① 小游戏适配层（`weapp-adapter` / `three-platformize`）的**维护活跃度**与对 three **新版**的跟进速度不同步——本次用的 r186 已相当新，适配器很可能滞后，**必须锁版本**（🔴 未验证）<br>② three 库内 `document`/`window` 假设必须在适配层解决，不是零成本<br>③ 真机 GPU 性能与 WebGL1 降级路径未验证<br>④ 包体 557 KB 中若含未用模块，需额外 tree-shaking 优化 |
| **B** | ① 开发周期与质量风险最高，射线拾取对非平凡几何体的精度/性能需自研<br>② 无社区支持，招聘与交接困难<br>③ 需求一变（加阴影、加模型格式、加骨骼动画）就要自己补轮子，**范围失控风险最大** |
| **C** | ① **框架与编辑器强绑定**，团队迁移成本高<br>② 引擎包体更大，小游戏 4 MB 主包余量更小<br>③ 生态与文档量级明显小于 three，遇到坑的检索成本高<br>④ 若团队不熟悉，学习曲线会吞掉前期工期<br>⑤ 本次**完全未实测**，所有结论都不足以作为决策依据 |

### 5.2 取景算法的横向对比（本次实测的设计要点，值得带入正式项目）

竖屏是这类"浮空岛"游戏的主战场，而竖屏最大的坑是**取景**。
本次没有写死相机距离，而是：

1. 遍历所有网格的**真实顶点**，算出内容相对中心竖轴的**最大水平半径**（6.20）
   与**竖直半高**（6.30）；
2. 用当前视口宽高比求出水平半 FOV 与竖直半 FOV；
3. 分别求 `dH = R_h / tan(halfH)` 与 `dV = R_v / tan(halfV)`，**取较大者** × 1.15 留白。

**为什么不用包围球？** 包围球半径是 10.51，比真实水平半径 6.20 大了 70%——因为它把
岛底那根长长的锥体也算了进去。用它取景的结果是岛只占画面宽度约 55%（第一版实测），
大量留白。改用分轴实测后，岛的宽度占比提升到约 87%，观感明显改善。

**为什么不用 AABB 角点？** 浮空岛是圆盘形，AABB 角点落在空白处，会把水平半径
从 6.2 虚报成 8.8（√(6.2²+6.2²)），同样导致过度留白。**必须用顶点**。

---

## 6. 方案优缺点总结

### 方案 A：Three.js + TypeScript + Vite

**优点**
1. 🟢 四项核心能力（3D 相机 / 拖动旋转 / 射线拾取 / 阴影光照）开箱即用，本次 0 自研数学代码
2. 🟢 NAS 无头环境构建极顺：纯 JS、无原生编译、`build` 0.4 秒
3. 🟢 运行时依赖仅 1 个，包体 557 KB（gzip 139 KB），远低于小游戏 4 MB 限制
4. 🟢 TypeScript `strict` 全开 0 错误，工程可维护性好
5. 🟢 业务代码对 DOM 的依赖**薄且集中**（2 个文件），渲染核心零 DOM，移植面可控
6. 🟢 有两条公开的小游戏适配链路（官方 `threejs-miniprogram` + 社区 `three-platformize`）
7. 🟢 全项目零贴图、零外部资源，天然绕开小游戏最麻烦的资源加载适配
8. 🟢 后续加建筑升级 / 居民寻访 / 城市装扮的接入点已经现成（独立 Group + 统一标签）

**缺点**
1. 引入了一个较大的第三方渲染库（557 KB），且其内部有 `document`/`window` 假设
2. 小游戏适配器与 three 新版的跟进存在滞后风险，需锁版本
3. 抽象层级高，遇到渲染细节问题时要下钻到 three 源码
4. 阴影 + 半透明在小游戏低端机的表现与桌面不同（🔴 未验证）

### 方案 B：原生 WebGL + TypeScript

**优点**：运行时零依赖；包体最小；对 canvas 与输入的抽象完全自主，理论上最贴合小游戏；
没有第三方库的 `document` 假设需要绕。
**缺点**：相机、投影、场景图、材质、阴影、**射线拾取**、变换层级全部自研；
周期与质量风险最高；无社区兜底；需求演进时持续补轮子，**范围失控风险最大**。

对"要持续加内容"的项目，B 省下的 557 KB 换不回自研渲染层的长期人力成本。

### 方案 C：LayaAir / Cocos Creator 等带小游戏发布链路的方案

**优点**：官方一键发布微信小游戏，最省事；自带编辑器，美术/策划可参与；3D 能力完整。
**缺点**：框架与编辑器强绑定；引擎包体更大（小游戏 4 MB 余量更小）；
生态与文档量级明显小于 three；团队学习曲线成本；
**本次完全未实测**（Cocos Creator 属明令禁止安装项，LayaAir 未安装）。

---

## 7. 微信小游戏适配分析

> ⚠️ **总声明：本次没有微信开发者工具，微信端未验证。**
> 以下所有微信相关结论都**不是**实测结果，而是分为
> 【已在浏览器实测】【根据官方资料推断】【尚未验证】三类，请勿把推断当实测。

### 7.1 使用/依赖了哪些浏览器 API

（完整清单见 5.1 ⑥，此处按"移植时要改什么"归类。）

| 依赖 | 移植小游戏时 | 分类 |
|---|---|---|
| `document.getElementById` 取 5 个 DOM 节点 | 小游戏无 DOM，需改为代码创建或直接持有引用 | 【已在浏览器实测】确认占用 |
| `canvas.getBoundingClientRect()` 求点击坐标 | 小游戏 canvas 铺满全屏，需换成 `wx.getSystemInfoSync()` 的屏幕尺寸 | 【已在浏览器实测】确认占用 |
| `clientWidth/clientHeight` 视口尺寸 | 换成 `wx.getSystemInfoSync().windowWidth/windowHeight` | 【已在浏览器实测】确认占用 |
| `classList` 控制反馈条显隐（CSS） | 小游戏无 CSS，名称反馈需改为 canvas 内绘制文本或开放数据域 | 【已在浏览器实测】确认占用 |
| `window.addEventListener`（resize/orientationchange） | 换成 `wx.onWindowResize` | 【已在浏览器实测】确认占用 |
| `window.addEventListener`（mousemove/mouseup） | 小游戏**没有鼠标**，该通路整条删除（触摸通路已独立实现，直接可用） | 【已在浏览器实测】确认占用 |
| `touchstart/move/end/cancel` | 换成 `wx.onTouchStart/onTouchMove/onTouchEnd/onTouchCancel`，事件字段名基本一致 | 【已在浏览器实测】双通路已实现 |
| `performance.now()` | 小游戏可用 `Date.now()` 或 `wx.getPerformance()` | 【根据官方资料推断】 |
| `requestAnimationFrame`（`renderer.setAnimationLoop`） | 小游戏提供全局 `requestAnimationFrame` | 【根据官方资料推断】 |
| `ResizeObserver` | 小游戏无此 API，已有 `typeof !== 'undefined'` 降级分支可兜底 | 【已在浏览器实测】已写降级 |
| CSS（渐变背景 / 安全区 / `touch-action`） | 小游戏无 CSS，背景需改为 `renderer.setClearColor` 或天空盒 | 【已在浏览器实测】确认占用 |

### 7.2 是否依赖 window / document / HTML / CSS

| 层 | 结论 | 分类 |
|---|---|---|
| **业务渲染核心**（world / cameraRig / lighting / picker / selection） | **完全不依赖** window、document、HTML、CSS | 【已在浏览器实测】逐文件清点确认 |
| **业务外壳**（main / controls / label） | 依赖 window、document、CSS，但集中且薄 | 【已在浏览器实测】逐文件清点确认 |
| **Three.js 库内部** | **依赖** `document`、`window`（如 `createElementNS`、canvas 创建、特性探测） | 【根据官方资料推断】腾讯云文章明确记录小游戏里 `createElementNS` 不被支持、需打补丁或经适配层 |
| **HTML 入口** | 小游戏没有 HTML，入口是 `game.js` + `game.json` | 【根据官方资料推断】 |

**关键判断**：**HTML/CSS 可以重写，但 three 库内部的 DOM 假设无法靠改业务代码消除**——
这是必须引入适配层的根本原因。

### 7.3 是否依赖 WebGL 扩展

| 项 | 结论 | 分类 |
|---|---|---|
| 原型显式调用的扩展 | **0 个** | 【已在浏览器实测】源码确认无 `getExtension` 调用 |
| 渲染实际使用的核心能力 | WebGL2 核心：深度缓冲、阴影贴图（`PCFSoftShadowMap`）、alpha 混合 | 【已在浏览器实测】 |
| 环境提供的扩展数 | 30（但**非必需**） | 【已在浏览器实测】 |
| 阴影实现是否依赖特殊扩展 | 标准深度纹理路径，不需要 `WEBGL_depth_texture` 等（WebGL2 已内置） | 【根据官方资料推断】 |
| 小游戏 WebGL1 机型 | 若目标机只有 WebGL1，three 可降级，但阴影与部分特性表现会变 | 【尚未验证】 |

**这是本次预研的利好结论**：因为零贴图、零压缩纹理、零浮点纹理，
原型对 WebGL 扩展的依赖几乎为零，**大幅降低了小游戏适配的扩展兼容风险**。

### 7.4 微信小游戏中需要替换哪些画布 / 触摸 / 资源加载接口

| 类别 | 浏览器侧（现状） | 小游戏侧（需替换为） | 分类 |
|---|---|---|---|
| **画布** | `document.getElementById('stage')` 得到 canvas | 小游戏自带全局 `canvas`；`const ctx = canvas.getContext('webgl')`，再 `new THREE.WebGLRenderer({ canvas, context: ctx })` | 【根据官方资料推断】 |
| **视口尺寸** | `appEl.clientWidth/Height` + `window.devicePixelRatio` | `wx.getSystemInfoSync()` 的 `windowWidth/windowHeight/pixelRatio`；`wx.onWindowResize` | 【根据官方资料推断】 |
| **触摸** | `touchstart/move/end` + `getBoundingClientRect()` | `wx.onTouchStart/onTouchMove/onTouchEnd`；事件里 `touches[i].clientX/clientY` 语义基本一致（本次触摸通路已独立实现，改绑定即可） | 【根据官方资料推断】 |
| **鼠标** | `mousedown/move/up` + `wheel` | **直接删除**——小游戏无鼠标、无滚轮；缩放只保留双指捏合（已实现） | 【根据官方资料推断】 |
| **资源加载** | 无任何加载器，零外部资源 | **无需替换**——本次零贴图零模型，直接绕开 | 【已在浏览器实测】 |
| **动画循环** | `renderer.setAnimationLoop` | 小游戏提供全局 `requestAnimationFrame` | 【根据官方资料推断】 |
| **DOM 文本反馈** | `#label` div + CSS | canvas 内绘制，或改用小游戏开放数据域 | 【尚未验证】 |
| **WASM** | 未使用 | 未使用，无需 `WXWebAssembly` | 【已在浏览器实测】未使用 |

### 7.5 是否存在已知适配器

存在，公开资料可查（**均未在本机验证**）：

| 适配器 | 说明 | 分类 |
|---|---|---|
| `threejs-miniprogram` + `weapp-adapter` | 腾讯官方方向。文章记录了完整改动：小游戏已备好 canvas，只需 `canvas.getContext('webgl')` 并把它作为 `context` 传给 `WebGLRenderer`；`createElementNS` 不被支持需要处理 | 【根据官方资料推断】 |
| `three-platformize`（社区） | 明确宣称已适配微信小游戏（真机 ✔️ / 模拟器 ✔️），支持 tree-shaking，适配了 `GLTFLoader`、`TextureLoader` 等，并列出**不支持**模块（如 `ImageBitmapLoader`，因微信小程序未开放 ImageBitmap） | 【根据官方资料推断】 |
| 微信 8.0 后的 WASM 限制 | 官方文章提到 WebAssembly API 需改用 `WXWebAssembly` 且只支持包内 wasm | 【根据官方资料推断】 |

> 适配器存在≠能直接用。本次用的 three r186 是相当新的版本，适配器是否跟进
> **完全未验证**，这是落地前必须实测的第一件事。

### 7.6 当前是否真正通过微信开发者工具验证

**❌ 没有。微信端未验证。**

环境里没有微信开发者工具，且任务明令禁止安装。
因此本报告**不声称任何微信小游戏兼容性**。所有微信相关条目均为
【根据官方资料推断】或【尚未验证】。

---

## 8. 未来微信适配风险

按"风险 × 不确定性"排序：

| # | 风险 | 影响 | 分类 | 建议的验证动作 |
|---|---|---|---|---|
| 1 | **适配器与 three r186 的版本兼容性未知** | 可能需降级 three 或自行打补丁 | 🔴 未验证 | 落地第一步：在小游戏项目里跑通最小 three 场景 |
| 2 | **three 内部 `document`/`window` 假设**（`createElementNS` 等） | 可能黑屏，且报错信息晦涩 | 🟡 官方资料有记录 | 用适配层 + 真机调试模式复现并修复 |
| 3 | **触摸事件语义差异** | 旋转/点击判定错位 | 🟡 推断，字段名接近 | 真机上跑 10 次旋转 + 4 次点击（可直接复用本目录 e2e 用例思路） |
| 4 | **阴影 + 半透明在低端机表现** | 画面变黑、性能掉帧 | 🔴 未验证 | 真机跑分；准备"关阴影"降级开关（`shadowMap.enabled = false` 一行） |
| 5 | **WebGL1 降级路径** | 老机型无法运行 | 🔴 未验证 | 明确最低机型，或在适配层强制 WebGL1 跑一遍 |
| 6 | **小游戏包体与分包** | 557 KB 在 4 MB 内很安全，但以后加音频/模型会膨胀 | 🟡 推断 | 建立包体预算与分包策略 |
| 7 | **DOM 文本反馈无法直接用** | 名称提示条要重做 | 🔴 未验证 | 改为 canvas 内绘制或开放数据域 |
| 8 | **CSS 背景渐变失效** | 天空变纯黑 | 🟢 已定位 | 改为 `renderer.setClearColor` 或加一个天空盒 |
| 9 | **`performance.now()` / `ResizeObserver` 等 API 缺失** | 交互计时、尺寸自适应失效 | 🟡 推断 | 已有降级分支，改绑 `wx` 对应 API |
| 10 | **真机性能完全未知** | 帧率可能不达标 | 🔴 未验证 | 真机实测帧率；本次全是软件渲染，帧率数据无参考价值 |

**综合判断**：微信适配的核心工作量在
「**替换 canvas 获取 + 替换触摸绑定 + 引入适配层**」这三件事上，
**渲染与业务逻辑基本不用动**。最大的不确定性是**适配层与 three 新版的兼容性**，
这是落地前必须先用一天时间打掉的钉子。

---

## 9. 对正式项目的推荐

### 9.1 推荐结论

**推荐方案 A：Three.js + TypeScript + Vite。**

不是因为它"最先进"，而是因为它在这三个约束下同时最优：
**① 要能在 NAS 上无头构建；② 要能持续加内容；③ 要能移植微信小游戏。**

方案 B 省下的 557 KB 换不回自研渲染层的人力成本；
方案 C 的编辑器绑定会牺牲工程灵活性，且本次完全未实测、不足以支撑决策。

### 9.2 建议的落地路线

**第 0 步（1–2 天，最高优先级）：先把微信适配的钉子打掉。**
用 three r186 在小游戏项目里跑通"一个立方体 + 一次触摸旋转 + 一次射线点击"。
如果适配器不兼容 r186，此刻就能知道要降级到哪个版本——**这是整个方案最大的未知数，
必须最早验证，不能等到开发后期**。

**第 1 步：把本次原型的架构直接带过去。**
这些设计已经过实测，建议原样保留：

- **鼠标/触摸双通路**（`controls.ts`）——小游戏只需删掉鼠标那条
- **纯 `Raycaster` 拾取 + `userData` 标签**（`picker.ts` + `PICK_TAG`）——新对象打标签即自动可点
- **按顶点实测 + 分轴求解的取景**（`world.ts` `measureFraming` + `cameraRig.ts`）——竖屏/横屏自适应
- **零贴图、纯几何 + 低多边形**——省掉资源加载适配，换肤靠 `palette.ts` 色值
- **独立 `Group` 组织每个建筑/居民**——升级、寻访、装扮的天然接入点

**第 2 步：内容层的三个扩展点（已在本次原型中预留）**

| 玩法 | 接入方式 |
|---|---|
| 建筑升级 | 建筑是独立 `Group`；升级 = 切换子网格组合 + `userData.level`；拾取已能区分对象，点击触发升级面板即可 |
| 居民寻访 | 居民是独立 `Group` + 可拾取；寻访 = tween `position`/`rotation`，或挂 `AnimationMixer` |
| 城市装扮 | 装饰物已是独立构建函数；换肤 = 改 `palette.ts` 色值或替换几何体，**零贴图所以成本极低** |

**第 3 步：工程约束**
- **锁定 three 版本**（`package.json` 用精确版本号而非 `^`），升级前必须先过小游戏验证
- 保留 `tsc --noEmit` + 构建 + E2E 三道关卡作为提交门禁
- E2E **必须断言"画面真的变了"**（投影位移 / 截图差异），不能只断言计数器——
  本次正是靠这条断言抓出了"旋转状态变了但相机矩阵没重写"的严重缺陷

### 9.3 如果小游戏验证失败怎么办

若第 0 步发现适配器与新 three 不兼容且短期无法解决：
1. **首选**：降级 three 到适配器支持的版本（本原型只用到了极稳定的核心 API，
   相机/射线/Lambert 材质在各版本间差异很小，降级成本低）
2. **次选**：方案 C（LayaAir）—— 但要重新评估编辑器绑定与团队学习成本
3. **不建议**：方案 B —— 除非团队有专职图形学工程师且项目周期充裕

---

## 10. 与 MIMO 的对比表

> **⚠️ 隔离声明**：按任务强制隔离规则，DSH **没有**读取 MIMO 的目录
> （`/vol1/ai/projects/wyszz-new/3d-spike-mimo/`）、源码、报告、截图或日志。
> 因此下表 MIMO 一列**全部保留为"待主控方填入"**，
> **没有任何推测、编造或间接引用**。

| 项目 | DSH | MIMO |
|---|---|---|
| 使用方案 | Three.js 0.186.1 + TypeScript 5.9.3 + Vite 8.3.3（方案 A），运行时依赖仅 1 个 | 待主控方填入 |
| 构建是否成功 | ✅ 成功。`tsc --noEmit` 0 错误；`vite build` 0.4 秒，产物 557.73 KB / gzip 139.37 KB | 待主控方填入 |
| 旋转是否成功 | ✅ 成功。鼠标拖动 **10/10** 次（方位角 Δ−0.868 rad）、触摸拖动 **10/10** 次（Δ−0.868 rad）；市政厅屏幕投影实测移动 70.9 px / 68.0 px，证明画面真的在转 | 待主控方填入 |
| 射线点击是否成功 | ✅ 成功。`THREE.Raycaster` 真实射线命中市政厅 / 建筑·民居 / 建筑·商店 / 居民，名称全部正确；空白处负样本正确不命中 | 待主控方填入 |
| 竖屏适配 | ✅ 成功。4 种竖屏尺寸（390×844 / 360×780 / 430×932 / 320×568）均无横纵溢出；按顶点实测 + 分轴求解取景距离，岛宽占画面约 87% | 待主控方填入 |
| 构建包体 | JS 557,730 B（gzip 139,365 B）＋ CSS 1,999 B ＋ HTML 1,337 B；`dist/` 合计 564 KB / gzip 约 141 KB；`node_modules` 130 MB | 待主控方填入 |
| 微信适配结论 | ⚠️ **微信端未验证**（无微信开发者工具，且任务禁止安装），**不声称兼容**。已定位需替换项：canvas 获取、视口尺寸、触摸绑定（鼠标通路删除）、CSS 反馈条、适配层引入；原型显式使用的 WebGL 扩展为 **0 个** | 待主控方填入 |
| 主要风险 | ① 小游戏适配器与 three r186 的兼容性未知（最大不确定项）② three 内部 `document`/`window` 假设需靠适配层解决 ③ 真机性能与 WebGL1 降级路径未验证 ④ 阴影+半透明在低端机表现未知 | 待主控方填入 |

### 补充对比字段（建议主控方一并核对）

| 项目 | DSH | MIMO |
|---|---|---|
| 源码文件数 | `src/` 10 个 `.ts` + 1 个 `.css`（1355 行）；含入口与 E2E 共约 1861 行 | 待主控方填入 |
| 运行时依赖数 | 1（three） | 待主控方填入 |
| 依赖总数（含开发） | 52 | 待主控方填入 |
| 相机类型 | 透视 FOV 35°（低透视） | 待主控方填入 |
| 缩放实现 | 有：滚轮 + 双指捏合（两种） | 待主控方填入 |
| 阴影 | 有：平行光 1024² PCFSoft | 待主控方填入 |
| 贴图 / 外部资源 | 0 | 待主控方填入 |
| 控制台错误数 | 0 | 待主控方填入 |
| 自动化验收 | 无头 Chromium + CDP 真实鼠标/触摸事件，`scripts/e2e.mjs`，结果落盘 `docs/e2e-results.json` | 待主控方填入 |
| 微信开发者工具验证 | ❌ 未验证 | 待主控方填入 |
| 真机验证 | ❌ 未验证 | 待主控方填入 |
| 已知环境坑 | NAS `fs.inotify.max_user_instances=128` 已被占满（实测在用 175），`vite dev` 报 EMFILE；已加 `SPIKE_POLL=1` 轮询规避，`build`/`preview` 不受影响 | 待主控方填入 |

---

## 附录 A：交付清单（全部绝对路径）

```
/vol1/ai/projects/wyszz-new/3d-spike-ds/README.md
/vol1/ai/projects/wyszz-new/3d-spike-ds/index.html
/vol1/ai/projects/wyszz-new/3d-spike-ds/package.json
/vol1/ai/projects/wyszz-new/3d-spike-ds/package-lock.json
/vol1/ai/projects/wyszz-new/3d-spike-ds/tsconfig.json
/vol1/ai/projects/wyszz-new/3d-spike-ds/vite.config.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/main.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/style.css
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/scene/world.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/scene/cameraRig.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/scene/lighting.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/scene/selection.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/scene/palette.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/input/controls.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/input/picker.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/ui/label.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/src/debug/hook.ts
/vol1/ai/projects/wyszz-new/3d-spike-ds/scripts/e2e.mjs
/vol1/ai/projects/wyszz-new/3d-spike-ds/shots/01-default-island.png
/vol1/ai/projects/wyszz-new/3d-spike-ds/shots/02-rotated-island.png
/vol1/ai/projects/wyszz-new/3d-spike-ds/shots/03-click-label.png
/vol1/ai/projects/wyszz-new/3d-spike-ds/docs/DSH-3D技术预研报告.md
/vol1/ai/projects/wyszz-new/3d-spike-ds/docs/e2e-results.json
/vol1/ai/projects/wyszz-new/3d-spike-ds/dist/            （构建产物，可重新生成）
```

## 附录 B：命令速查

```bash
cd /vol1/ai/projects/wyszz-new/3d-spike-ds

npm install                        # 安装依赖（52 个包，约 18 秒）
npm run typecheck                  # 类型检查：tsc --noEmit
npm run build                      # 生产构建：输出 dist/
npm run preview                    # 竖屏浏览器预览：http://127.0.0.1:5181
SPIKE_POLL=1 npm run dev           # 开发服务器：http://127.0.0.1:5180（本 NAS 需轮询）

# 自动化验收（需先启动 preview）
npm run e2e                        # 全流程断言，结果写入 docs/e2e-results.json
```

## 附录 C：环境与依赖实测版本

```
主机        : homeNAS / Debian GNU/Linux 12 (bookworm) / 16 核 / 15 GB
Node.js     : v24.15.0
npm         : 11.12.1
Chromium    : 154.0.8037.57（无头，ANGLE + SwiftShader 软件渲染）
WebGL       : WebGL 2.0 (OpenGL ES 3.0 Chromium)，30 个可用扩展

运行时依赖  : three@0.186.1
开发依赖    : typescript@5.9.3, vite@8.3.3, @types/three@0.186.0,
              @types/node@24.19.1, puppeteer-core@25.12.0
```

## 附录 D：删除本次实验的方法

**本次实验没有创建任何 Docker 容器。** 全部在宿主机上以 Node.js + 系统 Chromium 运行，
未修改 `docker-compose.yml`，未改动 NAS 权限、共享、网络、防火墙或任何现有容器。

```bash
# 1) 停掉可能仍在运行的预览 / 开发服务
pkill -f "3d-spike-ds" || true

# 2) 确认目标路径无误（不可恢复操作前必须核对）
ls -d /vol1/ai/projects/wyszz-new/3d-spike-ds

# 3) 删除实验目录
rm -rf /vol1/ai/projects/wyszz-new/3d-spike-ds
```

---

**报告结束。**
本任务为 DSH 独立对照实验。MIMO 不得读取、修改或删除本目录。
DSH 也不得读取或修改 MIMO 的工作目录。
