Function Overview
Defines the standardized 7-phase workflow for migrating ATB operators from the OPS interface to the ACLNN interfacestandardized 7-phase workflow, including a Human in the Loop user confirmation mechanism.
When to Use
{xxx}Quant、{xxx}Norm、SoftmaxOPS→ACLNN migration of operators such as- Enable ACLNN acceleration on 910B/950 devices
- Maintain compatibility with other devices
Detailed Content
Phase Gates Overview
[Phase 0] 前置知识学习
│
▼
[Phase 1] 设计文档生成 ────→ [用户确认 Gate 1] ───┐
│ │
▼ │
[Phase 2] CSV用例设计 ─────→ [用户确认 Gate 2] ───┤
│ │
▼ ▼
[Phase 3] 实际迁移(TDD) ←───────────────────────┘
│
▼
[Phase 4] 编译验证(≤3次尝试)
│
▼
[Phase 5a] 小范围验证
├─ Step 1: 前台跑 _func.csv(正例+反例, ~30s)
└─ Step 2: 后台 subagent 跑 _perf.csv(性能, ~10min, 不阻塞)
│
▼
[Phase 5b] 全量回归(所有相关 CSV)──→ [Gate 5b: 全量通过] ──┐
│ (汇合 subagent 性能结果) │
▼ ▼
[Phase 6] 交付报告 ←──────────────────────────────────────────┘
Detailed Description of Phase 0-6
See the detailed documents for each phase below.
No-Skipping Rules ⛔
⚠️ The following rules must be enforced at every Phase transition and cannot be bypassed:
Phase Dependency Matrix
| Phase | Prerequisite Gate | Behavior When Not Passed |
|---|---|---|
| Phase 1 | Gate 0 (Documents Complete) | Block — Entering the design phase is prohibited when interface documents are missing |
| Phase 2 | Gate 1 (Design Confirmation) | Block — Writing CSV is prohibited before the user confirms the design document |
| Phase 3 | Gate 2 (CSV Confirmation) | Block — Writing code is prohibited before the user confirms the CSV test cases |
| Phase 4 | Phase 3 Complete | Executable (compilation verification) |
| Phase 5a | Phase 4 Passed | Run Phase 2 first, then Phase 5a — Testing is prohibited before test case design is complete |
| Phase 5b | Phase 5a Passed | Full regression — All related CSV must be fully run and pass |
| Phase 6 | Gate 5b Passed | Executable (delivery report) |
Checks That Must Be Performed at the Start of Each Phase
1. 确认上一阶段 Gate 状态:
- Gate X 是否已获用户确认?
- 确认记录在哪里 (commit message / working_files / 对话记录)?
2. 如果 Gate 未通过:
- 立即停止
- 向用户报告: "Phase Y 需要 Gate X 确认,当前 Gate X 状态: 未确认"
- 等待用户指示
3. 如果 Gate 已通过:
- 明确告知用户: "Gate X 已通过,进入 Phase Y"
- 继续执行
Common Skipping Errors and Interception Scripts
| Erroneous Behavior | Agent Self-Check Question | Interception Script |
|---|---|---|
| Run tests directly after compilation | "Have the CSV test cases been designed and confirmed?" | ⛔ Phase 5a requires Gate 2 confirmation. Current Gate 2 status: not confirmed. Please complete Phase 2 CSV test case design first. |
| Write the delivery report directly after 5a passes | "Has the full regression been executed?" | ⛔ Gate 5b not passed: full regression testing is incomplete. Please execute Phase 5b first and confirm that all related CSV pass. |
| Skip the design document after implementation | "Has the design document been generated?" | ⛔ Phase 3 requires Gate 1 confirmation. Current Gate 1 status: not confirmed. Please complete the Phase 1 design document first. |
| Infer from code after WebFetch fails | "Are the interface documents complete?" | ⛔ Gate 0 not passed: failed to obtain the ATB/ACLNN interface documents; inferring from code is prohibited. Please ask the user to provide the documents. |
| Write code directly after CSV design is complete | "Has the user confirmed the CSV?" | ⛔ Phase 3 requires Gate 2 confirmation. Please wait for the user to confirm the CSV test cases first. |
Phase Status Self-Check at Agent Startup
Every time the Agent is invoked to execute a migration task, it must first execute:
1. git log --oneline -5 → 检查当前分支做了什么
2. ls working_files/ → 检查哪些阶段产物已存在
3. 判断当前处于哪个 Phase → 报告用户当前状态
4. 确认下一 Phase 的前置 Gate 是否通过 → 按依赖矩阵校验
Skills invocation sequence
| Stage | Skill invoked |
|---|---|
| Phase 1 | atb-aclnn-operator-replacement-designer |
| Phase 2 | atb-csv-testcase-generator |
| Phase 3 | atb-aclnn-operator-migration |
| Phase 4 | atb-testframework-build |
| Phase 5a | atb-csv-tester(1 run by default for positive/negative cases, 400 runs by default for performance) |
| Phase 5b | atb-csv-tester (Gate 5 full regression) |
| Debugging | atb-debug-guide |
Quick reference
# Phase 0-1: 设计和用例生成
# → atb-aclnn-operator-replacement-designer
# → atb-csv-testcase-generator
# → [等待用户确认 Gate 1 & 2]
# Phase 3: 实际迁移
# → atb-aclnn-operator-migration
# Phase 4: 编译
# → atb-testframework-build
# → [失败] atb-debug-guide
# Phase 5a: 小范围验证
# → atb-csv-tester(不指定 -t,正例/反例默认1次,性能默认400次)
# → [失败] atb-debug-guide
#
# Phase 5b: 全量回归
# → atb-csv-tester (Gate 5)
# → [失败] atb-debug-guide
Detailed stage documentation
Objective
Understand the technical background related to the operator, laying the foundation for subsequent design.
Prerequisites
None
Input
- Operator name (e.g.,
{xxx}Quant) - Task background document (if any)
Output
- Prerequisite knowledge summary document (saved to working_files)
Learning content
| Topic | Content | Output location |
|---|---|---|
| Quantization basics | Differences between per-token/per-channel/per-tensor | {WORKING_DIR}/quant_basics.md |
| ACLNN interface documentation | Understanding of official API specifications | Record key parameters |
| Existing ATB implementation | Analysis of the current OPS implementation | Record migration points |
Checkpoint
| Check item | Verification method |
|---|---|
| Quantization knowledge has been summarized | File exists in working_files |
| Key parameters of the ACLNN interface have been extracted | Parameter list is present in the document |
Gate 0
- Type: Automatic pass (no user confirmation)
- Condition: Learning document has been generated
Objective
Generate a complete detailed design document for operator replacement (7-chapter structure).
Prerequisites
- Phase 0 completed
- ATB/ACLNN interface documentation links have been provided
Skills invocation
atb-aclnn-operator-replacement-designer
Checkpoint
| Check item | Verification method |
|---|---|
| ATB interface URL has been provided | Documentation link is valid |
| ACLNN interface URL has been provided | Documentation link is valid |
| ATB operator parameters have been extracted | Chapter 2 of the design document is complete |
| ACLNN interface parameters have been extracted | Chapter 2 of the design document is complete |
| Parameter mapping table has been created | Section 2.3 of the design document exists |
| All 7 chapters of the design document are complete | Chapters 1-7 all exist |
Gate 1: User confirmation ⭐
⚠️ Mandatory checkpoint - cannot be skipped
Before confirmation is received, entering Phase 2 is prohibited
Objective
Design a CSV test case set covering positive cases, negative cases, and performance tests,producing two separate files。
Output artifacts
| File | Content | Purpose |
|---|---|---|
{op}_func.csv |
Positive cases + negative cases | Phase 5a foreground quick verification |
{op}_perf.csv |
Performance test cases | Phase 5a background subagent runs them one by one |
{op}_test.csv(Optional) |
All merged | Phase 5b full regression |
Prerequisites
- Phase 1 has passed Gate 1 user confirmation
Skills invocation
atb-csv-testcase-generator
Checkpoint
| Check item | Quantity | Verification method |
|---|---|---|
| Positive cases cover typical scenarios | 5-15 | Cover float16/bf16 |
| Negative cases cover all validation branches | 10-20 | Cover all ERROR_INVALID_* |
| Performance tests cover large and small shapes | 5-10 | Include large/medium/small shapes |
| Split into _func.csv and _perf.csv | 2 independent files | Each has a complete 21-column header |
| CSV format conforms to the specification | - | Column count=21, delimiter=| |
Gate 2: User confirmation ⭐
⚠️ Mandatory checkpoint - cannot be skipped
Before confirmation is received, entering Phase 3 is prohibited
Objective
Implement the ACLNN Runner and modify Operation to enable 910B/950 acceleration.
Prerequisites
- Phase 2 has passed Gate 2 user confirmation
Skills invocation
atb-aclnn-operator-migration
Implementation points
- Inherit AclnnRunner: The new runner must inherit from the base class
- Implement the four major methods:
BuildAclnnVariantPack: Handle input and output tensorsSetAclNNWorkspaceExecutor: Configure workspaceLaunchAclnnKernel: Execute computationLoadMethod: Dynamically load ACLNN functions
- Device detection: Use
GetSingleton<Config>().Is910B()andIs950() - Backward compatibility: Non-910B/950 devices retain the OPS implementation
Objective
Verify that the code compiles successfully, with a maximum of 3 attempts.
Skills invocation
atb-testframework-build
atb-debug-guide(编译失败时)
Compilation rules
| Attempt | Action |
|---|---|
| 1st failure | Analyze the error, locate the problem, fix it, and recompile |
| 2nd failure | Analyze in depth, review the reference implementation, fix it, and recompile |
| 3rd failure | Stop, record the error and modification plan,ask the user |
Objective
Run the CSVs produced in Phase 2 in two steps: quickly verify functionality in the foreground, and run performance tests in a background subagent.
Prerequisites
- Phase 4 compilation passed
- Phase 2 has produced
{op}_func.csvand{op}_perf.csv
Step 1: Run the functional CSV in the foreground
cd <ATB_REPO_PATH>/tests/framework/python/CsvOpsTestTool
python3 atb_csv_ops_test.py -i <CSV_DIR>/{op}_func.csv
- Do not specify
-t, defaults to 1 time, completes in seconds - Must wait for all to pass, stop and troubleshoot if any fail
Step 2: Run the performance CSV in a background Subagent
Agent(
description="运行 {op} 性能测试",
prompt="""
逐个运行 {op}_perf.csv 中的性能测试用例,避免 OOM:
cd {ATB_REPO_PATH}/tests/framework/python/CsvOpsTestTool
source {CANN_PATH}/set_env.sh
source {ATB_REPO_PATH}/output/atb/set_env.sh
# 获取性能用例总数
lines=$(tail -n +2 {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv | wc -l)
# 逐个运行每个性能 case
for i in $(seq 1 $lines); do
echo "=== 运行性能 case $i/$lines ==="
python3 atb_csv_ops_test.py -i {ATB_REPO_PATH}/tests/apitest/opstest/csv/{op}_perf.csv -n $i:$i
done
完成后汇总:通过/失败/耗时。
""",
subagent_type="general-purpose",
run_in_background=True
)
Key points:
- Use
-n N:Nto run one by one, loading only 1 performance case each time run_in_background=TrueExecute in the background without blocking the main flow- The subagent notifies automatically upon completion, and the results are consolidated into the Phase 6 delivery report
Skills invocation
atb-csv-tester(双文件 + 前台/后台两种模式)
atb-debug-guide(测试失败时)
Post-completion actions
After Step 1 fully passes, start the Step 2 background subagent,and immediately continue in the foreground with Phase 5b full regression。
Objective
Run all CSV files related to the target operator to ensure no regressions are introduced.
Prerequisites
- Phase 5a Step 1 (foreground functional CSV) all passed
- Phase 5a Step 2 (background performance subagent) may still be running
Skills invocation
atb-csv-tester(Gate 5 全量回归门控模式)
Test scope
Enumerate and run all related CSVs:
find <ATB_REPO_PATH>/tests/apitest/opstest/csv/ -name '{op_name}*.csv' -type f | sort
Subagent result aggregation
If the background performance subagent has not yet completed, wait for completion and then summarize:
### Phase 5a 后台性能测试结果
| Case | ExecuteTime(us) | precision | 状态 |
|------|----------------|-----------|------|
| case 1 | xxx | 100% | ✅ |
| ...
Test requirements
| Requirement | Description |
|---|---|
| All CSVs run in full | Partial runs are not allowed |
| All test cases pass | Failures or skips are not allowed |
| Use default iteration counts | Do not specify -t(positive/negative cases 1 time, performance 400 times) |
| Aggregate background subagent results | Wait for the subagent to complete and summarize |
Gate 5b: Full regression confirmation
Mandatory checkpoint — cannot be skipped
## Gate 5b — 全量回归结果
| CSV 文件 | 总用例 | 通过 | 失败 | 状态 |
|---------|--------|------|------|------|
| {op}_test.csv | N | N | 0 | ✅ |
| {op}.csv | M | M | 0 | ✅ |
**全部通过,Gate 5b 满足,可进入 Phase 6 交付。**
When blocked, see atb-csv-tester Gate 5 blocking script.
Goal
Automatically aggregate the outputs of Phase 1/2/5 to generate a standardized delivery report.
Prerequisites
- Phase 5a tests passed
- Phase 5b full regression passed (Gate 5b confirmed)
Automatic aggregation process
The data for the delivery report should be automatically extracted from preceding phases; do not fill it in manually:
| Report section | Data source | Extraction method |
|---|---|---|
| Design document summary | {WORKING_DIR}/{op}_replacement_design.md |
Read the requirements summary/parameter mapping/risk assessment |
| CSV case statistics | {op}_test.csv |
wc -l + awk Group by ExpectedError |
| Code changes | git diff / git log |
git diff --stat + git log --oneline |
| Compilation verification | Phase 4 compilation log | Extract compilation status |
| Phase 5a results | Test output | Extract passed/failed/skipped |
| Phase 5b results | Test output | Summarize all CSVs |
| Outstanding items | Phase 5b items that did not pass | If there are failure records |
Automatic aggregation command snippet
# 统计 CSV 用例数
tail -n +2 {CSV_FILE} | wc -l
# 统计正例/反例/性能
tail -n +2 {CSV_FILE} | grep -c 'NO_ERROR$'
tail -n +2 {CSV_FILE} | grep -c 'Performance'
tail -n +2 {CSV_FILE} | awk -F'|' '{print $21}' | sort | uniq -c | sort -rn
# 代码变更
git diff --stat HEAD~1..HEAD
git log --oneline -5
Report template
# {Op} OPS→ACLNN 迁移交付报告
> **自动生成时间**: {timestamp}
> **生成方式**: 自动聚合 Phase 1/2/5 输出
## 任务概述
- **算子名称**: {Op}
- **迁移目标**: OPS → ACLNN
- **目标设备**: 910B/950
- **执行日期**: {date}
## 阶段完成情况
| 阶段 | 状态 | 关键输出 |
|------|------|----------|
| Phase 0 前置学习 | ✅ | working_files |
| Phase 1 设计文档 | ✅ | {op}_replacement_design.md |
| Phase 2 CSV用例 | ✅ | {op}_test.csv({total} 个用例) |
| Phase 3 实际迁移 | ✅ | 代码变更({files}个文件) |
| Phase 4 编译验证 | ✅ | 第 {N} 次编译通过 |
| Phase 5a 小范围验证 | ✅ | {designed_pass}/{designed_total} 通过 |
| Phase 5b 全量回归 | ✅ | {regression_total} 通过({csv_count} 个 CSV) |
| Gate 1/2 确认 | ✅ | 用户已确认 |
| Gate 5b 全量回归 | ✅ | 所有 CSV 通过 |
## 测试结果汇总
### Phase 5a: 小范围验证
- 执行 CSV: {op}_test.csv
- 通过: N/N
### Phase 5b: 全量回归
| CSV | 总用例 | 通过 | 失败 |
|-----|--------|------|------|
| {op}_test.csv | N | N | 0 |
| {op}.csv | M | M | 0 |
## 代码变更
{git diff --stat ...}
## 遗留事项
[如有未通过用例或已知问题]
## 附件清单
- 设计文档: {path}
- CSV用例: {path}
- 代码变更: git commit {hash}
- 交付报告: {path}
Gate 6: Final delivery ⭐
⚠️ Mandatory checkpoint
FAQ
Skipping Gate 1 and Gate 2 is prohibited. If the user does not respond in time:
- Remind the user to confirm pending
- If there is still no response after 24 hours, record the risk and pause the task
- Do not proceed to the next phase without authorization
- Record the complete error log to working_files
- Analyze using atb-debug-guide
- Ask the user (Socratic style):
- Phenomenon description
- Fixes already attempted
- Possible root cause hypotheses
- Support needed