> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 預覽

> 在內嵌預覽面板中執行您的 BRICKS 應用程式

在聊天視窗內預覽您的 BRICKS 應用程式。[右側面板](/zh-Hant/ctor/reference/right-panel)中的**預覽**分頁以內嵌網頁檢視的方式執行已編譯的專案，自動偵測檔案變更，並為 [BRICKS CLI](/zh-Hant/cli) 提供 Chrome DevTools Protocol (CDP) 端點。

## 開啟預覽

從[右側面板](/zh-Hant/ctor/reference/right-panel)的 **+**（新增分頁）選單新增**預覽**分頁。該分頁會在背景開始編譯您的專案。

分頁開啟後，CTOR 會執行 `bun typecheck`，接著執行 `bun compile.ts`，然後使用 `application.json` 中的 stage（`production`、`beta` 或 `development`）將應用程式載入內嵌網頁檢視。

<Info>
  預覽需要安裝 `bun` 並在您的 `PATH` 中可用。
</Info>

## 面板控制

分頁的工具列有以下按鈕：

| 按鈕           | 動作              |
| ------------ | --------------- |
| **DevTools** | 將預覽的檢查器停靠為底部面板  |
| **重新整理**     | 重新載入網頁檢視        |
| **彈出**       | 在新的應用程式內視窗中開啟預覽 |

從[右側面板](/zh-Hant/ctor/reference/right-panel)中該分頁上的 **×** 關閉預覽，這會停止後端。

## 停靠預覽的 DevTools

點選分頁工具列中的 **DevTools**，可將預覽自身的 Chrome DevTools 檢查器停靠為分頁底部的可調整大小面板。拖曳分隔線可調整其高度；再次點選 **DevTools** 即可隱藏。

此檢查器連線至預覽的本機 CDP 伺服器，因此無需通行碼。當您從**本機裝置**面板開啟的裝置正是前景專案的預覽時，其 DevTools 會匯入此停靠區；其他裝置則會以各自的 [DevTools 分頁](/zh-Hant/ctor/reference/right-panel#devtools)開啟。

## 在右側面板中的版面配置

預覽與差異、Controller 和 DevTools 分頁共用[右側面板](/zh-Hant/ctor/reference/right-panel)。同一時間只會顯示一個分頁——可從分頁列或以 **Cmd+1..9** 切換。拖曳面板左緣的控制桿，即可相對於聊天區域調整其大小。

## 即時重新編譯

面板監視您的專案變更：

* 儲存 `subspaces/` 下的任何檔案會觸發透過 `bun compile.ts` 的防抖動重新建置。
* `.bricks/build/application-config.json` 的變更會直接推送至執行中的網頁檢視，無需完整重新載入。

## 彈出視窗

點擊**彈出**可將預覽分離至獨立的無邊框應用程式內視窗。新視窗保持後端工作階段持續執行——關閉聊天側面板、切換工作階段或切換專案不會停止已彈出的預覽。關閉彈出視窗本身才會釋放工作階段。

## 由代理驅動的預覽

代理會使用與**預覽**分頁相同的預覽執行階段來擷取螢幕截圖並執行 [BRICKS Automation](/zh-Hant/foundation/automations) 測試，因此代理看到的內容會與您在分頁中看到的內容一致。若代理需要螢幕截圖時分頁尚未開啟，會在背景啟動預覽而不會把分頁蓋在聊天視窗上——此時輸入列會顯示一個帶有強調色圓點的**預覽**指示器，表示預覽正在背景執行。點選即可將預覽分頁移至前景。

支援視覺的模型會直接收到內嵌的螢幕截圖；同時也會將影像檔寫入專案，讓不支援視覺的模型仍可透過路徑參考。設定[備援視覺模型](/zh-Hant/ctor/reference/settings#備援視覺模型)後，CTOR 也會把每張螢幕截圖描述成文字，讓不支援視覺的模型能依其內容採取行動。

## 將互動記錄為自動化

當您與執行中的預覽互動時，CTOR 會逐步記錄每個操作。開啟預覽面板的選單（**≡** 按鈕），點選 **Record Events as Automations**，即可將這段記錄轉換為 [BRICKS Automation](/zh-Hant/foundation/automations)（E2E 測試）。

CTOR 不會直接幫您寫好測試，而是在聊天輸入框中預先填入一段請求，要求代理撰寫該自動化——請您檢視後再送出，就像 [繪圖模式](#繪圖模式) 將結果交給輸入列一樣。這段請求會為代理描述這次記錄：

* **真實時間** —每個步驟都會帶有觸發時的實際時間，以及與前一步的間隔，讓代理能重現步驟之間的真實節奏，而非套用一致的延遲。
* **具名項目** —每個步驟所參考的 Subspace、Brick、Generator 與 Canvas 都會解析為它們在編輯器中的別名（找不到時退回標題），讓請求以您專案中的名稱呈現，而非難以辨識的 id。

送出前可先編輯請求，以刪減或重新排序步驟。代理會以 bricks-ctor 的格式撰寫自動化，接著在預覽中編譯並執行，以確認測試通過。

## 同時執行多個專案

每個開啟的專案會保留各自的預覽生命週期，因此在某個專案啟動的模擬器，您切換到其他專案後仍會繼續執行。同一時間只會顯示一個預覽面板——以前景專案為準——但背景模擬器會持續執行，以供代理擷取螢幕截圖、CDP 檢視與彈出視窗使用。

## 繪圖模式

點選面板標頭的 **Draw** 可在執行中的預覽上方疊加一層標註畫布。面板底部會出現一列工具列，包含下列工具：

| 工具     | 動作                          |
| ------ | --------------------------- |
| **畫筆** | 手繪筆觸                        |
| **箭頭** | 從拖曳起點到放開處的直線箭頭              |
| **矩形** | 外框方塊                        |
| **文字** | 點選以放置可重新編輯的多行文字；按兩下既有文字即可編輯 |
| **擦除** | 在圖形上拖曳即可移除                  |

從調色盤挑選筆觸顏色，並以滑桿設定線條寬度。**Undo** 與 **Redo** 可逐步檢視你的編輯——或按 **Cmd/Ctrl+Z** 復原、按 **Cmd/Ctrl+Shift+Z**（或 **Cmd/Ctrl+Y**）重做。**Clear** 會清除全部內容。

直接在預覽內容上標註——圈出對位錯誤的元素、標記目標區域，或快速註記想法——接著點選 **Save** 將你的筆跡合成至預覽螢幕擷圖上，並將該單一影像附加至聊天輸入框。

繪圖模式在內嵌面板與彈出預覽視窗中皆可使用。在彈出視窗中儲存的影像會自動轉送到主視窗的聊天輸入框。

由於 **Save** 會產生影像附件，當所選的聊天模型不支援視覺時，**Draw** 按鈕會停用——除非您已設定[備援視覺模型](/zh-Hant/ctor/reference/settings#備援視覺模型)，由它把已註解的螢幕截圖描述成文字。

## CDP 與 `bricks devtools`

預覽執行時，CTOR 會啟動 CDP 伺服器，並將探索資訊寫入專案目錄中的 `.bricks/devtools.json`。[BRICKS CLI](/zh-Hant/cli) 讀取此檔案以從終端機檢查執行中的預覽。

在專案目錄內執行：

```bash theme={null}
bricks devtools scan        # 自動探索本機預覽
bricks devtools brick tree  # 瀏覽磚塊元件樹
```

執行 `bricks devtools --help` 以檢視完整的子指令清單（`brick`、`input`、`network`、`runtime`、`screenshot`、`storage`）。

關閉面板時，探索檔案會被移除。

## 切換工作階段

切換至不同的聊天工作階段時，若預覽面板屬於其他專案或工作階段，會自動隱藏面板，但**不會**停止底層模擬器。回到擁有該面板的專案與工作階段時，面板會再次顯示。當您不再需要模擬器執行時，請以面板的**關閉**按鈕明確停止。