diff --git a/apps/site/docs/en/android-api-reference.mdx b/apps/site/docs/en/android-api-reference.mdx
deleted file mode 100644
index f82882f8fd..0000000000
--- a/apps/site/docs/en/android-api-reference.mdx
+++ /dev/null
@@ -1,238 +0,0 @@
-# API reference (Android)
-
-Use this doc when you need to customize Midscene's Android automation or review Android-only constructor options. For shared parameters (reporting, hooks, caching, etc.), see the platform-agnostic [API reference (Common)](./api).
-
-## Action Space
-
-`AndroidDevice` uses the following action space; the Midscene Agent can use these actions while planning tasks:
-
-- `Tap` — Tap an element.
-- `DoubleClick` — Double-tap an element.
-- `Input` — Enter text with `replace`/`typeOnly`/`clear` modes (`append` is a deprecated alias for `typeOnly`). Supports optional `autoDismissKeyboard` parameter.
-- `Scroll` — Scroll from an element or screen center in any direction, with helpers to reach the top, bottom, left, or right.
-- `DragAndDrop` — Drag from one element to another.
-- `KeyboardPress` — Press a specified key.
-- `LongPress` — Long-press a target element with optional duration.
-- `PullGesture` — Pull up or down (e.g., to refresh) with optional distance and duration.
-- `Pinch` &mdash; Two-finger pinch gesture. Use `scale > 1` to zoom in, `scale < 1` to zoom out.
-- `ClearInput` &mdash; Clear the contents of an input field.
-- `Launch` &mdash; Open a web URL or `package/.Activity` string.
-- `Terminate` &mdash; Force-stop an app by package name.
-- `RunAdbShell` &mdash; Execute raw `adb shell` commands.
-- `AndroidBackButton` &mdash; Trigger the system back action.
-- `AndroidHomeButton` &mdash; Return to the home screen.
-- `AndroidRecentAppsButton` &mdash; Open the multitasking/recent apps view.
-
-## AndroidDevice {#androiddevice}
-
-Create a connection to an adb-managed device that an AndroidAgent can drive.
-
-### Import
-
-```ts
-import { AndroidDevice, getConnectedDevices } from '@midscene/android';
-```
-
-### Constructor
-
-```ts
-const device = new AndroidDevice(deviceId, {
-  // device options...
-});
-```
-
-### Device options
-
-- `deviceId: string` &mdash; Value returned by `adb devices` or `getConnectedDevices()`.
-- `autoDismissKeyboard?: boolean` &mdash; Automatically hide the keyboard after input. Default `true`.
-- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` &mdash; Order for dismissing keyboards. Default `'esc-first'`.
-- `androidAdbPath?: string` &mdash; Custom path to the adb executable.
-- `remoteAdbHost?: string` / `remoteAdbPort?: number` &mdash; Point to a remote adb server.
-- `imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii'` &mdash; Choose when to invoke [yadb](https://github.com/ysbing/YADB) for text input. Default `'yadb-for-non-ascii'`.
-  - `'yadb-for-non-ascii'` (default) &mdash; Uses yadb for Unicode characters (including Latin Unicode like ö, é, ñ), Chinese, Japanese, and format specifiers (like %s, %d). Pure ASCII text uses the faster native `adb input text`.
-  - `'always-yadb'` &mdash; Always uses yadb for all text input, providing maximum compatibility but slightly slower for pure ASCII text.
-- `displayId?: number` &mdash; Target a specific virtual display if the device mirrors multiple displays.
-- `screenshotResizeScale?: number` &mdash; **Deprecated.** This option has been removed and no longer has any effect. Use `screenshotShrinkFactor` in `AgentOpt` instead to control screenshot size sent to the AI model.
-- `minScreenshotBufferSize?: number` &mdash; Screenshot buffer size validation threshold in bytes. Buffers below this value are treated as failed or corrupted captures. Default `1024` (1KB). Set to `0` to skip only this size check; Midscene still rejects empty buffers and invalid image formats.
-- `alwaysRefreshScreenInfo?: boolean` &mdash; Re-query rotation and screen size every step. Default `false`.
-- `scrcpyConfig?: object` &mdash; Scrcpy high-performance screenshot configuration, disabled by default. See [Scrcpy Screenshot Mode](#scrcpy) below.
-
-### Scrcpy Screenshot Mode {#scrcpy}
-
-By default, Midscene captures screenshots via `adb shell screencap`, which takes ~500–2000ms per call. Enabling Scrcpy mode streams H.264 video from the device and captures frames in real time, reducing screenshot latency to approximately **100–200ms**.
-
-**How to enable:**
-
-```ts
-const device = new AndroidDevice(deviceId, {
-  scrcpyConfig: {
-    enabled: true,
-  },
-});
-```
-
-**Optional parameters:**
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `enabled` | `boolean` | `false` | Enable Scrcpy screenshots |
-| `maxSize` | `number` | `0` | Max video dimension (width or height). `0` = no scaling |
-| `videoBitRate` | `number` | `2000000` | H.264 encoding bitrate (bps) |
-| `idleTimeoutMs` | `number` | `30000` | Auto-disconnect after idle (ms). Set to `0` to disable |
-
-:::tip
-Scrcpy mode automatically falls back to ADB screenshots if the connection fails. No extra error handling is needed.
-:::
-
-### Usage notes
-
-- Discover devices with `getConnectedDevices()`; the `udid` matches `adb devices`.
-- Supports remote adb via `remoteAdbHost/remoteAdbPort`; set `androidAdbPath` if adb is not on PATH.
-- Use `screenshotShrinkFactor` in `AgentOpt` to cut latency on high-DPI devices.
-
-### Examples
-
-#### Quick start
-
-```ts
-import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';
-
-const [first] = await getConnectedDevices();
-const device = new AndroidDevice(first.udid);
-await device.connect();
-
-const agent = new AndroidAgent(device, {
-  aiActionContext: 'If a permissions dialog appears, accept it.',
-});
-
-await agent.launch('https://www.ebay.com');
-await agent.aiAct('search "Headphones" and wait for results');
-const items = await agent.aiQuery(
-  '{itemTitle: string, price: number}[], find item in list and corresponding price',
-);
-console.log(items);
-```
-
-#### Launch native packages
-
-```ts
-await agent.launch('com.android.settings/.Settings');
-await agent.back();
-await agent.home();
-```
-
-## AndroidAgent {#androidagent}
-
-Wire Midscene's AI planner to an AndroidDevice for UI automation.
-
-### Import
-
-```ts
-import { AndroidAgent } from '@midscene/android';
-```
-
-### Constructor
-
-```ts
-const agent = new AndroidAgent(device, {
-  // common agent options...
-});
-```
-
-### Android-specific options
-
-- `customActions?: DeviceAction[]` &mdash; Extend planning with actions defined via `defineAction`.
-- `appNameMapping?: Record<string, string>` &mdash; Map friendly app names to package names. When you pass an app name to `launch(target)`, the agent will look up the package name in this mapping. If no mapping is found, it will attempt to launch `target` as-is. User-provided mappings take precedence over default mappings.
-- All other fields match [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, and more.
-
-### Usage notes
-
-:::info
-
-- Use one agent per device connection.
-- Android-only helpers such as `launch`, `terminate`, and `runAdbShell` are also exposed in YAML scripts. See [Android platform-specific actions](./automate-with-scripts-in-yaml#the-android-part).
-- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
-
-:::
-
-### Android-specific methods
-
-#### `agent.launch()`
-
-Launch a web URL or native Android activity/package.
-
-```ts
-function launch(target: string): Promise<void>;
-```
-
-- `target: string` &mdash; Can be a web URL, a string in `package/.Activity` format (e.g., `com.android.settings/.Settings`), an app package name, or an app name. If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped package name; otherwise, `target` will be launched as-is.
-
-#### `agent.runAdbShell()`
-
-Run a raw `adb shell` command through the connected device. Pass only the shell command itself, without the `adb shell` prefix.
-
-```ts
-function runAdbShell(command: string, opt?: { timeout?: number }): Promise<string>;
-```
-
-- `command: string` &mdash; Command passed verbatim to `adb shell`. For example, use `input tap 100 200`, not `adb shell input tap 100 200`.
-- `opt.timeout?: number` &mdash; Optional command execution timeout in milliseconds.
-
-```ts
-const result = await agent.runAdbShell('dumpsys battery', { timeout: 60 * 1000 });
-console.log(result);
-
-await agent.runAdbShell('input tap 100 200');
-```
-
-#### `agent.terminate()`
-
-Terminate (force-stop) a running Android app.
-
-```ts
-function terminate(uri: string): Promise<void>;
-```
-
-- `uri: string` &mdash; Package name, app name in `appNameMapping`, or `package/.Activity` (only the package part is used).
-
-```ts
-await agent.terminate('com.android.settings');
-```
-
-#### Navigation helpers
-
-- `agent.back(): Promise<void>` &mdash; Trigger the Android system Back action.
-- `agent.home(): Promise<void>` &mdash; Return to the launcher.
-- `agent.recentApps(): Promise<void>` &mdash; Open the Recents/Overview screen.
-
-### Helper utilities
-
-#### `agentFromAdbDevice()`
-
-Create an `AndroidAgent` from any connected adb device.
-
-```ts
-function agentFromAdbDevice(
-  deviceId?: string,
-  opts?: PageAgentOpt & AndroidDeviceOpt,
-): Promise<AndroidAgent>;
-```
-
-- `deviceId?: string` &mdash; Connect to a specific device; omitted means “first available”.
-- `opts?: PageAgentOpt & AndroidDeviceOpt` &mdash; Combine agent options with [AndroidDevice](#androiddevice) settings.
-
-#### `getConnectedDevices()`
-
-Enumerate adb devices Midscene can drive.
-
-```ts
-function getConnectedDevices(): Promise<Array<{
-  udid: string;
-  state: string;
-  port?: number;
-}>>;
-```
-
-### See also
-
-- [Android getting started](./android-getting-started) for setup and scripting steps.
diff --git a/apps/site/docs/en/android-introduction.mdx b/apps/site/docs/en/android-introduction.mdx
deleted file mode 100644
index cc9c61d07e..0000000000
--- a/apps/site/docs/en/android-introduction.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
-import StartExperience from './common/start-experience.mdx';
-import ShowcaseAndroid from './showcases-android.mdx';
-
-# Android Automation Support
-
-Midscene can drive adb tools to support Android automation.
-
-By adapting a visual model solution, the automation process works with any app tech stack—whether built with Native, Flutter, React Native, or Lynx. Developers only need to focus on the final experience when debugging UI automation scripts.
-
-The Android UI automation solution comes with all the features of Midscene:
-
-- Supports zero-code trial using Playground.
-- Supports JavaScript SDK.
-- Supports automation scripts in YAML format and command-line tools.
-- Supports HTML reports to replay all operation paths.
-
-## Showcases
-
-<ShowcaseAndroid />
-
-See more showcases: [showcases](./showcases.mdx)
-
-## Try Midscene Playground on Android
-
-With Midscene.js playground, you can experience Android automation capabilities without writing any code.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/booking2.mp4" controls/>
-
-See [Getting Started](./android-getting-started#try-playground-no-code) to learn how to launch the Playground.
-
-## Next Steps
-
-* [Getting Started](./android-getting-started)
-* [Use JavaScript SDK](./android-getting-started)
-* [Use YAML format automation scripts](./automate-with-scripts-in-yaml) and [command-line tools](./automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/en/android-getting-started.mdx b/apps/site/docs/en/android.mdx
similarity index 56%
rename from apps/site/docs/en/android-getting-started.mdx
rename to apps/site/docs/en/android.mdx
index 778978bba5..d731634916 100644
--- a/apps/site/docs/en/android-getting-started.mdx
+++ b/apps/site/docs/en/android.mdx
@@ -1,9 +1,18 @@
 import StartExperience from './common/start-experience.mdx';
+import ShowcaseAndroid from './showcases-android.mdx';
 import SetupEnv from './common/setup-env.mdx';
 
 import { PackageManagerTabs } from '@theme';
 
-# Android Getting Started
+# Android Automation Support
+
+Midscene can drive adb tools to support Android automation.
+
+## Showcases
+
+<ShowcaseAndroid />
+
+See more showcases: [showcases](./showcases.mdx)
 
 This guide walks you through everything required to automate an Android device with Midscene: connect a real phone over adb, configure model credentials, try the no-code Playground, and run your first JavaScript script.
 
@@ -151,7 +160,7 @@ Successful runs print `Midscene - report file updated: /path/to/report/some_id.h
 
 ## Advanced
 
-Use this section when you need to customize device behavior, wire Midscene into your framework, or troubleshoot adb issues. For detailed constructor parameters, jump to the [API reference(Android)](./android-api-reference).
+Use this section when you need to customize device behavior, wire Midscene into your framework, or troubleshoot adb issues. For detailed constructor parameters, jump to the [API reference(Android)](#api-reference).
 
 ### Extend Midscene on Android
 
@@ -192,7 +201,7 @@ See [Integrate with any interface](./integrate-with-any-interface#define-a-custo
 ## More
 
 - For every Agent method, check the [API reference (Common)](./api#interaction-methods).
-- For the Android API reference, see [Android Agent API](./android-api-reference).
+- For the Android API reference, see [Android Agent API](#api-reference).
 - Demo projects
   - Android JavaScript SDK demo: [https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo)
   - Android + Vitest demo: [https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo)
@@ -394,3 +403,238 @@ const device = new AndroidDevice('s4ey59', {
   remoteAdbPort: 5037,
 });
 ```
+
+## API reference {#api-reference}
+
+Use this doc when you need to customize Midscene's Android automation or review Android-only constructor options. For shared parameters (reporting, hooks, caching, etc.), see the platform-agnostic [API reference (Common)](./api).
+
+### Action Space
+
+`AndroidDevice` uses the following action space; the Midscene Agent can use these actions while planning tasks:
+
+- `Tap` &mdash; Tap an element.
+- `DoubleClick` &mdash; Double-tap an element.
+- `Input` &mdash; Enter text with `replace`/`typeOnly`/`clear` modes (`append` is a deprecated alias for `typeOnly`). Supports optional `autoDismissKeyboard` parameter.
+- `Scroll` &mdash; Scroll from an element or screen center in any direction, with helpers to reach the top, bottom, left, or right.
+- `DragAndDrop` &mdash; Drag from one element to another.
+- `KeyboardPress` &mdash; Press a specified key.
+- `LongPress` &mdash; Long-press a target element with optional duration.
+- `PullGesture` &mdash; Pull up or down (e.g., to refresh) with optional distance and duration.
+- `Pinch` &mdash; Two-finger pinch gesture. Use `scale > 1` to zoom in, `scale < 1` to zoom out.
+- `ClearInput` &mdash; Clear the contents of an input field.
+- `Launch` &mdash; Open a web URL or `package/.Activity` string.
+- `Terminate` &mdash; Force-stop an app by package name.
+- `RunAdbShell` &mdash; Execute raw `adb shell` commands.
+- `AndroidBackButton` &mdash; Trigger the system back action.
+- `AndroidHomeButton` &mdash; Return to the home screen.
+- `AndroidRecentAppsButton` &mdash; Open the multitasking/recent apps view.
+
+### AndroidDevice {#androiddevice}
+
+Create a connection to an adb-managed device that an AndroidAgent can drive.
+
+#### Import
+
+```ts
+import { AndroidDevice, getConnectedDevices } from '@midscene/android';
+```
+
+#### Constructor
+
+```ts
+const device = new AndroidDevice(deviceId, {
+  // device options...
+});
+```
+
+#### Device options
+
+- `deviceId: string` &mdash; Value returned by `adb devices` or `getConnectedDevices()`.
+- `autoDismissKeyboard?: boolean` &mdash; Automatically hide the keyboard after input. Default `true`.
+- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` &mdash; Order for dismissing keyboards. Default `'esc-first'`.
+- `androidAdbPath?: string` &mdash; Custom path to the adb executable.
+- `remoteAdbHost?: string` / `remoteAdbPort?: number` &mdash; Point to a remote adb server.
+- `imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii'` &mdash; Choose when to invoke [yadb](https://github.com/ysbing/YADB) for text input. Default `'yadb-for-non-ascii'`.
+  - `'yadb-for-non-ascii'` (default) &mdash; Uses yadb for Unicode characters (including Latin Unicode like ö, é, ñ), Chinese, Japanese, and format specifiers (like %s, %d). Pure ASCII text uses the faster native `adb input text`.
+  - `'always-yadb'` &mdash; Always uses yadb for all text input, providing maximum compatibility but slightly slower for pure ASCII text.
+- `displayId?: number` &mdash; Target a specific virtual display if the device mirrors multiple displays.
+- `screenshotResizeScale?: number` &mdash; **Deprecated.** This option has been removed and no longer has any effect. Use `screenshotShrinkFactor` in `AgentOpt` instead to control screenshot size sent to the AI model.
+- `minScreenshotBufferSize?: number` &mdash; Screenshot buffer size validation threshold in bytes. Buffers below this value are treated as failed or corrupted captures. Default `1024` (1KB). Set to `0` to skip only this size check; Midscene still rejects empty buffers and invalid image formats.
+- `alwaysRefreshScreenInfo?: boolean` &mdash; Re-query rotation and screen size every step. Default `false`.
+- `scrcpyConfig?: object` &mdash; Scrcpy high-performance screenshot configuration, disabled by default. See [Scrcpy Screenshot Mode](#scrcpy) below.
+
+#### Scrcpy Screenshot Mode {#scrcpy}
+
+By default, Midscene captures screenshots via `adb shell screencap`, which takes ~500–2000ms per call. Enabling Scrcpy mode streams H.264 video from the device and captures frames in real time, reducing screenshot latency to approximately **100–200ms**.
+
+**How to enable:**
+
+```ts
+const device = new AndroidDevice(deviceId, {
+  scrcpyConfig: {
+    enabled: true,
+  },
+});
+```
+
+**Optional parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable Scrcpy screenshots |
+| `maxSize` | `number` | `0` | Max video dimension (width or height). `0` = no scaling |
+| `videoBitRate` | `number` | `2000000` | H.264 encoding bitrate (bps) |
+| `idleTimeoutMs` | `number` | `30000` | Auto-disconnect after idle (ms). Set to `0` to disable |
+
+:::tip
+Scrcpy mode automatically falls back to ADB screenshots if the connection fails. No extra error handling is needed.
+:::
+
+#### Usage notes
+
+- Discover devices with `getConnectedDevices()`; the `udid` matches `adb devices`.
+- Supports remote adb via `remoteAdbHost/remoteAdbPort`; set `androidAdbPath` if adb is not on PATH.
+- Use `screenshotShrinkFactor` in `AgentOpt` to cut latency on high-DPI devices.
+
+#### Examples
+
+##### Quick start
+
+```ts
+import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';
+
+const [first] = await getConnectedDevices();
+const device = new AndroidDevice(first.udid);
+await device.connect();
+
+const agent = new AndroidAgent(device, {
+  aiActionContext: 'If a permissions dialog appears, accept it.',
+});
+
+await agent.launch('https://www.ebay.com');
+await agent.aiAct('search "Headphones" and wait for results');
+const items = await agent.aiQuery(
+  '{itemTitle: string, price: number}[], find item in list and corresponding price',
+);
+console.log(items);
+```
+
+##### Launch native packages
+
+```ts
+await agent.launch('com.android.settings/.Settings');
+await agent.back();
+await agent.home();
+```
+
+### AndroidAgent {#androidagent}
+
+Wire Midscene's AI planner to an AndroidDevice for UI automation.
+
+#### Import
+
+```ts
+import { AndroidAgent } from '@midscene/android';
+```
+
+#### Constructor
+
+```ts
+const agent = new AndroidAgent(device, {
+  // common agent options...
+});
+```
+
+#### Android-specific options
+
+- `customActions?: DeviceAction[]` &mdash; Extend planning with actions defined via `defineAction`.
+- `appNameMapping?: Record<string, string>` &mdash; Map friendly app names to package names. When you pass an app name to `launch(target)`, the agent will look up the package name in this mapping. If no mapping is found, it will attempt to launch `target` as-is. User-provided mappings take precedence over default mappings.
+- All other fields match [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, and more.
+
+#### Usage notes
+
+:::info
+
+- Use one agent per device connection.
+- Android-only helpers such as `launch`, `terminate`, and `runAdbShell` are also exposed in YAML scripts. See [Android platform-specific actions](./automate-with-scripts-in-yaml#the-android-part).
+- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
+
+:::
+
+#### Android-specific methods
+
+##### `agent.launch()`
+
+Launch a web URL or native Android activity/package.
+
+```ts
+function launch(target: string): Promise<void>;
+```
+
+- `target: string` &mdash; Can be a web URL, a string in `package/.Activity` format (e.g., `com.android.settings/.Settings`), an app package name, or an app name. If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped package name; otherwise, `target` will be launched as-is.
+
+##### `agent.runAdbShell()`
+
+Run a raw `adb shell` command through the connected device. Pass only the shell command itself, without the `adb shell` prefix.
+
+```ts
+function runAdbShell(command: string, opt?: { timeout?: number }): Promise<string>;
+```
+
+- `command: string` &mdash; Command passed verbatim to `adb shell`. For example, use `input tap 100 200`, not `adb shell input tap 100 200`.
+- `opt.timeout?: number` &mdash; Optional command execution timeout in milliseconds.
+
+```ts
+const result = await agent.runAdbShell('dumpsys battery', { timeout: 60 * 1000 });
+console.log(result);
+
+await agent.runAdbShell('input tap 100 200');
+```
+
+##### `agent.terminate()`
+
+Terminate (force-stop) a running Android app.
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` &mdash; Package name, app name in `appNameMapping`, or `package/.Activity` (only the package part is used).
+
+```ts
+await agent.terminate('com.android.settings');
+```
+
+##### Navigation helpers
+
+- `agent.back(): Promise<void>` &mdash; Trigger the Android system Back action.
+- `agent.home(): Promise<void>` &mdash; Return to the launcher.
+- `agent.recentApps(): Promise<void>` &mdash; Open the Recents/Overview screen.
+
+#### Helper utilities
+
+##### `agentFromAdbDevice()`
+
+Create an `AndroidAgent` from any connected adb device.
+
+```ts
+function agentFromAdbDevice(
+  deviceId?: string,
+  opts?: PageAgentOpt & AndroidDeviceOpt,
+): Promise<AndroidAgent>;
+```
+
+- `deviceId?: string` &mdash; Connect to a specific device; omitted means “first available”.
+- `opts?: PageAgentOpt & AndroidDeviceOpt` &mdash; Combine agent options with [AndroidDevice](#androiddevice) settings.
+
+##### `getConnectedDevices()`
+
+Enumerate adb devices Midscene can drive.
+
+```ts
+function getConnectedDevices(): Promise<Array<{
+  udid: string;
+  state: string;
+  port?: number;
+}>>;
+```
diff --git a/apps/site/docs/en/api.mdx b/apps/site/docs/en/api.mdx
index 0296218fd8..e079c39cec 100644
--- a/apps/site/docs/en/api.mdx
+++ b/apps/site/docs/en/api.mdx
@@ -7,8 +7,8 @@ Midscene ships multiple agents tuned for specific automation environments. Every
 - In Puppeteer, use [PuppeteerAgent](./web-api-reference#puppeteer-agent)
 - In Playwright, use [PlaywrightAgent](./web-api-reference#playwright-agent)
 - In Bridge Mode, use [AgentOverChromeBridge](./web-api-reference#chrome-bridge-agent)
-- On Android, use [Android API reference](./android-api-reference)
-- On iOS, use [iOS API reference](./ios-api-reference)
+- On Android, use [Android API reference](./android#api-reference)
+- On iOS, use [iOS API reference](./ios#api-reference)
 - For GUI agents integrating with your own interface, refer to [Custom Interface Agent](./integrate-with-any-interface)
 
 ### Parameters
diff --git a/apps/site/docs/en/automate-with-scripts-in-yaml.mdx b/apps/site/docs/en/automate-with-scripts-in-yaml.mdx
index db5825c887..2a8f79d893 100644
--- a/apps/site/docs/en/automate-with-scripts-in-yaml.mdx
+++ b/apps/site/docs/en/automate-with-scripts-in-yaml.mdx
@@ -242,7 +242,7 @@ android:
 
 :::tip View Complete Android Configuration Options
 
-YAML scripts now support all configuration options from the `AndroidDevice` constructor. For the complete list of options, please refer to [AndroidDevice Constructor in Android Integration Documentation](./android-getting-started#androiddevice-constructor).
+YAML scripts now support all configuration options from the `AndroidDevice` constructor. For the complete list of options, please refer to [AndroidDevice Constructor in Android Integration Documentation](./android#androiddevice).
 
 :::
 
@@ -343,7 +343,7 @@ ios:
 
 :::tip View Complete iOS Configuration Options
 
-YAML scripts now support all configuration options from the `IOSDevice` constructor. For the complete list of options, please refer to [IOSDevice constructor in the iOS API reference](./ios-api-reference#iosdevice-constructor).
+YAML scripts now support all configuration options from the `IOSDevice` constructor. For the complete list of options, please refer to [IOSDevice constructor in the iOS API reference](./ios#iosdevice).
 
 :::
 
diff --git a/apps/site/docs/en/changelog.mdx b/apps/site/docs/en/changelog.mdx
index 92e7e140aa..8b6a6d0d23 100644
--- a/apps/site/docs/en/changelog.mdx
+++ b/apps/site/docs/en/changelog.mdx
@@ -53,7 +53,7 @@ Midscene now includes an AndroidWorld benchmark report. With v1.9.5, Midscene ac
 
 - `1.9.8` is the final Midscene version that includes MCP support. Later versions retire MCP server packages in favor of Skills and the platform CLIs.
 - Platform CLIs now accept agent behavior init args.
-- YAML scripts now support the HarmonyOS target in the CLI, so HarmonyOS automation can be driven through the same script runner workflow as Web, Android, iOS, and Computer. See: [Automate with Scripts in YAML](./automate-with-scripts-in-yaml), [HarmonyOS API](./harmony-api-reference)
+- YAML scripts now support the HarmonyOS target in the CLI, so HarmonyOS automation can be driven through the same script runner workflow as Web, Android, iOS, and Computer. See: [Automate with Scripts in YAML](./automate-with-scripts-in-yaml), [HarmonyOS API](./harmony#api-reference)
 - YAML Web config supports custom HTTP headers for browser automation.
 - YAML Web config supports `downloadPath` for browser downloads.
 - YAML runs now surface real execution errors instead of ending as a silent "not executed" case.
@@ -117,7 +117,7 @@ We're building a full record → script → replay loop into Studio: drive a rea
 
 ### YAML Workflow Enhancements
 
-- **Android `runAdbShell` timeout**: A `timeout` option is now accepted in both the JavaScript API and YAML scripts. See: [Android API](./android-api-reference), [Automate with Scripts in YAML](./automate-with-scripts-in-yaml)
+- **Android `runAdbShell` timeout**: A `timeout` option is now accepted in both the JavaScript API and YAML scripts. See: [Android API](./android#api-reference), [Automate with Scripts in YAML](./automate-with-scripts-in-yaml)
 
 ### New Interaction APIs
 
@@ -220,7 +220,7 @@ A new YAML output language option is available in the Chrome extension's recordi
 
 ### Android / HarmonyOS Improvements
 
-- Added `terminate` action on Android and HarmonyOS to force-stop apps, useful for resetting app state during testing. See: [Android API](./android-api-reference), [HarmonyOS API](./harmony-api-reference)
+- Added `terminate` action on Android and HarmonyOS to force-stop apps, useful for resetting app state during testing. See: [Android API](./android#api-reference), [HarmonyOS API](./harmony#api-reference)
 - Fixed placeholder text unexpectedly retained when typing on X/Twitter on Android
 - Fixed Android Playground LAN access issues
 
@@ -272,7 +272,7 @@ The `deepThink` parameter in element-locating APIs has been renamed to `deepLoca
 
 - **Skill CLI Custom Interfaces**: Skill CLI now supports custom interfaces for more flexible Skill extensibility. See: [Skills](./skills)
 - **Unified MCP Tool Export**: All platform packages (Web, Android, iOS, etc.) now export MidsceneTools uniformly, making MCP integration simpler. See: [MCP](./mcp)
-- **iOS App Termination by bundleId**: You can now terminate iOS apps by bundleId, making it easier to reset app state during testing. See: [iOS API Reference](./ios-api-reference)
+- **iOS App Termination by bundleId**: You can now terminate iOS apps by bundleId, making it easier to reset app state during testing. See: [iOS API Reference](./ios#api-reference)
 - **CLI Version Display**: CLI now shows version info in health checks, helping you troubleshoot environment issues
 
 ### Task Cancellation Support
@@ -387,7 +387,7 @@ See: [Midscene Skills](https://github.com/web-infra-dev/midscene-skills)
 
 New `@midscene/computer-mcp` package provides PC desktop automation as a standalone MCP service. Developers can use desktop automation capabilities directly in MCP-compatible tools like Cursor and Trae without additional integration.
 
-See docs: [PC Desktop Automation](./computer-introduction)
+See docs: [PC Desktop Automation](./computer)
 
 ### Chrome Extension MCP Background Connection
 
@@ -440,13 +440,13 @@ Midscene now supports PC desktop automation on Windows, macOS, and Linux, drivin
 - YAML automation scripts and CLI tools
 - HTML report playback for all operation paths
 
-See documentation: [PC Desktop Automation](./computer-introduction)
+See documentation: [PC Desktop Automation](./computer)
 
 ### Major Android Screenshot Performance Improvement
 
 With Scrcpy screenshot mode enabled, screenshot time drops from 500–2000ms to **100–200ms**, significantly improving Android automation response speed. This is particularly useful for remote device debugging and high frame rate scenarios.
 
-See documentation: [Scrcpy Screenshot Mode](./android-api-reference#scrcpy)
+See documentation: [Scrcpy Screenshot Mode](./android#scrcpy)
 
 ### Deep Thinking Mode Enhancement
 
@@ -715,7 +715,7 @@ v0.30 improves the cache system, allowing you to control cache behavior based on
 ## v0.29 - iOS platform support added
 
 ### iOS platform support added
-The biggest highlight of v0.29 is the official introduction of iOS platform support! Now you can connect and automate iOS devices through WebDriver, extending Midscene's powerful AI automation capabilities to the Apple ecosystem, details: [Support iOS automation](./ios-introduction).
+The biggest highlight of v0.29 is the official introduction of iOS platform support! Now you can connect and automate iOS devices through WebDriver, extending Midscene's powerful AI automation capabilities to the Apple ecosystem, details: [Support iOS automation](./ios).
 
 ### Qwen3-VL model adaptation
 
@@ -801,7 +801,7 @@ Based on the introduction of [Rslib](https://github.com/web-infra-dev/rslib) in
 - Add all agent APIs to Playwright fixture, simplify test script writing, and solve the problem of not generating reports when using agentForPage
 
 ### Android automation enhancement
-- New keyboard hiding strategy([keyboardDismissStrategy](./android-getting-started#androiddevice-constructor)), allowing you to specify the way to automatically hide the keyboard
+- New keyboard hiding strategy([keyboardDismissStrategy](./android#androiddevice)), allowing you to specify the way to automatically hide the keyboard
 
 ### Report function optimization
 - Report content lazy parsing, solving the problem of report crash when the report is large
@@ -1080,7 +1080,7 @@ Upgrade now to experience these powerful new features!
 
 * [Custom Report Node API documentation](/en/api.mdx#log-screenshot)
 
-* [API documentation for more Android configuration items](/en/android-getting-started.mdx#androiddevice-constructor)
+* [API documentation for more Android configuration items](/en/android#androiddevice)
 
 
 ## v0.17 - Let AI see the DOM of the page
@@ -1190,7 +1190,7 @@ Read more: [Use JavaScript to Optimize the AI Automation Code](./use-javascript-
 🛠️ YAML or JS SDK
 ⚡ Auto‑planning & Instant Actions APIs
 
-Read more: [Android automation](./android-introduction)
+Read more: [Android automation](./android)
 
 ### More features
 
diff --git a/apps/site/docs/en/computer-api-reference.mdx b/apps/site/docs/en/computer-api-reference.mdx
deleted file mode 100644
index 8efbdeceaf..0000000000
--- a/apps/site/docs/en/computer-api-reference.mdx
+++ /dev/null
@@ -1,438 +0,0 @@
-# API Reference (PC Desktop)
-
-This page documents the PC desktop-specific APIs provided by `@midscene/computer`.
-
-For common APIs that work across all platforms, see [Common API Reference](./api).
-
-## Agent Creation
-
-`agentForComputer(opts?): Promise<ComputerAgent>`
-
-Create an agent for local desktop automation.
-
-> Backward compatibility: `agentFromComputer` is still available as an alias.
-
-`agentForRDPComputer(opts): Promise<ComputerAgent<RDPDevice>>`
-
-Create an agent for remote Windows desktop automation over RDP.
-
-**Parameters:**
-
-```typescript
-interface BaseComputerAgentOpt {
-  // Agent options (inherited from AgentOpt)
-  aiActionContext?: string;
-  cache?: boolean;
-  // ... other AgentOpt properties
-
-  customActions?: DeviceAction<any>[];
-}
-
-interface LocalComputerAgentOpt extends BaseComputerAgentOpt {
-
-  // Local desktop options
-  displayId?: string;
-  headless?: boolean;
-  xvfbResolution?: string;
-}
-
-interface RDPComputerAgentOpt extends BaseComputerAgentOpt {
-  host: string;
-  port?: number;
-  username?: string;
-  password?: string;
-  domain?: string;
-  adminSession?: boolean;
-  ignoreCertificate?: boolean;
-  securityProtocol?: 'auto' | 'tls' | 'nla' | 'rdp';
-  desktopWidth?: number;
-  desktopHeight?: number;
-}
-```
-
-### Local Desktop Options
-
-- `displayId` (optional): Specify which display to control. Get available displays with `ComputerDevice.listDisplays()`.
-- `customActions` (optional): Add custom actions to the device.
-- `headless` (optional, Linux only): Set to `true` to start a virtual display via [Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml), enabling desktop automation on headless Linux servers and CI environments without a physical display. Can also be set via the `MIDSCENE_COMPUTER_HEADLESS_LINUX=true` environment variable.
-- `xvfbResolution` (optional): Resolution for the Xvfb virtual display. Defaults to `'1920x1080x24'`.
-
-### RDP Options
-
-- `host`: Remote Windows host or IP.
-- `port`: RDP port. Defaults to `3389`.
-- `username` / `password`: Credentials for the remote session.
-- `domain`: Optional Windows domain.
-- `adminSession`: Request the remote admin session when the server allows it.
-- `ignoreCertificate`: Skip certificate validation for self-signed setups.
-- `securityProtocol`: Choose `'auto'`, `'tls'`, `'nla'`, or `'rdp'`.
-- `desktopWidth` / `desktopHeight`: Request a specific remote desktop resolution.
-
-:::tip Example: Testing Electron Apps on Headless Linux CI
-A complete demo of testing [Obsidian](https://obsidian.md/) (an Electron app) on headless Linux CI with `@midscene/computer`: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
-:::
-
-**Example:**
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-// Connect to primary display
-const agent = await agentForComputer({
-  aiActionContext: 'You are automating a desktop application.',
-});
-
-// Connect to specific display
-const displays = await ComputerDevice.listDisplays();
-const agent2 = await agentForComputer({
-  displayId: displays[1].id,
-});
-```
-
-**Example: connect to a remote Windows desktop over RDP**
-
-```typescript
-import { agentForRDPComputer } from '@midscene/computer';
-
-const agent = await agentForRDPComputer({
-  aiActionContext:
-    'You are controlling a remote Windows desktop over the RDP protocol.',
-  host: '10.75.166.249',
-  port: 3389,
-  username: 'Admin',
-  password: 'replace-with-your-password',
-  // Optional: bind the TCP connection to this local source IP.
-  localAddress: '10.75.166.10',
-  ignoreCertificate: true,
-});
-
-await agent.aiWaitFor('The remote Windows desktop is visible');
-await agent.aiAct('Click the Windows Start button');
-await agent.aiAct('Open Settings');
-```
-
-:::tip Example: Remote Windows desktop over RDP
-A runnable demo that connects to a remote Windows machine over RDP, opens Settings, navigates into Windows Update, and emits a structured report: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
-:::
-
-Use `localAddress` only when the machine running Midscene has multiple outbound
-routes and the RDP server must be reached from a specific local source IP. Pass
-an IP address, not a network interface name.
-
-## Device Management
-
-`ComputerDevice.listDisplays(): Promise<DisplayInfo[]>`
-
-List all available displays.
-
-**Returns:**
-
-```typescript
-interface DisplayInfo {
-  id: string;
-  name: string;
-  primary?: boolean;
-}
-```
-
-**Example:**
-
-```typescript
-import { ComputerDevice } from '@midscene/computer';
-
-const displays = await ComputerDevice.listDisplays();
-console.log('Available displays:', displays);
-// [
-//   { id: '0', name: 'Built-in Display', primary: true },
-//   { id: '1', name: 'External Display', primary: false }
-// ]
-```
-
-`checkComputerEnvironment(): Promise<EnvironmentCheck>`
-
-Check if the computer environment is properly configured.
-
-**Returns:**
-
-```typescript
-interface EnvironmentCheck {
-  available: boolean;
-  error?: string;
-  platform: string;
-  displays: number;
-}
-```
-
-**Example:**
-
-```typescript
-import { checkComputerEnvironment } from '@midscene/computer';
-
-const env = await checkComputerEnvironment();
-console.log('Environment check:', env);
-
-if (!env.available) {
-  console.error('Environment error:', env.error);
-}
-```
-
-## ComputerAgent
-
-The `ComputerAgent` class extends `PageAgent<ComputerDevice>` and inherits all common agent methods:
-
-- `aiAct(action: string)`: Perform an action with AI
-- `aiQuery(query: string)`: Extract information with AI
-- `aiAssert(assertion: string)`: Assert a condition with AI
-- `aiWaitFor(condition: string)`: Wait for a condition
-- `aiLocate(description: string)`: Locate an element
-- And more...
-
-Instant actions are also available for direct, deterministic control once an element is located:
-
-- `aiTap()`, `aiDoubleClick()`, `aiRightClick()`, `aiHover()`: Mouse actions
-- `aiInput()`, `aiClearInput()`, `aiKeyboardPress()`: Keyboard actions
-- `aiScroll()`: Scroll action
-
-See [Common API Reference](./api) for details.
-
-## Available Actions
-
-The `ComputerDevice` supports the following actions:
-
-### Mouse Actions
-
-#### Tap (Click)
-
-Single click at the target location.
-
-```typescript
-await agent.aiAct('click on the File menu');
-await agent.aiAct('click at center of screen');
-```
-
-#### DoubleClick
-
-Double-click at the target location.
-
-```typescript
-await agent.aiAct('double-click on the desktop icon');
-```
-
-#### RightClick
-
-Right-click to open context menu.
-
-```typescript
-await agent.aiAct('right-click on the desktop');
-await agent.aiAct('right-click on the file');
-```
-
-#### MouseMove (Hover)
-
-Move the mouse to an element — also known as hovering — for example to reveal a hover menu or tooltip.
-
-```typescript
-// Natural-language form (move mouse / hover)
-await agent.aiAct('move mouse to the menu item');
-
-// Instant action: locate and hover in one call
-await agent.aiHover('the menu item "Products"');
-```
-
-#### DragAndDrop
-
-Drag from one location and drop at another.
-
-```typescript
-await agent.aiAct('drag the file to the folder');
-```
-
-### Keyboard Actions
-
-#### KeyboardPress
-
-Press keyboard keys with optional modifiers.
-
-**Supported keys:**
-- Regular keys: `a-z`, `0-9`, `Enter`, `Escape`, `Space`, `Tab`, etc.
-- Arrow keys: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`
-- Function keys: `F1`-`F12`
-- Modifiers: `Command`/`Cmd` (macOS), `Control`/`Ctrl`, `Alt`, `Shift`, `Win` (Windows)
-- Media keys: `VolumeUp`, `VolumeDown`, `Mute`, etc.
-
-**Examples:**
-
-```typescript
-// Simple key press
-await agent.aiAct('press Enter');
-await agent.aiAct('press Escape');
-
-// Key combinations (platform-specific)
-if (process.platform === 'darwin') {
-  // macOS
-  await agent.aiAct('press Cmd+Space');  // Open Spotlight
-  await agent.aiAct('press Cmd+Tab');    // App switcher
-  await agent.aiAct('press Cmd+C');      // Copy
-  await agent.aiAct('press Cmd+V');      // Paste
-} else {
-  // Windows/Linux
-  await agent.aiAct('press Windows key'); // Start menu
-  await agent.aiAct('press Alt+Tab');     // App switcher
-  await agent.aiAct('press Ctrl+C');      // Copy
-  await agent.aiAct('press Ctrl+V');      // Paste
-}
-
-// Arrow keys
-await agent.aiAct('press ArrowDown');
-await agent.aiAct('press ArrowUp');
-
-// Function keys
-await agent.aiAct('press F5');  // Refresh
-```
-
-#### Input
-
-Type text into an input field.
-
-```typescript
-await agent.aiAct('type "Hello World" in the search box');
-await agent.aiAct('type "my-document.txt"');
-```
-
-#### ClearInput
-
-Clear the content of an input field.
-
-```typescript
-await agent.aiAct('clear the text field');
-```
-
-### Scroll Actions
-
-Scroll the screen or a specific area.
-
-```typescript
-// Scroll directions
-await agent.aiAct('scroll down');
-await agent.aiAct('scroll up');
-await agent.aiAct('scroll left');
-await agent.aiAct('scroll right');
-
-// Scroll to positions
-await agent.aiAct('scroll to top');
-await agent.aiAct('scroll to bottom');
-```
-
-### Display Actions
-
-#### ListDisplays
-
-Get information about all connected displays.
-
-```typescript
-const displays = await ComputerDevice.listDisplays();
-```
-
-When you use RDP, `ListDisplays` returns the current remote session as a single display.
-
-## Examples
-
-### Open Application and Navigate
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-const agent = await agentForComputer();
-
-// Open application
-if (process.platform === 'darwin') {
-  await agent.aiAct('press Cmd+Space');
-  await agent.aiAct('type "TextEdit" and press Enter');
-} else {
-  await agent.aiAct('press Windows key');
-  await agent.aiAct('type "Notepad" and press Enter');
-}
-
-await agent.aiWaitFor('text editor window is visible');
-
-// Type content
-await agent.aiAct('type "Hello, Midscene!"');
-
-// Save file
-if (process.platform === 'darwin') {
-  await agent.aiAct('press Cmd+S');
-} else {
-  await agent.aiAct('press Ctrl+S');
-}
-```
-
-### Multi-Display Workflow
-
-```typescript
-import { ComputerDevice, agentForComputer } from '@midscene/computer';
-
-// List displays
-const displays = await ComputerDevice.listDisplays();
-console.log(`Found ${displays.length} displays`);
-
-// Control primary display
-const agent1 = await agentForComputer({
-  displayId: displays[0].id,
-});
-await agent1.aiAct('move mouse to center of screen');
-
-// Control secondary display
-if (displays.length > 1) {
-  const agent2 = await agentForComputer({
-    displayId: displays[1].id,
-  });
-  await agent2.aiAct('move mouse to center of screen');
-}
-```
-
-### Web Browser Automation
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-const agent = await agentForComputer();
-
-// Open browser
-if (process.platform === 'darwin') {
-  await agent.aiAct('press Cmd+Space');
-  await agent.aiAct('type "Safari" and press Enter');
-} else {
-  await agent.aiAct('press Windows key');
-  await agent.aiAct('type "Chrome" and press Enter');
-}
-
-await agent.aiWaitFor('browser window is open');
-
-// Navigate
-await agent.aiAct('click on address bar');
-await agent.aiAct('type "example.com" and press Enter');
-await agent.aiWaitFor('page has loaded');
-
-// Extract information
-const title = await agent.aiQuery('string, get the page title');
-console.log('Page title:', title);
-```
-
-## TypeScript Types
-
-```typescript
-import type {
-  ComputerAgent,
-  ComputerAgentOpt,
-  ComputerDevice,
-  ComputerDeviceOpt,
-  DisplayInfo,
-  EnvironmentCheck,
-} from '@midscene/computer';
-```
-
-## See Also
-
-- [Common API Reference](./api) - APIs that work across all platforms
-- [Model Configuration](./model-config) - Configure AI models
-- [Caching](./caching) - Improve performance with caching
diff --git a/apps/site/docs/en/computer-getting-started.mdx b/apps/site/docs/en/computer-getting-started.mdx
deleted file mode 100644
index b76fea888b..0000000000
--- a/apps/site/docs/en/computer-getting-started.mdx
+++ /dev/null
@@ -1,297 +0,0 @@
-import StartExperience from './common/start-experience.mdx';
-import SetupEnv from './common/setup-env.mdx';
-
-import { PackageManagerTabs } from '@theme';
-
-# PC Desktop Getting Started
-
-This guide walks you through everything required to automate PC desktop applications with Midscene: install dependencies, configure model credentials, and run your first JavaScript script.
-
-:::info Demo Projects
-
-Control PC desktop with JavaScript: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo)
-
-Integrate Vitest for testing: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo)
-
-Control a remote Windows desktop over RDP: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
-
-Test [Obsidian](https://obsidian.md/) (an Electron app) on headless Linux CI with `@midscene/computer`: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
-
-:::
-
-<SetupEnv />
-
-## System Requirements
-
-### Node.js
-
-Node.js 18.19.0 or higher is required.
-
-### Platform-Specific Dependencies
-
-**macOS**: Accessibility permissions are required for keyboard and mouse control. When you run the script for the first time, macOS will prompt you to grant access. Go to **System Settings > Privacy & Security > Accessibility** and enable permissions for the application running your script (e.g., Terminal, iTerm2, VS Code, WebStorm, or other IDEs). For more details, see [nut.js macOS setup](https://github.com/nut-tree/nut.js#macos).
-
-**Windows**: No extra setup is needed for ordinary apps. However, Windows isolates input across privilege levels (UIPI): a non-elevated process **cannot** send mouse or keyboard input to a window that runs **as Administrator** (elevated). The input is silently dropped — the cursor still moves to the right spot, but clicks and keystrokes have no effect. Prefer running the target application without Administrator privileges. If the target application must stay elevated, run the terminal or Node.js that launches Midscene **as Administrator** too, so both processes share the same privilege level. See [Windows: clicks have no effect on some apps](#windows-clicks-have-no-effect-on-some-apps).
-
-**Linux**: [ImageMagick](https://imagemagick.org/script/download.php) is required for screenshot functionality.
-
-**Headless Linux (CI)**: To run desktop automation on a headless Linux server (e.g. GitHub Actions), install Xvfb and its dependencies, then enable headless mode:
-
-```bash
-# Install dependencies
-sudo apt-get install -y xvfb x11-xserver-utils imagemagick
-```
-
-```typescript
-// Option 1: Pass headless option
-const agent = await agentForComputer({ headless: true });
-
-// Option 2: Set environment variable
-// MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
-```
-
-Xvfb creates a virtual display so that mouse, keyboard, and screenshot operations work without a physical monitor. See [API Reference](./computer-api-reference) for details.
-
-## Try Playground (no code)
-
-Playground is the fastest way to validate the connection and observe AI-driven steps without writing code. It shares the same core as `@midscene/computer`, so anything that works here will behave the same once scripted.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
-
-1. Launch the Playground CLI:
-
-```bash
-npx --yes @midscene/computer-playground
-```
-
-2. Click the gear icon in the Playground window, then paste your API key configuration. Refer back to [Model configuration](./model-config) if you still need credentials.
-
-## Start experiencing
-
-<StartExperience />
-
-## Integration with Midscene Agent
-
-Once Playground works, move to a repeatable script with the JavaScript SDK.
-
-### Step 1. Install dependencies
-
-<PackageManagerTabs command="install @midscene/computer" />
-
-### Step 2. Write your first script
-
-Create `example.ts`:
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-(async () => {
-  // Create an agent
-  const agent = await agentForComputer({
-    aiActionContext: 'You are controlling a desktop computer.',
-  });
-
-  // Take a screenshot and query information
-  const screenInfo = await agent.aiQuery(
-    '{width: number, height: number}, get screen resolution'
-  );
-  console.log('Screen resolution:', screenInfo);
-
-  // Move mouse to center
-  await agent.aiAct('move mouse to center of screen');
-
-  // Assert screen has content
-  await agent.aiAssert('The screen has visible content');
-
-  console.log('Desktop automation completed!');
-})();
-```
-
-### Step 3. Run the script
-
-```bash
-npx tsx example.ts
-```
-
-## Connect to a Remote Windows Desktop via RDP
-
-`@midscene/computer` can also drive a remote Windows desktop directly over the RDP protocol through the dedicated `agentForRDPComputer()` factory.
-
-### Prerequisites
-
-1. A reachable Windows machine with RDP enabled.
-2. [FreeRDP](https://www.freerdp.com/) installed on the machine running your script.
-
-### Example
-
-```typescript
-import { agentForRDPComputer } from '@midscene/computer';
-
-const agent = await agentForRDPComputer({
-  aiActionContext:
-    'You are controlling a remote Windows desktop over the RDP protocol.',
-  host: '10.75.166.249',
-  port: 3389,
-  username: 'Admin',
-  password: 'replace-with-your-password',
-  ignoreCertificate: true,
-});
-
-await agent.aiWaitFor('The remote Windows desktop is visible');
-await agent.aiAct('Click the Windows Start button');
-await agent.aiAct('Open Settings');
-await agent.aiAssert('The Windows Settings window is visible');
-```
-
-### Common RDP Options
-
-- `host`: Remote Windows host or IP.
-- `port`: RDP port. Defaults to `3389`.
-- `username` / `password`: Account credentials for the remote session.
-- `domain`: Optional Windows domain.
-- `ignoreCertificate`: Skip certificate validation for self-signed setups.
-- `desktopWidth` / `desktopHeight`: Request a specific remote desktop resolution.
-- `adminSession`: Request the remote admin session when the server allows it.
-
-RDP sessions are exposed to Midscene as a single remote display. You can still use the same `aiAct`, `aiQuery`, `aiAssert`, and report features as local desktop automation.
-
-## Multi-Display Support
-
-If you have multiple displays, you can control a specific one:
-
-```typescript
-import { ComputerDevice, agentForComputer } from '@midscene/computer';
-
-// List all displays
-const displays = await ComputerDevice.listDisplays();
-console.log('Available displays:', displays);
-
-// Connect to a specific display
-const agent = await agentForComputer({
-  displayId: displays[0].id,
-});
-```
-
-## Example Usage
-
-### Basic Mouse Operations
-
-```typescript
-// Click at center of screen
-await agent.aiAct('click mouse at center of screen');
-
-// Move mouse to a specific location
-await agent.aiAct('move mouse to top-left corner');
-
-// Double-click
-await agent.aiAct('double-click on the desktop icon');
-
-// Right-click
-await agent.aiAct('right-click to open context menu');
-```
-
-### Keyboard Operations
-
-```typescript
-// Type text
-await agent.aiAct('type "Hello World"');
-
-// Press keyboard shortcuts
-if (process.platform === 'darwin') {
-  await agent.aiAct('press Cmd+Space to open Spotlight');
-  await agent.aiAct('type "Calculator" and press Enter');
-} else {
-  await agent.aiAct('press Windows key');
-  await agent.aiAct('type "Calculator" and press Enter');
-}
-
-// Press function keys
-await agent.aiAct('press Escape');
-await agent.aiAct('press Enter');
-```
-
-### Query Information
-
-```typescript
-// Extract screen information
-const info = await agent.aiQuery(
-  '{hasDesktop: boolean, visibleApps: string[]}, check if desktop is visible and list visible apps'
-);
-
-// Locate elements
-const position = await agent.aiLocate('the File menu');
-console.log('File menu position:', position);
-```
-
-### Complex Workflows
-
-```typescript
-// Open an application and interact with it
-await agent.aiAct('open Finder');
-await agent.aiWaitFor('Finder window is visible');
-
-await agent.aiAct('click on Documents folder');
-await agent.aiAct('press Cmd+N to create new folder');
-await agent.aiAct('type "My Project"');
-await agent.aiAct('press Enter');
-
-await agent.aiAssert('A folder named "My Project" exists');
-```
-
-## Environment Check
-
-You can check if your system is properly configured:
-
-```typescript
-import { checkComputerEnvironment } from '@midscene/computer';
-
-const env = await checkComputerEnvironment();
-console.log('Platform:', env.platform);
-console.log('Available:', env.available);
-console.log('Displays:', env.displays);
-
-if (!env.available) {
-  console.error('Environment not available:', env.error);
-}
-```
-
-## FAQ
-
-### macOS: Script cannot control mouse or keyboard
-
-macOS requires Accessibility permissions for keyboard and mouse control. Go to **System Settings > Privacy & Security > Accessibility** and enable the toggle for the application running your script (e.g., Terminal, iTerm2, VS Code, or WebStorm).
-
-If you have already granted permission but it still doesn't work, try removing the app from the Accessibility list and re-adding it — macOS sometimes caches stale permissions.
-
-### Windows: clicks have no effect on some apps
-
-If the cursor moves to the correct position but clicks or key presses do nothing on a particular application — while other apps work fine — check whether the target app is running **as Administrator** (elevated). Windows UIPI blocks input injected from a lower-privilege process into an elevated window and drops it silently, with no error.
-
-Prefer lowering the target application's privilege level first, for example by launching it without "Run as Administrator" or disabling any setting that always starts it elevated. If the target app must stay elevated, run the terminal or Node.js that launches Midscene **as Administrator** so it matches the target app's privilege level, then try again. System-level shortcuts such as `Win+Tab` are handled by the shell and keep working even when this happens, which is why keyboard shortcuts may appear to work while in-app clicks do not.
-
-> The health check logged at connection time prints this troubleshooting link when Midscene is not running as Administrator on Windows.
-
-### Linux: Screenshots or interactions fail on a headless server
-
-A headless Linux environment (e.g. CI) has no physical display. You need to install Xvfb and ImageMagick, and enable headless mode:
-
-```bash
-sudo apt-get install -y xvfb x11-xserver-utils imagemagick
-```
-
-```typescript
-const agent = await agentForComputer({ headless: true });
-```
-
-Or set the environment variable:
-
-```bash
-MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
-```
-
-## Next Steps
-
-- [API Reference](./computer-api-reference)
-- [Use YAML format automation scripts](./automate-with-scripts-in-yaml)
-- [YAML script runner](./yaml-script-runner)
-- [Caching for efficiency](./caching)
diff --git a/apps/site/docs/en/computer-introduction.mdx b/apps/site/docs/en/computer-introduction.mdx
deleted file mode 100644
index 9551125b20..0000000000
--- a/apps/site/docs/en/computer-introduction.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
-import ShowcaseComputer from './showcases-computer.mdx';
-
-# PC Desktop Automation Support
-
-Midscene can drive native keyboard and mouse controls to support PC desktop automation on Windows, macOS, and Linux.
-
-By leveraging a visual model solution, the automation process works with any desktop application—whether built with Electron, Qt, WPF, or native technologies. Developers only need to focus on the final user experience when debugging UI automation scripts.
-
-The PC desktop automation solution comes with all the features of Midscene:
-
-- Supports zero-code trial using Playground
-- Supports JavaScript SDK for scripting
-- Supports automation scripts in YAML format and command-line tools
-- Supports HTML reports to replay all operation paths
-- Works across Windows, macOS, and Linux platforms
-- Headless mode for Linux CI via Xvfb (no physical display required)
-- Multi-display support for complex setups
-
-## Showcases
-
-<ShowcaseComputer />
-
-See more showcases: [showcases](./showcases.mdx)
-
-## Try with Playground
-
-With Midscene.js playground, you can experience PC desktop automation capabilities without writing any code.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
-
-See [Getting Started](./computer-getting-started#try-playground-no-code) to learn how to launch the Playground.
-
-## Key Features
-
-### Cross-platform Desktop Control
-
-- **Mouse Operations**: Click, double-click, right-click, mouse move, drag-and-drop
-- **Keyboard Input**: Type text, press keys with modifiers (Cmd/Ctrl/Alt/Shift)
-- **Screen Capture**: Take screenshots of any display
-- **Multi-display**: Work with multiple monitors simultaneously
-
-### AI-Powered Automation
-
-Using Midscene's AI capabilities, you can automate desktop applications with natural language:
-
-```typescript
-await agent.aiAct('open the File menu');
-await agent.aiAct('click on Save As');
-await agent.aiAct('type "my-document" in the filename field');
-await agent.aiAct('press Enter');
-```
-
-## Use Cases
-
-- **Desktop Application Testing**: Automate testing for Electron, Qt, or native apps
-- **Workflow Automation**: Automate repetitive tasks across desktop applications
-- **Cross-app Integration**: Control multiple applications in sequence
-- **UI Testing**: Test desktop applications with natural language descriptions
-
-## Next Steps
-
-* [Getting Started](./computer-getting-started)
-* [API Reference](./computer-api-reference)
-* [Use YAML format automation scripts](./automate-with-scripts-in-yaml) and [YAML script runner](./yaml-script-runner)
diff --git a/apps/site/docs/en/computer.mdx b/apps/site/docs/en/computer.mdx
new file mode 100644
index 0000000000..191c2248e4
--- /dev/null
+++ b/apps/site/docs/en/computer.mdx
@@ -0,0 +1,738 @@
+import ShowcaseComputer from './showcases-computer.mdx';
+import StartExperience from './common/start-experience.mdx';
+import SetupEnv from './common/setup-env.mdx';
+
+import { PackageManagerTabs } from '@theme';
+
+# PC Desktop Automation Support
+
+Midscene can drive native keyboard and mouse controls to support PC desktop automation on Windows, macOS, and Linux.
+
+## Showcases
+
+<ShowcaseComputer />
+
+See more showcases: [showcases](./showcases.mdx)
+
+This guide walks you through everything required to automate PC desktop applications with Midscene: install dependencies, configure model credentials, and run your first JavaScript script.
+
+:::info Demo Projects
+
+Control PC desktop with JavaScript: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo)
+
+Integrate Vitest for testing: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo)
+
+Control a remote Windows desktop over RDP: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
+
+Test [Obsidian](https://obsidian.md/) (an Electron app) on headless Linux CI with `@midscene/computer`: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
+
+:::
+
+<SetupEnv />
+
+## System Requirements
+
+### Node.js
+
+Node.js 18.19.0 or higher is required.
+
+### Platform-Specific Dependencies
+
+**macOS**: Accessibility permissions are required for keyboard and mouse control. When you run the script for the first time, macOS will prompt you to grant access. Go to **System Settings > Privacy & Security > Accessibility** and enable permissions for the application running your script (e.g., Terminal, iTerm2, VS Code, WebStorm, or other IDEs). For more details, see [nut.js macOS setup](https://github.com/nut-tree/nut.js#macos).
+
+**Windows**: No extra setup is needed for ordinary apps. However, Windows isolates input across privilege levels (UIPI): a non-elevated process **cannot** send mouse or keyboard input to a window that runs **as Administrator** (elevated). The input is silently dropped — the cursor still moves to the right spot, but clicks and keystrokes have no effect. Prefer running the target application without Administrator privileges. If the target application must stay elevated, run the terminal or Node.js that launches Midscene **as Administrator** too, so both processes share the same privilege level. See [Windows: clicks have no effect on some apps](#windows-clicks-have-no-effect-on-some-apps).
+
+**Linux**: [ImageMagick](https://imagemagick.org/script/download.php) is required for screenshot functionality.
+
+**Headless Linux (CI)**: To run desktop automation on a headless Linux server (e.g. GitHub Actions), install Xvfb and its dependencies, then enable headless mode:
+
+```bash
+# Install dependencies
+sudo apt-get install -y xvfb x11-xserver-utils imagemagick
+```
+
+```typescript
+// Option 1: Pass headless option
+const agent = await agentForComputer({ headless: true });
+
+// Option 2: Set environment variable
+// MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
+```
+
+Xvfb creates a virtual display so that mouse, keyboard, and screenshot operations work without a physical monitor. See [API Reference](#api-reference) for details.
+
+## Try Playground (no code)
+
+Playground is the fastest way to validate the connection and observe AI-driven steps without writing code. It shares the same core as `@midscene/computer`, so anything that works here will behave the same once scripted.
+
+<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
+
+1. Launch the Playground CLI:
+
+```bash
+npx --yes @midscene/computer-playground
+```
+
+2. Click the gear icon in the Playground window, then paste your API key configuration. Refer back to [Model configuration](./model-config) if you still need credentials.
+
+## Start experiencing
+
+<StartExperience />
+
+## Integration with Midscene Agent
+
+Once Playground works, move to a repeatable script with the JavaScript SDK.
+
+### Step 1. Install dependencies
+
+<PackageManagerTabs command="install @midscene/computer" />
+
+### Step 2. Write your first script
+
+Create `example.ts`:
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+(async () => {
+  // Create an agent
+  const agent = await agentForComputer({
+    aiActionContext: 'You are controlling a desktop computer.',
+  });
+
+  // Take a screenshot and query information
+  const screenInfo = await agent.aiQuery(
+    '{width: number, height: number}, get screen resolution'
+  );
+  console.log('Screen resolution:', screenInfo);
+
+  // Move mouse to center
+  await agent.aiAct('move mouse to center of screen');
+
+  // Assert screen has content
+  await agent.aiAssert('The screen has visible content');
+
+  console.log('Desktop automation completed!');
+})();
+```
+
+### Step 3. Run the script
+
+```bash
+npx tsx example.ts
+```
+
+## Connect to a Remote Windows Desktop via RDP
+
+`@midscene/computer` can also drive a remote Windows desktop directly over the RDP protocol through the dedicated `agentForRDPComputer()` factory.
+
+### Prerequisites
+
+1. A reachable Windows machine with RDP enabled.
+2. [FreeRDP](https://www.freerdp.com/) installed on the machine running your script.
+
+### Example
+
+```typescript
+import { agentForRDPComputer } from '@midscene/computer';
+
+const agent = await agentForRDPComputer({
+  aiActionContext:
+    'You are controlling a remote Windows desktop over the RDP protocol.',
+  host: '10.75.166.249',
+  port: 3389,
+  username: 'Admin',
+  password: 'replace-with-your-password',
+  ignoreCertificate: true,
+});
+
+await agent.aiWaitFor('The remote Windows desktop is visible');
+await agent.aiAct('Click the Windows Start button');
+await agent.aiAct('Open Settings');
+await agent.aiAssert('The Windows Settings window is visible');
+```
+
+### Common RDP Options
+
+- `host`: Remote Windows host or IP.
+- `port`: RDP port. Defaults to `3389`.
+- `username` / `password`: Account credentials for the remote session.
+- `domain`: Optional Windows domain.
+- `ignoreCertificate`: Skip certificate validation for self-signed setups.
+- `desktopWidth` / `desktopHeight`: Request a specific remote desktop resolution.
+- `adminSession`: Request the remote admin session when the server allows it.
+
+RDP sessions are exposed to Midscene as a single remote display. You can still use the same `aiAct`, `aiQuery`, `aiAssert`, and report features as local desktop automation.
+
+## Multi-Display Support
+
+If you have multiple displays, you can control a specific one:
+
+```typescript
+import { ComputerDevice, agentForComputer } from '@midscene/computer';
+
+// List all displays
+const displays = await ComputerDevice.listDisplays();
+console.log('Available displays:', displays);
+
+// Connect to a specific display
+const agent = await agentForComputer({
+  displayId: displays[0].id,
+});
+```
+
+## Example Usage
+
+### Basic Mouse Operations
+
+```typescript
+// Click at center of screen
+await agent.aiAct('click mouse at center of screen');
+
+// Move mouse to a specific location
+await agent.aiAct('move mouse to top-left corner');
+
+// Double-click
+await agent.aiAct('double-click on the desktop icon');
+
+// Right-click
+await agent.aiAct('right-click to open context menu');
+```
+
+### Keyboard Operations
+
+```typescript
+// Type text
+await agent.aiAct('type "Hello World"');
+
+// Press keyboard shortcuts
+if (process.platform === 'darwin') {
+  await agent.aiAct('press Cmd+Space to open Spotlight');
+  await agent.aiAct('type "Calculator" and press Enter');
+} else {
+  await agent.aiAct('press Windows key');
+  await agent.aiAct('type "Calculator" and press Enter');
+}
+
+// Press function keys
+await agent.aiAct('press Escape');
+await agent.aiAct('press Enter');
+```
+
+### Query Information
+
+```typescript
+// Extract screen information
+const info = await agent.aiQuery(
+  '{hasDesktop: boolean, visibleApps: string[]}, check if desktop is visible and list visible apps'
+);
+
+// Locate elements
+const position = await agent.aiLocate('the File menu');
+console.log('File menu position:', position);
+```
+
+### Complex Workflows
+
+```typescript
+// Open an application and interact with it
+await agent.aiAct('open Finder');
+await agent.aiWaitFor('Finder window is visible');
+
+await agent.aiAct('click on Documents folder');
+await agent.aiAct('press Cmd+N to create new folder');
+await agent.aiAct('type "My Project"');
+await agent.aiAct('press Enter');
+
+await agent.aiAssert('A folder named "My Project" exists');
+```
+
+## Environment Check
+
+You can check if your system is properly configured:
+
+```typescript
+import { checkComputerEnvironment } from '@midscene/computer';
+
+const env = await checkComputerEnvironment();
+console.log('Platform:', env.platform);
+console.log('Available:', env.available);
+console.log('Displays:', env.displays);
+
+if (!env.available) {
+  console.error('Environment not available:', env.error);
+}
+```
+
+## FAQ
+
+### macOS: Script cannot control mouse or keyboard
+
+macOS requires Accessibility permissions for keyboard and mouse control. Go to **System Settings > Privacy & Security > Accessibility** and enable the toggle for the application running your script (e.g., Terminal, iTerm2, VS Code, or WebStorm).
+
+If you have already granted permission but it still doesn't work, try removing the app from the Accessibility list and re-adding it — macOS sometimes caches stale permissions.
+
+### Windows: clicks have no effect on some apps
+
+If the cursor moves to the correct position but clicks or key presses do nothing on a particular application — while other apps work fine — check whether the target app is running **as Administrator** (elevated). Windows UIPI blocks input injected from a lower-privilege process into an elevated window and drops it silently, with no error.
+
+Prefer lowering the target application's privilege level first, for example by launching it without "Run as Administrator" or disabling any setting that always starts it elevated. If the target app must stay elevated, run the terminal or Node.js that launches Midscene **as Administrator** so it matches the target app's privilege level, then try again. System-level shortcuts such as `Win+Tab` are handled by the shell and keep working even when this happens, which is why keyboard shortcuts may appear to work while in-app clicks do not.
+
+> The health check logged at connection time prints this troubleshooting link when Midscene is not running as Administrator on Windows.
+
+### Linux: Screenshots or interactions fail on a headless server
+
+A headless Linux environment (e.g. CI) has no physical display. You need to install Xvfb and ImageMagick, and enable headless mode:
+
+```bash
+sudo apt-get install -y xvfb x11-xserver-utils imagemagick
+```
+
+```typescript
+const agent = await agentForComputer({ headless: true });
+```
+
+Or set the environment variable:
+
+```bash
+MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
+```
+
+## API reference {#api-reference}
+
+This section documents the PC desktop-specific APIs provided by `@midscene/computer`.
+
+For common APIs that work across all platforms, see [Common API Reference](./api).
+
+### Agent Creation
+
+`agentForComputer(opts?): Promise<ComputerAgent>`
+
+Create an agent for local desktop automation.
+
+> Backward compatibility: `agentFromComputer` is still available as an alias.
+
+`agentForRDPComputer(opts): Promise<ComputerAgent<RDPDevice>>`
+
+Create an agent for remote Windows desktop automation over RDP.
+
+**Parameters:**
+
+```typescript
+interface BaseComputerAgentOpt {
+  // Agent options (inherited from AgentOpt)
+  aiActionContext?: string;
+  cache?: boolean;
+  // ... other AgentOpt properties
+
+  customActions?: DeviceAction<any>[];
+}
+
+interface LocalComputerAgentOpt extends BaseComputerAgentOpt {
+
+  // Local desktop options
+  displayId?: string;
+  headless?: boolean;
+  xvfbResolution?: string;
+}
+
+interface RDPComputerAgentOpt extends BaseComputerAgentOpt {
+  host: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  domain?: string;
+  adminSession?: boolean;
+  ignoreCertificate?: boolean;
+  securityProtocol?: 'auto' | 'tls' | 'nla' | 'rdp';
+  desktopWidth?: number;
+  desktopHeight?: number;
+}
+```
+
+#### Local Desktop Options
+
+- `displayId` (optional): Specify which display to control. Get available displays with `ComputerDevice.listDisplays()`.
+- `customActions` (optional): Add custom actions to the device.
+- `headless` (optional, Linux only): Set to `true` to start a virtual display via [Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml), enabling desktop automation on headless Linux servers and CI environments without a physical display. Can also be set via the `MIDSCENE_COMPUTER_HEADLESS_LINUX=true` environment variable.
+- `xvfbResolution` (optional): Resolution for the Xvfb virtual display. Defaults to `'1920x1080x24'`.
+
+#### RDP Options
+
+- `host`: Remote Windows host or IP.
+- `port`: RDP port. Defaults to `3389`.
+- `username` / `password`: Credentials for the remote session.
+- `domain`: Optional Windows domain.
+- `adminSession`: Request the remote admin session when the server allows it.
+- `ignoreCertificate`: Skip certificate validation for self-signed setups.
+- `securityProtocol`: Choose `'auto'`, `'tls'`, `'nla'`, or `'rdp'`.
+- `desktopWidth` / `desktopHeight`: Request a specific remote desktop resolution.
+
+:::tip Example: Testing Electron Apps on Headless Linux CI
+A complete demo of testing [Obsidian](https://obsidian.md/) (an Electron app) on headless Linux CI with `@midscene/computer`: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
+:::
+
+**Example:**
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+// Connect to primary display
+const agent = await agentForComputer({
+  aiActionContext: 'You are automating a desktop application.',
+});
+
+// Connect to specific display
+const displays = await ComputerDevice.listDisplays();
+const agent2 = await agentForComputer({
+  displayId: displays[1].id,
+});
+```
+
+**Example: connect to a remote Windows desktop over RDP**
+
+```typescript
+import { agentForRDPComputer } from '@midscene/computer';
+
+const agent = await agentForRDPComputer({
+  aiActionContext:
+    'You are controlling a remote Windows desktop over the RDP protocol.',
+  host: '10.75.166.249',
+  port: 3389,
+  username: 'Admin',
+  password: 'replace-with-your-password',
+  // Optional: bind the TCP connection to this local source IP.
+  localAddress: '10.75.166.10',
+  ignoreCertificate: true,
+});
+
+await agent.aiWaitFor('The remote Windows desktop is visible');
+await agent.aiAct('Click the Windows Start button');
+await agent.aiAct('Open Settings');
+```
+
+:::tip Example: Remote Windows desktop over RDP
+A runnable demo that connects to a remote Windows machine over RDP, opens Settings, navigates into Windows Update, and emits a structured report: [https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
+:::
+
+Use `localAddress` only when the machine running Midscene has multiple outbound
+routes and the RDP server must be reached from a specific local source IP. Pass
+an IP address, not a network interface name.
+
+### Device Management
+
+`ComputerDevice.listDisplays(): Promise<DisplayInfo[]>`
+
+List all available displays.
+
+**Returns:**
+
+```typescript
+interface DisplayInfo {
+  id: string;
+  name: string;
+  primary?: boolean;
+}
+```
+
+**Example:**
+
+```typescript
+import { ComputerDevice } from '@midscene/computer';
+
+const displays = await ComputerDevice.listDisplays();
+console.log('Available displays:', displays);
+// [
+//   { id: '0', name: 'Built-in Display', primary: true },
+//   { id: '1', name: 'External Display', primary: false }
+// ]
+```
+
+`checkComputerEnvironment(): Promise<EnvironmentCheck>`
+
+Check if the computer environment is properly configured.
+
+**Returns:**
+
+```typescript
+interface EnvironmentCheck {
+  available: boolean;
+  error?: string;
+  platform: string;
+  displays: number;
+}
+```
+
+**Example:**
+
+```typescript
+import { checkComputerEnvironment } from '@midscene/computer';
+
+const env = await checkComputerEnvironment();
+console.log('Environment check:', env);
+
+if (!env.available) {
+  console.error('Environment error:', env.error);
+}
+```
+
+### ComputerAgent
+
+The `ComputerAgent` class extends `PageAgent<ComputerDevice>` and inherits all common agent methods:
+
+- `aiAct(action: string)`: Perform an action with AI
+- `aiQuery(query: string)`: Extract information with AI
+- `aiAssert(assertion: string)`: Assert a condition with AI
+- `aiWaitFor(condition: string)`: Wait for a condition
+- `aiLocate(description: string)`: Locate an element
+- And more...
+
+Instant actions are also available for direct, deterministic control once an element is located:
+
+- `aiTap()`, `aiDoubleClick()`, `aiRightClick()`, `aiHover()`: Mouse actions
+- `aiInput()`, `aiClearInput()`, `aiKeyboardPress()`: Keyboard actions
+- `aiScroll()`: Scroll action
+
+See [Common API Reference](./api) for details.
+
+### Available Actions
+
+The `ComputerDevice` supports the following actions:
+
+#### Mouse Actions
+
+##### Tap (Click)
+
+Single click at the target location.
+
+```typescript
+await agent.aiAct('click on the File menu');
+await agent.aiAct('click at center of screen');
+```
+
+##### DoubleClick
+
+Double-click at the target location.
+
+```typescript
+await agent.aiAct('double-click on the desktop icon');
+```
+
+##### RightClick
+
+Right-click to open context menu.
+
+```typescript
+await agent.aiAct('right-click on the desktop');
+await agent.aiAct('right-click on the file');
+```
+
+##### MouseMove (Hover)
+
+Move the mouse to an element — also known as hovering — for example to reveal a hover menu or tooltip.
+
+```typescript
+// Natural-language form (move mouse / hover)
+await agent.aiAct('move mouse to the menu item');
+
+// Instant action: locate and hover in one call
+await agent.aiHover('the menu item "Products"');
+```
+
+##### DragAndDrop
+
+Drag from one location and drop at another.
+
+```typescript
+await agent.aiAct('drag the file to the folder');
+```
+
+#### Keyboard Actions
+
+##### KeyboardPress
+
+Press keyboard keys with optional modifiers.
+
+**Supported keys:**
+- Regular keys: `a-z`, `0-9`, `Enter`, `Escape`, `Space`, `Tab`, etc.
+- Arrow keys: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`
+- Function keys: `F1`-`F12`
+- Modifiers: `Command`/`Cmd` (macOS), `Control`/`Ctrl`, `Alt`, `Shift`, `Win` (Windows)
+- Media keys: `VolumeUp`, `VolumeDown`, `Mute`, etc.
+
+**Examples:**
+
+```typescript
+// Simple key press
+await agent.aiAct('press Enter');
+await agent.aiAct('press Escape');
+
+// Key combinations (platform-specific)
+if (process.platform === 'darwin') {
+  // macOS
+  await agent.aiAct('press Cmd+Space');  // Open Spotlight
+  await agent.aiAct('press Cmd+Tab');    // App switcher
+  await agent.aiAct('press Cmd+C');      // Copy
+  await agent.aiAct('press Cmd+V');      // Paste
+} else {
+  // Windows/Linux
+  await agent.aiAct('press Windows key'); // Start menu
+  await agent.aiAct('press Alt+Tab');     // App switcher
+  await agent.aiAct('press Ctrl+C');      // Copy
+  await agent.aiAct('press Ctrl+V');      // Paste
+}
+
+// Arrow keys
+await agent.aiAct('press ArrowDown');
+await agent.aiAct('press ArrowUp');
+
+// Function keys
+await agent.aiAct('press F5');  // Refresh
+```
+
+##### Input
+
+Type text into an input field.
+
+```typescript
+await agent.aiAct('type "Hello World" in the search box');
+await agent.aiAct('type "my-document.txt"');
+```
+
+##### ClearInput
+
+Clear the content of an input field.
+
+```typescript
+await agent.aiAct('clear the text field');
+```
+
+#### Scroll Actions
+
+Scroll the screen or a specific area.
+
+```typescript
+// Scroll directions
+await agent.aiAct('scroll down');
+await agent.aiAct('scroll up');
+await agent.aiAct('scroll left');
+await agent.aiAct('scroll right');
+
+// Scroll to positions
+await agent.aiAct('scroll to top');
+await agent.aiAct('scroll to bottom');
+```
+
+#### Display Actions
+
+##### ListDisplays
+
+Get information about all connected displays.
+
+```typescript
+const displays = await ComputerDevice.listDisplays();
+```
+
+When you use RDP, `ListDisplays` returns the current remote session as a single display.
+
+### Examples
+
+#### Open Application and Navigate
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+const agent = await agentForComputer();
+
+// Open application
+if (process.platform === 'darwin') {
+  await agent.aiAct('press Cmd+Space');
+  await agent.aiAct('type "TextEdit" and press Enter');
+} else {
+  await agent.aiAct('press Windows key');
+  await agent.aiAct('type "Notepad" and press Enter');
+}
+
+await agent.aiWaitFor('text editor window is visible');
+
+// Type content
+await agent.aiAct('type "Hello, Midscene!"');
+
+// Save file
+if (process.platform === 'darwin') {
+  await agent.aiAct('press Cmd+S');
+} else {
+  await agent.aiAct('press Ctrl+S');
+}
+```
+
+#### Multi-Display Workflow
+
+```typescript
+import { ComputerDevice, agentForComputer } from '@midscene/computer';
+
+// List displays
+const displays = await ComputerDevice.listDisplays();
+console.log(`Found ${displays.length} displays`);
+
+// Control primary display
+const agent1 = await agentForComputer({
+  displayId: displays[0].id,
+});
+await agent1.aiAct('move mouse to center of screen');
+
+// Control secondary display
+if (displays.length > 1) {
+  const agent2 = await agentForComputer({
+    displayId: displays[1].id,
+  });
+  await agent2.aiAct('move mouse to center of screen');
+}
+```
+
+#### Web Browser Automation
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+const agent = await agentForComputer();
+
+// Open browser
+if (process.platform === 'darwin') {
+  await agent.aiAct('press Cmd+Space');
+  await agent.aiAct('type "Safari" and press Enter');
+} else {
+  await agent.aiAct('press Windows key');
+  await agent.aiAct('type "Chrome" and press Enter');
+}
+
+await agent.aiWaitFor('browser window is open');
+
+// Navigate
+await agent.aiAct('click on address bar');
+await agent.aiAct('type "example.com" and press Enter');
+await agent.aiWaitFor('page has loaded');
+
+// Extract information
+const title = await agent.aiQuery('string, get the page title');
+console.log('Page title:', title);
+```
+
+### TypeScript Types
+
+```typescript
+import type {
+  ComputerAgent,
+  ComputerAgentOpt,
+  ComputerDevice,
+  ComputerDeviceOpt,
+  DisplayInfo,
+  EnvironmentCheck,
+} from '@midscene/computer';
+```
+
+### See Also
+
+- [Common API Reference](./api) - APIs that work across all platforms
+- [Model Configuration](./model-config) - Configure AI models
+- [Caching](./caching) - Improve performance with caching
diff --git a/apps/site/docs/en/faq.md b/apps/site/docs/en/faq.md
index 1b7f23f485..f1909a0fd1 100644
--- a/apps/site/docs/en/faq.md
+++ b/apps/site/docs/en/faq.md
@@ -8,10 +8,10 @@ The following platform-specific FAQs are maintained in their respective document
 - [Web Browser - Puppeteer](./integrate-with-puppeteer#faq)
 - [Web Browser - Chrome Extension](./quick-experience#faq)
 - [Web Browser - Bridge Mode](./bridge-mode#faq)
-- [Android](./android-getting-started#faq)
-- [iOS](./ios-getting-started#faq)
-- [HarmonyOS](./harmony-getting-started#faq)
-- [PC Desktop](./computer-getting-started#faq)
+- [Android](./android#faq)
+- [iOS](./ios#faq)
+- [HarmonyOS](./harmony#faq)
+- [PC Desktop](./computer#faq)
 
 ## What data is sent to AI model?
 
diff --git a/apps/site/docs/en/harmony-api-reference.mdx b/apps/site/docs/en/harmony-api-reference.mdx
deleted file mode 100644
index 2ff451c0d2..0000000000
--- a/apps/site/docs/en/harmony-api-reference.mdx
+++ /dev/null
@@ -1,217 +0,0 @@
-# API Reference (HarmonyOS)
-
-When you need to customize device behavior, integrate Midscene into a framework, or troubleshoot HDC issues, refer to this section. For common constructor parameters (reports, hooks, caching, etc.), see the platform-agnostic [API Reference](./api).
-
-## Action Space
-
-`HarmonyDevice` uses the following action space. The Midscene Agent can use these operations when planning tasks:
-
-- `Tap` — Tap on an element.
-- `DoubleClick` — Double-tap on an element.
-- `Input` — Input text, supporting `replace`/`typeOnly`/`clear` modes.
-- `Scroll` — Scroll from an element or screen center in any direction, supporting scroll-to-top/bottom/left/right.
-- `DragAndDrop` — Drag from one element to another.
-- `KeyboardPress` — Press a specific key.
-- `LongPress` — Long-press a target element with optional custom duration.
-- `ClearInput` — Clear input field contents.
-- ~~`Pinch`~~ — Not supported. The HarmonyOS `uitest` framework does not provide multi-touch input APIs.
-- `Launch` — Open a HarmonyOS app (bundle name).
-- `Terminate` — Force-stop a HarmonyOS app by bundle name.
-- `RunHdcShell` — Execute a raw `hdc shell` command.
-- `HarmonyBackButton` — Trigger system back.
-- `HarmonyHomeButton` — Return to home screen.
-- `HarmonyRecentAppsButton` — Open recent apps / multitasking.
-
-## HarmonyDevice {#harmonydevice}
-
-Creates an HDC device instance that can be driven by HarmonyAgent.
-
-### Import
-
-```ts
-import { HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
-```
-
-### Constructor
-
-```ts
-const device = new HarmonyDevice(deviceId, {
-  // device options...
-});
-```
-
-### Device Options
-
-- `deviceId: string` — Value from `hdc list targets` or `getConnectedDevices()`.
-- `hdcPath?: string` — Custom path to the HDC executable. If not set, it searches `HDC_HOME` environment variable and common installation paths.
-- `autoDismissKeyboard?: boolean` — Automatically hide keyboard after input, default `true`.
-- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` — Key preference for automatically hiding the keyboard, default `'esc-first'`. HarmonyOS sends the first key from the strategy only: `'esc-first'` sends ESC, while `'back-first'` sends Back.
-- `screenshotResizeScale?: number` — **Deprecated.** This option has been removed and no longer has any effect. Use `screenshotShrinkFactor` in `AgentOpt` instead to control screenshot size sent to the AI model.
-- `customActions?: DeviceAction[]` — Extend the planner's available actions via `defineAction`.
-
-### Usage Notes
-
-- Use `getConnectedDevices()` to discover devices. The returned `deviceId` matches `hdc list targets` output.
-- If HDC is not in your system PATH, specify it via the `HDC_HOME` environment variable or the `hdcPath` option.
-
-### Examples
-
-#### Quick Start
-
-```ts
-import { HarmonyAgent, HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
-
-const [first] = await getConnectedDevices();
-const device = new HarmonyDevice(first.deviceId, {});
-await device.connect();
-
-const agent = new HarmonyAgent(device, {
-  aiActionContext: 'This is a HarmonyOS device. If any popup appears, agree to it.',
-});
-
-await agent.launch('com.huawei.hmos.settings');
-await agent.aiAct('scroll down one screen');
-const items = await agent.aiQuery(
-  'string[], list all visible setting item names',
-);
-console.log(items);
-```
-
-#### Launch Apps
-
-```ts
-await agent.launch('com.huawei.hmos.settings'); // Open Settings
-await agent.launch('com.huawei.hmos.camera');    // Open Camera
-await agent.back();
-await agent.home();
-```
-
-## HarmonyAgent {#harmonyagent}
-
-Binds Midscene's AI planning capabilities to a HarmonyDevice for UI automation.
-
-### Import
-
-```ts
-import { HarmonyAgent } from '@midscene/harmony';
-```
-
-### Constructor
-
-```ts
-const agent = new HarmonyAgent(device, {
-  // common Agent options...
-});
-```
-
-### HarmonyOS-Specific Options
-
-- `customActions?: DeviceAction[]` — Extend the planner's available actions via `defineAction`.
-- `appNameMapping?: Record<string, string>` — Map friendly app names to bundle names. When you pass an app name to `launch(target)`, the Agent looks up the corresponding bundle name in this mapping; if no mapping is found, it tries to launch `target` as-is.
-- Other fields are the same as [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, etc.
-
-### Usage Notes
-
-:::info
-
-- One device connection corresponds to one Agent.
-- HarmonyOS-specific helpers like `launch`, `terminate`, and `runHdcShell` can also be used in YAML scripts. See [HarmonyOS platform-specific actions](./automate-with-scripts-in-yaml#the-harmony-part).
-- For common interaction methods, see [API Reference (Common)](./api#interaction-methods).
-
-:::
-
-### HarmonyOS-Specific Methods
-
-#### `agent.launch()`
-
-Launch a HarmonyOS app.
-
-```ts
-function launch(uri: string): Promise<void>;
-```
-
-- `uri: string` — Can be an app bundle name (e.g., `com.huawei.hmos.settings`), or an app name registered in `appNameMapping`. If a URL starting with `http://` or `https://` is passed, it opens via the browser.
-
-```ts
-await agent.launch('com.huawei.hmos.settings'); // Open Settings
-await agent.launch('com.huawei.hmos.camera');    // Open Camera
-```
-
-#### `agent.runHdcShell()`
-
-Run a raw `hdc shell` command on the connected device.
-
-```ts
-function runHdcShell(command: string): Promise<string>;
-```
-
-- `command: string` — The command passed directly to `hdc shell`.
-
-```ts
-const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
-console.log(result);
-```
-
-#### `agent.terminate()`
-
-Terminate (force-stop) a running HarmonyOS app.
-
-```ts
-function terminate(uri: string): Promise<void>;
-```
-
-- `uri: string` — Bundle name, app name in `appNameMapping`, or `bundle/Ability` (only the bundle part is used).
-
-```ts
-await agent.terminate('com.huawei.hmos.settings');
-```
-
-#### Navigation Helpers
-
-- `agent.back(): Promise<void>` — Trigger HarmonyOS system back.
-- `agent.home(): Promise<void>` — Return to home screen.
-- `agent.recentApps(): Promise<void>` — Open recent apps / multitasking.
-
-### Utilities
-
-#### `agentFromHdcDevice()`
-
-Create a `HarmonyAgent` from any connected HDC device.
-
-```ts
-function agentFromHdcDevice(
-  deviceId?: string,
-  opts?: HarmonyAgentOpt & HarmonyDeviceOpt,
-): Promise<HarmonyAgent>;
-```
-
-- `deviceId?: string` — Connect to a specific device; leave empty for "first available device".
-- `opts?: HarmonyAgentOpt & HarmonyDeviceOpt` — Merge Agent options and [`HarmonyDevice`](#harmonydevice) settings in a single object.
-
-```ts
-import { agentFromHdcDevice } from '@midscene/harmony';
-
-const agent = await agentFromHdcDevice('0123456789ABCDEF'); // specific device
-const agent = await agentFromHdcDevice(); // first available device
-```
-
-#### `getConnectedDevices()`
-
-List HDC devices that Midscene can drive.
-
-```ts
-function getConnectedDevices(
-  hdcPath?: string,
-): Promise<Array<{ deviceId: string }>>;
-```
-
-```ts
-import { getConnectedDevices } from '@midscene/harmony';
-
-const devices = await getConnectedDevices();
-console.log(devices); // [{ deviceId: '0123456789ABCDEF' }]
-```
-
-### Related Reading
-
-- [HarmonyOS Getting Started](./harmony-getting-started) for setup and script examples.
diff --git a/apps/site/docs/en/harmony-introduction.mdx b/apps/site/docs/en/harmony-introduction.mdx
deleted file mode 100644
index 372c021238..0000000000
--- a/apps/site/docs/en/harmony-introduction.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
-import ShowcaseHarmony from './showcases-harmony.mdx';
-
-# HarmonyOS Automation Support
-
-Midscene can drive the HDC (HarmonyOS Device Connector) tool to automate HarmonyOS NEXT devices.
-
-Thanks to its visual model approach, the entire automation process works with any HarmonyOS app technology stack — whether ArkTS native or other frameworks. Developers only need to debug UI automation scripts against the final rendered interface.
-
-The HarmonyOS UI automation solution includes all Midscene features:
-
-- Zero-code trial via Playground.
-- JavaScript SDK support.
-- YAML-based automation scripts and CLI tools.
-- HTML report generation for replaying all action paths.
-
-## Showcases
-
-<ShowcaseHarmony />
-
-See more showcases: [showcases](./showcases.mdx)
-
-## Try Midscene Playground on HarmonyOS
-
-With Midscene.js Playground, you can experience HarmonyOS automation without writing any code.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/harmony.mp4" controls/>
-
-See [Getting Started](./harmony-getting-started#try-playground-zero-code) to learn how to launch Playground.
-
-## Next Steps
-
-* [Getting Started](./harmony-getting-started)
-* [Using JavaScript SDK](./harmony-getting-started)
-* [Using YAML automation scripts](./automate-with-scripts-in-yaml) and [CLI tools](./automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/en/harmony-getting-started.mdx b/apps/site/docs/en/harmony.mdx
similarity index 56%
rename from apps/site/docs/en/harmony-getting-started.mdx
rename to apps/site/docs/en/harmony.mdx
index d25291baee..4974585377 100644
--- a/apps/site/docs/en/harmony-getting-started.mdx
+++ b/apps/site/docs/en/harmony.mdx
@@ -1,9 +1,18 @@
+import ShowcaseHarmony from './showcases-harmony.mdx';
 import StartExperience from './common/start-experience.mdx';
 import SetupEnv from './common/setup-env.mdx';
 
 import { PackageManagerTabs } from '@theme';
 
-# HarmonyOS Getting Started
+# HarmonyOS Automation Support
+
+Midscene can drive the HDC (HarmonyOS Device Connector) tool to automate HarmonyOS NEXT devices.
+
+## Showcases
+
+<ShowcaseHarmony />
+
+See more showcases: [showcases](./showcases.mdx)
 
 This guide walks you through everything needed to automate HarmonyOS devices with Midscene: connecting a real device via HDC, configuring model API keys, trying the zero-code Playground, and running your first JavaScript script.
 
@@ -143,7 +152,7 @@ After a successful run, the console outputs `Midscene - report file updated: /pa
 
 ## Advanced
 
-When you need to customize device behavior, integrate Midscene into a standalone framework, or troubleshoot HDC issues, refer to this section. See [API Reference (HarmonyOS)](./harmony-api-reference) for more constructor parameters.
+When you need to customize device behavior, integrate Midscene into a standalone framework, or troubleshoot HDC issues, refer to this section. See [API Reference (HarmonyOS)](#api-reference) for more constructor parameters.
 
 ### Extending Midscene on HarmonyOS
 
@@ -184,7 +193,7 @@ For more details on custom actions and action schemas, see [Integrate with Any I
 ## More
 
 - View all Agent methods: [API Reference (Common)](./api#interaction-methods)
-- HarmonyOS-specific parameters and interfaces: [HarmonyOS Agent API](./harmony-api-reference)
+- HarmonyOS-specific parameters and interfaces: [HarmonyOS Agent API](#api-reference)
 - Demo projects
   - HarmonyOS JavaScript SDK demo: [https://github.com/web-infra-dev/midscene-example/blob/main/harmony/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/harmony/javascript-sdk-demo)
   - HarmonyOS + Vitest demo: [https://github.com/web-infra-dev/midscene-example/tree/main/harmony/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/harmony/vitest-demo)
@@ -320,3 +329,217 @@ const device = new HarmonyDevice('0123456789ABCDEF', {
   hdcPath: '/path/to/hdc',
 });
 ```
+
+## API reference {#api-reference}
+
+When you need to customize device behavior, integrate Midscene into a framework, or troubleshoot HDC issues, refer to this section. For common constructor parameters (reports, hooks, caching, etc.), see the platform-agnostic [API Reference](./api).
+
+### Action Space
+
+`HarmonyDevice` uses the following action space. The Midscene Agent can use these operations when planning tasks:
+
+- `Tap` — Tap on an element.
+- `DoubleClick` — Double-tap on an element.
+- `Input` — Input text, supporting `replace`/`typeOnly`/`clear` modes.
+- `Scroll` — Scroll from an element or screen center in any direction, supporting scroll-to-top/bottom/left/right.
+- `DragAndDrop` — Drag from one element to another.
+- `KeyboardPress` — Press a specific key.
+- `LongPress` — Long-press a target element with optional custom duration.
+- `ClearInput` — Clear input field contents.
+- ~~`Pinch`~~ — Not supported. The HarmonyOS `uitest` framework does not provide multi-touch input APIs.
+- `Launch` — Open a HarmonyOS app (bundle name).
+- `Terminate` — Force-stop a HarmonyOS app by bundle name.
+- `RunHdcShell` — Execute a raw `hdc shell` command.
+- `HarmonyBackButton` — Trigger system back.
+- `HarmonyHomeButton` — Return to home screen.
+- `HarmonyRecentAppsButton` — Open recent apps / multitasking.
+
+### HarmonyDevice {#harmonydevice}
+
+Creates an HDC device instance that can be driven by HarmonyAgent.
+
+#### Import
+
+```ts
+import { HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
+```
+
+#### Constructor
+
+```ts
+const device = new HarmonyDevice(deviceId, {
+  // device options...
+});
+```
+
+#### Device Options
+
+- `deviceId: string` — Value from `hdc list targets` or `getConnectedDevices()`.
+- `hdcPath?: string` — Custom path to the HDC executable. If not set, it searches `HDC_HOME` environment variable and common installation paths.
+- `autoDismissKeyboard?: boolean` — Automatically hide keyboard after input, default `true`.
+- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` — Key preference for automatically hiding the keyboard, default `'esc-first'`. HarmonyOS sends the first key from the strategy only: `'esc-first'` sends ESC, while `'back-first'` sends Back.
+- `screenshotResizeScale?: number` — **Deprecated.** This option has been removed and no longer has any effect. Use `screenshotShrinkFactor` in `AgentOpt` instead to control screenshot size sent to the AI model.
+- `customActions?: DeviceAction[]` — Extend the planner's available actions via `defineAction`.
+
+#### Usage Notes
+
+- Use `getConnectedDevices()` to discover devices. The returned `deviceId` matches `hdc list targets` output.
+- If HDC is not in your system PATH, specify it via the `HDC_HOME` environment variable or the `hdcPath` option.
+
+#### Examples
+
+##### Quick Start
+
+```ts
+import { HarmonyAgent, HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
+
+const [first] = await getConnectedDevices();
+const device = new HarmonyDevice(first.deviceId, {});
+await device.connect();
+
+const agent = new HarmonyAgent(device, {
+  aiActionContext: 'This is a HarmonyOS device. If any popup appears, agree to it.',
+});
+
+await agent.launch('com.huawei.hmos.settings');
+await agent.aiAct('scroll down one screen');
+const items = await agent.aiQuery(
+  'string[], list all visible setting item names',
+);
+console.log(items);
+```
+
+##### Launch Apps
+
+```ts
+await agent.launch('com.huawei.hmos.settings'); // Open Settings
+await agent.launch('com.huawei.hmos.camera');    // Open Camera
+await agent.back();
+await agent.home();
+```
+
+### HarmonyAgent {#harmonyagent}
+
+Binds Midscene's AI planning capabilities to a HarmonyDevice for UI automation.
+
+#### Import
+
+```ts
+import { HarmonyAgent } from '@midscene/harmony';
+```
+
+#### Constructor
+
+```ts
+const agent = new HarmonyAgent(device, {
+  // common Agent options...
+});
+```
+
+#### HarmonyOS-Specific Options
+
+- `customActions?: DeviceAction[]` — Extend the planner's available actions via `defineAction`.
+- `appNameMapping?: Record<string, string>` — Map friendly app names to bundle names. When you pass an app name to `launch(target)`, the Agent looks up the corresponding bundle name in this mapping; if no mapping is found, it tries to launch `target` as-is.
+- Other fields are the same as [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, etc.
+
+#### Usage Notes
+
+:::info
+
+- One device connection corresponds to one Agent.
+- HarmonyOS-specific helpers like `launch`, `terminate`, and `runHdcShell` can also be used in YAML scripts. See [HarmonyOS platform-specific actions](./automate-with-scripts-in-yaml#the-harmony-part).
+- For common interaction methods, see [API Reference (Common)](./api#interaction-methods).
+
+:::
+
+#### HarmonyOS-Specific Methods
+
+##### `agent.launch()`
+
+Launch a HarmonyOS app.
+
+```ts
+function launch(uri: string): Promise<void>;
+```
+
+- `uri: string` — Can be an app bundle name (e.g., `com.huawei.hmos.settings`), or an app name registered in `appNameMapping`. If a URL starting with `http://` or `https://` is passed, it opens via the browser.
+
+```ts
+await agent.launch('com.huawei.hmos.settings'); // Open Settings
+await agent.launch('com.huawei.hmos.camera');    // Open Camera
+```
+
+##### `agent.runHdcShell()`
+
+Run a raw `hdc shell` command on the connected device.
+
+```ts
+function runHdcShell(command: string): Promise<string>;
+```
+
+- `command: string` — The command passed directly to `hdc shell`.
+
+```ts
+const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
+console.log(result);
+```
+
+##### `agent.terminate()`
+
+Terminate (force-stop) a running HarmonyOS app.
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` — Bundle name, app name in `appNameMapping`, or `bundle/Ability` (only the bundle part is used).
+
+```ts
+await agent.terminate('com.huawei.hmos.settings');
+```
+
+##### Navigation Helpers
+
+- `agent.back(): Promise<void>` — Trigger HarmonyOS system back.
+- `agent.home(): Promise<void>` — Return to home screen.
+- `agent.recentApps(): Promise<void>` — Open recent apps / multitasking.
+
+#### Utilities
+
+##### `agentFromHdcDevice()`
+
+Create a `HarmonyAgent` from any connected HDC device.
+
+```ts
+function agentFromHdcDevice(
+  deviceId?: string,
+  opts?: HarmonyAgentOpt & HarmonyDeviceOpt,
+): Promise<HarmonyAgent>;
+```
+
+- `deviceId?: string` — Connect to a specific device; leave empty for "first available device".
+- `opts?: HarmonyAgentOpt & HarmonyDeviceOpt` — Merge Agent options and [`HarmonyDevice`](#harmonydevice) settings in a single object.
+
+```ts
+import { agentFromHdcDevice } from '@midscene/harmony';
+
+const agent = await agentFromHdcDevice('0123456789ABCDEF'); // specific device
+const agent = await agentFromHdcDevice(); // first available device
+```
+
+##### `getConnectedDevices()`
+
+List HDC devices that Midscene can drive.
+
+```ts
+function getConnectedDevices(
+  hdcPath?: string,
+): Promise<Array<{ deviceId: string }>>;
+```
+
+```ts
+import { getConnectedDevices } from '@midscene/harmony';
+
+const devices = await getConnectedDevices();
+console.log(devices); // [{ deviceId: '0123456789ABCDEF' }]
+```
diff --git a/apps/site/docs/en/integrate-with-any-interface.mdx b/apps/site/docs/en/integrate-with-any-interface.mdx
index 58ca83fecc..b5eade2125 100644
--- a/apps/site/docs/en/integrate-with-any-interface.mdx
+++ b/apps/site/docs/en/integrate-with-any-interface.mdx
@@ -376,7 +376,7 @@ You can find the parameters of the actions in the type definition of these funct
 
 #### Define a custom action
 
-You can define your own action by using the `defineAction()` function. You can also use this method to define more actions for the [PuppeteerAgent](./integrate-with-puppeteer), [AgentOverChromeBridge](./bridge-mode#constructor), and [AndroidAgent](./android-getting-started).
+You can define your own action by using the `defineAction()` function. You can also use this method to define more actions for the [PuppeteerAgent](./integrate-with-puppeteer), [AgentOverChromeBridge](./bridge-mode#constructor), and [AndroidAgent](./android).
 
 API Signature:
 
diff --git a/apps/site/docs/en/ios-api-reference.mdx b/apps/site/docs/en/ios-api-reference.mdx
deleted file mode 100644
index 5f8aff220b..0000000000
--- a/apps/site/docs/en/ios-api-reference.mdx
+++ /dev/null
@@ -1,240 +0,0 @@
-# API reference (iOS)
-
-Use this doc when you need to customize iOS device behavior, wire Midscene into WebDriverAgent-driven workflows, or troubleshoot WDA requests. For shared constructor options (reporting, hooks, caching, etc.), see the platform-agnostic [API reference (Common)](./api).
-
-## Action Space
-
-`IOSDevice` uses the following action space; the Midscene Agent can use these actions while planning tasks:
-
-- `Tap` &mdash; Tap an element.
-- `DoubleClick` &mdash; Double-tap an element.
-- `Input` &mdash; Enter text with `replace`/`typeOnly`/`clear` modes (`append` is a deprecated alias for `typeOnly`). Supports optional `autoDismissKeyboard` parameter.
-- `Scroll` &mdash; Scroll from an element or screen center in any direction, including scroll-to-top/bottom/left/right helpers.
-- `DragAndDrop` &mdash; Drag from one element to another.
-- `KeyboardPress` &mdash; Press a specified key.
-- `LongPress` &mdash; Long-press a target element with optional duration.
-- `Pinch` &mdash; Two-finger pinch gesture. Use `scale > 1` to zoom in, `scale < 1` to zoom out.
-- `ClearInput` &mdash; Clear the contents of an input field.
-- `Launch` &mdash; Open a URL, bundle identifier, or URL scheme.
-- `Terminate` &mdash; Close a running iOS app by its bundle identifier.
-- `RunWdaRequest` &mdash; Call WebDriverAgent REST endpoints directly.
-- `IOSHomeButton` &mdash; Trigger the iOS system Home action.
-- `IOSAppSwitcher` &mdash; Open the iOS multitasking view.
-
-## IOSDevice {#iosdevice}
-
-Create a WebDriverAgent-backed instance that an IOSAgent can drive.
-
-### Import
-
-```ts
-import { IOSDevice } from '@midscene/ios';
-```
-
-### Constructor
-
-```ts
-const device = new IOSDevice({
-  // device options...
-});
-```
-
-### Device options
-
-- `wdaPort?: number` &mdash; WebDriverAgent port. Default `8100`.
-- `wdaHost?: string` &mdash; WebDriverAgent host. Default `'localhost'`.
-- `iOSDeviceClassOverride?: string` &mdash; Optional npm module path that replaces the default `IOSDevice` when using `agentFromWebDriverAgent()` or iOS Playground. The module must export an `IOSDevice` class or a default class.
-- `autoDismissKeyboard?: boolean` &mdash; Hide the keyboard after text input. Default `true`.
-- `customActions?: DeviceAction<any>[]` &mdash; Additional device actions exposed to the agent.
-
-### Usage notes
-
-- Ensure Developer Mode is enabled and WDA can reach the device; use `iproxy` when forwarding ports from a real device.
-- Use `wdaHost`/`wdaPort` to target remote devices or custom WDA deployments.
-- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
-
-### Examples
-
-#### Quick start
-
-```ts
-import { IOSAgent, IOSDevice } from '@midscene/ios';
-
-const device = new IOSDevice({ wdaHost: 'localhost', wdaPort: 8100 });
-await device.connect();
-
-const agent = new IOSAgent(device, {
-  aiActionContext: 'If any permission dialog appears, accept it.',
-});
-
-await agent.launch('https://ebay.com');
-await agent.aiAct('Search for "Headphones"');
-const items = await agent.aiQuery(
-  '{itemTitle: string, price: Number}[], list headphone products',
-);
-console.log(items);
-```
-
-#### Custom host and port
-
-```ts
-const device = new IOSDevice({
-  wdaHost: '192.168.1.100',
-  wdaPort: 8300,
-});
-await device.connect();
-```
-
-## IOSAgent {#iosagent}
-
-Wire Midscene's AI planner to an IOSDevice for UI automation over WebDriverAgent.
-
-### Import
-
-```ts
-import { IOSAgent } from '@midscene/ios';
-```
-
-### Constructor
-
-```ts
-const agent = new IOSAgent(device, {
-  // common agent options...
-});
-```
-
-### iOS-specific options
-
-- `customActions?: DeviceAction<any>[]` &mdash; Extend planning with actions defined via `defineAction`.
-- `appNameMapping?: Record<string, string>` &mdash; Map friendly app names to bundle identifiers. When you pass an app name to `launch(target)` or `terminate(bundleId)`, the agent will look up the bundle ID in this mapping. If no mapping is found, it will attempt to use `target` as-is. User-provided mappings take precedence over default mappings.
-- All other fields match [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, and more.
-
-### Usage notes
-
-:::info
-
-- Use one agent per device connection.
-- iOS-only helpers such as `launch`, `terminate`, and `runWdaRequest` are also exposed in YAML scripts. See [iOS platform-specific actions](./automate-with-scripts-in-yaml#the-ios-part).
-- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
-
-:::
-
-### iOS-specific methods
-
-#### `agent.launch()`
-
-Launch a web URL, native application bundle, or custom scheme.
-
-```ts
-function launch(target: string): Promise<void>;
-```
-
-- `target: string` &mdash; Target address (web URL, Bundle Identifier, URL scheme, tel/mailto, etc.) or app name. If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped Bundle ID; otherwise, `target` will be launched as-is.
-
-```ts
-await agent.launch('https://www.apple.com');
-await agent.launch('com.apple.Preferences');
-await agent.launch('myapp://profile/user/123');
-await agent.launch('tel:+1234567890');
-```
-
-#### `agent.terminate()`
-
-Terminate (close) a running iOS app by its bundle ID.
-
-```ts
-function terminate(bundleId: string): Promise<void>;
-```
-
-- `bundleId: string` &mdash; The bundle identifier of the app to terminate (e.g. `com.apple.Preferences`). If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped Bundle ID.
-
-```ts
-await agent.terminate('com.apple.Preferences');
-await agent.terminate('com.apple.mobilesafari');
-```
-
-#### `agent.runWdaRequest()`
-
-Execute raw WebDriverAgent REST calls when you need low-level control.
-
-```ts
-function runWdaRequest(
-  method: string,
-  endpoint: string,
-  data?: Record<string, any>,
-): Promise<any>;
-```
-
-- `method: string` &mdash; HTTP verb (`GET`, `POST`, `DELETE`, etc.).
-- `endpoint: string` &mdash; WebDriverAgent endpoint path.
-- `data?: Record<string, any>` &mdash; Optional JSON body.
-
-```ts
-const screen = await agent.runWdaRequest('GET', '/wda/screen');
-await agent.runWdaRequest('POST', '/session/test/wda/pressButton', { name: 'home' });
-```
-
-#### Navigation helpers
-
-- `agent.home(): Promise<void>` &mdash; Return to the Home screen.
-- `agent.appSwitcher(): Promise<void>` &mdash; Reveal the multitasking view.
-
-### Helper utilities
-
-#### `agentFromWebDriverAgent()` {#agentfromwebdriveragent}
-
-Connect to WebDriverAgent and return a ready-to-use IOSAgent.
-
-```ts
-function agentFromWebDriverAgent(
-  opts?: PageAgentOpt & IOSDeviceOpt,
-): Promise<IOSAgent>;
-```
-
-- `opts?: PageAgentOpt & IOSDeviceOpt` &mdash; Combine common agent options with [`IOSDevice`](#iosdevice) settings.
-- Set `MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE` to apply the same device class override through the environment. An explicit option takes precedence over the environment variable.
-
-```ts
-import { agentFromWebDriverAgent } from '@midscene/ios';
-
-const agent = await agentFromWebDriverAgent({
-  wdaHost: 'localhost',
-  wdaPort: 8100,
-  iOSDeviceClassOverride: '@your-scope/ios-device',
-  aiActionContext: 'Accept permission dialogs automatically.',
-});
-```
-
-### Extending custom interaction actions
-
-Extend the Agent's action space by supplying `customActions` with handlers created via `defineAction`. These actions appear after the built-in ones and can be called during planning.
-
-```ts
-import { getMidsceneLocationSchema, z } from '@midscene/core';
-import { defineAction } from '@midscene/core/device';
-import { agentFromWebDriverAgent } from '@midscene/ios';
-
-const ContinuousClick = defineAction({
-  name: 'continuousClick',
-  description: 'Click the same target repeatedly',
-  paramSchema: z.object({
-    locate: getMidsceneLocationSchema(),
-    count: z.number().int().positive().describe('How many times to click'),
-  }),
-  async call({ locate, count }) {
-    console.log('click target center', locate.center);
-    console.log('click count', count);
-  },
-});
-
-const agent = await agentFromWebDriverAgent({
-  customActions: [ContinuousClick],
-});
-
-await agent.aiAct('Click the red button five times');
-```
-
-### See also
-
-- [iOS getting started](./ios-getting-started) for setup and scripting steps.
-- [Integrate with any interface](./integrate-with-any-interface#define-a-custom-action) for custom actions and schemas.
diff --git a/apps/site/docs/en/ios-getting-started.mdx b/apps/site/docs/en/ios-getting-started.mdx
deleted file mode 100644
index 4b3636e873..0000000000
--- a/apps/site/docs/en/ios-getting-started.mdx
+++ /dev/null
@@ -1,192 +0,0 @@
-import StartExperience from './common/start-experience.mdx';
-import SetupEnv from './common/setup-env.mdx';
-import PrepareIOS from './common/prepare-ios.mdx';
-
-import { PackageManagerTabs } from '@theme';
-
-# iOS getting started
-
-This guide walks you through everything required to automate an iOS device with Midscene: connect a real phone through WebDriverAgent, configure model credentials, try the no-code Playground, and run your first JavaScript script.
-
-:::info Demo Projects
-
-Control iOS devices with JavaScript: [https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
-
-Integrate Vitest for testing: [https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
-
-:::
-
-<SetupEnv />
-
-<PrepareIOS />
-
-## Try Playground (no code)
-
-Playground is the fastest way to validate the connection and observe AI-driven steps without writing code. It shares the same core as `@midscene/ios`, so anything that works here will behave the same once scripted.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
-
-1. Launch the Playground CLI:
-
-```bash
-npx --yes @midscene/ios-playground
-```
-
-2. Click the gear button to enter the configuration page and paste your API key config. Refer back to [Model configuration](./model-config) if you still need credentials.
-
-![](/ios-set-env.png)
-
-## Start experiencing
-
-<StartExperience />
-
-## Integration with Midscene Agent
-
-Once Playground works, move to a repeatable script with the JavaScript SDK.
-
-### Step 1. Install dependencies
-
-<PackageManagerTabs command="install @midscene/ios dotenv --save-dev" />
-
-### Step 2. Write scripts
-
-Save the following code as `./demo.ts`. It opens Safari on the device, searches eBay, and asserts the result list.
-
-```typescript title="./demo.ts"
-import 'dotenv/config'; // load Midscene environment variables from .env if present
-import {
-  IOSAgent,
-  IOSDevice,
-  agentFromWebDriverAgent,
-} from '@midscene/ios';
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-Promise.resolve(
-  (async () => {
-    // Method 1: Create device and agent directly
-    const page = new IOSDevice({
-      wdaPort: 8100,
-      wdaHost: 'localhost',
-    });
-
-    // 👀 Initialize Midscene agent
-    const agent = new IOSAgent(page, {
-      aiActionContext:
-        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
-    });
-    await page.connect();
-
-    // Method 2: Or use convenience function (recommended)
-    // const agent = await agentFromWebDriverAgent({
-    //   wdaPort: 8100,
-    //   wdaHost: 'localhost',
-    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
-    // });
-
-    // 👀 Directly open ebay.com webpage (recommended approach)
-    await page.launch('https://ebay.com');
-    await sleep(3000);
-
-    // 👀 Enter keywords and perform search
-    await agent.aiAct('Search for "Headphones"');
-
-    // 👀 Wait for loading to complete
-    await agent.aiWaitFor('At least one headphone product is displayed on the page');
-    // Or you can use a simple sleep:
-    // await sleep(5000);
-
-    // 👀 Understand page content and extract data
-    const items = await agent.aiQuery(
-      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
-    );
-    console.log('Headphone product information', items);
-
-    // 👀 Use AI assertion
-    await agent.aiAssert('Multiple headphone products are displayed on the interface');
-
-    await page.destroy();
-  })(),
-);
-```
-
-### Step 3. Run
-
-```bash
-npx tsx demo.ts
-```
-
-### Step 4: View the report
-
-Successful runs print `Midscene - report file updated: /path/to/report/some_id.html`. Open the generated HTML file in a browser to replay every interaction, query, and assertion.
-
-## API reference and more resources
-
-Looking for constructors, helper methods, and platform-only device APIs? See the dedicated [iOS API reference](./ios-api-reference) for detailed parameter lists plus advanced topics like custom actions. For API surfaces shared across platforms, head to the [common API reference](./api).
-
-## FAQ
-
-### Why can't I control my device through WebDriverAgent even though it's connected?
-
-Please check the following:
-
-1. **Developer Mode**: Ensure it's enabled in Settings > Privacy & Security > Developer Mode
-2. **UI Automation**: Ensure it's enabled in Settings > Developer > UI Automation
-3. **Device Trust**: Ensure the device trusts the current Mac
-
-### What are the differences between simulators and real devices?
-
-| Feature | Real Device | Simulator |
-|---------|-------------|-----------|
-| Port Forwarding | Requires iproxy | Not required |
-| Developer Mode | Must enable | Auto-enabled |
-| UI Automation Settings | Must enable manually | Auto-enabled |
-| Performance | Real device performance | Depends on Mac performance |
-| Sensors | Real hardware | Simulated data |
-
-### How to use custom WebDriverAgent port and host?
-
-You can specify WebDriverAgent port and host through the `IOSDevice` constructor or `agentFromWebDriverAgent`:
-
-```typescript
-// Method 1: Using IOSDevice
-const device = new IOSDevice({
-  wdaPort: 8100,        // Custom port
-  wdaHost: '192.168.1.100', // Custom host
-});
-
-// Method 2: Using convenience function (recommended)
-const agent = await agentFromWebDriverAgent({
-  wdaPort: 8100,        // Custom port
-  wdaHost: '192.168.1.100', // Custom host
-});
-```
-
-For remote devices, you also need to set up port forwarding accordingly:
-
-```bash
-iproxy 8100 8100 YOUR_DEVICE_ID
-```
-
-### How to get smoother live screen preview in Playground?
-
-Playground's screen preview supports two modes:
-
-- **Polling mode** (default): Captures screenshots one by one via the WDA screenshot API, achieving ~5-10fps.
-- **Native MJPEG stream** (recommended): Proxies WDA's built-in MJPEG Server directly for higher frame rate and lower latency.
-
-To enable the native MJPEG stream, forward the WDA MJPEG Server port (default 9100) to localhost:
-
-```bash
-# Required for real devices only (simulators don't need this)
-iproxy 9100 9100 YOUR_DEVICE_ID
-```
-
-Playground automatically probes port 9100 on startup. If available, the log will show `MJPEG: streaming via native WDA MJPEG server`; otherwise it falls back to polling mode automatically.
-
-## More
-
-- For every Agent method, check the [API reference (Common)](./api#interaction-methods).
-- For the iOS API reference, see [iOS Agent API](./ios-api-reference).
-- Demo projects
-  - iOS JavaScript SDK demo: [https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
-  - iOS + Vitest demo: [https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
diff --git a/apps/site/docs/en/ios-introduction.mdx b/apps/site/docs/en/ios-introduction.mdx
deleted file mode 100644
index 01ff110187..0000000000
--- a/apps/site/docs/en/ios-introduction.mdx
+++ /dev/null
@@ -1,53 +0,0 @@
-import ShowcaseIOS from './showcases-ios.mdx';
-
-# iOS Automation Support
-
-Midscene can drive WebDriver tools to support iOS automation.
-
-By adapting a visual model solution, the automation process works with any app tech stack—whether built with Native, Flutter, React Native, or Lynx. Developers only need to focus on the final experience when debugging UI automation scripts.
-
-The iOS UI automation solution comes with all the features of Midscene:
-
-- Supports zero-code trial using Playground.
-- Supports JavaScript SDK.
-- Supports automation scripts in YAML format and command-line tools.
-- Supports HTML reports to replay all operation paths.
-
-## Showcases
-
-<ShowcaseIOS />
-
-See more showcases: [showcases](./showcases.mdx)
-
-## Try with Playground
-
-With Playground, you can experience Midscene's capabilities without writing any code.
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
-
-See [Getting Started](./ios-getting-started#try-playground-no-code) to learn how to launch the Playground.
-
-
-## Understand WebDriverAgent
-
-WebDriver is a standard protocol established by W3C for browser automation, providing a unified API to control different browsers and applications. The WebDriver protocol defines the communication method between client and server, enabling automation tools to control various user interfaces across platforms.
-
-Through the efforts of the Appium team and other open source communities, the industry now has many excellent libraries that convert desktop and mobile device automation operations into WebDriver protocol. These tools include:
-- **Appium** - Cross-platform mobile automation framework
-- **WebDriverAgent** - Service dedicated to iOS device automation
-- **Selenium** - Web browser automation tool
-- **WinAppDriver** - Windows application automation tool
-
-**Midscene adapts to the WebDriver protocol**, which means developers can use AI models to perform intelligent automated operations on any device that supports WebDriver. Through this design, Midscene can not only control traditional operations like clicking and typing, but also:
-- Understand interface content and context
-- Execute complex multi-step operations
-- Perform intelligent assertions and validations
-- Extract and analyze interface data
-
-On iOS platform, Midscene connects to iOS devices through WebDriverAgent, allowing you to control iOS apps and system using natural language descriptions.
-
-
-## Next Steps
-
-* [Use JavaScript SDK](/en/ios-getting-started)
-* [Use YAML format automation scripts](/en/automate-with-scripts-in-yaml) and [command-line tools](/en/automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/en/ios.mdx b/apps/site/docs/en/ios.mdx
new file mode 100644
index 0000000000..960b1d48e2
--- /dev/null
+++ b/apps/site/docs/en/ios.mdx
@@ -0,0 +1,459 @@
+import ShowcaseIOS from './showcases-ios.mdx';
+import StartExperience from './common/start-experience.mdx';
+import SetupEnv from './common/setup-env.mdx';
+import PrepareIOS from './common/prepare-ios.mdx';
+
+import { PackageManagerTabs } from '@theme';
+
+# iOS Automation Support
+
+Midscene can drive WebDriver tools to support iOS automation.
+
+## Showcases
+
+<ShowcaseIOS />
+
+See more showcases: [showcases](./showcases.mdx)
+
+## Understand WebDriverAgent
+
+WebDriver is a standard protocol established by W3C for browser automation, providing a unified API to control different browsers and applications. The WebDriver protocol defines the communication method between client and server, enabling automation tools to control various user interfaces across platforms.
+
+Through the efforts of the Appium team and other open source communities, the industry now has many excellent libraries that convert desktop and mobile device automation operations into WebDriver protocol. These tools include:
+- **Appium** - Cross-platform mobile automation framework
+- **WebDriverAgent** - Service dedicated to iOS device automation
+- **Selenium** - Web browser automation tool
+- **WinAppDriver** - Windows application automation tool
+
+**Midscene adapts to the WebDriver protocol**, which means developers can use AI models to perform intelligent automated operations on any device that supports WebDriver. Through this design, Midscene can not only control traditional operations like clicking and typing, but also:
+- Understand interface content and context
+- Execute complex multi-step operations
+- Perform intelligent assertions and validations
+- Extract and analyze interface data
+
+On iOS platform, Midscene connects to iOS devices through WebDriverAgent, allowing you to control iOS apps and system using natural language descriptions.
+
+This guide walks you through everything required to automate an iOS device with Midscene: connect a real phone through WebDriverAgent, configure model credentials, try the no-code Playground, and run your first JavaScript script.
+
+:::info Demo Projects
+
+Control iOS devices with JavaScript: [https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
+
+Integrate Vitest for testing: [https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
+
+:::
+
+<SetupEnv />
+
+<PrepareIOS />
+
+## Try Playground (no code)
+
+Playground is the fastest way to validate the connection and observe AI-driven steps without writing code. It shares the same core as `@midscene/ios`, so anything that works here will behave the same once scripted.
+
+<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
+
+1. Launch the Playground CLI:
+
+```bash
+npx --yes @midscene/ios-playground
+```
+
+2. Click the gear button to enter the configuration page and paste your API key config. Refer back to [Model configuration](./model-config) if you still need credentials.
+
+![](/ios-set-env.png)
+
+## Start experiencing
+
+<StartExperience />
+
+## Integration with Midscene Agent
+
+Once Playground works, move to a repeatable script with the JavaScript SDK.
+
+### Step 1. Install dependencies
+
+<PackageManagerTabs command="install @midscene/ios dotenv --save-dev" />
+
+### Step 2. Write scripts
+
+Save the following code as `./demo.ts`. It opens Safari on the device, searches eBay, and asserts the result list.
+
+```typescript title="./demo.ts"
+import 'dotenv/config'; // load Midscene environment variables from .env if present
+import {
+  IOSAgent,
+  IOSDevice,
+  agentFromWebDriverAgent,
+} from '@midscene/ios';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+Promise.resolve(
+  (async () => {
+    // Method 1: Create device and agent directly
+    const page = new IOSDevice({
+      wdaPort: 8100,
+      wdaHost: 'localhost',
+    });
+
+    // 👀 Initialize Midscene agent
+    const agent = new IOSAgent(page, {
+      aiActionContext:
+        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
+    });
+    await page.connect();
+
+    // Method 2: Or use convenience function (recommended)
+    // const agent = await agentFromWebDriverAgent({
+    //   wdaPort: 8100,
+    //   wdaHost: 'localhost',
+    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
+    // });
+
+    // 👀 Directly open ebay.com webpage (recommended approach)
+    await page.launch('https://ebay.com');
+    await sleep(3000);
+
+    // 👀 Enter keywords and perform search
+    await agent.aiAct('Search for "Headphones"');
+
+    // 👀 Wait for loading to complete
+    await agent.aiWaitFor('At least one headphone product is displayed on the page');
+    // Or you can use a simple sleep:
+    // await sleep(5000);
+
+    // 👀 Understand page content and extract data
+    const items = await agent.aiQuery(
+      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
+    );
+    console.log('Headphone product information', items);
+
+    // 👀 Use AI assertion
+    await agent.aiAssert('Multiple headphone products are displayed on the interface');
+
+    await page.destroy();
+  })(),
+);
+```
+
+### Step 3. Run
+
+```bash
+npx tsx demo.ts
+```
+
+### Step 4: View the report
+
+Successful runs print `Midscene - report file updated: /path/to/report/some_id.html`. Open the generated HTML file in a browser to replay every interaction, query, and assertion.
+
+## API reference and more resources
+
+Looking for constructors, helper methods, and platform-only device APIs? See the [iOS API reference](#api-reference) below for detailed parameter lists plus advanced topics like custom actions. For API surfaces shared across platforms, head to the [common API reference](./api).
+
+## FAQ
+
+### Why can't I control my device through WebDriverAgent even though it's connected?
+
+Please check the following:
+
+1. **Developer Mode**: Ensure it's enabled in Settings > Privacy & Security > Developer Mode
+2. **UI Automation**: Ensure it's enabled in Settings > Developer > UI Automation
+3. **Device Trust**: Ensure the device trusts the current Mac
+
+### What are the differences between simulators and real devices?
+
+| Feature | Real Device | Simulator |
+|---------|-------------|-----------|
+| Port Forwarding | Requires iproxy | Not required |
+| Developer Mode | Must enable | Auto-enabled |
+| UI Automation Settings | Must enable manually | Auto-enabled |
+| Performance | Real device performance | Depends on Mac performance |
+| Sensors | Real hardware | Simulated data |
+
+### How to use custom WebDriverAgent port and host?
+
+You can specify WebDriverAgent port and host through the `IOSDevice` constructor or `agentFromWebDriverAgent`:
+
+```typescript
+// Method 1: Using IOSDevice
+const device = new IOSDevice({
+  wdaPort: 8100,        // Custom port
+  wdaHost: '192.168.1.100', // Custom host
+});
+
+// Method 2: Using convenience function (recommended)
+const agent = await agentFromWebDriverAgent({
+  wdaPort: 8100,        // Custom port
+  wdaHost: '192.168.1.100', // Custom host
+});
+```
+
+For remote devices, you also need to set up port forwarding accordingly:
+
+```bash
+iproxy 8100 8100 YOUR_DEVICE_ID
+```
+
+### How to get smoother live screen preview in Playground?
+
+Playground's screen preview supports two modes:
+
+- **Polling mode** (default): Captures screenshots one by one via the WDA screenshot API, achieving ~5-10fps.
+- **Native MJPEG stream** (recommended): Proxies WDA's built-in MJPEG Server directly for higher frame rate and lower latency.
+
+To enable the native MJPEG stream, forward the WDA MJPEG Server port (default 9100) to localhost:
+
+```bash
+# Required for real devices only (simulators don't need this)
+iproxy 9100 9100 YOUR_DEVICE_ID
+```
+
+Playground automatically probes port 9100 on startup. If available, the log will show `MJPEG: streaming via native WDA MJPEG server`; otherwise it falls back to polling mode automatically.
+
+## More
+
+- For every Agent method, check the [API reference (Common)](./api#interaction-methods).
+- For the iOS API reference, see [iOS Agent API](#api-reference).
+- Demo projects
+  - iOS JavaScript SDK demo: [https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
+  - iOS + Vitest demo: [https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
+
+## API reference {#api-reference}
+
+Use this doc when you need to customize iOS device behavior, wire Midscene into WebDriverAgent-driven workflows, or troubleshoot WDA requests. For shared constructor options (reporting, hooks, caching, etc.), see the platform-agnostic [API reference (Common)](./api).
+
+### Action Space
+
+`IOSDevice` uses the following action space; the Midscene Agent can use these actions while planning tasks:
+
+- `Tap` &mdash; Tap an element.
+- `DoubleClick` &mdash; Double-tap an element.
+- `Input` &mdash; Enter text with `replace`/`typeOnly`/`clear` modes (`append` is a deprecated alias for `typeOnly`). Supports optional `autoDismissKeyboard` parameter.
+- `Scroll` &mdash; Scroll from an element or screen center in any direction, including scroll-to-top/bottom/left/right helpers.
+- `DragAndDrop` &mdash; Drag from one element to another.
+- `KeyboardPress` &mdash; Press a specified key.
+- `LongPress` &mdash; Long-press a target element with optional duration.
+- `Pinch` &mdash; Two-finger pinch gesture. Use `scale > 1` to zoom in, `scale < 1` to zoom out.
+- `ClearInput` &mdash; Clear the contents of an input field.
+- `Launch` &mdash; Open a URL, bundle identifier, or URL scheme.
+- `Terminate` &mdash; Close a running iOS app by its bundle identifier.
+- `RunWdaRequest` &mdash; Call WebDriverAgent REST endpoints directly.
+- `IOSHomeButton` &mdash; Trigger the iOS system Home action.
+- `IOSAppSwitcher` &mdash; Open the iOS multitasking view.
+
+### IOSDevice {#iosdevice}
+
+Create a WebDriverAgent-backed instance that an IOSAgent can drive.
+
+#### Import
+
+```ts
+import { IOSDevice } from '@midscene/ios';
+```
+
+#### Constructor
+
+```ts
+const device = new IOSDevice({
+  // device options...
+});
+```
+
+#### Device options
+
+- `wdaPort?: number` &mdash; WebDriverAgent port. Default `8100`.
+- `wdaHost?: string` &mdash; WebDriverAgent host. Default `'localhost'`.
+- `iOSDeviceClassOverride?: string` &mdash; Optional npm module path that replaces the default `IOSDevice` when using `agentFromWebDriverAgent()` or iOS Playground. The module must export an `IOSDevice` class or a default class.
+- `autoDismissKeyboard?: boolean` &mdash; Hide the keyboard after text input. Default `true`.
+- `customActions?: DeviceAction<any>[]` &mdash; Additional device actions exposed to the agent.
+
+#### Usage notes
+
+- Ensure Developer Mode is enabled and WDA can reach the device; use `iproxy` when forwarding ports from a real device.
+- Use `wdaHost`/`wdaPort` to target remote devices or custom WDA deployments.
+- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
+
+#### Examples
+
+##### Quick start
+
+```ts
+import { IOSAgent, IOSDevice } from '@midscene/ios';
+
+const device = new IOSDevice({ wdaHost: 'localhost', wdaPort: 8100 });
+await device.connect();
+
+const agent = new IOSAgent(device, {
+  aiActionContext: 'If any permission dialog appears, accept it.',
+});
+
+await agent.launch('https://ebay.com');
+await agent.aiAct('Search for "Headphones"');
+const items = await agent.aiQuery(
+  '{itemTitle: string, price: Number}[], list headphone products',
+);
+console.log(items);
+```
+
+##### Custom host and port
+
+```ts
+const device = new IOSDevice({
+  wdaHost: '192.168.1.100',
+  wdaPort: 8300,
+});
+await device.connect();
+```
+
+### IOSAgent {#iosagent}
+
+Wire Midscene's AI planner to an IOSDevice for UI automation over WebDriverAgent.
+
+#### Import
+
+```ts
+import { IOSAgent } from '@midscene/ios';
+```
+
+#### Constructor
+
+```ts
+const agent = new IOSAgent(device, {
+  // common agent options...
+});
+```
+
+#### iOS-specific options
+
+- `customActions?: DeviceAction<any>[]` &mdash; Extend planning with actions defined via `defineAction`.
+- `appNameMapping?: Record<string, string>` &mdash; Map friendly app names to bundle identifiers. When you pass an app name to `launch(target)` or `terminate(bundleId)`, the agent will look up the bundle ID in this mapping. If no mapping is found, it will attempt to use `target` as-is. User-provided mappings take precedence over default mappings.
+- All other fields match [API constructors](./api#common-parameters): `generateReport`, `reportFileName`, `aiActionContext`, `modelConfig`, `cacheId`, `createOpenAIClient`, `onTaskStartTip`, and more.
+
+#### Usage notes
+
+:::info
+
+- Use one agent per device connection.
+- iOS-only helpers such as `launch`, `terminate`, and `runWdaRequest` are also exposed in YAML scripts. See [iOS platform-specific actions](./automate-with-scripts-in-yaml#the-ios-part).
+- For shared interaction methods, see [API reference (Common)](./api#interaction-methods).
+
+:::
+
+#### iOS-specific methods
+
+##### `agent.launch()`
+
+Launch a web URL, native application bundle, or custom scheme.
+
+```ts
+function launch(target: string): Promise<void>;
+```
+
+- `target: string` &mdash; Target address (web URL, Bundle Identifier, URL scheme, tel/mailto, etc.) or app name. If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped Bundle ID; otherwise, `target` will be launched as-is.
+
+```ts
+await agent.launch('https://www.apple.com');
+await agent.launch('com.apple.Preferences');
+await agent.launch('myapp://profile/user/123');
+await agent.launch('tel:+1234567890');
+```
+
+##### `agent.terminate()`
+
+Terminate (close) a running iOS app by its bundle ID.
+
+```ts
+function terminate(bundleId: string): Promise<void>;
+```
+
+- `bundleId: string` &mdash; The bundle identifier of the app to terminate (e.g. `com.apple.Preferences`). If you pass an app name and it exists in `appNameMapping`, it will be automatically resolved to the mapped Bundle ID.
+
+```ts
+await agent.terminate('com.apple.Preferences');
+await agent.terminate('com.apple.mobilesafari');
+```
+
+##### `agent.runWdaRequest()`
+
+Execute raw WebDriverAgent REST calls when you need low-level control.
+
+```ts
+function runWdaRequest(
+  method: string,
+  endpoint: string,
+  data?: Record<string, any>,
+): Promise<any>;
+```
+
+- `method: string` &mdash; HTTP verb (`GET`, `POST`, `DELETE`, etc.).
+- `endpoint: string` &mdash; WebDriverAgent endpoint path.
+- `data?: Record<string, any>` &mdash; Optional JSON body.
+
+```ts
+const screen = await agent.runWdaRequest('GET', '/wda/screen');
+await agent.runWdaRequest('POST', '/session/test/wda/pressButton', { name: 'home' });
+```
+
+##### Navigation helpers
+
+- `agent.home(): Promise<void>` &mdash; Return to the Home screen.
+- `agent.appSwitcher(): Promise<void>` &mdash; Reveal the multitasking view.
+
+#### Helper utilities
+
+##### `agentFromWebDriverAgent()` {#agentfromwebdriveragent}
+
+Connect to WebDriverAgent and return a ready-to-use IOSAgent.
+
+```ts
+function agentFromWebDriverAgent(
+  opts?: PageAgentOpt & IOSDeviceOpt,
+): Promise<IOSAgent>;
+```
+
+- `opts?: PageAgentOpt & IOSDeviceOpt` &mdash; Combine common agent options with [`IOSDevice`](#iosdevice) settings.
+- Set `MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE` to apply the same device class override through the environment. An explicit option takes precedence over the environment variable.
+
+```ts
+import { agentFromWebDriverAgent } from '@midscene/ios';
+
+const agent = await agentFromWebDriverAgent({
+  wdaHost: 'localhost',
+  wdaPort: 8100,
+  iOSDeviceClassOverride: '@your-scope/ios-device',
+  aiActionContext: 'Accept permission dialogs automatically.',
+});
+```
+
+#### Extending custom interaction actions
+
+Extend the Agent's action space by supplying `customActions` with handlers created via `defineAction`. These actions appear after the built-in ones and can be called during planning.
+
+```ts
+import { getMidsceneLocationSchema, z } from '@midscene/core';
+import { defineAction } from '@midscene/core/device';
+import { agentFromWebDriverAgent } from '@midscene/ios';
+
+const ContinuousClick = defineAction({
+  name: 'continuousClick',
+  description: 'Click the same target repeatedly',
+  paramSchema: z.object({
+    locate: getMidsceneLocationSchema(),
+    count: z.number().int().positive().describe('How many times to click'),
+  }),
+  async call({ locate, count }) {
+    console.log('click target center', locate.center);
+    console.log('click count', count);
+  },
+});
+
+const agent = await agentFromWebDriverAgent({
+  customActions: [ContinuousClick],
+});
+
+await agent.aiAct('Click the red button five times');
+```
+
+#### See also
+
+- [Integrate with any interface](./integrate-with-any-interface#define-a-custom-action) for custom actions and schemas.
diff --git a/apps/site/docs/en/quick-start.mdx b/apps/site/docs/en/quick-start.mdx
index 01a8900d90..b8a4d72145 100644
--- a/apps/site/docs/en/quick-start.mdx
+++ b/apps/site/docs/en/quick-start.mdx
@@ -102,5 +102,5 @@ Open that HTML file in your browser to replay every action, query, and assertion
 ## Next steps
 
 - **Use it in your tests**: [Integrate with Playwright](./integrate-with-playwright) to add Midscene to your existing suite.
-- **Other platforms**: get started on [Android](./android-getting-started), [iOS](./ios-getting-started), [HarmonyOS](./harmony-getting-started), or [desktop](./computer-getting-started).
+- **Other platforms**: get started on [Android](./android), [iOS](./ios), [HarmonyOS](./harmony), or [desktop](./computer).
 - **Go further**: improve results with [Model strategy](./model-strategy), or look up every method in the [API reference](./api).
diff --git a/apps/site/docs/zh/android-api-reference.mdx b/apps/site/docs/zh/android-api-reference.mdx
deleted file mode 100644
index b031aecb1f..0000000000
--- a/apps/site/docs/zh/android-api-reference.mdx
+++ /dev/null
@@ -1,237 +0,0 @@
-# API 参考（Android）
-
-当你需要自定义设备行为、把 Midscene 接入框架，或排查 adb 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 [API 参考](./api)。
-
-## Action Space（动作空间）
-
-`AndroidDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
-
-- `Tap` —— 点击元素。
-- `DoubleClick` —— 双击元素。
-- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式（`append` 是 `typeOnly` 的已废弃别名）。支持可选参数 `autoDismissKeyboard`。
-- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
-- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
-- `KeyboardPress` —— 按下指定键位。
-- `LongPress` —— 长按目标元素，可选自定义时长。
-- `PullGesture` —— 上拉或下拉（如下拉刷新），可选距离与持续时间。
-- `Pinch` —— 双指缩放手势。`scale > 1` 放大，`scale < 1` 缩小。
-- `ClearInput` —— 清空输入框内容。
-- `Launch` —— 打开网页或 `package/.Activity`。
-- `Terminate` —— 按包名强制停止应用。
-- `RunAdbShell` —— 执行原始 `adb shell` 命令。
-- `AndroidBackButton` —— 触发系统返回。
-- `AndroidHomeButton` —— 回到桌面。
-- `AndroidRecentAppsButton` —— 打开多任务/最近应用。
-
-## AndroidDevice {#androiddevice}
-
-创建一个可供 AndroidAgent 驱动的 adb 设备实例。
-
-### 导入
-
-```ts
-import { AndroidDevice, getConnectedDevices } from '@midscene/android';
-```
-
-### 构造函数
-
-```ts
-const device = new AndroidDevice(deviceId, {
-  // 设备参数...
-});
-```
-
-### 设备选项
-
-- `deviceId: string` —— 来自 `adb devices` 或 `getConnectedDevices()` 的值。
-- `autoDismissKeyboard?: boolean` —— 输入完成后自动隐藏键盘，默认 `true`。
-- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` —— 关闭键盘的顺序，默认 `'esc-first'`。
-- `androidAdbPath?: string` —— adb 可执行文件的自定义路径。
-- `remoteAdbHost?: string` / `remoteAdbPort?: number` —— 指向远程 adb server。
-- `imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii'` —— 控制何时调用 [yadb](https://github.com/ysbing/YADB) 进行文本输入，默认 `'yadb-for-non-ascii'`。
-  - `'yadb-for-non-ascii'`（默认）—— 对 Unicode 字符（包括 Latin Unicode 如 ö、é、ñ）、中文、日文以及格式化符号（如 %s、%d）使用 yadb。纯 ASCII 文本使用更快的原生 `adb input text`。
-  - `'always-yadb'` —— 对所有文本输入始终使用 yadb，提供最大兼容性，但对纯 ASCII 文本稍慢。
-- `displayId?: number` —— 在设备镜像多个屏幕时，选择特定虚拟屏幕。
-- `screenshotResizeScale?: number` —— **已废弃。** 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 `AgentOpt` 中的 `screenshotShrinkFactor`。
-- `minScreenshotBufferSize?: number` —— 截图 buffer 大小校验阈值，单位为字节；低于该值的 buffer 会被视为截图采集失败或已损坏。默认 `1024`（1KB）。设置为 `0` 仅跳过此大小校验；Midscene 仍会拒绝空 buffer 和无效图片格式。
-- `alwaysRefreshScreenInfo?: boolean` —— 每一步都重新查询旋转角度与屏幕尺寸，默认 `false`。
-- `scrcpyConfig?: object` —— Scrcpy 高性能截图配置，默认关闭。详见下方 [Scrcpy 截图模式](#scrcpy)。
-
-### Scrcpy 截图模式 {#scrcpy}
-
-默认情况下，Midscene 通过 `adb shell screencap` 截图，每次耗时约 500–2000ms。开启 Scrcpy 模式后，通过 H.264 视频流实时获取画面，每次截图耗时约 **100–200ms**。
-
-**开启方式：**
-
-```ts
-const device = new AndroidDevice(deviceId, {
-  scrcpyConfig: {
-    enabled: true,
-  },
-});
-```
-
-**可选参数：**
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `enabled` | `boolean` | `false` | 是否启用 Scrcpy 截图 |
-| `maxSize` | `number` | `0` | 视频流最大分辨率（宽或高），`0` 表示不缩放 |
-| `videoBitRate` | `number` | `2000000` | H.264 编码码率（bps） |
-| `idleTimeoutMs` | `number` | `30000` | 空闲超时后自动断开连接（ms），设为 `0` 禁用 |
-
-:::tip
-Scrcpy 模式在连接失败时会自动降级到 ADB 截图，无需额外处理。
-:::
-
-### 使用说明
-
-- 可以使用 `getConnectedDevices()` 发现设备，`udid` 与 `adb devices` 输出一致。
-- 可以使用 `remoteAdbHost/remoteAdbPort` 连接远程 adb；如果 adb 不在 PATH 中，可设置 `androidAdbPath`。
-
-### 示例
-
-#### 快速开始
-
-```ts
-import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';
-
-const [first] = await getConnectedDevices();
-const device = new AndroidDevice(first.udid);
-await device.connect();
-
-const agent = new AndroidAgent(device, {
-  aiActionContext: 'If a permissions dialog appears, accept it.',
-});
-
-await agent.launch('https://www.ebay.com');
-await agent.aiAct('search "Headphones" and wait for results');
-const items = await agent.aiQuery(
-  '{itemTitle: string, price: number}[], find item in list and corresponding price',
-);
-console.log(items);
-```
-
-#### 启动原生 App
-
-```ts
-await agent.launch('com.android.settings/.Settings');
-await agent.back();
-await agent.home();
-```
-
-## AndroidAgent {#androidagent}
-
-将 Midscene 的 AI 规划能力绑定到 AndroidDevice，实现 UI 自动化。
-
-### 导入
-
-```ts
-import { AndroidAgent } from '@midscene/android';
-```
-
-### 构造函数
-
-```ts
-const agent = new AndroidAgent(device, {
-  // 通用 Agent 参数...
-});
-```
-
-### Android 特有选项
-
-- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
-- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到包名。当你在 `launch(target)` 里传入应用名称时，Agent 会在此映射中查找对应的包名；若未找到映射，则按原样尝试启动 `target`。
-- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
-
-### 使用说明
-
-:::info
-
-- 一个设备连接对应一个 Agent。
-- `launch`、`terminate`、`runAdbShell` 等 Android 专属辅助函数也可在 YAML 脚本中使用，语法见 [Android 平台特定动作](./automate-with-scripts-in-yaml#the-android-part)。
-- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
-
-:::
-
-### Android 特有方法
-
-#### `agent.launch()`
-
-启动网页或原生 Android activity/package。
-
-```ts
-function launch(target: string): Promise<void>;
-```
-
-- `target: string` —— 可以是网页 URL，也可以是 `package/.Activity` 形式的字符串，例如 `com.android.settings/.Settings`，也可以是应用包名、URL 或应用名称。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应包名；若未找到映射，则直接按 `target` 启动。
-
-#### `agent.runAdbShell()`
-
-通过连接的设备运行原始的 `adb shell` 命令。传入的内容只需要包含 shell 命令本身，不要包含 `adb shell` 前缀。
-
-```ts
-function runAdbShell(command: string, opt?: { timeout?: number }): Promise<string>;
-```
-
-- `command: string` —— 原样传递给 `adb shell` 的命令。例如要传 `input tap 100 200`，不要传 `adb shell input tap 100 200`。
-- `opt.timeout?: number` —— 可选的命令执行超时时间，单位为毫秒。
-
-```ts
-const result = await agent.runAdbShell('dumpsys battery', { timeout: 60 * 1000 });
-console.log(result);
-
-await agent.runAdbShell('input tap 100 200');
-```
-
-#### `agent.terminate()`
-
-终止（强制停止）正在运行的 Android 应用。
-
-```ts
-function terminate(uri: string): Promise<void>;
-```
-
-- `uri: string` —— 应用包名、`appNameMapping` 中的应用名称，或 `package/.Activity`（仅使用包名部分）。
-
-```ts
-await agent.terminate('com.android.settings');
-```
-
-#### 导航辅助
-
-- `agent.back(): Promise<void>` —— 触发 Android 系统的返回操作。
-- `agent.home(): Promise<void>` —— 返回桌面。
-- `agent.recentApps(): Promise<void>` —— 打开多任务/最近应用界面。
-
-### 辅助工具
-
-#### `agentFromAdbDevice()`
-
-从任意已连接的 adb 设备创建 `AndroidAgent`。
-
-```ts
-function agentFromAdbDevice(
-  deviceId?: string,
-  opts?: PageAgentOpt & AndroidDeviceOpt,
-): Promise<AndroidAgent>;
-```
-
-- `deviceId?: string` —— 连接特定设备；留空表示使用“第一个可用设备”。
-- `opts?: PageAgentOpt & AndroidDeviceOpt` —— 在一个对象中合并 Agent 选项与 [`AndroidDevice`](#androiddevice) 的设置。
-
-#### `getConnectedDevices()`
-
-列举 Midscene 可驱动的 adb 设备。
-
-```ts
-function getConnectedDevices(): Promise<Array<{
-  udid: string;
-  state: string;
-  port?: number;
-}>>;
-```
-
-### 相关阅读
-
-- [Android 快速开始](./android-getting-started) 获取搭建与脚本示例。
diff --git a/apps/site/docs/zh/android-introduction.mdx b/apps/site/docs/zh/android-introduction.mdx
deleted file mode 100644
index 68a6a4d9d6..0000000000
--- a/apps/site/docs/zh/android-introduction.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
-import ShowcaseAndroid from './showcases-android.mdx';
-
-# Android 自动化支持
-
-Midscene 可以驱动 adb 工具来实现 Android 自动化。
-
-由于适配了视觉模型方案，整个自动化过程可以适配任意的 App 技术栈，无论是 Native、Flutter 还是 React Native 构建的 App 或小程序都能使用。开发者只需面向最终效果调试 UI 自动化脚本即可。
-
-Android UI 自动化解决方案具备 Midscene 的全部特性：
-
-- 支持使用 Playground 进行零代码试用。
-- 支持 JavaScript SDK。
-- 支持使用 YAML 格式的自动化脚本和命令行工具。
-- 支持生成 HTML 报告来回放所有操作路径。
-
-## 案例展示
-
-<ShowcaseAndroid />
-
-查看更多案例：[showcases](./showcases.mdx)
-
-## 在 Android 上试用 Midscene Playground
-
-借助 Midscene.js Playground，你无需编写任何代码就能体验 Android 自动化能力。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/booking2.mp4" controls/>
-
-查看 [开始使用](./android-getting-started#试用-playground零代码) 了解如何启动 Playground。
-
-## 下一步
-
-* [快速开始](./android-getting-started)
-* [使用 JavaScript SDK](./android-getting-started)
-* [使用 YAML 格式的自动化脚本](./automate-with-scripts-in-yaml) 与 [命令行工具](./automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/zh/android-getting-started.mdx b/apps/site/docs/zh/android.mdx
similarity index 50%
rename from apps/site/docs/zh/android-getting-started.mdx
rename to apps/site/docs/zh/android.mdx
index 88ba3bdac9..2dcec62213 100644
--- a/apps/site/docs/zh/android-getting-started.mdx
+++ b/apps/site/docs/zh/android.mdx
@@ -1,9 +1,18 @@
 import StartExperience from './common/start-experience.mdx';
+import ShowcaseAndroid from './showcases-android.mdx';
 import SetupEnv from './common/setup-env.mdx';
 
 import { PackageManagerTabs } from '@theme';
 
-# Android 开始使用
+# Android 自动化支持
+
+Midscene 可以驱动 adb 工具来实现 Android 自动化。
+
+## 案例展示
+
+<ShowcaseAndroid />
+
+查看更多案例：[showcases](./showcases.mdx)
 
 本指南将带你完成使用 Midscene 自动化 Android 设备所需的一切：通过 adb 连接真机、配置模型 API Key、体验零代码 Playground，并运行你的首个 JavaScript 脚本。
 
@@ -151,7 +160,7 @@ npx tsx demo.ts
 
 ## 进阶
 
-当你需要自定义设备行为、把 Midscene 接入独立框架，或排查 adb 问题时，可参考本节内容。更多构造函数参数可前往 [API 参考（Android）](./android-api-reference)。
+当你需要自定义设备行为、把 Midscene 接入独立框架，或排查 adb 问题时，可参考本节内容。更多构造函数参数可前往 [API 参考（Android）](#api-reference)。
 
 ### 扩展 Android 上的 Midscene
 
@@ -295,7 +304,241 @@ const device = new AndroidDevice('s4ey59', {
 ## 更多
 
 - 查看所有 Agent 方法：[API 参考（通用）](./api#interaction-methods)
-- Android 专属参数与接口：[Android Agent API](./android-api-reference)
+- Android 专属参数与接口：[Android Agent API](#api-reference)
 - 示例项目
   - Android JavaScript SDK 示例：[https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/android/javascript-sdk-demo)
   - Android + Vitest 示例：[https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/android/vitest-demo)
+
+## API 参考 {#api-reference}
+
+当你需要自定义设备行为、把 Midscene 接入框架，或排查 adb 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 [API 参考](./api)。
+
+### Action Space（动作空间）
+
+`AndroidDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
+
+- `Tap` —— 点击元素。
+- `DoubleClick` —— 双击元素。
+- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式（`append` 是 `typeOnly` 的已废弃别名）。支持可选参数 `autoDismissKeyboard`。
+- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
+- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
+- `KeyboardPress` —— 按下指定键位。
+- `LongPress` —— 长按目标元素，可选自定义时长。
+- `PullGesture` —— 上拉或下拉（如下拉刷新），可选距离与持续时间。
+- `Pinch` —— 双指缩放手势。`scale > 1` 放大，`scale < 1` 缩小。
+- `ClearInput` —— 清空输入框内容。
+- `Launch` —— 打开网页或 `package/.Activity`。
+- `Terminate` —— 按包名强制停止应用。
+- `RunAdbShell` —— 执行原始 `adb shell` 命令。
+- `AndroidBackButton` —— 触发系统返回。
+- `AndroidHomeButton` —— 回到桌面。
+- `AndroidRecentAppsButton` —— 打开多任务/最近应用。
+
+### AndroidDevice {#androiddevice}
+
+创建一个可供 AndroidAgent 驱动的 adb 设备实例。
+
+#### 导入
+
+```ts
+import { AndroidDevice, getConnectedDevices } from '@midscene/android';
+```
+
+#### 构造函数
+
+```ts
+const device = new AndroidDevice(deviceId, {
+  // 设备参数...
+});
+```
+
+#### 设备选项
+
+- `deviceId: string` —— 来自 `adb devices` 或 `getConnectedDevices()` 的值。
+- `autoDismissKeyboard?: boolean` —— 输入完成后自动隐藏键盘，默认 `true`。
+- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` —— 关闭键盘的顺序，默认 `'esc-first'`。
+- `androidAdbPath?: string` —— adb 可执行文件的自定义路径。
+- `remoteAdbHost?: string` / `remoteAdbPort?: number` —— 指向远程 adb server。
+- `imeStrategy?: 'always-yadb' | 'yadb-for-non-ascii'` —— 控制何时调用 [yadb](https://github.com/ysbing/YADB) 进行文本输入，默认 `'yadb-for-non-ascii'`。
+  - `'yadb-for-non-ascii'`（默认）—— 对 Unicode 字符（包括 Latin Unicode 如 ö、é、ñ）、中文、日文以及格式化符号（如 %s、%d）使用 yadb。纯 ASCII 文本使用更快的原生 `adb input text`。
+  - `'always-yadb'` —— 对所有文本输入始终使用 yadb，提供最大兼容性，但对纯 ASCII 文本稍慢。
+- `displayId?: number` —— 在设备镜像多个屏幕时，选择特定虚拟屏幕。
+- `screenshotResizeScale?: number` —— **已废弃。** 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 `AgentOpt` 中的 `screenshotShrinkFactor`。
+- `minScreenshotBufferSize?: number` —— 截图 buffer 大小校验阈值，单位为字节；低于该值的 buffer 会被视为截图采集失败或已损坏。默认 `1024`（1KB）。设置为 `0` 仅跳过此大小校验；Midscene 仍会拒绝空 buffer 和无效图片格式。
+- `alwaysRefreshScreenInfo?: boolean` —— 每一步都重新查询旋转角度与屏幕尺寸，默认 `false`。
+- `scrcpyConfig?: object` —— Scrcpy 高性能截图配置，默认关闭。详见下方 [Scrcpy 截图模式](#scrcpy)。
+
+#### Scrcpy 截图模式 {#scrcpy}
+
+默认情况下，Midscene 通过 `adb shell screencap` 截图，每次耗时约 500–2000ms。开启 Scrcpy 模式后，通过 H.264 视频流实时获取画面，每次截图耗时约 **100–200ms**。
+
+**开启方式：**
+
+```ts
+const device = new AndroidDevice(deviceId, {
+  scrcpyConfig: {
+    enabled: true,
+  },
+});
+```
+
+**可选参数：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `false` | 是否启用 Scrcpy 截图 |
+| `maxSize` | `number` | `0` | 视频流最大分辨率（宽或高），`0` 表示不缩放 |
+| `videoBitRate` | `number` | `2000000` | H.264 编码码率（bps） |
+| `idleTimeoutMs` | `number` | `30000` | 空闲超时后自动断开连接（ms），设为 `0` 禁用 |
+
+:::tip
+Scrcpy 模式在连接失败时会自动降级到 ADB 截图，无需额外处理。
+:::
+
+#### 使用说明
+
+- 可以使用 `getConnectedDevices()` 发现设备，`udid` 与 `adb devices` 输出一致。
+- 可以使用 `remoteAdbHost/remoteAdbPort` 连接远程 adb；如果 adb 不在 PATH 中，可设置 `androidAdbPath`。
+
+#### 示例
+
+##### 快速开始
+
+```ts
+import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';
+
+const [first] = await getConnectedDevices();
+const device = new AndroidDevice(first.udid);
+await device.connect();
+
+const agent = new AndroidAgent(device, {
+  aiActionContext: 'If a permissions dialog appears, accept it.',
+});
+
+await agent.launch('https://www.ebay.com');
+await agent.aiAct('search "Headphones" and wait for results');
+const items = await agent.aiQuery(
+  '{itemTitle: string, price: number}[], find item in list and corresponding price',
+);
+console.log(items);
+```
+
+##### 启动原生 App
+
+```ts
+await agent.launch('com.android.settings/.Settings');
+await agent.back();
+await agent.home();
+```
+
+### AndroidAgent {#androidagent}
+
+将 Midscene 的 AI 规划能力绑定到 AndroidDevice，实现 UI 自动化。
+
+#### 导入
+
+```ts
+import { AndroidAgent } from '@midscene/android';
+```
+
+#### 构造函数
+
+```ts
+const agent = new AndroidAgent(device, {
+  // 通用 Agent 参数...
+});
+```
+
+#### Android 特有选项
+
+- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
+- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到包名。当你在 `launch(target)` 里传入应用名称时，Agent 会在此映射中查找对应的包名；若未找到映射，则按原样尝试启动 `target`。
+- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
+
+#### 使用说明
+
+:::info
+
+- 一个设备连接对应一个 Agent。
+- `launch`、`terminate`、`runAdbShell` 等 Android 专属辅助函数也可在 YAML 脚本中使用，语法见 [Android 平台特定动作](./automate-with-scripts-in-yaml#the-android-part)。
+- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
+
+:::
+
+#### Android 特有方法
+
+##### `agent.launch()`
+
+启动网页或原生 Android activity/package。
+
+```ts
+function launch(target: string): Promise<void>;
+```
+
+- `target: string` —— 可以是网页 URL，也可以是 `package/.Activity` 形式的字符串，例如 `com.android.settings/.Settings`，也可以是应用包名、URL 或应用名称。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应包名；若未找到映射，则直接按 `target` 启动。
+
+##### `agent.runAdbShell()`
+
+通过连接的设备运行原始的 `adb shell` 命令。传入的内容只需要包含 shell 命令本身，不要包含 `adb shell` 前缀。
+
+```ts
+function runAdbShell(command: string, opt?: { timeout?: number }): Promise<string>;
+```
+
+- `command: string` —— 原样传递给 `adb shell` 的命令。例如要传 `input tap 100 200`，不要传 `adb shell input tap 100 200`。
+- `opt.timeout?: number` —— 可选的命令执行超时时间，单位为毫秒。
+
+```ts
+const result = await agent.runAdbShell('dumpsys battery', { timeout: 60 * 1000 });
+console.log(result);
+
+await agent.runAdbShell('input tap 100 200');
+```
+
+##### `agent.terminate()`
+
+终止（强制停止）正在运行的 Android 应用。
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` —— 应用包名、`appNameMapping` 中的应用名称，或 `package/.Activity`（仅使用包名部分）。
+
+```ts
+await agent.terminate('com.android.settings');
+```
+
+##### 导航辅助
+
+- `agent.back(): Promise<void>` —— 触发 Android 系统的返回操作。
+- `agent.home(): Promise<void>` —— 返回桌面。
+- `agent.recentApps(): Promise<void>` —— 打开多任务/最近应用界面。
+
+#### 辅助工具
+
+##### `agentFromAdbDevice()`
+
+从任意已连接的 adb 设备创建 `AndroidAgent`。
+
+```ts
+function agentFromAdbDevice(
+  deviceId?: string,
+  opts?: PageAgentOpt & AndroidDeviceOpt,
+): Promise<AndroidAgent>;
+```
+
+- `deviceId?: string` —— 连接特定设备；留空表示使用“第一个可用设备”。
+- `opts?: PageAgentOpt & AndroidDeviceOpt` —— 在一个对象中合并 Agent 选项与 [`AndroidDevice`](#androiddevice) 的设置。
+
+##### `getConnectedDevices()`
+
+列举 Midscene 可驱动的 adb 设备。
+
+```ts
+function getConnectedDevices(): Promise<Array<{
+  udid: string;
+  state: string;
+  port?: number;
+}>>;
+```
diff --git a/apps/site/docs/zh/api.mdx b/apps/site/docs/zh/api.mdx
index 5ec7b35dd6..923c68eccd 100644
--- a/apps/site/docs/zh/api.mdx
+++ b/apps/site/docs/zh/api.mdx
@@ -9,8 +9,8 @@ Midscene 针对每个不同环境都有对应的 Agent。每个 Agent 的构造
 - 在 Puppeteer 中，使用 [PuppeteerAgent](./web-api-reference#puppeteer-agent)
 - 在 Playwright 中，使用 [PlaywrightAgent](./web-api-reference#playwright-agent)
 - 在桥接模式（Bridge Mode）中，使用 [AgentOverChromeBridge](./web-api-reference#chrome-bridge-agent)
-- 在 Android 中，使用 [Android API 参考](./android-api-reference)
-- 在 iOS 中，使用 [iOS API 参考](./ios-api-reference)
+- 在 Android 中，使用 [Android API 参考](./android#api-reference)
+- 在 iOS 中，使用 [iOS API 参考](./ios#api-reference)
 - 如果你要把 GUI Agent 集成到自己的界面，请参考 [自定义界面 Agent](./integrate-with-any-interface)
 
 ### 参数
diff --git a/apps/site/docs/zh/automate-with-scripts-in-yaml.mdx b/apps/site/docs/zh/automate-with-scripts-in-yaml.mdx
index 922a7e1d7c..73ceeab329 100644
--- a/apps/site/docs/zh/automate-with-scripts-in-yaml.mdx
+++ b/apps/site/docs/zh/automate-with-scripts-in-yaml.mdx
@@ -242,7 +242,7 @@ android:
 
 :::tip 查看完整的 Android 配置项
 
-YAML 脚本现在支持 `AndroidDevice` 构造函数的所有配置选项。完整的配置项列表请参考 [Android API 参考中的 AndroidDevice](./android-api-reference#androiddevice)。
+YAML 脚本现在支持 `AndroidDevice` 构造函数的所有配置选项。完整的配置项列表请参考 [Android API 参考中的 AndroidDevice](./android#androiddevice)。
 
 :::
 
@@ -345,7 +345,7 @@ ios:
 
 :::tip 查看完整的 iOS 配置项
 
-YAML 脚本现在支持 `IOSDevice` 构造函数的所有配置选项。完整的配置项列表请参考 [iOS API 参考中的 IOSDevice](./ios-api-reference#iosdevice)。
+YAML 脚本现在支持 `IOSDevice` 构造函数的所有配置选项。完整的配置项列表请参考 [iOS API 参考中的 IOSDevice](./ios#iosdevice)。
 
 :::
 
diff --git a/apps/site/docs/zh/changelog.mdx b/apps/site/docs/zh/changelog.mdx
index 3abd5255e2..9c83cad13f 100644
--- a/apps/site/docs/zh/changelog.mdx
+++ b/apps/site/docs/zh/changelog.mdx
@@ -53,7 +53,7 @@ Midscene 新增 AndroidWorld benchmark 报告。使用 v1.9.5 测试时，Midsce
 
 - `1.9.8` 是最后一个包含 MCP 支持的 Midscene 版本。后续版本会下线 MCP server 包，改为推荐 Skills 与各平台 CLI。
 - 各平台 CLI 支持传入 agent behavior init args。
-- CLI 的 YAML 脚本新增 HarmonyOS target，HarmonyOS 自动化可以通过与 Web、Android、iOS、Computer 一致的脚本运行器流程执行。详见：[YAML 脚本自动化](./automate-with-scripts-in-yaml)、[HarmonyOS API](./harmony-api-reference)
+- CLI 的 YAML 脚本新增 HarmonyOS target，HarmonyOS 自动化可以通过与 Web、Android、iOS、Computer 一致的脚本运行器流程执行。详见：[YAML 脚本自动化](./automate-with-scripts-in-yaml)、[HarmonyOS API](./harmony#api-reference)
 - YAML Web config 支持自定义 HTTP headers。
 - YAML Web config 支持通过 `downloadPath` 指定浏览器下载目录。
 - YAML 执行会暴露真实错误，不再只落到静默的 "not executed" 结果。
@@ -117,7 +117,7 @@ Midscene Studio 是一个基于 Electron 的桌面应用，把多平台 Playgrou
 
 ### YAML 工作流增强
 
-- **Android runAdbShell timeout**：在 JavaScript API 和 YAML 脚本中都支持 `timeout` 选项。详见：[Android API](./android-api-reference)、[YAML 脚本自动化](./automate-with-scripts-in-yaml)
+- **Android runAdbShell timeout**：在 JavaScript API 和 YAML 脚本中都支持 `timeout` 选项。详见：[Android API](./android#api-reference)、[YAML 脚本自动化](./automate-with-scripts-in-yaml)
 
 ### 新增交互 API
 
@@ -220,7 +220,7 @@ Chrome 扩展的录制设置中新增了 YAML 输出语言选项，支持 Englis
 
 ### Android / 鸿蒙端改进
 
-- Android 和鸿蒙端新增 `terminate` 操作，支持强制停止指定应用，方便在测试中重置应用状态。详见：[Android API](./android-api-reference)、[鸿蒙 API](./harmony-api-reference)
+- Android 和鸿蒙端新增 `terminate` 操作，支持强制停止指定应用，方便在测试中重置应用状态。详见：[Android API](./android#api-reference)、[鸿蒙 API](./harmony#api-reference)
 - 修复 Android 端在 X/Twitter 上输入时 placeholder 文本被意外保留的问题
 - 修复 Android Playground 局域网访问问题
 
@@ -272,7 +272,7 @@ v1.6 版本新增了 CDP 浏览器连接模式、跨平台双指缩放手势、G
 
 - **Skill CLI 自定义接口**：Skill CLI 支持自定义接口，开发者可以更灵活地扩展 Skill 能力。详见：[Skills 文档](./skills)
 - **统一 MCP 工具导出**：所有平台包（Web、Android、iOS 等）统一导出 MidsceneTools，在 MCP 场景下集成更简单。详见：[MCP 服务](./mcp)
-- **iOS 终止指定应用**：iOS 端支持通过 bundleId 终止指定应用，方便测试流程中重置应用状态。详见：[iOS API](./ios-api-reference)
+- **iOS 终止指定应用**：iOS 端支持通过 bundleId 终止指定应用，方便测试流程中重置应用状态。详见：[iOS API](./ios#api-reference)
 - **CLI 版本查看**：CLI 新增版本查看功能，健康检查中显示各包版本信息，便于排查环境问题
 
 ### 任务取消支持
@@ -387,7 +387,7 @@ Midscene Skills 是一套可安装到 Claude Code、OpenClaw 等 AI 助手中的
 
 新增 `@midscene/computer-mcp` 包，将 PC 桌面自动化能力以独立 MCP 服务的形式提供。开发者可以直接在 Cursor、Trae 等支持 MCP 的工具中使用桌面自动化能力，无需额外集成。
 
-详见文档：[PC 桌面自动化](./computer-introduction)
+详见文档：[PC 桌面自动化](./computer)
 
 ### Chrome 扩展支持 MCP 后台连接
 
@@ -440,13 +440,13 @@ Midscene 现在支持 PC 桌面自动化，在 Windows、macOS 和 Linux 上驱
 - 支持 YAML 格式的自动化脚本和命令行工具
 - 支持 HTML 报告回放所有操作路径
 
-详见文档：[PC 桌面自动化](./computer-introduction)
+详见文档：[PC 桌面自动化](./computer)
 
 ### Android 截图性能大幅提升
 
 开启 Scrcpy 截图模式后，截图耗时从原来的 500–2000ms 降低到 **100–200ms**，显著提升 Android 自动化的响应速度，特别适用于远程设备调试和高帧率场景。
 
-详见文档：[Scrcpy 截图模式](./android-api-reference#scrcpy)
+详见文档：[Scrcpy 截图模式](./android#scrcpy)
 
 ### 深度思考模式增强
 
@@ -725,7 +725,7 @@ v0.30 版本改进了缓存系统，让你可以根据实际需求控制缓存
 ## v0.29 - 新增 iOS 平台支持
 
 ### 新增 iOS 平台支持
-v0.29 版本最大的亮点是正式引入了对 iOS 平台的支持！现在，你可以通过 WebDriver 连接并自动化 iOS 设备，将 Midscene 的强大 AI 自动化能力扩展到苹果生态系统，了解详情: [支持 iOS 自动化](./ios-introduction)
+v0.29 版本最大的亮点是正式引入了对 iOS 平台的支持！现在，你可以通过 WebDriver 连接并自动化 iOS 设备，将 Midscene 的强大 AI 自动化能力扩展到苹果生态系统，了解详情: [支持 iOS 自动化](./ios)
 
 ### 适配 Qwen3-VL 模型
 
@@ -810,7 +810,7 @@ v0.28 版本推出了与任意界面集成的功能。定义符合 `AbstractInte
 - 为 Playwright fixture 补全所有 agent api，简化测试脚本编写，解决使用 agentForPage 无法生成报告的问题
 
 ### Android 自动化增强
-- 新增隐藏键盘策略（[keyboardDismissStrategy](./android-api-reference#androiddevice)），允许指定自动隐藏键盘的方式
+- 新增隐藏键盘策略（[keyboardDismissStrategy](./android#androiddevice)），允许指定自动隐藏键盘的方式
 
 ### 报告功能优化
 - 报告内容引入懒解析，解决大体积报告的崩溃问题
@@ -1081,7 +1081,7 @@ const agent = await agentFromAdbDevice('s4ey59', {
 立即升级版本，体验这些强大新功能！
 
 * [自定义报告节点 API 文档](/zh/api.mdx#agentlogscreenshot)
-* [Android 更多配置项 API 文档](/zh/android-api-reference#androiddevice)
+* [Android 更多配置项 API 文档](/zh/android#androiddevice)
 
 
 ## v0.17 - 让 AI 看见页面 DOM
@@ -1207,7 +1207,7 @@ APIs: `aiBoolean`, `aiNumber`, `aiString`, `aiLocate`
 * 增强超时配置和日志记录，支持网络空闲和导航超时
 * 适配 gemini-2.5-pro
 
-了解详情: [支持 Android 自动化](./android-introduction)
+了解详情: [支持 Android 自动化](./android)
 
 ## v0.14 - 即时操作 API
 
diff --git a/apps/site/docs/zh/computer-api-reference.mdx b/apps/site/docs/zh/computer-api-reference.mdx
deleted file mode 100644
index e1969dd622..0000000000
--- a/apps/site/docs/zh/computer-api-reference.mdx
+++ /dev/null
@@ -1,437 +0,0 @@
-# API 参考（PC 桌面）
-
-本页记录了 `@midscene/computer` 提供的 PC 桌面特定 API。
-
-有关适用于所有平台的通用 API，请参阅 [通用 API 参考](./api)。
-
-## Agent 创建
-
-`agentForComputer(opts?): Promise<ComputerAgent>`
-
-创建用于本机桌面自动化的 agent。
-
-> 向后兼容：`agentFromComputer` 仍可作为别名使用。
-
-`agentForRDPComputer(opts): Promise<ComputerAgent<RDPDevice>>`
-
-创建用于通过 RDP 控制远程 Windows 桌面的 agent。
-
-**参数：**
-
-```typescript
-interface BaseComputerAgentOpt {
-  // Agent 选项（继承自 AgentOpt）
-  aiActionContext?: string;
-  cache?: boolean;
-  // ... 其他 AgentOpt 属性
-
-  customActions?: DeviceAction<any>[];
-}
-
-interface LocalComputerAgentOpt extends BaseComputerAgentOpt {
-
-  // 本机桌面选项
-  displayId?: string;
-  headless?: boolean;
-  xvfbResolution?: string;
-}
-
-interface RDPComputerAgentOpt extends BaseComputerAgentOpt {
-  host: string;
-  port?: number;
-  username?: string;
-  password?: string;
-  domain?: string;
-  adminSession?: boolean;
-  ignoreCertificate?: boolean;
-  securityProtocol?: 'auto' | 'tls' | 'nla' | 'rdp';
-  desktopWidth?: number;
-  desktopHeight?: number;
-}
-```
-
-### 本机桌面选项
-
-- `displayId`（可选）：指定要控制的显示器。使用 `ComputerDevice.listDisplays()` 获取可用显示器。
-- `customActions`（可选）：向设备添加自定义操作。
-- `headless`（可选，仅 Linux）：设为 `true` 时通过 [Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) 启动虚拟显示器，使桌面自动化能在无物理显示器的 Linux 服务器和 CI 环境中运行。也可通过环境变量 `MIDSCENE_COMPUTER_HEADLESS_LINUX=true` 设置。
-- `xvfbResolution`（可选）：Xvfb 虚拟显示器的分辨率，默认为 `'1920x1080x24'`。
-
-### RDP 选项
-
-- `host`：远程 Windows 主机名或 IP。
-- `port`：RDP 端口，默认是 `3389`。
-- `username` / `password`：远程会话凭据。
-- `domain`：可选的 Windows 域。
-- `adminSession`：当服务端允许时，请求远程管理员会话。
-- `ignoreCertificate`：用于跳过自签名证书校验。
-- `securityProtocol`：可选 `'auto'`、`'tls'`、`'nla'` 或 `'rdp'`。
-- `desktopWidth` / `desktopHeight`：请求指定远程桌面分辨率。
-
-:::tip 示例：在无头 Linux CI 中测试 Electron 应用
-使用 `@midscene/computer` 在无头 Linux CI 中测试 [Obsidian](https://obsidian.md/)（Electron 应用）的完整示例：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
-:::
-
-**示例：**
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-// 连接到主显示器
-const agent = await agentForComputer({
-  aiActionContext: '你正在自动化一个桌面应用。',
-});
-
-// 连接到特定显示器
-const displays = await ComputerDevice.listDisplays();
-const agent2 = await agentForComputer({
-  displayId: displays[1].id,
-});
-```
-
-**示例：通过 RDP 连接远程 Windows 桌面**
-
-```typescript
-import { agentForRDPComputer } from '@midscene/computer';
-
-const agent = await agentForRDPComputer({
-  aiActionContext:
-    'You are controlling a remote Windows desktop over the RDP protocol.',
-  host: '10.75.166.249',
-  port: 3389,
-  username: 'Admin',
-  password: 'replace-with-your-password',
-  // 可选：把 TCP 连接绑定到这个本地源 IP。
-  localAddress: '10.75.166.10',
-  ignoreCertificate: true,
-});
-
-await agent.aiWaitFor('The remote Windows desktop is visible');
-await agent.aiAct('Click the Windows Start button');
-await agent.aiAct('Open Settings');
-```
-
-:::tip 示例：通过 RDP 控制远程 Windows 桌面
-一个可直接运行的 Demo：连接远程 Windows，打开「设置」并进入「Windows 更新」，最后输出一份结构化报告：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
-:::
-
-当运行 Midscene 的机器存在多条出站路由，且 RDP 服务器要求从指定本地源
-IP 访问时，可以使用 `localAddress`。这里传入的是 IP 地址，不是网卡名。
-
-## 设备管理
-
-`ComputerDevice.listDisplays(): Promise<DisplayInfo[]>`
-
-列出所有可用显示器。
-
-**返回：**
-
-```typescript
-interface DisplayInfo {
-  id: string;
-  name: string;
-  primary?: boolean;
-}
-```
-
-**示例：**
-
-```typescript
-import { ComputerDevice } from '@midscene/computer';
-
-const displays = await ComputerDevice.listDisplays();
-console.log('可用显示器:', displays);
-// [
-//   { id: '0', name: '内置显示器', primary: true },
-//   { id: '1', name: '外接显示器', primary: false }
-// ]
-```
-
-`checkComputerEnvironment(): Promise<EnvironmentCheck>`
-
-检查计算机环境是否正确配置。
-
-**返回：**
-
-```typescript
-interface EnvironmentCheck {
-  available: boolean;
-  error?: string;
-  platform: string;
-  displays: number;
-}
-```
-
-**示例：**
-
-```typescript
-import { checkComputerEnvironment } from '@midscene/computer';
-
-const env = await checkComputerEnvironment();
-console.log('环境检查:', env);
-
-if (!env.available) {
-  console.error('环境错误:', env.error);
-}
-```
-
-## ComputerAgent
-
-`ComputerAgent` 类继承自 `PageAgent<ComputerDevice>`，并继承所有通用 agent 方法：
-
-- `aiAct(action: string)`：使用 AI 执行操作
-- `aiQuery(query: string)`：使用 AI 提取信息
-- `aiAssert(assertion: string)`：使用 AI 断言条件
-- `aiWaitFor(condition: string)`：等待条件
-- `aiLocate(description: string)`：定位元素
-- 更多...
-
-定位元素后，还可以使用即时操作（Instant Action）进行直接、确定性的控制：
-
-- `aiTap()`、`aiDoubleClick()`、`aiRightClick()`、`aiHover()`：鼠标操作
-- `aiInput()`、`aiClearInput()`、`aiKeyboardPress()`：键盘操作
-- `aiScroll()`：滚动操作
-
-详见 [通用 API 参考](./api)。
-
-## 可用操作
-
-`ComputerDevice` 支持以下操作：
-
-### 鼠标操作
-
-#### Tap（点击）
-
-在目标位置单击。
-
-```typescript
-await agent.aiAct('点击文件菜单');
-await agent.aiAct('点击屏幕中心');
-```
-
-#### DoubleClick（双击）
-
-在目标位置双击。
-
-```typescript
-await agent.aiAct('双击桌面图标');
-```
-
-#### RightClick（右键）
-
-右键点击打开上下文菜单。
-
-```typescript
-await agent.aiAct('右键点击桌面');
-await agent.aiAct('右键点击文件');
-```
-
-#### MouseMove（移动鼠标 / 悬停）
-
-将鼠标移动到目标元素上，也就是鼠标悬停（hover），例如用于触发悬停菜单或提示框。
-
-```typescript
-// 自然语言形式（移动鼠标 / 悬停）
-await agent.aiAct('移动鼠标到菜单项');
-
-// 即时操作：一次调用完成定位并悬停
-await agent.aiHover('菜单项「Products」');
-```
-
-#### DragAndDrop（拖放）
-
-从一个位置拖动并放到另一个位置。
-
-```typescript
-await agent.aiAct('将文件拖到文件夹');
-```
-
-### 键盘操作
-
-#### KeyboardPress（按键）
-
-按键盘按键，可选修饰键。
-
-**支持的按键：**
-- 普通键：`a-z`、`0-9`、`Enter`、`Escape`、`Space`、`Tab` 等
-- 方向键：`ArrowUp`、`ArrowDown`、`ArrowLeft`、`ArrowRight`
-- 功能键：`F1`-`F12`
-- 修饰键：`Command`/`Cmd`（macOS）、`Control`/`Ctrl`、`Alt`、`Shift`、`Win`（Windows）
-- 媒体键：`VolumeUp`、`VolumeDown`、`Mute` 等
-
-**示例：**
-
-```typescript
-// 简单按键
-await agent.aiAct('按 Enter');
-await agent.aiAct('按 Escape');
-
-// 组合键（平台特定）
-if (process.platform === 'darwin') {
-  // macOS
-  await agent.aiAct('按 Cmd+Space');  // 打开 Spotlight
-  await agent.aiAct('按 Cmd+Tab');    // 应用切换器
-  await agent.aiAct('按 Cmd+C');      // 复制
-  await agent.aiAct('按 Cmd+V');      // 粘贴
-} else {
-  // Windows/Linux
-  await agent.aiAct('按 Windows 键'); // 开始菜单
-  await agent.aiAct('按 Alt+Tab');    // 应用切换器
-  await agent.aiAct('按 Ctrl+C');     // 复制
-  await agent.aiAct('按 Ctrl+V');     // 粘贴
-}
-
-// 方向键
-await agent.aiAct('按 ArrowDown');
-await agent.aiAct('按 ArrowUp');
-
-// 功能键
-await agent.aiAct('按 F5');  // 刷新
-```
-
-#### Input（输入）
-
-在输入框中输入文本。
-
-```typescript
-await agent.aiAct('在搜索框输入 "你好世界"');
-await agent.aiAct('输入 "我的文档.txt"');
-```
-
-#### ClearInput（清空输入）
-
-清空输入框内容。
-
-```typescript
-await agent.aiAct('清空文本框');
-```
-
-### 滚动操作
-
-滚动屏幕或特定区域。
-
-```typescript
-// 滚动方向
-await agent.aiAct('向下滚动');
-await agent.aiAct('向上滚动');
-await agent.aiAct('向左滚动');
-await agent.aiAct('向右滚动');
-
-// 滚动到位置
-await agent.aiAct('滚动到顶部');
-await agent.aiAct('滚动到底部');
-```
-
-### 显示器操作
-
-#### ListDisplays（列出显示器）
-
-获取所有已连接显示器的信息。
-
-```typescript
-const displays = await ComputerDevice.listDisplays();
-```
-
-使用 RDP 时，`ListDisplays` 会把当前远程会话视为单个显示器返回。
-
-## 示例
-
-### 打开应用并导航
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-const agent = await agentForComputer();
-
-// 打开应用
-if (process.platform === 'darwin') {
-  await agent.aiAct('按 Cmd+Space');
-  await agent.aiAct('输入 "文本编辑" 并按回车');
-} else {
-  await agent.aiAct('按 Windows 键');
-  await agent.aiAct('输入 "记事本" 并按回车');
-}
-
-await agent.aiWaitFor('文本编辑器窗口可见');
-
-// 输入内容
-await agent.aiAct('输入 "你好，Midscene！"');
-
-// 保存文件
-if (process.platform === 'darwin') {
-  await agent.aiAct('按 Cmd+S');
-} else {
-  await agent.aiAct('按 Ctrl+S');
-}
-```
-
-### 多显示器工作流
-
-```typescript
-import { ComputerDevice, agentForComputer } from '@midscene/computer';
-
-// 列出显示器
-const displays = await ComputerDevice.listDisplays();
-console.log(`找到 ${displays.length} 个显示器`);
-
-// 控制主显示器
-const agent1 = await agentForComputer({
-  displayId: displays[0].id,
-});
-await agent1.aiAct('将鼠标移动到屏幕中心');
-
-// 控制副显示器
-if (displays.length > 1) {
-  const agent2 = await agentForComputer({
-    displayId: displays[1].id,
-  });
-  await agent2.aiAct('将鼠标移动到屏幕中心');
-}
-```
-
-### Web 浏览器自动化
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-const agent = await agentForComputer();
-
-// 打开浏览器
-if (process.platform === 'darwin') {
-  await agent.aiAct('按 Cmd+Space');
-  await agent.aiAct('输入 "Safari" 并按回车');
-} else {
-  await agent.aiAct('按 Windows 键');
-  await agent.aiAct('输入 "Chrome" 并按回车');
-}
-
-await agent.aiWaitFor('浏览器窗口已打开');
-
-// 导航
-await agent.aiAct('点击地址栏');
-await agent.aiAct('输入 "example.com" 并按回车');
-await agent.aiWaitFor('页面已加载');
-
-// 提取信息
-const title = await agent.aiQuery('string, 获取页面标题');
-console.log('页面标题:', title);
-```
-
-## TypeScript 类型
-
-```typescript
-import type {
-  ComputerAgent,
-  ComputerAgentOpt,
-  ComputerDevice,
-  ComputerDeviceOpt,
-  DisplayInfo,
-  EnvironmentCheck,
-} from '@midscene/computer';
-```
-
-## 另请参阅
-
-- [通用 API 参考](./api) - 适用于所有平台的 API
-- [模型配置](./model-config) - 配置 AI 模型
-- [缓存](./caching) - 使用缓存提高性能
diff --git a/apps/site/docs/zh/computer-getting-started.mdx b/apps/site/docs/zh/computer-getting-started.mdx
deleted file mode 100644
index 9f50b9f938..0000000000
--- a/apps/site/docs/zh/computer-getting-started.mdx
+++ /dev/null
@@ -1,297 +0,0 @@
-import StartExperience from './common/start-experience.mdx';
-import SetupEnv from './common/setup-env.mdx';
-
-import { PackageManagerTabs } from '@theme';
-
-# PC 桌面入门指南
-
-本指南将引导您完成使用 Midscene 自动化 PC 桌面应用所需的一切：安装依赖、配置模型凭据并运行您的第一个 JavaScript 脚本。
-
-:::info 示例项目
-
-使用 JavaScript 控制 PC 桌面：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo)
-
-集成 Vitest 进行测试：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo)
-
-通过 RDP 控制远程 Windows 桌面：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
-
-使用 `@midscene/computer` 在无头 Linux CI 中测试 [Obsidian](https://obsidian.md/)（Electron 应用）：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
-
-:::
-
-<SetupEnv />
-
-## 系统要求
-
-### Node.js
-
-需要 Node.js 18.19.0 或更高版本。
-
-### 平台特定依赖
-
-**macOS**：需要辅助功能权限才能控制键盘和鼠标。首次运行脚本时，macOS 会提示你授予访问权限。前往 **系统设置 > 隐私与安全性 > 辅助功能**，为运行脚本的应用程序（如 Terminal、iTerm2、VS Code、WebStorm 或其他 IDE）启用权限。更多详情请参阅 [nut.js macOS 设置](https://github.com/nut-tree/nut.js#macos)。
-
-**Windows**：操作普通程序无需额外配置。但 Windows 会按权限级别隔离输入（UIPI）：未提权的进程**无法**向以**管理员身份运行（已提权）**的窗口发送鼠标或键盘输入，输入会被静默丢弃——光标仍会移动到正确位置，但点击和按键不生效。优先尝试让目标程序不要以管理员权限运行；如果目标程序必须保持提权状态，再**同样以管理员身份运行启动 Midscene 的终端或 Node.js**，让两个进程处于相同的权限级别。详见 [Windows：点击对某些程序不生效](#windows点击对某些程序不生效)。
-
-**Linux**：需要安装 [ImageMagick](https://imagemagick.org/script/download.php) 用于截图功能。
-
-**无头 Linux（CI 环境）**：要在无头 Linux 服务器（如 GitHub Actions）上运行桌面自动化，需安装 Xvfb 及其依赖，然后启用 headless 模式：
-
-```bash
-# 安装依赖
-sudo apt-get install -y xvfb x11-xserver-utils imagemagick
-```
-
-```typescript
-// 方式 1：传入 headless 选项
-const agent = await agentForComputer({ headless: true });
-
-// 方式 2：设置环境变量
-// MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
-```
-
-Xvfb 会创建一个虚拟显示器，使鼠标、键盘和截图操作在没有物理显示器的情况下正常工作。详见 [API 参考](./computer-api-reference)。
-
-## 试用 Playground（零代码）
-
-Playground 是验证连接、观察 AI Agent 的最快方式，无需编写代码。它与 `@midscene/computer` 共享相同的代码实现，因此在 Playground 上验证通过的流程，用脚本运行时也完全一致。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
-
-1. 启动 Playground CLI：
-
-```bash
-npx --yes @midscene/computer-playground
-```
-
-2. 点击 Playground 窗口中的齿轮按钮，粘贴你的 API Key 配置。如果还没有 API Key，请回到 [模型配置](./model-config) 获取。
-
-## 开始体验
-
-<StartExperience />
-
-## 与 Midscene Agent 集成
-
-当 Playground 运行正常后，就可以切换到可复用的 JavaScript 脚本。
-
-### 步骤 1. 安装依赖
-
-<PackageManagerTabs command="install @midscene/computer" />
-
-### 步骤 2. 编写您的第一个脚本
-
-创建 `example.ts`：
-
-```typescript
-import { agentForComputer } from '@midscene/computer';
-
-(async () => {
-  // 创建 agent
-  const agent = await agentForComputer({
-    aiActionContext: '你正在控制一台桌面计算机。',
-  });
-
-  // 截图并查询信息
-  const screenInfo = await agent.aiQuery(
-    '{width: number, height: number}, 获取屏幕分辨率'
-  );
-  console.log('屏幕分辨率:', screenInfo);
-
-  // 移动鼠标到中心
-  await agent.aiAct('将鼠标移动到屏幕中心');
-
-  // 断言屏幕有内容
-  await agent.aiAssert('屏幕有可见内容');
-
-  console.log('桌面自动化完成！');
-})();
-```
-
-### 步骤 3. 运行脚本
-
-```bash
-npx tsx example.ts
-```
-
-## 通过 RDP 连接远程 Windows 桌面
-
-`@midscene/computer` 也可以通过专用的 `agentForRDPComputer()` 工厂，直接经由 RDP 协议控制远程 Windows 桌面。
-
-### 前提条件
-
-1. 一台已开启 RDP 且网络可达的 Windows 机器。
-2. 在运行脚本的机器上安装 [FreeRDP](https://www.freerdp.com/)。
-
-### 示例
-
-```typescript
-import { agentForRDPComputer } from '@midscene/computer';
-
-const agent = await agentForRDPComputer({
-  aiActionContext:
-    'You are controlling a remote Windows desktop over the RDP protocol.',
-  host: '10.75.166.249',
-  port: 3389,
-  username: 'Admin',
-  password: 'replace-with-your-password',
-  ignoreCertificate: true,
-});
-
-await agent.aiWaitFor('The remote Windows desktop is visible');
-await agent.aiAct('Click the Windows Start button');
-await agent.aiAct('Open Settings');
-await agent.aiAssert('The Windows Settings window is visible');
-```
-
-### 常用 RDP 选项
-
-- `host`：远程 Windows 主机名或 IP。
-- `port`：RDP 端口，默认是 `3389`。
-- `username` / `password`：远程会话使用的账号凭据。
-- `domain`：可选的 Windows 域。
-- `ignoreCertificate`：用于跳过自签名证书校验。
-- `desktopWidth` / `desktopHeight`：请求指定远程桌面分辨率。
-- `adminSession`：当服务端允许时，请求远程管理员会话。
-
-对于 Midscene 来说，一个 RDP 会话会被视为单个远程显示器。你仍然可以像本机桌面自动化一样，使用 `aiAct`、`aiQuery`、`aiAssert` 和报告能力。
-
-## 多显示器支持
-
-如果您有多个显示器，可以控制特定的显示器：
-
-```typescript
-import { ComputerDevice, agentForComputer } from '@midscene/computer';
-
-// 列出所有显示器
-const displays = await ComputerDevice.listDisplays();
-console.log('可用显示器:', displays);
-
-// 连接到特定显示器
-const agent = await agentForComputer({
-  displayId: displays[0].id,
-});
-```
-
-## 使用示例
-
-### 基本鼠标操作
-
-```typescript
-// 在屏幕中心点击
-await agent.aiAct('在屏幕中心点击鼠标');
-
-// 移动鼠标到特定位置
-await agent.aiAct('将鼠标移动到左上角');
-
-// 双击
-await agent.aiAct('双击桌面图标');
-
-// 右键
-await agent.aiAct('右键打开上下文菜单');
-```
-
-### 键盘操作
-
-```typescript
-// 输入文本
-await agent.aiAct('输入 "你好世界"');
-
-// 按快捷键
-if (process.platform === 'darwin') {
-  await agent.aiAct('按 Cmd+Space 打开 Spotlight');
-  await agent.aiAct('输入 "计算器" 并按回车');
-} else {
-  await agent.aiAct('按 Windows 键');
-  await agent.aiAct('输入 "计算器" 并按回车');
-}
-
-// 按功能键
-await agent.aiAct('按 Escape');
-await agent.aiAct('按 Enter');
-```
-
-### 查询信息
-
-```typescript
-// 提取屏幕信息
-const info = await agent.aiQuery(
-  '{hasDesktop: boolean, visibleApps: string[]}, 检查桌面是否可见并列出可见应用'
-);
-
-// 定位元素
-const position = await agent.aiLocate('文件菜单');
-console.log('文件菜单位置:', position);
-```
-
-### 复杂工作流
-
-```typescript
-// 打开应用并与之交互
-await agent.aiAct('打开访达');
-await agent.aiWaitFor('访达窗口可见');
-
-await agent.aiAct('点击文稿文件夹');
-await agent.aiAct('按 Cmd+N 创建新文件夹');
-await agent.aiAct('输入 "我的项目"');
-await agent.aiAct('按回车');
-
-await agent.aiAssert('存在名为 "我的项目" 的文件夹');
-```
-
-## 环境检查
-
-您可以检查系统是否正确配置：
-
-```typescript
-import { checkComputerEnvironment } from '@midscene/computer';
-
-const env = await checkComputerEnvironment();
-console.log('平台:', env.platform);
-console.log('可用:', env.available);
-console.log('显示器数量:', env.displays);
-
-if (!env.available) {
-  console.error('环境不可用:', env.error);
-}
-```
-
-## 常见问题
-
-### macOS：脚本无法控制鼠标或键盘
-
-macOS 需要辅助功能权限才能控制键盘和鼠标。请前往 **系统设置 > 隐私与安全性 > 辅助功能**，为运行脚本的应用程序（如 Terminal、iTerm2、VS Code 或 WebStorm）开启权限。
-
-如果已经授权但仍然无法控制，可以尝试将该应用从辅助功能列表中移除后重新添加——macOS 有时会缓存过期的权限。
-
-### Windows：点击对某些程序不生效
-
-如果光标能移动到正确位置，但对某个程序点击或按键毫无反应，而其他程序却正常，请检查目标程序是否以**管理员身份运行（已提权）**。Windows 的 UIPI 机制会拦截由低权限进程注入到高权限窗口的输入，并静默丢弃，且不报任何错误。
-
-优先尝试降低目标程序的权限级别，例如不要使用“以管理员身份运行”启动它，或关闭总是提权启动的相关设置。如果目标程序必须保持提权状态，再**以管理员身份运行**启动 Midscene 的终端（或 Node.js），使其与目标程序处于相同的权限级别，然后重试。像 `Win+Tab` 这类系统级快捷键由 shell 处理，即使在这种情况下也照常生效——这也是为什么有时键盘快捷键看起来能用、但程序内的点击却不行。
-
-> 在 Windows 上，如果 Midscene 未以管理员身份运行，连接时的健康检查日志会打印这条排查文档链接。
-
-### Linux：在无头服务器上截图或交互失败
-
-无头 Linux 环境（如 CI）没有物理显示器，需要安装 Xvfb 和 ImageMagick，并启用无头模式：
-
-```bash
-sudo apt-get install -y xvfb x11-xserver-utils imagemagick
-```
-
-```typescript
-const agent = await agentForComputer({ headless: true });
-```
-
-或通过环境变量设置：
-
-```bash
-MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
-```
-
-## 下一步
-
-- [API 参考](./computer-api-reference)
-- [使用 YAML 格式自动化脚本](./automate-with-scripts-in-yaml)
-- [YAML 脚本运行器](./yaml-script-runner)
-- [缓存提高效率](./caching)
diff --git a/apps/site/docs/zh/computer-introduction.mdx b/apps/site/docs/zh/computer-introduction.mdx
deleted file mode 100644
index 6c9e04ead5..0000000000
--- a/apps/site/docs/zh/computer-introduction.mdx
+++ /dev/null
@@ -1,64 +0,0 @@
-import ShowcaseComputer from './showcases-computer.mdx';
-
-# PC 桌面自动化支持
-
-Midscene 可以驱动原生键盘和鼠标控制，在 Windows、macOS 和 Linux 上支持 PC 桌面自动化。
-
-通过采用视觉模型方案，自动化流程可以适配任何桌面应用程序——无论是用 Electron、Qt、WPF 还是原生技术构建的。开发者在调试 UI 自动化脚本时，只需关注最终的用户体验。
-
-PC 桌面自动化方案具备 Midscene 的所有特性：
-
-- 支持使用 Playground 进行零代码试用
-- 支持 JavaScript SDK 进行脚本编写
-- 支持 YAML 格式的自动化脚本和命令行工具
-- 支持 HTML 报告回放所有操作路径
-- 跨 Windows、macOS 和 Linux 平台
-- 支持 Linux CI 无头模式（通过 Xvfb，无需物理显示器）
-- 多显示器支持复杂设置
-
-## 案例展示
-
-<ShowcaseComputer />
-
-查看更多案例：[showcases](./showcases.mdx)
-
-## 在 Playground 中试用
-
-借助 Midscene.js Playground，你无需编写任何代码就能体验 PC 桌面自动化能力。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
-
-查看 [开始使用](./computer-getting-started#试用-playground零代码) 了解如何启动 Playground。
-
-## 核心功能
-
-### 跨平台桌面控制
-
-- **鼠标操作**：单击、双击、右键、移动鼠标、拖放
-- **键盘输入**：输入文本、按键组合（Cmd/Ctrl/Alt/Shift）
-- **屏幕截图**：捕获任意显示器的截图
-- **多显示器**：同时操作多个显示器
-
-### AI 驱动自动化
-
-使用 Midscene 的 AI 能力，您可以用自然语言自动化桌面应用：
-
-```typescript
-await agent.aiAct('打开文件菜单');
-await agent.aiAct('点击另存为');
-await agent.aiAct('在文件名字段输入 "我的文档"');
-await agent.aiAct('按回车键');
-```
-
-## 使用场景
-
-- **桌面应用测试**：自动化测试 Electron、Qt 或原生应用
-- **工作流自动化**：自动化桌面应用中的重复任务
-- **跨应用集成**：按顺序控制多个应用程序
-- **UI 测试**：使用自然语言描述测试桌面应用
-
-## 下一步
-
-* [开始使用](./computer-getting-started)
-* [API 参考](./computer-api-reference)
-* [使用 YAML 格式自动化脚本](./automate-with-scripts-in-yaml) 和 [YAML 脚本运行器](./yaml-script-runner)
diff --git a/apps/site/docs/zh/computer.mdx b/apps/site/docs/zh/computer.mdx
new file mode 100644
index 0000000000..1338029d4e
--- /dev/null
+++ b/apps/site/docs/zh/computer.mdx
@@ -0,0 +1,737 @@
+import ShowcaseComputer from './showcases-computer.mdx';
+import StartExperience from './common/start-experience.mdx';
+import SetupEnv from './common/setup-env.mdx';
+
+import { PackageManagerTabs } from '@theme';
+
+# PC 桌面自动化支持
+
+Midscene 可以驱动原生键盘和鼠标控制，在 Windows、macOS 和 Linux 上支持 PC 桌面自动化。
+
+## 案例展示
+
+<ShowcaseComputer />
+
+查看更多案例：[showcases](./showcases.mdx)
+
+本指南将引导您完成使用 Midscene 自动化 PC 桌面应用所需的一切：安装依赖、配置模型凭据并运行您的第一个 JavaScript 脚本。
+
+:::info 示例项目
+
+使用 JavaScript 控制 PC 桌面：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/javascript-sdk-demo)
+
+集成 Vitest 进行测试：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/vitest-demo)
+
+通过 RDP 控制远程 Windows 桌面：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
+
+使用 `@midscene/computer` 在无头 Linux CI 中测试 [Obsidian](https://obsidian.md/)（Electron 应用）：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
+
+:::
+
+<SetupEnv />
+
+## 系统要求
+
+### Node.js
+
+需要 Node.js 18.19.0 或更高版本。
+
+### 平台特定依赖
+
+**macOS**：需要辅助功能权限才能控制键盘和鼠标。首次运行脚本时，macOS 会提示你授予访问权限。前往 **系统设置 > 隐私与安全性 > 辅助功能**，为运行脚本的应用程序（如 Terminal、iTerm2、VS Code、WebStorm 或其他 IDE）启用权限。更多详情请参阅 [nut.js macOS 设置](https://github.com/nut-tree/nut.js#macos)。
+
+**Windows**：操作普通程序无需额外配置。但 Windows 会按权限级别隔离输入（UIPI）：未提权的进程**无法**向以**管理员身份运行（已提权）**的窗口发送鼠标或键盘输入，输入会被静默丢弃——光标仍会移动到正确位置，但点击和按键不生效。优先尝试让目标程序不要以管理员权限运行；如果目标程序必须保持提权状态，再**同样以管理员身份运行启动 Midscene 的终端或 Node.js**，让两个进程处于相同的权限级别。详见 [Windows：点击对某些程序不生效](#windows点击对某些程序不生效)。
+
+**Linux**：需要安装 [ImageMagick](https://imagemagick.org/script/download.php) 用于截图功能。
+
+**无头 Linux（CI 环境）**：要在无头 Linux 服务器（如 GitHub Actions）上运行桌面自动化，需安装 Xvfb 及其依赖，然后启用 headless 模式：
+
+```bash
+# 安装依赖
+sudo apt-get install -y xvfb x11-xserver-utils imagemagick
+```
+
+```typescript
+// 方式 1：传入 headless 选项
+const agent = await agentForComputer({ headless: true });
+
+// 方式 2：设置环境变量
+// MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
+```
+
+Xvfb 会创建一个虚拟显示器，使鼠标、键盘和截图操作在没有物理显示器的情况下正常工作。详见 [API 参考](#api-reference)。
+
+## 试用 Playground（零代码）
+
+Playground 是验证连接、观察 AI Agent 的最快方式，无需编写代码。它与 `@midscene/computer` 共享相同的代码实现，因此在 Playground 上验证通过的流程，用脚本运行时也完全一致。
+
+<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/pc-twitter2.mp4" controls/>
+
+1. 启动 Playground CLI：
+
+```bash
+npx --yes @midscene/computer-playground
+```
+
+2. 点击 Playground 窗口中的齿轮按钮，粘贴你的 API Key 配置。如果还没有 API Key，请回到 [模型配置](./model-config) 获取。
+
+## 开始体验
+
+<StartExperience />
+
+## 与 Midscene Agent 集成
+
+当 Playground 运行正常后，就可以切换到可复用的 JavaScript 脚本。
+
+### 步骤 1. 安装依赖
+
+<PackageManagerTabs command="install @midscene/computer" />
+
+### 步骤 2. 编写您的第一个脚本
+
+创建 `example.ts`：
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+(async () => {
+  // 创建 agent
+  const agent = await agentForComputer({
+    aiActionContext: '你正在控制一台桌面计算机。',
+  });
+
+  // 截图并查询信息
+  const screenInfo = await agent.aiQuery(
+    '{width: number, height: number}, 获取屏幕分辨率'
+  );
+  console.log('屏幕分辨率:', screenInfo);
+
+  // 移动鼠标到中心
+  await agent.aiAct('将鼠标移动到屏幕中心');
+
+  // 断言屏幕有内容
+  await agent.aiAssert('屏幕有可见内容');
+
+  console.log('桌面自动化完成！');
+})();
+```
+
+### 步骤 3. 运行脚本
+
+```bash
+npx tsx example.ts
+```
+
+## 通过 RDP 连接远程 Windows 桌面
+
+`@midscene/computer` 也可以通过专用的 `agentForRDPComputer()` 工厂，直接经由 RDP 协议控制远程 Windows 桌面。
+
+### 前提条件
+
+1. 一台已开启 RDP 且网络可达的 Windows 机器。
+2. 在运行脚本的机器上安装 [FreeRDP](https://www.freerdp.com/)。
+
+### 示例
+
+```typescript
+import { agentForRDPComputer } from '@midscene/computer';
+
+const agent = await agentForRDPComputer({
+  aiActionContext:
+    'You are controlling a remote Windows desktop over the RDP protocol.',
+  host: '10.75.166.249',
+  port: 3389,
+  username: 'Admin',
+  password: 'replace-with-your-password',
+  ignoreCertificate: true,
+});
+
+await agent.aiWaitFor('The remote Windows desktop is visible');
+await agent.aiAct('Click the Windows Start button');
+await agent.aiAct('Open Settings');
+await agent.aiAssert('The Windows Settings window is visible');
+```
+
+### 常用 RDP 选项
+
+- `host`：远程 Windows 主机名或 IP。
+- `port`：RDP 端口，默认是 `3389`。
+- `username` / `password`：远程会话使用的账号凭据。
+- `domain`：可选的 Windows 域。
+- `ignoreCertificate`：用于跳过自签名证书校验。
+- `desktopWidth` / `desktopHeight`：请求指定远程桌面分辨率。
+- `adminSession`：当服务端允许时，请求远程管理员会话。
+
+对于 Midscene 来说，一个 RDP 会话会被视为单个远程显示器。你仍然可以像本机桌面自动化一样，使用 `aiAct`、`aiQuery`、`aiAssert` 和报告能力。
+
+## 多显示器支持
+
+如果您有多个显示器，可以控制特定的显示器：
+
+```typescript
+import { ComputerDevice, agentForComputer } from '@midscene/computer';
+
+// 列出所有显示器
+const displays = await ComputerDevice.listDisplays();
+console.log('可用显示器:', displays);
+
+// 连接到特定显示器
+const agent = await agentForComputer({
+  displayId: displays[0].id,
+});
+```
+
+## 使用示例
+
+### 基本鼠标操作
+
+```typescript
+// 在屏幕中心点击
+await agent.aiAct('在屏幕中心点击鼠标');
+
+// 移动鼠标到特定位置
+await agent.aiAct('将鼠标移动到左上角');
+
+// 双击
+await agent.aiAct('双击桌面图标');
+
+// 右键
+await agent.aiAct('右键打开上下文菜单');
+```
+
+### 键盘操作
+
+```typescript
+// 输入文本
+await agent.aiAct('输入 "你好世界"');
+
+// 按快捷键
+if (process.platform === 'darwin') {
+  await agent.aiAct('按 Cmd+Space 打开 Spotlight');
+  await agent.aiAct('输入 "计算器" 并按回车');
+} else {
+  await agent.aiAct('按 Windows 键');
+  await agent.aiAct('输入 "计算器" 并按回车');
+}
+
+// 按功能键
+await agent.aiAct('按 Escape');
+await agent.aiAct('按 Enter');
+```
+
+### 查询信息
+
+```typescript
+// 提取屏幕信息
+const info = await agent.aiQuery(
+  '{hasDesktop: boolean, visibleApps: string[]}, 检查桌面是否可见并列出可见应用'
+);
+
+// 定位元素
+const position = await agent.aiLocate('文件菜单');
+console.log('文件菜单位置:', position);
+```
+
+### 复杂工作流
+
+```typescript
+// 打开应用并与之交互
+await agent.aiAct('打开访达');
+await agent.aiWaitFor('访达窗口可见');
+
+await agent.aiAct('点击文稿文件夹');
+await agent.aiAct('按 Cmd+N 创建新文件夹');
+await agent.aiAct('输入 "我的项目"');
+await agent.aiAct('按回车');
+
+await agent.aiAssert('存在名为 "我的项目" 的文件夹');
+```
+
+## 环境检查
+
+您可以检查系统是否正确配置：
+
+```typescript
+import { checkComputerEnvironment } from '@midscene/computer';
+
+const env = await checkComputerEnvironment();
+console.log('平台:', env.platform);
+console.log('可用:', env.available);
+console.log('显示器数量:', env.displays);
+
+if (!env.available) {
+  console.error('环境不可用:', env.error);
+}
+```
+
+## 常见问题
+
+### macOS：脚本无法控制鼠标或键盘
+
+macOS 需要辅助功能权限才能控制键盘和鼠标。请前往 **系统设置 > 隐私与安全性 > 辅助功能**，为运行脚本的应用程序（如 Terminal、iTerm2、VS Code 或 WebStorm）开启权限。
+
+如果已经授权但仍然无法控制，可以尝试将该应用从辅助功能列表中移除后重新添加——macOS 有时会缓存过期的权限。
+
+### Windows：点击对某些程序不生效
+
+如果光标能移动到正确位置，但对某个程序点击或按键毫无反应，而其他程序却正常，请检查目标程序是否以**管理员身份运行（已提权）**。Windows 的 UIPI 机制会拦截由低权限进程注入到高权限窗口的输入，并静默丢弃，且不报任何错误。
+
+优先尝试降低目标程序的权限级别，例如不要使用“以管理员身份运行”启动它，或关闭总是提权启动的相关设置。如果目标程序必须保持提权状态，再**以管理员身份运行**启动 Midscene 的终端（或 Node.js），使其与目标程序处于相同的权限级别，然后重试。像 `Win+Tab` 这类系统级快捷键由 shell 处理，即使在这种情况下也照常生效——这也是为什么有时键盘快捷键看起来能用、但程序内的点击却不行。
+
+> 在 Windows 上，如果 Midscene 未以管理员身份运行，连接时的健康检查日志会打印这条排查文档链接。
+
+### Linux：在无头服务器上截图或交互失败
+
+无头 Linux 环境（如 CI）没有物理显示器，需要安装 Xvfb 和 ImageMagick，并启用无头模式：
+
+```bash
+sudo apt-get install -y xvfb x11-xserver-utils imagemagick
+```
+
+```typescript
+const agent = await agentForComputer({ headless: true });
+```
+
+或通过环境变量设置：
+
+```bash
+MIDSCENE_COMPUTER_HEADLESS_LINUX=true npx tsx example.ts
+```
+
+## API 参考 {#api-reference}
+
+本节记录了 `@midscene/computer` 提供的 PC 桌面特定 API。
+
+有关适用于所有平台的通用 API，请参阅 [通用 API 参考](./api)。
+
+### Agent 创建
+
+`agentForComputer(opts?): Promise<ComputerAgent>`
+
+创建用于本机桌面自动化的 agent。
+
+> 向后兼容：`agentFromComputer` 仍可作为别名使用。
+
+`agentForRDPComputer(opts): Promise<ComputerAgent<RDPDevice>>`
+
+创建用于通过 RDP 控制远程 Windows 桌面的 agent。
+
+**参数：**
+
+```typescript
+interface BaseComputerAgentOpt {
+  // Agent 选项（继承自 AgentOpt）
+  aiActionContext?: string;
+  cache?: boolean;
+  // ... 其他 AgentOpt 属性
+
+  customActions?: DeviceAction<any>[];
+}
+
+interface LocalComputerAgentOpt extends BaseComputerAgentOpt {
+
+  // 本机桌面选项
+  displayId?: string;
+  headless?: boolean;
+  xvfbResolution?: string;
+}
+
+interface RDPComputerAgentOpt extends BaseComputerAgentOpt {
+  host: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  domain?: string;
+  adminSession?: boolean;
+  ignoreCertificate?: boolean;
+  securityProtocol?: 'auto' | 'tls' | 'nla' | 'rdp';
+  desktopWidth?: number;
+  desktopHeight?: number;
+}
+```
+
+#### 本机桌面选项
+
+- `displayId`（可选）：指定要控制的显示器。使用 `ComputerDevice.listDisplays()` 获取可用显示器。
+- `customActions`（可选）：向设备添加自定义操作。
+- `headless`（可选，仅 Linux）：设为 `true` 时通过 [Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) 启动虚拟显示器，使桌面自动化能在无物理显示器的 Linux 服务器和 CI 环境中运行。也可通过环境变量 `MIDSCENE_COMPUTER_HEADLESS_LINUX=true` 设置。
+- `xvfbResolution`（可选）：Xvfb 虚拟显示器的分辨率，默认为 `'1920x1080x24'`。
+
+#### RDP 选项
+
+- `host`：远程 Windows 主机名或 IP。
+- `port`：RDP 端口，默认是 `3389`。
+- `username` / `password`：远程会话凭据。
+- `domain`：可选的 Windows 域。
+- `adminSession`：当服务端允许时，请求远程管理员会话。
+- `ignoreCertificate`：用于跳过自签名证书校验。
+- `securityProtocol`：可选 `'auto'`、`'tls'`、`'nla'` 或 `'rdp'`。
+- `desktopWidth` / `desktopHeight`：请求指定远程桌面分辨率。
+
+:::tip 示例：在无头 Linux CI 中测试 Electron 应用
+使用 `@midscene/computer` 在无头 Linux CI 中测试 [Obsidian](https://obsidian.md/)（Electron 应用）的完整示例：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/electron-demo)
+:::
+
+**示例：**
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+// 连接到主显示器
+const agent = await agentForComputer({
+  aiActionContext: '你正在自动化一个桌面应用。',
+});
+
+// 连接到特定显示器
+const displays = await ComputerDevice.listDisplays();
+const agent2 = await agentForComputer({
+  displayId: displays[1].id,
+});
+```
+
+**示例：通过 RDP 连接远程 Windows 桌面**
+
+```typescript
+import { agentForRDPComputer } from '@midscene/computer';
+
+const agent = await agentForRDPComputer({
+  aiActionContext:
+    'You are controlling a remote Windows desktop over the RDP protocol.',
+  host: '10.75.166.249',
+  port: 3389,
+  username: 'Admin',
+  password: 'replace-with-your-password',
+  // 可选：把 TCP 连接绑定到这个本地源 IP。
+  localAddress: '10.75.166.10',
+  ignoreCertificate: true,
+});
+
+await agent.aiWaitFor('The remote Windows desktop is visible');
+await agent.aiAct('Click the Windows Start button');
+await agent.aiAct('Open Settings');
+```
+
+:::tip 示例：通过 RDP 控制远程 Windows 桌面
+一个可直接运行的 Demo：连接远程 Windows，打开「设置」并进入「Windows 更新」，最后输出一份结构化报告：[https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo](https://github.com/web-infra-dev/midscene-example/tree/main/computer/rdp-demo)
+:::
+
+当运行 Midscene 的机器存在多条出站路由，且 RDP 服务器要求从指定本地源
+IP 访问时，可以使用 `localAddress`。这里传入的是 IP 地址，不是网卡名。
+
+### 设备管理
+
+`ComputerDevice.listDisplays(): Promise<DisplayInfo[]>`
+
+列出所有可用显示器。
+
+**返回：**
+
+```typescript
+interface DisplayInfo {
+  id: string;
+  name: string;
+  primary?: boolean;
+}
+```
+
+**示例：**
+
+```typescript
+import { ComputerDevice } from '@midscene/computer';
+
+const displays = await ComputerDevice.listDisplays();
+console.log('可用显示器:', displays);
+// [
+//   { id: '0', name: '内置显示器', primary: true },
+//   { id: '1', name: '外接显示器', primary: false }
+// ]
+```
+
+`checkComputerEnvironment(): Promise<EnvironmentCheck>`
+
+检查计算机环境是否正确配置。
+
+**返回：**
+
+```typescript
+interface EnvironmentCheck {
+  available: boolean;
+  error?: string;
+  platform: string;
+  displays: number;
+}
+```
+
+**示例：**
+
+```typescript
+import { checkComputerEnvironment } from '@midscene/computer';
+
+const env = await checkComputerEnvironment();
+console.log('环境检查:', env);
+
+if (!env.available) {
+  console.error('环境错误:', env.error);
+}
+```
+
+### ComputerAgent
+
+`ComputerAgent` 类继承自 `PageAgent<ComputerDevice>`，并继承所有通用 agent 方法：
+
+- `aiAct(action: string)`：使用 AI 执行操作
+- `aiQuery(query: string)`：使用 AI 提取信息
+- `aiAssert(assertion: string)`：使用 AI 断言条件
+- `aiWaitFor(condition: string)`：等待条件
+- `aiLocate(description: string)`：定位元素
+- 更多...
+
+定位元素后，还可以使用即时操作（Instant Action）进行直接、确定性的控制：
+
+- `aiTap()`、`aiDoubleClick()`、`aiRightClick()`、`aiHover()`：鼠标操作
+- `aiInput()`、`aiClearInput()`、`aiKeyboardPress()`：键盘操作
+- `aiScroll()`：滚动操作
+
+详见 [通用 API 参考](./api)。
+
+### 可用操作
+
+`ComputerDevice` 支持以下操作：
+
+#### 鼠标操作
+
+##### Tap（点击）
+
+在目标位置单击。
+
+```typescript
+await agent.aiAct('点击文件菜单');
+await agent.aiAct('点击屏幕中心');
+```
+
+##### DoubleClick（双击）
+
+在目标位置双击。
+
+```typescript
+await agent.aiAct('双击桌面图标');
+```
+
+##### RightClick（右键）
+
+右键点击打开上下文菜单。
+
+```typescript
+await agent.aiAct('右键点击桌面');
+await agent.aiAct('右键点击文件');
+```
+
+##### MouseMove（移动鼠标 / 悬停）
+
+将鼠标移动到目标元素上，也就是鼠标悬停（hover），例如用于触发悬停菜单或提示框。
+
+```typescript
+// 自然语言形式（移动鼠标 / 悬停）
+await agent.aiAct('移动鼠标到菜单项');
+
+// 即时操作：一次调用完成定位并悬停
+await agent.aiHover('菜单项「Products」');
+```
+
+##### DragAndDrop（拖放）
+
+从一个位置拖动并放到另一个位置。
+
+```typescript
+await agent.aiAct('将文件拖到文件夹');
+```
+
+#### 键盘操作
+
+##### KeyboardPress（按键）
+
+按键盘按键，可选修饰键。
+
+**支持的按键：**
+- 普通键：`a-z`、`0-9`、`Enter`、`Escape`、`Space`、`Tab` 等
+- 方向键：`ArrowUp`、`ArrowDown`、`ArrowLeft`、`ArrowRight`
+- 功能键：`F1`-`F12`
+- 修饰键：`Command`/`Cmd`（macOS）、`Control`/`Ctrl`、`Alt`、`Shift`、`Win`（Windows）
+- 媒体键：`VolumeUp`、`VolumeDown`、`Mute` 等
+
+**示例：**
+
+```typescript
+// 简单按键
+await agent.aiAct('按 Enter');
+await agent.aiAct('按 Escape');
+
+// 组合键（平台特定）
+if (process.platform === 'darwin') {
+  // macOS
+  await agent.aiAct('按 Cmd+Space');  // 打开 Spotlight
+  await agent.aiAct('按 Cmd+Tab');    // 应用切换器
+  await agent.aiAct('按 Cmd+C');      // 复制
+  await agent.aiAct('按 Cmd+V');      // 粘贴
+} else {
+  // Windows/Linux
+  await agent.aiAct('按 Windows 键'); // 开始菜单
+  await agent.aiAct('按 Alt+Tab');    // 应用切换器
+  await agent.aiAct('按 Ctrl+C');     // 复制
+  await agent.aiAct('按 Ctrl+V');     // 粘贴
+}
+
+// 方向键
+await agent.aiAct('按 ArrowDown');
+await agent.aiAct('按 ArrowUp');
+
+// 功能键
+await agent.aiAct('按 F5');  // 刷新
+```
+
+##### Input（输入）
+
+在输入框中输入文本。
+
+```typescript
+await agent.aiAct('在搜索框输入 "你好世界"');
+await agent.aiAct('输入 "我的文档.txt"');
+```
+
+##### ClearInput（清空输入）
+
+清空输入框内容。
+
+```typescript
+await agent.aiAct('清空文本框');
+```
+
+#### 滚动操作
+
+滚动屏幕或特定区域。
+
+```typescript
+// 滚动方向
+await agent.aiAct('向下滚动');
+await agent.aiAct('向上滚动');
+await agent.aiAct('向左滚动');
+await agent.aiAct('向右滚动');
+
+// 滚动到位置
+await agent.aiAct('滚动到顶部');
+await agent.aiAct('滚动到底部');
+```
+
+#### 显示器操作
+
+##### ListDisplays（列出显示器）
+
+获取所有已连接显示器的信息。
+
+```typescript
+const displays = await ComputerDevice.listDisplays();
+```
+
+使用 RDP 时，`ListDisplays` 会把当前远程会话视为单个显示器返回。
+
+### 示例
+
+#### 打开应用并导航
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+const agent = await agentForComputer();
+
+// 打开应用
+if (process.platform === 'darwin') {
+  await agent.aiAct('按 Cmd+Space');
+  await agent.aiAct('输入 "文本编辑" 并按回车');
+} else {
+  await agent.aiAct('按 Windows 键');
+  await agent.aiAct('输入 "记事本" 并按回车');
+}
+
+await agent.aiWaitFor('文本编辑器窗口可见');
+
+// 输入内容
+await agent.aiAct('输入 "你好，Midscene！"');
+
+// 保存文件
+if (process.platform === 'darwin') {
+  await agent.aiAct('按 Cmd+S');
+} else {
+  await agent.aiAct('按 Ctrl+S');
+}
+```
+
+#### 多显示器工作流
+
+```typescript
+import { ComputerDevice, agentForComputer } from '@midscene/computer';
+
+// 列出显示器
+const displays = await ComputerDevice.listDisplays();
+console.log(`找到 ${displays.length} 个显示器`);
+
+// 控制主显示器
+const agent1 = await agentForComputer({
+  displayId: displays[0].id,
+});
+await agent1.aiAct('将鼠标移动到屏幕中心');
+
+// 控制副显示器
+if (displays.length > 1) {
+  const agent2 = await agentForComputer({
+    displayId: displays[1].id,
+  });
+  await agent2.aiAct('将鼠标移动到屏幕中心');
+}
+```
+
+#### Web 浏览器自动化
+
+```typescript
+import { agentForComputer } from '@midscene/computer';
+
+const agent = await agentForComputer();
+
+// 打开浏览器
+if (process.platform === 'darwin') {
+  await agent.aiAct('按 Cmd+Space');
+  await agent.aiAct('输入 "Safari" 并按回车');
+} else {
+  await agent.aiAct('按 Windows 键');
+  await agent.aiAct('输入 "Chrome" 并按回车');
+}
+
+await agent.aiWaitFor('浏览器窗口已打开');
+
+// 导航
+await agent.aiAct('点击地址栏');
+await agent.aiAct('输入 "example.com" 并按回车');
+await agent.aiWaitFor('页面已加载');
+
+// 提取信息
+const title = await agent.aiQuery('string, 获取页面标题');
+console.log('页面标题:', title);
+```
+
+### TypeScript 类型
+
+```typescript
+import type {
+  ComputerAgent,
+  ComputerAgentOpt,
+  ComputerDevice,
+  ComputerDeviceOpt,
+  DisplayInfo,
+  EnvironmentCheck,
+} from '@midscene/computer';
+```
+
+### 另请参阅
+
+- [通用 API 参考](./api) - 适用于所有平台的 API
+- [模型配置](./model-config) - 配置 AI 模型
+- [缓存](./caching) - 使用缓存提高性能
diff --git a/apps/site/docs/zh/faq.md b/apps/site/docs/zh/faq.md
index 161962a736..bd3608686d 100644
--- a/apps/site/docs/zh/faq.md
+++ b/apps/site/docs/zh/faq.md
@@ -8,10 +8,10 @@
 - [Web 浏览器 - Puppeteer](./integrate-with-puppeteer#faq)
 - [Web 浏览器 - Chrome 插件](./quick-experience#faq)
 - [Web 浏览器 - 桥接模式](./bridge-mode#faq)
-- [Android](./android-getting-started#常见问题)
-- [iOS](./ios-getting-started#常见问题)
-- [HarmonyOS](./harmony-getting-started#常见问题)
-- [PC 桌面](./computer-getting-started#常见问题)
+- [Android](./android#常见问题)
+- [iOS](./ios#常见问题)
+- [HarmonyOS](./harmony#常见问题)
+- [PC 桌面](./computer#常见问题)
 
 ## 会有哪些信息发送到 AI 模型？
 
diff --git a/apps/site/docs/zh/harmony-api-reference.mdx b/apps/site/docs/zh/harmony-api-reference.mdx
deleted file mode 100644
index c7b0b00272..0000000000
--- a/apps/site/docs/zh/harmony-api-reference.mdx
+++ /dev/null
@@ -1,217 +0,0 @@
-# API 参考（HarmonyOS）
-
-当你需要自定义设备行为、把 Midscene 接入框架，或排查 HDC 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 [API 参考](./api)。
-
-## Action Space（动作空间）
-
-`HarmonyDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
-
-- `Tap` —— 点击元素。
-- `DoubleClick` —— 双击元素。
-- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式。
-- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
-- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
-- `KeyboardPress` —— 按下指定键位。
-- `LongPress` —— 长按目标元素，可选自定义时长。
-- `ClearInput` —— 清空输入框内容。
-- ~~`Pinch`~~ —— 不支持。HarmonyOS `uitest` 框架未提供多触点输入 API。
-- `Launch` —— 打开 HarmonyOS 应用（bundle name）。
-- `Terminate` —— 按 bundle name 强制停止应用。
-- `RunHdcShell` —— 执行原始 `hdc shell` 命令。
-- `HarmonyBackButton` —— 触发系统返回。
-- `HarmonyHomeButton` —— 回到桌面。
-- `HarmonyRecentAppsButton` —— 打开多任务/最近应用。
-
-## HarmonyDevice {#harmonydevice}
-
-创建一个可供 HarmonyAgent 驱动的 HDC 设备实例。
-
-### 导入
-
-```ts
-import { HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
-```
-
-### 构造函数
-
-```ts
-const device = new HarmonyDevice(deviceId, {
-  // 设备参数...
-});
-```
-
-### 设备选项
-
-- `deviceId: string` —— 来自 `hdc list targets` 或 `getConnectedDevices()` 的值。
-- `hdcPath?: string` —— HDC 可执行文件的自定义路径。若未设置，将依次从 `HDC_HOME` 环境变量和常见安装路径中查找。
-- `autoDismissKeyboard?: boolean` —— 输入完成后自动隐藏键盘，默认 `true`。
-- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` —— 自动隐藏键盘时优先使用的按键，默认 `'esc-first'`。HarmonyOS 只发送该策略的首选按键：`'esc-first'` 发送 ESC，`'back-first'` 发送 Back。
-- `screenshotResizeScale?: number` —— **已废弃。** 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 `AgentOpt` 中的 `screenshotShrinkFactor`。
-- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
-
-### 使用说明
-
-- 可以使用 `getConnectedDevices()` 发现设备，返回的 `deviceId` 与 `hdc list targets` 输出一致。
-- 如果 HDC 不在系统 PATH 中，可通过 `HDC_HOME` 环境变量或 `hdcPath` 选项指定路径。
-
-### 示例
-
-#### 快速开始
-
-```ts
-import { HarmonyAgent, HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
-
-const [first] = await getConnectedDevices();
-const device = new HarmonyDevice(first.deviceId, {});
-await device.connect();
-
-const agent = new HarmonyAgent(device, {
-  aiActionContext: '这是一台鸿蒙设备，如果出现弹窗，点击同意。',
-});
-
-await agent.launch('com.huawei.hmos.settings');
-await agent.aiAct('scroll down one screen');
-const items = await agent.aiQuery(
-  'string[], list all visible setting item names',
-);
-console.log(items);
-```
-
-#### 启动应用
-
-```ts
-await agent.launch('com.huawei.hmos.settings'); // 打开系统设置
-await agent.launch('com.huawei.hmos.camera');    // 打开相机
-await agent.back();
-await agent.home();
-```
-
-## HarmonyAgent {#harmonyagent}
-
-将 Midscene 的 AI 规划能力绑定到 HarmonyDevice，实现 UI 自动化。
-
-### 导入
-
-```ts
-import { HarmonyAgent } from '@midscene/harmony';
-```
-
-### 构造函数
-
-```ts
-const agent = new HarmonyAgent(device, {
-  // 通用 Agent 参数...
-});
-```
-
-### HarmonyOS 特有选项
-
-- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
-- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到 bundle name。当你在 `launch(target)` 里传入应用名称时，Agent 会在此映射中查找对应的 bundle name；若未找到映射，则按原样尝试启动 `target`。
-- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
-
-### 使用说明
-
-:::info
-
-- 一个设备连接对应一个 Agent。
-- `launch`、`terminate`、`runHdcShell` 等 HarmonyOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [HarmonyOS 平台特定动作](./automate-with-scripts-in-yaml#harmony-部分)。
-- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
-
-:::
-
-### HarmonyOS 特有方法
-
-#### `agent.launch()`
-
-启动 HarmonyOS 应用。
-
-```ts
-function launch(uri: string): Promise<void>;
-```
-
-- `uri: string` —— 可以是应用 bundle name（如 `com.huawei.hmos.settings`），也可以是在 `appNameMapping` 中注册的应用名称。如果传入 `http://` 或 `https://` 开头的 URL，将通过浏览器打开。
-
-```ts
-await agent.launch('com.huawei.hmos.settings'); // 打开系统设置
-await agent.launch('com.huawei.hmos.camera');    // 打开相机
-```
-
-#### `agent.runHdcShell()`
-
-通过连接的设备运行原始的 `hdc shell` 命令。
-
-```ts
-function runHdcShell(command: string): Promise<string>;
-```
-
-- `command: string` —— 原样传递给 `hdc shell` 的命令。
-
-```ts
-const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
-console.log(result);
-```
-
-#### `agent.terminate()`
-
-终止（强制停止）正在运行的 HarmonyOS 应用。
-
-```ts
-function terminate(uri: string): Promise<void>;
-```
-
-- `uri: string` —— 应用 bundle name、`appNameMapping` 中的应用名称，或 `bundle/Ability`（仅使用 bundle name 部分）。
-
-```ts
-await agent.terminate('com.huawei.hmos.settings');
-```
-
-#### 导航辅助
-
-- `agent.back(): Promise<void>` —— 触发 HarmonyOS 系统的返回操作。
-- `agent.home(): Promise<void>` —— 返回桌面。
-- `agent.recentApps(): Promise<void>` —— 打开多任务/最近应用界面。
-
-### 辅助工具
-
-#### `agentFromHdcDevice()`
-
-从任意已连接的 HDC 设备创建 `HarmonyAgent`。
-
-```ts
-function agentFromHdcDevice(
-  deviceId?: string,
-  opts?: HarmonyAgentOpt & HarmonyDeviceOpt,
-): Promise<HarmonyAgent>;
-```
-
-- `deviceId?: string` —— 连接特定设备；留空表示使用"第一个可用设备"。
-- `opts?: HarmonyAgentOpt & HarmonyDeviceOpt` —— 在一个对象中合并 Agent 选项与 [`HarmonyDevice`](#harmonydevice) 的设置。
-
-```ts
-import { agentFromHdcDevice } from '@midscene/harmony';
-
-const agent = await agentFromHdcDevice('0123456789ABCDEF'); // 传入 deviceId
-const agent = await agentFromHdcDevice(); // 使用第一个连接的设备
-```
-
-#### `getConnectedDevices()`
-
-列举 Midscene 可驱动的 HDC 设备。
-
-```ts
-function getConnectedDevices(
-  hdcPath?: string,
-): Promise<Array<{ deviceId: string }>>;
-```
-
-```ts
-import { getConnectedDevices } from '@midscene/harmony';
-
-const devices = await getConnectedDevices();
-console.log(devices); // [{ deviceId: '0123456789ABCDEF' }]
-```
-
-### 相关阅读
-
-- [HarmonyOS 快速开始](./harmony-getting-started) 获取搭建与脚本示例。
diff --git a/apps/site/docs/zh/harmony-introduction.mdx b/apps/site/docs/zh/harmony-introduction.mdx
deleted file mode 100644
index 30565255dc..0000000000
--- a/apps/site/docs/zh/harmony-introduction.mdx
+++ /dev/null
@@ -1,34 +0,0 @@
-import ShowcaseHarmony from './showcases-harmony.mdx';
-
-# HarmonyOS 自动化支持
-
-Midscene 可以驱动 HDC（HarmonyOS Device Connector）工具来实现 HarmonyOS NEXT 设备自动化。
-
-由于适配了视觉模型方案，整个自动化过程可以适配任意的 HarmonyOS App 技术栈，无论是 ArkTS 原生还是其他框架构建的 App 都能使用。开发者只需面向最终效果调试 UI 自动化脚本即可。
-
-HarmonyOS UI 自动化解决方案具备 Midscene 的全部特性：
-
-- 支持使用 Playground 进行零代码试用。
-- 支持 JavaScript SDK。
-- 支持使用 YAML 格式的自动化脚本和命令行工具。
-- 支持生成 HTML 报告来回放所有操作路径。
-
-## 案例展示
-
-<ShowcaseHarmony />
-
-查看更多案例：[showcases](./showcases.mdx)
-
-## 在 HarmonyOS 上试用 Midscene Playground
-
-借助 Midscene.js Playground，你无需编写任何代码就能体验 HarmonyOS 自动化能力。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/harmony.mp4" controls/>
-
-查看 [开始使用](./harmony-getting-started#试用-playground零代码) 了解如何启动 Playground。
-
-## 下一步
-
-* [快速开始](./harmony-getting-started)
-* [使用 JavaScript SDK](./harmony-getting-started)
-* [使用 YAML 格式的自动化脚本](./automate-with-scripts-in-yaml) 与 [命令行工具](./automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/zh/harmony-getting-started.mdx b/apps/site/docs/zh/harmony.mdx
similarity index 55%
rename from apps/site/docs/zh/harmony-getting-started.mdx
rename to apps/site/docs/zh/harmony.mdx
index 27fa3ccd94..76f3dce9d8 100644
--- a/apps/site/docs/zh/harmony-getting-started.mdx
+++ b/apps/site/docs/zh/harmony.mdx
@@ -1,9 +1,18 @@
+import ShowcaseHarmony from './showcases-harmony.mdx';
 import StartExperience from './common/start-experience.mdx';
 import SetupEnv from './common/setup-env.mdx';
 
 import { PackageManagerTabs } from '@theme';
 
-# HarmonyOS 开始使用
+# HarmonyOS 自动化支持
+
+Midscene 可以驱动 HDC（HarmonyOS Device Connector）工具来实现 HarmonyOS NEXT 设备自动化。
+
+## 案例展示
+
+<ShowcaseHarmony />
+
+查看更多案例：[showcases](./showcases.mdx)
 
 本指南将带你完成使用 Midscene 自动化 HarmonyOS 设备所需的一切：通过 HDC 连接真机、配置模型 API Key、体验零代码 Playground，并运行你的首个 JavaScript 脚本。
 
@@ -143,7 +152,7 @@ npx tsx demo.ts
 
 ## 进阶
 
-当你需要自定义设备行为、把 Midscene 接入独立框架，或排查 HDC 问题时，可参考本节内容。更多构造函数参数可前往 [API 参考（HarmonyOS）](./harmony-api-reference)。
+当你需要自定义设备行为、把 Midscene 接入独立框架，或排查 HDC 问题时，可参考本节内容。更多构造函数参数可前往 [API 参考（HarmonyOS）](#api-reference)。
 
 ### 扩展 HarmonyOS 上的 Midscene
 
@@ -184,7 +193,7 @@ await agent.aiAct('click the red button five times');
 ## 更多
 
 - 查看所有 Agent 方法：[API 参考（通用）](./api#interaction-methods)
-- HarmonyOS 专属参数与接口：[HarmonyOS Agent API](./harmony-api-reference)
+- HarmonyOS 专属参数与接口：[HarmonyOS Agent API](#api-reference)
 - 示例项目
   - HarmonyOS JavaScript SDK 示例：[https://github.com/web-infra-dev/midscene-example/blob/main/harmony/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/harmony/javascript-sdk-demo)
   - HarmonyOS + Vitest 示例：[https://github.com/web-infra-dev/midscene-example/tree/main/harmony/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/harmony/vitest-demo)
@@ -320,3 +329,217 @@ const device = new HarmonyDevice('0123456789ABCDEF', {
   hdcPath: '/path/to/hdc',
 });
 ```
+
+## API 参考 {#api-reference}
+
+当你需要自定义设备行为、把 Midscene 接入框架，或排查 HDC 问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等）的参数说明，请参考平台无关的 [API 参考](./api)。
+
+### Action Space（动作空间）
+
+`HarmonyDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
+
+- `Tap` —— 点击元素。
+- `DoubleClick` —— 双击元素。
+- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式。
+- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
+- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
+- `KeyboardPress` —— 按下指定键位。
+- `LongPress` —— 长按目标元素，可选自定义时长。
+- `ClearInput` —— 清空输入框内容。
+- ~~`Pinch`~~ —— 不支持。HarmonyOS `uitest` 框架未提供多触点输入 API。
+- `Launch` —— 打开 HarmonyOS 应用（bundle name）。
+- `Terminate` —— 按 bundle name 强制停止应用。
+- `RunHdcShell` —— 执行原始 `hdc shell` 命令。
+- `HarmonyBackButton` —— 触发系统返回。
+- `HarmonyHomeButton` —— 回到桌面。
+- `HarmonyRecentAppsButton` —— 打开多任务/最近应用。
+
+### HarmonyDevice {#harmonydevice}
+
+创建一个可供 HarmonyAgent 驱动的 HDC 设备实例。
+
+#### 导入
+
+```ts
+import { HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
+```
+
+#### 构造函数
+
+```ts
+const device = new HarmonyDevice(deviceId, {
+  // 设备参数...
+});
+```
+
+#### 设备选项
+
+- `deviceId: string` —— 来自 `hdc list targets` 或 `getConnectedDevices()` 的值。
+- `hdcPath?: string` —— HDC 可执行文件的自定义路径。若未设置，将依次从 `HDC_HOME` 环境变量和常见安装路径中查找。
+- `autoDismissKeyboard?: boolean` —— 输入完成后自动隐藏键盘，默认 `true`。
+- `keyboardDismissStrategy?: 'esc-first' | 'back-first'` —— 自动隐藏键盘时优先使用的按键，默认 `'esc-first'`。HarmonyOS 只发送该策略的首选按键：`'esc-first'` 发送 ESC，`'back-first'` 发送 Back。
+- `screenshotResizeScale?: number` —— **已废弃。** 此选项已移除，不再生效。如需控制发送给 AI 模型的截图尺寸，请使用 `AgentOpt` 中的 `screenshotShrinkFactor`。
+- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
+
+#### 使用说明
+
+- 可以使用 `getConnectedDevices()` 发现设备，返回的 `deviceId` 与 `hdc list targets` 输出一致。
+- 如果 HDC 不在系统 PATH 中，可通过 `HDC_HOME` 环境变量或 `hdcPath` 选项指定路径。
+
+#### 示例
+
+##### 快速开始
+
+```ts
+import { HarmonyAgent, HarmonyDevice, getConnectedDevices } from '@midscene/harmony';
+
+const [first] = await getConnectedDevices();
+const device = new HarmonyDevice(first.deviceId, {});
+await device.connect();
+
+const agent = new HarmonyAgent(device, {
+  aiActionContext: '这是一台鸿蒙设备，如果出现弹窗，点击同意。',
+});
+
+await agent.launch('com.huawei.hmos.settings');
+await agent.aiAct('scroll down one screen');
+const items = await agent.aiQuery(
+  'string[], list all visible setting item names',
+);
+console.log(items);
+```
+
+##### 启动应用
+
+```ts
+await agent.launch('com.huawei.hmos.settings'); // 打开系统设置
+await agent.launch('com.huawei.hmos.camera');    // 打开相机
+await agent.back();
+await agent.home();
+```
+
+### HarmonyAgent {#harmonyagent}
+
+将 Midscene 的 AI 规划能力绑定到 HarmonyDevice，实现 UI 自动化。
+
+#### 导入
+
+```ts
+import { HarmonyAgent } from '@midscene/harmony';
+```
+
+#### 构造函数
+
+```ts
+const agent = new HarmonyAgent(device, {
+  // 通用 Agent 参数...
+});
+```
+
+#### HarmonyOS 特有选项
+
+- `customActions?: DeviceAction[]` —— 通过 `defineAction` 扩展规划器的可用动作。
+- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到 bundle name。当你在 `launch(target)` 里传入应用名称时，Agent 会在此映射中查找对应的 bundle name；若未找到映射，则按原样尝试启动 `target`。
+- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
+
+#### 使用说明
+
+:::info
+
+- 一个设备连接对应一个 Agent。
+- `launch`、`terminate`、`runHdcShell` 等 HarmonyOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [HarmonyOS 平台特定动作](./automate-with-scripts-in-yaml#harmony-部分)。
+- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
+
+:::
+
+#### HarmonyOS 特有方法
+
+##### `agent.launch()`
+
+启动 HarmonyOS 应用。
+
+```ts
+function launch(uri: string): Promise<void>;
+```
+
+- `uri: string` —— 可以是应用 bundle name（如 `com.huawei.hmos.settings`），也可以是在 `appNameMapping` 中注册的应用名称。如果传入 `http://` 或 `https://` 开头的 URL，将通过浏览器打开。
+
+```ts
+await agent.launch('com.huawei.hmos.settings'); // 打开系统设置
+await agent.launch('com.huawei.hmos.camera');    // 打开相机
+```
+
+##### `agent.runHdcShell()`
+
+通过连接的设备运行原始的 `hdc shell` 命令。
+
+```ts
+function runHdcShell(command: string): Promise<string>;
+```
+
+- `command: string` —— 原样传递给 `hdc shell` 的命令。
+
+```ts
+const result = await agent.runHdcShell('hidumper -s RenderService -a screen');
+console.log(result);
+```
+
+##### `agent.terminate()`
+
+终止（强制停止）正在运行的 HarmonyOS 应用。
+
+```ts
+function terminate(uri: string): Promise<void>;
+```
+
+- `uri: string` —— 应用 bundle name、`appNameMapping` 中的应用名称，或 `bundle/Ability`（仅使用 bundle name 部分）。
+
+```ts
+await agent.terminate('com.huawei.hmos.settings');
+```
+
+##### 导航辅助
+
+- `agent.back(): Promise<void>` —— 触发 HarmonyOS 系统的返回操作。
+- `agent.home(): Promise<void>` —— 返回桌面。
+- `agent.recentApps(): Promise<void>` —— 打开多任务/最近应用界面。
+
+#### 辅助工具
+
+##### `agentFromHdcDevice()`
+
+从任意已连接的 HDC 设备创建 `HarmonyAgent`。
+
+```ts
+function agentFromHdcDevice(
+  deviceId?: string,
+  opts?: HarmonyAgentOpt & HarmonyDeviceOpt,
+): Promise<HarmonyAgent>;
+```
+
+- `deviceId?: string` —— 连接特定设备；留空表示使用"第一个可用设备"。
+- `opts?: HarmonyAgentOpt & HarmonyDeviceOpt` —— 在一个对象中合并 Agent 选项与 [`HarmonyDevice`](#harmonydevice) 的设置。
+
+```ts
+import { agentFromHdcDevice } from '@midscene/harmony';
+
+const agent = await agentFromHdcDevice('0123456789ABCDEF'); // 传入 deviceId
+const agent = await agentFromHdcDevice(); // 使用第一个连接的设备
+```
+
+##### `getConnectedDevices()`
+
+列举 Midscene 可驱动的 HDC 设备。
+
+```ts
+function getConnectedDevices(
+  hdcPath?: string,
+): Promise<Array<{ deviceId: string }>>;
+```
+
+```ts
+import { getConnectedDevices } from '@midscene/harmony';
+
+const devices = await getConnectedDevices();
+console.log(devices); // [{ deviceId: '0123456789ABCDEF' }]
+```
diff --git a/apps/site/docs/zh/integrate-with-any-interface.mdx b/apps/site/docs/zh/integrate-with-any-interface.mdx
index a30546a6e8..1d052dd99c 100644
--- a/apps/site/docs/zh/integrate-with-any-interface.mdx
+++ b/apps/site/docs/zh/integrate-with-any-interface.mdx
@@ -349,7 +349,7 @@ import {
 
 #### 定义一个自定义动作
 
-你可以使用 `defineAction()` 函数定义自己的动作。你也可以使用这种方式为 [PuppeteerAgent](./integrate-with-puppeteer)、[AgentOverChromeBridge](./bridge-mode#constructor) 和 [AndroidAgent](./android-getting-started) 定义更多动作。
+你可以使用 `defineAction()` 函数定义自己的动作。你也可以使用这种方式为 [PuppeteerAgent](./integrate-with-puppeteer)、[AgentOverChromeBridge](./bridge-mode#constructor) 和 [AndroidAgent](./android) 定义更多动作。
 
 API 签名：
 
diff --git a/apps/site/docs/zh/ios-api-reference.mdx b/apps/site/docs/zh/ios-api-reference.mdx
deleted file mode 100644
index 042c8edf1a..0000000000
--- a/apps/site/docs/zh/ios-api-reference.mdx
+++ /dev/null
@@ -1,245 +0,0 @@
-# API 参考（iOS）
-
-当你需要自定义 iOS 设备行为、将 Midscene 接入依赖 WebDriverAgent 的工作流，或排查 WDA 请求问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等），请参考平台无关的 [API 参考](./api)。
-
-## Action Space（动作空间）
-
-`IOSDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
-
-- `Tap` —— 点击元素。
-- `DoubleClick` —— 双击元素。
-- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式（`append` 是 `typeOnly` 的已废弃别名）。支持可选参数 `autoDismissKeyboard`。
-- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
-- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
-- `KeyboardPress` —— 按下指定键位。
-- `LongPress` —— 长按目标元素，可选自定义时长。
-- `Pinch` —— 双指缩放手势。`scale > 1` 放大，`scale < 1` 缩小。
-- `ClearInput` —— 清空输入框内容。
-- `Launch` —— 打开网页、Bundle ID 或 URL Scheme。
-- `Terminate` —— 通过 Bundle ID 关闭正在运行的 iOS 应用。
-- `RunWdaRequest` —— 直接调用 WebDriverAgent REST 接口。
-- `IOSHomeButton` —— 执行 iOS 系统 Home 操作。
-- `IOSAppSwitcher` —— 打开 iOS 多任务视图。
-
-## IOSDevice {#iosdevice}
-
-创建一个由 WebDriverAgent 支撑、供 IOSAgent 驱动的设备连接。
-
-### 导入
-
-```ts
-import { IOSDevice } from '@midscene/ios';
-```
-
-### 构造函数
-
-```ts
-const device = new IOSDevice({
-  // 设备参数...
-});
-```
-
-### 设备选项
-
-- `wdaPort?: number` —— WebDriverAgent 端口，默认 `8100`。
-- `wdaHost?: string` —— WebDriverAgent host，默认 `'localhost'`。
-- `iOSDeviceClassOverride?: string` —— 使用 `agentFromWebDriverAgent()` 或 iOS Playground 时替换默认 `IOSDevice` 的 npm module path。目标模块必须导出 `IOSDevice` class 或 default class。
-- `autoDismissKeyboard?: boolean` —— 文本输入后自动隐藏键盘，默认 `true`。
-- `customActions?: DeviceAction<any>[]` —— 向 Agent 暴露的额外设备动作。
-
-
-### 使用说明
-
-- 请确认已开启开发者模式且 WDA 能访问设备；真机转发端口时可借助 `iproxy`。
-- 通过 `wdaHost`/`wdaPort` 可指向远程设备或自建的 WDA。
-- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
-
-### 示例
-
-#### 快速开始
-
-```ts
-import { IOSAgent, IOSDevice } from '@midscene/ios';
-
-const device = new IOSDevice({ wdaHost: 'localhost', wdaPort: 8100 });
-await device.connect();
-
-const agent = new IOSAgent(device, {
-  aiActionContext: 'If any permission dialog appears, accept it.',
-});
-
-await agent.launch('https://ebay.com');
-await agent.aiAct('Search for \"Headphones\"');
-const items = await agent.aiQuery(
-  '{itemTitle: string, price: Number}[], list headphone products',
-);
-console.log(items);
-```
-
-#### 自定义 Host 与端口
-
-```ts
-const device = new IOSDevice({
-  wdaHost: '192.168.1.100',
-  wdaPort: 8300,
-});
-await device.connect();
-```
-
-## IOSAgent {#iosagent}
-
-将 Midscene 的 AI 规划能力绑定到 IOSDevice，通过 WebDriverAgent 实现 UI 自动化。
-
-### 导入
-
-```ts
-import { IOSAgent } from '@midscene/ios';
-```
-
-### 构造函数
-
-```ts
-const agent = new IOSAgent(device, {
-  // 通用 Agent 参数...
-});
-```
-
-### iOS 特有选项
-
-- `customActions?: DeviceAction<any>[]` —— 通过 `defineAction` 扩展规划器的可用动作。
-- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到 Bundle Identifier。当你在 `launch(target)` 或 `terminate(bundleId)` 里传入应用名称时，Agent 会在此映射中查找对应的 Bundle ID；若未找到映射，则按原样使用 `target`。用户提供的 appNameMapping 优先级高于默认映射。
-- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
-
-### 使用说明
-
-:::info
-
-- 一个设备连接对应一个 Agent。
-- `launch`、`terminate`、`runWdaRequest` 等 iOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [iOS 平台特定动作](./automate-with-scripts-in-yaml#the-ios-part)。
-- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
-
-:::
-
-### iOS 特有方法
-
-#### `agent.launch()`
-
-打开网页、原生应用或自定义 Scheme。
-
-```ts
-function launch(target: string): Promise<void>;
-```
-
-- `target: string` —— 目标地址（网页 URL、Bundle Identifier、URL scheme、tel/mailto 等）或应用名称。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应 Bundle ID；若未找到映射，则直接按 `target` 启动。
-
-```ts
-await agent.launch('https://www.apple.com');
-await agent.launch('com.apple.Preferences');
-await agent.launch('myapp://profile/user/123');
-await agent.launch('tel:+1234567890');
-```
-
-#### `agent.terminate()`
-
-通过 Bundle ID 终止（关闭）正在运行的 iOS 应用。
-
-```ts
-function terminate(bundleId: string): Promise<void>;
-```
-
-- `bundleId: string` —— 要终止的应用的 Bundle Identifier（如 `com.apple.Preferences`）。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应 Bundle ID。
-
-```ts
-await agent.terminate('com.apple.Preferences');
-await agent.terminate('com.apple.mobilesafari');
-```
-
-#### `agent.runWdaRequest()`
-
-当你需要更底层的控制能力时，执行原始的 WebDriverAgent REST 请求。
-
-```ts
-function runWdaRequest(
-  method: string,
-  endpoint: string,
-  data?: Record<string, any>,
-): Promise<any>;
-```
-
-- `method: string` —— HTTP 动词（`GET`、`POST`、`DELETE` 等）。
-- `endpoint: string` —— WebDriverAgent 接口路径。
-- `data?: Record<string, any>` —— 可选的 JSON 请求体。
-
-```ts
-const screen = await agent.runWdaRequest('GET', '/wda/screen');
-await agent.runWdaRequest('POST', '/session/test/wda/pressButton', { name: 'home' });
-```
-
-#### 应用间导航
-
-- `agent.home(): Promise<void>` —— 回到主屏。
-- `agent.appSwitcher(): Promise<void>` —— 打开多任务视图。
-
-### 辅助工具
-
-#### `agentFromWebDriverAgent()` {#agentfromwebdriveragent}
-
-连接 WebDriverAgent 并返回可用的 IOSAgent。
-
-```ts
-function agentFromWebDriverAgent(
-  opts?: PageAgentOpt & IOSDeviceOpt,
-): Promise<IOSAgent>;
-```
-
-- `opts?: PageAgentOpt & IOSDeviceOpt` —— 在一个对象中同时传入通用 Agent 选项与 [`IOSDevice`](#iosdevice) 的配置。
-- 设置 `MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE` 可通过环境变量应用同一个设备 class override。显式传入的选项优先级高于环境变量。
-
-```ts
-import { agentFromWebDriverAgent } from '@midscene/ios';
-
-const agent = await agentFromWebDriverAgent({
-  wdaHost: 'localhost',
-  wdaPort: 8100,
-  iOSDeviceClassOverride: '@your-scope/ios-device',
-  aiActionContext: 'Accept permission dialogs automatically.',
-});
-```
-
-### 扩展自定义交互动作
-
-通过 `defineAction` 创建处理器并传入 `customActions`，即可扩展 Agent 的动作空间。这些动作会追加在内置动作之后，可在规划阶段被调用。
-
-```ts
-import { getMidsceneLocationSchema, z } from '@midscene/core';
-import { defineAction } from '@midscene/core/device';
-import { agentFromWebDriverAgent } from '@midscene/ios';
-
-const ContinuousClick = defineAction({
-  name: 'continuousClick',
-  description: 'Click the same target repeatedly',
-  paramSchema: z.object({
-    locate: getMidsceneLocationSchema(),
-    count: z
-      .number()
-      .int()
-      .positive()
-      .describe('How many times to click'),
-  }),
-  async call({ locate, count }) {
-    console.log('click target center', locate.center);
-    console.log('click count', count);
-  },
-});
-
-const agent = await agentFromWebDriverAgent({
-  customActions: [ContinuousClick],
-});
-
-await agent.aiAct('Click the red button five times');
-```
-
-### 相关阅读
-
-- [iOS 快速开始](./ios-getting-started) 获取搭建与脚本示例。
-- [与任意界面集成](./integrate-with-any-interface) 查看自定义动作与 Schema 细节。
diff --git a/apps/site/docs/zh/ios-getting-started.mdx b/apps/site/docs/zh/ios-getting-started.mdx
deleted file mode 100644
index bd446d26dc..0000000000
--- a/apps/site/docs/zh/ios-getting-started.mdx
+++ /dev/null
@@ -1,196 +0,0 @@
-import StartExperience from './common/start-experience.mdx';
-import SetupEnv from './common/setup-env.mdx';
-import PrepareIOS from './common/prepare-ios.mdx';
-
-import { PackageManagerTabs } from '@theme';
-
-# iOS 开始使用
-
-本指南会带你完成使用 Midscene 控制 iOS 设备的全部步骤：通过 WebDriverAgent 连接真机、配置模型 API Key、体验零代码 Playground，并运行你的首个 JavaScript 脚本。
-
-:::info 示例项目
-
-使用 JavaScript 控制 iOS 设备：[https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
-
-集成 Vitest 进行测试：[https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
-
-:::
-
-<SetupEnv />
-
-## 准备工作
-
-继续之前，请确保 WebDriverAgent 可以与设备通信。
-
-<PrepareIOS />
-
-## 试用 Playground（零代码）
-
-Playground 是验证连接、观察 AI 驱动步骤的最快方式，无需编写代码。它与 `@midscene/ios` 共享相同的核心，因此在 Playground 中通过的流程，在脚本中运行会保持一致。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
-
-1. 启动 Playground CLI：
-
-```bash
-npx --yes @midscene/ios-playground
-```
-
-2. 点击窗口中的齿轮按钮进入配置页，粘贴你的 API Key 配置。如果还没有 API Key，请回到 [模型配置](./model-config) 获取。
-
-![](/ios-set-env.png)
-
-## 开始体验
-
-<StartExperience />
-
-## 集成 Midscene Agent
-
-当 Playground 工作正常后，就可以切换到可复用的 JavaScript 脚本。
-
-### 第 1 步：安装依赖
-
-<PackageManagerTabs command="install @midscene/ios dotenv --save-dev" />
-
-### 第 2 步：编写脚本
-
-下面的示例会在设备上打开 Safari，搜索 eBay，并断言结果列表。
-
-```typescript title="./demo.ts"
-import 'dotenv/config'; // 通过 dotenv/config 自动加载 .env 文件中的环境变量
-import {
-  IOSAgent,
-  IOSDevice,
-  agentFromWebDriverAgent,
-} from '@midscene/ios';
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-Promise.resolve(
-  (async () => {
-    // 方式一：直接创建设备和 Agent
-    const page = new IOSDevice({
-      wdaPort: 8100,
-      wdaHost: 'localhost',
-    });
-
-    // 👀 初始化 Midscene Agent
-    const agent = new IOSAgent(page, {
-      aiActionContext:
-        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
-    });
-    await page.connect();
-
-    // 方式二：使用便捷函数（推荐）
-    // const agent = await agentFromWebDriverAgent({
-    //   wdaPort: 8100,
-    //   wdaHost: 'localhost',
-    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
-    // });
-
-    // 👀 直接打开 ebay.com（推荐做法）
-    await page.launch('https://ebay.com');
-    await sleep(3000);
-
-    // 👀 输入关键字并执行搜索
-    await agent.aiAct('Search for "Headphones"');
-
-    // 👀 等待加载完成
-    await agent.aiWaitFor('At least one headphone product is displayed on the page');
-    // 或简单地等待几秒：
-    // await sleep(5000);
-
-    // 👀 理解页面内容并提取数据
-    const items = await agent.aiQuery(
-      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
-    );
-    console.log('Headphone product information', items);
-
-    // 👀 使用 AI 断言
-    await agent.aiAssert('Multiple headphone products are displayed on the interface');
-
-    await page.destroy();
-  })(),
-);
-```
-
-### 第 3 步：运行示例
-
-```bash
-npx tsx demo.ts
-```
-
-### 第 4 步：查看报告
-
-脚本成功后会输出 `Midscene - report file updated: /path/to/report/some_id.html`。在浏览器中打开对应 HTML 文件即可回放每一步交互、查询与断言。
-
-## API 参考与更多资源
-
-需要查看构造函数、辅助方法或平台专属设备 API？请移步 [iOS API 参考](./ios-api-reference) 获取详细参数及自定义操作等高级主题。若想了解跨平台共用的 API，可阅读 [通用 API 参考](./api)。
-
-## 常见问题
-
-### 为什么 WebDriverAgent 已连接，但仍无法控制设备？
-
-请检查以下事项：
-
-1. **开发者模式**：在“设置 > 隐私与安全性 > 开发者模式”中确认已开启。
-2. **UI Automation**：在“设置 > 开发者 > UI Automation”中确认已开启。
-3. **设备信任**：确保设备信任当前 Mac。
-
-### 模拟器与真机有哪些区别？
-
-| 特性 | 真机 | 模拟器 |
-|------|------|--------|
-| 端口转发 | 需要 iproxy | 不需要 |
-| 开发者模式 | 必须手动开启 | 默认开启 |
-| UI Automation 设置 | 需手动开启 | 默认开启 |
-| 性能 | 真实设备性能 | 取决于 Mac 性能 |
-| 传感器 | 真实硬件 | 模拟数据 |
-
-### 如何自定义 WebDriverAgent 的端口和 Host？
-
-可以通过 `IOSDevice` 构造函数或 `agentFromWebDriverAgent` 来指定端口和 Host：
-
-```typescript
-// 方式一：使用 IOSDevice
-const device = new IOSDevice({
-  wdaPort: 8100,        // 自定义端口
-  wdaHost: '192.168.1.100', // 自定义主机
-});
-
-// 方式二：使用便捷函数（推荐）
-const agent = await agentFromWebDriverAgent({
-  wdaPort: 8100,        // 自定义端口
-  wdaHost: '192.168.1.100', // 自定义主机
-});
-```
-
-针对远程设备，还需要按需设置端口转发：
-
-```bash
-iproxy 8100 8100 YOUR_DEVICE_ID
-```
-
-### 如何在 Playground 中获得更流畅的实时画面？
-
-Playground 的画面预览支持两种模式：
-
-- **轮询模式**（默认）：逐帧调用 WDA 截图 API，帧率约 5-10fps。
-- **原生 MJPEG 流**（推荐）：直接代理 WDA 内置的 MJPEG Server，帧率更高、延迟更低。
-
-要启用原生 MJPEG 流，需要将 WDA MJPEG Server 的端口（默认 9100）转发到本机：
-
-```bash
-# 真机需要端口转发（模拟器不需要）
-iproxy 9100 9100 YOUR_DEVICE_ID
-```
-
-Playground 启动时会自动探测 9100 端口。如果可用，日志会显示 `MJPEG: streaming via native WDA MJPEG server`；否则自动回退到轮询模式。
-
-## 更多
-
-- 查看所有 Agent 方法：[API 参考（通用）](./api#interaction-methods)
-- iOS 专属参数与接口：[iOS Agent API](./ios-api-reference)
-- 示例项目
-  - iOS JavaScript SDK 示例：[https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
-  - iOS + Vitest 示例：[https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
diff --git a/apps/site/docs/zh/ios-introduction.mdx b/apps/site/docs/zh/ios-introduction.mdx
deleted file mode 100644
index 26169537c9..0000000000
--- a/apps/site/docs/zh/ios-introduction.mdx
+++ /dev/null
@@ -1,54 +0,0 @@
-import ShowcaseIOS from './showcases-ios.mdx';
-
-# iOS 自动化支持
-
-Midscene 可以驱动 WebDriver 工具来支持 iOS 自动化。
-
-由于适配了视觉模型方案，整个自动化过程可以适配任意的 App 技术栈，无论是 Native、Flutter 还是 React Native 构建的 App 或小程序都能使用。开发者只需面向最终效果调试 UI 自动化脚本即可。
-
-iOS UI 自动化方案具备 Midscene 的全部特性：
-
-- 支持使用 Playground 进行零代码试用。
-- 支持 JavaScript SDK。
-- 支持使用 YAML 格式的自动化脚本与命令行工具。
-- 支持生成 HTML 报告回放所有操作路径。
-
-## 案例展示
-
-<ShowcaseIOS />
-
-查看更多案例：[showcases](./showcases.mdx)
-
-## 在 Playground 中试用
-
-借助 Playground，你无需编写任何代码即可体验 Midscene 的能力。
-
-<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
-
-查看 [开始使用](./ios-getting-started#试用-playground零代码) 了解如何启动 Playground。
-
-## 关于 WebDriverAgent
-
-WebDriver 是 W3C 制定的浏览器自动化标准协议，提供统一的 API 来控制不同的浏览器和应用。该协议定义了客户端与服务端之间的通信方式，使自动化工具能跨平台地操纵各种界面。
-
-得益于 Appium 团队以及其他开源社区的努力，业界已经出现了多个优秀的库，将桌面端和移动端的操作转化为 WebDriver 协议，例如：
-
-- **Appium** —— 跨平台移动自动化框架
-- **WebDriverAgent** —— 专注于 iOS 设备自动化的服务
-- **Selenium** —— Web 浏览器自动化工具
-- **WinAppDriver** —— Windows 应用自动化工具
-
-**Midscene 适配 WebDriver 协议**，这意味着开发者可以在任何支持 WebDriver 的设备上使用 AI 模型执行智能自动化操作。通过该设计，Midscene 不仅能完成点击、输入等传统操作，还可以：
-
-- 理解界面内容与上下文
-- 执行复杂的多步骤操作
-- 进行智能断言与验证
-- 提取并分析界面数据
-
-在 iOS 平台上，Midscene 通过 WebDriverAgent 连接 iOS 设备，让你可以用自然语言描述来控制 iOS App 和系统。
-
-
-## 下一步
-
-* [使用 JavaScript SDK](./ios-getting-started)
-* [使用 YAML 格式的自动化脚本](./automate-with-scripts-in-yaml) 与 [命令行工具](./automate-with-scripts-in-yaml)
diff --git a/apps/site/docs/zh/ios.mdx b/apps/site/docs/zh/ios.mdx
new file mode 100644
index 0000000000..943f3acfff
--- /dev/null
+++ b/apps/site/docs/zh/ios.mdx
@@ -0,0 +1,470 @@
+import ShowcaseIOS from './showcases-ios.mdx';
+import StartExperience from './common/start-experience.mdx';
+import SetupEnv from './common/setup-env.mdx';
+import PrepareIOS from './common/prepare-ios.mdx';
+
+import { PackageManagerTabs } from '@theme';
+
+# iOS 自动化支持
+
+Midscene 可以驱动 WebDriver 工具来支持 iOS 自动化。
+
+## 案例展示
+
+<ShowcaseIOS />
+
+查看更多案例：[showcases](./showcases.mdx)
+
+## 关于 WebDriverAgent
+
+WebDriver 是 W3C 制定的浏览器自动化标准协议，提供统一的 API 来控制不同的浏览器和应用。该协议定义了客户端与服务端之间的通信方式，使自动化工具能跨平台地操纵各种界面。
+
+得益于 Appium 团队以及其他开源社区的努力，业界已经出现了多个优秀的库，将桌面端和移动端的操作转化为 WebDriver 协议，例如：
+
+- **Appium** —— 跨平台移动自动化框架
+- **WebDriverAgent** —— 专注于 iOS 设备自动化的服务
+- **Selenium** —— Web 浏览器自动化工具
+- **WinAppDriver** —— Windows 应用自动化工具
+
+**Midscene 适配 WebDriver 协议**，这意味着开发者可以在任何支持 WebDriver 的设备上使用 AI 模型执行智能自动化操作。通过该设计，Midscene 不仅能完成点击、输入等传统操作，还可以：
+
+- 理解界面内容与上下文
+- 执行复杂的多步骤操作
+- 进行智能断言与验证
+- 提取并分析界面数据
+
+在 iOS 平台上，Midscene 通过 WebDriverAgent 连接 iOS 设备，让你可以用自然语言描述来控制 iOS App 和系统。
+
+本指南会带你完成使用 Midscene 控制 iOS 设备的全部步骤：通过 WebDriverAgent 连接真机、配置模型 API Key、体验零代码 Playground，并运行你的首个 JavaScript 脚本。
+
+:::info 示例项目
+
+使用 JavaScript 控制 iOS 设备：[https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
+
+集成 Vitest 进行测试：[https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
+
+:::
+
+<SetupEnv />
+
+## 准备工作
+
+继续之前，请确保 WebDriverAgent 可以与设备通信。
+
+<PrepareIOS />
+
+## 试用 Playground（零代码）
+
+Playground 是验证连接、观察 AI 驱动步骤的最快方式，无需编写代码。它与 `@midscene/ios` 共享相同的核心，因此在 Playground 中通过的流程，在脚本中运行会保持一致。
+
+<video src="https://lf3-static.bytednsdoc.com/obj/eden-cn/nupipfups/Midscene/1.0-showcases/x2.mp4" controls/>
+
+1. 启动 Playground CLI：
+
+```bash
+npx --yes @midscene/ios-playground
+```
+
+2. 点击窗口中的齿轮按钮进入配置页，粘贴你的 API Key 配置。如果还没有 API Key，请回到 [模型配置](./model-config) 获取。
+
+![](/ios-set-env.png)
+
+## 开始体验
+
+<StartExperience />
+
+## 集成 Midscene Agent
+
+当 Playground 工作正常后，就可以切换到可复用的 JavaScript 脚本。
+
+### 第 1 步：安装依赖
+
+<PackageManagerTabs command="install @midscene/ios dotenv --save-dev" />
+
+### 第 2 步：编写脚本
+
+下面的示例会在设备上打开 Safari，搜索 eBay，并断言结果列表。
+
+```typescript title="./demo.ts"
+import 'dotenv/config'; // 通过 dotenv/config 自动加载 .env 文件中的环境变量
+import {
+  IOSAgent,
+  IOSDevice,
+  agentFromWebDriverAgent,
+} from '@midscene/ios';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+Promise.resolve(
+  (async () => {
+    // 方式一：直接创建设备和 Agent
+    const page = new IOSDevice({
+      wdaPort: 8100,
+      wdaHost: 'localhost',
+    });
+
+    // 👀 初始化 Midscene Agent
+    const agent = new IOSAgent(page, {
+      aiActionContext:
+        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
+    });
+    await page.connect();
+
+    // 方式二：使用便捷函数（推荐）
+    // const agent = await agentFromWebDriverAgent({
+    //   wdaPort: 8100,
+    //   wdaHost: 'localhost',
+    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
+    // });
+
+    // 👀 直接打开 ebay.com（推荐做法）
+    await page.launch('https://ebay.com');
+    await sleep(3000);
+
+    // 👀 输入关键字并执行搜索
+    await agent.aiAct('Search for "Headphones"');
+
+    // 👀 等待加载完成
+    await agent.aiWaitFor('At least one headphone product is displayed on the page');
+    // 或简单地等待几秒：
+    // await sleep(5000);
+
+    // 👀 理解页面内容并提取数据
+    const items = await agent.aiQuery(
+      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
+    );
+    console.log('Headphone product information', items);
+
+    // 👀 使用 AI 断言
+    await agent.aiAssert('Multiple headphone products are displayed on the interface');
+
+    await page.destroy();
+  })(),
+);
+```
+
+### 第 3 步：运行示例
+
+```bash
+npx tsx demo.ts
+```
+
+### 第 4 步：查看报告
+
+脚本成功后会输出 `Midscene - report file updated: /path/to/report/some_id.html`。在浏览器中打开对应 HTML 文件即可回放每一步交互、查询与断言。
+
+## API 参考与更多资源
+
+需要查看构造函数、辅助方法或平台专属设备 API？请移步下方的 [iOS API 参考](#api-reference) 获取详细参数及自定义操作等高级主题。若想了解跨平台共用的 API，可阅读 [通用 API 参考](./api)。
+
+## 常见问题
+
+### 为什么 WebDriverAgent 已连接，但仍无法控制设备？
+
+请检查以下事项：
+
+1. **开发者模式**：在“设置 > 隐私与安全性 > 开发者模式”中确认已开启。
+2. **UI Automation**：在“设置 > 开发者 > UI Automation”中确认已开启。
+3. **设备信任**：确保设备信任当前 Mac。
+
+### 模拟器与真机有哪些区别？
+
+| 特性 | 真机 | 模拟器 |
+|------|------|--------|
+| 端口转发 | 需要 iproxy | 不需要 |
+| 开发者模式 | 必须手动开启 | 默认开启 |
+| UI Automation 设置 | 需手动开启 | 默认开启 |
+| 性能 | 真实设备性能 | 取决于 Mac 性能 |
+| 传感器 | 真实硬件 | 模拟数据 |
+
+### 如何自定义 WebDriverAgent 的端口和 Host？
+
+可以通过 `IOSDevice` 构造函数或 `agentFromWebDriverAgent` 来指定端口和 Host：
+
+```typescript
+// 方式一：使用 IOSDevice
+const device = new IOSDevice({
+  wdaPort: 8100,        // 自定义端口
+  wdaHost: '192.168.1.100', // 自定义主机
+});
+
+// 方式二：使用便捷函数（推荐）
+const agent = await agentFromWebDriverAgent({
+  wdaPort: 8100,        // 自定义端口
+  wdaHost: '192.168.1.100', // 自定义主机
+});
+```
+
+针对远程设备，还需要按需设置端口转发：
+
+```bash
+iproxy 8100 8100 YOUR_DEVICE_ID
+```
+
+### 如何在 Playground 中获得更流畅的实时画面？
+
+Playground 的画面预览支持两种模式：
+
+- **轮询模式**（默认）：逐帧调用 WDA 截图 API，帧率约 5-10fps。
+- **原生 MJPEG 流**（推荐）：直接代理 WDA 内置的 MJPEG Server，帧率更高、延迟更低。
+
+要启用原生 MJPEG 流，需要将 WDA MJPEG Server 的端口（默认 9100）转发到本机：
+
+```bash
+# 真机需要端口转发（模拟器不需要）
+iproxy 9100 9100 YOUR_DEVICE_ID
+```
+
+Playground 启动时会自动探测 9100 端口。如果可用，日志会显示 `MJPEG: streaming via native WDA MJPEG server`；否则自动回退到轮询模式。
+
+## 更多
+
+- 查看所有 Agent 方法：[API 参考（通用）](./api#interaction-methods)
+- iOS 专属参数与接口：[iOS Agent API](#api-reference)
+- 示例项目
+  - iOS JavaScript SDK 示例：[https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo](https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo)
+  - iOS + Vitest 示例：[https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo](https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo)
+
+## API 参考 {#api-reference}
+
+当你需要自定义 iOS 设备行为、将 Midscene 接入依赖 WebDriverAgent 的工作流，或排查 WDA 请求问题时，请查阅本节。关于通用构造函数（报告、Hook、缓存等），请参考平台无关的 [API 参考](./api)。
+
+### Action Space（动作空间）
+
+`IOSDevice` 使用以下动作空间，Midscene Agent 在规划任务时可以使用这些操作：
+
+- `Tap` —— 点击元素。
+- `DoubleClick` —— 双击元素。
+- `Input` —— 输入文本，支持 `replace`/`typeOnly`/`clear` 模式（`append` 是 `typeOnly` 的已废弃别名）。支持可选参数 `autoDismissKeyboard`。
+- `Scroll` —— 以元素为起点或从屏幕中央向上/下/左/右滚动，支持滚动到顶/底/左/右。
+- `DragAndDrop` —— 从一个元素拖拽到另一个元素。
+- `KeyboardPress` —— 按下指定键位。
+- `LongPress` —— 长按目标元素，可选自定义时长。
+- `Pinch` —— 双指缩放手势。`scale > 1` 放大，`scale < 1` 缩小。
+- `ClearInput` —— 清空输入框内容。
+- `Launch` —— 打开网页、Bundle ID 或 URL Scheme。
+- `Terminate` —— 通过 Bundle ID 关闭正在运行的 iOS 应用。
+- `RunWdaRequest` —— 直接调用 WebDriverAgent REST 接口。
+- `IOSHomeButton` —— 执行 iOS 系统 Home 操作。
+- `IOSAppSwitcher` —— 打开 iOS 多任务视图。
+
+### IOSDevice {#iosdevice}
+
+创建一个由 WebDriverAgent 支撑、供 IOSAgent 驱动的设备连接。
+
+#### 导入
+
+```ts
+import { IOSDevice } from '@midscene/ios';
+```
+
+#### 构造函数
+
+```ts
+const device = new IOSDevice({
+  // 设备参数...
+});
+```
+
+#### 设备选项
+
+- `wdaPort?: number` —— WebDriverAgent 端口，默认 `8100`。
+- `wdaHost?: string` —— WebDriverAgent host，默认 `'localhost'`。
+- `iOSDeviceClassOverride?: string` —— 使用 `agentFromWebDriverAgent()` 或 iOS Playground 时替换默认 `IOSDevice` 的 npm module path。目标模块必须导出 `IOSDevice` class 或 default class。
+- `autoDismissKeyboard?: boolean` —— 文本输入后自动隐藏键盘，默认 `true`。
+- `customActions?: DeviceAction<any>[]` —— 向 Agent 暴露的额外设备动作。
+
+
+#### 使用说明
+
+- 请确认已开启开发者模式且 WDA 能访问设备；真机转发端口时可借助 `iproxy`。
+- 通过 `wdaHost`/`wdaPort` 可指向远程设备或自建的 WDA。
+- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
+
+#### 示例
+
+##### 快速开始
+
+```ts
+import { IOSAgent, IOSDevice } from '@midscene/ios';
+
+const device = new IOSDevice({ wdaHost: 'localhost', wdaPort: 8100 });
+await device.connect();
+
+const agent = new IOSAgent(device, {
+  aiActionContext: 'If any permission dialog appears, accept it.',
+});
+
+await agent.launch('https://ebay.com');
+await agent.aiAct('Search for \"Headphones\"');
+const items = await agent.aiQuery(
+  '{itemTitle: string, price: Number}[], list headphone products',
+);
+console.log(items);
+```
+
+##### 自定义 Host 与端口
+
+```ts
+const device = new IOSDevice({
+  wdaHost: '192.168.1.100',
+  wdaPort: 8300,
+});
+await device.connect();
+```
+
+### IOSAgent {#iosagent}
+
+将 Midscene 的 AI 规划能力绑定到 IOSDevice，通过 WebDriverAgent 实现 UI 自动化。
+
+#### 导入
+
+```ts
+import { IOSAgent } from '@midscene/ios';
+```
+
+#### 构造函数
+
+```ts
+const agent = new IOSAgent(device, {
+  // 通用 Agent 参数...
+});
+```
+
+#### iOS 特有选项
+
+- `customActions?: DeviceAction<any>[]` —— 通过 `defineAction` 扩展规划器的可用动作。
+- `appNameMapping?: Record<string, string>` —— 将友好的应用名称映射到 Bundle Identifier。当你在 `launch(target)` 或 `terminate(bundleId)` 里传入应用名称时，Agent 会在此映射中查找对应的 Bundle ID；若未找到映射，则按原样使用 `target`。用户提供的 appNameMapping 优先级高于默认映射。
+- 其余字段与 [API constructors](./api#common-parameters) 一致：`generateReport`、`reportFileName`、`aiActionContext`、`modelConfig`、`cacheId`、`createOpenAIClient`、`onTaskStartTip` 等。
+
+#### 使用说明
+
+:::info
+
+- 一个设备连接对应一个 Agent。
+- `launch`、`terminate`、`runWdaRequest` 等 iOS 专属辅助函数也可在 YAML 脚本中使用，语法见 [iOS 平台特定动作](./automate-with-scripts-in-yaml#the-ios-part)。
+- 通用交互方法请查阅 [API 参考（通用）](./api#interaction-methods)。
+
+:::
+
+#### iOS 特有方法
+
+##### `agent.launch()`
+
+打开网页、原生应用或自定义 Scheme。
+
+```ts
+function launch(target: string): Promise<void>;
+```
+
+- `target: string` —— 目标地址（网页 URL、Bundle Identifier、URL scheme、tel/mailto 等）或应用名称。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应 Bundle ID；若未找到映射，则直接按 `target` 启动。
+
+```ts
+await agent.launch('https://www.apple.com');
+await agent.launch('com.apple.Preferences');
+await agent.launch('myapp://profile/user/123');
+await agent.launch('tel:+1234567890');
+```
+
+##### `agent.terminate()`
+
+通过 Bundle ID 终止（关闭）正在运行的 iOS 应用。
+
+```ts
+function terminate(bundleId: string): Promise<void>;
+```
+
+- `bundleId: string` —— 要终止的应用的 Bundle Identifier（如 `com.apple.Preferences`）。若传入应用名称且在 `appNameMapping` 中存在映射，将自动解析为对应 Bundle ID。
+
+```ts
+await agent.terminate('com.apple.Preferences');
+await agent.terminate('com.apple.mobilesafari');
+```
+
+##### `agent.runWdaRequest()`
+
+当你需要更底层的控制能力时，执行原始的 WebDriverAgent REST 请求。
+
+```ts
+function runWdaRequest(
+  method: string,
+  endpoint: string,
+  data?: Record<string, any>,
+): Promise<any>;
+```
+
+- `method: string` —— HTTP 动词（`GET`、`POST`、`DELETE` 等）。
+- `endpoint: string` —— WebDriverAgent 接口路径。
+- `data?: Record<string, any>` —— 可选的 JSON 请求体。
+
+```ts
+const screen = await agent.runWdaRequest('GET', '/wda/screen');
+await agent.runWdaRequest('POST', '/session/test/wda/pressButton', { name: 'home' });
+```
+
+#### 应用间导航
+
+- `agent.home(): Promise<void>` —— 回到主屏。
+- `agent.appSwitcher(): Promise<void>` —— 打开多任务视图。
+
+#### 辅助工具
+
+##### `agentFromWebDriverAgent()` {#agentfromwebdriveragent}
+
+连接 WebDriverAgent 并返回可用的 IOSAgent。
+
+```ts
+function agentFromWebDriverAgent(
+  opts?: PageAgentOpt & IOSDeviceOpt,
+): Promise<IOSAgent>;
+```
+
+- `opts?: PageAgentOpt & IOSDeviceOpt` —— 在一个对象中同时传入通用 Agent 选项与 [`IOSDevice`](#iosdevice) 的配置。
+- 设置 `MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE` 可通过环境变量应用同一个设备 class override。显式传入的选项优先级高于环境变量。
+
+```ts
+import { agentFromWebDriverAgent } from '@midscene/ios';
+
+const agent = await agentFromWebDriverAgent({
+  wdaHost: 'localhost',
+  wdaPort: 8100,
+  iOSDeviceClassOverride: '@your-scope/ios-device',
+  aiActionContext: 'Accept permission dialogs automatically.',
+});
+```
+
+### 扩展自定义交互动作
+
+通过 `defineAction` 创建处理器并传入 `customActions`，即可扩展 Agent 的动作空间。这些动作会追加在内置动作之后，可在规划阶段被调用。
+
+```ts
+import { getMidsceneLocationSchema, z } from '@midscene/core';
+import { defineAction } from '@midscene/core/device';
+import { agentFromWebDriverAgent } from '@midscene/ios';
+
+const ContinuousClick = defineAction({
+  name: 'continuousClick',
+  description: 'Click the same target repeatedly',
+  paramSchema: z.object({
+    locate: getMidsceneLocationSchema(),
+    count: z
+      .number()
+      .int()
+      .positive()
+      .describe('How many times to click'),
+  }),
+  async call({ locate, count }) {
+    console.log('click target center', locate.center);
+    console.log('click count', count);
+  },
+});
+
+const agent = await agentFromWebDriverAgent({
+  customActions: [ContinuousClick],
+});
+
+await agent.aiAct('Click the red button five times');
+```
+
+### 相关阅读
+
+- [与任意界面集成](./integrate-with-any-interface) 查看自定义动作与 Schema 细节。
diff --git a/apps/site/docs/zh/quick-start.mdx b/apps/site/docs/zh/quick-start.mdx
index 34eaf7d9ae..41d3deefe2 100644
--- a/apps/site/docs/zh/quick-start.mdx
+++ b/apps/site/docs/zh/quick-start.mdx
@@ -102,5 +102,5 @@ Midscene - report file updated: ./midscene_run/report/some_id.html
 ## 后续步骤
 
 - **用于测试**：[集成到 Playwright](./integrate-with-playwright)，把 Midscene 接入你现有的测试套件。
-- **其他平台**：在 [Android](./android-getting-started)、[iOS](./ios-getting-started)、[HarmonyOS](./harmony-getting-started) 或 [桌面端](./computer-getting-started) 上开始使用。
+- **其他平台**：在 [Android](./android)、[iOS](./ios)、[HarmonyOS](./harmony) 或 [桌面端](./computer) 上开始使用。
 - **进一步了解**：用 [模型策略](./model-strategy) 提升效果，或在 [API 参考](./api) 中查阅所有方法。
diff --git a/apps/site/rspress.config.ts b/apps/site/rspress.config.ts
index 614d71e723..46a8c6e161 100644
--- a/apps/site/rspress.config.ts
+++ b/apps/site/rspress.config.ts
@@ -169,64 +169,23 @@ export default defineConfig(async () => {
             link: '/web-api-reference',
           },
           {
-            sectionHeaderText: 'Android',
+            sectionHeaderText: 'More platforms',
           },
           {
-            text: 'Introduction',
-            link: '/android-introduction',
-          },
-          {
-            text: 'Getting started',
-            link: '/android-getting-started',
-          },
-          {
-            text: 'API reference (Android)',
-            link: '/android-api-reference',
-          },
-          {
-            sectionHeaderText: 'iOS',
-          },
-          {
-            text: 'Introduction',
-            link: '/ios-introduction',
-          },
-          {
-            text: 'Getting started',
-            link: '/ios-getting-started',
-          },
-          {
-            text: 'API reference (iOS)',
-            link: '/ios-api-reference',
-          },
-          {
-            sectionHeaderText: 'HarmonyOS',
-          },
-          {
-            text: 'Introduction',
-            link: '/harmony-introduction',
-          },
-          {
-            text: 'Getting started',
-            link: '/harmony-getting-started',
-          },
-          {
-            text: 'API reference (HarmonyOS)',
-            link: '/harmony-api-reference',
-          },
-          {
-            sectionHeaderText: 'PC Desktop',
+            text: 'Android',
+            link: '/android',
           },
           {
-            text: 'Introduction',
-            link: '/computer-introduction',
+            text: 'iOS',
+            link: '/ios',
           },
           {
-            text: 'Getting started',
-            link: '/computer-getting-started',
+            text: 'HarmonyOS',
+            link: '/harmony',
           },
           {
-            text: 'API reference (PC Desktop)',
-            link: '/computer-api-reference',
+            text: 'PC Desktop',
+            link: '/computer',
           },
           {
             sectionHeaderText: 'YAML automation',
@@ -359,64 +318,23 @@ export default defineConfig(async () => {
             link: '/zh/web-api-reference',
           },
           {
-            sectionHeaderText: 'Android',
-          },
-          {
-            text: '介绍',
-            link: '/zh/android-introduction',
-          },
-          {
-            text: '开始使用',
-            link: '/zh/android-getting-started',
-          },
-          {
-            text: 'API 参考（Android）',
-            link: '/zh/android-api-reference',
-          },
-          {
-            sectionHeaderText: 'iOS',
-          },
-          {
-            text: '介绍',
-            link: '/zh/ios-introduction',
-          },
-          {
-            text: '开始使用',
-            link: '/zh/ios-getting-started',
-          },
-          {
-            text: 'API 参考（iOS）',
-            link: '/zh/ios-api-reference',
-          },
-          {
-            sectionHeaderText: 'HarmonyOS',
-          },
-          {
-            text: '介绍',
-            link: '/zh/harmony-introduction',
-          },
-          {
-            text: '开始使用',
-            link: '/zh/harmony-getting-started',
-          },
-          {
-            text: 'API 参考（HarmonyOS）',
-            link: '/zh/harmony-api-reference',
+            sectionHeaderText: '更多平台',
           },
           {
-            sectionHeaderText: 'PC 桌面',
+            text: 'Android',
+            link: '/zh/android',
           },
           {
-            text: '介绍',
-            link: '/zh/computer-introduction',
+            text: 'iOS',
+            link: '/zh/ios',
           },
           {
-            text: '开始使用',
-            link: '/zh/computer-getting-started',
+            text: 'HarmonyOS',
+            link: '/zh/harmony',
           },
           {
-            text: 'API 参考（PC 桌面）',
-            link: '/zh/computer-api-reference',
+            text: 'PC 桌面',
+            link: '/zh/computer',
           },
           {
             sectionHeaderText: 'YAML automation',
@@ -566,25 +484,121 @@ export default defineConfig(async () => {
       }),
       pluginClientRedirects({
         redirects: [
+          {
+            from: '^/android-introduction(?:\\.html)?/?$',
+            to: '/android',
+          },
+          {
+            from: '^/android-getting-started(?:\\.html)?/?$',
+            to: '/android',
+          },
+          {
+            from: '^/android-api-reference(?:\\.html)?/?$',
+            to: '/android#api-reference',
+          },
+          {
+            from: '^/ios-introduction(?:\\.html)?/?$',
+            to: '/ios',
+          },
+          {
+            from: '^/ios-getting-started(?:\\.html)?/?$',
+            to: '/ios',
+          },
+          {
+            from: '^/ios-api-reference(?:\\.html)?/?$',
+            to: '/ios#api-reference',
+          },
+          {
+            from: '^/harmony-introduction(?:\\.html)?/?$',
+            to: '/harmony',
+          },
+          {
+            from: '^/harmony-getting-started(?:\\.html)?/?$',
+            to: '/harmony',
+          },
+          {
+            from: '^/harmony-api-reference(?:\\.html)?/?$',
+            to: '/harmony#api-reference',
+          },
+          {
+            from: '^/computer-introduction(?:\\.html)?/?$',
+            to: '/computer',
+          },
+          {
+            from: '^/computer-getting-started(?:\\.html)?/?$',
+            to: '/computer',
+          },
+          {
+            from: '^/computer-api-reference(?:\\.html)?/?$',
+            to: '/computer#api-reference',
+          },
+          {
+            from: '^/zh/android-introduction(?:\\.html)?/?$',
+            to: '/zh/android',
+          },
+          {
+            from: '^/zh/android-getting-started(?:\\.html)?/?$',
+            to: '/zh/android',
+          },
+          {
+            from: '^/zh/android-api-reference(?:\\.html)?/?$',
+            to: '/zh/android#api-reference',
+          },
+          {
+            from: '^/zh/ios-introduction(?:\\.html)?/?$',
+            to: '/zh/ios',
+          },
+          {
+            from: '^/zh/ios-getting-started(?:\\.html)?/?$',
+            to: '/zh/ios',
+          },
+          {
+            from: '^/zh/ios-api-reference(?:\\.html)?/?$',
+            to: '/zh/ios#api-reference',
+          },
+          {
+            from: '^/zh/harmony-introduction(?:\\.html)?/?$',
+            to: '/zh/harmony',
+          },
+          {
+            from: '^/zh/harmony-getting-started(?:\\.html)?/?$',
+            to: '/zh/harmony',
+          },
+          {
+            from: '^/zh/harmony-api-reference(?:\\.html)?/?$',
+            to: '/zh/harmony#api-reference',
+          },
+          {
+            from: '^/zh/computer-introduction(?:\\.html)?/?$',
+            to: '/zh/computer',
+          },
+          {
+            from: '^/zh/computer-getting-started(?:\\.html)?/?$',
+            to: '/zh/computer',
+          },
+          {
+            from: '^/zh/computer-api-reference(?:\\.html)?/?$',
+            to: '/zh/computer#api-reference',
+          },
           {
             from: '^/integrate-with-android(?:\\.html)?/?$',
-            to: '/android-getting-started',
+            to: '/android',
           },
           {
             from: '^/integrate-with-ios(?:\\.html)?/?$',
-            to: '/ios-getting-started',
+            to: '/ios',
           },
           {
             from: '^/integrate-with-harmony(?:\\.html)?/?$',
-            to: '/harmony-getting-started',
+            to: '/harmony',
           },
           {
             from: '^/android-playground(?:\\.html)?/?$',
-            to: '/android-introduction',
+            to: '/android',
           },
           {
             from: '^/ios-playground(?:\\.html)?/?$',
-            to: '/ios-getting-started',
+            to: '/ios',
           },
           {
             from: '^/choose-a-model(?:\\.html)?/?$',
@@ -612,19 +626,19 @@ export default defineConfig(async () => {
           },
           {
             from: '^/blog-support-android-automation(?:\\.html)?/?$',
-            to: '/android-introduction',
+            to: '/android',
           },
           {
             from: '^/blog-support-ios-automation(?:\\.html)?/?$',
-            to: '/ios-introduction',
+            to: '/ios',
           },
           {
             from: '^/quick-experience-with-android(?:\\.html)?/?$',
-            to: '/android-getting-started',
+            to: '/android',
           },
           {
             from: '^/quick-experience-with-ios(?:\\.html)?/?$',
-            to: '/ios-getting-started',
+            to: '/ios',
           },
           {
             from: '^/zh/web-mcp(?:\\.html)?/?$',
@@ -636,31 +650,31 @@ export default defineConfig(async () => {
           },
           {
             from: '^/zh/integrate-with-android(?:\\.html)?/?$',
-            to: '/zh/android-getting-started',
+            to: '/zh/android',
           },
           {
             from: '^/zh/integrate-with-ios(?:\\.html)?/?$',
-            to: '/zh/ios-getting-started',
+            to: '/zh/ios',
           },
           {
             from: '^/zh/integrate-with-harmony(?:\\.html)?/?$',
-            to: '/zh/harmony-getting-started',
+            to: '/zh/harmony',
           },
           {
             from: '^/zh/blog-support-android-automation(?:\\.html)?/?$',
-            to: '/zh/android-introduction',
+            to: '/zh/android',
           },
           {
             from: '^/zh/blog-support-ios-automation(?:\\.html)?/?$',
-            to: '/zh/ios-introduction',
+            to: '/zh/ios',
           },
           {
             from: '^/zh/quick-experience-with-android(?:\\.html)?/?$',
-            to: '/zh/android-getting-started',
+            to: '/zh/android',
           },
           {
             from: '^/zh/quick-experience-with-ios(?:\\.html)?/?$',
-            to: '/zh/ios-getting-started',
+            to: '/zh/ios',
           },
           {
             from: '^/zh/choose-a-model(?:\\.html)?/?$',
@@ -680,11 +694,11 @@ export default defineConfig(async () => {
           },
           {
             from: '^/zh/android-playground(?:\\.html)?/?$',
-            to: '/zh/android-introduction',
+            to: '/zh/android',
           },
           {
             from: '^/zh/ios-playground(?:\\.html)?/?$',
-            to: '/zh/ios-getting-started',
+            to: '/zh/ios',
           },
           {
             from: '^/command-line-tools(?:\\.html)?/?$',
diff --git a/apps/site/theme/i18n/enUS.ts b/apps/site/theme/i18n/enUS.ts
index cdf8c29879..3e6ab25705 100644
--- a/apps/site/theme/i18n/enUS.ts
+++ b/apps/site/theme/i18n/enUS.ts
@@ -118,6 +118,6 @@ and more`,
   multiModelStrategyLink: '/model-strategy#advanced-combining-multiple-models',
   platformWebLink: '/quick-experience.html',
   platformPCLink: '/quick-experience.html',
-  platformMobileLink: '/android-introduction.html',
+  platformMobileLink: '/android.html',
   platformAnyInterfaceLink: '/integrate-with-any-interface.html',
 } as const;
diff --git a/apps/site/theme/i18n/zhCN.ts b/apps/site/theme/i18n/zhCN.ts
index e79a3c50b1..729910e74a 100644
--- a/apps/site/theme/i18n/zhCN.ts
+++ b/apps/site/theme/i18n/zhCN.ts
@@ -111,6 +111,6 @@ export const ZH_CN: Record<keyof typeof EN_US, string> = {
   multiModelStrategyLink: '/model-strategy#高阶特性多模型配合',
   platformWebLink: '/quick-experience.html',
   platformPCLink: '/quick-experience.html',
-  platformMobileLink: '/android-introduction.html',
+  platformMobileLink: '/android.html',
   platformAnyInterfaceLink: '/integrate-with-any-interface.html',
 };