瀏覽器窗格

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。