dsh-sidebar-browser-control 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +156 -2
- package/README.zh.md +141 -0
- package/client.js +783 -0
- package/cordis.patch.yml +12 -0
- package/icon.svg +7 -0
- package/index.js +561 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +70 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 XUFENGCHINA
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,157 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-sidebar-browser-control
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-sidebar-browser-control)
|
|
4
|
+
[](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/actions/workflows/ci.yml)
|
|
5
|
+
[](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/LICENSE)
|
|
6
|
+
[](#compatibility)
|
|
7
|
+
|
|
8
|
+
**Let the agent drive DSH's own built-in browser** — the Browser tab in the
|
|
9
|
+
right-hand Sidebar — instead of launching a second Chromium.
|
|
10
|
+
|
|
11
|
+
[中文说明 →](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/README.zh.md)
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
you › open the docs page in the built-in browser and tell me what the API section says
|
|
15
|
+
agent › browser_control { action: "open", url: "https://example.com/docs" }
|
|
16
|
+
browser_page { action: "text" }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Why not a CDP/Playwright plugin
|
|
20
|
+
|
|
21
|
+
There is already a DSH plugin that drives browsers over CDP
|
|
22
|
+
(`dsh-browser-control`). This one is the in-app counterpart, and the differences
|
|
23
|
+
are the point:
|
|
24
|
+
|
|
25
|
+
| | This plugin | CDP / Playwright wrapper |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| What it drives | the Browser tab DSH already ships | a separate browser process |
|
|
28
|
+
| Where you see it | in the Sidebar, next to your session | in another window |
|
|
29
|
+
| Extra runtime | none | a browser + driver |
|
|
30
|
+
| Logins | the workspace partition the tab already uses | whatever you set up |
|
|
31
|
+
| Reach | that tab only | any page, headless, screenshots |
|
|
32
|
+
|
|
33
|
+
Use this one when you want the agent to look at something *with* you, in the
|
|
34
|
+
place you are already working. Use a CDP wrapper when you need headless
|
|
35
|
+
automation, downloads or screenshots.
|
|
36
|
+
|
|
37
|
+
## What it can do
|
|
38
|
+
|
|
39
|
+
| Tool | Actions |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `browser_tabs` | list open built-in-browser tabs: id, live title, URL, owning session, panel state, whether page control is available |
|
|
42
|
+
| `browser_control` | `open` · `navigate` · `back` · `forward` · `reload` · `close` · `focus` · `expand` · `collapse` · `fullscreen` · `split` · `float` · `dock` · `external` |
|
|
43
|
+
| `browser_page` | `text` · `links` · `elements` · `eval` · `click` · `type` · `scroll` · `wait` *(Desktop only)* |
|
|
44
|
+
| `/browser` | `open <url>` · `tabs` · `back` · `forward` · `reload` · `close` · `focus` · `expand` · `collapse` · `fullscreen` · `split` · `float` · `dock` · `external` · `read` |
|
|
45
|
+
|
|
46
|
+
The tools and the slash command share one implementation, so `/browser open …`
|
|
47
|
+
costs no model round trip and behaves exactly like the tool.
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
The plugin is a normal DSH bundle, so any spec the plugin manager accepts works.
|
|
52
|
+
|
|
53
|
+
**From GitHub** (works before the first npm release). Ask the agent, no restart
|
|
54
|
+
needed:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
plugin_manager { action: install_bundle, target: "github:XUFENGCHINA/dsh-sidebar-browser-control" }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
or with the CLI:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
dsh plugin --profile desktop add github:XUFENGCHINA/dsh-sidebar-browser-control
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**From npm**, once published:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
plugin_manager { action: install_bundle, target: "dsh-sidebar-browser-control" }
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**From a checkout**, for development:
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
dsh plugin --profile desktop add link:/abs/path/to/checkout
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Remove it with `plugin_manager { action: "remove_bundle", target: "dsh-sidebar-browser-control" }`.
|
|
79
|
+
|
|
80
|
+
After editing `client.js` in a checkout, ask the Host to re-scan the bundle
|
|
81
|
+
(`set_bundle` off, then on) — the client artifact is served from a snapshot.
|
|
82
|
+
|
|
83
|
+
## Use
|
|
84
|
+
|
|
85
|
+
Just ask, in any session whose Sidebar is on screen:
|
|
86
|
+
|
|
87
|
+
- "open `https://news.ycombinator.com` in the built-in browser and summarise the top 5"
|
|
88
|
+
- "in the built-in browser, click the *Sign in* link and tell me what the form asks for"
|
|
89
|
+
- "search Bing in the built-in browser for DeepSeek Harness and give me the first three results"
|
|
90
|
+
- `/browser open https://example.com` — straight from the composer, no model call
|
|
91
|
+
|
|
92
|
+
## How it works
|
|
93
|
+
|
|
94
|
+
The browser lives in the Web renderer, tools live in the Host, and DSH exposes no
|
|
95
|
+
supported Host → Client call to third-party plugins. So the plugin is two halves
|
|
96
|
+
joined by four loopback routes (a long-poll carries Host → Client commands, with
|
|
97
|
+
no timer in either direction), and all layout/navigation goes through
|
|
98
|
+
`ctx.sidebarRight` so the shipped address bar, history and restore logic stay
|
|
99
|
+
authoritative.
|
|
100
|
+
|
|
101
|
+
Full protocol, design decisions and the DSH internals it depends on:
|
|
102
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md).
|
|
103
|
+
|
|
104
|
+
## Security
|
|
105
|
+
|
|
106
|
+
`browser_page eval` runs arbitrary JavaScript inside the browser tab, with that
|
|
107
|
+
page's cookies — if you are logged in there, the agent can act as you in that
|
|
108
|
+
tab. Tool calls are logged with their arguments, but treat these tools like
|
|
109
|
+
letting someone read your screen. The four routes admit only the DSH application
|
|
110
|
+
origin (no cross-site CSRF) and only this plugin's own tools can enqueue a
|
|
111
|
+
command. Details:
|
|
112
|
+
[SECURITY.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/SECURITY.md).
|
|
113
|
+
|
|
114
|
+
## Compatibility
|
|
115
|
+
|
|
116
|
+
Verified end to end on **DSH Desktop 0.2.0-rc.2 / Electron 44 / Windows x64**:
|
|
117
|
+
list, open, navigate, back/forward/reload, read text, `eval`, list elements,
|
|
118
|
+
click, type + submit, float/dock, close, expand/collapse. The Web profile gets
|
|
119
|
+
tab and layout control (its sandboxed iframe cannot be read).
|
|
120
|
+
|
|
121
|
+
The plugin talks to public services (`ctx.sidebarRight`, `ctx.webServer`,
|
|
122
|
+
`ctx.tools`, `ctx.commands`) plus a few DOM markers owned by the shipped Sidebar
|
|
123
|
+
packages. If a marker changes, page-level actions fail with an explicit message
|
|
124
|
+
while tab and layout control keep working; the table of those dependencies is in
|
|
125
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md#dsh-internals-this-plugin-depends-on).
|
|
126
|
+
|
|
127
|
+
## Known limitations
|
|
128
|
+
|
|
129
|
+
- **No screenshots.** `webview.capturePage()` natively crashed the Electron
|
|
130
|
+
renderer on the verified deployment, so the capability is removed and the call
|
|
131
|
+
refuses with the reason. Evidence and survivable alternatives:
|
|
132
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md#why-there-is-no-screenshot).
|
|
133
|
+
- Page-level actions are **Desktop only**.
|
|
134
|
+
- Tab ids are unique per session; an ambiguous id is reported and accepted as
|
|
135
|
+
`<sessionId>#<tabId>`.
|
|
136
|
+
- Actions are selector-based — no coordinate clicks, uploads or downloads — and
|
|
137
|
+
they target the session currently on screen (`ctx.sidebarRight` semantics).
|
|
138
|
+
|
|
139
|
+
## Development
|
|
140
|
+
|
|
141
|
+
No build step and no dependencies: `client.js` is the shipped artifact, written
|
|
142
|
+
by hand in the loader's classic-script format.
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
npm test # offline protocol test: stub context + real HTTP + a fake client half
|
|
146
|
+
npm run verify # syntax + protocol test + packaged-tarball check
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`npm test` needs no DSH running, so it works in CI and on a clean checkout.
|
|
150
|
+
Guidelines and the list of invariants that keep this plugin loadable:
|
|
151
|
+
[CONTRIBUTING.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/CONTRIBUTING.md).
|
|
152
|
+
Releasing:
|
|
153
|
+
[RELEASING.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/RELEASING.md).
|
|
154
|
+
|
|
155
|
+
## License
|
|
156
|
+
|
|
157
|
+
[MIT](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/LICENSE)
|
package/README.zh.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# dsh-sidebar-browser-control
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-sidebar-browser-control)
|
|
4
|
+
[](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/actions/workflows/ci.yml)
|
|
5
|
+
[](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/LICENSE)
|
|
6
|
+
[](#兼容性)
|
|
7
|
+
|
|
8
|
+
**让 Agent 直接驱动 DSH 自带的内置浏览器**（右侧栏的「浏览器」tab），而不是再开一个 Chromium。
|
|
9
|
+
|
|
10
|
+
[English →](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/README.md)
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
你 › 在内置浏览器里打开文档页，告诉我 API 那一节讲了什么
|
|
14
|
+
AI › browser_control { action: "open", url: "https://example.com/docs" }
|
|
15
|
+
browser_page { action: "text" }
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 为什么不用 CDP / Playwright 方案
|
|
19
|
+
|
|
20
|
+
npm 上已有一个走 CDP 的 DSH 浏览器插件（`dsh-browser-control`）。本插件是它的**应用内对照物**，
|
|
21
|
+
差别就是价值所在：
|
|
22
|
+
|
|
23
|
+
| | 本插件 | CDP / Playwright 封装 |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| 驱动对象 | DSH 已经自带的那只浏览器 tab | 另起的浏览器进程 |
|
|
26
|
+
| 你在哪看到 | 右侧栏，就在会话旁边 | 另一个窗口 |
|
|
27
|
+
| 额外运行时 | 无 | 浏览器 + driver |
|
|
28
|
+
| 登录态 | 该 tab 已在用的工作区分区 | 你自己另外配 |
|
|
29
|
+
| 能力边界 | 只有这个 tab | 任意页面、无头、截图 |
|
|
30
|
+
|
|
31
|
+
想和 AI **一起看着同一个页面**做事，用这个；要无头自动化、下载、截图，用 CDP 方案。
|
|
32
|
+
|
|
33
|
+
## 能做什么
|
|
34
|
+
|
|
35
|
+
| 工具 | 动作 |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `browser_tabs` | 列出内置浏览器已打开的标签：id、实时标题、URL、所属会话、面板状态、是否支持页面级控制 |
|
|
38
|
+
| `browser_control` | `open` · `navigate` · `back` · `forward` · `reload` · `close` · `focus` · `expand` · `collapse` · `fullscreen` · `split` · `float` · `dock` · `external` |
|
|
39
|
+
| `browser_page` | `text` · `links` · `elements` · `eval` · `click` · `type` · `scroll` · `wait`（**仅 Desktop**） |
|
|
40
|
+
| `/browser` | `open <url>` · `tabs` · `back` · `forward` · `reload` · `close` · `focus` · `expand` · `collapse` · `fullscreen` · `split` · `float` · `dock` · `external` · `read` |
|
|
41
|
+
|
|
42
|
+
工具和斜杠命令**共用同一份实现**，所以 `/browser open …` 不花模型轮次，行为与工具完全一致。
|
|
43
|
+
|
|
44
|
+
## 安装
|
|
45
|
+
|
|
46
|
+
它就是一个普通 DSH bundle，plugin manager 接受的任何 spec 都能用。
|
|
47
|
+
|
|
48
|
+
**从 GitHub 安装**（还没发 npm 时用这个）。让 Agent 装，无需重启：
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
plugin_manager { action: install_bundle, target: "github:XUFENGCHINA/dsh-sidebar-browser-control" }
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
或用 CLI：
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
dsh plugin --profile desktop add github:XUFENGCHINA/dsh-sidebar-browser-control
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**从 npm 安装**（发布之后）：
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
plugin_manager { action: install_bundle, target: "dsh-sidebar-browser-control" }
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**从本地 checkout 安装**（开发用）：
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
dsh plugin --profile desktop add link:/绝对路径/到/本仓库
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
卸载：`plugin_manager { action: "remove_bundle", target: "dsh-sidebar-browser-control" }`。
|
|
73
|
+
|
|
74
|
+
本地开发时改完 `client.js` 要请 Host 重新扫描 bundle（`set_bundle` 关一次再开一次）——
|
|
75
|
+
客户端产物是按快照提供的，光改文件不会生效。
|
|
76
|
+
|
|
77
|
+
## 用法
|
|
78
|
+
|
|
79
|
+
直接说就行（右侧栏要有屏幕上的会话）：
|
|
80
|
+
|
|
81
|
+
- 「在内置浏览器打开 `https://news.ycombinator.com`，总结前 5 条」
|
|
82
|
+
- 「在内置浏览器里点 *Sign in*，告诉我表单要填什么」
|
|
83
|
+
- 「在内置浏览器用 Bing 搜 DeepSeek Harness，给我前三条结果」
|
|
84
|
+
- `/browser open https://example.com` —— 输入框直接敲，不经过模型
|
|
85
|
+
|
|
86
|
+
## 工作原理
|
|
87
|
+
|
|
88
|
+
浏览器活在 Web 渲染进程里，工具活在 Host 进程里，而 DSH 没有面向第三方插件的
|
|
89
|
+
Host → Client 调用。于是插件拆成两半，用 4 条回环路由相连（Host → Client 走**长轮询**，
|
|
90
|
+
两个方向都没有定时轮询）；导航与布局全部走公开的 `ctx.sidebarRight`，
|
|
91
|
+
所以内置地址栏、历史、重启恢复逻辑始终是权威。
|
|
92
|
+
|
|
93
|
+
完整协议、设计取舍、以及它依赖的 DSH 内部细节见
|
|
94
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md)。
|
|
95
|
+
|
|
96
|
+
## 安全
|
|
97
|
+
|
|
98
|
+
`browser_page eval` 会在该 tab 的页面里执行任意 JavaScript，并带着那个页面的 Cookie——
|
|
99
|
+
你在里面登录过什么，Agent 就能以你的身份在那个 tab 里做什么。工具调用会连同参数进会话日志，
|
|
100
|
+
但请把这三个工具当作「允许对方看你的屏幕」来对待。4 条路由只放行 DSH 自身来源（跨站 CSRF 打不进来），
|
|
101
|
+
且只有本插件自己的工具能下发命令。细节见
|
|
102
|
+
[SECURITY.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/SECURITY.md)。
|
|
103
|
+
|
|
104
|
+
## 兼容性
|
|
105
|
+
|
|
106
|
+
已在 **DSH Desktop 0.2.0-rc.2 / Electron 44 / Windows x64** 上端到端实测：
|
|
107
|
+
列出、打开、导航、前进后退、刷新、读取正文、`eval`、列出元素、点击、输入并提交、
|
|
108
|
+
浮窗/停靠、关闭、展开/收起。Web profile 只能做标签与布局控制（sandbox iframe 读不到页面内容）。
|
|
109
|
+
|
|
110
|
+
插件只依赖公开服务（`ctx.sidebarRight`、`ctx.webServer`、`ctx.tools`、`ctx.commands`）
|
|
111
|
+
以及若干由随包 Sidebar 拥有的 DOM 标记。标记一旦变化，页面级动作会**明确报错**，
|
|
112
|
+
而标签与布局控制照常可用；依赖清单见
|
|
113
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md#dsh-internals-this-plugin-depends-on)。
|
|
114
|
+
|
|
115
|
+
## 已知限制
|
|
116
|
+
|
|
117
|
+
- **没有截图。** `webview.capturePage()` 在实测环境下让 Electron 渲染进程**原生崩溃**，
|
|
118
|
+
因此该能力被移除，调用会明确拒绝并说明原因。证据与可行替代方案见
|
|
119
|
+
[docs/architecture.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/docs/architecture.md#why-there-is-no-screenshot)。
|
|
120
|
+
- 页面级操作**仅 Desktop**。
|
|
121
|
+
- tab id 只在会话内唯一；重名时以 `<会话id>#<tabN>` 形式给出并接受。
|
|
122
|
+
- 动作为选择器式（无坐标点击、上传、下载），且作用于**屏幕上显示的会话**（`ctx.sidebarRight` 的语义）。
|
|
123
|
+
|
|
124
|
+
## 开发
|
|
125
|
+
|
|
126
|
+
无构建步骤、无依赖：`client.js` 就是交付产物，按 loader 的 classic-script 格式手写。
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
npm test # 离线协议测试：stub context + 真实 HTTP + 假 Client 半
|
|
130
|
+
npm run verify # 语法 + 协议测试 + 打包产物自足性检查
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`npm test` 不需要运行中的 DSH，因此在 CI 和全新 checkout 上都能跑。
|
|
134
|
+
规范与「保证可加载」的几条硬约束见
|
|
135
|
+
[CONTRIBUTING.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/CONTRIBUTING.md)，
|
|
136
|
+
发布流程见
|
|
137
|
+
[RELEASING.md](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/RELEASING.md)。
|
|
138
|
+
|
|
139
|
+
## 许可
|
|
140
|
+
|
|
141
|
+
[MIT](https://github.com/XUFENGCHINA/dsh-sidebar-browser-control/blob/main/LICENSE)
|