我做 Codex 的时候最抓狂的从来不是它改代码改得不对而是它改完之后我根本没法快速判断它到底动了什么。你在终端里把 Codex 跑起来让它重构一个接口它埋头干半天提交了三五个 commit切了好几次分支还顺手 stash 了一堆改动。等你回来想看情况终端里早被日志刷屏了只剩一个命令提示符安静地等你输入。你不知道它在哪个分支、工作区是不是干净、中间提交了什么、那些被 stash 的东西是什么——这才是我决定做一个 Git 面板的起点。这篇文章就把我做这个东西的全过程拆开讲从需求分析、技术选型到分支树、提交历史、工作区操作的实现细节再到真实使用中踩过的坑。这个面板不复杂核心就是用 Node.js 包一层 Git 命令再做一个单页 Web 界面但它解决的痛点是实打实的——任何一个长期用 Codex 写代码的人都值得花半天时间给自己配一个。1. 先弄清楚Codex 在 Git 上到底给你搞出了什么问题1.1 三个真实痛点第一是“看不见”。Codex 不像人它不会做完一件事就停下来跟你汇报。它可能在后台连续执行几十个操作每一个操作都会改变工作区、暂存区或者提交历史。等它运行时你只能看它打出来的文本日志但如果日志很长关键信息会被冲掉。而且 Codex 经常“自作主张”——比如它发现当前分支不对会自己切一个分支 发现文件有冲突会自己 reset 掉一部分改动。第二是“历史乱”。Codex 生成提交信息的水准其实还行但它数量多而且频率不规律。有时候它为了一个很小的改动就提交两次有时候一个大的重构挤在一个 commit 里。你自己用 Git 的时候习惯了“一次提交一个逻辑单元”的节奏但 AI 没有这个习惯。这时候你特别需要一种可视化视图把分支、提交、合并、分叉一次性看清楚。第三是“抢键盘”。你在终端里想查看状态、切分支、恢复文件而 Codex 正在同一个仓库里跑它的下一个命令随时会执行。你手动敲一行git checkout它那边可能刚好在改同一个文件。这种碰撞非常危险。有了面板你可以只读地观察一切把写操作留到它跑完再执行风险小很多。1.2 把需求拆成功能清单我当时把需求梳理成了这样分支树能够把所有本地分支、远程分支、提交节点、合并关系在一张图里展示出来高亮当前 HEAD。提交历史能按时间倒序看提交看到每次提交的文件改动统计最好能点击看 diff。工作区状态能区分已暂存、未暂存、未跟踪、冲突文件并且显示每个文件的增删行数。工作区操作支持常见的 add、commit、restore、stash、switch、clean 等操作但要有确认机制不能误操作。配套能力能够显示“最近 AI 操作”的事件流让我知道 Codex 在我离开期间到底做了什么。注意这个面板不是要替代 IDE 的 Git 插件而是要做成一个独立的、浏览器里打开的、随时可刷新的本地工具。它的核心使用场景是“Codex 跑任务时我盯着面板看它的进展”。2. 面板的整体设计一杯咖啡时间的选型2.1 为什么还是 Node.js选择 Node.js 有几个很实际的理由Codex CLI 本身跑在 Node 生态里我的机器上早就有了 Node 运行时child_process调 Git 命令非常直接前端我只需要一个静态 HTML 页面不需要额外起重型框架。如果你更喜欢 Python也可以把下面的细节平移到subprocess但我在选型时倾向于少引入一个运行时。还有一点我想要一个真正意义上的“本地服务”不仅是静态页面还要能执行命令、处理并发、做安全的参数传递。Node.js 的spawn天然适合这个场景它支持参数数组不需要手工拼接 shell 字符串避免了很多注入和转义问题。2.2 一个本地 Git 服务的分层结构这个面板在结构上分四层Git 命令执行器统一封装spawn调用处理 cwd、env、超时、错误捕获。解析层把git status --porcelain、git log --pretty、git diff --numstat的输出解析成 JSON。API 层用 Express 暴露/api/branches、/api/commits、/api/status、/api/diff等接口。前端渲染层一个 HTML 页面拉 API、渲染树状图和表格、绑定操作按钮。核心的命令执行器长这样const { spawn } require(child_process); function execGit(args, options {}) { return new Promise((resolve, reject) { const child spawn(git, args, { cwd: options.cwd || projectRoot, env: { ...process.env, ...options.env }, shell: false, }); let stdout ; let stderr ; child.stdout.on(data, (d) { stdout d.toString(); }); child.stderr.on(data, (d) { stderr d.toString(); }); child.on(close, (code) { if (code 0) { resolve({ stdout, stderr }); } else { reject(new Error(git ${args.join( )} failed with code ${code}: ${stderr})); } }); child.on(error, (err) reject(err)); }); }这里有两个容易被忽略的点。第一必须显式设置shell: false这样参数数组才会被当作参数直接传给 Git不会经过 shell 解析。第二需要注意stdout和stderr的编码我在 Windows 上遇到过默认编码不是 UTF-8 导致的乱码问题一般在env里显式设置一下相关环境变量能缓解。2.3 只读优先写操作单独开开关我把面板设计成“默认只读写操作手动打开”。也就是说刚打开面板时只能看分支树、历史、状态和 diff所有提交、切换、恢复按钮都是灰色禁用的。只有你在设置里勾选“启用写操作”它们才亮起来。这么做不是保守是为了和 Codex 协作时保证安全。你想想看面板如果随时可以执行写操作而 Codex 又在后台跑任务两边同时动同一个仓库很容易出现不可预期的问题。写操作单独开一个开关至少能让你意识到“我接下来要做的是有副作用的操作需要自己确认”。3. 分支树如何画出真正可读的提交关系3.1 从 git log --graph 说起分支树是整个面板的视觉中心。一开始我以为可以直接解析git log --graph输出的 ASCII 图形后来发现这条路没那么好走。--graph输出的最大问题是它本质上是 Git 为终端渲染定制的包含了字符画*、|、\、字符合并规则和列分配逻辑是隐式的很难可靠地还原成结构化数据。更可靠的方式是直接读取 Git 的 DAG 数据。每个 commit 对象里有父提交哈希这就是天然的边。我们可以用git log --all --topo-order --prettyformat取节点再用git cat-file --batch或者git rev-list --parents取父提交关系。具体来说git log --all --topo-order --dateiso --prettyformat:%H%x00%P%x00%an%x00%ad%x00%s%x00%D用%H拿节点哈希%P拿父提交哈希列表%D拿引用名称分支、tag、HEAD 标记。这样一条输出就是一个节点解析起来干干净净。3.2 lane 分配与 merge 连线有了节点和边以后剩下的就是布局。Git 的提交图是一个 DAG但画图时我们希望它看起来像一棵“从新到旧”展开的树。这里我使用了一个经典的 lane泳道算法从最新提交开始按--topo-order顺序遍历。每个 commit 被分配到一个整数 lane。如果 commit 有一个父提交那么这个 commit 和它的父提交尽量保持在同一条 lane 上。遇到 merge commit有两个父提交第一个父提交继续在当前 lane 上第二个父提交起一个新的 lane。遇到分支分裂一个 commit 有多个子提交其中一条子线继续在原 lane其他子线另起 lane。渲染时我用 SVG 画点、线、标签。每个提交是一个圆点竖向的实线代表历史延续横向的连线代表 merge 或者分支分叉。当前 HEAD 所在的节点用实心橙色圆点分支 tip 用带名字的小方块标记。这个算法在实际使用中会遇到一些边缘情况。比如--topo-order并不能保证所有分支之间的相对顺序总是直观尤其是多个特性分支交叉合并时线条会有重叠。我在处理时加了一步“后处理”如果发现两条 lane 上的提交之间有交叉就交换兄弟节点的 lane 分配尽量让线条不交叉。3.3 中文乱码和性能问题分支树好看还不够信息得读得出来。第一个坑是中文提交信息乱码。Git 在某些环境下默认会把非 ASCII 路径和内容转义解决方法是设置core.quotepath false并且让 Node 端接收时用 UTF-8 解码。我在执行命令时显式加上了环境变量LC_ALLC.UTF-8或者GIT_CONFIG_PARAMETERS等配置保证输出格式稳定。第二个坑是性能。git log --all在大型仓库里可能返回几万条提交浏览器渲染会直接卡死。我的处理方式是默认只取最近 300 条提交并且只显示包含分支 tip 的连通子图。提供“range”参数面板上有一个输入框可以指定--since或--max-count。SVG 绘制时对超过阈值的连接线做降级处理只显示节点、引用标签和提交信息不画连线。实际经验是300 条对于观察 Codex 一个任务的变更完全够用。如果你盯的是那种持续集成很久的大仓库建议先把范围缩小到“当前分支 最近的合并分叉”而不是一股脑全画出来。4. 提交历史与工作区AI 干了什么一目了然4.1 用 --porcelain 拿稳定状态工作区状态是“AI 操作”的重灾区也是最需要一眼看明白的部分。我早期用git status的普通文本输出做解析后来改成了git status --porcelainv2 -z。为什么因为--porcelain是给机器读的稳定格式-z用 NUL 分隔条目文件名里的空格、换行等特殊字符都不会破坏解析。--porcelainv2的输出条目有很多列包括当前分支索引、原索引、工作区索引、文件路径、原来的路径重命名时等。我重点用前两三个字段判断文件处于什么状态如果第一列是M表示工作区已修改。如果第二列是M第一列是.表示文件在暂存区被修改。如果两列相同表示已暂存且工作区无额外改动。??表示未跟踪文件。我把这些状态映射成表格里的四种颜色红色表示有冲突橙色表示未暂存修改蓝色表示已暂存灰色表示未跟踪。整个页面刷新时我只调用一个/api/status它会同时返回状态列表和每个文件对应的统计信息。4.2 diff 阅读体验优化知道哪些文件改了只是第一步关键还得看改了什么。Codex 一个任务往往牵扯几十个文件如果每点击一个文件就弹出几百行的 diff看得人头晕。我的做法是先展示基于git diff --numstat的增删行统计让用户先判断“这个文件到底改动大不大”。点击文件后再加载真正的 diff。我用git diff --unified3获取标准 diff然后在前端做一个简单的语法着色把新增行、删除行、上下文分色显示。默认只显示前 200 行超过部分折叠点击“展开”再加载。还有一个细节diff 里遇到二进制文件Git 可能输出“Binary files differ”这种情况我直接标记为“二进制文件”不渲染内容。这样才能保持面板干净易懂。4.3 用 reflog 做 AI 操作时间线这是我最得意的一个功能虽然实现很简单。Codex 跑任务时它的每一步 Git 操作都会留下痕迹。与其去解析它的日志不如直接看git reflog。reflog记录了 HEAD 的每次变化包括 checkout、commit、reset、stash 等操作。我在面板里增加了一个“最近操作时间线”每隔几秒刷新一次git reflog --dateiso --prettyformat:%h%x00%gd%x00%gs%x00%cd%x00%an解析出来之后按时间倒序排列每条记录包括操作哈希、操作类型从%gs里解析比如commit:、checkout:、reset:、操作时间和操作人。这样我就能看到 Codex 在几点几分切到了哪个分支、在几点几分提交了哪个 commit。这个时间线和分支树配合起来能让我快速判断它“走没走偏”。有一点要提示reflog有有效期默认 90 天清理一次。如果你想保留更长时间的操作痕迹可以设置gc.reflogExpire为never不过这个改动需要谨慎会让.git目录变大。5. 工作区操作哪些按钮值得放上去5.1 操作的边界整个面板我总共放了七类写操作切换分支git switch恢复文件git restore暂存全部git add -A快速提交git commit -m暂存/取消暂存git stash/git stash pop清理未跟踪文件git clean -fd软重置git reset --soft放按钮之前我问自己一个问题这个操作能撤销吗能撤销的才值得放在面板上不能撤销的我宁可不做。比如说git clean -fd就是一个不可撤销操作我在面板上虽然放了按钮但默认隐藏需要你在设置里手动打开“显示危险操作”并且每次点击都要输入路径或者输入“confirm”字符串。5.2 每一类操作怎么安全落地以“快速提交”为例它的实现难点在于提交信息的默认值。我不会让用户直接输入一大段文字而是提供几个预设选项保持工作区干净chore: snapshot按 AI 建议提交读取一个指定的AI_COMMIT_MESSAGE.md文件手动输入弹出一个多行输入框提交前面板会先检查工作区状态如果有未跟踪文件、有已暂存文件、有未暂存文件会给出不同提示确保用户知道自己提交的是哪些东西。如果发现还在rebase或者merge状态会直接禁用提交按钮。“恢复文件”是一个高频操作也很危险。Codex 经常改着改着就把某个文件改乱了你想回到它改动之前的状态。这里我用两级机制首先点击文件右侧的“恢复”按钮时弹窗会显示“该操作将丢弃该文件的工作区改动且不可撤销”并要求选择恢复的基准HEAD还是某个具体提交。只有当用户勾选了“我确定要丢弃这个文件的改动”之后按钮才会真正生效。5.3 和 Codex 抢工作区的问题最容易被忽视的坑是面板的写操作和 Codex 的执行可能会冲突。我实测遇到过一个典型案例Codex 刚执行完git add和git reset的一瞬间我这边刚好点了一个“切换分支”结果它后续的命令全部因为“你已经切换分支”而失败。这不是我哪个命令写错了而是“人类和 AI 同在一个仓库里操作”天然就有竞态。解决方案有两个方向在“启用写操作”时面板会检测 Codex 进程是否在运行。如果检测到它的 PID 还活着就弹一个提示让你确认“我知道 Codex 还在运行”。写操作执行前面板自动做一次git status --porcelain快照执行后再次拉取状态并对比如果发现“执行前后仓库状态发生意外变化”立刻用红色警告通知你。这个对比功能在实际使用中救了我好几次。有一次面板显示提交成功但提交的 message 被 Codex 接下来的一个操作自动修正了如果我没有这个对比提醒根本不会注意到。6. 高频报错与排查技巧6.1 常见命令级问题我汇总了几个自己踩过且经常有人问的报错fatal: not a git repository (or any of the parent directories): .git这个几乎都是 cwd 设置错了。Codex 启动时的工作目录可能和你面板的 root 不一致。解决办法面板启动时自动走一遍“向上查找.git目录”的逻辑找到正确的仓库根目录而不是死板地使用用户填写的路径。中文文件名乱码看状态表时文件路径变成一堆转义序列\346\265...。解决办法是给 Git 传-c core.quotepathfalse并且保证 Node 环境变量里的编码是 UTF-8。git diff输出超大有些文件几千行改动接口响应慢到超时。我的做法是给 diff API 加行数上限默认返回前 300 行 尾部 20 行并且在前端显示“已截断”提示。git stash后找不到改动面板里 stash 的恢复入口藏太深是个体验问题。我在时间线里增加了对stash操作的解析点击对应记录可以直接看到 stash 内容并提供stash pop按钮。6.2 渲染和解析层面的坑分支树里 merge commit 的父顺序Git 的%P输出父提交时第一个父提交是“当前分支继续向前的那个”第二个父提交是“被并入的那个”。一开始我画图时把两个父提交直接并列导致线条交叉很难看。后来改成“第一个父提交继承当前 lane第二个父提交开新 lane”视觉才正常。--all和远程分支的重名问题如果本地分支main和远程分支origin/main同时存在%D会列出两个引用但我解析时用空格切分引号经常把origin/main拆成两半。解决办法是统一用--decorate-refs-exclude过滤或者干脆把远程分支单独用一个前缀展示。SVG 渲染的行列定位绘制横向连接线时如果两个节点相距很多层SVG 的贝塞尔曲线容易超出画布。我的简单方案是只画“相邻两层”的连线跨层的线用虚线在侧边绕一下虽然不够完美但可读性已经足够。Windows 路径转义在 Windows 上spawn传递包含反斜杠的路径参数时偶尔会被吞掉。解决办法是尽量用正斜杠替换并且不要依赖cwd里的反斜杠如果必须用做好路径规范化。6.3 问题速查表其实排查 Git 面板问题最好的方法永远是回到“直接在终端里执行同样的 git 命令”这一步。面板只是包了一层壳大量问题的源头在 Git 环境本身。症状可能原因解决办法分支树显示不全--all范围过大限制最大条数或改用当前分支范围文件名全是转义码core.quotepath未关闭传-c core.quotepathfalse点击提交历史无反应前端解析%D时引号处理失败用--decorateshort并统一处理空格分隔写操作执行后状态变化不对面板和 Codex 竞态操作前后做快照对比并告警中文提交信息乱码stdout 解码不是 UTF-8强制 UTF-8 解码并设置环境变量git clean误删文件危险操作没有二次确认隐藏危险按钮 输入确认字符串最后的几条经验这个面板我从写完到真正顺畅使用大概迭代了两周。最大的教训是工具的价值不取决于功能多而取决于你是否信任它。你信任一个面板才会在 Codex 跑长任务时放心离开回来看一眼时间线就知道一切正常。要做到这种信任必须让“只读状态”永远准确“写操作”永远可控。如果你也想动手做一个我建议按这样的顺序来先把/api/status、/api/log、/api/branches三个接口做出来前端只做表格和树状渲染跑通了再往上加写操作。写操作从“恢复文件”和“切换分支”开始这是风险最低、收益最高的两个按钮。至于 stash、clean、reset 这些等你真的遇到需求再去加也不迟。另外这个面板本质上是一个通用工具它不绑定 Codex。你可以把它接到任何需要长时间占用 Git 仓库的自动化流程上比如 CI 流水线、自动化测试脚本、甚至你自己写的一个批量迁移工具。接入方式也很简单——只需把 cwd 指向对应仓库开一个端口让那个工具在跑任务之前把工作区状态“拍一张照片”传到面板展示就行。最后再分享一个小技巧面板端口不要固定写 3000 或者 8080而是启动时随机分配一个可用端口然后自动打开浏览器。这样你不会因为端口占用而烦心也不会在同时开多个仓库时搞混。这个小细节是我自己用了三天之后才加上的加完之后体验立刻不一样了。