建立 App

建立筆記本或自訂應用程式、使用 AI App 建置器，並設定 App 的啟動方式、可存取的資源，以及建置器可參考的知識

本頁說明如何建立兩種 App，以及建置時需要設定的所有項目：App 建置器對話、啟動指令與連接埠、沙箱環境、Harness 與連線保險庫、連結的知識庫、來源與 Skill。

建置與設定自訂應用程式需要工作區的 建構者 或 管理員 角色。任何成員都可以建立筆記本。

​

建立筆記本

1. 開啟筆記本頁面

   前往 應用程式，選擇 筆記本。

2. 點選新增筆記本

   填寫對話框：

   • 標題：顯示名稱，例如 銷售分析。
   • 名稱：筆記本在共用資料夾中的檔名，也是 Agent 使用的參照（app:<name>）。只能使用小寫英文字母、數字、連字號與底線，最多 64 個字元，建立後無法更改。
   • 說明（選填）：這個筆記本的用途。
   • Sandbox 環境：筆記本核心啟動時使用的映像檔。只能選擇已建置筆記本映像檔的環境；工作區預設 會使用工作區的標準映像檔。
3. 點選建立

   筆記本建立後會立即啟動，並在 marimo 編輯器中開啟。新增儲存格、執行它們，檔案會儲存在工作區共用的筆記本資料夾中。

你也可以在對話中請 Agent 建立，例如「建立一個筆記本，畫出每週註冊數」。Agent 會使用 create_notebook 工具，並把結果開在對話旁。

​

建立自訂應用程式

1. 開啟自訂應用程式頁面

   前往 應用程式，選擇 自訂應用程式，再點選 新增應用程式。

2. 選擇 App 類型

   • 一般 App：提供使用者介面，依需求加入 API。
   • MCP App：提供使用者介面與 Agent 可呼叫的工具。
3. 描述 App

   寫下這個 App 給誰用、要做什麼，或從 從一個想法開始 底下的範例開始（數據儀表板、內部工具、客戶入口）。展開 應用程式名稱（選填） 可以自行設定標題與名稱；否則會依標題自動產生名稱。

4. 開始建立

   開始建立 會開啟 App 建置器，並把你的描述當作第一則訊息送出。略過，前往設定 會直接開啟建置器的 設定 分頁，不會開始對話。

​

匯入既有資料夾

已經有程式碼了嗎？在 自訂應用程式 頁面點選 匯入資料夾，從電腦選擇一個資料夾，並設定 標題 與 名稱。檔案會以草稿形式進入建置器；在你儲存版本並發布之前，不會有任何內容上線。

在資料夾最上層放一個 datagen.app.json，即可宣告 App 的啟動方式（請參閱下方的「App 的啟動方式」）。沒有這個檔案的資料夾仍可匯入，但在 manifest 存在之前無法儲存或發布。建置器 Agent 可以讀取程式碼並幫你寫出這個檔案。

​

App 建置器

App 建置器位於 /signalgen/apps/<appId>/build。在 App 詳情頁點選 開啟建置器，或在檢視 App 時點選 編輯 即可進入。

欄位	分頁	用途
左欄	對話、設定、版本	過去的建置器對話、App 設定，以及已儲存的版本
中欄	對話 與開啟的檔案	與建置器對話；AI 正在撰寫的檔案會以分頁形式開在對話旁
右欄	UI、API、工具、檔案	草稿的即時預覽、App 探索到的 API 與 MCP 工具，以及草稿的檔案樹

​

用對話建置

描述你要的變更，或詢問 App 的檔案內容，例如「新增一個列出未結請求的頁面」、「為什麼圖表沒有資料？」。建置器會在自己的建置用沙盒中編輯 App 的 草稿。在你發布之前，這裡的任何操作都不會影響執行中的 App。

• 新對話 針對同一個 App 開始新的對話。
• 重新載入 重新整理預覽頁面；重啟 會停止並重新啟動 App 程序，變更指令、連接埠或相依套件後需要這麼做。
• 重啟 sandbox 會重新建立建置用沙盒，草稿會保留。
• 捨棄 會把所有未儲存的檔案還原為最新的已儲存版本。還原 則只針對單一檔案。
• 在 API 與 工具 分頁中，新增 與 更新 會在對話中準備一段描述介面變更的提示；確認後再送出。

一次只有一個人能編輯 App。如果其他人正在使用建置器，標頭會顯示是誰在編輯。點選 接手 後，你的下一個變更就會生效；對方正在進行的回合仍會完成。

​

App 的啟動方式

自訂應用程式的啟動設定放在 App 檔案根目錄的 datagen.app.json 中。設定 裡的 啟動方式 區塊以唯讀方式顯示目前的值；編輯這個檔案（或請建置器對話代為編輯），設定就會跟著改變。

datagen.app.json

{
  "command": "python app.py",
  "port": 8080,
  "envVars": {
    "APP_MODE": "production"
  }
}

欄位	說明
command	只放啟動指令。相依套件會在儲存版本時安裝，所以不要加上 npm install && 之類的指令。自訂應用程式不能用 marimo 當作指令；請改為建立筆記本。
port	App 在 0.0.0.0 上監聽的連接埠，範圍 1024 到 65535。這個值也會以 $PORT 匯出。變更後會重新建立沙盒。
cwd	選填的工作目錄，必須是 App 自己資料夾內的絕對路徑。預設為 App 的資料夾。
envVars	一般、非機密的設定，格式為 {"NAME": "value"}。名稱只能使用大寫英文字母、數字與底線。機密請放在連線保險庫。
install	選填的安裝指令，用來取代依相依套件檔案偵測出的安裝指令。
build / artifacts	選填的建置步驟，以及它產生的路徑（例如 ".next"）。兩者必須同時宣告或同時省略；建置產物會一併建進該版本的映像檔。
dev	選填，只用於建置器預覽的指令，適合直接從原始碼提供服務的開發伺服器。已發布的 App 不會使用它。

如果沒有這個檔案，建置器會依檔案偵測可能的啟動指令（package.json 中的 start 或 dev 腳本、根目錄的進入點檔案，或靜態的 index.html），點選 建立 datagen.app.json 或 請 agent 設定 即可寫出 manifest。

datagen.app.json 不能綁定機密。像 secrets 這類鍵會被拒絕。請改在 設定 中綁定憑證，方式如下所述。

​

相依套件

在 package.json、package-lock.json、requirements.txt、pyproject.toml 或 uv.lock 中宣告的相依套件，會在每次儲存版本時安裝進該版本的映像檔。開啟映像檔仍在建置中的 App 時，會顯示 正在安裝相依套件，直到完成為止。

​

設定

建置器的 設定 分頁（以及 App 詳情頁的 設定 分頁）包含 manifest 以外的所有設定。未設定的項目會使用工作區預設值。

設定	控制的內容
名稱	App 的資料夾與 app:<name> 參照。建立後無法更改。
標題、說明	顯示在應用程式頁面與詳情頁。
執行環境	建置器對話所使用的 Harness（執行環境與模型）。請參閱 Harness。
連線保險庫	執行中的 App 以環境變數取得的憑證。使用的是每位成員自己的值，所以個人憑證只屬於該成員。選擇 不使用憑證庫 時，App 不會取得任何憑證。請參閱 連線保險庫。
DataGen MCP	讓建置器對話在撰寫 App 時可以呼叫 DataGen 工具。已發布的 App 永遠不會取得這些工具。
工具套件	建置器對話可以呼叫哪些工具。只在 DataGen MCP 開啟時有效。
沙箱	App 啟動時使用的沙箱環境。變更後，系統會先在新環境上重新建置自訂應用程式的相依套件映像檔，再重新建立沙盒。請參閱 沙箱環境。
保險庫	App 程序以環境變數取得的工作區機密。App 上只存放機密的名稱，值仍保留在保險庫中。變更後需重啟沙盒，執行中的 App 才會套用。

連接埠與沙箱環境在 App 的沙盒啟動時就已固定。在詳情頁變更這兩項後，請停止 App 再重新開啟。

​

為建置器提供知識與 Skill

​

連結知識庫

在 設定 > 知識庫（或詳情頁的 工具與知識 分頁）點選 連結知識庫，並選擇一個已發布的知識庫。連結的知識庫會以唯讀方式掛載到建置器的沙盒中，作為撰寫 App 的背景資料。已發布的 App 不會讀取它們。

知識庫的建立與連結方式請參閱 使用知識庫。

​

安裝 Skill

在詳情頁的 工具與知識 分頁中，技能 區塊會列出工作區已審核通過的 Skill。點選 安裝 即可讓建置器使用。已安裝的 Skill 只存在於建置器的沙盒中；它們是建置 App 的工具，永遠不會成為已發布版本的一部分。當登錄中有更新的已審核版本時，該列會顯示 有可用更新。

上傳與審核 Skill 的方式請參閱 Skills。

在啟用資產層（assets layer）的部署環境中，工具與知識 還會列出 執行中的 App 可以用開啟者身分讀取的知識庫與分析模型。選擇一項並點選 連結 即可。

​

為執行中的 App 提供資料

​

來源：工作區檔案

詳情頁的 來源 分頁用來選擇 App 可以讀取的工作區檔案。選取的檔案會在 App 的沙盒啟動時複製到 App 的 .sources/ 資料夾，App 也可以透過 Files API 讀取它們。來源不屬於已發布的版本，所以執行中的 App 永遠看到的是目前的檔案。

檔案變更後，重新複製來源 會把檔案重新複製到執行中的 App，但不會重新啟動 App。只在啟動時載入資料的程序，會沿用舊的副本，直到你停止並重新開啟 App。

上傳檔案到工作區的方式請參閱 檔案。

​

資料庫

若要從 App 的程式碼查詢資料庫，請把唯讀憑證存進連線保險庫，在 設定 中選擇該金庫，再從環境變數讀取連線資訊。做法與 Agent 相同；請參閱 從程式碼查詢。

​

下一步

發布與分享

儲存版本、發布，並控管誰可以開啟 App。

教學：發布一個 App

用 Demo 資料從頭到尾做出一個 marimo 儀表板。