@zhz8888/dsh-android-emulator-helper 1.0.0 → 1.1.0

package/lib/providers/avd.js

@@ -1,5 +1,6 @@
 import { spawn as spawnChild } from 'node:child_process'
 import { open, readFile } from 'node:fs/promises'
+import os from 'node:os'
 import path from 'node:path'
 import { brief, ok, run, splitArgumentLines } from '../util/run.js'
 import { systemImagePackage } from '../settings.js'
@@ -62,7 +63,8 @@ export function parseAvds(value) {
  * @throws When nothing is ready and `autoStartEmulator` is off.
  */
 export async function ensureDevice(rt, input = {}) {
-  const timeoutMs = input.timeoutMs ?? rt.settings.bootTimeoutMs
+  // The page edits seconds; every spawn below wants milliseconds.
+  const timeoutMs = input.timeoutMs ?? rt.settings.bootTimeoutSeconds * 1000
   if (input.serial) return waitForReadyTarget(rt, await pickDevice(rt, { serial: input.serial }), timeoutMs)
   const ready = await pickDevice(rt).catch(() => undefined)
   if (ready) return ready.kind === 'emulator' ? waitForReadyTarget(rt, ready, timeoutMs) : ready
@@ -88,7 +90,7 @@ export async function ensureDevice(rt, input = {}) {
  * @throws When the AVD is already running, or the boot times out.
  */
 export async function startEmulator(rt, input = {}) {
-  const timeoutMs = input.timeoutMs ?? rt.settings.bootTimeoutMs
+  const timeoutMs = input.timeoutMs ?? rt.settings.bootTimeoutSeconds * 1000
   if (input.serial) {
     throw new Error(
       'android_start_emulator always starts a new emulator. Reuse an existing target by passing serial to build, install, launch, screenshot, log, or UI tools.',
@@ -180,6 +182,11 @@ export async function createAvd(rt, input = {}) {
 /**
  * Choose the AVD to start: the requested one, the configured default, else the first.
  *
+ * Only the *fallback* (nothing asked for, or the configured default is gone) may
+ * pick an AVD the caller did not name. An explicitly requested AVD that does not
+ * exist must fail: silently starting a different emulator turns a typo into a
+ * wrong device, and the caller never learns which AVD it is actually talking to.
+ *
  * @param {object} rt - the call runtime.
  * @param {string} [name] - the requested AVD name.
  * @returns {Promise<{name: string}>} the chosen AVD.
@@ -187,9 +194,22 @@ export async function createAvd(rt, input = {}) {
 async function pickAvd(rt, name) {
   if (name && !AVD.test(name)) throw new Error(`Invalid Android AVD name: ${name}`)
   const avds = await listAvds(rt)
-  const want = name || rt.settings.defaultAvd
+  if (name) {
+    // Exact match first: `includes` alone would let "Pixel" select "Pixel_10"
+    // even when an AVD literally called "Pixel" exists.
+    const hit =
+      avds.find((item) => item.name === name) ??
+      avds.find((item) => item.name.toLowerCase().includes(name.toLowerCase()))
+    if (hit) return hit
+    throw new Error(
+      `Android AVD "${name}" not found. Available AVDs: ${avds.map((item) => item.name).join(', ') || 'none'}.`,
+    )
+  }
+  const want = rt.settings.defaultAvd
   if (want) {
-    const hit = avds.find((item) => item.name === want || item.name.toLowerCase().includes(want.toLowerCase()))
+    const hit =
+      avds.find((item) => item.name === want) ??
+      avds.find((item) => item.name.toLowerCase().includes(want.toLowerCase()))
     if (hit) return hit
   }
   const first = avds[0]
@@ -233,10 +253,39 @@ async function waitForStartedDevice(rt, before, avdName, timeoutMs, watch) {
   const detail = last.length ? last.map((item) => `${item.serial}:${item.state}`).join(', ') : 'no adb devices'
   throw new Error(
     `Timed out waiting for Android Emulator to boot (${detail}).\n` +
+      blockerHint(last) +
       `Log: ${watch.logPath}\n${await logTail(watch.logFile)}`,
   )
 }
 
+/**
+ * Explain the device states that stop a boot poll from ever succeeding.
+ *
+ * `startedEmulatorCandidates` only accepts a serial in `device` state, so an
+ * emulator sitting in `unauthorized` (an adb key handshake that never
+ * completed) or `offline` is invisible to the loop above: it polls until the
+ * timeout and reports only the boot timeout. Naming the real blocker turns an
+ * opaque timeout into something a caller can act on.
+ *
+ * @param {Array<{serial: string, state: string}>} devices - the devices seen on the last poll.
+ * @returns {string} a hint line, or an empty string when nothing was blocked.
+ */
+export function blockerHint(devices) {
+  const blocked = devices.filter((item) => item.state !== 'device')
+  if (blocked.length === 0) return ''
+  const unauthorized = blocked.filter((item) => item.state === 'unauthorized')
+  const lines = [`Blocking devices: ${blocked.map((item) => `${item.serial}:${item.state}`).join(', ')}.\n`]
+  if (unauthorized.length > 0) {
+    lines.push(
+      `An unauthorized emulator never accepts adb commands. Accept the RSA prompt on screen, ` +
+        `or wipe and restart the AVD with \`emulator -avd <name> -no-snapshot-load\`; ` +
+        `ADB_VENDOR_KEYS=${path.join(os.homedir(), '.android', 'adbkey')} must be readable by the adb server.\n`,
+    )
+  }
+  lines.push('')
+  return lines.join('')
+}
+
 /** Human-readable description of how a child process ended. */
 function exitDescription(child) {
   if (child.signalCode !== null && child.signalCode !== undefined) return `signal ${child.signalCode}`

package/lib/providers/build.js

@@ -38,7 +38,7 @@ export async function buildApp(rt, input = {}) {
   const gradle = await gradleCommand(rt, root)
   const out = await run([...gradle, task, ...splitArgumentLines(rt.settings.gradleExtraArgs)], {
     cwd: root,
-    timeout: input.timeoutMs ?? rt.settings.buildTimeoutMs,
+    timeout: input.timeoutMs ?? rt.settings.buildTimeoutSeconds * 1000,
     env: await androidEnv(rt),
   })
   const logPath = await record(rt, 'build', out)

package/lib/providers/preflight.js

@@ -17,7 +17,7 @@ import { androidEnv, checkTool, findTool, javaHome, listJavaHomes, sdkRoot, sdkR
  * @module @zhz8888/dsh-android-emulator-helper/providers/preflight
  */
 
-/** Name of the ADB device check, exempted from the overall verdict. */
+/** Name of the ADB device check, exempted from the overall verdict when a device can still be started. */
 const ADB_DEVICES_CHECK = 'ADB devices'
 
 /**
@@ -28,16 +28,38 @@ const ADB_DEVICES_CHECK = 'ADB devices'
  */
 const READY_TARGET_OPTIONAL_CHECKS = new Set(['emulator', 'avdmanager', 'Android Virtual Devices', 'Emulator acceleration'])
 
+/**
+ * Whether a missing ready device is still recoverable.
+ *
+ * `ensureDevice` starts an emulator when it finds no ready target, so "no
+ * devices" is not itself a failure — but only while that recovery is actually
+ * available. With `autoStartEmulator` off, or with no emulator binary or no
+ * AVD to start, every device-targeted tool refuses, and a verdict of "ready"
+ * would be a lie the caller only discovers on its first real call.
+ *
+ * @param {Array<{name: string, ok: boolean}>} checks - the preflight checks.
+ * @param {{autoStartEmulator?: boolean}} input - the live setting backing the recovery.
+ * @returns {boolean} true when the plugin can still produce a target on its own.
+ */
+function canStartTarget(checks, input) {
+  if (input.autoStartEmulator === false) return false
+  const failed = new Set(checks.filter((item) => !item.ok).map((item) => item.name))
+  return !failed.has('emulator') && !failed.has('Android Virtual Devices')
+}
+
 /**
  * Reduce the checks to one verdict.
  *
  * @param {Array<{name: string, ok: boolean}>} checks - the preflight checks.
- * @param {{hasReadyTarget: boolean}} input - whether any device is ready.
+ * @param {{hasReadyTarget: boolean, autoStartEmulator?: boolean}} input - whether any device is ready, and whether one could still be started.
  * @returns {boolean} true when the environment can run the workflow.
  */
 export function preflightOk(checks, input) {
+  const deviceOptional = input.hasReadyTarget || canStartTarget(checks, input)
   return checks.every(
-    (item) => item.ok || item.name === ADB_DEVICES_CHECK || (input.hasReadyTarget && READY_TARGET_OPTIONAL_CHECKS.has(item.name)),
+    (item) =>
+      item.ok ||
+      (deviceOptional && (item.name === ADB_DEVICES_CHECK || READY_TARGET_OPTIONAL_CHECKS.has(item.name))),
   )
 }
 
@@ -147,7 +169,12 @@ export async function preflight(rt) {
     fix: 'Start an Android Emulator or connect a device with USB debugging enabled.',
   })
 
-  return { ok: preflightOk(checks, { hasReadyTarget }), backend: 'sdk', settings: rt.settings, checks }
+  return {
+    ok: preflightOk(checks, { hasReadyTarget, autoStartEmulator: rt.settings.autoStartEmulator !== false }),
+    backend: 'sdk',
+    settings: rt.settings,
+    checks,
+  }
 }
 
 /**

package/lib/providers/project-template.js

@@ -11,6 +11,38 @@
  */
 
 import path from "node:path";
+
+/**
+ * Lowest bytecode target the template will emit.
+ *
+ * Java 17 is the floor because AGP 8 requires a JDK 17 toolchain and the pinned
+ * Kotlin release targets 17 by default.
+ */
+export const MIN_JVM_TARGET = 17;
+
+/**
+ * Highest bytecode target the template will emit.
+ *
+ * Deliberately below the newest JDK: `JavaVersion.VERSION_24` does not exist in
+ * AGP 8.7, and the Kotlin release pinned here does not know `JvmTarget.JVM_24`
+ * either, so a generated project naming them fails at configuration time. The
+ * cap keeps a modern-only host building instead of emitting a file that cannot
+ * be evaluated.
+ */
+export const MAX_JVM_TARGET = 21;
+
+/**
+ * Clamp a JDK major version to a bytecode target both plugins can name.
+ *
+ * @param {number|string|undefined} major - the JDK major the project will build with.
+ * @returns {number} a target between {@link MIN_JVM_TARGET} and {@link MAX_JVM_TARGET}.
+ */
+export function jvmTargetFor(major) {
+    const parsed = Number.parseInt(String(major ?? ""), 10);
+    if (!Number.isInteger(parsed)) return MIN_JVM_TARGET;
+    return Math.min(MAX_JVM_TARGET, Math.max(MIN_JVM_TARGET, parsed));
+}
+
 export function templateFiles(root, pkg, sdk) {
     const pkgDir = pkg.replaceAll(".", "/");
     return [
@@ -110,6 +142,27 @@ android {
         versionCode = 1
         versionName = "1.0"
     }
+
+    // Both halves of a Compose build must agree on the bytecode target. Without
+    // these, AGP falls back to its own default (Java 8) while the Kotlin plugin
+    // derives its target from whichever JDK runs Gradle, and any JDK newer than
+    // the AGP release makes the two disagree:
+    //
+    //   'compileDebugJavaWithJavac' and 'compileDebugKotlin' have different JVM
+    //   target compatibility: 1.8 and 22
+    //
+    // Pinning both to the same version is what makes a freshly generated project
+    // build on a machine whose only JDK is newer than the template's.
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_${input.jvmTarget}
+        targetCompatibility = JavaVersion.VERSION_${input.jvmTarget}
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_${input.jvmTarget})
+    }
 }
 
 dependencies {

package/lib/providers/project.js

@@ -1,7 +1,7 @@
 import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { inside } from '../util/path.js'
-import { templateFiles } from './project-template.js'
+import { templateFiles, jvmTargetFor } from './project-template.js'
 import { sdkRoot } from './sdk.js'
 
 /**
@@ -97,6 +97,14 @@ export async function create(rt, input) {
   const pkg = packageName(input.packageName || `com.example.${slug(name)}`)
   const minSdk = sdkLevel(input.minSdk ?? rt.settings.minSdk, 'minSdk')
   const compileSdk = sdkLevel(input.compileSdk ?? Number(rt.settings.apiLevel), 'compileSdk')
+  // The generated project pins ONE bytecode target for both its Java and its
+  // Kotlin compilation. Left unpinned, AGP uses its own default while the Kotlin
+  // plugin follows whichever JDK runs Gradle, and on a host whose JDK is newer
+  // than the pinned AGP release a freshly generated app fails to compile with
+  // "different JVM target compatibility". Deriving the target from the
+  // configured JDK major keeps the user's intent, and `jvmTargetFor` clamps it
+  // to a version both plugins can actually name.
+  const jvmTarget = jvmTargetFor(rt.settings.jdkMajor)
   const files = templateFiles(root, pkg, await sdkRoot(rt))
 
   if (!input.overwrite) {
@@ -110,7 +118,7 @@ export async function create(rt, input) {
 
   for (const file of files) {
     await mkdir(path.dirname(file.path), { recursive: true })
-    await writeFile(file.path, file.body({ name, pkg, minSdk, compileSdk }), 'utf8')
+    await writeFile(file.path, file.body({ name, pkg, minSdk, compileSdk, jvmTarget }), 'utf8')
   }
 
   return {

package/lib/providers/ui.js

@@ -47,17 +47,45 @@ export async function status(rt) {
 /**
  * Dump the current screen's UI Automator tree.
  *
+ * `uiautomator dump` reports success by exit code even when it wrote nothing
+ * (a null root node is a common cause and still exits 0), and the dump path is
+ * persistent. Dumping to one fixed path and reading it back therefore has a
+ * silent failure mode: a failed dump leaves the PREVIOUS file in place, and the
+ * caller is handed a stale screen as if it were current.
+ *
+ * The dump therefore goes to a path unique to this call, which both removes the
+ * staleness (nothing to read means an empty tree, not the last one) and lets two
+ * concurrent callers stop racing on one shared file. The file is removed again
+ * so repeated calls do not accumulate on the device.
+ *
  * @param {object} rt - the call runtime.
  * @param {{serial?: string, avd?: string, timeoutMs?: number}} [input] - the tool arguments.
  * @returns {Promise<{device: object, elements: Array<object>}>} the device and its flattened elements.
  */
 export async function describe(rt, input = {}) {
   const device = await ensureDevice(rt, input)
-  await adbShell(rt, device.serial, ['uiautomator', 'dump', '/sdcard/window.xml'], input.timeoutMs ?? 30_000)
-  const out = await adbShell(rt, device.serial, ['cat', '/sdcard/window.xml'], input.timeoutMs ?? 30_000)
-  return { device, elements: parseUiAutomator(out.stdout) }
+  const timeout = input.timeoutMs ?? 30_000
+  const remote = `/sdcard/.dsh-ui-${process.pid}-${Date.now()}-${dumpSeq++}.xml`
+  try {
+    await adbShell(rt, device.serial, ['uiautomator', 'dump', remote], timeout)
+    const out = await adbShell(rt, device.serial, ['cat', remote], timeout)
+    if (!looksLikeDump(out.stdout)) {
+      // Reported rather than answered with an empty tree: "no elements" is a
+      // legitimate screen, so silently returning it would let a failed dump pass
+      // for an empty UI and send the caller looking for a bug in its own query.
+      throw new Error(
+        `UI Automator produced no dump for ${device.serial}. The screen may be mid-transition, or a secure window is in front. Retry once the app has settled.`,
+      )
+    }
+    return { device, elements: parseUiAutomator(out.stdout) }
+  } finally {
+    await adbShell(rt, device.serial, ['rm', '-f', remote], timeout).catch(() => undefined)
+  }
 }
 
+/** Counter making each dump path unique within this process. */
+let dumpSeq = 0
+
 /**
  * Resolve a visible element to tap coordinates.
  *
@@ -84,13 +112,13 @@ export async function resolve(rt, input) {
  */
 export async function tap(rt, input) {
   const device = await ensureDevice(rt, input)
-  await adbShell(
-    rt,
-    device.serial,
-    ['input', 'tap', String(Math.round(input.x)), String(Math.round(input.y))],
-    input.timeoutMs ?? 30_000,
-  )
-  return { tapped: true, serial: device.serial, x: input.x, y: input.y }
+  // Report what was sent, not what was asked for: `input tap` takes integers, so
+  // a fractional request is rounded on the way out and the caller would
+  // otherwise be told a coordinate the device never received.
+  const x = Math.round(input.x)
+  const y = Math.round(input.y)
+  await adbShell(rt, device.serial, ['input', 'tap', String(x), String(y)], input.timeoutMs ?? 30_000)
+  return { tapped: true, serial: device.serial, x, y }
 }
 
 /**
@@ -102,28 +130,22 @@ export async function tap(rt, input) {
  */
 export async function swipe(rt, input) {
   const device = await ensureDevice(rt, input)
+  const x1 = Math.round(input.x1)
+  const y1 = Math.round(input.y1)
+  const x2 = Math.round(input.x2)
+  const y2 = Math.round(input.y2)
+  const durationMs = Math.round(input.durationMs ?? 300)
   await adbShell(
     rt,
     device.serial,
-    [
-      'input',
-      'swipe',
-      String(Math.round(input.x1)),
-      String(Math.round(input.y1)),
-      String(Math.round(input.x2)),
-      String(Math.round(input.y2)),
-      String(Math.round(input.durationMs ?? 300)),
-    ],
+    ['input', 'swipe', String(x1), String(y1), String(x2), String(y2), String(durationMs)],
     input.timeoutMs ?? 30_000,
   )
-  return {
-    swiped: true,
-    serial: device.serial,
-    x1: input.x1,
-    y1: input.y1,
-    x2: input.x2,
-    y2: input.y2,
-  }
+  // `durationMs` is part of the report because it is the one gesture parameter a
+  // caller cannot infer from the visible result: a clamped list moves the same
+  // distance at every duration, so without it there is no way to confirm which
+  // value actually ran.
+  return { swiped: true, serial: device.serial, x1, y1, x2, y2, durationMs }
 }
 
 /**
@@ -180,6 +202,15 @@ export function parseUiAutomator(value) {
   return elements
 }
 
+/** Whether a dump result is a UI Automator document rather than an error message. */
+function looksLikeDump(value) {
+  const text = String(value ?? '').trim()
+  if (!text.startsWith('<')) return false
+  // An empty hierarchy is still a valid dump; it is the absent document — the
+  // `cat` of a file the failed dump never wrote — that must not read as "no UI".
+  return /<hierarchy\b/.test(text)
+}
+
 /** Parse the attribute list of one `<node>` tag. */
 function attributes(value) {
   const out = new Map()
@@ -210,6 +241,15 @@ function parseBounds(value) {
 /**
  * Escape text for `adb shell input text`, which uses `%s` for spaces.
  *
+ * `input text` is a small custom parser, not a URL decoder: the ONLY escape it
+ * understands is `%s` for a space. Percent signs pass through unchanged, so
+ * replacing them with `%25` does not protect anything — the device types the
+ * four literal characters and the caller's text comes back corrupted.
+ *
+ * The residual limitation is the mirror image: a literal `%s` in the caller's
+ * text cannot be represented, because the device reads it as a space. That is
+ * documented rather than worked around, since escaping it is impossible.
+ *
  * @param {string} value - the raw text.
  * @returns {string} the escaped text.
  * @throws When the text is longer than {@link MAX_INPUT_TEXT_LENGTH}.
@@ -217,7 +257,7 @@ function parseBounds(value) {
 export function inputText(value) {
   if (typeof value !== 'string') throw new Error('Text input must be a string.')
   if (value.length > MAX_INPUT_TEXT_LENGTH) throw new Error('Text input is too long.')
-  return value.replace(/%/g, '%25').replace(/\s/g, '%s')
+  return value.replace(/\s/g, '%s')
 }
 
 /** Searchable text of one element. */

package/lib/settings.js

@@ -39,6 +39,14 @@ export const FIELD_GROUPS = [
   {
     id: 'sdk',
     env: 'ANDROID_PLUGIN_SDK_PATH',
+    // The heading and hint the settings page renders around this card. The
+    // browser half cannot import this module, so it carries its own copy;
+    // `scripts/check-bundle.mjs` compares the two word for word.
+    title: { zh: 'SDK 与工具链', en: 'SDK and toolchain' },
+    hint: {
+      zh: '预检、编译与 sdkmanager 使用的 Android SDK 与 JDK 位置。',
+      en: 'The Android SDK and JDK the diagnostic, the build and sdkmanager use.',
+    },
     fields: [
       {
         key: 'sdkPath',
@@ -60,8 +68,8 @@ export const FIELD_GROUPS = [
         placeholder: '17',
         label: { zh: 'JDK 主版本', en: 'JDK major version' },
         hint: {
-          zh: '用于预检与安装指引，例如 17 或 21。',
-          en: 'Used by preflight and the install guidance, e.g. 17 or 21.',
+          zh: '用于预检与安装指引；下拉项来自本机已安装的 JDK。',
+          en: "Used by the diagnostic and the install guidance; the suggestions come from this machine's JDKs.",
         },
       },
       {
@@ -72,14 +80,19 @@ export const FIELD_GROUPS = [
         placeholder: '35.0.0',
         label: { zh: 'Build-tools 版本', en: 'Build-tools version' },
         hint: {
-          zh: '预检与安装指引中使用的 Android SDK build-tools 版本。',
-          en: 'The Android SDK build-tools version named by preflight and the install guidance.',
+          zh: '安装指引中引用的 Android SDK build-tools 版本。',
+          en: 'The Android SDK build-tools version named by the install guidance.',
         },
       },
     ],
   },
   {
     id: 'emulator',
+    title: { zh: '模拟器与设备', en: 'Emulator and devices' },
+    hint: {
+      zh: '选择默认 AVD、如何启动模拟器，以及传给 emulator 的命令行参数。',
+      en: 'The default AVD, how the emulator starts, and the arguments it receives.',
+    },
     fields: [
       {
         key: 'defaultAvd',
@@ -126,16 +139,24 @@ export const FIELD_GROUPS = [
         },
       },
       {
-        key: 'bootTimeoutMs',
+        key: 'bootTimeoutSeconds',
         kind: 'number',
-        default: 180000,
-        label: { zh: '模拟器启动超时 (ms)', en: 'Emulator boot timeout (ms)' },
-        hint: { zh: '等待模拟器启动完成的最长时间。', en: 'Longest wait for the emulator to finish booting.' },
+        default: 180,
+        label: { zh: '模拟器启动超时（秒）', en: 'Emulator boot timeout (seconds)' },
+        hint: {
+          zh: '等待模拟器完成启动的最长时间，默认 180 秒。',
+          en: 'Longest wait for the emulator to finish booting; 180 seconds by default.',
+        },
       },
     ],
   },
   {
     id: 'image',
+    title: { zh: 'API 级别与系统镜像', en: 'API level and system image' },
+    hint: {
+      zh: '生成项目、安装 SDK 包与创建 AVD 时使用的默认值。',
+      en: 'Defaults used when generating a project, installing SDK packages and creating an AVD.',
+    },
     fields: [
       {
         key: 'apiLevel',
@@ -166,8 +187,8 @@ export const FIELD_GROUPS = [
         options: ['', ...SYSTEM_IMAGE_ABIS],
         label: { zh: '系统镜像 ABI', en: 'System image ABI' },
         hint: {
-          zh: '留空时 Apple Silicon 用 arm64-v8a，其他宿主用 x86_64。',
-          en: 'Empty uses arm64-v8a on Apple Silicon and x86_64 elsewhere.',
+          zh: '自动时 Apple Silicon 用 arm64-v8a，其他宿主用 x86_64。',
+          en: 'Automatic uses arm64-v8a on Apple Silicon and x86_64 elsewhere.',
         },
       },
       {
@@ -175,19 +196,30 @@ export const FIELD_GROUPS = [
         kind: 'number',
         default: 23,
         label: { zh: '默认 minSdk', en: 'Default minSdk' },
-        hint: { zh: 'android_create_app 生成新项目时的默认 minSdk。', en: 'Default minSdk for a project created by android_create_app.' },
+        hint: {
+          zh: 'android_create_app 生成新项目时的默认 minSdk，默认 23。',
+          en: 'Default minSdk for a project created by android_create_app; 23 by default.',
+        },
       },
     ],
   },
   {
     id: 'build',
+    title: { zh: '构建', en: 'Build' },
+    hint: {
+      zh: 'Gradle 构建的超时与附加参数。',
+      en: 'Gradle timeouts and extra arguments.',
+    },
     fields: [
       {
-        key: 'buildTimeoutMs',
+        key: 'buildTimeoutSeconds',
         kind: 'number',
-        default: 600000,
-        label: { zh: 'Gradle 构建超时 (ms)', en: 'Gradle build timeout (ms)' },
-        hint: { zh: '一次 assemble 任务的最长运行时间。', en: 'Longest runtime of one assemble task.' },
+        default: 600,
+        label: { zh: 'Gradle 构建超时（秒）', en: 'Gradle build timeout (seconds)' },
+        hint: {
+          zh: '一次 assemble 任务的最长运行时间，默认 600 秒。',
+          en: 'Longest runtime of one assemble task; 600 seconds by default.',
+        },
       },
       {
         key: 'gradleExtraArgs',
@@ -201,6 +233,11 @@ export const FIELD_GROUPS = [
   },
   {
     id: 'output',
+    title: { zh: '输出目录与日志', en: 'Output and logs' },
+    hint: {
+      zh: '截图与构建日志的落盘位置。',
+      en: 'Where screenshots and build logs are written.',
+    },
     fields: [
       {
         key: 'dataDir',
@@ -226,7 +263,10 @@ export const FIELD_GROUPS = [
         kind: 'number',
         default: 500,
         label: { zh: '默认 logcat 行数', en: 'Default logcat lines' },
-        hint: { zh: 'android_logs 未指定行数时读取的最近行数。', en: 'Lines android_logs reads when the call names none.' },
+        hint: {
+          zh: 'android_logs 未指定行数时读取的最近行数，默认 500。',
+          en: 'Lines android_logs reads when the call names none; 500 by default.',
+        },
       },
     ],
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhz8888/dsh-android-emulator-helper",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "icon": "./icon.svg",
   "description": "Android SDK, emulator and device management plus Kotlin/Compose build-and-run tools for DeepSeek Harness, ported from the official ZCode android-emulator plugin, with a full in-app settings page.",
   "keywords": [