add python-decorator agent rules

docs/dev_guides/coding_agent_rules/api_compatibility/0-api-compatibility.mdr

@@ -8,7 +8,7 @@ alwaysApply: false
 
 你是《Paddle API对齐PyTorch项目》的**主控智能体**，负责统筹全流程的工作，调用多个子智能体，最终完成输入的所有API对齐。
 
-## 核心职责
+**核心职责**：
 1. 接收待对齐的Pytorch API列表
 2. 为对应的Paddle API决策改动方案
 3. 执行具体的Paddle API修改
@@ -70,7 +70,7 @@ torch.logsumexp
 |Paddle API兼容性单测位置|`test_api_compatibility.py`|Paddle/test/legacy_test/test_api_compatibility.py||
 |Pytorch API单测位置|`test_{api_name}.py`|PaConvert/tests/|PaConvert/tests/test_tan.py||
 
-## 4.2 Paddle API架构（5层调用栈）
+## 4.3 Paddle API架构（5层调用栈）
 
 Paddle API从上到下由5层组成（本项目直接修改第1、5层，对于第2~4层通常是修改yaml配置文件，例如python_api_info.yaml）：
 
@@ -100,7 +100,7 @@ Tensor atan(const Tensor& x, ...)
 void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 ```
 
-## 4.3 专业术语表
+## 4.4 专业术语表
 
 | 术语 | 定义 | 备注 |
 |------|------|------|
@@ -119,20 +119,20 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 
 # 五、代码修改规范
 
-## 1. 代码注释规范
+## 5.1 代码注释规范
 - ✅ 改动的位置如果方便注释，可以注释`# Edit by AI Agent`，表明这是你完成的工作
 
-## 2. 代码质量规范
+## 5.2 代码质量规范
 - ✅ 保持代码风格与项目一致
 - ✅ 不破坏现有功能
 - ✅ 确保向后兼容性
 
-## 3. 测试规范
+## 5.3 测试规范
 - ✅ 修改后必须通过原有测试
 - ✅ 必须添加新的单元测试
 - ✅ 必须通过PyTorch对齐验证
 
-## 4. 文档规范
+## 5.4 文档规范
 - ✅ 同步更新中文文档
 - ✅ 文档格式符合Paddle规范
 - ✅ 准确描述API功能和参数
@@ -155,7 +155,7 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
    - Step4：对**所有API**更新文档
 3. **流程推进的豁免与放弃条件**：
    - **豁免条件**（跳过后续步骤，但记录决策结果）：
-     * 非方案2：若决策不为方案2，则该API跳过后续Step2~4，无需自行处理
+     * 若决策不为方案1/2，则该API跳过后续Step2~4，无需自行处理
    - **放弃策略**（合理分配精力，最大化成功率）：
      * **放弃判断标准**：
        - 当某个API在Step2或Step3经过多次尝试（建议3次）仍无法通过验证
@@ -179,7 +179,7 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 
 **执行步骤**：
 1. 输入：需要对齐的PyTorch API列表（如 `torch.atan`、`torch.asinh`）
-2. 调用 `API改动方案决策智能体`
+2. 严格执行1-scheme-decision.mdr，如果你找不到该文件，请直接结束会话，并告知我异常
 3. 输出：方案类型、对应Paddle API、差异分类、决策依据
 
 **方案类型**：
@@ -197,7 +197,7 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 **执行步骤**：
 1. 输入：方案类型、对应Paddle API（如 `paddle.atan`、`paddle.asinh`）、差异分类、决策依据
 2. 根据方案类型，调用对应的子智能体，每个子智能体批量处理其所负责的API：
-   - 方案1 → `Python装饰器智能体`（豁免）
+   - 方案1 → `Python装饰器智能体`
    - 方案2 → `Cpp下沉智能体`
    - 方案3 → `修改API智能体`（豁免）
    - 方案4 → `新增API智能体`（豁免）
@@ -234,8 +234,6 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 
 ## 6.3 重要约束 ⚠️
 
-### 执行原则
-
 1. **流程正向推进原则**
    - 正常情况下必须遵循 Step1 → Step2 → Step3 → Step4 的顺序
    - 每个步骤完成并验证通过后，才能进入下一步骤
@@ -270,11 +268,10 @@ void AtanKernel(const Context& dev_ctx, const DenseTensor& x, DenseTensor* out)
 
 | 序号 | 智能体名称 | 负责步骤 | 主要职责 | 对应方案 |
 |------|-----------|---------|---------|---------|
-| 1 | **API改动方案决策智能体** | Step 1 | 通过API差异分析，决策API的兼容修改方案 | - |
-| 2 | **Python装饰器智能体**(暂未实现) | Step 2 | 通过装饰器对齐参数签名 | 方案1：Python装饰器 |
-| 3 | **Cpp下沉智能体** | Step 2 | 将API从Python层下沉到C++层 | 方案2：C++下沉 |
-| 4 | **修改API智能体**(暂未实现) | Step 2 | 修改现有API实现 | 方案3：修改API方案 |
-| 5 | **新增API智能体**(暂未实现) | Step 2 | 新增缺失的API | 方案4：新增API方案 |
-| 6 | **新增compat类型API智能体**(暂未实现) | Step 2 | 添加兼容性API | 方案5：新增compat方案 |
-| 7 | **Pytorch对齐验证智能体** | Step 3 | 验证修改后的Paddle API能与PyTorch API完全对齐 | - |
-| 8 | **API文档修改智能体** | Step 4 | 更新Paddle API中文文档 | - |
+| 1 | **Python装饰器智能体** | Step 2 | 通过装饰器对齐参数签名 | 方案1：Python装饰器 |
+| 2 | **Cpp下沉智能体** | Step 2 | 将API从Python层下沉到C++层 | 方案2：C++下沉 |
+| 3 | **修改API智能体**(暂未实现) | Step 2 | 修改现有API实现 | 方案3：修改API方案 |
+| 4 | **新增API智能体**(暂未实现) | Step 2 | 新增缺失的API | 方案4：新增API方案 |
+| 5 | **新增compat类型API智能体**(暂未实现) | Step 2 | 添加兼容性API | 方案5：新增compat方案 |
+| 6 | **Pytorch对齐验证智能体** | Step 3 | 验证修改后的Paddle API能与PyTorch API完全对齐 | - |
+| 7 | **API文档修改智能体** | Step 4 | 更新Paddle API中文文档 | - |

docs/dev_guides/coding_agent_rules/api_compatibility/1-scheme-decision.mdr

@@ -1,5 +1,5 @@
 ---
-description: API改动方案决策智能体
+description: API改动方案决策规则
 globs:
 alwaysApply: false
 ---
@@ -11,10 +11,10 @@ alwaysApply: false
 # 二、输入输出规范
 
 ## 2.1 输入
-- 需要对齐的PyTorch API列表（如 `torch.atan`、`torch.asinh`）
+需要对齐的PyTorch API列表（如 `torch.atan`、`torch.asinh`）
 
 ## 2.2 输出
-- 方案类型、对应Paddle API、差异分类、决策依据（以表格形式展示）
+方案类型、对应Paddle API、差异分类、决策依据（以表格形式展示）
 
 ## 2.3 输出内容
 输出应包含如下内容，以表格式形式展示：
@@ -36,9 +36,6 @@ alwaysApply: false
 |torch.frexp|方案3+方案1|paddle.frexp|torch参数更多|API相对引用路径一致，差异为：1）仅参数名不同（input→x）；2）仅多out参数。当前Python实现包含多个paddle操作调用（abs、floor、log2等），逻辑较复杂，不满足C++下沉条件。选择方案3修改API，在末尾添加out参数（带默认值None），保持后向兼容。同时方案1支持参数名不同的重载情况。|
 ```
 
-## 2.5 工作目标
-**核心目标**：决策修改方案，使Paddle API能与PyTorch API完全对齐一致。
-
 # 三、候选方案
 
 ## 方案1：Python装饰器
@@ -120,9 +117,9 @@ alwaysApply: false
 
 # 四、标准工作流程
 
-## Step 1: 读取差异文档
+## Step 1: 分析差异文档
 
-### 1.1 文档获取要求
+### 1.1 获取差异文档
 务必找到每个PyTorch API对应的API差异文档（`torch.{api_name}.md`），如果实在无法找到差异文档，则差异分类直接视作『API完全一致』。
 
 ### 1.2 差异分类定义
@@ -144,28 +141,28 @@ alwaysApply: false
 | 12 | API别名 | PyTorch API是其他API的别名 |
 | 13 | 功能缺失 | Paddle暂无等效实现 |
 
-## Step 2: 识别差异分类
+### 1.3 提取差异信息
 
-从差异文档中提取：
+提取相关差异信息，提供给Step2进行方案决策：
 
 | 项目 | 内容  |
 |------|------|
 | API映射 | PyTorch API vs 对应的Paddle API（可能为空）|
 | 参数映射 | 参数对应关系和差异说明（忽略paddle的 `name` 参数，`name` 参数无意义） |
 | 转写示例 | 代码转换示例 |
 
-## Step 3: 决策流程
+## Step 2: 方案决策
 
-### 3.1 关键概念
+### 2.1 关键概念
 
 **API相对引用路径**：API完整路径在去掉框架导入模块(torch/paddle)后剩余的部分
 - 示例：`torch.nn.functional.dropout` 的API相对引用路径是 `nn.functional.dropout`
 - 示例：`paddle.nn.functional.dropout` 的API相对引用路径是 `nn.functional.dropout`
 - 示例：`torch.Tensor.tile` 的API相对引用路径是 `Tensor.tile`
 
-### 3.2 关键执行原则
+### 2.2 关键原则
 
-> **⚠️ 严格执行原则**：决策时必须严格遵守以下原则，不得主观臆断：
+> **⚠️ 严格遵循**：决策时必须严格遵守以下原则，不得主观臆断：
 >
 > 1. **API相对引用路径不一致 → 必须方案4（新增API）**
 >    - 只要API相对引用路径不一致，直接选择方案4，无需再分析其他因素
@@ -176,79 +173,77 @@ alwaysApply: false
 >    - 严格按照各方案的适用条件判断
 >    - 不得因"可以"、"应该"等主观判断偏离规则定义
 
-### 3.3 决策流程图
+### 2.3 决策流程图
 
 ```
 开始
   │
-  ├─→ API相对引用路径是否一致？
-  │    ├─ 否 → 方案4（新增API）→ 结束
-  │    └─ 是 ↓
-  │         │
-  │         └─→ 具体有哪些差异？
-  │              │
-  │              ├─ API完全一致 → 方案6（无需改动）→ 结束
-  │              │
-  │              ├─ 仅参数名不一致 → 方案2（C++下沉）→ 不适用则方案1→ 结束
-  │              │
-  │              ├─ paddle参数更多 → 是否影响对齐？
-  │              │                          ├─ 否 → 方案6（无需改动）→ 结束
-  │              │                          └─ 是 → 方案3（修改API）→ 存在兼容性则方案5→ 结束
-  │              │
-  │              ├─ 参数默认值不一致 → 方案3（修改API）→ 存在兼容性则方案5→ 结束
-  │              │
-  │              ├─ torch参数更多 → 仅多out参数？
-  │              │                          ├─ 是 → 方案2（C++下沉）→ 不适用则方案3→ 存在兼容性则方案1→ 无法区分则方案5→ 结束
-  │              │                          └─ 否 → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5→ 结束
-  │              │
-  │              ├─ 输入参数用法/类型不一致 → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5→ 结束
-  │              │
-  │              └─ 返回参数类型不一致 → 方案5（新增compat类型API）→ 结束
+  ├───→ API相对引用路径是否一致？ ──────┐
+  │                                  │
+  │是                                │否
+  ↓                                  ↓
+具体有哪些差异？              方案4（新增API）→结束
+  │
+  ├──→ API完全一致 → 方案6（无需改动）→结束
+  │
+  ├──→ 仅参数名不一致 → 方案2（C++下沉）→ 不适用则方案1→结束
+  │
+  ├──→ paddle参数更多 → 是否影响对齐？─┬→否→方案6（无需改动）→结束
+  │                                   └→是→方案3（修改API）→存在兼容性则方案5→结束
+  │
+  ├──→ 参数默认值不一致 → 方案3（修改API）→存在兼容性则方案5→结束
+  │
+  ├──→ torch参数更多 → 仅多out参数？─┬→是→方案2（C++下沉）→不适用则方案3→存在兼容性则方案1→无法区分则方案5→结束
+  │                                └→否→方案3（修改API）→存在兼容性则方案1→无法区分则方案5→结束
+  │
+  ├──→ 输入参数用法/类型不一致 → 方案3（修改API）→存在兼容性则方案1→无法区分则方案5→结束
+  │
+  └──→ 返回参数类型不一致 → 方案5（新增compat类型API）→结束
 ```
 
-### 3.4 详细决策规则
+### 2.4 详细决策规则
 
 **前置判断**：以下规则均基于**API相对引用路径一致**的前提。只要API相对引用路径不一致，直接选择**方案4（新增API）**，无需进入后续判断。
 
-#### 3.3.1 API完全一致
+#### 1. API完全一致
 - **决策**：方案6（无需改动）
 
-#### 3.3.2 仅参数名不一致
+#### 2. 仅参数名不一致
 - **优先级1**：方案2（C++下沉）
   - **适用条件**：满足方案2适用条件（见第三部分定义）
   - **优势**：性能最优
 - **优先级2**：方案1（Python装饰器）
   - **适用条件**：不满足方案2适用条件
 
-#### 3.3.3 paddle参数更多
+#### 3. paddle参数更多
 - **判断**：额外参数是否影响对齐
   - **否**（如默认参数，Paddle保持默认即可）→ 方案6（无需改动）
   - **是** → 方案3（修改API）
     - **存在兼容性** → 方案5（新增compat类型API）
 
-#### 3.3.4 参数默认值不一致
+#### 4. 参数默认值不一致
 - **优先级1**：方案3（修改API）
 - **回退**：存在兼容性 → 方案5（新增compat类型API）
 
-#### 3.3.5 torch参数更多
+#### 5. torch参数更多
 - **子判断**：是否仅多out参数
   - **是** → 方案2（C++下沉）
     - **不适用** → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5
   - **否** → 方案3（修改API）→ 存在兼容性则方案1→ 无法区分则方案5
 
-#### 3.3.6 输入参数用法/类型不一致
+#### 6. 输入参数用法/类型不一致
 - **优先级1**：方案3（修改API）
   - **存在兼容性** → 方案1（Python装饰器）
     - **无法区分两套签名** → 方案5（新增compat类型API）
 
-#### 3.3.7 返回参数类型不一致
+#### 7. 返回参数类型不一致
 - **唯一决策**：方案5（新增compat类型API）
 - **原因**：
   - ❌ 方案3：修改返回值必然不兼容
   - ❌ 方案1：装饰器只能根据输入区分，无法区分返回值差异
   - ✅ 方案5：在compat路径下新增，不影响原API
 
-### 3.5 方案组合说明
+### 2.5 方案组合说明
 
 > **重要提醒**：一个API可能涉及多种差异分类，需要综合分析所有差异点，可以组合多种方案来消除所有差异点。