@dcrays/dcgchat-test 0.6.1 → 0.6.2

package/src/utils/mediaEmitter.ts

@@ -0,0 +1,54 @@
+import type { ReplyPayload } from 'openclaw/plugin-sdk'
+import { mediaPathDedupeKey } from './global.js'
+import { normalizeOutboundMediaPaths, sendDcgchatMedia } from '../channel/index.js'
+
+export interface MediaEmitter {
+  emitFromPayload(payload: Partial<ReplyPayload>): Promise<boolean>
+  readonly sentKeys: ReadonlySet<string>
+}
+
+export interface CreateMediaEmitterOptions {
+  sessionKey: string
+  onEmit?: () => void
+}
+
+function resolveReplyMediaList(payload: Partial<ReplyPayload>): string[] {
+  if ('mediaUrls' in payload && Array.isArray(payload.mediaUrls) && payload.mediaUrls.length > 0) {
+    return normalizeOutboundMediaPaths(payload.mediaUrls)
+  }
+  const single = 'mediaUrl' in payload ? payload.mediaUrl : null
+  return normalizeOutboundMediaPaths(single ?? null)
+}
+
+export function createMediaEmitter(options: CreateMediaEmitterOptions): MediaEmitter {
+  const { sessionKey, onEmit } = options
+  const sentKeys = new Set<string>()
+
+  const emit = async (mediaUrls: string[]): Promise<boolean> => {
+    if (mediaUrls.length === 0) return false
+    await sendDcgchatMedia({ sessionKey, mediaUrls, text: '' })
+    onEmit?.()
+    return true
+  }
+
+  const emitFromPayload = async (payload: Partial<ReplyPayload>): Promise<boolean> => {
+    const list = resolveReplyMediaList(payload)
+    const urls: string[] = []
+    for (const url of list) {
+      const key = mediaPathDedupeKey(url)
+      if (sentKeys.has(key)) continue
+      sentKeys.add(key)
+      urls.push(url)
+    }
+    if (urls.length === 0) return false
+    await emit(urls)
+    return true
+  }
+
+  return {
+    emitFromPayload,
+    get sentKeys(): ReadonlySet<string> {
+      return new Set(sentKeys)
+    }
+  }
+}

package/src/utils/outboundAssistantText.ts

@@ -0,0 +1,110 @@
+import type { IMsgParams } from '../types.js'
+import { sendChunk } from '../transport.js'
+import { takeStreamChunkIdxAndAdvance } from './inboundTurnState.js'
+
+type OutboundTextState = {
+  inboundGen: number
+  lastStreamSnapshot: string
+  /** 仅 onPartialReply 成功下发过正文时为 true，用于 deliver 兜底判断 */
+  hasStreamedAssistantText: boolean
+  hasEmittedAssistantText: boolean
+}
+
+const stateBySessionKey = new Map<string, OutboundTextState>()
+
+/** 每轮入站 dispatch 开始前初始化，与 inboundGen 绑定供调试对齐 */
+export function resetOutboundTextState(sessionKey: string, inboundGen: number): void {
+  const k = sessionKey.trim()
+  if (!k) return
+  stateBySessionKey.set(k, {
+    inboundGen,
+    lastStreamSnapshot: '',
+    hasStreamedAssistantText: false,
+    hasEmittedAssistantText: false
+  })
+}
+
+export function clearOutboundTextState(sessionKey: string): void {
+  const k = sessionKey.trim()
+  if (!k) return
+  stateBySessionKey.delete(k)
+}
+
+function getState(sessionKey: string): OutboundTextState | undefined {
+  const k = sessionKey.trim()
+  if (!k) return undefined
+  return stateBySessionKey.get(k)
+}
+
+/** 子 agent 等路径可能未走 bot reset；懒初始化保证 dcgchat_message 仍可出站且参与快照去重 */
+function ensureState(sessionKey: string): OutboundTextState | undefined {
+  const k = sessionKey.trim()
+  if (!k) return undefined
+  let state = stateBySessionKey.get(k)
+  if (!state) {
+    state = {
+      inboundGen: 0,
+      lastStreamSnapshot: '',
+      hasStreamedAssistantText: false,
+      hasEmittedAssistantText: false
+    }
+    stateBySessionKey.set(k, state)
+  }
+  return state
+}
+
+export function outboundHasStreamedAssistantText(sessionKey: string): boolean {
+  return getState(sessionKey)?.hasStreamedAssistantText ?? false
+}
+
+export function outboundHasEmittedAssistantText(sessionKey: string): boolean {
+  return getState(sessionKey)?.hasEmittedAssistantText ?? false
+}
+
+/** 仅重置快照（用于 `replace` 流式片段），保留 generation 与已下发标记 */
+export function resetOutboundTextSnapshot(sessionKey: string): void {
+  const k = sessionKey.trim()
+  if (!k) return
+  const state = ensureState(k)
+  if (state) {
+    state.lastStreamSnapshot = ''
+  }
+}
+
+/**
+ * 统一助手正文出站：bot 流式/deliver 与 dcgchat_message 共用快照增量，避免双发或漏发。
+ * @param markStreamed 为 true 时表示来自 onPartialReply，会置 hasStreamedAssistantText
+ */
+export function emitOutboundAssistantText(
+  sessionKey: string,
+  raw: string | undefined,
+  outboundCtx: IMsgParams,
+  options?: { markStreamed?: boolean; emitDelta?: (delta: string) => boolean | void }
+): boolean {
+  if (!raw) return false
+  const state = ensureState(sessionKey)
+  if (!state) return false
+
+  const t = raw
+  let delta = ''
+  if (t.startsWith(state.lastStreamSnapshot)) {
+    delta = t.slice(state.lastStreamSnapshot.length)
+    state.lastStreamSnapshot = t
+  } else if (state.lastStreamSnapshot.startsWith(t)) {
+    // 快照缩短（模型修订等）：不重复下发
+  } else {
+    delta = t
+    state.lastStreamSnapshot = t
+  }
+
+  if (!delta.trim()) return false
+
+  const emitted =
+    options?.emitDelta != null ? options.emitDelta(delta) !== false : sendChunk(delta, outboundCtx, takeStreamChunkIdxAndAdvance(sessionKey))
+  if (!emitted) return false
+  state.hasEmittedAssistantText = true
+  if (options?.markStreamed) {
+    state.hasStreamedAssistantText = true
+  }
+  return true
+}

package/src/utils/params.ts

@@ -0,0 +1,104 @@
+import { CHANNEL_ID } from './constant.js'
+import { getOpenClawConfig } from './global.js'
+import type { DcgchatConfig, IMsgParams } from '../types.js'
+
+/**
+ * map key 是 session_key，value 为该会话下已 merge 后的消息参数。
+ */
+const paramsMessageMap = new Map<string, IMsgParams>()
+
+/** 从 OpenClaw 配置读取当前 channel 的基础参数（唯一来源，供 transport / resolve 等复用） */
+export function getParamsDefaults(): IMsgParams {
+  const ch = (getOpenClawConfig()?.channels?.[CHANNEL_ID] as DcgchatConfig | undefined) ?? {}
+  return {
+    userId: Number(ch.userId ?? 0),
+    botToken: ch.botToken ?? '',
+    sessionId: '',
+    messageId: '',
+    domainId: String(ch.domainId ?? '1000'),
+    appId: String(ch.appId ?? '100'),
+    botId: '',
+    agentId: '',
+    sessionKey: ''
+  }
+}
+
+export function resolveParamsMessage(params: Partial<IMsgParams>): IMsgParams {
+  const defaults = getParamsDefaults()
+  return {
+    userId: Number(params.userId ?? defaults.userId),
+    botToken: params.botToken ?? defaults.botToken,
+    sessionId: params.sessionId ?? defaults.sessionId,
+    messageId: params.messageId ?? defaults.messageId,
+    domainId: String(params.domainId ?? defaults.domainId),
+    appId: String(params.appId ?? defaults.appId),
+    botId: params.botId ?? defaults.botId,
+    agentId: params.agentId ?? defaults.agentId,
+    sessionKey: params.sessionKey ?? defaults.sessionKey
+  }
+}
+
+/**
+ * 统一取值入口：显式 sessionKey，或回落到当前会话；再与配置缺省 merge，保证字段完整。
+ */
+export function getEffectiveMsgParams(sessionKey?: string): IMsgParams {
+  const stored = sessionKey ? paramsMessageMap.get(sessionKey) : undefined
+  return stored ? resolveParamsMessage(stored) : getParamsDefaults()
+}
+
+/**
+ * Agent `dcgchat_message` / 出站 `target` 应为 `dcgSessionKey`（如 `agent:main:mobook:direct:...`）。
+ * `setParamsMessage` 的 key 与此一致；查不到 map 时回落到配置缺省（无会话级 messageId/sessionId）。
+ */
+export function getOutboundMsgParams(preferredKey: string): IMsgParams {
+  const k = preferredKey?.trim()
+  if (k && paramsMessageMap.has(k)) {
+    return getEffectiveMsgParams(k)
+  }
+  return getEffectiveMsgParams()
+}
+
+export function setParamsMessage(sessionKey: string, params: Partial<IMsgParams>) {
+  if (!sessionKey) return
+  const previous = paramsMessageMap.get(sessionKey)
+  const base = previous ? resolveParamsMessage(previous) : getParamsDefaults()
+  paramsMessageMap.set(sessionKey, resolveParamsMessage({ ...base, ...params, sessionKey }))
+}
+
+export function getParamsMessage(sessionKey: string): IMsgParams | undefined {
+  return paramsMessageMap.get(sessionKey)
+}
+
+export function clearParamsMessage(sessionKey: string): void {
+  const k = sessionKey?.trim()
+  if (!k) return
+  paramsMessageMap.delete(k)
+}
+
+/** 用于网关重启时持久化/恢复的参数模块状态快照 */
+export type ParamsStateSnapshot = {
+  paramsMessageMap: Array<[string, Partial<IMsgParams>]>
+}
+
+function snapshotMsgParams(params: IMsgParams): Partial<IMsgParams> {
+  const { botToken: _botToken, ...rest } = params
+  return rest
+}
+
+export function snapshotParamsState(sessionKeys?: ReadonlySet<string>): ParamsStateSnapshot {
+  return {
+    paramsMessageMap: [...paramsMessageMap.entries()]
+      .filter(([k]) => !sessionKeys || sessionKeys.has(k))
+      .map(([k, v]) => [k, snapshotMsgParams(v)])
+  }
+}
+
+export function restoreParamsState(snap: ParamsStateSnapshot | null | undefined): void {
+  if (!snap) return
+  paramsMessageMap.clear()
+  for (const [k, v] of snap.paramsMessageMap ?? []) {
+    if (typeof k === 'string' && k && v && typeof v === 'object') {
+      paramsMessageMap.set(k, resolveParamsMessage(v))
+    }
+  }
+}

package/src/utils/passTxt.ts

@@ -0,0 +1,4 @@
+export function isInsufficientBalanceAssistantText(text: string | undefined): boolean {
+  const t = text?.trim() ?? ''
+  return t === '1003-额度不足请充值' || /1003[-–]?额度不足请充值/.test(t)
+}

package/src/utils/resolveRegisterConfig.ts

@@ -0,0 +1,33 @@
+import type { OpenClawConfig } from 'openclaw/plugin-sdk'
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk'
+import { CHANNEL_ID } from './constant.js'
+
+function isEmptyObject(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && Object.keys(value as object).length === 0
+}
+
+export function openclawConfigLooksUsable(cfg: OpenClawConfig | undefined | null): cfg is OpenClawConfig {
+  if (!cfg || typeof cfg !== 'object' || isEmptyObject(cfg)) return false
+  const ch = cfg.channels
+  if (!ch || typeof ch !== 'object' || Object.keys(ch).length === 0) return false
+  return ch[CHANNEL_ID as keyof typeof ch] != null
+}
+
+/**
+ * `registerFull` 里 OpenClaw 传入的 `api.config` 在部分加载路径下会是 `{}` 或缺本通道段落，
+ * 应改用 `api.runtime.config.loadConfig()` 读盘上完整配置，避免 `getOpenClawConfig()` 不可靠。
+ *
+ * （`setRuntime` 在 `registerFull` 之前已执行，故此处可安全使用 `api.runtime`。）
+ */
+export function resolveOpenClawConfigAtRegister(api: OpenClawPluginApi): OpenClawConfig {
+  const snap = api.config as OpenClawConfig | undefined
+  if (openclawConfigLooksUsable(snap)) {
+    return snap
+  }
+  try {
+    const full = api.runtime.config.loadConfig() as OpenClawConfig
+    return structuredClone(full)
+  } catch {
+    return (snap ?? {}) as OpenClawConfig
+  }
+}

package/src/utils/searchFile.ts

@@ -0,0 +1,228 @@
+import { dcgLogger } from './log.js'
+
+/**
+ * 从文本中提取 /mobook 目录下的文件
+ * @param {string} text
+ * @returns {string[]}
+ */
+const EXT_LIST = [
+  // 文档类
+  'doc',
+  'docx',
+  'xls',
+  'xlsx',
+  'ppt',
+  'pptx',
+  'pdf',
+  'txt',
+  'rtf',
+  'odt',
+
+  // 数据/开发
+  'json',
+  'xml',
+  'csv',
+  'yaml',
+  'yml',
+
+  // 前端/文本
+  'html',
+  'htm',
+  'md',
+  'markdown',
+  'css',
+  'js',
+  'ts',
+
+  // 图片
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'bmp',
+  'webp',
+  'svg',
+  'ico',
+  'tiff',
+
+  // 音频
+  'mp3',
+  'wav',
+  'ogg',
+  'aac',
+  'flac',
+  'm4a',
+
+  // 视频
+  'mp4',
+  'avi',
+  'mov',
+  'wmv',
+  'flv',
+  'mkv',
+  'webm',
+
+  // 压缩包
+  'zip',
+  'rar',
+  '7z',
+  'tar',
+  'gz',
+  'bz2',
+  'xz',
+
+  // 可执行/程序
+  'exe',
+  'dmg',
+  'pkg',
+  'apk',
+  'ipa',
+
+  // 其他常见
+  'log',
+  'dat',
+  'bin'
+]
+/**
+ * 扩展名按长度降序，用于正则交替，避免 xls 抢先匹配 xlsx、htm 抢先匹配 html 等
+ */
+const EXT_SORTED_FOR_REGEX = [...EXT_LIST].sort((a, b) => b.length - a.length)
+
+/** 去除控制符、零宽字符等常见脏值 */
+function stripMobookNoise(s: string) {
+  return s.replace(/[\u0000-\u001F\u007F\u200B-\u200D\u200E\u200F\uFEFF]/g, '')
+}
+
+/**
+ * 从文本中扫描 `.../mobook/...` 或 `...\mobook\...` 片段，按最长后缀匹配合法扩展名（兜底）
+ */
+function collectMobookPathsAfterNeedle(text: string, lower: string, needle: string, result: Set<string>): void {
+  let from = 0
+  while (from < text.length) {
+    const i = lower.indexOf(needle, from)
+    if (i < 0) break
+    const start = i + needle.length
+    const tail = text.slice(start)
+    const seg = tail.match(/^([^\s\]\)'"}\u3002，,]+)/)
+    if (!seg) {
+      from = start + 1
+      continue
+    }
+    let raw = stripMobookNoise(seg[1]).trim()
+    if (!raw || raw.includes('\uFFFD')) {
+      from = start + 1
+      continue
+    }
+    const low = raw.toLowerCase()
+    let matchedExt: string | undefined
+    for (const ext of EXT_SORTED_FOR_REGEX) {
+      if (low.endsWith(`.${ext}`)) {
+        matchedExt = ext
+        break
+      }
+    }
+    if (!matchedExt) {
+      from = start + 1
+      continue
+    }
+    const base = raw.slice(0, -(matchedExt.length + 1))
+    const fileName = `${base}.${matchedExt}`
+    if (isValidFileName(fileName)) {
+      result.add(normalizePath(`/mobook/${fileName}`))
+    }
+    from = start + 1
+  }
+}
+
+function collectMobookPathsByScan(text: string, result: Set<string>): void {
+  const lower = text.toLowerCase()
+  collectMobookPathsAfterNeedle(text, lower, '/mobook/', result)
+  collectMobookPathsAfterNeedle(text, lower, '\\mobook\\', result)
+}
+
+export function extractMobookFiles(text = '') {
+  if (typeof text !== 'string' || !text.trim()) return []
+  // 全角冒号（中文输入常见）→ 半角，便于匹配 c：\mobook\
+  text = text.replace(/\uFF1A/g, ':')
+  const result = new Set<string>()
+  // ✅ 扩展名（必须长扩展名优先，见 EXT_SORTED_FOR_REGEX）
+  const EXT = `(${EXT_SORTED_FOR_REGEX.join('|')})`
+  // ✅ 文件名字符（增强：支持中文、符号）
+  const FILE_NAME = `[\\w\\u4e00-\\u9fa5：:《》()（）\\-\\s]+?`
+  try {
+    // 1️⃣ `xxx.xxx`
+    const backtickReg = new RegExp(`\`([^\\\`]+?\\.${EXT})\``, 'gi')
+    ;(text.match(backtickReg) || []).forEach((item) => {
+      const name = item.replace(/`/g, '').trim()
+      if (isValidFileName(name)) {
+        result.add(`/mobook/${name}`)
+      }
+    })
+    // 2️⃣ /mobook/xxx.xxx
+    const fullPathReg = new RegExp(`/mobook/${FILE_NAME}\\.${EXT}`, 'gi')
+    ;(text.match(fullPathReg) || []).forEach((p) => {
+      result.add(normalizePath(p))
+    })
+    // 2️⃣b Windows 实际保存路径：C:\mobook\xxx、c:/mobook/xxx、\mobook\xxx（模型常写反斜杠，原先无法识别）
+    const winMobookReg = new RegExp(`(?:[a-zA-Z]:)?[/\\\\]mobook[/\\\\]${FILE_NAME}\\.${EXT}`, 'gi')
+    ;(text.match(winMobookReg) || []).forEach((full) => {
+      const name = full.replace(/^(?:[a-zA-Z]:)?[/\\\\]mobook[/\\\\]/i, '').trim()
+      if (isValidFileName(name)) {
+        result.add(normalizePath(`/mobook/${name}`))
+      }
+    })
+    // 3️⃣ mobook下的 xxx.xxx
+    const inlineReg = new RegExp(`mobook下的\\s*(${FILE_NAME}\\.${EXT})`, 'gi')
+    ;(text.match(inlineReg) || []).forEach((item) => {
+      const match = item.match(new RegExp(`${FILE_NAME}\\.${EXT}`, 'i'))
+      if (match && isValidFileName(match[0])) {
+        result.add(`/mobook/${match[0].trim()}`)
+      }
+    })
+    // 🆕 4️⃣ **xxx.xxx**
+    const boldReg = new RegExp(`\\*\\*(${FILE_NAME}\\.${EXT})\\*\\*`, 'gi')
+    ;(text.match(boldReg) || []).forEach((item) => {
+      const name = item.replace(/\*\*/g, '').trim()
+      if (isValidFileName(name)) {
+        result.add(`/mobook/${name}`)
+      }
+    })
+    // 🆕 5️⃣ xxx.xxx (123字节)
+    const looseReg = new RegExp(`(${FILE_NAME}\\.${EXT})\\s*\\(`, 'gi')
+    ;(text.match(looseReg) || []).forEach((item) => {
+      const name = item.replace(/\s*\(.+$/, '').trim()
+      if (isValidFileName(name)) {
+        result.add(`/mobook/${name}`)
+      }
+    })
+    // 6️⃣ 兜底：绝对路径等 `.../mobook/<文件名>.<扩展名>` + 最长后缀匹配 + 去脏字符
+    collectMobookPathsByScan(text, result)
+  } catch (e) {
+    dcgLogger(`extractMobookFiles error:${e}`, 'error')
+  }
+  return [...result]
+}
+
+/**
+ * 校验文件名是否合法（避免脏数据）
+ */
+function isValidFileName(name: string) {
+  if (!name) return false
+  const cleaned = stripMobookNoise(name).trim()
+  if (!cleaned) return false
+  if (cleaned.includes('\uFFFD')) return false
+  // 过滤异常字符
+  if (/[\/\\<>:"|?*]/.test(cleaned)) return false
+  // 长度限制（防止异常长字符串）
+  if (cleaned.length > 200) return false
+  return true
+}
+
+/**
+ * 规范路径（去重用）
+ */
+function normalizePath(path: string) {
+  return path
+    .replace(/\/+/g, '/') // 多斜杠 → 单斜杠
+    .replace(/\/$/, '') // 去掉结尾 /
+}

package/src/utils/sessionState.ts

@@ -0,0 +1,137 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { getWorkspaceDir, snapshotGlobalSessionState, restoreGlobalSessionState, type GlobalSessionStateSnapshot } from './global.js'
+import { snapshotParamsState, restoreParamsState, type ParamsStateSnapshot } from './params.js'
+import { dcgLogger } from './log.js'
+
+/** 子 agent 跟踪状态（由 tool.ts 侧维护）的可序列化快照 */
+export type SubagentTrackingSnapshot = {
+  activeSubagentRunIdsByRequester: Array<[string, string[]]>
+  requesterByChildSessionKey: Array<[string, string]>
+  runIdByChildSessionKey: Array<[string, string]>
+  requesterSessionKeyByRunId?: Array<[string, string]>
+  childSessionKeyByRunId?: Array<[string, string]>
+}
+
+/** 完整的会话相关内存状态快照 */
+export type SessionStateFile = {
+  version: number
+  savedAt: number
+  params: ParamsStateSnapshot
+  global: GlobalSessionStateSnapshot
+  subagent: SubagentTrackingSnapshot
+}
+
+const SESSION_STATE_FILE_VERSION = 1
+const SESSION_STATE_FILE_NAME = 'session-state.json'
+
+/**
+ * 将快照落地到 `${workspace}/../session-state.json`，与 cron 走同级约定，
+ * 避免运行时污染 workspace 文件树。workspace 未初始化时直接跳过。
+ */
+function getSessionStateFilePath(): string | null {
+  const ws = getWorkspaceDir()
+  if (!ws) return null
+  return path.join(path.dirname(ws), SESSION_STATE_FILE_NAME)
+}
+
+export function writeSessionStateFile(subagent: SubagentTrackingSnapshot): void {
+  const filePath = getSessionStateFilePath()
+  if (!filePath) {
+    dcgLogger('writeSessionStateFile: workspace dir not initialized, skip', 'error')
+    return
+  }
+  const global = snapshotGlobalSessionState()
+  const runningSessionKeys = new Set(global.msgStatusBySessionKey.map(([k]) => k))
+  if (runningSessionKeys.size === 0) {
+    removeSessionStateFile()
+    dcgLogger('session state skipped: no running sessions')
+    return
+  }
+  const payload: SessionStateFile = {
+    version: SESSION_STATE_FILE_VERSION,
+    savedAt: Date.now(),
+    params: snapshotParamsState(runningSessionKeys),
+    global,
+    subagent
+  }
+  try {
+    const dir = path.dirname(filePath)
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+    const tmp = `${filePath}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8')
+    fs.renameSync(tmp, filePath)
+    dcgLogger(`session state persisted: ${filePath}`)
+  } catch (e) {
+    dcgLogger(`writeSessionStateFile failed: ${String(e)}`, 'error')
+  }
+}
+
+export function readSessionStateFile(): SessionStateFile | null {
+  const filePath = getSessionStateFilePath()
+  if (!filePath || !fs.existsSync(filePath)) return null
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const data = JSON.parse(raw) as SessionStateFile
+    if (!data || typeof data !== 'object') return null
+    if (data.version !== SESSION_STATE_FILE_VERSION) {
+      dcgLogger(`readSessionStateFile: version mismatch ${data.version} vs ${SESSION_STATE_FILE_VERSION}`, 'error')
+      return null
+    }
+    return data
+  } catch (e) {
+    dcgLogger(`readSessionStateFile failed: ${String(e)}`, 'error')
+    return null
+  }
+}
+
+/**
+ * 恢复 params/global 两个模块的内存状态。subagent 跟踪由 tool.ts 侧自行 restore（避免循环依赖）。
+ */
+export function restoreParamsAndGlobal(snap: SessionStateFile | null): void {
+  if (!snap) return
+  restoreParamsState(snap.params)
+  restoreGlobalSessionState(snap.global)
+}
+
+export function removeSessionStateFile(): void {
+  const filePath = getSessionStateFilePath()
+  if (!filePath) return
+  try {
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath)
+  } catch (e) {
+    dcgLogger(`removeSessionStateFile failed: ${String(e)}`, 'error')
+  }
+}
+
+function addSessionKeyToSet(out: Set<string>, k: string | undefined) {
+  const t = k?.trim()
+  if (t) out.add(t)
+}
+
+/**
+ * 从持久化快照中收集所有与「会话」相关的 dcg sessionKey，供网关恢复后 `chat.send` 等用。
+ * （不含 `sentMediaKeys` 外层 key：那是 messageId，不是 sessionKey。）
+ */
+export function collectSessionKeysFromSnapshot(snap: SessionStateFile | null | undefined): string[] {
+  if (!snap) return []
+  const set = new Set<string>()
+  for (const [k, status] of snap.global?.msgStatusBySessionKey ?? []) {
+    if (status === 'running') addSessionKeyToSet(set, k)
+  }
+  return [...set]
+}
+
+/**
+ * 网关恢复时只恢复顶层会话，避免对旧子会话发送「继续执行」但本地不恢复 runId 映射，
+ * 导致后续子 agent 流式输出无法回到主消息。
+ */
+export function collectRootSessionKeysFromSnapshot(snap: SessionStateFile | null | undefined): string[] {
+  if (!snap) return []
+  const childKeys = new Set<string>()
+  for (const [child] of snap.subagent?.requesterByChildSessionKey ?? []) {
+    const k = child?.trim()
+    if (k) childKeys.add(k)
+  }
+  return collectSessionKeysFromSnapshot(snap).filter((k) => !childKeys.has(k))
+}