PaddlePaddle 与 PyTorch C++ API 兼容性测试开发规范。适用于：编写或扩展 test/ 目录下的兼容性测试、验证 Paddle 兼容层与 PyTorch 同一 API 的行为一致性、定位接口输出差异、新增算子测试、覆盖 Shape/Dtype/值域/API 变体。Use when: writing compatibility tests, adding operator tests, checking ATen/c10 API behavior differences between Paddle and PyTorch.

2026-05-190

name	fix-compat-api
description	根据 PR 链接、GitHub Actions 链接或 review/comment 链接定位问题并修复 Paddle C++ compat 接口。Use when: 需要按外部链接驱动修复 c10/ATen/torch 兼容层接口并完成编译、测试和回归。
argument-hint	传入一个链接（PR / Actions / review comment）与仓库路径参数

Fix Compat API From Link

根据外部链接定位兼容性问题来源，执行最小修复并完成验证闭环。流程参考 ~/Paddle/.humanize 中的兼容修复实践。

输入参数

INPUT_LINK: 必填。三选一：
- PR 链接：https://github.com/<org>/<repo>/pull/<number>
- Actions 链接：https://github.com/<org>/<repo>/actions/runs/<run_id>
- review/comment 链接：
  - https://github.com/<org>/<repo>/pull/<number>#discussion_r...
  - https://github.com/<org>/<repo>/pull/<number>/files#r...
  - https://github.com/<org>/<repo>/pull/<number>#issuecomment-...
PADDLE_ROOT: 默认 ~/Paddle
PYTORCH_ROOT: 默认 ~/pytorch
PCAT_ROOT: 默认 ~/PaddleCppAPITest
TORCH_DIR: 默认 ~/libtorch

建议先设置：

PADDLE_ROOT=~/Paddle
PYTORCH_ROOT=~/pytorch
PCAT_ROOT=~/PaddleCppAPITest
TORCH_DIR=~/libtorch

适用场景

评审意见指向 compat 接口行为不一致
CI/Actions 报错指向 c10/ATen/torch 兼容层
需要按链接快速复现、修复并回归验证

链接分流规则

分支 A：输入为 PR 链接

提取 PR 编号
收集最新 review comments 与普通 comments（优先 unresolved / 最新）
仅筛选 compat 相关问题（paddle/phi/api/include/compat、test/cpp/compat）

分支 B：输入为 Actions 链接

提取失败 job 与失败步骤
锁定失败测试/文件（优先 c10、ATen、torch compat 相关）
必须反查关联 PR，再定位对应评论与代码上下文

分支 C：输入为 review/comment 链接

直接读取评论内容与上下文代码片段
回溯到对应 PR 与文件位置
将该评论作为本轮修复主目标

分支 D：链接无法识别

明确提示支持的 URL 格式
请求用户重新提供可解析链接

横向退出条件：根因为接口完全缺失

若 Step 1 解析后发现链接所指根因是 "Paddle 侧完全没有该接口" （而非行为不一致），本 skill 不直接走 Step 2–5。请退出当前 fix 循环，改用 add-compat-api skill 启动新增循环。add-compat-api 完成后，回到本 skill 重新输入原链接，验证问题是否消失。

本引用为说明性引用，不会自动触发 add-compat-api——避免一次输入同时启动两条驱动型循环造成递归。请用户/Claude 明确在两个 skill 间切换。

Step 0. 环境检测与自动配置

进入主流程之前，按以下顺序检测并按需配置环境。完整命令模板与 fallback 决策见 ../add-compat-api/references/Step0.md（与 add-compat-api 共享同一份 references）。

检测 NVIDIA GPU（决定 libtorch CPU/CUDA 版本，用 nvidia-smi）
PaddleCppAPITest（fork 工作流，缺失则自动克隆并配置 origin/upstream）
pytorch（upstream，缺失则浅克隆，仅供参考）
libtorch（缺失则下载并解压；URL 按上一步检测结果选 CPU / cu126）
Paddle 仓库（不自动克隆——缺失时提示用户手动 fork + 克隆 + 配置 upstream，并暂停等待）
- fix 流程通常已有 Paddle 仓库（因为是链接驱动、对已有代码做修复）；若缺失，提示并暂停等待用户配置
Paddle wheel（缺失则提示用户安装；不自动 pip install，因为版本须与 Paddle build 输出一致）

安全约定：克隆、下载、pip install 这类"本地、可逆"操作可在用户已知意图下直接执行；但不要主动改用户已存在仓库的 remote（remote 是用户工作流，意外覆盖会丢失工作）。

修复流程（循环执行）

Step 1. 解析需求并定义本轮目标

从链接提取本轮要修复的接口清单（建议 1-3 项）
明确每项接口的语义基线：
- 参数/返回类型
- dtype/shape 规则
- 异常触发时机
约束修复范围：仅处理本轮链接指向问题

Step 2. 对照 PyTorch 实现

在 $PYTORCH_ROOT 查找目标接口声明与实现
记录语义关键点，不照搬无关实现
确认不引入 PyTorch 和 Paddle 都不存在的新设计

Step 3. 在 Paddle 侧实施最小修复

修改 compat 接口实现：$PADDLE_ROOT/paddle/phi/api/include/compat
新增或补充测试：$PADDLE_ROOT/test/cpp/compat
若本轮修复涉及 $PCAT_ROOT/test 下用例（链接指向 result_cmp diff、或修复改变了输出格式 / dtype / 异常路径），按统一规范扩写或新增。测试规范见 compatibility-testing，本文档不复述。

调用该 skill 时传入：
- PCAT_ROOT=$PCAT_ROOT
- 算子名：链接指向的接口
- 修复点：dtype 推导 / 异常路径 / shape 边界 / API 变体 等
- 已有测试路径：$PCAT_ROOT/test/<分类>/<OpName>Test.cpp
返回后只针对修复点新增最小化用例，不重排无关测试。
必要时补充 $PCAT_ROOT/test 下其余兼容回归用例（按上一调用返回的 checklist 自检强制项）。

Step 4. 编译与测试验证

cd "$PADDLE_ROOT/build"
ninja -j"$(nproc)"
ctest -R "ATen|c10|torch"

Step 5. 安装 wheel 并执行外部回归

pip install "$PADDLE_ROOT"/build/python/dist/*.whl --force-reinstall --no-deps

cd "$PCAT_ROOT/build"
cmake .. -DTORCH_DIR="$TORCH_DIR" -DENABLE_COVERAGE=ON -G Ninja
ninja -j"$(nproc)"

cd "$PCAT_ROOT"
bash test/result_cmp.sh ./build/

Step 6. 判定是否继续循环

若本轮链接对应问题仍未消失：回到 Step 2
若本轮问题已修复且验证通过：进入收尾

完成标准

同时满足以下条件才算完成：

链接对应的问题点已被代码与测试覆盖
$PADDLE_ROOT/build 下 ninja -j"$(nproc)" 成功
ctest -R "ATen|c10|torch" 全部通过
$PCAT_ROOT 下 bash test/result_cmp.sh ./build/ 中相关用例通过
未引入 PyTorch 与 Paddle 上游都不存在的实现
文档已通过 compat-doc-authoring 归档，且其 Step 5 校验全部通过

文档收尾模板

完成后更新文档（固定写入 $PCAT_ROOT/doc/ 对应专题文档）：

## Compat 修复记录（YYYY-MM-DD）

### 1) 输入链接
- 链接类型：PR / Actions / review comment
- 原始链接：
- 关联 PR（如可定位）：

### 2) 问题与根因
- 问题接口：
- 触发场景：
- 根因说明：

### 3) 修复内容
- Paddle compat 改动文件：
- 新增/修改测试：
- PyTorch 对齐依据：

### 4) 验证结果
- ninja：通过/失败
- ctest -R "ATen|c10|torch"：通过/失败
- result_cmp：通过/失败

### 5) 风险与后续
- 已知风险：
- 后续待办：

文档归档（调用 compat-doc-authoring）

按上节"Compat 修复记录"模板填好五段后，调用 compat-doc-authoring 完成入库与格式校验。

调用该 skill 时传入：

PCAT_ROOT=$PCAT_ROOT
调用模式：append-to-existing
目标文档：$PCAT_ROOT/doc/<topic>.md
上游模板名：Compat 修复记录
已填段落：粘贴上节"Compat 修复记录（YYYY-MM-DD）"五段完整填好的 Markdown

下游会做的事：

若本次修复改变了 API 对比表中某行的状态（🔧 ↔ ✅），由下游负责改表
回填 ## 兼容性统计 数字
检查链接编号、PR 编号是否在"备注"列被回填
按 Step 5 校验 checklist 全项过审

Step 7. 提交 commit 并创建 PR

闭环验证通过且文档已回填后，按以下流程提交。完整命令模板见 ../add-compat-api/references/Step7.md（与 add-compat-api 共享同一份 references）。

从本地跟踪 origin 的 develop 创建新分支（git checkout develop && git pull --ff-only origin develop && git checkout -b fix/<pr-or-issue-num>-<YYYYMMDD>）
commit 改动（commit message 首行使用 [Cpp API Compatibility] <Compat 修复记录标题>）
征求用户同意后 push 到 fork（git push origin <branch>——这是发出去的动作，push 前必须明确询问用户）
征求用户同意后 gh pr create 到 upstream（--repo PaddlePaddle/Paddle --base develop——同样需要用户确认；若本轮修复源自外部 PR/Actions/comment 链接，PR 描述里应引用原链接便于追溯）
如果还改了 PCAT 测试：在 $PCAT_ROOT 上重复 1-4 步，--repo PFCCLab/PaddleCppAPITest --base master
等待 CI 完成并按结果分流（gh pr checks <PR_NUM> --watch）
- CI 通过 → 等待 reviewer，本流程结束
- CI 失败 → 调查失败是否由本 PR 引起（命令与判断标准见 ../add-compat-api/references/Step7.md 第 6 节）：
  - 是 → 返回 Step 2 修复；同一分支上 commit + push（push 仍需用户同意），PR 自动更新，不发新 PR
  - 否 → gh pr comment <PR_NUM> --body "/re-run all-failed" 重新触发 CI，回到本步骤继续 watch

安全约定：git push 与 gh pr create 每一次执行前必须征求用户同意（不是"在整个 Step 7 开始时一次性确认"，而是这两条命令各确认一次）。修复后的 push 同样适用——同一分支不豁免。这与系统提示"对影响他人的动作要逐次确认"一致。

常见错误

只修测试输出，不修接口语义
跳过 ctest 或 result_cmp 直接结束
为“临时通过”引入上游不存在的实现
一次改动过大，导致无法定位回归来源