zcode-pro 0.20.3 → 1.1.0

package/package.json

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

package/src/host/helper.mjs

@@ -11,13 +11,13 @@ import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from 'no
 import { homedir, tmpdir, userInfo } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readSettings, writeSettingsAtomic, remapSettingsPaths, isProjectOpenInTabs } from './settings.mjs';
-import { taskIndexPath, probeTaskIndexWritable, remapTaskIndexPaths, taskIndexDriverAvailable, listOverriddenTitles, listTaskWorkspaceMap, setTaskTitleIfNotOverridden, setCustomSessionTitle, isTaskTitleOverridden, reconcileCustomTitles, getTaskProviderModel } from './taskIndex.mjs';
+import { taskIndexPath, probeTaskIndexWritable, remapTaskIndexPaths, taskIndexDriverAvailable, listOverriddenTitles, listTaskWorkspaceMap, setTaskTitleIfNotOverridden, setCustomSessionTitle, isTaskTitleOverridden, reconcileCustomTitles, getTaskProviderModel, listVirtualProjects } from './taskIndex.mjs';
 import { pickFolderSystem } from './pickFolder.mjs';
 import { reorderWorkspaceTasks, reorderGroupMembers } from './taskOrder.mjs';
 import { webdavRequest, webdavPutWithMkcol, webdavHttpText, parseWebdavListing, findCurl } from './webdav.mjs';
 import { resolveZcodeExecutable } from './paths.mjs';
 
-const VERSION = '0.20.3';
+const VERSION = '1.1.0';
 
 // 全局提示词固定在用户主目录：官方加载器按 HOME/USERPROFILE 拼 .zcode/AGENTS.md，
 // 不读 ZCODE_DATA_BASE_DIR（数据根迁走时全局指令仍在原位）。
@@ -56,7 +56,6 @@ export function defaultConfig() {
       projectMenu: true,        // 项目菜单增强：自定义别名 + 切换文件夹 + 打开文件夹 + 复制路径（含侧栏别名渲染）
       taskOrder: true,          // 侧边栏会话拖动排序持久化
       fileActions: true,        // 文件菜单：默认应用打开 / 打开所在目录
-      pinnedKeepCollapsed: false, // 点击置顶会话保持项目折叠（实验性：会先展开再缩起，有闪烁）
       autoUpdatePlugins: false,  // 启动时自动更新已装的 zcode-plugins 插件（含安装市场里新增的）
       sessionSwitch: true,     // 会话快捷切换（alt+z 上次会话；按住 alt x/c 弹窗导航，类 alt+tab）
       titleLock: true,        // 会话名锁定：手动重命名过的会话不被运行时推送的自动标题覆盖（侧栏钉回索引库中的名字）
@@ -324,6 +323,11 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
           current.devMode = body.devMode;
         }
         if (body && typeof body === 'object' && body.features && typeof body.features === 'object') {
+          // 会话名锁定开关的每次变化都落日志：它被意外关闭两次（页面里是关、
+          // 配置文件是开，来源不明），有记录才能查到是谁改的
+          if (typeof body.features.titleLock === 'boolean' && body.features.titleLock !== (loadConfig(configFile).features.titleLock !== false)) {
+            titleGenLog(dataRoot, `titleLock ${body.features.titleLock ? 'on' : 'off'}（此前为 ${!body.features.titleLock ? 'on' : 'off'}）`);
+          }
           applyFeaturesPartial(current.features, body.features);
         }
         if (body && typeof body === 'object' && typeof body.idleReclaimMinutes === 'number' && Number.isFinite(body.idleReclaimMinutes)) {
@@ -335,9 +339,26 @@ 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.shortcuts && typeof body.shortcuts === 'object') {
+          const patch = {};
+          for (const k of ['switchLast', 'switchPrev', 'switchNext', 'switchRecent', 'switchAttention']) {
+            const v = body.shortcuts[k];
+            if (typeof v === 'string' && /^[a-z0-9]$/.test(v)) patch[k] = v;
+          }
+          current.shortcuts = { ...(current.shortcuts || {}), ...patch };
+        }
         if (body && typeof body === 'object' && body.titleGen && typeof body.titleGen === 'object') {
           current.titleGen = mergeTitleGenConfig({ ...current.titleGen, ...body.titleGen });
         }
+        // 一次性迁移标记（如别名迁移弹窗的“暂不迁移”）：按项合并，只接受布尔值
+        if (body && typeof body === 'object' && body.migrations && typeof body.migrations === 'object') {
+          const patch = {};
+          for (const [k, v] of Object.entries(body.migrations)) {
+            if (typeof v === 'boolean') patch[k] = v;
+          }
+          current.migrations = { ...(current.migrations || {}), ...patch };
+        }
         saveConfig(configFile, current);
         json(res, 200, { ok: true, config: current });
         return;
@@ -383,6 +404,16 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
         json(res, ...writeAgents(body, agentsFile));
         return;
       }
+      if (req.method === 'GET' && url.pathname === '/projects-v2') {
+        // 虚拟项目（3.16.1 起 projects/project_roots 表）：别名迁移弹窗用 roots
+        // 区分“目录已并入其他项目”与“项目已删除”。读不到时 available=false，
+        // 注入端降级为纯 DOM 检测
+        const data = await listVirtualProjects(dataRoot);
+        json(res, 200, data
+          ? { ok: true, available: true, ...data }
+          : { ok: true, available: false, projects: [], deletedRoots: [] });
+        return;
+      }
       if (req.method === 'GET' && url.pathname === '/projects') {
         const settings = readSettings(settingsFile);
         const projects = (settings.recentProjects || []).map((p) => {
@@ -1106,7 +1137,9 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
       // —— zcode-plugins 市场更新：读状态（带 30 分钟节流的市场同步）与执行更新 ————
       if (req.method === 'GET' && url.pathname === '/plugins/status') {
         await ensureZcodePluginsMarketplace();
-        if (Date.now() - lastMarketplaceSync > 30 * 60 * 1000) {
+        // 有更新任务在执行或排队时跳过这里的节流同步（任务本身会同步市场并刷新
+        // 时间戳），避免两处同时跑 marketplace update
+        if (!pluginsUpdateJob && Date.now() - lastMarketplaceSync > 30 * 60 * 1000) {
           await runZcodeCli(['plugins', 'marketplace', 'update', ZCODE_PLUGINS_MARKETPLACE], 60000);
           lastMarketplaceSync = Date.now();
         }
@@ -1120,40 +1153,8 @@ export function startHelper({ port, token, dataRoot, state, agentsFile = default
       }
       if (req.method === 'POST' && url.pathname === '/plugins/update') {
         const body = await readBody(req);
-        // 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 });
-        if (!sync.ok && sync.code !== 'cli-not-found') {
-          json(res, 500, { ok: false, code: 'plugins-update', error: sync.error || sync.output || 'marketplace update 失败', steps });
-          return;
-        }
-        const status = pluginUpdateStatus();
-        if (status) {
-          let updated = 0;
-          for (const p of status.plugins) {
-            if (only && p.name !== only) continue;
-            if (p.installed && p.hasUpdate) {
-              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 && 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;
-            }
-          }
-          json(res, 200, { ok: steps.every((s) => s.ok), updated, steps, ...pluginUpdateStatus() });
-          return;
-        }
-        json(res, 200, { ok: sync.ok, updated: 0, steps });
+        const result = await enqueuePluginsUpdate(body);
+        json(res, result.status, result.payload);
         return;
       }
       json(res, 404, { ok: false, error: 'not found' });
@@ -1386,16 +1387,17 @@ async function runSettingsSync({ direction, dataRoot, configFile, config, proxyU
 }
 
 // 上传：每组独立一个云端文件（zcodepro.json / model.json，始终最新一版），勾选几组
-// 写几个；写前预读云端内容，别名与本机的合并后再写（合并规则见 mergeAliases），
-// 其余内容整份覆盖。同一份内容再写一个带时间戳的历史版本文件，供下载时任选版本
-// 恢复（旧版 zcode-pro 仍读固定名）；历史版本最多保留 historyLimit 个（同一时间戳
-// 的各组文件算一个），上传成功后自动删除更早的
+// 写几个。aliases 不再上传——3.16.1 起别名功能已停用（官方“编辑项目”改名），
+// 且各机器项目路径不同，同步别名只会互相带来无效路径。同一份内容再写一个带
+// 时间戳的历史版本文件，供下载时任选版本恢复（旧版 zcode-pro 仍读固定名）；
+// 历史版本最多保留 historyLimit 个（同一时间戳的各组文件算一个），上传成功后
+// 自动删除更早的
 async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
   const keep = Number.isInteger(sync.historyLimit) ? sync.historyLimit : defaultConfig().sync.historyLimit;
   const docs = {};
   if (sync.include.zcodepro) {
-    // sync（本机的同步配置与凭据）与 version（本机 helper 版本）不外发
-    const { sync: _s, version: _v, ...rest } = config;
+    // sync（本机的同步配置与凭据）、version（本机 helper 版本）与 aliases 不外发
+    const { sync: _s, version: _v, aliases: _a, ...rest } = config;
     docs.zcodepro = rest;
   }
   if (sync.include.model) {
@@ -1419,11 +1421,6 @@ async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
     for (const kind of Object.keys(docs)) {
       const remote = await fetchSyncDoc(sync, proxyUrl, kind);
       if (remote.error) return remote;
-      // 别名先与云端合并：本机没配过的条目从云端带上，别让这次上传把别的机器配的别名顶掉
-      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');
@@ -1457,8 +1454,9 @@ async function runSyncPush({ dataRoot, configFile, config, sync, proxyUrl }) {
 }
 
 // 下载：把云端所选组应用到本机（各组独立文件，勾选几组读几组，可只覆盖模型设置）。
-// 覆盖前留 .zcodepro-backup 备份；zcodepro 组覆盖功能/样式/代理，别名与本机的
-// 合并（合并规则见 mergeAliases）；sync 配置与凭据始终保留本机的
+// 覆盖前留 .zcodepro-backup 备份；zcodepro 组覆盖功能/样式/代理，别名不受影响
+//（3.16.1 起别名已停用，且云端备份里的别名多是其他机器的路径）；sync 配置与
+// 凭据始终保留本机的
 async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
   // 先把勾选组的云端数据全部读到（任何一组读取失败都不动本机文件），再逐组应用
   const docs = {};
@@ -1476,8 +1474,9 @@ async function runSyncPull({ dataRoot, configFile, config, sync, proxyUrl }) {
 }
 
 // 把云端读到的各组数据落到本机（runSyncPull 与按文件的历史版本导入共用）：
-// zcodepro 组覆盖功能/样式/代理（sync 配置与凭据保留本机的），别名与本机的合并，
-// model 组覆盖 v2/config.json 的 provider 与 provider_config.json；覆盖前都留备份
+// zcodepro 组覆盖功能/样式/代理（sync 配置与凭据保留本机的），别名不导入
+//（云端备份可能出自别的机器，路径在本机无效），model 组覆盖 v2/config.json 的
+// provider 与 provider_config.json；覆盖前都留备份
 function applySyncDocs({ docs, dataRoot, configFile, config, sync }) {
   const applied = [];
   const backupFile = (p) => {
@@ -1494,10 +1493,8 @@ function applySyncDocs({ docs, dataRoot, configFile, config, sync }) {
     const next = loadConfig(configFile);
     applyFeaturesPartial(next.features, rz.features);
     next.styles = applyStylesPartial(next.styles, rz.styles);
-    // 别名与本机的合并（本机配过的优先），不再整份替换——各机器项目路径不同，
-    // 合并后两边的别名都在，谁也不会被对方的同步顶掉
-    const remoteAliases = sanitizeAliases(rz.aliases);
-    if (remoteAliases) next.aliases = mergeAliases(next.aliases, remoteAliases);
+    // 别名保持本机的原样：云端备份里的别名可能出自其他机器（路径在本机无效），
+    // 且 3.16.1 起别名功能已停用，不再导入
     if (typeof rz.proxy === 'string') {
       const v = rz.proxy.trim();
       if (v === '' || /^https?:\/\/\S+:\d+$/.test(v)) next.proxy = v;
@@ -3056,7 +3053,8 @@ async function runHeadroomHook(args, timeoutMs = 30000) {
   });
 }
 
-// 解析 ensure-proxy.sh status 输出为结构化字段（字段名以脚本 hr_status 的输出为准）。
+// 解析 ensure-proxy(.sh/.mjs) status 输出为结构化字段（字段名以脚本 hr_status 的输出为准；
+// headroom 插件 1.3.0+ 多实例模式由 hr-multi 输出同名字段，另附 instance: 行）。
 // 导出以便测试脚本直接驱动。
 export function parseHeadroomStatus(text) {
   const raw = String(text || '');
@@ -3066,15 +3064,23 @@ export function parseHeadroomStatus(text) {
   };
   const proxy = line('proxy') || '';
   const ps = line('power-save-auto-cpu') || '';
+  // 多实例模式的实例行：instance: <端口> <格式> <上游> <up|down> <供应商列表>
+  const instances = [];
+  for (const m of raw.matchAll(/^instance: (\d+) (\S+) (\S+) (up|down) ?(.*)$/gm)) {
+    instances.push({ port: Number(m[1]), format: m[2], upstream: m[3], up: m[4] === 'up', providers: m[5] || '' });
+  }
   return {
     up: /^up\b/.test(proxy),
     port: Number(/(\d+)\)?$/.exec(proxy)?.[1]) || null,
     managed: line('managed-by-plugin'),
+    multi: instances.length > 0 || /^instances: \d+$/m.test(raw),
+    instances,
     backend: line('current-backend'),
     desiredBackend: line('desired-backend'),
     powerMode: line('power-mode'),
     saverDetect: line('saver-detect'),
-    watcherRunning: /^watcher: running/m.test(raw),
+    // watcher 行存在才是真状态；多实例模式不输出该行时为 null（面板显示 —）
+    watcherRunning: /^watcher: /m.test(raw) ? /^watcher: running/m.test(raw) : null,
     saverHint: (raw.split('\n').find((l) => l.startsWith('注意：')) || '').trim() || null,
     powerSaveMode: (/^(battery|saver|off)/.exec(ps) || [])[1] || null,
     watchInterval: Number(/\(interval (\d+)s\)/.exec(ps)?.[1]) || null,
@@ -3221,6 +3227,38 @@ function runZcodeCli(subArgs, timeoutMs = 120000, scope = 'plugins') {
   return runNodeScript([bundle, ...subArgs], timeoutMs, scope);
 }
 
+// 简单版本号比较（a<b 返回 -1，相等 0，a>b 返回 1）：主版本按点分段，
+// 数字段按数值比、非数字段按字符串比；主版本相同时带 pre-release 后缀
+// （如 1.7.0-beta）低于正式版，后缀内部同样按段比较；空版本视为最旧
+// （已装版本未知时当作可更新）
+function cmpVersion(a, b) {
+  const cmpSegs = (A, B) => {
+    for (let i = 0; i < Math.max(A.length, B.length); i++) {
+      const x = A[i] || '';
+      const y = B[i] || '';
+      const nx = /^\d+$/.test(x) ? Number(x) : null;
+      const ny = /^\d+$/.test(y) ? Number(y) : null;
+      if (nx !== null && ny !== null) {
+        if (nx !== ny) return nx < ny ? -1 : 1;
+      } else if (x !== y) {
+        return x < y ? -1 : 1;
+      }
+    }
+    return 0;
+  };
+  const parse = (v) => {
+    const s = String(v || '');
+    const i = s.indexOf('-');
+    return { pre: i >= 0 ? s.slice(i + 1) : null, core: (i >= 0 ? s.slice(0, i) : s).split('.') };
+  };
+  const A = parse(a), B = parse(b);
+  const c = cmpSegs(A.core, B.core);
+  if (c !== 0) return c;
+  if ((A.pre === null) !== (B.pre === null)) return A.pre === null ? 1 : -1;
+  if (A.pre !== B.pre) return cmpSegs(A.pre.split('.'), B.pre.split('.'));
+  return 0;
+}
+
 // 比对市场清单与已装清单：每个插件的已装版本与最新版本。导出以便测试。
 export function pluginUpdateStatus() {
   const installedRaw = readJsonFile(join(cliPluginsDir(), 'installed_plugins.json'));
@@ -3234,7 +3272,8 @@ export function pluginUpdateStatus() {
     name: e.name,
     latest: e.version || '',
     installed: mine.get(e.name) || null,
-    hasUpdate: mine.has(e.name) && mine.get(e.name) !== (e.version || ''),
+    // 只有市场版本更高才算可更新：本地高于市场（市场回退/降级）不提示、不自动降级
+    hasUpdate: mine.has(e.name) && cmpVersion(mine.get(e.name), e.version || '') < 0,
   }));
   return { plugins, updates: plugins.filter((e) => e.hasUpdate) };
 }
@@ -3254,6 +3293,63 @@ async function ensureZcodePluginsMarketplace() {
   return { ok: r.ok, output: r.output, error: r.error };
 }
 
+// /plugins/update 并发控制：启动自动更新、打开设置弹窗时的自动触发、手动按钮、
+// 各插件面板的单插件操作都打到这个端点，而 CLI 同时改同一个插件目录会互相破坏。
+// 同目标（全量或同一插件名）的并发请求共用同一次执行结果；
+// 不同目标的请求排队串行，后到的等前一个结束再跑
+let pluginsUpdateJob = null; // { only, promise }：正在执行或排队的任务
+let pluginsUpdateQueue = Promise.resolve();
+
+async function runPluginsUpdateJob(body) {
+  // 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 });
+  if (!sync.ok && sync.code !== 'cli-not-found') {
+    return { status: 500, payload: { ok: false, code: 'plugins-update', error: sync.error || sync.output || 'marketplace update 失败', steps } };
+  }
+  const status = pluginUpdateStatus();
+  if (!status) return { status: 200, payload: { ok: sync.ok, updated: 0, steps } };
+  let updated = 0;
+  for (const p of status.plugins) {
+    if (only && p.name !== only) continue;
+    if (p.installed && p.hasUpdate) {
+      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 && 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;
+    }
+  }
+  return { status: 200, payload: { ok: steps.every((s) => s.ok), updated, steps, ...pluginUpdateStatus() } };
+}
+
+function enqueuePluginsUpdate(body) {
+  const only = typeof body?.name === 'string' && body.name.trim() ? body.name.trim() : null;
+  if (pluginsUpdateJob && pluginsUpdateJob.only === only) return pluginsUpdateJob.promise;
+  const prev = pluginsUpdateQueue;
+  const promise = (async () => {
+    await prev;
+    try {
+      return await runPluginsUpdateJob(body);
+    } finally {
+      if (pluginsUpdateJob && pluginsUpdateJob.promise === promise) pluginsUpdateJob = null;
+    }
+  })();
+  pluginsUpdateQueue = promise.then(() => undefined, () => undefined);
+  pluginsUpdateJob = { only, promise };
+  return promise;
+}
+
 // 读全局提示词（~/.zcode/AGENTS.md）；文件不存在视为空内容。
 export function readAgents(agentsFile) {
   try {

package/src/host/main.mjs

@@ -10,6 +10,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { resolveZcodeExecutable, resolveDataRootDir } from './paths.mjs';
+import { readZcodeVersion } from './version.mjs';
 import { CdpConnection, fetchBrowserWsUrl } from './cdp.mjs';
 import { startHelper } from './helper.mjs';
 import { runSetup } from './setup.mjs';
@@ -154,12 +155,12 @@ async function waitForCdp(port, timeoutMs) {
   return false;
 }
 
-async function buildInjectSource(token, helperPort, features) {
+async function buildInjectSource(token, helperPort, features, zcodeVersion) {
   if (!existsSync(INJECT_BUNDLE)) {
     throw new Error('缺少注入脚本 dist/inject.js，请先运行 npm run build');
   }
   const bundle = readFileSync(INJECT_BUNDLE, 'utf8');
-  const bootstrap = `window.__ZCODEPRO__={helperUrl:'http://127.0.0.1:${helperPort}',token:${JSON.stringify(token)},features:${JSON.stringify(features)}};`;
+  const bootstrap = `window.__ZCODEPRO__={helperUrl:'http://127.0.0.1:${helperPort}',token:${JSON.stringify(token)},features:${JSON.stringify(features)},zcodeVersion:${JSON.stringify(zcodeVersion || '')}};`;
   return bootstrap + '\n' + bundle;
 }
 
@@ -189,6 +190,8 @@ export async function run(argv) {
     throw err;
   }
   winLog(`启动: ZCode=${exe}, CDP 端口 ${args.cdpPort}`);
+  const zcodeVersion = readZcodeVersion(exe);
+  if (args.verbose) console.log(`[zcodepro] ZCode 版本: ${zcodeVersion || '未知（app.asar 读取失败）'}`);
   const dataRoot = resolveDataRootDir();
   const token = randomBytes(16).toString('hex');
   const state = { injectedPages: 0 };
@@ -220,7 +223,7 @@ export async function run(argv) {
   }
 
   // 2. 启动辅助服务
-  const server = await startHelper({ port: args.helperPort, token, dataRoot, state });
+  const server = await startHelper({ port: args.helperPort, token, dataRoot, state, zcodeVersion });
   console.log(`[zcodepro] 辅助服务已就绪: http://127.0.0.1:${args.helperPort} (数据目录 ${dataRoot})`);
 
   // 3. 连接 CDP 并注入（断线自动重连）
@@ -236,7 +239,7 @@ export async function run(argv) {
     server.close();
     process.exit(1);
   }
-  const source = await buildInjectSource(token, args.helperPort, healthRes.features || {});
+  const source = await buildInjectSource(token, args.helperPort, healthRes.features || {}, zcodeVersion);
 
   async function attachConnection() {
     const conn = new CdpConnection(await fetchBrowserWsUrl(args.cdpPort));

package/src/host/taskIndex.mjs

@@ -172,6 +172,103 @@ export async function remapTaskIndexPaths(dataRoot, oldPath, newPath) {
   }
 }
 
+// 虚拟项目清单（projects + project_roots，只读）：别名迁移弹窗用它判断每条别名的
+// 目标现状——路径是某项目的附加目录（3.16.1 多目录合并）还是已删除的项目。
+// 返回 { projects: [{ name, roots: [{ path, primary }] }], deletedRoots: [path] }；
+// 读不到（库缺失/无驱动/查询失败）返回 null，调用方降级为纯 DOM 检测
+export async function listVirtualProjects(dataRoot) {
+  const dbFile = taskIndexPath(dataRoot);
+  if (!existsSync(dbFile)) return null;
+  const driver = await loadDriver();
+  if (!driver) return null;
+  const SQL_ACTIVE = `SELECT p.project_id AS pid, p.name AS name, r.root_path AS path, r.is_primary, p.name_overridden
+    FROM projects p JOIN project_roots r ON r.project_id = p.project_id
+    WHERE p.deleted = 0 AND (p.host_id = 'local' OR p.host_id IS NULL)`;
+  const SQL_DELETED = `SELECT r.root_path AS path
+    FROM projects p JOIN project_roots r ON r.project_id = p.project_id
+    WHERE p.deleted = 1 AND (p.host_id = 'local' OR p.host_id IS NULL)`;
+  // CLI 驱动用制表符分隔行（项目名含引号/逗号都安全；名字含制表符的极端情况不处理）
+  const TAB = "char(9)";
+  try {
+    let activeRows;
+    let deletedRows;
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile, { readOnly: true });
+      try {
+        activeRows = db.prepare(SQL_ACTIVE).all();
+        deletedRows = db.prepare(SQL_DELETED).all();
+      } finally { db.close(); }
+    } else {
+      const act = runCli(dbFile,
+        `SELECT p.project_id || ${TAB} || p.name || ${TAB} || r.root_path || ${TAB} || r.is_primary || ${TAB} || p.name_overridden${SQL_ACTIVE.slice(SQL_ACTIVE.indexOf(' FROM'))};`).stdout;
+      activeRows = act.split('\n').filter(Boolean).map((l) => {
+        const [pid, name, path, primary, overridden] = l.split('\t');
+        return { pid, name, path, primary, name_overridden: overridden };
+      });
+      const del = runCli(dbFile,
+        `SELECT r.root_path FROM projects p JOIN project_roots r ON r.project_id = p.project_id
+        WHERE p.deleted = 1 AND (p.host_id = 'local' OR p.host_id IS NULL);`).stdout;
+      deletedRows = del.split('\n').filter(Boolean).map((p) => ({ path: p }));
+    }
+    const byId = new Map();
+    for (const row of activeRows) {
+      const key = String(row.pid || row.name || '');
+      let proj = byId.get(key);
+      if (!proj) {
+        proj = { id: String(row.pid || ''), name: String(row.name || ''), roots: [], overridden: Number(row.name_overridden) === 1 };
+        byId.set(key, proj);
+      }
+      proj.roots.push({ path: String(row.path || ''), primary: Number(row.is_primary) === 1 });
+    }
+    // 全部出现过的任务工作区（含非项目工作区：draft/独立任务等，它们的任务
+    // 显示在侧栏“任务”分区）：供分区头运行判定把活跃任务按归属分类
+    let allPaths = [];
+    try {
+      if (driver.kind === 'node') {
+        const db = new driver.DatabaseSync(dbFile, { readOnly: true });
+        try { allPaths = db.prepare('SELECT DISTINCT workspace_path FROM tasks').all().map((r) => String(r.workspace_path || '')); } finally { db.close(); }
+      } else {
+        allPaths = runCli(dbFile, 'SELECT DISTINCT workspace_path FROM tasks;').stdout.split('\n').filter(Boolean);
+      }
+    } catch { /* 读不到就不带，调用方只有项目路径 */ }
+    return {
+      projects: [...byId.values()],
+      deletedRoots: deletedRows.map((r) => String(r.path || '')),
+      allPaths,
+    };
+  } catch {
+    return null;
+  }
+}
+
+// 批量查会话终态：task_id → task_status。分区头运行判定用它剔除官方 syncer
+// 卡滞的报告（会话已完成但内存态仍报活跃时，任务行 loader 会一直卡转）。
+// 读不到（库缺失/无驱动）返回 null，调用方按未确认处理
+export async function listTaskStatuses(dataRoot, ids) {
+  const out = {};
+  const dbFile = taskIndexPath(dataRoot);
+  if (!existsSync(dbFile)) return null;
+  const driver = await loadDriver();
+  if (!driver) return null;
+  const esc = (v) => "'" + String(v).replace(/'/g, "''") + "'";
+  const inList = ids.map((id) => esc(id)).join(', ');
+  const sql = `SELECT task_id, task_status, updated_at FROM tasks WHERE task_id IN (${inList})`;
+  try {
+    let rows;
+    if (driver.kind === 'node') {
+      const db = new driver.DatabaseSync(dbFile, { readOnly: true });
+      try { rows = db.prepare(sql).all(); } finally { db.close(); }
+    } else {
+      rows = runCli(dbFile, sql + ';').stdout.split('\n').filter(Boolean)
+        .map((l) => { const [id, st, at] = l.split('|'); return { task_id: id, task_status: st, updated_at: at }; });
+    }
+    for (const r of rows) out[String(r.task_id)] = { status: String(r.task_status || ''), updatedAt: Number(r.updated_at) || 0 };
+    return out;
+  } catch {
+    return null;
+  }
+}
+
 // 已重命名会话的标题表：task_id → title（title_overridden = 1 且未删除）。
 // 只读单条 SELECT，不开事务；库不存在或没有 SQLite 支持时返回空表，
 // 调用方（会话名锁定）自然降级为不干预。

package/src/host/version.mjs

@@ -0,0 +1,51 @@
+// 读取已安装 ZCode 的版本号：从可执行文件旁边的 resources/app.asar（macOS 为
+// Contents/Resources/app.asar）头部解析内嵌 package.json 的 version 字段。
+// asar 结构：偏移 0–15 为头部尺寸描述，偏移 12 处的 u32 是头部 JSON 长度，
+// JSON 紧跟在偏移 16；files["package.json"] 的 offset 相对 16+jsonLen，且实测
+// 存在 4 字节对齐补位，因此多读几字节、从首个 '{' 开始截取再解析。
+// 读取失败一律返回空串：调用方把空串当作“版本未知”，不启用按版本的分支。
+import { closeSync, openSync, readSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// 本启动器常以 ELECTRON_RUN_AS_NODE 方式复用 ZCode 二进制运行，该模式下 Electron
+// 的 fs 仍带 asar 补丁：.asar 路径被当作归档目录而非普通文件，按字节偏移读头部会
+// 全部落空（实测 3.16.1 下读到空串）。noAsar 开关（Electron 官方 API）关闭该拦截；
+// 纯 Node 运行时没有这个属性，赋值无副作用
+process.noAsar = true;
+
+export function zcodeAsarPath(exePath) {
+  if (!exePath) return '';
+  // Electron 约定：Linux/Windows 资源目录在可执行文件旁；macOS 在 Contents/Resources
+  const dir = process.platform === 'darwin'
+    ? join(dirname(exePath), '..', 'Resources')
+    : join(dirname(exePath), 'resources');
+  return join(dir, 'app.asar');
+}
+
+export function readZcodeVersion(exePath) {
+  let fd = 0;
+  try {
+    fd = openSync(zcodeAsarPath(exePath), 'r');
+    const head = Buffer.alloc(16);
+    if (readSync(fd, head, 0, 16, 0) !== 16) return '';
+    const jsonLen = head.readUInt32LE(12);
+    // 头部异常大小说明不是预期的 asar（或文件损坏），直接放弃
+    if (jsonLen <= 0 || jsonLen > 64 * 1024 * 1024) return '';
+    const hdr = Buffer.alloc(jsonLen);
+    if (readSync(fd, hdr, 0, jsonLen, 16) !== jsonLen) return '';
+    const entry = JSON.parse(hdr.toString('utf8')).files?.['package.json'];
+    if (!entry || entry.unpacked || typeof entry.offset !== 'string') return '';
+    const base = 16 + jsonLen + Number(entry.offset);
+    const buf = Buffer.alloc(entry.size + 8);
+    readSync(fd, buf, 0, buf.length, base);
+    const text = buf.toString('utf8');
+    const start = text.indexOf('{');
+    if (start < 0) return '';
+    const version = JSON.parse(text.slice(start, start + entry.size)).version;
+    return typeof version === 'string' ? version : '';
+  } catch {
+    return '';
+  } finally {
+    if (fd) { try { closeSync(fd); } catch { /* ignore */ } }
+  }
+}