dsh-live-browser 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-live-browser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,298 @@
+# dsh-live-browser
+
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/c347087870/dsh-live-browser)
+
+Let the agent drive the browser DSH already ships — inside DSH, with nothing
+leaving the window.
+
+[中文](README.md) | English
+
+DSH's own `@deepseek-ai/dsh-client-ui-sidebar-browser` renders a real Electron
+`<webview>` in the right sidebar, with an address bar, history and an independent
+browser session. It exposes navigation only, so the agent can open a page but
+cannot click, type, read or scroll it.
+
+This plugin closes that gap **without modifying DSH**: it finds the guests that
+plugin mounted, injects a command surface into each document, and gives the model
+25 `browser_*` tools that operate the page the human is looking at. It also fills
+in the tab's right-click menu: **close other tabs / close all tabs / close tabs to
+the right**.
+
+## Install
+
+Requires DSH 0.2.x and Node.js 20 or newer. The plugin declares its DSH bundle in
+`package.json`, so DSH registers it on install.
+
+### From GitHub
+
+```bash
+# Web / CLI profile
+dsh plugin --profile web add github:c347087870/dsh-live-browser
+```
+
+The desktop profile is owned by the Electron application, so install it from the
+UI instead: **Plugins → Add plugin**, paste
+`https://github.com/c347087870/dsh-live-browser`, then restart DSH.
+
+### From npm
+
+No npm package yet; once published the command is
+`dsh plugin --profile web add dsh-live-browser`.
+
+### Verify the install
+
+```bash
+node -e "const p=require('./node_modules/dsh-live-browser/package.json');console.log(p.version, p.dsh)"
+```
+
+`dsh.bundle.patch` must be present, and `lib/index.js` must exist. After a
+restart the plugin logs
+`[dsh-live-browser] loaded: 25 tools, driving the DSH sidebar browser`.
+
+> A junction (`mklink /J`, `ln -s`) does **not** work for local development: Node
+> resolves the real path, so `schemastery` is looked up where the source lives
+> rather than in the profile. Copy the package directory, or install it with
+> `dsh plugin`.
+
+## Settings
+
+DSH renders these on the plugin's settings card. Every one has a default, so the
+plugin works without touching any of them.
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `confirmSensitive` | `true` | Ask the user before an action marked `sensitive` |
+| `allowEval` | `true` | Allow `browser_eval` to run arbitrary JavaScript in the page |
+| `autoOpenPanel` | `true` | Open the sidebar browser when a command arrives with no page |
+| `commandTimeoutMs` | `30000` | How long one command may wait for the panel |
+| `openPanelWaitMs` | `8000` | How long to wait for a new panel to become ready |
+| `maxSnapshotNodes` | `400` | Default node cap for `browser_snapshot` |
+| `maxTextChars` | `12000` | Default character cap for `browser_read_text` |
+| `waitTimeoutMs` | `10000` | Default timeout for `browser_wait` |
+| `uploadMaxBytes` | `16777216` | Largest file `browser_upload` will hand to a page |
+| `imageDir` | empty | Where `browser_screenshot` writes PNGs; empty uses `~/.dsh/storages/dsh-live-browser/images` |
+| `downloadsDir` | empty | Directory `browser_downloads` lists; empty uses the system Downloads folder |
+
+`allowEval: false` is the switch to reach for if you want the agent to read pages
+without running code in them. `browser_eval` then returns `executed: false` and
+points at `browser_snapshot` / `browser_read_text` instead.
+
+## Opening the browser
+
+The agent never asks you to open a browser first, and it never reaches for an
+external window:
+
+- Tools queue a command on the host, tagged with the **conversation** that asked.
+- The plugin's client bundle polls continuously, even when no browser tab exists.
+- If a command arrives with no page on screen, the client opens the **DSH sidebar
+  browser** itself (the same `openTabIn(sessionId, 'browser', …)` call the sidebar
+  uses internally), waits for the guest to mount, then runs the command.
+
+So `browser_navigate` on a cold start shows up as a sidebar tab that opens by
+itself and loads the requested page.
+
+### One browser per conversation
+
+DSH keeps a separate sidebar per Session, and this plugin respects that:
+
+- Every command carries the Session id of the chat that issued it
+  (`exec.agent.session.id` on the host).
+- A panel only receives commands belonging to its own Session, so a second chat's
+  sidebar polling at the same time cannot steal them.
+- A panel only targets the sidebar of the chat **on screen**: background chats keep
+  theirs mounted (`keepMounted`), but those are marked `hidden` and are never
+  mistaken for the page in front of the human.
+- After switching chats, commands belonging to the old chat are refused with an
+  explanation instead of running against a page nobody can see.
+- When the browser has to be opened, it opens in the **requesting** chat via
+  `openTabIn(sessionId, …)`, not in whichever chat happens to be on screen.
+
+That is what stops the old failure mode: ask for a page in chat A, switch to chat
+B before it opens, and find the browser in B.
+
+> Why the renderer does the opening: the sidebar lives entirely in the client —
+> its host module contributes nothing — so there is no host service to call. The
+> client half publishes `sidebarRight` through `ctx.reflect.provide`, which is
+> what this plugin uses.
+
+## Why this shape
+
+| | This plugin | Patching the shipped bundle |
+|---|---|---|
+| Click / type / read / scroll | yes | yes |
+| Export a page's charts as PNG | yes, via the page's own canvas/SVG | yes |
+| Native window screenshots | no | yes |
+| Survives a DSH upgrade | yes | no — re-patch every release |
+| Risk to existing features | none | can break sidebar link handling |
+
+## How it works
+
+```
+agent tool call
+      │  bridge.call(method, params)          lib/bridge.js
+      ▼
+  command queue  ──────►  panel long-polls   client.js
+                                │
+                                ├─ no guest yet → open the sidebar browser (openTabIn)
+                                ├─ page commands  → injected script in the guest
+                                ├─ browser commands → guest element (loadURL/goBack…)
+                                └─ tab commands   → sidebar service
+                                │
+                          settle(result)
+                                ▼
+                        tool result
+
+right-click a tab ──► decorate the menu (client.js) ──► close others / all / to the right
+```
+
+- **`lib/bridge.js`** — the queue and the long poll. Cold calls stay queued long
+  enough for the client to open a tab; a call that never gets a panel fails with
+  an actionable message instead of hanging.
+- **`lib/agent-script.js`** — the script injected into every guest document. Pure
+  DOM: snapshot with stable `ref`s, click, type, press, select, hover, scroll,
+  read text, evaluate, wait, attach files, capture canvas/SVG to PNG.
+- **`lib/rpc.js`** — one prefix route on the DSH web server (`/dsh-live-browser`)
+  speaking the panel's small request/response envelope. Every request is checked
+  for a same-origin browser and loopback host, because the route can write files
+  (`saveImage`) and read them (`readUpload`).
+- **`lib/config.js` / `lib/schema.js`** — the settings values and the form DSH
+  renders. Values are dependency-free so the tool layer and tests can read them
+  without a `node_modules` tree.
+- **`client.js`** — finds the guest inside **the current conversation's** sidebar
+  (`webview[data-sidebar-browser-frame="webview"]`), injects the script, opens the
+  tab when needed, and runs the poll loop. Background chats keep their sidebars
+  mounted (`keepMounted`) but `hidden`, so they are never mistaken for the one on
+  screen; among several tabs it picks the one that is actually laid out, not the
+  last mounted. It also decorates the tab context menu: a `contextmenu` listener
+  waits for DSH's menu portal and appends the three entries, still without
+  touching DSH. IIFE-wrapped: DSH batches plugin bundles into one combo
+  `<script>`, so a top-level `const` would collide with a sibling.
+
+### Why not `connection.rpc.handle`
+
+On dsh 0.2.1-rc.2 that API builds its route with
+`owner.effect(() => owner.webServer.register(route))`, where `owner` is the
+connection plugin's own context — which never declared a `webServer` dependency.
+The property read throws `cannot get property "webServer" without inject`, the
+effect swallows it, and every panel request falls through to the static frontend
+fallback as **HTTP 405**. Registering on `webServer` directly is the same call
+without the broken indirection.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `browser_status` | Is the panel open, what page is showing |
+| `browser_open_panel` | Open the sidebar browser (also happens automatically) |
+| `browser_navigate` / `back` / `forward` / `reload` | Navigation |
+| `browser_snapshot` | Accessibility-style node list with stable `ref`s |
+| `browser_read_text` | Visible body text, optionally scoped by selector |
+| `browser_click` / `type` / `press` / `select` / `hover` | Page interaction |
+| `browser_scroll` / `wait` | Scrolling and waiting |
+| `browser_eval` | Run a JS expression in the page |
+| `browser_screenshot` | Export a chart (canvas/SVG) or element as a PNG file |
+| `browser_tabs` / `tab_new` | List tabs, open a new browser tab |
+| `browser_upload` | Attach local files to a file input |
+| `browser_downloads` | List files in the downloads folder |
+| `browser_confirm` | Ask the human to confirm an irreversible action |
+
+### Tabs
+
+The sidebar keeps its tab ids internal. The plugin acts on the focused guest, or
+on the tab that is actually laid out in the current chat's sidebar when nothing
+is focused: every visited tab stays mounted, so document order is not what the
+human sees. There is no `tab` argument to aim it elsewhere: the parameter used to
+exist and was silently dropped, which let a caller believe it had targeted a
+specific tab. `browser_tabs` still lists what is open.
+
+The tab's right-click menu gains three entries: **close other tabs**, **close all
+tabs**, and **close tabs to the right** (everything after this tab; the current
+tab stays, and entries with nothing to close are disabled). Order comes from the
+strip of the pane the menu was opened in, so split panes stay independent; the
+menu itself still belongs to DSH. Floating panes have no strip, so they do not get
+these entries.
+
+### Honest limits
+
+Three things DSH does not let a plugin do, reported as structured results rather
+than silent failures:
+
+- **`browser_tab_close` / `browser_tab_activate`** — the sidebar keeps tab ids
+  internal; the tool tells you to click the tab yourself.
+- **`browser_reset_profile`** — the browser session is not exposed for clearing;
+  the tool returns step-by-step instructions.
+- **Native window screenshots** — the guest renders natively, so there are no
+  pixels at the DOM level. `browser_screenshot` instead asks the page to
+  rasterise its own `<canvas>`/`<svg>`, which is exactly what charts are.
+
+## Security
+
+- The plugin never patches DSH. It reads the DOM the official sidebar browser
+  renders and injects a script into guests the official plugin mounted.
+- `browser_eval` runs arbitrary JavaScript in whatever page is loaded. That is the
+  point of the tool and the reason `allowEval` exists.
+- Actions marked `sensitive` ask the user first while `confirmSensitive` is on.
+  A missing question channel denies rather than allows.
+- The `/dsh-live-browser` route refuses cross-site and non-loopback callers. A
+  local process could still spoof the headers, but it can already read and write
+  the same files as you.
+
+## Tests
+
+```bash
+node test/test-all.mjs
+```
+
+Thirteen suites. Two groups:
+
+- **No browser needed** — package integrity, tool contracts, the tool layer, the
+  bridge, the end-to-end path, the client driver, session binding, the tab menu,
+  settings, DOM behaviour. These run anywhere.
+- **Need a live page** — scenarios and chart capture. They drive a real page
+  through the CDP harness in `test/fixtures/`, which exists **only** for testing;
+  the shipped plugin never touches Chrome directly. Start one with
+  `node scripts/ensure-browser.mjs`, or let them report `SKIP`.
+
+`test/test-rpc-http.mjs` needs a running DSH:
+
+```bash
+node test/test-rpc-http.mjs "http://127.0.0.1:PORT/?token=..."
+```
+
+Paths for the test browser can be overridden with `DSH_TEST_CDP_PORT`,
+`DSH_TEST_PROFILE_DIR` and `DSH_TEST_DOWNLOAD_DIR`.
+
+> After editing the source locally, **DSH must be restarted**: host plugin tool
+> registration happens only at process start, so file changes do not take effect.
+> Until the restart, the `browser_*` tools and the `/dsh-live-browser` route do not
+> exist (an HTTP 405 from that route is the signal that it is not loaded).
+
+## Publish
+
+The plugin is installable straight from GitHub or npm with no registry step. To
+have it listed in the community plugin markets that index GitHub, the repository
+carries the `dsh-plugin` topic; those indexes rescan on their own schedule.
+
+## Changelog
+
+### 0.4.0
+
+- Fixed: the first sidebar in the document was treated as the current chat's
+  sidebar, so the agent could read another chat's / another tab's page. It now
+  follows the sidebar of the chat on screen and the tab that is actually shown.
+- Fixed: after switching chats, commands belonging to the old chat are refused
+  with an explanation instead of running against a page nobody can see.
+- Fixed: `browser_status` / `browser_open_panel` report the panel of the current
+  chat only.
+- Added: tab context menu entries — close other tabs / close all tabs / close tabs
+  to the right.
+- Fixed: `autoOpenPanel` was declared but never honoured; turning it off now stops
+  the automatic open.
+
+### 0.3.0
+
+- Cold-start auto-open, per-session binding, tab listing and chart capture.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,312 @@
-# Temporary Holding Version
+# dsh-live-browser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/zh/plugins/c347087870/dsh-live-browser)
+
+让 agent 操作 DSH 自带的那个浏览器 —— 就在 DSH 里，什么都不离开窗口。
+
+中文 | [English](README.en.md)
+
+DSH 自带的 `@deepseek-ai/dsh-client-ui-sidebar-browser` 会在右侧栏渲染一个真正的
+Electron `<webview>`，带地址栏、历史记录和独立的浏览器会话。但它只开放了导航能力：
+agent 能打开页面，却点不了、输不进、读不到、滚不动。
+
+这个插件在**不修改 DSH 任何文件**的前提下补上这一段：找到官方插件挂载的那些 guest，
+往每个文档里注入一套操作接口，再给模型 25 个 `browser_*` 工具，操作的正是用户眼前那张页面。
+顺带把标签页右键菜单补全：**关闭其他标签页 / 关闭全部标签页 / 关闭右侧所有标签页**。
+
+## 安装
+
+需要 DSH 0.2.x 与 Node.js 20 以上。插件在 `package.json` 里声明了 DSH 组合包，安装时
+DSH 会自动注册。
+
+### 从 GitHub 安装
+
+```bash
+# Web / CLI profile
+dsh plugin --profile web add github:c347087870/dsh-live-browser
+```
+
+桌面版的 profile 由 Electron 应用独占，请从界面安装：**插件 → 添加插件**，粘贴
+`https://github.com/c347087870/dsh-live-browser`，然后重启 DSH。
+
+### 从 npm 安装
+
+npm 包尚未发布；发布后安装命令为 `dsh plugin --profile web add dsh-live-browser`。
+
+### 确认装好了
+
+```bash
+node -e "const p=require('./node_modules/dsh-live-browser/package.json');console.log(p.version, p.dsh)"
+```
+
+`dsh.bundle.patch` 必须存在，`lib/index.js` 必须存在。重启后日志里会出现
+`[dsh-live-browser] loaded: 25 tools, driving the DSH sidebar browser`。
+
+> 本地开发**不要**用 junction（`mklink /J`、`ln -s`）：Node 会解析真实路径，于是
+> `schemastery` 去源码目录找而不是去 profile 找。要么复制整个包目录，要么用
+> `dsh plugin` 安装。
+
+## 配置项
+
+DSH 会把这些渲染在插件的设置卡片里。每一项都有默认值，不动也能用。
+
+| 配置 | 默认 | 含义 |
+|---|---|---|
+| `confirmSensitive` | `true` | 标记为 `sensitive` 的动作执行前先问用户 |
+| `allowEval` | `true` | 是否允许 `browser_eval` 在页面里执行任意 JavaScript |
+| `autoOpenPanel` | `true` | 命令到达但没有页面时，自动打开侧边栏浏览器 |
+| `commandTimeoutMs` | `30000` | 单次命令等待面板执行的超时（毫秒） |
+| `openPanelWaitMs` | `8000` | 打开面板后等待其就绪的时间 |
+| `maxSnapshotNodes` | `400` | `browser_snapshot` 默认节点上限 |
+| `maxTextChars` | `12000` | `browser_read_text` 默认字符上限 |
+| `waitTimeoutMs` | `10000` | `browser_wait` 默认超时（毫秒） |
+| `uploadMaxBytes` | `16777216` | `browser_upload` 单个文件的上限 |
+| `imageDir` | 空 | `browser_screenshot` 的图片目录；留空用 `~/.dsh/storages/dsh-live-browser/images` |
+| `downloadsDir` | 空 | `browser_downloads` 读取的目录；留空用系统「下载」文件夹 |
+
+想让 agent 只读页面、不在页面里跑代码，就把 `allowEval` 关掉。`browser_eval` 随后
+返回 `executed: false`，并提示改用 `browser_snapshot` / `browser_read_text`。
+
+## 浏览器会自己打开
+
+agent 不会先让你去开浏览器，也永远不会去开外部窗口：
+
+- 工具把命令排进宿主队列，并标记它来自**哪个对话**。
+- 插件的客户端 bundle 一直在轮询，即使当前一个浏览器标签页都没有。
+- 命令到达时如果没有页面，客户端会自己调用侧边栏的
+  `openTabIn(sessionId, 'browser', …)` 打开浏览器标签页，等 guest 挂载好再执行。
+
+所以冷启动时一句 `browser_navigate`，表现就是右侧栏自己弹出一个标签页并加载目标地址。
+
+### 一个对话一个浏览器
+
+DSH 每个 Session 一个侧边栏，插件遵守这个边界：
+
+- 每条命令都带着发起它的 Session id（宿主侧取 `exec.agent.session.id`）。
+- 面板只收到属于自己 Session 的命令，别的对话的面板同时在轮询也抢不走。
+- 面板只认**屏幕上那个对话**的侧边栏：后台对话的侧边栏还挂在 DOM 里（`keepMounted`），
+  但它们被标了 `hidden`，不能被当成你眼前这一页。
+- 切走对话后，属于旧对话的命令会被拒绝并说明原因，而不是在看不见的页面上继续执行。
+- 需要打开浏览器时，用 `openTabIn(sessionId, …)` 在**发起请求的那个对话**里打开，
+  而不是在屏幕上恰好显示的那个对话里。
+
+这消除了老的故障模式：在 A 对话要页面，没等它出来就切到 B，结果浏览器出现在 B。
+
+> 为什么打开动作放在渲染层：侧边栏整个在客户端，它的宿主模块什么都不贡献，所以没有
+> 宿主服务可调。客户端那一半通过 `ctx.reflect.provide` 发布 `sidebarRight`，插件用的就是这个。
+
+## 为什么用这个形态
+
+| | 本插件 | 直接改官方 bundle |
+|---|---|---|
+| 点击 / 输入 / 读取 / 滚动 | 可以 | 可以 |
+| 把页面图表导成 PNG | 可以，用页面自己的 canvas/SVG | 可以 |
+| 截原生窗口 | 不行 | 可以 |
+| 经得起 DSH 升级 | 可以 | 不行，每个版本都要重打补丁 |
+| 对现有功能的风险 | 无 | 可能破坏侧边栏的链接处理 |
+
+## 工作原理
+
+```
+工具调用
+      │  bridge.call(method, params)          lib/bridge.js
+      ▼
+   命令队列  ──────►  面板长轮询              client.js
+                          │
+                          ├─ 还没有 guest → 打开侧边栏浏览器（openTabIn 本对话）
+                          ├─ 页面命令     → 注入到 guest 里的脚本
+                          ├─ 浏览器命令   → guest 元素本身（loadURL/goBack…）
+                          └─ 标签页命令   → 侧边栏服务
+                          │
+                    settle(result)
+                          ▼
+                      工具结果
+
+右键标签页 ──► 菜单 DOM 装饰（client.js）──► 关闭其他 / 全部 / 右侧
+```
+
+- **`lib/bridge.js`** —— 队列与长轮询。冷调用会在队列里留够时间让客户端把标签页开出来；
+  始终等不到面板的调用会带着可操作的提示失败，而不是一直挂着。
+- **`lib/agent-script.js`** —— 注入每个 guest 文档的脚本。纯 DOM：带稳定 `ref` 的快照、
+  点击、输入、按键、选择、悬停、滚动、读正文、执行表达式、等待、附加文件、canvas/SVG 转 PNG。
+- **`lib/rpc.js`** —— 挂在 DSH web server 上的一个前缀路由（`/dsh-live-browser`），说面板那套
+  简单的请求/响应信封。每个请求都校验同源与回环主机，因为这个路由既能写文件（`saveImage`）
+  也能读文件（`readUpload`）。
+- **`lib/config.js` / `lib/schema.js`** —— 配置值与 DSH 渲染的表单。取值部分不依赖第三方包，
+  所以工具层和测试不需要 `node_modules` 就能跑。
+- **`client.js`** —— 找到**当前对话**那个侧边栏里的
+  `webview[data-sidebar-browser-frame="webview"]`，注入脚本，需要时打开标签页，跑轮询循环。
+  后台对话的侧边栏还挂在 DOM 里（`keepMounted`），但被标了 `hidden`，插件不会误认；
+  同一栏里有多个标签时，挑真正有布局盒子的那个，而不是最后挂载的那个。标签页右键菜单
+  也在这里补三项：监听 `contextmenu`，等 DSH 的菜单 portal 出现后追加按钮，仍然不改 DSH。
+  整体包在 IIFE 里：DSH 会把多个插件 bundle 塞进同一个 combo `<script>`，顶层 `const`
+  会跟邻居撞名。
+
+### 为什么不用 `connection.rpc.handle`
+
+在 dsh 0.2.1-rc.2 上，这个 API 用
+`owner.effect(() => owner.webServer.register(route))` 建路由，而 `owner` 是 connection
+插件自己的 context —— 它从没声明过 `webServer` 依赖。于是属性读取抛
+`cannot get property "webServer" without inject`，effect 把错误吞掉，面板请求全部落到
+静态前端兜底，表现为 **HTTP 405**。直接在 `webServer` 上注册是同一个调用，只是绕开了
+那层坏掉的间接。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `browser_status` | 面板是否打开、当前是什么页面 |
+| `browser_open_panel` | 打开侧边栏浏览器（也会自动发生） |
+| `browser_navigate` / `back` / `forward` / `reload` | 导航 |
+| `browser_snapshot` | 无障碍风格的节点列表，带稳定 `ref` |
+| `browser_read_text` | 可见正文，可用选择器限定范围 |
+| `browser_click` / `type` / `press` / `select` / `hover` | 页面交互 |
+| `browser_scroll` / `wait` | 滚动与等待 |
+| `browser_eval` | 在页面里执行一段 JS 表达式 |
+| `browser_screenshot` | 把图表（canvas/SVG）或元素导出成 PNG |
+| `browser_tabs` / `tab_new` | 列出标签页、新建标签页 |
+| `browser_upload` | 给文件输入框附加本地文件 |
+| `browser_downloads` | 列出下载目录里的文件 |
+| `browser_confirm` | 请用户确认一个不可撤销的动作 |
+
+### 关于标签页
+
+侧边栏把标签页 id 留在内部。插件操作的是获得焦点的那个 guest；没有焦点时，用当前对话的
+右侧栏里真正显示着的那个标签页 —— 访问过的标签页都会保活挂在 DOM 里，按挂载顺序取最后一个
+会点到看不见的页面。也没有 `tab` 参数去指别处 —— 这个参数以前存在却被静默丢弃，会让调用方
+误以为自己指定了某个标签页。`browser_tabs` 仍然可以列出当前有哪些。
+
+右键标签页的菜单里，插件补了三个动作：**关闭其他标签页**、**关闭全部标签页**、
+**关闭右侧所有标签页**（当前标签右侧的全部，当前标签保留；没得关时置灰）。顺序取自当前
+分栏的标签条，分栏两侧互不影响；菜单本体仍是 DSH 的，插件不接管它。浮动分栏没有标签条，
+因此不提供这组动作。
+
+### 说实话的限制
+
+有三件事 DSH 不开放给插件，插件以结构化结果如实报告，而不是假装成功：
+
+- **`browser_tab_close` / `browser_tab_activate`** —— 侧边栏的标签 id 是内部的，工具会
+  请你自己去点标签。
+- **`browser_reset_profile`** —— 浏览器会话没有开放清理接口，工具返回操作步骤。
+- **截原生窗口** —— guest 渲染在原生层，DOM 层面没有像素。`browser_screenshot` 改为让
+  页面自己栅格化它的 `<canvas>`/`<svg>`，而这正是图表。
+
+## 安全
+
+- 插件不改 DSH。它读官方侧边栏浏览器渲染出来的 DOM，往官方插件挂载的 guest 里注入脚本。
+- `browser_eval` 会在当前加载的任何页面里执行任意 JavaScript。这是这个工具存在的意义，
+  也是 `allowEval` 存在的原因。
+- `confirmSensitive` 开着时，标记为 `sensitive` 的动作会先问用户；没有确认通道时是拒绝，
+  不是放行。
+- `/dsh-live-browser` 路由拒绝跨站与非回环的调用方。本机进程仍能伪造这些头，但它本来就能
+  读写和你一样的文件。
+
+## 测试
+
+```bash
+node test/test-all.mjs
+```
+
+十三个套件，分两类：
+
+- **不需要浏览器** —— 包完整性、工具契约、工具层、桥接、端到端链路、客户端驱动、
+  会话绑定、标签菜单、设置项、DOM 行为。任何环境都能跑，`npm test` 即可。
+- **需要真实页面** —— 场景、注入脚本、图表导出。它们通过 `test/fixtures/` 里的 CDP
+  夹具驱动真实页面，这个夹具**只为测试而存在**；实际发的插件从不直接碰 Chrome。
+  用 `node scripts/ensure-browser.mjs` 起一个，或者让它们报 `SKIP`。
+
+「DOM 行为」和「端到端链路」原本也要真浏览器，现在改成在 jsdom 里跑同一份注入脚本，
+所以不需要 Chrome。图表导出没跟着改，因为 jsdom 的 canvas 要额外装原生包 `canvas`，
+为了跑测试把编译依赖架到使用者机器上不划算。
+
+`test/test-rpc-http.mjs` 需要一个正在运行的 DSH：
+
+```bash
+node test/test-rpc-http.mjs "http://127.0.0.1:PORT/?token=..."
+```
+
+测试浏览器的路径可以用 `DSH_TEST_CDP_PORT`、`DSH_TEST_PROFILE_DIR`、
+`DSH_TEST_DOWNLOAD_DIR` 覆盖。
+
+> 本地改源码后，**必须重启 DSH**：宿主插件的工具注册只在进程启动时发生，文件变化
+> 不会热生效。重启前 `browser_*` 工具和 `/dsh-live-browser` 路由都不存在（路由返回
+> HTTP 405 就是没加载的信号）。
+
+### 文件不能带 BOM
+
+`package.json` 这类文件如果开头混进 UTF-8 BOM，DSH 会报
+
+```
+installation rejected: Cannot validate installed package dsh-live-browser:
+SyntaxError: Unexpected token ... is not valid JSON
+```
+
+然后把 `package.json`、`pnpm-lock.yaml` 和 `node_modules` **整体回滚**——插件装不上，
+但代码本身毫无问题，现象是「工具和路由都不存在」，极难排查。
+
+Windows 上用 PowerShell 的 `Set-Content`、`Out-File` 写文件很容易带上 BOM。仓库里带了
+巡检脚本：
+
+```bash
+npm run strip-bom     # 扫掉全仓库文本文件的 BOM
+```
+
+`test/test-package-integrity.mjs` 也会检查这一点，并核对 `files` 里声明的每个文件是否
+真实存在、`exports` 指向的入口是否存在、运行时代码有没有 `console.log` 残留。
+
+### 在内置浏览器里实测
+
+凡是依赖真实渲染的行为，都在 DSH 侧边栏的内置浏览器里跑过一遍。做法是先
+`node scripts/verify-in-browser.mjs --serve` 起本地页面，再用 `browser_*` 工具驱动。
+
+结论（实测通过）：
+
+- **pointer 事件** —— 一次点击产生的序列是
+  `pointerover, pointerenter, pointerdown, mousedown, pointerup, mouseup, click`，
+  且每个事件恰好一次。只监听 `pointerdown` 的库（拖拽类、React 合成事件）也能收到。
+- **编辑键** —— Backspace 删一个字符、Shift+A 输入大写 A（不是 `+A`）、
+  Control+a 清空、Enter 在 textarea 里插入换行。
+- **contenteditable** —— `browser_type` 能写入，编辑键也能作用在可编辑 div 上。
+- **ref 生命周期** —— 连续多次 `browser_snapshot`，ref 数量稳定，不随快照次数增长。
+- **链接跳转** —— 点击 `<a>` 会真实导航，落点页面的标题与正文都变了。
+
+这几个行为里有三个曾经是真 bug：pointer 事件根本没派发、编辑键只发 keydown
+不改值、修饰键被模板字符串的反斜杠吞掉导致 `Control+a` 解析成 `+a`。
+
+### 开发脚本
+
+`scripts/` 下这几个只在开发和维护时用，发布产物里不含它们：
+
+| 脚本 | 用途 |
+| --- | --- |
+| `ensure-browser.mjs` | 起一个测试用的 Chrome，供需要真实页面的套件使用 |
+| `strip-bom.mjs` | 扫掉全仓库文本文件的 BOM（见上节，DSH 会因此拒绝安装） |
+| `verify-in-browser.mjs` | 生成内置浏览器实机验证用的页面，`--serve` 起本地服务，`--check` 自检 |
+| `audit-tools.mjs` | 核对「工具 → 方法 → 客户端处理器」这条链有没有断的 |
+| `audit-plugins.mjs` | 扫一遍本地 profile 里装了哪些插件、版本与兼容性 |
+| `wrap-client-iife.mjs` | 把客户端 bundle 包成 IIFE，避免与同页其他插件顶层声明撞名 |
+| `verify-isolation.mjs` | 验证包成 IIFE 后，与别的插件声明混在同一个 script 里仍能解析 |
+
+## 发布
+
+插件可以直接从 GitHub 或 npm 安装，不需要任何注册步骤。如果要被那些索引 GitHub 的社区
+插件市场收录，仓库带上 `dsh-plugin` topic 即可，它们会按自己的节奏重新扫描。
+
+## 更新记录
+
+### 0.4.0
+
+- 修复：把「文档里第一个右侧栏」当成当前对话的侧边栏，导致 agent 读到别的对话/别的标签页；
+  现在只认屏幕上那个对话的侧边栏，并按真正显示的标签取 guest。
+- 修复：切走对话后，属于旧对话的命令会被拒绝并说明原因，不再落到看不见的页面上。
+- 修复：`browser_status` / `browser_open_panel` 按当前对话判断面板，别的对话的面板不再算数。
+- 新增：标签页右键菜单补齐「关闭其他标签页 / 关闭全部标签页 / 关闭右侧所有标签页」。
+- 修复：`autoOpenPanel` 此前只声明未生效，现在关闭后命令不会自动打开面板。
+
+### 0.3.0
+
+- 冷启动自动打开侧边栏浏览器、会话绑定、标签页列表与截图导出。
+
+## 许可
+
+MIT