agentworkshop 0.2.1

package/shared/town-anim.ts

@@ -0,0 +1,56 @@
+/**
+ * town-anim —— 角色模型 → 动画状态映射(纯函数,零 Phaser,可单测)。
+ *
+ * 让「内置员工模型」与「自定义上传模型」走同一套动画接口:
+ *  - resolveAnimDef(textureKey, model) → 依模型帧布局给出 idle/walk/work 的帧区间与帧率。
+ *  - 约定:模型若声明 anims 就用之;否则回退默认(4 帧悬停 bob = 全部帧循环)。
+ *  - 供 TownScene 在 registerModelFromId / createAnimations / swapTexture 统一取帧。
+ */
+
+/** 一个动画状态的定义 */
+export interface AnimDef {
+  key: string
+  /** 起止帧号(含 end) */
+  start: number
+  end: number
+  frameRate: number
+  /** 是否循环 */
+  repeat: number
+}
+
+/** 模型帧布局声明(与 CharacterAsset.sheet/anims 对齐) */
+export interface ModelAnimSpec {
+  frameWidth?: number
+  frameHeight?: number
+  frames?: number
+  /** 各状态帧覆盖;缺省按默认整表循环 */
+  anims?: Partial<Record<'idle' | 'walk' | 'work', { start: number, count: number, frameRate?: number }>>
+}
+
+/** 默认悬停 bob(与内置 wu-* 一致):全部帧循环 */
+const DEFAULT_BOB = { start: 0, end: 3, frameRate: 3, repeat: -1 }
+
+/** 解析某纹理 key 对应的动画定义(idle/walk/work)。缺省给悬停 bob。 */
+export function resolveAnimDef(textureKey: string, spec?: ModelAnimSpec): Record<'idle' | 'walk' | 'work', AnimDef> {
+  const mk = (state: 'idle' | 'walk' | 'work'): AnimDef => {
+    const a = spec?.anims?.[state]
+    if (!a) {
+      // 默认:无状态覆盖 → 整表循环(悬停 bob),区分 idle 慢、walk 中间、work 快
+      const rate = state === 'idle' ? DEFAULT_BOB.frameRate : state === 'work' ? 8 : 5
+      return { key: `${textureKey}-${state}`, start: 0, end: DEFAULT_BOB.end, frameRate: rate, repeat: -1 }
+    }
+    return {
+      key: `${textureKey}-${state}`,
+      start: a.start,
+      end: a.start + (a.count || 1) - 1,
+      frameRate: a.frameRate ?? 6,
+      repeat: -1,
+    }
+  }
+  return { idle: mk('idle'), walk: mk('walk'), work: mk('work') }
+}
+
+/** 便捷:是否已声明多状态(否则仅悬停 bob) */
+export function hasMultiState(spec?: ModelAnimSpec): boolean {
+  return Boolean(spec?.anims)
+}

package/shared/town-behavior.ts

@@ -0,0 +1,136 @@
+/**
+ * TownBehavior — 小镇 AI 角色行为纯决策层。
+ *
+ * 标准 AI 控制游戏架构的事件 → 决策 → 动作链的「决策」部分:
+ *  - parseActionFromEnvelope(e):AEP 通信/任务事件 → ActionContext(发送方/接收方/类型/是否等待回复)。
+ *    纯函数,零 Phaser 依赖,可单测。
+ *  - stepToward(cur, target, speed, dt):匀速移动一步,返回下一个位置 + 是否到达 + 朝向。
+ *    物理运动由场景执行,这里只做确定性步进计算(可单测)。
+ *
+ * ActionContext 语义:
+ *  - sender(发送方)需跑到 recipient(接收方)身边「下发」;
+ *  - 若 requireReply 或 kind=task → sender 在接收方附近「等待回复/执行结果」;
+ *  - 否则送达即返回。
+ */
+import type { AepEnvelope } from './workshop-protocol'
+
+/** 行为动作类别 */
+export type ActionKind = 'task' | 'message' | 'reply'
+
+/** 一次「跑去对面下发/通信」的上下文 */
+export interface ActionContext {
+  channelId: string
+  /** 发送方(sender 跑去 recipient 身边) */
+  fromId: string
+  /** 接收方(recipient) */
+  toId: string
+  kind: ActionKind
+  /** 任务类投递(assign/cancel/child-completed 等) */
+  taskKind?: string
+  /** 是否需要等待回复(require_reply) */
+  requireReply: boolean
+  /** 下发/通信文本(bubble 内容) */
+  text: string
+}
+
+/** 一帧 AEP 的文本(与 town-protocol.partsToText 同口径) */
+function partsToText(parts: Array<{ text?: string } | { data?: unknown }>): string {
+  return parts
+    .map(p => 'text' in p ? (p.text ?? '') : 'data' in p ? JSON.stringify(p.data) : '')
+    .join('\n')
+    .trim()
+}
+
+/**
+ * 从 AEP 信封解析出行为动作。
+ * 命中「点对点通信/任务投递」类事件才返回;未命中返回 null。
+ * 依赖 metadata 的 from/target/task-kind/require-reply 字段(与 service 层投递契约一致)。
+ *
+ * 注意:mock harness 的任务投递消息 metadata 只带 x-aw-task-kind + x-aw-from-agent,
+ * 收件方由 route 从任务的 assigneeId 解析,x-aw-target-agent 可能缺省。
+ * 因此传入 opts.resolveTaskAssignee 用于任务类消息按 taskId 反查收件方。
+ */
+export function parseActionFromEnvelope(
+  e: AepEnvelope,
+  opts?: { resolveTaskAssignee?: (taskId: string) => string | null },
+): ActionContext | null {
+  switch (e.type) {
+    case 'a2a.message': {
+      const msg = e.payload as { parts?: Array<{ text?: string } | { data?: unknown }>, metadata?: Record<string, unknown>, contextId?: string }
+      const meta = msg.metadata ?? {}
+      const fromId = typeof meta['x-aw-from-agent'] === 'string' ? meta['x-aw-from-agent'] as string : (e.agentId ?? '')
+      let toId = typeof meta['x-aw-target-agent'] === 'string' ? meta['x-aw-target-agent'] as string : ''
+      const taskKind = typeof meta['x-aw-task-kind'] === 'string' ? meta['x-aw-task-kind'] as string : undefined
+      const taskId = typeof meta['x-aw-task-id'] === 'string' ? meta['x-aw-task-id'] as string : (e.taskId ?? '')
+      // 任务投递缺 target-agent 时按 taskId 反查 assignee
+      if (!toId && taskKind && taskId && opts?.resolveTaskAssignee) {
+        toId = opts.resolveTaskAssignee(taskId) ?? ''
+      }
+      // 消息类事件必须有明确收件方,否则无法驱动「跑去下发」
+      if (!toId) return null
+      const requireReply = meta['x-aw-require-reply'] === 'true' || taskKind === 'assign'
+      const text = partsToText(msg.parts ?? [])
+      const kind: ActionKind = taskKind ? 'task' : 'message'
+      return {
+        channelId: e.channelId,
+        fromId,
+        toId,
+        kind,
+        taskKind,
+        requireReply,
+        text: text || (taskKind === 'assign' ? '下发任务' : '发送消息'),
+      }
+    }
+    case 'agent.message': {
+      const msg = e.payload as { parts?: Array<{ text?: string } | { data?: unknown }>, metadata?: Record<string, unknown> }
+      const meta = msg.metadata ?? {}
+      const fromId = e.agentId ?? ''
+      const toId = typeof meta['x-aw-target-agent'] === 'string' ? meta['x-aw-target-agent'] as string : ''
+      if (!toId) return null
+      const requireReply = meta['x-aw-require-reply'] === 'true'
+      return {
+        channelId: e.channelId,
+        fromId,
+        toId,
+        kind: 'message',
+        requireReply,
+        text: partsToText(Array.isArray(msg.parts) ? msg.parts : []),
+      }
+    }
+    default:
+      return null
+  }
+}
+
+/** 到达判定距离(px;两个角色的 arcade body 约 12~14px 宽 + 间距,需略大于 body 尺寸,
+ *  否则角色被彼此 body 挡住,卡在"就差 1~2px"的位置永远到不了,呈停滞 approach) */
+export const ARRIVE_DIST = 48
+
+/**
+ * 匀速移动一步:从 cur 朝 target 前进 speed*dt 像素。
+ * 返回下一个位置、是否到达、水平朝向(供 sprite flip)。
+ */
+export function stepToward(
+  cur: { x: number, y: number },
+  target: { x: number, y: number },
+  speed: number,
+  dt: number,
+): { x: number, y: number, arrived: boolean, dir: 'left' | 'right' | 'none' } {
+  const dx = target.x - cur.x
+  const dy = target.y - cur.y
+  const dist = Math.hypot(dx, dy)
+  const dir: 'left' | 'right' | 'none' = dx < -1 ? 'left' : dx > 1 ? 'right' : 'none'
+  if (dist <= ARRIVE_DIST || dist === 0) {
+    return { x: cur.x, y: cur.y, arrived: true, dir }
+  }
+  const stepLen = speed * dt
+  if (stepLen >= dist) {
+    return { x: target.x, y: target.y, arrived: true, dir }
+  }
+  return {
+    x: cur.x + (dx / dist) * stepLen,
+    y: cur.y + (dy / dist) * stepLen,
+    arrived: false,
+    dir,
+  }
+}

package/shared/town-protocol.ts

@@ -0,0 +1,110 @@
+/**
+ * 小镇事件语义映射(AEP → 可渲染指令)。
+ *
+ * 纯函数,零 Phaser 依赖:把 workshop 的 AEP 信封翻译成小镇场景能消费的
+ * 渲染意图(spawn/update agent、头顶气泡、进度更新、错误警示)。让
+ * TownScene 保持"只渲染"的单一职责,映射逻辑可独立单测。
+ */
+import type { AepEnvelope } from './workshop-protocol'
+import type { A2AArtifact } from '../server/services/workshop/types/a2a'
+
+/** 气泡种类:决定气泡外观(信息/交付/错误/系统) */
+export type TownBubbleKind = 'info' | 'artifact' | 'error' | 'system'
+
+/** 可直接渲染的头顶气泡意图 */
+export interface TownBubble {
+  channelId: string
+  /** 气泡归属 agent(空 = 广播/系统气泡,挂在街区入口) */
+  agentId?: string
+  kind: TownBubbleKind
+  text: string
+  /** 气泡存活时长 ms */
+  ttlMs: number
+}
+
+/** 一帧 AEP 的事件意图(命中才返回;未命中返回 null) */
+export interface TownEventIntent {
+  channelId: string
+  /** 需要刷新进度/状态的目标 agent(可能为 'system' 或空) */
+  agentId?: string
+  bubble?: TownBubble
+}
+
+/** Part → 纯文本(与 useEventBlocks.textOf 同口径,供气泡/交付物预览) */
+function partsToText(parts: Array<{ text?: string } | { data?: unknown }>): string {
+  return parts
+    .map(p => 'text' in p ? (p.text ?? '') : 'data' in p ? JSON.stringify(p.data) : '')
+    .join('\n')
+    .trim()
+}
+
+const truncate = (s: string, n: number): string => (s.length > n ? `${s.slice(0, n)}…` : s)
+
+/** 交付物名(缺省用任务短 id) */
+function artifactName(a: A2AArtifact): string {
+  return a.name?.trim() ? a.name : (a.artifactId ?? '').slice(0, 6)
+}
+
+/** 事件 → 气泡意图(命中 TODO 展示类事件才产生气泡) */
+export function eventToBubble(e: AepEnvelope): TownBubble | null {
+  switch (e.type) {
+    case 'agent.message': {
+      const msg = e.payload as { parts?: Array<{ text?: string }> }
+      const t = partsToText(msg.parts ?? [])
+      return t ? { channelId: e.channelId, agentId: e.agentId, kind: 'info', text: truncate(t, 220), ttlMs: 3600 } : null
+    }
+    case 'agent.status.message': {
+      const text = String((e.payload as { text?: string }).text ?? '')
+      if (!text) return null
+      return { channelId: e.channelId, agentId: e.agentId, kind: 'info', text: truncate(text, 220), ttlMs: 2600 }
+    }
+    case 'a2a.message': {
+      const msg = e.payload as { parts?: Array<{ text?: string }> }
+      const t = partsToText(msg.parts ?? [])
+      return t ? { channelId: e.channelId, agentId: e.agentId, kind: 'info', text: truncate(t, 200), ttlMs: 3200 } : null
+    }
+    case 'a2a.artifact': {
+      const p = e.payload as { artifact?: A2AArtifact }
+      const a = p?.artifact
+      if (!a) return null
+      const body = partsToText((a.parts ?? []) as Array<{ text?: string } | { data?: unknown }>)
+      return {
+        channelId: e.channelId,
+        agentId: e.agentId,
+        kind: 'artifact',
+        text: `交付「${artifactName(a)}」${body ? ` · ${truncate(body, 120)}` : ''}`,
+        ttlMs: 3200,
+      }
+    }
+    case 'error': {
+      const p = e.payload as { code?: string, message?: string }
+      return { channelId: e.channelId, agentId: e.agentId, kind: 'error', text: `⚠ ${p.code ?? 'ERROR'} ${truncate(p.message ?? '', 160)}`, ttlMs: 4200 }
+    }
+    default:
+      return null
+  }
+}
+
+/**
+ * 主入口:一帧 AEP → 事件意图。
+ * 负责:更新类事件标记 agentId;展示类事件生成气泡;task.progress 单独由
+ * 场景从 entities 读进度(此处只回传 agentId 让场景刷新进度环)。
+ */
+export function mapEnvelopeToIntent(e: AepEnvelope): TownEventIntent | null {
+  const bubble = eventToBubble(e)
+  switch (e.type) {
+    case 'agent.status':
+    case 'agent.member':
+    case 'task.status':
+    case 'task.progress':
+      return { channelId: e.channelId, agentId: e.agentId, bubble: bubble ?? undefined }
+    case 'agent.message':
+    case 'agent.status.message':
+    case 'a2a.message':
+    case 'a2a.artifact':
+    case 'error':
+      return { channelId: e.channelId, agentId: e.agentId, bubble: bubble ?? undefined }
+    default:
+      return null
+  }
+}

package/shared/town-scene-math.ts

@@ -0,0 +1,283 @@
+/**
+ * TownSceneMath — 小镇场景的纯几何/色彩决策层(零渲染依赖,可单测)。
+ *
+ * 从 TownScene3D 抽离的纯函数集:边界几何(椭圆/矩形 + rotationY)、点钳制、
+ * 活动范围收敛、身份色哈希。2D/3D 场景与测试共用同一实现,避免答案分叉。
+ *
+ * 约定:3D 世界用 x/z 平面(y 向上,地面 y=0);2D 世界用 x/y 平面等价映射。
+ * 边界围绕中心 (x,z);radiusX/radiusZ 表示椭圆半轴或矩形半宽,rotationY(度)绕纵轴。
+ */
+import type { AepEnvelope } from './workshop-protocol'
+
+// ================================================================
+// 世界尺度(与 2D 对齐:3200×2400,3D 用 x/z 平面,y 向上)
+// ================================================================
+
+export const WORLD_W = 3200
+export const WORLD_H = 2400
+export const WORLD_CX = WORLD_W / 2
+export const WORLD_CZ = WORLD_H / 2
+/** 地面 y=0,Agent 站立于其上 */
+export const GROUND_Y = 0
+/** GLB 归一化到该高度(世界单位,角色要清晰可读) */
+export const UNITS = 120
+export const AGENT_SPEED = 96
+export const WAIT_MS = 2600
+export const ARRIVE = 48
+/** 编辑拖拽网格吸附粒度(世界单位) */
+export const SNAP_SIZE = 16
+/** 聊天气泡悬挂高度(世界单位;角色头顶名牌上方,随模型缩放微调) */
+export const BUBBLE_Y = 86
+
+// ================================================================
+// 布局类型(频道领地 / Agent 活动范围)
+// ================================================================
+
+/** 频道领地布局:与 AepSceneLayout/useSceneLayouts 同构 */
+export interface ChannelLayout {
+  channelId: string
+  x: number
+  z: number
+  radiusX: number
+  radiusZ: number
+  shape: 'ellipse' | 'rect'
+  rotationY: number
+}
+
+/** Agent 独立活动范围(编辑模式框选绘制/手柄调整;经 config.range 持久化)。
+ *  缺省(null)= 未设置,该 Agent 沿用频道边界活动。 */
+export interface AgentRangeLayout {
+  x: number
+  z: number
+  radiusX: number
+  radiusZ: number
+  shape: 'ellipse' | 'rect'
+  rotationY: number
+}
+
+// ================================================================
+// 边界几何
+// ================================================================
+
+/** 边界/范围的局部轮廓点(矩形四角 / 椭圆细分;radius 是半轴或半宽,供线框与测试)。 */
+export function boundaryPoints(shape: 'ellipse' | 'rect', rx: number, rz: number, seg = 48): Array<[number, number]> {
+  if (shape === 'rect') return [[-rx, -rz], [rx, -rz], [rx, rz], [-rx, rz]]
+  const pts: Array<[number, number]> = []
+  for (let i = 0; i < seg; i++) {
+    const t = (i / seg) * Math.PI * 2
+    pts.push([Math.cos(t) * rx, Math.sin(t) * rz])
+  }
+  return pts
+}
+
+/** 归一化边界(radius 钳制下限;椭圆半轴 / 矩形半宽) */
+export function normLayout<T extends ChannelLayout | { x: number, z: number, radiusX: number, radiusZ: number, shape: 'ellipse' | 'rect', rotationY: number }>(l: T): T {
+  return {
+    ...l,
+    radiusX: Math.max(60, l.radiusX),
+    radiusZ: Math.max(40, l.radiusZ),
+    shape: l.shape === 'rect' ? 'rect' : 'ellipse',
+    rotationY: l.rotationY || 0,
+  }
+}
+
+/** 旋转坐标到局部系(localX/localZ);用于把世界点折算到未旋转的边界坐标系。 */
+export function toLocal(l: { x: number, z: number, rotationY: number }, x: number, z: number): { x: number, z: number } {
+  const rad = -l.rotationY * Math.PI / 180
+  const cos = Math.cos(rad)
+  const sin = Math.sin(rad)
+  const dx = x - l.x
+  const dz = z - l.z
+  return { x: dx * cos - dz * sin, z: dx * sin + dz * cos }
+}
+
+/** 局部坐标旋回世界系。 */
+export function toWorld(l: { x: number, z: number, rotationY: number }, lx: number, lz: number): { x: number, z: number } {
+  const wrad = l.rotationY * Math.PI / 180
+  const wcos = Math.cos(wrad)
+  const wsin = Math.sin(wrad)
+  return { x: l.x + lx * wcos - lz * wsin, z: l.z + lx * wsin + lz * wcos }
+}
+
+/** 把点钳制到边界内(带内缩 margin;旋转边界用逆变换求局部坐标) */
+export function clampToBoundary(
+  layout: ChannelLayout,
+  x: number,
+  z: number,
+  margin = 0,
+): { x: number, z: number } {
+  const l = normLayout(layout)
+  const { x: lx, z: lz } = toLocal(l, x, z)
+  const rx = Math.max(8, l.radiusX - margin)
+  const rz = Math.max(8, l.radiusZ - margin)
+  let cx = lx
+  let cz = lz
+  if (l.shape === 'rect') {
+    cx = Math.max(-rx, Math.min(rx, lx))
+    cz = Math.max(-rz, Math.min(rz, lz))
+  }
+  else {
+    // 椭圆:点缩放到单位圆内
+    const nx = lx / rx
+    const nz = lz / rz
+    const d = Math.hypot(nx, nz)
+    if (d > 1) {
+      cx = nx / d * rx
+      cz = nz / d * rz
+    }
+  }
+  return toWorld(l, cx, cz)
+}
+
+/** 点到边界内判定(与 clampToBoundary 同旋转约定;纯函数,供工具与场景共用) */
+export function pointInBoundary(layout: ChannelLayout, x: number, z: number): boolean {
+  const l = normLayout(layout)
+  const { x: lx, z: lz } = toLocal(l, x, z)
+  if (l.shape === 'rect') return Math.abs(lx) <= l.radiusX && Math.abs(lz) <= l.radiusZ
+  const nx = lx / l.radiusX
+  const nz = lz / l.radiusZ
+  return nx * nx + nz * nz <= 1
+}
+
+/** 边界/范围的极值点(矩形四角 / 椭圆轴向四点;世界坐标,含 rotationY) */
+export function boundaryExtremePoints(
+  layout: { x: number, z: number, radiusX: number, radiusZ: number, shape: 'ellipse' | 'rect', rotationY: number },
+  margin = 0,
+): Array<[number, number]> {
+  const rx = Math.max(0, layout.radiusX - margin)
+  const rz = Math.max(0, layout.radiusZ - margin)
+  const local: Array<[number, number]> = layout.shape === 'rect'
+    ? [[rx, rz], [-rx, rz], [-rx, -rz], [rx, -rz]]
+    : [[rx, 0], [-rx, 0], [0, rz], [0, -rz]]
+  return local.map(([lx, lz]) => {
+    const { x, z } = toWorld(layout, lx, lz)
+    return [x, z] as [number, number]
+  })
+}
+
+/** 把 Agent 活动范围整体收进频道边界:中心钳入 + 半径收缩使极值点全部在边界内 */
+export function clampRangeToLayout(layout: ChannelLayout, range: AgentRangeLayout): AgentRangeLayout {
+  const l = normLayout(layout)
+  const center = clampToBoundary(l, range.x, range.z, 20)
+  let rx = Math.max(30, range.radiusX)
+  let rz = Math.max(30, range.radiusZ)
+  const margin = 12
+  for (let i = 0; i < 24; i++) {
+    const outside = boundaryExtremePoints({ x: center.x, z: center.z, radiusX: rx, radiusZ: rz, shape: range.shape, rotationY: range.rotationY }, margin)
+      .some(([wx, wz]) => !pointInBoundary(l, wx, wz))
+    if (!outside) break
+    rx = Math.max(30, rx * 0.9)
+    rz = Math.max(30, rz * 0.9)
+  }
+  return { x: center.x, z: center.z, radiusX: rx, radiusZ: rz, shape: range.shape, rotationY: range.rotationY }
+}
+
+/** 把点钳制到 Agent 自己活动范围内(带内缩 margin;矩形 radius 是半宽)。 */
+export function clampToAgentRange(
+  range: AgentRangeLayout,
+  x: number,
+  z: number,
+  margin = 0,
+): { x: number, z: number } {
+  const { x: lx, z: lz } = toLocal(range, x, z)
+  const rx = Math.max(8, range.radiusX - margin)
+  const rz = Math.max(8, range.radiusZ - margin)
+  let cx = lx
+  let cz = lz
+  if (range.shape === 'rect') {
+    cx = Math.max(-rx, Math.min(rx, lx))
+    cz = Math.max(-rz, Math.min(rz, lz))
+  }
+  else {
+    const nx = lx / rx
+    const nz = lz / rz
+    const d = Math.hypot(nx, nz)
+    if (d > 1) {
+      cx = (nx / d) * rx
+      cz = (nz / d) * rz
+    }
+  }
+  return toWorld(range, cx, cz)
+}
+
+/** 世界点到活动范围边界线的最近距离(矩形 4 边带 / 椭圆等距采样;矩形 radius 是半宽)。 */
+export function distToRangeBoundary(range: AgentRangeLayout, x: number, z: number): number {
+  const { x: lx, z: lz } = toLocal(range, x, z)
+  const rx = Math.max(8, range.radiusX)
+  const rz = Math.max(8, range.radiusZ)
+  if (range.shape === 'rect') {
+    return Math.min(Math.abs(lz - rz), Math.abs(lz + rz), Math.abs(lx - rx), Math.abs(lx + rx))
+  }
+  let best = Infinity
+  const seg = 40
+  for (let i = 0; i < seg; i++) {
+    const t = (i / seg) * Math.PI * 2
+    best = Math.min(best, Math.hypot(lx - Math.cos(t) * rx, lz - Math.sin(t) * rz))
+  }
+  return best
+}
+
+// ================================================================
+// 身份色(agentId / channelId 哈希 → 稳定色相,一处定义)
+// ================================================================
+
+/** FIFO 下每条气泡的展示时长:短句快速切换、长句更久(2.4s~7.2s)——放大气泡后同步延长可读窗口 */
+export function bubbleDisplayMs(text: string): number {
+  return Math.min(7200, Math.max(2400, 1700 + text.length * 36))
+}
+
+/** 接收器排空节拍:队列积压时按长度压缩单条展示时长(下限 1.4s 保证可读),
+ *  让爆发期(多 Agent 并发输出)的消息都能在场景里露脸,而不是被 FIFO 长队列吞掉。 */
+export function drainDisplayMs(text: string, queueLen = 0): number {
+  const base = bubbleDisplayMs(text)
+  if (queueLen <= 2) return base
+  return Math.max(1400, Math.min(base, 6400 / (queueLen - 1)))
+}
+
+export function hashHue(id: string): number {
+  if (!id) return 200
+  let h = 0
+  for (const c of id) h = (h * 31 + c.charCodeAt(0)) % 360
+  return h
+}
+
+export function hslToRgb(h: number, s: number, l: number): { r: number, g: number, b: number } {
+  const f = (n: number) => {
+    const k = (n + h * 12) % 12
+    const a = s * Math.min(l, 1 - l)
+    return Math.round((l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))) * 255)
+  }
+  return { r: f(0), g: f(8), b: f(4) }
+}
+
+/** 频道身份色相桶(策展色域:橙/琥珀/绿/青绿/数据青/蓝/靛/紫)——
+ *  原始哈希落满 0-360 色相环会产出洋红/品红等与夜航控制室五色语义冲突的杂色,
+ *  收敛到与宪法色板同族的 8 档,身份区分靠桶间色差,纪律靠色域封锁 */
+const CHANNEL_HUES = [16, 40, 158, 178, 195, 212, 235, 262] as const
+
+/** channelId → 稳定色(3D 场景用:RGB 打包 int) */
+export function channelColorNum(channelId: string): number {
+  const h = CHANNEL_HUES[hashHue(channelId) % CHANNEL_HUES.length]!
+  const c = hslToRgb(h / 360, 0.52, 0.6)
+  return (c.r << 16) | (c.g << 8) | c.b
+}
+
+/** channelId → CSS 色(UI 用:HSL 字符串,与场景同源) */
+export function channelColorCss(channelId: string): string {
+  const h = CHANNEL_HUES[hashHue(channelId) % CHANNEL_HUES.length]!
+  return `hsl(${h}, 52%, 60%)`
+}
+
+// ================================================================
+// 调试/统计辅助
+// ================================================================
+
+/** 事件流最近活动:提取可读文本(供 HUD 跑马灯;与 town-protocol 同口径) */
+export function eventText(e: AepEnvelope): string {
+  const p = e.payload as { parts?: Array<{ text?: string } | { data?: unknown }> } | undefined
+  const parts = p?.parts ?? []
+  return parts
+    .map(pt => 'text' in pt ? (pt.text ?? '') : 'data' in pt ? JSON.stringify(pt.data) : '')
+    .join('\n')
+    .trim()
+}