safe-git-ops

安全 Git 操作

帮助用户执行常见的 Git 操作，避免混淆沙盒故障、仓库状态问题和真正的内容冲突。

技能目录结构

<installed-skill-dir>/
├── SKILL.md
├── scripts/
│   └── project-push
└── references/
    ├── failure-modes.md
    ├── commit-paths.md
    └── worktrees.md

渐进式加载

• 始终阅读 references/failure-modes.md
• 当用户要求提交、推送、加快收尾，或选择验证／重新安装范围时，阅读 references/commit-paths.md
• 当仓库使用 git worktree、.git 指向另一个目录，或用户提到多个工作树时，阅读 references/worktrees.md

核心行为

• 将预检与会改变状态的 Git 命令分开
• 区分沙盒或权限故障与合并冲突
• 将工作树视为特殊情况，因为它们可能会在可见工作目录之外写入共享 Git 元数据
• 对 reset --hard、checkout --、删除分支或丢弃储藏等破坏性操作，先征求用户同意
• 优先使用非交互式 Git 命令
• 使用分级风险的提交路径，避免低风险的文本／文档更改承担完整验证、完整冒烟测试或完整技能重新安装的成本
• 对常规网络推送，优先使用稳定的封装命令 project-push <repo> <remote> <branch>，而不是临时拼凑命令，例如 cd repo && git push、bash -lc "git push"，或在相对路径和绝对路径的 git -C 形式之间切换。
• 对非简单的收尾任务，如果 sidecar-task-runner 可以只读运行并减少主 Agent 的决策时间，则使用它进行提交前分类
• 如果沙盒阻止写操作，应明确说明并请求提升权限，而不是猜测是否存在冲突
• 网络 Git 操作失败时，在要求用户更改凭据前，先区分网络／沙盒访问问题、身份验证问题、Git 远程配置问题或仓库问题
• 倾向于尽早启用：如果用户含糊地报告 Git 故障，应假定本技能负责诊断，并在任何会改变状态的命令运行前介入

触发启发规则

出现以下任一情况时，立即使用本技能：

• 用户要求运行 git cherry-pick、merge、rebase、commit、stash、switch、checkout、branch 或 worktree
• 用户说“Git 失败了”“合并出问题了”“cherry-pick 被阻止了”“有冲突”或“这个仓库为什么会变成这样”
• Agent 看到涉及以下内容的错误文本：
  • CONFLICT
  • index.lock
  • operation not permitted
  • permission denied
  • Could not resolve host
  • Could not read from remote repository
  • Connection timed out
  • Network is unreachable
  • .git/worktrees/
  • ORIG_HEAD
  • CHERRY_PICK_HEAD
  • branch is already checked out

如果任务显然涉及大量 Git 操作，不要等到写入失败后才加载本技能。

避免误诊

除非 Git 已证实，否则绝不要说以下任何内容：

• 错误实际上与权限有关时，却说“这是合并冲突”
• 可能涉及公共 Git 目录时，却说“这只是当前工作树本地的问题”
• 真正的问题是脏状态、分离的 HEAD 或正在进行的操作时，却说“Git 坏了”
• 首次失败是沙盒限制导致的网络或 DNS 故障时，却说“你的令牌／SSH 密钥／远程仓库配置有问题”
• 不说明阻碍属于冲突、仓库状态还是沙盒问题，就说“直接重试”

第 1 步——了解仓库

执行任何重要的 Git 操作前，检查仓库结构：

git rev-parse --show-toplevel
git rev-parse --git-dir
git branch --show-current
git status --short

如果用户提到工作树，或者 .git 是文件而不是目录，也要检查：

git worktree list
git rev-parse --git-common-dir

总结：

• 仓库根目录
• 当前分支
• 工作树是否有未提交的更改
• 是否为工作树
• 共享 Git 元数据是否位于当前目录之外

步骤 2 — 分类请求的操作

将请求归为以下类别之一：

• inspect：状态、日志、差异、分支列表、远程仓库、工作树布局
• network_inspect：fetch、pull、push 的试运行检查、ls-remote、子模块更新，或任何会连接 Git 远程仓库的 Git 操作
• safe_write：add、commit、cherry-pick、merge、rebase、stash、创建分支、创建工作树
• destructive_write：reset、覆盖本地更改的 checkout、clean、删除分支、删除 stash、强制推送

对于 inspect，如果沙盒规则允许，直接运行命令。

对于 network_inspect，除非已获准使用网络，否则应预期沙盒运行环境会阻止 DNS 查询或出站连接。

对于 safe_write，先执行预检。对于 commit/push 收尾操作，使用 references/commit-paths.md 将更改归类为 Fast Path、Skill Path、Code Path 或 Risk Path，然后运行与该路径匹配的最小验证集。

对于 destructive_write，执行前必须获得用户明确确认。

步骤 3 — 执行任何会更改状态的 Git 命令前进行预检

在执行 safe_write 或 destructive_write 前，收集足够的上下文，以避免处理失败时草率应对：

git status --short
git branch --show-current
git rev-parse --short HEAD

对于常规 commit/push 收尾操作，除非适用 Risk Path，否则不要进行全面检查。Fast Path 收尾操作只需在 commit 前运行 git status --short、git diff --check、明确指定文件的 git add <files>，以及 git diff --cached --stat。

对于 cherry-pick、merge 或 rebase，还应先检查目标 commit 或分支：

git log --oneline --decorate -n 5
git show --stat --summary <target>

对于工作树，检查共享元数据的位置：

git rev-parse --git-common-dir

如果该命令很可能会写入沙盒可写根目录之外的共享 Git 元数据，请在运行前告知用户，并准备好请求提升权限。

如果用户明确要求执行限定于工作树的写操作，例如 cherry-pick、merge 或 commit，请在运行前明确说明，工作树可能需要写入公共 git 目录，而不只是可见的工作树路径。

步骤 4 — 正确执行操作并解读失败

Git 写操作失败时，先对失败进行分类，再告知用户发生了什么。

请遵循 references/failure-modes.md 中的指导。总体规则如下：

• 如果 Git 报告 CONFLICT、冲突标记，或要求解决文件问题，则属于代码冲突
• 如果 Git 报告 operation not permitted、permission denied、无法创建锁文件，或无法更新 refs 或工作树元数据，则属于沙盒或权限问题
• 如果 Git 在执行 fetch、pull、push、ls-remote 或子模块操作期间报告 DNS 故障、API/主机连接失败、超时或网络不可达，则属于网络/沙盒访问问题，需在获得网络权限后重试
• 如果 Git 报告工作区状态不干净、未跟踪文件被覆盖、detached HEAD 不匹配，或缺少 commit，则属于仓库状态问题

除非 Git 确实报告了冲突，否则不要告诉用户“存在冲突”。

如果 Git 因 DNS/网络/沙盒限制而始终未能连接到主机，不要告诉用户“身份验证失败”“SSH 密钥错误”或“远程仓库不存在”。

步骤 5 — 当沙箱限制才是真正的问题时，妥善升级权限

如果重要的写入命令因沙箱限制而失败：

1. 说明这是环境问题，而非代码冲突
2. 指明被阻止的操作
3. 如果已知，说明可能的写入目标，例如：
   • .git/index.lock
   • .git/worktrees/...
   • 公共 git 目录下的共享 refs
4. 请求提升权限，并重新运行同一命令

可以这样表述：

此 git cherry-pick 失败看起来是沙箱写入限制所致，而非合并冲突。Git 需要更新共享的工作树元数据，因此我应该提升权限后重新运行该命令。

如果重要的网络 Git 命令因 DNS、API 或主机连接受阻而失败：

1. 说明首次失败是网络／沙箱访问问题，尚不能证明是 Git 身份验证或远程配置故障
2. 指明命令，例如 git fetch、git push 或 git ls-remote
3. 请求网络权限，并重新运行同一命令
4. 只有在启用网络后重新运行，才能将错误归类为凭据、权限、仓库缺失、分支或服务器端错误

可以这样表述：

此 git ls-remote 失败时并未连接到 GitHub；看起来是沙箱网络访问受限，而非仓库不存在或 SSH 密钥无效。我应该先获得网络权限并重新运行，然后再诊断凭据问题。

提交后的常规推送请使用稳定的包装器形式：

project-push <repo> <remote> <branch>

使用预检时找到的分支。除非包装器不可用，否则不要将同一推送改写为 cd <repo> && git push、git -C <repo> push 或由 shell 包装的变体。

步骤 6 — 工作树专属规则

当仓库使用工作树时：

• 假定 commit、cherry-pick、merge、rebase 等类似命令可能会在当前工作树目录之外写入数据
• 尽早检查 git worktree list 和 git rev-parse --git-common-dir
• 在确认 Git 尝试写入的位置之前，不要声称故障“仅限于此工作树”
• 删除分支或重置时要格外小心，因为其他工作树可能正在使用同一分支

详细处理规则请参阅 references/worktrees.md。

步骤 7 — 准确报告结果

完成后，明确报告以下结果之一：

• 成功
• 发生冲突，需要手动解决
• 沙箱或权限限制
• 网络／沙箱限制
• 仓库状态问题，需要用户选择

针对每种情况，告诉用户下一步该做什么，不要只给出含糊的 Git 输出。

正确示例：

git cherry-pick <commit> 尚未进入合并冲突解决阶段。Git 无法在公共 git 目录下写入共享工作树元数据，因此这是沙箱问题。下一步是提升权限后重新运行同一命令。

错误示例：

cherry-pick 失败了，可能是冲突

推荐的输出格式

当用户询问“发生了什么？”或“为什么失败？”时，请按以下结构报告：

Operation: <git command>
Classification: success | content conflict | sandbox restriction | network/sandbox restriction | repository state problem
Evidence: <the key git message or state observation>
Why it happened: <short explanation>
Next step: <single concrete next action>

明确写出分类结论。这是避免草率诊断 Git 问题的关键保障。

此技能应能妥善处理的命令

• git status、log、diff、show、branch、remote
• git fetch、pull、push、ls-remote
• git add、commit、stash
• git cherry-pick
• git merge
• git rebase
• git switch、checkout、checkout -b
• git worktree list、git worktree add

需要格外谨慎的命令

• git reset --hard
• git checkout -- <path>
• git clean -fd
• git branch -D
• git stash drop 或 clear
• git push --force

未经用户明确批准，不要运行这些命令。