docs(site): clarify screenshot scaling options (#2765)

Author: EAGzzyCSL

apps/site/docs/en/api.mdx

@@ -37,7 +37,23 @@ All agents share these base options:
   Then access the report via `http://localhost:3000` (or the port shown in the terminal).
 - `screenshotShrinkFactor: number`: Controls the scaling ratio of screenshots to reduce the image size sent to the AI model, thereby reducing token consumption. The default value is 1 (no scaling). If set to 2, the width and height of the screenshot will be halved, and the area will be reduced to a quarter of the original. You can adjust this value based on your actual situation to find the best balance between image clarity and token consumption.
   - 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.
+  - For web pages, if the content is complex or contains a lot of details, avoid setting `screenshotShrinkFactor` too high to prevent overly blurry screenshots. You can usually control screenshot size earlier in the pipeline through Puppeteer or Playwright's `deviceScaleFactor`.
+
+:::info
+
+**Difference between `screenshotShrinkFactor` and `deviceScaleFactor`:**
+
+- `screenshotShrinkFactor` is a Midscene-specific option. It controls whether Midscene compresses a screenshot after capturing it from devices such as browsers and phones. Its purpose is to reduce token consumption and speed up model responses, but excessive compression can blur the image and hurt the model's understanding.
+
+- `deviceScaleFactor` is a Puppeteer and Playwright option for configuring high-DPI display adaptation. It defines how many physical pixels should be used to render one CSS logical pixel. This is why a mismatch between `deviceScaleFactor` and the actual device scale can cause page flickering in non-headless mode. The same scaling logic also determines the screenshot size generated by Puppeteer/Playwright, based on physical pixels. Compared with `screenshotShrinkFactor`, it controls screenshot size further upstream at the production stage.
+
+**Can they be used together?**
+
+- Web scenarios: using both usually has limited value. Prefer `deviceScaleFactor` to control screenshot size directly at the production stage.
+  - One exception: when you configure `deviceScaleFactor` to avoid browser flickering, but still do not want to send an oversized screenshot to the model. In that case, you can also use `screenshotShrinkFactor` to compress the image before model consumption.
+- Mobile and other non-Web scenarios: `deviceScaleFactor` is not available, so use `screenshotShrinkFactor` to control the screenshot size consumed by the model.
+
+:::
 
 The device CLIs expose these same Agent behavior options per call. Convert the camelCase API option to a bare kebab-case flag, such as `waitAfterAction` -> `--wait-after-action`. See [Skills](./skills) for the platform CLI entry points.
 

apps/site/docs/zh/api.mdx

@@ -39,7 +39,23 @@ Midscene 针对每个不同环境都有对应的 Agent。每个 Agent 的构造
   然后通过 `http://localhost:3000`（或终端显示的端口）访问报告。
 - `screenshotShrinkFactor: number`: 控制截图的缩放比例，以减少发送给 AI 模型的图像大小，从而减少 token 消耗。默认值为 1（不缩放）。如果将其设置为 2，则截图的宽高将缩小为原来的一半，面积缩小为原来的四分之一。你可以根据实际情况调整这个值，以在图像清晰度和 token 消耗之间找到最佳平衡点。
   - 对于移动端设备，将 `screenshotShrinkFactor` 设置为 2 可以在保持清晰度的同时减少 token 的消耗，但不建议设置的值超过 3，否则可能会导致图像过于模糊，影响 AI 模型的理解。
-  - 对于 Web 页面，如果页面内容比较复杂或包含大量细节，不建议设置 `screenshotShrinkFactor`，以避免截图过于模糊。此外，如果为了让 Web 页面截图有更高的清晰度，可以配置 Puppeteer 或 Playwright 的 `deviceScaleFactor` 为 2，这可以让 Puppeteer 或 Playwright 按照高清屏的方式来渲染页面。
+  - 对于 Web 页面，如果页面内容比较复杂或包含大量细节，不建议设置过高的 `screenshotShrinkFactor`，以避免截图过于模糊。通常也可以通过 Puppeteer 或 Playwright 的 `deviceScaleFactor` 在更上游控制截图尺寸。
+
+:::info
+
+**`screenshotShrinkFactor` 与 `deviceScaleFactor` 的区别：**
+
+- `screenshotShrinkFactor` 是 Midscene 自定义的参数，用于控制拿到浏览器、手机等设备的截图后，是否对其进行尺寸压缩。目的是减少 token 消耗、加快模型响应速度。但过度压缩会导致图片模糊，影响模型理解。
+
+- `deviceScaleFactor` 是 Puppeteer 和 Playwright 自带的参数，用于配置高清屏适配（现在很多设备都是高清屏了）时将一个 CSS 逻辑像素渲染为几倍的物理像素。这也就是为什么 `deviceScaleFactor` 和实际设备的缩放比例不一致时，非 headless 模式下可能会出现页面闪烁。同时，这一缩放逻辑也决定了 Puppeteer/Playwright 的截图尺寸（基于物理像素）。相比于 `screenshotShrinkFactor`，它是在更上游的生产端控制了截图尺寸。
+
+**二者是否可以同时使用？**
+
+- Web 场景：二者同时使用的意义不大，应该优先使用 `deviceScaleFactor`，直接在生产端控制截图尺寸。
+  - 一种特殊情况：你期望配置 `deviceScaleFactor` 来避免浏览器闪烁，但同时又不期望发送给模型的截图过大，此时可以同时使用 `screenshotShrinkFactor` 控制发送给模型时的图片压缩。
+- 移动端等非 Web 场景：因为没有 `deviceScaleFactor` 参数可用，所以只能通过 `screenshotShrinkFactor` 来控制模型消费时使用的截图尺寸。
+
+:::
 
 设备 CLI 可以按单次调用传入这些 Agent 行为参数。把 API 的 camelCase 参数名转换成不带平台前缀的 kebab-case flag，例如 `waitAfterAction` -> `--wait-after-action`。各平台 CLI 入口请参考 [Skills](./skills)。