docs(site): clarify cli agent behavior args

Author: quanru

apps/site/docs/en/api.mdx

@@ -39,6 +39,8 @@ All agents share these base options:
   - For mobile devices, setting `screenshotShrinkFactor` to 2 can reduce token consumption while maintaining clarity, but it is not recommended to set it higher than 3, as this may cause the image to be too blurry and affect the AI model's understanding.
   - For web pages, if the content is complex or contains a lot of details, it is not recommended to set `screenshotShrinkFactor` to avoid overly blurry screenshots. Additionally, if you want higher clarity for web page screenshots, you can configure Puppeteer or Playwright's `deviceScaleFactor` to 2, which will allow Puppeteer or Playwright to render the page as if it were a high-definition screen.
 
+The MCP tools and device CLIs expose these same Agent behavior options per call. In CLIs, convert the camelCase API option to a bare kebab-case flag, such as `waitAfterAction` -> `--wait-after-action`. In MCP calls, keep the camelCase option under the platform namespace, such as `android.waitAfterAction` or `web.waitAfterAction`. See [Configure Agent behavior per call](./mcp#configure-agent-behavior-per-call) for examples.
+
 ### Custom model configuration
 
 Use `modelConfig: Record<string, string | number>` to configure models directly in code instead of environment variables.

apps/site/docs/en/mcp.mdx

@@ -192,24 +192,25 @@ A per-call value always wins over the startup flag: action tools accept `locate.
 
 ## Configure Agent behavior per call
 
-MCP tools and the device CLIs also accept common Agent behavior parameters. Use them when a target UI needs a longer settle time, a different `act` replanning limit, extra action context, or smaller screenshots.
+MCP tools and the device CLIs also accept common Agent behavior parameters. Use them when a target UI needs a longer settle time, a different `act` replanning limit, extra action context, or smaller screenshots. These parameters are the per-call form of the same Agent options documented in [API reference (Common)](./api#parameters).
 
-In the device CLIs, pass the bare kebab-case flags on each command that should use them:
+In the device CLIs, convert the API camelCase option name to a bare kebab-case flag and pass it on each command that should use it. The generated CLI also accepts the original camelCase alias shown in `--help`, but docs and examples use kebab-case:
 
 ```bash
 midscene-android tap --locate "the login button" --wait-after-action 800
 midscene-web act --prompt "finish checkout" --replanning-cycle-limit 30
 midscene-ios assert --prompt "the success message is visible" --screenshot-shrink-factor 2
 ```
 
-Available flags:
+Common flags:
 
-- `--wait-after-action <ms>`: wait time after each action execution. The default is `300`.
-- `--replanning-cycle-limit <n>`: maximum number of `aiAct` replanning cycles.
-- `--ai-act-context <text>`: extra background knowledge for `aiAct`.
-- `--screenshot-shrink-factor <n>`: shrink screenshots before sending them to the AI model.
+- `--wait-after-action <ms>` maps to `waitAfterAction`: wait time after each action execution. The default is `300`.
+- `--replanning-cycle-limit <n>` maps to `replanningCycleLimit`: maximum number of `aiAct` replanning cycles.
+- `--ai-act-context <text>` maps to `aiActContext`: extra background knowledge for `aiAct`.
+- `--ai-action-context <text>` maps to `aiActionContext`: deprecated alias for `aiActContext`.
+- `--screenshot-shrink-factor <n>` maps to `screenshotShrinkFactor`: shrink screenshots before sending them to the AI model.
 
-In MCP calls, use the same camelCase names under the platform namespace: `android.waitAfterAction`, `harmony.waitAfterAction`, `ios.waitAfterAction`, `computer.waitAfterAction`, or `web.waitAfterAction`. The same pattern applies to `replanningCycleLimit`, `aiActContext`, and `screenshotShrinkFactor`.
+In MCP calls, keep the API camelCase name and put it under the platform namespace: `android.waitAfterAction`, `harmony.waitAfterAction`, `ios.waitAfterAction`, `computer.waitAfterAction`, or `web.waitAfterAction`. The same pattern applies to `replanningCycleLimit`, `aiActContext`, `aiActionContext`, and `screenshotShrinkFactor`.
 
 These parameters are part of the Agent init args for that tool call. If a later call changes them, or omits them after setting them, Midscene rebuilds the Agent so the next call uses the new effective configuration. For Web tools, `web.url` opens or navigates to the URL each time it is supplied; omit it to keep using the current page.
 

apps/site/docs/zh/api.mdx

@@ -41,6 +41,8 @@ Midscene 针对每个不同环境都有对应的 Agent。每个 Agent 的构造
   - 对于移动端设备，将 `screenshotShrinkFactor` 设置为 2 可以在保持清晰度的同时减少 token 的消耗，但不建议设置的值超过 3，否则可能会导致图像过于模糊，影响 AI 模型的理解。
   - 对于 Web 页面，如果页面内容比较复杂或包含大量细节，不建议设置 `screenshotShrinkFactor`，以避免截图过于模糊。此外，如果为了让 Web 页面截图有更高的清晰度，可以配置 Puppeteer 或 Playwright 的 `deviceScaleFactor` 为 2，这可以让 Puppeteer 或 Playwright 按照高清屏的方式来渲染页面。
 
+MCP 工具和设备 CLI 也可以按单次调用传入这些 Agent 行为参数。在 CLI 中，把 API 的 camelCase 参数名转换成不带平台前缀的 kebab-case flag，例如 `waitAfterAction` -> `--wait-after-action`。在 MCP 调用中，保留 camelCase 参数名，并放在平台 namespace 下，例如 `android.waitAfterAction` 或 `web.waitAfterAction`。示例见 [按单次调用配置 Agent 行为](./mcp#按单次调用配置-agent-行为)。
+
 ### 自定义模型
 
 `modelConfig: Record<string, string | number>` 可选。它允许你通过代码配置模型，而不是通过环境变量。

apps/site/docs/zh/mcp.mdx

@@ -192,24 +192,25 @@ midscene-android --deep-locate tap --locate "登录按钮"
 
 ## 按单次调用配置 Agent 行为
 
-MCP 工具和设备 CLI 也支持通用的 Agent 行为参数。如果目标 UI 需要更长的稳定等待时间、不同的 `act` 重规划上限、额外的动作上下文，或需要压缩截图，都可以使用这些参数。
+MCP 工具和设备 CLI 也支持通用的 Agent 行为参数。如果目标 UI 需要更长的稳定等待时间、不同的 `act` 重规划上限、额外的动作上下文，或需要压缩截图，都可以使用这些参数。这些参数是 [API 公共参考](./api#参数) 中同名 Agent options 的单次调用写法。
 
-在设备 CLI 中，把这些 bare kebab-case 参数加到需要生效的命令上：
+在设备 CLI 中，把 API 里的 camelCase 参数名转换成不带平台前缀的 kebab-case flag，并加到需要生效的命令上。生成的 CLI 也接受 `--help` 中展示的 camelCase alias，但文档和示例统一使用 kebab-case：
 
 ```bash
 midscene-android tap --locate "登录按钮" --wait-after-action 800
 midscene-web act --prompt "完成结账" --replanning-cycle-limit 30
 midscene-ios assert --prompt "成功提示可见" --screenshot-shrink-factor 2
 ```
 
-可用参数：
+通用参数：
 
-- `--wait-after-action <ms>`：每次动作执行后的等待时间，默认值为 `300`。
-- `--replanning-cycle-limit <n>`：`aiAct` 的最大重规划次数。
-- `--ai-act-context <text>`：传给 `aiAct` 的额外背景信息。
-- `--screenshot-shrink-factor <n>`：发送给 AI 模型前的截图压缩倍率。
+- `--wait-after-action <ms>` 对应 `waitAfterAction`：每次动作执行后的等待时间，默认值为 `300`。
+- `--replanning-cycle-limit <n>` 对应 `replanningCycleLimit`：`aiAct` 的最大重规划次数。
+- `--ai-act-context <text>` 对应 `aiActContext`：传给 `aiAct` 的额外背景信息。
+- `--ai-action-context <text>` 对应 `aiActionContext`：`aiActContext` 的旧参数名，不建议继续使用。
+- `--screenshot-shrink-factor <n>` 对应 `screenshotShrinkFactor`：发送给 AI 模型前的截图压缩倍率。
 
-在 MCP 调用中，使用平台 namespace 下的 camelCase 参数名：`android.waitAfterAction`、`harmony.waitAfterAction`、`ios.waitAfterAction`、`computer.waitAfterAction` 或 `web.waitAfterAction`。`replanningCycleLimit`、`aiActContext` 和 `screenshotShrinkFactor` 也使用同样的规则。
+在 MCP 调用中，保留 API 里的 camelCase 参数名，并放在平台 namespace 下：`android.waitAfterAction`、`harmony.waitAfterAction`、`ios.waitAfterAction`、`computer.waitAfterAction` 或 `web.waitAfterAction`。`replanningCycleLimit`、`aiActContext`、`aiActionContext` 和 `screenshotShrinkFactor` 也使用同样的规则。
 
 这些参数属于当前工具调用的 Agent init args。后续调用如果改变这些参数，或在设置后省略它们，Midscene 会重建 Agent，让下一次调用使用新的有效配置。对于 Web 工具，只要传入 `web.url`，每次都会打开或导航到该 URL；省略它则继续使用当前页面。