智能体运行时模型

运行时配置不是数据库实体的直接复制，而是 LoadAgentConfigNode 把 Agent、用户模型、工具、Skill、Dataset、Session workspace 和 Web Search 能力合并后的执行快照。这个快照在主图状态中传递，再桥接到 Agentic Loop；它决定本轮“模型能看到什么、工具能调用什么、文件能访问什么”。

1. 配置对象分层

AiAgentEntity：持久化关系

实体保存 Agent 名称、提示词、类型、toolIds、subAgentIds、skillIds、enableSandbox、enableWebSearch、memoryNodeId 等引用。它不适合直接交给模型，因为工具、Skill 和 Dataset 仍是 ID 关系，且包含平台管理字段。

AgentConfig：本轮 Agent 快照

AgentConfig 主要字段如下：

字段	来源/语义
name、description	Agent 基础元数据
systemPrompt、userPrompt、openingRemark	运行提示与 UI 展示
tools	已解析工具元数据、参数 Schema、服务类型
subAgents	可委托的子 Agent 摘要
skills	Agent 绑定的 Skill 列表及当前发布版本信息
officialSkillMounts	后端只读挂载配置，不放入模型可见 toMap()
memoryNodeId	未启用真实 Sandbox 时的 DocSpace/VFS 节点；语义随 Sandbox 开关变化
sandboxEnabled	Agent 级开关，还要与全局 agent.sandbox.enabled 合并
sandboxRoomId、sandboxRelativePath	当前 session 选中的文件房间和相对工作目录
sandboxProvider	cubesandbox 或 opensandbox 等 provider
webSearchEnabled	平台联网搜索能力，null 按允许兼容

AgentConfig.toMap() 是旧下游工具和模型 Provider 的兼容边界；新增字段时应同时考虑 typed getter、serializer 和 Map 消费者。

LlmModelConfig：本轮模型快照

模型配置由 BaseAgent.buildLlmModelConfig 合并平台模型与 Agent 覆盖，再叠加用户 BYOK 模型。重要字段包括 provider、modelId、baseUrl、apiVersion、maxTokens、temperature、topP、contextWindow、supportsStreaming、supportsFunctionCall、supportsVision、supportsJsonMode 和 customConfig。

byok=true 表示本轮使用用户自己的 Key，计费流程会走 BYOK 分支；平台模型则触发平台墨点冻结/结算。模型密钥只在构建 Provider 时使用，不应写入普通消息、SSE 或执行历史。

2. load_config 的真实执行顺序

具体行为：

1. Agent 不存在会写配置错误。
2. 用户模型优先于平台 Agent 绑定模型；没有模型时保留错误并由后续节点决定是否直接失败。
3. Agent 绑定的工具列表会过滤平台 web_search 工具；平台搜索由 WebSearchCapabilityService 控制，避免同时暴露重复搜索工具。
4. Skill 解析当前发布 release，补充 runtimePath、workspacePath、officialReleasePath，并保存只读挂载信息。
5. Dataset 没有缓存时从数据库加载，写入 datasetList 和 ragRetrievalConfig。
6. Dataset 存在但没有显式 RAG 子 Agent 时，尝试幂等注入 AgenticRagAgent；找不到时仍可走内置 RagNode。
7. Session 已选定 Sandbox workspace 时，以 session 绑定覆盖 Agent 固定房间，防止每轮请求切换用户工作区。

配置加载失败时不是所有异常都可忽略：BYOK 回退平台后补冻结失败会抛出 CoinBillingException，防止平台模型被无计费调用；普通配置错误则写入 state，IntentRecognitionNode 和 PlanningNode 会跳过后续模型调用或转 task end。

3. 提示词和模型调用边界

系统提示词、用户提示词、历史消息、RAG 上下文、Skill 内容和工具 Schema 的来源不同：

内容	注入阶段	是否应持久化
Agent system prompt	LoopInit/各节点	仅在配置变更或允许策略下保存
当前用户输入	Controller/AgentMessage	保存原文和必要模型版本
chat history	ChatMemoryStore/JSONL projection	保存 canonical message
工具定义	LoopInit	保存配置摘要，恢复时重建
Skill SKILL.md	skill_call	结果可记录，脚本不自动执行
RAG 内容	RagNode	记录来源和摘要，按策略控制原文
Web Search	prefetch/task end	记录 [[ref:n]] 引用映射

模型能力标记不是装饰字段：不支持流式时不能强行走 streaming handler；不支持 function call 时应降级文本路径；上下文窗口决定 LoopMemoryNode 的压缩阈值；Vision 能力影响附件是否可直接传递。

4. 会话与运行时隔离

ChatSession 固定 agentId、tenantId、roomId、userId、当前 branch/leaf、Dataset 缓存、状态和 loopCount。LoopRuntime 固定当前一次执行的 ChatModel、工具实例、消息列表、TodoManager、ToolResultStore 和 StreamHandler。

两者不能混用：session 是可暂停、可分支和可恢复的业务容器；runtime 是可销毁、可重建的执行对象。worker 结束时必须清理 runtime，但不能删除 session 历史。

5. 新增运行时字段的检查表

新增 Agent/模型配置时需要同步：

1. DTO 字段、toMap()、JSON serializer 和 TaskExecutionState schema。
2. LoadAgentConfigNode 的加载和缓存逻辑。
3. checkpoint codec 的恢复和配置摘要。
4. 模型 Provider 对能力字段的消费。
5. 权限、租户和 BYOK 计费路径。
6. SSE structured block 和轨迹中的脱敏展示。

不要把数据库实体直接序列化到 checkpoint；应保存最小、可版本化、可重建的配置快照。