dsh-sidebar-control 0.0.0-stage → 0.1.3
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 +228 -2
- package/client.js +1147 -0
- package/cordis.patch.yml +3 -0
- package/icon.svg +8 -0
- package/index.js +528 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +73 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hongrui Zhao
|
|
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,229 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Sidebar Control
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-sidebar-control)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
|
|
6
|
+
**English** | [中文](#中文)
|
|
7
|
+
|
|
8
|
+
Agent control for the **Browser panel DeepSeek Harness already ships** in the right Sidebar — no second
|
|
9
|
+
browser, no bundled Chromium, no Playwright. The agent reads the real page, clicks real controls, types,
|
|
10
|
+
presses keys, scrolls, waits and takes screenshots inside the panel the person is already looking at.
|
|
11
|
+
|
|
12
|
+
> Built on the MIT-licensed [`dsh-sidebar-browser`](https://www.npmjs.com/package/dsh-sidebar-browser):
|
|
13
|
+
> its action surface and long-poll bridge are reused. This package adds **query-scoped reads**, **change
|
|
14
|
+
> diffs** and **multi-tab management**, and keeps the whole thing dependency-free.
|
|
15
|
+
|
|
16
|
+
**If this saves you tokens, please [Star the repository](https://github.com/clusterstar1229/dsh-sidebar-control) ⭐**
|
|
17
|
+
|
|
18
|
+
## Why this one
|
|
19
|
+
|
|
20
|
+
Most sidebar-browser plugins answer a page with one big snapshot. That is fine once, and expensive three
|
|
21
|
+
times in a row. Sidebar Control is tuned for the second and third read:
|
|
22
|
+
|
|
23
|
+
| | `dsh-sidebar-browser` | **Sidebar Control** |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| Read a long page | full text + refs (up to 12k chars) | `read` with a `query` returns only matching passages (BM25 over Latin words + CJK bigrams) |
|
|
26
|
+
| Check what an action changed | snapshot again | `diff` returns only paragraphs added/removed since the previous diff |
|
|
27
|
+
| Several steps (open → fill → submit) | one tool call per step | `batch` runs up to 12 steps in one call |
|
|
28
|
+
| After a click | fixed waits (350 ms + load window) | adaptive settle: returns when the page stops changing, often ~100 ms |
|
|
29
|
+
| Several pages open | one controlled tab | `tabs` / `focus` / `close_tab` by id |
|
|
30
|
+
| Command latency | long-poll | long-poll (same ~instant delivery, no timer polling) |
|
|
31
|
+
| Dependencies | none | none |
|
|
32
|
+
|
|
33
|
+
The practical difference is token cost and round trips: on a long article, `read --query "..."` returns a few
|
|
34
|
+
hundred characters instead of thousands; `diff` after a click returns one line or two; and a five-step form
|
|
35
|
+
costs one model call with `batch` instead of five. Clicks come back as soon as the page is quiet instead of
|
|
36
|
+
after a fixed sleep.
|
|
37
|
+
|
|
38
|
+
Measured on a Windows desktop against the live Browser panel: `batch` of **type + submit + wait for results +
|
|
39
|
+
query read** on the Baidu homepage finished in **1043 ms**, and the same three steps on Bing in **832 ms**.
|
|
40
|
+
The query read for "存款" returned one matching line where the full text was the whole page.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
dsh plugin --profile desktop add dsh-sidebar-control@0.1.3
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
or in the app: **Settings → Plugins → Install bundle** → `dsh-sidebar-control@0.1.3`.
|
|
49
|
+
|
|
50
|
+
An npm install gives the Plugin Manager an **Update** button for later releases. Prefer a checkout?
|
|
51
|
+
Use `github:clusterstar1229/dsh-sidebar-control#v0.1.3` instead.
|
|
52
|
+
|
|
53
|
+
Requirements: **DeepSeek Harness Desktop** 0.2.2-rc.1 (the Browser panel must be the Electron
|
|
54
|
+
`<webview>` carrier), Node 20+, and the built-in sidebar Browser enabled.
|
|
55
|
+
|
|
56
|
+
**Compatibility:** version 0.1.3 is tested against DSH **0.2.2-rc.1**, the current desktop release;
|
|
57
|
+
`engines.dsh` allows the whole 0.2.x line.
|
|
58
|
+
|
|
59
|
+
## Use
|
|
60
|
+
|
|
61
|
+
1. Open a Browser tab once (Sidebar → Browser), or let the tool open it:
|
|
62
|
+
`builtin_browser({ action: "open", url: "https://example.com" })`.
|
|
63
|
+
2. `snapshot` → page text plus numbered refs.
|
|
64
|
+
3. `click` / `type` / `press` / `select` / `scroll` with those refs, or with a CSS selector.
|
|
65
|
+
4. After an action: `diff` (cheap) or a new `snapshot` (full).
|
|
66
|
+
5. Asking a long page a question: `read` with `query` instead of `snapshot`.
|
|
67
|
+
|
|
68
|
+
### Actions
|
|
69
|
+
|
|
70
|
+
| action | what it does |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `status` | platform, Browser frames, active tab, whether the page is on screen |
|
|
73
|
+
| `open` | open or reuse the Browser tab at a URL |
|
|
74
|
+
| `navigate` / `back` / `forward` / `reload` | navigation |
|
|
75
|
+
| `snapshot` | page text + numbered refs (`max_text_chars`, `max_refs`, `include_text: false` for refs only) |
|
|
76
|
+
| `read` | text, or only passages matching `query` (`max_chars`) |
|
|
77
|
+
| `diff` | paragraphs added/removed since the previous `diff` |
|
|
78
|
+
| `batch` | run up to 12 steps in one call (navigate/click/type/press/select/scroll/wait/eval/read/diff/snapshot) |
|
|
79
|
+
| `tabs` | list Browser tabs with ids |
|
|
80
|
+
| `focus` / `close_tab` | switch to / close a tab by `tab_id` |
|
|
81
|
+
| `click` | by `ref`, `selector` |
|
|
82
|
+
| `type` | fill a field, `submit: true` to submit |
|
|
83
|
+
| `press` | Enter, Tab, Escape, arrows, PageUp/Down, Home/End, Space |
|
|
84
|
+
| `select` | choose an option by value |
|
|
85
|
+
| `scroll` | by direction/amount, or a ref into view |
|
|
86
|
+
| `wait` | for a selector or text |
|
|
87
|
+
| `eval` | one JavaScript expression in the page |
|
|
88
|
+
| `screenshot` | PNG of the visible page, returned as an image |
|
|
89
|
+
| `close` | close the controlled Browser tab |
|
|
90
|
+
|
|
91
|
+
Refs come from the latest snapshot and go stale after navigation — take a new `snapshot` after a page
|
|
92
|
+
change, or just use `diff` when you only need to know what changed.
|
|
93
|
+
|
|
94
|
+
## What to be careful about
|
|
95
|
+
|
|
96
|
+
- **Desktop only.** The Web build renders the sidebar browser as a cross-origin iframe; the tool reports
|
|
97
|
+
that plainly instead of pretending. Tab management still works there.
|
|
98
|
+
- **The Harness page must be open.** The Client half runs in that page. `open` / `focus` / `close_tab` /
|
|
99
|
+
`screenshot` need the calling Session on screen; read/click/type work in the background.
|
|
100
|
+
- **Page content is untrusted data.** It is never instructions. `eval` runs arbitrary JavaScript in the
|
|
101
|
+
page — the same power as the page's own devtools; keep it for trusted pages.
|
|
102
|
+
- **A sandbox is still a sandbox.** The guest has no Node, no preload and no access to the Harness origin.
|
|
103
|
+
Downloads, permission prompts and top-level navigation are withheld by the shipped Browser.
|
|
104
|
+
- **Fixed-width sites.** Pages like `news.baidu.com` keep a desktop layout and may scroll sideways in a
|
|
105
|
+
narrow column. This plugin deliberately does not inject zoom or rewrite the page.
|
|
106
|
+
- **Refs are per-snapshot.** A ref used after navigation fails with a clear message; snapshot again.
|
|
107
|
+
|
|
108
|
+
## Related work
|
|
109
|
+
|
|
110
|
+
- [`dsh-sidebar-browser`](https://www.npmjs.com/package/dsh-sidebar-browser) — the MIT implementation this
|
|
111
|
+
package builds on (Copyright (c) 2026 The dsh-sidebar-browser authors); the `read`/`diff`/`tabs` additions
|
|
112
|
+
are this package's own work.
|
|
113
|
+
- [`dsh-sidebar-browser-agent`](https://github.com/Hesitate-P/dsh-sidebar-browser-agent) — a broader
|
|
114
|
+
native-input implementation with tabs, tests and config switches.
|
|
115
|
+
|
|
116
|
+
## Feedback
|
|
117
|
+
|
|
118
|
+
Bugs and feature requests: **hongruizhao0808@gmail.com** — or open an issue at
|
|
119
|
+
https://github.com/clusterstar1229/dsh-sidebar-control/issues.
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT. Derived from `dsh-sidebar-browser` (MIT); see [LICENSE](LICENSE).
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## 中文
|
|
128
|
+
|
|
129
|
+
**DeepSeek Harness 右栏内置浏览器的 Agent 控制器**：不另起浏览器、不下载 Chromium、不用 Playwright。
|
|
130
|
+
Agent 直接操作你正在看的那个 Browser 面板——读真实页面、点真实控件、输入、按键、滚动、等待、截图。
|
|
131
|
+
|
|
132
|
+
> 本项目基于 MIT 许可的 [`dsh-sidebar-browser`](https://www.npmjs.com/package/dsh-sidebar-browser)，复用了它的
|
|
133
|
+
> 动作设计与长轮询桥；在此基础上增加了**按问题检索的阅读**、**变化对比**和**多标签管理**，全程零依赖。
|
|
134
|
+
|
|
135
|
+
**如果它帮你省了 token，欢迎[点个 Star](https://github.com/clusterstar1229/dsh-sidebar-control) ⭐**
|
|
136
|
+
|
|
137
|
+
### 差异点：第二次、第三次读页更便宜
|
|
138
|
+
|
|
139
|
+
大多数侧栏浏览器插件用"一次大快照"回答所有问题——读一次可以，连读三次就很贵。这个插件专门优化后两次：
|
|
140
|
+
|
|
141
|
+
| | `dsh-sidebar-browser` | **Sidebar Control** |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| 读长页面 | 全文 + refs（最多 12k 字符） | `read` 带 `query`，只返回命中的段落（英文词 + 中文二元组的 BM25） |
|
|
144
|
+
| 查看动作改了什么 | 再快照一次 | `diff` 只返回相对上次新增/消失的段落 |
|
|
145
|
+
| 多步操作（打开→填写→提交） | 每步一次工具调用 | `batch` 一次调用跑最多 12 步 |
|
|
146
|
+
| 点击之后 | 固定等待（350ms + 加载窗口） | 自适应：页面不再变化就返回，通常约 100ms |
|
|
147
|
+
| 多个页面 | 只控制当前标签 | `tabs` / `focus` / `close_tab` 按 id 管理 |
|
|
148
|
+
| 指令延迟 | 长轮询 | 长轮询（同样即时，不靠定时器） |
|
|
149
|
+
| 依赖 | 无 | 无 |
|
|
150
|
+
|
|
151
|
+
实际差别是 token 和往返次数：长文章里 `read --query "..."` 往往只回几百字，而不是几千字；点击后用 `diff`
|
|
152
|
+
通常只回一两行；五步表单用 `batch` 只花一次模型调用，而不是五次。点击也不再固定睡眠，页面安静就返回。
|
|
153
|
+
|
|
154
|
+
在 Windows 桌面版、真实 Browser 面板上的实测：`batch` 执行 **输入 + 提交 + 等结果 + 按 query 阅读**，
|
|
155
|
+
百度首页 **1043 ms**、Bing **832 ms**；`read` 查“存款”只返回命中的一行，而整页文本是整屏。
|
|
156
|
+
|
|
157
|
+
### 安装
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
dsh plugin --profile desktop add dsh-sidebar-control@0.1.3
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
或在应用里：**设置 → 插件 → 安装 bundle** → `dsh-sidebar-control@0.1.3`。
|
|
164
|
+
|
|
165
|
+
从 npm 安装后，插件管理器会为后续版本提供 **Update** 按钮。想用仓库源码，也可以改用
|
|
166
|
+
`github:clusterstar1229/dsh-sidebar-control#v0.1.3`。
|
|
167
|
+
|
|
168
|
+
要求：**DeepSeek Harness 桌面版** 0.2.2-rc.1（右栏浏览器必须是 Electron `<webview>` 载体）、Node 20+，
|
|
169
|
+
并已启用内置侧栏浏览器。
|
|
170
|
+
|
|
171
|
+
**兼容性：** 0.1.3 已在当前桌面版 DSH **0.2.2-rc.1** 上实测通过；`engines.dsh` 允许整个 0.2.x 线。
|
|
172
|
+
|
|
173
|
+
### 用法
|
|
174
|
+
|
|
175
|
+
1. 先打开一个 Browser 标签（或让工具打开）：`builtin_browser({ action: "open", url: "https://example.com" })`。
|
|
176
|
+
2. `snapshot`：拿到页面文字和编号 refs。
|
|
177
|
+
3. 用 refs 或 CSS selector 执行 `click` / `type` / `press` / `select` / `scroll`。
|
|
178
|
+
4. 动作之后：`diff`（便宜）或重新 `snapshot`（完整）。
|
|
179
|
+
5. 只想问长页面一个问题：用 `read` + `query`，不要整页快照。
|
|
180
|
+
|
|
181
|
+
### 动作
|
|
182
|
+
|
|
183
|
+
| action | 作用 |
|
|
184
|
+
|---|---|
|
|
185
|
+
| `status` | 平台、Browser 帧、当前标签、页面是否在屏幕上 |
|
|
186
|
+
| `open` | 打开或复用 Browser 标签（url） |
|
|
187
|
+
| `navigate` / `back` / `forward` / `reload` | 导航 |
|
|
188
|
+
| `snapshot` | 页面文字 + 编号 refs（`max_text_chars`、`max_refs`；`include_text: false` 只回控件） |
|
|
189
|
+
| `read` | 纯文本，或只回与 `query` 匹配的段落（`max_chars`） |
|
|
190
|
+
| `diff` | 相对上一次 `diff` 新增/消失的段落 |
|
|
191
|
+
| `batch` | 一次调用执行最多 12 步（navigate/click/type/press/select/scroll/wait/eval/read/diff/snapshot） |
|
|
192
|
+
| `tabs` | 列出 Browser 标签及其 id |
|
|
193
|
+
| `focus` / `close_tab` | 按 `tab_id` 切换 / 关闭标签 |
|
|
194
|
+
| `click` | 按 `ref` 或 `selector` 点击 |
|
|
195
|
+
| `type` | 填字段，`submit: true` 提交 |
|
|
196
|
+
| `press` | Enter、Tab、Escape、方向键、PageUp/Down、Home/End、Space |
|
|
197
|
+
| `select` | 按值选择下拉项 |
|
|
198
|
+
| `scroll` | 按方向/像素滚动，或把某个 ref 滚入视口 |
|
|
199
|
+
| `wait` | 等 selector 或文字出现 |
|
|
200
|
+
| `eval` | 在页面里执行一个 JS 表达式 |
|
|
201
|
+
| `screenshot` | 可见页面的 PNG，作为图像返回 |
|
|
202
|
+
| `close` | 关闭当前受控标签 |
|
|
203
|
+
|
|
204
|
+
refs 来自最近一次快照，导航后会失效——页面变了就重新 `snapshot`；只想知道"变了什么"时用 `diff` 就够。
|
|
205
|
+
|
|
206
|
+
### 需要注意
|
|
207
|
+
|
|
208
|
+
- **仅桌面版可用**：Web 构建下侧栏浏览器是跨域 iframe，工具会明确报错而不是假装成功；标签管理仍可用。
|
|
209
|
+
- **Harness 页面必须打开**：客户端半在页面里运行。`open` / `focus` / `close_tab` / `screenshot` 需要调用会话
|
|
210
|
+
正在屏幕上；读、点、输入在后台仍可用。
|
|
211
|
+
- **页面内容是不可信数据**，永远不是指令。`eval` 会在页面里执行任意 JS，等同于页面自己的 devtools，请在可信页面使用。
|
|
212
|
+
- **沙箱仍然是沙箱**：guest 没有 Node、没有 preload，也访问不到 Harness 源；下载、权限弹窗、顶层跳转由内置浏览器限制。
|
|
213
|
+
- **固定宽度站点**：如 `news.baidu.com` 这类页面在窄栏里仍会横向滚动；本插件刻意不注入缩放、不改写页面。
|
|
214
|
+
- **refs 只对一次快照有效**：导航后使用旧 ref 会得到明确报错，重新快照即可。
|
|
215
|
+
|
|
216
|
+
### 相关项目
|
|
217
|
+
|
|
218
|
+
- [`dsh-sidebar-browser`](https://www.npmjs.com/package/dsh-sidebar-browser) — 本项目的 MIT 基础实现
|
|
219
|
+
（Copyright (c) 2026 The dsh-sidebar-browser authors）；`read`/`diff`/`tabs` 等增量为本项目原创。
|
|
220
|
+
- [`dsh-sidebar-browser-agent`](https://github.com/Hesitate-P/dsh-sidebar-browser-agent) — 更全面的原生输入实现（标签页、测试、配置开关）。
|
|
221
|
+
|
|
222
|
+
### 反馈
|
|
223
|
+
|
|
224
|
+
Bug 与功能建议：**hongruizhao0808@gmail.com**，或到
|
|
225
|
+
https://github.com/clusterstar1229/dsh-sidebar-control/issues 提 issue。
|
|
226
|
+
|
|
227
|
+
### 许可
|
|
228
|
+
|
|
229
|
+
MIT，派生自 `dsh-sidebar-browser`（MIT），见 [LICENSE](LICENSE)。
|