@taole/dd-playwright 0.1.6 → 0.1.7

package/README.md

@@ -19,6 +19,7 @@
 | `browser_get_dom` | 提取当前页面的结构化可交互 DOM 树（按钮/链接/输入框及其选择器），免去盲猜 |
 | `browser_eval_js` | 页面上下文执行 JS |
 | `browser_set_proxy_rule` | 声明「本地 dev server → 干净 `*.tuwan.com` 域名」映射，隔离 whistle 代理自动托管 |
+| `browser_load_proxy_rules_dir` | 批量加载项目规则目录（如 `.whistle-rules`），全量注入并激活域名映射与 Mock 规则 |
 | `browser_status` | 查询登录态挂载情况、当前 UID、代理状态、数据目录，排查免登问题先调它 |
 
 ## 安装与挂载
@@ -30,20 +31,11 @@ npm install
 npx playwright install chromium
 ```
 
-MCP 客户端配置（以 omp / Cursor / Claude 为例）：
-
-```json
-{
-  "mcpServers": {
-    "dd-playwright": {
-      "command": "dd-playwright-mcp"
-    }
-  }
-}
-```
-
-或者直接指向本地入口：`node D:/tools/dd-browser-mcp/bin/mcp-server.mjs`
+### MCP 客户端挂载配置
 
+启动后台控制台后，直接在浏览器打开 **`http://127.0.0.1:12309`**：
+- 切换到 **「MCP 客户端配置」** 选项卡。
+- 页面会自动根据你当前的系统与安装路径生成准确的配置 JSON，支持**一键复制**或**一键安装到 Cursor**，开箱即用，无需手动拼接路径。
 ## 数据与配置
 
 - **数据目录**：默认自动固定为 `~/.dd-browser-mcp`（账号库 `runtime.db` 与截图目录），无需手动设置环境变量。

package/SKILL.md

@@ -17,10 +17,19 @@ description: >-
 ## 2. 本地开发服务联调（Dev Server 代理映射）
 - 当本地启动了前端开发服务器（如 Vite/Webpack 监听本地端口）时，**严禁修改系统 hosts**。
 - 必须先调用本 MCP 的 `browser_set_proxy_rule` 将本地端口映射到合法的点点子域名（子域名不要求在线上真实存在，支持任意自定义前缀）。
-- **示例**：
+- **单域名映射示例**：
   - 本地 dev server 运行在 `127.0.0.1:9527` 时，可映射为自定义域名 `p9527-test.tuwan.com`：
     `browser_set_proxy_rule({ domain: "p9527-test.tuwan.com", port: 9527 })`
   - 随后调用 `browser_navigate({ url: "http://p9527-test.tuwan.com/" })` 访问，进程内隔离 Whistle 代理会自动转发流量并正确携带点点线上 Cookie。
+- **项目规则目录批量加载（推荐）**：
+  - 若项目中存在 `.whistle-rules` 等包含多份代理/Mock 规则文件的目录，直接调用 `browser_load_proxy_rules_dir({ rulesDir: "绝对路径" })` 全量注入激活。
+
+### 附：常用 Whistle 规则语法参考（编写 .whistle-rules 目录时）
+1. **域名与端口映射**：`p9527-test.tuwan.com http://127.0.0.1:9527`
+2. **接口 Mock / 响应替换**：`yapi.tuwan.com/act resBody://D:/mock/data.json`
+3. **静态资源替换**：`act.tuwan.com/cdn/index.js D:/dist/index.js`
+4. **请求头注入**：`y.tuwan.com reqHeaders://{debug: '1'}`
+> 更多高级协议与规则参考官方文档：https://wproxy.org/whistle/rules/
 
 ## 3. 页面交互规范
 - **元素定位**：在动态页面或选择器不确定时，优先调用 `browser_get_dom` 提取当前可见的交互元素结构（包含按钮、输入框、链接及其选择器），严禁盲猜选择器。

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.6";
+export const MCP_VERSION = "0.1.7";
 
 function textResult(payload) {
   return {
@@ -336,6 +336,37 @@ export function createBrowserMcpServer({ manager, config }) {
       }
     },
   );
+  server.registerTool(
+    "browser_load_proxy_rules_dir",
+    {
+      description:
+        "从指定本地目录批量加载 Whistle 规则文件（如项目的 .whistle-rules 目录），将其全量注入并激活到进程内 Whistle 代理中。" +
+        "支持目录下包含多个 .rule / .txt / .whistle 文件（如域名端口映射、Mock 接口 resBody、静态资源重定向等）。" +
+        "调用后浏览器会自动重启连接以加载新规则。",
+      inputSchema: {
+        rulesDir: z
+          .string()
+          .describe("包含 Whistle 规则文件的本地绝对路径目录"),
+        clearExisting: z
+          .boolean()
+          .optional()
+          .describe("是否清空已有的旧规则，默认 false（增量合并注入）"),
+      },
+    },
+    async ({ rulesDir, clearExisting = false }) => {
+      try {
+        const res = await manager.loadProxyRulesDir({ rulesDir, clearExisting });
+        return textResult({
+          success: true,
+          message: `已成功加载目录规则：${rulesDir}`,
+          ...res,
+        });
+      } catch (err) {
+        return errorResult("加载目录代理规则失败", err);
+      }
+    },
+  );
+
 
   server.registerTool(
     "browser_eval_js",

package/package.json

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

package/src/browser-manager.mjs

@@ -140,6 +140,18 @@ export class PlaywrightBrowserManager {
     await this._closeBrowserOnly();
     return this.proxyRule;
   }
+  /**
+   * 从指定目录批量加载 Whistle 规则并重启浏览器加载规则。
+   * @param {{rulesDir: string, clearExisting?: boolean}} params
+   */
+  async loadProxyRulesDir({ rulesDir, clearExisting = false }) {
+    const whistle = await this.ensureProxy();
+    const result = await whistle.loadRulesFromDirectory(rulesDir, { clearExisting });
+    // 重启浏览器以清除连接与 DNS 缓存，确保新规则立即生效
+    await this._closeBrowserOnly();
+    return result;
+  }
+
 
   /**
    * 根据指定的 uid 或 anonymous 状态准备浏览器上下文。

package/src/server/web-server.mjs

@@ -381,10 +381,9 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
             • 访问点点业务页面必须调用本 MCP 的 <code>browser_navigate</code> 工具，自动注入当前激活账号的 storageState（含 <code>Tuwan_Passport</code> 鉴权 Cookie）免登。<br>
             • 多角色或指定账号测试时传入特定 <code>uid</code>，自动隔离并重建独立浏览器上下文。<br><br>
             <b>2. 本地开发服务联调（Dev Server 代理映射）：</b><br>
-            • 本地服务启动后严禁改动系统 hosts，必须先调用 <code>browser_set_proxy_rule</code> 映射到点点子域名。<br>
-            • <b>示例</b>：本地 dev server 运行在 <code>127.0.0.1:9527</code> 时，可映射为自定义域名 <code>p9527-test.tuwan.com</code>（域名无需线上真实存在）：<br>
-              <code style="color: #38bdf8;">browser_set_proxy_rule({ domain: "p9527-test.tuwan.com", port: 9527 })</code><br>
-              随后访问该域名，内部隔离 Whistle 代理会自动转发流量并正确携带线上 Cookie。<br><br>
+            • 本地服务启动后严禁改动系统 hosts，可通过单域名映射或项目规则目录全量注入：<br>
+            • <b>单条映射</b>：<code>browser_set_proxy_rule({ domain: "p9527-test.tuwan.com", port: 9527 })</code><br>
+            • <b>目录批量规则（推荐）</b>：若项目有 <code>.whistle-rules</code> 目录，直接调用 <code>browser_load_proxy_rules_dir({ rulesDir: "目录绝对路径" })</code> 全量激活代理与 Mock。<br><br>
             <b>3. 页面交互规范：</b><br>
             • 复杂或动态页面定位困难时，优先调用 <code>browser_get_dom</code> 获取可见元素清单，严禁盲猜选择器。<br>
             • 表单填写使用 <code>browser_fill_text</code>，按键使用 <code>browser_press_key</code>。
@@ -742,18 +741,6 @@ export function createWebServer({ accountStore, authManager }) {
         new URL("../../bin/mcp-server.mjs", import.meta.url),
       ).replaceAll("\\", "/");
 
-      const globalConfigStr = JSON.stringify(
-        {
-          mcpServers: {
-            "dd-playwright": {
-              command: "dd-playwright-mcp",
-            },
-          },
-        },
-        null,
-        2,
-      );
-
       const localConfigStr = JSON.stringify(
         {
           mcpServers: {

package/src/whistle-proxy.mjs

@@ -8,9 +8,18 @@
  *   - 仅监听 127.0.0.1，不对外暴露
  *   - 域名后缀限制可声明规则；启用后浏览器流量均经代理转发
  */
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import {
+  mkdtempSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, extname } from "node:path";
 import { createRequire } from "node:module";
 
 let startWhistleFn = null;
@@ -169,6 +178,103 @@ export class WhistleProxyManager {
     const url = protocol === "https" ? `https://${domain}/` : `http://${domain}/`;
     return { url, rule: ruleText };
   }
+  /**
+   * 从指定目录加载 Whistle 规则文件并全量激活。
+   * @param {string} rulesDir 规则文件所在的本地绝对路径
+   * @param {{clearExisting?: boolean}} [options] 是否清空已有的旧规则（默认 false，增量覆盖）
+   * @returns {Promise<{success: boolean, loadedFiles: string[], totalRulesCount: number, rulesSummary: string}>}
+   */
+  async loadRulesFromDirectory(rulesDir, { clearExisting = false } = {}) {
+    if (!this.started) {
+      throw new Error("Whistle proxy not started. Call start() first.");
+    }
+    if (!rulesDir || typeof rulesDir !== "string") {
+      throw new Error("必须提供有效的 rulesDir 路径");
+    }
+    if (!existsSync(rulesDir) || !statSync(rulesDir).isDirectory()) {
+      throw new Error(`目标路径不存在或不是有效目录: ${rulesDir}`);
+    }
+
+    const entries = readdirSync(rulesDir);
+    const loadedFiles = [];
+    const collectedRuleLines = [];
+
+    for (const file of entries) {
+      const fullPath = join(rulesDir, file);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) continue;
+
+        // 读取文本文件内容
+        const content = readFileSync(fullPath, "utf8").trim();
+        if (!content) continue;
+
+        loadedFiles.push(file);
+        collectedRuleLines.push(`# === From File: ${file} ===`);
+        collectedRuleLines.push(content);
+        collectedRuleLines.push("");
+      } catch {}
+    }
+
+    if (loadedFiles.length === 0) {
+      return {
+        success: true,
+        loadedFiles: [],
+        totalRulesCount: 0,
+        rulesSummary: "目录中未发现可读的规则文件",
+      };
+    }
+
+    let finalRulesText = collectedRuleLines.join("\n");
+
+    // 如果不需要清空已有规则，读取当前 default 规则合并
+    if (!clearExisting) {
+      try {
+        const listRes = await fetch(
+          `http://127.0.0.1:${this.port}/cgi-bin/rules/list`,
+        );
+        const listData = await listRes.json();
+        const currentDefault = listData.list?.find((r) => r.name === "default")?.data || "";
+        if (currentDefault.trim()) {
+          finalRulesText = `${currentDefault.trim()}\n\n${finalRulesText}`;
+        }
+      } catch {}
+    }
+
+    // 通过 WebUI CGI 写入 default 规则并激活
+    const res = await fetch(
+      `http://127.0.0.1:${this.port}/cgi-bin/rules/select`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          name: "default",
+          value: finalRulesText,
+        }).toString(),
+      },
+    );
+
+    if (!res.ok) {
+      throw new Error(`Failed to set directory whistle rules: HTTP ${res.status}`);
+    }
+    const result = await res.json();
+    if (result.ec !== 0) {
+      throw new Error(`Failed to set whistle rules: ${JSON.stringify(result)}`);
+    }
+
+    const nonCommentRules = finalRulesText
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"));
+
+    return {
+      success: true,
+      loadedFiles,
+      totalRulesCount: nonCommentRules.length,
+      rulesSummary: finalRulesText,
+    };
+  }
+
 
   /**
    * 浏览器应使用的 Chromium 启动参数。