helixlife-v5-cli 1.1.9 → 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

@@ -0,0 +1,208 @@
+/* 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

@@ -4,6 +4,13 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const PACKAGE_JSON = require(path.join(__dirname, '..', 'package.json'));
+const {
+  parseVisualFlags,
+  injectVisualConfig,
+  shouldWrapWithVisual,
+  runWithVisualFeedback,
+  DEFAULT_VISUAL_ENABLED,
+} = require('./visual');
 
 /** 默认快照/下载等工作区目录名（相对 cwd），替代引擎默认的 .playwright-cli */
 const DEFAULT_OUTPUT_DIR_NAME = 'helixlife-v5-cli';
@@ -34,21 +41,38 @@ 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) {
-  const result = spawnSync(process.execPath, [playwrightCliEntry(), ...args], {
-    stdio: 'inherit',
+function runPlaywrightCliPassthrough(args, options = {}) {
+  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;
+    if (!options.capture) {
+      console.error(`[${PACKAGE_JSON.name}] 子进程被终止: ${result.signal}`);
+    }
+    return options.capture
+      ? { code: 1, stdout: result.stdout || '', stderr: result.stderr || '' }
+      : 1;
   }
-  return result.status === null || result.status === undefined ? 1 : result.status;
+  const code = result.status === null || result.status === undefined ? 1 : result.status;
+  if (options.capture) {
+    return { code, stdout: result.stdout || '', stderr: result.stderr || '' };
+  }
+  return code;
 }
 
 function parseHelixFlags(tokens, startIndex) {
@@ -57,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) {
@@ -85,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;
 }
 
@@ -105,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('');
@@ -112,8 +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}）`
+    `  HELIX_OUTPUT_DIR / PLAYWRIGHT_MCP_OUTPUT_DIR（默认输出目录 <cwd>/${DEFAULT_OUTPUT_DIR_NAME}）、`
   );
+  console.log('  HELIX_VISUAL=0（全局关闭视觉反馈，可用 --visual 单次开启）');
 }
 
 function getBaseUrl() {
@@ -122,8 +170,7 @@ 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}`);
   }
@@ -152,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
@@ -164,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;
@@ -198,19 +263,17 @@ async function main(argv = process.argv) {
     return 2;
   }
 
-  return runPlaywrightCliPassthrough(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

@@ -0,0 +1,5 @@
+{
+  "browser": {
+    "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.1.9",
+  "version": "1.2.1",
   "description": "Helix（vip.helixlife.cn）精细化浏览器自动化命令行工具。",
   "main": "helix-cli.js",
   "bin": {