dsh-inner-browser-use 0.0.0-stage → 0.11.44

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 regrevia
+
+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.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# dsh-inner-browser-use
 
-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.
+**Lets an agent drive the built-in sidebar browser of DeepSeek Harness — the one already in the right panel, not a new window.**
+
+The agent navigates, reads the page as numbered controls, clicks, types, and runs JavaScript. You watch it happen: a pointer moves to each target and ripples where it lands. Everything runs inside the `<webview>` the product already leases, with the same partition and the same cookies, so a page you signed into by hand is the page the agent works on.
+
+> **On the name:** *inner* means the browser built into the Harness sidebar. This plugin opens no window of its own and never attaches to Chrome.
+
+## What you get
+
+| Tool | What it does |
+| --- | --- |
+| `browser_navigate` | Opens a URL in this chat's built-in browser and returns the page. |
+| `browser_view` | Returns the address, title, visible text, and every control as `#1 … #80`. |
+| `browser_click` | Clicks one numbered control and returns the page it leads to. |
+| `browser_type` | Types into one numbered field, optionally pressing Enter. |
+| `browser_script` | Evaluates JavaScript and returns the last expression. |
+| `browser_selection` | Returns the text currently selected in the page. |
+| `browser_copy` | Copies the selection, or one control's text, to the clipboard. |
+| `browser_screenshot` | Saves a PNG of the tab and returns its path. |
+| `browser_download` | Saves a file the page offers into this chat's project folder. A file the page starts saving on its own lands there too, and the call that caused it reports the path. |
+| `browser_upload` | Attaches a local file to a numbered file field. |
+
+Every call is visible: the pointer travels to the control, a ring marks it, and the page scrolls the target into view first.
+
+The first call opens the tab for you: the page half hears that a chat needs one and opens **内置浏览器** in the right sidebar. That tab is the product's own — same tab kind, same address bar, same partition — and this plugin adds nothing to the guide pane. A tab you opened by hand is the tab the agent drives.
+
+## Where files land
+
+The tab reports the folder its chat works in when it connects, and everything this plugin writes goes under one
+folder of that working directory:
+
+```
+.dsh-inner-browser-use/
+  .gitignore     keeps the folder out of your project's own version control
+  screenshots/   PNGs from browser_screenshot
+  downloads/     files the page offered to browser_download
+```
+
+## Install
+
+```bash
+git clone https://github.com/regrevia/dsh-inner-browser-use
+```
+
+Then in DeepSeek Harness: **Plugins → Install from folder**, and pick the clone. Or from a shell:
+
+```bash
+dsh plugin install /path/to/dsh-inner-browser-use
+```
+
+Or install the packed release, no clone and no npm account:
+
+```bash
+dsh plugin install https://github.com/regrevia/dsh-inner-browser-use/releases/download/v0.11.40/dsh-inner-browser-use-0.11.40.tgz
+```
+
+The plugin appears under **Plugins** as *内置浏览器*. It needs the Desktop app, because the sidebar browser is a Desktop capability.
+
+## Use
+
+1. Open the chat you want the agent to browse for.
+2. Ask the agent for something on a page: *"打开 example.com，告诉我标题"*. The first call opens the built-in browser in the right panel; pressing **+ → 内置浏览器** yourself lands on the same tab.
+
+The tab is per chat: each chat has its own in the same built-in browser. A call for a chat that never opened one opens it there.
+
+## Drag data both ways
+
+- **Page → chat:** `browser_script` returns strings and `browser_screenshot` saves a PNG, so the agent can read what the page shows and quote it — or hand you the image path — in the conversation.
+- **Chat → page:** `browser_type` puts text into a field; `browser_script` can set values the page cannot be typed into.
+- **Page → chat, by hand:** select text on the page and a **Drag to chat** handle appears in the tab's
+  status row. Drag it into the conversation to carry that text with you. After the agent downloads something
+  for this chat, the same handle carries that file, so a page's picture or PDF can be dropped into the chat
+  as an attachment without leaving the app. The agent gets the same content through `browser_selection`,
+  `browser_copy` and `browser_download`.
+
+## What it will not do
+
+- **It does not create a second browser.** No new window, no Chrome profile, no CDP mirror.
+- **A sign-in outlives a restart only when the page can read its cookie.** The guest partition lives in memory; the cookies this page can see are kept per workspace in `~/.dsh/inner-browser-use/cookies/` and written back when that workspace's pane opens again. A login held only in an `HttpOnly` cookie needs the password again.
+- **Screenshots are viewport-sized.** A `<webview>` captures what is visible, not the whole scroll height; scroll first, then capture.
+- **One partition per workspace.** Two chats in the same workspace share the browser's storage, exactly as two tabs of the built-in browser do.
+- **No popups or permission prompts.** A link that wants a new window stays in the tab it is in. A file the page
+  offers comes out through `browser_download`, which saves it into this chat's project folder and hands the path
+  back to the conversation. A file the page starts saving by itself needs no call: it lands in the same folder,
+  and the call that pressed the link reports where it went.
+- **It opens the tab only when a call needs it.** A call for the chat you are reading may open the right
+  panel; a call for any other chat gets a page out of sight instead, so the panel stays as you arranged it.
+  At most three such pages are kept, and the oldest goes first.
+- **A capture of a chat you are not looking at.** Reading, clicking and typing work on a tab that chat already
+  had, because they drive the page itself; a tab is opened only for the chat on screen. Pixels come from a surface the app is drawing, and a view
+  behind another tab of the same pane is not drawn: the capture tries to bring this chat's tab forward, and if the
+  page still has no surface it says so in a couple of seconds instead of waiting. Read what you need from the page
+  instead — `browser_script` returns the same content.
+
+## Compatibility
+
+| | |
+| --- | --- |
+| Harness | Desktop app, sidebar browser present |
+| Tab kind | `browser` — the built-in browser's own kind |
+| Host | Node 20+ |
+| License | MIT |
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the wire and [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for version limits.
+
+## Develop
+
+```bash
+node --test test/*.test.mjs
+```
+
+The host half is plain ESM with no dependencies; the client half is a dynamic client module with no build step. Both are loaded by the app as-is.
+
+- **The page comes back on its own.** The pane is rebuilt from time to time; when that leaves the view blank, the
+  next tool call reopens the page that chat was last told to open, so a run is not interrupted by it.
+
+## License
+
+MIT © regrevia

package/README.zh.md

@@ -0,0 +1,91 @@
+# dsh-inner-browser-use
+
+**让 agent 直接操作 DeepSeek Harness 右侧栏里那个内置浏览器——不是再开一个窗口。**
+
+模型可以打开网址、把页面读成带编号的控件、点击、输入、执行脚本。你能看见它做每一步：指针移到目标上，落点有涟漪。页面就跑在产品自己租用的 `<webview>` 里，分区和 cookie 都没换，所以你手动登录过的那页，就是 agent 操作的那页。
+
+> **关于名字：** *inner* 指 Harness 侧边栏里内置的浏览器。这个插件不另开窗口，也不接管 Chrome。
+
+## 提供的工具
+
+| 工具 | 作用 |
+| --- | --- |
+| `browser_navigate` | 在本文的内置浏览器里打开网址，返回页面。 |
+| `browser_view` | 返回地址、标题、可见文字，以及 `#1 … #80` 编号的控件。 |
+| `browser_click` | 点击一个编号控件，返回跳转后的页面。 |
+| `browser_type` | 往一个编号输入框里写字，可选回车。 |
+| `browser_script` | 执行 JavaScript，返回最后一个表达式。 |
+| `browser_selection` | 返回页面里选中的文字。 |
+| `browser_copy` | 把选中内容、或某个编号控件的文字，复制到剪贴板。 |
+| `browser_screenshot` | 存一张当前画面的 PNG，返回文件路径。 |
+| `browser_download` | 把网页给的文件存进本对话的项目目录。网页自己开始的下载也落在同一个目录，触发它的那次调用会报出路径。 |
+| `browser_upload` | 把本机文件塞进一个编号的文件框。 |
+
+每次调用都可见：指针先滑到控件上，套一个光圈，页面会先把目标滚进视野。
+
+第一次调用会自己把标签页开出来：侧边栏里出现**内置浏览器**，不用先点 `+`。那是产品自己的标签页——同样的标签类型、同样的地址栏、同样的分区——插件只借用它，不往「开始」里加任何东西。你手动开的那页，就是 agent 操作的那页。
+
+## 安装
+
+```bash
+git clone https://github.com/regrevia/dsh-inner-browser-use
+```
+
+然后在 DeepSeek Harness 里：**插件 → 从文件夹安装**，选中该目录。或命令行：
+
+```bash
+dsh plugin install /path/to/dsh-inner-browser-use
+```
+
+也可以直接装打包好的发布版，不用 clone、不用 npm 账号：
+
+```bash
+dsh plugin install https://github.com/regrevia/dsh-inner-browser-use/releases/download/v0.11.40/dsh-inner-browser-use-0.11.40.tgz
+```
+
+装好后**插件**列表里出现 *内置浏览器*。需要桌面版，因为侧边栏浏览器是桌面能力。
+
+## 使用
+
+1. 打开你想让它浏览的那个会话。
+2. 直接提要求：*「打开 example.com，告诉我标题」*。第一次调用会把内置浏览器在右侧栏开出来；自己按 **+ → 内置浏览器** 也是同一个标签页。
+
+标签属于会话：每个会话在同一套内置浏览器里各有一页。会话里还没开过时，工具会替你在那里开。
+
+## 数据双向流动
+
+- **页面 → 聊天：** `browser_script` 返回字符串，`browser_screenshot` 存成 PNG，模型可以把页面内容写进对话，也可以把图片路径交给你。
+- **选中即用：** `browser_selection` 把你在页面里选中的文字交到对话里；`browser_copy` 把它压进剪贴板，⌘V 就粘进输入框。
+- **聊天 → 页面：** `browser_type` 写进输入框；`browser_script` 可以设置那些没法输入的字段。
+
+## 它不做什么
+
+- **不另开浏览器。** 没有新窗口，没有 Chrome 配置目录，没有 CDP 镜像。
+- **只有页面能读到的 cookie 才活过重启。** 访客分区在内存里，页面能读到的 cookie 按工作区存到 `~/.dsh/inner-browser-use/cookies/`，该工作区的侧边栏再次打开时写回；只存在 `HttpOnly` cookie 里的登录要重新输密码。
+- **截图只有可视区域。** `<webview>` 抓到的是看得见的那块，不是整页；要拍长页面先滚动。
+- **一个工作区一个分区。** 同一工作区的两个会话共用浏览器存储，和内置浏览器开两个标签时一样。
+- **没有新窗口、没有权限弹窗。** 想在新的窗口打开的链接留在当前页里。
+- **没有标签时会替你开。** 会话里还没有内置浏览器时，第一次调用就在那里开一页；你自己开的那页同样会被接管。
+
+## 兼容
+
+| | |
+| --- | --- |
+| Harness | 桌面版，且侧边栏浏览器存在 |
+| 标签 kind | `browser`，就是内置浏览器自己那个 |
+| 运行环境 | Node 20+ |
+| 许可 | MIT |
+
+链路细节见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，版本边界见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。
+
+## 开发
+
+```bash
+node --test test/*.test.mjs
+```
+
+宿主半边是零依赖 ESM，客户端半边是动态客户端模块，都没有构建步骤，应用直接加载。
+
+## 许可
+
+MIT © regrevia