企业官网建设流程全解析

如何从diff自动生成提交信息？Worktrunk llm-commits机制详解

【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk

Worktrunk是一款面向并行 AI Agent 工作流的 Git worktree 管理 CLI，它的llm-commits 机制能把 git diff 直接交给大模型，自动生成提交信息——你不再需要每次手写 commit message，AI 会替你"读改动、写摘要"，并在wt step commit、wt step squash、wt merge时自动生效。本文带你快速上手，并拆解这套机制的底层原理。

🤔 为什么需要自动生成提交信息

• 手写繁琐：多个 worktree 并行开发（尤其是 AI Agent 干活、人审核的场景）意味着频繁提交，每次都要停下来琢磨措辞；
• 风格不一：团队里提交信息格式混乱，难以追溯；
• 合并成本高：squash 合并时还要再"综合"多条提交信息。

Worktrunk 的思路很直接：把 diff 当作"原料"，用 LLM 当"笔"。只要一条能"从 stdin 读入提示词、向 stdout 输出提交信息"的命令，就能接入。

📦 三步开启 AI 自动生成提交信息

第 1 步：拿到 Worktrunk

从仓库克隆后按 README.md 说明构建安装，或在包管理器中搜索 Worktrunk 安装。

git clone https://gitcode.com/GitHub_Trending/wo/worktrunk

第 2 步：配置一条 LLM 命令

在用户配置文件~/.config/worktrunk/config.toml中加入[commit.generation]区块。官方为常见工具都准备好了推荐命令（完整清单见 dev/config.example.toml）：

配置示例：

[commit.generation] command = "llm -m claude-haiku-4.5"

💡 第一次提交时如果尚未配置，Worktrunk 会自动探测本机已安装的claude/codex/opencode，并弹窗引导一键写入推荐配置（相关逻辑见 src/output/commit_generation.rs）。

第 3 步：体验自动提交

在有改动的 worktree 里执行：

wt step commit

效果大致如下（演示脚本快照见 docs/demos/snapshots/wt-commit.snap）：

◎ Generating commit message and committing changes... (2 files, +25) feat(validation): add input validation utilities Add validation module with is_positive and is_non_empty helpers for validating user input. Includes comprehensive test coverage. ✓ Committed changes @ 08d6aa2

合并时wt merge会把未提交改动 + 分支提交压缩成一个 commit，同样自动生成信息；压缩场景还能用wt step squash单独完成。

📌没有配置 LLM 也不会卡住：Worktrunk 会退化为确定性消息，例如Changes to auth.rs & config.rs，保证流程永远可用。

🔍 机制详解：从 diff 到提示词，Worktrunk 做了什么

整个流程在 src/llm.rs 中实现，可以概括为四步：

1️⃣ 收集上下文针对提交场景执行git diff --staged与--stat，同时取当前分支名、仓库名和最近 5 条提交标题（供 LLM 模仿既有风格）；squash 场景则取合并基点到 HEAD 的合并 diff 与各条提交的 subject/body。

2️⃣ 智能控制体积提示词有 100KB 的 diff 预算，超限时分两级处理：

• 先剔除*.lock、-lock.json等锁文件（机器生成的噪音）；
• 仍超限则每个文件截断到最多 50 行、每行 500 字节，并在省略处留下标记。

这样即使一次提交改动上万个文件，提示词也不会撑爆模型上下文。

3️⃣ 模板渲染提示词使用 minijinja 模板引擎渲染，可用变量如下：

4️⃣ 调用外部命令渲染好的提示词通过stdin管道发送给配置的命令，捕获 stdout 作为最终提交信息。若命令执行缓慢，界面会显示"等待中"的看门狗状态；执行失败时会给出一条可直接复制的复现命令（如wt step commit --show-prompt | <你的命令>），方便排查。

✨ 进阶：自定义模板与团队共享规范

• 整体替换：template/squash-template可用任意 Jinja2 风格模板覆盖默认提示词，比如要求"标题不超过 50 字符、只输出正文"；
• 追加引导：template-append不必重写整个模板，只需追加风格要求。它同时存在于用户配置（个人偏好）与项目配置.config/wt.toml（团队共享）中，项目片段首次使用时会弹出一次性审批，拒绝也不影响提交（详见 docs/public/llm-commits.md）；
• 分支摘要：配置[list] summary = true后，wt list --full会为每个分支生成一行 AI 摘要，且带缓存——只有 diff 变化时才重新生成。

❓ 常见问题

Q1：如何查看 Worktrunk 到底发了什么提示词？给wt step commit/wt step squash加上--show-prompt即可打印渲染后的完整提示词。

Q2：配置文件在哪里？macOS/Linux 位于~/.config/worktrunk/config.toml（支持$XDG_CONFIG_HOME），Windows 位于%APPDATA%\worktrunk\config.toml。

Q3：LLM 返回空内容会怎样？会明确报错"LLM returned empty message"，不会把空信息写进提交历史。

Q4：提示词太大会不会很慢？有 100KB 预算兜底，且默认模板建议使用 haiku 级别的高速小模型，日常改动通常在几秒内完成。

📚 小结

Worktrunk 的 llm-commits 机制用"diff 进、提交信息出"的管道设计，把 LLM 变成了一个即插即用的"提交文案助手"：一条[commit.generation]配置即可接入 Claude Code、Codex、OpenCode、llm、aichat 等工具，配合模板变量与template-append，既能服务个人工作流，也能把统一的提交规范沉淀到团队项目配置中。完整文档见 docs/public/llm-commits.md。

【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk