看得见、摸得着、能动手的桌面 AI 工作站。基于 ReAct Agent + 子 Agent 分层架构，一个引擎统一服务 Web / 桌面 / IM 三大入口。
💡 项目介绍 · 📊 对比 · 🧠 核心能力 · 🖥️ 远程工作区 · 🚀 快速开始 · 💬 反馈 · 🤝 加入社区
English · Gitee · GitHub · GitCode
GuaDa 是一个本地优先的开源 AI 工作站——它不只是聊天框，而是一个能动手干活的 AI 工作台：读写文件、执行命令、操控内嵌浏览器，任务从规划到执行自动闭环。
一套 Agent 引擎，三种使用方式：桌面端开箱即用，Web 端可私有化部署，QQ / 企业微信 / 飞书 / Discord / 微信 群里也能直接召唤。配合 RAG 知识库、长期记忆和定时任务，它能记住你的资料、按你的习惯工作、在你睡觉时继续干活。数据默认存在你自己的机器上，安全可控。
需要动用服务器、NAS、虚拟机、开发板上的文件时，它还能在同一个会话里把多台机器挂载进来——AI 留在本机，只把手伸进去。详见 🖥️ 远程工作区。
无论你是写脚本追热点的新媒体人、想让 Agent 代写代码的程序员、需要它记住人物设定的创作者，还是想搭一个绑定知识库、接入 IM 的内部 AI 助手的团队——GuaDa 都能直接上手。如果这个项目对你有帮助，欢迎点亮 Star ⭐，你的支持是持续更新的动力。
| 维度 | GuaDa | Claude Code | Codex | Trae Work |
|---|---|---|---|---|
| 产品定位 | 🏠 通用 AI 工作站 | 💻 编程 Agent | 💻 编程 Agent | 📋 AI 任务执行平台 |
| 开源 | ✅ | ❌ | ✅ CLI | ❌ |
| 自托管 Web 部署 | ✅ | ❌ | ❌ | ❌ |
| Desktop 桌面端 | ✅ | ✅ | ✅ | ✅ |
| CLI | ❌ | ✅ | ✅ | |
| Bot / IM 接入 | ✅ QQ·企微·飞书·Discord·微信 | ❌ | ❌ | ❌ |
| 知识库 (RAG) | ✅ 混合检索·40+ 格式 | ❌ | ❌ | |
| 浏览器自动化 | ✅ 内嵌·可视操控 | ✅ 内嵌·可视操控（2026.7） | ||
| 沙盒 | ✅ 轻沙盒 | ✅ 文件+网络双隔离 | ✅ 云端容器+本地 | ✅ 云端容器+本地文件权限 |
| 远程 / 多机开发 | ✅ 直连自己的服务器·NAS·虚拟机·开发板，本地与多台远程同会话 | |||
| 长期记忆 | ✅ 可编辑可回退 | ❌ | ||
| 定时任务 | ✅ | ❌ | ❌ | ❌ |
| 多Agent | ✅ 全能力独立配置（角色/模型/工具/知识库） | ❌ | ||
| 多模型支持 | ✅ 17 家厂商·含国产模型 | ❌ 仅 Claude | ❌ 仅 OpenAI | |
| 数据本地可控 | ✅ | ❌ | ❌ | ❌ |
| 配置难易 | ⭐⭐⭐⭐ 开箱即用 | ⭐⭐⭐ 登录即用 | ⭐⭐⭐ API Key 即用 | ⭐⭐⭐⭐⭐ 登录即用 |
| 费用 | 免费（自备 Key） | $20+/月 | $20+/月 | 内测免费 |
| 能力 | 亮点说明 | 文档 |
|---|---|---|
| 🤖 智能体（Agent） | ReAct 多轮自治循环 + 子 Agent 分层委派，支持会话锁、流式传输、中断处理与三种再生模式 | → 详情 |
| 👥 子 Agent 系统 | 全能力独立配置（角色/模型/工具/知识库），复杂任务自动拆解 → 委派执行 → 结果归集 | → 详情 |
| 🔌 插件系统 | 核心功能全部插件化（浏览器/文件/搜索/记忆/定时任务/角色等），PluginBase 生命周期 + 热插拔即时生效，工具包级权限过滤 | — |
| 📚 知识库 (RAG) | 语义 + 关键词双混合检索，Agent 自助多轮搜索与写入，支持 40+ 文件格式（含 OCR） | → 详情 |
| 🧠 长期记忆 | 两级压缩（裁剪→语义），可编辑、可回退、有历史，非破坏性压缩 | → 详情 |
| 🛠️ 技能管理 | 文件即技能，chokidar 热更新即时生效，渐进式加载省 Token | → 详情 |
| ⏰ 定时任务 | Agent 按 Cron 自动执行，独立会话隔离，完整执行记录 | → 详情 |
| 🤖 Bot 网关 | 统一接入 QQ / 企业微信 / 飞书 / Discord / 个人微信，自动重连、消息合并、动态启停 | → 详情 |
| 🌐 浏览器自动化 | Electron 内嵌 Chromium，Agent 实时可视操控。 | → 详情 |
| 🧩 多模型管理 | 5 种协议适配器 × 17 家厂商（OpenAI / Claude / Gemini / Azure / DeepSeek / 通义 / 文心 / 智谱 / Kimi / 火山 / Minimax 等），角色级/会话级/全局级配置 | → 详情 |
| 🛡️ 沙箱模式 | Shell 命令经独立沙箱进程隔离执行，Agent 动手更安全 | → 详情 |
| 🖥️ 远程工作区 | 把服务器·NAS·虚拟机·开发板（SSH）与运行中的 Docker 容器挂成「附加工作目录」，本地与多台远程同一会话；远端只需一个约 10MB 的静态二进制，容器零侵入 | → 详情 |
| 🔗 MCP 集成 | 原生支持 MCP 协议，接入外部工具生态 | — |
| 📦 多部署方式 | Electron 桌面 + Web 应用 + Docker 容器化，开箱即用 | → 部署指南 |
| 🗄️ 企业级数据 | 默认 SQLite，Prisma 7 ORM 可无缝切换 MySQL / PostgreSQL | — |
| 🎨 自定义壁纸 | 自定义背景、透明度、毛玻璃效果，打造你的专属工作站 | — |
不把开发环境搬到服务器上，只把 AI 的手伸进去。 主工作目录始终在本地，远程目录作为「附加工作目录」挂进同一个会话——本地和多台远程机器同时可用，AI 用 workspace="连接名" 指定在哪台机器上动手。
两种可挂载的目标：SSH 远程主机（服务器 / NAS / 虚拟机 / 开发板）与运行中的 Docker 容器（devcontainer、docker compose 起的服务等）。
嵌入式 Linux 开发是这套设计的典型主场：Windows 上位机管编辑、串口与烧写，每个项目一台 Linux 虚拟机管交叉编译，板端管运行——三层缺一不可，而 AI 只需要一个入口。
| 嵌入式开发的三层 | 它承担什么 | 在 GuaDa 里 |
|---|---|---|
| Windows 上位机 | IDE、串口工具、烧写与调试工具 | 主工作目录：AI 就在本机，烧写脚本与调试工具随手可调 |
| 每个项目的 Linux 虚拟机 | 交叉编译、SDK/BSP、内核源码 | 附加远程目录：直接改源码、跑 make，虚拟机里不用装任何东西 |
| 板端 / 目标设备 | 设备树、rootfs、内核模块、串口日志 | 附加远程目录：读 dmesg、换 .ko，可设为只读 |
- 8BD0 端零依赖：执行代理是单个静态二进制（约 10MB，无 cgo，不依赖 Node 与 glibc），现有构建覆盖 linux / macOS × amd64 / arm64，老 glibc 的精简系统同样能跑。
- 容器零侵入：接入已有容器（如 VS Code devcontainer）时，代理经
docker cp注入容器内/tmp并以 stdio 管道通信——不改镜像、不加端口映射、容器重启即自动重连，GuaDa 也绝不停止或删除你的容器。 - 一个会话，多台机器：本地 + 多台远程同时挂载，跨机器对比、补丁移植、日志与源码对照都在一轮对话里完成。
- 模型与密钥不出本机：远端只握有一个 Bearer token；定时任务与子 Agent 会自动继承会话的远程绑定，无人值守也照样跑。
- 权限在服务器侧强制：
readonly / workspace / unrestricted三档，默认「工作目录内可读写、目录外只读」，写操作前解析符号链接防逃逸。 - 不挑 sshd 配置：agent ≥ 0.6.0 时走 SSH exec 通道（stdio 管道），不再要求 sshd 允许端口转发——实测 Alpine 的 openssh 默认关闭转发，旧方案在这种环境下直接连不上；旧版 agent 自动回退端口转发链路，不做强制升级。
- 对远端零侵入：连接断开即退出、不留常驻进程；NAS 的
$HOME不存在、SFTP 被 chroot 等实际坑位已内置回退（安装目录自动降级、改走 exec 通道上传并校验字节数）。
设计文档：主工作目录与附加工作目录统一操作接口 · Docker 容器工作区方案
git clone https://gitee.com/zhendongdong/guada_ai.git
cd guada_ai
docker compose up -d --build
# 打开浏览器访问 http://localhost:8787
# 开始跟你的 AI 助手对话！下载预编译安装包（见 QQ 群 1047993501），或从源码构建：
pnpm install
pnpm run build:electron # 安装包输出在 release/ 目录macOS（Apple Silicon）安装注意：安装包带自签名证书、但未做 Apple 公证，从浏览器 下载后首次打开会被系统拦截（提示「无法验证开发者」，或「已损坏，无法打开」）—— 这是 Gatekeeper 的拦截，不是文件损坏。把 GuaDa 拖进「应用程序」后，先在「终端」执行：
xattr -cr /Applications/GuaDa.app再正常双击打开即可。若仍提示「已损坏」，追加一次本机 ad-hoc 重签（无需任何证书）：
codesign --force --deep --sign - /Applications/GuaDa.app原理与更多细节见 Electron 部署文档 4.1 / 4.2。
Windows：直接运行安装包即可；未签名的安装包可能触发 SmartScreen 提示 （「Windows 已保护你的电脑」），选择「更多信息 → 仍要运行」继续。
# 终端 1：启动后端（首次需初始化数据库）
cd backend-ts
pnpm install
pnpm run db:seed:force
pnpm run start:dev
# 终端 2：启动前端
cd frontend
pnpm install
pnpm run dev
# 访问 http://localhost:5173更多部署细节：Docker 部署 · Electron 部署 · 生产环境部署 · 快速上手
架构四层： 前端入口 → 入口层 → 核心服务层 → 数据层
| 层级 | 职责 | 核心组件 |
|---|---|---|
| 前端入口 | 用户交互 | Vue 3、Electron（内嵌 Chromium）、QQ/企微/飞书/Discord/微信 Bot |
| 入口层 | 路由与协议转换 | REST + SSE API、Bot Gateway、Bridge（命名管道 ↔ Electron） |
| 核心服务层 | Agent 引擎 + 子 Agent + 插件 + RAG + Skills + LLM 适配 | Agent Engine（ReAct 循环）、Sub-Agent Manager、插件系统、Skills 框架、上下文压缩、RAG、MCP、定时任务、Shell 沙箱、远程工作区（SSH / Docker 容器）、LLM 适配器 |
| 数据层 | 持久化存储 | SQLite（Prisma 7，可切换 MySQL/PostgreSQL）、sqlite-vec + FTS5、文件系统 |
浏览器自动化链路：Agent 决策（后端）→ 命名管道 Bridge → Electron 操控内嵌 Chromium → 无障碍快照 6 层压缩回传 → Agent 继续推理。
ai_chat/
├── backend-ts/ # NestJS 后端
│ ├── prisma/schema.prisma # 数据库 Schema
│ ├── src/
│ │ ├── common/ # 基础设施（数据库、向量库、MCP、日志、工具函数）
│ │ └── modules/
│ │ ├── chat/ # ⭐ 核心对话（Agent 引擎、压缩、上下文、审批）
│ │ ├── sub-agent/ # ⭐ 子 Agent 系统（分层委派、前台/后台）
│ │ ├── plugins/ # ⭐ 插件系统（PluginBase、热插拔、工具包级权限）
│ │ ├── skills/ # ⭐ Skills 技能框架（文件即技能、热更新）
│ │ ├── knowledge-base/ # ⭐ 知识库（RAG、分块、向量化、OCR）
│ │ ├── llm-core/ # LLM 适配层（5 协议 × 17 厂商）
│ │ ├── bot-gateway/ # 机器人网关（QQ/企微/飞书/Discord/微信）
│ │ ├── scheduler/ # 定时任务（Cron、会话隔离）
│ │ ├── shell/ # Shell 执行 + 轻沙箱
│ │ ├── remote-workspace/ # ⭐ 远程工作区（SSH / Docker 容器附加目录、工具路由、部署与 RPC）
│ │ ├── bridge/ # 命名管道通信（↔ Electron）
│ │ ├── tools/ # 工具编排
│ │ ├── mcp-servers/ # MCP 服务器集成
│ │ ├── commands/ # 斜杠命令
│ │ ├── characters/ # 角色管理
│ │ └── ... # auth、files、models、settings、users
│ └── main.ts
├── frontend/ # Vue 3 前端（Vite + Pinia + Element Plus + Tailwind 4）
├── electron/ # Electron 桌面端（内嵌 Chromium 浏览器自动化）
├── sandbox/ # 沙箱进程（sandbox.exe）
├── guada-agent/ # 远程执行代理（Go 静态二进制，部署到远端）
├── docs/ # 文档
└── LICENSE
遇到问题？想交流技术？下载预编译客户端？来这里：
|
🐧 QQ 群：1047993501 |
💬 微信群 |
📱 公众号：冬瓜编程实验室 |
⭐ 点个 Star 支持项目（你的鼓励是持续更新的动力 ❤️）
本项目基于 MIT License 开源，可自由使用、修改和商用。
如果 GuaDa 对你有帮助，欢迎在 Gitee 上点个 Star ⭐
你的每一次 Star，都是让这个项目变得更好的动力