名称： 修复 Git 状态
描述： 通过分阶段、低风险的恢复流程，诊断并修复损坏的 Git 状态和工作树元数据。适用于 Git 报告 HEAD 分离或状态矛盾、幽灵工作树锁、孤立工作树条目、引用缺失、全零哈希值，或分支操作失败并出现诸如“已检出”、“未知版本”、“非有效对象名”或“无法锁定引用”等错误的情况。

修复 Git 状态

在不扩大影响范围的前提下恢复仓库。

核心原则

1. 先做快照。切勿“直接尝试”。
2. 优先使用非破坏性修复，再考虑强制操作。
3. 在备份完成前，将 .git/ 目录视为生产数据。
4. 在手动编辑 .git/HEAD 之前，优先使用 git symbolic-ref。
5. 每次修复后，在继续下一步前先进行验证。

快速工作流

1. 捕获诊断信息：
   bash bash scripts/snapshot_git_state.sh .
2. 根据 references/symptom-map.md 中的症状进行路由。
3. 生成非破坏性命令计划：
   bash bash scripts/guided_repair_plan.sh --repo .
4. 应用最匹配的最小化操作手册。
5. 运行 references/recovery-checklist.md 中的验证检查点。
6. 仅在检查点失败时进行升级处理。

如需显式路由：

bash scripts/guided_repair_plan.sh --list
bash scripts/guided_repair_plan.sh --symptom phantom-branch-lock

回归测试框架

在更改脚本逻辑前，先使用可丢弃的模拟测试：

bash scripts/regression_harness.sh

运行单个场景：

bash scripts/regression_harness.sh --scenario orphaned-worktree

操作手册 A：孤立的工作树元数据

症状：
- git worktree list 显示一个不存在的路径。
- 工作树条目包含无效或全零哈希值。

步骤：

git worktree list --porcelain
git worktree prune -v
git worktree list --porcelain

如果仍有残留条目，请备份 .git/ 目录，然后删除 .git/worktrees/<name> 下特定的残留文件夹，并重新运行 prune。

操作手册 B：幽灵分支锁

症状：
- git branch -d 或 git branch -D 失败，提示“已由工作树使用”。
- git worktree list 显示的分支归属信息似乎矛盾。

步骤：

git worktree list --porcelain

找到使用该分支的工作树，在该工作树中切换到另一个分支或分离 HEAD，然后在主仓库中重试分支操作。

操作手册 C：分离或矛盾的 HEAD

症状：
- git status 意外报告 HEAD 处于分离状态。
- git branch --show-current 和 git symbolic-ref -q HEAD 的结果不一致。

步骤：

git symbolic-ref -q HEAD || true
git reflog --date=iso -n 20
git switch <known-good-branch>

如果分支上下文未知，则从当前提交创建一个救援分支：

git switch -c rescue/$(date +%Y%m%d-%H%M%S)

然后在调查后重新连接到目标分支。

操作手册 D：缺失或损坏的引用

症状：
- unknown revision、not a valid object name 或 cannot lock ref。

步骤：

git fetch --all --prune
git show-ref --verify refs/remotes/origin/<branch>
git branch -f <branch> origin/<branch>
git switch <branch>

在强制移动分支指针之前，使用 reflog 恢复仅本地的提交。

最后手段：手动修复 HEAD

仅在对 .git/ 进行备份后使用。

首选方法：

git show-ref --verify refs/heads/<branch>
git symbolic-ref HEAD refs/heads/<branch>

当无法使用 symbolic-ref 时的备选方案：

echo "ref: refs/heads/<branch>" > .git/HEAD

立即运行验证检查点。

验证检查点（必须通过）

运行 references/recovery-checklist.md 中的检查。最低要求：
- git status 正常退出，无致命错误。
- git symbolic-ref -q HEAD 与预期分支匹配。
- git worktree list --porcelain 没有缺失的路径和全零哈希值。
- git fsck --no-reflogs --full 没有新的关键错误。

升级路径

1. 归档 .git：
   bash tar -czf git-metadata-backup-$(date +%Y%m%d-%H%M%S).tar.gz .git
2. 从远程仓库克隆一份新的。
3. 使用 reflog 和 cherry-pick 从旧克隆中恢复未推送的工作。
4. 记录故障模式，并为自动化流程添加防护措施。

自动化钩子

在构建工作树工具（iMi、脚本、机器人）时，强制执行：
- 操作前快照和状态验证
- 操作后验证检查点
- 在 HEAD/引用不一致时强制停止
- 在执行破坏性命令前需要明确的用户确认

资源

• 症状路由：references/symptom-map.md
• 验证清单：references/recovery-checklist.md
• 诊断快照脚本：scripts/snapshot_git_state.sh
• 引导计划生成器：scripts/guided_repair_plan.sh
• 可丢弃回归测试框架：scripts/regression_harness.sh