@taole/dd-playwright 0.1.14 → 0.3.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,9 +69,18 @@ dd-pw statusweb
 # 停止后台运行的服务：
 dd-pw stopweb
 
+# 查看当前安装的版本：
+dd-pw version
+
 # 一键检查并升级到最新版本：
 dd-pw update
 
+# 环境诊断（Node 版本 / Chromium 内核 / 账号库 / Web 服务 / 版本检查）：
+dd-pw doctor
+
+# 诊断并自动修复安全项（当前为缺失的 Chromium 内核）：
+dd-pw doctor --fix
+
 # （可选）前台阻塞运行（Ctrl+C 退出）：
 dd-pw serve [--port 12309]
 ```

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,10 @@ import {
   startWebDaemon,
   stopWebDaemon,
   getWebDaemonStatus,
+  getStoredWebPort,
 } from "../src/server/daemon.mjs";
-import { handleUpdateCommand } from "../src/updater.mjs";
+import { getLocalVersion, handleUpdateCommand } from "../src/updater.mjs";
+import { runDoctor, formatDoctorReport } from "../src/doctor.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -21,6 +23,8 @@ 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 doctor [--fix]                  诊断环境（Node/Chromium/数据库/Web 服务/版本）
   dd-pw update                         检查远端最新版本并自动升级
   dd-pw mcp                            以 stdio 模式启动 MCP 浏览器服务
   dd-pw --help, -h                     查看帮助信息
@@ -37,7 +41,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 +102,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 服务状态:
@@ -160,6 +169,15 @@ async function main() {
       console.error(`[dd-playwright] 启动失败:`, err);
       process.exit(1);
     }
+  } else if (command === "doctor") {
+    const report = await runDoctor({
+      config: resolveConfig(),
+      fix: args.includes("--fix"),
+    });
+    console.log(formatDoctorReport(report));
+    // 用 exitCode 而非 process.exit()：Windows 下显式退出与在途 fetch 的
+    // handle 关闭竞争会触发 uv async.c 断言崩溃
+    process.exitCode = report.ok ? 0 : 1;
   } else if (command === "update" || command === "upgrade") {
     await handleUpdateCommand();
   } else if (command === "mcp") {

package/bin/mcp-server.mjs

@@ -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.14",
+  "version": "0.3.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/doctor.mjs

@@ -0,0 +1,160 @@
+/**
+ * dd-pw doctor：环境健康度诊断。只读检查，不启动浏览器/代理，不做修复。
+ * 每项检查返回 { name, ok, detail, hint }；exit code 由汇总结果决定。
+ */
+import { existsSync, accessSync, constants, readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+import { getChromiumMetadata } from "./browser-check.mjs";
+import { getLocalVersion, getRemoteLatestVersion, compareSemver } from "./updater.mjs";
+import { getStoredWebPort, getStoredWebPid } from "./server/daemon.mjs";
+
+const MIN_NODE = [22, 13, 0];
+
+function check(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then((r) => ({ name, ok: r.ok !== false, detail: r.detail ?? "", hint: r.hint ?? "" }))
+    .catch((err) => ({ name, ok: false, detail: String(err.message || err), hint: "" }));
+}
+
+function checkNodeVersion() {
+  const [maj, min, pat] = process.versions.node.split(".").map((n) => parseInt(n, 10));
+  const ok =
+    maj > MIN_NODE[0] ||
+    (maj === MIN_NODE[0] && min > MIN_NODE[1]) ||
+    (maj === MIN_NODE[0] && min === MIN_NODE[1] && pat >= MIN_NODE[2]);
+  return {
+    detail: `当前 ${process.version}，要求 >= ${MIN_NODE.join(".")}`,
+    ok,
+    hint: ok ? "" : "升级 Node.js 后重试（依赖内置 node:sqlite）",
+  };
+}
+
+async function checkChromium(fix) {
+  const meta = await getChromiumMetadata();
+  if (meta.installed && meta.version) {
+    return { detail: `${meta.version} (${meta.executablePath})` };
+  }
+  const hint = "执行 npx playwright install chromium 补齐内核";
+  if (fix) {
+    const { ensureChromiumInstalled } = await import("./browser-check.mjs");
+    const done = await ensureChromiumInstalled({ silent: true });
+    if (done) {
+      const after = await getChromiumMetadata();
+      return { detail: `已自动修复：${after.version} (${after.executablePath})` };
+    }
+  }
+  return { ok: false, detail: meta.error || `内核缺失：${meta.executablePath || "未知路径"}`, hint };
+}
+
+function checkDataDir(config) {
+  const dir = config.dataDir;
+  if (!existsSync(dir)) {
+    return { ok: true, detail: `${dir} 尚不存在（首次使用时自动创建）` };
+  }
+  accessSync(dir, constants.R_OK | constants.W_OK);
+  return { detail: `${dir} 可读写` };
+}
+
+function checkDatabase(config) {
+  const dbPath = config.dbPath;
+  if (!existsSync(dbPath)) {
+    return { ok: true, detail: `${dbPath} 不存在（未绑定账号属正常）` };
+  }
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    const tables = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+      .all()
+      .map((r) => r.name);
+    const missing = ["diandian_accounts", "app_settings"].filter((t) => !tables.includes(t));
+    if (missing.length) {
+      return {
+        ok: false,
+        detail: `数据库缺少表：${missing.join(", ")}`,
+        hint: "数据库可能来自旧版本或已损坏；可备份后删除 runtime.db 重新扫码绑定",
+      };
+    }
+    const row = db
+      .prepare("SELECT account_id, nickname, storage_state FROM diandian_accounts WHERE is_active = 1 LIMIT 1")
+      .get();
+    if (!row) {
+      return { ok: true, detail: "数据库正常，未设置激活账号" };
+    }
+    try {
+      JSON.parse(row.storage_state);
+      return { detail: `激活账号 ${row.account_id}（${row.nickname || "未知昵称"}），storageState 可解析` };
+    } catch {
+      return {
+        ok: false,
+        detail: `激活账号 ${row.account_id} 的 storageState 无法解析`,
+        hint: "在 Web 控制台重新扫码绑定该账号",
+      };
+    }
+  } finally {
+    db.close();
+  }
+}
+
+async function checkWebDaemon(config) {
+  const pid = getStoredWebPid(config.webPidFile);
+  if (!pid) {
+    return { ok: true, detail: "后台 Web 控制台未运行（dd-pw startweb 启动）" };
+  }
+  const storedPort = getStoredWebPort(config.dataDir) || 12309;
+  try {
+    const res = await fetch(`http://127.0.0.1:${storedPort}/api/accounts`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    if (res.ok) {
+      return { detail: `运行中 PID=${pid}，http://127.0.0.1:${storedPort} 可访问` };
+    }
+    return { ok: false, detail: `PID=${pid} 存在但端口 ${storedPort} 响应 ${res.status}`, hint: "dd-pw stopweb 后重新 startweb" };
+  } catch {
+    return { ok: false, detail: `PID=${pid} 存在但端口 ${storedPort} 不可访问`, hint: "PID 文件可能残留，执行 dd-pw stopweb 清理后重新 startweb" };
+  }
+}
+
+async function checkVersion() {
+  const local = getLocalVersion();
+  const remote = await getRemoteLatestVersion();
+  if (!remote) {
+    return { ok: true, detail: `本地 ${local}，远端版本查询失败（网络问题，不影响使用）` };
+  }
+  const cmp = compareSemver(local, remote);
+  if (cmp < 0) {
+    return { ok: false, detail: `本地 ${local} 落后于远端 ${remote}`, hint: "执行 dd-pw update 升级" };
+  }
+  return { detail: `本地 ${local} 已是最新` };
+}
+
+/**
+ * 执行全部诊断
+ * @param {object} options
+ * @param {object} options.config resolveConfig() 结果
+ * @param {boolean} [options.fix] 允许自动修复安全项（当前仅 Chromium 内核缺失）
+ * @returns {Promise<{ok: boolean, results: Array}>}
+ */
+export async function runDoctor({ config, fix = false }) {
+  const results = await Promise.all([
+    check("Node 版本", checkNodeVersion),
+    check("Chromium 内核", () => checkChromium(fix)),
+    check("数据目录", () => checkDataDir(config)),
+    check("账号数据库", () => checkDatabase(config)),
+    check("Web 控制台", () => checkWebDaemon(config)),
+    check("包版本", checkVersion),
+  ]);
+  return { ok: results.every((r) => r.ok), results };
+}
+
+export function formatDoctorReport({ ok, results }) {
+  const lines = results.map((r) => {
+    const mark = r.ok ? "✔" : "✘";
+    let line = `${mark} ${r.name}: ${r.detail}`;
+    if (!r.ok && r.hint) line += `\n    建议: ${r.hint}`;
+    return line;
+  });
+  lines.push(ok ? "\n全部检查通过。" : `\n发现 ${results.filter((r) => !r.ok).length} 项问题。`);
+  return lines.join("\n");
+}

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

@@ -347,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>
@@ -368,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>
@@ -399,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 等多份规则）
@@ -409,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. 获取页面结构化交互元素，杜绝盲猜选择器
@@ -431,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>
@@ -463,11 +463,6 @@ 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>
@@ -697,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');
@@ -910,7 +905,7 @@ export function createWebServer({ accountStore, authManager, updater, port = 123
         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);

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(
@@ -119,10 +122,19 @@ export async function handleUpdateCommand(overrideCurrentVersion = null) {
     });
     console.log(`\n🎉 自动升级成功！已成功升级至最新版本 v${latestVersion}。\n`);
 
+    // 升级后 Playwright 期望的 Chromium revision 可能变化，自动补齐内核，
+    // 避免下次启动 MCP 时报“浏览器二进制缺失”
+    try {
+      const { ensureChromiumInstalled } = await import("./browser-check.mjs");
+      await ensureChromiumInstalled();
+    } catch (err) {
+      console.warn(`[dd-playwright] Chromium 内核自动补齐失败: ${err.message}`);
+      console.log(`可稍后执行 dd-pw doctor --fix 重试。\n`);
+    }
     if (wasWebRunning) {
       console.log(`[dd-playwright] 正在自动为您重启后台 Web 服务...`);
       const restartRes = await startWebDaemon({
-        port: 12309,
+        port: webPort,
         dataDir: config.dataDir,
         pidFile: config.webPidFile,
         logFile: config.webLogFile,