一个简单、克制、开箱即用的 AstrBot 随机图片插件：发送真实猫猫照片，或发送指定角色“兽耳酱（Kemomimi-chan）”图片。
默认回复只有图片本体，不附加多余文案，聊天效果接近“发出命令 → 机器人直接回图”。插件不包含本地图片包，安装体积很小。
- 随机真实猫猫图：支持 TheCatAPI 与 CATAAS，自动按配置选择主源和备用源。
- 随机兽耳酱图：从 MoeHu 与 jsDelivr 两个公共源中随机首选，只返回指定角色兽耳酱。
- 图片下载后再发送：机器人平台无需自行访问第三方图片链接。
- 自动检查响应确实是受支持的图片格式，拒绝 HTML 错误页等异常内容。
- 限制单张图片大小，避免异常响应占用过多内存。
- 可配置超时、重试、并发、用户冷却和近期图片去重。
- 复用异步 HTTP 会话，插件卸载时自动释放网络资源。
- 支持 HTTP/HTTPS 代理与系统代理环境变量。
在 AstrBot 插件管理页中，使用仓库地址安装：
https://github.com/Whereis-Alice/astrbot_plugin_random_cat
安装后重载插件即可。运行依赖会由 AstrBot 根据 requirements.txt 安装。
将本仓库目录放入 AstrBot 的插件目录，确保目录名为：
astrbot_plugin_random_cat
然后重启 AstrBot 或在管理面板中重载插件。
以下示例使用 AstrBot 默认命令前缀 /。如果你的实例修改过命令前缀，请使用实例自己的前缀。
| 功能 | 主命令 | 可用别名 |
|---|---|---|
| 真实猫猫图 | /猫图 |
/cat、/rcat、/猫猫图、/来点猫猫、/随机猫猫 |
| 兽耳酱图 | /兽耳酱 |
/kemomimi、/狐狸图、/狐图、/小狐狸 |
例如：
/猫图
/狐狸图
默认情况下，机器人直接回复一张图片。若希望同时显示图源，可在插件配置中开启 show_source。
插件采用双源设计：
| 配置情况 | 主源 | 备用源 |
|---|---|---|
已填写 thecatapi_key |
TheCatAPI | CATAAS |
| 未填写 API Key | CATAAS | TheCatAPI 匿名接口 |
CATAAS 无需注册即可使用，目前公开接口可直接查询随机真实猫图。TheCatAPI 的图库和尺寸元数据更丰富；建议请求量较大的公开机器人申请免费 API Key，并填入插件配置。
若主源超时、返回错误、图片过大或内容不是有效图片，插件会自动尝试备用源。
每次执行 /兽耳酱 时，插件会等概率随机选择以下一个首选源：
| 图源 | 当前公开范围 | 访问方式 |
|---|---|---|
| MoeHu | 服务页面标注 581 张 | kemomimi JSON API |
| JackEasons/emoticon | 固定编号 001～354 | 固定提交的 jsDelivr CDN |
MoeHu 请求示例：
https://img.moehu.org/pic.php?id=kemomimi&return=json&num=1&cdn=wp
jsDelivr 请求格式：
https://cdn.jsdelivr.net/gh/JackEasons/emoticon@<固定提交>/packages/兽耳酱/<编号>.png
如果本次随机到 MoeHu 而 MoeHu 请求失败，插件会自动回退到 jsDelivr；反过来，若首选 jsDelivr 失败，也会尝试 MoeHu。两个公共源都不可用时，插件才会使用 TheresaQWQ/kemomimi 的固定提交图片清单进行最后兜底。
MoeHu 的 581 张与 jsDelivr 的 354 张可能存在重合，因此不能简单相加为 935 张不同图片。插件会记录近期图片 URL，尽量减少短时间内连续重复。
每个图源的失败原因、重试次数和自动切换目标都会写入 AstrBot 后台警告日志。固定提交让 jsDelivr 与 Raw GitHub 的图片路径可复现，在第三方随机 API 临时不可用时仍能正常回图。
插件显式使用 MoeHu 文档公开的 wp CDN 分流，避免其默认分流可能返回的 JavaScript 验证页面；即便上游行为再次变化，图片签名校验也会拒绝异常 HTML，并触发 jsDelivr 回退。
兽耳酱角色与原画作者为 ながユー（Pixiv 2509595）。远程图片版权归原作者所有。
所有选项都可以在 AstrBot 插件配置页中修改。
| 配置项 | 默认值 | 说明 |
|---|---|---|
show_source |
false |
是否在图片后附上图源信息。 |
cooldown_seconds |
3 |
同一用户两次请求之间的冷却秒数；设为 0 关闭。 |
request_timeout_seconds |
20 |
单次网络请求总超时，代码会限制在 5～60 秒。 |
retry_count |
2 |
每个图片源的尝试次数，代码会限制在 1～4。 |
max_image_size_mb |
12 |
单张图片最大下载体积，代码会限制在 1～25 MB。 |
recent_cache_size |
20 |
内存中记录的近期图片 URL 数量，用于减少连续重复；设为 0 关闭。 |
max_concurrency |
4 |
同时处理的图片请求数，代码会限制在 1～8。 |
thecatapi_key |
空 | 可选。填写后优先使用 TheCatAPI。 |
use_moehu_kemomimi_source |
true |
是否让 MoeHu 与 jsDelivr 等概率成为兽耳酱首选源。 |
use_github_kemomimi_fallback |
true |
两个公共源均异常时，是否启用固定 Raw GitHub 备用清单。 |
proxy_url |
空 | 可选 HTTP/HTTPS 代理，如 http://127.0.0.1:7890。 |
trust_env_proxy |
true |
是否读取 HTTP_PROXY、HTTPS_PROXY、NO_PROXY。 |
当前 proxy_url 不直接支持 socks5://。如需 SOCKS5，可在本机使用能够提供 HTTP 代理入口的代理客户端，再把该 HTTP 地址填入配置。
本项目参考了上游 nonebot-plugin-random-cat 的随机图片交互思路，但没有直接照搬 NoneBot/OneBot 实现。
- 上游猫图接口
aws.random.cat目前已经无法解析，改为 TheCatAPI + CATAAS。 - 删除了本项目不需要的狗图、定时群推送和群号白名单逻辑，功能只保留真实猫猫与兽耳酱。
- 使用 AstrBot 原生消息组件，不拼接 CQ 码，不依赖特定 QQ 适配器。
- 不再用正则处理 Base64，也不为每一步重复创建 HTTP 客户端。
- 增加有限超时、受控重试、主备切换、图片签名校验、体积上限、并发限制、冷却和近期去重。
- 下载图片字节后交给 AstrBot 发送，降低平台侧远程 URL 拉取失败或防盗链导致的发送问题。
- 为
nekos.best等普通狐娘源做过调研，但最终按插件定位排除，确保/兽耳酱返回的是指定角色。 - 兽耳酱使用 MoeHu 581 张随机 API 与 jsDelivr 354 张固定图集随机首选，并保留 Raw GitHub 最后兜底。
- 增加图源失败、重试与自动回退的 AstrBot 后台警告日志。
先确认插件已启用，再确认当前 AstrBot 实例使用的命令前缀。默认示例是 /猫图，不是所有实例都允许省略 /。
部分平台无法访问外部 URL，或者目标站点存在重定向、防盗链和请求头要求。插件先在 AstrBot 侧下载并验证图片，再通过 Image.fromBytes 发送，跨平台表现更稳定。
公开图片接口需要被友善使用。默认每个用户有 3 秒冷却，可在配置中调整，但不建议在公开群关闭冷却后高频刷图。
不是。零配置时会优先使用无需密钥的 CATAAS。填写 Key 后可优先使用图库更丰富的 TheCatAPI，也更适合请求量较大的机器人。
不会。图片只在内存中短暂存在，发送完成后由 Python 回收；插件只在内存里保存少量近期 URL 用于去重。
查看 AstrBot 后台日志。图源异常时会看到类似记录：
[astrbot_plugin_random_cat] kemomimi 图源 MoeHu 兽耳酱 API 第 1/2 次失败：ImageServiceError: HTTP 503
[astrbot_plugin_random_cat] kemomimi 图源 MoeHu 兽耳酱 API 不可用，切换到 jsDelivr 兽耳酱图集。
正常请求不会写入警告日志，避免后台被每次随机结果刷屏。
- 调用远程图片源时，对方服务器能够看到 AstrBot 所在服务器的出口 IP 和本插件的
User-Agent。 - 插件不会上传聊天内容、用户昵称、QQ 号或群号。
- API Key 由 AstrBot 配置系统保存；插件不会把 Key 写入额外日志或缓存，也不会发送给 TheCatAPI 以外的服务。
- 若启用代理，请自行确认代理服务的隐私与安全性。
- NoneBot2-AeCraft/nonebot-plugin-random-cat：本插件交互思路的主要上游参考，MIT License。
- AstrBotDevs/AstrBot：插件运行框架。
- ながユー：兽耳酱角色与原画作者。
- MoeHu 随机图片 API：
kemomimi兽耳酱随机图片源。 - JackEasons/emoticon：兽耳酱固定图片清单来源。
- TheresaQWQ/kemomimi：兽耳酱备用图片清单来源。
- jsDelivr：固定 GitHub 提交的 CDN 访问通道。
- TheCatAPI 与 CATAAS：真实猫猫图片源。
更完整的第三方说明见 THIRD_PARTY_NOTICES.md。
插件代码使用 MIT License。
MIT License 只覆盖本仓库中的插件代码和文档，不代表远程图片被重新授权。猫图与兽耳酱图片分别遵循其图片源、上传者和原作者的版权条款；请勿将本插件用于侵权用途。