> ## 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 專案

## 前置需求

* [Bun](https://bun.sh) v1.3 或更新版本
* [Git](https://git-scm.com)（強烈建議）
* 一個 [BRICKS](https://bricks.tools) 工作區帳號

## 建立專案

取得 bricks-ctor 專案有三種方式。

### 選項 1：BRICKS Controller（建議）

從 [BRICKS Controller](/zh-Hant/controller/applications) 網頁介面產生專案：

1. 在 BRICKS Controller 中開啟您的應用程式
2. 點擊 **Generate Project**
3. 設定選項：
   * **AGENTS.md** —AI 代理指令（適用於 Claude Code、Codex 等）
   * **CLAUDE.md** —Claude Code 專用指令
   * **GEMINI.md** —Gemini CLI 指令
   * **GitHub Actions** —CI/CD 部署工作流程
4. 點擊 **Download Project (.zip)**

請參閱 [BRICKS Controller 文件](/zh-Hant/controller)，了解工作區設定、Foundation 綁定與應用程式管理。

解壓縮後執行：

```bash theme={null}
cd my-app
bun install
```

### 選項 2：CLI

安裝 BRICKS CLI 並從指令列初始化：

```bash theme={null}
bun add -g @fugood/bricks-cli
bricks auth login
bricks app project-init <application-id> --yes
```

`project-init` 指令會產生專案檔案並安裝相依套件。您可以使用旗標自訂輸出：

| 旗標                    | 說明                     |
| --------------------- | ---------------------- |
| `--no-agents`         | 略過 AGENTS.md 的產生       |
| `--no-claude`         | 略過 CLAUDE.md 的產生       |
| `--gemini`            | 包含 GEMINI.md           |
| `--no-github-actions` | 略過 GitHub Actions 工作流程 |

### 選項 3：CTOR

使用 [CTOR](/zh-Hant/ctor) —一個內建 AI 代理的桌面 IDE，可透過對話建立、編輯和部署專案。

## 開發工作流程

### 編譯

對您的 TypeScript 檢查並編譯成 BRICKS 執行環境所需的 JSON 設定：

```bash theme={null}
bun compile
```

### 預覽

啟動本機預覽以測試您的應用程式：

```bash theme={null}
bun preview
```

預覽會在本機視窗中開啟您的應用程式。使用 `--show-menu` 可取得額外的測試選項。

### 部署

將已編譯的應用程式部署至 [BRICKS](https://bricks.tools) 伺服器：

```bash theme={null}
bun deploy-app
```

| 旗標                         | 說明            |
| -------------------------- | ------------- |
| `--changelogs <text>`      | 版本的更新記錄文字     |
| `--changelogs-file <path>` | 從檔案讀取更新記錄     |
| `--auto-commit`            | 部署前自動提交未暫存的變更 |
| `--auto-version`           | 部署前自動升級修訂版本號碼 |
| `--version <version>`      | 為版本設定明確的版本號碼  |
| `-y, --yes`                | 略過所有確認提示      |

版本解析優先順序：`--version` 旗標 > `--auto-version` 升版 > `package.json` 版本。`--version` 與 `--auto-version` 都會在部署前更新 `package.json`。

<Warning>
  部署需要乾淨的 Git 工作目錄。請在部署前提交您的變更，或使用 `--auto-commit` 自動提交。
</Warning>

### 拉取

從伺服器拉取最新版本的應用程式：

```bash theme={null}
bun pull-app
```

此指令會將您的本機專案與伺服器版本同步。使用 `--force` 可覆蓋本機變更。

## AI 輔助開發

bricks-ctor 的設計與 AI 編碼代理協同運作。當您在啟用 AI 指令的情況下產生專案時，會建立以下檔案：

| 檔案          | 使用者              |
| ----------- | ---------------- |
| `CLAUDE.md` | Claude Code、CTOR |
| `AGENTS.md` | Codex CLI、其他代理   |
| `GEMINI.md` | Gemini CLI       |

這些檔案包含專案專屬指令、架構模式，以及協助 AI 代理理解和修改應用程式的 BRICKS 領域知識。

專案中也包含[內建 MCP server](/zh-Hant/ctor-pkg/mcp-server) 和[內建 skill](/zh-Hant/ctor-pkg/skills)，為 AI 代理提供工具與領域知識。

<Tip>
  使用 [CTOR](/zh-Hant/ctor) 可享有完整整合體驗，包含 AI 代理對話、部署和預覽——全在同一個應用程式中。
</Tip>

## 使用 GitHub Actions 進行 CI/CD

若您在產生專案時啟用了 GitHub Actions，您的儲存庫中會包含自動部署的工作流程。推送至主分支即可觸發部署。