为Codex打造终端Git面板：分支树、提交历史与工作区操作实战

1. 起因：为什么我会给 Codex 做一个 Git 面板

1.1 真正让人头疼的不是生成代码，而是版本状态

做这个项目的起因特别实际：我让 Codex 在本地仓库里跑一轮持续好几天的功能迭代，它每天都会自己建分支、改文件、提交、再切到别的分支去处理问题。表面看一切正常，但问题出在"我看不到全貌"。

Codex 确实能执行 git 命令，比如git status、git log，但它返回的是文字。文字最大的问题是没有空间感。仓库里现在有几条分支？每条分支领先或者落后主分支多少？哪个提交还没推上去？工作区有哪些文件被改了？这些问题如果靠一屏一屏翻对话记录去拼，脑负担特别大。

有一次它提交错了文件，然后在对话里说"我建议你手动 reset 一下"。那一瞬间我就意识到，我需要一个能直接看到仓库结构的工具，而不是靠 Codex 用文字描述仓库长什么样。于是就有了这个 Git 面板：分支树、提交历史、工作区操作，三个核心区块，全部跑在终端里，Codex 能调用，我也能手动看。

这个项目适合谁？两类人。第一类是和我一样重度使用 Codex 这类终端 AI 编程工具的人，需要随时掌握仓库状态；第二类是嫌git log --graph不够直观、又不想为了看个分支装一整套重量级 GUI 的人。

1.2 现有的方案到底差在哪

动手之前，我先把市面上的方案都过了一遍，结论是"能用，但都有点别扭"。

VS Code 里的 GitLens 功能确实强大，能看 blame、能看分支图、能看历史。但我的工作流是纯终端流，Codex 在终端里跑，代码也在终端里改，为了看仓库状态再切到 VS Code，来回切换的成本太高。

lazygit 是个非常好的 TUI 工具，我也用过一段时间。它的问题在于交互设计面向的是"人直接操作"，快捷键多到记不住，而且它没有为外部 AI 程序提供稳定的调用接口。如果让 Codex 去操作 lazygit，每次都要处理键位映射，非常脆弱。

还有一类方案是给 git 配 alias，比如git tree、git lg之类的命令。这类方案轻，但本质还是文本输出，分支多了以后字符画会糊成一片，别说分支树，连阅读都费劲。

我的结论很明确：我需要一个轻量的、直接在终端里跑的、既能人看又能让 Codex 调用的 Git 面板。它不是要取代 lazygit，也不是要复制 GitLens，它只需要把分支树、提交历史、工作区操作这三件最常用的事做清楚。

2. 整体设计：一个全部跑在终端里的 Git 面板

2.1 三个核心功能的定位

先明确功能边界，避免做成一个四不像。

这三个模块不是割裂的，它们共享同一个 Git 状态层。分支树里切换分支后，提交历史和工作区面板要立刻刷新。提交历史里选中一个提交，工作区如果正好在这个提交上有 diff，应该能看到关联变化。整个面板要有"联动"的感觉，而不是三个互不相干的小工具。

2.2 形态选型：为什么是 TUI 而不是 Web

我最初想过做 Web 面板，浏览器里展示分支树确实好看。但想了十分钟就放弃了。

Web 方案意味着要启动一个本地服务，监听端口，然后还要处理 Codex 和这个服务之间的会话关系。用完之后服务挂在后台，要么没人关，要么端口冲突。对于一个只是在终端里临时看一眼仓库状态的场景，这个启动链路太长了。

TUI 方案的优势在于零摩擦：面板直接在当前终端里渲染，和 Codex 共用同一个终端，启动就是codex-git-panel一个命令的事，退出就是 Ctrl+C。而且 TUI 通过 ANSI 转义序列实现界面刷新，完全不需要浏览器渲染引擎，内存占用低很多。

2.3 技术栈与目录结构

技术选型上，我用了 Node.js + TypeScript + Ink。Ink 是 Vercel 出品的 React 终端渲染库，把 React 组件模型搬到了终端里，用 flexbox 布局来摆界面元素。选它而不是 blessed，是因为我熟悉 React 的思维模式，而且 Ink 对"组件化面板"的支持好很多，状态管理可以直接用 React 的 useState、useEffect。

Git 数据的获取，最关键的决策是：不用 nodegit 这类 libgit2 封装库，直接用child_process调用本机 git CLI。原因是 git CLI 才是唯一的事实标准，如果封装库行为和本地 git 版本不一致，排查起来特别痛苦。用 CLI 固然要自己解析字符串，但至少保证：你拿到的结果就是真实 git 会给出的结果。

项目目录结构如下：

codex-git-panel/ ├── package.json ├── tsconfig.json ├── commands/ │ └── git-panel.md # Codex slash command 入口 ├── src/ │ ├── index.ts # 程序入口 │ ├── git/ │ │ ├── exec.ts # 统一 git 命令执行层 │ │ ├── graph.ts # 分支树数据构建 │ │ ├── history.ts # 提交历史解析 │ │ └── status.ts # 工作区状态解析 │ └── ui/ │ ├── App.tsx # 主界面布局 │ ├── BranchTree.tsx # 分支树面板 │ ├── HistoryList.tsx # 提交历史面板 │ └── WorktreePanel.tsx # 工作区操作面板

主界面是三栏布局：左侧分支树，右上提交历史，右下工作区操作。用 Ink 的<Box>组件做 flex 布局，终端宽度低于 80 列时自动隐藏工作区面板，保证基本可用性。

3. 分支树：把 Git 拓扑搬进终端

3.1 分支数据从哪来

要画分支树，第一步是拿到仓库里所有分支以及它们指向的提交。用git for-each-ref这个命令最合适，它专门用于枚举 ref，性能好，格式可控。

git for-each-ref --sort=-committerdate \ --format='%(refname:short)|%(objectname:short)|%(committerdate:iso8601)|%(subject)' \ refs/heads refs/remotes

refname:short是分支名，objectname:short是它指向的 commit 短哈希，committerdate是最后提交时间，subject是最近一条提交的主题。按提交时间倒序排，这样最活跃的分支永远排在最上面。

这里有个细节：refs/remotes会把origin/HEAD这种符号引用也带出来，它指向的是远程默认分支，不是真正的分支。解析时要过滤掉这种以/HEAD结尾的条目，否则分支树会多出一条假分支。

3.2 把 commit 关系变成树

有了分支顶部的位置还不够，我想展示出"分支是从哪个基点分出来的"这种层次关系。

完整做法是读取所有提交的 parent 关系，构建 DAG（有向无环图），然后用图布局算法去画线条。我第一版就这么干的，结果意料之中的糟糕：当仓库有二十多条分支、几百次合并提(d交)时，交叉线多得根本看不清。

后来我换了个思路：不画完整 commit DAG，只画一张"分支关系树"。先找到每条分支和当前分支的 merge-base，也就是分叉点，然后以分叉点为基准计算这条分支相对当前分支是领先了多少个提交。这样展示出来的效果非常干净。

数据结构上，我前后端统一用一种节点类型：

interface BranchNode { name: string; commit: string; // 分支指向的 commit 短哈希 base: string; // 与当前分支的 merge-base 短哈希 ahead: number; // 领先 base 多少提交 lastSubject: string; // 最近提交主题 kind: "local" | "remote"; isCurrent: boolean; }

ahead的计算用git rev-list --count <base>..<branch>，这个命令会快速统计两者之间的提交差异。如果ahead是 0，说明这条分支就是当前分支的直接后代，在树里缩进一级展示；如果不是，就单独一个分组展示。

这种设计放弃了"精确的交叉线"，换来的是信息的清晰度。我觉得对终端里快速判断"我该切到哪条分支、哪条分支是新的"来说，这个取舍非常值得。

3.3 分支树渲染策略与视觉细节

渲染层我用 Ink 自绘。每一行左侧是对齐的树形缩进，右侧是分支名、领先数、最近提交主题。

颜色的设计是：

• 当前分支：绿色高亮，前面加一个*
• 本地分支：默认前景色
• 远程分支：黄色，前缀显示origin/
• 落后或领先的分支会在末尾显示[behind 3]、[ahead 5]这类标记

终端宽度有限，提交主题超过行宽要截断。我一开始直接用字符串slice，结果中文和 emoji 会被切出乱码。后来改用visual库按显示宽度截断，保证截断处不会破掉字符边界，超出部分打...。

还有一个值得注意的点：刷新策略。分支树不能只在启动时读一次，因为 Codex 随时可能创建分支、删除分支。我做了个简单的轮询，每 5 秒拉一次git for-each-ref的最新数据，如果 ref list 变了才重绘。实测下来性能影响可以忽略，但信息新鲜度提升很大。

4. 提交历史：不只是把 git log 拿过来

4.1 格式化输出里的坑

提交历史的核心数据来自git log，但要小心格式化字符串。

git log --date=iso-strict --max-count=200 \ --pretty=format:'%x1f%H%x1f%P%x1f%an%x1f%ae%x1f%ad%x1f%s%x1f%b%x1f%D'

这里%x1f是 ASCII 分隔符 0x1f，我用它而不是|或者逗号，是因为 commit message 里可能包含任何字符，唯独控制字符 0x1f 几乎不可能出现。用不可见字符做分隔符，解析的时候就绝对安全，不需要担心消息内容里的符号把字段拆坏。

每个字段的含义是：完整哈希、父提交哈希，作者名、作者邮箱、ISO 8601 格式时间、主题、正文、ref 名称列表（比如HEAD -> main, tag: v1.0）。正文和 ref 列表是容易踩坑的地方，%b是多行内容，里面可能带换行；%D可能为空。解析时要用split(/\x1f/)拿前 6 个字段，剩下的合并处理，不要用固定长度切割。

提交历史面板默认只加载 200 条。原因很朴素：渲染 200 条 commit 在 Ink 里是很快的，但解析%b长正文时会慢。每次进入面板都解析几千条提交没有意义，用户根本看不完。滚动到底部时再通过git log --skip=200加载下一批，这样交互顺滑，启动也快。

4.2 提交详情与 diff 查看

选中一条提交后回车，我展示完整 diff。这里用git show：

git -c core.quotepath=false show --stat --format='%H%n%an%n%ad%n%s%n%b' -m <sha>

注意-m参数，这个参数对普通提交没有影响，但它能强制合并提交显示 diff。合并提交默认情况下git show是不输出 diff 内容的，第一版我没加这个参数，点进去看到一片空白，排查了半天才意识到是合并提交的默认行为。

diff 超过 300 行时，面板只显示前 300 行，然后给一行提示"diff 过长，已截断"。本意是防止大文件 diff 把终端刷爆，实际用下来这个策略很有效，尤其是在 Codex 批量修改了一堆文件的时候。

4.3 性能优化：避免每次全量读取

刚开始我图省事，每次刷新都重新执行一次完整git log。仓库小没问题，但跑在一个有两万个提交的项目里，每次刷新都要卡两三百毫秒，上下键操作时明显掉帧。

现在的做法是缓存提交历史列表，只监听可能影响历史的信号：HEAD 是否变化、ref 列表是否变化。这两个信号都可以通过前面分支树模块的轮询结果顺带拿到。如果 HEAD 没变、ref 没变，就不重新拉日志，直接用缓存。

说到底，提交历史这个模块的复杂度不在功能本身，而在"如何让它快"。配合增量加载和缓存，现在上下键滚动完全没有迟滞感，Codex 提交了新的 commit 后，面板最多 5 秒就能刷新出来。

5. 工作区操作：给 AI 装上一道安全门

5.1 工作区操作的安全分级

工作区操作是三个模块里最敏感的，因为涉及修改文件、提交代码。尤其这个面板是给 Codex 用的，如果 AI 误操作，比人误操作更难发现。所以我把所有操作分为三类：

git add这种操作虽然不危险，但考虑到 AI 可能同时改了很多文件，一字排开全部暂存还是挺吓人的。所以即便是我自己手动时常用的git add -A，在面板里也要求先展示完整的暂存文件列表，确认后再执行。

reset --hard和clean -fd是一旦执行就无法轻易撤销的操作，所以除了确认框，还要让用户手动输入完整的英文单词confirm。这个设计最初可能觉得繁琐，但实际使用中，正是这道门槛挡住了好几次手滑。

5.2 解析工作区状态

工作区状态的解析用git status --porcelain=v2，这是给程序准备的机器可读输出，比普通 status 稳定得多。

git status --porcelain=v2 --branch

输出大概长这样：

# branch.oid <hash> # branch.head main # branch.upstream origin/main # branch.ab +2 -1 1 .M N... 100644 100644 100644 <hash> <hash> src/index.ts 1 M. N... 100644 100644 100644 <hash> <hash> src/app.ts ? docs/todo.md

每条记录的第一个字段是变更类型，三语说明：

• 1表示已跟踪文件，后面紧跟工作区状态和暂存区状态
• 2表示重命名或复制
• ?表示未跟踪文件
• 第二字段第一个字符是暂存区状态（.表示无变化，M、A、D、R、C分别表示修改、新增、删除、重命名、复制）
• 第三字符是工作区状态，含义类似

我把这些状态映射成面板里的标签：已暂存、已修改、新增、已删除、未跟踪。按目录折叠展示，文件多时先显示目录级别统计，展开后才逐个显示文件。

5.3 核心操作的实现

实际执行 Git 操作时，最需要注意的坑是外部编辑器。git commit 默认会打开配置的编辑器，在 TUI 面板里这绝对是灾难。所以我在执行层统一设置了GIT_EDITOR=true环境变量，让 git 认为编辑器是true，也就是"什么都不做直接成功"。

const env = { ...process.env, GIT_EDITOR: "true" }; execFile("git", ["commit", "-m", message], { env });

这样就能保证不带交互、不会弹出 vim，干干净净地提交。

其他核心操作我整理成一个表格：

其中git checkout和分离头指针（detached HEAD）的边界情况最麻烦。如果当前处于detached HEAD，面板顶部会显示一个明显的警告条，而且禁止直接输入checkout目标分支以外的操作，避免用户在一个无名的 commit 上做了修改后找不到分支归属。

5.4 如何让 Codex 调用它

面板不能只有人看，还得能被 Codex 调用。我打通了两条路。

第一条是 Codex 的 slash command。Codex 会读取~/.codex/commands/下的 Markdown 文件作为自定义命令。我在里面放了一个git-panel.md：

# 启动 Codex Git 面板 当用户需要查看分支树、提交历史或工作区状态时，使用面板工具。 运行方式： ```bash codex-git-panel --root "{{.WorkingDirectory}}" --non-interactive

面板会输出当前仓库的分支树、最近提交历史和未提交变更摘要。

`{{.WorkingDirectory}}` 是 Codex 提供的模板变量，会替换成当前项目路径。`--non-interactive` 模式表示不需要人类操作，面板直接输出机器可读的摘要给 Codex 看。 第二条是 MCP（Model Context Protocol）工具。我在 Codex 的 `config.toml` 里把面板注册成 MCP server，这样 Codex 就能像调用函数一样调用面板的各个能力： ```toml [mcp_servers.git-panel] command = "codex-git-panel" args = ["--mcp"]

对应的 MCP 工具包括：

• git_branch_tree— 获取分支树摘要
• git_commit_history— 获取最近的提交列表
• git_worktree_status— 获取工作区状态
• git_stage_files— 暂存指定文件
• git_commit— 创建提交
• git_restore— 恢复文件

给 AI 集成的工具，接口要尽量窄、返回值要尽量结构化。我在 MCP 模式下统一返回 JSON，而不是终端渲染的彩色字符串，这样 Codex 解析起来可靠得多。

6. 踩坑实录：开发这个面板时遇到的 6 个坑

6.1 问题速查表

先把踩过的坑整理成一张速查表，方便你直接对号入座：

6.2 两个值得展开说的深坑

第一个是index.lock并发问题。有一次 Codex 正在自动执行git add . && git commit，此时我手动在面板里想暂存一个文件，结果直接报错。排查后发现，git 在执行写操作前会创建.git/index.lock，如果另一个进程已经在写索引，第二个进程就会失败。这个错误不是偶发的，Codex 的自动操作越频繁，撞上的概率越高。

解决方法是把所有 git 写操作放进一个互斥队列，面板内的写命令同时只能有一个在执行。同时执行前检测.git/index.lock是否存在，存在就先提示"另一个 git 操作正在进行"，而不是盲目重试。实测这个改进之后，面板再也没有因为索引锁崩溃过。

第二个坑是core.quotepath。git 默认会把非 ASCII 的文件名转义成八进制序列，比如中文文件文档.md会显示成\346\226\207\344\273\266.md。普通命令行里你看习惯了还好，但在 TUI 面板里，这个转义序列会让文件名完全不可读，也没法直接传给git add。

既然所有显示和操作都依赖路径，我选择在统一的 git 执行层里加上-c core.quotepath=false，让 git 直接输出原始字符。这之后再遇到中文文件名、带空格文件名都能正确处理。

6.3 Codex + 面板联动时的环境问题

这里再说一个 slash command 特有的坑。Codex 调用命令文件时，它自己的子进程环境不一定包含用户的完整 shell 环境变量。比如我用的 nvm 安装的 Node，PATH 里需要包含~/.nvm/versions/node/...，但 Codex 的子进程默认继承的是精简 PATH，结果面板根本启动不起来，报了command not found: node。

折腾了几个小时的排查，最后定位到问题不在面板代码，而在启动方式。解决方法是把命令文件改成显式加载用户环境：

#!/usr/bin/env bash source ~/.bashrc codex-git-panel --root "{{.WorkingDirectory}}"

另外EDITOR环境变量也会影响 git 的行为。如果用户配了编辑器，而面板没有设置GIT_EDITOR=true，那么 commit 时 git 会尝试启动编辑器，在非交互式环境里直接卡死。这个问题虽然我在设计时已经规避，但后来给别人用时又踩了一次，说明它确实容易遗漏。

6.4 关于"稳定优先"的一点体会

这个项目开发到后期，我最大的感悟是：给 AI 做工具，稳定永远是第一位的。分支树不需要画得像 GitHub 网页那么精美，提交历史也不需要秒级响应，但如果命令执行结果不可靠、路径解析出错、或者在最不该出现的时候弹出一个交互编辑器，那这个工具就失去了存在的意义。

所以我后来把所有 git 命令调用都收敛到一个执行层里，统一处理环境变量、分页器、编码参数、锁并发。UI 层只是一个壳，真正的血泪都在这个执行层里。这也算是给后续要维护这个项目的我一点安慰：至少所有脏活都集中在一个文件，好排查。

最后再分享一个小技巧，如果你也在做类似的终端工具，建议给所有 git 命令的执行加上超时控制。我设置了 10 秒超时，超过就杀掉进程并输出错误。这能防止在某些网络驱动器上 git 命令长时间挂起，导致整个面板像死机一样。自从加了超时，面板的稳定性又上了一个台阶。