@web-auto/webauto 0.1.8 → 0.1.11

package/modules/camo-runtime/src/autoscript/runtime.mjs

@@ -340,6 +340,7 @@ export class AutoscriptRunner {
       'sync_window_viewport',
       'verify_subscriptions',
       'xhs_submit_search',
+      'xhs_assert_logged_in',
       'xhs_open_detail',
       'xhs_detail_harvest',
       'xhs_expand_replies',
@@ -359,10 +360,19 @@ export class AutoscriptRunner {
 
   resolveTimeoutMs(operation) {
     const pacing = this.resolvePacing(operation);
-    const disableTimeout = Boolean(
-      operation?.disableTimeout ?? this.script?.defaults?.disableTimeout,
-    );
-    if (disableTimeout) return 0;
+    const operationDisableTimeout = operation?.disableTimeout;
+    if (operationDisableTimeout === true) return 0;
+
+    const rawOperationTimeout = operation?.timeoutMs ?? operation?.pacing?.timeoutMs;
+    const hasOperationTimeout = Number.isFinite(Number(rawOperationTimeout))
+      && Number(rawOperationTimeout) > 0;
+    const defaultDisableTimeout = Boolean(this.script?.defaults?.disableTimeout);
+
+    // Keep default "no-timeout" mode, but allow operation-level timeout to opt in.
+    if (defaultDisableTimeout && operationDisableTimeout !== false && !hasOperationTimeout) {
+      return 0;
+    }
+
     if (pacing.timeoutMs === 0) return 0;
     if (Number.isFinite(pacing.timeoutMs) && pacing.timeoutMs > 0) return pacing.timeoutMs;
     return this.getDefaultTimeoutMs(operation);

package/modules/camo-runtime/src/autoscript/schema.mjs

@@ -126,10 +126,19 @@ function normalizeSubscription(item, index, defaults) {
   const id = toTrimmedString(item.id) || `subscription_${index + 1}`;
   const selector = toTrimmedString(item.selector);
   if (!selector) return null;
+  const pageUrlIncludes = toArray(item.pageUrlIncludes || item.urlIncludes)
+    .map((value) => toTrimmedString(value))
+    .filter(Boolean);
+  const pageUrlExcludes = toArray(item.pageUrlExcludes || item.urlExcludes)
+    .map((value) => toTrimmedString(value))
+    .filter(Boolean);
   const events = toArray(item.events).map((name) => toTrimmedString(name)).filter(Boolean);
   return {
     id,
     selector,
+    visible: item.visible === false ? false : true,
+    pageUrlIncludes,
+    pageUrlExcludes,
     events: events.length > 0 ? events : ['appear', 'exist', 'disappear', 'change'],
     dependsOn: toArray(item.dependsOn).map((x) => toTrimmedString(x)).filter(Boolean),
     retry: normalizeRetry(item.retry, defaults.retry),

package/modules/camo-runtime/src/autoscript/xhs-unified-template.mjs

@@ -575,7 +575,14 @@ export function buildXhsUnifiedAutoscript(rawOptions = {}) {
       { id: 'home_search_input', selector: '#search-input, input.search-input', events: ['appear', 'exist', 'disappear'] },
       { id: 'home_search_button', selector: '.input-button, .input-button .search-icon', events: ['exist'] },
       { id: 'search_result_item', selector: '.note-item', events: ['appear', 'exist', 'change'] },
-      { id: 'detail_modal', selector: '.note-detail-mask, .note-detail-page, .note-detail-dialog, .note-detail-mask .detail-container, .note-detail-mask .media-container, .note-detail-mask .note-scroller, .note-detail-mask .note-content, .note-detail-mask .interaction-container, .note-detail-mask .comments-container', events: ['appear', 'exist', 'disappear'] },
+      {
+        id: 'detail_modal',
+        selector: 'body',
+        visible: false,
+        pageUrlIncludes: ['/explore/'],
+        pageUrlExcludes: ['/search_result'],
+        events: ['appear', 'exist', 'disappear'],
+      },
       { id: 'detail_comment_item', selector: '.comment-item, [class*="comment-item"]', events: ['appear', 'exist', 'change'] },
       { id: 'detail_show_more', selector: '.note-detail-mask .show-more, .note-detail-mask .reply-expand, .note-detail-mask [class*="expand"], .note-detail-page .show-more, .note-detail-page .reply-expand, .note-detail-page [class*="expand"]', events: ['appear', 'exist'] },
       { id: 'detail_discover_button', selector: 'a[href*="/explore?channel_id=homefeed_recommend"]', events: ['appear', 'exist'] },
@@ -884,7 +891,7 @@ export function buildXhsUnifiedAutoscript(rawOptions = {}) {
       },
       {
         id: 'abort_on_login_guard',
-        action: 'raise_error',
+        action: 'xhs_assert_logged_in',
         params: { code: 'LOGIN_GUARD_DETECTED' },
         trigger: 'login_guard.appear',
         once: false,

package/modules/camo-runtime/src/container/runtime-core/checkpoint.mjs

@@ -40,6 +40,105 @@ export const XHS_CHECKPOINTS = {
   ],
 };
 
+function extractEvaluateResult(payload) {
+  if (!payload || typeof payload !== 'object') return {};
+  if (payload.result && typeof payload.result === 'object') return payload.result;
+  if (payload.data && typeof payload.data === 'object') return payload.data;
+  return payload;
+}
+
+async function detectXhsLoginSignal(profileId) {
+  const script = `(() => {
+    const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
+    const selectors = ${JSON.stringify(XHS_CHECKPOINTS.login_guard)};
+    const isVisible = (node) => {
+      if (!(node instanceof HTMLElement)) return false;
+      const style = window.getComputedStyle(node);
+      if (!style) return false;
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity || '1') === 0) return false;
+      const rect = node.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    };
+    const nodes = selectors.flatMap((selector) => Array.from(document.querySelectorAll(selector)));
+    const visibleNodes = nodes.filter((node) => isVisible(node));
+    const guardText = visibleNodes
+      .slice(0, 10)
+      .map((node) => normalize(node.textContent || ''))
+      .filter(Boolean)
+      .join(' ');
+    const hasLoginText = /登录|扫码|验证码|手机号|请先登录|注册|sign\\s*in/i.test(guardText);
+    const loginUrl = /\\/login|signin|passport|account\\/login/i.test(String(location.href || ''));
+
+    let accountId = '';
+    try {
+      const initialState = (typeof window !== 'undefined' && window.__INITIAL_STATE__) || null;
+      const rawUserInfo = initialState && initialState.user && initialState.user.userInfo
+        ? (
+          (initialState.user.userInfo._rawValue && typeof initialState.user.userInfo._rawValue === 'object' && initialState.user.userInfo._rawValue)
+          || (initialState.user.userInfo._value && typeof initialState.user.userInfo._value === 'object' && initialState.user.userInfo._value)
+          || (typeof initialState.user.userInfo === 'object' ? initialState.user.userInfo : null)
+        )
+        : null;
+      accountId = normalize(rawUserInfo?.user_id || rawUserInfo?.userId || '');
+    } catch {}
+
+    if (!accountId) {
+      const selfAnchor = Array.from(document.querySelectorAll('a[href*="/user/profile/"]'))
+        .find((node) => {
+          const text = normalize(node.textContent || '');
+          const title = normalize(node.getAttribute('title') || '');
+          const aria = normalize(node.getAttribute('aria-label') || '');
+          return ['我', '我的', '个人主页', '我的主页'].includes(text)
+            || ['我', '我的', '个人主页', '我的主页'].includes(title)
+            || ['我', '我的', '个人主页', '我的主页'].includes(aria);
+        });
+      if (selfAnchor) {
+        const href = normalize(selfAnchor.getAttribute('href') || '');
+        const matched = href.match(/\\/user\\/profile\\/([^/?#]+)/);
+        if (matched && matched[1]) accountId = normalize(matched[1]);
+      }
+    }
+
+    const hasAccountSignal = Boolean(accountId);
+    const hasLoginGuard = (visibleNodes.length > 0 && hasLoginText) || loginUrl;
+    return {
+      hasLoginGuard,
+      hasLoginText,
+      hasAccountSignal,
+      accountId: accountId || null,
+      visibleGuardCount: visibleNodes.length,
+      guardTextPreview: guardText.slice(0, 240),
+      loginUrl,
+    };
+  })()`;
+
+  try {
+    const ret = await callAPI('evaluate', { profileId, script });
+    const data = extractEvaluateResult(ret);
+    return {
+      hasLoginGuard: data?.hasLoginGuard === true,
+      hasLoginText: data?.hasLoginText === true,
+      hasAccountSignal: data?.hasAccountSignal === true,
+      accountId: String(data?.accountId || '').trim() || null,
+      visibleGuardCount: Math.max(0, Number(data?.visibleGuardCount || 0) || 0),
+      guardTextPreview: String(data?.guardTextPreview || '').trim(),
+      loginUrl: data?.loginUrl === true,
+      ok: true,
+    };
+  } catch {
+    return {
+      hasLoginGuard: false,
+      hasLoginText: false,
+      hasAccountSignal: false,
+      accountId: null,
+      visibleGuardCount: 0,
+      guardTextPreview: '',
+      loginUrl: false,
+      ok: false,
+    };
+  }
+}
+
 export async function detectCheckpoint({ profileId, platform = 'xiaohongshu' }) {
   if (platform !== 'xiaohongshu') {
     return asErrorPayload('UNSUPPORTED_PLATFORM', `Unsupported platform: ${platform}`);
@@ -72,10 +171,16 @@ export async function detectCheckpoint({ profileId, platform = 'xiaohongshu' })
     addCount('login_guard', XHS_CHECKPOINTS.login_guard);
     addCount('risk_control', XHS_CHECKPOINTS.risk_control);
 
+    const loginSignal = await detectXhsLoginSignal(resolvedProfile);
+    const loginGuardBySelector = signals.some((item) => item.startsWith('login_guard:'));
+    const loginGuardConfirmed = loginSignal.ok
+      ? loginSignal.hasLoginGuard
+      : loginGuardBySelector;
+
     let checkpoint = 'unknown';
     if (!url || !url.includes('xiaohongshu.com')) checkpoint = 'offsite';
     else if (isCheckpointRiskUrl(url)) checkpoint = 'risk_control';
-    else if (signals.some((item) => item.startsWith('login_guard:'))) checkpoint = 'login_guard';
+    else if (loginGuardConfirmed) checkpoint = 'login_guard';
     else if (signals.some((item) => item.startsWith('comments_ready:'))) checkpoint = 'comments_ready';
     else if (signals.some((item) => item.startsWith('detail_ready:'))) checkpoint = 'detail_ready';
     else if (signals.some((item) => item.startsWith('search_ready:'))) checkpoint = 'search_ready';
@@ -92,6 +197,7 @@ export async function detectCheckpoint({ profileId, platform = 'xiaohongshu' })
         url,
         signals,
         selectorHits: counter,
+        loginSignal,
       },
     };
   } catch (err) {

package/modules/camo-runtime/src/container/runtime-core/subscription.mjs

@@ -18,8 +18,22 @@ export async function watchSubscriptions({
       const id = String(item.id || `sub_${index + 1}`);
       const selector = String(item.selector || '').trim();
       if (!selector) return null;
+      const visible = item.visible !== false;
+      const pageUrlIncludes = normalizeArray(item.pageUrlIncludes || item.urlIncludes)
+        .map((value) => String(value || '').trim())
+        .filter(Boolean);
+      const pageUrlExcludes = normalizeArray(item.pageUrlExcludes || item.urlExcludes)
+        .map((value) => String(value || '').trim())
+        .filter(Boolean);
       const events = normalizeArray(item.events).map((name) => String(name).trim()).filter(Boolean);
-      return { id, selector, events: events.length > 0 ? new Set(events) : null };
+      return {
+        id,
+        selector,
+        visible,
+        pageUrlIncludes,
+        pageUrlExcludes,
+        events: events.length > 0 ? new Set(events) : null,
+      };
     })
     .filter(Boolean);
 
@@ -40,9 +54,17 @@ export async function watchSubscriptions({
     try {
       const snapshot = await getDomSnapshotByProfile(resolvedProfile);
       const ts = new Date().toISOString();
+      const currentUrl = String(snapshot?.__url || '');
       for (const item of items) {
         const prev = state.get(item.id) || { exists: false, stateSig: '', appearCount: 0 };
-        const elements = notifier.findElements(snapshot, { css: item.selector });
+        const includeOk = item.pageUrlIncludes.length === 0
+          || item.pageUrlIncludes.some((token) => currentUrl.includes(token));
+        const excludeHit = item.pageUrlExcludes.length > 0
+          && item.pageUrlExcludes.some((token) => currentUrl.includes(token));
+        const pageUrlMatched = includeOk && !excludeHit;
+        const elements = pageUrlMatched
+          ? notifier.findElements(snapshot, { css: item.selector, visible: item.visible })
+          : [];
         const exists = elements.length > 0;
         const stateSig = elements.map((node) => node.path).sort().join(',');
         const changed = stateSig !== prev.stateSig;

package/modules/camo-runtime/src/utils/browser-service.mjs

@@ -215,6 +215,7 @@ function buildDomSnapshotScript(maxDepth, maxChildren) {
     const root = collect(document.body || document.documentElement, 0, 'root');
     return {
       dom_tree: root,
+      current_url: String(window.location.href || ''),
       viewport: {
         width: viewportWidth,
         height: viewportHeight,
@@ -238,6 +239,9 @@ export async function getDomSnapshotByProfile(profileId, options = {}) {
       height: Number(payload.viewport.height) || 0,
     };
   }
+  if (tree && payload.current_url) {
+    tree.__url = String(payload.current_url);
+  }
   return tree;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-auto/webauto",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "type": "module",
   "bin": {
     "webauto": "bin/webauto.mjs"
@@ -9,6 +9,7 @@
     "bin/",
     "dist/",
     "modules/",
+    "runtime/",
     "scripts/",
     "services/",
     "apps/desktop-console/dist/",
@@ -59,9 +60,9 @@
     "check:modules": "echo \"Module checks skipped\"",
     "check:ts": "tsc --noEmit -p tsconfig.services.json",
     "test:modules:unit": "npx tsx --test $(find modules -name \"*.test.ts\" -o -name \"*.test.mts\" 2>/dev/null | tr \"\\n\" \" \")",
-    "test:desktop-console:unit": "tsx --test apps/desktop-console/src/main/profile-store.test.mts apps/desktop-console/src/main/index-streaming.test.mts apps/desktop-console/src/main/ui-cli-bridge.test.mts apps/desktop-console/src/main/heartbeat-watchdog.test.mts apps/desktop-console/src/main/core-daemon-manager.test.mts apps/desktop-console/src/main/desktop-settings.test.mts apps/desktop-console/src/main/env-check.test.mts",
+    "test:desktop-console:unit": "tsx --test apps/desktop-console/src/main/profile-store.test.mts apps/desktop-console/src/main/index-streaming.test.mts apps/desktop-console/src/main/ui-cli-bridge.test.mts apps/desktop-console/src/main/task-gateway.test.mts apps/desktop-console/src/main/heartbeat-watchdog.test.mts apps/desktop-console/src/main/core-daemon-manager.test.mts apps/desktop-console/src/main/desktop-settings.test.mts apps/desktop-console/src/main/env-check.test.mts",
     "test:desktop-console:renderer": "npm --prefix apps/desktop-console run test:renderer",
-    "test:desktop-console:coverage": "c8 --reporter=text --reporter=lcov --all --src apps/desktop-console/src/main --extension .mts --extension .mjs --extension .ts --exclude \"**/*.test.*\" --check-coverage --lines 75 --functions 75 --branches 55 --statements 75 --include \"apps/desktop-console/src/main/profile-store.mts\" --include \"apps/desktop-console/src/main/ui-cli-bridge.mts\" --include \"apps/desktop-console/src/main/heartbeat-watchdog.mts\" --include \"apps/desktop-console/src/main/core-daemon-manager.mts\" --include \"apps/desktop-console/src/main/desktop-settings.mts\" --include \"apps/desktop-console/src/main/env-check.mts\" tsx --test apps/desktop-console/src/main/profile-store.test.mts apps/desktop-console/src/main/index-streaming.test.mts apps/desktop-console/src/main/ui-cli-bridge.test.mts apps/desktop-console/src/main/heartbeat-watchdog.test.mts apps/desktop-console/src/main/core-daemon-manager.test.mts apps/desktop-console/src/main/desktop-settings.test.mts apps/desktop-console/src/main/env-check.test.mts",
+    "test:desktop-console:coverage": "c8 --reporter=text --reporter=lcov --all --src apps/desktop-console/src/main --extension .mts --extension .mjs --extension .ts --exclude \"**/*.test.*\" --check-coverage --lines 75 --functions 75 --branches 55 --statements 75 --include \"apps/desktop-console/src/main/profile-store.mts\" --include \"apps/desktop-console/src/main/ui-cli-bridge.mts\" --include \"apps/desktop-console/src/main/task-gateway.mts\" --include \"apps/desktop-console/src/main/heartbeat-watchdog.mts\" --include \"apps/desktop-console/src/main/core-daemon-manager.mts\" --include \"apps/desktop-console/src/main/desktop-settings.mts\" --include \"apps/desktop-console/src/main/env-check.mts\" tsx --test apps/desktop-console/src/main/profile-store.test.mts apps/desktop-console/src/main/index-streaming.test.mts apps/desktop-console/src/main/ui-cli-bridge.test.mts apps/desktop-console/src/main/task-gateway.test.mts apps/desktop-console/src/main/heartbeat-watchdog.test.mts apps/desktop-console/src/main/core-daemon-manager.test.mts apps/desktop-console/src/main/desktop-settings.test.mts apps/desktop-console/src/main/env-check.test.mts",
     "test:webauto:schedule:unit": "node --test tests/unit/webauto/schedule-store.test.mjs tests/unit/webauto/schedule-cli.test.mjs",
     "test:webauto:ui-cli:unit": "node --test tests/unit/webauto/ui-cli-command.test.mjs",
     "test:webauto:install:unit": "node --test tests/unit/webauto/xhs-install.test.mjs",
@@ -69,6 +70,9 @@
     "test:ci": "npm test && npm --prefix apps/desktop-console run test:renderer",
     "coverage:ci": "node scripts/test/run-coverage.mjs",
     "build:release": "node bin/webauto.mjs build:release",
+    "version:bump": "node scripts/bump-version.mjs patch",
+    "version:bump:minor": "node scripts/bump-version.mjs minor",
+    "version:bump:major": "node scripts/bump-version.mjs major",
     "test": "npm run check:modules && npm run check:ts && npm run test:modules:unit && npm run test:webauto:schedule:unit && npm run test:webauto:ui-cli:unit && npm run test:webauto:install:unit && npm run test:desktop-console:unit && npm run test:services:unit",
     "cli:session-manager": "tsx modules/session-manager/src/cli.ts",
     "cli:logging": "tsx modules/logging/src/cli.ts",

package/runtime/infra/utils/README.md

@@ -0,0 +1,13 @@
+# Runtime Utilities
+
+运行时工具统一收敛到 `runtime/infra/utils/scripts/`。
+
+当前保留目录：
+- `scripts/development/`：开发期调试脚本（会话内执行、高亮等）
+- `scripts/service/`：服务启停与端口清理脚本
+- `scripts/` 根脚本：跨场景工具（例如 `test-services.mjs`）
+
+已移除：
+- `local-dev/`
+- `scripts/local-dev/`
+- 其它历史遗留脚本目录

package/runtime/infra/utils/scripts/development/eval-in-session.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Post a local JS file (or inline) to Workflow API /browser/eval for the given session
+import { readFileSync, existsSync } from 'node:fs';
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 2) {
+    console.log('Usage: node scripts/dev/eval-in-session.mjs <sessionId> <file.js|--code="JS..."> [--host=http://127.0.0.1:7701]');
+    process.exit(1);
+  }
+  const sessionId = args[0];
+  let codeArg = args[1];
+  let host = 'http://127.0.0.1:7701';
+  for (const a of args.slice(2)) {
+    if (a.startsWith('--host=')) host = a.slice('--host='.length);
+  }
+  let script = '';
+  if (codeArg.startsWith('--code=')) {
+    script = codeArg.slice('--code='.length);
+  } else {
+    if (!existsSync(codeArg)) {
+      console.error('File not found:', codeArg);
+      process.exit(2);
+    }
+    script = readFileSync(codeArg, 'utf8');
+  }
+  const res = await fetch(host + '/browser/eval', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sessionId, script })
+  }).then(r => r.json()).catch(e => ({ success: false, error: String(e) }));
+  if (!res || !res.success) {
+    console.error('Eval failed:', res?.error || 'unknown');
+    process.exit(1);
+  }
+  console.log('Eval OK:', JSON.stringify(res.value));
+}
+
+main().catch(e => { console.error(e); process.exit(1); });
+

package/runtime/infra/utils/scripts/development/highlight-search-containers.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Highlight search containers for 3 seconds: root -> listContainer -> first item
+const host = process.env.WORKFLOW_HOST || 'http://127.0.0.1:7701';
+
+function arg(k, d){ const a = process.argv.find(x=>x.startsWith(`--${k}=`)); return a ? a.split('=')[1] : d; }
+const sleep = (ms)=>new Promise(r=>setTimeout(r,ms));
+
+async function j(u,opt){ const r = await fetch(host+u, { headers:{'Content-Type':'application/json'}, ...(opt||{}) }); return await r.json(); }
+async function lastSession(){ const s = await j('/v1/sessions'); const arr=s.sessions||[]; return arr[arr.length-1]||null; }
+
+async function highlight({ sessionId, selector, label }){
+  return await j('/v1/containers/highlight', { method:'POST', body: JSON.stringify({ sessionId, containerSelector: selector, label, durationMs: 3000 }) });
+}
+
+async function validate({ sessionId, selector }){ return await j('/v1/containers/validate', { method:'POST', body: JSON.stringify({ sessionId, containerSelector: selector }) }); }
+
+async function main(){
+  const sessionId = arg('sessionId', null) || await lastSession();
+  if (!sessionId) { console.error('No active session.'); process.exit(1); }
+  // container definitions (must match container registry)
+  const rootSel = '.search-ui2024, .search-i18nUi, body';
+  const listSel = '.space-common-offerlist, .offer-list, #offer-list';
+  const itemSel = '.offer-item, .sm-offer, [class*=offer]';
+
+  const out = { sessionId, checks: [] };
+  for (const [label, sel] of [['ROOT', rootSel], ['LIST', listSel], ['ITEM', itemSel]]){
+    const v = await validate({ sessionId, selector: sel });
+    out.checks.push({ label, selector: sel, found: !!v.found });
+    if (v.found) await highlight({ sessionId, selector: sel, label });
+    await sleep(400);
+  }
+  console.log(JSON.stringify({ ok:true, ...out }, null, 2));
+}
+
+main().catch(e=>{ console.error(e); process.exit(1); });

package/runtime/infra/utils/scripts/service/kill-port.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// 杀掉占用指定端口的进程（跨平台尽力）
+import { execSync } from 'node:child_process';
+
+const port = Number(process.argv[2] || 0);
+if (!port) { console.error('Usage: node runtime/infra/utils/scripts/service/kill-port.mjs <port>'); process.exit(1); }
+
+try {
+  if (process.platform === 'win32') {
+    const out = execSync(`netstat -ano | findstr :${port}`, { encoding: 'utf8' });
+    const pids = new Set();
+    out.split(/\r?\n/).forEach(line=>{ const m=line.trim().match(/\s(\d+)\s*$/); if (m) pids.add(Number(m[1])); });
+    for (const pid of pids) { try { execSync(`taskkill /F /PID ${pid}`); console.log(`killed pid ${pid}`); } catch {} }
+    if (pids.size===0) console.log('no process found');
+  } else {
+    const out = execSync(`lsof -ti :${port}`, { encoding: 'utf8' });
+    const pids = out.split(/\s+/).map(s=>Number(s.trim())).filter(Boolean);
+    for (const pid of pids) { try { process.kill(pid, 'SIGKILL'); console.log(`killed pid ${pid}`); } catch {} }
+    if (pids.length===0) console.log('no process found');
+  }
+} catch (e) {
+  console.log('nothing to kill or command failed');
+}
+

package/runtime/infra/utils/scripts/service/start-api.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+
+const API_PID_FILE = process.env.WEBAUTO_API_PID_FILE
+  ? path.resolve(process.env.WEBAUTO_API_PID_FILE)
+  : path.join(os.tmpdir(), 'webauto-api.pid');
+const DIST_SERVER = path.resolve(process.cwd(), 'dist', 'apps', 'webauto', 'server.js');
+
+function resolveOnPath(candidates) {
+  const pathEnv = process.env.PATH || process.env.Path || '';
+  const dirs = String(pathEnv).split(path.delimiter).map((x) => x.trim()).filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const full = path.join(dir, name);
+      if (existsSync(full)) return full;
+    }
+  }
+  return null;
+}
+
+function resolveNodeBin() {
+  const explicit = String(process.env.WEBAUTO_NODE_BIN || '').trim();
+  if (explicit) return explicit;
+  const npmNode = String(process.env.npm_node_execpath || '').trim();
+  if (npmNode) return npmNode;
+  const fromPath = resolveOnPath(process.platform === 'win32' ? ['node.exe', 'node.cmd', 'node'] : ['node']);
+  if (fromPath) return fromPath;
+  return process.execPath;
+}
+
+function resolveNpmBin() {
+  if (process.platform !== 'win32') return 'npm';
+  const fromPath = resolveOnPath(['npm.cmd', 'npm.exe', 'npm.bat', 'npm.ps1']);
+  return fromPath || 'npm.cmd';
+}
+
+function quoteCmdArg(value) {
+  if (!value) return '""';
+  if (!/[\s"]/u.test(value)) return value;
+  return `"${String(value).replace(/"/g, '""')}"`;
+}
+
+function run(command, args) {
+  const lower = String(command || '').toLowerCase();
+  if (process.platform === 'win32' && (lower.endsWith('.cmd') || lower.endsWith('.bat'))) {
+    const cmdLine = [quoteCmdArg(command), ...args.map(quoteCmdArg)].join(' ');
+    return spawnSync('cmd.exe', ['/d', '/s', '/c', cmdLine], { stdio: 'inherit', windowsHide: true });
+  }
+  if (process.platform === 'win32' && lower.endsWith('.ps1')) {
+    return spawnSync(
+      'powershell.exe',
+      ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', command, ...args],
+      { stdio: 'inherit', windowsHide: true },
+    );
+  }
+  return spawnSync(command, args, { stdio: 'inherit', windowsHide: true });
+}
+
+async function health(url='http://127.0.0.1:7701/health'){
+  try{
+    const res = await fetch(url);
+    if (!res.ok) return false;
+    const j = await res.json().catch(() => ({}));
+    return Boolean(j?.ok ?? true);
+  }catch{
+    return false;
+  }
+}
+
+async function main(){
+  if (!existsSync(DIST_SERVER)) {
+    const npmBin = resolveNpmBin();
+    const buildRet = run(npmBin, ['run', '-s', 'build:services']);
+    if (buildRet.status !== 0) {
+      console.error('build:services failed');
+      process.exit(1);
+    }
+  }
+  // start
+  const child = spawn(resolveNodeBin(), [DIST_SERVER], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    env: {
+      ...process.env,
+      WEBAUTO_RUNTIME_MODE: 'unified',
+    },
+  });
+  child.unref();
+  try {
+    mkdirSync(path.dirname(API_PID_FILE), { recursive: true });
+  } catch {}
+  writeFileSync(API_PID_FILE, String(child.pid));
+  // wait for health
+  for(let i=0;i<20;i++){ if (await health()) { console.log('API started. PID', child.pid); return; } await wait(500); }
+  console.error('API did not become healthy in time'); process.exit(1);
+}
+
+main().catch(e=>{ console.error(e); process.exit(1); });