AI GO使用教學

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

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

起手式與應用商城

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

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

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

Builder IDE 的分頁

開發

原始碼編輯與即時預覽。

  • 檔案總管：以樹狀結構顯示應用的原始碼。修改會自動儲存，也可按 Ctrl+S 手動儲存
  • 編輯器：支援語法高亮；改動後預覽會即時刷新
  • 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 變數定義一律使用雙選擇器：

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

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

發布前的檢查

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

  • 程式碼呼叫了外部服務，但該服務尚未授權或金鑰未設定
  • Action 數量比上一版少（可能是誤刪），需要明確確認才能繼續

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