zcode-pro 0.17.2 → 0.19.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 { taskIndexPath, probeTaskIndexWritable, remapTaskIndexPaths, taskIndexDriverAvailable, listOverriddenTitles, listTaskWorkspaceMap, setTaskTitleIfNotOverridden, getTaskProviderModel } 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.2';
+const VERSION = '0.19.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,35 @@ export function defaultConfig() {
     },
     // 项目路径（规范化，无尾分隔符）→ 自定义别名。只影响界面渲染，不改动任何真实数据。
     aliases: {},
+    // headroom 启用开关的记忆（供应商 id → { proxy, direct }）：关闭时把走 headroom 的
+    // 供应商地址切回直连并记录下来，再次开启时按记录把地址切回代理
+    headroomRoutes: {},
+    // 任务名提示词（自动起名）：新会话开始作答后按可配置的供应商与提示词生成
+    // 标题，并按“手动重命名”写入任务索引。默认关闭。provider：
+    // 'session' = 跟随当前会话（调用时从任务索引解析该会话的供应商，默认）、
+    // '' = 不跟随（自填 baseUrl/apiKey/format）、其余 = 供应商 id（保存时同步
+    // 解析一份 baseUrl/apiKey/format 副本，供应商日后被删仍可直连）；
+    // model 默认 glm-5.3-flash（起名用快模型即可），跟随会话时可留空
+    //（用会话当前模型）；prompt 留空 = 内置默认提示词
+    titleGen: {
+      enabled: false,
+      provider: 'session',
+      model: 'glm-5.3-flash',
+      prompt: '',
+      baseUrl: '',
+      apiKey: '',
+      format: '',
+    },
     // 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 +156,13 @@ 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 : {}) },
+      titleGen: mergeTitleGenConfig(saved.titleGen),
+      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 +223,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 +240,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 +294,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);
         }
@@ -257,6 +316,9 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         if (body && typeof body === 'object' && body.styles && typeof body.styles === 'object') {
           current.styles = applyStylesPartial(current.styles, body.styles);
         }
+        if (body && typeof body === 'object' && body.titleGen && typeof body.titleGen === 'object') {
+          current.titleGen = mergeTitleGenConfig({ ...current.titleGen, ...body.titleGen });
+        }
         saveConfig(configFile, current);
         json(res, 200, { ok: true, config: current });
         return;
@@ -365,6 +427,89 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         json(res, 200, { ok: true, enabled: config.features.titleLock !== false, titles: r.titles });
         return;
       }
+      // —— 智能起名：配置读写 + 供应商列表 + 生成并写库 ——
+      if (req.method === 'GET' && url.pathname === '/title-gen') {
+        json(res, 200, { ok: true, titleGen: loadConfig(configFile).titleGen, defaultPrompt: titleGenDefaultPrompt() });
+        return;
+      }
+      if (req.method === 'POST' && url.pathname === '/title-gen') {
+        const body = await readBody(req);
+        if (body && typeof body === 'object' && body.titleGen && typeof body.titleGen === 'object') {
+          const current = loadConfig(configFile);
+          const next = { ...current.titleGen, ...body.titleGen };
+          // 选了列表内供应商：同步解析并保存其地址/密钥/协议副本——供应商日后
+          // 被删，这份副本仍可直连（界面标注“已删除”并展开字段）；
+          // 跟随会话不存副本（每次调用时按该会话实时解析）
+          const providerId = (next.provider || '').trim();
+          if (providerId && providerId !== 'session') {
+            const found = listTitleGenProviders().find((p) => p.id === providerId);
+            if (found) {
+              next.baseUrl = found.baseUrl;
+              next.apiKey = found.apiKey;
+              next.format = found.format;
+            }
+            // 找不到（手输 id 或已删）：保留原有副本字段不动
+          } else if (providerId === 'session') {
+            // 跟随会话不存副本（每次调用时按该会话实时解析）
+            next.baseUrl = '';
+            next.apiKey = '';
+            next.format = '';
+          }
+          current.titleGen = mergeTitleGenConfig(next);
+          saveConfig(configFile, current);
+          json(res, 200, { ok: true, titleGen: current.titleGen });
+          return;
+        }
+        json(res, 400, { ok: false, code: 'invalid-request', error: 'body 需包含 titleGen 对象' });
+        return;
+      }
+      // 供应商下拉数据：与视觉代理同源同规则，但只列 helper 能在会话外直接
+      // 调用的条目（有地址、密钥且协议可判定），并带可选模型列表；不回密钥
+      if (req.method === 'GET' && url.pathname === '/title-gen/providers') {
+        json(res, 200, {
+          ok: true,
+          providers: listTitleGenProviders().map(({ apiKey, ...rest }) => rest),
+        });
+        return;
+      }
+      // 生成（并可选写库）：text = 会话首条消息；sessId 指定且非 test 时按
+      // “手动重命名”写入任务索引（已重命名的会话不会被动）；test = 设置面板
+      // 的测试按钮，只生成不写库
+      if (req.method === 'POST' && url.pathname === '/title-gen/run') {
+        const body = await readBody(req);
+        const text = typeof body?.text === 'string' ? body.text : '';
+        if (!text.trim()) {
+          json(res, 400, { ok: false, code: 'invalid-request', error: 'text 不能为空' });
+          return;
+        }
+        const cfg = loadConfig(configFile).titleGen;
+        if (cfg.enabled !== true && body.test !== true) {
+          json(res, 400, { ok: false, code: 'title-gen-disabled', error: '智能起名未开启' });
+          return;
+        }
+        const sessId = typeof body?.sessId === 'string' && /^sess_[A-Za-z0-9._-]+$/.test(body.sessId) ? body.sessId : '';
+        const title = await generateTitleWith(cfg, text, dataRoot, sessId);
+        let written = false;
+        if (sessId && body.test !== true) {
+          // 写库撞上宿主写入时稍候重试（起名不急这几秒）
+          for (let attempt = 0; ; attempt++) {
+            try {
+              const r = await setTaskTitleIfNotOverridden(dataRoot, sessId, title);
+              written = r.written;
+              break;
+            } catch (err) {
+              if (err.code === 'index-busy' && attempt < 2) {
+                await new Promise((r) => setTimeout(r, 1200));
+                continue;
+              }
+              json(res, 500, { ok: false, code: err.code || 'index-error', error: err.message });
+              return;
+            }
+          }
+        }
+        json(res, 200, { ok: true, title, written });
+        return;
+      }
       // —— zcode-vision 插件（图片视觉代理）：设置弹窗“视觉代理”标签页读写 ————
       if (req.method === 'GET' && url.pathname === '/vision') {
         const file = defaultVisionFile();
@@ -373,7 +518,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 +566,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 +647,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 +715,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 +759,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 +767,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 +835,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 +905,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 +913,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 +1056,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 +1074,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 +1095,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 +1135,37 @@ function clampInt(v, min, max, dflt) {
 
 // —— 设置同步（“同步”标签页）的实现 ——
 
+// loadConfig 时把磁盘上的 titleGen 段按默认值归一（智能起名）：只收已知字段，
+// 字符串限长；enabled 默认关闭（改动官方起名行为，需用户显式开启）
+function mergeTitleGenConfig(saved) {
+  const d = defaultConfig().titleGen;
+  const s = (saved && typeof saved === 'object' && !Array.isArray(saved)) ? saved : {};
+  // 旧版配置的 'cli'（登录账号单独成模式）统一迁移为 'session'：
+  // 登录账号的套餐已在供应商列表里，跟随会话即覆盖原语义
+  const provider = typeof s.provider === 'string' ? s.provider.trim().slice(0, 200) : d.provider;
+  return {
+    enabled: s.enabled === true,
+    provider: provider === 'cli' ? 'session' : provider,
+    model: typeof s.model === 'string' ? s.model.trim().slice(0, 200) : d.model,
+    prompt: typeof s.prompt === 'string' ? s.prompt.slice(0, 20000) : d.prompt,
+    baseUrl: typeof s.baseUrl === 'string' ? s.baseUrl.trim().slice(0, 500) : d.baseUrl,
+    apiKey: typeof s.apiKey === 'string' ? s.apiKey.trim().slice(0, 500) : d.apiKey,
+    format: s.format === 'openai' ? 'openai' : s.format === 'anthropic' ? 'anthropic' : '',
+  };
+}
+
+// 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 +1213,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 +1239,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 +1268,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 +1296,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 +1322,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 +1361,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 +1375,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 +1392,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 +1427,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 +1514,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 +1760,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;
@@ -1266,33 +1794,290 @@ function sanitizeFontStack(v) {
   return s;
 }
 
-// 跟随供应商下拉取数：合并 ~/.zcode/v2/config.json 的 provider（优先）与
-// ~/.zcode/v2/provider_config.json 的 providerRules（同 id 时规则表的名字保留为别名）；只回 id/名称/别名，不含密钥。
+// 视觉代理「跟随供应商」下拉取数：与智能起名共用同一套供应商列表和过滤规则
+//（见 listTitleGenProviders），只回 id/名称/别名，不含密钥。
 // 导出以便测试脚本直接驱动。
 export function listVisionProviders() {
-  const list = [];
+  return listTitleGenProviders().map((p) => ({ id: p.id, name: p.name, aliases: p.aliases || [] }));
+}
+
+// —— 智能起名：供应商取数、模型调用与标题清洗 ——
+
+// 内置默认提示词（用户可在设置弹窗覆盖），按界面语言取中文或英文版。
+// 英文版的词数上限比中文版紧：英文单词更长，3~15 个词在会话列表里放不下
+const TITLE_GEN_DEFAULT_PROMPTS = {
+  zh: [
+    '为下面的会话生成一个简短的标题。',
+    '要求：',
+    '- 使用用户消息的主要语言（中文消息用中文标题）',
+    '- 概括用户要做的主要事情或主题，不要给出答案或结果',
+    '- 一般3~15个词，在会话列表里能一眼认出',
+    '- 保留重要的专有名词（文件名、产品名、技术名词等，如有）',
+    '- 不要用`用户请求`、`新任务`、`提问`这类泛泛的标题',
+    '- 不要直接复述或截取用户消息原文当标题',
+    '- 只输出标题本身：不要解释、不要引号、不要末尾标点、不要markdown',
+  ].join('\n'),
+  en: [
+    'Generate a short title for the session below.',
+    'Requirements:',
+    "- Use the primary language of the user's message (an English message gets an English title)",
+    '- Summarize the user\'s main task or topic; do not give the answer or result',
+    '- Usually 3-8 words, easy to recognize in a session list',
+    '- Keep important proper nouns (file names, product names, technical terms, if any)',
+    '- Avoid generic titles such as `User Request`, `New Task`, or `Question`',
+    '- Do not copy or truncate the user\'s message as the title',
+    '- Output only the title itself: no explanation, no quotes, no trailing punctuation, no markdown',
+  ].join('\n'),
+};
+
+// 界面语言：桌面设置（v2/setting.json 的 localePreference）为 en-US / zh-CN 时
+// 直接采用；system 或未设置时按系统环境语言判断（中文环境 → 中文，其余 → 英文）
+function titleGenLocale() {
+  const s = readJsonFile(join(homedir(), '.zcode', 'v2', 'setting.json'));
+  const pref = String((s && s.localePreference) || '').toLowerCase();
+  if (pref.startsWith('en')) return 'en';
+  if (pref.startsWith('zh')) return 'zh';
+  const lang = String(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '').toLowerCase();
+  return lang.startsWith('zh') ? 'zh' : 'en';
+}
+
+function titleGenDefaultPrompt() {
+  return TITLE_GEN_DEFAULT_PROMPTS[titleGenLocale()] || TITLE_GEN_DEFAULT_PROMPTS.en;
+}
+
+const TITLE_GEN_MAX_TEXT = 1200;  // 用户消息送入模型的长度上限（与官方起名一致）
+const TITLE_GEN_MAX_TITLE = 64;   // 生成标题的长度上限（按字符计）
+const TITLE_GEN_TIMEOUT_MS = 60000; // 单次模型调用超时（与官方起名一致；推理模型思考占时较长）
+
+// 内置套餐显示名：与 ZCode 界面的叫法一致——条目原始名区分度差
+//（coding-plan 与 start-plan 都叫 "Coding Plan"），界面里按套餐类型显示。
+// coding-plan 的个人/团队是动态的：从桌面设置（v2/setting.json 的
+// providerFamilyConnectionSelections）读当前登录的连接方式（kind 含
+// individual → 个人、team → 团队），读不到时退回「个人/团队」
+function codingPlanKindByFamily() {
+  const s = readJsonFile(join(homedir(), '.zcode', 'v2', 'setting.json'));
+  const sel = (s && s.providerFamilyConnectionSelections && typeof s.providerFamilyConnectionSelections === 'object')
+    ? s.providerFamilyConnectionSelections : {};
+  const out = {};
+  for (const [family, v] of Object.entries(sel)) {
+    const kind = String(v?.kind || '');
+    if (/individual/i.test(kind)) out[family] = '个人';
+    else if (/team/i.test(kind)) out[family] = '团队';
+  }
+  return out;
+}
+
+function titleGenProviderDisplayName(id, name, planKinds = {}) {
+  const m = /^builtin:(zai|bigmodel)-coding-plan$/.exec(id);
+  if (m) {
+    const fam = m[1] === 'zai' ? 'Z.ai' : 'BigModel';
+    return `${fam}（${planKinds[m[1]] || '个人/团队'}）`;
+  }
+  if (/^builtin:(zai|bigmodel)-start-plan$/.test(id)) return 'Start Plan';
+  return (name && String(name).trim()) || id;
+}
+
+// 供应商条目（智能起名与视觉代理共用），列表范围与 ZCode 界面的供应商列表
+// 保持一致：
+// - 内置套餐（builtin:*）：有地址、密钥才列出（无密钥的 helper 无法在会话外
+//   调用，如未配 key 的 API Key 型条目）；
+// - 自定义供应商：以 provider_config.json 的 providerOrder 为准（ZCode 界面的
+//   自定义列表就来自它），provider 表里不在其中的残留条目（已弃用的中转等）
+//   不列出；
+// - 协议：api.type / kind 缺失时按地址推断（含 anthropic → anthropic，含
+//   openai 或以 /v\d 结尾 → openai），两个都推不出才放弃该条目。
+// 两张来源表同 id 合并（模型并集、原始名收进别名）。models 为该供应商的
+// 可选模型（下拉用，可为空）。导出以便测试
+export function listTitleGenProviders() {
+  const out = [];
   const byId = new Map();
-  const v2 = readJsonFile(join(homedir(), '.zcode', 'v2', 'config.json'));
-  for (const [id, p] of Object.entries((v2 && typeof v2.provider === 'object' && v2.provider) || {})) {
-    const entry = { id, name: (p && typeof p.name === 'string' && p.name.trim()) || id, aliases: [] };
-    list.push(entry);
+  const planKinds = codingPlanKindByFamily();
+  const add = (id, { name, aliases = [], kind, baseUrl, apiKey, models = [] }) => {
+    baseUrl = typeof baseUrl === 'string' ? baseUrl.trim() : '';
+    apiKey = typeof apiKey === 'string' ? apiKey.trim() : '';
+    if (!id || !baseUrl || !apiKey) return;
+    let format = /anthropic/i.test(String(kind)) ? 'anthropic' : /openai/i.test(String(kind)) ? 'openai' : '';
+    if (!format) format = /anthropic/i.test(baseUrl) ? 'anthropic'
+      : (/openai/i.test(baseUrl) || /\/v\d+$/.test(baseUrl)) ? 'openai' : '';
+    if (!format) return;
+    models = models.filter(Boolean);
+    const known = byId.get(id);
+    if (known) {
+      known.models = [...new Set([...known.models, ...models])];
+      for (const a of aliases) if (a && !known.aliases.includes(a)) known.aliases.push(a);
+      return;
+    }
+    const shown = titleGenProviderDisplayName(id, name, planKinds);
+    const entry = {
+      id, name: shown, aliases: [...new Set(aliases.filter((a) => a && a !== shown))],
+      format, baseUrl, apiKey, models: [...new Set(models)],
+    };
     byId.set(id, entry);
-  }
+    out.push(entry);
+  };
+
+  const v2 = readJsonFile(join(homedir(), '.zcode', 'v2', 'config.json'));
+  const providers = (v2 && typeof v2.provider === 'object' && v2.provider) || {};
   const rulesDoc = readJsonFile(join(homedir(), '.zcode', 'v2', 'provider_config.json'));
   const rules = (rulesDoc && rulesDoc.config?.providerConfigRules?.providerRules) || [];
-  for (const r of rules) {
-    if (!r || typeof r.providerId !== 'string' || !r.providerId) continue;
-    const existing = byId.get(r.providerId);
-    if (existing) {
-      const alias = (typeof r.providerName === 'string' && r.providerName.trim()) || r.providerId;
-      if (alias !== existing.name && !existing.aliases.includes(alias)) existing.aliases.push(alias);
-      continue;
+  const ruleById = new Map(rules.filter((r) => r && typeof r.providerId === 'string').map((r) => [r.providerId, r]));
+  // 同一 id 在两张表的字段并起来（provider 表优先：地址/密钥以桌面实际在用的为准）
+  const addMerged = (id) => {
+    const p = providers[id];
+    if (p !== undefined && (p === null || typeof p !== 'object')) return;
+    const r = ruleById.get(id) || {};
+    const c = r.config || {};
+    add(id, {
+      name: (p && p.name) || r.providerName,
+      aliases: [r.providerName, p && p.name],
+      kind: (p && p.kind) || c.api?.type,
+      baseUrl: (p && p.options?.baseURL) || c.api?.baseUrl,
+      apiKey: (p && p.options?.apiKey) || c.access?.apiKey,
+      models: [...Object.keys((p && p.models) || {}), ...(c.modelOrder || []), ...(c.personalModelIds || [])],
+    });
+  };
+
+  // 内置套餐在前（BigModel（个人/团队）→ Start Plan 的顺序）
+  for (const id of Object.keys(providers)) {
+    if (id.startsWith('builtin:')) addMerged(id);
+  }
+  // 自定义供应商按界面顺序（providerOrder）
+  const order = (rulesDoc && Array.isArray(rulesDoc.config?.providerOrder) ? rulesDoc.config.providerOrder : [])
+    .filter((id) => typeof id === 'string');
+  for (const id of order) addMerged(id);
+  return out;
+}
+
+// Anthropic Messages 文本调用（无系统提示词，单条用户消息）。max_tokens 给足
+// 2048：glm 系列等推理模型先输出 thinking 块再出正文，给小了会全部耗在
+// 思考上（stop_reason=max_tokens 且没有任何 text 块），起名调用不在意这点额度
+async function callAnthropicText(baseUrl, apiKey, model, content) {
+  const url = baseUrl.replace(/\/+$/, '') + '/v1/messages';
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TITLE_GEN_TIMEOUT_MS);
+  try {
+    const resp = await fetch(url, {
+      method: 'POST', signal: ctrl.signal,
+      headers: { 'content-type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify({ model, max_tokens: 2048, messages: [{ role: 'user', content }] }),
+    });
+    const body = await resp.text();
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${body.slice(0, 300)}`);
+    const doc = JSON.parse(body);
+    const text = Array.isArray(doc.content)
+      ? doc.content.filter((b) => b && b.type === 'text').map((b) => b.text || '').join('') : '';
+    if (!text) throw new Error(doc.stop_reason === 'max_tokens'
+      ? '模型的思考用完了输出上限，仍未给出标题' : '响应中没有文本内容');
+    return text;
+  } catch (err) {
+    if (err && err.name === 'AbortError') throw new Error(`请求超时（${Math.round(TITLE_GEN_TIMEOUT_MS / 1000)} 秒）`);
+    throw err;
+  } finally { clearTimeout(timer); }
+}
+
+// OpenAI Chat Completions 文本调用；baseURL 已含 /v1 时不重复拼
+async function callOpenAiText(baseUrl, apiKey, model, content) {
+  const base = baseUrl.replace(/\/+$/, '');
+  const url = /\/v\d+$/.test(base) ? base + '/chat/completions' : base + '/v1/chat/completions';
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), TITLE_GEN_TIMEOUT_MS);
+  try {
+    const resp = await fetch(url, {
+      method: 'POST', signal: ctrl.signal,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ model, max_tokens: 2048, messages: [{ role: 'user', content }] }),
+    });
+    const body = await resp.text();
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${body.slice(0, 300)}`);
+    const doc = JSON.parse(body);
+    const text = doc.choices?.[0]?.message?.content || '';
+    if (typeof text !== 'string' || !text.trim()) throw new Error('响应中没有文本内容');
+    return text;
+  } catch (err) {
+    if (err && err.name === 'AbortError') throw new Error(`请求超时（${Math.round(TITLE_GEN_TIMEOUT_MS / 1000)} 秒）`);
+    throw err;
+  } finally { clearTimeout(timer); }
+}
+
+// 生成标题。provider 三种取值：
+// - 'session'：跟随当前会话——从任务索引解析该会话正在用的供应商与模型
+//   （model 已填时用填写的），供应商需在可直连列表内；
+// - ''：不跟随，用配置里的 baseUrl/apiKey/format 直连；
+// - 供应商 id：按列表解析直连；id 已被删时退回保存时留下的地址/密钥副本。
+// 输出统一清洗为单行短标题。导出以便测试
+export async function generateTitleWith(cfg, rawText, dataRoot = '', sessId = '') {
+  const text = String(rawText || '').trim().replace(/\s+/g, ' ').slice(0, TITLE_GEN_MAX_TEXT);
+  const prompt = (cfg.prompt && cfg.prompt.trim()) || titleGenDefaultPrompt();
+  const userContent = `${prompt}\n\n会话的用户消息：\n${text}`;
+  const providerId = (cfg.provider || '').trim();
+  const model = (cfg.model || '').trim();
+  const conn = await resolveTitleGenConnection(cfg, providerId, model, dataRoot, sessId);
+  const raw = conn.format === 'anthropic'
+    ? await callAnthropicText(conn.baseUrl, conn.apiKey, conn.model, userContent)
+    : await callOpenAiText(conn.baseUrl, conn.apiKey, conn.model, userContent);
+  const title = cleanGeneratedTitle(raw);
+  if (!title) throw new Error('模型未返回可用标题');
+  return title;
+}
+
+// 直连前的连接解析（见 generateTitleWith 的取值说明）；解析不出抛明确错误
+async function resolveTitleGenConnection(cfg, providerId, model, dataRoot, sessId) {
+  if (providerId === 'session') {
+    if (!sessId || !dataRoot) {
+      throw new Error('跟随当前会话需要会话信息（测试按钮请选择具体供应商或“不跟随”）');
+    }
+    const task = await getTaskProviderModel(dataRoot, sessId);
+    if (!task || !task.providerId) throw new Error('索引中查不到该会话的供应商信息');
+    const entry = listTitleGenProviders().find((p) => p.id === task.providerId);
+    if (!entry) throw new Error(`会话供应商 ${task.providerId} 无法在会话外直连（无密钥或协议未知）`);
+    const useModel = model || task.modelId;
+    if (!useModel) throw new Error('未能确定会话当前模型，请手动填写模型');
+    return { format: entry.format, baseUrl: entry.baseUrl, apiKey: entry.apiKey, model: useModel };
+  }
+  if (providerId) {
+    const entry = listTitleGenProviders().find((p) => p.id === providerId);
+    if (entry) {
+      if (!model) throw new Error('已选择供应商，但未填写模型');
+      return { format: entry.format, baseUrl: entry.baseUrl, apiKey: entry.apiKey, model };
+    }
+    // 供应商已被删：退回保存时的地址/密钥副本
+    if (cfg.baseUrl && cfg.apiKey && cfg.format) {
+      if (!model) throw new Error('已删除的供应商需手动填写模型');
+      return { format: cfg.format, baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, model };
     }
-    const entry = { id: r.providerId, name: (typeof r.providerName === 'string' && r.providerName.trim()) || r.providerId, aliases: [] };
-    list.push(entry);
-    byId.set(r.providerId, entry);
+    throw new Error(`供应商 ${providerId} 已不可用（未保存地址/密钥副本），请重新选择`);
+  }
+  // 不跟随（自填地址）
+  if (!cfg.baseUrl || !cfg.apiKey || !cfg.format) {
+    throw new Error('不跟随（自填地址）需要填写接口地址、API Key 与协议');
+  }
+  if (!model) throw new Error('不跟随（自填地址）需要填写模型');
+  return { format: cfg.format, baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, model };
+}
+
+// 清洗模型输出：去思考块/代码围栏/首尾引号/序号/末尾标点，取首个非空行并限长。
+// 模型可能沿用官方起名的习惯回 JSON 对象，此时取其 title 字段。导出以便测试
+export function cleanGeneratedTitle(text) {
+  let t = String(text || '').replace(/<think>[\s\S]*?<\/think>/gi, '').trim();
+  // 整段包在代码围栏里时先去掉围栏标记（先取行会把「```json」当成标题内容）
+  t = t.replace(/^```[a-zA-Z]*\s*\n?/, '').replace(/\n?```\s*$/, '').trim();
+  let line = t.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || '';
+  line = line.replace(/^```[a-zA-Z]*\s*/, '').replace(/```\s*$/, '');
+  try {
+    const doc = JSON.parse(line);
+    if (doc && typeof doc.title === 'string') line = doc.title;
+  } catch { /* 不是 JSON，按纯文本处理 */ }
+  line = line.replace(/^["'「『“]+/, '').replace(/["'」』”]+$/, '');
+  line = line.replace(/^\d+[.、)\]]\s*/, '');
+  line = line.replace(/[.。!！?？，,;；:：]\s*$/, '');
+  line = line.replace(/\s+/g, ' ').trim();
+  const chars = [...line];
+  if (chars.length > TITLE_GEN_MAX_TITLE) {
+    line = chars.slice(0, TITLE_GEN_MAX_TITLE).join('');
+    // 截断落在英文单词中间时退到词边界，避免出现半个单词
+    if (line.includes(' ')) line = line.slice(0, line.lastIndexOf(' '));
   }
-  return list;
+  return line.trim();
 }
 
 // zcode-vision 配置校验：只保留已知字段并规范化；出错时返回中文原因。
@@ -1337,7 +2122,11 @@ export function validateVisionConfig(raw) {
     names.add(name);
     proxy.name = name;
     if (!(proxy.baseUrl || '').trim() && !(proxy.useProvider || '').trim()) return [null, `代理 ${name} 缺少 baseUrl（或设置 useProvider 跟随供应商）`];
-    if (!(proxy.model || '').trim()) return [null, `代理 ${name} 缺少 model`];
+    // 跟随会话（useProvider=session）时允许 model 留空：留空 = 用会话当前模型
+    //（zcode-vision ≥1.6.1 支持）；其余情况必须填写
+    if (!(proxy.model || '').trim() && proxy.useProvider !== 'session') {
+      return [null, `代理 ${name} 缺少 model`];
+    }
     if (proxy.baseUrl) proxy.baseUrl = proxy.baseUrl.trim();
     if (proxy.model) proxy.model = proxy.model.trim();
     if (proxy.useProvider) proxy.useProvider = proxy.useProvider.trim();
@@ -1447,16 +2236,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 +2259,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 +2292,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 +2390,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 +2430,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 +2508,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 +2531,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 +2597,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 +2615,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 +2646,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 +2716,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 +2777,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 +2885,35 @@ 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 …）
-function runZcodeCli(subArgs, timeoutMs = 120000) {
+// 运行 zcode CLI 子命令（plugins … 默认走 plugins 代理范围；智能起名的
+// 无界面提问传 none——模型 API 直连，不走下载代理）
+function runZcodeCli(subArgs, timeoutMs = 120000, scope = 'plugins') {
   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, scope);
 }
 
 // 比对市场清单与已装清单：每个插件的已装版本与最新版本。导出以便测试。
@@ -1896,6 +2934,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 {
@@ -1931,12 +2984,30 @@ export function writeAgents(body, agentsFile) {
   return [200, { ok: true, content: body.content }];
 }
 
+// 路径不存在时的还原尝试。宿主把消息里的反斜杠路径渲染成文件 chip 时，markdown
+// 会把 “\.” 当转义序列吃掉反斜杠（Administrator\.zcode 变成 Administrator.zcode），
+// 其余分隔符再统一显示为 /，chip 上拿到的就是这种坏路径。把每个“段名.点开头后缀”
+// 形式的段试着拆回两级（Administrator.zcode → Administrator/.zcode），哪个变体
+// 真实存在就用哪个；都不存在返回 null，按原路径走 not-found。导出以便测试脚本直接驱动。
+export function recoverSwallowedSeparator(rawPath) {
+  const segs = String(rawPath).split(/[\\/]/);
+  for (let i = 0; i < segs.length; i++) {
+    const dot = segs[i].indexOf('.');
+    if (dot <= 0) continue; // 段里没有点，或本身就是 .zcode 这类点开头目录
+    const candidate = [...segs.slice(0, i), segs[i].slice(0, dot), segs[i].slice(dot), ...segs.slice(i + 1)].join(sep);
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
 // 在系统文件管理器中定位文件：
 // Linux 走 freedesktop FileManager1.ShowItems（Dolphin/Nautilus 均支持），无会话服务时回退打开所在目录；
 // macOS 用 open -R；Windows 用 explorer /select。导出以便测试脚本直接驱动。
 export function revealInFileManager(rawPath) {
   return new Promise((resolveReveal) => {
-    const p = typeof rawPath === 'string' ? rawPath.trim() : '';
+    let p = typeof rawPath === 'string' ? rawPath.trim() : '';
     if (!p || !isAbsolute(p)) {
       resolveReveal([400, { ok: false, code: 'invalid-path', error: '无效的路径' }]);
       return;
@@ -1991,25 +3062,46 @@ export function openFolder(rawPath) {
   });
 }
 
-// 用系统默认应用打开文件（或文件夹）：macOS 用 open；Windows 用 explorer；
-// Linux 用 xdg-open。导出以便测试脚本直接驱动。
+// 用系统默认应用打开文件（或文件夹）：macOS 用 open；Windows 走 rundll32 的
+// FileProtocolHandler（等价 ShellExecute，启动失败时退回 cmd start）；Linux 用
+// xdg-open。导出以便测试脚本直接驱动。Windows 上不能用 explorer.exe <文件路径>：
+// 那只会在资源管理器里定位该文件（打开所在目录并选中），不会启动默认关联应用。
 export function openWithDefaultApp(rawPath) {
   return new Promise((resolveOpen) => {
-    const p = typeof rawPath === 'string' ? rawPath.trim() : '';
+    let p = typeof rawPath === 'string' ? rawPath.trim() : '';
     if (!p || !isAbsolute(p)) {
       resolveOpen([400, { ok: false, code: 'invalid-path', error: '无效的路径' }]);
       return;
     }
     if (!existsSync(p)) {
-      resolveOpen([400, { ok: false, code: 'not-found', error: '文件不存在' }]);
-      return;
+      // chip 带来的路径可能被宿主渲染弄坏（见 recoverSwallowedSeparator），先试还原
+      const recovered = recoverSwallowedSeparator(p);
+      if (!recovered) {
+        resolveOpen([400, { ok: false, code: 'not-found', error: '文件不存在' }]);
+        return;
+      }
+      p = recovered;
     }
     const done = (err) => resolveOpen(err ? [500, { ok: false, error: err.message }] : [200, { ok: true }]);
     if (process.platform === 'darwin') execFile('open', [p], { timeout: 5000 }, done);
     else if (process.platform === 'win32') {
-      const child = spawn('explorer.exe', [p], { detached: true, stdio: 'ignore' });
-      child.on('error', done);
-      child.on('close', () => done(null));
+      // rundll32 的参数不经 shell 解释，路径里的空格、%、& 等字符都安全；
+      // start 的第一个引号参数是窗口标题，兜底时必须先给空标题再给路径。
+      // 进程拉起即算成功：系统里没有该类型的关联应用时 rundll32 会弹
+      // “你要如何打开这个文件”对话框并一直挂着，不能等它退出才回话
+      let settled = false;
+      const finish = (err) => {
+        if (settled) return;
+        settled = true;
+        done(err);
+      };
+      const child = spawn('rundll32.exe', ['url.dll,FileProtocolHandler', p], { detached: true, stdio: 'ignore', windowsHide: true });
+      child.on('spawn', () => finish(null));
+      child.on('error', () => {
+        const viaCmd = spawn('cmd.exe', [`/d /s /c start "" "${p}"`], { windowsVerbatimArguments: true, detached: true, stdio: 'ignore', windowsHide: true });
+        viaCmd.on('spawn', () => finish(null));
+        viaCmd.on('error', finish);
+      });
     } else execFile('xdg-open', [p], { timeout: 5000 }, done);
   });
 }