清理我的Git状态

恢复代码仓库，避免问题扩大。

核心规则

1. 先做快照。不要“随便尝试”。
2. 在强制操作之前，优先使用非破坏性修复。
3. 将.git/视为生产数据，直到备份完成。
4. 在手动编辑.git/HEAD之前，先使用git symbolic-ref。
5. 每次修复后，在继续之前运行验证。

快速工作流程

1. 收集诊断信息：

bash scripts/snapshot_git_state.sh .

2. 根据症状使用references/symptom-map.md进行路由。
3. 生成非破坏性命令计划：

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/<名称>下特定的过时文件夹，然后重新运行修剪命令。

操作手册 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：缺失或损坏的引用

症状：

• 未知的修订版本、不是有效的对象名称，或无法锁定引用.

步骤：

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：

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