update cuda_stream and other docs

.claude/skills/compat-doc-authoring/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: compat-doc-authoring
+description: '编写或更新 Paddle 与 PyTorch C++ API 兼容性文档。Use when: 添加兼容文档、补充 API 对比表、补全兼容性统计、拆分 typeid 类级文档、统一文档格式。'
+argument-hint: '要编写的头文件或模块，例如 typeid.h、Stream.h、TensorBase.h'
+---
+
+# 兼容性文档编写技能
+
+面向 `doc/` 目录的 API 兼容文档生产与维护流程，目标是输出可审阅、可追踪、可统计的对比文档。
+
+## 何时使用
+
+- 需要新增某个头文件的兼容性文档
+- 需要补齐/修订已有文档的 API 对比表
+- 需要给文档增加或修正“兼容性统计”
+- 需要把一个大文档拆成多个类级文档（如 `typeid`）
+- 需要统一文档格式到 `TensorBase` 风格
+
+## 输入与产出
+
+### 输入
+
+1. 对比源文件路径（Paddle compat 与 PyTorch 原生）
+2. 文档目标路径（通常在 `doc/`）
+3. 用户的格式约束（例如“每个函数都要注释实现差异”）
+
+### 产出
+
+1. 结构化 Markdown 文档
+2. API 对比表（按模块分组）
+3. 兼容性统计表（`✅/🔧/❌`）
+4. 关键差异说明与建议测试点（如用户需要）
+
+## 标准模板（推荐）
+
+1. 标题：`<HeaderName> 头文件 API 兼容性`
+2. 对比文件列表（Paddle / Torch）
+3. 状态说明（`✅/🔧/❌`）
+4. 分组表格（按构造、访问器、静态函数、宏等）
+5. `### 兼容性统计`
+6. `### 备注`（可选）
+
+表格列默认：
+
+| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
+|---|---|---|---|---|
+
+## 工作流程
+
+### Step 1. 先读代码再写文档
+
+1. 读取 Paddle compat 头文件（必要时包含 `.cpp`）
+2. 读取 PyTorch 对应头文件（必要时包含 `.cpp`）
+3. 列出 API 清单（函数、运算符、模板、宏、类型别名）
+
+### Step 2. 建立分组与差异模型
+
+1. 按“构造/访问/静态 helper/宏与注册/运算符”分组
+2. 对每个 API 标注状态：
+   - `✅`：接口与语义一致
+   - `🔧`：接口在，但实现路径或边界行为不同
+   - `❌`：Torch 有、Paddle 缺失
+3. 在备注中写清：
+   - 实现方式是否一致
+   - 语义是否一致
+   - 若不同，具体如何实现
+
+### Step 3. 写入文档
+
+1. 新文档：按模板完整创建
+2. 旧文档：只做必要改动，避免重排无关内容
+3. 如果用户要求“每个类单独文档”：
+   - 为每个类创建独立 `*.md`
+   - 增加索引文档（如 `README.md`）
+
+### Step 4. 兼容性统计回填
+
+1. 统计口径：按文档中 API 对比表逐行计数
+2. 统计表固定格式：
+
+```markdown
+### 兼容性统计
+
+| 状态 | 数量 |
+|---|---|
+| ✅ 已实现 | N1 |
+| 🔧 部分兼容 | N2 |
+| ❌ 未实现 | N3 |
+```
+
+3. 若是索引文档：标注“汇总统计”，并说明口径来源
+
+### Step 5. 强制完成校验
+
+以下任一项不满足，任务不得结束：
+
+1. 文档中存在 `### 兼容性统计`
+2. 统计值与表格行数一致（可复算）
+3. 对比文件路径正确且可访问
+4. `🔧` 条目都解释了“差异在哪里”
+5. 无明显过时描述（如“未接入”但代码已接入）
+
+## 决策与分支
+
+### 分支 A：只有头文件差异
+
+- 只对比 `.h`
+- 备注写“仅基于声明”
+
+### 分支 B：行为依赖实现文件
+
+- 同时对比 `.cpp`
+- 在备注明确“实现位于 `.cpp`”
+
+### 分支 C：用户要求快速补齐统计
+
+- 不改正文，优先补 `### 兼容性统计`
+- 以现有表格行为统计基准
+- 必须完成统计复算后再结束
+
+### 分支 D：用户要求深度重构文档
+
+- 先出拆分方案（目录与文件映射）
+- 再分批落地，最后统一索引
+
+## 质量标准
+
+1. 可审阅：每个差异都有落点说明
+2. 可验证：统计表可由行数复算
+3. 可维护：结构稳定、命名统一、索引清晰
+4. 可复用：同一模板可直接用于下一个头文件
+
+## 推荐触发词示例
+
+- “给 `xxx.h` 写兼容文档”
+- “补齐这个文档的兼容性统计并复算”
+- “按 TensorBase 风格重写文档”
+- “把 typeid 文档拆成每个类一个文件”

.github/skills/add-compat-api/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: add-compat-api
+description: '循环新增 Paddle 对 PyTorch C++ 兼容接口。Use when: 有新增 PyTorch C++ API 需求时，在 Paddle compat 层新增接口与测试，并执行双仓编译、ctest、wheel 安装和回归验证。'
+argument-hint: '传入 Paddle 仓库路径与 PyTorch 仓库路径（可选：PaddleCppAPITest 路径）'
+---
+
+# Add Compat API Loop
+
+用于在 Paddle 兼容层中持续新增 PyTorch C++ API：
+先补测试，再实现新接口，持续编译和回归，直到新增接口相关用例通过。
+
+## 输入参数
+
+- `PADDLE_ROOT`: Paddle 仓库路径，例如 `~/Paddle`
+- `PYTORCH_ROOT`: PyTorch 仓库路径，例如 `~/pytorch`
+- `PCAT_ROOT`: PaddleCppAPITest 路径，默认 `~/PaddleCppAPITest`
+- `TORCH_DIR`: libtorch 路径，默认 `~/libtorch`
+
+建议先设置：
+
+```bash
+PADDLE_ROOT=~/Paddle
+PYTORCH_ROOT=~/pytorch
+PCAT_ROOT=~/PaddleCppAPITest
+TORCH_DIR=~/libtorch
+```
+
+## 适用场景
+
+- 有新增 PyTorch C++ API 需要在 Paddle compat 层实现
+- `bash test/result_cmp.sh ./build/` 仍出现 `FAILED/SKIPPED/DIFF`
+- 需要新增 Device、Tensor、c10、ATen 等 compat 接口和测试
+
+## 主流程（循环执行）
+
+### Step 1. 确定本轮新增接口范围
+
+1. 明确本轮要新增的接口（建议一次聚焦 1-3 个接口）
+2. 在 `$PCAT_ROOT/test/` 中定位或补充对应测试（例如 Device 相关）
+3. 明确接口行为基线：参数、返回、异常语义
+
+### Step 3. 参考 PyTorch 实现并新增 Paddle compat 接口
+
+1. 在 `$PYTORCH_ROOT` 中查找目标接口实现（声明 + 实现）
+2. 在 `$PADDLE_ROOT/paddle/phi/api/include/compat` 中新增接口
+3. 在 `$PADDLE_ROOT/test/cpp/compat` 中新增对应测试
+4. 保持与 PyTorch 行为一致：
+   - 参数语义
+   - 返回类型与 dtype/shape
+   - 异常触发时机
+
+### Step 4. 编译 Paddle 并跑兼容测试
+
+```bash
+cd "$PADDLE_ROOT/build"
+ninja -j"$(nproc)"
+ctest -R "ATen|c10|torch"
+```
+
+若此步失败，先修复 Paddle 侧编译或测试问题，再继续。
+
+### Step 5. 安装新 wheel
+
+```bash
+pip install "$PADDLE_ROOT"/build/python/dist/*.whl --force-reinstall --no-deps
+```
+
+### Step 6. 回到 PaddleCppAPITest 复编并复测
+
+```bash
+cd "$PCAT_ROOT/build"
+ninja -j"$(nproc)"
+
+cd "$PCAT_ROOT"
+bash test/result_cmp.sh ./build/
+```
+
+### Step 7. 判定是否继续循环
+
+- 若新增接口相关用例仍有 `FAILED/SKIPPED/DIFF`：回到 Step 3，进入下一轮
+- 若新增接口相关用例通过：进入收尾步骤
+
+## 分支决策
+
+### 分支 A：PaddleCppAPITest 编译失败（接口缺失）
+
+- 优先补齐 compat 声明与最小实现
+- 回到 Step 3 完善接口与测试后，再执行 Step 4-6 验证
+
+### 分支 B：Paddle 编译通过但 `ctest` 失败
+
+- 先修复回归，再安装 wheel
+- 不要跳过 `ctest` 直接进入回归对比
+
+### 分支 C：新增接口行为不一致
+
+- 对照 PyTorch 检查 dtype 推导、边界输入、异常行为
+- 仅处理本轮新增接口导致的问题，不处理历史遗留差异
+
+### 分支 D：wheel 安装异常
+
+- 确认 `build/python/dist/` 下有最新 whl
+- 必要时先清理旧包后重装
+
+## 完成标准
+
+同时满足以下条件才算完成：
+
+- `$PADDLE_ROOT/build` 下 `ninja -j"$(nproc)"` 成功
+- `$PADDLE_ROOT/build` 下 `ctest -R "ATen|c10|torch"` 通过
+- `$PCAT_ROOT` 下 `bash test/result_cmp.sh ./build/` 中新增接口相关用例通过
+- 文档已更新：新增接口迭代记录（以及相关专题文档）
+
+## 文档收尾要求
+
+完成新增后，按以下固定模板更新文档（推荐记录到
+`$PCAT_ROOT/doc/` 下的专题文档，必要时同步相关文档）：
+
+```markdown
+## 对齐迭代记录（YYYY-MM-DD）
+
+### 1) 接口变更
+- 接口名：
+- 变更类型：新增
+- Paddle 兼容层位置：
+- 参考 PyTorch 位置：
+
+### 2) 测试覆盖
+- 测试文件：
+- 新增/修改用例：
+- 覆盖点：shape / dtype / 边界 / 异常
+
+### 3) 新增接口验证结果
+- 新增前状态（缺失）：
+- 新增后验证结果：
+- 关键行为说明：
+
+### 4) 构建与回归结果
+- Paddle 编译：通过/失败
+- ctest (ATen|c10|torch)：通过/失败
+- result_cmp：无差异/仍有差异
+
+### 5) 未完成项与下一轮计划
+- 未完成接口：
+- 下一轮优先级：
+```
+
+## 推荐执行节奏
+
+- 每轮只处理一组强相关接口，避免一次修改过大
+- 每轮都完整执行“编译→测试→安装→回归”闭环
+- 以新增接口相关用例通过作为验收基线

.github/skills/add-compat-api/references/Step3-1.md

@@ -0,0 +1,94 @@
+# Step 3 参考：从声明追踪到 PyTorch 实现
+
+本文用于补充 Step 3 的第 1 步：从声明追踪到 PyTorch 实现。
+
+## 第1步：先在 libtorch 查声明，再定位真实实现
+
+目标：先从 libtorch 头文件确认 API 入口，再追踪到 PyTorch 源码中的最终 C++ 实现。
+
+### 1) 先在 libtorch 中定位声明
+
+将目标接口名记为 `<api_name>`，先在 libtorch include 目录搜索：
+
+```bash
+rg -n "<api_name>\(" "$TORCH_DIR/include/ATen" "$TORCH_DIR/include/torch"
+```
+
+常见声明位置：
+- `$TORCH_DIR/include/ATen/ops/*.h`
+- `$TORCH_DIR/include/ATen/core/*.h`
+- `$TORCH_DIR/include/torch/csrc/api/include/torch/*.h`
+
+### 2) 判断“有实现”还是“仅声明/转发”
+
+找到声明后，分两类：
+
+- 情况 A：头文件里有明确函数体
+  - 可直接把该函数体作为语义参考起点。
+
+- 情况 B：只有声明，或转发到 dispatcher
+  - 常见形态：`at::_ops::<op>::call(...)`、`redispatch(...)`。
+  - 这通常表示该接口由 torchgen 生成包装层，不在该头文件里放最终业务实现。
+
+对情况 B，继续执行第 3-6 步。
+
+### 3) 在 PyTorch YAML 中找 schema 与 dispatch
+
+在 PyTorch 源码中搜索：
+
+```bash
+rg -n "<api_name>" "$PYTORCH_ROOT/aten/src/ATen/native/native_functions.yaml"
+```
+
+在命中的 YAML 条目中提取：
+- 函数 schema（func）
+- dispatch 表（CPU/CUDA/Composite/Meta 等）
+- 各后端对应的 kernel 名称
+
+说明：
+- PyTorch 会使用 `$PYTORCH_ROOT/torchgen`（例如 `/home/may/pytorch/torchgen`）解析 YAML，生成 libtorch 头文件与包装层。
+- 因此 libtorch 中很多接口只有声明或轻量转发，真实实现需要继续沿 dispatcher 追踪。
+
+### 4) 沿 dispatcher 链路追踪到 kernel 符号
+
+把调用路径映射为：
+
+1. 头文件声明/包装
+2. `at::_ops::<op>::call`（生成代码）
+3. dispatcher 注册路由
+4. YAML dispatch 指向的后端 kernel 符号
+
+再用 kernel 符号搜索真实实现：
+
+```bash
+rg -n "<kernel_symbol>\(" "$PYTORCH_ROOT/aten/src/ATen/native"
+```
+
+### 5) 仍未命中时，检查生成注册文件
+
+有些场景下，先看生成的注册文件更快：
+
+```bash
+rg -n "<api_name>|<kernel_symbol>" "$PYTORCH_ROOT/build/aten/src/ATen"
+```
+
+重点关注 `Register*.cpp` 和生成的 ops 相关文件。
+
+### 6) 在实现 compat 前，先落一份追踪记录
+
+正式改 Paddle compat 之前，至少记录以下映射：
+
+- libtorch 声明文件位置
+- 声明是直接实现还是 dispatcher 转发
+- YAML 条目与 dispatch 键
+- PyTorch 最终 kernel 文件与函数
+
+只有映射清晰后，才进入 compat 接口实现阶段。
+
+## 快速检查清单
+
+- 已先从 libtorch 声明开始查找
+- 已确认是否属于 torchgen 生成转发
+- 已定位 native_functions.yaml 的 schema 与 dispatch
+- 已定位最终 C++ kernel 实现
+- 未臆造上游不存在的实现