@taole/dd-playwright 0.1.11 → 0.1.12

package/README.md

@@ -8,7 +8,8 @@
 
 | 工具 | 说明 |
 |---|---|
-| `browser_navigate` | 访问 URL。支持显式指定 `uid` 选择绑定账号（默认使用当前默认账号）；支持通过 `anonymous: true` 模拟未登录游客状态访问 |
+| `browser_navigate` | 访问 URL。支持显式指定 `uid` 选择绑定账号（默认使用当前默认账号）；支持通过 `anonymous: true` 模拟未登录游客状态访问；支持 `device`（如 `iPhone 13`）启用完整移动端仿真（视口+UA+触摸），传 `desktop` 恢复桌面模式；支持 `userAgent` 会话级自定义 UA，传 `default` 清除 |
+| `browser_resize` | 调整当前页面渲染视口（对标 playwright-mcp）。只改 innerWidth/innerHeight，不改 UA/触摸；完整移动仿真请用 `browser_navigate` 的 `device` 参数 |
 | `browser_screenshot` | 页面/元素截图，落盘到数据目录并返回路径 |
 | `browser_get_console_errors` | 收集 console.error 与未捕获异常 |
 | `browser_click_element` | 按选择器模拟用户点击元素 |
@@ -42,6 +43,7 @@ npx playwright install chromium
 - **数据目录**：默认自动固定为 `~/.dd-browser-mcp`（账号库 `runtime.db` 与截图目录），无需手动设置环境变量。
 - **无头模式 (Headless)**：默认为 `true`（静默后台运行），可在 Web 控制台（`http://127.0.0.1:12309`）的「全局运行配置」中一键开关切换为可见窗口。
 - **域名白名单**：默认为 `tuwan.com`，可通过 `BROWSER_MCP_DOMAIN_SUFFIX` 按需调整。
+- **自定义 UA**：优先用 `browser_navigate` 的 `userAgent` 参数（会话级，随调随改）；也可用环境变量 `BROWSER_MCP_USER_AGENT` 设置启动级默认值。UA 优先级：工具参数 > 环境变量 > `device` 设备描述符 > 浏览器默认；自定义 UA 只替换 UA 字符串，视口与触摸仿真仍按 `device` 生效。
 
 登录态来源优先级：`BROWSER_MCP_STORAGE_STATE` 文件 > `~/.dd-browser-mcp/runtime.db` 中激活的账号 > 无登录态。
 

package/SKILL.md

@@ -31,7 +31,28 @@ description: >-
 4. **请求头注入**：`y.tuwan.com reqHeaders://{debug: '1'}`
 > 更多高级协议与规则参考官方文档：https://wproxy.org/whistle/rules/
 
-## 3. 页面交互规范
+## 3. 设备与视口仿真（移动端/H5 验收）
+- **移动端验收**：调用 `browser_navigate` 时传 `device`（Playwright 设备描述符名，如 `"iPhone 13"`、`"Pixel 7"`），一次性启用完整移动仿真：移动视口 + 移动 UA + isMobile + 触摸事件（hasTouch）。设置后整个会话保持，后续导航无需重复传；传 `"desktop"` 恢复默认 1280×800 桌面模式。
+- **切换时机**：切换 device 会重建浏览器上下文（当前页面关闭后重开目标 URL，登录态自动重挂），必须在导航时一并指定，严禁在已打开页面的会话中途切换。
+- **仅调视口**：只需改变 innerWidth/innerHeight（如响应式断点验证）时调用 `browser_resize({ width, height })`；它不改 UA 与触摸仿真，页面内执行 `window.resizeTo` 对 Playwright 视口无效，不要用它尝试改视口。
+- **常见设备名参考**：`iPhone 13`（390×844）、`iPhone 15 Pro`（393×852）、`Pixel 7`（412×915）、`iPad Mini`（768×1024）；传错名称时工具会返回错误提示与示例。
+- **自定义 UA**：调用 `browser_navigate` 时传 `userAgent`（如模拟 App 内 WebView：`"WebView/9.9 ..."`），会话级生效、整个会话保持；只替换 UA 字符串，不影响视口与触摸仿真，可与 `device` 同时指定。传 `"default"` 清除会话级设置。UA 优先级：工具参数 > 环境变量 `BROWSER_MCP_USER_AGENT`（启动级默认值）> `device` 描述符 > 浏览器默认。与 `device` 一样，切换 UA 会重建上下文，必须在导航时一并指定；`browser_status.sessionUserAgent` / `envUserAgent` 可确认当前生效值。
+- **典型示例**：
+  ```
+  // 完整移动端仿真（视口 390x844 + iPhone UA + 触摸），会话级保持
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "iPhone 13" })
+
+  // 模拟 App 内 WebView：设备仿真 + 自定义 UA（只换 UA，视口/触摸仍按 iPhone 13）
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "iPhone 13", userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) TuwanApp/8.0.0" })
+
+  // 只调视口验证响应式断点（不改 UA / 触摸）
+  browser_resize({ width: 375, height: 812 })
+
+  // 恢复桌面模式并清除自定义 UA
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "desktop", userAgent: "default" })
+  ```
+
+## 4. 页面交互规范
 - **元素定位**：在动态页面或选择器不确定时，优先调用 `browser_get_dom` 提取当前可见的交互元素结构（包含按钮、输入框、链接及其选择器），严禁盲猜选择器。
 - **表单与按键**：表单输入调用 `browser_fill_text`（原生触发 `input` 与 `change` 事件）；键盘按键/回车提交调用 `browser_press_key`。
 - **状态排查**：排查免登异常前先调用 `browser_status` 确认 MCP 服务凭据挂载状态与当前 UID。

package/bin/mcp-server.mjs

@@ -11,7 +11,7 @@ import { resolveConfig } from "../src/config.mjs";
 import { PlaywrightBrowserManager } from "../src/browser-manager.mjs";
 import { pathToFileURL } from "node:url";
 
-export const MCP_VERSION = "0.1.11";
+export const MCP_VERSION = "0.1.12";
 
 function textResult(payload) {
   return {
@@ -38,7 +38,8 @@ export function createBrowserMcpServer({ manager, config }) {
       description:
         "使用内置 Playwright 访问目标 URL。" +
         "可显式指定 uid 选择绑定的点点账号（不传则使用默认激活账号）；" +
-        "若传 anonymous: true 则以完全未登录的游客身份访问。" +
+        "若传 anonymous: true 则以完全未登录的游客身份访问；" +
+        "移动端/H5 验收可传 device 启用完整设备仿真（视口+UA+触摸），也可单独传 userAgent 自定义 UA。" +
         "返回 HTTP 状态码、页面标题与控制台报错统计。",
       inputSchema: {
         url: z.string().describe("需要访问的目标页面 URL"),
@@ -50,6 +51,23 @@ export function createBrowserMcpServer({ manager, config }) {
           .boolean()
           .optional()
           .describe("是否以匿名/未登录状态访问（默认 false）。若为 true，则不注入任何 Cookie/storageState"),
+        device: z
+          .string()
+          .optional()
+          .describe(
+            "可选 Playwright 设备描述符名称（如 'iPhone 13'、'iPhone 15 Pro'、'Pixel 7'），启用完整移动端仿真：" +
+              "视口 + 移动 UA + isMobile + hasTouch。设置后整个会话保持该设备，后续导航无需重复传。" +
+              "传 'desktop' 恢复默认 1280x800 桌面模式。" +
+              "注意：切换设备会重建浏览器上下文（当前页面关闭后重开目标 URL，登录态自动重挂），请在导航时一并指定，不要在中途切换。",
+          ),
+        userAgent: z
+          .string()
+          .optional()
+          .describe(
+            "可选自定义 User-Agent（会话级，设置后整个会话保持，后续导航无需重复传）。" +
+              "优先级高于设备描述符自带 UA 与环境变量 BROWSER_MCP_USER_AGENT；只替换 UA 字符串，不影响视口与触摸仿真。" +
+              "传 'default' 清除会话级设置。注意：切换 UA 会重建浏览器上下文（当前页面关闭后重开目标 URL，登录态自动重挂），请在导航时一并指定。",
+          ),
         waitFor: z
           .string()
           .optional()
@@ -60,10 +78,10 @@ export function createBrowserMcpServer({ manager, config }) {
           .describe("导航与等待超时时间（毫秒），默认 15000"),
       },
     },
-    async ({ url, uid, anonymous, waitFor, timeout }) => {
+    async ({ url, uid, anonymous, device, userAgent, waitFor, timeout }) => {
       try {
         return textResult(
-          await manager.navigate({ url, uid, anonymous, waitFor, timeout }),
+          await manager.navigate({ url, uid, anonymous, device, userAgent, waitFor, timeout }),
         );
       } catch (err) {
         return errorResult("导航失败", err);
@@ -268,6 +286,27 @@ export function createBrowserMcpServer({ manager, config }) {
     },
   );
 
+  server.registerTool(
+    "browser_resize",
+    {
+      description:
+        "调整当前页面的渲染视口尺寸（对标 playwright-mcp 的 browser_resize）。" +
+        "只影响 innerWidth/innerHeight 与布局视口，不修改 UA 与触摸仿真；" +
+        "若页面按 UA 判断端别或依赖触摸事件，请改用 browser_navigate 的 device 参数做完整移动端仿真。",
+      inputSchema: {
+        width: z.number().int().positive().describe("视口宽度（像素）"),
+        height: z.number().int().positive().describe("视口高度（像素）"),
+      },
+    },
+    async ({ width, height }) => {
+      try {
+        return textResult(await manager.resize({ width, height }));
+      } catch (err) {
+        return errorResult("调整视口失败", err);
+      }
+    },
+  );
+
   server.registerTool(
     "browser_get_dom",
     {
@@ -399,6 +438,9 @@ export function createBrowserMcpServer({ manager, config }) {
         storageStateLoaded: manager.hasAuth,
         currentUid: manager.currentUid,
         isAnonymous: manager.isAnonymous,
+        device: manager.device,
+        sessionUserAgent: manager.sessionUserAgent,
+        envUserAgent: manager.userAgent,
         headless: manager.headless,
         proxyStarted: manager.whistle.started,
         proxyRule: manager.proxyRule,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taole/dd-playwright",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Standalone stdio MCP & CLI: Playwright browser automation + isolated whistle proxy + diandian account storageState injection",
   "type": "module",
   "license": "ISC",

package/src/browser-manager.mjs

@@ -4,10 +4,36 @@
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
-import { chromium } from "playwright";
+import { chromium, devices } from "playwright";
 import { ensureChromiumInstalled } from "./browser-check.mjs";
 import { WhistleProxyManager } from "./whistle-proxy.mjs";
 
+/** 桌面模式默认视口 */
+const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+
+/** 常用设备描述符示例（用于报错提示） */
+const DEVICE_EXAMPLES = ["iPhone 13", "iPhone 15 Pro", "Pixel 7", "Galaxy S9+", "iPad Mini"];
+
+/**
+ * 解析设备描述符为 newContext 选项。
+ * @param {string|null} device null/"desktop" 表示桌面模式
+ * @returns {object} context 选项（桌面模式仅含默认视口）
+ */
+function resolveDeviceOptions(device) {
+  if (!device || device === "desktop") {
+    return { viewport: DEFAULT_VIEWPORT };
+  }
+  const descriptor = devices[device];
+  if (!descriptor) {
+    throw new Error(
+      `未知设备描述符 [${device}]。取值参考 Playwright devices，例如: ${DEVICE_EXAMPLES.join(", ")}；传 "desktop" 恢复桌面模式`,
+    );
+  }
+  // 剔除仅用于 launch 的字段，其余（viewport/userAgent/isMobile/hasTouch/deviceScaleFactor 等）全量合入
+  const { defaultBrowserType, ...contextOptions } = descriptor;
+  return contextOptions;
+}
+
 /**
  * 从账号库或文件加载指定账号或激活账号的 storageState。
  * 优先级：
@@ -89,6 +115,7 @@ export class PlaywrightBrowserManager {
    * @param {boolean} [options.headless]
    * @param {string} [options.dbPath]
    * @param {string|null} [options.storageStateFile]
+   * @param {string|null} [options.userAgent] 启动级自定义 UA（环境变量），作为会话级 UA 参数的默认值
    * @param {object} [options.storageState] 直接注入，跳过自动加载
    */
   constructor({
@@ -97,9 +124,11 @@ export class PlaywrightBrowserManager {
     headless = true,
     dbPath,
     storageStateFile = null,
+    userAgent = null,
     storageState,
   } = {}) {
     this.headless = headless;
+    this.userAgent = userAgent?.trim() || null;
     this.screenshotsDir = screenshotsDir;
     this.dbPath = dbPath;
     this.storageStateFile = storageStateFile;
@@ -110,6 +139,8 @@ export class PlaywrightBrowserManager {
         : resolveStorageState({ dbPath, storageStateFile });
     this.currentUid = null;
     this.isAnonymous = false;
+    this.device = null; // 当前设备描述符名；null 表示桌面模式
+    this.sessionUserAgent = null; // 会话级 UA（工具参数设置）；null 表示回落到 this.userAgent / 设备描述符 / 默认
     this.browser = null;
     this.context = null;
     this.page = null;
@@ -154,20 +185,39 @@ export class PlaywrightBrowserManager {
 
 
   /**
-   * 根据指定的 uid 或 anonymous 状态准备浏览器上下文。
-   * @param {{uid?: string|null, anonymous?: boolean}} [authOptions]
+   * 根据指定的 uid、anonymous 状态、设备描述符与会话级 UA 准备浏览器上下文。
+   * @param {{uid?: string|null, anonymous?: boolean, device?: string|null, userAgent?: string|null}} [options]
+   *   device 不传则保持当前模式；传 "desktop"/null 恢复桌面；传 Playwright 设备名启用移动端仿真。
+   *   userAgent 不传则保持当前会话级 UA；传 "default"/null 清除会话级 UA（回落到启动配置/设备描述符/默认 UA）
    */
-  async ensurePage({ uid = null, anonymous = false } = {}) {
+  async ensurePage({ uid = null, anonymous = false, device, userAgent } = {}) {
     const targetAnonymous = Boolean(anonymous);
     const targetUid = targetAnonymous ? null : (uid ? String(uid) : null);
 
+    // 先解析并校验设备（非法设备名必须在关闭现有上下文之前抛错，避免误毁会话）
+    let targetDevice = this.device;
+    if (device !== undefined) {
+      targetDevice = !device || device === "desktop" ? null : String(device);
+      if (targetDevice) {
+        resolveDeviceOptions(targetDevice); // 仅校验，非法名抛错
+      }
+    }
+    const deviceChanged = targetDevice !== this.device;
+
+    // 解析会话级 UA（同样在任何上下文变更之前完成）
+    let targetSessionUA = this.sessionUserAgent;
+    if (userAgent !== undefined) {
+      targetSessionUA = !userAgent || userAgent === "default" ? null : String(userAgent);
+    }
+    const uaChanged = targetSessionUA !== this.sessionUserAgent;
+
     // 检查是否需要重建上下文（当前模式与目标不一致）
     const authChanged =
       this.isAnonymous !== targetAnonymous ||
       (targetUid !== null && this.currentUid !== targetUid) ||
       (targetUid === null && this.currentUid !== null && !targetAnonymous);
 
-    if (authChanged && this.context) {
+    if ((authChanged || deviceChanged || uaChanged) && this.context) {
       if (this.page && !this.page.isClosed()) {
         await this.page.close().catch(() => {});
         this.page = null;
@@ -206,10 +256,16 @@ export class PlaywrightBrowserManager {
       this.storageState = state;
       this.currentUid = targetUid;
       this.isAnonymous = targetAnonymous;
-
-      const contextOptions = {
-        viewport: { width: 1280, height: 800 },
-      };
+      this.device = targetDevice;
+      this.sessionUserAgent = targetSessionUA;
+
+      // 对标 Playwright devices 仿真：设备模式下合入 viewport/userAgent/isMobile/hasTouch 等完整描述符
+      const contextOptions = resolveDeviceOptions(targetDevice);
+      // UA 优先级：会话级（工具参数）> 启动级（环境变量）> 设备描述符 > 浏览器默认
+      const effectiveUA = this.sessionUserAgent || this.userAgent;
+      if (effectiveUA) {
+        contextOptions.userAgent = effectiveUA;
+      }
       if (state) {
         contextOptions.storageState = state;
       }
@@ -247,8 +303,8 @@ export class PlaywrightBrowserManager {
     return this.page;
   }
 
-  async navigate({ url, waitFor, timeout = 15000, uid, anonymous = false }) {
-    const page = await this.ensurePage({ uid, anonymous });
+  async navigate({ url, waitFor, timeout = 15000, uid, anonymous = false, device, userAgent }) {
+    const page = await this.ensurePage({ uid, anonymous, device, userAgent });
     const response = await page.goto(url, {
       timeout,
       waitUntil: "domcontentloaded",
@@ -491,6 +547,23 @@ export class PlaywrightBrowserManager {
     return snapshot;
   }
 
+  /**
+   * 调整当前页面渲染视口（对标 playwright-mcp 的 browser_resize）。
+   * 只影响 innerWidth/innerHeight 与布局视口，不改 UA / 触摸仿真；
+   * 完整移动端仿真请使用 navigate 的 device 参数。
+   * @param {{width: number, height: number}} params
+   */
+  async resize({ width, height }) {
+    const page = await this.ensurePage();
+    const viewport = { width: Number(width), height: Number(height) };
+    await page.setViewportSize(viewport);
+    return {
+      resized: true,
+      viewport,
+      url: page.url(),
+    };
+  }
+
   async evalJs({ script }) {
     const page = await this.ensurePage();
     const result = await page.evaluate((code) => {

package/src/config.mjs

@@ -47,6 +47,8 @@ export function resolveConfig(env = process.env) {
     domainRegex: buildDomainRegex(domainSuffix),
     headless,
     storageStateFile: env.BROWSER_MCP_STORAGE_STATE?.trim() || null,
+    // 启动级自定义 UA；设置后覆盖默认桌面 UA 与 device 设备描述符自带的 UA
+    userAgent: env.BROWSER_MCP_USER_AGENT?.trim() || null,
   };
 }
 

package/src/server/web-server.mjs

@@ -390,7 +390,11 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
               &nbsp;&nbsp;3) 静态替换：<code>act.tuwan.com/cdn/index.js D:/dist/index.js</code><br>
               &nbsp;&nbsp;4) 请求头注入：<code>y.tuwan.com reqHeaders://{debug: '1'}</code><br>
               &nbsp;&nbsp;👉 官方完整语法参考：<a href="https://wproxy.org/whistle/rules/" target="_blank" style="color: #38bdf8; text-decoration: underline;">https://wproxy.org/whistle/rules/</a><br><br>
-            <b>3. 页面交互规范：</b><br>
+            <b>3. 设备与视口仿真（移动端/H5 验收）：</b><br>
+            • 移动端验收在导航时传 <code>device</code>（如 <code>"iPhone 13"</code>）启用完整仿真：移动视口 + 移动 UA + 触摸；传 <code>"desktop"</code> 恢复桌面。<br>
+            • 自定义 UA 传 <code>userAgent</code>（会话级保持，可与 device 叠加，传 <code>"default"</code> 清除）。<br>
+            • 只调视口用 <code>browser_resize({ width, height })</code>；页面内 <code>window.resizeTo</code> 对 Playwright 视口无效。<br><br>
+            <b>4. 页面交互规范：</b><br>
             • 复杂或动态页面定位困难时，优先调用 <code>browser_get_dom</code> 获取可见元素清单，严禁盲猜选择器。<br>
             • 表单填写使用 <code>browser_fill_text</code>，按键使用 <code>browser_press_key</code>。
           </div>
@@ -434,6 +438,19 @@ browser_press_key({ selector: "input#keyword", key: "Enter" })
 // 3. 结果截图与控制台报错收集
 browser_screenshot({ selector: ".result-box" })
 const errors = browser_get_console_errors()</div>
+
+          <div class="code-title"><span>流程 4：移动端 / H5 仿真验收（设备 · UA · 视口）</span></div>
+          <div class="code-block" style="color: #93c5fd; font-size: 12px; margin-bottom: 0;">// 1. 完整移动端仿真：视口 390x844 + iPhone UA + 触摸，会话级保持
+browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "iPhone 13" })
+
+// 2. 模拟 App 内 WebView：设备仿真 + 自定义 UA（只换 UA，视口/触摸仍按 iPhone 13）
+browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "iPhone 13", userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) TuwanApp/8.0.0" })
+
+// 3. 只调视口验证响应式断点（不改 UA / 触摸）
+browser_resize({ width: 375, height: 812 })
+
+// 4. 恢复桌面模式并清除自定义 UA
+browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "desktop", userAgent: "default" })</div>
         </div>
       </div>
     </div>