内容
# mavis
**(非)传统提交信息，你来定规则。**
<img alt="mavis - (非)传统提交信息，你来定规则" src="demo.gif" width="800" />
## 关于
Mavis 是一个终端优先的工具，用于编写结构化的 Git 提交信息 —— 传统提交信息，你来定规则。
你可以自定义字段、格式规则和消息模板，这样提交信息就遵循 *你* 的约定，而不是固定的规范。交互式 TUI，实时预览，AI 辅助默认值，以及用于从像 Claude Code 这样的代理直接提交的 MCP 服务器。
### 主要功能
- **交互式界面**：分屏显示表单输入和实时提交信息预览
- **AI 辅助建议**：使用 OpenAI 生成提交信息字段默认值
- **MCP 服务器**：通过模型上下文协议与像 Claude Code 这样的 AI 代理集成
- **自定义模板**：使用灵活的模板系统格式化提交信息
- **可配置字段**：定义提交信息的结构
- **多种主题**：选择 charm、dracula、catppuccin 等主题
- **配置系统**：基于 YAML，支持条件配置
- **环境变量覆盖**：通过环境变量自定义行为
## 安装
### Homebrew 安装
```console
brew install kristofferahl/tap/mavis
```
### 使用 go 安装
```console
go install github.com/kristofferahl/mavis@latest
```
### 手动安装
从 [发布页面](https://github.com/kristofferahl/mavis/releases) 下载二进制文件。
## 使用
在 Git 仓库中运行 `mavis` 开始交互式提交过程：
```console
mavis
```
### 键盘快捷键
- **Ctrl+A / Ctrl+S**：接受预览并提交
- **?**：切换帮助视图
- **Esc / Ctrl+C**：退出而不提交
### 配置
Mavis 在首次运行时会自动创建一个默认配置文件 `~/.config/mavis/config.yaml`。你可以自定义此文件以更改主题、字段和提交信息模板。
#### 环境变量
- `MAVIS_THEME`：覆盖主题（例如 "charm"、"dracula"、"catppuccin"）
- `MAVIS_CHIP`：覆盖 UI 中显示的芯片标签
#### 调试模式
使用调试标志运行以查看更多信息：
```console
mavis --debug
```
### AI 辅助提交
Mavis 可以使用 OpenAI 的 GPT 模型生成智能提交信息建议。启用后，它会分析你的 git diff 并为提交信息字段建议适当的值。
#### 设置
1. **获取 OpenAI API 密钥**：在 [OpenAI](https://platform.openai.com/) 注册并创建 API 密钥
2. **设置环境变量**：
```bash
export OPENAI_API_KEY="你的-api-密钥"
```
3. **运行 mavis 并使用 --ai 或在配置文件中启用** - AI 建议将根据你的暂存更改自动生成
#### 自定义
你可以在配置文件中自定义 AI 行为：
```yaml
ai:
enabled: true
provider: "openai"
custom_prompt: "关注业务影响并使用命令式语气。"
openai:
model: "gpt-4.1-mini"
max_completion_tokens: 500
temperature: 0.2
```
#### 工作原理
- 分析你的暂存 git 更改（diff）
- 考虑当前分支名称以获取更好的上下文
- 使用 GPT-4 Mini 进行成本效益高、准确的建议
- 为所有配置的提交信息字段生成默认值
- 尊重你现有的字段配置和模板
- 与你在配置文件中定义的任何自定义字段一起工作
- 设计支持多个 AI 提供商（目前支持 OpenAI）
### MCP 服务器（AI 代理集成）
Mavis 包含一个 MCP（模型上下文协议）服务器，允许像 Claude Code、Kiro 等 AI 代理使用你的 mavis 配置创建提交。
#### 设置
将以下内容添加到项目的 `.mcp.json` 文件中：
```json
{
"mcpServers": {
"mavis": {
"command": "mavis",
"args": ["mcp"]
}
}
}
```
或从源代码运行：
```json
{
"mcpServers": {
"mavis": {
"command": "go",
"args": ["run", ".", "mcp"]
}
}
}
```
#### 可用工具
MCP 服务器提供三个工具：
| 工具 | 描述 |
|------|-------------|
| `prepare_commit` | 返回提交模板、字段和用于生成字段值的说明 |
| `preview_commit` | 根据提供的字段值渲染提交信息并返回批准 ID |
| `approve_commit` | 在用户批准后执行提交 |
#### 可用提示
MCP 服务器还为 AI 代理指导提供提示：
| 提示 | 描述 |
|--------|-------------|
| `mavis` | 向 AI 代理说明提交工作流程：调用 `prepare_commit`，然后 `preview_commit`，显示结果给用户，并在调用 `approve_commit` 之前等待批准 |
#### 工作原理
1. AI 代理调用 `prepare_commit` 以获取配置的字段和模板
2. 它分析暂存更改并生成适当的字段值
3. 它调用 `preview_commit` 以渲染提交信息
4. 在向你展示预览并获得你的批准后，它调用 `approve_commit`
这确保你的提交遵循你配置的约定，同时让 AI 代理处理分析和起草。
