菜单
自动生成 ATB 到 ACLNN 算子替换的详细设计文档。接收用户提供的 ATB 和 ACLNN 接口文档链接， 输出包含参数映射、开发自测、风险评估的 7 章结构化设计文档。 TRIGGER when: 用户需要将 ATB 算子替换为 ACLNN 算子并撰写设计文档。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
基于 SOC 职业分类
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ascend-ai-coding/awesome-ascend-skills --skill external-gitcode-ascend-atb-aclnn-operator-replacement-designer命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
评估 CANN 算子仓的「进阶教程 / 开发指南」类文档质量——通读文档 + 对照算子代码**静态**查证(默认不跑),按五轴(找得到/信得过/学得会/可操作/读得懂)找出 漏讲/讲不清/过时/对不上代码/概念讲错,产出带证据与改进建议的体检报告(MD + HTML)。涉及「评进阶教程 / 开发指南文档质量 / 文档对不对得上代码 / 教程审稿 / tutorial 体检 / 文档信不信得过」等意图时使用。只评不改不跑,只对着文档与代码出诊断。
Run NPU inference/training tests on a remote SSH server with vllm-ascend Docker container. Use when the user asks to test models on NPU, run inference on Ascend devices, or deploy models to an SSH server.
Track daily PRs and Issues from vllm-project/vllm and vllm-project/vllm-ascend, filter by model (DeepSeek/Qwen/GLM/MiniMax/Kimi) and tech topics (PD disaggregation, MTP, quantization, graph mode, performance), analyze with LLM, and generate a Markdown report. Use when user wants vllm daily tracker, PR/Issue digest, or Ascend inference ecosystem monitoring.
| name | external-gitcode-ascend-atb-aclnn-operator-replacement-designer |
| description | 自动生成 ATB 到 ACLNN 算子替换的详细设计文档。接收用户提供的 ATB 和 ACLNN 接口文档链接， 输出包含参数映射、开发自测、风险评估的 7 章结构化设计文档。 TRIGGER when: 用户需要将 ATB 算子替换为 ACLNN 算子并撰写设计文档。 |
| keywords | ["atb","aclnn","operator","replacement","design","算子","设计文档","昇腾"] |
| metadata | {"author":"ascend-transformer-boost-team + Claude Code + deepseek-v4-pro","version":"1.4.0","created":"2026-04-17","updated":"2026-04-29","skill-type":"design","gates":[{"id":"gate-design","description":"设计文档确认","trigger":"设计文档生成完成后，必须等待用户确认再进入 CSV 用例设计阶段"}]} |
| hooks | {"PreToolUse":[{"matcher":"Write|Edit|Bash","hooks":"[Truncated]"}],"PostToolUse":[{"matcher":"Write","hooks":"[Truncated]"}],"Stop":[{"hooks":"[Truncated]"}]} |
| original-name | atb-aclnn-operator-replacement-designer |
| synced-from | https://gitcode.com/Ascend/agent-skills |
| synced-date | 2026-05-26 |
| synced-commit | 1f7666e7768a0ceb21bb1d40ce4b5179fcb6f1d6 |
| license | UNKNOWN |
该工具能够根据用户提供的ATB和ACLNN接口文档链接，自动生成完整的算子替换详细设计文档。支持多种算子类型，提供标准化的文档结构和内容。
在以下情况下调用此技能：
调用此技能时，必须首先执行规模检测，确定使用完整模板还是轻量模板。
# 在 ATB 仓库中搜索目标算子的 ACLNN Runner 是否已存在
find <ATB_REPO_PATH>/src/ops/ops_infer/<op_type>/ -name '*_aclnn_runner.cpp' -type f 2>/dev/null
find <ATB_REPO_PATH>/src/ops/ops_infer/<op_type>/ -name '*_aclnn_runner.h' -type f 2>/dev/null
| 场景 | 判断条件 | 模板等级 | 说明 |
|---|---|---|---|
| 已有 Runner 接入 | *_aclnn_runner.cpp 已存在且已注册 REG_RUNNER_TYPE | 轻量模板 (4 节) | 仅需参数映射 + 约束 + 风险 |
| 全新迁移 | *_aclnn_runner.cpp 不存在 | 完整模板 (7 章) | 需要完整设计文档 |
## 规模检测结果
算子: {OpType}
ATB 仓库: <ATB_REPO_PATH>
检测: {op_type}_aclnn_runner.{h,cpp} [✅ 已存在 / 不存在]
→ 使用 [轻量模板 / 完整模板] 生成设计文档。
→ 预计生成 [4 节 / 7 章] 文档。
当 ACLNN Runner 已存在时（如仅需修改 Operation 的 CreateRunner 以挂载已有 runner），生成以下精简文档：
# {OpType} OPS→ACLNN 替换设计文档（轻量版）
## 文档信息
| 项目 | 内容 |
|------|------|
| 算子名称 | {OpType} |
| 迁移类型 | 挂载已有 ACLNN Runner（{op}_aclnn_runner.cpp 已存在） |
| 变更范围 | 仅修改 {op}_operation.cpp 的 CreateRunner，添加 910B/950 设备检测 |
| 目标设备 | 910B / 950 |
## 需求简述
- 将 {OpType} 算子在 910B/950 上从 OPS 切换至 ACLNN
- 非 910B/950 设备保持 OPS 路径
- ACLNN Runner 已存在且通过 REG_RUNNER_TYPE 注册，仅需接入分发
## 参数映射关系
| ATB参数 | ACLNN参数 | 映射类型 | 说明 |
|---------|-----------|----------|------|
| [从已有 runner 代码提取] | [从已有 runner 代码提取] | [直接/计算] | |
## 规格约束
- 数据类型: [从已有 runner 和接口文档提取]
- 输入约束: [提取]
- 参数约束: [提取]
- 设备相关: 950 上仅支持 {受支持的变体}
## 风险评估
| 风险项 | 风险等级 | 应对策略 |
|--------|---------|---------|
| 设备检测逻辑错误 | 低 | 参考已有 runner (Gather/Split/Repeat) 的分发模式 |
| 变体路由错误 | 中 | 在 CreateRunner 中加严格的 layerType/quantType 过滤 |
| 非目标设备回归 | 低 | 非 910B/950 设备保持 OPS 路径不变 |
轻量模板生成规则：
{WORKING_DIR}/{op_type}_replacement_design.md，标注为轻量版轻量版使用精简的 3 项确认表：
## 设计文档确认 - {OpType}（轻量版）
| 检查项 | 说明 | 用户确认 |
|--------|------|----------|
| 参数映射关系正确 | ATB→ACLNN 映射准确 | [ ] |
| 规格约束清晰 | 数据类型、参数约束完整 | [ ] |
| 风险评估完整 | 风险项和应对策略充分 | [ ] |
执行此技能前，必须从用户处获取以下路径：
<CANN_PATH>: CANN 安装路径（如 /usr/local/Ascend/ascend-toolkit/latest）<ATB_REPO_PATH>: ATB 仓库路径（如 {your working path}ascend-transformer-boost）若用户未提供或路径无效，立即停止并报错。
脚本校验示例：
if [ -z "$CANN_PATH" ] || [ ! -f "$CANN_PATH/set_env.sh" ]; then
echo "ERROR: CANN_PATH 未设置或无效，请用户提供。"
exit 1
fi
if [ -z "$ATB_REPO_PATH" ] || [ ! -d "$ATB_REPO_PATH" ]; then
echo "ERROR: ATB_REPO_PATH 未设置或无效，请用户提供。"
exit 1
fi
⚠️ 强制规则 — 不可通过代码反推绕过
WebFetch 是获取接口文档的途径。以下规则覆盖所有场景：
| 场景 | 行为 |
|---|---|
| WebFetch 两个 URL 均成功 | 继续分析 |
| WebFetch 任一 URL 失败 | 立即停止，打断用户 |
| WebFetch 返回 404/403/超时 | 立即停止，打断用户 |
| ACLNN Runner 已存在于代码仓 | 仍需文档成功 — 代码不能替代官方文档 |
打断用户的标准话术：
## ⛔ WebFetch 失败 — 需要接口文档
获取以下接口文档失败：
- [URL] → [失败原因]
**请提供以下任一形式**：
1. 可直接访问的文档 URL
2. ACLNN 开源仓中对应算子的接口头文件路径/内容
3. CANN 安装目录下的接口文档（如 `$ASCEND_TOOLKIT_HOME/opp/*/op_proto/` 下的算子定义）
4. 手动提供的完整参数列表（类型、含义、约束）
在没有完整接口文档前，禁止进入设计阶段。
禁止行为：
*_aclnn_runner.cpp 代码反推接口参数infer_op_params.h 结构体推断 ACLNN 约束规模检测（是否存在 *_aclnn_runner.cpp）→ 接口文档分析 → 参数映射建立 → 按模板等级生成文档
检查点系统：每个阶段完成后，请对照 执行结果 章节的检查点表确认状态。
用户需要提供以下信息：
| 映射类型 | 处理方式 |
|---|---|
| 直接映射 | 参数名和含义完全一致，直接映射 |
| 计算映射 | 根据公式或规则进行转换（如beginNormAxis → normalizedShape） |
| 废弃参数 | 识别不再需要的参数并说明 |
| 新增参数 | 识别新增参数并说明默认值或计算方式 |
## 需求详情
### 项目背景
为了兼容性和性能提升，需要将ATB中的{算子类型}算子替换为ACLNN算子。
### 需求目标
- 将ATB中的{算子类型}算子替换为对应的ACLNN算子
- 保持原有接口的兼容性，确保上层应用无需修改代码即可迁移
- 提升算子执行性能，充分利用昇腾硬件加速能力
- 确保替换后的算子功能正确性和稳定性
### 适用范围
本设计适用于ATB仓中的算子：
- {算子类型}算子
## 算子IR与参数配置
### ATB算子参数结构
```cpp
struct {OpType}Param {
// 从文档中提取的参数结构
};
// 从文档中提取的ACLNN接口
| ATB参数 | ACLNN参数 | 映射关系 |
|---|---|---|
| param1 | param1 | 直接映射 |
| param2 | param2 | 计算映射 |
| param3 | - | 废弃参数 |
</details>
## 参考实现
### softmax_aclnn_runner 参考
softmax_aclnn_runner是一个已实现的ACLNN runner示例，可作为参考。详细实现请参考 `references/softmax_aclnn_runner_reference.md` 文件，其中包含完整的头文件和源文件实现。
### 实现模式
所有ACLNN runner实现应遵循以下模式：
1. **继承自AclnnRunner基类**
2. **实现核心方法**：
- `BuildAclnnVariantPack`：构建ACLNN变体包，处理输入输出张量
- `SetAclNNWorkspaceExecutor`：设置ACLNN工作空间和执行器
- `LaunchAclnnKernel`：启动ACLNN内核执行计算
- `LoadMethod`：加载ACLNN函数指针
3. **注册Runner类型**：使用 `REG_RUNNER_TYPE` 宏注册Runner
### 代码结构
src/ops/ops_infer/{op_type}/{op_type}_aclnn_runner.h/cpp
其中 `{op_type}` 为算子类型，如 `softmax`、`layernorm` 等。
## 最佳实践
1. **接口文档分析**：仔细阅读ATB和ACLNN接口文档，确保准确理解参数含义和约束条件
2. **参数映射**：建立清晰的参数映射关系，特别注意计算映射和特殊参数的处理
3. **测试用例设计**：设计全面的测试用例，覆盖正常、异常和性能场景
4. **风险评估**：充分考虑可能的风险并制定应对策略
5. **代码结构**：遵循现有ACLNN runner的实现模式，保持代码一致性
6. **working_files 集成**：设计文档必须保存至 `working_files` 目录，便于用户确认和后续追溯
## Human in the Loop: 用户确认检查点 ⭐
**⚠️ 强制检查点 - 不可跳过**
设计文档生成完成后，必须等待用户确认后方可进入下一阶段。
### 确认前准备
1. **保存文档**: 将生成的设计文档保存至 `working_files` 目录
- **文件路径**: `{WORKING_DIR}/{op_type}_replacement_design.md`
- **变量说明**:
- `WORKING_DIR`: 由用户指定的 working_files 目录
- `op_type`: 算子类型小写（如 `swigluquant`, `layernorm`）
2. **准备确认清单**: 供用户逐项确认
### 用户确认检查表
```markdown
## 设计文档确认 - {OpType}
### 待确认文档
- **设计文档路径**: `{WORKING_DIR}/{op_type}_replacement_design.md`
- **ATB 接口链接**: [用户提供的链接]
- **ACLNN 接口链接**: [用户提供的链接]
### 确认检查表
| 检查项 | 说明 | 用户确认 |
|--------|------|----------|
| 参数映射关系正确 | 第 2.3 节参数映射表准确反映了 ATB→ACLNN 的映射关系 | [ ] |
| 风险评估合理 | 第 6 章识别的风险项和应对策略完整 | [ ] |
| 实现方案可行 | 第 5 章实现方案符合 ATB ACLNN Runner 标准模式 | [ ] |
| 测试用例设计可行 | 第 4 章测试用例覆盖全面，可进入 CSV 设计阶段 | [ ] |
| 规格约束清晰 | 第 3 章规格约束明确，便于编写反例测试 | [ ] |
### 确认方式
- **通过**: 回复 "确认通过" 或逐项打勾确认
- **修改**: 指出具体问题，返回修改后重新确认
### 后续步骤
确认通过后，将进入 Phase 2: CSV 用例设计阶段
- 下一步调用: `atb-csv-testcase-generator`
**⚠️ 未收到用户确认前，禁止进入 CSV 用例设计阶段**
我已生成 {OpType} 算子的替换设计文档，请确认以下内容：
📄 **文档位置**: `{WORKING_DIR}/{op_type}_replacement_design.md`
请检查：
1. 第 2.3 节"参数映射关系"是否正确？
2. 第 6 章"风险评估"是否遗漏重要风险？
3. 第 5 章"实现方案"是否符合预期？
4. 第 4 章"开发自测"是否覆盖全面？
回复 "确认通过" 进入 CSV 用例设计阶段，或指出需要修改的地方。
该skill可以与以下工具配合使用：
WebFetch：自动获取和解析接口文档内容Read：读取现有代码文件以了解实现模式Write：生成设计文档并保存至 working_filesEdit：根据需要调整文档内容通过使用该skill，用户可以快速生成高质量的ATB到ACLNN算子替换设计文档，提高开发效率和文档质量。
⚠️ 执行后填写：技能执行完成后，参照下方格式填写实际执行结果。
| 步骤 | 检查点描述 | 状态 |
|---|---|---|
| - | ATB 接口 URL 已提供 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| - | ACLNN 接口 URL 已提供 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 1 | ATB 算子参数已提取 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 1 | ACLNN 接口参数已提取 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 2 | 参数映射表已创建 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 2 | 至少一个计算映射已定义 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 3 | 设计文档 7 个章节完整 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 3 | 风险评估表存在 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 4 | AclnnRunner 子类模式已记录 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| 4 | 实现代码结构已定义 | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| HIL | 设计文档已保存至 working_files | ✅ PASS / ❌ FAIL / ⏭️ SKIP |
| HIL | 用户已确认设计文档 ⭐ | ⬜ 待确认 |
VERDICT: ✅ SUCCESS / ⚠️ PARTIAL / ❌ FAILED / ⏭️ SKIPPED
| 等级 | 检查点 | 问题描述 | 建议 |
|---|---|---|---|
| 🔴 CRITICAL | - | - | - |
| 🟡 WARNING | - | - | - |