# agent-base

**Repository Path**: madalin/agent-base

## Basic Information

- **Project Name**: agent-base
- **Description**: 企业智能体的数字底座
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-02
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agent Base（智体基地）

> **每一个智能体，从这里出发。**

面向小微企业的多租户"轻定制AI应用"托管平台。客户通过 REST API 或 MCP 协议让智能体操作业务数据，也可通过自助后台网页管理。

## 快速开始

```bash
# 1. 启动基础设施
docker compose up -d postgres redis

# 2. 后端
cd backend
cp .env.example .env        # 编辑数据库连接、管理员密钥等
uv sync
uv run alembic upgrade head
uv run python scripts/create_admin.py --username admin --role super_admin  # 首个管理员账号
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 3. 管理后台前端（管理员）
cd admin_frontend && pnpm install && pnpm dev    # http://localhost:5173

# 4. 客户自助后台前端（客户）
cd customer_frontend && pnpm install && pnpm dev # http://localhost:5174
```

> **生产部署见 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)** —— 含必须挂 cron 的
> 定时任务、OSS 权限清单、nginx 配置等「漏了会静默出问题」的条目。

## 项目结构

```
agent-base/
├── backend/              FastAPI 后端 + MCP Server
├── admin_frontend/       管理后台（管理员 / FDE）
├── customer_frontend/    客户自助后台（客户）
├── docs/
│   ├── DEPLOYMENT.md     生产部署与运维
│   └── RLS_PLAN.md       行级安全启用方案（已准备未启用）
├── CLAUDE.md             开发指引（架构、模式、命令）
└── DEVELOPMENT_PLAN_*.md 各轮开发方案
```

## 三套接口

| 接口 | 认证 | 用途 |
|------|------|------|
| REST API `/tables/*` `/records/*` | API Key | 智能体 / 外部集成 |
| REST API `/auth/*` `/my/*` | 客户 JWT | 客户自助后台 |
| REST API `/tenants/*` `/admin/*` | 管理员 JWT（`X-Admin-Key` 为后备） | 管理后台 |
| MCP Server (stdio/SSE/HTTP) | API Key | Claude Desktop 等 MCP 客户端 |

## 核心能力

- **租户动态建表**：JSONB 存储，客户/智能体自行定义表结构，无需 DDL
- **双接口**：REST + MCP，同一套 services 层
- **多管理员**：super_admin 管平台，FDE 管自己负责的客户
- **订阅计费**：套餐快照 + 调用量计量 + 状态机（试用/宽限/停用）
- **附件**：挂在记录下，OSS 签名直链，权限随记录继承
- **CSV 导入导出**：数据初始化与带走，形成闭环

## 技术栈

**后端**：FastAPI · SQLAlchemy 2.0 (async) · PostgreSQL (JSONB) · Redis · Alembic · MCP SDK

**前端**：React 19 · Ant Design 6 · Vite · TypeScript

**包管理**：uv（后端）· pnpm（前端）