helixlife-v5-cli 1.2.0 → 1.2.2

package/lib/.cli.runtime.generated.json

@@ -0,0 +1,7 @@
+{
+  "browser": {
+    "initScript": [
+      "C:/Users/zouyh/Desktop/WorkSpace/jieluoxuan/cli/helix-cli/lib/automation-overlay.init.js"
+    ]
+  }
+}

package/lib/automation-overlay.init.js

@@ -1,78 +1,208 @@
-// Playwright browser init script: inject automation status overlay on every document.
-// Source is duplicated from automation-overlay.browser.js (keep in sync when editing).
-(() => {
-  const ROOT_ID = '__helix_cli_automation_overlay';
-
-  function ensureOverlay() {
-    if (document.getElementById(ROOT_ID)) {
-      return window.__helixCliOverlay;
-    }
-
-    const root = document.createElement('div');
-    root.id = ROOT_ID;
-    root.setAttribute('data-helix-cli', 'automation-overlay');
-    root.setAttribute('aria-hidden', 'true');
-    root.style.cssText = [
-      'position:fixed',
-      'top:16px',
-      'right:16px',
-      'z-index:2147483647',
-      'pointer-events:none',
-      'box-sizing:border-box',
-      'max-width:280px',
-      'padding:10px 14px',
-      'border-radius:12px',
-      'background:#f5b942',
-      'color:#3d2b00',
-      'font:13px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"PingFang SC","Microsoft YaHei",sans-serif',
-      'box-shadow:0 4px 14px rgba(0,0,0,.18)',
-      'letter-spacing:.01em',
-    ].join(';');
-
-    const title = document.createElement('div');
-    title.dataset.line = 'title';
-    title.style.cssText = 'font-weight:600;margin-bottom:4px;word-break:break-all;';
-
-    const status = document.createElement('div');
-    status.dataset.line = 'status';
-    status.style.cssText = 'opacity:.92;';
-
-    const detail = document.createElement('div');
-    detail.dataset.line = 'detail';
-    detail.style.cssText = 'opacity:.78;margin-top:2px;font-size:12px;';
-
-    root.append(title, status, detail);
-    (document.body || document.documentElement).appendChild(root);
-
-    const api = {
-      update(payload = {}) {
-        const el = document.getElementById(ROOT_ID);
-        if (!el) return;
-        const t = el.querySelector('[data-line="title"]');
-        const s = el.querySelector('[data-line="status"]');
-        const d = el.querySelector('[data-line="detail"]');
-        if (t) t.textContent = payload.title || 'helixlife-v5-cli';
-        if (s) s.textContent = payload.status || '机器自动化';
-        if (d) d.textContent = payload.detail || 'CLI 操作中';
-        el.style.display = payload.hidden ? 'none' : 'block';
-      },
-    };
-
-    window.__helixCliOverlay = api;
-    return api;
-  }
-
-  function boot() {
-    ensureOverlay().update({
-      title: 'helixlife-v5-cli',
-      status: '机器自动化',
-      detail: '会话已就绪',
-    });
-  }
-
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', boot, { once: true });
-  } else {
-    boot();
-  }
-})();
+/* eslint-disable */
+/**
+ * helixlife-v5-cli 页面内视觉反馈层。
+ * 挂载 window.__helix_visual__：节点高亮框 + 动作标签（pending/success/danger/info）+ 右上角 HUD。
+ * 可作为 Playwright initScript 注入，也可由 CLI eval 懒加载。
+ */
+(() => {
+  if (window.__helix_visual__) return;
+
+  const VERSION = '1.0.0';
+  const VISUAL_DEFAULTS = {
+    enabled: true,
+    durationMs: 420,
+  };
+  const VISUAL_STYLE_ID = '__helix_visual_style__';
+  const VISUAL_LAYER_ID = '__helix_visual_layer__';
+  const VISUAL_HUD_ID = '__helix_visual_hud__';
+  const VISUAL_TONE_MAP = {
+    pending: { border: '#faad14', fill: 'rgba(250, 173, 20, 0.16)', pill: '#ad6800', text: '#fffbe6' },
+    success: { border: '#52c41a', fill: 'rgba(82, 196, 26, 0.14)', pill: '#237804', text: '#f6ffed' },
+    danger: { border: '#ff4d4f', fill: 'rgba(255, 77, 79, 0.14)', pill: '#a8071a', text: '#fff1f0' },
+    info: { border: '#1677ff', fill: 'rgba(22, 119, 255, 0.14)', pill: '#0958d9', text: '#f0f5ff' },
+  };
+  const visualState = {
+    config: { ...VISUAL_DEFAULTS },
+    hudTimer: null,
+  };
+
+  function clamp(n, min, max) {
+    return Math.max(min, Math.min(max, n));
+  }
+
+  function normalizeDuration(ms, fallback = VISUAL_DEFAULTS.durationMs) {
+    const n = Number(ms);
+    if (!Number.isFinite(n) || n <= 0) return fallback;
+    return clamp(Math.round(n), 120, 4000);
+  }
+
+  function normalizeVisualOptions(options = {}) {
+    const base = { ...visualState.config };
+    if (!options || typeof options !== 'object') return base;
+    if (typeof options.enabled === 'boolean') base.enabled = options.enabled;
+    if (options.durationMs != null) base.durationMs = normalizeDuration(options.durationMs, base.durationMs);
+    return base;
+  }
+
+  function ensureVisualRoot() {
+    let style = document.getElementById(VISUAL_STYLE_ID);
+    if (!style) {
+      style = document.createElement('style');
+      style.id = VISUAL_STYLE_ID;
+      style.textContent = `
+        #${VISUAL_LAYER_ID}{
+          position:fixed;
+          inset:0;
+          pointer-events:none;
+          z-index:2147483646;
+          overflow:visible;
+        }
+        .__helix_visual_box{
+          position:fixed;
+          box-sizing:border-box;
+          border-radius:8px;
+          animation:__helix_visual_pulse .55s ease-out 1;
+        }
+        .__helix_visual_badge{
+          position:absolute;
+          left:0;
+          top:-28px;
+          max-width:280px;
+          padding:4px 10px;
+          border-radius:999px;
+          font:600 12px/1.2 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+          letter-spacing:.01em;
+          white-space:nowrap;
+          text-overflow:ellipsis;
+          overflow:hidden;
+          box-shadow:0 8px 24px rgba(0,0,0,.18);
+        }
+        #${VISUAL_HUD_ID}{
+          position:fixed;
+          top:16px;
+          right:16px;
+          max-width:360px;
+          padding:10px 14px;
+          border-radius:12px;
+          box-shadow:0 12px 32px rgba(0,0,0,.22);
+          font:600 13px/1.35 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+          white-space:pre-wrap;
+        }
+        @keyframes __helix_visual_pulse{
+          0%{transform:scale(.985);opacity:.2}
+          35%{transform:scale(1.003);opacity:1}
+          100%{transform:scale(1);opacity:1}
+        }
+      `;
+      (document.head || document.documentElement).appendChild(style);
+    }
+    let layer = document.getElementById(VISUAL_LAYER_ID);
+    if (!layer) {
+      layer = document.createElement('div');
+      layer.id = VISUAL_LAYER_ID;
+      (document.body || document.documentElement).appendChild(layer);
+    }
+    return layer;
+  }
+
+  function toneSpec(tone) {
+    return VISUAL_TONE_MAP[tone] || VISUAL_TONE_MAP.info;
+  }
+
+  function removeLater(el, durationMs) {
+    if (!el) return;
+    const ms = normalizeDuration(durationMs);
+    window.setTimeout(() => {
+      if (el && el.parentNode) el.remove();
+    }, ms);
+  }
+
+  function flashElement(el, options = {}) {
+    const { tone = 'info', label = '', durationMs, inset = 0 } = options;
+    if (!el || !visualState.config.enabled) return false;
+    const rect = el.getBoundingClientRect();
+    if (!rect || rect.width <= 0 || rect.height <= 0) return false;
+    const layer = ensureVisualRoot();
+    const spec = toneSpec(tone);
+    const box = document.createElement('div');
+    box.className = '__helix_visual_box';
+    box.style.left = Math.max(4, rect.left - inset) + 'px';
+    box.style.top = Math.max(4, rect.top - inset) + 'px';
+    box.style.width = Math.max(18, rect.width + inset * 2) + 'px';
+    box.style.height = Math.max(18, rect.height + inset * 2) + 'px';
+    box.style.border = `2px solid ${spec.border}`;
+    box.style.background = spec.fill;
+    box.style.boxShadow = `0 0 0 1px ${spec.border}33, 0 12px 28px ${spec.border}22`;
+    if (label) {
+      const badge = document.createElement('div');
+      badge.className = '__helix_visual_badge';
+      badge.textContent = label;
+      badge.style.background = spec.pill;
+      badge.style.color = spec.text;
+      badge.style.top = (rect.top < 38 ? rect.height + 8 : -28) + 'px';
+      box.appendChild(badge);
+    }
+    layer.appendChild(box);
+    removeLater(box, durationMs);
+    return true;
+  }
+
+  function showHud(options = {}) {
+    const { action = '', target = '', status = 'pending', detail = '', durationMs } = options;
+    if (!visualState.config.enabled) return false;
+    const layer = ensureVisualRoot();
+    let hud = document.getElementById(VISUAL_HUD_ID);
+    if (!hud) {
+      hud = document.createElement('div');
+      hud.id = VISUAL_HUD_ID;
+      layer.appendChild(hud);
+    }
+    const spec = toneSpec(status);
+    const lines = [];
+    if (action) lines.push(action);
+    if (target) lines.push(target);
+    if (detail) lines.push(detail);
+    hud.textContent = lines.join('\n');
+    hud.style.border = `1px solid ${spec.border}`;
+    hud.style.background = spec.fill.replace(/0\.\d+\)$/, '0.92)');
+    hud.style.color = spec.pill;
+    if (visualState.hudTimer) clearTimeout(visualState.hudTimer);
+    visualState.hudTimer = window.setTimeout(() => {
+      if (hud && hud.parentNode) hud.remove();
+      visualState.hudTimer = null;
+    }, normalizeDuration(durationMs, Math.max(900, visualState.config.durationMs * 2)));
+    return true;
+  }
+
+  function cleanupVisualArtifacts() {
+    const layer = document.getElementById(VISUAL_LAYER_ID);
+    if (!layer) return;
+    Array.from(layer.querySelectorAll('.__helix_visual_box')).forEach((el) => el.remove());
+    const hud = document.getElementById(VISUAL_HUD_ID);
+    if (hud) hud.remove();
+    if (visualState.hudTimer) {
+      clearTimeout(visualState.hudTimer);
+      visualState.hudTimer = null;
+    }
+  }
+
+  function setVisualOptions(options = {}) {
+    if (!options || typeof options !== 'object') {
+      visualState.config = { ...VISUAL_DEFAULTS };
+      cleanupVisualArtifacts();
+      return { ok: true, data: { ...visualState.config } };
+    }
+    visualState.config = normalizeVisualOptions(options);
+    if (!visualState.config.enabled) cleanupVisualArtifacts();
+    return { ok: true, data: { ...visualState.config } };
+  }
+
+  window.__helix_visual__ = {
+    version: () => VERSION,
+    setVisualOptions,
+    flash: flashElement,
+    showHud,
+    cleanup: cleanupVisualArtifacts,
+    __meta: { version: VERSION, loadedAt: new Date().toISOString() },
+  };
+})();

package/lib/cli.js

@@ -5,12 +5,12 @@ const { spawnSync } = require('node:child_process');
 
 const PACKAGE_JSON = require(path.join(__dirname, '..', 'package.json'));
 const {
-  isOverlayEnabled,
-  injectOpenConfig,
-  shouldUpdateOverlay,
-  describeOverlayPayload,
-  buildOverlayRunCode,
-} = require('./automation-overlay');
+  parseVisualFlags,
+  injectVisualConfig,
+  shouldWrapWithVisual,
+  runWithVisualFeedback,
+  DEFAULT_VISUAL_ENABLED,
+} = require('./visual');
 
 /** 默认快照/下载等工作区目录名（相对 cwd），替代引擎默认的 .playwright-cli */
 const DEFAULT_OUTPUT_DIR_NAME = 'helixlife-v5-cli';
@@ -41,40 +41,36 @@ function buildChildEnv() {
 /**
  * 将参数原样交给底层浏览器自动化引擎，返回子进程退出码。
  * 使用 node 直接执行入口脚本，避免依赖 npx、Shell 与 PATH，在 Windows / macOS 上一致。
+ * @param {string[]} args
+ * @param {{ capture?: boolean }} [options]
+ * @returns {number | { code: number, stdout: string, stderr: string }}
  */
 function runPlaywrightCliPassthrough(args, options = {}) {
-  const result = spawnSync(process.execPath, [playwrightCliEntry(), ...args], {
-    stdio: options.quiet ? ['ignore', 'ignore', 'ignore'] : 'inherit',
+  const spawnOpts = {
     env: buildChildEnv(),
     windowsHide: true,
-  });
+  };
+  if (options.capture) {
+    spawnOpts.encoding = 'utf8';
+    spawnOpts.stdio = ['ignore', 'pipe', 'pipe'];
+  } else {
+    spawnOpts.stdio = 'inherit';
+  }
+  const result = spawnSync(process.execPath, [playwrightCliEntry(), ...args], spawnOpts);
   if (result.error) {
     throw result.error;
   }
   if (result.signal) {
-    console.error(`[${PACKAGE_JSON.name}] 子进程被终止: ${result.signal}`);
-    return 1;
-  }
-  return result.status === null || result.status === undefined ? 1 : result.status;
-}
-
-function updateAutomationOverlay(tokens, phase) {
-  if (!isOverlayEnabled() || !shouldUpdateOverlay(tokens)) {
-    return;
-  }
-  const payload = describeOverlayPayload(tokens, phase);
-  const code = buildOverlayRunCode(payload);
-  runPlaywrightCliPassthrough(['run-code', code], { quiet: true });
-}
-
-function runPlaywrightCliWithOverlay(tokens) {
-  const args = injectOpenConfig(tokens);
-  if (isOverlayEnabled() && shouldUpdateOverlay(args)) {
-    updateAutomationOverlay(args, 'before');
+    if (!options.capture) {
+      console.error(`[${PACKAGE_JSON.name}] 子进程被终止: ${result.signal}`);
+    }
+    return options.capture
+      ? { code: 1, stdout: result.stdout || '', stderr: result.stderr || '' }
+      : 1;
   }
-  const code = runPlaywrightCliPassthrough(args);
-  if (code === 0 && isOverlayEnabled() && shouldUpdateOverlay(args)) {
-    updateAutomationOverlay(args, 'after');
+  const code = result.status === null || result.status === undefined ? 1 : result.status;
+  if (options.capture) {
+    return { code, stdout: result.stdout || '', stderr: result.stderr || '' };
   }
   return code;
 }
@@ -85,11 +81,21 @@ function parseHelixFlags(tokens, startIndex) {
     cdpUrl: process.env.HELIX_CDP_URL || 'http://127.0.0.1:9222',
     profile:
       process.env.HELIX_PROFILE_DIR || path.join(process.cwd(), '.helixlife-profile'),
+    visual: { enabled: DEFAULT_VISUAL_ENABLED, durationMs: null },
   };
   for (let i = startIndex; i < tokens.length; i += 1) {
     const t = tokens[i];
     if (t === '--headless') {
       options.headless = true;
+    } else if (t === '--visual') {
+      options.visual.enabled = true;
+    } else if (t === '--no-visual') {
+      options.visual.enabled = false;
+    } else if (t === '--visual-ms') {
+      options.visual.durationMs = tokens[i + 1];
+      i += 1;
+    } else if (t.startsWith('--visual-ms=')) {
+      options.visual.durationMs = t.slice('--visual-ms='.length);
     } else if (t === '--profile') {
       const next = tokens[i + 1];
       if (next === undefined) {
@@ -113,6 +119,14 @@ function parseHelixFlags(tokens, startIndex) {
       return null;
     }
   }
+  if (options.visual.durationMs != null) {
+    const n = Number(options.visual.durationMs);
+    if (!Number.isFinite(n) || n <= 0) {
+      console.error(`[${PACKAGE_JSON.name}] --visual-ms 需要正数，收到 ${JSON.stringify(options.visual.durationMs)}`);
+      return null;
+    }
+    options.visual.durationMs = Math.round(n);
+  }
   return options;
 }
 
@@ -133,6 +147,11 @@ function printHelp() {
     `  ${n} helix doctor [--cdp-url <url>] [--profile <dir>]   先 list，再执行 helix home`
   );
   console.log('');
+  console.log('页面内视觉反馈（默认开启，作用于 click/fill/hover 等元素命令）：');
+  console.log(`  ${n} click e5                         操作前黄框 + 标签，成功后绿框`);
+  console.log(`  ${n} click e5 --no-visual              静默执行，无页面高亮`);
+  console.log(`  ${n} fill e3 "文本" --visual-ms 700     自定义高亮时长（毫秒）`);
+  console.log('');
   console.log('本地开发可使用：');
   console.log('  node helix-cli.js <同上参数>');
   console.log('');
@@ -140,12 +159,9 @@ function printHelp() {
     '环境变量：HELIX_BASE_URL、HELIX_CDP_URL、HELIX_PROFILE_DIR（默认 profile 目录）、'
   );
   console.log(
-    `  HELIX_OUTPUT_DIR / PLAYWRIGHT_MCP_OUTPUT_DIR（默认输出目录 <cwd>/${DEFAULT_OUTPUT_DIR_NAME}）`
-  );
-  console.log(
-    '  HELIX_AUTOMATION_OVERLAY（设为 0/false/off 可关闭右上角机器操作浮层，默认开启）'
+    `  HELIX_OUTPUT_DIR / PLAYWRIGHT_MCP_OUTPUT_DIR（默认输出目录 <cwd>/${DEFAULT_OUTPUT_DIR_NAME}）、`
   );
-  console.log('  HELIX_CLI_CONFIG（自定义 Playwright CLI 配置文件路径）');
+  console.log('  HELIX_VISUAL=0（全局关闭视觉反馈，可用 --visual 单次开启）');
 }
 
 function getBaseUrl() {
@@ -154,20 +170,19 @@ function getBaseUrl() {
 
 function helixHome(options) {
   const baseUrl = getBaseUrl();
-  // 单次 `open <url>`：与手动打开一致，避免先 about:blank 再二次 `goto` 的跨进程导航竞态（偶发样式/布局不全）。
-  const openArgs = ['open', baseUrl];
+  const openArgs = injectVisualConfig(['open', baseUrl], options.visual);
   if (options.profile) {
     openArgs.push(`--profile=${options.profile}`);
   }
   if (!options.headless) {
     openArgs.push('--headed');
   }
-  const code = runPlaywrightCliWithOverlay(openArgs);
+  const code = runPlaywrightCliPassthrough(openArgs);
   if (code !== 0) {
     return code;
   }
   console.error(`[${PACKAGE_JSON.name}] opened: ${baseUrl}`);
-  return runPlaywrightCliWithOverlay(['eval', 'document.title']);
+  return runPlaywrightCliPassthrough(['eval', 'document.title']);
 }
 
 function helixDoctor(options) {
@@ -184,6 +199,25 @@ function helixDoctor(options) {
   return helixHome(options);
 }
 
+async function runPassthroughWithVisual(tokens) {
+  let visual;
+  let stripped;
+  try {
+    ({ tokens: stripped, visual } = parseVisualFlags(tokens));
+  } catch (e) {
+    console.error(`[${PACKAGE_JSON.name}] ${e.message}`);
+    return 3;
+  }
+  const withConfig = injectVisualConfig(stripped, visual);
+  if (shouldWrapWithVisual(stripped, visual)) {
+    return runWithVisualFeedback(stripped, visual, (args, opts) => {
+      const result = runPlaywrightCliPassthrough(args, opts);
+      return opts && opts.capture ? result.code : result;
+    });
+  }
+  return runPlaywrightCliPassthrough(withConfig);
+}
+
 /**
  * @param {string[]} argv process.argv
  * @returns {Promise<number>} exit code
@@ -196,7 +230,6 @@ async function main(argv = process.argv) {
     return 0;
   }
 
-  // 勿透传到底层引擎：否则 --version 会变成 @playwright/cli 的版本（如 0.1.x），易与本体版本混淆。
   if (tokens[0] === '--version' || tokens[0] === '-v') {
     console.log(PACKAGE_JSON.version);
     return 0;
@@ -230,19 +263,17 @@ async function main(argv = process.argv) {
     return 2;
   }
 
-  return runPlaywrightCliWithOverlay(tokens);
+  return runPassthroughWithVisual(tokens);
 }
 
 main.printHelp = printHelp;
 main.runPlaywrightCliPassthrough = runPlaywrightCliPassthrough;
 main.playwrightCliEntry = playwrightCliEntry;
 
-// 注意：`require.main === module` 入口守卫统一放在 helix-cli.js；
-// 本文件仅导出，不在此处重复启动。
-
 module.exports = {
   main,
   resolveOutputDir,
   buildChildEnv,
   DEFAULT_OUTPUT_DIR_NAME,
+  runPassthroughWithVisual,
 };

package/lib/cli.runtime.config.json

@@ -1,7 +1,5 @@
 {
   "browser": {
-    "initScript": [
-      "C:\\Users\\zouyh\\Desktop\\WorkSpace\\jieluoxuan\\cli\\helix-cli\\lib\\automation-overlay.init.js"
-    ]
+    "initScript": ["./automation-overlay.init.js"]
   }
 }