@follenfang/fupload 0.0.4 → 0.0.6

package/README.md

@@ -42,7 +42,7 @@ fupload/
 - 网易 DD：Windows、Python 3、已安装并登录官方客户端
 - Heybox Workshop：Windows、Python 3、已安装并登录 Heybox 桌面客户端
 
-Heybox ZIP 上传还需要腾讯官方 Python SDK：`python -m pip install cos-python-sdk-v5`。只读命令和纯元数据编辑不依赖该包。
+npm 安装和 `fupload update` 会在用户状态目录中创建 Fuploader 专用 Python venv，并自动安装 Heybox ZIP 上传所需的腾讯官方 COS SDK；不会修改系统 Python。使用 `npm --ignore-scripts` 安装时，首次运行实际 CLI 命令会校验并补齐该 runtime。
 
 官方 `ncc` 的安装命令为 `npm i -g @newbeebox/newbeebox-creator-center-cli@latest`。Fuploader 不读取其凭据文件；用户在自己的终端完成 `ncc login`，Agent 仅用 `ncc whoami -o json` 验证。自动化可在启动 Agent 前注入 `NCC_TOKEN`，令牌不得写入命令参数、项目文件或 Git。
 
@@ -169,7 +169,7 @@ fupload uninstall
 
 `fupload update` 固定安装 `@follenfang/fupload@latest`，随后把默认位置和所有登记有效的自定义 Skill 同步到同一版本。未知目录不会被覆盖。
 
-`fupload uninstall` 先删除所有仍有有效 npm 管理标记的 Fuploader Skill，再调用 npm 删除 `@follenfang/fupload` 和 `fupload` 命令。Skill 清理失败时 npm 包保持可用，处理占用或权限问题后可重试。项目中的 `publish/`、新手盒子/DD 登录数据、DD 日志和 `~/.fupload/curseforge.env` 始终保留。
+`fupload uninstall` 先删除所有仍有有效 npm 管理标记的 Fuploader Skill 和专用 Python runtime，再调用 npm 删除 `@follenfang/fupload` 和 `fupload` 命令。Skill 或 runtime 清理失败时 npm 包保持可用，处理占用或权限问题后可重试。项目中的 `publish/`、新手盒子/DD 登录数据、DD 日志和 `~/.fupload/curseforge.env` 始终保留。
 
 npm 7 及以上不执行卸载 lifecycle，因此直接运行 `npm uninstall -g @follenfang/fupload` 只删除 npm 包和 CLI，可能留下 Skill；它不属于完整卸载流程。
 

package/fupload/SKILL.md

@@ -2,7 +2,7 @@
 name: fupload
 description: Explicit author-publishing workflow for World of Warcraft plugins, configuration shares, and WA/strings on NewBeeBox, NetEase DD, CurseForge, and Heybox Workshop, including CurseForge author project lookup, plugin ZIP upload, and Heybox client-session version management. Use only when the user explicitly invokes `$fupload`, explicitly asks to use the Fupload Skill, or loads this Skill by path. Do not trigger from ordinary mentions of publishing, NewBeeBox, DD, CurseForge, Heybox, plugins, configurations, or WA.
 metadata:
-  version: "0.0.4"
+  version: "0.0.6"
 ---
 
 # Fupload
@@ -60,7 +60,7 @@ Run `<fupload-cli> --help` from the user's project. The npm launcher resolves an
 
 When the npm command is absent and the source/direct-Skill fallback is required, resolve `<skill-root>` from this `SKILL.md` and use `python <skill-root>/scripts/fupload.py`. On Windows, prefer `py -3` only if `python` is unavailable. Do not use a binary, Go source, repository-relative fallback, browser automation, Computer Use, or direct handcrafted HTTP calls. NewBeeBox's official `ncc` is not this bundled CLI and must not be wrapped as a Python `--input` command.
 
-For npm package maintenance, use `fupload update` to update the CLI and every registered managed Skill to `@follenfang/fupload@latest`. For a complete removal, use `fupload uninstall`; it removes every registered Skill that still has a valid Fuploader npm ownership marker, then removes the npm package and command. Do not use direct `npm install -g` or `npm uninstall -g` as the normal Agent-managed update/removal workflow.
+For npm package maintenance, use `fupload update` to update the CLI, managed Python runtime, and every registered managed Skill to `@follenfang/fupload@latest`. The npm installer and launcher create a Fuploader-only venv and install the pinned Python dependencies there; never ask for a system-wide `pip install`. For a complete removal, use `fupload uninstall`; it removes every registered Skill that still has a valid Fuploader npm ownership marker, the managed Python runtime, then the npm package and command. Do not use direct `npm install -g` or `npm uninstall -g` as the normal Agent-managed update/removal workflow.
 
 ## Load only the needed contract
 

package/fupload/references/blackbox.md

@@ -2,7 +2,7 @@
 
 The blackbox provider reuses the signed-in Heybox desktop client's local login state. It never accepts credentials, cookies, tokens, signatures, or COS temporary credentials as input.
 
-ZIP uploads require Tencent's official Python SDK: `python -m pip install cos-python-sdk-v5`. Read-only commands and metadata-only edits do not require that package.
+The npm installer manages Tencent's official COS SDK in a Fuploader-only Python venv. `fupload update` synchronizes it, the launcher repairs a missing or stale runtime before executing the Python CLI, and `fupload uninstall` removes it. No system-wide `pip install` is required.
 
 ## `blackbox plugin edit`
 

package/fupload/scripts/fupload_cli/__init__.py

@@ -1,3 +1,3 @@
 """Fupload Python CLI."""
 
-__version__ = "0.0.4"
+__version__ = "0.0.6"

package/fupload/scripts/fupload_cli/blackbox.py

@@ -6,19 +6,35 @@ from urllib.parse import urlencode
 from urllib.request import Request, urlopen
 from typing import Any, Mapping
 from .errors import FuploadError, ValidationError
-from .blackbox_auth import API_BASE, hkey, load_session
+from .blackbox_auth import API_BASE, CLIENT_VERSION, hkey, load_session
+
+API_MISC_BASE = "https://api.xiaoheihe.cn"
 
 class Blackbox:
     def __init__(self, config: Mapping[str, Any] | None = None, transport=None):
         self.config = dict(config or {})
         self.profile = Path(self.config.get("client_profile") or Path.home() / "AppData/Roaming/heybox-pc-launcher")
         self._transport = transport
-    def _request(self, method, path, body=None, query=None):
+    def _request(self, method, path, body=None, query=None, *, base=API_BASE):
         if self._transport: return self._transport(method, path, body or {}, query or {})
         cookies, identity = load_session(self.profile); ts=int(time.time()); nonce=hashlib.md5((str(ts)+secrets.token_hex(16)).encode()).hexdigest().upper()
-        params={**identity,"version":identity.get("version","1.12.0"),"hkey":hkey(path,ts,nonce),"_time":ts,"_chat_time":int(time.time()*1000),"nonce":nonce,**(query or {})}
-        headers={"User-Agent":"HeyboxApp/1.12.0","x_xhh_tokenid":cookies["x_xhh_tokenid"],"Cookie":"; ".join(f"{k}={v}" for k,v in cookies.items()),"Content-Type":"application/x-www-form-urlencoded"}
-        url=API_BASE+path+"?"+urlencode(params); data=urlencode(body or {},doseq=True).encode() if method=="POST" else None
+        version = identity.get("version") or CLIENT_VERSION
+        params={
+            "app": "heybox",
+            "os_type": "Windows",
+            "web_version": "",
+            **identity,
+            "version": version,
+            "hkey": hkey(path,ts + 1,nonce),
+            "_time": ts,
+            "_chat_time": int(time.time()*1000),
+            "nonce": nonce,
+            **(query or {}),
+        }
+        json_body = base == API_MISC_BASE or path.startswith("/bbs/app/api/qcloud/")
+        headers={"Referer":"https://chat.xiaoheihe.cn","User-Agent":f"HeyboxApp/{identity.get('exe_version') or version}","x_xhh_tokenid":cookies["x_xhh_tokenid"],"Cookie":" ".join(f"{k}={v};" for k,v in cookies.items()),"Content-Type":("application/json;charset=utf-8" if json_body else "application/x-www-form-urlencoded;charset=utf-8")}
+        url=base.rstrip("/")+path+"?"+urlencode(params)
+        data=(json.dumps(body or {}, separators=(",", ":")).encode() if json_body else urlencode(body or {},doseq=True).encode()) if method=="POST" else None
         try:
             with urlopen(Request(url,data=data,headers=headers,method=method),timeout=60) as r: result=json.loads(r.read().decode())
         except Exception as exc: raise FuploadError("Workshop API request failed", endpoint=path, verification_required=method=="POST") from exc
@@ -72,8 +88,10 @@ class Blackbox:
     def version_upsert(self,doc):
         aliases={"module_id":"moduleId","version_id":"versionId","game_versions":"gameVersions","file_url":"fileUrl"}
         normalized={aliases.get(k,k):v for k,v in doc.items() if k not in {"schema","dry_run"}}
+        upload_result = None
         if "file" in normalized and "fileUrl" not in normalized:
-            normalized["fileUrl"]=self.upload_zip(int(normalized["moduleId"]),str(normalized["file"]))["url"]
+            upload_result=self.upload_zip(int(normalized["moduleId"]),str(normalized["file"]))
+            normalized["fileUrl"]=upload_result["url"]
         if "fileUrl" not in normalized and "versionId" in normalized:
             existing = self._find_version(int(normalized["moduleId"]), int(normalized["versionId"]))
             if existing and existing.get("fileUrlHeybox"):
@@ -91,7 +109,10 @@ class Blackbox:
         if not found.get("fileUrlHeybox"):
             mismatches.append("fileUrl")
         if mismatches: raise FuploadError("version upsert readback mismatch",kind="verification_required",verification_required=True,details={"fields":mismatches})
-        return {"accepted":True,"verified":True,"module_id":body["moduleId"],"version_id":found.get("id"),"readback":self._redact(found),"response":self._redact(response)}
+        result={"accepted":True,"verified":True,"module_id":body["moduleId"],"version_id":found.get("id"),"readback":self._redact(found),"response":self._redact(response)}
+        if upload_result:
+            result["upload"]={key:upload_result[key] for key in ("protocol","bytes","sha256") if key in upload_result}
+        return result
     def version_delete(self,doc):
         version_id=doc.get("versionId",doc.get("version_id")); module_id=doc.get("moduleId",doc.get("module_id"))
         if version_id is None or module_id is None: raise ValidationError("versionId and moduleId are required")
@@ -133,6 +154,53 @@ class Blackbox:
         path=Path(file_path)
         if not path.is_file(): raise ValidationError("file does not exist",path="$.file")
         if dry_run: return {"dry_run":True,"bytes":path.stat().st_size,"sha256":hashlib.sha256(path.read_bytes()).hexdigest()}
+        try:
+            return self._upload_zip_v2(path)
+        except FuploadError:
+            # The web creator still exposes the legacy Workshop token route.
+            # Fall back to it when the desktop generic uploader is unavailable.
+            return self._upload_zip_legacy(path)
+
+    def _upload_zip_v2(self, path: Path):
+        file_info = {"name": path.name, "mimetype": "application/zip", "fsize": path.stat().st_size}
+        info = self._result(self._request(
+            "POST", "/bbs/app/api/qcloud/cos/upload/info/v2", base=API_MISC_BASE,
+            body={"file_infos": json.dumps([file_info], separators=(",", ":")), "scope": "any", "need_cache": 0},
+        ))
+        keys = info.get("keys") or []
+        if not keys or not info.get("bucket"):
+            raise FuploadError("Current COS upload info response is incomplete", endpoint="/bbs/app/api/qcloud/cos/upload/info/v2", verification_required=True)
+        key = str(keys[0])
+        token = self._result(self._request(
+            "POST", "/bbs/app/api/qcloud/cos/upload/token/v2", base=API_MISC_BASE,
+            body={"bucket": info["bucket"], "keys": json.dumps([key], separators=(",", ":")), "mimetypes": json.dumps([file_info["mimetype"]]), "is_multipart_upload": 0},
+        ))
+        credentials = token.get("credentials") or {}
+        secret_id = credentials.get("tmpSecretId") or credentials.get("TmpSecretID")
+        secret_key = credentials.get("tmpSecretKey") or credentials.get("TmpSecretKey")
+        session_token = credentials.get("sessionToken") or credentials.get("Token")
+        if not all((secret_id, secret_key, session_token)):
+            raise FuploadError("Current COS upload credentials are incomplete", endpoint="/bbs/app/api/qcloud/cos/upload/token/v2", verification_required=True)
+        try:
+            from qcloud_cos import CosConfig, CosS3Client
+        except ModuleNotFoundError as exc:
+            raise FuploadError("The managed Fuploader Python runtime is missing the Heybox COS SDK", kind="environment_error", details={"repair_command":"fupload update"}) from exc
+        try:
+            cos=CosS3Client(CosConfig(Region=info.get("region") or "ap-shanghai",SecretId=secret_id,SecretKey=secret_key,Token=session_token,Scheme="https"))
+            with path.open("rb") as stream: cos.put_object(Bucket=info["bucket"],Key=key,Body=stream)
+        except Exception as exc:
+            raise FuploadError("COS upload failed", endpoint="/bbs/app/api/qcloud/cos/upload/token/v2", verification_required=True) from exc
+        callback = self._result(self._request(
+            "POST", "/bbs/app/api/qcloud/cos/upload/callback/v2", base=API_MISC_BASE,
+            query={"is_finished": "true"}, body={"keys": json.dumps([key], separators=(",", ":"))},
+        ))
+        urls = callback.get("preview_urls") or callback.get("previewUrls") or []
+        url = urls[0] if urls else callback.get("url")
+        if not url:
+            raise FuploadError("Current COS upload callback did not return a URL", endpoint="/bbs/app/api/qcloud/cos/upload/callback/v2", verification_required=True)
+        return {"url":url,"bytes":path.stat().st_size,"sha256":hashlib.sha256(path.read_bytes()).hexdigest(),"protocol":"v2"}
+
+    def _upload_zip_legacy(self, path: Path):
         size_mb=path.stat().st_size/1024/1024
         token=self._result(self._request("POST","/wow/cos/upload/token/",body={"jsonData":json.dumps({"upload_infos":[{"filename":path.name,"file_size":size_mb,"type":"module"}]},separators=(",",":"))}))
         info=token["info"]; f=token["files"][0]; creds=info["Credentials"].get("Credentials",info["Credentials"])
@@ -140,12 +208,12 @@ class Blackbox:
             from qcloud_cos import CosConfig, CosS3Client
         except ModuleNotFoundError as exc:
             raise FuploadError(
-                "Heybox ZIP upload requires cos-python-sdk-v5",
+                "The managed Fuploader Python runtime is missing the Heybox COS SDK",
                 kind="environment_error",
-                details={"install_command":"python -m pip install cos-python-sdk-v5"},
+                details={"repair_command":"fupload update"},
             ) from exc
         try:
             cos=CosS3Client(CosConfig(Region=info.get("region") or "ap-shanghai",SecretId=creds["TmpSecretID"],SecretKey=creds["TmpSecretKey"],Token=creds["Token"],Scheme="https"))
             with path.open("rb") as stream: cos.put_object(Bucket=info["bucket"],Key=f["key"],Body=stream)
         except Exception as exc: raise FuploadError("COS upload failed",verification_required=True) from exc
-        return {"url":"https://%s/%s"%(info["host"],f["key"]),"bytes":path.stat().st_size,"sha256":hashlib.sha256(path.read_bytes()).hexdigest()}
+        return {"url":"https://%s/%s"%(info["host"],f["key"]),"bytes":path.stat().st_size,"sha256":hashlib.sha256(path.read_bytes()).hexdigest(),"protocol":"legacy"}

package/fupload/scripts/fupload_cli/blackbox_auth.py

@@ -1,11 +1,13 @@
 """Authentication helpers for the Heybox desktop Workshop client."""
 from __future__ import annotations
-import hashlib, json, secrets, sqlite3, time
+import hashlib, json, platform, secrets, sqlite3, time
 from pathlib import Path
 from urllib.parse import parse_qs, urlparse
 from .errors import FuploadError
 
 API_BASE = "https://workshopapi.xiaoheihe.cn"
+CLIENT_VERSION = "1.14.1"
+_CONFIG_AES_KEY = bytes.fromhex("5f1d7f11e6e90dbb5c2f0c1e614a6a8c4b9e16b50fa724e4c54d6f25b1208b93")
 _ALPHABET = "AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89"
 
 def _n8(value: str, limit: int) -> str:
@@ -28,27 +30,130 @@ def hkey(path: str, timestamp: int, nonce: str) -> str:
     digest = hashlib.md5(_interleave([_n8(str(timestamp), -2), _i8(normalized), _i8(nonce)]).encode()).hexdigest()
     return _n8(digest[:5], -4) + "%02d" % (sum(_mix([ord(x) for x in digest[-6:]])) % 100)
 
-def load_session(profile: Path | None = None):
-    profile = profile or Path.home() / "AppData/Roaming/heybox-pc-launcher"
+def _decrypt_user_pkey(value: str) -> str:
+    """Decrypt the desktop config's ``iv:ciphertext`` AES-256-CBC value.
+
+    Older Chromium cookie databases contain the already decrypted pkey, so this
+    helper deliberately returns ordinary values unchanged and only attempts
+    crypto for the new config format.
+    """
+    if not isinstance(value, str) or ":" not in value:
+        return value
+    iv_hex, ciphertext_hex = value.split(":", 1)
+    try:
+        iv = bytes.fromhex(iv_hex)
+        ciphertext = bytes.fromhex(ciphertext_hex)
+        if len(iv) != 16 or not ciphertext or len(ciphertext) % 16:
+            return value
+    except ValueError:
+        return value
+    try:
+        from Crypto.Cipher import AES
+        plaintext = AES.new(_CONFIG_AES_KEY, AES.MODE_CBC, iv).decrypt(ciphertext)
+    except ImportError:
+        try:
+            from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+            decryptor = Cipher(algorithms.AES(_CONFIG_AES_KEY), modes.CBC(iv)).decryptor()
+            plaintext = decryptor.update(ciphertext) + decryptor.finalize()
+        except ImportError as exc:
+            raise FuploadError(
+                "AES support is required to read the Heybox desktop session",
+                kind="environment_error",
+                details={"install": "Crypto or cryptography"},
+            ) from exc
+    if not plaintext:
+        return value
+    pad = plaintext[-1]
+    if not 1 <= pad <= 16 or plaintext[-pad:] != bytes([pad]) * pad:
+        raise FuploadError("Heybox desktop pkey could not be decrypted", kind="authentication_error")
+    try:
+        return plaintext[:-pad].decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise FuploadError("Heybox desktop pkey is invalid", kind="authentication_error") from exc
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_cookie_db(profile: Path) -> dict[str, str]:
     db = profile / "Network/Cookies"
     try:
         with sqlite3.connect("file:%s?mode=ro" % db, uri=True) as con:
             rows = con.execute("select name,value from cookies where host_key like '%xiaoheihe.cn'").fetchall()
-    except (OSError, sqlite3.Error) as exc:
-        raise FuploadError("Heybox desktop Cookie DB is missing", kind="authentication_error") from exc
-    cookies = {str(k): str(v) for k,v in rows if k in {"user_heybox_id","user_pkey","x_xhh_tokenid"} and v}
-    if not {"user_heybox_id","user_pkey","x_xhh_tokenid"} <= set(cookies):
-        raise FuploadError("Heybox desktop login state is incomplete", kind="authentication_error")
-    identity = {}
+    except (OSError, sqlite3.Error):
+        return {}
+    return {str(k): str(v) for k, v in rows if k in {"user_heybox_id", "user_pkey", "x_xhh_tokenid"} and v}
+
+
+def _read_sentry_identity(profile: Path) -> dict[str, str]:
+    identity: dict[str, str] = {}
     scope = profile / "sentry/scope_v3.json"
     try:
-        crumbs = json.loads(scope.read_text(encoding="utf-8")).get("scope",{}).get("breadcrumbs",[])
+        crumbs = _read_json(scope).get("scope", {}).get("breadcrumbs", [])
         for crumb in reversed(crumbs):
             raw = crumb.get("data",{}).get("url","")
             if "x_app=heybox_pc" in raw:
                 query = parse_qs(urlparse(raw).query)
-                allowed = {"x_client_type","x_os_type","x_app","version","exe_version","os_version","device_id","channel","heybox_id"}
-                identity = {k:v[-1] for k,v in query.items() if k in allowed and v}; break
+                allowed = {
+                    "app", "client_type", "device_id", "exe_version", "heybox_id",
+                    "os_type", "os_version", "version", "web_version", "x_app",
+                    "x_client_type", "x_client_version", "x_os_type",
+                }
+                identity = {k: v[-1] for k, v in query.items() if k in allowed and v}
+                break
     except (OSError, ValueError, TypeError):
         pass
+    return identity
+
+
+def load_session(profile: Path | None = None):
+    """Load the current desktop session without exposing credential material.
+
+    Heybox 1.14 stores its authoritative session in ``config.json``.  The
+    Chromium database is retained as a compatibility fallback because older
+    installations and upgrade paths may not have written the new config yet.
+    """
+    profile = profile or Path.home() / "AppData/Roaming/heybox-pc-launcher"
+    config = _read_json(profile / "config.json")
+    db_cookies = _load_cookie_db(profile)
+    cookies: dict[str, str] = dict(db_cookies)
+    config_cookies = config.get("cookies")
+    if isinstance(config_cookies, list):
+        for item in config_cookies:
+            if not isinstance(item, dict):
+                continue
+            name, value = item.get("name"), item.get("value")
+            if isinstance(name, str) and isinstance(value, str) and value:
+                if name in {"user_heybox_id", "user_pkey", "x_xhh_tokenid"}:
+                    cookies[name] = value
+    acc_config = config.get("acc_config")
+    if isinstance(acc_config, dict) and acc_config.get("xhh_token_id"):
+        cookies["x_xhh_tokenid"] = str(acc_config["xhh_token_id"])
+    if cookies.get("user_pkey"):
+        cookies["user_pkey"] = _decrypt_user_pkey(cookies["user_pkey"])
+    account = config.get("account") if isinstance(config.get("account"), dict) else {}
+    if not cookies.get("user_heybox_id") and account.get("heybox_id"):
+        cookies["user_heybox_id"] = str(account["heybox_id"])
+    if not {"user_heybox_id", "user_pkey", "x_xhh_tokenid"} <= set(cookies):
+        raise FuploadError("Heybox desktop login state is incomplete", kind="authentication_error")
+
+    identity = _read_sentry_identity(profile)
+    version = identity.get("version") or CLIENT_VERSION
+    identity = {
+        "x_client_type": "pc",
+        "x_os_type": "Windows",
+        "x_app": "heybox_pc",
+        "version": version,
+        "exe_version": identity.get("exe_version") or version,
+        "os_version": identity.get("os_version") or platform.platform(aliased=True),
+        **identity,
+    }
+    identity["version"] = version
+    identity["exe_version"] = identity.get("exe_version") or version
+    identity["heybox_id"] = cookies["user_heybox_id"]
     return cookies, identity

package/npm/bin/fupload.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { ensureCurseForgeEnv } from "../lib/curseforge-config.mjs";
 import { recordManagedSkill } from "../lib/managed-install.mjs";
 import { parseLauncherOptions, resolveSkillDirectory } from "../lib/options.mjs";
-import { discoverPython, runPython } from "../lib/python.mjs";
+import { ensurePythonRuntime, runPython } from "../lib/python.mjs";
 import { ensureSkill } from "../lib/skill-installer.mjs";
 import { uninstallSelf } from "../lib/uninstall.mjs";
 import { updateSelf } from "../lib/update.mjs";
@@ -65,16 +65,18 @@ async function main() {
     return 0;
   }
 
-  const python = discoverPython();
-  if (!python) {
+  let runtime;
+  try {
+    runtime = ensurePythonRuntime({ packageRoot });
+  } catch (error) {
     emitError(
-      "PYTHON_VERSION_UNSUPPORTED",
-      "Fuploader requires Python >=3.9,<4.0. Install Python and run the command again.",
+      "PYTHON_RUNTIME_SETUP_FAILED",
+      error.message,
     );
     return 1;
   }
   const script = path.join(target, "scripts", "fupload.py");
-  const result = runPython(python, script, options.forwarded);
+  const result = runPython(runtime.python, script, options.forwarded);
   if (result.error) {
     emitError("PYTHON_LAUNCH_FAILED", result.error.message);
     return 1;

package/npm/lib/managed-install.mjs

@@ -6,11 +6,15 @@ export const MANAGED_INSTALL_SCHEMA = "fupload.npm-managed-install.v1";
 export const MANAGED_INSTALL_FILE = "managed-install.json";
 const PACKAGE_NAME = "@follenfang/fupload";
 
-function stateRoot({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+export function productStateRoot({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
   if (platform === "win32") {
-    return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "Fupload", "npm");
+    return path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "Fupload");
   }
-  return path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "fupload", "npm");
+  return path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "fupload");
+}
+
+function stateRoot(options = {}) {
+  return path.join(productStateRoot(options), "npm");
 }
 
 function atomicWriteJson(filename, value) {

package/npm/lib/python-requirements.txt

@@ -0,0 +1 @@
+cos-python-sdk-v5==1.9.44

package/npm/lib/python.mjs

@@ -1,4 +1,16 @@
 import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { productStateRoot } from "./managed-install.mjs";
+
+export const PYTHON_RUNTIME_SCHEMA = "fupload.python-runtime.v1";
+const RUNTIME_DIRECTORY = "python";
+const RUNTIME_MARKER = "runtime.json";
+const RUNTIME_LOCK_WAIT_MS = 5 * 60 * 1000;
+const RUNTIME_LOCK_STALE_MS = 15 * 60 * 1000;
 
 function probe(command, args, minimum) {
   const result = spawnSync(command, [...args, "-c", "import sys; print('.'.join(map(str, sys.version_info[:3])))"], {
@@ -43,3 +55,218 @@ export function runPython(python, script, args, options = {}) {
     windowsHide: true,
   });
 }
+
+export function pythonRequirementsFile(packageRoot) {
+  return path.join(packageRoot, "npm", "lib", "python-requirements.txt");
+}
+
+export function pythonRuntimeRoot(options = {}) {
+  return path.join(productStateRoot(options), RUNTIME_DIRECTORY);
+}
+
+export function pythonRuntimeExecutable(root, platform = process.platform) {
+  return platform === "win32"
+    ? path.join(root, "Scripts", "python.exe")
+    : path.join(root, "bin", "python");
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function readMarker(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, RUNTIME_MARKER), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function probeRuntime(executable, run = spawnSync) {
+  if (!fs.existsSync(executable)) {
+    return null;
+  }
+  const result = run(executable, [
+    "-c",
+    "import importlib.metadata,sys; import qcloud_cos; print('.'.join(map(str,sys.version_info[:3]))); print(importlib.metadata.version('cos-python-sdk-v5'))",
+  ], { encoding: "utf8", shell: false, windowsHide: true });
+  if (result.status !== 0) {
+    return null;
+  }
+  const [pythonVersion, dependencyVersion] = result.stdout.trim().split(/\r?\n/);
+  const match = pythonVersion?.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match || !dependencyVersion) {
+    return null;
+  }
+  return { version: match.slice(1).map(Number), dependencyVersion };
+}
+
+function inspectRuntime({ root, platform, requirementsHash, run }) {
+  const marker = readMarker(root);
+  if (marker?.schema !== PYTHON_RUNTIME_SCHEMA || marker.requirements_sha256 !== requirementsHash) {
+    return null;
+  }
+  const command = pythonRuntimeExecutable(root, platform);
+  const probe = probeRuntime(command, run);
+  if (!probe || probe.version[0] !== 3 || probe.version[1] < 9) {
+    return null;
+  }
+  return { command, args: [], version: probe.version, dependencyVersion: probe.dependencyVersion };
+}
+
+function bounded(value) {
+  return String(value || "").trim().slice(0, 4000);
+}
+
+function runChecked(run, command, args, message) {
+  const result = run(command, args, {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    const detail = bounded(result.stderr || result.stdout || result.error?.message);
+    throw new Error(`${message}${detail ? `: ${detail}` : ""}`);
+  }
+  return result;
+}
+
+function writeMarker(root, value) {
+  fs.writeFileSync(path.join(root, RUNTIME_MARKER), `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function acquireRuntimeLock(root) {
+  const lock = `${root}.lock`;
+  fs.mkdirSync(path.dirname(root), { recursive: true });
+  const deadline = Date.now() + RUNTIME_LOCK_WAIT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const descriptor = fs.openSync(lock, "wx", 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify({ pid: process.pid })}\n`);
+      return {
+        release() {
+          fs.closeSync(descriptor);
+          fs.rmSync(lock, { force: true });
+        },
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > RUNTIME_LOCK_STALE_MS) {
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      } catch (statError) {
+        if (statError.code !== "ENOENT") {
+          throw statError;
+        }
+      }
+      sleepSync(50);
+    }
+  }
+  throw new Error(`Timed out waiting for the Fuploader Python runtime lock: ${lock}`);
+}
+
+export function ensurePythonRuntime({
+  packageRoot,
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  run = spawnSync,
+  discover = discoverPython,
+} = {}) {
+  const requirements = pythonRequirementsFile(packageRoot);
+  const content = fs.readFileSync(requirements);
+  const requirementsHash = sha256(content);
+  const root = pythonRuntimeRoot({ platform, env, home });
+  const parent = path.dirname(root);
+  const lock = acquireRuntimeLock(root);
+  try {
+    const current = inspectRuntime({ root, platform, requirementsHash, run });
+    if (current) {
+      return { status: "current", root, requirements, python: current };
+    }
+
+    const base = discover({ platform });
+    if (!base) {
+      throw new Error("Fuploader requires Python >=3.9,<4.0 to create its managed runtime.");
+    }
+    const nonce = `${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
+    const staging = path.join(parent, `.python-stage-${nonce}`);
+    const backup = path.join(parent, `.python-backup-${nonce}`);
+    fs.mkdirSync(parent, { recursive: true });
+    let movedOld = false;
+    try {
+      runChecked(run, base.command, [...base.args, "-m", "venv", staging], "Could not create the Fuploader Python runtime");
+      const stagingPython = pythonRuntimeExecutable(staging, platform);
+      runChecked(run, stagingPython, [
+        "-m", "pip", "install", "--disable-pip-version-check", "--no-input", "--requirement", requirements,
+      ], "Could not install Fuploader Python dependencies");
+      const installed = probeRuntime(stagingPython, run);
+      if (!installed) {
+        throw new Error("The Fuploader Python runtime did not pass its dependency probe.");
+      }
+      writeMarker(staging, {
+        schema: PYTHON_RUNTIME_SCHEMA,
+        requirements_sha256: requirementsHash,
+        python_version: installed.version.join("."),
+        dependency_version: installed.dependencyVersion,
+      });
+      if (fs.existsSync(root)) {
+        fs.renameSync(root, backup);
+        movedOld = true;
+      }
+      try {
+        fs.renameSync(staging, root);
+      } catch (error) {
+        if (movedOld && !fs.existsSync(root)) {
+          fs.renameSync(backup, root);
+          movedOld = false;
+        }
+        throw error;
+      }
+      if (movedOld) {
+        fs.rmSync(backup, { recursive: true, force: true });
+      }
+    } finally {
+      fs.rmSync(staging, { recursive: true, force: true });
+    }
+    const created = inspectRuntime({ root, platform, requirementsHash, run });
+    if (!created) {
+      throw new Error("The installed Fuploader Python runtime failed final validation.");
+    }
+    return { status: "installed", root, requirements, python: created };
+  } finally {
+    lock.release();
+  }
+}
+
+export function removePythonRuntime({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  const productRoot = productStateRoot({ platform, env, home });
+  const root = pythonRuntimeRoot({ platform, env, home });
+  const lock = acquireRuntimeLock(root);
+  try {
+    fs.rmSync(root, { recursive: true, force: true });
+  } finally {
+    lock.release();
+  }
+  try {
+    if (fs.readdirSync(productRoot).length === 0) {
+      fs.rmdirSync(productRoot);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT" && error.code !== "ENOTEMPTY") {
+      throw error;
+    }
+  }
+  return { root, status: "removed" };
+}

package/npm/lib/uninstall.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 
 import { clearManagedInstall, readManagedInstall } from "./managed-install.mjs";
 import { resolveSkillDirectory } from "./options.mjs";
+import { removePythonRuntime } from "./python.mjs";
 import { INSTALL_STAMP, INSTALL_STAMP_SCHEMA, readInstallStamp } from "./skill-installer.mjs";
 
 export const PACKAGE_NAME = "@follenfang/fupload";
@@ -173,6 +174,7 @@ export async function uninstallSelf({
   env = process.env,
   home = os.homedir(),
   runNpm = runNpmCli,
+  removeRuntime = removePythonRuntime,
 } = {}) {
   const installation = resolveGlobalInstall(packageRoot, platform);
   const cleanup = await cleanupManagedSkills({
@@ -181,6 +183,15 @@ export async function uninstallSelf({
     home,
     extraTargets: target ? [target] : [],
   });
+  let runtime;
+  try {
+    runtime = removeRuntime({ platform, env, home });
+  } catch (error) {
+    throw new ManagedUninstallError("The managed Fuploader Python runtime could not be removed.", {
+      cleanup,
+      reason: error.message,
+    });
+  }
   const args = ["uninstall", "-g", "--ignore-scripts", "--prefix", installation.prefix, PACKAGE_NAME];
   const npmResult = runNpm(args, { platform, env });
   if (npmResult.error || npmResult.status !== 0) {
@@ -206,6 +217,7 @@ export async function uninstallSelf({
     package: PACKAGE_NAME,
     prefix: installation.prefix,
     cleanup,
+    python_runtime: runtime,
     npm_exit_status: npmResult.status,
   };
 }

package/npm/lib/update.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { ensureCurseForgeEnv } from "./curseforge-config.mjs";
 import { readManagedInstall, recordManagedSkill } from "./managed-install.mjs";
 import { resolveSkillDirectory } from "./options.mjs";
+import { ensurePythonRuntime } from "./python.mjs";
 import { ensureSkill, loadDistribution } from "./skill-installer.mjs";
 import { PACKAGE_NAME, inspectManagedSkill, resolveGlobalInstall, runNpmCli } from "./uninstall.mjs";
 
@@ -27,6 +28,7 @@ export async function updateSelf({
   env = process.env,
   home = os.homedir(),
   runNpm = runNpmCli,
+  ensureRuntime = ensurePythonRuntime,
 } = {}) {
   const curseforgeConfig = ensureCurseForgeEnv({ home, platform });
   const installation = resolveGlobalInstall(packageRoot, platform);
@@ -57,6 +59,16 @@ export async function updateSelf({
       reason: error.message,
     });
   }
+  let runtime;
+  try {
+    runtime = ensureRuntime({ packageRoot, platform, env, home });
+  } catch (error) {
+    throw new ManagedUpdateError("The npm CLI updated but its Python runtime could not be synchronized.", {
+      from_version: current.packageRecord.version,
+      to_version: updated.packageRecord.version,
+      reason: error.message,
+    });
+  }
   const registry = readManagedInstall({ platform, env, home });
   const targets = [
     ...new Set([
@@ -97,6 +109,7 @@ export async function updateSelf({
     to_version: updated.packageRecord.version,
     npm_exit_status: npmResult.status,
     curseforge_config: curseforgeConfig,
+    python_runtime: { status: runtime.status, root: runtime.root },
     skills,
   };
 }

package/npm/postinstall.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { ensureCurseForgeEnv } from "./lib/curseforge-config.mjs";
 import { recordManagedSkill } from "./lib/managed-install.mjs";
 import { resolveSkillDirectory } from "./lib/options.mjs";
+import { ensurePythonRuntime } from "./lib/python.mjs";
 import { ensureSkill } from "./lib/skill-installer.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -11,11 +12,13 @@ const target = resolveSkillDirectory();
 
 try {
   const config = ensureCurseForgeEnv();
+  const runtime = ensurePythonRuntime({ packageRoot });
   const result = await ensureSkill({ packageRoot, target });
   recordManagedSkill(target);
   process.stdout.write(`Fuploader Skill ${result.status}: ${target}\n`);
   process.stdout.write(`CurseForge configuration ${config.status}: ${config.path}\n`);
+  process.stdout.write(`Python runtime ${runtime.status}: ${runtime.root}\n`);
 } catch (error) {
-  process.stderr.write(`Fuploader Skill installation failed: ${error.message}\n`);
+  process.stderr.write(`Fuploader installation failed: ${error.message}\n`);
   process.exitCode = 1;
 }

package/npm/skill-manifest.json

@@ -1,9 +1,9 @@
 {
   "schema": "fupload.npm-skill-manifest.v1",
   "package_name": "@follenfang/fupload",
-  "package_version": "0.0.4",
-  "skill_version": "0.0.4",
-  "tree_sha256": "657cba2688d07435efd1b5d4ae36b9db58704918dd870b468d9e5ef74c15adc4",
+  "package_version": "0.0.6",
+  "skill_version": "0.0.6",
+  "tree_sha256": "89170e9d93a44d9aa72a1c041f93d941609eb9d762375358090c5a96129405d9",
   "files": [
     {
       "path": "agents/openai.yaml",
@@ -77,8 +77,8 @@
     },
     {
       "path": "references/blackbox.md",
-      "bytes": 2244,
-      "sha256": "910bcd8ff334a063a3c2121bbe16d5134e5719eab80835a1d4f6d8a830b27d51"
+      "bytes": 2357,
+      "sha256": "022563a7611a5877761df71074ed347ef51fd27f735da7926cbb96d3b781dcc6"
     },
     {
       "path": "references/curseforge.md",
@@ -108,17 +108,17 @@
     {
       "path": "scripts/fupload_cli/__init__.py",
       "bytes": 49,
-      "sha256": "833580602400dbdb71fb0d388ffbceb1d4a4f6478bd2667b4a564f5004cf1ca6"
+      "sha256": "acf9b050750b58742981c5b9ae836149b89bb86daad01d18dd1948e71817d2c2"
     },
     {
       "path": "scripts/fupload_cli/blackbox_auth.py",
-      "bytes": 2874,
-      "sha256": "e018a33dce4babd1dc739af68c58499412474c7e1f1e3c0640dc53dbe46fce29"
+      "bytes": 7211,
+      "sha256": "797ca228c57d2b845a7105f132891b71d3e494adcdb8f44027ce835125206177"
     },
     {
       "path": "scripts/fupload_cli/blackbox.py",
-      "bytes": 12503,
-      "sha256": "e15ef8a5063c000c6d4569028acdee2d32915d8ac27f3863122e344381d071c6"
+      "bytes": 16666,
+      "sha256": "c6a793cacc7d9ceb8995cac62a076c1944345eaa113bed21068c75a05b1b0ee6"
     },
     {
       "path": "scripts/fupload_cli/cli.py",
@@ -187,8 +187,8 @@
     },
     {
       "path": "SKILL.md",
-      "bytes": 22692,
-      "sha256": "f83b18a43c8013c0ebf7531abca2a0eb34d032a5803c12e154fce84996630142"
+      "bytes": 22890,
+      "sha256": "af700f4e6eb924d955c8e5ae1205934c0bc08b425c85ce5f279eb0c630a0f77a"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@follenfang/fupload",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Install and run the Fuploader Agent Skill and Python CLI.",
   "type": "module",
   "bin": {