@mobileaidev/ai-app-bridge 0.2.0 → 0.2.1

package/README.md

@@ -4,9 +4,11 @@
 npm install -g @mobileaidev/ai-app-bridge
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge install-apk --package-name io.github.mobileaidev.aiappbridge.sample --apk-path app-debug.apk
-ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge install-apk --package-name io.github.mobileaidev.aiappbridge.sample --apk-path app-debug.apk
+ai-app-bridge launch-app --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge launch-activity --package-name io.github.mobileaidev.aiappbridge.sample --activity .MainActivity --extra route=/home
+ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge input-text --package-name io.github.mobileaidev.aiappbridge.sample --text "中文输入" --hide-keyboard
 ai-app-bridge network --package-name io.github.mobileaidev.aiappbridge.sample --compact --url-filter /api/
 ai-app-bridge webview-network --package-name io.github.mobileaidev.aiappbridge.sample --duration-ms 3000
@@ -25,5 +27,11 @@ 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.
+`--artifact-dir` to choose that 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
+`launcher_ambiguous` with the candidates instead of guessing. Use
+`launch-activity` or `launch-app --activity/--component` to choose the intended
+entry point explicitly.

package/bin/ai-app-bridge.js

@@ -68,10 +68,12 @@ Device/action commands:
   keyboard-state         Read Android soft keyboard visibility from dumpsys.
   hide-keyboard          Hide the Android soft keyboard when it is visible.
 
-App/permission commands:
-  install-apk            Install an APK and assist device-side installer screens.
-  launch-native-test     Launch the debug native Android bridge test Activity.
-  launch-flutter         Launch the Flutter Activity.
+App/permission commands:
+  install-apk            Install an APK and assist device-side installer screens.
+  launch-app             Launch the target package LAUNCHER Activity.
+  launch-activity        Launch an explicit Android Activity component.
+  launch-native-test     Launch the debug native Android bridge test Activity.
+  launch-flutter         Launch the Flutter Activity.
   permission-state       Read Android runtime permission state.
   permission-grant       Grant an Android runtime permission.
   permission-revoke      Revoke an Android runtime permission.
@@ -92,7 +94,13 @@ Options:
   --adb-timeout-ms <ms>  Timeout for ADB subprocesses.
   --out-file <path>      Screenshot output path.
   --artifact-dir <path>  Directory for generated screenshot/artifact defaults.
-  --apk-path <path>      APK path used by install-apk.
+  --apk-path <path>      APK path used by install-apk.
+  --activity <name>      Activity class for launch-activity or launch-app override.
+  --component <pkg/act>  Explicit Android component for launch-activity.
+  --action <name>        Intent action for launch-activity.
+  --category <name>      Intent category for launch-activity; may be repeated.
+  --data <uri>           Intent data URI for launch-activity.
+  --extra <key=value>    String intent extra for launch-activity; may be repeated.
   --text <text>          Text used by Unicode-safe bridge input commands.
   --value <text>         Text value used by h5-input or flutter-h5-input.
   --selector <css>       CSS selector used by H5 commands.
@@ -319,11 +327,15 @@ async function runCommand(command, options, ctx) {
       return appopsSet(ctx, requiredString(options.op, 'op'), requiredString(options.mode, 'mode'));
     case 'tap-uia-text':
       return tapUiaText(ctx, requiredString(options.targetText, 'targetText'), options);
-    case 'permission-dialog':
-      return permissionDialog(ctx, options);
-    case 'launch-native-test':
-      return launchNativeTest(ctx);
-    case 'launch-flutter':
+    case 'permission-dialog':
+      return permissionDialog(ctx, options);
+    case 'launch-app':
+      return launchApp(ctx, options);
+    case 'launch-activity':
+      return launchActivity(ctx, options);
+    case 'launch-native-test':
+      return launchNativeTest(ctx);
+    case 'launch-flutter':
       return launchFlutter(ctx, options.initialRoute || '');
     case 'smoke':
       return smoke(ctx, options);
@@ -347,16 +359,25 @@ function parseArgs(argv) {
     const rawName = arg.slice(2);
     const name = rawName.replace(/-([a-z])/g, (_, value) => value.toUpperCase());
     const next = argv[index + 1];
-    if (next === undefined || next.startsWith('--')) {
-      options[name] = true;
-      continue;
-    }
-    options[name] = next;
-    index += 1;
-  }
-  return { command, options };
-}
-
+    if (next === undefined || next.startsWith('--')) {
+      appendOption(options, name, true);
+      continue;
+    }
+    appendOption(options, name, next);
+    index += 1;
+  }
+  return { command, options };
+}
+
+function appendOption(options, name, value) {
+  if (name === 'extra' || name === 'category') {
+    if (!Array.isArray(options[name])) options[name] = [];
+    options[name].push(value);
+    return;
+  }
+  options[name] = value;
+}
+
 async function adb(ctx, args, { binary = false } = {}) {
   const allArgs = adbArgs(ctx, args);
   return new Promise((resolve, reject) => {
@@ -3664,13 +3685,17 @@ async function resolveLogcatPid(ctx, options) {
   return '';
 }
 
-function filterLogcat(text, options) {
-  const tags = splitCsv(options.tag || options.tags);
-  const grep = options.grep ? String(options.grep) : '';
-  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
-  const minLevel = priorityValue(options.level || options.minLevel || '');
-  const pid = options.pid ? String(options.pid) : '';
-  const lines = String(text || '').split(/\r?\n/);
+function filterLogcat(text, options) {
+  const tags = splitCsv(options.tag || options.tags);
+  const grep = options.grep ? String(options.grep) : '';
+  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
+  const minLevel = priorityValue(options.level || options.minLevel || '');
+  const pid = options.pid ? String(options.pid) : '';
+  const requiresAppPid = options.appPid || options.packagePid || options.pid === 'current';
+  if (requiresAppPid && !pid) {
+    return '';
+  }
+  const lines = String(text || '').split(/\r?\n/);
   const filtered = [];
   let previousIncluded = false;
   for (const line of lines) {
@@ -3753,19 +3778,134 @@ function adbFollow(ctx, args, durationMs) {
   });
 }
 
-async function launchNativeTest(ctx) {
-  const component = `${ctx.packageName}/${ctx.nativeActivity}`;
-  await adb(ctx, ['shell', 'am', 'start', '-n', component]);
-  return { ok: true, transport: 'adb', component };
-}
-
-async function launchFlutter(ctx, initialRoute) {
-  const component = `${ctx.packageName}/${ctx.flutterActivity}`;
-  const args = ['shell', 'am', 'start', '-n', component];
-  if (initialRoute) args.push('-e', 'ai_app_initial_route', initialRoute);
-  await adb(ctx, args);
-  return { ok: true, transport: 'adb', component, initialRoute };
-}
+async function launchApp(ctx, options = {}) {
+  if (options.component || options.activity) {
+    return launchActivity(ctx, options);
+  }
+
+  const candidates = await launcherActivityCandidates(ctx);
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      error: 'launcher_not_found',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      ok: false,
+      error: 'launcher_ambiguous',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+      suggestion: 'Pass --component or --activity to choose the intended launcher Activity.',
+    };
+  }
+
+  return startActivity(ctx, candidates[0], options, {
+    packageName: ctx.packageName,
+    launcherCandidates: candidates,
+  });
+}
+
+async function launchActivity(ctx, options = {}) {
+  const component = normalizeActivityComponent(
+    ctx.packageName,
+    options.component || requiredString(options.activity, 'activity'),
+  );
+  return startActivity(ctx, component, options, { packageName: ctx.packageName });
+}
+
+async function launchNativeTest(ctx) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.nativeActivity);
+  return startActivity(ctx, component, {}, { packageName: ctx.packageName });
+}
+
+async function launchFlutter(ctx, initialRoute) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.flutterActivity);
+  const options = initialRoute ? { extra: [`ai_app_initial_route=${initialRoute}`] } : {};
+  const result = await startActivity(ctx, component, options, { packageName: ctx.packageName });
+  return { ...result, initialRoute };
+}
+
+async function launcherActivityCandidates(ctx) {
+  const result = await adb(ctx, [
+    'shell',
+    'cmd',
+    'package',
+    'query-activities',
+    '--brief',
+    '-a',
+    'android.intent.action.MAIN',
+    '-c',
+    'android.intent.category.LAUNCHER',
+    ctx.packageName,
+  ]);
+  return parseLauncherActivityCandidates(result.stdout);
+}
+
+function parseLauncherActivityCandidates(stdout) {
+  const candidates = [];
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const candidate = line.trim();
+    if (/^[A-Za-z0-9_.$]+\/[A-Za-z0-9_.$]+$/.test(candidate) && !candidates.includes(candidate)) {
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function normalizeActivityComponent(packageName, activityOrComponent) {
+  const value = requiredString(activityOrComponent, 'activity');
+  if (value.includes('/')) return value;
+  return `${packageName}/${value}`;
+}
+
+async function startActivity(ctx, component, options = {}, extraResult = {}) {
+  const args = buildAmStartArgs(component, options);
+  const result = await adb(ctx, args);
+  return {
+    ok: true,
+    transport: 'adb',
+    component,
+    ...extraResult,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  };
+}
+
+function buildAmStartArgs(component, options = {}) {
+  const args = ['shell', 'am', 'start'];
+  if (options.action) args.push('-a', options.action);
+  for (const category of optionList(options.category)) {
+    args.push('-c', category);
+  }
+  if (options.data) args.push('-d', options.data);
+  for (const extra of parseStartExtras(options.extra)) {
+    args.push('-e', extra.key, extra.value);
+  }
+  args.push('-n', component);
+  return args;
+}
+
+function parseStartExtras(rawExtras) {
+  return optionList(rawExtras).map((rawExtra) => {
+    const value = String(rawExtra);
+    const separator = value.indexOf('=');
+    if (separator <= 0) {
+      throw new Error('extra must use key=value');
+    }
+    return {
+      key: value.slice(0, separator),
+      value: value.slice(separator + 1),
+    };
+  });
+}
+
+function optionList(value) {
+  if (value === undefined || value === null || value === false || value === '') return [];
+  return Array.isArray(value) ? value : [value];
+}
 
 async function smoke(ctx, options) {
   const summary = {
@@ -4131,9 +4271,10 @@ module.exports = {
   compactUiaTree,
   defaultArtifactDirectory,
   defaultArtifactPath,
-  findFlutterNode,
-  findTappableNodeByText,
-  firstErrorLine,
+  findFlutterNode,
+  findTappableNodeByText,
+  filterLogcat,
+  firstErrorLine,
   flutterNodePoint,
   flutterPhysicalViewport,
   helpText,
@@ -4141,10 +4282,14 @@ module.exports = {
   isAdbInputTextSafe,
   isLikelyInstallerSurface,
   nodeTapState,
-  normalizeBridgeError,
-  parseWebViewDevToolsSockets,
-  parseKeyboardState,
-  parseUiaBounds,
+  normalizeBridgeError,
+  normalizeActivityComponent,
+  parseWebViewDevToolsSockets,
+  parseArgs,
+  parseKeyboardState,
+  parseLauncherActivityCandidates,
+  parseStartExtras,
+  parseUiaBounds,
   parseUiaViewport,
   parseComponentFromWindowLine,
   parseForegroundWindow,

package/bin/mcp-server.js

@@ -219,8 +219,10 @@ function toolDefinitions() {
       installerTimeoutMs: { type: 'number', description: 'Maximum time to keep assisting installer screens after adb install exits. Defaults to 90000 ms.' },
       intervalMs: { type: 'number', description: 'Installer polling interval. Defaults to 700 ms.' },
     }, ['apkPath']),
-    bridgeTool('launch_native_test', 'Launch the debug native Android bridge test Activity.'),
-    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
+    bridgeTool('launch_app', 'Launch the target package LAUNCHER Activity. If multiple launcher Activities exist, returns launcher_ambiguous with candidates unless activity or component is explicit.', launchProperties()),
+    bridgeTool('launch_activity', 'Launch an explicit Android Activity component, optionally with action/data/category/string extras.', launchProperties()),
+    bridgeTool('launch_native_test', 'Launch the debug native Android bridge test Activity.'),
+    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
     bridgeTool('tap', 'Tap device coordinates through ADB.', {
       tapX: { type: 'number' },
       tapY: { type: 'number' },
@@ -233,12 +235,12 @@ function toolDefinitions() {
       targetText: { type: 'string' },
       timeoutSec: { type: 'number' },
     }, ['targetText']),
-    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; do not use raw adb shell input text for non-ASCII text.', {
+    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; always pass packageName so the tool targets the intended app.', {
       text: { type: 'string', description: 'Text to set in the focused or coordinate-matched native EditText.' },
       tapX: { type: 'number', description: 'Optional X coordinate used to choose a native EditText target.' },
       tapY: { type: 'number', description: 'Optional Y coordinate used to choose a native EditText target.' },
       hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
-    }, ['text']),
+    }, ['text', 'packageName']),
     bridgeTool('keyboard_state', 'Read Android soft-keyboard visibility from dumpsys input_method.'),
     bridgeTool('hide_keyboard', 'Hide the Android soft keyboard when it is visible.', {
       force: { type: 'boolean', description: 'Send keyboard-dismiss keys even when the visibility probe says the keyboard is hidden.' },
@@ -287,14 +289,38 @@ function toolDefinitions() {
   ];
 }
 
-function bridgeTool(name, description, properties = {}, required = []) {
-  return {
-    name,
-    description,
-    inputSchema: baseSchema(properties, required),
-  };
-}
-
+function bridgeTool(name, description, properties = {}, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: baseSchema(properties, required),
+  };
+}
+
+function launchProperties() {
+  return {
+    activity: { type: 'string', description: 'Activity class, such as .MainActivity or com.example.MainActivity.' },
+    component: { type: 'string', description: 'Explicit Android component, such as com.example/.MainActivity.' },
+    action: { type: 'string', description: 'Intent action for explicit Activity launch.' },
+    category: {
+      oneOf: [
+        { type: 'string' },
+        { type: 'array', items: { type: 'string' } },
+      ],
+      description: 'Intent category or categories.',
+    },
+    data: { type: 'string', description: 'Intent data URI.' },
+    extra: {
+      oneOf: [
+        { type: 'string' },
+        { type: 'array', items: { type: 'string' } },
+        { type: 'object', additionalProperties: { type: 'string' } },
+      ],
+      description: 'String extras. Use key=value strings or an object of string values.',
+    },
+  };
+}
+
 function baseSchema(extraProperties = {}, extraRequired = []) {
   return {
     type: 'object',
@@ -324,11 +350,14 @@ function h5TargetSchema() {
   };
 }
 
-async function callTool(name, args) {
-  if (name === 'run_smoke') {
-    return runSmoke(args);
-  }
-  const commandMap = {
+async function callTool(name, args) {
+  if (name === 'run_smoke') {
+    return runSmoke(args);
+  }
+  if (name === 'input_text' && !args.packageName) {
+    return toolText('packageName is required for input_text so text input is routed to the intended app bridge.', true);
+  }
+  const commandMap = {
     flutter_tree: 'flutter-tree',
     h5_dom: 'h5-dom',
     h5_eval: 'h5-eval',
@@ -346,9 +375,11 @@ async function callTool(name, args) {
     tap_flutter_text: 'tap-flutter-text',
     input_flutter_text: 'input-flutter-text',
     uia_tree: 'uia-tree',
-    install_apk: 'install-apk',
-    launch_native_test: 'launch-native-test',
-    launch_flutter: 'launch-flutter',
+    install_apk: 'install-apk',
+    launch_app: 'launch-app',
+    launch_activity: 'launch-activity',
+    launch_native_test: 'launch-native-test',
+    launch_flutter: 'launch-flutter',
     tap_text: 'tap-text',
     wait_text: 'wait-text',
     input_text: 'input-text',
@@ -371,8 +402,14 @@ async function callTool(name, args) {
 async function runBridge(command, args) {
   const cliArgs = [cliScript, command];
   addCommonArgs(cliArgs, args);
-  addArg(cliArgs, 'initial-route', args.initialRoute);
-  addArg(cliArgs, 'out-file', args.outFile);
+  addArg(cliArgs, 'initial-route', args.initialRoute);
+  addArg(cliArgs, 'activity', args.activity);
+  addArg(cliArgs, 'component', args.component);
+  addArg(cliArgs, 'action', args.action);
+  addRepeatedArg(cliArgs, 'category', args.category);
+  addArg(cliArgs, 'data', args.data);
+  addExtraArgs(cliArgs, args.extra);
+  addArg(cliArgs, 'out-file', args.outFile);
   addArg(cliArgs, 'artifact-dir', args.artifactDir || defaultArtifactDirFor(command, args));
   addArg(cliArgs, 'apk-path', args.apkPath);
   addArg(cliArgs, 'tap-x', args.tapX);
@@ -459,13 +496,35 @@ function addCommonArgs(cliArgs, args) {
   addArg(cliArgs, 'package-name', args.packageName);
 }
 
-function addArg(cliArgs, name, value) {
-  if (value === undefined || value === null || value === '' || value === false) {
-    return;
-  }
-  cliArgs.push(`--${name}`, String(value));
-}
-
+function addArg(cliArgs, name, value) {
+  if (value === undefined || value === null || value === '' || value === false) {
+    return;
+  }
+  cliArgs.push(`--${name}`, String(value));
+}
+
+function addRepeatedArg(cliArgs, name, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, name, item);
+    return;
+  }
+  addArg(cliArgs, name, value);
+}
+
+function addExtraArgs(cliArgs, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, 'extra', item);
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, extraValue] of Object.entries(value)) {
+      addArg(cliArgs, 'extra', `${key}=${extraValue}`);
+    }
+    return;
+  }
+  addArg(cliArgs, 'extra', value);
+}
+
 function runProcess(cliArgs) {
   return new Promise((resolve) => {
     const child = spawn(nodeBinary, cliArgs, {
@@ -490,12 +549,23 @@ function runProcess(cliArgs) {
         code === 0 ? '' : `exitCode: ${code}`,
         retryWithPackageNameHint(cliArgs, stdout, stderr, code),
       ].filter(Boolean).join('\n\n');
-      resolve(toolText(text || 'ok', code !== 0));
-    });
-  });
-}
-
-function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
+      resolve(toolText(text || emptyProcessText(cliArgs), code !== 0));
+    });
+  });
+}
+
+function emptyProcessText(cliArgs) {
+  const command = cliArgs[1] || '';
+  if (command === 'logcat' && cliArgs.includes('--app-pid')) {
+    return 'logcat: no matching lines for current app pid';
+  }
+  if (command === 'logcat') {
+    return 'logcat: no matching lines';
+  }
+  return 'ok';
+}
+
+function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
   if (code === 0 || cliArgs.includes('--package-name') || cliArgs.includes('--port')) {
     return '';
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Desktop CLI and MCP server for AI App Bridge.",
   "repository": {
     "type": "git",