koishi-plugin-kkk 3.7.1 → 3.7.2

package/scripts/smoke-md-image.cjs

@@ -0,0 +1,206 @@
+/**
+ * 冒烟测试：**图片统一改走 markdown**（用户要求）。
+ *
+ * 背景（用户反馈）：
+ *   - 「所有的图片发送都要走 md，不然太模糊了」—— QQ 的普通图片消息会被压糊，md 图片不会；
+ *   - 「![#px大小#px大小]() 必须要 #px，不然手机不会显示」—— md 图片必须写死尺寸。
+ * 所以 compat 的发送出口会把 image 段改写成 `![#宽px #高px](https://…)`（见 compat/imageMarkdown.ts）。
+ *
+ * 这里验四件事：
+ *   1. 尺寸真的读出来了（PNG / JPEG 两种头），并且写进了 md；
+ *   2. **只在认 markdown 的平台上改**（qq 改；onebot / qqguild / 未知平台一律不动）；
+ *   3. 该跳过的都跳过（消息里有视频/语音/文件时不能改，否则 md 内容会被适配器丢掉）；
+ *   4. 改不动就**原样发**（上传失败、没有 assets 服务），绝不把图弄丢；
+ *   5. 走的是真出口：`Message.reply` / `KkkBot.sendMsg` 里就要已经改好了。
+ *
+ * 用法：node scripts/smoke-md-image.cjs
+ */
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const pluginRoot = path.resolve(__dirname, '..')
+
+let failures = 0
+const check = (name, ok, detail) => {
+  console.log((ok ? '  ✅ ' : '  ❌ ') + name + (detail ? '  —— ' + detail : ''))
+  if (!ok) failures++
+}
+
+const runtime = require(path.join(pluginRoot, 'lib/compat/runtime.js'))
+const segment = require(path.join(pluginRoot, 'lib/compat/segment.js')).segment
+const mdImage = require(path.join(pluginRoot, 'lib/compat/imageMarkdown.js'))
+const nodeKarin = require(path.join(pluginRoot, 'lib/compat/node-karin.js'))
+
+/** 一个「够用」的 PNG：只补到 readImageSize 要读的字段（IHDR 的宽高） */
+const fakePng = (width, height) => {
+  const buffer = Buffer.alloc(32)
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(buffer, 0)
+  buffer.writeUInt32BE(13, 8)
+  buffer.write('IHDR', 12, 'latin1')
+  buffer.writeUInt32BE(width, 16)
+  buffer.writeUInt32BE(height, 20)
+  return buffer
+}
+
+/** 一个「够用」的 JPEG：SOF0 段里有高宽即可 */
+const fakeJpeg = (width, height) => {
+  const buffer = Buffer.alloc(20)
+  buffer[0] = 0xff
+  buffer[1] = 0xd8
+  buffer[2] = 0xff
+  buffer[3] = 0xc0
+  buffer.writeUInt16BE(17, 4)
+  buffer[6] = 0x08
+  buffer.writeUInt16BE(height, 7)
+  buffer.writeUInt16BE(width, 9)
+  return buffer
+}
+
+const dataUri = (buffer) => 'data:image/png;base64,' + buffer.toString('base64')
+
+let uploads = 0
+let uploadShouldFail = false
+const noop = () => {}
+const ctx = {
+  get: () => undefined,
+  logger: () => ({ info: noop, warn: noop, error: noop, debug: noop, mark: noop }),
+  assets: {
+    upload: async (dataUriText, name) => {
+      uploads++
+      if (uploadShouldFail) throw new Error('assets 挂了')
+      return 'https://assets.example.com/' + String(name)
+    }
+  }
+}
+runtime.bindRuntime({ ctx, config: {}, pluginRoot, dataRoot: os.tmpdir() })
+
+const textOf = (element) => {
+  if (!element) return ''
+  if (element.type === 'text') return element.attrs?.content ?? ''
+  return (element.children ?? []).map(textOf).join('')
+}
+
+const run = async () => {
+  console.log('— 尺寸读得出来 —')
+  mdImage.clearMarkdownImageCache()
+  uploads = 0
+  const pngMd = await mdImage.markdownImageOf(dataUri(fakePng(600, 400)))
+  check('PNG 宽高写进了 md', pngMd === '![#600px #400px](https://assets.example.com/kkk-md.png)', pngMd)
+  check('PNG 按 image/png 上传（扩展名跟着走）', String(pngMd).endsWith('.png)'), pngMd)
+
+  const jpegMd = await mdImage.markdownImageOf(dataUri(fakeJpeg(2880, 1440)))
+  check('JPEG 宽高写进了 md', jpegMd === '![#2880px #1440px](https://assets.example.com/kkk-md.jpg)', jpegMd)
+
+  const base64Md = await mdImage.markdownImageOf('base64://' + fakePng(12, 34).toString('base64'))
+  check('base64:// 也认', base64Md === '![#12px #34px](https://assets.example.com/kkk-md.png)', base64Md)
+
+  const file = path.join(os.tmpdir(), 'kkk-md-smoke-' + Date.now() + '.png')
+  fs.writeFileSync(file, fakePng(8, 9))
+  const fileMd = await mdImage.markdownImageOf(file)
+  check('本地路径也认', fileMd === '![#8px #9px](https://assets.example.com/kkk-md.png)', fileMd)
+  fs.rmSync(file, { force: true })
+
+  console.log('— 同一张图不重复上传 —')
+  mdImage.clearMarkdownImageCache()
+  uploads = 0
+  const again = dataUri(fakePng(100, 50))
+  await mdImage.markdownImageOf(again)
+  await mdImage.markdownImageOf(again)
+  check('第二次走缓存（只上传一次）', uploads === 1, 'uploads=' + uploads)
+
+  console.log('— 只改认 markdown 的平台 —')
+  const image = () => segment.image(dataUri(fakePng(600, 400)))
+  for (const platform of ['onebot', 'napcat', 'lagrange', 'go-cqhttp', 'chronocat', 'mirai', 'qqguild', 'sandbox', '']) {
+    const list = [image()]
+    const out = await mdImage.imagesToMarkdown(list, platform)
+    check(platform + ' 平台保持图片段', out.length === 1 && out[0] === list[0] && out[0].type === 'img')
+  }
+  const qqOut = await mdImage.imagesToMarkdown([image()], 'qq')
+  check('qq 平台改成 markdown', qqOut.length === 1 && qqOut[0].type === 'markdown', qqOut[0]?.type)
+  check('qq 平台的 md 里带 #宽px #高px', /!\[#600px #400px\]\(https:\/\//.test(textOf(qqOut[0])), textOf(qqOut[0]))
+
+  console.log('— 该跳过的都跳过 —')
+  const withVideo = [image(), segment.video('data:video/mp4;base64,AAAA')]
+  const videoOut = await mdImage.imagesToMarkdown(withVideo, 'qq')
+  check('带视频的消息不动（md 会被适配器丢掉）', videoOut[0].type === 'img' && videoOut[1].type === 'video')
+  const withAudio = [image(), segment.audio('data:audio/mpeg;base64,AAAA')]
+  check('带语音的消息不动', (await mdImage.imagesToMarkdown(withAudio, 'qq'))[0].type === 'img')
+  const noImage = [segment.text('只有文字')]
+  const noImageOut = await mdImage.imagesToMarkdown(noImage, 'qq')
+  check('没有图片就不进这套逻辑', noImageOut[0] === noImage[0])
+
+  console.log('— 顺序与合并 —')
+  const mixed = [segment.text('看图：'), image(), segment.text('就这些')]
+  const mixedOut = await mdImage.imagesToMarkdown(mixed, 'qq')
+  check('文字 / md 图片 / 文字 顺序不变',
+    mixedOut.length === 3 && mixedOut[0].type === 'text' && mixedOut[1].type === 'markdown' && mixedOut[2].type === 'text',
+    mixedOut.map((element) => element.type).join(','))
+  const twice = await mdImage.imagesToMarkdown([image(), image(), segment.text('尾')], 'qq')
+  check('连续图片合成一条 markdown（两行）',
+    twice.length === 2 && twice[0].type === 'markdown' && String(textOf(twice[0])).split(String.fromCharCode(10)).length === 2,
+    twice.map((element) => element.type).join(','))
+
+  console.log('— 改不动就原样发，绝不丢图 —')
+  uploadShouldFail = true
+  mdImage.clearMarkdownImageCache()
+  const failedList = [image()]
+  const failedOut = await mdImage.imagesToMarkdown(failedList, 'qq')
+  check('上传失败时退回图片段', failedOut.length === 1 && failedOut[0] === failedList[0] && failedOut[0].type === 'img')
+  uploadShouldFail = false
+
+  const savedCtx = ctx.assets
+  delete ctx.assets
+  mdImage.clearMarkdownImageCache()
+  const noAssetsList = [image()]
+  const noAssetsOut = await mdImage.imagesToMarkdown(noAssetsList, 'qq')
+  check('没有 assets 服务时退回图片段', noAssetsOut[0] === noAssetsList[0] && noAssetsOut[0].type === 'img')
+  ctx.assets = savedCtx
+
+  console.log('— 读不出尺寸的图，宁可发普通图片 —')
+  mdImage.clearMarkdownImageCache()
+  const unknown = Buffer.alloc(64, 0x42)
+  const unknownList = [segment.image('data:application/octet-stream;base64,' + unknown.toString('base64'))]
+  const unknownOut = await mdImage.imagesToMarkdown(unknownList, 'qq')
+  check('认不出格式的图保持图片段（不带尺寸的 md 手机上不显示）',
+    unknownOut.length === 1 && unknownOut[0] === unknownList[0] && unknownOut[0].type === 'img')
+
+  console.log('— 真出口上就已经改好了（Message.reply / KkkBot.sendMsg） —')
+  const sent = []
+  const makeBot = (platform) => new nodeKarin.KkkBot({
+    platform,
+    selfId: '1',
+    sendMessage: async (channelId, elements) => {
+      sent.push({ channelId, elements })
+      return ['mid-1']
+    }
+  })
+
+  const qqMessage = new nodeKarin.Message({ bot: makeBot('qq'), contact: { peer: 'group:1' } })
+  await qqMessage.reply([segment.image(dataUri(fakePng(320, 240)))])
+  check('Message.reply 发出去的是 markdown',
+    sent.length === 1 && sent[0].elements.length === 1 && sent[0].elements[0].type === 'markdown',
+    sent[0]?.elements?.map((element) => element.type).join(','))
+  check('Message.reply 的 md 带尺寸', /!\[#320px #240px\]/.test(textOf(sent[0].elements[0])), textOf(sent[0].elements[0]))
+
+  sent.length = 0
+  const onebotBot = makeBot('onebot')
+  await onebotBot.sendMsg('group:1', [segment.image(dataUri(fakePng(320, 240)))])
+  check('OneBot 的 KkkBot.sendMsg 保持图片段',
+    sent.length === 1 && sent[0].elements[0].type === 'img', sent[0]?.elements?.[0]?.type)
+
+  sent.length = 0
+  const qqBot = makeBot('qq')
+  await qqBot.sendMsg('group:1', [segment.image(dataUri(fakePng(64, 64)))])
+  check('qq 的 KkkBot.sendMsg 也改成了 markdown',
+    sent[0]?.elements?.[0]?.type === 'markdown', sent[0]?.elements?.[0]?.type)
+
+  console.log('')
+  console.log(failures === 0 ? '全部通过' : failures + ' 项失败')
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/src/compat/imageMarkdown.ts

@@ -0,0 +1,263 @@
+/**
+ * 图片段 → markdown 图片（`![#宽px #高px](url)`）。
+ *
+ * 用户反馈两条，这里一起解决：
+ *   1. **「所有的图片发送都要走 md，不然太模糊了」** —— QQ 的普通图片消息（image 段 → 适配器按
+ *      MEDIA 上传）会被客户端二次压缩，卡片上的小字糊成一团；markdown 里的图片不会被压，字是清楚的。
+ *   2. **「![#px大小#px大小]() 必须要 #px，不然手机不会显示」** —— md 图片必须写死尺寸，
+ *      不写尺寸手机端干脆不显示这张图。
+ *
+ * 所以这里在**发送出口**统一改写：compat/node-karin 的 reply / sendMsg / sendMaster 四条路径都过一遍，
+ * 业务代码照旧 e.reply(segment.image(...))，不用一处处改。
+ *
+ * 只在「认 markdown 的平台」上生效（官方 QQ：`qq`）：
+ *   - OneBot 系（NapCat / Lagrange / go-cqhttp / Chronocat…）收到 markdown 只显示成一串文字、
+ *     图片全丢（用户实测），所以那条链路继续发图片段；
+ *   - QQ 频道（`qqguild`）的适配器没有 markdown 分支，md 元素会被当纯文本渲染 → 也排除。
+ *
+ * 另外三种情况**不动**（动了只会更糟）：
+ *   - 消息里还有视频 / 语音 / 文件：适配器遇到附件会把整条消息转成 MEDIA，markdown 内容会被丢掉；
+ *   - 合并转发收集中的消息：转发节点里塞 markdown 客户端不认；
+ *   - 上传拿不到公网地址（没装 assets 服务等）、或者**读不出图片尺寸**：保持原来的图片段。
+ *     读不出尺寸是可以退回普通图片的，但**绝不能发一张不带尺寸的 markdown 图片** ——
+ *     用户实测「必须要 #px，不然手机不会显示」，那种图上手机就是一片空白。
+ */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { logger } from './logger'
+import { tryGetRuntime } from './runtime'
+import { segment } from './segment'
+
+/** OneBot 系：不渲染 markdown（见文件头） */
+const ONEBOT_LIKE = /onebot|napcat|lagrange|go-?cqhttp|chronocat|mirai/i
+
+/**
+ * 会渲染 markdown 图片的平台。
+ *
+ * 只认 `qq` 这一个平台名 —— QQ 的 markdown 是**官方机器人**能力，
+ * `qqguild`（频道）走的是另一套编码器，md 元素在那里会被当成纯文本原样发出去。
+ */
+const canUseMarkdownImage = (platform: string): boolean => {
+  const name = String(platform || '').toLowerCase()
+  if (!name) return false
+  if (ONEBOT_LIKE.test(name)) return false
+  if (name.startsWith('qqguild')) return false
+  return name === 'qq' || name.startsWith('qq-') || name.startsWith('qqbot')
+}
+
+/** 媒体段：md 和附件不能塞进同一条消息（会被适配器吃掉），所以要跳过整条改写 */
+const ATTACHMENT_TYPES = new Set(['video', 'audio', 'record', 'file'])
+
+const isImageElement = (element: any): boolean =>
+  !!element && typeof element === 'object' && (element.type === 'img' || element.type === 'image')
+
+const srcOf = (element: any): string => {
+  const attrs = element?.attrs ?? {}
+  const src = attrs.src ?? attrs.url ?? element?.data?.file ?? element?.data?.url
+  return typeof src === 'string' ? src : ''
+}
+
+/** 按二进制头认 mime（发给 assets 用；标错会让适配器按错格式处理） */
+const mimeOfBuffer = (buffer: Buffer): string => {
+  if (buffer.length >= 8 && buffer[0] === 0x89 && buffer.toString('latin1', 1, 4) === 'PNG') return 'image/png'
+  if (buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8) return 'image/jpeg'
+  if (buffer.length >= 6 && buffer.toString('latin1', 0, 3) === 'GIF') return 'image/gif'
+  if (buffer.length >= 12 && buffer.toString('latin1', 0, 4) === 'RIFF' && buffer.toString('latin1', 8, 12) === 'WEBP') return 'image/webp'
+  return 'image/jpeg'
+}
+
+/**
+ * 读出图片的**真实像素尺寸** —— md 里的 `#宽px #高px` 就靠它。
+ *
+ * 不引第三方库：卡片是 JPEG、图集是 JPEG、二维码是 PNG、实况图封面是 WebP，四种头都自己认，
+ * 免得又出现「取不到尺寸 → 正方形拉伸」或「没写尺寸 → 手机不显示」。
+ */
+const readImageSize = (buffer: Buffer): { width: number; height: number } => {
+  // PNG：IHDR 就在固定偏移
+  if (buffer.length >= 24 && buffer[0] === 0x89 && buffer.toString('latin1', 1, 4) === 'PNG') {
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+  }
+  // GIF：逻辑屏幕描述符，小端
+  if (buffer.length >= 10 && buffer.toString('latin1', 0, 3) === 'GIF') {
+    return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) }
+  }
+  // JPEG：扫到 SOF 段（SOF0..SOF15，跳过 DHT/DAC 这些非 SOF 标记）
+  if (buffer.length > 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+    let offset = 2
+    while (offset + 9 < buffer.length) {
+      if (buffer[offset] !== 0xff) { offset++; continue }
+      const marker = buffer[offset + 1]
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) }
+      }
+      const length = buffer.readUInt16BE(offset + 2)
+      if (length <= 0) break
+      offset += 2 + length
+    }
+  }
+  // WebP：VP8X（扩展）/ VP8L（无损）/ VP8（有损）三种头的写法都不一样
+  if (buffer.length >= 30 && buffer.toString('latin1', 0, 4) === 'RIFF' && buffer.toString('latin1', 8, 12) === 'WEBP') {
+    const format = buffer.toString('latin1', 12, 16)
+    if (format === 'VP8X') {
+      return { width: 1 + buffer.readUIntLE(24, 3), height: 1 + buffer.readUIntLE(27, 3) }
+    }
+    if (format === 'VP8L') {
+      const bits = buffer.readUInt32LE(21)
+      return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff) }
+    }
+    if (format === 'VP8 ') {
+      return { width: buffer.readUInt16LE(26) & 0x3fff, height: buffer.readUInt16LE(28) & 0x3fff }
+    }
+  }
+  return { width: 0, height: 0 }
+}
+
+/** 把各种写法读成 Buffer：data URI / base64:// / file:// / 本地路径 / http(s) */
+const loadImageBuffer = async (src: string): Promise<Buffer | null> => {
+  try {
+    if (src.startsWith('base64://')) return Buffer.from(src.slice('base64://'.length), 'base64')
+    if (src.startsWith('data:')) {
+      const comma = src.indexOf(',')
+      if (comma < 0) return null
+      return Buffer.from(src.slice(comma + 1), 'base64')
+    }
+    const localPath = src.startsWith('file://') ? fileURLToPath(src) : src
+    if (!/^https?:\/\//i.test(src)) {
+      if (fs.existsSync(localPath)) return fs.readFileSync(localPath)
+      return null
+    }
+    const response = await fetch(src)
+    if (!response.ok) {
+      logger.mark('[图片md] 下载失败 HTTP ' + response.status + ': ' + src.slice(0, 80))
+      return null
+    }
+    return Buffer.from(await response.arrayBuffer())
+  } catch (error: any) {
+    logger.mark('[图片md] 读取图片失败: ' + String(error?.message ?? error).slice(0, 120))
+    return null
+  }
+}
+
+/**
+ * 上传到宿主的 assets，拿到 QQ 能直接取的 https 地址。
+ *
+ * md 里的图片地址**必须是公网 http(s)**：适配器只对 data: 图片做特殊处理
+ * （见 qq-crack 的 renderMarkdownDataImages —— data 图片会被它转回 MEDIA 上传，等于白改），
+ * 相对路径/本地路径手机端也取不到。
+ */
+let warnedNoAssets = false
+
+const uploadImage = async (buffer: Buffer): Promise<string | null> => {
+  const assets: any = (tryGetRuntime() as any)?.ctx?.assets
+  if (!assets?.upload) {
+    /** 没装 assets 服务就整条链路都用不了，提示一次就够，别每张图刷一遍日志 */
+    if (!warnedNoAssets) {
+      warnedNoAssets = true
+      logger.mark('[图片md] 宿主没有 assets 服务（拿不到公网图片地址），图片继续按普通图片段发送')
+    }
+    return null
+  }
+  const mime = mimeOfBuffer(buffer)
+  const ext = mime === 'image/png' ? '.png' : mime === 'image/gif' ? '.gif' : mime === 'image/webp' ? '.webp' : '.jpg'
+  try {
+    const uploaded: any = await assets.upload('data:' + mime + ';base64,' + buffer.toString('base64'), 'kkk-md' + ext)
+    const url = typeof uploaded === 'string' ? uploaded : uploaded?.url
+    return url && /^https?:\/\//i.test(String(url)) ? String(url) : null
+  } catch (error: any) {
+    logger.mark('[图片md] 上传失败: ' + String(error?.message ?? error).slice(0, 120))
+    return null
+  }
+}
+
+/**
+ * 同一张图反复发（推送里的封面、面板卡片…）不用反复上传：
+ * 按图片内容摘要缓存结果，顺带省掉重复的下载与解码。
+ */
+const imageCache = new Map<string, string | null>()
+const IMAGE_CACHE_MAX = 200
+
+/** 图片段 → md 图片字符串；拿不到尺寸/地址就返回 null（调用方保持原样，别把图弄丢） */
+export const markdownImageOf = async (src: string): Promise<string | null> => {
+  if (!src) return null
+  const key = crypto.createHash('md5').update(src).digest('hex')
+  const cached = imageCache.get(key)
+  if (cached) return cached
+  const buffer = await loadImageBuffer(src)
+  let result: string | null = null
+  if (buffer && buffer.length) {
+    const { width, height } = readImageSize(buffer)
+    /**
+     * **读不出尺寸就不换成 markdown**（退回普通图片段）。
+     *
+     * 用户实测：「必须要 #px，不然手机不会显示」—— 不带尺寸的 md 图片在手机端干脆是空白，
+     * 比糊更糟。所以这里宁可发一张（会被压糊但看得见的）普通图片，
+     * 也不发一张手机上什么都不显示的 markdown 图片。
+     */
+    if (width > 0 && height > 0) {
+      const url = await uploadImage(buffer)
+      if (url) result = '![#' + width + 'px #' + height + 'px](' + url + ')'
+    }
+  }
+  /**
+   * **只缓存成功的结果**：网络 / 图床抖动导致的失败要是也缓存下来，
+   * 这张图之后就一直按普通图片发（糊），得等重启才能恢复。
+   */
+  if (result) {
+    if (imageCache.size >= IMAGE_CACHE_MAX) imageCache.delete(imageCache.keys().next().value as string)
+    imageCache.set(key, result)
+  } else {
+    logger.debug('[图片md] 这张图这次没转成 markdown，按普通图片发送: ' + src.slice(0, 60))
+  }
+  return result
+}
+
+/** 清空缓存（测试用） */
+export const clearMarkdownImageCache = (): void => { imageCache.clear() }
+
+/**
+ * 把一条消息里的图片段改写成 markdown 图片（其它段原样保留、顺序不变）。
+ *
+ * 连续的图片合成**一个** markdown 元素（换行分隔）—— 和官方 QQ 的渲染习惯一致：
+ * 连续图片紧贴显示，视觉上仍是一整张卡片，而不是一张一张孤立的图。
+ *
+ * @param elements 已归一化的消息元素数组
+ * @param platform 适配器平台名（kompat 层从 bot.platform / session.platform 取）
+ * @returns 改写后的数组；不该改或改不动时**原样返回**，绝不让消息发不出去
+ */
+export const imagesToMarkdown = async (elements: any[], platform: string): Promise<any[]> => {
+  const list = Array.isArray(elements) ? elements : []
+  if (!list.length) return list
+  if (!canUseMarkdownImage(platform)) return list
+  if (!list.some(isImageElement)) return list
+  if (list.some((element) => ATTACHMENT_TYPES.has(String(element?.type ?? '')))) return list
+
+  const out: any[] = []
+  /** 攒着的连续图片（遇到非图片段就冲出去） */
+  let run: string[] = []
+  const flushRun = () => {
+    // 有图转不动（上传失败等）时 run 里会是空串占位，这里只冲有内容的
+    if (run.length) out.push(segment.markdown(run.join(String.fromCharCode(10))))
+    run = []
+  }
+
+  for (const element of list) {
+    if (!isImageElement(element)) {
+      flushRun()
+      out.push(element)
+      continue
+    }
+    const markdown = await markdownImageOf(srcOf(element))
+    if (markdown) {
+      run.push(markdown)
+    } else {
+      // 转不了就把它自己按图片段发出去，别丢
+      flushRun()
+      out.push(element)
+    }
+  }
+  flushRun()
+  return out
+}

package/src/compat/node-karin.ts

@@ -20,6 +20,7 @@ import { isSemverGreater } from '../karin/module/utils/semver'
 import { resolveAdapterInfo } from './adapter-info'
 import { logger } from './logger'
 import { COLLECTED_MESSAGE_ID, collectForward } from './forward-collect'
+import { imagesToMarkdown } from './imageMarkdown'
 import { UnconfirmedSendError, classifySendFailure, decorateSendError, describeSendFailure, isPassiveLimitFailure } from './sendError'
 import { commandQueue, eventQueue, getRuntime, karinPathBase, taskQueue, tryGetRuntime } from './runtime'
 import { segment } from './segment'
@@ -250,13 +251,15 @@ export class KkkBot {
     }
 
     // 退化路径：整条发一次；失败再逐个元素发，尽量把内容送出去
+    /** 退化发送 = 直接发消息，所以图片同样要改走 markdown（见 compat/imageMarkdown） */
+    const fallback = await imagesToMarkdown(payload.elements, platformOfBot(this.bot))
     try {
-      const ids = await this.bot.sendMessage(channelId, payload.elements as any)
+      const ids = await this.bot.sendMessage(channelId, fallback as any)
       return { messageId: ids[ids.length - 1] ?? '' }
     } catch (error) {
       logger.warn('整条发送失败，改为逐个元素发送: ' + String((error as any)?.message ?? error))
       let lastId = ''
-      for (const item of payload.elements) {
+      for (const item of fallback) {
         const ids = await this.bot.sendMessage(channelId, [item] as any)
         lastId = ids[ids.length - 1] ?? lastId
       }
@@ -351,10 +354,13 @@ export class KkkBot {
 
   /** 发送消息（karin 的 bot.sendMsg） */
   async sendMsg (contact: Contact | string, content: any, _options?: any): Promise<{ messageId: string }> {
+    const elements = normalizeContent(content)
     /** 解析结果合并转发：正在收集就攒起来（见 compat/forward-collect） */
-    if (collectForward(peerOf(contact), content)) return { messageId: COLLECTED_MESSAGE_ID }
+    if (collectForward(peerOf(contact), elements)) return { messageId: COLLECTED_MESSAGE_ID }
     const channelId = typeof contact === 'string' ? contact : contact.peer
-    const ids = await this.bot.sendMessage(channelId, normalizeContent(content) as any)
+    /** 图片统一改走 markdown（见 compat/imageMarkdown） */
+    const outgoing = await imagesToMarkdown(elements, platformOfBot(this.bot))
+    const ids = await this.bot.sendMessage(channelId, outgoing as any)
     // 同 reply/uploadFile：**没拿到消息 ID 就是没发出去**，别当成功返回
     const id = ids?.[ids.length - 1] ?? ''
     if (!id) {
@@ -480,13 +486,22 @@ export class Message {
    * 这时自动改用**主动消息**（不带引用，直接往频道里发），失败才把原错误抛出去。
    */
   async reply (content: any, _options?: any): Promise<{ messageId: string; rawData?: any }> {
-    const elements = normalizeContent(content)
+    const raw = normalizeContent(content)
 
     /**
      * 解析结果合并转发：正在收集就攒起来，等解析结束发一条转发（见 compat/forward-collect）。
      * 回一个假的消息 ID：调用方普遍只看「有没有拿到 ID」（例如 uploadFile 判断发送成没成功）。
      */
-    if (collectForward(this.contact?.peer ?? '', elements)) return { messageId: COLLECTED_MESSAGE_ID }
+    if (collectForward(this.contact?.peer ?? '', raw)) return { messageId: COLLECTED_MESSAGE_ID }
+
+    /**
+     * **图片统一改走 markdown**（上传拿公网地址 + 写死 `#宽px #高px`），见 compat/imageMarkdown。
+     *
+     * 放在这里是因为它是**所有回复的唯一出口** —— 业务代码一律 `e.reply(...)`，
+     * 不用一处处改业务代码。转换不成功会退回原来的图片段（绝不把图弄丢）。
+     * 上面的合并转发分支已经返回了，所以转发节点里仍然是普通图片段。
+     */
+    const elements = await imagesToMarkdown(raw, platformOfMessage(this))
 
     /**
      * 没拿到消息 ID 就是**没发出去**（对齐 qq-chat 的判法）。
@@ -585,6 +600,21 @@ function peerOf (contact: Contact | string): string {
   return typeof contact === 'string' ? contact : String((contact as Contact)?.peer ?? '')
 }
 
+/**
+ * 适配器平台名。
+ *
+ * 发送出口要用它判断「这个平台认不认 markdown 图片」（见 compat/imageMarkdown）：
+ * KkkBot 包装上直接转发真实 Bot 的 platform，传 KkkBot 或裸 Bot 都能取到。
+ */
+function platformOfBot (bot: any): string {
+  return String(bot?.platform ?? bot?.bot?.platform ?? '')
+}
+
+/** 同上，从消息事件取（会话上就带 platform，拿不到再问 bot） */
+function platformOfMessage (message: Message): string {
+  return String(message.session?.platform ?? platformOfBot(message.bot))
+}
+
 /**
  * 合并转发的载荷。
  *
@@ -718,18 +748,22 @@ async function sendMsg (selfId: string, contact: Contact | string, content: any,
       + '），这条消息发不出去。等它重新上线后下次推送会正常发出；如果是长期不在线，检查一下适配器连接')
   }
   const channelId = peerOf(contact)
+  const elements = normalizeContent(content)
   /** 解析结果合并转发：这条也走漏斗（karin.sendMsg 是业务代码另一条常用出口） */
-  if (collectForward(channelId, normalizeContent(content))) {
+  if (collectForward(channelId, elements)) {
     return { messageId: COLLECTED_MESSAGE_ID, rawData: [] }
   }
-  const ids = await bot.bot.sendMessage(channelId, normalizeContent(content) as any)
+  /** 图片统一改走 markdown（见 compat/imageMarkdown） */
+  const outgoing = await imagesToMarkdown(elements, platformOfBot(bot.bot))
+  const ids = await bot.bot.sendMessage(channelId, outgoing as any)
   return { messageId: ids[ids.length - 1] ?? '', rawData: ids }
 }
 
 async function sendMaster (botId: string, master: string, content: any, _options?: any) {
   const bot = resolveBot(botId)
   if (!bot) throw new Error('[kkk] 没有可用的机器人实例，无法发送消息')
-  const elements = normalizeContent(content)
+  // 图片统一改走 markdown（见 compat/imageMarkdown）：私聊和群里一样，md 图片才不会被压糊
+  const elements = await imagesToMarkdown(normalizeContent(content), platformOfBot(bot.bot))
   const target = bot.bot as any
   // Satori 的 Bot 有 sendPrivateMessage；个别适配器没有，退化成私聊频道 id
   const ids = typeof target.sendPrivateMessage === 'function'