@web-auto/webauto 0.1.14 → 0.1.15

package/README.md

@@ -0,0 +1,137 @@
+# @web-auto/webauto
+
+Windows 优先的 WebAuto CLI + Desktop UI 使用说明。
+
+## 1. 安装（Windows）
+
+要求：
+- Node.js 18+（建议 20+）
+- npm 可用
+
+全局安装：
+
+```bat
+npm install -g @web-auto/webauto
+```
+
+验证：
+
+```bat
+webauto --help
+```
+
+## 2. 直接启动 UI
+
+最直接方式：
+
+```bat
+webauto ui console
+```
+
+或用 UI CLI 自动拉起（适合脚本化）：
+
+```bat
+webauto ui cli start --json
+webauto ui cli status --json
+```
+
+说明：
+- 首次启动会自动准备 Desktop runtime 依赖（Electron），不需要手工安装。
+- 启动成功后，UI CLI bridge 默认端口是 `7716`。
+
+## 3. UI CLI 常用命令（模拟真实 UI 操作）
+
+```bat
+webauto ui cli --help
+
+:: 切换到任务页
+webauto ui cli tab --tab tasks --json
+
+:: 输入任务参数
+webauto ui cli input --selector "#task-keyword" --value "deepseek" --json
+webauto ui cli input --selector "#task-target" --value "20" --json
+
+:: 点击执行
+webauto ui cli click --selector "#task-run-ephemeral-btn" --json
+
+:: 读取当前 UI 快照
+webauto ui cli status --json
+webauto ui cli snapshot --json
+
+:: 元素探测
+webauto ui cli probe --selector "#task-likes" --json
+```
+
+任务状态查看（后端状态）：
+
+```bat
+webauto xhs status --json
+webauto xhs status --run-id <runId> --json
+```
+
+## 4. Windows 路径与设置
+
+默认数据目录（未设置环境变量时）：
+- 有 `D:` 盘：`D:\webauto`
+- 无 `D:` 盘：`%USERPROFILE%\.webauto`
+
+可选环境变量：
+- `WEBAUTO_HOME`：显式指定数据根目录（推荐）
+- `WEBAUTO_ROOT` / `WEBAUTO_PORTABLE_ROOT`：兼容旧变量（会归一化到 `.webauto`）
+
+PowerShell 设置示例：
+
+```powershell
+$env:WEBAUTO_HOME = "D:\webauto"
+webauto ui console
+```
+
+CMD 设置示例：
+
+```bat
+set WEBAUTO_HOME=D:\webauto
+webauto ui console
+```
+
+不设置也可以直接用，系统会按默认规则落盘。
+
+## 5. 首次安装常见问题
+
+### 5.1 `Lock file can not be created` / 启动失败
+
+说明：通常是残留的 Electron/Node 进程占用。
+
+```bat
+taskkill /F /IM electron.exe /T
+taskkill /F /IM node.exe /T
+webauto ui console
+```
+
+### 5.2 `ui cli fetch failed`
+
+先确认 UI 已启动并就绪：
+
+```bat
+webauto ui cli start --json
+webauto ui cli status --json
+```
+
+若仍失败，前台启动看日志：
+
+```bat
+webauto ui console --no-daemon
+```
+
+## 6. 资源检查/安装
+
+```bat
+webauto xhs install --check --json
+webauto xhs install --download-browser --json
+webauto xhs install --download-geoip --json
+```
+
+## 7. 开发者（仓库模式）
+
+在仓库中开发请看：
+- `apps/desktop-console/README.md`
+

package/apps/webauto/entry/flow-gate.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import minimist from 'minimist';
+import {
+  listPlatformFlowGates,
+  loadFlowGateDoc,
+  patchPlatformFlowGate,
+  resetPlatformFlowGate,
+  resolveFlowGatePath,
+  resolvePlatformFlowGate,
+} from './lib/flow-gate.mjs';
+
+function normalizePlatform(value) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return 'xiaohongshu';
+  if (text === 'xhs') return 'xiaohongshu';
+  return text;
+}
+
+function toJsonMode(argv) {
+  return argv.json === true || argv.j === true;
+}
+
+function printHelp() {
+  console.log([
+    'Usage: node apps/webauto/entry/flow-gate.mjs <get|list|set|reset|path> [options]',
+    'Options:',
+    '  --platform <name>       平台名（默认 xiaohongshu）',
+    '  --patch-json <json>     set 动作补丁 JSON（对象）',
+    '  --json                  输出 JSON',
+    '',
+    'Examples:',
+    '  node apps/webauto/entry/flow-gate.mjs get --platform xiaohongshu --json',
+    '  node apps/webauto/entry/flow-gate.mjs list --json',
+    '  node apps/webauto/entry/flow-gate.mjs set --platform xiaohongshu --patch-json \'{"noteInterval":{"minMs":2600,"maxMs":5200}}\' --json',
+    '  node apps/webauto/entry/flow-gate.mjs reset --platform xiaohongshu --json',
+  ].join('\n'));
+}
+
+function parsePatchJson(raw) {
+  const text = String(raw || '').trim();
+  if (!text) throw new Error('missing --patch-json');
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`invalid --patch-json: ${error?.message || String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('--patch-json must be object JSON');
+  }
+  return parsed;
+}
+
+async function main() {
+  const argv = minimist(process.argv.slice(2), {
+    boolean: ['help', 'h', 'json', 'j'],
+    string: ['platform', 'patch-json'],
+  });
+  if (argv.help || argv.h) {
+    printHelp();
+    return;
+  }
+
+  const action = String(argv._[0] || 'get').trim().toLowerCase();
+  const platform = normalizePlatform(argv.platform);
+  const jsonMode = toJsonMode(argv);
+  const path = resolveFlowGatePath();
+
+  if (action === 'path') {
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, path }, null, 2));
+    } else {
+      console.log(path);
+    }
+    return;
+  }
+
+  if (action === 'get') {
+    const gate = await resolvePlatformFlowGate(platform);
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, platform, path, gate }, null, 2));
+    } else {
+      console.log(`[flow-gate] platform=${platform}`);
+      console.log(JSON.stringify(gate, null, 2));
+      console.log(`[flow-gate] file=${path}`);
+    }
+    return;
+  }
+
+  if (action === 'list') {
+    const gates = await listPlatformFlowGates();
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, path, platforms: gates }, null, 2));
+    } else {
+      console.log(JSON.stringify(gates, null, 2));
+      console.log(`[flow-gate] file=${path}`);
+    }
+    return;
+  }
+
+  if (action === 'set') {
+    const patch = parsePatchJson(argv['patch-json']);
+    const gate = await patchPlatformFlowGate(platform, patch);
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, action, platform, path, gate }, null, 2));
+    } else {
+      console.log(`[flow-gate] updated platform=${platform}`);
+      console.log(JSON.stringify(gate, null, 2));
+      console.log(`[flow-gate] file=${path}`);
+    }
+    return;
+  }
+
+  if (action === 'reset') {
+    const gate = await resetPlatformFlowGate(platform);
+    if (jsonMode) {
+      console.log(JSON.stringify({ ok: true, action, platform, path, gate }, null, 2));
+    } else {
+      console.log(`[flow-gate] reset platform=${platform}`);
+      console.log(JSON.stringify(gate, null, 2));
+      console.log(`[flow-gate] file=${path}`);
+    }
+    return;
+  }
+
+  if (action === 'show-doc') {
+    const doc = await loadFlowGateDoc();
+    if (jsonMode) console.log(JSON.stringify({ ok: true, path, doc }, null, 2));
+    else console.log(JSON.stringify(doc, null, 2));
+    return;
+  }
+
+  throw new Error(`unknown action: ${action}`);
+}
+
+main().catch((err) => {
+  console.error(err?.message || String(err));
+  process.exit(1);
+});