69gg · 69gg · May 24, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+
+reviews:
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    base_branches:
+      - ".*"
diff --git a/ARCHITECTURE.md b/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)

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,17 @@
+## 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 自己调总结能力」拆成两条更合适的链路，用可配置的上下文窗口统一约束注入与分块，并同步收紧提示词、史官侧写与定时任务持久化，让总结更可信、配置更贴近上游模型、并发场景下更少重复劳动。

diff --git a/README.md b/README.md
@@ -34,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 条始终注入，保持短期连续性，零配置开箱即用
@@ -77,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` 查询。
@@ -91,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 之间的相互调用与工具越权防范。
 
@@ -125,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 账号）**  
@@ -140,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>

diff --git a/apps/undefined-console/package-lock.json b/apps/undefined-console/package-lock.json
diff --git a/apps/undefined-console/package.json b/apps/undefined-console/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "undefined-console",
 	"private": true,
-	"version": "3.4.2",
+	"version": "3.5.0",
 	"type": "module",
 	"scripts": {
 		"tauri": "tauri",