新增: 小程序端跨端AI对话

apps/df-miniapp/src/composables/useAiChat.ts

@@ -20,17 +20,20 @@
  * - tokenUsage: 最近回复 token 用量(可选展示)
  *
  * 方法:
- * - send(text): 发消息(send_message Command → relay → device invoke ai_chat_send)
+ * - send(text, skill?, spans?): 发消息(send_message Command → relay → device invoke ai_chat_send)
+ *   F-#95 联想扩展:skill(`/<skill>` 选中)+ spans(`@项目/@任务/@灵感` mention_spans)可选透传
  * - stop(): 停止生成(stop Command → device invoke ai_chat_stop)
  * - regenerate(): 重发最后一条 user 消息(重新 send_message)
  * - switchConversation(id): 切换会话(switch Command → device 切 active)
+ * - listSkills(): 拉技能列表(list_skills Command → AiSkillList 事件回流 skills)
+ * - listEntities(): 拉实体列表(list_entities Command → AiEntityList 事件回流 entities)
  * - approve(toolCallId, approved): 审批工具调用(approve Command → device invoke ai_approve)
  * - authorizeDir(toolCallId, decision): 路径授权(authorize_dir Command → device invoke ai_authorize_dir)
  * - continueLoop(convId): 继续循环(continue_loop Command → device invoke ai_continue_loop)
  * - stopLoop(convId): 停止循环(stop_loop Command → device invoke ai_stop_loop)
  */
 
-import { ref, reactive, computed } from 'vue'
+import { ref, reactive, computed, watch } from 'vue'
 import { wsClient } from '@/api/ws'
 import type { WsStatus } from '@/api/ws'
 import type {
@@ -39,8 +42,17 @@ import type {
   Conversation,
   AiToolCallInfo,
   TokenUsage,
+  ProjectRecord,
+  TaskRecord,
+  IdeaRecord,
 } from '@/types/events'
-import type { BroadcastMessage, MiniCommand, ControlMessage } from '@/types/relay'
+import type {
+  BroadcastMessage,
+  MiniCommand,
+  ControlMessage,
+  SkillInfo,
+  MentionSpan,
+} from '@/types/relay'
 
 /** 简易唯一 id 生成(miniapp 无 crypto.randomUUID 兼容性顾虑,时间戳+随机即可) */
 function genId(prefix: string): string {
@@ -55,14 +67,159 @@ function genId(prefix: string): string {
  */
 const messages = reactive<ChatMessage[]>([])
 const currentText = ref<string>('')
+/**
+ * 当前流式累积目标 assistant 气泡 id(F3:精确回填,取代启发式「末尾非 error assistant」)。
+ * send/AiAgentRound push 新占位时记录;flushCurrentText 按 id 精确写入,治 retry/error/
+ * compressed 气泡穿插致启发式定位错位(新一轮内容写入旧气泡)。找不到则回退启发式兜底。
+ */
+const currentAssistantMsgId = ref<string | null>(null)
 const generating = ref<boolean>(false)
 const agentRound = ref<number>(0)
+/**
+ * 达最大轮次挂起标志(P1-E):true 时 chat 渲染「继续/停止循环」按钮(对齐桌面 MaxRounds)。
+ * AiMaxRoundsReached 置 true;continueLoop/stopLoop/send/switch/new 清 false。
+ */
+const maxRoundsActive = ref<boolean>(false)
 const conversations = reactive<Conversation[]>([])
-const activeConversationId = ref<string | null>(null)
+
+/** 消息内存上限(P3-A:防长会话 OOM;渲染另有 visibleMessages slice 200 兜底,此为存储层) */
+const MAX_STORE_MESSAGES = 500
+watch(
+  () => messages.length,
+  (len) => {
+    if (len > MAX_STORE_MESSAGES) messages.splice(0, len - MAX_STORE_MESSAGES)
+  },
+)
+
+/** 冷启动恢复上次激活会话(P1-8)的 storage key */
+const ACTIVE_CONV_STORAGE_KEY = 'df_active_conv_id'
+
+/** 读取持久化的激活会话 id(冷启动恢复,模块加载时调一次) */
+function loadPersistedActiveConv(): string | null {
+  try {
+    const v = uni.getStorageSync(ACTIVE_CONV_STORAGE_KEY)
+    return v || null
+  } catch {
+    return null
+  }
+}
+
+/** 持久化激活会话 id(switch/newConversation 时调,冷启动据此恢复) */
+function persistActiveConv(convId: string | null): void {
+  try {
+    if (convId) uni.setStorageSync(ACTIVE_CONV_STORAGE_KEY, convId)
+    else uni.removeStorageSync(ACTIVE_CONV_STORAGE_KEY)
+  } catch (e) {
+    console.warn('[useAiChat] 持久化 active conv 失败', e)
+  }
+}
+
+const activeConversationId = ref<string | null>(loadPersistedActiveConv())
+/**
+ * 最近发起 load_messages 的目标会话(MINIAPP-02 历史丢失竞态修复)。
+ *
+ * 问题:switchConversation 同步置 activeConversationId=convId 后发 load_messages,
+ * 但 AiMessageHistory 回流判定 `event.conversation_id === activeConversationId.value`。
+ * 用户快速切 A→B→A,或切后立即 newConversation() 置 null,致 activeConversationId
+ * 在历史回流前已变 → is_active=false → 49 条历史静默丢弃 → 点进会话空白。
+ *
+ * 修复:用此变量记录最近一次 load 目标,回流时除 active 外还比对它,命中则写入
+ * (避免用户停留目标会话时被竞态丢弃);不命中则 console.warn 明确丢弃原因(非静默)。
+ */
+const lastLoadedConvId = ref<string | null>(null)
 const wsStatus = ref<WsStatus>('disconnected')
 const wsStatusDetail = ref<string>('')
 const tokenUsage = ref<TokenUsage | null>(null)
 const pendingApprovals = reactive<AiToolCallInfo[]>([])
+/**
+ * 最近批准(approved=true)的工具调用(P2-E 审批失败回填)。
+ * approve 成功发出后记录;device 返 AiError(执行失败/已被桌面端处理)时回填 pendingApprovals 让用户重试,
+ * 避免 UI 误导「已批准」实际未生效。AiApprovalResult/AiToolCallCompleted 确认 → 清;切会话/新建/断连 → 清。
+ */
+const lastApprovedTc = ref<AiToolCallInfo | null>(null)
+/**
+ * `/` 联想技能列表(F-#95 扩展,list_skills 命令 → device route_list_skills → AiSkillList 回流)。
+ * 初始空数组,chat/index.vue inputText 以 / 开头时 listSkills() 拉取后填充浮层。
+ */
+const skills = reactive<SkillInfo[]>([])
+/**
+ * `@` 联想实体列表(F-#95 扩展,list_entities 命令 → device route_list_entities → AiEntityList 回流)。
+ * 含 projects/tasks/ideas 三类,chat/index.vue 末尾 @ 触发 listEntities() 后填充浮层。
+ * 单 reactive 对象聚合三类(对齐 AiEntityList 事件载荷结构,UI 用 entities.projects/tasks/ideas)。
+ */
+const entities = reactive<{ projects: ProjectRecord[]; tasks: TaskRecord[]; ideas: IdeaRecord[] }>({
+  projects: [],
+  tasks: [],
+  ideas: [],
+})
+/**
+ * device(桌面端)在线探测(F-#95)。
+ *
+ * 问题:wsStatus=connected 仅表 relay 握手成功(中继链路通),relay 纯透传不广播 device presence,
+ * 故「device 是否在线」无法从 ws 状态直接得 —— device 离线时 miniapp 点发无响应,用户体验差。
+ *
+ * 探测口径:收到 `AiConversationList` 响应 = device 在线(route_list_conversations 由 device 桥接层发出)。
+ * - list_conversations 命令经 ws→relay→device,device 响应 AiConversationList 透传回 miniapp。
+ * - 收到即置 true;device 离线/命令未达则永不置 true,文案保持「已连接中继」诚实表述。
+ *
+ * 注:MVP 不做超时复位(device 离线后不回退 deviceOnline=false),因 device 离线时连 send 超时兜底
+ * 已覆盖(15s 后 reset generating + 错误提示),deviceOnline 仅影响状态文案,容许滞后。
+ */
+const deviceOnline = ref<boolean>(false)
+
+/**
+ * 流式看门狗(miniapp 状态机健壮性,对齐桌面 STREAM_TIMEOUT_MS — memory devflow-generating-statemachine)
+ *
+ * 治「发送不了」根因:旧 15s send 超时首事件即 clearSendTimeout(:189),首事件到达后中途断
+ * (后端 hang/网络断不发 AiCompleted/AiError)无兜底 → generating 永卡 true → 后续 handleSend 被
+ * `generating` 守卫拦截 → 点发无响应(消息停留输入框)。
+ *
+ * 现机制(130s 持续 watchdog,非首事件清除):
+ * - send 后 resetWatchdog 启动
+ * - 活跃事件(AiTextDelta/AiAgentRound/AiToolCallStarted/Heartbeat/Retry)resetWatchdog 重置 130s
+ * - 终态(AiCompleted/AiError)/挂起(Approval/DirAuth/MaxRounds/Help)/断连 clearWatchdog 清除
+ * - 超时(130s 无活跃事件)= 中途断 → flush + 错误气泡 + reset generating,用户可重发
+ */
+let streamTimer: ReturnType<typeof setTimeout> | null = null
+// 130s(对齐桌面 STREAM_TIMEOUT_MS,≥后端 120s idle timeout + 余量)。
+const STREAM_TIMEOUT_MS = 130000
+
+/**
+ * 停止标志(F9:stop 终态兜底)。治「点了停止还在生成」:stop 命令在途期间 device 可能续推
+ * AiTextDelta(持续 reset 看门狗致 generating 卡 true)。stop() 成功后乐观复位 generating + 置
+ * stopping,handleEvent 对 AiTextDelta/AiAgentRound 提前 return 忽略迟到增量;终态事件清 stopping。
+ * 无超时(布尔无泄漏,至下次 send/终态自然清)。
+ */
+let stopping = false
+
+/** 看门狗超时回调:中途断兜底(flush + 错误气泡 + reset generating) */
+function onStreamTimeout(): void {
+  streamTimer = null
+  if (generating.value) {
+    flushCurrentText()
+    currentText.value = ''
+    generating.value = false
+    messages.push({
+      id: genId('timeout'),
+      role: 'assistant',
+      content: '⚠ 回复中断(桌面端长时间无响应),请检查连接后重试',
+      isError: true,
+      timestamp: Date.now(),
+    })
+  }
+}
+
+/** 重置看门狗(send 后启动 / 活跃事件重置,确保 watchdog 运行计 STREAM_TIMEOUT_MS) */
+function resetWatchdog(): void {
+  if (streamTimer) clearTimeout(streamTimer)
+  streamTimer = setTimeout(onStreamTimeout, STREAM_TIMEOUT_MS)
+}
+
+/** 清除看门狗(终态/挂起/断连触发,timer 彻底停) */
+function clearWatchdog(): void {
+  if (streamTimer) clearTimeout(streamTimer)
+  streamTimer = null
+}
 
 /** 已注册事件监听标志(防多次订阅 wsClient) */
 let subscribed = false
@@ -80,9 +237,19 @@ function findToolCall(id: string): AiToolCallInfo | null {
   return null
 }
 
-/** 流式文本回填到最后一条 assistant 气泡(对齐桌面 flushCurrentText,useAiEvents.ts:186) */
+/** 流式文本回填到当前轮 assistant 气泡(F3:按 id 精确,回退启发式) */
 function flushCurrentText(): void {
   if (!currentText.value) return
+  // F3:优先按记录的 id 精确写入(治 retry/error/compressed 气泡穿插致启发式定位错位)
+  if (currentAssistantMsgId.value) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].id === currentAssistantMsgId.value) {
+        messages[i].content = currentText.value
+        return
+      }
+    }
+  }
+  // 回退启发式:取末尾第一个非 error assistant(id 失配时兼容,对齐桌面 useAiEvents.ts:186)
   for (let i = messages.length - 1; i >= 0; i--) {
     const m = messages[i]
     if (m.role !== 'assistant') break
@@ -102,6 +269,105 @@ function flushCurrentText(): void {
  * - 路由判断:无 conversation_id 或等于 active 时处理,其他忽略
  */
 export function handleEvent(event: AiChatEvent): void {
+  // 诊断:事件类型 + 频率(排查 device 持续推流式致 view 层过载 / tap 失效)
+  console.log('[dbg:event] type=', event.type)
+  // F-#95:会话列表同步是全局事件(无 conversation_id),不受单会话路由守卫约束,
+  // 提前处理,避免下方 event.conversation_id narrowing 报错(该变体无此字段)。
+  if (event.type === 'AiConversationList') {
+    // splice 替换(conversations 是 reactive 数组,直接赋值丢响应性)
+    conversations.splice(0, conversations.length, ...event.conversations)
+    // 收到响应即 device 在线(探测成功),chat 页状态文案据此切「已连接桌面端」。
+    deviceOnline.value = true
+    return
+  }
+
+  // F-#95 联想扩展:`/` 技能列表同步(全局事件,提前处理避免 conversation_id narrowing —— 该变体无此字段)。
+  // route_list_skills(device 桥接层)调 ai_list_skills → publish_event(AiSkillList) 跨端透传回 miniapp。
+  // 收到即 splice 替换 skills(chat/index.vue `/` 联想浮层消费),并置 deviceOnline=true(响应=在线)。
+  if (event.type === 'AiSkillList') {
+    skills.splice(0, skills.length, ...event.skills)
+    deviceOnline.value = true
+    return
+  }
+
+  // F-#95 联想扩展:`@` 实体列表同步(全局事件,提前处理避免 conversation_id narrowing —— 该变体无此字段)。
+  // route_list_entities(device 桥接层)调 list_projects/list_tasks/list_ideas → publish_event(AiEntityList)。
+  // 收到即 splice 替换三类实体(chat/index.vue `@` 联想浮层消费),并置 deviceOnline=true。
+  if (event.type === 'AiEntityList') {
+    entities.projects.splice(0, entities.projects.length, ...event.projects)
+    entities.tasks.splice(0, entities.tasks.length, ...event.tasks)
+    entities.ideas.splice(0, entities.ideas.length, ...event.ideas)
+    deviceOnline.value = true
+    return
+  }
+
+  // F-260622-02 跨端用户消息同步:device route_send_message 放行后 publish_event 广播,
+  // miniapp 自身也订阅 ai_event_bus,故此事件会回灌 miniapp 自己。去重防双气泡:
+  // 最近一条 user 气泡已是同 content(send 时本地乐观 push 过)则跳过,否则补 user 气泡。
+  // 提前处理(在 convId narrowing 之前),因该事件必带 conversation_id 但语义独立于 watchdog/
+  // generating 态,不应触发活跃事件 reset。
+  //
+  // MINIAPP-01(P1)去重失效修复:旧判定仅看 messages 末条 role==='user',但 send() 乐观 push 后
+  // 紧跟 assistant 占位气泡(:499-504),AiUserMessage 回灌时末条是 assistant 占位,role!=='user'
+  // 成立 → 误判「未重复」→ push 第二个重复 user 气泡(夹在乐观 user 与 assistant 占位之间错位)。
+  // 改:从末尾向前扫,跳过非 user 气泡(占位/系统),取最近一条 user 比 content。
+  if (event.type === 'AiUserMessage') {
+    // P1-4/P1-5:会话守卫。AiUserMessage 由 device route_send_message publish_event 广播,
+    // miniapp 自身也订阅 ai_event_bus → 自回灌;多设备同 relay 时他机消息也广播到本机。
+    // 切会话/新建会话后旧会话的 AiUserMessage 异步回流会污染新会话视图(串话)。
+    // 守卫:事件带 conversation_id 且非当前会话也非最近 load 目标 → 丢弃(乐观 push 已在发送方本地渲染)。
+    // 保留 null 放行(新会话首条,active 也可能 null,避免误杀自回灌)。
+    const uc = event.conversation_id ?? null
+    if (uc && uc !== activeConversationId.value && uc !== lastLoadedConvId.value) {
+      console.warn(
+        `[useAiChat] AiUserMessage conv=${uc} 非当前会话(active=${activeConversationId.value})丢弃,防串话`,
+      )
+      return
+    }
+    let lastUser: ChatMessage | undefined
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === 'user') {
+        lastUser = messages[i]
+        break
+      }
+    }
+    if (!(lastUser && lastUser.content === event.message)) {
+      messages.push({
+        id: genId('user'),
+        role: 'user',
+        content: event.message,
+        timestamp: Date.now(),
+      })
+    }
+    return
+  }
+
+  // F-#95 扩展:历史消息同步(全局事件,提前处理避免 conversation_id narrowing)。
+  // 仅当消息属当前活跃会话才替换(防串会话:device 可能推非当前 conv 历史)。
+  if (event.type === 'AiMessageHistory') {
+    const histConv = event.conversation_id
+    const isActive = histConv === activeConversationId.value
+    // MINIAPP-02:竞态兜底。用户快速 A→B→A 或切后 newConversation() 置 null,
+    // 会使 activeConversationId 在历史回流前已变 → is_active=false → 49 条历史静默丢弃。
+    // 优先按 active 写入;其次若与最近发起的 load 目标相符,仍写入(用户停留该会话时
+    // 不应丢);都不符(确实已切走)才丢,并 console.warn 明确原因(非静默)。
+    const isLastLoaded = histConv !== null && histConv === lastLoadedConvId.value
+    if (isActive || isLastLoaded) {
+      if (!isActive) {
+        console.warn(
+          `[useAiChat] 历史回流 conv=${histConv} active=${activeConversationId.value} 已切走,但与最近 load 目标相符,仍写入(竞态兜底)`,
+        )
+      }
+      // splice 替换(messages 是 reactive 数组,保留响应性)
+      messages.splice(0, messages.length, ...event.messages)
+    } else {
+      console.warn(
+        `[useAiChat] 历史 conv=${histConv} 因会话已切换被丢弃(active=${activeConversationId.value} lastLoaded=${lastLoadedConvId.value}) count=${event.messages.length}`,
+      )
+    }
+    return
+  }
+
   const convId = event.conversation_id ?? null
 
   // 首次收到事件同步当前对话 id(对齐桌面 useAiEvents.ts:705)
@@ -113,17 +379,28 @@ export function handleEvent(event: AiChatEvent): void {
   const isCurrent = !convId || convId === activeConversationId.value
   if (!isCurrent) return
 
+  // 收到当前会话活跃事件 = device 在响应,重置看门狗(重新计 130s)。
+  // 终态/挂起事件在各自 case 内 clearWatchdog 覆盖此 reset。
+  // F9:stopping 期间不重置(stop 已 clearWatchdog,迟到 delta 不应续命看门狗)
+  if (!stopping) resetWatchdog()
+
   switch (event.type) {
     case 'AiTextDelta':
+      // F9:stopping 期间忽略迟到增量(用户已点停止,device 续推 delta 丢弃,防文本回填)
+      if (stopping) break
       currentText.value += event.delta
       break
 
     case 'AiAgentRound': {
+      // F9:stopping 期间忽略新一轮(用户已停,device 未及时停的续推不新建气泡)
+      if (stopping) break
       // 新一轮:flush 当前文本到上一条 assistant,新建空 assistant 占位
       flushCurrentText()
       currentText.value = ''
+      const roundPlaceholderId = genId('ai')
+      currentAssistantMsgId.value = roundPlaceholderId // F3:记录新一轮目标气泡
       messages.push({
-        id: genId('ai'),
+        id: roundPlaceholderId,
         role: 'assistant',
         content: '',
         timestamp: Date.now(),
@@ -155,11 +432,12 @@ export function handleEvent(event: AiChatEvent): void {
     }
 
     case 'AiMaxRoundsReached':
-      // 达 max 暂停:miniapp 展示提示气泡(不实现继续/停止按钮,用户回桌面处理)
+      clearWatchdog() // 达 max 挂起,停看门狗
+      maxRoundsActive.value = true // P1-E:chat 渲染「继续/停止循环」按钮(替代旧「回桌面处理」)
       messages.push({
         id: genId('maxrounds'),
         role: 'system',
-        content: '⚠ 已达最大轮次,请在桌面端处理(继续/停止)',
+        content: '⚠ 已达最大轮次,可选择继续或停止',
         timestamp: Date.now(),
       })
       break
@@ -190,6 +468,10 @@ export function handleEvent(event: AiChatEvent): void {
       // 移除对应挂起审批(若有)
       const idx = pendingApprovals.findIndex((p) => p.id === event.id)
       if (idx >= 0) pendingApprovals.splice(idx, 1)
+      // P2-E:工具执行完成 → 清回填标志(审批已生效执行,不再回填)
+      if (lastApprovedTc.value && lastApprovedTc.value.id === event.id) {
+        lastApprovedTc.value = null
+      }
       break
     }
 
@@ -208,7 +490,11 @@ export function handleEvent(event: AiChatEvent): void {
         reason: event.reason,
         diff: event.diff ?? undefined,
       }
-      pendingApprovals.push(info)
+      // req3 去重:sync_pending 重发 + 实时事件竞态可能同 id 重复,面板只保留一条
+      if (!pendingApprovals.some((p) => p.id === info.id)) {
+        pendingApprovals.push(info)
+      }
+      clearWatchdog() // 挂起等审批,停看门狗(用户操作后续生成会 reset 重启)
       const tc = findToolCall(event.id)
       if (tc) {
         tc.status = 'pending_approval'
@@ -225,25 +511,49 @@ export function handleEvent(event: AiChatEvent): void {
       }
       const idx = pendingApprovals.findIndex((p) => p.id === event.id)
       if (idx >= 0) pendingApprovals.splice(idx, 1)
+      // P2-E:审批结果确认(批准/拒绝均落定)→ 清回填标志(该 id 已定,不再回填)
+      if (lastApprovedTc.value && lastApprovedTc.value.id === event.id) {
+        lastApprovedTc.value = null
+      }
       break
     }
 
-    case 'AiDirAuthRequired':
-      // 路径授权:miniapp 仅提示(不实现授权 UI,用户回桌面处理)
-      messages.push({
-        id: genId('dirauth'),
-        role: 'system',
-        content: `⚠ 路径授权请求:${event.tool} → ${event.dir}(请在桌面端处理)`,
-        timestamp: Date.now(),
-      })
+    case 'AiDirAuthRequired': {
+      clearWatchdog() // 挂起等授权,停看门狗
+      // F-#95 P0-3:路径授权进 pendingApprovals(kind=path),chat 页渲染 once/always/deny 按钮
+      // (替代旧 system 文案降级「请在桌面端处理」,miniapp 成轻量审批终端,治 loop 卡死)。
+      const authInfo: AiToolCallInfo = {
+        id: event.id,
+        name: event.tool,
+        args: {},
+        status: 'pending_approval',
+        kind: 'path',
+        dir: event.dir,
+        path: event.path,
+      }
+      // req3 去重:同 AiApprovalRequired(sync_pending 重发 + 实时事件竞态防重复)
+      if (!pendingApprovals.some((p) => p.id === authInfo.id)) {
+        pendingApprovals.push(authInfo)
+      }
+      // 对齐 AiApprovalRequired:同步更新消息内工具卡片为 pending_approval + path 授权信息,
+      // 使 chat 页消息内联渲染 once/always/deny 按钮(单一渲染源,避免消息 tc 卡 running 态)。
+      const authTc = findToolCall(event.id)
+      if (authTc) {
+        authTc.status = 'pending_approval'
+        authTc.kind = 'path'
+        authTc.dir = event.dir
+        authTc.path = event.path
+      }
       break
+    }
 
     case 'AiCompleted': {
+      stopping = false // F9:终态清停止标志
       flushCurrentText()
       currentText.value = ''
       generating.value = false
       agentRound.value = 0
-      // token 用量(可选展示)
+      clearWatchdog() // 终态:停看门狗
       tokenUsage.value = {
         prompt: event.prompt_tokens,
         completion: event.completion_tokens,
@@ -262,11 +572,20 @@ export function handleEvent(event: AiChatEvent): void {
     }
 
     case 'AiError': {
+      stopping = false // F9:终态清停止标志
       flushCurrentText()
       currentText.value = ''
       generating.value = false
       agentRound.value = 0
+      clearWatchdog() // 终态:停看门狗
       pendingApprovals.splice(0, pendingApprovals.length)
+      // P2-E:审批失败回填 —— 刚 approve(approved=true)成功发出但 device 返 AiError(执行失败/已被
+      // 桌面端处理),回填 pendingApprovals 让用户重试,避免 UI 误导「已批准」实际未生效。
+      if (lastApprovedTc.value) {
+        pendingApprovals.push(lastApprovedTc.value)
+        uni.showToast({ title: '审批操作未生效,请重试', icon: 'none' })
+        lastApprovedTc.value = null
+      }
       messages.push({
         id: genId('err'),
         role: 'assistant',
@@ -278,6 +597,7 @@ export function handleEvent(event: AiChatEvent): void {
     }
 
     case 'AiHelpRequired':
+      clearWatchdog() // 求助挂起,停看门狗
       // 断路器熔断求助:miniapp 展示求助卡(用户在桌面选 option,miniapp 不渲染选项按钮)
       flushCurrentText()
       currentText.value = ''
@@ -306,14 +626,22 @@ export function handleEvent(event: AiChatEvent): void {
       break
 
     case 'AiConvStateChanged':
-      // 统一状态机:generating/stopping → generating=true;idle/error → false
+      // 统一状态机:generating/stopping → generating=true(看门狗已在 :340 reset 续计 130s);
+      // idle/error → false + clearWatchdog(终态停看门狗,兑现 :156 注释承诺,防 timer 泄漏假超时)。
       if (event.conv_state === 'generating' || event.conv_state === 'stopping') {
         generating.value = true
       } else if (event.conv_state === 'idle' || event.conv_state === 'error') {
         generating.value = false
+        clearWatchdog()
+        stopping = false // F9:终态清停止标志
       }
       // compressed 是派生态,保持当前 generating(压缩完回原态)
       break
+
+    default:
+      // 生产可观测兜底:后端新增事件变体时前端可见(:229 dbg:event 是开发日志,不够)
+      console.warn('[useAiChat] 未处理事件类型', (event as { type?: string }).type)
+      break
   }
 }
 
@@ -349,18 +677,40 @@ function subscribeWs(): void {
     onStatus: (status: WsStatus, detail?: string) => {
       wsStatus.value = status
       wsStatusDetail.value = detail ?? ''
+      if (status === 'connected') {
+        // req2/req3:重连/初始连接从远端恢复完整状态(拉完整消息 + 同步挂起审批)
+        syncOnConnect()
+      } else if (status === 'disconnected' || status === 'reconnecting') {
+        // 断开/重连中:清看门狗 + reset generating + device 离线复位
+        // (连接断肯定停,防 generating 卡死拦截后续 send;deviceOnline 置位后需回退,
+        //  否则文案恒显「已连接桌面端」误导用户 —— 旧实现:76-77 注释自认「离线不复位」置位永不回退)
+        clearWatchdog()
+        generating.value = false
+        stopping = false // F9:断连清停止标志
+        lastApprovedTc.value = null // P2-E:断连清审批回填标志
+        deviceOnline.value = false
+      }
     },
   })
 }
 
-/** 发 send_message Command(relay → device invoke ai_chat_send) */
-function send(text: string): void {
+/**
+ * 发 send_message Command(relay → device invoke ai_chat_send)
+ *
+ * F-#95 联想扩展:skill(`/<skill>` 选中后透传,后端注入对应 SKILL.md 全文到 prompt)+
+ * spans(`@项目/@任务/@灵感` 选中后透传 mention_spans,后端 resolve 投影成 Augmentation)。
+ * 二者均可选,空/undefined=普通对话零回归。
+ */
+function send(text: string, skill?: string | null, spans?: MentionSpan[] | null): void {
   const trimmed = text.trim()
+  console.log('[dbg:send] enter trimmed=', JSON.stringify(trimmed), 'gen=', generating.value)
   if (!trimmed) return
   if (generating.value) {
     console.warn('[useAiChat] 生成中,忽略新发送')
     return
   }
+  stopping = false // F9:新 generation 清停止标志(上次 stop 后重启)
+  maxRoundsActive.value = false // P1-E:新 generation 清 MaxRounds 挂起
 
   // 本地先 push user 气泡(乐观渲染,对齐桌面 sendMessage)
   messages.push({
@@ -370,9 +720,11 @@ function send(text: string): void {
     timestamp: Date.now(),
   })
 
-  // 新建 assistant 占位气泡(等待流式增量填充)
+  // 新建 assistant 占位气泡(等待流式增量填充);记录 id 供 flushCurrentText 精确回填(F3)
+  const aiPlaceholderId = genId('ai')
+  currentAssistantMsgId.value = aiPlaceholderId
   messages.push({
-    id: genId('ai'),
+    id: aiPlaceholderId,
     role: 'assistant',
     content: '',
     timestamp: Date.now(),
@@ -385,9 +737,14 @@ function send(text: string): void {
     args: {
       message: trimmed,
       conversation_id: activeConversationId.value,
+      // skill/spans 仅在有值时透传(对齐 ai_chat_send Option 参数,None 走默认路径)
+      ...(skill ? { skill } : {}),
+      ...(spans && spans.length > 0 ? { mention_spans: spans } : {}),
     },
   }
-  if (!wsClient.send(cmd)) {
+  const _sent = wsClient.send(cmd)
+  console.log('[dbg:send] wsClient.send 返回=', _sent)
+  if (!_sent) {
     // 发送失败:在 assistant 占位气泡显错误
     flushCurrentText()
     messages.push({
@@ -398,6 +755,9 @@ function send(text: string): void {
       timestamp: Date.now(),
     })
     generating.value = false
+  } else {
+    // 发送成功:启动流式看门狗(活跃事件 reset,终态/挂起/断开 clear,超时 reset generating 防卡死)
+    resetWatchdog()
   }
 }
 
@@ -410,11 +770,35 @@ function stop(): void {
       conversation_id: activeConversationId.value,
     },
   }
-  wsClient.send(cmd)
+  if (!wsClient.send(cmd)) {
+    // P1-6:发送失败(ws.send 返 false,如 relay 中断但 wsStatus 尚未翻转)必须复位 generating,
+    // 否则后端永不推 AiCompleted(命令未达)→ generating 永卡 → 后续 send 被守卫拦截。
+    // 对齐 send() 发送失败分支:clearWatchdog + flush + 错误提示 + reset generating。
+    uni.showToast({ title: '未连接,操作未发出', icon: 'none' })
+    clearWatchdog()
+    flushCurrentText()
+    currentText.value = ''
+    generating.value = false
+    return
+  }
+  // F9:发送成功乐观停止反馈。不等 device 推 AiConvStateChanged idle(在途 delta 续 reset 看门狗
+  // 致「点了停止还在生成」)。立即 flush 当前文本(用户可见已生成部分)+ 复位 generating +
+  // clearWatchdog + 置 stopping(忽略迟到 delta/新轮)。终态事件/下次 send/切会话清 stopping。
+  flushCurrentText()
+  currentText.value = ''
+  generating.value = false
+  clearWatchdog()
+  stopping = true
 }
 
 /** 重发最后一条 user 消息(重新 send_message) */
 function regenerate(): void {
+  // 生成中守卫:send() 内虽有 generating 守卫但静默 return 无反馈,这里显式 toast 提示。
+  // (避免用户点重发后末尾气泡被 pop 但无新消息生成,以为卡死)
+  if (generating.value) {
+    uni.showToast({ title: '生成中,请先停止', icon: 'none' })
+    return
+  }
   // 找最后一条 user 消息
   let lastUserText = ''
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -447,10 +831,19 @@ function approve(toolCallId: string, approved: boolean): void {
       approved,
     },
   }
-  wsClient.send(cmd)
-  // 乐观从挂起列表移除(对齐 AiApprovalResult 事件处理,避免 UI 卡 pending)
+  if (!wsClient.send(cmd)) {
+    // 发送失败:wsClient.send 返 false(未连接),提示用户操作未发出,挂起审批保留(下次可重批)
+    uni.showToast({ title: '未连接,操作未发出', icon: 'none' })
+    return
+  }
+  // 发送成功才乐观移除挂起审批(对齐 AiApprovalResult 事件处理,避免 UI 卡 pending)。
+  // 旧实现无条件乐观移除:send 失败时用户已批但命令未发,挂起条目消失误导用户以为已批。
   const idx = pendingApprovals.findIndex((p) => p.id === toolCallId)
-  if (idx >= 0) pendingApprovals.splice(idx, 1)
+  if (idx >= 0) {
+    // P2-E:批准(approved=true)记录,device 返 AiError 时回填让用户重试(执行失败/已被桌面端处理)
+    if (approved) lastApprovedTc.value = pendingApprovals[idx]
+    pendingApprovals.splice(idx, 1)
+  }
 }
 
 /**
@@ -468,7 +861,10 @@ function authorizeDir(toolCallId: string, decision: 'once' | 'always' | 'deny'):
       decision,
     },
   }
-  wsClient.send(cmd)
+  if (!wsClient.send(cmd)) {
+    // 发送失败:wsClient.send 返 false(未连接),提示用户操作未发出
+    uni.showToast({ title: '未连接,操作未发出', icon: 'none' })
+  }
 }
 
 /**
@@ -488,6 +884,7 @@ function continueLoop(conversationId?: string | null): void {
     args: { conversation_id: convId },
   }
   wsClient.send(cmd)
+  maxRoundsActive.value = false // P1-E:用户已选继续,收起按钮
 }
 
 /**
@@ -508,32 +905,157 @@ function stopLoop(conversationId?: string | null): void {
     args: { conversation_id: convId },
   }
   wsClient.send(cmd)
+  maxRoundsActive.value = false // P1-E:用户已选停止,收起按钮
 }
 
 /** 切换会话(switch Command → device 切 active_conversation_id) */
 function switchConversation(convId: string): void {
   activeConversationId.value = convId
-  // 清空当前视图(新会话消息从 device 同步或留空)
+  // P1-8:持久化激活会话,冷启动据此恢复。
+  persistActiveConv(convId)
+  // MINIAPP-02:记录本次 load 目标,AiMessageHistory 回流时除 active 外还比对它,
+  // 防止用户快速切会话致 active 在回流前已变 → 历史静默丢弃。置位须早于 load_messages 发送。
+  lastLoadedConvId.value = convId
+  // 清空当前视图,等 AiMessageHistory 事件回流替换(对齐列表链路异步语义)。
   messages.splice(0, messages.length)
   currentText.value = ''
+  currentAssistantMsgId.value = null // F3:复位精确回填目标
+  stopping = false // F9:切会话清停止标志
+  maxRoundsActive.value = false // P1-E:切会话清 MaxRounds 挂起
+  lastApprovedTc.value = null // P2-E:切会话清审批回填标志(防跨会话误回填)
   generating.value = false
+  // MINIAPP-03:清残留挂起状态,防旧会话审批卡/超时回调污染新会话视图(对齐 newConversation)。
+  pendingApprovals.splice(0, pendingApprovals.length)
+  clearWatchdog()
 
+  // F-#95 扩展:发 load_messages 拉历史(device route_load_messages 读库 → AiMessageHistory 回流)。
+  // 不发 switch_conversation(后端 §2.2 决策 a 忽略,无 Tauri command 对应)。
   const cmd: MiniCommand = {
-    cmd: 'switch_conversation',
+    cmd: 'load_messages',
     args: { conversation_id: convId },
   }
   wsClient.send(cmd)
 }
 
+/**
+ * 拉取会话列表(F-#95)。
+ *
+ * 发 `list_conversations` Command → device route_list_conversations 读库 →
+ * 推回 `AiConversationList` 事件(handleEvent 替换 conversations + 置 deviceOnline=true)。
+ *
+ * 调用时机:
+ * - ws 握手成功后(ws.ts handleHandshakeResponse,device 在线探测 + 首屏列表)
+ * - 会话列表页下拉刷新(conversations/index.vue onPullDownRefresh)
+ *
+ * 注:返回值仅表「命令是否发出」(wsClient.send bool),列表实际更新经事件异步回流
+ * (非 request-reply 同步返回,对齐 relay 纯透传单向语义)。
+ */
+function refreshConversations(): boolean {
+  const cmd: MiniCommand = {
+    cmd: 'list_conversations',
+    args: {},
+  }
+  return wsClient.send(cmd)
+}
+
+/**
+ * 拉取技能列表(F-#95 `/` 联想扩展)。
+ *
+ * 发 `list_skills` Command → device route_list_skills 调 ai_list_skills →
+ * 推回 `AiSkillList` 事件(handleEvent 替换 skills reactive 数组)。
+ *
+ * 调用时机:chat 页输入框文本以 `/` 开头时(技能联想浮层渲染前)。
+ *
+ * 注:返回值仅表「命令是否发出」(wsClient.send bool),列表实际更新经事件异步回流
+ * (非 request-reply 同步返回,对齐 relay 纯透传单向语义)。
+ */
+function listSkills(): boolean {
+  const cmd: MiniCommand = {
+    cmd: 'list_skills',
+    args: {},
+  }
+  return wsClient.send(cmd)
+}
+
+/**
+ * 拉取实体列表(F-#95 `@` 联想扩展,项目/任务/灵感三类聚合)。
+ *
+ * 发 `list_entities` Command → device route_list_entities 并行调
+ * list_projects/list_tasks/list_ideas → 推回 `AiEntityList` 事件
+ * (handleEvent 替换 entities.projects/tasks/ideas 三个数组)。
+ *
+ * 调用时机:chat 页输入框末尾触发 `@` 时(实体联想浮层渲染前)。
+ *
+ * 注:返回值仅表「命令是否发出」(wsClient.send bool),列表实际更新经事件异步回流
+ * (非 request-reply 同步返回,对齐 relay 纯透传单向语义)。
+ */
+function listEntities(): boolean {
+  const cmd: MiniCommand = {
+    cmd: 'list_entities',
+    args: {},
+  }
+  return wsClient.send(cmd)
+}
+
 /** 新建会话(本地清空 + 切到 null,下次 send 时 device 创建新 conv) */
 function newConversation(): void {
   activeConversationId.value = null
+  // P1-8:清持久化(新建会话,冷启动不再恢复到旧会话)。
+  persistActiveConv(null)
+  // MINIAPP-02:作废最近 load 目标,防切换前已发的 load_messages 历史回流时
+  // 命中宽松兜底(isLastLoaded)污染本应空白的新会话视图。
+  lastLoadedConvId.value = null
   messages.splice(0, messages.length)
   currentText.value = ''
+  currentAssistantMsgId.value = null // F3:复位精确回填目标
+  stopping = false // F9:新会话清停止标志
+  maxRoundsActive.value = false // P1-E:新会话清 MaxRounds 挂起
+  lastApprovedTc.value = null // P2-E:新会话清审批回填标志
   generating.value = false
   pendingApprovals.splice(0, pendingApprovals.length)
 }
 
+/**
+ * 重连/初始连接同步(req2 断网不丢消息 + req3 审批状态恢复)。
+ *
+ * 连接成功后从远端恢复完整权威状态:
+ * - req2:发 load_messages 拉当前会话完整历史(断网期间 missed 消息恢复;兼修冷启动空白 P1-C)。
+ * - req3:清本地 pendingApprovals + 发 sync_pending,device 重推挂起审批事件重建卡片
+ *   (断网期间可能错过审批事件,或桌面端已处理;清+重推拿权威状态,避本地陈旧)。
+ *
+ * 审批卡从 pendingApprovals 独立面板渲染(与 messages 解耦),故 load_messages 替换 messages
+ * 不影响审批卡(避重连时两异步响应乱序竞态:load_messages 替换 vs sync_pending 重建)。
+ *
+ * 无 activeConversationId(新建会话/未选会话)则跳过(无目标 conv 可同步)。
+ */
+function syncOnConnect(): void {
+  const convId = activeConversationId.value
+  if (!convId) return
+  // req2:拉完整历史
+  wsClient.send({ cmd: 'load_messages', args: { conversation_id: convId } })
+  // req3:清本地 pending + 发 sync_pending 重推权威审批状态
+  pendingApprovals.splice(0, pendingApprovals.length)
+  wsClient.send({ cmd: 'sync_pending', args: { conversation_id: convId } })
+}
+
+/**
+ * 重命名会话(rename_conversation Command → relay → device invoke ai_conversation_rename)。
+ *
+ * 成功后 device 推 AiConversationList 刷新(列表 reactive 见新标题)。本地乐观更新标题即时反馈。
+ */
+function renameConversation(convId: string, title: string): boolean {
+  const trimmed = title.trim()
+  if (!trimmed) return false
+  // 乐观本地更新(即时反馈,列表事件回流确认)
+  const conv = conversations.find((c) => c.id === convId)
+  if (conv) conv.title = trimmed
+  const cmd: MiniCommand = {
+    cmd: 'rename_conversation',
+    args: { conversation_id: convId, title: trimmed },
+  }
+  return wsClient.send(cmd)
+}
+
 /**
  * useAiChat 单例 hook
  *
@@ -550,6 +1072,7 @@ export function useAiChat() {
     currentText,
     generating,
     agentRound,
+    maxRoundsActive,
     conversations,
     activeConversationId,
     wsStatus,
@@ -557,6 +1080,10 @@ export function useAiChat() {
     isWsConnected,
     tokenUsage,
     pendingApprovals,
+    deviceOnline,
+    // F-#95 联想扩展:技能/实体列表(`/<skill>` 与 `@项目/@任务/@灵感`)
+    skills,
+    entities,
     // 方法
     connect: () => wsClient.connect(),
     disconnect: () => wsClient.disconnect(),
@@ -565,6 +1092,10 @@ export function useAiChat() {
     stop,
     regenerate,
     switchConversation,
+    renameConversation,
+    refreshConversations,
+    listSkills,
+    listEntities,
     newConversation,
     approve,
     authorizeDir,
@@ -572,5 +1103,16 @@ export function useAiChat() {
     stopLoop,
     handleEvent,
     friendlyError,
+    // P1-9/P1-10:后台定时器清理(App.vue onHide/onShow 调)
+    pauseBackground: () => {
+      // 停后台定时器(心跳 + 流式看门狗),保留连接
+      clearWatchdog()
+      wsClient.pauseBackground()
+    },
+    resumeBackground: () => {
+      // 前台恢复:重启心跳/重连 + 若仍在生成重启看门狗
+      wsClient.resumeBackground()
+      if (generating.value && !streamTimer) resetWatchdog()
+    },
   }
 }