Git 仓库整理器
将每一项结论建立在一个全新的 Git 快照之上。将引用、已检出的目录、未提交的文件和托管的远程仓库视为独立的状态层。
选择操作模式
推断请求授权的最窄模式：
- 分析：检查并报告，不更改引用、索引或工作树内容。当当前远程真相很重要时，使用
git ls-remote；不要仅仅为了分析而执行 fetch、merge、pull、commit、rebase、delete、push、创建跟踪分支或切换工作树。 - 刷新：获取远程跟踪引用，然后报告。不要仅仅因为获取了引用就集成一个分支。
- 提交：仅在命名的工作树中组织和提交更改。
- 整合：仅通过一个干净的集成工作树合并、变基或挑选指定的分支。
- 清理：仅移除在决策矩阵下证明安全的分支或工作树。
- 同步：在刷新并重新检查后，仅推送或快进指定的引用。
如果“整理”或“同步”没有明确授权变更，则先进行清单盘点并呈现确切的操作提议。在删除远程引用、强制推送、重写共享历史、丢弃更改或强制移除工作树之前，需要明确的确认。
构建当前快照
- 定位真正的仓库和公共 Git 目录。切勿假定提示工作目录是仓库根目录。
- 在操作前阅读诸如
AGENTS.md之类的项目指令。 - 在分析模式下，验证实时的远程提示，而不更新远程跟踪引用：
git ls-remote --symref --heads REMOTE
明确说明本地远程跟踪引用保持缓存且未更改。在刷新模式，或在明确请求的远程变更之前，运行：
git fetch --all --prune --no-tags
默认使用 --no-tags。获取分支和获取标签是分开的操作；切勿自动覆盖冲突的本地标签。
获取仅更新远程跟踪引用。在刷新模式下，在此停止，并将每个本地分支与其远程对应项进行比较，而不集成任一方：
- 永远不要仅仅为了让审计看起来最新而进行合并或拉取。一个本地分支可能合法地领先、落后或分叉；报告该状态。
- 永远不要仅仅为了分析一个脏的工作树而进行提交、暂存、快照、切换、重置或以其他方式触碰它。记录脏状态并将其视为变更阻塞器。
- 远程已被删除（
upstream gone）或从未推送的本地分支将保持仅本地状态；在报告中明确注明。 - 仅在用户明确请求该变更时才进入同步或整合模式。在执行该操作前立即重新运行审计，在拥有该分支的工作树中操作，并应用决策矩阵。
- 运行捆绑的只读审计脚本：
python3 scripts/audit_git_state.py --repo /absolute/path --format markdown
python3 scripts/audit_git_state.py --repo /absolute/path --base main --format json
相对于此技能目录（而非目标仓库）解析脚本。
- 检查每个可能保留、整合或删除的分支的唯一提交和更改过的文件：
git log --left-right --cherry-pick --oneline BASE...BRANCH
git diff --stat BASE...BRANCH
git diff --name-status BASE...BRANCH
在描述分支功能之前，先阅读代表性差异。不要从分支名称推断功能。
- 在清理前分类每个分离的工作树：
git merge-base --is-ancestor HEAD BASE && echo "HEAD already in BASE"
同时针对本地基础和远程基础（例如 main 和 github/main）进行检查。一个干净的分离 HEAD 如果是远程基础的祖先，则已合并——它不需要重新集成，也不需要恢复分支；它很可能是验证脚本的遗留物，可以在确认后安全移除。一个不是祖先的分离 HEAD 可能持有唯一提交；在移除前（即使工作树看起来很干净），在 HEAD 处创建一个恢复分支。在强制移除前，检查未跟踪文件，并将生成的产物（测试输出、构建目录）与手写工作区分开。
-
保持输出与决策成正比。将 JSON 审计和批量引用/工作树/差异列表写入一个临时文件，只读取摘要。仅对整合或删除候选分支进行深度差异分析；不要在大型仓库的上下文中倾倒每个分支的日志和完整差异。
-
在最终报告之前和每次变更之前立即重新运行审计。仓库可能在分析运行时发生变化；在结果中包含快照时间和提示哈希值。还要注意并发活动：自上次快照以来另一个进程创建或删除的引用、工作树或远程分支（例如一个合并候选分支）会改变计划；重新呈现计划，而不是对过时的目标进行操作。
保持状态模型精确
- 仓库的正常检出是主工作树。它出现在
git worktree list中，但不是外部链接的工作树。 - 在另一个路径下检出的分支是外部链接工作树。
- 分离工作树有一个检出的提交但没有分支。将脏的分离工作树视为可恢复的工作，而不是垃圾。始终检查其 HEAD 是否是基础（本地和远程）的祖先：如果是且工作树干净，则它已合并，不需要重新集成；如果不是，其提交在移除后可能变得不可达，需要先创建一个恢复分支。
- 分支引用和工作树是不同对象。移除一个干净的链接工作树不会删除其分支；删除一个分支不能安全地处理一个脏工作树。
- 远程 HEAD 是一个符号默认分支指针，不是另一个远程分支。
- 远程跟踪引用是对远程状态的本地观察。获取它不同于拉取或合并它。
- 除非用户要求本地跟踪分支，否则不要为每个远程分支创建本地分支。
向用户解释状态时，保持这些事实清晰：
- 一个分支引用一次最多可以被一个工作树检出（0 或 1）；Git 拒绝同一个分支的第二次检出。
- 移除一个工作树仅删除其目录和注册信息。分支引用和提交保留在共享仓库中；该分支只是变为未检出状态，以后可以再次检出。
- 移除一个工作树只会丢失未提交的工作（暂存、未暂存、未跟踪或冲突的文件）。“干净”意味着丢失风险为零，而不是该分支已合并。
- 分离工作树不占用任何分支。其 HEAD 直接指向一个提交，因此它永远不会导致另一个工作树获得或丢失分支。
- 分支不在主工作树“内部”；未检出的分支作为引用存在，可以随时切换。
明确定义可删除的分支
一个分支只有在其内容完全合并到目标基础分支（通常是 main）时才是明确可删除的：
- 按祖先关系：分支提示是基础的祖先（
git merge-base --is-ancestor BRANCH BASE），因此它有零个仅属于该分支的提交。 - 按补丁等价性：每个仅属于该分支的提交在基础中都有一个补丁 ID 等价的提交（
git cherry BASE BRANCH显示没有+条目），使用git patch-id验证，绝不从提主题推断。
一个具有任何唯一提交或唯一补丁的分支不是明确可删除的，即使其工作看起来冗余、其名称类似于已合并的分支或其提示被标签保留。标签归档的分支只能在明确确认后删除，而不是根据此规则。
一个分支也可能被取代：它实现了某个特性，但该特性已由基础中演变或替代的实现交付。逐提交和逐文件验证基础是否涵盖了相同的意图和文件，并且剩余的仅属于该分支的行是过时的残余而非缺失的功能。被取代的分支不能根据此规则明确删除；用标签归档确切的提示，呈现比较证据，并仅在用户明确确认后删除。
对于远程分支，合并内容的证据必须针对远程基础成立；仅合并到未推送的本地基础中的内容不符合条件。在删除之前，始终应用 references/decision-matrix.md 中的删除关卡。
使用固定的分支矩阵报告
对于每个规范分支名称，报告：
| 字段 | 必需含义 |
|---|---|
| 本地 | refs/heads 是否包含该分支 |
| 远程 | 每个同名的远程引用，不仅仅是上游 |
| 同步 | 相对于其配置的上游是领先/落后还是分叉 |
| 基础关系 | 仅基础有和仅分支有的提交、祖先关系和补丁等价证据 |
| 检出状态 | 未检出、主工作树、外部链接工作树或分离 |
| 工作树状态 | 暂存、未暂存、未跟踪和冲突 |
| 功能 | 由提交和差异证明的特性或修复 |
| 建议 | 保留、提交、整合、归档、删除或调查；仅对内容已完全合并到基础中的明确可删除分支使用“删除” |
分别列出分离的和可删除的工作树，每个都带有其 HEAD 哈希值、该 HEAD 是否是本地和远程基础的祖先、干净/脏状态、未跟踪的产物以及建议（安全移除/先建恢复分支/保留）。最后以按顺序排列的操作结束，分为：现在安全、需要确认、被未提交或唯一工作阻塞。当用户想要仅本地视图，或请求涉及清理/删除决策（整理、删除候选、哪些可以删）时，始终在报告中包含下方的彩色本地仓库图；不要等待明确的“画图”请求。
画出本地的代码库图
在收到明确请求时（例如“画出本地的代码库图”、“本地 Git 状态的图”、“只展示本地分支”或“本地优先视图”），触发画图，并自动将其包含在每个面向清理的报告（整理、删除候选、哪些可以删）中。生成一个本地优先的分支图：
- 在画图前立即重新运行审计；用快照时间和提示哈希值标记图表。
- 范围仅限于本地分支（
refs/heads/*）。不要渲染仅远程的分支。 - 将每个也有同名远程分支的分支标记为也有远程分支；否则标记为无远程分支，区分从未推送和推送后被删除（
upstream gone）。 - 按性质对分支进行分组：长期/主要（保留）、临时性（确认后归档/删除）和有实际工作（保留并决定整合）。
- 为每个分支附加工作树状态：未检出、主工作树或链接工作树（及其路径），以及干净/脏状态。
- 附加清理证据：唯一提交/补丁、上游状态（包括领先/落后）、脏文件和暂存区。
- 如果另一个进程在会话期间创建了合并候选或验证引用，将这些分支放在它们自己的待定组中；报告它们但在外部进程解决之前不要修改它们。
- 在 Worktree 子图中绘制每个分离工作树，即使它没有分支：将其标记为
detached <path> → HEAD <hash>，带有干净/脏状态和祖先判定（✔ HEAD 已在 base 中，已合入或✘ 未合入，需恢复分支）。它没有分支边。 - 渲染一个 mermaid 流程图，每组一个子图，外加一个单独的工作树子图；将每个检出的分支连接到其工作树。
模板：
flowchart TB
subgraph LOCAL["本地分支 refs/heads/*"]
subgraph KEEP["长期/主要 —— 保留"]
A["main（ahead 25 · behind 4）<br/>✔ 也有远程分支<br/>primary worktree · 干净"]
B["dev<br/>✔ 也有远程分支 · 未检出<br/>祖先，已完全合入 main"]
end
subgraph TEMP["临时性 —— 确认后归档/删除"]
C["branch-c（N 个独有提交）<br/>✘ 无远程分支（upstream gone）<br/>linked worktree · 脏"]
end
subgraph WORK["有实际工作 —— 保留并决定是否合入"]
D["branch-d（N 个独有提交）<br/>✘ 无远程分支（从未推送）<br/>linked worktree · 干净"]
end
subgraph PENDING["在途/外部验证 —— 不动"]
E["merge-candidate-x（外部创建）<br/>✔ 也有远程分支 · linked worktree · 干净"]
end
end
subgraph WT["Worktree"]
W1["primary /path/to/repo → main · 干净"]
W2["linked /path/to/wt1 → branch-d · 干净"]
W3["linked /path/to/wt2 → branch-c · 脏"]
W4["linked /path/to/wt3 → merge-candidate-x · 干净"]
W5["detached /path/to/wt4 → HEAD abc1234 · 干净<br/>✔ HEAD 已在 base 中（已合入）"]
W6["detached /path/to/wt5 → HEAD def5678 · 脏<br/>✘ 未合入（需恢复分支）"]
end
A --> W1
B -- "祖先" --> A
D --> W2
C --> W3
E --> W4
style LOCAL fill:#e3f2fd,stroke:#1e88e5
style KEEP fill:#e8f5e9,stroke:#4c8c4c
style TEMP fill:#fff8e1,stroke:#f9a825
style WORK fill:#e8eaf6,stroke:#3949ab
style PENDING fill:#fff3e0,stroke:#fb8c00
style WT fill:#f3e5f5,stroke:#8e24aa
style A fill:#fce4ec,stroke:#d81b60
组织本地提交
仅在拥有更改的工作树内工作。
- 检查暂存、未暂存、未跟踪、忽略、生成、大型和类似秘密的文件。
- 将生成的输出、缓存、截图、本地日志和凭据与产品更改分开。 对于锁定文件，将仅格式的重新序列化（例如 pnpm 版本引号样式更改）与真正的依赖更改分开；在恢复或提交之前通过依赖差异验证。
- 按行为（而非仅按目录）分组提交。当一个文件包含多个关注点时，使用补丁暂存：
git add -p
git diff --cached --check
git diff --cached --stat
git diff --cached
- 在每个逻辑提交之前运行聚焦的验证，在集成之前运行更广泛的验证。
- 使用常规提交消息。切勿在混合或不熟悉的工作树上盲目使用
git add -A。 - 在每次提交后重新检查状态，并准确说明还有哪些未提交。
安全地整合分支
在合并、变基、挑选、删除、移除工作树或类似强制操作之前，阅读 references/decision-matrix.md。
（原文未完，译文亦同）
...
（由于原文被截断，以下内容未翻译。完整的技能应包含决策矩阵和更多细节。）
注意：此技能需要仓库根目录下的 scripts/audit_git_state.py 脚本以及 references/decision-matrix.md 文件。使用前请确保这些文件存在。