Language

English 简体中文

Sage 文档

这套文档面向当前仓库实际存在的代码结构，围绕 examples/、app/server/、app/desktop/、sagents/ 和 mcp_servers/ 这些真实入口组织。

适合谁阅读

• 想在本地运行 Sage 的使用者
• 需要理解运行时和应用结构的贡献者
• 需要通过工具、技能、API 或 MCP Server 扩展 Sage 的集成人员

建议先读

1. 应用入口：快速开始、Web（含 Docker）、桌面、CLI、TUI 与 Chrome 扩展
2. 核心概念：运行时模型
3. 架构：仓库与子系统边界
4. 配置：环境变量与部署参数
5. API 文档：HTTP 与运行时接口

常见阅读路径

我想在本地运行 Sage

建议阅读：

1. 应用入口
2. 配置
3. 故障排查

我想扩展运行时

建议阅读：

1. 核心概念
2. 架构
3. MCP Servers
4. 开发

我想和服务端集成

建议阅读：

1. 应用入口
2. 配置
3. API 文档（入口含 HTTP API 参考 与历史 Python 参考）
4. OAuth2 对接指南（Lage）

文档地图

• 应用入口：快速开始、Web、桌面、CLI、TUI 与 Chrome 扩展
  • 快速开始
  • Web 应用（手动启动 + Docker Compose 全栈）
  • 桌面应用
  • CLI 使用指南 · TUI 使用指南
  • Chrome 扩展
• 核心概念：会话、智能体、工具、技能、流程和沙箱
• 架构：代码库整体组织方式（含子章节）
  • 应用层：Server · Desktop · 其它入口
  • sagents 核心：总览 · Agent / Flow · Session / Context · Tool / Skill · Sandbox / LLM / Obs
• 配置：运行时环境变量与存储设置
• MCP Servers：内置 MCP Server 以及它们在平台中的角色
• API 文档：HTTP 与历史 Python API 的导航入口
  • HTTP API 参考：与 register_routes 一致的后端接口、请求体、返回体与示例；侧栏可展开子文档
    • 子文档：认证与用户 · 对话与流式 · Agent 补充 · 知识库 RAG · 工具 / 技能 / MCP · 计划任务 /tasks · 平台与可观测
  • Python 运行时 API：与 sagents 源码一致，主站对外 HTTP 请见上条
• 知识库指南：知识库模块架构、入库、检索与 Agent 接入
• Memory：记忆、检索与 memory-search 工作线
• 落地应用方案：面向行业与业务场景的售前方案集合
• OAuth2 对接指南（Lage）：恢复自历史提交的 OAuth2 对接文档
• 开发：贡献流程和源码位置
• 故障排查：常见启动和环境问题

当前产品入口

轻量示例

• sage run / sage chat / sage doctor：开发向 CLI 入口
• examples/sage_demo.py：Streamlit 演示
• examples/sage_server.py：独立 FastAPI 示例服务

主应用服务端

• app/server/main.py：主 FastAPI 应用入口
• app/server/web/：Vue 3 + Vite Web 客户端

当你需要完整产品能力，而不是演示程序时，优先走这条路径。

桌面应用

• app/desktop/entry.py：桌面端启动入口
• app/desktop/core/main.py：桌面本地 FastAPI 后端
• app/desktop/ui/：桌面 UI

当你需要打包后的桌面体验，而不是浏览器版应用时，使用这条路径。

核心运行时

• sagents/sagents.py：SAgent 流式运行时入口
• sagents/agent/：智能体实现
• sagents/tool/：工具系统与 MCP 代理支持
• sagents/skill/：Skill 加载与执行
• sagents/utils/sandbox/：沙箱抽象与提供者

文档原则

• 这套文档优先保证与当前源码一致，而不是追求历史信息完整。
• 历史迁移说明和重复页面不再作为主文档集合的一部分。
• 仓库根目录的 README.md 仍然是项目介绍页面；这里是技术层面的权威来源。