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 三个核心功能的定位先明确功能边界避免做成一个四不像。功能模块解决什么问题核心交互分支树快速看清仓库有哪些分支、各分支相对位置、当前在哪条分支上下键选择分支回车切换分支或查看详情提交历史看清最近提交、每个提交改了什么、作者和时间上下键浏览回车展开 diff 详情工作区操作看清工作区状态、暂存区变化执行 add/commit/restore快捷键暂存、提交、恢复文件这三个模块不是割裂的它们共享同一个 Git 状态层。分支树里切换分支后提交历史和工作区面板要立刻刷新。提交历史里选中一个提交工作区如果正好在这个提交上有 diff应该能看到关联变化。整个面板要有联动的感觉而不是三个互不相干的小工具。2.2 形态选型为什么是 TUI 而不是 Web我最初想过做 Web 面板浏览器里展示分支树确实好看。但想了十分钟就放弃了。Web 方案意味着要启动一个本地服务监听端口然后还要处理 Codex 和这个服务之间的会话关系。用完之后服务挂在后台要么没人关要么端口冲突。对于一个只是在终端里临时看一眼仓库状态的场景这个启动链路太长了。TUI 方案的优势在于零摩擦面板直接在当前终端里渲染和 Codex 共用同一个终端启动就是codex-git-panel一个命令的事退出就是 CtrlC。而且 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/remotesrefname: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 --dateiso-strict --max-count200 \ --prettyformat:%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 --skip200加载下一批这样交互顺滑启动也快。4.2 提交详情与 diff 查看选中一条提交后回车我展示完整 diff。这里用git showgit -c core.quotepathfalse 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 误操作比人误操作更难发现。所以我把所有操作分为三类操作级别操作内容触发方式只读status、diff、查看文件变更无需确认默认确认add、commit、restore、checkout执行前弹确认框双重确认reset --hard、clean -fd输入confirm才能执行git add这种操作虽然不危险但考虑到 AI 可能同时改了很多文件一字排开全部暂存还是挺吓人的。所以即便是我自己手动时常用的git add -A在面板里也要求先展示完整的暂存文件列表确认后再执行。reset --hard和clean -fd是一旦执行就无法轻易撤销的操作所以除了确认框还要让用户手动输入完整的英文单词confirm。这个设计最初可能觉得繁琐但实际使用中正是这道门槛挡住了好几次手滑。5.2 解析工作区状态工作区状态的解析用git status --porcelainv2这是给程序准备的机器可读输出比普通 status 稳定得多。git status --porcelainv2 --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_EDITORtrue环境变量让 git 认为编辑器是true也就是什么都不做直接成功。const env { ...process.env, GIT_EDITOR: true }; execFile(git, [commit, -m, message], { env });这样就能保证不带交互、不会弹出 vim干干净净地提交。其他核心操作我整理成一个表格操作实际命令注意点暂存文件git add -- path用--分隔路径防止路径以-开头被当成参数取消暂存git restore --staged -- path不会改动工作区内容恢复文件git restore -- path有未提交修改且想放弃时使用要二次确认切换分支git checkout branch如果工作区有冲突改动git 会拒绝要捕获 stderr 提示丢弃所有修改git reset --hard target必须输入confirm才能执行其中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 看。 第二条是 MCPModel 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 问题速查表先把踩过的坑整理成一张速查表方便你直接对号入座现象原因解决方式偶发Unable to create .../index.lockCodex 和面板同时执行写操作给所有 git 写操作加互斥锁队列中文文件名显示成\346\226\207\344\273\266core.quotepath默认开启转义执行层统一加-c core.quotepathfalsegit log输出被截断或卡住git 在部分环境触发分页器统一加GIT_PAGERcat和--no-pager点开合并提交看不到 diffgit show对合并提交默认不输出 diff加-m参数emoji 和中文在截断时出现乱码按字节长度截断字符串用按显示宽度截断的视觉方式处理从 Codex 启动面板时找不到 nodeslash command 的环境变量 PATH 不完整命令文件里显式设置 PATH 或使用绝对路径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.quotepathfalse让 git 直接输出原始字符。这之后再遇到中文文件名、带空格文件名都能正确处理。6.3 Codex 面板联动时的环境问题这里再说一个 slash command 特有的坑。Codex 调用命令文件时它自己的子进程环境不一定包含用户的完整 shell 环境变量。比如我用的 nvm 安装的 NodePATH 里需要包含~/.nvm/versions/node/...但 Codex 的子进程默认继承的是精简 PATH结果面板根本启动不起来报了command not found: node。折腾了几个小时的排查最后定位到问题不在面板代码而在启动方式。解决方法是把命令文件改成显式加载用户环境#!/usr/bin/env bash source ~/.bashrc codex-git-panel --root {{.WorkingDirectory}}另外EDITOR环境变量也会影响 git 的行为。如果用户配了编辑器而面板没有设置GIT_EDITORtrue那么 commit 时 git 会尝试启动编辑器在非交互式环境里直接卡死。这个问题虽然我在设计时已经规避但后来给别人用时又踩了一次说明它确实容易遗漏。6.4 关于稳定优先的一点体会这个项目开发到后期我最大的感悟是给 AI 做工具稳定永远是第一位的。分支树不需要画得像 GitHub 网页那么精美提交历史也不需要秒级响应但如果命令执行结果不可靠、路径解析出错、或者在最不该出现的时候弹出一个交互编辑器那这个工具就失去了存在的意义。所以我后来把所有 git 命令调用都收敛到一个执行层里统一处理环境变量、分页器、编码参数、锁并发。UI 层只是一个壳真正的血泪都在这个执行层里。这也算是给后续要维护这个项目的我一点安慰至少所有脏活都集中在一个文件好排查。最后再分享一个小技巧如果你也在做类似的终端工具建议给所有 git 命令的执行加上超时控制。我设置了 10 秒超时超过就杀掉进程并输出错误。这能防止在某些网络驱动器上 git 命令长时间挂起导致整个面板像死机一样。自从加了超时面板的稳定性又上了一个台阶。
