cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/scripts/family_asset_audit.py

@@ -0,0 +1,68 @@
+#!/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.
+# ----------------------------------------------------------------------------------------------------------
+"""family_asset_audit.py — ops-family 族表数据防漂移静态断言
+
+对 SKILL.md 族分类表中的「模板数」列做实测校验：模板数必须与
+references/<族>/ 下 .h/.cpp/.template 文件的实际计数一致。
+不一致 → exit 1（族表失真，模板路由第一跳数据错误）。
+
+用法：python3 family_asset_audit.py   （在 ops-family SKILL 根目录或仓根执行）
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+SKILL_MD = Path(__file__).resolve().parents[1] / "SKILL.md"
+REFERENCES = Path(__file__).resolve().parents[1] / "references"
+
+TEMPLATE_EXTS = (".h", ".cpp", ".template")
+
+
+def actual_template_count(family: str) -> int:
+    d = REFERENCES / family
+    if not d.is_dir():
+        return 0
+    return sum(1 for p in d.rglob("*") if p.suffix in TEMPLATE_EXTS and p.is_file())
+
+
+def main() -> int:
+    text = SKILL_MD.read_text(encoding="utf-8")
+    # 解析族表行：| <族> | ... | <模板数> | <状态> | <文档> |
+    rows = re.findall(r"^\|\s*([a-z0-9_]+)\s*\|[^|]+\|[^|]+\|\s*(\d+)\s*\|", text, re.M)
+    if not rows:
+        print(
+            "ERROR: SKILL.md 族表未解析出「模板数」列（表结构变化？）", file=sys.stderr
+        )
+        return 1
+    failed = []
+    for family, declared in rows:
+        actual = actual_template_count(family)
+        mark = "OK" if int(declared) == actual else "MISMATCH"
+        print(f"[{mark}] {family}: 表={declared} 实测={actual}")
+        if mark == "MISMATCH":
+            failed.append(family)
+    if failed:
+        print(
+            f"\n族表模板数与实测不一致：{', '.join(failed)} —— 模板路由第一跳数据失真，"
+            f"请更新 SKILL.md 族表",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"\n{len(rows)} 族模板数全部与实测一致")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/asc-tools/tool-ops-tune/ops-family/scripts/tiling_candidates.py

@@ -0,0 +1,419 @@
+#!/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.
+# ----------------------------------------------------------------------------------------------------------
+"""tiling_candidates.py — Tiling 候选参数生成器·四族
+
+设计对齐：
+  - 机制卡 ascendc-tiling.md「禁止经验值交付」与 mc2-balancing.md 四剪枝此前
+    只有 markdown 描述，全仓无候选生成执行载体——Block Dim 是最低垂果实
+    （L2 yaml 引用 4→20 核 4.75x 实测案例），也是最容易翻车的（容量联动
+    device fault 是 troubleshooting 运行类第一条）。
+  - 本脚本把候选生成 + 容量预算校验变成可执行载体：L2_UNDERUTILIZATION
+    命中后不再靠 LLM 经验拍 block_dim / tile。
+  - 推导逻辑以契约方式移植一线 tiling 推导脚本
+    （elewise/reduction/broadcast/conversion 四族 fallback 参考实现），
+    不直接复制其代码——本仓输出的是「候选表 + 逐候选容量占用计算过程」，
+    单候选交付仍走 perf-implementer 单变量铁律。
+
+覆盖四族（首期）：
+  elementwise：一维展开 → 多核均分（512 元素对齐）→ UB 切分（256B 对齐，双缓冲）
+  reduction：A/R 轴折叠 → 行块切分（rows_per_ub 受 UB 预算）→ 多核按 outer 分
+  broadcast：输出 shape 折叠 → UB 切分（多输入共享预算）→ 多核按 tile 数分
+  conversion：channel-flat → tile 元素对齐 → 多核按 tile 分（offset 表）
+
+用法：
+  python3 tiling_candidates.py --family elementwise --shape 8448,4096 --dtype fp16 \\
+      --soc a5 [--input-count 1] [--output candidates.json]
+
+输出（opstune.tiling-candidates/1.0）：
+  { soc, family, shape, dtype, soc_spec_source,
+    candidates: [ {variant, block_dim, tile..., capacity_kb, capacity_note,
+                   derived: {…计算过程}, aligned: true/false} ],
+    pruned: [ {variant, reason} ],  // 剪枝记录（容量超限/未对齐）——可审计证据
+    warning: "候选表仅供参数选择，实施须单变量 + 容量复核 + 全量精度" }
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SCHEMA = "opstune.tiling-candidates/1.0"
+
+# soc-spec 峰值标尺文件名（判定引擎同源数据）
+SOC_SPEC_NAME = "soc-spec" + ".yaml"
+
+# 常量（与参考实现同款契约值；来源标注）
+ELEM_ALIGN_512 = 512  # [tuning-practice] 多核元素对齐粒度
+ALIGN_256B = 256  # [tuning-practice] UB 对齐（字节）
+MIN_TILING_BITS = 32768  # [tuning-practice] 每核最小 4KB（bits）
+BUFFER_NUM_DEFAULT = 2  # [tuning-practice] 双缓冲队列数
+DTYPE_BYTES = {
+    "fp16": 2,
+    "float16": 2,
+    "bf16": 2,
+    "bfloat16": 2,
+    "fp32": 4,
+    "float32": 4,
+    "int8": 1,
+    "int32": 4,
+}
+
+
+def load_soc_spec(path: Path) -> dict:
+    import yaml
+
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def soc_caps(soc_spec: dict, soc: str) -> dict:
+    """解析 SoC 约束：核数（reference 默认）+ UB 容量（同架构一致）。"""
+    block = soc_spec.get("socs", {}).get(soc)
+    if not block:
+        raise SystemExit(
+            f"ERROR: soc-spec 无 {soc} 条目（支持：{list(soc_spec.get('socs', {}))}）"
+        )
+    ref = block.get("reference", {})
+    buf = block.get("buffer", {})
+    return {
+        "core_num": ref.get("ai_core_cnt", {}).get("value")
+        or ref.get("vector_core_cnt", {}).get("value")
+        or 1,
+        "vec_core_num": ref.get("vector_core_cnt", {}).get("value") or 1,
+        "ub_kb": buf.get("ub_kb", 192),
+        "l1_kb": buf.get("l1_kb", 512),
+        "soc_name": block.get("name", soc),
+    }
+
+
+def _align_up(v: int, a: int) -> int:
+    return (v + a - 1) // a * a
+
+
+def _multicore_core_num(total_elems: int, elem_bytes: int, available_cores: int) -> int:
+    """每核最小 4KB 约束下的用核数（与参考实现 calc_multicore_split 同款契约）。"""
+    min_bits = elem_bytes * 8
+    core_num = (total_elems * min_bits + MIN_TILING_BITS - 1) // MIN_TILING_BITS
+    return max(1, min(core_num, available_cores))
+
+
+def candidates_elementwise(
+    shape: list[int], dtype: str, caps: dict, input_count: int
+) -> tuple[list, list]:
+    dim0 = 1
+    for d in shape:
+        dim0 *= d
+    elem_bytes = DTYPE_BYTES.get(dtype, 2)
+    cores = _multicore_core_num(dim0, elem_bytes, caps["core_num"])
+    ub_bytes = caps["ub_kb"] * 1024
+
+    out, pruned = [], []
+    # 候选 1：满核均分（Block Dim 提升机制——L2_UNDERUTILIZATION 的首选候选）
+    block_former = _align_up((dim0 + cores - 1) // cores, ELEM_ALIGN_512)
+    block_num = (dim0 + block_former - 1) // block_former
+    block_tail = dim0 - (block_num - 1) * block_former
+    # 候选 2/3：UB tile 缩减变体（容量联动防护：tile 越小 UB 占用越低，搬运次数越多）
+    for variant, buf_div in (
+        ("full-cores", BUFFER_NUM_DEFAULT * max(input_count, 1)),
+        ("half-tile", BUFFER_NUM_DEFAULT * max(input_count, 1) * 2),
+    ):
+        divisor = buf_div * elem_bytes
+        max_elem = ub_bytes // divisor
+        align_elems = max(ALIGN_256B // elem_bytes, 1)
+        ub_former = max((max_elem // align_elems) * align_elems, align_elems)
+        if variant == "half-tile":
+            ub_former = max(ub_former // 2 // align_elems * align_elems, align_elems)
+        cap_kb = round(
+            ub_former * elem_bytes * BUFFER_NUM_DEFAULT * max(input_count, 1) / 1024, 1
+        )
+        if cap_kb > caps["ub_kb"]:
+            pruned.append(
+                {
+                    "variant": variant,
+                    "reason": f"UB 预算超限（{cap_kb}KB > {caps['ub_kb']}KB）",
+                }
+            )
+            continue
+        out.append(
+            {
+                "variant": variant,
+                "block_dim": cores,
+                "block_former": block_former,
+                "block_num": block_num,
+                "block_tail": block_tail if block_tail > 0 else block_former,
+                "ub_former": ub_former,
+                "ub_loop_former": (block_former + ub_former - 1) // ub_former,
+                "capacity_kb": cap_kb,
+                "capacity_note": f"UB {cap_kb}KB / {caps['ub_kb']}KB（双缓冲 × {max(input_count, 1)} 输入）",
+                "derived": {
+                    "dim0": dim0,
+                    "cores": cores,
+                    "per_core_min_4kb": "dim0×dtype_bits / 32768 向上取整，min(可用核数)",
+                    "block_former": f"ceil(dim0/cores) 向上对齐 {ELEM_ALIGN_512} 元素",
+                    "ub_former": f"(ub_size / (buffer_num×inputs×elem_bytes)) 向下对齐 {ALIGN_256B}B",
+                },
+                "aligned": block_former % ELEM_ALIGN_512 == 0
+                and ub_former % align_elems == 0,
+            }
+        )
+    return out, pruned
+
+
+def candidates_reduction(
+    shape: list[int], dtype: str, caps: dict, axis: int
+) -> tuple[list, list]:
+    """行块切分（AR 型：outer × reduce 折叠）。axis 为归约轴（-1 语义 = 最后一维）。"""
+    if axis < 0:
+        axis = len(shape) + axis
+    outer = 1
+    for i, d in enumerate(shape):
+        if i != axis:
+            outer *= d
+    r = shape[axis]
+    elem_bytes = DTYPE_BYTES.get(dtype, 2)
+    ub_bytes = caps["ub_kb"] * 1024
+
+    out, pruned = [], []
+    # rows_per_ub 受 UB 预算（一行 r 元素 × 双缓冲）
+    row_bytes = r * elem_bytes
+    rows_per_ub = max(ub_bytes // (row_bytes * BUFFER_NUM_DEFAULT), 1)
+    full_load = outer <= rows_per_ub
+    for variant, cores in (
+        ("full-load", min(outer, caps["core_num"])),
+        ("split-rows", caps["core_num"]),
+    ):
+        if variant == "full-load" and not full_load:
+            pruned.append(
+                {
+                    "variant": variant,
+                    "reason": f"outer({outer}) > rows_per_ub({rows_per_ub})，整行驻留不可行",
+                }
+            )
+            continue
+        tiles_per_core = max(outer // cores, 1)
+        cap_kb = round(
+            min(rows_per_ub, outer) * row_bytes * BUFFER_NUM_DEFAULT / 1024, 1
+        )
+        if cap_kb > caps["ub_kb"]:
+            pruned.append(
+                {
+                    "variant": variant,
+                    "reason": f"UB 预算超限（{cap_kb}KB > {caps['ub_kb']}KB）",
+                }
+            )
+            continue
+        out.append(
+            {
+                "variant": variant,
+                "block_dim": cores,
+                "rows_per_ub": min(rows_per_ub, outer),
+                "tiles_per_core": tiles_per_core,
+                "r_chunk": r,
+                "is_full_load": variant == "full-load",
+                "capacity_kb": cap_kb,
+                "capacity_note": f"UB {cap_kb}KB / {caps['ub_kb']}KB（行块 × 双缓冲）",
+                "derived": {
+                    "outer": outer,
+                    "reduce_dim": r,
+                    "rows_per_ub": "ub_size / (行字节 × buffer_num=2)",
+                    "cores": "min(outer, 物理核数)（full-load）/ 物理核数（split）",
+                },
+                "aligned": True,
+            }
+        )
+    return out, pruned
+
+
+def candidates_broadcast(
+    shape: list[int], dtype: str, caps: dict, input_count: int
+) -> tuple[list, list]:
+    """输出 shape 折叠后按末轴 UB 切分（broadcast 侧 stride=0 不占额外预算）。"""
+    total = 1
+    for d in shape:
+        total *= d
+    last = shape[-1] if shape else 1
+    elem_bytes = DTYPE_BYTES.get(dtype, 2)
+    ub_bytes = caps["ub_kb"] * 1024
+    align_elems = max(ALIGN_256B // elem_bytes, 1)
+    max_tile = max(
+        ub_bytes // (BUFFER_NUM_DEFAULT * max(input_count, 1) * elem_bytes), align_elems
+    )
+    ub_former = max_tile // align_elems * align_elems
+
+    out, pruned = [], []
+    ub_outer = (last + ub_former - 1) // ub_former
+    total_tiles = ub_outer
+    for d in shape[:-1]:
+        total_tiles *= d
+    for variant, cores in (
+        ("balanced", min(total_tiles, caps["core_num"])),
+        ("few-cores", max(min(total_tiles, caps["core_num"]) // 2, 1)),
+    ):
+        block_former = max(total_tiles // cores, 1)
+        cap_kb = round(
+            ub_former * elem_bytes * BUFFER_NUM_DEFAULT * max(input_count, 1) / 1024, 1
+        )
+        if cap_kb > caps["ub_kb"]:
+            pruned.append(
+                {
+                    "variant": variant,
+                    "reason": f"UB 预算超限（{cap_kb}KB > {caps['ub_kb']}KB）",
+                }
+            )
+            continue
+        out.append(
+            {
+                "variant": variant,
+                "block_dim": cores,
+                "ub_split_axis": len(shape) - 1,
+                "ub_former": ub_former,
+                "ub_outer": ub_outer,
+                "block_former": block_former,
+                "capacity_kb": cap_kb,
+                "capacity_note": f"UB {cap_kb}KB / {caps['ub_kb']}KB（tile × 双缓冲 × {max(input_count, 1)} 输入）",
+                "derived": {
+                    "total_tiles": total_tiles,
+                    "ub_former": f"ub_size/（buffer×inputs×dtype）对齐 {ALIGN_256B}B",
+                },
+                "aligned": ub_former % align_elems == 0,
+            }
+        )
+    return out, pruned
+
+
+def candidates_conversion(
+    shape: list[int], dtype: str, caps: dict, channel: int
+) -> tuple[list, list]:
+    """channel-flat 形态：按 (channel, 空间) 折叠，tile 元素对齐。"""
+    space = 1
+    for d in shape:
+        space *= d
+    space = space // channel if channel else space
+    elem_bytes = DTYPE_BYTES.get(dtype, 2)
+    ub_bytes = caps["ub_kb"] * 1024
+    align_elems = max(ALIGN_256B // elem_bytes, 1)
+    tile = max(
+        ub_bytes // (BUFFER_NUM_DEFAULT * 2 * elem_bytes) // align_elems * align_elems,
+        align_elems,
+    )
+
+    out, pruned = [], []
+    tiles = (space + tile - 1) // tile * channel
+    for variant, cores in (
+        ("full", min(tiles, caps["core_num"])),
+        ("half", max(min(tiles, caps["core_num"]) // 2, 1)),
+    ):
+        per_core = max(tiles // cores, 1)
+        cap_kb = round(tile * elem_bytes * BUFFER_NUM_DEFAULT * 2 / 1024, 1)
+        if cap_kb > caps["ub_kb"]:
+            pruned.append({"variant": variant, "reason": "UB 预算超限"})
+            continue
+        out.append(
+            {
+                "variant": variant,
+                "block_dim": cores,
+                "tile_elements": tile,
+                "channel": channel,
+                "tiles_per_core": per_core,
+                "capacity_kb": cap_kb,
+                "capacity_note": f"UB {cap_kb}KB / {caps['ub_kb']}KB（in+out 双缓冲）",
+                "derived": {
+                    "tiles": tiles,
+                    "tile": f"ub_size/(buffer×2×dtype) 对齐 {ALIGN_256B}B",
+                },
+                "aligned": tile % align_elems == 0,
+            }
+        )
+    return out, pruned
+
+
+def main() -> int:
+    here = Path(__file__).resolve().parent
+    ap = argparse.ArgumentParser(
+        description="Tiling 候选生成器·四族（容量预算校验 + 剪枝记录）"
+    )
+    ap.add_argument(
+        "--family",
+        required=True,
+        choices=["elementwise", "reduction", "broadcast", "conversion"],
+        help="算子族（首期四族；matmul/mc2 走 Blaze 模板，sort/simt 见族表）",
+    )
+    ap.add_argument("--shape", required=True, help="逗号分隔维度（如 8448,4096）")
+    ap.add_argument("--dtype", required=True, help="fp16/bf16/fp32/int8")
+    ap.add_argument(
+        "--soc", required=True, help="a2/a3/a5（核数与 UB 容量读 soc-spec）"
+    )
+    ap.add_argument(
+        "--soc-spec",
+        default=str(here.parents[1] / "ops-verdict" / "references" / SOC_SPEC_NAME),
+    )
+    ap.add_argument(
+        "--input-count", type=int, default=1, help="输入张量数（UB 预算摊入）"
+    )
+    ap.add_argument(
+        "--axis", type=int, default=-1, help="reduction 族：归约轴（默认末轴）"
+    )
+    ap.add_argument("--channel", type=int, default=1, help="conversion 族：channel 数")
+    ap.add_argument("--output", default=None, help="candidates.json（缺省只打印）")
+    args = ap.parse_args()
+
+    shape = [int(x) for x in args.shape.split(",") if x.strip()]
+    soc_spec = load_soc_spec(Path(args.soc_spec))
+    caps = soc_caps(soc_spec, args.soc)
+
+    if args.family == "elementwise":
+        cands, pruned = candidates_elementwise(
+            shape, args.dtype, caps, args.input_count
+        )
+    elif args.family == "reduction":
+        cands, pruned = candidates_reduction(shape, args.dtype, caps, args.axis)
+    elif args.family == "broadcast":
+        cands, pruned = candidates_broadcast(shape, args.dtype, caps, args.input_count)
+    else:
+        cands, pruned = candidates_conversion(shape, args.dtype, caps, args.channel)
+
+    result = {
+        "schema": SCHEMA,
+        "soc": args.soc,
+        "family": args.family,
+        "shape": shape,
+        "dtype": args.dtype,
+        "input_count": args.input_count,
+        "soc_caps": caps,
+        "candidates": cands,
+        "pruned": pruned,
+        "warning": (
+            "候选表仅供参数选择起点：实施须单变量铁律（一次一个机制）、"
+            "容量运行时复核（GetCoreMemSize 为准，本表为静态估算）、"
+            "全量 case 精度验证（semantic_risk=altered 须边界用例）"
+        ),
+    }
+    if args.output:
+        out = Path(args.output)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(
+            json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        print(f"→ {out}")
+    print(f"{args.family} × {args.soc}：{len(cands)} 候选 / {len(pruned)} 剪枝")
+    for c in cands:
+        print(
+            f"  [{c['variant']}] block_dim={c['block_dim']}  {c['capacity_note']}  aligned={c['aligned']}"
+        )
+    for p in pruned:
+        print(f"  ✂ pruned [{p['variant']}]: {p['reason']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/asc-tools/tool-ops-tune/ops-mechanism/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ops-mechanism
+description: 算子优化机制库与案例证据库。按判定结果（verdict findings 的 mechanism_refs）路由到具体优化机制卡（原理/适用前提/预期收益/架构限制/精度风险/验证命令/回滚条件），并提供同型案例检索（A-E 证据分级、反例入库、无同型降级策略）。触发：瓶颈判定已出、选择优化机制、查案例参考、候选方案卡编写时使用。
+---
+
+# 优化机制库与案例证据库（mechanism）
+
+> **本子域知识资产（机制卡 / 案例卡 / 索引 / 回灌脚本）随「优化卡片知识」PR 交付**，
+> 当前为骨架占位——SKILL.md 先行声明消费时机纪律与路由契约，供判定引擎
+> `mechanism_refs` 字段的前向引用对齐。
+
+## 消费时机纪律（渐进式披露）
+
+**判定之后才加载**。没有 verdict 证据时禁止先加载机制/案例猜瓶颈——证据先行是
+判定质量与上下文预算的双重保障。
+
+## 路由契约
+
+- 判定引擎每条 HIT 规则携带 `mechanism_refs`（指向本子域 `references/optimize/`
+  下机制卡路径）；主 agent 按 findings 逐张加载（≤3 张候选方案卡）；
+- 机制卡八要素与案例卡 A-E 证据分级的书写规范见套件根 `docs/知识库规范.md`；
+- 无同型案例的降级策略：证据链 + 机制卡驱动，实施细节自行推导并提高验证强度，
+  报告标注「无同型案例」，本次证据沉淀为 E 级案例候选。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/cases/ascendc/case_groupedmatmul_pipeline.md

@@ -0,0 +1,23 @@
+# 案例卡：GroupedMatmul 流水线气泡三连优化（AIC:AIV 配比 → workspace 份数 → DoubleBuffer）
+
+- **算子类别**: matmul / grouped matmul
+- **DSL**: Ascend C
+- **类型**: 非 PR（官方递进教程，cann-samples 2_Performance story 系列之一）
+- **来源可信度**: C（官方指南/sample，可运行代码）
+- **来源链接**: gitcode.com/cann/cann-samples 2_Performance story（**验证日期: 2026-10**）
+- **瓶颈证据**: 多单元 30-50% 占比、无明显主导（流水气泡形态；对应本体系 L1_LATENCY_SYNC_SUSPECT / 串行指纹）
+- **优化机制**: ① AIC:AIV 启动比例 1:1→1:2（Cube/Vector 耗时不匹配） ② workspace 份数 2→4（减少互等） ③ DoubleBuffer（锦上添花）
+- **原文性能数字**:
+
+| 阶段 | 耗时 | 增量收益 |
+|------|------|---------|
+| 基线 | 218.1 us | — |
+| AIC:AIV=1:2 | 154.2 us | 29.3% |
+| workspace 2→4 | 131.8 us | 14.5% |
+| DoubleBuffer | 128.1 us | 2.8% |
+| **合计** | **128.1 us** | **41.3%** |
+
+- **适用范围与警示**: ⚠ 数字只代表来源环境；三步是**机制优先级**证据（配比 > workspace > DB），
+  非每步收益承诺；混合绑核 UB 预算须重算。
+- **对应机制卡**: pipeline.md
+- **对应判定规则**: L1_LATENCY_SYNC_SUSPECT / L1_SERIAL_NO_OVERLAP

package/skills/asc-tools/tool-ops-tune/ops-mechanism/cases/ascendc/case_triton_atomic_revert.md

@@ -0,0 +1,19 @@
+# 案例卡：Triton SIMT→SIMD 原子归约 24.5x —— 反例入库样本（后被 revert）
+
+- **算子类别**: reduction
+- **DSL**: Triton-Ascend
+- **类型**: PR（#208/#218 合并；**#376/#405 revert**）
+- **来源可信度**: A（官方已合并 PR 含测试表）→ 收录为**反例**（被 revert）
+- **来源链接**: github.com/triton-lang/triton-ascend PR #208/#218/#376/#405
+  （**验证日期: 2026-10**）
+- **瓶颈证据**: atomic_add_3d 原子操作 SIMT 路径串行化
+- **优化机制**: SIMT→SIMD 原子操作改写
+- **原文性能数字**: 81.163 → 3.309 µs（~24.5x）
+- **适用范围与警示**:
+  - ⚠⚠ **反例**：24.5x 收益后被 revert（PR #376/#405）——合并窗口的收益不等于可持续收益，
+    revert 原因（正确性/兼容性）在采纳同类机制前必须查明；
+  - ⚠ 机制可迁移，数字不可迁移；原子归约类改动属高风险语义变更，验证强度须提高
+    （并发场景 + 异常位型）。
+- **对应机制卡**: api-usage.md（向量化）+ pipeline.md
+- **对应判定规则**: L1_SCALAR_BOUND / L1_LATENCY_SYNC_SUSPECT
+- **收录理由**: 与收益案例同等地位的反例——「负优化/回退记录是瓶颈证据的组成部分」。

package/skills/asc-tools/tool-ops-tune/ops-mechanism/cases/mc2/case_mc2_fusion.md

@@ -0,0 +1,19 @@
+# 案例卡：MC² 通算融合（R 值五档驱动配平 — 反例警示样本）
+
+- **算子类别**: communication / MC²（matmul_all_reduce 类）
+- **DSL**: Ascend C + SHMEM
+- **类型**: 非 PR（社区文章）+ 内部调优实战综合
+- **来源可信度**: D（二手来源，仅作线索与背景）——**本卡价值在方法论示例而非数字**
+- **来源链接**: 社区文章（端到端 1.3x–1.5x 区间报道）+ MC² 通算融合调优实践文档
+  （**验证日期: 2026-10**）
+- **瓶颈证据**: 隔离测试 R 值实测跨 0.3 ~ 9.8（30 倍区间）——R 不是常数，随 shape/量化/
+  rank 数剧烈变化，每 case 必须实测，禁止沿用上一次的 R
+- **优化机制**: Local Matmul（首选，不依赖 R）→ R 驱动配平方向（R<1 计算掩盖通信 /
+  R>1 通信掩盖计算）→ 膨胀控制（最小化瓶颈方膨胀）
+- **原文性能数字**: 端到端 1.3x–1.5x（D 级，不作预期收益依据）
+- **适用范围与警示**:
+  - ⚠ D 级来源：数字仅证明「该机制类有收益记录」，禁止作为当前算子目标；
+  - ⚠ MTE2 污染必须先判：污染场景下做单核访存优化的案例多为负优化；
+  - ⚠ 跨 rank 取 max 口径：用平均口径报告会系统性高估收益。
+- **对应机制卡**: mc2.md / mc2-balancing.md
+- **对应判定规则**: L3_MC2_* 全档 / L3_MTE2_POLLUTED

package/skills/asc-tools/tool-ops-tune/ops-mechanism/references/optimize/api-usage.md

@@ -0,0 +1,70 @@
+# 机制卡：API 使用优化（标量削减 / Cast 削减 / 融合指令）
+
+> 对应判定规则：L1_SCALAR_BOUND、L1_VEC_BOUND（Cast 重反证）、L0_ICACHE_MISS、
+> L2_HEAD_OVERHEAD。内容沉淀自标量与 API 层调优一线实践。
+> **DSL 适用域**：本卡实施细节以 **Ascend C** 为准；Triton / CATLASS / TileLang 的等价原语与实施差异见 [index.md 跨 DSL 原语对照表](index.md#跨-dsl-原语对照六原语--dsl)——跨 DSL 实施时以该表为路由、对应 DSL 专项文档为深度参考，不按本卡字面照搬。
+
+## 标量削减（L1_SCALAR_BOUND）
+
+| # | 方法 | 说明 |
+|---|------|------|
+| 1 | 缩小 TilingData | 字段越少 host→device 搬运越快 |
+| 2 | 减少核数 | 数据量小时少核 = 少头开销（与 A2 满核 ~20-21us 头开销权衡） |
+| 3 | TPipe 外置 | 避免 TPipe 对象内创建初始化 |
+| 4 | 循环不变量外提 | 移到 Host 侧或 kernel 顶层 |
+| 5 | 标量参数向量化 | 常量标量用 `Muls`/广播替代逐元素标量路径 |
+| 6 | 地址计算优化 | areg 地址生成（LayerNormV3 案例：原文未附数字，机制见 cases/） |
+
+scalar >90% 且 vec/mte 低 → 标量访问/地址计算主导：查指针运算与分支，而不是数据量。
+
+## Cast 削减（L1_VEC_BOUND + fp32 ratio 高反证）
+
+- 检查 `aiv_vec_fp32_ratio` vs `aiv_vec_fp16_ratio`：fp32 远高于预期 = 大量 fp16→fp32 转换；
+- 精度允许 → 直接 fp16 计算（**语义变更类**：须精度代价标注 + 边界位型验证）；
+- 必须转换 → 批量一次转换，禁止循环内逐元素 Cast。
+
+## 融合指令
+
+mul+add → Axpy 类、mul+sub 等可融合序列查表合并；`Compare+Select` 链合并。
+
+## 头开销（L2_HEAD_OVERHEAD）
+
+Task Duration − max(aic,aiv) 占比 >30%：数据量太小或核数太多——先减核再谈其它。
+
+## 减少计算量（深度 VEC BOUND 核心策略，沉淀自一线调优实践）
+
+VEC >80% 时微架构调整（DoubleBuffer/融合指令/Bank Align）收益有限——瓶颈在
+计算量本身，须从**算法层减少向量指令数**：
+
+| 手段 | 说明 | 适用条件 |
+|------|------|---------|
+| **LUT + 插值** | 查表+插值替代 Taylor 展开（超越函数每元素数十条 FMA 是计算量大头） | `aiv_vec_ratio` >90% 且 elementwise/activation 类 |
+| 减少超越函数项数 | Taylor 12→8 项 | ❌ 有精度风险，不推荐 |
+
+**Exp 案例（公开 API 路径）**：`AscendC::Exp<T, expandLevel, isReuseSrc>` 的
+`expandLevel = 0` 即内部走查表+插值——无需手写查表逻辑。Log/Tanh 等同理，
+按 asc-devkit 对应 API 的模板参数取查表模式。
+
+**检查方法**：trace 里 `vec_exp`/`vec_log`/`vec_tanh` 等超越函数指令占比
+（trace_bubble 的空泡分类 + 指令统计）；profiling 里 `aiv_vec_ratio` >90% +
+算子含超越函数 → 本策略优先级最高。
+
+## Matmul API 常量折叠（scalar bound 的 matmul 场景，蒸馏）
+
+Kernel 使用 Matmul API 且 `aic_scalar_ratio` ≥ 0.15、shape 可固化或可取上界 →
+把 `TCubeTiling` 解析迁到编译期（constexpr），降低 `aic_scalar_time`。
+
+## 性能友好 API 选择（scalar 削减第 7 法，蒸馏）
+
+- `SetFlag/WaitFlag` 代替 Queue、`LocalTensor` 代替 TBuffer、去除 TPipe——
+  减少封装带来的 scalar 开销；
+- 循环展开小循环减少分支代价；按 tiling 最简化循环轴。
+
+## 验证与回滚
+
+同口径 verdict 复跑（scalar_ratio / vec_fp32_ratio 下降为机制生效证据）；语义变更类
+（fp16 计算）精度用例必附。噪声带内 → revert。
+
+## 模板资产
+
+`ops-family:references/scalar/guide.md`、`ops-family:references/elementwise/vector_efficiency_design.md`。