dsh-sidebar-browser-agent 0.0.0-stage → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## 0.2.6
+
+- Publishing is now token-free: the publish workflow authenticates to npm with
+  **Trusted Publishing (GitHub OIDC)**, publishes with provenance, and no
+  longer needs the `NPM_TOKEN` secret (long-lived/bypass-2FA tokens are being
+  deprecated by npm).
+
+## 0.2.5
+
+- Resilience: every awaited guest operation (page script, screenshot, native
+  navigation) is now bounded by a deadline. A hung or unresponsive page becomes
+  a normal command error and the bridge keeps polling, instead of blocking the
+  page half until the plugin is reloaded.
+- Update without restart: the Host entry is now a versioned file
+  (`lib/entry-<version>.js` published through `package.json`'s `"."` export).
+  A reinstalled newer version resolves a new module URL, so the running Host
+  loads the new Host code after a Plugin Manager update instead of executing
+  the previously cached module.
+
+## 0.2.4
+
+- Page actions no longer refuse while the guest still reports loading assets:
+  readiness now follows the document's `readyState` (bounded to 5 s), so slow
+  pages such as GitHub's login and 2FA screens stay controllable.
+
+## 0.2.3
+
+- Package entries moved to `lib/index.js` and `lib/client.js` (DSH package
+  convention). A replaced install now resolves a fresh Host module generation,
+  so a GitHub update can load new Host code without a manual restart.
+- `sidebar_browser status` warns when the page half and the running Host half
+  report different versions (`restart the Harness to load the installed Host code`).
+
+## 0.2.2
+
+- Plugin Manager configuration page: the bundle's row now has a **Configure**
+  page under Plugins → bundle → row, with switches for `enabled`, `allowedHosts`,
+  `allowEval`, `allowNativeInput`, a save/reset form and localized copy (en/zh).
+- Config fields are declared `.volatile()`: edits apply to the running plugin
+  immediately (tool visibility through a per-step condition, gates read live
+  values) without restarting it.
+- `status` diagnostics now report the configuration form state (`checks.configForm`).
+
+## 0.2.1
+
+- docs: document GitHub installation, the update flow, the release process, and the
+  difference between GitHub-installed (remove + reinstall) and registry-installed
+  (one-click Update) bundles. No behavioral change to the plugin tools.
+
+## 0.2.0
+
+- Initial public release.
+- `sidebar_browser`: `status`, `list`, `open`, `navigate`, `reload`, `focus`, `close`
+  for native right-sidebar browser tabs.
+- `sidebar_page`: `read` (text / interactive / html), `click`, `type`, `press`,
+  `scroll`, `wait`, `eval`, `screenshot`, driven through the native Electron
+  `<webview>` guest (`executeJavaScript`, `capturePage`, `sendInputEvent`,
+  `loadURL`, `reload`).
+- Native Schemastery configuration: `enabled`, `allowedHosts`, `allowEval`,
+  `allowNativeInput`.
+- Startup self-check and `status` diagnostics (carrier, DOM contract, native API
+  list, Harness release, host config, attachment availability).
+- Page actions continue on the calling conversation's hidden sidebar tab while
+  another conversation is on screen; layout actions and screenshots report when
+  visibility is required.
+- Dependency-free regression suites for both halves, GitHub Actions CI, npm
+  publish workflow, and `scripts/set-version.mjs` version tooling.

package/LICENSE

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

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# 侧栏浏览器 Agent 控制（dsh-sidebar-browser-agent）
 
-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.
+给 DSH 右侧栏的**原生浏览器**加上完整的 Agent 可操作能力：管理标签页，并读取页面内容、
+点击、输入、按键、滚动、执行 JS、截图返回给模型查看；带配置开关、启动自检与回归测试。
+
+实现是**全原生**的：不依赖 Playwright/Puppeteer、不注入代理、不重写页面。页面操作直接使用
+侧栏浏览器自带的 Electron `<webview>` 客户端的 Chromium API：
+
+- `executeJavaScript()` —— 在真实页面里读取 DOM、执行脚本；
+- `sendInputEvent()` —— 原生鼠标/键盘事件（真实点击、按键）；
+- `capturePage()` —— Chromium 原生截图，经 attachment 服务变成图像内容块返回给模型；
+- `loadURL()` / `reload()` —— 原生导航与刷新，侧栏地址栏同步更新。
+
+## 结构
+
+| 文件 | 作用 |
+| --- | --- |
+| `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 Desktop 原生载体（Electron webview）**；Web 构建下侧栏浏览器是沙箱跨域 iframe，
+  页面操作会明确报错，标签页管理仍可用，读取纯文本可改用 `web_fetch`。
+- 调用时 Harness 页面必须打开；`open`/`focus`/`close`/`screenshot` 需要调用会话正显示在页面上。
+- 截图是当前视口（非整页长图），且只在会话可见时可靠；超宽图会自动降采样，最大约 12MB base64。
+- 页面卡死/无响应时，guest 调用会在 25s 内返回超时错误（导航 20s），桥保持可用；极端情况下仍建议重载该标签页。
+- `eval` 可在页面执行任意 JS（可用配置关闭），等同把该页面当作可编程环境；请只在可信页面使用。
+- 侧栏浏览器对页面有沙箱限制：无下载、无弹窗（会转为新侧栏标签）、无权限授予，页面也访问不到 DSH 应用。
+
+## 许可
+
+本插件 MIT（见 `LICENSE`）。`vendor/` 内置的 `@deepseek-ai/schemastery` 与
+`@deepseek-ai/cosmokit` 同为 MIT，来源与改动见 `vendor/NOTICE.md`。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle patch for dsh-sidebar-browser-agent.
+#
+# One Host row: it registers the `sidebar_browser` model tool and the HTTP
+# bridge the Web page half uses. The browser half is declared through the
+# package's `dsh.client` section, so no separate row is needed for it.
+- insert:
+    - id: sidebar-browser-agent
+      name: 'dsh-sidebar-browser-agent'

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Sidebar browser agent">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#1f6feb"/>
+  <circle cx="31" cy="29" r="15" fill="none" stroke="#ffffff" stroke-width="2.4"/>
+  <ellipse cx="31" cy="29" rx="6.5" ry="15" fill="none" stroke="#ffffff" stroke-width="2.4"/>
+  <path d="M16 29h30" stroke="#ffffff" stroke-width="2.4" stroke-linecap="round"/>
+  <circle cx="47" cy="47" r="9.5" fill="#0b2a4a" stroke="#7ee787" stroke-width="2"/>
+  <path d="M42.5 47h9M47 42.5v9" stroke="#7ee787" stroke-width="2" stroke-linecap="round"/>
+</svg>