> ## 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/panels)中的**模擬器**分頁以內嵌網頁檢視的方式執行已編譯的專案，自動偵測檔案變更，並為 [BRICKS CLI](/zh-Hant/cli) 提供 Chrome DevTools Protocol (CDP) 端點。

<Note>
  當[編輯器](/zh-Hant/ctor/reference/editor)分頁有未儲存的編輯時，模擬器會即時呈現這些尚未儲存的編輯，直到您儲存為止。
</Note>

## 開啟模擬器

從任一[面板](/zh-Hant/ctor/reference/panels)的 **+**（新增分頁）選單新增**模擬器**分頁，或點選輸入列中的**模擬器**按鈕——一個在模擬器執行時會切換為脈動圖示的播放圖示。該分頁會在背景開始編譯您的專案。

分頁開啟後，CTOR 會對專案執行型別檢查（`bun typecheck`）與編譯（`bricks ctor compile`），然後使用 `application.json` 中的 stage（`production`、`beta` 或 `development`）將應用程式載入內嵌網頁檢視。

<Info>
  模擬器需要安裝 `bun` 並在您的 `PATH` 中可用。
</Info>

## 面板控制

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

| 按鈕           | 動作                             |
| ------------ | ------------------------------ |
| **Draw**     | 切換繪圖模式                         |
| **Save**     | 將您的標註合成至螢幕擷圖並附加至聊天（僅限繪圖模式）     |
| **DevTools** | 將模擬器的檢查器停靠在窗格下方                |
| **詢問**       | 插入一段請求，要求代理透過其 CDP 端點檢查執行中的模擬器 |
| **Refresh**  | 重新載入網頁檢視                       |
| **彈出**       | 在新的應用程式內視窗中開啟模擬器               |
| **Close**    | 停止模擬器並關閉面板（僅限彈出視窗）             |

在面板中該分頁上按下 **×** 即可關閉模擬器（在彈出視窗中則使用 **Close** 按鈕），這會停止後端。

## 模擬器選單

以 **≡** 按鈕開啟模擬器面板的選單，其中列出：

* **Viewer** —檢視執行中應用程式的執行階段 Data
* **Logs**
* **Debug View**
* **Automations**
* **Mute**
* **Clear Persistent Data**
* **Take Screenshot**
* **Record Events as Automations** —將記錄的工作階段轉換為 [BRICKS Automation](/zh-Hant/foundation/automations)（請參閱[將互動記錄為自動化](#將互動記錄為自動化)）
* **Simulator Settings** —選擇哪些 Bricks 與 Generators 使用模擬替身（請參閱[模擬硬體與模型](#模擬硬體與模型)）
* **Compatibility**

## 模擬硬體與模型

為了讓模擬器能在沒有裝置權限、API key 或大型模型下載的情況下執行，它會為硬體 Brick 與模型 Generator 替換為輕量的替身：

* **Camera** —顯示模擬的 3D canvas，而非真實的相機畫面。
* **Maps** —呈現免費的 OpenStreetMap 圖磚，因此不需要地圖 API key。
* **Thermal Printer** —呈現模擬的螢幕收據；它一律為模擬。
* **LLM**、**Reranker**、**Speech-to-Text**、**Text-to-Speech** 與 **Vector Store** Generator —執行微小的本機替身模型。

已卸載至 [BRICKS Buttress](/zh-Hant/buttress) 的 Generator 在模擬器中會停用。

左下角的狀態氣泡會列出使用中的模擬項目，並包含一個 **Simulator Settings** 連結。從該連結或[模擬器選單](#模擬器選單)開啟 **Simulator Settings**，即可控制哪些部分以模擬方式執行。此面板將切換項目分組為 **Bricks** 與 **Generators** 區段——取消勾選某個 Brick 或 Generator 即可使用其真實實作，然後點選 **Apply**。套用會重新載入模擬器。

您可以在專案目錄中，從終端機檢查模擬的熱感式印表機輸出：

```bash theme={null}
bricks devtools simulator thermal-printer list
bricks devtools simulator thermal-printer print-result -o receipt.png
```

列印記錄保存在記憶體中——每台印表機最多 10 筆——並在模擬器重新載入時清除。

## 網路安全性

預設情況下，模擬器會封鎖不安全的 `http://` 與 `ws://` 請求；安全的 `https://` 與 `wss://` 請求則允許通過。若要測試僅提供不安全連線的主機，請將它加入專案層級的 `allowedInsecureHosts` 設定，以將其加入白名單。

## 停靠模擬器的 DevTools

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

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

## 在面板中的版面配置

模擬器與差異、編輯器、檔案、瀏覽器和 DevTools 分頁共用[面板](/zh-Hant/ctor/reference/panels)——無論是右側面板或下方面板。同一時間每個面板只會顯示一個分頁——可從分頁列切換，或在右側面板中以 **Cmd+1..9** 切換。拖曳面板邊緣的控制桿，即可相對於聊天區域調整其大小。

## 即時重新編譯

面板監視您的專案變更：

* 儲存 `subspaces/` 下的任何檔案會觸發透過 `bun compile` 的防抖動重新建置。
* `.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。
* **Brick Sketch 繪圖** —繪圖會記錄為它所產生、可匯入的狀態，每一段連續繪圖為一個步驟，因此重播會重現繪製的結果，而非一連串雜亂的逐筆步驟。

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

## 同時執行多個專案

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

## 繪圖模式

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

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

從調色盤挑選筆觸顏色，並以滑桿設定線條寬度。**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  # 瀏覽 Brick 元件樹
```

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

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

## 切換工作階段

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