zcode-pro 0.16.0__tar.gz → 0.17.0__tar.gz

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zcode-pro
-Version: 0.16.0
+Version: 0.17.0
 Summary: ZCode Pro — ZCode 桌面版界面增强启动器（不修改客户端文件），核心功能：项目自定义别名
 Project-URL: Homepage, https://github.com/duanluan/zcode-pro
 Project-URL: Repository, https://github.com/duanluan/zcode-pro

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/README.en.md

@@ -2,9 +2,9 @@
 
 [简体中文](README.md) | English
 
-ZCode Pro enhances the ZCode desktop UI. No client files are modified; just launch via the ZCode Pro shortcut.
+ZCode Pro enhances the ZCode desktop UI. No client files are modified; just launch via the ZCode Pro shortcut or the `zcode-pro` terminal command.
 
-![AUR](https://img.shields.io/aur/version/zcode-pro) ![Platform](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux%20%7C%20AUR-blue)
+![npm](https://img.shields.io/npm/v/zcode-pro) ![PyPI](https://img.shields.io/pypi/v/zcode-pro) ![AUR](https://img.shields.io/aur/version/zcode-pro) ![Platform](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux%20%7C%20AUR-blue)
 
 > **Opening settings: after launching ZCode Pro, right-click the settings button (gear) at the bottom of the ZCode sidebar to open the ZCode Pro settings window.**
 
@@ -41,6 +41,28 @@ All features can be toggled or adjusted in the settings window.
 
 Once installed, launch ZCode via the "ZCode Pro" shortcut in your app menu / Start menu, or the `zcode-pro` command in a terminal — the enhancements are enabled automatically in this mode; launching ZCode through its original entry does not load them. After launching, right-click the settings button at the bottom of the ZCode sidebar to open the ZCode Pro settings window.
 
+### 📦 npm / PyPI
+
+At runtime the Node runtime bundled with ZCode is preferred; if ZCode cannot be found, system Node.js (≥ 22) is used.
+
+```bash
+# Option 1: install/uninstall via npm
+npm install -g zcode-pro
+npm uninstall -g zcode-pro
+# Option 2: install/uninstall via pip
+pip install zcode-pro
+pip uninstall zcode-pro
+
+# Launch via the command
+zcode-pro
+# Add a Start-menu shortcut
+zcode-pro setup
+# Add a Start-menu shortcut + a desktop shortcut
+zcode-pro setup --desktop
+# Undo the shortcuts
+zcode-pro setup --uninstall
+```
+
 ### 🐧 Linux / macOS
 
 ```bash
@@ -55,15 +77,19 @@ cd zcode-pro && ./scripts/install.sh
 
 ### 🪟 Windows
 
+Run with **PowerShell (Admin)**:
 ```powershell
 git clone https://github.com/duanluan/zcode-pro.git
 cd zcode-pro
-powershell -ExecutionPolicy Bypass -File scripts\install.ps1          # Start menu shortcut
-powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Desktop # plus a desktop shortcut
-```
 
-- Installs to `%LOCALAPPDATA%\ZCodePro`; shortcuts launch silently without a console window;
-- Uninstall: `powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Uninstall`.
+# Add a Start-menu shortcut
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1
+# Add a Start-menu shortcut + a desktop shortcut
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Desktop
+
+# Uninstall
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Uninstall
+```
 
 ### 📦 AUR (Arch / Manjaro)
 
@@ -80,12 +106,19 @@ If you previously installed via `install.sh`, run `./scripts/install.sh --uninst
 
 ### 🚀 Run without installing
 
-No standalone Node.js required: when a system Node is missing, the runtime bundled with ZCode is used.
+No standalone Node.js required: the runtime bundled with ZCode is preferred and used even without a system Node; works whether ZCode is installed in the default or a custom directory (auto-detected, falling back to the registry).
 
 ```bash
 git clone https://github.com/duanluan/zcode-pro.git && cd zcode-pro
-./bin/zcode-pro            # Linux / macOS (auto-detects /opt/ZCode, /Applications/ZCode.app)
-bin\zcode-pro.cmd          # Windows (auto-detects %LOCALAPPDATA%\Programs\ZCode\ZCode.exe)
+
+# Linux / macOS (auto-detects /opt/ZCode, /Applications/ZCode.app)
+./bin/zcode-pro
+# Windows (auto-detects default locations, falls back to the registry)
+bin\zcode-pro.cmd
+
+# Manually add a Start-menu shortcut (--desktop also adds a desktop shortcut, --uninstall undoes)
+./bin/zcode-pro setup
+bin\zcode-pro.cmd setup
 ```
 
 ## 📖 Reference
@@ -99,6 +132,7 @@ Command-line options (see `zcode-pro --help` for all):
 | `--zcode-path` | Explicit path to the ZCode executable |
 | `--inject-only` | Attach to a running instance only; do not launch a new one |
 | `--verbose` | Verbose logging |
+| `setup [--desktop] [--uninstall]` | Install/undo local shortcuts (`--desktop` also adds a desktop one) |
 
 Each option can also be overridden with a `ZCODEPRO_*` environment variable.
 

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/README.md

@@ -2,9 +2,9 @@
 
 [English](README.en.md) | 简体中文
 
-ZCode 桌面版界面增强工具。不修改客户端文件，通过 ZCode Pro 快捷方式启动即可。
+ZCode 桌面版界面增强工具。不修改客户端文件，通过 ZCode Pro 快捷方式或终端命令 `zcode-pro` 启动即可。
 
-![AUR 版本](https://img.shields.io/aur/version/zcode-pro) ![平台](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux%20%7C%20AUR-blue)
+![npm](https://img.shields.io/npm/v/zcode-pro) ![PyPI](https://img.shields.io/pypi/v/zcode-pro) ![AUR 版本](https://img.shields.io/aur/version/zcode-pro) ![平台](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux%20%7C%20AUR-blue)
 
 > ⚙️ **打开设置：启动 ZCode Pro 后，右键点击 ZCode 侧边栏底部的设置按钮（齿轮）即可打开 ZCode Pro 设置窗口。**
 
@@ -41,6 +41,28 @@ ZCode 桌面版界面增强工具。不修改客户端文件，通过 ZCode Pro
 
 安装后，通过应用菜单 / 开始菜单中的“ZCode Pro”快捷方式或终端命令 `zcode-pro` 启动 ZCode，增强在该方式下自动生效；使用原有 ZCode 入口启动时不加载增强。
 
+### 📦 npm / PyPI
+
+运行时优先复用 ZCode 自带的运行时；未找到 ZCode 时回退系统 Node.js（≥ 22）。
+
+```bash
+# 方式一：npm 安装/卸载
+npm install -g zcode-pro
+npm uninstall -g zcode-pro
+# 方式二：pip 安装/卸载
+pip install zcode-pro
+pip uninstall zcode-pro
+
+# 通过命令启动
+zcode-pro
+# 添加开始菜单快捷方式
+zcode-pro setup
+# 添加开始菜单快捷方式 + 桌面快捷方式
+zcode-pro setup --desktop
+# 撤销添加快捷方式
+zcode-pro setup --uninstall
+```
+
 ### 🐧 Linux / macOS
 
 - 安装至 `~/.local`，可通过 `PREFIX=` 指定其他位置；
@@ -55,14 +77,18 @@ cd zcode-pro && ./scripts/install.sh
 
 ### 🪟 Windows
 
-- 程序安装至 `%LOCALAPPDATA%\ZCodePro`，快捷方式静默启动，不显示控制台窗口；
-- 卸载：`powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Uninstall`。
-
+使用 **PowerShell (管理员)** 运行：
 ```powershell
 git clone https://github.com/duanluan/zcode-pro.git
 cd zcode-pro
-powershell -ExecutionPolicy Bypass -File scripts\install.ps1          # 开始菜单快捷方式
-powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Desktop # 加桌面快捷方式
+
+# 添加开始菜单快捷方式
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1
+# 添加开始菜单快捷方式 + 桌面快捷方式
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Desktop
+
+# 卸载
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Uninstall
 ```
 
 ### 📦 AUR
@@ -80,12 +106,19 @@ git clone https://aur.archlinux.org/zcode-pro.git && cd zcode-pro && makepkg -si
 
 ### 🚀 手动运行（不安装）
 
-无需单独安装 Node.js：缺少系统 Node 时自动使用 ZCode 内置运行时。
+无需单独安装 Node.js：优先使用 ZCode 内置运行时，缺少系统 Node 时亦能运行；ZCode 安装在默认或自定义目录均可（自动探测，必要时查注册表）。
 
 ```bash
 git clone https://github.com/duanluan/zcode-pro.git && cd zcode-pro
-./bin/zcode-pro            # Linux / macOS（自动探测 /opt/ZCode、/Applications/ZCode.app）
-bin\zcode-pro.cmd          # Windows（自动探测 %LOCALAPPDATA%\Programs\ZCode\ZCode.exe）
+
+# Linux / macOS（自动探测 /opt/ZCode、/Applications/ZCode.app）
+./bin/zcode-pro
+# Windows（自动探测默认安装位置，找不到时查注册表）
+bin\zcode-pro.cmd
+
+# 手动添加开始菜单快捷方式（--desktop 同时添加桌面快捷方式，--uninstall 撤销添加快捷方式）
+./bin/zcode-pro setup
+bin\zcode-pro.cmd setup
 ```
 
 ## 📖 参考
@@ -99,6 +132,7 @@ bin\zcode-pro.cmd          # Windows（自动探测 %LOCALAPPDATA%\Programs\ZCod
 | `--zcode-path` | 显式指定 ZCode 可执行文件 |
 | `--inject-only` | 只接管已在运行的实例，不启动新实例 |
 | `--verbose` | 详细日志 |
+| `setup [--desktop] [--uninstall]` | 安装/撤销本机快捷方式（`--desktop` 同时加桌面） |
 
 各选项也可用环境变量 `ZCODEPRO_*` 覆盖。
 

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/bin/zcode-pro.cmd

@@ -1,24 +1,29 @@
-@echo off
-rem ZCode Pro 启动器（Windows）
-rem 优先用 ZCode 自带的 Node 运行时（ELECTRON_RUN_AS_NODE），无需安装 Node.js。
-setlocal
-set "SCRIPT_DIR=%~dp0"
-set "APP_DIR=%SCRIPT_DIR%.."
-set "ENTRY=%APP_DIR%\cli.mjs"
-
-where node >nul 2>nul
-if %errorlevel%==0 (
-  node "%ENTRY%" %*
-  exit /b %errorlevel%
-)
-
-set "ZCODE_BIN=%ZCODEPRO_ZCODE_PATH%"
-if not exist "%ZCODE_BIN%" set "ZCODE_BIN=%LOCALAPPDATA%\Programs\ZCode\ZCode.exe"
-if not exist "%ZCODE_BIN%" set "ZCODE_BIN=%PROGRAMFILES%\ZCode\ZCode.exe"
-if not exist "%ZCODE_BIN%" (
-  echo [zcodepro] 未找到 node，也未找到 ZCode 可执行文件。请安装 Node.js ^>= 22 或设置 ZCODEPRO_ZCODE_PATH。 1>&2
-  exit /b 1
-)
-set "ELECTRON_RUN_AS_NODE=1"
-"%ZCODE_BIN%" "%ENTRY%" %*
-exit /b %errorlevel%
+@echo off
+rem ZCode Pro 启动器（Windows）
+rem 优先用 ZCode 自带的 Node 运行时（ELECTRON_RUN_AS_NODE），无需安装 Node.js。
+setlocal
+set "SCRIPT_DIR=%~dp0"
+set "APP_DIR=%SCRIPT_DIR%.."
+set "ENTRY=%APP_DIR%\cli.mjs"
+
+where node >nul 2>nul
+if %errorlevel%==0 (
+  node "%ENTRY%" %*
+  exit /b %errorlevel%
+)
+
+set "ZCODE_BIN=%ZCODEPRO_ZCODE_PATH%"
+if not exist "%ZCODE_BIN%" set "ZCODE_BIN=%LOCALAPPDATA%\Programs\ZCode\ZCode.exe"
+if not exist "%ZCODE_BIN%" set "ZCODE_BIN=%PROGRAMFILES%\ZCode\ZCode.exe"
+rem Custom install dir: look up App Paths in registry (per-machine then per-user).
+if not exist "%ZCODE_BIN%" for /f "tokens=2*" %%A in (
+  'reg query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\zcode.exe" /ve 2^>nul ^|^|
+   reg query "HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\zcode.exe" /ve 2^>nul'
+) do if not exist "%ZCODE_BIN%" if exist "%%B" set "ZCODE_BIN=%%B"
+if not exist "%ZCODE_BIN%" (
+  echo [zcodepro] 未找到 node，也未找到 ZCode 可执行文件。请安装 Node.js ^>= 22 或设置 ZCODEPRO_ZCODE_PATH。 1>&2
+  exit /b 1
+)
+set "ELECTRON_RUN_AS_NODE=1"
+"%ZCODE_BIN%" "%ENTRY%" %*
+exit /b %errorlevel%

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/bin/zcode-pro.mjs

@@ -3,20 +3,24 @@
 // 优先用 ZCode 自带的 Node 运行时（ELECTRON_RUN_AS_NODE），避免系统 node 过旧
 // （<22.5 缺 node:sqlite、<22 缺全局 WebSocket）时启动失败；
 // 找不到 ZCode 可执行文件时回退当前 node 进程（npm 环境必有 node）。
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
-const cliPath = fileURLToPath(new URL('../cli.mjs', import.meta.url));
+// 动态导入必须用 URL 对象：Windows 上绝对路径（C:\...）会被当作 c: 协议报错
+const cliUrl = new URL('../cli.mjs', import.meta.url);
+const cliPath = fileURLToPath(cliUrl);
 const argv = process.argv.slice(2);
 
 async function runWithZcodeRuntime() {
   const { resolveZcodeExecutable } = await import('../src/host/paths.mjs');
   const zcodeBin = resolveZcodeExecutable('');
+  const env = { ...process.env, ELECTRON_RUN_AS_NODE: '1' };
+  // 预检：注册表等来源找到的 ZCode 可能不完整（缺 resources/ICU 数据等），以 Node
+  // 模式跑不起来的直接抛错回退系统 node，避免启动器跟着报难懂的错误退出
+  const pre = spawnSync(zcodeBin, ['-e', 'process.exit(0)'], { env, stdio: 'ignore' });
+  if (pre.status !== 0) throw new Error(`ZCode 运行时不可用（${zcodeBin}）`);
   await new Promise((resolve, reject) => {
-    const child = spawn(zcodeBin, [cliPath, ...argv], {
-      stdio: 'inherit',
-      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
-    });
+    const child = spawn(zcodeBin, [cliPath, ...argv], { stdio: 'inherit', env });
     child.on('error', reject);
     child.on('exit', (code, signal) => {
       if (signal) process.kill(process.pid, signal);
@@ -29,5 +33,5 @@ async function runWithZcodeRuntime() {
 try {
   await runWithZcodeRuntime();
 } catch {
-  await import(cliPath);
+  await import(cliUrl);
 }

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/bin/zcode-pro.vbs

@@ -1,16 +1,16 @@
-' ZCode Pro 静默启动器（Windows）
-' 以隐藏窗口运行 zcode-pro.cmd：快捷方式启动时不会常驻黑色控制台窗口，
-' 而 helper/注入进程继续在后台维持增强。
-Set fso = CreateObject("Scripting.FileSystemObject")
-Set sh = CreateObject("WScript.Shell")
-dir = fso.GetParentFolderName(WScript.ScriptFullName)
-cmd = """" & dir & "\zcode-pro.cmd"""
-If WScript.Arguments.Count > 0 Then
-  Dim parts()
-  ReDim parts(WScript.Arguments.Count - 1)
-  For i = 0 To WScript.Arguments.Count - 1
-    parts(i) = """" & WScript.Arguments(i) & """"
-  Next
-  cmd = cmd & " " & Join(parts, " ")
-End If
-sh.Run cmd, 0, False
+' ZCode Pro 静默启动器（Windows）
+' 以隐藏窗口运行 zcode-pro.cmd：快捷方式启动时不会常驻黑色控制台窗口，
+' 而 helper/注入进程继续在后台维持增强。
+Set fso = CreateObject("Scripting.FileSystemObject")
+Set sh = CreateObject("WScript.Shell")
+dir = fso.GetParentFolderName(WScript.ScriptFullName)
+cmd = """" & dir & "\zcode-pro.cmd"""
+If WScript.Arguments.Count > 0 Then
+  Dim parts()
+  ReDim parts(WScript.Arguments.Count - 1)
+  For i = 0 To WScript.Arguments.Count - 1
+    parts(i) = """" & WScript.Arguments(i) & """"
+  Next
+  cmd = cmd & " " & Join(parts, " ")
+End If
+sh.Run cmd, 0, False

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/dist/inject.js

@@ -611,6 +611,18 @@
     failed: "Operation failed",
     retryHint: "Please retry"
   };
+  var cachedSystemLocale = null;
+  function startLocaleResolver() {
+    if (cachedSystemLocale !== null) return;
+    const get = typeof window !== "undefined" ? window.zcode?.getSystemLocale : null;
+    if (typeof get !== "function") return;
+    Promise.resolve(get()).then((locale) => {
+      if (typeof locale === "string" && locale) {
+        cachedSystemLocale = locale.toLowerCase().startsWith("zh") ? "zh-CN" : "en-US";
+      }
+    }).catch(() => {
+    });
+  }
   function isZhLocale() {
     let pref = null;
     try {
@@ -618,6 +630,7 @@
     } catch {
     }
     if (pref === "zh-CN" || pref === "en-US") return pref === "zh-CN";
+    if (cachedSystemLocale) return cachedSystemLocale === "zh-CN";
     return /^zh/i.test(navigator.language || "zh-CN");
   }
   function t() {
@@ -5747,8 +5760,16 @@
     if (typeof window === "undefined") return;
     if (window.__zcodeproInjected) return;
     window.__zcodeproInjected = true;
+    try {
+      startLocaleResolver();
+    } catch {
+    }
     const start = () => {
       ensureStyle();
+      try {
+        startLocaleResolver();
+      } catch {
+      }
       observeRadixPopups((content) => {
         try {
           handleProjectMenu(content);

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-pro",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "ZCode Pro — 为 ZCode 桌面版增加界面增强（不修改客户端文件，通过 ZCode Pro 快捷方式启动即可），核心功能：项目自定义别名",
   "type": "module",
   "bin": {

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/src/host/helper.mjs

@@ -15,7 +15,7 @@ import { pickFolderSystem } from './pickFolder.mjs';
 import { reorderWorkspaceTasks, reorderGroupMembers } from './taskOrder.mjs';
 import { webdavRequest, webdavPutWithMkcol, webdavHttpText } from './webdav.mjs';
 
-const VERSION = '0.16.0';
+const VERSION = '0.17.0';
 
 // 全局提示词固定在用户主目录：官方加载器按 HOME/USERPROFILE 拼 .zcode/AGENTS.md，
 // 不读 ZCODE_DATA_BASE_DIR（数据根迁走时全局指令仍在原位）。

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/src/host/main.mjs

@@ -12,6 +12,7 @@ import { randomBytes } from 'node:crypto';
 import { resolveZcodeExecutable, resolveDataRootDir } from './paths.mjs';
 import { CdpConnection, fetchBrowserWsUrl } from './cdp.mjs';
 import { startHelper } from './helper.mjs';
+import { runSetup } from './setup.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const INJECT_BUNDLE = resolve(here, '..', '..', 'dist', 'inject.js');
@@ -29,6 +30,11 @@ function usage() {
   --verbose              输出详细日志
   -h, --help             显示帮助
 
+子命令:
+  setup                  安装本机集成（快捷方式：Linux 应用菜单 / Windows 开始菜单 / macOS 应用）
+  setup --desktop        同时在桌面创建快捷方式
+  setup --uninstall      移除由 setup 安装的集成（含桌面）
+
 环境变量:
   ZCODEPRO_ZCODE_PATH     ZCode 可执行文件路径（同 --zcode-path）
   ZCODEPRO_CDP_PORT       CDP 端口
@@ -47,6 +53,9 @@ function parseArgs(argv) {
     else if (a === '--inject-only' || a === '--no-launch') out.injectOnly = true;
     else if (a === '--verbose' || a === '-v') out.verbose = true;
     else if (a === '-h' || a === '--help') out.help = true;
+    else if (a === 'setup') out.setup = true;
+    else if (a === '--uninstall') out.setupUninstall = true;
+    else if (a === '--desktop') out.setupDesktop = true;
     else { console.error('未知参数: ' + a); out.help = true; }
   }
   out.cdpPort = out.cdpPort || Number(process.env.ZCODEPRO_CDP_PORT) || 9333;
@@ -122,6 +131,16 @@ async function buildInjectSource(token, helperPort, features) {
 export async function run(argv) {
   const args = parseArgs(argv);
   if (args.help) { console.log(usage()); return; }
+  // setup 不依赖 ZCode 运行（装快捷方式等本机集成），先于 ZCode 定位处理
+  if (args.setup || args.setupUninstall || args.setupDesktop) {
+    if (!args.setup && (args.setupUninstall || args.setupDesktop)) {
+      console.error('未知用法: --uninstall / --desktop 仅可与 setup 连用');
+      console.log(usage());
+      return;
+    }
+    await runSetup({ uninstall: args.setupUninstall, desktop: args.setupDesktop });
+    return;
+  }
   const log = (...a) => { if (args.verbose) console.log('[zcodepro]', ...a); };
 
   let exe;

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/src/host/paths.mjs

@@ -1,8 +1,51 @@
 // 跨平台定位 ZCode 桌面版可执行文件。
-// 优先级：--zcode-path 参数 > ZCODEPRO_ZCODE_PATH 环境变量 > 平台默认候选路径 > PATH 上的 zcode。
+// 优先级：--zcode-path 参数 > ZCODEPRO_ZCODE_PATH 环境变量 > 平台默认候选路径 > 注册表（Windows） > PATH 上的 zcode。
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { arch, homedir, platform } from 'node:os';
+import { execFileSync } from 'node:child_process';
+
+// Windows 注册表探测（结果缓存）：自定义安装目录的安装器会在 App Paths（可执行
+// 文件全路径）或卸载表 DisplayIcon（控制面板-卸载软件里可见）留有登记，固定
+// 候选找不到时兜底。reg 输出按行取 REG_SZ 后的值，容忍引号与 ",0" 图标序号后缀。
+let winRegistryCandidates;
+
+function windowsRegistryCandidates() {
+  if (winRegistryCandidates) return winRegistryCandidates;
+  winRegistryCandidates = [];
+  const seen = new Set();
+  const push = (raw) => {
+    const p = String(raw || '').trim().replace(/^"|"$/g, '').replace(/,\d+$/, '');
+    if (/\.exe$/i.test(p) && !seen.has(p.toLowerCase())) {
+      seen.add(p.toLowerCase());
+      winRegistryCandidates.push(p);
+    }
+  };
+  const reg = (args) => {
+    try {
+      return execFileSync('reg', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch { return ''; }
+  };
+  const valueAfter = (out) => (out.split(/REG_SZ\s+/)[1] || '').trim();
+  // App Paths：安装器注册的可执行文件全路径（ShellExecute 同款查找）
+  for (const root of ['HKLM', 'HKCU']) {
+    const out = reg(['query', `${root}\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\zcode.exe`, '/ve']);
+    if (out) push(valueAfter(out));
+  }
+  // 卸载表 DisplayIcon：安装目录自定义时通常只有这里能找到
+  for (const key of [
+    'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+    'HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+    'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+  ]) {
+    const out = reg(['query', key, '/s', '/v', 'DisplayIcon']);
+    for (const line of out.split(/\r?\n/)) {
+      const seg = (line.split(/REG_SZ\s+/)[1] || '').trim();
+      if (seg && /zcode/i.test(seg)) push(seg);
+    }
+  }
+  return winRegistryCandidates;
+}
 
 function candidates() {
   const home = homedir();
@@ -14,6 +57,7 @@ function candidates() {
       join(localAppData, 'Programs', 'zcode', 'zcode.exe'),
       join(programFiles, 'ZCode', 'ZCode.exe'),
       join(programFiles, 'zcode', 'zcode.exe'),
+      ...windowsRegistryCandidates(),
     ];
   }
   if (platform() === 'darwin') {

zcode_pro-0.17.0/src/host/setup.mjs

@@ -0,0 +1,514 @@
+// zcode-pro setup：本机集成设置入口（npm / pip 等包管理器安装不写系统目录，
+// 需要菜单入口等集成时显式运行本子命令）。按「设置项」组织（id / 标题 /
+// install / uninstall），以后新增设置项往 items 里加即可。
+// setup 不依赖 ZCode 运行，在 main.run 里先于 ZCode 定位处理。
+//
+// 快捷方式各平台形态（与 install.sh / install.ps1 的条目内容保持一致）：
+// - Linux：应用菜单 .desktop（Exec 指向 PATH 中的 zcode-pro，Icon=zcode 复用 ZCode 图标）
+// - Windows：开始菜单 .lnk → wscript 运行生成的 vbs（静默启动、无控制台窗口），
+//   图标取 ZCode.exe；包管理器安装不带 vbs，这里按 PATH 命令现生成
+// - macOS：~/Applications 下的“ZCode Pro.app”包（图标复制 ZCode 的 app.icns，无则省略）
+//
+// Windows 中文编码注意（vbs / PowerShell 均受代码页影响）：
+// - vbs 由 wscript 按 ANSI 代码页解析，不支持 UTF-8——生成内容只用 ASCII；
+// - PowerShell 脚本一律经 -EncodedCommand 传 Base64(UTF-16LE)，中文不经命令行与
+//   文件编码，避开代码页问题；
+// - 仓库内 PowerShell 脚本（install.ps1 等）必须保存为带 BOM 的 UTF-8。
+import { execFileSync } from 'node:child_process';
+import { accessSync, chmodSync, constants as fsConstants, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, sep } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolveZcodeExecutable } from './paths.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url)); // …/src/host（随包安装后为包内对应目录）
+const pkgRoot = dirname(dirname(here));               // 安装根目录（含 cli.mjs 与 bin/）
+
+const SUPPORTED = ['linux', 'win32', 'darwin'];
+
+// —— PATH 中的 zcode-pro 命令 ——
+
+function commandInPath(plat) {
+  const pathSep = plat === 'win32' ? ';' : ':';
+  // Windows 上 npm 会生成 zcode-pro.cmd / zcode-pro.ps1，pip 生成 zcode-pro.exe，
+  // 只有 .cmd / .exe 能被 wscript 的 sh.Run 直接运行
+  const names = plat === 'win32' ? ['zcode-pro.cmd', 'zcode-pro.exe'] : ['zcode-pro'];
+  for (const dir of (process.env.PATH || '').split(pathSep)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const p = join(dir, name);
+      try {
+        if (plat === 'win32') {
+          if (existsSync(p)) return p;
+        } else {
+          accessSync(p, fsConstants.X_OK); // 可执行
+          return p;
+        }
+      } catch { /* 继续找 */ }
+    }
+  }
+  return null;
+}
+
+// PATH 命令是否属于当前运行的这份安装：
+// - POSIX npm / AUR / install.sh：命令（经符号链接）最终指向本包目录内的启动器；
+// - Windows npm：全局命令是普通 .cmd（非符号链接），按 npm 目录布局认定——
+//   命令旁的 node_modules\zcode-pro 是否即当前包；
+// - pip：命令是 Python 控制台脚本，位于解释器目录而非包目录——POSIX 为文本脚本，
+//   校验其 shebang 解释器所属环境是否包含当前包；Windows 为 exe 启动器，读不出
+//   内容，只能按文件名认定（同机多 Python 环境时以 PATH 靠前者为准，属已知局限）。
+function sameInstall(cmdPath, plat) {
+  let real = cmdPath;
+  try { real = realpathSync(cmdPath); } catch { /* 保持原路径 */ }
+  if (real === pkgRoot || real.startsWith(pkgRoot + sep)) return true;
+  if (plat === 'win32') {
+    try {
+      if (realpathSync(join(dirname(real), 'node_modules', 'zcode-pro')) === pkgRoot) return true;
+    } catch { /* 布局不符则继续 */ }
+    return pkgRoot.split(/[\\/]/).includes('zcode_pro')
+      && basename(real).toLowerCase().startsWith('zcode-pro');
+  }
+  if (pkgRoot.split(sep).includes('zcode_pro')) {
+    try {
+      const shebang = readFileSync(real, 'utf-8').match(/^#!\s*(\S+)/);
+      if (shebang && pkgRoot.startsWith(dirname(dirname(shebang[1])) + sep)) return true;
+    } catch { /* 读不到内容则不认定 */ }
+  }
+  return false;
+}
+
+// —— Windows 快捷方式（路径 / 脚本生成） ——
+
+// 本功能创建的 .lnk 归属标记（PowerShell -like 通配）：vbs 方案的 Arguments 指向
+// 我们的 vbs；WSH 异常降级方案的 start 窗口标题用固定名。卸载据此只删自己的
+const OWN_LNK_MARKERS = ['*zcode-pro-setup.vbs*', '*ZCodePro-Setup*'];
+
+// 归属判断的 PowerShell 表达式：每个 -like 都必须带完整变量前缀（写成共享的
+// “-like a -or -like b” 是语法错误）
+const ownsExpr = (v) => OWN_LNK_MARKERS.map((m) => `${v}.Arguments -like '${m}'`).join(' -or ');
+
+function windowsPaths() {
+  const appData = process.env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+  const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+  return {
+    appData,
+    localAppData,
+    lnkPath: join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'ZCode Pro.lnk'),
+    vbsDir: join(localAppData, 'ZCodePro', 'setup'),
+    vbsPath: join(localAppData, 'ZCodePro', 'setup', 'zcode-pro-setup.vbs'),
+  };
+}
+
+// 经 Base64(UTF-16LE) 的 -EncodedCommand 执行 PowerShell：中文不经过命令行与
+// 文件编码，任何系统代码页下都安全。返回 stdout；非零退出码抛错
+function runPowerShell(script) {
+  const b64 = Buffer.from(script, 'utf16le').toString('base64');
+  return execFileSync('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', b64],
+    { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
+}
+
+// WSH 是否可用：复现 vbs 的启动调用（WScript.Shell.Run 隐藏窗口执行）。
+// 部分机器（精简系统/安全软件/组件禁用）上该调用报 0x800A01AD，需降级 cmd 启动。
+// ZCODEPRO_FORCE_NO_WSH=1 供测试强制走降级路径。
+let wshOkCache;
+
+function windowsWshOk() {
+  if (process.env.ZCODEPRO_FORCE_NO_WSH === '1') return false;
+  if (wshOkCache !== undefined) return wshOkCache;
+  try {
+    runPowerShell([
+      "$ErrorActionPreference = 'Stop'",
+      '$sh = New-Object -ComObject WScript.Shell',
+      "$sh.Run('cmd /c exit 0', 0, $true) | Out-Null",
+    ].join('\r\n'));
+    wshOkCache = true;
+  } catch {
+    wshOkCache = false;
+  }
+  return wshOkCache;
+}
+
+// .lnk 是否本功能创建（按 Arguments 里的归属标记判断；读不到按外来处理，不覆盖）
+function lnkIsOurs(lnkPath) {
+  try {
+    const out = runPowerShell([
+      "$ErrorActionPreference = 'Stop'",
+      `$l = (New-Object -ComObject WScript.Shell).CreateShortcut('${psQuote(lnkPath)}')`,
+      `Write-Output (${OWN_LNK_MARKERS.map((m) => `$l.Arguments -like '${m}'`).join(' -or ')})`,
+    ].join('\r\n'));
+    return /True/.test(out);
+  } catch {
+    return false;
+  }
+}
+
+const psQuote = (s) => String(s).replace(/'/g, "''"); // PowerShell 单引号字面量转义
+
+// 快捷方式计划（导出仅供测试审查，不执行）。desktop 为真时同时创建桌面快捷方式，
+// 桌面目录由 PowerShell 的 GetFolderPath 解析（正确跟随 OneDrive 重定向等）。
+// wshOk 为假（WSH 异常的机器）时降级：.lnk 直接经 cmd 最小化启动，不再依赖
+// wscript+vbs，代价是启动瞬间任务栏短暂闪一个最小化控制台
+export function windowsShortcutPlan(cmd, desktop = false, wshOk = true) {
+  const paths = windowsPaths();
+  // vbs 由 wscript 按 ANSI 代码页解析（不支持 UTF-8），内容只用 ASCII
+  const vbsContent = [
+    `' Generated by zcode-pro setup: run zcode-pro silently (no console window); forwards all arguments`,
+    'Set sh = CreateObject("WScript.Shell")',
+    `cmd = """${cmd.replace(/"/g, '""')}"""`,
+    'If WScript.Arguments.Count > 0 Then',
+    '  Dim parts()',
+    '  ReDim parts(WScript.Arguments.Count - 1)',
+    '  For i = 0 To WScript.Arguments.Count - 1',
+    '    parts(i) = """" & WScript.Arguments(i) & """"',
+    '  Next',
+    '  cmd = cmd & " " & Join(parts, " ")',
+    'End If',
+    'sh.Run cmd, 0, False',
+    '',
+  ].join('\r\n');
+  // 图标复用已安装的 ZCode：探测走 paths.mjs 同一条优先级（含注册表，覆盖自定义
+  // 安装目录）；未安装 ZCode 时留空，快捷方式回落系统默认图标
+  let icon = '';
+  try { icon = resolveZcodeExecutable(''); } catch { /* 未安装 ZCode，省略图标 */ }
+  const iconLine = icon ? `  $l.IconLocation = '${psQuote(`${icon},0`)}'` : '';
+  const setProps = wshOk ? [
+    'function setProps($l) {',
+    '  $l.TargetPath = "$env:SystemRoot\\System32\\wscript.exe"',
+    `  $l.Arguments = '${psQuote(`"${paths.vbsPath}"`)}'`,
+    `  $l.WorkingDirectory = '${psQuote(paths.vbsDir)}'`,
+    "  $l.Description = 'ZCode 桌面版增强启动器（自定义别名等，不修改客户端文件）'",
+    iconLine,
+    '}',
+  ] : [
+    'function setProps($l) {',
+    '  $l.TargetPath = "$env:SystemRoot\\System32\\cmd.exe"',
+    `  $l.Arguments = '/c start "ZCodePro-Setup" /min "${psQuote(cmd)}"'`,
+    `  $l.WorkingDirectory = '${psQuote(paths.vbsDir)}'`,
+    "  $l.Description = 'ZCode 桌面版增强启动器（自定义别名等，不修改客户端文件）'",
+    iconLine,
+    '  $l.WindowStyle = 7',
+    '}',
+  ];
+  const psScript = [
+    "$ErrorActionPreference = 'Stop'",
+    '$wsh = New-Object -ComObject WScript.Shell',
+    ...setProps,
+    `$lnk = $wsh.CreateShortcut('${psQuote(paths.lnkPath)}')`,
+    'setProps $lnk',
+    '$lnk.Save()',
+    ...(desktop ? [
+      "$desk = Join-Path ([Environment]::GetFolderPath('Desktop')) 'ZCode Pro.lnk'",
+      '$dl = $wsh.CreateShortcut($desk)',
+      '# 已存在且非本功能创建（Arguments 无归属标记）时不覆盖',
+      `if (-not (Test-Path $desk) -or (${ownsExpr('$dl')})) {`,
+      '  setProps $dl',
+      '  $dl.Save()',
+      '}',
+    ] : []),
+  ].filter(Boolean).join('\r\n');
+  return { ...paths, vbsContent, psScript, icon, wshOk };
+}
+
+// —— 快捷方式设置项 ——
+
+const DESKTOP_FILE = 'zcode-pro.desktop';
+// setup 创建的条目带标记：卸载只动自己的，不误删 install.sh / AUR / install.ps1 的同名条目
+const SETUP_MARK = 'X-ZCodePro-Setup=true';
+
+function desktopEntry(execCmd) {
+  const exec = /\s/.test(execCmd) ? `"${execCmd}"` : execCmd;
+  return [
+    '[Desktop Entry]',
+    'Type=Application',
+    'Name=ZCode Pro',
+    'Comment=ZCode 桌面版增强启动器（自定义别名等，不修改客户端文件）',
+    `Exec=${exec}`,
+    'Icon=zcode',
+    'Terminal=false',
+    'Categories=Development;IDE;',
+    'Keywords=zcode;pro;enhance;',
+    SETUP_MARK,
+    '',
+  ].join('\n');
+}
+
+function applicationsDir() {
+  return join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'applications');
+}
+
+// Linux 桌面目录：优先 xdg-user-dir（正确跟随本地化目录名，如 ~/桌面）
+function desktopDir() {
+  try {
+    const dir = execFileSync('xdg-user-dir', ['DESKTOP'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    if (dir) return dir;
+  } catch { /* 无该命令时按常见值回退 */ }
+  return existsSync(join(homedir(), 'Desktop')) ? join(homedir(), 'Desktop') : join(homedir(), '桌面');
+}
+
+// macOS 应用包目录、桌面入口（指向应用包的符号链接）与图标来源
+function macAppBundle() {
+  return join(homedir(), 'Applications', 'ZCode Pro.app');
+}
+
+function macDesktopLink() {
+  return join(homedir(), 'Desktop', 'ZCode Pro.app');
+}
+
+function plistContent(hasIcon) {
+  const pairs = [
+    ['CFBundleName', 'ZCode Pro'],
+    ['CFBundleDisplayName', 'ZCode Pro'],
+    ['CFBundleIdentifier', 'com.duanluan.zcodepro'],
+    ['CFBundleVersion', '1'],
+    ['CFBundleShortVersionString', '1'],
+    ['CFBundlePackageType', 'APPL'],
+    ['CFBundleExecutable', 'zcode-pro'],
+  ];
+  if (hasIcon) pairs.push(['CFBundleIconFile', 'app']);
+  const body = pairs.map(([k, v]) => `  <key>${k}</key>\n  <string>${v}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n${body}\n</dict>\n</plist>\n`;
+}
+
+const shortcutItem = {
+  id: 'desktop-shortcut',
+  title: '快捷方式“ZCode Pro”（应用菜单/开始菜单，图标复用 ZCode）',
+  supported: (plat) => SUPPORTED.includes(plat),
+
+  install(plat, opts = {}) {
+    const cmd = commandInPath(plat);
+    if (!cmd) {
+      throw new Error('未在 PATH 中找到 zcode-pro 命令，无法创建快捷方式；请确认安装方式后重试。');
+    }
+    if (!sameInstall(cmd, plat)) {
+      throw new Error(`PATH 中的 zcode-pro（${cmd}）不属于当前运行的这份安装，` +
+        '为避免快捷方式指向旧版本已跳过；请用那份安装自己的方式管理快捷方式。');
+    }
+    if (plat === 'linux') return this.installLinux(cmd, opts);
+    if (plat === 'win32') return this.installWindows(cmd, opts);
+    return this.installMac(cmd, opts);
+  },
+
+  installLinux(cmd, opts = {}) {
+    // 系统级（AUR 等）已有同名条目时不再建用户级：desktop 文件 id 相同时用户级
+    // 会遮蔽系统级（项目既有约定），残留后表现为菜单一直运行另一份
+    if (existsSync('/usr/share/applications/zcode-pro.desktop')) {
+      return { skipped: '检测到系统级 ZCode Pro 快捷方式（AUR 等已安装），用户级条目会遮蔽它，已跳过' };
+    }
+    const appsDir = applicationsDir();
+    const target = join(appsDir, DESKTOP_FILE);
+    const parts = [];
+    if (existsSync(target)) {
+      const cur = readFileSync(target, 'utf-8');
+      if (!cur.includes(SETUP_MARK)) {
+        return { skipped: `${target} 已存在且非 setup 创建（如 install.sh），未覆盖` };
+      }
+      const exec = (cur.match(/^Exec=(.+)$/m) || [])[1] || '';
+      if (exec.includes(cmd)) {
+        parts.push('应用菜单条目已存在且指向当前命令，无需重复创建');
+      } else {
+        writeFileSync(target, desktopEntry(cmd));
+        parts.push(`已更新 ${target}（Exec=${cmd}）`);
+      }
+    } else {
+      mkdirSync(appsDir, { recursive: true });
+      writeFileSync(target, desktopEntry(cmd));
+      parts.push(`已写入 ${target}（Exec=${cmd}）`);
+    }
+    try { execFileSync('update-desktop-database', [appsDir], { stdio: 'ignore' }); } catch { /* 无该命令时忽略 */ }
+    // 桌面条目独立判断（不因菜单条目幂等而短路）
+    if (opts.desktop) {
+      const dDir = desktopDir();
+      const dTarget = join(dDir, DESKTOP_FILE);
+      if (!existsSync(dTarget) || readFileSync(dTarget, 'utf-8').includes(SETUP_MARK)) {
+        writeFileSync(dTarget, desktopEntry(cmd));
+        parts.push(`桌面 ${dTarget}`);
+      } else {
+        parts.push('桌面已存在非 setup 创建的条目，未覆盖');
+      }
+    }
+    if (parts.length === 1 && parts[0].startsWith('应用菜单条目已存在')) return { skipped: parts[0] };
+    return { detail: parts.join('；') };
+  },
+
+  installWindows(cmd, opts = {}) {
+    const wshOk = windowsWshOk();
+    const plan = windowsShortcutPlan(cmd, !!opts.desktop, wshOk);
+    // .lnk 已存在且不属于本功能（Arguments 无归属标记）＝ install.ps1 等其他方式创建，不覆盖
+    if (existsSync(plan.lnkPath) && !lnkIsOurs(plan.lnkPath)) {
+      return { skipped: `已存在其他方式创建的 ${plan.lnkPath}，未覆盖` };
+    }
+    if (wshOk) {
+      mkdirSync(plan.vbsDir, { recursive: true });
+      writeFileSync(plan.vbsPath, plan.vbsContent);
+    }
+    runPowerShell(plan.psScript);
+    const how = wshOk
+      ? `经 ${plan.vbsPath} 静默启动`
+      : '本机 WSH 异常，经 cmd 最小化启动（启动时会短暂闪烁控制台窗口）';
+    return { detail: `已创建 ${plan.lnkPath}（${how}${opts.desktop ? '，含桌面' : ''}）` };
+  },
+
+  installMac(cmd, opts = {}) {
+    const app = macAppBundle();
+    const contents = join(app, 'Contents');
+    const marker = join(contents, 'zcodepro-setup-marker');
+    if (existsSync(app) && !existsSync(marker)) {
+      return { skipped: `${app} 已存在且非 setup 创建，未覆盖` };
+    }
+    let iconCopied = false;
+    for (const src of [join('/', 'Applications', 'ZCode.app', 'Contents', 'Resources', 'app.icns'),
+                       join(homedir(), 'Applications', 'ZCode.app', 'Contents', 'Resources', 'app.icns')]) {
+      if (!existsSync(src)) continue;
+      try {
+        mkdirSync(join(contents, 'Resources'), { recursive: true });
+        copyFileSync(src, join(contents, 'Resources', 'app.icns'));
+        iconCopied = true;
+        break;
+      } catch { /* 复制失败则省略图标 */ }
+    }
+    mkdirSync(join(contents, 'MacOS'), { recursive: true });
+    const launcher = join(contents, 'MacOS', 'zcode-pro');
+    writeFileSync(launcher, `#!/bin/sh\nexec "${cmd}" "$@"\n`);
+    chmodSync(launcher, 0o755);
+    writeFileSync(join(contents, 'Info.plist'), plistContent(iconCopied));
+    writeFileSync(marker, '');
+    let detail = `已创建 ${app}（启动器指向 ${cmd}${iconCopied ? '，图标已复制' : ''}）`;
+    if (opts.desktop) {
+      const link = macDesktopLink();
+      if (existsSync(link)) {
+        detail += '；桌面已存在同名入口，未覆盖';
+      } else {
+        try {
+          symlinkSync(app, link);
+          detail += `；桌面 ${link}`;
+        } catch { /* 建链接失败仅省略桌面入口 */ }
+      }
+    }
+    return { detail };
+  },
+
+  uninstall(plat) {
+    if (plat === 'linux') return this.uninstallLinux();
+    if (plat === 'win32') return this.uninstallWindows();
+    return this.uninstallMac();
+  },
+
+  uninstallLinux() {
+    const target = join(applicationsDir(), DESKTOP_FILE);
+    const dTarget = join(desktopDir(), DESKTOP_FILE);
+    const removed = [];
+    if (existsSync(target) && readFileSync(target, 'utf-8').includes(SETUP_MARK)) {
+      rmSync(target);
+      removed.push(target);
+    }
+    // setup --desktop 建的桌面条目一并清理（同样只动带标记的）
+    if (existsSync(dTarget) && readFileSync(dTarget, 'utf-8').includes(SETUP_MARK)) {
+      rmSync(dTarget);
+      removed.push(dTarget);
+    }
+    if (!removed.length) return { skipped: '未发现 setup 创建的快捷方式' };
+    try { execFileSync('update-desktop-database', [applicationsDir()], { stdio: 'ignore' }); } catch { /* 无该命令时忽略 */ }
+    return { detail: `已移除 ${removed.join('、')}` };
+  },
+
+  uninstallWindows() {
+    const paths = windowsPaths();
+    const hadVbs = existsSync(paths.vbsPath);
+    const hadLnk = existsSync(paths.lnkPath);
+    if (!hadVbs && !hadLnk) return { skipped: '未发现 setup 创建的快捷方式' };
+    // .lnk 可能已被 install.ps1 等重建并指向它自己：只有 Arguments 带本功能归属
+    // 标记才删；校验失败也保留 .lnk（宁可漏删不误删）
+    let lnkRemoved = false;
+    let verified = false;
+    try {
+      runPowerShell([
+        "$ErrorActionPreference = 'Stop'",
+        '$wsh = New-Object -ComObject WScript.Shell',
+        `$lnk = $wsh.CreateShortcut('${psQuote(paths.lnkPath)}')`,
+        `if (${ownsExpr('$lnk')}) { Remove-Item -LiteralPath '${psQuote(paths.lnkPath)}' -Force }`,
+        // setup --desktop 建的桌面 .lnk 一并清理（归属校验同开始菜单）
+        "$desk = Join-Path ([Environment]::GetFolderPath('Desktop')) 'ZCode Pro.lnk'",
+        'if (Test-Path $desk) {',
+        '  $dl = $wsh.CreateShortcut($desk)',
+        `  if (${ownsExpr('$dl')}) { Remove-Item -LiteralPath $desk -Force }`,
+        '}',
+      ].join('\r\n'));
+      verified = true;
+      lnkRemoved = !existsSync(paths.lnkPath);
+    } catch { /* 校验失败则不动 .lnk */ }
+    let vbsCleaned = !hadVbs;
+    if (hadVbs) {
+      try {
+        rmSyncWithRetry(paths.vbsDir);
+        vbsCleaned = true;
+      } catch (err) {
+        // 目录被杀软/索引短暂锁定导致 EPERM：先试原生 rmdir，仍失败但里面的文件
+        // 已删干净时按成功处理（残留空目录无害，下次运行会覆盖）
+        try {
+          execFileSync('cmd', ['/c', 'rmdir', '/s', '/q', paths.vbsDir], { stdio: 'ignore' });
+          vbsCleaned = true;
+        } catch {
+          vbsCleaned = !existsSync(paths.vbsPath);
+          if (!vbsCleaned) console.error(`  （${paths.vbsDir} 删除失败，可能被占用，可稍后手动删除）`);
+        }
+      }
+    }
+    const parts = [];
+    if (hadLnk) {
+      parts.push(lnkRemoved ? '开始菜单/桌面快捷方式' : verified ? '快捷方式已非本功能创建，未删除' : '快捷方式归属校验失败，未删除 .lnk');
+    }
+    if (hadVbs) parts.push(vbsCleaned ? '生成的启动脚本' : '启动脚本（删除失败）');
+    return { detail: `已移除：${parts.join('；')}` };
+  },
+
+  uninstallMac() {
+    const app = macAppBundle();
+    const marker = join(app, 'Contents', 'zcodepro-setup-marker');
+    if (!existsSync(marker)) return { skipped: '未发现 setup 创建的应用包' };
+    // setup --desktop 建的桌面入口一并清理（只删指向本应用包的链接）
+    const link = macDesktopLink();
+    try {
+      if (existsSync(link) && realpathSync(link) === realpathSync(app)) rmSync(link);
+    } catch { /* 链接失效则忽略 */ }
+    rmSync(app, { recursive: true, force: true });
+    return { detail: `已移除 ${app}` };
+  },
+};
+
+// Windows 上刚写过的目录可能被杀软/索引短暂占用，立即删除偶发 EPERM：短暂等待后重试
+function rmSyncWithRetry(target, tries = 4) {
+  for (let i = 0; ; i++) {
+    try {
+      rmSync(target, { recursive: true, force: true });
+      return;
+    } catch (err) {
+      if (i >= tries - 1) throw err;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+    }
+  }
+}
+
+// —— 设置项注册处：以后新增设置项在这里加 ——
+
+const items = [shortcutItem];
+
+export async function runSetup({ uninstall = false, platform: plat = platform(), desktop = false } = {}) {
+  console.log(`[zcodepro] setup ${uninstall ? '卸载' : '安装'}本机集成${desktop && !uninstall ? '（含桌面）' : ''}：`);
+  let failed = 0;
+  for (const item of items) {
+    if (!item.supported(plat)) {
+      console.log(`  · ${item.title}：当前平台（${plat}）暂不支持，跳过`);
+      continue;
+    }
+    try {
+      const res = uninstall ? item.uninstall(plat) : item.install(plat, { desktop });
+      if (res && res.skipped) console.log(`  · ${item.title}：${res.skipped}`);
+      else console.log(`  ✓ ${item.title}：${res && res.detail ? res.detail : '完成'}`);
+    } catch (err) {
+      failed++;
+      console.error(`  ✗ ${item.title}：${err?.message || err}`);
+    }
+  }
+  console.log(uninstall ? '' : '  撤销：zcode-pro setup --uninstall');
+  if (failed) process.exitCode = 1;
+}

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/src/inject/core.js

@@ -617,11 +617,32 @@ const en = {
 };
 
 // 界面语言：与官方 IntlProvider 的解析一致——先读应用的 localStorage 偏好
-// （zcode-locale-preference：zh-CN/en-US/system），'system' 或读取失败时回退 navigator.language
+// （zcode-locale-preference：zh-CN/en-US/system），显式偏好直接生效；'system' 或未设置时
+// 官方在主进程用系统首选语言解析（macOS 上可能与渲染进程的 navigator.language 不一致：
+// 系统是中文而 Chromium 报 en-US，导致注入界面误判成英文）。这里通过 preload 暴露的
+// window.zcode.getSystemLocale()（IPC，异步）取主进程结果并缓存；取回前先按
+// navigator.language 兜底，避免阻塞首次渲染。
+let cachedSystemLocale = null; // 'zh-CN' | 'en-US' | null（尚未取回）
+
+export function startLocaleResolver() {
+  if (cachedSystemLocale !== null) return; // 已取回则跳过，避免重复 IPC（index.js 会调用两次）
+  const get = typeof window !== 'undefined' ? window.zcode?.getSystemLocale : null;
+  if (typeof get !== 'function') return;
+  Promise.resolve(get())
+    .then((locale) => {
+      if (typeof locale === 'string' && locale) {
+        // 与主进程解析一致：zh 开头视为中文，其余视为英文（兼容 'zh-Hans-CN' 等原始格式）
+        cachedSystemLocale = locale.toLowerCase().startsWith('zh') ? 'zh-CN' : 'en-US';
+      }
+    })
+    .catch(() => { /* 取回失败：沿用 navigator.language 兜底 */ });
+}
+
 export function isZhLocale() {
   let pref = null;
   try { pref = window.localStorage.getItem('zcode-locale-preference'); } catch { /* ignore */ }
   if (pref === 'zh-CN' || pref === 'en-US') return pref === 'zh-CN';
+  if (cachedSystemLocale) return cachedSystemLocale === 'zh-CN';
   return /^zh/i.test(navigator.language || 'zh-CN');
 }
 

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/src/inject/index.js

@@ -1,6 +1,6 @@
 // ZCode Pro 注入脚本入口（由 esbuild 打包为 dist/inject.js，launcher 拼上启动参数后注入页面）。
 // 幂等守卫：页面刷新/重复注入时只初始化一次。
-import { observeRadixPopups } from './core.js';
+import { observeRadixPopups, startLocaleResolver } from './core.js';
 import { handleProjectMenu } from './features/project-menu.js';
 import { handleFileMenu } from './features/file-menu.js';
 import { startImageMenu } from './features/image-menu.js';
@@ -23,10 +23,15 @@ import { ensureStyle } from './ui.js';
   if (window.__zcodeproInjected) return;
   window.__zcodeproInjected = true;
 
+  // 尽早取回系统语言（异步 IPC）：system 偏好下 macOS 的 navigator.language 可能与
+  // 实际不符；start() 里会再调一次，覆盖 preload 桥未就绪的情况
+  try { startLocaleResolver(); } catch { /* ignore */ }
+
   // 注意：本脚本可能在 document start 阶段执行（head 尚未就绪），
   // 因此所有 DOM 操作都推迟到 DOMContentLoaded 之后。
   const start = () => {
     ensureStyle();
+    try { startLocaleResolver(); } catch { /* ignore */ }
     observeRadixPopups((content) => {
       try { handleProjectMenu(content); } catch { /* 单个功能失败不影响其他 */ }
       try { handleFileMenu(content); } catch { /* ignore */ }

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/zcode_pro/__init__.py

@@ -1,3 +1,3 @@
 """ZCode Pro 的 PyPI 安装包：内置 Node 应用源码，通过 zcode-pro 命令启动。"""
 
-__version__ = "0.16.0"
+__version__ = "0.17.0"

{zcode_pro-0.16.0 → zcode_pro-0.17.0}/zcode_pro/cli.py

@@ -51,9 +51,22 @@ def _find_zcode_binary() -> str | None:
     return None
 
 
+def _runtime_ok(zcode_bin: str) -> bool:
+    """预检 ZCode 自带运行时是否可用：注册表等来源找到的可执行文件可能不完整
+    （缺 resources/ICU 数据等），以 Node 模式跑不起来就回退系统 node。"""
+    env = dict(os.environ, ELECTRON_RUN_AS_NODE="1")
+    try:
+        return subprocess.run(
+            [zcode_bin, "-e", "process.exit(0)"],
+            env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        ).returncode == 0
+    except OSError:
+        return False
+
+
 def main() -> int:
     zcode_bin = _find_zcode_binary()
-    if zcode_bin:
+    if zcode_bin and _runtime_ok(zcode_bin):
         # 用 ZCode 内置的 Node 运行时执行启动器（ELECTRON_RUN_AS_NODE 使其表现为纯 Node）
         env = dict(os.environ, ELECTRON_RUN_AS_NODE="1")
         return subprocess.run([zcode_bin, str(CLI_MJS), *sys.argv[1:]], env=env).returncode