系统架构 | SAG Wiki

SAG 将产品界面、HTTP 应用、Agent Runtime 与知识引擎分开。最重要的依赖规则是：应用通过一个适配层访问 zleap-sag，知识引擎不依赖 FastAPI、Web UI、用户、会话或引用。

一个引擎，三种入口

SAG 仓库与系统边界

产品前端、任何自定义前端与外部 Agent 都可以独立使用同一后端；Python 服务也可以绕过参考应用，直接嵌入 zleap-sag。

仓库结构

apps/
├── web/                    Next.js 15 + React 19 产品界面
├── desktop/                Electron 桌面封装与本地 sidecar
└── api/
    ├── sag_api/
    │   ├── api/v1/         FastAPI 路由与序列化
    │   ├── connectors/     文件/网页连接器与注册表
    │   ├── parsing/        MarkItDown 与 MinerU 规范化
    │   ├── jobs/           ingest -> extract 后台状态机
    │   ├── sag/            唯一导入 zleap-sag 的应用适配层
    │   ├── generation/     检索证据 -> 流式带引用回答
    │   ├── mcp/            MCP Server 与 HTTP 挂载
    │   ├── services/       应用与领域编排
    │   └── tools/          内置与远程 MCP Agent 工具
    └── sag_agent/          与框架无关的 Agent Runtime Core
skills/sag/                 Agent 知识探索 Skill
deploy/                     数据库初始化资源
docs/assets/readme/         产品截图与架构图

后端分层

API 路由只处理协议、鉴权和序列化；services 负责编排业务；sag/ 适配层把应用对象转换为知识引擎配置与 DTO；zleap-sag 执行 chunk、ingest、extract 和 search。

这条边界允许：

替换 Web 或桌面界面而保留完整 API；
在自己的 Python 服务里只使用引擎；
独立演进 Agent 会话与知识检索；
在应用层负责用户、引用、任务和安全策略。

文档处理路径

connector -> parser -> document service -> background job
          -> sag adapter -> DataEngine ingest/extract
          -> relational + vector storage

上传文件保留在应用数据目录。解析后的 Markdown、文档状态与任务属于应用层；chunk、event、entity 和检索索引由引擎管理。

回答生成路径

Agent run -> retrieval service -> evidence sections
          -> generation LLM -> SSE output + citations

引用在应用层组装，但引用目标来自引擎返回的原文 chunk。这样生成文本和证据边界不会混在同一个不可解释结果里。

桌面边界

Electron 打包同一套 Next.js 工作台，并在本机管理 Next.js standalone 运行时与 PyInstaller FastAPI sidecar。数据库、上传文件、索引和运行密钥写入系统 userData 目录，不写入安装目录。

Web、API 与 Python sidecar 使用同一整包版本发布，不能分别升级其中一部分。