dsh-sidebar-browser-agent 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.10
+
+- README is now just what the plugin does and its limits, with a hero diagram
+  of the tool → native webview flow.
+- The plugin page shows the same diagram as an official-style hero card above
+  the settings form (localized heading/subtitle).
+
+## 0.2.9
+
+- Polished the official-style plugin page rhythm: field/row spacing, tertiary
+  12px hints, the same input surface and radius the built-in settings pages
+  use, and the shared form footer as the only save action.
+
 ## 0.2.8
 
 - The plugin page now follows the official plugin-page style: the configuration

package/README.md

@@ -1,227 +1,25 @@
 # 侧栏浏览器 Agent 控制（dsh-sidebar-browser-agent）
 
-给 DSH 右侧栏的**原生浏览器**加上完整的 Agent 可操作能力：管理标签页，并读取页面内容、
-点击、输入、按键、滚动、执行 JS、截图返回给模型查看；带配置开关、启动自检与回归测试。
+给 DeepSeek Harness 右侧栏的**原生浏览器**加上 Agent 可操作能力。
 
-实现是**全原生**的：不依赖 Playwright/Puppeteer、不注入代理、不重写页面。页面操作直接使用
-侧栏浏览器自带的 Electron `<webview>` 客户端的 Chromium API：
+![工作原理](https://raw.githubusercontent.com/Hesitate-P/dsh-sidebar-browser-agent/main/assets/how-it-works.svg)
 
-- `executeJavaScript()` —— 在真实页面里读取 DOM、执行脚本；
-- `sendInputEvent()` —— 原生鼠标/键盘事件（真实点击、按键）；
-- `capturePage()` —— Chromium 原生截图，经 attachment 服务变成图像内容块返回给模型；
-- `loadURL()` / `reload()` —— 原生导航与刷新，侧栏地址栏同步更新。
+## 做什么
 
-## 结构
+- 管理右侧栏浏览器标签页：`sidebar_browser`（status / list / open / navigate / reload / focus / close）。
+- 操作真实页面：`sidebar_page`（read 文本 / 交互元素 / HTML、click、type、press、scroll、wait、eval、screenshot）。
+- 全原生：直接调用 Electron `<webview>` 的 `executeJavaScript`、`sendInputEvent`、`capturePage`、`loadURL` —— 不使用 Playwright/Puppeteer、不注入代理、不重写页面。
+- 截图以图片附件返回给模型；配置页可开关工具、允许 eval / 原生输入、设置域名白名单。
 
-| 文件 | 作用 |
-| --- | --- |
-| `cordis.patch.yml` | bundle patch，插入 Host 插件行（id `sidebar-browser-agent`） |
-| `lib/index.js` | Host 半源码：配置与开关、`sidebar_browser` / `sidebar_page` 工具、HTTP 长轮询桥、截图转 attachment、启动自检 |
-| `lib/entry-<version>.js` | 实际提供给 Loader 的 Host 入口（由 `scripts/set-version.mjs` 生成）：每次发版换新文件路径，重装后能加载新 Host 代码而非 Node 缓存的旧模块 |
-| `lib/client.js` | 浏览器半：长轮询取命令，用公开 `ctx.sidebarRight` 管理标签、用原生 webview 操作页面；所有 guest 调用有超时看门狗，页面卡死不会阻塞桥；`status` 输出自检信息 |
-| `locale/*.json` | 插件列表显示用的标题与描述（中/英） |
-| `icon.svg` | 插件图标 |
-| `vendor/` | 内置的 MIT 依赖（schemastery + cosmokit），使 link 安装的插件也能声明原生 Config schema，见 `vendor/NOTICE.md` |
-| `test/` | 零依赖离线回归测试（Host 桥/工具/配置 + Client guest 脚本），`node test/run.mjs` |
-
-### 为什么需要桥
-
-右侧栏布局与标签状态属于浏览器页面，只有页面持有 `ctx.sidebarRight`。Host 工具把命令排入队列，
-页面半长轮询取走命令、执行后回传结果（截图走同一条通道）。所有桥路由都经过
-`ctx.connection.requestRejection` 的准入检查。
-
-### webview 定位方式
-
-侧栏为每个标签渲染 title 和 body 两个带 `data-sidebar-right-tab="<tabId>"` 的节点，
-外层是 `[data-sidebar-right-session]`。body 节点内是原生 `<webview data-sidebar-browser-frame>`，
-插件按 (sessionId, tabId) 精确定位它，不依赖标签顺序或坐标猜测；找不到时返回明确诊断而不是静默失败。
-
-## 工具
-
-### `sidebar_browser` —— 标签页管理
-
-| action | 说明 | 参数 |
-| --- | --- | --- |
-| `status` | 桥状态、载体类型、原生能力、插件版本、配置、attachment 自检 | — |
-| `list` | 列出标签页（含原生读取的 URL / 标题） | — |
-| `open` | 新建标签页打开网页 | `url` |
-| `navigate` | 在当前标签页内原生导航 | `tabId`、`url` |
-| `reload` | 原生刷新 | `tabId` |
-| `focus` | 切换到标签页 | `tabId` |
-| `close` | 关闭标签页 | `tabId` |
-
-### `sidebar_page` —— 页面读取与操作
-
-| action | 说明 | 参数 |
-| --- | --- | --- |
-| `read` | 读取页面：`text` 可见文本 / `interactive` 可交互元素（含 CSS selector 与坐标）/ `html` 源码 | `mode`、`selector`、`maxChars`、`maxElements` |
-| `click` | 原生点击：按 CSS selector、按可见文本、或按视口坐标 | `selector` / `contains` / `x`+`y` |
-| `type` | 聚焦输入框写入文本（可替换原值、可回车提交），触发真实 input/change 事件 | `selector`、`text`、`clear`、`submit` |
-| `press` | 原生按键：Enter/Tab/Escape/Backspace/Delete/方向键/PageUp/PageDown/Home/End/Space | `key` |
-| `scroll` | 滚动页面或把元素滚入视口 | `dy`、`dx`、`selector` |
-| `wait` | 轮询等待 selector 或页面文本出现 | `selector` / `contains`、`timeoutMs` |
-| `eval` | 在页面执行 JavaScript，返回 JSON 结果（可做任意 DOM 操作） | `code` |
-| `screenshot` | 截取当前视口，图像作为内容块返回给模型 | — |
-
-`read` 的 `interactive` 输出示例：
-
-```
-[2] <button type=button> "Say hello" selector=#greet @(118,261)
-```
-
-随后即可 `click --selector "#greet"`。页面结构未知时先 `read interactive`。
-
-## 配置
-
-插件把四个字段声明为**原生 Schemastery `Config`（全部 `.volatile()`）**，并随包提供配置页组件，因此在
-**Plugin Manager → 对应 bundle → 该行 → Configure** 可直接编辑：
-
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| `enabled` | `true` | 是否对 Agent 暴露 `sidebar_browser` / `sidebar_page`（关闭后工具从模型视图隐藏，桥仍在，便于诊断） |
-| `allowedHosts` | `[]` | 允许 `open`/`navigate` 的域名白名单；空 = 全部 HTTP(S)。每行一个，`example.com` 同时允许子域，`localhost:8765` 精确匹配主机与端口 |
-| `allowEval` | `true` | 是否允许 `sidebar_page` 的 `eval`（页面内任意 JS） |
-| `allowNativeInput` | `true` | 是否允许 `click` / `type` / `press` 原生输入 |
-
-因为字段是 volatile 的，保存后**立即生效、无需重启**：工具显隐由每步的 `when` 条件读取实时值，
-各开关也在每次调用时实时读取。页面上的配置来自 profile patch 的持久化写入（与手写 patch 等价）：
-
-```yaml
-- id: sidebar-browser-agent
-  config:
-    enabled: true
-    allowedHosts: []
-    allowEval: true
-    allowNativeInput: true
-```
-
-若部署中没有 settings 服务，配置页会显示「不可编辑」，插件本身仍按 patch 中的值运行。
-
-## 诊断与自检
-
-- 插件启动时 `apply` 会做一次自检：`webServer` / `connection` / `tools` / `attachments` 是否就绪，
-  通过日志输出 `sidebar-browser-agent 0.2.0: ready (...)`；attachment 缺失会 warn（截图不可用）。
-- `sidebar_browser status` 的 note 末尾带：
-  - `checks={...}`：页面半自检，含插件版本、载体、DOM 标记、guest webview、原生 API 清单、
-    当前 guest URL、Harness release（版本 + commit）；
-  - `host-plugin=...`：Host 版本、生效配置、attachment 可用性。
-- 原生 API 或 DOM 标记缺失时，`checks.apiMissing` / `surface=false` / `webview=false` 会直接暴露问题。
-
-## 安装
-
-### 从 GitHub 安装（推荐给使用者）
-
-Plugin Manager（或 `plugin_manager` 工具）接受 pnpm 能解析的安装规格。仓库带标签后：
-
-```text
-github:Hesitate-P/dsh-sidebar-browser-agent#v0.2.2
-```
-
-- Web 界面：Plugins → 添加插件 → 粘贴上面的规格（DSH 会先用 `git ls-remote` 检查 GitHub 连通性，再交给 pnpm 安装）；
-- Agent 工具：`plugin_manager install_bundle(target: "github:Hesitate-P/dsh-sidebar-browser-agent#v0.2.2")`。
-
-也可以直接填 GitHub 仓库 URL。安装完成后 profile 依赖会记录为 `github:...#v0.2.0`，bundle 自动选中并启用。
-`engines.dsh` 声明兼容 `>=0.2.2-rc.1 <0.3.0`，Git 规格在安装后由 DSH 校验版本要求。
-
-### 从 npm 安装（推荐，可一键更新）
-
-包名 `dsh-sidebar-browser-agent`（已发布，最新 `0.2.5`）。在 Plugin Manager 中以
-`dsh-sidebar-browser-agent@<version>` 安装（或直接点 Update 升级），此后详情页会持续提供 **Update**
-（DSH 的版本列表与 Update 只对 registry 安装的第三方包生效）：
-
-```text
-plugin_manager install_bundle(target: "dsh-sidebar-browser-agent@0.2.5")
-```
-
-### 开发安装（link）
-
-通过 Plugin Manager 安装本目录的**绝对路径**：
-
-```text
-plugin_manager install_bundle(target: /path/to/sidebar-browser-agent)
-```
-
-profile 以 `link:` 指向该目录，**不要移动或删除它**。Host 半代码修改后重启 Harness
-（或对该行 disable→enable）才会重新加载；`lib/client.js` 修改会被客户端 HMR 自动热换。link 安装没有 Update 按钮。
-
-## 更新
-
-DSH Plugin Manager 的 **Update** 按钮只接受"以自身包名保存的 registry spec"的第三方包；
-GitHub 安装（`github:...` 规格）不会出现 Update。对应更新方式：
-
-| 安装来源 | 更新方式 |
-| --- | --- |
-| GitHub 安装 | Plugin Manager 中先 **Remove**，再安装新标签：`github:Hesitate-P/dsh-sidebar-browser-agent#v0.2.2`。工具等价操作：`plugin_manager remove_bundle` → `install_bundle`。移除期间插件短暂不可用，重新安装后恢复。 |
-| npm 安装 | 详情页 **Update**：列出更高版本、校验 `engines.dsh`/peer 后一键替换；失败会回滚并重装旧版本。 |
-
-更新后先跑一次 `sidebar_browser status` 确认版本：自 0.2.5 起 Host 入口使用版本化文件路径，
-Plugin Manager 重装新版本后解析到新的模块 URL，Host 半会加载新代码而**无需重启** Harness；
-若仍看到「page half / Host half 版本不一致」告警，重启一次 Harness 即可。
-
-如果希望 GitHub 安装也具备一键更新：把 profile 的安装来源切换到 registry spec
-（`dsh-sidebar-browser-agent@<version>`）一次即可；本仓库自 `0.2.5` 起已发布到 npm。
-
-## 发布流程
-
-发布认证使用 **npm Trusted Publishing（GitHub OIDC）**，不使用长期 token：npm 包设置里把发布者绑定到
-本仓库的 `publish.yml`，workflow 以 `id-token: write` 换取短期发布权限（`npm publish --provenance`）。
-这样没有需要轮换的 `NPM_TOKEN`，也不受 bypass-2FA token 弃用政策影响。
-
-首次发布前在 npm 包设置（Settings → Trusted Publisher）绑定：owner `Hesitate-P`、repository
-`dsh-sidebar-browser-agent`、workflow `publish.yml`。
-
-```bash
-node scripts/set-version.mjs 0.2.1   # 同步 package.json、index.js/client.js 的 PLUGIN_VERSION，并生成新的 lib/entry-<version>.js
-npm test                             # 回归测试同时校验版本一致性、版本化 Host 入口
-git commit -am "release v0.2.1"
-git tag v0.2.1
-git push --follow-tags               # CI 跑测试；publish workflow 通过 OIDC 自动发布 npm
-```
-
-### 本地打包
-
-```bash
-npm run pack:check       # 校验 npm pack 文件清单
-npm pack                 # 生成 dsh-sidebar-browser-agent-0.2.0.tgz
-```
-
-`files` 已显式包含运行文件、`vendor/`、`test/`、`README.md`、`CHANGELOG.md`、`LICENSE`。
-
-变更记录见 [CHANGELOG.md](CHANGELOG.md)。
-
-## 测试
-
-```bash
-node test/run.mjs        # 或 npm test
-```
-
-- `test/host-harness.mjs`：真实 Config 校验、开关门禁、工具注册、输出 schema、HTTP 桥往返、
-  截图 attachment + 图像块、版本一致性；
-- `test/client-harness.mjs`：在 vm + 假 DOM 中执行真实 guest 脚本，覆盖 read/click/type/press/
-  scroll/wait/eval/screenshot、原生导航刷新、后台会话与自检输出。
-
-零第三方依赖、无需运行中的 Harness。
-
-## 跨会话（后台）行为
-
-页面切到别的会话时（`status` 的 `mounted` 是另一个会话 id）：
-
-- **可用**：`read` / `click` / `type` / `press` / `scroll` / `wait` / `eval`、`navigate` / `reload`、
-  `list` / `status`。原生 webview 在会话切走后仍保持挂载，结果会附带「操作未显示在屏幕上」的说明。
-- **不可用**：`open` / `focus` / `close`（改变可见侧栏布局，必须让调用会话在屏幕上）；
-  `screenshot`（Chromium 无法截取隐藏的 guest，会返回明确提示，切回即可）。
+安装：`dsh plugin --profile <profile> add dsh-sidebar-browser-agent`（要求 DSH `>=0.2.2-rc.1 <0.3.0`）。
 
 ## 限制
 
-- 页面操作需要 **DSH Desktop 原生载体（Electron webview）**；Web 构建下侧栏浏览器是沙箱跨域 iframe，
-  页面操作会明确报错，标签页管理仍可用，读取纯文本可改用 `web_fetch`。
-- 调用时 Harness 页面必须打开；`open`/`focus`/`close`/`screenshot` 需要调用会话正显示在页面上。
-- 截图是当前视口（非整页长图），且只在会话可见时可靠；超宽图会自动降采样，最大约 12MB base64。
-- 页面卡死/无响应时，guest 调用会在 25s 内返回超时错误（导航 20s），桥保持可用；极端情况下仍建议重载该标签页。
-- `eval` 可在页面执行任意 JS（可用配置关闭），等同把该页面当作可编程环境；请只在可信页面使用。
-- 侧栏浏览器对页面有沙箱限制：无下载、无弹窗（会转为新侧栏标签）、无权限授予，页面也访问不到 DSH 应用。
-
-## 许可
+- 只操作 **DSH 右侧栏原生浏览器**，不控制系统 Chrome/Safari，也不是无头浏览器。
+- 页面内容操作需要 **DSH Desktop**（Electron 原生 webview）；Web 版只能管理标签页。
+- 截图仅当调用会话可见时可用；会话隐藏时截图会返回错误。
+- guest 调用有超时：页面脚本 25s、导航 20s；页面卡死会返回错误而不是挂起，必要时重载标签页。
+- 受 profile 配置约束：Host 可关闭工具入口、禁止 eval / 原生输入、限制允许访问的域名。
+- 只能访问宿主侧栏浏览器允许的 HTTP(S) 页面，地址栏规则之外的目标不可达。
 
-本插件 MIT（见 `LICENSE`）。`vendor/` 内置的 `@deepseek-ai/schemastery` 与
-`@deepseek-ai/cosmokit` 同为 MIT，来源与改动见 `vendor/NOTICE.md`。
+变更记录见 [CHANGELOG.md](CHANGELOG.md)。

package/lib/client.js

@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
     const BASE_BACKOFF_MS = 400
     const MAX_EVAL_CHARS = 100_000
     /** Plugin version reported by diagnostics; keep in sync with package.json. */
-    const PLUGIN_VERSION = '0.2.8'
+    const PLUGIN_VERSION = '0.2.10'
     const MAX_SCREENSHOT_WIDTH = 1_400
     const MAX_SCREENSHOT_BASE64 = 12_000_000
     /**
@@ -1136,6 +1136,9 @@ window.__ModuleLoader__.load({
     const CONFIG_EN = {
       'config.summary': 'Configure the sidebar browser tools: enabled switches, allowed hosts and permissions.',
       'config.heading': 'Sidebar browser agent',
+      'config.heroTitle': 'Hands on the real page inside the sidebar',
+      'config.heroSubtitle': 'Read, click, type, scroll, run JavaScript and screenshot through the native Electron webview — no proxy, no Playwright.',
+      'config.heroAlt': 'The agent drives the native sidebar browser through two tools.',
       'config.intro': 'Applies immediately to this profile. Page content work needs the DSH Desktop native browser carrier.',
       'config.enabled': 'Enable agent tools',
       'config.enabledHint': 'Register sidebar_browser and sidebar_page for agents in this profile.',
@@ -1161,6 +1164,9 @@ window.__ModuleLoader__.load({
     const CONFIG_ZH = {
       'config.summary': '配置侧栏浏览器工具：启用开关、域名白名单与权限。',
       'config.heading': '侧栏浏览器 Agent 控制',
+      'config.heroTitle': '让 Agent 操作右侧栏里的真实网页',
+      'config.heroSubtitle': '读取、点击、输入、滚动、执行 JavaScript、截图 —— 全部通过原生 Electron webview，无代理、无 Playwright。',
+      'config.heroAlt': 'Agent 通过两个工具驱动侧栏原生浏览器。',
       'config.intro': '修改立即对本 profile 生效。页面内容操作需要 DSH Desktop 原生浏览器载体。',
       'config.enabled': '启用 Agent 工具',
       'config.enabledHint': '为本 profile 中的 Agent 注册 sidebar_browser 与 sidebar_page。',
@@ -1182,6 +1188,75 @@ window.__ModuleLoader__.load({
       'config.readOnlyHint': 'Host 不接受在此写入配置。',
     }
 
+    /** Inline hero diagram; kept in sync with `assets/how-it-works.svg`. */
+    const HOW_IT_WORKS_SVG = `<svg width="720" height="230" viewBox="0 0 720 230" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g>
+  <defs>
+    <linearGradient id="hiw-blue" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#67C7FE"/><stop offset="1" stop-color="#3F77D8"/>
+    </linearGradient>
+    <linearGradient id="hiw-teal" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#6AECB6"/><stop offset="1" stop-color="#37A6B1"/>
+    </linearGradient>
+    <linearGradient id="hiw-arrow" x1="260" y1="84" x2="336" y2="84" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#9AA7FF"/><stop offset="1" stop-color="#5F7BF0"/>
+    </linearGradient>
+    <filter id="hiw-shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="6" stdDeviation="10" flood-color="#4a3f8f" flood-opacity="0.10"/>
+    </filter>
+  </defs>
+  <!-- agent tool chips -->
+  <g filter="url(#hiw-shadow)">
+    <rect x="0" y="26" width="250" height="48" rx="13" fill="#FFFFFF" stroke="#E4DFF5"/>
+    <rect x="14" y="38" width="24" height="24" rx="7" fill="url(#hiw-blue)"/>
+    <rect x="20" y="44" width="7" height="7" rx="2" fill="#FFFFFF" fill-opacity="0.95"/>
+    <rect x="29" y="49" width="4" height="4" rx="1" fill="#FFFFFF" fill-opacity="0.55"/>
+    <text x="50" y="56" font-family="SFMono-Regular, Menlo, monospace" font-size="15" fill="#3A3560">sidebar_browser</text>
+    <rect x="14" y="88" width="24" height="24" rx="7" fill="url(#hiw-teal)"/>
+    <rect x="20" y="94" width="9" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.95"/>
+    <rect x="20" y="100" width="6" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.7"/>
+    <rect x="20" y="106" width="7.5" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.45"/>
+  </g>
+  <g filter="url(#hiw-shadow)">
+    <rect x="0" y="88" width="250" height="48" rx="13" fill="#FFFFFF" stroke="#E4DFF5"/>
+    <rect x="14" y="100" width="24" height="24" rx="7" fill="url(#hiw-teal)"/>
+    <rect x="20" y="106" width="9" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.95"/>
+    <rect x="20" y="112" width="6" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.7"/>
+    <rect x="20" y="118" width="7.5" height="3" rx="1.5" fill="#FFFFFF" fill-opacity="0.45"/>
+    <text x="50" y="118" font-family="SFMono-Regular, Menlo, monospace" font-size="15" fill="#3A3560">sidebar_page</text>
+  </g>
+  <!-- arrow -->
+  <path d="M266 82H322" stroke="url(#hiw-arrow)" stroke-width="3" stroke-linecap="round"/>
+  <path d="M318 74L330 82L318 90" stroke="#5F7BF0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  <!-- browser window -->
+  <g filter="url(#hiw-shadow)">
+    <rect x="342" y="4" width="374" height="222" rx="18" fill="#FFFFFF" stroke="#E4DFF5"/>
+    <rect x="342" y="4" width="374" height="34" rx="18" fill="#FAF8FF"/>
+    <rect x="342" y="21" width="374" height="17" fill="#FAF8FF"/>
+    <circle cx="360" cy="21" r="4" fill="#D9D4EC"/>
+    <circle cx="372" cy="21" r="4" fill="#D9D4EC"/>
+    <circle cx="384" cy="21" r="4" fill="#D9D4EC"/>
+    <rect x="402" y="13" width="196" height="16" rx="8" fill="#F0EDFA"/>
+    <rect x="414" y="18" width="92" height="6" rx="3" fill="#C9C3E4"/>
+    <!-- sidebar list -->
+    <rect x="354" y="48" width="74" height="166" rx="12" fill="#F6F3FE"/>
+    <rect x="364" y="60" width="54" height="9" rx="4.5" fill="url(#hiw-teal)" fill-opacity="0.9"/>
+    <rect x="364" y="78" width="42" height="9" rx="4.5" fill="#CFC8EC"/>
+    <rect x="364" y="96" width="48" height="9" rx="4.5" fill="#DCD6F1"/>
+    <rect x="364" y="114" width="38" height="9" rx="4.5" fill="#DCD6F1"/>
+    <!-- page -->
+    <rect x="440" y="48" width="264" height="166" rx="12" fill="#FBFAFF" stroke="#EFEBFA"/>
+    <rect x="456" y="64" width="132" height="10" rx="5" fill="#E4DEF6"/>
+    <rect x="456" y="84" width="176" height="10" rx="5" fill="#EDE8F8"/>
+    <rect x="456" y="104" width="112" height="10" rx="5" fill="#EDE8F8"/>
+    <rect x="456" y="128" width="104" height="22" rx="11" fill="#E2F7EE" stroke="#7CDDB4" stroke-opacity="0.7"/>
+    <rect x="468" y="137" width="66" height="6" rx="3" fill="#37A6B1" fill-opacity="0.55"/>
+    <!-- cursor -->
+    <path d="M566 128L566 158L574 150L580 161L588 157L581 146L593 145Z" fill="url(#hiw-blue)" stroke="#FFFFFF" stroke-width="1.6" stroke-linejoin="round"/>
+  </g>
+</g>
+</svg>`
+
     const configStyles = {
       root: { display: 'flex', flexDirection: 'column', gap: '18px', maxWidth: '620px', color: 'var(--dsw-alias-label-primary)', fontSize: '13px', lineHeight: '20px' },
       heading: { margin: 0, fontSize: '15px', fontWeight: 600, lineHeight: '22px' },
@@ -1226,13 +1301,35 @@ window.__ModuleLoader__.load({
         cursor: 'pointer',
         font: 'inherit',
       },
+      // Hero illustration shown above the official settings form. The SVG is
+      // inline so it travels with the installed bundle and needs no asset route.
+      heroCard: {
+        margin: '0 0 20px',
+        padding: '24px 26px',
+        border: '0.5px solid var(--dsw-alias-border-l1)',
+        borderRadius: 'var(--dsw-radius-xl, 14px)',
+        background: 'linear-gradient(135deg, color-mix(in srgb, var(--dsw-alias-brand-primary) 6%, var(--dsw-alias-bg-layer-1)), color-mix(in srgb, var(--dsw-alias-brand-primary) 14%, var(--dsw-alias-bg-layer-1)))',
+      },
+      heroTitle: { margin: '0 0 6px', color: 'var(--dsw-alias-label-primary)', fontSize: '18px', fontWeight: 600, lineHeight: 1.4 },
+      heroSubtitle: { margin: '0 0 16px', color: 'var(--dsw-alias-label-secondary)', fontSize: '13px', lineHeight: 1.5 },
+      heroDiagram: { display: 'block', width: '100%', height: 'auto' },
       // --- official-style settings page (shared SettingsForm + Switch) ---
-      switchList: { display: 'flex', flexDirection: 'column' },
+      // Mirrors the built-in settings page rhythm: the shared form only stacks
+      // children, so each block below brings its own 12px vertical padding, the
+      // same scale the official fields and rows use.
+      formBody: { display: 'flex', flexDirection: 'column' },
+      noticeOfficial: {
+        margin: '0 0 4px',
+        color: 'var(--dsw-alias-label-secondary)',
+        fontSize: '13px',
+        lineHeight: 1.5,
+      },
+      switchList: { display: 'flex', flexDirection: 'column', padding: '12px 0' },
       switchRow: {
         display: 'flex',
         alignItems: 'center',
         gap: '16px',
-        minHeight: '44px',
+        minHeight: '40px',
         padding: '8px 0',
         borderBottom: '0.5px solid var(--dsw-alias-border-l2)',
       },
@@ -1240,28 +1337,29 @@ window.__ModuleLoader__.load({
         display: 'flex',
         alignItems: 'center',
         gap: '16px',
-        minHeight: '44px',
+        minHeight: '40px',
         padding: '8px 0',
       },
       switchText: { display: 'flex', flexDirection: 'column', gap: '2px', flex: '1 1 auto', minWidth: 0 },
-      switchLabel: { color: 'var(--dsw-alias-label-primary)', fontSize: '13px', lineHeight: '20px', fontWeight: 500 },
-      switchHint: { color: 'var(--dsw-alias-label-secondary)', fontSize: '13px', lineHeight: '18px' },
-      fieldLabel: { color: 'var(--dsw-alias-label-primary)', fontSize: '13px', lineHeight: '20px' },
+      switchLabel: { color: 'var(--dsw-alias-label-primary)', fontSize: '13px', lineHeight: 1.5, fontWeight: 500 },
+      switchHint: { color: 'var(--dsw-alias-label-tertiary)', fontSize: '12px', lineHeight: 1.5 },
+      field: { display: 'flex', flexDirection: 'column', gap: '6px', padding: '12px 0' },
+      fieldLabel: { color: 'var(--dsw-alias-label-primary)', fontSize: '13px', lineHeight: 1.5, fontWeight: 500 },
+      fieldHint: { color: 'var(--dsw-alias-label-tertiary)', fontSize: '12px', lineHeight: 1.5 },
       textareaOfficial: {
         boxSizing: 'border-box',
         width: '100%',
         minHeight: '96px',
         color: 'var(--dsw-alias-label-primary)',
-        background: 'var(--dsw-alias-bg-base)',
+        background: 'var(--dsw-alias-bg-layer-3)',
         border: '0.5px solid var(--dsw-alias-border-l4)',
         borderRadius: 'var(--dsw-radius-md, 8px)',
         font: 'inherit',
         fontSize: '13px',
-        lineHeight: '20px',
-        padding: '8px 10px',
+        lineHeight: 1.5,
+        padding: '8px 12px',
         resize: 'vertical',
       },
-      noticeOfficial: { color: 'var(--dsw-alias-label-secondary)', margin: 0, fontSize: '13px', lineHeight: '20px' },
     }
 
     /**
@@ -1378,7 +1476,7 @@ window.__ModuleLoader__.load({
         switchRow(t, { label: 'config.enabled', hint: 'config.enabledHint', checked: draft.enabled, disabled: readOnly, onChange: (next) => setDraft({ ...draft, enabled: next }) }),
         React.createElement('div', { style: configStyles.field },
           React.createElement('span', { style: configStyles.checkLabel }, t('config.hosts')),
-          React.createElement('span', { style: configStyles.hint }, t('config.hostsHint')),
+          React.createElement('span', { style: configStyles.fieldHint }, t('config.hostsHint')),
           React.createElement('textarea', {
             style: configStyles.textarea,
             rows: 4,
@@ -1492,13 +1590,26 @@ window.__ModuleLoader__.load({
         }),
       )
       return React.createElement(SettingsForm, { labels, state: model, onSave: save, onDiscard: discard },
-        React.createElement('p', { style: configStyles.noticeOfficial }, t('config.intro')),
-        React.createElement('div', { style: configStyles.switchList },
+        React.createElement('div', { style: configStyles.formBody },
+          React.createElement('div', {
+            style: configStyles.heroCard,
+            role: 'img',
+            'aria-label': t('config.heroAlt'),
+          },
+            React.createElement('h3', { style: configStyles.heroTitle }, t('config.heroTitle')),
+            React.createElement('p', { style: configStyles.heroSubtitle }, t('config.heroSubtitle')),
+            React.createElement('div', {
+              style: configStyles.heroDiagram,
+              dangerouslySetInnerHTML: { __html: HOW_IT_WORKS_SVG },
+            }),
+          ),
+          React.createElement('p', { style: configStyles.noticeOfficial }, t('config.intro')),
+          React.createElement('div', { style: configStyles.switchList },
           toggleRow('enabled', 'config.enabled', 'config.enabledHint', false),
           toggleRow('allowEval', 'config.allowEval', 'config.allowEvalHint', false),
-          toggleRow('allowNativeInput', 'config.allowNativeInput', 'config.allowNativeInputHint', true),
-        ),
-        React.createElement('div', { style: configStyles.field },
+            toggleRow('allowNativeInput', 'config.allowNativeInput', 'config.allowNativeInputHint', true),
+          ),
+          React.createElement('div', { style: configStyles.field },
           React.createElement('span', { style: configStyles.fieldLabel }, t('config.hosts')),
           React.createElement('textarea', {
             style: configStyles.textareaOfficial,
@@ -1509,7 +1620,8 @@ window.__ModuleLoader__.load({
             value: draft.hostsText,
             onChange: (event) => setDraft({ ...draft, hostsText: event.target.value }),
           }),
-          React.createElement('span', { style: configStyles.hint }, t('config.hostsHint')),
+            React.createElement('span', { style: configStyles.fieldHint }, t('config.hostsHint')),
+          ),
         ),
       )
     }

package/lib/{entry-0.2.8.js → entry-0.2.10.js}

@@ -20,7 +20,7 @@ import z from '../vendor/schemastery/index.mjs'
 export const name = 'dsh-sidebar-browser-agent'
 
 /** Plugin version reported by diagnostics; keep in sync with package.json. */
-export const PLUGIN_VERSION = '0.2.8'
+export const PLUGIN_VERSION = '0.2.10'
 
 /** Services that must exist before this plugin mounts. */
 export const inject = ['webServer', 'connection', 'tools']

package/lib/index.js

@@ -20,7 +20,7 @@ import z from '../vendor/schemastery/index.mjs'
 export const name = 'dsh-sidebar-browser-agent'
 
 /** Plugin version reported by diagnostics; keep in sync with package.json. */
-export const PLUGIN_VERSION = '0.2.8'
+export const PLUGIN_VERSION = '0.2.10'
 
 /** Services that must exist before this plugin mounts. */
 export const inject = ['webServer', 'connection', 'tools']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sidebar-browser-agent",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "type": "module",
   "icon": "./icon.svg",
   "description": "Native agent control for the DSH right-sidebar browser: manage tabs, and read, click, type, scroll, run JavaScript in and screenshot the real page through its Electron guest.",
@@ -20,7 +20,7 @@
     "electron-webview"
   ],
   "exports": {
-    ".": "./lib/entry-0.2.8.js",
+    ".": "./lib/entry-0.2.10.js",
     "./client": "./lib/client.js",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg"

package/test/client-harness.mjs

@@ -538,6 +538,10 @@ async function main() {
   // --- configuration page: locale, slot registration and rendering ---
   const localeEntry = localeRegistrations.find((entry) => entry.ns === 'sidebarBrowserAgent')
   check('config locale registered', localeEntry !== undefined && localeEntry.dicts.en !== undefined && localeEntry.dicts.zh !== undefined, localeRegistrations.map((entry) => entry.ns))
+  check('config locale carries the hero copy',
+    localeEntry.dicts.en['config.heroTitle'] !== undefined && localeEntry.dicts.zh['config.heroTitle'] !== undefined
+    && localeEntry.dicts.en['config.heroSubtitle'] !== undefined && localeEntry.dicts.zh['config.heroSubtitle'] !== undefined,
+    Object.keys(localeEntry.dicts.en).filter((key) => key.startsWith('config.hero')))
   const slotEntry = slotRegistrations.find((entry) => entry.options?.name === 'plugins.row.config')
   check('row config slot registered', slotEntry !== undefined
     && slotEntry.options.key === 'dsh-sidebar-browser-agent#sidebar-browser-agent'