nonebot-plugin-aigf-master 1.6.2__tar.gz → 2.0.0b1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/PKG-INFO +131 -31
  2. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/README.md +126 -28
  3. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/__init__.py +799 -0
  4. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/api_hooks.py +226 -0
  5. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/config.py +9 -2
  6. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/context_bus.py +30 -0
  7. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/meme_store.py +13 -13
  8. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/models.py +1 -1
  9. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/peer_client.py +5 -2
  10. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/plugin_invoker.py +332 -0
  11. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/processor.py +32 -26
  12. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/session.py +273 -0
  13. nonebot_plugin_aigf_master-2.0.0b1/nonebot_plugin_aigf_master/unimsg.py +454 -0
  14. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master.egg-info/PKG-INFO +131 -31
  15. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master.egg-info/SOURCES.txt +2 -1
  16. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master.egg-info/requires.txt +3 -1
  17. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/pyproject.toml +5 -3
  18. nonebot_plugin_aigf_master-1.6.2/nonebot_plugin_aigf_master/__init__.py +0 -882
  19. nonebot_plugin_aigf_master-1.6.2/nonebot_plugin_aigf_master/api_hooks.py +0 -260
  20. nonebot_plugin_aigf_master-1.6.2/nonebot_plugin_aigf_master/context_bus.py +0 -30
  21. nonebot_plugin_aigf_master-1.6.2/nonebot_plugin_aigf_master/message_builder.py +0 -92
  22. nonebot_plugin_aigf_master-1.6.2/nonebot_plugin_aigf_master/plugin_invoker.py +0 -111
  23. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/LICENSE +0 -0
  24. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/anime_recognizer.py +0 -0
  25. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/animetrace_client.py +0 -0
  26. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/cache_cleanup.py +0 -0
  27. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/command_learner.py +0 -0
  28. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/image_gen_client.py +0 -0
  29. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/image_handler.py +0 -0
  30. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/llm_client.py +0 -0
  31. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/memory_store.py +0 -0
  32. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/plugin_discovery.py +0 -0
  33. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/preset_store.py +0 -0
  34. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/prompt_builder.py +0 -0
  35. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/response_parser.py +0 -0
  36. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/search_client.py +0 -0
  37. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master/vlm_client.py +0 -0
  38. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master.egg-info/dependency_links.txt +0 -0
  39. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/nonebot_plugin_aigf_master.egg-info/top_level.txt +0 -0
  40. {nonebot_plugin_aigf_master-1.6.2 → nonebot_plugin_aigf_master-2.0.0b1}/setup.cfg +0 -0
@@ -1,14 +1,16 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: nonebot-plugin-aigf-master
3
- Version: 1.6.2
4
- Summary: 群聊特化LLM聊天机器人(增强版),具有记忆、表情包、跨插件调用和跨bot通信能力
3
+ Version: 2.0.0b1
4
+ Summary: 群聊特化LLM聊天机器人(增强版),具有记忆、表情包、跨插件调用、跨bot通信与跨适配器支持
5
5
  License-Expression: MIT
6
6
  Requires-Python: <4.0,>=3.10
7
7
  Description-Content-Type: text/markdown
8
8
  License-File: LICENSE
9
- Requires-Dist: nonebot2>=2.3.0
9
+ Requires-Dist: nonebot2>=2.5.0
10
10
  Requires-Dist: nonebot-adapter-onebot>=2.2.0
11
11
  Requires-Dist: nonebot-plugin-localstore>=0.5.0
12
+ Requires-Dist: nonebot-plugin-alconna>=0.62
13
+ Requires-Dist: nonebot-plugin-uninfo>=0.11
12
14
  Requires-Dist: openai>=1.0.0
13
15
  Requires-Dist: httpx>=0.24.0
14
16
  Requires-Dist: anyio>=4.0.0
@@ -24,21 +26,30 @@ Dynamic: license-file
24
26
 
25
27
  ## ✨ AI-group-friend-master ✨
26
28
 
27
- 群聊特化 LLM 聊天机器人,具备表情包管理、记忆存储、联网搜索、跨插件感知、插件调用、LLM 命令学习等能力。
29
+ 群聊特化 LLM 聊天机器人,具备表情包管理、记忆存储、联网搜索、跨插件感知、插件调用、LLM 命令学习等能力,并以适配器无关的方式收发消息(OneBot / Satori / Telegram / Discord 等 alconna 支持的适配器均可)。
28
30
 
29
31
  <p>
30
32
  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="python">
31
- <img src="https://img.shields.io/badge/nonebot-2.3+-red?style=flat-square" alt="nonebot">
33
+ <img src="https://img.shields.io/badge/nonebot-2.5+-red?style=flat-square" alt="nonebot">
32
34
  </p>
33
35
  </div>
34
36
 
37
+ > [!WARNING]
38
+ > **这是 beta 分支(2.0.0 开发中):跨适配器改造版**,与 1.6.x(main)不兼容,请勿直接覆盖生产环境的稳定版:
39
+ > - 会话改用 `适配器:会话id` 为键(旧版 `memory/{群号}` 目录会在启动时**自动迁移**为 `onebot11_群号`),新增私聊会话支持
40
+ > - 新增依赖 `nonebot-plugin-alconna`(统一消息)与 `nonebot-plugin-uninfo`(跨适配器会话/成员信息)
41
+ > - 插件调用改为「复制真实消息事件」,合成事件里携带**真实发送者的昵称/群名片/角色**(见「无法代为执行的命令」)
42
+ >
43
+ > 稳定版请留在 main 分支(1.6.x),beta 的功能验证完成后再合并发版。
44
+
35
45
  ## 📖 介绍
36
46
 
37
- 一个基于 NoneBot2 的群聊 AI 助手插件,能够自主收集和发送表情包、联网搜索知识、对群内信息进行记忆,还能够感知同实例内其它插件的输出、通过 LLM 调用其它插件、自主学习群内命令用法,并能通过子插件与其它 bot 通信获取消息和远程调用命令。
47
+ 一个基于 NoneBot2 的群聊 AI 助手插件,能够自主收集和发送表情包、联网搜索知识、对群内信息进行记忆,还能够感知同实例内其它插件的输出、通过 LLM 调用其它插件、自主学习群内命令用法,并能通过子插件与其它 bot 通信获取消息和远程调用命令。消息收发走 [nonebot-plugin-alconna](https://github.com/nonebot/plugin-alconna) 的通用消息层、会话与成员信息走 [nonebot-plugin-uninfo](https://github.com/nonebot/plugin-uninfo),因此同一份代码可以在多个适配器上工作(详细边界见「多适配器支持」)。
38
48
  > 本项目有AI高度参与,若有做得不够好及需要改进的地方,欢迎在issue提出意见。
39
49
 
40
50
  ### 核心能力
41
51
 
52
+ - 🧩 **多适配器支持**:消息收发与会话身份走通用层,OneBot / Satori / Telegram / Discord 等适配器共用同一套聊天、记忆、表情包与命令逻辑(跨插件感知、插件调用等能力仍以 OneBot 为主,见下文边界)
42
53
  - 🔌 **跨插件感知**:LLM 能看到同实例内其它插件的输出(如 rollpig 的小猪卡片、搜索结果等)
43
54
  - 🤖 **插件调用**:LLM 可通过 function calling 调用其它插件(如 `/roll`、`/天气`),支持传递参数与 @ 群友(如 `决斗 @张三 10`)
44
55
  - 🧠 **LLM 命令学习**:通过观察群聊自动学习命令用法,支持学习、编辑、删除
@@ -66,20 +77,20 @@ Dynamic: license-file
66
77
  > 要使用本插件, 你至少需要
67
78
  >
68
79
  > - 一个有效的 openai 规范接口 api key,你需要在 `.env` 文件中配置对应的 api 地址
80
+ >
81
+ > 从 2.0 起插件还依赖 `nonebot-plugin-alconna` 与 `nonebot-plugin-uninfo`(跨适配器收发与会话/成员信息),用下面的方式安装时会自动装上。
69
82
 
70
- <details open>
71
- <summary>使用 nb-cli 安装</summary>
72
- 在 nonebot2 项目的根目录下打开命令行, 输入以下指令安装
83
+ ### 安装 beta 版本(2.0.0b1)
73
84
 
74
- nb plugin install nonebot-plugin-aigf-master --upgrade
85
+ `2.0.0b1` 是**预发布(pre-release)版本**,因此:
75
86
 
76
- </details>
87
+ - `pip install nonebot-plugin-aigf-master` 装的仍是稳定版 **1.6.x**
88
+ - `nb plugin install nonebot-plugin-aigf-master` 同样只装稳定版,而且 nb-cli **不支持指定版本**,所以 beta 只能用 pip 装
77
89
 
78
- <details>
79
- <summary>使用包管理器安装</summary>
90
+ 要装 beta,**必须显式写出版本号**:
80
91
 
81
92
  ```bash
82
- pip install nonebot-plugin-aigf-master
93
+ pip install nonebot-plugin-aigf-master==2.0.0b1
83
94
  ```
84
95
 
85
96
  在 `pyproject.toml` 中添加:
@@ -89,7 +100,8 @@ pip install nonebot-plugin-aigf-master
89
100
  plugins = ["nonebot-plugin-aigf-master"]
90
101
  ```
91
102
 
92
- </details>
103
+ > 需要装 beta 分支上尚未发版的改动时,可以直接从分支安装:
104
+ > `pip install git+https://github.com/Funny1Potato/nonebot-plugin-aigf-master.git@beta`
93
105
 
94
106
 
95
107
  ## 配置
@@ -103,7 +115,8 @@ plugins = ["nonebot-plugin-aigf-master"]
103
115
  AIGFM_LLM_API_KEY="sk-xxxxxxxxxxxx" # LLM API Key
104
116
  AIGFM_LLM_BASE_URL="https://api.deepseek.com" # LLM API 地址
105
117
  AIGFM_LLM_MODEL="deepseek-v4-flash" # LLM 模型名称
106
- AIGFM_ENABLED_GROUPS=[123456, 789012] # 启用的群号列表
118
+ AIGFM_ENABLED_GROUPS=[123456, 789012] # 启用的群/频道会话(可写 `适配器:会话id`,只写数字按 OneBot V11 识别)
119
+ AIGFM_ENABLED_PRIVATE=[] # 启用的私聊会话(同上写法;留空则私聊不响应)
107
120
 
108
121
  # --- 图片理解(VLM) ---
109
122
  AIGFM_IMAGE_MODE="vlm" # 图片模式: vlm / llm(默认 vlm)
@@ -187,7 +200,6 @@ AIGFM_ANIME_RECOGNIZE_MAX_CHARACTERS=3 # 展示的角色标签数量上限(
187
200
  AIGFM_ANIME_NSFW_THRESHOLD=0.5 # explicit 概率超过该值标注 [NSFW](默认 0.5;仅本地后端提供画风分级)
188
201
  AIGFM_ANIMETRACE_URL="https://api.animetrace.com" # AnimeTrace API 地址(公共 API、无需鉴权;识别会把图片上传到该服务)
189
202
  AIGFM_ANIMETRACE_TIMEOUT=20.0 # AnimeTrace 请求超时/秒(默认 20.0)
190
- AIGFM_ANIME_RECOGNIZE_ENABLED=false # 【已被 AIGFM_ANIME_BACKEND 取代,仅兼容保留】为 true 且 backend=off 时按 anime-recognize 处理
191
203
 
192
204
  # --- 缓存清理 ---
193
205
  AIGFM_IMAGE_CACHE_MAX_FILES=500 # 描述/角色识别缓存(image_cache 下的 JSON)最大数量,超出按 mtime 最旧删除(默认 500,0=不清理)
@@ -225,6 +237,85 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
225
237
  - 每次处理时,LLM 收到最近 **20 条**(可配置)历史聊天记录 + 四层记忆 + 预设 + 表情包列表 + 其它插件响应;本批消息只出现在「新消息」段,同一条插件响应也只注入一次(不会在历史与新消息里重复)
226
238
  - LLM 一次调用同时完成:回复决策 + 记忆管理 + 表情包选择 + 命令学习
227
239
 
240
+ ## 🧩 多适配器支持
241
+
242
+ 插件的消息**收发**(文本、@、图片、语音、视频、群文件、链接分享、回复、合并转发等)走 [nonebot-plugin-alconna](https://github.com/nonebot/plugin-alconna) 的通用消息层,**会话与成员信息**(昵称、群名片、角色、群名、@ 目标解析)走 [nonebot-plugin-uninfo](https://github.com/nonebot/plugin-uninfo)。因此只要适配器被这两个库支持,聊天 / 记忆 / 表情包 / 生图 / 命令学习等功能就能直接工作,不需要为每个适配器改代码。
243
+
244
+ ### 会话与启用清单
245
+
246
+ - 会话以 **`适配器:会话id`** 为键,例如 `onebot11:617770183`(群)、`console:console-chat`(频道)、`onebot11:20001`(私聊)
247
+ - `AIGFM_ENABLED_GROUPS` 管群/频道会话、`AIGFM_ENABLED_PRIVATE` 管私聊会话;条目可写带前缀的完整键,也可以只写 id(**按 OneBot V11 识别**,旧配置无需改动)
248
+ - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_617770183`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
249
+ - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
250
+
251
+ ### 功能 × 适配器支持表(2026-09-25 实测)
252
+
253
+ 测试方式:本机用 `nb`/pip 装上各适配器包后,为每个适配器**构造真实事件**(各适配器的消息/事件模型),跑本插件同一套功能路径——会话解析(uninfo)→ 消息渲染(uniseg)→ 回复发送(alconna exporter)→ 跨插件捕获(`on_calling_api`)→ 插件调用(复制真实事件 + 目标响应器实际收到命令)。bot 为记录型 mock(拦下所有 API 调用并断言调用的接口名),**未连真实平台**,因此"需要真实 API 才有数据"的项目另标 ⚠。
254
+
255
+ | 适配器 | 会话解析 | 收发/渲染 | 回复发送 | 私聊 | @ 按昵称 | 跨插件捕获 | 插件调用 | 群通知¹ | 跨 bot² |
256
+ |---|---|---|---|---|---|---|---|---|---|
257
+ | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
258
+ | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
259
+ | Console | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
260
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ⚠ | ❌ | ✅ |
261
+ | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
262
+ | Discord | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
263
+ | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
264
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
265
+ | Milky | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
266
+ | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
267
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ⚠ | ❌ | ✅ |
268
+ | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
269
+ | Kritor | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ✅ | ❌ | ✅ |
270
+ | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
271
+ | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
272
+ | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
273
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
274
+ | YunHu⁴ | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ✅ | ❌ | ✅ |
275
+ | bilibili Live⁴ | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠ | ✅ | ✅ | ❌ | ✅ |
276
+
277
+ **读表说明**
278
+
279
+ - **✅ 已实测通过**:会话键、渲染文本、发送接口、捕获入缓冲、目标插件确实收到了命令,逐项断言过。**本表 17 行在 Python 3.10 实测(167 项检查)**;**YunHu / bilibili Live 两行在 Python 3.14 实测**(3.10 装不上,见下),19 个适配器合计 **187 项检查、只有 2 项未通过**(Satori / Kaiheila 的插件调用)
280
+ - **整套依赖栈在 Python 3.14 上跑通**:`nonebot2 2.5.0` + `nonebot-plugin-alconna 0.62.1` + `nonebot-plugin-uninfo 0.11.2` 在 **Python 3.14.3** 上通过了全部回归——主插件 150 项、peer 子插件 67 项、适配器矩阵 187 项(仅上述 2 项未通过)
281
+ - **⚠ 需真机/特例**:
282
+ - **@ 按昵称**:只有 OneBot V11 实测能按群昵称反查出用户 id(走 `get_group_member_list`);其它适配器需要 uninfo 的成员列表查询实现(多数适配器没有),因此**让 LLM 直接用用户 id 更稳**;渲染 @ 时昵称拿不到会回落成 id
283
+ - **插件调用(Satori / Kaiheila)**:这两类适配器的事件结构特殊(Satori 的 `message` 是 `{id, content}` 结构体、Kaiheila 的消息在嵌套的 `event` 里),离线构造"uninfo 与 alconna 都认可"的事件未能复现,因此**未验证通过**;其余 14 个适配器已实测目标响应器收到命令。真机使用请以实际表现为准
284
+ - **❌ 不支持**:群系统通知¹(戳一戳/禁言/进出群/撤回是 OneBot 专属事件类型)
285
+ - **⚠ Python 版本要求**(上表 YunHu / bilibili Live):这两个适配器包**需要 Python ≥ 3.12**——`bilibili Live` 用了 `typing.TypedDict`(pydantic 在 Python < 3.12 直接拒绝),`YunHu` 还额外用到 `typing.NotRequired`(Python 3.11+),所以在 Python 3.10 的 bot 里**导入即失败**。上表这两行的 ✅ 是**在本机 Python 3.14.3 上实测的结果**:两个包都能导入,`alconna` 的 builder/exporter 与 `uninfo` 的 fetcher 三者齐备,会话解析/渲染/发送/捕获/插件调用全部通过(`bilibili Live` 的场景路径=房间号;`YunHu` 的群资料需要真实 API 才有昵称)。**要用这两个平台就把 bot 跑在 Python 3.12+/3.14 上**(本工作目录另建了参考环境 `.venv314`:Python 3.14.3 + `nonebot2 2.5.0` + `alconna 0.62.1` + `uninfo 0.11.2` + 全部 19 个适配器包,回归与矩阵都在里面跑过)
286
+ - **Kook 注意**:社区包 `nonebot-adapter-kook` 的模块名是 `nonebot.adapters.kook`、`get_name()` 报 `Kook`,而 alconna/uninfo 期望的是 `nonebot.adapters.kaiheila`(`Kaiheila`)——**请安装 `nonebot-adapter-kaiheila`**,否则该平台等同于"不被支持"
287
+ - **昵称/群名片**:取决于适配器的 uninfo fetcher 能取到什么(很多要真实 API 调用,离线 mock 拿不到),拿不到时回落成用户 id,功能不受影响
288
+ - 适配器完全不被 alconna/uninfo 支持时,该会话的消息会被静默跳过(只留 debug 日志),不会报错、也不会影响其它适配器
289
+
290
+ <details>
291
+ <summary>实测到的各适配器发送接口(供排查用)</summary>
292
+
293
+ | 适配器 | 回复发送最终调用的接口 |
294
+ |---|---|
295
+ | OneBot V11 / V12 | `send_msg` / `send_message` |
296
+ | Console | `send_message`(私聊 `send_private_message`) |
297
+ | Satori | `send_message`(私聊 `send_private_message`) |
298
+ | Telegram | `send_to` |
299
+ | Discord | `send_to` |
300
+ | QQ | `send_to_group` / `send_to_channel` / `send_to_c2c` |
301
+ | Feishu | `send_msg` |
302
+ | Milky | `send_group_message` / `send_private_message` |
303
+ | Mirai | `send_group_message` / `send_friend_message` |
304
+ | Kaiheila | `send_msg`(按 channel/private 区分) |
305
+ | DoDo | `send_to_channel` / `send_to_personal` |
306
+ | Kritor | `send_message` / `send_channel_message` |
307
+ | Mail | `send_to` |
308
+ | Minecraft | `send_msg` |
309
+ | WXMP | `send_custom_message` |
310
+ | EFChat | `send_chat_message` |
311
+
312
+ </details>
313
+
314
+ > ¹ 群系统通知 = 戳一戳/禁言/进出群/消息撤回。
315
+ > ² 跨 bot = 子插件 [nonebot-plugin-aigfm-peer](https://github.com/Funny1Potato/nonebot-plugin-aigfm-peer) 的推送与远程调用。上表按 **peer 0.4.0+** 的协议标 ✅:推送与调用都会带 `session`(`适配器:会话id`)、主插件按会话键落位,因此各适配器都可用。**用旧 peer(0.3.x)时只有 OneBot V11 的会话能对上**(旧协议只带 `group_id`,按 `onebot11:{group_id}` 映射)。peer 侧捕获/推送与主插件侧落位各自实测过,端到端的「复制事件执行命令」在 OneBot V11 与 Console 上跑通。
316
+ > ³ Kritor / Kaiheila 的私聊事件本次未构造,故未测;它们的私聊类型在 alconna/uninfo 里是有实现的。
317
+ > ⁴ 这两个适配器**需要 Python ≥ 3.12**(3.10 环境里导入即失败),表里这两行是在 **Python 3.14.3** 下实测的结果,见下方说明。
318
+
228
319
  ## 🔌 跨插件感知
229
320
 
230
321
  ### 工作原理
@@ -365,23 +456,30 @@ LLM 只能调用 prompt 里「可用的群功能」/「其它 bot 的命令」
365
456
 
366
457
  ### 无法代为执行的命令
367
458
 
368
- `invoke_plugin` / `invoke_peer_plugin` 是构造一个**合成群事件**(`GroupMessageEvent`)把命令文本投递给目标插件,而不是让真人发消息。合成事件与真实消息存在字段差异,下列命令**调不动**(表现为投递后聊天记录里始终不出现该插件的响应):
459
+ `invoke_plugin` / `invoke_peer_plugin` 并不是让真人发消息,而是**复制该会话里最近一条真实消息事件**、把消息体换成命令文本后投递(2.0 起改为这种做法,此前是手工拼一个 `GroupMessageEvent`)。因此事件的适配器字段、发送者信息都来自那条真实消息,比过去准确得多,但仍与"真的有人发了这条命令"有差别,下列命令**调不动**(表现为投递后聊天记录里始终不出现该插件的响应):
369
460
 
370
461
  | 命令类型 | 无法执行的原因 |
371
462
  |---|---|
372
- | 需要 @机器人 或呼叫昵称才触发 | 合成事件的 `to_me` 恒为 `False`(该字段由适配器在真实消息上计算,投递时绕过了这一步) |
373
- | 需要管理员 / 群主 / 超级用户权限 | `sender.role` 固定为 `"member"`,且传入的 `user_id` 一般不在 `SUPERUSERS` 内,权限检查直接拒绝 |
374
- | 私聊命令 | 合成事件固定 `message_type="group"`,不会命中只监听私聊的 Matcher |
375
- | 必须先回复/引用某条消息才能执行 | 合成事件的 `reply` 恒为 `None`,且真实消息里的 `reply` 段会被适配器展开,这里没有 |
376
- | 依赖群名片 / 头衔 / 等级 / 地区判断身份 | `sender` 只填 `user_id`、`nickname`(当前群预设名,默认「小助手」;peer 侧由 Bot A 传入同一名字)、`role`,其余字段为空 |
377
- | 依赖真实 `message_id` 的后续操作 | `message_id` 是占位值 `0`,插件拿它去 `get_msg` / 撤回 / 引用回复会失败 |
463
+ | 需要 @机器人 或呼叫昵称才触发 | 合成消息里没有 @机器人,`to_me` 沿用被复制那条消息的值(通常为 `False`) |
464
+ | 私聊命令 / 与事件类型强相关 | 复制的是群/频道事件(`message_type` 保持原样),不会命中只监听私聊或其它事件类型的 Matcher |
465
+ | 必须先回复/引用某条消息才能执行 | 合成消息不含回复段,事件里的 `reply` 也被清空 |
466
+ | 依赖群名片 / 头衔 / 等级 / 地区判断身份 | 发送者昵称、群名片、角色已按真实身份填好(`refresh` 不到的字段仍为空:头衔、等级、地区等) |
467
+ | 需要特殊 `message_id` 语义的操作 | `message_id` 是**被复制那条消息的真实 id**(不再是占位 `0`):引用回复可用,但插件若对"这条消息"做撤回/编辑等操作,作用的其实是那条真实消息 |
468
+
469
+ 关于**权限**:合成事件的发送者是**提出请求的那位群友**(`user_id`、昵称、群名片、角色都按真实身份填),所以:
470
+
471
+ - 需要管理员/群主权限的命令,**请托者本身有相应权限时可以被执行**(1.6.x 及更早版本里 `role` 固定为 `member`,一律拒绝);请托者没有权限时仍会被目标插件拒绝
472
+ - `SUPERUSERS` 相关的命令同理:以请托者的身份通过检查
473
+ - 本插件自己的管理命令(`status`/`reset`/`set_role`/…)**无论谁请托都一律拒绝**,不会代为执行(避免真实用户恰好是 SUPERUSER 时被 LLM 触发)
378
474
 
379
475
  两点补充:
380
476
 
381
477
  - `on_keyword` / `on_regex` / `on_message` 型插件(不用 `on_command` 注册)**不会出现在静态命令列表**里,无法被自动发现;但它们的 rule 只匹配文本时,合成事件仍会命中,所以可以靠 LLM 命令学习掌握后调用。
382
478
  - 命令学习会**主动跳过**上表中无法代为执行的命令(不会为它们生成用法记录),避免 LLM 反复误调用。
383
479
 
384
- > 需要多步确认的命令(执行中等待用户再回复)不在上表内:会话按 `group_{group_id}_{user_id}` 归组,只要后续真实消息来自同一个 `user_id`,等待流程仍能接上。
480
+ > 需要多步确认的命令(执行中等待用户再回复)不在上表内:会话按适配器的会话 id 归组(OneBot V11 为 `group_{group_id}_{user_id}`),只要后续真实消息来自同一个 `user_id`,等待流程仍能接上。
481
+
482
+ > 若目标插件是用 alconna 写的,插件会在投递前把 alconna 按 `message_id` 缓存的那条消息**替换成命令内容**——否则它会把命令读成"原来那条用户消息",永远匹配不上。
385
483
 
386
484
  ## 🌐 跨 bot 通信
387
485
 
@@ -581,7 +679,7 @@ memes/
581
679
  | 后端 | 工作方式 | 擅长 | 代价 |
582
680
  |---|---|---|---|
583
681
  | `anime-recognize` | 本地 WD14 推理服务([aigfm-anime-recognize](https://github.com/Funny1Potato/aigfm-anime-recognize)),**需自行部署** | 动漫 / 手游角色,输出英文 booru 标签(如 `hu_tao_(genshin_impact)`)+ 数值置信度 + 画风分级 | 本地推理、免费无限量;**对 gal / 视觉小说角色识别率低** |
584
- | `animetrace` | [AnimeTrace](https://ai.animedb.cn/) 公共 API,**无需部署、无需鉴权** | gal / 视觉小说角色,并给出作品名(如「胡桃(原神)」) | 图片会上传到该第三方公共服务;有使用配额;不返回数值置信度、无画风分级 |
682
+ | `animetrace` | [AnimeTrace](https://ai.animedb.cn/) 公共 API,**无需部署、无需鉴权** | gal / 视觉小说角色,并给出作品名(如「胡桃(原神)」) | 图片会上传到该第三方公共服务;有使用配额;不返回数值置信度、无画风分级;对gal以外游戏角色的识别率一般 |
585
683
 
586
684
  `both` 模式先问本地服务,本地置信度不足(低于 `AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE`)再问 AnimeTrace,两边都没有可信结果才渲染 `[角色识别: 未能识别]`——平时不消耗公共 API 配额。
587
685
 
@@ -592,8 +690,10 @@ memes/
592
690
  ```bash
593
691
  git clone https://github.com/Funny1Potato/aigfm-anime-recognize.git
594
692
  cd aigfm-anime-recognize
693
+ # 安装
595
694
  # Windows: install.bat ;Linux/macOS: chmod +x install.sh && ./install.sh
596
- # 一键完成:建虚拟环境 → 装钉版本依赖 → 下载模型(约 446MB)→ 启动服务(0.0.0.0:8000)
695
+ # 启动
696
+ # Windows: start.bat ; Linux / macOS: chmod +x start.sh && ./start.sh
597
697
  ```
598
698
 
599
699
  **插件配置**:
@@ -603,14 +703,14 @@ cd aigfm-anime-recognize
603
703
  AIGFM_ANIME_BACKEND=both
604
704
 
605
705
  # 本地后端地址(backend 含 anime-recognize 时必填;服务端未启用鉴权时 token 留空)
606
- AIGFM_ANIME_RECOGNIZE_URL=http://127.0.0.1:8000
706
+ AIGFM_ANIME_RECOGNIZE_URL="http://127.0.0.1:8000"
607
707
  # AIGFM_ANIME_RECOGNIZE_TOKEN=可选
608
708
 
609
709
  # 可选调参(默认值如下)
610
710
  # AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE=0.85 # 展示角色标签的最低置信度;both 模式下也用它判断本地是否有结果
611
711
  # AIGFM_ANIME_RECOGNIZE_MAX_CHARACTERS=3 # 展示的角色标签数量上限
612
712
  # AIGFM_ANIME_NSFW_THRESHOLD=0.5 # explicit 概率超过该值标注 [NSFW](只标注不拦截;仅本地后端提供分级)
613
- # AIGFM_ANIMETRACE_URL=https://api.animetrace.com
713
+ # AIGFM_ANIMETRACE_URL="https://api.animetrace.com"
614
714
  # AIGFM_ANIMETRACE_TIMEOUT=20 # AnimeTrace 请求超时(秒)
615
715
  ```
616
716
 
@@ -632,8 +732,8 @@ AIGFM_ANIME_RECOGNIZE_URL=http://127.0.0.1:8000
632
732
  - 改 `AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE` 只影响此后新识别的图片;已缓存图片要重新判定需删除其 `{md5}_anime.json`
633
733
 
634
734
  **已知局限**:
635
- - **本地后端**:训练数据截止 2024 年前后,新游/新角色可能认不出,**gal / 视觉小说角色识别率尤其低(建议改用 `animetrace` 或 `both`)**;多人合影会漏识别;皮肤/异格不区分;3D 战斗小人/游戏内截图识别率偏低;输出为英文标签(中文映射需自行扩展)
636
- - **AnimeTrace**:不返回数值置信度,只有服务自己的低置信判定——被判低置信时一律按「未能识别」处理,日志 `[角色识别] AnimeTrace 无可信结果,低置信候选: …` 会给出它认为最可能的候选,便于排查;其检测框可能包含误检,多人提示仅供参考;`[NSFW]` 标记只由本地后端提供
735
+ - **本地后端**:训练数据截止 2024 年前后,新游/新角色可能认不出,**gal / 视觉小说角色识别率尤其低(建议改用 `animetrace` 或 `both`)**;多人合影可能会漏识别;3D 战斗小人/游戏内截图识别率不高;输出为英文标签(中文映射需自行扩展)
736
+ - **AnimeTrace**:对gal以外的游戏角色识别率一般;不返回数值置信度,只有服务自己的低置信判定——被判低置信时一律按「未能识别」处理,日志 `[角色识别] AnimeTrace 无可信结果,低置信候选: …` 会给出它认为最可能的候选,便于排查;其检测框可能包含误检,多人提示仅供参考;`[NSFW]` 标记只由本地后端提供
637
737
  - 识别结果(角色名)会进入 LLM 上下文,也就是群里能看到;在意隐私请只用 `anime-recognize`(纯本地)或关闭本功能
638
738
 
639
739
  > 仅 `AIGFM_IMAGE_MODE=vlm` 模式生效;`llm` 模式图片不经过 VLM,无二次元判断。
@@ -4,21 +4,30 @@
4
4
 
5
5
  ## ✨ AI-group-friend-master ✨
6
6
 
7
- 群聊特化 LLM 聊天机器人,具备表情包管理、记忆存储、联网搜索、跨插件感知、插件调用、LLM 命令学习等能力。
7
+ 群聊特化 LLM 聊天机器人,具备表情包管理、记忆存储、联网搜索、跨插件感知、插件调用、LLM 命令学习等能力,并以适配器无关的方式收发消息(OneBot / Satori / Telegram / Discord 等 alconna 支持的适配器均可)。
8
8
 
9
9
  <p>
10
10
  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="python">
11
- <img src="https://img.shields.io/badge/nonebot-2.3+-red?style=flat-square" alt="nonebot">
11
+ <img src="https://img.shields.io/badge/nonebot-2.5+-red?style=flat-square" alt="nonebot">
12
12
  </p>
13
13
  </div>
14
14
 
15
+ > [!WARNING]
16
+ > **这是 beta 分支(2.0.0 开发中):跨适配器改造版**,与 1.6.x(main)不兼容,请勿直接覆盖生产环境的稳定版:
17
+ > - 会话改用 `适配器:会话id` 为键(旧版 `memory/{群号}` 目录会在启动时**自动迁移**为 `onebot11_群号`),新增私聊会话支持
18
+ > - 新增依赖 `nonebot-plugin-alconna`(统一消息)与 `nonebot-plugin-uninfo`(跨适配器会话/成员信息)
19
+ > - 插件调用改为「复制真实消息事件」,合成事件里携带**真实发送者的昵称/群名片/角色**(见「无法代为执行的命令」)
20
+ >
21
+ > 稳定版请留在 main 分支(1.6.x),beta 的功能验证完成后再合并发版。
22
+
15
23
  ## 📖 介绍
16
24
 
17
- 一个基于 NoneBot2 的群聊 AI 助手插件,能够自主收集和发送表情包、联网搜索知识、对群内信息进行记忆,还能够感知同实例内其它插件的输出、通过 LLM 调用其它插件、自主学习群内命令用法,并能通过子插件与其它 bot 通信获取消息和远程调用命令。
25
+ 一个基于 NoneBot2 的群聊 AI 助手插件,能够自主收集和发送表情包、联网搜索知识、对群内信息进行记忆,还能够感知同实例内其它插件的输出、通过 LLM 调用其它插件、自主学习群内命令用法,并能通过子插件与其它 bot 通信获取消息和远程调用命令。消息收发走 [nonebot-plugin-alconna](https://github.com/nonebot/plugin-alconna) 的通用消息层、会话与成员信息走 [nonebot-plugin-uninfo](https://github.com/nonebot/plugin-uninfo),因此同一份代码可以在多个适配器上工作(详细边界见「多适配器支持」)。
18
26
  > 本项目有AI高度参与,若有做得不够好及需要改进的地方,欢迎在issue提出意见。
19
27
 
20
28
  ### 核心能力
21
29
 
30
+ - 🧩 **多适配器支持**:消息收发与会话身份走通用层,OneBot / Satori / Telegram / Discord 等适配器共用同一套聊天、记忆、表情包与命令逻辑(跨插件感知、插件调用等能力仍以 OneBot 为主,见下文边界)
22
31
  - 🔌 **跨插件感知**:LLM 能看到同实例内其它插件的输出(如 rollpig 的小猪卡片、搜索结果等)
23
32
  - 🤖 **插件调用**:LLM 可通过 function calling 调用其它插件(如 `/roll`、`/天气`),支持传递参数与 @ 群友(如 `决斗 @张三 10`)
24
33
  - 🧠 **LLM 命令学习**:通过观察群聊自动学习命令用法,支持学习、编辑、删除
@@ -46,20 +55,20 @@
46
55
  > 要使用本插件, 你至少需要
47
56
  >
48
57
  > - 一个有效的 openai 规范接口 api key,你需要在 `.env` 文件中配置对应的 api 地址
58
+ >
59
+ > 从 2.0 起插件还依赖 `nonebot-plugin-alconna` 与 `nonebot-plugin-uninfo`(跨适配器收发与会话/成员信息),用下面的方式安装时会自动装上。
49
60
 
50
- <details open>
51
- <summary>使用 nb-cli 安装</summary>
52
- 在 nonebot2 项目的根目录下打开命令行, 输入以下指令安装
61
+ ### 安装 beta 版本(2.0.0b1)
53
62
 
54
- nb plugin install nonebot-plugin-aigf-master --upgrade
63
+ `2.0.0b1` 是**预发布(pre-release)版本**,因此:
55
64
 
56
- </details>
65
+ - `pip install nonebot-plugin-aigf-master` 装的仍是稳定版 **1.6.x**
66
+ - `nb plugin install nonebot-plugin-aigf-master` 同样只装稳定版,而且 nb-cli **不支持指定版本**,所以 beta 只能用 pip 装
57
67
 
58
- <details>
59
- <summary>使用包管理器安装</summary>
68
+ 要装 beta,**必须显式写出版本号**:
60
69
 
61
70
  ```bash
62
- pip install nonebot-plugin-aigf-master
71
+ pip install nonebot-plugin-aigf-master==2.0.0b1
63
72
  ```
64
73
 
65
74
  在 `pyproject.toml` 中添加:
@@ -69,7 +78,8 @@ pip install nonebot-plugin-aigf-master
69
78
  plugins = ["nonebot-plugin-aigf-master"]
70
79
  ```
71
80
 
72
- </details>
81
+ > 需要装 beta 分支上尚未发版的改动时,可以直接从分支安装:
82
+ > `pip install git+https://github.com/Funny1Potato/nonebot-plugin-aigf-master.git@beta`
73
83
 
74
84
 
75
85
  ## 配置
@@ -83,7 +93,8 @@ plugins = ["nonebot-plugin-aigf-master"]
83
93
  AIGFM_LLM_API_KEY="sk-xxxxxxxxxxxx" # LLM API Key
84
94
  AIGFM_LLM_BASE_URL="https://api.deepseek.com" # LLM API 地址
85
95
  AIGFM_LLM_MODEL="deepseek-v4-flash" # LLM 模型名称
86
- AIGFM_ENABLED_GROUPS=[123456, 789012] # 启用的群号列表
96
+ AIGFM_ENABLED_GROUPS=[123456, 789012] # 启用的群/频道会话(可写 `适配器:会话id`,只写数字按 OneBot V11 识别)
97
+ AIGFM_ENABLED_PRIVATE=[] # 启用的私聊会话(同上写法;留空则私聊不响应)
87
98
 
88
99
  # --- 图片理解(VLM) ---
89
100
  AIGFM_IMAGE_MODE="vlm" # 图片模式: vlm / llm(默认 vlm)
@@ -167,7 +178,6 @@ AIGFM_ANIME_RECOGNIZE_MAX_CHARACTERS=3 # 展示的角色标签数量上限(
167
178
  AIGFM_ANIME_NSFW_THRESHOLD=0.5 # explicit 概率超过该值标注 [NSFW](默认 0.5;仅本地后端提供画风分级)
168
179
  AIGFM_ANIMETRACE_URL="https://api.animetrace.com" # AnimeTrace API 地址(公共 API、无需鉴权;识别会把图片上传到该服务)
169
180
  AIGFM_ANIMETRACE_TIMEOUT=20.0 # AnimeTrace 请求超时/秒(默认 20.0)
170
- AIGFM_ANIME_RECOGNIZE_ENABLED=false # 【已被 AIGFM_ANIME_BACKEND 取代,仅兼容保留】为 true 且 backend=off 时按 anime-recognize 处理
171
181
 
172
182
  # --- 缓存清理 ---
173
183
  AIGFM_IMAGE_CACHE_MAX_FILES=500 # 描述/角色识别缓存(image_cache 下的 JSON)最大数量,超出按 mtime 最旧删除(默认 500,0=不清理)
@@ -205,6 +215,85 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
205
215
  - 每次处理时,LLM 收到最近 **20 条**(可配置)历史聊天记录 + 四层记忆 + 预设 + 表情包列表 + 其它插件响应;本批消息只出现在「新消息」段,同一条插件响应也只注入一次(不会在历史与新消息里重复)
206
216
  - LLM 一次调用同时完成:回复决策 + 记忆管理 + 表情包选择 + 命令学习
207
217
 
218
+ ## 🧩 多适配器支持
219
+
220
+ 插件的消息**收发**(文本、@、图片、语音、视频、群文件、链接分享、回复、合并转发等)走 [nonebot-plugin-alconna](https://github.com/nonebot/plugin-alconna) 的通用消息层,**会话与成员信息**(昵称、群名片、角色、群名、@ 目标解析)走 [nonebot-plugin-uninfo](https://github.com/nonebot/plugin-uninfo)。因此只要适配器被这两个库支持,聊天 / 记忆 / 表情包 / 生图 / 命令学习等功能就能直接工作,不需要为每个适配器改代码。
221
+
222
+ ### 会话与启用清单
223
+
224
+ - 会话以 **`适配器:会话id`** 为键,例如 `onebot11:617770183`(群)、`console:console-chat`(频道)、`onebot11:20001`(私聊)
225
+ - `AIGFM_ENABLED_GROUPS` 管群/频道会话、`AIGFM_ENABLED_PRIVATE` 管私聊会话;条目可写带前缀的完整键,也可以只写 id(**按 OneBot V11 识别**,旧配置无需改动)
226
+ - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_617770183`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
227
+ - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
228
+
229
+ ### 功能 × 适配器支持表(2026-09-25 实测)
230
+
231
+ 测试方式:本机用 `nb`/pip 装上各适配器包后,为每个适配器**构造真实事件**(各适配器的消息/事件模型),跑本插件同一套功能路径——会话解析(uninfo)→ 消息渲染(uniseg)→ 回复发送(alconna exporter)→ 跨插件捕获(`on_calling_api`)→ 插件调用(复制真实事件 + 目标响应器实际收到命令)。bot 为记录型 mock(拦下所有 API 调用并断言调用的接口名),**未连真实平台**,因此"需要真实 API 才有数据"的项目另标 ⚠。
232
+
233
+ | 适配器 | 会话解析 | 收发/渲染 | 回复发送 | 私聊 | @ 按昵称 | 跨插件捕获 | 插件调用 | 群通知¹ | 跨 bot² |
234
+ |---|---|---|---|---|---|---|---|---|---|
235
+ | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
236
+ | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
237
+ | Console | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
238
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ⚠ | ❌ | ✅ |
239
+ | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
240
+ | Discord | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
241
+ | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
242
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
243
+ | Milky | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
244
+ | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
245
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ⚠ | ❌ | ✅ |
246
+ | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
247
+ | Kritor | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ✅ | ❌ | ✅ |
248
+ | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
249
+ | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
250
+ | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
251
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠ | ✅ | ✅ | ❌ | ✅ |
252
+ | YunHu⁴ | ✅ | ✅ | ✅ | 未测³ | ⚠ | ✅ | ✅ | ❌ | ✅ |
253
+ | bilibili Live⁴ | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠ | ✅ | ✅ | ❌ | ✅ |
254
+
255
+ **读表说明**
256
+
257
+ - **✅ 已实测通过**:会话键、渲染文本、发送接口、捕获入缓冲、目标插件确实收到了命令,逐项断言过。**本表 17 行在 Python 3.10 实测(167 项检查)**;**YunHu / bilibili Live 两行在 Python 3.14 实测**(3.10 装不上,见下),19 个适配器合计 **187 项检查、只有 2 项未通过**(Satori / Kaiheila 的插件调用)
258
+ - **整套依赖栈在 Python 3.14 上跑通**:`nonebot2 2.5.0` + `nonebot-plugin-alconna 0.62.1` + `nonebot-plugin-uninfo 0.11.2` 在 **Python 3.14.3** 上通过了全部回归——主插件 150 项、peer 子插件 67 项、适配器矩阵 187 项(仅上述 2 项未通过)
259
+ - **⚠ 需真机/特例**:
260
+ - **@ 按昵称**:只有 OneBot V11 实测能按群昵称反查出用户 id(走 `get_group_member_list`);其它适配器需要 uninfo 的成员列表查询实现(多数适配器没有),因此**让 LLM 直接用用户 id 更稳**;渲染 @ 时昵称拿不到会回落成 id
261
+ - **插件调用(Satori / Kaiheila)**:这两类适配器的事件结构特殊(Satori 的 `message` 是 `{id, content}` 结构体、Kaiheila 的消息在嵌套的 `event` 里),离线构造"uninfo 与 alconna 都认可"的事件未能复现,因此**未验证通过**;其余 14 个适配器已实测目标响应器收到命令。真机使用请以实际表现为准
262
+ - **❌ 不支持**:群系统通知¹(戳一戳/禁言/进出群/撤回是 OneBot 专属事件类型)
263
+ - **⚠ Python 版本要求**(上表 YunHu / bilibili Live):这两个适配器包**需要 Python ≥ 3.12**——`bilibili Live` 用了 `typing.TypedDict`(pydantic 在 Python < 3.12 直接拒绝),`YunHu` 还额外用到 `typing.NotRequired`(Python 3.11+),所以在 Python 3.10 的 bot 里**导入即失败**。上表这两行的 ✅ 是**在本机 Python 3.14.3 上实测的结果**:两个包都能导入,`alconna` 的 builder/exporter 与 `uninfo` 的 fetcher 三者齐备,会话解析/渲染/发送/捕获/插件调用全部通过(`bilibili Live` 的场景路径=房间号;`YunHu` 的群资料需要真实 API 才有昵称)。**要用这两个平台就把 bot 跑在 Python 3.12+/3.14 上**(本工作目录另建了参考环境 `.venv314`:Python 3.14.3 + `nonebot2 2.5.0` + `alconna 0.62.1` + `uninfo 0.11.2` + 全部 19 个适配器包,回归与矩阵都在里面跑过)
264
+ - **Kook 注意**:社区包 `nonebot-adapter-kook` 的模块名是 `nonebot.adapters.kook`、`get_name()` 报 `Kook`,而 alconna/uninfo 期望的是 `nonebot.adapters.kaiheila`(`Kaiheila`)——**请安装 `nonebot-adapter-kaiheila`**,否则该平台等同于"不被支持"
265
+ - **昵称/群名片**:取决于适配器的 uninfo fetcher 能取到什么(很多要真实 API 调用,离线 mock 拿不到),拿不到时回落成用户 id,功能不受影响
266
+ - 适配器完全不被 alconna/uninfo 支持时,该会话的消息会被静默跳过(只留 debug 日志),不会报错、也不会影响其它适配器
267
+
268
+ <details>
269
+ <summary>实测到的各适配器发送接口(供排查用)</summary>
270
+
271
+ | 适配器 | 回复发送最终调用的接口 |
272
+ |---|---|
273
+ | OneBot V11 / V12 | `send_msg` / `send_message` |
274
+ | Console | `send_message`(私聊 `send_private_message`) |
275
+ | Satori | `send_message`(私聊 `send_private_message`) |
276
+ | Telegram | `send_to` |
277
+ | Discord | `send_to` |
278
+ | QQ | `send_to_group` / `send_to_channel` / `send_to_c2c` |
279
+ | Feishu | `send_msg` |
280
+ | Milky | `send_group_message` / `send_private_message` |
281
+ | Mirai | `send_group_message` / `send_friend_message` |
282
+ | Kaiheila | `send_msg`(按 channel/private 区分) |
283
+ | DoDo | `send_to_channel` / `send_to_personal` |
284
+ | Kritor | `send_message` / `send_channel_message` |
285
+ | Mail | `send_to` |
286
+ | Minecraft | `send_msg` |
287
+ | WXMP | `send_custom_message` |
288
+ | EFChat | `send_chat_message` |
289
+
290
+ </details>
291
+
292
+ > ¹ 群系统通知 = 戳一戳/禁言/进出群/消息撤回。
293
+ > ² 跨 bot = 子插件 [nonebot-plugin-aigfm-peer](https://github.com/Funny1Potato/nonebot-plugin-aigfm-peer) 的推送与远程调用。上表按 **peer 0.4.0+** 的协议标 ✅:推送与调用都会带 `session`(`适配器:会话id`)、主插件按会话键落位,因此各适配器都可用。**用旧 peer(0.3.x)时只有 OneBot V11 的会话能对上**(旧协议只带 `group_id`,按 `onebot11:{group_id}` 映射)。peer 侧捕获/推送与主插件侧落位各自实测过,端到端的「复制事件执行命令」在 OneBot V11 与 Console 上跑通。
294
+ > ³ Kritor / Kaiheila 的私聊事件本次未构造,故未测;它们的私聊类型在 alconna/uninfo 里是有实现的。
295
+ > ⁴ 这两个适配器**需要 Python ≥ 3.12**(3.10 环境里导入即失败),表里这两行是在 **Python 3.14.3** 下实测的结果,见下方说明。
296
+
208
297
  ## 🔌 跨插件感知
209
298
 
210
299
  ### 工作原理
@@ -345,23 +434,30 @@ LLM 只能调用 prompt 里「可用的群功能」/「其它 bot 的命令」
345
434
 
346
435
  ### 无法代为执行的命令
347
436
 
348
- `invoke_plugin` / `invoke_peer_plugin` 是构造一个**合成群事件**(`GroupMessageEvent`)把命令文本投递给目标插件,而不是让真人发消息。合成事件与真实消息存在字段差异,下列命令**调不动**(表现为投递后聊天记录里始终不出现该插件的响应):
437
+ `invoke_plugin` / `invoke_peer_plugin` 并不是让真人发消息,而是**复制该会话里最近一条真实消息事件**、把消息体换成命令文本后投递(2.0 起改为这种做法,此前是手工拼一个 `GroupMessageEvent`)。因此事件的适配器字段、发送者信息都来自那条真实消息,比过去准确得多,但仍与"真的有人发了这条命令"有差别,下列命令**调不动**(表现为投递后聊天记录里始终不出现该插件的响应):
349
438
 
350
439
  | 命令类型 | 无法执行的原因 |
351
440
  |---|---|
352
- | 需要 @机器人 或呼叫昵称才触发 | 合成事件的 `to_me` 恒为 `False`(该字段由适配器在真实消息上计算,投递时绕过了这一步) |
353
- | 需要管理员 / 群主 / 超级用户权限 | `sender.role` 固定为 `"member"`,且传入的 `user_id` 一般不在 `SUPERUSERS` 内,权限检查直接拒绝 |
354
- | 私聊命令 | 合成事件固定 `message_type="group"`,不会命中只监听私聊的 Matcher |
355
- | 必须先回复/引用某条消息才能执行 | 合成事件的 `reply` 恒为 `None`,且真实消息里的 `reply` 段会被适配器展开,这里没有 |
356
- | 依赖群名片 / 头衔 / 等级 / 地区判断身份 | `sender` 只填 `user_id`、`nickname`(当前群预设名,默认「小助手」;peer 侧由 Bot A 传入同一名字)、`role`,其余字段为空 |
357
- | 依赖真实 `message_id` 的后续操作 | `message_id` 是占位值 `0`,插件拿它去 `get_msg` / 撤回 / 引用回复会失败 |
441
+ | 需要 @机器人 或呼叫昵称才触发 | 合成消息里没有 @机器人,`to_me` 沿用被复制那条消息的值(通常为 `False`) |
442
+ | 私聊命令 / 与事件类型强相关 | 复制的是群/频道事件(`message_type` 保持原样),不会命中只监听私聊或其它事件类型的 Matcher |
443
+ | 必须先回复/引用某条消息才能执行 | 合成消息不含回复段,事件里的 `reply` 也被清空 |
444
+ | 依赖群名片 / 头衔 / 等级 / 地区判断身份 | 发送者昵称、群名片、角色已按真实身份填好(`refresh` 不到的字段仍为空:头衔、等级、地区等) |
445
+ | 需要特殊 `message_id` 语义的操作 | `message_id` 是**被复制那条消息的真实 id**(不再是占位 `0`):引用回复可用,但插件若对"这条消息"做撤回/编辑等操作,作用的其实是那条真实消息 |
446
+
447
+ 关于**权限**:合成事件的发送者是**提出请求的那位群友**(`user_id`、昵称、群名片、角色都按真实身份填),所以:
448
+
449
+ - 需要管理员/群主权限的命令,**请托者本身有相应权限时可以被执行**(1.6.x 及更早版本里 `role` 固定为 `member`,一律拒绝);请托者没有权限时仍会被目标插件拒绝
450
+ - `SUPERUSERS` 相关的命令同理:以请托者的身份通过检查
451
+ - 本插件自己的管理命令(`status`/`reset`/`set_role`/…)**无论谁请托都一律拒绝**,不会代为执行(避免真实用户恰好是 SUPERUSER 时被 LLM 触发)
358
452
 
359
453
  两点补充:
360
454
 
361
455
  - `on_keyword` / `on_regex` / `on_message` 型插件(不用 `on_command` 注册)**不会出现在静态命令列表**里,无法被自动发现;但它们的 rule 只匹配文本时,合成事件仍会命中,所以可以靠 LLM 命令学习掌握后调用。
362
456
  - 命令学习会**主动跳过**上表中无法代为执行的命令(不会为它们生成用法记录),避免 LLM 反复误调用。
363
457
 
364
- > 需要多步确认的命令(执行中等待用户再回复)不在上表内:会话按 `group_{group_id}_{user_id}` 归组,只要后续真实消息来自同一个 `user_id`,等待流程仍能接上。
458
+ > 需要多步确认的命令(执行中等待用户再回复)不在上表内:会话按适配器的会话 id 归组(OneBot V11 为 `group_{group_id}_{user_id}`),只要后续真实消息来自同一个 `user_id`,等待流程仍能接上。
459
+
460
+ > 若目标插件是用 alconna 写的,插件会在投递前把 alconna 按 `message_id` 缓存的那条消息**替换成命令内容**——否则它会把命令读成"原来那条用户消息",永远匹配不上。
365
461
 
366
462
  ## 🌐 跨 bot 通信
367
463
 
@@ -561,7 +657,7 @@ memes/
561
657
  | 后端 | 工作方式 | 擅长 | 代价 |
562
658
  |---|---|---|---|
563
659
  | `anime-recognize` | 本地 WD14 推理服务([aigfm-anime-recognize](https://github.com/Funny1Potato/aigfm-anime-recognize)),**需自行部署** | 动漫 / 手游角色,输出英文 booru 标签(如 `hu_tao_(genshin_impact)`)+ 数值置信度 + 画风分级 | 本地推理、免费无限量;**对 gal / 视觉小说角色识别率低** |
564
- | `animetrace` | [AnimeTrace](https://ai.animedb.cn/) 公共 API,**无需部署、无需鉴权** | gal / 视觉小说角色,并给出作品名(如「胡桃(原神)」) | 图片会上传到该第三方公共服务;有使用配额;不返回数值置信度、无画风分级 |
660
+ | `animetrace` | [AnimeTrace](https://ai.animedb.cn/) 公共 API,**无需部署、无需鉴权** | gal / 视觉小说角色,并给出作品名(如「胡桃(原神)」) | 图片会上传到该第三方公共服务;有使用配额;不返回数值置信度、无画风分级;对gal以外游戏角色的识别率一般 |
565
661
 
566
662
  `both` 模式先问本地服务,本地置信度不足(低于 `AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE`)再问 AnimeTrace,两边都没有可信结果才渲染 `[角色识别: 未能识别]`——平时不消耗公共 API 配额。
567
663
 
@@ -572,8 +668,10 @@ memes/
572
668
  ```bash
573
669
  git clone https://github.com/Funny1Potato/aigfm-anime-recognize.git
574
670
  cd aigfm-anime-recognize
671
+ # 安装
575
672
  # Windows: install.bat ;Linux/macOS: chmod +x install.sh && ./install.sh
576
- # 一键完成:建虚拟环境 → 装钉版本依赖 → 下载模型(约 446MB)→ 启动服务(0.0.0.0:8000)
673
+ # 启动
674
+ # Windows: start.bat ; Linux / macOS: chmod +x start.sh && ./start.sh
577
675
  ```
578
676
 
579
677
  **插件配置**:
@@ -583,14 +681,14 @@ cd aigfm-anime-recognize
583
681
  AIGFM_ANIME_BACKEND=both
584
682
 
585
683
  # 本地后端地址(backend 含 anime-recognize 时必填;服务端未启用鉴权时 token 留空)
586
- AIGFM_ANIME_RECOGNIZE_URL=http://127.0.0.1:8000
684
+ AIGFM_ANIME_RECOGNIZE_URL="http://127.0.0.1:8000"
587
685
  # AIGFM_ANIME_RECOGNIZE_TOKEN=可选
588
686
 
589
687
  # 可选调参(默认值如下)
590
688
  # AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE=0.85 # 展示角色标签的最低置信度;both 模式下也用它判断本地是否有结果
591
689
  # AIGFM_ANIME_RECOGNIZE_MAX_CHARACTERS=3 # 展示的角色标签数量上限
592
690
  # AIGFM_ANIME_NSFW_THRESHOLD=0.5 # explicit 概率超过该值标注 [NSFW](只标注不拦截;仅本地后端提供分级)
593
- # AIGFM_ANIMETRACE_URL=https://api.animetrace.com
691
+ # AIGFM_ANIMETRACE_URL="https://api.animetrace.com"
594
692
  # AIGFM_ANIMETRACE_TIMEOUT=20 # AnimeTrace 请求超时(秒)
595
693
  ```
596
694
 
@@ -612,8 +710,8 @@ AIGFM_ANIME_RECOGNIZE_URL=http://127.0.0.1:8000
612
710
  - 改 `AIGFM_ANIME_RECOGNIZE_MIN_CONFIDENCE` 只影响此后新识别的图片;已缓存图片要重新判定需删除其 `{md5}_anime.json`
613
711
 
614
712
  **已知局限**:
615
- - **本地后端**:训练数据截止 2024 年前后,新游/新角色可能认不出,**gal / 视觉小说角色识别率尤其低(建议改用 `animetrace` 或 `both`)**;多人合影会漏识别;皮肤/异格不区分;3D 战斗小人/游戏内截图识别率偏低;输出为英文标签(中文映射需自行扩展)
616
- - **AnimeTrace**:不返回数值置信度,只有服务自己的低置信判定——被判低置信时一律按「未能识别」处理,日志 `[角色识别] AnimeTrace 无可信结果,低置信候选: …` 会给出它认为最可能的候选,便于排查;其检测框可能包含误检,多人提示仅供参考;`[NSFW]` 标记只由本地后端提供
713
+ - **本地后端**:训练数据截止 2024 年前后,新游/新角色可能认不出,**gal / 视觉小说角色识别率尤其低(建议改用 `animetrace` 或 `both`)**;多人合影可能会漏识别;3D 战斗小人/游戏内截图识别率不高;输出为英文标签(中文映射需自行扩展)
714
+ - **AnimeTrace**:对gal以外的游戏角色识别率一般;不返回数值置信度,只有服务自己的低置信判定——被判低置信时一律按「未能识别」处理,日志 `[角色识别] AnimeTrace 无可信结果,低置信候选: …` 会给出它认为最可能的候选,便于排查;其检测框可能包含误检,多人提示仅供参考;`[NSFW]` 标记只由本地后端提供
617
715
  - 识别结果(角色名)会进入 LLM 上下文,也就是群里能看到;在意隐私请只用 `anime-recognize`(纯本地)或关闭本功能
618
716
 
619
717
  > 仅 `AIGFM_IMAGE_MODE=vlm` 模式生效;`llm` 模式图片不经过 VLM,无二次元判断。