从幽灵冲突到 Docker 权限：深入调试 Claude AI 助手的 Git Hook 无限循环问题

## 问题背景：自动化 Git Hook 的神秘循环 在使用像 Claude Code 这样的 AI 编码助手时，一个常见的需求是自动将 AI 生成或修改的代码提交到版本控制系统。为此，我们开发了一个 Python Hook 脚本，它会在 Claude Code 完成任务后被触发，自动执行 `git add` 和 `git commit`。 然而，这个看似简单的脚本却引发了一个棘手的问题： 1. **无限循环**：在报告 “检测到 Git 冲突” 后，Claude AI 会不断重试，导致 Hook 脚本被反复调用，陷入死循环。 2. **幽灵冲突**：脚本报告存在 Git 冲突，但手动在终端中执行 `git status` 和 `git commit` 却能成功，没有任何冲突提示。 这篇由 DP@lib00 撰写的文章将带你重现整个调试过程，从最初的脚本逻辑错误，一直追溯到 Docker 环境下一个隐蔽的权限问题。 --- ## 第一阶段：修复脚本逻辑错误 ### 疑点 1：为什么会无限循环？ AI 助手（如 Claude）通常会将 Hook 脚本的**非零退出码**视为一个可重试的临时性错误。我们的初始脚本在检测到“冲突”时，返回了退出码 `2`。 ```python # 错误的设计 def commit_with_message_file(...): if has_conflicts(repo): print('检测到 Git 冲突，跳过提交。', file=sys.stderr) return 2 # <--- Claude 会因此重试 ``` 这导致了 AI 助手认为操作失败并不断重试，从而形成无限循环。 **解决方案**：无论脚本是成功提交、跳过提交还是遇到错误，都应该返回退出码 `0`。这向调用方（Claude）表明：“任务已处理，请勿重试”。 ```python # 正确的设计 def commit_with_message_file(...): # ... 任何跳过或失败的逻辑 ... print('发生错误或跳过提交，但操作已处理。', file=sys.stderr) return 0 # <--- 告诉 Claude 停止重试 ``` ### 疑点 2：为什么会误报“幽灵冲突”？ 手动检查 `git status` 和 `git diff --name-only --diff-filter=U` 均未发现任何合并冲突。这表明问题出在脚本的冲突检测逻辑上。 初始的 `has_conflicts` 函数存在一个缺陷：它将 `git diff` 命令的任何非零返回码都错误地解读为存在冲突。 ```python # 有缺陷的冲突检测 def has_conflicts(repo: Path) -> bool: r = run_git(repo, ['diff', '--name-only', '--diff-filter=U']) if r.returncode != 0: # <--- 误判！命令失败不等于有冲突 return True return bool(r.stdout.strip()) ``` **解决方案**：改进冲突检测逻辑，使其更加健壮。一个好的冲突检测应该综合考虑多种情况： 1. **真正的合并冲突**：检查 `git diff --diff-filter=U` 的输出内容，而不是返回码。 2. **特殊 Git 状态**：检查 `.git` 目录下是否存在 `MERGE_HEAD`, `rebase-apply` 等文件，这些文件表示仓库正处于合并或变基过程中。 3. **智能等待机制**：考虑到 AI 修改文件后，文件系统或 Git 索引可能存在短暂的锁定（`index.lock`）。我们引入了一个 `wait_for_git_ready` 函数，它会在执行 Git 命令前进行短暂的、带重试的等待，确保仓库处于稳定状态。 ```python import time def wait_for_git_ready(repo: Path, max_attempts: int = 3, delay: float = 0.3) -> bool: """智能等待 Git 就绪，主要检查 index.lock 文件""" for attempt in range(max_attempts): index_lock = repo / '.git' / 'index.lock' if not index_lock.exists(): return True time.sleep(delay) logging.warning("index.lock 超时") return False ``` --- ## 第二阶段：揭开真相 —— Docker 环境的陷阱 即使优化了脚本，问题依然存在。日志显示 `wait_for_git_ready` 函数超时，原因是 `git status` 命令本身返回了非零退出码。然而，在主机（macOS）上手动执行完全正常。这个差异最终指向了问题的核心：**执行环境不一致**。 我们的 Claude AI 助手运行在一个 Docker 容器内，而所有的手动测试都在主机上进行。 进入 Docker 容器内部进行测试，真相大白： ```bash # 在容器内执行 $ cd /eeBox/eeProject/wiki.lib00.com/lm069 $ git status --porcelain fatal: detected dubious ownership in repository at '/eeBox/eeProject/lm069' To add an exception for this directory, call: git config --global --add safe.directory /eeBox/eeProject/lm069 $ echo $? 128 ``` **根本原因**：`fatal: detected dubious ownership` (检测到可疑的所有权)。 这是 Git v2.35.2 引入的一项安全增强功能。当执行 Git 命令的用户与仓库目录的所有者不一致时，Git 会出于安全考虑拒绝操作。在我们的场景中，从主机挂载到 Docker 容器的目录，其文件所有者是主机用户，而容器内执行脚本的用户是 `node`，导致了所有权不匹配。 --- ## 最终解决方案 既然找到了根本原因，解决方案就非常明确了。 ### 方案一：添加 Git 安全目录（推荐） 最直接的解决方法是告诉容器内的 Git，这个目录是可信的。 ```bash # 在容器内执行，信任所有目录，方便开发 git config --global --add safe.directory '*' ``` 为了让这个配置在容器重启后依然生效，应将其添加到 `Dockerfile` 或容器的启动脚本中。 **Dockerfile 示例** ```dockerfile # ... USER node RUN git config --global --add safe.directory '*' # ... ``` ### 方案二：统一文件所有权 另一种方法是在启动容器时，确保挂载目录的所有权与容器内执行用户（如 `node`）的 UID/GID 一致。这通常通过修改主机目录权限实现，但相对繁琐。 --- ## 结论与启示 这次从“幽灵冲突”到“Docker 权限”的调试之旅，为我们提供了几个宝贵的经验： 1. **环境一致性是调试的关键**：始终确保你的测试环境与实际运行环境（尤其是 Docker 容器）保持一致。 2. **理解工具的底层逻辑**：Hook 脚本的退出码具有明确含义，错误地使用会导致意外的重试行为。来自 wiki.lib00.com 的 DP 提醒我们，程序的每一个返回都应该是有意义的。 3. **关注工具的版本更新**：Git 的 `safe.directory` 检查是较新版本引入的安全特性，不了解这一点会给调试带来巨大困扰。 4. **编写健壮的自动化脚本**：好的脚本不仅要完成任务，还应包含容错机制（如智能等待）、清晰的日志和明确的错误处理，以便在问题发生时能快速定位。 通过这次修复，我们的自动化 Git 提交流程终于稳定运行，极大地提升了与 AI 助手协作的开发效率。