Git Plain Speak（大白话搞 Git）

Overview

把用户说的"人话"翻译成正确的 git 命令，在当前工作目录的项目里执行。覆盖四类高频操作：备份、查询、回滚、分支。所有命令执行前先用一句话说清"要干啥、影响什么"，危险操作（改写历史、丢数据、强制推送）必须显式确认后才执行。

全程使用中文回复。git 命令本身保持英文。

执行原则

1. 先检测，再动手。任何操作前，先运行 scripts/git_status_summary.py 拿到当前项目状态（是否 git 仓库、当前分支、未提交改动、与远程的领先/落后关系、最近提交）。
2. 说人话，不甩命令。执行前用一句大白话告诉用户将做什么；执行后用大白话汇报结果，避免堆砌 raw git 输出。
3. 危险操作必须确认。回滚、强制推送、删除分支、丢弃改动等不可逆操作，先列出「将执行的命令 + 影响范围 + 是否可撤销」，等用户明确同意后才执行。详见 references/dangerous-ops.md。
4. 不猜远程。没有配置 remote 时，引导用户配置或创建 GitHub 仓库，不要擅自 push。
5. 当前目录即项目。所有 git 命令默认作用于当前工作目录的仓库，不要跨目录操作。

触发与意图识别

当用户用大白话表达 git 意图时（所有触发词均含 "git" 关键词），按下表归类到五大模块。完整关键词映射见 references/plain-to-git-mapping.md。

识别到模块后，进入对应章节执行。无法确定意图时，用一句话向用户确认，不要猜。

模块零：GitHub 配置（首次使用必经）

当用户说"git备份到 GitHub""git推到 GitHub""git建仓库"等，且检测到当前仓库无远程或未登录 GitHub 时，进入本模块。

完整流程见 references/github-setup.md，核心顺序：

1. 检测 gh CLI 是否已装 → 运行 scripts/gh_check.py。
   • 未装 → 按系统自动安装（Windows 优先 choco/scoop/winget，macOS 用 brew，Linux 用 apt/dnf）。安装细节见 github-setup.md 步骤1。
   • 已装 → 继续。
2. 检测登录状态 → gh auth status。
   • 未登录 → 执行 gh auth login --hostname github.com --git-protocol https --web，引导用户用浏览器设备码方式授权（最安全，不存密码不存 token）。引导话术见 github-setup.md 步骤2。
   • 已登录 → 继续。
3. 创建或关联仓库：
   • 建新仓库 → 问公开/私有 → gh repo create <名字> --public/--private --source=. --remote=origin --push（一键建+关联+推送）。
   • 关联已有 → 要仓库地址 → git remote add origin <地址> → git push -u origin <分支>。
4. 汇报仓库地址和推送结果。

⚠️ 沙箱环境：如果 gh 命令在执行沙箱中运行，登录配置的写入可能被拦截（表现为授权成功但 gh auth status 仍显示未登录）。解决方案：每个 gh/git push 命令前先设 export GH_CONFIG_DIR="<项目路径>/.gh_config"，让 gh 把登录态存在项目内。详细排查与解决见 references/github-setup.md「沙箱/权限问题处理」节。务必在 .gitignore 中排除 .gh_config/。

Fallback：若 gh 因网络装不上，临时改用 PAT 方案（建临时 token → API 建库 → push → 立即换干净 remote URL）。详见 github-setup.md 末尾。skill 主路径仍是 gh。

本模块完成后，仓库已有远程且已登录，后续"git备份"等操作直接走模块一。

模块一：备份（commit + push）

目标：把本地改动存档并同步到远程 GitHub。

流程

1. 运行 scripts/git_status_summary.py，读取未提交改动清单。
2. 若无改动 → 告诉用户"没有需要备份的改动"，并提示是否只想 push 已有提交。
3. 若有改动：
   • 用 git diff --stat 和 git diff --cached --stat 看改动概览。
   • 自动生成 commit 消息：根据改动文件和 diff 摘要，生成简洁中文 commit 消息（动词开头，如"修复登录页样式""新增导出功能"）。把拟定的消息告诉用户，允许用户直接采用或修改。
   • 默认 git add -A 暂存全部改动；若用户只指定了部分文件，则只 add 指定文件。
   • 执行 git commit -m "<消息>"。
4. push 阶段：
   • 若有远程且当前分支有上游 → git push。
   • 若有远程但无上游 → git push -u origin <当前分支>。
   • 若无远程 → 进入「特殊情况：无远程」。
5. 汇报：提交了什么、推送到哪、远程仓库地址。

注意

• commit 消息不要写"update""wip"这种废话，要反映实际改动。
• 用户说"先别推，只提交" → 跳过 push。
• 用户说"强制推上去" → 进入危险操作确认流程（push --force-with-lease）。

拉取/下载（pull + clone）

目标：从远程 GitHub 获取代码。分两种场景。

场景 A：同步远程更新（git pull）

用户说"git拉下来""git同步远程""git更新一下"，表示当前已有项目，想拉取远程最新代码。

1. 运行 scripts/git_status_summary.py，确认当前分支、工作区是否干净、与远程的 ahead/behind 关系。
2. 若 behind 为 0 → 告诉用户"已经是最新了，不需要拉"。
3. 若工作区有未提交改动 → 先处理改动，提示三选一：
   • 先 git stash 暂存 → 拉取 → git stash pop 恢复
   • 先 commit → 再 pull
   • 用户自己搞，暂不拉
4. 默认用 git pull --rebase（保持线性历史，推荐），若用户明确要 merge commit 则用 git pull --no-rebase。
5. 若有冲突 → 进入「特殊情况：合并冲突」处理。
6. 汇报：拉了多少提交、当前与远程是否同步。

场景 B：首次下载项目（git clone）

用户说"git下载仓库""git下载项目 xx""git clone""git拉个项目"，表示想从 GitHub 下载一个新项目到本地。

1. 确认仓库来源：
   • 用户给了完整地址（https://github.com/用户/仓库）→ 直接用。
   • 用户只说了仓库名（如"下载 git-plain-speak"）→ 问 GitHub 用户名或用 gh repo clone 自动定位。
   • 用户说"下载我的 xx 项目" → 用自己的 GitHub 用户名拼接。
2. 执行下载：
   • 用 gh：gh repo clone 用户名/仓库名 <本地目录>（自动处理认证，私有仓库也能下）。
   • 用 git：git clone https://github.com/用户名/仓库名.git <本地目录>（公开仓库不需要认证）。
3. 下载完成后 cd 进入项目目录，运行 scripts/git_status_summary.py 展示项目状态。
4. 若无远程 → 首次下载已自动有远程，无需额外配置。

注意

• git clone 不存在危险操作，不需要确认。
• git pull 如果用户当前分支没配上游（首次 push 前），提示用户先设上游：git branch --set-upstream-to=origin/<分支>。
• 下载后若仓库是私有的且未登录 gh，先走模块零登录。

模块二：查询（status / log / diff / blame）

目标：让用户看懂项目当前状态和历史。只读操作，无风险。

2.1 查改动

• git status（人类可读的改动清单）
• git diff（未暂存的具体改动）
• git diff --cached（已暂存的具体改动）
• 汇报时按"新增/修改/删除"分类说，不要直接贴一大坨 diff。

2.2 查历史

• git log --oneline -n 20（最近 20 条提交，简洁模式）
• 用户问"某文件谁改的" → git log --oneline -- <文件> 或 git blame <文件>。
• 用户问"某次提交干了啥" → git show ，用大白话总结改动。
• 用户问"两个分支/版本差多少" → git log A..B --oneline + git diff --stat A B。

2.3 查远程关系

• git status 里的 ahead/behind 信息（status_summary 脚本已汇总）。
• 用户问"远程有啥新东西" → git fetch 后 git log HEAD..origin/<分支> --oneline。

模块三：回滚（reset / revert / restore）

⚠️ 高危模块。所有操作走危险操作确认流程。

先弄清用户想回滚什么，分三种场景：

3.1 丢弃未提交的改动（还没 commit）

• 用户说"我改的不要了 / 恢复文件原样"：
  • 未暂存改动 → git restore <文件> 或 git restore .（全部）。
  • 已暂存改动 → 先 git restore --staged <文件> 取消暂存，再 restore。
• git restore . / git checkout . / git clean -fd 属危险操作，必须确认。

3.2 撤销已提交但未 push 的 commit

• 用户说"撤回刚才的提交，但保留改动" → git reset --soft HEAD~1。
• 用户说"撤回刚才的提交，改动放回工作区" → git reset --mixed HEAD~1（默认）。
• 用户说"彻底干掉刚才的提交，改动也不要了" → git reset --hard HEAD~1（高危，必须确认）。
• 回退 N 步 → HEAD~N。

3.3 撤销已 push 的 commit

• 优先用 git revert ：生成一个反向提交，不改写历史，安全。
• 只有在明确需要改写历史（如私有分支、协作方很少）且用户坚持时，才用 git push --force-with-lease。必须走危险确认。
• 永远不要在不确认的情况下 force push 到 main/master。

回滚后用大白话说清：现在 HEAD 在哪、改动去哪了（保留/丢弃）、远程是否已同步。

模块四：分支（branch / switch / merge）

4.1 查询分支

• git branch（本地）、git branch -a（含远程）。
• 汇报当前所在分支，用星号或文字标明。

4.2 创建 + 切换分支

• 用户说"新建分支 xx" → git switch -c <分支名>（或 git checkout -b）。
• 分支名建议：用英文 kebab-case，如 feat/export、fix/login-bug。用户给中文名时，帮忙转成规范英文并告知。

4.3 切换分支

• git switch <分支>。
• 若工作区有未提交改动会阻挡切换 → 提示用户三选一：commit / stash / 丢弃，不要擅自决定。

4.4 合并分支

• 用户说"把 xx 合到当前" → git merge <分支>。
• 用户说"把当前合到 xx" → 先切到目标分支再 merge，或用 git merge 的反向，确认意图后执行。
• 出现冲突 → 进入「特殊情况：合并冲突」。

4.5 删除分支

• git branch -d <分支>（安全删，未合并会拒绝）。
• git branch -D <分支>（强制删，高危，必须确认）。
• 删除远程分支 git push origin --delete <分支>（高危，必须确认）。

特殊情况处理

当前目录不是 git 仓库

git_status_summary.py 会返回 NOT_A_REPO。此时：

1. 告诉用户当前目录还没初始化 git。
2. 问是否要 git init，以及是否要关联到 GitHub 远程。
3. 用户同意后执行 git init，再按「无远程」流程引导配置远程。

无远程（未配置 remote）

直接进入「模块零：GitHub 配置」流程——优先用 gh CLI 自动建库+关联+推送，避免让用户手动去 GitHub 网页操作。完整步骤见 references/github-setup.md。

合并冲突

1. git status 列出冲突文件。
2. 打开冲突文件，定位 <<<<<<< / ======= / >>>>>>> 标记。
3. 用大白话解释冲突点，给出建议保留方案；不要擅自改用户的代码逻辑，只解决标记冲突。
4. 解决后 git add <文件> → git commit（merge）或 git rebase --continue（rebase）。
5. 用户说"放弃合并" → git merge --abort 或 git rebase --abort。

push 被拒（non-fast-forward）

1. 说明远程有本地没有的提交。
2. 建议先 git pull --rebase（保持线性历史），或 git pull（产生 merge commit）。
3. 不要直接 force push，除非用户明确要求并走危险确认。

危险操作确认流程

对所有不可逆操作统一执行：

1. 列出将执行的命令（完整命令文本）。
2. 说明影响范围：会丢哪些数据、改写哪些历史、影响哪些远程分支。
3. 说明可逆性：能否撤销、撤销难度。
4. 等待用户明确同意（"确认"/"继续"/"执行"等肯定词）才执行；模糊回答或沉默则不执行并再次询问。
5. 执行后立即汇报结果。

危险操作完整清单见 references/dangerous-ops.md。

Resources

scripts/

• git_status_summary.py — 扫描当前项目 git 状态，输出结构化摘要（是否仓库、当前分支、改动文件、ahead/behind、最近 5 条提交、远程地址）。任何操作前先运行它，拿到状态再决定后续动作。可用 python scripts/git_status_summary.py 执行；也可直接读取其输出。
• gh_check.py — 检测 gh CLI 是否已安装、版本、登录状态。退出码：0=已装已登录，1=已装未登录，2=未安装，3=版本过旧。模块零前置检测脚本，用户说"git备份到 GitHub"且无远程时先跑它。

references/

按需加载，不必全部读入：

• plain-to-git-mapping.md — 大白话关键词到 git 命令的完整映射表。意图不明确或需要更多关键词样例时加载。
• dangerous-ops.md — 危险操作完整清单、风险分级、确认话术模板。执行任何回滚/强制操作前加载。
• github-setup.md — GitHub 配置全流程：gh CLI 安装（Win/Mac/Linux）、浏览器设备码登录、一键建库+关联+推送、网络不通时的 PAT fallback。用户首次备份到 GitHub 或检测到无远程时加载。
• common-scenarios.md — 常见场景速查（首次备份、查看某文件历史、回退到指定提交、创建功能分支并开发完合并等完整流程示例）。遇到典型场景时可参考。

assets/

无。本 skill 不需要模板或静态资源文件。