Matt1tech/fastapi-project-generator

FastAPI 專案產生器

產生一個乾淨且經過驗證的 FastAPI 專案。先簡短訪談使用者，推薦合理的預設值，然後建立專案結構，最後使用真實命令進行驗證。

第一步 - 訪談

如果代理人（agent）有結構化提問工具（例如詢問使用者或多選提示工具），請使用該工具。否則，請以簡短編號列表形式在聊天中提出相同問題，每個問題附上字母選項，並標記推薦選項，然後等待回覆。

最多分兩輪提問。跳過使用者已在訊息中回答的任何問題。始終將推薦選項標記為「(Recommended)」。絕對不要詢問已有安全預設值的事項。

第一輪 - 必要項目（一次最多 4 個問題）：

1. 專案名稱 - 自由文字（使用「Other」）。根據目錄名稱提供簡短建議。將資料夾名稱標準化為 kebab-case，Python 名稱則用 snake_case。
2. 目標資料夾 - 選項：目前目錄 ./<name>（Recommended）、自訂路徑（Other）。
3. 架構 - 模組化分層（Recommended）、最小化、簡潔架構、六邊形架構。微服務僅在選擇「Other」時出現；若選擇，需詢問原因，並針對小型應用程式提出警告（請參閱 references/architectures.md）。
4. 服務（多選）- PostgreSQL + SQLAlchemy + Alembic、JWT 驗證、Redis、Docker Compose。建議選擇 PostgreSQL 與 Docker Compose。

第二輪 - 可選擴充（僅在相關時詢問；一次提出）：

1. 向量資料庫（多選，僅在使用者需要 AI/RAG 或 Qdrant 時詢問）：Qdrant、PostgreSQL pgvector、None。
2. AI 模組（多選）：None（Recommended）、LangChain、LangGraph、RAG、MCP。
3. LLM 提供者（僅在選取 AI 模組時詢問）：OpenAI、Anthropic、Google Gemini、Ollama（本地）。
4. 是否持久化對話狀態？（僅在選取 LangGraph 時詢問）：是，透過 Postgres checkpointer / 否（記憶體中）。

然後列印 6 行摘要，說明選擇的內容，然後繼續進行 - 除非目標資料夾非空，否則無需再次要求確認。

第二步 - 安全檢查

1. 解析目標路徑。如果該路徑已存在且非空，請 STOP 並詢問是否要使用不同的資料夾或合併。未經明確許可，絕不覆寫現有檔案。
2. 確認 uv 已安裝（uv --version）。如果未安裝，告知使用者如何安裝（curl -LsSf https://astral.sh/uv/install.sh | sh）並停止。
3. 僅在選取 Docker Compose 時，才確認 Docker 是否可用，且僅用於驗證步驟。

第三步 - 建立專案結構

在產生程式碼之前，請先讀取對應的參考檔案：

• 總是讀取：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 資料夾、端點與相依套件僅在使用者要求時才會建立。

第四步 - 驗證（未執行命令前，絕不宣稱成功）

從 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，或者詢問一次。修正失敗並重新執行。如果某些項目無法驗證，請明確說明。

第五步 - 交付報告

簡潔報告：

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 並推送」）。