dsh-page-struct
Read-only page structure for DSH, attached to the CUA browser. Extract table coordinates, shadow-DOM fields, code blocks, and confidence labels — without screenshots or a full-page dump.
只读的页面结构读取器：CUA 负责浏览器和登录，page-struct 只负责把页面读成结构。不做点击、输入或页面操作。
Architecture
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
The plugin does not launch or keep a browser alive. It reads the port that
browser_prepare wrote for the named CUA profile, attaches over CDP, and opens a
page in that same browser. CUA owns the browser lifecycle and the login state.
Why
Native snapshots often lose the structure an agent needs:
- table row/column coordinates, merged cells, multi-level headers;
- shadow-DOM component fields (
等级 = Lv.42);
- div/grid pseudo-tables that are not
<table>;
- code/log blocks on GitHub-style pages;
- whether a region is trustworthy (
high / partial / unreliable).
On the project's 4-page × 13-question benchmark, the structured representation made
13/13 answers determinable versus 2/13 for a flat snapshot, with 10× fewer
characters. See the upstream page-struct project for the benchmark and its caveats.
Prerequisite: a running CUA browser
Start the named CUA profile once:
browser_prepare({ profile: { mode: "isolated_named", name: "dsh-page-struct" } })
A visible Chrome window opens. Log in to the sites you need in that window.
The profile persists, so persistent cookies and localStorage survive restarts.
Then the plugin's default endpoint works:
{ "url": "https://example.com" }
If the CUA browser is not running, the tool returns a clear error. Start it with
browser_prepare and retry. The plugin cannot start or keep it alive.
Tools
| Tool | Purpose |
|---|
page_structure | Region index, table matrices, shadow-DOM fields, code blocks, confidence evidence. |
page_region | One region (T1 / P1 / X1 / S:<host> / C1) after the index was truncated. Reuses the latest analysis when possible. |
Both tools are read-only. Use CUA/browser tools for clicks, typing, and navigation.
Configuration
config:
proxy: ''
endpoint: cua:dsh-page-struct
cuaProfile: dsh-page-struct
exe: ''
cacheTtlMs: 120000
cacheMax: 3
| Key | Meaning |
|---|
endpoint | cua:<profile> (default), host:port, or "" for a one-shot temporary browser. auto is an alias for cua:<cuaProfile>. |
cuaProfile | Named CUA profile. Default dsh-page-struct. |
proxy | Only for endpoint: "". CUA/another browser must be configured with its own proxy at launch. |
exe | Optional Edge/Chrome path for the one-shot temporary browser. |
cacheTtlMs / cacheMax | In-memory snapshot cache used by page_region. |
Endpoint modes
cua:dsh-page-struct — attach to the running CUA browser. No new browser.host:port — attach to any browser already exposing CDP."" — launch a one-shot temporary browser (with proxy if set); useful for
fixtures, offline snapshots, or foreign pages that need a proxy.
Login state
CUA's isolated_named profile is a normal persistent Chrome profile:
persistent cookies and localStorage survive closing and re-running
browser_prepare. Session cookies (no Max-Age) still expire by design.
The plugin never touches your daily Edge/Chrome profile and never copies cookies.
Reading the current tab
page_structure({ tab: "current" }) attaches to an existing page in the CUA browser
without creating a tab or navigating. It shares cookies/login state and reads the
DOM as it is now (post-click, post-login, SPA route).
Selection order:
- explicit
targetId;
- exact URL match (
url), then URL prefix match;
- the last non-blank page target.
CDP does not expose the "active" tab, so with multiple tabs pass targetId for an
exact target. The output's 页面: line reports the URL that was actually read.
Examples:
{ "tab": "current" }
{ "tab": "current", "url": "https://example.com/report" }
{ "tab": "current", "targetId": "A95662CFE231DF63DE2DAEF4049DAB6F" }
page_region accepts the same tab/targetId and reuses the analysis when the
cache key matches.
Security and privacy
- Page content is returned to the DSH model as a tool result. The plugin does not
send it to any third-party service of its own.
- The CUA browser is a real Chrome with a persistent profile. Treat it as a
logged-in browser: do not expose its CDP port to untrusted local processes.
proxy can route temporary-browser traffic through a proxy; CUA browser traffic
follows the CUA browser's own launch configuration.- The plugin runs in the DSH Host process and only reads pages; it does not click,
type, download, or modify cookies.
Limitations
- Windows only. It depends on CUA's native browser profile layout.
- CUA must be running. The plugin cannot start it; use
browser_prepare.
- Read-only. No clicks, typing, scrolling, or navigation.
- Tab selection heuristic. With multiple open tabs,
tab:"current" may pick the
wrong one; pass targetId for an exact target.
- Latency. Reusing a warm browser is ~0.6–0.8s; a cold navigation can be
1–2s. Large pages are truncated to the index; use
page_region for details.
- Unsupported content. Closed shadow DOM, pure custom-drawn canvas, and some
virtualized lists are marked
unreliable.
License
MIT. The vendored page-struct core (vendor/page-struct/) is also MIT; see its
package.json and upstream project for attribution.
