# 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-28

## 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        # 编辑数据库连接、密钥等（JWT_SECRET_KEY / ADMIN_API_KEY 必须配置，否则拒绝启动）
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（13 个工具）
├── admin_frontend/       管理后台（管理员 / FDE）
├── customer_frontend/    客户自助后台（客户）
├── docs/
│   ├── COMMANDS.md       全部命令（含运维脚本、本地库重建、依赖漏洞核对）
│   ├── ARCHITECTURE.md   目录树、16 张表的字段清单、Redis 用法
│   ├── CONFIGURATION.md  环境变量全清单、本地/云两套环境
│   ├── DEPLOYMENT.md     生产部署与运维
│   └── RLS_PLAN.md       行级安全启用方案（已准备未启用）
├── CLAUDE.md             开发约束与设计取舍（给 Claude Code 读）
└── DEVELOPMENT_PLAN_*.md 各轮开发方案
```

> **CLAUDE.md 与 docs/ 的分工**：CLAUDE.md 只放「不知道就会写错代码」的
> 约束与反直觉取舍，每次会话全量载入故需控制体量；可枚举、可从代码读出的
> 内容放 docs/，按需查阅。

## 四套认证

| 接口 | 认证 | 用途 |
|------|------|------|
| REST API `/tables/*` `/records/*` | API Key（bcrypt + Fernet 双存储） | 智能体 / 外部集成 |
| REST API `/auth/*` `/my/*` | 客户 JWT（2h 有效，支持吊销/刷新） | 客户自助后台 |
| REST API `/tenants/*` `/admin/*` | 管理员 JWT（`X-Admin-Key` 为后备） | 管理后台 |
| MCP Server (stdio/SSE/HTTP) | API Key + 表级权限 + 订阅门禁 | Claude Desktop / Hermes 等 |

管理员分两级：**super_admin**（平台级：模板/套餐/管理员 CRUD、租户分配、收款/停用）与 **FDE**（只管自己负责的客户）。共享 Admin Key 视为 super_admin，审计记为 `"admin_key"`。

## 核心能力

- **租户动态建表**：JSONB 存储，客户/智能体自行定义表结构，无需 DDL
- **双接口**：REST + MCP，同一套 services 层
- **应用层租户隔离**：FastAPI 依赖注入，非 RLS
- **多管理员**：super_admin 管平台，FDE 管自己负责的客户
- **订阅计费**：套餐快照（改套餐不影响已订阅客户）+ 调用量计量 + 状态机（试用 → 宽限 → 停用）
- **附件**：挂在记录下，OSS 签名直链，权限随记录继承，三态配额回退
- **CSV 导入导出**：数据初始化与带走，形成闭环
- **邀请码注册**：两层防护（IP 限流 + 邀请码准入），两段式校验防并发
- **登录防爆破**：双维度（IP + 用户名），两级阈值（验证码 → 429）
- **平台配置表**：9 项可后台改的配置（MCP 地址、配额、注册模式等），无需发版
- **模板系统**：从客户提取表结构为行业模板，新客户一键套用，支持拓扑排序与版本管理
- **一键安装脚本**：为客户生成 sh/PowerShell 脚本，自动下载技能文件并配置 MCP

## 数据模型

16 张表，核心围绕：

| 表 | 职责 |
|---|---|
| `tenants` | 租户（含配额、指派管理员） |
| `data_tables` / `data_records` | 业务表定义 + JSONB 数据 |
| `customer_users` | 客户登录账号 |
| `api_keys` | API Key（支持分组级权限、Fernet 加密、数量上限） |
| `files` | 附件（挂在记录下，配额随记录继承） |
| `plans` / `subscriptions` / `usage_daily` | 套餐 + 订阅 + 调用量计量 |
| `admin_users` | 管理员账号（super_admin / FDE） |
| `templates` | 行业模板（版本机制） |
| `invite_codes` | 注册邀请码 |
| `audit_logs` / `admin_audit_logs` | 租户级 / 平台级审计 |
| `platform_configs` | 可后台改的配置项 |

字段清单与设计取舍见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 与 `CLAUDE.md`。

## 技术栈

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

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

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

**基础设施**：PostgreSQL + Redis via Docker（本地）；阿里云 RDS + Redis + OSS（发布）