全栈 AI 代理模板

这是什么 – 一个命令行生成器，可快速搭建一个完整的生产就绪型 Web 应用（FastAPI 后端 + Next.js 前端），预先集成 AI 代理功能、检索增强生成（RAG）、认证、计费、可观测性以及部署工具。生成的项目可通过 Docker 本地运行，或部署到 Kubernetes，同时提供丰富的用户界面，支持聊天、团队/工作区管理、知识库导入和管理员仪表板。

---

🎯 核心目标

该模板让开发者在几分钟内启动一个全栈 AI 代理 SaaS，然后专注于特定领域的逻辑，而非自行搭建常见的基础设施（如认证、数据库、RAG、CI、监控等）。

---

🚀 快速入门（来自 README）

1. 安装生成器

   pip install fastapi-fullstack   # 或 `uv tool install fastapi-fullstack`
   

2. 创建项目 – 回答交互式向导（或传递参数）：

   fastapi-fullstack               # 生成 `my_ai_app`
   

3. 初始化项目栈

   cd my_ai_app
   make bootstrap                 # 构建 Docker 镜像，启动数据库，运行迁移，初始化管理员账户
   

4. 运行前端 UI（在另一个终端）

   cd frontend && bun install && bun dev   # 或 `make dev-frontend`
   

5. 打开服务：
   • API 文档：http://localhost:8000/docs
   • 管理员界面：http://localhost:8000/admin（admin@example.com / admin123）
   • 前端：http://localhost:3000

---

🛠️ 主要功能（列出如下）

类别	你将获得
AI 代理框架	支持 5 种运行时 – Pydantic AI、Pydantic Deep Agents、LangChain、LangGraph、DeepAgents。
RAG 流水线	即插即用的向量存储（Milvus、Qdrant、pgvector、ChromaDB），支持自动分块和嵌入。
Web 栈	FastAPI 15 后端，支持 WebSocket 流式传输，Next.js 15 前端，实时聊天界面。
对话共享	公共链接、仅管理员可浏览的浏览器视图、聊天会话的导出与分享。
企业级就绪	JWT + OAuth、管理员面板、Celery 任务队列、Docker 与 Kubernetes 配置、环境专用的 compose 文件。
可观测性	内置使用仪表板、按 token 计费、Stripe 计费集成、操作日志。
CLI 与 Django 风格管理	生成的 my_ai_app 命令，用于启动服务、数据库迁移、用户创建等。
升级路径	make upgrade 可将上游模板变更合并到现有项目中，而不会丢失自定义代码。
可扩展性	功能标志（如 enable_marketing_site）可轻松添加营销落地页、SaaS 计费、团队工作区等。

---

📂 生成的项目结构（概览）

my_ai_app/
├─ backend/          # FastAPI 应用，Pydantic 模型，Celery 工作进程
│   ├─ app/
│   ├─ alembic/      # 数据库迁移
│   ├─ Dockerfile
│   └─ Makefile
├─ frontend/         # Next.js (React) UI，Tailwind，WebSocket 客户端
│   ├─ pages/        # 聊天、仪表板、管理员、计费等
│   ├─ components/
│   └─ Dockerfile
├─ docker-compose.dev.yml   # 开发环境栈（数据库、Redis、Milvus 等）
├─ docker-compose.prod.yml  # 生产环境栈
└─ makefile          # 开发、生产、升级等的快捷命令

该项目还包含一个 PyPI 包（fastapi-fullstack），其中封装了项目生成逻辑。

---

🤖 AI 代理详情

• 代理代码位于后端，可在生成时选择（例如 pydantic_deep）。
• 代理支持流式响应、调用工具、暂停等待用户确认（ask_user）、执行 Python 代码片段，并可启动子代理。
• UI 将每个工具调用渲染为卡片，显示实时的任务计划清单，并内联展示图表或代码输出。

---

📚 文档与生态

• 文档网站 – https://vstorm-co.github.io/full-stack-ai-agent-template/（安装指南、升级说明、API 参考）。
• 属于 Vstorm 开源生态 – 关联项目如 AgenticOS、pydantic-deepagents、pydantic-ai-shields 提供底层运行时、防护机制和沙箱环境。
• CI 指示器显示 100 % 测试覆盖率；OpenSSF 最佳实践徽章表明该项目具备成熟的开源流程。

---

🏁 何时使用它

• 你需要一个现成的 SaaS 模板，用于 AI 助手类产品（客户支持机器人、数据分析师、代码助手等）。
• 你需要企业级功能（认证、多租户工作区、Stripe 计费），但不想从零开始构建。
• 你希望使用一条命令来保持技术栈更新，并在未来轻松升级。

---

📦 打包方式

• 生成器通过 PyPI 发布为 fastapi-fullstack（可通过 pip、uv 或 pipx 安装）。
• 生成的应用程序使用 Docker 容器化，并包含可选的 Kubernetes 清单文件。

---

📌 TL;DR

vstorm-co/full-stack-ai-agent-template 是一个真正的生产级项目，能够生成一个完整的 FastAPI + Next.js 应用，预先集成 AI 代理、RAG、认证、计费和部署功能。它专为构建 AI 代理 SaaS 产品而设计，为生成的代码提供了清晰的升级路径。