@dcrays/dcgchat-test 0.6.1 → 0.6.2

package/src/bot.ts

@@ -0,0 +1,676 @@
+import path from 'node:path'
+import type { OpenClawConfig, ReplyPayload } from 'openclaw/plugin-sdk'
+import { createReplyPrefixContext, createTypingCallbacks } from 'openclaw/plugin-sdk/channel-reply-pipeline'
+import type { IMsgParams, InboundMessage } from './types.js'
+import {
+  formatText,
+  getSessionKey,
+  getWorkspaceDir,
+  isReviserExpert,
+  setMsgStatus,
+  clearSentMediaKeys,
+  removeAllCronMessageIdsForSession,
+  takeApartSessionKey,
+  getDcgchatRuntime,
+  getOpenClawConfig
+} from './utils/global.js'
+import { resolveAccount } from './channel/index.js'
+import {
+  ensureExpertAgentWorkspaceBinding,
+  isAgentInstalled,
+  isAgentInstalling,
+  retryDownloadAgent,
+  waitForAgentInstall
+} from './agent.js'
+import { sendFinal, sendText as sendTextMsg, sendError, sendText } from './transport.js'
+import { dcgLogger } from './utils/log.js'
+import { contextOverflowUserHint, isContextOverflowError } from './utils/agentErrors.js'
+import { isInsufficientBalanceAssistantText } from './utils/passTxt.js'
+import {
+  systemCommand,
+  stopCommand,
+  ignoreToolCommand,
+  CHANNEL_ID,
+  AFTER_STOP_SETTLE_MS,
+  SUBAGENT_IDLE_TIMEOUT_MS
+} from './utils/constant.js'
+import { clearParamsMessage, getEffectiveMsgParams, setParamsMessage } from './utils/params.js'
+import {
+  resetSubagentStateForRequesterSession,
+  waitUntilSubagentsIdle,
+  stringifyToolHookPayload,
+  sendToolCallMessage
+} from './tool.js'
+import { createStreamMergeController } from './utils/streamMerge.js'
+import { createMediaEmitter } from './utils/mediaEmitter.js'
+import {
+  beginDispatchAbortForInboundTurn,
+  clearActiveRunIdForSession,
+  clearSessionStreamSuppression,
+  isSessionStreamSuppressed,
+  releaseDispatchAbortIfCurrent,
+  requestStopInterruption,
+  runInboundTurnSequenced,
+  setActiveRunIdForSession,
+  waitForStopInterruption
+} from './utils/sessionTermination.js'
+import {
+  buildAgentInboundBodySuffix,
+  buildDcgchatInboundMediaPayload,
+  normalizeInboundFileList,
+  resolveMediaFromUrls,
+  type DcgchatInboundMediaInfo
+} from './utils/mediaAttached.js'
+import {
+  bumpInboundGeneration,
+  clearStopSeqForSession,
+  deleteStreamChunkIdxForSession,
+  getInboundGeneration,
+  getStopSeq,
+  resetStreamChunkIdxForSession
+} from './utils/inboundTurnState.js'
+import {
+  clearOutboundTextState,
+  emitOutboundAssistantText,
+  outboundHasEmittedAssistantText,
+  outboundHasStreamedAssistantText,
+  resetOutboundTextState,
+  resetOutboundTextSnapshot
+} from './utils/outboundAssistantText.js'
+
+/**
+ * 本轮入站**已正常收尾**时清理该 sessionKey 的内存态（params、去重、分片、msgStatus、子 agent 本地跟踪等）。
+ * 不可在「stale」或已有新入站占用的场景调用，否则会删掉新一轮写入的 `paramsMessageMap`。
+ * 保留入站 generation（单调计数，见 inboundTurnState）；下一轮 turn 开始时会 bump，旧 handler 用 gen 不等判定 stale。
+ */
+function clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey: string, messageId: string | undefined) {
+  clearParamsMessage(dcgSessionKey)
+  deleteStreamChunkIdxForSession(dcgSessionKey)
+  clearSessionStreamSuppression(dcgSessionKey)
+  clearActiveRunIdForSession(dcgSessionKey)
+  setMsgStatus(dcgSessionKey, '')
+  // 出站媒体去重 bucket：写入时为 `resolveOutboundMediaDedupeKey(messageId, sessionId, sessionKey)` 的结果，
+  // 可能是 messageId / sessionId / sessionKey 之一。turn 收尾时按这三者都清一次，覆盖 messageId 为空的兜底场景。
+  if (messageId) clearSentMediaKeys(messageId)
+  const { sessionId: tookApartSessionId } = takeApartSessionKey(dcgSessionKey)
+  if (tookApartSessionId) clearSentMediaKeys(tookApartSessionId)
+  clearSentMediaKeys(dcgSessionKey)
+  // cronMessageIdMap：sendDcgchatMedia 兜底路径会写一条永不消费的 entry（见 global.removeAllCronMessageIdsForSession 注释），
+  // turn 收尾时整条队列即可视为失效。
+  removeAllCronMessageIdsForSession(dcgSessionKey)
+  resetSubagentStateForRequesterSession(dcgSessionKey)
+  clearOutboundTextState(dcgSessionKey)
+}
+
+const DEFAULT_AGENT_ID = 'main'
+const VALID_AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i
+const INVALID_AGENT_ID_CHARS_RE = /[^a-z0-9_-]+/g
+const LEADING_AGENT_ID_DASH_RE = /^-+/
+const TRAILING_AGENT_ID_DASH_RE = /-+$/
+
+type HumanDelayConfig = NonNullable<NonNullable<NonNullable<OpenClawConfig['agents']>['defaults']>['humanDelay']>
+
+function normalizeDcgAgentId(value: string | undefined): string {
+  const trimmed = (value ?? '').trim()
+  if (!trimmed) return DEFAULT_AGENT_ID
+  const normalized = trimmed.toLowerCase()
+  if (VALID_AGENT_ID_RE.test(trimmed)) return normalized
+  return (
+    normalized
+      .replace(INVALID_AGENT_ID_CHARS_RE, '-')
+      .replace(LEADING_AGENT_ID_DASH_RE, '')
+      .replace(TRAILING_AGENT_ID_DASH_RE, '')
+      .slice(0, 64) || DEFAULT_AGENT_ID
+  )
+}
+
+function resolveDcgHumanDelayConfig(cfg: OpenClawConfig, agentId: string | undefined): HumanDelayConfig | undefined {
+  const defaults = cfg.agents?.defaults?.humanDelay
+  const normalizedAgentId = normalizeDcgAgentId(agentId)
+  const overrides = cfg.agents?.list?.find((entry) => normalizeDcgAgentId(entry.id) === normalizedAgentId)?.humanDelay
+  if (!defaults && !overrides) return undefined
+  return {
+    mode: overrides?.mode ?? defaults?.mode,
+    minMs: overrides?.minMs ?? defaults?.minMs,
+    maxMs: overrides?.maxMs ?? defaults?.maxMs
+  }
+}
+
+const typingCallbacks = createTypingCallbacks({
+  start: async () => {},
+  onStartError: (err) => {
+    dcgLogger(`typing start error: ${String(err)}`, 'error')
+  }
+})
+
+function sendAbortFinalForInterruptedTurn(ctx: IMsgParams, stopMessageId: string | undefined, sessionKey: string): void {
+  const interruptedMessageId = ctx.messageId?.trim()
+  if (!interruptedMessageId || interruptedMessageId === stopMessageId?.trim()) return
+  sendFinal(ctx, 'abort')
+  dcgLogger(`stop abort final for interrupted turn: sessionKey=${sessionKey} messageId=${interruptedMessageId}`)
+}
+
+/** `/stop` 是 control message：立即 ack 当前消息，再用 stop barrier 终止旧 run 并阻塞后续普通消息。 */
+async function handleStopControlMessage(msg: InboundMessage, accountId: string, interruptedOutboundCtx: IMsgParams | undefined): Promise<void> {
+  const config = getOpenClawConfig()
+  if (!config) {
+    return
+  }
+  const account = resolveAccount(config, accountId)
+  const dcgSessionKey = getSessionKey(msg.content, account.accountId)
+  const conversationId = msg.content.session_id?.trim()
+  const mergedParams = {
+    userId: msg._userId,
+    botToken: msg.content.bot_token,
+    sessionId: conversationId,
+    messageId: msg.content.message_id,
+    domainId: msg.content.domain_id,
+    appId: config.channels?.[CHANNEL_ID]?.appId || 100,
+    botId: msg.content.bot_id ?? '',
+    agentId: msg.content.agent_id ?? '',
+    sessionKey: dcgSessionKey,
+    real_mobook: msg.content.real_mobook?.toString().trim()
+  }
+  setParamsMessage(dcgSessionKey, mergedParams)
+  const outboundCtx = getEffectiveMsgParams(dcgSessionKey)
+  sendFinal(outboundCtx, 'stop')
+  const { started, barrier } = requestStopInterruption(dcgSessionKey)
+  if (started && interruptedOutboundCtx) {
+    sendAbortFinalForInterruptedTurn(interruptedOutboundCtx, msg.content.message_id, dcgSessionKey)
+  }
+  dcgLogger(`stop control ack: sessionKey=${dcgSessionKey} messageId=${msg.content.message_id} started=${started}`)
+  await barrier
+}
+
+/**
+ * 处理一条用户消息，调用 Agent 并返回回复（同会话串行见 sessionTermination.runInboundTurnSequenced）。
+ */
+export async function handleDcgchatMessage(msg: InboundMessage, accountId: string): Promise<void> {
+  const config = getOpenClawConfig()
+  if (!config) {
+    dcgLogger('no OpenClaw config available', 'error')
+    return
+  }
+  const account = resolveAccount(config, accountId)
+  const queueSessionKey = getSessionKey(msg.content, account.accountId)
+  const queueText = (msg.content.text ?? '').trim()
+  const isStopInbound = stopCommand.includes(queueText)
+
+  const interruptedOutboundCtx = isStopInbound ? getEffectiveMsgParams(queueSessionKey) : undefined
+  if (isStopInbound) {
+    await handleStopControlMessage(msg, accountId, interruptedOutboundCtx)
+    return
+  }
+
+  await waitForStopInterruption(queueSessionKey)
+  await runInboundTurnSequenced(queueSessionKey, () => handleDcgchatMessageInboundTurn(msg, accountId))
+}
+
+async function handleDcgchatMessageInboundTurn(msg: InboundMessage, accountId: string): Promise<void> {
+  let config = getOpenClawConfig()
+  if (!config) {
+    return
+  }
+  const account = resolveAccount(config, accountId)
+
+  const core = getDcgchatRuntime()
+
+  const conversationId = msg.content.session_id?.trim()
+  const real_mobook = msg.content.real_mobook?.toString().trim()
+
+  const agentCloneCode = msg.content?.agent_clone_code?.trim() || ''
+
+  if (agentCloneCode) {
+    await ensureExpertAgentWorkspaceBinding(agentCloneCode)
+    const latest = getOpenClawConfig()
+    if (latest) config = latest
+  }
+
+  let route = core.channel.routing.resolveAgentRoute({
+    cfg: config,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: { kind: 'direct', id: conversationId }
+  })
+
+  let effectiveAgentId = route.agentId
+  const dcgSessionKey = getSessionKey(msg.content, account.accountId)
+
+  // 检测是否是 /stop 后的新消息（通过 stopSeq 判断）
+  const previousStopSeq = getStopSeq(dcgSessionKey)
+
+  // 每轮入站先卸掉可能残留的流抑制（如 /stop 与 dispatch 收尾竞态），避免 deliver 全程静默 return
+  clearSessionStreamSuppression(dcgSessionKey)
+  const inboundGenAtStart = bumpInboundGeneration(dcgSessionKey)
+
+  // 检测是否需要开始新任务（新消息而非延续之前的任务）
+  // 条件：是 /stop 后的第一条非 stop 消息。
+  const isAfterStop = previousStopSeq > 0 && !stopCommand.includes((msg.content.text ?? '').trim())
+  const isNewTask = isAfterStop
+
+  const mergedParams = {
+    userId: msg._userId,
+    botToken: msg.content.bot_token,
+    sessionId: conversationId,
+    messageId: msg.content.message_id,
+    domainId: msg.content.domain_id,
+    appId: config.channels?.[CHANNEL_ID]?.appId || 100,
+    botId: msg.content.bot_id ?? '',
+    agentId: msg.content.agent_id ?? '',
+    sessionKey: dcgSessionKey,
+    real_mobook
+  }
+  setParamsMessage(dcgSessionKey, mergedParams)
+  const outboundCtx = getEffectiveMsgParams(dcgSessionKey)
+  let agentDisplayName = null
+
+  dcgLogger(`dcgSessionKey: ${dcgSessionKey} , effectiveAgentId: ${effectiveAgentId} }`)
+
+  let text = msg.content.text?.trim()
+
+  if (!text) {
+    sendTextMsg('你需要我帮你做什么呢？', outboundCtx)
+    sendFinal(outboundCtx, 'not text')
+    clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+    return
+  }
+
+  if (stopCommand.includes(text)) {
+    sendFinal(outboundCtx, 'stop')
+    clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+    return
+  }
+
+  // 校验 agent 是否安装。gateway 重连等场景下可能漏掉安装事件，导致
+  // agent 文件不存在。若正在安装则等待结果；若未安装或安装失败，利用
+  // 缓存的 URL 尝试一次重新下载（只试一次），仍失败则提示网络异常。
+  if (agentCloneCode && dcgSessionKey.includes(agentCloneCode) && !isAgentInstalled(agentCloneCode)) {
+    let agentReady = false
+
+    if (isAgentInstalling(agentCloneCode)) {
+      const installOk = await waitForAgentInstall(agentCloneCode)
+      if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) {
+        dcgLogger(
+          `skip stale install result: sessionKey=${dcgSessionKey} inboundGen=${inboundGenAtStart} current=${getInboundGeneration(dcgSessionKey)}`
+        )
+        return
+      }
+      const isInstalled = isAgentInstalled(agentCloneCode)
+      dcgLogger(`installOk: ${installOk}, isAgentInstalled: ${isInstalled}`)
+      if (!installOk || !isInstalled) {
+        agentReady = await retryDownloadAgent(agentCloneCode)
+      } else {
+        agentReady = true
+      }
+    } else {
+      dcgLogger(`retry install because the agent not installed, ${agentCloneCode}`)
+      agentReady = await retryDownloadAgent(agentCloneCode)
+    }
+
+    dcgLogger(`agentReady: ${agentReady}`)
+    if (!agentReady || !isAgentInstalled(agentCloneCode)) {
+      dcgLogger(`receive agentCloneCode, but agent not ready: ${agentCloneCode}`)
+      sendTextMsg('抱歉，网络异常，请稍后重试', outboundCtx, { message_tags: { source: 'agent_not_found' }, is_finish: -1 })
+      sendFinal(outboundCtx, 'agent_not_installed')
+      clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+      return
+    }
+
+    await ensureExpertAgentWorkspaceBinding(agentCloneCode)
+    const latestAfterInstall = getOpenClawConfig()
+    if (latestAfterInstall) config = latestAfterInstall
+    route = core.channel.routing.resolveAgentRoute({
+      cfg: config,
+      channel: CHANNEL_ID,
+      accountId: account.accountId,
+      peer: { kind: 'direct', id: conversationId }
+    })
+    effectiveAgentId = route.agentId
+    agentDisplayName = config.agents?.list?.find((a) => a.id === effectiveAgentId)?.name || effectiveAgentId || null
+  }
+
+  try {
+    let dispatchReplyErrorHandledByOnError = false
+    if ((msg.content.skills_scope?.length ?? 0) > 0 && !ignoreToolCommand.includes(text?.trim()) && !agentCloneCode) {
+      const workspaceDir = getWorkspaceDir()
+      const skill = msg.content.skills_scope?.[0]
+      if (skill?.skill_code) {
+        const skillDir = path.join(workspaceDir, 'skills', skill.skill_code)
+        const skillText = `用户选择使用此技能："${skill.skill_code}"，技能路径是："${skillDir}"，在目录下查找并`
+        text = `${skillText} ${text}`
+      }
+    }
+    // 处理用户上传的文件（兼容多种下行字段名与单文件对象）
+    const files = normalizeInboundFileList(msg.content as Record<string, unknown>)
+    let mediaListResolved: DcgchatInboundMediaInfo[] = []
+    let mediaPayload: Record<string, unknown> = {}
+    if (files.length > 0) {
+      // 从 OSS 下载 附件内容
+      mediaListResolved = await resolveMediaFromUrls(files, msg.content.bot_token)
+      mediaPayload = buildDcgchatInboundMediaPayload(mediaListResolved)
+    }
+
+    /** 与飞书一致：RawBody/CommandBody 不含系统附件说明，便于指令探测；完整提示在 BodyForAgent */
+    const rawAndCommandBody = text
+
+    // 如果是新任务（/stop 后或任务完成后），添加系统提示
+    let agentInboundText: string
+    if (isNewTask && !agentCloneCode) {
+      const systemPrompt =
+        '[系统提示] 这是一个全新的对话任务，请仅基于当前用户消息回复，不要延续之前的对话内容、未完成的任务或工具调用。当前是一个全新的开始。'
+      agentInboundText = buildAgentInboundBodySuffix(`${systemPrompt}\n\n用户消息：${rawAndCommandBody}`, mediaListResolved)
+    } else {
+      agentInboundText = buildAgentInboundBodySuffix(rawAndCommandBody, mediaListResolved)
+    }
+
+    const ctxPayload = core.channel.inbound.buildContext({
+      channel: CHANNEL_ID,
+      accountId: route.accountId,
+      provider: CHANNEL_ID,
+      surface: CHANNEL_ID,
+      messageId: msg.content.message_id,
+      timestamp: Date.now(),
+      from: dcgSessionKey,
+      sender: {
+        id: dcgSessionKey,
+        name: agentDisplayName ?? undefined
+      },
+      conversation: {
+        kind: 'direct',
+        id: conversationId ?? dcgSessionKey
+      },
+      route: {
+        agentId: effectiveAgentId ?? '',
+        accountId: route.accountId,
+        routeSessionKey: dcgSessionKey,
+        dispatchSessionKey: dcgSessionKey
+      },
+      reply: {
+        to: dcgSessionKey,
+        originatingTo: dcgSessionKey
+      },
+      message: {
+        body: agentInboundText,
+        bodyForAgent: agentInboundText,
+        rawBody: rawAndCommandBody,
+        commandBody: rawAndCommandBody
+      },
+      access: {
+        mentions: {
+          canDetectMention: true,
+          wasMentioned: true
+        }
+      },
+      channelContext: {
+        sender: {
+          id: dcgSessionKey
+        },
+        chat: {
+          id: conversationId ?? dcgSessionKey,
+          sessionId: conversationId,
+          domainId: msg.content.domain_id,
+          appId: msg.content.app_id,
+          botId: msg.content.bot_id,
+          agentId: msg.content.agent_id
+        }
+      },
+      media: mediaListResolved.map((m) => ({
+        path: m.path,
+        contentType: m.contentType || undefined,
+        messageId: msg.content.message_id
+      })),
+      extra: {
+        Target: dcgSessionKey,
+        SourceTarget: dcgSessionKey,
+        SuppressMessageReceivedHooks: true,
+        ...mediaPayload
+      }
+    })
+    const storePath = core.channel.session.resolveStorePath(config.session?.store, { agentId: effectiveAgentId })
+
+    const mediaEmitter = createMediaEmitter({
+      sessionKey: dcgSessionKey,
+      onEmit: () => {
+        hasEmittedAssistantMedia = true
+      }
+    })
+    let hasEmittedAssistantMedia = false
+    // bot 流式/deliver 与 dcgchat_message 共用 outboundAssistantText 快照，避免双发或漏发
+    resetOutboundTextState(dcgSessionKey, inboundGenAtStart)
+    let partialTextSnapshot = ''
+    const streamMerge = createStreamMergeController({
+      sessionKey: dcgSessionKey,
+      inboundGenAtStart,
+      outboundCtx
+    })
+
+    const prefixContext = createReplyPrefixContext({
+      cfg: config,
+      agentId: effectiveAgentId ?? '',
+      channel: CHANNEL_ID,
+      accountId: account.accountId
+    })
+
+    const createDcgDeliveryAdapter = () => ({
+      deliver: async (payload: ReplyPayload, info: { kind: string }) => {
+        if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) return
+        if (isSessionStreamSuppressed(dcgSessionKey)) return
+        if (isInsufficientBalanceAssistantText(payload?.text)) {
+          dcgLogger(`[deliver]: pass text — skip raw insufficient-balance assistant line (plugin llm_output sends user copy)`)
+          return
+        }
+        await mediaEmitter.emitFromPayload(payload)
+        // 未真正发出过流式文本时，deliver/final 快照仍应作为正文兜底发送。
+        if (payload?.text?.trim() && !outboundHasStreamedAssistantText(dcgSessionKey)) {
+          emitOutboundAssistantText(dcgSessionKey, payload.text, outboundCtx, { emitDelta: (delta) => streamMerge.queueDelta(delta) })
+        }
+        const p = payload as Record<string, unknown>
+        const mediaCount = Array.isArray(p.mediaUrls) ? p.mediaUrls.length : p.mediaUrl ? 1 : 0
+        dcgLogger(
+          `[deliver]: kind=${info.kind}, text.length=${payload?.text?.length}, media.length=${mediaCount}, sessionId=${outboundCtx.sessionId}, ${formatText(payload?.text ?? '')}`
+        )
+      },
+      onError: (err: unknown, info: { kind: string }) => {
+        if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) {
+          dcgLogger(`${info.kind} reply failed (stale handler, ignored): ${String(err)}`)
+          return
+        }
+        dispatchReplyErrorHandledByOnError = true
+        const suppressed = isSessionStreamSuppressed(dcgSessionKey)
+        streamMerge.flush(true)
+        if (!suppressed && isContextOverflowError(err)) {
+          sendText(contextOverflowUserHint(), outboundCtx)
+        }
+        sendFinal(outboundCtx, 'error')
+        dcgLogger(`${info.kind} reply failed${suppressed ? ' (stream suppressed)' : ''}: ${String(err)}`, 'error')
+        clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+      }
+    })
+
+    const createDcgReplyDispatcherOptions = () => ({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: resolveDcgHumanDelayConfig(config, effectiveAgentId),
+      onReplyStart: async () => {},
+      onIdle: () => {
+        typingCallbacks.onIdle?.()
+      }
+    })
+
+    // /stop 后立即发下一条时，宿主 reply run 可能尚未从 registry 释放 → 无 llm_input、秒 end。短延迟缓解竞态。
+    if (isAfterStop) {
+      if (AFTER_STOP_SETTLE_MS > 0) {
+        dcgLogger(`after-stop settle: waiting ${AFTER_STOP_SETTLE_MS}ms before dispatch sessionKey=${dcgSessionKey}`)
+        await new Promise<void>((r) => setTimeout(r, AFTER_STOP_SETTLE_MS))
+      }
+      if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) return
+      clearStopSeqForSession(dcgSessionKey)
+      clearSessionStreamSuppression(dcgSessionKey)
+    }
+
+    let dispatchAbort: AbortController | undefined
+    try {
+      resetStreamChunkIdxForSession(dcgSessionKey, 0)
+      dispatchAbort = beginDispatchAbortForInboundTurn(dcgSessionKey)
+      if (!ignoreToolCommand.includes(text?.trim())) {
+        const { text: thinkingContent, callId } = stringifyToolHookPayload('message_received', {}, {}, 'lifecycle')
+        sendToolCallMessage(dcgSessionKey, thinkingContent, callId, 0)
+      }
+      const dispatchReplyAttempt = async () => {
+        const dispatcherOptions = createDcgReplyDispatcherOptions()
+        const delivery = createDcgDeliveryAdapter()
+        await core.channel.inbound.dispatchReply({
+          cfg: config,
+          channel: CHANNEL_ID,
+          accountId: route.accountId,
+          agentId: effectiveAgentId ?? '',
+          routeSessionKey: dcgSessionKey,
+          storePath,
+          ctxPayload,
+          recordInboundSession: core.channel.session.recordInboundSession,
+          dispatchReplyWithBufferedBlockDispatcher: core.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+          delivery,
+          dispatcherOptions,
+          record: {
+            updateLastRoute: {
+              sessionKey: dcgSessionKey,
+              channel: CHANNEL_ID,
+              to: dcgSessionKey,
+              accountId: route.accountId
+            },
+            onRecordError: (err) => {
+              dcgLogger(` session record error: ${String(err)}`, 'error')
+            }
+          },
+          messageId: msg.content.message_id,
+          replyOptions: {
+            abortSignal: dispatchAbort!.signal,
+            onModelSelected: prefixContext.onModelSelected,
+            onAgentRunStart: (runId) => {
+              setActiveRunIdForSession(dcgSessionKey, runId)
+            },
+            onPartialReply: async (payload: ReplyPayload) => {
+              if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) return
+              if (isSessionStreamSuppressed(dcgSessionKey)) return
+              if (isInsufficientBalanceAssistantText(payload.text)) {
+                return
+              }
+              const p = payload as Record<string, unknown>
+              // --- Streaming text chunks / deltas ---
+              if (p.replace === true) {
+                resetOutboundTextSnapshot(dcgSessionKey)
+                streamMerge.flush(true)
+                if (typeof p.text === 'string' && p.text.trim()) {
+                  partialTextSnapshot = p.text
+                  emitOutboundAssistantText(dcgSessionKey, p.text, outboundCtx, {
+                    markStreamed: true,
+                    emitDelta: (delta) => streamMerge.queueDelta(delta)
+                  })
+                }
+              } else if (typeof p.delta === 'string' && p.delta) {
+                partialTextSnapshot += p.delta
+                emitOutboundAssistantText(dcgSessionKey, partialTextSnapshot, outboundCtx, {
+                  markStreamed: true,
+                  emitDelta: (delta) => streamMerge.queueDelta(delta)
+                })
+              } else if (payload.text) {
+                partialTextSnapshot = payload.text
+                emitOutboundAssistantText(dcgSessionKey, payload.text, outboundCtx, {
+                  markStreamed: true,
+                  emitDelta: (delta) => streamMerge.queueDelta(delta)
+                })
+              } else {
+                dcgLogger(`[onPartialReply]: no text (media/tool metadata) keys=${Object.keys(p).join(',')}`)
+              }
+              // --- Media from payload ---
+              await mediaEmitter.emitFromPayload(payload)
+            }
+          }
+        })
+      }
+      await dispatchReplyAttempt()
+      streamMerge.flush(true)
+    } catch (err: unknown) {
+      dcgLogger(`handleDcgchatMessage error: ${String(err)}`, 'error')
+      if (getInboundGeneration(dcgSessionKey) === inboundGenAtStart && !dispatchReplyErrorHandledByOnError) {
+        streamMerge.flush(true)
+        if (!isSessionStreamSuppressed(dcgSessionKey)) {
+          sendText(isContextOverflowError(err) ? contextOverflowUserHint() : '抱歉，这次对话执行时发生异常，请稍后重试。', outboundCtx)
+        }
+        sendFinal(outboundCtx, 'error')
+        releaseDispatchAbortIfCurrent(dcgSessionKey, dispatchAbort)
+        streamMerge.dispose()
+        clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+        return
+      }
+      if (getInboundGeneration(dcgSessionKey) === inboundGenAtStart && dispatchReplyErrorHandledByOnError) {
+        releaseDispatchAbortIfCurrent(dcgSessionKey, dispatchAbort)
+        streamMerge.dispose()
+        return
+      }
+    } finally {
+      if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) {
+        releaseDispatchAbortIfCurrent(dcgSessionKey, dispatchAbort)
+        streamMerge.dispose()
+      }
+    }
+
+    const inboundGenNow = getInboundGeneration(dcgSessionKey)
+    if (inboundGenNow !== inboundGenAtStart) {
+      streamMerge.dispose()
+      dcgLogger(`skip post-reply tail: sessionKey=${dcgSessionKey} (stale handler: inbound gen ${inboundGenAtStart}→${inboundGenNow})`)
+      return
+    }
+
+    if (![...systemCommand, ...stopCommand].includes(text?.trim())) {
+      if (isSessionStreamSuppressed(dcgSessionKey)) {
+        clearSessionStreamSuppression(dcgSessionKey)
+      }
+    }
+    clearSentMediaKeys(msg.content.message_id)
+    try {
+      try {
+        await waitUntilSubagentsIdle(dcgSessionKey, { timeoutMs: SUBAGENT_IDLE_TIMEOUT_MS, signal: dispatchAbort?.signal })
+      } catch (err) {
+        if (dispatchAbort?.signal.aborted || getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) {
+          throw err
+        }
+        const message = err instanceof Error ? err.message : String(err)
+        if (/^waitUntilSubagentsIdle timeout /u.test(message)) {
+          dcgLogger(`subagent idle wait timeout, force cleanup: sessionKey=${dcgSessionKey}, err=${message}`, 'error')
+          resetSubagentStateForRequesterSession(dcgSessionKey)
+        } else {
+          throw err
+        }
+      }
+      // 等待子 agent 期间可能已有新入站消息（generation 已变），不能再 end/finished，否则会误结束新轮或放行错挂的正文。
+      if (getInboundGeneration(dcgSessionKey) !== inboundGenAtStart) {
+        streamMerge.dispose()
+        dcgLogger(
+          `skip post-wait tail: sessionKey=${dcgSessionKey} (stale handler after subagent wait: inbound gen ${inboundGenAtStart}→${getInboundGeneration(dcgSessionKey)})`
+        )
+        return
+      }
+    } finally {
+      releaseDispatchAbortIfCurrent(dcgSessionKey, dispatchAbort)
+    }
+    streamMerge.flush(true)
+    if (!outboundHasEmittedAssistantText(dcgSessionKey) && !hasEmittedAssistantMedia) {
+      dcgLogger(`empty assistant reply: sessionKey=${dcgSessionKey}, messageId=${msg.content.message_id}`, 'error')
+    }
+    if (!isReviserExpert(dcgSessionKey)) {
+      sendFinal(outboundCtx, 'end')
+    } else {
+      dcgLogger(`审校专家跳过终止 sessionKey=${dcgSessionKey}, messageId=${msg.content.message_id}`)
+    }
+    streamMerge.dispose()
+    clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+  } catch (err) {
+    dcgLogger(` handle message failed: ${String(err)}`, 'error')
+    if (getInboundGeneration(dcgSessionKey) === inboundGenAtStart) {
+      const rawErr = err instanceof Error ? err.message : String(err)
+      sendError(isContextOverflowError(err) ? contextOverflowUserHint() : rawErr, outboundCtx)
+      clearDcgSessionKeyCachesForCompletedTurn(dcgSessionKey, msg.content.message_id)
+    }
+  }
+}