msdevflow 0.7.5 → 0.7.6

package/README.md

@@ -9,7 +9,7 @@
 - Claude Code、Codex 或 OpenCode 中至少一个；
 - Node.js `>=18` 和 npm；
 - Git；
-- Python `>=3.10` 和 pip；
+- Python `>=3.10`，且标准库 `venv` 模块可用；
 - GitCode 账号；
 - Chrome 或 Edge（推荐，用于 openLiBing OAuth）。
 
@@ -31,7 +31,7 @@ npx msdevflow@latest setup
 
 1. 把一个 `msd` 核心和十个 `msd-<action>` 路由器作为整套事务原子安装或更新到所需目标；
 2. 安装或升级官方 `@gitcode-cli/cli@latest`；
-3. 安装受审的 Python Playwright 依赖；
+3. 创建或修复 msdevflow 受管 Python venv，并在其中安装受审的 Playwright 依赖；
 4. 验收 Issue、PR、结构化评论、行内评论、JSON、显式仓库和正文文件等 CLI 能力；
 5. GitCode CLI 未认证时打开官方 Token 创建页面，并让 CLI 自己的终端提示接收 Token。
 
@@ -67,6 +67,15 @@ npx msdevflow setup --agents-skills-dir "<shared-agent-skills-directory>"
 
 `--skills-dir` 未配合 `--targets` 使用时保留旧语义，只安装 Claude Code 目标。没有检测到客户端时，交互运行会要求选择目标；非交互运行必须提供 `--targets`。安装完成后重启或重新加载对应客户端。如果机器已有 Python 版本的 `gitcode`，setup 会保留它，并为 npm CLI 创建 `gitcode-npm` 命令；否则使用 `gitcode`。
 
+setup 在所有平台使用独立受管 venv，不向系统 Python 安装包：
+
+```text
+Windows:     %LOCALAPPDATA%\msdevflow\python
+macOS/Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/msdevflow/python
+```
+
+可用 `MSDEVFLOW_PYTHON_DIR` 覆盖，值必须是绝对路径或以 `~` 开头；setup 与后续 action 必须使用同一配置。`venv` 属于 CPython 标准库，但精简发行版可能未安装；Debian/Ubuntu 通常需要用户自行安装 `python3-venv`。setup 不执行 sudo，不回退到全局 pip，也不使用 `--break-system-packages`。Windows 官方 Python 和 Homebrew Python 通常已包含 `venv`。
+
 ## 运行与 action 补全
 
 从目标仓库目录启动客户端。直接调用核心 `msd` 会运行完整作者 E2E：

package/lib/bootstrap.js

@@ -11,6 +11,7 @@ import {
   readdirSync,
   readSync,
   renameSync,
+  rmdirSync,
   rmSync,
   unlinkSync,
   writeFileSync,
@@ -27,6 +28,8 @@ const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skill");
 const CORE_SKILL_NAME = "msd";
 const LEGACY_SKILL_NAME = "msdevflow";
+const PYTHON_RUNTIME_MARKER = ".msdevflow-python-runtime";
+const PYTHON_RUNTIME_MARKER_CONTENT = "managed-by=msdevflow\n";
 export const ACTIONS = [
   "discover",
   "create-issue",
@@ -946,6 +949,176 @@ function environmentHome(environment, platform) {
   return environment.HOME || homedir();
 }
 
+function pythonRuntimeAt(directory, python, platform) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  return {
+    baseExecutable: python.executable,
+    baseVersion: python.version,
+    directory,
+    executable: pathApi.join(
+      directory,
+      platform === "win32" ? "Scripts" : "bin",
+      platform === "win32" ? "python.exe" : "python",
+    ),
+    marker: pathApi.join(directory, PYTHON_RUNTIME_MARKER),
+    platform,
+  };
+}
+
+function expandHomePath(value, home, platform, variable) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  let expanded = value;
+  if (value === "~") {
+    expanded = home;
+  } else {
+    const homeRelative = platform === "win32" ? /^~[\\/]/ : /^~\//;
+    if (homeRelative.test(value)) {
+      expanded = pathApi.join(home, value.slice(2));
+    }
+  }
+  if (!pathApi.isAbsolute(expanded) && !path.isAbsolute(expanded)) {
+    throw new BootstrapError(`${variable} must be an absolute path or start with ~.`, 2);
+  }
+  return expanded;
+}
+
+export function pythonRuntimeDetails(
+  python,
+  environment = process.env,
+  platform = process.platform,
+) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const home = environmentHome(environment, platform);
+  const configured = environment.MSDEVFLOW_PYTHON_DIR;
+  const directory = configured
+    ? expandHomePath(configured, home, platform, "MSDEVFLOW_PYTHON_DIR")
+    : platform === "win32"
+      ? pathApi.join(environment.LOCALAPPDATA || pathApi.join(home, "AppData", "Local"), "msdevflow", "python")
+      : pathApi.join(
+          environment.XDG_DATA_HOME
+            ? expandHomePath(environment.XDG_DATA_HOME, home, platform, "XDG_DATA_HOME")
+            : pathApi.join(home, ".local", "share"),
+          "msdevflow",
+          "python",
+        );
+  return pythonRuntimeAt(directory, python, platform);
+}
+
+function validatePythonRuntime(runtime, run) {
+  let marker;
+  try {
+    const metadata = lstatSync(runtime.directory);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+      throw new BootstrapError(
+        `Refusing to use a Python runtime path not owned by msdevflow: ${runtime.directory}`,
+        3,
+      );
+    }
+    marker = readOptionalFile(
+      runtime.marker,
+      `Refusing to use an invalid msdevflow Python runtime marker: ${runtime.marker}`,
+    );
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "absent";
+    }
+    throw error;
+  }
+  if (marker !== PYTHON_RUNTIME_MARKER_CONTENT) {
+    throw new BootstrapError(
+      `Refusing to use a Python runtime directory not owned by msdevflow: ${runtime.directory}`,
+      3,
+    );
+  }
+  let descriptor;
+  try {
+    descriptor = openSync(runtime.executable, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return "repair";
+    }
+    throw error;
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+  if (runOptional(run, {
+    command: runtime.executable,
+    args: ["-m", "pip", "--version"],
+  }).status !== 0) {
+    return "repair";
+  }
+  return "current";
+}
+
+function writePythonRuntimeMarker(runtime) {
+  const existing = readOptionalFile(
+    runtime.marker,
+    `Refusing to replace an invalid msdevflow Python runtime marker: ${runtime.marker}`,
+  );
+  if (existing === PYTHON_RUNTIME_MARKER_CONTENT) {
+    return;
+  }
+  if (existing !== null) {
+    throw new BootstrapError(
+      `Refusing to replace an unrelated Python runtime marker: ${runtime.marker}`,
+      3,
+    );
+  }
+  writeFileSync(runtime.marker, PYTHON_RUNTIME_MARKER_CONTENT, { encoding: "utf8", flag: "wx" });
+}
+
+async function ensurePythonRuntime(runtime, status, runLong, run) {
+  if (validatePythonRuntime(runtime, run) !== status) {
+    throw new BootstrapError(
+      `Managed Python runtime changed after confirmation: ${runtime.directory}`,
+      3,
+    );
+  }
+  if (status === "absent") {
+    mkdirSync(path.dirname(runtime.directory), { recursive: true });
+    try {
+      mkdirSync(runtime.directory);
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new BootstrapError(
+          `Managed Python runtime changed after confirmation: ${runtime.directory}`,
+          3,
+        );
+      }
+      throw error;
+    }
+    try {
+      writePythonRuntimeMarker(runtime);
+    } catch (error) {
+      try {
+        rmdirSync(runtime.directory);
+      } catch {
+        // Preserve the marker failure as the actionable error.
+      }
+      throw error;
+    }
+  }
+  if (status !== "current") {
+    try {
+      await runLong({
+        command: runtime.baseExecutable,
+        args: ["-m", "venv", runtime.directory],
+      });
+    } catch (error) {
+      throw new BootstrapError(
+        `Python venv is unavailable for ${runtime.baseExecutable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup. ${error.message}`,
+        2,
+      );
+    }
+  }
+  verifyFile(
+    runtime.executable,
+    `Managed Python runtime was not created correctly: ${runtime.executable}`,
+  );
+}
+
 export function gitcodeInstallDetails(
   classification,
   environment = process.env,
@@ -993,11 +1166,11 @@ export function gitcodeInstallDetails(
   };
 }
 
-function readOptionalFile(file) {
+function readOptionalFile(file, invalidMessage = `Refusing to overwrite unrelated wrapper: ${file}`) {
   try {
     const metadata = lstatSync(file);
     if (metadata.isSymbolicLink() || !metadata.isFile()) {
-      throw new BootstrapError(`Refusing to overwrite unrelated wrapper: ${file}`, 3);
+      throw new BootstrapError(invalidMessage, 3);
     }
     return readFileSync(file, "utf8");
   } catch (error) {
@@ -1142,7 +1315,11 @@ function printPlan(plan, write) {
     write(`  Wrapper target: ${plan.gitcodeInstall.cliTarget}`);
   }
   write(`  npm command: ${formatCommand(plan.installInvocation)}`);
-  write(`  Python: ${plan.python.executable} (${plan.python.version.join(".")})`);
+  write(`  Base Python: ${plan.python.executable} (${plan.python.version.join(".")})`);
+  write(`  Managed Python runtime: ${plan.pythonRuntime.directory} (${plan.pythonRuntime.status})`);
+  if (plan.pythonRuntime.status === "absent") {
+    write(`  Python venv command: ${formatCommand(plan.venvInvocation)}`);
+  }
   write(`  Python dependency command: ${formatCommand(plan.pipInvocation)}`);
   write("  Browser binary download: disabled");
   write(`  GitCode authentication command when needed: ${plan.gitcodeInstall.workflowCommand} auth login --web`);
@@ -1259,8 +1436,9 @@ function textResult(result, write) {
   if (result.gitcode.authentication.username) {
     write(`  Username: ${result.gitcode.authentication.username}`);
   }
-  write(`  Python: ${result.python.executable} ${result.python.version}`);
-  write("  Playwright Python package: installed");
+  write(`  Base Python: ${result.python.baseExecutable} ${result.python.baseVersion}`);
+  write(`  Managed Python runtime: ${result.python.executable}`);
+  write("  Playwright Python package: installed in managed runtime");
   write("  Chromium: not downloaded");
 }
 
@@ -1334,9 +1512,27 @@ export async function runSetup(options, dependencies = {}) {
   );
 
   const python = detectPython(run, platform);
-  run({ command: python.executable, args: ["-m", "pip", "--version"] });
-  const pipInvocation = {
+  const venvCapability = runOptional(run, {
     command: python.executable,
+    args: ["-m", "venv", "--help"],
+  });
+  if (venvCapability.status !== 0) {
+    throw new BootstrapError(
+      `Python venv is unavailable for ${python.executable}. Install the venv component for this Python (for example python3-venv on Debian/Ubuntu) and rerun setup.`,
+      2,
+    );
+  }
+  const configuredPythonRuntime = pythonRuntimeDetails(python, environment, platform);
+  const pythonRuntime = dependencies.pythonRuntimeDir
+    ? pythonRuntimeAt(dependencies.pythonRuntimeDir, python, platform)
+    : configuredPythonRuntime;
+  pythonRuntime.status = validatePythonRuntime(pythonRuntime, run);
+  const venvInvocation = {
+    command: python.executable,
+    args: ["-m", "venv", pythonRuntime.directory],
+  };
+  const pipInvocation = {
+    command: pythonRuntime.executable,
     args: ["-m", "pip", "install", "-r", layouts[0].bundledPythonRequirements],
   };
   const plan = {
@@ -1347,6 +1543,8 @@ export async function runSetup(options, dependencies = {}) {
     installInvocation,
     gitcodeInstall,
     python,
+    pythonRuntime,
+    venvInvocation,
     pipInvocation,
   };
   printPlan(plan, writePlan);
@@ -1365,6 +1563,20 @@ export async function runSetup(options, dependencies = {}) {
     validateWrapper(gitcodeInstall, platform);
   }
 
+  await progress.run(
+    pythonRuntime.status === "absent"
+      ? "Creating the managed Python runtime"
+      : pythonRuntime.status === "repair"
+        ? "Repairing the managed Python runtime"
+        : "Validating the managed Python runtime",
+    () => ensurePythonRuntime(pythonRuntime, pythonRuntime.status, runLong, run),
+  );
+  await progress.run("Installing reviewed Python dependencies", () => runLong(pipInvocation));
+  await progress.run(
+    "Verifying the Playwright Python package",
+    () => runLong({ command: pythonRuntime.executable, args: ["-c", "import playwright.sync_api"] }),
+  );
+
   const installed = await progress.run(
     "Installing the official GitCode CLI",
     () => installGitcode(plan, runLong, run, platform),
@@ -1375,12 +1587,6 @@ export async function runSetup(options, dependencies = {}) {
   );
   gitcode.command = installed.command;
   gitcode.executable = installed.executable;
-
-  await progress.run("Installing reviewed Python dependencies", () => runLong(pipInvocation));
-  await progress.run(
-    "Verifying the Playwright Python package",
-    () => runLong({ command: python.executable, args: ["-c", "import playwright.sync_api"] }),
-  );
   gitcode.authentication = await authenticateGitcode(
     installed.executable,
     gitcode.authentication,
@@ -1411,8 +1617,10 @@ export async function runSetup(options, dependencies = {}) {
     skills,
     gitcode,
     python: {
-      executable: python.executable,
-      version: python.version.join("."),
+      baseExecutable: python.executable,
+      baseVersion: python.version.join("."),
+      runtimeDirectory: pythonRuntime.directory,
+      executable: pythonRuntime.executable,
       playwright: "installed",
       chromium: "not-downloaded",
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msd/README.md

@@ -146,7 +146,7 @@ PR：https://gitcode.com/Ascend/example/pulls/456
 本地仓库：D:\work\example
 ```
 
-CI 通过后立即停止，不处理 feedback 或 merge。识别为 openLiBing 且只读 API 返回 401/403 时，可自动安装 Python Playwright 依赖并打开已有的系统 Chrome/Edge 或 Playwright Chromium，认证成功后继续本 action；不会自动下载浏览器，浏览器不可用时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。可用 `autonomous-ci` 只授权同一 PR 上根因明确的最小 CI 修复循环。
+CI 通过后立即停止，不处理 feedback 或 merge。识别为 openLiBing 且只读 API 返回 401/403 时，使用 setup 创建的受管 Python 运行时和其中的 Playwright 打开已有的系统 Chrome/Edge 或 Playwright Chromium，认证成功后继续本 action；运行时不可用时停止并要求运行 `npx msdevflow@latest setup`，不会在 action 内调用 pip，也不会自动下载浏览器。浏览器不可用时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。可用 `autonomous-ci` 只授权同一 PR 上根因明确的最小 CI 修复循环。
 
 ### 只验证 openLiBing OAuth
 
@@ -155,7 +155,7 @@ CI 通过后立即停止，不处理 feedback 或 merge。识别为 openLiBing
 本地仓库：D:\work\example
 ```
 
-本 action 从当前工作区唯一识别 canonical，只在该仓库内按“当前分支关联 PR → 最近开放 PR → 最近合入 PR”的顺序选择一个包含 openLiBing run 的验证目标，不要求用户提供 PR。它可自动安装 Python Playwright 依赖，并使用已有的系统 Chrome/Edge 或 Playwright Chromium打开可见窗口；不会自动下载浏览器。用户亲自完成 GitCode 登录和授权。浏览器不可用时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`；人工浏览器登录不等于验证完成。只有 OAuth 后对固定 run 的真实只读请求成功才完成，随后立即停止，不进入 `ci`。
+本 action 从当前工作区唯一识别 canonical，只在该仓库内按“当前分支关联 PR → 最近开放 PR → 最近合入 PR”的顺序选择一个包含 openLiBing run 的验证目标，不要求用户提供 PR。它使用 setup 创建的受管 Python 运行时和其中的 Playwright，并使用已有的系统 Chrome/Edge 或 Playwright Chromium 打开可见窗口；运行时不可用时要求运行 `npx msdevflow@latest setup`，不会在 action 内调用 pip，也不会自动下载浏览器。用户亲自完成 GitCode 登录和授权。浏览器不可用时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`；人工浏览器登录不等于验证完成。只有 OAuth 后对固定 run 的真实只读请求成功才完成，随后立即停止，不进入 `ci`。
 
 它不读取或输出 GitCode Token。openLiBing Token 只驻留当前 Python 进程，固定显示为 `redacted`；持久化的只有受管专用 profile 中的 GitCode 浏览器登录态。
 
@@ -241,13 +241,23 @@ npx msdevflow@latest setup
 
 `setup` 是幂等的：内容一致时保持 `current`，内容不同时原子更新。
 
-`setup` 默认检测 PATH 中的 Claude Code、Codex 和 OpenCode，先展示客户端、物理 skill 目标、安装或更新状态、GitCode CLI 归属、registry、安装模式、Python 依赖命令和认证方式；用户确认后，在同一次运行中：
+`setup` 默认检测 PATH 中的 Claude Code、Codex 和 OpenCode，先展示客户端、物理 skill 目标、安装或更新状态、GitCode CLI 归属、registry、安装模式、受管 Python 运行时、依赖命令和认证方式；用户确认后，在同一次运行中：
 
-1. 从 npm 包内的 `skill/msd` 核心和十个 `skill/msd-<action>` 路由器原子安装或更新整套入口；
-2. 安装或升级官方 GitCode npm CLI；
-3. 安装内置 `scripts/requirements.txt` 中的 Python Playwright 包；
+1. 创建、修复或复用 msdevflow 受管 Python venv；
+2. 用受管 Python 安装内置 `scripts/requirements.txt` 中的 Playwright 包；
+3. 安装或升级官方 GitCode npm CLI；
 4. 验收 workflow 所需 schema/API；
-5. CLI 未认证时运行选定命令的 `auth login --web`。
+5. CLI 未认证时运行选定命令的 `auth login --web`；
+6. 从 npm 包内的 `skill/msd` 核心和十个 `skill/msd-<action>` 路由器原子安装或更新整套入口。
+
+受管运行时默认位于：
+
+```text
+Windows:     %LOCALAPPDATA%\msdevflow\python
+macOS/Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/msdevflow/python
+```
+
+可用 `MSDEVFLOW_PYTHON_DIR` 覆盖，值必须是绝对路径或以 `~` 开头；setup 与后续 action 必须使用同一配置。`venv` 属于 CPython 标准库，但精简发行版可能缺失；Debian/Ubuntu 通常需要用户自行安装 `python3-venv`。setup 不执行 sudo，不回退到全局 pip，也不使用 `--break-system-packages`。来源不明或 marker 损坏的运行时目录不会被接管。
 
 客户端到物理目录的映射：
 

package/skill/msd/references/ci-and-review.md

@@ -11,7 +11,7 @@
 
 不要把一个仓库的 `compile`、label 或机器人协议迁移到另一个仓库。
 
-若评论/文档明确为 openLiBing，按需加载 [openlibing-ci.md](openlibing-ci.md)；先用 GitCode 评论定位 run/job，再尝试只读 detail/log API。401/403 时，显式 `action=ci` 和完整 E2E 都直接进入安全 OAuth 子流程，允许自动安装 Python Playwright 依赖并打开已有的系统 Chrome/Edge 或 Playwright Chromium，但不自动下载浏览器；成功后恢复原 CI 诊断，浏览器不可用时输出 OAuth 链接并停止为 `blocked: browser-required`。不得把 GitCode Actions 当作 openLiBing。
+若评论/文档明确为 openLiBing，按需加载 [openlibing-ci.md](openlibing-ci.md)；先用 GitCode 评论定位 run/job，再尝试只读 detail/log API。401/403 时，显式 `action=ci` 和完整 E2E 都直接进入安全 OAuth 子流程，使用 setup 创建的受管 Python 运行时和其中的 Playwright，并打开已有的系统 Chrome/Edge 或 Playwright Chromium；action 内不调用 pip，也不自动下载浏览器。受管运行时不可用时要求运行 `npx msdevflow@latest setup`；成功后恢复原 CI 诊断，浏览器不可用时输出 OAuth 链接并停止为 `blocked: browser-required`。不得把 GitCode Actions 当作 openLiBing。
 
 记录适配器：
 

package/skill/msd/references/command-capabilities.md

@@ -42,7 +42,7 @@ CLI 缺失、版本低于推荐下限或所需 schema 不存在时，当前 acti
 npx msdevflow setup
 ```
 
-独立 setup 会在同一次确认后安装或更新 npm 包内置的 `msdevflow` skill，安装或升级官方 npm 包 `@gitcode-cli/cli@latest`，保留已有 Python `gitcode`，默认安装内置 `scripts/requirements.txt` 中的 Playwright，并验收 workflow 所需 schema/API。它不下载 Playwright Chromium。若 CLI 未认证，setup 会启动 `<gitcode-command> auth login --web` 的官方浏览器流程；凭证由 GitCode CLI 自己接收和保存，setup 不读取、打印或转存 Token，也不要求用户把 Token 传给 Agent。workflow 不在 action 内隐式安装依赖。setup 成功后重新探测环境并恢复原 action；不要 fallback 到可能安装旧实现的 PyPI `gitcode-cli`。
+独立 setup 会在同一次确认后安装或更新 npm 包内置的 `msd` Skill 套件，安装或升级官方 npm 包 `@gitcode-cli/cli@latest`，保留已有 Python `gitcode`，创建或修复 msdevflow 受管 Python venv，在其中安装 `scripts/requirements.txt` 的 Playwright，并验收 workflow 所需 schema/API。它不修改系统 Python、不使用 `--break-system-packages`、不回退到全局 pip，也不下载 Playwright Chromium。若 Python 发行版缺少 `venv`，setup 明确阻断；Debian/Ubuntu 通常需要用户自行安装 `python3-venv`。若 CLI 未认证，setup 会启动 `<gitcode-command> auth login --web` 的官方浏览器流程；凭证由 GitCode CLI 自己接收和保存，setup 不读取、打印或转存 Token，也不要求用户把 Token 传给 Agent。workflow 不在 action 内隐式安装依赖。setup 成功后重新探测环境并恢复原 action；不要 fallback 到可能安装旧实现的 PyPI `gitcode-cli`。
 
 ## 能力降级顺序
 

package/skill/msd/references/openlibing-ci.md

@@ -20,7 +20,14 @@
 
 ### 执行和完成证据
 
-setup 默认安装 `scripts/requirements.txt` 中的 Python Playwright 依赖；脚本在依赖缺失时也可从同一清单受控恢复，但不下载 Playwright Chromium。脚本优先使用系统 Chrome/Edge，其次使用当前 Playwright 环境中已经存在的 Chromium。然后运行：
+setup 在所有平台创建或修复一个 msdevflow 受管 Python venv，并在其中安装 `scripts/requirements.txt` 的 Playwright；脚本进入 OAuth 流程时自动重启到该受管解释器。受管运行时或 Playwright 不可用时要求运行 `npx msdevflow@latest setup`，脚本自身不调用 pip，不修改系统 Python，也不下载 Playwright Chromium。脚本优先使用系统 Chrome/Edge，其次使用受管 Playwright 环境中已经存在的 Chromium。然后运行：
+
+```text
+Windows:     %LOCALAPPDATA%\msdevflow\python
+macOS/Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/msdevflow/python
+```
+
+可用 `MSDEVFLOW_PYTHON_DIR` 覆盖，值必须是绝对路径或以 `~` 开头；setup 与运行 action 时必须保持一致。
 
 ```bash
 python <skill-dir>/scripts/openlibing_ci.py login-check \
@@ -85,7 +92,7 @@ python <skill-dir>/scripts/openlibing_ci.py diagnose \
 python <skill-dir>/scripts/openlibing_ci.py diagnose ... --oauth
 ```
 
-`--oauth` 需要 Python Playwright，以及已有的系统 Chrome/Edge 或当前 Playwright 环境中已经存在的 Chromium。脚本可从 `scripts/requirements.txt` 自动安装受审依赖，但不会执行 `playwright install chromium`；浏览器可用时打开本机可见窗口让用户自己完成 GitCode 登录/授权，浏览器不可用时只输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。捕获的 openLiBing token 只驻留当前 Python 进程内，不打印、不落盘。
+`--oauth` 需要 setup 已准备好的受管 Python 运行时及其中的 Playwright，以及已有的系统 Chrome/Edge 或受管 Playwright 环境中已经存在的 Chromium。脚本不调用 pip，也不会执行 `playwright install chromium`；受管运行时或依赖缺失时停止并要求运行 `npx msdevflow@latest setup`。浏览器可用时打开本机可见窗口让用户自己完成 GitCode 登录/授权，浏览器不可用时只输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。捕获的 openLiBing token 只驻留当前 Python 进程内，不打印、不落盘。
 
 默认使用专用持久浏览器 profile：
 

package/skill/msd/references/pr-and-ci.md

@@ -90,7 +90,7 @@ Suggested next action: ci
 4. 分类当前改动、连带失败、canonical 基线、基础设施、权限或证据不足；
 5. guided 模式确认修复；`autonomous-ci` 只在已授权最小范围内自动修改、验证、新 commit、push 和重触发；
 6. 新 push 后获取新 head，旧 head 结果失效；
-7. openLiBing detail/log 返回 401/403 时，按 [openlibing-ci.md](openlibing-ci.md) 自动安装缺失的 Python Playwright 依赖，并使用已有的系统 Chrome/Edge 或 Playwright Chromium 打开可见浏览器；不自动下载浏览器。用户完成 GitCode 登录/授权且固定 run 验证成功后恢复当前 CI 诊断；浏览器不可用时输出 OAuth 链接并停止为 `blocked: browser-required`；
+7. openLiBing detail/log 返回 401/403 时，按 [openlibing-ci.md](openlibing-ci.md) 使用 setup 创建的受管 Python 运行时和其中的 Playwright，并用已有的系统 Chrome/Edge 或 Playwright Chromium 打开可见浏览器；action 内不调用 pip，也不自动下载浏览器。受管运行时不可用时要求运行 `npx msdevflow@latest setup`；用户完成 GitCode 登录/授权且固定 run 验证成功后恢复当前 CI 诊断，浏览器不可用时输出 OAuth 链接并停止为 `blocked: browser-required`；
 8. 循环至当前 head 全绿或形成证据充分的 blocker。
 
 重试不能代替根因分析。CI 修复不得扩大 Issue 范围；发现产品实现缺失或方案错误时返回 `blocked` 并建议 `action=develop`，不得把 CI action 变成补开发流程。

package/skill/msd/references/state-and-safety.md

@@ -100,7 +100,7 @@ Agent 创建或修改的 Issue/PR 正文，以及发布的 Issue 评论、PR 普
 
 `autonomous-ci` 只授权在同一 PR 的 CI 修复循环中：修改与根因直接相关的代码、运行门禁、创建新 commit、push 同一 source branch、重触发 CI。它不授权扩大需求、force push、降低测试、处理 feedback、review、approve 或 merge。
 
-显式 `openlibing-auth`、显式 `ci` 和完整 E2E 均授权在需要 openLiBing OAuth 时自动安装配套 Python Playwright 依赖并打开可见浏览器，但不授权下载 Playwright Chromium。优先使用系统 Chrome/Edge，其次使用已存在的 Playwright Chromium；均不可用或 Playwright 无法启动时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。该链接只供人工浏览器访问，不能证明当前进程已认证或固定 run 已验证。该授权不允许 Agent 代替用户填写 GitCode 凭证、点击授权同意、读取浏览器 Cookie 值或导出任何 Token。
+显式 `openlibing-auth`、显式 `ci` 和完整 E2E 均授权在需要 openLiBing OAuth 时使用 setup 创建的受管 Python 运行时和其中的 Playwright 打开可见浏览器，但不授权在 action 内调用 pip，也不授权下载 Playwright Chromium。受管运行时不可用时要求用户运行 `npx msdevflow@latest setup`。优先使用系统 Chrome/Edge，其次使用已存在的 Playwright Chromium；均不可用或 Playwright 无法启动时输出可复制的 OAuth 链接并停止为 `blocked: browser-required`。该链接只供人工浏览器访问，不能证明当前进程已认证或固定 run 已验证。该授权不允许 Agent 代替用户填写 GitCode 凭证、点击授权同意、读取浏览器 Cookie 值或导出任何 Token。
 
 ## Guided 检查点
 

package/skill/msd/scripts/openlibing_ci.py

@@ -8,7 +8,6 @@ import os
 import re
 import shutil
 import stat
-import subprocess
 import sys
 import time
 import urllib.error
@@ -79,6 +78,59 @@ LEGACY_PROFILE_MARKERS = {
     },
 }
 PROFILE_METADATA = "session.json"
+PYTHON_RUNTIME_MARKER = ".msdevflow-python-runtime"
+PYTHON_RUNTIME_MARKER_CONTENT = "managed-by=msdevflow\n"
+
+
+def configured_directory(value: str, variable: str) -> Path:
+    selected = Path(value).expanduser()
+    if not selected.is_absolute():
+        raise OpenLibingAuthRequired(
+            f"{variable} 必须是绝对路径或以 ~ 开头。请运行 npx msdevflow@latest setup。"
+        )
+    return selected
+
+
+def default_python_runtime_dir() -> Path:
+    configured = os.getenv("MSDEVFLOW_PYTHON_DIR")
+    if configured:
+        return configured_directory(configured, "MSDEVFLOW_PYTHON_DIR")
+    if os.name == "nt":
+        local_app_data = os.getenv("LOCALAPPDATA")
+        root = (
+            configured_directory(local_app_data, "LOCALAPPDATA")
+            if local_app_data
+            else Path.home() / "AppData" / "Local"
+        )
+        return root / "msdevflow" / "python"
+    data_home = os.getenv("XDG_DATA_HOME")
+    root = (
+        configured_directory(data_home, "XDG_DATA_HOME")
+        if data_home
+        else Path.home() / ".local" / "share"
+    )
+    return root / "msdevflow" / "python"
+
+
+def managed_python_executable(runtime_dir: Path | None = None) -> Path:
+    selected = (runtime_dir or default_python_runtime_dir()).expanduser()
+    executable = selected / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    marker = selected / PYTHON_RUNTIME_MARKER
+    try:
+        owned = (
+            selected.is_dir()
+            and not selected.is_symlink()
+            and marker.is_file()
+            and not marker.is_symlink()
+            and marker.read_text(encoding="utf-8") == PYTHON_RUNTIME_MARKER_CONTENT
+        )
+    except OSError:
+        owned = False
+    if not owned or not executable.is_file():
+        raise OpenLibingAuthRequired(
+            f"msdevflow 受管 Python 运行时不可用：{selected}。请运行 npx msdevflow@latest setup。"
+        )
+    return executable
 
 
 def profile_marker(profile_dir: Path) -> Path:
@@ -181,29 +233,18 @@ def clear_openlibing_storage(context: Any, page: Any, base_url: str) -> None:
         raise OpenLibingAuthRequired("无法从持久 profile 清除 openLiBing Cookie，已拒绝保存会话。")
 
 
-def oauth_requirements_file() -> Path:
-    return Path(__file__).with_name("requirements.txt")
-
-
 def ensure_playwright() -> None:
+    executable = managed_python_executable()
+    active_prefix = os.path.normcase(str(Path(sys.prefix).resolve()))
+    managed_prefix = os.path.normcase(str(default_python_runtime_dir().resolve()))
+    if active_prefix != managed_prefix:
+        os.execv(str(executable), [str(executable), str(Path(__file__).resolve()), *sys.argv[1:]])
     try:
         importlib.import_module("playwright.sync_api")
-        return
-    except ImportError:
-        requirements = oauth_requirements_file()
-        if not requirements.is_file():
-            raise OpenLibingAuthRequired("缺少 openLiBing OAuth 依赖清单，无法自动安装 Playwright。")
-        result = subprocess.run(
-            [sys.executable, "-m", "pip", "install", "-r", str(requirements)],
-            check=False,
-        )
-        if result.returncode != 0:
-            raise OpenLibingAuthRequired("自动安装 Playwright 失败。")
-        importlib.invalidate_caches()
-        try:
-            importlib.import_module("playwright.sync_api")
-        except ImportError as error:
-            raise OpenLibingAuthRequired("Playwright 安装完成但当前 Python 无法导入。") from error
+    except ImportError as error:
+        raise OpenLibingAuthRequired(
+            "受管 Python 运行时缺少 Playwright。请运行 npx msdevflow@latest setup。"
+        ) from error
 
 
 def playwright_chromium_path() -> Path: