Appearance
使用 Git 服务
Git 服务用于将当前 AI 编程项目与 GitLab 远程仓库关联。绑定后，可以在版本控制页面查看同步状态，将本地提交 Push 到远程仓库，或通过 Pull 获取协作者提交的更新。
本功能适合团队协作、代码备份和在 AI 编程平台之外继续维护项目。
功能概述
| 功能 | 说明 |
|---|---|
| 绑定仓库 | 使用 GitLab 仓库地址、远程分支和访问 Token 关联当前项目。 |
| 查看同步状态 | 判断本地是否有待推送提交、远程是否有更新或工作区是否存在未提交修改。 |
| Push | 将当前项目已经创建的本地提交推送到远程分支。 |
| Pull | 拉取远程分支的新提交，并将更新同步到当前项目文件。 |
| 冲突处理 | Pull 检测到同一内容被两侧修改时，查看冲突文件并选择保留本地或远程版本。 |
| 解除绑定 | 解除项目与当前 GitLab 仓库的关联，以便更换仓库或授权。 |
绑定与导入的区别
绑定 GitLab 仓库和从 GitLab 导入项目是两个不同的功能：
| 场景 | 使用功能 | 结果 |
|---|---|---|
| 已经有 AI 编程项目，希望同步到 GitLab | 绑定仓库 | 当前项目继续保留，并新增远程仓库同步关系。 |
| GitLab 中已经有项目，希望在 AI 编程中继续开发 | 导入项目 | 平台读取远程仓库并创建新的 AI 编程项目。 |
绑定操作只建立当前项目与远程仓库的关联，不等于重新导入项目。需要从已有仓库创建项目时，请参见导入项目。
当前支持范围
- 当前页面提供 GitLab 仓库绑定。
- 仓库绑定以当前项目为单位，不是整个工作空间的统一绑定。
- 绑定时可以指定远程分支，默认值为
main。 - 一个项目同时维护一个仓库绑定；更换仓库时需要先解除当前绑定。
- Push、Pull 和冲突处理要求项目处于可编辑状态，并且项目运行实例已经准备完成。
准备工作
绑定前请准备：
- 可访问的 GitLab 仓库 HTTPS 地址。
- 需要同步的远程分支名称。
- 对目标仓库具有相应权限的 GitLab Personal Access Token。
- 当前项目的编辑权限。
建议同时完成以下检查：
- 确认仓库和分支属于正确的团队与项目。
- 如果远程仓库已有代码，先确认它与当前 AI 编程项目是否来自同一代码基础。
- 提交或备份本地重要修改，避免首次 Pull 时产生难以判断的冲突。
- 根据 GitLab 和企业管理员要求，为 Token 配置必要的仓库读取、写入权限。
谨慎绑定已有代码的仓库
当前项目与远程仓库文件差异较大时，首次同步可能产生大量冲突。新项目优先使用空仓库；如果必须绑定已有仓库，应先比较双方文件和提交历史。
绑定 GitLab 仓库
打开绑定窗口
- 打开目标 AI 编程项目。
- 在工作区顶部打开 版本控制 页签。
- 在仓库状态区域单击 绑定仓库。
- 填写仓库地址、远程分支和访问 Token。
- 单击窗口底部的 绑定仓库。
- 等待“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
- 打开 版本控制 页签。
- 确认页面提示 有未推送的更改。
- 单击 Push。
- 在“有未推送的更改”窗口中检查待推送的提交编号、说明和时间。
- 如果本次暂不推送，单击 忽略 关闭窗口。
- 如果内容正确，单击 Push。
- 在二次确认窗口中确认推送所有列出的更改。
- 等待“Push 成功”提示，并确认同步状态变为 已同步。
Push 前先确认远程没有新提交
远程分支有更新时，Push 按钮可能不可用，或页面提示先 Pull。不要通过强制推送覆盖远程提交，应先拉取并处理差异。
Push 按钮不可用
常见原因包括：
- 当前没有需要推送的本地提交。
- 远程分支包含尚未拉取的更新。
- 仓库绑定或项目运行实例尚未准备完成。
- 当前用户没有项目编辑权限。
- Token 对目标仓库没有写入权限。
Pull：拉取远程更新
Pull 用于获取远程分支的新提交。例如，团队成员在 GitLab 中提交代码后，可以通过 Pull 把这些更新同步到当前 AI 编程项目。
执行 Pull
- 打开 版本控制 页签。
- 确认绑定的仓库和远程分支正确。
- 检查项目中是否存在尚未提交的修改。
- 单击 Pull。
- 等待平台拉取并合并远程更新。
- Pull 成功后，检查版本时间线和项目文件。
- 重新运行、构建或预览项目，验证远程改动没有破坏现有功能。
Pull 可能返回以下结果：
| 结果 | 说明与处理方式 |
|---|---|
| Pull 成功 | 远程提交已经同步到当前项目，项目文件会刷新。 |
| 本地仓库已是最新 | 当前项目已经包含远程分支的最新提交。 |
| 存在本地未提交修改 | 平台不会直接拉取；先提交或放弃本地修改，再重试 Pull。 |
| 检测到冲突 | 本地和远程修改无法自动合并，需要在冲突检查窗口中选择处理方式。 |
处理代码冲突
当本地和远程修改了同一文件的相同内容，Pull 可能打开 冲突检查 窗口。
冲突窗口会列出需要处理的文件。单击文件可以展开左右差异，确认本地与远程分别修改了什么。
当前页面提供两种整体处理策略：
| 策略 | 结果 |
|---|---|
| 全部保留我的版本 | 放弃远程仓库在所有冲突文件中的修改，只保留当前 AI 编程项目的本地内容。 |
| 全部使用远程版本 | 使用远程仓库内容覆盖所有冲突文件中的本地内容。 |
选择策略后，页面还会进行一次确认。处理成功后，项目文件和版本状态会刷新。
冲突策略会作用于全部冲突文件
在单击“全部保留我的版本”或“全部使用远程版本”之前，应逐个展开冲突文件并检查差异。如果不同文件需要采用不同结果，建议先在终端或代码编辑器中手动处理，再创建清晰的合并提交。
冲突处理建议
- 先确认冲突是由哪些本地提交和远程提交产生的。
- 逐个查看冲突文件，不要只根据文件名选择策略。
- 配置、依赖、数据库脚本等文件应重点检查。
- 处理完成后运行测试和预览。
- 确认结果正确后，再将合并结果 Push 到远程仓库。
解除或更换仓库绑定
绑定成功后，仓库名称旁会显示解除绑定入口。
- 打开 版本控制 页签。
- 找到当前绑定的仓库名称。
- 单击解除绑定图标。
- 在“解除当前仓库绑定？”提示中单击确认。
- 页面显示“已解除仓库绑定”后，重新单击 绑定仓库，填写新的仓库或授权信息。
解除绑定只移除当前项目与 GitLab 仓库的关联，不会删除远程仓库，也不会删除项目已有的本地版本历史。
在终端中检查 Git 状态
熟悉 Git 的开发者可以在 AI 编程环境终端中使用命令检查仓库。常用的只读命令包括：
bash
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 重新绑定。
安全与协作建议
- Token 只授予完成同步所需的最小权限，并设置合理有效期。
- 不同成员使用各自的 GitLab 凭证，不共享个人 Token。
- Push 前检查待推送提交和远程分支，不使用强制推送覆盖团队提交。
- Pull 前先提交或备份本地修改。
- 处理冲突后必须重新运行测试、构建和预览。
- 不要把
.env、密钥、Token 或生产配置提交到远程仓库。