dsh-qqchat 0.2.0

package/src/gateway/normalize.ts

@@ -0,0 +1,236 @@
+import type { QQAttachmentInput, QQAuthor, QQDispatchData, QQNormalizedMessage, QQQuoteInput, QQMediaKind } from '../types.js'
+
+function authorId(author: QQAuthor = {}): string {
+  return String(author.user_openid || author.member_openid || author.id || '')
+}
+
+function authorName(author: QQAuthor = {}): string {
+  return String(author.username || author.nickname || '').trim()
+}
+
+/** Replace QQ's stable mention tokens with the best known display name. */
+export function renderQQMentionNames(
+  text: string,
+  data: QQDispatchData,
+  lookup: (platformUserId: string) => string | undefined = () => undefined,
+): string {
+  const mentions = Array.isArray(data.mentions) ? data.mentions : []
+  let rendered = String(text || '')
+  for (const item of mentions) {
+    if (!item || typeof item !== 'object') continue
+    const id = String(item.user_openid || item.member_openid || item.openid || item.id || '').trim()
+    if (!id) continue
+    const name = String(item.username || item.nickname || item.display_name || item.name || lookup(id) || '').trim()
+    if (!name) continue
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    rendered = rendered
+      .replace(new RegExp(`<@!?${escaped}>`, 'g'), `@${name}`)
+      .replace(new RegExp(`@${escaped}(?![A-Za-z0-9_-])`, 'g'), `@${name}`)
+  }
+  return rendered
+}
+
+export function messageMentionsBot(data: QQDispatchData, eventType: string): boolean {
+  if (!Object.prototype.hasOwnProperty.call(data, 'mentions')) {
+    return eventType === 'GROUP_AT_MESSAGE_CREATE'
+  }
+  const mentions = data.mentions
+  if (!Array.isArray(mentions)) return false
+  if (mentions.length === 0) return eventType === 'GROUP_AT_MESSAGE_CREATE'
+  for (const item of mentions) {
+    if (!item || typeof item !== 'object' || item.bot !== true) continue
+    if (Object.prototype.hasOwnProperty.call(item, 'is_you')) return item.is_you === true
+    return true
+  }
+  return false
+}
+
+export function botMentionId(data: QQDispatchData, eventType: string): string {
+  const mentions = data.mentions
+  if (Array.isArray(mentions)) {
+    for (const item of mentions) {
+      if (!item || typeof item !== 'object' || item.bot !== true) continue
+      for (const key of ['id', 'user_openid', 'member_openid', 'openid'] as const) {
+        if (item[key]) return String(item[key])
+      }
+    }
+  }
+  if (eventType === 'GROUP_AT_MESSAGE_CREATE') {
+    const match = String(data.content || '').match(/<@!?([^>]+)>/)
+    if (match?.[1]) return match[1]
+  }
+  return ''
+}
+
+export function normalizeQQDispatch(
+  eventType: string,
+  data: QQDispatchData | undefined,
+  accountId: number,
+): QQNormalizedMessage | undefined {
+  if (!data || typeof data !== 'object') return undefined
+  if (eventType === 'C2C_MESSAGE_CREATE') {
+    const senderId = authorId(data.author)
+    if (!senderId) return undefined
+    return {
+      platform: 'qq', accountId, chatType: 'c2c', chatId: senderId,
+      senderId, senderName: authorName(data.author), groupOpenid: undefined,
+      messageId: String(data.id || ''), msgIdx: messageSceneIndex(data), refMsgIdx: messageReferenceIndex(data), text: String(data.content || '').trim(),
+      quotedText: extractQuotedText(data), quote: extractQuote(data), attachments: extractAttachments(data), mentioned: true,
+      botMentionId: '', raw: data,
+    }
+  }
+  if (eventType === 'GROUP_AT_MESSAGE_CREATE' || eventType === 'GROUP_MESSAGE_CREATE') {
+    const senderId = authorId(data.author)
+    const groupOpenid = String(data.group_openid || '')
+    if (!senderId || !groupOpenid) return undefined
+    return {
+      platform: 'qq', accountId, chatType: 'group', chatId: groupOpenid,
+      senderId, senderName: authorName(data.author), groupOpenid,
+      messageId: String(data.id || ''), msgIdx: messageSceneIndex(data), refMsgIdx: messageReferenceIndex(data), text: String(data.content || '').trim(),
+      quotedText: extractQuotedText(data), quote: extractQuote(data), attachments: extractAttachments(data), mentioned: messageMentionsBot(data, eventType),
+      botMentionId: botMentionId(data, eventType), raw: data,
+    }
+  }
+  return undefined
+}
+
+function extractQuotedText(data: QQDispatchData): string {
+  const reference = data.message_reference || data.reference || data.quote
+  if (reference && typeof reference === 'object') {
+    const text = String(reference.content || reference.text || '').trim()
+    if (text) return decodeQQText(text)
+  }
+
+  // QQ's native reply payload uses message_scene.ext/ref_msg_idx and keeps the
+  // referenced message in msg_elements instead of message_reference.
+  const elements = data.msg_elements || []
+  if (elements.length === 0) return ''
+  const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : []
+  const referenceIndex = messageReferenceIndex(data)
+  const ownIndex = sceneValue(ext, 'msg_idx')
+  const element = referenceIndex
+    ? elements.find(item => String(item.msg_idx || '') === referenceIndex)
+    : elements.find(item => String(item.msg_idx || '') !== ownIndex)
+  if (!element) return ''
+  return decodeQQText(String(element.content || element.text || '').trim())
+}
+
+function extractQuote(data: QQDispatchData): QQQuoteInput | undefined {
+  const text = extractQuotedText(data)
+  const reference = data.message_reference || data.reference || data.quote
+  let record = reference && typeof reference === 'object' ? reference : undefined
+  if (!record && Array.isArray(data.msg_elements)) {
+    const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : []
+    const referenceIndex = messageReferenceIndex(data)
+    const element = referenceIndex ? data.msg_elements.find(item => String(item.msg_idx || '') === referenceIndex) : undefined
+    if (element) record = element
+  }
+  const messageId = String(record?.id || record?.message_id || record?.messageId || '').trim() || undefined
+  const sender = record?.author && typeof record.author === 'object' ? record.author as QQAuthor : undefined
+  const senderId = String(sender?.user_openid || sender?.member_openid || sender?.id || record?.sender_id || '').trim() || undefined
+  const senderName = String(sender?.username || sender?.nickname || record?.sender_name || '').trim() || undefined
+  const attachments = extractAttachments(record as QQDispatchData | undefined, true)
+  if (!text && !messageId && !senderId && attachments.length === 0) return undefined
+  return { messageId, senderId, senderName, text, attachments }
+}
+
+function messageSceneIndex(data: QQDispatchData): string | undefined {
+  const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : []
+  return sceneValue(ext, 'msg_idx') || String(data.id || '').trim() || undefined
+}
+
+function messageReferenceIndex(data: QQDispatchData): string | undefined {
+  const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : []
+  return sceneValue(ext, 'ref_msg_idx') || sceneValue(ext, 'msg_ref_idx') || undefined
+}
+
+function extractAttachments(data: QQDispatchData | undefined, quoted = false): QQAttachmentInput[] {
+  if (!data) return []
+  const values: Array<Record<string, unknown>> = []
+  if (Array.isArray(data.attachments)) values.push(...data.attachments.filter(isRecord))
+  if (Array.isArray(data.msg_elements)) {
+    const ext = Array.isArray(data.message_scene?.ext) ? data.message_scene.ext : []
+    const referenceIndex = sceneValue(ext, 'ref_msg_idx') || sceneValue(ext, 'msg_ref_idx')
+    for (const element of data.msg_elements) {
+      if (!quoted && referenceIndex && String(element.msg_idx || '') === referenceIndex) continue
+      const type = String(element.type || element.element_type || element.kind || '').toLowerCase()
+      if (type && !/(image|photo|picture|file|video|audio|voice|record|media|attachment)/u.test(type)) continue
+      if (isRecord(element.attachment)) values.push(element.attachment)
+      else values.push(element)
+    }
+  }
+  const output: QQAttachmentInput[] = []
+  const seen = new Set<string>()
+  for (const value of values) {
+    const sourceUrl = firstString(value, ['url', 'file_url', 'download_url', 'downloadUrl', 'href', 'file'])
+    const platformFileId = firstString(value, ['file_id', 'fileid', 'fileId', 'id'])
+    if (!sourceUrl && !platformFileId && !isRecord(value.attachment)) continue
+    const filename = firstString(value, ['filename', 'file_name', 'name']) || inferFilename(sourceUrl) || 'QQ附件'
+    const contentType = firstString(value, ['content_type', 'contentType', 'mime', 'mime_type', 'type'])
+    const kind = mediaKind(contentType, filename, String(value.type || value.element_type || value.kind || ''))
+    const key = `${platformFileId || ''}|${sourceUrl || ''}|${filename}|${kind}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    output.push({
+      sourceUrl, filename, contentType, platformFileId,
+      size: numberValue(value, ['size', 'file_size', 'bytes']),
+      width: numberValue(value, ['width', 'img_width']),
+      height: numberValue(value, ['height', 'img_height']),
+      durationMs: numberValue(value, ['duration_ms', 'duration']), quoted, kind,
+    })
+  }
+  return output
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function firstString(value: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const item = value[key]
+    if (typeof item === 'string' && item.trim()) return item.trim()
+  }
+  return undefined
+}
+
+function numberValue(value: Record<string, unknown>, keys: string[]): number | undefined {
+  for (const key of keys) {
+    const item = Number(value[key])
+    if (Number.isFinite(item) && item >= 0) return item
+  }
+  return undefined
+}
+
+function inferFilename(url: string | undefined): string | undefined {
+  if (!url) return undefined
+  try {
+    const name = decodeURIComponent(new URL(url).pathname.split('/').pop() || '')
+    return name && name !== '/' ? name : undefined
+  } catch { return undefined }
+}
+
+function mediaKind(contentType: string | undefined, filename: string, rawType: string): QQMediaKind {
+  const value = `${contentType || ''} ${filename} ${rawType}`.toLowerCase()
+  if (/voice|record|audio|\.(amr|silk|mp3|wav|ogg|m4a)(?:$|\?)/u.test(value)) return 'voice'
+  if (/video|\.(mp4|mov|avi|mkv|webm)(?:$|\?)/u.test(value)) return 'video'
+  if (/image|photo|picture|\.(png|jpe?g|gif|webp|bmp|heic)(?:$|\?)/u.test(value)) return 'image'
+  if (/audio/u.test(value)) return 'audio'
+  return 'file'
+}
+
+function sceneValue(ext: unknown[], key: string): string {
+  const prefix = `${key}=`
+  for (const item of ext) {
+    if (typeof item === 'string' && item.startsWith(prefix)) return item.slice(prefix.length).trim()
+    if (!item || typeof item !== 'object') continue
+    const record = item as Record<string, unknown>
+    if (record.key === key) return String(record.value || '').trim()
+    if (key in record) return String(record[key] || '').trim()
+  }
+  return ''
+}
+
+function decodeQQText(value: string): string {
+  return value.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&')
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import type {} from '@deepseek-ai/dsh-commands'
+import type {} from '@deepseek-ai/dsh-client-connection'
+import { DshQQBridge } from './session/agent-bridge.js'
+import { resolveConfig } from './config.js'
+import { QQChatDatabase } from './storage/db.js'
+import { QQChatLogger } from './shared/logging.js'
+import { MemoryEngine } from './storage/memory.js'
+import { QQMediaStore } from './media/store.js'
+import { QQApiClient } from './gateway/api.js'
+import { QQBindService } from './gateway/auth.js'
+import { createQQChatRpc } from './transport/rpc.js'
+import { QQChatRuntime } from './session/runtime.js'
+import type { LoggerLike, QQChatConfigInput } from './types.js'
+
+export const name = 'dsh-qqchat'
+export const inject = ['connection', 'agents', 'agentDefaultModel', 'commands', 'llm', 'tools', 'workspaceRegistry'] as const
+
+export function apply(ctx: Context, inputConfig: QQChatConfigInput = {}): void {
+  const config = resolveConfig(inputConfig)
+  mkdirSync(config.dataDir, { recursive: true, mode: 0o700 })
+  const db = new QQChatDatabase(join(config.dataDir, 'qqchat.sqlite'))
+  const baseLogger = (ctx as unknown as { logger?: LoggerLike }).logger || console
+  const logger = new QQChatLogger(baseLogger)
+  const api = new QQApiClient(db, config)
+  const auth = new QQBindService(db, config)
+  const memory = new MemoryEngine(ctx, db, config, logger)
+  const media = new QQMediaStore(db, ctx, logger)
+  const bridge = new DshQQBridge(ctx, db, memory, config, logger)
+  const runtime = new QQChatRuntime(ctx, db, api, auth, memory, bridge, config, logger, media)
+
+  ctx.connection.rpc.handle('/qqchat', createQQChatRpc(runtime), { authority: 'loopback' })
+  ctx.effect(() => {
+    void runtime.start().catch(error => logger.error?.(error))
+    return () => runtime.stop()
+  }, 'dsh-qqchat runtime')
+}
+
+export type { QQChatConfig, QQChatConfigInput } from './types.js'
+export { QQChatDatabase } from './storage/db.js'
+export { normalizeQQDispatch } from './gateway/normalize.js'
+
+export default { name, inject, apply }

package/src/media/image-tool.ts

@@ -0,0 +1,62 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { QQChatDatabase } from '../storage/db.js'
+
+/** Exposes stored QQ images through DSH's durable image-block seam. */
+export function registerQQImageTool(ctx: Context, db: QQChatDatabase, isAllowed: (agentId: string, attachmentId: string) => boolean = () => true): () => void {
+  const definition = defineTool({
+    name: 'qqchat_describe_image',
+    description: '查看 QQ 消息中的图片。传入 QQChat 提供的 attachment_id，可用于 OCR、截图、界面和照片分析。',
+    parameters: {
+      attachment_id: { type: 'string', required: true, description: 'QQChat 图片附件 ID' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          ok: { type: 'boolean' },
+          attachment_id: { type: 'string' },
+          filename: { type: 'string' },
+          media_type: { type: 'string' },
+          bytes: { type: 'number' },
+          image_ref: { type: 'json' },
+          error: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+      render: (_args, value) => {
+        if (!value.ok) return [{ type: 'text', text: value.error || '图片不可用。' }]
+        if (!value.image_ref || typeof value.image_ref !== 'object') return [{ type: 'text', text: '图片已找到，但当前 DSH 没有可用的图片附件服务。' }]
+        return [
+          { type: 'text', text: `已加载图片：${value.filename || value.attachment_id}` },
+          { type: 'image', attachment: value.image_ref as never },
+        ]
+      },
+    },
+    async execute(args, exec) {
+      const attachment = db.attachmentById(args.attachment_id)
+      if (!attachment || attachment.kind !== 'image' || !attachment.imageRef) {
+        return { ok: false, attachment_id: args.attachment_id, error: '找不到可查看的 QQ 图片附件。' }
+      }
+      const agent = exec.agent as unknown as { id?: string; options?: { provider?: string; model?: string } } | undefined
+      if (!isAllowed(String(agent?.id || ''), args.attachment_id)) {
+        return { ok: false, attachment_id: args.attachment_id, error: '当前 QQ 消息没有权限访问这张图片。' }
+      }
+      if (agent?.options?.provider && agent.options.model) {
+        try {
+          const info = await ctx.llm.resolveModelInfo(agent.options.provider, agent.options.model, exec.signal)
+          if (!info.inputModalities?.includes('image')) {
+            return { ok: false, attachment_id: args.attachment_id, error: '当前模型不支持图片输入。' }
+          }
+        } catch {
+          return { ok: false, attachment_id: args.attachment_id, error: '无法确认当前模型是否支持图片输入。' }
+        }
+      }
+      return {
+        ok: true, attachment_id: attachment.id, filename: attachment.filename,
+        media_type: attachment.imageRef.mediaType, bytes: attachment.sizeBytes, image_ref: { ...attachment.imageRef },
+      }
+    },
+  })
+  return ctx.tools.register(definition)
+}

package/src/media/media-tools.ts

@@ -0,0 +1,66 @@
+import { readFile, stat } from 'node:fs/promises'
+import { execFile as execFileCallback } from 'node:child_process'
+import { promisify } from 'node:util'
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { QQChatDatabase } from '../storage/db.js'
+
+const execFile = promisify(execFileCallback)
+const MAX_TEXT_BYTES = 2 * 1024 * 1024
+
+export function registerQQMediaTools(
+  ctx: Context,
+  db: QQChatDatabase,
+  isAllowed: (agentId: string, attachmentId: string) => boolean = () => true,
+): () => void {
+  const readFileTool = defineTool({
+    name: 'qqchat_read_file',
+    description: '读取 QQ 消息中的文本文件。传入 QQChat 提供的 attachment_id；二进制文件不会被当作文本读取。',
+    parameters: { attachment_id: { type: 'string', required: true, description: 'QQChat 文件附件 ID' } },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    async execute(args, exec) {
+      const attachment = db.attachmentById(args.attachment_id)
+      const agentId = String((exec.agent as unknown as { id?: string } | undefined)?.id || '')
+      if (!attachment || !attachment.localPath || !isAllowed(agentId, args.attachment_id)) return '当前 QQ 消息没有可读取的文件附件。'
+      if (attachment.kind !== 'file') return '这个附件不是普通文本文件。'
+      if (attachment.sizeBytes > MAX_TEXT_BYTES) return `文件过大，超过 ${MAX_TEXT_BYTES} 字节读取上限。`
+      try {
+        return await readFile(attachment.localPath, { encoding: 'utf8', signal: exec.signal })
+      } catch {
+        return '文件读取失败或文件已过期。'
+      }
+    },
+  })
+
+  const mediaInfoTool = defineTool({
+    name: 'qqchat_media_info',
+    description: '查看 QQ 图片、语音、视频或文件附件的元数据；视频可在服务器安装 ffprobe 时补充流信息。',
+    parameters: { attachment_id: { type: 'string', required: true, description: 'QQChat 媒体附件 ID' } },
+    output: {
+      schema: { type: 'object', properties: { ok: { type: 'boolean' }, info: { type: 'string' }, error: { type: 'string' } }, additionalProperties: false },
+      render: (_args, value) => [{ type: 'text', text: value.ok ? (value.info || '{}') : (value.error || '媒体信息不可用。') }],
+    },
+    async execute(args, exec) {
+      const attachment = db.attachmentById(args.attachment_id)
+      const agentId = String((exec.agent as unknown as { id?: string } | undefined)?.id || '')
+      if (!attachment || !isAllowed(agentId, args.attachment_id)) return { ok: false, error: '当前 QQ 消息没有权限访问这个附件。' }
+      const info: Record<string, unknown> = {
+        attachmentId: attachment.id, kind: attachment.kind, filename: attachment.filename,
+        contentType: attachment.contentType || null, sizeBytes: attachment.sizeBytes,
+      }
+      if (attachment.localPath) {
+        try { info.fileSize = Number((await stat(attachment.localPath)).size) } catch {}
+        if (attachment.kind === 'video' || attachment.kind === 'voice' || attachment.kind === 'audio') {
+          try {
+            const result = await execFile('ffprobe', ['-v', 'quiet', '-print_format', 'json', '-show_format', '-show_streams', attachment.localPath], { timeout: 10_000, signal: exec.signal })
+            info.ffprobe = JSON.parse(result.stdout)
+          } catch { info.ffprobe = 'ffprobe 不可用或媒体格式无法探测。' }
+        }
+      }
+      return { ok: true, info: JSON.stringify(info, null, 2) }
+    },
+  })
+  const disposeRead = ctx.tools.register(readFileTool)
+  const disposeInfo = ctx.tools.register(mediaInfoTool)
+  return () => { disposeInfo(); disposeRead() }
+}

package/src/media/store.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto'
+import { access, mkdir, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join } from 'node:path'
+import { lookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+import type { Context } from '@deepseek-ai/cordis'
+import type { LoggerLike, QQAttachmentInput, QQMediaKind, StoredAttachmentSummary } from '../types.js'
+import type { QQChatDatabase } from '../storage/db.js'
+
+const MAX_FILE_BYTES = 50 * 1024 * 1024
+const MAX_MESSAGE_BYTES = 100 * 1024 * 1024
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+
+export class QQMediaStore {
+  readonly root: string
+
+  constructor(private readonly db: QQChatDatabase, private readonly ctx?: Context, private readonly logger: LoggerLike = console) {
+    this.root = join(dirname(db.path), 'media')
+  }
+
+  async ingest(accountId: number, messageId: string, attachments: QQAttachmentInput[]): Promise<StoredAttachmentSummary[]> {
+    const result: StoredAttachmentSummary[] = []
+    let messageBytes = 0
+    for (const [sourceIndex, input] of attachments.slice(0, 12).entries()) {
+      try {
+        if (input.attachmentId) {
+          const existingById = this.db.attachmentById(input.attachmentId)
+          if (existingById?.localPath) {
+            try {
+              await access(existingById.localPath)
+              this.db.extendAttachment(existingById.id, Date.now() + RETENTION_MS)
+            result.push({ ...existingById, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId || existingById.sourceFileId, sourceIndex })
+              continue
+            } catch {}
+          }
+        }
+        const reusable = this.db.findReusableAttachment(accountId, messageId, input.platformFileId, input.kind)
+        if (reusable?.localPath) {
+          try {
+            await access(reusable.localPath)
+            this.db.extendAttachment(reusable.id, Date.now() + RETENTION_MS)
+            result.push({ ...reusable, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId || reusable.sourceFileId, sourceIndex })
+            continue
+          } catch {}
+        }
+        const downloaded = await this.download(input, messageBytes)
+        if (!downloaded) continue
+        messageBytes += downloaded.data.byteLength
+        const id = `qqatt-${randomUUID()}`
+        const extension = safeExtension(input.filename, input.contentType)
+        await mkdir(this.root, { recursive: true, mode: 0o700 })
+        const path = join(this.root, `${id}${extension}`)
+        await writeFile(path, downloaded.data, { mode: 0o600 })
+        const imageRef = await this.saveImageRef(input, downloaded.data)
+        const kind = input.kind || inferKind(input.contentType, input.filename)
+        const summary: StoredAttachmentSummary = {
+          id, kind, filename: safeFilename(input.filename), contentType: input.contentType,
+          sizeBytes: downloaded.data.byteLength, quoted: Boolean(input.quoted), sourceFileId: input.platformFileId, sourceIndex, localPath: path, imageRef,
+        }
+        this.db.saveAttachment({ id, accountId, sourceMessageId: messageId, sourceFileId: input.platformFileId,
+          kind, filename: summary.filename, contentType: input.contentType, sizeBytes: summary.sizeBytes,
+          localPath: path, imageRef, expiresAt: Date.now() + RETENTION_MS })
+        result.push(summary)
+      } catch (error) {
+        this.logger.warn?.(`[dsh-qqchat] QQ media ingest failed for ${safeFilename(input.filename)}: ${error instanceof Error ? error.message : String(error)}`)
+        // Media is optional input. The text turn must remain usable when a download fails.
+      }
+    }
+    return result
+  }
+
+  async cleanup(): Promise<void> {
+    const cutoff = Date.now()
+    this.db.expireQuoteIndex(cutoff)
+    this.db.expireAttachments(cutoff)
+    for (const path of this.db.expiredAttachmentPaths(cutoff)) {
+      try {
+        await rm(path, { force: true })
+        this.db.markAttachmentDeleted(path)
+      } catch {
+        // Keep the expired row for the next sweep if the physical object is busy.
+      }
+    }
+    await mkdir(this.root, { recursive: true, mode: 0o700 })
+  }
+
+  private async download(input: QQAttachmentInput, currentBytes: number): Promise<{ data: Uint8Array } | undefined> {
+    const source = input.sourceUrl
+    if (!source) return undefined
+    let url = source
+    for (let redirect = 0; redirect <= 3; redirect++) {
+      const parsed = new URL(url)
+      if (parsed.protocol !== 'https:') throw new Error('QQ media URL must use HTTPS')
+      await assertPublicHost(parsed.hostname)
+      const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(20_000) })
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        const location = response.headers.get('location')
+        if (!location) return undefined
+        url = new URL(location, url).toString()
+        continue
+      }
+      if (!response.ok) return undefined
+      const length = Number(response.headers.get('content-length') || 0)
+      if (length > MAX_FILE_BYTES || currentBytes + length > MAX_MESSAGE_BYTES) throw new Error('QQ media size limit exceeded')
+      const data = new Uint8Array(await response.arrayBuffer())
+      if (data.byteLength > MAX_FILE_BYTES || currentBytes + data.byteLength > MAX_MESSAGE_BYTES) throw new Error('QQ media size limit exceeded')
+      return { data }
+    }
+    return undefined
+  }
+
+  private async saveImageRef(input: QQAttachmentInput, data: Uint8Array): Promise<StoredAttachmentSummary['imageRef'] | undefined> {
+    const service = this.ctx?.get('attachments') as { saveImage(input: { data: Uint8Array; mediaType: string; name?: string }): Promise<StoredAttachmentSummary['imageRef']> } | undefined
+    const mediaType = sniffImageType(data)
+    if (!service || !mediaType) return undefined
+    try { return await service.saveImage({ data, mediaType, name: safeFilename(input.filename) }) }
+    catch { return undefined }
+  }
+}
+
+async function assertPublicHost(hostname: string): Promise<void> {
+  const addresses = isIP(hostname) ? [hostname] : (await lookup(hostname, { all: true })).map(item => item.address)
+  for (const address of addresses) {
+    if (isPrivateAddress(address)) throw new Error('QQ media URL resolves to a private address')
+  }
+}
+
+function isPrivateAddress(address: string): boolean {
+  if (address === '::1' || address === '0.0.0.0' || address === '::') return true
+  if (address.includes(':')) return address === '::1' || address.toLowerCase().startsWith('fc') || address.toLowerCase().startsWith('fd') || address.toLowerCase().startsWith('fe8') || address.toLowerCase().startsWith('fe9') || address.toLowerCase().startsWith('fea') || address.toLowerCase().startsWith('feb')
+  const parts = address.split('.').map(Number)
+  const [a, b] = parts
+  return parts.length === 4 && (a === 10 || a === 127 || (a === 172 && b !== undefined && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254))
+}
+
+function sniffImageType(data: Uint8Array): 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | undefined {
+  if (data.length >= 8 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) return 'image/png'
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg'
+  if (data.length >= 6 && new TextDecoder().decode(data.slice(0, 6)) === 'GIF89a') return 'image/gif'
+  if (data.length >= 12 && new TextDecoder().decode(data.slice(0, 4)) === 'RIFF' && new TextDecoder().decode(data.slice(8, 12)) === 'WEBP') return 'image/webp'
+  return undefined
+}
+
+function safeFilename(value: string): string { return basename(value || 'QQ附件').replace(/[^\p{L}\p{N}._-]+/gu, '_').slice(0, 160) || 'QQ附件' }
+function safeExtension(filename: string, contentType?: string): string {
+  const ext = extname(filename).replace(/[^a-zA-Z0-9.]/g, '').slice(0, 12)
+  if (ext) return ext.toLowerCase()
+  const typeExtension = contentType?.split('/')[1]
+  return typeExtension ? `.${typeExtension.replace(/[^a-zA-Z0-9]/g, '')}` : '.bin'
+}
+function inferKind(contentType?: string, filename = ''): QQMediaKind {
+  const value = `${contentType || ''} ${filename}`.toLowerCase()
+  if (value.includes('video') || /\.(mp4|mov|avi|mkv|webm)$/u.test(value)) return 'video'
+  if (value.includes('audio') || /\.(mp3|wav|ogg|m4a|amr|silk)$/u.test(value)) return 'voice'
+  if (value.includes('image') || /\.(png|jpe?g|gif|webp|bmp|heic)$/u.test(value)) return 'image'
+  return 'file'
+}