Penpot 的 OpenCode 命令 resolve-git-conflicts：一个可复用的 AI Agent Git 冲突解决工作流设计

Penpot 的 OpenCode 命令 resolve-git-conflicts一个可复用的 AI Agent Git 冲突解决工作流设计【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpotPenpot 仓库在.opencode/commands/目录下维护了一套面向 OpenCode 智能体的命令定义其中 resolve-git-conflicts.md 用五个阶段规定了 AI Agent 处理 Git 冲突的完整规程只读分析、先出方案、批准后再改、暂存校验、汇报即止。读完后你不仅能理解这条命令的每一条规则为何存在还能把Agent 解决冲突、人类收尾 rebase这套职责分离模式搬进自己的 AI 辅助开发流程。命令文件的定位OpenCode 命令体系中的一个专职环节该文件是一个带 YAML frontmatter 的 Markdown 命令定义--- description: Resolve local git conflicts and stage the resolved files with git add — never continues the rebase agent: build ---description用一句话概括了命令的职责边界——解决冲突并用git add暂存结果永远不推进 rebaseagent: build指明该命令由 OpenCode 的 build 型智能体执行即拥有读写代码和运行命令能力的角色而不是只读的分析型角色对照 planner skill 中analysis-only的只读角色定位。description里那句 never continues the rebase 与正文开头you mustneverrungit rebase --continue...、Phase 5 末尾的再次强调形成了三处重复。这种刻意的冗余是 LLM 提示工程的常见手法对影响面最大的安全红线在元数据、开头、结尾各钉一次提高模型遵守的概率。同目录下的两条命令恰好构成一个完整的工作流闭环理解它们的分工有助于把握 resolve-git-conflicts 的边界命令职责是否触碰 Git 历史implement-plan.md建 issue、建issue-NNNN分支、实现计划、经 create-commit skill 提交只做本地 commit不 pushreview.md对计划或代码做审查输出结构化结论完全不修改代码resolve-git-conflicts.md解决 rebase/merge 等产生的本地冲突并暂存只编辑文件 git add不推进、不提交、不 push再结合仓库根目录 AGENTS.md 中的 HARD RULES——Nevergit push, force-push, or modifygit origin、Never amend a commit that has been pushed——可以看出 Penpot 给智能体划定的边界是一致的push、远程、历史改写这些不可逆/共享状态的操作一律留给人类Agent 只在本地工作区内活动。resolve-git-conflicts 的永不git rebase --continue正是这一边界在冲突场景下的具体化。Phase 1 — 只读理解在动任何文件之前弄清冲突全貌原文 Phase 1 的全部要求第 12–18 行运行git status检测当前处于哪种冲突状态rebase、merge、cherry-pick 等并列出所有冲突文件对每一个 unmerged 文件在不修改任何东西的前提下理解现状读取文件内容定位冲突标记、、用git show ours:file和git show theirs:file分别查看两侧在对象库中的原始版本再用git log/git show查看相关提交理解每一侧的意图判断每一侧改了什么、为什么改、二者应当如何合并。这里有两个值得注意的技术点git show ours:file的用法在 rebase 进行中时:ours指 rebase 目标分支被重放提交所基于的那一侧:theirs指正在重放的提交——与 merge 语义恰好相反。要求 Agent 先查看两侧的完整对象版本而不是只看带标记的工作区文件正是为了拿到双方改动的干净基线避免被冲突标记干扰判断。fragile state与仓库工具链的呼应Penpot 的 devenv 工具 manage.sh 中的assert-clean-git-state函数检测的正是同一组脆弱状态——[ -d .git/rebase-apply ] fragile$fragile rebase-apply [ -d .git/rebase-merge ] fragile$fragile rebase-merge [ -f .git/MERGE_HEAD ] fragile$fragile merge [ -f .git/CHERRY_PICK_HEAD ] fragile$fragile cherry-pick [ -f .git/index.lock ] fragile$fragile index.lock即 rebase 进行到一半rebase-apply/rebase-merge目录、merge 到一半MERGE_HEAD、cherry-pick 到一半CHERRY_PICK_HEAD、以及 index 被锁。devenv 文档也明确写道处于这些状态时工作区同步--sync会被整体阻止因为把一次进行到一半的 rebase 复制进所有工作区会让每个实例都停在同一个坏状态。也就是说本命令要处理的冲突状态恰好是仓库多工作区开发流程中唯一会冻结整条工具链的状态——尽快、正确地把它走完是有实际工程价值的而 Phase 1 的只读约束保证 Agent 在诊断阶段绝不会把状态搞得更糟。Phase 2 — 先给方案每个文件都要说清两边各干了什么、我准备怎么合原文 Phase 2第 20–27 行是整个命令中最人类中心的一段动任何文件之前必须先向用户呈现明确方案。对每个冲突文件说明三件事每一侧改了什么、为什么建议的解决方案及其推理依据两侧如何组合——原文给出的判据是both additive → merge两边只是各自新增 → 直接都保留both modify the same code → keep the semantically correct version, merging intent from both sides when clear from code and context两边改了同一段代码 → 保留语义正确的那一版当代码和上下文足够清楚时把两侧的意图融合起来只在真正无法判断时才提问。能从代码、commit message 或上下文推断出来的一律不要问只有那些不可判定且会改变结果的决定——例如相互冲突的产品决策、应当丢弃哪一侧——才值得提问所有提问集中到方案末尾的 Open Questions 小节让用户带着完整上下文一次性作答而不是被碎片化地打断在用户接受方案并回答 open questions之前不编辑、不暂存、不做任何修改。这条规则的设计意图值得展开冲突解决是典型的多解问题——机械上能合并不代表合对了。把方案评审前置等于给 Agent 的每个合并决定加了一道人类确认闸且确认成本被集中压缩到一次交互中。这与同仓库 review 命令 的Every finding must be real and actionable不要编造问题、以及 create-commit skill 中commit 前审查git diff --staged、发现与声明意图不符就 STOP 并告知用户的防御式风格一脉相承Penpot 的智能体规程普遍遵循先呈现可审查的证据再执行有副作用的动作。Phase 3 — 执行把文件编辑为约定好的合并结果原文 Phase 3 只有一条规则第 29–31 行按方案把每个冲突文件编辑为双方商定的合并内容删除所有冲突标记。看似简单但它是整条链路里唯一被允许修改文件内容的阶段。前两个阶段只读分析、方案呈现都是纯读操作写操作被收敛到一个与人类批准严格挂钩的窗口内——这正是Phase 2 末尾的等待存在的意义批准是写操作的许可证。Phase 4 — 暂存与验证用两条可机器检验的标准收尾原文 Phase 4第 33–36 行给出两条硬性验证标准用git add file暂存每一个已解决的冲突文件不要顺手暂存与本次解决无关的 untracked 文件除非它们明确属于解决方案的一部分验证无残留在已解决文件中搜索/确认没有冲突标记残留并且git status中不再出现 unmerged paths。这两步都是低成本、可重复执行的自检专门防御 LLM 常见失误——编辑时漏删一行或只解决了部分冲突文件就宣布完成。不暂存无关文件的补充规则则防止 Agent 把用户工作区里的其他未跟踪文件草稿、临时输出误打进暂存区污染后续提交。注意这一步的终点是暂存index而非提交git add是可逆的本地状态变更而git rebase --continue会推进 rebase 状态机并创建新的提交二者对系统的影响量级不同命令把分界线精确画在git add上。Phase 5 — 汇报即止把收尾权交还给用户原文 Phase 5第 38–41 行要求简要汇报冲突状态、每个冲突文件是如何解决的以及 open questions 收到了什么答案然后停下——不得运行git rebase --continue或任何类似的推进命令。汇报即止与开头的禁令、frontmatter 的描述共同构成三重强调。从工作流角度看收尾动作git rebase --continue、处理可能的下一个冲突、最终git status确认留给人类意味着人类始终掌握 rebase 的推进节奏和最终判断——这与 AGENTS.md 中 The user pushes from their own shell. If a push is required to surface the agents work ... state this in the response and wait for the user 的处理方式完全同构Agent 做到自己权限的边界把下一步由谁触发的控制权明确移交。从源码结构看这条命令与 Penpot 多工作区开发流程的衔接从仓库结构看这条命令不是孤立的提示词而是嵌在 Penpot 一套智能体辅助开发设施里的多工作区 devenvdevenv 文档 描述了ws0主仓库状态ws1位于~/.penpot/penpot_workspaces/的克隆的并行工作区模型--sync会把主仓库状态复制到各工作区。冲突rebase 进行中会让主仓库处于fragile state此时所有 sync 被 manage.sh 的assert-clean-git-state阻断。因此快速且正确地解决本地冲突直接决定了并行工作区能否恢复同步——resolve-git-conflicts 命令处理的正是这条链路上的阻塞点命令 → skill 的委托关系.opencode/commands/下的命令与.opencode/skills/下的 skill 是流程与规范细节的分工。例如 implement-plan.md 在提交步骤委托给 create-commit skill该 skill 拥有提交格式、staging 审查与安全禁令包括不要运行git reset/git checkout/git clean/rm这类破坏性命令resolve-git-conflicts 则刻意不委托任何 skill因为它的全部动作读文件、git show、编辑、git add都已在命令内定义完毕无需额外的规范源记忆系统的配合AGENTS.md 要求 Agent 在特定动作前读取mem:workflow/*记忆如提交前读mem:workflow/creating-commits。冲突解决不涉及提交故该命令未挂接此类前置读取——这也从侧面印证其职责收敛在文件级冲突消解 暂存这一最小集内。如何把这套规程搬进你自己的仓库如果想在其他项目复用这个工作流可以直接从原文的五个阶段抽象出一份可执行的冲突解决清单保留原命令的全部约束只补充了通用的命令细节1. 只读诊断 - git status # 确认 rebase/merge/cherry-pick 状态与冲突文件清单 - 读取每个 unmerged 文件定位 / / - git show :ours:file、git show :theirs:file # 两侧干净版本 - git log / git show sha # 理解两侧提交的意图 2. 呈现方案先批准后动手 - 每个文件两侧各改了什么、为什么建议方案与理由组合方式 - 判据纯新增冲突 → 两侧合并同段代码竞争 → 保留语义正确版本可辨识时融合双方意图 - 无法从代码/提交信息判定的决策 → 集中写入 Open Questions 待用户一次性作答 - 未获用户确认前不编辑、不暂存 3. 执行 - 按批准的方案改写文件删除全部冲突标记 4. 暂存与验证 - 对每个已解决文件执行 git add file不碰无关 untracked 文件 - grep 确认 / 无残留 - git status 确认无 unmerged paths 5. 汇报并停止 - 汇报冲突状态、每个文件的解决方式、open questions 的答案 - 不运行 git rebase --continue / --skip / git merge --continue收尾由用户执行这套清单的价值不在命令本身它们都是基础 Git 操作而在顺序与边界只读诊断 → 方案评审 → 受控写入 → 机器可验证的收尾 → 控制权移交。对 AI Agent 而言冲突解决最大的风险不是不会合并而是在错误理解意图的情况下把错误的合并一路推到rebase --continue使结果以提交的形式固化下来。Penpot 这条命令通过批准前零副作用 止步于git add 三重红线强调把这类风险压到了最低——这也是该文档对任何使用智能体辅助 Git 工作流的团队最有参考价值的部分。参考路径命令正文.opencode/commands/resolve-git-conflicts.md同目录配套命令.opencode/commands/implement-plan.md、.opencode/commands/review.md智能体硬规则AGENTS.md脆弱 Git 状态检测实现manage.sh多工作区与 fragile state 说明docs/technical-guide/developer/devenv.md提交规范 skillstaging 审查与安全禁令.opencode/skills/create-commit/SKILL.md【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考