@taole/dd-playwright 0.2.0 → 0.4.0

package/README.md

@@ -75,10 +75,21 @@ dd-pw version
 # 一键检查并升级到最新版本：
 dd-pw update
 
+# 环境诊断（Node 版本 / Chromium 内核 / 账号库 / Web 服务 / 版本检查）：
+dd-pw doctor
+
+# 诊断并自动修复安全项（当前为缺失的 Chromium 内核）：
+dd-pw doctor --fix
+
+# 获取 npm 最新发布的 Skill 内容和来源版本（JSON，不写本地文件）：
+dd-pw skill get
+
 # （可选）前台阻塞运行（Ctrl+C 退出）：
 dd-pw serve [--port 12309]
 ```
 
+MCP 的 `skill_get_latest` 和 CLI 的 `dd-pw skill get` 获取 npm 最新发布包中的 `SKILL.md`，校验完整性后返回内容与来源版本，不安装 Skill、不修改本地文件或 MCP 配置。Agent 可按当前工具支持的路径安装；覆盖可能包含本地修改的文件前应取得用户授权。升级 dd-pw 后需重新连接 MCP 才能发现新工具；更新 Skill 后可能需要重载 Agent 或开启新会话。
+
 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`。

package/SKILL.md

@@ -9,6 +9,12 @@ description: >-
 
 本技能必须通过 **`dd-playwright` MCP 服务**提供的 `browser_*` 系列工具执行。
 
+## Skill 更新
+- 用户要求更新 dd-playwright Skill 时，调用 MCP `skill_get_latest` 获取 npm 最新发布的完整内容及版本；该工具只读取内容，不安装或修改本地文件。
+- 根据当前工具实际支持的 Skill 路径安装；不确定当前工具、路径或作用域时询问用户，不猜测。尊重用户对 `.agents` 等目录的选择。
+- 写入前检查现有文件并比较内容；若不一致且无法确认没有本地修改，先告知路径和覆盖风险，取得用户明确授权后再覆盖。内容一致则无需写入。
+- 报告来源版本与实际路径；可能需要重载 Agent 或开启新会话。不修改 MCP 配置，也不升级 dd-pw。旧 MCP 缺少该工具时先升级 dd-pw 并重新连接 MCP。
+
 ## 1. 登录态与身份切换
 - **每次导航必须显式选择身份**：默认账号使用 `identity: { mode: "default" }`；游客使用 `identity: { mode: "anonymous" }`；指定账号使用 `identity: { mode: "uid", uid: "28689781" }`。缺少身份或参数冲突会报错。
 - **身份隔离**：相同身份导航复用上下文；切换身份会关闭当前页面并重建上下文。游客模式不注入登录态，默认账号模式使用当前激活账号或配置的凭据。

package/bin/cli.mjs

@@ -9,6 +9,8 @@ import {
   getStoredWebPort,
 } from "../src/server/daemon.mjs";
 import { getLocalVersion, handleUpdateCommand } from "../src/updater.mjs";
+import { runDoctor, formatDoctorReport } from "../src/doctor.mjs";
+import { getLatestSkill } from "../src/skill-manager.mjs";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -23,6 +25,8 @@ dd-playwright (别名: dd-pw) CLI
   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 skill get                      输出 npm 最新发布的 Skill 内容及版本（JSON）
   dd-pw update                         检查远端最新版本并自动升级
   dd-pw mcp                            以 stdio 模式启动 MCP 浏览器服务
   dd-pw --help, -h                     查看帮助信息
@@ -167,6 +171,20 @@ 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 === "skill") {
+    if (args.length !== 2 || args[1] !== "get") {
+      throw new Error("用法：dd-pw skill get");
+    }
+    console.log(JSON.stringify(await getLatestSkill(), null, 2));
   } else if (command === "update" || command === "upgrade") {
     await handleUpdateCommand();
   } else if (command === "mcp") {

package/bin/mcp-server.mjs

@@ -9,6 +9,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import * as z from "zod/v4";
 import { resolveConfig } from "../src/config.mjs";
 import { PlaywrightBrowserManager } from "../src/browser-manager.mjs";
+import { getLatestSkill } from "../src/skill-manager.mjs";
 import { pathToFileURL } from "node:url";
 
 export const MCP_VERSION = "0.1.14";
@@ -445,6 +446,21 @@ export function createBrowserMcpServer({ manager, config }) {
       });
     },
   );
+  server.registerTool(
+    "skill_get_latest",
+    {
+      description: "从 npm 最新发布包获取并校验 dd-playwright 的 SKILL.md，返回包名、版本及完整内容；不安装、不修改本地文件或 MCP 配置。",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        return textResult(await getLatestSkill());
+      } catch (err) {
+        return errorResult("获取 Skill 失败", err);
+      }
+    },
+  );
+
   return server;
 }
 

package/package.json

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

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/skill-manager.mjs

@@ -0,0 +1,80 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+
+const PACKAGE = '@taole/dd-playwright';
+const MAX_ARCHIVE = 20 * 1024 * 1024;
+const MAX_UNPACKED = 50 * 1024 * 1024;
+
+async function fetchBytes(fetchImpl, url, limit) {
+  const response = await fetchImpl(url);
+  if (!response.ok) throw new Error(`Request failed (${response.status}): ${url}`);
+  const length = Number(response.headers?.get('content-length'));
+  if (length > limit) throw new Error('Download exceeds size limit');
+  // Stream when available to avoid buffering an unbounded response.
+  if (response.body?.getReader) {
+    const reader = response.body.getReader();
+    const chunks = []; let size = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.length;
+        if (size > limit) { await reader.cancel(); throw new Error('Download exceeds size limit'); }
+        chunks.push(Buffer.from(value));
+      }
+    } finally { reader.releaseLock(); }
+    return Buffer.concat(chunks, size);
+  }
+  const data = Buffer.from(await response.arrayBuffer());
+  if (data.length > limit) throw new Error('Download exceeds size limit');
+  return data;
+}
+
+function verifyIntegrity(data, integrity) {
+  if (typeof integrity !== 'string') throw new Error('Missing npm dist.integrity');
+  const tokens = integrity.trim().split(/\s+/).map(token => /^(sha512|sha384|sha256)-([A-Za-z0-9+/]+={0,2})(?:\?.*)?$/.exec(token)).filter(Boolean);
+  const algorithm = ['sha512', 'sha384', 'sha256'].find(name => tokens.some(token => token[1] === name));
+  if (!algorithm) throw new Error('Unsupported npm dist.integrity');
+  const actual = createHash(algorithm).update(data).digest();
+  if (!tokens.some(token => {
+    if (token[1] !== algorithm) return false;
+    const expected = Buffer.from(token[2], 'base64');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  })) throw new Error('npm dist.integrity mismatch');
+}
+
+function extractSkill(archive) {
+  const tar = gunzipSync(archive, { maxOutputLength: MAX_UNPACKED });
+  let found = null;
+  for (let offset = 0; offset + 512 <= tar.length;) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) break;
+    const text = (start, end) => header.subarray(start, end).toString('utf8').replace(/\0.*$/, '');
+    const name = text(0, 100);
+    const prefix = text(345, 500);
+    const sizeText = text(124, 136).trim();
+    if (!/^[0-7]+$/.test(sizeText)) throw new Error('Invalid tar entry size');
+    const size = parseInt(sizeText, 8);
+    const start = offset + 512;
+    const next = start + Math.ceil(size / 512) * 512;
+    if (!Number.isSafeInteger(next) || next > tar.length) throw new Error('Truncated tar archive');
+    if ((prefix ? `${prefix}/${name}` : name) === 'package/SKILL.md') {
+      if (found || !['0', '\0'].includes(String.fromCharCode(header[156]))) throw new Error('Invalid SKILL.md tar entry');
+      found = Buffer.from(tar.subarray(start, start + size));
+    }
+    offset = next;
+  }
+  if (!found || !found.length) throw new Error('Package does not contain SKILL.md');
+  return found;
+}
+
+export async function getLatestSkill({ fetchImpl = globalThis.fetch, registry = 'https://registry.npmjs.org' } = {}) {
+  const metadata = JSON.parse((await fetchBytes(fetchImpl, `${registry.replace(/\/$/, '')}/${encodeURIComponent(PACKAGE)}/latest`, 2 * 1024 * 1024)).toString('utf8'));
+  if (metadata.name !== PACKAGE || typeof metadata.version !== 'string' || !metadata.version || typeof metadata.dist?.tarball !== 'string') throw new Error('Invalid npm package metadata');
+  const url = new URL(metadata.dist.tarball);
+  if (url.protocol !== 'https:' && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') throw new Error('Insecure npm tarball URL');
+  const archive = await fetchBytes(fetchImpl, url.href, MAX_ARCHIVE);
+  verifyIntegrity(archive, metadata.dist.integrity);
+  return { package: PACKAGE, version: metadata.version, content: extractSkill(archive).toString('utf8') };
+}
+

package/src/updater.mjs

@@ -122,6 +122,15 @@ 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({