koishi-plugin-qq-image-markdown
v0.1.0
Published
在发送前将 QQ 图文转换为 Markdown,保留引用和原发送上下文。
Readme
koishi-plugin-qq-image-markdown
独立监听 Koishi 的 before-send,在 QQ 适配器拆分前,将同一次发送内的文字和图片转换为原生 Markdown。无需改动业务插件或适配器。
只替换可转换的正文片段,保留原来的引用元素、引用索引、被动回复参数及显式消息边界,不重新调用发送。纯文字、纯图片、已有 Markdown、合并转发,以及含 @、按钮、音视频、文件或其他未知元素的消息保持原样。不同次发送之间不合并;不会为原本没有引用的消息补造引用索引,也不修复适配器原本无法完成的引用。
图片支持 HTTP(S)、本地路径 / file:、Base64 / data:,按实际图片内容识别格式,忽略错误的文件后缀或响应 MIME。PNG、JPEG、GIF、WebP 原样上传,不改变透明度、动画帧或原图文件;BMP、未旋转的单页 TIFF 可转为 PNG。其他格式、多页 TIFF、无效图片、超过 10MB 或无法安全转换的图片,会使本次发送整体回退。展示宽高默认限制为 480×420px,保持比例、小图不放大。
图片按机器人和内容缓存,通过 QQ 素材接口上传二进制,Markdown 使用该账号专属的 qqbot-media:// 引用。上传到 COS 时只携带图片 Content-Type,不传 QQ 凭证。素材默认保留 10 分钟,避免在实际发送完成前删除;过期后回收。只管理本插件创建的素材,在 data/qq-image-markdown/materials.json 保存清理记录,重载/重启后可以继续回收。不会删除其他插件的素材。每个账号默认缓存最多 80 张,为其他插件预留官方 100 张配额的一部分;达到上限或准备失败时继续原发送。
转换完成后原消息仍由 Koishi 和 QQ 适配器发送,因此消息 ID 返回值、发送事件及原有被动回复机制沿用原流程。直接调用平台底层接口的发送不经过 before-send,不在转换范围内。
图片卡片接口
提供可选的 qqImageMarkdown 服务:ctx.qqImageMarkdown.renderImages(bot, images, { maxWidth, maxHeight })。参数为图片元素数组,返回一个已上传图片的 qq:markdown 元素,可与 Koishi 的 button-group、button 组合在同一个 message 中发送。
该接口复用自动图文转换的素材缓存、资源台账和回收机制,支持纯图片卡片;不改变原先只自动转换混合图文的行为。调用方负责导航和权限检查。
