From 6be786e25cca5302ccc1c6b8410183fa028b7e5e Mon Sep 17 00:00:00 2001
From: yu-xin-c <2182712990@qq.com>
Date: Tue, 29 Sep 2026 17:11:45 +0800
Subject: [PATCH 1/2] fix(video2code): resolve Python across platforms

---
 marketplace.json                              |  2 +-
 plugins/video2code/.claude-plugin/plugin.json |  8 +-
 plugins/video2code/.mcp.json                  | 14 +++-
 plugins/video2code/.zcode-plugin/plugin.json  |  8 +-
 plugins/video2code/README.md                  | 12 ++-
 plugins/video2code/README_CN.md               | 11 ++-
 plugins/video2code/hooks/check_closeout.py    |  5 +-
 plugins/video2code/hooks/hooks.json           | 10 +--
 plugins/video2code/hooks/run_python.mjs       | 63 +++++++++++++++
 plugins/video2code/mcp/v2c_tools/deploy.py    |  3 +-
 plugins/video2code/skills/env-setup/SKILL.md  |  4 +-
 .../skills/env-setup/scripts/env_doctor.py    | 17 ++--
 plugins/video2code/skills/video2code/SKILL.md |  4 +-
 plugins/video2code/tests/test_env_doctor.py   | 39 ++++++++++
 .../video2code/tests/test_python_launcher.py  | 78 +++++++++++++++++++
 15 files changed, 244 insertions(+), 34 deletions(-)
 create mode 100644 plugins/video2code/hooks/run_python.mjs
 create mode 100644 plugins/video2code/tests/test_python_launcher.py

diff --git a/marketplace.json b/marketplace.json
index b988fe5..2a64d15 100644
--- a/marketplace.json
+++ b/marketplace.json
@@ -117,7 +117,7 @@
         "en": "Records WebM through ZCode's built-in Browser Use WebView and converts it to MP4 with ffmpeg for video/URL replication; no Playwright or external Chromium required.",
         "zh-CN": "基于 ZCode 内置 Browser Use WebView 录制 WebM 并用 ffmpeg 转成 MP4/URL 复刻；无需 Playwright 或外部 Chromium"
       },
-      "version": "0.6.0",
+      "version": "0.6.1",
       "author": {
         "name": "Z.ai",
         "url": "https://z.ai"
diff --git a/plugins/video2code/.claude-plugin/plugin.json b/plugins/video2code/.claude-plugin/plugin.json
index cfc189f..4d55433 100644
--- a/plugins/video2code/.claude-plugin/plugin.json
+++ b/plugins/video2code/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "video2code",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "基于 ZCode 内置 Browser Use WebView 录制 WebM 并用 ffmpeg 转成 MP4/URL 复刻；无需 Playwright 或外部 Chromium",
   "author": {
     "name": "Z.ai",
@@ -34,8 +34,9 @@
   "mcpServers": {
     "runtime": {
       "type": "stdio",
-      "command": "python3",
+      "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
         "${CLAUDE_PLUGIN_ROOT}/mcp/runtime_server.py"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
@@ -47,8 +48,9 @@
     },
     "video": {
       "type": "stdio",
-      "command": "python3",
+      "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
         "${CLAUDE_PLUGIN_ROOT}/mcp/video_server.py"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
diff --git a/plugins/video2code/.mcp.json b/plugins/video2code/.mcp.json
index 0bb0ccc..9b4d5e3 100644
--- a/plugins/video2code/.mcp.json
+++ b/plugins/video2code/.mcp.json
@@ -2,8 +2,11 @@
   "mcpServers": {
     "runtime": {
       "type": "stdio",
-      "command": "python3",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/runtime_server.py"],
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/runtime_server.py"
+      ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "env": {
         "V2C_PLUGIN_ROOT": "${CLAUDE_PLUGIN_ROOT}",
@@ -13,8 +16,11 @@
     },
     "video": {
       "type": "stdio",
-      "command": "python3",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/video_server.py"],
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/video_server.py"
+      ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "env": {
         "V2C_PLUGIN_ROOT": "${CLAUDE_PLUGIN_ROOT}",
diff --git a/plugins/video2code/.zcode-plugin/plugin.json b/plugins/video2code/.zcode-plugin/plugin.json
index cfc189f..4d55433 100644
--- a/plugins/video2code/.zcode-plugin/plugin.json
+++ b/plugins/video2code/.zcode-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "video2code",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "基于 ZCode 内置 Browser Use WebView 录制 WebM 并用 ffmpeg 转成 MP4/URL 复刻；无需 Playwright 或外部 Chromium",
   "author": {
     "name": "Z.ai",
@@ -34,8 +34,9 @@
   "mcpServers": {
     "runtime": {
       "type": "stdio",
-      "command": "python3",
+      "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
         "${CLAUDE_PLUGIN_ROOT}/mcp/runtime_server.py"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
@@ -47,8 +48,9 @@
     },
     "video": {
       "type": "stdio",
-      "command": "python3",
+      "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
         "${CLAUDE_PLUGIN_ROOT}/mcp/video_server.py"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}",
diff --git a/plugins/video2code/README.md b/plugins/video2code/README.md
index 99b8c77..db21643 100644
--- a/plugins/video2code/README.md
+++ b/plugins/video2code/README.md
@@ -69,7 +69,13 @@ Two stdio MCP servers, declared in both [`.mcp.json`](./.mcp.json) and the plugi
 
 ## Hooks
 
-All four are `command` hooks running `python3` against scripts in [`hooks/`](./hooks).
+All four are `command` hooks. They and both MCP servers use the bundled
+[`run_python.mjs`](./hooks/run_python.mjs) launcher instead of assuming the host
+provides a `python3` executable. On Windows it tries `py -3`, `python`, then
+`python3`; on macOS and Linux it tries `python3`, then `python`. The launcher
+preserves the selected interpreter's exit status and defaults Python stdio to
+UTF-8 so localized Hook output is not limited by the Windows console code page.
+Existing `PYTHONUTF8` and `PYTHONIOENCODING` values are respected.
 
 | Event | Script | Behavior |
 | --- | --- | --- |
@@ -90,8 +96,8 @@ All four are `command` hooks running `python3` against scripts in [`hooks/`](./h
 Run the doctor rather than checking by hand:
 
 ```bash
-python3 skills/env-setup/scripts/env_doctor.py
-python3 skills/env-setup/scripts/env_doctor.py --fix
+node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py
+node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py --fix
 ```
 
 ## Side effects, network access, and data
diff --git a/plugins/video2code/README_CN.md b/plugins/video2code/README_CN.md
index 895863f..a5b0638 100644
--- a/plugins/video2code/README_CN.md
+++ b/plugins/video2code/README_CN.md
@@ -69,7 +69,12 @@
 
 ## Hooks
 
-四个都是 `command` 类型，用 `python3` 执行 [`hooks/`](./hooks) 下的脚本。
+四个都是 `command` 类型。它们和两个 MCP 服务都通过插件自带的
+[`run_python.mjs`](./hooks/run_python.mjs) 启动 Python，不再假设宿主一定提供
+`python3` 命令。Windows 依次尝试 `py -3`、`python`、`python3`，macOS 和 Linux
+依次尝试 `python3`、`python`；选中解释器后会原样传递其退出码，并默认把 Python
+标准输入输出设为 UTF-8，避免中文 Hook 输出受 Windows 控制台代码页限制。调用方已经
+设置的 `PYTHONUTF8` 或 `PYTHONIOENCODING` 会被保留。
 
 | 事件 | 脚本 | 行为 |
 | --- | --- | --- |
@@ -90,8 +95,8 @@
 不要手工逐项确认，直接跑体检脚本：
 
 ```bash
-python3 skills/env-setup/scripts/env_doctor.py
-python3 skills/env-setup/scripts/env_doctor.py --fix
+node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py
+node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py --fix
 ```
 
 ## 副作用、网络访问与数据
diff --git a/plugins/video2code/hooks/check_closeout.py b/plugins/video2code/hooks/check_closeout.py
index 65b662e..a9d2ceb 100644
--- a/plugins/video2code/hooks/check_closeout.py
+++ b/plugins/video2code/hooks/check_closeout.py
@@ -127,8 +127,9 @@ def main() -> None:
         allow()  # 三振/会话预算用尽/已顶回过 → 放行并已记录, 防死循环
     block_stop(
         "复刻契约未闭环, 不能收尾:\n- " + "\n- ".join(res["gaps"]) +
-        "\n先自己跑审计脚本对账: python3 <plugin_root>/skills/video2code/scripts/"
-        "contract_audit.py (plugin_root 见会话开头横幅, 兜底 cat .v2c/plugin_root), "
+        "\n先自己跑审计脚本对账: node \"<plugin_root>/hooks/run_python.mjs\" "
+        "\"<plugin_root>/skills/video2code/scripts/contract_audit.py\" "
+        "(plugin_root 见会话开头横幅, 兜底 cat .v2c/plugin_root), "
         "按缺口逐条补完 (D 项成对证据用 composite_view 的 beats 视频输入一轮即出), "
         "全绿后再收尾。\n"
         "若用户本轮要的其实不是这个复刻任务 (契约是本会话早前认领的, 但用户已经转去别的事, "
diff --git a/plugins/video2code/hooks/hooks.json b/plugins/video2code/hooks/hooks.json
index fff69b8..2012170 100644
--- a/plugins/video2code/hooks/hooks.json
+++ b/plugins/video2code/hooks/hooks.json
@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/env_check.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/env_check.py\"",
             "timeout": 30,
             "statusMessage": "video2code 环境检查…"
           }
@@ -18,12 +18,12 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check_video_input.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/check_video_input.py\"",
             "timeout": 15
           },
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check_url_input.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/check_url_input.py\"",
             "timeout": 10
           }
         ]
@@ -35,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check_plan_first.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/check_plan_first.py\"",
             "timeout": 10
           }
         ]
@@ -46,7 +46,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check_closeout.py\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs\" \"${CLAUDE_PLUGIN_ROOT}/hooks/check_closeout.py\"",
             "timeout": 15
           }
         ]
diff --git a/plugins/video2code/hooks/run_python.mjs b/plugins/video2code/hooks/run_python.mjs
new file mode 100644
index 0000000..96fde44
--- /dev/null
+++ b/plugins/video2code/hooks/run_python.mjs
@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/** Run a plugin Python entrypoint with platform-appropriate interpreter names. */
+
+import { spawnSync } from "node:child_process";
+
+const [script, ...scriptArgs] = process.argv.slice(2);
+
+if (!script) {
+  process.stderr.write("Usage: run_python.mjs <script> [...args]\n");
+  process.exit(2);
+}
+
+const candidates =
+  process.platform === "win32"
+    ? [
+        ["py", ["-3"]],
+        ["python", []],
+        ["python3", []],
+      ]
+    : [
+        ["python3", []],
+        ["python", []],
+      ];
+
+const childEnv = { ...process.env };
+if (childEnv.PYTHONUTF8 === undefined) childEnv.PYTHONUTF8 = "1";
+if (childEnv.PYTHONIOENCODING === undefined) childEnv.PYTHONIOENCODING = "utf-8";
+
+for (const [command, prefixArgs] of candidates) {
+  const probe = spawnSync(
+    command,
+    [
+      ...prefixArgs,
+      "-c",
+      "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)",
+    ],
+    { env: childEnv, stdio: "ignore" },
+  );
+
+  if (probe.error?.code === "ENOENT") continue;
+  if (probe.error || probe.status !== 0) continue;
+
+  const result = spawnSync(command, [...prefixArgs, script, ...scriptArgs], {
+    env: childEnv,
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    process.stderr.write(`[video2code] failed to start ${command}: ${result.error}\n`);
+    process.exit(1);
+  }
+  if (result.signal) {
+    process.stderr.write(`[video2code] ${command} exited via ${result.signal}\n`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+process.stderr.write(
+  "[video2code] No compatible Python interpreter was found; install Python 3.10+ and retry.\n",
+);
+process.exit(127);
diff --git a/plugins/video2code/mcp/v2c_tools/deploy.py b/plugins/video2code/mcp/v2c_tools/deploy.py
index c297462..6f65030 100644
--- a/plugins/video2code/mcp/v2c_tools/deploy.py
+++ b/plugins/video2code/mcp/v2c_tools/deploy.py
@@ -16,6 +16,7 @@
 import shutil
 import socket
 import subprocess
+import sys
 import time
 import uuid
 from pathlib import Path
@@ -88,7 +89,7 @@ def _last_server(ctx: RunContext) -> dict | None:
 def _spawn_httpd(dst: Path, port: int) -> subprocess.Popen:
     """起 http.server (allow_reuse_address 默认开, 原端口进程死后可立即重绑)。"""
     proc = subprocess.Popen(
-        ["python3", "-m", "http.server", str(port), "--bind", "127.0.0.1"],
+        [sys.executable, "-m", "http.server", str(port), "--bind", "127.0.0.1"],
         cwd=str(dst),
         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
     )
diff --git a/plugins/video2code/skills/env-setup/SKILL.md b/plugins/video2code/skills/env-setup/SKILL.md
index d646dc9..f23a588 100644
--- a/plugins/video2code/skills/env-setup/SKILL.md
+++ b/plugins/video2code/skills/env-setup/SKILL.md
@@ -8,8 +8,8 @@ description: "Check and provision the video2code plugin environment: Python/MCP/
 唯一入口：
 
 ```bash
-python3 <plugin_root>/skills/env-setup/scripts/env_doctor.py
-python3 <plugin_root>/skills/env-setup/scripts/env_doctor.py --fix
+node "<plugin_root>/hooks/run_python.mjs" "<plugin_root>/skills/env-setup/scripts/env_doctor.py"
+node "<plugin_root>/hooks/run_python.mjs" "<plugin_root>/skills/env-setup/scripts/env_doctor.py" --fix
 ```
 
 插件根路径由 SessionStart 输出，并写入 `.v2c/plugin_root`。完整探测给 Bash ≥120s。
diff --git a/plugins/video2code/skills/env-setup/scripts/env_doctor.py b/plugins/video2code/skills/env-setup/scripts/env_doctor.py
index 797b4c4..32a43f3 100644
--- a/plugins/video2code/skills/env-setup/scripts/env_doctor.py
+++ b/plugins/video2code/skills/env-setup/scripts/env_doctor.py
@@ -25,10 +25,12 @@
 
 import argparse
 import hashlib
+import importlib
 import importlib.util
 import importlib.metadata as importlib_metadata
 import json
 import os
+import site
 import shutil
 import subprocess
 import sys
@@ -42,9 +44,10 @@
 WEB_SCRIPTS = PLUGIN_ROOT / "skills" / "web-replicate" / "scripts"
 TPL_DIR = PLUGIN_ROOT / "skills" / "web-replicate" / "templates" / "default" / "template"
 NM_LOCAL_ROOT = Path(os.environ.get("NM_LOCAL_ROOT", "/tmp/webapp-node-modules"))
-PY = sys.executable or "python3"
+PY = sys.executable or ("python" if os.name == "nt" else "python3")
 # 命令行里用 PYQ: Windows 解释器路径常含空格, do_fix 又走 shell=True
 PYQ = f'"{PY}"' if " " in PY else PY
+PIP_USER_INSTALL = f"{PYQ} -m pip install --user --break-system-packages"
 
 OS = ("macos" if sys.platform == "darwin"
       else "windows" if os.name == "nt" else "linux")
@@ -231,7 +234,7 @@ def probe_nm_master() -> tuple[bool, str]:
 ]
 
 CHECKS: list[Check] = [
-    Check("py", "python3 ≥ 3.10", "hook 与 MCP server 用了 3.10+ 语法 (X | Y 注解)",
+    Check("py", "Python ≥ 3.10", "hook 与 MCP server 用了 3.10+ 语法 (X | Y 注解)",
           probe_py_version,
           need="Python 3.10 或更高 (CC 调 hook/MCP 用的就是这个解释器)",
           fix=by_os(any=["# 换一个 3.10+ 解释器, 例如 conda create -n v2c python=3.12"]),
@@ -240,11 +243,11 @@ def probe_nm_master() -> tuple[bool, str]:
           "MCP server 本体 — 缺少或装到 2.x 会导致 deploy/clip_video 工具不存在",
           probe_mcp_sdk,
           need=f"pip 包 mcp=={MCP_SDK_VERSION} (2.x 已删除本插件使用的 Server decorator API)",
-          fix=[f"{PYQ} -m pip install --user --break-system-packages mcp=={MCP_SDK_VERSION}"],
+          fix=[f"{PIP_USER_INSTALL} mcp=={MCP_SDK_VERSION}"],
           cheap=True, auto=True, needs="py"),
     *[Check(f"py-{mod}", f"python 包: {mod}", why, probe_module(mod),
             need=f"pip 包 {pkg} (装进上面那个解释器, 不是系统里随便哪个 python)",
-            fix=[f"{PYQ} -m pip install {pkg}"], cheap=True, auto=True, needs="py")
+            fix=[f"{PIP_USER_INSTALL} {pkg}"], cheap=True, auto=True, needs="py")
       for mod, pkg, why in PY_MODULES],
     Check("ffmpeg", "ffmpeg + ffprobe", "video MCP 摄入 / clip 抽帧 / 时长探测 / url2video 把录制的 WebM 转成 MP4（必需）",
           probe_bins("ffmpeg", "ffprobe"),
@@ -364,7 +367,7 @@ def render(results: list[Result]) -> str:
         for cmd in r.check.fix:
             lines.append(f"       {cmd}")
     if any(r.check.auto for r in bad if r.status == "missing"):
-        lines.append(f"[env] 自动项可一把过: python3 {Path(__file__).name} --fix "
+        lines.append(f"[env] 自动项可一把过: {PYQ} {Path(__file__).name} --fix "
                      "(只跑上面标 自动可装 的命令)")
     return "\n".join(lines)
 
@@ -390,6 +393,10 @@ def do_fix(results: list[Result]) -> list[Result]:
             fixed.add(r.check.id)
     if not fixed:
         return results
+    user_site = site.getusersitepackages()
+    if isinstance(user_site, str) and Path(user_site).is_dir() and user_site not in sys.path:
+        site.addsitedir(user_site)
+    importlib.invalidate_caches()
     recheck = {res.check.id: res for res in run_checks(only=fixed)}
     return [recheck.get(r.check.id, r) for r in results]
 
diff --git a/plugins/video2code/skills/video2code/SKILL.md b/plugins/video2code/skills/video2code/SKILL.md
index d882905..f314641 100644
--- a/plugins/video2code/skills/video2code/SKILL.md
+++ b/plugins/video2code/skills/video2code/SKILL.md
@@ -262,7 +262,7 @@ Grading treats a report still carrying the `V2C_REPORT_SKELETON` marker as **unf
 
 **Append at the moment of judgment.** The bookkeeping unit is the evidence artifact: the moment you finish judging an artifact's ids, append those lines in one `cat >> out/verify.jsonl` call, and let that bookkeeping **ride in the same turn as the next acquisition** (append calls first, then the next capture call — pairing them halves the sweep's round count). A `fail` is written when it is discovered, never reconstructed later; do NOT hold judged lines for an end-of-run ledger dump — the file's append timeline is part of the evidence. One artifact usually settles several ids; write them together. Never write a line for a check you haven't actually run.
 
-**Chaining the audit onto an append: use `--progress`.** Running the contract audit in the same `Bash` call as an append (`cat >> … <<EOF … EOF` then `python3 …/contract_audit.py`) is good round economy — keep doing it, but pass `--progress`. The shell returns the *last* command's exit code, so a bare audit that still has gaps (normally just "report.md is still the skeleton", which is the expected state until close-out) makes the whole call come back as a tool error even though your append landed fine. `--progress` prints the identical gap list and exits 0, so a successful append reads as successful. Drop the flag only for the final self-audit in §4.6, where a non-zero exit is the point.
+**Chaining the audit onto an append: use `--progress`.** Running the contract audit in the same `Bash` call as an append (`cat >> … <<EOF … EOF` then `node "<plugin_root>/hooks/run_python.mjs" "…/contract_audit.py"`) is good round economy — keep doing it, but pass `--progress`. The shell returns the *last* command's exit code, so a bare audit that still has gaps (normally just "report.md is still the skeleton", which is the expected state until close-out) makes the whole call come back as a tool error even though your append landed fine. `--progress` prints the identical gap list and exits 0, so a successful append reads as successful. Drop the flag only for the final self-audit in §4.6, where a non-zero exit is the point.
 
 Discipline (each a hard rule):
 - **One id, one line, one examined verdict.** Every line cites the artifact it was actually judged from — ids covered by one artifact are judged one by one against it, never stamped in a batch.
@@ -364,7 +364,7 @@ Pair each recording with `clip_video` of the corresponding source moment and com
 
 **Final motion sweep (mandatory, before the report):** give the Phase-1 contact sheet (and your clip grids) one last scan for any motion or visible state change that never became a tagged plan id. Anything found goes back through the loop — clip → tag → verify — before close-out; a silently missed effect is the same failure as a failed one.
 
-**Self-audit (mandatory, before finalizing the report):** run the contract audit yourself — `python3 <plugin_root>/skills/video2code/scripts/contract_audit.py` (plugin root announced at session start; fallback `cat .v2c/plugin_root`). It mechanically checks the whole contract — coverage, D-id paired evidence under `out/cmp/`, evidence↔id attribution, freshness — and prints a gap list. Fix every gap (missing paired strips: one `composite_view` beats call per id), re-run until it reports clean, and only then finalize `out/report.md`. The Stop hook runs the exact same audit — finishing with gaps just bounces you back here with extra rounds burned; auditing yourself first is always cheaper.
+**Self-audit (mandatory, before finalizing the report):** run the contract audit yourself — `node "<plugin_root>/hooks/run_python.mjs" "<plugin_root>/skills/video2code/scripts/contract_audit.py"` (plugin root announced at session start; fallback `cat .v2c/plugin_root`). It mechanically checks the whole contract — coverage, D-id paired evidence under `out/cmp/`, evidence↔id attribution, freshness — and prints a gap list. Fix every gap (missing paired strips: one `composite_view` beats call per id), re-run until it reports clean, and only then finalize `out/report.md`. The Stop hook runs the exact same audit — finishing with gaps just bounces you back here with extra rounds burned; auditing yourself first is always cheaper.
 
 **The contract belongs to the session that took it on, not to the directory.** The Stop hook only enforces closeout on the session that claimed the contract (claiming happens when you write `out/plan.md` or `app/src/**`), so a replication that *another* session left unfinished in this workspace never becomes your obligation — you get an advisory, not a block. Two consequences: (a) if the user's request this turn is unrelated to a contract you claimed earlier, state the open gaps in one line and **ask** whether to close it out — if they say no, write `.v2c/contract_abandoned` with a one-line reason and finish normally, rather than grinding through a task the user no longer wants; (b) `.v2c/contract_abandoned` is the *user's* exit, never a shortcut around your own gaps — don't write it for a contract the user still wants.
 
diff --git a/plugins/video2code/tests/test_env_doctor.py b/plugins/video2code/tests/test_env_doctor.py
index 92d7f17..3358d25 100644
--- a/plugins/video2code/tests/test_env_doctor.py
+++ b/plugins/video2code/tests/test_env_doctor.py
@@ -2,6 +2,7 @@
 
 import importlib.util
 import sys
+import tempfile
 import unittest
 from pathlib import Path
 from unittest.mock import patch
@@ -41,6 +42,44 @@ def test_accepts_exact_mcp_version(self) -> None:
         self.assertTrue(ok)
         self.assertIn("1.9.0", detail)
 
+    def test_python_package_fixes_use_selected_interpreter_and_user_site(self) -> None:
+        python_package_checks = [
+            check for check in env_doctor.CHECKS if check.id.startswith("py-")
+        ]
+
+        self.assertGreaterEqual(len(python_package_checks), 4)
+        for check in python_package_checks:
+            with self.subTest(check=check.id):
+                self.assertTrue(check.fix)
+                self.assertTrue(check.fix[0].startswith(env_doctor.PIP_USER_INSTALL))
+
+    def test_fix_recheck_adds_new_user_site_to_current_process(self) -> None:
+        check = env_doctor.Check(
+            "fixture",
+            "fixture",
+            "fixture",
+            lambda: (True, "ready"),
+            fix=[f'{env_doctor.PYQ} -c "raise SystemExit(0)"'],
+            auto=True,
+        )
+        missing = env_doctor.Result(check, "missing", "not ready")
+
+        with tempfile.TemporaryDirectory() as directory, patch.object(
+            env_doctor.site, "getusersitepackages", return_value=directory
+        ), patch.object(env_doctor.importlib, "invalidate_caches") as invalidate, patch.object(
+            env_doctor, "CHECKS", [check]
+        ):
+            if directory in sys.path:
+                sys.path.remove(directory)
+            try:
+                result = env_doctor.do_fix([missing])
+                self.assertIn(directory, sys.path)
+                invalidate.assert_called_once_with()
+                self.assertEqual(result[0].status, "ok")
+            finally:
+                if directory in sys.path:
+                    sys.path.remove(directory)
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/plugins/video2code/tests/test_python_launcher.py b/plugins/video2code/tests/test_python_launcher.py
new file mode 100644
index 0000000..d6a1395
--- /dev/null
+++ b/plugins/video2code/tests/test_python_launcher.py
@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[1]
+LAUNCHER = PLUGIN_ROOT / "hooks" / "run_python.mjs"
+
+
+class PythonLauncherTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.node = shutil.which("node")
+        if not cls.node:
+            raise unittest.SkipTest("node is required to exercise the Python launcher")
+
+    def test_executes_script_with_unicode_and_spaced_arguments(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="video2code launcher ") as directory:
+            probe = Path(directory) / "probe script.py"
+            probe.write_text(
+                "import json, sys\n"
+                "print(json.dumps({\"args\": sys.argv[1:], "
+                "\"version\": list(sys.version_info[:2])}, ensure_ascii=False))\n",
+                encoding="utf-8",
+            )
+
+            result = subprocess.run(
+                [self.node, str(LAUNCHER), str(probe), "hello world", "\u590d\u523b"],
+                capture_output=True,
+                encoding="utf-8",
+                check=False,
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        output = json.loads(result.stdout)
+        self.assertEqual(output["args"], ["hello world", "\u590d\u523b"])
+        self.assertGreaterEqual(output["version"], [3, 10])
+
+    def test_preserves_script_exit_status(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="video2code-launcher-") as directory:
+            failure = Path(directory) / "failure.py"
+            failure.write_text("raise SystemExit(7)\n", encoding="utf-8")
+            result = subprocess.run(
+                [self.node, str(LAUNCHER), str(failure)],
+                capture_output=True,
+                encoding="utf-8",
+                check=False,
+            )
+
+        self.assertEqual(result.returncode, 7, result.stderr)
+
+    def test_hook_and_mcp_entries_use_launcher(self) -> None:
+        hooks = json.loads(
+            (PLUGIN_ROOT / "hooks" / "hooks.json").read_text(encoding="utf-8")
+        )["hooks"]
+        for groups in hooks.values():
+            for group in groups:
+                for hook in group["hooks"]:
+                    self.assertIn("hooks/run_python.mjs", hook["command"])
+
+        servers = json.loads(
+            (PLUGIN_ROOT / ".mcp.json").read_text(encoding="utf-8")
+        )["mcpServers"]
+        for server in servers.values():
+            self.assertEqual(server["command"], "node")
+            self.assertEqual(
+                server["args"][0],
+                "${CLAUDE_PLUGIN_ROOT}/hooks/run_python.mjs",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

From 8cbb7a779d1a0eec4b85d1d5efc2b6bfb6e2b508 Mon Sep 17 00:00:00 2001
From: yu-xin-c <2182712990@qq.com>
Date: Tue, 29 Sep 2026 17:44:14 +0800
Subject: [PATCH 2/2] fix(video2code): keep dependency repairs inside
 virtualenvs

---
 plugins/video2code/README.md                  |  4 ++-
 plugins/video2code/README_CN.md               |  4 ++-
 .../skills/env-setup/scripts/env_doctor.py    | 14 ++++++---
 plugins/video2code/tests/test_env_doctor.py   | 29 +++++++++++++++++--
 4 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/plugins/video2code/README.md b/plugins/video2code/README.md
index db21643..bb47ddd 100644
--- a/plugins/video2code/README.md
+++ b/plugins/video2code/README.md
@@ -100,6 +100,8 @@ node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py
 node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py --fix
 ```
 
+The launcher skips interpreters older than Python 3.10. Run the doctor in the same environment as ZCode: GUI and terminal `PATH` values may select different interpreters. Python repairs install into the selected virtual environment, or the selected interpreter's user site outside a virtual environment; externally managed installations such as Homebrew additionally require pip's `--break-system-packages` flag, applied only together with `--user`.
+
 ## Side effects, network access, and data
 
 Enabling this plugin grants code-execution trust. Concretely, it will:
@@ -107,7 +109,7 @@ Enabling this plugin grants code-execution trust. Concretely, it will:
 - **Execute commands** — `ffmpeg`/`ffprobe` for transcoding and frame extraction, and `skills/web-replicate/scripts/init-webapp.sh`, which runs `npm install` to populate `node_modules`.
 - **Write files** — `recordings/` (WebM and MP4), `app/` (the scaffolded project), `out/` (`plan.md`, `verify.jsonl`, `report.md`, comparison images under `out/cmp/`), `.v2c/` (plugin root pointer and hook state, including `.v2c/hook_state/interceptions.jsonl`), and a `node_modules` cache under `/tmp/webapp-node-modules` (override with `NM_LOCAL_ROOT`).
 - **Bind a local port** — `deploy_website` starts a `http.server` on port 8765 or the next free port, bound locally, and stops it when the MCP server process exits.
-- **Access the network** — the npm registry when installing template dependencies, and whatever site you ask it to record.
+- **Access the network** — the configured Python package index when the doctor installs Python dependencies, the npm registry when installing template dependencies, and whatever site you ask it to record.
 - **Send no telemetry** and require no API key, token, or account. There are no credentials in this plugin and nothing is uploaded anywhere.
 
 ## User configuration
diff --git a/plugins/video2code/README_CN.md b/plugins/video2code/README_CN.md
index a5b0638..16089a7 100644
--- a/plugins/video2code/README_CN.md
+++ b/plugins/video2code/README_CN.md
@@ -99,6 +99,8 @@ node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py
 node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py --fix
 ```
 
+启动器会跳过低于 Python 3.10 的解释器。请在与 ZCode 相同的环境中运行体检：GUI 和终端的 `PATH` 可能选中不同解释器。Python 修复会安装到选中的虚拟环境；不在虚拟环境时则安装到该解释器的用户目录。Homebrew 等受外部管理的环境还需要 pip 的 `--break-system-packages` 参数，脚本仅在同时使用 `--user` 时添加它。
+
 ## 副作用、网络访问与数据
 
 启用本插件等于授予代码执行信任。具体地，它会：
@@ -106,7 +108,7 @@ node hooks/run_python.mjs skills/env-setup/scripts/env_doctor.py --fix
 - **执行命令** —— `ffmpeg`/`ffprobe` 做转码与抽帧；`skills/web-replicate/scripts/init-webapp.sh` 会执行 `npm install` 拉起 `node_modules`。
 - **写文件** —— `recordings/`（WebM 与 MP4）、`app/`（脚手架项目）、`out/`（`plan.md`、`verify.jsonl`、`report.md`，以及 `out/cmp/` 下的对照图）、`.v2c/`（插件根路径指针与 hook 状态，含 `.v2c/hook_state/interceptions.jsonl`），以及 `/tmp/webapp-node-modules` 下的 `node_modules` 缓存（可用 `NM_LOCAL_ROOT` 改）。
 - **监听本地端口** —— `deploy_website` 在 8765 或之后第一个空闲端口起 `http.server`，只监听本地，MCP 服务进程退出时统一清理。
-- **访问网络** —— 安装模板依赖时访问 npm registry；以及你让它录制的目标网站。
+- **访问网络** —— 体检脚本安装 Python 依赖时访问配置的 Python 包索引；安装模板依赖时访问 npm registry；以及你让它录制的目标网站。
 - **不上报任何遥测**，不需要 API key、token 或账号。插件里没有任何凭据，也不会把内容上传到任何地方。
 
 ## 用户配置
diff --git a/plugins/video2code/skills/env-setup/scripts/env_doctor.py b/plugins/video2code/skills/env-setup/scripts/env_doctor.py
index 32a43f3..0d36a4c 100644
--- a/plugins/video2code/skills/env-setup/scripts/env_doctor.py
+++ b/plugins/video2code/skills/env-setup/scripts/env_doctor.py
@@ -34,6 +34,7 @@
 import shutil
 import subprocess
 import sys
+import sysconfig
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable
@@ -47,7 +48,11 @@
 PY = sys.executable or ("python" if os.name == "nt" else "python3")
 # 命令行里用 PYQ: Windows 解释器路径常含空格, do_fix 又走 shell=True
 PYQ = f'"{PY}"' if " " in PY else PY
-PIP_USER_INSTALL = f"{PYQ} -m pip install --user --break-system-packages"
+PIP_INSTALL = f"{PYQ} -m pip install"
+if sys.prefix == sys.base_prefix:
+    PIP_INSTALL += " --user"
+    if (Path(sysconfig.get_path("stdlib")) / "EXTERNALLY-MANAGED").is_file():
+        PIP_INSTALL += " --break-system-packages"
 
 OS = ("macos" if sys.platform == "darwin"
       else "windows" if os.name == "nt" else "linux")
@@ -243,11 +248,11 @@ def probe_nm_master() -> tuple[bool, str]:
           "MCP server 本体 — 缺少或装到 2.x 会导致 deploy/clip_video 工具不存在",
           probe_mcp_sdk,
           need=f"pip 包 mcp=={MCP_SDK_VERSION} (2.x 已删除本插件使用的 Server decorator API)",
-          fix=[f"{PIP_USER_INSTALL} mcp=={MCP_SDK_VERSION}"],
+          fix=[f"{PIP_INSTALL} mcp=={MCP_SDK_VERSION}"],
           cheap=True, auto=True, needs="py"),
     *[Check(f"py-{mod}", f"python 包: {mod}", why, probe_module(mod),
             need=f"pip 包 {pkg} (装进上面那个解释器, 不是系统里随便哪个 python)",
-            fix=[f"{PIP_USER_INSTALL} {pkg}"], cheap=True, auto=True, needs="py")
+            fix=[f"{PIP_INSTALL} {pkg}"], cheap=True, auto=True, needs="py")
       for mod, pkg, why in PY_MODULES],
     Check("ffmpeg", "ffmpeg + ffprobe", "video MCP 摄入 / clip 抽帧 / 时长探测 / url2video 把录制的 WebM 转成 MP4（必需）",
           probe_bins("ffmpeg", "ffprobe"),
@@ -394,7 +399,8 @@ def do_fix(results: list[Result]) -> list[Result]:
     if not fixed:
         return results
     user_site = site.getusersitepackages()
-    if isinstance(user_site, str) and Path(user_site).is_dir() and user_site not in sys.path:
+    if (site.ENABLE_USER_SITE and isinstance(user_site, str)
+            and Path(user_site).is_dir() and user_site not in sys.path):
         site.addsitedir(user_site)
     importlib.invalidate_caches()
     recheck = {res.check.id: res for res in run_checks(only=fixed)}
diff --git a/plugins/video2code/tests/test_env_doctor.py b/plugins/video2code/tests/test_env_doctor.py
index 3358d25..c0db96f 100644
--- a/plugins/video2code/tests/test_env_doctor.py
+++ b/plugins/video2code/tests/test_env_doctor.py
@@ -1,9 +1,13 @@
 from __future__ import annotations
 
 import importlib.util
+import json
+import os
+import subprocess
 import sys
 import tempfile
 import unittest
+import venv
 from pathlib import Path
 from unittest.mock import patch
 
@@ -42,7 +46,7 @@ def test_accepts_exact_mcp_version(self) -> None:
         self.assertTrue(ok)
         self.assertIn("1.9.0", detail)
 
-    def test_python_package_fixes_use_selected_interpreter_and_user_site(self) -> None:
+    def test_python_package_fixes_use_selected_interpreter(self) -> None:
         python_package_checks = [
             check for check in env_doctor.CHECKS if check.id.startswith("py-")
         ]
@@ -51,7 +55,27 @@ def test_python_package_fixes_use_selected_interpreter_and_user_site(self) -> No
         for check in python_package_checks:
             with self.subTest(check=check.id):
                 self.assertTrue(check.fix)
-                self.assertTrue(check.fix[0].startswith(env_doctor.PIP_USER_INSTALL))
+                self.assertTrue(check.fix[0].startswith(env_doctor.PIP_INSTALL))
+
+    def test_virtualenv_fix_uses_its_own_package_directory(self) -> None:
+        with tempfile.TemporaryDirectory(prefix="video2code venv ") as directory:
+            venv.EnvBuilder(with_pip=True).create(directory)
+            python = Path(directory) / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+            probe = subprocess.run(
+                [str(python), "-c",
+                 "import json, runpy, sys; "
+                 "doctor = runpy.run_path(sys.argv[1]); "
+                 "print(json.dumps(doctor['PIP_INSTALL']))", str(DOCTOR_PATH)],
+                capture_output=True, text=True, check=True,
+            )
+            command = json.loads(probe.stdout)
+            result = subprocess.run(
+                command + " --no-index v2c-smoke-nonexistent-package",
+                shell=True, capture_output=True, text=True,
+            )
+            self.assertNotIn("--user", command)
+            self.assertNotIn("--break-system-packages", command)
+            self.assertIn("No matching distribution found", result.stderr)
 
     def test_fix_recheck_adds_new_user_site_to_current_process(self) -> None:
         check = env_doctor.Check(
@@ -66,6 +90,7 @@ def test_fix_recheck_adds_new_user_site_to_current_process(self) -> None:
 
         with tempfile.TemporaryDirectory() as directory, patch.object(
             env_doctor.site, "getusersitepackages", return_value=directory
+        ), patch.object(env_doctor.site, "ENABLE_USER_SITE", True
         ), patch.object(env_doctor.importlib, "invalidate_caches") as invalidate, patch.object(
             env_doctor, "CHECKS", [check]
         ):