kimi-webbridge-dsh 1.4.5 → 1.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +13 -12
  2. package/lib/index.js +41 -39
  3. package/package.json +2 -2
  4. package/skill.md +14 -9
package/README.md CHANGED
@@ -1,17 +1,17 @@
1
1
  # kimi-webbridge-dsh
2
2
 
3
- Kimi WebBridge 的 dsh 插件（**基础设施 + 技能生成**）。插件本身不代理浏览器操作，而是负责：
3
+ Kimi WebBridge 的 dsh 插件（**基础设施 + 技能注册**）。插件本身不代理浏览器操作，而是负责：
4
4
 
5
5
  1. **保障桥完好**：守护进程二进制缺失时自动从官方 CDN 下载（跨平台、SHA-256 校验），守护进程未运行时自动拉起；
6
- 2. **生成 skill**：启动时把随包内置的 `skill.md` 同步到 `~/.dsh/skills/kimi-webbridge/SKILL.md`，模型通过 `skill` 工具加载它，按文档用 HTTP 行使全部浏览器能力（17 个动作）；
6
+ 2. **注册 skill**：启动时把随包内置的 `skill.md` 注册为运行时 skill（`ctx.skills.register`，`source: bundled`），模型通过 `skill` 工具加载它，按文档用 HTTP 行使全部浏览器能力（25 个动作）；
7
7
  3. **注册一个瘦工具 `kimi_webbridge`**：只有 `status` 一个动作（守护进程 + 扩展健康检查），作为其他 skill（如 x-cli 系列）的桥健康锚点。
8
8
 
9
9
  ## 架构
10
10
 
11
11
  | 层 | 角色 |
12
12
  |---|---|
13
- | 插件（本包） | 守护进程二进制供应 + 自动启动；apply() 时同步 skill 文件 |
14
- | 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 |
13
+ | 插件（本包） | 守护进程二进制供应 + 自动启动；apply() 时注册运行时 skill |
14
+ | 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 |
15
15
  | 瘦工具 `kimi_webbridge` | 仅 `status` 健康检查（自带守护进程自愈） |
16
16
 
17
17
  ## 安装（一次性，零手工配置）
@@ -20,7 +20,7 @@ Kimi WebBridge 的 dsh 插件（**基础设施 + 技能生成**）。插件本
20
20
  dsh plugin --profile web add kimi-webbridge-dsh
21
21
  ```
22
22
 
23
- 本包声明了 `dsh.bundle.patch`：`dsh plugin add` 会自动把它登记进 profile 的 bundle 层（`dsh.profile.bundles`），**无需手动编辑任何 cordis.patch.yml**。重启一次 `dsh web`：启动时插件同步 skill 文件，新会话的 skill 目录中即出现 `kimi-webbridge`。
23
+ 本包声明了 `dsh.bundle.patch`：`dsh plugin add` 会自动把它登记进 profile 的 bundle 层（`dsh.profile.bundles`），**无需手动编辑任何 cordis.patch.yml**。重启一次 `dsh web`：启动时插件把 skill 注册进运行时 registry，新会话的 skill 目录中即出现 `kimi-webbridge`。
24
24
 
25
25
  ## 用法（模型视角）
26
26
 
@@ -58,16 +58,17 @@ dsh plugin --profile web add kimi-webbridge-dsh
58
58
 
59
59
  下载流程：先落盘为临时文件（`kimi-webbridge(.exe).tmp-{pid}-{时间戳}`）→ SHA-256 与官方清单核对 → 匹配才重命名为最终路径；不匹配则删除临时文件并中止，任何未验证的二进制都不会留在磁盘。该路径与官方安装器 / `kimi-webbridge upgrade` 命令完全一致，插件、官方工具共用同一份守护进程。
60
60
 
61
- ## 功能（skill 承载，17 个动作）
61
+ ## 功能（skill 承载，25 个动作）
62
62
 
63
63
  | 能力 | 动作 |
64
64
  |---|---|
65
65
  | 导航 / 标签 | `navigate`、`find_tab`、`list_tabs`、`close_tab`、`close_session` |
66
- | 读页面 | `snapshot`（accessibility tree + `@e` 引用） |
67
- | 点击 / 输入 | `click`、`mouse_click`（真实鼠标，可信输入）、`fill`、`key_type`（键入，可信）、`send_keys`（组合键） |
66
+ | 读页面 | `snapshot`（accessibility tree + `@e` 引用）、`read_page`（全文文本）、`find`（页面内搜索） |
67
+ | 点击 / 输入 | `click`、`mouse_click`（真实鼠标，可信输入）、`hover`、`drag`、`fill`、`key_type`（键入，可信）、`send_keys`（组合键）、`select_option`、`dialog` |
68
68
  | JS / CDP | `evaluate`（页面上下文）、`cdp`（chrome.debugger 直通） |
69
69
  | 截图 / PDF | `screenshot`、`save_as_pdf`（写文件、返回路径） |
70
70
  | 网络 / 上传 | `network`（请求捕获）、`upload`（文件上传） |
71
+ | 滚动 / 等待 | `scroll`（滚动/定位）、`wait`（等待文本/选择器条件） |
71
72
  | 会话分组 | 一个任务 = 一个 session = 一个标签页组，可一键清理 |
72
73
 
73
74
  ## 配置（可选）
@@ -78,7 +79,7 @@ dsh plugin --profile web add kimi-webbridge-dsh
78
79
  - id: kimi-webbridge
79
80
  config:
80
81
  autoInstallDaemon: false
81
- daemonVersion: 0.3.0
82
+ daemonVersion: v1.11.6
82
83
  ```
83
84
 
84
85
  | 配置项 | 默认值 | 说明 |
@@ -87,8 +88,8 @@ dsh plugin --profile web add kimi-webbridge-dsh
87
88
  | `requestTimeoutMs` | `120000` | 单次请求超时（毫秒） |
88
89
  | `autoStartDaemon` | `true` | 守护进程未运行时自动启动 |
89
90
  | `autoInstallDaemon` | `true` | 二进制缺失时自动从官方 CDN 下载安装（关闭后需手动[从官方安装](https://www.kimi.ai/products/kimi-webbridge)） |
90
- | `daemonVersion` | `latest` | 自动安装时的版本（可固定如 `0.3.0`） |
91
- | `generateSkill` | `true` | 启动时同步 `kimi-webbridge` skill 文件（关闭后不生成/更新） |
91
+ | `daemonVersion` | `latest` | 自动安装时的版本（可固定如 `v1.11.6`，需带 `v` 前缀与 CDN 路径一致） |
92
+ | `registerSkill` | `true` | 启动时把 `kimi-webbridge` skill 注册进运行时 registry（关闭后不注册） |
92
93
 
93
94
  ## 移除
94
95
 
@@ -96,4 +97,4 @@ dsh plugin --profile web add kimi-webbridge-dsh
96
97
  dsh plugin --profile web remove kimi-webbridge-dsh
97
98
  ```
98
99
 
99
- 自动从 bundle 层移除（无需手动删补丁行），重启后生效。skill 文件（`~/.dsh/skills/kimi-webbridge/`）如需一并删除可手动清理。
100
+ 自动从 bundle 层移除（无需手动删补丁行），重启后生效。skill 为运行时注册，移除插件即随之消失，无残留文件。
package/lib/index.js CHANGED
@@ -3,8 +3,8 @@ import { TOOL_ABORTED, defineTool } from "@deepseek-ai/dsh-tools";
3
3
  import { HarnessError } from "@deepseek-ai/dsh-llm";
4
4
  import { spawn } from "node:child_process";
5
5
  import { createHash } from "node:crypto";
6
- import { createWriteStream, existsSync } from "node:fs";
7
- import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
6
+ import { createWriteStream, existsSync, readFileSync } from "node:fs";
7
+ import { chmod, mkdir, readFile, rename, rm } from "node:fs/promises";
8
8
  import { request as httpRequest } from "node:http";
9
9
  import { request as httpsRequest } from "node:https";
10
10
  import { homedir } from "node:os";
@@ -17,9 +17,8 @@ import { fileURLToPath } from "node:url";
17
17
  * Infrastructure-only bridge plugin:
18
18
  * - provisions the daemon binary (official Kimi CDN, SHA-256 verified) and
19
19
  * auto-starts it, keeping the bridge healthy;
20
- * - syncs the packaged skill.md into ~/.dsh/skills/kimi-webbridge/SKILL.md,
21
- * the model-facing skill that documents the full 17-action HTTP protocol
22
- * for driving the user's real browser;
20
+ * - registers the packaged skill.md (the full 25-action HTTP protocol for
21
+ * driving the user's real browser) as a runtime skill via ctx.skills;
23
22
  * - registers one thin tool `kimi_webbridge` whose only action is `status`
24
23
  * (daemon + extension health check) as an anchor for other skills.
25
24
  *
@@ -32,7 +31,7 @@ import { fileURLToPath } from "node:url";
32
31
  const name = "kimi-webbridge";
33
32
 
34
33
  /** Services required by this plugin. */
35
- const inject = ["tools", "systemPrompt"];
34
+ const inject = ["tools", "systemPrompt", "skills"];
36
35
 
37
36
  /** The single action of the thin bridge tool. The full browser protocol lives in the generated skill. */
38
37
  const ACTIONS = ["status"];
@@ -44,7 +43,7 @@ const Config = z.object({
44
43
  autoStartDaemon: z.boolean().default(true),
45
44
  autoInstallDaemon: z.boolean().default(true),
46
45
  daemonVersion: z.string().default("latest"),
47
- generateSkill: z.boolean().default(true)
46
+ registerSkill: z.boolean().default(true)
48
47
  });
49
48
 
50
49
  /** Official release CDN base. */
@@ -88,37 +87,18 @@ function manualInstallHint() {
88
87
  return `run \"curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash\" (or install from ${page})`;
89
88
  }
90
89
 
91
- /** Directory the DSH skill loader scans for the generated skill. */
92
- function skillDir() {
93
- return join(homedir(), ".dsh", "skills", "kimi-webbridge");
94
- }
90
+ /** Skill identity registered into the host skill registry. */
91
+ const SKILL_NAME = "kimi-webbridge";
92
+
93
+ /** Model-facing routing description shown in the skill catalog. */
94
+ const SKILL_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 (浏览器 / 网页 / 打开网页 / 截图 / 页面).`;
95
95
 
96
96
  /**
97
- * Sync the packaged skill.md into the DSH skills directory so the model can
98
- * load it with the skill tool. Rewrites only when missing or changed, so
99
- * restarts stay cheap and updates propagate automatically.
100
- * @returns true when the file was (re)written.
97
+ * Read the packaged skill body (markdown instructions, no frontmatter).
98
+ * @returns the skill body text.
101
99
  */
102
- async function syncSkill() {
103
- try {
104
- const source = join(dirname(fileURLToPath(import.meta.url)), "..", "skill.md");
105
- const content = await readFile(source, "utf8");
106
- const dest = join(skillDir(), "SKILL.md");
107
- let existing = null;
108
- try {
109
- existing = await readFile(dest, "utf8");
110
- } catch {
111
- // missing — created below
112
- }
113
- if (existing === content) return false;
114
- await mkdir(skillDir(), { recursive: true });
115
- await writeFile(dest, content, "utf8");
116
- return true;
117
- } catch (error) {
118
- // Never break plugin startup over skill syncing; the health tool still works.
119
- console.warn(`kimi-webbridge: skill sync failed: ${error?.message ?? error}`);
120
- return false;
121
- }
100
+ function readSkillBody() {
101
+ return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "skill.md"), "utf8");
122
102
  }
123
103
 
124
104
  /**
@@ -318,10 +298,22 @@ function apply(ctx, config = {}) {
318
298
  autoStartDaemon = true,
319
299
  autoInstallDaemon = true,
320
300
  daemonVersion = "latest",
321
- generateSkill = true
301
+ registerSkill = true
322
302
  } = config;
323
303
 
324
- if (generateSkill) void syncSkill();
304
+ if (registerSkill) {
305
+ try {
306
+ ctx.skills.register({
307
+ name: SKILL_NAME,
308
+ description: SKILL_DESCRIPTION,
309
+ source: "bundled",
310
+ content: readSkillBody()
311
+ });
312
+ } catch (error) {
313
+ // Never break plugin startup over skill registration; the status tool still works.
314
+ console.warn(`kimi-webbridge: skill registration failed: ${error?.message ?? error}`);
315
+ }
316
+ }
325
317
 
326
318
  ctx.systemPrompt.section({
327
319
  name: "tool:kimi-webbridge",
@@ -331,7 +323,7 @@ function apply(ctx, config = {}) {
331
323
 
332
324
  ctx.tools.register(defineTool({
333
325
  name: "kimi_webbridge",
334
- 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.",
326
+ 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.",
335
327
  parameters: {
336
328
  action: {
337
329
  type: "string",
@@ -346,7 +338,17 @@ function apply(ctx, config = {}) {
346
338
  additionalProperties: true
347
339
  },
348
340
  render(args, value) {
349
- return [{ type: "text", text: JSON.stringify(value) }];
341
+ const blocks = [{ type: "text", text: JSON.stringify(value) }];
342
+ const norm = (s) => (typeof s === "string" ? s.replace(/^v/i, "") : "");
343
+ const daemonVer = norm(value?.version);
344
+ const extVer = norm(value?.extension_version);
345
+ if (daemonVer && extVer && daemonVer !== extVer) {
346
+ blocks.push({
347
+ type: "text",
348
+ text: `⚠️ version drift: daemon ${value.version} vs extension ${value.extension_version} — the browser extension likely auto-updated. Re-audit the 25-action skill list and update the daemon.`
349
+ });
350
+ }
351
+ return blocks;
350
352
  }
351
353
  },
352
354
  isConcurrencySafe() {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "kimi-webbridge-dsh",
3
- "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).",
4
- "version": "1.4.5",
3
+ "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).",
4
+ "version": "1.4.7",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "keywords": [
package/skill.md CHANGED
@@ -1,20 +1,14 @@
1
- ---
2
- name: kimi-webbridge
3
- description: |
4
- 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 (浏览器 / 网页 / 打开网页 / 截图 / 页面).
5
- ---
6
-
7
1
  # Kimi WebBridge
8
2
 
9
3
  Control the user's real browser (their login sessions) through the local daemon at `http://127.0.0.1:10086`.
10
4
 
11
- > 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.
5
+ > This skill is registered by the `kimi-webbridge-dsh` plugin (plugin v1.4.7 / daemon v2.0.1). Do not hand-edit it.
12
6
 
13
7
  ## Health check first
14
8
 
15
9
  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.
16
10
 
17
- ## The 17 actions
11
+ ## The 25 actions
18
12
 
19
13
  Every action is one HTTP call: `POST http://127.0.0.1:10086/command` with body `{"action": "<name>", "args": {...}, "session": "<task-name>"}`.
20
14
 
@@ -37,6 +31,14 @@ Every action is one HTTP call: `POST http://127.0.0.1:10086/command` with body `
37
31
  | `list_tabs` | — | `{success, tabs:[{tabId,url,title,active,groupTitle}]}` | |
38
32
  | `close_tab` | — | `{success, closed}` | |
39
33
  | `close_session` | — | `{success, closed}` | close all session tabs — only when the user asks |
34
+ | `read_page` | `max_chars?`, `start?` | `{text, complete, screens, chars}` | readable page text, paged — pass `start` to continue when `complete:false` |
35
+ | `find` | `query` | `{url, title, matches}` | search the page (accessibility tree) for a text query |
36
+ | `scroll` | `direction?` up/down, `to?` top/bottom, `selector?`, `text?` | `{scrolled, direction, atTop, atBottom, scrollY}` | scroll the page or an element into view |
37
+ | `hover` | `selector` (`@e` or CSS) | `{success, x, y, tag, text}` | hover over an element |
38
+ | `drag` | `from`, `to` (`@e`/CSS) | `{success, dispatched, verified, dropAccepted}` | HTML5 drag-and-drop from→to |
39
+ | `select_option` | `selector`, `values` (or `value`) | `{success, ...}` | pick options in a native `<select>`; custom dropdowns → click |
40
+ | `dialog` | `action` status/accept/dismiss, `text?` | `{open, type, message}` / `{success, action}` | handle JS dialogs (alert/confirm/prompt) |
41
+ | `wait` | `text?`, `text_gone?`, `selector?`, `timeout_ms?` | `{ok, ...}` / `{ok:false, timedOut, waitedMs}` | wait for a condition (text appears/disappears, selector visible) |
40
42
 
41
43
  ## Sending requests (shell-proof)
42
44
 
@@ -69,6 +71,8 @@ Call `close_session` only when the user explicitly asks to close the tabs.
69
71
  - 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.
70
72
  - `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").
71
73
  - Cross-origin iframes are not covered — navigate to the iframe URL directly.
74
+ - `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.
75
+ - `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.
72
76
 
73
77
  ## Screenshots and PDF
74
78
 
@@ -79,7 +83,8 @@ Call `close_session` only when the user explicitly asks to close the tabs.
79
83
  - Call the `kimi_webbridge` tool (`status`) — the plugin auto-provisions and starts the daemon. Never run `stop` / `restart` / `uninstall` yourself.
80
84
  - 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).
81
85
  - If the daemon stays unreachable after the status tool's retry, point the user to the help page instead of deep-troubleshooting.
86
+ - If the status tool warns that `version` (daemon) and `extension_version` (extension) differ, the extension has drifted (likely auto-updated) — re-audit the 25-action list above and ask the user to update the daemon.
82
87
 
83
88
  ---
84
89
 
85
- 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.
90
+ 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.