主题
SuccApp for VS Code
SuccApp for VS Code 是 SuccApp 的图形化开发和同步工具，适合人工浏览服务器项目、查看 Changes、打开 diff、查看文件历史、编辑脚本、推送测试环境和配合 Git 评审 AI 修改。
它主要服务人工交互场景：当 AI 已经修改本地文件后，项目成员可以在 VS Code 中确认变化是否只包含预期文件、diff 是否合理、服务器文件历史是否支持回退，以及推送测试后页面效果是否正确。
1234567图中数字对应的界面区域如下：
- 活动栏：进入 SuccApp、资源管理器、搜索、Git、扩展等 VS Code 视图。
- 服务器视图：连接和维护服务器、浏览远端项目和文件、克隆项目。
- 变化视图：查看本地变化、远端变化和冲突，执行推送、拉取、对比等操作。
- 文件历史视图：查看服务器文件历史，并与历史版本或工作区文件对比。
- 编辑与差异对比区：编辑本地文件，查看本地版本和服务器版本的差异。
- AI 助手区：使用 AI Coding 工具辅助修改、解释和检查文件。
- 状态栏：查看当前服务器、Git 分支、同步状态、文件类型和光标位置等信息。
安装
在线安装时，打开 VS Code 扩展视图，搜索 SuccApp，点击安装。安装完成后，活动栏中会出现 SuccApp 图标。
离线环境可以使用 .vsix 安装包：
bash
code --install-extension succapp-for-vscode-版本号.vsix升级离线版本时，先确认 .vsix 的版本号和目标服务器版本兼容。升级后重新打开工作区，并检查服务器连接、项目树和同步状态。
服务器视图
服务器视图用于管理当前工作区配置的服务器，并浏览服务器上的项目和文件。
顶部按钮
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 添加服务器 | Add Server | 添加服务器地址并登录。 |
| 刷新服务器 | Refresh Servers | 刷新服务器列表和远端项目状态。 |
服务器节点菜单
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 连接服务器 | Connect Server | 使用已保存认证状态连接服务器。 |
| 断开服务器连接 | Disconnect Server | 断开当前服务器连接。 |
| 登录服务器 | Login Server | 重新选择 OAuth2 授权或 PAT 登录。 |
| 设置服务器地址 | Set Server URL | 替换服务器地址并迁移本地服务器基线。 |
| 移除服务器 | Remove Server | 从当前工作区移除服务器配置。 |
项目节点菜单
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 克隆项目 | Clone Project | 将服务器项目下载到本地工作区。 |
| 从服务器重置本地项目 | Reset Local Project from Server | 用服务器当前内容重建已克隆项目，可能覆盖或删除本地文件。 |
远端文件菜单
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 打开服务器源码 | Open Server Source | 在 VS Code 中以只读方式打开服务器当前内容。 |
| 查看服务器文件历史 | Show Server File History | 在文件历史视图中查看该文件的历史版本。 |
| 复制元数据路径 | Copy Metadata Path | 复制服务器元数据路径。 |
| 复制元数据 ID | Copy Metadata ID | 复制服务器资源 ID。 |
| 打开服务器视图 | Open Server Views | 在浏览器中打开该资源对应的查看页面。 |
| 打开服务器编辑页 | Open Server Edit Page | 在浏览器中打开该资源对应的编辑页面。 |
变化视图
变化视图用于查看本地工作区、服务器基线和服务器当前内容之间的差异。
| 分组 | 英文界面 | 含义 |
|---|---|---|
| 本地变化 | Local Changes | 本地工作区相对上次同步基线发生了变化，可以推送到服务器。 |
| 远端变化 | Remote Changes | 服务器相对本地基线发生了变化，可以拉取到本地。 |
冲突不是独立顶层分组。发生冲突时，同一个资源可能同时出现在本地变化和远端变化中，并带有冲突标记。
顶部按钮
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 推送变化 | Push Changes | 批量推送当前窗口中已连接工作区的本地变化。 |
| 拉取变化 | Pull Changes | 批量拉取当前窗口中已连接工作区的服务器变化。 |
| 刷新变化 | Refresh Changes | 刷新同步状态。 |
| 切换树/列表视图 | Toggle Tree/List View | 在目录树和列表展示之间切换。 |
| 放弃修改 | Discard Changes | 批量放弃当前窗口中的本地变化。 |
单个变化菜单
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 打开文件 | Open File | 打开变化文件或打开差异。 |
| 推送文件 | Push File | 只推送该文件的本地变化。 |
| 拉取文件 | Pull File | 只拉取该文件的服务器变化。 |
| 放弃修改 | Discard Change | 用同步基线恢复本地文件，必要时会删除本地新增文件。 |
| 采用服务器版本 | Use Server Version | 对有服务器版本的变化使用服务器版本。 |
| 恢复本地版本 | Restore Local Version | 对本地变化或冲突恢复本地版本。 |
| 与服务器版本对比 | Compare File with Server | 打开 VS Code diff。 |
文件历史视图
文件历史视图用于查看服务器上的文件历史。常用入口包括服务器视图、变化视图和本地文件菜单中的 查看服务器文件历史。
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 刷新文件历史 | Refresh File History | 重新加载当前文件的历史。 |
| 与上一版本对比 | Compare with Previous Version | 对比相邻两个服务器历史版本。 |
| 与工作区文件对比 | Compare with Workspace | 对比某个历史版本和当前本地文件。 |
本地文件菜单
| 操作 | 英文界面 | 说明 |
|---|---|---|
| 与服务器版本对比 | 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。 |
命令面板命令
可以通过 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 日志面板。 |
快捷键
| 快捷键 | 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 | 与服务器版本对比。 |
设置项
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 | 单个文件允许推送的最大大小。 |
注意
自动推送适合测试环境中的快速调试，不建议在生产环境中开启。自动拉取可能修改本地文件，多人协作时也应谨慎开启。
与 AI 协同
AI 修改文件后，项目成员应在 SuccApp for VS Code 中检查：
- Changes 视图是否只包含预期文件。
- diff 是否存在误删、无关格式化或风险配置。
.meta变化是否符合资源操作。- 推送测试环境后，浏览器页面或设计器效果是否正确。
- Git diff 是否适合提交和评审。
