# deepagents **Repository Path**: joaquin1473/deepagents ## Basic Information - **Project Name**: deepagents - **Description**: AI 智能助手应用 — FastAPI 后端 + React 前端 + Tauri 桌面集成 - **Primary Language**: Python - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2025-12-16 - **Last Updated**: 2026-08-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ZhiXia
**把一次对话,沉淀为可复用的能力 — 本地优先的 AI 工作站** FastAPI 后端 + React 前端 + Tauri 桌面壳 [![Python](https://img.shields.io/badge/Python-3.11.9+-blue)](https://www.python.org/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green)](https://fastapi.tiangolo.com/) [![React](https://img.shields.io/badge/React-18+-cyan)](https://react.dev/) [![Tauri](https://img.shields.io/badge/Tauri-2-orange)](https://tauri.app/) [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
## 为什么是 ZhiXia 普通 AI 聊天工具用完即弃——每次都要重新解释上下文、重新交代流程。ZhiXia 把**「对话」变成「能力」**:一段反复出现的交互,可以沉淀为技能(带脚本)、提示词、或可视化工作流,下次一键复用。这是 ChatGPT / DeepSeek 官网给不了你的,也是 ZhiXia 的核心差异化。 所有数据留在本地(SQLite + 文件沙箱,全 `127.0.0.1` 通信),适合对数据自主有要求的开发者与知识工作者。 ## ✨ 特性 - 🧩 **能力沉淀(核心差异化)** — 技能(Skill,可带脚本/venv)/ 提示词(Prompt)/ 工作流(Workflow,可视化 DAG)**三类可复用能力,对话内即可创建,下次一键触发** - 🤖 **智能对话** — 基于 LangChain / deepagents 的 AI Agent，支持工具调用与流式输出 - 🛠️ **MCP 工具集成** — TAPD 项目管理、XWiki 文档管理（数据库驱动，Settings 可配置） - 🧠 **记忆系统** — 纯后台自动记忆：跨会话偏好/洞见提取 + 统一检索（FTS + 可选语义） + 跨源去重 + 时间衰减 + 存储淘汰 - 🖥️ **桌面专属** — Tauri 2 轻量桌面应用(Rust 壳 + 系统 WebView),系统托盘常驻 + **全局快捷键 Alt+Space 一键唤起** - 💬 **多会话管理** — 会话历史持久化（SQLite），随时回看延续 - 📂 **文件沙箱** — 安全的文件上传与隔离机制 - 💾 **SQLite (WAL)** — 轻量级关系数据库，零运维 ## 📁 项目结构 ``` deepagents/ ├── backend/ # FastAPI 后端服务 │ ├── app/ │ │ ├── core/ # 配置、异常、路径 │ │ ├── routes/ # API 路由（薄处理层） │ │ ├── services/ # 业务逻辑 │ │ ├── models/ # Pydantic 请求/响应模型 │ │ ├── database/ # SQLite + SQLAlchemy (async) │ │ ├── mcp/ # MCP 工具/服务管理 (manager.py) │ │ ├── memory/ # 长期记忆系统 │ │ ├── tools/ # 内置工具 │ │ ├── events/ # 事件/流式处理 │ │ ├── middleware/ # 中间件 │ │ └── utils/ │ ├── main.py # 应用入口（uv run python main.py） │ ├── mcp_config.json # MCP 服务器配置（集中管理） │ ├── pyproject.toml # Python 依赖（uv） │ └── data/ # 运行时数据（已 gitignore） │ ├── frontend/ # React 18 + Vite + TypeScript │ ├── src/ │ │ ├── pages/ # 页面组件 │ │ ├── components/ # UI 组件 │ │ ├── stores/ # Zustand 状态管理 │ │ ├── hooks/ # React Hooks │ │ ├── api/ # 共享 Axios 客户端 │ │ ├── types/ # TS 类型 │ │ └── utils/ │ └── package.json │ ├── src-tauri/ # Tauri v2 桌面壳层（Rust） │ ├── src/ # lib.rs / commands.rs / sidecar/（Python 进程管理） │ ├── binaries/ # 生产 sidecar：zhixia-server.exe │ ├── icons/ # 应用图标 │ ├── tauri.conf.json # Tauri 配置（CSP / 窗口 / 打包） │ └── Cargo.toml │ ├── tests/ # 根级 Python 测试（token 优化等） ├── docs/ # 项目文档（见 docs/README.md） └── scripts/ # Windows 开发/打包脚本（dev-tauri / build-tauri） ``` ## 🚀 快速开始 ### 环境要求 - **Python 3.11.9+** - **Node.js 24+**（frontend 通过 Volta 锁定） - **uv**（Python 包管理器，必需） - **Rust (stable-msvc) + MSVC C++ Build Tools**（编译 Tauri 壳，仅桌面开发/打包需要） - Git ### 1. 安装 uv（如未安装） ```bash # Windows (PowerShell) powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Linux/macOS curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 2. 安装依赖 ```bash # 后端依赖（在仓库根目录） uv sync # 前端依赖 cd frontend && npm install && cd .. ``` ### 3. 配置（数据库驱动，无 .env 文件） 所有业务配置都通过 Settings 界面管理，存 SQLite 数据库，支持热重载： - **LLM Provider / 任务模型** — Settings → Provider 管理 / 任务模型分配（三条任务管线：agent 主对话、processing 压缩·OCR·记忆、embedding 向量检索） - **MCP 服务** — Settings → MCP 服务（首次播种 `mcp_config.json`，之后只读数据库） - **OCR / Embedding** — 已硬编码为企业 ollama 端点（单一真相源 `backend/app/core/ollama.py`），无需配置 - **工具集 / 提示词 / 技能 / 助手** — Settings 各分类 系统级配置（数据目录、端口）由 Tauri 壳层以进程环境变量注入（`ZHIXIA_*`），开发态用默认值，无需任何 `.env` 文件。 ### 4. 启动服务 **方式 1：一键启动（Windows，推荐）** ```bash scripts\dev-tauri.bat ``` **方式 2：手动启动（3 个终端）** ```bash # 终端 1 — 后端 uv run python backend/main.py # 终端 2 — 前端 cd frontend && npm run dev # 终端 3 — Tauri 壳 cd src-tauri && cargo tauri dev ``` **访问地址** | 服务 | 地址 | |------|------| | 前端开发服务器 | http://localhost:3712 | | 后端 API | http://localhost:37120 | | API 文档 (Swagger) | http://localhost:37120/docs | ## 🛠️ MCP 配置 MCP 服务器在首次启动时从 `backend/mcp_config.json` 播种到数据库，之后由 Settings「MCP 服务」管理（运行时只读数据库，改该 JSON 无效）。出厂默认 tapd / wiki（streamable-http），Bearer Token 经 `${MCPHUB_AUTH_TOKEN}` 环境变量注入。 ## 📦 打包桌面应用 详见 [打包指南](docs/BUILD_GUIDE.md)。 ```bash # 一键打包（Windows） scripts\build-tauri.bat # 清理构建产物 scripts\clean.bat ``` ## 🧪 测试 ```bash # 前端单元测试 cd frontend && npm run test:run # 后端 Python 测试 cd backend && uv run pytest tests ``` ## 📖 文档 - [开发指南](DEVELOPMENT.md) — 开发流程、环境、调试 - [系统架构](docs/ARCHITECTURE.md) - [Memory 系统](docs/MEMORY_SYSTEM.md) - [打包指南](docs/BUILD_GUIDE.md) - [文档总索引](docs/README.md) ## 🧰 技术栈 **后端**：FastAPI · Uvicorn · SQLAlchemy (async) · aiosqlite · LangChain · deepagents · MCP · Pydantic · structlog · uv **前端**：React 18 · TypeScript · Vite · Ant Design · Zustand · React Router · ECharts · Mermaid · KaTeX **桌面**：Tauri v2（Rust 壳层，管理 Python sidecar）· 系统 WebView2 **MCP**：streamable-http (tapd/wiki) · 数据库驱动，Settings 抽屉可配置 ## 📦 数据存储位置 **开发环境** - 数据库：`backend/data/`（运行时生成，已 gitignore） - 上传文件：`backend/uploads/` - 文件沙箱：`backend/data/sandbox/` **生产环境（打包后，Windows）** - `%APPDATA%\zhixia\data\` — 数据库 `zhixia.db` + 文件沙箱 `sandbox/` + 日志 > 桌面应用当前以 Windows（NSIS 安装包）为打包目标。数据目录根名为 `zhixia`。 ## 🐛 故障排除 | 现象 | 排查 | |------|------| | 后端启动失败 | 确认 `python --version >= 3.11.9`；`uv sync` 后 `uv run python backend/main.py` 看日志 | | MCP 调用 401 | Settings → MCP 服务里对应 server 的 auth token 是否配置（存数据库） | | `cargo` 编译超时 / `link.exe` 未找到 | 国内配 rsproxy 镜像；装 MSVC C++ Build Tools（详见 [打包指南](docs/BUILD_GUIDE.md#常见问题)） | 更多调试技巧与常见问题见 [开发指南](DEVELOPMENT.md)。 ## 📝 许可证 MIT License — 详见 [LICENSE](LICENSE)。