portal_deploy 0.2.0__tar.gz

portal_deploy-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

portal_deploy-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: portal_deploy
+Version: 0.2.0
+Summary: Ray environment deployment and building toolkit
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10

portal_deploy-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "portal_deploy"          
+version = "0.2.0"   # 必须是未发布过的新版本
+description = "Ray environment deployment and building toolkit"
+long_description = { file = ["README.md"] }  # 兼容所有版本的写法
+long_description_content_type = "text/markdown"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+# 关键修正：用 [project.scripts] 作为配置段标题（方括号），下面配具体命令
+[project.scripts]
+# 命令名 = "包名.模块名:函数名"
+raydeploy-build = "raykit.env_builder:main"
+raydeploy-install = "raykit.env_installer:main"
+
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = ["raykit/"]
+exclude = [".idea/", ".venv/", "*.pth", "*.jpg", "uv.lock"]

portal_deploy-0.2.0/raykit/__init__.py

@@ -0,0 +1,4 @@
+# raykit/__init__.py
+from .env_builder import main as build
+# 如果 env_installer.py 中的函数是 install_env，就这样导入
+from .env_installer import main as install

portal_deploy-0.2.0/raykit/cli.py

@@ -0,0 +1,22 @@
+# raykit/cli.py
+import argparse
+from raykit import env_builder
+from raykit import env_installer
+
+def main():
+    parser = argparse.ArgumentParser(prog="raydeploy")
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+
+    # 子命令：build
+    subparsers.add_parser("build", help="Build the environment")
+    # 子命令：install
+    subparsers.add_parser("install", help="Install the environment")
+
+    args = parser.parse_args()
+    if args.cmd == "build":
+        env_builder.main()
+    elif args.cmd == "install":
+        env_installer.main()
+
+if __name__ == "__main__":
+    main()

portal_deploy-0.2.0/raykit/env_builder.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+环境构建SDK工具：固定Python 3.10.19，生成uv标准的pyproject.toml源配置
+"""
+import os
+import sys
+from typing import Dict, List, Tuple
+
+# 固定Python版本（核心配置）
+FIXED_PYTHON_VERSION = "3.10.19"
+# 兼容的Python版本范围（用于提示）
+COMPATIBLE_PYTHON_RANGE = ">=3.10,<3.11"
+
+# 预定义框架版本映射（新增uv源名称/url映射）
+FRAMEWORK_VERSIONS = {
+    "pytorch": {
+        "2.2.1": {
+            "cpu": {
+                "deps": {
+                    "torch": "2.2.1",
+                    "torchvision": "0.17.1",
+                    "torchaudio": "2.2.1"
+                },
+                "install_cmd": "pip install torch==2.2.1+cpu torchvision==0.17.1+cpu torchaudio==2.2.1+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html",
+                "uv_index_name": "pytorch-official",
+                "uv_index_url": "https://download.pytorch.org/whl/cpu",
+                "cuda_alias": "cpu"
+            },
+            "gpu": {
+                "cuda_version": "12.1",
+                "deps": {
+                    "torch": "2.2.1",
+                    "torchvision": "0.17.1",
+                    "torchaudio": "2.2.1"
+                },
+                "install_cmd": "pip install torch==2.2.1 torchvision==0.17.1 torchaudio==2.2.1 --index-url https://download.pytorch.org/whl/cu121",
+                "uv_index_name": "pytorch-official",
+                "uv_index_url": "https://download.pytorch.org/whl/cu121",
+                "cuda_alias": "cu121"
+            }
+        },
+        "2.5.1": {
+            "cpu": {
+                "deps": {
+                    "torch": "2.5.1",
+                    "torchvision": "0.20.1",
+                    "torchaudio": "2.5.1"
+                },
+                "install_cmd": "pip install torch==2.5.1+cpu torchvision==0.20.1+cpu torchaudio==2.5.1+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html",
+                "uv_index_name": "pytorch-official",
+                "uv_index_url": "https://download.pytorch.org/whl/cpu",
+                "cuda_alias": "cpu"
+            },
+            "gpu": {
+                "cuda_version": "12.1",
+                "deps": {
+                    "torch": "2.5.1",
+                    "torchvision": "0.20.1",
+                    "torchaudio": "2.5.1"
+                },
+                "install_cmd": "conda install pytorch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 pytorch-cuda=12.1 -c pytorch -c nvidia",
+                "uv_index_name": "pytorch-official",
+                "uv_index_url": "https://download.pytorch.org/whl/cu121",
+                "cuda_alias": "cu121",
+                "conda_channels": ["pytorch", "nvidia"]
+            }
+        }
+    },
+    "paddle": {
+        "2.5.2": {
+            "cpu": {
+                "deps": {
+                    "paddlepaddle": "2.5.2",
+                    "paddlenlp": "2.5.2"
+                },
+                "install_cmd": "pip install paddlepaddle==2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple",
+                "uv_index_name": "paddle-official",
+                "uv_index_url": "https://pypi.tuna.tsinghua.edu.cn/simple",
+                "cuda_alias": "cpu"
+            },
+            "gpu": {
+                "cuda_version": "11.7",
+                "deps": {
+                    "paddlepaddle-gpu": "2.5.2",
+                    "paddlenlp": "2.5.2"
+                },
+                "install_cmd": "pip install paddlepaddle-gpu==2.5.2.post117 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html",
+                "uv_index_name": "paddle-official",
+                "uv_index_url": "https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html",
+                "cuda_alias": "cu117"
+            }
+        }
+    }
+}
+
+# 强制内置依赖
+MANDATORY_DEPS = {
+    "ray[serve]": "2.54.0"
+}
+
+
+class EnvBuilderSDK:
+    def __init__(self):
+        self.selected_framework = None
+        self.selected_version = None
+        self.selected_device = None  # cpu/gpu
+        self.framework_deps = {}
+        self.requirements_deps = {}
+        self.all_deps = {}
+        self.install_config = {}  # 存储uv源配置、conda通道等
+
+    def check_python_version(self):
+        """检查当前Python版本，给出兼容性提示"""
+        current_ver = ".".join(map(str, sys.version_info[:3]))
+        print(f"\n📌 本工具要求Python版本：{FIXED_PYTHON_VERSION}")
+        print(f"   当前Python版本：{current_ver}")
+        if current_ver != FIXED_PYTHON_VERSION:
+            print(f"⚠️  版本不匹配！建议使用conda创建指定版本环境：")
+            print(f"   conda create -n farmland python={FIXED_PYTHON_VERSION}")
+            print(f"   conda activate farmland")
+        else:
+            print("✅ Python版本符合要求！")
+
+    def select_framework(self) -> str:
+        """交互式选择框架"""
+        print("\n===== 选择深度学习框架 =====")
+        frameworks = list(FRAMEWORK_VERSIONS.keys())
+        for idx, fw in enumerate(frameworks, 1):
+            print(f"{idx}. {fw.upper()}")
+
+        while True:
+            try:
+                choice = int(input(f"\n请输入框架序号(1-{len(frameworks)}): "))
+                if 1 <= choice <= len(frameworks):
+                    self.selected_framework = frameworks[choice - 1]
+                    print(f"已选择框架：{self.selected_framework.upper()}")
+                    return self.selected_framework
+                else:
+                    print(f"请输入1-{len(frameworks)}之间的数字！")
+            except ValueError:
+                print("请输入有效的数字！")
+
+    def select_device_type(self) -> str:
+        """选择CPU/GPU版本"""
+        print(f"\n===== 选择{self.selected_framework.upper()}运行设备 =====")
+        devices = ["cpu", "gpu"]
+        for idx, dev in enumerate(devices, 1):
+            print(f"{idx}. {dev.upper()}")
+
+        while True:
+            try:
+                choice = int(input(f"\n请输入设备序号(1-{len(devices)}): "))
+                if 1 <= choice <= len(devices):
+                    self.selected_device = devices[choice - 1]
+                    print(f"已选择设备：{self.selected_device.upper()}")
+                    # 提示CUDA版本（GPU时）
+                    if self.selected_device == "gpu":
+                        cuda_ver = FRAMEWORK_VERSIONS[self.selected_framework][self.selected_version][
+                            self.selected_device].get("cuda_version")
+                        if cuda_ver:
+                            print(f"⚠️  该版本需要CUDA {cuda_ver}，请确保系统已安装对应版本CUDA")
+                    return self.selected_device
+                else:
+                    print(f"请输入1-{len(devices)}之间的数字！")
+            except ValueError:
+                print("请输入有效的数字！")
+
+    def select_framework_version(self) -> str:
+        """交互式选择框架版本（先选版本，再选CPU/GPU）"""
+        print(f"\n===== 选择{self.selected_framework.upper()}版本 =====")
+        versions = list(FRAMEWORK_VERSIONS[self.selected_framework].keys())
+        for idx, ver in enumerate(versions, 1):
+            print(f"{idx}. 版本{ver}")
+
+        while True:
+            try:
+                choice = int(input(f"\n请输入版本序号(1-{len(versions)}): "))
+                if 1 <= choice <= len(versions):
+                    self.selected_version = versions[choice - 1]
+                    print(f"已选择{self.selected_framework.upper()}版本：{self.selected_version}")
+
+                    # 选择CPU/GPU
+                    self.select_device_type()
+
+                    # 获取该版本+设备的依赖和安装配置
+                    self.framework_deps = \
+                    FRAMEWORK_VERSIONS[self.selected_framework][self.selected_version][self.selected_device]["deps"]
+                    self.install_config = FRAMEWORK_VERSIONS[self.selected_framework][self.selected_version][
+                        self.selected_device]
+
+                    # 打印安装命令参考
+                    print(f"\n📝 参考安装命令：{self.install_config['install_cmd']}")
+                    return self.selected_version
+                else:
+                    print(f"请输入1-{len(versions)}之间的数字！")
+            except ValueError:
+                print("请输入有效的数字！")
+
+    def read_requirements(self, file_path: str = "requirements.txt") -> Dict[str, str]:
+        """读取requirements.txt文件，解析依赖"""
+        self.requirements_deps = {}
+        if not os.path.exists(file_path):
+            print(f"\n⚠️  未找到{file_path}文件，跳过读取第三方依赖")
+            return self.requirements_deps
+
+        print(f"\n===== 读取{file_path}依赖 =====")
+        with open(file_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+        for line in lines:
+            line = line.strip()
+            # 跳过注释和空行
+            if not line or line.startswith("#"):
+                continue
+            # 解析包名和版本（支持==/>=/<=等）
+            if "==" in line:
+                pkg, ver = line.split("==", 1)
+                self.requirements_deps[pkg.strip()] = ver.strip()
+            else:
+                # 无版本号时保留原字符串
+                self.requirements_deps[line.strip()] = ""
+
+        print(f"成功读取{len(self.requirements_deps)}个依赖：{list(self.requirements_deps.keys())}")
+        return self.requirements_deps
+
+    def merge_dependencies(self) -> Dict[str, str]:
+        """合并所有依赖：框架依赖 + requirements依赖 + 强制依赖"""
+        self.all_deps = {}
+        # 1. 框架依赖（优先级最高，避免版本冲突）
+        self.all_deps.update(self.framework_deps)
+        # 2. requirements依赖（若与框架依赖冲突，以框架为准）
+        for pkg, ver in self.requirements_deps.items():
+            if pkg not in self.all_deps:
+                self.all_deps[pkg] = ver
+        # 3. 强制依赖（ray[serve]，优先级最高）
+        self.all_deps.update(MANDATORY_DEPS)
+
+        print(f"\n===== 合并后总依赖 =====")
+        for pkg, ver in self.all_deps.items():
+            print(f"{pkg}: {ver if ver else '未指定版本'}")
+        return self.all_deps
+
+    def generate_pyproject_toml(self, output_path: str = "pyproject.toml") -> None:
+        """生成pyproject.toml文件（固定Python 3.10.19 + uv源配置）"""
+        # 基础配置
+        pyproject_content = f"""
+[project]
+name = "tool"
+version = "0.1.0"
+description = "（Python {FIXED_PYTHON_VERSION} | {self.selected_framework.upper()} {self.selected_version} {self.selected_device.upper()}）"
+authors = [{{ name="Your Name", email="your@email.com" }}]
+requires-python = "{COMPATIBLE_PYTHON_RANGE}"  # 强制Python 3.10.x，精确版本{FIXED_PYTHON_VERSION}
+license = {{ file="LICENSE" }}
+
+# 核心依赖（包含{self.selected_framework} {self.selected_device}版本 + 第三方依赖）
+dependencies = [
+"""
+        # 添加所有依赖到dependencies列表
+        dep_lines = []
+        for pkg, ver in self.all_deps.items():
+            if ver:
+                dep_lines.append(f'    "{pkg}=={ver}",')
+            else:
+                dep_lines.append(f'    "{pkg}",')
+
+        pyproject_content += "\n".join(dep_lines)
+        pyproject_content += """
+]
+
+"""
+        # ========== uv标准的源配置 ==========
+        pyproject_content += f"""# 新增 {self.selected_framework} 官方源（{self.install_config['cuda_alias']} 版本）
+[[tool.uv.index]]
+name = "{self.install_config['uv_index_name']}"
+url = "{self.install_config['uv_index_url']}"
+explicit = true
+
+"""
+        # 针对PyTorch：强制torch/torchaudio/torchvision从官方源下载
+        if self.selected_framework == "pytorch":
+            pyproject_content += f"""# 关键：指定PyTorch相关包强制从 {self.install_config['uv_index_name']} 源下载
+[tool.uv.sources]
+torch = {{ index = "{self.install_config['uv_index_name']}" }}
+torchaudio = {{ index = "{self.install_config['uv_index_name']}" }}
+torchvision = {{ index = "{self.install_config['uv_index_name']}" }}
+
+"""
+        # 针对Paddle：强制Paddle相关包从官方源下载
+        elif self.selected_framework == "paddle":
+            pyproject_content += f"""# 关键：指定Paddle相关包强制从 {self.install_config['uv_index_name']} 源下载
+[tool.uv.sources]
+paddlepaddle = {{ index = "{self.install_config['uv_index_name']}" }}
+paddlepaddle-gpu = {{ index = "{self.install_config['uv_index_name']}" }}
+paddlenlp = {{ index = "{self.install_config['uv_index_name']}" }}
+
+"""
+        # 可选开发依赖
+        pyproject_content += """[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "black>=23.0",
+    "flake8>=6.0"
+]
+"""
+
+        # 写入文件
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(pyproject_content)
+
+        print(f"\n✅ 成功生成{output_path}文件！")
+        print(f"文件路径：{os.path.abspath(output_path)}")
+        # 提示关键信息
+        print(f"📌 强制指定Python版本：{FIXED_PYTHON_VERSION}")
+        if self.selected_device == "gpu":
+            cuda_ver = self.install_config.get("cuda_version")
+            print(f"⚠️  注意：该配置需要CUDA {cuda_ver}，请确保系统已安装对应版本CUDA")
+
+    def run(self):
+        """SDK主执行流程"""
+        print("===== 环境构建SDK（Python 3.10.19固定版）=====")
+        # 前置步骤：检查Python版本
+        self.check_python_version()
+        # 步骤1：选择框架
+        self.select_framework()
+        # 步骤2：选择框架版本 + CPU/GPU
+        self.select_framework_version()
+        # 步骤3：读取requirements.txt
+        self.read_requirements()
+        # 步骤4：合并依赖
+        self.merge_dependencies()
+        # 步骤5：生成pyproject.toml
+        self.generate_pyproject_toml()
+        print("\n===== SDK执行完成 =====")
+
+# 核心新增：定义main函数，供raykit.build调用
+def main():
+    """环境构建的入口函数（供模块导入调用）"""
+    sdk = EnvBuilderSDK()
+    sdk.run()
+
+# 保留原有直接运行的逻辑
+if __name__ == "__main__":
+    main()

portal_deploy-0.2.0/raykit/env_installer.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Portal 环境构建脚本（全平台兼容：Windows/Linux）
+特性：
+1. 自动识别系统类型，适配 Conda 执行逻辑
+2. 智能跳过已完成步骤（环境/uv/依赖）
+3. 自动处理 uv.lock 锁文件（首次不加 --frozen）
+4. 兼容 Conda 初始化、路径分隔符、权限等问题
+"""
+
+import subprocess
+import sys
+import argparse
+import os
+import re
+import platform
+
+# 跨平台彩色输出兼容
+try:
+    from colorama import init, Fore, Style
+
+    # Windows 初始化 colorama，Linux 无需
+    if platform.system() == "Windows":
+        init(autoreset=True)
+except ImportError:
+    # 无 colorama 时降级为无颜色输出
+    class FakeColor:
+        def __getattr__(self, name):
+            return ""
+
+
+    Fore = FakeColor()
+    Style = FakeColor()
+
+
+class EnvBuilderError(Exception):
+    """自定义异常类"""
+    pass
+
+
+def get_conda_init_cmd():
+    """获取对应系统的 Conda 初始化命令"""
+    system = platform.system()
+    if system == "Linux":
+        # Linux 下 Conda 初始化路径（兼容 Miniconda/Anaconda）
+        conda_paths = [
+            "~/miniconda3/etc/profile.d/conda.sh",
+            "~/anaconda3/etc/profile.d/conda.sh",
+            "/opt/conda/etc/profile.d/conda.sh"
+        ]
+        for path in conda_paths:
+            abs_path = os.path.expanduser(path)
+            if os.path.exists(abs_path):
+                return f"source {abs_path} && "
+        return "source ~/miniconda3/etc/profile.d/conda.sh && "  # 默认路径
+    return ""  # Windows 无需初始化
+
+
+def run_command(cmd, description, check_only=False):
+    """
+    执行系统命令（全平台兼容）
+    check_only=True: 仅检查结果，不抛出异常、不打印冗余输出
+    """
+    if not check_only:
+        print(f"{Fore.BLUE}[*] {description}...{Style.RESET_ALL}")
+
+    system = platform.system()
+    try:
+        # 构建最终执行的命令
+        final_cmd = cmd
+        if system == "Linux" and cmd[0] == "conda":
+            # Linux 下：封装 Conda 命令，确保初始化 + bash 执行
+            conda_init = get_conda_init_cmd()
+            cmd_str = conda_init + " ".join(cmd)
+            final_cmd = ["bash", "-c", cmd_str]
+            shell = False
+        else:
+            # Windows 下：启用 shell 以支持 conda 命令
+            shell = system == "Windows"
+
+        # 执行命令
+        result = subprocess.run(
+            final_cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="ignore",
+            shell=shell
+        )
+
+        # 打印输出（非检查模式）
+        if not check_only and result.stdout:
+            print(f"{Fore.GREEN}[+] 输出: {result.stdout}{Style.RESET_ALL}")
+
+        # 返回执行结果
+        return result.returncode == 0, result.stdout
+
+    except Exception as e:
+        if check_only:
+            return False, str(e)
+        raise EnvBuilderError(f"{Fore.RED}[-] 执行{description}出错: {str(e)}{Style.RESET_ALL}")
+
+
+def check_conda_env_exists(env_name):
+    """检查 Conda 环境是否存在（跨平台）"""
+    print(f"{Fore.BLUE}[*] 检查虚拟环境 {env_name} 是否存在...{Style.RESET_ALL}")
+    success, output = run_command(
+        ["conda", "info", "--envs"],
+        f"检查 Conda 环境 {env_name}",
+        check_only=True
+    )
+    if success:
+        env_pattern = re.compile(rf"{env_name}\s+")
+        if env_pattern.search(output):
+            print(f"{Fore.GREEN}[+] 虚拟环境 {env_name} 已存在，跳过创建步骤{Style.RESET_ALL}")
+            return True
+    print(f"{Fore.YELLOW}[!] 虚拟环境 {env_name} 不存在，需要创建{Style.RESET_ALL}")
+    return False
+
+
+def check_uv_installed(env_name):
+    """检查指定 Conda 环境中是否安装 uv（跨平台）"""
+    print(f"{Fore.BLUE}[*] 检查环境 {env_name} 中是否安装 uv...{Style.RESET_ALL}")
+    cmd = ["conda", "run", "-n", env_name, "uv", "--version"]
+    success, output = run_command(cmd, "检查 uv 安装状态", check_only=True)
+    if success and "uv " in output:  # 确保输出包含 uv 版本信息（避免误判）
+        print(f"{Fore.GREEN}[+] uv 已安装，跳过安装步骤{Style.RESET_ALL}")
+        return True
+    print(f"{Fore.YELLOW}[!] uv 未安装，需要安装{Style.RESET_ALL}")
+    return False
+
+
+def check_deps_synced(env_name):
+    """检查依赖是否已还原（跨平台）"""
+    print(f"{Fore.BLUE}[*] 检查依赖是否已还原...{Style.RESET_ALL}")
+    # 检查 uv.lock 是否存在 + 依赖是否安装
+    if os.path.exists("uv.lock"):
+        success, _ = run_command(
+            ["conda", "run", "-n", env_name, "uv", "list"],
+            "检查依赖列表",
+            check_only=True
+        )
+        if success:
+            print(f"{Fore.GREEN}[+] 依赖已还原，跳过 uv sync 步骤{Style.RESET_ALL}")
+            return True
+    print(f"{Fore.YELLOW}[!] 依赖未还原，需要执行 uv sync{Style.RESET_ALL}")
+    return False
+
+
+def create_portal_env(env_name="portal_test", python_version="3.10.19"):
+    """核心功能：智能创建并配置测试环境（全平台）"""
+    try:
+        # 1. 检查 Conda 是否可用
+        conda_ok, conda_output = run_command(["conda", "--version"], "检查 Conda 安装状态", check_only=True)
+        if not conda_ok:
+            hint = ""
+            if platform.system() == "Linux":
+                hint = "\n    请先安装 Conda，或执行: source ~/miniconda3/etc/profile.d/conda.sh"
+            elif platform.system() == "Windows":
+                hint = "\n    请确保 Conda 已添加到系统 PATH 中"
+            raise EnvBuilderError(f"{Fore.RED}未检测到 Conda！{hint}{Style.RESET_ALL}")
+
+        # 2. 检查并创建虚拟环境
+        env_exists = check_conda_env_exists(env_name)
+        if not env_exists:
+            run_command(
+                ["conda", "create", "-n", env_name, f"python={python_version}", "-y"],
+                f"创建虚拟环境 {env_name} (Python {python_version})"
+            )
+
+        # 3. 检查并安装 uv（Linux 加 --user 避免权限问题）
+        uv_installed = check_uv_installed(env_name)
+        if not uv_installed:
+            install_cmd = ["conda", "run", "-n", env_name, "pip", "install", "uv"]
+            if platform.system() == "Linux":
+                install_cmd.append("--user")
+            run_command(install_cmd, "安装 uv 包管理器")
+
+        # 4. 检查 pyproject.toml 是否存在
+        if not os.path.exists("pyproject.toml"):
+            raise EnvBuilderError(f"{Fore.RED}当前目录未找到 pyproject.toml 文件！{Style.RESET_ALL}")
+
+        # 5. 检查并执行 uv sync（跨平台适配）
+        deps_synced = check_deps_synced(env_name)
+        if not deps_synced:
+            uv_sync_cmd = ["conda", "run", "-n", env_name, "uv", "sync"]
+            # Linux 下强制指定 Python 解释器路径（动态拼接）
+            if platform.system() == "Linux":
+                # 自动获取 conda 环境路径
+                conda_env_path = os.path.expanduser(f"~/miniconda3/envs/{env_name}/bin/python")
+                uv_sync_cmd.extend(["--python", conda_env_path])
+            run_command(uv_sync_cmd, "还原线上环境依赖")
+
+        # 执行完成提示（区分系统）
+        print(f"\n{Fore.GREEN}[✓] 环境检查/构建完成！{Style.RESET_ALL}")
+        activate_hint = ""
+        if platform.system() == "Linux":
+            activate_hint = f"source activate {env_name}"
+        elif platform.system() == "Windows":
+            activate_hint = f"conda activate {env_name}"
+        print(f"{Fore.YELLOW}[提示] 手动激活环境：{activate_hint}{Style.RESET_ALL}")
+
+    except EnvBuilderError as e:
+        print(f"\n{Fore.RED}[✗] 环境构建失败：{str(e)}{Style.RESET_ALL}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print(f"\n{Fore.YELLOW}[!] 用户中断操作{Style.RESET_ALL}")
+        sys.exit(0)
+
+
+def main():
+    """命令行参数解析和入口（全平台）"""
+    parser = argparse.ArgumentParser(
+        description="Portal 测试环境一键构建工具（Windows/Linux 通用）",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="示例:\n  python env_builder.py\n  python env_builder.py --env-name my_env --python 3.10.20"
+    )
+    parser.add_argument(
+        "--env-name",
+        default="portal_test",
+        help="虚拟环境名称（默认：portal_test）"
+    )
+    parser.add_argument(
+        "--python",
+        default="3.10.19",
+        help="Python 版本（默认：3.10.19）"
+    )
+
+    args = parser.parse_args()
+
+    # 检查 Python 版本
+    if sys.version_info < (3, 10):
+        print(f"{Fore.RED}[-] 该脚本需要 Python 3.10 及以上版本！{Style.RESET_ALL}")
+        sys.exit(1)
+
+    create_portal_env(env_name=args.env_name, python_version=args.python)
+
+
+if __name__ == "__main__":
+    main()