git-operations

name	git-operations
description	BoardGame Git 操作入口。用于提交、推送、同步主分支、pre-push 阻塞、PR、worktree、fork、merge 等协作场景。

Git 操作 Skill

本 skill 只负责一件事：告诉 AI 在本项目里怎么做 Git 操作。 根 AGENTS.md 只保留通用红线和高频入口；复杂 Git 协作细则以下文为准。

0. 什么时候用

命中以下任一场景就用本 skill：

• 用户要 git status / diff / commit / push
• 用户要“检查一下没问题就提交”“看下再推”
• 用户要同步 main、处理 pre-push 阻塞、排查远端失败
• 用户要处理 PR、merge、fork、worktree、跨仓库写回

1. 日常高频操作

1.1 看改动

• 先看 git status --short --branch
• 再按需要看 git diff --stat、关键文件 git diff
• 不要先跑一堆和当前动作无关的 Git 命令

1.2 提交

• 默认只提交本轮明确范围内的改动
• 用户说 都提交 / 全修改 / 所有修改 / 全部改动 时，统一解释为：审查并处理整个当前工作区的改动集合，再执行 git add/commit
• 这里的“整个当前工作区”默认只包含当前仓库内的：已暂存、未暂存、未跟踪 文件；不包含 ignored 文件
• 若用户口令是“看下没问题就把全修改提交 / 检查后把所有修改都提交”，则检查范围也必须覆盖上述整个集合，不能只看 index 或只看 unstaged
• git commit -m 默认用中文，且要点明业务对象
• 不要用“修复问题”“更新代码”这种空标题
• 当提交里包含用户明确点名的 bug / 修复 / 反馈项时，提交消息必须点名这些事项，不能只写“顺手补的门禁修复”或泛化桶名
• 大提交或多模块提交默认用中文多行消息；不要把 10+ 文件、多个游戏、UI + 领域逻辑 + 测试压成一行空泛标题
• 提交消息必须来自真实 diff 审查；先识别主要功能、行为变化、测试和文档改动，再写标题与 body
• 首次提交消息必须尽量一次性覆盖主要改动面；不得只写最后一次小修、门禁输出或抽象桶名

1.2.1 提交消息结构

• 小提交：标题直接写清业务对象 + 动作，例如 补齐 SmashUp 非核心控件切换文案
• 大提交：第一行概括 2-4 个主要改动面，body 用列表覆盖：
  • 用户明确提到的修复项
  • 核心模块 / 文件簇
  • 行为变化或新增测试 / evidence
• 如果一次提交同时包含“用户已有修复 + 本轮补丁 + hook 门禁修正”，消息里至少要让人看出前两者都在；不能只剩最后那个 hook 修正
• 如果提交标题或 body 没有覆盖实际主要功能增量，视为审查没有看全；先回到 diff 审查并重写消息

1.2.2 提交前自检

• 先问一句：如果用户现在追问“那我的修复为什么没写进提交消息”，这条消息能否直接自证？
• 如果答案是否定的，先重写提交消息，再执行 git commit
• 若第一行容纳不下全部关键项，就保留高层概括，并在 body 单列用户点名事项；不要为了保持单行而吞掉关键修复名
• 提交前必须把 git diff --stat 与关键 diff 映射到提交消息；主要文件簇映射不上就继续审查，不要提交
• 涉及 i18n 或可见 UI 文案时，默认在首次提交前跑 npm run i18n:check 或等价最小检查

1.3 推送

• 默认先推已提交内容，不要把未提交工作区和 push 混在一起
• 用户目标涉及远端 push 时，默认先执行 git fetch --prune origin 刷新远端引用；fetch 只更新远端跟踪信息，不改工作区，不等于授权 pull、merge、rebase 或 stash
• fetch 后若分支只是 ahead N，继续直接推送当前提交
• fetch 后若分支出现 behind 或 ahead + behind，不得自动 pull、merge、rebase 或 stash；先说明远端已有新提交，并按本项目 AI 协作常态，默认建议进入可审计的 merge 同步流程
• 若用户当轮已经明确要求“处理远端更新后继续推 / 同步后再推 / 合并远端再推 / 改到能 push”，可把远端分叉视为同一 push 目标内的同步 blocker，先锁定合并方向、工作区归属和双边内容范围，再按 merge 规则推进
• push 失败先分辨：是网络/协议、hook 门禁、还是代码测试失败
• 任何门禁、guard、预算或 hook 的绕过（例如 --no-verify、BG_BYPASS_GLOBAL_HEAVY_BUDGET=1、guard bypass env）都不是默认动作；除非用户当轮明确允许，否则只能等门禁通过，或停止并汇报 blocker

2. 本项目默认口径

2.1 远端协议

• 默认优先 SSH
• 只要 SSH 已验证可用，fetch/pull/push/ls-remote 都优先走 SSH
• 不要在已知 HTTPS 443 不稳定时反复重试 HTTPS

2.2 当前仓库

• origin 默认应指向主仓库 SSH：
  • [e-mail]:zhuanggenhua/BoardGame.git
• 若发现 origin 还是 HTTPS，且用户目标涉及远端操作，可直接切为 SSH

2.3 工作区

• 默认假设工作区可能是脏的
• 不得擅自 git stash、git restore、git checkout --、git clean
• 看见陌生改动，先判断是否影响当前任务；不影响就绕开，不要顺手清

2.4 共享脏工作区与并发 AI

• 默认假设当前工作区里长期存在用户和其他 AI 的并发改动；dirty 不是异常，而是常态背景
• 看到 ahead/behind 加脏工作区时，先分清用户当前目标是 push、同步主线、整理工作区 还是 修 bug；不要把它们自动合并成“先保护现场”
• ahead N, behind M 且工作区已脏时，默认只允许做审查、汇报 blocker、或继续当前目标内的最小编辑；不得擅自用 stash、pull --rebase、rebase、reset、restore 去“整理现场”
• 用户只说“push/提交”时，先处理已提交内容与明确范围内的改动；若 fetch 后发现 behind 或 ahead + behind，可以建议合并远端更新，但不要因为 behind 或工作区脏就私自切到同步主线、变基、stash、建临时保护分支
• 用户说“看着删 / 该删的删 / 整理改动”时，默认含义仍是先看内容再判断，不是任何形式的回滚、覆盖或清空授权

3. 检查与门禁

3.1 “检查一下再提交/推”

• 默认先做静态代码审查：阅读 git diff --stat、关键 git diff 和潜在风险点
• “检查没问题”“看下再提交”默认不等于主动跑测试
• “检查没问题”“看下没问题就提交/push”也默认不等于授权修复：这是一条 review-then-git 动作路径，不是 fix-then-git 路径
• 如果静态审查、快检查、hook 或生成脚本暴露 bug、缺 key、类型错误、测试失败、新生成代码差异、范围外改动或其它需要编辑代码的问题，必须停止在 review 结论：列出 finding / blocker、影响文件、建议最小修法；不得自行修复、补齐、改测试、改文档或继续追加提交
• 若用户已对同一目标给出持续授权，则按根 AGENTS.md 的“持续授权在同一目标内持续生效”执行；Git 流程不额外发明自己的特例
• 如果用户在同一目标内明确要求“提交 push / 改到能 push / 继续”，随后静态检查或门禁只暴露机械性 i18n 问题，例如缺少 titleKey 对应语言包、缺少 labelKey、中英文 key 需要一一补齐，默认直接按现有中文业务名和英文卡名补最小词条并继续；不得停下来问“要不要补 key”。只有文案本身涉及产品口径、命名争议或多种翻译方案时才停下。
• 如果用户已经明确说明这是业务规则/能力文本变化，或要求“看能力描述后直接更新测试”，而失败项只是旧测试断言与当前能力文本不一致，默认直接按能力文本更新测试期望并继续提交/push；不得把这类旧断言失败包装成业务逻辑 blocker。若能力文本本身冲突、缺失或会改变真实玩法实现，才停下说明需要业务裁定。
• 只有用户当轮明确说“修复后提交”“补齐门禁”“继续改到能 push”“自动修掉再推”等修复授权时，才允许从 review-then-git 切换到 fix-then-git
• 只有当用户明确要求、仓库现有 hook 阻塞、或静态审查已发现需要机器确认的具体风险时，才追加手工检查命令
• 若仓库已有 pre-commit / pre-push 等价门禁，默认依赖 hook，不重复手工预跑同类检查

3.2 pre-push 失败

先分类，再处理：

1. 网络/协议失败
   • HTTPS 失败且 SSH 可用：直接切 SSH
2. hook/质量门禁失败
   • 按失败项归类并停止，不要笼统说“push 失败”
   • 若失败项的唯一解是“绕过门禁/绕过预算/绕过 guard”，而用户没有当轮明确授权，则必须停下，不能自行加 bypass 环境变量或参数继续推
   • ESLint warning-only 的新口径（强制）：若最近一次 pre-push 已经跑到 ESLint warning delta，且同时满足 ① TypeScript / 构建 / 测试未失败；② ESLint 为 0 errors；③ 阻塞项只是“新增 warning”；④ 这些 warning 没有指向真实运行时崩溃、安全泄漏、数据丢失或用户点名的玩法症状，则默认把它归类为“质量门禁阻塞”，不得把它包装成“影响游玩”或“玩法 bug 已发现”。用户当轮明确说“这个不影响游玩不用管 / 按这个口径 / 以我的口径为真相 / 无校验 push / 跳过 warning 门禁”时，视为只针对本次 warning-only pre-push 阻塞的明确放行授权，可在汇报清楚剩余 warning 与风险后继续推送。
   • warning-only 放行边界（强制）：上述放行不适用于 ESLint error、typecheck 失败、测试失败、构建失败、密钥/安全问题、真实业务链路失败、生成文件带出的未审 diff、或需要用户裁定产品/规则/交互语义的问题。命中这些情况时仍必须修到门禁自然通过，或再次取得用户明确绕过授权。
   • 若用户目标只是“检查后提交并 push / 看下没问题就推 / 提交 push”，失败项即使明显来自当前提交改动（如缺失 i18n key、lint/typecheck/build 门禁、当前 diff 触发的测试），也只能汇报为 review finding / blocker；不得默认继续补齐、改代码、改测试、改文档或追加提交
   • 若当前对话已存在持续授权，则按根 AGENTS.md 的同一目标/同一边界口径判断是否可直接修；这里不再重复枚举“简单 blocker”特例
   • 只有用户当轮已经明确授权“修复后提交/push”“补齐门禁”“继续改到能 push”，才允许按失败项做最小修复并重新提交/再次 push
   • 不需要人工决策的门禁项默认直接修（强制）：若当前对话已存在持续授权，且失败项属于同一目标、同一语义边界内的机械性修补，例如补 i18n key、补缺失文案映射、修 lint/typecheck 小口径、补构建脚本要求的静态字段、修 hook/格式化自动暴露的确定性错误，这类问题默认直接处理并继续 commit/push，不需要再停下来问用户“要不要修”“汉化缺失要不要补”。
   • 这里的“最小修复”指最小必要影响范围，不是低质量、偷懒、止血或绕过门禁。修法仍必须按商业级交付口径完成：定位直接原因，选择能长期成立的正式实现，补齐必要的类型、文案、测试或文档证据，并让现有门禁自然通过。
   • 禁止把“最小修复”做成吞异常、跳过任务、删除断言、降低覆盖、硬编码绕过、只改测试不改真实逻辑、只压日志不处理真实失败、或其它不能解释原始失败的临时补丁。若唯一可行方案只是临时保护，必须明确标注为止血，并说明根因缺口，不能把它包装成已修复。
   • 上条仅在以下同时满足时成立：① 不需要用户拍板产品语义、交互口径、业务取舍或文案内容方向；② 不涉及删除/回滚他人改动；③ 不跨出当前任务文件边界附近太远；④ 修法具有单一明显最小解，而不是多方案分歧。
   • 只有当门禁问题开始触及业务真相、命名口径、规则裁定、交互改版、跨模块扩散或并发改动归属不清时，才重新停下汇报；不要把纯机械门禁修补伪装成人工决策问题。
   • 如果 hook、格式化脚本、生成脚本或门禁修复在提交/推送过程中改出了同一目标、同一影响边界内的新工作区 diff，默认视为本次 git 目标的延续产物：直接审查这些新增 diff，按最小修法继续修复、补提并重试；不需要为了“出现了新 diff”单独停下汇报或等待人工确认
   • 上条仅适用于以下同时满足的情况：① 新 diff 明显由本次 commit/push 链路、hook、格式化、生成、测试门禁或为通过该门禁所做的最小修补产生；② 仍落在同一任务语义与同一文件边界附近；③ 不涉及删除/回滚他人改动、不需要创建/切换分支、不需要扩大到新的业务目标
   • 遇到以下情况才重新停下：① 新 diff 明显跨出当前目标范围；② 需要在多种实质性方案间做选择；③ 怀疑有并发他人改动且无法归属；④ 需要破坏性清理、回滚或更高影响动作
   • 继续推进时，仍要保持可审计：最终提交消息必须覆盖这些 hook/门禁引出的补丁；若提交过程中因此形成追加提交，不要假装它们不存在
3. 门禁脚本自身锁冲突
   • 先确认是陈旧 runtime / stale lock / 预算冷却，还是实际 E2E 失败
   • 若当前目标只是推送当前工作树里的已提交内容，默认只在当前工作树内核对锁冲突证据；不得为了“解锁 / 降载 / 看看谁占着”就擅自读取、终止、清理或修改其他 worktree 的进程、文件或测试现场
   • 只有用户明确点名那个其他 worktree，或明确授权跨 worktree 排障/清理时，才允许扩展到别的 worktree
4. 真实测试失败
   • 按失败用例定位，不能把它说成“只是网络问题”

3.3 命令层 guard

• 规范只能约束 AI；要拦命令本身，必须依赖仓库可控入口
• 本仓库现在提供两层 guard：
  • simple-git-hooks 的 pre-rebase：原生硬拦 git rebase
  • scripts/infra/git-command-guard.mjs：仓库内 wrapper，可拦 stash / restore / clean / rebase / pull --rebase / reset / revert / switch / checkout / 受控 branch/worktree
• git stash / restore / clean 没有 Git 原生 hook，无法只靠 .git/hooks 全局硬拦；要拦这几类命令，必须让当前 shell 先走 wrapper
• PowerShell 当前会话可通过以下方式启用项目 guard：

. .\scripts\infra\enable-boardgame-git-guard.ps1

• 启用后，当前 PowerShell 会话里、位于本仓库路径下的 git 命令会先经过 git-command-guard
• 如果用户当轮已明确授权危险 Git 动作，必须显式写出绕过痕迹，而不是静默执行：

$env:BOARDGAME_GIT_GUARD_BYPASS='1'
git rebase ...

• 这层 guard 的目标不是“替代判断”，而是把最容易误伤工作区的命令先硬停下来，逼迫执行者回到用户授权与 skill 口径

4. 低频复杂协作

4.1 分支 / worktree

• 未获用户明确许可，不擅自创建、切换、删除分支或 worktree
• 但若用户已明确进入 PR 修复/合并流，且隔离现场明显更安全，可按根规范使用隔离 worktree
• 当仓库里存在多个 worktree，且当前任务明显对应某条 feature/worktree 任务线时，不得把“当前 shell 正站在根目录 / main”当成默认正确实施位置
• 开始任何会改代码、跑页面、出截图、跑专项测试或准备 merge 的动作前，必须先核对：哪个 worktree 在承载当前任务、哪些候选 worktree 已有相关脏改、哪个运行页/端口属于哪棵树
• 如果两个或以上候选 worktree 都与当前任务直接相关，且没有证据唯一锁定应该落在哪棵树，必须停止并向用户确认；不得先在其中任意一棵树试改，更不得两边各改一份
• 若某个专项 worktree 已存在与当前游戏/模块直接相关的未提交修改，默认优先把它视为实施候选；除非用户明确要求改别处，或证据证明那棵树只是历史残留，否则不得直接绕开它在 main / 根目录实施
• 若某个专项 worktree 已承载该任务线的最新分支、计划/进度文档、专项 evidence、运行页面或持续中的实现修改，则默认把它视为唯一实现真相源；根目录误改或其他 worktree 的同类差异只能作为待吸收输入，不得再当成与它并列的实现现场
• 已并回 main 的专项 worktree 默认降级（强制）：若某专项 worktree 的提交头已经被 main 包含（例如 worktree HEAD 是 main 的祖先），且 main 还继续前进，则这棵树默认不再是“当前实现真相源”；后续新工作默认回仓库根目录 / main 进行，不再沿用该专项树当实施现场
• 删专项树前必须同时满足“已并回 + 工作树干净”（强制）：只有当 ① 该 worktree 的提交历史已经并回 main；② 该 worktree 没有未提交改动、未跟踪文件或其他独有现场内容 时，才允许把它当作历史残留直接删除。只满足“提交已合并”但 worktree 仍然是脏的，不能直接删；必须先判断这些脏改是应吸收到 main、单独归档，还是明确放弃
• 合并后默认收口顺序：确认“专项树提交已并回 main”后，默认顺序固定为：① 先核对该 worktree 是否仍有独有未提交内容；② 若没有，则回 main 继续实施，并在用户已授权时删除该 worktree；③ 若还有独有脏改，则先对这些脏改做内容裁定，不得一边继续在 main 开新实现、一边把脏专项树继续当半真相源
• 在决定“直接 merge main 进专项 worktree / 直接把专项 worktree merge 回 main / 先提交根目录脏改再统一合并”之前，必须先做双边内容比对，而不是只看冲突文件名
• 内容比对至少要回答：两边各自改了哪些现实含义、哪些是一边独有、哪些必须双保留、哪些只是规范/计划文档变更、哪些是正式实现；没有这份内容判断前，只能停在“潜在冲突待裁定”，不得直接给 merge 路径
• 若已确认根目录 / main 是误改现场，而专项 worktree 才是正确落点，默认收口顺序固定为：先回专项 worktree 读真相，再在专项 worktree 吸收或重做误改中仍有价值的部分，待专项 worktree 成为唯一实现真相源后，再考虑合并回 main；不得把误改现场反向升级成主现场

4.2 fork / 主仓

• 默认优先主仓协作，不默认 fork
• 只有主仓不可写、需要账号隔离、或用户明确要求时才走 fork

4.3 PR 写回 / merge

• 用户说“合并/收口/同步回去/准备并回 main/重新合并”时，默认先做内容裁定与吸收准备；这不等于已经授权执行 git merge、pull、IDE 冲突合并，或在目标侧手工重做一版实现
• 必须先锁定合并方向（强制）：把 main 合进专项线、把专项线回 main、把 A 分支同步到 B 分支 是三种不同动作，不能按“都叫合并”混成一件事。用户如果只说“把 main 合进来”，默认只授权 main -> 当前专项线 的同步动作，不等于已经授权 当前专项线 -> main 的正式回主线
• 处理同步 blocker 时不得自动升级目标（强制）：当当前目标只是“吸收 main / 处理 merge blocker / 让专项线继续吃到主线最新内容”时，只允许做两类动作：① 证明哪些改动真的是当前同步动作的 blocker；② 为继续这次同步动作，按最小范围收口 blocker。不得借处理 blocker 之名，自动扩成“整条专项线正式回主线”“顺手做最终收口”“顺手清理整批任务线”
• 合并是 Git/内容归并动作，不是实现动作：它只能整合双边现有正文、已确认要保留的片段和明确放弃的差异；若已经开始“按自己理解重写一版 UI/逻辑/测试来代替双边吸收”，就不再属于 merge，必须停下并按“新实施”重新锁定真相源、实施落点和验收口径
• 只有在以下同时成立时，才允许实际执行 merge 命令：① 用户当轮明确要求现在执行合并；② 已锁定具体双方（哪棵 worktree / 哪个分支并到哪边）；③ 已完成双边内容级比对，知道哪些吸收、哪些放弃、哪些双保留；④ 当前工作区没有未归属脏改会被误吞
• 如果用户只是在问“怎么收口 / 哪边更适合当正式版 / 能不能都保留 / 冲突怎么处理”，默认交付物应是裁定结论、吸收顺序和风险说明，而不是直接动手 merge
• 可写 PR：默认先本地修，再推回，再 review / merge
• 不可写 PR：再走 fallback，不要假装能推回 head
• 当 merge origin/main 被 Your local changes would be overwritten by merge 拦住时，先区分：
  • 用户未授权并入当前未提交改动：停下汇报具体文件，不得擅自 stash
  • 用户已明确授权“当前这批没问题可一起提交/并入提交”：允许先审查这批未提交 diff，按当前目标补一次提交，再重新执行 merge
• 这种“先补提交再 merge”只适用于：
  • 未提交改动仍属于当前目标或用户明确接受的同批改动
  • 不需要回滚他人改动
  • 不需要 stash、rebase、reset、restore
• 如果未提交改动明显跨出当前目标，或无法判断归属，仍然必须停下，不得借“可以一起提交”把整片脏工作区直接吞进来
• merge 前若命中项目要求，先读：
  • docs/git-merge-checklist.md

5. 不该做的事

• 不要把 Git 规则写成一整段大而全提示词塞回根 AGENTS.md
• 不要把“日常 commit/push”与“复杂 PR/fork/worktree 协作”混成一层
• 不要把网络失败、hook 失败、测试失败混成一句“push 没成功”
• 不要在用户没授权时做破坏性清理

6. 根文件与本 skill 的分工

根 AGENTS.md 应只保留：

• 提交 / push 的高频入口规则
• 不可越过的红线
• 本 skill 的入口指引

本 skill 承担：

• Git 日常用法模板
• 远端协议口径
• 共享脏工作区 / 并发 AI 下的 Git 边界
• 项目级 Git command guard 的能力边界与使用方法
• pre-push 失败分类
• PR / merge / fork / worktree / 协作细则