Undefined-bot 3.6.8__tar.gz → 3.7.0__tar.gz

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/ARCHITECTURE.md

@@ -69,6 +69,7 @@ graph TB
         
         subgraph AIComponents["AI 组件"]
             PromptBuilder["PromptBuilder<br/>提示词构建器<br/>[ai/prompts/ + prompts.py shim]"]
+            ToolSearchSession["ToolSearchSession<br/>请求级工具按需投影<br/>[ai/tool_search.py]<br/>• 名称检索 • schema 逐轮扩展"]
             ModelRequester["ModelRequester<br/>模型请求器<br/>[ai/llm/ + llm.py shim]<br/>• OpenAI SDK • 工具清理<br/>• Thinking 提取"]
             ToolManager["ToolManager<br/>工具管理器<br/>[tooling.py]<br/>• 工具执行 • Agent 工具合并<br/>• MCP 工具注入"]
             MultimodalAnalyzer["MultimodalAnalyzer<br/>多模态分析器<br/>[ai/multimodal/ + multimodal.py shim]<br/>• 图片/音频/视频"]
@@ -239,6 +240,7 @@ graph TB
     
     %% AI 核心能力层
     AIClient --> PromptBuilder
+    AIClient --> ToolSearchSession
     AIClient --> ModelRequester
     AIClient --> ToolManager
     AIClient --> MultimodalAnalyzer
@@ -250,6 +252,8 @@ graph TB
     PromptBuilder -->|"注入总结"| EndSummaryStorage
     PromptBuilder -->|"注入认知"| CognitiveService
     PromptBuilder -->|"注入历史"| HistoryManager
+    ToolSearchSession -->|"注入延迟工具名"| PromptBuilder
+    ToolSearchSession -->|"投影本轮 schema"| ModelRequester
     T_End -->|"写短期摘要"| EndSummaryStorage
     T_End -->|"enqueue_job(memo/observations)"| CognitiveService
     CognitiveService -->|"入队"| CognitiveJobQueue
@@ -835,7 +839,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 |---------|-----------|------|
 | **基础配置** | `core.bot_qq`, `core.superadmin_qq`, `onebot.ws_url` | 机器人身份和连接 |
 | **模型配置** | `models.chat` / `models.vision` / `models.agent` / `models.security` | 四类模型独立配置（含 `queue_interval_seconds`） |
-| **功能开关** | `skills.hot_reload`, `skills.intro_autogen_enabled` | 热重载和自动生成 |
+| **功能开关** | `skills.hot_reload`, `skills.intro_autogen_enabled`, `skills.tool_search_enabled` | 热重载、自动生成和主 AI 按需工具投影 |
 | **日志配置** | `logging.level`, `logging.file_path`, `logging.max_size_mb` | 日志系统 |
 | **MCP 配置** | `mcp.config_path` | MCP 配置文件路径 |
 | **存储配置** | `token_usage.*` | Token 归档和清理策略 |
@@ -887,7 +891,8 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 
 - **Tools (基础工具)**：原子化的功能单元，如 `send_message`, `get_history`, `bilibili_video`, `arxiv_paper`。
 - **Toolsets (复合工具集)**：11大类工具集 (group, messages, memory, contacts, group_analysis, notices, render, scheduler, cognitive, mcp, memes)。
-- **延迟加载 + 热重载**：`handler.py` 仅在首次调用时导入；当 `skills/` 下的 `config.json`/`handler.py` 发生变更时会自动重新加载。
+- **注册表延迟导入 + 热重载**：启动时读取 `config.json` 建立本地 schema，`handler.py` 仅在首次执行工具时导入；当 `skills/` 下的 `config.json`/`handler.py` 发生变更时会自动重新加载。
+- **模型 schema 按需投影**：启用 `skills.tool_search_enabled` 后，主 AI 的请求级 `ToolSearchSession` 只投影配置为始终加载的工具、虚拟 `tool_search` 和本轮已检索工具的 schema，其余工具仅注入规范名称；搜索命中的 schema 从下一模型轮开始可用，新 `ask()` 会重置。该机制不改变本地完整注册表、handler 导入时机或子 Agent 工具集。
 - **Agent 自我介绍自动生成**：启动时按 Agent 代码/配置 hash 生成 `intro.generated.md` 并与 `intro.md` 合并。
 
 ### 统一 IO 层与异步存储

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/CHANGELOG.md

@@ -1,3 +1,16 @@
+## v3.7.0 主 AI Tool Search 按需工具加载
+
+本版本为主 AI 新增请求级 Tool Search：工具较多时不再必须把全部 function schema 一次性发送给模型，而是先提供基础工具、虚拟搜索工具和经过权限过滤的名称目录，再按模型实际需要从下一轮开始补充完整 schema。该能力使用普通 function tool 实现，可同时适配 Chat Completions 与 Responses，并保持子 Agent 现有私有工具集不变。
+
+- 新增请求级 `ToolSearchSession`。启用后，主 AI 首轮只加载 `send_message`、`end` 等配置项指定的常驻工具与虚拟 `tool_search`；其余工具以稳定排序的 `<available_deferred_tools>` 名称目录注入。目录在会话权限与运行时功能过滤后生成，已加载集合在当前 `ask()` 内只增不减，新用户请求会重新建立最小快照。
+- 支持精确选择与关键词检索。`tool_search` 接受 `select:tool_a,tool_b`、完整工具名、普通关键词和 `+必需词` 查询，可按工具名、参数名、工具描述与参数描述稳定评分；`max_results` 只能缩小配置上限，返回结果会区分新加载、已加载、未找到及是否截断。
+- 加固逐轮 schema 扩展与执行边界。搜索命中的工具从下一模型轮开始可调用；同轮猜测未加载工具会被执行层拒绝，`end` 与其他调用同轮出现时仍按既有规则拒绝结束，所有 tool result 按原始 tool call 顺序回填，兼容 Responses 的严格调用链校验。
+- 新增 `[skills]` 配置与热更新。`tool_search_enabled` 默认关闭，`tool_search_always_loaded` 默认 `["send_message", "end"]`，`tool_search_max_results` 默认 `5`；配置变更从下一次 `ask()` 生效。预取工具隐藏、保留名冲突、无延迟工具和功能关闭场景均保留安全回退，不会覆盖真实工具或重复执行预取。
+- 同步 Prompt、配置模板、根 README、架构、使用说明、Skills 文档与独立 Tool Search 专题文档；新增搜索内核、主循环、预取、配置、Prompt、Chat Completions、Responses 状态续轮及 stateless fallback 回归测试。
+- 修复 Console 前端依赖审计告警。将 Vite 的最低版本提升到 `6.4.3`，并刷新 `picomatch`、`postcss` 与 `nanoid` 锁定版本，消除开发服务器路径读取、glob ReDoS 和 CSS stringify XSS 等已知漏洞；`npm audit` 结果归零。
+
+---
+
 ## v3.6.8 生图响应自动识别与 WebUI request_params 搜索修复
 
 本版本修复 OpenAI 兼容生图链路对 `response_format` 的错误默认与解析依赖，并加固 base64 解码；同时修正 WebUI 配置搜索会把 `request_params` 结构化编辑器里的 key/type 控件单独隐藏的问题。

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.6.8
+Version: 3.7.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
@@ -117,6 +117,7 @@ Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
+- **Tool Search 按需工具加载**：可在 `[skills]` 下设置 `tool_search_enabled = true`，让主 AI 首轮只接收基础工具、虚拟 `tool_search` 和已检索工具的完整 schema，其余能力仅以名称目录提示，并在检索后的下一模型轮加载。该功能默认关闭，只减少模型上下文中的工具声明，不改变本地注册表、会话权限或子 Agent 的私有工具集。详见 [Tool Search 按需工具加载](docs/tool-search.md)。
 - **可嵌入 Python 库**：`pip install Undefined-bot` 后可 import 配置、`AIClient`、Skills 与认知记忆等组件，无需启动 Bot CLI。详见 [Python 库 API 参考](docs/python-api.md)。
 - **Skills 热重载**：自动扫描 `skills/` 目录，检测到变更后即时重载工具与 Agent，无需重启服务。
 - **三层分层记忆架构**：创新的分层记忆系统，模拟人类记忆机制——
@@ -169,6 +170,7 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
 - 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置；库嵌入见 [§2 库嵌入配置](docs/configuration.md#2-库嵌入配置)。
+- 🔎 **[Tool Search 按需工具加载](docs/tool-search.md)**：减少主 AI 请求携带的 function schema，说明启用方式、检索语法、请求级生命周期、权限边界及 Chat Completions / Responses 兼容行为。
 - 😶 **[表情包系统 (Memes)](docs/memes.md)**：查看表情包两阶段判定管线、统一图片 `uid` 发送机制、检索模式及库存管理说明。
 - 💡 **[交互与使用手册](docs/usage.md)**：包含实用的对话示例、多模态解析用法，以及群管家必备的管理员`/指令`。
 - 📝 **[版本变更记录](CHANGELOG.md)**：查看按版本整理的更新摘要，也可在运行时使用 `/changelog` 查询。

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/README.md

@@ -58,6 +58,7 @@ Console 和 Chat 都需要连接到已经运行的 Undefined 服务。首次部
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
+- **Tool Search 按需工具加载**：可在 `[skills]` 下设置 `tool_search_enabled = true`，让主 AI 首轮只接收基础工具、虚拟 `tool_search` 和已检索工具的完整 schema，其余能力仅以名称目录提示，并在检索后的下一模型轮加载。该功能默认关闭，只减少模型上下文中的工具声明，不改变本地注册表、会话权限或子 Agent 的私有工具集。详见 [Tool Search 按需工具加载](docs/tool-search.md)。
 - **可嵌入 Python 库**：`pip install Undefined-bot` 后可 import 配置、`AIClient`、Skills 与认知记忆等组件，无需启动 Bot CLI。详见 [Python 库 API 参考](docs/python-api.md)。
 - **Skills 热重载**：自动扫描 `skills/` 目录，检测到变更后即时重载工具与 Agent，无需重启服务。
 - **三层分层记忆架构**：创新的分层记忆系统，模拟人类记忆机制——
@@ -110,6 +111,7 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
 - 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置；库嵌入见 [§2 库嵌入配置](docs/configuration.md#2-库嵌入配置)。
+- 🔎 **[Tool Search 按需工具加载](docs/tool-search.md)**：减少主 AI 请求携带的 function schema，说明启用方式、检索语法、请求级生命周期、权限边界及 Chat Completions / Responses 兼容行为。
 - 😶 **[表情包系统 (Memes)](docs/memes.md)**：查看表情包两阶段判定管线、统一图片 `uid` 发送机制、检索模式及库存管理说明。
 - 💡 **[交互与使用手册](docs/usage.md)**：包含实用的对话示例、多模态解析用法，以及群管家必备的管理员`/指令`。
 - 📝 **[版本变更记录](CHANGELOG.md)**：查看按版本整理的更新摘要，也可在运行时使用 `/changelog` 查询。

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/config.toml.example

@@ -998,6 +998,15 @@ prefetch_tools = ["get_current_time"]
 # zh: 隐藏已预取的工具声明。
 # en: Hide prefetched tools from the model's tool list.
 prefetch_tools_hide = true
+# zh: 是否为主 AI 启用按需工具搜索。关闭时仍向模型暴露完整工具列表。
+# en: Enable on-demand tool search for the main AI. When disabled, the full tool list remains exposed.
+tool_search_enabled = false
+# zh: Tool Search 启用后始终向主 AI 暴露的工具名称。
+# en: Tool names always exposed to the main AI when Tool Search is enabled.
+tool_search_always_loaded = ["send_message", "end"]
+# zh: 单次工具搜索最多加载的匹配数量（最小为 1）。
+# en: Maximum matches loaded by one tool search (minimum 1).
+tool_search_max_results = 5
 
 # zh: Prompt 系统信息注入。总开关默认关闭；开启后各子项默认展示，可逐项关闭。
 # en: Prompt system information injection. The master switch is disabled by default; enabled sub-items are shown by default and can be disabled individually.

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/pyproject.toml

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

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/res/prompts/undefined.xml

@@ -128,6 +128,14 @@
         **工具调用执行模式（重要）：**
         - 在单次响应中，你可以调用多个工具，但所有工具调用会**并行执行**
         - 如果工具之间有依赖关系（需要串行执行），必须分多次响应调用
+
+        <tool_search_mode>
+          **仅当当前 tools 列表中实际包含虚拟 `tool_search`，且当前消息中存在 `<available_deferred_tools>` 目录时，启用以下按需工具规则；缺一不可：**
+          - `<available_deferred_tools>` 只是一份尚未加载 schema 的工具名称目录；目录中的名称不代表当前轮已经可以调用。
+          - 目标工具只出现在该目录、没有出现在当前 tools 列表时，必须先调用 `tool_search`；已经知道准确名称时优先使用 `query="select:工具名"` 精确加载，不要猜测参数或直接调用未加载工具。
+          - `tool_search` 与目标工具存在严格的轮次依赖：本轮只搜索，读取搜索结果并等待系统在下一轮暴露目标 schema 后，才能按下一轮 tools 列表中的实际名称调用目标工具；禁止与搜索同轮调用目标工具。
+          - 如果当前 tools 列表没有虚拟 `tool_search`，或当前消息没有 `<available_deferred_tools>` 目录，忽略本段，按当前可见工具正常工作。
+        </tool_search_mode>
         
         **【工具调用安全锁】（每次调用前必须自检）：**
         在生成任何业务 Agent 或 Tool Call（如代码、画图、搜索）前，必须进行以下三条断言：

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/res/prompts/undefined_nagaagent.xml

@@ -128,6 +128,14 @@
         **工具调用执行模式（重要）：**
         - 在单次响应中，你可以调用多个工具，但所有工具调用会**并行执行**
         - 如果工具之间有依赖关系（需要串行执行），必须分多次响应调用
+
+        <tool_search_mode>
+          **仅当当前 tools 列表中实际包含虚拟 `tool_search`，且当前消息中存在 `<available_deferred_tools>` 目录时，启用以下按需工具规则；缺一不可：**
+          - `<available_deferred_tools>` 只是一份尚未加载 schema 的工具名称目录；目录中的名称不代表当前轮已经可以调用。
+          - 目标工具只出现在该目录、没有出现在当前 tools 列表时，必须先调用 `tool_search`；已经知道准确名称时优先使用 `query="select:工具名"` 精确加载，不要猜测参数或直接调用未加载工具。
+          - `tool_search` 与目标工具存在严格的轮次依赖：本轮只搜索，读取搜索结果并等待系统在下一轮暴露目标 schema 后，才能按下一轮 tools 列表中的实际名称调用目标工具；禁止与搜索同轮调用目标工具。
+          - 如果当前 tools 列表没有虚拟 `tool_search`，或当前消息没有 `<available_deferred_tools>` 目录，忽略本段，按当前可见工具正常工作。
+        </tool_search_mode>
         
         **【工具调用安全锁】（每次调用前必须自检）：**
         在生成任何业务 Agent 或 Tool Call（如代码、画图、搜索）前，必须进行以下三条断言：

{undefined_bot-3.6.8 → undefined_bot-3.7.0}/src/Undefined/__init__.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from .skills.registry import BaseRegistry as BaseRegistry
     from .skills.tools import ToolRegistry as ToolRegistry
 
-__version__: str = "3.6.8"
+__version__: str = "3.7.0"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {