agentshire 1.0.0

package/src/bridge/AGENTS.md

@@ -0,0 +1,136 @@
+# Bridge 层架构指南
+
+> AgentEvent（OpenClaw 协议）→ GameEvent（3D 前端消费）的翻译与编排层。
+
+## 目录结构
+
+```
+src/bridge/
+├── DirectorBridge.ts      # 中央编排器：7阶段Phase状态机 + 事件分发
+├── EventTranslator.ts     # 兜底翻译：AgentEvent → GameEvent 简单映射
+├── RouteManager.ts        # A*寻路 + moveNpcAndWait(带ack/超时) + 目的地评分
+├── CitizenManager.ts      # 居民生命周期：persona检测 → spawn动画编排 → 寻路
+├── ActivityStream.ts      # 活动日志 + thinking流缓冲（500ms flush）
+├── NpcEventQueue.ts       # 对话/phase事件排队（保护气泡不被快速覆盖）
+├── StateTracker.ts        # agentId↔npcId双向映射 + 工位池(A-J共10个)
+├── ToolVfxMapper.ts       # 纯函数：工具名 → VFX事件/emoji/动画phase
+├── ReconnectManager.ts    # WebSocket指数退避重连
+├── implicit-chat.ts       # NPC隐式LLM调用（10种场景，DI注入）
+├── index.ts               # barrel export
+└── data/
+    ├── route-config.ts    # 路由图类型 + 导入
+    └── route-config.json  # 小镇/办公室节点图 + 居民目的地坐标
+```
+
+## 数据流
+
+```
+hook-translator (plugin层)  →  AgentEvent
+    │
+    ▼  WebSocket
+DirectorBridge.processAgentEvent(event)
+    ├─ sub_agent.started  → 注册映射 + npc_spawn + 启动summon收集窗口(3s)
+    ├─ sub_agent.progress → 转发内部事件给对应NPC的queue
+    ├─ sub_agent.done     → npc_work_done + 更新进度
+    ├─ text/text_delta    → handleStewardText() → 对话气泡 + activity
+    ├─ thinking_delta     → ActivityStream.appendThinkingDelta()
+    ├─ tool_use           → ActivityStream + ToolVfxMapper驱动VFX
+    ├─ tool_result        → activity状态 + CitizenManager检测(persona/citizen)
+    ├─ turn_end           → flush所有队列 + flushPendingCitizens
+    ├─ bus_message        → NPC互看 + connectionBeam VFX
+    ├─ hook_activity      → hookFlash VFX
+    ├─ media_output       → deliverable_card
+    ├─ error              → NPC error phase
+    └─ default            → EventTranslator.translate() (兜底)
+    │
+    ▼  emit GameEvent[]
+MainScene.handleGameEvent()
+
+DirectorBridge.processCitizenEvent(npcId, event)
+    → 居民Agent（非子Agent）的独立事件流，附加npcId后处理
+```
+
+## Phase 状态机
+
+```
+idle → summoning → assigning → going_to_office → working → publishing → returning → idle
+```
+
+| Phase | 触发条件 | 发出事件 | 前端编排 |
+|-------|---------|---------|---------|
+| idle | 初始/返回完成 | — | — |
+| summoning | 首个 `sub_agent.started` | `workflow_summon`（收集窗口3s后） | SummonOrchestrator |
+| assigning | 前端 `workflow_phase_complete(summoning)` | `workflow_assign` | BriefingOrchestrator |
+| going_to_office | 前端 `workflow_phase_complete(assigning)` | `workflow_go_office` + 工位分配 | SceneSwitcher + WorkflowHandler |
+| working | 前端 `workflow_phase_complete(going_to_office)` | `progress` + 转发sub_agent事件 | 工位屏幕 + 小游戏 |
+| publishing | `project_complete` tool_result | `workflow_publish` + deliverable_card | CelebrationOrchestrator |
+| returning | 前端 `workflow_phase_complete(publishing)` | `workflow_return` | Choreographer散场 |
+
+**迟到者处理**：working 阶段到达的 `sub_agent.started` 不走 summoning，直接分配工位。
+
+**临时工机制**：未在 TownConfig 中配置的 agent 自动分配随机 avatar，标记为临时工。
+
+## implicit-chat：NPC 隐式 LLM 调用
+
+通过 `setImplicitChatFn()` 依赖注入实际调用函数（浏览器端走 WebSocket → llm-agent-proxy → OpenClaw embedded agent，Node端可直连）。
+
+10 种场景及 maxTokens：
+
+| 场景 | 用途 | maxTokens |
+|------|------|-----------|
+| `daily_plan` | 黎明日计划 | 200 |
+| `encounter_init` | 发起对话 | 120 |
+| `encounter_reply` | 回复对话 | 100 |
+| `encounter_summary` | 对话摘要 | 80 |
+| `tactical_decision` | L2战术决策 | 60 |
+| `night_reflection` | 夜间反思 | 120 |
+| `town_journal` | 每日叙事 | 300 |
+| `greeting` | 问候 | 60 |
+| `farewell` | 告别 | 60 |
+| `micro_reaction` | 微反应 | 60 |
+
+回退机制：无 chatFn / 超时(8s) / 异常时返回预设中文回退文本。
+
+## 模块职责与依赖
+
+| 模块 | 职责 | 依赖 |
+|------|------|------|
+| DirectorBridge | Phase状态机 + 事件分发 + 居民事件管道 | StateTracker, EventTranslator, NpcEventQueue, RouteManager, ActivityStream, CitizenManager, ToolVfxMapper |
+| EventTranslator | AgentEvent→GameEvent 简单映射（兜底） | StateTracker |
+| RouteManager | A*寻路 + moveNpcAndWait + 目的地评分 | route-config |
+| CitizenManager | persona检测 + 居民spawn动画序列 | RouteManager, CharacterRoster（DI注入） |
+| ActivityStream | 活动日志 + thinking流 + todo活动 | — |
+| NpcEventQueue | 对话保护期 + phase缓冲 | — |
+| StateTracker | 双向ID映射 + 工位池管理 | — |
+| ToolVfxMapper | 工具→VFX/动画 纯函数 | — |
+| implicit-chat | 隐式LLM调用 + 统计 | DI注入chatFn |
+
+## 编排原则
+
+- **Bridge 发高级意图事件，不做 setTimeout 微操**：NPC 完成时发 `npc_work_done`，前端 `WorkflowHandler.handleNpcWorkDone()` 用 async/await 编排完整序列
+- **工位延迟释放**：Bridge 在 `sub_agent.done` 时不立即释放，等前端 `workstation_released` action 回传后才释放（12s安全网兜底）
+- **Phase 前进靠前端回传**：前端通过 `workflow_phase_complete` 推动状态机，Bridge 不假设动画时长
+
+## 常见改动
+
+| 要做的事 | 改哪里 |
+|---------|--------|
+| 新增 AgentEvent → GameEvent 映射 | `EventTranslator.translate()` 加 case |
+| 修改工具VFX/动画 | `ToolVfxMapper.ts` |
+| 修改活动日志描述/图标 | `ActivityStream.ts` 的 `toolActivityMsg/toolActivityIcon` |
+| 修改居民spawn动画序列 | `CitizenManager.spawnCitizenSequence()` |
+| 修改寻路图节点 | `data/route-config.json` |
+| 修改Phase编排 | `DirectorBridge` 的 phase 切换逻辑（发意图事件，不编排动画） |
+| 新增隐式LLM场景 | `implicit-chat.ts` 的 `SCENE_CONFIG` |
+| 修改对话保护时长 | `NpcEventQueue.ts` 的 `calcDialogDuration()` |
+
+## 测试
+
+```
+src/bridge/__tests__/
+├── EventTranslator.test.ts   # AgentEvent → GameEvent 映射
+├── NpcEventQueue.test.ts     # 对话保护 + phase 缓冲
+├── RouteManager.test.ts      # A*寻路 + 移动 + 目的地
+├── ActivityStream.test.ts    # thinking流 + 活动日志
+└── CitizenManager.test.ts    # 居民检测 + 名字匹配
+```

package/src/bridge/ActivityStream.ts

@@ -0,0 +1,184 @@
+// @desc NPC activity log and thinking stream — buffers thinking deltas and emits activity/status events
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+
+const MAX_ACTIVITY_LOG = 500
+
+/** Manages the activity log panel: emits activity entries, streams thinking text in batches, and tracks tool result success/failure */
+export class ActivityStream {
+  private thinkingBuffers = new Map<string, string>()
+  private thinkingFlushTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  private activityLog: any[] = []
+  private emitFn: (events: GameEvent[]) => void
+
+  constructor(emitFn: (events: GameEvent[]) => void) {
+    this.emitFn = emitFn
+  }
+
+  private nowHHMM(): string {
+    const d = new Date()
+    return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+  }
+
+  private cacheActivity(event: any): void {
+    this.activityLog.push(event)
+    if (this.activityLog.length > MAX_ACTIVITY_LOG) this.activityLog.shift()
+  }
+
+  getActivityReplayEvents(): any[] {
+    return this.activityLog.slice()
+  }
+
+  /** Emit an activity log entry with icon, message, and timestamp */
+  emitActivity(npcId: string, icon: string, message: string, noStatus?: boolean): void {
+    const ev: GameEvent = { type: 'npc_activity', npcId, icon, message, time: this.nowHHMM() }
+    if (noStatus) (ev as any).status = null
+    this.cacheActivity(ev)
+    this.emitFn([ev])
+  }
+
+  /** Mark the most recent activity entry for an NPC as success or failure */
+  emitActivityStatus(npcId: string, success: boolean): void {
+    for (let i = 0; i < this.activityLog.length; i++) {
+      const cached = this.activityLog[i]
+      if (cached.npcId === npcId && cached.type === 'npc_activity' && cached.status === undefined) {
+        cached.status = success
+        break
+      }
+    }
+    const ev: GameEvent = { type: 'npc_activity_status', npcId, success }
+    this.cacheActivity(ev)
+    this.emitFn([ev])
+  }
+
+  private startThinkingStream(npcId: string): void {
+    if (this.thinkingFlushTimers.has(npcId)) return
+    const ev: GameEvent = { type: 'npc_activity', npcId, icon: 'brain', message: '', time: this.nowHHMM() }
+    this.cacheActivity(ev)
+    this.emitFn([ev])
+    const timer = setInterval(() => {
+      const buf = this.thinkingBuffers.get(npcId)
+      if (buf && buf.length > 0) {
+        const streamEv: GameEvent = { type: 'npc_activity_stream', npcId, delta: buf }
+        this.cacheActivity(streamEv)
+        this.emitFn([streamEv])
+        this.thinkingBuffers.set(npcId, '')
+      }
+    }, 500)
+    this.thinkingFlushTimers.set(npcId, timer)
+  }
+
+  /** Buffer a thinking text delta; starts a periodic flush stream if not already running */
+  appendThinkingDelta(npcId: string, delta: string): void {
+    if (!delta && !this.thinkingFlushTimers.has(npcId)) return
+    const buf = this.thinkingBuffers.get(npcId) ?? ''
+    this.thinkingBuffers.set(npcId, buf + delta)
+    if (!this.thinkingFlushTimers.has(npcId)) {
+      this.startThinkingStream(npcId)
+    }
+  }
+
+  /** Flush any buffered thinking text and emit stream-end marker */
+  flushThinking(npcId: string): void {
+    const timer = this.thinkingFlushTimers.get(npcId)
+    if (!timer) return
+    clearInterval(timer)
+    this.thinkingFlushTimers.delete(npcId)
+    const buf = this.thinkingBuffers.get(npcId)
+    if (buf && buf.length > 0) {
+      const streamEv: GameEvent = { type: 'npc_activity_stream', npcId, delta: buf }
+      this.cacheActivity(streamEv)
+      this.emitFn([streamEv])
+    }
+    this.thinkingBuffers.set(npcId, '')
+    const endEv: GameEvent = { type: 'npc_activity_stream_end', npcId }
+    this.cacheActivity(endEv)
+    this.emitFn([endEv])
+  }
+
+  /** Return the Lucide icon name for a given tool */
+  toolActivityIcon(toolName: string): string {
+    if (toolName === '__thinking__') return 'sparkles'
+    if (toolName === '__thinking_placeholder__') return 'sparkles'
+    if (toolName === 'bash' || toolName === 'exec') return 'terminal'
+    if (['read', 'read_file', 'grep', 'glob'].includes(toolName)) return 'file-search'
+    if (['write', 'edit', 'write_file', 'edit_file'].includes(toolName)) return 'file-edit'
+    if (toolName === 'web_search' || toolName === 'web_fetch') return 'globe'
+    if (toolName === 'browser') return 'globe'
+    if (toolName === 'process') return 'terminal'
+    if (toolName === 'skill') return 'zap'
+    if (toolName === 'spawn_agent' || toolName === 'sessions_spawn') return 'users'
+    if (toolName === 'todo_write') return 'list-checks'
+    return 'wrench'
+  }
+
+  /** Generate a human-readable Chinese description of what a tool is doing */
+  toolActivityMsg(toolName: string, input?: Record<string, unknown>): string {
+    const inp = input ?? {}
+    if (toolName === '__thinking__') {
+      const content = String(inp.content ?? '')
+      const firstLine = content.split('\n')[0].trim()
+      const preview = firstLine.length > 60 ? firstLine.slice(0, 57) + '...' : firstLine
+      return `思考完成\n${preview}`
+    }
+    if (toolName === '__thinking_placeholder__') return '正在思考'
+    if (toolName === 'bash' || toolName === 'exec') {
+      const cmd = String(inp.command ?? '').trim()
+      if (/\b(pnpm|npm|yarn)\s+(install|i|ci)\b/.test(cmd)) return '安装依赖'
+      if (/\b(git\s+clone|cp\s+-r|rsync)\b/.test(cmd)) return '克隆项目'
+      if (/\bmkdir\b/.test(cmd)) return '创建目录'
+      if (/\b(rm|rmdir)\b/.test(cmd)) return '删除文件'
+      if (/\b(pnpm|npm|yarn|npx)\s+(run|exec|start|dev|build|test)\b/.test(cmd)) return '运行脚本'
+      if (/\b(node|ts-node|tsx)\b/.test(cmd)) return '运行脚本'
+      if (/\b(cat|head|tail|less|more)\b/.test(cmd)) return '查看文件'
+      if (/\bls\b/.test(cmd)) return '查看目录'
+      if (/\b(sed|awk|grep|find)\b/.test(cmd)) return '处理文件'
+      if (/\bscreencapture\b/.test(cmd)) return '截取屏幕'
+      if (/\bcurl|wget\b/.test(cmd)) return '网络请求'
+      if (/\bdocker\b/.test(cmd)) return '运行容器'
+      if (/\bcd\b/.test(cmd)) return '切换目录'
+      return '执行命令'
+    }
+    if (['read', 'read_file', 'grep', 'glob'].includes(toolName)) {
+      const p = String(inp.path ?? inp.pattern ?? '').split('/').pop() ?? ''
+      return `阅读 ${p || '文件'}`
+    }
+    if (['write', 'edit', 'write_file', 'edit_file'].includes(toolName)) {
+      const p = String(inp.path ?? inp.file ?? inp.content?.toString().slice(0, 0) ?? '').split('/').pop() ?? ''
+      const writePath = String(inp.path ?? inp.file ?? '').split('/').pop() ?? ''
+      return `编辑 ${writePath || '文件'}`
+    }
+    if (toolName === 'web_search') return '搜索网络'
+    if (toolName === 'web_fetch') return '访问网页'
+    if (toolName === 'browser') return '浏览器操作'
+    if (toolName === 'process') {
+      const action = String(inp.action ?? '')
+      if (action === 'poll') return '等待进程完成'
+      if (action === 'log') return '查看进程日志'
+      if (action === 'kill') return '终止进程'
+      return '进程操作'
+    }
+    if (toolName === 'skill') {
+      const sn = String(inp.skill_name ?? inp.name ?? '').slice(0, 20)
+      return `使用技能：${sn || '技能'}`
+    }
+    if (toolName === 'spawn_agent' || toolName === 'sessions_spawn') {
+      const name = String(inp.name ?? inp.displayName ?? inp.label ?? '').slice(0, 15)
+      return `召唤 ${name || '居民'}`
+    }
+    if (toolName === 'todo_write') return ''
+    return `使用工具：${toolName}`
+  }
+
+  isTodoWrite(toolName: string): boolean {
+    return toolName === 'todo_write'
+  }
+
+  /** Emit a todo list activity entry */
+  emitTodoActivity(npcId: string, input: Record<string, unknown>): void {
+    const todos = input.todos as Array<{ id: number; content: string; status: string }> | undefined
+    if (!todos || !Array.isArray(todos)) return
+    const ev: GameEvent = { type: 'npc_activity_todo', npcId, todos: todos.map(t => ({ id: t.id, content: t.content, status: t.status })) }
+    this.cacheActivity(ev)
+    this.emitFn([ev])
+  }
+}

package/src/bridge/CitizenManager.ts

@@ -0,0 +1,280 @@
+// @desc Citizen lifecycle: persona detection, spawn animation sequence, and name matching
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+import type { RouteManager } from './RouteManager.js'
+import { CITIZEN_SPAWN_ORIGIN, STEWARD_FACE_POS } from './RouteManager.js'
+import { getCharacterKeyForNpc } from '../../town-frontend/src/data/CharacterRoster.js'
+
+export interface CitizenManagerDeps {
+  emit: (events: GameEvent[]) => void
+  routes: RouteManager
+  getConfig: () => any
+  getCharacterAssignments: () => Map<string, string>
+  isStewardConfirmed: () => boolean
+  getPersonaName: () => string | null
+  getStewardName: () => string
+  onPersonaChanged: (name: string) => void
+  delayMs: (ms: number) => Promise<void>
+  scheduleDelayedEmit: (delayMs: number, events: GameEvent[]) => void
+  getLastToolInput: () => Record<string, unknown>
+}
+
+/** Detects new citizen persona files, manages the spawn queue, and orchestrates the citizen arrival animation (spawn -> greet steward -> walk to destination) */
+export class CitizenManager {
+  pendingCitizenNames: { npcId: string; citizenName: string }[] = []
+  citizenSpawnQueue: { npcId: string; citizenName: string }[] = []
+  citizenSpawning = false
+  activeCitizenNpcs = new Set<string>()
+  spawnedCitizenCount = 0
+  spawnedCitizenIds = new Set<string>()
+  citizenFlowStartMs = new Map<string, number>()
+  pendingStewardRenameTimer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(private deps: CitizenManagerDeps) {}
+
+  /** Handle switch_persona tool result: update steward name and trigger persona transform VFX */
+  async detectPersonaSwitch(event: any): Promise<void> {
+    if (event.name !== 'switch_persona') return
+    const output = String(event.output ?? '')
+    const m = output.match(/Persona switched to "(.+?)"/)
+    if (!m) return
+
+    const newName = m[1]
+
+    this.deps.emit([
+      { type: 'fx', effect: 'personaTransform', params: { npcId: this.deps.getStewardName() } },
+    ])
+
+    if (this.pendingStewardRenameTimer) {
+      clearTimeout(this.pendingStewardRenameTimer)
+      this.pendingStewardRenameTimer = null
+    }
+    this.pendingStewardRenameTimer = setTimeout(() => {
+      this.pendingStewardRenameTimer = null
+      this.deps.emit([
+        { type: 'steward_rename', npcId: 'steward', newName },
+      ])
+    }, 1500)
+
+    this.flushPendingCitizens()
+    this.deps.onPersonaChanged(newName)
+  }
+
+  /** Handle write_file tool result: if the file is a persona, queue the citizen for spawning */
+  detectCitizenCreated(event: any): void {
+    if (event.name !== 'write_file') return
+    const filePath = String(event.meta?.filePath ?? this.deps.getLastToolInput().path ?? '')
+    console.log('[CitizenManager] detectCitizenCreated filePath:', filePath, 'isPersona:', this.isPersonaPath(filePath))
+    if (!this.isPersonaPath(filePath)) return
+
+    const fileName = filePath.split('/').pop() ?? ''
+    const citizenName = fileName.replace(/\.md$/i, '').replace(/_/g, ' ').trim()
+    if (!citizenName) return
+
+    const npcId = `citizen_${citizenName.toLowerCase().replace(/\s+/g, '_')}`
+    if (this.spawnedCitizenIds.has(npcId)) return
+    if (this.pendingCitizenNames.some(p => p.npcId === npcId)) return
+    if (this.citizenSpawnQueue.some(p => p.npcId === npcId)) return
+
+    if (!this.deps.isStewardConfirmed()) {
+      console.log(`[CitizenManager] steward not confirmed yet, queue persona file: ${citizenName} (${npcId})`)
+      this.pendingCitizenNames.push({ npcId, citizenName })
+      return
+    }
+
+    if (this.isStewardName(citizenName)) {
+      console.log(`[CitizenManager] skipping recognized steward persona file: ${citizenName}`)
+      this.spawnedCitizenIds.add(npcId)
+      return
+    }
+
+    console.log(`[CitizenManager] citizen persona detected: ${citizenName} (${npcId}), spawn immediately`)
+    this.spawnedCitizenIds.add(npcId)
+    this.citizenSpawnQueue.push({ npcId, citizenName })
+    this.drainCitizenSpawnQueue()
+  }
+
+  isStewardName(name: string): boolean {
+    const lower = name.toLowerCase().replace(/\s+/g, '_')
+    const personaName = this.deps.getPersonaName()
+    if (personaName && lower === personaName.toLowerCase().replace(/\s+/g, '_')) return true
+    const stewardName = this.deps.getStewardName()
+    if (stewardName !== 'steward' && lower === stewardName.toLowerCase().replace(/\s+/g, '_')) return true
+    return false
+  }
+
+  /** Move pending citizen names (held until steward persona is confirmed) into the spawn queue */
+  flushPendingCitizens(): void {
+    if (!this.deps.isStewardConfirmed()) {
+      console.log('[CitizenManager] steward persona not confirmed yet, defer citizen spawning')
+      return
+    }
+
+    const toSpawn = this.pendingCitizenNames.splice(0)
+    for (const { npcId, citizenName } of toSpawn) {
+      if (this.spawnedCitizenIds.has(npcId)) continue
+      if (this.isStewardName(citizenName)) {
+        console.log(`[CitizenManager] skipping steward persona: ${citizenName}`)
+        this.spawnedCitizenIds.add(npcId)
+        continue
+      }
+      this.spawnedCitizenIds.add(npcId)
+      this.citizenSpawnQueue.push({ npcId, citizenName })
+    }
+    this.drainCitizenSpawnQueue()
+  }
+
+  drainCitizenSpawnQueue(): void {
+    while (this.citizenSpawnQueue.length > 0) {
+      if (this.citizenSpawning) return
+      const next = this.citizenSpawnQueue[0]
+      if (this.isStewardName(next.citizenName)) {
+        console.log(`[CitizenManager] drainQueue: skipping steward persona: ${next.citizenName}`)
+        this.citizenSpawnQueue.shift()
+        continue
+      }
+      this.citizenSpawning = true
+      this.citizenSpawnQueue.shift()
+      this.spawnCitizenSequence(next.npcId, next.citizenName)
+      return
+    }
+  }
+
+  async spawnCitizenSequence(npcId: string, citizenName: string): Promise<void> {
+    const idx = this.spawnedCitizenCount++
+
+    const spawnX = CITIZEN_SPAWN_ORIGIN.x + (idx % 3 - 1) * 2.5
+    const spawnZ = CITIZEN_SPAWN_ORIGIN.z
+    const flowStart = Date.now()
+    this.citizenFlowStartMs.set(npcId, flowStart)
+
+    console.log(`[CitizenManager] spawning citizen: ${citizenName} (${npcId}) at (${spawnX.toFixed(1)}, ${spawnZ.toFixed(1)})`)
+
+    this.activeCitizenNpcs.add(npcId)
+    let claimedDestinationId: string | null = null
+    let destinationArrived = false
+    const config = this.deps.getConfig()
+    const configuredCitizen = config?.citizens?.find((c: any) => c.id === npcId)
+    const citizenCharacterKey = configuredCitizen?.avatarId ?? getCharacterKeyForNpc(npcId)
+
+    this.deps.emit([
+      {
+        type: 'npc_spawn', npcId, name: citizenName,
+        role: 'general', category: 'citizen',
+        spawn: { x: spawnX, y: 0, z: spawnZ },
+        avatarId: citizenCharacterKey,
+      },
+    ])
+
+    try {
+      await this.deps.delayMs(300)
+
+      const greetPoint = this.deps.routes.getGreetPoint(idx)
+      const greetX = greetPoint.x
+      const greetZ = greetPoint.z
+      const distToSteward = Math.sqrt((greetX - spawnX) ** 2 + (greetZ - spawnZ) ** 2)
+      const walkSpeed = 5
+      const greetStart = Date.now()
+      console.log(`[CitizenManager][CitizenFlow] ${npcId} -> greet target=(${greetX.toFixed(2)}, ${greetZ.toFixed(2)}) speed=${walkSpeed} mode=arrival-driven`)
+
+      const greetStatus = await this.deps.routes.moveNpcAndWait(
+        npcId,
+        { x: greetX, y: 0, z: greetZ },
+        walkSpeed,
+      )
+      if (greetStatus !== 'arrived') {
+        console.warn(`[CitizenManager][CitizenFlow] ${npcId} greet move interrupted`)
+        return
+      }
+
+      this.deps.emit([
+        { type: 'npc_anim', npcId, anim: 'wave' },
+        { type: 'fx', effect: 'exclamation', params: { npcId } },
+        { type: 'dialog_message', npcId, text: `你好！我是${citizenName}，很高兴来到小镇！`, isStreaming: false },
+      ])
+
+      await this.deps.delayMs(2500)
+
+      const destination = this.deps.routes.chooseCitizenDestination(npcId, { x: greetX, z: greetZ })
+      const targetX = destination.x + (Math.random() - 0.5) * 1.3
+      const targetZ = destination.z + (Math.random() - 0.5) * 1.3
+      this.deps.routes.claimDestinationForNpc(npcId, destination.id)
+      claimedDestinationId = destination.id
+      const distToDestination = this.deps.routes.distance2D({ x: greetX, z: greetZ }, { x: targetX, z: targetZ })
+      console.log(`[CitizenManager][CitizenFlow] ${npcId} route destination=${destination.id} target=(${targetX.toFixed(2)}, ${targetZ.toFixed(2)}) score=${destination.score.toFixed(2)} mode=arrival-driven`)
+
+      const destinationStatus = await this.deps.routes.moveNpcAndWait(
+        npcId,
+        { x: targetX, y: 0, z: targetZ },
+        walkSpeed,
+      )
+      if (destinationStatus !== 'arrived') {
+        console.warn(`[CitizenManager][CitizenFlow] ${npcId} destination move interrupted`)
+        return
+      }
+
+      destinationArrived = true
+      this.deps.emit([{ type: 'npc_daily_behavior_ready', npcId }])
+      this.deps.routes.releaseDestinationClaimLater(npcId, destination.id, 30000)
+      const flowEnd = Date.now()
+      console.log(`[CitizenManager][CitizenFlow] ${npcId} done total=${flowEnd - flowStart}ms`)
+    } finally {
+      if (claimedDestinationId && !destinationArrived) {
+        this.deps.routes.releaseDestinationClaim(npcId, claimedDestinationId)
+      }
+      this.activeCitizenNpcs.delete(npcId)
+      this.citizenFlowStartMs.delete(npcId)
+      this.citizenSpawning = false
+      this.drainCitizenSpawnQueue()
+    }
+  }
+
+  /** Find a citizen's NPC ID by exact name match against town config and spawned IDs */
+  findCitizenNpcId(name: string): string | null {
+    const normalized = name.toLowerCase().replace(/\s+/g, '_')
+    const config = this.deps.getConfig()
+
+    if (config?.citizens) {
+      for (const c of config.citizens) {
+        if (c.name === name || c.name.toLowerCase().replace(/\s+/g, '_') === normalized) {
+          return c.id
+        }
+      }
+    }
+
+    const candidateId = `citizen_${normalized}`
+    if (this.spawnedCitizenIds.has(candidateId)) return candidateId
+    for (const id of this.spawnedCitizenIds) {
+      if (id.endsWith(`_${normalized}`)) return id
+    }
+    return null
+  }
+
+  /** Find a citizen's NPC ID by fuzzy substring match */
+  fuzzyMatchCitizen(name: string): string | null {
+    const lower = name.toLowerCase().replace(/\s+/g, '')
+    if (!lower) return null
+    const config = this.deps.getConfig()
+
+    if (config?.citizens) {
+      for (const c of config.citizens) {
+        const cName = c.name.toLowerCase().replace(/\s+/g, '')
+        if (cName.includes(lower) || lower.includes(cName)) return c.id
+      }
+    }
+
+    for (const id of this.spawnedCitizenIds) {
+      const citizenName = id.replace(/^citizen_/, '').replace(/_/g, '')
+      if (citizenName.includes(lower) || lower.includes(citizenName)) return id
+    }
+    return null
+  }
+
+  looksLikeIdFragment(name: string): boolean {
+    return /^[a-z0-9_\- ]{1,12}$/i.test(name) && !/[\u4e00-\u9fa5]/.test(name)
+  }
+
+  isPersonaPath(filePath: string | null): boolean {
+    if (!filePath) return false
+    return /\bpersonas?\b/i.test(filePath)
+  }
+}