页面结构读取器 LISHUANGXI1412/dsh-page-struct

dsh-page-struct

给 DSH 用的只读页面结构读取器，挂在 CUA 浏览器上。 提取表格坐标、shadow-DOM 字段、代码块和置信度标签——不用截图，也不用整页 dump。

只读的页面结构读取器：CUA 负责浏览器和登录，page-struct 只负责把页面读成结构。不做点击、输入或页面操作。

架构

CUA browser (profile: %LOCALAPPDATA%\CuaDriver\BrowserProfiles\dsh-page-struct)
│ CDP 127.0.0.1:<port>
├── CUA tools: browser_navigate / browser_click / browser_type
└── dsh-page-struct: page_structure / page_region
→ same process, same cookies, same localStorage

插件不启动浏览器，也不维持浏览器存活。它读取 browser_prepare 为指定 CUA 配置档写下的端口，通过 CDP 连上去，在同一个浏览器里打开页面。浏览器生命周期和登录状态都归 CUA 管。

为什么需要它

原生快照经常丢掉智能体需要的结构：

- 表格的行列坐标、合并单元格、多级表头；
- shadow-DOM 组件字段（等级 = Lv.42）；
- 不是 的 div/grid 伪表格；
- GitHub 风格页面上的代码块和日志块；
- 某个区域是否可信（high / partial / unreliable）。

在项目自带的 4 页 × 13 题基准测试里，结构化表示让 13/13 道题都能确定答案，扁平快照只有 2/13，字符数还少了 10 倍。基准测试和它的注意事项见上游 page-struct 项目。

前提：CUA 浏览器正在运行

先启动一次指定的 CUA 配置档：

browser_prepare({ profile: { mode: "isolated_named", name: "dsh-page-struct" } })

会弹出一个可见的 Chrome 窗口。在这个窗口里登录你要用的站点。配置档会持久化，所以持久 cookie 和 localStorage 重启后还在。

之后插件的默认端点就能用了：

{ "url": "https://example.com" }

CUA 浏览器没运行时，工具会返回明确的错误。用 browser_prepare 启动后重试。插件没法启动它，也没法维持它存活。

工具

| 工具 | 用途 |
| page_structure | 区域索引、表格矩阵、shadow-DOM 字段、代码块、置信度证据。 |
| page_region | 索引被截断后，单独取一个区域（T1 / P1 / X1 / S:<host> / C1）。尽量复用最近一次分析结果。 |

两个工具都是只读的。点击、输入、导航请用 CUA/浏览器工具。

配置

config:
proxy: ''
endpoint: cua:dsh-page-struct
cuaProfile: dsh-page-struct
exe: ''
cacheTtlMs: 120000
cacheMax: 3

| 键 | 含义 |
| endpoint | cua:<profile>（默认）、host:port，或 "" 表示一次性临时浏览器。auto 是 cua:<cuaProfile> 的别名。 |
| cuaProfile | 指定的 CUA 配置档。默认 dsh-page-struct。 |
| proxy | 仅用于 endpoint: ""。 CUA 或另一个浏览器必须在启动时配好自己的代理。 |
| exe | 可选，一次性临时浏览器用的 Edge/Chrome 路径。 |
| cacheTtlMs / cacheMax | page_region 使用的内存快照缓存。 |

端点模式

- cua:dsh-page-struct — 连接到正在运行的 CUA 浏览器，不新开浏览器。
- host:port — 连接到任何已暴露 CDP 的浏览器。
- "" — 启动一次性临时浏览器（若设置了 proxy 则带上）；适合测试夹具、离线快照，或需要走代理的外部页面。

登录状态

CUA 的 isolated_named 配置档就是普通的持久化 Chrome 配置档：持久化 cookie 和 localStorage 在关闭并重新运行 browser_prepare 后依然保留。会话 cookie（没有 Max-Age）仍会按设计过期。

插件绝不碰你日常用的 Edge/Chrome 配置档，也绝不复制 cookie。

读取当前标签页

page_structure({ tab: "current" }) 连接到 CUA 浏览器里已有的页面，不新建标签页，也不导航。它共享 cookie/登录状态，读取当前的 DOM（点击后、登录后、SPA 路由切换后）。

选择顺序：

1. 显式指定的 targetId；
2. URL 精确匹配（url），再按 URL 前缀匹配；
3. 最后一个非空白页面目标。

CDP 不暴露「活动」标签页，所以有多个标签页时，要精确指定就传 targetId。输出的 页面: 行会报告实际读取的 URL。

示例：

{ "tab": "current" }
{ "tab": "current", "url": "https://example.com/report" }
{ "tab": "current", "targetId": "A95662CFE231DF63DE2DAEF4049DAB6F" }

page_region 接受同样的 tab/targetId，缓存键匹配时复用分析结果。

安全与隐私

- 页面内容作为工具结果返回给 DSH 模型。插件不会自行把它发给任何第三方服务。
- CUA 浏览器是带持久化配置档的真实 Chrome。把它当作已登录的浏览器对待：不要把它的 CDP 端口暴露给不可信的本地进程。
- proxy 可以让临时浏览器的流量走代理；CUA 浏览器的流量遵循 CUA 浏览器自身的启动配置。
- 插件运行在 DSH Host 进程里，只读取页面；不点击、不输入、不下载、不修改 cookie。

限制

- 仅支持 Windows。 依赖 CUA 的原生浏览器配置档布局。
- CUA 必须正在运行。 插件无法启动它；请用 browser_prepare。
- 只读。 不点击、不输入、不滚动、不导航。
- 标签页选择是启发式的。 打开多个标签页时，tab:"current" 可能选错；要精确指定就传 targetId。
- 延迟。 复用热浏览器约 0.6–0.8s；冷导航可能 1–2s。大页面会截断到索引；细节用 page_region。
- 不支持的内容。 闭合 shadow DOM、纯自定义绘制的 canvas，以及部分虚拟化列表会标记为 unreliable。

许可证

MIT。内置的 page-struct 核心（vendor/page-struct/）同样是 MIT；署名信息见其 package.json 和上游项目。