CommitLoom 使用教程：在 IntelliJ IDEA 中自动生成 Git 提交信息

写完代码，提交信息却经常只剩下 update、fix bug，或者还要把 diff 复制到聊天窗口，让模型帮忙总结。

我开发了一个 IntelliJ IDEA 插件 CommitLoom · 提交织语，把这一步放回日常的 Git 提交流程：在 Commit 窗口勾选本次修改，按需预览要发送的差异，再生成提交信息，直接填入 IDEA 原生的提交框。

这篇文章以 CommitLoom 1.0 为例，从安装和模型配置开始，走一遍完整使用流程，再介绍中英文切换、团队规范和常见问题。

使用前先确认：1.0 版面向 IntelliJ IDEA 2026.2.x（build 262），使用普通 Commit 窗口的勾选模式，暂不支持 Git 暂存区（staging area）模式。模型服务及 API Key 需要自行配置，调用费用和数据处理规则由所选服务商决定。

目录

• • [一、CommitLoom 适合做什么](#一、CommitLoom 适合做什么)
  • 二、安装插件
  • • [1. 从 Marketplace 安装](#1. 从 Marketplace 安装)
    • [2. 从 ZIP 安装](#2. 从 ZIP 安装)
  • 三、第一次配置模型
  • • [1. 填写连接信息](#1. 填写连接信息)
    • [2. 点击"自动识别并测试"](#2. 点击“自动识别并测试”)
    • [3. 设置实际用于生成的模型](#3. 设置实际用于生成的模型)
    • [4. 代理怎么选](#4. 代理怎么选)
  • 四、生成第一条提交信息
  • • 第一步：只勾选本次准备提交的改动
    • 第二步：按需预览待发送改动
    • 第三步：点击"生成提交信息"
    • 第四步：核对并正常提交
  • 五、界面语言和提交信息语言分别设置
  • 六、用项目规范统一团队风格
  • 七、速度、隐私和常见问题
  • • [1. 生成比较慢，先看耗时在哪里](#1. 生成比较慢，先看耗时在哪里)
    • [2. 代码会发送到哪里](#2. 代码会发送到哪里)
    • [3. 提示不支持 Git staging area](#3. 提示不支持 Git staging area)
    • [4. 改了模型，生成时怎么还是原来的](#4. 改了模型，生成时怎么还是原来的)
    • [5. 测试能通过，正式生成却失败](#5. 测试能通过，正式生成却失败)
  • 八、开始使用

一、CommitLoom 适合做什么

最常见的场景是：已经写好一组代码，现在需要为本次准备提交的改动写一条准确、规范的提交信息。

CommitLoom 的核心能力包括：

• 根据勾选的文件和代码块生成提交信息，支持新增、修改、删除和重命名等文本变更。
• 将结果填入 IDEA 原生 Commit Message 输入框，保留原有提交流程。
• 在发送前，通过原生彩色 Diff 查看本次准备发送的差异、生成请求和生效规范。
• 保存多套模型配置，在提交窗口切换使用。
• 支持 Chat Completions、Responses、Anthropic Messages 三种接口协议。
• 分别设置插件界面语言和提交信息输出语言。
• 按需使用 .commitloom.json 共享团队规范，或在本地参考近期提交风格。

日常流程可以概括为：

勾选本次改动 → 预览差异（按需）→ 生成提交信息 → 人工核对 → 正常提交

生成完成后仍由你决定是否提交。 插件不会自动执行 Git commit，也不会自动 push。生成结果也不等于代码评审结论或测试报告。

二、安装插件

1. 从 Marketplace 安装

插件页面：

CommitLoom --- JetBrains Marketplace

在 IDEA 中进入：

Settings → Plugins → Marketplace

搜索 CommitLoom，确认发布者为 hulei，安装后按 IDE 提示完成操作。

如果搜索不到，先核对两个地方：

1. 当前选择的是 Marketplace，而不是 Installed 列表。
2. IDEA 版本是否在插件支持范围内。1.0 版针对 2026.2.x，旧版 IDEA 不能靠离线安装绕过兼容限制。

2. 从 ZIP 安装

已有插件 ZIP 时，可以使用：

Settings → Plugins → 齿轮菜单 → Install Plugin from Disk

选择 commitloom-1.0.zip，无需解压，也不要选择整个源码目录。离线安装同样需要满足 IDE 版本要求。

三、第一次配置模型

安装后打开：

Settings → CommitLoom

CommitLoom 是设置列表中的一级入口。首次使用先新增一套模型配置。

1. 填写连接信息

配置项	怎么填
配置名称	方便自己识别的名称，例如"日常提交模型"
Base URL	模型服务商提供的 API 根地址或完整接口地址，不是网页聊天地址
模型 ID	服务商控制台或 API 文档中实际可调用的模型标识
API Key	对应 API 服务的密钥
接口协议	不确定时先选"自动识别（推荐）"
代理	能直接访问接口时保留"直接连接"
请求超时	根据网络和模型响应速度设置

例如，接入 DeepSeek 的 Chat Completions 接口时，官方 API 根地址为 https://api.deepseek.com，模型 ID 填写自己账号当前可用的型号。具体型号和权限以服务商文档及控制台为准。

网页端会员、网页登录状态和 API 调用权限不是同一个配置。 这里需要填写 API 服务使用的地址、模型 ID 和密钥，不要直接粘贴聊天网站的网址。

2. 点击"自动识别并测试"

填写好地址、模型 ID 和 Key 后，点击 自动识别并测试。

这个测试会向当前配置的服务发送简短提示词，确认接口是否能够工作；测试不会携带仓库 diff，但可能产生少量 API 调用费用。成功后检查识别出的协议，再点击 Apply / OK 保存。

如果测试失败，优先检查地址、模型 ID、Key、账号额度和网络，不要只反复切换协议。

3. 设置实际用于生成的模型

这是最容易漏掉的一步：

在模型列表中选中一项，是在编辑这套配置；点击"设为生成模型"，才会切换实际用于生成的模型。

确认星号标记移动到目标配置，再点击 Apply / OK。之后也可以通过 Commit Message 工具栏中的模型菜单切换已保存的配置。

4. 代理怎么选

新建模型配置默认使用 直接连接。另外还可以选择"跟随 IDEA 代理设置"或"自定义 HTTP 代理"。

如果接口本身能访问，就保留直接连接。需要代理时再按实际网络配置，不要照抄别人的 127.0.0.1 和端口；这个地址指向的是你自己的电脑，前提是本机确实有对应代理服务。

四、生成第一条提交信息

第一步：只勾选本次准备提交的改动

打开项目的 Commit 工具窗口，勾选要纳入当前提交的文件。如果一个文件里混有几项不同修改，也可以按 IDEA 支持的方式只纳入相关代码块。

比如这次只修复"订单列表分页异常"，就先勾选与这个问题有关的修改。未准备提交的其他功能，可以留到下一次处理。

选得准确，生成的提交信息才有明确主题；同一批 diff 里混入越多无关内容，结果越难概括。

第二步：按需预览待发送改动

在 Commit Message 工具栏点击 预览待发送改动。

插件会打开 IDEA 原生的只读 Diff，使用新增、删除等颜色区分变更，并展示本次生效的规范和生成请求。预览本身不调用模型。

建议重点看三件事：

1. 当前内容是否就是本次准备提交的修改。
2. 是否出现了不该发送的业务信息或敏感内容。
3. 是否有文件被跳过、内容被截断，以及生成要求是否符合预期。

预览针对当次读取的快照。预览后如果修改了源码或勾选范围，应重新预览；后续生成会重新读取当时的选中内容。

第三步：点击"生成提交信息"

点击 生成提交信息，插件会在后台请求所选模型，并显示进度。等待期间可以取消请求。

正常完成后，生成结果会直接填入原生提交框。例如，启用 Conventional Commits 和变更要点后，格式可能如下：

fix(order): 修复订单列表分页参数未生效的问题

- 将当前页码和每页条数传递给查询接口
- 切换筛选条件时重置页码

以上仅用于演示输出格式，真实内容取决于本次勾选的 diff。

第四步：核对并正常提交

核对标题、scope 和变更要点是否准确，再使用 IDEA 原来的 Commit 或 Commit and Push 操作。

如果生成期间你修改了提交框、勾选范围或相关文件，插件会保留你的新内容，单独展示生成结果供复制，避免覆盖正在编辑的信息。

五、界面语言和提交信息语言分别设置

这两个选项解决的是不同问题：

设置	控制什么	示例
界面语言	插件按钮、设置项和提示文字	中文界面或英文界面
输出语言	交给模型的提交信息语言要求	简体中文、English 或自定义语言

因此，你可以使用中文界面，为国际团队生成英文提交信息；也可以使用英文界面，为中文项目生成中文提交信息。

在生成规则里，还可以设置：

• 是否采用 Conventional Commits。
• 是否在标题后附加变更要点；关闭后只生成标题。
• 额外生成要求，例如"标题简洁，正文只描述可从 diff 确认的变更"。

启用 Conventional Commits 时，结构通常为：

type(scope): subject

例如 feat 表示新增功能、fix 表示问题修复。scope 可以帮助说明影响模块，但应与实际改动一致。

六、用项目规范统一团队风格

个人使用时可以先保留应用设置。团队需要统一语言、标题长度和术语时，再启用 遵循项目规范并参考近期提交风格；该选项默认不勾选。

在 Git 仓库根目录创建 .commitloom.json：

{
  "version": 1,
  "language": "简体中文",
  "conventionalCommits": true,
  "includeBody": true,
  "subjectMaxLength": 72,
  "scopes": ["order", "user", "payment"],
  "terms": {
    "账户": "账号"
  }
}

这个示例表达的是：使用简体中文、采用 Conventional Commits、附带正文、标题建议不超过 72 个字符，优先参考给出的 scope，并统一"账号"的表述。

把文件纳入版本控制后，团队成员就能共用这份规范。不要在这里写 API Key、接口地址或其他凭据；它用于描述提交风格，模型连接仍在每个人的插件设置中配置。

启用该功能后，设置优先级为：

项目中显式声明的规范 → 有足够样本的近期提交风格 → 应用偏好

近期提交风格在本地统计。插件不会把历史提交标题原文、作者或完整日志发送给模型；预览页面可以检查最终生效的规范。

七、速度、隐私和常见问题

1. 生成比较慢，先看耗时在哪里

完成通知会分别展示准备时间和模型请求时间：前者包括读取勾选改动、构建请求等工作，后者包括网络、服务端处理和响应解析。

如果主要耗时在模型请求阶段，可以：

• 减少无关勾选内容，让每次提交主题更集中。
• 换用账号可用、响应更快的模型，对相同 diff 比较效果。
• 检查当前模型的代理和网络连接。
• 对插件已适配且支持控制思考的模型，按需关闭深度思考。

"允许深度思考"按模型配置保存，但不同服务商和协议支持的参数不同。对于未适配的模型，不能仅凭取消勾选就认定远端思考已经关闭。

2. 代码会发送到哪里

点击生成时，插件会把勾选修改的文本差异、路径和必要上下文，以及生效的生成要求，直接发送到你配置的模型服务。

插件没有开发者运营的中转后端或遥测，API Key 使用 IDEA 的凭据库保存。本地预览不联网，普通设置编辑和切换模型也不会自动调用模型。

这不代表代码不会离开电脑：使用远程模型时，差异会发送给该服务商。请按照项目要求选择服务，并在发送前检查范围。常见敏感文件过滤不能保证识别所有藏在业务代码里的密钥。

3. 提示不支持 Git staging area

1.0 版使用普通 Commit 窗口的勾选范围。启用 Git 暂存区模式时，插件会提示并停止读取、发送。

需要使用当前版本时，请在 IDEA 的版本控制设置中关闭暂存区模式，再按普通 Commit 窗口操作。

4. 改了模型，生成时怎么还是原来的

先看模型配置的星号标记。仅选中列表项不会切换生成模型，需要点击 设为生成模型，并保存设置；也可以在提交窗口的模型菜单中切换。

5. 测试能通过，正式生成却失败

测试使用的提示词很短，正式生成包含实际 diff，输入大小和处理时间不同。可以先减少勾选内容、检查请求超时和服务商额度，再按报错排查。

正式生成失败后，插件不会自动换协议重复发送这份业务 diff。

八、开始使用

第一次使用可以先完成四件事：配置一套模型并测试，设为生成模型，勾选一组主题明确的修改，然后预览并生成。

等这个流程用顺手后，再添加多模型切换和团队规范。提交前仍保留最后一次人工核对，让生成结果准确对应这次代码改动。

• 插件安装页面：CommitLoom
• 项目说明与使用文档

如果遇到配置或使用问题，欢迎在评论区说明 IDEA 版本、接口协议和经过脱敏的报错信息，请勿贴出 API Key 或业务敏感代码。