使用 Git 服务

Git 服务用于将当前 AI 编程项目与 GitLab 远程仓库关联。绑定后，可以在版本控制页面查看同步状态，将本地提交 Push 到远程仓库，或通过 Pull 获取协作者提交的更新。

本功能适合团队协作、代码备份和在 AI 编程平台之外继续维护项目。

功能概述

功能	说明
绑定仓库	使用 GitLab 仓库地址、远程分支和访问 Token 关联当前项目。
查看同步状态	判断本地是否有待推送提交、远程是否有更新或工作区是否存在未提交修改。
Push	将当前项目已经创建的本地提交推送到远程分支。
Pull	拉取远程分支的新提交，并将更新同步到当前项目文件。
冲突处理	Pull 检测到同一内容被两侧修改时，查看冲突文件并选择保留本地或远程版本。
解除绑定	解除项目与当前 GitLab 仓库的关联，以便更换仓库或授权。

绑定与导入的区别

绑定 GitLab 仓库和从 GitLab 导入项目是两个不同的功能：

场景	使用功能	结果
已经有 AI 编程项目，希望同步到 GitLab	绑定仓库	当前项目继续保留，并新增远程仓库同步关系。
GitLab 中已经有项目，希望在 AI 编程中继续开发	导入项目	平台读取远程仓库并创建新的 AI 编程项目。

绑定操作只建立当前项目与远程仓库的关联，不等于重新导入项目。需要从已有仓库创建项目时，请参见导入项目。

当前支持范围

• 当前页面提供 GitLab 仓库绑定。
• 仓库绑定以当前项目为单位，不是整个工作空间的统一绑定。
• 绑定时可以指定远程分支，默认值为 main。
• 一个项目同时维护一个仓库绑定；更换仓库时需要先解除当前绑定。
• Push、Pull 和冲突处理要求项目处于可编辑状态，并且项目运行实例已经准备完成。

准备工作

绑定前请准备：

1. 可访问的 GitLab 仓库 HTTPS 地址。
2. 需要同步的远程分支名称。
3. 对目标仓库具有相应权限的 GitLab Personal Access Token。
4. 当前项目的编辑权限。

建议同时完成以下检查：

• 确认仓库和分支属于正确的团队与项目。
• 如果远程仓库已有代码，先确认它与当前 AI 编程项目是否来自同一代码基础。
• 提交或备份本地重要修改，避免首次 Pull 时产生难以判断的冲突。
• 根据 GitLab 和企业管理员要求，为 Token 配置必要的仓库读取、写入权限。

谨慎绑定已有代码的仓库

当前项目与远程仓库文件差异较大时，首次同步可能产生大量冲突。新项目优先使用空仓库；如果必须绑定已有仓库，应先比较双方文件和提交历史。

绑定 GitLab 仓库

打开绑定窗口

1. 打开目标 AI 编程项目。
2. 在工作区顶部打开 版本控制 页签。
3. 在仓库状态区域单击 绑定仓库。
4. 填写仓库地址、远程分支和访问 Token。
5. 单击窗口底部的 绑定仓库。
6. 等待“GitLab 仓库已绑定”提示，然后检查页面显示的仓库和同步状态。

编号	配置项	说明
1	仓库地址	GitLab 仓库的 HTTPS 地址，例如 https://gitlab.example.com/group/project.git。
2	远程分支	与当前项目同步的目标分支。未填写时使用 main。
3	访问 Token	GitLab Personal Access Token。页面以密码输入框显示，可单击眼睛按钮临时查看。
4	操作按钮	“取消”关闭窗口且不保存；“绑定仓库”校验并建立仓库关联。

仓库地址

建议复制 GitLab 仓库页面提供的 HTTPS 克隆地址。地址通常以 .git 结尾，但是否需要后缀应以实际仓库地址为准。

填写前检查：

• 协议、域名、群组路径和仓库名称完整。
• 不要把 Token、用户名或密码直接拼进仓库地址。
• 不要误填仓库浏览页面中的文件、提交或分支子页面地址。

远程分支

远程分支用于确定 Push 和 Pull 的目标。默认可以填写 main，也可以按项目需要填写其他分支名称。

分支名称必须准确匹配远程仓库。绑定已有仓库时，优先选择已经存在且允许当前账号读写的分支。

访问 Token

Token 用于验证当前项目访问 GitLab 仓库的权限。绑定失败时，应检查 Token 是否过期、是否属于正确账号，以及是否具有目标仓库所需权限。

访问 Token 是敏感凭证

Token 只应填写在绑定窗口中。不要把 Token 写入项目代码、环境变量示例、提交消息、AI 对话、截图或文档。发现 Token 泄露后，应立即在 GitLab 中撤销并重新创建。

查看同步状态

绑定成功后，版本控制页顶部会显示仓库名称、同步提示、Push 和 Pull 按钮。

状态提示	含义	建议操作
已同步	本地与远程提交一致，且没有检测到本地未提交修改。	可以继续开发，无需执行同步。
有未推送的更改	当前项目有本地提交尚未发送到远程仓库。	检查待推送提交后执行 Push。
远程有更新	远程分支包含当前项目尚未获取的提交。	检查本地修改后执行 Pull。
有本地未提交的修改	工作区文件发生变化，但尚未创建本地提交。	先查看并提交或放弃这些更改。
同步状态检测中	平台正在读取本地与远程仓库状态。	等待检测完成后再执行 Push 或 Pull。

仓库状态还可能显示最近同步时间。单击仓库名称旁的跳转图标，可以在新页面打开对应 GitLab 仓库。

Push：推送本地提交

Push 用于将 AI 编程项目中已经创建的本地提交发送到远程分支。它不会替代本地提交；存在尚未提交的文件时，应先在源代码管理区域创建版本。

执行 Push

1. 打开 版本控制 页签。
2. 确认页面提示 有未推送的更改。
3. 单击 Push。
4. 在“有未推送的更改”窗口中检查待推送的提交编号、说明和时间。
5. 如果本次暂不推送，单击 忽略 关闭窗口。
6. 如果内容正确，单击 Push。
7. 在二次确认窗口中确认推送所有列出的更改。
8. 等待“Push 成功”提示，并确认同步状态变为 已同步。

Push 前先确认远程没有新提交

远程分支有更新时，Push 按钮可能不可用，或页面提示先 Pull。不要通过强制推送覆盖远程提交，应先拉取并处理差异。

Push 按钮不可用

常见原因包括：

• 当前没有需要推送的本地提交。
• 远程分支包含尚未拉取的更新。
• 仓库绑定或项目运行实例尚未准备完成。
• 当前用户没有项目编辑权限。
• Token 对目标仓库没有写入权限。

Pull：拉取远程更新

Pull 用于获取远程分支的新提交。例如，团队成员在 GitLab 中提交代码后，可以通过 Pull 把这些更新同步到当前 AI 编程项目。

执行 Pull

1. 打开 版本控制 页签。
2. 确认绑定的仓库和远程分支正确。
3. 检查项目中是否存在尚未提交的修改。
4. 单击 Pull。
5. 等待平台拉取并合并远程更新。
6. Pull 成功后，检查版本时间线和项目文件。
7. 重新运行、构建或预览项目，验证远程改动没有破坏现有功能。

Pull 可能返回以下结果：

结果	说明与处理方式
Pull 成功	远程提交已经同步到当前项目，项目文件会刷新。
本地仓库已是最新	当前项目已经包含远程分支的最新提交。
存在本地未提交修改	平台不会直接拉取；先提交或放弃本地修改，再重试 Pull。
检测到冲突	本地和远程修改无法自动合并，需要在冲突检查窗口中选择处理方式。

处理代码冲突

当本地和远程修改了同一文件的相同内容，Pull 可能打开 冲突检查 窗口。

冲突窗口会列出需要处理的文件。单击文件可以展开左右差异，确认本地与远程分别修改了什么。

当前页面提供两种整体处理策略：

策略	结果
全部保留我的版本	放弃远程仓库在所有冲突文件中的修改，只保留当前 AI 编程项目的本地内容。
全部使用远程版本	使用远程仓库内容覆盖所有冲突文件中的本地内容。

选择策略后，页面还会进行一次确认。处理成功后，项目文件和版本状态会刷新。

冲突策略会作用于全部冲突文件

在单击“全部保留我的版本”或“全部使用远程版本”之前，应逐个展开冲突文件并检查差异。如果不同文件需要采用不同结果，建议先在终端或代码编辑器中手动处理，再创建清晰的合并提交。

冲突处理建议

1. 先确认冲突是由哪些本地提交和远程提交产生的。
2. 逐个查看冲突文件，不要只根据文件名选择策略。
3. 配置、依赖、数据库脚本等文件应重点检查。
4. 处理完成后运行测试和预览。
5. 确认结果正确后，再将合并结果 Push 到远程仓库。

解除或更换仓库绑定

绑定成功后，仓库名称旁会显示解除绑定入口。

1. 打开 版本控制 页签。
2. 找到当前绑定的仓库名称。
3. 单击解除绑定图标。
4. 在“解除当前仓库绑定？”提示中单击确认。
5. 页面显示“已解除仓库绑定”后，重新单击 绑定仓库，填写新的仓库或授权信息。

解除绑定只移除当前项目与 GitLab 仓库的关联，不会删除远程仓库，也不会删除项目已有的本地版本历史。

在终端中检查 Git 状态

熟悉 Git 的开发者可以在 AI 编程环境终端中使用命令检查仓库。常用的只读命令包括：

git status
git log --oneline --decorate -n 20
git diff
git remote -v
git branch --show-current

也可以使用标准 Git 命令执行提交、Pull 和 Push，但平台页面提供了同步状态、待推送提交确认和冲突检查，常规协作优先使用版本控制页面更容易确认结果。

不要在终端命令中直接写 Token

带 Token 的命令可能被终端历史、日志或截图记录。远程认证应优先使用平台的仓库绑定窗口。

常见问题

绑定仓库失败

依次检查：

• 仓库地址是否完整，并且能够从当前环境访问。
• GitLab 服务是否可用，仓库是否存在。
• 远程分支名称是否正确。
• Token 是否有效、过期或已被撤销。
• Token 所属账号是否有目标仓库权限。
• 当前用户是否有 AI 编程项目编辑权限。

为什么 Pull 提示先提交本地修改

当前工作区存在尚未提交的文件变化。打开 源代码管理 查看差异，把需要保留的修改提交成版本，或明确放弃不再需要的修改，然后重新执行 Pull。

为什么 Push 提示先 Pull

远程分支包含本地没有的提交。先执行 Pull，将远程更新合并到当前项目；解决冲突并验证代码后，再重新 Push。

可以指定其他分支吗

可以。绑定窗口提供 远程分支 输入框，默认值为 main。绑定已有仓库时，应填写实际存在的分支，并确保 Token 对该分支具有相应权限。

可以绑定已有代码的仓库吗

可以，但双方代码基础不一致时容易产生冲突。建议优先绑定空仓库；使用已有仓库前，应比较提交历史和主要文件。

如何更换仓库或 GitLab 账号

先解除当前仓库绑定，再使用新仓库地址、分支和新账号 Token 重新绑定。

安全与协作建议

1. Token 只授予完成同步所需的最小权限，并设置合理有效期。
2. 不同成员使用各自的 GitLab 凭证，不共享个人 Token。
3. Push 前检查待推送提交和远程分支，不使用强制推送覆盖团队提交。
4. Pull 前先提交或备份本地修改。
5. 处理冲突后必须重新运行测试、构建和预览。
6. 不要把 .env、密钥、Token 或生产配置提交到远程仓库。

相关文档

• 版本控制：查看版本时间线、代码差异和手动提交。
• 导入项目：从 GitLab 仓库或压缩包创建新的 AI 编程项目。
• AI 编程环境：了解项目文件、编辑器和终端。