快速开始

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

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

前提条件

开始前请确认：

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

注意

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

安装 SuccApp CLI

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

npm install -g @succsoft/succapp

安装后确认命令可用：

succapp --version
succapp --help

更多信息见SuccApp CLI。

可选安装 SuccApp for VS Code

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

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

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

更多图形化入口见SuccApp for VS Code。

初始化工作区

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

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 协作入口文件。更多说明见初始化工作区。

克隆项目

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

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

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

更多说明见连接服务器与克隆项目。

让 AI 先理解再修改

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

可以先这样要求 AI：

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

确认范围后再允许修改：

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

完整流程见使用 AI 修改元数据。

查看变化和差异

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

succapp workspace status

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

succapp workspace status --json

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

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

推送测试并预览

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

succapp workspace push

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

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

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

如果推送被远端变化阻止，先查看差异或拉取服务器变化，不要直接强制覆盖。更多说明见修改、对比、拉取与推送和冲突处理。

提交 Git

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

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

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