# 系统架构

了解前端、后端、智能体运行服务和图引擎如何配合完成分析，以及各模块负责的数据和调用接口。

## 四模块架构

系统围绕分析过程分工：Frontend 接收问题并展示证据，Backend 校验可访问的数据与服务身份，Agent Runtime 组织分析步骤，Graph Engine 提供图模式和计算结果。工具输出回到智能体后，可以形成解释，也可以触发进一步的实体定位、查询或比较。自进化构图位于图模式准备与优化环节，为这个分析过程提供可用输入。

![系统架构与调用关系](/diagrams/architecture-zh.svg)

| 模块 | 职责 | 入口 |
| --- | --- | --- |
| Frontend | React 18、TypeScript、Vite；提供项目与会话、数据集上传与构图预览、图分析与训练视图、报告、工作区文件、记忆与技能管理。 | frontend/ |
| Backend | 面向浏览器的公共 API；将请求绑定到默认工作区，管理项目与模型配置，校验数据范围，转发运行和图请求，并提供工作区下载与导出接口。 | python -m backend |
| Agent Runtime | Agno AgentOS；选择分析步骤并解释工具结果，管理会话、单次运行、记忆、技能、审批与执行追踪。 | python -m agent_runtime |
| Graph Engine | 管理图模式、版本与数据集，执行查询、算法和图学习，支持构图准备、后台作业与结果文件；提供 HTTP 和 MCP 适配器。 | python -m graph_engine api |

## 数据归属

| 数据 | 归属与保存位置 |
| --- | --- |
| 默认工作区归属、项目与模型配置 | Backend 的配置存储 |
| 会话、单次运行、消息、记忆与追踪 | Agent Runtime / PostgreSQL |
| 内置、用户活动与候选技能 | Agent Runtime 的技能目录；候选技能不进入活动加载器 |
| 源数据、图版本、构图结果、图作业和模型文件 | Graph Engine 管理的数据目录与存储 |
| 会话文件工作区 | Backend 保存上传文件；Agent Runtime 运行工作区工具并发布结果；共享存储仍按默认工作区归属与会话分目录保存 |

文件工作区分为 Uploaded（只读上传文件）、Ephemeral（中间文件）、Derived（已发布结果）和 Environment（会话运行环境）。前端文件列表展示 Uploaded 与 Derived，并为可下载的 Derived 文件提供下载入口。智能体必须发布结果文件后，用户才能从这个入口取得文件；文字回答中写出服务器路径不等于文件已经交付。

浏览器保留恢复所需的 session_id、run_id、event_index 和本地交互偏好。会话与图数据以服务端记录为准；切换或刷新页面时，前端读取持久化消息和可用的运行快照来恢复展示。

单用户模式沿用已有默认归属的数据目录。升级时保持 IGRAPH_ADMIN_USER_ID 和持久化卷一致，即可继续使用对应项目、会话和数据；其他旧用户的数据不会被自动删除或合并。内部 user_id 是存储与调用上下文，不再对应浏览器中的登录或切换账号。

## 一次分析请求的路径

- Frontend 通过 Backend 创建会话并提交用户问题及数据范围。
- Backend 将请求绑定到默认工作区并校验数据范围，调用 AgentOS，以 background=true 和 stream=true 启动 Run 并转发 SSE。
- Agent Runtime 结合会话状态与技能选择证据操作，通过 MCP 调用 Graph Engine，附带固定工作区归属、会话与 Run 上下文及内部服务凭据。
- Graph Engine 核验工具前提、输入范围和版本，执行图操作并返回实际结果；长任务通过作业状态交付最终结果。
- 工具证据回到智能体，供其补充分析或组织解释、图视图与报告。AgentOS 持久化消息、Run 和可用结果；原始事件回放缓存属于运行进程。

HTTP、MCP 与 SSE 分别解决不同问题。HTTP 提供项目、数据集、状态与文件等请求响应接口；MCP 把图能力暴露为带名称和参数结构的工具；SSE 持续把文本增量、工具状态、审批请求与作业进度传回浏览器。构图页也会经 Backend 直接访问 Graph Engine，不要求每项操作先发一条聊天消息。关闭浏览器连接只结束观察，服务器停止操作需要单独的取消流程。

图张量、构图结果和模型文件由 Graph Engine 管理。启用持久化执行控制后，运行标识、执行代次和停止状态沿服务链传播，用于核对操作是否仍可执行，以及工作进程能否发布结果。工具返回成功与运行结束是不同层次的状态，最终结束还需确认执行已退出、结果已保存。取消与编辑最新一轮的界面入口受 /api/capabilities 返回值控制。

- [运行与恢复机制](/zh/agent-runtime/): 了解会话状态、工具调度、事件恢复和持久化控制。
- [图数据与计算机制](/zh/graph-engine/): 了解张量表示、版本缓存、算法适配和工作进程。
- [使用工作台](/zh/workspace/): 项目、构图、训练、审批、文件、记忆和技能的实际入口。

## 记忆与构图经验

会话历史、用户记忆与构图经验为分析提供不同层次的上下文。历史帮助继续同一问题，技能复用操作流程，构图经验辅助选择图模式变换。它们都不能代替对当前图和工具结果的核验。

LearnedKnowledge 的语义检索需要最终解析得到可用的嵌入模型与凭据。显式 EMBEDDING 配置可以覆盖供应商通用配置；未填写 EMBEDDING_API_KEY 并不一定表示关闭，因为配置代码会读取后备凭据。无法获得所需配置时，用户画像与用户记忆等基础功能仍可工作；SessionContext 是否包含计划取决于规划配置。LearnedKnowledge 使用用户命名空间和 PROPOSE 模式，和技能候选审核分开管理。

表格构图子智能体的领域策略经验是 Graph Engine 内部的独立机制，不读取主智能体的对话与记忆，也不自动替换会话当前活动图。

用户可在工作台管理面板查看、搜索和删除记忆，也可查看技能全文、上传技能以及批准或拒绝候选技能。这些入口让已保存的内容可供核对；它们不会证明每次对话都已自动形成长期记忆或可执行技能。