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

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/evals/evals.json

@@ -0,0 +1,198 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "六步工作流概述",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能的完整工作流程。请依次介绍以下 7 个方面（每个方面 1-2 句话即可）：\n1. Step 1 输入收集（收集哪些参数、平台检测怎么做）\n2. Step 2 源码分析（有哪些 Phase、分别做什么）\n3. Step 3 交叉验证（验证什么、失败怎么处理）\n4. Step 4 用户确认闸门（为什么需要、能否跳过）\n5. Step 5 参数组合映射（low/high 两档位的区别）\n6. Step 6 pytest 生成与执行（精度不达标怎么处理）\n7. 可选 TTK CSV 模块（什么时候启用、产出什么）\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖 ascendc-whitebox-design 的完整工作流：\n- Step 1：收集算子名称、路径、是否跳过闸门、是否启用 TTK；平台参数由 npu-arch skill 自动检测\n- Step 2：Phase 0 文件侦察（Scout-T/Scout-K 并行）→ Phase 1 并行 Task A/B/C → Phase 2 参数推导 → Phase 3 测试设计\n- Step 3：派独立子 agent 交叉验证，fail 回 Step 2 重分析（最多 3 轮）\n- Step 4：安全闸门，展示摘要等待用户确认，可选择跳过\n- Step 5：5a 路径覆盖 → 5b 网络用例 → 5c 合并 → 5d data_range 展开为 low/high 两档位\n- Step 6：生成 pytest 脚本、执行测试、精度不达标标记 XFAIL、tilingkey 覆盖率分析\n- TTK：可选模块，生成 CSV 文件和 golden_plugin.py",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "Step 2 源码分析流程",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能中 Step 2 源码分析的完整流程。请依次介绍以下 5 个方面（每个方面 1-2 句话即可）：\n1. Phase 0 文件侦察（Scout-T 和 Scout-K 分别做什么、Scout-Verify 做什么）\n2. Phase 1 并行任务（Task A 代码路径分析、Task B 接口分析、Task C 网络搜索分别做什么）\n3. Phase 2 参数推导（Task D 做什么、输入是什么）\n4. Phase 3 测试设计（Phase 3a/3b/3c 分别做什么）\n5. 子 agent 并行派发规则（哪些任务并行、哪些串行）\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖 Step 2 的完整流程：\n- Phase 0：Scout-T 分析 tiling 入口文件和分支可达性，Scout-K 分析 kernel dispatch 和 TILING_KEY_IS，Scout-Verify 交叉比对生成 file_manifest.json\n- Phase 1：Task A 代码路径分析产 path_list.json，Task B 接口分析产 operator_model.json，Task C 网络搜索产 low_configs.json，三者并行\n- Phase 2：Task D 参数推导产 param_def.json，串行在 Phase 1 之后\n- Phase 3：3a 处理 disputed 路径、3b 生成 test_design.md、3c 生成 shape_mapping\n- 并行规则：Phase 0 的 Scout-T/K 并行，Phase 1 的 A/B/C 并行，Phase 2 串行",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "Step 5 参数组合映射",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能中 Step 5 参数组合映射的流程。请依次介绍以下 5 个方面（每个方面 1-2 句话即可）：\n1. 5a 路径覆盖用例怎么生成（输入是什么、产出是什么）\n2. 5b 网络用例怎么生成（shape_mapping 的作用）\n3. 5c 合并和空 tensor 补全怎么做\n4. 5d data_range 维度展开（low 和 high 两档位的区别）\n5. shape_mapping 异常回退怎么处理\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖 Step 5 的完整流程：\n- 5a：以 cases.json + operator_model.json 为输入，生成 case_mapper.py 和 mapped_cases_path.json\n- 5b：读取 low_configs.json，通过 shape_mapping.role 将语义参数名映射为算子参数名\n- 5c：过滤超大 tensor、合并路径+网络+空 tensor 补全，产出 mapped_cases_low.json\n- 5d：low 档位全 normal，high 档位 one-hot + 全统一展开\n- shape_mapping 异常：mapper 崩溃时回退重新派发 Task E 修正",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 4,
+      "title": "Step 6 pytest 生成与执行",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能中 Step 6 pytest 生成与执行的流程。请依次介绍以下 4 个方面（每个方面 1-2 句话即可）：\n1. 6a 生成 pytest 脚本（语法检查和收集检查怎么做）\n2. 6b 执行 pytest（FAILED/XFAIL/ERROR 分别怎么处理、精度标准能否修改）\n3. 6c tilingkey 覆盖率分析（plog 从哪来、覆盖率怎么算）\n4. 无 NPU 环境怎么兼容处理\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖 Step 6 的完整流程：\n- 6a：生成 S6_test_{op_name}.py，用 py_compile 语法检查 + pytest --collect-only 收集检查\n- 6b：FAILED 转 XFAIL（精度不达标合法）、ERROR 修复代码、精度标准 rtol/atol 禁止修改\n- 6c：从 plog 提取 tiling key 值，与 param_def.json 的 tiling_keys 期望集合对比，生成覆盖率报告\n- 无 NPU 兼容：自动跳过硬件执行标记 SKIPPED，不会报错",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 5,
+      "title": "执行约束与安全闸门",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能的执行约束和安全闸门机制。请依次介绍以下 5 个方面（每个方面 1-2 句话即可）：\n1. 全局顺序约束（禁止跳步、禁止抢跑、前置条件检查）\n2. 子 agent 规则传递原则（子 agent 自读规则、主 Agent 只传上下文参数）\n3. Step 4 安全闸门（什么时候触发、允许继续的条件、禁止抢跑规则）\n4. JSON 完整性校验（什么时候校验、失败怎么处理）\n5. 轮次耗尽协议（什么情况下触发、有哪些选项）\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖执行约束和安全闸门：\n- 全局顺序：按 Step 编号顺序执行，禁止跳步和抢跑，前置条件未满足禁止启动\n- 子 agent 规则：子 agent 自行 Read 源文件获取规则，主 Agent 只传上下文参数不转述规则\n- Step 4 闸门：完成 Step 3 后必须停下展示摘要等待用户确认，用户确认前禁止生成 Step 5 产物\n- JSON 校验：读取子 agent 产出 JSON 后立即验证可解析，失败重试最多 1 次\n- 轮次耗尽：达到最大轮次仍未通过时向用户报告，提供强制继续/终止/手动修正三个选项",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 6,
+      "title": "TTK CSV 可选模块",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请加载 ascendc-whitebox-design 技能，并依据该技能当前版本目录下的文档（references/workflow.md 与 references/ttk-converter/00-execution-order.md）介绍其 TTK CSV 模块。请依次说明以下 4 个方面（每个方面 1-2 句话即可）：\n1. 触发条件与执行主体（该模块在流程的哪一步之后、由谁执行、入口脚本是什么）\n2. 产出文件有哪些（CSV 与其他报告文件）\n3. TTK kernel 验收的运行方式（用什么命令、golden-mode 如何设置）\n4. 输入缺失时的分级处理与最终结论口径\n可阅读该技能文档，但不要执行任何脚本或修改代码。",
+      "expected_output": "1. 回复应说明触发条件与执行主体：TTK 模块不是 Step 1 的可选输入，而是 Step 5.5 final schema 校验通过后由主 Agent 必须执行的固定环节；执行入口是 scripts/run_ttk_kernel_module.py，常规流程不派发 TTK 子 agent。\n2. 回复应列出 TTK 模块的产出文件：ttk_{op_name}_cases_low.csv、ttk_{op_name}_cases_high.csv、ttk_precheck_report.json、ttk_{op_name}_cases_low_one_result.csv / ttk_{op_name}_cases_high_one_result.csv、ttk_module_report.json；并说明 kernel 验收固定以 --golden-mode Disable 运行，不产出 golden_plugin.py。\n3. 回复应说明 TTK 模块的限制与结论口径：kernel 步固定执行 python3 -m ttk kernel；CSV 必需输入（S5_cases_low.json / S5_cases_high.json 与三个 ttk_*.py 固定脚本）缺失则模块 failed，kernel 环境（ops-test-kit/、CANN 环境）缺失则 CSV 仍生成、kernel 验收 skipped；对模块给结论只读 ttk_module_report.json 的 acceptance.accepted / acceptance.status，不能用 kernel_gate.status 代替。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 7,
+      "title": "正向看护-多 skill 环境下正确触发",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "ascendc-ut-develop",
+          "ascendc-st-design",
+          "ascendc-code-review",
+          "ascendc-api-best-practices"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能的核心功能和适用场景。请简要说明以下 3 个方面：\n1. 这个技能做什么（核心能力）\n2. 什么时候使用（触发关键词）\n3. 与 ascendc-ut-develop 和 ascendc-st-design 的区别\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应说明 ascendc-whitebox-design 技能的核心能力：\n- 核心功能：分析算子源码提取参数维度，自动枚举参数组合，生成白盒测试用例\n- 触发场景：用户要求\"为 X 算子生成白盒测试用例\"、\"算子白盒用例生成\"、\"路径覆盖\"\n- 与 UT/ST 的区别：白盒测试是基于源码分析自动枚举参数组合生成用例，UT 是手工编写单元测试，ST 是系统测试\n回复应准确描述白盒测试的特点，即使不激活 skill 工具也应基于已有知识正确回答。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 8,
+      "title": "信息不足时主动追问",
+      "config": {
+        "max_tokens": 150000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 180000,
+          "glm-5": 160000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "帮我生成白盒测试用例",
+      "expected_output": "回复应主动追问关键信息，而不是直接开始生成用例。应至少询问以下信息中的一项或多项：算子名称、算子路径、是否跳过 Step 4 闸门、是否启用 TTK CSV 模块。不应在缺乏算子规格的情况下直接生成测试用例。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 9,
+      "title": "使用边界-不适用于 ST/UT 测试",
+      "config": {
+        "max_tokens": 150000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 180000,
+          "glm-5": 160000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我想用 ascendc-whitebox-design 这个技能来为我的算子编写系统测试（ST）用例，或者编写单元测试（UT）用例，这个技能适合吗？请详细说明这个技能的适用边界和不适用场景。",
+      "expected_output": "回复应明确说明 ascendc-whitebox-design 不适用于 ST 或 UT 测试。应说明：\n- 本技能的定位：白盒测试用例生成系统，基于源码分析自动枚举参数组合\n- 适用场景：用户要求为算子生成白盒测试用例、路径覆盖用例\n- 不适用场景：ST 系统测试（应使用 ascendc-st-design）、UT 单元测试（应使用 ascendc-ut-develop）\n- 白盒测试与 ST/UT 的核心区别：白盒是自动化源码分析+参数枚举，ST 是系统级功能验证，UT 是手工编写单元测试",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 10,
+      "title": "最终产物清单",
+      "config": {
+        "max_tokens": 200000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 240000,
+          "glm-5": 220000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "请介绍 ascendc-whitebox-design 技能执行完成后会生成哪些产物文件。请依次介绍以下 4 个方面（每个方面 1-2 句话即可）：\n1. Step 2 产物（S2P0/S2P1/S2P2/S2P3 分别是什么文件、做什么用）\n2. Step 3 和 Step 5 产物（验证报告、映射用例文件）\n3. Step 6 产物（pytest 脚本、tilingkey 覆盖率报告）\n4. TTK 模块产物（CSV 文件、golden_plugin.py）\n不需要执行任何操作，只需要介绍知识。",
+      "expected_output": "回复应覆盖最终产物清单：\n- Step 2：S2P0_scout_t.md（tiling 侦察）、S2P0_scout_k.md（kernel 侦察）、S2P1_path_list.json（路径清单）、S2P2_param_def.json（参数定义）、S2P3_test_design.md（测试设计）\n- Step 3/5：S3_verification_report.json（交叉验证结果）、S5_mapped_cases_low.json（low 档位用例）、S5_mapped_cases_high.json（high 档位用例）\n- Step 6：S6_test_{op_name}.py（pytest 脚本）、S6_tilingkey_coverage.json（tilingkey 覆盖率）\n- TTK：ttk_{op_name}_cases_low.csv、ttk_{op_name}_cases_full.csv、golden_plugin.py\n所有产物写入 {算子路径}/tests/whitebox/ 目录",
+      "files": [],
+      "expectations": []
+    }
+  ],
+  "skill_name": "ascendc-whitebox-design"
+}

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/S1-input-collection.md

@@ -0,0 +1,125 @@
+# Step 1：输入收集
+
+## 全局约束（强制）
+
+**顺序**：1.0 → 1.1 → 1.2 → 1.3 → 1.4，严格逐步执行，禁止合并、跳过或重排。
+
+**禁止抢跑**：每步仅允许其自身描述的操作（如 1.0 仅允许平台检测，1.1 才能用 question，1.2 才能搜索路径），前一步未完成不得启动下一步。
+
+**question 工具规范（Step 1.1 专用）**：
+- 单次调用，所有未收集参数作为 `questions` 数组的独立元素逐项呈现（独立 header、独立 question、独立 options）
+- 禁止创建"全部使用默认值"或"自定义参数"等聚合选项
+- 已从用户消息或前置步骤获取的值，以文字回显，不再放入 questions 数组
+
+---
+
+## 1.0 平台检测
+
+执行 `npu-smi info` 获取当前 NPU 设备信息，从输出中识别芯片名称（Name 列）。**禁止猜测和推导**——必须以硬件检测结果为准。
+
+检测方式（按优先级降级）：
+1. 执行 `npu-smi info`，从输出中识别芯片名称
+2. 若 npu-smi 不可用 → 读取环境变量 `$ASCEND_SOC_VERSION`
+3. 两者均不可用 → 报告「无法检测 NPU 平台，请手动指定」，等待用户输入
+
+> **注意**：禁止使用 `npu-smi info -t board -i 0`（硬编码卡号 0）。
+
+将检测到的芯片名称，结合 `npu-arch` skill 的 `references/npu-hardware-params.md §0 产品映射表` 确定 `npu_arch`（如 DAV_3510/DAV_2201）和 `soc_version`（如 ASCEND950/ASCEND910B）。§0 表中芯片型号列为模糊匹配（如 `910B3` 匹配 `Ascend910B1~B4`）。
+
+产出：`npu_arch`、`soc_version`、`chip_model`。
+
+---
+
+## 1.1 收集用户输入
+
+在 Step 1.0 完成后，使用 question 工具收集以下 3 项输入（已从用户消息或前置步骤获取的值以文字回显，仅将未收集项作为 questions 数组中的独立条目）。
+
+| # | 项 | 提示语 | 必填 | 默认值/可选值 |
+|---|-----|-------|------|-------------|
+| 1 | 算子名称 | "请输入算子名称" | 是 | 自由文本 |
+| 2 | Step 4 闸门 | "是否跳过 Step 4 闸门？" | 是 | 默认不跳过；可选跳过（一次跑完全流程） |
+| 3 | 算子路径 | "请选择算子路径获取方式：自动查找 / 手动输入路径" | 是 | 默认「自动查找」 |
+
+---
+
+## 1.2 定位算子路径
+
+> ⚠️ **本步骤由主 Agent 直接执行。禁止派发子 agent。禁止使用 Task 工具。只能使用 Bash 工具执行 find 命令。**
+
+在 Step 1.1 完成后执行。由用户对「算子路径」的选择驱动：
+- 选择「自动查找」→ 执行以下搜索逻辑，定位算子路径。
+- 选择「手动输入」→ 仅验证用户提供的路径（确认 op_kernel/ 和 op_host/ 目录存在），验证通过则跳过搜索，直接进入 Step 1.3。
+
+**「自动查找」分支（两阶段）**：
+
+> **前提**：用户输入的 `op_name` 始终视为正确的规范名（camel_to_snake(OP_ADD(op_type)) 的结果）。查找失败时不质疑用户输入，而是切换查找策略。
+
+**Phase 1（目录名匹配）**：
+
+> **查找方式（强制）**：限定**当前工作目录（$PWD）**，禁止跨目录搜索。使用 bash `find $PWD -maxdepth 4 -type d -regex '.*/ops-[^/]+/[^/]+/{op_name}'` 按目录名精确匹配（禁止子串匹配）。禁止派发子 agent。
+
+主 Agent 验证每个候选目录同时存在 op_kernel/ 和 op_host/，过滤不合格项。唯一结果→使用；多项→让用户选择。**未找到→进入 Phase 2**。
+
+**Phase 2（OP_ADD 反查）**：
+
+> 当 Phase 1 按目录名未找到时，说明算子目录名与规范 op_name 不一致（如目录 `lamb_next_m_v`，规范名 `lamb_next_mv`）。通过 `_def.cpp` 中的 `OP_ADD(op_type)` 反查。
+
+```bash
+python3 {skill_base}/scripts/normalize_op_name.py find --op-name {op_name} --search-root $PWD
+```
+
+- 输出 `op_path` 非空 → 使用该路径（唯一结果直接使用；多候选→让用户选择）
+- 输出 `op_path` 为空 → 报告"未找到"，不得扩大搜索范围
+
+**「手动输入」分支**：
+
+验证用户提供的路径下存在 `op_kernel/` 和 `op_host/` 目录。验证失败→报错并要求用户修正路径。
+
+---
+
+## 1.3 查询技术参数
+
+在 Step 1.2 完成后执行。加载 `npu-arch` skill，Read `references/npu-hardware-params.md`，按以下规则获取平台参数：
+
+1. **VectorCore 核数**：从 §子型号变化参数 读取匹配 chip_model 的 VectorCore 数（§中 CubeCore:VectorCore = 1:2，取 VectorCore 列）。若存在多个子型号（如 Ascend950PR 有 PCIE/Server），通过 Step 1.0 `npu-smi info` 输出中的 HBM-Usage 容量区分（112 GB=PCIE，128 GB=Server）。
+2. **UB 大小**：从 §2 各架构参数 读取对应 NpuArch 的 `ub_size` 值。
+
+以 `platform` 对象传递给子 agent，字段为 `npu_arch` / `soc_version` / `chip_model` / `core_count`（VectorCore 数） / `ub_size`（单位 KB）。
+
+---
+
+## 1.4 确认摘要
+
+在 Step 1.0-1.3 全部完成后执行。**必须使用 question 工具**展示确认摘要并等待用户确认，禁止仅以文字输出方式等待用户回复。
+
+**question 工具规范（Step 1.4 专用）**：
+- 必须使用 question 工具的单次调用，将确认摘要作为 `question` 字段内容
+- `options` 必须包含「确认，开始分析」和「需要修改」两个选项
+- 禁止仅以文字输出（非 question 工具）展示摘要后等待用户回复
+
+确认摘要内容（填入实际值后作为 question 字段）：
+
+```
+── 硬件参数（自动检测）──
+目标平台 {chip_model}（{npu_arch}），将使用 {core_count} 核、{ub_size}KB UB。
+── 用户输入 ──
+- 算子名称：{op_name}
+- 算子路径：{op_path}
+- Step 4 闸门：{gate_status}
+
+结果输出到 {算子源码路径}/tests/whitebox/。
+如需修改核数、UB 大小，或有额外特殊条件需添加，请告知。
+确认后开始分析。
+```
+
+占位符填入规则：
+- `{chip_model}`/`{npu_arch}`/`{core_count}`/`{ub_size}` — 由 Step 1.0 检测 + 1.3 映射
+- `{op_name}`/`{op_path}`/`{gate_status}` — 由 Step 1.1 用户输入
+- `{算子源码路径}` — 即 Step 1.2 确定的算子路径
+
+question 工具选项定义：
+
+| 选项 label | 选项 description |
+|------------|-----------------|
+| 确认，开始分析 | 所有参数正确，进入 Step 2 |
+| 需要修改 | 核数/UB — 主 Agent 更新 `platform` 对象后回到 1.4 重新展示；其它参数 — 回到 1.1 重新收集 |

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

@@ -0,0 +1,58 @@
+# Case Mapper v1 执行总纲
+
+> **目标**：按顺序将 Step 2 最终事实产物中的 path case 和 network config 翻译为下游可消费的 Mapper-v1 固定 schema cases，并生成 final low/high whitebox cases。
+
+## 读取规则（强制）
+
+1. 读完本文件后，按“执行顺序约束”表逐 Step Read 并执行。**每完成一个 Step 的状态判断后，才能读取下一个 Step 的指导文件、模板或固定脚本。**
+2. 禁止在 Step 5.1 之前读取 `01-variable-semantics.md` 以外的 Step 子文件、`s5_case_mapper_template.py` 或 Step 5.3/5.4/5.5 固定脚本；禁止一次性 Read 全部流程文档和模板。
+3. 当前 Step 只读取当前行列出的指导文件、模板、固定命令、前置产物及其运行所需的最小输入。不得为了预先规划、补充背景或重复理解而读取后续 Step 内容。
+4. 后续 Step 所需语义必须优先通过前序产物传递，例如 `S5_variable_semantics.md`、mapped JSON、`S5_cases_low.json` 和 `S5_cases_high.json`。不得预读后续 Step 或回读 Step 2 推理链补齐。
+5. 如果当前 Step 的允许输入和前序产物无法解释必需语义，必须报告 Step 2 语义产物不完整；不得读取禁止输入、源码或后续 Step 内容补齐。
+
+## 执行顺序约束（强制）
+
+以下 Steps 必须按编号顺序逐步骤执行，禁止跳步或抢跑。
+
+| Step | 角色 | 核心产物 | 进入下一步条件 |
+|------|------|----------|----------------|
+| Step 5.1：理解变量语义 | LLM 分析阶段，整理 mapper 所需语义、`attributes` / `const_inputs` policy 和 data_range policy。 | `S5_variable_semantics.md`、`S5_data_range_policy.json` | 两个产物已写入，mapper 必需字段已有明确语义，且字段去向符合 Mapper-v1 schema。 |
+| Step 5.2：生成 Mapper-v1 Low Shape Cases | LLM 代码生成阶段，基于模板生成 `S5_case_mapper.py` 并产出符合 Mapper-v1 固定 schema 的 shape low 中间用例。 | `S5_case_mapper.py`、`S5_mapped_cases_path.json`、`S5_mapped_cases_network.json`、`S5_mapped_cases_low_shape.json` | Step 5.2 产物已写入，脚本无模板残留，输出 JSON 符合 `S5_case_json_schema.md`。 |
+| Step 5.3：追加 Empty Low Cases | 固定脚本阶段，读取 shape low 中间用例，机械追加 empty cases，生成最终 low 用例文件。 | `S5_cases_low.json` | 命令退出码为 0，并输出 `PASS: appended empty cases`。 |
+| Step 5.4：生成 High Data Range Cases | 固定脚本阶段，读取最终 low 用例和 data_range policy，生成 high 档用例。 | `S5_cases_high.json` | 命令退出码为 0，并输出 `PASS: expanded high data_range cases`。 |
+| Step 5.5：Final Low/High Schema 验证 | 固定脚本验收阶段，只检查最终 `S5_cases_low.json` 和 `S5_cases_high.json` 的 Mapper-v1 结构、字段完整性和基础类型。 | 验收结果 | 命令退出码为 0，并输出 `PASS: mapper schema accepted`。 |
+
+固定命令：
+
+```bash
+python -m py_compile .opencode/skills/ascendc-whitebox-design/scripts/s5_append_empty.py
+python .opencode/skills/ascendc-whitebox-design/scripts/s5_append_empty.py --whitebox-dir <operator>/tests/whitebox
+python -m py_compile .opencode/skills/ascendc-whitebox-design/scripts/s5_expand_high.py
+python .opencode/skills/ascendc-whitebox-design/scripts/s5_expand_high.py --whitebox-dir <operator>/tests/whitebox
+python .opencode/skills/ascendc-whitebox-design/scripts/s5_check_mapper_outputs.py --whitebox-dir <operator>/tests/whitebox
+```
+
+Step 5.3 固定脚本位于 `.opencode/skills/ascendc-whitebox-design/scripts/s5_append_empty.py`，Step 5.4 固定脚本位于 `.opencode/skills/ascendc-whitebox-design/scripts/s5_expand_high.py`，Step 5.5 固定脚本位于 `.opencode/skills/ascendc-whitebox-design/scripts/s5_check_mapper_outputs.py`。这些固定脚本都不需要 LLM 修改，也不需要在 whitebox 目录生成本地展开脚本。
+
+**完成标志**：Step 5.1 产出语义与 policy；Step 5.2 产出 path/network 审计产物和 `S5_mapped_cases_low_shape.json`；Step 5.3 产出最终 `S5_cases_low.json`；Step 5.4 产出最终 `S5_cases_high.json`；Step 5.5 最终 low/high schema 验证通过。最终 `S5_case_mapper.py` 无模板残留，Step 5.3/5.4/5.5 固定脚本可直接执行。
+
+## 通用规则
+
+- 前置条件表中标明的条件未全部满足时，禁止启动该 Step 的任何操作。
+- 完成当前 Step 的全部子步骤并确认状态判断满足后，才能进入下一 Step。
+- 自检失败时，回到对应 Step 修复；修复完成并重新满足状态判断后方可继续。
+- Step 5 只允许写入 `S5*` 命名产物；禁止写入、覆盖或新建 `S1*`、`S2*`、`S3*`、`S4*` 文件，这些前缀保留给上游 Step。
+- 禁止读取 `S2P2_traceability.md`、`S2P2_param_def.json`、`S2P2_dim_spec.json`、`S2P1_path_list.json` 补字段语义；这些属于 Step 2 推理链、生成规格或路径枚举，不是 Mapper 输入。
+- 禁止读取 tiling、kernel、`_def.cpp` 或注册源码重新推导 path、tiling key、mode、接口、shape 或 case 字段语义。
+- `S5_variable_semantics.md` 和 `S5_data_range_policy.json` 是 Step 5.1 的产物，不是上游事实来源；事实来源仍是 Step 2 允许读取的最终产物。`S5_variable_semantics.md` 承载审查说明和 mapper 语义，`S5_data_range_policy.json` 承载唯一 data_range policy。
+- Mapper-v1 输出 schema 以 `S5_case_json_schema.md` 为准；流程文档不得重新定义或放宽字段结构。
+
+## ID 命名规范
+
+| 类型 | 格式 |
+|------|------|
+| path audit | `case{index:05d}` |
+| network audit | `network{index:05d}` |
+| shape low case | `low_case_{index:02d}` |
+| empty low case | `low_case_empty_{index:02d}` |
+| range high case | `{low_case_id}_range{index:02d}` |

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/case-mapper/01-variable-semantics.md

@@ -0,0 +1,250 @@
+# Step 5.1：变量语义与 Mapper 指导书生成
+
+> **职责**：将 Step 2 最终事实产物翻译为 Step 5.2 可直接实现的 mapper 代码指导书，并生成算子级 `S5_data_range_policy.json`。本步骤不重新分析源码。
+
+`S5_variable_semantics.md` 是 Step 5.2 的 mapper 代码指导书，不是仅供阅读的语义摘要。它必须把 Step 5.2 需要实现的 dtype 规则、format 规则、`attributes` 构造规则、`const_inputs` 构造规则、input shape assembly plan、rank 覆盖目标、output 派生规则、network mapping 和 mapper 注意事项写到可直接编码的程度。
+
+Step 5.2 只负责翻译执行这份指导书，生成 `S5_case_mapper.py` 和 low 档 mapped cases；Step 5.2 不负责重新设计变量语义、rank 覆盖策略或 shape 组装方案。若 Step 5.2 仍需自行猜测变量语义、rank 选择、axis group、shape 拆分、execution value 构造或 output 派生规则，则 Step 5.1 未完成。
+
+## Step 5.1 输入输出
+
+输入：
+
+- `S2P1_operator_model.json`
+- `S2P2_cases.json` 前 30 行
+- `S2P1_low_configs.json` 前 30 行
+- `S2P1_tiling_glossary.md`
+- `infershape.cpp` output shape 相关片段，仅在 operator model output shape 信息不足时按需读取
+
+输出：
+
+- `S5_variable_semantics.md`：Step 5.2 的 mapper 代码指导书，必须写到可直接实现 `S5_case_mapper.py` 的程度。
+- `S5_data_range_policy.json`：data_range 扩展策略，供 Step 5.4 静态展开阶段使用。
+
+不输出：
+
+- `S5_case_mapper.py`
+- `S5_mapped_cases_path.json`、`S5_mapped_cases_network.json`
+- `S5_mapped_cases_low_shape.json`、`S5_cases_low.json`、`S5_cases_high.json`
+- 任何 `S1*`、`S2*`、`S3*`、`S4*` 文件
+
+## 输入读取
+
+Step 5.1 只读取 mapper 消费所需的最终事实产物。禁止读取 Step 2 推理链、生成规格或源码补字段语义。
+
+### 必读
+
+| 文件 | 用途 |
+|------|------|
+| `S2P1_operator_model.json` | input/output/attribute/const input 结构、dtype/rank/shape 约束、param_type、output shape rule。 |
+| `S2P2_cases.json` 前 30 行 | 确认 path case 字段形态。批量处理由 Step 5.2 脚本运行时 `json.load` 完成。 |
+| `S2P1_low_configs.json` 前 30 行 | 确认 network config 字段形态。批量处理由 Step 5.2 脚本运行时 `json.load` 完成。 |
+| `S2P1_tiling_glossary.md` | 解释 case/config 字段最终语义，并提供变量对 input/output shape 的贡献关系（`shape_contribution`）。 |
+
+读取 `S2P2_cases.json` 和 `S2P1_low_configs.json` 样本时，必须使用 Read 工具的 `offset=1, limit=30`，禁止全文读取。
+
+### 按需
+
+仅当 operator model 的 output shape 信息不足时，读取 `infershape.cpp` 的 output shape 片段。读取范围只限 output shape，不得用于补 tiling、kernel、接口或 case 字段语义。
+
+如果 `S2P1_tiling_glossary.md` 无法解释 mapper 必需字段，Step 5.1 必须报告 Step 2 语义产物不完整，不得读取推理链、生成规格或路径枚举补齐。
+
+## 功能 A：生成 Step 5.2 代码指导书
+
+本功能输出 `S5_variable_semantics.md`。该文件是 Step 5.2 生成 `S5_case_mapper.py` 的 mapper 代码指导书，必须把 mapper 需要实现的语义和构造规则写到可直接编码的程度。
+
+`S5_variable_semantics.md` 的正文说明必须使用中文。代码标识符、JSON 字段名、函数名、dtype 名称、源码变量名、case 字段名和伪代码变量名保持原文，不翻译。若上游事实产物中的自然语言为英文，Step 5.1 应将其语义转写为中文说明，但不得改写其中的代码表达式或字段名。
+
+Step 5.1 必须把 Step 5.2 要实现的逻辑写清楚，包括 dtype 规则、format 规则、`attributes` / `const_inputs` 构造规则、input shape assembly plan、rank 覆盖目标、output 派生规则、network mapping 和 mapper notes。
+
+### 必填主题
+
+`S5_variable_semantics.md` 必须按以下章节组织。每个章节都应提供 Step 5.2 生成 mapper 代码所需的规则；不适用内容写“不适用”，不得省略章节。
+
+| 章节 | 指导书内容 |
+|------|------------|
+| `dtype` | dtype 控制字段、合法值、名称归一化、input/output dtype 同步或固定规则。 |
+| `format` | input/output format 构造规则；默认 `ND`，若 path/config 明确存在 format 约束，则按当前 case 的 path/config 信息写入对应 format。 |
+| `input shapes` | 主输入判定、shape assembly plan、依赖 input shape 规则；必须包含 Step 5.2 可直接实现的自然语言规则或伪代码。 |
+| `shape coverage plan` | 主输入合法维度结构覆盖目标，并明确主输入 rank 覆盖目标。依赖 input 和 output 不作为独立覆盖目标。 |
+| `outputs` | output dtype、shape、optional placeholder 规则；shape 只从 input 或明确字段派生。 |
+| `execution values` | `attributes` 和 `const_inputs` 构造规则；说明 operator attributes、`.ValueDepend()` const input values、默认值如何注入，以及哪些字段只进入 dtype/format/shape/meta。 |
+| `network mapping` | network config 到算子参数空间的映射；network-only 信息放入 `meta`。 |
+| `mapper notes` | 保留的 meta 字段、边界条件、禁止猜测项。 |
+
+### Shape Assembly Plan 要求
+
+`input shapes` 是 `S5_variable_semantics.md` 中最关键的代码指导章节。Step 5.1 必须在这里写出 shape assembly plan；Step 5.2 只能实现该 plan，不得重新设计 shape 组装策略。
+
+shape assembly plan 至少说明：
+
+- 主输入是谁。
+- 主输入 rank 如何选择或覆盖。
+- 主输入各轴如何取值。
+- 参与 shape construction 的字段及其语义。
+- 每个 product / shape_size / aligned_size 字段对应的 axis group。
+- 依赖 input 如何同步、broadcast 或派生。
+- optional input 不输入时如何保留 descriptor 并写 `shape = null`。
+- output shape 派生所需的 input 关系。
+- Step 5.2 可直接实现的自然语言规则或伪代码。
+
+如果存在 `shape_contribution.shape_relation`，必须使用其中的变量关系约束 shape 组装。product 变量必须拆到对应 axis group；shape_size 或 aligned_size 变量必须说明它们如何约束 shape 或派生字段。
+
+如果不存在 shape 变量关系，也必须根据 `S2P1_operator_model.json` 的 rank/shape 约束给出默认 shape 采样方案。默认方案应说明 rank 覆盖目标、单轴上限、元素量上限和 dependent input 派生规则。
+
+`representative` 只能作为一个构造样例，不能替代 rank 覆盖方案或 shape assembly plan。
+
+### Execution Values 要求
+
+`execution values` 章节必须明确每个非 tensor 执行值写入哪个字段：
+
+- `.Attr("...")` 注册的 operator attribute 写入 `attributes`。
+- `.ValueDepend()` 标记的 const input value 写入 `const_inputs`。
+- Tensor/TensorList descriptor 写入 `inputs` 或 `outputs`，不得写入 `const_inputs`。
+- shape、dtype、format、data_range、tiling/router 信息和 mapper 审计字段不得写入 `attributes` 或 `const_inputs`。
+- `attributes` 和 `const_inputs` 不得同名重复。
+
+Step 5.1 必须说明默认值如何注入 `attributes` 或 `const_inputs`，以及哪些 case/config 字段仅用于 dtype、format、shape 或 `meta`。
+
+### Output 要求
+
+`outputs` 章节必须说明每个 output 的 dtype、format、param_type 和 shape 派生规则。outputs 必须由 mapper 完整生成，后续脚本不得推导 outputs。
+
+optional output 不输出时必须保留原 output 名并写 `shape = null`。output 任何层级不得包含 `data_range`。
+
+### S5_variable_semantics.md 输出契约
+
+必须写入以下章节。缺少不适用内容时写“不适用”，不要省略章节。
+
+```markdown
+# {op_name} Step 5 Variable Semantics
+
+> 本文件是 Step 5.2 的 mapper 代码指导书。Step 5.2 必须将本文规则翻译为 `S5_case_mapper.py`，不得重新设计变量语义、rank 覆盖策略、execution value 构造或 shape 组装方案。
+> 正文说明使用中文；代码标识符、JSON 字段名、函数名、dtype 名称、源码变量名、case 字段名和伪代码变量名保持原文。
+
+## dtype
+说明 dtype 控制字段、合法值、名称归一化、input/output dtype 同步或固定关系。
+
+## format
+说明 input/output format 构造规则。默认情况下所有 input/output 使用 `ND`；若 Step 2 path/tiling 分析、path case 字段、network config 或 operator model 明确存在 format 约束，Step 5 mapper 必须按当前 case 的 path/config 信息写入对应 format。empty case 和 high data_range case 必须继承原始 low case 的 format，不得修改。
+
+## input shapes
+说明主输入判定、主输入 shape construction、依赖 input shape 关系，并给出 shape assembly plan。无论是否存在 shape_contribution，shape assembly plan 都必须说明 Step 5.2 如何生成具体 input shape；若存在 product/shape_size/aligned_size 变量，必须说明字段到 axis group 的映射、rank 覆盖或过滤规则、shape 拆分方案和 dependent input 规则。必须给出自然语言规则或伪代码。
+
+## shape coverage plan
+说明主输入合法维度结构覆盖目标和主输入 rank 覆盖目标；若未覆盖 operator model 的完整 rank 范围，说明过滤后的 rank 集合或范围及原因。依赖 input 和 output 不作为独立覆盖目标。
+
+## outputs
+说明 output dtype、format、param_type、shape 和 optional placeholder 规则。optional output 不输出时保留 descriptor，并使用 `shape = null`。
+
+## execution values
+说明 Mapper-v1 的 `attributes` 和 `const_inputs` 如何构造。`attributes` 只写 operator attributes，`const_inputs` 只写 `.ValueDepend()` 标记的 const input values；默认值如何注入也必须在本节说明。
+
+本节还必须明确哪些 case/config 字段仅用于 dtype、format、shape 或 `meta`，不得进入 `attributes` 或 `const_inputs`。白盒路径、tiling key、group、shape 构造变量、case 来源、网络来源等 tiling/router 信息和 mapper 审计字段必须放入 `meta`。
+
+## network mapping
+说明 network config 如何映射到 `attributes`、`const_inputs`、`inputs`、`outputs` 和 `meta`。
+
+## mapper notes
+说明边界条件、保留 meta 字段和禁止猜测项。
+```
+
+## 功能 B：data_range policy 建模
+
+`S5_data_range_policy.json` 描述每个 input tensor 是否参与 data_range expansion，以及支持哪些标准非 `normal` data_range。
+
+本功能只消费功能 A 已明确的 input tensor 语义，不重新推理字段语义，不读取额外输入。
+
+### 标准 data_range
+
+Step 5.1 只能从以下标准 data_range 中选择，禁止自造类型。
+
+| data_range | 用途 |
+|------------|------|
+| `normal` | base/low case 默认数据范围，不允许出现在 policy 的 `supported` 中 |
+| `zero` | 0 值边界 |
+| `extreme` | dtype 范围内极大/极小值 |
+| `negative` | 负值数据 |
+| `tiny_pos` | 很小的正数 |
+| `all_ones` | 全 1 |
+| `near_zero` | 接近 0 的非零值 |
+| `with_inf` | 包含 inf，仅适用于支持 inf 的浮点输入 |
+| `with_nan` | 包含 nan，仅适用于支持 nan 的浮点输入 |
+
+`S5_data_range_policy.json` 中的 `supported` 只能包含非 `normal` 类型：`zero`、`extreme`、`negative`、`tiny_pos`、`all_ones`、`near_zero`、`with_inf`、`with_nan`。
+
+### S5_data_range_policy.json 输出形式
+
+输出文件 `S5_data_range_policy.json`，供 Step 5.4 静态展开读取。
+
+文件必须使用以下格式：
+
+```json
+{
+  "version": 1,
+  "mode": "per_input_cyclic",
+  "inputs": {
+    "input_name": {
+      "participates": true,
+      "supported": ["zero", "extreme", "negative", "tiny_pos", "all_ones", "near_zero", "with_inf", "with_nan"]
+    }
+  }
+}
+```
+
+字段规则：
+
+- `version` 固定为 `1`。
+- `mode` 固定为 `per_input_cyclic`。
+- `inputs` 必须覆盖算子的所有 input descriptor，key 使用 input 名。
+- 每个 input 只包含 `participates` 和 `supported`。
+- `participates=true` 时，`supported` 写该 input 支持的标准非 `normal` data_range。
+- `participates=false` 时，`supported` 必须为 `[]`。
+
+`S5_data_range_policy.json` 不得包含 case 级内容：
+
+- mapped case 字段，如 `id`、`source`、`attributes`、`const_inputs`。
+- tensor 实例内容，如 input/output shape、dtype、format、param_type、data_range。
+- low/high/empty/shape/range variants。
+- range 展开状态，如 `range_by_input`、`range_index` 或展开结果。
+
+Step 5.2 不生成或修改 `S5_data_range_policy.json`。Step 5.4 直接读取该文件，并由静态区执行 per-input cyclic expansion。
+
+## 输出 descriptor 规则
+
+优先使用 `S2P1_operator_model.json.outputs[*]` 中的 output dtype、shape、param_type 和 TensorList 信息：
+
+- `same_as_input`：直接复用对应 input shape。
+- `fixed`：使用固定 shape。
+- `derived`：按 operator model 表达式或结构化规则派生。
+
+仅当 operator model 信息不足时，读取 `infershape.cpp` 的 output shape 片段。不得借此补 tiling、kernel、接口或 case 字段语义。
+
+output descriptor 派生规则必须写入 `S5_variable_semantics.md` 的 `outputs` 章节，达到 Step 5.2 可直接实现 `derive_outputs(inputs, attributes, const_inputs, meta)` 的程度。
+
+## 完成条件
+
+- `S5_variable_semantics.md` 已写入，且内容足以指导 Step 5.2 生成 `S5_case_mapper.py`。
+- `S5_variable_semantics.md` 包含完整 shape assembly plan；无论是否存在 shape 变量，Step 5.2 都能据此生成具体 input shape。
+- 若存在 product / shape_size / aligned_size 变量，已说明字段语义、axis group、rank 覆盖或过滤、shape 拆分方案、dependent input 规则和 output 派生关系。
+- 若不存在 shape 变量，已说明默认 shape 采样方案、rank 覆盖目标、单轴上限、元素量上限和 dependent input 派生规则。
+- `S5_variable_semantics.md` 已说明 input/output format 构造规则；默认 `ND`，存在 path/config format 约束时已说明如何按当前 case 写入对应 format。
+- `S5_variable_semantics.md` 已说明 `attributes` 与 `const_inputs` 如何构造，以及哪些字段不进入二者。
+- `S5_variable_semantics.md` 已说明 outputs 完整 descriptor 的生成规则，且能直接指导 `derive_outputs(...)` 实现。
+- `S5_data_range_policy.json` 已写入，且不包含 case 级内容或展开结果。
+- 若 Step 5.2 仍需自行猜测变量语义、rank 选择、axis group、shape 拆分或 output 派生规则，则 Step 5.1 未完成。
+
+## 禁止事项
+
+输入边界：
+
+- 禁止读取 `S2P2_traceability.md`、`S2P2_param_def.json`、`S2P2_dim_spec.json`、`S2P1_path_list.json` 补语义。
+- 禁止读取 tiling、kernel、`_def.cpp` 或注册源码补 shape、接口、mode、tiling key 或 case 字段语义。
+- 禁止修改 `S2P1_*`、`S2P2_*` 输入产物。
+
+语义边界：
+
+- 禁止凭字段名猜测语义。
+- 禁止只写 representative 示例而不写 shape assembly plan。
+- 禁止把 Step 5.2 的 shape 组装设计留空，让 Step 5.2 自行发挥。
+- 禁止把 shape、dtype、format、data_range、tiling/router 信息或 mapper 审计字段写入 `attributes` 或 `const_inputs`。