Merge branch 'main' into feat/android-screenshot-resize-ratio

Author: yuyutaotao

apps/chrome-extension/static/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "Midscene.js",
   "description": "Open-source SDK for automating web pages using natural language through AI.",
-  "version": "0.130",
+  "version": "0.132",
   "manifest_version": 3,
   "permissions": [
     "activeTab",

apps/site/docs/en/caching.mdx

@@ -51,22 +51,33 @@ agent:
 
 ### Read-write mode
 
-Configuration: `cache: { id: "my-cache-id" }`
+Configuration: `cache: { id: "my-cache-id" }` or `cache: { strategy: "read-write", id: "my-cache-id" }`
 
-Automatically read existing cache and update cache files during execution.
+Automatically read existing cache and update cache files during execution. The default value of `strategy` is `read-write`.
 
 ```javascript
 // Direct Agent creation - explicit cache ID
 const agent = new PuppeteerAgent(page, {
   cache: { id: "my-cache-id" },
 });
+
+// Explicitly specify strategy
+const agent = new PuppeteerAgent(page, {
+  cache: { strategy: "read-write", id: "my-cache-id" },
+});
 ```
 
 ```yaml
 # YAML configuration - explicit cache ID
 agent:
   cache:
     id: "my-cache-test"
+
+# Explicitly specify strategy
+agent:
+  cache:
+    id: "my-cache-test"
+    strategy: "read-write"
 ```
 
 YAML mode also supports `cache: true` to automatically use the file name as the cache ID.

apps/site/docs/en/integrate-with-android.mdx

@@ -164,6 +164,40 @@ await agent.launch('com.android.settings'); // open a native page
 await agent.launch('com.android.settings/.Settings'); // open a native page
 ```
 
+#### `agent.runAdbShell()`
+
+Execute a command through `adb shell` on the connected device.
+
+> Note: This method wraps `adb shell` and forwards the command directly to the device.
+
+- Type
+
+```typescript
+function runAdbShell(command: string): Promise<string>;
+```
+
+- Parameters:
+
+  - `command: string` - The adb shell command to execute.
+
+- Return Value:
+
+  - `Promise<string>` - Returns a Promise that resolves to the command output.
+
+- Examples:
+
+```typescript
+import { AndroidAgent, AndroidDevice } from '@midscene/android';
+
+const device = new AndroidDevice('s4ey59');
+const agent = new AndroidAgent(device);
+await device.connect();
+
+const result = await agent.runAdbShell('dumpsys battery');
+// Equivalent to running `adb shell dumpsys battery`
+console.log(result);
+```
+
 #### `agentFromAdbDevice()`
 
 Create a AndroidAgent from a connected adb device.

apps/site/docs/zh/caching.mdx

@@ -54,22 +54,33 @@ agent:
 
 ### 读写模式
 
-配置方式：`cache: { id: "my-cache-id" }`
+配置方式：`cache: { id: "my-cache-id" }` 或 `cache: { strategy: "read-write", id: "my-cache-id" }`
 
-自动读取已有缓存，执行过程中自动更新缓存文件。
+自动读取已有缓存，执行过程中自动更新缓存文件。`strategy` 的默认值是 `read-write`。
 
 ```javascript
 // 直接创建 Agent - 显式设置 cache ID
 const agent = new PuppeteerAgent(page, {
   cache: { id: "my-cache-id" },
 });
+
+// 显式指定 strategy
+const agent = new PuppeteerAgent(page, {
+  cache: { strategy: "read-write", id: "my-cache-id" },
+});
 ```
 
 ```yaml
 # YAML 配置 - 显式设置 cache ID
 agent:
   cache:
     id: "my-cache-test"
+
+# 显式指定 strategy
+agent:
+  cache:
+    id: "my-cache-test"
+    strategy: "read-write"
 ```
 
 YAML 模式还支持配置 `cache: true`，自动使用文件名作为 cache ID。

apps/site/docs/zh/integrate-with-android.mdx

@@ -163,6 +163,40 @@ await agent.launch('com.android.settings'); // 打开系统设置 app(package na
 await agent.launch('com.android.settings/.Settings'); // 打开系统设置 app(package name) 的 .Settings(activity name) 页面
 ```
 
+#### `agent.runAdbShell()`
+
+执行 `adb shell` 命令。
+
+> 注意：该方法本质上是调用 `adb shell` 执行传入的命令。
+
+- 类型
+
+```typescript
+function runAdbShell(command: string): Promise<string>;
+```
+
+- 参数：
+
+  - `command: string` - 要执行的 adb shell 命令
+
+- 返回值:
+
+  - `Promise<string>` - 命令执行的输出结果
+
+- 示例:
+
+```typescript
+import { AndroidAgent, AndroidDevice } from '@midscene/android';
+
+const page = new AndroidDevice('s4ey59');
+const agent = new AndroidAgent(page);
+await page.connect();
+
+const result = await agent.runAdbShell('dumpsys battery');
+// 等同于执行 `adb shell dumpsys battery`
+console.log(result);
+```
+
 #### `agentFromAdbDevice()`
 
 从已连接的 adb 设备中，创建一个 AndroidAgent。