@follenfang/fupload 0.0.2 → 0.0.5

package/README.md

@@ -1,12 +1,12 @@
 # Fuploader
 
-Fuploader 是一个面向 Agent 的《魔兽世界》作者发布 Skill 和 CLI。npm 安装后统一使用 `fupload` 命令；命令内部运行随 Skill 分发的纯 Python 实现。新手盒子（NewBeeBox）默认优先使用官方 `ncc` CLI，用户显式要求第三方管理工具时才使用 Fuploader 通道；网易 DD 使用 Fuploader 调用官方无头客户端；CurseForge 使用 Core API 查询作者公开项目，并使用 Authors Upload API 上传插件 ZIP。
+Fuploader 是一个面向 Agent 的《魔兽世界》作者发布 Skill 和 CLI。npm 安装后统一使用 `fupload` 命令；命令内部运行随 Skill 分发的纯 Python 实现。新手盒子（NewBeeBox）默认优先使用官方 `ncc` CLI，用户显式要求第三方管理工具时才使用 Fuploader 通道；网易 DD 使用 Fuploader 调用官方无头客户端；CurseForge 使用 Core API 查询作者公开项目，并使用 Authors Upload API 上传插件 ZIP；Heybox Workshop 复用本机客户端登录态管理插件元数据和版本。
 
 项目强调显式调用、完整字段收集、写入前确认和写入后读回验证。CLI 只负责单次原子读写，业务选择、执行计划和异常恢复由 Agent 在对话中完成。
 
 ## 功能
 
-- 支持新手盒子官方 `ncc`、第三方 Python 管理通道、网易 DD 和 CurseForge。
+- 支持新手盒子官方 `ncc`、第三方 Python 管理通道、网易 DD、CurseForge 和 Heybox Workshop。
 - CurseForge 支持按作者 ID 查询 WoW 公开项目、读取上传用游戏版本，以及向已有项目上传插件 ZIP；不创建 Project，也不枚举私有、草稿或待审 Project。
 - 支持插件、配置分享、WA/字符串的创建、内容更新与元数据编辑。
 - 官方通道严格采用已安装 `ncc` 暴露的能力；第三方 Python 通道覆盖版本、游戏分支、分类、媒体、可见性、审核、商业设置、频道、关联内容和配置备份选择等页面字段。
@@ -40,6 +40,9 @@ fupload/
 - 新手盒子官方通道：Windows、macOS 或 Linux，Node.js >= 18、官方 `ncc` CLI 与本机登录态
 - 新手盒子第三方 Python 通道：Windows、Python 3、已安装并登录新手盒子桌面客户端
 - 网易 DD：Windows、Python 3、已安装并登录官方客户端
+- Heybox Workshop：Windows、Python 3、已安装并登录 Heybox 桌面客户端
+
+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。
 
@@ -73,7 +76,7 @@ CURSEFORGE_UPLOAD_TOKEN=
 $fupload
 ```
 
-该 Skill 不会因普通提及“发布”“新手盒子”“DD”或“CurseForge”而自动触发。Agent 会先询问平台、资源和动作。新手盒子会自动检测 `ncc`：已安装即默认使用官方通道；未安装时先询问是否安装；只有用户显式选择第三方 Python 管理工具才进入项目内 CLI。CurseForge 上传缺少作者 ID 时，Agent 会主动询问；缺少 API Key 或 Upload Token 时，只会引导用户在本机填写 `~/.fupload/curseforge.env`，不会要求在对话中提供秘密。Agent 在被发布项目中创建 `publish/<时间>-<平台>-<资源>-<动作>/`，同一次发布的脱敏 JSON 按原子步骤保存为 `01-<动作>.json`、`02-<动作>.json`。展示完整写入计划并得到确认后才会真实写入。
+该 Skill 不会因普通提及“发布”“新手盒子”“DD”“CurseForge”或“Heybox”而自动触发。Agent 会先询问平台、资源和动作。新手盒子会自动检测 `ncc`：已安装即默认使用官方通道；未安装时先询问是否安装；只有用户显式选择第三方 Python 管理工具才进入项目内 CLI。CurseForge 上传缺少作者 ID 时，Agent 会主动询问；缺少 API Key 或 Upload Token 时，只会引导用户在本机填写 `~/.fupload/curseforge.env`，不会要求在对话中提供秘密。Heybox 命令复用桌面客户端登录态，支持模块元数据和版本增删改，不支持整体删除模块。Agent 在被发布项目中创建 `publish/<时间>-<平台>-<资源>-<动作>/`，同一次发布的脱敏 JSON 按原子步骤保存为 `01-<动作>.json`、`02-<动作>.json`。展示完整写入计划并得到确认后才会真实写入。
 
 ## CLI 使用
 
@@ -88,7 +91,7 @@ ncc whoami -o json
 
 创建令牌和本机登录说明见[官方 CLI 文档](https://creator.newbeebox.com/cli-docs)。不要把令牌粘贴到 Agent 对话；在自己的终端完成 `ncc login`。
 
-以下为 Fuploader 第三方 NewBeeBox、DD 与 CurseForge 执行层。
+以下为 Fuploader 第三方 NewBeeBox、DD、CurseForge 与 Heybox Workshop 执行层。
 
 查看总帮助：
 
@@ -117,6 +120,9 @@ fupload curseforge plugin upload --input publish\20260807-120000-curseforge-plug
 ```powershell
 fupload newbee plugin create --help
 fupload dd config update --help
+fupload blackbox plugin edit --help
+fupload blackbox plugin update --help
+fupload blackbox plugin version-delete --help
 ```
 
 检查桌面登录与安装状态：
@@ -124,6 +130,8 @@ fupload dd config update --help
 ```powershell
 fupload newbee session doctor
 fupload dd session doctor
+fupload blackbox plugin list
+fupload blackbox plugin get --module-id 101149612
 ```
 
 DD doctor 不会登录。若输出 `gui_running=true`，需先取得用户同意，随后关闭已验证的官方 GUI 并建立一个任务会话：
@@ -161,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；它不属于完整卸载流程。
 
@@ -182,6 +190,7 @@ npm 7 及以上不执行卸载 lifecycle，因此直接运行 `npm uninstall -g
 - [新手盒子第三方 Python 字段参考](fupload/references/newbee.md)
 - [网易 DD 字段参考](fupload/references/dd.md)
 - [CurseForge API、字段与上传参考](fupload/references/curseforge.md)
+- [Heybox Workshop 黑盒字段与版本参考](fupload/references/blackbox.md)
 
 ## 测试
 

package/fupload/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: fupload
-description: Explicit author-publishing workflow for World of Warcraft plugins, configuration shares, and WA/strings on NewBeeBox, NetEase DD, and CurseForge, including CurseForge author project lookup and plugin ZIP upload. 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, plugins, configurations, or WA.
+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.2"
+  version: "0.0.5"
 ---
 
 # Fupload
 
-Act as the publishing operator. For NewBeeBox, prefer the official `ncc` CLI whenever it is installed unless the user explicitly requests the third-party Python management tool. For DD, CurseForge, and an explicitly selected third-party NewBeeBox workflow, use the bundled Python CLI. Keep investigation, choices, planning, confirmation, and recovery in the conversation.
+Act as the publishing operator. For NewBeeBox, prefer the official `ncc` CLI whenever it is installed unless the user explicitly requests the third-party Python management tool. For DD, CurseForge, Heybox Workshop, and an explicitly selected third-party NewBeeBox workflow, use the bundled Python CLI. Keep investigation, choices, planning, confirmation, and recovery in the conversation.
 
 When installed from npm, interpret `<fupload-cli>` as `fupload`. Only while maintaining the source repository, directly installing this Skill, or when `fupload` is absent from PATH, use `python <skill-root>/scripts/fupload.py`. Keep the user's current project as the working directory in either mode.
 
@@ -15,7 +15,7 @@ When installed from npm, interpret `<fupload-cli>` as `fupload`. Only while main
 
 When the user has not already stated both dimensions, ask in one short message:
 
-1. Platform: NewBeeBox, DD, or CurseForge.
+1. Platform: NewBeeBox, DD, CurseForge, or Heybox Workshop.
 2. Resource and action: plugin/configuration/WA, then create/content update/metadata edit/delete. CurseForge supports public project listing and uploading a plugin ZIP to an existing project only.
 
 Map natural language consistently:
@@ -25,7 +25,7 @@ Map natural language consistently:
 - `edit`: change fields allowed by the target platform's action allowlist. For DD plugins, this is existing-record commercial, association, room/channel, and creation-statement settings; first-publication metadata, categories, media, and version fields are create/update-only.
 - `delete`: delete one main record only. It never deletes an individual version, media object, or associated record.
 
-Never offer bulk delete, version-file delete, drafts, guides, messages, or GUI control automation. The DD task-session command may close verified official GUI processes only after the consent flow below.
+Never offer bulk delete, drafts, guides, messages, or GUI control automation. Heybox supports individual version deletion with asynchronous readback; whole-module deletion is not supported. The DD task-session command may close verified official GUI processes only after the consent flow below.
 
 CurseForge cannot create a project or enumerate private, draft, or pending-review projects. Direct project creation to the Authors website; use the Core API list only as the public-project view for one numeric author ID.
 
@@ -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
 
@@ -69,6 +69,7 @@ For npm package maintenance, use `fupload update` to update the CLI and every re
 - Read [references/newbee.md](references/newbee.md) only when the user explicitly selected the third-party Python NewBeeBox channel.
 - Read [references/dd.md](references/dd.md) only for DD.
 - Read [references/curseforge.md](references/curseforge.md) for every CurseForge lookup or upload.
+- Read [references/blackbox.md](references/blackbox.md) for Heybox Workshop plugin list/detail, metadata edit, version upload/edit/delete, and client-session authentication.
 - For Python, run the exact leaf command with `--help` before creating its input. Treat help as the executable schema contract.
 
 ## Investigate
@@ -87,6 +88,8 @@ For DD, use the one active task session to read game types/builds and the resour
 
 For every existing DD update or edit, GET the detail first and rebuild the official full form before preparing the write. If a legacy record lacks a field now required by the official submit validator, such as `creation_statement`, stop before upload and collect that value. When the missing field belongs to a different action allowlist, plan and confirm the prerequisite edit first, read it back, then run the content update. Do not send `null`, create defaults, or guessed values to bypass the missing field.
 
+For Heybox Workshop, use the signed-in desktop client's local session automatically. `blackbox plugin list`, `get`, and `versions` are read-only; `plugin edit` preserves omitted module fields by reading the complete module first; `plugin update` and `version-edit` upload or reuse a ZIP URL and verify the version readback; `version-delete` waits for asynchronous soft deletion and retries once when the audit state temporarily returns active. Do not accept or print cookies, tokens, signatures, or temporary COS credentials, and do not delete a whole module.
+
 For DD WA create, collect user choices before generating JSON, then let the Python CLI supply only the official create defaults for omitted form values: seven-day share and purchase lifetimes, `need_buy=false`, category `ui_original`, `Interface/Addons`, empty VIP levels, and version `0`. Submit category IDs as strings even when a discovery response represents them numerically. WA create/update versions contain digits only; update must be numerically greater than the current remote value. Every `!WA:2!` create/update/edit is reparsed by the installed official `WowUIInterface.parseWa` chain, including unchanged edit content. Do not carry create defaults into WA update/edit; omitted existing fields preserve their remote value.
 
 For official NewBeeBox, use only `ncc whoami -o json` to verify authentication; do not inspect its credential files. For third-party Python NewBeeBox, run `newbee session doctor`; credentials must come from the Windows Known Folder auth-store and all authenticated requests must use fixed official HTTPS origins. For DD, run `dd session doctor`; discovery must accept only an Authenticode-valid executable from an allowed official NetEase publisher. Doctor is local-only and must not start a native login. Do not set endpoint, credential-directory, or DD executable-path environment overrides.

package/fupload/references/blackbox.md

@@ -0,0 +1,37 @@
+# Heybox Workshop
+
+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.
+
+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`
+
+Edits existing module metadata and verifies the module detail readback. Input schema: `fupload.v1.blackbox.plugin.edit`.
+
+Fields: `id`, `name`, `logo_url`, `category_ids`, `type`, `desc`, `official`, `official_url`, `core_folders`.
+
+`id` is required. Omitted metadata fields preserve their current remote values. `category_ids` contains positive category IDs; `core_folders` is an array in the input and is sent as the platform's comma-separated value.
+
+## `blackbox plugin update`
+
+Uploads a local ZIP and creates one new plugin version. Input schema: `fupload.v1.blackbox.plugin.update`.
+
+Fields: `module_id`, `name`, `type`, `game_versions`, `file`, `file_url`.
+
+`module_id`, `name`, `type`, `game_versions`, and `file` are required. The provider uploads the ZIP through the official COS token flow, sends the server-normalized URL to the version upsert endpoint, and verifies `name`, `type`, `gameVersions`, and non-empty `fileUrlHeybox`.
+
+## `blackbox plugin version-edit`
+
+Edits one existing version. Input schema: `fupload.v1.blackbox.version.edit`.
+
+Fields: `version_id`, `module_id`, `name`, `type`, `game_versions`, `file`, `file_url`.
+
+`version_id`, `module_id`, `name`, `type`, and `game_versions` are required. Provide `file` to upload a replacement ZIP or `file_url` to reuse an already uploaded package; when both are omitted, the current server file URL is preserved.
+
+## `blackbox plugin version-delete`
+
+Soft-deletes one version and verifies `auditState=4` or absence after the platform's asynchronous processing. Input schema: `fupload.v1.blackbox.version.delete`.
+
+Fields: `version_id`, `module_id`.
+
+The provider may retry once when the platform temporarily returns a deleted version to an active audit state. Deleting the entire plugin module is not supported by the current client/web contract and is outside this command.

package/fupload/scripts/fupload_cli/__init__.py

@@ -1,3 +1,3 @@
 """Fupload Python CLI."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.5"

package/fupload/scripts/fupload_cli/blackbox.py

@@ -0,0 +1,151 @@
+"""Heybox Workshop plugin provider."""
+from __future__ import annotations
+import hashlib, json, secrets, time
+from pathlib import Path
+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
+
+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):
+        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
+        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
+        if not isinstance(result,dict) or result.get("status")!="ok": raise FuploadError("Workshop API rejected request", endpoint=path, details={"status":result.get("status") if isinstance(result,dict) else None})
+        return result
+    @staticmethod
+    def _result(payload): return payload.get("result") or {}
+    def execute_read(self, resource: str, action: str, args: Any):
+        if resource == "plugin" and action in ("list", "get", "versions"):
+            if action == "list": return self.plugin_list()
+            module_id = getattr(args,"module_id",None) if not isinstance(args,Mapping) else args.get("module_id")
+            result = self.plugin_get(int(module_id))
+            return result["versions"] if action == "versions" else result
+        raise ValidationError("unsupported blackbox read operation")
+    def execute_write(self, resource: str, action: str, doc: Mapping[str,Any]):
+        if doc.get("dry_run"): return {"dry_run":True,"operation":f"{resource}.{action}","fields":sorted(k for k in doc if k not in {"dry_run","schema"})}
+        if resource == "plugin" and action == "edit": return self.module_edit(doc)
+        if resource == "plugin" and action == "update": return self.version_upsert(doc)
+        if resource=="version" and action in ("create","update","edit"): return self.version_upsert(doc)
+        if resource=="version" and action=="delete": return self.version_delete(doc)
+        raise ValidationError("unsupported blackbox write operation")
+    def plugin_list(self):
+        rows=self._result(self._request("GET","/wow/open_platform/module/list/")).get("moduleList") or []
+        return {"total_count":len(rows),"plugins":[self._redact(x) for x in rows if isinstance(x,dict)]}
+    def plugin_get(self,module_id:int):
+        detail=self._result(self._request("GET","/wow/open_platform/module/detail/",query={"moduleId":module_id}))
+        versions=self._result(self._request("GET","/wow/open_platform/module_version/list/",query={"moduleId":module_id,"offset":0,"limit":100}))
+        return {"module":self._redact(detail.get("module") or detail),"versions":[self._redact(x) for x in (versions.get("versionList") or [])]}
+    def module_edit(self,doc):
+        aliases={"module_id":"id","logo_url":"logoUrl","category_ids":"categoryIds","official_url":"officialUrl","core_folders":"coreFolders"}
+        normalized={aliases.get(k,k):v for k,v in doc.items() if k not in {"schema","dry_run"}}
+        if "id" not in normalized: raise ValidationError("id is required",path="$.id")
+        module_id = int(normalized["id"])
+        current = self.plugin_get(module_id)["module"]
+        # The web client sends a complete module object; preserve omitted fields.
+        defaults = {"name":"", "logoUrl":"", "id":module_id, "categoryIds":[],
+                    "type":1, "desc":"", "official":"", "officialUrl":"", "coreFolders":""}
+        fields={key: normalized.get(key, current.get(key, defaults[key]))
+                for key in ("name","logoUrl","id","categoryIds","type","desc","official","officialUrl","coreFolders")}
+        fields["id"] = module_id
+        if isinstance(fields.get("coreFolders"),list): fields["coreFolders"]=",".join(map(str,fields["coreFolders"]))
+        response=self._request("POST","/wow/open_platform/module/update/",body=fields)
+        actual=self.plugin_get(module_id)["module"]
+        mismatches=[]
+        for key,wanted in ((aliases.get(key,key), value) for key,value in normalized.items() if key in aliases or key in fields):
+            observed=actual.get(key)
+            if key=="coreFolders" and isinstance(observed,list): wanted=[x for x in str(wanted).split(",") if x]
+            if observed != wanted: mismatches.append(key)
+        if mismatches: raise FuploadError("module update readback mismatch",kind="verification_required",verification_required=True,details={"fields":mismatches})
+        return {"accepted":True,"verified":True,"module_id":module_id,"response":self._redact(response)}
+    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"}}
+        if "file" in normalized and "fileUrl" not in normalized:
+            normalized["fileUrl"]=self.upload_zip(int(normalized["moduleId"]),str(normalized["file"]))["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"):
+                normalized["fileUrl"] = existing["fileUrlHeybox"]
+        required=("moduleId","name","type","gameVersions","fileUrl")
+        missing=[k for k in required if k not in normalized]
+        if missing: raise ValidationError("missing field(s): %s"%", ".join(missing))
+        games=normalized["gameVersions"] if isinstance(normalized["gameVersions"],list) else [x for x in str(normalized["gameVersions"]).split(",") if x]
+        body={"moduleId":int(normalized["moduleId"]),"name":normalized["name"],"type":int(normalized["type"]),"gameVersions":",".join(map(str,games)),"fileUrl":normalized["fileUrl"]}
+        if "versionId" in normalized: body["versionId"]=int(normalized["versionId"])
+        response=self._request("POST","/wow/open_platform/module_version/upsert/",body=body)
+        found=self._wait_version(body["moduleId"],body.get("versionId"),body["name"],
+                                 expected={"name":body["name"],"type":body["type"],"gameVersions":list(map(str,games))})
+        mismatches=[key for key,wanted in {"name":body["name"],"type":body["type"],"gameVersions":list(map(str,games))}.items() if found.get(key)!=wanted]
+        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)}
+    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")
+        response=self._request("POST","/wow/open_platform/module_version/delete/",body={"versionId":int(version_id),"moduleId":int(module_id)})
+        found=self._wait_version(int(module_id),int(version_id),None,deleted=True)
+        retry = False
+        settle = float(self.config.get("delete_settle_seconds", 10))
+        if settle:
+            time.sleep(settle)
+            current = self._find_version(int(module_id), int(version_id))
+            if current is not None and current.get("auditState") != 4:
+                retry = True
+                response = self._request("POST","/wow/open_platform/module_version/delete/",body={"versionId":int(version_id),"moduleId":int(module_id)})
+                found = self._wait_version(int(module_id),int(version_id),None,deleted=True)
+        return {"accepted":True,"verified":True,"module_id":int(module_id),"version_id":int(version_id),"audit_state":found.get("auditState") if found else None,"retry":retry,"response":self._redact(response)}
+    def _version_rows(self,module_id):
+        return self._result(self._request("GET","/wow/open_platform/module_version/list/",query={"moduleId":module_id,"offset":0,"limit":100})).get("versionList") or []
+
+    def _find_version(self, module_id, version_id):
+        return next((x for x in self._version_rows(module_id) if x.get("id") == version_id), None)
+    def _wait_version(self,module_id,version_id,name,deleted=False,expected=None):
+        for attempt in range(int(self.config.get("verify_attempts",20))):
+            rows=self._version_rows(module_id)
+            found=next((x for x in rows if (version_id is not None and x.get("id")==version_id) or (version_id is None and x.get("name")==name)),None)
+            matches_expected = found and all(
+                (list(map(str, found.get(key) or [])) if key == "gameVersions" else found.get(key)) == wanted
+                for key, wanted in (expected or {}).items()
+            )
+            if (deleted and (found is None or found.get("auditState")==4)) or (not deleted and found and matches_expected): return found or {}
+            if attempt+1<int(self.config.get("verify_attempts",20)): time.sleep(float(self.config.get("verify_interval",2)))
+        raise FuploadError("version write was not confirmed by readback",kind="verification_required",verification_required=True)
+    @staticmethod
+    def _redact(value):
+        if isinstance(value,dict): return {k:("<redacted>" if any(s in k.lower() for s in ("token","secret","cookie","nonce","hkey")) else Blackbox._redact(v)) for k,v in value.items()}
+        if isinstance(value,list): return [Blackbox._redact(v) for v in value]
+        return value
+
+    def upload_zip(self, module_id: int, file_path: str, *, dry_run=False):
+        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()}
+        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"])
+        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=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()}

package/fupload/scripts/fupload_cli/blackbox_auth.py

@@ -0,0 +1,54 @@
+"""Authentication helpers for the Heybox desktop Workshop client."""
+from __future__ import annotations
+import hashlib, json, secrets, sqlite3, time
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+from .errors import FuploadError
+
+API_BASE = "https://workshopapi.xiaoheihe.cn"
+_ALPHABET = "AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89"
+
+def _n8(value: str, limit: int) -> str:
+    table = _ALPHABET[:limit]
+    return "".join(table[ord(ch) % len(table)] for ch in value)
+def _i8(value: str) -> str:
+    return "".join(_ALPHABET[ord(ch) % len(_ALPHABET)] for ch in value)
+def _interleave(parts):
+    return "".join(part[i] for i in range(max(map(len, parts))) for part in parts if i < len(part))
+def _mix(values):
+    def p(x): return ((x << 1) ^ 27) & 255 if x & 128 else (x << 1) & 255
+    def hm(x): return p(x) ^ x
+    def qg(x): return hm(p(x))
+    def dx(x): return qg(hm(p(x)))
+    def mw(x): return dx(x) ^ qg(x) ^ hm(x)
+    a,b,c,d,*rest=values
+    return [mw(a)^dx(b)^qg(c)^hm(d), hm(a)^mw(b)^dx(c)^qg(d), qg(a)^hm(b)^mw(c)^dx(d), dx(a)^qg(b)^hm(c)^mw(d), *rest]
+def hkey(path: str, timestamp: int, nonce: str) -> str:
+    normalized = "/" + "/".join(x for x in path.split("/") if x) + "/"
+    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"
+    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 = {}
+    scope = profile / "sentry/scope_v3.json"
+    try:
+        crumbs = json.loads(scope.read_text(encoding="utf-8")).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
+    except (OSError, ValueError, TypeError):
+        pass
+    return cookies, identity

package/fupload/scripts/fupload_cli/cli.py

@@ -11,6 +11,7 @@ from typing import Any, Callable, Dict, Optional, Sequence, Tuple
 from . import __version__
 from .dd import DD
 from .curseforge import CurseForge
+from .blackbox import Blackbox
 from .errors import FuploadError, ValidationError
 from .io import read_json, write_error, write_output
 from .newbee import NewBee
@@ -58,9 +59,10 @@ def _list_flags(parser: argparse.ArgumentParser, *, offset: bool = False, game_t
         parser.add_argument("--game-type", type=_positive, required=True, help="DD game type selected from `dd options game-types`.")
 
 
-def _write_leaf(parent: argparse._SubParsersAction, platform: str, resource: str, action: str, summary: str) -> None:
+def _write_leaf(parent: argparse._SubParsersAction, platform: str, resource: str, action: str, summary: str, *, command: Optional[str] = None) -> None:
+    command = command or action
     leaf = parent.add_parser(
-        action, help=summary, description=summary + "\n\n" + WRITE_HELP,
+        command, help=summary, description=summary + "\n\n" + WRITE_HELP,
         epilog=schema_help(platform, resource, action),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -200,6 +202,25 @@ def _curseforge_tree(platforms: argparse._SubParsersAction) -> None:
     _write_leaf(plugin, "curseforge", "plugin", "upload", "Upload one plugin archive to an existing CurseForge project.")
 
 
+def _blackbox_tree(platforms: argparse._SubParsersAction) -> None:
+    root = platforms.add_parser(
+        "blackbox",
+        help="Heybox Workshop plugin management",
+        description="Reuse the signed-in Heybox desktop client login state; no credential input is accepted.",
+    )
+    groups = root.add_subparsers(dest="resource_command", required=True)
+    plugin = groups.add_parser("plugin", help="Heybox Workshop plugin metadata and versions").add_subparsers(dest="action_command", required=True)
+    _read_leaf(plugin, "list", "List plugins managed by the current Heybox Workshop account.", platform="blackbox", resource="plugin", action="list")
+    leaf = _read_leaf(plugin, "get", "Read one Heybox Workshop plugin and its versions.", platform="blackbox", resource="plugin", action="get")
+    leaf.add_argument("--module-id", type=_positive, required=True)
+    leaf = _read_leaf(plugin, "versions", "List versions for one Heybox Workshop plugin.", platform="blackbox", resource="plugin", action="versions")
+    leaf.add_argument("--module-id", type=_positive, required=True)
+    _write_leaf(plugin, "blackbox", "plugin", "edit", "Edit Heybox Workshop plugin metadata and verify the module readback.")
+    _write_leaf(plugin, "blackbox", "plugin", "update", "Upload a ZIP and create a new Heybox Workshop plugin version.")
+    _write_leaf(plugin, "blackbox", "version", "edit", "Edit an existing Heybox Workshop plugin version and verify its readback.", command="version-edit")
+    _write_leaf(plugin, "blackbox", "version", "delete", "Soft-delete one Heybox Workshop plugin version and verify its deleted state.", command="version-delete")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = _parser(
         prog="fupload",
@@ -211,6 +232,7 @@ def build_parser() -> argparse.ArgumentParser:
     _newbee_tree(platforms)
     _dd_tree(platforms)
     _curseforge_tree(platforms)
+    _blackbox_tree(platforms)
     return parser
 
 
@@ -258,14 +280,14 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             if args.dry_run:
                 write_output(platform, operation, _dry_run_data(doc, schema.name), dry_run=True)
                 return 0
-            provider = NewBee() if platform == "newbee" else (DD() if platform == "dd" else CurseForge())
+            provider = NewBee() if platform == "newbee" else (DD() if platform == "dd" else (Blackbox() if platform == "blackbox" else CurseForge()))
             if platform == "dd":
                 data = provider.execute_write(resource, action, doc, getattr(args, "session", None))
             else:
                 data = provider.execute_write(resource, action, doc)
             write_output(platform, operation, data)
             return 0
-        provider = NewBee() if platform == "newbee" else (DD() if platform == "dd" else CurseForge())
+        provider = NewBee() if platform == "newbee" else (DD() if platform == "dd" else (Blackbox() if platform == "blackbox" else CurseForge()))
         if platform == "dd":
             data = provider.execute_read(resource, action, args, getattr(args, "session", None))
         else:

package/fupload/scripts/fupload_cli/schema.py

@@ -552,6 +552,24 @@ register("curseforge", "plugin", "upload", required({
     "is_marked_for_manual_release": f("boolean"),
 }, ("project_id", "file", "changelog", "release_type")))
 
+register("blackbox", "plugin", "edit", required({
+    "id": f("integer"), "name": f("string"), "logo_url": f("string"), "category_ids": f("array"),
+    "type": f("integer", choices=(1, 9)), "desc": f("string"), "official": f("string"),
+    "official_url": f("string"), "core_folders": f("array"),
+}, ("id",)))
+register("blackbox", "plugin", "update", required({
+    "module_id": f("integer"), "name": f("string", nonempty=True), "type": f("integer", choices=(1, 2, 3)),
+    "game_versions": f("array", nonempty=True), "file": f("string", local_file=True), "file_url": f("string"),
+}, ("module_id", "name", "type", "game_versions", "file")))
+register("blackbox", "version", "edit", required({
+    "version_id": f("integer"), "module_id": f("integer"), "name": f("string", nonempty=True),
+    "type": f("integer", choices=(1, 2, 3)), "game_versions": f("array", nonempty=True),
+    "file": f("string", local_file=True), "file_url": f("string"),
+}, ("version_id", "module_id", "name", "type", "game_versions")))
+register("blackbox", "version", "delete", required({
+    "version_id": f("integer"), "module_id": f("integer"),
+}, ("version_id", "module_id")))
+
 
 def get_schema(platform: str, resource: str, action: str) -> Schema:
     try:

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.2",
-  "skill_version": "0.0.2",
-  "tree_sha256": "4ea99f3fb2dee23792450b0d890dcd4520aa8ed827edddf6c6353a8cd753d32e",
+  "package_version": "0.0.5",
+  "skill_version": "0.0.5",
+  "tree_sha256": "0a6d0f91197fbaaff3266c7b78f6f894eb8eac38bdf899581909344393d79afd",
   "files": [
     {
       "path": "agents/openai.yaml",
@@ -75,6 +75,11 @@
       "bytes": 168,
       "sha256": "40491e9aeddc71a4e9578264e5c42b40613e0ea5f0321da29e170b84ff9f1905"
     },
+    {
+      "path": "references/blackbox.md",
+      "bytes": 2357,
+      "sha256": "022563a7611a5877761df71074ed347ef51fd27f735da7926cbb96d3b781dcc6"
+    },
     {
       "path": "references/curseforge.md",
       "bytes": 11917,
@@ -103,12 +108,22 @@
     {
       "path": "scripts/fupload_cli/__init__.py",
       "bytes": 49,
-      "sha256": "72609f840f9864ae70d3ee5226e29dc260e132e06ea4c89b0174b3ba9313d95e"
+      "sha256": "219d361d9b7f13dc9ff7f9eab399b0696fd3de9adcd6ecae755f5724262f12e6"
+    },
+    {
+      "path": "scripts/fupload_cli/blackbox_auth.py",
+      "bytes": 2874,
+      "sha256": "e018a33dce4babd1dc739af68c58499412474c7e1f1e3c0640dc53dbe46fce29"
+    },
+    {
+      "path": "scripts/fupload_cli/blackbox.py",
+      "bytes": 12499,
+      "sha256": "5b46c38f8c5f8a352f261f2c3751b51f16827f62410d2124e0147073e8308350"
     },
     {
       "path": "scripts/fupload_cli/cli.py",
-      "bytes": 23794,
-      "sha256": "3c01585b50e1db308444d094e60751491667ea05a98e5a51f284f098b7a8f376"
+      "bytes": 25664,
+      "sha256": "d1327783aa0e4e27fcc1f71a80cd090f661feaf2e226688b2efa6a36b9645073"
     },
     {
       "path": "scripts/fupload_cli/curseforge.py",
@@ -152,8 +167,8 @@
     },
     {
       "path": "scripts/fupload_cli/schema.py",
-      "bytes": 35113,
-      "sha256": "388c89131bf032428d2ed6c047b52c54adf2fa9d1db91833caefe7a1296acf58"
+      "bytes": 36268,
+      "sha256": "db788d2422c0f6b50ce2795a3df75d5bf1e23934ba4211a64198de06931492a5"
     },
     {
       "path": "scripts/fupload_cli/transport.py",
@@ -172,8 +187,8 @@
     },
     {
       "path": "SKILL.md",
-      "bytes": 21764,
-      "sha256": "ea2019f79aca3a6420aff657fa29b75fd731fc0b3fa4941068e0cfce0921afba"
+      "bytes": 22890,
+      "sha256": "937bbee45d18e8ef257a8071f63951aede681628bb951e40793de81d763f85f3"
     }
   ]
 }

package/package.json

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