@dcrays/dcgchat-test 0.6.1 → 0.6.2

package/src/utils/global.ts

@@ -0,0 +1,306 @@
+import type WebSocket from 'ws'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { OpenClawConfig, PluginRuntime } from 'openclaw/plugin-sdk'
+import { createPluginRuntimeStore } from 'openclaw/plugin-sdk/runtime-store'
+import { CHANNEL_ID } from './constant.js'
+import { dcgLogger } from './log.js'
+
+/** 配置中 `channels.*.appId` 为该值时，默认工作区落在 `~/.mobook/workspace`（否则 `~/.openclaw/workspace`）。 */
+export const MOBOOK_WORKSPACE_APP_ID = 110
+
+/** socket connection */
+let ws: WebSocket | null = null
+
+export function setWsConnection(next: WebSocket | null) {
+  ws = next
+}
+
+export function getWsConnection(): WebSocket | null {
+  return ws
+}
+
+let config: OpenClawConfig | null = null
+
+export function setOpenClawConfig(next: OpenClawConfig | null) {
+  config = next
+}
+
+export function getOpenClawConfig(): OpenClawConfig | null {
+  return config
+}
+
+function getWorkspacePath(): string | null {
+  const chAppId = config?.channels?.[CHANNEL_ID]?.appId
+  const workspacePath = path.join(os.homedir(), Number(chAppId) === MOBOOK_WORKSPACE_APP_ID ? '.mobook' : '.openclaw', 'workspace')
+  if (fs.existsSync(workspacePath)) {
+    return workspacePath
+  }
+  return null
+}
+
+let workspaceDir: string = getWorkspacePath() ?? ''
+
+export function setWorkspaceDir(dir?: string) {
+  if (dir && dir !== workspaceDir) {
+    workspaceDir = dir
+    dcgLogger(`setWorkspaceDir ==> ${dir}`)
+  }
+}
+
+export function getWorkspaceDir(): string {
+  if (!workspaceDir) {
+    dcgLogger?.('Workspace directory not initialized', 'error')
+  }
+  return workspaceDir
+}
+
+const { setRuntime: setDcgchatRuntime, getRuntime: getDcgchatRuntime } = createPluginRuntimeStore<PluginRuntime>(
+  `${CHANNEL_ID} runtime not initialized`
+)
+export { setDcgchatRuntime, getDcgchatRuntime }
+
+export type MsgSessionStatus = 'running' | 'finished' | ''
+
+const msgStatusBySessionKey = new Map<string, MsgSessionStatus>()
+
+export function setMsgStatus(sessionKey: string, status: MsgSessionStatus) {
+  if (!sessionKey?.trim()) return
+  if (status === '') {
+    msgStatusBySessionKey.delete(sessionKey)
+  } else {
+    msgStatusBySessionKey.set(sessionKey, status)
+  }
+}
+
+export function getMsgStatus(sessionKey: string): MsgSessionStatus {
+  if (!sessionKey?.trim()) return ''
+  return msgStatusBySessionKey.get(sessionKey) ?? ''
+}
+
+/**
+ * 出站媒体去重 bucket：优先本轮用户 `messageId`（与 bot / sendFinal 清理一致），否则书灵 `sessionId`，最后可回落 `sessionKey`。
+ */
+export function resolveOutboundMediaDedupeKey(messageId?: string, sessionId?: string, sessionKeyFallback?: string): string {
+  const mid = messageId?.trim()
+  if (mid) return mid
+  const sid = sessionId?.trim()
+  if (sid) return sid
+  return sessionKeyFallback?.trim() ?? ''
+}
+
+/**
+ * 本地路径用 `path.resolve`、http(s) 用「origin+pathname」并去掉 query，避免仅用 basename 导致跨目录误去重。
+ */
+export function mediaPathDedupeKey(mediaUrl: string): string {
+  const t = mediaUrl.trim()
+  if (!t) return ''
+  if (/^https?:\/\//i.test(t)) {
+    try {
+      const u = new URL(t)
+      return `${u.origin}${u.pathname}`
+    } catch {
+      return t.split('?')[0] ?? t
+    }
+  }
+  try {
+    const r = path.resolve(t)
+    return process.platform === 'win32' ? r.toLowerCase() : r
+  } catch {
+    const n = path.normalize(t)
+    return process.platform === 'win32' ? n.toLowerCase() : n
+  }
+}
+
+/** 已发送媒体去重：外层 dedupe bucket（见 resolveOutboundMediaDedupeKey）→ 内层规范化路径/url key */
+const sentMediaKeysBySession = new Map<string, Set<string>>()
+
+function getSessionMediaSet(dedupeBucketKey: string): Set<string> {
+  let set = sentMediaKeysBySession.get(dedupeBucketKey)
+  if (!set) {
+    set = new Set<string>()
+    sentMediaKeysBySession.set(dedupeBucketKey, set)
+  }
+  return set
+}
+
+export function addSentMediaKey(dedupeBucketKey: string, url: string) {
+  const k = dedupeBucketKey.trim()
+  if (!k) return
+  getSessionMediaSet(k).add(mediaPathDedupeKey(url))
+}
+
+export function hasSentMediaKey(dedupeBucketKey: string, url: string): boolean {
+  const k = dedupeBucketKey.trim()
+  if (!k) return false
+  return sentMediaKeysBySession.get(k)?.has(mediaPathDedupeKey(url)) ?? false
+}
+
+/** 仅删除指定 bucket；`dedupeBucketKey` 为空则 no-op（不做「清空全部」以免误伤）。 */
+export function clearSentMediaKeys(dedupeBucketKey?: string) {
+  const k = dedupeBucketKey?.trim()
+  if (!k) return
+  sentMediaKeysBySession.delete(k)
+}
+
+/** 每个 sessionKey 下多个定时任务 messageId，入队在尾、出队在头（FIFO） */
+const cronMessageIdMap = new Map<string, string[]>()
+
+export function setCronMessageId(sk: string, messageId: string | number | null | undefined) {
+  const mid = messageId != null && messageId !== '' ? String(messageId).trim() : ''
+  if (!sk?.trim() || !mid) return
+  let q = cronMessageIdMap.get(sk)
+  if (!q) {
+    q = []
+    cronMessageIdMap.set(sk, q)
+  }
+  q.push(mid)
+}
+
+/** 窥视队首 messageId（不移除），供发送中与 finished 配对使用 */
+export function getCronMessageId(sk: string): string {
+  if (!sk?.trim()) return ''
+  return cronMessageIdMap.get(sk)?.[0] ?? ''
+}
+
+/** 弹出队首一条，与一次 finished 对应；队列为空时移除 key */
+export function removeCronMessageId(sk: string) {
+  if (!sk?.trim()) return
+  const q = cronMessageIdMap.get(sk)
+  if (!q?.length) return
+  q.shift()
+  if (q.length === 0) {
+    cronMessageIdMap.delete(sk)
+  }
+}
+
+/**
+ * turn 已正常收尾时清空该 sessionKey 的整条 cron 队列。
+ *
+ * 背景：
+ * - `setCronMessageId` 同时服务于两类调用方：
+ *   1. `cron/message.ts onRunCronJob`：每条 cron.run 写入队首，与 `finishedDcgchatCron` 1.2s 后 `removeCronMessageId` 配对消费（队首一条）。
+ *   2. `outboundMedia.ts sendDcgchatMedia` 兜底：未传 `opts.messageId` 且队列为空时写入 `${Date.now()}`，本意是给后续 cron 气泡配 messageId。
+ *      这条 entry 永远不会被 `finishedDcgchatCron` 消费（其队首始终是 onRunCronJob 写入的），且每次 `deliver` 回调都会触发一条 → 队列无限增长。
+ * - turn 收尾时该 sessionKey 下不会再有 in-flight finished 配对，可安全清空。
+ * - 若 1.2s 内 `finishedDcgchatCron` 才被调用，`q.shift()` 在空队列上为 no-op（`removeCronMessageId` 已判空），不报错。
+ */
+export function removeAllCronMessageIdsForSession(sk: string): void {
+  if (!sk?.trim()) return
+  cronMessageIdMap.delete(sk)
+}
+
+/** 用于网关重启时持久化/恢复的全局会话状态快照 */
+export type GlobalSessionStateSnapshot = {
+  msgStatusBySessionKey: Array<[string, MsgSessionStatus]>
+  /** 媒体已发送去重：bucket 为 `resolveOutboundMediaDedupeKey`（优先 messageId） */
+  sentMediaKeysBySession: Array<[string, string[]]>
+  cronMessageIdMap: Array<[string, string[]]>
+}
+
+export function snapshotGlobalSessionState(): GlobalSessionStateSnapshot {
+  const runningEntries = [...msgStatusBySessionKey.entries()].filter(([, status]) => status === 'running')
+  const runningSessionKeys = new Set(runningEntries.map(([k]) => k))
+  return {
+    msgStatusBySessionKey: runningEntries,
+    sentMediaKeysBySession: [],
+    cronMessageIdMap: [...cronMessageIdMap.entries()]
+      .filter(([k]) => runningSessionKeys.has(k))
+      .map(([k, q]) => [k, [...q]])
+  }
+}
+
+export function restoreGlobalSessionState(snap: GlobalSessionStateSnapshot | null | undefined): void {
+  if (!snap) return
+  msgStatusBySessionKey.clear()
+  sentMediaKeysBySession.clear()
+  cronMessageIdMap.clear()
+  for (const [k, v] of snap.msgStatusBySessionKey ?? []) {
+    if (typeof k === 'string' && k && v === 'running') {
+      msgStatusBySessionKey.set(k, v)
+    }
+  }
+  for (const [k, arr] of snap.cronMessageIdMap ?? []) {
+    if (typeof k !== 'string' || !k || !Array.isArray(arr)) continue
+    const q = arr.filter((x): x is string => typeof x === 'string' && !!x)
+    if (q.length > 0) cronMessageIdMap.set(k, q)
+  }
+}
+
+/** 与 bot 侧一致：session_id 为 `agentId::对话标识` 时提取 agentId（专家会话可仅依赖此前缀）。 */
+export function extractAgentIdFromConversationId(conversationId: string): string | null {
+  const idx = conversationId.indexOf('::')
+  if (idx <= 0) return null
+  return conversationId.slice(0, idx)
+}
+
+export const getSessionKey = (content: any, accountId: string) => {
+  const { real_mobook, agent_id, agent_clone_code, session_id } = content
+  const core = getDcgchatRuntime()
+
+  const sid = typeof session_id === 'string' ? session_id.trim() : ''
+  const embeddedAgent = sid ? extractAgentIdFromConversationId(sid) : null
+  const agentCode = (typeof agent_clone_code === 'string' && agent_clone_code.trim()) || embeddedAgent || 'main'
+
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: getOpenClawConfig() as OpenClawConfig,
+    channel: CHANNEL_ID,
+    accountId: accountId || 'default',
+    peer: { kind: 'direct', id: session_id }
+  })
+  return real_mobook == '1' ? route.sessionKey : `agent:${agentCode}:mobook:direct:${agent_id}:${session_id}`.toLowerCase()
+}
+
+interface TakeApartSessionKeyResult {
+  sessionId: string
+  agentId: string
+}
+export function takeApartSessionKey(sk: string): TakeApartSessionKeyResult {
+  const sessionInfo = sk.split(':')
+  const sessionId = sessionInfo.at(-1) ?? ''
+  const agentId = sessionInfo.at(-2) ?? ''
+  return { sessionId, agentId }
+}
+
+export function compressFields(obj: Record<string, unknown>, fields: string[] = []) {
+  const start = 8
+  const end = 8
+  const newObj = { ...obj }
+
+  const compressText = (str: unknown) => {
+    if (typeof str !== 'string') return str
+
+    if (str.length <= start + end) {
+      return str
+    }
+
+    const omittedCount = str.length - start - end
+
+    return str.slice(0, start) + `...省略${omittedCount}个字...` + str.slice(-end)
+  }
+
+  fields.forEach((field) => {
+    if (field in newObj) {
+      newObj[field] = compressText(newObj[field])
+    }
+  })
+
+  return newObj
+}
+
+export function formatText(text: string): string {
+  if (!text) return ''
+  const str = String(text).replace(/\s/g, '')
+  if (!str) return ''
+  if (str.length <= 50) {
+    return str
+  }
+  return str.slice(0, 25) + `...[此处省略${str.length - 50}字]....` + str.slice(-25)
+}
+
+export function isReviserExpert(sessionKey?: string): boolean {
+  if (!sessionKey) return false
+  const segment = sessionKey.split(':')[1]
+  return segment != null && segment.includes('reviser-expert')
+}

package/src/utils/inboundTurnState.ts

@@ -0,0 +1,66 @@
+/**
+ * 入站 generation 与流式分片序号（bot 与会话清理共用）。
+ * 独立模块以避免 bot 与 sessionTermination 之间的循环依赖。
+ */
+
+const inboundGenerationBySessionKey = new Map<string, number>()
+const streamChunkIdxBySessionKey = new Map<string, number>()
+
+/**
+ * stop 序列号：每条 /stop 在 turn 开始时递增，用于 stale handler 判定。
+ * 与 generation 独立：generation 区分不同用户消息，stopSeq 区分 /stop 与普通消息。
+ */
+const stopSeqBySessionKey = new Map<string, number>()
+
+/** 每条入站消息在 turn 开始时单调递增；用于 stale handler 判定 */
+export function bumpInboundGeneration(sessionKey: string): number {
+  const n = (inboundGenerationBySessionKey.get(sessionKey) ?? 0) + 1
+  inboundGenerationBySessionKey.set(sessionKey, n)
+  return n
+}
+
+export function getInboundGeneration(sessionKey: string): number {
+  return inboundGenerationBySessionKey.get(sessionKey) ?? 0
+}
+
+/**
+ * 每条 /stop 在 turn 开始时单调递增；用于 stale handler 判定（与 generation 独立检查）。
+ * 普通消息 bumpGeneration 时不 bump stopSeq，只有 /stop 才 bump。
+ */
+export function bumpStopSeq(sessionKey: string): number {
+  const n = (stopSeqBySessionKey.get(sessionKey) ?? 0) + 1
+  stopSeqBySessionKey.set(sessionKey, n)
+  return n
+}
+
+export function getStopSeq(sessionKey: string): number {
+  return stopSeqBySessionKey.get(sessionKey) ?? 0
+}
+
+/** 第一条 /stop 后的新用户消息已接管会话时，消费 stop 标记，避免后续消息一直被当作 after-stop。 */
+export function clearStopSeqForSession(sessionKey: string): void {
+  stopSeqBySessionKey.delete(sessionKey)
+}
+
+/** 会话完全终止时清理 generation 与 streamChunkIdx，防止 Map 泄漏 */
+export function clearInboundGenerationForSession(sessionKey: string): void {
+  inboundGenerationBySessionKey.delete(sessionKey)
+  streamChunkIdxBySessionKey.delete(sessionKey)
+  stopSeqBySessionKey.delete(sessionKey)
+}
+
+/** 本轮正常收尾时仅删除分片序号（generation 保留） */
+export function deleteStreamChunkIdxForSession(sessionKey: string): void {
+  streamChunkIdxBySessionKey.delete(sessionKey)
+}
+
+export function resetStreamChunkIdxForSession(sessionKey: string, value: number): void {
+  streamChunkIdxBySessionKey.set(sessionKey, value)
+}
+
+/** 返回当前序号并将计数 +1，供 sendChunk(..., prev) 使用 */
+export function takeStreamChunkIdxAndAdvance(sessionKey: string): number {
+  const prev = streamChunkIdxBySessionKey.get(sessionKey) ?? 0
+  streamChunkIdxBySessionKey.set(sessionKey, prev + 1)
+  return prev
+}

package/src/utils/log.ts

@@ -0,0 +1,77 @@
+import { RuntimeEnv } from 'openclaw/plugin-sdk'
+import { CHANNEL_ID } from './constant.js'
+
+let logger: RuntimeEnv | null = null
+const STACK_ROOT = 'openclaw-dcgchat'
+/** 发布包 scope，与 @dcrays/dcgchat-test 前段一致，用于匹配已安装到 node_modules 下的路径 */
+const SCOPE = '@dcrays/dcgchat'
+
+function isOurCodePath(line: string): boolean {
+  if (line.includes(STACK_ROOT)) return true
+  if (line.includes(SCOPE)) return true
+  // 无 node_modules 的本地单文件 /dist/index.js
+  if (line.replaceAll('\\', '/').includes('dist/index.js') && !line.includes('node_modules')) {
+    return true
+  }
+  return false
+}
+
+function isOtherNodeModuleLine(line: string): boolean {
+  if (!line.includes('node_modules/')) return false
+  // 本扩展装在 host 的 node_modules 下时，路径仍要保留
+  if (line.includes('node_modules/@dcrays/')) return false
+  if (line.includes(`node_modules/${STACK_ROOT}/`)) return false
+  return true
+}
+
+export function setLogger(next: RuntimeEnv | null) {
+  logger = next
+}
+
+function buildFilteredStack(): string {
+  const stack = new Error().stack
+  if (!stack) return ''
+  const frames = stack
+    .split('\n')
+    .slice(1)
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        isOurCodePath(line) &&
+        !isOtherNodeModuleLine(line) &&
+        !line.includes('dcgLogger') &&
+        !line.includes('buildFilteredStack')
+    )
+    .map((line) => {
+      const normalized = line.replaceAll('\\', '/')
+      const fromRoot = normalized.indexOf(`${STACK_ROOT}/`)
+      if (fromRoot >= 0) {
+        const trimmed = normalized.slice(fromRoot + STACK_ROOT.length + 1)
+        return normalized.startsWith('at ') ? `at ${trimmed}` : trimmed
+      }
+      const scopeIdx = normalized.indexOf(`${SCOPE}`)
+      if (scopeIdx >= 0) {
+        const tail = normalized.slice(scopeIdx)
+        return normalized.startsWith('at ') ? `at ${tail}` : tail
+      }
+      return normalized.replace(/^at\s+/, '')
+    })
+
+  if (!frames.length) return ''
+  return `\nstack:\n${frames.join('\n')}`
+}
+
+export function dcgLogger(
+  message: string,
+  type: 'log' | 'error' = 'log',
+  options?: { includeStack?: boolean }
+): void {
+  const includeStack = options?.includeStack ?? false
+  const stack = includeStack ? buildFilteredStack() : ''
+  const fullMessage = `${message}${stack}`
+  if (logger) {
+    logger[type](`书灵墨宝🚀 ~ [${new Date().toISOString()}] ${fullMessage}`)
+  } else {
+    console[type](`书灵墨宝🚀 ~ ${new Date().toISOString()} [${CHANNEL_ID}]: ${fullMessage}`)
+  }
+}

package/src/utils/mediaAttached.ts

@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import path from 'node:path'
+import { buildAgentMediaPayload } from 'openclaw/plugin-sdk/agent-media-payload'
+import { getDcgchatRuntime } from './global.js'
+import { dcgLogger } from './log.js'
+import { generateSignUrl } from '../request/api.js'
+
+export type DcgchatInboundMediaInfo = {
+  path: string
+  fileName: string
+  contentType: string
+  placeholder: string
+}
+
+export type DcgchatInboundFileRef = { name: string; url: string }
+
+export const DCGCHAT_INBOUND_MEDIA_MAX_BYTES = 500 * 1024 * 1024
+
+const INBOUND_FILE_URL_KEYS = ['url', 'fileUrl', 'file_url', 'link', 'href', 'path', 'ossKey', 'oss_key', 'key'] as const
+const INBOUND_FILE_NAME_KEYS = ['name', 'fileName', 'file_name', 'title', 'originalName', 'original_filename'] as const
+const INBOUND_FILE_ARRAY_KEYS = [
+  'files',
+  'file_list',
+  'fileList',
+  'attachments',
+  'media_files',
+  'mediaFiles',
+  'resources',
+  'uploads'
+] as const
+
+function firstNonEmptyString(o: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const k of keys) {
+    const v = o[k]
+    if (typeof v === 'string' && v.trim()) return v.trim()
+  }
+  return undefined
+}
+
+function fallbackFileNameFromUrl(url: string): string {
+  try {
+    return path.basename(new URL(url).pathname) || 'file'
+  } catch {
+    const base = url.split(/[\\/]/).pop() ?? url
+    return path.basename(base.split('?')[0] || base) || 'file'
+  }
+}
+
+function coerceInboundFileItem(item: unknown): DcgchatInboundFileRef | null {
+  if (item == null) return null
+  if (typeof item === 'string') {
+    const t = item.trim()
+    if (!t) return null
+    return { url: t, name: fallbackFileNameFromUrl(t) }
+  }
+  if (typeof item !== 'object') return null
+  const o = item as Record<string, unknown>
+  const url = firstNonEmptyString(o, INBOUND_FILE_URL_KEYS)
+  if (!url) return null
+  const name = firstNonEmptyString(o, INBOUND_FILE_NAME_KEYS) ?? ''
+  return { url, name: name || fallbackFileNameFromUrl(url) }
+}
+
+function asInboundFileArray(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw
+  if (typeof raw === 'string') {
+    const t = raw.trim()
+    if (!t) return []
+    try {
+      const p = JSON.parse(t) as unknown
+      return Array.isArray(p) ? p : []
+    } catch {
+      return []
+    }
+  }
+  return []
+}
+
+/** 合并服务端可能使用的多种附件字段与对象形状，避免仅认 `files`+`url` 时视频未入队 */
+export function normalizeInboundFileList(content: Record<string, unknown>): DcgchatInboundFileRef[] {
+  const seen = new Set<string>()
+  const out: DcgchatInboundFileRef[] = []
+  for (const key of INBOUND_FILE_ARRAY_KEYS) {
+    for (const item of asInboundFileArray(content[key])) {
+      const f = coerceInboundFileItem(item)
+      if (f && !seen.has(f.url)) {
+        seen.add(f.url)
+        out.push(f)
+      }
+    }
+  }
+  for (const key of ['file', 'attachment', 'media'] as const) {
+    const f = coerceInboundFileItem(content[key])
+    if (f && !seen.has(f.url)) {
+      seen.add(f.url)
+      out.push(f)
+    }
+  }
+  return out
+}
+
+/** 供模型侧识别媒体槽位类型 */
+export function inferPlaceholderFromContentType(contentType: string): string {
+  const ct = (contentType || '').toLowerCase()
+  if (ct.startsWith('image/')) return '<media:image>'
+  if (ct.startsWith('video/')) return '<media:video>'
+  if (ct.startsWith('audio/')) return '<media:audio>'
+  if (
+    ct === 'application/pdf' ||
+    ct.includes('word') ||
+    ct.includes('document') ||
+    ct.includes('msword') ||
+    ct.includes('officedocument') ||
+    ct.includes('spreadsheet') ||
+    ct.includes('presentation')
+  ) {
+    return '<media:document>'
+  }
+  return '<media:document>'
+}
+
+/**
+ * 使用 SDK 与飞书通道一致的 Media* 布局，并保留 dcgchat 原有的文件名字段供工具/模板使用。
+ */
+export function buildDcgchatInboundMediaPayload(mediaList: DcgchatInboundMediaInfo[]): Record<string, unknown> {
+  if (mediaList.length === 0) return {}
+  const base = buildAgentMediaPayload(mediaList.map((m) => ({ path: m.path, contentType: m.contentType || null })))
+  const mediaFileNames = mediaList.map((m) => m.fileName).filter(Boolean)
+  if (mediaFileNames.length === 0) return { ...base }
+  return {
+    ...base,
+    MediaFileName: mediaFileNames[0],
+    MediaFileNames: mediaFileNames
+  }
+}
+
+/** BodyForAgent：含附件说明与槽位行；与 RawBody/CommandBody（纯用户侧文本）分离 */
+export function buildAgentInboundBodySuffix(userText: string, mediaList: DcgchatInboundMediaInfo[]): string {
+  if (mediaList.length === 0) return userText
+  const brief = mediaList.map((m, i) => `${i + 1}) ${m.fileName} [${m.contentType || 'unknown'}]`).join('; ')
+  const slots = mediaList.map((m) => m.placeholder).join('\n')
+  return `${userText}\n\n[系统: 用户已随本消息上传 ${mediaList.length} 个附件: ${brief}。请勿要求用户再次上传；下列槽位与 MediaPaths/MediaTypes 顺序一致。]\n${slots}`
+}
+
+const DEFAULT_INBOUND_FETCH_TIMEOUT_MS = 180_000
+const DEFAULT_INBOUND_DOWNLOAD_CONCURRENCY = 3
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(new Error(`fetch timeout ${timeoutMs}ms`)), timeoutMs)
+  try {
+    return await fetch(url, { signal: ctrl.signal })
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+function resolveFilepath(savedFilePath: string, filename: string) {
+  if (path.extname(savedFilePath)) return savedFilePath
+
+  const ext = path.extname(filename)
+  if (!ext) return savedFilePath
+
+  const newPath = `${savedFilePath}${ext}`
+  try {
+    fs.renameSync(savedFilePath, newPath);
+    return newPath
+  } catch (err) {
+    dcgLogger(`media: failed to append extension to ${savedFilePath}: ${String(err)}`, 'error')
+    return savedFilePath
+  }
+}
+
+async function resolveOneInboundFile(
+  file: DcgchatInboundFileRef,
+  botToken: string,
+  maxBytes: number,
+  fetchTimeoutMs: number
+): Promise<DcgchatInboundMediaInfo | null> {
+  const core = getDcgchatRuntime()
+  try {
+    let data = ''
+    if (/^https?:\/\//i.test(file.url)) {
+      data = file.url
+    } else {
+      data = await generateSignUrl(file.url, botToken)
+    }
+    const response = await fetchWithTimeout(data, fetchTimeoutMs)
+    if (!response.ok) {
+      dcgLogger?.(`media: ${file.url} fetch failed with HTTP ${response.status}`, 'error')
+      return null
+    }
+    const buffer = Buffer.from(await response.arrayBuffer())
+
+    let contentType = response.headers.get('content-type') || ''
+    if (!contentType) {
+      contentType = (await core.media.detectMime({ buffer })) || ''
+    }
+    const fileName = file.name || fallbackFileNameFromUrl(file.url)
+    const saved = await core.channel.media.saveMediaBuffer(buffer, contentType, 'inbound', maxBytes, fileName)
+    const effectiveType = saved.contentType || contentType
+
+    const finalPath = resolveFilepath(saved.path, fileName)
+
+    return {
+      path: finalPath,
+      fileName,
+      contentType: effectiveType,
+      placeholder: inferPlaceholderFromContentType(effectiveType)
+    }
+  } catch (err) {
+    dcgLogger(`media: ${file.url} FAILED to process: ${String(err)}`, 'error')
+    return null
+  }
+}
+
+export async function resolveMediaFromUrls(
+  files: DcgchatInboundFileRef[],
+  botToken: string,
+  opts?: { maxBytes?: number; fetchTimeoutMs?: number; concurrency?: number }
+): Promise<DcgchatInboundMediaInfo[]> {
+  const maxBytes = opts?.maxBytes ?? DCGCHAT_INBOUND_MEDIA_MAX_BYTES
+  const fetchTimeoutMs = opts?.fetchTimeoutMs ?? DEFAULT_INBOUND_FETCH_TIMEOUT_MS
+  const conc = Math.max(1, opts?.concurrency ?? DEFAULT_INBOUND_DOWNLOAD_CONCURRENCY)
+  const concurrency = files.length === 0 ? 1 : Math.min(conc, files.length)
+
+  dcgLogger(`media: inbound files count=${files.length}, concurrency=${concurrency}, fetchTimeoutMs=${fetchTimeoutMs}`)
+  const results: (DcgchatInboundMediaInfo | null)[] = new Array(files.length).fill(null)
+  let nextIndex = 0
+
+  async function worker() {
+    while (true) {
+      const i = nextIndex++
+      if (i >= files.length) break
+      results[i] = await resolveOneInboundFile(files[i], botToken, maxBytes, fetchTimeoutMs)
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => worker()))
+
+  const out = results.filter((x): x is DcgchatInboundMediaInfo => x != null)
+  dcgLogger(`media: resolve complete, ${out.length}/${files.length} file(s) succeeded`)
+  return out
+}