From 08688a892d163d80218a8e9056ae1019d57e496a Mon Sep 17 00:00:00 2001
From: 666ghj <670939375@qq.com>
Date: Wed, 17 Dec 2025 18:26:09 +0800
Subject: [PATCH] Update project setup scripts and enhance README for clarity

- Modified the backend setup script to clear the virtual environment before installation.
- Improved README.md by restructuring the prerequisites section into a table for better readability.
- Added installation instructions for the `uv` package and clarified terminal requirements post-installation.
---
 README.md              | 23 ++++++++++++++++++-----
 backend/pyproject.toml |  4 ++--
 package.json           |  2 +-
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 039b32f..bd9a853 100644
--- a/README.md
+++ b/README.md
@@ -29,19 +29,29 @@ MiroFish/
 
 ### 前置要求
 
-- **Python 3.11+**
-- **Node.js 18+**
-- **[uv](https://docs.astral.sh/uv/)**（Python 包管理器）
+在开始之前，请确保已安装以下工具：
+
+| 工具 | 版本要求 | 说明 | 安装检查 |
+|------|---------|------|---------|
+| **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` |
+| **Python** | 3.11+ | 后端运行环境 | `python --version` |
+| **uv** | 最新版 | Python 包管理器（替代 pip） | `uv --version` |
+
+#### 安装 uv
 
-安装 uv：
 ```bash
 # macOS/Linux
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Windows
+# Windows (PowerShell)
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 或使用 Homebrew (macOS)
+brew install uv
 ```
 
+> ⚠️ 安装 uv 后需要**重新打开终端**或执行 `source ~/.zshrc` (macOS/Linux) 使其生效。
+
 ### 配置环境变量
 
 ```bash
@@ -186,6 +196,9 @@ A: 检查后端是否正常运行在 5001 端口，前端开发服务器会自
 ### Q: OASIS 模拟启动失败
 A: 确保已安装 `camel-oasis` 和 `camel-ai` 依赖，且 LLM API 配置正确。
 
+### Q: 运行 `npm run setup:backend` 报错 "uv: command not found"
+A: uv 未安装或未加入 PATH。请先安装 uv（参考前置要求），安装后**重新打开终端**再执行。
+
 ### Q: Windows 上 Python 虚拟环境激活失败
 A: 使用 `.venv\Scripts\activate` 而不是 `source .venv/bin/activate`。
 
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 9aa3f74..7635fc6 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -43,8 +43,8 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
 ]
diff --git a/package.json b/package.json
index c79f2f0..13bb6b5 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
   "description": "MiroFish - 简洁通用的群体智能引擎，预测万物",
   "scripts": {
     "setup": "npm install && cd frontend && npm install",
-    "setup:backend": "cd backend && uv venv && uv pip install -r requirements.txt",
+    "setup:backend": "cd backend && uv venv --clear && uv pip install -r requirements.txt",
     "setup:all": "npm run setup && npm run setup:backend",
     "dev": "concurrently -n \"backend,frontend\" -c \"yellow,cyan\" \"npm run backend\" \"npm run frontend\"",
     "backend": "cd backend && uv run python run.py",