add python-decorator agent rules #7687

zhwesky2010 · 2026-01-20T14:36:17Z

Python装饰器智能体编程规则

paddle-bot · 2026-01-20T14:36:34Z

感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-7687.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明，请参考：飞桨文档预览工具

Copilot

Pull request overview

This pull request adds comprehensive documentation for the Python decorator agent rules used in Paddle API compatibility work with PyTorch. The PR introduces a new detailed guide and updates references in existing documentation.

Changes:

Adds a complete 597-line Python decorator agent guide (2-1-python-decorator.mdr) covering decorator types, workflows, testing, and best practices
Updates C++ sink agent guide (2-2-sink-to-cpp.mdr) to refine section headers and add test coverage for out parameter
Updates the main API compatibility guide (0-api-compatibility.mdr) to reflect that Python decorator agent is now implemented (removing "暂未实现" status)

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 29 comments.

File	Description
`docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr`	New comprehensive guide for Python decorator approach to API compatibility, including decorator selection, implementation patterns, testing requirements, and troubleshooting
`docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr`	Simplified section headers, removed redundant notes, and added test coverage for `out` parameter in compatibility tests
`docs/dev_guides/coding_agent_rules/api_compatibility/0-api-compatibility.mdr`	Updated Python decorator agent status from "not implemented" to active, adjusted exemption conditions to include both schemes 1 and 2

Comments suppressed due to low confidence (1)

docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr:16

中英文之间需要使用空格分隔。根据文档规范，"消除Python层逻辑开销" 应改为 "消除 Python 层逻辑开销"，"在C++层高效解析位置参数和关键字参数" 应改为 "在 C++ 层高效解析位置参数和关键字参数"，"自动完成Paddle与Torch API参数别名的映射转换" 应改为 "自动完成 Paddle 与 Torch API 参数别名的映射转换"，"C++层原生支持默认参数" 应改为 "C++ 层原生支持默认参数"。

- **性能提升**：消除Python层逻辑开销
- **参数解析**：在C++层高效解析位置参数和关键字参数
- **参数映射**：自动完成Paddle与Torch API参数别名的映射转换
- **默认值处理**：C++层原生支持默认参数
- **灵活扩展**：支持自定义参数处理逻辑

Copilot · 2026-01-20T14:41:47Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+
+## Step 1: 选择装饰器
+
+根据PyTorch API与Paddle API的**差异分析**来选择装饰器：


中英文之间需要使用空格分隔。根据文档规范，"根据PyTorch API与Paddle API的" 应改为 "根据 PyTorch API 与 Paddle API 的"。

Copilot · 2026-01-20T14:41:48Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+1. **不要修改sparse目录下的API**
+2. **确保不破坏现有功能**
+3. **保持向后兼容性**
+4. **优先使用通用装饰器以获得更好性能**
+5. **开发专用装饰器时参考现有实现**
+6. **out参数必须作为keyword-only参数**


中英文之间需要使用空格分隔。根据文档规范，"不要修改sparse目录下的API" 应改为 "不要修改 sparse 目录下的 API"，"out参数必须作为keyword-only参数" 应改为 "out 参数必须作为 keyword-only 参数"。

Copilot · 2026-01-20T14:41:48Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+
+# 二、现有装饰器体系
+
+Paddle现有装饰器统一位于 `Paddle/python/paddle/utils/decorator_utils.py`，按功能分为两类：


中英文之间需要使用空格分隔。根据文档规范，"Paddle现有装饰器" 应改为 "Paddle 现有装饰器"。

Copilot · 2026-01-20T14:41:48Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+```
+
+**注意事项**：
+- Alias说明应放在参数描述的末尾


中英文之间需要使用空格分隔。根据文档规范，"Alias说明应放在参数描述的末尾" 应改为 "Alias 说明应放在参数描述的末尾"。

Copilot · 2026-01-20T14:41:48Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+## Paddle API分层结构
+
+**Paddle API架构（5层）**：
+1. **Python层**：Python函数定义（本方案修改层）
+2. **Pybind层**：Python与C++绑定（自动生成）
+3. **Dygraph层**：动态图前反向传播组合（自动生成）
+4. **C++ API层**：Kernel选择调度（自动生成）
+5. **Kernel层**：实际计算逻辑实现（C++）


中英文之间需要使用空格分隔。根据文档规范，"Paddle API分层结构" 应改为 "Paddle API 分层结构"，"Paddle API架构（5层）" 应改为 "Paddle API 架构（5 层）"，"Python层" 应改为 "Python 层"，"Python函数定义" 应改为 "Python 函数定义"，"Pybind层" 应改为 "Pybind 层"，"Python与C++绑定" 应改为 "Python 与 C++ 绑定"，"Dygraph层" 应改为 "Dygraph 层"，"C++ API层" 应改为 "C++ API 层"，"Kernel选择调度" 应改为 "Kernel 选择调度"，"Kernel层" 应改为 "Kernel 层"，"实际计算逻辑实现（C++）" 应改为 "实际计算逻辑实现（C++）"。

Copilot · 2026-01-20T14:41:54Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+
+## Step 4: 更新文档
+
+在函数文档字符串中为有别名的参数添加Alias Support说明：


中英文之间需要使用空格分隔。根据文档规范，"在函数文档字符串中为有别名的参数添加Alias Support说明" 应改为 "在函数文档字符串中为有别名的参数添加 Alias Support 说明"。

Copilot · 2026-01-20T14:41:54Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr


 # 一、角色定义

 你擅长《Paddle API对齐PyTorch项目》中的**C++下沉方案**的代码开发。通过将Python API下沉至C++层，可以减少Python装饰器带来的性能开销，提升API调度效率。


中英文之间需要使用空格分隔。根据文档规范，"通过将Python API下沉至C++层" 应改为 "通过将 Python API 下沉至 C++ 层"，"可以减少Python装饰器带来的性能开销" 应改为 "可以减少 Python 装饰器带来的性能开销"，"提升API调度效率" 应改为 "提升 API 调度效率"。

Copilot · 2026-01-20T14:41:54Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+- **适用面广**：支持灵活处理多种重载情况：参数名不同、参数顺序不同、参数个数不同、参数类型不同
+- **向后兼容**：保持Paddle原有API调用方式
+- **开发效率**：相比C++下沉方案，修改更快速直接
+- **性能开销**：Python装饰器层会引入轻微性能开销


中英文之间需要使用空格分隔。根据文档规范，"Python装饰器层会引入轻微性能开销" 应改为 "Python 装饰器层会引入轻微性能开销"。

Copilot · 2026-01-20T14:41:54Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-1-python-decorator.mdr

+## 特点
+- **零侵入性**：无需修改API的C++底层代码
+- **适用面广**：支持灵活处理多种重载情况：参数名不同、参数顺序不同、参数个数不同、参数类型不同
+- **向后兼容**：保持Paddle原有API调用方式


中英文之间需要使用空格分隔。根据文档规范，"保持Paddle原有API调用方式" 应改为 "保持 Paddle 原有 API 调用方式"。

Copilot · 2026-01-20T14:41:55Z

docs/dev_guides/coding_agent_rules/api_compatibility/2-2-sink-to-cpp.mdr

        out5 = x.log2()
        paddle_dygraph_out.append(out5)

+        # 测试out参数


中英文之间需要使用空格分隔。根据文档规范，"测试out参数" 应改为 "测试 out 参数"。

add python-decorator agent rules

0046d1b

Copilot AI review requested due to automatic review settings January 20, 2026 14:36

Copilot started reviewing on behalf of zhwesky2010 January 20, 2026 14:36 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

Add python-decorator agent rule and update other agent rule

3b88c70

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add python-decorator agent rules #7687

add python-decorator agent rules #7687

zhwesky2010 commented Jan 20, 2026 •

edited

Loading

Uh oh!

paddle-bot bot commented Jan 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Copilot AI Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		## Step 1: 选择装饰器

		根据PyTorch API与Paddle API的差异分析来选择装饰器：


		# 二、现有装饰器体系

		Paddle现有装饰器统一位于 `Paddle/python/paddle/utils/decorator_utils.py`，按功能分为两类：


		## Step 4: 更新文档

		在函数文档字符串中为有别名的参数添加Alias Support说明：


		# 一、角色定义

		你擅长《Paddle API对齐PyTorch项目》中的C++下沉方案的代码开发。通过将Python API下沉至C++层，可以减少Python装饰器带来的性能开销，提升API调度效率。

add python-decorator agent rules #7687

Are you sure you want to change the base?

add python-decorator agent rules #7687

Conversation

zhwesky2010 commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paddle-bot bot commented Jan 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

zhwesky2010 commented Jan 20, 2026 •

edited

Loading