内容
# PrivAgent
**Private AI Agent — Your data never leaves your machine.**
Vue 3 + FastAPI + LangGraph + PostgreSQL/pgvector
隐私优先的本地 AI Agent。自主决策调用工具（知识库检索、联网搜索、深度研究等），具备长期记忆、SSE 流式输出、MCP 外部工具接入。所有数据本地存储，API key 仅存后端。
[](.)
[](.)
[](.)
[](.)
---
## 为什么值得关注 (Why This Project)
- **完整 Agent 闭环** — 不是简单的 Chatbot。LangGraph 6 节点状态图驱动自主决策：Recall → Plan → Act → Observe → Decide → Summarize。Agent 决定"是否用工具、用哪个工具、何时停止"。
- **6 个内置工具** — 知识库检索（含语义搜索与章节索引策略）、联网搜索、网页抓取、深度研究 (多轮搜索+综合报告)、数学计算、配置诊断
- **MCP 协议支持** — 接入外部 MCP Server (stdio/SSE)，自动发现和注册工具，Agent 即时可用
- **API key 安全** — 前端不接触任何模型 API key。所有敏感配置通过环境变量注入，Provider Profile 后端隔离存储
- **369 个单元测试全部通过** — 覆盖 Agent 全链路、工具注册、SSE 事件、RAG pipeline
- **Docker 一键部署** — `docker compose up -d` 即可启动完整 5 容器栈
---
## 快速开始 (Quick Start)
### 前置要求
- Docker & Docker Compose
- DeepSeek API Key (或其他 OpenAI 兼容 API)
### 1. 配置环境变量
```bash
cp backend/.env.example backend/.env
```
编辑 `backend/.env`，填入必要的 API key：
```bash
# 必填 — 模型对话
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
# 推荐 — 语义检索（不填则退化为关键词匹配）
EMBEDDING_API_KEY=sk-xxxxxxxxxxxx
EMBEDDING_PROVIDER=openai_compatible
EMBEDDING_MODEL=BAAI/bge-m3
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
```
> **安全提示**: API key 仅存后端，不会发送到前端。`.env` 文件不应提交到版本控制。
### 2. 启动
```bash
docker compose up -d
```
### 3. 访问
| 服务 | URL |
|------|-----|
| 前端 | http://127.0.0.1:3000 |
| API | http://127.0.0.1:8000 |
| Swagger | http://127.0.0.1:8000/docs |
| Health | http://127.0.0.1:8000/health |
### 4. 配置 Provider
打开 Settings → 快速配置 → 选择预设（推荐大陆用户选 `DeepSeek + BGE-M3`）→ 填写 API Key → 激活
---
## 架构 (Architecture)
```
┌─ Frontend (Vue 3) ──────────────────────────────────────────┐
│ QuestionView (Agent 问答) SettingsView (配置) │
│ ├─ useAgentChat (SSE 流) ├─ Provider Profile │
│ ├─ 工具卡片 / 来源标注 ├─ MCP 服务管理 │
│ └─ 工具历史 / 对话导出 └─ 记忆管理 / 配置向导 │
└──────────────────────────────┬──────────────────────────────┘
│ SSE / REST
┌──────────────────────────────┴──────────────────────────────┐
│ Backend (FastAPI) │
│ ┌─ Agent Routes ─────────────────────────────────────────┐ │
│ │ /api/v1/agent/chat/stream (SSE 流式 Agent) │ │
│ │ /api/v1/agent/chat/resume (人工审批恢复) │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌─ Agent Service (LangGraph) ────────────────────────────┐ │
│ │ START → recall → plan → act → observe → decide → END │ │
│ │ ↑ ↓ │ │
│ │ summarize ←──────────────────────── │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌─ ToolRegistry (6 tools) ───────────────────────────────┐ │
│ │ kb_search | web_search | web_fetch | deep_research │ │
│ │ calculator | config_status │ │
│ └────────────────────────────────────────────────────────┘ │
│ ┌─ MCPService ───────────────────────────────────────────┐ │
│ │ Stdio/SSE 传输 → 工具发现 → ToolSpec 注册 → 可调用 │ │
│ └────────────────────────────────────────────────────────┘ │
└──────────────────────────────┬──────────────────────────────┘
│
┌──────────────────────────────┴──────────────────────────────┐
│ Storage: PostgreSQL/pgvector | Redis | Local File System │
└─────────────────────────────────────────────────────────────┘
```
---
## Agent 决策流程
```
用户提问
│
▼
[Recall] ← 加载会话历史 + 偏好记忆
│
▼
[Plan] ← LLM 判断: 直接回答? 调工具?
│
├─ 直接回答 → [Summarize] → 返回答案
│
└─ 调工具 → [Act] ← 执行工具 (人工审批 if risk≥local_write)
│
▼
[Observe] ← 记录结果
│
▼
[Decide] ← 继续? 停止? 合成答案?
│
├─ continue → 回到 [Plan]
└─ stop → [Summarize] → 返回答案 (附来源标注)
```
---
## 内置工具
| 工具 | 风险等级 | 说明 |
|------|---------|------|
| `kb_search` | read_only | pgvector 语义搜索 + 可选 DeepSeek Rerank |
| `web_search` | network | Bing 元搜索 (ddgs)，可关闭 |
| `web_fetch` | network | 抓取网页内容，SSRF 保护 |
| `deep_research` | network | 多轮搜索→拆解→抓取→综合报告 |
| `calculator` | read_only | 安全数学表达式计算 |
| `config_status` | read_only | 查询 Provider/Embedding/Rerank 配置状态 |
风险等级 `≥ local_write` 的工具执行前需要人工确认（LangGraph interrupt）。
---
## 支持的文档格式
| 格式 | 解析库 | 说明 |
|------|--------|------|
| `.md` / `.markdown` | 内置 | Markdown 结构保留 |
| `.txt` | 内置 | 纯文本清洗 |
| `.pdf` | pypdf | PDF 文本提取 |
| `.docx` | python-docx | Word 段落 + 表格提取 |
---
## 配置说明
所有敏感配置通过 **环境变量** 注入，不硬编码在代码或配置文件中。
### 环境变量参考 (backend/.env)
| 变量 | 必填 | 说明 |
|------|------|------|
| `DEEPSEEK_API_KEY` | 推荐 | DeepSeek 模型 API key |
| `DEEPSEEK_BASE_URL` | 否 | 模型 API 地址 (默认: https://api.deepseek.com) |
| `DEEPSEEK_MODEL` | 否 | 模型名称 (默认: deepseek-v4-flash) |
| `EMBEDDING_API_KEY` | 推荐 | Embedding 服务 API key |
| `EMBEDDING_PROVIDER` | 否 | `hashing` 或 `openai_compatible` |
| `EMBEDDING_MODEL` | 否 | Embedding 模型名 |
| `EMBEDDING_BASE_URL` | 否 | Embedding API 地址 |
| `RETRIEVAL_RERANK_PROVIDER` | 否 | `none` 或 `deepseek` |
| `APP_VERSION` | 否 | 应用版本号 (默认: 1.0.0) |
| `APP_ENV` | 否 | `dev` 或 `prod` |
完整参考见 [`backend/.env.example`](backend/.env.example)。
### Provider Profile (推荐方式)
通过 Settings 页面配置，支持一键切换：
| 预设 | 模型 | Embedding | 适合场景 |
|------|------|-----------|---------|
| DeepSeek + Hashing | deepseek-chat | 本地 hashing | 快速体验，无需 embedding key |
| DeepSeek + Jina | deepseek-chat | Jina v5 | 海外网络，免费额度 |
| **DeepSeek + BGE-M3** | deepseek-chat | SiliconFlow BGE-M3 | **大陆用户推荐**，国内稳定 |
---
## 部署注意事项
### 安全原则
1. **API key 仅存后端**。`.env` 或 Provider Profile 中的 key 不会发送到前端。
2. **不要暴露端口到公网**。本应用无认证机制。如需远程访问，加 Nginx + HTTPS + Basic Auth。
3. **修改默认密码**。`docker-compose.yml` 中的 PostgreSQL 密码应修改。
4. **`.env` 不提交**。已加入 `.gitignore`，禁止提交真实 API key。
### 搜索引擎
- 默认使用 **Bing** (通过 ddgs 元搜索库)，无需 API Key
- 中国大陆网络下 DuckDuckGo 不可用，Bing 可用
- 切换引擎：修改 `WEB_SEARCH_ENGINE` 环境变量
### 资源需求
| 组件 | 最低配置 |
|------|---------|
| CPU | 2 cores |
| RAM | 4 GB (含 PostgreSQL + Redis) |
| 磁盘 | 2 GB (不含知识库文档) |
---
## MCP 配置 (Model Context Protocol)
接入外部 MCP Server，自动发现工具并注册到 Agent。
### SSE 传输
Settings → MCP 服务 → 新建 → 填写 URL → 连接
### Stdio 传输
```json
{
"name": "local-filesystem",
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
"enabled": true,
"auto_connect": true
}
```
---
## 开发 (Development)
### 本地运行
```bash
# 后端
cd backend
python -m venv .venv
pip install -r requirements.txt
cp .env.example .env # 编辑填入 API key
python -m pytest tests/
# 前端
cd frontend
npm install
npm run dev
```
### 代码质量
```bash
ruff check app/ tests/ # Lint
ruff format app/ tests/ # Format
pytest tests/ -q # 350+ tests, release gate
npm run build # Frontend build
```
### 验证命令
```bash
# Agent eval benchmark
python scripts/agent_eval.py --save-baseline
# Smoke 验证
python scripts/smoke_preflight.py
python scripts/smoke_full_rag.py
```
当前 v1.0.0 发布候选验收结果：`pytest` 369/369、`ruff`、`npm run build`、`smoke_preflight.py`、`smoke_full_rag.py` 均通过；Agent eval 基线为 30/33 (91%)，RAG quality 为 7/9。发布步骤详见 [`Release Checklist`](docs/release-checklist.md)。
---
## 技术决策
1. **LangGraph 替代 LangChain Agent** — 显式状态图完全可控
2. **本地应用无认证** — 不引入 JWT/多用户复杂度
3. **Provider Profile 隔离** — API key 仅后端存储
4. **MCP 作为工具扩展边界** — Agent 工具可无限扩展
5. **环境变量配置优先** — 敏感值不进代码，不进版本控制
---
## License
MIT
