AmritaBot 项目架构分析

1. 项目概述

AmritaBot 的技术栈分为三层：

AmritaBot 应用层（NoneBot2 的 Amrita 子系统） — 终端应用层。集成 NoneBot2 + OneBot V11 适配器 + WebUI + 插件系统，通过 AgentSession 管理会话生命周期、AmritaMemoryBackend 对接数据库持久化、SessionDepends 提供依赖注入工厂。
AmritaCore — Agent 运行时层。构建于 AmritaSense 之上，提供会话级工作流编排器（ChatObject）、策略节点编排（LOAD_STATE / AGENT_ENTRY / LLM）、ReAct 思考-行动循环（ReActAgentStrategy）、厂商无关的适配器系统（OpenAI / Anthropic / 可扩展）、工具系统（ToolsManager / MCP 客户端）、上下文裁剪与摘要（ContextCompactor）以及事件钩子（Pre/Post Completion）。
AmritaSense — 底层工作流编排引擎。采用指令集架构替代传统图模型，将控制流（IF/WHILE/GOTO/CALL/TRY）编译为线性指令序列，由轻量 VM（WorkflowInterpreter + PointerVector + 调用栈）逐条执行。核心约 300 LOC，支持原生异步挂起/恢复。

三者的关系类似于：AmritaSense = 操作系统内核 → AmritaCore = 中间件/运行时 → AmritaBot = 桌面环境/应用。

版本说明

本文描述 AmritaCore 1.0 的架构。1.0 相比 0.x 的主要变化：

上下文裁剪与摘要由 MemoryLimiter 改为 ContextCompactor，配置项从 enable_memory_abstract / memory_abstract_proportion 改为 enable_compaction / compaction_trigger_ratio （1.2 起 enable_compaction 再改为三选一的 context_strategy： compact / slide / none）
本地分词器（amrita_core.tokenizer）整体移除，用量只来自 provider 上报
HybridReActAgentStrategy 归并到 ReActAgentStrategy

2. 整体架构拓扑图

架构要点：
AgentSession（nonebot_plugin_amrita.agent）是应用层会话入口，负责会话生命周期（创建/加载/销毁），并注入 SessionDepends 供各插件按依赖获取会话
ChatObject（amrita_core.chatmanager）是会话级工作流编排器：将内置的预编译工作流（REACT_ONLY = LOAD_STATE >> NORMALIZE_MESSAGES >> COMPACT_HISTORY >> JINJA2_RENDER >> BUILD_MESSAGE >> REACT_BLOCK、STEP_REACT_ONLY 等，见 builtins/workflows.py）交给 WorkflowInterpreter 执行
AGENT_ENTRY 节点将控制权交给 ReActAgentStrategy，策略通过 tools_caller 并发执行工具（ToolsManager / MCP Client），并用 ContextCompactor（COMPACT_HISTORY 节点）控制上下文窗口
记忆的读写由 LOAD_STATE / COMMIT_MEMORY 节点触发应用层 AmritaMemoryBackend（或同构的 ChatMemoryBackend），经 CachedUserDataRepository → UserDataExecutor 事务性落库
缓存层使用 WeakValueLRUCache（弱引用 + LRU），权限 / 管理模块用其实现细粒度锁池（_lock_pool）

3. Chat插件详细架构

3.1 Chat插件核心组件拓扑图

AgentSession 与内置 chat 是两条独立路径

容易混淆，注意区分：

内置 chat 插件（amrita/plugins/chat/）不使用 AgentSession。它直接构造 CoreChatObject，并传入自己的 BackendSlots(NoopAbilityBackend(), ChatMemoryBackend(...))，会话超时/归档由 SessionManager（runtime_session.py）负责。
AgentSession 是 nonebot_plugin_amrita 提供给第三方插件的高层会话封装（AmritaMemoryBackend + SessionDepends），内置 chat 没有走这条路。

3.2 数据流分析

4. 核心组件分析

4.1 运行时核心 (chatmanager + runtime_session)

职责：处理单次聊天会话的完整生命周期。

核心组件：

ChatObject（amrita_core.chatmanager.chat_object）：会话级工作流编排器，绑定预设、记忆后端与策略，调用 WorkflowInterpreter 执行内置工作流
SessionManager（amrita/plugins/chat/runtime_session.py）：会话超时检测、自动归档、"继续"恢复
AgentSession（nonebot_plugin_amrita.agent）：面向第三方插件的高层会话封装，内置 chat 不走这条路（见 3.1 的说明）

主要功能：

会话超时管理（session.session_control）
上下文恢复（"继续"功能）
异常处理和管理员通知
会话状态快照

4.2 事件路由系统 (matcher_manager.py)

职责：集中管理所有事件处理器和命令注册。

事件类型：

消息事件：处理普通聊天消息
命令事件：处理各种管理命令
通知事件：处理戳一戳、撤回等通知

4.3 消息处理器 (handlers/chat/)

职责：实现消息处理的核心业务逻辑。

该目录原为单文件 handlers/chat.py，现已拆分为包（__init__.py 只保留 entry() 编排）：

子模块	职责
`__init__.py`	`entry()` 编排主函数
`message.py`	消息合成 / 引用 / 角色 / 多模态
`strategy.py`	Agent 策略选择与 workflow 装配
`lock.py`	`chat_pending_mode` 锁策略
`streaming.py`	`StreamSession` 生命周期与长任务监控
`recovery.py`	Panic-Recover 处理
`usage.py`	Token 用量统计与持久化

处理流程：

会话超时检测与归档（SessionManager）
消息预处理（合成消息内容，处理引用，展开多模态）
构建 CoreChatObject（注入 BackendSlots 与 hook 上下文）
加锁并运行（chat.begin() → await chat）
后处理（流式发送、用量统计、记忆持久化）

4.4 数据访问层 (utils/sql.py + utils/app.py)

数据库模型：

UserMetadata：用户元数据（用量统计、活跃时间）
Memory：会话记忆数据（聊天历史）
MemorySessions：会话归档（超时会话保存）
InsightsModel：全局用量统计

缓存机制：

LRUCache：基于最近最少使用策略的缓存
WeakValueLRUCache：弱引用缓存
脏数据标记：自动跟踪数据修改状态
细粒度锁：确保并发安全

4.5 规则引擎 (check_rule.py)

职责：决定是否响应特定消息事件。

决策逻辑：

插件状态检查
权限验证
用量限制检查
自动回复触发条件判断

5. 技术特性

5.1 并发控制机制

5.2 缓存架构

5.3 上下文管理策略

上下文长度控制：

消息数量限制（core.llm.memory_length_limit，默认 200 条）
Token 窗口限制（预设的 max_context，未声明则回退到 core.llm.session_tokens_windows，默认 65536）
自动压缩（占用达到 compaction_trigger_ratio 时由 ContextCompactor 生成摘要）
会话归档（超时会话自动归档保存）

上下文优化：

最小上下文模式
多模态上下文支持
引用上下文处理

6. 扩展机制

完整清单见独立页面

本节只讲钩子在架构中的位置。可订阅事件的完整列表、可变字段、以及 WebUI / 工具注册等扩展点，见扩展点与事件钩子。

6.1 钩子系统

钩子系统由 amrita_core.hook 提供，基于 AmritaSense 的事件总线（on_event），支持优先级排序与 block 阻断：

block 的默认值是 True

Matcher(event_type, priority=10, block=True) 中的 block=True 表示「我是终点，跑完就结束整条事件链」。观察型钩子必须显式传 block=False，否则会静默吃掉后续优先级的处理器（包括 Amrita 内置的钩子）。

预完成钩子 (on_precompletion → PreCompletionEvent)：

在LLM调用前执行自定义逻辑（EventTypeEnum.BEFORE_COMPLETION）
支持优先级排序
可修改输入上下文

完成钩子 (on_completion → CompletionEvent)：

在LLM调用完成后执行自定义逻辑（EventTypeEnum.COMPLETION）
可读取/修改最终输出
支持优先级排序与阻断

预设回退钩子 (on_preset_fallback → FallbackContext)：

预设缺失/回退时触发（EventTypeEnum.PRESET_FALLBACK）

工具注册 (on_tools)：

注册自定义工具函数
支持条件启用
集成到Agent工作流

Chat 生命周期事件（amrita.plugins.chat.events）：

CHAT_ENTRY / CHAT_REQUEST / CHAT_USAGE_RECORDED / SESSION_COMPACT
已有事件：SEND_MESSAGE / POKE_SEND_MESSAGE / CHAT_PANIC_RECOVER

Agent 步骤事件（amrita_core.builtins.agent.events）：

agent.step_intro / agent.step_leave / agent.step_iteration
agent.tool_call / agent.tool_return（工具执行前后，可改写参数或返回值）

6.2 WebUI集成

管理界面功能：

模型预设管理
提示词模板编辑
用量统计查看
会话状态监控

扩展方式：

register_router() 挂载插件自己的 FastAPI 路由
register_page() 注册页面（支持 iframe 或运行期 ESM 模块，无需重新构建前端）
register_ws_channel() / broadcast_ws() 声明并推送 WebSocket 频道

详见扩展点与事件钩子。

AmritaBot 项目架构分析 ​

1. 项目概述 ​

2. 整体架构拓扑图 ​

3. Chat插件详细架构 ​

3.1 Chat插件核心组件拓扑图 ​

3.2 数据流分析 ​

4. 核心组件分析 ​

4.1 运行时核心 (chatmanager + runtime_session) ​

4.2 事件路由系统 (matcher_manager.py) ​

4.3 消息处理器 (handlers/chat/) ​

4.4 数据访问层 (utils/sql.py + utils/app.py) ​

4.5 规则引擎 (check_rule.py) ​

5. 技术特性 ​

5.1 并发控制机制 ​

5.2 缓存架构 ​

5.3 上下文管理策略 ​

6. 扩展机制 ​

6.1 钩子系统 ​

6.2 WebUI集成 ​