@taole/dd-playwright 0.1.6 → 0.1.8

package/README.md

@@ -3,6 +3,7 @@
 增强型 stdio MCP 服务与 CLI 工具：Playwright 浏览器自动化 + 隔离 whistle 代理 + 点点账号 storageState 免登注入。
 可挂载到任意 AI 客户端（omp / Cursor / Claude Desktop / Codex 等）使用，不依赖任何特定宿主项目。
 
+> 📖 **团队知识库与使用手册**：[dd-playwright 钉钉在线文档](https://alidocs.dingtalk.com/i/nodes/14lgGw3P8vL9wkv1FnOLZAlkV5daZ90D?utm_scene=person_space)（持续同步最新工具契约与最佳实践）
 ## 能力
 
 | 工具 | 说明 |
@@ -19,6 +20,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 +32,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` 与截图目录），无需手动设置环境变量。
@@ -72,6 +65,9 @@ dd-pw statusweb
 # 停止后台运行的服务：
 dd-pw stopweb
 
+# 一键检查并升级到最新版本：
+dd-pw update
+
 # （可选）前台阻塞运行（Ctrl+C 退出）：
 dd-pw serve [--port 12309]
 ```

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/cli.mjs

@@ -7,6 +7,7 @@ import {
   stopWebDaemon,
   getWebDaemonStatus,
 } from "../src/server/daemon.mjs";
+import { handleUpdateCommand } from "../src/updater.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -20,6 +21,7 @@ dd-playwright (别名: dd-pw) CLI
   dd-pw stopweb                        停止后台运行的 Web 控制台
   dd-pw statusweb                      查看后台 Web 控制台运行状态与端口
   dd-pw serve [--port 12309]           前台阻塞启动 Web 控制台（按 Ctrl+C 退出）
+  dd-pw update                         检查远端最新版本并自动升级
   dd-pw mcp                            以 stdio 模式启动 MCP 浏览器服务
   dd-pw --help, -h                     查看帮助信息
 
@@ -158,6 +160,8 @@ async function main() {
       console.error(`[dd-playwright] 启动失败:`, err);
       process.exit(1);
     }
+  } else if (command === "update" || command === "upgrade") {
+    await handleUpdateCommand();
   } else if (command === "mcp") {
     // 转发至 mcp-server.mjs
     await import("./mcp-server.mjs");

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.8";
 
 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.8",
   "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/updater.mjs

@@ -0,0 +1,111 @@
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+export const PACKAGE_NAME = "@taole/dd-playwright";
+
+/**
+ * 比较两个语义化版本号 (semver)
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {number} 1: v1 > v2; -1: v1 < v2; 0: v1 == v2
+ */
+export function compareSemver(v1, v2) {
+  const parse = (v) =>
+    (v || "")
+      .replace(/^v/i, "")
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+
+  const [maj1, min1, pat1] = parse(v1);
+  const [maj2, min2, pat2] = parse(v2);
+
+  if (maj1 !== maj2) return maj1 > maj2 ? 1 : -1;
+  if (min1 !== min2) return min1 > min2 ? 1 : -1;
+  if (pat1 !== pat2) return pat1 > pat2 ? 1 : -1;
+  return 0;
+}
+
+/**
+ * 获取本地安装的版本号
+ * @returns {string}
+ */
+export function getLocalVersion() {
+  try {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/**
+ * 查询 NPM 远端最新版本号
+ * @returns {Promise<string|null>}
+ */
+export async function getRemoteLatestVersion() {
+  const registries = [
+    "https://registry.npmjs.org/",
+    "https://registry.npmmirror.com/",
+  ];
+
+  for (const reg of registries) {
+    try {
+      const url = `${reg}${PACKAGE_NAME}/latest`;
+      const res = await fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(4000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        if (data.version) return data.version;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * 执行 update 命令核心流程
+ */
+export async function handleUpdateCommand(overrideCurrentVersion = null) {
+  const currentVersion = overrideCurrentVersion || getLocalVersion();
+  console.log(`[dd-playwright] 正在检查 npm 远端最新版本...`);
+
+  const latestVersion = await getRemoteLatestVersion();
+  if (!latestVersion) {
+    console.warn(`[dd-playwright] 无法连接到 npm 注册表查询最新版本，请检查网络。`);
+    console.log(`您可直接尝试执行手动更新命令：\n  npm install -g ${PACKAGE_NAME}@latest\n`);
+    return;
+  }
+
+  const cmp = compareSemver(latestVersion, currentVersion);
+  if (cmp <= 0) {
+    console.log(`🎉 恭喜！当前已是最新版本 (v${currentVersion})，无需更新。\n`);
+    return;
+  }
+
+  console.log(`\n==================================================`);
+  console.log(`  🚀 发现新版本可用: v${currentVersion} -> v${latestVersion}`);
+  console.log(`==================================================\n`);
+
+  console.log(`[dd-playwright] 正在尝试自动执行全局升级 (npm install -g ${PACKAGE_NAME}@latest)...`);
+
+  try {
+    // 优先尝试自动升级
+    execSync(`npm install -g ${PACKAGE_NAME}@latest`, {
+      stdio: "inherit",
+      windowsHide: true,
+    });
+    console.log(`\n🎉 自动更新完成！已成功升级至最新版本 v${latestVersion}。\n`);
+    console.log(`提示：若当前后台正在运行 Web 服务，建议重启生效：`);
+    console.log(`  dd-pw stopweb && dd-pw startweb\n`);
+  } catch (err) {
+    // 若因系统权限不足等原因报错，优雅降级，打印完整手工升级命令
+    console.warn(`\n⚠️ 自动升级未完成（可能需要管理员权限或当前终端权限受限）。`);
+    console.log(`请复制下方命令并在终端中执行升级：\n`);
+    console.log(`👉  npm install -g ${PACKAGE_NAME}@latest\n`);
+  }
+}

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 启动参数。