@web-auto/webauto 0.1.18 → 0.1.19

package/README.md

@@ -1,137 +1,206 @@
 # @web-auto/webauto
 
-Windows 优先的 WebAuto CLI + Desktop UI 使用说明。
+Windows 优先的 WebAuto CLI + Desktop UI 使用说明（面向直接安装使用）。
 
-## 1. 安装（Windows）
+## 1. 安装
 
 要求：
 - Node.js 18+（建议 20+）
 - npm 可用
 
-全局安装：
-
 ```bat
 npm install -g @web-auto/webauto
+webauto --help
 ```
 
-验证：
+## 2. 首次启动（推荐路径）
+
+直接启动 UI：
 
 ```bat
-webauto --help
+webauto ui console
+```
+
+也可以用 UI CLI 自动拉起（适合脚本/远程）：
+
+```bat
+webauto ui cli start --json
+webauto ui cli status --json
 ```
 
-## 2. 直接启动 UI
+说明：
+- `webauto` 默认会自动设置运行根目录，不需要手工设置 `WEBAUTO_REPO_ROOT`。
+- 首次运行会按需准备运行依赖（Electron/服务进程）。
+
+## 3. Windows 默认目录规则
+
+未设置环境变量时：
+- 如果存在 `D:` 盘：默认使用 `D:\webauto`
+- 否则：默认使用 `%USERPROFILE%\.webauto`
 
-最直接方式：
+可选覆盖（仅在你需要自定义目录时）：
+- `WEBAUTO_HOME`（推荐）
+- `WEBAUTO_ROOT` / `WEBAUTO_PORTABLE_ROOT`（兼容旧变量）
+
+PowerShell 示例：
+
+```powershell
+$env:WEBAUTO_HOME = 'E:\my-webauto'
+webauto ui console
+```
+
+CMD 示例：
 
 ```bat
+set WEBAUTO_HOME=E:\my-webauto
 webauto ui console
 ```
 
-或用 UI CLI 自动拉起（适合脚本化）：
+## 4. UI 常用流程（推荐人机流程）
+
+1. 启动 UI：`webauto ui console`
+2. 在任务页填写关键词、目标数、账号等参数
+3. 点“保存并执行”或“执行”
+4. 用 UI CLI 查询当前状态（可选）
 
 ```bat
-webauto ui cli start --json
 webauto ui cli status --json
+webauto xhs status --json
 ```
 
 说明：
-- 首次启动会自动准备 Desktop runtime 依赖（Electron），不需要手工安装。
-- 启动成功后，UI CLI bridge 默认端口是 `7716`。
+- `ui cli status`：轻量健康/状态查询（适合轮询）
+- `ui cli snapshot`：完整 UI 快照（字段更全，开销更大）
 
-## 3. UI CLI 常用命令（模拟真实 UI 操作）
+## 5. UI CLI 操作示例（模拟真实 UI 操作）
 
 ```bat
-webauto ui cli --help
+:: 启动并确认 UI
+webauto ui cli start --json
+webauto ui cli status --json
 
-:: 切换到任务页
+:: 切到任务 tab
 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
+:: 触发执行（按你的页面按钮 selector）
+webauto ui cli click --selector "#task-run-btn" --json
+
+:: 等待 runId 出现
+webauto ui cli wait --selector "#run-id-text" --state exists --timeout 20000 --json
 
-:: 读取当前 UI 快照
+:: 取轻量状态 / 完整快照
 webauto ui cli status --json
 webauto ui cli snapshot --json
+```
 
-:: 元素探测
-webauto ui cli probe --selector "#task-likes" --json
+## 6. 账号与任务命令（CLI）
+
+```bat
+:: 账号
+webauto account list
+webauto account login xhs-0001 --url https://www.xiaohongshu.com
+webauto account sync-alias xhs-0001
+
+:: 调度任务
+webauto schedule list
+webauto schedule run <taskId>
 ```
 
-任务状态查看（后端状态）：
+## 7. XHS 运行前初始化
+
+建议先检查/准备依赖：
 
 ```bat
-webauto xhs status --json
-webauto xhs status --run-id <runId> --json
+webauto xhs install --check --json
+webauto xhs install --download-browser --json
+webauto xhs install --download-geoip --json
+webauto xhs install --ensure-backend --json
 ```
 
-## 4. Windows 路径与设置
+## 8. XHS 任务执行与状态
 
-默认数据目录（未设置环境变量时）：
-- 有 `D:` 盘：`D:\webauto`
-- 无 `D:` 盘：`%USERPROFILE%\.webauto`
+完整采集（搜索 + 评论 + 点赞）：
 
-可选环境变量：
-- `WEBAUTO_HOME`：显式指定数据根目录（推荐）
-- `WEBAUTO_ROOT` / `WEBAUTO_PORTABLE_ROOT`：兼容旧变量（会归一化到 `.webauto`）
+```bat
+webauto xhs unified --profile xiaohongshu-batch-1 --keyword "deepseek" --max-notes 200 --do-comments true --persist-comments true --do-likes true --like-keywords "太强了,真不错" --match-mode any --match-min-hits 1 --max-likes 10 --env debug --tab-count 4
+```
 
-PowerShell 设置示例：
+仅查状态：
 
-```powershell
-$env:WEBAUTO_HOME = "D:\webauto"
-webauto ui console
+```bat
+webauto xhs status --json
+webauto xhs status --run-id <runId> --json
 ```
 
-CMD 设置示例：
+## 9. 流控 Gate（按平台隔离）
+
+默认会使用平台 gate 参数控制节奏（含随机区间），你可以在线修改并立即生效。
 
 ```bat
-set WEBAUTO_HOME=D:\webauto
-webauto ui console
+webauto xhs gate get --platform xiaohongshu --json
+webauto xhs gate set --platform xiaohongshu --patch-json "{\"noteInterval\":{\"minMs\":2600,\"maxMs\":5200}}" --json
+webauto xhs gate reset --platform xiaohongshu --json
 ```
 
-不设置也可以直接用，系统会按默认规则落盘。
+## 10. 输出与日志
+
+常见目录（以默认目录为例）：
+- 数据根：`D:\webauto` 或 `%USERPROFILE%\.webauto`
+- 采集输出：`<WEBAUTO_HOME>\download\xiaohongshu\<env>\<keyword>\`
+- 运行日志：`<WEBAUTO_HOME>\logs\`
 
-## 5. 首次安装常见问题
+典型文件：
+- `comments.jsonl`
+- `like-evidence\<noteId>\summary-*.json`
+- `run.log` / `run-events.jsonl`
 
-### 5.1 `Lock file can not be created` / 启动失败
+## 11. 常见问题排查
 
-说明：通常是残留的 Electron/Node 进程占用。
+### 11.1 UI 启动报错 `Lock file can not be created`
+
+通常是残留进程占用：
 
 ```bat
 taskkill /F /IM electron.exe /T
 taskkill /F /IM node.exe /T
-webauto ui console
+webauto ui console --no-daemon
 ```
 
-### 5.2 `ui cli fetch failed`
+### 11.2 `ui cli fetch failed`
 
-先确认 UI 已启动并就绪：
+先确认 UI 已启动，再查状态：
 
 ```bat
 webauto ui cli start --json
 webauto ui cli status --json
 ```
 
-若仍失败，前台启动看日志：
+如果仍失败，前台模式查看实时日志：
 
 ```bat
 webauto ui console --no-daemon
 ```
 
-## 6. 资源检查/安装
+### 11.3 旧账号/Profile 看不到
+
+先确认当前数据根目录是否与历史目录一致。
+- 若历史数据在其它目录，可临时设置 `WEBAUTO_HOME` 指向旧目录再启动。
+- 或把旧目录下的 `profiles/`、`cookies/` 等迁移到当前数据根后再启动。
+
+## 12. 升级与版本确认
 
 ```bat
-webauto xhs install --check --json
-webauto xhs install --download-browser --json
-webauto xhs install --download-geoip --json
+npm install -g @web-auto/webauto@latest
+webauto version
+webauto version --json
 ```
 
-## 7. 开发者（仓库模式）
+## 13. 开发者文档
 
-在仓库中开发请看：
+如果你在仓库模式下开发，请看：
 - `apps/desktop-console/README.md`
-
+- `AGENTS.md`

package/apps/desktop-console/dist/main/index.mjs

@@ -922,6 +922,7 @@ var DEFAULT_PORT = 7716;
 var DEFAULT_SNAPSHOT_TIMEOUT_MS = 35e3;
 var DEFAULT_ACTION_TIMEOUT_MS = 3e4;
 var DEFAULT_WAIT_PROBE_TIMEOUT_MS = 3e3;
+var UI_CLI_ACTION_LOG_FILE = path5.join(resolveWebautoRoot2(), "logs", "ui-cli-actions.jsonl");
 function normalizePathForPlatform(raw, platform = process.platform) {
   const input = String(raw || "").trim();
   const isWinPath = platform === "win32" || /^[A-Za-z]:[\\/]/.test(input);
@@ -997,6 +998,45 @@ function toActionError(input, error, extra = {}) {
   };
   return payload;
 }
+function clipText(value, maxLen = 220) {
+  const text = String(value ?? "");
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, Math.max(0, maxLen - 3))}...`;
+}
+function summarizeAction(input) {
+  const rawClient = input?._client;
+  const client = rawClient && typeof rawClient === "object" ? {
+    client: clipText(rawClient.client ?? "", 80) || null,
+    cmd: clipText(rawClient.cmd ?? "", 80) || null,
+    pid: Number.isFinite(Number(rawClient.pid)) ? Math.floor(Number(rawClient.pid)) : null,
+    ppid: Number.isFinite(Number(rawClient.ppid)) ? Math.floor(Number(rawClient.ppid)) : null
+  } : null;
+  return {
+    action: String(input?.action || "").trim() || null,
+    selector: String(input?.selector || "").trim() || null,
+    tabId: String(input?.tabId || "").trim() || null,
+    tabLabel: String(input?.tabLabel || "").trim() || null,
+    state: String(input?.state || "").trim() || null,
+    key: String(input?.key || "").trim() || null,
+    text: clipText(input?.text ?? "", 160) || null,
+    value: clipText(input?.value ?? "", 160) || null,
+    timeoutMs: readInt(input?.timeoutMs, 0) || null,
+    intervalMs: readInt(input?.intervalMs, 0) || null,
+    nth: Number.isFinite(Number(input?.nth)) ? Math.floor(Number(input?.nth)) : null,
+    exact: input?.exact === true ? true : null,
+    detailed: input?.detailed === true ? true : null,
+    client
+  };
+}
+async function appendActionLog(entry) {
+  const payload = { ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry };
+  try {
+    await fs3.mkdir(path5.dirname(UI_CLI_ACTION_LOG_FILE), { recursive: true });
+    await fs3.appendFile(UI_CLI_ACTION_LOG_FILE, `${JSON.stringify(payload)}
+`, "utf8");
+  } catch {
+  }
+}
 async function withTimeout(promise, timeoutMs, label) {
   const ms = readInt(timeoutMs, 0);
   if (ms <= 0) return promise;
@@ -1382,7 +1422,26 @@ var UiCliBridge = class {
     }
     if (method === "POST" && url.pathname === "/action") {
       const body = await parseBody(req);
+      const actionId = `act-${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
+      const startedAt = Date.now();
+      await appendActionLog({
+        event: "action.request",
+        actionId,
+        method,
+        path: url.pathname,
+        remoteAddress: req.socket?.remoteAddress || null,
+        remotePort: Number.isFinite(Number(req.socket?.remotePort)) ? Number(req.socket?.remotePort) : null,
+        userAgent: clipText(req.headers?.["user-agent"] || "", 160) || null,
+        payload: summarizeAction(body || {})
+      });
       const result = await this.handleAction(body || {});
+      await appendActionLog({
+        event: "action.response",
+        actionId,
+        elapsedMs: Date.now() - startedAt,
+        ok: result?.ok === true,
+        error: result?.ok === true ? null : String(result?.error || "action_failed")
+      });
       return sendJson(res, result.ok ? 200 : 400, result);
     }
     return sendJson(res, 404, { ok: false, error: "not_found" });
@@ -1434,6 +1493,9 @@ var UiCliBridge = class {
   async handleAction(input) {
     const action = String(input?.action || "").trim();
     if (!action) return toActionError(input, "missing_action");
+    if (action === "restart") {
+      return this.handleRestart(input);
+    }
     if (action === "wait") {
       return this.waitForSelector(input);
     }
@@ -1451,6 +1513,22 @@ var UiCliBridge = class {
       return toActionError(input, err?.message || String(err), { details: err?.stack || null });
     }
   }
+  async handleRestart(input) {
+    const onRestart = this.options.onRestart;
+    if (typeof onRestart !== "function") {
+      return toActionError(input, "restart_not_supported");
+    }
+    const reason = String(input?.reason || input?.value || "").trim() || "ui_cli";
+    try {
+      const out = await Promise.resolve(onRestart({ reason, source: "ui_cli_bridge" }));
+      if (out && typeof out === "object") {
+        return { ok: true, restarting: true, reason, ...out };
+      }
+      return { ok: true, restarting: true, reason };
+    } catch (err) {
+      return toActionError(input, err?.message || String(err), { details: err?.stack || null });
+    }
+  }
   async waitForSelector(input) {
     const selector = String(input.selector || "").trim();
     if (!selector) return toActionError(input, "missing_selector");
@@ -1696,6 +1774,25 @@ async function scheduleInvoke(options, input) {
     if (action === "run") {
       const taskId = asText(input?.taskId);
       if (!taskId) return { ok: false, error: "missing taskId" };
+      if (input?.background === true) {
+        const script = path6.join(options.repoRoot, "apps", "webauto", "entry", "schedule.mjs");
+        const ret = await options.spawnCommand({
+          title: `schedule run ${taskId}`,
+          cwd: options.repoRoot,
+          args: [script, "run", taskId, "--json"],
+          groupKey: `schedule-run:${taskId}`
+        });
+        const runId = asText(ret?.runId);
+        return {
+          ok: true,
+          json: {
+            ok: true,
+            background: true,
+            runId: runId || null,
+            runResult: runId ? { runId } : {}
+          }
+        };
+      }
       return runScheduleJson(options, ["run", taskId], timeoutMs);
     }
     if (action === "delete") {
@@ -1770,6 +1867,8 @@ async function runEphemeralTask(options, input) {
           String(asBool(argv["do-comments"], true)),
           "--fetch-body",
           String(asBool(argv["fetch-body"], true)),
+          "--service-reset",
+          String(asBool(argv["service-reset"], false)),
           "--do-likes",
           String(asBool(argv["do-likes"], false)),
           "--like-keywords",
@@ -1815,8 +1914,15 @@ function trackBrowserProcess(pid) {
     spawnedBrowserProcesses.add(pid);
   }
 }
+function safeConsole(method, ...args) {
+  try {
+    const fn = console[method];
+    if (typeof fn === "function") fn(...args);
+  } catch {
+  }
+}
 function cleanupAllBrowserProcesses(reason = "ui_close") {
-  console.log(`[process-cleanup] Cleaning up ${spawnedBrowserProcesses.size} browser process(s) (${reason})`);
+  safeConsole("log", `[process-cleanup] Cleaning up ${spawnedBrowserProcesses.size} browser process(s) (${reason})`);
   for (const pid of spawnedBrowserProcesses) {
     try {
       if (process.platform === "win32") {
@@ -1825,11 +1931,11 @@ function cleanupAllBrowserProcesses(reason = "ui_close") {
         process.kill(pid, "SIGTERM");
       }
     } catch (err) {
-      console.warn(`[process-cleanup] Failed to kill PID ${pid}:`, err);
+      safeConsole("warn", `[process-cleanup] Failed to kill PID ${pid}:`, err);
     }
   }
   spawnedBrowserProcesses.clear();
-  console.log(`[process-cleanup] Cleanup complete`);
+  safeConsole("log", "[process-cleanup] Cleanup complete");
 }
 var __dirname = path7.dirname(fileURLToPath2(import.meta.url));
 var APP_ROOT = path7.resolve(__dirname, "../..");
@@ -1856,6 +1962,12 @@ var DESKTOP_HEARTBEAT_FILE = path7.join(
   "run",
   "desktop-console-heartbeat.json"
 );
+var DESKTOP_LIFECYCLE_LOG_FILE = path7.join(
+  os5.homedir(),
+  ".webauto",
+  "logs",
+  "desktop-lifecycle.jsonl"
+);
 var profileStore = createProfileStore({ repoRoot: REPO_ROOT2 });
 var XHS_SCRIPTS_ROOT = path7.join(REPO_ROOT2, "scripts", "xiaohongshu");
 var XHS_FULL_COLLECT_RE = /collect-content\.mjs$/;
@@ -1897,6 +2009,20 @@ function configureElectronPaths() {
 function now() {
   return Date.now();
 }
+async function appendDesktopLifecycle(event, extra = {}) {
+  const payload = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    event: String(event || "unknown").trim() || "unknown",
+    pid: process.pid,
+    ...extra
+  };
+  try {
+    await fs4.mkdir(path7.dirname(DESKTOP_LIFECYCLE_LOG_FILE), { recursive: true });
+    await fs4.appendFile(DESKTOP_LIFECYCLE_LOG_FILE, `${JSON.stringify(payload)}
+`, "utf8");
+  } catch {
+  }
+}
 var GroupQueue = class {
   running = false;
   queue = [];
@@ -1955,6 +2081,7 @@ var heartbeatTimeoutHandled = false;
 var coreServicesStopRequested = false;
 var coreServiceHeartbeatTimer = null;
 var coreServiceHeartbeatStopped = false;
+var restartRequested = false;
 var RUN_LOG_DIR = path7.join(os5.homedir(), ".webauto", "logs");
 function appendRunLog(runId, line) {
   const rid = String(runId || "").trim();
@@ -2012,16 +2139,55 @@ function ensureStateBridge() {
   }
 }
 var win = null;
-var uiCliBridge = new UiCliBridge({ getWindow: getWin });
+var uiCliBridge = new UiCliBridge({
+  getWindow: getWin,
+  onRestart: ({ reason }) => requestAppRestart(reason)
+});
 configureElectronPaths();
 var singleInstanceLock = app.requestSingleInstanceLock();
 if (!singleInstanceLock) {
+  void appendDesktopLifecycle("single_instance_lock_failed");
   app.quit();
 }
 function getWin() {
   if (!win || win.isDestroyed()) return null;
   return win;
 }
+function requestAppRestart(reason = "ui_cli") {
+  const normalizedReason = String(reason || "").trim() || "ui_cli";
+  if (restartRequested) {
+    return { accepted: false, reason: normalizedReason };
+  }
+  restartRequested = true;
+  void appendDesktopLifecycle("restart_requested", { reason: normalizedReason });
+  console.warn(`[desktop-console] restart requested: ${normalizedReason}`);
+  const w = getWin();
+  if (w) {
+    try {
+      w.webContents.send("app:restart-requested", {
+        reason: normalizedReason,
+        ts: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch {
+    }
+  }
+  setTimeout(() => {
+    void Promise.race([
+      ensureAppExitCleanup(`restart:${normalizedReason}`, { stopStateBridge: true }),
+      sleep2(1500)
+    ]).catch(() => null).finally(() => {
+      try {
+        app.relaunch();
+      } catch (err) {
+        restartRequested = false;
+        console.error("[desktop-console] relaunch failed", err);
+        return;
+      }
+      app.exit(0);
+    });
+  }, 25);
+  return { accepted: true, reason: normalizedReason };
+}
 if (singleInstanceLock) {
   app.on("second-instance", () => {
     const w = getWin();
@@ -2469,7 +2635,8 @@ async function spawnCommand(spec) {
   return { runId };
 }
 async function runJson(spec) {
-  const timeoutMs = typeof spec.timeoutMs === "number" ? spec.timeoutMs : 2e4;
+  const timeoutRaw = Number(spec.timeoutMs);
+  const timeoutMs = Number.isFinite(timeoutRaw) ? Math.floor(timeoutRaw) : 2e4;
   const cwd = resolveCwd(spec.cwd);
   const child = spawn2(resolveNodeBin2(), spec.args, {
     cwd,
@@ -2481,16 +2648,19 @@ async function runJson(spec) {
   const stderr = [];
   child.stdout?.on("data", (c) => stdout.push(c));
   child.stderr?.on("data", (c) => stderr.push(c));
-  const timer = setTimeout(() => {
-    try {
-      child.kill("SIGTERM");
-    } catch {
-    }
-  }, timeoutMs);
+  let timer = null;
+  if (timeoutMs > 0) {
+    timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+      }
+    }, timeoutMs);
+  }
   const { code } = await new Promise((resolve) => {
     child.on("exit", (c) => resolve({ code: c }));
   });
-  clearTimeout(timer);
+  if (timer) clearTimeout(timer);
   const out = Buffer.concat(stdout).toString("utf8").trim();
   const err = Buffer.concat(stderr).toString("utf8").trim();
   if (code !== 0) {
@@ -2756,20 +2926,58 @@ function createWindow() {
     }
   });
   const htmlPath = path7.join(APP_ROOT, "dist", "renderer", "index.html");
+  void appendDesktopLifecycle("window_created", {
+    width: win.getBounds().width,
+    height: win.getBounds().height,
+    title: VERSION_INFO.windowTitle
+  });
+  win.on("close", () => {
+    void appendDesktopLifecycle("window_close");
+  });
+  win.on("closed", () => {
+    void appendDesktopLifecycle("window_closed");
+  });
+  win.on("unresponsive", () => {
+    void appendDesktopLifecycle("window_unresponsive");
+  });
+  win.webContents.on("render-process-gone", (_event, details) => {
+    void appendDesktopLifecycle("render_process_gone", {
+      reason: String(details?.reason || "").trim() || null,
+      exitCode: Number.isFinite(Number(details?.exitCode)) ? Number(details?.exitCode) : null
+    });
+  });
+  win.webContents.on("did-fail-load", (_event, code, desc, validatedURL, isMainFrame) => {
+    void appendDesktopLifecycle("did_fail_load", {
+      code,
+      desc: String(desc || ""),
+      url: String(validatedURL || ""),
+      isMainFrame: Boolean(isMainFrame)
+    });
+  });
   void win.loadFile(htmlPath);
   ensureStateBridge();
 }
 app.on("window-all-closed", () => {
+  void appendDesktopLifecycle("window_all_closed");
   void ensureAppExitCleanup("window_closed");
   app.quit();
 });
 app.on("before-quit", () => {
+  void appendDesktopLifecycle("before_quit");
   void ensureAppExitCleanup("before_quit");
 });
 app.on("will-quit", () => {
+  void appendDesktopLifecycle("will_quit");
   void ensureAppExitCleanup("will_quit", { stopStateBridge: true });
 });
+app.on("quit", (_evt, exitCode) => {
+  void appendDesktopLifecycle("quit", { exitCode });
+});
+process.on("exit", (code) => {
+  void appendDesktopLifecycle("process_exit", { code });
+});
 app.whenReady().then(async () => {
+  void appendDesktopLifecycle("app_ready");
   startCoreServiceHeartbeat();
   const started = await startCoreDaemon().catch((err) => {
     console.error("[desktop-console] core services startup failed", err);
@@ -2786,12 +2994,19 @@ app.whenReady().then(async () => {
   createWindow();
   try {
     await uiCliBridge.start();
+    void appendDesktopLifecycle("ui_cli_bridge_started");
   } catch (err) {
+    void appendDesktopLifecycle("ui_cli_bridge_start_failed", {
+      error: err?.message || String(err)
+    });
     console.error("[desktop-console] ui-cli bridge start failed", err);
     await ensureAppExitCleanup("ui_cli_bridge_start_failed", { stopStateBridge: true }).catch(() => null);
     app.exit(1);
   }
 }).catch(async (err) => {
+  void appendDesktopLifecycle("app_startup_exception", {
+    error: err?.message || String(err)
+  });
   console.error("[desktop-console] fatal startup error", err);
   await ensureAppExitCleanup("startup_exception", { stopStateBridge: true }).catch(() => null);
   app.exit(1);