@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/ut-guide/op-host-ut-guide.md

@@ -0,0 +1,240 @@
+# OP_HOST UT 详细指南
+
+## 概述
+
+OP_HOST UT 包含两种测试类型：
+- **Tiling测试**：验证Tiling策略、TilingKey、TilingData、Workspace
+- **InferShape测试**：验证输出Shape和Dtype推导
+
+---
+
+## 前置准备
+
+### 1. 检测 CompileInfo 类型
+
+不同算子的 CompileInfo 类型和命名空间不同，编写 Tiling 测试前必须检测类型。
+
+**检测方法**：
+
+```bash
+# 在 tiling 实现文件中查找 TilingParse<TYPE>
+find op_host -name "*_tiling*.cpp" -exec grep -l "TilingParse" {} \;
+grep -n "TilingParse" op_host/<arch>/<op>_tiling_<arch>.cpp
+```
+
+**典型代码行**：
+```cpp
+IMPL_OP_OPTILING(Mul).TilingParse<BroadcastCompileInfo>(context, compileInfo);
+```
+
+**类型对照表**：
+
+| TYPE | 命名空间 | 头文件 | 示例算子 |
+|------|---------|--------|---------|
+| `BroadcastCompileInfo` | `Ops::Base::` | `atvoss/broadcast/broadcast_tiling.h` | Mul, Div, Sub |
+| `<Op>CompileInfo` | `optiling::` | 算子tiling头文件 | Add, Abs |
+
+**使用示例**：
+
+```cpp
+// BroadcastCompileInfo（广播类算子）
+#include "atvoss/broadcast/broadcast_tiling.h"
+Ops::Base::BroadcastCompileInfo compileInfo = {64, 245760};
+
+// 自定义 CompileInfo（如 AddCompileInfo）
+#include "../../../../op_host/arch35/add_tiling_arch35.h"
+optiling::AddCompileInfo compileInfo = {64, 245760};
+```
+
+**常见错误**：
+
+| 错误信息 | 原因 | 解决方案 |
+|---------|------|---------|
+| `'BroadcastCompileInfo' is not a member of 'optiling'` | 命名空间错误 | 使用 `Ops::Base::` |
+| `no matching function for call to 'TilingParse<...>'` | 类型不匹配 | 检测正确的 TYPE |
+
+---
+
+### 2. 确认 NodeAttrs 配置
+
+> **这是 op_host UT 编写中最常见的错误来源。大部分"测试运行返回 GRAPH_FAILED"问题都与此相关。**
+
+#### 问题表现
+- 测试编译通过，但运行失败
+- `infer_shape_func()` 返回 `4294967295` (GRAPH_FAILED)
+- `tiling_func()` 返回 `GRAPH_FAILED`
+
+#### 根本原因
+大部分算子的 InferShape/Tiling 函数会调用 `context->GetAttr()` 读取算子属性。如果测试中未配置 `NodeAttrs`，这些函数会因为读取不到必需属性而返回失败。
+
+#### 解决方案
+
+**InferShape 测试必须包含 NodeAttrs**：
+
+```cpp
+auto holder = gert::InferShapeContextFaker()
+                  .NodeIoNum(2, 1)
+                  .IrInstanceNum({1, 1})
+                  .InputShapes({&x1_shape, &x2_shape})
+                  .OutputShapes({&output_shape})
+                  .NodeAttrs({{"adj_x1", Ops::NN::AnyValue::CreateFrom<bool>(false)},
+                              {"adj_x2", Ops::NN::AnyValue::CreateFrom<bool>(false)}})
+                  .Build();
+```
+
+**Tiling 测试需要 NodeAttrs + NodeInputTd**：
+
+```cpp
+auto holder = gert::TilingContextFaker()
+                  .SetOpType("BatchMatMulV3")
+                  .NodeIoNum(2, 1)
+                  .IrInstanceNum({1, 1})
+                  .InputShapes({&x1_shape, &x2_shape})
+                  .OutputShapes(output_shapes_ref)
+                  .NodeAttrs({{"adj_x1", Ops::NN::AnyValue::CreateFrom<bool>(false)},
+                              {"adj_x2", Ops::NN::AnyValue::CreateFrom<bool>(false)},
+                              {"offset_x", Ops::NN::AnyValue::CreateFrom<int64_t>(0)},
+                              {"opImplMode", Ops::NN::AnyValue::CreateFrom<int64_t>(0)}})
+                  .NodeInputTd(0, param.input_dtype, param.x1_ori_format, param.x1_format)
+                  .NodeInputTd(1, param.input_dtype, param.x2_ori_format, param.x2_format)
+                  .NodeOutputTd(0, param.y_dtype, param.y_ori_format, param.y_format)
+                  .Build();
+```
+
+**如何确定需要哪些属性**：
+
+1. 查看算子源码中的 `INFER_SHAPE_FUNC` 或 `TILING_FUNC` 宏
+2. 搜索 `context->GetAttr()` 或 `GetAttrValue()` 调用
+3. 参考同算子仓中类似算子的测试文件
+
+**常见算子属性对照表**：
+
+| 算子类型 | 常见属性 | 命名空间 |
+|---------|---------|---------|
+| MatMul系列 | adj_x1, adj_x2, offset_x, opImplMode | Ops::NN |
+| Reduce系列 | axes, keepdims | Ops::Math |
+| Activation系列 | 通常无特殊属性 | - |
+| Conv系列 | pads, strides, dilations, groups | Ops::NN |
+
+---
+
+## 目录结构
+
+```
+<repo>/<category>/<op>/tests/ut/op_host/
+├── CMakeLists.txt
+├── test_<op>_infershape.cpp
+├── test_<op>_tiling.cpp
+└── arch35/                     # 芯片架构目录（如需要）
+    └── test_<op>_tiling.cpp
+```
+
+---
+
+## Tiling 测试
+
+### 核心组件
+
+```cpp
+#include "tiling_context_faker.h"
+#include "tiling_case_executor.h"
+
+// 1. CompileInfo（必须先检测类型）
+optiling::AddCompileInfo compileInfo = {64, 245760};
+
+// 2. TilingContextPara
+gert::TilingContextPara tilingContextPara("Add",
+    { {{{1, 64}, {1, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND} },  // 输入
+    { {{{1, 64}, {1, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND} },  // 输出
+    &compileInfo);
+
+// 3. ExecuteTestCase
+ExecuteTestCase(tilingContextPara, ge::GRAPH_SUCCESS, expectTilingKey, expectTilingData, expectWorkspaces);
+```
+
+### 测试用例示例
+
+```cpp
+// 成功场景
+TEST_F(AddTilingTest, test_tiling_fp16_001) {
+    optiling::AddCompileInfo compileInfo = {64, 245760};
+    gert::TilingContextPara tilingContextPara("Add",
+        { {{{1, 64, 2, 64}, {1, 64, 2, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND} },
+        { {{{1, 64, 2, 64}, {1, 64, 2, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND} },
+        &compileInfo);
+    ExecuteTestCase(tilingContextPara, ge::GRAPH_SUCCESS, 102, "...", {16777216});
+}
+
+// 失败场景
+TEST_F(AddTilingTest, test_tiling_failed_dtype) {
+    optiling::AddCompileInfo compileInfo = {64, 245760};
+    gert::TilingContextPara tilingContextPara("Add",
+        { {{{1, 64}, {1, 64}}, ge::DT_DOUBLE, ge::FORMAT_ND} },  // 不支持的dtype
+        { {{{1, 64}, {1, 64}}, ge::DT_DOUBLE, ge::FORMAT_ND} },
+        &compileInfo);
+    ExecuteTestCase(tilingContextPara, ge::GRAPH_FAILED, 0, "", {});
+}
+```
+
+---
+
+## InferShape 测试
+
+### 核心组件
+
+```cpp
+#include "infershape_context_faker.h"
+#include "infershape_case_executor.h"
+
+// InferShapeContextPara
+gert::InfershapeContextPara infershapeContextPara("Abs",
+    { {{{4, 3, 4}, {4, 3, 4}}, ge::DT_FLOAT16, ge::FORMAT_ND} },  // 输入
+    { {{{}, {}}, ge::DT_FLOAT16, ge::FORMAT_ND} });               // 输出（空shape待推导）
+
+// ExecuteTestCase
+std::vector<std::vector<int64_t>> expectOutputShape = {{4, 3, 4}};
+ExecuteTestCase(infershapeContextPara, ge::GRAPH_SUCCESS, expectOutputShape);
+```
+
+### 测试用例示例
+
+```cpp
+// 成功场景
+TEST_F(AbsInferShapeTest, test_infershape_fp16) {
+    gert::InfershapeContextPara infershapeContextPara("Abs",
+        { {{{4, 3, 4}, {4, 3, 4}}, ge::DT_FLOAT16, ge::FORMAT_ND} },
+        { {{{}, {}}, ge::DT_FLOAT16, ge::FORMAT_ND} });
+    std::vector<std::vector<int64_t>> expectOutputShape = {{4, 3, 4}};
+    ExecuteTestCase(infershapeContextPara, ge::GRAPH_SUCCESS, expectOutputShape);
+}
+
+// 失败场景：不支持的dtype
+TEST_F(AbsInferShapeTest, test_infershape_failed_dtype) {
+    gert::InfershapeContextPara infershapeContextPara("Abs",
+        { {{{4, 3, 4}, {4, 3, 4}}, ge::DT_DOUBLE, ge::FORMAT_ND} },
+        { {{{}, {}}, ge::DT_DOUBLE, ge::FORMAT_ND} });
+    ExecuteTestCase(infershapeContextPara, ge::GRAPH_FAILED, {});
+}
+```
+
+---
+
+## 编译命令
+
+```bash
+# 编译 op_host UT
+bash build.sh -u --ophost --ops='<op_name>' --soc='<soc_version>'
+
+# 编译并生成覆盖率
+bash build.sh -u --ophost --ops='<op_name>' --soc='<soc_version>' --cov
+```
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|------|------|---------|
+| 测试运行返回 GRAPH_FAILED | 未配置 NodeAttrs | 查看源码中的 GetAttr 调用，添加必需属性 |
+| CompileInfo 类型错误 | 命名空间不匹配 | 检测正确的 TYPE 和命名空间 |
+| 编译找不到头文件 | include 路径不正确 | 使用相对路径或检查 CMakeLists.txt |

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/ut-guide/op-kernel-ut-guide.md

@@ -0,0 +1,198 @@
+# OP_KERNEL UT 详细指南
+
+## 概述
+
+OP_KERNEL UT 测试 Kernel 计算逻辑，分两种类型：
+- **AscendC Kernel**：AI Core 上的 Kernel，使用 CPU 模拟执行（tikicpulib）
+- **AICPU Kernel**：AICPU 上的 Kernel
+
+> **注意**：`op_kernel/`（AscendC Kernel）和 `op_kernel_aicpu/`（AICPU Kernel）是互斥的，一个算子只会存在其中一种。
+
+---
+
+## 目录结构
+
+```
+<repo>/<category>/<op>/tests/ut/
+├── op_kernel/                  # AscendC Kernel UT
+│   ├── CMakeLists.txt
+│   ├── test_<op>.cpp
+│   └── <op>_data/              # 测试数据
+└── op_kernel_aicpu/            # AICPU Kernel UT
+    ├── CMakeLists.txt
+    └── test_<op>.cpp
+```
+
+---
+
+## AscendC Kernel UT
+
+### 核心组件
+
+```cpp
+#include "tikicpulib.h"
+
+// 1. 声明kernel入口函数
+extern "C" __global__ __aicore__ void <op>(GM_ADDR x, GM_ADDR y, GM_ADDR workspace, GM_ADDR tiling);
+
+// 2. 内存分配
+uint8_t* x = (uint8_t*)AscendC::GmAlloc(inputSize);
+uint8_t* y = (uint8_t*)AscendC::GmAlloc(outputSize);
+uint8_t* workspace = (uint8_t*)AscendC::GmAlloc(16 * 1024 * 1024);
+uint8_t* tiling = (uint8_t*)AscendC::GmAlloc(sizeof(<Op>TilingData));
+
+// 3. 设置Tiling数据
+<Op>TilingData* tilingData = reinterpret_cast<<Op>TilingData*>(tiling);
+tilingData->usedCoreNum = 1;
+tilingData->totalLength = 1024;
+
+// 4. 执行Kernel
+ICPU_SET_TILING_KEY(tilingKey);
+ICPU_RUN_KF(<op>, numBlocks, x, y, workspace, tilingData);
+
+// 5. 释放内存
+AscendC::GmFree((void*)x);
+AscendC::GmFree((void*)y);
+AscendC::GmFree((void*)workspace);
+AscendC::GmFree((void*)tiling);
+```
+
+### 两种Tiling参数获取模式
+
+| 模式 | 适用场景 | 说明 |
+|------|---------|------|
+| 手动设置 | Tiling参数简单、固定 | 手动构造TilingData结构体 |
+| 自动获取 | Tiling参数复杂（推荐） | 使用ExecuteTiling从Tiling实现获取 |
+
+### 手动设置模式示例
+
+```cpp
+TEST_F(add_lora_test, test_add_lora_0) {
+    uint8_t* x = (uint8_t*)AscendC::GmAlloc(inputSize);
+    uint8_t* y = (uint8_t*)AscendC::GmAlloc(outputSize);
+    uint8_t* workspace = (uint8_t*)AscendC::GmAlloc(16781184);
+    uint8_t* tiling = (uint8_t*)AscendC::GmAlloc(sizeof(AddLoraTilingData));
+
+    AddLoraTilingData* tilingData = reinterpret_cast<AddLoraTilingData*>(tiling);
+    tilingData->usedCoreNum = 20;
+    tilingData->batch = 1;
+
+    ICPU_SET_TILING_KEY(100001);
+    ICPU_RUN_KF(add_lora, 20, x, y, workspace, tilingData);
+
+    AscendC::GmFree((void*)x);
+    AscendC::GmFree((void*)y);
+    AscendC::GmFree((void*)workspace);
+    AscendC::GmFree((void*)tiling);
+}
+```
+
+### 自动获取模式示例
+
+```cpp
+#include "tiling_case_executor.h"
+
+TEST_F(IsInfTest, test_case_float16_1) {
+    // 1. 构造Tiling上下文并获取参数
+    optiling::IsInfCompileInfo compileInfo = {};
+    gert::TilingContextPara tilingContextPara("IsInf",
+        {{{{128, 64}, {128, 64}}, ge::DT_FLOAT16, ge::FORMAT_ND}},
+        {{{{128, 64}, {128, 64}}, ge::DT_BOOL, ge::FORMAT_ND}},
+        &compileInfo);
+
+    TilingInfo tilingInfo;
+    ExecuteTiling(tilingContextPara, tilingInfo);
+
+    // 2. 使用TilingInfo中的参数
+    uint8_t* workspace = (uint8_t*)AscendC::GmAlloc(tilingInfo.workspaceSizes[0]);
+    uint8_t* tiling = (uint8_t*)AscendC::GmAlloc(tilingInfo.tilingDataSize);
+    std::memcpy(tiling, tilingInfo.tilingData.get(), tilingInfo.tilingDataSize);
+
+    // 3. 执行
+    ICPU_SET_TILING_KEY(tilingInfo.tilingKey);
+    ICPU_RUN_KF(is_inf, tilingInfo.blockNum, x, y, workspace, tiling);
+}
+```
+
+### CMakeLists.txt
+
+```cmake
+if (UT_TEST_ALL OR OP_KERNEL_UT)
+    set(<op>_tiling_files
+        ${CMAKE_CURRENT_SOURCE_DIR}/../../../op_host/<op>_tiling.cpp
+    )
+    AddOpTestCase(<op> "ascend910b" "-DDTYPE_X=float" "${<op>_tiling_files}")
+endif()
+```
+
+---
+
+## AICPU Kernel UT
+
+### 核心组件
+
+```cpp
+#include "gtest/gtest.h"
+#define private public
+#define protected public
+#include "utils/aicpu_test_utils.h"
+#include "cpu_kernel_utils.h"
+#include "node_def_builder.h"
+#undef private
+#undef protected
+
+// NodeDefBuilder
+#define CREATE_NODEDEF(shapes, data_types, datas)                    \
+    auto node_def = CpuKernelUtils::CpuKernelUtils::CreateNodeDef(); \
+    NodeDefBuilder(node_def.get(), "OpName", "OpName")               \
+        .Input({"input1", data_types[0], shapes[0], datas[0]})       \
+        .Output({"output", data_types[1], shapes[1], datas[1]});
+
+// 执行
+RUN_KERNEL(node_def, HOST, KERNEL_STATUS_OK);
+
+// 验证
+bool compare = CompareResult(output, expected, count);
+```
+
+### AICPU 测试示例
+
+```cpp
+TEST_F(TEST_ADD_UT, FLOAT_TENSOR_ADD_TENSOR_SUCC) {
+    vector<DataType> data_types = {DT_FLOAT, DT_FLOAT, DT_FLOAT};
+    vector<vector<int64_t>> shapes = {{2, 3}, {2, 3}, {2, 3}};
+
+    float input1[6] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
+    float input2[6] = {6.0, 5.0, 4.0, 3.0, 2.0, 1.0};
+    float output[6] = {0};
+    vector<void*> datas = {(void*)input1, (void*)input2, (void*)output};
+
+    CREATE_NODEDEF(shapes, data_types, datas);
+    RUN_KERNEL(node_def, HOST, KERNEL_STATUS_OK);
+
+    float expected[6] = {7.0, 7.0, 7.0, 7.0, 7.0, 7.0};
+    EXPECT_EQ(CompareResult(output, expected, 6), true);
+}
+```
+
+---
+
+## 常见问题
+
+| 问题 | 解决方案 |
+|------|---------|
+| `cannot find -lpem_davinci` | 算子不支持op_kernel，删除op_kernel UT目录 |
+| 内存访问错误 | 使用32字节对齐：`CeilAlign(size, 32)` |
+| KernelMode需要设置 | Vector API需要：`AscendC::SetKernelMode(KernelMode::AIV_MODE)` |
+
+---
+
+## 编译命令
+
+```bash
+# 编译 op_kernel UT
+bash build.sh -u --opkernel --ops='<op_name>' --soc='<soc_version>'
+
+# 编译并生成覆盖率
+bash build.sh -u --opkernel --ops='<op_name>' --soc='<soc_version>' --cov
+```

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/workflow/step1.md

@@ -0,0 +1,43 @@
+## Step 1 了解当前仓库信息
+
+### Step 1.1 阅读基础知识文档
+
+如果文档 `references/${repo_type}/${repo_type}.md` 存在，立即阅读。
+
+### Step 1.2 提取支持的 SoC 列表
+
+```bash
+# 优先使用 --list-socs（custom 工程）
+bash ${repo_path}/build.sh --list-socs 2>/dev/null | grep '^ *- ' | sed 's/^ *- //'
+# 若不支持 --list-socs，从变量提取（标准仓）
+grep -oE 'SUPPORT_COMPUTE_UNIT[A-Z_]*=\([^)]+\)' ${repo_path}/build.sh | grep -o '"[^"]*"' | tr -d '"'
+```
+
+soc 和 arch 对应关系
+| soc | arch |
+|-----|------|
+| ascend310p | arch20 |
+| ascend910b | arch32 |
+| ascend910_93 | arch32 |
+| ascend950 | arch35 |
+
+### Step 1.3 学习编译命令
+
+```bash
+bash build.sh -h
+```
+
+**明确以下场景的编译命令：**
+- [ ] 单独编译运行 `${soc_type}` 模块的用例
+- [ ] 仅编译 `${soc_type}` 模块，不运行用例（用于快速验证）
+- [ ] 获取覆盖率
+
+**⚠️ 重要：build.sh 参数使用规范**
+
+| 参数 | 用途 | 注意事项 |
+|-----|------|---------|
+| 无 `--noexec` | 编译 + 运行一步完成 | **推荐日常使用**，能发现 CSV 格式等运行时错误 |
+| `--noexec` | 仅编译，不运行 | 仅用于快速验证语法错误，**编译通过后必须再运行测试** |
+
+**常见错误**：加了 `--noexec` 后忘记运行测试，导致 CSV 格式错误未被发现。
+

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/workflow/step2.md

@@ -0,0 +1,26 @@
+## Step 2 检查算子现有 UT 框架
+
+### Step 2.1 查看算子目录结构
+
+```bash
+# 确认算子目录位置
+find ${repo_path} -maxdepth 2 -type d -name ${op_name}
+
+# 查看算子目录结构
+tree ${op_path}
+```
+
+根据算子 `ut` 目录下的文件情况，判断算子是否已有 UT 框架
+
+### Step 2.2 编译运行现有用例
+
+**⚠️ 本步骤不能跳过！即使用户要求"重构 UT 框架"，也必须先验证旧框架是否正常。**
+
+如果算子已有 UT 框架，编译运行 `${test_model}` 涉及的用例，确认：
+- [ ] 已有用例可以编译通过
+- [ ] 已有用例全部 PASS
+- [ ] 可以获取到覆盖率数据
+
+**如果现有用例无法运行通过，或无法获取覆盖率，使用 `question` 工具向用户询问：**
+1. 尝试自动修复现有用例
+2. 立即结束会话，由用户确认编译环境是否正常

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/workflow/step3.md

@@ -0,0 +1,51 @@
+## Step 3 重构 UT 框架
+
+**用户没有明确提到“重构”时，跳过本步骤**
+
+### Step 3.1 备份旧框架代码
+
+将当前框架下 `ut/${test_model}` 目录下的 `.cpp`、`.h` 文件备份到系统临时目录：
+
+```bash
+mkdir -p /tmp/cannbot_${op_name}/backup
+cp ${op_path}/tests/ut/${test_model}/*.cpp ${op_path}/tests/ut/${test_model}/*.h /tmp/cannbot_${op_name}/backup/
+```
+
+备份完成后，删除原有的测试文件。
+
+### Step 3.2 搭建新框架，确保编译通过
+
+> **本步骤使用 Task 工具调用子 Agent 进行调试，避免污染上下文**
+> **不要读算子的定义和模板文件，分析算子的工作也交给子 Agent**
+
+根据用户的需求，搭建新的 UT 框架，确认可编译通过
+
+**算子的 UT 代码，需要放置在算子的目录下，而不是代码仓根目录下的 test 目录**
+
+**注意，仅迁移一条预期执行成功的旧用例**，用于验证框架是否正常，**迁移所有用例是后续步骤的任务**
+
+如果 `${repo_type}` 为 **"ops-transformer"** 且用户提及 **"CSV"**、**"CSV整改"**、**"CSV格式"**、**"CSV化"**，执行 **CSV 格式重构**:
+1. 让子 Agent 参考 [ops-transformer.md](../ops-transformer/ops-transformer.md) 和 [csv-refactor-workflow.md](../ops-transformer/csv-refactor-workflow.md)
+2. 让子 Agent 使用 `assets/csv-refactor/` 下的模板文件
+3. 让子 Agent 查看详细规范 [csv-format-spec.md](../ops-transformer/csv-format-spec.md)
+
+> **⚠️ 子 Agent 完成任务后，必须检查（编译 + 运行）：**
+> - [ ] UT 可以编译通过
+> - [ ] 所有用例运行显示 PASS
+> 如果有误，要求子 Agent 修正
+
+### Step 3.3 迁移所有旧用例
+
+> **本步骤使用 Task 工具调用子 Agent 进行调试，分析算子的工作也交给子 Agent，避免污染上下文**
+
+将旧框架中**所有**用例迁移至新框架，并确保用例**全部通过**
+
+- **新增用例时，不得更改已迁移用例和公共代码，例如 CSV 表头**
+- **每 5 条一组，确保编译运行通过后再迁移下一组**
+- **所有旧用例都要完整迁移，迁移中出现了框架不适配的情况时，及时向用户寻求策略**
+
+> **⚠️ 子 Agent 完成任务后，必须检查（编译 + 运行）：**
+> - [ ] UT 可以编译通过
+> - [ ] 运行测试验证所有用例 PASS
+> - [ ] 新的用例集数量和重构前一致
+> 如果有误，要求子 Agent 修正

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/workflow/step4.md

@@ -0,0 +1,130 @@
+## Step 4 补全用例，提升覆盖率
+
+**如果用户没有明确说明跳过本步骤，不得跳过**
+
+> **本步骤使用 Task 工具调用子 Agent 进行调试，避免污染上下文**
+
+### Step 4.1: 获取当前覆盖率
+
+```bash
+# 标准仓
+cd ${repo_path} && bash build.sh -u --ops=${op_name} --soc=${soc_type} --cov
+# custom 工程
+cd ${repo_path} && bash build.sh -u --soc=${soc_type} --cov
+```
+
+### Step 4.2: 阅读算子文档
+
+```bash
+# 查找并阅读算子目录下的 md 文档
+find ${op_path} -name "*.md" -exec cat {} \;
+```
+
+### Step 4.3: 判断覆盖率类型
+
+编译后需要先判断是**全局覆盖率**还是**单算子覆盖率**：
+
+```bash
+# 查看覆盖率报告包含的文件路径
+lcov --list ops.info_filtered | head -50
+```
+
+| 覆盖率类型 | 文件路径特征 | 处理方式 |
+|-----------|-------------|---------|
+| 单算子覆盖率 | 仅包含当前算子路径 | 直接使用 |
+| 全局覆盖率 | 包含多个算子路径 | 需要使用 `lcov --extract` 提取 |
+
+详细提取方法见 [coverage-extraction.md](../coverage-guide/coverage-extraction.md)
+
+### Step 4.4: 分析未覆盖代码
+
+根据 `${interactive_mode}` 选择不同的分析方式：
+
+#### 4.4a 交互模式
+
+当 `${interactive_mode} == "interactive"` 时：
+
+> **⚠️ 强制交互步骤 — 必须向用户询问，禁止跳过**
+>
+> 在交互模式下，**必须**通过 `question` 工具与用户确认目标文件，**不得**自动决定处理范围或直接生成报告。
+>
+> - 本步骤是交互模式的核心特征，跳过此步骤违背了用户选择交互模式的意图
+> - 即使用户dismiss问卷，也必须记录用户的选择（包括"无选择"），不得自行假设处理范围
+
+1. **获取文件覆盖率清单**
+   ```bash
+   # 提取每个文件的覆盖率，按覆盖率升序排列（未覆盖优先）
+   lcov --list ops.info_filtered | grep -E "^\s*.+\.(cpp|h)$" | awk '{print $1, $NF}' | sort -t: -k2 -n
+   ```
+
+2. **存储文件覆盖率清单**
+   ```bash
+   # 存储到临时文件
+   lcov --list ops.info_filtered | grep -E "^\s*.+\.(cpp|h)$" > /tmp/cannbot_${op_name}/coverage_files.txt
+   ```
+
+3. **⚠️ 询问用户选择目标文件（强制步骤，不可跳过）**
+   
+   **立即**使用 `question` 工具询问用户选择要提升覆盖率的文件：
+   - 问卷配置参考 `assets/coverage_files_question.json`
+   - 将不满足覆盖率标准的文件作为选项列出
+   - 每个选项显示文件名和覆盖率
+   - 用户选择的文件存储到 `/tmp/cannbot_${op_name}/target_files.txt`
+   
+   **如果用户 dismiss 问卷或选择"不处理"**：
+   - 明确记录用户的选择状态（如"用户未选择目标文件，结束覆盖率提升流程"）
+   - **不得**自行假设处理全部文件或继续后续步骤
+   - 可询问用户是否只需生成报告或结束流程
+
+4. **获取选中文件的未覆盖代码**
+   ```bash
+   # 针对每个目标文件提取未覆盖行
+   for file in $(cat /tmp/cannbot_${op_name}/target_files.txt); do
+     lcov --list ops.info_filtered | grep "${file}" | grep ":0"
+   done
+   ```
+
+5. **分析分支条件** — 识别进入该分支需要的参数组合
+6. **设计测试用例** — 参考 [test-implementation.md](../coverage-guide/test-implementation.md)
+
+#### 4.4b 自动模式
+
+当 `${interactive_mode} == "auto"` 时：
+
+1. **获取未覆盖代码清单**
+   ```bash
+   lcov --list ops.info_filtered | grep ":0"
+   ```
+   
+2. **分析分支条件** — 识别进入该分支需要的参数组合
+3. **设计测试用例** — 参考 [test-implementation.md](../coverage-guide/test-implementation.md)
+
+### Step 4.5: 迭代补充用例
+
+**用例来源**：
+- 已有算子文档中的示例
+- 重构前的旧用例
+- 算子其它组件的用例
+- 未覆盖代码分析结果
+
+**迭代策略**：
+
+| 缺口类型 | 补充策略 |
+|---------|---------|
+| 异常分支 | 添加 ACLNN_ERR_*/GRAPH_FAILED 用例 |
+| dtype分支 | 根据测试模块参考对应 guide 文档 |
+| 边界条件 | 添加空tensor、大shape用例 |
+| 格式分支 | 添加各 format 的测试用例 |
+
+**dtype 分支补充策略（按测试模块）**：
+
+| 测试模块 | 补充方法 | 参考 |
+|---------|---------|------|
+| opapi | 使用脚本提取 def 文件中的 dtype 组合 | 参考 [op-api-ut-guide.md](../ut-guide/op-api-ut-guide.md) 中的 "Dtype 排列组合校验" 章节 |
+| ophost | 分析 tiling 实现中的 dtype 分支逻辑 | [op-host-ut-guide.md](../ut-guide/op-host-ut-guide.md) |
+| opkernel | 分析 kernel 实现中的 dtype 分支逻辑 | [op-kernel-ut-guide.md](../ut-guide/op-kernel-ut-guide.md) |
+
+**完成检查**：
+- [ ] 所有新增测例通过
+- [ ] 行覆盖率 >= 80%
+- [ ] 函数覆盖率 >= 80%

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/references/workflow/step5.md

@@ -0,0 +1,5 @@
+## Step 5 生成总结报告
+
+**目标**：输出完整的 UT 开发记录
+
+模板见 [assets/template_report.md](../../assets/template_report.md)