> ## 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.

# 本機除錯

> 在區域網路上連接 Chrome DevTools 並存取 MCP 端點

BRICKS Foundation 實作了 Chrome DevTools Protocol (CDP)，為您的應用程式提供類似前端的除錯體驗。透過 Chrome DevTools 連線，可以檢查 DOM、除錯 JavaScript、分析效能並檢視主控台記錄。您也可以連線支援 CDP 的工具（如 Puppeteer 或 Playwright）以撰寫自動化指令碼，或透過 AI 代理連線。此外也提供 MCP 端點供 AI 代理整合使用。

## 在裝置上啟用 DevTools

<Steps>
  <Step title="開啟進階設定">
    在裝置上開啟**設定**，並導覽至進階設定區段。
  </Step>

  <Step title="啟用 Chrome DevTools">
    開啟 **Chrome DevTools**。裝置會在區域網路上的連接埠 `19851` 啟動 DevTools 伺服器。若該連接埠已被使用，則會自動遞增至下一個可用的連接埠。
  </Step>
</Steps>

## 探索裝置

使用 [BRICKS CLI](/zh-Hant/cli) 掃描區域網路中已啟用 DevTools 的裝置：

```bash theme={null}
bricks devtools scan
```

<Info>
  裝置必須在進階設定中開啟**啟用 LAN 探索**，網路掃描才能正常運作。預設為啟用。
</Info>

## DevTools 端點

找到裝置後，使用 `bricks devtools open` 搭配 `--info` 旗標檢視所有可用端點：

```bash theme={null}
bricks devtools open <device-address> --info
```

此指令會顯示以下連線 URL：

| 端點          | 說明                                           |
| ----------- | -------------------------------------------- |
| **Web UI**  | 在瀏覽器中開啟此 URL 以存取 DevTools 首頁                 |
| **CDP**     | 直接連線的 Chrome DevTools Protocol 端點            |
| **MCP**     | 供 AI 代理整合使用的 Model Context Protocol 端點       |
| **MCP SSE** | 使用 Server-Sent Events 傳輸的 MCP 端點             |
| **Info**    | 位於 `/devtools/info` 的 JSON 中繼資料端點，描述裝置、版本與協定 |

輸出內容也會包含裝置通行碼（若已探索到），以及 MCP 與 MCP SSE 端點所需的 `Authorization: Bearer <passcode>` 標頭。

未加上 `--info` 時，指令會顯示伺服器識別資訊（名稱、版本、裝置 ID、工作區、協定與驗證狀態）。

### 開啟 DevTools 頁面

在瀏覽器中開啟 **Web UI** URL 以存取 DevTools 首頁。您可以在此檢查正在執行的應用程式、檢視可用的除錯目標，並連線至裝置。

### 透過 Chrome 連線

您也可以直接透過 Chrome 連線：

1. 在[進階設定](/zh-Hant/foundation/settings#chrome-devtools)中啟用 **Expose endpoints for chrome://inspect**
2. 在 Chrome 中開啟 `chrome://inspect`
3. 您的裝置會出現在遠端目標清單中
4. 點選**檢查**以開啟連線至正在執行應用程式的 DevTools 視窗

<Warning>
  **Expose endpoints for chrome://inspect** 會在不需驗證的情況下公開裝置的 `/json` 端點以供 Chrome 探索，這會以明碼形式暴露通行碼。請僅在信任的網路上用於除錯。
</Warning>

### 透過 BRICKS CLI 檢視（CDP）

<Info>
  需要 BRICKS Foundation **2.24** 或更新版本。
</Info>

[BRICKS CLI](/zh-Hant/cli) 提供 CDP 指令，可直接從終端機檢視裝置，無需開啟瀏覽器：

```bash theme={null}
# 列印 brick 元件樹
bricks devtools brick tree -a <device-address>

# 擷取截圖
bricks devtools screenshot -a <device-address> -o screenshot.png

# 執行 JavaScript 運算式
bricks devtools runtime eval -a <device-address> "document.title"

# 監控網路活動
bricks devtools network list -a <device-address>
```

若裝置需要驗證，請使用 `--passcode`。完整 CDP 指令清單請參閱 [CLI 指令參考](/zh-Hant/cli/commands#devtools-cdp-指令)。

## 使用 DevTools 可以做什麼

已連線的 DevTools 視窗看起來像瀏覽器，但 BRICKS Foundation 並不是網頁，每個面板投射的是裝置的即時執行狀態。共有四個面板已啟用且具有實際意義：**Elements**、**Console**、**Network** 與 **Application**。其他面板（Sources、Performance、Memory 以及檢查元素按鈕）會被隱藏，因為背後並沒有網頁。

### Elements—Brick 樹狀結構

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/elements-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=4538b96005a06765d77add9cf23b599b" alt="DevTools Elements 面板，顯示投射為 DOM 文件的 BRICKS 渲染樹" width="1600" height="827" data-path="images/foundation/elements-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/elements-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=aa67aa7af66515329bb7989c96a3b29e" alt="DevTools Elements 面板，顯示投射為 DOM 文件的 BRICKS 渲染樹" width="1600" height="833" data-path="images/foundation/elements-dark.webp" />
</Frame>

Elements 面板會將應用程式的**渲染樹**投射為 DOM 文件。此樹狀結構以 `#document` 為根節點，並以巢狀方式排列您在 BRICKS 中建立的結構：

```text theme={null}
#document
└─ bricks-system
   └─ subspace          ← 每個已渲染的 Subspace 各一個
      ├─ text           ← 目前 Canvas 上每個 Brick 各一個元素
      ├─ image
      └─ subspace       ← 巢狀的 Subspace
```

* 每個 **Subspace** 都是一個 `<subspace>` 元素。目前顯示的 Canvas 會合併至其中，因此其 Bricks 會直接以子節點呈現（不會有獨立的 `<canvas>` 節點），而 `canvas-*` 屬性（`canvas-id`、`canvas-title` 等）則描述目前顯示的是哪個 Canvas。
* 每個 **Brick** 都是一個元素，其標籤名稱為移除 `BRICK_` 前綴後的 Brick 類型，例如 `<text>`、`<image>`、`<text_input>`、`<video>`、`<chart>`、`<items>`、`<webview>`、`<qrcode>`。
* Brick 的主要內容會顯示為該元素的文字：Text Brick 顯示其字串，Image Brick 顯示其來源路徑（過長的值會被截斷）。

每個 Subspace 只會顯示**目前渲染的 Canvas**；該 Subspace 其他 Canvas 上的 Bricks 不會出現在樹狀結構中。**Generator** 與 **Data** 不會出現在 Elements 中：請在 **Network** 面板檢視 Generator 流量，並在 **Application** 面板檢視已儲存的 Data。

從 Brick 的屬性可讀取其識別資訊與版面配置：

| 屬性                          | 意義                                                                                            |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| `id` / `alias` / `short-id` | 識別碼。Short ID 會依類型加上前綴：`B_` 為 Brick、`S_` 為 Subspace、`C_` 為 Canvas、`D_` 為 Data、`G_` 為 Generator |
| `title`                     | Brick 在編輯器中的標題                                                                                |
| `pressable` / `editable`    | Brick 是否回應點選／接受文字輸入                                                                           |
| `hide`                      | Brick 是否隱藏                                                                                    |
| `x` / `y` / `w` / `h`       | 以 BRICKS **格線單位**（非畫素）表示的位置與大小                                                                |

選取某個 Brick 後，其屬性會內嵌顯示，解析後的執行階段狀態則顯示於側邊面板：**Properties** 分頁會列出該 Brick 的 `props`、`events`、`outlet` 與 `templateKey`，而 **Styles** 與 **Computed** 則顯示其合成後的版面配置。將游標停留在某個節點或選取節點時，會在裝置上**標示對應的 Brick 或 Subspace**，並顯示如 `text — WelcomeHeader` 的標籤。

從 Elements 搜尋框可使用 BRICKS 專屬的選擇器搜尋樹狀結構：

* `#welcome-text` 或 `#B_3`—依別名或 short ID 比對
* `:pressable`、`:editable`、`:hidden`—依能力或狀態比對
* `.MyStateGroup`—比對屬於某個狀態群組的 Brick

<Note>
  Elements 樹狀結構為**唯讀**：編輯屬性或移除節點並不會變更正在執行的應用程式，且編輯會還原。若要操作應用程式，請使用 Console 中的 `system` 輔助函式（如下），或使用支援 CDP 的自動化工具。
</Note>

### Console—執行階段記錄與 `system` 輔助函式

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/console-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=80ced98558809614177f0ba0543ea70a" alt="DevTools Console 面板，顯示連線橫幅與展開的 system 輔助物件" width="1600" height="226" data-path="images/foundation/console-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/console-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=81f10d7da3cf917d64cc85e8d9e0eb0f" alt="DevTools Console 面板，顯示連線橫幅與展開的 system 輔助物件" width="1600" height="223" data-path="images/foundation/console-dark.webp" />
</Frame>

Console 會串流**裝置執行階段本身的記錄**：應用程式輸出、事件觸發時的 `[System] Event:` 行，以及原生模型（LLM/STT）記錄。它並非網頁的 `console.*`。連線時會自動重播最近的歷史記錄。

連線時，BRICKS 也會將一組輔助物件直接注入 Console 的求值範圍中。**直接以名稱輸入**即可，不需要加上 `globals` 前綴。請先執行 `usage()` 列印完整目錄，或輸入 `globalThis` 展開整個樹狀結構。

| 輔助函式                                       | 用途                                                                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `info()` · `memoryUsage()` · `diskUsage()` | 裝置與應用程式資訊、記憶體與磁碟使用量                                                                                                                                                |
| `usage()`                                  | 列印可用輔助函式的目錄                                                                                                                                                        |
| `system.*`                                 | 檢查並操作正在執行的應用程式（見下方）                                                                                                                                                |
| `control.*`                                | `refresh()`、`clearCache()`、`takeScreenshot()`、`checkUpdate()`、`rebindDevice('imsure')`、`externalScreen(enable)`                                                    |
| `panel.*`                                  | 開啟裝置端疊加層：`panel.menu()`、`panel.info()`、`panel.apps()`、`panel.debug.root/data/log/cache/localSync()`、`panel.automation()`、`panel.advancedSetting()`、`panel.about()` |
| `automation.*`                             | E2E 自動化的 `list()`、`run(testId, payload)`、`stop()`                                                                                                                  |
| `mcp.*`                                    | 呼叫 MCP server/client Generator 的工具、資源與提示                                                                                                                           |
| `tv.focusRegistry()`                       | 檢查 TV／遙控器焦點登錄資訊                                                                                                                                                    |

`system.*` 是應用程式檢查的核心：

| 呼叫                                                                  | 回傳／作用                        |
| ------------------------------------------------------------------- | ---------------------------- |
| `system.isReady()`                                                  | 執行階段是否就緒                     |
| `system.subspaces()`                                                | Subspace 樹狀結構的快照             |
| `system.querySelector(sel)` · `querySelectorAll(sel)`               | 查詢**已渲染的** Brick 樹           |
| `system.query(sel)` · `queryAll(sel)`                               | 查詢**完整的**實例樹                 |
| `system.simulatePress(subspaceId, brickId)`                         | 點選某個 Brick                   |
| `system.simulateKeyDown(code, key, flags)` · `simulateKeyUp(...)`   | 送出按鍵輸入                       |
| `system.executeAction(subspaceId, { handler, action, parameters })` | 執行 Brick、Data 或 Generator 動作 |
| `system.data.storeList()`                                           | 列出 Data store                |
| `system.data.properties(subspaceId, { filter, command })`           | 列出 Property Bank 屬性          |
| `system.data.property(subspaceId, propertyId)`                      | 讀取單一屬性值                      |
| `system.cache.generatorCache(subspaceId, generatorId)`              | 讀取 Generator 的快取輸出           |
| `system.cache.runtimeCacheStats(subspaceId)`                        | 執行階段快取統計                     |
| `system.channel.keys()` · `subscriptions(regex)`                    | 檢查 channel（發布／訂閱）            |
| `system.storage.persist.global.get(key)` · `allKeys()`              | 讀取持續性範圍儲存（`memory` 為記憶體內）    |
| `system.localSync.isEnabled()` · `isMain()` · `summary()`           | Local Sync 狀態                |
| `system.inspectEventRouting(id)` · `inspectParentCall(id)`          | 追蹤事件的串接方式                    |

```js theme={null}
usage()                                  // 列印輔助函式目錄
system.subspaces()
system.querySelectorAll(':pressable')    // 已渲染樹中所有可點選的 Brick
system.data.storeList()
system.data.properties('S_1', { command: false })
system.simulatePress('S_1', 'B_3')       // 點選 Subspace S_1 中的 Brick B_3
control.takeScreenshot()                 // 直接在 Console 中內嵌呈現
panel.debug.log(true)                    // 開啟裝置端的記錄面板
```

<Tip>
  ID 遵循與 Elements 面板相同的前綴：Subspace 為 `S_`、Brick 為 `B_`、Data／屬性為 `D_`、Generator 為 `G_`。非同步輔助函式會透過 `[Launcher] …` 記錄行回報，而非以內嵌回傳值呈現。機密資訊（密碼、token、API 金鑰）會遮蔽為 `[HIDDEN]`。
</Tip>

### Network—請求流量

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/network-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=b94a05d0dd0f70ad7eec1f729749bbc6" alt="DevTools Network 面板，顯示擷取到的 HTTP 請求與標頭" width="1600" height="723" data-path="images/foundation/network-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/network-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=bba4afde4db8dd6c2389387e2358a234" alt="DevTools Network 面板，顯示擷取到的 HTTP 請求與標頭" width="1600" height="729" data-path="images/foundation/network-dark.webp" />
</Frame>

Network 面板會顯示 **Generator**、**Preload**（預載）與執行階段發出的請求。只要啟用 DevTools 就會進行擷取，因此即使尚未開啟面板，請求也會出現。各來源的呈現方式如下：

| 流量                                  | 呈現方式                                                                   |
| ----------------------------------- | ---------------------------------------------------------------------- |
| HTTP／HTTPS（HTTP Generator、內部 fetch） | 標準請求列（類型為 **Fetch**）：方法、URL、狀態、標頭、請求內容、回應主體                            |
| 串流／伺服器推送（HTTP 與 LLM Generator）      | 一列 **EventSource**；開啟 **EventStream** 分頁即可觀看事件                         |
| WebSocket（`ws` / `wss`）             | 一列 **WebSocket**；開啟 **Messages** 分頁即可觀看訊框                              |
| MQTT（`mqtt` / `mqtts`）              | 位於 broker URL 的 WebSocket 樣式列；每次發布或接收到的訊息都是一個顯示為 `[topic] payload` 的訊框 |
| Data Bank 即時訂閱、GraphQL              | 查詢以 HTTP 列呈現，訂閱則以 WebSocket 列呈現                                        |
| **Preload**（資產、字型、Media Box）        | 應用程式預載內容時的 `HEAD` 大小探測，以及 `GET`／`POST` 下載                              |

舉例來說，指向 `mqtt://broker.example.com:1883` 的 Generator 會顯示一列（狀態為 `101 Connected`）；將 `{"temp":21}` 發布至 `sensors/room1` 時，會在 **Messages** 中以傳出訊框 `[sensors/room1] {"temp":21}` 呈現，接收到的訊息則以傳入訊框呈現。

<Warning>
  網路流量會**原封不動地顯示，且不會遮蔽**：`Authorization` 標頭、URL 中的 API 金鑰，以及請求／回應主體全都可見。請將 DevTools 存取權視為敏感資訊，僅與您信任的人分享裝置通行碼。
</Warning>

Subspace、Canvas、Brick 與 Property Bank 值沒有直接的 Network 列：它們只會以發出請求的 Generator 或 Preload 步驟來源形式間接出現。回應主體僅會為最近的請求快取，且在 DevTools 啟動前就已建立的連線不會出現。

<Note>
  從執行階段快取提供的回應目前不會顯示為網路請求；在此面板中呈現執行階段快取活動屬於未來版本的規劃。
</Note>

### Application—已儲存的 Data（唯讀）

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/application-light.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=e49c06a591cb369454cef2309a6cc4d1" alt="DevTools Application 面板，顯示投射至 IndexedDB 的 BRICKS 儲存" width="1600" height="612" data-path="images/foundation/application-light.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/bricks-207cc1f2/14EfWWl_W0enCa3o/images/foundation/application-dark.webp?fit=max&auto=format&n=14EfWWl_W0enCa3o&q=85&s=2c6217ed1c45d45d062e9d52525822de" alt="DevTools Application 面板，顯示投射至 IndexedDB 的 BRICKS 儲存" width="1600" height="614" data-path="images/foundation/application-dark.webp" />
</Frame>

Application 面板會將裝置的執行階段儲存投射至瀏覽器的儲存區，全部位於單一來源 `bricks://app` 之下：

| DevTools 位置                              | BRICKS 資料                                                                           |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| **Local Storage**                        | 持續性範圍儲存（重新啟動後仍保留），鍵為 `global:<key>` 與 `subspace:<id>:<key>`                         |
| **Session Storage**                      | 記憶體內範圍儲存（重設時清除）                                                                     |
| **IndexedDB → `GENERATOR_CACHE`**        | 已快取的 Generator 輸出                                                                   |
| **IndexedDB → `GENERATIVE_MEDIA_CACHE`** | 已快取的生成式媒體結果                                                                         |
| **IndexedDB → `DATA-<subspace>`**        | 各 Subspace 的 **Property Bank** 值（store 為 `properties`）；前綴為 `[persist]` 的列為已持續化的備份副本 |

<Note>
  `DATA-…` 資料庫存放的是執行階段 **Property Bank**，與 [BRICKS Controller](/zh-Hant/controller) 中的 [Data Bank](/zh-Hant/controller/data-bank) 儲存產品不同。同樣地，`GENERATIVE_MEDIA_CACHE` 是執行階段快取，而非 Media Box 或 Media Flow。
</Note>

Application 面板為**唯讀**：無法從 DevTools 編輯值，請改在應用程式中變更。物件值會隨應用程式執行即時更新，機密資訊則遮蔽為 `[HIDDEN]`。

## 下一步

<CardGroup cols={2}>
  <Card title="遠端除錯" icon="tower-broadcast" href="/zh-Hant/foundation/remote-debug">
    透過 BRICKS Controller 遠端除錯裝置，無需存取區域網路。
  </Card>

  <Card title="除錯面板" icon="bug" href="/zh-Hant/foundation/debug-panel">
    使用裝置端的疊加層來檢查運行時狀態。
  </Card>
</CardGroup>