@taole/dd-playwright 0.1.13 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@
 
 | 工具 | 说明 |
 |---|---|
-| `browser_navigate` | 访问 URL。支持显式指定 `uid` 选择绑定账号（默认使用当前默认账号）；支持通过 `anonymous: true` 模拟未登录游客状态访问；支持 `device`（如 `iPhone 13`）启用完整移动端仿真（视口+UA+触摸），传 `desktop` 恢复桌面模式；支持 `userAgent` 会话级自定义 UA，传 `default` 清除 |
+| `browser_navigate` | 访问 URL。每次必传 `identity: { mode: "default" }`、`{ mode: "anonymous" }` 或 `{ mode: "uid", uid: "账号UID" }`；支持 `device` 设备仿真和会话级 `userAgent` |
 | `browser_resize` | 调整当前页面渲染视口（对标 playwright-mcp）。只改 innerWidth/innerHeight，不改 UA/触摸；完整移动仿真请用 `browser_navigate` 的 `device` 参数 |
 | `browser_screenshot` | 页面/元素截图，落盘到数据目录并返回路径 |
 | `browser_get_console_errors` | 收集 console.error 与未捕获异常 |
@@ -24,6 +24,8 @@
 | `browser_load_proxy_rules_dir` | 批量加载项目规则目录（如 `.whistle-rules`），全量注入并激活域名映射与 Mock 规则 |
 | `browser_status` | 查询登录态挂载情况、当前 UID、代理状态、数据目录，排查免登问题先调它 |
 
+页面操作复用当前页面及身份；没有可用页面时须先导航。相同身份的导航复用上下文，切换身份会关闭旧页面并重建上下文。
+
 ## 安装与挂载
 
 需要 Node.js >=22.13（使用内置 `node:sqlite`）。在本仓库目录执行：
@@ -67,6 +69,9 @@ dd-pw statusweb
 # 停止后台运行的服务：
 dd-pw stopweb
 
+# 查看当前安装的版本：
+dd-pw version
+
 # 一键检查并升级到最新版本：
 dd-pw update
 
@@ -74,7 +79,7 @@ dd-pw update
 dd-pw serve [--port 12309]
 ```
 
-1. 启动后在浏览器打开 `http://127.0.0.1:12309`。在「全局运行配置」的「软件更新」中可检查 npm 最新版本；当当前服务来自 npm 全局安装且有新版本时，可点击「立即更新」。安装完成后需手动重启 Web 服务和 MCP 客户端。源码或项目依赖运行时请按对应安装方式手动更新。
+1. 启动后在浏览器打开 `http://127.0.0.1:12309`。在「全局运行配置」的「软件更新」中可检查 npm 最新版本；发现新版本时，可在终端执行 `dd-pw update`，更新后在 Agent 或 IDE 中重载 MCP。源码或项目依赖运行时请按对应安装方式手动更新。
 2. 点击右上角 **「+ 添加绑定账号」**，后台会以独立的 Playwright 实例拉起扫码页并渲染二维码。
 3. 使用微信或点点 App 扫码登录，完成后会自动捕获 Cookie 与 `storageState`，提取点点账号 UID、昵称与头像，并落库至 `$BROWSER_MCP_DATA_DIR/runtime.db`。
 4. 支持多账号管理、一键设为当前激活账号或解绑账号。

package/SKILL.md

@@ -10,9 +10,9 @@ description: >-
 本技能必须通过 **`dd-playwright` MCP 服务**提供的 `browser_*` 系列工具执行。
 
 ## 1. 登录态与身份切换
-- **默认免登**：访问点点业务页面必须调用本 MCP 的 `browser_navigate` 工具，自动注入当前激活账号的凭据（包含 `Tuwan_Passport` 等 Cookie）。
-- **测试游客态/未登录拦截**：调用 `browser_navigate` 时必须显式指定 `anonymous: true`，用于验证未登录弹窗、游客导流或未鉴权状态。
-- **指定测试账号**：传入特定账号的 `uid`（如 `browser_navigate({ url, uid: "28689781" })`），自动隔离并切换独立浏览器上下文。
+- **每次导航必须显式选择身份**：默认账号使用 `identity: { mode: "default" }`；游客使用 `identity: { mode: "anonymous" }`；指定账号使用 `identity: { mode: "uid", uid: "28689781" }`。缺少身份或参数冲突会报错。
+- **身份隔离**：相同身份导航复用上下文；切换身份会关闭当前页面并重建上下文。游客模式不注入登录态，默认账号模式使用当前激活账号或配置的凭据。
+- **页面交互**：填写、点击、截图等操作复用当前页面和身份，无需重复传身份；没有可用页面时先调用 `browser_navigate`。
 
 ## 2. 本地开发服务联调（Dev Server 代理映射）
 - 当本地启动了前端开发服务器（如 Vite/Webpack 监听本地端口）时，**严禁修改系统 hosts**。
@@ -20,7 +20,7 @@ description: >-
 - **单域名映射示例**：
   - 本地 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。
+  - 随后调用 `browser_navigate({ url: "http://p9527-test.tuwan.com/", identity: { mode: "default" } })` 访问，进程内隔离 Whistle 代理会自动转发流量并按 Cookie 规则携带登录态。
 - **项目规则目录批量加载（推荐）**：
   - 若项目中存在 `.whistle-rules` 等包含多份代理/Mock 规则文件的目录，直接调用 `browser_load_proxy_rules_dir({ rulesDir: "绝对路径" })` 全量注入激活。
 
@@ -40,16 +40,16 @@ description: >-
 - **典型示例**：
   ```
   // 完整移动端仿真（视口 390x844 + iPhone UA + 触摸），会话级保持
-  browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "iPhone 13" })
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, 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" })
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, 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" })
+  browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, device: "desktop", userAgent: "default" })
   ```
 
 ## 4. 页面交互规范

package/bin/cli.mjs

@@ -6,8 +6,9 @@ import {
   startWebDaemon,
   stopWebDaemon,
   getWebDaemonStatus,
+  getStoredWebPort,
 } from "../src/server/daemon.mjs";
-import { handleUpdateCommand } from "../src/updater.mjs";
+import { getLocalVersion, handleUpdateCommand } from "../src/updater.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -21,6 +22,7 @@ dd-playwright (别名: dd-pw) CLI
   dd-pw stopweb                        停止后台运行的 Web 控制台
   dd-pw statusweb                      查看后台 Web 控制台运行状态与端口
   dd-pw serve [--port 12309]           前台阻塞启动 Web 控制台（按 Ctrl+C 退出）
+  dd-pw version, --version, -v         查看当前版本
   dd-pw update                         检查远端最新版本并自动升级
   dd-pw mcp                            以 stdio 模式启动 MCP 浏览器服务
   dd-pw --help, -h                     查看帮助信息
@@ -37,7 +39,9 @@ async function main() {
     process.exit(0);
   }
 
-  if (command === "startweb") {
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(getLocalVersion());
+  } else if (command === "startweb") {
     let port = 12309;
     const portIdx = args.indexOf("--port");
     if (portIdx !== -1 && args[portIdx + 1]) {
@@ -96,7 +100,10 @@ async function main() {
   } else if (command === "statusweb") {
     const config = resolveConfig();
     try {
-      const status = await getWebDaemonStatus(config.webPidFile);
+      const status = await getWebDaemonStatus(
+        config.webPidFile,
+        getStoredWebPort(config.dataDir) || 12309,
+      );
       if (status.running) {
         console.log(`
 [dd-playwright] 后台 Web 服务状态:

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.13";
+export const MCP_VERSION = "0.1.14";
 
 function textResult(payload) {
   return {
@@ -37,20 +37,16 @@ export function createBrowserMcpServer({ manager, config }) {
     {
       description:
         "使用内置 Playwright 访问目标 URL。" +
-        "可显式指定 uid 选择绑定的点点账号（不传则使用默认激活账号）；" +
-        "若传 anonymous: true 则以完全未登录的游客身份访问；" +
+        "必须通过 identity 指定匿名、默认账号或指定 UID 的身份；" +
         "移动端/H5 验收可传 device 启用完整设备仿真（视口+UA+触摸），也可单独传 userAgent 自定义 UA。" +
         "返回 HTTP 状态码、页面标题与控制台报错统计。",
       inputSchema: {
         url: z.string().describe("需要访问的目标页面 URL"),
-        uid: z
-          .string()
-          .optional()
-          .describe("显式指定的点点账号 UID。若不传，则默认使用当前激活账号"),
-        anonymous: z
-          .boolean()
-          .optional()
-          .describe("是否以匿名/未登录状态访问（默认 false）。若为 true，则不注入任何 Cookie/storageState"),
+        identity: z.discriminatedUnion("mode", [
+          z.strictObject({ mode: z.literal("anonymous") }),
+          z.strictObject({ mode: z.literal("default") }),
+          z.strictObject({ mode: z.literal("uid"), uid: z.string().min(1).refine((uid) => uid.trim().length > 0) }),
+        ]).describe("必填身份：anonymous、default 或 uid（需提供非空 uid）"),
         device: z
           .string()
           .optional()
@@ -78,10 +74,10 @@ export function createBrowserMcpServer({ manager, config }) {
           .describe("导航与等待超时时间（毫秒），默认 15000"),
       },
     },
-    async ({ url, uid, anonymous, device, userAgent, waitFor, timeout }) => {
+    async ({ url, identity, device, userAgent, waitFor, timeout }) => {
       try {
         return textResult(
-          await manager.navigate({ url, uid, anonymous, device, userAgent, waitFor, timeout }),
+          await manager.navigate({ url, identity, device, userAgent, waitFor, timeout }),
         );
       } catch (err) {
         return errorResult("导航失败", err);

package/package.json

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

package/src/browser-manager.mjs

@@ -137,8 +137,7 @@ export class PlaywrightBrowserManager {
       storageState !== undefined
         ? storageState
         : resolveStorageState({ dbPath, storageStateFile });
-    this.currentUid = null;
-    this.isAnonymous = false;
+    this.identity = null;
     this.device = null; // 当前设备描述符名；null 表示桌面模式
     this.sessionUserAgent = null; // 会话级 UA（工具参数设置）；null 表示回落到 this.userAgent / 设备描述符 / 默认
     this.browser = null;
@@ -185,14 +184,17 @@ export class PlaywrightBrowserManager {
 
 
   /**
-   * 根据指定的 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）
+   * 根据身份、设备描述符与会话级 UA 准备浏览器上下文。
+   * @param {{identity: {mode: 'anonymous'|'default'|'uid', uid?: string}, device?: string|null, userAgent?: string|null}} options
    */
-  async ensurePage({ uid = null, anonymous = false, device, userAgent } = {}) {
-    const targetAnonymous = Boolean(anonymous);
-    const targetUid = targetAnonymous ? null : (uid ? String(uid) : null);
+  async ensurePage({ identity, device, userAgent } = {}) {
+    if (!identity || typeof identity !== "object" || Array.isArray(identity) ||
+        !["anonymous", "default", "uid"].includes(identity.mode) ||
+        Object.keys(identity).some((key) => key !== "mode" && key !== "uid") ||
+        (identity.mode === "uid" ? typeof identity.uid !== "string" || !identity.uid.trim() : Object.hasOwn(identity, "uid"))) {
+      throw new Error("identity 必须指定 anonymous、default 或带非空 uid 的 uid 模式");
+    }
+    const targetUid = identity.mode === "uid" ? identity.uid : null;
 
     // 先解析并校验设备（非法设备名必须在关闭现有上下文之前抛错，避免误毁会话）
     let targetDevice = this.device;
@@ -211,11 +213,15 @@ export class PlaywrightBrowserManager {
     }
     const uaChanged = targetSessionUA !== this.sessionUserAgent;
 
-    // 检查是否需要重建上下文（当前模式与目标不一致）
-    const authChanged =
-      this.isAnonymous !== targetAnonymous ||
-      (targetUid !== null && this.currentUid !== targetUid) ||
-      (targetUid === null && this.currentUid !== null && !targetAnonymous);
+    const authChanged = !this.identity || this.identity.mode !== identity.mode ||
+      (identity.mode === "uid" && this.identity.uid !== targetUid);
+    let state;
+    if (authChanged || deviceChanged || uaChanged || !this.context) {
+      if (identity.mode === "anonymous") state = null;
+      else if (identity.mode === "uid") state = resolveStorageState({ dbPath: this.dbPath, uid: targetUid });
+      else if (this.customStorageState !== undefined) state = this.customStorageState;
+      else state = resolveStorageState({ dbPath: this.dbPath, storageStateFile: this.storageStateFile });
+    }
 
     if ((authChanged || deviceChanged || uaChanged) && this.context) {
       if (this.page && !this.page.isClosed()) {
@@ -236,26 +242,8 @@ export class PlaywrightBrowserManager {
     }
 
     if (!this.context) {
-      let state = null;
-      if (targetAnonymous) {
-        state = null;
-      } else if (targetUid) {
-        state = resolveStorageState({
-          dbPath: this.dbPath,
-          uid: targetUid,
-        });
-      } else if (this.customStorageState !== undefined) {
-        state = this.customStorageState;
-      } else {
-        state = resolveStorageState({
-          dbPath: this.dbPath,
-          storageStateFile: this.storageStateFile,
-        });
-      }
-
       this.storageState = state;
-      this.currentUid = targetUid;
-      this.isAnonymous = targetAnonymous;
+      this.identity = targetUid === null ? { mode: identity.mode } : { mode: "uid", uid: targetUid };
       this.device = targetDevice;
       this.sessionUserAgent = targetSessionUA;
 
@@ -303,8 +291,8 @@ export class PlaywrightBrowserManager {
     return this.page;
   }
 
-  async navigate({ url, waitFor, timeout = 15000, uid, anonymous = false, device, userAgent }) {
-    const page = await this.ensurePage({ uid, anonymous, device, userAgent });
+  async navigate({ url, waitFor, timeout = 15000, identity, device, userAgent }) {
+    const page = await this.ensurePage({ identity, device, userAgent });
     const response = await page.goto(url, {
       timeout,
       waitUntil: "domcontentloaded",
@@ -325,8 +313,13 @@ export class PlaywrightBrowserManager {
     };
   }
 
+  currentPage() {
+    if (!this.page || this.page.isClosed()) throw new Error("没有当前页面，请先使用 browser_navigate");
+    return this.page;
+  }
+
   async screenshot({ selector, fullPage = false } = {}) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const dir = this.screenshotsDir;
     mkdirSync(dir, { recursive: true });
     const filename = `screenshot-${Date.now()}-${Math.random()
@@ -349,6 +342,7 @@ export class PlaywrightBrowserManager {
   }
 
   getConsoleErrors() {
+    this.currentPage();
     return {
       total: this.consoleErrors.length,
       errors: [...this.consoleErrors],
@@ -356,7 +350,7 @@ export class PlaywrightBrowserManager {
   }
 
   async clickElement({ selector, timeout = 10000 }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const locator = page.locator(selector).first();
     await locator.click({ timeout });
     return {
@@ -366,7 +360,7 @@ export class PlaywrightBrowserManager {
     };
   }
   async fillText({ selector, text, timeout = 10000 }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const locator = page.locator(selector).first();
     await locator.fill(String(text), { timeout });
     return {
@@ -378,7 +372,7 @@ export class PlaywrightBrowserManager {
   }
 
   async pressKey({ key, selector, timeout = 10000 }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     if (selector) {
       const locator = page.locator(selector).first();
       await locator.press(key, { timeout });
@@ -394,7 +388,7 @@ export class PlaywrightBrowserManager {
   }
 
   async hover({ selector, timeout = 10000 }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const locator = page.locator(selector).first();
     await locator.hover({ timeout });
     return {
@@ -405,7 +399,7 @@ export class PlaywrightBrowserManager {
   }
 
   async scroll({ direction = "down", deltaY, selector } = {}) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     if (selector) {
       const locator = page.locator(selector).first();
       await locator.scrollIntoViewIfNeeded();
@@ -432,7 +426,7 @@ export class PlaywrightBrowserManager {
   }
 
   async waitFor({ selector, state = "visible", timeout = 15000 }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     if (selector) {
       await page.waitForSelector(selector, { state, timeout });
       return {
@@ -451,7 +445,7 @@ export class PlaywrightBrowserManager {
   }
 
   async getDom({ interactiveOnly = true, maxDepth = 10 } = {}) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const snapshot = await page.evaluate(
       ({ onlyInteractive, maxD }) => {
         function isVisible(el) {
@@ -554,7 +548,7 @@ export class PlaywrightBrowserManager {
    * @param {{width: number, height: number}} params
    */
   async resize({ width, height }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const viewport = { width: Number(width), height: Number(height) };
     await page.setViewportSize(viewport);
     return {
@@ -565,7 +559,7 @@ export class PlaywrightBrowserManager {
   }
 
   async evalJs({ script }) {
-    const page = await this.ensurePage();
+    const page = this.currentPage();
     const result = await page.evaluate((code) => {
       // eslint-disable-next-line no-eval
       return window.eval(code);

package/src/server/daemon.mjs

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, unlinkSync, openSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
@@ -110,6 +110,10 @@ export async function startWebDaemon({ port, dataDir, pidFile, logFile }) {
 
   const pid = child.pid;
   writeFileSync(pidFile, String(pid), "utf8");
+  // 记录监听端口，供 update 重启时恢复原端口（避免回落到默认 12309）
+  try {
+    writeFileSync(join(dataDir, "web.port"), String(port), "utf8");
+  } catch {}
   child.unref();
 
   // 等待最多 5 秒检测端口服务是否就绪
@@ -135,6 +139,21 @@ export async function startWebDaemon({ port, dataDir, pidFile, logFile }) {
   };
 }
 
+/**
+ * 读取后台 Web 服务启动时记录的监听端口
+ * @param {string} dataDir
+ * @returns {number|null} 端口；未记录或非法时返回 null（调用方回落默认端口）
+ */
+export function getStoredWebPort(dataDir) {
+  try {
+    const raw = readFileSync(join(dataDir, "web.port"), "utf8").trim();
+    const port = parseInt(raw, 10);
+    return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 停止后台常驻 Web 服务
  * @param {string} pidFile
@@ -151,6 +170,8 @@ export async function stopWebDaemon(pidFile) {
     if (existsSync(pidFile)) {
       unlinkSync(pidFile);
     }
+    // 同步清理端口记录；update 场景需先读取端口再调用本函数
+    unlinkSync(join(dirname(pidFile), "web.port"));
   } catch {}
 
   return { stopped: true, pid };

package/src/server/web-server.mjs

@@ -337,18 +337,7 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
           </button>
         </div>
         
-        <!-- 动态运行环境提示卡片 -->
-        <div id="envBanner" style="padding: 12px 16px; border-radius: 6px; margin-bottom: 20px; font-size: 13px; line-height: 1.5; {{BANNER_STYLE}}">
-          {{BANNER_CONTENT}}
-        </div>
-        <!-- 配置建议区块 -->
         {{CONFIG_SECTIONS}}
-
-        <div style="font-size: 12px; color: var(--muted); line-height: 1.6; background: #0f172a; padding: 12px; border-radius: 6px; border: 1px solid var(--border); margin-top: 20px;">
-          💡 <b>配置生效小提示：</b><br>
-          1. 挂载后启动 AI 客户端，AI 会自动识别 <code>browser_navigate</code>、<code>browser_screenshot</code> 等 13 个完整 Playwright 工具。<br>
-          2. 在本页面扫码绑定的账号，MCP 会自动读取同一个 SQLite 账号库免登运行。
-        </div>
       </div>
     </div>
 
@@ -358,9 +347,9 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
         <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
           <div class="card-title" style="margin-bottom: 0;">Skill 规范说明 (SKILL.md)</div>
           <div style="display: flex; gap: 8px;">
-            <a href="/api/skill/download" download="SKILL.md" class="btn" style="background: #334155; color: white; display: flex; align-items: center; gap: 6px; font-weight: 500; padding: 7px 12px; text-decoration: none;">
+            <a href="/api/skill/download" download="DD-PLAYWRIGHT-SKILL.MD" class="btn" style="background: #334155; color: white; display: flex; align-items: center; gap: 6px; font-weight: 500; padding: 7px 12px; text-decoration: none;">
               <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
-              下载 SKILL.md
+              下载 DD-PLAYWRIGHT-SKILL.MD
             </a>
             <button class="btn" onclick="installSkillToCursor()" style="background: #0284c7; color: white; display: flex; align-items: center; gap: 7px; font-weight: 600; padding: 7px 14px;">
               <svg width="14" height="16" viewBox="0 0 467 533" fill="currentColor"><path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z"/></svg>
@@ -379,8 +368,8 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
           
           <div style="background: #0f172a; border: 1px solid var(--border); border-radius: 6px; padding: 14px; margin-top: 10px; font-size: 13px; line-height: 1.8; color: #cbd5e1;">
             <b>1. 登录态与身份切换：</b><br>
-            • 访问点点业务页面必须调用本 MCP 的 <code>browser_navigate</code> 工具，自动注入当前激活账号的 storageState（含 <code>Tuwan_Passport</code> 鉴权 Cookie）免登。<br>
-            • 多角色或指定账号测试时传入特定 <code>uid</code>，自动隔离并重建独立浏览器上下文。<br><br>
+            • 每次导航必须通过 <code>identity</code> 选择身份：默认账号 <code>{ mode: "default" }</code>、游客 <code>{ mode: "anonymous" }</code> 或指定账号 <code>{ mode: "uid", uid: "账号UID" }</code>。<br>
+            • 切换身份会重建上下文；页面交互复用当前页面与身份。<br><br>
             <b>2. 本地开发服务联调（Dev Server 代理映射）：</b><br>
             • 本地服务启动后严禁改动系统 hosts，可通过单域名映射或项目规则目录全量注入：<br>
             • <b>单条映射</b>：<code>browser_set_proxy_rule({ domain: "p9527-test.tuwan.com", port: 9527 })</code><br>
@@ -410,8 +399,8 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
           <div class="code-block" style="color: #93c5fd; font-size: 12px; margin-bottom: 12px;">// 方式 A：单域名映射
 1. 本地 Vite 启动在 127.0.0.1:9527
 2. 映射代理域名：browser_set_proxy_rule({ domain: "p9527-test.tuwan.com", port: 9527 })
-3. 免登访问页面：browser_navigate({ url: "http://p9527-test.tuwan.com/" })
-   -> 自动携带点点线上 Tuwan_Passport Cookie，无需改动系统 hosts！
+3. 免登访问页面：browser_navigate({ url: "http://p9527-test.tuwan.com/", identity: { mode: "default" } })
+   -> 按浏览器 Cookie 规则携带登录态，无需改动系统 hosts！
 
 // 方式 B：项目规则目录批量导入（推荐）
 1. 项目中已存在 .whistle-rules 目录（含域名映射、接口 Mock 等多份规则）
@@ -420,13 +409,13 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
 
           <div class="code-title"><span>流程 2：游客拦截 vs 正常登录态对比测试</span></div>
           <div class="code-block" style="color: #93c5fd; font-size: 12px; margin-bottom: 12px;">// 1. 游客态验证（验证未登录拦截弹窗/导流流程）
-browser_navigate({ url: "https://y.tuwan.com/activity/...", anonymous: true })
+browser_navigate({ url: "https://y.tuwan.com/activity/...", identity: { mode: "anonymous" } })
 
 // 2. 默认登录态验证（自动携带默认账号正常参与活动）
-browser_navigate({ url: "https://y.tuwan.com/activity/..." })
+browser_navigate({ url: "https://y.tuwan.com/activity/...", identity: { mode: "default" } })
 
 // 3. 指定测试账号（切换特定身份排查权限或对账）
-browser_navigate({ url: "https://y.tuwan.com/activity/...", uid: "28689781" })</div>
+browser_navigate({ url: "https://y.tuwan.com/activity/...", identity: { mode: "uid", uid: "28689781" } })</div>
 
           <div class="code-title"><span>流程 3：交互排查与元素定位</span></div>
           <div class="code-block" style="color: #93c5fd; font-size: 12px; margin-bottom: 0;">// 1. 获取页面结构化交互元素，杜绝盲猜选择器
@@ -442,16 +431,16 @@ 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" })
+browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, 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" })
+browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, 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>
+browser_navigate({ url: "https://xdd-test.tuwan.com/", identity: { mode: "default" }, device: "desktop", userAgent: "default" })</div>
         </div>
       </div>
     </div>
@@ -474,17 +463,10 @@ browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "desktop", userAg
             <span id="headlessKnob" style="position: absolute; height: 20px; width: 20px; left: 3px; bottom: 3px; background-color: white; transition: .2s; border-radius: 50%;"></span>
           </label>
         </div>
-        <div style="margin-top: 16px; font-size: 12px; color: var(--muted); line-height: 1.6; padding: 12px; background: #090d16; border-radius: 6px; border: 1px solid var(--border);">
-          📁 <b>数据存储说明：</b><br>
-          本服务所有数据与账号库已默认固化在用户主目录下的 <code>~/.dd-browser-mcp/runtime.db</code>，无需配置任何复杂环境变量，开箱即用。
-        </div>
-
         <div style="margin-top: 20px; padding: 16px; background: #0f172a; border-radius: 8px; border: 1px solid var(--border);">
           <div style="font-size: 14px; font-weight: 600; margin-bottom: 8px;">软件更新</div>
-          <div id="updateInfo" style="font-size: 12px; color: var(--muted); line-height: 1.8; margin-bottom: 12px;" aria-live="polite">准备检查更新…</div>
+          <div id="updateInfo" style="font-size: 12px; color: var(--muted); line-height: 1.8; margin-bottom: 12px;" aria-live="polite">点击检查更新，查看是否有新版本。</div>
           <button id="checkUpdateBtn" class="btn btn-primary" onclick="checkUpdates()">检查更新</button>
-          <button id="installUpdateBtn" class="btn btn-primary" onclick="installUpdate()" style="display:none; margin-left: 8px;">立即更新</button>
-          <div style="font-size: 12px; color: var(--muted); margin-top: 10px;">更新仅针对全局安装的 npm 包。更新完成后需重启 Web 服务及 MCP 客户端；源码运行请手动更新。</div>
         </div>
 
         <!-- Chromium 浏览器内核状态展示卡片 -->
@@ -710,7 +692,7 @@ browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "desktop", userAg
         '---',
         '# dd-playwright 自动化指南',
         '本技能必须通过 dd-playwright MCP 服务提供的 browser_* 系列工具执行：',
-        '1. 登录态与身份切换：访问点点页面调用本 MCP 的 browser_navigate 自动注入激活账号免登；排查游客态或未登录拦截必须传 anonymous: true；指定测试账号传特定 uid。',
+        '1. 登录态与身份切换：每次 browser_navigate 必须传 identity：默认账号 { mode: "default" }，游客 { mode: "anonymous" }，指定账号 { mode: "uid", uid: "账号UID" }。页面操作复用当前身份。',
         '2. 本地 Dev Server 联调：严禁改动系统 hosts。支持 browser_set_proxy_rule 单条映射，或 browser_load_proxy_rules_dir 批量加载 .whistle-rules 目录（语法如：域名映射 p9527-test.tuwan.com http://127.0.0.1:9527、接口 Mock yapi.tuwan.com/act resBody://{mock.json}、官方文档 https://wproxy.org/whistle/rules/）。',
         '3. 页面交互规范：定位困难时优先调用 browser_get_dom 提取可见元素结构，严禁盲猜选择器；表单填写使用 browser_fill_text，按键使用 browser_press_key。'
       ].join('\\n');
@@ -786,63 +768,31 @@ browser_navigate({ url: "https://xdd-test.tuwan.com/", device: "desktop", userAg
     async function checkUpdates() {
       const info = document.getElementById('updateInfo');
       const check = document.getElementById('checkUpdateBtn');
-      const install = document.getElementById('installUpdateBtn');
       check.disabled = true;
-      install.style.display = 'none';
       info.textContent = '正在查询 npm 最新版本…';
       try {
         const response = await fetch('/api/update/check', { cache: 'no-store' });
         const data = await response.json();
         if (!data.ok) throw new Error(data.error || data.message || '检查失败');
-        info.textContent = '当前版本：' + data.currentVersion + '；最新版本：' + data.latestVersion + '。' + (data.message || '');
-        if (data.updateAvailable && data.canUpdate) install.style.display = 'inline-block';
+        if (!data.updateAvailable) {
+          info.textContent = '当前已是最新版本（v' + data.currentVersion + '）。';
+        } else {
+          info.textContent = '发现新版本：v' + data.currentVersion + ' → v' + data.latestVersion + '。请在终端执行 dd-pw update，更新后在 Agent 或 IDE 中重载 MCP。';
+        }
       } catch (err) {
         info.textContent = '检查更新失败：' + err.message;
       } finally { check.disabled = false; }
     }
 
-    async function installUpdate() {
-      if (!confirm('确认更新全局安装的 dd-playwright？完成后需要重启 Web 服务和 MCP 客户端。')) return;
-      const info = document.getElementById('updateInfo');
-      const install = document.getElementById('installUpdateBtn');
-      const check = document.getElementById('checkUpdateBtn');
-      install.disabled = true;
-      check.disabled = true;
-      try {
-        const response = await fetch('/api/update', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
-        const data = await response.json();
-        if (!data.ok) throw new Error(data.error || data.message || '无法启动更新');
-        info.textContent = data.message || '正在更新，请稍候…';
-        const poll = async () => {
-          try {
-            const state = await (await fetch('/api/update/status', { cache: 'no-store' })).json();
-            if (!state.ok) throw new Error(state.error || '查询更新状态失败');
-            info.textContent = (state.message || '正在更新…') + (state.error ? '：' + state.error : '');
-            if (state.status === 'running') { setTimeout(poll, 1500); return; }
-            if (state.status === 'success') install.style.display = 'none';
-            install.disabled = false;
-            check.disabled = false;
-          } catch (err) {
-            info.textContent = '查询更新状态失败：' + err.message + '；请稍后重新检查。';
-            install.disabled = false; check.disabled = false;
-          }
-        };
-        setTimeout(poll, 1000);
-      } catch (err) {
-        info.textContent = '更新失败：' + err.message;
-        install.disabled = false; check.disabled = false;
-      }
-    }
-
     loadAccounts();
     loadSettings();
     loadChromiumMeta();
-    checkUpdates();
   </script>
 </body>
 </html>`;
 
-export function createWebServer({ accountStore, authManager, updater = createWebUpdater() }) {
+export function createWebServer({ accountStore, authManager, updater, port = 12309 }) {
+  updater ??= createWebUpdater({ port });
   const server = createServer(async (req, res) => {
     // Update endpoints are privileged even when the listener binds 0.0.0.0.
     if (req.url?.split("?")[0].startsWith("/api/update")) {
@@ -866,21 +816,6 @@ export function createWebServer({ accountStore, authManager, updater = createWeb
       if (req.method === "GET" && path === "/api/update/check") {
         try { sendUpdate(200, { ok: true, ...await updater.check() }); }
         catch (err) { sendUpdate(502, { ok: false, error: err.message }); }
-      } else if (req.method === "GET" && path === "/api/update/status") {
-        sendUpdate(200, { ok: true, ...updater.status() });
-      } else if (req.method === "POST" && path === "/api/update") {
-        if (!/^application\/json(?:\s*;\s*charset=utf-8)?\s*$/i.test(req.headers["content-type"] || "")) {
-          sendUpdate(415, { ok: false, error: "需要 application/json" }); return;
-        }
-        let body = "";
-        for await (const chunk of req) {
-          body += chunk;
-          if (body.length > 4096) { sendUpdate(413, { ok: false, error: "请求过大" }); return; }
-        }
-        try { const data = JSON.parse(body); if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error(); }
-        catch { sendUpdate(400, { ok: false, error: "需要 JSON 对象" }); return; }
-        const { started, ...result } = await updater.start();
-        sendUpdate(started ? 202 : 409, { ok: started, ...result });
       } else { sendUpdate(404, { ok: false, error: "Not Found" }); }
       return;
     }
@@ -899,8 +834,6 @@ export function createWebServer({ accountStore, authManager, updater = createWeb
 
     // 1. 首页控制台
     if (pathname === "/" || pathname === "/index.html") {
-      const currentFilePath = fileURLToPath(import.meta.url).replaceAll("\\", "/");
-      const isInstalledViaNpm = /\/node_modules\/(@taole\/)?dd-playwright\//i.test(currentFilePath);
       const serverScriptPath = fileURLToPath(
         new URL("../../bin/mcp-server.mjs", import.meta.url),
       ).replaceAll("\\", "/");
@@ -918,12 +851,9 @@ export function createWebServer({ accountStore, authManager, updater = createWeb
         2,
       );
 
-      let bannerStyle = "background: rgba(59, 130, 246, 0.12); border: 1px solid rgba(59, 130, 246, 0.3); color: #60a5fa;";
-      let bannerContent = `💻 <b>当前代码位置：</b><code style="background: rgba(0,0,0,0.3); padding: 2px 6px; border-radius: 4px; color: #93c5fd;">${serverScriptPath}</code><br><span style="color:#cbd5e1; font-size:12px; margin-top: 4px; display: inline-block;">使用 Node 绝对路径方式挂载 MCP，不受系统 PATH 或环境切换影响，100% 稳定运行。</span>`;
-
       let configSections = `
         <div class="code-title">
-          <span>本地绝对路径配置（推荐，开箱即用）</span>
+          <span>MCP 配置</span>
           <button class="copy-btn" onclick="copyCode('code-mcp-local')">复制代码</button>
         </div>
         <div id="code-mcp-local" class="code-block">${localConfigStr}</div>
@@ -938,8 +868,6 @@ export function createWebServer({ accountStore, authManager, updater = createWeb
 
       const renderedHtml = DASHBOARD_HTML
         .replace("{{VERSION}}", pkgVersion)
-        .replace("{{BANNER_STYLE}}", bannerStyle)
-        .replace("{{BANNER_CONTENT}}", bannerContent)
         .replace("{{CONFIG_SECTIONS}}", configSections);
       sendHtml(res, renderedHtml);
       return;
@@ -977,7 +905,7 @@ export function createWebServer({ accountStore, authManager, updater = createWeb
         const content = readFileSync(skillPath, "utf8");
         res.writeHead(200, {
           "Content-Type": "text/markdown; charset=utf-8",
-          "Content-Disposition": 'attachment; filename="SKILL.md"',
+          "Content-Disposition": 'attachment; filename="DD-PLAYWRIGHT-SKILL.MD"',
           "Cache-Control": "no-cache",
         });
         res.end(content);
@@ -1122,7 +1050,7 @@ export async function startWebServer({
 } = {}) {
   const store = accountStore || new AccountStore(dbPath);
   const authManager = new DiandianAuthManager({ accountStore: store });
-  const server = createWebServer({ accountStore: store, authManager });
+  const server = createWebServer({ accountStore: store, authManager, port });
 
   return new Promise((resolve, reject) => {
     server.listen(port, "0.0.0.0", () => {

package/src/server/web-update.mjs

@@ -1,67 +1,13 @@
-import { spawn, execFile } from "node:child_process";
-import { realpath } from "node:fs/promises";
-import { promisify } from "node:util";
-import { fileURLToPath } from "node:url";
-import { join } from "node:path";
-import { PACKAGE_NAME, compareSemver, getLocalVersion, getRemoteLatestVersion } from "../updater.mjs";
+import { compareSemver, getLocalVersion, getRemoteLatestVersion } from "../updater.mjs";
 
-const execFileAsync = promisify(execFile);
-const packageDir = fileURLToPath(new URL("../../", import.meta.url));
-
-async function isGlobalInstall() {
-  try {
-    const windows = process.platform === "win32";
-    const { stdout } = await execFileAsync(windows ? process.env.ComSpec || "cmd.exe" : "npm", windows ? ["/d", "/s", "/c", "npm.cmd root -g"] : ["root", "-g"], { windowsHide: true, timeout: 10000 });
-    const [actual, global] = await Promise.all([realpath(packageDir), realpath(join(stdout.trim(), PACKAGE_NAME))]);
-    return windows ? actual.toLowerCase() === global.toLowerCase() : actual === global;
-  } catch { return false; }
-}
-
-function installGlobal() {
-  return new Promise((resolve, reject) => {
-    const windows = process.platform === "win32";
-    const child = spawn(windows ? process.env.ComSpec || "cmd.exe" : "npm", windows
-      ? ["/d", "/s", "/c", `npm.cmd install -g ${PACKAGE_NAME}@latest`]
-      : ["install", "-g", `${PACKAGE_NAME}@latest`],
-    { windowsHide: true, stdio: ["ignore", "ignore", "pipe"] });
-    let stderr = "";
-    child.stderr?.on("data", chunk => { stderr = (stderr + chunk.toString()).slice(-4000); });
-    child.once("error", reject);
-    child.once("close", (code, signal) => code === 0 ? resolve() : reject(new Error(stderr.trim() || `npm 退出: ${signal || code}`)));
-  });
-}
-
-export function createWebUpdater({ getVersion = getLocalVersion, getLatest = getRemoteLatestVersion, isGlobal = isGlobalInstall, install = installGlobal } = {}) {
-  let state = { status: "idle", error: null, message: "尚未开始更新", restartRequired: false };
+/** 仅检查版本，不执行安装或重启。 */
+export function createWebUpdater({ getVersion = getLocalVersion, getLatest = getRemoteLatestVersion } = {}) {
   return {
     async check() {
       const currentVersion = getVersion();
-      const [latestVersion, global] = await Promise.all([getLatest(), isGlobal()]);
+      const latestVersion = await getLatest();
       if (!latestVersion) throw new Error("无法查询 npm 最新版本，请检查网络");
-      return { currentVersion, latestVersion, updateAvailable: compareSemver(latestVersion, currentVersion) > 0,
-        installType: global ? "global" : "local", canUpdate: global,
-        message: global ? "更新完成后请手动重启服务" : "当前运行的不是 npm 全局安装，更新全局包不会更新此服务，请按当前安装方式手动更新" };
-    },
-    status() { return { ...state }; },
-    async start() {
-      if (state.status === "running") return { started: false, ...state };
-      state = { status: "running", error: null, message: "正在确认安装位置", restartRequired: false };
-      try {
-        if (!await isGlobal()) {
-          state = { status: "error", error: "当前服务不是 npm 全局安装，请手动更新当前安装", message: "无法自动更新", restartRequired: false };
-          return { started: false, ...state };
-        }
-        state.message = "正在安装更新，完成后请手动重启服务";
-        Promise.resolve().then(() => install()).then(() => {
-          state = { status: "success", error: null, message: "安装完成，请手动重启服务以使用新版本", restartRequired: true };
-        }, err => {
-          state = { status: "error", error: String(err?.message || err), message: "安装失败，服务仍在运行", restartRequired: false };
-        });
-        return { started: true, ...state };
-      } catch (err) {
-        state = { status: "error", error: String(err?.message || err), message: "更新启动失败", restartRequired: false };
-        return { started: false, ...state };
-      }
+      return { currentVersion, latestVersion, updateAvailable: compareSemver(latestVersion, currentVersion) > 0 };
     },
   };
 }

package/src/updater.mjs

@@ -4,6 +4,7 @@ import { execSync } from "node:child_process";
 import { resolveConfig } from "./config.mjs";
 import {
   getStoredWebPid,
+  getStoredWebPort,
   stopWebDaemon,
   startWebDaemon,
 } from "./server/daemon.mjs";
@@ -100,6 +101,8 @@ export async function handleUpdateCommand(overrideCurrentVersion = null) {
   const config = resolveConfig();
   const runningPid = getStoredWebPid(config.webPidFile);
   const wasWebRunning = Boolean(runningPid);
+  // 停止前先读取服务启动时记录的端口，重启时恢复原端口
+  const webPort = getStoredWebPort(config.dataDir) || 12309;
 
   if (wasWebRunning) {
     console.log(
@@ -122,7 +125,7 @@ export async function handleUpdateCommand(overrideCurrentVersion = null) {
     if (wasWebRunning) {
       console.log(`[dd-playwright] 正在自动为您重启后台 Web 服务...`);
       const restartRes = await startWebDaemon({
-        port: 12309,
+        port: webPort,
         dataDir: config.dataDir,
         pidFile: config.webPidFile,
         logFile: config.webLogFile,