@agentunion/kite 1.5.0 → 1.6.1

package/scripts/setup-python-env.js

@@ -1,191 +1,700 @@
-#!/usr/bin/env node
-
-/**
- * Kite Python 环境准备脚本（版本锁定）
- *
- * 在 npm install 后自动执行，负责：
- * 1. 读取 python_version.json 获取要求的 Python 版本
- * 2. 检测系统是否有该精确版本的 Python
- * 3. 如果没有，下载并安装该版本到 ~/.kite/python/（仅 Windows）
- *
- * 注意：不创建虚拟环境，不安装依赖
- * 这些由 Python 层的 env_checker.py 负责
- */
-
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-// 颜色输出
-const colors = {
-  reset: '\x1b[0m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  red: '\x1b[31m',
-  cyan: '\x1b[36m'
-};
-
-function log(msg, color = 'reset') {
-  console.log(`${colors[color]}[Kite Setup]${colors.reset} ${msg}`);
-}
-
-function error(msg) {
-  console.error(`${colors.red}[Kite Setup Error]${colors.reset} ${msg}`);
-}
-
-// 获取 KITE_DATA 路径
-function getKiteDataPath() {
-  return path.join(os.homedir(), '.kite');
-}
-
-// 获取 Python 安装路径
-function getPythonInstallPath() {
-  return path.join(getKiteDataPath(), 'python');
-}
-
-// 读取要求的 Python 版本
-function getRequiredPythonVersion() {
-  const versionFile = path.join(__dirname, '..', 'python_version.json');
-
-  if (!fs.existsSync(versionFile)) {
-    error('python_version.json 不存在');
-    return null;
-  }
-
-  try {
-    const data = JSON.parse(fs.readFileSync(versionFile, 'utf-8'));
-    return data.version;
-  } catch (e) {
-    error(`读取 python_version.json 失败: ${e.message}`);
-    return null;
-  }
-}
-
-// 检测系统 Python（精确版本匹配）
-function detectSystemPython(requiredVersion) {
-  const pythonCommands = ['python3', 'python'];
-
-  for (const cmd of pythonCommands) {
-    try {
-      const version = execSync(`${cmd} --version`, {
-        encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'ignore']
-      }).trim();
-
-      // 解析版本号
-      const match = version.match(/Python (\d+\.\d+\.\d+)/);
-      if (match) {
-        const installedVersion = match[1];
-
-        if (installedVersion === requiredVersion) {
-          log(`检测到系统 Python: ${version}`, 'green');
-          return cmd;
-        } else {
-          log(`系统 Python 版本不匹配: ${installedVersion} (需要 ${requiredVersion})`, 'yellow');
-        }
-      }
-    } catch (e) {
-      // 命令不存在，继续尝试下一个
-    }
-  }
-
-  return null;
-}
-
-// 下载 Python（精确版本）
-async function downloadPython(requiredVersion) {
-  log(`系统未检测到 Python ${requiredVersion}`, 'yellow');
-  log('正在下载 Python embeddable 版本...', 'cyan');
-
-  const arch = process.arch === 'x64' ? 'amd64' : 'win32';
-  const filename = `python-${requiredVersion}-embed-${arch}.zip`;
-  const url = `https://www.python.org/ftp/python/${requiredVersion}/${filename}`;
-
-  const installPath = getPythonInstallPath();
-
-  // 如果已经安装过，跳过
-  const pythonExe = path.join(installPath, 'python.exe');
-  if (fs.existsSync(pythonExe)) {
-    log('Python 已安装，跳过下载', 'green');
-    return pythonExe;
-  }
-
-  const zipPath = path.join(os.tmpdir(), filename);
-
-  // 下载
-  log(`下载地址: ${url}`, 'cyan');
-  log('这可能需要几分钟...', 'cyan');
-
-  try {
-    // 使用 PowerShell 下载
-    execSync(`powershell -Command "Invoke-WebRequest -Uri '${url}' -OutFile '${zipPath}'"`, {
-      stdio: 'inherit'
-    });
-  } catch (e) {
-    error('下载失败');
-    throw e;
-  }
-
-  // 解压
-  log('正在解压 Python...', 'cyan');
-  fs.mkdirSync(installPath, { recursive: true });
-
-  execSync(`powershell -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${installPath}' -Force"`, {
-    stdio: 'inherit'
-  });
-
-  // 清理
-  fs.unlinkSync(zipPath);
-
-  log(`Python ${requiredVersion} 已安装到: ${installPath}`, 'green');
-
-  return pythonExe;
-}
-
-// 主流程
-async function main() {
-  try {
-    log('检查 Python 环境...', 'cyan');
-
-    // 1. 读取要求的 Python 版本
-    const requiredVersion = getRequiredPythonVersion();
-
-    if (!requiredVersion) {
-      error('无法读取要求的 Python 版本');
-      return;
-    }
-
-    log(`要求的 Python 版本: ${requiredVersion}`, 'cyan');
-
-    // 2. 检测系统 Python
-    let pythonCmd = detectSystemPython(requiredVersion);
-
-    // 3. 如果没有，下载安装（仅 Windows）
-    if (!pythonCmd) {
-      if (process.platform === 'win32') {
-        pythonCmd = await downloadPython(requiredVersion);
-      } else {
-        log(`未检测到 Python ${requiredVersion}`, 'yellow');
-        log('请手动安装 Python 后重试', 'yellow');
-        log(`下载地址: https://www.python.org/downloads/release/python-${requiredVersion.replace(/\./g, '')}/`, 'cyan');
-        // 不退出，让 Python 层的检查器处理
-      }
-    }
-
-    if (pythonCmd) {
-      log('Python 环境检查完成', 'green');
-      log(`Python 命令: ${pythonCmd}`, 'cyan');
-    }
-
-    log('虚拟环境和依赖将在首次运行 kite 时自动准备', 'cyan');
-
-  } catch (e) {
-    error('环境准备失败');
-    console.error(e);
-    // 不退出，让 Python 层的检查器处理
-  }
-}
-
-// 执行
-main();
+#!/usr/bin/env node
+
+/**
+ * Kite Python 环境准备脚本（版本锁定）
+ *
+ * 在 npm install 后自动执行，负责：
+ * 1. 读取 python_version.json 获取要求的 Python 版本
+ * 2. 检测系统是否有该精确版本的 Python
+ * 3. 如果没有，下载并安装该版本到 ~/.kite/python/（仅 Windows）
+ *
+ * 注意：不创建虚拟环境，不安装依赖
+ * 这些由 Python 层的 env_checker.py 负责
+ */
+
+const { execSync, exec } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { promisify } = require('util');
+
+const execAsync = promisify(exec);
+
+// 所有可用的下载源
+const ALL_SOURCES = [
+  'https://www.python.org/ftp/python',           // 官方源
+  'https://mirrors.tuna.tsinghua.edu.cn/python', // 清华源
+  'https://mirrors.ustc.edu.cn/python',          // 中科大镜像
+  'https://mirrors.huaweicloud.com/python'       // 华为云镜像
+];
+
+// PyPI 镜像源（用于 pip 安装依赖）
+const PYPI_SOURCES = [
+  'https://pypi.org/simple',                           // 官方源
+  'https://pypi.tuna.tsinghua.edu.cn/simple',          // 清华源
+  'https://mirrors.aliyun.com/pypi/simple',            // 阿里云
+  'https://pypi.mirrors.ustc.edu.cn/simple',           // 中科大
+  'https://mirrors.huaweicloud.com/repository/pypi/simple'  // 华为云
+];
+
+// 超时配置（毫秒）
+const TIMEOUT_CONFIG = {
+  SOURCE_TEST: 6000,        // 源测速：6秒
+  PYPI_TEST: 4000,          // PyPI测速：4秒
+  DOWNLOAD: 300000,         // 下载：5分钟
+  INSTALL: 180000,          // 安装：3分钟
+  PIP_INSTALL: 180000       // pip安装：3分钟
+};
+
+// 安装方法配置
+const INSTALL_METHOD = process.env.KITE_PYTHON_INSTALL_METHOD || 'auto';
+const RETRY_TIMES = INSTALL_METHOD === 'auto' ? 2 : 3;
+
+// 颜色输出
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+};
+
+function log(msg, color = 'reset') {
+  console.log(`${colors[color]}[Kite Setup]${colors.reset} ${msg}`);
+}
+
+function error(msg) {
+  console.error(`${colors.red}[Kite Setup Error]${colors.reset} ${msg}`);
+}
+
+// 获取 KITE_DATA 路径
+function getKiteDataPath() {
+  return path.join(os.homedir(), '.kite');
+}
+
+// 获取 Python 安装路径
+function getPythonInstallPath() {
+  return path.join(getKiteDataPath(), 'python');
+}
+
+/**
+ * 保存安装信息
+ */
+function saveInstallInfo(method, version, patched = false) {
+  const installPath = getPythonInstallPath();
+  const infoFile = path.join(installPath, '.install-info.json');
+
+  const info = {
+    method: method,           // 'official' | 'embed'
+    version: version,
+    patched: patched,
+    installed_at: new Date().toISOString()
+  };
+
+  try {
+    fs.writeFileSync(infoFile, JSON.stringify(info, null, 2), 'utf-8');
+  } catch (e) {
+    log('无法保存安装信息', 'yellow');
+  }
+}
+
+/**
+ * 测试 PyPI 源速度并排序（并行测试，跨平台）
+ */
+async function testPyPISpeed() {
+  log('正在测试 PyPI 源速度（并行）...', 'cyan');
+
+  // 并行测试所有源
+  const testPromises = PYPI_SOURCES.map(async (source) => {
+    const start = Date.now();
+    try {
+      // 使用 curl 测试（跨平台）
+      await execAsync(`curl -I "${source}/pip/" --max-time 3 -s`, {
+        timeout: 4000
+      });
+      const elapsed = Date.now() - start;
+      log(`${source}: ${elapsed}ms`, 'green');
+      return { source, speed: elapsed };
+    } catch (e) {
+      log(`${source}: 不可用`, 'yellow');
+      return null;
+    }
+  });
+
+  const results = (await Promise.all(testPromises)).filter(r => r !== null);
+  results.sort((a, b) => a.speed - b.speed);
+  return results.map(r => r.source);
+}
+
+/**
+ * 测试下载源速度并排序（并行实际下载测试，跨平台）
+ */
+async function testSourceSpeed(requiredVersion, filename) {
+  log('正在测试下载源速度（并行实际下载测试）...', 'cyan');
+
+  // 并行测试所有源
+  const testPromises = ALL_SOURCES.map(async (source) => {
+    const url = `${source}/${requiredVersion}/${filename}`;
+    const testFile = path.join(os.tmpdir(), `test-${Date.now()}-${Math.random()}.tmp`);
+    const start = Date.now();
+
+    try {
+      // 使用 curl 下载前 100KB（跨平台）
+      await execAsync(`curl -r 0-102399 -o "${testFile}" "${url}" --max-time 5 -s`, {
+        timeout: 6000
+      });
+
+      const elapsed = Date.now() - start;
+
+      // 清理测试文件
+      if (fs.existsSync(testFile)) {
+        fs.unlinkSync(testFile);
+      }
+
+      log(`${source}: ${elapsed}ms`, 'green');
+      return { source, speed: elapsed };
+    } catch (e) {
+      // 清理测试文件
+      if (fs.existsSync(testFile)) {
+        fs.unlinkSync(testFile);
+      }
+      log(`${source}: 不可用`, 'yellow');
+      return null;
+    }
+  });
+
+  const results = (await Promise.all(testPromises)).filter(r => r !== null);
+  results.sort((a, b) => a.speed - b.speed);
+  return results.map(r => r.source);
+}
+
+/**
+ * 读取安装信息
+ */
+function loadInstallInfo() {
+  const installPath = getPythonInstallPath();
+  const infoFile = path.join(installPath, '.install-info.json');
+
+  if (!fs.existsSync(infoFile)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(infoFile, 'utf-8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 跨平台下载函数（支持 PowerShell 和 curl）
+ */
+function downloadFile(url, outputPath, timeout = TIMEOUT_CONFIG.DOWNLOAD) {
+  // 尝试使用 curl（跨平台更好）
+  try {
+    execSync(`curl -L -o "${outputPath}" "${url}" --max-time ${Math.floor(timeout / 1000)}`, {
+      stdio: 'inherit',
+      timeout: timeout
+    });
+    return true;
+  } catch (e) {
+    // curl 失败，尝试 PowerShell（仅 Windows）
+    if (process.platform === 'win32') {
+      try {
+        execSync(`powershell -Command "Invoke-WebRequest -Uri '${url}' -OutFile '${outputPath}'"`, {
+          stdio: 'inherit',
+          timeout: timeout
+        });
+        return true;
+      } catch (e2) {
+        throw new Error('下载失败：curl 和 PowerShell 都不可用');
+      }
+    }
+    throw e;
+  }
+}
+
+/**
+ * 带重试和超时的下载函数
+ */
+function downloadWithRetry(url, outputPath, retries = RETRY_TIMES) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      if (i > 0) {
+        log(`重试 ${i}/${retries - 1}...`, 'yellow');
+      }
+
+      downloadFile(url, outputPath, TIMEOUT_CONFIG.DOWNLOAD);
+      return true;
+    } catch (e) {
+      if (e.killed && e.signal === 'SIGTERM') {
+        log(`下载超时（${TIMEOUT_CONFIG.DOWNLOAD / 1000}秒）`, 'red');
+      }
+      if (i === retries - 1) {
+        throw e;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 方案 1: 使用系统 Python 创建虚拟环境（如果系统已有同版本）
+ * 如果系统没有，则下载官方安装包
+ */
+async function installOfficialPython(requiredVersion, installPath) {
+  // 策略 1: 检测系统是否已有同版本 Python
+  const systemPython = detectSystemPython(requiredVersion);
+
+  if (systemPython) {
+    log(`检测到系统 Python ${requiredVersion}，使用虚拟环境方案`, 'cyan');
+    log('正在创建虚拟环境...', 'cyan');
+
+    try {
+      // 使用系统 Python 创建虚拟环境到目标路径
+      execSync(`"${systemPython}" -m venv "${installPath}"`, {
+        stdio: 'inherit',
+        timeout: TIMEOUT_CONFIG.INSTALL
+      });
+
+      // 验证虚拟环境（Windows 下 python.exe 在 Scripts 目录）
+      const pythonExe = process.platform === 'win32'
+        ? path.join(installPath, 'Scripts', 'python.exe')
+        : path.join(installPath, 'bin', 'python');
+
+      if (!fs.existsSync(pythonExe)) {
+        throw new Error('虚拟环境创建失败');
+      }
+
+      // 升级 pip
+      log('正在升级 pip...', 'cyan');
+      const sortedPyPISources = await testPyPISpeed();
+      const pypiSource = sortedPyPISources[0] || PYPI_SOURCES[0];
+
+      try {
+        execSync(`"${pythonExe}" -m pip install --upgrade pip -i ${pypiSource}`, {
+          stdio: 'inherit',
+          timeout: TIMEOUT_CONFIG.PIP_INSTALL
+        });
+      } catch (e) {
+        log('pip 升级失败（可能已是最新版本）', 'yellow');
+      }
+
+      saveInstallInfo('venv', requiredVersion, false);
+      log(`Python ${requiredVersion} (虚拟环境) 已创建`, 'green');
+
+      return;
+    } catch (e) {
+      log(`虚拟环境创建失败: ${e.message}`, 'yellow');
+      log('降级到安装包方案...', 'yellow');
+      // 清理失败的虚拟环境
+      if (fs.existsSync(installPath)) {
+        fs.rmSync(installPath, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // 策略 2: 下载官方安装包
+  log('系统无同版本 Python，下载官方安装包...', 'cyan');
+
+  const arch = process.arch === 'x64' ? 'amd64' : 'win32';
+  const filename = `python-${requiredVersion}-${arch}.exe`;
+  const installerPath = path.join(os.tmpdir(), filename);
+
+  // 测试源速度并排序
+  const sortedSources = await testSourceSpeed(requiredVersion, filename);
+
+  if (sortedSources.length === 0) {
+    throw new Error('所有下载源均不可用');
+  }
+
+  // 按速度从快到慢尝试下载
+  let downloaded = false;
+  for (const source of sortedSources) {
+    const url = `${source}/${requiredVersion}/${filename}`;
+    log(`使用源: ${source}`, 'cyan');
+
+    try {
+      downloadWithRetry(url, installerPath);
+      downloaded = true;
+      break;
+    } catch (e) {
+      log(`下载失败，尝试下一个源`, 'yellow');
+    }
+  }
+
+  if (!downloaded) {
+    throw new Error('所有下载源均失败');
+  }
+
+  // 先卸载已有版本（清理注册表残留）
+  log('清理注册表残留...', 'cyan');
+  try {
+    execSync(`"${installerPath}" /uninstall /quiet`, {
+      stdio: 'pipe',
+      timeout: 60000
+    });
+    // 等待卸载完成
+    await new Promise(resolve => setTimeout(resolve, 2000));
+  } catch (e) {
+    // 卸载失败或无旧版本，继续
+  }
+
+  log('正在静默安装 Python...', 'cyan');
+
+  const installArgs = [
+    '/quiet',
+    'InstallAllUsers=0',
+    `TargetDir=${installPath}`,
+    'PrependPath=0',
+    'Include_pip=1',
+    'Include_test=0',
+    'CompileAll=0'
+  ].join(' ');
+
+  execSync(`"${installerPath}" ${installArgs}`, {
+    stdio: 'inherit',
+    timeout: TIMEOUT_CONFIG.INSTALL
+  });
+
+  // 等待安装完成（官方安装器可能异步执行）
+  log('等待安装完成...', 'cyan');
+  const pythonExe = path.join(installPath, 'python.exe');
+  let retries = 30; // 最多等待30秒
+  while (retries > 0 && !fs.existsSync(pythonExe)) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    retries--;
+  }
+
+  if (!fs.existsSync(pythonExe)) {
+    fs.unlinkSync(installerPath);
+    throw new Error('安装超时：python.exe 未出现在目标路径');
+  }
+
+  fs.unlinkSync(installerPath);
+
+  saveInstallInfo('official', requiredVersion, false);
+  log(`Python ${requiredVersion} (官方安装包) 已安装`, 'green');
+}
+
+/**
+ * 方案 2: embed 版 + 自动补丁（轻量但有限制）
+ */
+async function installEmbedPython(requiredVersion, installPath) {
+  const arch = process.arch === 'x64' ? 'amd64' : 'win32';
+  const filename = `python-${requiredVersion}-embed-${arch}.zip`;
+  const zipPath = path.join(os.tmpdir(), filename);
+
+  // 测试源速度并排序
+  const sortedSources = await testSourceSpeed(requiredVersion, filename);
+
+  if (sortedSources.length === 0) {
+    throw new Error('所有下载源均不可用');
+  }
+
+  // 按速度从快到慢尝试下载
+  let downloaded = false;
+  for (const source of sortedSources) {
+    const url = `${source}/${requiredVersion}/${filename}`;
+    log(`使用源: ${source}`, 'cyan');
+
+    try {
+      downloadWithRetry(url, zipPath);
+      downloaded = true;
+      break;
+    } catch (e) {
+      log(`下载失败，尝试下一个源`, 'yellow');
+    }
+  }
+
+  if (!downloaded) {
+    throw new Error('所有下载源均失败');
+  }
+
+  log('正在解压 Python...', 'cyan');
+  fs.mkdirSync(installPath, { recursive: true });
+  execSync(`powershell -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${installPath}' -Force"`, {
+    stdio: 'inherit'
+  });
+  fs.unlinkSync(zipPath);
+
+  log('正在应用补丁...', 'cyan');
+  await applyEmbedPatches(requiredVersion, installPath);
+
+  saveInstallInfo('embed', requiredVersion, true);
+  log(`Python ${requiredVersion} (embeddable + 补丁) 已安装`, 'green');
+}
+
+/**
+ * 为 embed 版应用补丁（尽可能接近正式版）
+ */
+async function applyEmbedPatches(requiredVersion, installPath) {
+  const pythonExe = path.join(installPath, 'python.exe');
+  const versionShort = requiredVersion.split('.').slice(0, 2).join('');
+  const pthFile = path.join(installPath, `python${versionShort}._pth`);
+
+  // 补丁 1: 修改 ._pth 文件
+  if (fs.existsSync(pthFile)) {
+    log('补丁 1: 修改 ._pth 文件...', 'cyan');
+    const versionDir = path.join(__dirname, '..');
+    const scriptsDir = path.join(installPath, 'Scripts');
+    const sitePackagesDir = path.join(installPath, 'Lib', 'site-packages');
+
+    // 确保目录存在
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    fs.mkdirSync(sitePackagesDir, { recursive: true });
+
+    const pthContent = [
+      `python${versionShort}.zip`,
+      '.',
+      'Lib',
+      'Lib/site-packages',
+      'Scripts',
+      versionDir,
+      '',
+      '# Enable site module for pip support',
+      'import site'
+    ].join('\n');
+    fs.writeFileSync(pthFile, pthContent, 'utf-8');
+  }
+
+  // 测试 PyPI 源速度并排序
+  const sortedPyPISources = await testPyPISpeed();
+
+  if (sortedPyPISources.length === 0) {
+    log('警告: 所有 PyPI 源均不可用，使用默认源', 'yellow');
+    sortedPyPISources.push(PYPI_SOURCES[0]);
+  }
+
+  // 补丁 2: 安装 pip（带重试和多源降级）
+  log('补丁 2: 安装 pip...', 'cyan');
+  const getPipPath = path.join(os.tmpdir(), 'get-pip.py');
+
+  let pipInstalled = false;
+  try {
+    execSync(`curl -sS -L -o "${getPipPath}" https://bootstrap.pypa.io/get-pip.py`, {
+      stdio: 'inherit',
+      timeout: TIMEOUT_CONFIG.DOWNLOAD
+    });
+
+    // 尝试多个 PyPI 源安装 pip
+    for (const pypiSource of sortedPyPISources) {
+      try {
+        log(`使用 PyPI 源: ${pypiSource}`, 'cyan');
+        execSync(`"${pythonExe}" "${getPipPath}" -i ${pypiSource}`, {
+          stdio: 'inherit',
+          timeout: TIMEOUT_CONFIG.PIP_INSTALL
+        });
+        pipInstalled = true;
+        break;
+      } catch (e) {
+        log(`该源失败，尝试下一个源`, 'yellow');
+      }
+    }
+
+    fs.unlinkSync(getPipPath);
+  } catch (e) {
+    log('pip 安装失败（可能已安装）', 'yellow');
+  }
+
+  // 补丁 3: 安装标准工具链（带重试和多源降级）
+  // 注意：必须用 python -m pip 而非 pip.exe，因为 embed 版的 pip.exe 包装器
+  // 不走 ._pth 路径，会导致 No module named 'pip'
+  log('补丁 3: 安装标准工具链...', 'cyan');
+  const toolchainPackages = ['setuptools', 'wheel', 'virtualenv'];
+
+  // 验证 pip 模块可用
+  try {
+    execSync(`"${pythonExe}" -m pip --version`, { stdio: 'pipe' });
+  } catch (e) {
+    log('警告: pip 模块不可用，跳过工具链安装', 'yellow');
+    log('补丁应用完成', 'green');
+    return;
+  }
+
+  for (const pypiSource of sortedPyPISources) {
+    try {
+      log(`使用 PyPI 源: ${pypiSource}`, 'cyan');
+      execSync(`"${pythonExe}" -m pip install --upgrade ${toolchainPackages.join(' ')} -i ${pypiSource}`, {
+        stdio: 'inherit',
+        timeout: TIMEOUT_CONFIG.PIP_INSTALL
+      });
+      log('工具链安装成功', 'green');
+      break;
+    } catch (e) {
+      log(`该源失败，尝试下一个源`, 'yellow');
+    }
+  }
+
+  log('补丁应用完成', 'green');
+}
+
+// 读取要求的 Python 版本
+function getRequiredPythonVersion() {
+  const versionFile = path.join(__dirname, '..', 'python_version.json');
+
+  if (!fs.existsSync(versionFile)) {
+    error('python_version.json 不存在');
+    return null;
+  }
+
+  try {
+    const data = JSON.parse(fs.readFileSync(versionFile, 'utf-8'));
+    return data.version;
+  } catch (e) {
+    error(`读取 python_version.json 失败: ${e.message}`);
+    return null;
+  }
+}
+
+// 检测系统 Python（精确版本匹配），返回完整路径
+function detectSystemPython(requiredVersion) {
+  const pythonCommands = ['python3', 'python'];
+
+  for (const cmd of pythonCommands) {
+    try {
+      // 使用 Python 自己报告的可执行文件路径（绕过 WindowsApps 重定向）
+      const fullPath = execSync(`${cmd} -c "import sys; print(sys.executable)"`, {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore']
+      }).trim();
+
+      if (!fullPath) continue;
+
+      const version = execSync(`"${fullPath}" --version`, {
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore']
+      }).trim();
+
+      // 解析版本号
+      const match = version.match(/Python (\d+\.\d+\.\d+)/);
+      if (match) {
+        const installedVersion = match[1];
+
+        if (installedVersion === requiredVersion) {
+          log(`检测到系统 Python ${requiredVersion}: ${fullPath}`, 'green');
+          return fullPath;
+        } else {
+          log(`系统 Python 版本不匹配: ${installedVersion} (需要 ${requiredVersion})`, 'yellow');
+        }
+      }
+    } catch (e) {
+      // 命令不存在，继续尝试下一个
+    }
+  }
+
+  return null;
+}
+
+// 下载 Python（多级降级方案，支持强制指定）
+async function downloadPython(requiredVersion) {
+  if (INSTALL_METHOD === 'auto') {
+    log(`系统未检测到 Python ${requiredVersion}`, 'yellow');
+  }
+
+  const installPath = getPythonInstallPath();
+  const pythonExe = path.join(installPath, 'python.exe');
+
+  // 如果已经安装过，检查是否是 embed 版
+  if (fs.existsSync(pythonExe)) {
+    const versionShort = requiredVersion.split('.').slice(0, 2).join('');
+    const pthFile = path.join(installPath, `python${versionShort}._pth`);
+
+    if (fs.existsSync(pthFile)) {
+      log('检测到旧的 embeddable 版本，正在升级到完整版...', 'yellow');
+      fs.rmSync(installPath, { recursive: true, force: true });
+    } else {
+      log('Python 已安装，跳过下载', 'green');
+      return pythonExe;
+    }
+  }
+
+  // 根据安装模式选择方案
+  if (INSTALL_METHOD === 'official') {
+    await installOfficialPython(requiredVersion, installPath);
+    return pythonExe;
+  }
+
+  if (INSTALL_METHOD === 'embed') {
+    await installEmbedPython(requiredVersion, installPath);
+    return pythonExe;
+  }
+
+  // auto 模式：优先 official（虚拟环境或安装包），降级到 embed
+  // 方案 1: official - 优先虚拟环境（利用系统Python），降级到安装包
+  try {
+    log('方案 1: 尝试 official 方案（虚拟环境或安装包）...', 'cyan');
+    await installOfficialPython(requiredVersion, installPath);
+    return pythonExe;
+  } catch (e) {
+    log(`方案 1 失败: ${e.message}`, 'yellow');
+  }
+
+  // 方案 2: embed 版 + 自动补丁（备选：轻量但需要补丁）
+  try {
+    log('方案 2: 尝试 embeddable 版本 + 自动补丁...', 'cyan');
+    await installEmbedPython(requiredVersion, installPath);
+    return pythonExe;
+  } catch (e) {
+    log(`方案 2 失败: ${e.message}`, 'yellow');
+  }
+
+  // 方案 3: 提示用户手动安装
+  error('自动安装失败，请手动安装 Python');
+  log(`下载地址: https://www.python.org/downloads/release/python-${requiredVersion.replace(/\./g, '')}/`, 'cyan');
+  log(`或设置环境变量强制使用指定方案: KITE_PYTHON_INSTALL_METHOD=official 或 embed`, 'cyan');
+  throw new Error('Python installation failed');
+}
+
+// 主流程
+async function main() {
+  try {
+    log('检查 Python 环境...', 'cyan');
+
+    // 1. 读取要求的 Python 版本
+    const requiredVersion = getRequiredPythonVersion();
+
+    if (!requiredVersion) {
+      error('无法读取要求的 Python 版本');
+      return;
+    }
+
+    log(`要求的 Python 版本: ${requiredVersion}`, 'cyan');
+
+    // 2. 检测系统 Python（强制指定方案时跳过系统检测）
+    let pythonCmd = null;
+    if (INSTALL_METHOD === 'auto') {
+      pythonCmd = detectSystemPython(requiredVersion);
+    } else {
+      log(`安装模式: ${INSTALL_METHOD}`, 'cyan');
+      log(`强制模式: 仅尝试 ${INSTALL_METHOD === 'official' ? '官方安装包' : 'embeddable'} 版本`, 'yellow');
+    }
+
+    // 3. 如果没有，下载安装（仅 Windows）
+    if (!pythonCmd) {
+      if (process.platform === 'win32') {
+        pythonCmd = await downloadPython(requiredVersion);
+      } else {
+        log(`未检测到 Python ${requiredVersion}`, 'yellow');
+        log('请手动安装 Python 后重试', 'yellow');
+        log(`下载地址: https://www.python.org/downloads/release/python-${requiredVersion.replace(/\./g, '')}/`, 'cyan');
+        // 不退出，让 Python 层的检查器处理
+      }
+    }
+
+    if (pythonCmd) {
+      log('Python 环境检查完成', 'green');
+      log(`Python 命令: ${pythonCmd}`, 'cyan');
+    }
+
+    log('虚拟环境和依赖将在首次运行 kite 时自动准备', 'cyan');
+
+  } catch (e) {
+    error('环境准备失败');
+    console.error(e);
+    // 不退出，让 Python 层的检查器处理
+  }
+}
+
+// 执行
+main();