AI 编码代理时代缺失的代码评审工具。

特别致谢

目录

• 功能
• 快速上手
  • 先决条件
  • 安装
  • 配置（针对 AI 功能）
• 使用方法
  • 可视化差异查看器
  • 生成提交信息
  • 生成 Git 命令
  • 解释变更
  • 交互模式
  • 技巧与提示
• AI 提供商
• 高级配置
  • 配置文件
  • 配置优先级

功能 🔅

• 美观且符合人体工学的差异查看器：支持语法高亮，方便代码审查并添加注释
• 智能提交信息：为暂存的更改自动生成规范化的提交信息
• 交互式搜索：通过模糊搜索查找和浏览提交记录
• 多 AI 提供商支持：兼容 OpenAI、Claude、Groq、Ollama 等多种模型
• 灵活性强：适用于任何 Git 工作流，并支持多种 AI 提供商
• 丰富输出：支持 Markdown 格式，提供易读的说明和差异对比（需安装 mdcat）

快速上手 🔅

先决条件

在开始之前，请确保您已安装：

1. 系统中已安装 git
2. fzf（可选）——用于 lumen explain --list 命令
3. mdcat（可选）——用于美化输出格式

安装

使用 Homebrew（MacOS 和 Linux）

brew install jnsahaj/lumen/lumen

使用 Cargo

[!重要] cargo 是 Rust 的包管理工具， 在安装 Rust 时会自动一同安装。 详情请参阅 安装指南

cargo install lumen

配置（针对 AI 功能）

若要使用 AI 驱动的功能（explain、draft、list、operate），请运行交互式设置：

lumen configure

该命令将引导您完成以下步骤：

1. 选择 AI 提供商
2. 输入 API 密钥（如使用环境变量则可省略）
3. 指定自定义模型名称（可选——按回车键使用默认值）

配置信息将保存至 ~/.config/lumen/lumen.config.json。

[!注意] diff 命令无需任何配置即可使用——它是一个独立的可视化差异查看器。

使用方法 🔅

生成提交信息

为暂存的更改创建有意义的提交信息：

# 基本用法——根据暂存内容生成提交信息
lumen draft
# 输出： "feat(button.tsx): 将按钮颜色更新为蓝色"

# 添加上下文以生成更丰富的信息
lumen draft --context "符合品牌规范"
# 输出： "feat(button.tsx): 更新按钮颜色以符合品牌标识规范"

生成 Git 命令

让 Lumen 根据自然语言查询生成 Git 命令：

lumen operate "将最近的 3 次提交压缩成 1 次，提交信息为 'squashed commit'"
# 输出： git reset --soft HEAD~3 && git commit -m "squashed commit" [y/N]

该命令会显示所生成命令的作用说明，提示潜在危险操作，并在执行前要求确认。

可视化差异查看器

在终端中启动交互式的并排差异查看器：

# 查看未提交的更改
lumen diff

# 查看特定提交的更改
lumen diff HEAD~1

# 查看分支之间的差异
lumen diff main..feature/A

# 查看 GitHub Pull Request 中的更改
lumen diff --pr 123 # (--pr 为可选)
lumen diff https://github.com/owner/repo/pull/123

# 过滤到特定文件
lumen diff --file src/main.rs --file src/lib.rs

# 监视模式——文件变化时自动刷新
lumen diff --watch

# 堆叠模式——逐个查看提交
lumen diff main..feature --stacked

# 打开时直接跳转到指定文件
lumen diff --focus src/main.rs

堆叠差异模式

使用 --stacked 选项逐个查看一系列提交：

lumen diff main..feature --stacked
lumen diff HEAD~5..HEAD --stacked

此模式会单独显示每个提交，您可以进行导航：

• ctrl+h / ctrl+l：上一个 / 下一个提交
• 点击页眉中的 ‹ / › 箭头

页眉会显示当前提交的位置、SHA 值和提交信息。每次查看的文件都会被记录，因此在导航时您的进度会被保留。

查看 PR 时，您可以通过空格键标记已查看的文件（与 GitHub 同步）。

主题配置

使用预设主题自定义差异查看器的颜色：

# 使用命令行参数
lumen diff --theme dracula

# 使用环境变量
LUMEN_THEME=catppuccin-mocha lumen diff

# 或者在配置文件中永久设置（~/.config/lumen/lumen.config.json）
{
  "theme": "dracula"
}

可用主题：

主题	值
默认（自动检测）	dark、light
Catppuccin	catppuccin-mocha、catppuccin-latte
Dracula	dracula
Nord	nord
One Dark	one-dark
Gruvbox	gruvbox-dark、gruvbox-light
Solarized	solarized-dark、solarized-light

优先级：命令行参数 > 配置文件 > LUMEN_THEME 环境变量 > 操作系统自动检测。

选择与注释

选择：在内容区域中单击并拖动以进行字符级别的选择，或在行号上单击以进行行级别的选择。选定的文本可以被复制或添加注释。

注释：可以在三个不同粒度上添加评审评论：

• 选择 — 使用鼠标选择行，然后按 i 键为所选范围添加注释
• 块 — 使用 {/} 聚焦一个代码块，然后按 i 键为该块添加注释
• 文件 — 在没有选择或聚焦任何代码块的情况下按 i 键，即可为整个文件添加注释

带有注释的行会在侧边栏显示一个 ▍ 标记。使用 I 键可以查看、编辑、删除、复制或导出所有注释。

快捷键

• j/k 或方向键：导航
• {/}：在代码块之间跳转
• tab：切换侧边栏
• space：将文件标记为已查看
• e：在编辑器中打开文件
• y：复制选中的内容（或文件名）
• i：为选中的内容/代码块/文件添加注释
• I：查看所有注释
• ctrl+h/l：上一个/下一个提交（堆叠模式）
• ?：显示所有快捷键

解释变更

了解发生了哪些变化以及原因：

# 解释当前工作目录中的所有更改
lumen explain                         # 所有更改
lumen explain --staged                # 仅暂存的更改

# 解释特定的提交
lumen explain HEAD                    # 最近一次提交
lumen explain abc123f                 # 特定提交
lumen explain HEAD~3..HEAD            # 最近3次提交
lumen explain main..feature/A         # 分支对比
lumen explain main...feature/A        # 分支对比（合并基点）

# 针对变更提出具体问题
lumen explain --query "这些更改对性能有什么影响？"
lumen explain HEAD --query "可能有哪些副作用？"

# 交互式选择提交
lumen explain --list                  # 交互式选择提交

交互模式

# 启动交互式模糊查找工具来搜索提交记录（需要安装 fzf）
lumen explain --list

# 已弃用：lumen list（请改用 lumen explain --list）

小贴士与技巧

# 将提交信息复制到剪贴板
lumen draft | pbcopy                  # macOS
lumen draft | xclip -selection c      # Linux

# 查看并复制提交信息
lumen draft | tee >(pbcopy)

# 在你喜欢的编辑器中打开
lumen draft | code -      

# 直接使用生成的信息提交
lumen draft | git commit -F -           

如果你正在使用 lazygit，可以将其添加到 用户配置文件中：

customCommands:
  - key: '<c-l>'
    context: 'files'
    command: 'lumen draft | tee >(pbcopy)'
    loadingText: '生成消息...'
    showOutput: true
  - key: '<c-k>'
    context: 'files'
    command: 'lumen draft -c {{.Form.Context | quote}} | tee >(pbcopy)'
    loadingText: '生成消息...'
    showOutput: true
    prompts:
          - type: 'input'
            title: '上下文'
            key: 'Context'

AI 提供商 🔅

配置你偏好的 AI 提供商：

# 使用命令行参数
lumen -p openai -k "your-api-key" -m "gpt-5-mini" draft

# 使用环境变量
export LUMEN_AI_PROVIDER="openai"
export LUMEN_API_KEY="your-api-key"
export LUMEN_AI_MODEL="gpt-5-mini"

支持的提供商

提供商	是否需要 API 密钥	模型
OpenAI openai（默认）	是	gpt-5.2、gpt-5、gpt-5-mini、gpt-5-nano、gpt-4.1、gpt-4.1-mini、o4-mini（默认：gpt-5-mini）
Claude claude	是	claude-sonnet-4-5-20250930、claude-opus-4-5-20251115、claude-haiku-4-5-20251015（默认：claude-sonnet-4-5-20250930）
Gemini gemini	是（免费层级）	gemini-3-pro、gemini-3-flash-preview、gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite（默认：gemini-2.5-flash）
Groq groq	是（免费）	llama-3.3-70b-versatile、llama-3.1-8b-instant、meta-llama/llama-4-maverick-17b-128e-instruct、openai/gpt-oss-120b（默认：llama-3.3-70b-versatile）
DeepSeek deepseek	是	deepseek-chat（V3.2）、deepseek-reasoner（默认：deepseek-chat）
xAI xai	是	grok-4、grok-4-mini、grok-4-mini-fast（默认：grok-4-mini-fast）
OpenCode Zen opencode-zen	是	见列表（默认：claude-sonnet-4-5）
Ollama ollama	否（本地运行）	见列表（默认：llama3.2）
OpenRouter openrouter	是	见列表（默认：anthropic/claude-sonnet-4.5）
Vercel AI Gateway vercel	是	见列表（默认：anthropic/claude-sonnet-4.5）

高级配置 🔅

配置文件

Lumen 支持通过 JSON 文件进行配置。您可以将配置文件放置在以下任一位置：

1. 项目根目录：在项目的根目录下创建一个 lumen.config.json 文件。
2. 自定义路径：使用 --config CLI 选项指定自定义路径。
3. 全局配置（可选）：将 lumen.config.json 文件放置在系统的默认配置目录中：
   • Linux/macOS：~/.config/lumen/lumen.config.json
   • Windows：%USERPROFILE%\.config\lumen\lumen.config.json

Lumen 将按照以下优先级顺序加载配置：

1. CLI 参数（最高优先级）
2. 使用 --config 指定的配置文件
3. 项目根目录下的 lumen.config.json
4. 全局配置文件（最低优先级）

{
  "provider": "openai",
  "model": "gpt-5-mini",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "theme": "catppuccin-mocha",
  "draft": {
    "commit_types": {
      "docs": "仅涉及文档的更改",
      "style": "不影响代码含义的更改",
      "refactor": "既不修复错误也不添加新功能的代码更改",
      "perf": "提升性能的代码更改",
      "test": "添加缺失的测试或修正现有测试",
      "build": "影响构建系统或外部依赖项的更改",
      "ci": "CI 配置文件和脚本的更改",
      "chore": "不修改源代码或测试文件的其他更改",
      "revert": "撤销之前的提交",
      "feat": "新增功能",
      "fix": "修复 bug"
    }
  }
}

配置优先级

选项将按以下顺序应用（从高到低）：

1. CLI 标志
2. 配置文件
3. 环境变量
4. 默认选项

示例：为不同项目使用不同的提供商：

# 在 .zshrc 或 .bashrc 中设置全局默认值
export LUMEN_AI_PROVIDER="openai"
export LUMEN_AI_MODEL="gpt-5-mini"
export LUMEN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# 使用配置文件为每个项目覆盖设置
{
  "provider": "ollama",
  "model": "llama3.2"
}

# 或者使用 CLI 标志覆盖
lumen -p "ollama" -m "llama3.2" draft

贡献者

由 contrib.rocks 制作。

想要贡献吗？

欢迎任何贡献！请随时提交 Pull Request。

星标历史

Lumen 快速上手指南

Lumen 是 AI 编码代理时代的代码审查工具，提供美观的差异查看器、智能提交消息生成及多模型 AI 支持。

环境准备

在开始之前，请确保您的系统满足以下要求：

1. Git: 必须已安装并配置好。
2. fzf (可选): 用于 lumen explain --list 的交互式模糊搜索。
   • 安装参考：junegunn/fzf
3. mdcat (可选): 用于终端内渲染美观的 Markdown 输出。
   • 安装参考：swsnr/mdcat

注意：基础的 diff 命令无需任何额外配置即可直接使用。若需使用 explain、draft 等 AI 功能，需配置 API Key。

安装步骤

方式一：使用 Homebrew (推荐 macOS/Linux 用户)

brew install jnsahaj/lumen/lumen

方式二：使用 Cargo (Rust 包管理器)

如果您已安装 Rust 环境，可直接通过 cargo 安装：

cargo install lumen

提示：国内用户若遇到下载缓慢，可配置 Rust 镜像源：

export CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse
export CARGO_REGISTRIES_CRATES_IO_INDEX=https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git

基本使用

1. 配置 AI 功能 (可选)

若需使用智能生成提交信息或解释代码变更等功能，请先运行交互式配置向导：

lumen configure

按提示选择 AI 提供商（如 OpenAI, Claude, Ollama 等），输入 API Key 并选择模型。配置将保存至 ~/.config/lumen/lumen.config.json。

2. 查看代码差异 (Visual Diff)

启动终端内的交互式并排差异查看器，支持语法高亮和注释：

# 查看未提交的更改
lumen diff

# 查看特定提交的更改
lumen diff HEAD~1

# 查看分支间差异
lumen diff main..feature/A

# 堆叠模式：逐个审查一系列提交
lumen diff main..feature --stacked

常用快捷键：

• j/k 或方向键：导航
• { / }：跳转到上一个/下一个代码块 (hunk)
• i：添加注释 (支持选中行、代码块或整个文件)
• space：标记文件为已读
• ?：查看所有快捷键

3. 生成提交消息 (Smart Commit)

根据暂存区（staged）的更改自动生成符合规范的提交消息：

# 基础用法
lumen draft
# 输出示例：feat(button.tsx): Update button color to blue

# 添加上下文以生成更精准的消息
lumen draft --context "match brand guidelines"
# 输出示例：feat(button.tsx): Update button color to align with brand identity guidelines

实用技巧：直接提交

lumen draft | git commit -F -

4. 解释代码变更 (Explain Changes)

利用 AI 分析变更内容及其潜在影响：

# 解释当前工作目录的所有更改
lumen explain

# 仅解释暂存区的更改
lumen explain --staged

# 针对特定提交提问
lumen explain HEAD --query "这些更改对性能有什么影响？"

# 交互式选择提交进行解释 (需安装 fzf)
lumen explain --list

5. 生成 Git 命令 (Operate)

通过自然语言描述让 Lumen 生成复杂的 Git 命令：

lumen operate "squash the last 3 commits into 1 with the message 'squashed commit'"
# 输出预览：git reset --soft HEAD~3 && git commit -m "squashed commit" [y/N]

系统会展示命令解释及安全警告，确认无误后输入 y 执行。