Undefined-bot 3.4.1__tar.gz → 3.5.0__tar.gz

{undefined_bot-3.4.1 → undefined_bot-3.5.0}/ARCHITECTURE.md

@@ -18,14 +18,14 @@ 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.py]"]
+        OneBotClient["OneBotClient<br/>WebSocket 客户端<br/>[onebot/ + onebot.py shim]"]
         Context["RequestContext<br/>请求上下文<br/>[context.py]"]
         WebUI["webui.py<br/>配置控制台<br/>[src/Undefined/webui.py]"]
     end
 
     %% ==================== 消息处理层 ====================
     subgraph MessageLayer["消息处理层 (src/Undefined/)"]
-        MessageHandler["MessageHandler<br/>消息处理器<br/>[handlers.py]"]
+        MessageHandler["MessageHandler<br/>消息处理器<br/>[handlers/]"]
 
         subgraph BilibiliModule["Bilibili 模块 (bilibili/)"]
             BilibiliParser["parser.py<br/>标识符解析<br/>• BV/AV号 • URL<br/>• b23.tv短链 • 小程序JSON"]
@@ -46,10 +46,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.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]"]
 
         subgraph QueueSystem["车站-列车 队列系统 (services/)"]
-            AICoordinator["AICoordinator<br/>AI 协调器<br/>• Prompt 构建<br/>• 队列管理<br/>• 回复执行<br/>[ai_coordinator.py]"]
+            AICoordinator["AICoordinator<br/>AI 协调器<br/>• Prompt 构建<br/>• 队列管理<br/>• 回复执行<br/>[services/coordinator/ + ai_coordinator.py shim]"]
             QueueManager["QueueManager<br/>队列管理器<br/>[queue_manager.py]"]
             
             subgraph ModelQueues["ModelQueue 队列组 (按模型隔离)"]
@@ -65,13 +65,13 @@ graph TB
 
     %% ==================== AI 核心能力层 ====================
     subgraph AILayer["AI 核心能力层 (src/Undefined/ai/)"]
-        AIClient["AIClient<br/>AI 客户端主入口<br/>[client.py]<br/>• 技能热重载 • MCP 初始化<br/>• Agent intro 生成"]
+        AIClient["AIClient<br/>AI 客户端主入口<br/>[ai/client/ + client.py shim]<br/>• 技能热重载 • MCP 初始化<br/>• Agent intro 生成"]
         
         subgraph AIComponents["AI 组件"]
-            PromptBuilder["PromptBuilder<br/>提示词构建器<br/>[prompts.py]"]
-            ModelRequester["ModelRequester<br/>模型请求器<br/>[llm.py]<br/>• OpenAI SDK • 工具清理<br/>• Thinking 提取"]
+            PromptBuilder["PromptBuilder<br/>提示词构建器<br/>[ai/prompts/ + prompts.py shim]"]
+            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/>[multimodal.py]<br/>• 图片/音频/视频"]
+            MultimodalAnalyzer["MultimodalAnalyzer<br/>多模态分析器<br/>[ai/multimodal/ + multimodal.py shim]<br/>• 图片/音频/视频"]
             SummaryService["SummaryService<br/>总结服务<br/>[summaries.py]<br/>• 聊天记录总结<br/>• 标题生成"]
             TokenCounter["TokenCounter<br/>Token 统计<br/>[tokens.py]"]
             Parsing["Parsing<br/>响应解析<br/>[parsing.py]"]
@@ -154,9 +154,9 @@ graph TB
             HistoryManager["MessageHistoryManager<br/>消息历史管理<br/>[utils/history.py]<br/>• 懒加载<br/>• 10000条限制"]
             MemoryStorage["MemoryStorage<br/>置顶备忘录<br/>[memory.py]<br/>• 500条上限<br/>• 自动去重"]
             EndSummaryStorage["EndSummaryStorage<br/>短期总结存储<br/>[end_summary_storage.py]"]
-            CognitiveService["CognitiveService<br/>认知记忆服务<br/>[cognitive/service.py]<br/>• 事件检索 • 侧写读取<br/>• 入队 memory job"]
+            CognitiveService["CognitiveService<br/>认知记忆服务<br/>[cognitive/service/]<br/>• 事件检索 • 侧写读取<br/>• 入队 memory job"]
             CognitiveJobQueue["JobQueue<br/>认知任务队列<br/>[cognitive/job_queue.py]<br/>• pending/processing/failed"]
-            CognitiveHistorian["HistorianWorker<br/>后台史官<br/>[cognitive/historian.py]<br/>• 绝对化改写 • 闸门重试<br/>• 侧写合并（含历史事件注入）"]
+            CognitiveHistorian["HistorianWorker<br/>后台史官<br/>[cognitive/historian/]<br/>• 绝对化改写 • 闸门重试<br/>• 侧写合并（含历史事件注入）"]
             CognitiveVectorStore["CognitiveVectorStore<br/>向量存储<br/>[cognitive/vector_store.py]<br/>• events/profiles<br/>• 时间衰减加权排序<br/>• MMR 去重"]
             CognitiveProfileStorage["ProfileStorage<br/>侧写存储<br/>[cognitive/profile_storage.py]<br/>• users/groups Markdown<br/>• 历史快照"]
             MemeSystem["MemeSystem<br/>表情包存储<br/>[memes/]<br/>• worker.py (两阶段识别)<br/>• sqlite+chromadb<br/>• blob 持久化"]
@@ -849,10 +849,10 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 ### 8层架构分层
 
 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)、MessageBatcher (services/message_batcher.py)、AICoordinator (ai_coordinator.py)、QueueManager (queue_manager.py)、自动处理管线 (skills/pipelines/)、Bilibili/arXiv/GitHub 解析与发送模块
+2. **核心入口层**：main.py 启动入口、配置管理器 (config/loader.py + parsers/ + load_sections/)、热更新应用器 (config/hot_reload.py)、OneBotClient (onebot/ + onebot.py shim)、RequestContext (context.py)、Runtime API Server (api/app.py → api/routes/ 路由子模块，含 naga/ 子包)
+3. **消息处理层**：MessageHandler (`handlers/`)、SecurityService (security.py)、CommandDispatcher (services/command.py + commands/ mixins)、MessageBatcher (services/message_batcher/)、AICoordinator (services/coordinator/ + 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)
+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)
 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
 7. **异步 IO 层**：统一 IO 工具 (utils/io.py)，包含 write_json、read_json、append_line、跨平台文件锁 (flock/msvcrt)

{undefined_bot-3.4.1 → undefined_bot-3.5.0}/CHANGELOG.md

@@ -1,3 +1,30 @@
+## v3.5.0 模块拆分、库嵌入与工具链收敛
+
+本版本是一次以可维护性与可嵌入性为主线的架构整理：将 AI 客户端、消息处理、附件、认知、表情包、协调器、OneBot 与 Agent 运行器等原先体量过大的单文件拆成职责清晰的子包，同时保留向后兼容的 import 路径与 CLI 行为不变。并行修复了 `end` 与同轮业务工具并行调用时可能重复发送或误结束会话的问题，并补齐 Python 库嵌入所需的 `set_config`、`Config.from_mapping`、根包 lazy re-export 与 `py.typed` 类型标记。配置加载改为分段解析 + 域级 parser，文档与测试同步覆盖库嵌入、包布局与公共 API 契约，让 Undefined 既能继续作为 QQ Bot 运行，也能更可靠地被脚本、测试与其它服务按需复用。
+
+- 重构核心运行时模块结构。`ai/client`、`ai/llm`、`ai/prompts`、`ai/multimodal` 分别承载客户端组合、模型请求、Prompt 构建与多模态解析；`handlers/`、`onebot/`、`attachments/`、`cognitive/service` + `cognitive/historian`、`memes/`（ingest / search / 图像工具）、`services/coordinator`、`services/message_batcher`、`skills/agents/runner` 与 `api/routes/naga/` 等子包按域拆分；原 monolith 文件以兼容 shim 或 `__init__` 重导出保留，删除被 shadow 的不可达死代码，降低单文件复杂度与后续改动风险。
+- 完善 Python 库嵌入能力。根包新增 lazy re-export（`Config`、`get_config`、`set_config`、`AIClient`、Skills 注册表、认知/知识库/表情包/附件/Runtime API 等稳定符号）；`Config.from_mapping` / `ConfigBuilder` 支持无 `config.toml` 的内存构建，`env_registry` 统一管理环境变量兜底；`set_config()` 为 opt-in 注入全局单例，CLI 启动链不调用。wheel 打包 `py.typed`（PEP 561），新增 `docs/python-api.md` 公共 API 参考，README 补充嵌入示例与文档索引。
+- 收敛 `end` 工具与同轮并行调用的运行时语义。当模型在同一轮将 `end` 与 `send_message` 或其它业务工具一并调用时：其它工具照常并行执行并返回结果，`end` 不执行并回填明确拒绝响应，避免重复发送与「未读 tool 结果就结束」；提示词、`each.md` 与决策回归用例同步写入 P0 级「end 禁止并行」规则与运行时效果说明。
+- 改进缺失 tool call 时的重试策略。模型返回纯文本但未调用任何工具时，保留 assistant 原文于 messages，注入通用纠正提示而非硬编码 `send_message`/`end`，减少误导性后续 tool 调用；拆分后修复 Skills 路径解析，`PACKAGE_ROOT` 统一指向包根，避免内置工具零加载回归。
+- 加固队列化 LLM 与运行时边界。收紧 queued LLM 重试与 pending-call 清理、配置分段加载的边界校验、附件渲染容错，以及 Prompt 缓存键的隐私安全处理（系统上下文只暴露非敏感模型名等字段）；表情包入库锁与图像工具去重，Naga API 路由守卫与 B 站 WBI 导航解析小幅简化。
+- 更新架构图、开发指南与配置文档。`docs/development.md` 反映拆分后的目录树；`docs/configuration.md` 新增库嵌入专节（`from_mapping` / `set_config` / 环境变量注册表）；`ARCHITECTURE.md` 与相关运维文档同步引用路径。
+- 补强测试与工程契约。新增包布局、公共 API import、CLI 启动兼容、`Config.from_mapping` / 纯环境变量构建、`end` 同轮拒绝与 defer、`AIClient` setup 路径等回归测试；更新 LLM 重试抑制与请求参数相关用例，总测试覆盖库嵌入与拆分后的关键路径。
+
+---
+
+## v3.4.2 总结更准、上下文可配、高并发更稳
+
+本版本主要解决三类实际问题：群聊消息变长、合并发送变多之后，`/summary` 容易慢、容易编、分块预算也不准；主对话注入历史的 200 条硬顶与模型真实窗口脱节；高并发下用户连问「在吗」「好了吗」时，机器人仍可能把旧任务当新活重跑。围绕这些痛点，版本把「用户主动要总结」和「AI 自己调总结能力」拆成两条更合适的链路，用可配置的上下文窗口统一约束注入与分块，并同步收紧提示词、史官侧写与定时任务持久化，让总结更可信、配置更贴近上游模型、并发场景下更少重复劳动。
+
+- 提升消息总结的质量与效率。用户通过 `/summary`、`/sum` 获取总结时，改为直连 summary 模型一次性完成，不再绕 Agent 工具链，响应更快、路径更简单；AI 在对话里调用总结能力时，仍保留 Agent + 拉取历史的灵活流程。长会话按模型上下文窗口自动分段、队列内合并，并配套「只读原始记录、禁止编造」的专用提示词，减少幻觉与无关发挥。
+- 理顺上下文与模型配置边界。取消历史注入 200 条的隐性上限，改由 `context_recent_messages_limit` 与历史存储上限共同决定；各模型节新增 `context_window_tokens`，总结分块、Prompt 预算与实际上游窗口对齐，不再依赖硬编码或误用 `max_tokens`。同时补齐 `reasoning_content_replay`、`system_prompt_as_user`，便于 MiMo、DeepSeek 等 thinking 模型在多轮工具调用时正确续传思维链，或按网关要求改写 system 注入方式。
+- 强化高并发下的任务边界。系统提示词与 each 规则进一步明确：催促、寒暄不等于新任务，历史未完成任务不得自动拾取；启动业务工具前须检查是否已有同类或语义等价操作在处理，有则熔断为简短进度回复而非重跑；无依赖的工具与 Agent 仍鼓励并行，有数据依赖则必须串行，与 MessageBatcher 的批次语义一致。
+- 优化认知侧写的长期画像质量。史官合并侧写时必须先读取再更新，以增量补充稳定特征为主，一次性闲聊或无法沉淀为长期特质的事件应跳过，避免侧写被单轮对话冲散或写成流水账。
+- 修复「向未来的自己发指令」定时任务无法恢复。持久化任务若包含 `self_instruction`，此前会导致整表反序列化失败；现已补齐字段定义，自调用类定时任务可正常加载与执行。
+- 更新配置文档、WebUI 表单与相关测试，覆盖总结直连、上下文窗口、模型对接选项与并发防重复等关键路径。
+
+---
+
 ## v3.4.1 附件缓存治理、隐私安全防线与B站管线重构
 
 本版本围绕三大主线展开：一是附件系统的缓存容量治理与 URL 引用回退机制，防止本地缓存无限制膨胀；二是系统提示词新增 P0 级隐私与危险动作边界规则，从源头约束 AI 对敏感信息和安全请求的处理行为；三是 B 站自动管线全面重构——移除外部下载依赖、内联实现 API 客户端与 WBI 签名、新增弹幕获取并以合并转发形式发送提取结果。同步新增 `/feedback` 反馈命令、恢复发布说明中的分类提交详情，并修正提示词优先级体系。

{undefined_bot-3.4.1 → undefined_bot-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.4.1
+Version: 3.5.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
@@ -82,6 +82,8 @@ Description-Content-Type: text/markdown
 
 ### _与 [NagaAgent](https://github.com/Xxiii8322766509/NagaAgent) 进行联动！_
 
+> 学业繁忙，暂缓更新至六月下旬，在此期间仅作必要bugfix。
+
 ---
 
 ## ⚡ 立即体验
@@ -91,6 +93,7 @@ Description-Content-Type: text/markdown
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
+- **可嵌入 Python 库**：`pip install Undefined-bot` 后可 import 配置、`AIClient`、Skills 与认知记忆等组件，无需启动 Bot CLI。详见 [Python 库 API 参考](docs/python-api.md)。
 - **Skills 热重载**：自动扫描 `skills/` 目录，检测到变更后即时重载工具与 Agent，无需重启服务。
 - **三层分层记忆架构**：创新的分层记忆系统，模拟人类记忆机制——
   - **短期记忆**（`end.memo`）：每轮对话结束自动记录便签备忘，最近 N 条始终注入，保持短期连续性，零配置开箱即用
@@ -134,9 +137,10 @@ Description-Content-Type: text/markdown
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
 - ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- 📦 **[Python 库 API 参考](docs/python-api.md)**：根包 lazy re-export、`Config.from_mapping` / `set_config`、公共 API 符号表与嵌入示例。
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
-- 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置。
+- 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置；库嵌入见 [§2 库嵌入配置](docs/configuration.md#2-库嵌入配置)。
 - 😶 **[表情包系统 (Memes)](docs/memes.md)**：查看表情包两阶段判定管线、统一图片 `uid` 发送机制、检索模式及库存管理说明。
 - 💡 **[交互与使用手册](docs/usage.md)**：包含实用的对话示例、多模态解析用法，以及群管家必备的管理员`/指令`。
 - 📝 **[版本变更记录](CHANGELOG.md)**：查看按版本整理的更新摘要，也可在运行时使用 `/changelog` 查询。
@@ -148,7 +152,7 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 - 🌐 **[Runtime API 与 OpenAPI](docs/openapi.md)**：主进程 Runtime API、鉴权、探针、记忆/侧写查询和运行态集成说明。
 - 🏗️ **[构建指南](docs/build.md)**：Python 包、WebUI、跨平台 App、Android 与 Release 工作流的构建说明。
 - 🔧 **[运维脚本](scripts/README.md)**：嵌入模型更换后的向量库重嵌入等维护工具。
-- 👨‍💻 **[开发者与拓展中心](docs/development.md)**：代码结构剖析和开发新 Agent 的流程参考及自检命令。
+- 👨‍💻 **[开发者与拓展中心](docs/development.md)**：代码结构剖析、模块拆分后的目录树、开发新 Agent 的流程参考及自检命令。
   - **[核心技能系统 (Skills) 解析](src/Undefined/skills/README.md)**：全景式掌握什么是 Skills 架构、怎样定制原子工具与子智能体。
   - **[callable.json 共享授权说明](docs/callable.md)**：细粒度管控 Agent 之间的相互调用与工具越权防范。
 
@@ -182,6 +186,58 @@ uv run Undefined-webui
 
 ---
 
+## 作为 Python 库使用
+
+除 Bot CLI 外，Undefined 也可嵌入脚本、测试或其它服务，直接复用 **Skills 注册表**、**认知记忆**、**知识库**、**AIClient** 等运行时（与 CLI 启动链隔离）。
+
+```bash
+pip install Undefined-bot   # 源码开发：uv sync
+```
+
+```python
+import asyncio
+
+# 根包 lazy re-export：与 CLI 共用同一套运行时组件
+from Undefined import AgentRegistry, Config, ToolRegistry, set_config
+
+# 内存构建配置，测试/嵌入场景无需 config.toml
+cfg = Config.from_mapping(
+    {
+        "onebot": {"ws_url": "ws://127.0.0.1:3001"},
+        "models": {
+            "chat": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+            "vision": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+            "agent": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+        },
+    },
+    strict=False,
+)
+set_config(cfg)  # opt-in 注入全局单例；CLI 启动链不会调用
+
+# 自动扫描 skills/：tools + toolsets（end / group.* / cognitive.* …）
+tools = ToolRegistry()
+# 自动扫描 skills/agents/：web_agent、code_delivery_agent …
+agents = AgentRegistry()
+
+async def main() -> None:
+    # 直接调用原子工具，无需启动 OneBot
+    lunar_time = await tools.execute(
+        "get_current_time",
+        {"format": "text", "include_lunar": True},
+        context={},
+    )
+    print(lunar_time)
+    print(len(tools.get_schema()), "tools,", len(agents.get_schema()), "agents")
+
+asyncio.run(main())
+```
+
+- [Python 库 API 参考](docs/python-api.md) — 根包符号表、shim 路径、`AIClient` / `CognitiveService` 等嵌入示例
+- [配置详解 — 库嵌入配置](docs/configuration.md#2-库嵌入配置) — `from_mapping` / `Config.builder`
+- [开发者与拓展中心](docs/development.md) — 模块结构与自检命令
+
+---
+
 ## 风险提示与免责声明
 
 1. **账号风控与封禁风险（含 QQ 账号）**  
@@ -197,7 +253,9 @@ uv run Undefined-webui
 
 本项目遵循 [MIT License](LICENSE) 开源协议。
 
-感谢 **NagaAgent** 子模块作者及社区支持：[NagaAgent - A simple yet powerful agent framework.](https://github.com/Xxiii8322766509/NagaAgent)。
+感谢 **NagaAgent** 子模块作者及社区提供的支持与鼓励：[NagaAgent - A simple yet powerful agent framework.](https://github.com/Xxiii8322766509/NagaAgent)！
+
+感谢在开发过程中为我提供各种灵感的群友们！
 
 <div align="center">
   <strong>⭐ 如果这个项目对您有帮助，请考虑给我们一个 Star</strong>

{undefined_bot-3.4.1 → undefined_bot-3.5.0}/README.md

@@ -23,6 +23,8 @@
 
 ### _与 [NagaAgent](https://github.com/Xxiii8322766509/NagaAgent) 进行联动！_
 
+> 学业繁忙，暂缓更新至六月下旬，在此期间仅作必要bugfix。
+
 ---
 
 ## ⚡ 立即体验
@@ -32,6 +34,7 @@
 ## ⚡ 核心特性
 
 - **Skills 架构**：全新设计的技能系统，将基础工具（Tools）与智能代理（Agents）分层管理，支持自动发现与注册。
+- **可嵌入 Python 库**：`pip install Undefined-bot` 后可 import 配置、`AIClient`、Skills 与认知记忆等组件，无需启动 Bot CLI。详见 [Python 库 API 参考](docs/python-api.md)。
 - **Skills 热重载**：自动扫描 `skills/` 目录，检测到变更后即时重载工具与 Agent，无需重启服务。
 - **三层分层记忆架构**：创新的分层记忆系统，模拟人类记忆机制——
   - **短期记忆**（`end.memo`）：每轮对话结束自动记录便签备忘，最近 N 条始终注入，保持短期连续性，零配置开箱即用
@@ -75,9 +78,10 @@
 Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将各个模块的深入解析与高阶玩法整理成了专题游览图。这里是开启探索的钥匙：
 
 - ⚙️ **[安装与部署指南](docs/deployment.md)**：不管你是需要 `pip` 无脑一键安装，还是源码二次开发，这里的排坑指南应有尽有。
+- 📦 **[Python 库 API 参考](docs/python-api.md)**：根包 lazy re-export、`Config.from_mapping` / `set_config`、公共 API 符号表与嵌入示例。
 - 🖥️ **[WebUI 使用指南](docs/webui-guide.md)**：管理控制台功能一览——配置编辑、日志查看、认知记忆管理、表情包库、AI 对话与系统监控。
 - 🧭 **[Management API 与远程管理](docs/management-api.md)**：WebUI / App 共用的管理接口、认证、配置/日志/Bot 控制与引导探针说明。
-- 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置。
+- 🛠️ **[配置与热更新说明](docs/configuration.md)**：从模型切换到 MCP 库挂载，全方位掌握 `config.toml` 的高阶配置；库嵌入见 [§2 库嵌入配置](docs/configuration.md#2-库嵌入配置)。
 - 😶 **[表情包系统 (Memes)](docs/memes.md)**：查看表情包两阶段判定管线、统一图片 `uid` 发送机制、检索模式及库存管理说明。
 - 💡 **[交互与使用手册](docs/usage.md)**：包含实用的对话示例、多模态解析用法，以及群管家必备的管理员`/指令`。
 - 📝 **[版本变更记录](CHANGELOG.md)**：查看按版本整理的更新摘要，也可在运行时使用 `/changelog` 查询。
@@ -89,7 +93,7 @@ Undefined 的功能极为丰富，为了让本页面不过于臃肿，我们将
 - 🌐 **[Runtime API 与 OpenAPI](docs/openapi.md)**：主进程 Runtime API、鉴权、探针、记忆/侧写查询和运行态集成说明。
 - 🏗️ **[构建指南](docs/build.md)**：Python 包、WebUI、跨平台 App、Android 与 Release 工作流的构建说明。
 - 🔧 **[运维脚本](scripts/README.md)**：嵌入模型更换后的向量库重嵌入等维护工具。
-- 👨‍💻 **[开发者与拓展中心](docs/development.md)**：代码结构剖析和开发新 Agent 的流程参考及自检命令。
+- 👨‍💻 **[开发者与拓展中心](docs/development.md)**：代码结构剖析、模块拆分后的目录树、开发新 Agent 的流程参考及自检命令。
   - **[核心技能系统 (Skills) 解析](src/Undefined/skills/README.md)**：全景式掌握什么是 Skills 架构、怎样定制原子工具与子智能体。
   - **[callable.json 共享授权说明](docs/callable.md)**：细粒度管控 Agent 之间的相互调用与工具越权防范。
 
@@ -123,6 +127,58 @@ uv run Undefined-webui
 
 ---
 
+## 作为 Python 库使用
+
+除 Bot CLI 外，Undefined 也可嵌入脚本、测试或其它服务，直接复用 **Skills 注册表**、**认知记忆**、**知识库**、**AIClient** 等运行时（与 CLI 启动链隔离）。
+
+```bash
+pip install Undefined-bot   # 源码开发：uv sync
+```
+
+```python
+import asyncio
+
+# 根包 lazy re-export：与 CLI 共用同一套运行时组件
+from Undefined import AgentRegistry, Config, ToolRegistry, set_config
+
+# 内存构建配置，测试/嵌入场景无需 config.toml
+cfg = Config.from_mapping(
+    {
+        "onebot": {"ws_url": "ws://127.0.0.1:3001"},
+        "models": {
+            "chat": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+            "vision": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+            "agent": {"api_url": "https://api.example/v1", "api_key": "sk-xxx", "model_name": "gpt-4o-mini"},
+        },
+    },
+    strict=False,
+)
+set_config(cfg)  # opt-in 注入全局单例；CLI 启动链不会调用
+
+# 自动扫描 skills/：tools + toolsets（end / group.* / cognitive.* …）
+tools = ToolRegistry()
+# 自动扫描 skills/agents/：web_agent、code_delivery_agent …
+agents = AgentRegistry()
+
+async def main() -> None:
+    # 直接调用原子工具，无需启动 OneBot
+    lunar_time = await tools.execute(
+        "get_current_time",
+        {"format": "text", "include_lunar": True},
+        context={},
+    )
+    print(lunar_time)
+    print(len(tools.get_schema()), "tools,", len(agents.get_schema()), "agents")
+
+asyncio.run(main())
+```
+
+- [Python 库 API 参考](docs/python-api.md) — 根包符号表、shim 路径、`AIClient` / `CognitiveService` 等嵌入示例
+- [配置详解 — 库嵌入配置](docs/configuration.md#2-库嵌入配置) — `from_mapping` / `Config.builder`
+- [开发者与拓展中心](docs/development.md) — 模块结构与自检命令
+
+---
+
 ## 风险提示与免责声明
 
 1. **账号风控与封禁风险（含 QQ 账号）**  
@@ -138,7 +194,9 @@ uv run Undefined-webui
 
 本项目遵循 [MIT License](LICENSE) 开源协议。
 
-感谢 **NagaAgent** 子模块作者及社区支持：[NagaAgent - A simple yet powerful agent framework.](https://github.com/Xxiii8322766509/NagaAgent)。
+感谢 **NagaAgent** 子模块作者及社区提供的支持与鼓励：[NagaAgent - A simple yet powerful agent framework.](https://github.com/Xxiii8322766509/NagaAgent)！
+
+感谢在开发过程中为我提供各种灵感的群友们！
 
 <div align="center">
   <strong>⭐ 如果这个项目对您有帮助，请考虑给我们一个 Star</strong>

{undefined_bot-3.4.1 → undefined_bot-3.5.0}/config.toml.example

@@ -22,8 +22,8 @@ process_private_message = true
 # zh: 是否响应拍一拍。关闭后拍一拍事件将被忽略。
 # en: Respond to poke events. If disabled, poke events are ignored.
 process_poke_message = true
-# zh: 注入给模型的最近历史消息条数上限（0-200，0 表示不注入历史）。
-# en: Max number of recent messages injected as model context (0-200; 0 disables history injection).
+# zh: 注入给模型的最近历史消息条数（0 表示不注入；无固定上限，受 max_records 与存储约束）。
+# en: Recent messages injected as model context (0 disables; no fixed cap; bounded by max_records/storage).
 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.
@@ -89,6 +89,10 @@ model_name = ""
 # zh: 最大生成 tokens。
 # en: Max generation tokens.
 max_tokens = 8192
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -113,9 +117,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。当前已在 new-api v0.11.4-alpha.3 发现该问题。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. This issue is currently observed on new-api v0.11.4-alpha.3. Disabled by default.
 responses_tool_choice_compat = false
@@ -161,6 +171,10 @@ model_name = ""
 # zh: Vision 模型最大输出 tokens。启用 thinking 时建议设大（如 8192），确保思维链消耗后仍有余量输出工具调用。
 # en: Vision model max output tokens. When thinking is enabled, use a larger value (e.g. 8192) so there is still room for tool-call output after thinking.
 max_tokens = 8192
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -185,9 +199,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。当前已在 new-api v0.11.4-alpha.3 发现该问题。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. This issue is currently observed on new-api v0.11.4-alpha.3. Disabled by default.
 responses_tool_choice_compat = false
@@ -223,6 +243,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 100
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 8192
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -247,9 +271,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。当前已在 new-api v0.11.4-alpha.3 发现该问题。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. This issue is currently observed on new-api v0.11.4-alpha.3. Disabled by default.
 responses_tool_choice_compat = false
@@ -284,6 +314,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 160
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 8192
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -308,9 +342,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式。
 # en: Responses API tool_choice compatibility mode.
 responses_tool_choice_compat = false
@@ -340,6 +380,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 4096
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -364,9 +408,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。当前已在 new-api v0.11.4-alpha.3 发现该问题。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. This issue is currently observed on new-api v0.11.4-alpha.3. Disabled by default.
 responses_tool_choice_compat = false
@@ -412,6 +462,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 4096
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -436,9 +490,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。当前已在 new-api v0.11.4-alpha.3 发现该问题。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. This issue is currently observed on new-api v0.11.4-alpha.3. Disabled by default.
 responses_tool_choice_compat = false
@@ -456,8 +516,8 @@ stream_enabled = false
 # en: Extra request-body params (optional), e.g. temperature or vendor-specific fields.
 [models.historian.request_params]
 
-# zh: 消息总结模型配置（/summary /sum 专用；未配置时回退到 agent 模型）。
-# en: Message-summary model config (used by /summary and /sum; falls back to the agent model when unset).
+# zh: 消息总结模型配置（/summary /sum 与 SummaryService 专用；未配置时回退到 agent 模型；主 AI 调用 summary_agent 不使用此段配置）。
+# en: Message-summary model config (used by /summary, /sum, and SummaryService; falls back to the agent model when unset; summary_agent invoked by the main AI does not use this section).
 [models.summary]
 # zh: OpenAI-compatible 基址 URL，例如 https://api.openai.com/v1（legacy "/chat/completions" 已弃用但仍兼容）。
 # en: OpenAI-compatible base URL, e.g. https://api.openai.com/v1. Note: legacy "/chat/completions" is deprecated but still supported.
@@ -471,6 +531,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 4096
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -495,9 +559,15 @@ thinking_include_budget = true
 # zh: reasoning effort 传参风格：openai（reasoning.effort）/ anthropic（output_config.effort）。
 # en: Reasoning effort wire format: openai (reasoning.effort) / anthropic (output_config.effort).
 reasoning_effort_style = "openai"
-# zh: 思维链工具调用兼容：启用后在多轮工具调用中回传 reasoning_content，避免部分模型返回 400。
-# en: Thinking tool-call compatibility: pass back reasoning_content in multi-turn tool calls to avoid 400 errors from some models.
+# zh: 思维链工具调用兼容：多轮工具调用时在本地历史回填 reasoning_content（日志/回放），不向上游续传。
+# en: Thinking tool-call compatibility: locally store reasoning_content in history for multi-turn tool calls (logging/replay), not upstream replay.
 thinking_tool_call_compat = true
+# zh: 多轮工具调用时是否将 CoT 续传给上游（Chat: reasoning_content；Responses: output items）。默认 false。
+# en: Relay chain-of-thought to upstream on multi-turn tool calls (Chat: reasoning_content; Responses: output items). Default false.
+reasoning_content_replay = false
+# zh: 是否将所有 system 提示词合并注入第一条 user 消息（适配不支持 system role 的模型）。默认 false。
+# en: Merge all system prompts into the first user message (for models without system role). Default false.
+system_prompt_as_user = false
 # zh: Responses API 的 tool_choice 兼容模式：仅在关闭时请求仍返回 500、怀疑上游不兼容对象型 tool_choice 时再尝试开启；开启后上报为 "required" 并只保留目标工具。默认关闭。
 # en: Responses API tool_choice compatibility mode: only try enabling this when requests still return 500 with the default setting and you suspect the upstream does not support object-style tool_choice; it sends "required" and keeps only the selected tool. Disabled by default.
 responses_tool_choice_compat = false
@@ -530,6 +600,10 @@ model_name = ""
 # zh: 可选限制：最大生成 tokens。
 # en: Optional limit: max generation tokens.
 max_tokens = 8192
+
+# zh: 模型上下文窗口上限（token），用于 /summary 分块与 Prompt 预算；须与上游模型能力一致。
+# en: Model context window cap (tokens) for /summary chunking and prompt budgeting; must match upstream capability.
+context_window_tokens = 32768
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 1.0
@@ -574,6 +648,10 @@ api_key = ""
 # zh: Embedding 模型名称。
 # en: Embedding model name.
 model_name = ""
+
+# zh: 模型上下文窗口上限（token，可选）；嵌入/重排场景通常保持默认即可。
+# en: Model context window cap (tokens, optional); embedding/rerank can usually keep the default.
+context_window_tokens = 8192
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 0.0
@@ -603,6 +681,10 @@ api_key = ""
 # zh: Rerank 模型名称。
 # en: Rerank model name.
 model_name = ""
+
+# zh: 模型上下文窗口上限（token，可选）；嵌入/重排场景通常保持默认即可。
+# en: Model context window cap (tokens, optional); embedding/rerank can usually keep the default.
+context_window_tokens = 8192
 # zh: 队列发车间隔（秒，0 表示立即发车）。
 # en: Queue interval (seconds; 0 dispatches immediately).
 queue_interval_seconds = 0.0
@@ -812,11 +894,11 @@ filtered_result_limit = 200
 # zh: 工具过滤搜索时扫描的最大消息条数。
 # en: Max messages to scan when tools perform filtered searches.
 search_scan_limit = 10000
-# zh: 总结 agent 单次拉取的最大消息条数。
-# en: Max messages the summary agent can fetch per call.
+# zh: /summary 按条数拉取时的最大消息条数（可配置，无固定 500 上限；受 max_records 约束）。
+# en: Max messages fetched per /summary count request (configurable; no fixed 500 cap; bounded by max_records).
 summary_fetch_limit = 1000
-# zh: 总结 agent 按时间范围查询时的最大拉取条数。
-# en: Max messages the summary agent fetches for time-range queries.
+# zh: /summary 按时间范围查询时的最大扫描条数（可配置）。
+# en: Max messages scanned for /summary time-range queries (configurable).
 summary_time_fetch_limit = 5000
 # zh: OneBot API 回退获取的最大消息条数。
 # en: Max messages to fetch via OneBot API fallback.