feat: 不再使用覆盖层

Author: SengokuCola

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - 修复一些 Mac napcat注入问题
 - 修复一些未知问题
+- 优化了python管理和依赖安装的逻辑
 
 ## 0.4.16 - 2026-07-03
 

README.md

@@ -45,11 +45,11 @@ bun run build
 
 ## 运行时资源
 
-打包版默认把可写运行资源放在 `%APPDATA%\MaiBotOneKeyDesktop\<安装目录hash>` 下；设置中心的「实例路径」页可以迁移运行时资源目录。迁移只移动 `modules/` 与 `python-overrides/`，日志、实例锁和一键包设置仍保留在用户数据目录。
+打包版默认把可写运行资源放在 `%APPDATA%\MaiBotOneKeyDesktop\<安装目录hash>` 下；设置中心的「实例路径」页可以迁移运行时资源目录。迁移只移动 `modules/`，日志、实例锁、`python-env` 和一键包设置仍保留在用户数据目录。
 
 ## Windows 打包
 
-Windows x64 NSIS 安装包当前产出正式版：`MaiBot OK-<version>-win.exe`。正式版会打包干净的基础 Python、内置 Git、MaiBot、NapCat、SnowLuma 以及 NapCat/SnowLuma 适配器插件，但不会打包 MaiBot Python 依赖，也不会打包 `python-overrides` 覆盖层；首次启动时再由启动器安装运行依赖。
+Windows x64 NSIS 安装包当前产出正式版：`MaiBot OK-<version>-win.exe`。正式版会打包干净的基础 Python、内置 Git、MaiBot、NapCat、SnowLuma 以及 NapCat/SnowLuma 适配器插件，但不会把 MaiBot Python 依赖预装进包内 runtime；首次启动时启动器会复制一份可写 `python-env` 并把运行依赖安装到其中。
 
 打包前需要在仓库根目录放好 payload：
 
@@ -73,7 +73,7 @@ modules/
   SnowLuma/
 ```
 
-`runtime/python` 必须保持为便携 Python，只允许 Python 自身、`pip`/`setuptools`/`wheel` 以及启动依赖解析需要的 `packaging`；不要把 MaiBot、dashboard 或其它应用依赖预装进 `runtime/python/Lib/site-packages`。macOS 包内路径是 `runtime/python/bin/python3`，Windows 包内路径是 `runtime/python/python.exe`。`release-assets/python-overrides` 不会进入安装包。
+`runtime/python` 必须保持为便携 Python，只允许 Python 自身、`pip`/`setuptools`/`wheel` 以及启动依赖解析需要的 `packaging`；不要把 MaiBot、dashboard 或其它应用依赖预装进 `runtime/python/Lib/site-packages`。macOS 包内路径是 `runtime/python/bin/python3.12` 或同版本真实二进制，Windows 包内路径是 `runtime/python/python.exe`。
 
 编写器里的 OpenCode 入口依赖内置 CLI sidecar：打包前需要把 Windows x64 版 `opencode.exe` 放到 `runtime/opencode/opencode.exe`。当前接入按 `opencode-windows-x64` release binary 设计，`runtime/` 已被 `.gitignore` 忽略，所以该二进制不会进入源码提交；`bun run release:check` 会校验它是否存在。
 

docs/release.md

@@ -27,7 +27,7 @@
    modules/SnowLuma/index.mjs
    ```
 
-   `runtime/python` 必须保持为便携 Python，只保留 Python 自身、`pip`/`setuptools`/`wheel` 以及启动依赖解析需要的 `packaging`。不要把 MaiBot、dashboard 或其它应用依赖预装进 `runtime/python/Lib/site-packages` 或 `runtime/python/lib/python3.12/site-packages`；`release-assets/python-overrides` 不会进入安装包。
+   `runtime/python` 必须保持为便携 Python，只保留 Python 自身、`pip`/`setuptools`/`wheel` 以及启动依赖解析需要的 `packaging`。不要把 MaiBot、dashboard 或其它应用依赖预装进 `runtime/python/Lib/site-packages` 或 `runtime/python/lib/python3.12/site-packages`；首次启动会复制可写 `python-env` 并把运行依赖安装到其中。
 
    `resources/opencode/plugin_code.md` 会在打包时复制到安装包资源目录的 `runtime/opencode/plugin_code.md`，用于编写器内置 OpenCode 的默认插件编写说明。
 

scripts/release/check-windows-payload.ts

@@ -409,7 +409,7 @@ async function main(): Promise<void> {
     console.log("");
     console.log("[missing] portable Python should not contain application dependencies.");
     console.log("Keep runtime/python lean: only Python itself plus pip/setuptools/wheel/packaging are allowed.");
-    console.log("Install MaiBot/dashboard dependencies into python-overrides at first run instead.");
+    console.log("Install MaiBot/dashboard dependencies into the writable python-env at first run instead.");
     if (bundledPythonPackages.length > 0) {
       console.log(`Unexpected site-packages entries (${bundledPythonPackages.length}):`);
       for (const name of bundledPythonPackages.slice(0, 30)) {

scripts/release/prepare-python-overrides.ts

@@ -98,7 +98,7 @@ import type {
   ModuleSourceUpdate,
   ModuleTagOption,
   ModuleUpdateTarget,
-  PythonOverridesState,
+  PythonEnvironmentState,
   PythonPackageSourcePreset,
   PythonPackageInstallRequest,
   PythonPackageInstallResult,
@@ -2141,12 +2141,12 @@ export function registerAppIpc({
     }
 
     const dashboardVersion = await readPythonDistInfoVersion(
-      pythonDependencyManager.getActiveOverridesRoot(),
+      pythonDependencyManager.getPythonPackagesRoot(),
       "maibot-dashboard",
     );
     if (dashboardVersion) {
-      versions.dashboardOverride = dashboardVersion;
-      versions.dashboardOverrideSource = "python-overrides";
+      versions.dashboardPythonEnv = dashboardVersion;
+      versions.dashboardPythonEnvSource = "python-env";
     }
 
     return versions;
@@ -3749,7 +3749,7 @@ export function registerAppIpc({
     },
   );
 
-  ipcMain.handle("pythonDeps:getState", (): PythonOverridesState => {
+  ipcMain.handle("pythonDeps:getState", (): PythonEnvironmentState => {
     return pythonDependencyManager.getState();
   });
 
@@ -3758,7 +3758,7 @@ export function registerAppIpc({
     async (
       _event,
       preset: PythonPackageSourcePreset,
-    ): Promise<PythonOverridesState> => {
+    ): Promise<PythonEnvironmentState> => {
       const state = await pythonDependencyManager.saveSourcePreset(preset);
       await broadcastSnapshot();
       return state;

src/main/ipc/app.ts

@@ -56,7 +56,6 @@ const MAIBOT_WEBUI_FALLBACK_PORT = 8001;
 const QQ_BACKEND_FILE = "qq-backend.json";
 const MESSAGE_PLATFORM_FILE = "message-platform.json";
 const RUNTIME_PATH_CONFIG_FILE = "runtime-paths.json";
-const PYTHON_OVERRIDES_IGNORED_ENTRIES = new Set([".keep", "resource.lock"]);
 const NAPCAT_COMPONENT_PROTECTED_PATHS = [
   "config",
   "data",
@@ -3006,44 +3005,6 @@ export class InitManager {
     }
   }
 
-  async ensureBundledPythonOverrides(): Promise<string[]> {
-    const bundledRoot = join(dirname(this.paths.runtimeRoot), "python-overrides");
-    const targetRoot = this.paths.pythonOverridesRoot;
-    if (!existsSync(bundledRoot) || samePath(bundledRoot, targetRoot)) {
-      return [];
-    }
-
-    let bundledEntries: string[];
-    try {
-      bundledEntries = (await readdir(bundledRoot)).filter((entry) => !PYTHON_OVERRIDES_IGNORED_ENTRIES.has(entry));
-    } catch {
-      return [];
-    }
-    if (bundledEntries.length === 0) {
-      return [];
-    }
-
-    let targetEntries: string[] = [];
-    try {
-      targetEntries = (await readdir(targetRoot)).filter((entry) => !PYTHON_OVERRIDES_IGNORED_ENTRIES.has(entry));
-    } catch {
-      targetEntries = [];
-    }
-    if (targetEntries.length > 0) {
-      return [];
-    }
-
-    await mkdir(dirname(targetRoot), { recursive: true });
-    await runWithoutAsar(() =>
-      cp(bundledRoot, targetRoot, {
-        recursive: true,
-        force: false,
-        errorOnExist: false,
-      }),
-    );
-    return [targetRoot];
-  }
-
   /**
    * Generate a fixed launcher .cmd under the napcat directory; it runs chcp 65001 before the exe.
    * Avoid building a `cmd /C` command string in source while keeping the console in UTF-8.

src/main/services/init-manager.ts

@@ -40,7 +40,6 @@ function defaultResourcePaths(defaultResourceRoot: string): RuntimeResourcePathM
   return {
     maibot: join(defaultResourceRoot, "modules", "MaiBot"),
     napcat: join(defaultResourceRoot, "modules", "napcat"),
-    pythonOverrides: join(defaultResourceRoot, "python-overrides"),
   };
 }
 
@@ -52,7 +51,6 @@ function readStoredResourcePaths(userDataRoot: string): Partial<RuntimeResourceP
       return {
         maibot: normalizePath(raw.paths?.maibot),
         napcat: normalizePath(raw.paths?.napcat),
-        pythonOverrides: normalizePath(raw.paths?.pythonOverrides),
       };
     } catch {
       return {};
@@ -80,9 +78,6 @@ export function applyRuntimeResourcePaths(paths: RuntimePaths, updates: Partial<
   if (updates.napcat) {
     paths.napcatRoot = updates.napcat;
   }
-  if (updates.pythonOverrides) {
-    paths.pythonOverridesRoot = updates.pythonOverrides;
-  }
   paths.resourceRoot = paths.defaultResourceRoot;
   paths.modulesRoot = join(paths.defaultResourceRoot, "modules");
 }
@@ -116,8 +111,7 @@ export function configureRuntimePaths(): RuntimePaths {
     opencodePluginInstructionsPath: app.isPackaged
       ? join(payloadRoot, "runtime", "opencode", "plugin_code.md")
       : join(installRoot, "resources", "opencode", "plugin_code.md"),
-    defaultPythonOverridesRoot: defaults.pythonOverrides,
-    pythonOverridesRoot: defaults.pythonOverrides,
+    pythonEnvRoot: join(defaultResourceRoot, "python-env"),
     pluginBuilderRoot: join(userDataRoot, "plugin-builder", "plugins"),
     logsRoot: join(userDataRoot, "logs"),
   };