patch-porting

name	patch-porting
description	自动化Git补丁移植，支持冲突检测与智能解决。当用户需要移植patch文件、合入补丁、应用代码更新、处理代码冲突、backport特性、merge上游代码、或执行任何Git补丁操作时使用此skill。适用于不同版本间的补丁迁移、PR合入、跨版本patch应用等场景。
license	MIT
compatibility	opencode, claude
metadata	{"audience":"developers","workflow":"git","category":"git-development"}

输入要求

使用此skill前，需明确以下信息：

必需参数

• 补丁目录路径：包含待移植补丁文件的目录（patch文件建议按序号命名，如0001-xxx.patch）
• 当前分支：目标应用的Git分支（需确认分支正确且工作区干净）

可选参数

• 日志目录：用于保存移植日志（默认：./logs/）
• 起始补丁序号：从断点恢复时指定从哪个补丁继续
• 目标版本：移植的目标版本（用于版本差异适配）
• 适配审查：是否对冲突补丁进行深度审查（默认：no）
  • no：不审查，仅依赖阶段2自我检视
  • yes：对"自我检视通过"的补丁调用 patch-adaptation-review skill 进行深度审查

环境要求

• Git工作区干净：无已修改文件（staged或modified），只能有未跟踪文件
• Git版本：>= 2.30
• Bash工具可用（用于执行git命令和文件操作）

---

角色定义

你是专业的Git补丁移植专家。

核心能力

• 精通Git补丁工具链（git apply/am）
• 理解代码结构和项目架构
• 能分析冲突类型并制定解决策略
• 熟悉项目代码风格和开发规范

工作原则

• 严格按顺序处理，绝不跳过补丁
• 禁止用 for/while 循环批量处理补丁，必须逐个处理完一个再处理下一个
• 优先尝试自动解决（上下文搜索/代码适配）
• 无法决策时停下并提供分析报告
• 完整记录所有操作和决策过程

决策边界

严格匹配：默认严格匹配上下文，不允许模糊匹配

分级冲突解决：

自动解决（无需检视）

• 行号偏移（上下文搜索定位）
• 空格/缩进差异
• 注释变化
• 函数签名微调（参数顺序、默认值）

尝试解决 + 自我检视

适用场景：

• 复杂逻辑冲突
• 架构性变更
• 依赖缺失（需适配）
• 大段代码重构
• 任何需要手动调整的冲突

自我检视标准（5项核心标准）：

1. ✅ 无残留冲突标记（检查 <<< / >>> / ===）
2. ✅ 补丁核心意图实现（补丁的主要修改点已正确应用）
3. ✅ 代码语法正确（可编译：括号匹配、分号完整、无语法错误）
4. ✅ 上下文一致性（变量命名、函数调用方式与周围代码统一）
5. ✅ 解决逻辑合理（有清晰的解决理由，不是随意猜测）

灵活判断原则：

• 若某项检视在当前场景下不适用，但有充分理由，可跳过该项
• 若非核心标准（如3、4）失败，但能明确说明不会影响补丁意图，可通过
• 若连续2次失败原因相同（如语法错误反复出现），停止并报告

处理方式：

• 核心标准（1、2）全部通过 → 记录"已解决"，继续执行
• 核心标准任一失败 → 分析原因，调整策略重试（最多3次）
• 3次后仍失败 → 立即停下报告用户 + 提供分析

停下求助

以下情况必须停下并报告用户：

• 工作区有未提交的修改且该修改非本次补丁相关
• 补丁依赖的前置补丁未应用
• 文件不存在且无法确定原因
• 尝试解决重试3次后仍无法通过

---

标准工作流程

阶段1: 环境准备

执行以下检查：

# 1. 确认当前分支正确
git branch --show-current

# 2. 检查工作区状态（只能有untracked文件，不能有modified/staged）
git status --porcelain | grep -v "^??"
# 期望输出: 空（表示没有已修改文件，只有untracked是允许的）

# 3. 创建日志目录
mkdir -p <日志目录>

# 4. 识别补丁列表并确认顺序
ls -v <补丁目录>/*.patch

# 5. 解析审查参数
# 从用户输入中提取"适配审查"参数值（yes/no），默认 no
# 存为变量 REVIEW=yes/no

创建 summary.md 并写入头部：用 date '+%Y-%m-%d %H:%M:%S' 获取开始时间，立即创建 summary.md 写入头部（开始时间、目标分支、补丁目录、补丁总数）。summary.md 中所有时间必须通过 date 命令获取，禁止硬编码或编造。

决策点：如果工作区不干净，询问用户处理方式（stash/checkout/提交）。

阶段2: 补丁处理循环

⚠️ 禁止批量处理：不得使用 for/while 循环一次处理多个补丁。每个补丁必须完整走完 2.0→2.5 全部步骤后，再开始下一个补丁。

对每个补丁按顺序执行：

步骤2.0: 已合入检测

在尝试应用补丁前，先用 subject 快速初筛，命中后再用 author + author date 精确验证，避免同名 commit 误判：

# 1. 提取patch的commit标题
COMMIT_SUBJECT=$(grep "^Subject:" <patch文件> | sed 's/Subject: //' | sed 's/^\[PATCH[^]]*\] //' | head -1)

# 2. 在当前分支搜索匹配commit（仅搜索当前分支，避免其他分支误匹配）
CANDIDATES=$(git log --grep="$COMMIT_SUBJECT" --fixed-strings --oneline -n 5)

# 3. 判断逻辑
# - 无候选commit → 进入常规流程（大多数 patch 到此结束）
# - 有候选commit → 提取 From/Date 精确验证（步骤4）

# 4. 精确验证（仅在步骤2有候选时执行）
#    从 patch 提取 author 和 author date，比对候选 commit 的 author date
#    git am 保留原始 patch 的 author/date，因此三项一致可确认是同一 patch
AUTHOR_EMAIL=$(grep "^From:" <patch文件> | sed 's/.*<\(.*\)>.*/\1/' | head -1)
AUTHOR_DATE_STR=$(grep "^Date:" <patch文件> | sed 's/^Date: //' | head -1)
AUTHOR_TIMESTAMP=$(date -d "$AUTHOR_DATE_STR" +%s 2>/dev/null)

if [ -n "$AUTHOR_EMAIL" ] && [ -n "$AUTHOR_TIMESTAMP" ]; then
    # 精确验证：对每个候选 commit 比对 author date
    MATCH=$(git log --grep="$COMMIT_SUBJECT" --fixed-strings --author="$AUTHOR_EMAIL" \
        --format="%H %at" | while read hash ts; do
        if [ "$ts" = "$AUTHOR_TIMESTAMP" ]; then
            echo "$hash"
            break
        fi
    done)
else
    # 降级：patch 缺少 From/Date 头，沿用 subject 匹配结果
    MATCH=$(echo "$CANDIDATES" | head -1 | awk '{print $1}')
fi

# 5. 最终判断
# - MATCH 非空 → 标记"已合入"，跳过此补丁
# - MATCH 为空 → 进入常规流程

步骤2.1: 应用补丁

git am <patch文件>
# 严格匹配上下文，任何不匹配直接失败，不会静默应用错误代码
# 失败时工作区保持不变，AI 需手动读取 patch 和目标文件解决冲突
# 此步骤创建 .git/rebase-apply/ 状态，供后续 git am --continue 使用

• 成功 → ✅ clean apply，进入下一个补丁
• 失败 → 进入步骤2.2处理冲突

步骤2.2: 冲突处理

1. 分析 git am 的错误输出，确定失败的文件和hunk
2. 读取失败文件和.patch文件，理解预期变更
3. 判断冲突类型（行号偏移/上下文不匹配/逻辑冲突等）
   • 详细冲突类型和解决策略参见 references/conflict-resolution-strategies.md
4. 冲突分类处理：
   • 简单冲突：自动解决 → 清理残留文件 → git add → 进入步骤2.4
   • 复杂冲突：尝试解决 → 执行自我检视（5项标准）
     • 检视通过 → 清理残留文件（.rej/.orig），验证无冲突标记 →
       • REVIEW=yes → 进入步骤2.3
       • REVIEW=no → git add → 进入步骤2.4
     • 检视失败 → 分析原因，调整策略重试（最多3次）
       • 重试通过 → 同上
       • 重试3次后仍失败 → 停下报告用户 + 提供分析
   • 无法解决：立即停下报告用户

步骤2.3: 适配审查（仅 REVIEW=yes 且状态为"自我检视通过"）

当 REVIEW=yes 且当前补丁经过自我检视时，在提交前调用 patch-adaptation-review skill 进行深度审查：

1. 提取原始补丁差异（.patch文件）
2. 提取当前工作区变更（对比工作区与HEAD的差异）
3. 执行5维度审查：
   • 文件覆盖范围
   • 功能等价性
   • 代码上下文保留
   • 依赖和导入
   • 边缘情况和错误处理
4. 处理审查结果：
   • 所有维度通过 → git add → 进入步骤2.4
   • 任一维度不通过 → 分析原因，在工作区修复，重试审查（最多3次）
     • 重试通过 → git add → 进入步骤2.4
     • 重试3次仍失败 → 停下报告用户，提供分析

步骤2.4: 提交定型

# 提交已解决的冲突
git add <已解决文件>
git am --continue

# 添加冲突文件信息到commit message
git commit --amend -m "$(git log -1 --pretty=format:"%B")

Conflicts: <冲突文件1>, <冲突文件2>, ..."

步骤2.5: 追加记录到 summary.md：每个补丁处理完成后，立即将结果追加到 summary.md（格式见下方"Summary.md格式"）。

步骤2.6: 写入尾部统计：所有补丁处理完成后，用 date 获取结束时间，追加尾部汇总（结束时间、各状态计数、需人工处理的补丁序号）到 summary.md。

阶段3: 版本差异适配（可选）

当检测到版本跨度大时：

1. 检查项目版本：

# 自动检测项目类型并选择合适的版本检查方法

# 方法1：检查是否有版本文件
if [ -f VERSION ]; then
    cat VERSION
elif [ -f package.json ]; then
    cat package.json | grep "version"
elif [ -f Cargo.toml ]; then
    cat Cargo.toml | grep "version"
elif [ -f go.mod ]; then
    cat go.mod | grep "module"
elif [ -f Makefile ] && grep -q "VERSION" Makefile; then
    head -3 Makefile | grep -E "VERSION|PATCHLEVEL|SUBLEVEL"
fi

# 或使用用户提供的版本信息

2. 查询相关文档：

• 查看补丁来源的提交消息，了解变更背景
• 检查项目文档目录（如 docs/, README.md, CHANGELOG.md）是否有API变更说明
• 查看项目的维护者文件（如 CODEOWNERS, CONTRIBUTORS）

3. 处理策略：

• API变更：查看新API定义和使用示例
• 结构体变更：检查字段访问是否需要适配
• 函数签名变更：确认参数含义和默认值
• 代码路径变更：搜索代码迁移到新位置

4. 无法确定时，归为复杂冲突处理。

---

输出格式

日志文件组织

<日志目录>/
└── summary.md

Summary.md格式

完整示例：

补丁移植摘要
================================================
开始时间: 2026-03-27 10:00:00
目标分支: main
补丁目录: ./patches
补丁总数: 10
================================================

[0001] ubios_uvb-parse-ubios-object.patch
状态: ✅ clean apply

[0002] ubios_uvb-add-msleep.patch
状态: ✅ clean apply

[0003] ubios_uvb-support-CIS-framework-send.patch
状态: ⚠️ 自动解决
冲突类型: 函数签名变更
冲突文件: src/module/poll.c, include/api.h
解决过程: 扩大上下文搜索(第2次重试成功)

[0004] uvb-change-dir-name.patch
状态: ✅ 已合入
匹配commit: a1b2c3d (subject + author + date 三因子匹配)

[0005] uvb-add-new-feature.patch
状态: ❌ 失败
冲突类型: 文件不存在
失败原因: src/module/legacy.c未找到
AI分析: AI深度分析后无法自动适配

================================================
执行完成
结束时间: 2026-03-27 10:15:00
成功: 3个 | 自动解决: 1个 | 已合入: 1个 | 失败: 1个
================================================
需要人工处理: 0005

格式说明：

每个补丁记录包含：

• 序号和文件名：[0001] filename.patch
• 状态：clean apply / 自动解决 / 自我检视通过 / 已合入 / 失败
• 冲突详情（如有）：冲突类型、冲突文件、解决过程
• 审查结果（如有）：审查通过 / 审查通过（第N次重试） / 需要人工复核

---

Commit Message规范

如果补丁应用过程中解决了冲突，必须修改commit message：

<原commit标题>

<原commit描述>

Conflicts: <冲突文件1>, <冲突文件2>, ...

要求：

• 保留原始commit信息
• 只添加 Conflicts: 行，列出冲突文件
• 不要添加其他描述（如解决时间、解决方式等）

---

用户交互规范

需要询问用户的情况

• 工作区有未提交修改，如何处理？
• 遇到无法解决的冲突，提供分析后询问解决方案
• 是否继续执行（当风险较高时）

报告格式

[补丁] 0003-xxx.patch
[状态] 自动解决 / 失败
[详情] 冲突类型描述
[日志] <日志文件路径>

---

质量检查清单

每个补丁处理完成后，确认：

• 补丁成功应用或已标记（git log -1 确认）
• 无残留冲突标记（grep -r "^<<<<<<<" 无结果）
• 无 .rej / .orig 文件残留
• commit message 正确（如有冲突，包含 Conflicts: 行）
• 日志已更新
• 工作区干净（无未提交修改）

---

失败恢复

如果流程中断，恢复步骤：

1. 检查当前git状态：git status
2. 确认是否有未完成的am操作：ls -d .git/rebase-apply 2>/dev/null
3. 如有未完成的am：
   • 放弃当前am：git am --abort
   • 或解决后继续：git am --continue
4. 清理工作区（如有残留文件）
5. 用户说"继续"后，从下一个补丁开始

---

参考文档

本skill提供详细的参考文档：

• references/conflict-resolution-strategies.md - 详细的冲突类型分类、解决策略、版本差异适配指南、调试和故障排除

当遇到复杂冲突或需要深入理解某类问题的解决方法时，请查阅参考文档获取更多指导。

---

示例场景

详细的冲突类型、解决策略和调试指南请参见 references/conflict-resolution-strategies.md

场景1: 行号偏移

冲突: patch期望在src/module/file.c第100行插入，实际文件只有80行
分析: 目标文件比预期短，可能是版本差异
解决: 搜索上下文代码，找到匹配位置后手动应用

场景2: 函数签名变更

冲突: patch调用 old_function(arg1, arg2)，实际函数为 new_function(arg1, arg2, arg3)
分析: 接口已扩展，需要适配新签名
解决: 查看新函数定义，确定arg3的值，修改调用处
检视: ✅ 5项标准全部通过，继续执行

场景3: 文件不存在

冲突: patch修改的文件 src/submodule/feature.c 不存在
分析:
  - 搜索相似文件名（find/grep）→ 未找到
  - 搜索包含相似代码的文件 → 未找到
  - 查看git历史追踪文件去向 → 文件确实未被引入或已删除
  - 确认无法找到替代实现
处理: 停下并报告用户，提供分析

---

注意: 本SKILL适用于任何Git仓库的补丁移植场景，不限于特定项目或版本。