@cmach_socket/opencode-qq-bot 0.3.0 → 0.3.2

package/README.md

@@ -67,7 +67,6 @@ bun install
 | `sendDelayMs`                       | `QQ_SEND_DELAY_MS`              | `1000`        | 超长消息分段发送时每段之间的间隔                |
 | `warnLength`                        | `QQ_WARN_LENGTH`                | `20`          | 一轮回复总长度超过该值时告警                    |
 | `reuseSession`                      | `QQ_REUSE_SESSION`              | `false`       | 没有保存的绑定时，按会话标记找回上一次的会话    |
-| `busyTimeoutMs`                     | `QQ_BUSY_TIMEOUT_MS`            | `300000`      | 会话超过该时长未结束视为卡死，强制放行缓存消息  |
 | `proactive.enabled`                 | `QQ_PROACTIVE_ENABLED`          | `true`        | 是否启用主动说话                                |
 | `proactive.silenceThresholdSeconds` | `QQ_PROACTIVE_SILENCE_SECONDS`  | `10800`       | 沉默多久后才开始计算主动说话概率                |
 | `proactive.startProbability`        | `QQ_PROACTIVE_P_START`          | `0.01`        | 刚跨过阈值时的概率                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmach_socket/opencode-qq-bot",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "OpenCode V2 plugin bridging a QQ group chat (NapCat via NapLink) to an OpenCode session.",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,6 +35,7 @@
     "@naplink/naplink": "1.2.0",
     "@opencode/plugin": "2.2.5",
     "@opencode/schema": "2.2.5",
+    "async-mutex": "^0.5.0",
     "zod": "4.6.7"
   },
   "devDependencies": {

package/src/config.ts

@@ -66,8 +66,6 @@ export interface QQBotConfig {
   warnLength: number
   /** 重启后是否复用上一次的会话。 */
   reuseSession: boolean
-  /** 会话忙碌超过该时长（毫秒）视为卡死，强制放行缓存的消息。 */
-  busyTimeoutMs: number
   proactive: ProactiveConfig
   reminder: ReminderConfig
 }
@@ -79,7 +77,6 @@ export const DEFAULT_CONFIG: Omit<QQBotConfig, "napcat"> = {
   sendDelayMs: 1000,
   warnLength: 20,
   reuseSession: false,
-  busyTimeoutMs: 300_000,
   proactive: {
     enabled: true,
     silenceThresholdSeconds: 3 * 3600,
@@ -287,7 +284,6 @@ function createConfigSchema(
     sendDelayMs: nonNegative("sendDelayMs", defaults.sendDelayMs),
     warnLength: integer("warnLength", defaults.warnLength, 1),
     reuseSession: boolean("reuseSession", defaults.reuseSession),
-    busyTimeoutMs: positive("busyTimeoutMs", defaults.busyTimeoutMs),
     proactive: z
       .object({
         enabled: boolean("proactive.enabled", defaults.proactive.enabled),
@@ -329,7 +325,6 @@ const ENV_VARS = {
   sendDelayMs: "QQ_SEND_DELAY_MS",
   warnLength: "QQ_WARN_LENGTH",
   reuseSession: "QQ_REUSE_SESSION",
-  busyTimeoutMs: "QQ_BUSY_TIMEOUT_MS",
   "proactive.enabled": "QQ_PROACTIVE_ENABLED",
   "proactive.silenceThresholdSeconds": "QQ_PROACTIVE_SILENCE_SECONDS",
   "proactive.startProbability": "QQ_PROACTIVE_P_START",
@@ -350,7 +345,6 @@ const OPTION_KEYS = new Set([
   "sendDelayMs",
   "warnLength",
   "reuseSession",
-  "busyTimeoutMs",
   "proactive",
   "reminder",
 ])

package/src/index.ts

@@ -1,5 +1,6 @@
 import { Plugin } from "@opencode/plugin"
 import type { GroupMessageEvent, MessageEvent } from "@naplink/naplink"
+import { Mutex } from "async-mutex"
 import { type ChatTarget, configuredTargets, isTargetEnabled, targetKey, targetLabel } from "./chat"
 import { resolveConfig, type QQBotConfig } from "./config"
 import { claimInstance } from "./instance"
@@ -102,17 +103,28 @@ export default Plugin.define({
       await manager.handleIdle(event.sessionID, event.background)
     })
 
-    // 真正空闲（含后台任务结束）后，把忙碌期间缓存的消息合并成新的一轮。
-    // 失败或中断不会触发 idle 钩子，也要在这里释放状态；订阅断掉后自动重连。
+    // 会话空闲后，把队列里缓存的消息合并成新的一轮。
+    // `session.status` 是官方推荐的状态信号；2.2.5 实际只在执行结束时发
+    // `session.execution.succeeded`，所以两者都要监听。失败或中断单独结束轮次。
+    // 订阅断掉后自动重连。
     const idleAbort = new AbortController()
     void (async () => {
       while (!idleAbort.signal.aborted) {
         try {
           for await (const event of ctx.event.subscribe({
-            types: ["session.idle", "session.execution.failed", "session.execution.interrupted"],
+            types: [
+              "session.status",
+              "session.execution.succeeded",
+              "session.execution.failed",
+              "session.execution.interrupted",
+            ],
             signal: idleAbort.signal,
           })) {
-            if (event.type === "session.idle") {
+            if (event.type === "session.status") {
+              if (event.data.status.type === "idle") {
+                await manager.flushBuffered(event.data.sessionID)
+              }
+            } else if (event.type === "session.execution.succeeded") {
               await manager.flushBuffered(event.data.sessionID)
             } else {
               await manager.handleExecutionEnd(event.data.sessionID, event.type)
@@ -165,25 +177,30 @@ export default Plugin.define({
     }
 
     // 同一会话内串行处理，避免图片下载、成员查询等异步操作打乱消息顺序。
-    const processing = new Map<string, Promise<void>>()
+    const processing = new Map<string, Mutex>()
+    const processingMutex = (key: string): Mutex => {
+      let mutex = processing.get(key)
+      if (!mutex) {
+        mutex = new Mutex()
+        processing.set(key, mutex)
+      }
+      return mutex
+    }
     const scheduleMessage = (event: MessageEvent) => {
       const target = eventTarget(event)
       if (!isTargetEnabled(config, target)) return
       const selfId = String(event.self_id ?? client.selfId ?? "")
       if (selfId && String(event.user_id) === selfId) return
 
+      if (!manager.rememberIncoming(target, String(event.message_id))) {
+        logger.debug(`忽略重复消息 ${event.message_id}`)
+        return
+      }
       manager.touch(target)
-      manager.rememberIncoming(target, String(event.message_id))
 
-      const key = targetKey(target)
-      const previous = processing.get(key) ?? Promise.resolve()
-      const task = previous
-        .then(() => handleMessage(event, target, selfId))
+      void processingMutex(targetKey(target))
+        .runExclusive(() => handleMessage(event, target, selfId))
         .catch((error: unknown) => logger.error(`处理 ${targetLabel(target)} 消息失败`, error))
-      processing.set(key, task)
-      void task.finally(() => {
-        if (processing.get(key) === task) processing.delete(key)
-      })
     }
 
     // 先注册监听再连接：NapCat 连接期间推送的消息也会被收到。
@@ -194,13 +211,11 @@ export default Plugin.define({
 
     // 主动说话心跳。
     let timer: ReturnType<typeof setInterval> | undefined
-    let ticking = false
     if (config.proactive.enabled) {
+      const tickMutex = new Mutex()
       const tick = async () => {
-        if (ticking) return
-        ticking = true
-        try {
-          await manager.recoverStale()
+        if (tickMutex.isLocked()) return
+        await tickMutex.runExclusive(async () => {
           for (const target of configuredTargets(config)) {
             const probability = proactiveTickProbability(
               config.proactive,
@@ -210,12 +225,10 @@ export default Plugin.define({
             logger.info(`${targetLabel(target)} 沉默达到阈值，主动发起话题`)
             await manager.proactive(target, PROACTIVE_HINT)
           }
-        } finally {
-          ticking = false
-        }
+        })
       }
       timer = setInterval(() => {
-        void tick()
+        void tick().catch((error: unknown) => logger.error("主动说话心跳失败", error))
       }, config.proactive.tickSeconds * 1000)
       const handle = timer as { unref?: () => void }
       handle.unref?.()

package/src/naplink/client.ts

@@ -8,6 +8,83 @@ import {
 import type { Logger } from "../logger"
 import type { NapcatConfig } from "../config"
 
+const MEDIA_SEGMENT_TYPES = ["image", "video", "record", "audio", "file"] as const
+
+type MediaSegmentType = (typeof MEDIA_SEGMENT_TYPES)[number]
+
+interface MediaSegmentData {
+  file?: string
+  file_id?: string
+  url?: string
+}
+
+interface MediaFileLike {
+  file?: unknown
+  url?: unknown
+}
+
+function isMediaSegmentType(type: string): type is MediaSegmentType {
+  return (MEDIA_SEGMENT_TYPES as readonly string[]).includes(type)
+}
+
+/** 取第一个可下载的 http(s) 直链，忽略本地路径与 base64。 */
+export function pickRemoteUrl(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && /^https?:\/\//i.test(value)) return value
+  }
+  return undefined
+}
+
+/**
+ * 补全单个媒体段的远程直链。
+ *
+ * NapCat 同时返回本地路径（`file`）和 CDN 直链（`url`），SDK 自带的补全逻辑
+ * 会优先选用本地路径，导致插件无法下载。这里只写入 `url`，且优先使用 http(s) 地址。
+ */
+export async function hydrateSegment(
+  api: OneBotApi,
+  segment: MessageSegment,
+  logger: Logger,
+): Promise<void> {
+  if (!isMediaSegmentType(segment.type)) return
+  const data = segment.data as MediaSegmentData
+  // 已有可用的远程直链时不要覆盖。
+  if (pickRemoteUrl(data.url)) return
+  const fileId = data.file ?? data.file_id
+  if (typeof fileId !== "string" || fileId.length === 0) return
+  if (/^(file|base64|data):/i.test(fileId)) return
+
+  try {
+    const file = (await api.getFile(fileId)) as MediaFileLike | undefined
+    const direct = pickRemoteUrl(file?.url, file?.file)
+    if (direct) {
+      data.url = direct
+      return
+    }
+    if (segment.type === "image") {
+      const image = (await api.getImage(fileId)) as MediaFileLike | undefined
+      const imageUrl = pickRemoteUrl(image?.url, image?.file)
+      if (imageUrl) data.url = imageUrl
+    } else if (segment.type === "record" || segment.type === "audio") {
+      const record = (await api.getRecord(fileId, "mp3")) as MediaFileLike | undefined
+      const recordUrl = pickRemoteUrl(record?.url, record?.file)
+      if (recordUrl) data.url = recordUrl
+    }
+  } catch (error) {
+    logger.debug(`补全媒体直链失败 type=${segment.type} file=${fileId}`, error)
+  }
+}
+
+/** 补全一条消息里所有媒体段的远程直链。 */
+export async function hydrateMedia(
+  api: OneBotApi,
+  message: MessageSegment[],
+  logger: Logger,
+): Promise<void> {
+  if (!Array.isArray(message)) return
+  await Promise.all(message.map((segment) => hydrateSegment(api, segment, logger)))
+}
+
 /** NapCat 的连接与 API 门面，屏蔽 SDK 细节。 */
 export class QQClient {
   private readonly link: NapLink
@@ -105,7 +182,7 @@ export class QQClient {
   /** 补全消息里媒体段的直链，便于下载图片。 */
   async hydrate(message: MessageSegment[]): Promise<void> {
     try {
-      await this.link.hydrateMessage(message)
+      await hydrateMedia(this.api, message, this.logger)
     } catch (error) {
       this.logger.warn("补全媒体直链失败", error)
     }

package/src/naplink/media.ts

@@ -83,6 +83,11 @@ function truncateCodePoints(text: string, max: number): string {
   return Array.from(text).slice(0, max).join("")
 }
 
+/** 截断过长的地址，避免日志被超长 URL 淹没。 */
+function truncateForLog(value: string, max = 120): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value
+}
+
 /** 判断主机名是否指向本机或内网，避免下载请求打内网服务。 */
 export function isPrivateHost(hostname: string): boolean {
   let host = hostname.trim().toLowerCase()
@@ -199,7 +204,10 @@ export class MediaStore {
       return { bytes, mime }
     }
     if (url.startsWith("data:")) return parseDataUrl(url)
-    if (!url.startsWith("http://") && !url.startsWith("https://")) return undefined
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      this.logger.warn(`不支持的图片地址，跳过下载 url=${truncateForLog(url)}`)
+      return undefined
+    }
 
     let parsed: URL
     try {

package/src/naplink/render.ts

@@ -2,6 +2,7 @@ import type { MessageEvent, MessageSegment, OneBotApi } from "@naplink/naplink"
 import type { ChatTarget } from "../chat"
 import { targetKey } from "../chat"
 import type { Logger } from "../logger"
+import { hydrateSegment } from "./client"
 import {
   MAX_IMAGE_BYTES,
   inlineImageBytes,
@@ -174,8 +175,10 @@ async function renderForwardSegments(
           break
         case "image": {
           parts.push("[图片]")
+          if (budget.images <= 0) break
+          await hydrateSegment(ctx.api, segment, ctx.logger)
           const url = segment.data.url || segment.data.file
-          if (!url || budget.images <= 0) break
+          if (!url) break
           const stored = await ctx.media.storeImage(url)
           if (!stored || !takeImage(budget, stored)) break
           images.push(stored)
@@ -363,8 +366,10 @@ export async function renderMessage(
           break
         case "image": {
           textBuffer.push("[图片] ")
+          if (budget.images <= 0) break
+          await hydrateSegment(ctx.api, segment, ctx.logger)
           const url = segment.data.url || segment.data.file
-          if (!url || budget.images <= 0) break
+          if (!url) break
           const stored = await ctx.media.storeImage(url)
           if (!stored || !takeImage(budget, stored)) break
           imageIndex += 1

package/src/session/manager.ts

@@ -1,4 +1,6 @@
+import { randomUUID } from "node:crypto"
 import type { Plugin } from "@opencode/plugin"
+import { Mutex } from "async-mutex"
 import { type ChatTarget, isTargetEnabled, parseTargetKey, targetKey, targetLabel } from "../chat"
 import type { QQBotConfig } from "../config"
 import type { Logger } from "../logger"
@@ -14,8 +16,26 @@ export const MAX_BUFFER_TURNS = 100
 export const MAX_BUFFER_BYTES = 32 * 1024 * 1024
 /** 每个目标最多记录的消息 ID 数量。 */
 const MAX_TRACKED_MESSAGES = 200
+/** 刚投递的一轮还没在上游体现出忙碌状态，先跳过对账避免重复投递。 */
+export const SUBMIT_GRACE_MS = 5_000
+function toMillis(value: unknown): number | undefined {
+  if (value instanceof Date) return value.getTime()
+  if (typeof value === "number") return value
+  return undefined
+}
 
+/** 上游会话是否仍在执行；依据 `time.busy` 是否晚于 `time.idle`。 */
+function upstreamRunning(time: unknown): boolean {
+  if (!time || typeof time !== "object") return false
+  const { busy, idle } = time as { busy?: unknown; idle?: unknown }
+  const busyAt = toMillis(busy)
+  if (busyAt === undefined) return false
+  const idleAt = toMillis(idle)
+  return idleAt === undefined || busyAt > idleAt
+}
 export interface Turn {
+  /** 投递幂等键；重试时保持不变，避免上游重复执行同一轮。 */
+  id?: string
   /** 交给模型的文本。 */
   text: string
   /** 图片附件。 */
@@ -29,14 +49,12 @@ export interface Turn {
 interface ChatState {
   target: ChatTarget
   sessionID?: string
-  /** 会话是否正在跑模型（收到消息到 idle 之间）。 */
-  busy: boolean
-  /** 进入忙碌状态的时间戳（毫秒），用于识别卡死的会话。 */
-  busySince: number
-  /** 忙碌超时看门狗。 */
-  busyTimer?: ReturnType<typeof setTimeout>
-  /** 忙碌期间攒下的消息，空闲后合并成一次 prompt。 */
+  /** 等上游空闲后要投递的消息。 */
   buffer: Turn[]
+  /** 最近一次投递的时间戳（毫秒）。 */
+  lastDispatchAt: number
+  /** 最近一次上游确认空闲的时间戳（毫秒）。 */
+  idleAt: number
   /** 当前轮次的消息，供系统提示注入 @ 提示。 */
   current?: Turn
   /** 当前轮次模型是否还没调用发送工具。 */
@@ -51,6 +69,8 @@ type SessionListCursor = NonNullable<Parameters<Plugin.Context["session"]["list"
 
 export function mergeTurns(turns: readonly Turn[]): Turn {
   return {
+    // 合并后的批次沿用第一条消息的幂等键，重试时保持一致。
+    ...(turns[0]?.id ? { id: turns[0].id } : {}),
     text: turns
       .map((turn) => turn.text.trim())
       .filter((text) => text.length > 0)
@@ -77,13 +97,14 @@ function turnBytes(turn: Turn): number {
 export class SessionManager {
   private readonly states = new Map<string, ChatState>()
   private readonly sessions = new Map<string, ChatState>()
-  private readonly ensureRequests = new Map<string, Promise<string | undefined>>()
+  private readonly targetMutexes = new Map<string, Mutex>()
+  private readonly ensureMutexes = new Map<string, Mutex>()
   private readonly verifiedSessions = new Set<string>()
   private readonly outgoing = new Map<string, Set<string>>()
   private readonly incoming = new Map<string, Set<string>>()
+  private readonly saveMutex = new Mutex()
   private activity: Record<string, number> = {}
   private bindingsLoaded: Promise<void> | undefined
-  private saveQueue: Promise<void> = Promise.resolve()
 
   constructor(
     private readonly ctx: Plugin.Context,
@@ -140,7 +161,9 @@ export class SessionManager {
 
   /** 绑定或活跃时间变化后写回插件存储，串行执行避免互相覆盖。 */
   private scheduleSave(): void {
-    this.saveQueue = this.saveQueue.then(() => this.persist())
+    void this.saveMutex
+      .runExclusive(() => this.persist())
+      .catch((error: unknown) => this.logger.error("保存会话状态失败", error))
   }
 
   private async persist(): Promise<void> {
@@ -170,8 +193,28 @@ export class SessionManager {
 
   /** 等待所有待写入的绑定落盘。 */
   async flush(): Promise<void> {
-    await this.saveQueue
-    await this.persist()
+    await this.saveMutex.runExclusive(() => this.persist())
+  }
+
+  /** 取目标对应的互斥锁，保证同一目标的状态变更与投递串行执行。 */
+  private targetMutex(target: ChatTarget): Mutex {
+    const key = targetKey(target)
+    let mutex = this.targetMutexes.get(key)
+    if (!mutex) {
+      mutex = new Mutex()
+      this.targetMutexes.set(key, mutex)
+    }
+    return mutex
+  }
+
+  private ensureMutex(target: ChatTarget): Mutex {
+    const key = targetKey(target)
+    let mutex = this.ensureMutexes.get(key)
+    if (!mutex) {
+      mutex = new Mutex()
+      this.ensureMutexes.set(key, mutex)
+    }
+    return mutex
   }
 
   private state(target: ChatTarget): ChatState {
@@ -180,9 +223,9 @@ export class SessionManager {
     if (!state) {
       state = {
         target,
-        busy: false,
-        busySince: 0,
         buffer: [],
+        lastDispatchAt: 0,
+        idleAt: 0,
         awaitingSend: false,
         reminders: 0,
         lastUserMessageAt: this.activity[key] ?? Date.now(),
@@ -192,33 +235,6 @@ export class SessionManager {
     return state
   }
 
-  private beginBusy(state: ChatState): void {
-    state.busy = true
-    state.busySince = Date.now()
-    this.armBusyTimer(state)
-  }
-
-  private armBusyTimer(state: ChatState): void {
-    this.clearBusyTimer(state)
-    state.busyTimer = setTimeout(() => {
-      void this.recoverTarget(state.target)
-    }, this.config.busyTimeoutMs)
-    const timer = state.busyTimer as { unref?: () => void }
-    timer.unref?.()
-  }
-
-  private clearBusyTimer(state: ChatState): void {
-    if (state.busyTimer === undefined) return
-    clearTimeout(state.busyTimer)
-    state.busyTimer = undefined
-  }
-
-  private endBusy(state: ChatState): void {
-    state.busy = false
-    state.busySince = 0
-    this.clearBusyTimer(state)
-  }
-
   /** 会话 ID 反查目标。 */
   targetForSession(sessionID: string): ChatTarget | undefined {
     return this.sessions.get(sessionID)?.target
@@ -260,10 +276,15 @@ export class SessionManager {
     return this.outgoing.get(targetKey(target))?.has(messageId) ?? false
   }
 
-  /** 记录一条收到的消息，语音转写工具只能操作这些消息。 */
-  rememberIncoming(target: ChatTarget, messageId: string): void {
+  /**
+   * 记录一条收到的消息，语音转写工具只能操作这些消息。
+   *
+   * 返回该 ID 是否首次出现，用于忽略 NapCat 重连后重放的同一条消息。
+   */
+  rememberIncoming(target: ChatTarget, messageId: string): boolean {
     const key = targetKey(target)
     const ids = this.incoming.get(key) ?? new Set<string>()
+    const isNew = !ids.has(messageId)
     ids.add(messageId)
     while (ids.size > MAX_TRACKED_MESSAGES) {
       const oldest = ids.values().next().value
@@ -271,6 +292,7 @@ export class SessionManager {
       ids.delete(oldest)
     }
     this.incoming.set(key, ids)
+    return isNew
   }
 
   /** 判断消息是否属于当前目标最近收到的消息。 */
@@ -294,16 +316,14 @@ export class SessionManager {
     return (Date.now() - this.state(target).lastUserMessageAt) / 1000
   }
 
-  /**
-   * 收到一条消息：空闲则直接投进会话，忙则先缓存。
-   */
+  /** 收到一条消息：先入队，再尝试投递；上游忙时留在队列里。 */
   async enqueue(target: ChatTarget, turn: Turn): Promise<void> {
     const state = this.state(target)
-    if (state.busy) {
-      this.pushBuffered(state, turn)
-      return
-    }
-    await this.dispatch(state, turn)
+    const queued = turn.id ? turn : { ...turn, id: randomUUID() }
+    await this.targetMutex(target).runExclusive(async () => {
+      this.pushBuffered(state, queued)
+      await this.drain(state)
+    })
   }
 
   private pushBuffered(state: ChatState, turn: Turn): void {
@@ -321,16 +341,66 @@ export class SessionManager {
     if (state.buffer.length === 1 && bytes > MAX_BUFFER_BYTES) {
       this.logger.warn(`${targetLabel(state.target)} 单条消息超过缓存上限，仍保留该消息`)
     }
-    this.logger.debug(
-      `${targetLabel(state.target)} 忙碌中，消息已缓存（累计 ${state.buffer.length} 条）`,
-    )
+    this.logger.debug(`${targetLabel(state.target)} 消息已入队（累计 ${state.buffer.length} 条）`)
   }
 
-  /** 把一轮消息投进 OpenCode 会话。 */
-  private async dispatch(state: ChatState, turn: Turn): Promise<void> {
-    if (state.busy) return
-    // 先同步占位，避免并发消息重复投递
-    this.beginBusy(state)
+  /** 上游会话是否仍在执行。 */
+  private async sessionRunning(sessionID: string): Promise<boolean> {
+    try {
+      const info = await this.ctx.session.get({ sessionID })
+      return upstreamRunning((info as { time?: unknown }).time)
+    } catch (error) {
+      this.logger.debug(`查询会话 ${sessionID} 状态失败`, error)
+      return false
+    }
+  }
+
+  /**
+   * 结束信号是否属于更早的轮次。
+   *
+   * 上游 `time.idle` 只在执行结束时更新；它早于本次投递时间，说明这是上一轮
+   * 迟到的 idle/结束事件，不能用来清理当前轮次的状态。
+   */
+  private async idleIsStale(state: ChatState): Promise<boolean> {
+    if (!state.sessionID || state.lastDispatchAt === 0) return false
+    try {
+      const info = await this.ctx.session.get({ sessionID: state.sessionID })
+      const time = (info as { time?: { idle?: unknown } }).time
+      const idleAt = toMillis(time?.idle)
+      return idleAt !== undefined && idleAt < state.lastDispatchAt
+    } catch (error) {
+      this.logger.debug(`${targetLabel(state.target)} 查询会话结束时间失败`, error)
+      return false
+    }
+  }
+
+  /**
+   * 每次投递前都以上游状态为准：上游仍在跑就留在队列里，空闲才合并投递。
+   * `force` 仅用于上游已经明确发出结束事件的场景。
+   */
+  private async drain(state: ChatState, force = false): Promise<void> {
+    if (state.buffer.length === 0) return
+    if (!force && state.sessionID && this.verifiedSessions.has(state.sessionID)) {
+      if (await this.sessionRunning(state.sessionID)) {
+        this.logger.debug(
+          `${targetLabel(state.target)} 上游仍在执行，保留 ${state.buffer.length} 条消息`,
+        )
+        return
+      }
+      // 刚投递的轮次可能还没在上游留下忙碌时间，先给它一点时间。
+      const idleConfirmed = state.idleAt > 0 && state.idleAt >= state.lastDispatchAt
+      if (!idleConfirmed && Date.now() - state.lastDispatchAt < SUBMIT_GRACE_MS) return
+    }
+
+    const turns = state.buffer
+    state.buffer = []
+    if (!(await this.dispatch(state, mergeTurns(turns)))) {
+      state.buffer = [...turns, ...state.buffer]
+    }
+  }
+
+  /** 把一轮消息投进 OpenCode 会话；失败时由调用方放回队列。 */
+  private async dispatch(state: ChatState, turn: Turn): Promise<boolean> {
     state.current = turn
     state.awaitingSend = true
     // 新的用户轮次重新给一份提醒预算，否则连续几轮不调工具就再也提醒不了。
@@ -339,36 +409,31 @@ export class SessionManager {
     try {
       const sessionID = await this.ensureSession(state.target)
       if (!sessionID) {
-        this.endBusy(state)
         state.current = undefined
         state.awaitingSend = false
-        return
+        return false
       }
       await this.ctx.session.prompt({
         sessionID,
+        ...(turn.id ? { id: turn.id } : {}),
         text: turn.text,
         ...(turn.files.length > 0 ? { files: turn.files } : {}),
       })
+      state.lastDispatchAt = Date.now()
       this.logger.debug(`${label} 已投递消息到会话 ${sessionID}`)
+      return true
     } catch (error) {
-      this.endBusy(state)
       state.current = undefined
       state.awaitingSend = false
       this.logger.error(`${label} 投递消息失败`, error)
-      const buffered = state.buffer
-      state.buffer = []
-      if (buffered.length > 0) {
-        await this.dispatch(state, mergeTurns(buffered))
-      }
+      return false
     }
   }
 
   /**
-   * 会话即将空闲：若有缓存消息，保持忙碌等 session.idle 后再投递；
-   * 否则清掉忙碌标记，若模型这一轮没调用发送工具则提醒它补一次。
+   * 会话即将空闲：有缓存就等结束事件再投递；否则按需提醒模型补一次发送。
    *
-   * `background` 只统计本会话自己的后台任务；子会话遗留的任务不会唤醒本会话，
-   * 不能因此让目标一直保持忙碌。
+   * `background` 只统计本会话自己的后台任务；子会话遗留的任务不会唤醒本会话。
    */
   async handleIdle(
     sessionID: string,
@@ -376,30 +441,39 @@ export class SessionManager {
   ): Promise<void> {
     const state = this.sessions.get(sessionID)
     if (!state) return
-    const label = targetLabel(state.target)
+    await this.targetMutex(state.target).runExclusive(async () => {
+      const label = targetLabel(state.target)
 
-    if (background.some((task) => task.sessionID === sessionID)) {
-      this.logger.debug(`${label} 仍有后台任务，保持忙碌状态`)
-      return
-    }
+      if (background.some((task) => task.sessionID === sessionID)) {
+        this.logger.debug(`${label} 仍有后台任务，暂不投递缓存`)
+        return
+      }
 
-    if (state.buffer.length > 0) {
-      // 在 idle 钩子里投递会被并入旧的一轮；保持忙碌，等真正空闲后再开始新一轮。
-      this.logger.debug(`${label} 空闲，等待投递 ${state.buffer.length} 条缓存消息`)
-      return
-    }
+      if (await this.idleIsStale(state)) {
+        this.logger.debug(`${label} 忽略上一轮迟到的 idle 信号`)
+        return
+      }
 
-    this.endBusy(state)
-    state.current = undefined
+      if (state.buffer.length > 0) {
+        // 在 idle 钩子里投递会被并入旧的一轮；等结束事件后再作为新的一轮投递。
+        this.logger.debug(`${label} 空闲，等待投递 ${state.buffer.length} 条缓存消息`)
+        return
+      }
+
+      state.current = undefined
+
+      if (
+        !state.awaitingSend ||
+        !this.config.reminder.enabled ||
+        state.reminders >= this.config.reminder.max
+      ) {
+        state.idleAt = Date.now()
+        return
+      }
 
-    if (
-      state.awaitingSend &&
-      this.config.reminder.enabled &&
-      state.reminders < this.config.reminder.max
-    ) {
       state.reminders += 1
-      // 合成消息会唤醒会话再跑一轮，先占位避免新消息插队。
-      this.beginBusy(state)
+      state.idleAt = 0
+      state.lastDispatchAt = Date.now()
       state.current = { text: "[提醒]", files: [], atMe: false }
       this.logger.warn(`${label} 模型未调用发送工具，提醒第 ${state.reminders} 次`)
       try {
@@ -408,82 +482,64 @@ export class SessionManager {
           text: `[提醒] 你这一轮没有调用任何发送工具，直接输出的文字会被丢弃。请调用 qq_send_message 工具：想回复就 reply=true 并给出 content，不想回复就 reply=false；发送图片、语音、转发或戳一戳也视为已回复。`,
         })
       } catch (error) {
-        this.endBusy(state)
         state.awaitingSend = false
         this.logger.error(`${label} 发送提醒失败`, error)
       }
-    }
+    })
   }
 
-  /**
-   * 模型执行失败或被中断：idle 钩子不会触发，必须主动释放忙碌状态并处理缓存。
-   */
+  /** 模型执行失败或被中断：结束事件之后直接放行缓存。 */
   async handleExecutionEnd(sessionID: string, reason: string): Promise<void> {
     const state = this.sessions.get(sessionID)
     if (!state) return
-    this.logger.warn(`${targetLabel(state.target)} 会话执行结束（${reason}），释放忙碌状态`)
-    this.endBusy(state)
-    state.current = undefined
-    state.awaitingSend = false
-    if (state.buffer.length > 0) {
-      await this.flushBuffered(sessionID)
-    }
-  }
-
-  /** 超时看门狗：会话长时间没有 idle 时强制放行缓存。 */
-  async recoverTarget(target: ChatTarget): Promise<void> {
-    const state = this.states.get(targetKey(target))
-    if (!state?.busy) return
-    this.logger.warn(`${targetLabel(target)} 会话超时未结束，强制放行缓存消息`)
-    const buffered = state.buffer
-    state.buffer = []
-    this.endBusy(state)
-    state.current = undefined
-    state.awaitingSend = false
-    if (buffered.length > 0) {
-      await this.dispatch(state, mergeTurns(buffered))
-    }
+    await this.targetMutex(state.target).runExclusive(async () => {
+      if (await this.idleIsStale(state)) {
+        this.logger.debug(`${targetLabel(state.target)} 忽略上一轮迟到的结束事件（${reason}）`)
+        return
+      }
+      this.logger.warn(`${targetLabel(state.target)} 会话执行结束（${reason}）`)
+      state.current = undefined
+      state.awaitingSend = false
+      state.idleAt = Date.now()
+      await this.drain(state, true)
+    })
   }
 
-  /** 检查所有目标是否有超过阈值的忙碌会话。 */
-  async recoverStale(): Promise<void> {
-    for (const state of this.states.values()) {
-      if (!state.busy) continue
-      if (Date.now() - state.busySince <= this.config.busyTimeoutMs) continue
-      await this.recoverTarget(state.target)
+  /**
+   * 执行结束事件丢失时，用上游会话状态兜底放行缓存。
+   * 只在上游确认空闲且本轮确实结束后投递，不会打断仍在运行的长轮次。
+   */
+  async resumeBuffered(): Promise<void> {
+    for (const state of this.sessions.values()) {
+      if (state.buffer.length === 0) continue
+      await this.targetMutex(state.target).runExclusive(() => this.drain(state))
     }
   }
 
-  /** 会话真正空闲后，把忙碌期间缓存的消息合并成新的一轮投递。 */
+  /** 会话状态变为 idle 后，把缓存的消息合并成新的一轮投递。 */
   async flushBuffered(sessionID: string): Promise<void> {
     const state = this.sessions.get(sessionID)
     if (!state) return
-    if (state.buffer.length === 0) {
-      // 控制类工作（例如手动压缩）不会触发 idle 钩子，但仍会发 session.idle。
-      // 这里兜底释放可能残留的忙碌状态。
-      this.endBusy(state)
-      state.current = undefined
-      return
-    }
-
-    const turns = state.buffer
-    state.buffer = []
-    this.endBusy(state)
-    state.current = undefined
-    this.logger.debug(`${targetLabel(state.target)} 空闲，合并 ${turns.length} 条缓存消息`)
-    await this.dispatch(state, mergeTurns(turns))
+    await this.targetMutex(state.target).runExclusive(async () => {
+      if (await this.idleIsStale(state)) {
+        this.logger.debug(`${targetLabel(state.target)} 忽略上一轮迟到的结束信号`)
+        return
+      }
+      if (state.buffer.length === 0) {
+        // 只有没有新轮次时，idle 时间才代表当前状态；投递缓存时若也写入，
+        // 会与紧接着的 dispatch 落在同一毫秒，误判为新一轮已经结束。
+        state.idleAt = Date.now()
+        state.current = undefined
+        return
+      }
+      this.logger.debug(`${targetLabel(state.target)} 空闲，投递 ${state.buffer.length} 条缓存消息`)
+      await this.drain(state, true)
+    })
   }
 
-  /** 取得（必要时创建）目标对应的会话；并发调用复用同一个请求。 */
+  /** 取得（必要时创建）目标对应的会话；并发调用串行执行，避免重复建会话。 */
   ensureSession(target: ChatTarget): Promise<string | undefined> {
-    const key = targetKey(target)
-    const pending = this.ensureRequests.get(key)
-    if (pending) return pending
-    const request = this.resolveSession(target).finally(() => {
-      if (this.ensureRequests.get(key) === request) this.ensureRequests.delete(key)
-    })
-    this.ensureRequests.set(key, request)
-    return request
+    return this.ensureMutex(target).runExclusive(() => this.resolveSession(target))
   }
 
   private async resolveSession(target: ChatTarget): Promise<string | undefined> {
@@ -499,6 +555,7 @@ export class SessionManager {
       const reused = await this.findExistingSession(target)
       // 会话已经绑给别的目标时不能复用，改为新建一个会话。
       if (reused && this.bindSession(state, reused)) {
+        this.verifiedSessions.add(reused)
         this.scheduleSave()
         this.logger.info(`${label} 复用已有会话 ${reused}`)
         return reused
@@ -521,6 +578,7 @@ export class SessionManager {
       })
       return undefined
     }
+    this.verifiedSessions.add(created.id)
     this.scheduleSave()
     this.logger.info(`${label} 新建会话 ${created.id}`)
     return created.id
@@ -600,29 +658,35 @@ export class SessionManager {
   /** 主动说话：向目标对应的会话投递一条合成消息。 */
   async proactive(target: ChatTarget, text: string): Promise<void> {
     const state = this.state(target)
-    if (state.busy) return
-    // 在 await 之前占位，避免用户消息或下一次心跳同时投递。
-    this.beginBusy(state)
-    state.current = { text, files: [], atMe: true, proactive: true }
-    state.awaitingSend = true
-    state.reminders = 0
-    try {
-      const sessionID = await this.ensureSession(target)
-      if (!sessionID) {
-        this.endBusy(state)
-        state.current = undefined
+    await this.targetMutex(target).runExclusive(async () => {
+      if (state.buffer.length > 0 || state.current) return
+      // 先占位，避免用户消息或下一次心跳同时投递。
+      state.idleAt = 0
+      state.lastDispatchAt = Date.now()
+      state.current = { text, files: [], atMe: true, proactive: true }
+      state.awaitingSend = true
+      state.reminders = 0
+      try {
+        if (state.sessionID && (await this.sessionRunning(state.sessionID))) {
+          state.current = undefined
+          state.awaitingSend = false
+          return
+        }
+        const sessionID = await this.ensureSession(target)
+        if (!sessionID) {
+          state.current = undefined
+          state.awaitingSend = false
+          return
+        }
+        state.lastUserMessageAt = Date.now()
+        this.activity[targetKey(target)] = state.lastUserMessageAt
+        this.scheduleSave()
+        await this.ctx.session.synthetic({ sessionID, text })
+      } catch (error) {
         state.awaitingSend = false
-        return
+        state.current = undefined
+        this.logger.error(`${targetLabel(target)} 主动说话失败`, error)
       }
-      state.lastUserMessageAt = Date.now()
-      this.activity[targetKey(target)] = state.lastUserMessageAt
-      this.scheduleSave()
-      await this.ctx.session.synthetic({ sessionID, text })
-    } catch (error) {
-      this.endBusy(state)
-      state.current = undefined
-      state.awaitingSend = false
-      this.logger.error(`${targetLabel(target)} 主动说话失败`, error)
-    }
+    })
   }
 }

package/src/tools/qq.ts

@@ -193,7 +193,7 @@ export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promis
         }
         manager.markMessageSent(context.sessionID)
         logger.info(`${label} 已发送 ${content.length} 字`)
-        return text("sent")
+        return text("你已成功发送消息，可以选择结束对话")
       },
     })
 
@@ -220,7 +220,7 @@ export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promis
         const messageId = messageIdOf(response)
         if (messageId) manager.rememberOutgoing(target, messageId)
         manager.markMessageSent(context.sessionID)
-        return text("sent")
+        return text("你已成功发送图片，可以选择结束对话")
       },
     })
 
@@ -246,7 +246,7 @@ export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promis
         const messageId = messageIdOf(response)
         if (messageId) manager.rememberOutgoing(target, messageId)
         manager.markMessageSent(context.sessionID)
-        return text("sent")
+        return text("你已成功发送语音，可以选择结束对话")
       },
     })
 
@@ -301,7 +301,7 @@ export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promis
         const messageId = messageIdOf(response)
         if (messageId) manager.rememberOutgoing(target, messageId)
         manager.markMessageSent(context.sessionID)
-        return text("sent")
+        return text("你已成功发送合并转发消息，可以选择结束对话")
       },
     })
 
@@ -324,7 +324,7 @@ export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promis
         if (!input.user_id) return text("error: 缺少 user_id")
         await sendPoke(target, input.user_id)
         manager.markMessageSent(context.sessionID)
-        return text("sent")
+        return text("你已成功戳一下用户，可以选择结束对话")
       },
     })