主题
连接服务器与克隆项目
本文介绍 SuccApp 中服务器和项目的日常操作，包括添加服务器、登录服务器、使用服务器、设置服务器地址、浏览远端文件、克隆项目、重置项目和移除本地项目。AI 修改元数据前，应先连接测试服务器并把目标项目克隆到本地工作区。
第一次准备本地目录、Git 和推荐工作区设置时，请先阅读初始化工作区。
基本概念
服务器
服务器是一个 SuccApp 环境，可以是测试环境、预发布环境或生产环境。SuccApp 通过服务器地址访问项目、文件、历史版本和设计器页面。
活跃服务器
一个工作区可以保存多个服务器地址，但同一时间会有一个活跃服务器。同步、克隆、推送和拉取默认针对当前活跃服务器执行。
项目
项目是服务器上的顶层元数据目录。克隆项目后，工作区中会出现对应目录，目录中的文件可以本地编辑、对比、推送和提交 Git。
添加服务器
打开命令面板（Windows / Linux：Ctrl+Shift+P；macOS：Cmd+Shift+P），执行 SuccApp: 添加服务器（英文界面为 SuccApp: Add Server），输入服务器地址。例如：
text
http://localhost:8080地址输入后，SuccApp 会先检查服务器地址是否可访问。地址检查通过后，SuccApp 会把服务器保存到当前工作区的 .succapp/config.json，并要求登录。登录成功后，该服务器会成为当前活跃服务器。
如果当前工作区还没有克隆过项目，登录成功提示中会提供 克隆项目（英文界面为 Clone Projects）按钮。点击后可以继续选择远端项目并克隆到本地。
如果添加的是已有服务器，SuccApp 会提示服务器已存在。此时可以使用服务器或登录服务器。
登录服务器
添加服务器时会自动进入登录流程。默认方式是 OAuth2 浏览器授权；脚本、CI、远程终端或无浏览器环境可以选择使用服务器签发的 PAT。登录成功后，SuccApp 会保存本机认证状态，后续打开工作区时会尝试自动恢复连接。
如果 OAuth2 授权失效、PAT 被撤销或服务器要求重新授权，执行 SuccApp: 登录服务器（英文界面为 SuccApp: Login Server），重新选择 OAuth2 授权或 PAT 登录。
重新认证服务器只更新认证状态，不会删除服务器配置，也不会修改本地项目文件。
断开连接
在服务器视图中可以断开当前服务器连接，也可以执行 SuccApp: 断开服务器连接（英文界面为 SuccApp: Disconnect Server）。
断开连接只影响当前 VS Code 窗口中的连接状态，不会删除 .succapp/config.json，也不会删除本地已克隆项目。
使用服务器
一个工作区可以配置多个服务器。例如，同一个项目可以同时配置测试环境和生产环境。
执行 SuccApp: 使用服务器（英文界面为 SuccApp: Use Server），选择要使用的服务器。切换后，后续克隆、拉取、推送和服务器浏览都会针对新的活跃服务器。
注意
切换到生产服务器后，任何 push 操作都会影响生产环境。发布前必须确认 Git 版本、差异和审批流程。
修改服务器配置
SuccApp 将服务器操作拆成独立命令，可以在命令面板中直接执行：
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 添加服务器 | Add Server | 添加服务器地址并登录 |
| 使用服务器 | Use Server | 切换当前工作区活跃服务器 |
| 登录服务器 | Login Server | 登录当前服务器，认证失效时重新认证 |
| 设置服务器地址 | Set Server URL | 在服务器地址或端口变化时替换地址，并迁移本地服务器基线 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置 |
| 打开服务器配置 | Open Server Config | 打开 .succapp/config.json 手工查看或调整 |
移除服务器配置只会从当前工作区移除该服务器地址，不会删除服务器上的项目，也不会删除本地 Git 仓库。
设置服务器地址适合服务器域名、IP 或端口变化的场景。执行前 SuccApp 会提示确认，说明该操作只会更新服务器配置并移动 .succapp/remote/ 下的本地服务器基线，不会修改工作区中的项目文件，也不会修改服务器项目。确认后需要输入新地址并完成登录；只有登录成功且本地基线迁移成功后，SuccApp 才会写入新的服务器配置。
浏览服务器项目
打开 SuccApp 侧边栏中的服务器视图，可以看到当前工作区配置的服务器。
连接成功后，展开服务器节点，可以看到服务器上的项目列表。项目节点通常显示项目名称和描述。
如果某个项目已经克隆到本地，服务器视图会显示相应状态。可以通过这个状态判断本地是否已经有该项目的工作副本。
浏览远端文件
展开项目节点，可以继续浏览服务器上的远端文件和目录。
远端文件是服务器当前内容，不代表本地一定已经存在对应文件。打开远端文件时，SuccApp 会通过只读方式读取服务器内容。
远端文件常用操作包括：
- 打开服务器源码。
- 查看服务器文件历史。
- 复制元数据路径。
- 复制元数据 ID。
- 打开服务器视图。
- 打开服务器编辑页。
克隆项目到本地
克隆项目是 SuccApp 将服务器元数据转换为本地文件系统的主要方式，也是 AI 低代码开发的起点。
可以通过以下入口克隆项目：
- 执行 SuccApp: 克隆项目（英文界面为 SuccApp: Clone Project）。
- 在服务器视图中选择项目节点，点击克隆按钮。
- 使用 SuccApp CLI 执行
succapp server project list查看当前登录可见的项目，再执行succapp workspace project clone <project>克隆指定项目。
克隆完成后，工作区根目录会出现项目目录。SuccApp 同时会在 .succapp/remote/ 中建立该服务器项目的本地基线，用于后续差异判断。
如果新克隆的项目中包含旧版本元数据文件，SuccApp 会提示编辑前建议先升级。CLI 克隆命令只显示旧版文件总数和升级命令，不展开完整文件列表；需要先查看候选文件时，可以执行 succapp workspace file upgrade --dry-run <project>。省略 <project> 时，CLI 会预演当前 workspace 中所有本地已同步项目。克隆本身不会自动升级本地内容。
如果 CLI 提示项目不可用，通常表示项目名写错、当前账号没有权限，或当前活跃服务器不是目标服务器。先用 succapp server project list 确认可见项目，再使用准确的项目名重试。
提示
首次使用某个服务器时，建议只克隆当前任务需要的项目，避免一次性下载过多无关项目。
从服务器重置本地项目
如果本地项目已经克隆过，可以在服务器视图中对已克隆项目执行 从服务器重置本地项目。
该操作会用服务器当前内容覆盖本地项目，本地已有修改会被放弃；如果本地存在服务器上没有的文件，也可能被删除。执行前应确认：
- 本地未提交的修改是否已经保存或提交。
- 当前服务器是否正确。
- 是否真的希望放弃本地项目中的现有修改和本地新增文件。
注意
这个操作接近于把本地项目恢复为服务器当前状态。执行前建议先查看 Git 状态，必要时先提交或备份本地修改。
移除本地项目
执行 SuccApp: 移除本地项目（英文界面为 SuccApp: Remove Local Project）可以从工作区和本地 mirror 中移除项目。
该操作只删除本地文件和本地基线，不会删除服务器项目。
如果项目已经纳入 Git，删除前应确认 Git 中是否仍需要保留这些文件。
多服务器使用建议
测试环境和生产环境可以配置在同一个工作区中，但日常项目工作建议遵守以下规则：
- 日常修改优先连接测试环境。
- 生产环境只在发布窗口使用。
- 使用服务器切换后先执行 SuccApp: 刷新变化（英文界面为 SuccApp: Refresh Changes），再查看同步状态；需要接受服务器内容时再执行 SuccApp: 拉取变化（英文界面为 SuccApp: Pull Changes）。
- 推送生产前必须检查 Changes 视图中的差异。
- 不要在没有 Git 记录的情况下直接覆盖生产环境。
常见问题
登录成功后看不到项目怎么办
确认账号是否有访问项目的权限，并检查服务器地址是否指向正确环境。
克隆项目很慢怎么办
项目文件较多时，首次克隆会比较慢。建议只克隆当前任务需要的项目，并避免在网络不稳定时操作生产服务器。
远端文件能直接编辑吗
服务器视图中的远端文件是只读浏览入口。需要修改文件时，应先克隆项目，在本地工作区中修改，再通过 push 同步到服务器。
