helixlife-v5-cli 1.1.3

package/README.md

@@ -0,0 +1,87 @@
+# helixlife-v5-cli
+
+全局安装 **`helixlife-v5-cli`** 后即可直接操作网页。该工具默认会把命令行参数原样透传到底层浏览器自动化引擎，同时附带 **Helix** 站点一键流程 `helix home` / `helix doctor`。
+
+## 安装（仅 npm 全局安装）
+
+```bash
+npm install -g helixlife-v5-cli
+```
+
+> 不再支持 / 不建议项目级本地安装与 `npx helixlife-v5-cli`，以避免污染用户工程的 `node_modules` 与 lockfile。
+
+全局安装后直接：
+
+```bash
+helixlife-v5-cli --help
+helixlife-v5-cli list
+```
+
+## 首次执行前的自检（建议）
+
+每次新会话第一次使用前，按下面 3 步确认环境就绪（与 Cursor skill 中代理执行的逻辑一致）：
+
+```bash
+# 1. 是否已安装；未安装时执行 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
+```
+
+## 本地开发（与全局命令等价）
+
+仓库克隆后，**仅在开发本仓库时**使用 `node helix-cli.js`：
+
+```bash
+npm install
+node helix-cli.js --help
+node helix-cli.js list
+```
+
+## Helix 快捷命令
+
+封装了「打开会话 → `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
+```
+
+## 环境与兼容说明
+
+- **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` 生效；也可直接设置后者覆盖）
+
+## 命令说明
+
+详见 Cursor skill **helixlife-v5-cli**（`.cursor/skills/helixlife-v5-cli/SKILL.md`，通常不随 npm 包发布）；站点流程以包内 **`references/vip.helixlife.cn.site-ops.md`** 为准。
+
+## 依赖
+
+运行时依赖：`@playwright/cli` ^0.1.9（要求 Node ≥ 18）。

package/helix-cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * helixlife-v5-cli 入口：将参数透传给底层浏览器自动化引擎。
+ */
+'use strict';
+
+const { main } = require('./lib/cli');
+
+if (require.main === module) {
+  main()
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((e) => {
+      console.error(e);
+      process.exit(2);
+    });
+}

package/lib/cli.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const PACKAGE_JSON = require(path.join(__dirname, '..', 'package.json'));
+
+/** 默认快照/下载等工作区目录名（相对 cwd），替代引擎默认的 .playwright-cli */
+const DEFAULT_OUTPUT_DIR_NAME = '.helixlife-v5-cli';
+
+function playwrightCliEntry() {
+  return require.resolve('@playwright/cli/playwright-cli.js');
+}
+
+/**
+ * 解析 CLI 输出目录（快照、下载、trace 等）。优先 PLAYWRIGHT_MCP_OUTPUT_DIR，其次 HELIX_OUTPUT_DIR。
+ */
+function resolveOutputDir() {
+  const explicit =
+    process.env.PLAYWRIGHT_MCP_OUTPUT_DIR || process.env.HELIX_OUTPUT_DIR;
+  const dir = explicit || DEFAULT_OUTPUT_DIR_NAME;
+  return path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
+}
+
+/** 传给底层引擎子进程的环境变量（含输出目录覆盖） */
+function buildChildEnv() {
+  const env = { ...process.env };
+  if (!env.PLAYWRIGHT_MCP_OUTPUT_DIR) {
+    env.PLAYWRIGHT_MCP_OUTPUT_DIR = resolveOutputDir();
+  }
+  return env;
+}
+
+/**
+ * 将参数原样交给底层浏览器自动化引擎，返回子进程退出码。
+ * 使用 node 直接执行入口脚本，避免依赖 npx、Shell 与 PATH，在 Windows / macOS 上一致。
+ */
+function runPlaywrightCliPassthrough(args) {
+  const result = spawnSync(process.execPath, [playwrightCliEntry(), ...args], {
+    stdio: 'inherit',
+    env: buildChildEnv(),
+    windowsHide: true,
+  });
+  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 parseHelixFlags(tokens, startIndex) {
+  const options = {
+    headless: false,
+    cdpUrl: process.env.HELIX_CDP_URL || 'http://127.0.0.1:9222',
+    profile:
+      process.env.HELIX_PROFILE_DIR || path.join(process.cwd(), '.helixlife-profile'),
+  };
+  for (let i = startIndex; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t === '--headless') {
+      options.headless = true;
+    } else if (t === '--profile') {
+      const next = tokens[i + 1];
+      if (next === undefined) {
+        console.error(`[${PACKAGE_JSON.name}] --profile requires a value`);
+        return null;
+      }
+      options.profile = next;
+      i += 1;
+    } else if (t.startsWith('--profile=')) {
+      options.profile = t.slice('--profile='.length);
+    } else if (t === '--cdp-url') {
+      const next = tokens[i + 1];
+      if (next === undefined) {
+        console.error(`[${PACKAGE_JSON.name}] --cdp-url requires a value`);
+        return null;
+      }
+      options.cdpUrl = next;
+      i += 1;
+    } else {
+      console.error(`[${PACKAGE_JSON.name}] unknown option for helix command: ${t}`);
+      return null;
+    }
+  }
+  return options;
+}
+
+function printHelp() {
+  const n = PACKAGE_JSON.name;
+  console.log(`${n} v${PACKAGE_JSON.version}`);
+  console.log('');
+  console.log('默认将所有参数透传给底层浏览器自动化引擎（与直接调用相同）：');
+  console.log(`  ${n} list`);
+  console.log(`  ${n} open --headed`);
+  console.log(`  ${n} snapshot`);
+  console.log('');
+  console.log('Helix 站点快捷子命令：');
+  console.log(
+    `  ${n} helix home [--headless] [--profile <dir>]     单次 open 到 HELIX_BASE_URL（有头），再输出页面标题`
+  );
+  console.log(
+    `  ${n} helix doctor [--cdp-url <url>] [--profile <dir>]   先 list，再执行 helix home`
+  );
+  console.log('');
+  console.log('本地开发可使用：');
+  console.log('  node helix-cli.js <同上参数>');
+  console.log('');
+  console.log(
+    '环境变量：HELIX_BASE_URL、HELIX_CDP_URL、HELIX_PROFILE_DIR（默认 profile 目录）、'
+  );
+  console.log(
+    `  HELIX_OUTPUT_DIR / PLAYWRIGHT_MCP_OUTPUT_DIR（默认输出目录 <cwd>/${DEFAULT_OUTPUT_DIR_NAME}）`
+  );
+}
+
+function getBaseUrl() {
+  return process.env.HELIX_BASE_URL || 'https://vip.helixlife.cn/';
+}
+
+function helixHome(options) {
+  const baseUrl = getBaseUrl();
+  // 单次 `open <url>`：与手动打开一致，避免先 about:blank 再二次 `goto` 的跨进程导航竞态（偶发样式/布局不全）。
+  const openArgs = ['open', baseUrl];
+  if (options.profile) {
+    openArgs.push(`--profile=${options.profile}`);
+  }
+  if (!options.headless) {
+    openArgs.push('--headed');
+  }
+  const code = runPlaywrightCliPassthrough(openArgs);
+  if (code !== 0) {
+    return code;
+  }
+  console.error(`[${PACKAGE_JSON.name}] opened: ${baseUrl}`);
+  return runPlaywrightCliPassthrough(['eval', 'document.title']);
+}
+
+function helixDoctor(options) {
+  const baseUrl = getBaseUrl();
+  console.error(`[${PACKAGE_JSON.name} doctor] HELIX_BASE_URL: ${baseUrl}`);
+  console.error(`[${PACKAGE_JSON.name} doctor] HELIX_CDP_URL (hint): ${options.cdpUrl}`);
+  console.error(`[${PACKAGE_JSON.name} doctor] HELIX_PROFILE_DIR: ${options.profile}`);
+  console.error(`[${PACKAGE_JSON.name} doctor] helixlife-v5-cli list`);
+  const code = runPlaywrightCliPassthrough(['list']);
+  if (code !== 0) {
+    return code;
+  }
+  console.error(`[${PACKAGE_JSON.name} doctor] helix home`);
+  return helixHome(options);
+}
+
+/**
+ * @param {string[]} argv process.argv
+ * @returns {Promise<number>} exit code
+ */
+async function main(argv = process.argv) {
+  const tokens = argv.slice(2);
+
+  if (tokens[0] === '--helix-help' || tokens[0] === 'helix-help') {
+    printHelp();
+    return 0;
+  }
+
+  // 勿透传到底层引擎：否则 --version 会变成 @playwright/cli 的版本（如 0.1.x），易与本体版本混淆。
+  if (tokens[0] === '--version' || tokens[0] === '-v') {
+    console.log(PACKAGE_JSON.version);
+    return 0;
+  }
+
+  if (tokens.length === 0) {
+    console.error(`${PACKAGE_JSON.name}: 缺少子命令。透传示例：list、open、snapshot。`);
+    console.error(`Helix 快捷：helix home | helix doctor。详细说明：${PACKAGE_JSON.name} --helix-help`);
+    return 1;
+  }
+
+  if (tokens[0] === 'helix') {
+    const sub = tokens[1];
+    const rest = parseHelixFlags(tokens, 2);
+    if (rest === null) {
+      return 2;
+    }
+    if (sub === 'home') {
+      return helixHome(rest);
+    }
+    if (sub === 'doctor') {
+      return helixDoctor(rest);
+    }
+    if (sub === 'help' || sub === '--help' || sub === '-h' || sub === undefined) {
+      printHelp();
+      return 0;
+    }
+    console.error(
+      `[${PACKAGE_JSON.name}] unknown helix subcommand: ${sub}. See --helix-help`
+    );
+    return 2;
+  }
+
+  return runPlaywrightCliPassthrough(tokens);
+}
+
+main.printHelp = printHelp;
+main.runPlaywrightCliPassthrough = runPlaywrightCliPassthrough;
+main.playwrightCliEntry = playwrightCliEntry;
+
+if (require.main === module) {
+  main(process.argv).then(
+    (code) => process.exit(code),
+    (err) => {
+      console.error(err);
+      process.exit(2);
+    }
+  );
+}
+
+module.exports = {
+  main,
+  resolveOutputDir,
+  buildChildEnv,
+  DEFAULT_OUTPUT_DIR_NAME,
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "helixlife-v5-cli",
+  "version": "1.1.3",
+  "description": "Helix（vip.helixlife.cn）精细化浏览器自动化命令行工具。",
+  "main": "helix-cli.js",
+  "bin": {
+    "helixlife-v5-cli": "helix-cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "helixlife",
+    "cli",
+    "playwright",
+    "cdp"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node ./helix-cli.js helix doctor"
+  },
+  "files": [
+    "references",
+    "scripts",
+    "helix-cli.js",
+    "lib",
+    "README.md"
+  ],
+  "dependencies": {
+    "@playwright/cli": "^0.1.9"
+  }
+}