ascendc-operator-doc-gen（ascendc 运算符文档生成）

AscendC 算子接口文档生成

从算子源代码提取接口信息，生成 PyTorch 官方文档风格 的中文 API 接口文档。

前置条件：编译测试通过（Phase 3 完成），以下文件均已就绪：

• csrc/register.cpp — 包含 m.def 注册的 Python 调用 schema
• csrc/ops.h — 包含 C++ 函数声明
• csrc/ops/<op_name>/design.md — 包含算法描述、参数说明、dtype 支持、约束条件
• csrc/ops/<op_name>/op_host/<op_name>.cpp — 包含 TORCH_CHECK 约束和实际参数处理逻辑
• tests/test_<op_name>.py — 包含可运行的调用示例

工作流程

信息提取 → 文档结构组装 → 文件生成 → 聊天界面展示

阶段 1: 信息提取

从以下源文件中提取接口文档所需的全部信息。MUST 逐一读取这些文件，不可跳过。

1.1 从 csrc/register.cpp 提取 Python 调用签名

找到 m.def("<op_name>(...) 行，提取完整的 schema 字符串。

提取内容：

• 函数名
• 参数列表（含类型和默认值）
• 返回类型

示例：

m.def("acosh(Tensor self) -> Tensor");

→ 签名: torch.ops.npu.acosh(self) → Tensor

Schema 类型到 Python 类型映射：

1.2 从 csrc/ops.h 提取 C++ 函数声明

找到 namespace ascend_kernel 中对应函数的完整 C++ 签名。

提取内容：

• 返回类型（at::Tensor、void 等）
• 参数类型和参数名
• 参数是否为 const 引用 / optional

1.3 从 design.md 提取算法和设计信息

提取内容：

1.4 从 op_host/<op_name>.cpp 提取运行时约束

搜索所有 TORCH_CHECK(...) 语句，提取：

1.5 从 tests/test_<op_name>.py 提取使用示例

找到最简洁且完整的调用示例（优先选 run_simple_test 或 test_basic 中的代码），提取：

• 输入 tensor 构造方式
• 算子调用语句（torch.ops.npu.<op_name>(...)）
• 输出处理方式

阶段 2: 文档结构组装

按以下 固定结构 组装文档内容。格式严格参考 PyTorch 官方文档（如 torch.nn.RMSNorm、torch.abs），文档正文使用中文。

文档模板

# torch.ops.npu.<op_name>

torch.ops.npu.<op_name>(,,...,) →

<功能描述：1-3句中文说明算子做什么。如果有数学公式，用 LaTeX 行内公式展示。>

<如有数学公式，用独立公式块展示：>

$$
<公式>
$$

## 参数说明

- **<param1>** (*<type>*) – <中文描述>
- **<param2>** (*<type>*) – <中文描述>
- **<param3>** (*<type>, optional*) – <中文描述>。默认值: `<默认值>`

## 支持的数据类型

`torch.float16`, `torch.bfloat16`, `torch.float32`

## Shape

- **输入**: <shape描述，使用数学符号如 (N, *), (S, N, D) 等>
- **输出**: <shape描述>

<如有额外 shape 规则，以列表形式补充>

## 约束条件

- <约束条件1>
- <约束条件2>

## 使用示例

>> import torch >> import torch_npu >> import ascend_kernel >> <构造输入> >> <调用算子> >> <展示输出>

## 返回值

*<返回类型>* – <中文返回值描述>

各段落详细规范

标题签名

• 格式：torch.ops.npu.<op_name>(<参数列表>) → <返回类型>
• 参数列表从 register.cpp 的 schema 提取，仅保留参数名（不带类型）
• 有默认值的参数写为 <name>=<default>
• 返回类型：Tensor、tuple[Tensor, ...]、None（对应 C++ void）

功能描述

• 使用中文撰写
• 第一句话概括算子功能
• 如有数学公式，用 LaTeX 展示
• 如有多种工作模式（由参数控制），分别说明

参数说明

• 每个参数一行，格式：- **<name>** (*<type>*) – <中文描述>
• 可选参数标注 optional：- **<name>** (*<type>, optional*) – <中文描述>。默认值: \<value>\``
• 参数描述应包含：语义说明、shape 要求（如适用）、有效值范围（如适用）
• Tensor 参数说明 shape 格式，如 "形状: (S, N, D)"
• 布尔/枚举参数说明各取值的含义

支持的数据类型

• 列出算子支持的所有 PyTorch dtype
• 格式：` torch.float16, torch.bfloat16, torch.float32 `
• 从 op_host 的 TORCH_CHECK 和 design.md 交叉验证

Shape

• 使用中文标签（输入、输出）
• 描述输入输出 tensor 的 shape 语义
• 使用大写字母表示各维度含义，如 (N, C, H, W) — N: 批大小, C: 通道数, ...
• 如果 shape 随参数变化，分情况说明

约束条件

• 使用中文撰写
• 列出所有 TORCH_CHECK 中检查的约束条件
• 列出 design.md 中提到的有效输入范围
• 如果存在参数之间的互斥/依赖关系，明确说明

使用示例

• 提供可直接在 NPU 上运行的完整代码片段
• 包含 import 语句
• 使用 >>> 前缀（doctest 风格）
• 输入数据使用小尺寸（便于展示）
• 展示至少 1 个典型用例
• 如果有多种使用模式，各展示 1 个

返回值

• 使用中文描述
• 格式：*<type>* – <中文描述>
• 说明返回 tensor 的 shape 和 dtype（如与输入一致则注明"与输入 dtype 一致"）
• 如返回多个值（tuple），逐一说明

阶段 3: 文件生成

将组装好的文档写入：

ascend-kernel/csrc/ops/<op_name>/README.md

文件写入规则：

• 如果 README.md 已存在，覆盖旧内容
• 使用 UTF-8 编码
• 数学公式使用标准 LaTeX 语法（$...$ 行内，$$...$$ 块级）

阶段 4: 在交互界面展示文档（MANDATORY）

文件生成后，MUST 将完整的 README.md 内容直接输出到聊天界面中。

展示格式：

### 接口文档已生成

文件路径: `ascend-kernel/csrc/ops/<op_name>/README.md`

<完整 README.md 内容>

要求：

1. 展示完整文档内容，不要截断
2. 展示文件路径供用户查看
3. 如果某个段落因信息不足无法填写，用 [TODO: ...] 标注并提醒用户补充

完整示例

以下是一个假设的 acosh 算子的接口文档示例，展示最终生成效果：

说明：此示例仅用于展示文档格式，实际生成时所有信息均从源代码提取。

# torch.ops.npu.acosh

torch.ops.npu.acosh(self) → Tensor

逐元素计算输入张量的反双曲余弦值。

$$
\text{out}_i = \cosh^{-1}(\text{input}_i) = \ln(\text{input}_i + \sqrt{\text{input}_i^2 - 1})
$$

## 参数说明

- **self** (*Tensor*) – 输入张量，元素值必须 $\geq 1$。支持任意形状。

## 支持的数据类型

`torch.float16`, `torch.float32`

## Shape

- **输入**: $(*)$，支持任意形状
- **输出**: $(*)$，与输入形状相同

## 约束条件

- 仅支持 `float16` 和 `float32` 数据类型
- 输入张量的所有元素必须 $\geq 1$，否则结果为 `NaN`

## 使用示例

>> import torch >> import torch_npu >> import ascend_kernel >> x = torch.tensor([1.0, 2.0, 3.0, 10.0], dtype=torch.float32, device="npu:0") >> output = torch.ops.npu.acosh(x) >> output

tensor([0.0000, 1.3170, 1.7627, 2.9932], device='npu:0')

## 返回值

*Tensor* – 反双曲余弦计算结果，形状与输入相同，dtype 与输入一致。

检查清单

文档生成后按以下清单逐项验证：

• [ ] 签名一致性: torch.ops.npu.<op_name>(...) 的参数列表与 register.cpp 的 m.def 完全一致
• [ ] 参数完整性: 每个参数都有类型标注和中文语义描述
• [ ] 默认值正确: 有默认值的参数在签名和参数说明中都标注了默认值
• [ ] dtype 准确: 支持的数据类型与 op_host TORCH_CHECK 和 design.md 一致
• [ ] Shape 清晰: 输入输出 shape 描述使用了有语义的维度符号
• [ ] 约束完整: 所有 TORCH_CHECK 的检查条件都已体现
• [ ] 示例可运行: 使用示例中的代码是从 test 文件中提炼的可执行代码
• [ ] 返回值明确: 返回类型、shape、dtype 都已说明
• [ ] 中文表述: 功能描述、参数说明、约束条件、返回值均使用中文
• [ ] 文件已生成: README.md 已写入 csrc/ops/<op_name>/README.md
• [ ] 已在聊天界面展示完整文档内容

反模式清单

• NEVER 编造参数或 dtype 信息，所有信息必须从源代码提取
• NEVER 跳过 TORCH_CHECK 约束的提取
• NEVER 使用与 register.cpp schema 不一致的参数名或类型
• NEVER 省略使用示例段落
• NEVER 仅输出文件路径而不在聊天界面展示完整文档内容
• NEVER 修改算子源代码，本 skill 是只读文档生成
• NEVER 使用英文撰写文档正文（标题签名、代码、数学公式除外）

可读取文件范围