helixlife-v5-cli 1.2.7 → 1.2.9

package/README.md

@@ -1,87 +1,62 @@
 # helixlife-v5-cli
 
-全局安装 **`helixlife-v5-cli`** 后即可直接操作网页。该工具默认会把命令行参数原样透传到底层浏览器自动化引擎，同时附带 **Helix** 站点一键流程 `helix home` / `helix doctor`。
+Helix（vip.helixlife.cn）精细化浏览器自动化 CLI — npm 包运行时。
 
-## 安装（仅 npm 全局安装）
+业务规则与 Agent Skill 文档在独立 **Skill 仓库**；本仓库仅包含可全局安装的 CLI。
 
-```bash
-npm install -g helixlife-v5-cli
-```
+## 安装
 
-> 不再支持 / 不建议项目级本地安装与 `npx helixlife-v5-cli`，以避免污染用户工程的 `node_modules` 与 lockfile。
-
-全局安装后直接：
+**前置条件**：Node.js ≥ 18、npm。
 
 ```bash
-helixlife-v5-cli --help
-helixlife-v5-cli list
-```
-
-## 首次执行前的自检（建议）
-
-每次新会话第一次使用前，按下面 3 步确认环境就绪（与 Cursor skill 中代理执行的逻辑一致）：
-
-```bash
-# 1. 是否已安装；未安装时执行 npm install -g helixlife-v5-cli
+npm install -g helixlife-v5-cli
 helixlife-v5-cli --version
-
-# 2. 取得线上最新版本
-npm view helixlife-v5-cli version
-
-# 3. 与本地不一致时升级到最新
-npm install -g helixlife-v5-cli@latest
 ```
 
-`PATH` 不含 `npm bin -g` 时（nvm / Volta / 自定义 prefix 常见），临时兜底：
+从源码目录安装（开发/本地验证）：
 
 ```bash
-node "$(npm root -g)/helixlife-v5-cli/helix-cli.js" --version
+cd helixlife-v5-cli
+npm install -g .
+helixlife-v5-cli --version
 ```
 
-## 本地开发（与全局命令等价）
+首次执行任意浏览器命令时，CLI 会自动校验并安装 `@playwright/cli` 运行时依赖（需联网）。设 `HELIX_AUTO_INSTALL=0` 可关闭自动安装。
 
-仓库克隆后，**仅在开发本仓库时**使用 `node helix-cli.js`：
+## 快速开始
 
 ```bash
-npm install
-node helix-cli.js --help
-node helix-cli.js list
+helixlife-v5-cli list
+helixlife-v5-cli open https://vip.helixlife.cn/ --profile=.helixlife-profile --headed
+helixlife-v5-cli snapshot
+helixlife-v5-cli click "getByRole('button', { name: '登录' })"
 ```
 
-## Helix 快捷命令
+完整命令参考见 Skill 仓库 `references/cli-reference.md`；Helix 站点强约束见 Skill 仓库 `SKILL.md`。
 
-封装了「打开会话 → `goto` 到 HELIX_BASE_URL → `eval` 标题」，对应原 skill 文档里分步执行的启动流程：
+## 目录结构
 
-```bash
-helixlife-v5-cli helix home
-helixlife-v5-cli helix home --headless
-helixlife-v5-cli helix doctor
-helixlife-v5-cli helix doctor --cdp-url http://127.0.0.1:9222
 ```
-
-包装器自带的用法摘要（不参加透传）：
-
-```bash
-helixlife-v5-cli --helix-help
+helixlife-v5-cli/
+├── helix-cli.js          # CLI 入口（npm bin）
+├── package.json
+├── lib/                  # 运行时逻辑
+├── node_modules/         # 依赖（安装后生成，git 忽略）
+└── scripts/
+    └── README.md         # run-code 脚本总索引
 ```
 
-## 环境与兼容说明
-
-- **Windows / macOS**：通过当前 Node 直接引用包内引擎脚本启动子进程，不依赖 Shell、`npx` 或 PATH，便于 CI 与 Agent 调用。
-- **stdin/stdout/stderr**：子进程继承 `stdio: 'inherit'`，交互行为与直接调用引擎一致。
-- **退出码**：透传底层引擎退出码；包装器在无参数、`helix` 子命令错误时返回非零码。
-
-### 环境变量
+## 维护者说明
 
-- `HELIX_BASE_URL`：目标地址，默认 `https://vip.helixlife.cn/`
-- `HELIX_CDP_URL`：`helix doctor` 时在日志中输出的 CDP 参考地址，默认 `http://127.0.0.1:9222`
-- `HELIX_PROFILE_DIR`：`helix home/doctor` 默认使用的 profile 目录，默认 `<当前目录>/.helixlife-profile`
-- `HELIX_OUTPUT_DIR`：快照、下载、trace 等工作区目录，默认 `<当前目录>/helixlife-v5-cli`（通过底层 `PLAYWRIGHT_MCP_OUTPUT_DIR` 生效；也可直接设置后者覆盖）
+更新 `@playwright/cli` 依赖时，修改 `package.json` 中的版本，在 `helixlife-v5-cli` 目录执行 `npm i`，再运行 `scripts/maintainer/strip-extra-skills.ps1` 剔除 `node_modules` 内多余的 `SKILL.md`，确认 `helixlife-v5-cli --version` 正常。
 
-## 命令说明
+发布前确认 `package.json` 的 `bin` 字段指向 `helix-cli.js`，且 `files` 包含 `helix-cli.js`、`lib/`、`scripts/`。
 
-详见 Cursor skill **helixlife-v5-cli**（`.cursor/skills/helixlife-v5-cli/SKILL.md`，通常不随 npm 包发布）；站点流程以包内 **`references/vip.helixlife.cn.site-ops.md`** 为准。
+## 与 Skill 仓库的关系
 
-## 依赖
+| 组件 | 位置 |
+| --- | --- |
+| CLI 运行时 | 本仓库 → `npm install -g helixlife-v5-cli` |
+| Skill + 业务文档 | 独立 Skill 仓库 → `SKILL.md` + `references/` |
 
-运行时依赖：`@playwright/cli` ^0.1.9（要求 Node ≥ 18）。
+Agent 通过 Skill 读文档、通过本 CLI 跑命令，二者以全局 npm 安装衔接。

package/helix-cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * helixlife-v5-cli 入口：将参数透传给底层浏览器自动化引擎。
  */
@@ -10,7 +10,12 @@ if (require.main === module) {
   main()
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((e) => {
-      console.error(e);
+      if (process.env.HELIX_DEBUG) {
+        console.error(e);
+      } else {
+        console.error(`[helixlife-v5-cli] 执行失败: ${e && e.message ? e.message : e}`);
+        console.error('[helixlife-v5-cli] 设置环境变量 HELIX_DEBUG=1 可查看完整堆栈。');
+      }
       process.exit(2);
     });
 }

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

@@ -1,7 +1,16 @@
 {
   "browser": {
+    "launchOptions": {
+      "args": [
+        "--start-maximized"
+      ]
+    },
+    "initPage": [
+      "C:/Users/zouyh/Desktop/WorkSpace/jieluoxuan/cli/helix-cli/helixlife-v5-cli/lib/browser-window-maximize.init-page.js",
+      "C:/Users/zouyh/Desktop/WorkSpace/jieluoxuan/cli/helix-cli/helixlife-v5-cli/lib/browser-css-cache-guard.init-page.js"
+    ],
     "initScript": [
-      "C:/Users/zouyh/Desktop/WorkSpace/jieluoxuan/cli/helix-cli/lib/automation-overlay.init.js"
+      "C:/Users/zouyh/Desktop/WorkSpace/jieluoxuan/cli/helix-cli/helixlife-v5-cli/lib/automation-overlay.init.js"
     ]
   }
 }

package/lib/automation-file-chooser-guard.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * automation-file-chooser-guard
+ *
+ * 场景隔离（方案 1）：
+ *   - 默认（HELIX_NATIVE_FILE_CHOOSER=1）：Tab 不常驻订阅 filechooser → 用户手动点上传可弹系统选文件框。
+ *   - run-code / upload / drop 自动化链路：在执行期间临时 page.on('filechooser') → 启用 CDP 拦截，
+ *     避免点击上传控件时弹出系统原生文件选择框；脚本内 waitForEvent('filechooser') / setInputFiles 照常工作。
+ *
+ * 实现要点：
+ *   - 守卫监听器仅记录未处理的 chooser，在 finally 中尝试 setFiles([]) 关闭遗留弹层。
+ *   - 与 waitForEvent('filechooser') 兼容：守卫不主动 setFiles，由脚本消费；finally 仅清理残留。
+ */
+
+/** 注入到 async page => { ... } 体内的守卫代码（在 try 内、用户逻辑之前）。 */
+const GUARD_SETUP = `
+  let __helixActiveFc = null;
+  const __helixFcGuard = (chooser) => {
+    __helixActiveFc = chooser;
+  };
+  page.on('filechooser', __helixFcGuard);
+`;
+
+/** 与 GUARD_SETUP 配对的 finally 清理片段。 */
+const GUARD_TEARDOWN = `
+  page.off('filechooser', __helixFcGuard);
+  if (__helixActiveFc) {
+    try {
+      await __helixActiveFc.setFiles([]);
+    } catch (_) {
+      /* chooser 可能已被脚本 setFiles 消费 */
+    }
+    __helixActiveFc = null;
+  }
+`;
+
+/** 剥掉源码开头的空白与行注释、块注释（不影响函数体内的注释）。 */
+function stripLeadingComments(source) {
+  let s = String(source).trimStart();
+  for (;;) {
+    if (s.startsWith('//')) {
+      const nl = s.indexOf('\n');
+      s = nl === -1 ? '' : s.slice(nl + 1).trimStart();
+      continue;
+    }
+    if (s.startsWith('/*')) {
+      const end = s.indexOf('*/');
+      if (end === -1) break;
+      s = s.slice(end + 2).trimStart();
+      continue;
+    }
+    break;
+  }
+  return s;
+}
+
+/** 判断是否为 `async page =>` / `async (page) =>` 箭头函数（允许 leading 注释）。 */
+function isRunCodeArrowFunction(source) {
+  const head = stripLeadingComments(source);
+  return /^async\s+page\s*=>/.test(head) || /^async\s*\(\s*page\s*\)\s*=>/.test(head);
+}
+
+/**
+ * 将用户 run-code 源（`async page => { ... }` 或裸函数体）包上一层自动化上传守卫。
+ * @param {string} userSource
+ * @returns {string} 完整 `async page => { ... }` 源码字符串
+ */
+function wrapUserRunCodeWithUploadGuard(userSource) {
+  const trimmed = String(userSource || '').trim().replace(/;+\s*$/, '');
+  if (!trimmed) {
+    throw Object.assign(new Error('run-code 脚本为空'), { code: 'E_BAD_ARG' });
+  }
+
+  const isArrow = isRunCodeArrowFunction(trimmed);
+
+  const userFnLiteral = isArrow ? trimmed : `async page => { ${trimmed} }`;
+
+  return `async page => {${GUARD_SETUP}
+  try {
+    const __userFn = ${userFnLiteral};
+    return await __userFn(page);
+  } finally {${GUARD_TEARDOWN}
+  }
+}`;
+}
+
+/**
+ * 对 run-code CLI tokens 注入上传守卫（不依赖 visual 包装）。
+ * @param {string[]} tokens
+ * @returns {string[]}
+ */
+function applyRunCodeAutomationGuard(tokens) {
+  const { parseRunCodePayload } = require('./visual-page-wrap');
+  const { code, passthroughFlags } = parseRunCodePayload(tokens);
+  const guarded = wrapUserRunCodeWithUploadGuard(code);
+  return ['run-code', guarded, ...passthroughFlags];
+}
+
+/** 需启用上传守卫的自动化子命令（会触发文件选择或 setInputFiles 的 CLI 通道）。 */
+const AUTOMATION_UPLOAD_COMMANDS = new Set(['run-code', 'upload', 'drop']);
+
+/**
+ * @param {string[]} tokens 已剥离 visual flags 的 argv
+ * @returns {boolean}
+ */
+function isAutomationUploadCommand(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;
+  const cmd = tokens[i];
+  return AUTOMATION_UPLOAD_COMMANDS.has(cmd);
+}
+
+/**
+ * upload / drop：用极简 run-code 注册/注销守卫（跨多次 CLI 调用，挂在 page 对象上）。
+ * @param {'enable' | 'disable'} mode
+ * @returns {string} run-code 源码
+ */
+function buildUploadGuardOnlyRunCode(mode) {
+  if (mode === 'enable') {
+    return `async page => {
+  if (!page.__helixUploadGuardInstalled) {
+    page.__helixActiveFc = null;
+    page.__helixFcGuard = (chooser) => {
+      page.__helixActiveFc = chooser;
+    };
+    page.on('filechooser', page.__helixFcGuard);
+    page.__helixUploadGuardInstalled = true;
+  }
+}`;
+  }
+  return `async page => {
+  if (page.__helixFcGuard) {
+    page.off('filechooser', page.__helixFcGuard);
+    page.__helixFcGuard = null;
+    page.__helixUploadGuardInstalled = false;
+  }
+  if (page.__helixActiveFc) {
+    try {
+      await page.__helixActiveFc.setFiles([]);
+    } catch (_) {}
+    page.__helixActiveFc = null;
+  }
+}`;
+}
+
+/**
+ * 对 upload / drop 命令：先 enable 守卫 → 执行原命令 → disable 守卫。
+ * @param {string[]} tokens
+ * @param {(args: string[], opts?: object) => number | { code: number, stdout?: string, stderr?: string }} runPassthrough
+ * @returns {number}
+ */
+function runUploadCommandWithGuard(tokens, runPassthrough) {
+  const enableCode = buildUploadGuardOnlyRunCode('enable');
+  const disableCode = buildUploadGuardOnlyRunCode('disable');
+
+  const pre = runPassthrough(['run-code', enableCode], { capture: true });
+  const preCode = typeof pre === 'object' ? pre.code : pre;
+  if (preCode !== 0) {
+    return preCode;
+  }
+
+  const main = runPassthrough(tokens);
+  const mainCode = typeof main === 'object' ? main.code : main;
+
+  const post = runPassthrough(['run-code', disableCode], { capture: true });
+  const postCode = typeof post === 'object' ? post.code : post;
+
+  return mainCode !== 0 ? mainCode : postCode;
+}
+
+module.exports = {
+  GUARD_SETUP,
+  GUARD_TEARDOWN,
+  wrapUserRunCodeWithUploadGuard,
+  applyRunCodeAutomationGuard,
+  isAutomationUploadCommand,
+  AUTOMATION_UPLOAD_COMMANDS,
+  runUploadCommandWithGuard,
+};