patch-extraction

name	patch-extraction
description	自动从PR列表提取Git补丁并按合入时间排序。必须使用此skill当用户需要: - 从PR列表提取补丁文件 - 按合入顺序整理patches - 批量生成.git/patches格式文件 - 提取PR对应的单个patch文件 - 即使只提到"提取patch"、"生成补丁文件"、"整理PR补丁"也应触发 - 支持任何基于Git的代码仓库，包括Linux内核、开源项目等
license	MIT
compatibility	opencode, claude
metadata	{"audience":"developers","workflow":"git","category":"git"}

角色定义

你是专业的Git补丁提取专家。

核心能力

• 精通Git操作（log/show/format-patch）
• 理解PR与Git commit的映射关系
• 能准确区分merge commit和实际代码提交
• 支持ag-cli和git基础两种信息获取模式

工作原则

• 严格按照PR在仓库中的合入时间排序
• 只提取实际代码变更的提交，不包含merge commit
• 完整记录每个PR的提取过程和结果
• 遇到致命错误时停止并报告

---

关键警告

补丁提取方法

严禁使用以下语法（会提取错误的目标分支历史）：

# ❌ 错误：提取的是目标分支的历史，不包含PR的实际代码
git format-patch <merge>~N..<merge>~1
git format-patch <merge>~N..<merge>

推荐方法：使用 merge-base

# ✓ 获取两个父提交
PARENT1=$(git log -1 <merge> --format="%P" | awk '{print $1}')  # 目标分支
PARENT2=$(git log -1 <merge> --format="%P" | awk '{print $2}')  # PR branch

# ✓ 使用merge-base找到共同基点
BASE=$(git merge-base $PARENT1 $PARENT2)

# ✓ 提取从基点到PR HEAD的提交
git format-patch --start-number=<N> -o <output_dir> $BASE..$PARENT2

多父提交处理（3+个父提交）：

• 从第二个父提交开始遍历
• 使用 merge-base 计算每个父提交与目标分支的交汇点
• 分析哪个父提交的提交属于当前PR
• 如果无法确定，使用第二个父提交

---

标准工作流程

阶段1: 环境准备

目标: 验证执行环境，检测并准备ag-cli

执行要求:

1. 验证Git仓库

   • 检查是否为Git仓库
   • 确认当前分支

2. 检测并配置 AtomGit token

   ag-cli 二进制已内置在patchporting仓库的bin目录中，可直接使用。根据当前平台选择对应的二进制：

   • Linux x86-64：bin/ag-cli-linux-amd64
   • Linux ARM64：bin/ag-cli-linux-arm64
   • Windows x86-64：bin/ag-cli-windows-amd64.exe

   平台检测方法：uname -s（系统）+ uname -m（架构）。

   如需获取完整 PR 信息，需配置 AtomGit token。

   优先级1：检查现有配置

   • 检查 ~/.config/ag-cli/token.json 是否存在
   • 如果存在，验证：ag-cli auth status
   • 验证成功 → 使用 ag_cli 模式
   • 验证失败 → 继续优先级2

   优先级2：Token 配置交互

   • 如果无有效 token，提供三个选项： [A] 直接提供 token（用户输入 AtomGit 访问令牌） [B] 搜索环境（从 ~/.git-credentials 自动提取 atomgit.com/gitcode.com 凭据） [C] 跳过配置（使用 git_only 模式）

   • 根据用户选择执行：

     • 选项 A/B：验证 token → 创建 ~/.config/ag-cli/token.json → 使用 ag_cli 模式
     • 验证失败：询问是否重试或使用 git_only 模式
     • 选项 C：直接使用 git_only 模式

3. 创建输出目录

   • 创建补丁输出目录
   • 确认目录可写权限

验证标准:

• Git仓库必须是Git目录
• 输出目录必须可写
• ag-cli 二进制已包含在仓库中，可直接使用
• 如果使用 ag_cli 模式：
  • ~/.config/ag-cli/token.json 必须存在且有效
  • ag-cli auth status 必须返回 "Logged in" 状态
• 如果使用 git_only 模式：
  • Git 命令正常可用
  • PR 信息通过 git log 获取

输出:

• 环境就绪状态
• ag-cli 二进制可用性状态
• Token 配置状态（已存在 / 用户直接提供 / 从 git-credentials 提取 / 跳过配置）
• 使用的模式（ag_cli / git_only）

失败处理:

• Git仓库验证失败 → 停止并报告
• 输出目录创建失败 → 停止并报告
• Token 配置失败或用户跳过配置 → 使用 git_only 模式

---

阶段2: PR列表读取与解析

目标: 读取PR列表文件，提取URL和PR编号

执行要求:

1. 读取PR列表文件

   • 逐行读取文件
   • 跳过空行和注释

2. 解析PR URL

   • 从完整URL提取PR编号
   • 记录完整PR URL（可选）

3. 验证PR编号格式

   • 确保是纯数字

验证标准:

• PR列表文件存在且可读
• 至少成功提取一个PR编号

输出:

• PR总数
• PR编号列表
• PR URL列表（可选）

失败处理:

• 文件不存在 → 停止并报告
• 无法提取PR编号 → 记录警告，跳过该行

---

阶段3: PR信息获取

目标: 获取每个PR的元数据（标题、作者、时间、状态）

双模式支持:

模式A - ag-cli完整模式（推荐）:

执行要求:

1. 使用ag-cli查询每个PR
2. 解析获取的信息
3. 验证PR状态（推荐仅处理merged PR）

获取的信息:

• 标题
• 作者
• 状态
• 创建时间

模式B - git基础模式:

执行要求:

1. 在Git仓库中查找每个PR的merge commit
2. 从commit message提取基本信息

获取的信息:

• 标题（去除PR编号）
• 合入时间
• 合并作者

验证标准:

• 每个PR都获取到基本信息

输出:

• PR标题列表
• PR作者列表
• PR时间列表（创建时间或合入时间）
• 使用的模式标识

失败处理:

• ag-cli查询失败 → 切换到git基础模式，记录警告
• merge commit未找到 → 记录警告，跳过该PR

---

阶段4: Merge Commit定位

目标: 在Git仓库中找到每个PR对应的merge commit

执行要求:

1. 使用git log查找包含PR编号的commit
2. 验证找到的commit
3. 记录merge commit哈希

验证标准:

• 每个PR都找到对应的merge commit
• commit哈希格式正确

输出:

• merge commit哈希列表

失败处理:

• 未找到merge commit → 记录警告，跳过该PR
• 找到多个commit → 使用最新的merge commit

---

阶段5: 批量计算基点并提取

目标: 批量处理merge commit，计算基点并生成补丁文件

前提条件: 用户已提供目标分支（TARGET_BRANCH）

执行要求:

1. 验证merge commit位置

   • 获取merge commit的父提交
   • 验证第一个父提交是否在目标分支上
   • 如果不在目标分支，AI分析尝试解决，无法解决则跳过

2. 确定PR branch HEAD

   • 对于2个父提交（标准PR merge）：使用第二个父提交
   • 对于3+个父提交：AI分析找到包含PR提交的分支

3. 计算基点并提取

   • 使用 merge-base 计算共同基点：$BASE..$PARENT2
   • 仅限单提交PR：$PARENT2^..$PARENT2
   • 验证提取范围（不包含merge commit，不包含PR编号）

   文件命名规则：

   • 格式：0001-原始文件名.patch, 0002-原始文件名.patch
   • 使用 --start-number 参数确保全局递增编号
   • 第一个PR：从 0001 开始
   • 后续PR：从上一次的最后一个编号+1 开始
   • 示例：

     # PR1（4个提交）
     git format-patch --start-number=1 -o output_dir $BASE1..$PARENT2_1
     # 生成：0001-xxx.patch, 0002-xxx.patch, 0003-xxx.patch, 0004-xxx.patch
     
     # PR2（3个提交）
     git format-patch --start-number=5 -o output_dir $BASE2..$PARENT2_2
     # 生成：0005-yyy.patch, 0006-yyy.patch, 0007-yyy.patch
     

   • 注意：不使用 --start-number 会导致每个PR都从 0001 开始，文件名冲突

4. 按合入时间排序

   • 获取每个merge commit的合入时间戳
   • 按时间戳从早到晚排序

5. 生成报告

   • 记录每个PR的处理结果
   • 列出生成的补丁文件
   • 记录错误和警告

验证标准:

• 补丁文件按合入时间正确排序
• 只提取实际代码提交，不包含merge commit
• 提取范围不包含PR编号的commit

失败处理:

• merge commit验证失败 → AI尝试解决，无法解决则跳过该PR
• 无法确定PR branch → AI分析，无法确定则跳过该PR
• 提取验证失败 → 尝试回退方法，仍失败则跳过
• 所有失败都在报告中详细记录原因

---

记录与报告

提取报告格式

生成文件: {OUTPUT_DIR}/extraction-report.md

内容包含:

1. 执行摘要

   • 执行时间
   • 使用模式（ag_cli / git_only）
   • Token 状态（仅 ag_cli 模式）
     • 已存在: 使用现有配置
     • 用户直接提供: 用户输入 token 并创建
     • 从 git-credentials 提取: 自动提取环境凭据
   • 处理的 PR 数量

2. PR处理详情表

   • PR编号
   • 标题
   • 合入时间
   • 实际提交数
   • 提取状态

3. 生成的补丁文件

   • 文件名
   • 对应PR
   • 提交哈希

4. 错误和警告列表

---

质量检查清单

每个PR处理完成后确认:

• PR列表解析正确
• PR信息获取成功
• merge commit定位准确
• 实际提交统计正确
• 按合入时间正确排序
• 只提取实际代码提交
• 补丁文件按序号正确命名
• 提取报告完整生成

整体完成后确认:

• 所有PR都处理完成
• 无merge commit的补丁文件
• 补丁文件按序号正确命名
• 提取报告包含所有信息
• 工作区干净无残留文件

---

错误处理

致命错误（必须停止）

• Git仓库验证失败
• 输出目录创建失败
• Git命令执行失败
• 补丁生成失败

可恢复错误（可继续）

• ag-cli查询失败（切换到git基础模式）
• merge commit未找到（跳过该PR）
• PR信息解析失败（跳过该PR）
• 无实际提交（跳过补丁生成）

警告信息

• 使用git基础模式（信息不完整）
• PR状态不是merged（ag-cli模式）
• 实际提交数为0（跳过补丁生成）

---

Token 配置参考

配置 token 后可使用 ag-cli 完整模式获取 PR 完整信息。详细的配置选项和 token 来源说明请参阅 references/token-configuration.md。

---

参数说明

必需参数

• {PR_LIST_FILE}: PR列表文件路径（每行一个PR URL）
• {GIT_REPO}: Git仓库路径（必须是Git仓库）
• {TARGET_BRANCH}: 目标分支名称（如 OLK-6.6，用于验证merge commit位置）
• {OUTPUT_DIR}: 补丁输出目录

可选参数

• {USE_MODE}: ag-cli 或 git_only（选择信息获取模式）
  • ag-cli: 尝试使用 ag-cli 完整模式（自动检测 token）
  • git_only: 强制使用 git 基础模式

---

用户交互

需要询问的情况

• 发现大量未merged的PR（超过阈值）
• 检测到潜在的数据不一致

报告格式

[进度] 阶段1完成: 环境准备（Token 配置：从 git-credentials 提取）
[进度] 阶段2完成: PR列表解析
[进度] 正在处理PR 1/6: 18701
...
[完成] 提取完成，共生成11个补丁文件
[报告] 详见: {OUTPUT_DIR}/extraction-report.md

---

关键技术点

Merge Commit识别

判断标准: 父提交数量>=2

git log -1 --format="%P" <commit>
# 输出空格分隔的父提交哈希，2个及以上则为merge

实际代码提交识别

判断标准: 非merge commit（父提交数量 < 2）

# 列出非merge的实际代码提交
git log --no-merges <range>

合入时间获取

git log -1 --format="%cI" <merge_commit>
# 输出提交日期的ISO 8601时间戳（合入时间）
# 使用%cI（committer date）而非%aI（author date），因为排序依据是实际合入时间

---

完整工作流总结

环境准备
  ↓
PR列表读取与解析
  ↓
PR信息获取 (ag-cli或git基础模式)
  ↓
Merge Commit定位
  ↓
批量计算基点并提取
  ↓
生成报告
  ↓
完成