القائمة
Ascend C API 使用最佳实践。提供算术、归约、数据搬运、Buffer管理、精度转换等 API 的正确用法和限制说明。触发：用户询问具体 API 用法（如"DataCopy 怎么用"）、遇到 API 参数错误或限制报错（如 repeatTimes、对齐问题）、需要查看 API 最佳实践或避坑指南时。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Profile PyPTO kernels in-core with the Ascend msprof op-simulator — cycle-accurate per-kernel traces. Use when the user wants to profile a built case, inspect kernel timing or instruction streams, or generate MindStudio Insight traces.
Tune cube/matmul tile sizes (row tile, N fragment, K fragment) for a PyPTO kernel — analytic hints, an on-chip buffer constraint model, and an empirical device sweep. Use when optimizing a matmul/cube's throughput, sizing the row / N / K tiles, resolving Mat (L1) / L0C / UB buffer overflows, or trading one tile dim for another.
Locate which pypto commit introduced a precision regression. Only pypto and its corresponding simpler (submodule) are tracked — ptoas and pto-isa versions are not part of the bisect. If the culprit is a simpler submodule bump, performs a second-level bisect within simpler.
Reproduce a reported problem, collect dependency versions, and create a GitHub issue. Use when the user wants to file a bug, request a feature, or create any GitHub issue.
Ascend C 开发资源索引（本地+在线）。提供：(1) 本地 API 文档索引、示例代码映射，(2) 在线文档搜索功能，(3) 资源查找优先级，(4) Explore Agent 使用指南。优先使用本地资源，仅在本地检索不到时使用在线搜索。
Complete git commit workflow including pre-commit checks, staging, message generation, and verification. Use when creating commits or preparing changes for commit.
| name | ascendc-api-best-practices |
| description | Ascend C API 使用最佳实践。提供算术、归约、数据搬运、Buffer管理、精度转换等 API 的正确用法和限制说明。触发：用户询问具体 API 用法（如"DataCopy 怎么用"）、遇到 API 参数错误或限制报错（如 repeatTimes、对齐问题）、需要查看 API 最佳实践或避坑指南时。 |
| API 类别 | 涵盖 API | 核心文档 | 典型场景 |
|---|---|---|---|
| 算术运算 | Add, Sub, Mul, Div, Adds, Muls | api-arithmetic.md | Softmax, LayerNorm, 广播优化 |
| 归约操作 | ReduceMax, ReduceSum | api-reduce.md, api-reduce-pattern.md | Softmax, LayerNorm, ReduceMean |
| 数据搬运 | DataCopy, DataCopyPad | api-datacopy.md | 非对齐处理、多维搬运 |
| Buffer 管理 | TBuf, TQue | api-buffer.md | Double Buffer、内存规划 |
| 精度转换 | Cast | api-precision.md | FP16/FP32 混合精度 |
| 流水线同步 | EnQue, DeQue, SetFlag | api-pipeline.md | 多级流水线、事件同步 |
| Compare 256B对齐 | Compare | api-restrictions.md | Padding 策略 |
| repeatTime 限制 | repeatTimes ≤ 255 | api-repeat-limits.md | 分批处理 |
| API 限制 | - | api-restrictions.md | 禁用 API、编译期限制 |
| Host Runtime | aclrtSetDevice, aclrtGetDeviceInfo | api-host-runtime.md | 设备初始化、核数获取 |
| 使用场景 | 相关文档 | 关键技巧 |
|---|---|---|
| Softmax/LayerNorm | api-reduce.md, api-reduce-pattern.md, api-arithmetic.md | 标量操作、广播优化、Buffer 复用 |
| 逐行处理（AR 模板） | api-arithmetic.md | Adds/Muls、节省 UB |
| 多行广播（ARA 模板） | api-arithmetic.md | BinaryRepeatParams.src1RepStride=0、分批处理 |
| 非对齐数据 | api-datacopy.md | DataCopyPad、32 字节对齐 |
| 混合精度 | api-precision.md | FP16 输入 FP32 计算 |
| 流水线优化 | api-pipeline.md, api-buffer.md | Double Buffer、事件同步 |
| 性能调优 | api-buffer.md, api-repeat-limits.md | Double Buffer、repeatTimes 优化 |
| 遇到 API 限制 | api-restrictions.md | 替代方案、避坑指南 |
完整的 API 参数速查表：api-quickref.md
禁止在生产代码中使用：
| API | 禁止原因 | 替代方案 | 文档 |
|---|---|---|---|
GlobalTensor::SetValue() | 效率极低 | DataCopyPad | api-datacopy.md |
GlobalTensor::GetValue() | 效率极低 | DataCopyPad | api-datacopy.md |
DataCopy(GM↔UB) | 无法处理非对齐 | DataCopyPad | api-datacopy.md |
仅允许调试时使用：
// ✅ 调试：单点验证
AscendC::printf("debug: xGm[0]=%f\n", xGm.GetValue(0));