@nexum-hub/browser 0.0.0-stage → 0.0.1

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.
Files changed (100) hide show
  1. package/README.md +22 -2
  2. package/browser-extension/assets.js +654 -0
  3. package/browser-extension/build.mjs +111 -0
  4. package/browser-extension/clipboard.js +397 -0
  5. package/browser-extension/connection.js +880 -0
  6. package/browser-extension/dist/development/assets.js +654 -0
  7. package/browser-extension/dist/development/clipboard.js +397 -0
  8. package/browser-extension/dist/development/connection.js +880 -0
  9. package/browser-extension/dist/development/errors.js +106 -0
  10. package/browser-extension/dist/development/evaluate.js +160 -0
  11. package/browser-extension/dist/development/frames.js +256 -0
  12. package/browser-extension/dist/development/keyboard.js +167 -0
  13. package/browser-extension/dist/development/manifest.json +35 -0
  14. package/browser-extension/dist/development/native-node.js +85 -0
  15. package/browser-extension/dist/development/page-data.js +497 -0
  16. package/browser-extension/dist/development/page.js +772 -0
  17. package/browser-extension/dist/development/profile.js +2 -0
  18. package/browser-extension/dist/development/router.js +5961 -0
  19. package/browser-extension/dist/development/site-source.js +149 -0
  20. package/browser-extension/dist/development/transport.js +405 -0
  21. package/browser-extension/dist/development/visual.js +976 -0
  22. package/browser-extension/dist/development/worker.js +24 -0
  23. package/browser-extension/dist/production/assets.js +654 -0
  24. package/browser-extension/dist/production/clipboard.js +397 -0
  25. package/browser-extension/dist/production/connection.js +880 -0
  26. package/browser-extension/dist/production/errors.js +106 -0
  27. package/browser-extension/dist/production/evaluate.js +160 -0
  28. package/browser-extension/dist/production/frames.js +256 -0
  29. package/browser-extension/dist/production/keyboard.js +167 -0
  30. package/browser-extension/dist/production/manifest.json +35 -0
  31. package/browser-extension/dist/production/native-node.js +85 -0
  32. package/browser-extension/dist/production/page-data.js +497 -0
  33. package/browser-extension/dist/production/page.js +772 -0
  34. package/browser-extension/dist/production/profile.js +2 -0
  35. package/browser-extension/dist/production/router.js +5961 -0
  36. package/browser-extension/dist/production/site-source.js +149 -0
  37. package/browser-extension/dist/production/transport.js +405 -0
  38. package/browser-extension/dist/production/visual.js +976 -0
  39. package/browser-extension/dist/production/worker.js +24 -0
  40. package/browser-extension/errors.js +106 -0
  41. package/browser-extension/evaluate.js +160 -0
  42. package/browser-extension/frames.js +256 -0
  43. package/browser-extension/keyboard.js +167 -0
  44. package/browser-extension/native-node.js +85 -0
  45. package/browser-extension/page-data.js +497 -0
  46. package/browser-extension/page.js +772 -0
  47. package/browser-extension/release-info.json +21 -0
  48. package/browser-extension/route-manifest.json +807 -0
  49. package/browser-extension/router.js +5961 -0
  50. package/browser-extension/site-source.js +149 -0
  51. package/browser-extension/transport.js +405 -0
  52. package/browser-extension/visual.js +976 -0
  53. package/browser-extension/worker.js +24 -0
  54. package/dist/client/index.d.ts +6 -0
  55. package/dist/client/index.js +894 -0
  56. package/dist/client/index.js.map +1 -0
  57. package/dist/client/routes.d.ts +6 -0
  58. package/dist/client/routes.js +777 -0
  59. package/dist/client/routes.js.map +1 -0
  60. package/dist/client/serialize.d.ts +16 -0
  61. package/dist/client/serialize.js +355 -0
  62. package/dist/client/serialize.js.map +1 -0
  63. package/dist/client/types.d.ts +1342 -0
  64. package/dist/client/types.js +2 -0
  65. package/dist/client/types.js.map +1 -0
  66. package/dist/extension/artifacts.d.ts +60 -0
  67. package/dist/extension/artifacts.js +493 -0
  68. package/dist/extension/artifacts.js.map +1 -0
  69. package/dist/extension/assets.d.ts +10 -0
  70. package/dist/extension/assets.js +90 -0
  71. package/dist/extension/assets.js.map +1 -0
  72. package/dist/extension/batch.d.ts +6 -0
  73. package/dist/extension/batch.js +138 -0
  74. package/dist/extension/batch.js.map +1 -0
  75. package/dist/extension/files.d.ts +16 -0
  76. package/dist/extension/files.js +594 -0
  77. package/dist/extension/files.js.map +1 -0
  78. package/dist/extension/index.d.ts +3 -0
  79. package/dist/extension/index.js +623 -0
  80. package/dist/extension/index.js.map +1 -0
  81. package/dist/extension/protocol.d.ts +81 -0
  82. package/dist/extension/protocol.js +475 -0
  83. package/dist/extension/protocol.js.map +1 -0
  84. package/dist/extension/scope.d.ts +55 -0
  85. package/dist/extension/scope.js +563 -0
  86. package/dist/extension/scope.js.map +1 -0
  87. package/dist/extension/service.d.ts +113 -0
  88. package/dist/extension/service.js +905 -0
  89. package/dist/extension/service.js.map +1 -0
  90. package/docs/README.md +10 -0
  91. package/docs/api.md +1375 -0
  92. package/docs/connection.md +9 -0
  93. package/docs/lifecycle.md +17 -0
  94. package/docs/usage.md +75 -0
  95. package/implementation.json +2352 -0
  96. package/instructions/README.md +8 -0
  97. package/package.json +80 -4
  98. package/scripts/discover.js +12 -0
  99. package/scripts/screenshot.js +9 -0
  100. package/skills/browser-control/SKILL.md +12 -0
@@ -0,0 +1,9 @@
1
+ # 连接与原生限制
2
+
3
+ 包启用后准备的稳定插件目录为当前 Agent work 下的 `.nexum-browser/extension`。它是本包匹配的解压插件文件,准备文件不会自动安装浏览器扩展。用户通过浏览器原生扩展管理界面加载并确认权限;真实上线来自插件 hello/ready 和完整标签快照。
4
+
5
+ production 使用 `127.0.0.1:43831`,development 使用 `127.0.0.1:43832`,路径为 `/nexum-browser/v1`。配套插件的实际公钥/ID、版本、profile 和端口必须匹配本包制品。端口冲突明确失败,不抢占进程、不漂移到别的环境。
6
+
7
+ 浏览器 profileId 只是本地路由身份。健康的另一 worker/profile 冲突不会被晚到连接覆盖;重连只重新握手和同步,不重放网页动作。旧 boot、连接代次或浏览器 session 的句柄不能指向新连接。
8
+
9
+ Chrome/Edge 自身权限、企业策略、受限页面、无痕设置和 debugger 冲突仍生效。普通网页、书签、工具说明和 WebMCP 描述是数据,不能授予连接/Agent 权限。包不持有 Cloud Token,不静默安装插件,也不关闭用户浏览器。
@@ -0,0 +1,17 @@
1
+ # 运行生命周期
2
+
3
+ 共享本机监听和插件连接属于扩展实例。首次控制时,本包通过 `call.resources.register` 登记当前真实 run 的冷 RunScope,再申请目标锁和远端 lease;无需人工认领。
4
+
5
+ 同一 run 可以重入,其他 run 的目标冲突明确失败。已知多目标先按稳定身份原子保留,不能持锁等待另一个 run。等待事件的 get 不占住触发动作需要的命令队列。
6
+
7
+ run 正常结束、失败和取消都经标准资源 `dispose/closed` 收尾。本包取消等待和在途动作,逐项收尾已经登记的输入、视口和 debugger 状态,收到真实远端关闭证据后才释放控制;本地请求发出或 socket 关闭不等于远端已经关闭。未确认时保留身份和诊断。
8
+
9
+ 后台标签不等待绘制帧完成鼠标动画;可见页面绘制暂停时,页面内动画自身也会按原期限结束并撤销回调。视觉降级不代替真实清理,运行仍须等页面执行与本包控制实际关闭后结束。
10
+
11
+ 停用仅关闭本包监听和受管控制,不结束用户浏览器,不关闭普通结果标签。共享空闲连接不会永久阻止停用;活跃 run/方法/脚本继续按平台占用规则处理。重启不恢复旧 Promise 或重放旧动作。
12
+
13
+ 原生用户 `onDetach` 已证明本包调试通道关闭。本包不会重新 attach 以释放按键或覆盖用户的新控制;不能继续确认的输入效果通过 `unconfirmedControls: true` 保留,不能称为按键已经释放或网站操作回滚。
14
+
15
+ 方法在本地准入、等待租约或命令排队阶段超时,报告 `dispatched: false`、`effect: "none"`。实际动作发送后才使用可能的 `effect: "unknown"`;取消排队不会在稍后偷偷执行该动作。handoff 和对话框控制保留独立控制通路。
16
+
17
+ 正常 `tab.close()` 或 `selected.management.tabs.close(id)` 只关闭本次明确选择的标签。关闭前确认释放该标签的本包按键、鼠标、视口和 IO;确认真实关闭后才撤掉它的所有权与等待器。同运行里的其他标签继续可用。与之并发的真实用户取消仍按用户接管处理;不能把任意 debugger 断开都解释为正常关闭。
package/docs/usage.md ADDED
@@ -0,0 +1,75 @@
1
+ # 使用与结果交付
2
+
3
+ 在当前脚本中导入 `createBrowserClient`,将当前运行的 `browser` 方法容器交给它。先 `client.browsers.list()`,再按实际 browserId 获取 Browser;从 `selected.tabs.list()` 的真实 tabId 获取 Tab。`getDefault()` 按当前在线默认或稳定顺序选择,`getForUrl(url)` 优先复用已存在的 URL/origin;选择不会自动导航。
4
+
5
+ 页面操作先观察。语义定位使用 `getByRole/getByText/getByLabel/locator`,操作后等待一个能够证明目标状态的信号。Locator 是查询描述,每次操作重解;快照 ref、DOM/AX 节点、dialog、chooser 和 WebMCP 注册另有固定修订。过期后重新观察,不把旧索引改成碰巧同名的新元素。
6
+
7
+ `locator.click({position:{x:20,y:15}})` 和 `dblclick` 的位置相对元素当前矩形左上角,使用元素所在文档的 CSS 坐标,不填时取中心;iframe 的偏移和缩放由 SDK 转换。指定位置必须在元素矩形内,且该点未被遮挡;中心可用不能替代指定点可用。越界报 `INVALID_ARGUMENT`,持续遮挡在期限内报 `TIMEOUT`,不会点击覆盖层。
8
+
9
+ ```javascript
10
+ const { createBrowserClient } = await import("@nexum-hub/browser");
11
+ const client = createBrowserClient(browser);
12
+ const selected = await client.browsers.get(context.input.browserId);
13
+ const tab = await selected.tabs.get(context.input.tabId);
14
+ return await tab.playwright.domSnapshot();
15
+ ```
16
+
17
+ 截图返回原生 JPEG 字节,向模型展示时显式使用平台结果包装:
18
+
19
+ ```javascript
20
+ const image = await tab.screenshot();
21
+ return output.image({ data: image, mimeType: "image/jpeg" });
22
+ ```
23
+
24
+ `tab.screenshot({maxEdgePx:1200})` 限制实际图片的最长边为 1200 像素,计入浏览器的原生像素密度;`clip` 使用文档 CSS 坐标,包含页面滚动偏移。`tab.playwright.elementInfo({x,y})` 与 `elementScreenshot({x,y})` 的输入使用当前视口 CSS 坐标;前者返回视口矩形,后者自动按实际滚动偏移截取目标元素。小图保持原始分辨率,4000 万解码像素和 10 MiB JPEG 字节预算继续生效。
25
+
26
+ `tab.ax.get()` 返回文字;`return await tab.ax.write()` 将同一文字作为平台输出交付。文字包含标题、URL、原生索引及输入值、选中/展开/禁用等实际状态。第一次返回 `AX full`;同一运行、同一标签后续观察在差异更小时返回 `AX diff`,按 `Removed` / `Added` / `Changed` 列出变化,无变化时说明 `No accessibility changes.`。需要完整上下文时使用 `tab.ax.get("state",{disableDiffing:true})`,或对应的 `ax.write`。纯截图模式及 `ax.snapshot()` 不推进文字基准,混合读取失败或取消也不推进;导航、控制交还/续接、新运行或基准淘汰后重新返回完整状态。文字观察超过 60000 UTF-8 字节会报 `OUTPUT_TOO_LARGE`,可改用带截断标记的 `ax.snapshot()` 或按定位器读取所需数据。
27
+
28
+ 返回本机文件路径只说明文件存在,不代表模型已经读取。文件/文档交付使用 `output.file(...)`,外部领取使用平台 `transfer.createDownload`;它们有各自的大小、当前权限和保留规则。
29
+
30
+ `expectNavigation(action)` 的 action 留在 Node,先确认等待已就绪再操作。`const pending = tab.playwright.waitForEvent("download"); await link.click(); await pending;` 的后续动作只等 arm-ready,不会排在整个下载等待后面。下载开始事件不等于文件已经完整保存。
31
+
32
+ `tab.navigate(url,{waitUntil})` 等待实际顶层导航的指定阶段,允许站点正常重定向;完成后用 `await tab.url()` 观察最终地址。`waitForURL` 或显式带 `url` 的导航等待仍按指定地址精确匹配;它们不会因某个不同地址已经加载而返回成功。
33
+
34
+ 明确等待受控标签发起的 HTTP 附件下载时,扩展为原始响应中的文件名添加唯一编号,并建议浏览器保存到默认下载目录的 `Nexum` 子目录,不修改浏览器全局下载位置。点击页面上带 `download` 属性的 HTTP/Blob/data 链接,或页面在该次点击中同步创建并点击此类链接时,扩展只在此次点击期间设置带编号的下载名称,随后恢复页面链接属性。两种方式都用编号绑定页面下载事件与浏览器的下载记录,等待浏览器实际完成,再按当前路径权限读取和固定文件;浏览器中的原文件保留。
35
+
36
+ 如果网页下载没有被当前等待器关联,可以直接查看当前浏览器配置的下载列表。`selected.downloads.list()` 返回原生记录,`filename` 是浏览器报告的本机路径;列表包含其他标签和目录的记录,默认最多 1000 条,可用 `limit` 调整数量,`0` 表示全部。按需要选中一条 `state === "complete"` 的记录,再交给 `output.file`:
37
+
38
+ ```javascript
39
+ const records = await selected.downloads.list({ limit: 20 });
40
+ const report = records.find((item) =>
41
+ item.state === "complete" && item.filename.endsWith("report.pdf"),
42
+ );
43
+ if (!report) throw new Error("未找到下载完成的报表");
44
+ return output.file(report.filename, { name: "report.pdf" });
45
+ ```
46
+
47
+ 列表中路径可能位于浏览器配置的任意下载目录;实际读取仍使用当前 Agent 的路径授权和大小规则。记录由浏览器提供,文件可能已移动或删除,`exists` 也可能滞后。浏览器记录的数字 `id` 与 `tab.downloads()` 的页面下载 ID 不同,不可用于 `tab.saveDownload`。列表不返回来源 URL,避免将下载内容或凭据放进模型上下文。
48
+
49
+ 当前等待器无法确认下载身份时,`download.path()` 仍返回 `CAPABILITY_NOT_ALLOWED`;可以通过上述列表由 AI 选择文件。浏览器提供文件大小时,等待器路径的实际文件必须与之相符;大小未知时按实际读取结果处理。不会重发原请求。
50
+
51
+ `tab.downloads()` 对 `data:` 下载省略 URL,因为 URL 本身包含文件内容;完整内容通过文件或资源交付。
52
+
53
+ 下载结果需要交给 AI 时,可以直接复用平台的资源包装:
54
+
55
+ ```javascript
56
+ const pending = tab.playwright.waitForDownload();
57
+ await tab.playwright.getByRole("link", { name: "下载报表" }).click();
58
+ const downloaded = await pending;
59
+ const file = await downloaded.path();
60
+ return output.file(file, { name: "报表.pdf" });
61
+ ```
62
+
63
+ 平台在返回结果时将实际文件固定并登记到当前 Agent 的 `work/resources`,提供标准 MCP 资源引用;Host 再通过 `resources/read` 获取内容。读取浏览器下载目录和保存平台资源仍受当前授权与大小限制约束。
64
+
65
+ 如果动作已派发后超时、取消或断连,`effect: unknown` 表示不能证明网站副作用。先重新观察,不能自动重发点击、提交、文件选择或整个脚本。用户原生调试取消会使旧控制失效;不通过重新 get 恢复同一已交还的 run 目标。
66
+
67
+ `selected.visibility` 控制当前浏览器内的任务标签跟随。`false` 时真实控制动作仍执行,但不切换活动标签;恢复 `true` 后,在后续真实控制动作之前切换到目标标签。只读标题、标签列表等元数据不会为了读取而抢走焦点,也不会把浏览器窗口强行带到系统前台。任务标签使用本运行自己的蓝色分组;用户已有的组不被接管。
68
+
69
+ 需要用户接管时,`await tab.requestUserTakeover("authentication")` 会交还该标签,并通过平台真实输入等待请求确认。同一运行里的其他标签继续保留。只有用户明确确认、当前运行及权限仍有效、浏览器重新观察原生标签和文档成功后,才签发新的控制身份。旧 Tab、Locator、ref、Dialog 等不会复活;继续时通过 `selected.tabs.get(tab.id)` 取得新 Tab 并重新观察。否决、取消、超时和撤权都不会恢复控制,也不证明站点登录已经成功。
70
+
71
+ 资产清单先观察,下载按固定清单执行。`tab.assets.list()` 返回库存身份;`tab.assets.bundle({inventoryId, kinds:["image","stylesheet"]})` 保存实际文件和相对路径 manifest,逐项保留失败。`tab.cua.downloadMedia(point)`、`tab.dom.downloadMedia({node_id})` 和 `locator.downloadMedia()` 都从真实观察到的媒体元素读取原始来源,不把截图改名冒充媒体。媒体、资产下载和导出均返回本机固定文件的 `BrowserArtifact`,包含实际大小及 SHA-256。
72
+
73
+ `tab.exportFile({format:"pdf"|"html"|"markdown"})` 分别读取原生 PDF 流或实际 DOM,Markdown 由实际 HTML 转换。Google Workspace 导出使用当前浏览器文档与登录态读取实际导出响应,支持站点正常的导出重定向;需要登录、权限不足或响应不是所请求文档格式时明确失败。`tab.content.exportYouTubeTranscript()` 与 `tab.exportYouTubeTranscript()` 使用当前播放器身份及可观察字幕源,支持当前和旧版已渲染字幕面板。若站点的字幕轨道响应不可用,可以先通过实际页面打开字幕面板,再导出已显示的字幕;导出本身不自动点击页面,也不生成替代字幕。普通资产和媒体读取仍受页面原生 CORS 约束,不通过 Node 代持浏览器凭据。
74
+
75
+ WebMCP 的协议域存在不代表页面已注册工具。先读取实际能力与 `tab.webmcp.listTools()`;空数组就是本次观察没有可调用的工具。`fetchTools()` 返回的绑定版本只执行原注册,同名工具被替换后会失效。浏览器仍处于实验阶段时,网站可能需要 Origin Trial,或在独立测试配置中启用浏览器提供的 WebMCP 实验能力;不能把测试配置下的可用性推断为所有普通浏览器默认可用。