Skip to content

Commit 3096af9

Browse files
zhwesky2010zhwesky2010
committed
[Coding Agent] Update API Compatibility Claude Code Skills
1 parent 83b8774 commit 3096af9

3 files changed

Lines changed: 199 additions & 94 deletions

File tree

  • docs/dev_guides/coding_agent/api_compatibility/.claude/skills

‎docs/dev_guides/coding_agent/api_compatibility/.claude/skills/add-new-compat-api/SKILL.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
name: add-new-compat-api
3+
description: 负责《Paddle API 对齐 PyTorch 项目》中 Step2：API 代码修改，实施『新增 compat 类型 API』方案。在 `paddle.compat` 命名空间下新增 API，实现与 PyTorch API 行为对齐。
4+
context: fork
5+
disable-model-invocation: false
6+
---
7+
8+
# 与 add-new-api 的关系
9+
10+
本文档是 **add-new-api** 的变体，核心流程完全一致，**唯一区别**是新增 API 的存放目录：
11+
12+
| 方案 | API 存放目录 | 适用场景 |
13+
|------|-------------|---------|
14+
| add-new-api | `Paddle/python/paddle/` (常规目录) | 新增 Paddle 原生 API |
15+
| add-new-compat-api | `Paddle/python/paddle/compat/` (compat 目录) | 新增兼容性 API |
16+
17+
**请直接参考 add-new-api 的 SKILL.md 完成开发**，并将所有文件路径中的 `Paddle/python/paddle/` 替换为 `Paddle/python/paddle/compat/`。
18+
19+
---
20+
21+
# 核心差异说明
22+
23+
## 实现位置映射
24+
25+
| add-new-api 路径 | add-new-compat-api 路径 |
26+
|----------------|------------------------|
27+
| `python/paddle/__init__.py` | `python/paddle/compat/__init__.py` |
28+
| `python/paddle/tensor/math.py` | `python/paddle/compat/__init__.py` |
29+
| `python/paddle/tensor/__init__.py` | `python/paddle/compat/__init__.py` |
30+
| `python/paddle/nn/__init__.py` | `python/paddle/compat/nn/__init__.py` |
31+
| `python/paddle/nn/functional/__init__.py` | `python/paddle/compat/nn/functional/__init__.py` |
32+
33+
34+
# 更多细节
35+
36+
请参考 **add-new-api** 的 SKILL.md 了解：
37+
- 三种场景的完整工作流程
38+
- 背景知识（目录组织结构等）
39+
- 注意事项
40+
- 常见问题处理

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

Lines changed: 142 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
---
22
name: api-change-decider
33
description: 负责《Paddle API 对齐 PyTorch 项目》中 Step1：方案决策，分析 PyTorch API 与 Paddle API 之间的差异，制定合适的 API 改动方案
4-
context: fork
5-
agent: Explore
64
disable-model-invocation: false
75
---
86

@@ -31,14 +29,16 @@ disable-model-invocation: false
3129
2. API 名称和 `_C_ops.xxx` 的 OP 名称一致
3230
- ✅ 正确示例：`paddle.atan` 调用 `_C_ops.atan`
3331
- ❌ 错误示例：`paddle.select_scatter` 调用 `_C_ops.set_value_with_tensor`（名称不一致）
34-
3. API 差异**仅为参数名不同或仅多 out 参数**（不涉及参数顺序或个数差异）
35-
- torch 比 paddle 恰好只多一个参数 `out`，其余参数完全一致
36-
- ✅ 符合：仅多 `out` 一个参数
37-
- ❌ 不符合：多两个及以上参数、多的参数不是 `out`、还存在参数名不同等其他差异
32+
3. API 差异**仅涉及以下情况之一或组合**：
33+
- 仅参数名不同
34+
- 仅多 out 参数
35+
- 参数名不同 + 仅多 out 参数
36+
- ❌ 不符合：多两个及以上参数、多的参数不是 `out`、涉及参数顺序差异、存在其他额外参数
37+
**说明**：当满足此条件时，参数名映射和 out 参数都在 C++ 层统一处理，无需额外组合其他方案。
3838
4. Python 实现中**仅有一次** `_C_ops.xxx` 调用
3939
5. Python 实现中不涉及其他 Paddle API 调用
40-
- ❌ **禁止**：调用任何其他 paddle API（如 `paddle.where`、`paddle.abs`、`paddle.flatten` 等）
41-
- ❌ **禁止**：调用 Tensor 方法（如 `x.flatten()`、`x.reshape()`、`x.unsqueeze()` 等，这些等同于调用 paddle API）
40+
- ❌ **禁止**：调用任何其他 paddle API（如 `paddle.where`、`paddle.abs`、`paddle.flatten`、`paddle.full`、`paddle.cast` 等）
41+
- ❌ **禁止**：调用 Tensor 方法（如 `x.flatten()`、`x.reshape()`、`x.unsqueeze()`、`x.cast()` 等，这些等同于调用 paddle API）
4242
- ❌ **禁止**：使用 `paddle.full_like`、`paddle.zeros_like`、`paddle.cast` 等
4343
- ✅ **允许**：Python 内置函数（如 `len()`、`isinstance()`、`list()`、`range()` 等）
4444
- ✅ **允许**：简单的属性访问（如 `x.shape`、`x.dtype`、`x.ndim` 等）
@@ -161,9 +161,9 @@ disable-model-invocation: false
161161
| 1 | API 完全一致 | 无差异，无需改动 |
162162
| 2 | 仅 API 调用方式不一致 | API 路径不一致，但参数完全相同 |
163163
| 3 | 仅参数名不一致 | 参数功能相同但参数名称不同 |
164-
| 4 | paddle 参数更多 | Paddle 提供更多可选参数 |
164+
| 4 | paddle 参数更多 | Paddle 支持更多参数 |
165165
| 5 | 参数默认值不一致 | 参数默认值不同 |
166-
| 6 | torch 参数更多 | PyTorch 提供更多参数 |
166+
| 6 | torch 参数更多 | PyTorch 支持更多参数 |
167167
| 7 | 输入参数用法不一致 | 参数处理方式不同 |
168168
| 8 | 输入参数类型不一致 | 参数类型要求不同 |
169169
| 9 | 返回参数类型不一致 | 返回值类型或结构不同 |
@@ -198,62 +198,153 @@ python -c "import paddle; paddle.Tensor.addmv_" # AttributeError → 路径不
198198
**输出**：记录路径一致性结果（一致/不一致），用于选择决策表。
199199

200200

201-
### 3.2 查表决策
201+
### 3.2 执行决策流程
202202

203-
根据 3.1 的路径一致性结果选择决策表：**路径不一致** → 决策表 A；**路径一致** → 决策表 B。
203+
根据 3.1 的路径一致性结果选择决策流程图：**路径不一致** → 决策流程图 A；**路径一致** → 决策流程图 B。
204204

205-
**方案切换说明**：`→` 表示「不满足当前条件则切换到下一个备选方案」。
206-
- 方案 2 → 方案 1：不满足 C++ 下沉条件
207-
- 方案 3 → 方案 1：修改会破坏后向兼容
208-
- 方案 1 → 方案 5：不满足装饰器重载条件
205+
**针对每个差异分类独立执行流程图**，得到对应方案：
206+
- 仅一个差异分类 → 直接输出该方案
207+
- 多个差异分类 → 按 3.3 规则组合
209208

210-
**决策表 A：路径不一致**（必须包含方案 4）
209+
**决策流程图 A：路径不一致**
211210

212-
| 差异分类 | 决策链（→ 备选） |
213-
|----------|------------------|
214-
| 分类 2, 10, 12, 13 | 方案 4（新增 Python 层 API 或 C++ 算子） |
215-
| 分类 3 | 方案 2 + 方案 4（新增 API 别名）→ 方案 1 + 方案 4（新增 API 别名） |
216-
| 分类 4, 5 | 不影响对齐 → 无需修改；否则 → 方案 3 + 方案 4（新增 API 别名）→ 方案 4（新增 Python 层 API） |
217-
| 分类 6 | 仅多 out 且满足方案 2 条件 → 方案 2 + 方案 4（新增 API 别名）；否则 → 方案 3 + 方案 4（新增 API 别名）→ 方案 1 + 方案 4（新增 API 别名）→ 方案 4（新增 Python 层 API） |
218-
| 分类 7, 8 | 方案 3 + 方案 4（新增 API 别名）→ 方案 1 + 方案 4（新增 API 别名）→ 方案 4（新增 Python 层 API） |
219-
| 分类 9 | 方案 4（新增 Python 层 API） |
220-
| 分类 11 | 无需修改 |
211+
```
212+
API 路径不一致
213+
│
214+
├──→ 1. API 完全一致 → 方案 4（新增 API 别名）→ 得到方案
215+
│
216+
├──→ 2. 仅 API 调用方式不一致 → 方案 4（新增 API 别名）→ 得到方案
217+
│
218+
├──→ 3. 仅参数名不一致 → 满足方案 2 条件？
219+
│ ├──→ 是 → 方案 2（C++ 下沉）+ 方案 4（新增 API 别名）→ 得到方案
220+
│ └──→ 否 → 方案 1（Python 装饰器）+ 方案 4（新增 API 别名）→ 得到方案
221+
│
222+
├──→ 4. paddle 参数更多 → 是否影响对齐？
223+
│ ├──→ 否 → 无需修改 → 得到方案
224+
│ └──→ 是 → 满足方案 3 条件？
225+
│ ├──→ 是 → 方案 3（修改原有 API）+ 方案 4（新增 API 别名）→ 得到方案
226+
│ └──→ 否 → 方案 4（新增 Python 层 API）→ 得到方案
227+
│
228+
├──→ 5. 参数默认值不一致 → 是否影响对齐？
229+
│ ├──→ 否 → 无需修改 → 得到方案
230+
│ └──→ 是 → 满足方案 3 条件？
231+
│ ├──→ 是 → 方案 3（修改原有 API）+ 方案 4（新增 API 别名）→ 得到方案
232+
│ └──→ 否 → 方案 4（新增 Python 层 API）→ 得到方案
233+
│
234+
├──→ 6. torch 参数更多
235+
│ │
236+
│ ├──→ 仅多 out 参数 → 满足方案 2 条件？
237+
│ │ ├──→ 是 → 方案 2（C++ 下沉）+ 方案 4（新增 API 别名）→ 得到方案
238+
│ │ └──→ 否 → 方案 3（修改原有 API，新增 out 参数）+ 方案 4（新增 API 别名）→ 得到方案
239+
│ │
240+
│ └──→ 多其他参数（非仅 out）→ 满足方案 3 条件？
241+
│ ├──→ 是 → 方案 3（修改原有 API）+ 方案 4（新增 API 别名）→ 得到方案
242+
│ └──→ 否 → 满足方案 1 条件？
243+
│ ├──→ 是 → 方案 1（Python 装饰器）+ 方案 4（新增 API 别名）→ 得到方案
244+
│ └──→ 否 → 方案 4（新增 Python 层 API）→ 得到方案
245+
│
246+
├──→ 7. 输入参数用法不一致 → 满足方案 3 条件？
247+
│ ├──→ 是 → 方案 3（修改原有 API）+ 方案 4（新增 API 别名）→ 得到方案
248+
│ └──→ 否 → 满足方案 1 条件？
249+
│ ├──→ 是 → 方案 1（Python 装饰器）+ 方案 4（新增 API 别名）→ 得到方案
250+
│ └──→ 否 → 方案 4（新增 Python 层 API）→ 得到方案
251+
│
252+
├──→ 8. 输入参数类型不一致 → 满足方案 3 条件？
253+
│ ├──→ 是 → 方案 3（修改原有 API）+ 方案 4（新增 API 别名）→ 得到方案
254+
│ └──→ 否 → 满足方案 1 条件？
255+
│ ├──→ 是 → 方案 1（Python 装饰器）+ 方案 4（新增 API 别名）→ 得到方案
256+
│ └──→ 否 → 方案 4（新增 Python 层 API）→ 得到方案
257+
│
258+
├──→ 9. 返回参数类型不一致 → 方案 4（新增 Python 层 API）→ 得到方案
259+
│
260+
├──→ 10. 组合替代实现 → 方案 4（新增 Python 层 API）→ 得到方案
261+
│
262+
├──→ 11. 可删除 → 无需修改 → 得到方案
263+
│
264+
├──→ 12. API 别名 → 方案 4（新增 API 别名）→ 得到方案
265+
│
266+
└──→ 13. 功能缺失 → 方案 4（新增 Python 层 API 或 C++ 算子）→ 得到方案
267+
```
221268

222-
**决策表 B：路径一致**
269+
**决策流程图 B：路径一致**
223270

224-
| 差异分类 | 决策链（→ 备选） |
225-
|----------|------------------|
226-
| 分类 1, 11 | 无需修改 |
227-
| 分类 3 | 方案 2 → 方案 1 |
228-
| 分类 4, 5 | 不影响对齐 → 无需修改；否则 → 方案 3 → 方案 5 |
229-
| 分类 6 | 仅多 out 且满足方案 2 条件 → 方案 2；否则 → 方案 3 → 方案 1 → 方案 5 |
230-
| 分类 7, 8 | 方案 3 → 方案 1 → 方案 5 |
231-
| 分类 9 | 方案 5 |
271+
```
272+
API 路径一致
273+
│
274+
├──→ 1. API 完全一致 → 无需修改 → 得到方案
275+
│
276+
├──→ 2. 仅 API 调用方式不一致 → 不可能出现（路径一致时此分类不存在）
277+
│
278+
├──→ 3. 仅参数名不一致 → 满足方案 2 条件？
279+
│ ├──→ 是 → 方案 2（C++ 下沉）→ 得到方案
280+
│ └──→ 否 → 方案 1（Python 装饰器）→ 得到方案
281+
│
282+
├──→ 4. paddle 参数更多 → 是否影响对齐？
283+
│ ├──→ 否 → 无需修改 → 得到方案
284+
│ └──→ 是 → 满足方案 3 条件？
285+
│ ├──→ 是 → 方案 3（修改原有 API）→ 得到方案
286+
│ └──→ 否 → 方案 5（新增 compat 类型 API）→ 得到方案
287+
│
288+
├──→ 5. 参数默认值不一致 → 是否影响对齐？
289+
│ ├──→ 否 → 无需修改 → 得到方案
290+
│ └──→ 是 → 满足方案 3 条件？
291+
│ ├──→ 是 → 方案 3（修改原有 API）→ 得到方案
292+
│ └──→ 否 → 方案 5（新增 compat 类型 API）→ 得到方案
293+
│
294+
├──→ 6. torch 参数更多
295+
│ │
296+
│ ├──→ 仅多 out 参数 → 满足方案 2 条件？
297+
│ │ ├──→ 是 → 方案 2（C++ 下沉）→ 得到方案
298+
│ │ └──→ 否 → 方案 3（修改原有 API，新增 out 参数）→ 得到方案
299+
│ │
300+
│ └──→ 多其他参数（非仅 out）→ 满足方案 3 条件？
301+
│ ├──→ 是 → 方案 3（修改原有 API）→ 得到方案
302+
│ └──→ 否 → 满足方案 1 条件？
303+
│ ├──→ 是 → 方案 1（Python 装饰器）→ 得到方案
304+
│ └──→ 否 → 方案 5（新增 compat 类型 API）→ 得到方案
305+
│
306+
├──→ 7. 输入参数用法不一致 → 满足方案 3 条件？
307+
│ ├──→ 是 → 方案 3（修改原有 API）→ 得到方案
308+
│ └──→ 否 → 满足方案 1 条件？
309+
│ ├──→ 是 → 方案 1（Python 装饰器）→ 得到方案
310+
│ └──→ 否 → 方案 5（新增 compat 类型 API）→ 得到方案
311+
│
312+
├──→ 8. 输入参数类型不一致 → 满足方案 3 条件？
313+
│ ├──→ 是 → 方案 3（修改原有 API）→ 得到方案
314+
│ └──→ 否 → 满足方案 1 条件？
315+
│ ├──→ 是 → 方案 1（Python 装饰器）→ 得到方案
316+
│ └──→ 否 → 方案 5（新增 compat 类型 API）→ 得到方案
317+
│
318+
├──→ 9. 返回参数类型不一致 → 方案 5（新增 compat 类型 API）→ 得到方案
319+
│
320+
├──→ 10. 组合替代实现 → 不可能出现（路径一致时此分类不存在）
321+
│
322+
├──→ 11. 可删除 → 无需修改 → 得到方案
323+
│
324+
├──→ 12. API 别名 → 不可能出现（路径一致时此分类不存在）
325+
│
326+
└──→ 13. 功能缺失 → 不可能出现（路径一致时此分类不存在）
327+
```
232328

233329

234330
### 3.3 多差异分类组合决策
235331

236-
当 API 存在多个差异分类时，**逐个差异分类独立查表，再合并方案**。
237-
238-
**步骤 1**：遍历每个差异分类，根据决策表独立查表得到对应方案。
332+
当 API 存在多个差异分类时，**逐个差异分类独立查决策流程图，再合并方案**。
239333

240-
**步骤 2**：对多个方案执行合并。
334+
**合并规则**：
241335

242-
| 规则 | 判断条件 | 操作 |
243-
|------|----------|------|
336+
| 规则 | 条件 | 操作 |
337+
|------|------|------|
244338
| 去重 | 多个差异分类对应相同方案 | 只保留一个 |
245339
| 互斥 | 方案 2 与方案 1 同时出现 | 仅保留方案 2 |
246340
| 组合 | 不同方案且不互斥 | 按编号升序，用 `+` 连接 |
247341

248-
**步骤 3**：输出最终组合方案。
249-
250342
**示例**：
251343

252-
| API | 差异分类 | 查表结果 | 合并结果 |
344+
| API | 差异分类 | 查流程图结果 | 合并结果 |
253345
|-----|----------|----------|----------|
254-
| torch.atan | 分类 3 + 分类 6 | 分类 3 → 方案 2；分类 6 → 方案 2 | 方案 2（去重） |
255-
| torch.logspace | 分类 3 + 分类 6 | 分类 3 → 方案 1；分类 6 → 方案 3 | 方案 3 + 方案 1 |
256-
| torch.histc | 分类 2 + 分类 6 + 分类 9 | 分类 2 → 方案 4；分类 6 → 方案 4；分类 9 → 方案 4 | 方案 4（去重） |
346+
| torch.atan | 参数名不一致 + torch 参数更多（仅多 out 参数） | 参数名不一致 → 方案 2；torch 参数更多（仅多 out 参数） → 方案 2 | 方案 2（去重） |
347+
| torch.logspace | 参数名不一致 + torch 参数更多 | 参数名不一致 → 方案 1；torch 参数更多 → 方案 3 | 方案 3 + 方案 1 |
257348

258349

259350
# 三、输出要求
@@ -298,14 +389,14 @@ python -c "import paddle; paddle.Tensor.addmv_" # AttributeError → 路径不
298389
299390
**差异分析**
300391
- API 路径一致性：一致
301-
- 差异分类：参数名不一致 + torch 参数更多
392+
- 差异分类：参数名不一致 + torch 参数更多（仅多 out 参数）
302393
- 具体差异：
303394
- 参数名映射：`input → x`
304395
- 额外参数：torch 多出 `out`
305396
306397
**方案决策**
307398
- 选择方案：方案 2（C++ 下沉）
308-
- 决策依据：API 路径一致；仅参数名不同 + 多 out 参数，且满足 C++ 下沉全部条件。
399+
- 决策依据：API 路径一致；差异为"参数名不同 + 仅多 out 参数"，满足方案 2 条件 3；且满足 C++ 下沉全部其他条件（调用 `_C_ops.atan`、无其他 Paddle API 调用、无复杂前处理）。
309400
```
310401

311402
**示例 2：组合方案**
@@ -320,15 +411,15 @@ python -c "import paddle; paddle.Tensor.addmv_" # AttributeError → 路径不
320411
321412
**差异分析**
322413
- API 路径一致性：一致
323-
- 差异分类：参数名不一致 + torch 参数更多
414+
- 差异分类：参数名不一致 + torch 参数更多（多 out/device/requires_grad 等参数）
324415
- 具体差异：
325416
- 参数名映射：`end → stop, steps → num`
326417
- 额外参数：torch 多出 `out, device, requires_grad`
327418
328419
**方案决策**
329420
- 选择方案：方案 3 + 方案 1
330421
- 决策依据：API 路径一致；新增 out/device/requires_grad 参数可保持后向兼容；参数名差异需通过装饰器适配。
331-
- 组合说明：方案 3 处理 torch 参数更多；方案 1 处理参数名不一致。
422+
- 组合说明：方案 3 处理 torch 参数更多（新增参数）；方案 1 处理参数名不一致。
332423
```
333424

334425
# 四、注意事项

0 commit comments

Comments
 (0)