> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 建立 App

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

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

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

## 建立筆記本

<Steps>
  <Step title="開啟筆記本頁面">
    前往 **應用程式**，選擇 **筆記本**。
  </Step>

  <Step title="點選新增筆記本">
    填寫對話框：

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

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

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

<Frame>
  <img src="https://mintcdn.com/datagen/rusBmwP8bd_Srmdm/images/browser-guide/zh/new-notebook.jpg?fit=max&auto=format&n=rusBmwP8bd_Srmdm&q=85&s=8b8eca995caaece99a9248acf6c11e87" alt="新增筆記本：標題、名稱、說明與 Sandbox 環境" width="838" height="863" data-path="images/browser-guide/zh/new-notebook.jpg" />
</Frame>

## 建立自訂應用程式

<Steps>
  <Step title="開啟自訂應用程式頁面">
    前往 **應用程式**，選擇 **自訂應用程式**，再點選 **新增應用程式**。
  </Step>

  <Step title="選擇 App 類型">
    * **一般 App**：提供使用者介面，依需求加入 API。
    * **MCP App**：提供使用者介面與 Agent 可呼叫的工具。
  </Step>

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

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

### 匯入既有資料夾

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

在資料夾最上層放一個 `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** 與 **工具** 分頁中，**新增** 與 **更新** 會在對話中準備一段描述介面變更的提示；確認後再送出。

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

## App 的啟動方式

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

```json datagen.app.json theme={null}
{
  "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。

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

### 相依套件

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

## 設定

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

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

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

## 為建置器提供知識與 Skill

### 連結知識庫

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

知識庫的建立與連結方式請參閱 [使用知識庫](/zh/context/use)。

### 安裝 Skill

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

上傳與審核 Skill 的方式請參閱 [Skills](/zh/context/skills)。

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

## 為執行中的 App 提供資料

### 來源：工作區檔案

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

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

上傳檔案到工作區的方式請參閱 [檔案](/zh/files/overview)。

### 資料庫

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

## 下一步

<CardGroup cols={2}>
  <Card title="發布與分享" icon="share-nodes" href="/zh/apps/publish-and-share">
    儲存版本、發布，並控管誰可以開啟 App。
  </Card>

  <Card title="教學：發布一個 App" icon="graduation-cap" href="/zh/tutorial/05-ship-an-app">
    用 Demo 資料從頭到尾做出一個 marimo 儀表板。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.