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

> 以程式碼建置 BRICKS 應用的 TypeScript SDK

**bricks-ctor** 是一套 TypeScript SDK，讓您完全以程式碼的方式定義、建置與部署 [BRICKS](https://bricks.tools) 應用。相較於使用視覺化編輯器，您可以撰寫 TypeScript，並將其編譯為 BRICKS 運行時可理解的設定。

<Info>
  bricks-ctor 目前為**預覽版**。API 與工具可能會有所調整。
</Info>

## 為什麼選擇程式碼？

* **型別安全** —透過完整的 TypeScript 支援，在編譯時期即可攔截錯誤
* **版本控管** —以 Git 追蹤變更、審閱差異、協同合作
* **AI 輔助開發** —與可讀寫專案檔案的 AI 程式設計代理共同開發
* **自動化** —透過 CLI 或 GitHub Actions 等 CI/CD 管線進行部署

## 核心概念

一個 BRICKS 應用是由可組合的實體所構成的樹狀結構，架構如下：

```
Application
└── Subspace(功能/畫面容器)
    ├── Canvas(檢視/場景版面)
    │   └── Items(Brick 或 Subspace 參照的定位元素)
    ├── Brick(UI 元件)
    ├── Generator(資料/IO 提供者)
    ├── Data(狀態儲存)
    ├── Animation(視覺效果)
    └── Data Calculation(資料轉換)
```

### Subspaces

Subspace 是獨立的功能單元，您可以將其視為一個畫面或功能模組。每個 subspace 擁有自己的 brick、generator、data、canvas 與 animation。應用程式會以 `rootSubspace` 作為進入點。

### Canvases

Canvas 定義檢視版面。它會在格線上以 `frame` 座標(x、y、寬、高）放置項目(brick 或 subspace 參照）。Canvas 支援生命週期事件(`firstEnter`、`enter`、`exit`)，並可在彼此之間切換以進行導覽。

### Bricks

Brick 是視覺上的建構單位—負責顯示內容並處理互動的 UI 元件。常見範例包含：

| Brick               | 用途                                       |
| ------------------- | ---------------------------------------- |
| **Text**            | 顯示文字並套用樣式                                |
| **TextInput**       | 可編輯的文字欄位                                 |
| **RichText**        | 支援 HTML 內容、多種字型與內嵌圖片的 Rich Text          |
| **Image**           | 顯示圖片                                     |
| **Video**           | 影片播放                                     |
| **VideoStreaming**  | RTSP / RTMP 即時影像串流                       |
| **WebrtcStream**    | WebRTC 影音串流                              |
| **GenerativeMedia** | 由 AI 生成的圖片與影片                            |
| **WebView**         | 內嵌網頁內容                                   |
| **Lottie**          | `.json` 與 `.dotlottie` 動畫，支援速度、循環與影格範圍控制 |
| **Rive**            | `.riv` 動畫，支援狀態機輸入、文字取代與 artboard 切換      |
| **Svg**             | SVG 向量圖形                                 |
| **Chart**           | 資料視覺化                                    |
| **Icon**            | FontAwesome 6 Pro 圖示                     |
| **QrCode**          | QR code 顯示                               |
| **Camera**          | 相機即時畫面                                   |
| **Maps**            | 地圖顯示                                     |
| **Rect**            | 具備背景、邊框、陰影的容器                            |
| **Items**           | 以陣列資料驅動的列表或網格                            |
| **Slideshow**       | 具轉場效果的自動切換幻燈片                            |

Brick 可套用樣式、動畫、回應按壓事件，並可將屬性動態繫結至資料。

### Generators

Generator 負責所有外部 I/O 與資料處理，將應用連線到 API、資料庫、硬體、AI 模型等。每個 generator 擁有**輸出埠**(outlet，資料輸出通道）連線至 data，並透過**事件**觸發動作。

Generator 的類別包含：

| 類別           | 範例                                                               |
| ------------ | ---------------------------------------------------------------- |
| **AI & LLM** | Assistant、LLM (GGML/OpenAI/Anthropic/ONNX)、Vector Store、Reranker |
| **語音**       | Text-to-Speech、Speech-to-Text、VAD、即時語音辨識                         |
| **網路**       | HTTP、WebSocket、GraphQL、MQTT、TCP、UDP、HTTP Server                  |
| **儲存**       | File、SQLite、Data Bank、Media Flow                                 |
| **硬體**       | 藍牙 LE、序列埠、相機、鍵盤                                                  |
| **控制流**      | Tick(計時）、Alarm Clock、Step、Iterator、Watchdog                      |
| **其他**       | WebRTC、Web Crawler、MCP、熱感印表機                                     |

### Data

Data 節點儲存應用狀態。它們具型別(string、number、boolean、array、object)，並可**連結**至 brick 或 generator 的屬性以取得反應式更新。當 generator 的 outlet 輸出值時，所連結的 data 會更新，綁定至該 data 的 brick 也會自動重新渲染。

### Data Calculations

Data calculation 是 JavaScript 函式，用於轉換資料。它們在沙箱環境中執行，並提供 25 個以上內建函式庫(lodash、moment、crypto 等）。適合用於格式化、解析或計算衍生值。

### Actions 與 Events

Action 是由事件觸發的指令。Brick 與 generator 會發出事件(press、response、error、計時器觸發)，您可將其接線至 action，例如切換 canvas、更新 data、觸發 generator 或執行動畫。

## 專案結構

bricks-ctor 專案的結構如下：

```
my-app/
├── application.json              # 應用後設資料(名稱、ID、階段)
├── package.json
├── tsconfig.json
├── app.ts                        # 應用程式進入點
├── root.ts                       # 根 subspace 定義
├── subspaces/
│   └── subspace-0/
│       ├── index.ts              # Subspace 匯出
│       ├── bricks.ts             # Brick 定義
│       ├── canvases.ts           # Canvas 版面
│       ├── generators.ts         # Generator 設定
│       ├── data.ts               # Data 定義
│       ├── animations.ts         # Animation 設定
│       └── data-calc/            # Data calculation 腳本
│           └── index.ts
├── automation-tests/             # E2E 測試定義
├── CLAUDE.md / AGENTS.md         # AI 代理指示(選用)
└── .mcp.json                     # MCP 伺服器設定(自動產生)
```

所有應用邏輯皆以 TypeScript 檔案定義。執行 `bun compile` 會將其轉換為 BRICKS 運行時執行所需的 JSON 設定。

## 下一步

<Card title="開始使用" icon="rocket" href="/zh-Hant/ctor-pkg/getting-started">
  設定您的開發環境並建立第一個 BRICKS 專案。
</Card>