helixlife-v5-cli 1.2.0 → 1.2.1

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"]
   }
 }

package/lib/visual.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const INIT_SCRIPT_PATH = path.join(__dirname, 'automation-overlay.init.js');
+const GENERATED_CONFIG_PATH = path.join(__dirname, '.cli.runtime.generated.json');
+
+/** 默认开启页面内视觉反馈；HELIX_VISUAL=0 可全局关闭 */
+const DEFAULT_VISUAL_ENABLED = process.env.HELIX_VISUAL !== '0';
+
+const VISUAL_COMMANDS = {
+  click: { pending: '正在点击', success: '已点击', pendingTone: 'pending', successTone: 'success' },
+  dblclick: { pending: '正在双击', success: '已双击', pendingTone: 'pending', successTone: 'success' },
+  fill: { pending: '正在填写', success: '已填写', pendingTone: 'pending', successTone: 'success' },
+  hover: { pending: '正在悬停', success: '已悬停', pendingTone: 'info', successTone: 'info' },
+  check: { pending: '正在勾选', success: '已勾选', pendingTone: 'pending', successTone: 'success' },
+  uncheck: { pending: '正在取消勾选', success: '已取消勾选', pendingTone: 'pending', successTone: 'info' },
+  select: { pending: '正在选择', success: '已选择', pendingTone: 'pending', successTone: 'success' },
+  drag: { pending: '正在拖拽', success: '已拖拽', pendingTone: 'pending', successTone: 'success' },
+  drop: { pending: '正在放置', success: '已放置', pendingTone: 'pending', successTone: 'success' },
+  upload: { hudOnly: true, pending: '正在上传', success: '已上传', pendingTone: 'pending', successTone: 'success' },
+  press: { hudOnly: true, pending: '按键', success: '按键完成', pendingTone: 'info', successTone: 'success' },
+  type: { hudOnly: true, pending: '正在输入', success: '输入完成', pendingTone: 'pending', successTone: 'success' },
+};
+
+const SESSION_START_COMMANDS = new Set(['open', 'attach']);
+
+function readInitScriptSource() {
+  return fs.readFileSync(INIT_SCRIPT_PATH, 'utf8');
+}
+
+function resolveGeneratedConfigPath() {
+  const payload = {
+    browser: {
+      initScript: [INIT_SCRIPT_PATH.replace(/\\/g, '/')],
+    },
+  };
+  fs.writeFileSync(GENERATED_CONFIG_PATH, JSON.stringify(payload, null, 2), 'utf8');
+  return GENERATED_CONFIG_PATH;
+}
+
+/**
+ * 从 argv 中提取并剥离 --visual / --no-visual / --visual-ms。
+ * @returns {{ tokens: string[], visual: { enabled: boolean, durationMs: number | null } }}
+ */
+function parseVisualFlags(tokens) {
+  const visual = {
+    enabled: DEFAULT_VISUAL_ENABLED,
+    durationMs: null,
+  };
+  const out = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t === '--visual') {
+      visual.enabled = true;
+    } else if (t === '--no-visual') {
+      visual.enabled = false;
+    } else if (t === '--visual-ms') {
+      visual.durationMs = tokens[i + 1];
+      i += 1;
+    } else if (t.startsWith('--visual-ms=')) {
+      visual.durationMs = t.slice('--visual-ms='.length);
+    } else {
+      out.push(t);
+    }
+  }
+  if (visual.durationMs != null) {
+    const n = Number(visual.durationMs);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw Object.assign(new Error(`--visual-ms 需要正数，收到 ${JSON.stringify(visual.durationMs)}`), { code: 'E_BAD_ARG' });
+    }
+    visual.durationMs = Math.round(n);
+  }
+  return { tokens: out, visual };
+}
+
+function hasConfigFlag(tokens) {
+  return tokens.some((t) => t === '--config' || t.startsWith('--config='));
+}
+
+/**
+ * open / attach 时自动注入 initScript 配置，使新页面预装视觉层。
+ */
+function injectVisualConfig(tokens, visual) {
+  if (!visual.enabled) return tokens;
+  const cmd = resolveCommandName(tokens);
+  if (!SESSION_START_COMMANDS.has(cmd) || hasConfigFlag(tokens)) {
+    return tokens;
+  }
+  const configPath = resolveGeneratedConfigPath();
+  return [...tokens, `--config=${configPath}`];
+}
+
+function resolveCommandName(tokens) {
+  let i = 0;
+  if (tokens[i] === '--raw') i += 1;
+  if (tokens[i] === '--json') i += 1;
+  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  return tokens[i] || '';
+}
+
+function isElementRef(token) {
+  if (!token || token.startsWith('-')) return false;
+  if (/^e\d+$/.test(token)) return true;
+  if (token.startsWith('"') || token.startsWith("'")) return true;
+  if (token.startsWith('#') || token.startsWith('.')) return true;
+  if (token.startsWith('getBy')) return true;
+  return false;
+}
+
+/**
+ * 从命令参数中提取主要元素 target（用于高亮）。
+ */
+function extractElementTarget(tokens) {
+  const cmd = resolveCommandName(tokens);
+  if (!VISUAL_COMMANDS[cmd]) return null;
+  const def = VISUAL_COMMANDS[cmd];
+  if (def.hudOnly) return null;
+
+  let i = 0;
+  if (tokens[i] === '--raw') i += 1;
+  if (tokens[i] === '--json') i += 1;
+  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  i += 1; // skip command name
+
+  const positional = [];
+  for (; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t.startsWith('--')) {
+      if (t.includes('=')) continue;
+      const next = tokens[i + 1];
+      if (next !== undefined && !next.startsWith('-')) i += 1;
+      continue;
+    }
+    positional.push(t);
+  }
+
+  if (cmd === 'drag' && positional.length >= 1) return positional[0];
+  if (cmd === 'fill' && positional.length >= 1) return positional[0];
+  if (cmd === 'select' && positional.length >= 1) return positional[0];
+  if (cmd === 'drop' && positional.length >= 1) return positional[0];
+  if (positional.length >= 1 && isElementRef(positional[0])) return positional[0];
+  if (positional.length >= 2 && isElementRef(positional[positional.length - 1])) {
+    return positional[positional.length - 1];
+  }
+  return null;
+}
+
+function buildFlashEval(target, options) {
+  const optsLit = JSON.stringify(options);
+  return [
+    'eval',
+    `el => { const v = window.__helix_visual__; if (!v) return false; return v.flash(el, ${optsLit}); }`,
+    target,
+  ];
+}
+
+function buildHudEval(options) {
+  const optsLit = JSON.stringify(options);
+  return ['eval', `() => { const v = window.__helix_visual__; if (!v) return false; return v.showHud(${optsLit}); }`];
+}
+
+function buildSetOptionsEval(visual) {
+  const payload = JSON.stringify({
+    enabled: visual.enabled,
+    durationMs: visual.durationMs,
+  });
+  return ['eval', `() => { const v = window.__helix_visual__; if (!v) return null; return v.setVisualOptions(${payload}); }`];
+}
+
+function buildInstallEval() {
+  const src = readInitScriptSource();
+  return ['eval', src];
+}
+
+function buildBridgeCheckEval() {
+  return ['eval', '--raw', 'Boolean(window.__helix_visual__)'];
+}
+
+function shouldWrapWithVisual(tokens, visual) {
+  if (!visual.enabled) return false;
+  const cmd = resolveCommandName(tokens);
+  return Boolean(VISUAL_COMMANDS[cmd]);
+}
+
+/**
+ * 在元素交互命令前后注入视觉反馈。
+ * @param {string[]} tokens 已剥离 visual flags 的参数
+ * @param {{ enabled: boolean, durationMs: number | null }} visual
+ * @param {(args: string[], opts?: object) => number} runPassthrough
+ */
+async function runWithVisualFeedback(tokens, visual, runPassthrough) {
+  const cmd = resolveCommandName(tokens);
+  const def = VISUAL_COMMANDS[cmd];
+  const target = extractElementTarget(tokens);
+
+  const runCapture = (args) => runPassthrough(args, { capture: true });
+
+  const check = runCapture(buildBridgeCheckEval());
+  if (String(check.stdout || '').trim() !== 'true') {
+    runCapture(buildInstallEval());
+  }
+  runCapture(buildSetOptionsEval(visual));
+
+  const hudBase = { action: cmd, target: target || '', status: 'pending' };
+  runCapture(buildHudEval({ ...hudBase, detail: def.pending }));
+
+  if (target) {
+    runCapture(buildFlashEval(target, {
+      tone: def.pendingTone || 'pending',
+      label: def.pending,
+      durationMs: visual.durationMs,
+    }));
+  }
+
+  const code = runPassthrough(tokens);
+
+  const successTone = code === 0 ? (def.successTone || 'success') : 'danger';
+  const successLabel = code === 0 ? def.success : '操作失败';
+  runCapture(buildSetOptionsEval(visual));
+  if (target) {
+    runCapture(buildFlashEval(target, {
+      tone: successTone,
+      label: successLabel,
+      durationMs: visual.durationMs,
+    }));
+  }
+  runCapture(buildHudEval({
+    action: cmd,
+    target: target || '',
+    status: code === 0 ? 'success' : 'danger',
+    detail: successLabel,
+  }));
+
+  return code;
+}
+
+module.exports = {
+  INIT_SCRIPT_PATH,
+  VISUAL_COMMANDS,
+  DEFAULT_VISUAL_ENABLED,
+  parseVisualFlags,
+  injectVisualConfig,
+  shouldWrapWithVisual,
+  runWithVisualFeedback,
+  resolveGeneratedConfigPath,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helixlife-v5-cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Helix（vip.helixlife.cn）精细化浏览器自动化命令行工具。",
   "main": "helix-cli.js",
   "bin": {

package/lib/automation-overlay.browser.js

@@ -1,76 +0,0 @@
-(() => {
-  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();
-  }
-})();

package/lib/automation-overlay.js

@@ -1,238 +0,0 @@
-"use strict";
-
-const fs = require("node:fs");
-const path = require("node:path");
-
-const OVERLAY_SKIP_COMMANDS = new Set([
-  "run-code",
-  "list",
-  "close",
-  "close-all",
-  "kill-all",
-  "detach",
-  "delete-data",
-  "config-print",
-  "cookie-list",
-  "cookie-get",
-  "cookie-set",
-  "cookie-delete",
-  "cookie-clear",
-  "localstorage-list",
-  "localstorage-get",
-  "localstorage-set",
-  "localstorage-delete",
-  "localstorage-clear",
-  "sessionstorage-list",
-  "sessionstorage-get",
-  "sessionstorage-set",
-  "sessionstorage-delete",
-  "sessionstorage-clear",
-  "route-list",
-  "tab-list",
-  "console",
-  "network",
-  "state-save",
-  "state-load",
-  "tracing-start",
-  "tracing-stop",
-  "video-start",
-  "video-stop",
-  "video-chapter",
-  "highlight",
-  "generate-locator",
-  "show",
-]);
-
-const OVERLAY_SESSION_OPEN_COMMANDS = new Set(["open", "attach"]);
-
-let cachedBrowserScript = null;
-
-function isOverlayEnabled() {
-  const flag = process.env.HELIX_AUTOMATION_OVERLAY;
-  if (flag === "0" || flag === "false" || flag === "off") {
-    return false;
-  }
-  return true;
-}
-
-function resolveCliConfigPath() {
-  if (process.env.HELIX_CLI_CONFIG) {
-    return path.resolve(process.env.HELIX_CLI_CONFIG);
-  }
-  const initScriptPath = path.join(__dirname, "automation-overlay.init.js");
-  const runtimeConfigPath = path.join(__dirname, "cli.runtime.config.json");
-  const config = {
-    browser: {
-      initScript: [initScriptPath],
-    },
-  };
-  fs.writeFileSync(
-    runtimeConfigPath,
-    `${JSON.stringify(config, null, 2)}\n`,
-    "utf8",
-  );
-  return runtimeConfigPath;
-}
-
-function getBrowserOverlayScript() {
-  if (!cachedBrowserScript) {
-    cachedBrowserScript = fs.readFileSync(
-      path.join(__dirname, "automation-overlay.browser.js"),
-      "utf8",
-    );
-  }
-  return cachedBrowserScript;
-}
-
-function stripLeadingFlags(tokens) {
-  let i = 0;
-  while (i < tokens.length) {
-    const t = tokens[i];
-    if (t === "--raw" || t === "--json") {
-      i += 1;
-      continue;
-    }
-    if (t.startsWith("-s=")) {
-      i += 1;
-      continue;
-    }
-    break;
-  }
-  return tokens.slice(i);
-}
-
-function truncate(text, max = 48) {
-  const s = String(text || "")
-    .replace(/\s+/g, " ")
-    .trim();
-  if (s.length <= max) return s;
-  return `${s.slice(0, max - 1)}…`;
-}
-
-function describeOverlayPayload(tokens, phase) {
-  const core = stripLeadingFlags(tokens);
-  const command = core[0];
-  if (!command) {
-    return {
-      title: "helixlife-v5-cli",
-      status: phase === "after" ? "已完成" : "执行中...",
-      detail: "CLI自动化操作中",
-    };
-  }
-
-  const args = core.slice(1).filter((t) => !t.startsWith("--"));
-  let title = command;
-  let detail = args.length ? truncate(args.join(" ")) : "CLI自动化操作中";
-
-  switch (command) {
-    case "click":
-    case "dblclick":
-    case "hover":
-    case "check":
-    case "uncheck":
-      title = command;
-      detail = truncate(args[0] || "元素", 40);
-      break;
-    case "fill":
-      title = "fill";
-      detail = truncate(args[0] || "输入框", 40);
-      break;
-    case "type":
-      title = "type";
-      detail = truncate(args[0] || "", 32);
-      break;
-    case "goto":
-    case "open":
-      title = command;
-      detail = truncate(args[0] || "页面", 56);
-      break;
-    case "snapshot":
-      title = "snapshot";
-      detail = "页面验收";
-      break;
-    case "run-code":
-      title = "run-code";
-      detail = truncate(args[0] || "脚本", 40);
-      break;
-    case "press":
-      title = "press";
-      detail = truncate(args[0] || "按键", 24);
-      break;
-    case "select":
-      title = "select";
-      detail = truncate(args.join(" "), 40);
-      break;
-    case "upload":
-      title = "upload";
-      detail = truncate(args[0] || "文件", 40);
-      break;
-    case "eval":
-      title = "eval";
-      detail = "读取页面状态";
-      break;
-    default:
-      title = command;
-      break;
-  }
-
-  return {
-    title,
-    status: phase === "after" ? "已完成" : "执行中...",
-    detail: phase === "after" ? "CLI自动化操作中" : detail || "CLI自动化操作中",
-  };
-}
-
-function shouldUpdateOverlay(tokens) {
-  const core = stripLeadingFlags(tokens);
-  const command = core[0];
-  if (!command) return false;
-  if (OVERLAY_SKIP_COMMANDS.has(command)) return false;
-  return true;
-}
-
-function shouldInjectOpenConfig(tokens) {
-  const core = stripLeadingFlags(tokens);
-  const command = core[0];
-  if (!command || !OVERLAY_SESSION_OPEN_COMMANDS.has(command)) return false;
-  return !tokens.some((t) => t === "--config" || t.startsWith("--config="));
-}
-
-function injectOpenConfig(tokens) {
-  if (!isOverlayEnabled() || !shouldInjectOpenConfig(tokens)) {
-    return tokens;
-  }
-  const configPath = resolveCliConfigPath();
-  const next = [...tokens];
-  const core = stripLeadingFlags(tokens);
-  const insertAt = tokens.indexOf(core[0]);
-  next.splice(insertAt + 1, 0, `--config=${configPath}`);
-  return next;
-}
-
-function buildOverlayRunCode(payload) {
-  const browserScript = getBrowserOverlayScript();
-  const payloadJson = JSON.stringify(payload);
-  return [
-    "async page => {",
-    `  const browserScript = ${JSON.stringify(browserScript)};`,
-    `  const payload = ${payloadJson};`,
-    "  await page.evaluate(({ script, data }) => {",
-    "    // eslint-disable-next-line no-eval",
-    "    eval(script);",
-    "    if (window.__helixCliOverlay) window.__helixCliOverlay.update(data);",
-    "  }, { script: browserScript, data: payload });",
-    "}",
-  ].join("\n");
-}
-
-module.exports = {
-  OVERLAY_SKIP_COMMANDS,
-  isOverlayEnabled,
-  resolveCliConfigPath,
-  stripLeadingFlags,
-  describeOverlayPayload,
-  shouldUpdateOverlay,
-  shouldInjectOpenConfig,
-  injectOpenConfig,
-  buildOverlayRunCode,
-};