# AgentFor

**Repository Path**: yzj1/agent-for

## Basic Information

- **Project Name**: AgentFor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentFor

AgentFor 是一个通用智能体应用平台，面向个人开发者、企业团队以及二次开发者。它采用“核心引擎 + 配置扩展 + 可替换实现”的分层架构，帮助用户快速搭建、扩展和私有化部署基于大模型的 Agent 应用。

---

## 产品定位

AgentFor 借鉴 [Eino](https://github.com/cloudwego/eino) 的设计思想，后端采用 **Python 3.11 + FastAPI** 生态，前端使用 **Vue 3 + Element Plus**，提供完整的可视化配置与 API 能力。

无论是企业知识库问答、员工权限管理、操作审计，还是个人开发者快速搭建 Agent、学习 Agent 工程化，AgentFor 都可以作为可二次开发的底座。

---

## 功能特性

| 菜单 | 能力说明 |
|------|---------|
| 仪表盘 | 展示运行指标、用户/角色/知识库统计、最近操作 |
| 对话 | 与智能体多轮对话，支持选择角色、Markdown 渲染 |
| 角色 | 创建/编辑智能体角色，配置人设、系统提示、绑定工具/知识库/模型，支持角色能力升级 |
| 模型 | 模型 Provider 与模型配置管理（OpenAI、DeepSeek、Ollama 等），支持自动模型发现 |
| MCP | 配置 MCP Servers，工具发现、启用禁用 |
| Skills | 配置函数/HTTP/工作流类型的技能，支持热更新 |
| 知识库 | 文档上传、解析、切片、向量化、检索 |
| 用户管理 | 用户、角色、权限（RBAC） |
| 日志审计 | 操作日志与调用日志查询 |
| 机器人设置 | 机器人装配、系统参数配置 |
| 通知策略 | 通知渠道与告警策略管理 |
| 任务调度 | 定时任务创建、执行与调度管理 |
| 服务管理 | 智能体服务发布与对外开放 |
| Agent API | 对外 Agent 调用接口管理 |
| 记忆 | 对话记忆与上下文管理 |

---

## 技术栈

| 层次 | 技术 |
|------|------|
| 后端 | Python 3.11 + FastAPI + SQLAlchemy 2.0 + Pydantic v2 |
| 数据库 | SQLite（默认）/ PostgreSQL（生产） |
| 向量库 | Chroma（默认）/ Milvus / Qdrant 可扩展 |
| 模型 | 统一封装，支持 OpenAI、DeepSeek、Ollama、Claude 等 |
| 认证 | JWT + RBAC |
| 任务调度 | APScheduler |
| 前端 | Vue 3 + Element Plus + Pinia + Vue Router |
| 构建 | Vite |
| 部署 | Docker + Docker Compose（已支持） |

---

## 快速开始

### 1. 环境要求

- Python 3.11
- Node.js 18+
- conda（推荐）或 venv
- Docker + Docker Compose（可选，用于容器化部署）

### 2. 一键安装并启动（推荐）

**Linux / macOS**

```bash
cd AgentFor
./install.sh   # 首次安装：自动安装 Conda、Node.js、依赖、构建前端、下载模型
./start.sh     # 启动前后端
```

**Windows（PowerShell）**

```powershell
cd AgentFor
.\install.ps1   # 首次安装
.\start.ps1     # 启动前后端
```

> 首次启动会自动生成 `SECRET_KEY` 与 `ENCRYPTION_KEY` 并写入 `backend/.env`，无需手动配置。

- 后端访问：http://localhost:8002
- 前端访问：http://localhost:5173
- 后端 API 文档：http://localhost:8002/docs

停止服务：

```bash
./stop.sh
```

### 3. 手动启动后端

```bash
cd backend

# 创建并激活 conda 环境
conda create -n agentfor python=3.11 -y
conda activate agentfor

# 安装依赖
pip install -r requirements.txt

# 启动服务（默认端口 8002）
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8002
```

后端 API 文档：http://localhost:8002/docs

### 4. 手动启动前端

```bash
cd frontend

npm install
npm run dev
```

前端访问地址：http://localhost:5173

### 5. Docker 部署

```bash
# 构建并启动全部服务（首次启动会自动生成安全密钥）
docker compose up -d --build
```

- 前端访问：http://localhost
- 后端 API：http://localhost:8002

容器说明：

- `agentfor-backend`：后端服务，端口 `8002`
- `agentfor-frontend`：前端 nginx 服务，端口 `80`
- 数据目录 `./data` 与配置目录 `./config` 已挂载到宿主机持久化

### 6. 默认账号

- 用户名：`admin`
- 密码：`admin123`

---

## 项目结构

```
AgentFor/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/             # REST API 路由与 Schema
│   │   ├── services/        # 应用服务（Agent、MCP、Skill、RAG、任务调度等）
│   │   ├── domain/          # 领域模型（User、Role、Model、MCP、Skill 等）
│   │   ├── adapters/        # 基础设施适配器（LLM、Vector Store、Embedding）
│   │   ├── config/          # 配置中心与热更新
│   │   ├── infrastructure/  # 数据库、审计、用量统计等基础设施
│   │   ├── core/            # 安全、限流、SSRF、上传、MCP 安全等核心能力
│   │   └── main.py          # FastAPI 入口
│   ├── alembic/             # 数据库迁移
│   ├── scripts/             # 迁移、模型下载等运维脚本
│   ├── tests/               # 后端测试用例
│   ├── pytest.ini           # pytest 配置
│   ├── config/              # 运行时配置文件
│   ├── data/                # 数据目录（数据库、向量库、上传文件）
│   └── requirements.txt
├── frontend/                # 前端服务
│   ├── src/
│   │   ├── views/           # 页面视图
│   │   ├── api/             # 自动生成的 API 客户端
│   │   ├── router/          # 路由配置
│   │   ├── store/           # 状态管理
│   │   ├── components/      # 公共组件
│   │   └── utils/           # 工具函数
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── package.json
│   └── vite.config.ts
├── .env.example             # 环境变量示例
├── docker-compose.yml       # Docker Compose 部署配置
├── start.sh                 # 一键启动脚本
├── stop.sh                  # 一键停止脚本
├── Makefile                 # 常用运维命令
├── PLANNING.md              # 开发规划文档
├── ITERATION.md             # 后续优化与迭代计划
├── AGENTS.md                # 工程规范（面向开发/运维人员）
└── README.md                # 本文件
```

---

## 开发流程

1. 后端新增或修改接口后，重新生成 `swagger.json`：

```bash
cd backend
python -c "
import json
from app.main import app
from fastapi.openapi.utils import get_openapi

openapi_schema = get_openapi(
    title=app.title,
    version=app.version,
    description=app.description,
    routes=app.routes,
)

with open('../frontend/swagger.json', 'w', encoding='utf-8') as f:
    json.dump(openapi_schema, f, ensure_ascii=False, indent=2)

print('OpenAPI schema updated successfully')
"
```

2. 进入前端目录，重新生成 API 客户端：

```bash
cd frontend
npm run generate:api
```

3. 在前端页面中接入 `src/api/services` 下生成的客户端代码。

---

## 配置说明

### 环境变量

项目提供 `.env.example` 作为环境变量模板，复制为 `.env` 后按需修改。生产环境必须修改 `SECRET_KEY` 和 `ENCRYPTION_KEY`。

常用环境变量：

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `APP_NAME` | 应用名称 | AgentFor |
| `APP_VERSION` | 应用版本 | 0.1.0 |
| `APP_DESCRIPTION` | 应用描述 | 通用智能体应用平台 |
| `DATABASE_URL` | 数据库连接 | `sqlite:///./data/agentfor.db` |
| `SECRET_KEY` | JWT 密钥 | 请生产环境务必修改 |
| `ENCRYPTION_KEY` | Fernet 密钥，用于加密 API Key | 请生产环境务必修改 |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Token 有效期 | 10080（7 天） |
| `ALGORITHM` | JWT 算法 | HS256 |
| `DATA_DIR` | 数据目录 | `./data` |
| `UPLOAD_DIR` | 上传文件目录 | `./data/uploads` |
| `CONFIG_DIR` | 运行时配置目录 | `./config` |
| `VECTOR_STORE_TYPE` | 向量库类型 | `chroma` |
| `CHROMA_PERSIST_DIR` | Chroma 持久化目录 | `./data/chroma` |
| `DEFAULT_MODEL_PROVIDER` | 默认模型 Provider | `deepseek` |
| `DEFAULT_MODEL_NAME` | 默认模型名称 | `deepseek-v4-flash` |
| `CORS_ORIGINS` | 允许跨域来源 | `http://localhost,http://localhost:80` |
| `EMBEDDING_MODEL` | Embedding 模型 | `BAAI/bge-small-zh` |
| `SENTENCE_TRANSFORMERS_HOME` | Embedding 模型缓存目录 | `./data/models` |

### 运行时配置

- `backend/config/roles.yaml`：角色运行时定义与热更新
- `backend/config/skills.yaml`：Skill 运行时定义与热更新
- `backend/config/mcp.json`：MCP Server 运行时配置与热更新

修改这些文件后，系统会通过 `watchdog` 自动热更新。

### 安全模块

- `app.core.security`：密码哈希、JWT 签发/校验、API Key 加解密（Fernet）。
- `app.core.rate_limit`：登录等接口的滑动窗口限流。
- `app.core.ssrf`：HTTP Skill / Workflow 请求的 SSRF 校验，禁止访问内网/本地地址。
- `app.core.upload`：文件上传安全，包括文件名清理、扩展名与大小限制。
- `app.core.mcp_security`：MCP Server 启动前的白名单与参数安全校验。

### 基础设施与运营能力

- **限流（Rate Limiter）**：基于内存/Redis 的请求限流，保护后端服务。
- **用量统计（Usage Service）**：统计模型调用 token 消耗、调用次数、费用估算。
- **Token 用量（Token Usage）**：记录每次调用的 input/output tokens，支持按用户/模型/时间聚合。
- **日志审计**：记录用户操作日志与模型调用日志，支持查询与导出。

### 测试

后端测试位于 `backend/tests/`，使用内存 SQLite 运行，可通过以下命令执行：

```bash
cd backend
python -m pytest -q
```

### 脚本与运维

- `backend/scripts/migrate.py`：数据库迁移脚本（生产/已有数据时使用）。
- `backend/scripts/download_embedding_model.py`：预下载 Embedding 模型到本地缓存。
- `start.sh` / `stop.sh`：一键启动/停止前后端服务。
- `Makefile`：常用运维命令（如 lint、测试、构建、启动、停止）。

---

## 工程规范

面向开发/运维人员的详细规范（技术栈、常用命令、安全约定、环境变量、测试要求）请查看：

- [AGENTS.md](AGENTS.md)

---

## 当前状态与后续计划

AgentFor MVP 已跑通前后端完整链路，包括：

- 后端服务启动并响应 `/health`
- 登录接口验证通过（admin/admin123）
- 前端页面可访问
- OpenAPI 自动生成与前端 API 客户端生成
- 角色、对话、模型、MCP、Skills、知识库、用户管理、日志审计、机器人设置、通知策略、任务调度、服务管理、Agent API、记忆等模块已落地
- Docker + Docker Compose 容器化部署已支持
- 安全模块（JWT、限流、SSRF、上传安全、MCP 安全、API Key 加密）已落地
- 后端测试覆盖认证、安全、加密、限流、SSRF、上传、MCP 安全等场景
- 一键启动/停止脚本与运维 Makefile 已提供

详细规划与后续迭代方向请查看：

- [PLANNING.md](PLANNING.md)
- [ITERATION.md](ITERATION.md)

---

## 贡献与许可

AgentFor 是一个面向二次开发的通用底座。欢迎提交 Issue 和 PR 共同完善。

本项目采用 [MIT 许可证](LICENSE) 开源，版权所有 © 2026 杨忠杰。

> 注意：当前为 MVP 版本，不建议直接用于生产环境，后续会逐步完善企业级特性、安全加固与部署方案。