| name | asc-devkit-reference |
| description | Ascend C 算子开发工具包参考库。在架构设计、代码开发、API 查阅和性能优化阶段，从 asc-devkit 仓库中检索 API 文档、示例代码、实现参考和构建配置作为开发指导。触发：需要查阅 Ascend C API 官方文档、查找示例代码、参考算子实现、了解构建系统或学习编程模型时。 |
Ascend C 算子开发工具包参考库
概述
本技能管理 asc-devkit 仓库的本地副本，为算子开发各阶段提供 Ascend C 官方 API 文档、示例代码、实现参考和构建配置的全面支持。该仓库是 CANN 推出的昇腾 AI 处理器专用的算子程序开发语言，原生支持 C 和 C++ 标准规范，主要由类库和语言扩展层构成，提供多层级 API，满足多维场景算子开发需求。
仓库管理
初始化
首次使用时，将仓库克隆到 .agent/asc-devkit：
git clone https://gitcode.com/cann/asc-devkit.git .agent/asc-devkit
更新
若本地副本已存在，拉取最新内容：
git -C .agent/asc-devkit pull --rebase
每次使用前应检查是否需要更新，确保参考的是最新文档和示例。
仓库结构
asc-devkit/
├── docs/ # 官方文档
│ ├── api/ # API 文档
│ │ ├── context/ # API 上下文文档（1022+ 个 API 文档，含 figures/ 配图）
│ │ └── README.md # API 文档索引
│ ├── guide/ # 开发指南
│ └── README.md # 文档总入口
├── examples/ # 示例代码（587+ 个示例）
│ ├── 00_introduction/ # 入门示例：基本编程模型、数据搬运、计算指令
│ ├── 01_utilities/ # 工具类示例：printf 调试、断言使用
│ ├── 02_features/ # 特性示例：C API、SIMT、Micro API、Tiling 等
│ └── 03_libraries/ # 库函数示例：数学库等
├── impl/ # 实现代码
│ ├── adv_api/ # 高阶 API 实现
│ │ └── tiling/ # Tiling 参数配置参考
│ └── ... # 其他实现
├── include/ # 头文件
│ ├── ascendc/ # Ascend C 核心头文件
│ ├── utils/ # 工具类头文件
│ └── ... # 其他头文件
├── cmake/ # 构建配置
├── scripts/ # 脚本工具
├── tests/ # 单元测试
├── tools/ # 辅助工具
├── CMakeLists.txt # 根 CMake 配置
└── README.md # 仓库说明
注意：以上为仓库的大致分类结构，具体包含哪些文档和子目录会随仓库更新而变化。使用时应直接进入对应目录查看当前可用的内容。
各阶段参考指引
阶段一：架构设计
在设计 Tiling 策略、Kernel 结构和 Host 流程时，参考仓库中的文档和示例：
- API 能力调研 — 查阅
docs/api/context/ 目录下的 API 文档，了解可用 API 的功能、参数约束和平台支持情况，为设计方案选型提供依据
- 编程模型选择 — 查看
examples/02_features/ 中的 SIMT、Micro API 等特性示例，了解不同编程模型的适用场景和架构特点
- Tiling 策略设计 — 参考
impl/adv_api/tiling/ 中的 Tiling 参数配置，了解官方推荐的 Tiling 策略和参数计算方法
- 同类算子参考 — 在
examples/ 中查找与目标算子类型相近的示例，参考其整体架构设计思路
操作方式：进入 .agent/asc-devkit/ 对应子目录，阅读 README.md 了解概述，再进入具体目录查看文档和源码。
阶段二：代码开发
在编写 Host/Kernel/Tiling 代码时，参考仓库中的 API 文档和示例代码：
- API 用法查阅 — 查阅
docs/api/context/ 中目标 API 的官方文档，确认函数签名、参数类型、约束条件和平台支持。注意：同一 API 可能有多个变体文件（如 Add.md / Add-25.md），必须用通配符搜索所有变体并逐一查阅
- API 配图细读 —
docs/api/context/figures/ 下的配图（.png/.jpg/.svg）常承载文字未明确表达的关键约束（流水时序、内存布局、参数示意等），必须使用 Read 工具逐张查看
- 示例代码参考 — 参考
examples/00_introduction/ 中的入门示例，学习 Ascend C API 的标准调用方式（数据搬运、计算指令、同步 barrier 等）
- 特性代码参考 — 查看
examples/02_features/ 中的特性示例，学习 SIMT Kernel、C API、Micro API 等特定编程模型的代码写法
- 头文件查阅 — 查阅
include/ascendc/ 中的头文件，了解类型定义、模板参数和宏定义
- 构建配置 — 参考
cmake/ 和 CMakeLists.txt 了解编译配置和依赖管理方式
操作方式：直接阅读 .agent/asc-devkit/ 下目标文件。API 文档为 Markdown 格式，示例代码为 .asc/.cpp/.h 格式。
阶段三：性能优化
在进行性能调优和瓶颈分析时，参考仓库中的优化示例和工具：
- 性能优化示例 — 查看
examples/ 中与性能相关的示例，学习 Double Buffer、流水线并行、数据搬运优化等编程模式
- Tiling 参数调优 — 参考
impl/adv_api/tiling/ 中的 Tiling 配置，了解不同参数对性能的影响
- 工具使用 — 参考
tools/ 和 scripts/ 中的辅助工具，学习 Profiling 和仿真分析方法
- 单元测试参考 — 查看
tests/ 中的单元测试，了解 API 的正确使用方式和边界条件处理
操作方式：优先阅读相关示例目录中的 README.md，理解优化思路，再对照代码实现学习具体优化手法。
API 文档检索指南
变体搜索（重要）
Ascend C 存在 240+ 个带数字后缀的 API 变体（如 Add-25.md），同名 API 的不同变体功能可能完全不同。
强制搜索步骤
-
列出所有变体：
ls .agent/asc-devkit/docs/api/context/ | grep -iE "^APIName"
-
逐一确认功能：每个变体的函数签名、参数、功能可能完全不同
变体命名规律
| 后缀 | 含义 | 示例 |
|---|
| 无后缀 | 基础版本 | Add.md |
-数字 | 变体版本（数字无语义，功能可能完全不同） | Add-25.md |
变体检测命令
ls .agent/asc-devkit/docs/api/context/ | grep -iE "^APIName"
grep -l "关键词" .agent/asc-devkit/docs/api/context/APIName*.md
配图查阅
API 文档中引用的配图存放在 docs/api/context/figures/ 目录下，包含：
- 公式图：确认数学语义
- 流水时序图：理解 MTE2/V/MTE3 的依赖与并行关系
- 内存布局图：UB 槽位摆放规则、对齐边界
- 参数示意图：stride / block 在 UB/GM 的几何含义
强制要求：含配图（figures/*.png/jpg/svg）的 API 文档，必须使用 Read 工具逐张查看配图，禁止仅看正文文字。
检索策略
当需要查找参考时，按以下顺序检索：
- 先读文档索引 — 从
docs/README.md 和 docs/api/README.md 开始，定位相关文档
- 再读 API 文档 — 进入
docs/api/context/ 查找目标 API 的所有变体文档
- 查阅示例代码 — 进入
examples/ 对应子目录，查看 README.md 和源码文件
- 查阅实现代码 — 进入
impl/ 查看官方实现参考
- 查阅头文件 — 进入
include/ 查看类型定义和接口声明
仓库内容持续更新，若在某个分类下未找到相关参考，应检查仓库是否有新增目录或文件。也可查看仓库根目录 README.md 了解最新变更。
与其他技能的关系
| 技能 | 职责分工 | 协作方式 |
|---|
ascendc-docs-search | 在线文档搜索（华为昇腾社区） | 本地 asc-devkit 文档不足时，使用 ascendc-docs-search 在线搜索兜底 |
ascendc-api-best-practices | API 使用约束和最佳实践 | 查阅 asc-devkit API 文档后，结合 best-practices 确认使用约束 |
op-samples-reference | cann-samples 高性能样例 | asc-devkit 侧重 API/示例/实现参考，cann-samples 侧重端到端性能调优实践 |
注意事项
- 仓库中的示例可能依赖特定版本的 CANN Toolkit 和 NPU 架构，参考时注意查看示例 README 中的环境要求
- 示例代码的风格和规范可能与 ops-blas 项目不完全一致，参考时应以 ops-blas 自身的编码规范（
blas-ascendc-coding-rules）为准
- API 文档中的参数约束和平台支持信息以官方文档为准，设计方案中引用的 API 必须经过完整验证
