@taole/dd-playwright 0.0.0-stage → 0.1.1

package/bin/mcp-server.mjs

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+/**
+ * stdio MCP: 独立 Playwright 浏览器自动化服务。
+ * 自动注入 SQLite 中激活的点点测试账号 storageState，托管隔离 whistle 代理。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { resolveConfig } from "../src/config.mjs";
+import { PlaywrightBrowserManager } from "../src/browser-manager.mjs";
+import { pathToFileURL } from "node:url";
+
+export const MCP_VERSION = "0.1.1";
+
+function textResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+function errorResult(prefix, err) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${prefix}: ${err.message}` }],
+  };
+}
+
+export function createBrowserMcpServer({ manager, config }) {
+  const server = new McpServer({
+    name: "dd-playwright",
+    version: MCP_VERSION,
+  });
+
+  server.registerTool(
+    "browser_navigate",
+    {
+      description:
+        "使用内置 Playwright 访问目标 URL。" +
+        "可显式指定 uid 选择绑定的点点账号（不传则使用默认激活账号）；" +
+        "若传 anonymous: true 则以完全未登录的游客身份访问。" +
+        "返回 HTTP 状态码、页面标题与控制台报错统计。",
+      inputSchema: {
+        url: z.string().describe("需要访问的目标页面 URL"),
+        uid: z
+          .string()
+          .optional()
+          .describe("显式指定的点点账号 UID。若不传，则默认使用当前激活账号"),
+        anonymous: z
+          .boolean()
+          .optional()
+          .describe("是否以匿名/未登录状态访问（默认 false）。若为 true，则不注入任何 Cookie/storageState"),
+        waitFor: z
+          .string()
+          .optional()
+          .describe("可选等待的目标 DOM 选择器（CSS 或 XPath）"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("导航与等待超时时间（毫秒），默认 15000"),
+      },
+    },
+    async ({ url, uid, anonymous, waitFor, timeout }) => {
+      try {
+        return textResult(
+          await manager.navigate({ url, uid, anonymous, waitFor, timeout }),
+        );
+      } catch (err) {
+        return errorResult("导航失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_screenshot",
+    {
+      description:
+        "截取当前页面或指定元素截图，落盘至 BROWSER_MCP_DATA_DIR/screenshots，返回本地文件路径。",
+      inputSchema: {
+        selector: z
+          .string()
+          .optional()
+          .describe("可选选择器，仅对该元素截图；留空则截取视口或全页面"),
+        fullPage: z
+          .boolean()
+          .optional()
+          .describe("是否截取整页滚动长图，默认 false"),
+      },
+    },
+    async ({ selector, fullPage }) => {
+      try {
+        return textResult(await manager.screenshot({ selector, fullPage }));
+      } catch (err) {
+        return errorResult("截图失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_get_console_errors",
+    {
+      description:
+        "获取自页面导航以来的所有 console.error 和未捕获异常日志，用于验证前端脚本是否存在运行时报错。",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        return textResult(manager.getConsoleErrors());
+      } catch (err) {
+        return errorResult("获取控制台错误失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_click_element",
+    {
+      description:
+        "在页面中模拟点击指定 DOM 选择器的元素（如按钮、Tab、确认框）。",
+      inputSchema: {
+        selector: z
+          .string()
+          .describe("需要点击的目标元素 CSS 或 XPath 选择器"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("等待元素并点击的超时时间（毫秒），默认 10000"),
+      },
+    },
+    async ({ selector, timeout }) => {
+      try {
+        return textResult(await manager.clickElement({ selector, timeout }));
+      } catch (err) {
+        return errorResult("点击元素失败", err);
+      }
+    },
+  );
+  server.registerTool(
+    "browser_fill_text",
+    {
+      description:
+        "在指定 DOM 选择器的输入框（input、textarea）中填入文本，原生触发 input 与 change 事件。",
+      inputSchema: {
+        selector: z.string().describe("目标输入框的 CSS 或 XPath 选择器"),
+        text: z.string().describe("需要输入的文本内容"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("等待元素并填写的超时时间（毫秒），默认 10000"),
+      },
+    },
+    async ({ selector, text, timeout }) => {
+      try {
+        return textResult(await manager.fillText({ selector, text, timeout }));
+      } catch (err) {
+        return errorResult("填写文本失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_press_key",
+    {
+      description:
+        "模拟键盘按键（如 Enter、Tab、Escape、Backspace、ArrowDown 等），可聚焦特定元素按键或向全局页面按键。",
+      inputSchema: {
+        key: z
+          .string()
+          .describe(
+            "键盘按键名称，如 'Enter'、'Tab'、'Escape'、'Backspace'、'Control+A' 等",
+          ),
+        selector: z
+          .string()
+          .optional()
+          .describe("可选目标元素选择器；若提供则先聚焦该元素再按键"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("等待元素的超时时间（毫秒），默认 10000"),
+      },
+    },
+    async ({ key, selector, timeout }) => {
+      try {
+        return textResult(await manager.pressKey({ key, selector, timeout }));
+      } catch (err) {
+        return errorResult("键盘按键失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_hover",
+    {
+      description:
+        "将鼠标光标悬停在指定 DOM 元素上，触发 hover 状态、下拉菜单或 Tooltip 浮层。",
+      inputSchema: {
+        selector: z.string().describe("需要悬停的目标元素 CSS 或 XPath 选择器"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("等待元素并悬停的超时时间（毫秒），默认 10000"),
+      },
+    },
+    async ({ selector, timeout }) => {
+      try {
+        return textResult(await manager.hover({ selector, timeout }));
+      } catch (err) {
+        return errorResult("悬停元素失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_scroll",
+    {
+      description:
+        "滚动页面视口或滚动特定元素使其进入视图（如触底加载更多、翻页）。",
+      inputSchema: {
+        direction: z
+          .enum(["down", "up"])
+          .optional()
+          .describe("视口滚动方向，默认 'down'"),
+        deltaY: z
+          .number()
+          .optional()
+          .describe("精确滚动像素高度，正数向下，负数向上；若指定则优先于 direction"),
+        selector: z
+          .string()
+          .optional()
+          .describe("可选目标元素选择器；若提供则滚动该元素进入当前视口"),
+      },
+    },
+    async ({ direction, deltaY, selector }) => {
+      try {
+        return textResult(await manager.scroll({ direction, deltaY, selector }));
+      } catch (err) {
+        return errorResult("页面滚动失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_wait_for",
+    {
+      description:
+        "等待页面特定状态（如网络空闲 load/networkidle）或等待特定 DOM 元素出现/消失。",
+      inputSchema: {
+        selector: z
+          .string()
+          .optional()
+          .describe("可选等待的目标 DOM 选择器；留空则等待整页状态"),
+        state: z
+          .enum(["visible", "hidden", "attached", "detached"])
+          .optional()
+          .describe("元素等待状态，默认 'visible'"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("等待超时时间（毫秒），默认 15000"),
+      },
+    },
+    async ({ selector, state, timeout }) => {
+      try {
+        return textResult(await manager.waitFor({ selector, state, timeout }));
+      } catch (err) {
+        return errorResult("等待超时或失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_get_dom",
+    {
+      description:
+        "获取当前页面的结构化可交互 DOM 树（包含链接、按钮、输入框、下拉框等交互元素的文本和对应选择器），方便 AI Agent 精准定位元素，免去盲猜选择器或截大图肉眼识别。",
+      inputSchema: {
+        interactiveOnly: z
+          .boolean()
+          .optional()
+          .describe("是否仅提取可交互元素（按钮、输入框、链接等），默认 true"),
+        maxDepth: z
+          .number()
+          .optional()
+          .describe("DOM 遍历最大深度，默认 10"),
+      },
+    },
+    async ({ interactiveOnly, maxDepth }) => {
+      try {
+        return textResult(
+          await manager.getDom({ interactiveOnly, maxDepth }),
+        );
+      } catch (err) {
+        return errorResult("获取页面 DOM 失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_set_proxy_rule",
+    {
+      description:
+        `声明域名映射规则：将本地 dev server 映射到一个 *.${config.domainSuffix} 子域名。` +
+        "本地端口由你自行发现（读取项目 vite.config.js / package.json / dev 启动日志）。" +
+        "域名前缀由你决定：包含 -test / -dev / -local 任一后缀即可触发域名类测试环境判定；" +
+        "例外是 ChatRoomSvelteNew 项目，必须用白名单域名 y-dev.tuwan.com 或 y-test.tuwan.com（y-slt-test 同属白名单）且访问 URL 带 ?env=1。" +
+        "例如：xdd-test.tuwan.com -> 127.0.0.1:5173 之后，浏览器访问 https://xdd-test.tuwan.com/ 即可，" +
+        "无需在 URL 中携带本地端口，MAIN_DOMAIN 推导结果干净。" +
+        "注意：调用此工具后浏览器会自动重启以加载新规则。",
+      inputSchema: {
+        domain: z
+          .string()
+          .describe(
+            `目标域名，必须是 *.${config.domainSuffix} 子域名（如 xdd-test.${config.domainSuffix}）`,
+          ),
+        port: z
+          .number()
+          .int()
+          .positive()
+          .describe("本地 dev server 监听的端口号"),
+        protocol: z
+          .enum(["http", "https"])
+          .optional()
+          .describe("本地 dev server 使用的协议，默认 http"),
+      },
+    },
+    async ({ domain, port, protocol = "http" }) => {
+      try {
+        const res = await manager.setProxyRule({ domain, port, protocol });
+        return textResult({
+          success: true,
+          message: `域名映射已生效。浏览器访问 ${res.url} 即可。`,
+          ...res,
+        });
+      } catch (err) {
+        return errorResult("设置代理规则失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_eval_js",
+    {
+      description:
+        "在页面上下文执行 JavaScript 表达式并返回结果，用于断言全局变量、计算样式或页面状态。",
+      inputSchema: {
+        script: z.string().describe("要在页面内执行的 JS 脚本或表达式"),
+      },
+    },
+    async ({ script }) => {
+      try {
+        return textResult(await manager.evalJs({ script }));
+      } catch (err) {
+        return errorResult("执行 JS 失败", err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "browser_status",
+    {
+      description:
+        "查询服务当前状态：当前使用的点点 UID/激活状态、storageState 是否已加载、代理规则、数据目录。排查免登未生效时先调用此工具。",
+      inputSchema: {},
+    },
+    async () => {
+      return textResult({
+        version: MCP_VERSION,
+        storageStateLoaded: manager.hasAuth,
+        currentUid: manager.currentUid,
+        isAnonymous: manager.isAnonymous,
+        headless: manager.headless,
+        proxyStarted: manager.whistle.started,
+        proxyRule: manager.proxyRule,
+        dataDir: config.dataDir,
+        domainSuffix: config.domainSuffix,
+      });
+    },
+  );
+  return server;
+}
+
+async function main() {
+  const config = resolveConfig();
+  const manager = new PlaywrightBrowserManager(config);
+  const server = createBrowserMcpServer({ manager, config });
+  const transport = new StdioServerTransport();
+
+  let closing;
+  const shutdown = (reason) => {
+    closing ??= (async () => {
+      await server.close();
+      await manager.close();
+      // whistle 内部后台定时器（数据 GC 等）没有公开停止接口，
+      // 清理完成后主动退出，避免代理在客户端断开后存活
+      process.exit(process.exitCode || 0);
+    })().catch((err) => {
+      console.error("dd-browser-mcp 资源清理失败:", err);
+      process.exit(1);
+    });
+    return closing;
+  };
+  process.stdin.once("end", () => shutdown("stdin end"));
+  process.once("SIGINT", () => shutdown("SIGINT"));
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
+
+  await server.connect(transport);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((err) => {
+    console.error("dd-browser-mcp 服务启动失败:", err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@taole/dd-playwright",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Standalone stdio MCP & CLI: Playwright browser automation + isolated whistle proxy + diandian account storageState injection",
+  "type": "module",
+  "license": "ISC",
+  "bin": {
+    "dd-playwright": "bin/cli.mjs",
+    "dd-pw": "bin/cli.mjs",
+    "dd-playwright-mcp": "bin/mcp-server.mjs",
+    "dd-browser": "bin/cli.mjs",
+    "dd-browser-mcp": "bin/mcp-server.mjs"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "playwright": "1.64.1",
+    "whistle": "2.10.11",
+    "zod": "4.6.7"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md"
+  ]
+}

package/src/account-store.mjs

@@ -0,0 +1,234 @@
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export class AccountStore {
+  /**
+   * @param {string} dbPath SQLite 数据库绝对路径
+   */
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    const dir = dirname(dbPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    this.db = new DatabaseSync(dbPath);
+    this._initSchema();
+  }
+
+  _initSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS diandian_accounts (
+        account_id TEXT PRIMARY KEY,
+        nickname TEXT NOT NULL,
+        avatar TEXT,
+        cookie_header TEXT NOT NULL,
+        storage_state TEXT NOT NULL,
+        is_active INTEGER NOT NULL DEFAULT 1,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS app_settings (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `);
+  }
+
+  getSetting(key, defaultValue = null) {
+    const row = this.db
+      .prepare("SELECT value FROM app_settings WHERE key = ?")
+      .get(String(key));
+    if (!row) return defaultValue;
+    try {
+      return JSON.parse(row.value);
+    } catch {
+      return row.value;
+    }
+  }
+
+  setSetting(key, value) {
+    const now = new Date().toISOString();
+    const raw = typeof value === "string" ? JSON.stringify(value) : JSON.stringify(value);
+    this.db
+      .prepare(`
+        INSERT INTO app_settings (key, value, updated_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+          value = excluded.value,
+          updated_at = excluded.updated_at
+      `)
+      .run(String(key), raw, now);
+    return value;
+  }
+  listAccounts() {
+    const rows = this.db
+      .prepare(
+        "SELECT account_id, nickname, avatar, cookie_header, is_active, created_at, updated_at FROM diandian_accounts ORDER BY is_active DESC, updated_at DESC",
+      )
+      .all();
+    return rows.map((r) => ({
+      accountId: r.account_id,
+      nickname: r.nickname,
+      avatar: r.avatar,
+      cookieHeader: r.cookie_header,
+      isActive: Boolean(r.is_active),
+      createdAt: r.created_at,
+      updatedAt: r.updated_at,
+    }));
+  }
+
+  getActiveAccount() {
+    const row = this.db
+      .prepare(
+        "SELECT account_id, nickname, avatar, cookie_header, storage_state, is_active, created_at, updated_at FROM diandian_accounts WHERE is_active = 1 LIMIT 1",
+      )
+      .get();
+    if (!row) return null;
+    let storageState = null;
+    try {
+      storageState = JSON.parse(row.storage_state);
+    } catch {}
+    return {
+      accountId: row.account_id,
+      nickname: row.nickname,
+      avatar: row.avatar,
+      cookieHeader: row.cookie_header,
+      storageState,
+      isActive: true,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+
+  getAccount(accountId) {
+    if (!accountId) return null;
+    const row = this.db
+      .prepare(
+        "SELECT account_id, nickname, avatar, cookie_header, storage_state, is_active, created_at, updated_at FROM diandian_accounts WHERE account_id = ?",
+      )
+      .get(String(accountId));
+    if (!row) return null;
+    let storageState = null;
+    try {
+      storageState = JSON.parse(row.storage_state);
+    } catch {}
+    return {
+      accountId: row.account_id,
+      nickname: row.nickname,
+      avatar: row.avatar,
+      cookieHeader: row.cookie_header,
+      storageState,
+      isActive: Boolean(row.is_active),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+
+  saveAccount({
+    accountId,
+    nickname = "点点用户",
+    avatar = "",
+    cookieHeader = "",
+    storageState = {},
+    isActive = true,
+  } = {}) {
+    const id = String(accountId || "").trim();
+    if (!id) {
+      throw new Error("保存点点账号必须提供有效 accountId");
+    }
+    const now = new Date().toISOString();
+    const rawStorage =
+      typeof storageState === "string"
+        ? storageState
+        : JSON.stringify(storageState || {});
+
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      if (isActive) {
+        this.db.prepare("UPDATE diandian_accounts SET is_active = 0").run();
+      }
+      this.db
+        .prepare(`
+          INSERT INTO diandian_accounts (account_id, nickname, avatar, cookie_header, storage_state, is_active, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(account_id) DO UPDATE SET
+            nickname = excluded.nickname,
+            avatar = excluded.avatar,
+            cookie_header = excluded.cookie_header,
+            storage_state = excluded.storage_state,
+            is_active = excluded.is_active,
+            updated_at = excluded.updated_at
+        `)
+        .run(
+          id,
+          String(nickname || "点点用户"),
+          avatar || "",
+          String(cookieHeader || ""),
+          rawStorage,
+          isActive ? 1 : 0,
+          now,
+          now,
+        );
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+
+    return this.getAccount(id);
+  }
+
+  setActiveAccount(accountId) {
+    if (!accountId) return;
+    const id = String(accountId);
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db
+        .prepare(
+          "UPDATE diandian_accounts SET is_active = CASE WHEN account_id = ? THEN 1 ELSE 0 END",
+        )
+        .run(id);
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  deleteAccount(accountId) {
+    if (!accountId) return;
+    const id = String(accountId);
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const target = this.getAccount(id);
+      this.db
+        .prepare("DELETE FROM diandian_accounts WHERE account_id = ?")
+        .run(id);
+      if (target?.isActive) {
+        // 如果删除了激活账号，将最近更新的账号激活
+        const next = this.db
+          .prepare(
+            "SELECT account_id FROM diandian_accounts ORDER BY updated_at DESC LIMIT 1",
+          )
+          .get();
+        if (next?.account_id) {
+          this.db
+            .prepare("UPDATE diandian_accounts SET is_active = 1 WHERE account_id = ?")
+            .run(next.account_id);
+        }
+      }
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
+    }
+  }
+
+  close() {
+    try {
+      this.db.close();
+    } catch {}
+  }
+}