---
title: 快速开始
order: 2
navTitle: 快速开始
---
# 快速开始

本文帮助你快速跑通一次 AI 低代码开发闭环：安装工具、初始化 SuccApp 工作区、连接测试服务器、克隆项目、让 AI 做一个小修改、检查差异、推送测试环境并提交 Git。

预计用时 20 到 30 分钟。完成后，你应能得到一个可重复使用的 SuccApp 工作区、一个已克隆的测试项目、一处经过 AI 辅助修改的元数据变更，以及一次可审查的 Git 提交。

## 前提条件{#requirements}

开始前请确认：

1. 有一个可以访问的 SuccApp 测试服务器。
2. 有可以在浏览器中登录该服务器的账号；脚本、CI 或无浏览器环境如需登录，可提前准备 Personal Access Token（PAT）。
3. 已准备一个本地目录作为 SuccApp 工作区。
4. 已安装 Node.js 和 npm，用于安装 SuccApp CLI。
5. 如需图形化检查，已安装 VS Code 和 SuccApp for VS Code。

::: warning 注意
第一次练习建议连接测试环境，不要直接连接生产环境。
:::

## 安装 SuccApp CLI{#install-cli}

SuccApp CLI 已发布到 npm。可以使用 npm 全局安装，安装后本机可直接执行 `succapp` 命令。

```bash
npm install -g @succsoft/succapp
```

安装后确认命令可用：

```bash
succapp --version
succapp --help
```

更多信息见[SuccApp CLI](./basics/cli.md)。

## 可选安装 SuccApp for VS Code{#install-vscode}

如果需要可视化查看服务器项目、Changes、diff 和文件历史，建议安装 SuccApp for VS Code。

在线安装时，在 VS Code 扩展视图搜索 `SuccApp` 并安装。离线环境可以使用与当前 SuccApp 版本匹配的 `.vsix` 安装包：

```bash
code --install-extension succapp-for-vscode-版本号.vsix
```

更多图形化入口见[SuccApp for VS Code](./basics/vscode.md)。

## 初始化工作区{#init-workspace}

选择一个空目录或团队 Git 仓库作为工作区：

```bash
mkdir customer-a-bi-workspace
cd customer-a-bi-workspace
succapp auth login http://localhost:8080
succapp workspace init --server http://localhost:8080
```

`auth login` 默认会打开浏览器完成 OAuth2 授权。如果当前环境无法打开浏览器，可以改用 `succapp auth login --pat http://localhost:8080`，并按提示输入服务器签发的 PAT。

`workspace init` 会初始化 `.succapp/config.json`，并补齐推荐工作区设置、编辑器结构提示、TypeScript 诊断、Git 忽略规则和 AI 协作入口文件。更多说明见[初始化工作区](./workspace/init-workspace.md)。

## 克隆项目{#clone-project}

查看服务器项目并克隆当前任务需要的项目：

```bash
succapp server project list
succapp workspace project clone DEMO
succapp workspace status
```

在 VS Code 中也可以通过 SuccApp 服务器视图克隆项目。

![服务器连接成功后的项目列表](./images/quick-start-server-projects.png)

更多说明见[连接服务器与克隆项目](./workspace/connect-and-clone.md)。

## 让 AI 先理解再修改{#ai-edit}

第一次练习建议选择影响范围小、容易验证的修改，例如页面标题、说明文字、按钮文案或测试脚本中的一行日志。

可以先这样要求 AI：

```text
请在当前 SuccApp 工作区中查找客户明细页面相关的元数据文件。
先不要修改，请说明候选文件、判断依据和可能影响范围。
```

确认范围后再允许修改：

```text
请只修改客户明细页面标题，把“客户详情”改为“客户信息详情”。
不要修改字段名、资源 ID、权限、流程和脚本逻辑。修改后请列出变更文件。
```

完整流程见[使用 AI 修改元数据](./task-driven.md)。

## 查看变化和差异{#check-diff}

修改后先查看工作区状态：

```bash
succapp workspace status
```

需要给 AI 或脚本读取时使用结构化输出：

```bash
succapp workspace status --json
```

在 SuccApp for VS Code 中，可以打开 **变化** 视图并逐个文件查看 diff。

![查看本地文件和服务器版本差异](./images/quick-start-diff-view.png)

推送前确认变化列表里只包含本次需要的文件，没有误删、误改或大范围格式化。`.meta` 文件由 SuccApp 自动维护和修复，但出现大量无关 `.meta` 变化时仍要检查原因。

## 推送测试并预览{#push-preview}

确认差异无误后，推送到测试服务器：

```bash
succapp workspace push
```

如果只想定位当前文件对应的浏览器地址，可以使用：

```bash
succapp workspace file resolve path/to/file.spg
succapp workspace file open path/to/file.spg
```

在 VS Code 中也可以通过 **变化** 视图推送，并选择 **打开服务器视图** 或 **打开服务器编辑页**。

![变化视图中的文件操作按钮](./images/quick-start-changes-view.png)

如果推送被远端变化阻止，先查看差异或拉取服务器变化，不要直接强制覆盖。更多说明见[修改、对比、拉取与推送](./workspace/sync-changes.md)和[冲突处理](./troubleshoot/conflict-handling.md)。

## 提交 Git{#commit}

测试通过后，将本地修改提交到 Git：

```bash
git status
git diff
git add path/to/changed-file
git commit -m "调整客户明细页面标题"
```

提交前确认 `.succapp/remote/`、`.succapp/cache/`、`.succapp/locks/`、日志、临时文件和未确认的 AI 草稿没有进入 Git。更多说明见[工作区版本管理](./workspace/git-versioning.md)。