本機除錯

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

預設啟用

在 BRICKS Foundation 2.25 及後續版本中，本機除錯預設為啟用：DevTools 伺服器會在開機時啟動，無需任何設定，並在區域網路上的連接埠 19851 進行接聽。若該連接埠已被使用，則會自動遞增至下一個可用的連接埠。若要檢視或變更這些控制項，請在裝置上開啟設定並導覽至進階設定區段：

啟用 Local Debugging 可整個開啟或關閉伺服器。將其關閉即可停止伺服器。
啟用 Chrome DevTools Protocol (CDP)、啟用 Model Context Protocol (MCP) 與啟用區域網路探索為子開關，全部預設為啟用。
密碼為選用項目，僅在您想要求以密碼存取時才需設定。

需要 BRICKS Foundation 2.25 或更新版本。在較舊的版本上，伺服器採用選擇性啟用方式，請在進階設定中手動啟用 Chrome DevTools。

探索裝置

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

bricks devtools scan

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

驗證

DevTools 存取權的範圍限定於裝置所屬的工作區。用戶端可使用工作區 token 或選用的裝置密碼進行驗證。

工作區 token

裝置所屬工作區的任何成員都可以使用 DevTools workspace token 連線，這是一種以 Ed25519 簽署的 token，與 Workspace API Token 不同。BRICKS CLI 與 CTOR Desktop 會自動取得並更新這些 token，因此已登入的工作區成員通常無需額外步驟即可連線。若要手動核發或更新 token，請執行：

bricks devtools issue-token

Token 的預設效期為 30 天。CLI 會依設定檔與工作區將 token 快取於 ~/.bricks-cli/config.json（絕不會印出），並持續重複使用直到接近到期，若請求傳回 403 則會自動重新核發。

選用的密碼

裝置也接受密碼，但僅在進階設定中明確設定時才有效（請參閱進階設定）。不再有預設密碼。作為升級時的單次移轉措施，若某裝置在升級至 2.25 之前已明確啟用本機除錯但未設定密碼，則會保留舊版的 BRICKS_DEVTOOLS 密碼，讓既有的存取方式仍可運作。用戶端可提供任一種憑證：透過 WebSocket 路徑 /ws/<credential>、以查詢參數，或針對 MCP 使用 Authorization: Bearer <token or passcode> 標頭。當兩者皆可用時，工作區 token 的優先順序高於密碼。

驗證狀態

bricks devtools scan 與 bricks devtools open 會為每個裝置顯示驗證狀態：

狀態	意義
`workspace-jwt`	可使用工作區 token 驗證
`passcode`	裝置已設定密碼
`locked`	需要憑證，但您的憑證皆無法使用
`open`	無需憑證（僅限較舊的 BRICKS Foundation 版本）

bricks devtools open --info 也會回報是否已啟用工作區驗證。

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 中繼資料端點，描述裝置、版本與協定

加上 --info 時，輸出內容也會包含適用憑證的授權詳細資訊。MCP 與 MCP SSE 端點接受 Authorization: Bearer <workspace token or passcode> 標頭。未加上 --info 時，指令會顯示伺服器識別資訊（名稱、版本、裝置 ID、工作區、協定與驗證狀態）。

開啟 DevTools 頁面

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

透過 Chrome 連線

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

在 Chrome 中開啟 chrome://inspect
您的裝置會出現在遠端目標清單中：/json 探索端點一律會提供，因此無需任何設定
點選檢查以開啟連線至正在執行應用程式的 DevTools 視窗

若裝置設有密碼，請在進階設定中啟用向 chrome://inspect 公開密碼，讓 Chrome 無需提示即可連線。

向 chrome://inspect 公開密碼會以明碼形式將設定的密碼嵌入公開的 /json URL 中。請僅在信任的網路上用於除錯。

透過 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>

已登入的工作區成員無需額外旗標：CLI 會自動取得工作區 token。僅在連線至您並非其工作區成員的密碼保護裝置時，才需使用 --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]。

概覽

指南

參考

更新日誌

預設啟用

探索裝置

驗證

工作區 token

選用的密碼

驗證狀態

DevTools 端點

開啟 DevTools 頁面

透過 Chrome 連線

透過 BRICKS CLI 檢視（CDP）

使用 DevTools 可以做什麼

Elements—Brick 樹狀結構

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

Network—請求流量

Application—已儲存的 Data（唯讀）

下一步

遠端除錯

除錯面板

​預設啟用

​探索裝置

​驗證

​工作區 token

​選用的密碼

​驗證狀態

​DevTools 端點

​開啟 DevTools 頁面

​透過 Chrome 連線

​透過 BRICKS CLI 檢視（CDP）

​使用 DevTools 可以做什麼

​Elements—Brick 樹狀結構

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

​Network—請求流量

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

​下一步

遠端除錯

除錯面板

預設啟用

探索裝置

驗證

工作區 token

選用的密碼

驗證狀態

DevTools 端點

開啟 DevTools 頁面

透過 Chrome 連線

透過 BRICKS CLI 檢視（CDP）

使用 DevTools 可以做什麼

Elements—Brick 樹狀結構

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

Network—請求流量

Application—已儲存的 Data（唯讀）

下一步