nonebot-plugin-aigf-master 2.0.0b3__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.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/PKG-INFO +74 -24
  2. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/README.md +72 -23
  3. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/__init__.py +781 -745
  4. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/api_hooks.py +7 -5
  5. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/command_learner.py +59 -5
  6. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/config.py +129 -114
  7. nonebot_plugin_aigf_master-2.0.0b5/nonebot_plugin_aigf_master/effect_store.py +60 -0
  8. {nonebot_plugin_aigf_master-2.0.0b3 → 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.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/meme_store.py +30 -9
  12. {nonebot_plugin_aigf_master-2.0.0b3 → 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.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/plugin_invoker.py +47 -37
  16. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/processor.py +273 -85
  17. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/prompt_builder.py +587 -509
  18. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/search_client.py +82 -6
  19. {nonebot_plugin_aigf_master-2.0.0b3 → 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.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/unimsg.py +474 -453
  26. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/PKG-INFO +74 -24
  27. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/SOURCES.txt +8 -0
  28. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master.egg-info/requires.txt +1 -0
  29. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/pyproject.toml +5 -1
  30. nonebot_plugin_aigf_master-2.0.0b3/nonebot_plugin_aigf_master/llm_client.py +0 -118
  31. nonebot_plugin_aigf_master-2.0.0b3/nonebot_plugin_aigf_master/peer_client.py +0 -49
  32. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/LICENSE +0 -0
  33. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/anime_recognizer.py +0 -0
  34. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/animetrace_client.py +0 -0
  35. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/cache_cleanup.py +0 -0
  36. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/context_bus.py +0 -0
  37. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/image_gen_client.py +0 -0
  38. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/models.py +0 -0
  39. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/notice.py +0 -0
  40. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/plugin_discovery.py +0 -0
  41. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/preset_store.py +0 -0
  42. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/response_parser.py +0 -0
  43. {nonebot_plugin_aigf_master-2.0.0b3 → nonebot_plugin_aigf_master-2.0.0b5}/nonebot_plugin_aigf_master/vlm_client.py +0 -0
  44. {nonebot_plugin_aigf_master-2.0.0b3 → 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.0b3 → 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.0b3 → 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.0b3
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
@@ -55,7 +56,7 @@ Dynamic: license-file
55
56
  - 🧠 **LLM 命令学习**:通过观察群聊自动学习命令用法,支持学习、编辑、删除
56
57
  - 🌐 **跨 bot 通信**:通过 HTTP 获取其它 bot(同一 QQ 号下)的插件输出,并可远程调用其命令
57
58
  - 🖼️ **表情包功能**:AI 自主决定发表情包;自动从群聊中收藏
58
- - 🔍 **联网搜索**:支持 Tavily / Bocha / Bing,自动搜索不懂的梗和网络用语
59
+ - 🔍 **联网搜索**:支持 Tavily / Bocha / Bing / DeepSeek / 本地 open-websearch,自动搜索不懂的梗和网络用语
59
60
  - 🧠 **四层记忆系统**:短期记忆、长期记忆、群友信息、文化记忆,LLM 自主管理
60
61
  - 🎨 **AI 生图**:LLM可调用生图模型生成图片发到群里,尺寸由 LLM 决定(程序限最大尺寸),支持参考图改绘(回复图片消息或从聊天记录选图)
61
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.0b3)
84
+ ### 安装 beta 版本(2.0.0b5)
84
85
 
85
- `2.0.0b3` 是**预发布(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.0b3
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)
@@ -158,10 +160,11 @@ AIGFM_ENERGY_BASELINE=0.7 # 社交能量基线(默认 0.7,范
158
160
 
159
161
  # --- 联网搜索 ---
160
162
  AIGFM_SEARCH_ENABLED=false # 是否启用联网搜索(默认 false)
161
- AIGFM_SEARCH_API=tavily # 搜索API: tavily / bocha / bing / openwebsearch(默认 tavily)
162
- AIGFM_SEARCH_API_KEY="xxx" # 搜索 API Key(api=tavily/bocha/bing 时必填)
163
+ AIGFM_SEARCH_API=tavily # 搜索API: tavily / bocha / bing / openwebsearch / deepseek(默认 tavily)
164
+ AIGFM_SEARCH_API_KEY="xxx" # 搜索 API Key(api=tavily/bocha/bing 时必填;deepseek 留空则沿用 LLM Key)
163
165
  AIGFM_SEARCH_MAX_RESULTS=3 # 最大搜索结果数(默认 3)
164
166
  AIGFM_OPENWEBSEARCH_URL="" # open-websearch 本地服务地址(api=openwebsearch 时必填,如 http://127.0.0.1:3210)
167
+ AIGFM_SEARCH_BASE_URL="" # 搜索 API 根地址(api=deepseek 时用,留空则用官方 https://api.deepseek.com)
165
168
 
166
169
  # --- 代理 ---
167
170
  AIGFM_PROXY_ENABLED=false # 是否启用代理(默认 false)
@@ -248,7 +251,7 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
248
251
  - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_123456789`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
249
252
  - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
250
253
 
251
- ### 功能 × 适配器支持表(2026-09-25 实测)
254
+ ### 功能 × 适配器支持表(2026-11-12 离线复核,本地未发布改动)
252
255
 
253
256
  为每个适配器**构造真实事件**跑同一套功能路径(会话解析 → 渲染 → 回复发送 → 跨插件捕获 → 插件调用),bot 是记录型 mock,**未连真实平台**。
254
257
 
@@ -257,30 +260,34 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
257
260
  | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
258
261
  | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
259
262
  | Console | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
260
- | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
263
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
261
264
  | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
262
265
  | Discord | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
263
266
  | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
264
- | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
267
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
265
268
  | Milky | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
266
269
  | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
267
- | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
270
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
268
271
  | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
269
- | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ❌ | ✅ |
272
+ | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
270
273
  | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
271
274
  | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
272
275
  | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
273
- | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
276
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
274
277
  | YunHu | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
275
278
  | bilibili Live | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
276
279
 
277
- 图例:**✅ 已实测通过** | **⚠️ 已实现但未验证通过**(离线构造不出该适配器的事件,或需要真实 API / 真机)| **❌ 该适配器没有这类事件,或库层无法把该通知定位到群/频道会话(通知会被跳过)** | **未测** 本次未构造该场景。
280
+ **图例:**
281
+ - **✅ 已实测通过**
282
+ - **⚠️ 已实现但未验证通过**(离线构造不出该适配器的事件,或需要真实 API / 真机)
283
+ - **❌ 该适配器没有这类事件,或库层无法把该通知定位到群/频道会话(通知会被跳过)**
284
+ - **未测** 本次未构造该场景。
278
285
 
279
286
  **已知特例**
280
287
 
281
288
  - **@ 按昵称**:只有 OneBot V11 能按群昵称反查用户 id,其余适配器请让 LLM 直接用用户 id
282
- - **插件调用**:Satori / Kaiheila 的事件结构特殊,离线未验证通过;其余 14 个已实测目标响应器收到命令
283
- - **群通知**:为每个适配器构造真实通知事件实测,**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)。
284
291
  - **YunHu / bilibili Live**:需要把 bot 跑在 **Python ≥ 3.12**(3.10 里导入即失败;这两行的 ✅ 是在 3.14 实测的)
285
292
  - **Kaiheila**:请装 `nonebot-adapter-kaiheila`(社区包 `nonebot-adapter-kook` 的模块名与 alconna/uninfo 期望的不一致)
286
293
  - **跨 bot**:按 peer 0.4.0+ 的 `session` 协议可用;旧 peer(0.3.x)只有 OneBot V11 的会话能对上
@@ -406,6 +413,7 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
406
413
 
407
414
  | 限制 | 默认 | 配置项 |
408
415
  |---|---|---|
416
+ | **每批调用尝试上限** | 1(本机与 peer 共用) | `AIGFM_INVOKE_MAX_PER_BATCH`(正整数,含 JSON 解析重试) |
409
417
  | **重复调用去重** | 开启 | `AIGFM_INVOKE_DEDUP_ENABLED` |
410
418
  | **去重时间窗口** | 20 分钟 | `AIGFM_INVOKE_DEDUP_WINDOW`(秒;0 = 不限时间) |
411
419
  | **去重比对条数** | 15 | `AIGFM_INVOKE_DEDUP_RECORDS` |
@@ -414,12 +422,19 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
414
422
 
415
423
  - 去重判定为**命令 + 参数 + 调用身份(QQ 号)三者完全相同**;拦截范围 = **时间窗口内**(`AIGFM_INVOKE_DEDUP_WINDOW`)∩ **调用台账保留的最近 N 条**(`AIGFM_INVOKE_DEDUP_RECORDS`)
416
424
  - **不区分本机与其它 bot**:同一命令、同一身份在范围内只执行一次
417
- - 换个参数(`决斗 @张三` → `决斗 @李四`)或换个身份(不同 QQ 号)视为不同调用,正常放行
425
+ - 换参数或身份不命中相同调用去重,但仍受每批共享额度与能量限制;明确未投递的尝试也占本批额度,下一批重新计算
418
426
  - prompt 里的「你最近代为执行过的命令」段只展示**其中最近 10 条**(防止 prompt 随条数膨胀)
419
427
  - 执行 `/reset` 会一并清空调用台账(重置后不再被"刚调用过"挡住)
420
- - 每次**实际投递**扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量(被拒绝时不扣);能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
428
+ - 已投递、peer 已接收及投递结果不确定时,扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量并写入去重台账;明确未投递和前置拒绝不扣能量、不写去重台账;能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
421
429
  - 被拒绝时:工具结果**当场**告知 LLM 原因,同时在聊天记录里留下 `已拒绝调用命令「xxx」(原因)`,**下一轮** LLM 能看到;拒绝**不写入调用台账**(不会阻止之后真正的再调用)
422
430
 
431
+ ### 调用回执与身份
432
+
433
+ 回执区分未投递、本机已投递、peer 已接收、结果不确定。peer 的 HTTP `ok: true` 只表示请求已被接收;超时、分发异常、读写超时不证明没有执行,因此保留去重。后续没有输出也不能直接断定成功或失败。
434
+ 每次投递尝试附带请求编号,供本机日志、工具回执和台账相互核对;编号尚不随 peer 输出回传,也不自动将输出判定为某次命令执行成功。
435
+ 本批调用使用批处理开始时保存的 bot、会话、真实事件和默认用户身份;等待 LLM 期间到达的新消息不会替换这些调用依据。显式指定 user_id 的能力保持原样。
436
+ 搜索、插件调用和生图按各自开关进入工具路径,关闭搜索不会关闭后两者。本批调用额度仅限制 `invoke_plugin` 与 `invoke_peer_plugin`,不包含搜索或生图任务。
437
+
423
438
  ### 命令前缀自动适配
424
439
 
425
440
  - LLM 调用命令时**始终传不带前缀的命令**(如 `今日小猪`)
@@ -559,6 +574,7 @@ LLM 可以:
559
574
  | `bocha` | 国产 AI 搜索 API,中文搜索效果好 | 无 | https://open.bochaai.com |
560
575
  | `bing` | 微软必应搜索(Azure Bing Search API v7) | 无 | https://portal.azure.com |
561
576
  | `openwebsearch` | 本地 Node.js 搜索服务,聚合多引擎(bing/baidu/duckduckgo 等) | 需先启动 daemon:`cd open-webSearch && npm install && npm run serve`,配置 `AIGFM_OPENWEBSEARCH_URL` | 无需 Key,项目:https://github.com/Aas-ee/open-webSearch |
577
+ | `deepseek` | DeepSeek 自带联网搜索,摘要写得很适合喂给模型 | 无(`AIGFM_SEARCH_API_KEY` 留空则沿用 LLM Key) | https://platform.deepseek.com |
562
578
 
563
579
  > **Tavily** 需额外安装依赖:`pip install tavily-python`(或安装本插件时带上 extra:`pip install "nonebot-plugin-aigf-master[tavily]"`)
564
580
 
@@ -659,8 +675,18 @@ memes/
659
675
 
660
676
  | 模式 | 流程 | 适用场景 |
661
677
  |------|------|---------|
662
- | `vlm`(默认) | 图片 → VLM 分析 → 文字描述给 LLM | LLM 不支持图片输入 |
663
- | `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 请求发送(此前工具路径会漏掉图片)
664
690
 
665
691
  `vlm` 模式下的行为说明:
666
692
 
@@ -758,9 +784,11 @@ LLM 支持以下回复类型:
758
784
  | 类型 | 格式 | 说明 |
759
785
  |------|------|------|
760
786
  | 文本 | `{"type": "text", "content": "..."}` | 纯文本消息 |
761
- | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友 |
787
+ | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友(也可填群名片或 QQ 号) |
762
788
  | 表情包 | `{"type": "meme", "id": "表情包id"}` | 发送表情包 |
763
789
 
790
+ > 要 @ 群友时应使用独立的 `at` 段。为兼容部分模型误把 `@昵称` 写进文本的情况,发送前也会把能匹配到群成员的文本 @(含群名片、QQ 号写法)自动转换为真实 QQ @;重名成员不自动转换,避免误 @ 到别人。
791
+
764
792
  ## 📁 数据存储
765
793
 
766
794
  ```
@@ -811,3 +839,25 @@ LLM 支持以下回复类型:
811
839
  ## License
812
840
 
813
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)。
@@ -33,7 +33,7 @@
33
33
  - 🧠 **LLM 命令学习**:通过观察群聊自动学习命令用法,支持学习、编辑、删除
34
34
  - 🌐 **跨 bot 通信**:通过 HTTP 获取其它 bot(同一 QQ 号下)的插件输出,并可远程调用其命令
35
35
  - 🖼️ **表情包功能**:AI 自主决定发表情包;自动从群聊中收藏
36
- - 🔍 **联网搜索**:支持 Tavily / Bocha / Bing,自动搜索不懂的梗和网络用语
36
+ - 🔍 **联网搜索**:支持 Tavily / Bocha / Bing / DeepSeek / 本地 open-websearch,自动搜索不懂的梗和网络用语
37
37
  - 🧠 **四层记忆系统**:短期记忆、长期记忆、群友信息、文化记忆,LLM 自主管理
38
38
  - 🎨 **AI 生图**:LLM可调用生图模型生成图片发到群里,尺寸由 LLM 决定(程序限最大尺寸),支持参考图改绘(回复图片消息或从聊天记录选图)
39
39
 
@@ -58,9 +58,9 @@
58
58
  >
59
59
  > 从 2.0 起插件还依赖 `nonebot-plugin-alconna` 与 `nonebot-plugin-uninfo`(跨适配器收发与会话/成员信息),用下面的方式安装时会自动装上。
60
60
 
61
- ### 安装 beta 版本(2.0.0b3)
61
+ ### 安装 beta 版本(2.0.0b5)
62
62
 
63
- `2.0.0b3` 是**预发布(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.0b3
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)
@@ -136,10 +137,11 @@ AIGFM_ENERGY_BASELINE=0.7 # 社交能量基线(默认 0.7,范
136
137
 
137
138
  # --- 联网搜索 ---
138
139
  AIGFM_SEARCH_ENABLED=false # 是否启用联网搜索(默认 false)
139
- AIGFM_SEARCH_API=tavily # 搜索API: tavily / bocha / bing / openwebsearch(默认 tavily)
140
- AIGFM_SEARCH_API_KEY="xxx" # 搜索 API Key(api=tavily/bocha/bing 时必填)
140
+ AIGFM_SEARCH_API=tavily # 搜索API: tavily / bocha / bing / openwebsearch / deepseek(默认 tavily)
141
+ AIGFM_SEARCH_API_KEY="xxx" # 搜索 API Key(api=tavily/bocha/bing 时必填;deepseek 留空则沿用 LLM Key)
141
142
  AIGFM_SEARCH_MAX_RESULTS=3 # 最大搜索结果数(默认 3)
142
143
  AIGFM_OPENWEBSEARCH_URL="" # open-websearch 本地服务地址(api=openwebsearch 时必填,如 http://127.0.0.1:3210)
144
+ AIGFM_SEARCH_BASE_URL="" # 搜索 API 根地址(api=deepseek 时用,留空则用官方 https://api.deepseek.com)
143
145
 
144
146
  # --- 代理 ---
145
147
  AIGFM_PROXY_ENABLED=false # 是否启用代理(默认 false)
@@ -226,7 +228,7 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
226
228
  - 落盘目录名不能含 `:`,因此磁盘上写作 `onebot11_123456789`;`memory/` 下旧版裸数字目录会在启动时**一次性自动迁移**(目标已存在则跳过,幂等)
227
229
  - 非启用会话不发请求、不入缓冲:插件只会为启用的会话解析成员信息与图片
228
230
 
229
- ### 功能 × 适配器支持表(2026-09-25 实测)
231
+ ### 功能 × 适配器支持表(2026-11-12 离线复核,本地未发布改动)
230
232
 
231
233
  为每个适配器**构造真实事件**跑同一套功能路径(会话解析 → 渲染 → 回复发送 → 跨插件捕获 → 插件调用),bot 是记录型 mock,**未连真实平台**。
232
234
 
@@ -235,30 +237,34 @@ AIGFM_PEER_CAPTURE_PLUGINS=[] # 要捕获输出的插件名列表,为
235
237
  | OneBot V11 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
236
238
  | OneBot V12 | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
237
239
  | Console | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
238
- | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
240
+ | Satori | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
239
241
  | Telegram | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
240
242
  | Discord | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
241
243
  | QQ(频道/C2C/群) | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
242
- | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
244
+ | Feishu | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
243
245
  | Milky | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
244
246
  | Mirai | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
245
- | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ⚠️ | ✅ | ✅ |
247
+ | Kaiheila(Kook) | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
246
248
  | DoDo | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
247
- | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ❌ | ✅ |
249
+ | Kritor | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
248
250
  | Mail | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
249
251
  | Minecraft | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
250
252
  | WXMP | ✅(仅私聊) | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
251
- | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ✅ |
253
+ | EFChat | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | ✅ | ✅ | ✅ |
252
254
  | YunHu | ✅ | ✅ | ✅ | 未测 | ⚠️ | ✅ | ✅ | ✅ | ✅ |
253
255
  | bilibili Live | ✅ | ✅ | ✅ | ❌ 无好友私聊类型 | ⚠️ | ✅ | ✅ | ⚠️ | ✅ |
254
256
 
255
- 图例:**✅ 已实测通过** | **⚠️ 已实现但未验证通过**(离线构造不出该适配器的事件,或需要真实 API / 真机)| **❌ 该适配器没有这类事件,或库层无法把该通知定位到群/频道会话(通知会被跳过)** | **未测** 本次未构造该场景。
257
+ **图例:**
258
+ - **✅ 已实测通过**
259
+ - **⚠️ 已实现但未验证通过**(离线构造不出该适配器的事件,或需要真实 API / 真机)
260
+ - **❌ 该适配器没有这类事件,或库层无法把该通知定位到群/频道会话(通知会被跳过)**
261
+ - **未测** 本次未构造该场景。
256
262
 
257
263
  **已知特例**
258
264
 
259
265
  - **@ 按昵称**:只有 OneBot V11 能按群昵称反查用户 id,其余适配器请让 LLM 直接用用户 id
260
- - **插件调用**:Satori / Kaiheila 的事件结构特殊,离线未验证通过;其余 14 个已实测目标响应器收到命令
261
- - **群通知**:为每个适配器构造真实通知事件实测,**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)。
262
268
  - **YunHu / bilibili Live**:需要把 bot 跑在 **Python ≥ 3.12**(3.10 里导入即失败;这两行的 ✅ 是在 3.14 实测的)
263
269
  - **Kaiheila**:请装 `nonebot-adapter-kaiheila`(社区包 `nonebot-adapter-kook` 的模块名与 alconna/uninfo 期望的不一致)
264
270
  - **跨 bot**:按 peer 0.4.0+ 的 `session` 协议可用;旧 peer(0.3.x)只有 OneBot V11 的会话能对上
@@ -384,6 +390,7 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
384
390
 
385
391
  | 限制 | 默认 | 配置项 |
386
392
  |---|---|---|
393
+ | **每批调用尝试上限** | 1(本机与 peer 共用) | `AIGFM_INVOKE_MAX_PER_BATCH`(正整数,含 JSON 解析重试) |
387
394
  | **重复调用去重** | 开启 | `AIGFM_INVOKE_DEDUP_ENABLED` |
388
395
  | **去重时间窗口** | 20 分钟 | `AIGFM_INVOKE_DEDUP_WINDOW`(秒;0 = 不限时间) |
389
396
  | **去重比对条数** | 15 | `AIGFM_INVOKE_DEDUP_RECORDS` |
@@ -392,12 +399,19 @@ LLM 调用:invoke_plugin(command="决斗", parts=[
392
399
 
393
400
  - 去重判定为**命令 + 参数 + 调用身份(QQ 号)三者完全相同**;拦截范围 = **时间窗口内**(`AIGFM_INVOKE_DEDUP_WINDOW`)∩ **调用台账保留的最近 N 条**(`AIGFM_INVOKE_DEDUP_RECORDS`)
394
401
  - **不区分本机与其它 bot**:同一命令、同一身份在范围内只执行一次
395
- - 换个参数(`决斗 @张三` → `决斗 @李四`)或换个身份(不同 QQ 号)视为不同调用,正常放行
402
+ - 换参数或身份不命中相同调用去重,但仍受每批共享额度与能量限制;明确未投递的尝试也占本批额度,下一批重新计算
396
403
  - prompt 里的「你最近代为执行过的命令」段只展示**其中最近 10 条**(防止 prompt 随条数膨胀)
397
404
  - 执行 `/reset` 会一并清空调用台账(重置后不再被"刚调用过"挡住)
398
- - 每次**实际投递**扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量(被拒绝时不扣);能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
405
+ - 已投递、peer 已接收及投递结果不确定时,扣 `AIGFM_INVOKE_ENERGY_COST` 点社交能量并写入去重台账;明确未投递和前置拒绝不扣能量、不写去重台账;能量会按社交能量机制自然回充,所以能量不足只是暂时无法代为执行命令
399
406
  - 被拒绝时:工具结果**当场**告知 LLM 原因,同时在聊天记录里留下 `已拒绝调用命令「xxx」(原因)`,**下一轮** LLM 能看到;拒绝**不写入调用台账**(不会阻止之后真正的再调用)
400
407
 
408
+ ### 调用回执与身份
409
+
410
+ 回执区分未投递、本机已投递、peer 已接收、结果不确定。peer 的 HTTP `ok: true` 只表示请求已被接收;超时、分发异常、读写超时不证明没有执行,因此保留去重。后续没有输出也不能直接断定成功或失败。
411
+ 每次投递尝试附带请求编号,供本机日志、工具回执和台账相互核对;编号尚不随 peer 输出回传,也不自动将输出判定为某次命令执行成功。
412
+ 本批调用使用批处理开始时保存的 bot、会话、真实事件和默认用户身份;等待 LLM 期间到达的新消息不会替换这些调用依据。显式指定 user_id 的能力保持原样。
413
+ 搜索、插件调用和生图按各自开关进入工具路径,关闭搜索不会关闭后两者。本批调用额度仅限制 `invoke_plugin` 与 `invoke_peer_plugin`,不包含搜索或生图任务。
414
+
401
415
  ### 命令前缀自动适配
402
416
 
403
417
  - LLM 调用命令时**始终传不带前缀的命令**(如 `今日小猪`)
@@ -537,6 +551,7 @@ LLM 可以:
537
551
  | `bocha` | 国产 AI 搜索 API,中文搜索效果好 | 无 | https://open.bochaai.com |
538
552
  | `bing` | 微软必应搜索(Azure Bing Search API v7) | 无 | https://portal.azure.com |
539
553
  | `openwebsearch` | 本地 Node.js 搜索服务,聚合多引擎(bing/baidu/duckduckgo 等) | 需先启动 daemon:`cd open-webSearch && npm install && npm run serve`,配置 `AIGFM_OPENWEBSEARCH_URL` | 无需 Key,项目:https://github.com/Aas-ee/open-webSearch |
554
+ | `deepseek` | DeepSeek 自带联网搜索,摘要写得很适合喂给模型 | 无(`AIGFM_SEARCH_API_KEY` 留空则沿用 LLM Key) | https://platform.deepseek.com |
540
555
 
541
556
  > **Tavily** 需额外安装依赖:`pip install tavily-python`(或安装本插件时带上 extra:`pip install "nonebot-plugin-aigf-master[tavily]"`)
542
557
 
@@ -637,8 +652,18 @@ memes/
637
652
 
638
653
  | 模式 | 流程 | 适用场景 |
639
654
  |------|------|---------|
640
- | `vlm`(默认) | 图片 → VLM 分析 → 文字描述给 LLM | LLM 不支持图片输入 |
641
- | `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 请求发送(此前工具路径会漏掉图片)
642
667
 
643
668
  `vlm` 模式下的行为说明:
644
669
 
@@ -736,9 +761,11 @@ LLM 支持以下回复类型:
736
761
  | 类型 | 格式 | 说明 |
737
762
  |------|------|------|
738
763
  | 文本 | `{"type": "text", "content": "..."}` | 纯文本消息 |
739
- | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友 |
764
+ | @ | `{"type": "at", "name": "群友昵称"}` | 艾特群友(也可填群名片或 QQ 号) |
740
765
  | 表情包 | `{"type": "meme", "id": "表情包id"}` | 发送表情包 |
741
766
 
767
+ > 要 @ 群友时应使用独立的 `at` 段。为兼容部分模型误把 `@昵称` 写进文本的情况,发送前也会把能匹配到群成员的文本 @(含群名片、QQ 号写法)自动转换为真实 QQ @;重名成员不自动转换,避免误 @ 到别人。
768
+
742
769
  ## 📁 数据存储
743
770
 
744
771
  ```
@@ -789,3 +816,25 @@ LLM 支持以下回复类型:
789
816
  ## License
790
817
 
791
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)。