agentworkshop 0.7.41 → 0.7.46

package/app/components/workshop/town/TownScene3D.ts

@@ -15,773 +15,167 @@
  */
 import * as THREE from 'three'
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
-import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js'
-import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js'
-import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js'
-import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js'
-import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js'
-import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js'
+import type { TransformControls } from 'three/examples/jsm/controls/TransformControls.js'
+import type { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js'
 import type { AepEnvelope } from '#shared/workshop-protocol'
-import { mapEnvelopeToIntent, type TownBubbleKind } from '#shared/town-protocol'
-import { parseActionFromEnvelope, stepToward, type ActionKind, type ActionContext } from '#shared/town-behavior'
+import type { TownBubbleKind } from '#shared/town-protocol'
+import type { ActionKind, ActionContext } from '#shared/town-behavior'
 // 纯几何/色彩/尺度决策层(与测试共用,零渲染依赖)
 import {
-  AGENT_SPEED, ARRIVE, BUBBLE_Y, GROUND_Y, SNAP_SIZE, UNITS, WAIT_MS,
-  WORLD_CX, WORLD_CZ, WORLD_H, WORLD_W,
-  boundaryPoints, bubbleDisplayMs, channelColorNum, drainDisplayMs,
-  clampToAgentRange, clampToBoundary, distToRangeBoundary,
-  normLayout, pointInBoundary, toLocal,
+  WORLD_CX, WORLD_CZ,
   type AgentRangeLayout, type ChannelLayout,
 } from '#shared/town-scene-math'
 
-export type { AgentRangeLayout, ChannelLayout } from '#shared/town-scene-math'
-
-/** 场景 → Vue HUD 事件(TownEventMap 与 2D 同构) */
-export type TownEventMap = {
-  ready: boolean
-  fps: number
-  agentCount: number
-  blockCount: number
-  lastActivity: { channelId: string, agentName: string, text: string, at?: number } | null
-  behavior: { agentName: string, action: string, targetName: string | null } | null
-  /** 选中 Agent/设备(供 Vue 弹缩放/旋转滑杆);null 取消选中 */
-  select: { kind: 'agent' | 'device', id: string, scale: number, rotation: number } | null
-  /** 选中频道(供 Vue 边界编辑面板);null 取消 */
-  selectChannel: string | null
-  /** 频道布局被拖拽/手柄调整(供 Vue 刷新边界面板草稿);null 取消 */
-  channelResized: { channelId: string, layout: ChannelLayout } | null
-  /** Agent 活动范围被框选绘制/拖移/手柄调整/清除(供 Vue 刷新对象面板草稿);null 取消 */
-  agentRangeChanged: { agentId: string } | null
-  /** 动画状态切换(数据驱动:Agent 在 idle/walk 之间切换时广播);null 表示无 */
-  motion: { agentName: string, anim: 'idle' | 'walk', at: number } | null
-  /** 场景保存状态(设备/角色布局持久化进度) */
-  saveState: { state: 'idle' | 'dirty' | 'saving' | 'saved' | 'error', at: number } | null
-}
-
-/** 编辑 / 浏览模式:浏览只读(相机+点选),编辑可拖拽设备/调整角色落点 */
-export type TownScene3DMode = 'browse' | 'edit'
-
-/** 设备 transform 补丁(拖拽/滑杆结束防抖保存) */
-export interface DeviceTransformPatch {
-  posX?: number
-  posZ?: number
-  rotationY?: number
-  scale?: number
-}
-
-/** syncDevices 输入:与 useDeviceTwins.DeviceTwinView 同构的子集 */
-export interface DeviceTwinSync {
-  id: string
-  name: string
-  modelRef: string
-  /** 实体类别:'device' 常规设备(GLB) / 'daq' 数采节点(程序化网格);后端为宽 string */
-  kind?: string
-  state?: 'idle' | 'running' | 'offline' | 'alarm'
-  telemetry?: Record<string, number | string | boolean>
-  posX?: number
-  posZ?: number
-  rotationY?: number
-  scale?: number
-  /** 所属产线(场景光晕分色依据) */
-  lineId?: string
-  /** 产线光晕色(Hex;同产线节点同色光环) */
-  lineColor?: string
-}
-
-/** 场景内可缩放目标(Agent 或设备节点) */
-interface ScaledTarget {
-  kind: 'agent' | 'device'
-  id: string
-  /** 用户缩放倍率(1 = 默认归一化尺寸) */
-  userScale: number
-  /** 模型子节点(缩放施加于此) */
-  holder: THREE.Group
-}
+// 轨道相机与相机交互自本文件抽出(见 scene/town-scene3d-camera.ts)
+import {
+  autoFrameTo, flyToPreset, focusTo, getAutoOrbit, getCameraPose, orbitBy, panBy, panByScreen,
+  panWorldBy, resetView, screenToWorld, setAutoOrbit, setViewPreset, worldToScreen, zoomBy,
+} from './scene/town-scene3d-camera'
+// 渲染核心初始化自本文件抽出(见 scene/town-scene3d-renderer.ts)
+import { initRendererCore } from './scene/town-scene3d-renderer'
+// 类型契约 / 面向对象节点(Channel 领地 / 角色 / 数字孪生设备)自本文件抽出,
+// 只通过宿主契约回调场景 —— 细节见 town-scene3d-types.ts 与 town-scene3d-nodes.ts
+// 信息接收器 + 聊天气泡自本文件抽出(见 scene/town-scene3d-bubbles.ts)
+import { drainReceivers, enqueueBubble } from './scene/town-scene3d-bubbles'
+// 数采绑定链路 + 薄膜 web 自本文件抽出(见 scene/town-scene3d-links.ts)
+import { deviceTopY, rebuildFilmWeb, refreshDaqLinks, syncDaqLinks } from './scene/town-scene3d-links'
+// 事件共鸣 + 行为 FSM 入口 + WS 事件入口自本文件抽出(见 scene/town-scene3d-events.ts)
+import { behaviorActionLabel, emitResonance, handleTownEvent, startBehavior } from './scene/town-scene3d-events'
+// 调试 / HUD 数据面自本文件抽出(见 scene/town-scene3d-hud.ts)
+import { getDebugState, getMinimapState, getRecentActivity } from './scene/town-scene3d-hud'
+// 数字孪生设备节点层自本文件抽出(见 scene/town-scene3d-devices.ts)
+import {
+  getDeviceModelRef, getDeviceName, getDeviceNodes, persistAllDevices, persistDeviceTransform,
+  recreateDeviceNode, removeDevice, renameDevice, renameDeviceSprite, spawnDeviceNode,
+  swapDeviceModel, swapDeviceModelSprite, syncDevices, updateDeviceNode,
+} from './scene/town-scene3d-devices'
+// GLB 加载与 PBR 材质增强自本文件抽出(见 scene/town-scene3d-models.ts)
+import { enhancePbrMaterials } from './scene/town-scene3d-models'
+// 角色节点层 + 模型库挂载自本文件抽出(见 scene/town-scene3d-agents.ts)
+import {
+  dropModelOnWorld, ensureAgent, getAgentClips, getAgentModel, getAgentName,
+  registerModelsFromList, setAnimPref, swapAgentModel,
+} from './scene/town-scene3d-agents'
+// 频道领地放置层自本文件抽出(见 scene/town-scene3d-blocks.ts)
+import {
+  applyLayoutToBlock, applySceneLayouts, blockLayout, buildBlocks, dropChannelOnWorld,
+  getAllChannelLayouts, getCameraTarget, getChannelLayout, hasChannel, placedChannels,
+  removeChannel, trackLayout, updateChannelLayout,
+} from './scene/town-scene3d-blocks'
+// 渲染循环 + 画质阶梯自本文件抽出(见 scene/town-scene3d-loop.ts)
+import { adaptQuality, applyPixelRatio, applyQuality, setQualityMode, startRenderLoop } from './scene/town-scene3d-loop'
+// 拾取 / 选中 / 缩放旋转自本文件抽出(见 scene/town-scene3d-selection.ts)
+import {
+  getModelRotation, getSelectedChannel, getSelectedScale, isGizmoBusy, persistScale, pickAt,
+  pickBeacon, pickChannel, pickChannelEdge, registerScalable, selectChannel, setExposure,
+  setModelRotation, setModelScale, setSelected, setTerritoryOpacity, setTransformMode,
+} from './scene/town-scene3d-selection'
+// 实例资源释放与整场重置自本文件抽出(见 scene/town-scene3d-lifecycle.ts)
+import {
+  dispose as disposeScene, disposeAgentAssets, disposeCanvasTextures, disposeDeviceAssets,
+  resetAll as resetScene,
+} from './scene/town-scene3d-lifecycle'
+// 编辑/浏览模式 + 场景对象拖拽(设备/角色/频道/边界手柄)自本文件抽出(见 scene/town-scene3d-editing.ts)
+import {
+  applyBlockMove, applyResize, boundaryHandlePoints, clampAgentsToBoundary, endPointerDrag, getMode,
+  getSnap, isPointerDragging, movePointerDrag, pickResizeHandle, refreshChannelHandles, setMode,
+  setSnap, snapWorld, tryStartPointerDrag,
+} from './scene/town-scene3d-editing'
+// Agent 独立活动范围(框选绘制/整框平移/手柄缩放/面板读写)自本文件抽出(见 scene/town-scene3d-ranges.ts)
+import {
+  applyAgentRangeResize, cancelRangeDraw, clearAgentRange, commitAgentRange, emitAgentRangeChanged,
+  getAgentRange, hitAgentRangeBoundary, isRangeDrawing, pickAgentRangeHandle, rangeLineVisible,
+  rangeLineVisibleFor, refreshAgentRangeHandles, refreshAgentRangeLines, setAgentRangeScene,
+  startRangeDraw, updateRangeDrawPreview,
+} from './scene/town-scene3d-ranges'
+import type { Agent3D, Block3D, DeviceNode } from './scene/town-scene3d-nodes'
+import type {
+  AgentHost, AgentRangeHandle, BlockHost, ChannelMessageReceiver, ChannelResizeHandle, DaqLink,
+  DeviceApi, DeviceHost, DeviceTwinSync, ModelInfo, PointerDragState, ScaledTarget,
+  SelectedTarget, TownEntityInput, TownEventMap, TownScene3DMode, TownSceneHost,
+} from './scene/town-scene3d-types'
 
-/** 与 2D TownEntityInput 同构的实体基线 */
-export interface TownEntityInput {
-  channelId: string
-  channelName: string
-  agents: Array<{
-    agentId: string
-    name: string
-    role: 'lead' | 'worker'
-    harness: string
-    state: 'idle' | 'busy' | 'stopped'
-    currentTaskId?: string | null
-    currentTaskTitle?: string | null
-    currentTaskProgress?: number | null
-    modelRef?: string | null
-    /** 管理员布局落点(来自 config.homeX/homeZ;缺省 = 领地环形排布) */
-    homeX?: number | null
-    homeZ?: number | null
-    /** 管理员布局活动范围(来自 config.range;缺省 = 沿用频道边界) */
-    range?: AgentRangeLayout | null
-  }>
-}
+export type { AgentRangeLayout, ChannelLayout } from '#shared/town-scene-math'
+export {
+  Block3D, Agent3D, DeviceNode, makeBoundary,
+} from './scene/town-scene3d-nodes'
+export type {
+  BehaviorState, BubbleMsg, ChannelMessageReceiver, DeviceTransformPatch,
+  DeviceTwinSync, ModelInfo, ScaledTarget, TownEntityInput, TownEventMap, TownScene3DMode,
+} from './scene/town-scene3d-types'
 
 /** 频道布局(3D 小镇放置):与共享 AepSceneLayout/useSceneLayouts 同构 —— 定义见 #shared/town-scene-math */
 
 /** Agent 独立活动范围(编辑模式框选绘制/手柄调整;经 config.range 持久化)。
  *  缺省(null)= 未设置,该 Agent 沿用频道边界活动。 —— 定义见 #shared/town-scene-math */
 
-/** 频道领地 3D 实例(面向对象:持有布局/网格/成员,封装移动/边界/成员钳制等行为)。
- *  数据来自 scene-layouts 持久化,由场景按数据库元数据实例化,并注入宿主控制器。 */
-class Block3D {
-  channelId!: string
-  name!: string
-  x!: number
-  z!: number
-  radiusX!: number
-  radiusZ!: number
-  shape!: 'ellipse' | 'rect'
-  rotationY!: number
-  color!: number
-  platform!: THREE.Mesh
-  /** 领地边缘发光环(工业孪生边界告示;随平台移动) */
-  padRing!: THREE.Mesh
-  /** 中央信标(HMI 定位销:点击 → 定位频道中心 + 唤醒边界编辑) */
-  beacon!: THREE.Group
-  /** 活动边界(编辑高亮) */
-  boundary!: THREE.LineLoop
-  label!: THREE.Sprite
-  /** 本频道的 Agent3D 成员实例(面向对象聚合) */
-  members: Agent3D[] = []
-  /** 宿主场景控制器(实例化后注入;提供跨实体服务) */
-  host!: TownScene3D
-
-  constructor(init: {
-    channelId: string
-    name: string
-    x: number
-    z: number
-    radiusX: number
-    radiusZ: number
-    shape: 'ellipse' | 'rect'
-    rotationY: number
-    color: number
-    platform: THREE.Mesh
-    padRing: THREE.Mesh
-    beacon: THREE.Group
-    boundary: THREE.LineLoop
-    label: THREE.Sprite
-  }) {
-    Object.assign(this, init)
-  }
-
-  /** 当前布局(与共享 ChannelLayout 同构;供边界面板/落库/E2E) */
-  layout(): ChannelLayout {
-    return { channelId: this.channelId, x: this.x, z: this.z, radiusX: this.radiusX, radiusZ: this.radiusZ, shape: this.shape, rotationY: this.rotationY }
-  }
-
-  /** 归一化布局(radius 钳制下限) */
-  normLayout(): ChannelLayout {
-    return normLayout(this.layout())
-  }
-
-  /** 边界手柄本地坐标(矩形四角 / 椭圆轴向四点;radius 是半轴或半宽)。 */
-  handlePoints(): Array<[number, number]> {
-    if (this.shape === 'rect') return [[this.radiusX, this.radiusZ], [-this.radiusX, this.radiusZ], [-this.radiusX, -this.radiusZ], [this.radiusX, -this.radiusZ]]
-    return [[this.radiusX, 0], [-this.radiusX, 0], [0, this.radiusZ], [0, -this.radiusZ]]
-  }
-
-  /** 世界点是否落在领地边界内(点选/命中判定) */
-  pointIn(x: number, z: number): boolean {
-    return pointInBoundary(this.layout(), x, z)
-  }
-
-  /** 整体平移:更新中心、平台/边界/名牌网格,并携带全部成员落点与各自活动范围(行为内聚) */
-  moveBy(dx: number, dz: number): void {
-    this.x += dx
-    this.z += dz
-    this.platform.position.set(this.x, 0.16, this.z)
-    this.padRing.position.set(this.x, 0.32, this.z)
-    this.beacon.position.set(this.x, 0, this.z)
-    this.boundary.position.set(this.x, 0.3, this.z)
-    this.boundary.rotation.y = this.rotationY * Math.PI / 180
-    this.label.position.set(this.x, 30, this.z)
-    for (const a of this.members) {
-      a.root.position.x += dx
-      a.root.position.z += dz
-      a.homeX += dx
-      a.homeZ += dz
-      if (a.range) {
-        a.range.x += dx
-        a.range.z += dz
-        a.renderRangeLine()
-      }
-    }
-    this.host.trackLayout(this)
-  }
-
-  /** 按补丁更新布局字段(边界编辑;钳制下限由宿主统一保证) */
-  applyPatch(patch: Partial<ChannelLayout>): void {
-    if (patch.x !== undefined) this.x = patch.x
-    if (patch.z !== undefined) this.z = patch.z
-    if (patch.radiusX !== undefined) this.radiusX = patch.radiusX
-    if (patch.radiusZ !== undefined) this.radiusZ = patch.radiusZ
-    if (patch.shape !== undefined) this.shape = patch.shape
-    if (patch.rotationY !== undefined) this.rotationY = patch.rotationY
-  }
-
-  /** 把成员落点与各自活动范围收进当前频道边界(边界缩放/整体移动后调用) */
-  clampMembersAndRanges(): void {
-    const layout = this.layout()
-    for (const a of this.members) {
-      const c = clampToBoundary(layout, a.root.position.x, a.root.position.z, 16)
-      a.root.position.x = c.x
-      a.root.position.z = c.z
-      a.homeX = c.x
-      a.homeZ = c.z
-      if (a.range) {
-        a.renderRangeLine()
-        const cc = clampToAgentRange(a.range, a.homeX, a.homeZ, 0)
-        if (cc.x !== a.homeX || cc.z !== a.homeZ) {
-          a.homeX = cc.x
-          a.homeZ = cc.z
-          a.root.position.x = cc.x
-          a.root.position.z = cc.z
-        }
-      }
-    }
-    this.host.markDirty()
-  }
-}
-
-/** 边界几何体:椭圆/矩形线框,弯折朝向 rotationY(度)。
- *  轮廓点来自 #shared/town-scene-math.boundaryPoints(纯几何,场景只做渲染)。 */
-function makeBoundary(shape: 'ellipse' | 'rect', rx: number, rz: number, color: number): THREE.LineLoop {
-  const pts = boundaryPoints(shape, rx, rz, 48).map(([x, z]) => new THREE.Vector3(x, 0, z))
-  const geo = new THREE.BufferGeometry().setFromPoints(pts)
-  const line = new THREE.LineLoop(geo, new THREE.LineBasicMaterial({ color, transparent: true, opacity: 0.75, depthTest: false }))
-  return line
-}
-
-/** 归一化边界(radius 钳制下限;rect 用半宽) —— 定义见 #shared/town-scene-math */
-
-/** 把点钳制到频道边界内 —— 定义见 #shared/town-scene-math */
-
-/** 点到边界内判定 —— 定义见 #shared/town-scene-math */
-
-/** 边界/范围的极值点(矩形四角 / 椭圆轴向四点;世界坐标,含 rotationY) —— 定义见 #shared/town-scene-math */
-
-/** 把 Agent 活动范围整体收进频道边界 —— 定义见 #shared/town-scene-math */
-
-/** 把点钳制到 Agent 自己活动范围内 —— 定义见 #shared/town-scene-math */
-
-/** 世界点到活动范围边界线的最近距离 —— 定义见 #shared/town-scene-math */
-
-/** 角色 3D 实例(面向对象:持有模型/状态/行为,封装漫游 FSM、移动钳制、动画、活动范围)。
- *  由场景按 entities/数据库元数据(home/range/modelRef)实例化并注入宿主;动画状态驱动 motion 事件。 */
-class Agent3D {
-  channelId!: string
-  agentId!: string
-  name!: string
-  role!: 'lead' | 'worker'
-  /** 根 Group(位置=落地点,脚底) */
-  root!: THREE.Group
-  /** 模型子节点(换模型时替换) —— 始终存在(空组占位) */
-  model!: THREE.Group
-  mixer!: THREE.AnimationMixer | null
-  /** 当前模型动画 clip(若有) */
-  clips!: THREE.AnimationClip[]
-  /** 身份色(频道哈希色;气泡/小地图等取色数据源) */
-  colorNum!: number
-  /** 头顶名字 Sprite */
-  nameSprite!: THREE.Sprite
-  /** 当前气泡 */
-  bubble!: THREE.Sprite | null
-  /** 当前头顶聊天气泡文本(调试/HUD 用;null = 无气泡) */
-  bubbleText!: string | null
-  bubbleTimer!: ReturnType<typeof setTimeout> | null
-  /** 状态/进度/行为 */
-  state!: 'idle' | 'busy' | 'stopped'
-  progress!: number | null
-  /** 行为 FSM */
-  behavior!: BehaviorState
-  /** 用户拖动中 */
-  dragging!: boolean
-  /** home(行为结束后回归) */
-  homeX!: number
-  homeZ!: number
-  /** 独立活动范围(编辑模式框选/手柄;null = 沿用频道边界) */
-  range!: AgentRangeLayout | null
-  /** 活动范围线框(随 range 渲染;清除/重建时移除) */
-  rangeLine!: THREE.LineLoop | null
-  textureKey!: string
-  modelRef!: string
-  /** 当前动画状态(数据驱动模型:idle/walk;经宿主 motion 事件监听) */
-  animState: 'idle' | 'walk' = 'idle'
-  /** 当前 mixer action(crossfade 切换用;null = 未开始) */
-  activeAction: THREE.AnimationAction | null = null
-  /** 宿主场景控制器(实例化后注入) */
-  host!: TownScene3D
-  /** 本帧是否在移动(update 结束时驱动动画) */
-  private moving = false
-  /** 脚下光环组(频道色身份标识;root 子节点,随移动跟随,零每帧定位成本) */
-  aura: THREE.Group | null = null
-  /** 光环材质(渲染循环呼吸;userData.baseOp 存基准透明度) */
-  auraMats: THREE.MeshBasicMaterial[] = []
-  /** 呼吸相位(每实例随机,避免全场同频闪烁) */
-  auraPhase = 0
-
-  /** 挂脚下光环(频道色,与领地同源;lead 加外环 —— 角色身份一眼可辨) */
-  attachAura(color: number, role: 'lead' | 'worker'): void {
-    const g = new THREE.Group()
-    const mats: THREE.MeshBasicMaterial[] = []
-    const mk = (r0: number, r1: number, y: number, op: number): void => {
-      const m = new THREE.MeshBasicMaterial({ color, transparent: true, opacity: op, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending })
-      m.userData.baseOp = op
-      mats.push(m)
-      const mesh = new THREE.Mesh(new THREE.RingGeometry(r0, r1, 44), m)
-      mesh.rotation.x = -Math.PI / 2
-      mesh.position.y = y
-      g.add(mesh)
-    }
-    mk(34, 40, 0.36, 0.26)
-    if (role === 'lead') mk(46, 50, 0.42, 0.2)
-    this.root.add(g)
-    this.aura = g
-    this.auraMats = mats
-    this.auraPhase = Math.random() * Math.PI * 2
-  }
-
-  constructor(init: {
-    channelId: string
-    agentId: string
-    name: string
-    role: 'lead' | 'worker'
-    root: THREE.Group
-    model: THREE.Group
-    mixer: THREE.AnimationMixer | null
-    clips: THREE.AnimationClip[]
-    colorNum: number
-    nameSprite: THREE.Sprite
-    bubble: THREE.Sprite | null
-    bubbleText: string | null
-    bubbleTimer: ReturnType<typeof setTimeout> | null
-    state: 'idle' | 'busy' | 'stopped'
-    progress: number | null
-    behavior: BehaviorState
-    dragging: boolean
-    homeX: number
-    homeZ: number
-    range: AgentRangeLayout | null
-    rangeLine: THREE.LineLoop | null
-    textureKey: string
-    modelRef: string
-  }) {
-    Object.assign(this, init)
-  }
-
-  /** 到达判定 */
-  reached(target: { x: number, z: number }): boolean {
-    return Math.hypot(this.root.position.x - target.x, this.root.position.z - target.z) <= ARRIVE
-  }
-
-  /** 朝目标匀速走一步(按自身活动范围/频道边界钳制;驱动朝向与动画) */
-  driveToward(target: { x: number, z: number }, speed: number, dt: number): void {
-    this.moving = true
-    const cur = { x: this.root.position.x, z: this.root.position.z }
-    const next = stepToward({ x: cur.x, y: cur.z }, { x: target.x, y: target.z }, speed, dt)
-    let nx = next.x
-    let nz = next.y
-    if (this.range) {
-      const clamped = clampToAgentRange(this.range, nx, nz, 6)
-      nx = clamped.x
-      nz = clamped.z
-    }
-    else {
-      const layout = this.host.blockLayoutOf(this.channelId)
-      if (layout) {
-        const clamped = clampToBoundary(layout, nx, nz, 6)
-        nx = clamped.x
-        nz = clamped.z
-      }
-    }
-    this.root.position.x = nx
-    this.root.position.z = nz
-    // 朝向平滑:朝移动方向插值转动(左/右两态,不用瞬间 snap,2.5D 行走更顺)
-    const dir = next.dir
-    const targetY = dir === 'left' ? Math.PI : 0
-    const curY = this.root.rotation.y
-    // 最短角差插值(0 ↔ π 之间取捷径;步长限速防抖)
-    let d = targetY - curY
-    if (d > Math.PI) d -= Math.PI * 2
-    else if (d < -Math.PI) d += Math.PI * 2
-    const maxStep = dt * 3.2
-    this.root.rotation.y = curY + Math.max(-maxStep, Math.min(maxStep, d))
-    void dt
-  }
-
-  /** 行为 FSM(idle/roam/approach/wait/returnHome);由渲染循环每帧驱动,动画随移动状态切换 */
-  update(dt: number): void {
-    this.moving = false
-    try {
-      this.updateBehavior(dt)
-    }
-    finally {
-      this.playWalkAnim(this.moving)
-    }
-  }
-
-  private updateBehavior(dt: number): void {
-    const b = this.behavior
-    if (b.mode === 'idle' || b.mode === 'roam') {
-      if (b.engaged || this.dragging) return
-      b.mode = 'roam'
-      if (!b.roamTarget) {
-        // 到达后就地停顿片刻:保持 idle 动画,营造走走停停的闲逛节奏(并产生 motion 事件)
-        if (performance.now() < b.pauseUntil) return
-        // 漫游目标:有独立活动范围 → 在自身范围内取点;否则沿用频道边界内取点
-        const layout = this.host.blockLayoutOf(this.channelId)
-        let tx: number
-        let tz: number
-        if (this.range) {
-          tx = this.homeX + (Math.random() * 2 - 1) * this.range.radiusX * 0.9
-          tz = this.homeZ + (Math.random() * 2 - 1) * this.range.radiusZ * 0.9
-          const clamped = clampToAgentRange(this.range, tx, tz, 8)
-          tx = clamped.x
-          tz = clamped.z
-        }
-        else {
-          const range = layout ? Math.min(layout.radiusX, layout.radiusZ) * 0.45 : 80
-          tx = this.homeX + (Math.random() * 2 - 1) * range
-          tz = this.homeZ + (Math.random() * 2 - 1) * range * 0.6
-          if (layout) {
-            const clamped = clampToBoundary(layout, tx, tz, 16)
-            tx = clamped.x
-            tz = clamped.z
-          }
-        }
-        b.roamTarget = { x: tx, z: tz }
-      }
-      this.driveToward(b.roamTarget, AGENT_SPEED * 0.5, dt)
-      if (this.reached(b.roamTarget)) {
-        b.roamTarget = null
-        b.pauseUntil = performance.now() + 350 + Math.random() * 900
-      }
-      return
-    }
-    if (b.mode === 'approach') {
-      const target = b.targetId ? this.host.getAgent(b.targetId) : undefined
-      if (!target) {
-        b.mode = 'idle'
-        return
-      }
-      let pos = { x: target.root.position.x, z: target.root.position.z }
-      // 目标在自身活动范围外 → 逼近到自身范围边界(送达交接在边界处完成)
-      if (this.range) {
-        const c = clampToAgentRange(this.range, pos.x, pos.z, 8)
-        pos = { x: c.x, z: c.z }
-      }
-      this.driveToward(pos, AGENT_SPEED, dt)
-      if (this.reached(pos)) {
-        this.host.deliverBehavior(this, target)
-        if (b.action?.requireReply) {
-          b.mode = 'wait'
-          b.waitUntil = performance.now() + WAIT_MS
-        }
-        else {
-          b.mode = 'returnHome'
-          this.host.releaseEngaged(this)
-          b.targetId = null
-        }
-      }
-      return
-    }
-    if (b.mode === 'wait') {
-      if (this.dragging) return
-      const target = b.targetId ? this.host.getAgent(b.targetId) : undefined
-      if (target && !target.dragging) {
-        const stand = { x: target.root.position.x + 28, z: target.root.position.z + 8 }
-        this.driveToward(stand, AGENT_SPEED * 0.6, dt)
-      }
-      if (performance.now() >= b.waitUntil) {
-        b.mode = 'returnHome'
-        this.host.releaseEngaged(this)
-      }
-      return
-    }
-    if (b.mode === 'returnHome') {
-      if (this.dragging) return
-      const home = { x: this.homeX, z: this.homeZ }
-      this.driveToward(home, AGENT_SPEED * 0.7, dt)
-      if (this.reached(home)) {
-        this.root.position.set(this.homeX, GROUND_Y, this.homeZ)
-        b.mode = 'idle'
-        b.targetId = null
-        b.action = undefined
-      }
-    }
-  }
-
-  /** 动画状态切换(有 clip: idle/walk 动作;无 clip: 上下浮动 bob);切换时经宿主广播 motion 事件 */
-  playWalkAnim(moving: boolean): void {
-    const next = moving ? 'walk' : 'idle'
-    if (this.animState !== next) {
-      this.animState = next
-      this.host.notifyMotion(this)
-    }
-    const bob = () => {
-      // 程序化动作绑定(model 局部,色环/名牌保持贴地稳定):
-      //  待机呼吸浮动 + 行走跳跃颠簸 + 行走左右微摆
-      const t = performance.now()
-      const breathe = 1.2 + Math.sin(t * 0.0016) * 1.6
-      const hop = Math.abs(Math.sin(t * 0.005)) * 6
-      this.model.position.y = moving ? hop : breathe
-      const swayTarget = moving ? Math.sin(t * 0.006) * 0.07 : 0
-      this.model.rotation.z += (swayTarget - this.model.rotation.z) * 0.12
-    }
-    if (this.clips.length === 0) {
-      bob()
-      return
-    }
-    // 有动画 clip:名字感知选择(剪辑命名各异:WALK/Walk、idle/stand/breath...),
-    // 先按语义匹配,找不到回退索引(idle→0,walk→1);仅含走路剪辑的模型待机时
-    // 回退程序化 bob,避免原地播放走路。crossfade 平滑过渡(避免双 action 叠加)。
-    if (!this.mixer) return
-    const lower = (c: THREE.AnimationClip) => c.name.toLowerCase()
-    const clip = moving
-      ? (this.clips.find(c => /walk|run|move/.test(lower(c))) ?? this.clips[Math.min(1, this.clips.length - 1)])
-      : (this.clips.find(c => /idle|stand|breath/.test(lower(c))) ?? (this.clips.length > 1 ? this.clips[0] : null))
-    if (!clip) {
-      if (this.activeAction) {
-        this.activeAction.fadeOut(0.15)
-        this.activeAction = null
-      }
-      bob()
-      return
-    }
-    const nextAction = this.mixer.clipAction(clip)
-    if (this.activeAction === nextAction) {
-      nextAction.timeScale = moving ? 1.3 : 0.9
-      return
-    }
-    nextAction.reset().setEffectiveTimeScale(moving ? 1.3 : 0.9).fadeIn(0.15).play()
-    if (this.activeAction) this.activeAction.fadeOut(0.15)
-    this.activeAction = nextAction
-  }
-
-  /** 更新 home 落点(行为结束后回归点;含拖拽/范围位移后落库路径) */
-  setHome(x: number, z: number): void {
-    this.homeX = x
-    this.homeZ = z
-  }
-
-  /** 渲染/刷新活动范围线框(数据驱动:range 变更 → 线框重建)+ 可见性 */
-  renderRangeLine(): void {
-    if (this.rangeLine) {
-      this.host.threeScene.remove(this.rangeLine)
-      this.rangeLine = null
-    }
-    if (!this.range) return
-    const color = 0x41c8f4
-    const line = makeBoundary(this.range.shape, this.range.radiusX, this.range.radiusZ, color)
-    // 虚线描边(与频道实线边界区分;2.5D 可读性)
-    line.material = new THREE.LineDashedMaterial({ color, transparent: true, opacity: 0.75, depthTest: false, dashSize: 14, gapSize: 9 })
-    line.computeLineDistances()
-    line.position.set(this.range.x, 0.5, this.range.z)
-    line.rotation.y = this.range.rotationY * Math.PI / 180
-    line.visible = this.host.rangeLineVisibleFor(this)
-    this.host.threeScene.add(line)
-    this.rangeLine = line
-    this.host.markDirty()
-  }
-
-  /** 挂气泡(替换旧气泡;宿主完成纹理渲染) */
-  attachBubble(sprite: THREE.Sprite, text: string): void {
-    if (this.bubble) {
-      this.host.threeScene.remove(this.bubble)
-      this.bubbleText = null
-    }
-    this.bubble = sprite
-    this.bubbleText = text
-  }
-
-  /** 移除气泡(宿主负责从场景摘除) */
-  clearBubble(): void {
-    if (!this.bubble) return
-    this.host.threeScene.remove(this.bubble)
-    this.bubble = null
-    this.bubbleText = null
-  }
-}
-
-type BehaviorMode
-  = 'idle'
-    | 'roam'
-    | 'approach'
-    | 'wait'
-    | 'returnHome'
-
-/** 数字孪生设备 3D 实例(面向对象:持有节点网格/状态/遥测,封装讑生同步、状态环、模型重挂、transform 记忆)。
- *  由场景按 device-twins 数据库元数据实例化;state/telemetry 数据驱动渲染。 */
-class DeviceNode {
-  twinId!: string
-  name!: string
-  modelRef!: string
-  root!: THREE.Group
-  /** 模型挂载组(换模型时 clear 重挂;缩放施加于此) */
-  holder!: THREE.Group
-  ring!: THREE.Mesh
-  /** 运行态动效弧(仅 running 可见;渲染循环缓转 —— 语义动效:设备在转 = 在产) */
-  arc: THREE.Mesh | null = null
-  label!: THREE.Sprite
-  state!: 'idle' | 'running' | 'offline' | 'alarm'
-  telemetry!: Record<string, number | string | boolean>
-  /** 宿主场景控制器(实例化后注入) */
-  host!: TownScene3D
-
-  constructor(init: {
-    twinId: string
-    name: string
-    modelRef: string
-    root: THREE.Group
-    holder: THREE.Group
-    ring: THREE.Mesh
-    label: THREE.Sprite
-    state: 'idle' | 'running' | 'offline' | 'alarm'
-    telemetry: Record<string, number | string | boolean>
-  }) {
-    Object.assign(this, init)
-  }
-
-  /** 模型顶面世界高度缓存(HUD/callout 每帧读取;缩放变更时失效) */
-  topYCache: number | null = null
-  /** 当前产线光晕色(空 = 未分配) */
-  lineColor = ''
-  /** 产线换色回调(recreateDaqNode 装配;applyTwin 检测变化时重 tint) */
-  applyLine: ((color: string) => void) | null = null
-
-  /** 状态环颜色(数据驱动:状态变化/产线换色时调用,渲染循环不再每帧重刷)。
-   *  分配了产线的节点(数采)环随产线色 —— 状态生命感已由 LED 呼吸环表达;常规设备环 = 状态色。 */
-  updateRing(): void {
-    const mat = this.ring.material as THREE.MeshBasicMaterial
-    if (this.lineColor) mat.color.set(this.lineColor)
-    else mat.color.setHex(this.state === 'alarm' ? 0xff6b6b : this.state === 'offline' ? 0x8496a5 : this.state === 'running' ? 0x35e0a0 : 0xf6c453)
-    if (this.arc) this.arc.visible = this.state === 'running'
-  }
-
-  /** 与数据库讑生记录收敛(状态/遥测/名称/模型/产线光晕;宿主完成名牌与模型重挂) */
-  applyTwin(t: DeviceTwinSync): void {
-    if (t.state) this.state = t.state
-    if (t.telemetry) this.telemetry = { ...this.telemetry, ...t.telemetry }
-    if (t.name && t.name !== this.name) this.host.renameDeviceSprite(this, t.name)
-    if (t.modelRef && t.modelRef !== this.modelRef) this.host.swapDeviceModelSprite(this, t.modelRef)
-    if ((t.lineColor ?? '') !== this.lineColor) {
-      this.lineColor = t.lineColor ?? ''
-      this.applyLine?.(this.lineColor)
-    }
-    this.updateRing()
-    this.host.markDirty()
-  }
-
-  /** 记录当前 transform(供防抖落库快照) */
-  rememberTransform(): { posX: number, posZ: number, rotationY: number } {
-    return {
-      posX: Math.round(this.root.position.x * 10) / 10,
-      posZ: Math.round(this.root.position.z * 10) / 10,
-      rotationY: Math.round(THREE.MathUtils.radToDeg(this.root.rotation.y) * 10) / 10,
-    }
-  }
-}
-
-interface BehaviorState {
-  mode: BehaviorMode
-  roamTarget: { x: number, z: number } | null
-  targetId: string | null
-  waitUntil: number
-  /** 漫游到达后就地停顿至该时刻(idle 动画;营造走走停停的闲逛节奏,驱动 motion 事件) */
-  pauseUntil: number
-  action?: { kind: ActionKind, taskKind?: string, requireReply: boolean, text: string }
-  engaged: boolean
-}
-
-/** 信息接收器队列中的一条消息(按频道 FIFO 逐条消费) */
-interface BubbleMsg {
-  /** 说话 Agent(null = 频道级/系统气泡) */
-  agentId: string | null
-  kind: TownBubbleKind
-  text: string
-  ttlMs: number
-}
-
-/** 每个实例化 Channel 的信息接收器:WS 实时信息经 handleTownEvent 入队,FIFO 逐条消费渲染到对应 Agent 头顶 */
-interface ChannelMessageReceiver {
-  channelId: string
-  queue: BubbleMsg[]
-  current: BubbleMsg | null
-  currentUntil: number
-}
+// 频道领地 / 角色 / 数字孪生设备节点与类型契约见 ./scene/town-scene3d-nodes.ts 与 ./scene/town-scene3d-types.ts
 
 /** 世界尺度/速度/身份色等纯常量与函数集中定义于 #shared/town-scene-math(与 2D/测试共用) */
 
-/** 角色模型来源登记(registerModelsFromList) */
-interface ModelInfo { id: string, file: string, name: string, kind?: string, hFactor?: number }
+export class TownScene3D implements TownSceneHost {
+  // ================================================================
+  // 宿主契约面:下列成员被 scene/*.ts 抽出模块以「窄接口」直接读写
+  // (每个模块只声明它真正触达的项,见各模块顶部的 XxxHost 接口)。
+  // 为「方法簇 → 模块」的结构性拆分而公开,不改变任何运行时语义。
+  // 其中 autoFrameTo / pickChannelEdge / boundaryHandlePoints 由 private 放宽为 public:
+  // 原调用点全在本类内部(已随簇迁出),editing / ranges 模块经宿主契约回调,纯属可见性放宽。
+  // ================================================================
 
-export class TownScene3D {
-  private renderer!: THREE.WebGLRenderer
+  renderer!: THREE.WebGLRenderer
   /** 后处理管线:Render → Bloom(夜航辉光)→ Output(tone mapping + sRGB;曝光经 setExposure 仍实时生效) */
-  private composer!: EffectComposer
-  private camera!: THREE.PerspectiveCamera
+  composer!: EffectComposer
+  camera!: THREE.PerspectiveCamera
   /** 相机注视目标(拖拽平移它,zoom 微调距离) */
-  private camTarget = new THREE.Vector3(WORLD_CX, 20, WORLD_CZ)
+  camTarget = new THREE.Vector3(WORLD_CX, 20, WORLD_CZ)
   /** 主方向光(阴影相机范围随 dolly 扩,大领地投影不消失) */
-  private keyLight!: THREE.DirectionalLight
-  private scene!: THREE.Scene
-  private ground!: THREE.Mesh
+  keyLight!: THREE.DirectionalLight
+  scene!: THREE.Scene
+  ground!: THREE.Mesh
   /** 穹顶天幕(随镜头平移,保证无限视野观感) */
-  private skyDome: THREE.Mesh | null = null
-  private blocks = new Map<string, Block3D>()
-  private agents = new Map<string, Agent3D>()
+  skyDome: THREE.Mesh | null = null
+  blocks = new Map<string, Block3D>()
+  agents = new Map<string, Agent3D>()
   /** 数字孪生设备节点(twinId → node) */
-  private deviceNodes = new Map<string, DeviceNode>()
+  deviceNodes = new Map<string, DeviceNode>()
   /** 数采节点顶端 LED 环(twinId → 环;渲染循环缓转呼吸) */
-  private daqLedRings = new Map<string, THREE.Mesh>()
+  daqLedRings = new Map<string, THREE.Mesh>()
   /** 数采→设备 绑定链路(虚线贝塞尔 + 流动脉冲;syncDaqLinks 维护) */
-  private daqLinkGroup = new THREE.Group()
-  private daqLinks: Array<{ daqId: string, deviceId: string, line: THREE.Line, pulse: THREE.Mesh, curve: THREE.QuadraticBezierCurve3, pt: number, ptSig: string }> = []
-
-  // ===== 投影/拾取 scratch 单例(热路径零分配) =====
-  private static readonly _wDir = new THREE.Vector3()
-  private static readonly _wRel = new THREE.Vector3()
-  private static readonly _wVec = new THREE.Vector3()
-  private static readonly _wVec2 = new THREE.Vector2()
-  private static readonly _groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0)
-  private static readonly _raycaster = new THREE.Raycaster()
-  private daqLinkSig = ''
+  daqLinkGroup = new THREE.Group()
+  daqLinks: DaqLink[] = []
+
+  daqLinkSig = ''
   /** 期望链路(TownView 传入;设备节点晚到时由 syncDevices 末尾重仲裁) */
-  private daqLinksWanted: Array<{ daqId: string, deviceId: string }> = []
+  daqLinksWanted: Array<{ daqId: string, deviceId: string }> = []
   /** 薄膜 web(产线设备之间的半透明膜;按 X 序连接挤出→流延→MD→TD→收卷) */
-  private filmWebGroup = new THREE.Group()
-  private filmWebSig = ''
-  private filmWebMat: THREE.MeshStandardMaterial | null = null
+  filmWebGroup = new THREE.Group()
+  filmWebSig = ''
+  filmWebMat: THREE.MeshStandardMaterial | null = null
   /** 服务端已有但模型资产尚未注册的设备孪生，资产到达后补建节点。 */
-  private pendingDeviceTwins = new Map<string, DeviceTwinSync>()
+  pendingDeviceTwins = new Map<string, DeviceTwinSync>()
   /** 尚未取得服务端 ID 的本地设备节点(临时 ID → 创建请求初始状态)。 */
-  private pendingDeviceCreates = new Map<string, { name: string, modelRef: string, posX: number, posZ: number }>()
+  pendingDeviceCreates = new Map<string, { name: string, modelRef: string, posX: number, posZ: number }>()
   /** 用户在创建设备完成前删除的临时节点，创建完成后补偿删除服务端记录。 */
-  private cancelledDeviceCreates = new Set<string>()
+  cancelledDeviceCreates = new Set<string>()
   /** 场景内可缩放目标(Agent 或设备) */
-  private scalables = new Map<string, ScaledTarget>()
+  scalables = new Map<string, ScaledTarget>()
   /** 当前选中(kind:id) */
-  private selected: { kind: 'agent' | 'device', id: string } | null = null
+  selected: SelectedTarget | null = null
   /** 已登记模型(id → file) */
-  private modelsById = new Map<string, ModelInfo>()
+  modelsById = new Map<string, ModelInfo>()
   /** GLTF 缓存(避免重复加载) */
-  private gltfCache = new Map<string, { file: string, scene: THREE.Group, height: number }>()
-  private gltfLoader = new GLTFLoader()
-  private el: HTMLDivElement
-  private raf = 0
-  private clock = new THREE.Clock()
-  private frameCount = 0
-  private fpsAccum = 0
+  gltfCache = new Map<string, { file: string, scene: THREE.Group, height: number }>()
+  gltfLoader = new GLTFLoader()
+  el: HTMLDivElement
+  raf = 0
+  clock = new THREE.Clock()
+  frameCount = 0
+  fpsAccum = 0
   /** 墙钟 FPS 窗口起点与 rAF 回调计数(徽标/自适应质量的真实输入;原 dt 累计会漂移) */
-  private fpsWinT0 = 0
-  private rafCount = 0
+  fpsWinT0 = 0
+  rafCount = 0
   /** 帧预算(ms):渲染节流上限;0 = 不限制。数据消费不走此门控(帧到达即入实时缓冲) */
-  private frameBudgetMs = 1000 / 40
+  frameBudgetMs = 1000 / 40
 
   /** 用户帧率选择(60/120/0=不限制):只影响渲染节流,与数据消费频率无关 */
   setFpsCap(fps: number): void {
@@ -789,70 +183,56 @@ export class TownScene3D {
     this.frameAcc = 0
   }
 
-  private frameAcc = 0
+  frameAcc = 0
   /** 动态分辨率基准(初始 dpr):实测帧率过低时降,富余时回升 */
-  private baseDpr = Math.min(window.devicePixelRatio, 2)
-  private dirty = true
+  baseDpr = Math.min(window.devicePixelRatio, 2)
+  dirty = true
   /** 频道旗缓存(任务状态) */
-  private flagBy = new Map<string, THREE.Mesh>()
-  private disposed = false
+  flagBy = new Map<string, THREE.Mesh>()
+  disposed = false
   /** 当前相机缩放(滚轮;作用于 dolly 距离) */
-  private dolly = 1.0
+  dolly = 1.0
   /** 轨道相机状态机(Blender 规范):yaw 方位角 / pitch 仰角 / radius 半径。
    *  viewTarget 供预设平滑趋近;左键环绕直接改双值(即时跟手)。 */
-  private autoOrbit = false
-  private viewCur = { yaw: 0, pitch: 0.7, radius: 1178 }
-  private viewTarget = { yaw: 0, pitch: 0.7, radius: 1178 }
+  autoOrbit = false
+  viewCur = { yaw: 0, pitch: 0.7, radius: 1178 }
+  viewTarget = { yaw: 0, pitch: 0.7, radius: 1178 }
   /** Blender 式变换手柄(选中设备;G 移动 / R 旋转 / S 缩放) */
-  private tControls: TransformControls | null = null
+  tControls: TransformControls | null = null
   /** 舞台尺寸观察器 */
-  private resizeOb: ResizeObserver | null = null
+  resizeOb: ResizeObserver | null = null
   /** 编辑 / 浏览模式(浏览只读:设备/角色不可拖,仅点选) */
-  private mode: TownScene3DMode = 'browse'
+  mode: TownScene3DMode = 'browse'
   /** 正在拖曳的场景对象(编辑模式):设备 / 角色落点 / 频道整体 / 边界手柄 / Agent 活动范围 */
-  private pointerDrag:
-    | { kind: 'device', id: string }
-    | { kind: 'agent', id: string }
-    | { kind: 'channel', id: string, dx: number, dz: number }
-    | { kind: 'resize', id: string, handle: number }
-    | { kind: 'channelEdge', id: string, rx0: number, rz0: number, rd0: number }
-    | { kind: 'rangeDraw', id: string, x0: number, z0: number }
-    | { kind: 'agentRange', id: string, dx: number, dz: number }
-    | { kind: 'agentRangeResize', id: string, handle: number }
-    | null = null
+  pointerDrag: PointerDragState = null
 
   /** 网格吸附(编辑拖拽落点对齐 16 单位网格) */
-  private snapEnabled = true
+  snapEnabled = true
   /** 选中高亮环(琥珀色动效环,跟随当前选中设备/角色;渲染循环驱动) */
-  private selRing: THREE.Mesh | null = null
+  selRing: THREE.Mesh | null = null
   /** 边界缩放手柄(编辑模式选中频道时显示;拖拽手柄调整 radiusX/radiusZ) */
-  private resizeHandles: Array<{ mesh: THREE.Mesh, cid: string, handle: number }> = []
+  readonly resizeHandles: ChannelResizeHandle[] = []
   /** Agent 活动范围缩放手柄(编辑模式选中带范围角色时显示;拖拽调整该 Agent 范围大小) */
-  private agentRangeHandles: Array<{ mesh: THREE.Mesh, agentId: string, handle: number }> = []
+  readonly agentRangeHandles: AgentRangeHandle[] = []
   /** 框选绘制预览线框(rangeDraw 模式;松开后变为正式范围) */
-  private rangeDrawLine: THREE.LineLoop | null = null
+  rangeDrawLine: THREE.LineLoop | null = null
   /** 框选绘制目标 agent(非空 = 编辑模式正在为该角色拉动矩形框) */
-  private rangeDrawAgent: string | null = null
+  rangeDrawAgent: string | null = null
   /** 框选绘制当前对角(供 endPointerDrag 生成范围) */
-  private rangeDrawPreviewState: { x0: number, z0: number, x1: number, z1: number } | null = null
+  rangeDrawPreviewState: { x0: number, z0: number, x1: number, z1: number } | null = null
   /** setAgentRangeScene 中因范围收缩而位移的 home(面板提交时一并落库) */
-  private rangeHomeMoved: { agentId: string, x: number, z: number } | null = null
-  private lastActivity: { channelId: string, agentName: string, text: string, at?: number } | null = null
-  private recentActivity: Array<{ channelId: string, agentName: string, text: string, at?: number }> = []
-  private dbgBubbles: Array<{ text: string, at: number }> = []
+  rangeHomeMoved: { agentId: string, x: number, z: number } | null = null
+  lastActivity: { channelId: string, agentName: string, text: string, at?: number } | null = null
+  recentActivity: Array<{ channelId: string, agentName: string, text: string, at?: number }> = []
+  dbgBubbles: Array<{ text: string, at: number }> = []
   /** 频道信息接收器(channelId → FIFO 队列;实时信息经 handleTownEvent 入队,渲染循环逐条消费) */
-  private receivers = new Map<string, ChannelMessageReceiver>()
+  receivers = new Map<string, ChannelMessageReceiver>()
   readonly container: HTMLDivElement
 
   /** 任务 ID → assignee 反查 */
   resolveTaskAssignee: ((taskId: string) => string | null) | null = null
   /** 数字孪生设备 API(由 TownView 注入 useDeviceTwins 适配器;拖 dev 模型进场景时创建设备) */
-  devices: {
-    create(input: { name: string, modelRef?: string, kind?: string, controls?: string[], posX?: number, posZ?: number, scale?: number }): Promise<{ id: string }>
-    update(id: string, patch: DeviceTransformPatch): Promise<unknown>
-    remove?(id: string): Promise<unknown>
-    control(id: string, command: string, args?: Record<string, unknown>): Promise<unknown>
-  } | null = null
+  devices: DeviceApi | null = null
 
   /** 管理员布局:保存 Agent 落点(由 TownView 注入;经既有 channel_agents.config 持久化) */
   agentApi: {
@@ -875,363 +255,32 @@ export class TownScene3D {
     this.buildBlocks(seed)
   }
 
+  // ================================================================
+  // 面向对象节点的宿主契约(Block3D / Agent3D / DeviceNode)
+  // 节点只依赖 scene/town-scene3d-types 的最小接口,此处显式暴露宿主能力,
+  // 保证「节点所需服务」在编译期可校验(缺一即报错)。
+  // ================================================================
+
+  /** 频道领地节点宿主(Block3D.host) */
+  get blockHost(): BlockHost { return this }
+
+  /** 角色节点宿主(Agent3D.host) */
+  get agentHost(): AgentHost { return this }
+
+  /** 设备节点宿主(DeviceNode.host) */
+  get deviceHost(): DeviceHost { return this }
+
   // ================================================================
   // 初始化(渲染器/相机/灯光/地面)
   // ================================================================
 
   private initRenderer(): void {
-    this.renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true, powerPreference: 'high-performance' })
-    this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))
-    this.renderer.setSize(this.el.clientWidth || 1100, this.el.clientHeight || 700)
-    this.renderer.shadowMap.enabled = true
-    this.renderer.shadowMap.type = THREE.PCFSoftShadowMap
-    // 阴影按需重绘:渲染循环里仅场景内容变化(dirty)或角色动画在跑时置 needsUpdate,
-    // 静态场景(总览/无动画)不再每帧全量重绘阴影贴图(2048² PCFSoft 是最大单项 GPU 开销)
-    this.renderer.shadowMap.autoUpdate = false
-    this.renderer.outputColorSpace = THREE.SRGBColorSpace
-    // 电影级色调映射:高光滚降 + 中间调层次,GLB 材质不再"平板曝光"
-    this.renderer.toneMapping = THREE.ACESFilmicToneMapping
-    this.renderer.toneMappingExposure = 1.12
-    // 统计跨 pass 累计(composer 多 pass 直渲染时 info 每次自动清零,只会读到末 pass 的 1 次调用):
-    // 每帧渲染前手动 reset,render() 累加,__townStats 拿到的才是整帧真实 drawCalls/triangles
-    this.renderer.info.autoReset = false
-    this.el.appendChild(this.renderer.domElement)
-    // 舞台尺寸跟随宿主(网格布局/抽屉/全屏切换都会改变宿主尺寸)
-    this.resizeOb = new ResizeObserver(() => {
-      const w = this.el.clientWidth
-      const h = this.el.clientHeight
-      if (w < 2 || h < 2) return
-      this.renderer.setSize(w, h)
-      this.composer.setSize(w, h)
-      this.camera.aspect = w / h
-      this.camera.updateProjectionMatrix()
-      this.dirty = true
-    })
-    this.resizeOb.observe(this.el)
-    // 选中:点击 Agent/设备 → 弹缩放/旋转滑杆(经 on('select') 通知 Vue);拖拽释放不触发
-    // 点击语义守卫:记录按下位置;松手位移大 = 相机平移手势 → 不触发点选(含信标)
-    let clickDownAt: { x: number, y: number } | null = null
-    this.renderer.domElement.addEventListener('pointerdown', (e: PointerEvent) => {
-      clickDownAt = e.button === 0 ? { x: e.clientX, y: e.clientY } : null
-    })
-    this.renderer.domElement.addEventListener('pointerup', (e: PointerEvent) => {
-      if (e.button !== 0 || this.pointerDrag || this.tControls?.dragging) return
-      // 平移手势(按下后移动超 8px)→ 不作点选
-      if (clickDownAt && Math.hypot(e.clientX - clickDownAt.x, e.clientY - clickDownAt.y) > 8) {
-        clickDownAt = null
-        return
-      }
-      clickDownAt = null
-      const w = this.screenToWorld(e.clientX, e.clientY)
-      // 频道信标优先(领队驻扎中心与信标重叠;中心 ±34 内点=信标,按住拖=Agent:
-      // 拖拽手势在 pointerup 时因 pointerDrag 存在提前返回,不会误触信标)
-      const beacon = this.pickBeacon(w.x, w.z)
-      if (beacon) {
-        this.setSelected(null)
-        this.selectChannel(beacon.cid)
-        this.focusTo(beacon.x, beacon.z)
-        return
-      }
-      const hit = this.pickAt(w.x, w.z)
-      if (hit) {
-        this.setSelected(hit)
-        // 点中角色/设备时清除频道选中(避免与边界面板混用)
-        if (this.selectedChannel) this.selectChannel(null)
-        return
-      }
-      // 未命中 agent/设备 → 尝试点选频道领地(打开边界编辑面板)
-      const cid = this.pickChannel(w.x, w.z)
-      this.setSelected(null)
-      if (cid && this.mode === 'edit') this.selectChannel(cid)
-    })
-    // 双击 Agent/设备:缓动聚焦(指挥官镜头;不打断选择语义)
-    this.renderer.domElement.addEventListener('dblclick', (e: MouseEvent) => {
-      if (this.pointerDrag) return
-      const w = this.screenToWorld(e.clientX, e.clientY)
-      const hit = this.pickAt(w.x, w.z)
-      if (hit?.kind === 'agent') {
-        const a = this.agents.get(hit.id)
-        if (a) this.focusTo(a.root.position.x, a.root.position.z)
-      }
-      else if (hit?.kind === 'device') {
-        const d = this.deviceNodes.get(hit.id)
-        if (d) this.focusTo(d.root.position.x, d.root.position.z)
-      }
-      else {
-        // 双击领地(非 Agent/设备落点)→ 对焦该 Channel 中心并选中
-        // (浏览模式:边界面板即刻可用调节范围;编辑模式:缩放手柄同时显示,可拖拽控制)
-        const cid = this.pickChannel(w.x, w.z)
-        const b = cid ? this.blocks.get(cid) : undefined
-        if (b) {
-          this.selectChannel(cid)
-          this.focusTo(b.x, b.z)
-        }
-      }
-    })
-
-    this.scene = new THREE.Scene()
-    this.scene.background = new THREE.Color(0x0a0f18)
-    // 大气纵深:雾把远处柔化进夜色,2.5D 场景立刻有工业孪生的空间感
-    this.scene.fog = new THREE.Fog(0x1b2836, 1400, 8800)
-    // PBR 环境光照:PMREM 室内环境 → 金属/粗糙 GLB 材质获得真实反射与 specular 生命;
-    // 低强度保留夜景工业气氛(只在材质细节里"呼吸",不提亮全场)
-    try {
-      const pmrem = new THREE.PMREMGenerator(this.renderer)
-      this.scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture
-      this.scene.environmentIntensity = 0.42
-      pmrem.dispose()
-    }
-    catch { /* 环境贴图失败:退回纯灯光方案 */ }
-
-    // 穹顶渐变天幕(深空蓝黑 → 地平线工业暖灰;BackSide 大球,随镜头平移)
-    this.skyDome = this.makeSkyDome()
-    this.scene.add(this.skyDome)
-
-    // 边界缩放手柄(编辑模式选中频道时显示;4 个:椭圆轴点 / 矩形角点)
-    for (let i = 0; i < 4; i++) {
-      const h = new THREE.Mesh(
-        new THREE.TorusGeometry(16, 6, 8, 20),
-        new THREE.MeshBasicMaterial({ color: 0xf6c453, transparent: true, opacity: 0.95, depthTest: false }),
-      )
-      h.rotation.x = Math.PI / 2
-      h.position.y = 1.4
-      h.visible = false
-      this.scene.add(h)
-      this.resizeHandles.push({ mesh: h, cid: '', handle: i })
-    }
-    // Agent 活动范围缩放手柄(编辑模式选中带范围角色时显示;4 个:椭圆轴点 / 矩形角点)
-    for (let i = 0; i < 4; i++) {
-      const h = new THREE.Mesh(
-        new THREE.TorusGeometry(10, 4, 8, 16),
-        new THREE.MeshBasicMaterial({ color: 0x41c8f4, transparent: true, opacity: 0.95, depthTest: false }),
-      )
-      h.rotation.x = Math.PI / 2
-      h.position.y = 1.2
-      h.visible = false
-      this.scene.add(h)
-      this.agentRangeHandles.push({ mesh: h, agentId: '', handle: i })
-    }
-
-    // 选中高亮环:单位几何 + 每帧按目标缩放(琥珀 #f6c453,加性发光,慢转活性)
-    const selRing = new THREE.Mesh(
-      new THREE.RingGeometry(0.92, 1.0, 56),
-      new THREE.MeshBasicMaterial({ color: 0xf6c453, transparent: true, opacity: 0.85, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending }),
-    )
-    selRing.rotation.x = -Math.PI / 2
-    selRing.position.y = 0.5
-    selRing.visible = false
-    selRing.renderOrder = 5
-    this.scene.add(selRing)
-    this.selRing = selRing
-
-    // 相机:斜俯视 2.5D(FOV 55 + 远距框景,整个园区一块入画)
-    this.camera = new THREE.PerspectiveCamera(55, (this.el.clientWidth || 1100) / (this.el.clientHeight || 700), 1, 12000)
-    this.camera.position.set(WORLD_CX, 760, WORLD_CZ + 900)
-    this.camera.lookAt(WORLD_CX, 20, WORLD_CZ)
-
-    // Blender 式变换手柄:选中设备时出现(移动 G / 旋转 R / 缩放 S;UI 分段钮 + 键盘同源)
-    const tc = new TransformControls(this.camera, this.renderer.domElement)
-    tc.size = 0.85
-    tc.setMode('translate')
-    tc.showY = false
-    tc.addEventListener('dragging-changed', (e) => {
-      // 手柄拖拽期间压制场景点选/相机平移;松手后设备 transform 落库
-      if (!e.value) {
-        const sel = this.selected
-        if (sel?.kind === 'device' && this.deviceNodes.has(sel.id)) this.persistDeviceTransform(sel.id)
-      }
-    })
-    tc.addEventListener('objectChange', () => {
-      const sel = this.selected
-      if (!sel || sel.kind !== 'device') return
-      const dev = this.deviceNodes.get(sel.id)
-      if (!dev) return
-      // 缩放转移:gizmo 对 root 的缩放倍率转移到模型 holder(免得环/铭牌跟着变大),root 复位
-      if (tc.mode === 'scale' && Math.abs(dev.root.scale.x - 1) > 1e-4) {
-        const reg = this.scalables.get(`device:${sel.id}`)
-        const cur = reg?.userScale ?? 1
-        this.setModelScale(sel.id, Math.min(50, Math.max(0.02, cur * dev.root.scale.x)), 'device')
-        dev.root.scale.set(1, 1, 1)
-      }
-      this.dirty = true
-    })
-    this.tControls = tc
-    this.scene.add(tc.getHelper())
-
-    // 灯光:为 ACES 配平(整体提亮补偿 filmic 滚降;normalBias 消除模型自阴影痤疮)
-    this.scene.add(new THREE.AmbientLight(0xd0e4ee, 1.6))
-    const hemi = new THREE.HemisphereLight(0x9fc7e8, 0x3a2f25, 0.7)
-    this.scene.add(hemi)
-    const key = new THREE.DirectionalLight(0xfff4e0, 3.2)
-    key.position.set(WORLD_CX + 500, 900, WORLD_CZ + 300)
-    key.castShadow = true
-    this.keyLight = key
-    // 高分辨率软影:2048 map + 大 radius(PCSS 观感),贴地阴影是真实感的核心来源
-    key.shadow.mapSize.set(2048, 2048)
-    key.shadow.camera.left = -1400
-    key.shadow.camera.right = 1400
-    key.shadow.camera.top = 2000
-    key.shadow.camera.bottom = -2000
-    key.shadow.normalBias = 2
-    key.shadow.bias = -0.0002
-    key.shadow.radius = 6
-    this.scene.add(key)
-    const fill = new THREE.DirectionalLight(0x88bbff, 0.75)
-    fill.position.set(WORLD_CX - 1200, 900, WORLD_CZ - 800)
-    this.scene.add(fill)
-    // 设计稿光系补光:青色轮廓光(金属切边高光)+ 绿色低位补光(孪生绿氛围)
-    const rim = new THREE.DirectionalLight(0x41c8f4, 1.4)
-    rim.position.set(WORLD_CX - 1400, 620, WORLD_CZ - 1000)
-    this.scene.add(rim)
-    const green = new THREE.DirectionalLight(0x35e0a0, 0.4)
-    green.position.set(WORLD_CX + 700, 380, WORLD_CZ + 900)
-    this.scene.add(green)
-
-    // 地面(大平面,无限观感:7× 世界尺寸 + 高重复贴图)——夜航深蓝地坪;低反射让网格退为纹理
-    const groundMat = new THREE.MeshStandardMaterial({ color: 0xffffff, roughness: 0.62, metalness: 0.3, envMapIntensity: 0.42 })
-    this.ground = new THREE.Mesh(new THREE.PlaneGeometry(WORLD_W * 16, WORLD_H * 16), groundMat)
-    this.ground.rotation.x = -Math.PI / 2
-    this.ground.receiveShadow = true
-    this.scene.add(this.ground)
-
-    // 绑定链路层 + 薄膜 web 层(syncDaqLinks / 产线设备增删移动时重建)
-    this.scene.add(this.daqLinkGroup, this.filmWebGroup)
-
-    // 后处理:RenderPass → UnrealBloom(夜航辉光只作用于 HDR 顶端:阈值 3.0 =
-    // 本灯光系下漫反射亮面(2~2.5 线性)不起晕,只留指示灯/金属高光;LED 等指示件
-    // 已按 ×4.5~6 提为 HDR)→ OutputPass(tone mapping + sRGB 收尾;setExposure
-    // 经 OutputPass 透传仍实时生效)。MSAA 目标保住抗锯齿(EffectComposer 默认无 MSAA)。
-    const bloomTarget = new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType, samples: 4 })
-    this.composer = new EffectComposer(this.renderer, bloomTarget)
-    this.composer.setPixelRatio(this.renderer.getPixelRatio())
-    this.composer.setSize(this.el.clientWidth || 1100, this.el.clientHeight || 700)
-    this.composer.addPass(new RenderPass(this.scene, this.camera))
-    this.composer.addPass(new UnrealBloomPass(new THREE.Vector2(this.el.clientWidth || 1100, this.el.clientHeight || 700), 0.32, 0.35, 3.0))
-    this.composer.addPass(new OutputPass())
-
-    this.applyGroundTexture()
-
+    initRendererCore(this)
     // E2E/性能探针钩子:真值验证用(渲染帧计数/质量档/pixelRatio),dispose 时清除
     ;(globalThis as { __townScene3d?: TownScene3D }).__townScene3d = this
     this.loop()
   }
 
-  /** 工业孪生地面贴图(程序化 Canvas:深色混凝土地基 + 分块拼缝 + 细网格导引线 + 噪点)。
-   *  一次性生成并缓存;SVG 背景贴图仅作历史兼容,优先使用本贴图。 */
-  private makeIndustrialGroundTexture(): THREE.CanvasTexture {
-    const size = 1024
-    const canvas = document.createElement('canvas')
-    canvas.width = size
-    canvas.height = size
-    const ctx = canvas.getContext('2d')!
-    // 深色混凝土地基(微渐变)+ 分块拼缝 + 细网格导引线 —— 夜航深蓝基调(设计稿 #131f36 系)
-    const grad = ctx.createLinearGradient(0, 0, size, size)
-    grad.addColorStop(0, '#151f36')
-    grad.addColorStop(0.5, '#101a2d')
-    grad.addColorStop(1, '#131c31')
-    ctx.fillStyle = grad
-    ctx.fillRect(0, 0, size, size)
-    // 分块拼缝(工业板格 8×8;低调度 —— 地面是舞台,不是主角)
-    ctx.strokeStyle = 'rgba(42,63,102,0.32)'
-    ctx.lineWidth = 2
-    for (let i = 0; i <= 8; i++) {
-      const p = (i / 8) * size
-      ctx.beginPath()
-      ctx.moveTo(p, 0)
-      ctx.lineTo(p, size)
-      ctx.stroke()
-      ctx.beginPath()
-      ctx.moveTo(0, p)
-      ctx.lineTo(size, p)
-      ctx.stroke()
-    }
-    // 细网格导引线(设计稿 GridHelper 主色 0x2a3f66;压暗让设备读第一眼)
-    ctx.strokeStyle = 'rgba(42,63,102,0.2)'
-    ctx.lineWidth = 1
-    for (let i = 0; i <= 32; i++) {
-      const p = (i / 32) * size
-      ctx.beginPath()
-      ctx.moveTo(p, 0)
-      ctx.lineTo(p, size)
-      ctx.stroke()
-      ctx.beginPath()
-      ctx.moveTo(0, p)
-      ctx.lineTo(size, p)
-      ctx.stroke()
-    }
-    // 噪点(亚光粗糙感;伪随机但确定性)
-    ctx.fillStyle = 'rgba(255,255,255,0.02)'
-    for (let i = 0; i < 900; i++) {
-      const x = (i * 733) % size
-      const y = (i * 151) % size
-      ctx.fillRect(x, y, 2, 2)
-    }
-    const tex = new THREE.CanvasTexture(canvas)
-    tex.colorSpace = THREE.SRGBColorSpace
-    tex.wrapS = THREE.RepeatWrapping
-    tex.wrapT = THREE.RepeatWrapping
-    tex.repeat.set(23, 17)
-    tex.anisotropy = Math.min(8, this.renderer.capabilities.getMaxAnisotropy())
-    return tex
-  }
-
-  /** 穹顶天幕:垂直渐变(顶部深空 → 地平线工业暖灰)+ 顶半球星野 + 底部更亮一点,覆盖整球 */
-  private makeSkyDome(): THREE.Mesh {
-    const canvas = document.createElement('canvas')
-    canvas.width = 1024
-    canvas.height = 256
-    const ctx = canvas.getContext('2d')!
-    const grad = ctx.createLinearGradient(0, 0, 0, 256)
-    grad.addColorStop(0, '#080d16') // 天顶:近黑夜空
-    grad.addColorStop(0.40, '#121b27')
-    grad.addColorStop(0.64, '#22303e') // 中段石墨蓝(提前起坡,渐变带更长)
-    grad.addColorStop(0.84, '#3b4b5b') // 地平线:钢色微光(与雾同族)
-    grad.addColorStop(1, '#2a3644') // 地平线下收暗(下半球)
-    ctx.fillStyle = grad
-    ctx.fillRect(0, 0, canvas.width, canvas.height)
-    // 星野(顶部 45%:确定性伪随机,数据青/冷白微点,越靠天顶越密 —— 夜航纵深,低调度不抢戏)
-    let seed = 20260831
-    const rnd = (): number => {
-      seed = (seed * 1103515245 + 12345) % 2147483648
-      return seed / 2147483648
-    }
-    for (let i = 0; i < 220; i++) {
-      const x = rnd() * canvas.width
-      const y = rnd() * rnd() * 118
-      const r = rnd() < 0.88 ? 1 : 2
-      const a = 0.12 + rnd() * 0.5
-      ctx.fillStyle = rnd() < 0.24 ? `rgba(160,220,255,${a.toFixed(2)})` : `rgba(232,240,250,${a.toFixed(2)})`
-      ctx.beginPath()
-      ctx.arc(x, y, r, 0, Math.PI * 2)
-      ctx.fill()
-    }
-    const tex = new THREE.CanvasTexture(canvas)
-    tex.colorSpace = THREE.SRGBColorSpace
-    const geo = new THREE.SphereGeometry(5600, 24, 16)
-    const mat = new THREE.MeshBasicMaterial({ map: tex, side: THREE.BackSide, fog: false, depthWrite: false })
-    const dome = new THREE.Mesh(geo, mat)
-    dome.position.set(WORLD_CX, 0, WORLD_CZ)
-    dome.renderOrder = -10
-    return dome
-  }
-
-  /** 赛博小镇背景贴图 → 地面材质(优先程序化工业贴图;SVG 兼容保留) */
-  private applyGroundTexture(): void {
-    try {
-      const mat = this.ground.material as THREE.MeshStandardMaterial
-      // 工业孪生贴图为主(SVG 历史贴图只在程序化不可用时兜底)
-      mat.map = this.makeIndustrialGroundTexture()
-      mat.color.set(0xffffff)
-      mat.roughness = 0.94
-      mat.metalness = 0.06
-      // 环境反射压低:沥青地面保持亚光,反射生命留给金属设备/角色模型
-      mat.envMapIntensity = 0.28
-      mat.needsUpdate = true
-      this.dirty = true
-    }
-    catch { /* Canvas 不可用:保持纯色地面 */ }
-  }
-
   // ================================================================
   // 事件总线(与 2D 同构)
   // ================================================================
@@ -1241,7 +290,7 @@ export class TownScene3D {
     return () => this.busHandlers.delete(event)
   }
 
-  private emit<K extends keyof TownEventMap>(event: K, e: TownEventMap[K]): void {
+  emit<K extends keyof TownEventMap>(event: K, e: TownEventMap[K]): void {
     const fn = this.busHandlers.get(event)
     if (fn) fn(e)
   }
@@ -1253,455 +302,52 @@ export class TownScene3D {
   /**
    * 用频道实体基线同步领地/角色。仅放置已保存布局的频道(布局来自 useSceneLayouts,
    * 经 applySceneLayouts 注入);未放置频道只出现在频道坞,不进 3D。
+   * 实现见 scene/town-scene3d-blocks.ts。
    */
-  private buildBlocks(seeds: TownEntityInput[]): void {
-    this.entityIndex.clear()
-    for (const ch of seeds) {
-      this.entityIndex.set(ch.channelId, ch)
-      const layout = this.layouts.get(ch.channelId)
-      if (!layout) continue
-      this.placeChannel(ch, layout)
-    }
-    this.emit('blockCount', this.blocks.size)
-    this.emit('agentCount', this.agents.size)
-  }
-
-  /** 按布局放置一个频道领地(面向对象:Block3D 实例)+ 在其边界内铺放全部 Agent */
-  private placeChannel(ch: TownEntityInput, rawLayout: ChannelLayout): void {
-    const layout = normLayout(rawLayout)
-    const color = channelColorNum(ch.channelId)
-    const pad = this.makeBlock(ch.channelName, color, layout)
-    const block = new Block3D({
-      channelId: ch.channelId, name: ch.channelName,
-      x: layout.x, z: layout.z,
-      radiusX: layout.radiusX, radiusZ: layout.radiusZ,
-      shape: layout.shape, rotationY: layout.rotationY,
-      color,
-      platform: pad.platform,
-      padRing: pad.padRing,
-      beacon: pad.beacon,
-      boundary: makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, color),
-      label: this.makeLabel(ch.channelName, layout.x, 30, layout.z),
-    })
-    block.host = this
-    block.boundary.position.set(layout.x, 0.3, layout.z)
-    block.boundary.rotation.y = layout.rotationY * Math.PI / 180
-    this.scene.add(block.boundary)
-    this.blocks.set(ch.channelId, block)
-    // 在边界内铺放该频道的全部 Agent(lead 居中心,worker 左右展开;钳在边界内)
-    this.layoutAgentsInBlock(ch, block)
-    // 面向对象聚合:把该频道全部成员挂到 Block3D.members(供整体移动/边界钳制批量处理)
-    for (const a of this.agents.values()) {
-      if (a.channelId === ch.channelId && !block.members.includes(a)) block.members.push(a)
-    }
-  }
-
-  /** 在频道领地里铺放全部 Agent(按边界内分布;客户自定 home 优先) */
-  private layoutAgentsInBlock(ch: TownEntityInput, block: Block3D): void {
-    const { x, z, radiusX, radiusZ } = block
-    const inner = 0.6 // 内缩比例:agent 铺在边界内侧
-    const n = Math.max(1, ch.agents.length)
-    ch.agents.forEach((a, i) => {
-      // 若该 agent 有 persisted home(且在边界附近)则用之;否则沿长轴均匀铺放
-      let px: number
-      let pz: number
-      if (typeof a.homeX === 'number' && typeof a.homeZ === 'number') {
-        px = a.homeX
-        pz = a.homeZ
-      }
-      else {
-        const t = n <= 1 ? 0 : (i / (n - 1)) * 2 - 1
-        px = x + t * radiusX * inner * 0.8
-        pz = z + (a.role === 'lead' ? 0 : (i % 2 === 0 ? -1 : 1) * radiusZ * inner * 0.4)
-      }
-      this.ensureAgent({ ...a, channelId: ch.channelId }, px, pz, block.color)
-    })
-  }
-
-  /** 领地底盘 = 按真实形状的平台(染色层) + 同形边框环(边界告示);所见即用户设置 */
-  private makeBlock(name: string, color: number, layout: ChannelLayout): { platform: THREE.Mesh, padRing: THREE.Mesh, beacon: THREE.Group } {
-    const rotY = layout.rotationY * Math.PI / 180
-    // 平台:按真实半轴构建(与边框环同一构建路径,无单位几何、无 scale 传递 —— 杜绝缩放残留)
-    const platform = new THREE.Mesh(
-      this.makePadShapeGeometry(layout.shape, layout.radiusX, layout.radiusZ),
-      new THREE.MeshStandardMaterial({
-        color, transparent: true, opacity: 0.24, roughness: 0.85, metalness: 0.12,
-        emissive: color, emissiveIntensity: 0.12, side: THREE.DoubleSide,
-      }),
-    )
-    // 几何已烘焙放平(XY→XZ 无镜像),网格仅做 Y 旋转(与边界线同语义),不再有任何 scale
-    platform.rotation.set(0, rotY, 0)
-    platform.position.set(layout.x, 0.16, layout.z)
-    platform.receiveShadow = false
-    this.scene.add(platform)
-    // 边框环:实际尺寸外形挖去内缩内形(恒定 13 单位线宽,随形状变化重建)
-    const padRing = new THREE.Mesh(
-      this.makePadRingGeometry(layout.shape, layout.radiusX, layout.radiusZ),
-      new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.52, side: THREE.DoubleSide, depthWrite: false }),
-    )
-    padRing.rotation.set(0, rotY, 0)
-    padRing.position.set(layout.x, 0.34, layout.z)
-    this.scene.add(padRing)
-    // 中央信标(HMI 定位销):底座 + 立杆 + 频道色菱形顶标(顶标随渲染循环缓转)
-    const beacon = this.makeBeacon(color)
-    beacon.position.set(layout.x, 0, layout.z)
-    this.scene.add(beacon)
-    void name
-    return { platform, padRing, beacon }
-  }
-
-  /** 频道中心信标(HMI 定位销):点击 → pickBeacon 定位中心 + 唤醒边界编辑 */
-  private makeBeacon(color: number): THREE.Group {
-    const g = new THREE.Group()
-    const metal = new THREE.MeshStandardMaterial({ color: 0x2a3542, roughness: 0.45, metalness: 0.65 })
-    const base = new THREE.Mesh(new THREE.CylinderGeometry(7, 9, 5, 12), metal)
-    base.position.y = 2.5
-    const pole = new THREE.Mesh(new THREE.CylinderGeometry(1.6, 1.6, 30, 8), metal)
-    pole.position.y = 18
-    const tip = new THREE.Mesh(new THREE.OctahedronGeometry(6.5), new THREE.MeshBasicMaterial({ color }))
-    // HDR 亮度:信标顶标是 HMI 定位销的"灯",bloom 起晕(seleRing/边界保持 LDR 不起晕)
-    ;(tip.material as THREE.MeshBasicMaterial).color.multiplyScalar(4.5)
-    tip.position.y = 37
-    g.add(base, pole, tip)
-    return g
-  }
+  buildBlocks(seeds: TownEntityInput[]): void { buildBlocks(this, seeds) }
 
   /** 命中频道信标(中心 ±34 单位;点击信标 = 定位中心 + 唤醒边界编辑,任何模式) */
-  private pickBeacon(x: number, z: number): { cid: string, x: number, z: number } | null {
-    for (const b of this.blocks.values()) {
-      if (Math.hypot(b.x - x, b.z - z) < 34) return { cid: b.channelId, x: b.x, z: b.z }
-    }
-    return null
-  }
-
-  /** 领地平台面几何:按真实半轴的外形(椭圆/矩形);放平烘焙进顶点(XY→XZ,无镜像),
-   *  网格仅需 rotation.y —— 与边界线同一旋转语义,任意朝向严格贴合 */
-  private makePadShapeGeometry(shape: 'ellipse' | 'rect', radiusX: number, radiusZ: number): THREE.ShapeGeometry {
-    const shp = new THREE.Shape()
-    if (shape === 'rect') {
-      shp.moveTo(-radiusX, -radiusZ)
-      shp.lineTo(radiusX, -radiusZ)
-      shp.lineTo(radiusX, radiusZ)
-      shp.lineTo(-radiusX, radiusZ)
-      shp.closePath()
-    }
-    else {
-      shp.absellipse(0, 0, radiusX, radiusZ, 0, Math.PI * 2)
-    }
-    const geo = new THREE.ShapeGeometry(shp, shape === 'rect' ? 1 : 56)
-    geo.rotateX(Math.PI / 2)
-    return geo
-  }
-
-  /** 领地边框几何:外形挖去内缩 ringW 的同形内形(椭圆/矩形;恒定世界线宽) */
-  private makePadRingGeometry(shape: 'ellipse' | 'rect', radiusX: number, radiusZ: number, ringW = 13): THREE.ShapeGeometry {
-    const irx = Math.max(4, radiusX - ringW)
-    const irz = Math.max(4, radiusZ - ringW)
-    const outer = new THREE.Shape()
-    const inner = new THREE.Path()
-    if (shape === 'rect') {
-      outer.moveTo(-radiusX, -radiusZ)
-      outer.lineTo(radiusX, -radiusZ)
-      outer.lineTo(radiusX, radiusZ)
-      outer.lineTo(-radiusX, radiusZ)
-      outer.closePath()
-      inner.moveTo(-irx, -irz)
-      inner.lineTo(irx, -irz)
-      inner.lineTo(irx, irz)
-      inner.lineTo(-irx, irz)
-      inner.closePath()
-    }
-    else {
-      outer.absellipse(0, 0, radiusX, radiusZ, 0, Math.PI * 2)
-      inner.absellipse(0, 0, irx, irz, 0, Math.PI * 2)
-    }
-    outer.holes.push(inner)
-    const geo = new THREE.ShapeGeometry(outer, shape === 'rect' ? 1 : 56)
-    geo.rotateX(Math.PI / 2)
-    return geo
-  }
-
-  /** 平台/边框贴形(半径或形状变化后):平台与边框几何都按真实尺寸重建;同步朝向 */
-  private applyPadToBlock(b: Block3D): void {
-    const rotY = b.rotationY * Math.PI / 180
-    b.platform.rotation.set(0, rotY, 0)
-    b.padRing.rotation.set(0, rotY, 0)
-    const oldP = b.platform.geometry
-    b.platform.geometry = this.makePadShapeGeometry(b.shape, b.radiusX, b.radiusZ)
-    oldP.dispose()
-    const old = b.padRing.geometry
-    b.padRing.geometry = this.makePadRingGeometry(b.shape, b.radiusX, b.radiusZ)
-    old.dispose()
-  }
-
-  /** 文本 Sprite(名牌/名字)—— HMI 铭牌:深底 + 发丝描边 + 左缘数据条 + 等宽字。
-   *  accent: 左缘数据条与描边 tint 的身份色(Agent 铭牌传所属频道哈希色 → 归属一眼可辨)。 */
-  private makeLabel(text: string, x: number, y: number, z: number, accent = '#41c8f4'): THREE.Sprite {
-    const canvas = document.createElement('canvas')
-    const ctx = canvas.getContext('2d')!
-    const font = '600 21px "Geist Mono", Geist, "PingFang SC", monospace'
-    ctx.font = font
-    const padL = 26
-    const padR = 14
-    const w = Math.max(104, Math.ceil(ctx.measureText(text).width) + padL + padR)
-    const h = 48
-    canvas.width = w
-    canvas.height = h
-    ctx.font = font
-    // 深色铭牌底 + 半透明度(不遮场景,只提字)
-    ctx.fillStyle = 'rgba(10,14,20,0.8)'
-    ctx.fillRect(0, 0, w, h)
-    // 发丝描边(身份色轻 tint)+ 左缘数据条(身份色)
-    ctx.strokeStyle = `${accent}66`
-    ctx.lineWidth = 1
-    ctx.strokeRect(0.5, 0.5, w - 1, h - 1)
-    ctx.fillStyle = accent
-    ctx.fillRect(0, 0, 3, h)
-    ctx.fillStyle = '#dce7f0'
-    ctx.textAlign = 'left'
-    ctx.textBaseline = 'middle'
-    ctx.fillText(text, padL, h / 2 + 1)
-    const tex = new THREE.CanvasTexture(canvas)
-    tex.colorSpace = THREE.SRGBColorSpace
-    const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: tex, transparent: true, depthTest: false }))
-    sprite.scale.set(w / 6, h / 6, 1)
-    sprite.position.set(x, y, z)
-    this.scene.add(sprite)
-    return sprite
-  }
-
-  /** int 颜色 → CSS hex(铭牌身份色用) */
-  private hexOf(color: number): string {
-    return `#${color.toString(16).padStart(6, '0')}`
-  }
+  pickBeacon(x: number, z: number): { cid: string, x: number, z: number } | null { return pickBeacon(this, x, z) }
 
   // ================================================================
-  // Agent(3D 角色:根 Group + 模型 + 同频道色环 + 名字)
+  // Agent(3D 角色:根 Group + 模型 + 同频道色环 + 名字;
+  // 实现见 scene/town-scene3d-agents.ts)
   // ================================================================
 
-  private ensureAgent(a: TownEntityInput['agents'][number] & { channelId: string }, cx: number, cz: number, color: number): void {
-    const key = a.agentId
-    if (this.agents.has(key)) return
-    // 管理员布局落点(来自 config.homeX/homeZ)优先;缺省按领地内排布;整体钳制在频道边界内
-    const layout = this.blockLayout(a.channelId)
-    let homeX = a.homeX ?? cx
-    let homeZ = a.homeZ ?? cz
-    if (layout) {
-      const clamped = clampToBoundary(layout, homeX, homeZ, 20)
-      homeX = clamped.x
-      homeZ = clamped.z
-    }
-    // 管理员布局活动范围(来自 config.range;缺省 null = 沿用频道边界);收进频道边界
-    const range: AgentRangeLayout | null = a.range ?? null
-    const root = new THREE.Group()
-    root.position.set(homeX, GROUND_Y, homeZ)
-    const nameSprite = this.makeLabel(a.name, homeX, 48, homeZ, this.hexOf(color))
-    // 默认模型(内置二次元角色 hero-anime-1「樱叶少女」;模型库换装可覆盖)
-    const texKey = a.modelRef || 'hero-anime-1'
-    const model = new THREE.Group()
-    root.add(model)
-    this.scene.add(root)
-    const agent = new Agent3D({
-      channelId: a.channelId,
-      agentId: key,
-      name: a.name,
-      role: a.role,
-      root,
-      model,
-      mixer: null,
-      clips: [],
-      colorNum: color,
-      nameSprite,
-      bubble: null,
-      bubbleText: null,
-      bubbleTimer: null,
-      state: a.state,
-      progress: a.currentTaskProgress ?? null,
-      dragging: false,
-      homeX,
-      homeZ,
-      range,
-      rangeLine: null,
-      textureKey: texKey,
-      modelRef: a.modelRef ?? '',
-      behavior: { mode: 'idle', roamTarget: null, targetId: null, waitUntil: 0, pauseUntil: 0, engaged: false },
-    })
-    agent.host = this
-    agent.attachAura(color, a.role)
-    this.agents.set(key, agent)
-    // 载入模型(GLB);模型库注册先于/晚于挂载都能正确解析(内置二次元角色按 id 直取文件)
-    const info = this.modelsById.get(texKey)
-      ?? (texKey.startsWith('hero-anime-')
-        ? { id: texKey, file: `/assets/game/character/${texKey}.glb`, name: '二次元角色' }
-        : (this.modelsById.get('hero-3d') ?? { id: 'hero-3d', file: '/assets/game/character/hero-3d.glb', name: '标准员工模型' }))
-    void this.mountModel(agent, info.file, info.name)
-    agent.renderRangeLine()
-    this.emit('agentCount', this.agents.size)
-  }
-
-  /**
-   * 绑定模型到 Agent(GLTFLoader 加载 → 归一化 scale/锚点贴地 → 若有动画则 mixer)。
-   * 缺失/失败 → 回退内置 hero-3d,永不白屏。
-   */
-  private async mountModel(asp: Agent3D, file: string, name: string): Promise<void> {
-    const cached = this.gltfCache.get(file)
-    let loaded: THREE.Group
-    let height: number
-    if (cached) {
-      loaded = cached.scene.clone(true)
-      height = cached.height
-    }
-    else {
-      try {
-        const gltf = await this.loadGltf(file)
-        loaded = gltf.scene
-        const box = new THREE.Box3().setFromObject(loaded)
-        height = Math.max(0.5, box.max.y - box.min.y)
-        this.gltfCache.set(file, { file, scene: loaded, height })
-        // 缓存动画 clip(供 mixer 状态切换;GLTFLoader 动画必须在解析层保留)
-        this.agentAnimClips.set(file, gltf.animations)
-      }
-      catch {
-        // 加载失败回退程序化「孪生机器人」(胶囊躯干 + 发光核心 + 天线),角色永不隐形
-        loaded = this.makeFallbackBot()
-        height = 1.4
-      }
-    }
-    // 归一化 scale(使模型高度≈UNITS 世界单位)并贴地(模型大小自适应)
-    loaded.position.y = 0
-    loaded.scale.setScalar(UNITS / height)
-    // 真实投影 + PBR 增强:模型网格 cast/receiveShadow(体积感) + 分级环境反射(角色质感)
-    loaded.traverse((o) => {
-      if ((o as THREE.Mesh).isMesh) o.castShadow = true
-    })
-    this.enhancePbrMaterials(loaded, 'character')
-    // 清掉旧模型子节点与 mixer
-    asp.model.clear()
-    asp.model.add(loaded)
-    // 客制化:注册可缩放目标并恢复用户缩放(套在 asp.model 上,作为自适应之上的倍率层)
-    this.registerScalable('agent', asp.agentId, asp.model)
-    asp.mixer = null
-    asp.activeAction = null
-    const clips = this.agentAnimClips.get(file) ?? []
-    const firstClip = clips[0]
-    if (firstClip) {
-      asp.mixer = new THREE.AnimationMixer(loaded)
-      asp.clips = clips
-      const firstAction = asp.mixer.clipAction(firstClip)
-      firstAction.play()
-      asp.activeAction = firstAction
-    }
-    void name
-    this.dirty = true
-  }
-
-  private agentAnimClips = new Map<string, THREE.AnimationClip[]>()
-
-  private loadGltf(file: string): Promise<{ scene: THREE.Group, animations: THREE.AnimationClip[] }> {
-    return new Promise((resolve, reject) => {
-      this.gltfLoader.load(file, gltf => resolve({ scene: gltf.scene as THREE.Group, animations: gltf.animations ?? [] }), undefined, reject)
-    })
+  /** 按实体元数据实例化 Agent3D(落点钳制 / 活动范围 / 身份光环 / 名牌) */
+  ensureAgent(a: TownEntityInput['agents'][number] & { channelId: string }, cx: number, cz: number, color: number): void {
+    ensureAgent(this, a, cx, cz, color)
   }
 
-  /**
-   * 程序化「孪生机器人」兜底模型:GLB 缺失/加载失败时使用,保证 Agent 永远可见。
-   * 结构:胶囊躯干 + 头部 + 发光核心胸灯 + 天线信号球 + 悬浮底盘;中性工业灰 + 青蓝核心。
-   */
-  private makeFallbackBot(): THREE.Group {
-    const bot = new THREE.Group()
-    const bodyMat = new THREE.MeshStandardMaterial({ color: 0x2a3542, roughness: 0.42, metalness: 0.62 })
-    const darkMat = new THREE.MeshStandardMaterial({ color: 0x141b24, roughness: 0.6, metalness: 0.4 })
-    const coreMat = new THREE.MeshBasicMaterial({ color: 0x41c8f4 })
-    // 躯干(胶囊)
-    const body = new THREE.Mesh(new THREE.CapsuleGeometry(0.42, 0.62, 8, 16), bodyMat)
-    body.position.y = 0.86
-    // 头部
-    const head = new THREE.Mesh(new THREE.SphereGeometry(0.32, 16, 12), bodyMat)
-    head.position.y = 1.62
-    // 面窗(发光条带,数字孪生眼)
-    const visor = new THREE.Mesh(new THREE.BoxGeometry(0.4, 0.1, 0.12), coreMat)
-    visor.position.set(0, 1.66, 0.27)
-    // 发光核心胸灯
-    const core = new THREE.Mesh(new THREE.SphereGeometry(0.14, 12, 8), coreMat)
-    core.position.set(0, 1.1, 0.36)
-    // 悬浮底盘
-    const base = new THREE.Mesh(new THREE.CylinderGeometry(0.5, 0.62, 0.26, 16), darkMat)
-    base.position.y = 0.16
-    // 天线 + 信号球
-    const antenna = new THREE.Mesh(new THREE.CylinderGeometry(0.03, 0.03, 0.5, 6), darkMat)
-    antenna.position.set(0, 2.04, 0)
-    const signal = new THREE.Mesh(new THREE.SphereGeometry(0.08, 10, 8), coreMat)
-    signal.position.set(0, 2.34, 0)
-    bot.add(body, head, visor, core, base, antenna, signal)
-    return bot
-  }
+  agentAnimClips = new Map<string, THREE.AnimationClip[]>()
 
   /** 注册模型清单，并将晚到资产挂载到已存在的 Agent/设备。 */
   registerModelsFromList(list: Array<{ id: string, file: string, name: string, kind?: string, hFactor?: number }>): void {
-    if (this.disposed) return
-    const changed = new Set<string>()
-    for (const model of list) {
-      const previous = this.modelsById.get(model.id)
-      if (!previous || previous.file !== model.file || previous.name !== model.name || previous.kind !== model.kind || previous.hFactor !== (model.hFactor ?? 1)) {
-        this.modelsById.set(model.id, { ...model, hFactor: model.hFactor ?? 1 })
-        changed.add(model.id)
-      }
-    }
-    if (changed.size > 0) {
-      for (const agent of this.agents.values()) {
-        if (!agent.modelRef || !changed.has(agent.modelRef)) continue
-        const model = this.modelsById.get(agent.modelRef)
-        if (model) void this.mountModel(agent, model.file, model.name)
-      }
-      for (const device of this.deviceNodes.values()) {
-        if (changed.has(device.modelRef)) this.swapDeviceModelSprite(device, device.modelRef)
-      }
-    }
-    for (const twin of [...this.pendingDeviceTwins.values()]) {
-      const isDaq = twin.kind === 'daq' || (twin.modelRef ?? '').startsWith('daq-')
-      if (!isDaq && !this.modelsById.get(twin.modelRef)?.file) continue
-      this.pendingDeviceTwins.delete(twin.id)
-      this.recreateDeviceNode(twin)
-    }
+    registerModelsFromList(this, list)
   }
 
   // ================================================================
-  // 布局注入 / 重建 / 聚焦 / 事件入口(公开面与 2D 镜像)
+  // 布局注入 / 重建 / 聚焦 / 事件入口(公开面与 2D 镜像;
+  // 领地层实现见 scene/town-scene3d-blocks.ts)
   // ================================================================
 
   /**
    * 注入频道领地布局(来自 useSceneLayouts)。构建场景前必须调用;
    * 未放置的频道会在 rebuild 时被跳过(只停留在频道坞)。
    */
-  applySceneLayouts(layouts: ChannelLayout[]): void {
-    this.layouts.clear()
-    for (const l of layouts) {
-      const n = normLayout(l)
-      this.layouts.set(n.channelId, n)
-    }
-  }
+  applySceneLayouts(layouts: ChannelLayout[]): void { applySceneLayouts(this, layouts) }
 
   /** 频道是否已放入场景(供频道坞标记已放置/未放置) */
-  hasChannel(channelId: string): boolean {
-    return this.blocks.has(channelId)
-  }
+  hasChannel(channelId: string): boolean { return hasChannel(this, channelId) }
 
   /** 频道当前布局(供边界约束;未放置返回空) */
-  private blockLayout(channelId: string): ChannelLayout | null {
-    const b = this.blocks.get(channelId)
-    return b ? b.layout() : null
-  }
+  blockLayout(channelId: string): ChannelLayout | null { return blockLayout(this, channelId) }
 
   /** 已放入场景的频道集(供频道坞/选中面板) */
-  placedChannels(): string[] {
-    return [...this.blocks.keys()]
-  }
+  placedChannels(): string[] { return placedChannels(this) }
 
   /** 频道当前布局(供边界编辑面板初始化) */
-  getChannelLayout(channelId: string): ChannelLayout | null {
-    const b = this.blocks.get(channelId)
-    return b ? b.layout() : null
-  }
+  getChannelLayout(channelId: string): ChannelLayout | null { return getChannelLayout(this, channelId) }
 
   // ================================================================
   // 控制器公开面(供实体 class 反向调用:场景图/脏标记/布局表/设备名牌与模型)
@@ -1718,29 +364,13 @@ export class TownScene3D {
   }
 
   /** 记录频道当前布局到场景布局表(移动/缩放后由 Block3D 调用) */
-  trackLayout(b: Block3D): void {
-    this.layouts.set(b.channelId, b.normLayout())
-  }
+  trackLayout(b: Block3D): void { trackLayout(this, b) }
 
-  /** 设备改名:重建名牌 Sprite(由 DeviceNode.applyTwin 委托) */
-  renameDeviceSprite(dev: DeviceNode, name: string): void {
-    dev.name = name.trim()
-    this.scene.remove(dev.label)
-    dev.label = this.makeLabel(`⚙ ${dev.name}`, dev.root.position.x, 60, dev.root.position.z)
-    this.dirty = true
-  }
+  /** 设备改名:重建名牌 Sprite(由 DeviceNode.applyTwin 委托;实现见 scene/town-scene3d-devices.ts) */
+  renameDeviceSprite(dev: DeviceNode, name: string): void { renameDeviceSprite(this, dev, name) }
 
-  /** 设备换模型:按 modelRef 重挂 GLB 到 holder(由 DeviceNode.applyTwin 委托)。 */
-  swapDeviceModelSprite(dev: DeviceNode, modelRef: string): void {
-    const info = this.modelsById.get(modelRef)
-    if (!info?.file) return
-    if (dev.modelRef === modelRef && dev.holder.userData.modelFile === info.file) return
-    dev.modelRef = modelRef
-    dev.holder.clear()
-    dev.holder.userData.modelFile = info.file
-    void this.loadGltfToGroup(info.file, dev.holder, UNITS * 1.6)
-    this.dirty = true
-  }
+  /** 设备换模型:按 modelRef 重挂 GLB 到 holder(由 DeviceNode.applyTwin 委托) */
+  swapDeviceModelSprite(dev: DeviceNode, modelRef: string): void { swapDeviceModelSprite(this, dev, modelRef) }
 
   /** 统一实例化入口:按数据库元数据(布局/实体/设备孪生)实例化并初始化场景内全部实例。 */
   hydrate(channels: TownEntityInput[], layouts: ChannelLayout[], devices: DeviceTwinSync[]): void {
@@ -1765,7 +395,7 @@ export class TownScene3D {
   }
 
   // ================================================================
-  // 频道放置(drop 入口)+ 活动边界编辑
+  // 频道放置(drop 入口)+ 活动边界编辑(实现见 scene/town-scene3d-blocks.ts)
   // ================================================================
 
   /**
@@ -1773,285 +403,61 @@ export class TownScene3D {
    * 频道 id 需已在实体基线中;返回落点世界坐标(供 HUD 提示)。
    */
   dropChannelOnWorld(x: number, z: number, channelId: string, channelName: string, agentCount: number): { x: number, z: number, channelId: string, name: string } {
-    const existing = this.blocks.get(channelId)
-    if (existing) {
-      this.focusTo(existing.x, existing.z)
-      return { x: Math.round(existing.x), z: Math.round(existing.z), channelId, name: existing.name }
-    }
-    // 缺省布局:以落点为中心、与 Agent 数匹配的边界
-    const rx = Math.max(120, 110 + agentCount * 18)
-    const rz = Math.max(80, 70 + agentCount * 14)
-    const layout: ChannelLayout = { channelId, x, z, radiusX: rx, radiusZ: rz, shape: 'ellipse', rotationY: 0 }
-    this.layouts.set(channelId, normLayout(layout))
-    // 从实体基线取该频道 agents(由 TownView ensureChannelPresent 提前放置)
-    const seed = this.entityIndex.get(channelId)
-    if (seed) {
-      this.placeChannel(seed, layout)
-    }
-    else {
-      // 无实体基线(频道坞拖入,数据尚未到达):只建空领地占位
-      const color = channelColorNum(channelId)
-      const pad = this.makeBlock(channelName, color, layout)
-      const block = new Block3D({
-        channelId, name: channelName, x, z,
-        radiusX: layout.radiusX, radiusZ: layout.radiusZ,
-        shape: layout.shape, rotationY: layout.rotationY, color,
-        platform: pad.platform,
-        padRing: pad.padRing,
-        beacon: pad.beacon,
-        boundary: makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, color),
-        label: this.makeLabel(channelName, x, 30, z),
-      })
-      block.host = this
-      block.boundary.position.set(x, 0.3, z)
-      this.scene.add(block.boundary)
-      this.blocks.set(channelId, block)
-    }
-    this.emit('blockCount', this.blocks.size)
-    this.emit('agentCount', this.agents.size)
-    return { x: Math.round(x), z: Math.round(z), channelId, name: channelName }
+    return dropChannelOnWorld(this, x, z, channelId, channelName, agentCount)
   }
 
   /** 更新频道布局(编辑边界后本地即时生效;持久化由 TownView 经 useSceneLayouts.save 落库) */
-  updateChannelLayout(channelId: string, patch: Partial<ChannelLayout>): void {
-    const b = this.blocks.get(channelId)
-    if (!b) return
-    if (patch.x !== undefined) b.x = patch.x
-    if (patch.z !== undefined) b.z = patch.z
-    if (patch.radiusX !== undefined) b.radiusX = Math.max(60, patch.radiusX)
-    if (patch.radiusZ !== undefined) b.radiusZ = Math.max(40, patch.radiusZ)
-    if (patch.shape !== undefined) b.shape = patch.shape
-    if (patch.rotationY !== undefined) b.rotationY = patch.rotationY
-    const layout = normLayout({ channelId, x: b.x, z: b.z, radiusX: b.radiusX, radiusZ: b.radiusZ, shape: b.shape, rotationY: b.rotationY })
-    this.layouts.set(channelId, layout)
-    // 重建领地平台/边界/名牌
-    this.scene.remove(b.boundary)
-    this.applyPadToBlock(b)
-    b.boundary = makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, b.color)
-    b.boundary.position.set(layout.x, 0.3, layout.z)
-    b.boundary.rotation.y = layout.rotationY * Math.PI / 180
-    this.scene.add(b.boundary)
-    // 频道边界变化后把成员活动范围一并收进新边界(面板滑杆编辑路径)
-    this.clampAgentsToBoundary(channelId)
-    this.dirty = true
-  }
+  updateChannelLayout(channelId: string, patch: Partial<ChannelLayout>): void { updateChannelLayout(this, channelId, patch) }
 
   /** 移除频道放置(从场景撤走领地及其 Agent) */
-  removeChannel(channelId: string): void {
-    const b = this.blocks.get(channelId)
-    if (!b) return
-    this.scene.remove(b.platform)
-    this.scene.remove(b.padRing)
-    this.scene.remove(b.beacon)
-    if (b.boundary) this.scene.remove(b.boundary)
-    this.scene.remove(b.label)
-    for (const [aid, a] of [...this.agents.entries()]) {
-      if (a.channelId === channelId) {
-        this.scene.remove(a.root)
-        if (a.nameSprite) this.scene.remove(a.nameSprite)
-        if (a.bubble) this.scene.remove(a.bubble)
-        if (a.rangeLine) this.scene.remove(a.rangeLine)
-        this.disposeAgentAssets(a)
-        this.agents.delete(aid)
-      }
-    }
-    if (b.label) this.disposeCanvasTextures(b.label)
-    if (this.rangeDrawAgent && this.agents.get(this.rangeDrawAgent) === undefined) this.cancelRangeDraw()
-    this.blocks.delete(channelId)
-    this.layouts.delete(channelId)
-    this.receivers.delete(channelId)
-    for (const hl of this.resizeHandles) hl.mesh.visible = false
-    for (const hl of this.agentRangeHandles) hl.mesh.visible = false
-    if (this.selectedChannel === channelId) {
-      this.selectedChannel = null
-      this.emit('selectChannel', null)
-    }
-    this.emit('blockCount', this.blocks.size)
-    this.emit('agentCount', this.agents.size)
-    this.dirty = true
-  }
+  removeChannel(channelId: string): void { removeChannel(this, channelId) }
 
   // ================================================================
   // 频道整体拖拽 / 边界手柄缩放(编辑模式;用户自定义布局)
+  // 实现见 scene/town-scene3d-editing.ts
   // ================================================================
 
   /** 把频道地块整体平移(委托 Block3D.moveBy:平台/边界/名牌/成员落点与各自范围一并位移) */
-  private applyBlockMove(b: Block3D, nx: number, nz: number): void {
-    b.moveBy(nx - b.x, nz - b.z)
-    this.refreshAgentRangeHandles()
-    this.dirty = true
-  }
+  applyBlockMove(b: Block3D, nx: number, nz: number): void { applyBlockMove(this, b, nx, nz) }
 
   /** 按当前 Block 字段重建领地几何(平台刻度/边界线框/朝向),供缩放与移动共用 */
-  private applyLayoutToBlock(b: Block3D): void {
-    const layout = { channelId: b.channelId, x: b.x, z: b.z, radiusX: b.radiusX, radiusZ: b.radiusZ, shape: b.shape, rotationY: b.rotationY }
-    this.layouts.set(b.channelId, normLayout(layout))
-    b.platform.position.set(b.x, 0.16, b.z)
-    b.padRing.position.set(b.x, 0.34, b.z)
-    this.applyPadToBlock(b)
-    if (b.boundary) this.scene.remove(b.boundary)
-    b.boundary = makeBoundary(b.shape, b.radiusX, b.radiusZ, b.color)
-    b.boundary.position.set(b.x, 0.3, b.z)
-    b.boundary.rotation.y = b.rotationY * Math.PI / 180
-    this.scene.add(b.boundary)
-    this.dirty = true
-  }
+  applyLayoutToBlock(b: Block3D): void { applyLayoutToBlock(this, b) }
 
-  /** 边界手柄本地坐标(椭圆:轴向四点;矩形:四角;radius 是半轴或半宽)。 */
-  private boundaryHandlePoints(layout: { radiusX: number, radiusZ: number, shape: 'ellipse' | 'rect' }): Array<[number, number]> {
-    if (layout.shape === 'rect') return [[layout.radiusX, layout.radiusZ], [-layout.radiusX, layout.radiusZ], [-layout.radiusX, -layout.radiusZ], [layout.radiusX, -layout.radiusZ]]
-    return [[layout.radiusX, 0], [-layout.radiusX, 0], [0, layout.radiusZ], [0, -layout.radiusZ]]
-  }
+  /** 边界手柄本地坐标(椭圆:轴向四点;矩形:四角;radius 是半轴或半宽)。宿主契约面:ranges 模块回调。 */
+  boundaryHandlePoints(layout: { radiusX: number, radiusZ: number, shape: 'ellipse' | 'rect' }): Array<[number, number]> { return boundaryHandlePoints(layout) }
 
   /** 刷新边界手柄位置/可见性(编辑模式选中频道时显示;其余隐藏) */
-  private refreshChannelHandles(): void {
-    for (const hl of this.resizeHandles) hl.mesh.visible = false
-    if (this.mode !== 'edit' || !this.selectedChannel) return
-    const b = this.blocks.get(this.selectedChannel)
-    if (!b) return
-    const rot = b.rotationY * Math.PI / 180
-    const pts = this.boundaryHandlePoints(b)
-    for (let i = 0; i < this.resizeHandles.length && i < pts.length; i++) {
-      const [lx, lz] = pts[i]!
-      const wx = b.x + lx * Math.cos(rot) - lz * Math.sin(rot)
-      const wz = b.z + lx * Math.sin(rot) + lz * Math.cos(rot)
-      this.resizeHandles[i]!.cid = b.channelId
-      this.resizeHandles[i]!.mesh.position.set(wx, 1.4, wz)
-      this.resizeHandles[i]!.mesh.visible = true
-    }
-  }
+  refreshChannelHandles(): void { refreshChannelHandles(this) }
 
   /** 命中边界手柄(仅编辑模式;返回频道 id + 手柄号) */
-  private pickResizeHandle(x: number, z: number): { cid: string, handle: number } | null {
-    if (this.mode !== 'edit') return null
-    for (const hl of this.resizeHandles) {
-      if (!hl.mesh.visible) continue
-      if (Math.hypot(hl.mesh.position.x - x, hl.mesh.position.z - z) < 90) return { cid: hl.cid, handle: hl.handle }
-    }
-    return null
-  }
+  pickResizeHandle(x: number, z: number): { cid: string, handle: number } | null { return pickResizeHandle(this, x, z) }
 
   /** 拖拽手柄 → 实时调整 radiusX/radiusZ(矩形:角点双轴;椭圆:对应轴向轴点)。 */
-  private applyResize(b: Block3D, handle: number, wx: number, wz: number): void {
-    const rad = -b.rotationY * Math.PI / 180
-    const cos = Math.cos(rad)
-    const sin = Math.sin(rad)
-    const dx = wx - b.x
-    const dz = wz - b.z
-    const lx = dx * cos - dz * sin
-    const lz = dx * sin + dz * cos
-    if (b.shape === 'rect') {
-      // radiusX/radiusZ 表示半宽:角点到中心的局部距离即新半宽(无上限,相机自动跟随取景)
-      b.radiusX = Math.max(60, Math.abs(lx))
-      b.radiusZ = Math.max(40, Math.abs(lz))
-    }
-    else {
-      if (handle === 0 || handle === 1) b.radiusX = Math.max(60, Math.abs(lx))
-      else b.radiusZ = Math.max(40, Math.abs(lz))
-    }
-    this.applyLayoutToBlock(b)
-    this.refreshChannelHandles()
-    this.autoFrameTo(b.radiusX, b.radiusZ)
-    this.dirty = true
-  }
+  applyResize(b: Block3D, handle: number, wx: number, wz: number): void { applyResize(this, b, handle, wx, wz) }
 
   /** 缩放/移动结束后把该频道成员落点与活动范围钳回新边界内(委托 Block3D) */
-  private clampAgentsToBoundary(channelId: string): void {
-    const b = this.blocks.get(channelId)
-    if (!b) return
-    b.clampMembersAndRanges()
-    this.dirty = true
-  }
+  clampAgentsToBoundary(channelId: string): void { clampAgentsToBoundary(this, channelId) }
 
   /** 频道是否在场景内且被选中(供边界编辑面板) */
-  getSelectedChannel(): string | null {
-    return this.selectedChannel
-  }
+  getSelectedChannel(): string | null { return getSelectedChannel(this) }
 
   /** 点选频道(供频道坞/边界编辑面板打开) */
-  selectChannel(channelId: string | null): void {
-    this.selectedChannel = channelId
-    this.emit('selectChannel', channelId)
-    this.refreshChannelHandles()
-    this.cancelRangeDraw()
-    this.refreshAgentRangeHandles()
-    // 选中频道边界高亮勾边(取消时恢复频道本色)
-    for (const bb of this.blocks.values()) {
-      const m = bb.boundary.material as THREE.LineBasicMaterial
-      m.color.setHex(bb.channelId === channelId ? 0xf6c453 : bb.color)
-      m.opacity = bb.channelId === channelId ? 1 : 0.75
-    }
-    // 拖拽中不聚焦(避免拖频道/手柄时相机被拽走导致落点错乱)
-    if (channelId && !this.pointerDrag) this.focusTo(this.blocks.get(channelId)?.x ?? WORLD_CX, this.blocks.get(channelId)?.z ?? WORLD_CZ)
-  }
+  selectChannel(channelId: string | null): void { selectChannel(this, channelId) }
 
   /** 当前场景内全部频道布局(供「保存全部布局」/E2E) */
-  getAllChannelLayouts(): ChannelLayout[] {
-    return [...this.blocks.values()].map(b => ({
-      channelId: b.channelId, x: b.x, z: b.z,
-      radiusX: b.radiusX, radiusZ: b.radiusZ,
-      shape: b.shape, rotationY: b.rotationY,
-    }))
-  }
+  getAllChannelLayouts(): ChannelLayout[] { return getAllChannelLayouts(this) }
 
-  handleTownEvent(e: AepEnvelope): void {
-    if (e.type === 'channel.snapshot') return
-    // 频道布局事件:本地已放同一频道则即时应用(他人编辑边界/移入场景 → 本端同步)
-    if (e.type === 'scene.layout.saved') {
-      const l = e.payload as ChannelLayout
-      if (this.blocks.has(l.channelId)) {
-        this.applySceneLayouts([...(this.layouts.values()), l])
-        // 更新对应领地几何
-        const cur = this.getChannelLayout(l.channelId)
-        if (cur) this.updateChannelLayout(l.channelId, l)
-      }
-      return
-    }
-    if (e.type === 'scene.layout.removed') {
-      const { channelId } = e.payload as { channelId: string }
-      this.removeChannel(channelId)
-      return
-    }
-    const intent = mapEnvelopeToIntent(e)
-    if (!intent) return
-    if (intent.agentId) {
-      const asp = this.agents.get(intent.agentId)
-      if (asp) {
-        if (e.type === 'agent.status') {
-          asp.state = (e.payload as { state: 'idle' | 'busy' | 'stopped' }).state
-          if (asp.state !== 'busy') asp.progress = null
-        }
-        if (e.type === 'task.progress') asp.progress = (e.payload as { progress: number }).progress
-        this.dirty = true
-      }
-    }
-    if (intent.bubble) this.enqueueBubble(intent.bubble.channelId, intent.bubble.agentId, intent.bubble.kind, intent.bubble.text, intent.bubble.ttlMs)
-    this.emitResonance(e)
-    const action = parseActionFromEnvelope(e, { resolveTaskAssignee: this.resolveTaskAssignee ?? undefined })
-    if (action) this.startBehavior(action)
-  }
+  /** WS 事件入口(与 2D 同构):布局同步 / 状态收敛 / 气泡入队 / 共鸣 / 行为决策(实现见 scene/town-scene3d-events.ts) */
+  handleTownEvent(e: AepEnvelope): void { handleTownEvent(this, e) }
 
   // ================================================================
-  // 行为 FSM(3D x/z 平面,复刻 2D 逻辑)
+  // 行为 FSM(3D x/z 平面,复刻 2D 逻辑;实现见 scene/town-scene3d-events.ts)
   // ================================================================
 
-  private startBehavior(action: ActionContext): void {
-    const from = this.agents.get(action.fromId)
-    const to = this.agents.get(action.toId)
-    if (!from || !to || from.dragging) return
-    from.behavior.mode = 'approach'
-    from.behavior.targetId = to.agentId
-    from.behavior.action = action
-    if (!to.dragging) {
-      to.behavior.engaged = true
-      to.behavior.roamTarget = null
-    }
-    this.emit('behavior', { agentName: from.name, action: this.behaviorActionLabel(action.kind), targetName: to.name })
-  }
+  /** 触发一次「跑去下发」行为:from 跑到 to 身边 */
+  startBehavior(action: ActionContext): void { startBehavior(this, action) }
 
-  private behaviorActionLabel(kind: ActionKind): string {
-    return kind === 'task' ? '下发任务' : '回复'
-  }
+  behaviorActionLabel(kind: ActionKind): string { return behaviorActionLabel(kind) }
 
   /** 动画状态切换广播(数据驱动模型 → HUD/E2E 观察) */
   notifyMotion(asp: Agent3D): void {
@@ -2082,348 +488,43 @@ export class TownScene3D {
     return this.blockLayout(channelId)
   }
 
-  private resolveFile(id: string): string {
-    return this.modelsById.get(id)?.file ?? ''
-  }
-
   /** 相机注视目标(供频道坞首放落点/聚焦) */
-  getCameraTarget(): { x: number, z: number } {
-    return { x: Math.round(this.camTarget.x), z: Math.round(this.camTarget.z) }
-  }
+  getCameraTarget(): { x: number, z: number } { return getCameraTarget(this) }
 
   /** 为指定角色换装模型(选择器绑定;要求实体已在场景,否则仅记录) */
-  swapAgentModel(agentId: string, modelRef: string): void {
-    const asp = this.agents.get(agentId)
-    if (!asp) return
-    const info = this.modelsById.get(modelRef)
-    const file = info?.file ?? '/assets/game/character/hero-3d.glb'
-    asp.modelRef = modelRef
-    asp.textureKey = modelRef
-    void this.mountModel(asp, file, info?.name ?? modelRef)
-  }
+  swapAgentModel(agentId: string, modelRef: string): void { swapAgentModel(this, agentId, modelRef) }
 
   // ================================================================
   // 事件共鸣(说话/完成/错误/旗) —— 3D 圆环/光柱
+  // 实现见 scene/town-scene3d-events.ts
   // ================================================================
 
-  private emitResonance(e: AepEnvelope): void {
-    const b = this.blocks.get(e.channelId)
-    const asp = e.agentId ? this.agents.get(e.agentId) : undefined
-    const x = asp?.root.position.x ?? b?.x
-    const z = asp?.root.position.z ?? b?.z
-    if (x === undefined || z === undefined) return
-    if (e.type === 'agent.message' || e.type === 'agent.status.message' || e.type === 'a2a.message') {
-      this.pulseRing(x, z, asp ? 0x41c8f4 : (b?.color ?? 0x41c8f4))
-    }
-    else if (e.type === 'error' || (e.type === 'task.status' && ((e.payload as { state?: string }).state === 'failed' || (e.payload as { state?: string }).state === 'canceled'))) {
-      this.pulseRing(x, z, 0xff6b6b)
-    }
-    else if (e.type === 'task.status' && (e.payload as { state?: string }).state === 'completed') {
-      this.lightColumn(x, z, 0x35e0a0)
-    }
-  }
-
-  /** 事件共鸣扩散环(时间基:800ms 缓出扩散 + 淡出;帧率无关,结束即释放资源) */
-  private pulseRing(x: number, z: number, color: number): void {
-    const ring = new THREE.Mesh(new THREE.RingGeometry(10, 22, 24), new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.8, side: THREE.DoubleSide, depthWrite: false }))
-    ring.rotation.x = -Math.PI / 2
-    ring.position.set(x, 0.4, z)
-    this.scene.add(ring)
-    const start = performance.now()
-    const dur = 800
-    const step = () => {
-      const k = Math.min(1, (performance.now() - start) / dur)
-      const e = 1 - Math.pow(1 - k, 3)
-      ring.scale.setScalar(1 + e * 1.6)
-      ;(ring.material as THREE.MeshBasicMaterial).opacity = 0.8 * (1 - e)
-      if (k >= 1) {
-        this.scene.remove(ring)
-        ring.geometry.dispose()
-        ;(ring.material as THREE.MeshBasicMaterial).dispose()
-        return
-      }
-      this.rafAnims.push(step)
-    }
-    this.rafAnims.push(step)
-  }
-
-  /** 交付光柱(时间基:底部锚定向上生长 + 淡出;几何上移锚定,修复旧零高度柱不可见的缺陷) */
-  private lightColumn(x: number, z: number, color: number): void {
-    const geo = new THREE.CylinderGeometry(6, 12, 120, 16)
-    geo.translate(0, 60, 0)
-    const beam = new THREE.Mesh(geo, new THREE.MeshBasicMaterial({ color, transparent: true, opacity: 0.8, depthWrite: false }))
-    beam.position.set(x, 0, z)
-    beam.scale.y = 0.01
-    this.scene.add(beam)
-    const start = performance.now()
-    const dur = 900
-    const step = () => {
-      const k = Math.min(1, (performance.now() - start) / dur)
-      const e = 1 - Math.pow(1 - k, 2)
-      beam.scale.y = 0.01 + e * 0.99
-      ;(beam.material as THREE.MeshBasicMaterial).opacity = 0.8 * (1 - k)
-      if (k >= 1) {
-        this.scene.remove(beam)
-        beam.geometry.dispose()
-        ;(beam.material as THREE.MeshBasicMaterial).dispose()
-        return
-      }
-      this.rafAnims.push(step)
-    }
-    this.rafAnims.push(step)
-  }
+  emitResonance(e: AepEnvelope): void { emitResonance(this, e) }
 
-  private rafAnims: Array<() => void> = []
+  rafAnims: Array<() => void> = []
 
   /** 频道领地布局(channelId → 放置);由 applySceneLayouts 注入,驱动 buildBlocks/边界约束 */
-  private layouts = new Map<string, ChannelLayout>()
+  layouts = new Map<string, ChannelLayout>()
   /** 频道实体基线(channelId → seed;供 dropChannelOnWorld 即时铺放) */
-  private entityIndex = new Map<string, TownEntityInput>()
+  entityIndex = new Map<string, TownEntityInput>()
   /** 当前选中频道(供边界编辑面板) */
-  private selectedChannel: string | null = null
+  selectedChannel: string | null = null
 
   // ================================================================
   // 信息接收器 + 聊天气泡(每个实例化 Channel 一个接收器:FIFO 逐条消费,
   // WS 实时信息经 townBus → handleTownEvent 入队,渲染到对应 Agent 头顶,像真实对话)
+  // 实现见 scene/town-scene3d-bubbles.ts
   // ================================================================
 
   /** 实时信息(讲话/交付/错误)入队到目标频道的信息接收器;系统指标即时更新,3D 展示按 FIFO 消费 */
-  private enqueueBubble(channelId: string, agentId: string | undefined, kind: TownBubbleKind, text: string, ttlMs: number): void {
-    // 事件流 / 最近活动 / 调试气泡即时更新(展示延迟只作用于 3D 气泡)
-    this.dbgBubbles.push({ text, at: Date.now() })
-    if (this.dbgBubbles.length > 30) this.dbgBubbles.splice(0, this.dbgBubbles.length - 30)
-    const speaker = agentId ? this.agents.get(agentId)?.name : undefined
-    this.lastActivity = { channelId, agentName: speaker ?? this.blocks.get(channelId)?.name ?? '系统', text, at: Date.now() }
-    this.recentActivity.push(this.lastActivity)
-    if (this.recentActivity.length > 30) this.recentActivity.splice(0, this.recentActivity.length - 30)
-    this.emit('lastActivity', this.lastActivity)
-    // 入队(FIFO;超长队列丢最旧,防止异常风暴撑爆内存)
-    let rec = this.receivers.get(channelId)
-    if (!rec) {
-      rec = { channelId, queue: [], current: null, currentUntil: 0 }
-      this.receivers.set(channelId, rec)
-    }
-    if (rec.queue.length >= 24) rec.queue.splice(0, rec.queue.length - 24)
-    rec.queue.push({ agentId: agentId ?? null, kind, text, ttlMs })
-    this.dirty = true
+  enqueueBubble(channelId: string, agentId: string | undefined, kind: TownBubbleKind, text: string, ttlMs: number): void {
+    enqueueBubble(this, channelId, agentId, kind, text, ttlMs)
   }
 
   /** 各频道接收器 FIFO 消费:当前条目展示期满 → 清理其气泡并取下一条实时渲染(渲染循环每帧调用)。
    *  队列积压时按 drainDisplayMs 压缩单条时长,让爆发期消息尽快追平。 */
-  private drainReceivers(now: number): void {
-    for (const rec of this.receivers.values()) {
-      if (rec.current) {
-        if (now < rec.currentUntil) continue
-        this.clearReceiverBubble(rec.channelId, rec.current)
-        rec.current = null
-      }
-      const msg = rec.queue.shift()
-      if (!msg) continue
-      rec.current = msg
-      rec.currentUntil = now + drainDisplayMs(msg.text, rec.queue.length)
-      this.renderReceiverBubble(rec.channelId, msg)
-    }
-  }
-
-  /** 清除接收器条目对应的场景气泡(不同说话人衔接时避免叠泡) */
-  private clearReceiverBubble(channelId: string, msg: BubbleMsg): void {
-    if (!msg.agentId) return
-    const asp = this.agents.get(msg.agentId)
-    if (asp?.bubble) {
-      this.scene.remove(asp.bubble)
-      asp.bubble = null
-      asp.bubbleText = null
-      if (asp.bubbleTimer) {
-        clearTimeout(asp.bubbleTimer)
-        asp.bubbleTimer = null
-      }
-    }
-  }
-
-  /** 将接收器消息渲染为 2.5D 聊天气泡(说话 Agent 头顶;无对应用户则挂频道名牌上方) */
-  private renderReceiverBubble(channelId: string, msg: BubbleMsg): void {
-    const asp = msg.agentId ? this.agents.get(msg.agentId) : undefined
-    const b = this.blocks.get(channelId)
-    // 频道未放置且无对应用户 → 暂不渲染(队列保留,放置/用户出现后补显)
-    if (!asp && !b) return
-    const name = asp?.name ?? b?.name ?? '系统'
-    const accent = asp
-      ? asp.colorNum
-      : (b?.color ?? 0x41c8f4)
-    const text = (msg.kind === 'artifact' && !msg.text.startsWith('📦') ? `📦 ${msg.text}` : msg.text) || '…'
-    const sprite = this.makeChatBubble(text, name, accent, msg.kind)
-    const x = asp?.root.position.x ?? b!.x
-    const z = asp?.root.position.z ?? b!.z
-    // 放大气泡后锚点整体抬升(避免压到 48 处名牌)
-    sprite.position.set(x, asp ? BUBBLE_Y + 22 + Math.max(0, asp.model.scale.y - 1) * 22 : 64, z)
-    this.scene.add(sprite)
-    if (!asp) {
-      // 频道级(系统)气泡:展示期满自行移除
-      window.setTimeout(() => {
-        this.scene.remove(sprite)
-      }, bubbleDisplayMs(msg.text) + 500)
-      return
-    }
-    if (asp.bubble) {
-      this.scene.remove(asp.bubble)
-      this.disposeCanvasTextures(asp.bubble)
-      asp.bubbleText = null
-    }
-    asp.bubble = sprite
-    asp.bubbleText = text
-    this.popInSprite(sprite)
-    this.dirty = true
-  }
-
-  /** 2.5D 聊天气泡:工业 HMI 风格 —— 头部身份条(等宽名牌 + 类型印章)+ 多行正文 + 尾角 */
-  private makeChatBubble(text: string, name: string, accent: number, kind: TownBubbleKind): THREE.Sprite {
-    const accentHex = `#${accent.toString(16).padStart(6, '0')}`
-    const canvas = document.createElement('canvas')
-    const ctx = canvas.getContext('2d')!
-    // 超大字号会话气泡:正文 18px / 头名 13px / 最多 6 行 / 宽 ≤ 680px —— 实时信息一眼可读
-    const bodyFont = '18px Geist, "PingFang SC", sans-serif'
-    const headFont = '600 13px "Geist Mono", Geist, "PingFang SC", monospace'
-    const tagFont = '600 10px "Geist Mono", Geist, monospace'
-    const maxTextW = 470
-    const padX = 18
-    const padY = 12
-    const nameH = 26
-    const lineH = 24
-    const tailH = 13
-    ctx.font = bodyFont
-    const lines = this.wrapBubbleLines(ctx, text.replace(/\s+/g, ' ').trim() || '…', maxTextW, 6)
-    const textW = Math.max(...lines.map(l => ctx.measureText(l).width))
-    const bw = Math.min(680, Math.max(140, Math.ceil(textW) + padX * 2))
-    const bodyH = nameH + lines.length * lineH + padY * 2
-    const bh = bodyH + tailH
-    canvas.width = bw
-    canvas.height = bh
-    ctx.clearRect(0, 0, bw, bh)
-    // 方角矩形 + 底部中央尾角(指向说话人;HMI 直角配方)
-    const r = 4
-    const cx = bw / 2
-    const t = Math.min(24, bw * 0.32)
-    const path = () => {
-      ctx.beginPath()
-      ctx.moveTo(r, 0)
-      ctx.lineTo(bw - r, 0)
-      ctx.quadraticCurveTo(bw, 0, bw, r)
-      ctx.lineTo(bw, bodyH - r)
-      ctx.quadraticCurveTo(bw, bodyH, bw - r, bodyH)
-      ctx.lineTo(cx + t / 2, bodyH)
-      ctx.lineTo(cx, bodyH + tailH)
-      ctx.lineTo(cx - t / 2, bodyH)
-      ctx.lineTo(r, bodyH)
-      ctx.quadraticCurveTo(0, bodyH, 0, bodyH - r)
-      ctx.lineTo(0, r)
-      ctx.quadraticCurveTo(0, 0, r, 0)
-      ctx.closePath()
-    }
-    // 柔和投影 → 深色面板底
-    ctx.save()
-    ctx.shadowColor = 'rgba(0,0,0,0.55)'
-    ctx.shadowBlur = 14
-    ctx.shadowOffsetY = 4
-    path()
-    ctx.fillStyle = 'rgba(14,18,27,0.94)'
-    ctx.fill()
-    ctx.restore()
-    // 头部数据带(轻微抬升 + 发丝底边)
-    ctx.save()
-    path()
-    ctx.clip()
-    ctx.fillStyle = 'rgba(255,255,255,0.045)'
-    ctx.fillRect(0, 0, bw, padY + nameH)
-    ctx.restore()
-    ctx.globalAlpha = 0.28
-    ctx.fillStyle = '#fff'
-    ctx.fillRect(padX, padY + 18, bw - padX * 2, 1)
-    ctx.globalAlpha = 1
-    // 发丝描边 + 左缘身份色数据条
-    path()
-    ctx.lineWidth = 1.2
-    ctx.strokeStyle = 'rgba(140,170,195,0.4)'
-    ctx.stroke()
-    ctx.save()
-    path()
-    ctx.clip()
-    ctx.fillStyle = accentHex
-    ctx.fillRect(0, 0, 3, bodyH)
-    ctx.restore()
-    // 头牌:等宽名牌(身份色)+ 右侧类型印章(交付/异常)
-    ctx.font = headFont
-    ctx.fillStyle = accentHex
-    ctx.textBaseline = 'middle'
-    ctx.textAlign = 'left'
-    ctx.fillText(name, padX, padY + 10)
-    const tag = kind === 'artifact' ? 'ARTIFACT' : kind === 'error' ? 'FAULT' : ''
-    if (tag) {
-      const tw = ctx.measureText(tag).width + 12
-      ctx.font = tagFont
-      ctx.fillStyle = kind === 'error' ? '#ff8d80' : '#9fc3e8'
-      ctx.strokeStyle = kind === 'error' ? 'rgba(255,141,128,0.55)' : 'rgba(159,195,232,0.45)'
-      ctx.lineWidth = 1
-      const tx = bw - padX - tw
-      const ty = padY + 2
-      const th = 16
-      ctx.beginPath()
-      ctx.rect(tx, ty, tw, th)
-      ctx.fill()
-      ctx.stroke()
-      ctx.textAlign = 'center'
-      ctx.fillText(tag, tx + tw / 2, ty + th / 2 + 0.5)
-    }
-    // 正文(错误微红)
-    ctx.font = bodyFont
-    ctx.fillStyle = kind === 'error' ? '#ff9d9d' : '#eef2fb'
-    ctx.textAlign = 'left'
-    lines.forEach((l, i) => ctx.fillText(l, padX, padY + nameH + 10 + i * lineH))
-    // Sprite(纹理按 1/2.4 缩放到世界单位 —— 放大气泡后保持更大可见尺度)
-    const tex = new THREE.CanvasTexture(canvas)
-    tex.colorSpace = THREE.SRGBColorSpace
-    const sprite = new THREE.Sprite(new THREE.SpriteMaterial({ map: tex, transparent: true, depthTest: false, depthWrite: false }))
-    const k = 2.4
-    sprite.scale.set(bw / k, bh / k, 1)
-    return sprite
-  }
-
-  /** 气泡弹入动画:0.62 → 1.0 缓出(180ms,2.5D 手感) */
-  private popInSprite(sprite: THREE.Sprite): void {
-    const tx = sprite.scale.x
-    const ty = sprite.scale.y
-    sprite.scale.set(tx * 0.62, ty * 0.62, 1)
-    const start = performance.now()
-    const dur = 180
-    const step = () => {
-      if (this.disposed) return
-      const t = Math.min(1, (performance.now() - start) / dur)
-      const s = 0.62 + 0.38 * (1 - Math.pow(1 - t, 3))
-      sprite.scale.set(tx * s, ty * s, 1)
-      if (t < 1) this.rafAnims.push(step)
-    }
-    this.rafAnims.push(step)
-  }
-
-  /** 按宽度逐字符换行(兼容中英混排);超 maxLines 行末加省略号 */
-  private wrapBubbleLines(ctx: CanvasRenderingContext2D, text: string, maxW: number, maxLines: number): string[] {
-    const lines: string[] = []
-    let line = ''
-    for (const ch of text) {
-      if (ctx.measureText(line + ch).width > maxW && line) {
-        lines.push(line)
-        line = ch
-        if (lines.length >= maxLines) {
-          lines[maxLines - 1] = `${lines[maxLines - 1] ?? ''}…`
-          return lines
-        }
-      }
-      else {
-        line += ch
-      }
-    }
-    if (line) lines.push(line)
-    if (lines.length === 0) lines.push('…')
-    return lines
+  drainReceivers(now: number): void {
+    drainReceivers(this, now)
   }
 
   // ================================================================
@@ -2435,491 +536,87 @@ export class TownScene3D {
     return this.renderer.domElement
   }
 
+  // ==== 相机公开面(实现见 scene/town-scene3d-camera.ts;薄壳保持签名与语义不变) ====
+
   /** 世界坐标 → 屏幕像素(数据标注/悬浮 callout 投影;返回 null = 在相机背后) */
-  worldToScreen(x: number, y: number, z: number): { x: number, y: number } | null {
-    const rect = this.renderer.domElement.getBoundingClientRect()
-    // 相机背后的点 project() 会按负 w 翻转到错误的屏幕位置 → 先用前向点积剔除
-    const dir = TownScene3D._wDir
-    this.camera.getWorldDirection(dir)
-    const rel = TownScene3D._wRel.set(x - this.camera.position.x, y - this.camera.position.y, z - this.camera.position.z)
-    if (rel.dot(dir) <= 0.1) return null
-    const v = TownScene3D._wVec.set(x, y, z).project(this.camera)
-    if (v.z > 1) return null
-    // 视锥外过远(NDC ±1.6)的点投影无意义(可能落到数千 px 外)→ 剔除;边缘 ±1 内保留供夹取
-    if (Math.abs(v.x) > 1.6 || Math.abs(v.y) > 1.6) return null
-    return {
-      x: rect.left + (v.x + 1) / 2 * rect.width,
-      y: rect.top + (1 - v.y) / 2 * rect.height,
-    }
-  }
+  worldToScreen(x: number, y: number, z: number): { x: number, y: number } | null { return worldToScreen(this, x, y, z) }
 
   /** 页面坐标 → 世界 xz(经 canvas rect + 相机射线打在 y=0 平面) */
-  screenToWorld(clientX: number, clientY: number): { x: number, z: number } {
-    const rect = this.renderer.domElement.getBoundingClientRect()
-    const ndcX = ((clientX - rect.left) / rect.width) * 2 - 1
-    const ndcY = -((clientY - rect.top) / rect.height) * 2 + 1
-    const raycaster = TownScene3D._raycaster
-    raycaster.setFromCamera(TownScene3D._wVec2.set(ndcX, ndcY), this.camera)
-    const pt = TownScene3D._wVec
-    raycaster.ray.intersectPlane(TownScene3D._groundPlane, pt)
-    return pt ? { x: pt.x, z: pt.z } : { x: this.camera.position.x, z: this.camera.position.z }
-  }
+  screenToWorld(clientX: number, clientY: number): { x: number, z: number } { return screenToWorld(this, clientX, clientY) }
 
   /** 平移相机(拖拽):移动 camTarget(相机位置由 loop 据 target+dolly 推导) */
-  panBy(dxWorld: number, dzWorld: number): void {
-    this.camTarget.x -= dxWorld
-    this.camTarget.z -= dzWorld
-  }
-
-  /** 自动取景目标 dolly(缩放拖拽期间按范围尺寸计算;渲染循环平滑跟随,拖拽结束清除) */
-  private autoDolly: number | null = null
-
-  /** 范围半轴 → 容纳它的 dolly(基线几何:水平半幅 ≈ 613*aspect*d,地面纵深 ≈ 950*d) */
-  private fitDollyFor(rx: number, rz: number): number {
-    const aspect = this.camera.aspect || 1.6
-    return Math.max(rx / (0.82 * 613 * aspect), rz / (0.82 * 950))
-  }
-
-  /** 缩放过程中调用:范围超出当前视野 → 相机自动拉远(只放大不缩小,收敛于拖拽结束) */
-  private autoFrameTo(rx: number, rz: number): void {
-    const fit = this.fitDollyFor(rx, rz)
-    if (fit > this.dolly) this.autoDolly = Math.min(40, fit * 1.18)
-  }
-
-  /** 变换模式(Blender 规范):translate=移动 G / rotate=旋转 R / scale=缩放 S。
-   *  轴约束:移动仅 XZ(模型贴地),旋转仅 Y(2.5D 朝向),缩放 XYZ。 */
-  setTransformMode(mode: 'translate' | 'rotate' | 'scale'): void {
-    if (!this.tControls) return
-    this.tControls.setMode(mode)
-    this.tControls.showX = mode !== 'rotate'
-    this.tControls.showY = mode !== 'translate'
-    this.tControls.showZ = mode !== 'rotate'
-  }
+  panBy(dxWorld: number, dzWorld: number): void { panBy(this, dxWorld, dzWorld) }
 
-  /** 手柄是否悬停/拖拽中(调用方应让出相机平移与点选) */
-  isGizmoBusy(): boolean {
-    return !!this.tControls && (this.tControls.dragging || !!this.tControls.axis)
-  }
+  /** 缩放过程中调用:范围超出当前视野 → 相机自动拉远(只放大不缩小,收敛于拖拽结束)。宿主契约面:editing 模块回调。 */
+  autoFrameTo(rx: number, rz: number): void { autoFrameTo(this, rx, rz) }
 
-  /** 滚轮缩放(改变 dolly 距离) */
-  /** 视角预设(设计稿 angle-chip):std 标准 / top 俯视 / front 前视 / side 侧视。
-   *  轨道参数:yaw 方位 / pitch 仰角(rad) / radius 半径(再乘 dolly)。 */
-  setViewPreset(p: 'std' | 'top' | 'front' | 'side'): void {
-    const presets: Record<string, { yaw: number, pitch: number, radius: number }> = {
-      std: { yaw: 0, pitch: 0.70, radius: 1178 },
-      top: { yaw: 0, pitch: 1.51, radius: 2400 },
-      front: { yaw: 0, pitch: 0.09, radius: 1510 },
-      side: { yaw: Math.PI / 2, pitch: 0.33, radius: 1320 },
-    }
-    const t = presets[p] ?? presets.std!
-    this.viewTarget = { ...t }
-    // 预设切换走平滑趋近;环绕拖拽则是即时双写
-  }
+  /** 视角预设(设计稿 angle-chip):std 标准 / top 俯视 / front 前视 / side 侧视。 */
+  setViewPreset(p: 'std' | 'top' | 'front' | 'side'): void { setViewPreset(this, p) }
 
-  /** 左键环绕(设计稿 OrbitLite 语义):theta -= dx·0.0052(拖右=场景右转,内容跟手不反向);
-   *  phi -= dy·0.0052(拖上=压低视角看地平,拖下=抬升俯视),夹在仰角安全区间 */
-  /** 环绕(设计稿 OrbitLite 1:1):theta -= dx·0.0052;仰角 += dy·0.0052
-   *  (设计稿 phi -= dy·0.0052,phi 为极角 → 仰角随 dy 增大:往下拖 = 相机升向俯视) */
-  orbitBy(dxPx: number, dyPx: number): void {
-    const yaw = this.viewCur.yaw - dxPx * 0.0052
-    const pitch = Math.min(1.52, Math.max(0.06, this.viewCur.pitch + dyPx * 0.0052))
-    this.viewCur = { yaw, pitch, radius: this.viewCur.radius }
-    this.viewTarget = { ...this.viewCur }
-    this.dirty = true
-  }
+  /** 环绕(设计稿 OrbitLite 1:1):左键拖拽即时改 yaw/pitch,夹在仰角安全区间 */
+  orbitBy(dxPx: number, dyPx: number): void { orbitBy(this, dxPx, dyPx) }
 
   /** 自动环绕(设计稿 tOrbit):渲染循环缓转 yaw;orbitBy 拖拽时暂停 */
-  setAutoOrbit(on: boolean): void {
-    this.autoOrbit = on
-  }
+  setAutoOrbit(on: boolean): void { setAutoOrbit(this, on) }
 
-  getAutoOrbit(): boolean {
-    return this.autoOrbit
-  }
+  getAutoOrbit(): boolean { return getAutoOrbit(this) }
 
-  /** 滚轮缩放(改变 dolly 距离) */
-
-  /** 平移(设计稿 OrbitLite 1:1):target += (−right·dx + up·dy)·s。
-   *  right=(cosY,0,−sinY),up 地面分量 = −sinP·(sinY,cosY);panBy 内部取负 → 注视点
-   *  拖右时沿 −right 移动 = 相机左扫 = 内容跟随光标(抓取语义,与设计稿逐项一致)。 */
-  panByScreen(dxPx: number, dyPx: number): void {
-    const r = this.viewCur.radius * this.dolly
-    const k = r * 0.0011
-    const sinY = Math.sin(this.viewCur.yaw)
-    const cosY = Math.cos(this.viewCur.yaw)
-    const sinP = Math.sin(this.viewCur.pitch)
-    const dxw = (cosY * dxPx + sinP * sinY * dyPx) * k
-    const dzw = (-sinY * dxPx + sinP * cosY * dyPx) * k
-    this.panBy(dxw, dzw)
-  }
+  /** 平移(设计稿 OrbitLite 1:1):target += (−right·dx + up·dy)·s */
+  panByScreen(dxPx: number, dyPx: number): void { panByScreen(this, dxPx, dyPx) }
 
   /** 飞往预设视角(平滑;设计稿 flyTo) */
-  flyToPreset(p: 'std' | 'top' | 'front' | 'side', _dur = 900): void {
-    this.setViewPreset(p)
-  }
+  flyToPreset(p: 'std' | 'top' | 'front' | 'side', dur = 900): void { flyToPreset(this, p, dur) }
 
   /** 相机即时状态(导航地图/callout 距离显隐;世界坐标) */
-  getCameraPose(): { pos: { x: number, y: number, z: number }, target: { x: number, z: number }, yaw: number, dolly: number } {
-    return {
-      pos: { x: this.camera.position.x, y: this.camera.position.y, z: this.camera.position.z },
-      target: { x: this.camTarget.x, z: this.camTarget.z },
-      yaw: this.viewCur.yaw,
-      dolly: this.dolly,
-    }
-  }
+  getCameraPose(): { pos: { x: number, y: number, z: number }, target: { x: number, z: number }, yaw: number, dolly: number } { return getCameraPose(this) }
 
   /** 导航地图拖拽平移:世界位移直接作用于注视点与相机位置(设计稿 minimap drag) */
-  panWorldBy(dxw: number, dzw: number): void {
-    this.camTarget.x -= dxw
-    this.camTarget.z -= dzw
-    this.camera.position.x -= dxw
-    this.camera.position.z -= dzw
-    this.dirty = true
-  }
-
-  /** 渲染曝光(场景控制坞"环境光照";0.2~2.2) */
-  setExposure(v: number): void {
-    this.renderer.toneMappingExposure = Math.min(2.2, Math.max(0.2, v))
-  }
-
-  /** 领地染色浓度(平台透明度系数;0.05~1) */
-  setTerritoryOpacity(v: number): void {
-    const o = Math.min(1, Math.max(0.05, v))
-    for (const b of this.blocks.values()) {
-      ;(b.platform.material as THREE.MeshStandardMaterial).opacity = 0.24 * o
-    }
-    this.dirty = true
-  }
+  panWorldBy(dxw: number, dzw: number): void { panWorldBy(this, dxw, dzw) }
 
   /** 重置视角(注视世界中心,标准轨道,基准 dolly) */
-  resetView(): void {
-    this.dolly = 1
-    this.autoDolly = null
-    this.tweenCamTo(WORLD_CX, WORLD_CZ)
-    this.setViewPreset('std')
-  }
+  resetView(): void { resetView(this) }
 
-  zoomBy(f: number): void {
-    this.autoDolly = null
-    this.dolly = Math.min(1000, Math.max(0.001, this.dolly + f))
-  }
+  zoomBy(f: number): void { zoomBy(this, f) }
 
   /** 缓动聚焦某世界点(移动 camTarget) */
-  /** 缓动聚焦某世界点(移动 camTarget) */
-  focusTo(x: number, z: number): void {
-    this.tweenCamTo(x, z)
-  }
-
-  private tweenCamTo(x: number, z: number): void {
-    const start = performance.now()
-    const sx = this.camTarget.x
-    const sz = this.camTarget.z
-    const dur = 600
-    const step = () => {
-      const t = Math.min(1, (performance.now() - start) / dur)
-      const e = 1 - Math.pow(1 - t, 3)
-      this.camTarget.x = sx + (x - sx) * e
-      this.camTarget.z = sz + (z - sz) * e
-      if (t < 1) this.rafAnims.push(step)
-    }
-    this.rafAnims.push(step)
-  }
+  focusTo(x: number, z: number): void { focusTo(this, x, z) }
 
-  // ================================================================
-  // 拖拽换装 / 生成居民(drop 入口)
-  // ================================================================
+  /** 登记逐帧回调(渲染循环统一 flush;抽出模块经此驱动缓动/脉冲) */
+  pushAnim(f: () => void): void { this.rafAnims.push(f) }
 
-  dropModelOnWorld(x: number, z: number, assetId: string): { mode: 'rebind' | 'spawn', agentId?: string, textureKey: string, x: number, y: number } {
-    const near = this.nearestAgent(x, z, 80)
-    const model = this.modelsById.get(assetId)
-    const texKey = model?.id ?? assetId
-    // 数字孪生实体模型(kind=dev):拖入场景生成"设备节点" + 绑定 device twin
-    if (model?.kind === 'dev') {
-      const twinId = this.spawnDeviceNode(x, z, texKey, model.file, model.name)
-      return { mode: 'spawn', agentId: twinId, textureKey: texKey, x: Math.round(x), y: Math.round(z) }
-    }
-    if (near) {
-      this.swapTexture(near, texKey)
-      this.enqueueBubble(near.channelId, near.agentId, 'info', `换装 → ${model?.name ?? assetId}`, 2200)
-      return { mode: 'rebind', agentId: near.agentId, textureKey: texKey, x: Math.round(near.root.position.x), y: Math.round(near.root.position.z) }
-    }
-    // 落点生成居民
-    const info = model ?? { id: assetId, file: '', name: assetId }
-    this.spawnResident(x, z, texKey, info.name)
-    return { mode: 'spawn', textureKey: texKey, x: Math.round(x), y: Math.round(z) }
-  }
-
-  private nearestAgent(x: number, z: number, maxDist: number): Agent3D | undefined {
-    let best: Agent3D | undefined
-    let bestD = maxDist
-    for (const a of this.agents.values()) {
-      const d = Math.hypot(a.root.position.x - x, a.root.position.z - z)
-      if (d < bestD) {
-        best = a
-        bestD = d
-      }
-    }
-    return best
-  }
+  /** 自动取景目标 dolly(缩放拖拽期间按范围尺寸计算;渲染循环平滑跟随,拖拽结束清除) */
+  autoDolly: number | null = null
+  /** 变换模式(Blender 规范):translate=移动 G / rotate=旋转 R / scale=缩放 S。
+   *  轴约束:移动仅 XZ(模型贴地),旋转仅 Y(2.5D 朝向),缩放 XYZ。 */
+  setTransformMode(mode: 'translate' | 'rotate' | 'scale'): void { setTransformMode(this, mode) }
 
-  private swapTexture(asp: Agent3D, texKey: string): void {
-    const info = this.modelsById.get(texKey)
-    const file = info?.file ?? this.resolveFile(texKey) ?? '/assets/game/character/hero-3d.glb'
-    asp.modelRef = texKey
-    asp.textureKey = texKey
-    void this.mountModel(asp, file, info?.name ?? texKey)
-  }
+  /** 手柄是否悬停/拖拽中(调用方应让出相机平移与点选) */
+  isGizmoBusy(): boolean { return isGizmoBusy(this) }
 
-  private spawnResident(x: number, z: number, texKey: string, name: string): void {
-    const root = new THREE.Group()
-    root.position.set(x, GROUND_Y, z)
-    const model = new THREE.Group()
-    root.add(model)
-    const nameSprite = this.makeLabel(name, x, 48, z, this.hexOf(0xffe9c4))
-    this.scene.add(root)
-    const resident = new Agent3D({
-      channelId: '', agentId: `resident-${Date.now().toString(36)}`, name,
-      role: 'worker', root, model, mixer: null, clips: [], colorNum: 0xffe9c4, nameSprite,
-      bubble: null, bubbleText: null, bubbleTimer: null, state: 'idle', progress: null,
-      dragging: false, homeX: x, homeZ: z, range: null, rangeLine: null, textureKey: texKey, modelRef: texKey,
-      behavior: { mode: 'idle', roamTarget: null, targetId: null, waitUntil: 0, pauseUntil: 0, engaged: false },
-    })
-    resident.host = this
-    resident.attachAura(0xffe9c4, 'worker')
-    this.agents.set(resident.agentId, resident)
-    const info = this.modelsById.get(texKey)
-    void this.mountModel(resident, info?.file ?? '/assets/game/character/hero-3d.glb', info?.name ?? name)
-  }
+  /** 渲染曝光(场景控制坞"环境光照";0.2~2.2) */
+  setExposure(v: number): void { setExposure(this, v) }
 
-  /** 设备状态环 + 运行态动效弧(局部坐标一次定位随 root 移动 —— 修复曾被每帧写成世界坐标导致环 2× 漂移的缺陷)。
-   *  颜色/显隐由 DeviceNode.updateRing 数据驱动,渲染循环只负责弧的缓转。 */
-  private makeDeviceRing(): { ring: THREE.Mesh, arc: THREE.Mesh } {
-    const ring = new THREE.Mesh(
-      new THREE.RingGeometry(20, 26, 32),
-      new THREE.MeshBasicMaterial({ color: 0xf6c453, transparent: true, opacity: 0.8, side: THREE.DoubleSide }),
-    )
-    ring.rotation.x = -Math.PI / 2
-    ring.position.y = 0.3
-    const arc = new THREE.Mesh(
-      new THREE.RingGeometry(20, 26, 32, 1, 0, Math.PI * 1.5),
-      new THREE.MeshBasicMaterial({ color: 0x35e0a0, transparent: true, opacity: 0.55, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending }),
-    )
-    arc.rotation.x = -Math.PI / 2
-    arc.position.y = 0.34
-    arc.visible = false
-    return { ring, arc }
-  }
+  /** 领地染色浓度(平台透明度系数;0.05~1) */
+  setTerritoryOpacity(v: number): void { setTerritoryOpacity(this, v) }
 
-  /**
-   * 数字孪生设备节点:拖 dev 模型进场景生成。
-   * - 3D:挂 device GLB + 设备名牌 + 状态环(telemetry 驱动颜色);
-   * - 数据:经 devices.create 落一个 device twin,与 modelRef 绑定;
-   * - state 驱动:alarm→红环,running→青环,offline→灰环,idle→亮环。
-   */
-  private spawnDeviceNode(x: number, z: number, texKey: string, file: string, name: string): string {
-    const tempId = `dev-${Date.now().toString(36)}`
-    const root = new THREE.Group()
-    root.position.set(x, GROUND_Y, z)
-    const { ring, arc } = this.makeDeviceRing()
-    root.add(ring, arc)
-    const holder = new THREE.Group()
-    root.add(holder)
-    holder.userData.modelFile = file
-    const label = this.makeLabel(`⚙ ${name}`, x, 60, z)
-    this.scene.add(root)
-    const twin = new DeviceNode({ twinId: tempId, name, modelRef: texKey, root, holder, ring, label, state: 'idle', telemetry: {} })
-    twin.host = this
-    twin.arc = arc
-    twin.updateRing()
-    this.deviceNodes.set(tempId, twin)
-    this.registerScalable('device', tempId, holder)
-    void this.loadGltfToGroup(file, holder, UNITS * 1.6)
-    const st = this.scalables.get(`device:${tempId}`)
-    const createPromise = this.devices?.create({
-      name, modelRef: texKey, kind: 'device', controls: ['power_on', 'power_off', 'set_speed'],
-      posX: Math.round(x * 10) / 10,
-      posZ: Math.round(z * 10) / 10,
-      scale: st ? Math.round(st.userScale * 100) / 100 : 1,
-    })
-    if (!createPromise) return tempId
-    this.pendingDeviceCreates.set(tempId, { name, modelRef: texKey, posX: x, posZ: z })
-    void createPromise
-      .then((created) => {
-        const cancelled = this.cancelledDeviceCreates.delete(tempId)
-        this.pendingDeviceCreates.delete(tempId)
-        if (cancelled) {
-          void this.devices?.remove?.(created.id).catch(() => {})
-          return
-        }
-        if (this.disposed) return
-        this.adoptDeviceNode(tempId, created.id)
-      })
-      .catch(() => {
-        this.cancelledDeviceCreates.delete(tempId)
-        this.pendingDeviceCreates.delete(tempId)
-      })
-    return tempId
-  }
+  // ================================================================
+  // 拖拽换装 / 生成居民(drop 入口;实现见 scene/town-scene3d-agents.ts)
+  // ================================================================
 
-  /** 将本地临时设备原子迁移到服务端 ID，避免后续更新/删除命中旧键。 */
-  private adoptDeviceNode(tempId: string, realId: string): void {
-    this.pendingDeviceCreates.delete(tempId)
-    const node = this.deviceNodes.get(tempId)
-    if (!node) return
-    const duplicate = this.deviceNodes.get(realId)
-    if (duplicate && duplicate !== node) {
-      this.removeDeviceNode(tempId)
-      if (this.selected?.kind === 'device' && this.selected.id === tempId) this.setSelected({ kind: 'device', id: realId })
-      return
-    }
-    this.deviceNodes.delete(tempId)
-    node.twinId = realId
-    this.deviceNodes.set(realId, node)
-    const scalable = this.scalables.get(`device:${tempId}`)
-    this.scalables.delete(`device:${tempId}`)
-    if (scalable) {
-      scalable.id = realId
-      this.scalables.set(`device:${realId}`, scalable)
-    }
-    const timer = this.pendingSaveTimers.get(tempId)
-    this.pendingSaveTimers.delete(tempId)
-    if (timer) this.pendingSaveTimers.set(realId, timer)
-    if (this.pointerDrag?.kind === 'device' && this.pointerDrag.id === tempId) this.pointerDrag.id = realId
-    if (this.selected?.kind === 'device' && this.selected.id === tempId) this.setSelected({ kind: 'device', id: realId })
-    this.persistDeviceTransform(realId)
+  dropModelOnWorld(x: number, z: number, assetId: string): { mode: 'rebind' | 'spawn', agentId?: string, textureKey: string, x: number, y: number } {
+    return dropModelOnWorld(this, x, z, assetId)
   }
 
-  /** 将 GLB 加载进 Group(按高度归一化 scale) */
-  private async loadGltfToGroup(file: string, group: THREE.Group, targetH: number): Promise<void> {
-    try {
-      const gltf = await this.loadGltf(file)
-      const box = new THREE.Box3().setFromObject(gltf.scene)
-      const h = Math.max(0.5, box.max.y - box.min.y)
-      const scale = targetH / h
-      gltf.scene.scale.setScalar(scale)
-      gltf.scene.position.y = 0
-      // 真实投影 + PBR 材质增强(设备:金属机身材质反射拉满,像真实工业设备)
-      gltf.scene.traverse((o) => {
-        if ((o as THREE.Mesh).isMesh) o.castShadow = true
-      })
-      this.enhancePbrMaterials(gltf.scene, 'device')
-      // 静态子树矩阵冻结:设备模型加载后局部变换恒定,子孙 matrixAutoUpdate=false +
-      // 一次性 updateMatrix,免每帧全树 updateMatrix 合成(拖拽/缩放只改祖先链,
-      // world 矩阵经 force 传播仍正确;设备无动画,mixer 仅角色路径使用)
-      gltf.scene.traverse((o) => {
-        if (o === gltf.scene) return
-        o.matrixAutoUpdate = false
-        o.updateMatrix()
-      })
-      group.add(gltf.scene)
-    }
-    catch {
-      // 加载失败:空 Group,静默(节点仍存在,只是无网格)
-    }
+  /** 数字孪生设备节点:拖 dev 模型进场景生成(实现见 scene/town-scene3d-devices.ts) */
+  spawnDeviceNode(x: number, z: number, texKey: string, file: string, name: string): string {
+    return spawnDeviceNode(this, x, z, texKey, file, name)
   }
 
-  /**
-   * 模型 PBR 材质增强(放入场景后的渲染优化;设备/角色分治)。
-   * 根因修复:角色与产线设备 GLB 大量使用 KHR_materials_unlit(three 加载为
-   * MeshBasicMaterial),不受灯光/阴影约束,夜景里像自发光贴片 —— 这既是
-   * 「角色过亮」也是设备「假金属光泽」的来源。统一就地转标准材质接入光照
-   * 体系,再分级调参:
-   * - 角色:哑光 + 极轻环境反射(无清漆/自发光,保持原作贴图观感);
-   * - 设备:LED 指示灯保持无光照语义并提 HDR(bloom 起晕,幂等防重);
-   *   透光件微自发光 / 金属件适度镜面(0.85,克制)/ 烤漆件轻清漆。
-   */
-  private enhancePbrMaterials(root: THREE.Object3D, kind: 'device' | 'character'): void {
-    root.traverse((o) => {
-      const mesh = o as THREE.Mesh
-      if (!mesh.isMesh) return
-      mesh.receiveShadow = true
-      const tune = (raw: THREE.Material): THREE.Material => {
-        const b = raw as THREE.MeshBasicMaterial & { isMeshBasicMaterial?: boolean }
-        let m: THREE.MeshStandardMaterial
-        if (b?.isMeshBasicMaterial) {
-          if (kind === 'device' && /led|lamp|light/i.test(b.name ?? '')) {
-            // 设备指示灯:保持无光照语义;提为 HDR(bloom 起晕)。clone 共享同一材质,
-            // userData 幂等护桥避免多实例挂载时倍率叠乘。
-            const flag = (b.userData ?? (b.userData = {})) as { hdrBoost?: boolean }
-            if (!flag.hdrBoost) {
-              b.color.multiplyScalar(4.5)
-              flag.hdrBoost = true
-            }
-            return b
-          }
-          m = new THREE.MeshStandardMaterial({
-            map: b.map ?? null,
-            // unlit 贴图按"全亮"绘制,直接接入 ~8 倍总光的灯光系会过曝成白炽;
-            // 反照率按类型压暗:角色 0.4 / 设备 0.55(ACES 肩部回落到合理亮度)
-            color: b.color.clone().multiplyScalar(kind === 'character' ? 0.38 : 0.5),
-            transparent: b.transparent,
-            opacity: b.opacity,
-            alphaTest: b.alphaTest,
-            side: b.side,
-            roughness: kind === 'character' ? 0.92 : 0.6,
-            metalness: kind === 'character' ? 0 : 0.25,
-          })
-          m.name = b.name ?? ''
-          b.dispose()
-        }
-        else {
-          const s = raw as THREE.MeshStandardMaterial
-          if (!s || !('envMapIntensity' in s)) return raw
-          m = s
-        }
-        if (kind === 'character') {
-          // 角色:哑光 + 极轻环境反射(曾因 emissive 底光 + 清漆层整体过亮)
-          m.envMapIntensity = 0.45
-          if (m.metalness > 0.3) m.metalness = 0
-          return m
-        }
-        // 设备分级
-        if (m.transparent) {
-          // 灯罩/屏幕/指示窗:轻微自发光,像通电的设备部件
-          m.envMapIntensity = 0.42
-          if (m.emissive) m.emissive.setScalar(Math.max(m.emissive.r, 0.06))
-          return m
-        }
-        if (m.metalness >= 0.5) {
-          m.envMapIntensity = 0.85 // 金属机身:适可而止的镜面(1.35 曾过亮)
-          return m
-        }
-        // 涂装/塑料外壳 → 物理材质轻清漆层(已是物理材质只调参,避免 clone 共享材质重复替换)
-        if ((m as unknown as { isMeshPhysicalMaterial?: boolean }).isMeshPhysicalMaterial) {
-          const p = m as THREE.MeshPhysicalMaterial
-          p.clearcoat = 0.35
-          p.clearcoatRoughness = 0.4
-          p.envMapIntensity = 0.7
-          p.needsUpdate = true
-          return p
-        }
-        const p = new THREE.MeshPhysicalMaterial({
-          color: m.color,
-          map: m.map,
-          normalMap: m.normalMap,
-          roughnessMap: m.roughnessMap,
-          aoMap: m.aoMap,
-          emissive: m.emissive,
-          emissiveMap: m.emissiveMap,
-          emissiveIntensity: m.emissiveIntensity,
-          roughness: Math.min(m.roughness, 0.55),
-          metalness: m.metalness,
-          clearcoat: 0.35,
-          clearcoatRoughness: 0.4,
-        })
-        p.name = m.name
-        p.side = m.side
-        m.dispose()
-        return p
-      }
-      if (Array.isArray(mesh.material)) mesh.material = mesh.material.map(tune)
-      else mesh.material = tune(mesh.material)
-    })
-    this.dirty = true
-  }
+  /** 模型 PBR 材质增强(设备/角色分治;实现见 scene/town-scene3d-models.ts) */
+  enhancePbrMaterials(root: THREE.Object3D, kind: 'device' | 'character'): void { enhancePbrMaterials(this, root, kind) }
 
   // ================================================================
-  // 调试 / HUD 数据
+  // 调试 / HUD 数据(实现见 scene/town-scene3d-hud.ts)
   // ================================================================
 
   getDebugState(): {
@@ -2928,39 +625,7 @@ export class TownScene3D {
     bubbles: Array<{ text: string, at: number }>
     activity: { channelId: string, agentName: string, text: string } | null
     player: { x: number, y: number }
-  } {
-    return {
-      blocks: this.blocks.size,
-      agents: [...this.agents.values()].map(a => ({
-        agentId: a.agentId,
-        name: a.name,
-        role: a.role,
-        channelId: a.channelId,
-        state: a.state,
-        progress: a.progress,
-        x: Math.round(a.root.position.x),
-        y: Math.round(a.root.position.z),
-        visible: true,
-        draggable: true,
-        auraColor: a.colorNum,
-        behavior: a.behavior.mode,
-        targetId: a.behavior.targetId,
-        homeX: Math.round(a.homeX),
-        homeY: Math.round(a.homeZ),
-        textureKey: a.textureKey,
-        modelRef: a.modelRef,
-        decorated: !a.channelId,
-        range: a.range
-          ? { x: Math.round(a.range.x), z: Math.round(a.range.z), radiusX: Math.round(a.range.radiusX), radiusZ: Math.round(a.range.radiusZ), shape: a.range.shape }
-          : null,
-        bubbleText: a.bubbleText,
-        anim: a.animState,
-      })),
-      bubbles: this.dbgBubbles.slice(-8),
-      activity: this.lastActivity,
-      player: { x: Math.round(this.camera.position.x), y: Math.round(this.camera.position.z) },
-    }
-  }
+  } { return getDebugState(this) }
 
   getMinimapState(): {
     world: { w: number, h: number }
@@ -2968,711 +633,146 @@ export class TownScene3D {
     agents: Array<{ x: number, y: number, color: number, busy: boolean }>
     devices: Array<{ x: number, y: number, color: number, state: string }>
     player: { x: number, y: number }
-  } {
-    const stateColor = (state: 'idle' | 'running' | 'offline' | 'alarm'): number =>
-      state === 'alarm' ? 0xff6b6b : state === 'offline' ? 0x8496a5 : state === 'running' ? 0x35e0a0 : 0xf6c453
-    return {
-      world: { w: WORLD_W, h: WORLD_H },
-      // 领地含真实形状/半轴/朝向(归一化;镜头居中小地图按形状绘制)
-      blocks: [...this.blocks.values()].map(b => ({
-        x: b.x / WORLD_W,
-        y: b.z / WORLD_H,
-        color: b.color,
-        name: b.name,
-        shape: b.shape,
-        rx: b.radiusX / WORLD_W,
-        rz: b.radiusZ / WORLD_H,
-        rot: b.rotationY,
-      })),
-      agents: [...this.agents.values()].map(a => ({ x: a.root.position.x / WORLD_W, y: a.root.position.z / WORLD_H, color: a.colorNum, busy: a.state === 'busy' })),
-      devices: [...this.deviceNodes.values()].map(d => ({
-        twinId: d.twinId,
-        x: d.root.position.x / WORLD_W,
-        y: d.root.position.z / WORLD_H,
-        color: stateColor(d.state),
-        state: d.state,
-        daq: d.modelRef.startsWith('daq-') || d.modelRef.includes('daq'),
-        bound: false,
-      })),
-      // 镜头 = camTarget(画面注视中心;小地图准星锚点)
-      player: { x: this.camTarget.x / WORLD_W, y: this.camTarget.z / WORLD_H },
-    }
-  }
+  } { return getMinimapState(this) }
 
-  getRecentActivity(): Array<{ channelId: string, agentName: string, text: string }> {
-    return [...this.recentActivity]
-  }
+  getRecentActivity(): Array<{ channelId: string, agentName: string, text: string }> { return getRecentActivity(this) }
 
-  /** 更新设备节点状态/遥测(由 useDeviceTwins 轮询或控制反馈驱动;数据驱动渲染状态环) */
+  /** 更新设备节点状态/遥测(数据驱动渲染状态环;实现见 scene/town-scene3d-devices.ts) */
   updateDeviceNode(twinId: string, state: DeviceNode['state'], telemetry?: Record<string, number | string | boolean>): void {
-    const dev = this.deviceNodes.get(twinId)
-    if (!dev) return
-    if (state) {
-      dev.state = state
-      dev.updateRing()
-    }
-    if (telemetry) dev.telemetry = { ...dev.telemetry, ...telemetry }
-    this.dirty = true
+    updateDeviceNode(this, twinId, state, telemetry)
   }
 
   /** 设备改名(重建名牌 Sprite + 落库由 TownView 走 devices.update) */
-  renameDevice(id: string, name: string): void {
-    const dev = this.deviceNodes.get(id)
-    if (!dev || !name.trim() || name.trim() === dev.name) return
-    this.renameDeviceSprite(dev, name)
-  }
+  renameDevice(id: string, name: string): void { renameDevice(this, id, name) }
 
   /** 设备换模型(按 modelRef 重挂 GLB 到 holder;持久化由 TownView 走 devices.update) */
-  swapDeviceModel(id: string, modelRef: string): void {
-    const dev = this.deviceNodes.get(id)
-    if (!dev) return
-    this.swapDeviceModelSprite(dev, modelRef)
-  }
+  swapDeviceModel(id: string, modelRef: string): void { swapDeviceModel(this, id, modelRef) }
 
   /** 设备当前名称(供属性面板初始化) */
-  getDeviceName(id: string): string {
-    return this.deviceNodes.get(id)?.name ?? ''
-  }
+  getDeviceName(id: string): string { return getDeviceName(this, id) }
 
   /** 设备当前绑定模型 id(供模型下拉高亮) */
-  getDeviceModelRef(id: string): string {
-    return this.deviceNodes.get(id)?.modelRef ?? ''
-  }
+  getDeviceModelRef(id: string): string { return getDeviceModelRef(this, id) }
 
   /** 删除设备实例:落库删除 + 移除场景节点(由 TownView 触发;失败仅移除本地节点)。 */
-  async removeDevice(id: string): Promise<void> {
-    const dev = this.deviceNodes.get(id)
-    if (!dev) return
-    if (this.pendingDeviceCreates.has(id)) {
-      this.cancelledDeviceCreates.add(id)
-      this.removeDeviceNode(id)
-      return
-    }
-    try {
-      await this.devices?.remove?.(id)
-    }
-    catch { /* 服务端失败仍移除本地节点(尽力同步) */ }
-    this.removeDeviceNode(id)
-  }
+  async removeDevice(id: string): Promise<void> { await removeDevice(this, id) }
 
   /** 设备节点列表(供 HUD/E2E;topY = 模型顶面世界高度,callout 锚定用) */
   getDeviceNodes(): Array<{ twinId: string, name: string, x: number, z: number, topY: number, state: string, telemetry: Record<string, number | string | boolean> }> {
-    return [...this.deviceNodes.values()].map(d => ({
-      twinId: d.twinId,
-      name: d.name,
-      x: Math.round(d.root.position.x),
-      z: Math.round(d.root.position.z),
-      topY: Math.round(this.deviceTopY(d)),
-      state: d.state,
-      telemetry: d.telemetry,
-    }))
+    return getDeviceNodes(this)
   }
 
   /** 动作绑定:为某 Agent 指定动画 clip(按名称 idle/walk/work 或索引)。供 AssetLibrary 选择动作后调用。 */
-  setAnimPref(agentId: string, clipName: string): void {
-    const asp = this.agents.get(agentId)
-    if (!asp || asp.clips.length === 0 || !asp.mixer) return
-    // 解析:优先名称匹配,否则 idle→0/walk→1/work→末帧
-    let idx = asp.clips.findIndex(c => c.name.toLowerCase().includes(clipName.toLowerCase()))
-    if (idx < 0) idx = clipName === 'work' ? asp.clips.length - 1 : clipName === 'walk' ? Math.min(1, asp.clips.length - 1) : 0
-    const clip = asp.clips[idx]
-    if (!clip) return
-    asp.mixer.stopAllAction()
-    asp.mixer.clipAction(clip).reset().play()
-  }
+  setAnimPref(agentId: string, clipName: string): void { setAnimPref(this, agentId, clipName) }
 
   /** 角色当前绑定模型 id(供模型选择器高亮) */
-  getAgentModel(agentId: string): string | null {
-    const asp = this.agents.get(agentId)
-    return asp?.modelRef ?? null
-  }
+  getAgentModel(agentId: string): string | null { return getAgentModel(this, agentId) }
 
   /** 角色名字(供模型选择器标题) */
-  getAgentName(agentId: string): string {
-    return this.agents.get(agentId)?.name ?? agentId.slice(0, 8)
-  }
+  getAgentName(agentId: string): string { return getAgentName(this, agentId) }
 
   /** 角色动画 clip 名列表(供 UI 展示可绑定动作;无则空) */
-  getAgentClips(agentId: string): Array<{ name: string, duration: number }> {
-    const asp = this.agents.get(agentId)
-    if (!asp) return []
-    return asp.clips.map(c => ({ name: c.name, duration: Math.round(c.duration * 10) / 10 }))
-  }
+  getAgentClips(agentId: string): Array<{ name: string, duration: number }> { return getAgentClips(this, agentId) }
 
   // ================================================================
   // 选中 + 缩放(客制化:场景内点选 Agent/设备 → 弹滑杆调大小)
   // ================================================================
 
   /** 以世界坐标 hit 一个 Agent 或设备节点(近似距离阈值;供点击选中) */
-  private pickAt(x: number, z: number): { kind: 'agent' | 'device', id: string } | null {
-    let best: { kind: 'agent' | 'device', id: string, d: number } | null = null
-    for (const a of this.agents.values()) {
-      const d = Math.hypot(a.root.position.x - x, a.root.position.z - z)
-      if (d < 90 && (!best || d < best.d)) best = { kind: 'agent', id: a.agentId, d }
-    }
-    for (const dev of this.deviceNodes.values()) {
-      const d = Math.hypot(dev.root.position.x - x, dev.root.position.z - z)
-      if (d < 90 && (!best || d < best.d)) best = { kind: 'device', id: dev.twinId, d }
-    }
-    return best ? { kind: best.kind, id: best.id } : null
-  }
+  pickAt(x: number, z: number): { kind: 'agent' | 'device', id: string } | null { return pickAt(this, x, z) }
 
   /** 点选频道:返回包含该点的频道 id(边界内;供编辑模式打开边界编辑面板) */
-  private pickChannel(x: number, z: number): string | null {
-    for (const b of this.blocks.values()) {
-      const layout: ChannelLayout = {
-        channelId: b.channelId, x: b.x, z: b.z,
-        radiusX: b.radiusX, radiusZ: b.radiusZ,
-        shape: b.shape, rotationY: b.rotationY,
-      }
-      if (pointInBoundary(layout, x, z)) return b.channelId
-    }
-    return null
-  }
+  pickChannel(x: number, z: number): string | null { return pickChannel(this, x, z) }
 
-  /** 命中频道边界线(世界点落在某领地边界带 ±42 单位内 → 边界拖拽等比缩放)。 */
-  private pickChannelEdge(x: number, z: number): { cid: string, rx0: number, rz0: number, rd0: number } | null {
-    for (const b of this.blocks.values()) {
-      const lxz = toLocal(b, x, z)
-      const rd = Math.hypot(lxz.x / b.radiusX, lxz.z / b.radiusZ)
-      const tol = 42 / Math.min(b.radiusX, b.radiusZ)
-      if (Math.abs(rd - 1) <= tol) {
-        return { cid: b.channelId, rx0: b.radiusX, rz0: b.radiusZ, rd0: rd }
-      }
-    }
-    return null
-  }
+  /** 命中频道边界线(世界点落在某领地边界带 ±42 单位内 → 边界拖拽等比缩放)。宿主契约面:editing 模块回调。 */
+  pickChannelEdge(x: number, z: number): { cid: string, rx0: number, rz0: number, rd0: number } | null { return pickChannelEdge(this, x, z) }
 
   /** 设置选中(点击后由 Vue 弹缩放/旋转滑杆) */
-  private setSelected(sel: { kind: 'agent' | 'device', id: string } | null): void {
-    // 选中切换/取消 → 退出框选绘制(清理预览)
-    if (!sel || sel.kind !== 'agent' || sel.id !== this.rangeDrawAgent) this.cancelRangeDraw()
-    this.selected = sel
-    // 变换手柄跟随选中设备(Blender 规范:选中即出手柄;运行模式只读 → 不出手柄)
-    if (this.tControls) {
-      if (sel?.kind === 'device' && this.mode === 'edit' && this.deviceNodes.has(sel.id)) this.tControls.attach(this.deviceNodes.get(sel.id)!.root)
-      else this.tControls.detach()
-    }
-    this.refreshAgentRangeLines()
-    this.refreshAgentRangeHandles()
-    if (!sel) {
-      this.emit('select', null)
-      return
-    }
-    const st = this.scalables.get(`${sel.kind}:${sel.id}`)
-    if (st) {
-      this.emit('select', {
-        kind: sel.kind,
-        id: sel.id,
-        scale: st.userScale,
-        rotation: Math.round(this.getModelRotation(sel.id, sel.kind) * 10) / 10,
-      })
-    }
-  }
+  setSelected(sel: { kind: 'agent' | 'device', id: string } | null): void { setSelected(this, sel) }
 
   /** 场景内缩放:为 Agent(id)或设备(id)设定用户缩放倍率(0.2~5;1=默认归一化) */
-  setModelScale(id: string, scale: number, kind?: 'agent' | 'device'): void {
-    const k = kind ?? (this.scalables.has(`device:${id}`) ? 'device' : 'agent')
-    const key = `${k}:${id}`
-    const st = this.scalables.get(key)
-    if (!st) return
-    st.userScale = scale
-    // 施加于模型 holder(相对已归一化的默认尺寸)
-    st.holder.scale.setScalar(st.userScale)
-    if (k === 'device') {
-      const dev = this.deviceNodes.get(id)
-      if (dev) dev.topYCache = null
-    }
-    this.dirty = true
-  }
+  setModelScale(id: string, scale: number, kind?: 'agent' | 'device'): void { setModelScale(this, id, scale, kind) }
 
   /** 当前选中对象(供 Vue/滑杆初始化) */
-  getSelectedScale(): { kind: 'agent' | 'device', id: string, scale: number, rotation: number } | null {
-    if (!this.selected) return null
-    const st = this.scalables.get(`${this.selected.kind}:${this.selected.id}`)
-    if (!st) return null
-    return {
-      kind: this.selected.kind,
-      id: this.selected.id,
-      scale: st.userScale,
-      rotation: Math.round(this.getModelRotation(this.selected.id, this.selected.kind) * 10) / 10,
-    }
-  }
+  getSelectedScale(): { kind: 'agent' | 'device', id: string, scale: number, rotation: number } | null { return getSelectedScale(this) }
 
   /** 组装可缩放目标并恢复初始化缩放(initialScale 优先=服务端持久化;否则 localStorage) */
-  private registerScalable(kind: 'agent' | 'device', id: string, holder: THREE.Group, initialScale?: number): void {
-    const saved = initialScale !== undefined
-      ? initialScale
-      : (typeof localStorage !== 'undefined' ? Number(localStorage.getItem(`town.scale.${kind}:${id}`) ?? 1) : 1)
-    const userScale = Number.isFinite(saved) && saved > 0 ? saved : 1
-    this.scalables.set(`${kind}:${id}`, { kind, id, userScale, holder })
-    holder.scale.setScalar(userScale)
-    if (kind === 'device') {
-      const dev = this.deviceNodes.get(id)
-      if (dev) dev.topYCache = null
-    }
-  }
+  registerScalable(kind: 'agent' | 'device', id: string, holder: THREE.Group, initialScale?: number): void { registerScalable(this, kind, id, holder, initialScale) }
 
   /** 持久化指定对象的缩放(滑杆松手时调用;设备同时落库,角色仅本地) */
-  persistScale(kind: 'agent' | 'device', id: string): void {
-    const st = this.scalables.get(`${kind}:${id}`)
-    if (!st || typeof localStorage === 'undefined') return
-    localStorage.setItem(`town.scale.${kind}:${id}`, String(st.userScale))
-    if (kind === 'device') this.persistDeviceTransform(id)
-  }
+  persistScale(kind: 'agent' | 'device', id: string): void { persistScale(this, kind, id) }
 
   // ================================================================
   // 编辑/浏览模式 + 场景对象拖拽(设备↔地面,角色↔落点)
+  // 实现见 scene/town-scene3d-editing.ts
   // ================================================================
 
   /** 模式切换:浏览(只读:相机+点选) / 编辑(可拖拽设备/调整角色落点/旋转/频道整体移动/边界手柄/Agent 活动范围) */
-  setMode(mode: TownScene3DMode): void {
-    if (this.mode === mode) return
-    this.mode = mode
-    if (mode === 'browse') {
-      if (this.pointerDrag) this.endPointerDrag()
-      this.cancelRangeDraw()
-      this.setSelected(null)
-      // 运行模式只读:收起变换手柄(拖拽已在 tryStartPointerDrag 门禁)
-      this.tControls?.detach()
-    }
-    this.refreshChannelHandles()
-    this.refreshAgentRangeHandles()
-    // 编辑模式范围线框可见性(range 线框在编辑模式全部显示,浏览模式仅选中显示)
-    for (const a of this.agents.values()) a.renderRangeLine()
-    this.dirty = true
-  }
+  setMode(mode: TownScene3DMode): void { setMode(this, mode) }
 
-  getMode(): TownScene3DMode {
-    return this.mode
-  }
+  getMode(): TownScene3DMode { return getMode(this) }
 
   /** 网格吸附开关(编辑拖拽落点;默认开) */
-  setSnap(enabled: boolean): void {
-    this.snapEnabled = enabled
-  }
+  setSnap(enabled: boolean): void { setSnap(this, enabled) }
 
-  getSnap(): boolean {
-    return this.snapEnabled
-  }
+  getSnap(): boolean { return getSnap(this) }
 
   /**
    * 尝试开始场景拖拽(编辑模式;指针按下命中设备/角色 → 占用该手势)。
    * 返回 true 表示场景已接管指针(调用方应跳过相机平移)。
    */
-  tryStartPointerDrag(clientX: number, clientY: number): boolean {
-    if (this.mode !== 'edit' || this.isGizmoBusy()) return false
-    const w = this.screenToWorld(clientX, clientY)
-    // 1) Agent 活动范围手柄(编辑模式选中带范围角色时 → 拖拽调整该 Agent 范围大小)
-    const ar = this.pickAgentRangeHandle(w.x, w.z)
-    if (ar) {
-      this.pointerDrag = { kind: 'agentRangeResize', id: ar.agentId, handle: ar.handle }
-      this.emitSaveState('dirty')
-      return true
-    }
-    // 2) 边界缩放手柄(编辑模式选中频道的 4 个手柄 → 调整频道范围大小)
-    const h = this.pickResizeHandle(w.x, w.z)
-    if (h) {
-      this.pointerDrag = { kind: 'resize', id: h.cid, handle: h.handle }
-      this.setSelected(null)
-      this.emitSaveState('dirty')
-      return true
-    }
-    // 3) 框选绘制:rangeDraw 模式激活 → 以按下点为框角拉动(优先于点选,便于从角色身上起手)
-    if (this.rangeDrawAgent) {
-      this.pointerDrag = { kind: 'rangeDraw', id: this.rangeDrawAgent, x0: w.x, z0: w.z }
-      this.rangeDrawPreviewState = null
-      return true
-    }
-    // 4) 设备 / 角色
-    const hit = this.pickAt(w.x, w.z)
-    if (hit) {
-      if (hit.kind === 'device') {
-        if (!this.deviceNodes.has(hit.id)) return false
-        this.pointerDrag = hit
-        this.setSelected(hit)
-        this.emitSaveState('dirty')
-        return true
-      }
-      // 角色:仅频道角色可调整落点(装饰居民不持久化、不可布局)
-      const asp = this.agents.get(hit.id)
-      if (!asp || !asp.channelId) return false
-      if (asp.bubbleTimer) {
-        clearTimeout(asp.bubbleTimer)
-        asp.bubbleTimer = null
-      }
-      asp.dragging = true
-      asp.behavior.mode = 'idle'
-      asp.behavior.targetId = null
-      this.pointerDrag = hit
-      this.setSelected(hit)
-      this.emitSaveState('dirty')
-      return true
-    }
-    // 5) 拖某成员活动范围边界线 → 整框平移(频道整体移动之前;频道移动先排除已按范围接管)
-    const rangeHit = this.hitAgentRangeBoundary(w.x, w.z)
-    if (rangeHit && rangeHit.range) {
-      this.pointerDrag = { kind: 'agentRange', id: rangeHit.agentId, dx: rangeHit.range.x - w.x, dz: rangeHit.range.z - w.z }
-      this.setSelected({ kind: 'agent', id: rangeHit.agentId })
-      this.emitSaveState('dirty')
-      return true
-    }
-    // 6) 频道边界线拖拽:抓住边界附近 → 整体等比缩放(手柄之外,自由拉边调节范围)
-    const edge = this.pickChannelEdge(w.x, w.z)
-    if (edge) {
-      this.pointerDrag = { kind: 'channelEdge', id: edge.cid, rx0: edge.rx0, rz0: edge.rz0, rd0: edge.rd0 }
-      this.setSelected(null)
-      this.selectChannel(edge.cid)
-      this.emitSaveState('dirty')
-      return true
-    }
-    // 7) 频道信标:非拖拽目标(点击定位语义交给 pointerup;避免编辑模式下点信标变成整体拖动)
-    if (this.pickBeacon(w.x, w.z)) return false
-    // 8) 频道领地整体拖拽:点中领地空白处 → 平移整个频道(平台/边界/名牌/成员落点)
-    const cid = this.pickChannel(w.x, w.z)
-    if (cid) {
-      const b = this.blocks.get(cid)
-      if (!b) return false
-      this.pointerDrag = { kind: 'channel', id: cid, dx: b.x - w.x, dz: b.z - w.z }
-      this.setSelected(null)
-      this.selectChannel(cid)
-      this.emitSaveState('dirty')
-      return true
-    }
-    return false
-  }
+  tryStartPointerDrag(clientX: number, clientY: number): boolean { return tryStartPointerDrag(this, clientX, clientY) }
 
-  isPointerDragging(): boolean {
-    return this.pointerDrag !== null
-  }
+  isPointerDragging(): boolean { return isPointerDragging(this) }
 
-  private snapWorld(v: number): number {
-    return this.snapEnabled ? Math.round(v / SNAP_SIZE) * SNAP_SIZE : Math.round(v * 10) / 10
-  }
+  snapWorld(v: number): number { return snapWorld(this, v) }
 
   /** 拖拽中:对象跟随指针指向的 xz 平面(仅改内存;落库在 endPointerDrag) */
-  movePointerDrag(clientX: number, clientY: number): void {
-    if (!this.pointerDrag) return
-    const w = this.screenToWorld(clientX, clientY)
-    // 无边界画布:仅网格吸附,不钳制世界范围(模型可摆放到任意位置)
-    const x = this.snapWorld(w.x)
-    const z = this.snapWorld(w.z)
-    const pd = this.pointerDrag
-    if (pd.kind === 'device') {
-      const dev = this.deviceNodes.get(pd.id)
-      if (dev) {
-        dev.root.position.x = x
-        dev.root.position.z = z
-        this.dirty = true
-      }
-    }
-    else if (pd.kind === 'agent') {
-      const asp = this.agents.get(pd.id)
-      if (asp) {
-        // 频道角色落点钳制在所属领地边界内(不可拖出频道)
-        let px = x
-        let pz = z
-        const layout = this.blockLayout(asp.channelId)
-        if (layout) {
-          const clamped = clampToBoundary(layout, x, z, 20)
-          px = clamped.x
-          pz = clamped.z
-        }
-        asp.root.position.x = px
-        asp.root.position.z = pz
-        this.dirty = true
-      }
-    }
-    else if (pd.kind === 'rangeDraw') {
-      // 框选绘制:当前点为对角终点(钳入频道边界),实时更新预览矩形
-      const asp = this.agents.get(pd.id)
-      if (!asp) return
-      const layout = this.blockLayout(asp.channelId)
-      let cx = w.x
-      let cz = w.z
-      if (layout) {
-        const clamped = clampToBoundary(layout, cx, cz, 12)
-        cx = clamped.x
-        cz = clamped.z
-      }
-      this.rangeDrawPreviewState = { x0: pd.x0, z0: pd.z0, x1: cx, z1: cz }
-      this.updateRangeDrawPreview(pd.x0, pd.z0, cx, cz)
-      this.dirty = true
-    }
-    else if (pd.kind === 'agentRange') {
-      // 拖 Agent 活动范围边界 → 整框平移(钳入频道边界;范围线框/手柄跟随)
-      const asp = this.agents.get(pd.id)
-      if (!asp || !asp.range) return
-      const nx = x + pd.dx
-      const nz = z + pd.dz
-      asp.range = { ...asp.range, x: nx, z: nz }
-      asp.renderRangeLine()
-      this.refreshAgentRangeHandles()
-      this.dirty = true
-    }
-    else if (pd.kind === 'agentRangeResize') {
-      // 拖 Agent 范围手柄 → 实时调整 radiusX/radiusZ(矩形角点双轴 / 椭圆轴向轴点)
-      const asp = this.agents.get(pd.id)
-      if (!asp || !asp.range) return
-      asp.range = this.applyAgentRangeResize(asp.range, pd.handle, w.x, w.z)
-      asp.renderRangeLine()
-      this.refreshAgentRangeHandles()
-      this.autoFrameTo(asp.range.radiusX, asp.range.radiusZ)
-      this.dirty = true
-    }
-    else if (pd.kind === 'channel') {
-      const b = this.blocks.get(pd.id)
-      if (b) this.applyBlockMove(b, x + pd.dx, z + pd.dz)
-    }
-    else if (pd.kind === 'resize') {
-      const b = this.blocks.get(pd.id)
-      if (b) this.applyResize(b, pd.handle, w.x, w.z)
-    }
-    else if (pd.kind === 'channelEdge') {
-      // 边界线等比缩放:指针沿"中心→边界"射线的归一化距离比例 → 双轴同倍率
-      const b = this.blocks.get(pd.id)
-      if (b) {
-        const lxz = toLocal(b, x, z)
-        const rd = Math.hypot(lxz.x / pd.rx0, lxz.z / pd.rz0)
-        const factor = pd.rd0 > 0.05 ? rd / pd.rd0 : 1
-        b.radiusX = Math.max(60, Math.round(pd.rx0 * factor))
-        b.radiusZ = Math.max(40, Math.round(pd.rz0 * factor))
-        this.applyLayoutToBlock(b)
-        this.autoFrameTo(b.radiusX, b.radiusZ)
-      }
-    }
-  }
+  movePointerDrag(clientX: number, clientY: number): void { movePointerDrag(this, clientX, clientY) }
 
   /** 拖拽结束:设备 → 防抖落库;角色 → home 更新 + 持久化;频道 → 布局落库 */
-  endPointerDrag(): void {
-    if (!this.pointerDrag) return
-    const pd = this.pointerDrag
-    this.pointerDrag = null
-    if (pd.kind === 'device') {
-      const dev = this.deviceNodes.get(pd.id)
-      if (dev) this.persistDeviceTransform(pd.id)
-    }
-    else if (pd.kind === 'agent') {
-      const asp = this.agents.get(pd.id)
-      if (asp) {
-        asp.homeX = asp.root.position.x
-        asp.homeZ = asp.root.position.z
-        asp.dragging = false
-        this.emitSaveState('saving')
-        void this.agentApi?.updateHome(pd.id, asp.channelId, asp.homeX, asp.homeZ)
-          .then(() => this.emitSaveState('saved', Date.now()))
-          .catch(() => this.emitSaveState('error'))
-      }
-    }
-    else if (pd.kind === 'rangeDraw') {
-      // 框选结束:以拖框中点为中心、半宽为半径生成矩形范围(过小拖动视为取消)
-      const asp = this.agents.get(pd.id)
-      if (asp && this.rangeDrawPreviewState) {
-        const d = this.rangeDrawPreviewState
-        const range: AgentRangeLayout = {
-          x: (d.x0 + d.x1) / 2,
-          z: (d.z0 + d.z1) / 2,
-          radiusX: Math.abs(d.x1 - d.x0) / 2,
-          radiusZ: Math.abs(d.z1 - d.z0) / 2,
-          shape: 'rect',
-          rotationY: 0,
-        }
-        if (range.radiusX >= 40 && range.radiusZ >= 40) {
-          asp.range = range
-          asp.renderRangeLine()
-          // 把角色落点收进新范围(home 若在范围外会导致回归/漫游卡死)
-          const c = clampToAgentRange(asp.range, asp.homeX, asp.homeZ, 0)
-          if (c.x !== asp.homeX || c.z !== asp.homeZ) {
-            asp.homeX = c.x
-            asp.homeZ = c.z
-            asp.root.position.x = c.x
-            asp.root.position.z = c.z
-            void this.agentApi?.updateHome(pd.id, asp.channelId, c.x, c.z).catch(() => {})
-          }
-          this.emitSaveState('saving')
-          void this.agentApi?.updateRange(pd.id, asp.channelId, asp.range)
-            .then(() => this.emitSaveState('saved', Date.now()))
-            .catch(() => this.emitSaveState('error'))
-        }
-      }
-      this.cancelRangeDraw()
-      this.refreshAgentRangeHandles()
-      this.emitAgentRangeChanged(pd.id)
-    }
-    else if (pd.kind === 'agentRange' || pd.kind === 'agentRangeResize') {
-      // 拖范围整框 / 拖范围手柄结束 → 落库 config.range
-      const asp = this.agents.get(pd.id)
-      if (asp && asp.range) {
-        this.emitSaveState('saving')
-        void this.agentApi?.updateRange(pd.id, asp.channelId, asp.range)
-          .then(() => this.emitSaveState('saved', Date.now()))
-          .catch(() => this.emitSaveState('error'))
-      }
-      this.refreshAgentRangeHandles()
-      this.emitAgentRangeChanged(pd.id)
-    }
-    else {
-      // channel / resize:把成员钳回新边界 + 布局落库 + 通知 Vue 刷新边界面板草稿
-      const b = this.blocks.get(pd.id)
-      if (b) {
-        this.clampAgentsToBoundary(pd.id)
-        this.refreshChannelHandles()
-        const layout = this.getChannelLayout(pd.id)
-        if (layout) {
-          this.emitSaveState('saving')
-          void this.channelApi?.save(pd.id, layout)
-            .then(() => this.emitSaveState('saved', Date.now()))
-            .catch(() => this.emitSaveState('error'))
-          this.emit('channelResized', { channelId: pd.id, layout })
-        }
-      }
-    }
-  }
+  endPointerDrag(): void { endPointerDrag(this) }
 
   // ================================================================
   // Agent 独立活动范围(编辑模式:框选绘制 / 整框平移 / 手柄收缩扩张)
+  // 实现见 scene/town-scene3d-ranges.ts
   // ================================================================
 
   /** 活动范围线框可见性:编辑模式全部显示;浏览模式仅选中角色的范围显示 */
-  private rangeLineVisible(asp: Agent3D): boolean {
-    if (this.mode === 'edit') return true
-    return this.selected?.kind === 'agent' && this.selected.id === asp.agentId
-  }
+  rangeLineVisible(asp: Agent3D): boolean { return rangeLineVisible(this, asp) }
 
   /** 通知 Vue 对象面板刷新活动范围草稿 */
-  private emitAgentRangeChanged(agentId: string): void {
-    this.emit('agentRangeChanged', { agentId })
-  }
+  emitAgentRangeChanged(agentId: string): void { emitAgentRangeChanged(this, agentId) }
 
   /** 同步全部范围线框可见性(选中/模式切换后调用) */
-  private refreshAgentRangeLines(): void {
-    for (const a of this.agents.values()) {
-      if (a.rangeLine) a.rangeLine.visible = this.rangeLineVisibleFor(a)
-    }
-  }
+  refreshAgentRangeLines(): void { refreshAgentRangeLines(this) }
 
   /** 活动范围线框可见性(公众面,供 Agent3D.renderRangeLine):编辑模式全部显示;浏览模式仅选中显示 */
-  rangeLineVisibleFor(asp: Agent3D): boolean {
-    if (this.mode === 'edit') return true
-    return this.selected?.kind === 'agent' && this.selected.id === asp.agentId
-  }
+  rangeLineVisibleFor(asp: Agent3D): boolean { return rangeLineVisibleFor(this, asp) }
 
   /** 刷新 Agent 活动范围手柄(编辑模式 + 选中带范围角色时显示;矩形四角 / 椭圆轴向四点) */
-  private refreshAgentRangeHandles(): void {
-    for (const hl of this.agentRangeHandles) hl.mesh.visible = false
-    if (this.mode !== 'edit' || !this.selected || this.selected.kind !== 'agent') return
-    const asp = this.agents.get(this.selected.id)
-    if (!asp || !asp.range) return
-    const rot = asp.range.rotationY * Math.PI / 180
-    const pts = this.boundaryHandlePoints(asp.range)
-    for (let i = 0; i < this.agentRangeHandles.length && i < pts.length; i++) {
-      const [lx, lz] = pts[i]!
-      const wx = asp.range.x + lx * Math.cos(rot) - lz * Math.sin(rot)
-      const wz = asp.range.z + lx * Math.sin(rot) + lz * Math.cos(rot)
-      this.agentRangeHandles[i]!.agentId = asp.agentId
-      this.agentRangeHandles[i]!.mesh.position.set(wx, 1.2, wz)
-      this.agentRangeHandles[i]!.mesh.visible = true
-    }
-  }
+  refreshAgentRangeHandles(): void { refreshAgentRangeHandles(this) }
 
   /** 命中选中 Agent 的活动范围手柄(编辑模式;返回 agentId + 手柄号) */
-  private pickAgentRangeHandle(x: number, z: number): { agentId: string, handle: number } | null {
-    if (this.mode !== 'edit') return null
-    for (const hl of this.agentRangeHandles) {
-      if (!hl.mesh.visible) continue
-      if (Math.hypot(hl.mesh.position.x - x, hl.mesh.position.z - z) < 40) return { agentId: hl.agentId, handle: hl.handle }
-    }
-    return null
-  }
+  pickAgentRangeHandle(x: number, z: number): { agentId: string, handle: number } | null { return pickAgentRangeHandle(this, x, z) }
 
   /** 命中某成员活动范围边界线(供整框拖移;编辑模式;26 单位内视为命中) */
-  private hitAgentRangeBoundary(x: number, z: number): Agent3D | undefined {
-    if (this.mode !== 'edit') return undefined
-    for (const a of this.agents.values()) {
-      if (!a.range || !a.channelId) continue
-      if (distToRangeBoundary(a.range, x, z) < 26) return a
-    }
-    return undefined
-  }
+  hitAgentRangeBoundary(x: number, z: number): Agent3D | undefined { return hitAgentRangeBoundary(this, x, z) }
 
   /** 拖范围手柄 → 实时调整 radiusX/radiusZ(矩形:角点双轴;椭圆:对应轴向轴点),并收进频道边界 */
-  private applyAgentRangeResize(range: AgentRangeLayout, handle: number, wx: number, wz: number): AgentRangeLayout {
-    const rad = -range.rotationY * Math.PI / 180
-    const cos = Math.cos(rad)
-    const sin = Math.sin(rad)
-    const dx = wx - range.x
-    const dz = wz - range.z
-    const lx = dx * cos - dz * sin
-    const lz = dx * sin + dz * cos
-    let next: AgentRangeLayout
-    if (range.shape === 'rect') {
-      next = { ...range, radiusX: Math.max(30, Math.abs(lx)), radiusZ: Math.max(30, Math.abs(lz)) }
-    }
-    else if (handle === 0 || handle === 1) {
-      next = { ...range, radiusX: Math.max(30, Math.abs(lx)) }
-    }
-    else {
-      next = { ...range, radiusZ: Math.max(30, Math.abs(lz)) }
-    }
-    return next
-  }
+  applyAgentRangeResize(range: AgentRangeLayout, handle: number, wx: number, wz: number): AgentRangeLayout { return applyAgentRangeResize(range, handle, wx, wz) }
 
   /** 框选预览:以 (x0,z0)-(x1,z1) 为对角生成矩形线框(实时跟随指针) */
-  private updateRangeDrawPreview(x0: number, z0: number, x1: number, z1: number): void {
-    const lx = Math.min(x0, x1)
-    const hx = Math.max(x0, x1)
-    const lz = Math.min(z0, z1)
-    const hz = Math.max(z0, z1)
-    const cx = (lx + hx) / 2
-    const cz = (lz + hz) / 2
-    const rx = Math.max(8, (hx - lx) / 2)
-    const rz = Math.max(8, (hz - lz) / 2)
-    if (!this.rangeDrawLine) {
-      const line = makeBoundary('rect', 1, 1, 0x41c8f4)
-      ;(line.material as THREE.LineBasicMaterial).opacity = 0.95
-      line.position.y = 0.5
-      this.scene.add(line)
-      this.rangeDrawLine = line
-    }
-    this.rangeDrawLine.position.set(cx, 0.5, cz)
-    this.rangeDrawLine.rotation.y = 0
-    const geo = new THREE.BufferGeometry().setFromPoints([
-      new THREE.Vector3(-rx, 0, -rz), new THREE.Vector3(rx, 0, -rz),
-      new THREE.Vector3(rx, 0, rz), new THREE.Vector3(-rx, 0, rz),
-    ])
-    this.rangeDrawLine.geometry.dispose()
-    this.rangeDrawLine.geometry = geo
-  }
+  updateRangeDrawPreview(x0: number, z0: number, x1: number, z1: number): void { updateRangeDrawPreview(this, x0, z0, x1, z1) }
 
   /** 退出框选绘制模式(清理预览与状态) */
-  cancelRangeDraw(): void {
-    if (this.rangeDrawAgent === null && !this.rangeDrawLine) return
-    this.rangeDrawAgent = null
-    this.rangeDrawPreviewState = null
-    if (this.rangeDrawLine) {
-      this.scene.remove(this.rangeDrawLine)
-      this.rangeDrawLine = null
-    }
-    this.dirty = true
-  }
+  cancelRangeDraw(): void { cancelRangeDraw(this) }
 
   /** 进入「框选绘制」模式:为该角色拉动矩形框生成活动范围(编辑模式) */
-  startRangeDraw(agentId: string): void {
-    const asp = this.agents.get(agentId)
-    if (!asp || !asp.channelId || this.mode !== 'edit') return
-    this.setSelected({ kind: 'agent', id: agentId })
-    this.cancelRangeDraw()
-    this.rangeDrawAgent = agentId
-    this.rangeDrawPreviewState = null
-    this.refreshAgentRangeHandles()
-    this.dirty = true
-  }
+  startRangeDraw(agentId: string): void { startRangeDraw(this, agentId) }
 
   /** 当前是否正在为某角色框选绘制 */
-  isRangeDrawing(agentId?: string): boolean {
-    if (!this.rangeDrawAgent) return false
-    return agentId === undefined || this.rangeDrawAgent === agentId
-  }
+  isRangeDrawing(agentId?: string): boolean { return isRangeDrawing(this, agentId) }
 
   /** E2E/调试:强制某频道接收器跳过当前条目,立即消费下一条(FIFO 顺序断言用) */
   debugAdvanceReceiver(channelId: string): void {
@@ -3681,799 +781,92 @@ export class TownScene3D {
   }
 
   /** Agent 当前活动范围(供面板初始化;未设置返回 null) */
-  getAgentRange(agentId: string): AgentRangeLayout | null {
-    return this.agents.get(agentId)?.range ?? null
-  }
+  getAgentRange(agentId: string): AgentRangeLayout | null { return getAgentRange(this, agentId) }
 
   /** 面板滑杆/形状即时调整:局部更新范围(无上限,信任用户设定) + 线框/手柄刷新;home 被迫位移时记档待提交 */
-  setAgentRangeScene(agentId: string, patch: Partial<AgentRangeLayout>): void {
-    const asp = this.agents.get(agentId)
-    if (!asp) return
-    if (!asp.range) {
-      // 尚无范围:以落点为中心、频道半径 1/4 起手(面板直接给值时)
-      asp.range = { x: asp.homeX, z: asp.homeZ, radiusX: 120, radiusZ: 90, shape: 'ellipse', rotationY: 0 }
-    }
-    const next = { ...asp.range, ...patch }
-    asp.range = next
-    // 范围收缩致 home 越界 → 落点收进范围(提交时随 updateRange 一并落库)
-    const c = clampToAgentRange(asp.range, asp.homeX, asp.homeZ, 0)
-    if (c.x !== asp.homeX || c.z !== asp.homeZ) {
-      asp.homeX = c.x
-      asp.homeZ = c.z
-      asp.root.position.x = c.x
-      asp.root.position.z = c.z
-      this.rangeHomeMoved = { agentId, x: c.x, z: c.z }
-    }
-    asp.renderRangeLine()
-    this.refreshAgentRangeHandles()
-    this.dirty = true
-  }
+  setAgentRangeScene(agentId: string, patch: Partial<AgentRangeLayout>): void { setAgentRangeScene(this, agentId, patch) }
 
   /** 面板提交:落库范围(updateRange);home 若被迫位移一并落库(updateHome) */
-  commitAgentRange(agentId: string): void {
-    const asp = this.agents.get(agentId)
-    if (!asp) return
-    if (this.rangeHomeMoved?.agentId === agentId) {
-      const { x, z } = this.rangeHomeMoved
-      this.rangeHomeMoved = null
-      void this.agentApi?.updateHome(agentId, asp.channelId, x, z).catch(() => {})
-    }
-    this.emitSaveState('saving')
-    void this.agentApi?.updateRange(agentId, asp.channelId, asp.range)
-      .then(() => this.emitSaveState('saved', Date.now()))
-      .catch(() => this.emitSaveState('error'))
-    this.emitAgentRangeChanged(agentId)
-  }
+  commitAgentRange(agentId: string): void { commitAgentRange(this, agentId) }
 
   /** 清除角色活动范围(局部 + 落库 null;回退频道边界) */
-  clearAgentRange(agentId: string): void {
-    const asp = this.agents.get(agentId)
-    if (!asp) return
-    if (asp.rangeLine) {
-      this.scene.remove(asp.rangeLine)
-      asp.rangeLine = null
-    }
-    asp.range = null
-    this.rangeHomeMoved = null
-    this.refreshAgentRangeHandles()
-    this.emitSaveState('saving')
-    void this.agentApi?.updateRange(agentId, asp.channelId, null)
-      .then(() => this.emitSaveState('saved', Date.now()))
-      .catch(() => this.emitSaveState('error'))
-    this.emitAgentRangeChanged(agentId)
-    this.dirty = true
-  }
+  clearAgentRange(agentId: string): void { clearAgentRange(this, agentId) }
 
   /** 对象朝向(度;编辑模式旋转滑杆实时) */
-  setModelRotation(id: string, deg: number, kind?: 'agent' | 'device'): void {
-    const k = kind ?? (this.deviceNodes.has(id) ? 'device' : 'agent')
-    if (k === 'device') {
-      const dev = this.deviceNodes.get(id)
-      if (!dev) return
-      dev.root.rotation.y = deg * Math.PI / 180
-    }
-    else {
-      const asp = this.agents.get(id)
-      if (!asp) return
-      asp.root.rotation.y = deg * Math.PI / 180
-    }
-    this.dirty = true
-  }
+  setModelRotation(id: string, deg: number, kind?: 'agent' | 'device'): void { setModelRotation(this, id, deg, kind) }
 
-  getModelRotation(id: string, kind?: 'agent' | 'device'): number {
-    const k = kind ?? (this.deviceNodes.has(id) ? 'device' : 'agent')
-    if (k === 'device') {
-      const dev = this.deviceNodes.get(id)
-      return dev ? THREE.MathUtils.radToDeg(dev.root.rotation.y) : 0
-    }
-    const asp = this.agents.get(id)
-    return asp ? THREE.MathUtils.radToDeg(asp.root.rotation.y) : 0
-  }
+  getModelRotation(id: string, kind?: 'agent' | 'device'): number { return getModelRotation(this, id, kind) }
 
   // ================================================================
   // 场景保存状态(未保存/保存中/已保存/失败)+ 设备 transform 防抖落库
+  // 实现见 scene/town-scene3d-devices.ts
   // ================================================================
 
-  private emitSaveState(state: 'idle' | 'dirty' | 'saving' | 'saved' | 'error', at = Date.now()): void {
+  emitSaveState(state: 'idle' | 'dirty' | 'saving' | 'saved' | 'error', at = Date.now()): void {
     this.emit('saveState', { state, at })
   }
 
   /** 持久化设备 transform(位置/朝向/缩放一次写入;防抖 350ms,不逐帧写库) */
-  persistDeviceTransform(id: string): void {
-    const dev = this.deviceNodes.get(id)
-    if (!dev || !this.devices?.update || this.pendingDeviceCreates.has(id)) return
-    const st = this.scalables.get(`device:${id}`)
-    const prev = this.pendingSaveTimers.get(id)
-    if (prev) clearTimeout(prev)
-    this.pendingSaveTimers.set(id, setTimeout(() => {
-      this.pendingSaveTimers.delete(id)
-      if (this.disposed || this.pendingDeviceCreates.has(id)) return
-      this.emitSaveState('saving')
-      void this.devices!.update(id, {
-        posX: Math.round(dev.root.position.x * 10) / 10,
-        posZ: Math.round(dev.root.position.z * 10) / 10,
-        rotationY: Math.round(THREE.MathUtils.radToDeg(dev.root.rotation.y) * 10) / 10,
-        scale: st ? Math.round(st.userScale * 100) / 100 : undefined,
-      })
-        .then(() => this.emitSaveState('saved', Date.now()))
-        .catch(() => this.emitSaveState('error'))
-    }, 350))
-    this.emitSaveState('dirty')
-  }
+  persistDeviceTransform(id: string): void { persistDeviceTransform(this, id) }
 
   /** 保存全部设备节点(「保存布局」按钮:强制全量落库) */
-  persistAllDevices(): void {
-    for (const id of [...this.deviceNodes.keys()]) this.persistDeviceTransform(id)
-  }
+  persistAllDevices(): void { persistAllDevices(this) }
 
-  private pendingSaveTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  pendingSaveTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
   // ================================================================
-  // 设备场景实例同步(服务端设备孪生 → 本地节点;多客户端一致)
+  // 设备场景实例同步(服务端设备孪生 → 本地节点;多客户端一致;
+  // 实现见 scene/town-scene3d-devices.ts)
   // ================================================================
 
   /**
-   * 与设备孪生清单对齐:
-   *  - 服务端有落点且本地无节点 → 按保存的 transform 重建节点(刷新后恢复);
-   *  - 已存在 → 收敛状态/遥测,并在未拖拽时收敛 transform(他人编辑即时跟随);
-   *  - 服务端已删除 → 移除本地节点。
-   * TownView 在 device.* 事件与轮询时调用;轮询兜底多客户端同步。
+   * 与设备孪生清单对齐:服务端有落点且本地无节点 → 重建;已存在 → 收敛状态/遥测/transform;
+   * 服务端已删除 → 移除本地节点。TownView 在 device.* 事件与轮询时调用。
    */
-  syncDevices(twins: DeviceTwinSync[]): void {
-    const serverIds = new Set(twins.map(t => t.id))
-    for (const id of [...this.deviceNodes.keys()]) {
-      if (!serverIds.has(id) && !this.pendingDeviceCreates.has(id)) this.removeDeviceNode(id)
-    }
-    for (const t of twins) {
-      let existing = this.deviceNodes.get(t.id)
-      if (!existing) {
-        const pending = [...this.pendingDeviceCreates.entries()].find(([, p]) =>
-          p.name === t.name && p.modelRef === t.modelRef,
-        )
-        if (pending) {
-          this.adoptDeviceNode(pending[0], t.id)
-          existing = this.deviceNodes.get(t.id)
-        }
-      }
-      if (!existing) {
-        // 数采/智控节点走程序化路径(无 GLB 也可实例化);设备需模型可解析 + 已入场景
-        const isDaq = t.kind === 'daq' || (t.modelRef ?? '').startsWith('daq-') || (t.modelRef ?? '').startsWith('dcw-')
-        const resolvable = isDaq || !!this.resolveDeviceModel(t.modelRef)?.file
-        if (resolvable && typeof t.posX === 'number' && typeof t.posZ === 'number') this.recreateDeviceNode(t)
-        else this.pendingDeviceTwins.set(t.id, t)
-        continue
-      }
-      this.pendingDeviceTwins.delete(t.id)
-      existing.applyTwin(t)
-      if (this.pointerDrag?.id !== t.id) {
-        const moved = (typeof t.posX === 'number' && t.posX !== existing.root.position.x)
-          || (typeof t.posZ === 'number' && t.posZ !== existing.root.position.z)
-        if (typeof t.posX === 'number') existing.root.position.x = t.posX
-        if (typeof t.posZ === 'number') existing.root.position.z = t.posZ
-        if (typeof t.rotationY === 'number') existing.root.rotation.y = t.rotationY * Math.PI / 180
-        const st = this.scalables.get(`device:${t.id}`)
-        if (typeof t.scale === 'number' && st) {
-          st.userScale = t.scale
-          st.holder.scale.setScalar(t.scale)
-        }
-        if (moved) this.dirty = true
-      }
-      this.dirty = true
-    }
-    // 设备节点就位后重仲裁绑定链路(链路期望先于节点到达的时序兜底)
-    if (this.daqLinksWanted.length) this.syncDaqLinks(this.daqLinksWanted)
-    for (const id of [...this.pendingDeviceTwins.keys()]) {
-      if (!serverIds.has(id)) this.pendingDeviceTwins.delete(id)
-    }
-  }
+  syncDevices(twins: DeviceTwinSync[]): void { syncDevices(this, twins) }
 
   /** 按设备孪生记录重建场景节点(持久化恢复:pos/rotation/scale;模型缺失则跳过) */
-  /** 设备模型解析:精确 id → `dev-folder-<ref>` 前缀 → `-<ref>` 后缀(兼容旧数据短 modelRef) */
-  private resolveDeviceModel(ref: string): { id: string, file: string, hFactor: number } | null {
-    const direct = this.modelsById.get(ref)
-    if (direct?.file) return { id: direct.id, file: direct.file, hFactor: direct.hFactor ?? 1 }
-    for (const [id, m] of this.modelsById) {
-      if (m.kind !== 'dev' || !m.file) continue
-      if (id === `dev-folder-${ref}` || id.endsWith(`-${ref}`)) return { id, file: m.file, hFactor: m.hFactor ?? 1 }
-    }
-    return null
-  }
-
-  private recreateDeviceNode(t: DeviceTwinSync): void {
-    // 数采/智控节点:程序化传感网格(基座 + 传感头 + 信号环),不依赖 GLB 资产
-    // (modelRef 前缀兜底:旧数据 kind 落成 'device' 的数采实例同样走程序化路径)
-    if (t.kind === 'daq' || (t.modelRef ?? '').startsWith('daq-') || (t.modelRef ?? '').startsWith('dcw-')) {
-      this.recreateDaqNode(t)
-      return
-    }
-    const model = this.resolveDeviceModel(t.modelRef)
-    const file = model?.file ?? ''
-    if (!file) return
-    const x = typeof t.posX === 'number' ? t.posX : WORLD_CX
-    const z = typeof t.posZ === 'number' ? t.posZ : WORLD_CZ
-    const root = new THREE.Group()
-    root.position.set(x, GROUND_Y, z)
-    root.rotation.y = typeof t.rotationY === 'number' ? t.rotationY * Math.PI / 180 : 0
-    const { ring, arc } = this.makeDeviceRing()
-    root.add(ring, arc)
-    const holder = new THREE.Group()
-    root.add(holder)
-    const label = this.makeLabel(`⚙ ${t.name}`, x, 60, z)
-    holder.userData.modelFile = file
-    this.scene.add(root)
-    const twin = new DeviceNode({ twinId: t.id, name: t.name, modelRef: t.modelRef, root, holder, ring, label, state: t.state ?? 'idle', telemetry: t.telemetry ?? {} })
-    twin.host = this
-    twin.arc = arc
-    twin.updateRing()
-    this.deviceNodes.set(t.id, twin)
-    // 服务端缩放优先(持久化恢复);缺省回退 localStorage
-    this.registerScalable('device', t.id, holder, typeof t.scale === 'number' ? t.scale : undefined)
-    // 高度系数:产线设备按设计稿比例错落(基准高 × 模型系数),未知模型维持 1
-    void this.loadGltfToGroup(file, holder, UNITS * 1.6 * (model?.hFactor ?? 1))
-    this.dirty = true
-  }
-
-  /** 数采节点传感头(设计稿 DAQ 预制件 1:1 移植,×34 世界单位):
-   *  立杆基座 + 顶端 LED 环 + 每模板独立传感形态 —— 温度计/压力表/张力辊/编码盘/相机/电参天线。 */
-  private makeDaqMesh(modelRef: string): { group: THREE.Group, ledRing: THREE.Mesh } {
-    const S = 34
-    const g = new THREE.Group()
-    const steel = new THREE.MeshStandardMaterial({ color: 0x9fb2c8, metalness: 0.85, roughness: 0.32 })
-    const body = new THREE.MeshStandardMaterial({ color: 0x74869c, metalness: 0.35, roughness: 0.5 })
-    const body2 = new THREE.MeshStandardMaterial({ color: 0x55647a, metalness: 0.4, roughness: 0.55 })
-    const dark = new THREE.MeshStandardMaterial({ color: 0x2b3442, metalness: 0.7, roughness: 0.45 })
-    const chrome = new THREE.MeshStandardMaterial({ color: 0xdfe8f2, metalness: 1, roughness: 0.14 })
-    const copper = new THREE.MeshStandardMaterial({ color: 0xc57a45, metalness: 0.9, roughness: 0.35 })
-    const glow = new THREE.MeshBasicMaterial({ color: 0x41c8f4 })
-    glow.color.multiplyScalar(5)
-    const B = (w: number, h: number, d: number, m: THREE.Material): THREE.Mesh => {
-      const mesh = new THREE.Mesh(new THREE.BoxGeometry(w * S, h * S, d * S), m)
-      mesh.castShadow = true
-      return mesh
-    }
-    const Cyl = (rt: number, rb: number, h: number, m: THREE.Material, seg = 20): THREE.Mesh => {
-      const mesh = new THREE.Mesh(new THREE.CylinderGeometry(rt * S, rb * S, h * S, seg), m)
-      mesh.castShadow = true
-      return mesh
-    }
-    const at = (m: THREE.Mesh, x: number, y: number, z: number): THREE.Mesh => {
-      m.position.set(x * S, y * S, z * S)
-      g.add(m)
-      return m
-    }
-    // 立杆基座(设计稿 daqPole)
-    at(Cyl(0.17, 0.22, 0.09, dark), 0, 0.045, 0)
-    at(Cyl(0.028, 0.028, 0.95, steel, 10), 0, 0.55, 0)
-    const ledRing = new THREE.Mesh(new THREE.TorusGeometry(0.09 * S, 0.02 * S, 10, 28), new THREE.MeshBasicMaterial({ color: 0x35e0a0 }))
-    // HDR 亮度:LED 环(及其复用材质的 halo/iris/tip)提到阈值之上,"真发光"元件(bloom 起晕)
-    ;(ledRing.material as THREE.MeshBasicMaterial).color.multiplyScalar(6)
-    ledRing.rotation.x = Math.PI / 2
-    g.add(ledRing)
-    ledRing.position.y = 1.02 * S
-    // 每模板传感头(modelRef = `daq-<tplId>`)
-    if (modelRef.endsWith('temp-tc')) {
-      at(B(0.24, 0.32, 0.24, body), 0, 1.2, 0)
-      const probe = at(Cyl(0.014, 0.014, 0.4, steel, 8), 0.14, 0.85, 0)
-      probe.rotation.z = -0.5
-    }
-    else if (modelRef.endsWith('pressure-tx')) {
-      at(Cyl(0.13, 0.16, 0.3, steel), 0, 1.22, 0)
-      at(Cyl(0.12, 0.12, 0.05, dark), 0, 1.4, 0)
-      at(B(0.05, 0.05, 0.2, copper), 0, 1.1, 0.2)
-    }
-    else if (modelRef.endsWith('tension-cell')) {
-      at(B(0.34, 0.2, 0.2, body), 0, 1.25, 0)
-      for (const x of [-0.11, 0.11]) {
-        const roll = at(Cyl(0.06, 0.06, 0.26, chrome), x, 1.25, 0)
-        roll.rotation.x = Math.PI / 2
-      }
-    }
-    else if (modelRef.endsWith('line-encoder')) {
-      at(B(0.34, 0.05, 0.05, steel), 0.14, 1.28, 0)
-      const disc = at(Cyl(0.16, 0.16, 0.05, dark), 0.32, 1.28, 0)
-      disc.rotation.z = Math.PI / 2
-      const halo = new THREE.Mesh(new THREE.TorusGeometry(0.1 * S, 0.015 * S, 10, 26), ledRing.material as THREE.Material)
-      at(halo, 0.35, 1.28, 0)
-    }
-    else if (modelRef.endsWith('vision-cam')) {
-      at(B(0.28, 0.2, 0.36, body2), 0, 1.3, 0)
-      const lens = at(Cyl(0.07, 0.09, 0.14, dark), 0, 1.3, 0.24)
-      lens.rotation.x = Math.PI / 2
-      const iris = new THREE.Mesh(new THREE.TorusGeometry(0.075 * S, 0.012 * S, 10, 24), ledRing.material as THREE.Material)
-      at(iris, 0, 1.3, 0.3)
-    }
-    else if (modelRef.endsWith('power-meter')) {
-      at(B(0.32, 0.42, 0.18, body), 0, 1.3, 0)
-      at(Cyl(0.012, 0.012, 0.42, steel, 8), 0.1, 1.7, 0)
-      const tip = new THREE.Mesh(new THREE.SphereGeometry(0.028 * S, 10, 8), ledRing.material as THREE.Material)
-      at(tip, 0.1, 1.92, 0)
-      at(B(0.2, 0.06, 0.02, glow), 0, 1.42, 0.1)
-    }
-    return { group: g, ledRing }
-  }
-
-  /** 数采/智控节点(程序化):模板分化传感网格 + **产线光晕**(同产线同色光环)+ 名牌 */
-  private recreateDaqNode(t: DeviceTwinSync): void {
-    const x = typeof t.posX === 'number' ? t.posX : WORLD_CX
-    const z = typeof t.posZ === 'number' ? t.posZ : WORLD_CZ
-    const root = new THREE.Group()
-    root.position.set(x, GROUND_Y, z)
-    root.rotation.y = typeof t.rotationY === 'number' ? t.rotationY * Math.PI / 180 : 0
-    const { group: sensor, ledRing } = this.makeDaqMesh(t.modelRef)
-    root.add(sensor)
-    const sigRing = new THREE.Mesh(
-      new THREE.RingGeometry(16, 21, 36),
-      new THREE.MeshBasicMaterial({ color: 0x35e0a0, transparent: true, opacity: 0.5, side: THREE.DoubleSide, depthWrite: false }),
-    )
-    sigRing.rotation.x = -Math.PI / 2
-    sigRing.position.y = 0.35
-    root.add(sigRing)
-    // 产线光晕:外圈加性光环(soft) + 内圈亮环;未分配 = 缺省绿
-    const haloOuter = new THREE.Mesh(
-      new THREE.RingGeometry(24, 34, 48),
-      new THREE.MeshBasicMaterial({ color: 0x35e0a0, transparent: true, opacity: 0.16, side: THREE.DoubleSide, depthWrite: false, blending: THREE.AdditiveBlending }),
-    )
-    haloOuter.rotation.x = -Math.PI / 2
-    haloOuter.position.y = 0.28
-    root.add(haloOuter)
-    const accent = t.lineColor || '#35e0a0'
-    const label = this.makeLabel(t.name, x, 62, z, accent)
-    this.scene.add(root)
-    const node = new DeviceNode({
-      twinId: t.id, name: t.name, modelRef: t.modelRef,
-      root, holder: root, ring: sigRing, label,
-      state: t.state ?? 'running', telemetry: t.telemetry ?? {},
-    })
-    node.host = this
-    node.lineColor = t.lineColor ?? ''
-    // 换产线/换色:重 tint 光环 + LED 环 + 名牌(applyTwin 检测 lineColor 变化时触发)
-    node.applyLine = (color: string) => {
-      const c = new THREE.Color(color || '#35e0a0')
-      ;(sigRing.material as THREE.MeshBasicMaterial).color.copy(c)
-      ;(haloOuter.material as THREE.MeshBasicMaterial).color.copy(c)
-      ;(ledRing.material as THREE.MeshBasicMaterial).color.copy(c).multiplyScalar(6) // 保持 HDR(LED 起晕)
-      this.scene.remove(label)
-      label.material.dispose()
-      const fresh = this.makeLabel(node.name, root.position.x, 62, root.position.z, color || '#35e0a0')
-      node.label = fresh
-      this.scene.add(fresh)
-      this.dirty = true
-    }
-    if (t.lineColor) node.applyLine(t.lineColor)
-    node.updateRing()
-    this.deviceNodes.set(t.id, node)
-    this.daqLedRings.set(t.id, ledRing)
-    this.registerScalable('device', t.id, root, typeof t.scale === 'number' ? t.scale : undefined)
-    this.dirty = true
-  }
-
-  /** 移除设备场景节点(服务端记录被删/本地重建清理) */
-  private removeDeviceNode(id: string): void {
-    const dev = this.deviceNodes.get(id)
-    if (!dev) return
-    this.scene.remove(dev.root)
-    this.scene.remove(dev.label)
-    this.disposeDeviceAssets(dev)
-    if (this.selected?.kind === 'device' && this.selected.id === id) this.setSelected(null)
-    this.scalables.delete(`device:${id}`)
-    this.deviceNodes.delete(id)
-    this.daqLedRings.delete(id)
-    this.daqLinkSig = ''
-    this.filmWebSig = ''
-    this.dirty = true
-  }
+  recreateDeviceNode(t: DeviceTwinSync): void { recreateDeviceNode(this, t) }
 
   // ================================================================
-  // 数采绑定链路 + 薄膜 web(设计稿 buildChanLine / rebuildWeb 移植)
+  // 数采绑定链路 + 薄膜 web(设计稿 buildChanLine / rebuildWeb 移植;
+  // 实现见 scene/town-scene3d-links.ts)
   // ================================================================
 
-  /** 设备顶端世界高度(holder 包围盒;链路/膜 web 的挂点)。
-   *  缓存优先:Box3.setFromObject 遍历整个 GLB 子树,原每帧每设备全量计算是 HUD 最大热点;
-   *  设备贴地 y=0,高度只随缩放变化 → setModelScale/registerScalable 时失效即可。 */
-  private deviceTopY(dev: DeviceNode): number {
-    if (dev.topYCache != null) return dev.topYCache
-    const box = new THREE.Box3().setFromObject(dev.holder)
-    const y = Number.isFinite(box.max.y) ? Math.max(40, box.max.y) : 64
-    dev.topYCache = y
-    return y
-  }
+  /** 设备顶端世界高度(holder 包围盒;链路/膜 web 的挂点) */
+  deviceTopY(dev: DeviceNode): number { return deviceTopY(dev) }
 
   /** 同步数采→设备绑定链路(TownView 传入 [{daqId, deviceId}];端点移动时逐帧跟随重建) */
-  syncDaqLinks(links: Array<{ daqId: string, deviceId: string }>): void {
-    this.daqLinksWanted = links
-    // 签名按"成功建链"的链路计算:节点未就绪被跳过的链路不计入 → 设备节点晚到时 syncDevices 末尾重仲裁补链
-    const built = links.filter(l => this.deviceNodes.has(l.daqId) && this.deviceNodes.has(l.deviceId))
-    const sig = built.map(l => `${l.daqId}>${l.deviceId}`).sort().join('|')
-    if (sig === this.daqLinkSig) return
-    this.daqLinkSig = sig
-    for (const l of this.daqLinks) {
-      this.daqLinkGroup.remove(l.line)
-      this.daqLinkGroup.remove(l.pulse)
-      l.line.geometry.dispose()
-    }
-    this.daqLinks = []
-    for (const l of built) {
-      const daq = this.deviceNodes.get(l.daqId)!
-      const dev = this.deviceNodes.get(l.deviceId)!
-      const a = new THREE.Vector3(daq.root.position.x, 42, daq.root.position.z)
-      const b = new THREE.Vector3(dev.root.position.x, this.deviceTopY(dev) + 6, dev.root.position.z)
-      const mid = a.clone().add(b).multiplyScalar(0.5)
-      mid.y = Math.max(a.y, b.y) + 42
-      const curve = new THREE.QuadraticBezierCurve3(a, mid, b)
-      const geo = new THREE.BufferGeometry().setFromPoints(curve.getPoints(28))
-      const line = new THREE.Line(geo, new THREE.LineDashedMaterial({ color: 0x35e0a0, transparent: true, opacity: 0.55, dashSize: 8, gapSize: 5 }))
-      line.computeLineDistances()
-      const pulse = new THREE.Mesh(new THREE.SphereGeometry(2.6, 10, 8), new THREE.MeshBasicMaterial({ color: 0x41c8f4 }))
-      ;(pulse.material as THREE.MeshBasicMaterial).color.multiplyScalar(5) // HDR:链路数据脉冲起晕
-      this.daqLinkGroup.add(line, pulse)
-      this.daqLinks.push({ ...l, line, pulse, curve, pt: Math.random(), ptSig: '' })
-    }
-    this.dirty = true
-  }
+  syncDaqLinks(links: Array<{ daqId: string, deviceId: string }>): void { syncDaqLinks(this, links) }
 
   /** 端点跟随:任一端点位移超阈值 → 重建该链路曲线(拖拽设备/数采时虚线实时跟随) */
-  /** 链路端点 scratch(逐帧跟随用;免每帧 3 次分配) */
-  private static readonly _lkA = new THREE.Vector3()
-  private static readonly _lkB = new THREE.Vector3()
-  private static readonly _lkM = new THREE.Vector3()
-
-  private refreshDaqLinks(): void {
-    for (const l of this.daqLinks) {
-      const daq = this.deviceNodes.get(l.daqId)
-      const dev = this.deviceNodes.get(l.deviceId)
-      if (!daq || !dev) continue
-      const topY = this.deviceTopY(dev) + 6
-      const sig = `${Math.round(daq.root.position.x)},${Math.round(daq.root.position.z)},${Math.round(dev.root.position.x)},${Math.round(dev.root.position.z)},${Math.round(topY)}`
-      if (sig === l.ptSig) continue // 端点未动:曲线/geometry 不重建(脉冲仍逐帧走)
-      l.ptSig = sig
-      const a = TownScene3D._lkA.set(daq.root.position.x, 42, daq.root.position.z)
-      const b = TownScene3D._lkB.set(dev.root.position.x, topY, dev.root.position.z)
-      const mid = TownScene3D._lkM.copy(a).add(b).multiplyScalar(0.5)
-      mid.y = Math.max(a.y, b.y) + 42
-      l.curve.v0.copy(a)
-      l.curve.v1.copy(mid)
-      l.curve.v2.copy(b)
-      const pts = l.curve.getPoints(28)
-      l.line.geometry.setFromPoints(pts)
-      l.line.computeLineDistances()
-    }
-  }
-
-  /** 产线设备型号识别(modelRef 含产线关键字 → 薄膜 web 连线成员) */
-  private isLineDevice(modelRef: string): boolean {
-    const ref = modelRef.toLowerCase()
-    return /extruder|caster|mdo|tdo|winder/.test(ref)
-  }
+  refreshDaqLinks(): void { refreshDaqLinks(this) }
 
   /** 薄膜 web:按 X 序连接产线设备(挤出→流延→MD→TD→收卷),半透明膜面 —— 产线工艺连续性可视化 */
-  private rebuildFilmWeb(): void {
-    const list = [...this.deviceNodes.values()]
-      .filter(d => this.isLineDevice(d.modelRef) && !d.modelRef.startsWith('daq-'))
-      .sort((a, b) => a.root.position.x - b.root.position.x)
-    const sig = list.map(d => `${d.twinId}:${Math.round(d.root.position.x)},${Math.round(d.root.position.z)}`).join('|')
-    if (sig === this.filmWebSig) return
-    this.filmWebSig = sig
-    while (this.filmWebGroup.children.length) {
-      const c = this.filmWebGroup.children[0] as THREE.Mesh
-      this.filmWebGroup.remove(c)
-      c.geometry.dispose()
-    }
-    if (!this.filmWebMat) {
-      this.filmWebMat = new THREE.MeshStandardMaterial({
-        color: 0xaad8ff, metalness: 0.1, roughness: 0.35, transparent: true, opacity: 0.28,
-        emissive: 0x2b6b8f, emissiveIntensity: 0.25, side: THREE.DoubleSide, depthWrite: false,
-      })
-    }
-    for (let i = 0; i < list.length - 1; i++) {
-      const a = list[i]!.root.position
-      const b = list[i + 1]!.root.position
-      const len = Math.abs(b.x - a.x) - 110
-      if (len < 30) continue
-      const web = new THREE.Mesh(new THREE.BoxGeometry(len, 1.2, 46), this.filmWebMat)
-      web.position.set((a.x + b.x) / 2, 48, (a.z + b.z) / 2)
-      this.filmWebGroup.add(web)
-    }
-    this.dirty = true
-  }
+  rebuildFilmWeb(): void { rebuildFilmWeb(this) }
 
   // ================================================================
   // 生命周期 / 渲染循环
   // ================================================================
 
-  private loop(): void {
-    const animate = () => {
-      if (this.disposed) return
-      this.raf = requestAnimationFrame(animate)
-      this.rafCount += 1
-      const rawDt = this.clock.getDelta()
-      // 帧预算门控:数据消费与帧率解耦 —— WS 帧直写实时缓冲(消费层,不受此门控),
-      // 渲染循环每帧只取「当前最新值」上屏(展示层);budget 0 = 不限制(用户可选 60/120/∞)。
-      // 后台标签页 rAF 自动停摆;回前台 rawDt 巨大 → 钳制单步 ≤100ms 防动画跳变
-      if (this.frameBudgetMs > 0) {
-        this.frameAcc += rawDt * 1000
-        if (this.frameAcc < this.frameBudgetMs - 0.5) return
-        this.frameAcc = 0
-      }
-      const dt = Math.min(rawDt, 0.1)
-      const t = this.clock.elapsedTime
-      // 频道信息接收器:FIFO 逐条消费实时消息(每帧检查,展示期满取下一条)
-      this.drainReceivers(performance.now())
-      // 行为 FSM
-      for (const asp of this.agents.values()) {
-        if (asp.state !== 'stopped' && !asp.dragging) asp.update(dt)
-      }
-      // mixer 更新
-      for (const asp of this.agents.values()) {
-        if (asp.mixer) asp.mixer.update(dt)
-      }
-      // 频道信标缓转(顶标菱形旋转,中心定位销的生命感)
-      for (const b of this.blocks.values()) b.beacon.rotation.y += dt * 0.4
-      // 名字/气泡跟随 + 光环呼吸 + 逐帧动画(脉冲/光柱/缓动)
-      for (const asp of this.agents.values()) {
-        asp.nameSprite.position.set(asp.root.position.x, 48, asp.root.position.z)
-        if (asp.bubble) {
-          asp.bubble.position.set(asp.root.position.x, BUBBLE_Y + 22 + Math.max(0, asp.model.scale.y - 1) * 22, asp.root.position.z)
-        }
-        if (asp.auraMats.length) {
-          const br = 0.8 + 0.2 * Math.sin(t * 2.2 + asp.auraPhase)
-          for (const m of asp.auraMats) m.opacity = (m.userData.baseOp as number) * br
-        }
-      }
-      // 设备节点:名牌跟随(状态环是 root 子节点自动跟随;颜色由 updateRing 在状态变化时刷新)+ 运行弧缓转
-      for (const dev of this.deviceNodes.values()) {
-        dev.label.position.set(dev.root.position.x, 60, dev.root.position.z)
-        if (dev.arc?.visible) dev.arc.rotation.z += dt * 1.6
-      }
-      // 数采节点 LED 环:缓转 + 呼吸(绑定链路的信号生命感)
-      for (const ring of this.daqLedRings.values()) {
-        ring.rotation.z += dt * 1.2
-        const s = 1 + Math.sin(t * 3.2) * 0.08
-        ring.scale.setScalar(s)
-      }
-      // 绑定链路:端点位移时重建曲线(dirty 门控;脉冲仍逐帧行走)
-      if (this.daqLinks.length) {
-        if (this.dirty) this.refreshDaqLinks()
-        for (const l of this.daqLinks) {
-          l.pt = (l.pt + dt * 0.3) % 1
-          l.pulse.position.copy(l.curve.getPoint(l.pt))
-        }
-      }
-      // 薄膜 web:产线设备增删/移动时重建(dirty 门控;免每帧签名字符串分配)
-      if (this.dirty) this.rebuildFilmWeb()
-      // 选中高亮环:跟随选中目标(角色按用户缩放、设备按顶高定半径;慢转活性)
-      if (this.selRing) {
-        const sel = this.selected
-        let sx = 0
-        let sz = 0
-        let sr = 0
-        if (sel?.kind === 'agent') {
-          const a = this.agents.get(sel.id)
-          if (a) {
-            sx = a.root.position.x
-            sz = a.root.position.z
-            sr = 46 * Math.max(0.6, a.model.scale.y)
-          }
-        }
-        else if (sel?.kind === 'device') {
-          const d = this.deviceNodes.get(sel.id)
-          if (d) {
-            sx = d.root.position.x
-            sz = d.root.position.z
-            sr = Math.max(34, this.deviceTopY(d) * 0.42)
-          }
-        }
-        this.selRing.visible = sr > 0
-        if (sr > 0) {
-          this.selRing.position.set(sx, 0.5, sz)
-          this.selRing.scale.setScalar(sr)
-          this.selRing.rotation.z += dt * 0.9
-        }
-      }
-      const anims = this.rafAnims
-      this.rafAnims = []
-      for (const f of anims) f()
-      // 相机:围绕 camTarget 按 dolly 距离摆放(拖拽平移 camTarget,滚轮调 dolly,tween 平移 camTarget);
-      // 基线 1250/760 + FOV55 = 全园区电影化 2.5D 框景;穹顶随镜头平移(无限视野观感)
-      // 指数阻尼(帧率无关:1-e^(-λ·dt);60fps 下与旧每帧系数 0.12/0.08 等效,高刷屏不再加速)
-      const kDolly = 1 - Math.exp(-dt * 7.2)
-      if (this.autoDolly !== null) {
-        this.dolly += (this.autoDolly - this.dolly) * kDolly
-        if (Math.abs(this.autoDolly - this.dolly) < 0.01) this.autoDolly = null
-      }
-      const kView = 1 - Math.exp(-dt * 4.8)
-      for (const k of ['yaw', 'pitch', 'radius'] as const) {
-        this.viewCur[k] += (this.viewTarget[k] - this.viewCur[k]) * kView
-      }
-      // 自动环绕(设计稿 tOrbit):缓转方位角(dt 基 ≈ 24s/圈;指针按住场景时暂停)
-      if (this.autoOrbit && !this.pointerDrag) {
-        this.viewCur.yaw -= dt * 0.156
-        this.viewTarget.yaw = this.viewCur.yaw
-      }
-      const r = this.viewCur.radius * this.dolly
-      const cp = Math.cos(this.viewCur.pitch)
-      this.camera.position.set(
-        this.camTarget.x + r * cp * Math.sin(this.viewCur.yaw),
-        20 + r * Math.sin(this.viewCur.pitch),
-        this.camTarget.z + r * cp * Math.cos(this.viewCur.yaw),
-      )
-      this.camera.lookAt(this.camTarget.x, 20, this.camTarget.z)
-      // 无级缩放:近/远裁剪面随 dolly 伸缩(贴脸到星野全程不裁剪)
-      const near = Math.max(0.05, 1.2 * this.dolly)
-      const far = 16000 * this.dolly
-      if (Math.abs(this.camera.near - near) > 0.005 || Math.abs(this.camera.far - far) > 1) {
-        this.camera.near = near
-        this.camera.far = far
-        this.camera.updateProjectionMatrix()
-      }
-      if (this.skyDome) {
-        this.skyDome.position.set(this.camTarget.x, 0, this.camTarget.z)
-        // 穹顶随 dolly 缩放:高空拉远时相机始终在穹内,无硬地平线
-        this.skyDome.scale.setScalar(Math.max(1, this.dolly * 1.3))
-      }
-      // 地面跟随镜头滑动(重复纹理 = 无限地面;高空不见地面边缘);
-      // UV 偏移反向补偿平面位移 → 网格钉死世界坐标(否则纹理跟平面一起滑,平移时有"冰面漂移"感)
-      this.ground.position.set(this.camTarget.x, 0, this.camTarget.z)
-      const gmap = (this.ground.material as THREE.MeshStandardMaterial).map
-      if (gmap) {
-        gmap.offset.set(
-          this.camTarget.x / ((WORLD_W * 16) / gmap.repeat.x),
-          -this.camTarget.z / ((WORLD_H * 16) / gmap.repeat.y),
-        )
-      }
-      // 雾距/阴影范围随 dolly 缩放:任意 zoom 层级下取景内容都不被雾吞、投影不消失
-      const fog = this.scene.fog
-      if (fog instanceof THREE.Fog) {
-        fog.near = 1400 * this.dolly
-        fog.far = 8800 * this.dolly
-      }
-      const sc = this.keyLight.shadow.camera
-      const ext = 1600 * Math.max(1, this.dolly)
-      if (Math.abs(sc.right - ext) > 1) {
-        sc.left = -ext
-        sc.right = ext
-        sc.top = 2300 * Math.max(1, this.dolly)
-        sc.bottom = -2300 * Math.max(1, this.dolly)
-        sc.updateProjectionMatrix()
-        this.renderer.shadowMap.needsUpdate = true
-      }
-      // 阴影按需:内容变化(dirty)或有动画角色(mixer 驱动蒙皮位移)才重绘阴影贴图
-      let shadowAnimated = false
-      for (const asp of this.agents.values()) {
-        if (asp.mixer) {
-          shadowAnimated = true
-          break
-        }
-      }
-      this.renderer.shadowMap.needsUpdate = this.dirty || shadowAnimated
-      // 后处理管线出图(RenderPass → Bloom → OutputPass;替代直渲染)
-      this.renderer.info.reset()
-      this.composer.render(dt)
-      this.dirty = false
-      // FPS(墙钟 1000ms 窗口:performance.now 真实时钟;原 dt 累计在长任务饿死 rAF 时虚高)
-      this.frameCount += 1
-      const wallNow = performance.now()
-      if (this.fpsWinT0 === 0) this.fpsWinT0 = wallNow
-      if (wallNow - this.fpsWinT0 >= 1000) {
-        const fps = Math.round((this.frameCount * 1000) / (wallNow - this.fpsWinT0))
-        this.emit('fps', fps)
-        this.adaptQuality(fps)
-        // 仪表化快照(1Hz;e2e/性能回归经 window.__townStats 读取,免再猜渲染真相)
-        const info = this.renderer.info
-        ;(globalThis as typeof globalThis & { __townStats?: Record<string, number> }).__townStats = {
-          fps,
-          rafHz: this.rafCount,
-          drawCalls: info.render.calls,
-          triangles: info.render.triangles,
-          geometries: info.memory.geometries,
-          textures: info.memory.textures,
-          tier: this.qTier,
-          dpr: +this.renderer.getPixelRatio().toFixed(2),
-          frameBudgetMs: +this.frameBudgetMs.toFixed(2),
-          agents: this.agents.size,
-          devices: this.deviceNodes.size,
-        }
-        this.frameCount = 0
-        this.rafCount = 0
-        this.fpsWinT0 = wallNow
-      }
-    }
-    animate()
-  }
-
-  /** 质量阶梯:实测 fps 连续 2s < 17 → 降一档;连续 4s ≥ 27(帧预算附近)→ 升一档。
-   *  档位 = dprScale × 阴影贴图 × Bloom 开关的组合(Bloom+2048² 阴影是两大单项开销,
-   *  重活机器 11fps = 每帧 ~90ms 主线程阻塞)。统一阶梯,避免多套自适应互相打架。 */
-  private static readonly Q_TIERS = [
-    { scale: 1.0, shadow: 2048, bloom: true },
-    { scale: 0.8, shadow: 2048, bloom: true },
-    { scale: 0.65, shadow: 1024, bloom: true },
-    { scale: 0.55, shadow: 1024, bloom: false },
-  ] as const
+  private loop(): void { startRenderLoop(this) }
 
-  private qTier = 0
+  qTier = 0
 
-  private qLowStreak = 0
+  qLowStreak = 0
 
-  private qHighStreak = 0
+  qHighStreak = 0
 
   /** 画质模式:auto = 质量阶梯自适应;manual 三档由用户固定(渲染配置不再自动变动) */
-  private qualityMode: 'auto' | 'normal' | 'hd' | 'ultra' = 'auto'
-
-  /** 用户画质三档(超清 = WebGL 全配置:满 DPR/2048² 阴影/Bloom/最大各向异性) */
-  private static readonly USER_QUALITY = {
-    ultra: { scale: 1.0, shadow: 2048, bloom: true },
-    hd: { scale: 0.8, shadow: 2048, bloom: true },
-    normal: { scale: 0.6, shadow: 1024, bloom: true },
-  } as const
-
-  setQualityMode(mode: 'auto' | 'normal' | 'hd' | 'ultra'): void {
-    this.qualityMode = mode
-    if (mode === 'auto') {
-      this.applyQuality()
-      return
-    }
-    const q = TownScene3D.USER_QUALITY[mode]
-    this.applyPixelRatio(Math.max(0.5, this.baseDpr * q.scale))
-    const key = this.keyLight
-    if ((key.shadow.mapSize.x ?? 0) !== q.shadow) {
-      key.shadow.mapSize.set(q.shadow, q.shadow)
-      key.shadow.map?.dispose()
-      key.shadow.map = null
-      this.renderer.shadowMap.needsUpdate = true
-    }
-    const bloomPass = this.composer.passes.find(p => p instanceof UnrealBloomPass)
-    if (bloomPass) bloomPass.enabled = q.bloom
-  }
+  qualityMode: 'auto' | 'normal' | 'hd' | 'ultra' = 'auto'
 
-  private adaptQuality(fps: number): void {
-    if (this.qualityMode !== 'auto') return
-    const maxTier = TownScene3D.Q_TIERS.length - 1
-    if (fps < 17 && this.qTier < maxTier) {
-      if (++this.qLowStreak >= 2) {
-        this.qTier++
-        this.applyQuality()
-        this.qLowStreak = 0
-        this.qHighStreak = 0
-      }
-    }
-    else if (fps >= 27 && this.qTier > 0) {
-      if (++this.qHighStreak >= 4) {
-        this.qTier--
-        this.applyQuality()
-        this.qHighStreak = 0
-        this.qLowStreak = 0
-      }
-    }
-    else {
-      this.qLowStreak = 0
-      this.qHighStreak = 0
-    }
-  }
+  setQualityMode(mode: 'auto' | 'normal' | 'hd' | 'ultra'): void { setQualityMode(this, mode) }
 
-  private applyQuality(): void {
-    const tier = TownScene3D.Q_TIERS[this.qTier]!
-    this.applyPixelRatio(Math.max(0.5, this.baseDpr * tier.scale))
-    // 阴影贴图缩容:置空 map 让 three 按新尺寸重分配(渲染循环按需重绘阴影)
-    const key = this.keyLight
-    if ((key.shadow.mapSize.x ?? 0) !== tier.shadow) {
-      key.shadow.mapSize.set(tier.shadow, tier.shadow)
-      key.shadow.map?.dispose()
-      key.shadow.map = null
-      this.renderer.shadowMap.needsUpdate = true
-    }
-    // Bloom 开关:Pass.enabled=false 跳过该 pass(RenderPass→OutputPass 直通)
-    const bloomPass = this.composer.passes.find(p => p instanceof UnrealBloomPass)
-    if (bloomPass) bloomPass.enabled = tier.bloom
-  }
+  adaptQuality(fps: number): void { adaptQuality(this, fps) }
 
-  private applyPixelRatio(next: number): void {
-    this.renderer.setPixelRatio(next)
-    this.composer.setPixelRatio(next)
-    const w = this.el.clientWidth || 1100
-    const h = this.el.clientHeight || 700
-    this.renderer.setSize(w, h)
-    this.composer.setSize(w, h)
-  }
+  applyQuality(): void { applyQuality(this) }
+
+  applyPixelRatio(next: number): void { applyPixelRatio(this, next) }
 
   // ================================================================
   // 实例本地资源释放(防长会话 GPU 内存只涨不跌)
@@ -4484,98 +877,17 @@ export class TownScene3D {
   // 名牌/气泡的 CanvasTexture(材质 map)、状态环/链路等自建几何与材质。
 
   /** 释放对象树内所有 Canvas 纹理(名牌/气泡 sprite 的独占资源) */
-  private disposeCanvasTextures(root: THREE.Object3D | null): void {
-    if (!root) return
-    root.traverse((o) => {
-      const mesh = o as THREE.Mesh
-      const mat = mesh.material as THREE.Material | THREE.Material[] | undefined
-      const mats = Array.isArray(mat) ? mat : mat ? [mat] : []
-      for (const m of mats) {
-        const std = m as THREE.Material & { map?: THREE.Texture | null }
-        if (std.map && std.map.image instanceof HTMLCanvasElement) std.map.dispose()
-        m.dispose()
-      }
-    })
-  }
+  disposeCanvasTextures(root: THREE.Object3D | null): void { disposeCanvasTextures(root) }
 
   /** 释放单个设备节点的实例资源(状态环 + 运行弧 + LED 环 + 名牌) */
-  private disposeDeviceAssets(dev: DeviceNode): void {
-    dev.ring.geometry.dispose()
-    const rmat = dev.ring.material as THREE.Material & { map?: THREE.Texture | null }
-    rmat.dispose()
-    if (dev.arc) {
-      dev.arc.geometry.dispose()
-      ;(dev.arc.material as THREE.Material).dispose()
-    }
-    this.disposeCanvasTextures(dev.label)
-  }
+  disposeDeviceAssets(dev: DeviceNode): void { disposeDeviceAssets(dev) }
 
   /** 释放单个 agent 的实例资源(名牌/气泡纹理 + 光环 + 活动范围线几何;GLB 克隆不动) */
-  private disposeAgentAssets(a: { nameSprite?: THREE.Sprite | null, bubble?: THREE.Sprite | null, rangeLine?: THREE.Line | null, aura?: THREE.Group | null }): void {
-    this.disposeCanvasTextures(a.nameSprite ?? null)
-    this.disposeCanvasTextures(a.bubble ?? null)
-    a.rangeLine?.geometry.dispose()
-    if (a.aura) {
-      a.aura.traverse((o) => {
-        const m = o as THREE.Mesh
-        if (m.isMesh) {
-          m.geometry.dispose()
-          ;(m.material as THREE.Material).dispose()
-        }
-      })
-      a.aura = null
-    }
-  }
+  disposeAgentAssets(a: { nameSprite?: THREE.Sprite | null, bubble?: THREE.Sprite | null, rangeLine?: THREE.Line | null, aura?: THREE.Group | null }): void { disposeAgentAssets(a) }
 
   /** 重置全部(rebuild 用) */
-  private resetAll(): void {
-    for (const a of this.agents.values()) {
-      this.scene.remove(a.root)
-      if (a.nameSprite) this.scene.remove(a.nameSprite)
-      if (a.bubble) this.scene.remove(a.bubble)
-      if (a.rangeLine) this.scene.remove(a.rangeLine)
-      this.disposeAgentAssets(a)
-    }
-    for (const b of this.blocks.values()) {
-      this.scene.remove(b.platform)
-      this.scene.remove(b.padRing)
-      this.scene.remove(b.beacon)
-      this.scene.remove(b.boundary)
-      this.scene.remove(b.label)
-      this.disposeCanvasTextures(b.label)
-    }
-    for (const dev of this.deviceNodes.values()) {
-      this.scene.remove(dev.root)
-      this.scene.remove(dev.label)
-      this.disposeDeviceAssets(dev)
-    }
-    this.deviceNodes.clear()
-    this.scalables.clear()
-    this.receivers.clear()
-    this.pointerDrag = null
-    this.cancelRangeDraw()
-    this.selected = null
-    this.selectedChannel = null
-    for (const hl of this.resizeHandles) hl.mesh.visible = false
-    for (const hl of this.agentRangeHandles) hl.mesh.visible = false
-    this.agents.clear()
-    this.blocks.clear()
-  }
+  resetAll(): void { resetScene(this) }
 
   /** 销毁(卸载时由 TownView 调用) */
-  dispose(): void {
-    this.disposed = true
-    cancelAnimationFrame(this.raf)
-    delete (globalThis as { __townScene3d?: unknown }).__townScene3d
-    for (const t of this.pendingSaveTimers.values()) clearTimeout(t)
-    this.pendingSaveTimers.clear()
-    this.receivers.clear()
-    this.resizeOb?.disconnect()
-    this.resizeOb = null
-    this.tControls?.dispose()
-    this.tControls = null
-    this.composer?.dispose()
-    this.renderer.dispose()
-    if (this.renderer.domElement.parentElement === this.el) this.renderer.domElement.remove()
-  }
+  dispose(): void { disposeScene(this) }
 }