核心用法 / Core Usage
读取页面
snapshot 把页面变成一棵
带 ref 的可访问性树——你据此点击、输入；get text
则跨所有 frame 抓取正文，连 closed shadow DOM 都能穿透。
snapshot：结构化的页面视图
snapshot 从可访问性树生成页面结构。默认输出完整树（较冗长），
实际使用几乎总是加 -i：只保留可交互元素，
每个元素带一个 ref，把它作为 @eN 传给后续命令即可操作。
$ chrome-use snapshot # 完整树（冗长）
$ chrome-use snapshot -i # 仅可交互元素（推荐）
$ chrome-use snapshot -i -u # 链接上带出 href url
$ chrome-use snapshot -i -c # 紧凑：去掉空的结构节点
$ chrome-use snapshot -i -d 3 # 深度上限 3 层
$ chrome-use snapshot --json # 机器可读输出snapshot -i 开始。它体量小、只含你能操作的东西，
并且给出稳定可用的 @ref——这是驱动点击 / 输入的正规入口。
读懂 snapshot 的输出
输出是缩进的可访问性树，缩进代表嵌套深度：
Page: Example - Log in
URL: https://example.com/login
- heading "Log in" [level=1, ref=e1]
- textbox "Email" [ref=e2]
- textbox "Password" [ref=e3]
- button "Continue" [ref=e4]
- link "Forgot password?" [ref=e5]
每一行的格式是 - <role> "<可访问名称>" [<属性>, ref=eN]。
把 ref 作为 @eN 传给命令即可操作，例如
click @e4。
ref 在每次 snapshot 时重新编号。不要缓存旧的
@eN 跨操作复用——页面变化后先重新 snapshot，再拿新的 ref。
过滤庞大的快照
Synology DSM、NAS / 路由器管理后台、ExtJS 应用会把许多独立的「应用窗口」
渲染进同一棵可访问性树，snapshot -i 很容易撑爆 token 上限、
把目标控件淹没。不要 pipe 到 tail——用过滤器精准收窄。
$ chrome-use snapshot -s "#main" # 用 CSS 选择器把范围限定到一个容器
$ chrome-use snapshot -i -f "SSH|端口|应用" # 只保留匹配行 + 其祖先（正则）
-f/--filter <regex> 只保留匹配的行以及它们的祖先上下文，
refs 保持完整；-s <css> 则把整棵树限定到某一个
窗口的容器内。两者可以叠加使用。
校验错误也会一并出现
当表单拒绝提交时，原因会作为顶层的 alert 行追加进
-i 输出，例如 - alert "字数已超过 8 个字" 或
- alert "Email is required"——即使这条消息只是一个带样式的
<span>（.is-error、.invalid-feedback、
[role=alert]、aria-live），本来会被 -i 当作
非交互元素过滤掉。
alert 行是信息性的、故意不带 ref（你读它，不是点它）。
所以当一次 click 提交没反应时，别猜原因——直接重新
snapshot -i，读那几行 alert。
get text：非结构化地读正文
不需要 ref、只想读文字时用 get text。它可以读整页、读单个元素、
跳过导航样板、甚至穿透 closed shadow DOM。
$ chrome-use get text # 整页——默认聚合所有 frame（见下）
$ chrome-use get text @e1 # 单个元素的可见文本（也可传 CSS 选择器）
$ chrome-use get text --main # 仅正文——跳过 nav / header / 侧栏
$ chrome-use get text --pierce # 穿透 closed shadow DOM 读取（注入面板）
$ chrome-use frames # 列出每个 frame + 文本所在位置
$ chrome-use get html @e1 # innerHTML
$ chrome-use get attr @e1 href # 任意属性
$ chrome-use get value @e1 # 输入框的值
$ chrome-use get title # 页面标题
$ chrome-use get url # 当前 URL
$ chrome-use get count ".item" # 统计匹配元素数量整页文本默认跨 frame
不带选择器的 chrome-use get text 会聚合每一个 frame 的可见文本
——顶层文档、同进程子 frame、以及跨源 iframe——所以你不会静默漏掉
藏在 iframe 里的内容（Yahoo 拍卖 / 乐天 / Mercari 的商品描述、内嵌的结算 / 规格 frame）。
每个子 frame 用 ----- frame [kind] url ----- 标记分隔。你不需要记任何 flag，
默认就已经读全部 frame（--all-frames 仍作为显式别名保留）。
chrome-use get text 读全部。想看清结构（哪个 frame
装了什么）就 chrome-use frames；想去掉样板（全局 nav/header/footer、
「相关商品」侧栏）就 get text --main。若内容是懒加载的，先
scroll 到可视区再读。
read：把 URL 拉成 agent 可读文本
read [url] 抓一个 URL，尽量给出干净的 markdown/文本：优先找
.md 版本和附近的 llms.txt，都没有就从 HTML 里提取可读正文。
不传 URL 时读的是当前活动标签页渲染后的 DOM。
它跟 snapshot/extract 的分工不同：read 拿的是给人看的
正文/markdown，snapshot/extract 拿的是可交互元素
/ 结构化数据。
$ chrome-use read https://docs.example.com/guide # 读一个 URL
$ chrome-use read https://docs.example.com/guide --outline # 只要标题大纲
$ chrome-use read # 读当前活动标签页
常用 flag：--raw（原样返回响应体，不做任何加工）、--require-md
（响应不是 text/markdown 就直接失败）、--llms <index|full>
（读附近 llms.txt 的索引或完整版）、--outline（只要标题大纲）、
--filter <text>（只保留匹配的小节/标题）、--timeout <ms>。
--json 会连同元数据一起返回内容。
read https://site/docs/ --llms index
列出它 llms.txt 收录的页面清单（就近向上找 llms.txt），
挑中目标页后用 read <page> --require-md 强制要 markdown 版；
不带 --require-md 时会回退到从 HTML 提取的正文。
--llms 不能和 --outline 同用。
read；想找
可交互元素去点击/输入——用上面的 snapshot；
想要结构化 JSON——用 extract。
eval：在指定 frame 里执行
eval 默认跑在主 frame。它不会静默绑定到 Chrome 恰好返回的
某个 frame——裸的 eval 永远指向顶层文档。要在子 frame 里执行
（例如跨源的 Google 账号选择器），用
--frame <index|url-substring|@ref|css-selector>
（index / url 来自 chrome-use frames）。
$ chrome-use frames # 先拿到 index / url
$ chrome-use eval --frame accounts.google.com "location.href"穿透 closed shadow DOM
有些注入式 UI（浏览器扩展的调试面板、Web Components）渲染进
closed shadow root，eval / innerText 读不到。
chrome-use get text --pierce 通过 CDP 的 DOM 树穿透 closed shadow root
和子文档读取——当内容明明在屏幕上（截图能看到），而 get text /
eval 却返回空时，就用它。
snapshot -i 基于可访问性树构建，而 AX 树本身就已经穿透
closed shadow root——一个 closed-shadow 的 <button> /
[role=button] 会作为普通 @ref 出现，照常点击即可。
只有 closed root 里那种无语义的可点击 <div>
才可能同时躲过 AX 树和光标元素扫描。
下一步
读懂页面之后，拿着这些 ref 与文本去做点什么。