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

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/source-analysis/04-test-design-template.md

@@ -0,0 +1,231 @@
+# S2P3_test_design.md 模板
+
+## 用途
+
+源码分析完成后，Phase 3b 生成 `S2P3_test_design.md`。该文件用于固化 Step 2 的路径、group、参数维度与 case 设计，并作为 Step 3 后验证结论写回和 Step 4 用户确认的依据。
+
+Phase 3b 分为两段：
+
+1. 脚本生成区：由 `{skill_base}/scripts/generate_test_design.py` 从标准产物确定性生成。
+2. LLM 分析区：由主 Agent 基于脚本生成区和 Step 2 产物补充分析，不得修改脚本生成区事实。
+
+最终输出文件路径保持不变：`{output_dir}/S2P3_test_design.md`。
+
+## 输入文件
+
+脚本默认读取 `{output_dir}` 下的以下文件：
+
+| 文件 | 用途 |
+|------|------|
+| `S2P1_path_list.json` | 路径、conditions、kernel、reachability、group |
+| `S2P1_operator_model.json` | inputs / outputs / attributes / API 暴露差异 |
+| `S2P1_low_configs.json` | 常见网络配置数量统计 |
+| `S2P2_param_def.json` | group 顺序、per_dtype 参数维度、tiling_keys |
+| `S2P2_cases.json` | case 总数、按 group/key/dtype 分布 |
+| `S2P2_traceability.md` | LLM 分析区的推导链依据 |
+
+## 生成命令
+
+```bash
+python3 {skill_base}/scripts/generate_test_design.py \
+  --op-name {op_name} \
+  --op-path {op_path} \
+  --output-dir {output_dir}
+```
+
+默认行为：
+
+- 文件不存在：生成脚本区、LLM 分析区占位、verifier 区。
+- 文件存在：只替换脚本区，保留 LLM 分析区和 verifier 区。
+- `--force`：重写整个文件。
+- `--overwrite-llm-section`：重置 LLM 分析区。
+
+## 分区标记
+
+`S2P3_test_design.md` 必须包含以下 marker，用于脚本重跑和 Step 3 写回定位：
+
+```markdown
+<!-- BEGIN SCRIPT GENERATED SECTION -->
+...
+<!-- END SCRIPT GENERATED SECTION -->
+
+<!-- BEGIN LLM ANALYSIS SECTION -->
+...
+<!-- END LLM ANALYSIS SECTION -->
+
+<!-- BEGIN VERIFIER SECTION -->
+...
+<!-- END VERIFIER SECTION -->
+```
+
+## 章节结构（强制）
+
+```markdown
+# {OpName} 白盒测试设计
+
+<!-- BEGIN SCRIPT GENERATED SECTION -->
+## 1. 生成与输入摘要
+## 2. 接口与参数模型
+## 3. 路径与 Group 覆盖
+### 3.1 代码路径全景
+### 3.2 测试关注点（groups）
+## 4. Case 枚举与一致性校验
+## 5. 自动发现的未确认项
+<!-- END SCRIPT GENERATED SECTION -->
+
+<!-- BEGIN LLM ANALYSIS SECTION -->
+## 6. 测试设计分析
+### 6.1 事实摘要与设计结论
+### 6.2 关键派生变量
+### 6.3 执行模式分析
+## 7. 风险与补充建议
+<!-- END LLM ANALYSIS SECTION -->
+
+<!-- BEGIN VERIFIER SECTION -->
+## 8. Step 3 验证结论（原 §9 验证结论）
+（Step 3 完成后由 verifier 填写）
+<!-- END VERIFIER SECTION -->
+```
+
+## 脚本生成区要求
+
+### 1. 生成与输入摘要
+
+由脚本生成，包含：
+
+- 算子名、平台、输出目录。
+- 输入文件解析状态。
+- path 数、group 数、case 数、low config 数。
+- reachability 分布。
+
+### 2. 接口与参数模型
+
+由脚本从 `S2P1_operator_model.json` 生成：
+
+- inputs / outputs / attributes 表。
+- dtype / rank / shape / value_domain 摘要。
+- 若存在 API 暴露差异（如 `torch_npu_api_exposure.param_gaps`），必须展示。
+
+### 3. 路径与 Group 覆盖
+
+本章是 Phase 3 的事实核心，必须由脚本确定性生成。
+
+#### 3.1 代码路径全景
+
+脚本必须逐条列出 `S2P1_path_list.json` 中每个 path：
+
+| 字段 | 来源 |
+|------|------|
+| path id | `paths[*].id` |
+| tiling key | `paths[*].tiling_key` |
+| reachability | `paths[*].reachability` |
+| group | `paths[*].group` |
+| conditions | `paths[*].conditions` |
+| kernel | `paths[*].key_instructions` |
+| source | `paths[*].source` |
+
+禁止折叠或只写概要。path 数必须等于 `len(S2P1_path_list.json.paths)`。
+
+#### 3.2 测试关注点（groups）
+
+脚本必须按 `S2P2_param_def.json.groups` 顺序列出每个 group：
+
+- `id`
+- `mode`
+- `constraint_note`
+- `per_dtype`
+- `path`
+- `key`
+- entry 中除 `path` / `key` 外的所有维度字段
+
+维度字段必须通用遍历，禁止 hardcode `numCol`、`numRow`、`M/N/K` 等具体变量名。禁止引入 `S2P2_param_def.json` 中不存在的维度值。
+
+### 4. Case 枚举与一致性校验
+
+脚本生成：
+
+- `S2P2_cases.json` case 总数。
+- 按 `_group` / `key` 分布。
+- 若 `S2P2_param_def.json.dtype_tensors[*].param` 存在，按对应 dtype 参数统计。
+- 自动一致性校验表。
+
+脚本必须执行以下硬校验，失败则不得进入 LLM 分析或 Step 3：
+
+1. 必需输入文件存在且 JSON 可解析。
+2. path ID 唯一且非空。
+3. group ID 和顺序可读取。
+4. reachable path 必须有 group。
+5. `param_def.groups[*].per_dtype[*].path` 必须存在于 path list。
+6. `S2P2_cases.json[*].path` 必须存在于 path list。
+
+### 5. 自动发现的未确认项
+
+脚本根据结构化字段自动生成：
+
+- `reachability == disputed` 的 path。
+- `reachability == api_warn` / `api_dead` / `dead` 的 path。
+- `S2P1_operator_model.json` 中的 `param_gaps`。
+- `S2P1_path_list.json.completeness_checklist.unresolved_items`。
+
+无未确认项时写“无”。
+
+## LLM 分析区要求
+
+LLM 只能填写 `<!-- BEGIN LLM ANALYSIS SECTION -->` 与 `<!-- END LLM ANALYSIS SECTION -->` 之间的内容，禁止修改脚本生成区和 verifier 区。
+
+LLM 必须遵守：
+
+- 只基于脚本生成区、`S2P2_traceability.md`、`S2P1_path_list.json.source_constraints`、`S2P1_operator_model.json` 分析。
+- 不得新增 `S2P2_param_def.json` 中不存在的维度值。
+- 不得改写 path/group/reachability/key 等脚本区事实。
+- 信息不足时明确写“未从结构化产物中得到稳定结论”，不得猜测。
+
+### 6. 测试设计分析
+
+包含三个小节：
+
+1. `6.1 事实摘要与设计结论`：概述可覆盖路径、group 设计、主要不可达或 API 警告情况。
+2. `6.2 关键派生变量`：优先基于 `S2P2_traceability.md` 的推导链；无稳定信息时引用 `source_constraints`。
+3. `6.3 执行模式分析`：分析分核、UB、对齐、尾块、特殊路径等；无稳定信息时明确说明。
+
+### 7. 风险与补充建议
+
+汇总：
+
+- API 暴露限制。
+- dead/orphan 路径是否需要专项验证。
+- disputed/api_warn 的处理建议。
+- 是否需要额外 case。
+- 是否可进入 Step 3。
+
+## Verifier 区要求
+
+`## 8. Step 3 验证结论（原 §9 验证结论）` 保留给 Step 3 后写回。Step 3 / Step 4 流程引用“验证结论节”时，统一指该章节。
+
+## 通用维度指引
+
+### data_range
+
+每个 group 应包含 `data_range` 维度（除非算子有特殊限制），控制输入 tensor 的数据值域：
+
+```json
+"data_range": ["normal", "zero", "extreme", "negative", "tiny_pos", "all_ones", "near_zero", "with_inf", "with_nan"]
+```
+
+| 标签 | 含义 | 测什么 |
+|------|------|--------|
+| normal | torch.randn 正态随机 | 一般场景 |
+| zero | 全零 | 零值传播、除零保护 |
+| extreme | 接近 dtype 最大值 | 溢出、饱和 |
+| negative | 全负数 | sigmoid/silu 负值分支 |
+| tiny_pos | 极小正数（~1e-6） | 精度损失、scale 除零 |
+| all_ones | 全 1 | 恒等验证 |
+| near_zero | 接近零的正负混合 | 符号翻转、舍入 |
+| with_inf | 正常数据中混入 inf | inf 传播处理 |
+| with_nan | 正常数据中混入 nan | nan 传播处理 |
+
+定义域约束：当 `S2P1_operator_model.json` 中某输入的 `value_domain` 非 null 时，Step 5c 的 `expand_high()` 会自动过滤不兼容的 data_range 标签。
+
+### ndim
+
+如果算子支持多种 rank（如 ndim 2~8），可在参数定义中加入 ndim 维度。脚本只展示 `S2P2_param_def.json` 中已有维度，不自行推导 ndim。

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/source-analysis/05-network-search.md

@@ -0,0 +1,154 @@
+# Task C：网络搜索
+
+> **执行顺序（最高优先级）**
+> 严格按照以下步骤编号顺序执行。前置条件未满足禁止启动该步骤。
+> 每个步骤有独立职能和完成条件，完成后方可进入下一步。
+
+## 角色
+
+你是网络搜索专家。从 aclnn 文档提取算子的参数类型（Tensor vs TensorList）和关键约束，然后搜索常见深度学习网络中该算子的典型 shape 配置，生成带约束保障的网络用例集。
+
+## 输入
+
+你从主 agent 处获得以下参数：
+- 算子名称
+- 算子路径（包含 op_host/、op_kernel/ 和 docs/ 的目录）
+- 平台参数（核数、UB 大小、npuarch）
+- 产出写入路径
+
+---
+
+## 步骤总览
+
+| 步骤 | 职能 | 输入 | 产出 |
+|------|------|------|------|
+| Step 1 | 参数类型提取 | `docs/aclnn*.md` | 参数类型清单（TensorList vs Tensor）+ 约束 |
+| Step 2 | 网络搜索 | Step 1 结果 + 网络知识 | 典型 shape 配置列表 |
+| Step 3 | 组装写入 | Step 1 + Step 2 | `S2P1_low_configs.json` |
+| Step 4 | 返回文本 | Step 1-3 | 结构化文本（给主 Agent） |
+
+---
+
+## 执行顺序
+
+1. **Step 1 — 读 aclnn 文档提取参数类型和约束**
+   前置：无
+   定位：Glob `{op_path}/docs/aclnn*.md`，读取匹配到的文档。
+
+   从 aclnn 文档的**参数说明表**中提取以下信息：
+
+    **1a. 参数类型识别**：
+    - 参数名后标注 `aclTensorList*` → **TensorList** 类型（对应 DYNAMIC，包含 N ≥ 1 个子 tensor）
+    - 参数名后标注 `aclTensor*` → **Tensor** 类型（对应 REQUIRED，单个 tensor）
+
+   **1b. 约束提取**：
+   从每个参数的「使用说明」列提取约束，重点关注：
+    - **TensorList 的 tensor 数量约束**：如"元素个数与 x1 中 Tensor 的个数相等"、tensor count 范围等
+    - **shape 约束**：如"支持空 Tensor"、"列表内各 Tensor shape 相同"、"shape 与入参 x1 一致"等
+    - **dtype 约束**：如"数据类型保持一致"、支持的 dtype 列表等
+    - **元素数关系**：如"元素个数等于 x1 中 Tensor 的数量"等跨参数约束
+
+   **1c. 输出格式**：
+   将提取结果格式化为内部工作数据（不写入文件），供 Step 2-3 消费：
+
+   ```
+   参数类型清单：
+   - {name}: TensorList（aclTensorList*）
+     约束: {使用说明中的约束列表}
+    - {name}: Tensor（aclTensor*）
+      约束: {使用说明中的约束列表}
+
+    TensorList 上限：50（Ascend C DYNAMIC TensorList 硬件限制）
+   ```
+
+   完成条件：所有输入/输出参数的类型和约束已提取。
+
+2. **Step 2 — 搜索常见网络 shape 配置**
+   前置：Step 1 完成
+   搜索该算子在常见深度学习网络中的典型使用场景和 shape 配置。
+
+   **搜索范围**：
+   - 常见网络：ResNet、BERT、GPT、ViT、LLaMA 等
+   - 典型使用场景：前向计算、优化器 step、梯度计算等
+   - 数据类型：Step 1 提取的支持 dtype 列表
+
+   **每个配置包含**：
+   - `network_name`：网络名称 + 优化器/场景（如 `ResNet50_Adam`）
+   - `layer_context`：使用场景描述
+   - `shapes`：按 Step 1 的参数名组织各输入的 shape 列表
+   - `dtypes`：典型数据类型
+
+   **TensorList 约束检查（强制）**：
+   对于 Step 1 识别为 TensorList 的输入，每个配置中该输入的同 shape 分组 tensor 数量**不得超过 50**。若某个网络场景中同 shape 的 tensor 超过 50 个，截断为 50 并在 `layer_context` 中注明 `"truncated from N to 50 (TensorList hardware limit)"`。
+
+   完成条件：至少 10 个典型配置已收集，所有 TensorList 输入的 tensor 数 ≤ 50。
+
+3. **Step 3 — 组装写入 S2P1_low_configs.json**
+   前置：Step 1-2 完成
+   写入路径：`{产出写入路径}/S2P1_low_configs.json`
+
+    **组装前自检（强制）**：
+    - 每个配置中，TensorList 类型输入的同 shape 分组 tensor 数 ≤ 50
+    - TensorList 类型输入的所有子 tensor shape 在列表内一致（若 Step 1 提取了 same_shape 约束）
+    - TensorList 类型输入的所有子 tensor dtype 在列表内一致（若 Step 1 提取了 same_dtype 约束）
+    - 单 Tensor 类型输入的 shape 与使用说明中的约束一致（如"元素个数等于 x1 中 Tensor 的数量"）
+    - 所有配置的 dtype 在 Step 1 提取的支持 dtype 列表内
+
+   自检失败 → 修正后重新自检，直到全部通过。
+
+   完成条件：JSON 写入成功，自检通过。
+
+4. **Step 4 — 返回结构化文本**
+   前置：Step 3 完成
+   以文本形式返回，内容必须包含：
+   1. 参数类型清单（每个参数的 Tensor/TensorList 类型和关键约束）
+   2. 搜索到的典型配置数量和覆盖的网络/场景列表
+   3. 截断记录（若有配置因 TensorList 上限被截断）
+
+---
+
+## 输出
+
+### S2P1_low_configs.json（写入磁盘）
+
+写入路径：`{产出写入路径}/S2P1_low_configs.json`
+
+JSON 数组，每个元素为一个网络配置：
+
+```json
+[
+  {
+    "network_name": "string — 网络名称 + 场景（如 ResNet50_Adam）",
+    "layer_context": "string — 使用场景描述",
+    "shapes": {
+      "{tensor_list_input_name}_shapes": [["dim1", "dim2", "..."], "..."],
+      "{tensor_input_name}_shape": ["dim1", "dim2", "..."],
+      "...": "..."
+    },
+    "dtypes": "string — 数据类型（如 float16、float32）"
+  }
+]
+```
+
+**字段说明**：
+- `shapes` 的 key 命名与 Step 1 提取的参数名对应：TensorList 类型用 `{name}_shapes`（数组的数组），Tensor 类型用 `{name}_shape`（单个数组）
+- `dtypes` 为字符串，表示该配置中所有 tensor 的数据类型
+
+---
+
+## 关键规则
+
+1. **以 aclnn 文档为参数类型源**：Tensor vs TensorList 的判断必须以 aclnn 文档参数表中的类型标注（`aclTensor*` / `aclTensorList*`）为准，不从算子名称推断
+2. **TensorList 上限 50**：所有 TensorList 类型输入，同 shape 分组的 tensor 数不得超过 50（Ascend C DYNAMIC TensorList 硬件限制）
+3. **约束从文档提取**：shape/dtype/元素数等约束必须从 aclnn 文档的使用说明列提取，不猜测
+4. **截断透明**：因 TensorList 上限截断时，必须在 `layer_context` 中注明截断信息
+
+---
+
+## 严格禁止
+
+1. 禁止编造参数类型 — 必须从 aclnn 文档参数表提取
+2. 禁止生成 TensorList tensor 数超过 50 的配置 — 必须截断
+3. 禁止遗漏任何输入参数 — aclnn 文档中声明的所有输入必须在 shapes 中有对应字段
+4. 禁止在 shapes 中使用与 aclnn 文档不一致的参数名 — key 必须与文档参数名对应
+5. 禁止省略 Step 1 — 即使算子名称暗示了 TensorList（如 `foreach_*_list`），也必须从 aclnn 文档确认

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/task-a/00-overview.md

@@ -0,0 +1,66 @@
+# Task A 概览
+
+Task A：代码路径分析（tiling + kernel）。共 5 个步骤（步骤 4 分 4a/4b 两阶段），通过写入 `S2P1_path_config.json` 声明式配置并运行脚本 `build_path_list.py`，最终产出路径清单和源码约束表。
+
+本文档是 Task A 的轻量入口。子 agent 必须按步骤读取对应文件，禁止启动时批量读取整个 `task-a/` 目录。
+
+---
+
+## 核心原则：广度不可省 + 深度分级
+
+- **广度（分支）不可省**：Step 1 正向遍历实际控制流，tiling/kernel 里有什么分支就报什么分支，一个不漏。kernel 侧同一 key 内的二次 dispatch 也是独立路径。
+- **深度（每个函数读多细）可分级**：用 A/B/C 深读边界（详见 `01-step1-tiling.md`）。A/B/C 只裁剪深度，不裁剪访问面——每个分支都要访问、都要记录，只是纯填充/日志/校验类函数不读透。
+
+---
+
+## 步骤全景
+
+| 步骤 | 任务 | 规则位置 | 写入 path_config 的节 | 前置 |
+|------|------|---------|---------------------|------|
+| 1 | 读 Scout-T + source_scope → 按 `01-step1-tiling.md` 的 A/B/C 深度分级正向遍历 tiling 控制流（key 组装点优先，分支一个不漏，纯填充/日志/校验类仅抄约束不深读） → 分支骨架 + conditions | `01-step1-tiling.md` | — | 无 |
+| 2 | 未定义函数溯源（条件执行，按函数类型分界：平台判断函数代入求值；数值计算函数只登记不求值） | `02-step2-trace.md` | — | 步骤 1 发现未定义函数 |
+| 3 | 读 Scout-K + kernel P0 dispatch 块 → key 映射表（LLM 只提 key + 模板类名，行号/orphan 集合运算交脚本） | `03-step3-kernel.md` | — | 步骤 1 完成 |
+| 4a | 写 path_config 路径主体：paths + glossary + source_constraints | `04-path-config-schema.md` §路径主体 | 路径主体节 | 步骤 1-3 完成 |
+| 4b | 写 path_config 完整性配置：completeness_checklist + orphan_explanations + tiling_no_kernel_keys + degradations | `04-path-config-schema.md` §完整性配置 | 完整性配置节 | 步骤 4a 完成 |
+| 5 | 运行 `build_path_list.py` → 产出最终文件 | `01-code-analyzer.md` 步骤 5 | — | 步骤 4 完成 |
+
+---
+
+## 每条路径 5 核心字段（概览）
+
+LLM 每条路径只写 5 个字段，富化字段由脚本 `build_path_list.py` 自动补全：
+
+```json
+{
+  "id": "T1K1",
+  "tiling_key": 100,
+  "conditions": "varA==0\nvarB>8\nvarC<=varD",
+  "kernel_class": "KernelClassName<template_param, N>",
+  "tiling_line": 100
+}
+```
+
+字段含义、conditions 紧凑格式、dtype RHS 规则、变量三分类判定流程、glossary/source_constraints/完整性配置的完整判定逻辑 → **唯一权威在 `04-path-config-schema.md`**。本文档只给骨架概览。
+
+---
+
+## 文件导航
+
+| 文件 | 职责 | 读取时机 |
+|------|------|---------|
+| `00-overview.md`（本文档） | 步骤全景 + 文件导航 + 5 字段骨架概览 | 步骤 1 开始时首先 Read |
+| `01-step1-tiling.md` | 步骤 1 的 Scout-T、tiling 链路、A/B/C 深度分级、单一完成清单 | 步骤 1 开始时 Read |
+| `02-step2-trace.md` | 步骤 2 的未定义函数溯源（按函数类型分界） | 步骤 2（发现未定义函数）时 Read |
+| `03-step3-kernel.md` | 步骤 3 的 Scout-K、kernel P0 dispatch、key 映射规则 | 步骤 3 开始时 Read |
+| `04-path-config-schema.md` | 步骤 4a/4b 的 path_config 完整 schema（判定逻辑唯一权威） | 步骤 4a 开始时 Read |
+
+---
+
+## 严格禁止（总纲，细则见各步骤文件）
+
+1. 禁止编造路径、禁止合并路径、禁止省略条件、禁止跳过分支。
+2. 禁止参考 proto.h 做过滤，禁止输出 `reachability` 字段（可达性是 Task D Step 1 职责）。
+3. 禁止改写源码表达式（`source_expr` 逐字抄录）。
+4. 禁止未溯源即假设函数行为。
+5. 禁止指定 group（group 分配是 Task D 职责）。
+6. 禁止做参数推导（数值反推交 Task D）。

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/task-a/01-step1-tiling.md

@@ -0,0 +1,114 @@
+# Task A Step 1：Tiling 源码读取（正向遍历 + 深度分级）
+
+本文件对应 `01-code-analyzer.md` 的步骤 1：读取 Scout-T 和 `S2P0_source_scope.md`，正向遍历 tiling 执行链路，产出分支骨架 + 每条路径 conditions。
+
+未定义函数溯源规则见 `02-step2-trace.md`（步骤 2）。
+
+---
+
+## 核心原则：广度不可省 + 深度分级
+
+Step 1 的方式是**正向遍历实际控制流**（代码驱动），不做任何反向裁剪：
+
+- **广度（分支）不可省**：从入口沿 Init → DoTiling → 各 IsMatch/策略分发逐层展开，tiling 里有什么分支就记什么分支，一个不漏。这是完整性硬要求（禁止跳过分支、禁止编造分支）。
+- **深度（每个函数读多细）可分级**：用下方 A/B/C 深读边界。
+
+关键：**A/B/C 只裁剪深度，不裁剪访问面。** 每个分支都要访问、都要记录，只是 B 类函数不读透。耗时优化落在深度分级，不动分支广度。
+
+> **少深读 ≠ 少证据**：校验类代码不做语义深读，但仍需逐字抄录影响路径可达性的约束表达式（校验器要求 conditions 匹配源码、`source_constraints` 逐字抄录）。深度可降，证据不可省。
+
+核心判定标准只有一句，与具体算子无关：
+
+> **这段代码是否创建或门控一条 tiling 路径？** 是 → 深读；否 → 扫描登记或仅逐字抄录约束，不做语义深读。
+
+按代码「角色」分类深读深度，而不是按算子名或函数名。
+
+---
+
+## A. 深读清单（只深读这五类，按定位顺序）
+
+按编号顺序定位，锚点驱动，避免从文件头顺读到尾。
+
+1. **Tiling key 组装点（锚点，最先定位）**
+   - 找 `SetTilingKey(...)` / key 计算表达式 / 每分支的 key 常量赋值。
+   - 兼容两种形态：①**单一公式**（key 由若干分量组合，如 `dtype*N + mode + ...`）→ 拿到公式后，路径集合即为各分量取值的笛卡尔积，可枚举，不需逐条分析；②**各分支各写 key 字面量** → 逐分支记录 key 值。
+   - 先拿到 key 结构，再反推分量与分支，避免顺读整个文件。
+
+2. **Key 分量 / 分支变量的取值来源（公式的输入域）**
+   - 对出现在 key 公式或分支条件中的每个变量，定位其赋值点与取值集合（如 dtype 编码映射、可选输入/输出的存在性、平台版本等）。
+   - 只追到「取值来源 + 是否用户可控」，用于步骤 4 的变量三分类；不推导具体数值。
+
+3. **分支选择逻辑（策略分发链）**
+   - `IsMatch*` / `DoTiling*` / `DetermineMode*` 等 if-else / switch 链：提取每个分支的**进入条件**（逐字抄录条件表达式）与该分支所赋的 mode / strategy / key 分量值。
+
+4. **降级 / 回退点**
+   - 边界检查导致 key 分量被重新赋值、或切换到不同 kernel 的位置（如某计算量为 0 时回退到默认 mode）。这是唯一的非正交结构，必须单独识别并记录触发条件。
+
+5. **平台 / 可达边界**
+   - 平台判定谓词、架构 / SocVersion 守卫（如 `!= ASCEND310P`）、分叉到其他文件的谓词（如 regbase / arch 专用分支）。决定哪些分支进入 `paths`、哪些是 orphan 或对当前目标平台不可达。
+
+---
+
+## B. 深读边界（以下角色只登记 + 抄约束，不深读，算子无关）
+
+| 代码角色 | 处理方式 |
+|---------|---------|
+| 纯校验函数（shape / dtype / attr / nullptr 校验等） | 仅逐字抄录影响可达性的约束表达式进 `source_constraints`，**不逐条理解校验语义**；不产生路径 |
+| Tiling data 填充（`set_xxx` / SetTilingParameters 类） | 仅知其存在，不分析内部 |
+| Workspace / logging / 常量声明块 | 常量按需抄录进约束，代码体不深读 |
+| 数值算术推导（tile factor 具体数值公式） | 只追到「是哪个变量、参与哪个分支条件」，数值反推交 Task D |
+
+**注意**：B 类函数仍必须被访问和登记（角色 + 影响可达性的约束），只是不做逐行语义展开。不深读 ≠ 不访问。
+
+---
+
+## C. 止损规则
+
+顺读源码时，遇到不落入 A 五类的函数体，**立即停止深入**，只登记函数名与角色（归入 B 的某类），回到锚点驱动的定位。禁止对校验 / 填充 / 日志类代码做逐行语义展开。
+
+C 类止损与「广度不可省」不冲突：止损只针对 B 类函数的**内部深度**，该函数本身作为分支节点仍已被访问登记。
+
+---
+
+## 读取 Scout-T 和 source_scope
+
+先读取 Phase 0 产出的 `S2P0_scout_t.md` 和 `S2P0_source_scope.md`。
+
+Scout-T 报告已经过 Scout-Verify 校验，可直接信任其入口函数、平台分支关键词、key 设置方式、P0/P1/P2 文件清单和行号索引。
+
+仍需从源码提取：结构化 conditions、变量计算链、变量分类素材、降级触发条件。
+
+### 文件范围约束
+
+- 严格按 `S2P0_source_scope.md` 列出的文件范围执行。
+- 未列出的文件禁止读取，排除列表中的文件禁止读取。
+- 文件内读取粒度按本文件的执行链路展开规则执行。
+
+---
+
+## Tiling 执行链路展开
+
+本节规定**按什么顺序定位**函数（读取路线），上文 A/B/C 节规定**每个函数读多深**（深读深度）。二者正交：沿链路定位到的每个函数，按其在 A/B/C 中的角色决定是深读还是仅登记 + 抄录约束，不是一律完整读取。
+
+从 Scout-T 识别的入口函数出发，按执行链路逐层展开类内各被调用函数。类外函数按需读取，避免读入无关代码。
+
+1. 入口函数：读取 Tiling 类入口函数，按 A/B/C 深读边界处理其中各角色代码。
+2. Init 链路：沿入口函数调用链展开 Init 方法及其调用的所有类内子方法，各子方法按 A/B/C 深读边界处理。
+3. DoTiling 链路：展开 DoTiling 方法及其调用链上的类内函数，包括策略分发、策略判断、tile factor 计算等；这些多属 A 类，深读。
+4. 按需展开：每个函数读取后，若内部调用其他类内函数，继续沿链路定位，直到执行链路上的所有类内函数均已按 A/B/C 边界处理（落入 B 类的仅登记角色 + 抄录约束，不深读）。
+5. 行号记录：记录策略判断函数、key 设置代码、边界检查代码的行号区间。
+6. 类外函数：不在主链路中展开，按 `02-step2-trace.md` 的溯源规则单独读取。
+
+---
+
+## 单一完成清单
+
+Step 1 完成必须同时满足以下全部条目（本清单是 Step 1 的唯一完成判据，不设第二套核对）：
+
+1. **key 组装点已定位**：key 组装点及公式/字面量已确定。
+2. **分支全覆盖**：所有分支的进入条件与 key 分量已提取，分支一个不漏（对照 Scout-T 中入口执行链路上的关键节点：入口函数、Init 链、策略分发、策略判断系列、tile factor 计算系列，均已按 A/B/C 处理）。
+3. **变量来源已记录**：分支变量取值来源已记录（用于步骤 4 三分类）。
+4. **降级 / 平台边界已识别**：降级点与平台/可达边界已识别并记录触发条件。
+5. **约束已抄录**：影响可达性的约束表达式已逐字抄录（供 `source_constraints`）。
+
+若第 2 条对照发现遗漏关键节点 → 继续按需展开，不回退到全量读取。若链路上存在类外函数经 `02-step2-trace.md` 溯源仍无法定位实现 → 步骤 4 写入 `completeness_checklist`，不回退到全量读取。

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/task-a/02-step2-trace.md

@@ -0,0 +1,81 @@
+# Task A Step 2：未定义函数溯源（按函数类型分界）
+
+本文件对应 `01-code-analyzer.md` 的步骤 2：当 Step 1 遇到当前文件未定义、且返回值影响分支判断的函数调用时，溯源到实现代码，读取实际逻辑后再决定路径走向。
+
+**条件执行**：Step 1 未发现未定义函数则跳过本步骤。
+
+---
+
+## 适用范围
+
+需溯源：平台判断函数、返回值参与条件判断的计算工具函数、公共头文件中的 inline 函数。
+
+不需溯源：标准库函数、框架基础设施接口（如 `context->GetInputShape()` / `SetBlockDim()`）、已在当前文件有定义的函数。
+
+溯源范围限定在 `S2P0_source_scope.md` 列出的文件内。
+
+---
+
+## 按函数类型分界（核心）
+
+溯源到实现后，按被溯源函数的类型决定处理深度。两类分界明确，避免越界做 Task D 的数值反推：
+
+### 类型一：平台判断函数 → 代入求确定值
+
+函数返回值由平台常量（核数 / UB 大小 / SocVersion / arch）决定，用于门控分支进入。
+
+- 处理：读取实现逻辑，**将目标平台参数值代入，得到确定返回值**（true/false 或具体分支）。
+- 目的：决定该分支是进入 `paths` 还是 orphan / 平台不可达。
+- 这是 Step 2 必须求值的唯一情形。
+
+### 类型二：数值计算函数（tile factor 等）→ 只登记，不求值
+
+函数返回值是由用户可控输入参与的数值计算（如 tile factor、block factor、对齐后尺寸）。
+
+- 处理：**只登记「变量名 + 参与哪个分支条件」**，记录赋值/计算位置行号，不代入求具体数值。
+- 数值反推（解方程、代入常量算等价边界、对齐校正）**交 Task D 完成**。
+- 若该数值参与内部变量边界检查导致分支，按 `04-path-config-schema.md` §变量三分类判定流程记录 `boundary:内部变量==边界值`，计算链保留即可，不求边界数值。
+
+> **分界要点**：平台判断（不含用户可控量）代入求值决定路径存亡；数值计算（含用户可控量）只登记交 Task D。区分依据是「计算链是否经过用户可控输入」，与 `04-path-config-schema.md` §变量三分类判定流程一致。
+
+---
+
+## 强制流程
+
+1. 识别：发现函数调用在当前文件无定义。
+2. 定位：通过 `#include` 链和目录结构找到实现文件。
+3. 读取：读取实现代码，理解实际判断逻辑。
+4. 分界处理：按上文类型一 / 类型二决定「代入求值」或「只登记」。
+5. 记录：记录实现文件路径和行号，供后续 `tiling_line` 或完整性项引用。
+
+溯源深度：到函数实现代码并理解返回值逻辑即可，不需继续溯源更深层调用。
+
+---
+
+## 行为约束
+
+- 禁止根据函数名、文件名、平台名推断行为。
+- 禁止跳过溯源直接假设函数行为。
+- 禁止读取 `S2P0_source_scope.md` 范围之外的文件。
+- 禁止对类型二数值计算函数求具体边界数值（越界做 Task D 工作）。
+- 发现引用未在读取范围中列出且返回值影响分支判断的外部符号时，记录符号名、调用位置、影响分支，步骤 4 写入 `completeness_checklist`。
+
+遇到以下想法时必须 STOP，回归源码确认：
+
+- “这个值大概是 N” → 找 `constexpr` / `#define` 确认精确值。
+- “这个算子应该跟那个类似” → 每个算子独立分析。
+- “这个约束太复杂了” → 不可跳过，写进未确认项。
+- “没找到路径” → 记录为“未发现”，不默认没有。
+- “这个平台应该走这个分支” → 找到分支条件实现，代入目标平台值验证。
+- “proto.h 说不支持” → 不做可达性判断，kernel 有实现就报告。
+- “这条路径太边缘了” → 所有路径都报告。
+- “这个分支跟主干差不多” → conditions 不同就是不同路径。
+- “这个函数名说明了它的行为” → 函数名不等于实现，读代码。
+
+所有路径都报告，不做重要性判断；内部变量后续放入 `internal_variable`，但不可丢弃。
+
+---
+
+## 按需补充读取
+
+步骤 4 写 path_config 时若发现所需源码信息未在步骤 1-2 中读取，允许在 `S2P0_source_scope.md` 范围内搜索定位并补充读取。禁止为了补充信息扩大读取范围。