zcode-pro 0.17.1 → 0.18.0

package/src/host/helper.mjs

@@ -3,19 +3,20 @@
 // 仅绑定 127.0.0.1，并通过每次启动随机生成的 token 鉴权。
 
 import { createServer } from 'node:http';
-import { execFile, spawn } from 'node:child_process';
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { mkdtemp } from 'node:fs/promises'; // 注意：fs 的 mkdtemp 是回调版，await 它会把 undefined 当回调
 import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readSettings, writeSettingsAtomic, remapSettingsPaths, isProjectOpenInTabs } from './settings.mjs';
 import { taskIndexPath, probeTaskIndexWritable, remapTaskIndexPaths, taskIndexDriverAvailable, listOverriddenTitles, listTaskWorkspaceMap } from './taskIndex.mjs';
 import { pickFolderSystem } from './pickFolder.mjs';
 import { reorderWorkspaceTasks, reorderGroupMembers } from './taskOrder.mjs';
-import { webdavRequest, webdavPutWithMkcol, webdavHttpText } from './webdav.mjs';
+import { webdavRequest, webdavPutWithMkcol, webdavHttpText, parseWebdavListing, findCurl } from './webdav.mjs';
+import { resolveZcodeExecutable } from './paths.mjs';
 
-const VERSION = '0.17.1';
+const VERSION = '0.18.0';
 
 // 全局提示词固定在用户主目录：官方加载器按 HOME/USERPROFILE 拼 .zcode/AGENTS.md，
 // 不读 ZCODE_DATA_BASE_DIR（数据根迁走时全局指令仍在原位）。
@@ -38,8 +39,10 @@ function defaultHeadroomFile() {
   return join(homedir(), '.zcode', 'headroom.json');
 }
 
-// 本插件市场（zcode-plugins 仓库）在 ZCode CLI 数据目录里的落点
+// 本插件市场（zcode-plugins 仓库）在 ZCode CLI 数据目录里的落点。
+// 市场未添加时（新机器）从这里自动补装，免得“安装”按钮因市场缺失永远失败。
 const ZCODE_PLUGINS_MARKETPLACE = 'duanluan-zcode-plugins';
+const ZCODE_PLUGINS_MARKETPLACE_SOURCE = 'duanluan/zcode-plugins';
 
 function cliPluginsDir() {
   return join(homedir(), '.zcode', 'cli', 'plugins');
@@ -74,6 +77,7 @@ export function defaultConfig() {
       listItemSpacing: null,  // 列表项之间的间距（应用默认 6px）
       quoteCodeSpacing: null, // 引用/代码块上下留白（应用默认 16px，my-4）
       lineHeight: null,       // 回答行高，倍数（应用默认 1.75）
+      thinkingLineHeight: null, // 思考行高，倍数（应用默认 1.5）
       codeLineHeight: null,    // 代码块行高，倍数（应用默认 12px 字号 × 20px 行盒，约 1.65）
       tableSpacing: null,      // 表格上下边距（未设置时跟随段落间距）
       tableCellPaddingV: null, // 单元格上下边距（应用默认 3px）
@@ -88,9 +92,19 @@ export function defaultConfig() {
     },
     // 项目路径（规范化，无尾分隔符）→ 自定义别名。只影响界面渲染，不改动任何真实数据。
     aliases: {},
+    // headroom 启用开关的记忆（供应商 id → { proxy, direct }）：关闭时把走 headroom 的
+    // 供应商地址切回直连并记录下来，再次开启时按记录把地址切回代理
+    headroomRoutes: {},
     // HTTP 代理（http(s)://host:port）：helper 发起的网络访问走它——插件市场更新/安装
-    // （zcode CLI → git）、headroom 本体的检查更新与升级（pip）。空 = 不用代理。
+    // （zcode CLI → git）、headroom/rtk 的安装与升级（pip/GitHub）。空 = 不用代理。
     proxy: '',
+    // 代理生效范围（按用途开关）：plugins = 插件市场更新/安装/卸载；deps = 插件依赖
+    // 软件（headroom 与 rtk）的安装、检查更新与升级；sync = WebDAV 同步。同步默认
+    // 关闭——坚果云等国内网盘通常直连即可，代理停了同步会跟着失败
+    proxyScopes: { plugins: true, deps: true, sync: false },
+    // 开发模式（设置弹窗“调试”标签页）：开启后出现「重载」按钮，可在不重启
+    // ZCode 的情况下加载新代码（构建 → 换新启动器进程 → 各窗口自动刷新重注入）
+    devMode: false,
     // 设置同步（设置弹窗“同步”标签页，交互参考 Tampermonkey 的手动同步）：
     // 仅 WebDAV、仅在点击按钮时传输（type 字段预留多后端扩展，当前恒为 webdav）。
     // url 为 WebDAV 服务器地址；dir 为其下的上传目录（默认 zcode-pro，避免直接
@@ -126,6 +140,12 @@ export function loadConfig(configFile) {
       features: { ...defaultConfig().features, ...(saved.features || {}) },
       styles: { ...defaultConfig().styles, ...(saved.styles && typeof saved.styles === 'object' ? saved.styles : {}) },
       aliases: { ...((saved.aliases && typeof saved.aliases === 'object') ? saved.aliases : {}) },
+      headroomRoutes: { ...((saved.headroomRoutes && typeof saved.headroomRoutes === 'object' && !Array.isArray(saved.headroomRoutes)) ? saved.headroomRoutes : {}) },
+      proxyScopes: mergeProxyScopes(saved.proxyScopes),
+      devMode: saved.devMode === true,
+      // devActive 每次读取时重算（保存时会随配置一起写入文件，但读取方不用保存的值）：
+      // 开发模式生效 = 配置开关或启动器带 ZCODEPRO_DEV=1，设置弹窗据此决定是否显示“调试”标签页（普通用户不可见）
+      devActive: saved.devMode === true || process.env.ZCODEPRO_DEV === '1',
       sync: mergeSyncConfig(saved.sync),
     };
   } catch {
@@ -186,12 +206,16 @@ function readBody(req) {
   });
 }
 
-// 软件代理（设置弹窗“代理”标签页）：helper 发起的网络访问（zcode CLI→git、pip）
-// 统一走这里；startHelper 启动时读配置，保存代理时即时更新
+// 软件代理（设置弹窗“代理”标签页）：helper 发起的网络访问（zcode CLI→git、pip、
+// WebDAV 同步）按用途（proxyScopes）走这里；startHelper 启动时读配置，
+// 保存代理地址或范围开关时即时更新
 let activeProxyUrl = '';
+let activeProxyScopes = { plugins: true, deps: true, sync: false };
 
-function proxyEnv(extra = {}) {
-  if (!activeProxyUrl) return extra;
+// scope：'plugins'（插件市场）/ 'deps'（headroom、rtk）/ 'sync'（WebDAV 同步）；
+// 'none' 表示这次调用与下载无关（headroom 生命周期钩子等），永不注入下载代理
+function proxyEnv(extra = {}, scope = 'deps') {
+  if (scope === 'none' || !activeProxyUrl || !activeProxyScopes[scope]) return extra;
   return {
     HTTP_PROXY: activeProxyUrl, HTTPS_PROXY: activeProxyUrl,
     http_proxy: activeProxyUrl, https_proxy: activeProxyUrl,
@@ -199,11 +223,19 @@ function proxyEnv(extra = {}) {
   };
 }
 
+// 该用途当前是否走代理：同步按 proxyUrl 参数传给 webdav（curl 路径用，
+// fetch 兜底路径不认代理环境变量）
+function proxyUrlFor(scope) {
+  return activeProxyScopes[scope] ? activeProxyUrl : '';
+}
+
 export function startHelper({ port, token, dataRoot, state, agentsFile = defaultAgentsFile() }) {
   const configFile = join(dataRoot, 'zcodepro.json');
   const settingsFile = join(dataRoot, 'v2', 'setting.json');
   migrateConfigOnce(configFile);
-  activeProxyUrl = String(loadConfig(configFile).proxy || '').trim();
+  const bootConfig = loadConfig(configFile);
+  activeProxyUrl = String(bootConfig.proxy || '').trim();
+  activeProxyScopes = { ...bootConfig.proxyScopes };
 
   const server = createServer(async (req, res) => {
     const url = new URL(req.url, `http://127.0.0.1:${port}`);
@@ -245,6 +277,16 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           }
           activeProxyUrl = current.proxy;
         }
+        if (body && typeof body === 'object' && body.proxyScopes && typeof body.proxyScopes === 'object') {
+          // 代理生效范围按单项提交（每个开关只改自己那项），即时生效
+          for (const k of ['plugins', 'deps', 'sync']) {
+            if (typeof body.proxyScopes[k] === 'boolean') current.proxyScopes[k] = body.proxyScopes[k];
+          }
+          activeProxyScopes = { ...current.proxyScopes };
+        }
+        if (body && typeof body === 'object' && typeof body.devMode === 'boolean') {
+          current.devMode = body.devMode;
+        }
         if (body && typeof body === 'object' && body.features && typeof body.features === 'object') {
           applyFeaturesPartial(current.features, body.features);
         }
@@ -373,7 +415,7 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           json(res, 500, { ok: false, code: 'vision-read', error: 'zcode-vision.json 不是合法 JSON' });
           return;
         }
-        json(res, 200, { ok: true, config: parsed, file });
+        json(res, 200, { ok: true, config: parsed, file, hook: findVisionHook(), pluginVersion: installedPluginVersion('zcode-vision') });
         return;
       }
       if (req.method === 'POST' && url.pathname === '/vision') {
@@ -421,10 +463,14 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         const dir = defaultRtkDir();
         const mode = readRtkMode(join(dir, 'mode'));
         const info = await rtkBinaryInfo();
+        // 已装插件探测：新版（≥1.3.0）钩子入口是跨平台 rtk-pretooluse.mjs，旧版是 .sh
+        const hook = findMarketplaceHook('rtk', join('hooks', 'rtk-pretooluse.mjs'))
+          || findMarketplaceHook('rtk', join('hooks', 'rtk-pretooluse.sh'));
         // rtkBinaryInfo 走 PATH 命中时 binPath 是命令名；换绝对路径用于面板展示
         json(res, 200, {
           ok: true, mode, whitelist: readRtkWhitelist(join(dir, 'whitelist')),
-          dir, ...readRtkBuiltinWhitelist(), ...info,
+          dir, hook, pluginVersion: installedPluginVersion('rtk'),
+          ...readRtkBuiltinWhitelist(), ...info,
           binPath: info.binPath ? (rtkFindBin() || info.binPath) : null,
         });
         return;
@@ -498,12 +544,15 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           json(res, 500, { ok: false, code: 'headroom-read', error: '读取 headroom.json 失败: ' + (err?.message || err) });
           return;
         }
-        const hook = findMarketplaceHook('headroom', join('hooks', 'ensure-proxy.sh'));
+        // 已安装探测：新版（≥1.2.0）钩子入口是跨平台 ensure-proxy.mjs，旧版是 ensure-proxy.sh
+        const hook = findMarketplaceHook('headroom', join('hooks', 'ensure-proxy.mjs'))
+          || findMarketplaceHook('headroom', join('hooks', 'ensure-proxy.sh'));
         // 插件版本取自缓存目录名（…/headroom/1.0.2/hooks/…）
         const vm = hook ? /[/\\]headroom[/\\](\d+(?:\.\d+){0,3})[/\\]/.exec(hook) : null;
         json(res, 200, {
           ok: true, config, file, hook,
           pluginVersion: vm ? vm[1] : null,
+          usage: headroomUsageScan(dataRoot),
           ...(await headroomBinaryInfo()),
         });
         return;
@@ -563,6 +612,15 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
             return;
           }
           output = r.output;
+        } else if (body && typeof body.usage === 'boolean') {
+          // 启用开关：只改 ZCode 供应商配置里的地址（走/不走本地压缩代理），不动代理进程
+          const r = setHeadroomUsage(dataRoot, configFile, body.usage);
+          if (!r.ok) {
+            json(res, 500, { ok: false, code: r.code, error: r.error });
+            return;
+          }
+          json(res, 200, { ok: true, usage: headroomUsageScan(dataRoot), changed: r.changed });
+          return;
         } else if (body && body.cancelUpgrade === true) {
           json(res, 200, { ok: true, upgrade: cancelHeadroomUpgrade() });
           return;
@@ -598,7 +656,7 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
             return;
           }
         } else {
-          json(res, 400, { ok: false, code: 'invalid-request', error: 'body 需包含 action/backend/power/interval 之一' });
+          json(res, 400, { ok: false, code: 'invalid-request', error: 'body 需包含 action/backend/power/usage/interval 之一' });
           return;
         }
         let config = null;
@@ -606,6 +664,41 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         json(res, 200, { ok: true, output, config });
         return;
       }
+      // —— 开发模式重载（设置弹窗“调试”标签页）：不重启 ZCode 换新代码 ——
+      if (req.method === 'POST' && url.pathname === '/dev/reload') {
+        if (loadConfig(configFile).devMode !== true && process.env.ZCODEPRO_DEV !== '1') {
+          json(res, 404, { ok: false, error: 'not found' });
+          return;
+        }
+        // 源码目录（有 package.json 与 esbuild）先构建，安装副本没有构建环境则跳过
+        let built = false;
+        const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+        const esbuildBin = [join(repoRoot, 'node_modules', 'esbuild', 'bin', 'esbuild'),
+          join(repoRoot, 'node_modules', 'esbuild', 'bin', 'esbuild.exe')]
+          .find((p) => existsSync(p)) || '';
+        if (esbuildBin) {
+          try {
+            const b = spawnSync(esbuildBin, ['src/inject/index.js', '--bundle',
+              '--format=iife', '--target=chrome120', '--outfile=dist/inject.js'],
+              { cwd: repoRoot, timeout: 60000, encoding: 'utf8', windowsHide: true });
+            built = !b.error && b.status === 0;
+          } catch { /* 构建失败也继续交接（可能只改了 host 端代码） */ }
+        }
+        json(res, 200, { ok: true, built });
+        // 先应答再交接：拉起新的启动器进程（同一入口与参数，读新构建的 inject.js
+        // 与新 host 代码），本进程随后退出。页面刷新由注入脚本的换代守卫触发
+        // （见 src/inject/index.js）；新进程的 helper 端口占用靠监听重试等待
+        setTimeout(() => {
+          try {
+            const child = spawn(process.execPath, process.argv.slice(1), {
+              detached: true, stdio: 'ignore', windowsHide: true, env: process.env,
+            });
+            child.unref();
+          } catch { /* 拉不起来就只能等下次手动重启 */ }
+          setTimeout(() => process.exit(0), 250);
+        }, 150);
+        return;
+      }
       // —— 软件代理连通性检测：经 curl -x 走代理访问插件市场/本体升级实际要用的站点 ——
       if (req.method === 'POST' && url.pathname === '/proxy/test') {
         const body = await readBody(req);
@@ -639,11 +732,21 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           ['GitHub', 'https://github.com'],
           ['PyPI', pypiTarget],
         ];
+        // Windows 精简环境 PATH 可能不含 curl：与同步功能共用 findCurl（补测 System32）
+        const curlBin = findCurl();
         const results = [];
         for (const [name, targetUrl] of targets) {
           results.push(await new Promise((resolveT) => {
             const started = Date.now();
-            execFile('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '8', '-x', proxy, targetUrl],
+            if (!curlBin) {
+              resolveT({ name, httpCode: null, ms: null, ok: false, error: '未找到 curl 命令' });
+              return;
+            }
+            // -I 只取响应头：连通性检测不必下载整页（github 主页数百 KB，
+            // 经慢代理节点 8 秒必然超时误报）。-o 丢弃输出用各平台的空设备
+            // （Windows 上 /dev/null 是普通路径且目录不存在，必须用 NUL）
+            const nullDev = process.platform === 'win32' ? 'NUL' : '/dev/null';
+            execFile(curlBin, ['-sI', '-o', nullDev, '-w', '%{http_code}', '--max-time', '8', '-x', proxy, targetUrl],
               { timeout: 10000, windowsHide: true }, (err, stdout) => {
                 if (err && err.code === 'ENOENT') {
                   resolveT({ name, httpCode: null, ms: null, ok: false, error: '未找到 curl' });
@@ -699,7 +802,7 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           return;
         }
         const config = loadConfig(configFile);
-        const r = await runSettingsSync({ direction, dataRoot, configFile, config, proxyUrl: activeProxyUrl });
+        const r = await runSettingsSync({ direction, dataRoot, configFile, config, proxyUrl: proxyUrlFor('sync') });
         if (r.error) {
           json(res, r.status || 500, { ok: false, code: r.code || 'sync-run', error: r.error });
           return;
@@ -707,8 +810,132 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         json(res, 200, { ok: true, direction, applied: r.applied, sync: loadConfig(configFile).sync });
         return;
       }
+      // —— 同步连通性测试（“测试”按钮）：用表单当前值逐步验证（可先测再存），不写入配置文件 ——
+      if (req.method === 'POST' && url.pathname === '/sync/test') {
+        const body = await readBody(req);
+        const v = validateSyncForm(body?.sync || {});
+        if (v.error) {
+          json(res, 400, { ok: false, code: 'sync-invalid', error: v.error });
+          return;
+        }
+        // dir 缺省时沿用已保存的值
+        const sync = { ...loadConfig(configFile).sync, ...v.sync };
+        const r = await runSyncTest({ sync, proxyUrl: proxyUrlFor('sync') });
+        if (r.error) {
+          json(res, r.status || 500, { ok: false, code: r.code || 'sync-test', error: r.error });
+          return;
+        }
+        json(res, 200, { ok: true, targets: r.targets, fileCount: r.fileCount });
+        return;
+      }
+      // —— 云端版本列表（“从云端下载”先弹文件选择，任选一个版本恢复）——
+      if (req.method === 'POST' && url.pathname === '/sync/versions') {
+        const config = loadConfig(configFile);
+        const sync = config.sync;
+        if (!sync.url || !/^https?:\/\/\S+$/.test(sync.url)) {
+          json(res, 400, { ok: false, code: 'sync-not-configured', error: '请先填写 WebDAV URL 并保存' });
+          return;
+        }
+        const r = await listSyncVersions(sync, proxyUrlFor('sync'));
+        if (r.error) {
+          json(res, r.status || 500, { ok: false, code: r.code || 'sync-request', error: r.error });
+          return;
+        }
+        json(res, 200, { ok: true, files: r.files });
+        return;
+      }
+      // —— 按文件操作（文件名必须整串匹配 SYNC_VERSION_RE）：apply 导入 / delete 删除 / export 保存到磁盘 ——
+      if (req.method === 'POST' && url.pathname.startsWith('/sync/version/')) {
+        const action = url.pathname.slice('/sync/version/'.length);
+        if (!['apply', 'delete', 'export'].includes(action)) {
+          json(res, 404, { ok: false, error: 'not found' });
+          return;
+        }
+        const body = await readBody(req);
+        const file = typeof body?.file === 'string' ? body.file : '';
+        if (!SYNC_VERSION_RE.test(file)) {
+          json(res, 400, { ok: false, code: 'sync-file-invalid', error: '文件名不合法（只能是同步目录里的 zcode-pro 备份文件）' });
+          return;
+        }
+        const config = loadConfig(configFile);
+        const sync = config.sync;
+        if (!sync.url || !/^https?:\/\/\S+$/.test(sync.url)) {
+          json(res, 400, { ok: false, code: 'sync-not-configured', error: '请先填写 WebDAV URL 并保存' });
+          return;
+        }
+        const remoteMissing = () => json(res, 404, { ok: false, code: 'sync-remote-missing', error: `云端文件 ${file} 不存在（可能已被删除）` });
+        if (action === 'apply') {
+          const remote = await fetchSyncNamedDoc(sync, proxyUrlFor('sync'), file);
+          if (remote.error) {
+            json(res, remote.status || 500, { ok: false, code: remote.code, error: remote.error });
+            return;
+          }
+          if (remote.missing) {
+            remoteMissing();
+            return;
+          }
+          const kind = file.startsWith('model') ? 'model' : 'zcodepro';
+          sync.lastPullAt = Date.now();
+          const r = applySyncDocs({ docs: { [kind]: remote.doc.data }, dataRoot, configFile, config, sync });
+          json(res, 200, { ok: true, applied: r.applied, sync: loadConfig(configFile).sync });
+          return;
+        }
+        if (action === 'delete') {
+          const r = await webdavRequest({ method: 'DELETE', url: syncFileUrlByName(sync, file), login: sync.login, password: sync.password, proxyUrl: proxyUrlFor('sync'), timeoutMs: 30000 });
+          if (!r.ok) {
+            json(res, 502, { ok: false, code: 'sync-request', error: r.error });
+            return;
+          }
+          if (r.httpCode === 404) {
+            remoteMissing();
+            return;
+          }
+          if (r.httpCode < 200 || r.httpCode >= 300) {
+            json(res, 502, { ok: false, code: 'sync-request', error: webdavHttpText(r.httpCode) });
+            return;
+          }
+          json(res, 200, { ok: true });
+          return;
+        }
+        // export：把云端文件原样保存到本机（不做信封校验，取回什么存什么）
+        const r = await webdavRequest({ method: 'GET', url: syncFileUrlByName(sync, file), login: sync.login, password: sync.password, proxyUrl: proxyUrlFor('sync'), timeoutMs: 60000 });
+        if (!r.ok) {
+          json(res, 502, { ok: false, code: 'sync-request', error: r.error });
+          return;
+        }
+        if (r.httpCode === 404 || r.httpCode === 409) {
+          remoteMissing();
+          return;
+        }
+        if (r.httpCode < 200 || r.httpCode >= 300) {
+          json(res, 502, { ok: false, code: 'sync-request', error: webdavHttpText(r.httpCode) });
+          return;
+        }
+        if (r.body.length > 8 * 1024 * 1024) {
+          json(res, 400, { ok: false, code: 'sync-remote-invalid', error: `云端 ${file} 超过 8MB，已拒绝保存` });
+          return;
+        }
+        // 系统目录选择器选保存位置；环境没有选择器时退回用户主目录，用户取消则中止
+        const picked = await pickFolderSystem(homedir(), '选择保存位置');
+        let target = '';
+        if (picked && typeof picked.path === 'string' && picked.path) target = join(picked.path, file);
+        else if (picked && picked.unavailable) target = join(homedir(), file);
+        else {
+          json(res, 200, { ok: false, code: 'export-cancelled', error: '已取消' });
+          return;
+        }
+        try {
+          writeFileSync(target, r.body, 'utf8');
+        } catch (err) {
+          json(res, 500, { ok: false, code: 'sync-export', error: `写入 ${target} 失败: ${err?.message || err}` });
+          return;
+        }
+        json(res, 200, { ok: true, path: target });
+        return;
+      }
       // —— zcode-plugins 市场更新：读状态（带 30 分钟节流的市场同步）与执行更新 ————
       if (req.method === 'GET' && url.pathname === '/plugins/status') {
+        await ensureZcodePluginsMarketplace();
         if (Date.now() - lastMarketplaceSync > 30 * 60 * 1000) {
           await runZcodeCli(['plugins', 'marketplace', 'update', ZCODE_PLUGINS_MARKETPLACE], 60000);
           lastMarketplaceSync = Date.now();
@@ -726,6 +953,8 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         // name 指定时只处理该插件：已装且有更新则更新，未装则安装（各插件面板的单插件操作）
         const only = typeof body?.name === 'string' && body.name.trim() ? body.name.trim() : null;
         const steps = [];
+        const added = await ensureZcodePluginsMarketplace();
+        if (added) steps.push({ step: 'marketplace add', ok: added.ok, output: added.output || added.error });
         const sync = await runZcodeCli(['plugins', 'marketplace', 'update', ZCODE_PLUGINS_MARKETPLACE], 60000);
         lastMarketplaceSync = Date.now();
         steps.push({ step: 'marketplace update', ok: sync.ok, output: sync.output });
@@ -742,7 +971,10 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
               const r = await runZcodeCli(['plugins', 'update', `${p.name}@${ZCODE_PLUGINS_MARKETPLACE}`], 120000);
               steps.push({ step: `update ${p.name}`, ok: r.ok, output: r.output });
               if (r.ok) updated += 1;
-            } else if (!p.installed && (body?.installMissing || only)) {
+            } else if (!p.installed && only) {
+              // 安装只走单插件入口（name 指定＝各面板的安装卡）：
+              // 全量「检查并更新」/启动自动更新只升级已装插件——卸载必须被尊重，
+              // 未装插件一律由用户在各 tab 显式点安装
               const r = await runZcodeCli(['plugins', 'install', `${p.name}@${ZCODE_PLUGINS_MARKETPLACE}`], 120000);
               steps.push({ step: `install ${p.name}`, ok: r.ok, output: r.output });
               if (r.ok) updated += 1;
@@ -760,9 +992,24 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
     }
   });
 
+  // 端口被占时重试：开发重载的交接窗口内，旧进程退出略晚于新进程启动，
+  // 新进程在这里等它让出端口（最多 20 秒），而不是启动失败
   return new Promise((resolveStarted, rejectStarted) => {
-    server.once('error', rejectStarted);
-    server.listen(port, '127.0.0.1', () => resolveStarted(server));
+    let attempts = 0;
+    const tryListen = () => {
+      attempts += 1;
+      server.removeAllListeners('error');
+      server.once('error', (err) => {
+        if (err && err.code === 'EADDRINUSE' && attempts < 40) {
+          try { server.close(); } catch { /* ignore */ }
+          setTimeout(tryListen, 500);
+          return;
+        }
+        rejectStarted(err);
+      });
+      server.listen(port, '127.0.0.1', () => resolveStarted(server));
+    };
+    tryListen();
   });
 }
 
@@ -785,6 +1032,18 @@ function clampInt(v, min, max, dflt) {
 
 // —— 设置同步（“同步”标签页）的实现 ——
 
+// loadConfig 时把磁盘上的 proxyScopes 按默认值归一（只收布尔，缺的补默认：
+// 插件市场/依赖软件开、同步关）
+function mergeProxyScopes(saved) {
+  const d = defaultConfig().proxyScopes;
+  const s = (saved && typeof saved === 'object') ? saved : {};
+  return {
+    plugins: typeof s.plugins === 'boolean' ? s.plugins : d.plugins,
+    deps: typeof s.deps === 'boolean' ? s.deps : d.deps,
+    sync: typeof s.sync === 'boolean' ? s.sync : d.sync,
+  };
+}
+
 // loadConfig 时把磁盘上的 sync 段按默认值归一（长度限幅、时间戳只收数字）。
 // 当前唯一后端是 WebDAV，type 一律归为 webdav（不做“禁用”态：同步本就仅手动触发）
 function mergeSyncConfig(saved) {
@@ -832,6 +1091,18 @@ function validateSyncForm(raw) {
 // 上传/下载按勾选逐文件进行，可单独覆盖其中一项 ——
 const SYNC_FILES = { zcodepro: 'zcodepro.json', model: 'model.json' };
 
+// 云端版本文件名的合法形态：固定名（zcodepro.json / model.json，始终是最新一版）
+// 或组名 + ISO 时间戳（冒号换成 -，部分网盘文件名不允许冒号），如
+// zcodepro-2025-10-25T14-59-53-169Z.json。按文件操作的端点（导入/删除/导出）
+// 都先整串匹配该正则，杜绝 ../ 之类的路径注入
+const SYNC_VERSION_RE = /^(zcodepro|model)(?:-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)?\.json$/;
+
+// 历史版本文件名（同一次上传的各组共用同一时间戳，像“一次备份”而不是两个时刻）
+function syncVersionName(kind, ts) {
+  const iso = ts.toISOString(); // 2025-10-25T14:59:53.169Z
+  return `${kind}-${iso.slice(0, 19).replace(/:/g, '-')}-${iso.slice(20, 23)}Z.json`;
+}
+
 // 云端目录 = URL（服务器地址，容忍尾斜杠）+ 上传目录（默认 zcode-pro，可多级）。
 // 目录段逐段编码，中文/空格等文件夹名也能正确落到地址里
 function syncBaseDir(sync) {
@@ -846,6 +1117,25 @@ function syncFileUrl(sync, kind) {
   return syncBaseDir(sync) + '/' + SYNC_FILES[kind];
 }
 
+// 拼出云端目录里某个已校验文件名（固定名或历史版本）的完整地址
+function syncFileUrlByName(sync, fileName) {
+  return syncBaseDir(sync) + '/' + encodeURIComponent(fileName);
+}
+
+// 信封校验：云端文件必须是 { app: 'zcode-pro', kind, format, data } 且组别与文件名
+// 前缀一致；4MB 上限挡住异常大文件
+function parseSyncEnvelope(body, kind, label) {
+  if (body.length > 4 * 1024 * 1024) {
+    return { error: `云端 ${label} 超过 4MB，已拒绝应用`, code: 'sync-remote-invalid', status: 400 };
+  }
+  let doc = null;
+  try { doc = JSON.parse(body); } catch { /* 落到统一报错 */ }
+  if (!doc || typeof doc !== 'object' || doc.app !== 'zcode-pro' || doc.kind !== kind || !doc.data || typeof doc.data !== 'object') {
+    return { error: `云端 ${label} 不是 zcode-pro 的同步数据（可能被其他内容占用），请删除该文件或换一个目录`, code: 'sync-remote-invalid', status: 409 };
+  }
+  return { doc };
+}
+
 // 读云端某个同步文件：{ doc } 成功 | { missing } 云端没有该组数据 | { error, code, status } 失败。
 // 文件里已是其他内容（或组别不符）时拒绝覆盖；4MB 上限挡住异常大文件。
 async function fetchSyncDoc(sync, proxyUrl, kind) {
@@ -856,15 +1146,19 @@ async function fetchSyncDoc(sync, proxyUrl, kind) {
   if (r.httpCode === 404 || r.httpCode === 409) return { missing: true };
   if (r.httpCode < 200 || r.httpCode >= 300) return { error: webdavHttpText(r.httpCode), code: 'sync-request', status: 502 };
   if (!r.body.trim()) return { missing: true }; // 个别网盘对不存在的文件返回 200 空内容
-  if (r.body.length > 4 * 1024 * 1024) {
-    return { error: `云端 ${SYNC_FILES[kind]} 超过 4MB，已拒绝应用`, code: 'sync-remote-invalid', status: 400 };
-  }
-  let doc = null;
-  try { doc = JSON.parse(r.body); } catch { /* 落到统一报错 */ }
-  if (!doc || typeof doc !== 'object' || doc.app !== 'zcode-pro' || doc.kind !== kind || !doc.data || typeof doc.data !== 'object') {
-    return { error: `云端已存在其他内容的 ${SYNC_FILES[kind]}，请换一个目录`, code: 'sync-remote-invalid', status: 409 };
-  }
-  return { doc };
+  return parseSyncEnvelope(r.body, kind, SYNC_FILES[kind]);
+}
+
+// 读云端某个版本文件（固定名或带时间戳的历史版本，文件名需已过 SYNC_VERSION_RE）。
+// 返回值约定与 fetchSyncDoc 相同；kind 由文件名前缀决定
+async function fetchSyncNamedDoc(sync, proxyUrl, fileName) {
+  const kind = fileName.startsWith('model') ? 'model' : 'zcodepro';
+  const r = await webdavRequest({ method: 'GET', url: syncFileUrlByName(sync, fileName), login: sync.login, password: sync.password, proxyUrl });
+  if (!r.ok) return { error: r.error, code: 'sync-request', status: 502 };
+  if (r.httpCode === 404 || r.httpCode === 409) return { missing: true };
+  if (r.httpCode < 200 || r.httpCode >= 300) return { error: webdavHttpText(r.httpCode), code: 'sync-request', status: 502 };
+  if (!r.body.trim()) return { missing: true };
+  return parseSyncEnvelope(r.body, kind, fileName);
 }
 
 async function runSettingsSync({ direction, dataRoot, configFile, config, proxyUrl }) {
@@ -880,8 +1174,10 @@ async function runSettingsSync({ direction, dataRoot, configFile, config, proxyU
     : runSyncPull({ dataRoot, configFile, config, sync, proxyUrl });
 }
 
-// 上传：每组独立一个云端文件（zcodepro.json / model.json），勾选几组写几个；
-// 写前预读只为确认没顶到别人的文件，自己的文件直接整份覆盖
+// 上传：每组独立一个云端文件（zcodepro.json / model.json，始终最新一版），勾选几组
+// 写几个；写前预读云端内容，别名与本机的合并后再写（合并规则见 mergeAliases），
+// 其余内容整份覆盖。同一份内容再写一个带时间戳的历史版本文件，供下载时任选版本
+// 恢复（旧版 zcode-pro 仍读固定名）
 async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
   const docs = {};
   if (sync.include.zcodepro) {
@@ -904,22 +1200,34 @@ async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
     return { code: 'sync-run', status: 400, error: '本机没有可同步的内容' };
   }
   const pushed = [];
+  const stamp = new Date(); // 各组共用同一时间戳，对应“一次备份”
   const dir = await mkdtemp(join(tmpdir(), 'zcodepro-sync-'));
   try {
     for (const kind of Object.keys(docs)) {
       const remote = await fetchSyncDoc(sync, proxyUrl, kind);
       if (remote.error) return remote;
-      const doc = { app: 'zcode-pro', kind, format: 1, savedAt: new Date().toISOString(), data: docs[kind] };
+      // 别名先与云端合并：本机没配过的条目从云端带上，别让这次上传把别的机器配的别名顶掉
+      if (kind === 'zcodepro' && remote.doc) {
+        const remoteAliases = sanitizeAliases(remote.doc.data?.aliases);
+        if (remoteAliases) docs.zcodepro.aliases = mergeAliases(docs.zcodepro.aliases, remoteAliases);
+      }
+      const doc = { app: 'zcode-pro', kind, format: 1, savedAt: stamp.toISOString(), data: docs[kind] };
       const docPath = join(dir, SYNC_FILES[kind]);
       writeFileSync(docPath, JSON.stringify(doc, null, 2), 'utf8');
-      const put = await webdavPutWithMkcol({
-        url: syncFileUrl(sync, kind), login: sync.login, password: sync.password,
+      const putUrl = (name) => webdavPutWithMkcol({
+        url: syncFileUrlByName(sync, name), login: sync.login, password: sync.password,
         uploadFile: docPath, proxyUrl, timeoutMs: 60000,
       });
+      const put = await putUrl(SYNC_FILES[kind]);
       if (!put.ok) return { code: 'sync-request', status: 502, error: put.error };
       if (put.httpCode < 200 || put.httpCode >= 300) {
         return { code: 'sync-request', status: 502, error: webdavHttpText(put.httpCode) };
       }
+      const putVersion = await putUrl(syncVersionName(kind, stamp));
+      if (!putVersion.ok) return { code: 'sync-request', status: 502, error: putVersion.error };
+      if (putVersion.httpCode < 200 || putVersion.httpCode >= 300) {
+        return { code: 'sync-request', status: 502, error: webdavHttpText(putVersion.httpCode) };
+      }
       pushed.push(kind);
     }
   } finally {
@@ -931,8 +1239,8 @@ async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
 }
 
 // 下载：把云端所选组应用到本机（各组独立文件，勾选几组读几组，可只覆盖模型设置）。
-// 覆盖前留 .zcodepro-backup 备份；zcodepro 组只覆盖功能/样式/别名/代理，
-// sync 配置与凭据始终保留本机的
+// 覆盖前留 .zcodepro-backup 备份；zcodepro 组覆盖功能/样式/代理，别名与本机的
+// 合并（合并规则见 mergeAliases）；sync 配置与凭据始终保留本机的
 async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
   // 先把勾选组的云端数据全部读到（任何一组读取失败都不动本机文件），再逐组应用
   const docs = {};
@@ -945,6 +1253,14 @@ async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
   if (!Object.keys(docs).length) {
     return { code: 'sync-remote-missing', status: 404, error: '云端没有同步数据，请先在其他电脑上传' };
   }
+  sync.lastPullAt = Date.now();
+  return applySyncDocs({ docs, dataRoot, configFile, config, sync });
+}
+
+// 把云端读到的各组数据落到本机（runSyncPull 与按文件的历史版本导入共用）：
+// zcodepro 组覆盖功能/样式/代理（sync 配置与凭据保留本机的），别名与本机的合并，
+// model 组覆盖 v2/config.json 的 provider 与 provider_config.json；覆盖前都留备份
+function applySyncDocs({ docs, dataRoot, configFile, config, sync }) {
   const applied = [];
   const backupFile = (p) => {
     try { if (existsSync(p)) copyFileSync(p, p + '.zcodepro-backup'); } catch { /* 备份失败不阻塞 */ }
@@ -954,15 +1270,16 @@ async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
     writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
     renameSync(tmp, p);
   };
-  sync.lastPullAt = Date.now();
 
   if (docs.zcodepro) {
     const rz = docs.zcodepro;
     const next = loadConfig(configFile);
     applyFeaturesPartial(next.features, rz.features);
     next.styles = applyStylesPartial(next.styles, rz.styles);
-    const aliases = sanitizeAliases(rz.aliases);
-    if (aliases) next.aliases = aliases;
+    // 别名与本机的合并（本机配过的优先），不再整份替换——各机器项目路径不同，
+    // 合并后两边的别名都在，谁也不会被对方的同步顶掉
+    const remoteAliases = sanitizeAliases(rz.aliases);
+    if (remoteAliases) next.aliases = mergeAliases(next.aliases, remoteAliases);
     if (typeof rz.proxy === 'string') {
       const v = rz.proxy.trim();
       if (v === '' || /^https?:\/\/\S+:\d+$/.test(v)) next.proxy = v;
@@ -988,10 +1305,79 @@ async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
     }
     applied.push('model');
   }
+  // 没动 zcodepro.json 时，lastPullAt 也要写入配置文件（动了则已随 next 一起保存）
   if (!applied.includes('zcodepro')) saveConfig(configFile, config);
   return { applied };
 }
 
+// 同步“测试”按钮的实现：分三步验证，任一步失败即止（后续步骤没有意义）。
+// ① 连接与凭据：PROPFIND 上传目录——404/409 只说明目录还没建，能拿到 HTTP 响应
+// 且不是 401/403 即证明服务器可达、凭据可用（坚果云的应用密码可限定目录，
+// 探服务器根会误报）；② 上传目录：不存在时逐段 MKCOL 建出来再验（顺带验证写
+// 权限，与上传时的自动建目录一致）；③ 文件列表：PROPFIND Depth 1 数备份文件。
+// targets 的 step 供前端映射本地化步骤名（connect/dir/list）
+async function runSyncTest({ sync, proxyUrl }) {
+  const auth = { login: sync.login, password: sync.password, proxyUrl };
+  const targets = [];
+  const probe = async (step, run) => {
+    const started = Date.now();
+    const resp = await run();
+    const ok = resp.ok && resp.httpCode >= 200 && resp.httpCode < 300;
+    targets.push({
+      step, ok,
+      ms: Date.now() - started,
+      httpCode: resp.ok ? resp.httpCode : null,
+      error: ok ? '' : (resp.ok ? webdavHttpText(resp.httpCode) : resp.error),
+    });
+    return { ok, resp };
+  };
+  const baseDir = syncBaseDir(sync);
+  // ① 只要拿到响应且不是凭据问题就算连通（404/409 = 目录还没建，交给第②步处理）
+  const connect = await probe('connect', () => webdavRequest({ method: 'PROPFIND', url: baseDir, ...auth, timeoutMs: 20000, headers: ['Depth: 0'] }));
+  if (!connect.ok && connect.resp.ok && (connect.resp.httpCode === 404 || connect.resp.httpCode === 409)) {
+    // 目录缺失不算连接失败：改写第一步结果，继续建目录
+    targets[targets.length - 1] = { ...targets[targets.length - 1], ok: true, error: '' };
+  } else if (!connect.ok) {
+    return { targets };
+  }
+  // ② 目录不存在则逐段 MKCOL（已存在段 MKCOL 多半回 405，忽略），再 PROPFIND 验证
+  const dir = await probe('dir', async () => {
+    let r = connect.resp;
+    if (r.httpCode === 404 || r.httpCode === 409) {
+      try {
+        const u = new URL(baseDir);
+        let cur = u.origin;
+        for (const s of u.pathname.split('/').filter(Boolean)) {
+          cur += '/' + s;
+          await webdavRequest({ method: 'MKCOL', url: cur, ...auth, timeoutMs: 15000 });
+        }
+      } catch { /* URL 解析失败：交给下面的 PROPFIND 报错 */ }
+      r = await webdavRequest({ method: 'PROPFIND', url: baseDir, ...auth, timeoutMs: 20000, headers: ['Depth: 0'] });
+    }
+    return r;
+  });
+  if (!dir.ok) return { targets };
+  // ③ 列文件（Depth 1），数出同步目录里的备份文件个数
+  const list = await probe('list', () => webdavRequest({ method: 'PROPFIND', url: baseDir, ...auth, timeoutMs: 30000, headers: ['Depth: 1'] }));
+  if (!list.ok) return { targets };
+  const fileCount = parseWebdavListing(list.resp.body).filter((e) => SYNC_VERSION_RE.test(e.name)).length;
+  return { targets, fileCount };
+}
+
+// PROPFIND 云端同步目录，列出全部备份版本（固定名 + 带时间戳的历史）：
+// 按修改时间从新到旧（时间缺失的按文件名排后）；目录还不存在视为空列表
+async function listSyncVersions(sync, proxyUrl) {
+  const r = await webdavRequest({ method: 'PROPFIND', url: syncBaseDir(sync), login: sync.login, password: sync.password, proxyUrl, timeoutMs: 30000, headers: ['Depth: 1'] });
+  if (!r.ok) return { error: r.error, code: 'sync-request', status: 502 };
+  if (r.httpCode === 404 || r.httpCode === 409) return { files: [] };
+  if (r.httpCode < 200 || r.httpCode >= 300) return { error: webdavHttpText(r.httpCode), code: 'sync-request', status: 502 };
+  const files = parseWebdavListing(r.body)
+    .filter((e) => SYNC_VERSION_RE.test(e.name))
+    .map((e) => ({ name: e.name, size: e.size, lastModified: e.lastModified }));
+  files.sort((a, b) => ((b.lastModified || 0) - (a.lastModified || 0)) || b.name.localeCompare(a.name));
+  return { files };
+}
+
 // 别名表清洗（同步下载用）：只收 路径字符串 → 短字符串 的条目，数量限幅
 function sanitizeAliases(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
@@ -1006,6 +1392,26 @@ function sanitizeAliases(raw) {
   return out;
 }
 
+// 别名表合并（同步上传/下载共用）：取两边的并集，配过别名的条目优先——同一路径
+// 两边都配了别名时用本机的；只有一边配过时保留配过的那个。所以在一台机器上清除
+// 别名后，只要别的机器还配着，下次同步还会把这条带回来，两边都清掉才会真正消失。
+// 导出以便测试脚本直接驱动。
+export function mergeAliases(localRaw, remoteRaw) {
+  const out = {};
+  const put = (k, v) => {
+    if (typeof k !== 'string' || k.length > 500 || k.includes('\0')) return;
+    if (typeof v !== 'string' || !v || v.length > 200 || /[\r\n\0]/.test(v)) return;
+    out[k] = v;
+  };
+  const entries = (raw) => (raw && typeof raw === 'object' && !Array.isArray(raw)) ? Object.entries(raw) : [];
+  for (const [k, v] of entries(remoteRaw)) put(k, v);
+  for (const [k, v] of entries(localRaw)) {
+    // 本机配过的覆盖云端同路径条目；本机是空值（视为没配过）时不覆盖，云端配过的留下
+    if (v) put(k, v);
+  }
+  return out;
+}
+
 // features 部分更新（POST /config 与同步下载共用）：只收已知开关的布尔值
 function applyFeaturesPartial(base, partial) {
   const out = (base && typeof base === 'object') ? base : {};
@@ -1232,7 +1638,7 @@ function applyStylesPartial(base, partial) {
       else if (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 96) out[key] = Math.round(v);
     }
   }
-  for (const key of ['lineHeight', 'codeLineHeight', 'userLineHeight']) {
+  for (const key of ['lineHeight', 'thinkingLineHeight', 'codeLineHeight', 'userLineHeight']) {
     if (key in partial) {
       const v = partial[key];
       if (v === null) out[key] = null;
@@ -1447,16 +1853,22 @@ function readRtkBuiltinWhitelist() {
 // —— rtk 本体（独立二进制）的检查更新与升级：GitHub Releases 下载 → sha256 校验 → 原子替换 ——
 
 function rtkFindBin() {
+  // 兜底候选按平台给全扩展名：全新安装装到 ~/.local/bin 后 PATH 对运行中的 helper
+  // 不可见（需注销重登），必须能按固定位置直接找到，否则面板误报“未安装”
   return findBinFile(
-    process.platform === 'win32' ? ['rtk.exe', 'rtk.cmd'] : ['rtk'],
-    [join(homedir(), '.local', 'bin', 'rtk'), join(homedir(), 'miniforge3', 'bin', 'rtk'),
-     '/usr/local/bin/rtk', '/usr/bin/rtk']);
-}
-
-// 最新版本探测（两条互补通道，任一成功即用）：
-// ① releases/latest 的 302 重定向拿 tag——不受 API 速率限制，但 github.com 网页在
-//    部分网络直连不通（超时）；② 匿名 GitHub API——直连常可用，但走代理时出口 IP
-//    常被限流（403 无 tag_name）。资产与 checksums 的下载地址按官方命名规则构造。
+    process.platform === 'win32' ? ['rtk.exe'] : ['rtk'],
+    process.platform === 'win32'
+      ? [join(homedir(), '.local', 'bin', 'rtk.exe'), join(homedir(), '.cargo', 'bin', 'rtk.exe'),
+         join(homedir(), 'miniforge3', 'Scripts', 'rtk.exe'), join(homedir(), 'miniconda3', 'Scripts', 'rtk.exe')]
+      : [join(homedir(), '.local', 'bin', 'rtk'), join(homedir(), 'miniforge3', 'bin', 'rtk'),
+         '/usr/local/bin/rtk', '/usr/bin/rtk']);
+}
+
+// 最新版本探测。两条互补通道，任一成功即用：① 匿名 GitHub API——直连常可用，但
+// 走代理时出口 IP 常被限流；② releases/latest 302 的 Location 头——不受速率限制，
+// 但 github.com 网页在部分网络直连不通。资产与 checksums 的下载地址按官方命名规则
+// 构造。请求复用 webdavRequest（curl 优先、按 proxyScopes 注入代理；无 curl 的精简
+// Windows 回退 fetch 直连，代理在那条路径不生效）。
 async function rtkLatestInfo() {
   const assetName = rtkAssetName();
   if (!assetName) return { code: 'rtk-update', error: '当前平台不支持自动升级' };
@@ -1464,25 +1876,23 @@ async function rtkLatestInfo() {
     const base = `https://github.com/rtk-ai/rtk/releases/download/v${tag}`;
     return { tag, assetName, assetUrl: `${base}/${assetName}`, sumsUrl: `${base}/checksums.txt` };
   };
-  let redirErr = '';
-  const redir = await execCapture('curl', ['-sS', '-o', '/dev/null', '-w', '%{url_effective}', '-L', '--max-time', '6',
-    'https://github.com/rtk-ai/rtk/releases/latest'], 8000);
-  if (redir.ok) {
-    const m = /\/tag\/v?(\d[\w.+-]*)\s*$/.exec(redir.output.trim());
-    if (m) return mkInfo(m[1]);
-    redirErr = '重定向未携带版本';
-  } else {
-    redirErr = (redir.output || redir.error || '').split('\n').slice(-1)[0];
-  }
-  const api = await execCapture('curl', ['-s', '--max-time', '8',
-    'https://api.github.com/repos/rtk-ai/rtk/releases/latest'], 10000);
-  if (api.ok) {
+  const proxyUrl = proxyUrlFor('deps');
+  const api = await webdavRequest({
+    method: 'GET', url: 'https://api.github.com/repos/rtk-ai/rtk/releases/latest',
+    proxyUrl, timeoutMs: 12000, headers: ['User-Agent: zcode-pro'],
+  });
+  if (api.ok && api.httpCode === 200) {
     try {
-      const tag = String((JSON.parse(api.output) || {}).tag_name || '').replace(/^v/, '');
+      const tag = String(JSON.parse(api.body).tag_name || '').replace(/^v/, '');
       if (tag) return mkInfo(tag);
-    } catch { /* 落到统一报错 */ }
+    } catch { /* body 不是 JSON：换重定向通道 */ }
   }
-  return { code: 'rtk-update', error: '查询 GitHub Releases 失败（可尝试在“代理”标签页设置代理）。重定向: ' + redirErr };
+  const redir = await webdavRequest({
+    method: 'GET', url: 'https://github.com/rtk-ai/rtk/releases/latest', proxyUrl, timeoutMs: 10000,
+  });
+  const m = /\/tag\/v?(\d[\w.+-]*)\s*$/.exec(redir.redirectUrl || '');
+  if (m) return mkInfo(m[1]);
+  return { code: 'rtk-update', error: '查询 GitHub Releases 失败（网络不通或需代理）' };
 }
 
 // 按平台/架构选资产文件名（与官方 Release 命名一致）
@@ -1499,72 +1909,92 @@ export function rtkUpgradeSnapshot() { return upgradeJobSnapshot(rtkUpgradeJob);
 
 function cancelRtkUpgrade() { return cancelUpgradeJob(rtkUpgradeJob); }
 
-// 启动 rtk 本体升级（后台任务，面板经 GET /rtk/upgrade 轮询）：
-// 下载资产与 checksums → sha256 校验 → 解压 → 试运行 → 原子替换旧二进制
+// 启动 rtk 本体升级或安装（后台任务，面板经 GET /rtk/upgrade 轮询）：
+// 下载资产与 checksums → sha256 校验 → 解压 → 试运行 → 原子替换旧二进制；
+// 未安装时装到 ~/.local/bin（钩子的 rtk 查找清单含该位置，装完钩子立即可用；
+// Windows 资产是 zip，用系统自带 bsdtar 解压、PowerShell Get-FileHash 校验，
+// 全新安装后把 ~/.local/bin 注册进用户级 PATH，运行中的进程读不到——重启 ZCode 生效）
 function startRtkUpgrade() {
   if (rtkUpgradeJob && rtkUpgradeJob.running) return rtkUpgradeSnapshot();
   const j = newUpgradeJob();
   rtkUpgradeJob = j;
+  const WIN = process.platform === 'win32';
   void (async () => {
     let dir = null;
     let bin = null;
     try {
-      if (process.platform === 'win32') throw new Error('Windows 暂不支持自动升级，请手动下载 Release 覆盖安装');
-      bin = rtkFindBin();
-      if (!bin) throw new Error('未找到 rtk 程序');
+      const freshInstall = !rtkFindBin();
+      bin = rtkFindBin() || join(homedir(), '.local', 'bin', WIN ? 'rtk.exe' : 'rtk');
       const info = await rtkLatestInfo();
       if (info.code) throw new Error(info.error);
       dir = await mkdtemp(join(tmpdir(), 'rtk-upgrade-'));
       j.output += `下载 ${info.assetName}…\n`;
       const archPath = join(dir, info.assetName);
-      await jobRun(j, 'curl', ['-L', '--fail', '--progress-bar', '-o', archPath, info.assetUrl], 600000);
+      await downloadToFile(j, info.assetUrl, archPath, 600000);
       // sha256 校验（checksums.txt 与本机摘要工具；失败即中止，不替换）
       if (info.sumsUrl) {
         const sumPath = join(dir, 'checksums.txt');
-        await jobRun(j, 'curl', ['-sL', '--fail', '-o', sumPath, info.sumsUrl], 30000);
+        await downloadToFile(j, info.sumsUrl, sumPath, 30000);
         const want = readFileSync(sumPath, 'utf8').split('\n')
           .find((l) => l.trim().endsWith(info.assetName))?.trim().split(/\s+/)[0];
-        const sumCmd = process.platform === 'darwin' ? 'shasum' : 'sha256sum';
-        const sumArgs = process.platform === 'darwin' ? ['-a', '256', archPath] : [archPath];
-        const local = await execCapture(sumCmd, sumArgs, 30000);
-        const got = local.ok ? (local.output.split(/\s+/)[0] || '') : '';
+        let got = '';
+        if (WIN) {
+          const local = await execCapture('powershell.exe',
+            ['-NoProfile', '-Command', `(Get-FileHash -Algorithm SHA256 -LiteralPath "${archPath}").Hash`], 60000);
+          got = (/[0-9a-fA-F]{64}/.exec(local.output || '') || [''])[0];
+        } else {
+          const sumCmd = process.platform === 'darwin' ? 'shasum' : 'sha256sum';
+          const sumArgs = process.platform === 'darwin' ? ['-a', '256', archPath] : [archPath];
+          const local = await execCapture(sumCmd, sumArgs, 30000);
+          got = local.ok ? (local.output.split(/\s+/)[0] || '') : '';
+        }
         if (!want || !got || want.toLowerCase() !== got.toLowerCase()) {
           throw new Error(`sha256 校验失败（期望 ${want || '?'}，实际 ${got || '?'}）`);
         }
         j.output += 'sha256 校验通过\n';
       }
-      // 解压并定位二进制（包内根目录或一级子目录）
-      await jobRun(j, 'tar', ['-xzf', archPath, '-C', dir], 60000);
-      let newBin = join(dir, 'rtk');
+      // 解压并定位二进制（包内根目录或一级子目录）。Windows 资产是 zip，
+      // 系统自带 bsdtar（tar.exe）可直接解，不加 -z
+      await jobRun(j, 'tar', WIN ? ['-xf', archPath, '-C', dir] : ['-xzf', archPath, '-C', dir], 60000);
+      const exeName = WIN ? 'rtk.exe' : 'rtk';
+      let newBin = join(dir, exeName);
       if (!existsSync(newBin)) {
         for (const ent of readdirSync(dir, { withFileTypes: true })) {
-          const cand = join(dir, ent.name, 'rtk');
+          const cand = join(dir, ent.name, exeName);
           if (ent.isDirectory() && existsSync(cand)) { newBin = cand; break; }
         }
       }
       if (!existsSync(newBin)) throw new Error('解压后未找到 rtk 二进制');
-      chmodSync(newBin, 0o755);
+      if (!WIN) chmodSync(newBin, 0o755);
       const v = await binVersionOf(newBin);
       if (!v) throw new Error('新版本无法运行（--version 无输出）');
-      // 原子替换：旧文件先挪走，失败可回滚
+      // 放置：全新安装建目录直接放；已有旧文件则原子替换（先挪走，失败可回滚）
+      if (freshInstall) mkdirSync(dirname(bin), { recursive: true });
       const backup = bin + '.rtk-old';
       try { rmSync(backup, { force: true }); } catch { /* ignore */ }
-      renameSync(bin, backup);
+      const hadOld = existsSync(bin);
+      if (hadOld) renameSync(bin, backup);
       try {
         try {
           renameSync(newBin, bin);
         } catch (renameErr) {
           // 跨文件系统（EXDEV）等 rename 失败：退化为复制（复制再失败由外层 catch 回滚）
           copyFileSync(newBin, bin);
-          chmodSync(bin, 0o755);
+          if (!WIN) chmodSync(bin, 0o755);
         }
       } catch (err) {
-        renameSync(backup, bin);
+        if (hadOld && existsSync(backup)) { try { renameSync(backup, bin); } catch { /* ignore */ } }
         throw err;
       }
-      try { rmSync(backup, { force: true }); } catch { /* ignore */ }
+      try { if (existsSync(backup)) rmSync(backup, { force: true }); } catch { /* ignore */ }
       j.version = v;
-      j.output += `已升级到 ${v}\n`;
+      if (WIN && freshInstall) {
+        const inPath = await ensureUserPathEntry(dirname(bin));
+        j.output += `已安装 rtk ${v}（${bin}；PATH 需注销重登后对会话生效，插件钩子即时生效）\n`;
+        if (!inPath) j.output += '注意：把 ~/.local/bin 写入用户 PATH 失败，钩子不受影响，会话里直接跑 rtk 需手动加 PATH\n';
+      } else {
+        j.output += freshInstall ? `已安装 rtk ${v}（${bin}）\n` : `已升级到 ${v}\n`;
+      }
     } catch (err) {
       if (!j.canceled) j.error = j.timedOut ? '升级超时已终止' : String(err?.stack || err?.message || err);
     } finally {
@@ -1577,26 +2007,39 @@ function startRtkUpgrade() {
   return rtkUpgradeSnapshot();
 }
 
-// 在插件缓存里找市场插件的钩子脚本（取版本号最大的目录，按数值比较，0.10.0 > 0.9.0）。
-// 只认纯数字版本目录：手动安装/升级的残留（如 1.0.2.bak-1.0.2）内容不全，不能选中。
+// 把目录追加进用户级 PATH（HKCU\Environment，Windows）：保持原值类型不展开（REG_EXPAND_SZ
+// 里的 %VAR% 引用原样保留），已含该目录则不动。不广播环境变更——运行中的进程读不到，
+// 重启 ZCode 后新会话生效（rtk 钩子按固定清单找 rtk，不受 PATH 影响）。
+async function ensureUserPathEntry(dir) {
+  const q = await execCapture('reg', ['query', 'HKCU\\Environment', '/v', 'PATH'], 15000);
+  if (!q.ok) {
+    const add = await execCapture('reg', ['add', 'HKCU\\Environment', '/v', 'PATH', '/t', 'REG_EXPAND_SZ', '/d', `%USERPROFILE%\\.local\\bin`, '/f'], 15000);
+    return add.ok;
+  }
+  const m = /PATH\s+(REG_SZ|REG_EXPAND_SZ)\s+(.*)/i.exec(q.output.replace(/\r?\n/g, ' ').trim());
+  if (!m) return false;
+  const cur = m[2].trim();
+  const norm = (s) => s.replace(/[/\\]+/g, '\\').replace(/\\+$/, '').toLowerCase();
+  const expanded = cur.replaceAll('%USERPROFILE%', homedir());
+  if (expanded.split(';').some((p) => p && norm(p) === norm(dir))) return true;
+  const next = cur ? `${cur};${dir}` : dir;
+  const r = await execCapture('reg', ['add', 'HKCU\\Environment', '/v', 'PATH', '/t', m[1], '/d', next, '/f'], 15000);
+  return r.ok;
+}
+
+// 在插件缓存里找市场插件的钩子脚本：只认 installed_plugins.json 登记的 installPath。
+// 不能按目录扫描：卸载只删「当前指向」的版本目录，缓存里的历史版本目录会残留
+// （升级留旧版、GitHub/本地源先后装过等），扫目录会把已卸载的插件误判为已装，
+// 面板就不显示安装卡了。本地开发流（install-plugin-local.sh）同样会更新安装记录，兼容。
 // 注意只认正式市场 duanluan-zcode-plugins：本地临时市场（如 duanluan-local）装的副本不在查找范围，
 // 属预期限制——正式发布从 duanluan-zcode-plugins 安装后即可用。
 function findMarketplaceHook(pluginName, hookRelPath) {
-  const base = join(cliPluginsDir(), 'cache', ZCODE_PLUGINS_MARKETPLACE, pluginName);
-  try {
-    const versions = readdirSync(base)
-      .filter((d) => /^\d+(\.\d+){0,3}$/.test(d))
-      .sort((a, b) => {
-        const pa = a.split('.').map(Number);
-        const pb = b.split('.').map(Number);
-        for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
-        return 0;
-      });
-    for (let i = versions.length - 1; i >= 0; i--) {
-      const hook = join(base, versions[i], hookRelPath);
-      if (existsSync(hook)) return hook;
-    }
-  } catch { /* ignore */ }
+  const installedRaw = readJsonFile(join(cliPluginsDir(), 'installed_plugins.json'));
+  for (const rec of (installedRaw?.plugins || [])) {
+    if (rec?.name !== pluginName || rec?.marketplace !== ZCODE_PLUGINS_MARKETPLACE || !rec.installPath) continue;
+    const hook = join(rec.installPath, hookRelPath);
+    if (existsSync(hook)) return hook;
+  }
   return null;
 }
 
@@ -1604,6 +2047,13 @@ function findVisionHook() {
   return findMarketplaceHook('zcode-vision', join('hooks', 'vision-hook.mjs'));
 }
 
+// 读市场插件在 installed_plugins.json 里登记的版本（面板信息卡显示「插件 x.y.z」用）
+function installedPluginVersion(pluginName) {
+  const installedRaw = readJsonFile(join(cliPluginsDir(), 'installed_plugins.json'));
+  const rec = (installedRaw?.plugins || []).find((p) => p?.name === pluginName && p?.marketplace === ZCODE_PLUGINS_MARKETPLACE);
+  return rec?.version || null;
+}
+
 // —— headroom 配置读写与状态解析（与 headroom-lib.sh 共用 ~/.zcode/headroom.json）——
 
 // 读配置并按插件默认值归一（文件缺失/键非法 → 默认）。导出以便测试脚本直接驱动。
@@ -1675,11 +2125,11 @@ function cancelUpgradeJob(job) {
   return upgradeJobSnapshot(job);
 }
 
-// 升级任务的可取消子进程执行：输出喂给任务对象供面板轮询，环境注入代理
-function jobRun(j, cmd, args, timeoutMs) {
+// 升级任务的可取消子进程执行：输出喂给任务对象供面板轮询，环境按用途注入代理
+function jobRun(j, cmd, args, timeoutMs, scope = 'deps') {
   return new Promise((resolveRun, rejectRun) => {
     if (j.canceled) { rejectRun(new Error('canceled')); return; }
-    const child = spawn(cmd, args, { env: { ...process.env, ...proxyEnv() }, windowsHide: true });
+    const child = spawn(cmd, args, { env: { ...process.env, ...proxyEnv({}, scope) }, windowsHide: true });
     j.kill = () => { try { child.kill('SIGKILL'); } catch { /* ignore */ } };
     const feed = (d) => { j.output = (j.output + d.toString()).slice(-65536); };
     child.stdout.on('data', feed);
@@ -1698,10 +2148,62 @@ function jobRun(j, cmd, args, timeoutMs) {
   });
 }
 
+// rtk 资产/校验和下载：有 curl 时经子进程下载（jobRun 注入 deps 代理并提供取消
+// 与超时；-f 让 HTTP 错误直接失败，不会把错误页写成文件，此路径无百分比进度）。
+// 无 curl 的精简 Windows 用 node fetch 流式写文件兜底：进度按 5% 一档喂给升级
+// 任务，j.canceled 时立即中止（fetch 不读代理环境变量，配了代理又无 curl 的机器
+// 在这条路径只能直连——与 WebDAV 同步的 fetch 兜底同一限制）
+async function downloadToFile(j, url, dest, timeoutMs = 600000) {
+  const curl = findCurl();
+  if (curl) {
+    await jobRun(j, curl,
+      ['-fsSL', '--connect-timeout', '20', '--max-time', String(Math.ceil(timeoutMs / 1000)), '-o', dest, url],
+      timeoutMs);
+    return;
+  }
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok || !res.body) throw new Error(`下载失败 HTTP ${res.status}`);
+  const total = Number(res.headers.get('content-length')) || 0;
+  const out = createWriteStream(dest);
+  let got = 0;
+  let lastPct = -1;
+  try {
+    for await (const chunk of res.body) {
+      if (j.canceled) throw new Error('canceled');
+      if (!out.write(chunk)) await new Promise((r) => out.once('drain', r));
+      got += chunk.length;
+      if (total > 0) {
+        const pct = Math.floor((got / total) * 100);
+        if (pct >= lastPct + 5) { lastPct = pct; j.output += `下载中 ${pct}%\n`; }
+      }
+    }
+    await new Promise((resolve, reject) => { out.end(resolve); out.once('error', reject); });
+  } catch (err) {
+    try { out.destroy(); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
 // headroom 程序探测：镜像钩子 hr_find_headroom 的查找清单（PATH + 常见安装位置）
 function headroomFindBin() {
-  return findBinFile(
-    process.platform === 'win32' ? ['headroom.exe', 'headroom.cmd'] : ['headroom'],
+  // Windows 兜底：pip 的 console script 落在各 Python 环境的 Scripts 目录（.exe），
+  // Scripts 目录不一定在桌面应用的 PATH 里
+  if (process.platform === 'win32') {
+    const home = homedir();
+    const pfRoots = [...new Set([process.env.PROGRAMFILES || 'C:\\Program Files', 'C:\\Program Files', 'C:\\ProgramFiles'])];
+    const extra = [
+      join(home, '.local', 'bin', 'headroom.exe'),
+      join(home, 'miniforge3', 'Scripts', 'headroom.exe'),
+      join(home, 'miniconda3', 'Scripts', 'headroom.exe'),
+      join(home, 'anaconda3', 'Scripts', 'headroom.exe'),
+    ];
+    for (const pf of pfRoots) {
+      extra.push(join(pf, 'miniforge3', 'Scripts', 'headroom.exe'), join(pf, 'miniconda3', 'Scripts', 'headroom.exe'));
+      for (const v of ['313', '312', '311']) extra.push(join(pf, `Python${v}`, 'Scripts', 'headroom.exe'));
+    }
+    return findBinFile(['headroom.exe'], extra);
+  }
+  return findBinFile(['headroom'],
     [join(homedir(), '.local', 'bin', 'headroom'), join(homedir(), 'miniforge3', 'bin', 'headroom'),
      join(homedir(), '.cargo', 'bin', 'headroom'), '/usr/local/bin/headroom', '/usr/bin/headroom']);
 }
@@ -1712,10 +2214,11 @@ async function headroomBinaryInfo() {
   return { installed: true, binPath, version: await binVersionOf(binPath) };
 }
 
-// 通用命令执行（headroom 本体的 pip 检查/升级用），输出合并 stdout+stderr
-function execCapture(cmd, args, timeoutMs = 30000) {
+// 通用命令执行（headroom 本体的 pip 检查/升级等），输出合并 stdout+stderr，
+// 环境按用途注入代理（默认 deps：headroom/rtk；市场路径不走这里）
+function execCapture(cmd, args, timeoutMs = 30000, scope = 'deps') {
   return new Promise((resolveRun) => {
-    execFile(cmd, args, { timeout: timeoutMs, env: { ...process.env, ...proxyEnv() }, windowsHide: true }, (err, stdout, stderr) => {
+    execFile(cmd, args, { timeout: timeoutMs, env: { ...process.env, ...proxyEnv({}, scope) }, windowsHide: true }, (err, stdout, stderr) => {
       resolveRun({
         ok: !err,
         code: err ? (err.code ?? 'error') : 0,
@@ -1729,6 +2232,19 @@ function execCapture(cmd, args, timeoutMs = 30000) {
 // headroom 本体（pip 安装）的升级通道：控制台脚本 shebang 指向安装它的 Python
 // 解释器，检查更新与升级都通过该环境的 pip 执行（尊重用户 pip 源配置）。
 function headroomPythonOf(binPath) {
+  // Windows：pip console script 是 .exe（无 shebang），从所在目录推导——
+  // Scripts\headroom.exe → 同环境根目录的 python.exe
+  if (process.platform === 'win32') {
+    const dir = dirname(binPath);
+    if (basename(dir).toLowerCase() === 'scripts') {
+      const py = join(dirname(dir), 'python.exe');
+      if (existsSync(py)) return py;
+    }
+    const sibling = join(dir, 'python.exe');
+    if (existsSync(sibling)) return sibling;
+    return headroomFallbackPython();
+  }
+  // POSIX：读脚本的 shebang 行
   try {
     const first = (readFileSync(binPath, 'utf8').split('\n')[0] || '').trim();
     const m = /^#!\s*(.*python\S*)/.exec(first);
@@ -1747,9 +2263,35 @@ const HEADROOM_DIST_PY = [
   "        print(n + '\\t' + d.version); break",
 ].join('\n');
 
+// 本体未装时的全新安装通道：找可用的 Python（PATH + 常见安装位置），
+// 用官方发行版 headroom-ai[all] 走同一套 pip 升级任务
+function headroomFallbackPython() {
+  const WIN = process.platform === 'win32';
+  const home = homedir();
+  if (WIN) {
+    const pfRoots = [...new Set([process.env.PROGRAMFILES || 'C:\\Program Files', 'C:\\Program Files', 'C:\\ProgramFiles'])];
+    const extra = [
+      join(home, 'miniforge3', 'python.exe'),
+      join(home, 'miniconda3', 'python.exe'),
+      join(home, 'anaconda3', 'python.exe'),
+    ];
+    for (const pf of pfRoots) {
+      extra.push(join(pf, 'miniforge3', 'python.exe'), join(pf, 'miniconda3', 'python.exe'));
+      for (const v of ['313', '312', '311']) extra.push(join(pf, `Python${v}`, 'python.exe'));
+    }
+    return findBinFile(['python.exe'], extra);
+  }
+  return findBinFile(['python3', 'python'],
+    ['/usr/bin/python3', '/usr/local/bin/python3', join(home, '.local', 'bin', 'python3')]);
+}
+
 async function headroomPipChannel() {
   const bin = headroomFindBin();
-  if (!bin) return { code: 'headroom-update', error: '未找到 headroom 程序' };
+  if (!bin) {
+    const py = headroomFallbackPython();
+    if (!py) return { code: 'headroom-update', error: '未找到 headroom 程序，也未找到可用的 Python（全新安装需要 Python ≥ 3.10）' };
+    return { py, dist: 'headroom-ai[all]', current: null, freshInstall: true };
+  }
   const py = headroomPythonOf(bin);
   if (!py) return { code: 'headroom-update', error: '无法确定 headroom 的 Python 安装来源（不是 pip 控制台脚本）' };
   const r = await execCapture(py, ['-c', HEADROOM_DIST_PY], 20000);
@@ -1791,15 +2333,27 @@ function startHeadroomUpgrade(channel) {
   return headroomUpgradeSnapshot();
 }
 
-// 运行 headroom 插件钩子（ensure-proxy.sh，POSIX sh）：backend/power 写配置并立即
-// 生效，status/start/stop/restart 管理代理生命周期
-function runHeadroomHook(args, timeoutMs = 20000) {
+// 运行 headroom 插件钩子：新版插件（≥1.2.0）是跨平台 node 入口 ensure-proxy.mjs
+// （Windows 原生实现、POSIX 内部委托 ensure-proxy.sh），经 runNodeScript 跑（自动
+// 处理 node/内嵌 node 回退）；旧版只有 .sh 时用 sh 直跑（仅 POSIX）。
+// backend/power 写配置并立即生效，status/start/stop/restart 管理代理生命周期。
+// 钩子运行注意两点：
+// 1. 不注入下载代理（scope 'none'）——钩子不是安装/升级下载，代理范围开关不管它；
+// 2. localhost 强制不走代理——钩子里 curl 探测 http://127.0.0.1:<端口> 判断代理
+//    是否在跑，环境里残留的 http_proxy（包括 zcode-pro 自己注入的下载代理）会把
+//    探测请求送进代理服务器，代理停了就把在跑的 headroom 误判成未运行，面板一直
+//    卡在“正在启动”。
+async function runHeadroomHook(args, timeoutMs = 30000) {
+  const noProxy = ['127.0.0.1', 'localhost', process.env.NO_PROXY || process.env.no_proxy || ''].filter(Boolean).join(',');
+  const hookEnv = { NO_PROXY: noProxy, no_proxy: noProxy };
+  const mjs = findMarketplaceHook('headroom', join('hooks', 'ensure-proxy.mjs'));
+  if (mjs) return runNodeScript([mjs, ...args], timeoutMs, 'none', hookEnv);
   const hook = findMarketplaceHook('headroom', join('hooks', 'ensure-proxy.sh'));
   if (!hook) {
-    return Promise.resolve({ ok: false, code: 'headroom-plugin', error: '未找到 headroom 插件（先在插件市场安装）' });
+    return { ok: false, code: 'headroom-plugin', error: '未找到 headroom 插件（先在插件市场安装）' };
   }
   return new Promise((resolveRun) => {
-    execFile('sh', [hook, ...args], { timeout: timeoutMs, windowsHide: true }, (err, stdout, stderr) => {
+    execFile('sh', [hook, ...args], { timeout: timeoutMs, windowsHide: true, env: { ...process.env, ...hookEnv } }, (err, stdout, stderr) => {
       if (err && err.code === 'ENOENT') {
         resolveRun({ ok: false, code: 'headroom-sh', error: '未找到 sh，无法运行 headroom 插件脚本' });
         return;
@@ -1840,11 +2394,102 @@ export function parseHeadroomStatus(text) {
   };
 }
 
+// —— headroom 启用开关（设置弹窗“Headroom”标签页右上角）：只切换 ZCode 供应商配置
+// 里指向本地压缩代理（http://127.0.0.1:<端口>）的条目与直连上游之间的地址，绝不碰
+// 代理进程——headroom 是共享程序，其他工具（如 codex）可能同时在用。
+// 关闭时把条目改回直连地址（headroom 的默认转发上游），并在 zcodepro.json 的
+// headroomRoutes 里记下 { 供应商 id → { proxy, direct } }；开启时按记录切回代理。
+const HEADROOM_DIRECT_URL = 'https://open.bigmodel.cn/api/anthropic';
+const HEADROOM_LOCAL_URL_RE = /^http:\/\/127\.0\.0\.1:\d+\/?$/;
+
+// 扫描 v2/config.json（provider.<id>.options.baseURL）与 v2/provider_config.json
+// （providerRules[].config.api.baseUrl），统计当前走本地代理的条目数
+export function headroomUsageScan(dataRoot) {
+  let via = 0;
+  const v2 = readJsonFile(join(dataRoot, 'v2', 'config.json'));
+  for (const p of Object.values((v2 && typeof v2.provider === 'object' && v2.provider) || {})) {
+    const u = typeof p?.options?.baseURL === 'string' ? p.options.baseURL.trim() : '';
+    if (HEADROOM_LOCAL_URL_RE.test(u)) via += 1;
+  }
+  const pc = readJsonFile(join(dataRoot, 'v2', 'provider_config.json'));
+  for (const r of pc?.config?.providerConfigRules?.providerRules || []) {
+    const u = typeof r?.config?.api?.baseUrl === 'string' ? r.config.api.baseUrl.trim() : '';
+    if (HEADROOM_LOCAL_URL_RE.test(u)) via += 1;
+  }
+  return { enabled: via > 0, entries: via };
+}
+
+// 切换启用状态：enable=false 时 127.0.0.1 条目 → 直连（并记录）；enable=true 时按
+// 记录把直连条目切回代理。改写前各留 .zcodepro-backup 备份，与同步导入同款。
+export function setHeadroomUsage(dataRoot, configFile, enable) {
+  const backupFile = (p) => {
+    try { if (existsSync(p)) copyFileSync(p, p + '.zcodepro-backup'); } catch { /* 备份失败不阻塞 */ }
+  };
+  const atomicWrite = (p, obj) => {
+    const tmp = p + '.zcodepro-tmp';
+    writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    renameSync(tmp, p);
+  };
+  const v2File = join(dataRoot, 'v2', 'config.json');
+  const pcFile = join(dataRoot, 'v2', 'provider_config.json');
+  const v2 = readJsonFile(v2File);
+  const pc = readJsonFile(pcFile);
+  if (!v2 && !pc) return { ok: false, code: 'headroom-provider-config', error: '未找到 ZCode 供应商配置（v2/config.json）' };
+
+  const config = loadConfig(configFile);
+  const routes = { ...(config.headroomRoutes || {}) };
+  let changed = 0;
+  // 供应商 id 来自配置文件，跳过保留键：对普通对象按 ["__proto__"] 赋值改的是原型，
+  // 不是自有属性，记录会悄悄丢失
+  const reserved = (id) => id === '__proto__' || id === 'constructor' || id === 'prototype';
+  const apply = (get, set, id) => {
+    const u = get();
+    if (!enable && HEADROOM_LOCAL_URL_RE.test(u)) {
+      routes[id] = { proxy: u, direct: HEADROOM_DIRECT_URL };
+      set(HEADROOM_DIRECT_URL);
+      changed += 1;
+      return true;
+    }
+    if (enable && routes[id] && u === routes[id].direct) {
+      set(routes[id].proxy);
+      changed += 1;
+      return true;
+    }
+    return false;
+  };
+
+  if (v2 && v2.provider && typeof v2.provider === 'object') {
+    let touched = false;
+    for (const [id, p] of Object.entries(v2.provider)) {
+      if (reserved(id) || !p || typeof p !== 'object' || !p.options || typeof p.options !== 'object') continue;
+      const u = typeof p.options.baseURL === 'string' ? p.options.baseURL.trim() : '';
+      if (apply(() => u, (v) => { p.options.baseURL = v; }, id)) touched = true;
+    }
+    if (touched) { backupFile(v2File); atomicWrite(v2File, v2); }
+  }
+  if (Array.isArray(pc?.config?.providerConfigRules?.providerRules)) {
+    let touched = false;
+    for (const r of pc.config.providerConfigRules.providerRules) {
+      const id = typeof r?.providerId === 'string' ? r.providerId : '';
+      const api = r?.config?.api;
+      if (!id || reserved(id) || !api || typeof api.baseUrl !== 'string') continue;
+      const u = api.baseUrl.trim();
+      if (apply(() => u, (v) => { api.baseUrl = v; }, id)) touched = true;
+    }
+    if (touched) { backupFile(pcFile); atomicWrite(pcFile, pc); }
+  }
+  config.headroomRoutes = routes;
+  saveConfig(configFile, config);
+  return { ok: true, changed };
+}
+
 // 用 node 跑脚本：优先 PATH 里的 node；桌面环境没有时用自身进程
 // （zcode-pro 本就跑在 ELECTRON_RUN_AS_NODE=1 的 ZCode 二进制上）。导出以便测试。
-export function runNodeScript(scriptArgs, timeoutMs = 120000) {
-  const attempt = (cmd, extraEnv) => new Promise((resolveRun) => {
-    execFile(cmd, scriptArgs, { timeout: timeoutMs, env: { ...process.env, ...proxyEnv(), ...extraEnv }, windowsHide: true }, (err, stdout, stderr) => {
+// scope 默认 deps（headroom、rtk 的安装与升级）；插件市场的 zcode CLI 传 plugins；
+// extraEnv 是调用方要额外覆盖的环境变量（如 NO_PROXY）
+export function runNodeScript(scriptArgs, timeoutMs = 120000, scope = 'deps', extraEnv = {}) {
+  const attempt = (cmd, runEnv) => new Promise((resolveRun) => {
+    execFile(cmd, scriptArgs, { timeout: timeoutMs, env: { ...process.env, ...proxyEnv({}, scope), ...extraEnv, ...runEnv }, windowsHide: true }, (err, stdout, stderr) => {
       if (err && err.code === 'ENOENT') { resolveRun(null); return; }
       resolveRun({
         ok: !err,
@@ -1857,25 +2502,34 @@ export function runNodeScript(scriptArgs, timeoutMs = 120000) {
   return attempt('node', {}).then((r) => r || attempt(process.execPath, { ELECTRON_RUN_AS_NODE: '1' }));
 }
 
-// ZCode CLI bundle（plugins 子命令入口）：按常见安装位置查找，可用环境变量覆盖
+// ZCode CLI bundle（plugins 子命令入口）：优先从定位到的 ZCode 可执行文件推导
+// （paths.mjs 覆盖 --zcode-path/环境变量/平台默认位置/Windows 注册表，含
+// C:\Program Files\ZCode 安装），再退回常见安装位置，可用环境变量覆盖
 function zcodeCliBundleCandidates() {
+  const fromExe = [];
+  try {
+    const exe = resolveZcodeExecutable();
+    if (exe) fromExe.push(join(dirname(exe), 'resources', 'glm', 'zcode.cjs'));
+  } catch { /* 未找到 ZCode 可执行文件时走静态候选 */ }
   return [
     process.env.ZCODEPRO_ZCODE_CLI,
+    ...fromExe,
     '/opt/ZCode/resources/glm/zcode.cjs',
     '/usr/lib/zcode/resources/glm/zcode.cjs',
     '/usr/share/zcode/resources/glm/zcode.cjs',
     '/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs',
     process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'Programs', 'ZCode', 'resources', 'glm', 'zcode.cjs') : null,
+    process.env.PROGRAMFILES ? join(process.env.PROGRAMFILES, 'ZCode', 'resources', 'glm', 'zcode.cjs') : null,
   ].filter(Boolean);
 }
 
-// 运行 zcode CLI 子命令（plugins …）
+// 运行 zcode CLI 子命令（plugins …，走 plugins 代理范围）
 function runZcodeCli(subArgs, timeoutMs = 120000) {
   const bundle = zcodeCliBundleCandidates().find((c) => existsSync(c));
   if (!bundle) {
     return Promise.resolve({ ok: false, code: 'cli-not-found', error: '未找到 ZCode CLI（resources/glm/zcode.cjs）' });
   }
-  return runNodeScript([bundle, ...subArgs], timeoutMs);
+  return runNodeScript([bundle, ...subArgs], timeoutMs, 'plugins');
 }
 
 // 比对市场清单与已装清单：每个插件的已装版本与最新版本。导出以便测试。
@@ -1896,6 +2550,21 @@ export function pluginUpdateStatus() {
   return { plugins, updates: plugins.filter((e) => e.hasUpdate) };
 }
 
+// 市场未添加时自动补装（新机器上设置面板的“安装/更新”按钮一键可用）：
+// 读 known_marketplaces.json 判断，缺失则跑 plugins marketplace add。
+// 失败 30 分钟内不重试（add 是 git clone，GitHub 不通时每次面板请求都会白等
+// 最长 120 秒）；返回 null = 已存在无需处理，{ ok, cached } = 执行或跳过了 add。
+let lastMarketplaceAddFail = 0;
+async function ensureZcodePluginsMarketplace() {
+  const known = readJsonFile(join(cliPluginsDir(), 'known_marketplaces.json'));
+  const ids = new Set((known?.marketplaces || []).map((m) => m?.id).filter(Boolean));
+  if (ids.has(ZCODE_PLUGINS_MARKETPLACE)) return null;
+  if (Date.now() - lastMarketplaceAddFail < 30 * 60 * 1000) return { ok: false, cached: true, error: '上次添加市场失败，30 分钟内不再自动重试' };
+  const r = await runZcodeCli(['plugins', 'marketplace', 'add', ZCODE_PLUGINS_MARKETPLACE_SOURCE], 120000);
+  if (!r.ok) lastMarketplaceAddFail = Date.now();
+  return { ok: r.ok, output: r.output, error: r.error };
+}
+
 // 读全局提示词（~/.zcode/AGENTS.md）；文件不存在视为空内容。
 export function readAgents(agentsFile) {
   try {