# zendo

**Repository Path**: doublez99/zendo

## Basic Information

- **Project Name**: zendo
- **Description**: 基于 LangGraph 引擎的 agent 管理平台。引擎已本地化，零 pip langchain/langgraph 生态依赖。支持 Web、Electron 桌面端、远程服务器三种部署方式，所有端共享同一份后端数据。


- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent 管理平台

基于 LangGraph 引擎的 agent 管理平台。引擎已本地化，零 pip langchain/langgraph 生态依赖。支持 Web、Electron 桌面端、远程服务器三种部署方式，所有端共享同一份后端数据。

## 项目结构

```
agent/
├── backend/
│   ├── engine/              # Vendored LangGraph 引擎
│   │   ├── langgraph/       # 图编排框架
│   │   ├── langchain_core/  # 核心抽象（messages, runnables）
│   │   ├── langchain_protocol/  # 通信协议
│   │   └── langsmith/       # Tracing 支持
│   ├── llm/                 # LLM Provider + MCP Client + Checkpointer + BM25 + KB Registry + PromptComposer + ContextInjectors + MemoryManager
│   ├── routers/             # FastAPI 路由（auth / agents / models / tools / conversations / stats / mcp / knowledge / memory / checkpoints）
│   ├── services/            # 服务层（compact 上下文压缩 + cleanup 定时清理）
│   ├── tools/               # Tool Registry（builtin + rag + skill + memory + create_agent + list_resources + 文件/命令工具 + permissions）
│   ├── utils/               # 工具函数（tokens 估算）
│   ├── test/                # pytest 测试（unit/ + api/）
│   ├── auth.py              # 认证（单用户模式，设备码自动登录）
│   ├── main.py              # FastAPI 应用入口
│   ├── models.py            # SQLAlchemy ORM（16 业务表 + 3 checkpointer 表，含软删除）
│   ├── database.py          # SQLite 连接 + Fernet 加密 + checkpointer 存储
│   ├── schemas.py           # Pydantic 请求/响应
│   ├── run.py               # 开发服务器启动
│   └── requirements.txt     # 外部依赖
├── frontend/                # Vite + React 19 + TypeScript + shadcn/ui
│   └── src/
│       ├── App.tsx           # 路由入口
│       ├── components/ui/    # shadcn/ui 组件
│       ├── components/graph/ # 自定义 Graph 编辑器
│       ├── hooks/useApi.ts   # API 封装
│       ├── hooks/useAgentCore.ts  # Agent 核心逻辑
│       ├── hooks/useChatStream.ts # SSE 流式处理
│       ├── hooks/useWorkspace.ts  # Workspace 状态管理
│       ├── hooks/AuthContext.tsx  # 认证上下文
│       ├── layouts/AppLayout.tsx  # 侧边栏布局
│       └── pages/            # 13 个页面
├── electron/                # Electron 桌面壳
│   ├── main.js              # 主进程（启动本地后端 或 连接远程服务器）
│   └── preload.js           # 预加载脚本（IPC 桥接）
├── assets/                  # 应用图标
├── Dockerfile               # 后端 Docker 镜像
├── docker-compose.yml       # 一键部署
├── pyinstaller.spec         # PyInstaller 打包配置
├── electron-builder.yml     # Electron-builder 打包配置
└── docs/                    # 技术方案 + 架构文档 + 变更记录
```

## 快速开始

### Web 模式（开发）

```bash
# 1. 安装依赖
make install

# 2. 启动后端（SQLite，零配置）
make run
# → API: http://localhost:9912
# → Swagger: http://localhost:9912/docs

# 3. （可选）启动前端 dev server（热更新）
cd frontend && npm run dev
# → UI: http://localhost:5173
```

首次启动自动在 `~/.zendo/app.db` 创建 SQLite 数据库。可通过 `ZENDO_HOME` 环境变量自定义数据目录。

### 服务器部署（Docker）

```bash
docker compose up -d
# → API: http://<server>:9912
# → Health: http://<server>:9912/health
```

数据持久化在 Docker volume `zendo_data`。

前端静态文件部署到 nginx 后，Web 用户打开页面进入 Settings → Add Server，填入远程服务器 URL 和 API Key 即可连接。API Key 通过 `ZENDO_API_KEY` 环境变量设置。

### 桌面端（Electron）

```bash
# 一键本地桌面端测试
make dev

# 一键打包 macOS .dmg
make build
# → 产物在 dist-release/Zendo-0.1.0-mac.dmg
```

桌面端支持多服务器一键切换：
- **本地模式**（默认）：Electron 内启动本地 Python 后端，数据存本地 SQLite
- **远程模式**：在 Settings 页添加多台远程服务器（URL + API Key），保存后可随时一键切换，配置持久化不会丢失

## 运行测试

```bash
# 快速测试（零网络，零花费）
make test

# 全量测试（含真实 LLM 调用）
make test-slow
```

## API 概览

### Auth

| Method | Path | 说明 |
|--------|------|------|
| POST | /auth/login | 设备码登录（单用户模式） |
| GET | /auth/me | 当前用户信息 |

### Agent 管理

| Method | Path | 说明 |
|--------|------|------|
| POST | /agents | 创建 agent |
| GET | /agents | agent 列表 |
| GET | /agents/{id} | agent 详情 |
| PUT | /agents/{id} | 更新 agent |
| DELETE | /agents/{id} | 删除 agent |
| POST | /agents/{id}/invoke | 非流式调用 agent（202=中断，200=完成） |
| POST | /agents/{id}/stream | 流式调用 agent (SSE) |
| POST | /agents/{id}/stream/cancel | 取消进行中的流式会话 |
| GET | /agents/{id}/runs | Agent Run 历史列表 |
| GET | /agents/{id}/runs/{run_id} | Run 详情 |
| POST | /agents/{id}/runs/{run_id}/approve | HITL 中断恢复（提交用户输入） |

支持自定义 Graph 编排：llm / code / condition / human / tool / fork / map 7 种节点类型，条件路由（expression），HITL 中断，并行分支（Fork/Map + Send API）。支持 context（多轮对话）和 oneshot（单次执行）两种运行模式。

### Agent-Tool 绑定

| Method | Path | 说明 |
|--------|------|------|
| POST | /agents/{id}/tools | 绑定 Tool 到 Agent |
| GET | /agents/{id}/tools | Agent 绑定的 Tool 列表 |
| DELETE | /agents/{id}/tools/{binding_id} | 解绑 |

### Tool CRUD

| Method | Path | 说明 |
|--------|------|------|
| POST | /tools | 创建 Tool |
| GET | /tools | Tool 列表（可按 tool_type 筛选） |
| GET | /tools/{id} | Tool 详情 |
| PUT | /tools/{id} | 更新 Tool |
| DELETE | /tools/{id} | 删除 Tool |

### Model 管理

| Method | Path | 说明 |
|--------|------|------|
| POST | /models | 添加 LLM provider |
| GET | /models | provider 列表 |
| GET | /models/{id} | provider 详情 |
| PUT | /models/{id} | 更新 provider |
| DELETE | /models/{id} | 删除 provider |
| POST | /models/{id}/test | 测试已保存模型连通性 |
| POST | /models/test | 测试 provider 连通性（ad-hoc） |

### Conversation 管理

| Method | Path | 说明 |
|--------|------|------|
| POST | /conversations | 创建对话（agent_id + working_dir） |
| GET | /conversations | 对话列表（可按 agent_id 筛选，keyword 搜索，sort=asc\|desc） |
| PUT | /conversations/{id} | 重命名对话 |
| GET | /conversations/{id}/messages | 对话消息列表（含 tool 消息） |
| DELETE | /conversations/{id} | 删除对话（级联删除消息） |

### MCP Server 管理（进程主管）

| Method | Path | 说明 |
|--------|------|------|
| POST | /mcp/servers | 创建 MCP Server |
| GET | /mcp/servers | MCP Server 列表 |
| GET | /mcp/servers/{id} | MCP Server 详情 |
| PUT | /mcp/servers/{id} | 更新 MCP Server |
| DELETE | /mcp/servers/{id} | 删除 MCP Server |
| POST | /mcp/servers/{id}/start | 启动 MCP Server 进程 |
| POST | /mcp/servers/{id}/stop | 停止进程 |
| POST | /mcp/servers/{id}/restart | 重启进程 |
| GET | /mcp/servers/{id}/logs | 获取 stdout/stderr 日志 |

进程主管特性：setsid 进程隔离、crash 检测 + 自动重启、健康检查、日志落盘。

### Knowledge Base 管理（RAG）

| Method | Path | 说明 |
|--------|------|------|
| POST | /knowledge/ | 创建知识库 |
| GET | /knowledge/ | 知识库列表（支持 search） |
| GET | /knowledge/{id} | 知识库详情（含文档数/chunk 数） |
| PUT | /knowledge/{id} | 更新知识库 |
| DELETE | /knowledge/{id} | 软删除知识库 + 级联文档 |
| POST | /knowledge/{id}/documents | 上传文档（TXT/MD），异步分块 |
| GET | /knowledge/{id}/documents | 文档列表 |
| DELETE | /knowledge/{id}/documents/{doc_id} | 删除文档 + 级联 chunks |
| GET | /knowledge/{id}/documents/{doc_id}/chunks | 查看文档 chunk 列表 |
| GET | /knowledge/{id}/search?q=xxx&top_k=5 | BM25 检索测试 |
| POST | /knowledge/{id}/bind/{agent_id} | 绑定 Agent |
| DELETE | /knowledge/{id}/bind/{agent_id} | 解绑 Agent |
| GET | /knowledge/{id}/agents | 已绑定 Agent 列表 |

检索模式：BM25（纯 Python，零外部依赖），架构预留 semantic / hybrid 扩展点。

### Memory 管理

| Method | Path | 说明 |
|--------|------|------|
| POST | /memory/ | 创建记忆条目 |
| GET | /memory/ | 记忆列表（可按 agent_id / thread_id 筛选） |
| GET | /memory/{id} | 记忆详情 |
| PUT | /memory/{id} | 更新记忆 |
| DELETE | /memory/{id} | 软删除记忆 |
| POST | /memory/search | 语义搜索记忆（BM25） |

Memory 支持 fact / preference / event / reference 四种类型，按 agent_id 隔离，同一 agent 的多轮对话共享记忆。

## 支持的 LLM Provider

| Provider | 协议 | 需要 base_url |
|----------|------|---------------|
| DeepSeek | OpenAI 兼容 | 否 |
| OpenAI | OpenAI 兼容 | 否 |
| Anthropic | Anthropic Messages API | 否 |
| Ollama | OpenAI 兼容 | 是 |
| 智谱 AI | OpenAI 兼容 | 否 |
| Groq | OpenAI 兼容 | 否 |

API Key 使用 Fernet 加密存储，密钥来自 `ENCRYPTION_KEY` 环境变量或自动生成。

对话连续性由 LangGraph Checkpointer（SQLite）管理，支持断点续传和 Time Travel。

## 技术栈

- **后端**: FastAPI + SQLAlchemy 2.0 + SQLite（aiosqlite）
- **引擎**: Vendored LangGraph（无需 pip install）
- **前端**: Vite + React 19 + TypeScript + shadcn/ui
- **桌面壳**: Electron 35，支持本地/远程双模式
- **部署**: Docker + docker-compose
- **打包**: PyInstaller + electron-builder
- **测试**: pytest + pytest-asyncio + httpx

## 环境要求

- Python >= 3.12
- Node.js >= 18