zcode-pro 0.16.0__py3-none-any.whl

zcode_pro/app/src/host/main.mjs

@@ -0,0 +1,262 @@
+// ZCode Pro 主流程：
+// 1. 定位 ZCode 可执行文件
+// 2. 若 CDP 端口不可达且 ZCode 未在运行 → 以 --remote-debugging-port 启动 ZCode
+//    （若 ZCode 已在运行但没有调试端口，绝不主动杀进程，只提示用户手动重启）
+// 3. 连接 CDP，向所有页面注入增强脚本（新文档自动注入 + 已加载页面立即注入）
+// 4. 启动本地辅助 HTTP 服务并常驻，CDP 断开时自动重连
+import { spawn, execSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+import { resolveZcodeExecutable, resolveDataRootDir } from './paths.mjs';
+import { CdpConnection, fetchBrowserWsUrl } from './cdp.mjs';
+import { startHelper } from './helper.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const INJECT_BUNDLE = resolve(here, '..', '..', 'dist', 'inject.js');
+
+function usage() {
+  return `ZCode Pro — ZCode 桌面版界面增强启动器
+
+用法: zcode-pro [选项]
+
+选项:
+  --cdp-port <端口>      CDP 调试端口 (默认 9333)
+  --helper-port <端口>   本地辅助服务端口 (默认 47889)
+  --zcode-path <路径>    ZCode 可执行文件路径
+  --inject-only          只注入已运行的实例（要求其带调试端口），不启动新实例
+  --verbose              输出详细日志
+  -h, --help             显示帮助
+
+环境变量:
+  ZCODEPRO_ZCODE_PATH     ZCode 可执行文件路径（同 --zcode-path）
+  ZCODEPRO_CDP_PORT       CDP 端口
+  ZCODEPRO_HELPER_PORT    辅助服务端口
+  ZCODE_DATA_BASE_DIR    ZCode 数据根目录（与 ZCode 自身语义一致）
+`;
+}
+
+function parseArgs(argv) {
+  const out = { cdpPort: 0, helperPort: 0, zcodePath: '', injectOnly: false, verbose: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--cdp-port') out.cdpPort = Number(argv[++i]);
+    else if (a === '--helper-port') out.helperPort = Number(argv[++i]);
+    else if (a === '--zcode-path') out.zcodePath = argv[++i];
+    else if (a === '--inject-only' || a === '--no-launch') out.injectOnly = true;
+    else if (a === '--verbose' || a === '-v') out.verbose = true;
+    else if (a === '-h' || a === '--help') out.help = true;
+    else { console.error('未知参数: ' + a); out.help = true; }
+  }
+  out.cdpPort = out.cdpPort || Number(process.env.ZCODEPRO_CDP_PORT) || 9333;
+  out.helperPort = out.helperPort || Number(process.env.ZCODEPRO_HELPER_PORT) || 47889;
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// 桌面快捷方式启动（Terminal=false）时 stderr 不可见，致命错误用桌面通知兜底；
+// 终端运行或有通知服务缺失时静默退回纯 stderr。
+function guiNotify(title, body) {
+  if (process.platform !== 'linux' || process.stderr.isTTY) return;
+  try {
+    spawnSync('notify-send', ['-a', 'ZCode Pro', '-i', 'zcode', title, body], { stdio: 'ignore', timeout: 4000 });
+  } catch { /* ignore */ }
+}
+
+async function cdpAlive(port) {
+  try { await fetchBrowserWsUrl(port, 1200); return true; } catch { return false; }
+}
+
+// 只检测 ZCode 应用进程是否存在，绝不干预。
+// 注意：zcodepro 自身可能以 ELECTRON_RUN_AS_NODE 方式复用 zcode 二进制运行，
+// 进程名同为 zcode，因此要排除自己的 pid。
+function zcodeAppProcessExists() {
+  try {
+    if (process.platform === 'win32') {
+      execSync('tasklist /FI "IMAGENAME eq ZCode.exe" /NH | find /I "ZCode.exe"', { stdio: 'ignore' });
+      return true;
+    }
+    const out = execSync('pgrep -x zcode 2>/dev/null || true', { encoding: 'utf8' });
+    const pids = out.split('\n').map((s) => s.trim()).filter((s) => /^\d+$/.test(s));
+      // 排除自身（zcodepro 以 ELECTRON_RUN_AS_NODE 运行时进程名也是 zcode）
+    return pids.some((pid) => Number(pid) !== process.pid);
+  } catch {
+    return false;
+  }
+}
+
+function launchZcode(exe, cdpPort, verbose) {
+  // 启动器自身可能以 ELECTRON_RUN_AS_NODE=1 复用 zcode 二进制运行（无系统 node 时的回退），
+  // 该变量绝不能带给拉起的 ZCode——否则新实例同样以纯 Node 模式启动，窗口永远不出现。
+  const env = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  const child = spawn(exe, [`--remote-debugging-port=${cdpPort}`], {
+    detached: true,
+    stdio: 'ignore',
+    env,
+  });
+  child.unref();
+  if (verbose) console.log(`[zcodepro] 已启动 ZCode (pid=${child.pid})，调试端口 ${cdpPort}`);
+}
+
+async function waitForCdp(port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await cdpAlive(port)) return true;
+    await sleep(400);
+  }
+  return false;
+}
+
+async function buildInjectSource(token, helperPort, features) {
+  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)}};`;
+  return bootstrap + '\n' + bundle;
+}
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+  if (args.help) { console.log(usage()); return; }
+  const log = (...a) => { if (args.verbose) console.log('[zcodepro]', ...a); };
+
+  let exe;
+  try {
+    exe = resolveZcodeExecutable(args.zcodePath);
+  } catch (err) {
+    if (err.code === 'ZCODE_NOT_FOUND') guiNotify('ZCode Pro 启动失败', '未找到 ZCode 可执行文件，详见终端输出。');
+    throw err;
+  }
+  const dataRoot = resolveDataRootDir();
+  const token = randomBytes(16).toString('hex');
+  const state = { injectedPages: 0 };
+
+  // 1. 确保 ZCode 带着 CDP 端口在运行
+  if (!(await cdpAlive(args.cdpPort))) {
+    if (args.injectOnly) {
+      console.error(`[zcodepro] --inject-only 模式：端口 ${args.cdpPort} 上没有可注入的 ZCode 实例。`);
+      process.exit(1);
+    }
+    // 直接尝试启动；若单实例锁冲突（已有实例未开调试端口），端口不会起来
+    launchZcode(exe, args.cdpPort, args.verbose);
+    const ok = await waitForCdp(args.cdpPort, 30000);
+    if (!ok) {
+      console.error(`[zcodepro] 等待 ZCode 调试端口 ${args.cdpPort} 超时。`);
+      if (zcodeAppProcessExists()) {
+        console.error('[zcodepro] 检测到 ZCode 已在运行，但未开启调试端口，无法注入。');
+        console.error('[zcodepro] 请手动退出当前 ZCode（zcodepro 不会替你关闭正在运行的实例），然后重新运行 zcodepro。');
+        guiNotify('ZCode Pro 暂无法注入', 'ZCode 已在运行但未开启调试端口，请退出 ZCode 后重新打开 ZCode Pro。');
+      } else {
+        guiNotify('ZCode Pro 启动失败', `等待 ZCode 调试端口 ${args.cdpPort} 超时。`);
+      }
+      process.exit(1);
+    }
+  } else {
+    log(`复用已在监听的 CDP 端口 ${args.cdpPort}`);
+  }
+
+  // 2. 启动辅助服务
+  const server = await startHelper({ port: args.helperPort, token, dataRoot, state });
+  console.log(`[zcodepro] 辅助服务已就绪: http://127.0.0.1:${args.helperPort} (数据目录 ${dataRoot})`);
+
+  // 3. 连接 CDP 并注入（断线自动重连）
+  const injectedTargets = new Map(); // targetId -> sessionId
+  let stopping = false;
+
+  let healthRes;
+  try {
+    healthRes = await fetch(`http://127.0.0.1:${args.helperPort}/health`, { headers: { 'X-ZCodePro-Token': token } }).then((r) => r.json());
+  } catch (err) {
+    console.error(`[zcodepro] 辅助服务健康检查失败: ${err.message}`);
+    server.close();
+    process.exit(1);
+  }
+  const source = await buildInjectSource(token, args.helperPort, healthRes.features || {});
+
+  async function attachConnection() {
+    const conn = new CdpConnection(await fetchBrowserWsUrl(args.cdpPort));
+    await conn.connect();
+    injectedTargets.clear();
+
+    const handleAttach = async (sessionId, targetInfo) => {
+      const targetId = targetInfo?.targetId;
+      if (!targetId || targetInfo?.type !== 'page') return;
+      // 安全护栏：引导脚本内含 helper 鉴权 token，只能注入 ZCode 应用自身的页面。
+      // 外部网站若以内嵌浏览器/网页形式成为 page target，拿到 token 即可调用本地
+      // helper（改写增强配置/别名表等）。规则：放行非 http(s)（file://、应用自有协议）与
+      // 本机回环地址，拦截其余外部网页。代价是 http(s) 非 localhost 的自有页面不注入。
+      const pageUrl = String(targetInfo?.url || '');
+      const isExternalWeb = /^https?:\/\//i.test(pageUrl) && !/^https?:\/\/(127\.0\.0\.1|localhost)(:\d+)?/i.test(pageUrl);
+      if (isExternalWeb) {
+        log('跳过外部页面注入（防止 token 泄露）: ' + pageUrl.slice(0, 120));
+        return;
+      }
+      try {
+        await conn.send('Page.enable', {}, sessionId);
+        await conn.send('Page.addScriptToEvaluateOnNewDocument', { source, runImmediately: true }, sessionId);
+        const res = await conn.send('Runtime.evaluate', { expression: source, silent: true }, sessionId);
+        if (res?.exceptionDetails) log('注入执行异常: ' + String(res.exceptionDetails.exception?.description || '').slice(0, 200));
+        injectedTargets.set(targetId, sessionId);
+        state.injectedPages = injectedTargets.size;
+        conn.onSession(sessionId, (m) => {
+          if (m.type === 'detached') {
+            injectedTargets.delete(targetId);
+            state.injectedPages = injectedTargets.size;
+          }
+        });
+        log(`已注入页面 target=${targetId}`);
+      } catch (err) {
+        log('注入会话失败: ' + err.message);
+      }
+    };
+
+    conn.onSession('', (msg) => {
+      if (msg.type === 'attached') {
+        handleAttach(msg.sessionId, msg.targetInfo).catch((e) => log('attach 处理失败: ' + e.message));
+      }
+    });
+    await conn.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+    return conn;
+  }
+
+  let conn = null;
+  for (let attempt = 0; attempt < 5 && !conn; attempt++) {
+    try {
+      conn = await attachConnection();
+    } catch (err) {
+      log('CDP 连接失败: ' + err.message + '，重试…');
+      await sleep(1000);
+    }
+  }
+  if (!conn) {
+    console.error('[zcodepro] 无法连接 CDP，退出。');
+    server.close();
+    process.exit(1);
+  }
+  console.log('[zcodepro] 已连接 CDP 并开始注入。保持本进程运行以维持增强；Ctrl+C 退出（不影响 ZCode）。');
+
+  process.on('SIGINT', () => { stopping = true; try { conn.close(); } catch {} server.close(); process.exit(0); });
+  process.on('SIGTERM', () => { stopping = true; try { conn.close(); } catch {} server.close(); process.exit(0); });
+
+  while (!stopping) {
+    await sleep(3000);
+    if (stopping) break;
+    if (!conn.closed) continue;
+    // 连接断开：ZCode 退出则一并退出，否则重连
+    if (!(await cdpAlive(args.cdpPort))) {
+      console.log('[zcodepro] ZCode 已退出，zcodepro 一并退出。');
+      server.close();
+      process.exit(0);
+    }
+    try {
+      conn = await attachConnection();
+      log('CDP 已重连');
+    } catch (err) {
+      log('CDP 重连失败: ' + err.message);
+    }
+  }
+}

zcode_pro/app/src/host/paths.mjs

@@ -0,0 +1,73 @@
+// 跨平台定位 ZCode 桌面版可执行文件。
+// 优先级：--zcode-path 参数 > ZCODEPRO_ZCODE_PATH 环境变量 > 平台默认候选路径 > PATH 上的 zcode。
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { arch, homedir, platform } from 'node:os';
+
+function candidates() {
+  const home = homedir();
+  if (platform() === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA || join(home, 'AppData', 'Local');
+    const programFiles = process.env.PROGRAMFILES || 'C:\\Program Files';
+    return [
+      join(localAppData, 'Programs', 'ZCode', 'ZCode.exe'),
+      join(localAppData, 'Programs', 'zcode', 'zcode.exe'),
+      join(programFiles, 'ZCode', 'ZCode.exe'),
+      join(programFiles, 'zcode', 'zcode.exe'),
+    ];
+  }
+  if (platform() === 'darwin') {
+    return [
+      '/Applications/ZCode.app/Contents/MacOS/ZCode',
+      join(home, 'Applications', 'ZCode.app', 'Contents', 'MacOS', 'ZCode'),
+      '/Applications/ZCode Preview.app/Contents/MacOS/ZCode Preview',
+    ];
+  }
+  // linux（含 AUR 包，AUR 版安装到 /opt/ZCode）
+  const list = [
+    '/opt/ZCode/zcode',
+    '/usr/lib/zcode/zcode',
+    '/usr/share/zcode/zcode',
+    '/usr/local/ZCode/zcode',
+    join(home, '.local', 'share', 'zcode', 'zcode'),
+  ];
+  if (arch() === 'arm64') list.unshift('/opt/ZCode/zcode'); // AUR aarch64 同路径
+  return list;
+}
+
+export function resolveZcodeExecutable(explicit) {
+  const tried = [];
+  const check = (p) => {
+    if (!p) return null;
+    tried.push(p);
+    try {
+      if (existsSync(p)) return p;
+    } catch { /* ignore */ }
+    return null;
+  };
+  const fromFlag = check(explicit);
+  if (fromFlag) return fromFlag;
+  const fromEnv = check(process.env.ZCODEPRO_ZCODE_PATH);
+  if (fromEnv) return fromEnv;
+  for (const p of candidates()) {
+    const hit = check(p);
+    if (hit) return hit;
+  }
+  // 最后退回 PATH（仅类 Unix；Windows 上 PATH 查找由 shell 负责）
+  if (platform() !== 'win32') {
+    const hit = check('/usr/sbin/zcode') || check('/usr/bin/zcode');
+    if (hit) return hit;
+  }
+  const err = new Error(
+    '未找到 ZCode 可执行文件。请通过 --zcode-path <路径> 或环境变量 ZCODEPRO_ZCODE_PATH 指定。\n已尝试:\n' +
+      tried.map((p) => '  - ' + p).join('\n')
+  );
+  err.code = 'ZCODE_NOT_FOUND';
+  throw err;
+}
+
+// ZCode 数据根目录，与主进程逻辑保持一致：ZCODE_DATA_BASE_DIR || $HOME，再拼 .zcode
+export function resolveDataRootDir() {
+  const base = (process.env.ZCODE_DATA_BASE_DIR || '').trim() || homedir();
+  return join(base, '.zcode');
+}

zcode_pro/app/src/host/pickFolder.mjs

@@ -0,0 +1,152 @@
+// 系统原生目录选择器（Linux：xdg-desktop-portal FileChooser，经 gdbus 调用，
+// KDE/GNOME 弹出各自的原生对话框），支持指定起始目录。
+// 返回 { path: string | null }（用户取消为 null）或 { unavailable: true }（环境无可用选择器）。
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// kdialog（KDE 原生）：起始目录参数可靠生效。
+// xdg-desktop-portal-kde 不读 current_folder 选项（二进制中无该字符串），
+// KFileWidget 转而用“应用上次访问目录”记忆，导致起始目录失效；
+// GTK 后端支持 current_folder，无 kdialog 时回退门户。
+function kdialogPickFolder(startDir, title) {
+  return new Promise((resolve) => {
+    const child = spawn('kdialog', ['--getexistingdirectory', startDir, '--title', title], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d.toString(); });
+    child.on('error', () => resolve(undefined)); // 无 kdialog 或无法启动 → 回退门户
+    child.on('close', (code) => {
+      if (code === 0) {
+        const p = out.trim();
+        resolve(p || null);
+      } else {
+        resolve(null); // 用户取消（Esc/关闭）
+      }
+    });
+  });
+}
+
+function kdialogAvailable() {
+  const r = spawnSync('kdialog', ['--version'], { encoding: 'utf8' });
+  return !r.error && r.status === 0;
+}
+
+// zenity（GTK 原生）：--filename 指定起始目录（带尾部 / 让对话框定位到该目录）
+function zenityPickFolder(startDir) {
+  return new Promise((resolve) => {
+    const withSlash = startDir.endsWith('/') ? startDir : startDir + '/';
+    const child = spawn('zenity', ['--file-selection', '--directory', '--filename=' + withSlash], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d.toString(); });
+    child.on('error', () => resolve(undefined)); // 无 zenity 或无法启动 → 回退门户
+    child.on('close', (code) => {
+      if (code === 0) {
+        const p = out.trim();
+        resolve(p || null);
+      } else {
+        resolve(null); // 用户取消（Esc/关闭）
+      }
+    });
+  });
+}
+
+function zenityAvailable() {
+  const r = spawnSync('zenity', ['--version'], { encoding: 'utf8' });
+  return !r.error && r.status === 0;
+}
+
+function gdbusAvailable() {
+  const r = spawnSync('gdbus', ['--version'], { encoding: 'utf8' });
+  return !r.error && r.status === 0;
+}
+
+// 起始目录不存在时（切换文件夹的典型场景：原路径已被移走/删除），
+// 逐级向上找到第一个真实存在的目录，避免 portal 回退打开 home
+function firstExistingDir(p) {
+  let cur = p;
+  for (let i = 0; cur && i < 128; i++) {
+    try {
+      if (existsSync(cur) && statSync(cur).isDirectory()) return cur;
+    } catch { /* ignore */ }
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return '/';
+}
+
+function portalPickFolder(startDir, title, timeoutMs) {
+  return new Promise((resolve) => {
+    let monitor;
+    let timer = null;
+    let buf = '';
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      try { monitor && monitor.kill(); } catch { /* ignore */ }
+      resolve(v);
+    };
+
+    monitor = spawn('gdbus', ['monitor', '--session', '--dest', 'org.freedesktop.portal.Desktop'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    monitor.on('error', () => finish(undefined));
+    monitor.stdout.on('data', (d) => {
+      buf += d.toString();
+      if (done) return;
+      // 只认带我们 handle_token 的 Response 块（portal 的请求路径含调用方指定的 token）
+      const idx = buf.lastIndexOf('zcodepro_tok');
+      if (idx < 0) return;
+      const block = buf.slice(idx);
+      if (!block.includes('Response')) return;
+      const uri = /uris[^']*'([^']+)'/.exec(block) || /uris[^"]*"([^"]+)"/.exec(block);
+      if (uri) {
+        let p = uri[1];
+        if (p.startsWith('file://')) {
+          try { p = decodeURIComponent(p.slice(7)); } catch { p = p.slice(7); }
+        }
+        finish(p);
+      } else {
+        finish(null); // 用户取消或其他非成功响应
+      }
+    });
+
+    // 等 monitor 完成订阅（gdbus 就绪即输出首行）再发起对话框调用
+    monitor.stdout.once('data', () => {
+      if (done) return;
+      const bytes = Array.from(Buffer.from(startDir + '\0', 'utf8'));
+      const opts = `{"handle_token": <"zcodepro_tok_${Date.now().toString(36)}">, "modal": <true>, "directory": <true>, "multiple": <false>, "current_folder": <[${bytes.join(',')}]>}`;
+      const call = spawnSync('gdbus', ['call', '--session', '--dest', 'org.freedesktop.portal.Desktop',
+        '--object-path', '/org/freedesktop/portal/desktop',
+        '--method', 'org.freedesktop.portal.FileChooser.OpenFile', '', title, opts], { encoding: 'utf8' });
+      if (call.status !== 0 || !/object path/i.test((call.stdout || '') + (call.stderr || ''))) finish(undefined);
+    });
+
+    timer = setTimeout(() => finish(null), timeoutMs);
+  });
+}
+
+export async function pickFolderSystem(startDir, title, timeoutMs = 180000) {
+  if (process.platform !== 'linux') return { unavailable: true };
+  const start = firstExistingDir(String(startDir || '/'));
+  const dialogTitle = title || '选择文件夹';
+  if (kdialogAvailable()) {
+    const r = await kdialogPickFolder(start, dialogTitle);
+    if (r !== undefined) return { path: r };
+  }
+  if (zenityAvailable()) {
+    const r = await zenityPickFolder(start);
+    if (r !== undefined) return { path: r };
+  }
+  if (!gdbusAvailable()) return { unavailable: true };
+  const r = await portalPickFolder(start, dialogTitle, timeoutMs);
+  if (r === undefined) return { unavailable: true };
+  return { path: r };
+}

zcode_pro/app/src/host/settings.mjs

@@ -0,0 +1,61 @@
+// 读写 ZCode 的 setting.json（~/.zcode/v2/setting.json）。
+// 读用于 helper 的 /projects 端点；写仅用于“切换文件夹”后的路径引用同步，
+// 采用原子写并保留备份。
+
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function readSettings(settingsFile) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      if (!existsSync(settingsFile)) return {};
+      return JSON.parse(readFileSync(settingsFile, 'utf8'));
+    } catch (err) {
+      if (attempt === 4) throw new Error('读取 setting.json 失败: ' + err.message);
+      // 可能正被原子重命名，稍候重试
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 40);
+    }
+  }
+}
+
+export function writeSettingsAtomic(settingsFile, next) {
+  const dir = join(settingsFile, '..');
+  const backup = join(dir, 'setting.json.zcodepro-backup');
+  if (existsSync(settingsFile)) {
+    try { copyFileSync(settingsFile, backup); } catch { /* 备份失败不阻塞 */ }
+  }
+  const tmp = settingsFile + '.zcodepro-tmp';
+  writeFileSync(tmp, JSON.stringify(next, null, 2), 'utf8');
+  renameSync(tmp, settingsFile);
+}
+
+// 将 setting.json 中所有引用旧路径的字段映射到新路径，返回新 settings 对象。
+// 替换时保留原值的尾分隔符风格（ZCode 自身多写带 / 的路径），减少与宿主写入的差异。
+export function remapSettingsPaths(settings, oldPath, newPath) {
+  const next = JSON.parse(JSON.stringify(settings));
+  const norm = (p) => (typeof p === 'string' ? p.replace(/[\\/]+$/, '') : '');
+  const swap = (p) => {
+    if (typeof p !== 'string' || norm(p) !== norm(oldPath)) return p;
+    return newPath + p.slice(norm(oldPath).length); // 保留原尾分隔符（可为空）
+  };
+  if (Array.isArray(next.recentProjects)) {
+    next.recentProjects = next.recentProjects.map(swap);
+  }
+  if (Array.isArray(next.lastWorkspaceSession)) {
+    next.lastWorkspaceSession = next.lastWorkspaceSession.map((entry) => {
+      if (entry) entry.workspacePath = swap(entry.workspacePath);
+      return entry;
+    });
+  }
+  if (next.webRemoteControlLastEnabledContext) {
+    next.webRemoteControlLastEnabledContext.workspacePath = swap(next.webRemoteControlLastEnabledContext.workspacePath);
+  }
+  return next;
+}
+
+export function isProjectOpenInTabs(settings, projectPath) {
+  const norm = (p) => (typeof p === 'string' ? p.replace(/[\\/]+$/, '') : '');
+  const target = norm(projectPath);
+  const tabs = Array.isArray(settings.lastWorkspaceSession) ? settings.lastWorkspaceSession : [];
+  return tabs.some((entry) => entry && norm(entry.workspacePath) === target);
+}