@mobileaidev/ai-app-bridge 0.2.12 → 0.2.14

package/README.md

@@ -1,5 +1,23 @@
 # AI App Bridge CLI
 
+AI App Bridge CLI/MCP supports Android native apps, Android WebView/H5/CDP,
+Flutter apps on Android and iOS, iOS native apps via `AiAppBridgeIOS` plus
+WebDriverAgent/XCUITest, WKWebView, and desktop Web Bridge sessions.
+
+Command domains:
+
+- `core`: `status`, `tree`, `uia-tree`, `screenshot`, `logs`, `network`, `state`, `events`
+- `app`: `install-apk`, `clear-app-data`, `launch-*`, `freeze-app`, `thaw-app`, `permission-*`, `appops-set`
+- `action`: `tap`, `tap-text`, `tap-uia-text`, `input-text`, `swipe`, `keyevent`, `wait-text`, `keyboard-state`, `hide-keyboard`
+- `flutter`: `flutter-tree`, `flutter-nodes`, `flutter-action`, `tap-flutter-text`, `input-flutter-text`, `scroll-flutter`
+- `webview`: `h5-*`, `flutter-h5-*`, `webview-pages`, `webview-network`, `webview-console`
+- `ios`: `ios-devices`, `ios-doctor`, `ios-setup`, `ios-*` runtime evidence, WDA tree/tap/input/swipe, WKWebView, and Flutter iOS
+- `web`: `web-session-start`, `web-sessions`, `web-status`, `web-dom`, `web-logs`, `web-network`, `web-state`, `web-events`, `web-command`, `web-click`, `web-input`, `web-wait`, `web-scroll`
+- `diagnostics` / `advanced`: `logcat`, `smoke`, `batch`, `forward`, `remove-forward`
+
+For MCP clients, the default surface is compact: call `capabilities` to discover
+domains, commands, and options, then call `run` with the selected command.
+
 ```bash
 npm install -g @mobileaidev/ai-app-bridge
 
@@ -19,9 +37,10 @@ ai-app-bridge ios-setup --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
 ai-app-bridge ios-tap --bundle-id <ios.bundle.id> --tap-x 120 --tap-y 360 --wda-url <wda-url-from-setup>
 ai-app-bridge ios-input --bundle-id <ios.bundle.id> --accessibility-id sample_text_field --clear-first --text "hello" --wda-url <wda-url-from-setup>
+ai-app-bridge-mcp # then run web-session-start / web-* commands through MCP
 ai-app-bridge thaw-app --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge freeze-app --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge-mcp
+ai-app-bridge-mcp --help
 ```
 
 AI agents, model clients, automation frameworks, and IDE MCP clients reading
@@ -37,12 +56,13 @@ refresh the session.
 MCP defaults to a compact tool surface to avoid loading every command schema
 into the model context:
 
-- `capabilities` lists the bridge domains and command names.
+- `capabilities` lists supported targets, command domains, command names, and optional argument names.
 - `run` executes a selected command with command-specific arguments.
 
-This keeps install, data reset, launch, UI, Flutter, WebView, logcat, network,
-permission, iOS, and web capabilities discoverable without exposing dozens of full schemas
-at session start. Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
+This keeps install, data reset, launch, UI action, Flutter, WebView/H5/CDP,
+iOS, Web Bridge, logcat, network, permission, smoke, batch, and port-forward
+capabilities discoverable without exposing dozens of full schemas at session start.
+Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
 `ai-app-bridge-mcp` only when a client needs the legacy one-tool-per-command
 surface.
 
@@ -101,11 +121,14 @@ on many Android 16 devices; ASCII text can still fall back to ADB when an older
 bridge runtime is running.
 
 When `screenshot` or `smoke` runs without `--out-file`, the CLI writes a unique
-PNG under `build/ai_app_bridge_artifacts` instead of reusing a stable filename
-or creating files in the project root.
-It keeps the newest 20 generated screenshots for each command prefix. Use
-`--artifact-dir` to choose that directory, or `--out-file` when a fixed path is
-intentional.
+PNG under a git-ignored project artifact directory. Gradle, Android, and Flutter
+projects normally use `build/ai_app_bridge_artifacts`; Node projects can use
+`node_modules/.cache/ai_app_bridge_artifacts`; Swift projects can use
+`.build/ai_app_bridge_artifacts`. If the current git worktree has no ignored
+artifact candidate, generated defaults go under `.git/ai_app_bridge_artifacts`
+so they cannot dirty the repository root. It keeps the newest 20 generated
+screenshots for each command prefix. Use `--artifact-dir` to choose an ignored
+directory, or `--out-file` when a fixed path is intentional.
 
 `launch-app` queries Android LAUNCHER activities before starting the app. If a
 debug dependency exposes multiple launcher entries, it returns

package/bin/ai-app-bridge.js

@@ -7,6 +7,13 @@ const net = require('net');
 const os = require('os');
 const path = require('path');
 const { IOSBridgeProvider } = require('./ios-provider');
+const {
+  artifactTimestamp,
+  defaultArtifactDirectory,
+  defaultArtifactPath,
+  sanitizeArtifactExtension,
+  sanitizeArtifactName,
+} = require('./artifact-paths');
 
 const generatedArtifactRetention = 20;
 
@@ -22,6 +29,15 @@ const defaults = {
 
 const helpText = `Usage: ai-app-bridge <command> [options]
 
+Supports:
+  Android native apps; Android WebView/H5/CDP; Flutter apps on Android and iOS;
+  iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest; WKWebView;
+  desktop Web Bridge sessions through ai-app-bridge-mcp.
+
+MCP discovery:
+  ai-app-bridge-mcp exposes a compact capability index by default.
+  Call capabilities, then run a command from core/app/action/flutter/webview/ios/web/diagnostics/advanced.
+
 Commands:
   status                 Read bridge status and app/device metadata.
   tree                   Read the Android View tree from the in-app bridge.
@@ -84,6 +100,23 @@ Flutter commands:
   flutter-h5-wait        Wait for Flutter H5 text or selector.
   flutter-h5-scroll      Scroll Flutter H5 content.
 
+Web Bridge MCP commands:
+  web-provider-status    Read desktop Web Bridge provider status.
+  web-session-start      Start the Web Bridge WebSocket session server.
+  web-connect-info       Read endpoint/token for browser SDK clients.
+  web-sessions           List connected Web Bridge SDK sessions.
+  web-status             Read Web Bridge session status.
+  web-dom                Read or refresh Web Bridge DOM snapshots.
+  web-logs               Read Web Bridge log records.
+  web-network            Read Web Bridge network records.
+  web-state              Read Web Bridge state records.
+  web-events             Read Web Bridge event records.
+  web-command            Run a whitelisted browser SDK command.
+  web-click              Click a DOM element through the browser SDK.
+  web-input              Set text in a DOM input through the browser SDK.
+  web-wait               Wait for text or selector through the browser SDK.
+  web-scroll             Scroll a Web Bridge DOM target.
+
 Device/action commands:
   tap                    Tap device coordinates through ADB.
   tap-text               Tap a visible node by exact text or content description.
@@ -2366,17 +2399,6 @@ function screenshotOutputPath(options = {}, prefix = 'ai_app_bridge_screenshot')
   return defaultArtifactPath(prefix, 'png', { artifactDir: options.artifactDir });
 }
 
-function defaultArtifactPath(prefix, extension, options = {}) {
-  const directory = path.resolve(options.artifactDir || defaultArtifactDirectory());
-  const suffix = [
-    artifactTimestamp(options.now || new Date()),
-    String(options.pid || process.pid),
-    options.randomSuffix || Math.random().toString(36).slice(2, 8),
-  ].join('-');
-  const name = `${sanitizeArtifactName(prefix)}-${suffix}.${sanitizeArtifactExtension(extension)}`;
-  return path.join(directory, name);
-}
-
 async function pruneGeneratedArtifacts(options = {}) {
   const keep = generatedArtifactRetention;
   const result = {
@@ -2449,34 +2471,6 @@ async function pruneGeneratedArtifacts(options = {}) {
   return result;
 }
 
-function artifactTimestamp(date) {
-  const value = date instanceof Date ? date : new Date(date);
-  const pad = (number, size = 2) => String(number).padStart(size, '0');
-  return [
-    value.getUTCFullYear(),
-    pad(value.getUTCMonth() + 1),
-    pad(value.getUTCDate()),
-    '-',
-    pad(value.getUTCHours()),
-    pad(value.getUTCMinutes()),
-    pad(value.getUTCSeconds()),
-    '-',
-    pad(value.getUTCMilliseconds(), 3),
-  ].join('');
-}
-
-function sanitizeArtifactName(value) {
-  return String(value || 'artifact').replace(/[^a-zA-Z0-9_.-]+/g, '_').replace(/^_+|_+$/g, '') || 'artifact';
-}
-
-function sanitizeArtifactExtension(value) {
-  return sanitizeArtifactName(String(value || 'bin').replace(/^\.+/, '')) || 'bin';
-}
-
-function defaultArtifactDirectory() {
-  return path.join(process.cwd(), 'build', 'ai_app_bridge_artifacts');
-}
-
 function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -4555,4 +4549,3 @@ module.exports = {
   waitTextConditionsMet,
   withFileLock,
 };
-

package/bin/artifact-paths.js

@@ -0,0 +1,129 @@
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const artifactDirectoryName = 'ai_app_bridge_artifacts';
+
+function defaultArtifactDirectory(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const gitRoot = gitOutput(cwd, ['rev-parse', '--show-toplevel']);
+  if (!gitRoot) {
+    return path.join(cwd, 'build', artifactDirectoryName);
+  }
+
+  for (const directory of artifactDirectoryCandidates(gitRoot)) {
+    if (isGitIgnored(gitRoot, directory)) {
+      return directory;
+    }
+  }
+
+  const gitDirectory = gitOutput(cwd, ['rev-parse', '--absolute-git-dir']);
+  return path.join(gitDirectory || path.join(gitRoot, '.git'), artifactDirectoryName);
+}
+
+function defaultArtifactPath(prefix, extension, options = {}) {
+  const directory = path.resolve(options.artifactDir || defaultArtifactDirectory({ cwd: options.cwd }));
+  const suffix = [
+    artifactTimestamp(options.now || new Date()),
+    String(options.pid || process.pid),
+    options.randomSuffix || Math.random().toString(36).slice(2, 8),
+  ].join('-');
+  const name = `${sanitizeArtifactName(prefix)}-${suffix}.${sanitizeArtifactExtension(extension)}`;
+  return path.join(directory, name);
+}
+
+function artifactDirectoryCandidates(gitRoot) {
+  const root = path.resolve(gitRoot);
+  const candidates = [];
+
+  if (hasAny(root, ['settings.gradle', 'settings.gradle.kts', 'build.gradle', 'build.gradle.kts', 'gradlew', 'pubspec.yaml'])) {
+    candidates.push(path.join(root, 'build', artifactDirectoryName));
+  }
+  if (hasAny(root, ['Package.swift'])) {
+    candidates.push(path.join(root, '.build', artifactDirectoryName));
+  }
+  if (hasAny(root, ['pubspec.yaml'])) {
+    candidates.push(path.join(root, '.dart_tool', artifactDirectoryName));
+  }
+  if (hasAny(root, ['package.json'])) {
+    candidates.push(path.join(root, 'node_modules', '.cache', artifactDirectoryName));
+  }
+  if (hasAny(root, ['Cargo.toml'])) {
+    candidates.push(path.join(root, 'target', artifactDirectoryName));
+  }
+
+  candidates.push(
+    path.join(root, 'build', artifactDirectoryName),
+    path.join(root, '.build', artifactDirectoryName),
+    path.join(root, '.dart_tool', artifactDirectoryName),
+    path.join(root, 'node_modules', '.cache', artifactDirectoryName),
+    path.join(root, 'target', artifactDirectoryName),
+  );
+
+  return [...new Set(candidates)];
+}
+
+function hasAny(root, fileNames) {
+  return fileNames.some((fileName) => fs.existsSync(path.join(root, fileName)));
+}
+
+function isGitIgnored(gitRoot, directory) {
+  const relative = path.relative(gitRoot, directory);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return false;
+  }
+  try {
+    execFileSync('git', ['-C', gitRoot, 'check-ignore', '-q', '--', relative], {
+      stdio: 'ignore',
+      timeout: 2000,
+    });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function gitOutput(cwd, args) {
+  try {
+    return execFileSync('git', ['-C', cwd, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    }).trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+function artifactTimestamp(date) {
+  const value = date instanceof Date ? date : new Date(date);
+  const pad = (number, size = 2) => String(number).padStart(size, '0');
+  return [
+    value.getUTCFullYear(),
+    pad(value.getUTCMonth() + 1),
+    pad(value.getUTCDate()),
+    '-',
+    pad(value.getUTCHours()),
+    pad(value.getUTCMinutes()),
+    pad(value.getUTCSeconds()),
+    '-',
+    pad(value.getUTCMilliseconds(), 3),
+  ].join('');
+}
+
+function sanitizeArtifactName(value) {
+  return String(value || 'artifact').replace(/[^a-zA-Z0-9_.-]+/g, '_').replace(/^_+|_+$/g, '') || 'artifact';
+}
+
+function sanitizeArtifactExtension(value) {
+  return sanitizeArtifactName(String(value || 'bin').replace(/^\.+/, '')) || 'bin';
+}
+
+module.exports = {
+  artifactDirectoryCandidates,
+  artifactTimestamp,
+  defaultArtifactDirectory,
+  defaultArtifactPath,
+  sanitizeArtifactExtension,
+  sanitizeArtifactName,
+};

package/bin/ios-provider.js

@@ -4,6 +4,7 @@ const http = require('http');
 const os = require('os');
 const path = require('path');
 const { URL } = require('url');
+const { defaultArtifactPath } = require('./artifact-paths');
 
 const defaultRuntimePort = 18080;
 const runtimePortSearchCount = 50;
@@ -304,7 +305,7 @@ class IOSBridgeProvider {
     const device = await this.requireDevice(args);
     const outFile = args.outFile
       ? path.resolve(args.outFile)
-      : defaultArtifactPath('ios-screenshot', 'png', args.artifactDir);
+      : defaultArtifactPath('ios-screenshot', 'png', { artifactDir: args.artifactDir });
     await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
     const command = [
       'device',
@@ -1164,15 +1165,6 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function defaultArtifactPath(prefix, extension, artifactDir) {
-  const dir = artifactDir ? path.resolve(artifactDir) : path.join(process.cwd(), 'build', 'ai_app_bridge_artifacts');
-  return path.join(dir, `${prefix}-${artifactTimestamp()}.${extension}`);
-}
-
-function artifactTimestamp(date = new Date()) {
-  return date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
-}
-
 module.exports = {
   IOSBridgeProvider,
   formatHostForUrl,

package/bin/mcp-server.js

@@ -6,18 +6,69 @@ const path = require('path');
 const packageInfo = require('../package.json');
 const { IOSBridgeProvider } = require('./ios-provider');
 const { WebBridgeProvider } = require('./web-provider');
+const { defaultArtifactDirectory } = require('./artifact-paths');
 const bridgeDir = __dirname;
 const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
 const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
 const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
+const supportedTargets = [
+  'Android native apps',
+  'Android WebView/H5/CDP',
+  'Flutter apps on Android and iOS',
+  'iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest',
+  'WKWebView',
+  'desktop Web Bridge sessions',
+];
+const commandDomains = {
+  core: 'status, tree, uia-tree, screenshot, logs, network, state, events',
+  app: 'install-apk, clear-app-data, launch-*, freeze-app/thaw-app, permission-*, appops-set',
+  action: 'tap, tap-text, tap-uia-text, input-text, swipe, keyevent, wait-text, keyboard-state, hide-keyboard',
+  flutter: 'flutter-tree, flutter-nodes, flutter-action, tap/input/scroll Flutter controls',
+  webview: 'h5-*, flutter-h5-*, webview-pages, webview-network, webview-console',
+  ios: 'ios-devices, ios-doctor, ios-setup, ios runtime evidence, ios-uia-tree/tap/input/swipe, ios-h5-*, ios-flutter-*',
+  web: 'web-session-start, web-sessions, web-status, web-dom, web-logs, web-network, web-state, web-events, web-command, web-click, web-input, web-wait, web-scroll',
+  diagnostics: 'logcat, smoke',
+  advanced: 'batch, forward, remove-forward',
+};
+const supportedTargetsText = `AI App Bridge supports ${supportedTargets.join('; ')}.`;
+const commandDomainsText = `Command domains: ${Object.entries(commandDomains).map(([domain, summary]) => `${domain}(${summary})`).join('; ')}.`;
+const discoveryText = 'Default MCP surface is compact: call capabilities to discover domains, commands, and options, then call run with the selected command and arguments.';
 const serverInstructions = [
-  'AI App Bridge observes and controls Android, iOS, Flutter, and Web targets for agent workflows. Prefer these tools over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, and permissions.',
-  'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
+  supportedTargetsText,
+  commandDomainsText,
+  discoveryText,
+  'Prefer AI App Bridge over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, permissions, or app-level Web evidence.',
   'Always pass packageName for Android app-specific commands, or pass an explicit port. For iOS, pass bundleId plus deviceId when more than one iPhone is connected.',
+  'For Web Bridge sessions, start the provider, connect the browser SDK, then pass sessionId and targetId when needed.',
   'Use freeze-app/thaw-app only as an optional stabilization control for dynamic or transient screens: thaw before reads/actions/captures, freeze after evidence capture only when it helps reasoning, and thaw before the next operation or before finishing so the app is not left frozen.',
 ].join(' ');
+const mcpHelpText = `Usage: ai-app-bridge-mcp [--help]
+
+${supportedTargetsText}
+
+${commandDomainsText}
+
+MCP surface:
+  compact (default)  exposes only capabilities and run.
+  full/legacy        exposes one tool per command; set AI_APP_BRIDGE_MCP_SURFACE=full.
+
+Discovery:
+  1. Call capabilities with optional domain or command filters.
+  2. Call run with a command name from capabilities.
+  3. Put command-specific options in arguments.
+
+Target ids:
+  Android app commands require packageName or explicit port.
+  iOS app commands use bundleId; add deviceId when multiple devices exist and wdaUrl for WDA actions.
+  Web Bridge commands use sessionId; add targetId for multi-target pages.
+
+Examples:
+  capabilities { "domain": "webview", "includeOptions": true }
+  run { "command": "screenshot", "packageName": "com.example.app" }
+  run { "command": "web-session-start", "arguments": { "webPort": 18180 } }
+`;
 const iosProvider = new IOSBridgeProvider();
 const webProvider = new WebBridgeProvider();
 
@@ -185,18 +236,20 @@ function toolDefinitions() {
 
 function compactToolDefinitions() {
   return [
-    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning app automation; then use run to execute the selected command.', {
-      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, ios, web, or diagnostics.' },
-      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, or ios-tap.' },
+    bridgeTool('capabilities', `List AI App Bridge capability domains and commands across Android, iOS, Flutter, WebView/H5/CDP, and Web Bridge targets. ${commandDomainsText}`, {
+      domain: { type: 'string', description: 'Optional domain filter: core, app, action, flutter, webview, ios, web, diagnostics, or advanced.' },
+      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, ios-tap, web-session-start, or web-command.' },
       includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
     }),
-    bridgeTool('run', 'Run an AI App Bridge command. Use capabilities first to choose the command. Pass packageName for Android app commands and bundleId for iOS app commands.', {
-      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, or web-status.' },
+    bridgeTool('run', 'Run an AI App Bridge command from capabilities. Pass packageName/port for Android app commands, bundleId/deviceId for iOS app commands, and sessionId/targetId for Web Bridge commands.', {
+      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, web-session-start, web-status, or web-command.' },
       packageName: { type: 'string', description: 'Target Android package for app-specific commands. Strongly recommended.' },
       serial: { type: 'string', description: 'ADB serial when multiple devices are connected.' },
       port: { type: 'number', description: 'Explicit bridge port when packageName discovery is not available.' },
       bundleId: { type: 'string', description: 'Target iOS app bundle identifier for ios-* commands.' },
       deviceId: { type: 'string', description: 'iOS devicectl identifier, UDID, serial number, or device name.' },
+      sessionId: { type: 'string', description: 'Target Web Bridge SDK session id for web-* commands.' },
+      targetId: { type: 'string', description: 'Optional Web Bridge target id for multi-target pages.' },
       iosHost: { type: 'string', description: 'iOS runtime host or CoreDevice tunnel IP.' },
       iosPort: { type: 'number', description: 'iOS runtime port when auto-discovery is unavailable.' },
       runtimeUrl: { type: 'string', description: 'Explicit iOS runtime base URL.' },
@@ -635,7 +688,9 @@ function capabilityPayload(args = {}) {
   return {
     ok: true,
     surface: mcpSurface === 'full' || mcpSurface === 'legacy' ? 'full' : 'compact',
-    usage: 'Use run with one of these command names. Prefer packageName for app-specific commands; install-apk, clear-app-data, launch-app, freeze/thaw, UI, WebView, logcat, network, and permission workflows are supported.',
+    supportedTargets,
+    commandDomains,
+    usage: `${supportedTargetsText} ${discoveryText} Use run with one of these command names. Prefer packageName for Android app commands, bundleId/deviceId for iOS, and sessionId/targetId for Web Bridge sessions.`,
     domains,
   };
 }
@@ -1092,7 +1147,7 @@ async function runSmoke(args) {
 function defaultArtifactDirFor(command, args) {
   if (args.outFile) return '';
   if (command !== 'screenshot' && command !== 'smoke') return '';
-  return path.join(process.cwd(), 'build', 'ai_app_bridge_artifacts');
+  return defaultArtifactDirectory();
 }
 
 function addCommonArgs(cliArgs, args) {
@@ -1225,12 +1280,20 @@ function writeLog(text) {
 }
 
 if (require.main === module) {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    process.stdout.write(`${mcpHelpText}\n`);
+    process.exit(0);
+  }
   startServer();
 }
 
 module.exports = {
   buildBridgeCliArgs,
+  commandDomains,
+  defaultArtifactDirFor,
+  mcpHelpText,
   readNextMessage,
   runBatch,
   startServer,
+  supportedTargets,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.12",
-  "description": "Desktop CLI and MCP server for AI App Bridge.",
+  "version": "0.2.14",
+  "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mobileAiDev/ai-app-bridge.git",
@@ -17,6 +17,7 @@
   },
   "files": [
     "bin/ai-app-bridge.js",
+    "bin/artifact-paths.js",
     "bin/mcp-server.js",
     "bin/ios-provider.js",
     "bin/web-provider.js",

package/skills/ai-app-bridge-use/SKILL.md

@@ -1,10 +1,28 @@
 ---
 name: ai-app-bridge-use
-description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android、iOS、Flutter 或 Web 应用。Codex 需要检查移动端 UI、Web DOM、截图、Android View/UIAutomator tree、iOS UIKit/WDA tree、点击/输入/等待/滑动、安装/启动/清数据、Flutter widget 与 action、WebView/WKWebView/H5 DOM 或 CDP 网络/控制台、Web Bridge session/DOM/command、日志/网络/状态/事件、权限/appops、smoke 测试，或按需使用 freeze/thaw 稳定动态画面时触发。
+description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android native、Android WebView/H5/CDP、Flutter、iOS native + WDA/XCUITest、WKWebView 和桌面 Web Bridge。能力域包括 core/status/tree/screenshot/logs/network/state/events，app/install/clear-data/launch/freeze/thaw/permissions/appops，action/tap/input/swipe/keyevent/wait/keyboard，flutter/widget/action，webview/H5/CDP，ios/devices/setup/runtime/WDA/H5/flutter，web/session/DOM/logs/network/events/command，diagnostics/logcat/smoke，advanced/batch/port-forward。
 ---
 
 # AI App Bridge Use
 
+## 能力总览
+
+AI App Bridge 支持 Android native apps、Android WebView/H5/CDP、Flutter apps、iOS native apps via `AiAppBridgeIOS` + WebDriverAgent/XCUITest、WKWebView，以及桌面 Web Bridge sessions。
+
+默认 MCP surface 只有 `capabilities` 和 `run`；先用 `capabilities` 查 domain、command 和 options，再用 `run` 执行。
+
+目标标识：Android 用 `packageName` 或显式 `port`；iOS 用 `bundleId`，多设备加 `deviceId`，full-control 加 `wdaUrl`；Web 用 `sessionId`，多 target 加 `targetId`。
+
+命令域：
+- `core`: `status`/`tree`/`uia-tree`/`screenshot`/`logs`/`network`/`state`/`events`
+- `app`: `install-apk`/`clear-app-data`/`launch-*`/`freeze-app`/`thaw-app`/`permission-*`/`appops-set`
+- `action`: `tap`/`tap-text`/`tap-uia-text`/`input-text`/`swipe`/`keyevent`/`wait-text`/`keyboard-*`
+- `flutter`: `flutter-tree`/`flutter-nodes`/`flutter-action`/`tap-flutter-text`/`input-flutter-text`/`scroll-flutter`
+- `webview`: `h5-*`/`flutter-h5-*`/`webview-pages`/`webview-network`/`webview-console`
+- `ios`: `ios-devices`/`ios-doctor`/`ios-setup`/`ios-status`/`ios-tree`/`ios-uia-tree`/`ios-tap`/`ios-input`/`ios-swipe`/`ios-h5-*`/`ios-flutter-*`
+- `web`: `web-session-start`/`web-sessions`/`web-status`/`web-dom`/`web-logs`/`web-network`/`web-state`/`web-events`/`web-command`/`web-click`/`web-input`/`web-wait`/`web-scroll`
+- `diagnostics`/`advanced`: `logcat`/`smoke`/`batch`/`forward`/`remove-forward`
+
 ## Agent 快速流程
 
 1. 确认目标：Android 使用 `packageName`，iOS 使用 `bundleId`，真机多设备场景传 `deviceId`/UDID；Web 使用 `sessionId`，多 target 时加 `targetId`。没有目标 id 时先从上下文、构建配置或前台 app/session 线索推断。面向具体 app/session 的命令必须传目标 id，只有无法发现 bridge 端口时才传 `port`、`runtimeUrl` 或先启动 Web session。
@@ -12,7 +30,8 @@ description: 使用 AI App Bridge MCP 观察、操作、验证和调试 Android
 3. 选择命令路径：按任务类型选 `core`、`app`、`action`、`flutter`、`webview`、`ios`、`web`、`diagnostics` 或 `advanced` 域；不要先退回原始 `adb`、浏览器脚本或坐标猜测。
 4. 用 `batch` 串联相关步骤：观察、操作、等待、截图、tree 验证尽量放进一次 MCP 调用。
 5. 验证可见结果：界面变化必须用 `screenshot` 加 `tree`/`uia-tree` 交叉确认。
-6. 只在需要稳定动态画面时使用 `freeze-app`/`thaw-app`；如果本轮冻结过 app，最终回复前必须解冻。
+6. 生成截图等默认产物时，让 AI Bridge 自动选择会被当前项目 git 忽略的目录；只有确实需要固定路径时才传 `outFile`/`artifactDir`，且路径必须在 `build`、`.build`、`.dart_tool`、`node_modules/.cache`、`target` 或其他已忽略目录内。
+7. 只在需要稳定动态画面时使用 `freeze-app`/`thaw-app`；如果本轮冻结过 app，最终回复前必须解冻。
 
 ## 能力发现和调用
 

package/skills/ai-app-bridge-use/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "AI App Bridge Use"
-  short_description: "观察、操作并验证 Android/iOS/Flutter/Web app。"
-  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证目标 Android/iOS/Flutter/Web app；先发现能力，Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"
+  short_description: "Android/iOS/Flutter/Web 全域观察、操作、验证能力索引。"
+  default_prompt: "使用 $ai-app-bridge-use 观察、操作和验证 Android native、Android WebView/H5/CDP、Flutter、iOS native/WKWebView/WDA/XCUITest 或桌面 Web Bridge；先用 capabilities 查 core/app/action/flutter/webview/ios/web/diagnostics/advanced，再用 run 执行。Android 传 packageName，iOS 传 bundleId/deviceId 并在 full-control 时使用 WDA，Web 先建立 sessionId，只有移动端动态画面需要稳定证据时才使用 freeze/thaw。"