kimi-webbridge-dsh 1.4.0 → 1.4.5

package/README.md

@@ -1,21 +1,36 @@
 # kimi-webbridge-dsh
 
-Kimi WebBridge 的 dsh 插件：通过本机 kimi-webbridge 守护进程（`127.0.0.1:10086`）驱动用户的真实浏览器（保留登录态与 Cookie）。注册一个模型工具 `kimi_webbridge`，覆盖导航、点击、输入、读取页面（accessibility tree + @e 引用）、截图、JS 求值、CDP、网络、上传、PDF 导出、标签页与会话管理。
+Kimi WebBridge 的 dsh 插件（**基础设施 + 技能生成**）。插件本身不代理浏览器操作，而是负责：
 
-## 功能
+1. **保障桥完好**：守护进程二进制缺失时自动从官方 CDN 下载（跨平台、SHA-256 校验），守护进程未运行时自动拉起；
+2. **生成 skill**：启动时把随包内置的 `skill.md` 同步到 `~/.dsh/skills/kimi-webbridge/SKILL.md`，模型通过 `skill` 工具加载它，按文档用 HTTP 行使全部浏览器能力（17 个动作）；
+3. **注册一个瘦工具 `kimi_webbridge`**：只有 `status` 一个动作（守护进程 + 扩展健康检查），作为其他 skill（如 x-cli 系列）的桥健康锚点。
 
-| 能力 | 说明 |
+## 架构
+
+| 层 | 角色 |
 |---|---|
-| 浏览真实页面 | 在用户已登录的浏览器中导航、点击、填表、滚动 |
-| 读页面 | `snapshot` 返回 accessibility tree 与 `@e` 元素引用 |
-| 截图 / 导出 PDF | 结果写入本地文件，返回路径 |
-| JS 求值 / CDP | `evaluate`（页面上下文）、`cdp`（chrome.debugger 直通） |
-| 网络 / 上传 | 请求捕获与文件上传 |
-| 会话分组 | 一个任务 = 一个 session = 一个标签页组，可一键清理 |
+| 插件（本包） | 守护进程二进制供应 + 自动启动；apply() 时同步 skill 文件 |
+| skill（`~/.dsh/skills/kimi-webbridge/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 |
+| 瘦工具 `kimi_webbridge` | 仅 `status` 健康检查（自带守护进程自愈） |
+
+## 安装（一次性，零手工配置）
+
+```powershell
+dsh plugin --profile web add kimi-webbridge-dsh
+```
+
+本包声明了 `dsh.bundle.patch`：`dsh plugin add` 会自动把它登记进 profile 的 bundle 层（`dsh.profile.bundles`），**无需手动编辑任何 cordis.patch.yml**。重启一次 `dsh web`：启动时插件同步 skill 文件，新会话的 skill 目录中即出现 `kimi-webbridge`。
+
+## 用法（模型视角）
+
+1. 需要真实浏览器时，加载 `kimi-webbridge` skill（触发词：browser / webpage / open URL / 浏览器 / 网页 / 截图……）；
+2. 先用 `kimi_webbridge` 工具的 `status` 确认守护进程 + 扩展健康（插件自动补装/拉起二进制）；
+3. 按 skill 文档向 `POST http://127.0.0.1:10086/command` 发送 `{action, args, session}` 行使浏览器能力。Windows 上必须用临时文件承载 JSON（shell 会破坏非 ASCII 文本），skill 里有完整说明。
 
 ## 依赖
 
-- **浏览器扩展**：需安装并连接 Kimi WebBridge 浏览器扩展 —— 从 [Chrome Web Store](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) 安装（`kimi-webbridge status` 显示 `extension_connected: true`；扩展版本应与守护进程一致）。
+- **浏览器扩展**：需安装并连接 Kimi WebBridge 浏览器扩展 —— 从 [Chrome Web Store](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc) 安装（`kimi_webbridge status` 显示 `extension_connected: true`；扩展版本应与守护进程一致）。
 - **守护进程**：无需预装。插件在守护进程不可达时会自动启动它；二进制缺失时会自动从官方 CDN（cdn.kimi.com，与官方安装器同源）下载安装——全程无需手动运行任何安装命令。
 
 ### 跨平台支持
@@ -32,26 +47,28 @@ Kimi WebBridge 的 dsh 插件：通过本机 kimi-webbridge 守护进程（`127.
 
 不支持的平台组合会明确报错并提示手动安装。
 
-## 安装（一次性，零手工配置）
-
-```powershell
-dsh plugin --profile web add kimi-webbridge-dsh
-```
+### 守护进程二进制位置
 
-本包声明了 `dsh.bundle.patch`：`dsh plugin add` 会自动把它登记进 profile 的 bundle 层（`dsh.profile.bundles`），**无需手动编辑任何 cordis.patch.yml**。安装后重启一次 dsh web 即生效（bundle 在启动时加载）：
+下载到用户目录（与官方安装器路径一致，无需管理员权限；按用户隔离）：
 
-```powershell
-dsh web
-```
+| 平台 | 最终路径 |
+|---|---|
+| Windows | `%USERPROFILE%\.kimi-webbridge\bin\kimi-webbridge.exe` |
+| macOS / Linux | `~/.kimi-webbridge/bin/kimi-webbridge`（自动 `chmod 755`） |
 
-## 用法
+下载流程：先落盘为临时文件（`kimi-webbridge(.exe).tmp-{pid}-{时间戳}`）→ SHA-256 与官方清单核对 → 匹配才重命名为最终路径；不匹配则删除临时文件并中止，任何未验证的二进制都不会留在磁盘。该路径与官方安装器 / `kimi-webbridge upgrade` 命令完全一致，插件、官方工具共用同一份守护进程。
 
-模型在新会话中可直接调用 `kimi_webbridge` 工具。核心规则：
+## 功能（skill 承载，17 个动作）
 
-- **一个任务 = 一个 session = 一个标签页组**：任务开始时选一个 session 名，之后每次调用都带上（如 `camping-research`）。
-- **读页面用 snapshot**：返回 accessibility tree 和 `@e` 引用，点击/输入优先用 `@e` 引用而非手写 CSS。
-- **截图返回文件路径**：用 read 工具打开查看。
-- **守护进程不可达**：工具会自动启动；二进制缺失时自动从官方 CDN 下载安装。
+| 能力 | 动作 |
+|---|---|
+| 导航 / 标签 | `navigate`、`find_tab`、`list_tabs`、`close_tab`、`close_session` |
+| 读页面 | `snapshot`（accessibility tree + `@e` 引用） |
+| 点击 / 输入 | `click`、`mouse_click`（真实鼠标，可信输入）、`fill`、`key_type`（键入，可信）、`send_keys`（组合键） |
+| JS / CDP | `evaluate`（页面上下文）、`cdp`（chrome.debugger 直通） |
+| 截图 / PDF | `screenshot`、`save_as_pdf`（写文件、返回路径） |
+| 网络 / 上传 | `network`（请求捕获）、`upload`（文件上传） |
+| 会话分组 | 一个任务 = 一个 session = 一个标签页组，可一键清理 |
 
 ## 配置（可选）
 
@@ -69,8 +86,9 @@ dsh web
 | `baseUrl` | `http://127.0.0.1:10086` | 守护进程地址 |
 | `requestTimeoutMs` | `120000` | 单次请求超时（毫秒） |
 | `autoStartDaemon` | `true` | 守护进程未运行时自动启动 |
-| `autoInstallDaemon` | `true` | 二进制缺失时自动从官方 CDN 下载安装（关闭后需手动运行 `irm https://cdn.kimi.com/webbridge/install.ps1 | iex`） |
+| `autoInstallDaemon` | `true` | 二进制缺失时自动从官方 CDN 下载安装（关闭后需手动[从官方安装](https://www.kimi.ai/products/kimi-webbridge)） |
 | `daemonVersion` | `latest` | 自动安装时的版本（可固定如 `0.3.0`） |
+| `generateSkill` | `true` | 启动时同步 `kimi-webbridge` skill 文件（关闭后不生成/更新） |
 
 ## 移除
 
@@ -78,4 +96,4 @@ dsh web
 dsh plugin --profile web remove kimi-webbridge-dsh
 ```
 
-自动从 bundle 层移除（无需手动删补丁行），重启后生效。
+自动从 bundle 层移除（无需手动删补丁行），重启后生效。skill 文件（`~/.dsh/skills/kimi-webbridge/`）如需一并删除可手动清理。

package/lib/index.js

@@ -4,27 +4,26 @@ import { HarnessError } from "@deepseek-ai/dsh-llm";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createWriteStream, existsSync } from "node:fs";
-import { chmod, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { chmod, mkdir, readFile, rename, rm, writeFile } 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 { fileURLToPath } from "node:url";
 
 /**
  * Kimi WebBridge plugin for dsh.
  *
- * Registers one model-facing tool `kimi_webbridge` that drives the user's real
- * browser (their login sessions) through the local kimi-webbridge daemon at
- * `127.0.0.1:10086`.
+ * Infrastructure-only bridge plugin:
+ * - provisions the daemon binary (official Kimi CDN, SHA-256 verified) and
+ *   auto-starts it, keeping the bridge healthy;
+ * - syncs the packaged skill.md into ~/.dsh/skills/kimi-webbridge/SKILL.md,
+ *   the model-facing skill that documents the full 17-action HTTP protocol
+ *   for driving the user's real browser;
+ * - registers one thin tool `kimi_webbridge` whose only action is `status`
+ *   (daemon + extension health check) as an anchor for other skills.
  *
- * The plugin is self-sufficient: if the daemon binary is missing it is
- * downloaded from the official Kimi CDN (the same source the official
- * installer uses) and started automatically, so no external installer
- * command is required. A browser extension must still be connected for
- * browser actions to work.
- *
- * All requests go straight to the daemon over HTTP, so there are none of the
- * shell-quoting / non-ASCII corruption issues of curl-based integration.
+ * A browser extension must still be connected for browser actions to work.
  *
  * @module kimi-webbridge-dsh
  */
@@ -35,24 +34,8 @@ const name = "kimi-webbridge";
 /** Services required by this plugin. */
 const inject = ["tools", "systemPrompt"];
 
-/** Every action the daemon accepts on POST /command, plus local "status". */
-const ACTIONS = [
-  "status",
-  "navigate",
-  "find_tab",
-  "snapshot",
-  "click",
-  "fill",
-  "evaluate",
-  "cdp",
-  "screenshot",
-  "network",
-  "upload",
-  "save_as_pdf",
-  "list_tabs",
-  "close_tab",
-  "close_session"
-];
+/** The single action of the thin bridge tool. The full browser protocol lives in the generated skill. */
+const ACTIONS = ["status"];
 
 /** Runtime configuration schema for the plugin. */
 const Config = z.object({
@@ -60,7 +43,8 @@ const Config = z.object({
   requestTimeoutMs: z.number().step(1).min(1000).default(120000),
   autoStartDaemon: z.boolean().default(true),
   autoInstallDaemon: z.boolean().default(true),
-  daemonVersion: z.string().default("latest")
+  daemonVersion: z.string().default("latest"),
+  generateSkill: z.boolean().default(true)
 });
 
 /** Official release CDN base. */
@@ -91,6 +75,52 @@ function releasePlatform() {
   return null;
 }
 
+/**
+ * Platform-aware manual-install hint shown when auto-install is disabled or fails.
+ * Windows users get the PowerShell one-liner; macOS/Linux users get the bash one-liner.
+ * @returns a short human-readable install instruction.
+ */
+function manualInstallHint() {
+  const page = "https://www.kimi.ai/products/kimi-webbridge";
+  if (process.platform === "win32") {
+    return `run \"irm https://cdn.kimi.com/webbridge/install.ps1 | iex\" in PowerShell (or install from ${page})`;
+  }
+  return `run \"curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash\" (or install from ${page})`;
+}
+
+/** Directory the DSH skill loader scans for the generated skill. */
+function skillDir() {
+  return join(homedir(), ".dsh", "skills", "kimi-webbridge");
+}
+
+/**
+ * Sync the packaged skill.md into the DSH skills directory so the model can
+ * load it with the skill tool. Rewrites only when missing or changed, so
+ * restarts stay cheap and updates propagate automatically.
+ * @returns true when the file was (re)written.
+ */
+async function syncSkill() {
+  try {
+    const source = join(dirname(fileURLToPath(import.meta.url)), "..", "skill.md");
+    const content = await readFile(source, "utf8");
+    const dest = join(skillDir(), "SKILL.md");
+    let existing = null;
+    try {
+      existing = await readFile(dest, "utf8");
+    } catch {
+      // missing — created below
+    }
+    if (existing === content) return false;
+    await mkdir(skillDir(), { recursive: true });
+    await writeFile(dest, content, "utf8");
+    return true;
+  } catch (error) {
+    // Never break plugin startup over skill syncing; the health tool still works.
+    console.warn(`kimi-webbridge: skill sync failed: ${error?.message ?? error}`);
+    return false;
+  }
+}
+
 /**
  * One HTTP JSON round-trip with a timeout and caller-abort support.
  * @param url - absolute URL.
@@ -287,33 +317,27 @@ function apply(ctx, config = {}) {
     requestTimeoutMs = 120000,
     autoStartDaemon = true,
     autoInstallDaemon = true,
-    daemonVersion = "latest"
+    daemonVersion = "latest",
+    generateSkill = true
   } = config;
 
+  if (generateSkill) void syncSkill();
+
   ctx.systemPrompt.section({
     name: "tool:kimi-webbridge",
     order: 105,
-    text: "kimi_webbridge drives the user's real browser through the local kimi-webbridge daemon. Use it for any web task that needs a real browser: navigation, reading pages (snapshot returns an accessibility tree with @e refs), clicking, filling forms, screenshots, JS evaluation, and PDF export. Keep one session name per task and pass it on every call so tabs group under one label."
+    text: "kimi-webbridge: the local kimi-webbridge daemon (127.0.0.1:10086) bridges to the user's real browser with their login sessions; this plugin provisions the daemon binary and keeps it running. The `kimi_webbridge` tool is only the status health check (daemon + extension). For any browser automation (navigation, reading pages, clicking, typing, filling forms, screenshots, JS evaluation, CDP, uploads, PDF export, tab management), load the kimi-webbridge skill and drive the daemon over HTTP exactly as that skill documents."
   });
 
   ctx.tools.register(defineTool({
     name: "kimi_webbridge",
-    description: "Drive the user's real browser (with their login sessions) via the local kimi-webbridge daemon at " + baseUrl + ". The browser extension must be connected (status shows extension_connected). One task = one session = one tab group: pick a session name at the start of a task and pass it on every call. Actions: status (daemon + extension health); navigate {url, newTab?, group_title?} (first call opens a tab); find_tab {url, active?} (re-select a session tab, or borrow the user's active tab); snapshot (accessibility tree with @e refs — use it to read content and locate elements); click {selector} (@e ref or CSS); fill {selector, value} (inputs, textareas, and contenteditable editors; clear-and-insert); evaluate {code} (async JS in the page realm; wrap re-declarations in an IIFE; return compact JSON); cdp {method, params} (raw chrome.debugger passthrough); screenshot {format?, quality?, selector?, path?} (returns a file path — open it with the read tool to see it); network {cmd, filter?, requestId?}; upload {selector, files}; save_as_pdf {paper_format?, landscape?, scale?, print_background?, path?}; list_tabs; close_tab; close_session (only when the user asks to close the tabs). Prefer @e refs from snapshot over hand-written CSS selectors. When the daemon is unreachable the plugin starts it automatically; if the daemon binary is missing it is downloaded from the official Kimi CDN (config autoInstallDaemon:false disables this). Limits: sites that strictly check event.isTrusted (some banking portals, captchas) ignore click/fill — tell the user the page needs manual interaction; cross-origin iframes are not covered by fill/click/snapshot/evaluate — navigate to the iframe URL directly; if an error says 'Please update the Kimi WebBridge extension', the extension is outdated — ask the user to update it and retry.",
+    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.",
     parameters: {
       action: {
         type: "string",
         required: true,
         enum: ACTIONS,
-        description: "Which WebBridge action to perform."
-      },
-      session: {
-        type: "string",
-        description: "Task session name — one session per task, passed on every call so all tabs land in one group (e.g. \"camping-research\"). Defaults to \"default\"."
-      },
-      args: {
-        type: "object",
-        additionalProperties: true,
-        description: "Action-specific arguments (see the tool description for each action's fields)."
+        description: "The single supported action: status — check daemon and browser-extension health."
       }
     },
     output: {
@@ -329,18 +353,7 @@ function apply(ctx, config = {}) {
       return false;
     },
     async execute(args, exec) {
-      const action = args.action;
-      const session = args.session ?? "default";
-      const actionArgs = args.args ?? {};
-      const target = action === "status" ? `${baseUrl}/status` : `${baseUrl}/command`;
-      const attempt = () => action === "status"
-        ? httpJson(target, { method: "GET", timeoutMs: requestTimeoutMs, signal: exec.signal })
-        : httpJson(target, {
-            method: "POST",
-            body: { action, args: actionArgs, session },
-            timeoutMs: requestTimeoutMs,
-            signal: exec.signal
-          });
+      const attempt = () => httpJson(`${baseUrl}/status`, { method: "GET", timeoutMs: requestTimeoutMs, signal: exec.signal });
       let result;
       try {
         result = await attempt();
@@ -355,13 +368,13 @@ function apply(ctx, config = {}) {
         const notes = [];
         if (!existsSync(daemonBinPath())) {
           if (!autoInstallDaemon) {
-            throw new Error(`kimi-webbridge: daemon binary not found at ${daemonBinPath()} and autoInstallDaemon is disabled. Install it with: irm https://cdn.kimi.com/webbridge/install.ps1 | iex`);
+            throw new Error(`kimi-webbridge: daemon binary not found at ${daemonBinPath()} and autoInstallDaemon is disabled. Install it manually: ${manualInstallHint()}`);
           }
           try {
             const { url } = await installDaemonBinary({ version: daemonVersion, timeoutMs: requestTimeoutMs });
             notes.push(`installed daemon from ${url}`);
           } catch (installError) {
-            throw new Error(`kimi-webbridge: daemon binary missing and auto-install failed: ${installError?.message ?? installError}. Install it manually: irm https://cdn.kimi.com/webbridge/install.ps1 | iex`);
+            throw new Error(`kimi-webbridge: daemon binary missing and auto-install failed: ${installError?.message ?? installError}. Install it manually: ${manualInstallHint()}`);
           }
         }
         if (autoStartDaemon) {
@@ -370,7 +383,7 @@ function apply(ctx, config = {}) {
             result = await attempt();
           } catch (retryError) {
             const hint = notes.length > 0 ? " " + notes.join("; ") + "." : "";
-            throw new Error(`kimi-webbridge: daemon at ${baseUrl} still unreachable after starting it.${hint} Check ~/.kimi-webbridge/logs/daemon.log or reinstall: irm https://cdn.kimi.com/webbridge/install.ps1 | iex`);
+            throw new Error(`kimi-webbridge: daemon at ${baseUrl} still unreachable after starting it.${hint} Check ~/.kimi-webbridge/logs/daemon.log, or reinstall: ${manualInstallHint()}`);
           }
         } else {
           throw new Error(`kimi-webbridge: daemon at ${baseUrl} is not running and autoStartDaemon is disabled. Start it with: ${daemonBinPath()} start`);
@@ -381,9 +394,9 @@ function apply(ctx, config = {}) {
     presentCall(callArgs) {
       return {
         card: "generic",
-        title: `kimi_webbridge ${callArgs.action}`,
-        rawInput: JSON.stringify({ session: callArgs.session ?? "default", args: callArgs.args ?? {} }),
-        content: [{ type: "text", text: `action: ${callArgs.action}` }]
+        title: "kimi_webbridge status",
+        rawInput: JSON.stringify({ action: callArgs.action ?? "status" }),
+        content: [{ type: "text", text: "checking daemon + extension health" }]
       };
     }
   }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kimi-webbridge-dsh",
-  "description": "Kimi WebBridge plugin for dsh: drive the user's real browser (their login sessions) through the local kimi-webbridge daemon at 127.0.0.1:10086. Registers a single kimi_webbridge tool covering navigate, click, fill, snapshot, screenshot, evaluate, cdp, network, upload, save_as_pdf, tab and session management.",
-  "version": "1.4.0",
+  "description": "Infrastructure plugin for dsh: provisions the kimi-webbridge daemon (auto-install with SHA-256 verification, auto-start) and generates 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.5",
   "license": "MIT",
   "type": "module",
   "keywords": [
@@ -31,14 +31,13 @@
   },
   "files": [
     "lib/index.js",
+    "skill.md",
     "README.md",
     "cordis.patch.yml"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.7 <0.2.0",
-    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.7 <0.2.0"
-  },
-  "dependencies": {
+    "@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/schemastery": "^3.18.1"
   }
 }

package/skill.md

@@ -0,0 +1,85 @@
+---
+name: kimi-webbridge
+description: |
+  Drive the user's real browser (with their login sessions) through the local kimi-webbridge daemon at 127.0.0.1:10086: navigate, click, type, read, screenshot, evaluate JS, raw CDP, network capture, file upload, PDF export, and tab/session management. Use this skill whenever the user wants to interact with websites, automate browser tasks, scrape web content, or do anything that needs a real browser — even simple-sounding requests. Also use when the user mentions "browser", "webpage", "open URL", "screenshot", or asks to read/interact with any website (浏览器 / 网页 / 打开网页 / 截图 / 页面).
+---
+
+# Kimi WebBridge
+
+Control the user's real browser (their login sessions) through the local daemon at `http://127.0.0.1:10086`.
+
+> This skill file is generated by the `kimi-webbridge-dsh` plugin (plugin v1.4.5 / daemon v1.11.6) and re-synced on plugin updates. 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.
+
+## The 17 actions
+
+Every action is one HTTP call: `POST http://127.0.0.1:10086/command` with body `{"action": "<name>", "args": {...}, "session": "<task-name>"}`.
+
+| action | args | returns | notes |
+|---|---|---|---|
+| `navigate` | `url` (required), `newTab?`, `group_title?` | `{success, url, tabId}` | first call opens a tab |
+| `find_tab` | `url` (required), `active?` | `{success, url, tabId, borrowed}` | re-select a session tab; `active:true` borrows the tab the user is viewing |
+| `snapshot` | — | `{url, title, tree}` | accessibility tree with `@e` refs — read pages with this |
+| `click` | `selector` (`@e` or CSS) | `{success, tag, text}` | synthetic `el.click()` |
+| `mouse_click` | `selector` (`@e` or CSS) | `{success, x, y, tag, text}` | real mouse click at element center (CDP input) — trusted |
+| `fill` | `selector`, `value` | `{success, tag, mode}` | inputs/textareas/contenteditable; clear-and-insert |
+| `key_type` | `text` | `{success, length}` | types into the focused element (CDP input) — trusted |
+| `send_keys` | `keys`, `repeat?` (1–100) | `{success, dispatched, os}` | named keys/shortcuts, e.g. "Enter", "Mod+A", "Enter Escape" |
+| `evaluate` | `code` (async ok) | `{type, value}` | JS in the page realm |
+| `cdp` | `method`, `params` | raw CDP response | chrome.debugger passthrough |
+| `screenshot` | `format?` png/jpeg, `quality?`, `selector?`, `path?` | `{format, path, sizeBytes, mimeType}` | writes a file, returns the path |
+| `network` | `cmd` start/stop/list/detail, `filter?`, `requestId?` | request/response data | |
+| `upload` | `selector`, `files` (array of local paths) | `{success, fileCount}` | |
+| `save_as_pdf` | `paper_format?` letter/a4/legal/a3/tabloid, `landscape?`, `scale?` 0.1–2.0, `print_background?`, `path?` | `{path, sizeBytes, mimeType, pageTitle}` | |
+| `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 |
+
+## Sending requests (shell-proof)
+
+On **Windows (PowerShell)**, inline JSON with non-ASCII text gets corrupted by the shell — **always** send the body via a temp file: write the JSON to a uniquely-named temp file with your file-write tool, then:
+
+```powershell
+curl.exe -s -X POST http://127.0.0.1:10086/command -H "Content-Type: application/json" --data-binary "@$env:TEMP\wb-<random>.json"
+```
+
+then delete the temp file. Always `curl.exe`, never bare `curl` (PowerShell aliases it to Invoke-WebRequest).
+
+On **macOS / Linux**, inline `-d '{...}'` is fine; if a call fails with a shell quoting error or HTTP 400, switch to the temp-file form above.
+
+## Sessions
+
+One task = one session = one tab group. Pick a task-named session (`camping-research`) and pass it on **every** call, never switching mid-task. `group_title` (in the user's language) on the first `navigate` labels the group. Example body:
+
+```json
+{"action":"navigate","args":{"url":"https://example.com","newTab":true,"group_title":"Research"},"session":"research"}
+```
+
+Call `close_session` only when the user explicitly asks to close the tabs.
+
+## Reading and interacting
+
+- Prefer `snapshot` + `@e` refs over hand-written CSS selectors.
+- `find_tab` searches only this session's tabs; pass the exact URL (a bare domain may miss www/subdomain variants). On "no tab matching", `navigate` with `newTab:true`. With `active:true` it borrows the user's currently-viewed tab and operates it in place.
+- `evaluate`: wrap re-declarations in an IIFE; return compact `JSON.stringify` (never pretty-print).
+- `fill` is clear-and-insert; to append, read the current value via `evaluate` first.
+- 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.
+
+## Screenshots and PDF
+
+`screenshot` and `save_as_pdf` write files and return a path — open it with your read tool. A caller-supplied `path` is honored verbatim (parent dirs created, existing files overwritten). PDF decoded cap is 100 MB; reduce `scale` to shrink.
+
+## 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).
+- If the daemon stays unreachable after the status tool's retry, point the user to the help page instead of deep-troubleshooting.
+
+---
+
+Protocol and workflow adapted from the Kimi WebBridge community skill (Apache-2.0). Daemon binary and browser extension by Kimi. This file is generated by kimi-webbridge-dsh.