與 AI Agent 協作

Zshell 的自動化主要是給 AI 編碼 agent 用的。它讓 agent 安全地操作 Zshell 的窗格、協調其他 agent；你不需要再學一套指令。

AI 集成預設啟用，直接像平時一樣和編碼 agent 對話。它可以新建後台窗格、啟動另一個 agent、執行指令、等待結果，再把結論帶回來，全程不搶走你正在使用的窗格焦點。

等待命令結果複製連結

對於測試、建置等會結束的命令，agent 可以等待命令本身的結束碼與耗時，再讀取儲存的最近終端輸出。等待逾時後命令仍會繼續執行，之後可以再次等待同一個工作，全程不搶焦點。這需要 Zshell 啟動的原始本機 zsh 處於空白提示字元；巢狀 shell、SSH 和自訂啟動程式不支援命令結果。最近終端輸出可能包含先前的命令或提示字元，且長度有限；需要完整記錄時，請讓 agent 將輸出儲存至檔案。

直接執行 exit、logout 或 exec 會結束或取代原始 shell，因此會被拒絕；請透過 /bin/sh -c 在子行程中執行這類命令。

設定複製連結

設定 → Automation → AI 預設開啟。如果之前關閉過，請重新開啟，再新建終端機；已經執行的編碼 agent 需要重新啟動。

Zshell 支持 Codex、Claude Code、Gemini CLI、Grok Build、OpenCode、Cursor Agent、Aider、Amp 和 Pi。如果現有 agent 配置與這項功能衝突，Zshell 會原樣保留它，讓開關回到之前的狀態，並在設定裡顯示錯誤。

直接說你想要什麼複製連結

告訴 agent 最終要達到的結果。例如：

在後台窗格裡跑相關測試，然後告訴我哪裡失敗了。

把這個 bug 交給另一個 Codex agent，完成後再檢查它的結果。

問一下負責 API 的 agent，schema 是否已經定下來，再把答案告訴跑測試的 agent。

在旁邊啟動開發伺服器，等它就緒後把 URL 告訴我。

看看後台 agent 做完沒有。如果它卡住了，告訴我需要什麼。

Zshell 的自動化接口由 agent 自己調用，你不需要輸入或記住任何自動化指令。

讓多個 agent 在窗格間協作複製連結

你可以把相關工作拆到幾個 Zshell 窗格裡，再讓主要 agent 負責協調。例如，一個 agent 修改 API，另一個補測試。協調方可以向指定的 agent 詢問發現或進度、補充要求、把有用的結果傳給另一個 agent，最後再把匯總後的答案交給你。不同窗格也可以執行不同的受支持編碼工具。

這樣並行工作時就不必由你來回複製上下文。每個 agent 的對話仍留在自己的窗格裡，協調方只會傳遞另一個 agent 當前需要的問題、更新或結果。

發出補充消息不代表任務已經完成。協調方仍要等待 agent、讀取結果並檢查結論。來自另一個 agent 的消息也不等於你的批准；權限、憑據、信任和破壞性操作仍然必須交還給你決定。

它執行時，你繼續工作複製連結

除非你要求查看，分派出去的窗格會留在後台。當 provider 的原生生命週期集成報告狀態時，Zshell 會在窗格和分頁上顯示：

Zshell 優先採用 Codex、Claude Code、Pi、OpenCode 和 Grok 的原生生命週期事件，其次採用程式主動回報。將游標停在狀態標記上，或開啟 Agents，可查看來源、等待原因、百分比及子任務。Codex 的 hook 需先在其 /hooks 選單中審閱並信任；Zshell 不會略過此步驟。

沒有原生回報時，Zshell 只會檢查已辨識 Agent 程序目前畫面底部的有限文字。畫面推斷會標示來源，不代表完成、不發送通知，也不能滿足 zshell +agent wait，更不會核准提示。請查看窗格及實際結果。

程式可使用 zshell +agent report 回報進度，並透過 zshell +agent clear 清除自己的回報。超過 120 秒未更新或所屬程序結束時，回報會失效。

當集成報告 agent 已完成或需要輸入時，Zshell 還可以發送通知。按 Cmd+Shift+A，會跳到下一個已報告且需要你處理的 agent。

帳戶用量與限制複製連結

設定 → Automation → 帳戶用量會顯示 Claude Code 和 Codex 當前可讀取的帳戶限制， 包括已使用百分比、提供方報告的重置時間，以及上次更新時間。點擊 重新整理用量可以重新讀取。

Codex 需要已安裝、已登錄且能報告帳戶限制的 CLI。Claude Code 的用量會在 Zshell 收到 提供方的狀態欄用量報告後顯示。僅在有可用資料時才顯示這一分區；具體用量週期取決於提供方和帳戶。 這裡顯示的是帳戶限制，不是當前工作階段的 token 總量。

一次典型的使用過程複製連結

1. 在 Zshell 終端機裡啟動你平時使用的編碼 agent。
2. 讓它分派一個範圍明確的任務、在後台執行某個程式，或協調另一個 agent。
3. 繼續在當前窗格工作；Zshell 會把後台任務留在同一個專案佈局裡，隨時看得見。
4. 如果 provider 會報告生命週期，可以通過 Working、Blocked 或 Done 徽章掌握進度；否則請打開對應窗格，直接查看對話或終端機輸出。
5. 在 Git 面板裡審閱結果和 diff，只保留你認可的改動。

決定權仍然在你手裡複製連結

• Agent 自動化只作用於當前 Zshell 專案，不能操作其他專案或視窗裡的窗格。
• 後台工作預設不搶焦點。
• Zshell 不會替你回答權限、憑據、信任或破壞性操作提示。Provider 報告 Blocked，就是把決定交還給你。
• Provider 報告的 Done 只表示可以開始審閱，不代表 Zshell 自動批准了 agent 的改動。

Agent 沒有使用 Zshell 時複製連結

• 確認 設定 → Automation → AI 已經打開。
• 如果當前終端機是在打開設定前創建的，請新建一個 Zshell 終端機。
• 如果 agent 當時已經在執行，請重新啟動它。
• 看看設定裡有沒有直接顯示的錯誤。
• 如果希望這次任務使用自動化，可以明確說「在 Zshell 後台窗格裡執行」或「交給另一個 Zshell agent」。

繼續原對話複製連結

啟用 恢復 Agent 對話 後，重新開啟終端窗格時，若原 PTY 不可用，會繼續該窗格已記錄的 Claude Code、Codex、Pi 或 OpenCode 原對話。同一目錄裡的多個窗格各自綁定自己的對話。

Zshell 在現有 provider 設定中安裝 Claude Code 和 Codex 的 SessionStart 掛鉤、Pi 擴充和 OpenCode TUI 外掛，保留其他掛鉤、外掛、設定和 JSONC 註解。provider 提示時，需在 Claude Code 信任提示中啟用掛鉤，並在 Codex 的 /hooks 中核准新掛鉤。安裝前已執行的 agent 需要重新啟動。

只恢復這些整合回報且經過驗證的根對話。共用 Codex app-server 工作階段在已驗證的對話 ID 與窗格相符時受支援，有歧義時不綁定。遠端主機上的對話請參閱遠端共用工作階段。OpenCode 需要支援 TUI 外掛 API 的版本；不支援舊版本、無介面 server 工作階段和 opencode attach。子 agent 不會覆蓋父窗格的對話。Pi 需要已儲存的工作階段檔案。

缺少已驗證身分、原工作目錄或 Pi 檔案時，窗格會開啟新 shell；找不到 CLI 時也會回到 shell。Zshell 不會重播任意啟動命令或選擇最近對話。對話已刪除等 provider 錯誤由 CLI 顯示。

尋找並繼續已儲存對話複製連結

開啟 Agent → Agent 對話歷史，點擊專案側欄頂部的時鐘按鈕。可以跨專案按標題、provider、專案、對話 ID、工作目錄或設定目錄搜尋。Zshell 保留最近 200 條已驗證的本機對話，Agent 或窗格關閉、應用程式重新啟動後仍可查看。最近 顯示 20 條未封存的符合結果；全部 包含封存記錄；已封存 只顯示封存記錄。

選擇 顯示對話 前往仍開啟的對話，或選擇 繼續對話 恢復已儲存對話。Zshell 優先使用現有窗格、重新連線仍存活的 PTY，再以原工作目錄和設定恢復 provider 的確切對話。手動恢復需要啟用 AI 整合，即使自動恢復對話設定已關閉也可使用。工作目錄、設定目錄不存在，或 Pi 檔案遺失、身分不符時，會在建立新窗格前顯示錯誤。

封存 將記錄從「最近」隱藏，取消封存 將其恢復。刪除… 只刪除 Zshell 歷史記錄，保留 provider 的對話檔案。

在 Zshell 窗格內，使用 zshell +agent history --all 和 zshell +agent resume --id HISTORY_UUID，範圍為當前窗格的專案。在一般外部終端機中，保持 Zshell 執行，先取得專案 UUID，再明確選擇專案：

zshell +agent history projects
zshell +agent history --project PROJECT_UUID --all
zshell +agent resume --project PROJECT_UUID --id HISTORY_UUID --focus

CLI 恢復預設在背景進行，加入 --focus 才切換焦點。專案在多個視窗中開啟時，用 history projects 回傳的 --window WINDOW_UUID 明確選擇；多個應用程式實例執行時，用 --connection PATH 指向 CLI 提示的絕對私有連線檔案路徑。這些目標選項只用於外部終端機，窗格程序始終保留原專案範圍。

訂閱專案即時事件複製連結

在 Zshell 窗格內執行 zshell +events，以 NDJSON 接收目前終端機所屬專案和視窗的後續變更。支援 --pane UUID、可重複的 --event NAME、--once 和 --timeout MS（0 為無限等待），不需輪詢。

事件涵蓋終端工作階段、窗格建立與關閉、焦點、Agent 進度與注意事項、完成及命令完成。首行 stream.ready 的 sequence 為 0，後續相符事件逐一遞增，包含 version、event、stream_id、sequence、Unix 毫秒 time、project_id 和 data。不重播歷史；命令工作結果用 +pane wait --task UUID 讀取。

最多 32 個訂閱，每個佇列最多 256 幀、1 MiB，單幀最多 64 KiB。落後時傳送 stream.lagged 並斷線；連續 2 秒無法寫入也會關閉。落後、意外斷線或序號錯誤會非零結束，請重新訂閱並讀取目前狀態。關閉所屬終端機、輪換權杖或移至另一專案/視窗會終止原訂閱並清空佇列。不支援外部控制或 --project；清除環境變數不會擴大權限。--once 未相符而逾時回傳 124，一般逾時回傳 0。

zshell +events --event command.task.finished --once --timeout 30000

pane.updated: data.from → data (tab_id, pane_id, terminal_id, content).