Matt1tech/fastapi-project-generator

FastAPI 项目生成器

生成一个干净且经过验证的 FastAPI 项目。简要访谈用户，推荐 合理的默认选项，搭建项目骨架，然后使用实际命令进行验证。

第 1 步 - 访谈

如果你的代理工具提供结构化提问功能（例如任何“询问用户”或 多项选择提示工具），请优先使用它。如果没有，在聊天框中以简短编号列表形式 提出相同的问题，每个问题附带字母选项，并在推荐选项后标注“(推荐)”，然后等待用户回复。

最多分两轮提问。跳过用户已在消息中回答的任何问题。 始终将推荐选项放在首位并标注“(推荐)”。永远不要询问已有安全默认值的问题。

第一轮 - 关键信息（一批，最多 4 个问题）：

1. 项目名称 - 自由文本（使用“其他”）。根据当前目录名提供一个简短建议。 规范化为 kebab-case（文件夹名）和 snake_case（Python 名）。
2. 目标文件夹 - 选项：当前目录 ./<名称> (推荐)，或自定义路径（其他）。
3. 架构 - 模块化分层 (推荐)，最小化，整洁架构，六边形架构。 微服务仅通过“其他”选项出现；如果用户选择，询问原因，并警告 该架构不适合小型应用（参见 references/architectures.md）。
4. 服务（多选）- PostgreSQL + SQLAlchemy + Alembic、JWT 认证、Redis、Docker Compose。 推荐选择 PostgreSQL 和 Docker Compose。

第二轮 - 可选附加项（仅在相关时询问；一批）：

1. 向量数据库（多选，仅当用户需要 AI/RAG 或 Qdrant 时）：Qdrant、PostgreSQL pgvector、无。
2. AI 模块（多选）：无 (推荐)、LangChain、LangGraph、RAG、MCP。
3. LLM 提供商（仅当选择了 AI 模块时）：OpenAI、Anthropic、Google Gemini、Ollama（本地）。
4. 持久化对话状态？（仅当选择了 LangGraph 时）：通过 Postgres Checkpointer 实现 / 否（内存中）。

然后输出一行包含所选选项的简要摘要，并继续执行——除非目标文件夹非空，否则不再要求用户确认。

第 2 步 - 安全检查

1. 解析目标路径。如果该路径已存在且非空，则停止并要求用户 选择其他文件夹或进行合并。未经明确批准，绝不覆盖已有文件。
2. 确认 uv 已安装（uv --version）。如果未安装，告诉用户如何安装 （curl -LsSf https://astral.sh/uv/install.sh | sh）并停止。
3. 仅当选择了 Docker Compose 时，才确认 Docker 可用，并且仅用于 验证步骤。

第 3 步 - 搭建项目骨架

在生成代码之前，先读取对应的参考文件：

• 始终读取：references/base-project.md（布局、起始文件、uv 规则、代码规范）
• 所选架构：references/architectures.md
• 所选服务：references/services.md（依赖、Docker 规范）
• 任何 AI 模块：references/ai-rag.md

始终适用的规则：

• Python 3.12，仅使用 uv（绝不使用 pip）。backend/pyproject.toml 和 backend/uv.lock 必须在一起。
• [tool.uv] package = false，除非用户明确希望创建可安装的包。
• 没有 src/ 目录。没有空的抽象层。
• 仅添加所选服务的依赖，通过 uv add / uv add --dev 添加。
• 必需文件：app/main.py、app/core/config.py、app/api/routes/health.py、 tests/test_health.py、.env.example、.gitignore、README.md。
• /health 返回 HTTP 200 {"status": "ok"}；Swagger 位于 /docs。
• 绝不将密钥放在源代码中；绝不提交 .env。
• AI 文件夹、端点和依赖仅在被请求时才存在。

第 4 步 - 验证（未经实际运行绝不声称成功）

在 backend/ 目录下执行：

uv sync
uv run ruff check .
uv run ruff format --check .
uv run pytest -v

如果选择了 Docker Compose：在项目根目录下执行 docker compose config。 仅当用户要求时，或者询问一次后，执行 docker compose up -d。修复失败并重新运行。 如果某些内容无法验证，请如实说明。

第 5 步 - 交付报告

简洁报告以下内容：

1. 项目位置
2. 所选架构
3. 包含的服务
4. 已安装的依赖
5. 创建的文件（目录树）
6. 启动 API 的命令：cd backend && uv run uvicorn app.main:app --reload
7. 运行测试的命令：cd backend && uv run pytest -v
8. 实际的测试和 lint 结果
9. 已知限制

最后提供下一步建议（例如“添加第一个领域模块”、“git init 并推送”）。