# 65 · S-40 任务书：城市建模（可迁移模块库，与 0.3.5 应收并行）

> 机主 2026-10-27：「再给我发城市建模的任务并行进行，要保证建模方便迁移」。
> 与 S-30 封版**并行**：S-40 在**独立树** `frontend-rebuild-hm044-city` 里做，绝不碰 `hm035`（S-30 正在写它）。
> 目标不是"再做一个 demo"，而是产出**能整块搬进游戏的模块库 + 迁移契约**，让 S-31 只剩「接线」。

## 任务书 S-40

```
S-40

【开工第一件事·防截断】用 create_goal 把本任务立为持久目标（objective = S-40 城市建模（可迁移）：在独立树 hm044-city 产出 src/render/city/** 模块库 + CITY_API 迁移契约 + demo 渲染 + 性能表，保证整块搬进游戏只需接线）；每完成一个里程碑 update_goal 记进度；大段内容先落文件再给摘要；完成后再 update_goal complete。

你是实现工程师兼协调者，任务代号 S-40。用中文回复，每 30 分钟一行进度写 `tasks-out/S-40/进度.md`。

【开工前置】
1. 先读：`frontend-rebuild-hm/tasks-out/S-28/说明.md` + `迁移清单.md`、`S-29/说明.md` + `交付模块清单.md`、`docs/47`（0.4.0 城市风格原型）、`docs/49`（0.4.0 二轮城市内容）、`docs/52`（S-31 迁移任务书，了解将来怎么接）。
2. 建独立树（**只读复制，别改源**）：
   `rsync -a --exclude dist/ --exclude evidence/ --exclude node_modules/ /vol1/ai/projects/wyszz-new/frontend-rebuild-hm035/ /vol1/ai/projects/wyszz-new/frontend-rebuild-hm044-city/`
   写开工快照 `tasks-out/S-40/开工sha256.txt`。
3. **硬边界**：S-30 正在写 `hm035`；你**只许写** `frontend-rebuild-hm044-city/src/render/city/**`、`.../tools/city-demo/**`、`.../test/city-*.mjs`、`frontend-rebuild-hm/tasks-out/S-40/**`、`/tmp/s40/**`。**禁止**改 `hm044-city` 里的 `src/app/**`、`src/ui/**`、`src/render/world.ts`、`src/render/camera.ts`（这些留给 S-31 接线改）；禁止动 `hm035` 与其它树。

【目标：可迁移的城市模块库（迁移成本 = 接线，不是重写）】
1. `src/render/city/**` 分层，模块**不许 import 任何 src/app、src/ui、src/game 的东西**（只能用 three + 本目录 + 纯数据），保证能 Node 单测：
   - `city-contract.ts`：唯一入口 `buildCity(ctx: CityBuildCtx): CityBuildResult`；
     `CityBuildCtx = { blocks: BlockDesc[]; hallTier: 0..4; style: 'A'|'B'|'C'; traffic: 0|1|2; ped: 0|1|2; seed: number }`；
     `CityBuildResult = { root: THREE.Group; stats: {triangles, drawCalls, materials, meshes}; pickables: {blockId, object: THREE.Object3D}[] }`
   - `layout.ts`（街区布局规则）、`tier-residential.ts` / `tier-commercial.ts` / `hall.ts` / `park.ts` / `commercial.ts` / `landmark.ts` / `industry.ts`（内容库）、`props.ts`（树/灯/长椅/车/人）、`traffic.ts` / `pedestrians.ts`（InstancedMesh + 纯函数位置）、`materials.ts`（共享材质缓存）、`style-a|b|c.ts`（配色/密度参数，不复制几何代码）。
2. **迁移契约文件** `src/render/city/CITY_API.md`（必须写）：模块清单、每个导出函数签名、单位/坐标系、颜色表、tier 映射规则、性能预算、装配示例 20 行内可跑、`pickables` 语义、禁止事项（不许贴图/不许 window/wx/不许读配置）。
3. **可确定性**：所有随机用 `seed` 传入的确定性 RNG（`mulberry32` 之类，自己实现），同 seed 两次构建几何顶点逐位一致（测试断言）。
4. **内容范围（对齐 S-28/S-29）**：
   - 4 类建筑 × tier 0..4 外观（市政厅 hall 有 0..4 与满级形态；居民楼 tier 随等级长高；社区商店；公园）；
   - 街区地块（草地/路/水/地标/工业）与连接规则；
   - 三画风 A 清爽 / B 细节派（默认）/ C 霓虹夜景：**同一份几何，只换材质与灯光参数**；
   - 车流/行人 关/低/高（三档密度，InstancedMesh，纯函数轨迹，无累积误差）；
   - 纯程序化、顶点色/共享材质、无贴图、无外部资源。
5. **demo 渲染**：`tools/city-demo/` 下能起一个静态页（构建产物 + 截图脚本），5 屏 × 3 画风、车人三档、85 块满岛截图，全部落 `tasks-out/S-40/截图/`。

【测试】
- `test/city-contract.test.mjs`：入口签名/返回结构/pickables 完整、同 seed 顶点逐位一致、无 window/wx 引用（静态扫描 import）、三画风同几何（顶点数一致）、车人三档实例数正确、85 块满岛预算（三角形 ≤150k、draw call ≤70、材质数 ≤12）。
- `test/city-migration.test.mjs`：写一个 **host shim**（模拟将来的 `world.ts`：传入假 blocks/ctx，断言 `buildCity` 无需改动即可装配、pickables 能按 blockId 找到、dispose 能清干净）。
- 测试必须 Node 可跑（`node --test`），不依赖浏览器；截图用现有 puppeteer 工具链。

【子智能体（1 主 + 4 子并行）】10 分钟开工。
- 主对话（你）：contract 与装配、迁移契约文档、整体质量与交付。
- C1「内容库：建筑」：4 类建筑 × tier 0..4（含 hall 满级）+ 地标，纯函数工厂。
- C2「内容库：街区/道具/车流/行人」：地块与连接、树灯长椅、车/人 InstancedMesh 三档。
- C3「三画风 + 材质系统」：A/B/C 参数化（同几何换材质灯光）、共享材质缓存、夜晚霓虹。
- C4「demo + 截图 + 性能」：demo 页、5 屏 × 3 画风、车人档位、85 块预算读数、复刻审计（无贴图/实例化/材质数）。
提示词原样转发、禁止嵌套、目录写死、关键数字抽查（三角形/draw call/材质数/实例数）。

【验收（缺一不可）】
- `CITY_API.md` 齐（签名/坐标系/tier 规则/装配示例可跑/禁止事项）；`buildCity` 单入口，模块 0 处 import `src/app|src/ui|src/game`（静态扫描断言）；
- 同 seed 两次构建顶点逐位一致；三画风几何顶点数一致（只换材质/灯）；
- 4 类建筑 × tier 0..4 全部有实现与截图；hall 满级形态存在；街区连接规则有测试；
- 车流/行人三档实例数与密度单调；关闭后实例数 0；
- 85 块满岛：三角形 ≤150k、draw call ≤70、材质数 ≤12、构建耗时 ≤300ms（桌面读数）；
- `city-migration.test.mjs`：host shim 装配成功、pickables 按 blockId 命中、dispose 后几何/材质计数归零；
- 截图 ≥18 张（5 屏×3 画风 + 车人 + 85 块俯视 + hall 满级）；无 pageerror；
- U1「玩家视角锐评」独立出报告（先交机主）：三种画风是否"像 demo"、建筑是否认得出、夜里是否太黑/太花、车人是否假、满岛是否糊；P0=0/P1=0 才收。

【交付】`hm044-city` 源码（只新增 city 目录与工具/测试）+ `CITY_API.md` + 截图 + 性能表 + `tasks-out/S-40/迁移就绪清单.md`（S-31 接线时逐条打勾：入口、ctx 字段、pickables、dispose、设置项注入点）+ `总报告.md`。**不打包、不出码、不接线**。
【时间盒】**6 小时**（可与 S-30 并行；S-31 等 S-30 收口后开始，届时只需按清单接线）。
```
