git-muse：让 commit message 少一点敷衍，多一点准确

写代码时，很多人最不想花时间的环节，是写 commit message。

麻烦，谈不上不会写。改了三五个文件，修了一个边界问题，顺手补了测试，再调一点文档。真正提交时，脑子里只剩下两个字：差不多。于是仓库里慢慢出现这些记录：

fix
update
wip

改一下

调整代码

短期看没问题，代码能提交就行。等到回头排查问题、看版本变更、整理发布记录，这些 commit message 基本没有价值。当时改了什么、为何改、影响范围在哪，全对不上号。

git-muse 盯的就是这个小而高频的点：根据已暂存的改动，生成一条可用、可编辑、格式稳定的 commit message。

它不替代 Git，也不让 AI 接管提交。更像一个 Git 辅助：先看一眼 staged diff，给出一条靠谱的提交说明，最后仍由你确认，再交给原生 git commit。

1. 解决什么问题

写 commit message 太随意

很多项目的提交记录，信息密度太低，代码本身往往还行。

一条好的 commit message 至少该回答几个问题：

这次改了什么？

影响哪个模块？

属于新功能、修复、重构、文档变更里的哪一类？

以后回看时能不能快速理解？

日常开发节奏很快。小改动、多文件改动、临时修 bug 时，很容易随手写一句 fix。当时省了十秒，后面排查问题可能多花十分钟。

git-muse 会读取 git diff --cached，也就是已经 git add 的内容，根据真实改动生成 Conventional Commit 风格的候选消息，例如：

fix(auth): handle expired refresh token

中文输出也能出：

fix(auth): 修复刷新令牌过期处理

提交记录不会只剩“改了点东西”。

AI 工具容易越界

直接把整个仓库丢给 AI，让它帮你总结提交，看起来方便，问题不少：

它可能读到不该读的文件。

它可能把未暂存的改动也算进去。

它可能生成看起来像样、却不符合项目规则的 message。

它可能直接替你提交，风险太高。

git-muse 的边界更窄，也更清楚。

默认只读取 staged changes，也就是你明确准备提交的内容。未 git add 的改动不会被拿来生成 commit message。提交前会让你确认、编辑、重新生成、取消，不会悄悄替你做决定。

提交流程不该破坏 Git 原有行为

不少工具为了方便，会绕过 Git 原本的提交流程。hooks、签名、编辑器、credential helper 这些本地配置都可能受影响。

git-muse 不重造 Git。真正提交时，它使用：

git commit -F <message-file>

原来的 Git hooks、签名、编辑器行为都还在。它只帮你准备 message，不抢 Git 的工作。

团队需要稳定格式

团队协作里，commit message 给人看，也常被用来生成 changelog、判断版本类型、做发布说明。

git-muse 默认生成 Conventional Commits 格式：

<type>[optional scope]: <subject>

比如：

feat(cli): add inspect command

fix(diff): filter env files from context

docs(readme): update provider setup guide

格式稳定之后，提交历史更好读，自动化工具也好接。

2. 特点、功能

只分析已暂存改动

git-muse 默认读取：

git diff --cached

这点很关键。

工作区里可能有很多临时改动，只有 git add 过的内容才代表“这次准备提交”。git-muse 只看这部分，生成结果更贴近当前提交，也避免把未完成代码混进 message。

典型流程是：

git muse init

git add <files>

git muse inspect

git muse

init 用一次就行：写 ~/.git-muse.json，顺手处理 PATH、Git 帮助页。

生成 Conventional Commit

工具会根据改动内容生成提交消息候选，默认使用 Conventional Commits 风格。

支持常见类型：

feat
fix
docs
style
refactor
perf
test
build
ci
chore
revert

生成出来的 message 不单是“像一句话”，有结构、能归类，团队长期维护省事。

支持确认、编辑、重新生成、取消

git-muse 不会把模型输出直接当最终结果。

默认交互类似这样：

Suggested commit message:
feat(auth): add refresh token rotation
[c] commit  [p] commit and push  [e] edit  [r] regenerate  [q] quit
>

可以直接提交，也能提交后顺手 push，编辑、重新生成、退出都行。view diff 已经拿掉了，想看改动自己 git diff --cached 就行。

这比“AI 直接替你提交”安全得多。模型只给建议，最终决定仍在人手里。

使用原生 Git 提交

提交动作交给系统 Git 完成，工具自己不模拟 Git 行为。

实际使用：

git commit -F <message-file>

这样可以保留项目已有的：

pre-commit hook

commit-msg hook

GPG / SSH 签名

Git editor

credential helper

工具只做辅助，不破坏本地开发习惯。

选 [p] 时，先 git commit -F，再 git push。推送把终端交回给 Git，认证提示仍是原来那套。

Windows 上如果 Git editor 配成打不开的命令，会退回 Notepad，路径带空格也不再直接炸。

支持 Ollama、OpenAI-compatible API

git-muse 能走本地模型，也能走在线模型。

本地模型可以用 Ollama，例如：

git config --global muse.provider ollama
git config --global muse.baseUrl http://localhost:11434
git config --global muse.model qwen2.5-coder

OpenAI-compatible API 也可以配置：

git config --global muse.provider compatible
git config --global muse.baseUrl https://api.openai.com/v1
git config --global muse.model gpt-4.1-mini

API key 只从环境变量读取，不写进项目配置：

OPENAI_API_KEY

OPENROUTER_API_KEY

ANTHROPIC_API_KEY

GEMINI_API_KEY

这个设计比较克制，避免把密钥写进 Git config、仓库文件、日志。

仓库里确实不写。~/.git-muse.json 示例带了 apiKey 占位，init 完自己改；环境变量那几项仍然能用。

走 compatible 时默认关掉 thinking。deepseek 一类模型不然会把 max_tokens 耗在推理上，最后 content 是空的。

多路 LLM、限流切换

~/.git-muse.json 里 llm 既能写成单个对象，也能写成数组。上游返回 429 / RPM / rate limit 时，按数组顺序切。每个 LLM 先重试 failover.rateLimitRetries 次（默认 3），超过才请求下一个。重试、切换都会在 stderr 打日志。鉴权失败不切下一家。后一个 LLM 继承前一个的 proxy、maxTokens、timeout、temperature。inspect、doctor、init 示例里都能看见 Fallback、retries。

提供 inspect，看清楚发给模型的内容

担心“到底哪些内容会发给模型”，可以先运行：

git muse inspect

它会展示将要发送给 LLM 的上下文摘要，包括文件数量、纳入内容、排除原因等。

例如：

Provider: ollama
Model: qwen2.5-coder
Files changed: 5
Included bytes: 8420
Excluded:
.env.local secret pattern
dist/app.js generated file
pnpm-lock.yaml large lockfile

行为更透明。公司项目、私有仓库里，提交辅助必须能说清楚自己读了什么、发了什么、排除了什么。inspect 也会标 Fallback、retries。

提供 doctor，快速排查环境问题

配置不对、模型连不上、没有 staged changes，可以用：

git muse doctor

它会检查 Git 仓库状态、暂存区、provider、model、API key、网络等信息。现在也会打 Version、Executable，核对 PATH 命中的到底是哪一份二进制。

图的是告诉你下一步该做什么，调试日志堆一大坨没意义。

提供 init，把配置、PATH 一次写好

第一次建议跑：

git muse init

它会写入 ~/.git-muse.json。文件已存在会先问要不要覆盖。Windows 上还会把当前 git-muse.exe 所在目录写到用户 PATH 最前，旧安装目录会被替换，不会一条条堆。go run . init 会跳过 PATH，免得把临时构建目录写进去。

写入 PATH 后会广播 WM_SETTINGCHANGE，资源管理器能刷新环境变量。PATH 没变化也会广播。Zed、VS Code 要整个退出再开，才认新目录。

顺手装一份 git-muse.html。Git 自己处理 git muse --help 时会找这个页面；日常用 git muse help / git-muse --help 也行。--version、help 文末会打印版本号，外加正在运行的 git-muse.exe 路径。

支持代理配置

访问在线模型时，可能需要代理。git-muse 支持命令行、环境变量、配置文件多种方式。

命令行：

git muse --proxy http://127.0.0.1:7890

环境变量：

GIT_MUSE_PROXY

配置文件：

{
  "llm": {
    "proxy": "http://127.0.0.1:7890"
  }
}

代理优先级清楚：

--proxy > GIT_MUSE_PROXY > ~/.git-muse.json > muse.proxy

可配置输出语言

团队用中文提交说明，可以在配置里设置：

{
  "output": {
    "language": "zh"
  }
}

默认支持：

英文项目用英文，中文团队用中文，不强行绑死一种风格。

过滤敏感文件、大文件

git-muse 默认会避开 secrets、证书、.env*、生成文件、过大的 diff。

也可以通过配置补充忽略规则：

{
  "diff": {
    "maxBytes": 100000,
    "ignore": ["*.lock", "coverage/*"],
    "allow": [".env.example"]
  }
}

这类功能不显眼，很要紧。commit message 工具不该为了省事，把敏感内容塞进模型上下文。

github 地址：https://github.com/dirkhe1051931999/muse