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

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/task-d/05-step5-gen-cases.md

@@ -0,0 +1,156 @@
+# Step 5：生成 S2P2_gen_cases.py
+
+> **前置条件**：Step 4 已完成，S2P2_param_def.json 已就绪
+>
+> **职责边界**：本文档为规范文档，仅定义规则、约束和校验标准。完整脚本模板在 `{skill_base}/scripts/gen_cases_template.py` 中，直接复制使用。
+
+## 输入
+
+脚本运行时从 `S2P2_param_def.json` 读取所有数据。LLM **不硬编码**任何维度取值，仅生成提取逻辑。
+
+| param_def 字段 | 运行时提取方式 |
+|---|---|
+| `dtype_tensors[0].param` | `DTYPE_PARAM` 变量 |
+| `groups[].per_dtype[{dtype}][*].path` / `key` | 直接读取 entry 的 `path`/`key` 字段 |
+| `groups[].per_dtype[{dtype}][*].{其他字段}` | `extract_entry_dims(entry)` 自动识别并构建 dim_dicts |
+| `groups[].group_dims.{dim}` 数组（group 级维度） | `extract_group_dims(group)` 自动识别并构建 dim_dicts |
+
+## 输出
+
+| 产出 | 文件 | 说明 |
+|------|------|------|
+| 生成脚本 | S2P2_gen_cases.py | JSON 驱动的可执行 Python 脚本 |
+| 测试用例 | S2P2_cases.json | 脚本执行后自动产出的 JSON 文件 |
+
+## 硬性规则
+
+1. **JSON 驱动**。脚本运行时从 `S2P2_param_def.json` 读取所有数据。LLM 仅生成提取逻辑（`extract_entry_dims`、`extract_group_dims` 函数调用）和通用循环，不硬编码任何维度取值。
+
+2. **约束隐含在取值中**。所有路由约束（dtype 依赖、对齐要求、范围互斥）在 **Task D Step 3 选值** 时已消化完毕。脚本中不含 `if` 约束过滤逻辑。
+
+3. **运行时提取，运行时采样**。`extract_entry_dims()` 从 per_dtype entry 自动识别字段类型并构建 dim_dicts；`extract_group_dims()` 从 group 对象自动提取 group 级维度。提取结果传入 `compress_per_dtype()` 和 `compress_group_pool()` 进行采样。
+
+4. **去重**。全字段去重：对完整 case dict 排序后构造元组作为去重键，防止完全重复的 case。去重仅作为安全网捕获极端边界情况。
+
+5. **零外部依赖**。仅使用 Python 标准库（`json`、`os`、`random`、`argparse`、`collections`、`zlib`）。不 import 第三方包。
+
+6. **自执行**。`python3 S2P2_gen_cases.py` 即可产出 `S2P2_cases.json`，无需命令行参数。
+
+## 压缩函数接口
+
+以下函数由 `gen_cases_template.py` 提供完整实现，此处仅声明接口契约。生成脚本时不得修改函数签名或违反约束条件。
+
+| 函数 | 输入 | 输出 | 约束 |
+|------|------|------|------|
+| `compress_per_dtype(dim_dicts, cap)` | `dict[str, list[dict]]`：维度名 → 取值列表；`int`：每个 per_dtype 路径生成的组合数 | `list[dict]`：生成的 dict 列表（≤ cap 条） | 循环生成 cap 个组合，每维度独立随机选值，固定 seed 保证可复现；可选值空间不足 cap 时以实际唯一组合数为准 |
+| `compress_group_pool(dim_dicts)` | `dict[str, list[dict]]`：维度名 → 取值列表 | `list[dict]`：合并后的 POOL | 单维度直接返回原 list；多维度池大小 = 各维度最小长度 |
+| `shuffled_pool(base, seed)` | `list[dict]`（base POOL）+ `int`（seed） | `(list[dict], int)`：(打乱后的池, 位置指针 0) | 每个 group 独立 seed；池耗尽时用相同 seed 重新打乱 |
+
+## 提取函数规则
+
+### extract_entry_dims(entry)
+
+从 per_dtype entry 中提取维度字段，构建 `dim_dicts` 供 `compress_per_dtype` 使用。
+
+**字段识别规则**：
+- `path`、`key` → 跳过（不作为维度）
+- 值为 dict list（如 compound `{compound_dim}`）→ 直接作为 dim_dicts 的一个 key
+- 值为 flat array（如 `["NHWC"]`、`[1]`）→ 转为 `[{field: v} for v in values]`
+
+### extract_group_dims(group)
+
+从 `group["group_dims"]` 提取 group 级维度。
+
+**提取规则**：遍历 `group["group_dims"]` 的所有字段，值为 list 的 → 转为 `[{field: v} for v in values]`
+
+## 生成逻辑
+
+所有 group 统一使用通用循环模式，无需为每个 group 单独编写代码。
+
+### 生成步骤
+
+1. 遍历 `param_def["groups"]`
+2. 对每个 group：`extract_group_dims(group)` → `compress_group_pool()` → `shuffled_pool()`
+3. 遍历 group 的 `per_dtype` 每个 dtype 的每个 entry：`extract_entry_dims(entry)` → `compress_per_dtype()` → 对每个组合从 pool 抽取 1 项 → 组装 case
+4. 池耗尽时用相同 seed 重新打乱
+
+### case dict 结构
+
+每条 case 必须包含以下字段：
+
+| 字段 | 来源 | 说明 |
+|------|------|------|
+| `_group` | group.id | 当前 group 标识 |
+| `{dtype_param}` | dtype 名称 | 主 dtype 的取值（如 `"float16"`） |
+| `path` | entry.path | 字符串 |
+| `key` | entry.key | 整数 |
+| per_dtype 维度 | `**p` 解包 | 当前 per_dtype 组合的所有维度 |
+| group 级维度 | `**gp` 解包 | 当前 pool 项的所有维度 |
+
+完整代码模板见 `{skill_base}/scripts/gen_cases_template.py`。
+
+## 池化抽样规则
+
+- `shuffled_pool(base, seed)` 函数：返回 `(pool, 0)`，其中 pool 是 base 打乱后的副本
+- 每个 group 使用独立 `seed`（`(group_idx + 1) * 100`），不同 group 错开切片实现互补覆盖
+- `_a` 由脚本运行时从 JSON 累加计算（遍历所有 group × 所有 dtype 的 per_dtype entry 总数）
+- `_default_cap = max(min(10, 100 // _a), 1)`
+- cap 通过 `--cap` 命令行参数传入；无参数运行时使用 default_cap
+
+  | a 范围 | cap | 效果 |
+  |--------|-----|------|
+  | ≤ 10 | 10 | 小算子，每 entry 可组合 10 种代表配置 |
+  | 11 | 9 | cap 随 a 增长逐步收敛 |
+  | 12 | 8 | |
+  | 13–14 | 7 | |
+  | 15–16 | 6 | |
+  | 17–20 | 5 | 中等 |
+  | 21–25 | 4 | |
+  | 26–33 | 3 | 多 dispatch |
+  | 34–50 | 2 | 高度分支 |
+  | ≥ 51 | 1 | 密集算子，每 entry 仅 1 种代表配置，依赖 group POOL 提供多样性 |
+
+- 池耗尽时调用 `shuffled_pool` 用 **相同 seed** 重新打乱（结果与上一轮完全一致），从头消费
+
+## 输出格式
+
+`S2P2_cases.json`：
+
+```json
+[
+  {"_group": "{group_a}", "{dtype_param}": "{dtype_val}", "{dim1}": {v1}, "{dim2}": {v2}},
+  {"_group": "{group_b}", "{dtype_param}": "{dtype_val}", "{dim1}": {v1}}
+]
+```
+
+- 每条 case 必含 `_group`（对应 `S2P2_param_def.json` 的 group `id`）
+- 每条 case 必含 dtype key（key 名为 `S2P2_param_def.json` 的 `dtype_tensors[0].param`）
+- 每条 case 必含 `path`（字符串）和 `key`（整数）
+- 每条 case 必含所有路由维度（通过 `**` 解包写入；复合维度展开为各子维度的独立字段）
+
+## 脚本模板
+
+使用 Bash 复制模板到产出目录：
+
+```bash
+cp {skill_base}/scripts/gen_cases_template.py S2P2_gen_cases.py
+```
+
+模板为通用 JSON 驱动脚本，无需任何修改。
+
+## 生成后自检
+
+`S2P2_gen_cases.py` 写完后，主 Agent 执行以下自检：
+
+**阶段 1：执行**。`python3 S2P2_gen_cases.py` 返回码为 0，并检查输出中的 `a=N, default_cap=M, cap=M` 信息（无参数运行时 cap==default_cap；若需覆盖，用 `python3 S2P2_gen_cases.py --cap X` 运行，此时 cap==X；default_cap 由公式 `max(min(10, 100//a), 1)` 计算，可人工复核）。
+
+**阶段 2：完整性**。S2P2_cases.json 中：
+- 每个 group 的每类 dtype 至少有一条 case
+- 所有 case 无完全重复（全字段去重，first-win）
+- JSON 语法有效
+- 所有 case 均包含 `path`（string）和 `key`（int）字段，无缺失
+- 所有 case 的顶层 key 均为标量字段（string/int/float/bool），不存在 dict 或 array 类型的值（复合维度必须已展开为独立字段）
+
+**阶段 3：一致性**：
+- 脚本正确从 `S2P2_param_def.json` 读取数据（验证 `extract_entry_dims` 和 `extract_group_dims` 函数逻辑）
+- `constraint_note` 描述的约束在取值中全部体现（人工核对——constraint_note 为自由文本，不要求自动化校验）

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/ttk-converter/00-execution-order.md

@@ -0,0 +1,108 @@
+# TTK Converter 执行入口
+
+## 角色
+
+将 Step 5 final case 文件转换为 TTK Kernel CSV，并执行 low/high 单用例 TTK kernel 验收。
+
+常规流程只执行 `scripts/run_ttk_kernel_module.py`，不派发 TTK 子 agent，不读取 `01-csv-common.md`、`02-kernel-fields.md` 或 `03-kernel-mode.md`。`01`-`03` 仅作为 kernel 模式内部实现细节、固定脚本维护资料和失败诊断参考。
+
+## 输入
+
+| 参数 | 说明 |
+|------|------|
+| `{skill_base}` | 技能根目录绝对路径 |
+| `{whitebox_dir}` | 白盒测试产出目录，需包含已通过 Step 5.5 校验的 `S5_cases_low.json`、`S5_cases_high.json` |
+| `{op_name}` | 规范算子名，如 `add_rms_norm` |
+| `{op_path}` | 算子源码根目录，如 `.../ops-nn/norm/add_rms_norm` |
+| `{ops_test_kit_path}` | 主 Agent 已在当前工作目录 `$PWD` 下定位到的 `ops-test-kit/` 路径 |
+
+## 常规执行命令
+
+主 Agent 直接执行：
+
+```bash
+python3 {skill_base}/scripts/run_ttk_kernel_module.py \
+  --op-name {op_name} \
+  --whitebox-dir {whitebox_dir} \
+  --op-path {op_path} \
+  --ops-test-kit-path {ops_test_kit_path} \
+  --skill-base {skill_base}
+```
+
+如用户提供了非默认 CANN 环境脚本，可追加：
+
+```bash
+  --setenv-path {setenv_path}
+```
+
+若只需生成/校验 CSV 和 precheck，不执行 kernel 单用例验收，可追加：
+
+```bash
+  --skip-kernel-run
+```
+
+`--skip-kernel-run` 仅用于脚本调试、CSV 生成链路冒烟或环境问题隔离。正常验收必须执行 TTK kernel 单用例，禁止追加 `--skip-kernel-run`。
+
+## wrapper 内部流程
+
+`run_ttk_kernel_module.py` 串行执行以下固定步骤：
+
+1. 调用 `scripts/ttk_generate_kernel_csv.py` 生成 low/high CSV。
+2. 调用 `scripts/ttk_validate_csv.py` 校验 low/high CSV，并对账 CSV 行数与 low/high case 数量。
+3. 调用 `scripts/ttk_precheck_env.py` 生成 `ttk_precheck_report.json`。
+4. `kernel_gate.status == "passed"` 时，串行执行 low/high 各 1 个 `python3 -m ttk kernel --golden-mode Disable` 用例。
+5. 内联分析 result CSV，确认目标 testcase 行存在、`dyn_precision` 为 `SUPPRESSED` 且 `memory_oob_status` 为空或 `PASS`，生成 `ttk_module_report.json`。
+
+## 输出
+
+| 文件 | 说明 |
+|------|------|
+| `ttk_{op_name}_cases_low.csv` | low 档位 TTK Kernel CSV |
+| `ttk_{op_name}_cases_high.csv` | high 档位 TTK Kernel CSV |
+| `ttk_precheck_report.json` | TTK 环境和 kernel gate 报告 |
+| `ttk_{op_name}_cases_low_one_result.csv` | low 单用例验收结果 |
+| `ttk_{op_name}_cases_high_one_result.csv` | high 单用例验收结果 |
+| `ttk_module_report.json` | wrapper 统一结构化报告，含步骤状态、耗时和 `acceptance` 最终验收结论 |
+
+## 状态判断
+
+Agent 对 TTK 模块给结论时，只读取 `ttk_module_report.json` 的 `acceptance` 字段：
+
+| acceptance 字段 | 结论 |
+|---|---|
+| `accepted=true` 且 `status="passed"` | TTK 模块验收通过 |
+| `accepted=false` 且 `status="failed"` | TTK 模块验收失败 |
+| `accepted=false` 且 `status="skipped"` | TTK 模块验收未完成，不能作为通过结论 |
+
+禁止直接使用 `kernel_gate.status` 作为最终验收结论。`kernel_gate` 只表示 TTK/CANN 环境门禁是否允许进入 kernel 执行阶段；最终结论必须以 `acceptance.accepted` / `acceptance.status` 为准。
+
+`acceptance.accepted=true` 仅表示 low/high result CSV 内联分析均通过。当前内联分析通过条件为：目标 `testcase_name` 行存在，必需字段 `testcase_name` / `dyn_precision` / `memory_oob_status` 存在，`dyn_precision` 为 `SUPPRESSED`，且 `memory_oob_status` 为空或 `PASS`。`dyn_precision` 对应 ttk-info.log 中的 `DYN_GOLD`，在 `--golden-mode Disable` 下用于确认 DYN 链路未出现 `INVALID_TILING` 等前置错误。
+
+### 输入分级
+
+wrapper 将输入分为两类：
+
+| 类别 | 路径 | 缺失处理 |
+|------|------|----------|
+| CSV 必需 | `S5_cases_low.json`、`S5_cases_high.json`、三个 `ttk_*.py` 固定脚本 | `status=failed`，无法生成 CSV |
+| kernel 环境 | `ops-test-kit/`、CANN 环境 | CSV 继续生成；precheck 记录原因；kernel 验收 `skipped` |
+
+### 常见 reason
+
+| reason | 说明 |
+|--------|------|
+| `missing_required_for_csv` | CSV 必需输入缺失 |
+| `csv_row_count_mismatch` / `csv_validation_failed` | CSV 生成结果不满足要求 |
+| `skip_kernel_run_requested` | 调试/冒烟场景主动跳过 kernel 验收；正常验收禁止使用 |
+| `env_unavailable` | `ops-test-kit`、TTK kernel 或 CANN 环境不可用 |
+| `low_kernel_execution_failed` / `high_kernel_execution_failed` | kernel 命令返回非 0，或 result CSV 缺失/空，或目标行缺失，或 `dyn_precision` 非 `SUPPRESSED`，或 `memory_oob_status` 非 PASS/空 |
+
+若 precheck 报告 `checks.cann_env.status == "passed_after_source"`，wrapper 会使用报告中的 `setenv_path` 执行 low/high TTK kernel 命令。
+
+## 失败诊断
+
+仅当 `ttk_module_report.json` 显示 wrapper 失败、CSV validator 失败、TTK kernel 执行失败，或用户要求分析 TTK 字段/规则时，再读取以下内部参考文档：
+
+- `03-kernel-mode.md`：Kernel CSV 生成、字段来源、TTK kernel 验收规则。
+- `02-kernel-fields.md`：Kernel CSV 字段定义。
+- `01-csv-common.md`：公共 CSV 字段和格式规则。

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/ttk-converter/01-csv-common.md

@@ -0,0 +1,33 @@
+# CSV 公共字段与约定
+
+## 公共字段定义（9 个，所有模式通用）
+
+| 序号 | 列名 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| 1 | `testcase_name` | STRING | 是 | 自动生成 | 用例唯一名称。缺失时自动生成为 `auto_testcase_name_N`。 |
+| 2 | `network_name` | STRING | 否 | `None` | 网络/模型名称标签（如 `model_name_train`）。 |
+| 3 | `input_data_ranges` | FLOAT_RANGE_NESTED | 否 | `((None, None),)` | 每个输入张量的随机数据范围。每个元素为 `(min, max)`。TensorList 输入使用展开嵌套格式（每个子 tensor 对应一个 range），如 `(((-10, 10), (-10, 10), (-10, 10)),)`，详见 02-kernel-fields.md「TensorList 嵌套结构」。 |
+| 4 | `precision_tolerances` | FLOAT_RANGE_NESTED | 否 | `None` | 每个输出的精度容差对 `(rtol, atol)`。如 `"((0.001, 0.001),)"`。TensorList 输出使用展开嵌套格式，如 `(((0.001, 0.001), (0.001, 0.001), (0.001, 0.001)),)`。 |
+| 5 | `absolute_precision` | FLOAT_OR_NESTED | 否 | `1e-8` | 默认绝对精度容差。可以是单个浮点数或嵌套容器实现逐输出控制。 |
+| 6 | `is_enabled` | BOOL | 否 | `True` | 设为 `False` 跳过此用例。 |
+| 7 | `remark` | STRING | 否 | `None` | 自由备注信息。 |
+| 8 | `soc_series` | STRING_TUPLE | 否 | `None` | SoC 过滤。前缀 `-` 表示排除。如 `('Ascend910A', '-Ascend310P')` |
+| 9 | `priority` | INT | 否 | `0` | 优先级，用于选择性执行。 |
+
+## CSV 格式规则（填写规范）
+
+1. **禁止无故设 None**：未明确要求为空的字段，使用列规格默认值
+2. **字符串带单引号**：tuple 内 dtype/format 等字符串用 `'float16'`、`'ND'`；顶层字段（testcase_name、op_name）不加引号
+3. **双引号包裹特殊字段**：含括号、逗号的字段必须用双引号包裹（CSV 标准）
+4. **dict key 双引号**：`{"epsilon": 1e-05}`
+5. **禁止 repr()**：字符串用 `str()`，单引号在构造 tuple 时嵌入
+6. **单元素 tuple 尾逗号**：1 维 shape 如 `(12289,)` 必须带尾逗号
+7. **precision_tolerances 尾逗号兼容**：校验脚本需同时接受 `((a, b))` 和 `((a, b),)` 两种格式
+8. **input_shapes / output_shapes**：只填静态值，动态 shape 由框架自动推导
+9. **ori 字段**：默认留空，TTK 框架自动回退
+
+## 通用禁止（所有模式，约束）
+
+1. 禁止不从 S5 JSON 取值而自行推导 shape/dtype
+2. 禁止修改固定列名和列顺序
+3. 禁止跳过验证步骤

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/ttk-converter/02-kernel-fields.md

@@ -0,0 +1,64 @@
+# Kernel 模式 CSV 字段规格
+
+适用于 `python3 -m ttk kernel` 命令，使用 `UniversalTestcaseStructure`。
+
+静态 shape 通过 `input_shapes` / `output_shapes` 直接指定，动态 shape 由框架自动推导（将正数维度替换为 `-1`）。
+
+## Kernel 专有字段（17 个）
+
+| 序号 | 列名 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| 10 | `op_name` | STRING | 是 | *(无)* | 算子名称（用户输入的规范名 = camel_to_snake(OP_ADD(op_type))，可能与目录名不一致）。如 `add`、`mat_mul_v3`、`lamb_next_mv`。 |
+| 11 | `input_shapes` | SHAPE_NESTED | 是 | `()` | 输入张量 shape。支持 TensorList 嵌套。用 `None` 表示可选输入。 |
+| 12 | `input_dtypes` | DTYPE_NESTED | 是 | `()` | 输入数据类型。支持 TensorList 嵌套。 |
+| 13 | `output_shapes` | SHAPE_INFER_NESTED | 是 | `None` | 输出张量 shape。支持 TensorList 嵌套和自动推断关键字。 |
+| 14 | `output_dtypes` | DTYPE_NESTED | 是 | *(无)* | 输出数据类型。支持 TensorList 嵌套。 |
+| 15 | `input_formats` | DTYPE_NESTED | 否 | `('ND',)` | 输入张量格式。 |
+| 16 | `input_ori_shapes` | SHAPE_NESTED | 否 | → `input_shapes` | 原始输入 shape（格式转换前）。 |
+| 17 | `input_ori_formats` | DTYPE_NESTED | 否 | `('ND',)` | 原始输入格式。 |
+| 18 | `output_formats` | DTYPE_NESTED | 否 | `('ND',)` | 输出张量格式。 |
+| 19 | `output_ori_shapes` | SHAPE_INFER_NESTED | 否 | `None` | 原始输出 shape。 |
+| 20 | `output_ori_formats` | DTYPE_NESTED | 否 | `('ND',)` | 原始输出格式。 |
+| 21 | `attributes` | DICT | 否 | `{}` | 算子属性（编译期和运行期合并）。 |
+| 22 | `output_inplace_indexes` | INT_TUPLE | 否 | `()` | inplace 输入的索引。Kernel CSV 生成阶段固定写入 `()`；必要的同名 inplace 由 TTK op_info 自动推导。详见 `03-kernel-mode.md`。 |
+| 23 | `output_shape_unknown_indexes` | INT_TUPLE | 否 | `()` | 编译期 shape 未知的输出索引。 |
+| 24 | `dump_file_prefix` | STRING | 否 | `None` | 数据 dump 文件的自定义文件名前缀。 |
+| 25 | `manual_input_binaries` | EVAL | 否 | `()` | 手动输入二进制文件路径。 |
+| 26 | `manual_golden_binaries` | EVAL | 否 | `()` | 手动 Golden 输出二进制文件路径。 |
+
+## CSV 列顺序（严格固定）
+
+```
+testcase_name, network_name, op_name, input_shapes, input_dtypes, input_formats, output_shapes, output_dtypes, output_formats, input_ori_shapes, input_ori_formats, output_ori_shapes, output_ori_formats, attributes, input_data_ranges, precision_tolerances, absolute_precision, output_inplace_indexes, output_shape_unknown_indexes, is_enabled, remark, soc_series, priority, dump_file_prefix, manual_input_binaries, manual_golden_binaries
+```
+
+## TensorList 嵌套结构
+
+当输入/输出为 TensorList（S5_mapping_spec.md 中 param_type=DYNAMIC）时，以下字段使用嵌套格式：外层 tuple = 各输入/输出，内层 tuple = 该 TensorList 的各子 tensor。
+
+各字段因值类型不同，DYNAMIC 格式有差异：
+
+| 字段 | REQUIRED 格式 | DYNAMIC 格式 | 说明 |
+|------|-------------|-------------|------|
+| `input_shapes` | `((1,2), (3,4))` | `(((1,2), (3,4), (5,6)),)` | 展开：每个子 tensor 对应一个 shape |
+| `input_dtypes` | `("float16", "float32")` | `(("float16",),)` | 压缩：1 dtype 广播到所有子 tensor |
+| `output_shapes` | `((1,2),)` | `(((1,2), (3,4), (5,6)),)` | 展开：每个子 tensor 对应一个 shape |
+| `output_dtypes` | `("float16",)` | `(("float16",),)` | 压缩：1 dtype 广播到所有子 tensor |
+| `input_data_ranges` | `((-10,10), (-1,1))` | `(((-10,10),(-10,10),(-10,10)),)` | **展开**：每个子 tensor 对应一个 range |
+| `precision_tolerances` | `((0.001,0.001),)` | `(((0.001,0.001),(0.001,0.001),(0.001,0.001)),)` | **展开**：每个子 tensor 对应一个 tolerance |
+
+**格式选择原因**（经 TTK 源码验证）：
+
+- **`input_shapes` / `output_shapes`**：必须展开（每个子 tensor 有独立 shape，无法广播）
+- **`input_dtypes` / `output_dtypes`**：压缩即可。TTK `_normalize_field_by_dist` 负责归一化 dtype 这类 string/scalar 字段，`_flatten_by_distribution` 的 `len(val)==1` 分支会将 `('float16',)` 自动广播到所有子 tensor
+- **`input_data_ranges` / `precision_tolerances`**：**必须展开**。range pair `(min, max)` 本身是 2 元素 tuple，TTK `_normalize_range_field_by_dist` 的 `len(field)==1` 广播分支会将 `field[0]` 整体广播，压缩嵌套 `(((-10,10),),)` 会导致每个子 tensor 收到 `((-10,10),)` 而非 `(-10,10)`，解析错误。扁平格式 `((-10,10),)` 在纯 TensorList（1 个输入）时可用，但在混合场景（TensorList + 普通 tensor）下 `_flatten_by_distribution` 会拆散 range pair，解析错误。展开嵌套是唯一通用格式
+
+`input_formats` / `output_formats` / `ori` 系列字段保持扁平格式不变（TTK 通过 `get()` 回退机制处理，无需嵌套）。
+
+混合示例（2 个输入：第 1 个 TensorList 含 3 子 tensor，第 2 个普通 tensor）：
+
+```
+input_shapes      = (((1,2), (3,4), (5,6)), (7,8))
+input_dtypes      = (("float16",), "float32")
+input_data_ranges = (((-10,10),(-10,10),(-10,10)), (-1,1))
+```

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/ttk-converter/03-kernel-mode.md

@@ -0,0 +1,142 @@
+# Kernel 模式脚本规则
+
+Kernel 模式由 `run_ttk_kernel_module.py` 固定执行。常规流程不要求 LLM 手写 CSV、逐字段复核 CSV 或手动拼接 `python3 -m ttk kernel` 命令。
+
+TTK 模块默认信任已通过 Mapper-v1 Step 5.5 校验的 `S5_cases_low.json` / `S5_cases_high.json`。Kernel 模式不重新校验 Mapper-v1 schema，仅在 CSV 生成失败、CSV 行数不一致、CSV 格式校验失败或 TTK kernel 基本执行链路失败时报告失败。
+
+## 输入
+
+| 输入 | 用途 |
+|---|---|
+| `S5_cases_low.json` | Step 5 final low cases，生成 low CSV。 |
+| `S5_cases_high.json` | Step 5 final high cases，生成 high CSV。 |
+| `{op_name}` | 作为 CSV `op_name` 列。 |
+| `{ops_test_kit_path}` | 执行 `python3 -m ttk kernel` 的 TTK 工具路径。 |
+
+Step 5 final case 的 schema 由 Mapper-v1 Step 5 文档定义，并已由 Step 5.5 最终校验脚本检查字段完整性。Kernel CSV 生成脚本直接读取 `attributes`、`const_inputs`、`inputs`、`outputs` 和 `meta`。
+
+## 输出
+
+| 输出 | 说明 |
+|---|---|
+| `ttk_{op_name}_cases_low.csv` | low 档位 Kernel CSV。 |
+| `ttk_{op_name}_cases_high.csv` | high 档位 Kernel CSV。 |
+| `ttk_precheck_report.json` | TTK 环境和 kernel gate 报告。 |
+| `ttk_{op_name}_cases_low_one_result.csv` | low 单用例 TTK kernel 验收结果。 |
+| `ttk_{op_name}_cases_high_one_result.csv` | high 单用例 TTK kernel 验收结果。 |
+| `ttk_module_report.json` | wrapper 统一结构化报告。 |
+
+## Wrapper 流程
+
+1. 调用 `scripts/ttk_generate_kernel_csv.py` 生成 low/high CSV。
+2. 调用 `scripts/ttk_validate_csv.py` 校验 low/high CSV，并对账 CSV 行数与 low/high case 数量。
+3. 调用 `scripts/ttk_precheck_env.py` 生成 `ttk_precheck_report.json`。
+4. `kernel_gate.status == "passed"` 时，串行执行 low/high 各 1 个 `python3 -m ttk kernel --golden-mode Disable` 用例。
+5. 解析 result CSV 和日志关键状态，生成 `ttk_module_report.json`。
+
+`ttk_precheck_env.py` 只检查 TTK/CANN 环境是否能启动 kernel 命令，不检查 case JSON schema，不检查额外函数注册。
+
+TTK kernel 验收固定使用 `--golden-mode Disable`，禁用参考计算函数调用，只验证 TTK 能消费 CSV、完成 kernel 编译并启动基本执行链路。
+
+## CSV 生成规则
+
+CSV 列顺序必须与 `02-kernel-fields.md` 的 Kernel CSV 列顺序完全一致。CSV 的 26 个字段全部由 `ttk_generate_kernel_csv.py` 生成，不要求 LLM 手写或复核字段提取脚本。
+
+| 规则 | 说明 |
+|---|---|
+| `attributes` | 直接合并 Step 5 final case 的 `attributes` 和 `const_inputs`。 |
+| `inputs` | 从 Step 5 final case 的 input descriptor 生成 shape、dtype、format 和 data range。 |
+| `outputs` | 从 Step 5 final case 的 output descriptor 全量生成 shape、dtype、format 和 tolerance。 |
+| `shape = null` | JSON `null` 写为 Python literal `None`，并保留 dtype、format 和位置结构。 |
+| `output_inplace_indexes` | 固定写 `()`；必要的同名 inplace 由 TTK op_info 自动推导。 |
+| `output_shape_unknown_indexes` | 固定写 `()`。 |
+| ori 系列字段 | 留空，交由 TTK 回退。 |
+| `manual_input_binaries` / `manual_golden_binaries` | 固定写 `()`，保持 TTK Kernel CSV 标准列。 |
+
+`attributes` 生成形式：
+
+```text
+attributes = {
+  **case.attributes,
+  **case.const_inputs,
+}
+```
+
+`output_inplace_indexes = ()` 会触发 TTK 的 op_info 自动推导。TTK 根据 op_info 中 input/output 名称同名关系推导 inplace 输入索引；CSV 生成器不根据算子名、shape 或 case 分布自行推断。
+
+## TensorList 规则
+
+TensorList 嵌套格式以 `02-kernel-fields.md` 为准。固定脚本负责将 Step 5 final case 中的 TensorList descriptor 转换为 TTK Kernel CSV 需要的嵌套 tuple：
+
+- `input_shapes` / `output_shapes`：展开到每个子 tensor。
+- `input_dtypes` / `output_dtypes`：使用压缩嵌套 dtype。
+- `input_data_ranges` / `precision_tolerances`：展开到每个子 tensor。
+
+## data_range 映射
+
+固定脚本按每个输入 descriptor 的 `data_range` 标签生成 TTK `input_data_ranges`。
+
+| data_range | `input_data_ranges` 生成方式 |
+|---|---|
+| `normal` | 固定 seed 随机范围。 |
+| `zero` | `(0, 0)`。 |
+| `extreme` | `(dtype_max * 0.9, dtype_max)`。 |
+| `negative` | 固定 seed 负数随机范围。 |
+| `tiny_pos` | `(1e-7, 1e-5)`。 |
+| `all_ones` | `(1, 1)`。 |
+| `near_zero` | `(-0.01, 0.01)`。 |
+| `with_inf` | `(1, float('inf'))`。 |
+| `with_nan` | `(nan, nan)`。 |
+
+固定 seed 为 `42`，保证 CSV 生成可复现。
+
+## tolerance 映射
+
+固定脚本按输出 dtype 生成 tolerance：
+
+| dtype | `(rtol, atol)` |
+|---|---|
+| `float16` | `(0.001, 0.001)` |
+| `bfloat16` | `(0.001, 0.001)` |
+| `float32` | `(0.0001, 0.0001)` |
+| 其他 dtype | `(0.001, 0.001)` |
+
+## Kernel Gate
+
+`kernel_gate.status` 只由 TTK/CANN 环境决定：
+
+| status | 含义 |
+|---|---|
+| `passed` | `ops-test-kit` 可用，且 `python3 -m ttk kernel --help` 在当前环境或 source setenv 后可运行。 |
+| `skipped` | `ops-test-kit` 不可用，或 TTK/CANN kernel 环境不可用。 |
+
+若 precheck 报告 `checks.cann_env.status == "passed_after_source"`，wrapper 使用报告中的 `setenv_path` 执行 low/high TTK kernel 命令。
+
+## 结果判定
+
+常规流程只读取 `ttk_module_report.json` 判断模块结果。
+
+| status | 含义 |
+|---|---|
+| `passed` | CSV 生成/校验通过，TTK 能消费 CSV，low/high 单用例在禁用参考计算模式下 `dyn_precision=SUPPRESSED`，且 result CSV 内联分析通过。 |
+| `skipped` | CSV 生成/校验通过，但 kernel 验收被跳过。 |
+| `failed` | CSV 阶段失败，或 TTK 无法消费 CSV/完成基本执行链路，或 result CSV 内联分析不通过。 |
+
+TTK kernel low/high 单用例串行执行，禁止并行执行，避免 TTK profiling/profiler 目录争用。
+
+TTK kernel 验收不写单用例日志文件。执行结果以命令返回码和 result CSV 为准，命令 stdout/stderr tail 保存在 `ttk_module_report.json` 对应 step 中。
+
+`--golden-mode Disable` 下，result CSV 内联分析要求目标 `testcase_name` 行存在，`dyn_precision` 为 `SUPPRESSED`，且 `memory_oob_status` 为空或 `PASS`。`dyn_precision` 对应 ttk-info.log 中的 `DYN_GOLD`，用于确认 DYN 链路未出现 `INVALID_TILING` 等前置错误；`precision_status` 不参与功能验收门禁。
+
+## 失败处理
+
+| 失败点 | 处理 |
+|---|---|
+| CSV 生成失败 | 检查 `ttk_generate_kernel_csv.py` 和 Step 5 final case。 |
+| CSV validator 失败 | 检查 CSV 字段格式和 TensorList 嵌套格式。 |
+| CSV 行数不一致 | 检查 low/high case 文件是否被并发修改，重新生成 CSV。 |
+| `env_unavailable` | 检查 `ops-test-kit` 路径、CANN 环境变量和 setenv 脚本。 |
+| kernel 命令返回非 0、无 result CSV 或 `dyn_precision` 非 `SUPPRESSED` | 核查 case shape/dtype 是否违反算子约束，并查看 `ttk_module_report.json` 中对应 step 的 stdout/stderr tail。 |
+| 目标 testcase 行缺失 | 检查 wrapper 选择的 testcase_name 与 TTK result CSV 输出是否一致。 |
+| `memory_oob_status` 非 PASS/空 | 单 case 复现，必要时进入内存/崩溃调试流程。 |
+| profiler 目录争用或 `Directory not empty` 等并发痕迹 | 按 low → high 顺序重跑单用例，不直接判为 case 失败。 |