Git Assist AI
Git Assist AI 是 VS Code 中的 AI Git 助手,帮助你生成提交信息、审查分支合并、分析并解决代码冲突、创建和推送标签。在源代码管理面板中完成日常操作,使用自己配置的模型和 API 服务。
支持兼容 Chat Completions 或 Responses 协议的接口,包括符合协议的本地、自建服务。核心功能无需 GitKraken、Copilot 或 Codex CLI 账户。
功能介绍
| 功能 |
可以做什么 |
| AI 提交信息 |
根据 Git diff 生成提交描述,默认使用中文 Conventional Commits;参考近期提交风格及可读取的项目提交规则,直接填入原有提交输入框。 |
| 合并前审查 |
选择“来源分支 → 合入目标”,检查逻辑缺陷、安全问题、兼容性、数据与并发、性能回退,以及与具体缺陷有关的测试遗漏。 |
| 变更总结 |
选择“总结并审查”或“仅总结”,查看变更说明、相关文件,以及模型提供的有效前后流程。 |
| 问题定位与修复辅助 |
问题按文件分组、按 P0–P3 标记优先级;点击进入原生 diff 和行内问题卡片,支持逐条查看、忽略、恢复及准备修复提示。 |
| 合并冲突预检 |
在合并前检查所选分支是否可能出现 Git 冲突,与 AI 发现的代码问题分别展示。 |
| 标签发布 |
选择测试 / 生产环境,按模板推荐标签名;使用简短 AI 说明或手写说明,确认后先推送对应代码,再推送单个附注标签。支持选配预发、本地创建和失败重试。 |
| 实际冲突处理 |
检测 merge、rebase、cherry-pick 后的未解决冲突,分析双方意图与冲突原因,预览解决方案后单个或批量应用,支持撤销本次应用和标记已解决。 |
提交审查与冲突处理位于源代码管理 → Git Assist · 智能审查:上方“实际合并冲突”处理当前仓库中的冲突,下方“合并前审查”比较所选分支。打开面板和刷新冲突状态不会调用 AI;点击生成、审查或分析后才会发送请求。标签操作使用独立的 Git Assist · 标签发布 面板,只有点击“AI 生成说明”才会调用模型。
应用场景
| 场景 |
推荐用法 |
| 开发完成,准备提交代码 |
暂存本次修改,生成提交信息,检查描述后提交。 |
| 功能分支准备合入 main / develop |
选择功能分支为来源、main / develop 为目标,运行“总结并审查”,同时了解变更内容和潜在问题。 |
| 接手他人的分支或整理评审说明 |
使用“仅总结”快速了解分支改动,再根据相关文件查看代码差异。 |
| 发布前或公共接口调整后检查风险 |
在审查要求中补充兼容性、金额计算、事务一致性等关注点,使用“仅审查”检查具体问题。 |
| 合并、变基或挑选提交时出现冲突 |
在“实际合并冲突”中分析文件,查看双方代码和解决前后差异,确认方案后应用。 |
| 为某个版本创建标签并交给已有发布流程使用 |
打开“标签发布”,选择已提交版本,填写标签名和说明,预览后推送。 |
| 先准备标签,稍后再推送 |
选择“仅创建本地标签”;之后从最近标签点击“推送”,继续使用原提交和说明。 |
| 同时出现多个文本冲突 |
使用“分析全部 → 预览全部 → 应用已预览方案”,检查结果后逐个标记已解决。 |
使用方法
1. 安装与准备
- 使用 VS Code 1.95 或更新版本,确保 Git 已安装且内置 Git 扩展已启用。
- 在扩展面板右上角菜单选择 Install from VSIX… / 从 VSIX 安装…,选中 Git Assist AI 的
.vsix 文件。
- 打开受信任的本地 Git 项目,按下
⌘⇧P(macOS)或 Ctrl+Shift+P(Windows / Linux),需要 AI 功能时运行 Git Assist: Configure API,按下文完成配置。手写标签说明并创建 / 推送标签无需配置 AI。
- 打开源代码管理面板。多个仓库时,使用对应仓库的按钮,或在提示中选择需要操作的仓库。
2. 生成提交信息
- 暂存修改:先暂存准备提交的文件或代码片段。
- 生成描述:点击源代码管理标题栏中的 ✨,或运行 Git Assist: Generate Commit Message。
- 检查并提交:结果填入 Git 原有提交输入框,你可以继续编辑,再使用 VS Code 的提交操作完成提交。
优先使用暂存区内容;暂存区为空时,使用已跟踪文件的工作区差异。新建但尚未跟踪的文件需要先暂存。生成提交信息只填写文字,暂存、提交和推送由你操作。
默认参考最近 10 条非合并提交、根目录 AGENTS.md 和可静态读取的提交钩子规则,最终提交仍以项目 Git hooks 校验为准。生成期间代码或提交输入框发生变化时,结果会另开文档供你查看。
3. 进行合并前审查
- 打开面板:展开 Git Assist · 智能审查,找到“合并前审查”;也可运行 Git Assist: Review Merge / 合并审查。
- 选择分支:例如将
feature/login 设为“来源分支”,将 main 设为“合入目标”。支持本地分支和远端跟踪分支,无需切换当前分支。需要最新远端内容时,先执行 Fetch / 提取。
- 选择模式:使用“总结并审查”“仅审查”或“仅总结”,然后点击 开始审查。审查过程中可以停止,完成后可以重新审查。
- 阅读结果:点击摘要查看变更说明和相关文件;点击问题进入原生 diff,查看触发条件、影响与修复建议。可用上一个 / 下一个连续查看,也可忽略或恢复问题。
- 跟进修复:点击单个问题的 修复 或 修复所有问题,生成带有问题与代码上下文的 Markdown 提示,并尝试填入 VS Code Chat。你可以在聊天工具中发起修复,也可复制文档到其他 AI 编码工具。
审查针对所选分支的已提交内容,不会包含未提交的工作区修改、暂存区修改或未跟踪文件。需要检查这些修改时,先完成提交。分支和模式按仓库记忆;忽略状态仅在本次审查中有效,重新审查会重置。
普通审查中的“修复”用于准备修复上下文,需要你在所用 AI 工具中继续操作;它不会自动发送聊天或应用代码修改。修复完成后先验证代码,提交后再运行分支审查。
Git 冲突预检需要 Git 2.38 或更新版本。检测不可用或仓库使用不支持的合并配置时,面板会显示“冲突检测未完成”,AI 审查仍可进行。审查使用分支差异及相关文件上下文,不会遍历整个仓库调用关系,也不自动运行测试;未发现问题不代表所有行为均已验证。
4. 分析并解决实际冲突
当 Git 操作产生未解决冲突时,面板上方的“实际合并冲突”会列出文件。也可运行 Git Assist: Resolve Conflicts / 智能解决冲突 进入该区域。
- 分析:保存冲突文件,点击 分析冲突 或 分析全部。AI 根据共同祖先、当前方、传入方和当前文件,解释冲突原因并提出方案。
- 预览:点击 查看方案 或 预览全部,阅读双方改动意图,打开双方代码对比或解决前后 diff。rebase 时,当前方是变基目标,传入方是正在重放的提交,界面会提示这一含义。
- 应用:查看方案后,点击 应用方案 或 应用已预览方案。只替换冲突块,保留块外代码;应用后文件仍未暂存。需要业务决策的方案会列出待确认问题,供你人工处理。
- 验证或撤销:检查修改并运行项目测试。需要恢复时,点击 撤销本次应用;若文件或 Git 状态已变化,扩展会停止操作并提示,避免覆盖后续编辑。
- 标记并继续:确认结果后,点击 标记已解决。这一步会暂存整个文件,包括该文件中冲突块之外的修改。之后由你提交合并,或继续 rebase / cherry-pick,再按需要推送。
撤销记录仅在当前窗口会话内有效;标记已解决或重载窗口后失效。已手动解决冲突的普通文本文件,也可直接标记已解决。
当前支持含完整冲突标记的 UTF-8 普通文本文件,包括双方修改和双方新增,兼容 diff3 标记及 CRLF 换行。删除/修改、复杂重命名、文件模式差异、二进制、符号链接与子模块等情况会提示人工处理。应用前会检查残留冲突标记,JSON 文件额外检查语法;其他语言的编译和项目测试由你执行。
5. 创建和推送标签
入口:源代码管理 → Git Assist · 标签发布,或命令 Git Assist: Publish Tag / 标签发布。
- 选择环境:默认只有“测试、生产”。标签名按环境模板自动推荐;版本可从分支名称推导,也可点击“修改版本”。可以手动修改名称,或点击“恢复推荐”。
- 设置模板:点击“设置模板”,分别填写测试、生产模板,预发为选填;留空时不显示预发。面板展示当前版本下的示例,保存到当前项目的 VS Code 设置,也可在插件设置中配置用户级默认值。
- 编写说明:手动填写,或在“AI 生成说明”左侧选择基准标签后生成。默认按模板寻找最近祖先标签;选择“不选标签”时,只概括目标提交的变化。
- 创建并推送:点击后自动查询远端并显示确认页,核对标签名、目标提交、代码推送分支、说明和实际地址,再确认。只在本地准备标签时,选择“仅创建本地标签”。
- 继续操作:成功后可再建一个标签;本地标签可稍后推送。推送失败保留已创建的标签,可核对状态并重试。
AI 说明规则:优先一句不超过 60 字的摘要,必要时补充最多 3 条要点,每条不超过 40 字,总长不超过 200 字。合并重复内容,描述实际功能、修复和必要的兼容性影响,不罗列提交、文件路径或部署步骤。格式或长度不符时自动重新精简一次,仍不符合则保留原说明;不会直接截断文字。没有代码变化时直接提示无变更。手写说明不受这套 AI 长度规则限制,最多 20000 字符。
推送顺序:先确保标签对应的已提交代码在所选远端的分支上,再推送标签。通常使用所选本地分支及其同远端的跟踪分支;也可在“提交与远端”中选择代码推送分支。代码已在远端时直接进行标签操作。代码推送失败、分支分叉或无法核对时停止,不强推、不继续推标签。代码推送成功而标签操作失败时,已推送的代码保留,修正问题后可重试标签。
标签只包含所选版本的已提交内容;未提交和未保存的修改需先自行提交,插件不会自动提交这些修改。默认允许针对已提交版本创建标签;团队需要干净工作区时可启用 gitAssist.release.requireCleanWorktree。正在 merge / rebase / cherry-pick 或存在冲突时,先完成或中止对应操作。
“提交与远端”“查看比较变更”“最近标签”默认收起。支持选择本地 / 远端分支或已有标签的固定提交,无需切换工作分支;多个 push URL 只使用选中的地址。缺少远端提交或基准对象时,点击“获取所选版本”。这个操作只下载所选对象,不切换分支、不覆盖本地标签。
打开面板只读取本地信息;本地创建无需联网。序号按对应模板下全部已读取的本地和远端标签计算最大值加一;尚未查询远端时先按本地推荐。推送前重新查重,不覆盖同名标签,不顺带推送其他标签或未选中的提交。Git 原有身份认证、推送 hooks 和签名配置继续生效;签名失败停止操作。
比较基准默认从最多 80 个候选中寻找最近祖先,也可手动指定;基准存在历史分叉时,比较区列出双方独有提交,AI 按实际差异总结。最近标签显示前 40 个,序号查重仍使用全部已读取标签。已有附注标签在重试时保留原提交和说明;轻量标签和标签删除使用 Git 自身工具处理。
如何配置
首次连接 API
在命令面板运行 Git Assist: Configure API,依次填写:
| 配置项 |
填写说明 |
| API 地址 |
使用服务商提供的 Base URL,例如 https://your-provider.example/v1;也可以填写完整的 /chat/completions 或 /responses 接口地址。 |
| 接口类型 |
根据服务商支持的协议选择 chat-completions 或 responses。 |
| 模型名称 |
填写服务商实际支持的完整模型 ID。 |
| 认证方式 |
通常选择“使用 API Key”;不要求认证的本地、自建接口可选择“无需 API Key”。 |
| API Key |
在向导中输入,保存到 VS Code SecretStorage,不写入项目文件或 settings.json。 |
扩展会按协议补上接口路径,但不会自动补 /v1 等版本前缀;请按服务商文档填写地址。API Key 与完整接口地址关联,更换地址或协议后可能需要重新输入。
提交生成、合并审查、冲突分析和标签说明共用上述 API 与模型。地址、模型和认证方式使用用户级配置。需要更换 Key 时重新运行配置向导;需要移除时运行 Git Assist: Remove API Key for Current Endpoint。
调整语言和项目要求
在 VS Code 设置中搜索 @ext:dewan.git-assist 查看全部选项,也可编辑用户级 settings.json。下面是可复制的示例,请替换 API 地址和模型名称,并通过配置向导保存 Key:
{
"gitCommitCustom.baseUrl": "https://your-provider.example/v1",
"gitCommitCustom.apiType": "chat-completions",
"gitCommitCustom.model": "your-model-id",
"gitCommitCustom.requireApiKey": true,
"gitCommitCustom.language": "简体中文",
"gitCommitCustom.customInstructions": "使用 type(scope): 中文描述,标题简洁,不添加 emoji。",
"gitCommitCustom.maxDiffCharacters": 300000,
"gitCommitCustom.timeoutSeconds": 120,
"gitAssist.review.customInstructions": "重点检查公共接口的向后兼容性、金额计算和事务一致性。",
"gitAssist.review.maxContextCharacters": 300000,
"gitAssist.review.timeoutSeconds": 180,
"gitAssist.release.templates.test": "v{version}.alpha.{seq}",
"gitAssist.release.templates.production": "v{version}.rc.{seq}",
"gitAssist.release.templates.staging": "",
"gitAssist.release.remote": "origin",
"gitAssist.release.requireCleanWorktree": false
}
为兼容已有设置,部分配置键保留 gitCommitCustom.* 前缀,扩展标识为 dewan.git-assist。语言、提交附加要求和审查附加要求也支持工作区级配置。
| 设置 |
默认值 |
用途与范围 |
gitCommitCustom.language |
简体中文 |
提交信息、审查、冲突分析和标签说明的输出语言。 |
gitCommitCustom.customInstructions |
空 |
提交信息的附加要求,例如格式、措辞或是否使用 emoji。 |
gitCommitCustom.maxDiffCharacters |
300000 |
提交生成、合并审查和标签说明的 diff 上限,可设为 1000–1000000 字符。 |
gitCommitCustom.timeoutSeconds |
120 |
提交生成和每次标签说明请求超时,可设为 10–300 秒。 |
gitAssist.review.customInstructions |
空 |
合并审查和冲突分析的附加要求,例如兼容性与业务约束。 |
gitAssist.review.maxContextCharacters |
300000 |
合并审查的额外代码上下文预算,以及冲突分析的完整上下文预算,可设为 1000–1000000 字符。 |
gitAssist.review.timeoutSeconds |
180 |
合并审查和冲突分析请求超时,可设为 10–600 秒。 |
gitAssist.release.templates.test |
v{version}.alpha.{seq} |
测试模板,支持用户 / 工作区配置。 |
gitAssist.release.templates.production |
v{version}.rc.{seq} |
生产模板,支持用户 / 工作区配置。 |
gitAssist.release.templates.staging |
空 |
预发模板,选填。配置后才显示预发环境,例如 v{version}.beta.{seq}。 |
gitAssist.release.remote |
origin |
标签面板优先选择的远端,在最终确认页核对实际地址。 |
gitAssist.release.requireCleanWorktree |
false |
启用后,有未提交或未保存修改时阻止标签操作,支持工作区级设置。 |
模板必须包含一个 {seq},可选一个 {version};不包含版本变量的模板按整个模板累计序号,例如 release-{seq}。未知变量、非法 Git 标签名和重复变量会提示修正。
常见配置与使用问题
- 接口连接失败或模型不可用:核对完整 API 地址、接口协议、模型 ID 和认证方式,必要时重新运行配置向导。
- 请求超时:根据操作调整对应超时设置,或缩小本次变更范围。模型服务需支持相应的输入长度。
- 提示 diff 或上下文超限:可在设置允许范围内提高预算,或拆分变更。来源 diff 超限会停止请求;合并审查最多支持 150 个改动文件,额外快照受到限制时会在结果中说明。冲突文件的每个版本最多 300000 字节,完整上下文超限会停止分析。
- 审查没有包含最新修改:检查修改是否已提交到所选来源分支;远端跟踪分支需要先 Fetch 才能更新本地快照。
- 找不到审查面板:确认已打开受信任的 Git 项目、内置 Git 扩展已启用,再运行合并审查命令。面板较小时可收起其他区域或拖动分隔线扩大显示空间。
调用 AI 时,提交生成会发送所选 diff、近期提交标题及提交规则;合并审查会发送分支差异、相关代码快照和项目规则;冲突分析会发送冲突文件的三方版本及工作区内容;标签说明会发送目标提交信息、基线比较和所选已提交差异。内容均交由你配置的 API 服务处理。