koishi-plugin-sdkkt

读取 Stable Diffusion 生成图片中的 EXIF 信息（prompt、参数等）的 Koishi 插件。

功能特性

• 🖼️ 读取 Stable Diffusion 生成图片的元数据
• 📁 新增：支持群文件图片自动解析
• 📝 支持多种 SD 格式：
  • AUTOMATIC1111 WebUI
  • NovelAI
  • ComfyUI
• 🖼️ 支持多种图片格式：PNG、WebP、JPEG/JPG
• 💬 支持普通消息和合并转发两种发送格式
• 🔧 简单易用的配置
• 🐞 调试日志功能，方便排查问题

安装

# 使用 npm
npm install koishi-plugin-sdkkt

# 使用 yarn
yarn add koishi-plugin-sdkkt

# 使用 pnpm
pnpm add koishi-plugin-sdkkt

使用方法

基本用法

1. 在 Koishi 中启用本插件
2. 发送包含 sdexif 或 读图 指令的消息，并附带图片
3. Bot 会自动解析并返回图片中的 Stable Diffusion 信息

群文件图片自动解析

新增功能：当用户在群聊中上传图片文件时，插件可以自动检测并解析，无需发送命令！

配置方法

在插件配置中添加群白名单：

{
  "groupAutoParseWhitelist": ["123456", "789012"]
}

使用条件

• 群聊必须在白名单中
• 文件大小 ≤ 10MB
• 支持的图片格式：JPG、PNG、WebP、GIF、BMP、TIFF、HEIC、HEIF
• 非图片文件自动跳过

示例

sdexif [图片]

或者

读图 [图片]

输出示例

正向提示词:
masterpiece, best quality, 1girl, solo, beautiful

负向提示词:
lowres, bad anatomy, bad hands, text, error

参数:
Steps: 20
Sampler: Euler a
CFG Scale: 7
Seed: 123456789
Size: 512x768
Model: AnythingV5

配置项

| 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | useForward | boolean | false | 是否使用合并转发格式发送消息 | | enableDebugLog | boolean | false | 是否启用调试日志（用于排查图片接收问题） | | privateOnly | boolean | false | 是否仅在私聊中启用 | | groupAutoParseWhitelist | string[] | [] | 新增：群聊白名单，在这些群聊中自动解析群文件图片（无需命令） | | preferFileCache | boolean | false | 新增：是否优先使用文件缓存（默认使用内存Buffer，性能更好） |

useForward 说明

• false：以普通文本消息形式发送，适合单个或少量图片
• true：使用合并转发格式，适合多张图片或内容较长的情况

enableDebugLog 说明

• false：正常运行模式，只输出警告和错误信息
• true：启用详细调试日志，包括：
  • 接收到的消息详情（平台、频道、用户、内容）
  • 消息元素分析（元素类型、数量、图片元素详情）
  • 图片 URL 提取过程
  • HTTP 请求和响应详情
  • PNG 格式验证
  • 元数据提取过程

建议：当遇到图片接收问题（特别是 QQ OneBot 平台）时，启用此选项以获取详细的调试信息，帮助定位问题。

preferFileCache 说明

• false（默认）：直接使用内存 Buffer 处理图片，性能更好，适合大多数情况
• true：优先使用临时文件缓存，适合内存受限的环境或大文件处理

建议：保持默认 false 即可，除非遇到内存不足的问题。

支持的格式

图片格式

• PNG：完整支持，通过 PNG text chunks 读取元数据
• WebP：支持，通过 EXIF/XMP 数据读取元数据
• JPEG/JPG：支持，通过 EXIF/XMP 数据读取元数据

SD 工具格式

AUTOMATIC1111 WebUI

完整支持 A1111 WebUI 生成的图片，包括：

• Prompt（正向提示词）
• Negative Prompt（负向提示词）
• Steps（步数）
• Sampler（采样器）
• CFG Scale（提示词相关性）
• Seed（种子）
• Size（尺寸）
• Model（模型）

NovelAI

支持 NovelAI 生成的图片格式。

ComfyUI

支持 ComfyUI 的 workflow 格式，会尝试提取：

• Prompt
• Negative Prompt
• 采样参数

注意事项

1. 支持 PNG、WebP、JPEG/JPG 格式的图片
2. 只能读取包含元数据的图片（未经压缩或转换）
3. 如果图片被社交平台压缩，可能会丢失元数据：
   • PNG 格式：压缩后通常会丢失 text chunks
   • WebP/JPEG 格式：压缩后可能保留 EXIF 数据，但也可能被移除
4. 图片下载有 30 秒超时限制
5. 建议使用原图以获取最佳结果

常见问题

Q: 为什么读取不到信息？

A: 可能的原因：

• 图片被压缩或转换，丢失了元数据
• 图片不是由 Stable Diffusion 生成的
• 图片格式不在支持范围内（仅支持 PNG/WebP/JPEG）
• 对于 WebP/JPEG 格式，SD 工具可能没有将参数写入 EXIF 数据

Q: 支持哪些平台的图片？

A: 理论上支持所有可以通过 URL 访问的图片，但需要注意：

• QQ/微信等平台会压缩图片，建议使用原图
• 某些平台的图片可能有防盗链限制
• PNG 格式的元数据保存最完整，WebP/JPEG 可能会在传输过程中被移除 EXIF 数据

Q: QQ OneBot 平台收不到图片怎么办？

A: 请按以下步骤排查：

1. 启用调试日志：在插件配置中将 enableDebugLog 设置为 true

2. 发送测试消息：发送 sdexif 或 读图 命令并附带图片

3. 查看日志输出：检查 Koishi 控制台的日志，重点关注：

   • 收到消息 - 确认消息被接收
   • 消息元素分析 - 查看 elementTypes 数组中是否包含 img 或 image 类型
   • imageElementDetails - 查看图片元素的 attrs 属性，确认是否有 src 或 url 字段

4. 常见问题：

   • 如果 elementTypes 为空或不包含图片类型，可能是 OneBot 适配器的问题
   • 如果图片元素存在但 attrs 中没有 URL，可能需要检查 OneBot 协议版本
   • 如果有 URL 但下载失败，可能是网络或权限问题

5. 反馈问题：如果以上步骤无法解决，请将调试日志提供给开发者

开发

# 克隆项目
git clone https://github.com/yourusername/koishi-plugin-sdexif.git

# 安装依赖
npm install

# 构建
npm run build

相关项目

• stable-diffusion-inspector - 参考项目

许可证

MIT License

更新日志

1.2.0 (2025-11-11)

• 📁 新增群文件图片自动解析功能
  • 支持监听群文件上传事件
  • 自动检测 10MB 以下的图片文件
  • 支持的格式：JPG、PNG、WebP、GIF、BMP、TIFF、HEIC、HEIF
  • 通过 groupAutoParseWhitelist 配置启用
  • 无需发送命令，自动解析并发送结果
• 🔧 增强文件处理能力
  • 改进 collectImageSegments 函数，支持群文件事件
  • 增强 fetchImageBuffer 函数，支持群文件下载
  • 集成 OneBot get_group_file_url 接口调用
• 🛡️ 安全限制
  • 10MB 文件大小限制，防止内存溢出
  • 非图片文件自动跳过
  • 完善的错误处理和日志记录

1.1.1 (2025-11-10)

• 🔧 [重要修复] 修复 PNG 元数据读取问题
  • 实现手动 PNG chunks 解析（tEXt、iTXt、zTXt）
  • 修复 pngjs 库默认不解析文本块的问题
  • 支持更多 AI 图片生成工具的元数据格式
  • 提升 PNG 图片的元数据提取成功率
• 📝 详细修复说明请查看 FIX_NOTES.md

1.1.0

• 🎉 新增多格式图片支持：PNG、WebP、JPEG/JPG
• 🐞 新增调试日志功能（enableDebugLog 配置项）
• 🔧 改进图片格式检测机制
• 📝 完善 QQ OneBot 平台故障排查文档

1.0.0

• 初始版本
• 支持 A1111、NovelAI、ComfyUI 格式
• 支持合并转发配置