agentworkshop 0.7.44 → 0.7.46

package/app/components/workshop/town/scene/town-scene3d-selection.ts

@@ -0,0 +1,257 @@
+/**
+ * AgentTeam RPG 小镇(Three.js 3D 表现层)— 拾取 / 选中 / 缩放旋转 / 频道选中。
+ *
+ * 自 TownScene3D.ts 抽出(客制化:场景内点选 Agent/设备 → 弹滑杆调大小):
+ *  - pickBeacon / pickAt / pickChannel / pickChannelEdge:世界坐标命中判定;
+ *  - setSelected / getSelectedScale / registerScalable / persistScale:可缩放目标注册与滑杆;
+ *  - setModelScale / setModelRotation / getModelRotation:倍率与朝向;
+ *  - setTransformMode / isGizmoBusy:Blender 式变换手柄;
+ *  - setExposure / setTerritoryOpacity:环境光照与领地染色浓度;
+ *  - selectChannel / getSelectedChannel:频道选中(边界面板 + 边界高亮 + 聚焦)。
+ *
+ * 宿主契约:场景类实现 SelectionHost(只列本模块触达的成员)。
+ */
+import * as THREE from 'three'
+import type { TransformControls } from 'three/examples/jsm/controls/TransformControls.js'
+import { WORLD_CX, WORLD_CZ, pointInBoundary, toLocal } from '#shared/town-scene-math'
+import type { Agent3D, Block3D, DeviceNode } from './town-scene3d-nodes'
+import type { PointerDragState, ScaledTarget, SelectedTarget, TownEventMap, TownScene3DMode } from './town-scene3d-types'
+
+/** 拾取 / 选中模块的宿主契约(一项 = 本模块真正用到的字段/方法) */
+export interface SelectionHost {
+  readonly scene: THREE.Scene
+  readonly renderer: THREE.WebGLRenderer
+  readonly agents: Map<string, Agent3D>
+  readonly deviceNodes: Map<string, DeviceNode>
+  readonly blocks: Map<string, Block3D>
+  /** 场景内可缩放目标(Agent 或设备) */
+  readonly scalables: Map<string, ScaledTarget>
+  selected: SelectedTarget | null
+  /** 当前选中频道(供边界编辑面板) */
+  selectedChannel: string | null
+  readonly pointerDrag: PointerDragState
+  /** 框选绘制目标 agent(非空 = 编辑模式正在为该角色拉动矩形框) */
+  readonly rangeDrawAgent: string | null
+  readonly mode: TownScene3DMode
+  /** Blender 式变换手柄(选中设备) */
+  readonly tControls: TransformControls | null
+  /** 请求下一帧重绘 */
+  markDirty(): void
+  /** 场景 → Vue HUD 事件 */
+  emit<K extends keyof TownEventMap>(event: K, e: TownEventMap[K]): void
+  /** 退出框选绘制模式(清理预览与状态) */
+  cancelRangeDraw(): void
+  /** 同步全部范围线框可见性 */
+  refreshAgentRangeLines(): void
+  /** 刷新 Agent 活动范围手柄 */
+  refreshAgentRangeHandles(): void
+  /** 刷新边界手柄位置/可见性 */
+  refreshChannelHandles(): void
+  /** 缓动聚焦某世界点 */
+  focusTo(x: number, z: number): void
+  /** 持久化设备 transform(防抖) */
+  persistDeviceTransform(id: string): void
+}
+
+/** 命中频道信标(中心 ±34 单位;点击信标 = 定位中心 + 唤醒边界编辑,任何模式) */
+export function pickBeacon(host: SelectionHost, x: number, z: number): { cid: string, x: number, z: number } | null {
+  for (const b of host.blocks.values()) {
+    if (Math.hypot(b.x - x, b.z - z) < 34) return { cid: b.channelId, x: b.x, z: b.z }
+  }
+  return null
+}
+
+/** 以世界坐标 hit 一个 Agent 或设备节点(近似距离阈值;供点击选中) */
+export function pickAt(host: SelectionHost, 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 host.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 host.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
+}
+
+/** 点选频道:返回包含该点的频道 id(边界内;供编辑模式打开边界编辑面板) */
+export function pickChannel(host: SelectionHost, x: number, z: number): string | null {
+  for (const b of host.blocks.values()) {
+    const layout = {
+      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
+}
+
+/** 命中频道边界线(世界点落在某领地边界带 ±42 单位内 → 边界拖拽等比缩放)。 */
+export function pickChannelEdge(host: SelectionHost, x: number, z: number): { cid: string, rx0: number, rz0: number, rd0: number } | null {
+  for (const b of host.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
+}
+
+/** 设置选中(点击后由 Vue 弹缩放/旋转滑杆) */
+export function setSelected(host: SelectionHost, sel: { kind: 'agent' | 'device', id: string } | null): void {
+  // 选中切换/取消 → 退出框选绘制(清理预览)
+  if (!sel || sel.kind !== 'agent' || sel.id !== host.rangeDrawAgent) host.cancelRangeDraw()
+  host.selected = sel
+  // 变换手柄跟随选中设备(Blender 规范:选中即出手柄;运行模式只读 → 不出手柄)
+  if (host.tControls) {
+    if (sel?.kind === 'device' && host.mode === 'edit' && host.deviceNodes.has(sel.id)) host.tControls.attach(host.deviceNodes.get(sel.id)!.root)
+    else host.tControls.detach()
+  }
+  host.refreshAgentRangeLines()
+  host.refreshAgentRangeHandles()
+  if (!sel) {
+    host.emit('select', null)
+    return
+  }
+  const st = host.scalables.get(`${sel.kind}:${sel.id}`)
+  if (st) {
+    host.emit('select', {
+      kind: sel.kind,
+      id: sel.id,
+      scale: st.userScale,
+      rotation: Math.round(getModelRotation(host, sel.id, sel.kind) * 10) / 10,
+    })
+  }
+}
+
+/** 场景内缩放:为 Agent(id)或设备(id)设定用户缩放倍率(0.2~5;1=默认归一化) */
+export function setModelScale(host: SelectionHost, id: string, scale: number, kind?: 'agent' | 'device'): void {
+  const k = kind ?? (host.scalables.has(`device:${id}`) ? 'device' : 'agent')
+  const key = `${k}:${id}`
+  const st = host.scalables.get(key)
+  if (!st) return
+  st.userScale = scale
+  // 施加于模型 holder(相对已归一化的默认尺寸)
+  st.holder.scale.setScalar(st.userScale)
+  if (k === 'device') {
+    const dev = host.deviceNodes.get(id)
+    if (dev) dev.topYCache = null
+  }
+  host.markDirty()
+}
+
+/** 当前选中对象(供 Vue/滑杆初始化) */
+export function getSelectedScale(host: SelectionHost): { kind: 'agent' | 'device', id: string, scale: number, rotation: number } | null {
+  if (!host.selected) return null
+  const st = host.scalables.get(`${host.selected.kind}:${host.selected.id}`)
+  if (!st) return null
+  return {
+    kind: host.selected.kind,
+    id: host.selected.id,
+    scale: st.userScale,
+    rotation: Math.round(getModelRotation(host, host.selected.id, host.selected.kind) * 10) / 10,
+  }
+}
+
+/** 组装可缩放目标并恢复初始化缩放(initialScale 优先=服务端持久化;否则 localStorage) */
+export function registerScalable(host: SelectionHost, 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
+  host.scalables.set(`${kind}:${id}`, { kind, id, userScale, holder })
+  holder.scale.setScalar(userScale)
+  if (kind === 'device') {
+    const dev = host.deviceNodes.get(id)
+    if (dev) dev.topYCache = null
+  }
+}
+
+/** 持久化指定对象的缩放(滑杆松手时调用;设备同时落库,角色仅本地) */
+export function persistScale(host: SelectionHost, kind: 'agent' | 'device', id: string): void {
+  const st = host.scalables.get(`${kind}:${id}`)
+  if (!st || typeof localStorage === 'undefined') return
+  localStorage.setItem(`town.scale.${kind}:${id}`, String(st.userScale))
+  if (kind === 'device') host.persistDeviceTransform(id)
+}
+
+/** 对象朝向(度;编辑模式旋转滑杆实时) */
+export function setModelRotation(host: SelectionHost, id: string, deg: number, kind?: 'agent' | 'device'): void {
+  const k = kind ?? (host.deviceNodes.has(id) ? 'device' : 'agent')
+  if (k === 'device') {
+    const dev = host.deviceNodes.get(id)
+    if (!dev) return
+    dev.root.rotation.y = deg * Math.PI / 180
+  }
+  else {
+    const asp = host.agents.get(id)
+    if (!asp) return
+    asp.root.rotation.y = deg * Math.PI / 180
+  }
+  host.markDirty()
+}
+
+export function getModelRotation(host: SelectionHost, id: string, kind?: 'agent' | 'device'): number {
+  const k = kind ?? (host.deviceNodes.has(id) ? 'device' : 'agent')
+  if (k === 'device') {
+    const dev = host.deviceNodes.get(id)
+    return dev ? THREE.MathUtils.radToDeg(dev.root.rotation.y) : 0
+  }
+  const asp = host.agents.get(id)
+  return asp ? THREE.MathUtils.radToDeg(asp.root.rotation.y) : 0
+}
+
+/** 变换模式(Blender 规范):translate=移动 G / rotate=旋转 R / scale=缩放 S。
+ *  轴约束:移动仅 XZ(模型贴地),旋转仅 Y(2.5D 朝向),缩放 XYZ。 */
+export function setTransformMode(host: SelectionHost, mode: 'translate' | 'rotate' | 'scale'): void {
+  if (!host.tControls) return
+  host.tControls.setMode(mode)
+  host.tControls.showX = mode !== 'rotate'
+  host.tControls.showY = mode !== 'translate'
+  host.tControls.showZ = mode !== 'rotate'
+}
+
+/** 手柄是否悬停/拖拽中(调用方应让出相机平移与点选) */
+export function isGizmoBusy(host: SelectionHost): boolean {
+  return !!host.tControls && (host.tControls.dragging || !!host.tControls.axis)
+}
+
+/** 渲染曝光(场景控制坞"环境光照";0.2~2.2) */
+export function setExposure(host: SelectionHost, v: number): void {
+  host.renderer.toneMappingExposure = Math.min(2.2, Math.max(0.2, v))
+}
+
+/** 领地染色浓度(平台透明度系数;0.05~1) */
+export function setTerritoryOpacity(host: SelectionHost, v: number): void {
+  const o = Math.min(1, Math.max(0.05, v))
+  for (const b of host.blocks.values()) {
+    ;(b.platform.material as THREE.MeshStandardMaterial).opacity = 0.24 * o
+  }
+  host.markDirty()
+}
+
+/** 点选频道(供频道坞/边界编辑面板打开) */
+export function selectChannel(host: SelectionHost, channelId: string | null): void {
+  host.selectedChannel = channelId
+  host.emit('selectChannel', channelId)
+  host.refreshChannelHandles()
+  host.cancelRangeDraw()
+  host.refreshAgentRangeHandles()
+  // 选中频道边界高亮勾边(取消时恢复频道本色)
+  for (const bb of host.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 && !host.pointerDrag) host.focusTo(host.blocks.get(channelId)?.x ?? WORLD_CX, host.blocks.get(channelId)?.z ?? WORLD_CZ)
+}
+
+/** 频道是否在场景内且被选中(供边界编辑面板) */
+export function getSelectedChannel(host: SelectionHost): string | null {
+  return host.selectedChannel
+}

package/app/components/workshop/town/scene/town-scene3d-types.ts

@@ -0,0 +1,264 @@
+/**
+ * AgentTeam RPG 小镇(Three.js 3D 表现层)— 类型契约与常量。
+ *
+ * 自 TownScene3D.ts 抽出,承载「零行为」的声明:
+ *  - 场景 → Vue HUD 事件映射(TownEventMap)、编辑模式、设备 transform 补丁;
+ *  - 实体基线 / 设备孪生同步输入(TownEntityInput / DeviceTwinSync);
+ *  - 面向对象节点的宿主契约(TownSceneHost):Block3D / Agent3D / DeviceNode 只依赖此接口,
+ *    由 TownScene3D 实现(方法级解耦,节点可在独立模块中实例化与测试)。
+ */
+import type * as THREE from 'three'
+import type { AgentRangeLayout, ChannelLayout } from '#shared/town-scene-math'
+import type { TownBubbleKind } from '#shared/town-protocol'
+import type { ActionKind } from '#shared/town-behavior'
+
+/** 场景 → 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 或设备节点) */
+export interface ScaledTarget {
+  kind: 'agent' | 'device'
+  id: string
+  /** 用户缩放倍率(1 = 默认归一化尺寸) */
+  userScale: number
+  /** 模型子节点(缩放施加于此) */
+  holder: THREE.Group
+}
+
+/** 场景内当前选中目标(kind:id;供缩放/旋转滑杆与选中高亮环) */
+export type SelectedTarget = { kind: 'agent' | 'device', id: string }
+
+/** 编辑模式正在拖曳的场景对象(设备 / 角色落点 / 频道整体 / 边界手柄 / Agent 活动范围) */
+export type PointerDragState
+  = | { 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
+
+/** 边界缩放手柄(编辑模式选中频道时显示;拖拽手柄调整 radiusX/radiusZ) */
+export interface ChannelResizeHandle { mesh: THREE.Mesh, cid: string, handle: number }
+
+/** Agent 活动范围缩放手柄(编辑模式选中带范围角色时显示;拖拽调整该 Agent 范围大小) */
+export interface AgentRangeHandle { mesh: THREE.Mesh, agentId: string, handle: number }
+
+/** 一条已建成的数采→设备绑定链路(虚线 + 流动脉冲;curve 端点位移时重建) */
+export interface DaqLink {
+  daqId: string
+  deviceId: string
+  line: THREE.Line
+  pulse: THREE.Mesh
+  curve: THREE.QuadraticBezierCurve3
+  pt: number
+  ptSig: string
+}
+
+/** 数字孪生设备 API(由 TownView 注入 useDeviceTwins 适配器;拖 dev 模型进场景时创建设备) */
+export interface DeviceApi {
+  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>
+}
+
+/** 与 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
+  }>
+}
+
+/** 频道布局(3D 小镇放置):与共享 AepSceneLayout/useSceneLayouts 同构 —— 定义见 #shared/town-scene-math */
+
+/** Agent 独立活动范围(编辑模式框选绘制/手柄调整;经 config.range 持久化)。
+ *  缺省(null)= 未设置,该 Agent 沿用频道边界活动。 —— 定义见 #shared/town-scene-math */
+
+/** 行为状态机(标准 AI 控制:事件→决策→动作) */
+export type BehaviorMode
+  = | 'idle'
+    | 'roam'
+    | 'approach'
+    | 'wait'
+    | 'returnHome'
+
+export 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 逐条消费) */
+export interface BubbleMsg {
+  /** 说话 Agent(null = 频道级/系统气泡) */
+  agentId: string | null
+  kind: TownBubbleKind
+  text: string
+  ttlMs: number
+}
+
+/** 每个实例化 Channel 的信息接收器:WS 实时信息经 handleTownEvent 入队,FIFO 逐条消费渲染到对应 Agent 头顶 */
+export interface ChannelMessageReceiver {
+  channelId: string
+  queue: BubbleMsg[]
+  current: BubbleMsg | null
+  currentUntil: number
+}
+
+/** 世界尺度/速度/身份色等纯常量与函数集中定义于 #shared/town-scene-math(与 2D/测试共用) */
+
+/** 角色模型来源登记(registerModelsFromList) */
+export interface ModelInfo { id: string, file: string, name: string, kind?: string, hFactor?: number }
+
+/** 频道领地布局最小形状(宿主 trackLayout 入参;Block3D 天然满足) */
+export interface BlockLayoutCarrier {
+  channelId: string
+  x: number
+  z: number
+  radiusX: number
+  radiusZ: number
+  shape: 'ellipse' | 'rect'
+  rotationY: number
+}
+
+/** 节点必须由宿主提供的服务(形状契约,避免 类型 ↔ 节点 循环依赖) */
+export interface BlockHost {
+  /** 场景根(节点挂载/摘除线框) */
+  readonly threeScene: THREE.Scene
+  /** 请求下一帧重绘 */
+  markDirty(): void
+  /** 登记频道布局变更(拖拽/边界调整后落库路径) */
+  trackLayout(b: BlockLayoutCarrier): void
+}
+
+export interface AgentHost {
+  /** 场景根(节点挂载/摘除线框与气泡) */
+  readonly threeScene: THREE.Scene
+  /** 请求下一帧重绘 */
+  markDirty(): void
+  /** 某频道的当前布局(未放置 = null);Agent 漫游/钳制的边界来源 */
+  blockLayoutOf(channelId: string): ChannelLayout | null
+  /** 按 agentId 取场景角色实例 */
+  getAgent(agentId: string): AgentNodeHost | undefined
+  /** 行为送达(在目标头顶弹气泡 + 广播行为日志) */
+  deliverBehavior(asp: AgentNodeHost, target: AgentNodeHost): void
+  /** 释放被本角色邀请(engaged)的目标 */
+  releaseEngaged(asp: AgentNodeHost): void
+  /** 动画状态切换广播(idle/walk) */
+  notifyMotion(asp: AgentNodeHost): void
+  /** 活动范围线框是否可见(范围绘制/选中的可见性策略) */
+  rangeLineVisibleFor(asp: AgentNodeHost): boolean
+}
+
+export interface DeviceHost {
+  /** 请求下一帧重绘 */
+  markDirty(): void
+  /** 设备名牌重建(改名) */
+  renameDeviceSprite(dev: DeviceNodeLike, name: string): void
+  /** 设备模型重挂(换模型) */
+  swapDeviceModelSprite(dev: DeviceNodeLike, modelRef: string): void
+}
+
+/** Agent3D 最小形状(宿主行为回调需要读落点/名称/行为态) */
+export interface AgentNodeHost {
+  agentId: string
+  name: string
+  root: THREE.Group
+  homeX: number
+  homeZ: number
+  channelId: string
+  dragging: boolean
+  behavior: BehaviorState
+  range: AgentRangeLayout | null
+  rangeLine: THREE.LineLoop | null
+}
+
+/** DeviceNode 最小形状(宿主名牌/模型重挂入参) */
+export interface DeviceNodeLike {
+  twinId: string
+  name: string
+  modelRef: string
+  root: THREE.Group
+  holder: THREE.Group
+  ring: THREE.Mesh
+  arc: THREE.Mesh | null
+  state: 'idle' | 'running' | 'offline' | 'alarm'
+}
+
+/**
+ * 场景宿主契约(节点侧聚合):TownScene3D 实现本接口,
+ * 保证节点所依赖的服务齐备(缺一即编译期报错)。
+ */
+export interface TownSceneHost extends BlockHost, AgentHost, DeviceHost {}

package/app/components/workshop/transcript/TranscriptBlockList.vue

@@ -0,0 +1,68 @@
+<script setup lang="ts">
+/**
+ * 时间线块流:日期分隔线 + workshop-event-block 列表(v-for 整体搬入)。
+ * 纯呈现:`blocks`(增量聚类结果)与 `staged`(进场编排映射)由容器传入。
+ * 日期分隔线的计算随标记一起搬来(块 firstAt 跨日 → 插入 hairline 分隔;
+ * .date-divider / .date-divider-label 是 main.css 里的全局规则,故此处无需 scoped 样式)。
+ */
+import type { EventBlock } from '@/app/composables/workshop/useEventBlocks'
+import type { TranscriptEnterStage } from '@/app/composables/workshop/useTranscriptEnterStage'
+
+const props = defineProps<{
+  /** 聚类后的块流(与容器 v-for 同源) */
+  blocks: EventBlock[]
+  /** blockId → 进场延迟映射(useTranscriptEnterStage) */
+  staged: Map<string, TranscriptEnterStage>
+}>()
+
+const { t } = useI18n()
+
+// ===== 日期分隔线(open-tag date-divider 移植):块 firstAt 跨日 → 插入 hairline 分隔 =====
+const startOfDay = (iso: string): number => {
+  const d = new Date(iso)
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+}
+const dayLabel = (iso: string): string => {
+  const d = new Date(iso)
+  const today = new Date()
+  const yesterday = new Date()
+  yesterday.setDate(today.getDate() - 1)
+  const sameDay = (a: Date, b: Date) =>
+    a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate()
+  if (sameDay(d, today)) return t('transcriptTimeline.k3wcqg018')
+  if (sameDay(d, yesterday)) return t('transcriptTimeline.k40l1y019')
+  const y = d.getFullYear() !== today.getFullYear() ? t('transcriptTimeline.k2hda35028', { p0: d.getFullYear() }) : ''
+  return t('transcriptTimeline.kbs29zx029', { p0: y, p1: d.getMonth() + 1, p2: d.getDate() })
+}
+/** 每个块是否需要前置日界分隔(与上一块不同日,或首块) */
+const blockDayFlags = computed(() => {
+  const flags: Array<{ divider: string | null }> = []
+  let prevDay: number | null = null
+  for (const b of props.blocks) {
+    const day = startOfDay(b.firstAt)
+    flags.push({ divider: prevDay === null || day !== prevDay ? dayLabel(b.firstAt) : null })
+    prevDay = day
+  }
+  return flags
+})
+</script>
+
+<template>
+  <template
+    v-for="(b, i) in blocks"
+    :key="b.id"
+  >
+    <div
+      v-if="blockDayFlags[i]?.divider"
+      class="date-divider"
+    >
+      <span class="date-divider-label">{{ blockDayFlags[i]!.divider }}</span>
+    </div>
+    <workshop-event-block
+      :block="b"
+      :turn-start="i > 0 && blocks[i - 1]!.agentId !== b.agentId"
+      :compact="i > 0 && blocks[i - 1]!.agentId === b.agentId"
+      :enter-stage="staged.get(b.id)"
+    />
+  </template>
+</template>

package/app/components/workshop/transcript/TranscriptEarlierPager.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+/**
+ * 时间线列首的历史翻页区:「加载更早」按钮 + 触底提示。
+ * 纯呈现:loading / exhausted 由 TranscriptTimeline 的 useTranscriptHistory 持有,
+ * 点击只上抛 load 事件(锚定与探底逻辑在容器侧)。
+ */
+defineProps<{
+  /** 还可能存在更早历史(粗判;false 时按钮不渲染) */
+  visible: boolean
+  /** 本页拉取中(按钮禁用 + 文案切换) */
+  loading: boolean
+  /** 已确认没有更早历史 */
+  exhausted: boolean
+  /** 已加载事件数(为 0 时不显示"已到最早") */
+  loadedCount: number
+}>()
+
+const emit = defineEmits<{
+  load: []
+}>()
+</script>
+
+<template>
+  <button
+    v-if="visible"
+    class="earlier-btn"
+    :disabled="loading"
+    @click="emit('load')"
+  >
+    {{ loading ? $t('transcriptTimeline.k1br0ij9009') : $t('transcriptTimeline.kywgd38021') }}
+  </button>
+  <div
+    v-if="exhausted && loadedCount > 0"
+    class="earlier-done"
+  >
+    {{ $t('transcriptTimeline.k1kbaden003') }}
+  </div>
+</template>
+
+<style scoped>
+.earlier-btn {
+  display: block;
+  margin: 0 auto 10px;
+  padding: 4px 14px;
+  font-family: var(--font-body);
+  font-size: 11px;
+  color: var(--ink-faint);
+  cursor: pointer;
+  background: var(--paper-raised);
+  border: 1px solid var(--line-strong);
+  border-radius: var(--radius-pill);
+  transition: background var(--transition-fast), color var(--transition-fast);
+}
+.earlier-btn:hover:not(:disabled) {
+  color: var(--ink);
+  background: var(--paper-deep);
+}
+.earlier-btn:disabled { opacity: 0.5; cursor: default; }
+.earlier-done {
+  margin-bottom: 8px;
+  font-family: var(--font-mono);
+  font-size: 9.5px;
+  text-align: center;
+  color: var(--ink-faint);
+}
+
+/* ── 窄屏(≤1023):字号与触控高度对齐过滤条 ── */
+@media (max-width: 1023.98px) {
+  /* 与 transcript/TranscriptFilterBar.vue 的 `.count, .sync-chip` 原为同一条选择器列表
+     —— 有意重复,改一处同步所有副本。 */
+  .earlier-done {
+    font-size: 11.5px;
+  }
+
+  /* 与容器 .jump-latest 原共用一条 min-height 规则 —— 有意重复,改一处同步所有副本
+     (副本:workshop/TranscriptTimeline.vue 的同名媒体查询块)。 */
+  .earlier-btn {
+    min-height: 40px;
+  }
+}
+</style>