Commit Loom

在 VS Code 原生 Git 提交框中，使用 Codex 或 Claude 根据代码变更生成清晰、规范的提交信息。

Commit Loom 读取当前仓库的 Git diff 和可选仓库上下文，生成符合 Conventional Commits 的提交标题与正文，并直接写入 VS Code 自带的“源代码管理”输入框。支持 OpenAI、Anthropic 官方 API，也支持自定义 Base URL、代理网关和兼容接口。

生成效果

feat(user): 新增用户头像上传组件

- 支持图片上传
- 校验图片大小
- 更新用户资料接口

默认使用英文 type、scope，标题和正文使用简体中文。输出语言、正文、自定义规范和自动生成行为均可配置。

核心功能

• 暂存区变化后自动生成提交信息，并写入对应仓库的原生 Git 提交框。
• 在源代码管理输入框右侧提供 AI 生成按钮，生成期间切换为停止按钮。
• 优先分析 staged diff；手动生成且没有暂存内容时，可分析工作区和未跟踪文本文件。
• 可结合当前分支、近期提交、README 和项目清单理解修改目的与模块边界。
• 检查 Conventional Commits、72 字符主题行、正文空行和列表格式；不合格时自动修正一次。
• 支持 Codex/OpenAI、Claude/Anthropic、Responses API、Chat Completions 和 Messages API。
• 支持多仓库工作区，不覆盖用户已经输入的提交内容。
• 通过配置向导或设置命令输入的 API Key 存储在 VS Code SecretStorage 中，不写入 settings.json。

环境要求

• VS Code 1.90.0 或更高版本。
• 当前工作区已经初始化为 Git 仓库。
• 一个可用的 OpenAI、Anthropic 或代理网关 API Key。

安装与启用输入框按钮

从 VS Code 扩展市场搜索 Commit Loom，并核对发布者为 MelancholyDonkey、扩展 ID 为 melancholydonkey.commit-loom-ai。本地安装时，也可以运行“扩展：从 VSIX 安装...”并选择安装包。

兼容性说明：当前版本的输入框右侧按钮依赖 VS Code 提议 API contribSourceControlInputBoxMenu。提议 API 尚未稳定，可能随 VS Code 版本变化；如果当前版本不支持按钮，仍可使用命令面板或快捷键生成提交信息。

安装后按以下步骤启用输入框按钮：

1. 打开命令面板：macOS 使用 Cmd+Shift+P，Windows/Linux 使用 Ctrl+Shift+P。
2. 运行 Preferences: Configure Runtime Arguments（中文界面为“首选项: 配置运行时参数”）。
3. 在 argv.json 中找到或新增唯一的 enable-proposed-api 数组，并把 Commit Loom 的扩展 ID 合并进去。不要创建两个同名字段，也不要删除文件中的其他配置。例如：

{
  // 保留你已有的其他运行参数
  "enable-proposed-api": [
    "other-publisher.other-extension",
    "melancholydonkey.commit-loom-ai"
  ]
}

如果此前没有启用其他提议 API，只保留 Commit Loom 这一项即可。

4. 打开 VS Code 设置，搜索 scm.showInputActionButton，并在“用户”设置范围确认它为 true。
5. 真正退出 VS Code 进程后重新启动。macOS 请使用 Cmd+Q 或“Code → 退出 Visual Studio Code”；Windows/Linux 请关闭所有 VS Code 窗口。仅运行“开发人员: 重新加载窗口”不足以重新读取 argv.json。
6. 打开一个 Git 仓库并产生一项变更，再检查源代码管理输入框右侧的按钮。

如果按钮仍未显示，可先从命令面板运行 Commit Loom: AI 生成提交信息，并参阅常见问题。

快速开始

1. 打开命令面板，运行 Commit Loom: 一键配置 AI 服务。
2. 选择 OpenAI 官方 API、Anthropic 官方 API 或兼容网关。
3. 按向导填写 API Key；使用网关时还需要填写 Base URL 和模型 ID，部分网关还需要选择请求协议。
4. 在“源代码管理”中暂存准备提交的文件。
5. 等待自动生成，或者点击提交输入框右侧的 Commit Loom 图标。
6. 检查或编辑生成内容，然后正常执行 Git commit。

也可以使用快捷键手动生成：

平台	快捷键
macOS	Cmd+Alt+Enter
Windows/Linux	Ctrl+Alt+Enter

自动生成不会覆盖用户手动输入。手动重新生成时，如果输入框已经有内容，Commit Loom 会询问是替换还是追加。

验证配置是否成功

1. 在测试仓库中修改一个小文件并执行 Git Stage。
2. 运行 Commit Loom: AI 生成提交信息，或点击输入框右侧图标。
3. 成功时，规范提交信息会直接写入 Git 提交输入框。
4. 失败时，打开“查看 → 输出”，在通道列表中选择 Commit Loom，根据日志中的提供方、模型和错误状态继续排查。

配置 AI 服务

推荐始终通过 Commit Loom: 一键配置 AI 服务 完成首次配置或切换服务。该向导会同步设置提供方、Base URL、模型、协议和 API Key，避免旧网关配置与新 Key 混用。

OpenAI 官方 Key 可在 OpenAI API Keys 创建，Anthropic 官方 Key 可在 Anthropic Console 创建。ChatGPT、Claude.ai 或其他聊天产品的登录和订阅不等同于 API Key，也不一定包含 API 调用额度。

使用方式	向导选项	需要填写	Commit Loom 的处理
OpenAI 官方 API	OpenAI 官方 API	API Key	恢复官方 Base URL、模型和 Responses API
Anthropic 官方 API	Anthropic 官方 API	API Key	恢复官方 Base URL、模型和 Messages API
Codex/OpenAI 网关	OpenAI 兼容网关	Base URL、模型、协议、Key	支持 Responses、Chat Completions 或自动回退
Claude OpenAI 兼容网关	OpenAI 兼容网关 → Claude 模型	Base URL、模型、Key	使用 Chat Completions
Claude Anthropic 网关	Anthropic 兼容网关	Base URL、模型、Key	使用 Messages API

重新配置、替换或清除 API Key

通过向导或设置命令输入的 API Key 不会出现在 VS Code 设置页面或 settings.json 中，这是正常现象。Commit Loom 将它保存在当前 VS Code 环境的 SecretStorage 中，并且不会提供明文查看功能。

完整重新配置服务和 Key（推荐）

适用于切换官方服务、切换代理网关、修改 Base URL、模型或协议：

1. 打开命令面板。
2. 运行 Commit Loom: 一键配置 AI 服务。
3. 重新选择服务类型，并按向导填写全部信息和新 Key。

新配置会覆盖所选服务原来的 Base URL、模型、协议和 SecretStorage Key。重新选择官方服务时，还会恢复官方地址，避免把官方 Key 发送到旧代理网关。

只替换 API Key

适用于 Base URL、模型和协议都正确，仅需要更新过期或错误的 Key：

1. 打开命令面板。
2. 运行 Commit Loom: 设置 API Key。
3. 选择 Codex 或 Claude。其中 Codex 表示 OpenAI/Codex 提供方的 Key 存储槽，并不要求单独的 Codex 登录凭据。
4. 输入新 Key。新 Key 会覆盖该提供方原来保存的 Key，其他设置保持不变。

如果当前提供方选错了，再运行 Commit Loom: 选择 AI 提供方；该命令修改全局设置，如果工作区单独配置了 commitLoom.provider，工作区值仍会优先生效。如果还需要修改网关地址或协议，请改用“一键配置 AI 服务”。

清除 API Key

1. 打开命令面板。
2. 运行 Commit Loom: 清除 API Key。
3. 选择要清除的 Codex 或 Claude Key。

Codex 和 Claude 的 Key 分开保存；需要全部清除时，请分别执行一次。清除 SecretStorage Key 后，如果扩展宿主仍设置了 OPENAI_API_KEY 或 ANTHROPIC_API_KEY 环境变量，Commit Loom 仍会使用对应环境变量。

OpenAI 官方 API

一键配置会写入以下设置。注意：设置架构中 commitLoom.codex.apiMode 的初始默认值是 auto，选择 OpenAI 官方服务后会明确改为 responses：

{
  "commitLoom.provider": "codex",
  "commitLoom.codex.baseUrl": "https://api.openai.com/v1",
  "commitLoom.codex.model": "gpt-5.3-codex",
  "commitLoom.codex.apiMode": "responses"
}

Anthropic 官方 API

一键配置会使用以下设置：

{
  "commitLoom.provider": "claude",
  "commitLoom.claude.baseUrl": "https://api.anthropic.com",
  "commitLoom.claude.model": "claude-opus-4-7",
  "commitLoom.claude.protocol": "anthropic"
}

OpenAI 兼容网关

自定义 Base URL 会被原样使用，仅移除末尾多余的 /，不会自动添加 /v1。例如：

{
  "commitLoom.provider": "codex",
  "commitLoom.codex.baseUrl": "https://gateway.example.com/openai",
  "commitLoom.codex.model": "gateway-codex-model",
  "commitLoom.codex.apiMode": "auto"
}

根据协议，实际请求地址通常为：

• Responses API：https://gateway.example.com/openai/responses
• Chat Completions：https://gateway.example.com/openai/chat/completions

请填写接口前的基地址，不要把 /responses 或 /chat/completions 端点重复写入 Base URL。

auto 会先尝试 Responses API；遇到 Responses 空文本，或 HTTP 400、404、405、422、501 时，再尝试 Chat Completions。若网关只支持一种协议，建议在向导中直接选择对应协议。

Anthropic 兼容网关

填写 /v1/messages 之前的基地址，例如：

{
  "commitLoom.provider": "claude",
  "commitLoom.claude.baseUrl": "https://gateway.example.com",
  "commitLoom.claude.model": "gateway-claude-model",
  "commitLoom.claude.protocol": "anthropic"
}

如果 Claude 模型由网关通过 OpenAI Chat Completions 暴露，请在“一键配置 AI 服务”中选择 OpenAI 兼容网关，然后选择 Claude 模型，不要选择 Anthropic 兼容网关。

工作方式

自动生成

默认启用 commitLoom.autoGenerateOnStage。检测到非空暂存变更后（包括扩展启动时已经存在的暂存内容），如果提交输入框没有用户文本，Commit Loom 会等待短暂防抖时间后自动生成。

手动生成

以下方式均可触发：

• 点击源代码管理输入框右侧的 Commit Loom 图标。
• 运行 Commit Loom: AI 生成提交信息。
• 使用 Cmd+Alt+Enter 或 Ctrl+Alt+Enter。

存在 staged diff 时只分析已暂存变更；没有 staged diff 时，手动生成会分析工作区变更，并根据设置决定是否读取未跟踪文本文件。

仓库上下文

启用 commitLoom.includeRepositoryContext 后，Commit Loom 会读取以下只读信息辅助判断提交目的和 scope：

• 当前分支名。
• 最近 8 条提交标题，用于贴近仓库已有措辞风格。
• 根目录 README 摘要。
• 根目录及变更模块附近的 package.json、pyproject.toml、Cargo.toml、go.mod、pom.xml 或 Gradle 清单。

这些内容只作为语义和命名上下文，Git diff 仍是变更事实的唯一来源。

命令

命令	用途
Commit Loom: AI 生成提交信息	根据当前变更生成提交信息
Commit Loom: 停止生成提交信息	取消正在进行的请求
Commit Loom: 一键配置 AI 服务	配置官方 API 或代理网关，包含 Key
Commit Loom: 设置 API Key	仅替换 Codex 或 Claude Key
Commit Loom: 清除 API Key	从 SecretStorage 清除所选 Key
Commit Loom: 选择 AI 提供方	修改全局提供方；工作区级设置可能覆盖它
Commit Loom: 打开设置	打开 Commit Loom 设置页面

常用设置

设置项	默认值	说明
commitLoom.provider	codex	当前使用 codex 或 claude
commitLoom.language	zh-CN	auto、zh-CN 或 en
commitLoom.conventionalCommits	true	使用 Conventional Commits 格式
commitLoom.includeBody	true	复杂变更允许生成正文
commitLoom.includeUntracked	true	手动生成且无暂存内容时分析未跟踪文本文件
commitLoom.autoGenerateOnStage	true	检测到非空暂存变更后自动生成
commitLoom.autoGenerateDelayMs	1200	自动生成防抖时间，单位毫秒
commitLoom.includeRepositoryContext	true	使用分支、近期提交和项目文件上下文
commitLoom.maxRepositoryContextChars	12000	仓库上下文最大字符数
commitLoom.maxDiffChars	60000	发送给 AI 的 diff 最大字符数
commitLoom.requestTimeoutMs	60000	AI 请求超时时间，单位毫秒
commitLoom.customInstructions	空	附加团队提交规范

完整设置可在 VS Code 设置中搜索 @ext:MelancholyDonkey.commit-loom-ai。

数据与安全

• 生成时会向所选 AI 服务发送仓库名、Git 状态、目标 diff、自定义提交规范和已启用的仓库上下文。
• 暂存区存在变更时只分析 staged diff，避免发送尚未准备提交的工作区修改。
• 未跟踪的 .env 文件、文件名含 secret、credential 或 token 的文件，以及 .pem、.key、.p12、.pfx、.jks 文件默认只发送文件名，不读取内容。
• 通过向导或设置命令输入的 API Key 存储在 VS Code SecretStorage；Base URL、模型和协议存储在普通 VS Code 设置中。
• SecretStorage Key 优先于 OPENAI_API_KEY 和 ANTHROPIC_API_KEY 环境变量。
• Commit Loom 不执行 git commit、不自动暂存文件，也不上传遥测。

使用第三方代理网关时，代码变更会发送到该网关。请在配置前确认网关的隐私政策、日志策略和数据保留规则。

常见问题

输入框右侧没有 Commit Loom 按钮

1. 确认扩展已经启用。
2. 确认扩展 ID 是 melancholydonkey.commit-loom-ai。
3. 确认 argv.json 的唯一 enable-proposed-api 数组包含该 ID。
4. 在用户设置中确认 scm.showInputActionButton 为 true。
5. 真正退出 VS Code 进程并重新启动；macOS 仅关闭窗口不等于退出应用。
6. 确认当前打开的是 Git 仓库，并制造一项变更后重试。
7. 如果仍未显示，当前 VS Code 版本可能不支持该提议 API；改用命令面板或快捷键生成。

即使按钮暂时不可用，也可以从命令面板运行 Commit Loom: AI 生成提交信息。

在设置页面找不到 API Key

这是预期行为。Key 保存在 SecretStorage 中，不会显示在设置页面。使用 Commit Loom: 设置 API Key 替换，或使用 Commit Loom: 清除 API Key 删除。

返回 401 或 403

先打开“查看 → 输出 → Commit Loom”确认当前提供方和模型。Key 无效、过期、权限不足或网关不接受该 Key 时，运行 Commit Loom: 设置 API Key 重新填写；如果同时需要检查服务地址，请运行“一键配置 AI 服务”。

返回 404

先打开“查看 → 输出 → Commit Loom”确认当前提供方、模型和仓库。404 通常是 Base URL 或接口协议不匹配：

• 官方 API：重新运行“一键配置 AI 服务”，选择对应官方服务，以恢复官方 Base URL、模型和协议。
• 代理网关：检查 Base URL 是否重复包含 /responses、/chat/completions 或 /v1/messages。
• OpenAI 兼容网关：确认地址是否需要 /v1 或自定义路径；Commit Loom 不会自动添加 /v1。
• Anthropic 兼容网关：填写消息端点之前的基地址，SDK 会自动追加 /v1/messages。
• 代理网关：根据网关文档明确选择 Responses、Chat Completions 或 Anthropic Messages。

返回 400

先打开“查看 → 输出 → Commit Loom”确认当前模型。400 通常是模型 ID、请求协议或网关参数格式不兼容：

• 官方 API：重新运行“一键配置 AI 服务”恢复官方配置。如果账号不支持默认模型，可在设置中搜索 commitLoom.codex.model 或 commitLoom.claude.model，改为账号实际可用的模型 ID。
• 代理网关：确认填写的是网关实际模型 ID，而不是展示名称。
• 代理网关：根据网关文档明确选择 Responses、Chat Completions 或 Anthropic Messages，然后重新生成。
• auto 会在 Responses 返回空文本，或 HTTP 400、404、405、422、501 时尝试 Chat Completions，并不会对所有请求错误自动切换协议。

返回 429

API 额度不足、计费未启用或请求频率受限。检查对应官方账号或代理网关的余额、额度和速率限制；聊天产品订阅通常不包含 API 额度。

没有生成内容

• 确认仓库存在可分析的变更。
• 自动生成只处理暂存区；请先执行 Git Stage。
• 如果提交输入框已有手动内容，自动生成会跳过，避免覆盖。
• 打开“查看 → 输出”，在通道列表中选择 Commit Loom 查看详细错误。

与 GitLens 的关系

Commit Loom 可以与 GitLens — Git supercharged 同时使用。它通过 VS Code Git SCM API 读取仓库并写回原生提交输入框，不会修改或注入 GitLens 的私有界面。

相关链接

• OpenAI Responses API
• OpenAI 代码生成
• Anthropic Messages API
• Conventional Commits

License

MIT