# commitloom

**Repository Path**: buxingzhe/commitloom

## Basic Information

- **Project Name**: commitloom
- **Description**: IDEA插件，根据git提交记录自动生成commit信息
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: plugin

## README

# CommitLoom · 提交织语

CommitLoom 根据 IntelliJ IDEA 提交窗口中**勾选纳入提交的修改**生成纯文本提交信息，并填入原生 Commit Message 输入框。

## 已实现

- 在 Commit Message 工具栏提供纯文本生成、差异预览和模型切换入口。
- 生成结果直接回填；若生成期间改动了勾选范围或提交框，则保留新内容并单独展示结果。
- 用 `.commitloom.json` 共享项目规范，本地参考近期提交风格；预览实际请求和生效规范。
- 多套模型配置：独立 Base URL、模型 ID、API Key、代理和请求超时。
- 自动识别并验证接口协议，支持 OpenAI 兼容 Chat Completions、OpenAI Responses、Anthropic Messages。
- 每个模型独立配置深度思考开关；适配的千问官方混合思考模型可明确关闭思考。
- 纳入勾选的已跟踪文件、新文件和部分代码片段；处理新增、修改、删除和重命名。
- 中文/英文和自定义语言；Conventional Commits；标题与变更要点列表、仅标题及额外生成要求。
- API Key 使用 IDEA Password Safe 保存，普通偏好与凭据分开存储。
- 后台生成、进度和取消；区分鉴权、限流、服务错误、网络和超时；正式生成失败不自动重试。
- 生成期间修改了文件、勾选范围或提交信息时，展示结果供复制，保留用户的新内容。
- 发送前可本地预览实际 diff；过滤常见凭据文件和私钥，限制请求及响应大小。

**支持范围：**1.0 版使用普通 Commit 窗口的文件/代码块勾选。Git 暂存区（staging area）模式暂不支持，插件会提示并停止读取、发送；使用前请在 IDEA 的版本控制设置中关闭暂存区模式。

## 本地使用

1. 在项目目录运行 `.\gradlew.bat buildPlugin`，构建得到 `build/distributions/commitloom-1.0.zip`（完整命令见下方“日常打包”）。
2. IDEA → Settings → Plugins → 齿轮 → **Install Plugin from Disk**，选择 ZIP，按 IDE 提示重启。
3. Settings → **CommitLoom**（左侧一级入口，与 Tools 平级），新建模型配置，填写接口、模型 ID、Key。选中配置后点击列表下方的**设为生成模型**，确认星号移到该模型，再点击应用或 OK 保存；仅选中列表项是在编辑配置。
4. 协议可保留**自动识别（推荐）**，点击**自动识别并测试**；成功后会选中已验证协议，再点击应用保存。
5. 在 Commit 窗口勾选文件，点击**生成提交信息**，生成的纯文本会直接填入提交框。

可先通过 `runIde` 在独立沙箱中试用，避免影响日常 IDEA 的插件和配置。

### 差异预览

点击**预览待发送改动**，可在 IDEA 原生只读 Diff 中逐块查看勾选差异，以及本次生效的项目规范和完整生成请求。预览不会调用模型；代码内容只来自本次冻结快照，不读取未勾选的工作区内容。

### 项目共享规范

在所选 Git 仓库根目录放置 `.commitloom.json` 并纳入版本控制，团队即可共用规范。本仓库的文件也是可用示例：

```json
{
  "version": 1,
  "language": "简体中文",
  "conventionalCommits": true,
  "includeBody": true,
  "subjectMaxLength": 72,
  "scopes": ["core", "ide", "settings"],
  "terms": {"账户": "账号"}
}
```

字段均可省略；版本默认 1，标题建议上限默认 72、允许 20–200 个 Unicode 字符。`scopes` 是相关性优先的候选列表，`terms` 是术语替换偏好，各最多 32 项。文件最多 16 KB，拒绝符号链接、未知字段和错误类型；文件不支持命令、模型端点和凭据。无效配置会提示修正，不静默发送与规范不一致的请求。

优先级为**项目显式规范 → 有足够样本的近期提交风格 → 应用偏好**。插件最多在本地读取最近 30 条非合并提交标题；至少 5 个样本、某格式或语言达到 60% 时才推断 Conventional Commits 和中文/英文，并提取候选 scope。原始提交标题、作者和历史正文不会发给模型，只发送推断后的风格值。正文开关不会从标题猜测。多个仓库同时勾选时，仅采用 IDEA 项目根目录规范，不混用各仓库历史。

“遵循项目规范并参考近期提交风格”默认不勾选，只使用应用偏好；需要时可在设置中手动开启。点击预览可查看生效规范和生成请求；预览本身不访问模型。

### 接口配置示例

| 服务 | 协议 | Base URL | 模型 ID |
| --- | --- | --- | --- |
| DeepSeek | Chat Completions | `https://api.deepseek.com` | 服务商提供的 ID，如 `deepseek-chat` |
| 通义千问兼容接口 | Chat Completions | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 服务商提供的 ID |
| OpenAI | Responses / Chat Completions | `https://api.openai.com/v1` | 账号可使用的模型 ID |
| Anthropic | Messages | `https://api.anthropic.com/v1` | 账号可使用的 Claude 模型 ID |
| 本地服务 | 对应服务支持的协议 | `http://127.0.0.1:端口/v1` | 本地模型 ID |

可以填 API 根路径或完整调用地址；插件会按协议拼接接口。API Key 留空会保留已保存的 Key，勾选清除可用于无鉴权本地服务。仅本机 HTTP 可用，远程服务要求 HTTPS。

**代理：**新建模型默认直接连接，也可选择跟随 IDEA 或自定义无认证 HTTP 代理；已有配置保留原代理选择。需要代理认证的环境建议先验证服务商访问方式；当前未接入 IDEA 凭据库中的代理认证。TUN 和系统路由仍可能影响“直接连接”。

### 自动协议与深度思考

填写 URL、模型 ID、Key 后点击“自动识别并测试”，插件会先参考完整接口路径、已有选择和已知服务地址，再把模型名作为辅助线索，最多验证三种不同协议。模型名和模型列表本身无法证明协议，网关可以把同一模型包装成不同接口。

探测只发送简短的 OK 测试，不发送仓库 diff；不更换你配置的主机，也不跟随重定向。路径、参数、鉴权头不匹配时可换下一种协议；限流、权限、余额、服务异常和网络错误不会触发更多候选请求。候选共用一次超时预算，成功后自动矫正下拉框，点击应用才保存。多个成功测试可能产生少量费用，编辑表单、打开设置和切换模型不会联网。

若直接以“自动识别”模式生成，会先探测，再将业务 diff 发给已确认的协议一次。同一配置的确认结果在当前 IDE 进程内缓存最多 10 分钟，避免每次生成都多发测试请求；缓存最多 128 项，按完整配置、Key 的摘要和 IDEA 代理选择器区分，不保存原始 Key、响应文本或仓库内容。改动配置或 Key、确认过期及正式请求失败后，下一次自动生成会重新确认。显式点击测试始终发送真实测试请求。也可先测试并应用具体协议，之后直接调用；正式生成出错不自动换协议重发。测试期间修改参数或切换配置，旧结果不会覆盖当前表单。

“允许深度思考”按每个模型配置保存，默认不勾选。对已适配的千问官方 Chat Completions 混合思考型号（包括 `qwen3.8-max` 和 `qwen3.8-max-0902`），关闭时发送 `enable_thinking:false`，开启时发送 `true`。支持北京/新加坡兼容接口、文档列出的业务空间域名，以及套餐内已适配型号的 Coding Plan 地址。

未知网关、未适配模型、其他协议或纯思考模型不会被硬塞千问扩展参数；界面会显示能力说明，未适配时沿用服务商默认，不能据取消勾选就认定远端思考已关闭。型号及接口支持范围来自官方文档，不根据任意 `qwen*` 前缀猜测。开启思考可能增加耗时和 Token 消耗。

### 提交信息格式与耗时

在 Settings → CommitLoom 中选择“简体中文”，Conventional Commits 和“标题后附变更要点”默认勾选，生成规则会要求如下纯文本格式：

```text
feat(organization): 支持组织树及成员查询包含下级部门

- 新增 includeChildren 参数，按需返回完整子树
- 成员查询支持跨部门去重
```

示例仅说明格式，实际内容来自本次勾选的 diff。要点数量按改动决定；不会固定凑条数或仅凭提示词宣称测试通过。取消正文选项后只生成一行标题。

生成期间会显示模型等待秒数及发送的文件数、字符数，完成后通知分别列出准备时间和模型请求时间。准备包含任务排队、读取所选改动、凭据和构建提示词；模型请求包含客户端初始化、网络、远端处理及响应解析。批量申请跟踪器可减少本地界面线程往返，实际耗时需要在当前项目测量。

若耗时主要在模型请求，`qwen3.8-max` 可先取消勾选深度思考；其服务端默认开启思考。也可保持千问北京地域的协议、地址、Key 不变，试用 `qwen-flash`，使用相同勾选范围对比速度与生成质量。模型权限以账号为准，切换不会自动调用 API。`qwen-plus` 和 `qwen-flash` 默认已不思考，不能据此把所有慢请求归因于思考；当前没有固定提速倍数。改动越多模型输入越长，建议只勾选本次要提交的内容。

参考：[千问深度思考说明](https://help.aliyun.com/zh/model-studio/deep-thinking)、[百炼模型价格与型号](https://help.aliyun.com/zh/model-studio/model-pricing)。

## 开发与构建

- 首版目标：**IDEA 2026.2.x（262）**，基于 2026.2.3 SDK。
- **JDK 25**、Gradle Wrapper 9.1.0、IntelliJ Platform Gradle Plugin 2.19.0。
- Java 源码，Swing/IDE 原生组件，无额外前端工具链。

### 日常打包

在 PowerShell 中执行：

```powershell
Set-Location E:\commitloom
$env:JAVA_HOME = 'E:\devsofts\jdk25'
.\gradlew.bat buildPlugin
```

这里的 JDK 路径是本机安装位置，其他电脑替换为自己的 JDK 25 目录；终端已使用 JDK 25 时可省略 `JAVA_HOME` 这一行，该设置仅影响当前终端。

看到 `BUILD SUCCESSFUL` 即打包完成，当前版本的安装包为 `E:\commitloom\build\distributions\commitloom-1.0.zip`。每次修改代码后重新执行打包命令即可，直接选择生成的 ZIP 安装，无需解压或手工压缩项目。

### 测试与运行

需要同时执行测试和项目配置检查时，在项目目录使用 JDK 25 运行：

```powershell
.\gradlew.bat test buildPlugin verifyPluginProjectConfiguration
.\gradlew.bat runIde
```

本机已在 Git 忽略的 `local.properties` 中指定安装目录，避免重新下载整个 IDEA：

```properties
localPlatformPath=E:/devsofts/IntelliJIDEA
```

其他电脑可移除该本地配置，由 Gradle 下载 `gradle.properties` 中的目标 SDK；也可传 `-PlocalPlatformPath=...`。在 IDEA 中打开 `E:\commitloom`，将 Project SDK 和 Gradle JVM 都选择为 JDK 25，然后重新加载 Gradle 项目。Gradle JVM 可使用 `GRADLE_LOCAL_JAVA_HOME`，并在已忽略的 `.gradle/config.properties` 中设置 `java.home=你的 JDK 25 目录`，无需修改其他项目使用的全局 `JAVA_HOME`。同步完成后运行 Gradle 的 `runIde` 任务即可启动独立测试窗口。

```powershell
.\gradlew.bat verifyPlugin
```

这项任务运行 JetBrains Plugin Verifier；SDK 内部的部分提交接口需要逐版本验证，因此第一版限定当前 SDK 分支，上新版本前扩展验证范围。当前本机的 Verifier 因 SDK 依赖解析问题未完成，不能视为已通过市场兼容性验证，具体进展见验收说明。

## 目录

```text
src/main/java/com/commitloom/
  core/       模型协议、HTTP、提示词；不依赖 IDEA
  settings/   多模型配置、凭据库、设置界面
  ide/        勾选内容快照、提交工具栏、回填与预览
src/test/     本地 HTTP 模拟、提示词、配置、diff 边界测试
docs/         发布准备、隐私说明、手动验收
```

代码注释使用中文；所有命名类型（含内部类、枚举、record 和测试类）的 Javadoc 标注 `@author hulei`。

## 上架准备

项目包含插件元信息、图标、变更记录、CI 构建、隐私说明及发布文档。显示品牌已选定为 **CommitLoom · 提交织语**，首次发布前仍需检查 Marketplace 的近似名称及相关品牌占用，并确定发布账号、真实发布者、联系方式、公开隐私政策 URL 与许可条款；不能据此视为已通过 Marketplace 审核。

内部插件 ID `dev.commitloom.idea`、Java 包名 `com.commitloom`，以及已有配置/凭据标识。安装包名为 `commitloom-1.0.zip`，项目目录为 `E:\commitloom`。

参考 [发布说明](docs/发布说明.md)、[隐私政策](PRIVACY.md) 和 [验收说明](docs/验收说明.md)。源码仓库：[Gitee](https://gitee.com/buxingzhe/commitloom)。本项目尚未发布到插件市场。