浏览器窗格

Zshell 可以在任意标签页或分屏里放一个内置浏览器。它适合打开本地开发服务器、API 文档、issue，或者任何你想和当前终端并排看的网页。

打开浏览器复制链接

• 选 File → New Browser Tab 新建空白标签页。
• 打开命令面板（Cmd+P），运行 New Browser Tab 或 New Browser Pane。
• 在终端里按住 Command 右键一个识别出来的 URL，选 New Browser Tab 或 New Browser Pane，不用先复制地址。

浏览器标签页属于当前项目，和普通标签页、窗格一起参与布局。如果一个项目都没打开，Zshell 会先建一个项目，让浏览器有地方归属。

地址与搜索复制链接

顶部输入框可以接收完整 URL、主机名或搜索词：

• zshell.sh 会变成 HTTPS 地址。
• localhost、局域网主机名、IP 地址和显式端口使用 HTTP。
• 其他内容会变成 Google 搜索。

按 Cmd+L 聚焦输入框，Cmd+R 重新加载。工具栏还提供后退、前进、停止 / 刷新、分享和 Open in Default Browser。触控板的前进后退手势也能用。

决定链接打开在哪里复制链接

右键网页里的链接，可以选 Open Link in New Tab 或 Open Link in New Pane。新页面仍留在同一个项目工作区里。

在终端里，直接 Command 点按识别出来的网页 URL，会交给系统默认浏览器；按住 Command 右键，才会提供 Zshell 标签页和窗格。对本地路径也有一套对应操作，见路径与 URL。

会保留什么复制链接

切换标签页或项目后，网页会保持原样，包括浏览历史、滚动位置、表单和页面内部状态。Zshell 重启时会恢复当前 URL 和布局，但不会恢复完整的前进 / 后退历史。

浏览器窗格会跨标签页、跨启动保留 Cookie、登录状态和其他站点数据；这不是无痕浏览模式。

让 Agent 测试页面复制链接

可以让编程 Agent 检查当前项目中已经打开的页面、填写表单、核对结果或截取可见区域。Agent 复用现有浏览器会话，默认保持终端焦点，也可以为本地开发地址新建后台浏览器面板。

脚本可在 Zshell 终端中使用以下命令。记录返回的 browser_id，替换下方的 BROWSER_ID：

zshell +browser list
zshell +browser open http://localhost:3000 --wait
zshell +browser snapshot --browser BROWSER_ID
zshell +browser fill --browser BROWSER_ID --selector '#search' --text 'terminal'
zshell +browser click --browser BROWSER_ID --selector 'button[type="submit"]'
zshell +browser wait --browser BROWSER_ID --selector '#results' --timeout 10000
zshell +browser screenshot --browser BROWSER_ID --output /tmp/zshell-page.png

快照提供主框架的文本、可访问标签和元素引用。页面变化或执行操作后引用会过期，再次使用前需要重新获取快照。CSS 选择器必须唯一匹配一个元素。导航命令包括 navigate、back、forward、reload 和 stop。

自动化只接受完整的 HTTP/HTTPS 地址和 about:blank。其他协议、下载、文件选择器和原生对话框需要你直接操作；你通过地址栏或工具栏手动导航后，页面才会解除这一协议限制。命令只作用于调用终端所在的项目和窗口。--timeout 范围为 100–30000 毫秒。快照最多包含 200 个元素、32768 个文本字符，总大小不超过 256 KiB，密码和文件输入值会被省略。PNG 截图只截取可见区域，上限为 512 KiB，从未显示的后台面板也可截图，使用 1024 × 768 视口且不改变焦点，已有文件不会被覆盖；可用 --width 缩小截图。完整语法见 zshell +browser --help。

页面脚本与登录状态复制链接

zshell +browser eval --browser BROWSER_ID --script 'Promise.resolve({title: document.title})'
zshell +browser state save --browser BROWSER_ID --output /tmp/zshell-login.json
zshell +browser state load --browser BROWSER_ID --input /tmp/zshell-login.json
zshell +browser reload --browser BROWSER_ID --wait

eval --script 在真实主框架页面中执行脚本，等待返回的 Promise，并在 value 中返回 JSON；undefined 转为 null。需要 await 时使用异步函数表达式。脚本上限为 64 KiB，结果上限为 256 KiB、10000 个值和 64 层；执行后原 DOM 引用失效。超时只停止等待，不取消脚本。重试修改前先检查页面；同步死循环可能使页面无响应，需要关闭该页面。 单表达式（含 IIFE）通过原生全局 Script 注入执行。多语句字符串仍遵从页面 CSP；若字符串求值被禁止，请把语句包在 IIFE 中。

state save 将适用于目标主机的 Cookie（含父域和 HttpOnly Cookie）及当前来源的 localStorage 保存为 Playwright storage-state JSON。state load 合并 Cookie 并替换该来源的 localStorage，之后请重新加载页面。localStorage 的协议、主机和端口必须完全匹配；无关 Cookie 域、公有后缀、未知字段和错误类型会在任何修改前被拒绝。Secure Cookie 要求 HTTPS。

两个命令都加 --format cookies 可使用 Netscape cookies.txt，但该格式不保存 localStorage 和 SameSite。状态文件上限为 256 KiB，包含凭据，须保持私有且不要提交到 Git。导入只接受仅所有者可访问的普通文件（如 0600），拒绝符号链接；导出新建私有文件且不覆盖已有路径。WebKit 站点数据仍由各浏览器面板共享，命令继续受原有项目、窗口及导航限制。

广告与跟踪拦截复制链接

在 设置 → 浏览器 中管理原生 WebKit 内容拦截，默认开启 EasyList 和 EasyPrivacy。可单独关闭默认列表，也可每行添加一个 HTTP/HTTPS ABP 列表 URL，然后点击应用列表。最多 8 个列表，每个不超过 8 MiB；HTTP 下载未加密。

规则对所有现有和新建浏览器窗格的后续请求生效；更改后请重新加载页面，以更新资源和隐藏元素。立即更新列表会强制刷新。列表缓存在本机；重启后打开浏览器时，会检查超过四天的缓存。设置会显示更新状态、已转换和跳过的规则数量、失败，以及更新失败后使用缓存的状态。列表替换失败时，不会悄悄继续使用另一个已取消选择的列表。

支持 URL 通配符与锚点、常见资源类型、@@ 网络例外、简单的正负域名范围，以及 CSS ##/#@# 隐藏规则。域名范围以顶层页面为准，第一方/第三方分类遵循 WebKit。脚本片段、过程式过滤、重定向、正则表达式、整页放行和包含域名与排除其子域名的复杂范围会保守跳过，并非完整兼容 uBlock Origin。