nonebot-plugin-aigf-master 2.0.0b4__tar.gz → 2.0.0b5__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 (46) hide show
  1. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/PKG-INFO +64 -20
  2. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/README.md +62 -19
  3. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/__init__.py +781 -749
  4. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/api_hooks.py +7 -5
  5. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/command_learner.py +59 -5
  6. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/config.py +129 -115
  7. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/effect_store.py +60 -0
  8. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/image_handler.py +222 -219
  9. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/invocation.py +15 -0
  10. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/llm_client.py +257 -0
  11. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/meme_store.py +30 -9
  12. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/memory_store.py +67 -23
  13. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/message_sender.py +260 -0
  14. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/peer_client.py +65 -0
  15. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/plugin_invoker.py +47 -37
  16. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/processor.py +273 -85
  17. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/prompt_builder.py +587 -509
  18. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/search_client.py +26 -7
  19. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/session.py +410 -280
  20. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/store_coordinator.py +128 -0
  21. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/tool_handlers.py +173 -0
  22. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/tool_memory.py +176 -0
  23. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/tool_runtime.py +182 -0
  24. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/tool_schemas.py +203 -0
  25. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/unimsg.py +474 -453
  26. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/PKG-INFO +64 -20
  27. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/SOURCES.txt +8 -0
  28. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/requires.txt +1 -0
  29. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/pyproject.toml +5 -1
  30. nonebot_plugin_aigf_master-2.0.0b4/nonebot_plugin_aigf_master/llm_client.py +0 -118
  31. nonebot_plugin_aigf_master-2.0.0b4/nonebot_plugin_aigf_master/peer_client.py +0 -49
  32. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/LICENSE +0 -0
  33. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/anime_recognizer.py +0 -0
  34. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/animetrace_client.py +0 -0
  35. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/cache_cleanup.py +0 -0
  36. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/context_bus.py +0 -0
  37. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/image_gen_client.py +0 -0
  38. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/models.py +0 -0
  39. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/notice.py +0 -0
  40. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/plugin_discovery.py +0 -0
  41. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/preset_store.py +0 -0
  42. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/response_parser.py +0 -0
  43. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/vlm_client.py +0 -0
  44. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/dependency_links.txt +0 -0
  45. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/top_level.txt +0 -0
  46. {nonebot_plugin_aigf_master-2.0.0b4 → nonebot_plugin_aigf_master-2.0.0b5}/setup.cfg +0 -0
@@ -1,12 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: nonebot-plugin-aigf-master
3
- Version: 2.0.0b4
3
+ Version: 2.0.0b5
4
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
9
  Requires-Dist: nonebot2>=2.5.0
10
+ Requires-Dist: pydantic<3,>=2.0
10
11
  Requires-Dist: nonebot-adapter-onebot>=2.2.0
11
12
  Requires-Dist: nonebot-plugin-localstore>=0.5.0
12
13
  Requires-Dist: nonebot-plugin-alconna>=0.62
@@ -80,9 +81,9 @@ Dynamic: license-file
80
81
  >
81
82
  > 从 2.0 起插件还依赖 `nonebot-plugin-alconna` 与 `nonebot-plugin-uninfo`(跨适配器收发与会话/成员信息),用下面的方式安装时会自动装上。
82
83
 
83
- ### 安装 beta 版本(2.0.0b4)
84
+ ### 安装 beta 版本(2.0.0b5)
84
85
 
85
- `2.0.0b4` 是**预发布(pre-release)版本**,因此:
86
+ `2.0.0b5` 是**预发布(pre-release)版本**,因此:
86
87
 
87
88
  - `pip install nonebot-plugin-aigf-master` 装的仍是稳定版 **1.6.x**
88
89
  - `nb plugin install nonebot-plugin-aigf-master` 同样只装稳定版,而且 nb-cli **不支持指定版本**,所以 beta 只能用 pip 装
@@ -90,7 +91,7 @@ Dynamic: license-file
90
91
  要装 beta,**必须显式写出版本号**:
91
92
 
92
93
  ```bash
93
- pip install nonebot-plugin-aigf-master==2.0.0b4
94
+ pip install nonebot-plugin-aigf-master==2.0.0b5
94
95
  ```
95
96
 
96
97
  在 `pyproject.toml` 中添加:
@@ -118,9 +119,10 @@ AIGFM_LLM_MODEL="deepseek-v4-flash" # LLM 模型
118
119
  AIGFM_ENABLED_GROUPS=["onebot11:123456789", "console:console-chat"] # 启用的群/频道会话(`适配器:会话id`;也可只写数字,按 OneBot V11 识别)
119
120
  AIGFM_ENABLED_PRIVATE=["onebot11:20001"] # 启用的私聊会话(同上写法;留空则私聊不响应)
120
121
 
121
- # --- 图片理解(VLM) ---
122
- AIGFM_IMAGE_MODE="vlm" # 图片模式: vlm / llm(默认 vlm)
123
- AIGFM_VLM_ENABLED=true # 是否启用VLM(仅 vlm 模式有效,默认 true)
122
+ # --- 图片理解(多模态 LLM / VLM) ---
123
+ AIGFM_IMAGE_MODE="llm" # 图片模式: llm(默认,多模态统一模型)/ vlm(独立视觉模型)
124
+ AIGFM_LLM_MULTIMODAL="" # 主模型是否支持图片: 留空=启动时自动探测 / true=强制支持 / false=强制不支持并回落到 vlm
125
+ AIGFM_VLM_ENABLED=true # 是否启用VLM(vlm 模式必需;llm 模式主模型不支持图片时作为回落通道,默认 true)
124
126
  AIGFM_VLM_MODEL="..." # VLM 模型名称(vlm 模式必填)
125
127
  AIGFM_VLM_BASE_URL="https://..." # VLM API 地址
126
128
  AIGFM_VLM_API_KEY="" # VLM API Key(为空时使用 llm 的 key)
@@ -249,7 +251,7 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
249
251
  - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_123456789`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
250
252
  - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
251
253
 
252
- ### 功能 × 适配器支持表(2026-09-25 实测)
254
+ ### 功能 × 适配器支持表(2026-11-12 离线复核,本地未发布改动)
253
255
 
254
256
  为每个适配器**构造真实事件**跑同一套功能路径(会话解析 → 渲染 → 回复发送 → 跨插件捕获 → 插件调用),bot 是记录型 mock,**未连真实平台**。
255
257
 
@@ -258,20 +260,20 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
258
260
  | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
259
261
  | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
260
262
  | Console | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
261
- | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
263
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
262
264
  | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
263
265
  | Discord | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
264
266
  | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
265
- | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
267
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
266
268
  | Milky | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
267
269
  | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
268
- | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
270
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
269
271
  | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
270
- | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ❌ | ✅ |
272
+ | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
271
273
  | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
272
274
  | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
273
275
  | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
274
- | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
276
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
275
277
  | YunHu | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
276
278
  | bilibili Live | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
277
279
 
@@ -284,8 +286,8 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
284
286
  **已知特例**
285
287
 
286
288
  - **@ 按昵称**:只有 OneBot V11 能按群昵称反查用户 id,其余适配器请让 LLM 直接用用户 id
287
- - **插件调用**:Satori / Kaiheila 的事件结构特殊,离线未验证通过;其余 14 个已实测目标响应器收到命令
288
- - **群通知**:为每个适配器构造真实通知事件实测,**10 个通过**(OneBot V11/V12、Satori、Telegram、QQ、Milky、Mirai、Kaiheila、DoDo、YunHu);Discord / bilibili 未验证(离线 mock 不够 / 只有部分通知类在库的覆盖范围内);**Feishu、Kritor、EFChat** 的通知 uninfo 与 alconna 都无法定位到群/频道会话,**Minecraft、WXMP** 的通知事件没有群/频道字段(会话按私聊处理)——这几种会被跳过(库层限制,非本插件可修)
289
+ - **插件调用**:消息/调用矩阵 206 个检查点通过,包含 Satori / Kaiheila 目标响应器收到命令。已修复构造期消息缓存与只读消息属性;仍不等于真实平台联调通过。
290
+ - **群通知**:17 个通知检查点中 15 个通过、2 个按预期跳过(Minecraft / WXMP 无群会话字段;Console / Mail 无通知类型,不在该矩阵内)。飞书、Kritor、bilibili Live 对上游尚不支持的通知按明确群/房间字段定位;Discord / Kaiheila 的服务器级事件只进入服务器会话,不广播到子频道。详见 [能力边界](docs/ADAPTER_SUPPORT.md)。
289
291
  - **YunHu / bilibili Live**:需要把 bot 跑在 **Python ≥ 3.12**(3.10 里导入即失败;这两行的 ✅ 是在 3.14 实测的)
290
292
  - **Kaiheila**:请装 `nonebot-adapter-kaiheila`(社区包 `nonebot-adapter-kook` 的模块名与 alconna/uninfo 期望的不一致)
291
293
  - **跨 bot**:按 peer 0.4.0+ 的 `session` 协议可用;旧 peer(0.3.x)只有 OneBot V11 的会话能对上
@@ -411,6 +413,7 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
411
413
 
412
414
  | 限制 | 默认 | 配置项 |
413
415
  |---|---|---|
416
+ | **每批调用尝试上限** | 1(本机与 peer 共用) | `AIGFM_INVOKE_MAX_PER_BATCH`(正整数,含 JSON 解析重试) |
414
417
  | **重复调用去重** | 开启 | `AIGFM_INVOKE_DEDUP_ENABLED` |
415
418
  | **去重时间窗口** | 20 分钟 | `AIGFM_INVOKE_DEDUP_WINDOW`(秒;0 = 不限时间) |
416
419
  | **去重比对条数** | 15 | `AIGFM_INVOKE_DEDUP_RECORDS` |
@@ -419,12 +422,19 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
419
422
 
420
423
  - 去重判定为**命令 + 参数 + 调用身份(QQ 号)三者完全相同**;拦截范围 = **时间窗口内**(`AIGFM_INVOKE_DEDUP_WINDOW`)∩ **调用台账保留的最近 N 条**(`AIGFM_INVOKE_DEDUP_RECORDS`)
421
424
  - **不区分本机与其它 bot**:同一命令、同一身份在范围内只执行一次
422
- - 换个参数(`决斗 @张三` → `决斗 @李四`)或换个身份(不同 QQ 号)视为不同调用,正常放行
425
+ - 换参数或身份不命中相同调用去重,但仍受每批共享额度与能量限制;明确未投递的尝试也占本批额度,下一批重新计算
423
426
  - prompt 里的「你最近代为执行过的命令」段只展示**其中最近 10 条**(防止 prompt 随条数膨胀)
424
427
  - 执行 `/reset` 会一并清空调用台账(重置后不再被"刚调用过"挡住)
425
- - 每次**实际投递**扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量(被拒绝时不扣);能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
428
+ - 已投递、peer 已接收及投递结果不确定时,扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量并写入去重台账;明确未投递和前置拒绝不扣能量、不写去重台账;能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
426
429
  - 被拒绝时:工具结果**当场**告知 LLM 原因,同时在聊天记录里留下 `已拒绝调用命令「xxx」(原因)`,**下一轮** LLM 能看到;拒绝**不写入调用台账**(不会阻止之后真正的再调用)
427
430
 
431
+ ### 调用回执与身份
432
+
433
+ 回执区分未投递、本机已投递、peer 已接收、结果不确定。peer 的 HTTP `ok: true` 只表示请求已被接收;超时、分发异常、读写超时不证明没有执行,因此保留去重。后续没有输出也不能直接断定成功或失败。
434
+ 每次投递尝试附带请求编号,供本机日志、工具回执和台账相互核对;编号尚不随 peer 输出回传,也不自动将输出判定为某次命令执行成功。
435
+ 本批调用使用批处理开始时保存的 bot、会话、真实事件和默认用户身份;等待 LLM 期间到达的新消息不会替换这些调用依据。显式指定 user_id 的能力保持原样。
436
+ 搜索、插件调用和生图按各自开关进入工具路径,关闭搜索不会关闭后两者。本批调用额度仅限制 `invoke_plugin` 与 `invoke_peer_plugin`,不包含搜索或生图任务。
437
+
428
438
  ### 命令前缀自动适配
429
439
 
430
440
  - LLM 调用命令时**始终传不带前缀的命令**(如 `今日小猪`)
@@ -665,8 +675,18 @@ memes/
665
675
 
666
676
  | 模式 | 流程 | 适用场景 |
667
677
  |------|------|---------|
668
- | `vlm`(默认) | 图片 → VLM 分析 → 文字描述给 LLM | LLM 不支持图片输入 |
669
- | `llm` | 图片 → base64 直接附在 LLM prompt 中 | LLM 支持视觉 |
678
+ | `llm`(默认) | 图片 → base64 直接附在 LLM prompt 中 | 主模型支持视觉;推荐用统一多模态模型 |
679
+ | `vlm` | 图片 → VLM 分析 → 文字描述给 LLM | 主 LLM 不支持图片输入 |
680
+
681
+ > 默认使用 `llm` 模式,适应当前主流多模态模型。若主 LLM 只能处理文字,请显式设置 `AIGFM_IMAGE_MODE=vlm` 并配置 VLM,否则图片请求可能被服务端拒绝。
682
+
683
+ `llm` 模式下主模型不支持图片时的自动回落:
684
+
685
+ - 启动时用一张 16×16 的小图探测一次主模型是否接受图片输入,探不过就自动回落到 `vlm` 模式(解析期把图片转成文字描述,请求期只发文本),存量用户升级后不会因为主模型只支持文本而整批不回复
686
+ - 运行期若带图请求被服务端明确拒绝(400/415/422),同样标记为不支持多模态,**下一批**消息起自动回落到 `vlm` 模式
687
+ - 落回 `vlm` 模式需要配好 VLM;`AIGFM_LLM_MULTIMODAL=true/false` 可跳过探测、直接固定判定
688
+ - 图片按 base64 魔数声明真实 MIME(jpeg/png/gif/webp/bmp),并在多模态内容里给每张图加 `[图片 id: xxx]` 锚点,与 prompt 正文的标注一一对应
689
+ - 开启联网搜索等工具调用时,图片同样随首轮 LLM 请求发送(此前工具路径会漏掉图片)
670
690
 
671
691
  `vlm` 模式下的行为说明:
672
692
 
@@ -764,9 +784,11 @@ LLM 支持以下回复类型:
764
784
  | 类型 | 格式 | 说明 |
765
785
  |------|------|------|
766
786
  | 文本 | `{"type": "text", "content": "..."}` | 纯文本消息 |
767
- | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友 |
787
+ | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友(也可填群名片或 QQ 号) |
768
788
  | 表情包 | `{"type": "meme", "id": "表情包id"}` | 发送表情包 |
769
789
 
790
+ > 要 @ 群友时应使用独立的 `at` 段。为兼容部分模型误把 `@昵称` 写进文本的情况,发送前也会把能匹配到群成员的文本 @(含群名片、QQ 号写法)自动转换为真实 QQ @;重名成员不自动转换,避免误 @ 到别人。
791
+
770
792
  ## 📁 数据存储
771
793
 
772
794
  ```
@@ -817,3 +839,25 @@ LLM 支持以下回复类型:
817
839
  ## License
818
840
 
819
841
  MIT
842
+
843
+ ## 开发与验证
844
+
845
+ 当前实现与边界见 [项目状态](docs/CURRENT_STATE.md),维护流程见 [开发与同步](docs/DEVELOPMENT.md)。
846
+
847
+ 离线验证入口与环境要求见 [tests/README.md](tests/README.md)。
848
+
849
+ ## 工具动作协议(本地开发功能,尚未发布)
850
+
851
+ 新增 tools 协议,用函数调用完成发言、四层记忆、群友别名、表情包收藏及命令学习,不再执行最终 reply/memory JSON;普通结束文字不会发送。
852
+ 默认仍是 legacy_json。显式设置 `AIGFM_ACTION_PROTOCOL=tools` 后按新协议运行,不能在同一批混用两套动作。
853
+
854
+ ```env
855
+ AIGFM_ACTION_PROTOCOL=tools
856
+ AIGFM_LLM_MAX_TOOL_TURNS=3
857
+ AIGFM_TOOL_MAX_CALLS=12
858
+ AIGFM_TOOL_BATCH_TIMEOUT=180
859
+ AIGFM_TOOL_SEND_MAX_MESSAGES=3
860
+ AIGFM_TOOL_MEMORY_ENABLED=true
861
+ ```
862
+
863
+ 首次使用会备份并初始化记忆条目引用;非 OneBot 群友使用独立命名空间。建议先运行源码仓库中的只读迁移预览。完整契约、部分发送/重启处理、回退与验证边界见 [工具协议说明](docs/TOOL_PROTOCOL.md)。
@@ -58,9 +58,9 @@
58
58
  >
59
59
  > 从 2.0 起插件还依赖 `nonebot-plugin-alconna` 与 `nonebot-plugin-uninfo`(跨适配器收发与会话/成员信息),用下面的方式安装时会自动装上。
60
60
 
61
- ### 安装 beta 版本(2.0.0b4)
61
+ ### 安装 beta 版本(2.0.0b5)
62
62
 
63
- `2.0.0b4` 是**预发布(pre-release)版本**,因此:
63
+ `2.0.0b5` 是**预发布(pre-release)版本**,因此:
64
64
 
65
65
  - `pip install nonebot-plugin-aigf-master` 装的仍是稳定版 **1.6.x**
66
66
  - `nb plugin install nonebot-plugin-aigf-master` 同样只装稳定版,而且 nb-cli **不支持指定版本**,所以 beta 只能用 pip 装
@@ -68,7 +68,7 @@
68
68
  要装 beta,**必须显式写出版本号**:
69
69
 
70
70
  ```bash
71
- pip install nonebot-plugin-aigf-master==2.0.0b4
71
+ pip install nonebot-plugin-aigf-master==2.0.0b5
72
72
  ```
73
73
 
74
74
  在 `pyproject.toml` 中添加:
@@ -96,9 +96,10 @@ AIGFM_LLM_MODEL="deepseek-v4-flash" # LLM 模型
96
96
  AIGFM_ENABLED_GROUPS=["onebot11:123456789", "console:console-chat"] # 启用的群/频道会话(`适配器:会话id`;也可只写数字,按 OneBot V11 识别)
97
97
  AIGFM_ENABLED_PRIVATE=["onebot11:20001"] # 启用的私聊会话(同上写法;留空则私聊不响应)
98
98
 
99
- # --- 图片理解(VLM) ---
100
- AIGFM_IMAGE_MODE="vlm" # 图片模式: vlm / llm(默认 vlm)
101
- AIGFM_VLM_ENABLED=true # 是否启用VLM(仅 vlm 模式有效,默认 true)
99
+ # --- 图片理解(多模态 LLM / VLM) ---
100
+ AIGFM_IMAGE_MODE="llm" # 图片模式: llm(默认,多模态统一模型)/ vlm(独立视觉模型)
101
+ AIGFM_LLM_MULTIMODAL="" # 主模型是否支持图片: 留空=启动时自动探测 / true=强制支持 / false=强制不支持并回落到 vlm
102
+ AIGFM_VLM_ENABLED=true # 是否启用VLM(vlm 模式必需;llm 模式主模型不支持图片时作为回落通道,默认 true)
102
103
  AIGFM_VLM_MODEL="..." # VLM 模型名称(vlm 模式必填)
103
104
  AIGFM_VLM_BASE_URL="https://..." # VLM API 地址
104
105
  AIGFM_VLM_API_KEY="" # VLM API Key(为空时使用 llm 的 key)
@@ -227,7 +228,7 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
227
228
  - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_123456789`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
228
229
  - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
229
230
 
230
- ### 功能 × 适配器支持表(2026-09-25 实测)
231
+ ### 功能 × 适配器支持表(2026-11-12 离线复核,本地未发布改动)
231
232
 
232
233
  为每个适配器**构造真实事件**跑同一套功能路径(会话解析 → 渲染 → 回复发送 → 跨插件捕获 → 插件调用),bot 是记录型 mock,**未连真实平台**。
233
234
 
@@ -236,20 +237,20 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
236
237
  | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
237
238
  | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
238
239
  | Console | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
239
- | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
240
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
240
241
  | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
241
242
  | Discord | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
242
243
  | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
243
- | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
244
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
244
245
  | Milky | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
245
246
  | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
246
- | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
247
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
247
248
  | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
248
- | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ❌ | ✅ |
249
+ | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
249
250
  | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
250
251
  | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
251
252
  | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
252
- | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
253
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
253
254
  | YunHu | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
254
255
  | bilibili Live | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
255
256
 
@@ -262,8 +263,8 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
262
263
  **已知特例**
263
264
 
264
265
  - **@ 按昵称**:只有 OneBot V11 能按群昵称反查用户 id,其余适配器请让 LLM 直接用用户 id
265
- - **插件调用**:Satori / Kaiheila 的事件结构特殊,离线未验证通过;其余 14 个已实测目标响应器收到命令
266
- - **群通知**:为每个适配器构造真实通知事件实测,**10 个通过**(OneBot V11/V12、Satori、Telegram、QQ、Milky、Mirai、Kaiheila、DoDo、YunHu);Discord / bilibili 未验证(离线 mock 不够 / 只有部分通知类在库的覆盖范围内);**Feishu、Kritor、EFChat** 的通知 uninfo 与 alconna 都无法定位到群/频道会话,**Minecraft、WXMP** 的通知事件没有群/频道字段(会话按私聊处理)——这几种会被跳过(库层限制,非本插件可修)
266
+ - **插件调用**:消息/调用矩阵 206 个检查点通过,包含 Satori / Kaiheila 目标响应器收到命令。已修复构造期消息缓存与只读消息属性;仍不等于真实平台联调通过。
267
+ - **群通知**:17 个通知检查点中 15 个通过、2 个按预期跳过(Minecraft / WXMP 无群会话字段;Console / Mail 无通知类型,不在该矩阵内)。飞书、Kritor、bilibili Live 对上游尚不支持的通知按明确群/房间字段定位;Discord / Kaiheila 的服务器级事件只进入服务器会话,不广播到子频道。详见 [能力边界](docs/ADAPTER_SUPPORT.md)。
267
268
  - **YunHu / bilibili Live**:需要把 bot 跑在 **Python ≥ 3.12**(3.10 里导入即失败;这两行的 ✅ 是在 3.14 实测的)
268
269
  - **Kaiheila**:请装 `nonebot-adapter-kaiheila`(社区包 `nonebot-adapter-kook` 的模块名与 alconna/uninfo 期望的不一致)
269
270
  - **跨 bot**:按 peer 0.4.0+ 的 `session` 协议可用;旧 peer(0.3.x)只有 OneBot V11 的会话能对上
@@ -389,6 +390,7 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
389
390
 
390
391
  | 限制 | 默认 | 配置项 |
391
392
  |---|---|---|
393
+ | **每批调用尝试上限** | 1(本机与 peer 共用) | `AIGFM_INVOKE_MAX_PER_BATCH`(正整数,含 JSON 解析重试) |
392
394
  | **重复调用去重** | 开启 | `AIGFM_INVOKE_DEDUP_ENABLED` |
393
395
  | **去重时间窗口** | 20 分钟 | `AIGFM_INVOKE_DEDUP_WINDOW`(秒;0 = 不限时间) |
394
396
  | **去重比对条数** | 15 | `AIGFM_INVOKE_DEDUP_RECORDS` |
@@ -397,12 +399,19 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
397
399
 
398
400
  - 去重判定为**命令 + 参数 + 调用身份(QQ 号)三者完全相同**;拦截范围 = **时间窗口内**(`AIGFM_INVOKE_DEDUP_WINDOW`)∩ **调用台账保留的最近 N 条**(`AIGFM_INVOKE_DEDUP_RECORDS`)
399
401
  - **不区分本机与其它 bot**:同一命令、同一身份在范围内只执行一次
400
- - 换个参数(`决斗 @张三` → `决斗 @李四`)或换个身份(不同 QQ 号)视为不同调用,正常放行
402
+ - 换参数或身份不命中相同调用去重,但仍受每批共享额度与能量限制;明确未投递的尝试也占本批额度,下一批重新计算
401
403
  - prompt 里的「你最近代为执行过的命令」段只展示**其中最近 10 条**(防止 prompt 随条数膨胀)
402
404
  - 执行 `/reset` 会一并清空调用台账(重置后不再被"刚调用过"挡住)
403
- - 每次**实际投递**扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量(被拒绝时不扣);能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
405
+ - 已投递、peer 已接收及投递结果不确定时,扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量并写入去重台账;明确未投递和前置拒绝不扣能量、不写去重台账;能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
404
406
  - 被拒绝时:工具结果**当场**告知 LLM 原因,同时在聊天记录里留下 `已拒绝调用命令「xxx」(原因)`,**下一轮** LLM 能看到;拒绝**不写入调用台账**(不会阻止之后真正的再调用)
405
407
 
408
+ ### 调用回执与身份
409
+
410
+ 回执区分未投递、本机已投递、peer 已接收、结果不确定。peer 的 HTTP `ok: true` 只表示请求已被接收;超时、分发异常、读写超时不证明没有执行,因此保留去重。后续没有输出也不能直接断定成功或失败。
411
+ 每次投递尝试附带请求编号,供本机日志、工具回执和台账相互核对;编号尚不随 peer 输出回传,也不自动将输出判定为某次命令执行成功。
412
+ 本批调用使用批处理开始时保存的 bot、会话、真实事件和默认用户身份;等待 LLM 期间到达的新消息不会替换这些调用依据。显式指定 user_id 的能力保持原样。
413
+ 搜索、插件调用和生图按各自开关进入工具路径,关闭搜索不会关闭后两者。本批调用额度仅限制 `invoke_plugin` 与 `invoke_peer_plugin`,不包含搜索或生图任务。
414
+
406
415
  ### 命令前缀自动适配
407
416
 
408
417
  - LLM 调用命令时**始终传不带前缀的命令**(如 `今日小猪`)
@@ -643,8 +652,18 @@ memes/
643
652
 
644
653
  | 模式 | 流程 | 适用场景 |
645
654
  |------|------|---------|
646
- | `vlm`(默认) | 图片 → VLM 分析 → 文字描述给 LLM | LLM 不支持图片输入 |
647
- | `llm` | 图片 → base64 直接附在 LLM prompt 中 | LLM 支持视觉 |
655
+ | `llm`(默认) | 图片 → base64 直接附在 LLM prompt 中 | 主模型支持视觉;推荐用统一多模态模型 |
656
+ | `vlm` | 图片 → VLM 分析 → 文字描述给 LLM | 主 LLM 不支持图片输入 |
657
+
658
+ > 默认使用 `llm` 模式,适应当前主流多模态模型。若主 LLM 只能处理文字,请显式设置 `AIGFM_IMAGE_MODE=vlm` 并配置 VLM,否则图片请求可能被服务端拒绝。
659
+
660
+ `llm` 模式下主模型不支持图片时的自动回落:
661
+
662
+ - 启动时用一张 16×16 的小图探测一次主模型是否接受图片输入,探不过就自动回落到 `vlm` 模式(解析期把图片转成文字描述,请求期只发文本),存量用户升级后不会因为主模型只支持文本而整批不回复
663
+ - 运行期若带图请求被服务端明确拒绝(400/415/422),同样标记为不支持多模态,**下一批**消息起自动回落到 `vlm` 模式
664
+ - 落回 `vlm` 模式需要配好 VLM;`AIGFM_LLM_MULTIMODAL=true/false` 可跳过探测、直接固定判定
665
+ - 图片按 base64 魔数声明真实 MIME(jpeg/png/gif/webp/bmp),并在多模态内容里给每张图加 `[图片 id: xxx]` 锚点,与 prompt 正文的标注一一对应
666
+ - 开启联网搜索等工具调用时,图片同样随首轮 LLM 请求发送(此前工具路径会漏掉图片)
648
667
 
649
668
  `vlm` 模式下的行为说明:
650
669
 
@@ -742,9 +761,11 @@ LLM 支持以下回复类型:
742
761
  | 类型 | 格式 | 说明 |
743
762
  |------|------|------|
744
763
  | 文本 | `{"type": "text", "content": "..."}` | 纯文本消息 |
745
- | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友 |
764
+ | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友(也可填群名片或 QQ 号) |
746
765
  | 表情包 | `{"type": "meme", "id": "表情包id"}` | 发送表情包 |
747
766
 
767
+ > 要 @ 群友时应使用独立的 `at` 段。为兼容部分模型误把 `@昵称` 写进文本的情况,发送前也会把能匹配到群成员的文本 @(含群名片、QQ 号写法)自动转换为真实 QQ @;重名成员不自动转换,避免误 @ 到别人。
768
+
748
769
  ## 📁 数据存储
749
770
 
750
771
  ```
@@ -795,3 +816,25 @@ LLM 支持以下回复类型:
795
816
  ## License
796
817
 
797
818
  MIT
819
+
820
+ ## 开发与验证
821
+
822
+ 当前实现与边界见 [项目状态](docs/CURRENT_STATE.md),维护流程见 [开发与同步](docs/DEVELOPMENT.md)。
823
+
824
+ 离线验证入口与环境要求见 [tests/README.md](tests/README.md)。
825
+
826
+ ## 工具动作协议(本地开发功能,尚未发布)
827
+
828
+ 新增 tools 协议,用函数调用完成发言、四层记忆、群友别名、表情包收藏及命令学习,不再执行最终 reply/memory JSON;普通结束文字不会发送。
829
+ 默认仍是 legacy_json。显式设置 `AIGFM_ACTION_PROTOCOL=tools` 后按新协议运行,不能在同一批混用两套动作。
830
+
831
+ ```env
832
+ AIGFM_ACTION_PROTOCOL=tools
833
+ AIGFM_LLM_MAX_TOOL_TURNS=3
834
+ AIGFM_TOOL_MAX_CALLS=12
835
+ AIGFM_TOOL_BATCH_TIMEOUT=180
836
+ AIGFM_TOOL_SEND_MAX_MESSAGES=3
837
+ AIGFM_TOOL_MEMORY_ENABLED=true
838
+ ```
839
+
840
+ 首次使用会备份并初始化记忆条目引用;非 OneBot 群友使用独立命名空间。建议先运行源码仓库中的只读迁移预览。完整契约、部分发送/重启处理、回退与验证边界见 [工具协议说明](docs/TOOL_PROTOCOL.md)。