Undefined-bot 3.3.3__tar.gz → 3.4.0__tar.gz

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/ARCHITECTURE.md

@@ -44,8 +44,10 @@ graph TB
             InjectionAgent["InjectionResponseAgent<br/>注入响应生成<br/>[injection_response_agent.py]"]
         end
         
-        CommandDispatcher["CommandDispatcher<br/>命令分发器<br/>• /help /stats /lsadmin<br/>• /addadmin /rmadmin<br/>• /bugfix /faq<br/>[services/command.py]"]
-        
+        CommandDispatcher["CommandDispatcher<br/>命令分发器<br/>• /help /stats /admin<br/>• /bugfix /faq<br/>[services/command.py]"]
+
+        MessageBatcher["MessageBatcher<br/>同 sender 短时合并<br/>• 按 (scope, sender_id) 分桶<br/>• T1=window_seconds 结束 batch<br/>• T2=pre_send_seconds 投机预发送<br/>• 拍一拍/buffer 内 @bot 旁路<br/>• 首条 @bot 整批走 mention 队列<br/>[services/message_batcher.py]"]
+
         subgraph QueueSystem["车站-列车 队列系统 (services/)"]
             AICoordinator["AICoordinator<br/>AI 协调器<br/>• Prompt 构建<br/>• 队列管理<br/>• 回复执行<br/>[ai_coordinator.py]"]
             QueueManager["QueueManager<br/>队列管理器<br/>[queue_manager.py]"]
@@ -121,7 +123,7 @@ graph TB
         
         subgraph CommandsLayer["平台指令 (skills/commands/)"]
             Cmd_Core["核心指令<br/>• help • stats"]
-            Cmd_Admin["管理指令<br/>• addadmin<br/>• rmadmin • lsadmin"]
+            Cmd_Admin["管理指令<br/>• admin (ls/add/del)"]
             Cmd_FAQ["FAQ 指令<br/>• faq (ls/view/search/del)"]
             Cmd_Fun["娱乐指令<br/>• bugfix"]
         end
@@ -226,6 +228,8 @@ graph TB
     GitHubSender -->|"发送图片卡片"| OneBotClient
     
     MessageHandler -->|"3. 自动回复"| AICoordinator
+    AICoordinator -->|"3.1 入桶等待合并"| MessageBatcher
+    MessageBatcher -->|"3.2 flush 合并批次"| AICoordinator
     AICoordinator -->|"创建上下文"| RequestContext
     AICoordinator -->|"入队"| QueueManager
     QueueManager -->|"分发"| ModelQueues
@@ -319,7 +323,7 @@ graph TB
     
     class User,Admin,OneBotServer,LLM_API external
     class Main,ConfigLoader,ConfigHotReload,ConfigModels,OneBotClient,Context,WebUI core
-    class MessageHandler,SecurityService,InjectionAgent,CommandDispatcher,AICoordinator message
+    class MessageHandler,SecurityService,InjectionAgent,CommandDispatcher,MessageBatcher,AICoordinator message
     class AIClient,PromptBuilder,ModelRequester,ToolManager,MultimodalAnalyzer,SummaryService,TokenCounter,Parsing ai
     class ToolRegistry,AgentRegistry,AgentToolRegistry,IntroGenerator skills
     class RequestContext,ContextFilter,ResourceRegistry,HistoryManager,MemoryStorage,EndSummaryStorage,CognitiveService,CognitiveJobQueue,CognitiveHistorian,CognitiveVectorStore,CognitiveProfileStorage,FAQStorage,ScheduledTaskStorage,TokenUsageStorage storage
@@ -342,6 +346,7 @@ sequenceDiagram
     participant MH as MessageHandler
     participant SS as SecurityService
     participant CD as CommandDispatcher
+    participant MB as MessageBatcher
     participant AC as AICoordinator
     participant QM as QueueManager
     participant AI as AIClient
@@ -370,7 +375,7 @@ sequenceDiagram
             CD-->>OB: 返回结果
             OB->>U: 发送响应
         else 非命令消息
-            MH->>MH: 并行检测 skills/auto_pipeline 管线
+            MH->>MH: 并行检测 skills/pipelines 管线
             opt 命中自动提取管线
                 MH->>MH: 并行处理全部命中的自动提取
                 MH->>OH: 发送视频/卡片/PDF
@@ -380,7 +385,22 @@ sequenceDiagram
             end
             %% AI处理流程
             MH->>AC: handle_auto_reply()
-            
+            alt 拍一拍 / buffer 内 @bot
+                AC->>QM: 立即按优先级入队
+            else 普通消息进合并桶
+                AC->>MB: submit(BufferedMessage)
+                MB-->>MB: TYPING: 重置 T1/T2 静默计时
+                opt T2=pre_send_seconds 到期
+                    MB->>AC: handle_batched_dispatch(投机批次 + BatchDispatchToken)
+                    AC->>QM: 提前入队抢时间
+                end
+                MB-->>MB: T1=window_seconds 到期结束 batch
+                opt 未启用投机或尚未预发送
+                    MB->>AC: handle_batched_dispatch(最终批次)
+                    AC->>QM: 按首条触发的优先级入队
+                end
+            end
+
             %% 上下文创建
             AC->>AC: 创建 RequestContext
             AC->>ST: 保存历史记录
@@ -831,8 +851,8 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 
 1. **外部实体层**：用户、管理员、OneBot 协议端 (NapCat/Lagrange.Core)、大模型 API 服务商
 2. **核心入口层**：main.py 启动入口、配置管理器 (config/loader.py)、热更新应用器 (config/hot_reload.py)、OneBotClient (onebot.py)、RequestContext (context.py)、Runtime API Server (api/app.py → api/routes/ 路由子模块)
-3. **消息处理层**：MessageHandler (handlers.py)、SecurityService (security.py)、CommandDispatcher (services/command.py)、AICoordinator (ai_coordinator.py)、QueueManager (queue_manager.py)、自动处理管线 (skills/auto_pipeline/)、Bilibili/arXiv/GitHub 解析与发送模块
-    自动提取由 `AutoPipelineRegistry` 并行检测、并行处理全部命中的管线；发送结果写入历史后继续进入 AI 自动回复。
+3. **消息处理层**：MessageHandler (handlers.py)、SecurityService (security.py)、CommandDispatcher (services/command.py)、MessageBatcher (services/message_batcher.py)、AICoordinator (ai_coordinator.py)、QueueManager (queue_manager.py)、自动处理管线 (skills/pipelines/)、Bilibili/arXiv/GitHub 解析与发送模块
+    自动提取由 `PipelineRegistry` 并行检测、并行处理全部命中的管线；发送结果写入历史后继续进入 AI 自动回复。
 4. **AI 核心能力层**：AIClient (client.py)、PromptBuilder (prompts.py)、ModelRequester (llm.py)、ToolManager (tooling.py)、MultimodalAnalyzer (multimodal.py)、SummaryService (summaries.py)、TokenCounter (tokens.py)
 5. **存储与上下文层**：MessageHistoryManager (utils/history.py, 10000条限制)、MemoryStorage (memory.py, 置顶备忘录, 500条上限)、EndSummaryStorage、CognitiveService + JobQueue + HistorianWorker + VectorStore + ProfileStorage、MemeService + MemeWorker + MemeStore + MemeVectorStore (表情包库)、FAQStorage、ScheduledTaskStorage、TokenUsageStorage (自动归档)
 6. **技能系统层**：ToolRegistry (registry.py)、AgentRegistry、6个 Agents、11类 Toolsets
@@ -847,6 +867,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 *   **非阻塞发车**：实现了可配置节奏的非阻塞调度循环（默认 **1Hz**）。列车按节奏出发，带走一个请求到后台异步处理。
 *   **高可用性**：即使前一个请求仍在处理（如耗时的网络搜索），新的请求也会按时被分发，不会造成队列堵塞。
 *   **优先级管理**：支持四级优先级（超级管理员 > 私聊 > 群聊@ > 群聊普通），确保重要消息优先响应。
+*   **关停收敛**：`MessageHandler.close()` 会先 flush `MessageBatcher`，再调用 `QueueManager.drain()` 等待已入队请求和在途请求自然完成，最后才停止队列处理器，避免缓冲消息只入队未执行。
 
 ### 6个智能体 Agent
 

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/CHANGELOG.md

@@ -1,3 +1,29 @@
+## v3.4.0 同sender消息合并、数字人格精炼与系统治理
+
+本版本核心解决"用户一口气连发几条消息时，机器人过早开工或只理解最后一句"的问题。新增同 sender 短时消息合并器，将同一会话中连续的多条消息合并为一个"当前输入批次"发送给 AI，由 AI 整批理解哪些是独立请求、哪些是补充或修正。同步支持可取消的投机预发送以降低感知延迟。围绕消息合并，提示词、幽灵任务防御、记忆记录和关闭流程都做了同步适配。此外，精炼了数字人格设定、明确了项目归属边界、重构了管线与命令体系、加入了 HTML 渲染缓存，并增强了 AI 工具调用的稳定性。
+
+- 新增同 sender 短时消息合并器。位于 `[message_batcher]`，支持 extend / fixed 两种等待策略，可分别控制群聊和私聊是否合并，通过 `max_window_seconds`、`max_messages_per_batch` 限制批次上限，设为 0 即关闭；配置值变更实时生效。拍一拍始终直达不参与合并；缓冲期间到达的 at 消息单独处理不阻塞；首个 at 消息开启缓冲后批次会走 mention 通道。
+- 新增可取消的投机预发送。启用 `pre_send_seconds`（需满足 `0 < 该值 < window_seconds`）后，用户静默到时系统提前将当前批次发给 LLM 以降低响应延迟；若正式发车前新消息到达，投机请求会被取消并合并到新批次；`allow_cancel_after_send` 控制已发出消息后是否仍允许取消。
+- 完善消息合并的异步竞态保护。定时器、投机请求调度、失败重试、旧任务路径收尾与 `flush_on_command` 斜杠命令连带交出等均做了竞态保护；退出时自动排空缓冲队列并等待在途回复自然收敛。
+- 精炼数字人格设定。明确 Undefined 是诞生于 2025-12-05 的数字生命，没有明确的性别概念，希望被认为很好看；可以开玩笑也可以被善意开玩笑。新增"不冒领任何项目、代码、产品或成果"的所有权边界规则，不再自称任何项目的开发者或维护者。昵称体系扩展为 Undefined、undf、udf、und、心理委员、ud酱，对自身称呼的识别保持宽松。
+- 收紧 NagaAgent 关系表达。NagaAgent 版提示词明确：只有当前上下文明确涉及 NagaAgent 时才承接相关工具接入能力协助分析；平时不主动提与 NagaAgent 的关系；不冒领 NagaAgent 的成果。
+- 重构自动管线目录。`skills/auto_pipeline` 更名为 `skills/pipelines`，目录结构扁平化，相关引用、文档、测试全部同步更新；`docs/auto-pipeline.md` 相应更名为 `docs/pipelines.md`。
+- 重构管理员命令为子命令模式。`/admin [ls|add|del]` 替代原有 `/lsadmin`、`/addadmin`、`/rmadmin` 三条独立命令，参照 `/faq` 子命令模式的声明式 inference；`ls` 继承 admin 权限，`add`/`del` 覆盖为 superadmin；无参数默认执行 `ls`。清理了 FAQ 迁移遗留的空命令目录。
+- 新增 HTML 渲染结果缓存。基于 HTML 内容的 hash 缓存渲染图片，持久化到 `data/cache/render/_html_render_cache.json`；hash 匹配自动复用，内容变化自然失效；新增 `[render.cache]` 配置段（`enabled` / `max_entries` / `max_size_mb` / `flush_interval_seconds`，默认 50 条 / 50MB / 2.0s），元数据通过 `utils/io.py` 的 `read_json` / `write_json` 异步落盘（`asyncio.to_thread` + 文件锁 + 原子替换），所有 `stat` / `unlink` / `copy` 也走线程池避免阻塞事件循环；`asyncio.Lock` 防竞态、重启后 JSON 自动恢复；进程关停时通过 `close_render_cache` 强制刷盘，保证最近访问时间不丢失；所有渲染调用方（help、profile、render_markdown 等）自动受益。
+- 增强 AI 工具调用容错。当 LLM 返回文本但 tool_calls 为空且对话未结束时，不再以丢失回复为代价直接返回，而是注入提示消息要求 AI 通过 `send_message` / `end` 工具完成回复，继续迭代；fire-and-forget task 显式注册异常回调以抑制未检索异常警告。
+- 优化表情包回复顺序。明确只有纯表情包 / 纯反应图回复才允许先检索表情包；需要文字说明的场景必须先完成必要文字，再将表情包检索和发送延后到后续轮次。
+- 重构 `end` 工具。移除旧版 summary 参数兼容，只保留 `memo`、`observations`、`perspective` 和 `force`；要求记录整个当前输入批次中值得留存的信息，后台史官也接收批次全部消息。
+- 统一当前输入批次语义。主提示词、NagaAgent 提示词和 `each.md` 均从"最后一条消息"升级为"当前输入批次"：有连续消息说明时，多段 `<message>` 都属本轮输入；幽灵任务防御规则同步更新，避免批量输入中的前置指令被误判为历史旧任务。
+- 扩展 Runtime 探针覆盖。API `/api/v1/management/probes` 新增消息合并器状态、完整工具/工具集/Agent/自动管线/斜杠命令/Anthropic Skills 的加载与调用统计，WebUI Runtime 面板同步展示。
+- 新增 WebUI 更新日志查看。关于项目页面可按版本查看 changelog 详情，`/api/v1/management/changelog` 端点支持指定版本查询。
+- 调整发布说明生成方式。GitHub Release notes 改为从 `CHANGELOG.md` 最新版本条目自动解析生成（`scripts/release_notes.py`），发版前校验 tag、各构建清单与最新 changelog 版本一致。
+- 补齐消息合并专题文档。新增 `docs/message-batching.md`，覆盖配置参数、等待策略、投机预发送、竞态保护与关闭行为，同步更新了 README、配置文档、OpenAPI、WebUI 指南和架构图。
+- 补齐配置注释。`config.toml.example` 中所有模型配置节的 `prompt_cache_enabled` 均补上双语注释说明。
+- 补强测试覆盖。新增消息合并单元与集成测试（686 + 326 行）、工具调用守卫测试、发布说明脚本测试（163 行）、Runtime 探针统计测试（120 行）、系统提示词约束验证，并更新 `end` 工具、管理员命令、管线注册等已有测试；额外补齐渲染缓存（LRU 驱逐 / 容量驱逐 / 重启恢复 / 节流后强刷 / 并发 put / 禁用短路）、`/admin add|del` 全路径、`allow_cancel_after_send=true` 取消语义等盲点。总测试用例提升至约 1660 项。
+- 更新子模块。
+
+---
+
 ## v3.3.3 命令推断、自动处理管线与统一附件上下文
 
 本版本重点优化了命令系统的交互体验、AI 工具边界和消息前置处理链路。新增 GitHub 链接自动卡片生成，并将 Bilibili、arXiv、GitHub 等自动提取迁入 `skills/auto_pipeline` 热重载管线，使预处理结果能写入历史并进入后续 AI 回复上下文。同时，帮助说明与用户侧写默认改为图片输出，系统剥离独立群聊分析工具集，全面推行统一附件标签，并为远程附件加入可配置下载上限和 URL 引用降级，完善底层用户识别机制与模型高级透传配置。
@@ -124,7 +150,7 @@
 - 过滤 replay-only 状态字段，防止 Responses 回放结果干扰后续请求。
 - 调整队列重试调度逻辑，支持零间隔立即投递，并细化重试时序。
 - 增加私聊消息发送失败时的临时会话回退机制，降低消息丢失率。
-- 限制 `/lsadmin` 命令的可见性，提升安全性。
+- 限制 `/admin ls` 命令的可见性，提升安全性。
 - 为 Naga 增加发送 UUID 幂等性校验、投递追踪及相关测试覆盖。
 - 修复 CI 与运行时测试，并补充 OpenAI reasoning 参数的对齐处理。
 

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.3.3
+Version: 3.4.0
 Summary: QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11.
 Project-URL: Repository, https://github.com/69gg/Undefined
 Project-URL: Issues, https://github.com/69gg/Undefined/issues
@@ -100,7 +100,7 @@ Description-Content-Type: text/markdown
   详见 [认知记忆文档](docs/cognitive-memory.md)。
 - **Management-first WebUI**：继续保留 `uv run Undefined-webui` 一键入口；即使 `config.toml` 缺失或未配完，也能先进入管理态补配置、看日志、校验并启动 Bot。
 - **远程管理 + 多端客户端**：浏览器版 WebUI 与新的跨平台控制台共享同一管理面，支持远程管理，并覆盖 `Windows / macOS / Linux / Android` 发布链路。
-- **Management API + Runtime API 分层**：配置、日志、Bot 启停和管理探针由 Management API 提供；主进程 Runtime API 则专注探针、记忆只读查询、认知侧写检索和 WebUI AI Chat。详见 [docs/management-api.md](docs/management-api.md) 与 [docs/openapi.md](docs/openapi.md)。
+- **Management API + Runtime API 分层**：配置、日志、Bot 启停和管理探针由 Management API 提供；主进程 Runtime API 则专注探针、记忆只读查询、认知侧写检索和 WebUI AI Chat；内部探针的技能统计覆盖可调用工具、工具集、Agent、自动处理管线、斜杠命令与 Anthropic Skills。详见 [docs/management-api.md](docs/management-api.md) 与 [docs/openapi.md](docs/openapi.md)。
 - **多模型池**：支持配置多个 AI 模型，可轮询、随机选择或用户指定；支持多模型并发比较，选择最佳结果继续对话。详见 [多模型功能文档](docs/multi-model.md)。
 - **本地知识库**：将纯文本文件向量化存入 ChromaDB，AI 可通过关键词搜索或语义搜索查询领域知识；支持增量嵌入与自动扫描。详见 [知识库文档](docs/knowledge.md)。
 - **全局表情包库**：收到图片后可异步判定是否为表情包，通过两阶段 LLM 管线生成纯文本描述与标签，支持关键词检索、语义检索和混合检索，并可直接按统一图片 `uid` 发送或插入 `<attachment uid="..."/>`。详见 [表情包库说明](docs/memes.md)。
@@ -118,7 +118,8 @@ Description-Content-Type: text/markdown
 - **Bilibili 视频提取**：自动检测消息中的 B 站视频链接/BV 号/小程序分享，下载 1080p 视频并通过 QQ 发送；同时提供 AI 工具调用入口。
 - **arXiv 论文提取与搜索**：自动检测消息中的 arXiv 链接/标识并发送论文信息与 PDF；同时提供 `arxiv_paper` 发送工具和 `arxiv_search` 检索工具。
 - **GitHub 仓库卡片**：自动检测 GitHub 仓库链接或 `owner/repo` 仓库 ID，获取 public 仓库信息并发送简洁图片卡片，展示头像、简介、stars、forks、issues、contributors 等概览。
-- **自动处理管线**：Bilibili、arXiv、GitHub 等自动提取统一运行在 `skills/auto_pipeline` 中，斜杠命令优先级更高；命令输入/输出会写入历史，非命令消息会并行检测和处理命中管线，结果通过统一发送层写入历史并登记附件 UID 后再进入 AI 回复。远程大附件超过 `[attachments].remote_download_max_size_mb` 时只登记 URL 引用，避免无界下载和缓存膨胀。
+- **自动处理管线**：Bilibili、arXiv、GitHub 等自动提取统一运行在 `skills/pipelines` 中，斜杠命令优先级更高；命令输入/输出会写入历史，非命令消息会并行检测和处理命中管线，结果通过统一发送层写入历史并登记附件 UID 后再进入 AI 回复。远程大附件超过 `[attachments].remote_download_max_size_mb` 时只登记 URL 引用，避免无界下载和缓存膨胀。
+- **同 sender 短时消息合并**：默认开启。连续发的多条消息会合并到同一轮 AI 调用，AI 一次看到全部意图自行识别"独立请求/修正/打断"；告别"画猫→改成狗"的重复触发与回复打架。主提示词按 batcher 的"当前输入批次"语义适配，关闭该功能可能导致连续补充/修正消息与提示词不匹配，需要单独适配。可选投机预发送让用户停顿时 LLM 提前开跑、新消息可在未发出回复前取消，进一步压低响应延迟。详见 [docs/message-batching.md](docs/message-batching.md)。
 - **思维链支持**：支持开启思维链，提升复杂逻辑推理能力。
 - **高并发架构**：基于 `asyncio` 全异步设计，支持多队列消息处理与工具并发执行，轻松应对高并发场景。
 - **异步安全 I/O**：统一 IO 层通过线程池 + 跨平台文件锁（Linux/macOS `flock`，Windows `msvcrt`）+ 原子写入（`os.replace`）保证并发写入不损坏、且不阻塞主事件循环。

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/README.md

@@ -40,7 +40,7 @@
   详见 [认知记忆文档](docs/cognitive-memory.md)。
 - **Management-first WebUI**：继续保留 `uv run Undefined-webui` 一键入口；即使 `config.toml` 缺失或未配完，也能先进入管理态补配置、看日志、校验并启动 Bot。
 - **远程管理 + 多端客户端**：浏览器版 WebUI 与新的跨平台控制台共享同一管理面，支持远程管理，并覆盖 `Windows / macOS / Linux / Android` 发布链路。
-- **Management API + Runtime API 分层**：配置、日志、Bot 启停和管理探针由 Management API 提供；主进程 Runtime API 则专注探针、记忆只读查询、认知侧写检索和 WebUI AI Chat。详见 [docs/management-api.md](docs/management-api.md) 与 [docs/openapi.md](docs/openapi.md)。
+- **Management API + Runtime API 分层**：配置、日志、Bot 启停和管理探针由 Management API 提供；主进程 Runtime API 则专注探针、记忆只读查询、认知侧写检索和 WebUI AI Chat；内部探针的技能统计覆盖可调用工具、工具集、Agent、自动处理管线、斜杠命令与 Anthropic Skills。详见 [docs/management-api.md](docs/management-api.md) 与 [docs/openapi.md](docs/openapi.md)。
 - **多模型池**：支持配置多个 AI 模型，可轮询、随机选择或用户指定；支持多模型并发比较，选择最佳结果继续对话。详见 [多模型功能文档](docs/multi-model.md)。
 - **本地知识库**：将纯文本文件向量化存入 ChromaDB，AI 可通过关键词搜索或语义搜索查询领域知识；支持增量嵌入与自动扫描。详见 [知识库文档](docs/knowledge.md)。
 - **全局表情包库**：收到图片后可异步判定是否为表情包，通过两阶段 LLM 管线生成纯文本描述与标签，支持关键词检索、语义检索和混合检索，并可直接按统一图片 `uid` 发送或插入 `<attachment uid="..."/>`。详见 [表情包库说明](docs/memes.md)。
@@ -58,7 +58,8 @@
 - **Bilibili 视频提取**：自动检测消息中的 B 站视频链接/BV 号/小程序分享，下载 1080p 视频并通过 QQ 发送；同时提供 AI 工具调用入口。
 - **arXiv 论文提取与搜索**：自动检测消息中的 arXiv 链接/标识并发送论文信息与 PDF；同时提供 `arxiv_paper` 发送工具和 `arxiv_search` 检索工具。
 - **GitHub 仓库卡片**：自动检测 GitHub 仓库链接或 `owner/repo` 仓库 ID，获取 public 仓库信息并发送简洁图片卡片，展示头像、简介、stars、forks、issues、contributors 等概览。
-- **自动处理管线**：Bilibili、arXiv、GitHub 等自动提取统一运行在 `skills/auto_pipeline` 中，斜杠命令优先级更高；命令输入/输出会写入历史，非命令消息会并行检测和处理命中管线，结果通过统一发送层写入历史并登记附件 UID 后再进入 AI 回复。远程大附件超过 `[attachments].remote_download_max_size_mb` 时只登记 URL 引用，避免无界下载和缓存膨胀。
+- **自动处理管线**：Bilibili、arXiv、GitHub 等自动提取统一运行在 `skills/pipelines` 中，斜杠命令优先级更高；命令输入/输出会写入历史，非命令消息会并行检测和处理命中管线，结果通过统一发送层写入历史并登记附件 UID 后再进入 AI 回复。远程大附件超过 `[attachments].remote_download_max_size_mb` 时只登记 URL 引用，避免无界下载和缓存膨胀。
+- **同 sender 短时消息合并**：默认开启。连续发的多条消息会合并到同一轮 AI 调用，AI 一次看到全部意图自行识别"独立请求/修正/打断"；告别"画猫→改成狗"的重复触发与回复打架。主提示词按 batcher 的"当前输入批次"语义适配，关闭该功能可能导致连续补充/修正消息与提示词不匹配，需要单独适配。可选投机预发送让用户停顿时 LLM 提前开跑、新消息可在未发出回复前取消，进一步压低响应延迟。详见 [docs/message-batching.md](docs/message-batching.md)。
 - **思维链支持**：支持开启思维链，提升复杂逻辑推理能力。
 - **高并发架构**：基于 `asyncio` 全异步设计，支持多队列消息处理与工具并发执行，轻松应对高并发场景。
 - **异步安全 I/O**：统一 IO 层通过线程池 + 跨平台文件锁（Linux/macOS `flock`，Windows `msvcrt`）+ 原子写入（`os.replace`）保证并发写入不损坏、且不阻塞主事件循环。

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/config.toml.example

@@ -28,6 +28,9 @@ context_recent_messages_limit = 20
 # zh: 单次 LLM 请求失败时最大静默重试次数（0=不重试，默认2）。失败的请求会回到原队列的第 2 个位置。
 # en: Max silent retries for a single failed LLM request (0=no retry, default 2). Failed requests are reinserted at position 2 of their original queue lane.
 ai_request_max_retries = 2
+# zh: 模型返回纯文本但未调用 send_message/end 等工具时的最大纠正重试次数（0=不重试，默认3）。
+# en: Max correction retries when the model returns plain text without tool calls (0=no retry, default 3).
+missing_tool_call_retries = 3
 
 # zh: 访问控制。mode 可选：off（不启用）/ blacklist（按黑名单）/ allowlist（按白名单）。
 # en: Access control. mode options: off (disabled) / blacklist / allowlist.
@@ -191,6 +194,8 @@ responses_tool_choice_compat = false
 # zh: Responses API 续轮强制降级：启用后，多轮工具调用将始终跳过 previous_response_id，直接使用完整消息重放（stateless replay）。仅在上游不兼容 responses 状态续轮时使用。默认关闭。
 # en: Responses API force stateless replay: when enabled, multi-turn tool follow-ups always skip previous_response_id and replay the full message history instead. Use only when the upstream does not handle stateful responses follow-ups correctly. Disabled by default.
 responses_force_stateless_replay = false
+# zh: 是否启用自动 prompt_cache_key（建议开启，以提高相似请求的缓存命中率）。
+# en: Enable automatic prompt_cache_key generation (recommended).
 prompt_cache_enabled = true
 # zh: 是否对上游模型 API 启用流式请求。
 # en: Enable streaming requests to the upstream model API.
@@ -251,6 +256,8 @@ responses_tool_choice_compat = false
 # zh: Responses API 续轮强制降级：启用后，多轮工具调用将始终跳过 previous_response_id，直接使用完整消息重放（stateless replay）。仅在上游不兼容 responses 状态续轮时使用。默认关闭。
 # en: Responses API force stateless replay: when enabled, multi-turn tool follow-ups always skip previous_response_id and replay the full message history instead. Use only when the upstream does not handle stateful responses follow-ups correctly. Disabled by default.
 responses_force_stateless_replay = false
+# zh: 是否启用自动 prompt_cache_key（建议开启，以提高相似请求的缓存命中率）。
+# en: Enable automatic prompt_cache_key generation (recommended).
 prompt_cache_enabled = true
 # zh: 是否对上游模型 API 启用流式请求。
 # en: Enable streaming requests to the upstream model API.
@@ -366,6 +373,8 @@ responses_tool_choice_compat = false
 # zh: Responses API 续轮强制降级：启用后，多轮工具调用将始终跳过 previous_response_id，直接使用完整消息重放（stateless replay）。仅在上游不兼容 responses 状态续轮时使用。默认关闭。
 # en: Responses API force stateless replay: when enabled, multi-turn tool follow-ups always skip previous_response_id and replay the full message history instead. Use only when the upstream does not handle stateful responses follow-ups correctly. Disabled by default.
 responses_force_stateless_replay = false
+# zh: 是否启用自动 prompt_cache_key（建议开启，以提高相似请求的缓存命中率）。
+# en: Enable automatic prompt_cache_key generation (recommended).
 prompt_cache_enabled = true
 # zh: 是否对上游模型 API 启用流式请求。
 # en: Enable streaming requests to the upstream model API.
@@ -436,6 +445,8 @@ responses_tool_choice_compat = false
 # zh: Responses API 续轮强制降级：启用后，多轮工具调用将始终跳过 previous_response_id，直接使用完整消息重放（stateless replay）。仅在上游不兼容 responses 状态续轮时使用。默认关闭。
 # en: Responses API force stateless replay: when enabled, multi-turn tool follow-ups always skip previous_response_id and replay the full message history instead. Use only when the upstream does not handle stateful responses follow-ups correctly. Disabled by default.
 responses_force_stateless_replay = false
+# zh: 是否启用自动 prompt_cache_key（建议开启，以提高相似请求的缓存命中率）。
+# en: Enable automatic prompt_cache_key generation (recommended).
 prompt_cache_enabled = true
 # zh: 是否对上游模型 API 启用流式请求。
 # en: Enable streaming requests to the upstream model API.
@@ -493,6 +504,8 @@ responses_tool_choice_compat = false
 # zh: Responses API 续轮强制降级：启用后，多轮工具调用将始终跳过 previous_response_id，直接使用完整消息重放（stateless replay）。仅在上游不兼容 responses 状态续轮时使用。默认关闭。
 # en: Responses API force stateless replay: when enabled, multi-turn tool follow-ups always skip previous_response_id and replay the full message history instead. Use only when the upstream does not handle stateful responses follow-ups correctly. Disabled by default.
 responses_force_stateless_replay = false
+# zh: 是否启用自动 prompt_cache_key（建议开启，以提高相似请求的缓存命中率）。
+# en: Enable automatic prompt_cache_key generation (recommended).
 prompt_cache_enabled = true
 # zh: 是否对上游模型 API 启用流式请求。
 # en: Enable streaming requests to the upstream model API.
@@ -753,6 +766,40 @@ repeat_cooldown_minutes = 60
 # en: Enable inverted question mark (when repeat triggers on "?" messages, send "¿" instead).
 inverted_question_enabled = false
 
+# zh: 同 sender 短时多消息合并器。把同一用户在短时间内连续发送的多条消息合并到同一轮 AI 触发，避免重复回复 / 行为打架。
+# en: Same-sender short-window message batcher. Merges several messages a single user sends in quick succession into one AI turn to avoid duplicate replies / conflicting actions.
+[message_batcher]
+# zh: 是否启用合并器（关闭后所有消息按现行流程逐条触发 AI）。
+# en: Enable the batcher (when disabled all messages trigger the AI individually as before).
+enabled = true
+# zh: 等待窗口（秒）。期间同一用户发的新消息合并到同一批；<= 0 等同于关闭。
+# en: Wait window in seconds. New messages from the same sender within this window are merged; <= 0 disables the feature.
+window_seconds = 5.0
+# zh: 等待策略：extend（每来一条新消息重置 timer，"打字就继续等"）/ fixed（首条到达起定时，期间到达的消息只合并不重置）。
+# en: Wait strategy: extend (reset timer on each new message; keeps waiting while the user types) / fixed (timer fixed at the first message; new arrivals only merge but do not reset).
+strategy = "extend"
+# zh: extend 模式下的硬顶（秒），防止用户一直打字导致永远不发车；0 = 不限制（仅靠 window_seconds + max_messages_per_batch 触发发车）。
+# en: Hard cap in seconds for extend mode, prevents the timer from being reset forever; 0 = no limit (rely on window_seconds + max_messages_per_batch).
+max_window_seconds = 30.0
+# zh: 单批最多消息条数，超出立即发车；0 = 不限制。
+# en: Max messages per batch; exceeding triggers immediate dispatch. 0 = no limit.
+max_messages_per_batch = 0
+# zh: 是否在群聊启用合并。
+# en: Enable batching in group chats.
+group_enabled = true
+# zh: 是否在私聊启用合并。
+# en: Enable batching in private chats.
+private_enabled = true
+# zh: 收到斜杠命令时是否顺便把当前 buffer 一起发出（默认 false：命令独立执行，buffer 继续等到时间到再发）。
+# en: When a slash command arrives, also flush the current buffer to the AI (default false: commands are executed independently and the buffer keeps waiting).
+flush_on_command = false
+# zh: 投机预发送阈值（秒）。0 < pre_send_seconds < window_seconds 时启用：静默到该阈值就提前把当前 batch 发给 LLM 抢时间，但 batch 不结束；T1（window_seconds）才正式结束。0 或 >= window_seconds 视为关闭。
+# en: Speculative pre-fire threshold in seconds. Enabled when 0 < pre_send_seconds < window_seconds: once the user has been silent that long, the current batch is dispatched to the LLM early to save latency, while the batch itself only ends at window_seconds. 0 or >= window_seconds disables speculation.
+pre_send_seconds = 0.0
+# zh: 投机调用已经向用户发出过任何消息后，新消息到达是否仍然取消该 inflight 调用。默认 false（安全：不取消，新消息开新 batch），开启后可能造成重复发送。
+# en: Whether to cancel an in-flight speculative LLM call even when it has already sent at least one message to the user. Default false (safe: do not cancel; the new message starts a new batch). Enabling this may cause duplicate replies.
+allow_cancel_after_send = false
+
 # zh: 历史记录配置。
 # en: History settings.
 [history]
@@ -857,6 +904,22 @@ request_retries = 0
 # en: Max concurrent render browser pages. 0 = auto: Linux defaults to 1, other platforms default to 2.
 browser_max_concurrency = 0
 
+# zh: HTML 渲染结果缓存：基于 HTML 内容 hash 复用同一张图片，避免重复渲染。
+# en: HTML render result cache: reuse rendered images by content hash to skip re-rendering.
+[render.cache]
+# zh: 是否启用渲染缓存。设为 false 时所有渲染请求都会走 playwright 重新截图。
+# en: Whether to enable the render cache. When false, every request re-renders via playwright.
+enabled = true
+# zh: LRU 条目数上限（>=1）。超过时按 last_accessed_at 淘汰最久未用的条目。
+# en: Maximum LRU entries (>=1). Beyond this, the least-recently-used items are evicted.
+max_entries = 50
+# zh: 缓存总占用上限（MB，>=1）。超过时按 LRU 顺序持续淘汰，直到回到上限以内。
+# en: Maximum total cache size (MB, >=1). Evicts in LRU order until within budget.
+max_size_mb = 50
+# zh: 元数据落盘最小间隔（秒，>=0）。频繁访问期间合并写盘，避免热点 IO。
+# en: Minimum interval between metadata flushes (seconds, >=0). Coalesces hot-path writes.
+flush_interval_seconds = 2.0
+
 # zh: 第三方 API 基础地址（便于自定义镜像或私有网关）。
 # en: Third-party API base URLs (for mirrors or private gateways).
 [api_endpoints]

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.3.3"
+version = "3.4.0"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [

undefined_bot-3.4.0/res/IMPORTANT/each.md

@@ -0,0 +1,21 @@
+<rule num="0" priority="P0" id="严防并发导致的重复">
+  <step num="1">明确你这轮的目标（例如：写一个文章；对本条消息/当前输入批次做出合适回应等）或是最后产生的结果或进行的调用（例如：会产生一条消息；会调用某个agent等）</step>
+  <step num="2">回看当前输入批次之外的历史消息，确认不会有旧消息线程导致你产生同样的目标、结果或调用。若有，立刻停止所有操作！！！改为根据情景发送应付性回答（例如："在做了在做了"等）。</step>
+  <MUST priority="P0">以上步骤**必须**在进行任何操作之前进行执行、判断！！始终遵循规则：幽灵任务绝对隔离！！以前的消息仅做辅助判断和上下文补全，不要因为乐于助人处理之前消息列表里的任何消息！哪怕它是你必须要执行、处理的或没有回复！！以下规则仅适用于当前消息/当前输入批次，对以前消息不作数！！！</MUST>
+</rule>
+
+<current_input_batch_definition priority="P0">
+  **当前输入批次定义（适配 MessageBatcher）：**
+  - 如果输入中出现【连续消息说明】，或当前 prompt 中紧邻出现同一 sender 的多段当前 `<message>` 块，则这些 `<message>` 共同构成“当前输入批次”，必须按时间顺序整批理解。
+  - 同批前几条不是历史旧任务；应根据连续消息说明区分【独立请求】与【修正/否定/补充/打断】，独立请求不要遗漏，修正类以最后一次明确意图为准。
+  - 如果没有【连续消息说明】，当前输入批次退化为最后一条当前 `<message>`。
+  - 历史消息存档、旧上下文、上轮未完成请求不属于当前输入批次；除非当前输入批次明确延续或修正它们，否则不得回溯执行。
+</current_input_batch_definition>
+
+<pre_action_mandatory_check priority="P0">
+  **发信息前或调用任何工具前的必须判断（每次操作前强制执行）：**
+  1. 明确本次操作的目标：将发送的消息内容 / 将调用的工具及参数
+  2. 回看当前输入批次之外的历史消息，确认不会有旧消息线程导致你（bot）产生同样的工具调用或内容相似的消息发送
+     - 若无 → 允许继续
+     - 若有 → **立刻停止所有操作！！！** 改为根据情景发送应付性回答（例如："在做了在做了"、"已经在处理了"等），然后调用 end。不可以发送临时的、不过脑子的错误回复！
+</pre_action_mandatory_check>

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/res/README.md

@@ -10,6 +10,10 @@
 - `res/prompts/`：模型提示词与模板
 - `res/agents/intro/`：智能体介绍与自动生成内容
 
+主系统提示词约定：
+- `res/prompts/undefined.xml` 与 `res/prompts/undefined_nagaagent.xml` 共享 Undefined 的基础身份、昵称与项目归属边界。
+- `undefined_nagaagent.xml` 只在上下文明确涉及 NagaAgent 时承接相关工具接入关系，不应在普通自我介绍或无关对话里主动提起。
+
 自定义建议：
 - 在运行目录放置同名文件覆盖默认资源
 - 需要全局默认修改时，建议在源码中更新 `res/` 后运行

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/res/prompts/historian_profile_merge.md

@@ -30,7 +30,7 @@
 - sender_name: {sender_name}
 - message_ids: {message_ids}
 - memo: {memo}
-- 当前消息原文: {source_message}
+- 当前输入批次原文: {source_message}
 - 最近消息参考:
 {recent_messages}
 

{undefined_bot-3.3.3 → undefined_bot-3.4.0}/res/prompts/historian_rewrite.md

@@ -6,9 +6,9 @@
 3. 消灭所有相对地点（这里、那边），替换为具体地点
 4. 保持简洁，一两句话概括
 5. `memo` 可能为空；为空时以 `observations` 和上下文为主
-6. `observations` 代表当前消息提取到的一条新记忆（可能是多条中的一条），优先保证可追溯性
+6. `observations` 代表当前输入批次提取到的一条新记忆（可能是多条中的一条）；若本轮包含 MessageBatcher 合并的多条消息，必须结合整批消息保证可追溯性
 7. 若原文已显式出现实体标识（如 `昵称(数字ID)`、`用户123456`、`QQ:123456`），必须保留该数字ID；禁止擅自替换成 `sender_id` 或其他ID
-8. 可参考”当前消息原文”和”最近消息参考”做实体消歧；当 `observations` 与参考上下文冲突时，以可验证且更具体的信息为准
+8. 可参考”当前输入批次原文”和”最近消息参考”做实体消歧；当 `observations` 与参考上下文冲突时，以可验证且更具体的信息为准
 9. 当 `force=true` 且命中的“相对表达”属于专有名词本体（如用户名“你是谁”、片名《后天》、书名/歌名等）时，不得改写该专有名词，可保留原词直接提交；但实体 ID 一律不得漂移
 
 称呼规则：
@@ -32,7 +32,7 @@
 memo: {memo}
 observations: {observations}
 
-当前消息原文（触发本轮）：
+当前输入批次原文（触发本轮；连续消息会按时间顺序列出多条）：
 {source_message}
 
 最近消息参考（XML 格式，与主对话一致，消息间以 `---` 分隔，用于消歧，不要求逐字复述）：