kimi-webbridge-dsh 1.4.6 → 1.4.8

package/README.md

@@ -1,9 +1,9 @@
 # kimi-webbridge-dsh
 
-Kimi WebBridge 的 dsh 插件（**基础设施 + 技能注册**）。插件本身不代理浏览器操作，而是负责：
+Kimi 浏览器扩展（**Kimi Browser Extension**，原 Kimi WebBridge）的 dsh 插件（**基础设施 + 技能注册**）。插件本身不代理浏览器操作，而是负责：
 
 1. **保障桥完好**：守护进程二进制缺失时自动从官方 CDN 下载（跨平台、SHA-256 校验），守护进程未运行时自动拉起；
-2. **注册 skill**：启动时把随包内置的 `skill.md` 注册为运行时 skill（`ctx.skills.register`，`source: bundled`），模型通过 `skill` 工具加载它，按文档用 HTTP 行使全部浏览器能力（17 个动作）；
+2. **注册 skill**：启动时把随包内置的 `skill.md` 注册为运行时 skill（`ctx.skills.register`，`source: bundled`），模型通过 `skill` 工具加载它，按文档用 HTTP 行使全部浏览器能力（25 个动作）；
 3. **注册一个瘦工具 `kimi_webbridge`**：只有 `status` 一个动作（守护进程 + 扩展健康检查），作为其他 skill（如 x-cli 系列）的桥健康锚点。
 
 ## 架构
@@ -11,7 +11,7 @@ Kimi WebBridge 的 dsh 插件（**基础设施 + 技能注册**）。插件本
 | 层 | 角色 |
 |---|---|
 | 插件（本包） | 守护进程二进制供应 + 自动启动；apply() 时注册运行时 skill |
-| skill（运行时注册，随包内置 `skill.md`） | 模型经 `skill` 工具加载，按文档驱动守护进程：navigate / find_tab / snapshot / click / mouse_click / fill / key_type / send_keys / evaluate / cdp / screenshot / network / upload / save_as_pdf / list_tabs / close_tab / close_session |
+| skill（运行时注册，随包内置 `skill.md`） | 模型经 `skill` 工具加载，按文档驱动守护进程：navigate / find_tab / snapshot / read_page / find / click / mouse_click / hover / drag / fill / key_type / send_keys / select_option / dialog / evaluate / cdp / screenshot / network / upload / save_as_pdf / scroll / wait / list_tabs / close_tab / close_session |
 | 瘦工具 `kimi_webbridge` | 仅 `status` 健康检查（自带守护进程自愈） |
 
 ## 安装（一次性，零手工配置）
@@ -30,20 +30,38 @@ dsh plugin --profile web add kimi-webbridge-dsh
 
 ## 依赖
 
-- **浏览器扩展**：需安装并连接 Kimi WebBridge 浏览器扩展 —— 从 [Chrome Web Store](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) 安装（`kimi_webbridge status` 显示 `extension_connected: true`；扩展版本应与守护进程一致）。
+- **浏览器扩展**：需安装并连接 Kimi 浏览器扩展（Kimi Browser Extension，原 Kimi WebBridge）—— 从 [Chrome Web Store](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) 安装（`kimi_webbridge status` 显示 `extension_connected: true`；扩展版本应与守护进程一致）。
 - **守护进程**：无需预装。插件在守护进程不可达时会自动启动它；二进制缺失时会自动从官方 CDN（cdn.kimi.com，与官方安装器同源）下载安装——全程无需手动运行任何安装命令。
 
+### 版本对齐
+
+插件按官方 CDN 的 `version.json` 供应守护进程，因此始终与官方发布对齐；上表的存档哈希对应 **v2.0.8**（守护进程与扩展的产品名已更名为 Kimi Browser Extension）。
+
+`kimi_webbridge` 的 `status` 会原样透出守护进程的 `update_available`（有更新时）与 `version_mismatch`（守护进程与扩展不同步时）字段。按官方约定：这两个字段出现时**不要**自动执行 `upgrade` / `stop` / `restart` / `uninstall`（它们会杀掉正在运行的守护进程），而应把字段里的 `command` 原样交给用户执行。
+
+### 兼容性（dsh 版本）
+
+插件只 import 宿主提供的 `@deepseek-ai/*` 包，并声明为 `peerDependencies`（不打包自己的副本），所以与 dsh 版本解耦；已在 **dsh 0.1.5-rc.1** 上验证（工具注册、skill 注册、system prompt 注入、守护进程自愈均正常）。
+
+| peer | 声明范围 |
+|---|---|
+| `@deepseek-ai/dsh-tools` | `^0.1.0-rc.7 \|\| ^0.1.1-rc.2 \|\| ^0.1.2-rc.1 \|\| ^0.1.5-rc.1` |
+| `@deepseek-ai/dsh-llm` | 同上 |
+| `@deepseek-ai/schemastery` | `^3.18.1` |
+
+⚠️ **预发布版必须逐个元组写进范围。** node-semver 只在范围里存在一个**与该版本 `major.minor.patch` 完全一致、且自身带预发布标签**的比较符时才放行预发布版；因此看起来很宽的 `>=0.0.1-rc.1 <0.2.0` 会静默排除所有预发布构建，用户会遇到 `ERESOLVE`。dsh 发布新的预发布系列（如 `0.1.6-rc.1`）时，需要同步追加一个 `|| ^<新元组>-rc.N` 分支。
+
 ### 跨平台支持
 
 插件根据运行时硬件自动选择并下载对应的守护进程二进制（含 SHA-256 校验，与官方清单核对后才安装）：
 
-| 平台 | 二进制 | 存档哈希（v1.11.6） |
+| 平台 | 二进制 | 存档哈希（v2.0.8） |
 |---|---|---|
-| Windows x64 | `windows-amd64.exe` | `e085991e…90520` |
-| macOS arm64 | `darwin-arm64` | `46fe401e…c9930` |
-| macOS x64 | `darwin-amd64` | `edd1b126…e1ec54` |
-| Linux arm64 | `linux-arm64` | `b1b139bf…b7923d` |
-| Linux x64 | `linux-amd64` | `5c6eaf79…0150d` |
+| Windows x64 | `windows-amd64.exe` | `eec1976d…433c6` |
+| macOS arm64 | `darwin-arm64` | `04532d77…0a261` |
+| macOS x64 | `darwin-amd64` | `931769e9…8cc0c` |
+| Linux arm64 | `linux-arm64` | `ee201b44…34a3c` |
+| Linux x64 | `linux-amd64` | `61de010c…ce271` |
 
 不支持的平台组合会明确报错并提示手动安装。
 
@@ -58,16 +76,17 @@ dsh plugin --profile web add kimi-webbridge-dsh
 
 下载流程：先落盘为临时文件（`kimi-webbridge(.exe).tmp-{pid}-{时间戳}`）→ SHA-256 与官方清单核对 → 匹配才重命名为最终路径；不匹配则删除临时文件并中止，任何未验证的二进制都不会留在磁盘。该路径与官方安装器 / `kimi-webbridge upgrade` 命令完全一致，插件、官方工具共用同一份守护进程。
 
-## 功能（skill 承载，17 个动作）
+## 功能（skill 承载，25 个动作）
 
 | 能力 | 动作 |
 |---|---|
 | 导航 / 标签 | `navigate`、`find_tab`、`list_tabs`、`close_tab`、`close_session` |
-| 读页面 | `snapshot`（accessibility tree + `@e` 引用） |
-| 点击 / 输入 | `click`、`mouse_click`（真实鼠标，可信输入）、`fill`、`key_type`（键入，可信）、`send_keys`（组合键） |
+| 读页面 | `snapshot`（accessibility tree + `@e` 引用）、`read_page`（全文文本）、`find`（页面内搜索） |
+| 点击 / 输入 | `click`、`mouse_click`（真实鼠标，可信输入）、`hover`、`drag`、`fill`、`key_type`（键入，可信）、`send_keys`（组合键）、`select_option`、`dialog` |
 | JS / CDP | `evaluate`（页面上下文）、`cdp`（chrome.debugger 直通） |
 | 截图 / PDF | `screenshot`、`save_as_pdf`（写文件、返回路径） |
 | 网络 / 上传 | `network`（请求捕获）、`upload`（文件上传） |
+| 滚动 / 等待 | `scroll`（滚动/定位）、`wait`（等待文本/选择器条件） |
 | 会话分组 | 一个任务 = 一个 session = 一个标签页组，可一键清理 |
 
 ## 配置（可选）
@@ -78,7 +97,7 @@ dsh plugin --profile web add kimi-webbridge-dsh
 - id: kimi-webbridge
   config:
     autoInstallDaemon: false
-    daemonVersion: v1.11.6
+    daemonVersion: v2.0.8
 ```
 
 | 配置项 | 默认值 | 说明 |
@@ -86,8 +105,8 @@ dsh plugin --profile web add kimi-webbridge-dsh
 | `baseUrl` | `http://127.0.0.1:10086` | 守护进程地址 |
 | `requestTimeoutMs` | `120000` | 单次请求超时（毫秒） |
 | `autoStartDaemon` | `true` | 守护进程未运行时自动启动 |
-| `autoInstallDaemon` | `true` | 二进制缺失时自动从官方 CDN 下载安装（关闭后需手动[从官方安装](https://www.kimi.ai/products/kimi-webbridge)） |
-| `daemonVersion` | `latest` | 自动安装时的版本（可固定如 `v1.11.6`，需带 `v` 前缀与 CDN 路径一致） |
+| `autoInstallDaemon` | `true` | 二进制缺失时自动从官方 CDN 下载安装（关闭后需手动[从官方安装](https://www.kimi.com/products/kimi-webbridge)） |
+| `daemonVersion` | `latest` | 自动安装时的版本（可固定如 `v2.0.8`，需带 `v` 前缀与 CDN 路径一致；建议与扩展版本匹配） |
 | `registerSkill` | `true` | 启动时把 `kimi-webbridge` skill 注册进运行时 registry（关闭后不注册） |
 
 ## 移除

package/lib/index.js

@@ -3,12 +3,12 @@ import { TOOL_ABORTED, defineTool } from "@deepseek-ai/dsh-tools";
 import { HarnessError } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { once } from "node:events";
 import { createWriteStream, existsSync, readFileSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, rm } from "node:fs/promises";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
 
 /**
@@ -17,11 +17,15 @@ import { fileURLToPath } from "node:url";
  * Infrastructure-only bridge plugin:
  * - provisions the daemon binary (official Kimi CDN, SHA-256 verified) and
  *   auto-starts it, keeping the bridge healthy;
- * - registers the packaged skill.md (the full 17-action HTTP protocol for
+ * - registers the packaged skill.md (the full 25-action HTTP protocol for
  *   driving the user's real browser) as a runtime skill via ctx.skills;
  * - registers one thin tool `kimi_webbridge` whose only action is `status`
  *   (daemon + extension health check) as an anchor for other skills.
  *
+ * Outbound HTTP uses the platform `fetch`, so requests inherit the process-wide
+ * proxy policy the harness installs from the launch environment (`HTTP_PROXY`,
+ * `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`); loopback traffic is never proxied.
+ *
  * A browser extension must still be connected for browser actions to work.
  *
  * @module kimi-webbridge-dsh
@@ -80,7 +84,7 @@ function releasePlatform() {
  * @returns a short human-readable install instruction.
  */
 function manualInstallHint() {
-  const page = "https://www.kimi.ai/products/kimi-webbridge";
+  const page = "https://www.kimi.com/products/kimi-webbridge";
   if (process.platform === "win32") {
     return `run \"irm https://cdn.kimi.com/webbridge/install.ps1 | iex\" in PowerShell (or install from ${page})`;
   }
@@ -101,106 +105,136 @@ function readSkillBody() {
   return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "skill.md"), "utf8");
 }
 
+/** Underlying transport `code` for a rejected `fetch`, which buries it one level down in `cause`. */
+function transportErrorCode(error) {
+  const cause = error?.cause;
+  return cause?.code ?? cause?.errors?.[0]?.code ?? error?.code;
+}
+
+/** Human-readable reason for a rejected `fetch`, preferring the transport cause over "fetch failed". */
+function transportErrorMessage(error) {
+  const cause = error?.cause;
+  return cause?.errors?.[0]?.message ?? cause?.message ?? error?.message ?? String(error);
+}
+
+/**
+ * Shape a rejected `fetch` into the error this plugin's callers expect.
+ *
+ * A caller abort surfaces as a bare `aborted` error, which the tool maps to the canonical abort;
+ * a timeout names itself; and a transport failure keeps the underlying `code` (`ECONNREFUSED`,
+ * `ENOTFOUND`, …) so daemon self-healing still recognizes an unreachable local daemon.
+ *
+ * @param error - the rejection from `fetch` or from consuming its body.
+ * @param options - caller signal, whether our own timeout fired, and that timeout.
+ * @returns the error to throw.
+ */
+function fetchFailure(error, { signal, timedOut, timeoutMs } = {}) {
+  if (signal?.aborted) return new Error("aborted");
+  if (timedOut || error?.name === "TimeoutError") {
+    return new Error(`kimi-webbridge: request timed out after ${timeoutMs}ms`);
+  }
+  const failure = new Error(transportErrorMessage(error));
+  const code = transportErrorCode(error);
+  if (code !== void 0) failure.code = code;
+  return failure;
+}
+
 /**
  * One HTTP JSON round-trip with a timeout and caller-abort support.
+ *
+ * Uses the platform `fetch`, so the request inherits the process-wide proxy policy the harness
+ * installs from the launch environment. An already-aborted caller signal fails immediately,
+ * without issuing a request.
+ *
  * @param url - absolute URL.
  * @param options - method, optional JSON body, timeout, and AbortSignal.
  * @returns the parsed JSON body (or raw text fallback) plus the status code.
  */
-function httpJson(url, { method = "GET", body, timeoutMs, signal } = {}) {
-  return new Promise((resolve, reject) => {
-    let target;
-    try {
-      target = new URL(url);
-    } catch (error) {
-      reject(new Error(`kimi-webbridge: invalid baseUrl ${url}: ${String(error)}`));
-      return;
-    }
-    const transport = target.protocol === "https:" ? httpsRequest : httpRequest;
-    const payload = body === void 0 ? void 0 : JSON.stringify(body);
-    let req;
-    let timer;
-    const abort = (error) => {
-      clearTimeout(timer);
-      if (req) req.destroy(error);
-      else reject(error);
-    };
-    timer = setTimeout(() => abort(new Error(`kimi-webbridge: request timed out after ${timeoutMs}ms`)), timeoutMs);
-    const onSignal = () => abort(new Error("aborted"));
-    if (signal?.aborted) onSignal();
-    else signal?.addEventListener("abort", onSignal, { once: true });
-    req = transport(target, {
+async function httpJson(url, { method = "GET", body, timeoutMs, signal } = {}) {
+  try {
+    new URL(url);
+  } catch (error) {
+    throw new Error(`kimi-webbridge: invalid baseUrl ${url}: ${String(error)}`);
+  }
+  // Fail fast: never issue a request the caller has already cancelled.
+  if (signal?.aborted) throw new Error("aborted");
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  timer.unref?.();
+  const onCallerAbort = () => controller.abort();
+  signal?.addEventListener("abort", onCallerAbort, { once: true });
+  const payload = body === void 0 ? void 0 : JSON.stringify(body);
+  try {
+    const response = await fetch(url, {
       method,
-      headers: payload !== void 0 ? { "Content-Type": "application/json" } : {}
-    }, (res) => {
-      const chunks = [];
-      res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", onSignal);
-        const text = Buffer.concat(chunks).toString("utf8");
-        let parsed;
-        try {
-          parsed = text.length > 0 ? JSON.parse(text) : null;
-        } catch {
-          parsed = { raw: text };
-        }
-        resolve({ status: res.statusCode ?? 0, body: parsed, text });
-      });
+      headers: payload === void 0 ? void 0 : { "Content-Type": "application/json" },
+      body: payload,
+      signal: controller.signal
     });
-    req.on("error", (error) => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onSignal);
-      reject(error);
-    });
-    if (payload !== void 0) req.write(payload);
-    req.end();
-  });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text.length > 0 ? JSON.parse(text) : null;
+    } catch {
+      parsed = { raw: text };
+    }
+    return { status: response.status, body: parsed, text };
+  } catch (error) {
+    throw fetchFailure(error, { signal, timedOut, timeoutMs });
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onCallerAbort);
+  }
 }
 
 /**
- * Download a file to disk, following up to maxRedirects redirects.
+ * Stream an HTTP response body to disk, following redirects.
+ *
+ * Uses the platform `fetch`, so a CDN download works behind the proxy the harness installs from
+ * the launch environment. The timeout is an *idle* budget — it restarts on every received chunk —
+ * so a large but progressing download is never cut off, matching the socket idle timeout the
+ * previous `node:http` implementation relied on.
+ *
  * @param url - absolute download URL.
  * @param dest - destination file path.
- * @param options - per-request timeout and redirect budget.
+ * @param options - per-chunk idle timeout in milliseconds.
  * @returns the destination path on success.
  */
-function downloadFile(url, dest, { timeoutMs, maxRedirects = 3 } = {}) {
-  return new Promise((resolve, reject) => {
-    const fetch = (targetUrl, depth) => {
-      let target;
-      try {
-        target = new URL(targetUrl);
-      } catch (error) {
-        reject(new Error(`kimi-webbridge: invalid download URL ${targetUrl}: ${String(error)}`));
-        return;
-      }
-      const transport = target.protocol === "https:" ? httpsRequest : httpRequest;
-      const req = transport(target, { method: "GET" }, (res) => {
-        const status = res.statusCode ?? 0;
-        const location = res.headers.location;
-        if (status >= 300 && status < 400 && location !== void 0 && depth > 0) {
-          res.resume();
-          fetch(new URL(location, target).toString(), depth - 1);
-          return;
-        }
-        if (status < 200 || status >= 300) {
-          res.resume();
-          reject(new Error(`download failed: HTTP ${status} for ${targetUrl}`));
-          return;
-        }
-        const file = createWriteStream(dest);
-        res.pipe(file);
-        file.on("finish", () => file.close(() => resolve(dest)));
-        file.on("error", reject);
-        res.on("error", reject);
-      });
-      req.on("error", reject);
-      req.setTimeout(timeoutMs, () => req.destroy(new Error(`download timed out after ${timeoutMs}ms`)));
-      req.end();
-    };
-    fetch(url, maxRedirects);
-  });
+async function downloadFile(url, dest, { timeoutMs }) {
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer;
+  const arm = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+  };
+  arm();
+  const file = createWriteStream(dest);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) throw new Error(`download failed: HTTP ${response.status} for ${url}`);
+    for await (const chunk of Readable.fromWeb(response.body)) {
+      arm();
+      if (!file.write(chunk)) await once(file, "drain");
+    }
+    await new Promise((resolve, reject) => {
+      file.end((error) => (error ? reject(error) : resolve()));
+    });
+    return dest;
+  } catch (error) {
+    file.destroy();
+    throw fetchFailure(error, { timedOut, timeoutMs });
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
 /**
@@ -220,7 +254,7 @@ function downloadFile(url, dest, { timeoutMs, maxRedirects = 3 } = {}) {
 async function installDaemonBinary({ version, timeoutMs }) {
   const platform = releasePlatform();
   if (platform === null) {
-    throw new Error(`unsupported platform ${process.platform}-${process.arch} — install the daemon manually (see https://www.kimi.com/zh-cn/features/webbridge)`);
+    throw new Error(`unsupported platform ${process.platform}-${process.arch} — install the daemon manually (see https://www.kimi.com/products/kimi-webbridge)`);
   }
   const manifestKey = platform.endsWith(".exe") ? platform.slice(0, -4) : platform;
   const bin = daemonBinPath();
@@ -238,15 +272,20 @@ async function installDaemonBinary({ version, timeoutMs }) {
     // Manifest unavailable (e.g. old pinned version) — install without checksum.
   }
   const tmp = `${bin}.tmp-${process.pid}-${Date.now()}`;
-  await downloadFile(url, tmp, { timeoutMs });
-  if (expectedSha !== null) {
-    const actual = createHash("sha256").update(await readFile(tmp)).digest("hex");
-    if (actual !== expectedSha) {
-      await rm(tmp, { force: true });
-      throw new Error(`downloaded binary SHA-256 mismatch for ${platform}: expected ${expectedSha}, got ${actual}`);
+  try {
+    await downloadFile(url, tmp, { timeoutMs });
+    if (expectedSha !== null) {
+      const actual = createHash("sha256").update(await readFile(tmp)).digest("hex");
+      if (actual !== expectedSha) {
+        throw new Error(`downloaded binary SHA-256 mismatch for ${platform}: expected ${expectedSha}, got ${actual}`);
+      }
     }
+    await rename(tmp, bin);
+  } catch (error) {
+    // Never leave a partial or unverified download behind.
+    await rm(tmp, { force: true }).catch(() => {});
+    throw error;
   }
-  await rename(tmp, bin);
   if (process.platform !== "win32") await chmod(bin, 0o755);
   return { bin, url, sha256: expectedSha };
 }
@@ -273,6 +312,24 @@ function abortError() {
   return error;
 }
 
+/**
+ * Compare two dotted numeric versions, ignoring any prerelease/build suffix.
+ * @param a - left version (no leading "v").
+ * @param b - right version (no leading "v").
+ * @returns -1, 0, or 1.
+ */
+function compareVersions(a, b) {
+  const parts = (value) => value.split(/[.\-+]/).map((piece) => Number.parseInt(piece, 10));
+  const left = parts(a);
+  const right = parts(b);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const x = Number.isNaN(left[index]) ? 0 : left[index] ?? 0;
+    const y = Number.isNaN(right[index]) ? 0 : right[index] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 /** Shape one daemon response into the canonical tool value. */
 function canonicalResult(result) {
   if (result.status >= 200 && result.status < 300) {
@@ -323,7 +380,7 @@ function apply(ctx, config = {}) {
 
   ctx.tools.register(defineTool({
     name: "kimi_webbridge",
-    description: "Health check for the local kimi-webbridge bridge (daemon at " + baseUrl + " and the browser extension). The plugin auto-provisions the daemon: it installs the binary from the official Kimi CDN when missing and starts it, then retries once. Returns daemon version/uptime and extension_connected. This tool does NOT perform browser actions — for navigation, clicking, typing, reading pages, screenshots, JS evaluation, CDP, uploads, PDF export and tab management, load the kimi-webbridge skill, which documents the full 17-action HTTP protocol (POST " + baseUrl + "/command) to drive the user's real browser.",
+    description: "Health check for the local kimi-webbridge bridge (daemon at " + baseUrl + " and the browser extension). The plugin auto-provisions the daemon: it installs the binary from the official Kimi CDN when missing and starts it, then retries once. Returns daemon version/uptime, extension_connected, plus version (daemon) and extension_version (extension) — a mismatch means the components have drifted (the extension likely auto-updated). This tool does NOT perform browser actions — for navigation, clicking, typing, reading pages, screenshots, JS evaluation, CDP, uploads, PDF export and tab management, load the kimi-webbridge skill, which documents the full 25-action HTTP protocol (POST " + baseUrl + "/command) to drive the user's real browser.",
     parameters: {
       action: {
         type: "string",
@@ -338,7 +395,29 @@ function apply(ctx, config = {}) {
         additionalProperties: true
       },
       render(args, value) {
-        return [{ type: "text", text: JSON.stringify(value) }];
+        const blocks = [{ type: "text", text: JSON.stringify(value) }];
+        const norm = (s) => (typeof s === "string" ? s.replace(/^v/i, "") : "");
+        const daemonVer = norm(value?.version);
+        const extVer = norm(value?.extension_version);
+        if (daemonVer && extVer && daemonVer !== extVer) {
+          const daemonAhead = compareVersions(daemonVer, extVer) > 0;
+          blocks.push({
+            type: "text",
+            text: daemonAhead
+              ? `⚠️ the browser extension (${value.extension_version}) is behind the daemon (${value.version}) — ask the user to update the extension, then retry.`
+              : `⚠️ version drift: daemon ${value.version} vs extension ${value.extension_version} — the browser extension likely auto-updated ahead of the daemon. Re-audit the 25-action skill list and update the daemon.`
+          });
+        }
+        // The official convention: surface the release fields verbatim and let the
+        // user run the command — a model-triggered upgrade would kill the daemon.
+        const update = value?.update_available;
+        if (update !== null && typeof update === "object" && typeof update.command === "string") {
+          blocks.push({
+            type: "text",
+            text: `⬆️ update available: daemon ${update.current ?? "?"} → ${update.latest ?? "?"} — tell the user and hand them this command verbatim; do NOT run it yourself: ${update.command}`
+          });
+        }
+        return blocks;
       }
     },
     isConcurrencySafe() {

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "kimi-webbridge-dsh",
-  "description": "Infrastructure plugin for dsh: provisions the kimi-webbridge daemon (auto-install with SHA-256 verification, auto-start) and registers the kimi-webbridge skill that documents the full 17-action browser protocol. Registers a thin kimi_webbridge tool (status health check only).",
-  "version": "1.4.6",
+  "description": "Infrastructure plugin for dsh: provisions the kimi-webbridge daemon (auto-install with SHA-256 verification, auto-start) and registers the kimi-webbridge skill that documents the full 25-action browser protocol. Registers a thin kimi_webbridge tool (status health check only).",
+  "version": "1.4.8",
   "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/cfanmaoli/kimi-webbridge-dsh.git" },
   "type": "module",
   "keywords": [
     "dsh",
@@ -36,8 +37,8 @@
     "cordis.patch.yml"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7 || ^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7 || ^0.1.1-rc.2 || ^0.1.2-rc.1 || ^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   }
 }

package/skill.md

@@ -1,14 +1,14 @@
-# Kimi WebBridge
+# Kimi Browser Extension (Kimi 浏览器扩展, formerly Kimi WebBridge)
 
-Control the user's real browser (their login sessions) through the local daemon at `http://127.0.0.1:10086`.
+Control the user's real browser (their login sessions) through the local daemon at `http://127.0.0.1:10086` (the default address).
 
-> This skill is registered by the `kimi-webbridge-dsh` plugin (plugin v1.4.6 / daemon v1.11.6). Do not hand-edit it.
+> This skill is registered by the `kimi-webbridge-dsh` plugin (plugin v1.4.8 / daemon v2.0.8). Do not hand-edit it.
 
 ## Health check first
 
-Before driving the browser, call the **`kimi_webbridge` tool with action `status`**. It reports daemon + extension health and auto-provisions the daemon (downloads the binary from the official Kimi CDN when missing and starts it, then retries once). `extension_connected: true` means the browser extension is ready; if false, tell the user to install/connect the Kimi WebBridge extension.
+Before driving the browser, call the **`kimi_webbridge` tool with action `status`**. It reports daemon + extension health and auto-provisions the daemon (downloads the binary from the official Kimi CDN when missing and starts it, then retries once). `extension_connected: true` means the browser extension is ready; if false, tell the user to install/connect the Kimi Browser Extension.
 
-## The 17 actions
+## The 25 actions
 
 Every action is one HTTP call: `POST http://127.0.0.1:10086/command` with body `{"action": "<name>", "args": {...}, "session": "<task-name>"}`.
 
@@ -31,6 +31,14 @@ Every action is one HTTP call: `POST http://127.0.0.1:10086/command` with body `
 | `list_tabs` | — | `{success, tabs:[{tabId,url,title,active,groupTitle}]}` | |
 | `close_tab` | — | `{success, closed}` | |
 | `close_session` | — | `{success, closed}` | close all session tabs — only when the user asks |
+| `read_page` | `max_chars?`, `start?` | `{text, complete, screens, chars}` | readable page text, paged — pass `start` to continue when `complete:false` |
+| `find` | `query` | `{url, title, matches}` | search the page (accessibility tree) for a text query |
+| `scroll` | `direction?` up/down, `to?` top/bottom, `selector?`, `text?` | `{scrolled, direction, atTop, atBottom, scrollY}` | scroll the page or an element into view |
+| `hover` | `selector` (`@e` or CSS) | `{success, x, y, tag, text}` | hover over an element |
+| `drag` | `from`, `to` (`@e`/CSS) | `{success, dispatched, verified, dropAccepted}` | HTML5 drag-and-drop from→to |
+| `select_option` | `selector`, `values` (or `value`) | `{success, ...}` | pick options in a native `<select>`; custom dropdowns → click |
+| `dialog` | `action` status/accept/dismiss, `text?` | `{open, type, message}` / `{success, action}` | handle JS dialogs (alert/confirm/prompt) |
+| `wait` | `text?`, `text_gone?`, `selector?`, `timeout_ms?` | `{ok, ...}` / `{ok:false, timedOut, waitedMs}` | wait for a condition (text appears/disappears, selector visible) |
 
 ## Sending requests (shell-proof)
 
@@ -63,6 +71,8 @@ Call `close_session` only when the user explicitly asks to close the tabs.
 - Trusted input: on sites that reject synthetic events (`event.isTrusted` checks — banking portals, captchas), use `mouse_click` instead of `click` and `key_type`/`send_keys` instead of `fill`. If those still fail, tell the user the page needs manual interaction.
 - `send_keys` keys: Enter/Return, Escape/Esc, Tab, Backspace, Delete, Space, ArrowUp/Down/Left/Right, Home/End, PageUp/PageDown, F1–F12, single letters/digits. Modifiers: Alt/Ctrl/Control/Cmd/Meta/Shift, or `Mod` (Cmd on Mac, Ctrl elsewhere). Join with `+` ("Mod+A", "Shift+Tab"); space-separate several ("Enter Escape").
 - Cross-origin iframes are not covered — navigate to the iframe URL directly.
+- `read_page` returns the full readable page text (paged — follow `start` when `complete:false`); `find` searches the page text for a query. Both are text readers; `snapshot` is still how you get `@e` refs for interaction.
+- `scroll` (direction/to/selector/text), `hover`, `drag` (from→to), `select_option` (native `<select>` only), and `dialog` (status/accept/dismiss) cover page interaction; `wait` blocks until a condition (text/selector) is met instead of blind sleeps.
 
 ## Screenshots and PDF
 
@@ -70,10 +80,12 @@ Call `close_session` only when the user explicitly asks to close the tabs.
 
 ## Daemon or extension problems
 
-- Call the `kimi_webbridge` tool (`status`) — the plugin auto-provisions and starts the daemon. Never run `stop` / `restart` / `uninstall` yourself.
-- If an error mentions "Please update the Kimi WebBridge extension", the extension is outdated — ask the user to update it (https://www.kimi.com/features/webbridge).
+- Call the `kimi_webbridge` tool (`status`) — the plugin auto-provisions and starts the daemon. Never run `stop` / `restart` / `upgrade` / `uninstall` yourself: they kill a running daemon.
+- If an error mentions "Please update the Kimi Browser Extension", the extension is outdated — ask the user to update it (https://www.kimi.com/products/kimi-webbridge).
 - If the daemon stays unreachable after the status tool's retry, point the user to the help page instead of deep-troubleshooting.
+- When `status` reports `update_available` or `version_mismatch`, tell the user and hand them that field's `command` verbatim — that is what the field is for. Do **not** run it yourself.
+- If the status tool warns that `version` (daemon) and `extension_version` (extension) differ, one side is behind (the extension follows the browser store's schedule): if the **extension** is behind, ask the user to update it; if the **daemon** is behind, hand them the `upgrade` command. Re-audit the 25-action list above after either change.
 
 ---
 
-Protocol and workflow adapted from the Kimi WebBridge community skill (Apache-2.0). Daemon binary and browser extension by Kimi. This skill is registered by kimi-webbridge-dsh.
+Protocol and workflow adapted from the Kimi Browser Extension community skill (Apache-2.0). Daemon binary and browser extension by Kimi. This skill is registered by kimi-webbridge-dsh.