---
title: "App 建造器與開發環境"
category: "app-development"
canonical: "https://www.ai-go.app/zh-TW/docs/guide/app-builder"
locale: "zh-TW"
last_updated: "2026-09-01"
source: "AI GO 開發者文件（https://www.ai-go.app）"
---

# App 建造器與開發環境

App 建造器（Builder）是 Custom App 的開發環境。它是一套完整的雲端 IDE——原始碼編輯、即時預覽、型別檢查、實際試跑、發布流程都在裡面。

**入口**：主控台「AI 應用程式 › App 建造器」，需要 `builder.access` 權限。

---

## Custom App 是什麼

一個 Custom App 是一個獨立運作的應用程式，有自己的原始碼、自己的專屬網址、自己的資料授權範圍與執行身分。

技術上它由兩部分組成：

- **前端**：React／TypeScript 程式碼，編譯後在平台的執行環境中載入。程式進入點為 `src/App.tsx`
- **後端 Action**：Python 程式碼，在隔離的伺服器環境執行，透過 `ctx` 物件存取平台能力

前端負責介面，Action 負責需要權限或需要保密的邏輯。兩者由平台的 SDK 串起來。

---

## 兩種存取模式

建立應用時要先決定存取模式，這決定了它的使用者從哪來：

| | Internal App | External App |
|---|---|---|
| 使用者 | 組織成員（同一組帳號） | 該應用自己的使用者系統 |
| 典型場景 | 內部報表、流程審核、部門工具 | 客戶入口、供應商協作、線上表單 |
| 使用者管理 | 由組織的成員管理統一處理 | Builder 內的「用戶」分頁 |
| 可用的 SDK | 全部，含使用者角色與簽核 | 不含 Internal 專屬的角色與簽核 SDK |
| 額外檔案 | — | `src/auth.ts`（登入註冊流程） |

除了這兩種，還有第三種形態：**Self-Built（自建）**——第三方系統不透過 Builder 開發，直接以 API Key 存取平台資料。詳見第 11 章。

---

## 起手式與應用商城

建立應用時可以選擇起手式：

- **從商城模板開始**：官方精選的應用範本，涵蓋常見業務場景，可直接安裝或在其基礎上修改
- **從空白開始**：只帶最小骨架

商城模板同時也是最好的學習素材——它們展示了 SDK 的實際用法。

---

## Builder IDE 的分頁

### 開發

原始碼編輯與即時預覽。

- **檔案總管**：以樹狀結構顯示應用的原始碼。修改會自動儲存，也可按 <kbd>Ctrl</kbd>+<kbd>S</kbd> 手動儲存
- **編輯器**：支援語法高亮；改動後預覽會即時刷新
- **AI 開發助手**：以自然語言描述需求，助手會直接編寫並插入程式碼；也可以選取一段程式碼請它修改、除錯或優化

AI 開發助手不只會寫程式碼，它握有一組**實際驗證**的工具（見下節），這是它與一般程式碼生成工具最大的差別。

### 引用

宣告這個應用要存取哪些 ERP 內建表、哪些欄位、什麼操作權限。這是資料授權的第一層（見第 10 章）。

引用面板內建**資料瀏覽器**，可以直接檢視被引用表的實際資料，不需要切到資料中心去對照欄位。

### 服務

伺服器端 Action 的管理面——建立、編輯、測試 Action，以及設定 App Secrets（API 金鑰等機密值）。

### 外部服務

管理這個應用可以呼叫哪些外部 API。平台採**網域白名單**制，未經授權的網域一律呼叫不到。這是應用程式對外通訊的唯一入口（見第 12 章）。

### Scope

宣告與檢視這個應用要用哪些平台能力群，以及目前的核可狀態。這是資料授權的第二層（見第 10 章）。

### 排程

設定這個應用的定時任務——讓 Action 在指定時間自動執行，不需要有人操作介面（見第 9 章）。此分頁恆常顯示；應用尚未發布時會說明前置條件。

### 發布

版本提交與上線。每次發布填寫版本號與更新日誌；依權限直接發布或送出申請等候審核（見第 10 章）。

### 用戶（僅 External App）

管理該應用的外部使用者——建立帳號、修改 Email、重設密碼。

---

## AI 開發助手的驗證工具

這是 Builder 與一般 AI 程式碼生成最大的差異：助手不只產生程式碼，它會**實際驗證**產出。

| 工具 | 做什麼 |
|---|---|
| 編譯檢查 | 送編譯管線驗證程式碼可以編譯 |
| 型別檢查 | 執行 TypeScript 型別檢查（`tsc --noEmit`） |
| Action 靜態檢查 | 偵測未定義的名稱、比對 `ctx` SDK 的方法是否存在、警告阻塞式寫法 |
| **實際試跑 Action** | 在開發環境**真的執行**一次 Action，看真實輸出而不是猜測 |
| 讀執行日誌 | 讀取 Action 的執行紀錄，據此自我修正 |
| 讀前端錯誤 | 讀取應用在使用者端發生的執行期錯誤 |
| 資料表工具 | 查詢與操作自建表結構 |
| 送出發布申請 | 代為提交發布 |

「實際試跑」值得特別注意：Action 在發布前就能真的跑一次，撞到的是真實的權限、真實的資料、真實的外部服務。這讓「編譯過了但一跑就爆」的情況大幅減少。

---

## 應用的檔案結構

```
src/
  App.tsx           ← 前端進入點
  api.ts            ← 自建表 SDK（平台提供）
  db.ts             ← ERP 表 SDK（平台提供）
  action.ts         ← 呼叫 Action 的 SDK（平台提供）
  approval.ts       ← 簽核 SDK（平台提供，Internal 專屬）
  user.ts           ← 使用者脈絡 SDK（平台提供，Internal 專屬）
  auth.ts           ← 登入註冊（平台提供，External 專屬）
actions/
  manifest.json     ← Action 清單與設定
  <action_name>.py  ← 各個 Action
  _shared/          ← Action 之間共用的程式碼
```

`src/` 底下的 SDK 檔案由平台提供並維護，**不需要也不應該修改**。它們是第 8 章的主題。

---

## 前端樣式注意事項

Custom App 的前端在隔離環境中載入，這帶來一個必須知道的限制：**CSS 變數的 `:root` 選擇器在該環境中不生效**。

規則很簡單——所有 CSS 變數定義一律使用雙選擇器：

```css
:host, :root {
  --primary-color: #2563eb;
}
```

只寫 `:root` 的樣式會在預覽正常、實際載入後失效。深色模式的變數定義同樣適用這條規則。

---

## 發布前的檢查

平台會在發布前主動偵測設定缺口，包含：

- 程式碼呼叫了外部服務，但該服務尚未授權（網域不在白名單中）
- Action 數量比上一版少（可能是誤刪），需要明確確認才能繼續

這些檢查會在發布當下阻擋並說明原因，而不是讓應用上線後才在使用者面前失敗。