一、开发背景

在日常开发中，Git 提交是一个非常高频的操作。虽然 git commit 本身并不复杂，但在真实项目协作中，写好一次提交信息并不容易。

很多时候，一次代码修改会涉及多个文件。开发者需要先判断这次修改属于功能新增、问题修复、结构调整还是文档更新，再将这些内容组织成一条清晰的 commit message。如果提交信息写得过于简单，例如 update、fix bug、修改文件，虽然也能完成提交，但后续查看项目历史时，很难快速理解这次修改的真实目的。

IntelliGit 项目希望做的不只是普通 Git 图形化操作，而是在 Git 工作流中加入一定的智能辅助能力。基于这个目标，我在本阶段主要围绕提交模块进行了开发，尝试实现一个“智能提交”的功能雏形。

需要说明的是，当前阶段项目还没有正式接入外部大模型服务。虽然界面中已经提供了“AI 生成提交信息”和“分析变更分组”等入口，代码结构中也预留了智能分析服务层，但实际运行时主要走 fallback 本地模板降级逻辑。本阶段的重点不是验证模型效果，而是先把智能提交的前端入口、服务调用、结果展示、用户确认等基础流程跑通。

---

二、本阶段开发目标

本阶段主要围绕 5 月 20 日的提交内容展开，重点完成智能提交模块的初步建设。整体目标可以概括为：

1. 在提交面板中增加智能提交入口
2. 新增 smartCommitService 服务层
3. 设计 AI 分析与 fallback 降级的调用流程
4. 支持本地模板生成基础提交信息
5. 支持分析变更分组的 fallback 展示
6. 收敛提交面板的架构边界
7. 为后续接入真实 AI 服务预留扩展空间

也就是说，本阶段并不是一次性完成完整 AI 能力，而是先完成“智能提交工作流”的基本骨架。

当前设计思路是：

用户修改文件
→ 提交面板读取变更
→ 用户点击 AI 生成提交信息
→ 服务层判断 AI 是否可用
→ 如果 AI 不可用，则进入 fallback 降级
→ 生成基础提交信息或默认变更分组
→ 用户确认后继续执行提交流程

这样的设计可以保证：即使 AI 服务还没有正式接入，提交模块也不会因为缺少模型配置而完全不可用。

---

三、提交面板中的智能提交入口

本阶段首先在 IntelliGit 的提交面板中加入了智能提交相关入口。

从界面上看，用户可以在左侧看到当前仓库的文件变更状态，包括未暂存文件和已暂存文件。提交区域底部新增了两个主要操作按钮：

AI 生成提交信息
分析变更分组

这两个入口分别对应两个能力：

AI 生成提交信息：根据当前变更内容生成 commit message
分析变更分组：根据变更文件尝试拆分提交意图

虽然当前 AI 服务尚未正式配置，但这两个入口已经接入到实际提交面板中，可以用于验证用户交互流程。

图 1：IntelliGit 提交面板中的智能提交入口。左侧展示当前仓库的未暂存与已暂存文件，底部提供“AI 生成提交信息”和“分析变更分组”操作按钮。当前阶段 AI 服务尚未正式接入，功能主要通过 fallback 本地模板降级层完成流程验证。

---

四、smartCommitService 服务层设计

为了避免把智能提交逻辑全部写在 React 组件中，本阶段新增了 smartCommitService.ts，作为智能提交功能的服务层。

这个服务层的作用是把界面操作和具体业务逻辑隔离开。提交面板只负责触发操作和展示结果，而真正的提交信息生成、分组分析、fallback 降级等逻辑都放到服务层中处理。

这样设计有几个好处：

1. CommitPanel 组件不会过度膨胀
2. 智能提交逻辑可以独立维护
3. 后续接入真实 AI 服务时，不需要大幅修改界面层
4. fallback 逻辑和 AI 调用逻辑可以统一管理
5. 更符合前端组件与业务服务分层的设计思路

在功能结构上，smartCommitService 主要承担以下职责：

1. 读取当前暂存区或工作区变更
2. 判断是否存在可用的 AI 服务配置
3. 在 AI 不可用时进入 fallback 降级逻辑
4. 生成基础 commit message
5. 返回默认变更分组结果
6. 为后续真实模型接入预留统一调用入口

从代码结构角度看，这一步很重要。因为如果后续直接接入大模型 API，只需要重点替换服务层中“智能分析”的具体实现，而提交面板的按钮、状态展示和用户确认流程都可以继续复用。

---

五、fallback 本地模板降级逻辑

当前项目还没有正式接入 AI，因此智能提交功能实际运行时主要依赖 fallback 本地模板降级层。

fallback 的作用不是替代 AI，而是在 AI 不可用时保证流程不中断。也就是说，当系统检测到 AI 服务没有配置、模型调用失败或返回内容不可用时，不会直接报错终止，而是生成一个基础可用的结果。

例如，在当前截图中，暂存区存在 1 个文件时，点击“AI 生成提交信息”后，系统提示：

AI 服务未配置，已使用本地模板降级

同时生成了基础提交信息：

chore: 更新 1 个文件

图 2：AI 服务未配置时，系统自动进入本地模板降级模式，并生成基础提交信息“chore: 更新 1 个文件”。该结果说明智能提交功能在未接入外部模型时，仍然能够完成提交信息生成流程。

这个逻辑虽然简单，但意义比较明确：

1. 验证了按钮触发流程
2. 验证了服务层调用流程
3. 验证了结果返回和界面填充流程
4. 避免了 AI 未接入时功能完全不可用
5. 为后续真实 AI 生成结果保留了展示位置

从开发过程来看，我认为 fallback 层是智能提交模块中比较关键的一环。因为智能功能往往依赖外部模型服务，而外部服务可能受到配置、网络、接口权限等因素影响。如果没有降级处理，用户点击按钮后只会看到失败提示，整个功能体验会非常脆弱。

---

六、分析变更分组的 fallback 结果

除了提交信息生成，本阶段还加入了“分析变更分组”的入口。

理想情况下，分析变更分组应该由 AI 根据文件 diff 和修改意图，将当前变更拆成若干个提交组。例如：

feat：新增智能提交入口
refactor：调整提交面板结构
style：修改提交区域样式
docs：更新项目说明文档

这样可以帮助用户把一次复杂修改拆成多个更清晰的提交。

不过当前阶段 AI 服务尚未配置，因此分组功能同样走 fallback 降级逻辑。系统会将当前所有变更归为一个默认分组，并提示：

AI 不可用，所有变更归为一组

界面中显示的分组类型为：

图 3：分析变更分组的 fallback 结果。由于当前 AI 服务尚未配置，系统将所有变更归为一个 chore 分组，并提示“AI 不可用，所有变更归为一组”，用于验证分组展示、用户选择和后续暂存流程。

这里建议插入你发的“chore｜AI 不可用，所有变更归为一组”那张截图。

虽然当前 fallback 只能生成一个默认分组，但它已经把分组功能的前端结构搭建出来了。后续接入真实 AI 后，可以把 fallback 返回的单组结果替换成模型分析后的多组结果。

也就是说，当前分组功能已经完成了以下基础部分：

1. 分组按钮展示
2. 点击按钮触发分析
3. 服务层返回分组结果
4. 前端展示分组类型和说明
5. 用户可以选择分组
6. 后续可以基于分组执行暂存或提交信息生成

这为后续的智能分组升级打下了基础。

---

七、为什么要先做 fallback，而不是直接接入 AI

在开发过程中，我没有直接把重点放在接入某一个具体 AI 平台上，而是先完成 fallback 层和智能提交工作流，主要原因有三点。

第一，当前项目后续接入哪个 AI 服务还没有完全确定。如果过早绑定某一个模型接口，后续更换服务时可能需要修改大量代码。

第二，智能提交功能不仅仅是模型调用。它还包括前端入口、状态管理、暂存区读取、结果展示、用户确认、错误反馈等一整套流程。如果这些基础流程没有搭建好，即使模型能返回结果，功能体验也不完整。

第三，fallback 层可以作为测试和兜底能力。在 AI 未配置、调用失败或网络异常时，系统仍然能够给出一个基础结果，不会让用户操作中断。

因此，本阶段采用了比较稳妥的开发策略：

先搭建流程
再实现降级
最后接入真实 AI

这样的顺序可以降低开发风险，也能让每一步都有可验证的结果。

---

八、提交面板架构边界收敛

随着智能提交功能加入，提交面板的逻辑明显变多。如果所有业务逻辑都直接写在 CommitPanel 组件中，组件会变得越来越复杂。

因此，本阶段还对提交面板的架构边界进行了收敛。简单来说，就是把不同职责拆开：

CommitPanel：负责界面展示和用户交互
smartCommitService：负责智能提交和 fallback 业务逻辑
view model / selectors：负责状态读取和操作封装
store：负责全局状态管理

这样处理之后，提交面板不会直接承担过多复杂逻辑。后续如果要修改智能提交策略，只需要重点调整服务层；如果要调整界面样式，也不会影响底层提交逻辑。

这种结构虽然前期会多写一些代码，但对后续维护更友好。尤其是 IntelliGit 这类桌面端工具，功能会不断增加，如果早期不控制组件复杂度，后面很容易出现“一个组件里堆满所有逻辑”的问题。

---

九、本阶段不足

本阶段完成的是智能提交模块的雏形，还不是最终形态。当前仍然存在一些不足：

1. AI 服务尚未正式接入
2. fallback 提交信息比较基础，只能根据文件数量生成简单描述
3. fallback 分组只能将所有变更归为一组
4. 暂时无法根据真实 diff 内容判断修改意图
5. 还没有支持 hunk 级别或语义级别的提交拆分

因此，本阶段更准确的定位应该是：

智能提交功能入口与 fallback 闭环验证

而不是完整 AI 提交能力。

不过从项目开发角度看，这一步是必要的。因为只有先把用户操作路径和模块边界建立起来，后续接入真实 AI 服务时，才能更平滑地替换底层实现。

---

十、本阶段总结

本阶段我主要完成了 IntelliGit 智能提交模块的基础建设。虽然项目目前还没有正式接入外部大模型服务，但已经完成了智能提交入口、服务层结构、fallback 降级逻辑和分组展示流程。

本阶段主要成果包括：

1. 在提交面板中加入“AI 生成提交信息”入口
2. 在提交面板中加入“分析变更分组”入口
3. 新增智能提交服务层 smartCommitService
4. 实现 AI 未配置时的本地模板降级逻辑
5. 支持生成基础提交信息，例如“chore: 更新 1 个文件”
6. 支持分组功能的 fallback 结果展示
7. 将所有变更默认归为一个 chore 分组
8. 收敛提交面板的架构边界
9. 为后续接入真实 AI 服务预留扩展空间

整体来看，这次开发让 IntelliGit 的提交模块从普通手动提交，开始向智能辅助提交方向演进。当前 fallback 层虽然还不能真正理解代码语义，但它已经验证了智能提交的完整交互路径。

后续如果确定具体 AI 服务，可以在现有服务层基础上继续扩展，使系统真正根据 diff 内容生成更准确的提交信息，并进一步实现更细粒度的智能分组。