zcode-pro 0.16.0__py3-none-any.whl

zcode_pro/app/src/inject/features/alias.js

@@ -0,0 +1,211 @@
+// 功能三：项目自定义别名——只改侧边栏渲染文本，不改动磁盘目录与任何 ZCode 数据。
+// 存储：helper 的 zcodepro.json aliases 表（路径规范化无尾分隔符 → 名称）。
+// 渲染：侧边栏项目行有唯一文本叶子 div.min-w-0.truncate（逆向确认），
+// 按行 testid（workspace-item-<绝对路径>）查表替换；React 重渲染后由 MutationObserver 重新套用。
+import { h, t, rpc, getConfig, clearConfigCache, errText } from '../core.js';
+import { openDialog, dialogFooter, btnPrimary, btnSecondary, textInput, showToast, ensureStyle } from '../ui.js';
+
+const norm = (p) => String(p || '').replace(/[\\/]+$/, '');
+const basenameOf = (p) => norm(p).split(/[\\/]/).pop() || '';
+
+function extractPathFromTestId(testid) {
+  let m = testid.match(/[-:=,|](\/.+)$/);
+  if (m) return m[1];
+  m = testid.match(/[-:=,|]([A-Za-z]:\\.*)$/);
+  return m ? m[1] : null;
+}
+
+// —— 渲染替换 ——
+
+let aliases = {};       // 规范化路径 → 别名（与 helper 配置同步）
+let enabled = true;   // 功能总开关（关闭时还原真实名）
+let observer = null;
+
+// 只关心项目行的变动（行新增、行内重渲染、行内文本替换）；聊天区流式输出等
+// 全页高频变动在此滤掉，不再触发别名重扫（否则长会话流式期间 60ms 一轮全页查询）。
+const rowSel = '[data-testid^="workspace-item-"]';
+const inProjectRow = (node) => node instanceof Element && !!node.closest && !!node.closest(rowSel);
+function projectRowMutations(muts) {
+  for (const m of muts) {
+    if (m.type === 'characterData') {
+      if (m.target.parentElement && inProjectRow(m.target.parentElement)) return true;
+      continue;
+    }
+    if (inProjectRow(m.target)) return true;
+    for (const n of m.addedNodes) {
+      if (n instanceof Element && (n.matches(rowSel) || !!n.querySelector(rowSel))) return true;
+    }
+  }
+  return false;
+}
+
+export async function startAliasWatcher() {
+  await syncFromConfig();
+  if (observer) return;
+  observer = new MutationObserver((muts) => { if (projectRowMutations(muts)) scheduleApply(); });
+  observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+  applyAliass();
+}
+
+async function syncFromConfig() {
+  const config = await getConfig();
+  enabled = !(config.features && config.features.projectMenu === false);
+  aliases = enabled ? (config.aliases || {}) : {};
+}
+
+let applyTimer = 0;
+function scheduleApply() {
+  clearTimeout(applyTimer);
+  applyTimer = setTimeout(applyAliass, 60);
+}
+
+export function applyAliass() {
+  const rows = document.querySelectorAll('[data-testid^="workspace-item-"]');
+  for (const row of rows) {
+    const path = norm(extractPathFromTestId(row.getAttribute('data-testid') || ''));
+    if (!path) continue;
+    // 行内唯一文本叶子即项目名元素
+    const nameEl = [...row.querySelectorAll('*')].find((e) => e.children.length === 0 && e.textContent.trim());
+    if (!nameEl) continue;
+    const real = nameEl.textContent.trim();
+    const want = aliases[path];
+    if (want) {
+      // 记录真实名，供清除别名时恢复（React 不重渲染也能还原）
+      if (!row.dataset.zcodeproRealName) row.dataset.zcodeproRealName = real;
+      if (real !== want) nameEl.textContent = want;
+    } else if (row.dataset.zcodeproRealName) {
+      nameEl.textContent = row.dataset.zcodeproRealName;
+      delete row.dataset.zcodeproRealName;
+    }
+  }
+}
+
+export async function refreshAliases() {
+  await syncFromConfig();
+  applyAliass();
+}
+
+// —— “更多”菜单入口 ——
+
+export function appendAliasItem(menu, anchorItem, project) {
+  if (menu.querySelector('[data-zcodepro-item="alias"]')) return;
+  const L = t();
+  const item = anchorItem.cloneNode(true);
+  item.removeAttribute('data-testid');
+  item.removeAttribute('data-highlighted');
+  item.setAttribute('data-zcodepro-item', 'alias');
+  for (const child of [...item.childNodes]) child.remove();
+  const origIcon = anchorItem.querySelector('svg');
+  const iconClass = origIcon ? origIcon.getAttribute('class') : 'h-3.5 w-3.5';
+  item.append(hTagIcon(iconClass), document.createTextNode(L.aliasItem));
+  item.addEventListener('mouseenter', () => {
+    for (const el of menu.querySelectorAll('[role="menuitem"]')) el.removeAttribute('data-highlighted');
+    item.setAttribute('data-highlighted', '');
+  });
+  item.addEventListener('mouseleave', () => item.removeAttribute('data-highlighted'));
+  item.addEventListener('click', () => {
+    try { menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', code: 'Escape', bubbles: true, cancelable: true })); } catch { /* ignore */ }
+    setTimeout(() => openAliasDialog(project), 80);
+  });
+  anchorItem.before(item);
+}
+
+function hTagIcon(cls) {
+  const ns = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(ns, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('fill', 'none');
+  svg.setAttribute('stroke', 'currentColor');
+  svg.setAttribute('stroke-width', '2');
+  svg.setAttribute('stroke-linecap', 'round');
+  svg.setAttribute('stroke-linejoin', 'round');
+  svg.setAttribute('class', cls);
+  const p = document.createElementNS(ns, 'path');
+  // 标签（tag）图标
+  p.setAttribute('d', 'M12.586 2.586A2 2 0 0 0 11.172 2H4a2 2 0 0 0-2 2v7.172a2 2 0 0 0 .586 1.414l8.704 8.704a2.426 2.426 0 0 0 3.42 0l6.58-6.58a2.426 2.426 0 0 0 0-3.42z');
+  svg.append(p);
+  const c = document.createElementNS(ns, 'circle');
+  c.setAttribute('cx', '7.5');
+  c.setAttribute('cy', '7.5');
+  c.setAttribute('r', '.5');
+  c.setAttribute('fill', 'currentColor');
+  svg.append(c);
+  return svg;
+}
+
+// —— 弹窗 ——
+
+export function openAliasDialog(project) {
+  ensureStyle();
+  const L = t();
+  const current = aliases[norm(project.path)] || '';
+  const realName = project.name || basenameOf(project.path);
+  let submitting = false;
+
+  openDialog({
+    title: L.aliasTitle,
+    description: L.aliasDesc,
+    width: 'sm:max-w-md',
+    onMount: ({ body, close }) => {
+      const input = textInput({
+        value: current || realName,
+        placeholder: L.aliasPlaceholder,
+        onEnter: () => submit(),
+      });
+      const submitBtn = btnPrimary(L.aliasConfirm, () => submit(), 'min-w-24');
+      const submit = async () => {
+        if (submitting) return;
+        const name = input.value.trim();
+        if (name && name === current) { close(); return; }
+        submitting = true;
+        submitBtn.setAttribute('disabled', 'true');
+        const res = await rpc('/project/alias', {
+          method: 'POST',
+          body: { path: project.path, alias: name === realName ? '' : name },
+        });
+        submitting = false;
+        submitBtn.removeAttribute('disabled');
+        if (res.ok) {
+          close();
+          clearConfigCache();
+          await refreshAliases();
+          showToast(name ? L.aliasSaved : L.aliasCleared);
+          return;
+        }
+        showToast((L.failed) + ': ' + (errText(res) || L.retryHint), 'error');
+      };
+
+      body.append(
+        h('div', { class: 'space-y-3' },
+          h('div', {},
+            h('div', { class: 'mb-1.5 text-ui-sm font-medium text-foreground' }, L.aliasLabel),
+            input),
+          h('div', {},
+            h('div', { class: 'mb-1 text-ui-xs text-foreground-subtle' }, L.pathLabel),
+            h('div', { class: 'break-all rounded-lg border border-border bg-surface-hover/50 px-3 py-1.5 font-mono text-ui-xs text-foreground-subtle' }, project.path)),
+          h('p', { class: 'text-ui-xs/relaxed text-foreground-subtle' }, L.aliasHint)
+        ),
+        (() => {
+          const footer = document.createElement('div');
+          footer.className = 'mt-6 flex flex-col-reverse gap-2 sm:flex-row sm:justify-end';
+          if (current) {
+            footer.append(btnSecondary(L.aliasClear, async () => {
+              if (submitting) return;
+              submitting = true;
+              const res = await rpc('/project/alias', { method: 'POST', body: { path: project.path, alias: '' } });
+              submitting = false;
+              if (res.ok) {
+                close();
+                clearConfigCache();
+                await refreshAliases();
+                showToast(L.aliasCleared);
+              } else showToast((L.failed) + ': ' + (errText(res) || L.retryHint), 'error');
+            }));
+          }
+          footer.append(btnSecondary(L.cancel, () => close()), submitBtn);
+          return footer;
+        })()
+      );
+    },
+  });
+}

zcode_pro/app/src/inject/features/copy-path.js

@@ -0,0 +1,78 @@
+// “复制路径”：项目“更多”菜单中把项目绝对路径复制到剪贴板。
+// navigator.clipboard 在渲染进程有焦点时可用；失败时回退 execCommand 写入隐藏输入框。
+import { h, t, closeRadixMenu } from '../core.js';
+import { showToast } from '../ui.js';
+
+export async function appendCopyPathItem(menu, anchorItem, project) {
+  if (menu.querySelector('[data-zcodepro-item="copy-path"]')) return;
+  const L = t();
+  const item = anchorItem.cloneNode(true);
+  item.removeAttribute('data-testid');
+  item.removeAttribute('data-highlighted');
+  item.setAttribute('data-zcodepro-item', 'copy-path');
+  for (const child of [...item.childNodes]) child.remove();
+  const origIcon = anchorItem.querySelector('svg');
+  const iconClass = origIcon ? origIcon.getAttribute('class') : 'h-3.5 w-3.5';
+  item.append(hCopyIcon(iconClass), document.createTextNode(L.copyPathItem));
+  item.addEventListener('mouseenter', () => {
+    for (const el of menu.querySelectorAll('[role="menuitem"]')) el.removeAttribute('data-highlighted');
+    item.setAttribute('data-highlighted', '');
+  });
+  item.addEventListener('mouseleave', () => item.removeAttribute('data-highlighted'));
+  item.addEventListener('click', () => {
+    closeRadixMenu(menu);
+    void copyText(project.path);
+  });
+  anchorItem.before(item);
+}
+
+async function copyText(text) {
+  const L = t();
+  if (await copyToClipboard(text)) showToast(L.pathCopied);
+  else showToast(L.pathCopyFailed, 'error');
+}
+
+// 通用文本复制：成功返回 true，调用方自己决定提示文案
+export async function copyToClipboard(text) {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return copyViaHiddenInput(text);
+  }
+}
+
+// 剪贴板 API 不可用时的回退：临时输入框 + execCommand('copy')
+function copyViaHiddenInput(text) {
+  try {
+    const input = h('input', { type: 'text', style: 'position:fixed;left:-9999px;top:0;opacity:0' });
+    input.value = text;
+    document.body.append(input);
+    input.select();
+    const ok = document.execCommand('copy');
+    input.remove();
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+export function hCopyIcon(cls) {
+  const ns = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(ns, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('fill', 'none');
+  svg.setAttribute('stroke', 'currentColor');
+  svg.setAttribute('stroke-width', '2');
+  svg.setAttribute('stroke-linecap', 'round');
+  svg.setAttribute('stroke-linejoin', 'round');
+  svg.setAttribute('class', cls);
+  // lucide copy
+  for (const d of ['M8 8h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2V10a2 2 0 0 1 2-2Z',
+    'M4 16c-1.1 0-2-.9-2-2V4a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2']) {
+    const p = document.createElementNS(ns, 'path');
+    p.setAttribute('d', d);
+    svg.append(p);
+  }
+  return svg;
+}

zcode_pro/app/src/inject/features/file-menu.js

@@ -0,0 +1,147 @@
+// 功能五：文件菜单增强——文件操作弹出菜单（含“复制绝对路径”项的菜单，右键文件链接 chip
+// 与预览卡片“打开 ▾”下拉均有）：
+// - “打开”分组内、可用编辑器列表（无可用时为“未找到可用 App”禁用项）上方新增“默认应用打开”
+//   （helper /open-path 用系统默认应用打开；旧版曾用宿主桥 window.zcode.openExternalFile，新版已移除该桥）；
+// - “复制绝对路径”上方新增“打开所在目录”（helper /reveal-path 在文件管理器中定位文件；
+//   不用宿主 openInFileManager——其在 Linux/Windows 的实现只是 shell.openPath，即用默认应用打开）。
+// 路径获取（按序尝试）：触发器 title（文件 chip 右键场景，message.tsx 写入绝对路径）→
+// 触发器/菜单的 React fiber props（OpenSplitButton 场景 target/fileLink/row.path）。
+import { t, closeRadixMenu, itemsOf, itemText, rpc } from '../core.js';
+import { getConfig } from '../core.js';
+
+const COPY_ABS_TEXTS = ['复制绝对路径', 'Copy absolute path'];
+const NO_APPS_TEXTS = ['未找到可用 App', 'No apps found'];
+
+// lucide 图标：app-window（默认应用打开）/ folder-open（打开所在目录）
+const ICON_OPEN_DEFAULT = [
+  { rect: { x: '2', y: '4', width: '20', height: '16', rx: '2' } },
+  { d: 'M10 4v4' },
+  { d: 'M2 8h20' },
+  { d: 'M6 4v4' },
+];
+const ICON_REVEAL = [
+  { d: 'm6 14 1.45-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.55 6a2 2 0 0 1-1.94 1.5H4a2 2 0 0 1-2-2V5c0-1.1.9-2 2-2h3.93a2 2 0 0 1 1.66.9l.82 1.22a2 2 0 0 0 1.66.9H18a2 2 0 0 1 2 2v2' },
+];
+
+function buildIcon(cls, shapes) {
+  const ns = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(ns, 'svg');
+  svg.setAttribute('viewBox', '0 0 24 24');
+  svg.setAttribute('fill', 'none');
+  svg.setAttribute('stroke', 'currentColor');
+  svg.setAttribute('stroke-width', '2');
+  svg.setAttribute('stroke-linecap', 'round');
+  svg.setAttribute('stroke-linejoin', 'round');
+  if (cls) svg.setAttribute('class', cls);
+  for (const s of shapes) {
+    if (s.rect) {
+      const r = document.createElementNS(ns, 'rect');
+      for (const [k, v] of Object.entries(s.rect)) r.setAttribute(k, v);
+      svg.append(r);
+    } else {
+      const p = document.createElementNS(ns, 'path');
+      p.setAttribute('d', s.d);
+      svg.append(p);
+    }
+  }
+  return svg;
+}
+
+// 触发器 title 里应是绝对路径（Unix 或 Windows 盘符），防误取其他 title
+function looksLikePath(v) {
+  return typeof v === 'string' && (/^[\\/]/.test(v) || /^[A-Za-z]:[\\/]/.test(v));
+}
+
+// 从 React fiber 的祖先链上取文件路径（OpenSplitButton 等场景路径只在 props 里）
+function pathFromReactFiber(el) {
+  try {
+    const key = Object.keys(el).find((k) => k.startsWith('__reactFiber$'));
+    let fiber = key ? el[key] : null;
+    for (let i = 0; fiber && i < 40; i++, fiber = fiber.return) {
+      const props = fiber.memoizedProps;
+      if (!props || typeof props !== 'object') continue;
+      for (const k of ['target', 'fileLink', 'row']) {
+        const v = props[k];
+        if (v && looksLikePath(v.path)) return v.path;
+      }
+      if (looksLikePath(props.path)) return props.path;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+function resolveTargetPath(content) {
+  const id = content.id;
+  if (id) {
+    try {
+      const trigger = document.querySelector(`[aria-controls="${CSS.escape(id)}"]`);
+      const p = trigger?.getAttribute('title');
+      if (looksLikePath(p)) return p;
+      const fromFiber = trigger && pathFromReactFiber(trigger);
+      if (fromFiber) return fromFiber;
+    } catch { /* ignore */ }
+  }
+  // 兜底：当前打开状态的右键触发器（同一时刻通常只有一个菜单）
+  const open = document.querySelector('[data-slot="context-menu-trigger"][data-state="open"]');
+  const p2 = open?.getAttribute('title');
+  if (looksLikePath(p2)) return p2;
+  return pathFromReactFiber(content);
+}
+
+function appendMenuItem(content, template, anchor, { marker, label, icon, onPick }) {
+  // 模板必须取可用项（复制绝对路径）：禁用项带 data-disabled 与 pointer-events:none 类，
+  // 克隆会导致灰显且点击穿透。悬停高亮是 Radix 行为，克隆节点需手动模拟。
+  const item = template.cloneNode(true);
+  item.removeAttribute('data-testid');
+  item.removeAttribute('data-highlighted');
+  item.removeAttribute('data-disabled');
+  item.removeAttribute('aria-disabled');
+  item.setAttribute('data-zcodepro-item', marker);
+  for (const child of [...item.childNodes]) child.remove();
+  const origIcon = template.querySelector('svg');
+  item.append(buildIcon(origIcon?.getAttribute('class') || 'size-4', icon), document.createTextNode(label));
+  item.addEventListener('mouseenter', () => {
+    for (const el of content.querySelectorAll('[role="menuitem"]')) el.removeAttribute('data-highlighted');
+    item.setAttribute('data-highlighted', '');
+  });
+  item.addEventListener('mouseleave', () => item.removeAttribute('data-highlighted'));
+  item.addEventListener('click', () => {
+    closeRadixMenu(content);
+    onPick();
+  });
+  anchor.before(item);
+  return item;
+}
+
+export function handleFileMenu(content) {
+  if (content.dataset.zcodeproFileMenu) return;
+  const items = itemsOf(content);
+  const copyAbs = items.find((el) => COPY_ABS_TEXTS.some((x) => itemText(el).startsWith(x)));
+  if (!copyAbs) return;
+  // 同步占位防竞态：注入在下方异步段执行，多个观察者回调同时进入时只允许第一个注入
+  content.dataset.zcodeproFileMenu = '1';
+  void (async () => {
+    const config = await getConfig();
+    if (config.features && config.features.fileActions === false) return;
+    const path = resolveTargetPath(content);
+    if (!path) return;
+    const L = t();
+    // “默认应用打开”锚在编辑器列表末尾（无可用编辑器时即“未找到可用 App”禁用项）之上；
+    // 找不到该组时退而锚在“复制绝对路径”上，保持“打开方式在前、路径操作在后”的次序
+    const noApps = items.find((el) => NO_APPS_TEXTS.some((x) => itemText(el) === x))
+      || content.querySelector('[data-disabled][role="menuitem"]');
+    const openAnchor = noApps && content.contains(noApps) ? noApps : copyAbs;
+    appendMenuItem(content, copyAbs, openAnchor, {
+      marker: 'file-open-default',
+      label: L.fileOpenDefault,
+      icon: ICON_OPEN_DEFAULT,
+      onPick: () => { try { void rpc('/open-path', { method: 'POST', body: { path } }); } catch { /* ignore */ } },
+    });
+    appendMenuItem(content, copyAbs, copyAbs, {
+      marker: 'file-reveal',
+      label: L.fileReveal,
+      icon: ICON_REVEAL,
+      onPick: () => { try { void rpc('/reveal-path', { method: 'POST', body: { path } }); } catch { /* ignore */ } },
+    });
+  })();
+}

zcode_pro/app/src/inject/features/idle-reclaim.js

@@ -0,0 +1,179 @@
+// 空闲项目进程回收：ZCode 为每个打开过的项目常驻一个会话进程（含其 MCP 子进程），
+// 应用自身不回收这类进程（回收能力只接给了内部的 MCP 状态探测进程）。本功能对
+// “长时间无活动”的项目调用应用自身的 releaseWorkspacePreparation 接口主动释放：
+// 会话记录不受影响，下次点开该项目的会话时进程自动重建，仅第一条消息有几秒冷启动。
+//
+// 不回收（任一命中即跳过）：
+// 1) 当前选中的项目；
+// 2) 有运行中会话的项目（含子智能体/工作流，它们都在会话回合内运行）——先用
+//    折叠项目运行检测（ws-running）的现场记录，回收前再无感展开复核一次兜底；
+// 3) 有仍在运行的后台命令的项目——helper 扫描会话进程的子进程（/idle-busy，
+//    Linux/macOS/Windows 各走系统自带工具），插件/MCP 基础设施子进程除外，
+//    剩余视为用户命令；扫描不可用时整个功能停用，不做盲回收。
+// 定时/闲时任务由宿主进程调度、触发时自动重建会话进程，无需排除。
+//
+// 开关：features.idleReclaim（默认开）。
+// 两个时长：idleReclaimMinutes 常规空闲判定（默认 30，1–1440）；
+// idleReclaimStartupMinutes 启动一次性回收的延后分钟（默认 5，0–1440，0 = 启动后
+// 尽快收一次，不受常规空闲时长限制——应用启动会为每个恢复的项目预热进程，这次
+// 回收专治启动瞬间的内存高峰）。
+import { rpc, getConfig } from '../core.js';
+import { wsRunningSnapshot, verifyWorkspaceNotRunning } from './ws-running.js';
+
+const CHECK_MS = 30_000;      // 巡检周期
+const WS_SEL = '[data-testid^="workspace-item-"]';
+const MIN_MINUTES = 1;
+const MAX_MINUTES = 1440;
+
+const idleSince = new Map();   // 项目路径 → 首次判定空闲的时刻
+const blockUntil = new Map();  // 项目路径 → 此前不得再次回收的时刻（回收/复核失败后的冷却）
+let scanDisabledLogged = false;
+const bootAt = Date.now();     // 注入时刻 ≈ 应用启动时刻
+let startupSweepDone = false;  // 启动一次性回收是否已执行
+
+// 应用内部服务对象（含 zcodeTaskService.releaseWorkspacePreparation）：从 React
+// fiber 树上找持有它的组件（file-menu.js 同款取 fiber 的思路），找到后缓存
+let servicesRef = null;
+function findServices() {
+  if (servicesRef) return servicesRef;
+  try {
+    const rootEl = document.getElementById('root');
+    const containerKey = rootEl && Object.keys(rootEl).find((k) => k.startsWith('__reactContainer$'));
+    if (!containerKey) return null;
+    const seen = new Set();
+    let found = null;
+    const scanObj = (o) => {
+      if (!o || typeof o !== 'object' || seen.has(o) || found) return;
+      seen.add(o);
+      const ts = o.zcodeTaskService;
+      if (ts && typeof ts === 'object' && typeof ts.releaseWorkspacePreparation === 'function') found = o;
+    };
+    let visited = 0;
+    const visit = (f) => {
+      if (!f || found || visited > 60000) return;
+      visited++;
+      for (const holder of [f.memoizedProps, f.memoizedState]) {
+        if (!holder || typeof holder !== 'object') continue;
+        scanObj(holder);
+        for (const v of Object.values(holder)) {
+          if (v && typeof v === 'object') scanObj(v);
+        }
+      }
+      visit(f.child);
+      visit(f.sibling);
+    };
+    visit(rootEl[containerKey]);
+    if (found) servicesRef = found;
+    return found;
+  } catch {
+    return null;
+  }
+}
+
+function sidebarWorkspaces() {
+  const out = new Set();
+  for (const el of document.querySelectorAll(WS_SEL)) {
+    out.add(el.getAttribute('data-testid').slice('workspace-item-'.length));
+  }
+  return out;
+}
+
+async function reclaim(ws) {
+  const services = findServices();
+  if (!services) return false;
+  try {
+    // 应用内部的工作区键带尾分隔符（宿主日志可见），不带则键对不上、调用成空操作
+    await services.zcodeTaskService.releaseWorkspacePreparation({
+      workspacePath: ws.endsWith('/') ? ws : ws + '/',
+    });
+    console.info('[zcodepro] idle-reclaim: 已释放空闲项目进程 ' + ws);
+    return true;
+  } catch (err) {
+    console.warn('[zcodepro] idle-reclaim: 释放失败 ' + ws, err);
+    return false;
+  }
+}
+
+// 回收单个项目：回收前复核运行状态与当前归属，未通过则冷却后由后续周期重试
+async function tryReclaim(ws, cooldownMs) {
+  // 回收前最后复核：折叠项目的运行状态可能没被现场捕获到，无感展开读取再收起；
+  // 复核没做成（窗口隐藏/行不可达）也按忙处理，不回收
+  const verifiedIdle = await verifyWorkspaceNotRunning(ws);
+  if (!verifiedIdle) { blockUntil.set(ws, Date.now() + cooldownMs); return; }
+  // 复核要展开读行、网络请求也有耗时：期间用户可能已切到该项目，回收前再确认一次归属
+  const currentNow = wsRunningSnapshot().current;
+  if (!currentNow || currentNow === ws) { blockUntil.set(ws, Date.now() + cooldownMs); return; }
+  await reclaim(ws);
+  // 无论成败都冷却：失败退避重试；成功后用户再点开则进程重建、重新计时
+  blockUntil.set(ws, Date.now() + cooldownMs);
+}
+
+async function tick() {
+  const cfg = await getConfig();
+  if ((cfg.features || {}).idleReclaim === false) {
+    idleSince.clear();
+    return;
+  }
+  const minutes = Math.min(MAX_MINUTES, Math.max(MIN_MINUTES, Number(cfg.idleReclaimMinutes) || 30));
+  const threshold = minutes * 60_000;
+  let startupMinutes = Number(cfg.idleReclaimStartupMinutes);
+  if (!Number.isFinite(startupMinutes)) startupMinutes = 5;
+  startupMinutes = Math.min(MAX_MINUTES, Math.max(0, startupMinutes));
+
+  const snap = wsRunningSnapshot();
+  // 当前项目无法定位（新建任务输入态等没有选中会话行的状态）：无法保证不误回收
+  // 用户正在使用的项目，本轮跳过回收，空闲计时作废重新累计
+  if (!snap.current) {
+    idleSince.clear();
+    return;
+  }
+  const busy = new Set(snap.running);
+  busy.add(snap.current);
+
+  const workspaces = sidebarWorkspaces();
+  for (const ws of [...idleSince.keys(), ...blockUntil.keys()]) {
+    if (!workspaces.has(ws)) { idleSince.delete(ws); blockUntil.delete(ws); }
+  }
+
+  const candidates = [...workspaces].filter((ws) => !busy.has(ws));
+  const res = candidates.length
+    ? await rpc('/idle-busy', { method: 'POST', body: { paths: candidates } })
+    : { ok: true, scan: true, busy: [] };
+  if (!res.ok || res.scan === false) {
+    // 无法确认后台命令状态（系统工具缺失 / helper 旧版）：整体停用
+    if (!scanDisabledLogged) {
+      scanDisabledLogged = true;
+      console.info('[zcodepro] idle-reclaim: 后台命令扫描不可用，空闲回收停用');
+    }
+    idleSince.clear();
+    return;
+  }
+  const procBusy = new Set(res.busy || []);
+  const idleCandidates = candidates.filter((ws) => !procBusy.has(ws));
+
+  const now = Date.now();
+  // 启动一次性回收：应用启动会为每个恢复的项目预热会话进程，这次回收不等空闲
+  // 时长，到点把当时符合条件的项目一次收掉（0 = 启动后尽快回收一次；当前项目
+  // 定位不到时顺延到下一周期）。之后回归常规空闲计时
+  if (!startupSweepDone && now - bootAt >= startupMinutes * 60_000) {
+    startupSweepDone = true;
+    for (const ws of idleCandidates) {
+      if ((blockUntil.get(ws) || 0) > now) continue;
+      await tryReclaim(ws, threshold);
+    }
+  }
+  for (const ws of workspaces) {
+    if (busy.has(ws) || procBusy.has(ws)) { idleSince.delete(ws); continue; }
+    if (!idleSince.has(ws)) { idleSince.set(ws, now); continue; }
+    if (now - idleSince.get(ws) < threshold) continue;
+    if ((blockUntil.get(ws) || 0) > now) continue;
+    idleSince.delete(ws);
+    await tryReclaim(ws, threshold);
+  }
+}
+
+export function startIdleReclaim() {
+  const loop = () => { tick().catch(() => { /* 单次巡检失败不影响后续 */ }); };
+  loop();
+  setInterval(loop, CHECK_MS);
+}