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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/tree-reduction.md

@@ -0,0 +1,160 @@
+# Reduction 范式二分缓存树（树形归约累加模型）
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/binary-tree.md（原 reduction-binary-sum.md）全文。片上归约指令（`REDUCE_OP` 谓词）的调用细节在适配层。
+
+## 1 背景与问题
+
+对 N 个数归约，片上单次只能载入 B 个数，必须分块处理：将 N 个数分成 M=⌈N/B⌉ 块，逐块载入片上、用向量指令归约成 1 个部分结果，最后把 M 个部分结果合并成最终结果。
+
+**核心问题：如何合并这 M 个部分结果，使浮点累加误差尽可能小？**
+
+## 2 为什么用二分树
+
+**顺序累加的精度问题**：维护一个累加器逐块累加，随着累加器增大，后续部分结果相对量级越来越小。浮点加法中两个量级差异大的数相加会丢失有效位，**误差随累加次数线性增长，为 O(M)**。
+
+**树形归约的优势**：把 M 个部分结果两两配对、逐层合并，树高仅 log₂(M)。每一层相加的两个数量级相近，有效位损失小，**误差增长为 O(log M)**。
+
+## 3 非 2 幂的处理：主尾配对
+
+二分树要求叶子数为 2 的幂，但 M 一般不是 2 的幂。
+
+取 P = **严格小于** M 的最大 2 幂，尾段 T = M − P。将尾段 T 块与主段前 T 块**两两配对合并**，每对产生 1 个部分结果：
+
+```
+Phase A (配对, i=0..T-1):
+    chunk[i] 与 chunk[i+P] 配对
+    → 载入两块 → 逐元素运算合并成 1 块 → 归约 → 1 个部分结果
+
+Phase B (独立, i=T..P-1):
+    chunk[i] 单独处理
+    → 载入 → 归约 → 1 个部分结果
+```
+
+配对后，树的输入数恰好为 P（2 幂），形成完美二叉树。
+
+> **为什么取"严格小于"而非"≤"**：当 M 本身为 2 幂时（如 M=16），取 P=M/2=8 而非 M=16，树深少 1 层，缓存空间省一个槽；代价是需多做 M/2 次配对。用一点计算换空间更划算。
+
+> 配对时两块**逐元素**运算合并成一个块再归约，而非各自归约后再合并两个标量——元素级配对精度更好，且只调一次归约指令。尾块可能不足 B 个数，与主块配对时将尾块的有效元素逐元素作用到主块对应位置即可（等价于尾块按 identity 补齐再逐元素合并），不影响归约结果。
+
+## 4 顺序循环中的树形归约
+
+### 4.1 核心挑战
+
+单核顺序执行，无法真正并行做树形归约。传统树形归约需保存全部叶子，当 P 较大时片上空间不够。需要一个机制：**在顺序循环中，把每个部分结果写到正确的树层级，用 L=log₂(P)+1 个缓存槽轮转复用，替代保存全部叶子的空间开销**。
+
+### 4.2 多级缓存
+
+在片上开辟 L 个缓存槽，L = log₂(P) + 1：
+
+| 层级 | 含义 | 覆盖范围 | 写入频率 |
+|------|------|---------|---------|
+| cache[0] | 1 个部分结果 | 1 块 | 每 1 次迭代 |
+| cache[1] | 2 个部分结果的合并 | 2 块 | 每 2 次迭代 |
+| cache[2] | 4 个部分结果的合并 | 4 块 | 每 4 次迭代 |
+| … | … | … | … |
+| cache[L-1] | 全部 P 个部分结果的合并 | P 块 | 最后 1 次（树根） |
+
+### 4.3 写入层级规则
+
+迭代序号 i 的二进制表示中，**末尾连续 1 的个数**决定写入层级：
+
+```
+level(i) = i 的二进制末尾连续 1 的个数
+```
+
+直觉：与二进制计数器的进位传播一致——当低位全为 1 时，加 1 会触发连续进位，进位传播到第几位，就对应写入第几层。
+
+| i | 二进制 | 末尾 1 个数 | 写入层级 | 动作 |
+|---|--------|-----------|---------|------|
+| 0 | 0000 | 0 | cache[0] | 直接写入 |
+| 1 | 0001 | 1 | cache[1] | 吸收 cache[0]，写入 |
+| 2 | 0010 | 0 | cache[0] | 直接写入 |
+| 3 | 0011 | 2 | cache[2] | 吸收 cache[0,1]，写入 |
+| … | … | … | … | … |
+| 2^k−1 | …111 | k | cache[k] | 吸收 cache[0..k-1]，写入（该层树根）|
+
+### 4.4 写入时的吸收规则
+
+写入 cache[k] 前，先把 cache[0], cache[1], ..., cache[k-1] 全部吸收（合并），再覆盖写 cache[k]：
+
+```
+写入 cache[k]:
+    result = 当前部分结果
+    for j = 0 to k-1:
+        result = result + cache[j]    // 正序吸收所有低层
+    cache[k] = result                  // 覆盖写本层
+```
+
+**为什么必须正序（j=0→k-1）吸收**：cache[j] 覆盖 2^j 块的数据量，正序吸收保证每步相加的两个数量级匹配（1 块 + 1 块 → 2 块量级 → + 2 块 → 4 块量级 → …），精度最优。倒序吸收会让量级悬殊的数相加，破坏二分树的精度优势。**顺序不能变**。
+
+**为什么是覆盖写而非累加写**：cache[k] 此前保存的是上一轮同层写入的旧值（已被更高层吸收过）。若累加，会把过期旧值叠进当前结果，导致重复计算。
+
+### 4.5 树填充过程（P=16）
+
+```
+i=0:  cache[0]=S                                  树: [S, _, _, _, _]
+i=1:  cache[1]=S+cache[0]                         树: [_, S, _, _, _]
+i=2:  cache[0]=S                                  树: [S, _, _, _, _]
+i=3:  cache[2]=S+cache[0]+cache[1]                树: [_, _, S, _, _]
+...
+i=15: cache[4]=S+cache[0]+cache[1]+cache[2]+cache[3]  树: [_, _, _, _, S] ← 根
+```
+
+迭代结束后，cache[L-1]（最高层）即全部输入的归约结果。
+
+## 5 主流程伪码（语言中立）
+
+```
+输入: N 个数, 片上单块容量 B
+M = ceil(N / B)               # 总块数
+P = FindNearestPower2(M)      # 主段长度（严格小于 M 的最大 2 幂）
+T = M - P                     # 尾段长度
+L = log2(P) + 1               # 缓存树层数
+
+for i = 0 to P-1:
+    # 1. 载入并归约
+    if i < T:                            # Phase A: 主尾配对
+        load chunk[i]    → buf0
+        load chunk[i+P]  → buf1
+        buf0 = elementwise_merge(buf0, buf1)
+        result = reduce(buf0)
+    else:                                # Phase B: 独立
+        load chunk[i]    → reduce → result
+
+    # 2. 写入缓存树
+    k = GetCacheID(i)                    # 末尾连续 1 的个数 = 写入层级
+    DoCaching(k, result)                 # 正序吸收所有低层，覆盖写 cache[k]
+
+answer = cache[L-1]                      # 树根 = 最终结果
+```
+
+辅助函数：
+
+```
+FindNearestPower2(value):    # 严格小于 value 的最大 2 的幂；value 为 0 或 1 时特例
+    if value == 0: return 0
+    if value <= 2: return 1
+    return 1 << floor(log2(value - 1))
+
+GetCacheID(idx):             # 二进制末尾连续 1 的个数 = 写入层级
+    return count_ones(idx ^ (idx + 1)) - 1
+```
+
+## 6 设计要点总结
+
+1. **主尾配对解决非 2 幂**：M 拆成 P（严格小于 M 的最大 2 幂）+ T，尾段与主段前 T 块配对，树输入数为 2 幂。M 为 2 幂时取 P=M/2，树深少 1
+2. **末尾 1 规则编码树结构**：顺序循环中无需显式建树，迭代序号的二进制性质天然形成树形依赖
+3. **正序吸收低层再覆盖写**：低层旧值已被吸收，覆盖不影响正确性，且不需要额外缓冲
+4. **精度**：每层相加的两个数量级相近，误差 O(log P) 而非顺序累加的 O(M)
+5. **空间极小**：缓存树仅需 L=log₂(P)+1 个结果槽，远小于保存全部中间结果
+
+## 7 与片上归约指令的两级树关系
+
+片上归约指令（`REDUCE_OP` 谓词）内部通常也用树形/折叠累加处理**单个 chunk 内**的归约；本范式二分缓存树处理**跨 chunk** 的累加。两者构成两级树：
+
+- **指令级树**：chunk 内，指令内部的折叠（精度由 `REDUCE_OP_PRECISION` 谓词描述）
+- **范式级树**（本文档）：chunk 间，cacheBuf 二分缓存树
+
+范式无需关心指令内部实现——传入块形状，指令返回单次归约结果；范式树进一步保证跨 chunk 累加精度与确定性。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/generic/tuple-reduce.md

@@ -0,0 +1,53 @@
+# Reduction 范式 Tuple Reduce 场景模型
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 来源：adapters/ascendc/tuple-reduce.md（原 reduction-tuple-reduce.md）。AscendC 落地（kernel 入口 for 循环代码、`SyncAll` 调用）在适配层。
+
+## 1 场景定义
+
+**Tuple Reduce**（本范式术语）= 对同一输入（或同一组输入）沿**相同归约轴**做 N 次独立归约的算子形态（典型：多输出归约算子）。
+
+> `N_REDUCES` = 独立归约过程数。一次归约过程内部可产出多个分叉输出，分叉输出不增加 `N_REDUCES`——过程数与输出张量数解耦。`N_REDUCES` 为算子级常量（由算子公式固定），不进模板选择键、不进 TilingData。
+
+## 2 核心约束
+
+1. **共享归约轴**：所有归约过程的归约轴完全相同（共享切分结果的前提）
+2. **跨过程同步按全局判定**：全局首轮 = 第 0 个过程（跳过等待），全局末轮 = 第 N−1 个过程（跳过置位），中间轮次正常置位/等待——见 [sync-model.md](sync-model.md) §3.2
+
+## 3 总体策略（与标准范式的差异）
+
+- **模板选择键不变**，不新增模板参数
+- 差异仅在归约编排内部：归约过程按 `processIdx` 分发，搬出写到不同输出指针
+- **合轴、切分、多核切分、二分缓存树算法等全部不变**
+
+### 3.1 循环复用模型
+
+N 次归约**复用同一份**片上 buffer 与 workspace：
+
+- ⛔ **禁止在 workspace 公式或片上预算中乘以 N**——所有归约过程串行执行，生命周期不重叠，复用合法
+- CopyIn 执行 N 次（每次循环各做一次），带宽开销为标准范式的 N 倍（性能特征，非正确性问题）
+
+### 3.2 存活节点一条流规则
+
+存活节点分析**分阶段**（归约前/归约/归约后段，Group 为 Phase 1/Phase 2）各自画**一条流**，禁止按 for 循环展开成多轮：
+
+1. 公共步骤（所有过程都执行）只出现一次
+2. 过程独有步骤写成按 `processIdx` 分发的并列分支，分割粒度 = 归约过程
+3. 分支互斥——峰值取各分支 **max**，禁止相加、不按分支单独记账（详见 [liveness-fusion.md](liveness-fusion.md) §4）
+
+### 3.3 归约前分发的同步语义
+
+`processIdx` 是运行时变量——过程独有的 elementwise 分发用运行时 if/else（不可用编译期分支）。
+
+### 3.4 Group 轮末栅栏
+
+Group 分支每轮归约过程末尾需**跨核栅栏**：下一轮 Phase 1 写 workspace/片上前，本轮 Phase 2 必须读完——栅栏同时兜住 workspace 的跨过程 WAR 与片上侧跨过程 WAR（见 [sync-model.md](sync-model.md) §5）。Base/Empty 入口循环不插入额外跨核同步，跨过程 WAR 由核内流水同步按全局首末轮规则覆盖。
+
+## 4 设计产出要求
+
+1. **场景判定结论**：本算子是否 Tuple Reduce、`N_REDUCES` 取值（由算子公式决定）
+2. **分发结构**：过程独有的归约前/后 elementwise 按 `processIdx` 的分支表；搬出到各输出指针的映射
+3. **复用声明**：片上 buffer 与 workspace 与标准范式一致、N 次复用、禁止乘 N（显式写出）
+4. **同步全局首末轮**：跨过程 WAR 的等待/置位跳过规则按全局 processIdx 判定（显式写出）
+5. **Group 轮末栅栏**：若使用 Group 模板，每轮末尾栅栏及其兜住的 WAR 范围（显式写出）

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/patterns.md

@@ -0,0 +1,62 @@
+# Reduction 范式入口（语言中立）
+
+> 本文件是 Reduction 范式的**统一入口**：场景判定 + 语言路由 + 消费规则。具体知识分布在两个层次：
+>
+> - **通用知识层** `generic/` — 语言无关的算法、模型、方法论
+> - **语言适配层** `adapters/<lang>/` — 强耦合具体开发语言的实现知识（当前提供 `ascendc`）
+>
+> 范式路由（`routes.yaml` → 本文件）与语言路由（本文件 → 适配层）分离：范式路由由 `op.paradigms` 决定，语言路由由开发语言决定。
+
+---
+
+## 场景判定
+
+满足以下条件的算子属于 Reduction 范式：
+
+1. **跨元素归约语义**——输出元素由输入沿归约轴（R 轴）折叠计算得到（sum/mean/max/min/prod/any/all 及其复合），归约结果沿非归约轴（A 轴）保留
+2. **归约轴可标记**——输入张量的每一根轴可按算子语义标记为 A 轴（preserve）或 R 轴（reduce）
+3. **输出 shape 由 A 轴决定**——归约后 R 轴消失（keep_dims 场景 R 轴变 1，仍按消失处理）
+
+典型场景：单/多轴 reduce、全轴归约（All Reduce）、含归约的复合计算（归约前/后有 elementwise 变换）、多输出多次独立归约（Tuple Reduce）、空 tensor（shape 含 0）。语言中立的场景模型、模板分类与数据流骨架见 [generic/scene.md](generic/scene.md)。
+
+---
+
+## 语言路由
+
+按开发语言选择适配层。语言由调用方显式提供，或读取 `spec.yaml` 的 `op.language`；缺失或未知时先报告输入缺口，不选择语言适配层。
+
+| 开发语言 | 加载内容 | 入口 |
+|------|------|------|
+| `ascendc` | 通用知识层 + AscendC 适配层 | [adapters/ascendc/index.md](adapters/ascendc/index.md) |
+| `dsl`（CANNBotDSL） | 通用知识层 + DSL 通用方法 | 当前无 Reduction DSL 专用适配层；读取 `references/paradigms/general-methodology-dsl.md`，DSL API 和设备能力由调用方提供 |
+| 其他语言 | 通用知识层；适配层待确认 | 报告当前没有对应的语言适配层，不读取其他语言的 API 或模板 |
+
+**互斥规则**：一次任务只加载命中语言的适配层，其他语言的适配层不加载、不参考其 API 与代码模板。
+
+---
+
+## 通用知识层索引
+
+语言无关的算法与模型，按需展开（完整检索表见 [generic/index.md](generic/index.md)）：
+
+| 文档 | 覆盖 |
+|------|------|
+| [generic/scene.md](generic/scene.md) | 场景模型、A/R 轴与 pattern 坐标系、Base/Group/Empty 三模板分类、三段式数据流骨架、能力边界 |
+| [generic/capability-contract.md](generic/capability-contract.md) | 能力谓词定义（通用层算法引用的语言/硬件能力参数） |
+| [generic/axis-preprocessing.md](generic/axis-preprocessing.md) | axes 归一化 6 步、空 tensor 短路判定、四步合轴算法、pattern 形态与 MAX_PATTERN_RANK 推导 |
+| [generic/tree-reduction.md](generic/tree-reduction.md) | 二分缓存树：精度动机、非 2 幂主尾配对、多级缓存写入层级与吸收规则 |
+| [generic/liveness-fusion.md](generic/liveness-fusion.md) | L/P 存活节点模型、公平基线、互斥分支流规则、融合决策方法论 |
+| [generic/splitting.md](generic/splitting.md) | UB 双切分三步算法、多核均衡切分、Group 2D 分核、Empty 切分约束、UB 预算不等式 |
+| [generic/sync-model.md](generic/sync-model.md) | RAW/WAR 依赖识别、三层 WAR、循环间反向同步、跨核栅栏模型 |
+| [generic/tuple-reduce.md](generic/tuple-reduce.md) | Tuple Reduce 场景模型：N 次独立归约的循环复用、存活节点一条流规则 |
+
+---
+
+## 消费规则
+
+1. **按需加载**：Ascend C 先读适配层 index；DSL 读取通用层与 `general-methodology-dsl.md`。仅展开当前问题需要的叶子文档。
+2. **叶子文档限额**：单个子问题最多展开 5 个叶子文档，仍未闭环则拆分为更小的子问题
+3. **能力真值**：Ascend C 读取 [capability-mapping.md](adapters/ascendc/capability-mapping.md)；DSL 没有专用映射时，能力谓词必须从调用方提供的 DSL API 与设备证据确认，未知项保留待验证。
+4. **编码前检视参考实现**：Ascend C 可从 `adapters/ascendc/example/` 选择；DSL 从调用方提供的 CANNBotDSL 样例中选择。样例仅用于核实语言用法，不提供当前算子的算法或资源默认值。
+5. **设计依据**：根据规格读取通用算法与对应语言约束，给出分支、数据结构、资源预算、同步和验证结论；输出格式由调用方指定。Ascend C 设计检查见 [design-spec.md](adapters/ascendc/design-spec.md)，DSL 使用 `references/paradigms/general-methodology-dsl.md`。
+6. **范式优先级**：本范式的专用知识优先于 agent 通用知识；同一设计点结论冲突时，以本范式指向的必读文件为准

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/validate_gates.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Reduction paradigm design gates for validate_completeness.py.
+
+Checks that DESIGN.md contains actual code blocks (not prose descriptions)
+for critical Reduction kernel implementation components.
+
+Exposed API:
+    def validate_gates(design_text: str) -> list[str]:
+        Returns list of error strings. Empty = all gates passed.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def _extract_cpp_blocks(text: str) -> list[str]:
+    """Extract all ```cpp ... ``` code blocks from markdown text."""
+    pattern = re.compile(r"```(?:cpp|c\+\+)\s*\n(.*?)```", re.DOTALL)
+    return [m.group(1) for m in pattern.finditer(text)]
+
+
+def _block_lines(block: str) -> int:
+    """Count non-empty lines in a code block."""
+    return sum(1 for line in block.splitlines() if line.strip())
+
+
+def _has_function_definition(
+    blocks: list[str], func_name: str, min_lines: int = 0
+) -> bool:
+    """Check if any cpp block contains a function definition for func_name.
+
+    Matches patterns like:
+        void FunctionName(...) {
+        __aicore__ inline void FunctionName(...) {
+        static inline void FunctionName(...) {
+    """
+    # 匹配函数定义：可选的修饰符 + 返回类型 + 函数名 + 参数列表 + {
+    pattern = re.compile(
+        r"\b(?:__aicore__\s+)?(?:inline\s+)?(?:static\s+)?\w+\s+"
+        + re.escape(func_name)
+        + r"\s*\([^)]*\)\s*\{",
+        re.MULTILINE,
+    )
+    for block in blocks:
+        if pattern.search(block) and _block_lines(block) >= min_lines:
+            return True
+    return False
+
+
+def _has_ellipsis_placeholder(blocks: list[str]) -> list[str]:
+    """Find cpp blocks containing '// ...' as omission placeholder."""
+    pattern = re.compile(r"^\s*//\s*\.{3}\s*$", re.MULTILINE)
+    results = []
+    for i, block in enumerate(blocks):
+        matches = pattern.findall(block)
+        if matches:
+            results.append(
+                f"code block #{i + 1} contains {len(matches)} placeholder(s)"
+            )
+    return results
+
+
+def validate_gates(design_text: str) -> list[str]:
+    """Validate that DESIGN.md contains required code blocks for Reduction paradigm.
+
+    Args:
+        design_text: Full text of DESIGN.md
+
+    Returns:
+        List of error strings. Empty list means all gates passed.
+    """
+    errors: list[str] = []
+    blocks = _extract_cpp_blocks(design_text)
+
+    if not blocks:
+        errors.append("GATE-0: no cpp code blocks found in DESIGN.md")
+        return errors
+
+    # 1. Process() complete source block (>= 30 lines)
+    if not _has_function_definition(blocks, "Process", min_lines=30):
+        errors.append(
+            "GATE-1: missing Process() function definition "
+            "(need cpp block with Process() definition and >= 30 non-empty lines)"
+        )
+
+    # 2. CopyIn source (DoCopyInTile required)
+    if not _has_function_definition(blocks, "DoCopyInTile"):
+        errors.append("GATE-2: missing DoCopyInTile function definition in cpp blocks")
+
+    # 3. CopyOut three-path pseudocode (>= 15 lines)
+    if not _has_function_definition(blocks, "CopyOut", min_lines=15):
+        errors.append(
+            "GATE-3: missing CopyOut function definition "
+            "(need cpp block with CopyOut() definition and >= 15 non-empty lines)"
+        )
+
+    # 4. Cache tree (GetCacheID + DoCaching，两者都必须有，见 patterns.md [6.8.2])
+    has_cache_tree = _has_function_definition(
+        blocks, "GetCacheID"
+    ) and _has_function_definition(blocks, "DoCaching")
+    if not has_cache_tree:
+        errors.append(
+            "GATE-4: missing bisection cache tree function definitions "
+            "(need both GetCacheID() and DoCaching())"
+        )
+
+    # 5. Mandatory kernel functions per patterns [6.8.2]/[6.8.3]
+    required_funcs = [
+        "ClearChunkExtensionVf",
+        "MergeTmpBufVf",
+        "FindNearestPower2",
+        "CalLog2",
+    ]
+    missing_funcs = [name for name in required_funcs if name not in design_text]
+    if missing_funcs:
+        errors.append(
+            f"GATE-5: missing mandatory kernel function definitions: {', '.join(missing_funcs)} "
+            f"(ClearInnerBurstTailPadVf 按触发条件表决定是否产出，不强制)"
+        )
+
+    # 6. No ellipsis placeholders ('// ...') in cpp blocks
+    ellipsis_hits = _has_ellipsis_placeholder(blocks)
+    if ellipsis_hits:
+        errors.append(
+            f"GATE-6: ellipsis placeholder '// ...' found in cpp blocks: "
+            f"{'; '.join(ellipsis_hits)}"
+        )
+
+    # 7. TilingKey must have ASCENDC_TPL_ARGS_DECL and ASCENDC_TPL_SEL
+    has_decl = "ASCENDC_TPL_ARGS_DECL" in design_text
+    has_sel = "ASCENDC_TPL_SEL" in design_text
+    if not has_decl or not has_sel:
+        missing = []
+        if not has_decl:
+            missing.append("ASCENDC_TPL_ARGS_DECL")
+        if not has_sel:
+            missing.append("ASCENDC_TPL_SEL")
+        errors.append(
+            f"GATE-7: missing TilingKey macro definitions: {', '.join(missing)}"
+        )
+
+    # 8. TilingKey must not contain dtype —— 只检查 TPL 宏参数行，注释/正文中的 dtype 说明不误伤
+    for block in blocks:
+        if "ASCENDC_TPL_ARGS_DECL" in block or "ASCENDC_TPL_SEL" in block:
+            for line in block.splitlines():
+                if (
+                    "TPL_BOOL_DECL" in line
+                    or "TPL_SEL" in line
+                    or "TPL_ARGS_DECL" in line
+                ):
+                    if re.search(r"\b(dtype|DataType|DTYPE)\b", line, re.IGNORECASE):
+                        errors.append(
+                            "GATE-8: TilingKey contains dtype parameter — "
+                            "Reduction paradigm TilingKey should not split by dtype"
+                        )
+                        break
+            break
+
+    # 9. Tiling side: core function definitions
+    # ComputeGroupSplit 仅在算子使用 Group 模板时必查（overview §2.1：算子选择 1~3 个模板）
+    tiling_functions = [
+        "ComputeAUbFactor",
+        "ComputeRUbFactor",
+        "ExpandAIfRFullyLoaded",
+        "SetWorkspaceSize",
+        "FillAndLogTilingData",
+    ]
+    uses_group = (
+        "ProcessGroup" in design_text
+        or "GroupKernel" in design_text
+        or "ASCENDC_TPL_BOOL_SEL(isGroup, 1)" in design_text
+    )
+    if uses_group:
+        tiling_functions.append("ComputeGroupSplit")
+    missing_tiling = []
+    for func_name in tiling_functions:
+        if not _has_function_definition(blocks, func_name):
+            missing_tiling.append(func_name)
+    if missing_tiling:
+        errors.append(
+            f"GATE-9: missing tiling function definitions: {', '.join(missing_tiling)}"
+        )
+
+    return errors

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/resolve_example.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Resolve example-routes.yaml — accept spec.yaml, extract paradigms and language,
+map to language-adapter reference example packages."""
+
+from __future__ import annotations
+
+import logging
+import sys
+import argparse
+from pathlib import Path
+
+import yaml
+
+DEFAULT_LANGUAGE = "ascendc"
+SUPPORTED_LANGUAGES = {"ascendc", "dsl"}
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+def load_example_routes(skill_dir: Path) -> dict:
+    routes_file = skill_dir / "references" / "paradigms" / "example-routes.yaml"
+    if not routes_file.exists():
+        return {}
+    with open(routes_file) as f:
+        data = yaml.safe_load(f) or {}
+    return data.get("routes", {})
+
+
+def parse_spec(spec_text: str) -> dict:
+    """读取完整 YAML，并校验本模块消费的字段。"""
+    data = yaml.safe_load(spec_text)
+    if not isinstance(data, dict) or not isinstance(data.get("op"), dict):
+        raise ValueError("spec.op must be a mapping")
+    op = data["op"]
+    category = op.get("category", "")
+    if not isinstance(category, str):
+        raise ValueError("op.category must be a string")
+    paradigms = op.get("paradigms", [])
+    if not isinstance(paradigms, list) or any(
+        not isinstance(item, str) or not item.strip() for item in paradigms
+    ):
+        raise ValueError("op.paradigms must be a list of non-empty strings")
+    language = op.get("language", "")
+    if not isinstance(language, str):
+        raise ValueError("op.language must be a string")
+    if language and language not in SUPPORTED_LANGUAGES:
+        raise ValueError("op.language must be ascendc or dsl")
+    return op
+
+
+def extract_paradigm_info(spec_text: str) -> tuple[str, list[str]]:
+    op = parse_spec(spec_text)
+    return op.get("category", ""), op.get("paradigms", [])
+
+
+def extract_language(spec_text: str) -> str:
+    return parse_spec(spec_text).get("language", "")
+
+
+def _example_paths_for_language(entry: object, language: str) -> list[str]:
+    """Select example paths for one language from a paradigm route entry.
+
+    New format: {language: [paths]}; legacy flat format: [paths] (ascendc only).
+    No cross-language fallback: an unregistered language resolves to no examples.
+    """
+    if isinstance(entry, dict):
+        return list(entry.get(language, []))
+    if isinstance(entry, list):
+        return list(entry) if language == DEFAULT_LANGUAGE else []
+    return []
+
+
+def resolve_examples(
+    routes: dict,
+    paradigms: list[str],
+    skill_dir: Path,
+    language: str = "",
+) -> dict[str, list[str]]:
+    para_routes = routes.get("paradigms", {})
+    if language not in SUPPORTED_LANGUAGES:
+        raise ValueError("an explicit supported language (ascendc or dsl) is required")
+    lang = language
+    result: dict[str, list[str]] = {}
+    seen: set[str] = set()
+
+    for p in paradigms:
+        entry = para_routes.get(p)
+        if entry is None:
+            continue
+        for ref_path in _example_paths_for_language(entry, lang):
+            full = skill_dir / ref_path
+            if full.exists():
+                if str(full) not in seen:
+                    result.setdefault(p, []).append(str(full))
+                    seen.add(str(full))
+    return result
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stdout)
+    parser = argparse.ArgumentParser(
+        description="Resolve paradigms to example packages from example-routes.yaml"
+    )
+    parser.add_argument(
+        "--spec",
+        type=Path,
+        required=True,
+        help="调用方提供的算子规格 YAML 路径",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+    parser.add_argument(
+        "--language",
+        choices=sorted(SUPPORTED_LANGUAGES),
+        help="explicit language; overrides op.language in the spec",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(__file__).resolve().parents[2]
+    try:
+        op = parse_spec(args.spec.read_text(encoding="utf-8"))
+    except (OSError, ValueError, yaml.YAMLError) as exc:
+        parser.error(str(exc))
+    paradigms = op.get("paradigms", [])
+    language = args.language or op.get("language", "")
+    if language not in SUPPORTED_LANGUAGES:
+        parser.error("provide --language ascendc|dsl or a supported op.language")
+
+    routes = load_example_routes(skill_dir)
+    resolved = resolve_examples(routes, paradigms, skill_dir, language)
+
+    if args.json:
+        import json
+
+        print(
+            json.dumps(
+                {"language": language, "examples": resolved},
+                indent=2,
+                ensure_ascii=False,
+            )
+        )
+    else:
+        LOGGER.info(f"language: {language}")
+        if not resolved:
+            LOGGER.info(
+                "  (no example matched; language adapters are mutually exclusive, no cross-language fallback)"
+            )
+        for para, paths in resolved.items():
+            LOGGER.info(f"[{para}]")
+            for p in paths:
+                LOGGER.info(f"  {p}")
+
+
+if __name__ == "__main__":
+    main()