AGENT SKILL

maintain-fork-pr-merge

当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge

License 许可
MIT
最近更新
2026-11-13
Stars
★ 21
Forks
4

01 前言 Front Matter

name
maintain-fork-pr-merge
type
Skill
status
stable
metadata
{ "reason": "created from candidate materials", "source": "skill_creator", "summary": "fork PR 冲突时的维护者合入 SOP:merge-tree 探测 + worktree 隔离 + push fork", "revisions": [ "at: \"2026-09-06T11:43:46Z\"", { "at": "2026-09-06T11:45:12Z", "reason": "试用反馈:适用条件补 DRAFT 态 caveat(flag_issue skill-ineffective)", "source": "skill_creator" }, { "at": "2026-09-06T11:46:06Z", "reason": "drift 验证轮", "source": "skill_creator" }, { "at": "2026-09-06T11:50:16Z", "reason": "移除 drift 验证临时段,恢复正式正文", "source": "skill_creator" } ], "source_refs": [ "wiki/scenarios/发布与依赖治理方法.md", "notes/2026-08-26-fork-来源的-pr-与目标分支冲突时的维护者合入流程merge-tree-探测-worktree-push-fork.md" ], "installed_at": "2026-09-06T11:50:20Z", "installed_to": ".codebuddy/skills/maintain-fork-pr-merge/", "installed_hash": "sha256:3aa4f3725ce83a7c9c83531a737828dd674039eb7734fbaf1fc5d23f15db670e" }
generated
{ "at": "2026-09-06T11:43:46Z", "by": "codewiki/5.6.1" }
description
当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge
stale_after
1796428800000

03 SKILL.md 正文

工作场景

维护者合入外部贡献者从 fork 发起的 PR,且 PR 分支与目标分支存在冲突(mergeStateStatus=CONFLICTING/DIRTY)。本仓的典型情境:评审期间 develop 又合入了新提交,导致 fork PR 的改动与主线重叠。

适用条件

  • PR 的 head 分支在贡献者 fork 仓库中(isCrossRepository=true),本地 git fetch <pr-branch> 会 404
  • gh pr view --json mergeable,mergeStateStatus 显示 CONFLICTING 或 DIRTY
  • 注意:此时 CI 检查可能是全绿——CI 通过不等于可合并,以 mergeStateStatus 为准
  • mergeStateStatus=DRAFT(CI 未跑完)时先等结果再探测冲突,勿提前判定

核心 SOP

  1. 探测冲突清单:git merge-tree --write-tree --name-only <base> <head>——无需真实 checkout/merge 即可拿到冲突文件列表
  2. 确认可否代改:gh pr view --json isCrossRepository,headRepository;fork PR 合入前查 gh api repos/<owner>/<repo>/pulls/<n> --jq .maintainer_can_modify——为 false 时只能请作者解决或换合并策略
  3. 隔离解冲突:工作区有未提交改动时,用 git worktree add <tmp> <head> -b <branch> 在独立目录解决冲突,不污染主工作区
  4. 更新 PR 分支:冲突解决后 git push https://github.com/<fork-owner>/<repo>.git <local-branch>:<pr-branch>(maintainer_can_modify=true 时 GitHub 允许维护者推 fork 的 PR head)
  5. 收尾清理:git worktree remove --force + git branch -D,再 gh pr merge --merge

判断逻辑

  • mergeStateStatus=DIRTY ≠ CI 失败:先看冲突字段,不要先怪 CI
  • 主工作区是否常驻未提交改动决定是否必须走 worktree:常驻则必须隔离
  • maintainer_can_modify 是代改的前提闸门:false 时一切 push fork 方案不可行

禁忌与反模式

  • 不要直接在主工作区 checkout PR 分支解冲突(污染未提交改动)
  • 不要因 CI 绿就点 merge(mergeStateStatus 会拒绝,但先探测可省一轮)
  • 不要试图 fetch fork 的分支名到本地远程(不在主仓库,fetch 404 是预期行为)
  • maintainer_can_modify=false 时不要尝试 push fork(无权限,会失败)

04 同仓库更多 Skills

mambo-wang
mambo-wang/CodeWiki-Plus

write-doc-file-content-file-sidechannel

write_doc_file 建档报目标路径已被手写文件占用/路由冲突时——走 content_file 临时文件侧通道:正文写临时文件→删占位文件→write_doc_file(content_file=...) 正式建档→删临时文件

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

windows-python-release

当要手动发布 Python 包(codewiki-plus)到 PyPI 并建 GitHub Release 时——CI 不发布、Windows 控制台为 GBK、可能无 gh CLI、本机网络对 upload.pypi.org 的 Python TLS 握手有干扰——先核对 tag 区间与工作区未提交改动定 bump 级别,再按 8 步主干执行:同步四处版本→bump 提交(只 add 具体文件)→聚焦+ruff+全量闸门→清 dist 构建→PR 合并 main→tag merge commit 建 Release→uv publish(TLS 超时则 curl.exe 直传)→PyPI JSON API 核对

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

windows-dev-env

Windows/PowerShell 下做 git 写操作、跑子进程或批量文件/测试清理时:shell 漂移与中文路径致命令静默失败、无控制台宿主子进程闪窗、GCM 每次弹 OAuth 框、原生 DLL 被锁——须显式复核落盘、subprocess 加 CREATE_NO_WINDOW、gh auth setup-git 持久化凭据,并用 cmd /c 绕 safe-delete 钩子

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

repowiki-conclusion-update

已落库 repowiki 结论发生变化时,按「结论方向 vs 表述」分流:方向变则新写 decision 笔记+reject_note 旧+confirm 并回源 ADR,仅表述/证据变则 edit_doc_file 原地改

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

git-commit-hygiene

在共享 worktree 多会话并行或暂存区有残留时提交代码——用显式 pathspec 只提交自己的文件并排除临时目录,禁止 git add -A 或裸 commit 扫入并行会话的改动

★ 21
mambo-wang
mambo-wang/CodeWiki-Plus

writing-shape

Writing, exploit: shape raw material into an article, paragraph by paragraph.

★ 21