[API Compatibility] Modify and supplement documents Edit By AI Agent

Author: zhwesky2010

docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-change-decider/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: api-change-decider
-description: 仅用于《Paddle API 对齐 PyTorch 项目》，负责 Step1：方案决策，分析 PyTorch API 与 Paddle API 之间的差异，制定合适的 API 改动方案
-allowed-tools: Read Grep‌ Glob‌ WebSearch
+description: 负责《Paddle API 对齐 PyTorch 项目》中 Step1：方案决策，分析 PyTorch API 与 Paddle API 之间的差异，制定合适的 API 改动方案
+allowed-tools: Read Grep Glob WebSearch
 disable-model-invocation: false
 ---
 
@@ -15,7 +15,7 @@ disable-model-invocation: false
 
 ## 1.3 输出内容
 输出应包含如下内容，以表格式形式展示：
-1. **方案类型**：从方案 1~6 中选择合适的方案（可组合多种方案，例如方案 3+方案 1）
+1. **方案类型**：从方案 1~6 中选择合适的方案
 2. **对应 Paddle API**：需改动的 Paddle API 完整路径（如 `paddle.nn.functional.dropout`）
 3. **差异分类**：差异分类是什么
 4. **决策依据**：总结差异分析过程和选择理由
@@ -114,12 +114,49 @@ disable-model-invocation: false
 
 # 三、标准工作流程
 
-## Step 1: 分析差异文档
-
-### 1.1 获取差异文档
-务必查阅每个 PyTorch API 对应的 API 差异文档（`torch.{api_name}.md`，位于 docs/docs/guides/model_convert/convert_from_pytorch/api_difference/目录下），如果实在无法找到差异文档，则说明该 API 已经实现了对齐一致，差异分类直接视作『API 完全一致』，无需再查询其他内容。
-
-### 1.2 差异分类定义
+## Step 1: 差异分析
+
+### 1.1 获取差异信息
+
+按以下优先级依次尝试获取差异信息：
+
+**优选方案：查阅差异文档与转写配置**
+- **综合分析两者信息**：
+  1. 查阅 PyTorch API 对应的 API 差异文档（`torch.{api_name}.md`，位于 `${ROOT_DIR}/docs/docs/guides/model_convert/convert_from_pytorch/api_difference/` 目录下）
+  2. 查询 PyTorch API 对应的转写配置（位于 `${ROOT_DIR}/PaConvert/paconvert/api_mapping.json` 或 `${ROOT_DIR}/PaConvert/paconvert/attribute_mapping.json`）
+  3. 通过两者的信息综合确定差异分类和对应的 Paddle API
+- **冲突处理原则**：当差异文档与转写配置的信息产生冲突时，**以转写配置为准**
+  - 转写配置反映了实际运行的代码转换逻辑，更接近真实情况
+  - 差异文档可能存在更新不及时的情况
+
+- **转写配置字段说明**：
+
+| 字段 | 说明 | 对应差异分类 |
+|------|------|------------|
+| `Matcher: "ChangePrefixMatcher"` | API 完全一致，仅框架前缀不同（torch→paddle），无需任何参数转换 | API 完全一致 |
+| `Matcher: "ChangeAPIMatcher"` | API 调用方式不同，但功能一致，无需参数转换 | 仅 API 调用方式不一致 |
+| `Matcher: "NumelMatcher"` | 特定 API（如 torch.numel）的专用转换器 | 仅 API 调用方式不一致 |
+| `Matcher: "TensorFunc2PaddleFunc"` | Tensor 类方法转为 Paddle 函数，如 `x.func()` → `paddle.func(x)` | 仅 API 调用方式不一致（无其他差异时） |
+| `Matcher: "Func2Attribute"` | 函数调用转为属性访问，如 `x.func()` → `x.attr` | 仅 API 调用方式不一致（无其他差异时） |
+| `Matcher: "Attribute2Func"` | 属性访问转为函数调用，如 `x.attr` → `x.func()` | 仅 API 调用方式不一致（无其他差异时） |
+| `Matcher: "GenericMatcher"` | 通用转换器，适用于可直接映射的 API | 仅参数名不一致 / 仅 paddle 参数更多 / 仅参数默认值不一致 / torch 参数更多|
+| `paddle_api` | 对应的 Paddle API 完整路径，如 `"paddle.transpose"` | 表示 API 映射关系|
+| `kwargs_change` | 参数名映射关系，如 `{"input": "x", "dims": "perm"}` | 仅参数名不一致 |
+| `unsupport_args` | 不支持的参数列表，如 `["generator", "layout"]` | torch 参数更多（部分不支持） |
+| `paddle_default_kwargs` | Paddle 需要设置的默认参数，如 `{"axis": -1}` | 参数默认值不一致 / paddle 参数更多 |
+| 其他自定义 `Matcher` | 除上述 Matcher 外的其他自定义 Matcher 名称 | 参数用法/类型不一致 / 组合替代实现等复杂情况 |
+
+- **注意**：
+- 当 `TensorFunc2PaddleFunc`、`Func2Attribute`、`Attribute2Func` 同时包含 `unsupport_args`、`kwargs_change` 或 `paddle_default_kwargs` 字段时，说明除了调用方式差异外，还存在其他差异，不能归类为"仅 API 调用方式不一致"
+- 更多的分类映射关系则需要自行分析，可结合 `${ROOT_DIR}/PaConvert/paconvert/api_matcher.py` 中对应 Matcher 的实现逻辑进行差异分类
+
+**备选方案：网络搜索 API 文档**
+- 如果差异文档和转写配置都无法找到，则从网络中分别搜索：
+  1. PyTorch 官方 API 文档（https://pytorch.org/docs/stable/）
+  2. Paddle 官方 API 文档（https://www.paddlepaddle.org.cn/documentation/docs/zh/api/）
+- 对比两者的 API 文档，手动分析差异，获取 API 的签名、参数、返回值等信息
+
+### 1.2 确定差异分类
 差异分类共 13 类，具体如下：
 
 | 序号 | 差异分类 | 说明 |
@@ -140,10 +177,11 @@ disable-model-invocation: false
 
 ### 1.3 提取差异信息
 
-提取相关差异信息，提供给 Step2 进行方案决策：
+总结相关差异信息，提供给 Step2 进行方案决策：
 
 | 项目 | 内容  |
 |------|------|
+| 差异分类 | 具体差异分类 |
 | API 映射 | PyTorch API vs 对应的 Paddle API（可能为空）|
 | 参数映射 | 参数对应关系和差异说明 |
 | 转写示例 | 代码转换示例 |
@@ -185,70 +223,115 @@ disable-model-invocation: false
   ↓                                  ↓
 具体有哪些差异？              方案 4（新增 API）→结束
   │
-  ├──→ API 完全一致 → 方案 6（无需改动）→结束
+  ├──→ 1. API 完全一致 → 方案 6（无需改动）→结束
+  │
+  ├──→ 2. 仅 API 调用方式不一致 → 方案 4（新增 API）→结束
+  │
+  ├──→ 3. 仅参数名不一致 → 方案 2（C++下沉）→ 不适用则方案 1→结束
+  │
+  ├──→ 4. paddle 参数更多 → 是否影响对齐？─┬→否→方案 6（无需改动）→结束
+  │                                     └→是→方案 3（修改 API）→存在兼容性则方案 5→结束
   │
-  ├──→ 仅参数名不一致 → 方案 2（C++下沉）→ 不适用则方案 1→结束
+  ├──→ 5. 参数默认值不一致 → 是否影响对齐？─┬→否→方案 6（无需改动）→结束
+  │                                     └→是→方案 3（修改 API）→存在兼容性则方案 5→结束
   │
-  ├──→ paddle 参数更多 → 是否影响对齐？─┬→否→方案 6（无需改动）→结束
-  │                                   └→是→方案 3（修改 API）→存在兼容性则方案 5→结束
+  ├──→ 6. torch 参数更多 → 仅多 out 参数？─┬→是→方案 2（C++下沉）→不适用则方案 1→结束
+  │                                    └→否→方案 3（修改 API）→存在兼容性则方案 1→无法区分则方案 5→结束
   │
-  ├──→ 参数默认值不一致 → 方案 3（修改 API）→存在兼容性则方案 5→结束
+  ├──→ 7. 输入参数用法不一致 → 方案 3（修改 API）→存在兼容性则方案 1→无法区分则方案 5→结束
   │
-  ├──→ torch 参数更多 → 仅多 out 参数？─┬→是→方案 2（C++下沉）→不适用则方案 3→存在兼容性则方案 1→无法区分则方案 5→结束
-  │                                └→否→方案 3（修改 API）→存在兼容性则方案 1→无法区分则方案 5→结束
+  ├──→ 8. 输入参数类型不一致 → 方案 3（修改 API）→存在兼容性则方案 1→无法区分则方案 5→结束
   │
-  ├──→ 输入参数用法/类型不一致 → 方案 3（修改 API）→存在兼容性则方案 1→无法区分则方案 5→结束
+  ├──→ 9. 返回参数类型不一致 → 方案 5（新增 compat 类型 API）→结束
   │
-  └──→ 返回参数类型不一致 → 方案 5（新增 compat 类型 API）→结束
+  ├──→ 10. 组合替代实现 → 方案 4（新增 API）→结束
+  │
+  ├──→ 11. 可删除 →  方案 6（无需改动）→结束
+  │
+  ├──→ 12. API 别名 → 方案 4（新增 API）→结束
+  │
+  └──→ 13. 功能缺失 → 方案 4（新增 API）→结束
 ```
 
 ### 2.4 详细决策规则
 
-**前置判断**：以下规则均基于**API 相对引用路径一致**的前提。只要 API 相对引用路径不一致，直接选择**方案 4（新增 API）**，无需进入后续判断。
+**前置判断**：分类 3~10 判定规则均基于**API 相对引用路径一致**的前提。只要 API 相对引用路径不一致，直接选择**方案 4（新增 API）**，无需进行如下判断。
 
 #### 1. API 完全一致
 - **决策**：方案 6（无需改动）
 
-#### 2. 仅参数名不一致
+#### 2. 仅 API 调用方式不一致
+- **决策**：方案 4（新增 API）
+- **说明**：API 相对引用路径不一致，但参数完全相同，需要新增 API 来实现路径对齐
+
+#### 3. 仅参数名不一致
 - **优先级 1**：方案 2（C++下沉）
-  - **适用条件**：满足方案 2 适用条件（见第三部分定义）
+  - **适用条件**：满足方案 2 适用条件（见第二部分定义）
   - **优势**：性能最优
 - **优先级 2**：方案 1（Python 装饰器）
   - **适用条件**：不满足方案 2 适用条件
 
-#### 3. paddle 参数更多
+#### 4. paddle 参数更多
 - **判断**：额外参数是否影响对齐
-  - **否**（如默认参数，Paddle 保持默认即可）→ 方案 6（无需改动）
+  - **否**（例如默认参数，Paddle 保持默认即可）→ 方案 6（无需改动）
   - **是** → 方案 3（修改 API）
     - **存在兼容性** → 方案 5（新增 compat 类型 API）
 
-#### 4. 参数默认值不一致
-- **优先级 1**：方案 3（修改 API）
-- **回退**：存在兼容性 → 方案 5（新增 compat 类型 API）
+#### 5. 参数默认值不一致
+- **判断**：不一致的默认值是否影响对齐
+  - **否**（例如不影响结果的参数）→ 方案 6（无需改动）
+  - **是** → 方案 3（修改 API）
+    - **存在兼容性** → 方案 5（新增 compat 类型 API）
 
-#### 5. torch 参数更多
+#### 6. torch 参数更多
 - **子判断**：是否仅多 out 参数
-  - **是** → 方案 2（C++下沉）
-    - **不适用** → 方案 3（修改 API）→ 存在兼容性则方案 1→ 无法区分则方案 5
-  - **否** → 方案 3（修改 API）→ 存在兼容性则方案 1→ 无法区分则方案 5
+  - **是**：
+    - **优先级 1**：方案 2（C++下沉）
+      - **适用条件**：满足方案 2 适用条件（见第二部分定义）
+      - **优势**：性能最优
+    - **优先级 2**：方案 1（Python 装饰器）
+      - **适用条件**：方案 2 不适用时
+  - **否**：
+    - **优先级 1**：方案 3（修改 API）
+      - **存在兼容性** → 方案 1（Python 装饰器）
+        - **无法区分两套签名** → 方案 5（新增 compat 类型 API）
+
+#### 7. 输入参数用法不一致
+- **优先级 1**：方案 3（修改 API）
+  - **存在兼容性** → 方案 1（Python 装饰器）
+    - **无法区分两套签名** → 方案 5（新增 compat 类型 API）
 
-#### 6. 输入参数用法/类型不一致
+#### 8. 输入参数类型不一致
 - **优先级 1**：方案 3（修改 API）
   - **存在兼容性** → 方案 1（Python 装饰器）
     - **无法区分两套签名** → 方案 5（新增 compat 类型 API）
 
-#### 7. 返回参数类型不一致
+#### 9. 返回参数类型不一致
 - **唯一决策**：方案 5（新增 compat 类型 API）
 - **原因**：
-  - ❌ 方案 3：修改返回值必然不兼容
-  - ❌ 方案 1：装饰器只能根据输入区分，无法区分返回值差异
+  - ❌ 方案 3：修改返回值必然存在兼容性问题
+  - ❌ 方案 1：装饰器只能根据输入区分两套签名，返回值不一致无法区分两套签名
   - ✅ 方案 5：在 compat 路径下新增，不影响原 API
 
-### 2.5 方案组合说明
+#### 10. 组合替代实现
+- **决策**：方案 4（新增 API）
+- **说明**：PyTorch API 需要多个 Paddle API 组合实现，通过新增 API 实现组合计算逻辑
+
+#### 11. 可删除
+- **决策**：方案 6（无需改动）
+- **说明**：PyTorch API 在 Paddle 中可直接删除，无需开发
+
+#### 12. API 别名
+- **决策**：方案 4（新增 API）
+- **说明**：为 PyTorch 别名 API 新增对应的 Paddle 别名 API
+
+#### 13. 功能缺失
+- **决策**：方案 4（新增 API）
+- **说明**：Paddle 暂无等效实现，需要新增 API 来实现该功能
+
+# 四、注意事项
 
-> **重要提醒**：一个 API 可能涉及多种差异分类，需要综合分析所有差异点，可以组合多种方案来消除所有差异点。
+1. 严格按标准工作流程执行，杜绝自行臆断和跳过步骤
+2. 所有路径使用 `${ROOT_DIR}` 变量表示根目录，需自行替换为实际路径
 
-**示例**：`torch.frexp` 存在"仅参数名不同"和"仅多 out 参数"两个差异点
-- **组合方案**：方案 3 + 方案 1
-  - 方案 3：在末尾添加 out 参数（带默认值 None），消除"仅多 out 参数"差异
-  - 方案 1：支持参数名不同的重载，消除"仅参数名不同"差异
+# 五、常见问题处理