---

📸 产品截图

📖 详细文档: https://wiki.sage.zavixai.com/

---

✨ 核心功能

• 🤖 规划到交付: 内置规划、执行、自我检查、记忆检索和工具建议代理，用于完成复杂任务。
• 🌐 多入口产品界面: 根据工作流程，可通过桌面端、Web 端、CLI 和 Chrome 扩展使用 Sage。
• 🔁 自动化与周期性任务: 运行定时任务、问卷驱动的数据收集流程以及长期运行的操作任务，并可查看进度。
• 💬 全渠道 IM 集成: 支持微信个人号（iLink）、企业微信、飞书和钉钉的消息及文件传输。
• 🧰 统一工具系统: 将内置工具、技能、MCP 服务器、浏览器自动化、搜索和图像生成等功能整合在一个执行栈中。
• 🛡️ 沙箱式执行: 提供本地、直通和远程沙箱选项，以实现更安全的代理运行时隔离。
• 🛠️ 可视化工作台: 在一个工作空间内查看文件、工具输出、代码、图表、Mermaid、Draw.io、音频、视频以及远程预览内容。
• 🏢 企业级基础架构: OAuth2、可配置的身份验证与 CORS、共享服务架构、CI 覆盖以及可部署的跨平台打包。

---

🚀 快速入门

安装

git clone https://github.com/ZHangZHengEric/Sage.git
cd Sage

运行 Sage

选项 1：一键启动（推荐用于开发）

# 1. 可选：先激活你的虚拟环境
# conda activate your-env

# 2. 设置你的 LLM API 密钥
export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"

# 3. 运行启动脚本
./scripts/dev-up.sh

该脚本将自动：

• 检查 Python（>= 3.10）和 Node.js（>= 18）版本
• 创建配置文件（最小模式：SQLite，无外部依赖）
• 安装依赖并启动后端和前端服务
• 自动创建 logs/server.log
• 根据 .env 中的 SAGE_PORT 启动后端服务并进行健康检查

可选覆盖：

# 显式指定 Python 可执行文件
PYTHON_BIN=/path/to/python ./scripts/dev-up.sh

# 使用 uv 替代 python -m pip / python -m ...
USE_UV=1 ./scripts/dev-up.sh

首次使用？ 脚本会提示你选择：

• 最小模式：SQLite，无外部依赖（推荐用于快速启动）
• 完整模式：MySQL + Elasticsearch + RustFS（适用于类似生产环境）

启动后，打开：http://localhost:5173

选项 2：桌面应用（推荐给用户）

从 GitHub Releases 下载最新的桌面安装包：

• macOS: .dmg（Intel 和 Apple Silicon）
• Windows: .exe / .msi
• Linux: .deb（x86_64 / arm64）

桌面安装指南

macOS

1. 下载适合你 CPU 架构的 .dmg 文件并打开。
2. 将 Sage.app 拖入 Applications 文件夹。
3. 当前的 macOS 版本尚未经过 Apple 签名或公证。如果出现开发者无法验证或 Apple 无法检查应用是否包含恶意软件的警告，请打开 Applications 文件夹，右键点击 Sage.app，选择 Open，然后在弹出的对话框中再次点击 Open。
4. 如果 macOS 仍然阻止该应用，请前往 系统设置 -> 隐私与安全性，找到页面底部附近的 Sage 警告，然后点击 无论如何打开。
5. 如果 macOS 提示应用已损坏或仍拒绝启动，运行以下命令并重试：

xattr -dr com.apple.quarantine /Applications/Sage.app

Windows

1. 下载 .exe 安装程序并运行。
2. 按照安装向导完成安装。
3. 如果 Windows SmartScreen 显示警告，点击 更多信息 -> 无论如何运行。

Linux

1. 从 GitHub Releases 下载适合你架构的 .deb 包。
2. 在 Debian/Ubuntu 系统上，你可以直接双击安装，或者运行以下命令：

sudo apt install ./Sage-<version>-<arch>.deb

如果你更倾向于从源码构建桌面应用，可以使用以下命令。

# macOS/Linux
app/desktop/scripts/build.sh release

# Windows
./app/desktop/scripts/build_windows.ps1 release

命令行界面 (CLI):

# 安装可编辑包
pip install -e .

# 配置最低运行时变量
export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"
export SAGE_DB_TYPE="file"

# 诊断本地运行时配置
sage doctor

# 如有需要，创建最小化本地 CLI 配置
sage config init

# 运行一个简单任务
sage run --stats "Say hello briefly."

# 开启交互式聊天会话
sage chat

详细的 CLI 使用说明请参见：

• 英文：docs/en/CLI.md
• 中文：docs/zh/CLI.md

当前的 CLI MVP 仍然沿用现有的 Sage 运行时配置系统，因此 .env 文件和 Shell 环境变量仍然是主要的配置方式。当启用 --json 时，CLI 会发出流事件，并在运行结束后附加一个 cli_stats 事件，以便于结构化的后续检查。

Web 应用（FastAPI + Vue3）:

# 启动后端
python -m app.server.main

# 启动前端（在另一个终端）
cd app/server/web
npm install
npm run dev

---

🏗️ 系统架构

graph TD
    User[用户] --> Desktop[💻 桌面应用]
    User --> Web[🌐 网页应用]
    User --> CLI[⌨️ 命令行工具]
    User --> Ext[🧩 Chrome 扩展]
    User --> IM[💬 即时通讯渠道]

    Desktop --> AppLayer[🧭 应用服务层]
    Web --> AppLayer
    CLI --> AppLayer
    Ext --> AppLayer
    IM --> AppLayer

    subgraph App[产品层]
        AppLayer --> Chat[💬 聊天与会话]
        AppLayer --> AgentsUI[🤖 代理管理]
        AppLayer --> Tasks[⏰ 任务与自动化]
        AppLayer --> Browser[🌐 浏览器桥接]
        AppLayer --> Workbench[🛠️ 可视化工作台]
    end

    subgraph Core[SAgents 核心]
        AppLayer --> Runtime[🧠 会话运行时]
        Runtime --> Flow[📋 代理流程]
        Flow --> Agents["🤖 代理<br/>计划 / 简单 / 光纤 / 自检"]
        Agents --> Memory[🧠 记忆检索]
        Agents --> Skills[🧩 技能]
        Agents --> ToolMgr[🛠️ 工具管理器]
    end

    subgraph Tools[执行与集成]
        ToolMgr --> MCP[🔌 MCP 服务器]
        ToolMgr --> BrowserTools[🌍 浏览器自动化]
        ToolMgr --> Search[🔎 统一搜索]
        ToolMgr --> ImageGen[🎨 图像生成]
        ToolMgr --> Questionnaire[📝 问卷调查]
        ToolMgr --> IMTools[📨 即时通讯发送]
    end

    subgraph RuntimeEnv[运行时与基础设施]
        Agents --> Sandbox[📦 沙盒运行时]
        Sandbox --> Local[本地]
        Sandbox --> Pass[直通]
        Sandbox --> Remote[远程]
        AppLayer <--> Common[🧱 共享通用服务]
        Common <--> DB[(SQL 数据库)]
        Memory <--> ES[(Elasticsearch)]
        Workbench <--> FS[(RustFS / 本地文件)]
        Runtime -.-> Obs["👁️ 可观测性<br/>OpenTelemetry"]
    end

---

📅 v1.1.0 新特性

🤖 SAgents 内核更新

• 执行链增强：新增 PlanAgent、SelfCheckAgent、MemoryRecallAgent 和 ToolSuggestionAgent
• 上下文效率：优化用户输入并压缩对话历史，以提升长时间任务的处理效率
• 会话与消息：支持编辑后重新运行，提供更丰富的进度反馈，并改进会话检查流程
• 工具扩展：新增问卷收集流程，优化工具调用的渲染、截断及可观测性

💻 产品层更新

• 新入口：新增 Sage 命令行工具、Chrome 扩展以及浏览器自动化工具
• 工作台升级：扩展对音频、视频、Mermaid、Draw.io 的支持，支持远程文件预览，并丰富工具卡片展示
• 聊天体验：改进进度提示、消息传递流程显示、推理内容呈现以及工作区交互
• IM 集成：进一步扩展对微信个人号（iLink）、企业微信、飞书和钉钉的支持，强化文件消息流

🛡️ 平台与基础设施

• 企业级准备：新增 OAuth2、邮箱验证以及更强的身份认证、CORS 和安全控制
• 沙盒与运行时：重构了本地/直通/远程沙盒支持，并优化了 Node 运行时和 Sidecar 打包
• 共享架构：提取了桌面端和服务器端可复用的 common/ 服务、模型和架构
• 文档与 CI：重构了文档结构，新增命令行指南，并扩大了 CI/测试覆盖范围

查看完整发布说明

---

📚 文档

• 📖 完整文档：https://wiki.sage.zavixai.com/
• 📝 发布说明：release_notes/
• 🏗️ 架构：核心运行时和产品层请参阅 sagents/、common/ 和 app/
• 🔧 配置：环境变量和配置文件位于 app/desktop/

---

🛠️ 开发

项目结构

Sage/
├── sagents/                    # SAgents 核心运行时、流程、上下文、工具、沙盒
├── common/                     # 共享模型、架构、服务、核心客户端
├── app/
│   ├── desktop/                # 桌面应用（Python 后端 + Vue UI + Tauri 容器）
│   ├── server/                 # 服务器应用及网页前端
│   ├── cli/                    # Sage 命令行入口和服务
│   └── chrome-extension/       # 浏览器扩展及侧边栏
├── mcp_servers/                # 即时通讯、搜索、调度、图像生成等
├── docs/                       # 英文和中文文档
└── release_notes/              # 版本发布说明

贡献

我们欢迎各位贡献！请访问我们的 GitHub Issues 查看任务和讨论。

---

💖 赞助商

---

🦌 加入我们的社区

---

Sage AI 开源工具快速上手指南

Sage 是一个生产级的智能体（Agent）平台，支持任务执行、自动化工作流、浏览器操作及企业级部署。本指南将帮助你快速在本地运行 Sage。

1. 环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统：macOS, Windows, 或 Linux
• Python: 版本 >= 3.10
• Node.js: 版本 >= 18 (用于前端构建)
• Git: 用于克隆代码仓库

提示：推荐使用 conda 或 venv 创建独立的 Python 虚拟环境以避免依赖冲突。

2. 安装步骤

第一步：克隆项目

打开终端，执行以下命令获取源代码：

git clone https://github.com/ZHangZHengEric/Sage.git
cd Sage

第二步：配置大模型密钥

Sage 需要连接大语言模型（LLM）才能运行。请在终端设置环境变量（以 DeepSeek 为例，也可替换为其他兼容 OpenAI 格式的模型）：

export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"

Windows PowerShell 用户请使用 $env:VAR_NAME = "value" 格式设置。

第三步：启动服务

推荐开发者使用一键启动脚本，它会自动检查环境、安装依赖并启动前后端服务：

./scripts/dev-up.sh

首次运行提示： 脚本会询问你选择运行模式：

• Minimal mode (推荐): 使用 SQLite 数据库，无外部依赖，适合快速体验和开发。
• Full mode: 使用 MySQL + Elasticsearch + RustFS，适合生产环境模拟。

启动成功后，访问浏览器打开：http://localhost:5173

---

3. 基本使用

Sage 提供了多种使用方式，以下是两种最快捷的上手方法：

方式一：Web 界面交互（推荐新手）

1. 浏览器访问 http://localhost:5173。
2. 在可视化工作台（Visual Workbench）中直接输入自然语言指令，例如：“帮我搜索最新的 AI 新闻并总结”。
3. Sage 将自动规划任务、调用工具（如搜索、浏览器自动化），并在界面实时展示执行过程和结果。

方式二：命令行 (CLI) 快速任务

如果你更喜欢终端操作，可以使用 CLI 模式：

1. 安装 CLI 包（在项目根目录下）：

   pip install -e .
   

2. 执行单次任务：

   sage run --stats "Say hello briefly."
   

3. 开启交互式对话：

   sage chat
   

注意：CLI 模式同样依赖上述步骤中设置的 SAGE_DEFAULT_LLM_API_KEY 等环境变量。

---

其他安装选项

如果不希望从源码运行，可以直接下载桌面客户端：

• 访问 GitHub Releases
• 根据系统下载 .dmg (macOS), .exe (Windows), 或 .deb (Linux) 安装包。
• macOS 用户注意：若遇到“无法验证开发者”警告，请在“系统设置 -> 隐私与安全性”中点击“仍要打开”，或使用命令 xattr -dr com.apple.quarantine /Applications/Sage.app 解除隔离。