@taole/dd-playwright 0.1.0 → 0.1.2

package/SKILL.md

@@ -1,109 +1,28 @@
 ---
 name: dd-playwright
 description: >-
-  使用 dd-playwright (别名: dd-pw, dd-browser) 进行点点前端业务页面与 H5 活动的自动化测试、免登导航、页面截图、表单填写、键盘按键、DOM 提取、JS 评估与 Whistle 代理规则调试。
-  支持多账号免登与游客匿名态模拟，通过本地扫码控制台绑定点点账号。
-  当用户提到点点页面测试、免登访问、浏览器截图、控制台报错排查、本地 dev server 代理映射、dd-playwright、dd-pw、dd-browser 时使用。
+  通过 dd-playwright MCP 服务（提供 browser_* 工具集）进行点点前端业务页面与 H5 活动的自动化测试、免登导航、页面截图、表单交互与 Whistle 代理调试。
+  当用户提到点点页面测试、免登访问、浏览器截图、控制台报错排查、本地 dev server 代理映射、dd-playwright、dd-pw 时使用。
 ---
 
-# dd-playwright (dd-pw)
+# dd-playwright 自动化指南
 
-增强型 Playwright 浏览器自动化 MCP 服务与扫码控制台，专为点点业务前端调试和 AI Agent 设计。
+本技能必须通过 **`dd-playwright` MCP 服务**提供的 `browser_*` 系列工具执行。
 
-## 核心特性
+## 1. 登录态与身份切换
+- **默认免登**：访问点点业务页面必须调用本 MCP 的 `browser_navigate` 工具，自动注入当前激活账号的凭据（包含 `Tuwan_Passport` 等 Cookie）。
+- **测试游客态/未登录拦截**：调用 `browser_navigate` 时必须显式指定 `anonymous: true`，用于验证未登录弹窗、游客导流或未鉴权状态。
+- **指定测试账号**：传入特定账号的 `uid`（如 `browser_navigate({ url, uid: "28689781" })`），自动隔离并切换独立浏览器上下文。
 
-1. **自动免登注入**：访问 `*.tuwan.com` 时自动注入扫码绑定的点点测试账号凭据（`Tuwan_Passport` 等 Cookie）。
-2. **多账号与匿名切换**：
-   - 默认使用控制台设为「默认账号」的凭据。
-   - `browser_navigate` 支持显式指定 `uid: "12345"` 切换不同测试身份。
-   - 支持 `anonymous: true` 模拟未登录的游客态访问，测试未登录拦截与导流逻辑。
-3. **独立 Whistle 代理托管**：
-   - `browser_set_proxy_rule` 可声明 `本地端口 -> 干净 *.tuwan.com 域名` 的代理规则。
-   - 进程内完全隔离临时 Whistle 配置，绝不污染系统或用户目录 `~/.WhistleAppData`。
-4. **一键 Web 扫码绑定**：
-   - 内置 Web 控制台（默认监听 `12309` 端口），手机扫码即刻完成账号绑定并同步至 MCP。
+## 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。
 
----
-
-## 快速配置 MCP 客户端
-
-在你的 AI 客户端（如 **omp**, **Cursor**, **Claude Desktop** 等）的 MCP 配置文件中添加：
-
-### 1. 全局命令方式（推荐）
-```json
-{
-  "mcpServers": {
-    "dd-playwright": {
-      "command": "dd-playwright-mcp"
-    }
-  }
-}
-```
-
-### 2. 源码路径方式（本地调试）
-```json
-{
-  "mcpServers": {
-    "dd-playwright": {
-      "command": "node",
-      "args": ["D:/tools/dd-browser-mcp/bin/mcp-server.mjs"]
-    }
-  }
-}
-```
-
----
-
-## 工具集 (Tools) 契约
-
-| 工具名称 | 关键参数 | 说明 |
-|---|---|---|
-| `browser_navigate` | `url` (必填)<br>`uid` (可选): 指定点点账号 UID<br>`anonymous` (可选): `true` 模拟游客态<br>`waitFor` (可选): 等待的 DOM 选择器<br>`timeout` (可选, 默认 15000ms) | 访问目标页面，返回 HTTP 状态码、页面标题与控制台报错统计。自动注入点点 storageState。不同身份调用自动隔离上下文。 |
-| `browser_screenshot` | `selector` (可选): 指定元素选择器<br>`fullPage` (可选, 默认 false): 整页滚动截图 | 截取页面或特定元素，落盘到数据目录，返回本地图片路径。 |
-| `browser_get_console_errors` | 无 | 收集当前页面自导航以来的 console.error 与未捕获异常。 |
-| `browser_click_element` | `selector` (必填)<br>`timeout` (可选, 默认 10000ms) | 模拟用户点击指定 DOM 元素（按钮、选项卡等）。 |
-| `browser_fill_text` | `selector` (必填)<br>`text` (必填)<br>`timeout` (可选) | 向目标输入框/文本域填入文本，原生触发 input 与 change 事件。 |
-| `browser_press_key` | `key` (必填, 如 "Enter", "Tab", "Escape")<br>`selector` (可选): 目标聚焦元素 | 模拟键盘单键或组合键按下。 |
-| `browser_hover` | `selector` (必填)<br>`timeout` (可选) | 鼠标悬停在指定 DOM 元素上，触发 hover 样式或 Tooltip 浮层。 |
-| `browser_scroll` | `direction` ("down" 或 "up")<br>`deltaY` (可选数值)<br>`selector` (可选): 指定滚动元素 | 滚动视口或将指定元素滚动至可视区域。 |
-| `browser_wait_for` | `selector` (可选)<br>`state` ("visible", "hidden", "attached", "detached")<br>`timeout` (可选) | 等待页面加载状态或特定 DOM 元素出现/隐藏。 |
-| `browser_get_dom` | `interactiveOnly` (可选, 默认 true)<br>`maxDepth` (可选, 默认 10) | 结构化提取页面可见交互元素清单（含文本与选择器），免去盲猜或截大图。 |
-| `browser_eval_js` | `script` (必填): JS 代码字符串 | 在当前浏览器页面上下文中执行任意 JavaScript 脚本并返回结果。 |
-| `browser_set_proxy_rule` | `domain` (必填, 需匹配 `*.tuwan.com`)<br>`port` (必填, 本地服务端口)<br>`protocol` (可选, "http" 或 "https") | 声明本地 dev server 代理映射，使本地开发服务可通过合法的点点域名访问并正常携带登录 Cookie。 |
-| `browser_status` | 无 | 查询当前服务版本、激活点点账号、代理状态与数据目录。 |
-
----
-
-## Web 账号控制台 (扫码绑定)
-
-在终端运行以下命令启动管理控制台：
-
-```bash
-# 后台静默启动（推荐，不占控制台终端）：
-dd-pw startweb
-
-# 查看后台运行状态与 PID：
-dd-pw statusweb
-
-# 停止后台服务：
-dd-pw stopweb
-
-# 前台阻塞运行（Ctrl+C 退出）：
-dd-pw serve
-```
-
-- 打开浏览器访问：`http://127.0.0.1:12309`
-- 点击 **「+ 添加绑定账号」**，使用微信或点点 App 扫描二维码即可。
-- 控制台支持多账号查看、设为默认账号或解绑账号。
-
----
-
-## Agent 使用最佳实践
-
-1. **先排查状态**：在执行复杂的业务排查或测试前，先调用 `browser_status` 确认是否已加载登录态或默认账号 UID。
-2. **测试登录态与未登录态对比**：
-   - 先调用 `browser_navigate({ url, anonymous: true })` 查看游客视角行为（如是否弹出登录拦截、展示游客文案）。
-   - 再调用 `browser_navigate({ url })` 查看默认登录用户视角；或 `browser_navigate({ url, uid: "..." })` 验证特定业务角色。
-3. **本地 dev 调试**：
-   - 本地前端开发服务启动后（例如 `127.0.0.1:9527`），先调用 `browser_set_proxy_rule({ domain: "act-dev.tuwan.com", port: 9527 })`。
-   - 随后调用 `browser_navigate({ url: "http://act-dev.tuwan.com/..." })`，不仅不改 hosts，且浏览器能正常携带点点线上 Cookie。
+## 3. 页面交互规范
+- **元素定位**：在动态页面或选择器不确定时，优先调用 `browser_get_dom` 提取当前可见的交互元素结构（包含按钮、输入框、链接及其选择器），严禁盲猜选择器。
+- **表单与按键**：表单输入调用 `browser_fill_text`（原生触发 `input` 与 `change` 事件）；键盘按键/回车提交调用 `browser_press_key`。
+- **状态排查**：排查免登异常前先调用 `browser_status` 确认 MCP 服务凭据挂载状态与当前 UID。

package/bin/mcp-server.mjs

@@ -10,7 +10,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.0";
+export const MCP_VERSION = "0.1.1";
 
 function textResult(payload) {
   return {

package/package.json

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

package/src/auth/diandian-auth.mjs

@@ -1,4 +1,5 @@
 import { chromium } from "playwright";
+import { ensureChromiumInstalled } from "../browser-check.mjs";
 
 export const DIANDIAN_HOME_URL = "https://y.tuwan.com";
 export const DIANDIAN_USER_INFO_URL =
@@ -43,10 +44,9 @@ export class DiandianAuthManager {
 
     this.startupPromise = (async () => {
       await this.close();
-
+      await ensureChromiumInstalled();
       const instance = await this.chromium.launch({ headless });
       const ctx = await instance.newContext({
-        viewport: { width: 1100, height: 850 },
         userAgent:
           "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
       });

package/src/browser-check.mjs

@@ -0,0 +1,103 @@
+import { chromium } from "playwright";
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+let cachedChromiumMeta = null;
+
+/**
+ * 获取当前 Chromium 内核安装状态与元数据
+ * @returns {Promise<{ installed: boolean, executablePath: string, version: string|null, error: string|null }>}
+ */
+export async function getChromiumMetadata() {
+  let executablePath = "";
+  try {
+    executablePath = chromium.executablePath();
+  } catch (err) {
+    return {
+      installed: false,
+      executablePath: "",
+      version: null,
+      error: err.message,
+    };
+  }
+
+  const installed = Boolean(executablePath && existsSync(executablePath));
+  if (!installed) {
+    return {
+      installed: false,
+      executablePath: executablePath || "",
+      version: null,
+      error: "未在系统默认目录中发现对应版本的 Chromium 二进制文件",
+    };
+  }
+
+  if (cachedChromiumMeta && cachedChromiumMeta.installed) {
+    return cachedChromiumMeta;
+  }
+
+  let version = null;
+  try {
+    const browser = await chromium.launch({ headless: true });
+    version = browser.version();
+    await browser.close();
+  } catch (err) {
+    // 无法正常启动时可能是缺少依赖库或路径损坏
+    return {
+      installed: true,
+      executablePath,
+      version: null,
+      error: `启动检查异常: ${err.message}`,
+    };
+  }
+
+  cachedChromiumMeta = {
+    installed: true,
+    executablePath,
+    version,
+    error: null,
+  };
+  return cachedChromiumMeta;
+}
+
+/**
+ * 确保 Chromium 内核已就绪，若缺失则自动执行下载补齐
+ * @param {object} [options]
+ * @param {boolean} [options.silent] 是否静默输出
+ * @returns {Promise<boolean>} 是否成功就绪
+ */
+export async function ensureChromiumInstalled({ silent = false } = {}) {
+  const meta = await getChromiumMetadata();
+  if (meta.installed && meta.version) {
+    return true;
+  }
+
+  if (!silent) {
+    console.log(
+      "\n[dd-playwright] 检测到当前系统尚未安装 Chromium 浏览器内核，正在为您自动下载 (~150MB)，请稍候...",
+    );
+  }
+
+  try {
+    // 调用 playwright 内置命令安装 chromium
+    execSync("npx playwright install chromium", {
+      stdio: silent ? "ignore" : "inherit",
+      windowsHide: true,
+    });
+    cachedChromiumMeta = null; // 清理缓存
+    const verify = await getChromiumMetadata();
+    if (!silent) {
+      if (verify.installed) {
+        console.log(`[dd-playwright] Chromium 内核自动安装成功！版本: ${verify.version}\n`);
+      } else {
+        console.warn(`[dd-playwright] Chromium 安装流程已结束，但未能在路径检测到执行文件: ${verify.executablePath}\n`);
+      }
+    }
+    return verify.installed;
+  } catch (err) {
+    if (!silent) {
+      console.error(`[dd-playwright] 自动安装 Chromium 失败: ${err.message}`);
+      console.error(`可手动在终端执行: npx playwright install chromium\n`);
+    }
+    return false;
+  }
+}

package/src/browser-manager.mjs

@@ -5,6 +5,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { join } from "node:path";
 import { chromium } from "playwright";
+import { ensureChromiumInstalled } from "./browser-check.mjs";
 import { WhistleProxyManager } from "./whistle-proxy.mjs";
 
 /**
@@ -164,6 +165,7 @@ export class PlaywrightBrowserManager {
     }
 
     if (!this.browser) {
+      await ensureChromiumInstalled();
       const launchArgs = this.whistle.started ? this.whistle.getBrowserArgs() : [];
       this.browser = await chromium.launch({
         headless: this.headless,

package/src/server/web-server.mjs

@@ -1,7 +1,8 @@
 import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { AccountStore } from "../account-store.mjs";
 import { DiandianAuthManager } from "../auth/diandian-auth.mjs";
+import { getChromiumMetadata } from "../browser-check.mjs";
 
 function sendJson(res, statusCode, payload) {
   res.writeHead(statusCode, {
@@ -300,7 +301,7 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
         <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><path d="M9 3v18"/><path d="M15 9h6"/></svg>
         dd-playwright 账号管理控制台
       </h1>
-      <span style="font-size: 13px; color: var(--muted);">v0.1.0</span>
+      <span style="font-size: 13px; color: var(--muted);">v{{VERSION}}</span>
     </header>
 
     <div class="nav-tabs">
@@ -326,13 +327,18 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
     <!-- TAB 2: MCP 配置说明 -->
     <div id="pane-mcp" class="tab-pane">
       <div class="card">
-        <div class="card-title">MCP 挂载配置指南</div>
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
+          <div class="card-title" style="margin-bottom: 0;">MCP 挂载配置指南</div>
+          <button class="btn" onclick="installToCursor()" 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>
+            一键安装到 Cursor
+          </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}}
 
@@ -347,93 +353,42 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
     <!-- TAB 3: Skill 规范与工具说明 -->
     <div id="pane-skill" class="tab-pane">
       <div class="card">
-        <div class="card-title">Skill 规范说明 (SKILL.md)</div>
-        
+        <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;">
+              <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
+            </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>
+              一键安装到 Cursor
+            </button>
+          </div>
+        </div>
         <div class="doc-section">
           <h3>适用场景</h3>
-          <p>进行点点业务页面/活动 H5 自动化测试、免登导航、页面截图、控制台报错排查、本地 dev server 代理映射时由 AI Agent 自动调用。</p>
+          <p>适用于点点业务页面/活动 H5 自动化测试、免登导航、页面截图、控制台报错排查、本地 dev server 代理映射等任务。</p>
         </div>
 
         <div class="doc-section">
-          <h3>工具列表契约</h3>
-          <table class="doc-table">
-            <thead>
-              <tr>
-                <th style="width: 24%;">工具名</th>
-                <th style="width: 38%;">输入参数</th>
-                <th style="width: 38%;">功能与行为契约</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td><code>browser_navigate</code></td>
-                <td><code>url</code> (必填)<br><code>uid</code> (可选，指定点点账号)<br><code>anonymous</code> (可选，true 为游客态)<br><code>waitFor</code>, <code>timeout</code></td>
-                <td>访问 URL。不传 uid 取当前默认账号免登；指定 uid 切换特定身份；传 anonymous: true 模拟未登录状态。切换时自动隔离并重建 Context。</td>
-              </tr>
-              <tr>
-                <td><code>browser_screenshot</code></td>
-                <td><code>selector</code> (可选)<br><code>fullPage</code> (可选，默认 false)</td>
-                <td>截取指定元素或当前整页，保存至本地图片文件并返回绝对路径。</td>
-              </tr>
-              <tr>
-                <td><code>browser_get_console_errors</code></td>
-                <td>（无参数）</td>
-                <td>返回自导航以来的 console.error 与未捕获异常列表，方便诊断页面 JS 报错。</td>
-              </tr>
-              <tr>
-                <td><code>browser_click_element</code></td>
-                <td><code>selector</code> (必填)<br><code>timeout</code> (可选)</td>
-                <td>在页面中按 CSS/XPath 选择器模拟点击元素（按钮、Tab、确认框等）。</td>
-              </tr>
-              <tr>
-                <td><code>browser_fill_text</code></td>
-                <td><code>selector</code> (必填)<br><code>text</code> (必填)<br><code>timeout</code> (可选)</td>
-                <td>向输入框填入文本，触发 input 与 change 事件。</td>
-              </tr>
-              <tr>
-                <td><code>browser_press_key</code></td>
-                <td><code>key</code> (必填, 如 Enter, Tab, Escape)<br><code>selector</code> (可选)</td>
-                <td>模拟键盘按键，可聚焦特定元素按键或向全局页面按键。</td>
-              </tr>
-              <tr>
-                <td><code>browser_hover</code></td>
-                <td><code>selector</code> (必填)<br><code>timeout</code> (可选)</td>
-                <td>鼠标悬停在指定 DOM 元素上，触发 hover 菜单或 Tooltip 浮层。</td>
-              </tr>
-              <tr>
-                <td><code>browser_scroll</code></td>
-                <td><code>direction</code> ("down" / "up")<br><code>deltaY</code> (可选)<br><code>selector</code> (可选)</td>
-                <td>视口滚动或滚动指定元素进入视图（触底加载等）。</td>
-              </tr>
-              <tr>
-                <td><code>browser_wait_for</code></td>
-                <td><code>selector</code> (可选)<br><code>state</code> ("visible" 等)<br><code>timeout</code> (可选)</td>
-                <td>等待页面整页加载或特定 DOM 元素出现/隐藏。</td>
-              </tr>
-              <tr>
-                <td><code>browser_get_dom</code></td>
-                <td><code>interactiveOnly</code> (默认 true)<br><code>maxDepth</code> (默认 10)</td>
-                <td>提取当前页面结构化可交互 DOM 树（按钮/输入框/链接及其选择器），免去盲猜。</td>
-              </tr>
-              <tr>
-                <td><code>browser_eval_js</code></td>
-                <td><code>script</code> (必填，JS 字符串)</td>
-                <td>在当前页面上下文中执行任意 JavaScript 脚本并返回计算结果。</td>
-              </tr>
-              <tr>
-                <td><code>browser_set_proxy_rule</code></td>
-                <td><code>domain</code> (需匹配 *.tuwan.com)<br><code>port</code> (本地服务端口)<br><code>protocol</code> (http/https)</td>
-                <td>启动/设置本进程内隔离 Whistle 代理，将本地端口映射到干净点点域名，免改 hosts 携带 Cookie。</td>
-              </tr>
-              <tr>
-                <td><code>browser_status</code></td>
-                <td>（无参数）</td>
-                <td>查询当前 MCP 状态：版本号、默认账号 UID、storageState 加载情况、代理规则与数据目录。</td>
-              </tr>
-            </tbody>
-          </table>
+          <h3>自动化执行指导准则</h3>
+          <p>本技能必须通过 <b><code>dd-playwright</code> MCP 服务</b>（提供 <code>browser_*</code> 工具集）执行：</p>
+          
+          <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>
+            <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>
+            <b>3. 页面交互规范：</b><br>
+            • 复杂或动态页面定位困难时，优先调用 <code>browser_get_dom</code> 获取可见元素清单，严禁盲猜选择器。<br>
+            • 表单填写使用 <code>browser_fill_text</code>，按键使用 <code>browser_press_key</code>。
+          </div>
         </div>
-      </div>
     </div>
     <!-- TAB 4: 全局配置 -->
     <div id="pane-settings" class="tab-pane">
@@ -453,11 +408,25 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
             <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>
+
+        <!-- Chromium 浏览器内核状态展示卡片 -->
+        <div style="margin-top: 20px; padding: 16px; background: #0f172a; border-radius: 8px; border: 1px solid var(--border);">
+          <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px;">
+            <div style="font-size: 14px; font-weight: 600; display: flex; align-items: center; gap: 8px;">
+              <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="4"/><line x1="21.17" y1="8" x2="12" y2="8"/><line x1="3.95" y1="6.06" x2="8.54" y2="14"/><line x1="10.88" y1="21.94" x2="15.46" y2="14"/></svg>
+              Chromium 浏览器内核
+            </div>
+            <span id="chromiumStatusBadge" style="font-size: 11px; padding: 2px 8px; border-radius: 4px; background: #334155; color: var(--muted);">检测中...</span>
+          </div>
+          <div id="chromiumDetails" style="font-size: 12px; color: var(--muted); line-height: 1.8;">
+            <div>版本号：<span id="chromiumVersion" style="color: #cbd5e1; font-family: monospace;">加载中...</span></div>
+            <div>执行路径：<span id="chromiumPath" style="color: #cbd5e1; font-family: monospace; word-break: break-all;">加载中...</span></div>
+          </div>
+        </div>
       </div>
     </div>
 
@@ -628,6 +597,53 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
         });
       }
     }
+    function installToCursor() {
+      const serverName = 'dd-playwright';
+      let mcpConfigObj = {
+        command: 'node',
+        args: []
+      };
+      const localCode = document.getElementById('code-mcp-local')?.innerText;
+      if (localCode) {
+        try {
+          const parsed = JSON.parse(localCode);
+          const cfg = parsed.mcpServers?.[serverName];
+          if (cfg) {
+            mcpConfigObj = cfg;
+          }
+        } catch {}
+      }
+
+      // Cursor 官方标准格式：
+      // 路由为 anysphere.cursor-deeplink/mcp/install
+      // config 参数需为 Base64 编码的 JSON 字符串
+      const jsonStr = JSON.stringify(mcpConfigObj);
+      // 处理 UTF-8 字符的 Base64 编码
+      const base64Config = btoa(encodeURIComponent(jsonStr).replace(/%([0-9A-F]{2})/g, (match, p1) => {
+        return String.fromCharCode('0x' + p1);
+      }));
+      const cursorUrl = 'cursor://anysphere.cursor-deeplink/mcp/install?name=' + encodeURIComponent(serverName) + '&config=' + encodeURIComponent(base64Config);
+      // 唤起 Cursor
+      window.location.href = cursorUrl;
+    }
+    function installSkillToCursor() {
+      const ruleName = 'dd-playwright';
+      const compactRule = [
+        '---',
+        'description: 通过 dd-playwright MCP 服务（提供 browser_* 工具集）进行点点前端业务自动化测试、免登调试、页面截图排查与 dev server 代理映射',
+        'globs: *',
+        '---',
+        '# dd-playwright 自动化指南',
+        '本技能必须通过 dd-playwright MCP 服务提供的 browser_* 系列工具执行：',
+        '1. 登录态与身份切换：访问点点页面调用本 MCP 的 browser_navigate 自动注入激活账号免登；排查游客态或未登录拦截必须传 anonymous: true；指定测试账号传特定 uid。',
+        '2. 本地 Dev Server 联调：严禁修改系统 hosts。先调用本 MCP 的 browser_set_proxy_rule 将本地端口映射到点点子域名（如 127.0.0.1:9527 映射为 p9527-test.tuwan.com），免改 hosts 携带线上 Cookie。',
+        '3. 页面交互规范：定位困难时优先调用 browser_get_dom 提取可见元素结构，严禁盲猜选择器；表单填写使用 browser_fill_text，按键使用 browser_press_key。'
+      ].join('\\n');
+
+      const cursorUrl = 'cursor://anysphere.cursor-deeplink/rule?name=' + encodeURIComponent(ruleName) + '&text=' + encodeURIComponent(compactRule);
+      window.location.href = cursorUrl;
+    }
+
 
     async function loadSettings() {
       try {
@@ -667,9 +683,35 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
       }
     }
 
-    // 初次加载账号与配置
+    async function loadChromiumMeta() {
+      try {
+        const res = await fetch('/api/chromium');
+        const data = await res.json();
+        const badge = document.getElementById('chromiumStatusBadge');
+        const versionEl = document.getElementById('chromiumVersion');
+        const pathEl = document.getElementById('chromiumPath');
+        if (!badge || !versionEl || !pathEl) return;
+        
+        if (data.ok && data.meta && data.meta.installed) {
+          badge.innerText = '已安装就绪';
+          badge.style.background = 'rgba(16, 185, 129, 0.15)';
+          badge.style.color = 'var(--success)';
+          versionEl.innerText = data.meta.version || '已安装 (Playwright 托管)';
+          pathEl.innerText = data.meta.executablePath || '-';
+        } else {
+          badge.innerText = '未就绪 (首次调用将自动安装)';
+          badge.style.background = 'rgba(239, 68, 68, 0.15)';
+          badge.style.color = 'var(--danger)';
+          versionEl.innerText = '未检测到内核';
+          pathEl.innerText = data.meta?.executablePath || '-';
+        }
+      } catch {}
+    }
+
+    // 初次加载账号、配置与内核状态
     loadAccounts();
     loadSettings();
+    loadChromiumMeta();
   </script>
 </body>
 </html>`;
@@ -722,51 +764,29 @@ export function createWebServer({ accountStore, authManager }) {
         2,
       );
 
-      let bannerStyle = "";
-      let bannerContent = "";
-      let configSections = "";
+      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>`;
 
-      if (isInstalledViaNpm) {
-        bannerStyle = "background: rgba(16, 185, 129, 0.12); border: 1px solid rgba(16, 185, 129, 0.3); color: #34d399;";
-        bannerContent = "📦 <b>环境检测结果：已通过 npm 安装分发包</b><br><span style='color:#cbd5e1; font-size:12px;'>已自动为您推荐「全局命令配置」，直接配置命令即可被系统全局识别并运行。</span>";
-        
-        configSections = `
-          <div class="code-title">
-            <span>推荐方式：全局命令方式（最推荐）</span>
-            <button class="copy-btn" onclick="copyCode('code-mcp-global')">复制代码</button>
-          </div>
-          <div id="code-mcp-global" class="code-block">${globalConfigStr}</div>
-
-          <div class="code-title" style="margin-top: 24px;">
-            <span style="color: var(--muted);">备用方式：模块绝对路径方式</span>
-            <button class="copy-btn" onclick="copyCode('code-mcp-local')">复制代码</button>
-          </div>
-          <div id="code-mcp-local" class="code-block">${localConfigStr}</div>
-        `;
-      } else {
-        bannerStyle = "background: rgba(59, 130, 246, 0.12); border: 1px solid rgba(59, 130, 246, 0.3); color: #60a5fa;";
-        bannerContent = "💻 <b>环境检测结果：本地源码目录运行（开发/克隆模式）</b><br><span style='color:#cbd5e1; font-size:12px;'>已实时解析您当前的本地绝对路径，无需全局安装即可直接挂载；若希望使用全局命令，可在根目录执行一次 <code>npm link</code>。</span>";
-
-        configSections = `
-          <div class="code-title">
-            <span>推荐方式：本地源码绝对路径方式（免全局安装，当前代码实时生效）</span>
-            <button class="copy-btn" onclick="copyCode('code-mcp-local')">复制代码</button>
-          </div>
-          <div id="code-mcp-local" class="code-block">${localConfigStr}</div>
+      let configSections = `
+        <div class="code-title">
+          <span>本地绝对路径配置（推荐，开箱即用）</span>
+          <button class="copy-btn" onclick="copyCode('code-mcp-local')">复制代码</button>
+        </div>
+        <div id="code-mcp-local" class="code-block">${localConfigStr}</div>
+      `;
 
-          <div class="code-title" style="margin-top: 24px;">
-            <span style="color: var(--muted);">备用方式：全局命令方式（需在项目根目录下先执行 npm link）</span>
-            <button class="copy-btn" onclick="copyCode('code-mcp-global')">复制代码</button>
-          </div>
-          <div id="code-mcp-global" class="code-block">${globalConfigStr}</div>
-        `;
-      }
+      const pkgPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+      let pkgVersion = "0.1.0";
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        pkgVersion = pkg.version || "0.1.0";
+      } catch {}
 
       const renderedHtml = DASHBOARD_HTML
+        .replace("{{VERSION}}", pkgVersion)
         .replace("{{BANNER_STYLE}}", bannerStyle)
         .replace("{{BANNER_CONTENT}}", bannerContent)
         .replace("{{CONFIG_SECTIONS}}", configSections);
-
       sendHtml(res, renderedHtml);
       return;
     }
@@ -782,6 +802,48 @@ export function createWebServer({ accountStore, authManager }) {
       }
       return;
     }
+    // 2.1 获取 SKILL.md 原始内容
+    if (pathname === "/api/skill" && req.method === "GET") {
+      try {
+        const { readFileSync } = await import("node:fs");
+        const skillPath = fileURLToPath(new URL("../../SKILL.md", import.meta.url));
+        const content = readFileSync(skillPath, "utf8");
+        sendJson(res, 200, { ok: true, content });
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    // 2.2 下载 SKILL.md 附件
+    if (pathname === "/api/skill/download" && req.method === "GET") {
+      try {
+        const { readFileSync } = await import("node:fs");
+        const skillPath = fileURLToPath(new URL("../../SKILL.md", import.meta.url));
+        const content = readFileSync(skillPath, "utf8");
+        res.writeHead(200, {
+          "Content-Type": "text/markdown; charset=utf-8",
+          "Content-Disposition": 'attachment; filename="SKILL.md"',
+          "Cache-Control": "no-cache",
+        });
+        res.end(content);
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+    // 2.3 获取 Chromium 内核元数据
+    if (pathname === "/api/chromium" && req.method === "GET") {
+      try {
+        const meta = await getChromiumMetadata();
+        sendJson(res, 200, { ok: true, meta });
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+
 
     // 3. 切换激活账号
     if (pathname === "/api/switch" && req.method === "POST") {