Git Workflow

Git 全流程工作流

触发场景

• 分支创建、切换、管理
• 合并代码到 main（特别是 Monorepo 仓库）
• 创建、审查、合并 PR
• 解决合并冲突
• Git 操作前的安全检查

1. Git 安全协议

以下操作必须获得用户明确指示才能执行：

安全原则：

• 永远创建新 commit，而非 amend 已有 commit（除非用户明确要求）
• 暂存文件时，优先按文件名 git add <file> 而非 git add .
• 检测到 lock 文件时，先调查持有进程而非直接删除
• 遇到 pre-commit hook 失败时，修复问题后创建新 commit，不跳过 hook

2. 分支管理

创建新分支

# 从最新 main 创建
git checkout main && git pull origin main
git checkout -b <type>/<short-description>

# 命名规范
feat/add-ocr-support
fix/empty-description-retry
docs/update-readme
refactor/sync-logic

分支命名规范

分支名是远端协作和 PR 的公共标识，必须按任务语义命名，不按本地执行来源命名。不要在分支名前加 tmux-、subagent-、team-、agentteam- 等前缀；这些前缀属于本地 worktree 或 session 名称，由 parallel-agent-workflow 管理。

推荐示例：

docs/ch01-agent-intro
research/issue-13-ch08-materials
fix/agent-session-shell

反例：

tmux-ch01
subagent-fix-copy
team-feature-a

分支清理

合并后的分支应及时删除：

# 删除本地分支
git branch -d <branch-name>

# 删除远程分支
git push origin --delete <branch-name>

批量审计：已合并分支清理

仓库累积了一批已合并 PR 后做集中清理时，不要只用 git branch --merged main 判断。

核心陷阱：git branch --merged 只识别"提交可达"，对 squash merge / rebase merge 一律失效——main 上的合并 commit 是新生 SHA，原分支 tip 不在 main 历史里，分支会被误判为未合并。

权威依据：PR 在远端的 state == MERGED。

审计流程

# 1. 快照当前状态
git branch -vv                   # 本地分支 + 跟踪信息
git branch -r                    # 远程分支
git worktree list                # worktree 占用情况

# 2. 列候选（仅作为参考，不能作为删除依据）
git branch --merged main
git branch -r --merged origin/main | grep -v 'origin/main\|origin/HEAD'
git branch --no-merged main
git branch -r --no-merged origin/main | grep -v 'origin/main\|origin/HEAD'

# 3. 关键：用 PR 状态交叉验证（squash/rebase merge 必须）
gh pr list --state merged --search "head:<branch>" \
  --json number,title,mergedAt

# 或批量映射近期 PR ↔ 分支
gh pr list --state all --limit 50 \
  --json number,state,headRefName,mergedAt,closedAt

判定规则

辅助指纹：git rev-list --left-right --count main...origin/<branch> 返回 "ahead N, behind 1" 是 squash-merged 的典型形态（分支自身的 commits 不在 main，main 的 squash commit 不在分支）。它是提示而非证据，仍以 gh pr list 为准。

删除（fail-closed，必须先取得用户确认）

向用户展示候选表后再批量删除：

# 批量删除远程分支
git push origin --delete <b1> <b2> <b3>

# 删除本地分支（先 -d；refuse 后再讨论是否升级到 -D）
git branch -d <branch>

# 清理本地的 stale 远程跟踪 ref
git fetch --prune
# 或 git remote prune origin

红线（fail-closed）

• ❌ 仅凭 `git branch --merged` 删除：在 squash/rebase merge 仓库会漏判，在 merge commit 仓库才完整。
• ❌ 仅凭 ahead/behind 删除：WIP 分支也会"ahead 多个 commit"。
• ❌ 把 `CLOSED` 当 `MERGED`：closed-without-merge 是被废弃，删除前必须问用户。
• ❌ 跳过用户确认直接 `git push origin --delete`：远端删除对协作者可见，难撤销。
• ❌ 用 `git branch -D` 强删本地以"对齐远端"：会丢未推送的 WIP。

Worktree（工作树）

当需要同时在多个分支上工作时，使用 worktree 避免频繁切换分支：

# 创建 worktree（自动创建新分支）
git worktree add ../pm-feature-ocr feat/ocr-support

# 在 worktree 中工作
cd ../pm-feature-ocr
# ... 编辑、提交 ...

# 完成后回到主工作目录
cd -

# 删除 worktree
git worktree remove ../pm-feature-ocr

# 查看所有 worktree
git worktree list

使用场景：

• 一个分支在跑耗时任务（训练/测试），同时需要在另一个分支工作
• 需要对比两个分支的代码
• Code review 时需要拉取 PR 分支到本地测试

注意事项：

• 同一分支不能同时被两个 worktree 检出
• worktree 中的修改是独立的，需要单独 push
• 删除 worktree 前确认已提交或推送改动

3. Monorepo 安全合并

核心规则

禁止 `git merge` 直接合并 feature 分支到 main。 Feature 分支若从旧 commit 创建，直接合并会误删所有不在分支里的文件。

正确做法：目录级 checkout

git checkout main && git pull origin main
git checkout <feature-branch> -- <skill-directory>/
git diff --cached --stat   # 确认只改了目标目录
git commit -m "feat(<skill>): 描述"

多 Skill 合并

涉及多个 Skill 时逐个目录 checkout，每个目录一个提交：

git checkout main && git pull origin main
git checkout <feature-branch> -- skill-a/
git diff --cached --stat
git commit -m "feat(skill-a): 描述"

git checkout <feature-branch> -- skill-b/
git diff --cached --stat
git commit -m "feat(skill-b): 描述"

合并后验证

git diff HEAD~1 --stat    # 确认无误删
ls .gitignore .env 2>/dev/null  # 确认关键文件还在

GitHub PR 合并

若用 GitHub PR 合并 Monorepo 中的某个 Skill 改动：

1. 先 rebase feature 分支到最新 main，确保 base commit 包含所有文件 2. 确认 PR diff 只涉及目标 Skill 目录 3. 使用 squash merge，commit 标题包含模块名和 PR 编号

# rebase feature 分支
git checkout <feature-branch>
git rebase origin/main
git push --force-with-lease  # rebase 后需要 force push

Rebase 冲突时的恢复

git pull --rebase 遇到冲突时，不要盲目接受远程的删除。Monorepo 中远程 PR 误删文件是常见情况。

判断原则： 1. 如果冲突是"远程删除 vs 本地修改"，先确认远程的删除是否是有意为之 2. 如果该 Skill 目录在远程 main 仍存在但被删除，很可能是合并误删，应保留本地版本 3. 如果确认是误删，用 git checkout <本地commit> -- <skill-directory>/ 恢复

恢复流程：

# 1. 先中止 rebase，回到安全状态
git rebase --abort

# 2. 获取 rebase 前的本地提交（通过 reflog）
git reflog | head -10

# 3. 从本地提交恢复被误删的目录
git checkout <本地commit-hash> -- <skill-directory>/

# 4. 单独提交恢复的文件
git diff --cached --stat   # 确认恢复的文件
git commit -m "feat(<skill>): 恢复被误删的文件"
git push origin main

关键：git reflog 保存了所有操作历史，即使 rebase 后本地提交也不会真正丢失。

4. PR 工作流

创建 PR

# 推送分支
git push -u origin <branch-name>

# 创建 PR
gh pr create \
  --title "feat(module): 简短描述" \
  --body "$(cat <<'EOF'
## 摘要
- 关键变更 1
- 关键变更 2

## 测试计划
- [ ] 验证项 1
- [ ] 验证项 2
EOF
)"

PR 正文最低要求

创建或审查 PR 时，正文至少包含：

缺失「摘要」或「测试计划」时，不应 approve；缺失「Agent 归属」时，要求补齐后再合并。

PR 标题格式

<类型>(<模块>): <描述>

与 commit 格式一致，多 Skill 仓库必须带模块名。

审查 PR

# 查看 PR 详情
gh pr view <number>

# 查看 PR 文件变更
gh pr diff <number>

# 提交 review
gh pr review <number> --approve --body "LGTM"
gh pr review <number> --request-changes --body "建议修改..."

合并 PR

合并默认采用 fail-closed 策略。只有在 diff 可读、review 结论明确、CI/checks 明确通过时，才允许自动或半自动合并。

合并前先做最小检查：

gh pr view <number> --json title,state,isDraft,mergeable,reviewDecision,headRefName,baseRefName
gh pr diff <number> --name-only
gh pr checks <number>

判断规则：

• state 不是 OPEN 或 isDraft 为 true：不合并
• mergeable 为 UNKNOWN / CONFLICTING / 空值：不合并，先更新分支或人工检查
• reviewDecision 为 CHANGES_REQUESTED，或应有 review 但没有明确通过：不合并
• gh pr checks 有失败、等待中、未知状态，或无法读取：不合并
• gh pr diff --name-only 显示跨模块污染、误删大量文件、敏感配置文件：不合并

Monorepo PR Diff 检查清单

对 Monorepo 或多 Skill 仓库，合并前必须检查文件范围：

gh pr diff <number> --name-only
gh pr diff <number> --stat

阻断条件：

• PR 声称只改一个模块，但 diff 涉及多个无关目录。
• 出现大量 deleted 或目录整体删除，且 PR 正文没有解释。
• 改动包含 .env、config/secrets.*、credentials.json、私钥或 token 文件。
• lockfile、schema、迁移文件、生成物变化无法对应到 Summary / Test plan。
• README.md、Marketplace 清单、版本号、CHANGELOG 中的版本不一致。

处理方式：要求拆 PR、缩小 diff、补说明或补测试。不要用“看起来问题不大”替代文件级检查。

# Squash merge（推荐）
gh pr merge <number> --squash \
  --subject "feat(module): 描述 (#<number>)" \
  --body "关键变更说明"

# Merge commit
gh pr merge <number> --merge

# Rebase merge
gh pr merge <number> --rebase

重要：通过 API 执行 squash merge 时，commit_title 不会自动追加 (#N)，必须手动写入。

本地拉取 PR 到 main 的提交格式

当用户要求“拉取 PR 到主分支 / 把 PR 拉进 main / 合入这个 PR”时，默认目标是让 main 历史中能直接看出来源 PR。不要用 git pull --ff-only origin pull/<N>/head 作为最终合入方式，因为 fast-forward 会保留 PR 原提交标题，通常不会显示 (#N)。

默认使用 squash commit 方式在 main 上生成一个带 PR 编号的提交：

# 1. 更新 main
git checkout main
git pull --ff-only origin main

# 2. 检查 PR 状态与 diff
gh pr view <N> --json title,state,isDraft,mergeable,reviewDecision,headRefName,baseRefName,url
gh pr diff <N> --name-only
gh pr checks <N>

# 3. 拉取 PR head 并 squash 到暂存区
git fetch origin pull/<N>/head
git merge --squash FETCH_HEAD
git diff --cached --stat

# 4. 使用 PR 标题 + PR 编号提交
git commit -m "<PR 标题> (#<N>)" \
  -m "PR: <PR URL>"

# 5. 推送 main，并关闭原 PR（若 GitHub 未自动标记 merged）
git push origin main
gh pr close <N> --comment "已通过提交 <sha> 合入 main。"

提交标题示例：

docs: 设定章节撰写默认使用 tmux Codex session (#7)
docs(ch01): 从 Chatbot 到 Agent (#10)
research(issue13): ch08 迭代解耦素材包 (#11)

若 PR 标题已经包含 (#<N>)，不要重复追加。若用户明确要求保留 PR 中多个原子 commit，不做 squash；但仍应提醒用户这种方式可能无法在每个 commit 标题中显示 PR 编号。

Fail-Closed 合并门禁

以下任一情况出现时，不得自动合并，必须停下并让人类确认或先修复信号来源：

git-workflow 只维护这些 Git 安全规则；任务状态仍由 cross-agent-collab 和项目任务源管理，本地 Agent 会话由 parallel-agent-workflow 管理。

PR 状态检查

# 查看 CI 状态
gh pr checks <number>

# 查看所有 PR 列表
gh pr list --state open

PR 创建后立即跑 mergeable 检查（强制）

Agent 在 gh pr create 返回 PR URL 后，不要等用户/PM 拍板合并，立即跑一次完整状态检查，捕获 base 落后或 mergeable 冲突：

gh pr view <N> --json state,mergeable,mergeStateStatus,baseRefName,headRefName,files

判读规则：

base 落后 / 冲突处理决策表

当 PR 出现 base 落后、有冲突、或 update branch 失败时，按下表三选一：

禁止 git push --force（不带 --force-with-lease），可能在远端已有他人 push 时覆盖。

PR 创建后：可选文档体检扩展

若当前项目明确配置了 doc-curator subagent 或同等文档体检流程，Agent 在 gh pr create 成功返回 PR URL 后，可以按项目协议触发一次文档体检；未配置时跳过，不影响本 Skill 的 Git 流程。

目的：在 PR 进入 review 前，发现当次变更是否引入文档膨胀、超出归档指针、违反硬性规则；如果有问题，由项目内的文档体检流程在 PR 自身或单独的 maintenance PR 内修正，不让膨胀项进入 main。

调用方式：

# 在 Agent 流程里，PR 创建完成后：
# 1. 调起项目配置的文档体检流程（如存在）
#    - 工作目录：仓库根
#    - 输入：刚 push 的 commit hash（可选）
#    - 期望输出：markdown 报告 + JSON 行

# 2. 解析报告（subagent 内部完成），按规则分支：
#    - 全部 ok → 不动作，继续 review 流程
#    - 软提示 → 把提示写入 PR 描述的"跟进事项"小节，不阻断
#    - 硬性 / 自适应告警 → 走 maintenance-pr.sh：
#      - 工作区干净 → 自动创建维护分支、提一个 maintenance PR
#      - 工作区不干净 → 仅报告，提示用户先清理

# 3. 不阻塞当前 PR：把 maintenance PR 链接追加到当前 PR 描述，让 review 知道"已发现 N 项"

约束：

• 这是 post-action 调起，不是 pre-PR 门禁（避免锁死 PR 创建流程）。
• 文档体检扩展不得改 src/ / src-tauri/ / tests/；改动仅限于 docs/ 维护类动作。
• 文档体检扩展不写 CHANGELOG.md（CHANGELOG 由 release-workflow 或项目发布流程维护）。
• 当前 PR 已 push 但 review 还没合并时，maintenance PR 与当前 PR 并行存在；用户决定合并顺序。

PR 合并后：可选文档体检扩展

若当前项目明确配置了 doc-curator subagent 或同等文档体检流程，Agent 在 gh pr merge 成功（或 squash 推送 main 完成）后，可以按项目协议触发一次完整体检；未配置时跳过。

目的：合并后文档库状态更新（新增 ISS 归档指针、DEC 编号推进、文件行数变化），基线可能漂移；及时发现新合并项是否引入膨胀，必要时自动提 maintenance PR。

调用方式：

# 在 Agent 流程里，PR 合并完成后：
# 1. 调起项目配置的文档体检流程跑体检（如存在）
# 2. 解析报告：
#    - 全部 ok → 不动作，结束
#    - 软提示 → 报告给用户，不自动 PR
#    - 硬性 / 自适应告警 → 走 maintenance-pr.sh：
#      - 工作区干净 → 自动提 maintenance PR（按项目协议）
#      - 工作区不干净 → 仅报告，让用户处理
# 3. 如果报告项触发了 state.json 的基线更新（adaptive 阈值漂移），下一次体检会按新基线判定

约束：

• 与"PR 创建后体检"互补：创建后体检关注"这次提交带来的变化"，合并后体检关注"main 整体健康度"。
• 合并后体检不阻塞合并动作：它发生在合并完成之后，只用于发现后续问题。
• 同一 PR 不重复触发两次（创建 + 合并各一次即可，不在中间 review 轮次再触发）。
• 文档体检扩展不会因为"发现 main 不健康"而尝试 revert 刚合入的 commit；它只做文档级维护，不动代码与决策。

总结：本 Skill 与文档体检扩展的关系

git-workflow 只负责说明可选体检时机；具体体检逻辑、维护动作、PR 生成全部由项目配置的文档体检流程负责。两者通过 subagent 或项目协议解耦：git-workflow 不直接执行文档 trim。

5. 合并冲突解决

检测冲突

# 尝试 merge，查看冲突文件
git merge <branch> --no-commit --no-ff
git diff --name-only --diff-filter=U   # 列出冲突文件

解决原则

1. 理解双方意图：阅读冲突标记两侧的代码，理解各自修改的目的 2. 优先保留双方：如果双方修改不矛盾，尽量都保留 3. 最小修改：只修改冲突区域，不要顺便重构 4. 验证：解决后运行编译/lint/测试

解决流程

# 1. 查看冲突文件列表
git diff --name-only --diff-filter=U

# 2. 逐个文件解决冲突
# 编辑文件，移除 <<<<<<< ======= >>>>>>> 标记

# 3. 标记为已解决
git add <resolved-file>

# 4. 验证
# 运行编译/lint/测试确保无破坏

# 5. 完成合并
git commit

lock 文件冲突

package-lock.json、pnpm-lock.yaml 等锁文件冲突时：

# 删除 lock 文件，重新生成
rm package-lock.json
npm install   # 或 pnpm install
git add package-lock.json

6. 常用 Git 操作速查

撤销与回退

# 撤销工作区修改（未 add）
git restore <file>

# 撤销暂存（已 add，未 commit）
git restore --staged <file>

# 查看某个文件的修改历史
git log --oneline -- <file>

# 查看某次 commit 的内容
git show <commit-hash>

暂存工作

git stash save "描述"
git stash list
git stash pop        # 恢复最近的 stash
git stash pop stash@{2}  # 恢复指定 stash

Cherry-pick

Cherry-pick 用于把某个已存在 commit 回补到当前分支。它容易把无关文件一起带入，必须先确认范围。

安全流程：

# 1. 工作区必须干净
git status --short

# 2. 先看 commit 内容和影响范围
git show --stat --oneline <commit-hash>

# 3. 回补完整 commit，并保留来源记录
git cherry-pick -x <commit-hash>

# 4. 回补后确认范围
git diff HEAD~1 --stat

Monorepo 或只需要部分文件时，不直接 cherry-pick 整个 commit，改用目录级提取：

git checkout <commit-hash> -- <directory>/
git diff --cached --stat
git commit -m "fix(<module>): 回补指定改动"

关键规则：

• 跨分支 backport 默认使用 git cherry-pick -x，保留来源 commit。
• 不直接 cherry-pick merge commit；确需处理时，必须明确父提交并使用 git cherry-pick -m <parent-number> -x <merge-commit>。
• 冲突后若范围变大、意图不清或出现跨模块污染，先 git cherry-pick --abort 回到安全状态。
• 冲突解决后必须重新查看 git diff --stat，确认只包含目标改动。
• 不把 cherry-pick 当作批量同步工具；多个无关 commit 应逐个处理和验证。

查看状态

git status
git log --oneline -20    # 最近 20 条
git diff --stat           # 概览变更文件
git blame <file>          # 查看每行的修改者
git remote prune origin   # 清理已不存在的远端 ref（合并后清理 stale ref）
git push origin --delete <stale-branch>  # 手动删某个远端分支
# 集中审计 squash/rebase merge 后未清理的分支 → 见 §2「批量审计：已合并分支清理」

Tag 管理

git tag v1.0.0
git push origin v1.0.0
git tag -d v1.0.0        # 删除本地 tag
git push origin --delete v1.0.0  # 删除远程 tag

7. Issue 与 PR 命名规范

详细规范见 references/issue-pr-format.md，此处为速查。

本节只管理 GitHub Issue / PR 的命名和合并提交格式。项目常规任务状态、依赖和可领取判断仍由 cross-agent-collab 基于项目任务源维护。

Issue 格式

<类型>: <描述>

关闭时添加状态标记：[done]（自己）、[resolved]（外部）、[wontfix]、[duplicate]。

PR 格式

<类型>(<模块>): <描述>

多 Skill 仓库必须带模块名：

feat(skill-manager): 添加版本检查功能
fix(pdf-processor): 修复大文件解析崩溃
docs(litigation-analysis): 更新模板文档

PR 合并 Commit 格式

<类型>(<模块>): <描述> (#<PR编号>)

通过 API 执行 squash merge 时，commit_title 不会自动追加 (#N)，必须手动写入。

直接解决 Issue 的 Commit 格式

不是每个 Issue 都会通过“分支 + PR”解决。若用户要求直接在当前分支或 main 上修复/关闭某个 Issue，提交标题也必须显式带 Issue 编号，让 git log --oneline 能直接看出来源：

<类型>(<模块>): <描述> (#<Issue编号>)

提交正文用关闭关键字绑定 GitHub Issue：

Closes #<Issue编号>

- 关键变更 1
- 关键变更 2

示例：

docs: 清理过期待定事项 (#1)

Closes #1

- 删除过期决策记录
- 清理不再需要的待定项

如果编号来自项目本地任务源，而不是 GitHub Issue，不要使用 Closes #N 误关 GitHub Issue；改用正文标注：

Refs: project-task Issue #13

8. 提交规范

提交信息使用英文类型前缀 + 中文内容。每个 commit 必须有正文，不能只有标题。

与 git-batch-commit 的职责边界

git-batch-commit 是显式调用的提交快捷按钮，适合用户要求“git 提交 / 批量提交 / 拆分提交 / 整理提交”时，把已暂存变更按类型或模块拆成多个 commit。它可以把 GitHub Issue 写成标题后缀 (#N)，也可以在正文写 Refs #N 或本地任务引用。

git-workflow 是 Git 规则层，负责分支、PR、push、merge、安全门禁和 Issue 关闭语义。凡涉及“合并 PR”“拉 PR 到 main”“推送到远端”“关闭 Issue”“是否使用 Closes #N”，都以本 Skill 为准。

Commit 格式

<类型>: <标题>

- 关键变更 1
- 关键变更 2

支持类型

多 Skill / 多模块规则

多 Skill 仓库必须在标题中写明模块名：

feat(skill-name): 添加批量导出

- 新增导出入口
- 补充参数校验

一次修改涉及多个独立 Skill 或模块时，应拆成多个 commit。每个 commit 只表达一个目的。

参考资源

• references/issue-pr-format.md — Issue 与 PR 命名详细规范
• references/gh-cli-quickref.md — gh CLI 常用命令速查
• TASKS.md — 本 Skill 的维护任务和后续上下文

变更日志

[1.4.1] - 2026-06-06

改进

• 精简 SKILL.md frontmatter description：保留分支管理、Monorepo 安全合并、PR、冲突处理、cherry-pick、安全回退和 branch cleanup 等触发边界，删除具体命令细节和项目特定后置动作。
• 将 doc-curator 文档体检从默认动作调整为可选项目扩展：仅在当前项目明确配置 doc-curator subagent 或同等流程时执行；未配置时跳过，不影响 Git 工作流。

文档完善

• 同步 README 技能列表、最近更新区和 Marketplace 清单中的 git-workflow 描述与版本号。
• 为 skills/git-workflow/DECISIONS.md 和 skills/git-workflow/TASKS.md 增加 .gitignore 例外，使技能级决策与任务记录可随仓库追踪。
• 将最近版本记录中的 Added / Reason 标签调整为中文分类，符合本项目 CHANGELOG 规范。

[1.4.0] - 2026-06-06

新增

• §2 新增「批量审计：已合并分支清理」子节：仓库累积一批已合并 PR 后做集中清理时，权威依据是 gh pr list --state merged，不能仅信 git branch --merged。
• 核心陷阱：git branch --merged 只识别"提交可达"，对 squash merge / rebase merge 一律失效（main 上的合并 commit 是新生 SHA，原分支 tip 不在 main 历史里，分支被误判为未合并）。
• 完整流程：snapshot → 列候选（参考用）→ gh pr list --state merged --search "head:<branch>" 交叉验证 → 候选表展示 → 用户确认 → 批量删除 → git fetch --prune。
• 判定规则表（merge commit / squash-rebase merge / closed 非 merged / 未推送 WIP / stale ref）。
• 辅助指纹：git rev-list --left-right --count main...origin/<branch> 返回 "ahead N, behind 1" 是 squash-merged 的典型形态，仅是提示，仍以 PR 状态为准。
• 红线（fail-closed）：仅凭 git branch --merged 删 / 仅凭 ahead-behind 删 / 把 CLOSED 当 MERGED / 跳过确认就推删除 / -D 强删本地以"对齐远端"。
• description / frontmatter 关键词扩充："已合并分支审计""清理已合并的远程分支""branch cleanup""有没有分支没清理"加入自动触发词。
• §6 速查：git remote prune origin / git push origin --delete 两行下方加导引指针，指向 §2 完整流程。

决策依据

• 来源：Folia 2026-06-06 实操。4 个已 squash-merge 的远程分支（feat/statusbar-copy / fix/about-qr-align / fix/font-preview-live / fix/settings-flash）跑 git branch --merged origin/main 完全没有输出，Agent 第一时间没意识到 squash merge 会让这条检查失效，差点漏判。
• 现状：§2 原「分支清理」只列了 git branch -d / git push origin --delete 两条命令，没说明何时安全何时不安全；§6 速查的 git remote prune origin 注释只解决"远端已删，本地 ref 还在"的反向场景，不覆盖"本地/远端分支还在，但 PR 已合并"。
• 决策：在 §2 新增完整子流程，保留 §6 速查命令但加导引指针，避免速查表膨胀。

[1.3.0] - 2026-06-03

新增

• 「PR 创建后立即跑 mergeable 检查（强制）」：Agent 在 gh pr create 成功后立即跑 gh pr view <N> --json state,mergeable,mergeStateStatus,baseRefName,headRefName,files。mergeable=CONFLICTING 时不要直接 gh pr update-branch，先按决策表选方案。
• 「base 落后 / 冲突处理决策表」：三选一方案：
• 方案 A：冲突仅在 docs 同步文件 → 本地 rebase + 重新编号 + --force-with-lease push
• 方案 B：冲突在共享代码 / 实质代码 → gh pr close --delete-branch + 重建分支 + cherry-pick 实质代码 + 重新写 docs + new PR
• 方案 C：冲突极少 / 1-2 个文件 → GitHub PR UI 手动解决
• 禁止 git push --force（不带 --force-with-lease）
• 「远端 stale ref 清理」：合入后跑 git remote prune origin 清理不存在的远端 ref；手动删某个远端分支用 git push origin --delete <name>。

决策依据

• 来源：FaroPDF v0.1 Wave 1 真实合并 PR #18 / #19 前的根因复盘。
• 主要根因：提 PR 后没立即查 mergeable；本地 main 与 origin/main drift 后 push 报 non-fast-forward；squash merge 引入的"内容相同但 history 不同"被误判为冲突；多个 PR 共享 CHANGELOG 段、DEC 编号无 PM 收口。

[1.2.0] - 2026-06-03

改进

• 描述部分中文化：PR body 模板的 ## Summary / ## Test plan 改为 ## 摘要 / ## 测试计划，PR 正文最低要求表区块改为「摘要」「测试计划」「Agent 归属」「关联任务」「风险」。
• 表格与命令注释中文化：分支命名、Monorepo 合并、PR 合并、PR 状态检查等章节的表格与代码注释改为中文。
• references/issue-pr-format.md 表格和说明中的 Multi-Skill 改为「多 Skill」。

保留

• 英文类型前缀（feat / fix / docs / chore / refactor 等）以兼容 GitHub 标签和 Conventional Commit 工具链。
• 通用 Git 术语（Rebase merge / Squash merge / Merge commit / cherry-pick / worktree / Monorepo / commit / PR / CI / checks / review 等）保留英文，避免生硬翻译。

[1.1.0] - 2026-05-17

新增

• PR 正文最低要求：Summary、Test plan、Agent Attribution、Issue/Task 和风险说明。
• Monorepo PR diff 检查清单：跨目录污染、大量删除、敏感配置、lockfile/schema/版本清单不一致时阻断合并。

改进

• references/gh-cli-quickref.md 增加 gh pr diff --stat 和 PR 模板缺失时的 fail-closed 提醒。

[1.0.0] - 2026-05-17

新增

• 正式迁入 legal-skills/skills/git-workflow/，作为公开技能集合中的 Git 全流程工作流 Skill。
• 补齐正式发布元数据：homepage、MIT 许可证文件、README 技能列表和 Marketplace 条目。

改进

• 按正式发布版本规则将 Skill 版本设为 1.0.0，保留私有开发阶段 0.3.0 及以下历史记录。

[0.3.0] - 2026-05-17

新增

• PR 合并前检查命令序列：读取 PR 状态、draft 状态、mergeable、reviewDecision、diff 文件列表和 checks。
• Cherry-pick 安全流程：工作区干净、先看 commit 范围、默认 -x 保留来源、回补后检查范围。
• Monorepo 场景下的目录级提取规则，避免 cherry-pick 整个 commit 带入无关文件。
• Issue / PR 命名参考增加边界说明：GitHub Issue 不作为项目常规任务状态源，项目任务仍以项目配置的任务源为准。

改进

• references/gh-cli-quickref.md 增加 fail-closed merge gate 速查。
• TASKS.md 同步标记 PR 合并检查和 Cherry-pick 规则已完成。

[0.2.2] - 2026-05-17

新增

• 新增 TASKS.md，补齐 git-workflow 的维护任务上下文。

改进

• SKILL.md 参考资源增加 TASKS.md，方便后续代理查看当前关注和后续优化方向。

[0.2.1] - 2026-05-17

改进

• 将提交规范内置到 SKILL.md，不再在主流程中引用其他 Skill 的提交规范文档。
• 保持职责边界：git-workflow 拥有 Git 流程中需要用到的提交格式要求，批量提交自动化仍由专门的提交工具负责。

[0.2.0] - 2026-05-17

新增

• PR review / merge 默认 fail-closed：diff 不可读、CI/checks 未知、review 结论不明确时不得自动合并。
• 明确 git-workflow 只拥有 Git 安全规则；任务状态归 cross-agent-collab，本地 Agent 会话归 parallel-agent-workflow。

[0.1.0] - 2026-05-15

新增

• 创建 git-workflow skill，覆盖 Git 全流程操作
• Git 安全协议：禁止操作清单和安全原则
• 分支管理：命名规范、创建/清理流程、Worktree 使用
• Monorepo 安全合并：目录级 checkout 规范（从 AGENTS.md v1.7.4 迁移）
• PR 工作流：创建/审查/合并（基于 gh CLI）
• 合并冲突解决：检测、解决原则、lock 文件处理
• Issue 与 PR 命名规范（从 git-batch-commit v1.2.5 迁移）
• 常用 Git 操作速查：撤销、暂存、cherry-pick、tag
• references/gh-cli-quickref.md：gh CLI 命令速查
• references/issue-pr-format.md：Issue 与 PR 命名详细规范

参考

• 整合自 github/awesome-copilot@git-commit（30.8K 安装）
• 整合自 github/awesome-copilot@gh-cli（21.3K 安装）
• 整合自 cursor/plugins@fix-merge-conflicts
• 整合自 cursor/plugins@new-branch-and-pr

gh CLI 常用命令速查

基于 GitHub CLI (gh) 的常用操作参考。

认证

gh auth login          # 交互式登录
gh auth status         # 查看认证状态

Pull Request

创建

gh pr create --title "feat(module): 描述" --body "正文"
gh pr create --draft   # 创建为草稿

查看

gh pr list                           # 列出 open PR
gh pr list --state all               # 所有状态
gh pr list --author @me              # 我创建的
gh pr view <number>                  # 查看详情
gh pr diff <number>                  # 查看 diff
gh pr checks <number>                # 查看 CI 状态

审查

gh pr review <number> --approve --body "通过"
gh pr review <number> --request-changes --body "建议"
gh pr review <number> --comment --body "评论"

合并

合并前先检查 PR 状态、diff 和 checks：

gh pr view <number> --json title,state,isDraft,mergeable,reviewDecision,headRefName,baseRefName
gh pr diff <number> --name-only
gh pr diff <number> --stat
gh pr checks <number>

diff 不可读、checks 未知、review 不明确、PR 是 draft、mergeable 不明确或 diff 超范围时，不要 merge。

PR 正文缺少 Summary、Test plan、Agent Attribution 或 Issue/Task 关联时，先要求补齐。Monorepo PR 如果出现跨目录污染、大量删除、敏感配置或版本清单不一致，不要 merge。

gh pr merge <number> --squash        # Squash merge
gh pr merge <number> --merge         # Merge commit
gh pr merge <number> --rebase        # Rebase merge

其他

gh pr update-branch <number>         # 同步最新 base
gh pr ready <number>                 # 草稿转为正式
gh pr close <number>                 # 关闭 PR
gh pr reopen <number>                # 重新打开

Issue

创建

gh issue create --title "feat: 描述" --body "正文"
gh issue create --label "bug" --assignee @me

查看

gh issue list                         # 列出 open issue
gh issue list --state all             # 所有状态
gh issue list --label "bug"           # 按标签过滤
gh issue view <number>                # 查看详情

管理

gh issue close <number>
gh issue reopen <number>
gh issue edit <number> --title "新标题"
gh issue comment <number> --body "评论"

Repository

gh repo view                          # 查看当前仓库
gh repo clone <owner>/<repo>          # 克隆
gh repo fork <owner>/<repo>           # Fork

Release

gh release create v1.0.0 --title "v1.0.0" --notes "发布说明"
gh release list
gh release download v1.0.0

Actions

gh run list                           # 列出 workflow 运行
gh run view <run-id>                  # 查看运行详情
gh run watch                          # 实时监控
gh workflow list                      # 列出 workflow

搜索

gh search repos "query"               # 搜索仓库
gh search issues "query"              # 搜索 issue
gh search code "query"                # 搜索代码

API

gh api repos/:owner/:repo/pulls/123   # 调用 REST API
gh api graphql -f query='...'         # 调用 GraphQL

Issue 与 PR 命名规范

本规范只管理 GitHub Issue / PR 的标题、关闭标记和合并提交格式，确保 Git 历史可读、可追溯。

边界说明：项目任务状态不由本文档维护。常规任务领取、依赖和状态判断以项目自己的任务源为准；若项目使用 cross-agent-collab，则以其配置解析出的任务源为准。GitHub Issue 只作为远程协作入口或外部问题追踪入口。

Issue 命名格式

格式

<类型>: <描述>

类型前缀

与 Commit 类型保持一致：

状态标记（关闭时添加）

用于标记 GitHub Issue 的关闭结果：

来源区分：

• 自己提出的待办 → 关闭时标记 [done]
• 外部用户提出的 → 关闭时标记 [resolved]、[answered]、[wontfix]、[duplicate]

AI 读取规则

AI 读取 GitHub Issue 标题或关闭评论时：

• 看到 [done] → 已完成，跳过
• 看到 [resolved]/[answered] 等 → 已处理，跳过
• 其他 → 可作为待处理 GitHub 事项，但不得覆盖项目任务源中的状态

示例

feat: github-star-manager 支持自动刷新存量项目元数据
bug: 修复 description 为 null 时不重试的问题
enhancement: skill-manager 添加版本对比功能
docs: 更新 litigation-analysis 使用文档
question: 能接入 qclaw 吗
[done] 已完成上述任务
[resolved] description 为 null 问题已修复
[wontfix] 该建议暂不采纳

PR 命名格式

格式

<类型>(<模块>): <描述>

类型前缀

与 Commit 类型一致：

模块名称（用于多 Skill 仓库）

对于包含多个独立技能的仓库（如 legal-skills），PR 描述中应包含模块名称：

feat(course-generator): 添加多文件支持
fix(piclist-upload): 修复图片上传路径问题
docs(legal-proposal-generator): 更新模板文档

示例

feat(skill-manager): 添加版本检查功能
fix(github-star-manager): 修复 description 为 null 的问题
docs(litigation-analysis): 更新分析报告模板
chore: 更新 GitHub Actions 依赖版本

PR 合并提交格式

使用 squash merge 合并 PR 时，commit 标题必须包含 PR 编号。

格式

<类型>(<模块>): <描述> (#<PR编号>)

规则

1. commit 标题末尾必须带 `(#N)`，其中 N 是 PR 编号 2. 通过 GitHub API 的 merge_pull_request 执行 squash merge 时，自定义 commit_title 不会自动追加编号，必须手动写入 3. commit body 中使用 Closes #<issue编号> 关联相关 Issue

示例

# 正确
feat(funasr-transcribe): 新增 ONNX 优化转录路径 (#16)
fix(skill-manager): 修复符号链接创建位置问题 (#12)
docs: 更新 README (#8)

# 错误 — 缺少 PR 编号
feat(funasr-transcribe): 新增 ONNX 优化转录路径

为什么需要手动加编号？

GitHub 网页端 squash merge 会自动在标题末尾追加 (#N)，但通过 GitHub API 自定义 commit_title 时不会自动追加。因此在 API 合并时必须手动在标题中包含编号，确保 git log 中可直接追溯 PR。

格式对比

规范依据

为什么使用统一格式？

1. 一致性：Issue、PR、Commit 使用相似格式，便于理解和检索 2. 可追溯：通过类型前缀快速识别变更性质 3. AI 可读：AI 能根据 [done] 等标记区分已处理和待处理任务 4. GitHub 集成：GitHub 能自动识别并为 PR 添加标签颜色

成熟项目参考

本项目采用折中方案：Issue 和 PR 都使用类型前缀，但通过状态标记区分处理结果。