版本控制

版本控制用于记录 AI 编程项目的代码变化。每个版本对应一次 Git 提交，你可以查看提交时间线、定位某次修改、展开文件差异，并在项目可编辑时将代码恢复到指定版本。

版本控制记录的是项目代码版本，与已经部署到环境中的部署版本不是同一类记录。如果需要回滚已部署的应用，请使用部署历史中的回滚功能。

版本控制能做什么

能力	说明
记录版本	保存提交编号、提交说明、作者、提交者和提交时间。
查看历史	按时间线查看当前分支的版本记录。
搜索版本	按提交编号或提交说明中的关键词筛选记录。
按日期筛选	只显示所选开始日期和结束日期范围内的记录。
查看文件差异	查看某次提交新增、修改或删除的文件，以及具体代码差异。
恢复历史代码	将当前项目代码恢复到指定历史版本。
手动提交	对手动编辑产生的文件变更填写提交消息并创建版本。
同步 GitLab	绑定 GitLab 仓库后，通过 Push 和 Pull 同步远程代码。

打开版本控制

可以通过以下入口打开版本控制页面：

1. 在工作区顶部单击 版本控制 页签。
2. 如果页签尚未打开，单击 新标签页，再选择 版本控制。
3. 在 AI 对话区的版本卡片中单击 查看修改记录，直接查看该轮任务产生的版本。
4. 单击 AI 对话区顶部的历史按钮，选择目标版本后查看修改记录。

进入页面后，默认显示当前分支的版本时间线。

认识版本列表页面

编号	区域	功能
1	GitLab 仓库状态	显示项目是否已经绑定远程仓库。未绑定时提供“绑定仓库”按钮；绑定后显示仓库、同步状态和远程操作。
2	分支与筛选区	显示当前分支，并提供关键词搜索和日期范围筛选。
3	版本时间线	按时间显示提交编号、提交说明、作者和提交时间；单击任一记录可进入版本详情。

GitLab 仓库状态

未绑定 GitLab 仓库时，页面仍然可以显示项目自身的版本历史。绑定远程仓库主要用于在 AI 编程项目与 GitLab 之间同步代码。

绑定后，仓库状态区域可能显示以下内容：

元素或按钮	功能
仓库名称	显示当前绑定的 GitLab 仓库。支持时可跳转到对应仓库页面。
最近同步时间	显示最近一次获取远程状态的时间。
同步状态	提示本地与远程是否一致，以及是否存在待推送或待拉取内容。
Push	将本地尚未推送的提交发送到远程仓库。本地落后于远程时应先处理 Pull。
Pull	拉取远程分支的最新内容并同步到当前项目。
解除绑定	解除当前仓库关联。需要更换授权账号时，应先解除原绑定。

具体的仓库绑定、Push、Pull 和冲突处理方式，请参见使用 Git 服务。

分支、搜索与日期筛选

• 分支名称：显示当前版本时间线所属的分支。未绑定远程仓库时通常显示 Main。
• 搜索内容：输入提交编号或提交说明中的关键词，快速缩小版本范围。
• 开始日期 / 结束日期：选择日期范围，只查看该时间段内的提交。
• 清除筛选：删除搜索文字或清空日期范围后，恢复显示完整时间线。

版本时间线

每条版本记录包含以下信息：

信息	说明
提交编号	Git Commit Hash 的短格式，用于唯一识别版本。
提交说明	描述该版本完成的功能或修复内容。
作者	创建该提交的用户或系统身份。
提交时间	该版本写入项目仓库的时间。

提交说明中可能出现 feat:、fix:、docs: 等前缀，它们用于描述变更类型。例如：

• feat:：新增或调整功能。
• fix:：修复问题。
• docs:：更新文档。
• refactor:：重构代码但不改变预期功能。
• chore:：依赖、构建或维护性调整。
• Initial commit：项目初始化时创建的提交。

这些文字属于提交说明，不是独立的页面状态。实际显示内容取决于 Agent 或提交者填写的消息。

查看版本详情与代码差异

在版本时间线中单击一条记录，可查看该版本的完整信息和文件变更。

编号	区域	功能
1	版本信息	显示提交编号、提交说明、作者、提交者及日期，并提供“回到该版本”操作。
2	改动文件	汇总变更文件数量、增加和删除的代码行数；支持搜索文件或内容。
3	修改前内容	左侧以红色背景标识被删除或替换的旧代码。
4	修改后内容	右侧以绿色背景标识新增或替换后的新代码。

查看改动文件

改动文件列表会显示文件路径、增加行数、删除行数和文件状态。常见文件状态包括新增、修改和删除。

1. 在版本时间线中单击目标版本。
2. 在 改动文件 区域找到目标文件。
3. 单击文件行右侧的展开按钮。
4. 对照左右两侧代码，确认该版本修改了什么。
5. 再次单击展开按钮可收起文件差异。

当一次提交包含较多文件时，可以使用右上角搜索框定位目标文件或相关内容。

理解左右差异视图

• 左侧代表修改前的文件内容，删除或被替换的行使用红色背景。
• 右侧代表修改后的文件内容，新增或替换后的行使用绿色背景。
• 没有颜色标记的行是为了帮助理解上下文而显示的未变化代码。
• +18 表示该文件新增 18 行，-18 表示删除 18 行；它们不代表文件总行数。

回到历史版本

当当前代码出现错误，或需要恢复到之前的稳定状态时，可以使用 回到该版本。

1. 打开版本控制页面。
2. 在时间线中选择需要恢复的历史版本。
3. 先检查提交说明、提交时间和改动文件，确认目标版本正确。
4. 单击 回到该版本。
5. 等待页面提示操作成功，并重新检查项目文件。
6. 重新运行或预览项目，确认恢复后的代码可以正常工作。

回到该版本会修改当前项目代码

恢复前应先处理尚未提交的重要修改。不要只根据提交说明判断版本，建议同时核对提交编号和文件差异。版本恢复不会替代部署回滚；线上环境仍需在部署历史中单独处理。

以下情况可能无法执行恢复操作：

• 当前项目处于只读状态，或当前用户没有编辑权限。
• 项目运行实例尚未准备完成。
• 目标版本记录不完整或已经不可用。
• 页面正在执行其他版本或远程仓库操作。

手动提交代码版本

编程 Agent 完成任务后通常会自动创建版本。如果你直接在代码编辑器中修改了文件，可以通过项目文件区的 源代码管理 手动提交。

源代码管理区域

区域或按钮	功能
刷新	重新读取项目当前的 Git 状态。
列表 / 树状视图	切换变更文件的组织方式。
消息	填写本次提交说明。没有提交消息时不能提交。
提交	将当前项目变更创建为新的代码版本。
暂存的更改	显示已经暂存的文件；支持全部取消暂存。
更改	显示尚未暂存的文件；支持暂存全部。

单击变更文件可以打开差异视图。右键单击文件还可以执行以下操作：

• 打开更改：查看修改前后的代码差异。
• 打开文件：在代码编辑器中打开当前文件。
• 暂存更改：将未暂存文件放入暂存区。
• 取消暂存：把已暂存文件移回未暂存区域。
• 放弃更改：丢弃该文件尚未提交的修改。

放弃更改通常不可直接撤销

执行前应确认修改不再需要。对于重要内容，建议先复制备份或创建版本。

建议的手动提交流程

1. 保存正在编辑的文件。
2. 打开 源代码管理，单击刷新。
3. 逐个查看变更文件及代码差异。
4. 暂存需要纳入本次版本的文件。
5. 填写简洁、明确的提交消息。
6. 单击 提交。
7. 回到版本控制页签，确认新版本已经出现在时间线中。

绑定 GitLab 仓库

单击 绑定仓库 后，需要填写以下信息：

配置项	说明
仓库地址	GitLab 仓库的 HTTPS 地址，例如 https://gitlab.example.com/group/project.git。
远程分支	需要同步的目标分支，默认可填写 main。
访问 Token	有权访问目标仓库的 GitLab Personal Access Token。

保护访问 Token

Token 属于敏感凭证，只应在绑定窗口中填写。不要把 Token 写入项目文件、提交说明、截图、文档或 AI 对话。

绑定完成后，建议先检查同步状态，再决定执行 Push 或 Pull。远程分支包含其他成员的新提交时，应先拉取并处理可能的冲突，避免覆盖他人的改动。

常见页面状态

页面提示	含义与处理方式
当前项目未绑定 GitLab 仓库	只表示尚未关联远程仓库，本地版本历史仍可正常使用。
暂无版本记录	当前分支没有可显示的提交，或搜索和日期条件没有匹配结果。
暂无版本详情	目标提交没有返回可展示的详细信息。可以返回列表后重新选择。
未解析到文件差异	提交存在，但平台未识别到可展示的文件差异。
当前没有 Git 变更	工作区相对最近版本没有未提交修改。
正在加载版本记录	平台正在读取项目仓库，请等待完成后再操作。
版本历史加载失败	检查项目实例和网络状态，然后重新进入版本控制页签。

使用建议

1. 每完成一项可以独立验证的功能后创建一次版本，避免单次提交包含过多无关修改。
2. 提交消息应说明“改了什么”，不要只写“更新”“修改”等模糊文字。
3. 回到历史版本前先检查未提交文件，避免覆盖仍需保留的工作。
4. 查看差异时重点检查配置、依赖文件、数据库脚本和删除操作。
5. Push 前先确认远程分支和同步状态；多人协作时优先拉取最新提交。
6. 不要在代码、提交消息或远程仓库配置中写入密码、Token 等敏感信息。

相关文档

• AI 编程环境：了解工作区、文件区、编辑器和终端的功能。
• 使用 Git 服务：绑定 GitLab 仓库并执行 Push、Pull 和解绑。
• 回滚部署版本：恢复已经部署到环境中的历史版本。