@zhz8888/dsh-android-emulator-helper 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 zhz8888
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package is a DeepSeek Harness port of the ZCode official
+`android-emulator` plugin, which is distributed under the MIT License by Z.ai.
+Its provider logic and Kotlin/Jetpack Compose project template are ported from
+that plugin, and the template files are kept verbatim. See the "Differences
+from the original" section of README.md for the full account of what changed.

package/README.md

@@ -1,3 +1,294 @@
-# Temporary Holding Version
+# dsh-android-emulator-helper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** | [简体中文](README.zh-CN.md)
+
+The package is named `@zhz8888/dsh-android-emulator-helper`, and the plugin page
+shows its localized name — **Android Emulator** in English, **Android 模拟器** in
+Chinese — read from `locale/en.json` and `locale/zh.json`, which carry the
+one-line description too.
+
+A DSH (DeepSeek Harness) port of the official ZCode `android-emulator@0.1.0`
+plugin. All 23 tools keep their original names and argument names, and the
+plugin adds a full **settings page** (Settings → Android emulator) so the SDK,
+emulator, system-image, build and output parameters are configured in the app
+instead of through environment variables.
+
+## Contents
+
+- [Install](#install)
+- [Settings page](#settings-page)
+- [Tools](#tools)
+- [Skill and command](#skill-and-command)
+- [Differences from the original](#differences-from-the-original)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Known limitations](#known-limitations)
+- [Releases](#releases)
+- [License](#license)
+
+## Install
+
+### 1. Install dependencies
+
+```bash
+cd /path/to/dsh-android-emulator-helper
+pnpm install                     # the @deepseek-ai/* peers + react for the tests
+```
+
+Every `@deepseek-ai/*` package this plugin imports — `cordis`, `dsh-tools` and
+`schemastery` — is a **peer dependency the host provides**, not a dependency of
+its own: the profile already carries them, and resolving them to the host's copy
+keeps one `schemastery` instance behind the settings form. The local `pnpm
+install` above installs them for development and tests only.
+
+DSH's compatibility gate compares exactly the `@deepseek-ai/dsh*` peers against
+the runtime version, so a mismatch refuses the install loudly. The ranges are
+therefore lower-bound only (`>=0.2.0-rc.2`): an upper bound would have to be
+widened by a new release on every harness bump, and a `^` range silently drops
+the prereleases of the next version tuple.
+
+### 2. Mount into a profile
+
+**DSH Desktop**: the `desktop` profile is managed exclusively by the Electron
+app — `dsh plugin --profile desktop` is refused by the CLI. Install through the
+in-app plugin manager instead.
+
+**CLI / any other profile**:
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-android-emulator-helper
+```
+
+`dsh.bundle.patch` is declared, so DSH reconciles the package into
+`dsh.profile.bundles` and merges `cordis.patch.yml` at boot. Do **not** also add
+the same row to the profile's own `cordis.patch.yml`: a double mount registers
+every tool name twice and fails the load.
+
+### 3. Open the settings page
+
+After a restart or hot reload, open **Settings → Android emulator**. The page
+appears only while the host half actually serves the settings namespace, and
+leaves no trace when it does not.
+
+## Settings page
+
+The settings namespace is the profile patch row id, `android-emulator-helper`.
+The page reads and writes through `ctx.configForms`, so staged edits, dirty
+detection, inline validation, optimistic-concurrency revisions and
+"overridden / reset to default" all come from the harness. It draws its own
+title and one card per group — the card outline is what separates the
+categories — and the save lives in a sticky action bar at the bottom that
+appears only while there is something to act on: a staged edit, a write in
+flight, or a failure worth retrying.
+
+| Group | Field | Kind | Default |
+|---|---|---|---|
+| SDK and toolchain | `sdkPath` | text | empty (auto-detect) |
+| | `jdkMajor` | text, suggestions from this machine | `17` |
+| | `buildToolsVersion` | text, suggestions | `35.0.0` |
+| Emulator and devices | `defaultAvd` | text, suggestions | `medium_phone` |
+| | `defaultSerial` | text, suggestions | empty |
+| | `autoStartEmulator` | switch | on |
+| | `emulatorArgs` | multiline, one argument per line | empty |
+| | `bootTimeoutSeconds` | integer | `180` |
+| API and system image | `apiLevel` | text, suggestions | `35` |
+| | `systemImageVariant` | select | `default` |
+| | `systemImageAbi` | select (empty = host architecture) | auto |
+| | `minSdk` | integer | `23` |
+| Build | `buildTimeoutSeconds` | integer | `600` |
+| | `gradleExtraArgs` | multiline | empty |
+| Output and logs | `dataDir` | text | `$DSH_HOME/android-emulator-helper` |
+| | `screenshotDir` | text | `<data dir>/screenshots` |
+| | `logTailLines` | integer | `500` |
+
+Two buttons back the page with exact Fetch routes on the host half:
+
+- **Run diagnostic** → `GET /api/android-emulator-helper/status`, the same
+  checks as `android_preflight`, each with its detail and fix hint.
+- **Refresh devices and AVDs** → `GET /api/android-emulator-helper/inventory`,
+  detecting the SDK root, AVDs, connected devices, installed JDKs, system
+  images, platforms and build-tools to populate the fields' suggestions.
+
+The seven fields the original plugin exposed still fall back to their
+`ANDROID_PLUGIN_*` environment variables, so an existing ZCode or CI setup keeps
+working: the resolution order is settings page → environment variable →
+declared default.
+
+## Tools
+
+`android_preflight`, `android_discover_project`, `android_create_app`,
+`android_build_app`, `android_build_and_run`, `android_list_devices`,
+`android_list_avds`, `android_start_emulator`, `android_stop_emulator`,
+`android_create_avd`, `android_install_app`, `android_launch_app`,
+`android_terminate_app`, `android_open_url`, `android_screenshot`,
+`android_logs`, `android_ui_status`, `android_ui_describe`, `android_ui_resolve`,
+`android_ui_tap`, `android_ui_swipe`, `android_ui_type_text`,
+`android_ui_keyevent` — identical names and arguments to the original MCP
+server.
+
+`android_screenshot` always writes the PNG to disk and additionally submits it
+to the host attachment store for a canonical image block. When the current model
+does not declare image input, or the deployment stores no attachments, the
+result degrades to text plus the file path rather than failing the call.
+
+## Skill and command
+
+- The bundled `android-dev` skill is registered through `ctx.skills.register()`
+  with the skill directory as its `resourceBase`, so `INSTALL_ENVIRONMENT.md`
+  keeps resolving. Its text is rewritten for DSH: no `mcp__…` prefixes,
+  environment setup points at the settings page.
+- `/android-dev [goal]` runs the diagnostic and reports the verdict, failures
+  and fixes. DSH user commands deliberately create no model message, so the
+  command does the one useful thing that needs no model.
+
+## Differences from the original
+
+| | Original (ZCode) | This port (DSH) |
+|---|---|---|
+| Tool exposure | stdio MCP server, `mcp__android_emulator__*` | native `ctx.tools.register()`, `android_*` |
+| Configuration | `plugin.json` `userConfig` via `ANDROID_PLUGIN_*` | settings page + volatile `Config`; env vars still fall back |
+| Working directory | `process.cwd()` | `exec.agent.session.header.cwd` (session workspace) |
+| Data directory | `ANDROID_PLUGIN_DATA` / temp | `$DSH_HOME/android-emulator-helper`, configurable |
+| Screenshot | MCP image content (base64) | host attachment reference; text fallback |
+| Slash command | injects a model prompt | runs the diagnostic directly |
+| Process execution | direct `node:child_process` | unchanged |
+
+The direct `spawn` is a deliberate trade-off: `gradlew`, `adb` and `emulator`
+behave byte-for-byte as they did in the original, and `adb exec-out` needs no
+binary-stream adapter. The cost is bypassing DSH's subprocess seam — no managed
+process ranges, env scrubbing, output spill or teardown termination. Every call
+here has an explicit timeout and `SIGTERM`, and the plugin reads and forwards no
+credential-bearing environment variables.
+
+## Architecture
+
+```
+dsh-android-emulator-helper/
+├── package.json            # dsh.bundle.patch, dsh.client, peer dependencies (the compatibility gate)
+├── cordis.patch.yml        # - insert: [{ id: android-emulator-helper, name: '@zhz8888/dsh-android-emulator-helper' }]
+├── icon.svg                # plugin icon: the Android robot head, brand green, readable in both themes
+├── locale/en.json          # plugin-page name and description (English; its presence is what enables every other language)
+├── locale/zh.json          # the Simplified Chinese pair
+├── lib/
+│   ├── index.js            # host half: tools, skill, command and the two Fetch routes
+│   ├── client.js           # browser half: a hand-written __ModuleLoader__ bundle, the settings page
+│   ├── settings.js         # field declarations, the schemastery Config (every field .volatile()), live reads
+│   ├── runtime.js          # one runtime per call: session cwd + live settings → data directory
+│   ├── tools/index.js      # the 23 defineTool definitions, argument/result schemas, image admission
+│   ├── providers/          # ported from the original plugin file by file, now taking an explicit runtime
+│   └── util/               # process execution, paths, content blocks
+├── skills/android-dev/     # SKILL.md + INSTALL_ENVIRONMENT.md
+├── scripts/                # check-bundle.mjs (consistency gate), smoke.mjs (real-machine), verify-mount.mjs
+└── test/                   # node:test unit and integration suites
+```
+
+Three constraints shape everything above:
+
+1. **The settings namespace has exactly one source of truth**: the profile patch
+   row id. The `id` in `cordis.patch.yml`, `SETTINGS_NAMESPACE` in
+   `lib/settings.js` and the literal in `lib/client.js` must agree;
+   `scripts/check-bundle.mjs` verifies them, and also that the host and client
+   field tables have not drifted apart.
+2. **A browser bundle cannot import a host module** — the client purity gate
+   forbids cross-plugin value imports — so the field table is written twice and
+   held together by that gate. The bundle may `require` only the shell's nine
+   static modules (React, Cordis, `dsh-client-store`, `dsh-client-ui-slots`,
+   `dsh-client-ui-primitives`, `dsh-client-ui-dockkit`, …).
+3. **The plugin-page name is a package resource, not a manifest field**: DSH
+   resolves `<package>/locale/en.json` through the `exports` map, so
+   `./locale/*.json` has to stay exported and `locale` has to stay in `files`;
+   either omission degrades silently to showing the raw package name. `en.json`
+   is also the switch that enables every other language file, so it cannot be
+   dropped in favour of `zh.json`. `test/manifest.test.js` pins all three
+   conditions.
+
+## Development
+
+```bash
+pnpm install                 # the @deepseek-ai/* peers plus react/react-dom for the tests
+pnpm test                    # 145 tests, no Android SDK needed
+pnpm run check               # tests + host/client gate + real-Cordis mount
+pnpm run verify:mount        # real Cordis Context and real ToolRuntime
+pnpm run smoke               # read-only real-machine probes
+pnpm run smoke:emulator      # also boot an AVD, screenshot, logs, stop
+pnpm run link:dsh-deps       # offline dev: symlink a local DSH's @deepseek-ai packages
+```
+
+The package manager is pnpm: `packageManager` pins `pnpm@11.8.0`, and
+`pnpm-lock.yaml` is the only lockfile (npm's `package-lock.json` is gone).
+[`pnpm-workspace.yaml`](pnpm-workspace.yaml) does not open a workspace — this is a
+single-package repository — it only carries the install-script policy:
+`strictDepBuilds: true`. pnpm v10+ skips a dependency's build scripts *silently*
+by default, which is the wrong failure mode here, so the strict mode makes
+`pnpm install` fail immediately with `ERR_PNPM_IGNORED_BUILDS` and forces an
+explicit per-package decision. The current tree (27 packages) was scanned and
+contains no install-time build scripts, so no `allowBuilds` entry is needed.
+
+Four layers of verification:
+
+| Layer | Command | What it proves |
+|---|---|---|
+| Unit and parsers | `pnpm test` | Bundle load contract, manifest/patch contract, settings projection (live volatile reads, env fallback, out-of-range fallback), every ported parser, and the lossless-JSON projection |
+| Settings page render | `pnpm test` | The whole page rendered with real React and `react-dom/server`: every group, field and dictionary key present, controlled inputs holding live values, switch and select state correct, override badge and reset, both route buttons, and no action bar while nothing is staged |
+| Consistency gate | `scripts/check-bundle.mjs` | Bundle id equals the package name, namespace equals the patch row id, the two field tables and the two group tables match key-for-key and in order, every heading, hint, placeholder and option matches the host **word for word in both languages**, both routes agree on both sides, `locale/*.json` carries the same keys in both languages, and the bundle is still a classic script |
+| Route integration | `test/routes-integration.test.js` | The two settings routes mounted on a **real** Cordis `Context`: each handler invoked and its `Response` read, all 17 fields arriving as live volatile references, a saved setting visible to the very next call, a handler error answered as a `500` body rather than a crash, an absent optional service tolerated, and disposal removing both routes |
+| Real host mount | `scripts/verify-mount.mjs` | Mounted on a **real** Cordis `Context` with the **real** `ToolRuntime`: 23 tools registered, **all 23 dispatched through the registry** and validated against their argument and result schemas, malformed arguments refused, unknown names unresolved, 17 volatile fields, full unregistration on dispose |
+| Real device | `pnpm run smoke` … | What only a machine with an SDK, an emulator and Gradle can prove: discovery, boot and teardown, screenshots, logcat, UI automation, and a real `android_create_app` → build → install → launch cycle |
+
+### Registry constraints that shape the tools
+
+Two constraints come from the real tool registry and cannot be seen through a
+hand-written test double:
+
+- A result must match the tool's declared `output.schema`, so the two listing
+  tools return `{ devices: [...] }` and `{ avds: [...] }` rather than a bare
+  array, which the registry rejects as invalid output.
+- A result must be lossless JSON, and the registry's snapshot rejects
+  `undefined` outright. Every ported provider models an absent field as
+  `undefined` — a device without a `model`, a UI node without `bounds`, a
+  discovery report with no Gradle root — so `toLosslessJson()` normalizes the
+  value on the single path every tool result travels, instead of 23 providers
+  each handling it.
+
+## Known limitations
+
+- Linux is unsupported, exactly as in the original; `android_preflight` reports
+  it.
+- `android_start_emulator` always starts a new emulator and never reuses one.
+  Pass `serial` to the other tools to reuse a target.
+- `android_create_avd` always answers `no` to `avdmanager`'s confirmation, so it
+  can never silently trigger a multi-gigabyte image download.
+- The settings page's installed-image list comes from scanning the SDK
+  directory, not from `sdkmanager --list_installed`, which fails in restricted
+  environments and prefixes its output with deprecation notices.
+- The settings page's two routes are served by the plugin and are mounted in a
+  real profile, but their HTTP responses cannot be exercised outside the GUI:
+  the desktop app authenticates every request, so a bare `curl` to
+  `/api/android-emulator-helper/status` answers `403 forbidden` before the
+  handler runs. `test/routes-integration.test.js` therefore invokes the handlers
+  directly on a real Cordis context instead. The page's spacing, dark theme and
+  narrow-width wrapping still deserve a human look in the GUI.
+- `@deepseek-ai/dsh-client-ui-primitives` publishes only `0.0.1-rc.1` on npm,
+  which does not match the runtime API, so the render test uses a faithful double
+  for the primitives while React and `react-dom/server` stay real.
+
+## Releases
+
+| Version | Highlights |
+|---|---|
+| **1.1.0** | Settings page rebuilt around cards with a sticky action bar; both timeouts asked for in seconds; eight defects fixed, among them a generated project that did not compile, `android_ui_type_text` corrupting every `%` into `%25`, `android_ui_describe` serving the previous screen after a failed dump, and `android_start_emulator` silently starting a different AVD than the one requested. All 23 tools were exercised on a real emulator. |
+| 1.0.0 | First release: the 23 native `android_*` tools, the embedded `android-dev` skill and the `/android-dev` command, and the settings page. |
+
+**Restart the DSH host process after upgrading.** The package is mounted as a
+`link:` symlink and Node caches ESM modules for the life of the process, so a
+change under `lib/` does not take effect until the host restarts — until then the
+tools keep serving the old code.
+
+## License
+
+[MIT](LICENSE), copyright (c) 2026 zhz8888.
+
+Tools and provider logic are ported from the ZCode official `android-emulator`
+plugin (also MIT, copyright Z.ai); the Kotlin/Compose project template files are
+kept verbatim. See the note at the end of [LICENSE](LICENSE) for the full
+provenance.

package/README.zh-CN.md

@@ -0,0 +1,232 @@
+# dsh-android-emulator-helper
+
+[English](README.md) | **简体中文**
+
+包名为 `@zhz8888/dsh-android-emulator-helper`，插件页显示的是本地化名称——英文 **Android Emulator**、中文 **Android 模拟器**——由 `locale/en.json` 与 `locale/zh.json` 提供，一句话描述也在其中。
+
+把 ZCode 官方 `android-emulator@0.1.0` 插件移植为 **DSH（DeepSeek Harness）原生插件**：原有 23 个 MCP 工具全部保留为 DSH 原生工具，并新增一个完整的 **设置页面**（设置 → Android 模拟器），让 SDK、模拟器、系统镜像、构建与输出目录等参数都能在应用里配置，而不是靠环境变量。
+
+- 工具名、参数名与原插件完全一致，为原 MCP 服务器写的工作流可直接迁移。
+- 设置项 = 原插件 `userConfig` 的 7 个字段 + 10 个实用扩展。
+- 设置页在「设置」侧栏新增一个独立分区，含分组表单、下拉与建议列表、内联校验、「检测环境」与「刷新设备与 AVD」按钮。
+
+## 目录
+
+- [安装](#安装)
+- [设置页面](#设置页面)
+- [工具清单](#工具清单)
+- [Skill 与斜杠命令](#skill-与斜杠命令)
+- [与原插件的差异](#与原插件的差异)
+- [架构](#架构)
+- [开发与验证](#开发与验证)
+- [已知限制](#已知限制)
+- [版本](#版本)
+- [许可](#许可)
+
+## 安装
+
+### 1. 先安装依赖
+
+包本身只发布源码与手写的客户端 bundle，运行依赖由 DSH profile 提供。
+
+```bash
+cd /path/to/dsh-android-emulator-helper
+pnpm install
+```
+
+本插件 import 的官方包 `@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/schemastery` **全部声明在 `peerDependencies`**，由宿主提供：profile 里本来就带着它们，解析到宿主那一份还能保证设置表单背后只有一个 `schemastery` 实例。上面的 `pnpm install` 只为开发与测试把它们装到本仓库。
+
+DSH 的兼容性闸门正是按 `peerDependencies` 里 `@deepseek-ai/dsh*` 的版本区间与运行时版本比对，不匹配会明确拒装。区间因此**只写下界**（`>=0.2.0-rc.2`）：写上界会在 DSH 每次升版时逼着插件重发一次放宽范围，而 `^` 区间会静默漏掉下一个版本元组的预发布版。
+
+### 2. 装进 profile
+
+**DSH Desktop（本机 GUI）**：`desktop` profile 由 Electron 应用独占管理，`dsh plugin --profile desktop` 会被 CLI 主动拒绝。请通过应用内的插件管理器安装：把本目录加入本机连接器/插件源，或使用插件管理器的「安装」入口指向本地目录。
+
+**CLI / 其他 profile**：
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-android-emulator-helper
+```
+
+`dsh.bundle.patch` 已声明，因此安装后 DSH 的 reconcile 会自动把本包追加到 `dsh.profile.bundles`，profile 启动时合并 `cordis.patch.yml`，挂载唯一一行 host 入口。**不要**再手动往 profile 自己的 `cordis.patch.yml` 里加同一行，重复挂载会让同名工具二次注册并在加载期报错。
+
+### 3. 打开设置页
+
+重启/热加载后，打开 **设置 → Android 模拟器**。页面在 host 半侧真正提供了该设置命名空间时才会出现；反之不会留下任何痕迹。
+
+## 设置页面
+
+设置命名空间 = profile patch 行 id = `android-emulator-helper`（同时是 `dsh.name`）。页面通过 `ctx.configForms` 读写，因此具备暂存编辑、脏值检测、内联校验、乐观并发（revision）与「已覆盖/恢复默认」语义。页面自绘标题、每个分组一张卡片（卡片边框就是分组之间的分隔），保存按钮位于底部悬浮胶囊操作栏，只在有可操作内容时出现：有暂存改动、正在写入，或一次失败值得重试。
+
+| 分组 | 设置项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|---|
+| SDK 与工具链 | `sdkPath` | 文本 | 空 | Android SDK 根目录；留空时探测 `ANDROID_HOME`、`ANDROID_SDK_ROOT` 与常见路径 |
+| | `jdkMajor` | 文本（建议来自本机 JDK） | `17` | JDK 主版本，用于预检与安装指引 |
+| | `buildToolsVersion` | 文本（建议来自已装 build-tools） | `35.0.0` | 安装指引引用的 build-tools 版本 |
+| 模拟器与设备 | `defaultAvd` | 文本（建议来自本机 AVD） | `medium_phone` | 需要启动模拟器时优先使用 |
+| | `defaultSerial` | 文本（建议来自已连接设备） | 空 | 优先使用的设备序列号 |
+| | `autoStartEmulator` | 开关 | 开 | 关闭后无可用设备时直接报错，不启动模拟器 |
+| | `emulatorArgs` | 多行文本 | 空 | 额外 `emulator` 参数，每行一个，`#` 为注释 |
+| | `bootTimeoutSeconds` | 整数 | `180` | 模拟器启动超时（秒） |
+| API 与系统镜像 | `apiLevel` | 文本（建议来自已装 platform/镜像） | `35` | `compileSdk` 与系统镜像包名使用的 API 级别 |
+| | `systemImageVariant` | 下拉 | `default` | `default` / `google_apis` / `google_apis_playstore` |
+| | `systemImageAbi` | 下拉 | 自动 | 留空按宿主架构，Apple Silicon 用 `arm64-v8a` |
+| | `minSdk` | 整数 | `23` | `android_create_app` 生成项目的默认 minSdk |
+| 构建 | `buildTimeoutSeconds` | 整数 | `600` | 单次 assemble 的最长运行时间（秒） |
+| | `gradleExtraArgs` | 多行文本 | 空 | 额外 Gradle 参数，每行一个 |
+| 输出目录与日志 | `dataDir` | 文本 | 空 | 截图与构建日志根目录；留空用 `$DSH_HOME/android-emulator-helper` |
+| | `screenshotDir` | 文本 | 空 | 截图目录；留空用 `<数据目录>/screenshots` |
+| | `logTailLines` | 整数 | `500` | `android_logs` 未指定行数时的默认行数 |
+
+页面底部两个按钮调用 host 半侧的两个精确 Fetch 路由：
+
+- **检测环境** → `GET /api/android-emulator-helper/status`，返回与 `android_preflight` 相同的检查结果，逐条显示状态、详情与修复建议。
+- **刷新设备与 AVD** → `GET /api/android-emulator-helper/inventory`，探测 SDK 根目录、AVD、已连接设备、已安装 JDK、已装系统镜像/platform/build-tools，用于填充上方字段的建议列表。
+
+### 兼容旧配置
+
+原插件的 7 个字段仍会回落到同名环境变量（`ANDROID_PLUGIN_SDK_PATH`、`ANDROID_PLUGIN_DEFAULT_AVD`、`ANDROID_PLUGIN_API_LEVEL`、`ANDROID_PLUGIN_BUILD_TOOLS_VERSION`、`ANDROID_PLUGIN_SYSTEM_IMAGE_VARIANT`、`ANDROID_PLUGIN_SYSTEM_IMAGE_ABI`、`ANDROID_PLUGIN_JDK_MAJOR`）。解析顺序为「设置页 → 环境变量 → 内置默认值」，所以已有 ZCode 或 CI 环境无需改动即可继续工作。
+
+## 工具清单
+
+23 个工具，名称与参数与原插件一致。
+
+| 工具 | 作用 |
+|---|---|
+| `android_preflight` | 检查 SDK、adb、emulator、AVD、Java、Gradle 项目状态与 UI 自动化后端，并回显当前设置 |
+| `android_discover_project` | 发现 Gradle 根、模块、variant、applicationId、manifest 与 APK 产物 |
+| `android_create_app` | 生成最小 Kotlin + Jetpack Compose 工程 |
+| `android_build_app` | 构建指定模块/variant |
+| `android_build_and_run` | 构建 → 复用或启动设备 → 安装 → 启动 |
+| `android_list_devices` | 列出 adb 可见设备 |
+| `android_list_avds` | 列出 AVD |
+| `android_start_emulator` | 启动新的 GUI 模拟器（从不复用已有设备） |
+| `android_stop_emulator` | 按序列号停止模拟器 |
+| `android_create_avd` | 用 `avdmanager` 创建 AVD |
+| `android_install_app` | 安装 APK |
+| `android_launch_app` | 按 applicationId 启动 |
+| `android_terminate_app` | 强制停止应用 |
+| `android_open_url` | 在设备上打开 URL |
+| `android_screenshot` | 截图并落盘；模型支持图像输入时同时返回图像 |
+| `android_logs` | 读取 logcat 尾部，可按 applicationId 过滤 |
+| `android_ui_status` | 报告 UI 自动化后端可用性 |
+| `android_ui_describe` | 返回 UI Automator 元素树 |
+| `android_ui_resolve` | 按文本/描述/资源 id/类名解析到坐标 |
+| `android_ui_tap` | 坐标点击 |
+| `android_ui_swipe` | 坐标滑动 |
+| `android_ui_type_text` | 向聚焦控件输入文本 |
+| `android_ui_keyevent` | 发送 `BACK`/`HOME`/`ENTER`/`APP_SWITCH`/`MENU`/`SEARCH` |
+
+`android_screenshot` 的行为值得单独说明：PNG 总会写到磁盘（默认在数据目录的 `screenshots/` 下），同时尝试把图像提交给宿主的附件服务以获得规范的图像块。当前模型未声明图像输入、或部署没有附件服务时，结果会退化为纯文本并附上文件路径，而不会让整次调用失败。
+
+## Skill 与斜杠命令
+
+- **`android-dev` skill**：随包提供（`skills/android-dev/`），host 半侧通过 `ctx.skills.register()` 注册为嵌入式 skill，并把 skill 目录作为 `resourceBase`，因此 `INSTALL_ENVIRONMENT.md` 的相对引用照旧可用。内容已按 DSH 改写：不再有 `mcp__...` 前缀，环境配置指向设置页而非环境变量，并补充了设置页使用说明。
+- **`/android-dev [目标]` 命令**：通过 `ctx.commands.register()` 注册。DSH 的用户命令刻意不产生模型消息，因此该命令做一件不依赖模型的事——跑一遍环境诊断，输出结论、失败项与修复建议，并给出下一步提示。
+
+## 与原插件的差异
+
+| 方面 | 原插件（ZCode） | 本插件（DSH） |
+|---|---|---|
+| 工具暴露 | stdio MCP 服务器 `android-emulator`，模型看到 `mcp__android_emulator__*` | 原生 `ctx.tools.register()`，模型看到 `android_*` |
+| 用户配置 | `plugin.json` 的 `userConfig`，经 `ANDROID_PLUGIN_*` 注入 | 设置页 + schemastery `Config`，字段全部 `.volatile()` 实时生效；环境变量仍作回落 |
+| 工作目录 | `process.cwd()` | `exec.agent.session.header.cwd`（会话工作区） |
+| 数据目录 | `ANDROID_PLUGIN_DATA` / 临时目录 | `$DSH_HOME/android-emulator-helper`，可配置 |
+| 截图返回 | MCP image content（base64） | host 附件引用生成的图像块，失败时退化为文本 |
+| 斜杠命令 | 注入一段提示词给模型 | 直接运行诊断并输出结论 |
+| 进程调用 | `node:child_process` 直接 spawn | 保持一致 |
+
+保留直接 spawn 是有意的取舍：这样 `gradlew`、`adb`、`emulator` 的行为与原插件逐字节一致，且不必为 `adb exec-out` 的二进制流另写一层适配。代价是绕过了 DSH 的 subprocess seam——没有统一的过程管理、环境变量清洗、输出 spill 与卸载期终止。本插件的每个外部调用都有显式 timeout 与 `SIGTERM`，且不读写任何凭据环境变量。
+
+## 架构
+
+```
+dsh-android-emulator-helper/
+├── package.json            # dsh.bundle.patch、dsh.client、peer 依赖（兼容性闸门）
+├── cordis.patch.yml        # - insert: [{ id: android-emulator-helper, name: '@zhz8888/dsh-android-emulator-helper' }]
+├── icon.svg                # 插件图标：Android 机器人头部，品牌绿，明暗主题下都可辨认
+├── locale/en.json          # 插件页的显示名与描述（英文；它的存在才是其它语言文件生效的开关）
+├── locale/zh.json          # 简体中文那一份
+├── lib/
+│   ├── index.js            # host 半侧：注册工具 / skill / 命令 / 两个 Fetch 路由
+│   ├── client.js           # browser 半侧：__ModuleLoader__ 手写 bundle，设置页
+│   ├── settings.js         # 字段声明、schemastery Config（全部 .volatile()）、实时读取
+│   ├── runtime.js          # 每次调用构造 runtime（会话 cwd + 实时设置 → 数据目录）
+│   ├── tools/index.js      # 23 个 defineTool 定义、参数/结果 schema、图像准入
+│   ├── providers/          # 从原插件逐文件移植，改为显式接收 runtime
+│   └── util/               # 进程执行、路径、内容块
+├── skills/android-dev/     # SKILL.md + INSTALL_ENVIRONMENT.md
+├── scripts/                # check-bundle.mjs（一致性闸门）、smoke.mjs（真机集成）
+└── test/                   # node:test 单元与集成测试
+```
+
+三个关键约束决定了上面的形状：
+
+1. **设置命名空间只有一个真相来源**：profile patch 行 id。`cordis.patch.yml` 的 `id`、`lib/settings.js` 的 `SETTINGS_NAMESPACE`、`lib/client.js` 的字面量必须一致；`scripts/check-bundle.mjs` 会校验它们，也会校验 host 与 client 两份字段表无漂移。
+2. **browser bundle 不能 import host 模块**（客户端纯度闸门禁止跨插件值导入），因此字段表被写了两遍，靠闸门保持一致；bundle 只能 `require` 宿主的 9 个静态模块（React、Cordis、`dsh-client-store`、`dsh-client-ui-slots`、`dsh-client-ui-primitives`、`dsh-client-ui-dockkit` 等）。
+3. **插件页的名字是包内资源，不是 manifest 字段**：DSH 通过 `exports` 解析 `<包名>/locale/en.json`，所以 `./locale/*.json` 必须保持导出、`locale` 必须留在 `files` 里；任一处缺失都会静默退化成显示原始包名。`en.json` 同时是其它语言文件的开关，因此不能只留 `zh.json`。这三条都由 `test/manifest.test.js` 钉住。
+
+## 开发与验证
+
+```bash
+pnpm install                 # 装官方 peer 包与 react/react-dom（开发与测试用）
+pnpm test                    # 145 个测试（无需 Android SDK）
+pnpm run check               # 测试 + host/client 一致性闸门 + 真实 Cordis 挂载验证
+pnpm run verify:mount        # 真实 Cordis Context + 真实 ToolRuntime 注册表
+pnpm run smoke               # 只读真机探测：preflight / AVD / 设备 / 项目发现 / inventory
+pnpm run smoke:emulator      # 额外：启动模拟器 → 截图 → 读日志 → 停止
+pnpm run link:dsh-deps       # 离线开发：把本机 DSH 的 @deepseek-ai 包软链进 node_modules
+```
+
+### 四层验证
+
+| 层 | 命令 | 证明了什么 |
+|---|---|---|
+| 单元 / 解析器 | `pnpm test` | 客户端 bundle 加载契约与静态模块约束、manifest 与 patch 契约、设置投影（volatile 实时读取、环境变量回落、越界回落）、移植过来的解析器（`adb devices`、`emulator -list-avds`、UI Automator XML、`input text` 转义、APK 选择、JDK 主版本归一、无损 JSON 归一） |
+| 设置页渲染 | `pnpm test`（`client-render.test.js`） | 用真实 React + `react-dom/server` 渲染整个设置页：分组/字段/字典键完整、受控输入带真实值、开关与下拉状态正确、「已覆盖/恢复默认」、两个按钮齐全、无未解析字典键，且没有暂存改动时不出现操作栏 |
+| 一致性闸门 | `scripts/check-bundle.mjs` | bundle id = 包名、命名空间 = patch 行 id、host 与 client 两份字段表与分组表逐键逐序一致、每个标题/提示/占位符/选项在**两种语言下都逐字一致**、两个路由两侧一致、`locale/*.json` 两种语言键集相同、bundle 仍是经典脚本 |
+| 路由集成 | `test/routes-integration.test.js` | 在**真实** Cordis `Context` 上挂载两条设置路由：真正调用 handler 并读取其 `Response`、17 个字段都以 volatile 引用形式到达、保存的设置对下一次调用立即可见、handler 出错时返回 `500` JSON 体而不是抛出、缺少可选服务时仍能挂载、dispose 后两条路由都被移除 |
+| 真实宿主挂载 | `scripts/verify-mount.mjs` | 在**真实** Cordis `Context` + **真实** `ToolRuntime` 上挂载：23 个工具注册成功、**23 个工具全部经注册表实际派发**并通过参数/结果 schema 校验、错误参数被注册表拒绝、未知工具名不解析、17 个设置字段全部 volatile、dispose 后工具全部注销 |
+| 真机 | `pnpm run smoke`… | 只有带 SDK、模拟器与 Gradle 的机器才能证明的部分：发现、启动与停止、截图、logcat、UI 自动化，以及真实的 `android_create_app` → 构建 → 安装 → 启动闭环 |
+
+`pnpm run smoke` 覆盖只有真机才能证明的部分：SDK 发现、`adb`/`emulator` 实际调用、环境拼装、设置投影真正喂给 provider。
+`pnpm run smoke:emulator` 进一步覆盖启动模拟器 → 截图 → 读日志 → 停止的完整链路。
+
+### 注册表给工具层带来的两条约束
+
+这两条约束来自真实工具注册表，手写的测试替身看不到：
+
+- 结果必须匹配工具声明的 `output.schema`，因此两个列表工具返回
+  `{ devices: [...] }` 与 `{ avds: [...] }`，而不是裸数组——注册表会以
+  invalid output 拒绝裸数组。
+- 结果必须是无损 JSON，注册表的快照会直接拒绝 `undefined`。而移植过来的
+  provider 一律用 `undefined` 表示缺失字段（设备没有 `model`、UI 节点没有
+  `bounds`、发现结果没有 Gradle 根），因此在所有工具结果唯一的必经路径上用
+  `toLosslessJson()` 统一归一，而不是在 23 个 provider 里各处理一遍。
+
+## 已知限制
+
+- **Linux 不支持**，与原插件一致；`android_preflight` 会将其标记为不支持的宿主。
+- `android_start_emulator` 永远启动新模拟器，从不复用已有目标（原插件语义）。复用请把 `serial` 传给其他工具。
+- `android_create_avd` 对 `avdmanager` 的确认提示固定回答 `no`，绝不静默触发数 GB 的镜像下载；需要先自行 `sdkmanager --install`。
+- UI 自动化依赖设备端 `uiautomator`；失败时 `android_ui_status` 会报告不可用，构建/运行/截图链路不受影响。
+- 设置页的「已安装系统镜像」列表来自 SDK 目录扫描，而不是 `sdkmanager --list_installed`（后者在受限环境下会因创建 bin 目录失败，且输出含大量弃用提示）。
+- 设置页的两条路由由插件提供、并在真实 profile 中挂载，但它们的 HTTP 响应无法在 GUI 之外验证：桌面端对每个请求做鉴权，未带浏览器会话的 `curl` 访问 `/api/android-emulator-helper/status` 会在进入 handler 之前就返回 `403 forbidden`。因此 `test/routes-integration.test.js` 改为在真实 Cordis context 上直接调用 handler。设置页的间距、暗色主题与窄屏换行仍建议在 GUI 中人工核对一次。
+- `@deepseek-ai/dsh-client-ui-primitives` 在 npm 上只有 `0.0.1-rc.1`，与运行时 API 不一致；因此设置页渲染测试对 primitives 使用了忠实替身，真实 React 与 `react-dom/server` 仍是真件。
+- 插件不触碰凭据：不读取、不转发任何含 key/token/secret 的环境变量。
+
+## 版本
+
+| 版本 | 要点 |
+|---|---|
+| **1.1.0** | 设置页按卡片重做并加底部粘性操作栏；两处超时改为按秒填写；修复 8 个缺陷，其中包含生成的新工程编译不过、`android_ui_type_text` 把每个 `%` 变成 `%25`、`android_ui_describe` 在 dump 失败时返回上一屏、`android_start_emulator` 传入不存在的 AVD 名却静默启动另一个模拟器。23 个工具全部在真机上实测过。 |
+| 1.0.0 | 首个版本：23 个原生 `android_*` 工具、内置 `android-dev` skill 与 `/android-dev` 命令，以及设置页。 |
+
+**升级后请重启 DSH 宿主进程。** 本包以 `link:` 软链挂载，Node 对 ESM 做进程级缓存，`lib/` 的改动在宿主重启前不会生效——否则工具仍会跑旧代码。
+
+## 许可
+
+[MIT](LICENSE)，版权所有 (c) 2026 zhz8888。
+
+工具与 provider 逻辑移植自 ZCode 官方 `android-emulator` 插件（同样以 MIT 分发，
+版权归 Z.ai），Kotlin/Compose 工程模板逐字保留；完整的来源说明见 [LICENSE](LICENSE) 末尾。

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# dsh bundle patch for @zhz8888/dsh-android-emulator-helper.
+#
+# This file is the `dsh.bundle.patch` layer of the package. Installing the
+# plugin through the official CLI —
+#
+#   dsh plugin --profile <name> add @zhz8888/dsh-android-emulator-helper
+#
+# — reconciles `dsh.profile.bundles` against the installed packages and, seeing
+# this declaration, appends this package to the bundle stack. Profile boot then
+# merges THIS patch, which mounts exactly one host row.
+#
+# The row id doubles as the settings namespace: `@deepseek-ai/dsh-settings`
+# keys every editable form by the profile entry id, and the browser half
+# watches that same id through `ctx.configForms.whileServed([...])`. Renaming
+# the id here therefore requires renaming `SETTINGS_NAMESPACE` in
+# `lib/settings.js` and `lib/client.js` together.
+#
+# Mounting this package twice (for example by adding the row to the profile's
+# own cordis.patch.yml while the bundle channel is also active) registers the
+# same tool names twice and fails loudly at the loader. Use one channel only.
+- insert:
+    - id: android-emulator-helper
+      name: '@zhz8888/dsh-android-emulator-helper'

package/icon.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="20 199 985 627" width="985" height="627" role="img">
+  <title>Android emulator helper</title>
+  <!--
+    The Android robot head, from the artwork supplied as `android.svg`, at its
+    original `#2c2c2c`.
+
+    DSH renders `package.json.icon` as an <img> whose src is a base64 data URL, so
+    the SVG is an isolated document: it cannot see the host page's
+    `body[data-ds-dark-theme]`, and `currentColor` would resolve to black. It can,
+    however, see `prefers-color-scheme`, and that is the exact lever we need — DSH
+    Desktop pushes the user's theme preference into Electron as
+    `nativeTheme.themeSource = spec.readThemeSource()` (electron-runtime), and
+    `themeSource` is precisely what drives `prefers-color-scheme` in every renderer
+    frame. Light / dark / system therefore all agree between the app chrome and
+    this image, and the fill below inverts with the theme.
+
+    `#d3d3d3` is the exact RGB inversion of `#2c2c2c` (255 - 44 = 211), which also
+    happens to balance the pair: 13.97:1 against the light background `#ffffff`
+    and 11.98:1 against the dark one `#151517`.
+
+    The fill also sits on the element as a presentation attribute, so a renderer
+    without CSS support (an SVG-to-PNG pipeline, a strict validator) still draws
+    the light-theme colour instead of nothing. Presentation attributes lose to any
+    CSS rule, which is what lets the media query override it.
+  -->
+  <style>
+    path { fill: #2c2c2c; }
+    @media (prefers-color-scheme: dark) {
+      path { fill: #d3d3d3; }
+    }
+  </style>
+  <path fill="#2c2c2c" d="M805.664 239.21c15.194 8.676 20.578 27.92 12.181 43.195l-0.258 0.462-70.477 123.435c121.382 72.426 206.947 199.48 221.734 348.54C970.712 773.67 955.922 790 937 790H88c-18.922 0-33.712-16.33-31.844-35.16 14.14-142.538 93.003-264.954 206.014-338.722L186.09 282.867c-8.763-15.348-3.425-34.893 11.923-43.656 15.194-8.676 34.502-3.53 43.39 11.465l0.266 0.457 76.406 133.822c59.16-27.753 125.102-43.216 194.427-43.216 62.75 0 122.73 12.67 177.416 35.655l72.09-126.26c8.764-15.348 28.31-20.686 43.657-11.923zM512.5 405.74c-191.04 0-352.265 136.52-387.48 319.779l-0.089 0.481h775.135l-0.088-0.481c-34.84-181.31-193.023-316.87-381.391-319.734zM320.53 565.87c23.56 0 42.66 19.115 42.66 42.695 0 23.58-19.1 42.696-42.66 42.696-23.561 0-42.66-19.116-42.66-42.696s19.099-42.695 42.66-42.695z m383.946 0c23.56 0 42.66 19.115 42.66 42.695 0 23.58-19.1 42.696-42.66 42.696-23.56 0-42.66-19.116-42.66-42.696s19.1-42.695 42.66-42.695z"/>
+</svg>