---
title: SuccApp for VS Code
navTitle: SuccApp for VS Code
---
# SuccApp for VS Code

SuccApp for VS Code 是 SuccApp 的图形化开发和同步工具，适合人工浏览服务器项目、查看 Changes、打开 diff、查看文件历史、编辑脚本、推送测试环境和配合 Git 评审 AI 修改。

它主要服务人工交互场景：当 AI 已经修改本地文件后，项目成员可以在 VS Code 中确认变化是否只包含预期文件、diff 是否合理、服务器文件历史是否支持回退，以及推送测试后页面效果是否正确。

<div class="annotated-image">
  <img src="../images/overview-ui.png" alt="SuccApp for VS Code 界面功能区域划分" />
  <span class="annotated-image-marker" style="--x: 1.5%; --y: 65.6%;">1</span>
  <span class="annotated-image-marker" style="--x: 11.2%; --y: 15.4%;">2</span>
  <span class="annotated-image-marker" style="--x: 11.2%; --y: 53.4%;">3</span>
  <span class="annotated-image-marker" style="--x: 11.2%; --y: 88.6%;">4</span>
  <span class="annotated-image-marker" style="--x: 47.7%; --y: 50.6%;">5</span>
  <span class="annotated-image-marker" style="--x: 87.9%; --y: 50.6%;">6</span>
  <span class="annotated-image-marker" style="--x: 50.0%; --y: 98.4%;">7</span>
</div>

图中数字对应的界面区域如下：

1. 活动栏：进入 SuccApp、资源管理器、搜索、Git、扩展等 VS Code 视图。
2. 服务器视图：连接和维护服务器、浏览远端项目和文件、克隆项目。
3. 变化视图：查看本地变化、远端变化和冲突，执行推送、拉取、对比等操作。
4. 文件历史视图：查看服务器文件历史，并与历史版本或工作区文件对比。
5. 编辑与差异对比区：编辑本地文件，查看本地版本和服务器版本的差异。
6. AI 助手区：使用 AI Coding 工具辅助修改、解释和检查文件。
7. 状态栏：查看当前服务器、Git 分支、同步状态、文件类型和光标位置等信息。

## 安装{#install}

在线安装时，打开 VS Code 扩展视图，搜索 `SuccApp`，点击安装。安装完成后，活动栏中会出现 SuccApp 图标。

离线环境可以使用 `.vsix` 安装包：

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

升级离线版本时，先确认 `.vsix` 的版本号和目标服务器版本兼容。升级后重新打开工作区，并检查服务器连接、项目树和同步状态。

## 服务器视图{#servers-view}

服务器视图用于管理当前工作区配置的服务器，并浏览服务器上的项目和文件。

### 顶部按钮{#servers-toolbar}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 添加服务器 | Add Server | 添加服务器地址并登录。 |
| 刷新服务器 | Refresh Servers | 刷新服务器列表和远端项目状态。 |

### 服务器节点菜单{#server-menu}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 连接服务器 | Connect Server | 使用已保存认证状态连接服务器。 |
| 断开服务器连接 | Disconnect Server | 断开当前服务器连接。 |
| 登录服务器 | Login Server | 重新选择 OAuth2 授权或 PAT 登录。 |
| 设置服务器地址 | Set Server URL | 替换服务器地址并迁移本地服务器基线。 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置。 |

### 项目节点菜单{#project-menu}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 克隆项目 | Clone Project | 将服务器项目下载到本地工作区。 |
| 从服务器重置本地项目 | Reset Local Project from Server | 用服务器当前内容重建已克隆项目，可能覆盖或删除本地文件。 |

### 远端文件菜单{#remote-file-menu}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 打开服务器源码 | Open Server Source | 在 VS Code 中以只读方式打开服务器当前内容。 |
| 查看服务器文件历史 | Show Server File History | 在文件历史视图中查看该文件的历史版本。 |
| 复制元数据路径 | Copy Metadata Path | 复制服务器元数据路径。 |
| 复制元数据 ID | Copy Metadata ID | 复制服务器资源 ID。 |
| 打开服务器视图 | Open Server Views | 在浏览器中打开该资源对应的查看页面。 |
| 打开服务器编辑页 | Open Server Edit Page | 在浏览器中打开该资源对应的编辑页面。 |

## 变化视图{#changes-view}

变化视图用于查看本地工作区、服务器基线和服务器当前内容之间的差异。

| 分组 | 英文界面 | 含义 |
| --- | --- | --- |
| 本地变化 | Local Changes | 本地工作区相对上次同步基线发生了变化，可以推送到服务器。 |
| 远端变化 | Remote Changes | 服务器相对本地基线发生了变化，可以拉取到本地。 |

冲突不是独立顶层分组。发生冲突时，同一个资源可能同时出现在本地变化和远端变化中，并带有冲突标记。

### 顶部按钮{#changes-toolbar}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 推送变化 | Push Changes | 批量推送当前窗口中已连接工作区的本地变化。 |
| 拉取变化 | Pull Changes | 批量拉取当前窗口中已连接工作区的服务器变化。 |
| 刷新变化 | Refresh Changes | 刷新同步状态。 |
| 切换树/列表视图 | Toggle Tree/List View | 在目录树和列表展示之间切换。 |
| 放弃修改 | Discard Changes | 批量放弃当前窗口中的本地变化。 |

### 单个变化菜单{#change-menu}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 打开文件 | Open File | 打开变化文件或打开差异。 |
| 推送文件 | Push File | 只推送该文件的本地变化。 |
| 拉取文件 | Pull File | 只拉取该文件的服务器变化。 |
| 放弃修改 | Discard Change | 用同步基线恢复本地文件，必要时会删除本地新增文件。 |
| 采用服务器版本 | Use Server Version | 对有服务器版本的变化使用服务器版本。 |
| 恢复本地版本 | Restore Local Version | 对本地变化或冲突恢复本地版本。 |
| 与服务器版本对比 | Compare File with Server | 打开 VS Code diff。 |

## 文件历史视图{#history-view}

文件历史视图用于查看服务器上的文件历史。常用入口包括服务器视图、变化视图和本地文件菜单中的 **查看服务器文件历史**。

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 刷新文件历史 | Refresh File History | 重新加载当前文件的历史。 |
| 与上一版本对比 | Compare with Previous Version | 对比相邻两个服务器历史版本。 |
| 与工作区文件对比 | Compare with Workspace | 对比某个历史版本和当前本地文件。 |

## 本地文件菜单{#local-file-menu}

| 操作 | 英文界面 | 说明 |
| --- | --- | --- |
| 与服务器版本对比 | Compare File with Server | 对比本地文件和服务器基线或服务器当前内容。 |
| 打开服务器视图 | Open Server Views | 在浏览器中打开该文件对应的服务器查看页面。 |
| 打开服务器编辑页 | Open Server Edit Page | 在浏览器中打开该文件对应的编辑页面。 |
| 打开服务器源码 | Open Server Source | 以只读方式查看服务器当前源码。 |
| 查看服务器文件历史 | Show Server File History | 查看服务器文件历史。 |
| 复制 Meta 路径 | Copy Meta Path | 复制该本地文件对应的服务器路径。 |
| 复制 Meta ID | Copy Meta ID | 复制 `.meta` 中记录的资源 ID。 |

## 命令面板命令{#commands}

可以通过 VS Code 命令面板执行 SuccApp 命令。

| 中文界面命令 | 英文界面命令 | 说明 |
| --- | --- | --- |
| SuccApp: 添加服务器 | SuccApp: Add Server | 添加服务器并登录。 |
| SuccApp: 使用服务器 | SuccApp: Use Server | 切换当前工作区活跃服务器。 |
| SuccApp: 登录服务器 | SuccApp: Login Server | 登录当前服务器，认证失效时可重新认证。 |
| SuccApp: 断开服务器连接 | SuccApp: Disconnect Server | 断开当前服务器连接。 |
| SuccApp: 移除服务器 | SuccApp: Remove Server | 从当前工作区移除服务器配置，不删除服务器项目。 |
| SuccApp: 设置服务器地址 | SuccApp: Set Server URL | 设置服务器地址并迁移 `.succapp/remote/` 下的本地基线。 |
| SuccApp: 打开服务器配置 | SuccApp: Open Server Config | 打开当前工作区的 `.succapp/config.json`。 |
| SuccApp: 克隆项目 | SuccApp: Clone Project | 从服务器克隆项目。 |
| SuccApp: 移除本地项目 | SuccApp: Remove Local Project | 移除本地项目和本地 mirror。 |
| SuccApp: 拉取变化 | SuccApp: Pull Changes | 拉取服务器变化。 |
| SuccApp: 推送变化 | SuccApp: Push Changes | 推送本地变化。 |
| SuccApp: 推送当前文件 | SuccApp: Push Current File | 推送当前编辑器文件。 |
| SuccApp: 升级文件 | SuccApp: Upgrade File | 将当前文件、指定文件或文件夹下支持的元数据升级到当前服务器内容版本。 |
| SuccApp: 刷新变化 | SuccApp: Refresh Changes | 刷新同步状态。 |
| SuccApp: 修复工作区 | SuccApp: Repair Workspace | 先检查工作区、本地同步基线和同步状态，再修复可自动处理的问题。 |
| SuccApp: 开启自动推送 | SuccApp: Enable Auto Push | 保存后自动推送。 |
| SuccApp: 关闭自动推送 | SuccApp: Disable Auto Push | 关闭保存后自动推送。 |
| SuccApp: 与服务器版本对比 | SuccApp: Compare File with Server | 打开差异对比。 |
| SuccApp: 配置同步忽略规则 | SuccApp: Configure Sync Ignore Rules | 打开同步忽略配置。 |
| SuccApp: 初始化工作区 | SuccApp: Initialize Workspace | 创建或刷新 `.succapp/config.json`、推荐设置、AI 协作目录、TypeScript 类型声明和编辑器结构提示文件。 |
| SuccApp: 从模板新建扩展 | SuccApp: Create Extension from Template | 从服务器模板创建扩展目录。 |
| SuccApp: 推送扩展 | SuccApp: Push Extension | 把扩展目录推送到当前服务器。 |
| SuccApp: 查看日志 | SuccApp: Show Logs | 打开 SuccApp 日志面板。 |

## 快捷键{#keybindings}

| 快捷键 | macOS | 说明 |
| --- | --- | --- |
| `Ctrl+Shift+Down` | `Command+Shift+Down` | 拉取。 |
| `Ctrl+Shift+Up` | `Command+Shift+Up` | 推送。 |
| `Ctrl+Alt+Up` | `Command+Alt+Up` | 推送当前文件。 |
| `Ctrl+Alt+D` | `Command+Alt+D` | 与服务器版本对比。 |

## 设置项{#settings}

SuccApp 设置项可以在 VS Code 设置中搜索 `succapp` 查看。

| 设置项 | 默认值 | 说明 |
| --- | --- | --- |
| `succapp.sync.autoPush` | `false` | 保存文件后自动推送到服务器。 |
| `succapp.sync.autoPushDelay` | `2000` | 自动推送延迟，单位毫秒。 |
| `succapp.sync.autoPull` | `false` | 是否定时自动拉取服务器变化。 |
| `succapp.sync.autoPullInterval` | `60` | 自动拉取间隔，单位秒。 |
| `succapp.sync.ignore` | `["**/node_modules/**", "**/*.log"]` | 同步时忽略的文件匹配模式。 |
| `succapp.sync.maxPushFileSize` | `10Mb` | 单个文件允许推送的最大大小。 |

::: warning 注意
自动推送适合测试环境中的快速调试，不建议在生产环境中开启。自动拉取可能修改本地文件，多人协作时也应谨慎开启。
:::

## 与 AI 协同{#ai}

AI 修改文件后，项目成员应在 SuccApp for VS Code 中检查：

1. Changes 视图是否只包含预期文件。
2. diff 是否存在误删、无关格式化或风险配置。
3. `.meta` 变化是否符合资源操作。
4. 推送测试环境后，浏览器页面或设计器效果是否正确。
5. Git diff 是否适合提交和评审。