dsh-android-tool 0.0.0-stage → 0.1.1

package/cordis.patch.yml

@@ -0,0 +1,28 @@
+# dsh-android-tool 的挂载层。
+#
+# 只插入 host 行：AndroidService + 四个 AI 工具 + /x-android-tool 的 HTTP/WS 接口。
+# 浏览器半边（侧边栏「安卓设备」与设置里的「安卓调试」）随 dsh.client 一起加载，
+# 不在这里声明。
+#
+# 配置项一律给默认值：
+#   - adbPath / scrcpyPath 留空 = 自动使用本插件目录下 scrcpy-win64-v5.0.1 里的
+#     adb.exe / scrcpy.exe；
+#   - wirelessHost 留空 = 还没配置无线调试，插件正常运行，只是连不上设备；
+# 用户在「设置 → 安卓调试」里改，写入后立即生效（全部字段都是 volatile）。
+- insert:
+    - id: dsh-android-tool
+      name: dsh-android-tool
+      config:
+        adbPath: ''
+        scrcpyPath: ''
+        wirelessHost: ''
+        wirelessPort: 5555
+        pairingPort: 0
+        autoConnect: false
+        videoMaxSize: 720
+        videoBitRate: 2500000
+        videoFps: 30
+        previewFps: 3
+        logcatMaxLines: 5000
+        adbTimeoutMs: 15000
+        scrcpyExtraArgs: ''

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="16" y="4" width="32" height="56" rx="7" fill="none" stroke="currentColor" stroke-width="3" opacity="0.9"/>
+  <rect x="20" y="9" width="24" height="42" rx="3" fill="currentColor" opacity="0.16"/>
+  <circle cx="32" cy="55" r="2.6" fill="currentColor" opacity="0.75"/>
+  <path d="M27 19h10M27 23h10M27 27h7" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" opacity="0.85"/>
+  <path d="M24 33l-5 3 5 3M40 33l5 3-5 3" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" opacity="0.7"/>
+</svg>

package/index.js

@@ -0,0 +1,74 @@
+/**
+ * dsh-android-tool —— 把 Android 设备接进 DSH（host 半边）。
+ *
+ * 这一层做四件事：
+ *   1. 构造 AndroidService（adb / logcat / 性能 / scrcpy 推流与独立窗口）；
+ *   2. 注册 android_view / android_state / android_control / android_adb 四个工具；
+ *   3. 注册 /x-android-tool 的 HTTP 与 WebSocket 接口（侧边栏与设置页用）；
+ *   4. 卸载时关掉本插件启动的进程。
+ *
+ * 插件加载本身不 spawn 任何进程，第一次访问设备时才启动。
+ */
+
+import { snapshotConfig } from './lib/config.js'
+import { Config } from './lib/config-schema.js'
+import { pluginRootFrom } from './lib/paths.js'
+import { AndroidService } from './lib/service.js'
+import { buildTools } from './lib/tools.js'
+import { registerWebRoutes } from './lib/webapi.js'
+
+export const name = 'dsh-android-tool'
+
+/** `tools` 是硬依赖：没有工具注册表，这个插件就没有意义。 */
+export const inject = ['tools']
+
+export { Config }
+
+/**
+ * @param {object} ctx - host 作用域上下文
+ * @param {object} config - 运行期配置（volatile 字段需实时读取）
+ */
+export function apply(ctx, config) {
+  const logger = ctx.logger
+  const pluginRoot = pluginRootFrom(import.meta.url)
+
+  const service = new AndroidService({
+    ctx,
+    getConfig: () => snapshotConfig(config),
+    pluginRoot,
+    getProfileDir: () => process.env.DSH_PROFILE_DIR ?? '',
+    logger,
+  })
+
+  ctx.provide('androidTool', service)
+
+  // ── 工具注册（host 层，所有会话可见）──────────────────────────────────────
+  for (const definition of buildTools({ service })) {
+    ctx.effect(() => ctx.tools.register(definition), `dsh-android-tool: ${definition.name}`)
+  }
+
+  // ── 面板 / 设置页接口 ─────────────────────────────────────────────────────
+  ctx.inject(['webServer'], (scope) => {
+    scope.effect(
+      () => registerWebRoutes(scope.webServer, { service, logger }),
+      'dsh-android-tool: console routes',
+    )
+  })
+
+  // ── 拆卸 ───────────────────────────────────────────────────────────────────
+  ctx.effect(
+    () => () => {
+      service.dispose()
+    },
+    'dsh-android-tool: disposal',
+  )
+
+  void service.init().catch((error) => {
+    logger?.warn?.(`dsh-android-tool: 初始化失败 ${error instanceof Error ? error.message : String(error)}`)
+  })
+
+  const settings = snapshotConfig(config)
+  logger?.info?.(
+    `dsh-android-tool: 已加载（adb: ${settings.adbPath || '随包默认'} · 无线: ${settings.wirelessHost || '未配置'}）`,
+  )
+}

package/lib/adb.js

@@ -0,0 +1,422 @@
+/**
+ * adb 执行器：设备发现、无线调试、截图、shell 与按键。
+ *
+ * 约束：
+ *   - 永不抛；所有失败都变成 `{ ok:false, error }`。
+ *   - 每个命令都带 `-s <serial>`，避免多设备串线。
+ *   - 超时用 taskkill /T /F（Windows）或 SIGKILL，避免 adb 卡死拖着界面。
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolveExecutablePaths } from './config.js'
+import { join } from 'node:path'
+
+/** 文本输出上限。 */
+const TEXT_MAX_BYTES = 4 * 1024 * 1024
+
+/** 截图上限。 */
+const IMAGE_MAX_BYTES = 32 * 1024 * 1024
+
+/** 常用按键名 → Android keycode。 */
+export const KEY_CODES = {
+  back: 4,
+  home: 3,
+  recents: 187,
+  app_switch: 187,
+  menu: 82,
+  enter: 66,
+  escape: 111,
+  del: 67,
+  delete: 67,
+  tab: 61,
+  space: 62,
+  up: 19,
+  down: 20,
+  left: 21,
+  right: 22,
+  volume_up: 24,
+  volume_down: 25,
+  mute: 164,
+  power: 26,
+  wakeup: 224,
+  sleep: 223,
+  camera: 27,
+  search: 84,
+  page_up: 92,
+  page_down: 93,
+}
+
+/** 把按键名或数字转成 keycode。 */
+export function resolveKeyCode(key) {
+  const text = String(key ?? '').trim().toLowerCase()
+  if (/^\d+$/u.test(text)) return Number(text)
+  return KEY_CODES[text]
+}
+
+/** 杀进程树。 */
+function killTree(child) {
+  if (child === undefined || child === null || child.killed) return
+  try {
+    if (process.platform === 'win32') {
+      const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+      killer.on('error', () => {})
+    } else {
+      child.kill('SIGKILL')
+    }
+  } catch {
+    // 忽略
+  }
+}
+
+/**
+ * 跑一个子进程并收集输出。
+ *
+ * @param {string} file
+ * @param {string[]} args
+ * @param {{ timeoutMs?: number, maxBytes?: number, binary?: boolean }} [options]
+ * @returns {Promise<{ok:boolean, code:number|null, stdout:string, stderr:string, buffer?:Buffer, truncated?:boolean, elapsedMs:number, error?:string}>}
+ */
+export function runProcess(file, args, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 15000
+  const maxBytes = Number.isFinite(options.maxBytes) ? options.maxBytes : TEXT_MAX_BYTES
+  const binary = options.binary === true
+  const started = Date.now()
+
+  return new Promise((resolvePromise) => {
+    let child
+    try {
+      child = spawn(file, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch (error) {
+      resolvePromise({ ok: false, code: null, stdout: '', stderr: '', elapsedMs: 0, error: error instanceof Error ? error.message : String(error) })
+      return
+    }
+
+    const stdoutChunks = []
+    const stderrChunks = []
+    let stdoutBytes = 0
+    let stderrBytes = 0
+    let truncated = false
+    let settled = false
+    let timedOut = false
+
+    const finish = (payload) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolvePromise({
+        ok: payload.code === 0 && timedOut === false,
+        code: payload.code,
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        ...(binary ? { buffer: Buffer.concat(stdoutChunks) } : {}),
+        truncated,
+        elapsedMs: Date.now() - started,
+        ...(timedOut ? { error: `命令超时（${timeoutMs}ms）` } : {}),
+        ...(payload.error ? { error: payload.error } : {}),
+      })
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true
+      killTree(child)
+    }, timeoutMs)
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBytes += chunk.length
+      if (stdoutBytes > maxBytes) {
+        truncated = true
+        const room = maxBytes - (stdoutBytes - chunk.length)
+        if (room > 0) stdoutChunks.push(chunk.subarray(0, room))
+        return
+      }
+      stdoutChunks.push(chunk)
+    })
+    child.stderr.on('data', (chunk) => {
+      stderrBytes += chunk.length
+      if (stderrBytes > maxBytes) {
+        truncated = true
+        const room = maxBytes - (stderrBytes - chunk.length)
+        if (room > 0) stderrChunks.push(chunk.subarray(0, room))
+        return
+      }
+      stderrChunks.push(chunk)
+    })
+    child.on('error', (error) => {
+      finish({ code: null, error: error instanceof Error ? error.message : String(error) })
+    })
+    child.on('close', (code) => {
+      finish({ code })
+    })
+  })
+}
+
+/**
+ * 解析 `adb devices -l`。
+ * @param {string} output
+ * @returns {Array<{serial:string,state:string,model:string,product:string,device:string,transportId:string}>}
+ */
+export function parseAdbDevices(output) {
+  const rows = []
+  for (const raw of String(output ?? '').split(/\r?\n/u)) {
+    const line = raw.trim()
+    if (line.length === 0) continue
+    if (line.startsWith('List of devices') || line.startsWith('*')) continue
+    const parts = line.split(/\s+/u)
+    if (parts.length < 2) continue
+    const serial = parts[0]
+    const state = parts[1]
+    if (!/^(device|offline|unauthorized|bootloader|recovery|sideload|authorizing|connecting)$/u.test(state)) continue
+    const extras = {}
+    for (const token of parts.slice(2)) {
+      const index = token.indexOf(':')
+      if (index > 0) extras[token.slice(0, index)] = token.slice(index + 1)
+    }
+    rows.push({
+      serial,
+      state,
+      model: extras.model ?? '',
+      product: extras.product ?? '',
+      device: extras.device ?? '',
+      transportId: extras.transport_id ?? '',
+    })
+  }
+  return rows
+}
+
+/** 从 PNG 头里读宽高。 */
+export function pngSize(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 24) return undefined
+  if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) return undefined
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+}
+
+/** 从设备列表里选一台可用设备。 */
+export function pickDevice(devices, preferred) {
+  const list = Array.isArray(devices) ? devices : []
+  const online = list.filter((item) => item.state === 'device')
+  const wanted = String(preferred ?? '').trim()
+  if (wanted.length > 0) {
+    const hit = online.find((item) => item.serial === wanted)
+    if (hit !== undefined) return { ok: true, device: hit }
+  }
+  if (online.length === 1) return { ok: true, device: online[0] }
+  if (online.length === 0) {
+    const unauthorized = list.filter((item) => item.state === 'unauthorized')
+    const offline = list.filter((item) => item.state === 'offline')
+    if (unauthorized.length > 0) {
+      return { ok: false, error: `设备未授权：${unauthorized.map((item) => item.serial).join(', ')}。请在手机上点「允许 USB 调试」。` }
+    }
+    if (offline.length > 0) {
+      return { ok: false, error: `设备离线：${offline.map((item) => item.serial).join(', ')}。请检查连接或重新 adb connect。` }
+    }
+    return { ok: false, error: '没有检测到 Android 设备。请插 USB 或先在设置里连接无线调试。' }
+  }
+  return {
+    ok: false,
+    error: `发现 ${online.length} 台设备，但还没有选择当前调试设备。请在「设置 → 安卓调试」或面板顶部选一台。`,
+    multiple: online.map((item) => item.serial),
+  }
+}
+
+/** adb 操作集合。 */
+export class Adb {
+  /**
+   * @param {object} options
+   * @param {() => object} options.getConfig
+   * @param {string} options.pluginRoot
+   * @param {object} [options.logger]
+   */
+  constructor(options) {
+    this.getConfig = options.getConfig
+    this.pluginRoot = options.pluginRoot
+    this.logger = options.logger
+  }
+
+  /** 解析 adb 路径并校验存在。 */
+  resolve() {
+    const settings = this.getConfig()
+    const paths = resolveExecutablePaths({
+      pluginRoot: this.pluginRoot,
+      adbPath: settings.adbPath,
+      scrcpyPath: settings.scrcpyPath,
+      join,
+    })
+    if (!existsSync(paths.adbPath)) {
+      return {
+        ok: false,
+        error: `找不到 adb：${paths.adbPath}。请在「设置 → 安卓调试」里填正确的 adb.exe 路径。`,
+        paths,
+      }
+    }
+    return { ok: true, path: paths.adbPath, paths }
+  }
+
+  /** 解析 scrcpy 路径。 */
+  resolveScrcpy() {
+    const settings = this.getConfig()
+    return resolveExecutablePaths({
+      pluginRoot: this.pluginRoot,
+      adbPath: settings.adbPath,
+      scrcpyPath: settings.scrcpyPath,
+      join,
+    })
+  }
+
+  /**
+   * 执行 adb 子命令（自动加 -s）。
+   * @param {string[]} args
+   * @param {{serial?:string, timeoutMs?:number, maxBytes?:number, binary?:boolean}} [options]
+   */
+  async run(args, options = {}) {
+    const resolved = this.resolve()
+    if (!resolved.ok) return { ok: false, code: null, stdout: '', stderr: '', elapsedMs: 0, error: resolved.error }
+    const list = Array.isArray(args) ? [...args] : []
+    const serial = String(options.serial ?? '').trim()
+    const argv = serial.length > 0 ? ['-s', serial, ...list] : list
+    const result = await runProcess(resolved.path, argv, {
+      timeoutMs: options.timeoutMs ?? this.getConfig().adbTimeoutMs,
+      maxBytes: options.maxBytes,
+      binary: options.binary === true,
+    })
+    if (result.ok !== true && result.error === undefined) {
+      result.error = (result.stderr || '').trim() || `adb 退出码 ${result.code ?? '?'}`
+    }
+    return result
+  }
+
+  /** `adb version`。 */
+  async version() {
+    const result = await this.run(['version'], { timeoutMs: 8000 })
+    if (result.ok !== true) return result
+    return { ok: true, version: result.stdout.trim(), path: this.resolve().path }
+  }
+
+  /** `adb devices -l`。 */
+  async devices() {
+    const result = await this.run(['devices', '-l'], { timeoutMs: 12000 })
+    if (result.ok !== true) return { ok: false, error: result.error, devices: [] }
+    return { ok: true, devices: parseAdbDevices(result.stdout), raw: result.stdout.trim() }
+  }
+
+  /** 选中设备（返回 ok/device/error）。 */
+  async selectDevice(preferred) {
+    const listed = await this.devices()
+    if (listed.ok !== true) return { ok: false, error: listed.error, devices: [] }
+    const picked = pickDevice(listed.devices, preferred)
+    return { ...picked, devices: listed.devices }
+  }
+
+  /** 连接无线设备。 */
+  async connect(host, port) {
+    const target = `${String(host ?? '').trim()}:${Number(port) || 5555}`
+    if (String(host ?? '').trim().length === 0) return { ok: false, error: '请先填写设备 IP。' }
+    const result = await this.run(['connect', target], { timeoutMs: 15000 })
+    return { ok: result.ok === true, target, output: (result.stdout || result.stderr || '').trim(), error: result.ok === true ? undefined : result.error }
+  }
+
+  /** 断开无线设备。 */
+  async disconnect(host, port) {
+    const target = `${String(host ?? '').trim()}:${Number(port) || 5555}`
+    const result = await this.run(['disconnect', target], { timeoutMs: 10000 })
+    return { ok: result.ok === true, target, output: (result.stdout || result.stderr || '').trim(), error: result.ok === true ? undefined : result.error }
+  }
+
+  /** Android 11+ 无线调试配对。 */
+  async pair(host, port, code) {
+    const target = `${String(host ?? '').trim()}:${Number(port)}`
+    if (String(host ?? '').trim().length === 0) return { ok: false, error: '请先填写设备 IP。' }
+    if (!Number(port)) return { ok: false, error: '请填写无线调试的配对端口。' }
+    if (String(code ?? '').trim().length === 0) return { ok: false, error: '请填写手机屏幕上显示的配对码。' }
+    const result = await this.run(['pair', target, String(code).trim()], { timeoutMs: 30000 })
+    return { ok: result.ok === true, target, output: (result.stdout || result.stderr || '').trim(), error: result.ok === true ? undefined : result.error }
+  }
+
+  /** USB 已连接时开启 TCP 模式。 */
+  async enableTcpip(serial, port = 5555) {
+    const result = await this.run(['tcpip', String(port)], { serial, timeoutMs: 15000 })
+    return { ok: result.ok === true, port, output: (result.stdout || result.stderr || '').trim(), error: result.ok === true ? undefined : result.error }
+  }
+
+  /** 执行 shell 命令。 */
+  async shell(serial, command, options = {}) {
+    const text = String(command ?? '').trim()
+    if (text.length === 0) return { ok: false, error: '命令为空。' }
+    return this.run(['shell', text], { serial, timeoutMs: options.timeoutMs })
+  }
+
+  /** 发送按键。 */
+  async keyevent(serial, key) {
+    const code = resolveKeyCode(key)
+    if (code === undefined) return { ok: false, error: `不认识的按键：${key}` }
+    return this.run(['shell', `input keyevent ${code}`], { serial, timeoutMs: 8000 })
+  }
+
+  /** tap。 */
+  async tap(serial, x, y) {
+    return this.run(['shell', `input tap ${Math.round(Number(x))} ${Math.round(Number(y))}`], { serial, timeoutMs: 8000 })
+  }
+
+  /** 长按 / 滑动。 */
+  async swipe(serial, x1, y1, x2, y2, durationMs = 300) {
+    const ms = Math.max(50, Math.round(Number(durationMs) || 300))
+    return this.run(
+      ['shell', `input swipe ${Math.round(Number(x1))} ${Math.round(Number(y1))} ${Math.round(Number(x2))} ${Math.round(Number(y2))} ${ms}`],
+      { serial, timeoutMs: 12000 },
+    )
+  }
+
+  /** 输入 ASCII 文本（Android input 不支持中文，中文会返回提示）。 */
+  async inputText(serial, text) {
+    const source = String(text ?? '')
+    if (source.length === 0) return { ok: false, error: '文本为空。' }
+    if (/[^\x20-\x7e]/u.test(source)) {
+      return {
+        ok: false,
+        error: 'adb input text 只支持 ASCII。中文/emoji 请用「打开 scrcpy 窗口」在电脑键盘输入，或先装输入法辅助应用。',
+        unsupported: true,
+      }
+    }
+    const escaped = source.replace(/ /gu, '%s').replace(/'/gu, `'\\''`)
+    return this.run(['shell', `input text '${escaped}'`], { serial, timeoutMs: 8000 })
+  }
+
+  /**
+   * 截图，返回 PNG Buffer。
+   * 优先 exec-out（二进制安全）；失败时退回 shell screencap 到设备临时文件再 exec-out cat。
+   */
+  async screencap(serial) {
+    const direct = await this.run(['exec-out', 'screencap', '-p'], {
+      serial,
+      timeoutMs: 15000,
+      maxBytes: IMAGE_MAX_BYTES,
+      binary: true,
+    })
+    if (direct.ok === true && pngSize(direct.buffer) !== undefined) {
+      const size = pngSize(direct.buffer)
+      return { ok: true, buffer: direct.buffer, width: size.width, height: size.height }
+    }
+
+    const remote = `/data/local/tmp/dsh-android-${Date.now()}.png`
+    const shot = await this.run(['shell', `screencap -p ${remote}`], { serial, timeoutMs: 15000 })
+    if (shot.ok !== true) {
+      return { ok: false, error: shot.error ?? '截图失败', stderr: direct.stderr }
+    }
+    const pulled = await this.run(['exec-out', 'cat', remote], {
+      serial,
+      timeoutMs: 15000,
+      maxBytes: IMAGE_MAX_BYTES,
+      binary: true,
+    })
+    void this.run(['shell', `rm -f ${remote}`], { serial, timeoutMs: 3000 })
+    const size = pngSize(pulled.buffer)
+    if (pulled.ok === true && size !== undefined) {
+      return { ok: true, buffer: pulled.buffer, width: size.width, height: size.height }
+    }
+    return {
+      ok: false,
+      error: `截图失败：${pulled.error ?? direct.error ?? '返回数据不是 PNG'}`,
+      stderr: `${direct.stderr || ''}\n${pulled.stderr || ''}`.trim(),
+    }
+  }
+}

package/lib/config-schema.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-android-tool 的 Config schema。
+ *
+ * 每个字段都过 `volatile()`：DSH 设置页只允许写 volatile 字段，volatile 更新走
+ * `loader/volatile-update`、就地提交、不重挂插件，所以 apply() 只跑一次；
+ * 业务代码每次用时都要读实时值（见 config.js: snapshotConfig）。
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { DEFAULTS } from './config.js'
+
+/** 把 schema 标记为 volatile（老版本 schemastery 没有就退化）。 */
+function live(schema) {
+  return typeof schema?.volatile === 'function' ? schema.volatile() : schema
+}
+
+export const Config = z.object({
+  adbPath: live(
+    z
+      .string()
+      .default(DEFAULTS.adbPath)
+      .description('adb 可执行文件路径。留空 = 使用本插件 scrcpy-win64-v5.0.1 目录里的 adb.exe。'),
+  ),
+  scrcpyPath: live(
+    z
+      .string()
+      .default(DEFAULTS.scrcpyPath)
+      .description('scrcpy 可执行文件路径。精简包默认不含 scrcpy.exe；如果需要「打开 scrcpy 窗口」，请填本机 scrcpy.exe 的路径。'),
+  ),
+  wirelessHost: live(z.string().default(DEFAULTS.wirelessHost).description('无线调试的设备 IP，例如 192.168.1.23。留空 = 未配置。')),
+  wirelessPort: live(z.number().step(1).min(1).max(65535).default(DEFAULTS.wirelessPort).description('adb connect 使用的端口，Android 无线调试通常是 5555 或系统给出的端口。')),
+  pairingPort: live(z.number().step(1).min(0).max(65535).default(DEFAULTS.pairingPort).description('Android 11+ 无线调试配对端口。0 = 未设置；配对码只用于一次配对，不保存。')),
+  autoConnect: live(z.boolean().default(DEFAULTS.autoConnect).description('插件加载后自动 adb connect 配置的无线设备。')),
+  videoMaxSize: live(z.number().step(1).min(320).max(4096).default(DEFAULTS.videoMaxSize).description('scrcpy 画面最大边长（像素）。越小越省带宽。')),
+  videoBitRate: live(z.number().step(100000).min(100000).max(50000000).default(DEFAULTS.videoBitRate).description('scrcpy 视频码率（bit/s）。默认 4 Mbps。')),
+  videoFps: live(z.number().step(1).min(1).max(120).default(DEFAULTS.videoFps).description('scrcpy 最大帧率。')),
+  previewFps: live(z.number().step(1).min(1).max(10).default(DEFAULTS.previewFps).description('WebCodecs 不可用时的截图轮询帧率（1–10）。')),
+  logcatMaxLines: live(z.number().step(100).min(100).max(100000).default(DEFAULTS.logcatMaxLines).description('服务端 logcat 环形缓冲最大行数。')),
+  adbTimeoutMs: live(z.number().step(500).min(1000).max(120000).default(DEFAULTS.adbTimeoutMs).description('单次 adb 命令默认超时（毫秒）。')),
+  scrcpyExtraArgs: live(z.string().default(DEFAULTS.scrcpyExtraArgs).description('追加给独立 scrcpy 窗口的启动参数（空格分隔，高级用户使用）。')),
+})