Catlass Operator Dev

Catlass 算子端到端开发编排

Skill 类型：流程导向型（六阶段工作流；Catlass 源码准备并入 Phase 1，子技能串行编排）

本 skill 编排 ascend-kernel 上 Catlass 算子从零到生产可用；通用能力（工程骨架、编译调试、接口文档、精度、性能）复用 ascendc-* 子 skill，Catlass 专属（源码树、设计、Device/Host 落地）使用 catlass-* 子 skill。

核心原则

1. 六阶段串行：工程初始化（含 Catlass 源码）→ 设计文档 → 代码生成与编译测试 → 接口文档 → 精度评估 → 性能评测，严格顺序执行
2. 子技能执行：每个阶段 MUST 打开并遵循对应子 skill，不得自行替代实现
3. 阶段门控：前一阶段检查点全部通过后才进入下一阶段
4. 设计驱动编码：代码生成依赖 catlass-operator-design 定稿的 design.md 与 catlass/examples 选型
5. 无需用户预先手写设计文档：设计阶段由 catlass-operator-design 生成并落盘
6. 文档闭环：编译测试通过后 MUST 生成 PyTorch 风格中文接口文档（Phase 4），并在聊天界面展示
7. 精度闭环：算子必须通过 ≥30 例全面精度评估（Phase 5）才算完成
8. 性能闭环：算子必须完成 torch_npu.profiler 对比评测并输出性能报告（Phase 6）；结论以 ascendc-operator-performance-eval 为准
9. 结果可视化：Phase 3/4/5/6 的关键结果 MUST 以 Markdown 等形式直接展示在聊天界面，不要仅输出路径
10. 算子命名：op_name（snake_case）必须包含子串 catlass，与 ascend-kernel 内既有 Catlass 算子约定一致
11. 诚实停机：因环境或依赖无法继续时，说明具体原因与已完成步骤后停止

Catlass 编译与运行（易错摘要）

• 构建：BUILD_CATLASS_MODULE=ON；CMake 使用含 torch_npu 的 Python（如 -DPYTHON_EXECUTABLE / ASCEND_BUILD_PYTHON）；CATLASS_ARCH 与芯片一致（见 catlass-operator-code-gen/references/compile-catlass.md）；CANN 可为 bundle 根 + cann-*/set_env.sh。
• pytest / torch_npu：若报 ASCEND_RUNTIME_PATH：export ASCEND_RUNTIME_PATH="${ASCEND_TOOLKIT_HOME}/runtime"。
• 设计/代码：与 catlass/include、catlass/examples 可对齐编译的示例一致，细则见 compile-catlass.md。

可用子 Skill 清单

工程目录术语（与 AscendC 对齐）

工作流总览

┌─────────────────────────────┐   ┌──────────────┐   ┌───────────────────────────┐   ┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  Phase 1                    │   │  Phase 2     │   │  Phase 3                  │   │  Phase 4         │   │  Phase 5         │   │  Phase 6         │
│  工程初始化 + Catlass 源码   │──▶│  Catlass 设计 │──▶│  代码生成+框架适配+编译测试 │──▶│  接口文档生成     │──▶│  精度评估报告     │──▶│  性能评测报告     │
│  project-init + clone      │   │  catlass-    │   │  catlass-code-gen →       │   │  doc-gen         │   │  precision-eval  │   │  performance-eval│
│  catlass                   │   │  design      │   │  compile-debug            │   │                  │   │                  │   │  (profiler)      │
└─────────────────────────────┘   └──────────────┘   └───────────────────────────┘   └──────────────────┘   └──────────────────┘   └──────────────────┘

输入: 算子名(含 catlass) + 功能描述 + 环境确认          输出: 可交付算子 + README + 精度报告 + profiler 性能报告

反模式清单（NEVER DO THESE）

• ❌ 不要跳过 Catlass 源码准备（无 catlass/include、catlass/examples 就做设计或代码生成）
• ❌ 不要在 csrc/ops/<op_name>/ 内克隆 Catlass，必须在 工程根 下 catlass/
• ❌ 不要跳过设计阶段直接写 kernel/host
• ❌ 不要自行实现整套算子落地而不遵循 catlass-operator-code-gen 流程
• ❌ 不要在代码生成前擅自修改框架注册（以 project-init / code-gen 约定为准）
• ❌ 不要手动替代 compile-debug 所负责的编译安装与基础测试闭环（应通过 code-gen 阶段 5 触发）
• ❌ 不要跳过接口文档阶段（Phase 3 通过后必须 Phase 4）
• ❌ 不要跳过精度评估阶段（Phase 4 通过后必须 Phase 5）
• ❌ 不要跳过性能评测阶段（Phase 5 通过后必须 Phase 6）
• ❌ 不要使用与 ascendc-operator-performance-eval 不一致的采集方式作为最终性能结论
• ❌ 不要引用不存在的 skill

Phase 0：需求收集

目标：确认 Catlass 算子开发的最小信息集与运行环境（与 ascendc-operator-dev Phase 0 对齐，并增加 Catlass 命名约束）。

Step 0.1：环境确认（MUST 在任何开发动作之前完成）

CANN 环境

1. 检查 ASCEND_HOME_PATH（echo $ASCEND_HOME_PATH）
2. 已设置：作为 CANN_PATH，无需重复询问
3. 未设置：MUST 询问用户 CANN 路径（如 /usr/local/Ascend/ascend-toolkit）

source ${CANN_PATH}/*/set_env.sh

Conda 环境

1. 检查 CONDA_DEFAULT_ENV
2. 已激活且非 base：直接使用
3. 未激活或为 base：MUST 询问 conda 环境名

conda activate <env_name>

环境确认检查点

• CANN 路径已确定且 set_env.sh 可执行
• Conda 环境已确定且可激活

Step 0.2：算子需求收集

可选：支持 dtype、SoC —— 默认值与 catlass-operator-design / 平台 API 一致即可。

决策树

验收标准

• CANN + Conda 已确认
• op_name 已确认且包含 catlass
• 功能描述明确

Phase 1：工程初始化 + Catlass 源码准备

Step 1.1：工程骨架

调用 Skill：ascendc-operator-project-init

MANDATORY: 按 ascendc-operator-project-init 执行：
1. 检测或创建 ascend-kernel
2. 在 csrc/ops/<op_name>/ 创建算子骨架
3. 提示注册更新点（后续由 catlass-operator-code-gen 落实）

检查点（Step 1.1）

• ASCEND_KERNEL_ROOT 含 build.sh、CMakeLists.txt、csrc/
• csrc/ops/<op_name>/ 已创建，含占位 design.md、op_host/、op_kernel/、CMakeLists.txt 等（以该 skill 为准）

Step 1.2：Catlass 源码

本步骤不对应独立 skill文件，但必须按下列要求执行。

前置：Step 1.1 完成

执行内容

1. 在 ASCEND_KERNEL_ROOT 下确保存在 catlass/，且含 catlass/include、catlass/examples
2. 若不存在：MUST 在工程根执行（禁止在 csrc/ops/<op_name>/ 内克隆）
   git clone https://gitcode.com/cann/catlass.git catlass

检查点（Step 1.2）

• <ASCEND_KERNEL_ROOT>/catlass/include 存在
• <ASCEND_KERNEL_ROOT>/catlass/examples 存在

Phase 1 全部通过 → 进入 Phase 2

Phase 2：Catlass 设计文档

调用 Skill：catlass-operator-design

执行内容

MANDATORY: 按 catlass-operator-design 执行：
1. 分析需求与 Catlass 组件边界
2. 对齐 catlass/examples 与 catlass/include 的可实现路径
3. 定稿并落盘推荐路径：csrc/ops/<op_name>/design.md（与 doc-gen / precision-eval / performance-eval 读取一致）

检查点

• csrc/ops/<op_name>/design.md 已定稿（非空占位）
• 写清参考 example 路径、Kernel/Host 契约、dtype/shape 约束等（以 catlass-operator-design 为准）

全部通过 → 进入 Phase 3

Phase 3：代码生成 + 框架适配 + 编译测试

调用 Skill：catlass-operator-code-gen（阶段 5 MUST 调用 ascendc-operator-compile-debug）

执行内容

MANDATORY: 按 catlass-operator-code-gen 执行（与 ascendc-operator-code-gen 阶段结构对齐）：

阶段 1: 加载 GUIDE / references（含 compile-catlass、与 ascendc code-gen 对齐章节）
阶段 2: 读取 design.md，锁定 catlass/examples 路径与类型系统
阶段 3: 生成 op_kernel + op_host，CMake 登记 Catlass 编译选项（BUILD_CATLASS_MODULE、CATLASS_ARCH 等见 compile-catlass.md）
阶段 4: 框架适配 — ops.h、register.cpp、csrc/CMakeLists.txt
阶段 5: 编译安装与测试 — 调用 ascendc-operator-compile-debug（build.sh、pip install、tests/test_<op_name>.py，失败排错以该 skill 为准）

检查点

• op_host、op_kernel 与 design.md、选定 example 一致
• 框架注册与仓库模板一致（namespace ascend_kernel 等）
• 编译成功，whl 可安装
• tests/test_<op_name>.py 存在且通过（exit code 0）
• 关键编译/测试结果在聊天中有摘要展示

全部通过 → 进入 Phase 4

Phase 4：接口文档生成

调用 Skill：ascendc-operator-doc-gen

执行内容

MANDATORY: 按 ascendc-operator-doc-gen 执行：
- 从 register.cpp、ops.h、design.md、op_host、tests 提取接口信息
- 生成 csrc/ops/<op_name>/README.md（PyTorch 风格中文）
- 在聊天界面展示文档要点或全文

检查点

• README.md 已写入算子目录
• 与 m.def / 实际 Python 调用一致
• 已在聊天界面展示

全部通过 → 进入 Phase 5

Phase 5：精度评估报告

调用 Skill：ascendc-operator-precision-eval

执行内容

MANDATORY: 按 ascendc-operator-precision-eval 执行：
- 用例数 ≥ 30，覆盖 shapes × dtypes × 边界
- 输出到 csrc/ops/<op_name>/test/，生成 Markdown 精度报告
- 在聊天界面展示总览、失败摘要与关键发现（不得仅给路径）

检查点

• pytest 精度用例全部通过
• <op_name>_precision_report.md（或该 skill 规定的报告名）已生成
• 聊天中已展示精度结果摘要

FAIL 闭环：根因分析 → 修正设计（Phase 2）或代码（Phase 3）→ 再经 Phase 4、Phase 5 复测

全部通过 → 进入 Phase 6

Phase 6：性能评测报告

调用 Skill：ascendc-operator-performance-eval

执行内容

MANDATORY: 以 ascendc-operator-performance-eval SKILL.md 为唯一细则：
- 在 csrc/ops/<op_name>/test/ 维护 JSONL 用例；生成前先读 design.md
- 使用 torch_npu.profiler，warmup=5、active=5
- 汇总 ASCEND_PROFILER_OUTPUT/op_statistic.csv 等指标，输出自定义算子 vs 标杆的 Markdown 报告
- 在聊天界面展示对比表与简要结论

检查点

• 用例与报告形态符合该 skill（含 DType、双路径对比等）
• 报告文件已落盘于算子 test/ 目录
• 聊天中已展示性能摘要

全部通过 → Catlass 算子主流程完成

交付后可选：性能优化

调用 Skill：catlass-operator-performance-optim

须询问用户是否进入调优；不得默认跳过询问。

• 用户同意 → 按 catlass-operator-performance-optim 修改 tiling/实现；凡改代码 → 从 Phase 3 起复跑（Phase 3→4→5→6），直至再次达标
• 用户拒绝 → 结束

阶段间数据流

Phase 1 输出                         Phase 2 输入
  ascend-kernel + ops/<op>/骨架       算子名、catlass/ 可引用
  + catlass/include、examples   ────▶

Phase 2 输出                         Phase 3 输入
  design.md（定稿）            ────▶  example 路径、类型与 Host 契约

Phase 3 输出                         Phase 4 输入
  已安装 whl + test_<op>.py     ────▶  register.cpp / ops.h / design.md / op_host

Phase 4 输出                         Phase 5 输入
  README.md                    ────▶  接口、dtype、约束、调用方式

Phase 5 输出                         Phase 6 输入
  精度通过 + 报告                ────▶  算子名、标杆 API、JSONL 与 profiler 流程

Phase 6 输出
  性能报告（profiler）           ────▶  可选：用户确认后进入 catlass-operator-performance-optim

状态跟踪表

错误恢复

从中断点恢复

当用户说「继续 Catlass 算子开发」时：

编译/测试失败

由 ascendc-operator-compile-debug（经 catlass-operator-code-gen 触发）处理；重试与排错上限以 compile-debug skill 为准。