Undefined-bot 3.14.0__tar.gz → 3.15.0__tar.gz

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/ARCHITECTURE.md

@@ -18,7 +18,7 @@ graph TB
         ConfigLoader["ConfigManager<br/>配置管理器<br/>[config/manager.py + loader.py]"]
         ConfigHotReload["ConfigHotReload<br/>热更新应用器<br/>[config/hot_reload.py]"]
         ConfigModels["配置模型<br/>[config/models.py]<br/>ChatModelConfig<br/>VisionModelConfig<br/>SecurityModelConfig<br/>AgentModelConfig"]
-        OneBotClient["OneBotClient<br/>WebSocket 客户端<br/>[onebot/ + onebot.py shim]"]
+        OneBotClient["OneBotClient<br/>WebSocket 客户端<br/>[onebot/]"]
         Context["RequestContext<br/>请求上下文<br/>[context.py]"]
         WebUI["webui.py<br/>配置控制台<br/>[src/Undefined/webui.py]"]
     end
@@ -47,10 +47,10 @@ graph TB
         
         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/ + shim]"]
+        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/]"]
 
         subgraph QueueSystem["车站-列车 队列系统 (services/)"]
-            AICoordinator["AICoordinator<br/>AI 协调器<br/>• Prompt 构建<br/>• 队列管理<br/>• 回复执行<br/>[services/coordinator/ + ai_coordinator.py shim]"]
+            AICoordinator["AICoordinator<br/>AI 协调器<br/>• Prompt 构建<br/>• 队列管理<br/>• 回复执行<br/>[services/coordinator/]"]
             QueueManager["QueueManager<br/>队列管理器<br/>[queue_manager.py]"]
             
             subgraph ModelQueues["ModelQueue 队列组 (按模型隔离)"]
@@ -66,14 +66,14 @@ graph TB
 
     %% ==================== AI 核心能力层 ====================
     subgraph AILayer["AI 核心能力层 (src/Undefined/ai/)"]
-        AIClient["AIClient<br/>AI 客户端主入口<br/>[ai/client/ + client.py shim]<br/>• 技能热重载 • MCP 初始化<br/>• Agent intro 生成"]
+        AIClient["AIClient<br/>AI 客户端主入口<br/>[ai/client/]<br/>• 技能热重载 • MCP 初始化<br/>• Agent intro 生成"]
         
         subgraph AIComponents["AI 组件"]
-            PromptBuilder["PromptBuilder<br/>提示词构建器<br/>[ai/prompts/ + prompts.py shim]"]
+            PromptBuilder["PromptBuilder<br/>提示词构建器<br/>[ai/prompts/]"]
             ToolSearchSession["ToolSearchSession<br/>请求级工具按需投影<br/>[ai/tool_search.py]<br/>• 名称检索 • schema 逐轮扩展"]
-            ModelRequester["ModelRequester<br/>模型请求器<br/>[ai/llm/ + llm.py shim]<br/>• OpenAI SDK • 工具清理<br/>• Thinking 提取"]
+            ModelRequester["ModelRequester<br/>模型请求器<br/>[ai/llm/]<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/>• 图片/音频/视频"]
+            MultimodalAnalyzer["MultimodalAnalyzer<br/>多模态分析器<br/>[ai/multimodal/]<br/>• 图片/音频/视频"]
             SummaryService["SummaryService<br/>总结服务<br/>[summaries.py]<br/>• 聊天记录总结<br/>• 标题生成"]
             TokenCounter["TokenCounter<br/>Token 统计<br/>[tokens.py]"]
             Parsing["Parsing<br/>响应解析<br/>[parsing.py]"]
@@ -663,7 +663,7 @@ graph TB
         
         subgraph Features["特性"]
             F1["非阻塞: 即使前一个请求未完成,<br/>新请求也会按时分发"]
-            F2["优先级: 四级优先级,<br/>确保重要消息优先响应"]
+            F2["优先级: 六条车道,<br/>确保重要消息优先响应"]
             F3["隔离性: 每个模型独立队列,<br/>互不干扰"]
             F4["自动修剪: 普通队列超过10条时,<br/>只保留最新2条"]
             F5["可配置节奏: 每个模型可独立设置<br/>队列发车间隔"]
@@ -860,10 +860,10 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 ### 8层架构分层
 
 1. **外部实体层**：用户、管理员、OneBot 协议端 (NapCat/Lagrange.Core)、大模型 API 服务商
-2. **核心入口层**：main.py 启动入口、配置管理器 (config/loader.py + parsers/ + load_sections/)、热更新应用器 (config/hot_reload.py)、OneBotClient (onebot/ + onebot.py shim)、WeixinService (`weixin/` + `weixin-ilink-client`)、RequestContext (context.py)、Runtime API Server (api/app.py → api/routes/ 路由子模块，含 naga/ 子包)
-3. **消息处理层**：MessageHandler (`handlers/`)、统一 DeliveryAddress 路由 (`utils/message_targets.py`)、SecurityService (security.py)、CommandDispatcher (services/command.py + commands/ mixins)、自动处理管线 (skills/pipelines/)、AutomationService (`automations/service.py`，pipeline 之后、对应 AI loop 之前 await，命中可拦截)、MessageBatcher (services/message_batcher/)、AICoordinator (services/coordinator/ + ai_coordinator.py 门面)、QueueManager (queue_manager.py)、Bilibili/arXiv/GitHub 解析与发送模块
+2. **核心入口层**（目录级事实来源见 [docs/development.md](docs/development.md)）：main.py 启动入口、配置管理器 (config/loader.py + parsers/ + load_sections/)、热更新应用器 (config/hot_reload.py)、OneBotClient (onebot/)、WeixinService (`weixin/` + `weixin-ilink-client`)、RequestContext (context.py)、Runtime API Server (api/app.py → api/routes/ 路由子模块，含 naga/ 子包)
+3. **消息处理层**：MessageHandler (`handlers/`)、统一 DeliveryAddress 路由 (`utils/message_targets.py`)、SecurityService (security.py)、CommandDispatcher (services/command.py + services/commands/)、自动处理管线 (skills/pipelines/)、AutomationService (`automations/service.py`，pipeline 之后、对应 AI loop 之前 await，命中可拦截)、MessageBatcher (services/message_batcher/)、AICoordinator (services/coordinator/)、QueueManager (queue_manager.py)、Bilibili/arXiv/GitHub 解析与发送模块
     自动提取由 `PipelineRegistry` 并行检测、并行处理全部命中的管线；随后 `await` 自动化工作流，未拦截时再进入 AI 自动回复。
-4. **AI 核心能力层**：AIClient (ai/client/ + client.py shim)、PromptBuilder (ai/prompts/ + prompts.py shim)、ModelRequester (ai/llm/ + llm.py shim)、ToolManager (tooling.py)、MultimodalAnalyzer (ai/multimodal/ + multimodal.py shim)、SummaryService (summaries.py)、TokenCounter (tokens.py)。OpenAI Chat Completions / Responses、Anthropic Messages SDK 归一化、CoT 续传与文本 Tool Call 容错见[模型 API 与兼容层](docs/model-compatibility.md)。
+4. **AI 核心能力层**：AIClient (ai/client/)、PromptBuilder (ai/prompts/)、ModelRequester (ai/llm/)、ToolManager (tooling.py)、MultimodalAnalyzer (ai/multimodal/)、SummaryService (summaries.py)、TokenCounter (tokens.py)。OpenAI Chat Completions / Responses、Anthropic Messages SDK 归一化、CoT 续传与文本 Tool Call 容错见[模型 API 与兼容层](docs/model-compatibility.md)。
 5. **存储与上下文层**：MessageHistoryManager (utils/history.py, 10000条限制)、MemoryStorage (memory.py, 置顶备忘录, 500条上限)、EndSummaryStorage、CognitiveService + JobQueue + HistorianWorker + VectorStore + ProfileStorage、MemeService + MemeWorker + MemeStore + MemeVectorStore (表情包库)、FAQStorage、AutomationStorage (`data/automations.json`；旧 `scheduled_tasks.json` 启动时一次性转为新格式，不删旧文件、不双写)、TokenUsageStorage (自动归档)
 6. **技能系统层**：ToolRegistry (registry.py)、AgentRegistry、7个 Agents、13类 Toolsets
 7. **异步 IO 层**：统一 IO 工具 (utils/io.py)，包含 write_json、read_json、append_line、跨平台文件锁 (flock/msvcrt)
@@ -880,7 +880,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 *   **多模型隔离**：每个 AI 模型拥有独立的请求队列组（"站台"），互不干扰。
 *   **非阻塞发车**：实现了可配置节奏的非阻塞调度循环（默认 **1Hz**）。列车按节奏出发，带走一个请求到后台异步处理。
 *   **高可用性**：即使前一个请求仍在处理（如耗时的网络搜索），新的请求也会按时被分发，不会造成队列堵塞。
-*   **优先级管理**：支持四级优先级（超级管理员 > 私聊 > 群聊@ > 群聊普通），确保重要消息优先响应。
+*   **优先级管理**：支持六条车道（超级管理员私聊 > 群聊超级管理员 > 普通私聊 > 群聊@ > 群聊普通 > 后台请求），前两条为严格优先级、中间三条轮转发车，确保重要消息优先响应。
 *   **关停收敛**：`MessageHandler.close()` 会先 flush `MessageBatcher`，再调用 `QueueManager.drain()` 等待已入队请求和在途请求自然完成，最后才停止队列处理器，避免缓冲消息只入队未执行。
 
 ### 7个智能体 Agent

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/CHANGELOG.md

@@ -1,3 +1,22 @@
+## v3.15.0 按功能拆分 Embedding 配置与稳定性修复
+
+本版本将嵌入模型配置按功能拆分，知识库、认知记忆与表情包可以共用默认模型或各自覆写连接、维度与指令；同时修复侧写并发合并丢失更新、Agent 技能无法加载、热更新静默失效、SIGTERM 停机缺失等多处影响长期运行的问题。
+
+- `[models.embedding]` 保留为全局默认模型与默认参数，新增 `[models.embedding.features.<name>]`（`knowledge` / `cognitive` / `memes`）按功能覆写：`use_default` 整体继承默认表，也可按字段覆写连接信息、`context_window_tokens`、`queue_interval_seconds`、`dimensions`、`query_instruction` / `document_instruction`，`request_params` 与默认表按键合并。WebUI 配置表单同步支持覆写段编辑，`use_proxy` 的三态语义（继承 / 启用 / 禁用）改为下拉选择。
+- 生效配置相同的功能复用同一个 Embedder 与发车队列，重排器全局共享，避免重复加载与重复排队。
+- 修复嵌入指令前缀被剥离的问题：query / document instruction 与文本直接拼接，`"passage: "` 这类带尾随空格的前缀现在原样保留。
+- 修复认知侧写并发合并丢失更新：同一实体的「读取 → LLM 改写 → 写入」整段互斥，后一个合并基于前一个已落盘的结果继续，不再互相覆盖。`ProfileStorage` 新增版本读取与恢复，恢复前自动把当前内容另存为新快照（恢复操作本身可回退）；新增 `scripts/restore_profile.py` 提供 list / show / restore 与 `--dry-run`，侧写回滚不再依赖手工复制文件。
+- 史官 worker 新增并发上限 `[cognitive.historian].max_concurrency`（默认 4），以信号量与在途计数双重约束，不再无上限并发。
+- 修复随包 Agent 的 handler 无法加载：handler 模块改按真实包路径导入，`code_delivery_agent` 等使用相对导入的 Agent 恢复可用；注册阶段即预导入全部 handler，失败项记录 `load_error` 并从 schema 中排除，主 AI 不再看到不可用的技能。
+- 配置热更新失败不再静默：更新改为步骤表逐项执行，单步异常不中断其余步骤，失败项与「未完全生效」汇总以 error 级日志输出；异步热更新任务与配置回调的异常均会被记录。嵌入 / 重排模型配置变更加入需重启提示，避免热重载静默无效。
+- 新增 SIGTERM 优雅停机：容器 / systemd / supervisor 停止时不再被直接终止并跳过落盘清理，SIGTERM 与 SIGINT 收敛到同一停机事件，取消连接任务并等待收敛；停机完成后恢复系统原有信号处理器。
+- 修复消息队列重试上限口径分叉：coordinator 与 QueueManager 各用一套重试上限，热更新后两者可分叉，导致等待方在仍会重试时被误判为失败、或重试已耗尽后干等到 480 秒超时；现统一由 `resolve_effective_retry_count` 计算并与等待超时预算同口径。
+- `scripts/reembed_cognitive.py` 支持维度变化迁移：检测到新旧向量维度不同时把新向量全部写入临时 collection，校验记录数后删除原库并原子换名，原库在迁移完成前保持不动，中途被杀可自动清理或从临时库恢复，记录不丢；`--dry-run` 不做任何写入。
+- 依赖与配置清理：crawl4ai 与 langchain-community 改为必需依赖，删除「未安装则降级」的静默回退（crawl4ai 环境异常时启动降级为网页获取不可用并以 error 日志提示修复，不再让 Bot 启动崩溃）；移除零引用的死配置 `cognitive.historian.rewrite_max_retry`、无调用方的 `SecurityService.check_rate_limit` / `record_rate_limit`（限流由 rate_limiter 承担）与死依赖 imgkit、croniter。
+- CI 补齐治理：工作流收敛只读权限、并发取消与任务超时，前端行为测试真实执行而非静默跳过，新增 Python 3.11 / 3.13 兼容矩阵，测试开启 65% 覆盖率门禁。
+
+---
+
 ## v3.14.0 OneBot 本地文件三模式传输
 
 本版本为 Bot 本地文件新增统一传输层，支持 `local`、`url`、`stream` 三种发送方式并按投递快照热更新；默认保持 `local` 兼容旧部署，跨文件系统发送可显式启用 Runtime 临时链接或 NapCat Stream 分块上传。

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: Undefined-bot
-Version: 3.14.0
+Version: 3.15.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
@@ -14,10 +14,8 @@ Requires-Dist: apscheduler>=3.10.0
 Requires-Dist: chardet>=7.4.0.post1
 Requires-Dist: chromadb>=1.5.5
 Requires-Dist: crawl4ai>=0.8.6
-Requires-Dist: croniter>=6.2.2
 Requires-Dist: fastmcp>=3.1.1
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: imgkit
 Requires-Dist: langchain-community>=0.3.0
 Requires-Dist: linkify-it-py>=2.0.3
 Requires-Dist: lunar-python>=1.4.8
@@ -47,19 +45,8 @@ Requires-Dist: regex>=2026.2.28
 Requires-Dist: rich>=14.2.0
 Requires-Dist: silk-python<0.3.0,>=0.2.8
 Requires-Dist: tiktoken>=0.7.0
-Requires-Dist: types-aiofiles>=25.1.0.20251011
-Requires-Dist: types-markdown>=3.10.0.20251106
 Requires-Dist: websockets>=12.0
 Requires-Dist: weixin-ilink-client<0.2.0,>=0.1.3
-Provides-Extra: ci
-Requires-Dist: mypy>=1.8.0; extra == 'ci'
-Requires-Dist: ruff>=0.15.8; extra == 'ci'
-Provides-Extra: dev
-Requires-Dist: mypy>=1.8.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
-Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.15.8; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <table border="0">

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/config.toml.example

@@ -685,8 +685,8 @@ stream_enabled = false
 # en: Extra request-body params (optional), e.g. temperature or vendor-specific fields.
 [models.grok.request_params]
 
-# zh: 嵌入模型配置（知识库语义检索使用）。
-# en: Embedding model config (used by knowledge semantic retrieval).
+# zh: 嵌入模型默认配置（知识库 / 认知记忆 / 梗库默认共用；各功能可在下方 features 中单独覆写）。
+# en: Default embedding model config (shared by knowledge, cognitive memory and memes by default; override per feature below).
 [models.embedding]
 # zh: 是否让该模型请求使用 [proxy] 代理地址。默认关闭。
 # en: Whether this model uses proxy addresses from [proxy]. Disabled by default.
@@ -710,8 +710,11 @@ queue_interval_seconds = 0.0
 # zh: 向量维度（可选）。0 或留空表示使用模型默认维度。
 # en: Embedding dimensions (optional). Use 0/empty to use model defaults.
 dimensions = 0
-# zh: 查询端指令前缀（可选，Qwen3/BGE 等模型常用）。
+# zh: 查询端指令前缀（可选，Qwen3/BGE 等模型常用）。指令与文本直接拼接，
+#     首尾空白与换行原样保留；留空表示不使用指令。
 # en: Query instruction prefix (optional, common for Qwen3/BGE-style models).
+#     The instruction is concatenated directly with the text, whitespace and
+#     newlines preserved; leave empty to disable.
 query_instruction = ""
 # zh: 文档端指令前缀（可选，E5 等模型常用，例如 "passage: "）。
 # en: Document instruction prefix (optional, common for E5-style models, e.g. "passage: ").
@@ -721,6 +724,144 @@ document_instruction = ""
 # en: Extra request-body params (optional) for embedding-provider-specific fields.
 [models.embedding.request_params]
 
+# zh: 按功能覆写的 embedding 配置。每个功能可完全继承 [models.embedding] 默认配置，
+#     也可单独设置并按字段覆写；生效配置完全相同的功能共用一个发车队列。
+#     通用哨兵规则：所有字符串字段（api_url / api_key / model_name / 指令前缀）
+#     空字符串均表示继承默认配置、无法表达显式清空；数值与 use_proxy 的哨兵见各字段注释。
+# en: Per-feature embedding overrides. Each feature either inherits the
+#     [models.embedding] defaults or overrides individual fields; features with
+#     the same effective config share one dispatch queue.
+#     Sentinel rule: empty strings in api_url / api_key / model_name / instruction
+#     prefixes all mean "inherit the default" and cannot express an explicit clear;
+#     numeric and use_proxy sentinels are documented on each field.
+
+# zh: 按功能覆写示例：知识库（knowledge）。仅 use_default = false 时下方字段生效，取哨兵值仍表示继承默认配置。
+# en: Per-feature override example: knowledge base (knowledge). Fields below apply only when use_default = false; sentinel values inherit the defaults.
+[models.embedding.features.knowledge]
+# zh: 是否完全使用 [models.embedding] 默认配置；true 时本表其余字段全部忽略。
+# en: Whether to fully inherit the [models.embedding] defaults; when true, all other fields here are ignored.
+use_default = true
+# zh: 覆写 API 地址；空字符串表示继承默认配置。
+# en: Override API URL; an empty string inherits the default.
+api_url = ""
+# zh: 覆写 API Key；空字符串表示继承默认配置。
+# en: Override API key; an empty string inherits the default.
+api_key = ""
+# zh: 覆写模型名称；空字符串表示继承默认配置。
+# en: Override model name; an empty string inherits the default.
+model_name = ""
+# zh: 覆写代理开关；"inherit"（或 "default"）表示继承默认配置，也可写 true / false。
+# en: Override the proxy switch; "inherit" (or "default") inherits the default, true / false override it.
+use_proxy = "inherit"
+# zh: 覆写上下文窗口上限（token）；<=0 表示继承默认配置。
+# en: Override the context window cap (tokens); <=0 inherits the default.
+context_window_tokens = 0
+# zh: 覆写队列发车间隔（秒）；<0 表示继承默认配置，0 表示请求到达立即发车。
+# en: Override the queue interval (seconds); <0 inherits the default, 0 dispatches on arrival.
+queue_interval_seconds = -1.0
+# zh: 覆写向量维度；<0 表示继承默认配置，0 表示使用模型默认维度。
+# en: Override embedding dimensions; <0 inherits the default, 0 uses the model default.
+dimensions = -1
+# zh: 覆写查询端指令前缀；空字符串或纯空白都表示继承默认配置。覆写表无法表达
+#     「显式清空」——若默认表带前缀而本功能不需要，请把默认前缀留空、只在需要
+#     的功能上单独设置。
+# en: Override the query instruction prefix; an empty or whitespace-only string
+#     inherits the default. Overrides cannot express "explicitly empty" — if the
+#     default table has a prefix this feature does not need, keep the default
+#     empty and set the prefix only on the features that need it.
+query_instruction = ""
+# zh: 覆写文档端指令前缀；语义同 query_instruction（空/纯空白 = 继承）。
+# en: Override the document instruction prefix; same semantics as query_instruction (empty/whitespace = inherit).
+document_instruction = ""
+
+# zh: 覆写额外请求体参数，按 key 合并到默认 request_params 之上（同名以本表为准）。
+# en: Override extra request-body params, merged over the default request_params (this table wins).
+[models.embedding.features.knowledge.request_params]
+# zh: 按功能覆写示例：认知记忆（cognitive）。仅 use_default = false 时下方字段生效，取哨兵值仍表示继承默认配置。
+# en: Per-feature override example: cognitive memory (cognitive). Fields below apply only when use_default = false; sentinel values inherit the defaults.
+[models.embedding.features.cognitive]
+# zh: 是否完全使用 [models.embedding] 默认配置；true 时本表其余字段全部忽略。
+# en: Whether to fully inherit the [models.embedding] defaults; when true, all other fields here are ignored.
+use_default = true
+# zh: 覆写 API 地址；空字符串表示继承默认配置。
+# en: Override API URL; an empty string inherits the default.
+api_url = ""
+# zh: 覆写 API Key；空字符串表示继承默认配置。
+# en: Override API key; an empty string inherits the default.
+api_key = ""
+# zh: 覆写模型名称；空字符串表示继承默认配置。
+# en: Override model name; an empty string inherits the default.
+model_name = ""
+# zh: 覆写代理开关；"inherit"（或 "default"）表示继承默认配置，也可写 true / false。
+# en: Override the proxy switch; "inherit" (or "default") inherits the default, true / false override it.
+use_proxy = "inherit"
+# zh: 覆写上下文窗口上限（token）；<=0 表示继承默认配置。
+# en: Override the context window cap (tokens); <=0 inherits the default.
+context_window_tokens = 0
+# zh: 覆写队列发车间隔（秒）；<0 表示继承默认配置，0 表示请求到达立即发车。
+# en: Override the queue interval (seconds); <0 inherits the default, 0 dispatches on arrival.
+queue_interval_seconds = -1.0
+# zh: 覆写向量维度；<0 表示继承默认配置，0 表示使用模型默认维度。
+# en: Override embedding dimensions; <0 inherits the default, 0 uses the model default.
+dimensions = -1
+# zh: 覆写查询端指令前缀；空字符串或纯空白都表示继承默认配置。覆写表无法表达
+#     「显式清空」——若默认表带前缀而本功能不需要，请把默认前缀留空、只在需要
+#     的功能上单独设置。
+# en: Override the query instruction prefix; an empty or whitespace-only string
+#     inherits the default. Overrides cannot express "explicitly empty" — if the
+#     default table has a prefix this feature does not need, keep the default
+#     empty and set the prefix only on the features that need it.
+query_instruction = ""
+# zh: 覆写文档端指令前缀；语义同 query_instruction（空/纯空白 = 继承）。
+# en: Override the document instruction prefix; same semantics as query_instruction (empty/whitespace = inherit).
+document_instruction = ""
+
+# zh: 覆写额外请求体参数，按 key 合并到默认 request_params 之上（同名以本表为准）。
+# en: Override extra request-body params, merged over the default request_params (this table wins).
+[models.embedding.features.cognitive.request_params]
+# zh: 按功能覆写示例：梗库（memes）。仅 use_default = false 时下方字段生效，取哨兵值仍表示继承默认配置。
+# en: Per-feature override example: meme library (memes). Fields below apply only when use_default = false; sentinel values inherit the defaults.
+[models.embedding.features.memes]
+# zh: 是否完全使用 [models.embedding] 默认配置；true 时本表其余字段全部忽略。
+# en: Whether to fully inherit the [models.embedding] defaults; when true, all other fields here are ignored.
+use_default = true
+# zh: 覆写 API 地址；空字符串表示继承默认配置。
+# en: Override API URL; an empty string inherits the default.
+api_url = ""
+# zh: 覆写 API Key；空字符串表示继承默认配置。
+# en: Override API key; an empty string inherits the default.
+api_key = ""
+# zh: 覆写模型名称；空字符串表示继承默认配置。
+# en: Override model name; an empty string inherits the default.
+model_name = ""
+# zh: 覆写代理开关；"inherit"（或 "default"）表示继承默认配置，也可写 true / false。
+# en: Override the proxy switch; "inherit" (or "default") inherits the default, true / false override it.
+use_proxy = "inherit"
+# zh: 覆写上下文窗口上限（token）；<=0 表示继承默认配置。
+# en: Override the context window cap (tokens); <=0 inherits the default.
+context_window_tokens = 0
+# zh: 覆写队列发车间隔（秒）；<0 表示继承默认配置，0 表示请求到达立即发车。
+# en: Override the queue interval (seconds); <0 inherits the default, 0 dispatches on arrival.
+queue_interval_seconds = -1.0
+# zh: 覆写向量维度；<0 表示继承默认配置，0 表示使用模型默认维度。
+# en: Override embedding dimensions; <0 inherits the default, 0 uses the model default.
+dimensions = -1
+# zh: 覆写查询端指令前缀；空字符串或纯空白都表示继承默认配置。覆写表无法表达
+#     「显式清空」——若默认表带前缀而本功能不需要，请把默认前缀留空、只在需要
+#     的功能上单独设置。
+# en: Override the query instruction prefix; an empty or whitespace-only string
+#     inherits the default. Overrides cannot express "explicitly empty" — if the
+#     default table has a prefix this feature does not need, keep the default
+#     empty and set the prefix only on the features that need it.
+query_instruction = ""
+# zh: 覆写文档端指令前缀；语义同 query_instruction（空/纯空白 = 继承）。
+# en: Override the document instruction prefix; same semantics as query_instruction (empty/whitespace = inherit).
+document_instruction = ""
+
+# zh: 覆写额外请求体参数，按 key 合并到默认 request_params 之上（同名以本表为准）。
+# en: Override extra request-body params, merged over the default request_params (this table wins).
+[models.embedding.features.memes.request_params]
+
 # zh: 重排模型配置（知识库二阶段检索使用）。
 # en: Rerank model config (used in second-stage knowledge retrieval).
 [models.rerank]
@@ -1064,12 +1205,20 @@ tool_search_max_results = 5
 # zh: 主 Prompt 固定插槽对应的本地 UTF-8 文件。路径为空时不注入。
 # en: Local UTF-8 files mapped to stable main-Prompt slots. Empty paths disable injection.
 [prompt.file_includes]
-# zh: P0 / P1 / P2 / P3 分别位于对应优先级区块开头；summary 位于总结区块开头。
-# en: P0-P3 are placed at the start of their priority sections; summary is placed at the start of the summary section.
+# zh: 插入 <absolute_priority level="P0"> 开头（绝对优先级区块）。
+# en: Inserted at the start of the <absolute_priority level="P0"> block.
 p0 = ""
+# zh: 插入 <core_rules level="P1"> 开头（核心规则区块）。
+# en: Inserted at the start of the <core_rules level="P1"> block.
 p1 = ""
+# zh: 插入 <important_rules level="P2"> 开头（重要规则区块）。
+# en: Inserted at the start of the <important_rules level="P2"> block.
 p2 = ""
+# zh: 插入 <optimization_rules level="P3"> 开头（优化规则区块）。
+# en: Inserted at the start of the <optimization_rules level="P3"> block.
 p3 = ""
+# zh: 插入 <summary> 开头（总结区块）。
+# en: Inserted at the start of the <summary> block.
 summary = ""
 
 # zh: Prompt 系统信息注入。总开关默认关闭；开启后各子项默认展示，可逐项关闭。
@@ -1636,9 +1785,6 @@ profile_top_k = 8
 rerank_candidate_multiplier = 3
 
 [cognitive.historian]
-# zh: 记忆改写最大重试次数。
-# en: Max retries for memory rewrite.
-rewrite_max_retry = 2
 # zh: 提供给史官的最近消息参考条数（用于实体消歧）；0=禁用。
 # en: Number of recent message references for historian disambiguation; 0 disables.
 recent_messages_inject_k = 12
@@ -1654,6 +1800,9 @@ poll_interval_seconds = 1.0
 # zh: 任务超时时间（秒），超时后重新入队。
 # en: Stale job timeout (seconds), re-queued after timeout.
 stale_job_timeout_seconds = 300.0
+# zh: 史官同时在途处理的任务上限（>=1）；超出后暂停取新任务，避免并发无上限。
+# en: Max in-flight historian jobs (>=1); new jobs wait until in-flight drops below it.
+max_concurrency = 4
 
 [cognitive.profile]
 # zh: 用户画像存储路径。

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.14.0"
+version = "3.15.0"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [
@@ -17,9 +17,7 @@ dependencies = [
     "crawl4ai>=0.8.6",
     "matplotlib",
     "pillow",
-    "imgkit",
     "markdown>=3.10",
-    "types-markdown>=3.10.0.20251106",
     "aiofiles>=25.1.0",
     "markdown-it-py[plugins]>=4.0.0",
     "mdit-py-plugins>=0.5.0",
@@ -29,9 +27,7 @@ dependencies = [
     "pymdown-extensions>=10.20",
     "playwright>=1.57.0",
     "aiohttp>=3.13.2",
-    "types-aiofiles>=25.1.0.20251011",
     "APScheduler>=3.10.0",
-    "croniter>=6.2.2",
     "pymupdf>=1.27.2,!=1.27.2.2",
     "python-docx>=1.2.0",
     "python-pptx>=1.0.2",
@@ -63,19 +59,6 @@ Issues = "https://github.com/69gg/Undefined/issues"
 Undefined = "Undefined.main:run"
 Undefined-webui = "Undefined.webui:run"
 
-[project.optional-dependencies]
-dev = [
-    "mypy>=1.8.0",
-    "ruff>=0.15.8",
-    "pytest>=8.0.0",
-    "pytest-asyncio>=0.23.0",
-    "pytest-cov>=7.1.0",
-]
-ci = [
-    "ruff>=0.15.8",
-    "mypy>=1.8.0",
-]
-
 [[tool.uv.index]]
 url = "https://pypi.org/simple"
 
@@ -129,7 +112,17 @@ exclude = ["code"]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 
+[tool.coverage.run]
+source = ["Undefined"]
+branch = false
+
+[tool.coverage.report]
+# 覆盖率棘轮：整体不低于 65%（当前约 69%），防止明显回退
+fail_under = 65
+skip_covered = true
+
 [dependency-groups]
+# 开发与 CI 共用同一组工具（CI 通过 --group dev 安装，避免两份清单漂移）
 dev = [
     "mypy>=1.8.0",
     "ruff>=0.15.8",
@@ -137,8 +130,6 @@ dev = [
     "pytest-asyncio>=0.23.0",
     "pytest-cov>=7.1.0",
     "types-pyyaml>=6.0.12.20250915",
-]
-ci = [
-    "ruff>=0.15.8",
-    "mypy>=1.8.0",
+    "types-markdown>=3.10.0.20251106",
+    "types-aiofiles>=25.1.0.20251011",
 ]

{undefined_bot-3.14.0 → undefined_bot-3.15.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.14.0"
+__version__: str = "3.15.0"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/src/Undefined/ai/client/ask_loop.py

@@ -322,12 +322,10 @@ class ClientAskLoopMixin(ClientQueueMixin):
         ):
             tool_context[MUSIC_TRACK_STORE_CONTEXT_KEY] = MusicTrackReferenceStore()
         tool_context.setdefault("search_wrapper", self._search_wrapper)
-        tool_context.setdefault(
-            "crawl4ai_available", self._crawl4ai_capabilities.available
-        )
         tool_context.setdefault(
             "crawl4ai_proxy_config_available",
-            self._crawl4ai_capabilities.proxy_config_available,
+            self._crawl4ai_capabilities is not None
+            and self._crawl4ai_capabilities.proxy_config_available,
         )
         tool_context.setdefault("end_summary_storage", self._end_summary_storage)
         tool_context.setdefault("end_summaries", self._prompt_builder.end_summaries)

{undefined_bot-3.14.0 → undefined_bot-3.15.0}/src/Undefined/ai/client/setup.py

@@ -7,7 +7,7 @@ import logging
 import re
 from collections.abc import Collection
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Optional, Protocol, TYPE_CHECKING
+from typing import Any, Awaitable, Callable, Optional, Protocol
 
 import httpx
 
@@ -16,7 +16,10 @@ from Undefined.ai.llm import ModelRequester
 from Undefined.ai.model_selector import ModelSelector
 from Undefined.ai.multimodal import MultimodalAnalyzer
 from Undefined.ai.prompts import PromptBuilder
-from Undefined.ai.crawl4ai_support import get_crawl4ai_capabilities
+from Undefined.ai.crawl4ai_support import (
+    Crawl4AICapabilities,
+    get_crawl4ai_capabilities,
+)
 from Undefined.ai.summaries import SummaryService
 from Undefined.ai.tokens import TokenCounter
 from Undefined.ai.tool_search import TOOL_SEARCH_NAME
@@ -98,27 +101,6 @@ class SendPrivateMessageCallback(Protocol):
     ) -> Awaitable[None]: ...
 
 
-# 尝试导入 langchain SearxSearchWrapper
-if TYPE_CHECKING:
-    from langchain_community.utilities import (
-        SearxSearchWrapper as SearxSearchWrapperType,
-    )
-else:
-    SearxSearchWrapperType = object
-
-_SearxSearchWrapper: type[SearxSearchWrapperType] | None
-try:
-    from langchain_community.utilities import SearxSearchWrapper as _SearxSearchWrapper
-
-    _SEARX_AVAILABLE = True
-except Exception:
-    _SearxSearchWrapper = None
-    _SEARX_AVAILABLE = False
-    logger.warning(
-        "[初始化] langchain_community 未安装或 SearxSearchWrapper 不可用，搜索功能将禁用"
-    )
-
-
 def _attachment_remote_download_max_bytes(runtime_config: Config) -> int:
     value = int(runtime_config.attachment_remote_download_max_size_mb)
     return max(0, value) * 1024 * 1024
@@ -151,6 +133,17 @@ def _resolve_summary_model_config(
     return fallback
 
 
+def _build_searx_wrapper(searxng_url: str) -> Any:
+    """构造 SearxSearchWrapper；langchain_community 为必需依赖。
+
+    导入放在使用点而非模块顶层：依赖缺失或版本不兼容时不会让整个 AI 客户端
+    无法构造，搜索能力降级为不可用，并由调用方的 error 日志暴露环境问题。
+    """
+    from langchain_community.utilities import SearxSearchWrapper  # noqa: PLC0415
+
+    return SearxSearchWrapper(searx_host=searxng_url, k=10)
+
+
 class ClientSetupMixin:
     """AI 客户端初始化、配置热更新与资源清理。"""
 
@@ -182,7 +175,18 @@ class ClientSetupMixin:
         self.runtime_config = runtime_config
         self.memory_storage = memory_storage
         self._end_summary_storage = end_summary_storage or EndSummaryStorage()
-        self._crawl4ai_capabilities = get_crawl4ai_capabilities()
+        self._crawl4ai_capabilities: Crawl4AICapabilities | None
+        # crawl4ai 是必需依赖，但安装损坏 / 版本不兼容不应让整个 Bot 启动失败：
+        # 这里降级为能力缺失（网页获取工具运行时会明确报错），并以 error 日志暴露环境问题
+        try:
+            self._crawl4ai_capabilities = get_crawl4ai_capabilities()
+        except Exception as exc:
+            self._crawl4ai_capabilities = None
+            logger.error(
+                "[初始化] crawl4ai 初始化失败，网页获取功能不可用，"
+                "请修复 crawl4ai 安装后重启: %s",
+                exc,
+            )
 
         self._http_client = httpx.AsyncClient(timeout=480.0, trust_env=False)
         self._token_usage_storage = TokenUsageStorage()
@@ -295,35 +299,30 @@ class ClientSetupMixin:
         else:
             logger.info("[初始化] 技能热重载已禁用")
 
-        # 初始化搜索 wrapper
+        # 初始化搜索 wrapper（langchain_community 为必需依赖）
         self._search_wrapper: Optional[Any] = None
-        if _SEARX_AVAILABLE and _SearxSearchWrapper is not None:
-            searxng_url = runtime_config.searxng_url
-            if searxng_url:
-                try:
-                    self._search_wrapper = _SearxSearchWrapper(
-                        searx_host=searxng_url, k=10
-                    )
-                    logger.info(
-                        "[初始化] SearxSearchWrapper 初始化成功: url=%s k=10",
-                        redact_string(searxng_url),
-                    )
-                except Exception as exc:
-                    logger.warning("[初始化] SearxSearchWrapper 初始化失败: %s", exc)
-            else:
-                logger.info("[初始化] SEARXNG_URL 未配置，搜索功能禁用")
-
-        if self._crawl4ai_capabilities.available:
-            logger.info("[初始化] crawl4ai 可用，网页获取功能已启用")
-        else:
-            detail = self._crawl4ai_capabilities.error
-            if detail:
-                logger.warning(
-                    "[初始化] crawl4ai 不可用，网页获取功能将禁用: %s",
-                    detail,
+        searxng_url = runtime_config.searxng_url
+        if searxng_url:
+            try:
+                self._search_wrapper = _build_searx_wrapper(searxng_url)
+                logger.info(
+                    "[初始化] SearxSearchWrapper 初始化成功: url=%s k=10",
+                    redact_string(searxng_url),
                 )
-            else:
-                logger.warning("[初始化] crawl4ai 不可用，网页获取功能将禁用")
+            except Exception as exc:
+                logger.error(
+                    "[初始化] SearxSearchWrapper 初始化失败，搜索功能不可用，"
+                    "请修复 langchain-community 安装: %s",
+                    exc,
+                )
+        else:
+            logger.info("[初始化] SEARXNG_URL 未配置，搜索功能禁用")
+
+        if self._crawl4ai_capabilities is not None:
+            logger.info(
+                "[初始化] crawl4ai 已就绪，网页获取功能已启用: proxy_config=%s",
+                self._crawl4ai_capabilities.proxy_config_available,
+            )
 
         self._prompt_builder = PromptBuilder(
             bot_qq=self.bot_qq,
@@ -561,30 +560,19 @@ class ClientSetupMixin:
 
     def apply_search_config(self, searxng_url: str) -> None:
         """应用搜索服务配置（支持热更新）。"""
-        if not _SEARX_AVAILABLE or _SearxSearchWrapper is None:
-            if searxng_url:
-                logger.warning(
-                    "[配置] 搜索组件不可用，已忽略 SEARXNG_URL=%s",
-                    redact_string(searxng_url),
-                )
-            else:
-                logger.info("[配置] 搜索组件不可用，搜索已禁用")
-            self._search_wrapper = None
-            return
-
         if not searxng_url:
             self._search_wrapper = None
             logger.info("[配置] SEARXNG_URL 未配置，搜索功能已禁用")
             return
 
         try:
-            self._search_wrapper = _SearxSearchWrapper(searx_host=searxng_url, k=10)
+            self._search_wrapper = _build_searx_wrapper(searxng_url)
             logger.info(
                 "[配置] 搜索服务已更新: url=%s k=10",
                 redact_string(searxng_url),
             )
         except Exception as exc:
-            logger.warning("[配置] 搜索服务更新失败: %s", exc)
+            logger.error("[配置] 搜索服务更新失败: %s", exc)
             self._search_wrapper = None
             logger.info("[配置] 搜索服务已回退为禁用")