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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/docs/CONTEXT.md

@@ -0,0 +1,85 @@
+# MC2 通算融合算子生成能力域
+
+MC2（Matrix Computation & Communication）算子生成能力域的领域术语表。覆盖需求分析、方案设计、开发、审查、性能优化全链路。
+
+## Language
+
+### MC2
+
+多卡间集合通信 + 单卡内计算融合，通过通算流水掩盖通信开销。算子类型本质不随芯片或框架变化。
+
+### 决策栈
+
+实现一个通算融合算子需要逐层决策的五层模型。上层选择约束下层的合法集合：
+
+- **L0 需求层**：做什么、在哪跑、怎么被调用。算子类型 × 芯片 × 调用形态。这是输入而非选择。
+- **L1 通信路径层**：数据怎么跨卡搬（引擎 + 协议）。取值：UDMA（URMA 协议的同义称呼，大块搬运，计算密集型）/ MTE通信（AIV+UBMEM，细粒度 + 状态位协议，路由通信密集型）/ CCU（CCU+URMA，尚无直调参考工程）/ HCCL 高阶集合通信（服务端调度黑盒，仅注册场景）。
+- **L2 编程抽象层**：用什么写（buy vs build）。取值即**编码底座**：blaze-shmem（SHMEM 通信库 + Blaze 计算模板，手工组装）/ apace（APACE 模板库，通信+计算+工程组织全包）/ ascendc-api（裸 Ascend C API 全自建，如 MTE通信场景的 compat 层）/ hccl-matmul（HCCL 高阶 + `AscendC::Matmul` 高阶，官方路径，仅注册，知识目录 `references/foundations/hccl-matmul/`）。L1 与 L2 多对多：UDMA 上可用 blaze-shmem 或 apace 底座；apace 底座可跑 UDMA（直调）或 HCCL windows（注册）。
+- **L3 工程组织层**：代码怎么摆。独立 CMake 工程 / 框架共享层 `kernel/<op>/` / 样例工程 + compat 分层。基本被 L2 选定。
+- **L4 流水编排层**：通信与计算怎么重叠。GET/PUT、flag 编排、tileCnt、localMatmul 模式。部分被 L2 给定。
+
+_Avoid_: 把决策栈理解为轴的笛卡尔积——L1×L2 多对多，合法组合只能逐行登记，不能自由组合推导。
+
+### 通信引擎
+
+通信的驱动/执行单元。取值：AIV（向量核直驱，触发 MTE/UDMA 执行跨卡搬运）、AICPU（传统直驱方案）、CCU（专用通信引擎，配对 URMA 协议）。MTE（Memory Transfer Engine）是核内搬运硬件，由 AIV 触发执行，"MTE通信"以此命名。
+
+### 通信协议
+
+跨卡互连协议。取值：URMA（Unreliable Remote Memory Access，与 UDMA 同义）、UBMEM（UB 内存域，超节点/单机内全互联）。
+
+### 通信库
+
+编程接口层，屏蔽通信引擎与协议差异，归属 L2 编程抽象。取值：
+
+- **HCOMM 通信基础库**：最底层通信基础库（控制面管通信域/资源，数据面提供本地操作/同步/通信操作），屏蔽多引擎多协议。HCCL 集合通信库与 APACE 通信基础 API 均基于 HCOMM 构建。
+- **HCCL 集合通信库**：Ascend C 高阶 API 的一部分，基于 HCOMM 构建，服务端调度的集合通信原语（`Hccl::*`）。Kernel 直调场景不可用（依赖框架注入上下文）。
+- **APACE 通信基础 API**：APACE 自建，基于 HCOMM 构建，与 HCCL 集合通信库无关。
+- **SHMEM**：独立通信库（cann/shmem），与 HCOMM 无关，驱动 UDMA/URMA。
+
+_Avoid_: "HCCL 的通信基础库"（HCOMM 与 HCCL 集合通信库是两个东西，应分开说）；把 hcomm 当通信引擎（hcomm 是库，CCU 才是引擎）。
+
+### 编码底座（Foundation）
+
+L2 编程抽象层的实体——编码时立于其上的技术底座。当前四个：`blaze-shmem`、`apace`、`ascendc-api`、`hccl-matmul`，知识库中对应 `references/foundations/{底座名}/` 目录。注意它们不是并列的软件层：apace 是基于 Ascend C 基础 API 构建的模板库（其通信基础 API 基于 HCOMM，与 HCCL 集合通信库无关），ascendc-api 就是裸基础 API 本身，blaze-shmem 是"SHMEM 通信库 + Blaze 计算模板"的手工组装（SHMEM 与 HCOMM 无关），hccl-matmul 是官方 HCCL 高阶集合通信 + `AscendC::Matmul` 高阶（仅注册）——它们抽象层级不同，但在"选什么写代码"这个决策点上是并列选项。
+
+### Ascend C API
+
+最底层编程底座（基础 API + 高阶 API，均经 `kernel_operator.h` 调用），所有 kernel 都基于它书写。高阶 API 含 HCCL 集合通信库（基于 HCOMM 构建，服务端调度）。APACE 是基于 Ascend C 基础 API 构建的模板库（其通信基础 API 基于 HCOMM，与 HCCL 集合通信库无关），但"用 APACE"≠"用裸 Ascend C"——两者约束集、工程边界、可修改范围完全不同，在 L2 层是并列选项。
+
+### 路线（Route）
+
+决策栈上的一条**一致路线**（L0→L1→L2 的具体组合 + 对应 L3/L4 形态），是知识库的组织单元。**路线按底座命名**。当前四条 supported 路线：blaze-shmem 路线（AIV+URMA × blaze-shmem 底座 → `references/foundations/blaze-shmem/`）、apace 路线（AIV+URMA × apace 底座 → `references/foundations/apace/`）、ascendc-api 路线（HCCL window+MTE × ascendc-api 底座 → `references/foundations/ascendc-api/moe-dispatch-combine/`）、hccl-matmul 路线（HCCL 高阶 × hccl-matmul 底座 → `references/foundations/hccl-matmul/`，仅注册）。注意 ascendc-api 路线特指"裸 Ascend C API 全自建"——apace 模板库虽基于 Ascend C API 构建，但属独立底座，与 hccl-matmul（官方高阶 API 组合）也不混。
+_Avoid_: 把"MTE通信"当路线名（它是 L1 通信路径名；该路线按底座命名为 ascendc-api 路线）
+
+### 能力声明（路线登记表）
+
+`references/capability-declaration.md`。登记决策栈上**已验证/规划/明确不支持**的路径，每行 = chip × op_type × 调用形态 × 通信路径 × 编程抽象 + status + reference_impl + 知识目录。含**否定行**（unsupported + 原因），否决项有据可查。供 Architect 在需求分析阶段查询：可行性确认 → 编程抽象选择 → 知识目录路由 → 参考实现定位。
+_Avoid_: 路由表（不仅路由，还声明可用性状态与否定项）；能力矩阵（旧称，三维轴模型已被路径登记模型替代，见 ADR-0002）。
+
+### 调用形态
+
+算子的工程调用方式：Kernel 直调（`<<<>>>`，走 ops-direct-invoke）/ 注册算子（op_host + op_kernel，走 ops-registry-invoke）。L0 的一维，直接砍掉 L1/L2 的部分选项（直调禁 HCCL 高阶、HCCL windows、CCU——后两者无 `__global__` 入口，高阶 API 依赖框架注入上下文）。
+
+### Greenfield
+
+从零开始创建新算子（新建工程、新写代码）。两个现有 plugin 的默认模式。
+
+### Brownfield
+
+基于已有算子做功能拓展或性能优化（修改现有代码，不新建工程）。需要从代码推断路线坐标（命中能力声明中哪一行），做 delta 设计和修改式开发。是两个 plugin 各自的增量能力。
+
+### 算子类型
+
+MC2 算子按设计模式分两类：
+- **集合通信类**（collective-comm）：以集合通信原语（AllToAll/AllGather/AllReduce/ReduceScatter）+ 计算融合为核心。
+- **MOE 类**（moe）：以 MOE 场景的 dispatch/combine 为核心，涉及 expert 路由、token 分发与重排。
+
+### 流程性知识
+
+决定"先做什么、后做什么、门禁条件是什么"的流程编排知识。归属 plugin 层（AGENTS.md / task-prompts / workflow），不归属 skill。
+_Avoid_: 领域知识（领域知识是"怎么选 API、约束是什么"，归 skill）
+
+### 领域知识
+
+特定 MC2 路径下的技术参考——API 用法、工程结构、约束红线、设计模式、需求模板、需求拷问判据。归属 `ascendc-mc2-best-practice` skill。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/docs/MC2-CAPABILITY-PLAN.md

@@ -0,0 +1,111 @@
+# MC2 算子生成能力规划
+
+> 本文档是 MC2 算子生成能力的架构规划，记录通过 grilling + domain-modeling 会话达成的共识。
+> 相关：[领域术语表](./CONTEXT.md) | [ADR-0001](./adr/0001-mc2-skill-not-plugin.md) | [ADR-0002](./adr/0002-decision-stack-path-registry.md)
+> 2026-08-18 更新：能力模型由"三维轴矩阵"修订为"五层决策栈 + 路线登记表"（ADR-0002），落地路径明确为 PR-A（skill）→ PR-B（plugin）。
+
+## 1. 能力域定义
+
+MC2 算子生成能力按**五层决策栈**组织（详见 CONTEXT.md 与 ADR-0002）：
+
+- **L0 需求层**：算子类型（collective-comm / moe）× 芯片（dav-3510 / dav-2201 …）× 调用形态（直调 / 注册）
+- **L1 通信路径层**：UDMA（URMA）/ MTE通信（AIV+UBMEM）/ CCU（CCU+URMA，尚无直调参考工程）/ HCCL 高阶（仅注册）
+- **L2 编程抽象层**：SHMEM 库 / APACE / 裸 Ascend C + compat 层 / HCCL 高阶 + Matmul 高阶（仅注册）。L1×L2 多对多，合法组合只能逐行登记
+- **L3 工程组织层**：独立 CMake 工程 / 框架共享层 / 样例工程（被 L2 选定）
+- **L4 流水编排层**：GET/PUT、flag 编排、tileCnt（部分被 L2 给定）
+
+**路线（route）= 决策栈上的一条一致路线，按底座命名**，当前 supported 三条：blaze-shmem 路线（AIV+URMA × blaze-shmem 底座，3510）、apace 路线（AIV+URMA × apace 底座，3510）、ascendc-api 路线（HCCL window+MTE × ascendc-api 底座，3510+2201）。
+
+两种工作模式：Greenfield（默认）、Brownfield（后续扩展，两个 plugin 各自的增量能力）。
+
+## 2. 核心架构决策
+
+### 2.1 不建独立 plugin（ADR-0001）
+
+`ascendc-mc2-best-practice` 作为纯知识库 skill，被 ops-direct-invoke / ops-registry-invoke 两个 plugin 的 subagent 加载。MC2 横跨直调 + 注册两种形态，复用两个 plugin 的流程骨架。
+
+### 2.2 流程归 plugin，领域知识归 skill（ADR-0001）
+
+| 知识类型 | 归属 | 位置 |
+|---------|------|------|
+| 流程编排（何时拷问、门禁条件、阶段步骤、Step 映射） | plugin | AGENTS.md / task-prompts.md / workflow/SKILL.md |
+| 领域知识（模板、API 用法、约束红线、设计模式、算子分类、拷问维度判据、自检标准） | skill | `ascendc-mc2-best-practice/references/` |
+
+统一适用于需求分析、方案设计、开发、审查所有阶段。**SKILL.md 不出现 CANNBot Step 编号、route.json 等流程概念**（否则与未被 Step 1→7 约束的 plugin 不兼容）。
+
+### 2.3 能力声明 = 路线登记表（ADR-0002）
+
+`references/capability-declaration.md` 登记决策栈上的路径：每行 = chip × op_type × 调用形态 × 通信路径 × 编程抽象 + status + reference_impl + 知识目录。**调用形态当列**（为注册形态路径预留）；**含否定行**（unsupported + 原因，否决有据可查）。芯片知识复用 `npu-arch` skill。
+
+### 2.4 需求分析知识合入 best-practice（单源）
+
+PR #682（`ascendc-mc2-requirement-analysis`）的领域知识（REQUIREMENTS.md 模板、通信路径决策、算子分类速查、拷问 8 维度判据、自检 14 项清单）**单源**存放于 `references/requirement-analysis/`。plugin 侧不保留拷贝，task-prompts 逻辑引用 skill 路径（已有先例：developer agent 引用 `references/foundations/apace/development-guide.md`）。
+
+### 2.5 Brownfield 是两个 plugin 各自的增量能力
+
+代码分析规则（从代码推断路线坐标）作为领域知识放 skill（`references/codebase-analysis.md`，Stub），brownfield 流程编排放 plugin（后续扩展）。
+
+## 3. Skill 内部结构（PR-A 落地后）
+
+```
+ops/ascendc-mc2-best-practice/
+├── SKILL.md                          # 领域边界 + 触发信号 + 决策树 + 红线一句话版 + references 导航
+├── docs/                             # 架构规划（本地，不入 git）
+│   ├── CONTEXT.md                    # 领域术语表（决策栈模型）
+│   ├── MC2-CAPABILITY-PLAN.md        # 能力规划（本文档）
+│   └── adr/
+│       ├── 0001-mc2-skill-not-plugin.md
+│       └── 0002-decision-stack-path-registry.md
+├── references/
+│   ├── capability-declaration.md     # 路线登记表（含否定行）
+│   ├── codebase-analysis.md          # brownfield：从代码推断路线坐标（Stub）
+│   ├── requirement-analysis/         # 需求分析领域知识（单源）
+│   │   ├── template.md               # REQUIREMENTS.md 模板（MC2 特有章节）
+│   │   ├── comm-path-decision.md    # 通信路径选项（L1 层）
+│   │   ├── classification.md         # 算子分类速查 + 可信源清单
+│   │   ├── grill-protocol.md         # 需求拷问 8 维度判据
+│   │   └── quality-checklist.md      # 文档自检 14 项 + 开发就绪闸门
+│   ├── operators/                    # 算子类型跨底座共性设计模式
+│   │   └── collective-comm.md        # 集合通信类：通信语义、轴切分、通算流水模式
+│   ├── foundations/                  # 编码底座（L2 编程抽象的实体）
+│   │   ├── blaze-shmem/              # blaze-shmem 路线知识（AIV+URMA × blaze-shmem 底座）
+│   │   │   ├── workflow_integration.md   # Step 1→7 映射（ops-direct-invoke 场景）
+│   │   │   ├── review-checklist.md       # 审查验收 R1-R7
+│   │   │   ├── mc2_architecture.md / comm_shmem.md / matmul_blaze.md / codebase_map.md
+│   │   │   └── all_to_all_matmul/        # 参考工程
+│   │   ├── apace/                    # apace 路线知识（AIV+URMA × apace 底座）
+│   │   │   ├── workflow_integration.md / review-checklist.md（R1-R8）
+│   │   │   ├── architecture.md / compute.md / communication.md / fusion.md
+│   │   │   ├── operator-anatomy.md / host-and-testing.md / development-guide.md
+│   │   └── ascendc-api/              # ascendc-api 底座（裸 Ascend C 全自建）
+│   │       └── moe-dispatch-combine/ # ascendc-api 路线知识（MTE通信）
+│   │           ├── reading/ / samples/ / api-rules/ / tiling-scheme/
+│   └── shared/                       # 跨底座共性（profiling_mc2.md、pipeline_tuning.md）
+├── scripts/
+│   └── fetch_apace.sh
+└── evals/
+    └── evals.json
+```
+
+## 4. 落地顺序
+
+| 阶段 | 内容 | 状态 |
+|------|------|------|
+| PR-A | skill 重构（基于最新 main）：capability-declaration.md 路径登记模式 + requirement-analysis/ 合入（PR #682 领域知识）+ operators/collective-comm.md + review-checklist×2 + SKILL.md 重构（领域结构 + 红线一句话版 + 全量触发词）+ evals 补强 | 进行中 |
+| PR-B | ops-direct-invoke 加 MC2 支持（greenfield）：subagent 加载 skill、Step 分支、多卡检查、task-prompts（逻辑引用 skill 单源的拷问协议，删除 plugin 内拷贝） | 依赖 PR-A；可改造自 PR #757 |
+| C | ops-registry-invoke 加 MC2 支持（greenfield） | 依赖 PR-A |
+| D | Brownfield 模式扩展（两个 plugin）+ codebase-analysis.md 填充 | 依赖 PR-B、C |
+| E | 新芯片 / 新通信路径（CCU）/ 新编程抽象 / 新算子类型扩展；注册形态路线登记（如 apace × HCCL windows × 注册） | 按需 |
+
+> PR #757（feat/mc2-capability-integration）基于 MTE 合入前的旧 base，其 SKILL.md 骨架化方案（按 Step 组织、route.json 流程红线、触发词缩减、双份拷问协议拷贝）与本规划冲突，已在 2026-08-18 设计讨论中否决；其 plugin 侧改动（agent 加载、多卡检查、task-prompts MC2 prompt）可作为 PR-B 的基础改造复用。
+
+## 5. 扩展操作
+
+| 扩展场景 | 操作 | 影响范围 |
+|---------|------|---------|
+| 新芯片验证通过 | 登记表加/改行 | 仅 capability-declaration.md |
+| 新通信路径（如 CCU 直调落地） | L1 加取值 + 登记表加行 | capability-declaration.md + comm-path-decision.md |
+| 新编程抽象（新框架/库） | L2 加取值 + 登记表加行 + 新建 `references/{新目录}/` | 登记表 + 一个知识目录 |
+| 新算子类型 | L0 加取值 + 登记表加行 + `references/operators/{type}.md` | 登记表 + operators/ |
+| 注册形态路径验证 | 登记表加行（调用形态=注册） | 仅 capability-declaration.md |
+| 新工作模式（brownfield） | plugin 加流程分支；skill 填充 codebase-analysis.md | plugin + 一个 reference 文件 |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/docs/adr/0001-mc2-skill-not-plugin.md

@@ -0,0 +1,31 @@
+# MC2 算子生成能力：不建独立 plugin，知识归 skill，流程归 plugin
+
+## Context
+
+MC2 算子生成能力需要覆盖多芯片型号、多通信路径与编程抽象、多算子类型的组合（非正交）、两种工作模式（greenfield 新算子生成 + brownfield 已有算子拓展/优化）、两种工程形态（Kernel 直调 + 注册算子）。现有 `ascendc-mc2-best-practice` skill 已承载 SHMEM/apace 两条路线的设计开发知识。
+
+> 注：本文的"三维轴矩阵"能力模型已被 ADR-0002 的"五层决策栈 + 路线登记表"替代（仅第 3 条受影响）。
+
+## Decision
+
+1. **不建独立 plugin。** `ascendc-mc2-best-practice` 作为纯知识库 skill，被 ops-direct-invoke（直调）和 ops-registry-invoke（注册）两个现有 plugin 的 subagent 加载。MC2 横跨两种工程形态，复用两个 plugin 的流程骨架。
+
+2. **流程性知识归 plugin，领域知识归 skill。** 需求分析的拷问协议/自检清单/开发就绪闸门、方案设计的流程步骤/门禁条件——这些是 Agent 的决策职责，放 plugin 的 workflow/task-prompts。REQUIREMENTS.md 模板、DESIGN.md 模板、通信路径选项、框架约束、算子设计模式——这些是领域知识，放 skill 的 references。
+
+3. **能力声明放 skill 内部。** ~~`references/matrix.yaml` 声明 chip×framework×op_type 的可用组合~~ **【已被 ADR-0002 替代】** `references/capability-declaration.md` 以路线登记表形式声明决策栈上的已验证/规划/不支持路径，Architect 加载 skill 后查询。芯片知识复用 `npu-arch` skill，不重复。
+
+4. **需求分析知识合入 best-practice。** PR #682（`ascendc-mc2-requirement-analysis`）中的领域知识（模板、通信路径决策、算子分类速查）合入 `ascendc-mc2-best-practice/references/requirement-analysis/`；流程性知识（拷问协议、自检清单）留给 plugin。
+
+5. **Brownfield 是两个 plugin 各自的增量能力。** 代码分析规则（从代码推断路线坐标）作为领域知识放 skill（`references/codebase-analysis.md`），brownfield 流程编排放 plugin。
+
+## Considered Options
+
+- **独立 plugin（ops-mc2-generator）**：被否。MC2 与通用直调/注册算子共享 7 步流程骨架，独立 plugin 会复制流程编排。MC2 的特殊性在领域知识层，不在流程层。
+- **按轴拆分多个 skill（chip/framework/operator 各一个）**：被否。框架知识与算子设计模式高度耦合（如 apace 的通算流水编排不可拆分为"框架通用知识"+"算子通用知识"的简单叠加），拆分后交叉引用复杂。
+- **需求分析独立 skill（PR #682 现状）**：被否。需求分析阶段的 MC2 领域知识（通信路径选项、算子分类）与开发阶段的领域知识有重叠和依赖，独立 skill 会导致知识漂移或跨 skill 引用。
+
+## Consequences
+
+- `ascendc-mc2-best-practice` 承载量增大（需求+设计+开发+审查+brownfield 全链路领域知识），通过 references 目录分层和渐进式披露控制。
+- 两个 plugin 需各自增加 MC2 特化分支（task-prompts / workflow），流程编排维护在 plugin 侧。
+- 扩展新路径时，领域知识改 skill，流程不变；扩展新工作模式时，流程改 plugin，领域知识不变。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/docs/adr/0002-decision-stack-path-registry.md

@@ -0,0 +1,33 @@
+# 能力模型：五层决策栈 + 路线登记表（替代三维轴矩阵）
+
+## Context
+
+ADR-0001 第 3 条将能力声明定义为 chip × framework × op_type 三维轴矩阵。实施时发现该模型装不下实际能力域：
+
+1. **MTE通信（MoE 路径）无法入轴**。main 已合入 MoE dispatch/combine 体系（`b4e8f727`），其通信路径是"HCCL window 资源分配 + 裸 Ascend C（MTE/DataCopyPad）搬运 + 状态位协议"——它不是"基础框架"（软件实体），`framework ∈ {shmem, apace}` 的取值集合无法表达。
+2. **三轴概念层级混杂**。SHMEM 是通信库（仅通信），APACE 是模板框架（通信+计算+工程组织，且基于 Ascend C API 构建），MTE通信是通信路径/设计模式——三者不是同类事物，压成一维取值概念上不成立。
+3. **真实决策过程是多层的**。需求分析层本来就把"通信路径选型"（comm-path-decision）与"编程抽象选型"（SHMEM 库 vs APACE）分开决策；且 L1（通信路径）与 L2（编程抽象）是多对多关系（UDMA 上可跑 blaze-shmem 或 apace 底座；apace 底座可跑 UDMA 或 HCCL windows），轴的笛卡尔积会推导出大量不存在的组合。
+4. **调用形态与否定项需要登记位置**。apace 的 HCCL windows 变体仅限注册场景；"直调 × HCCL 高阶"这类常见误答需要明确否决依据，防止模型自由发挥。
+
+## Decision
+
+1. **能力模型定义为五层决策栈**：L0 需求层（op_type × chip × 调用形态）→ L1 通信路径层（UDMA(URMA) / MTE通信(AIV+UBMEM) / CCU / HCCL 高阶）→ L2 编程抽象层（blaze-shmem / apace / ascendc-api / HCCL 高阶+Matmul 高阶）→ L3 工程组织层 → L4 流水编排层。术语定义见 CONTEXT.md。
+2. **能力声明语义为"路线登记表"**（`references/capability-declaration.md`）：每行 = 决策栈上一条一致路线 + status + reference_impl + 知识目录。不再是轴的笛卡尔积格子。
+3. **调用形态进表当列**（直调/注册），为 apace × HCCL windows × 注册 等路径预留登记位置。
+4. **登记表含否定行**：明确不支持的组合（直调 × HCCL 高阶、直调 × HCCL windows/CCU、dav-2201 × AIV+URMA）+ 原因，否决有据可查。
+5. **路线（route）= 决策栈路径的标签，按底座命名**，是知识库组织单元；当前 supported 路线三条：blaze-shmem 路线、apace 路线、ascendc-api 路线。"MTE通信"为 L1 通信路径名（AIV+UBMEM），不再作路线名；ascendc-api 路线特指裸 Ascend C API 全自建，与"基于 Ascend C API 构建模板库"的 apace 路线不混。
+6. **L2 编程抽象的实体命名为"编码底座"，知识库以 `references/foundations/{底座名}/` 组织**：`shmem/` 更名 `foundations/blaze-shmem/`（旧名把 SHMEM 库与"SHMEM 库+Blaze 组装"的路线混为一谈），`apace/` 移入 `foundations/apace/`，`moe-dispatch-combine/` 移入 `foundations/ascendc-api/`（ascendc-api 路线的底座即裸 Ascend C API）。底座目录直接承载该底座上的路线知识，当前 1:1，未来同底座多路线时以子目录区分。
+
+## Considered Options
+
+- **一维 route 路由标签（值即目录名）**：被否。承认通信路径×底座×工程组织不可分割，实用但概念混杂；且未来"同通信路径长出新底座"（如 mte-window 上的框架）时需要造复合值，扩展性差。
+- **保留 framework 轴仅扩值（+mte-window）**：被否。MTE通信不是框架（无软件实体），撑破 CONTEXT.md"基础框架"定义；与 apace 的 HCCL windows 模式撞词。
+- **两级四维矩阵（chip × mechanism × framework × op_type）**：部分采纳——决策栈吸收了其正交性洞察（L1/L2 分层），但矩阵形态改为路线登记表，避免稀疏矩阵的非法组合推导问题，且调用形态必须入表。
+
+## Consequences
+
+- ADR-0001 第 3 条（matrix.yaml 三维矩阵）被本条替代；其余各条（不建独立 plugin、流程归 plugin 领域归 skill、需求分析知识合入、Brownfield 增量）继续有效。
+- 扩展语义清晰：新芯片 = 加/改行；新通信路径 = L1 加取值 + 加行；新编程抽象 = L2 加取值 + 加行 + `references/foundations/{新底座}/`；新算子类型 = L0 加取值 + 加行；注册形态路径 = 加行。
+- `comm-path-decision.md` 对齐为 L1 通信路径层选项说明（补 MTE通信）。
+- 需求文档模板 §6.2 通信引擎选项同步补 MTE通信 / CCU。
+- 目录重构：`references/{shmem,apace,moe-dispatch-combine}/` → `references/foundations/{blaze-shmem,apace,ascendc-api/moe-dispatch-combine}/`，全量链接同步修复；能力登记表的"编程抽象"列值即底座目录名。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/evals/evals.json

@@ -0,0 +1,315 @@
+{
+  "skill_name": "ascendc-mc2-best-practice",
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "通算融合算子开发完整工作流",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "请介绍 Ascend C 通算融合算子（多卡通信+计算融合 Kernel 直调）的开发完整工作流，需要包括哪些步骤？",
+      "expected_output": "1. 回复应给出 SHMEM/UDMA（AIV+URMA）路径的 7 步开发流程：环境检查 → 设计（DESIGN.md/PLAN.md）→ 设计串讲（Walkthrough）→ 代码开发 → 代码检视 → 修复循环 → 性能验证验收。\n2. 回复应说明开发前需先按决策树/路线登记表判断算子的通信路径与底座（AIV+URMA 的 blaze-shmem/apace、MTE通信的 ascendc-api、集合通信注册的 hccl-matmul），不能跳过路线决策直接开发。\n3. 回复应说明 ascendc-api 路线（MTE通信，MoE Dispatch/Combine）默认拆成 samples 规格补齐与样例工程、api-rules、tiling-scheme 三部分推进。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "两条通信路径的区分与决策",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "通算融合算子开发中，SHMEM/UDMA 路径和 MTE通信分别用在什么场景？如何判断一个算子该走哪条路线？",
+      "expected_output": "回复应说明：SHMEM/UDMA 路径适合计算密集型通算融合（AllToAll+Matmul、AllReduce+Matmul、TP/SP），MTE通信适合路由通信密集型场景（MoE Dispatch/Combine、专家并行 EP、token 路由分发、mega_moe）；判断方法看通信路径——SHMEM API = SHMEM/UDMA 路径，winContext/mc2Context = MTE通信。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "SHMEM 路径约束：通信与计算红线",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "开发 AllToAll+Matmul 通算融合算子时，通信和计算有哪些强制约束？为什么不能用 HCCL 高阶 API 和 asc-devkit Matmul 高阶 API？",
+      "expected_output": "回复应说明：通信必须走 SHMEM（host 侧 aclshmem_*，device 侧 aclshmemx_udma_* + aclshmem_barrier_all），禁止 Hccl::AllReduce/AlltoAll 等高阶 API；Matmul 必须走 Blaze 模板（Block::BlockMmad + Kernel::*）；原因是 HCCL 和 AscendC::Matmul 高阶 API 依赖框架注入的 GetHcclContext 上下文，Kernel 直调场景拿不到该上下文，无法使用。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 4,
+      "title": "ascendc-api 路线（MTE通信）约束：MoE 特化四红线",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "开发 MoE Dispatch 或 MoE Combine 算子时，ascendc-api 路线（MTE通信）有哪些强制约束？",
+      "expected_output": "回复应覆盖 ascendc-api 路线（MTE通信）的四大约束：① 跨卡搬运走 MTE通信，禁止 Hccl::AlltoAll/AlltoAllV/AllReduce 等高阶原语做数据搬运；② window 地址必须走 compat 层（GetBaseWindAddrByRankId 等统一接口），禁止直接硬编码 HcclA3OpResParam/HcclA5OpResParam 字段偏移；③ 共享 GM/状态区走 DataCopyPad，禁止 GetValue/SetValue 直接访问；④ 状态协议：先数据后状态、每核只写自己槽位、消费后清理。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 5,
+      "title": "ascendc-api 路线（MTE通信）的工程推进方式",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "我要生成一个新的 MoE dispatch 算子，或者在样例工程基础上改造。请先加载 ascendc-mc2-best-practice 技能并阅读其 SKILL.md 后回答：1）这类任务命中哪条路线，是否还套用通用 add.asc 模板？2）入口 B「生成新算子或在样例工程基础上改造」默认拆成哪几部分，每部分按顺序要读哪些文档——samples 的规格补齐与数据流路径、api-rules 覆盖哪些 MoE 特化主题、tiling-scheme 的分核方案按哪几个环节推进？3）如果任务同时包含「先阅读现有实现」与「再进行改造」，入口 A 与入口 B 的先后顺序是什么？",
+      "expected_output": "1. 应判定 MoE dispatch 生成/在样例工程上改造命中 ascendc-api 路线（MTE通信），不再套用通用 add.asc 模板，并按入口 B 默认拆成 samples / api-rules / tiling-scheme 三部分推进。\n2. 应说明 samples 部分走 spec-template.md → dispatch-dataflow.md 或 combine-dataflow.md 的规格补齐与样例工程路径，api-rules 部分覆盖 MoE 特化的 DataCopyPad、window 地址获取、同步与可见性、状态协议、dispatch/combine 接口契约。\n3. 应说明 tiling-scheme 分核方案按 window-memory-layout → multi-core-formulas → split-core-design → double-buffer-protocol 四环节推进；若任务同时包含「先阅读现有实现」与「再进行改造」，先走入口 A 阅读路径再进入入口 B 规格补齐。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 6,
+      "title": "通算融合 Skill 与其他 Ascend C 技能的区分（正向看护）",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "ascendc-direct-invoke-template",
+          "ascendc-api-best-practices",
+          "ascendc-tiling-design",
+          "npu-arch"
+        ]
+      },
+      "prompt": "我想开发一个多卡通信和计算融合的 Ascend C 算子，需要遵循哪些开发规范？",
+      "expected_output": "回复应聚焦通算融合算子的开发规范与约束：先按决策树判断走 SHMEM/UDMA 路径（通信走 SHMEM、Matmul 走 Blaze 模板）还是 ascendc-api 路线（MTE通信，MoE Dispatch/Combine 四红线），并说明与普通 Kernel 直调开发流程的区别。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 7,
+      "title": "能力声明查询：supported 路径与参考实现",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A5"
+        ]
+      },
+      "prompt": "Ascend 950 上用 apace 框架开发集合通信类 MC2 算子（Kernel 直调），支持吗？有哪些参考实现？",
+      "expected_output": "回复应查询 capability-declaration.md 路线登记表，确认 dav-3510 × collective-comm × 直调 × AIV+URMA × APACE 为 supported，列出参考实现（all_to_all_quant_matmul、all_gather_quant_matmul，位于 ops-transformer 仓 mc2/common/op_kernel/apace/kernel/），并路由到 references/foundations/apace/ 知识目录。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 8,
+      "title": "能力声明查询：否定行给出确定否决",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A2"
+        ]
+      },
+      "prompt": "我的服务器是 Ascend 910B（dav-2201），想用 SHMEM-UDMA 写一个 AllToAll+Matmul 通算融合直调算子，可以做吗？",
+      "expected_output": "回复应查询 capability-declaration.md 否定行，明确答复不可用：dav-2201 × UDMA 为 unsupported（UDMA 路径仅 dav-3510 已验证）。替代建议：910B 上集合通信+Matmul 走 hccl-matmul 注册路线（HCCL 高阶 + AscendC::Matmul，aclnn），或更换目标架构为 Ascend 950 再走 blaze-shmem/apace 直调。不得含糊应答或直接按 SHMEM 开始开发。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 9,
+      "title": "能力声明查询：ascendc-api 路线（MTE通信）双平台",
+      "config": {
+        "max_tokens": 500000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 520000
+        },
+        "ascend_platforms": [
+          "A3"
+        ]
+      },
+      "prompt": "A3 平台上开发 MoE Dispatch 算子（Kernel 直调），有支持的路径吗？参考什么知识？",
+      "expected_output": "回复应查询 capability-declaration.md，确认 dav-2201 × moe × 直调 × HCCL window+MTE 为 supported（compat 层抹平 A3/A5 window 结构差异），路由到 references/foundations/ascendc-api/moe-dispatch-combine/ 知识目录（samples/api-rules/tiling-scheme），参考实现为 moe_dispatch_direct_invoke_sample。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 10,
+      "title": "apace 按请求目的路由（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要用 apace 在 Ascend 950 上开发一个 AllToAll+QuantMatmul 通算融合算子。请分别说明：1) 明确要求从零完整开发算子时走哪几步；2) 只要求算子设计、方案分析并输出设计文档时走哪些步骤；3) 只做咨询/解释/评审/排障时如何执行。",
+      "expected_output": "应说明：明确要求开发算子时走 Step 1→2→3→4 完整流程（plugin 场景以 workflow_integration.md 的 7 步映射为主要消费文档）；只要求设计时走 Step 2→3；咨询/解释/评审/排障时只读取相关 references。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 11,
+      "title": "apace 路线模型判定（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "apace 开发中如何决定实现路线选择 apace_native、apace_custom 还是 unsupported？各自的判定依据是什么？PUT/GET/compute-first 在这个模型中扮演什么角色？",
+      "expected_output": "应说明按官方 README 双模式决策：官方 apace/kernel 已有算子可直接调用或参考复用时选 apace_native（不读取场景注册表）；官方 kernel 未覆盖但可基于 apace/block 接口组合构建（含 compute-first 等自研编排）且场景唯一命中时选 apace_custom；block 接口层无法支撑或场景零命中/多命中时选 unsupported。并说明官方接口未覆盖不是绕过 apace 接口层、退回裸 Ascend C 全自建的授权——那是 ascendc-api 底座的路线选择，不是 apace 路线内的 fallback。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 12,
+      "title": "apace 计算执行原则（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我计划把 apace 算子里的部分通信步骤（如数据打包/解包）放到 Host 侧实现，Kernel 里只做 MatMul。这样是否允许？为什么？",
+      "expected_output": "应说明通信与计算的流水编排、AIV-AIC 协同必须在 device 侧单次 launch 的融合 Kernel（MIX）中完成；host 侧只负责数据准备与 buffer 分配、Tiling 计算、多 rank 启动与通信建链（rootInfo 交换、HCCL/Win 资源分配、跨 rank barrier）、Kernel launch（含 dtype dispatch）和结果搬运；不得将算子语义中的任何计算或通信步骤（如归约、数据搬移、状态同步）放到 host 侧执行；CPU golden 等精度验证基建不属于算子语义，不在此限。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 13,
+      "title": "apace golden 切分轴错误必须先修 golden 再怀疑 kernel",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "一个 ReduceScatter+QuantMatmul compute-first 算子精度验证 golden 全错、误差不收敛。开发者想直接修改 kernel 代码。请给出正确的定位顺序，不执行工具。",
+      "expected_output": "应先核对 golden 语义（每卡输入/输出分布与切分轴），确认切分轴（M/N/K 哪根轴按 rank 切）是否正确——golden 切分轴写错则精度验证整体失效，先修 gen_data 再怀疑 kernel。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 15,
+      "title": "apace 归约 in-place Cast 导致精度系统性错误",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "一个 compute-first 算子的归约结果系统性错误，误差随来源序累积。开发者怀疑是归约公式问题，想修改归约的累加顺序。请给出正确的根因分析和修复方向，不执行工具。",
+      "expected_output": "应识别 in-place BF16→FP32 Cast 是根因（FP32 占 2× 空间覆盖未读 BF16 数据），修复方向是使用独立 srcFP32 双缓冲（R18），而不是修改归约累加顺序。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 16,
+      "title": "apace L2 flush 死代码导致性能数据不可复现",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "性能采集发现 MTE2 带宽虚高、数据不可复现。代码中分配了 cacheFlush buffer 但未调用 flush kernel。开发者认为 buffer 分配了就算 flush 了。请给出正确的分析和修复方向，不执行工具。",
+      "expected_output": "应指出只分配 cacheFlush buffer 不调 kernel = 死代码 = MTE2 带宽虚高（R20）。修复方向是每轮主 kernel 前实际调用 L2 flush kernel（如 heavy_add_kernel），msprof 记录数 == 轮数。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 17,
+      "title": "apace 场景唯一命中授权（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "对当前 CANN 内置 apace 框架完成调查后，发现官方只有 PUT 模式的 AllToAll 和 AllGather 参考算子，没有 GET 模式的参考实现。用户要求开发 GET 模式 AllGather+QuantMatmul。请说明应如何记录调查结果并选择下一步，不执行工具。",
+      "expected_output": "核对结果必须记录为 not_found（AllGather GET 钩子未见源码记录；仅 AllToAll GET 钩子 all_to_all_udma_get.h 有记录），而不是 unknown 或 unsupported；说明声明读取边界内未找到不等于 apace 不支持，不得据此虚构接口或文件名。应保留官方 PUT 参考算子作为接口组合参照，复用已验证的 block 层接口，并把 GET 模式 kernel 开发、场景注册和验证列为适配与证据闭合项。场景注册表唯一命中 get-all-gather-quant-matmul 时选择 apace_custom。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 18,
+      "title": "apace 问题记录格式（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "一个 apace 算子在编译阶段发现 ASC 设备编译报架构未选择。开发者想直接标记为 actual_failure 并记录为设备编译失败。请说明正确的分类和记录格式，不执行工具。",
+      "expected_output": "编译阶段发现的架构未选择问题属于设计/构建前风险，不能写成已经发生的设备失败。生产失败案例应按'现象 → 根因 → 修复方向'补入 review-checklist.md 常见 FAIL 原因表；设备结论必须标注执行环境、设备节点、实际命令和返回码，编译/静态通过不能写成设备已验证。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 19,
+      "title": "apace 四步流程边界（关键能力）",
+      "config": {
+        "max_tokens": 500000,
+        "ascend_platforms": [
+          "A5"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "apace 四步流程中，Step 2（Framework Investigation）和 Step 3（Design）各自的边界是什么？Step 2 可以推荐实现路线吗？Step 3 可以写实现代码吗？",
+      "expected_output": "应说明：Step 2 是设计前核对——只读核对 apace 框架的接口事实（matmul 链路/通信接口/入口 ABI/官方覆盖性），事实默认内联于 DESIGN.md §0.3，不做方案推荐、不匹配场景、不选择路线、不编译或运行设备；Step 3 依据需求和核对事实完成路线决策，生成冻结的 DESIGN 和 PLAN，不复制文件、不写实现、不构建项目。每个步骤都有明确的边界声明。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 20,
+      "title": "910B HCCL 高阶注册路线（hccl-matmul）",
+      "config": {
+        "max_tokens": 100000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要在 Ascend 910B（dav-2201 / A2）上开发 AllGather+Matmul 通算融合算子，用 HCCL 高阶 API 和 AscendC::Matmul，通过 aclnn 单算子调用。应该走哪条路线？通信和计算有哪些红线？PTA 怎么接？",
+      "expected_output": "应查询 capability-declaration.md，命中 dav-2201 × collective-comm × 注册 × HCCL 高阶 × hccl-matmul 为 supported，路由到 references/foundations/hccl-matmul/，参考实现 all_gather_matmul。红线：仅注册禁止 <<<>>> 直调；通信走 Hccl<HCCL_SERVER_TYPE_AICPU> V2（InitV2/SetCcTilingV2），禁止 SHMEM/Blaze；AIC-only + Finalize 前 CrossCore 同步；无 quant。PTA 不在本路线重做，走 torch-ascendc-op-extension 路线 B（aclnn 注册）。",
+      "expectations": [],
+      "files": []
+    }
+  ]
+}