本機除錯

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

在裝置上啟用 DevTools

開啟進階設定

在裝置上開啟設定，並導覽至進階設定區段。

啟用 Chrome DevTools

開啟 Chrome DevTools。裝置會在區域網路上的連接埠 19851 啟動 DevTools 伺服器。若該連接埠已被使用，則會自動遞增至下一個可用的連接埠。

探索裝置

使用 BRICKS CLI 掃描區域網路中已啟用 DevTools 的裝置：

bricks devtools scan

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

DevTools 端點

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

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 連線：

在進階設定中啟用 Expose endpoints for chrome://inspect
在 Chrome 中開啟 chrome://inspect
您的裝置會出現在遠端目標清單中
點選檢查以開啟連線至正在執行應用程式的 DevTools 視窗

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

透過 BRICKS CLI 檢視（CDP）

需要 BRICKS Foundation 2.24 或更新版本。

BRICKS CLI 提供 CDP 指令，可直接從終端機檢視裝置，無需開啟瀏覽器：

# 列印 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 指令參考。

使用 DevTools 可以做什麼

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

Elements—Brick 樹狀結構

DevTools Elements 面板，顯示投射為 DOM 文件的 BRICKS 渲染樹

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

#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

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

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

DevTools Console 面板，顯示連線橫幅與展開的 system 輔助物件

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)`	追蹤事件的串接方式

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)                    // 開啟裝置端的記錄面板

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

Network—請求流量

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} 呈現，接收到的訊息則以傳入訊框呈現。

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

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

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

Application—已儲存的 Data（唯讀）

DevTools Application 面板，顯示投射至 IndexedDB 的 BRICKS 儲存

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]` 的列為已持續化的備份副本

DATA-… 資料庫存放的是執行階段 Property Bank，與 BRICKS Controller 中的 Data Bank 儲存產品不同。同樣地，GENERATIVE_MEDIA_CACHE 是執行階段快取，而非 Media Box 或 Media Flow。

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

在裝置上啟用 DevTools

探索裝置

DevTools 端點

開啟 DevTools 頁面

透過 Chrome 連線

透過 BRICKS CLI 檢視（CDP）

使用 DevTools 可以做什麼

Elements—Brick 樹狀結構

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

Network—請求流量

Application—已儲存的 Data（唯讀）

下一步

遠端除錯

除錯面板

​在裝置上啟用 DevTools

​探索裝置

​DevTools 端點

​開啟 DevTools 頁面

​透過 Chrome 連線

​透過 BRICKS CLI 檢視（CDP）

​使用 DevTools 可以做什麼

​Elements—Brick 樹狀結構

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

​Network—請求流量

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

​下一步

遠端除錯

除錯面板

在裝置上啟用 DevTools

探索裝置

DevTools 端點

開啟 DevTools 頁面

透過 Chrome 連線

透過 BRICKS CLI 檢視（CDP）

使用 DevTools 可以做什麼

Elements—Brick 樹狀結構

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

Network—請求流量

Application—已儲存的 Data（唯讀）

下一步