Muotai AI 智能体核心引擎

muotai-ai 的核心不是一个“调用 LLM 的 Service”，而是一条把请求接收、session 串行化、配置快照、LangGraph、模型、RAG、工具、Skill、Sandbox、SSE 和持久化组合起来的运行时链路。

阅读路径

1. 请求生命周期：理解 Controller、队列、dispatcher、run 标识和终态。
2. 智能体运行时模型：理解 AgentConfig、LlmModelConfig、Dataset、Skill 和 workspace 如何组装。
3. 智能体执行引擎：理解主图、Agentic Loop、工具幂等、HITL、压缩和恢复。
4. Plan/Execute/Reflect：理解意图、联网预取、文本规划、Todo 和重规划。
5. 工具与 Skill 安全：理解工具来源、Schema、执行器、journal、副作用和 Skill 文件协议。
6. 记忆与会话状态：理解 ChatSession、TaskExecutionState、LoopRuntime、JSONL 和 checkpoint。
7. RAG 架构：理解向量入库、标准 RAG 图、Agentic RAG 和 Agent Loop 中的 RagNode。
8. SSE 与外部渠道：理解普通聊天流、轨迹流、pending 事件和外部 IM。
9. 轨迹与可观测性：理解 Trace、节点/LLM/工具/RAG 记录和排障链路。

运行时边界

边界	负责什么	关键对象
接入边界	认证、session 校验、消息接受	Controller、AgentChatServiceImpl
调度边界	同 session 串行、跨 session 并行	AgentMessageQueue、Dispatcher
配置边界	组装本轮可用能力	LoadAgentConfigNode、AgentConfig
图编排边界	路由、循环、暂停、恢复	AutoPlanningAgent、AgenticTaskExecutionNode
能力边界	模型、RAG、工具、Skill、文件	LoopRuntime、各执行节点
可靠性边界	journal、checkpoint、JSONL、终态	ToolExecutionJournal、AgentCheckpointStore
输出边界	可见事件、轨迹和产物	StreamHandler、SSE、TrajectoryController

新技术人员必须掌握的七条不变量

1. 同一 sessionId 只能有一个活动 graph run；resume、pause、cancel 也必须进入该 session 的 dispatcher。
2. ChatbotAgentState 是主图状态，TaskExecutionState 是执行子图状态，LoopRuntime 是不可直接持久化的运行对象。
3. 计划文本不会直接执行动作；只有通过工具 Schema 产生的 ToolExecutionRequest 才能进入工具分发。
4. 副作用工具必须可识别 toolCallId、journal 状态和 HITL 策略，不能因恢复而盲目重试。
5. RAG 片段、Skill 文件、Web Search 页面和业务工具返回值都属于不可信输入，不能把其中指令当系统指令执行。
6. HTTP 200、SSE 断开和模型返回文本都不能单独代表任务终态；以 run-control、graph state 和终态事件为准。
7. 新字段、新节点、新工具、新模型都必须同时考虑 serializer、checkpoint、日志、权限、SSE 和恢复。

当前实现与历史概念的区别

• 规划当前保存 taskPlanText，通过标记和编号步骤决定是否进入循环；TaskPlan/TaskStep DTO 是扩展模型，不应被当作所有路径都已结构化落库。
• 普通聊天 SSE 与 JSONL 轨迹 SSE 是两种补偿机制：前者使用 pending event/回答快照，后者使用 sequence/Last-Event-ID。
• SessionLeaseProvider 当前是 JVM 内存租约；多实例恢复互斥不能自动推断为 Redis/数据库锁。
• Web Search 已从普通 Agent 工具列表中分离，由平台能力和 WebSearchMode 控制。
• WORKFLOW Agent 类型当前明确不支持，不能按已有 Agentic Loop 行为假设。