| name | shmem-ops-design |
| description | 基于 SHMEM 设计通信算子与通算融合算子，将需求转化为 design.md。关键词：基于SHMEM算子设计、算子设计、设计文档、design、Canonical DSL、capability mapping。 |
SHMEM 算子设计
Skill类型：文档生成型（需求分析 → 设计文档输出）
中文写作要求：design.md 必须使用中文撰写。仅 API 名称、代码片段、变量名、DSL 字段名等技术术语保留英文原文。
将用户需求转化为可被 shmem-ops-code-gen 直接消费的 design.md。本 skill 只产出设计文档，不生成实现代码。
必读资料
设计前必须读取本 skill 的 reference：
当 API 名、能力边界、示例路径或约束不明确时，先定位 SHMEM_REPO（shmem-repo-resolution.md），再检查 ${SHMEM_REPO}/include/、src/、examples/、tests/、docs/ 下的真实代码和文档。
核心原则
- 语义优先：先统一语义，再选择 API、模板和调度策略
- 名称与类型先行：设计开始前 MUST 从编排器传入的
phase0_intake 中读取 op_name 和 dtype/dtypes；未读取前不得进入 Canonical DSL、能力映射或执行方案设计
- 语义与调度分离：区分 semantics 和 schedule——semantics 描述必须发生什么，schedule 描述如何高效执行
- 缺失不脑补：缺失信息必须写入 assumptions、open questions 或 gap analysis，不能静默脑补 topology、visibility、sync、dtype、shape
- 复用优先：优先复用 SHMEM 已有 API、模板和 examples；新增模块必须说明原因、风险和验证方式
- 面向代码生成：输出必须面向代码生成，避免只写概念性 prose
Phase 0 Intake 读取
编排器在 Phase 0 已通过五项 AskQuestion 确认以下信息，记录在 phase0_intake 中（字段定义见 intake-checklist.md）。本 skill MUST 直接从 phase0_intake 读取，禁止就已确认项向用户再次提问。
| 字段 | 来源 | 用途 |
|---|
op_name | phase0_intake | 目录名、文件名前缀、kernel/target 命名 |
dtype | Phase 0 Step 0.2 需求收集 | 输入/输出/中间计算 dtype |
build_mode | phase0_intake | meta.build_mode |
torch_required | phase0_intake | meta.torch_required |
performance_required | phase0_intake | meta.performance_required |
performance_auto_optim | phase0_intake | meta.performance_auto_optim |
shmem_repo | phase0_intake | 仓内文件定位 |
docker_container | phase0_intake | 是否 docker exec |
| 网络拓扑 | Phase 0 Step 0.2 需求收集 | SoC 型号 → 推断默认拓扑（如 910B3 → 8 卡 full-mesh） |
读取后 MUST 在 design.md 的 source.user_confirmations 中记录各字段值，来源标注 phase0_intake。
design.md 中不得留下阻塞的 dtype/open name/拓扑问题；否则不能交给 shmem-ops-code-gen。
步骤 1：输入规范化与语义提升
把自然语言、伪代码、异构参考实现统一成 Canonical DSL。
伪代码处理（用户提供伪代码时 MUST 执行）
用户提供伪代码时，MUST 完整通读并逐段拆解，NEVER 跳过或粗略浏览后直接照搬：
- 逐段拆解：识别伪代码中的局部计算段、跨 PE 数据搬运段、同步等待段
- 数据搬运映射：伪代码中隐式的跨 PE 数据访问必须显式映射为 SHMEM 原语：
- "从其他 PE 读取数据" →
aclshmem_*_get（MTE/SDMA/RDMA 择一，设计阶段不需要锁定具体引擎）
- "向其他 PE 写入数据" →
aclshmem_*_put_nbi
- "广播/收集/散布" → 对称堆 + get/put + signal/wait 或 barrier 的组合
- 所有跨 PE 搬运均经对称堆 staging：input(GM) → copy_in(symmetric) → put/get → copy_out(GM)
- 伪代码中的"共享变量""全局数组"在 SHMEM 中不存在，不可直接引用为可寻址内存
- 同步映射：伪代码中的 ready/done/flag → signal/wait/barrier/fence/quiet
- 禁止机械照搬：NEVER 将伪代码的变量名、循环结构、内存模型直接当作 SHMEM 实现。必须经过语义提升后再设计。
- 分核解耦：伪代码通常是单线程视角，设计时必须按 core-allocation.md 将单线程逻辑映射为多 AIV/AIC 的分组执行方案
执行要求
- 使用
phase0_intake 中读取的 op_name、dtype 和网络拓扑，并抽取 op_kind、target SoC、scope、shape、attrs、输出可见性。
- 将需求提升为三类语义：
- local compute：每个 PE 本地计算什么
- communication：跨 PE 交换、搬运、规约或同步什么
- finalize/result：最终输出由谁持有，replicated/sharded/owner-only 如何定义
- 将异构参考实现转成 SHMEM 语义，而不是机械照搬 API：
- send/recv -> put/get/exchange
- reduce/allreduce/reducescatter/allgather -> collective semantic，再映射到 SHMEM 能力
- ready/done/flag -> signal/wait/barrier/fence/quiet
- 按 references/op-dsl.md 填写 Canonical DSL；
meta.op_kind 判定规则见 op-dsl §3，并决定 code-gen 模板：fused_compute_comm → fused-compute GUIDE，其余 → communication 子模板。
DSL 必须显式包含：interface、semantics、topology、memory、schedule、correctness、performance。
DSL topology 必须写明：
deployment：intra_node（单服务器内）或 inter_node（跨服务器）intra_node_topology：full-mesh / switch / ring（来自 phase0_intake）intra_node_link_bandwidth_gbps：单条链路单向带宽（如 28）intra_node_links_per_npu：每 NPU 的 HCCS 链路数（如 7）- 跨服务器时还需写明
inter_node_fabric（RoCE / IB）和 inter_node_bandwidth_gbps
步骤 2：SHMEM 能力盘点与复用映射
目标不是列 API，而是判断每个需求点如何落到 SHMEM 现有能力。
对每个需求点给出唯一分类：
| 分类 | 含义 | 必填信息 |
|---|
| 可复用 | 已有 API、模板或 example 可直接使用 | 文件/API/example 路径，以及为什么匹配 |
| 需适配 | 已有能力基本匹配，但需要参数化、封装或调度调整 | 适配点、约束和风险 |
| 需新实现 | 现有能力不能覆盖 | 缺口、候选设计、fallback 和验证方式 |
能力映射至少覆盖六类：
- lifecycle：init/finalize、PE/team、bootstrap、资源生命周期
- memory：对称内存、地址翻译、本地/远端/UB buffer、输出可见性
- transport：MTE、RDMA/RoCE、SDMA、RMA put/get、非连续或 chunk 搬运
- sync：signal/wait/test、barrier/sync、quiet/fence、顺序约束
- compute：本地 AscendC/CATLASS 计算、dtype cast、accumulation、reduce
- scheduler：phase 顺序、tile/chunk、分核、stream/async/overlap
design.md 必须包含 Capability Mapping & Gap Analysis 合并表。凡是”需新实现”，都必须在同行写明 gap 原因、设计方案、验证方式和 correctness/performance risk。
步骤 3：执行方案设计
在 DSL 的 schedule、correctness 和 performance 中填写完整执行方案。
设计前必须读取 references/core-allocation.md，并优先复用其中总结的分核模式（A/B/C）、examples 分核经验和动态 tiling 参数。
MUST 在进入 core_partition 设计前，完成拓扑并行度分析：
- 读取 DSL
topology：明确 intra_node_topology（full-mesh/switch/ring）、intra_node_links_per_npu、intra_node_link_bandwidth_gbps
- 计算拓扑的理论最大并行链路数（如 full-mesh 8 卡 = 7 条独立 HCCS 链路每 PE）
- 设计时确保通信 phase 中同时活跃的链路数尽量接近最大并行链路数——若设计中 peer 维度串行（如
for peer in range(n_pes-1) 每次只 get_nbi 一个），必须显式标注为瓶颈并在 Design Review 中记录原因
- 优先方案：SetAtomicAdd（MTE 批量 in-flight）、按 peer 分核独立搬运、多 lane 交错等
DSL schedule 按以下顺序设计（先拓扑分析 → 分核 → 再 tiling → 最后 phases）：
-
core_partition（最先设计）：
mode：引用 core-allocation.md 的模式（A 全员协作 / B 按 PE 分组 / C1 生产者消费者 / C2 维度分组 / C3 引擎分组 / CoC 通算融合）groups：每组核的编号范围、职责、使用的数据接口。职责描述必须精确到以下三要素，禁止笼统概括：
- AIV→数据区间映射：每个 AIV 负责哪段数据，写出
offset 和 len 公式（及尾块处理方式，参考 core-allocation.md §6）
- AIV→PE 映射：每个 AIV 负责哪个/哪些 PE 的数据（写出 PE 编号映射公式或迭代顺序，如
for peer in [my_pe, (my_pe+1) % n_pes, ...]）
- 本地 vs 远端路径：self PE 使用本地快路径还是与其他 PE 走同一路径，明确写出
- 设计时必须参照 core-allocation.md §2 对应模式的分核公式（如模式 B 的
pe_idx = aiv_idx / core_per_rank）填写上述三要素
overlap：组间如何重叠（并行 / 2-stage pipeline / 无）sync_between_groups：组间同步方式（cross-core flag / barrier / signal-wait / quiet）rationale：引用 core-allocation.md 或 shmem/examples 路径cross_pe_dataplane：跨 PE 数据面接口（必须是 aclshmem_* 或 aclshmemx_*）
-
tiling（分核之后设计）：每组核的 tile、chunk、tail 处理方式
-
phases（最后设计）：device 侧大体执行流程，每个 phase 仅需 name + action（一句话中文描述），不需要写 input/output/dependency/sync 等微观细节
DSL correctness.invariants 每项必须含 invariant、test_method、case。
DSL performance 必须填写 baseline_search、baseline_target、min_scale。
baseline_search 必须记录的搜索步骤（参考 ../shmem-ops-performance-eval/references/baseline-selection.md 的 Baseline 选择决策树）：
- 查找 HCCL 集合通信算子：AllGather、AllReduce、ReduceScatter、AllToAll、Broadcast、Reduce、Scatter、Gather
- 查找 aclnn 扩展算子：aclnnAlltoAllV 等
- 是否可用 HCCL + CATLASS/AscendC 串行拼接（如 AllToAll + MatMul）
- 以上均无 → 填写
"metric_only" 并记录搜索过程
常见遗漏：HCCL 库包含 AllToAll 算子（HcclAlltoAll）。设计时不要误认为这些算子没有 baseline。
算子实现边界
设计文档必须明确 Device kernel、main.cpp、Host helper、Python scripts 四层职责边界，且 kernel 默认 unified single path（见 references/implementation-boundary.md）。
schedule.core_partition 必须说明 Device kernel 的分核策略，不能写成"Host 侧执行"。
步骤 4：生成契约输出
按 references/design-template.md 输出到算子目录的 docs/design.md（docs/ 目录若不存在则创建）。如果用户指定路径，写到指定路径；否则写到当前算子/工程目录的 docs/design.md，无法判断时写到当前 workspace 的 docs/design.md。不得将 design.md 放置在算子根目录。
输出前必须完成设计走读，走读项见 references/design-template.md section 5。走读失败时先修订 DSL 的 schedule、correctness 或 performance 字段，再输出 design.md。
语言规范
描述性字段使用中文，API/dtype/字段名/代码标识符使用英语。详见 references/op-dsl.md 的语言使用规则。
design.md 必须包含：
- 算子接口与 assumptions
- Canonical DSL（扩充后的 yaml block，唯一结构化信息源）
- Capability Mapping & Gap Analysis（合并表）
- 实现边界（Device/Host/Python 职责）
- Design Review Before Handoff（12 项检查表，必须逐项填写 pass/fail 和理由）
- compile/test contract
- handoff checklist for
shmem-ops-code-gen
Section 5 不可省略。缺少此 section 的 design.md 不能交给 shmem-ops-code-gen。
结构完整性自检
输出 design.md 前，逐项检查以下必须存在的结构块：
| 结构块 | 标识 | 必须包含 |
|---|
| Canonical DSL yaml | ```yaml 代码块 | interface、semantics、topology（含 deployment/拓扑类型/链路带宽）、memory、schedule（含 core_partition/tiling/phases）、correctness（含 invariants/case_matrix）、performance（含 baseline_search/baseline_target/min_scale） |
| Capability Mapping | 六列表格 | 覆盖六个能力域：lifecycle/memory/transport/sync/compute/scheduler（各域通过 schedule.core_partition、memory、semantics 等 DSL 字段表达，sync 和 transport 不设独立 DSL section） |
| Design Review | section 5 标题 | 12 项检查表，逐项 pass/fail |
| Compile/Test Contract | contract section | cann_env、build_mode、test_command |
| Handoff Checklist | section 7 | 逐项检查 |
任一结构块缺失 → 补齐后再输出。不得以"简化版"、"benchmark 不需要"等理由省略。
Canonical DSL
必须用 fenced yaml block 输出完整 DSL，不能只用 prose 概括。DSL 是设计的唯一结构化信息源：接口、语义、拓扑、内存、调度（core_partition/tiling/phases）、正确性（invariants 含 test_method/case、case_matrix 含 stress case）、性能（含 baseline_search/baseline_target/min_scale）全部在 DSL 中定义，不在 DSL 之外另设重复的 prose 表格。
Capability Mapping & Gap Analysis
必须包含如下列：
| Requirement | SHMEM capability/source | Classification | Adaptation / Gap | Risk |
|---|
Classification 只能是 可复用、需适配、需新实现。"需新实现"行必须在 Adaptation / Gap 列写明 gap 原因、设计方案和验证方式。
映射至少覆盖六个能力域。sync 和 transport 在 DSL 中通过 schedule.core_partition.sync_between_groups / cross_pe_dataplane 表达，不设独立顶层 section。
design.md 必须包含 Capability Mapping & Gap Analysis 合并表。凡是"需新实现"，都必须在同行写明 gap 原因、设计方案、验证方式和 correctness/performance risk。
质量门禁
按 references/design-template.md section 7 的 Handoff Checklist 逐项检查。额外要求：
- DSL
correctness.case_matrix 和 performance.target_cases 含中等规模 case（集合通信 256MB 级，计算/通算融合 hidden size 上千级），或标记未满足。
- DSL
schedule.core_partition.rationale 已参考 references/core-allocation.md，或说明不适用原因。
- DSL
schedule.core_partition.groups[].role 包含精确的 AIV→数据区间映射公式（含尾块处理）、AIV→PE 映射公式（或迭代顺序）、self/remote 路径差异，不可仅为模糊描述。
- assumptions、open questions、gap 没有隐藏在模糊 prose 中。
MUST检查
全部通过 → 可交给 shmem-ops-code-gen
反模式（NEVER DO THESE）
- ❌ 未从
phase0_intake 读取 op_name 或 dtype 就进入设计
- ❌
phase0_intake 中 op_name 或 dtype 缺失时自行脑补而非报告编排器
- ❌ 把缺失的关键语义写进
assumptions 替代从 phase0_intake 读取
- ❌ 只写概念性 prose 不输出 Canonical DSL yaml block
- ❌ 在 DSL 之外另建重复的 Phase 表、Tiling 节、分核节或 Correctness Invariants 节
- ❌ 通信模块写
DataCopy 直接读写远端 PE 地址
- ❌
core_partition 写"后续优化再并行"或"Host 侧执行"
- ❌
groups.role 只写模糊描述如"所有 AIV 并行处理""每个 AIV 负责连续区间"，不给出 AIV 编号→数据范围→PE 映射的具体公式
- ❌
groups.role 不区分 self PE 本地快路径和 remote PE 远路径
- ❌
main.cpp 设计为 fork/spawn 多 PE 或承载复杂逻辑
- ❌ 性能路径全部标为后续 gap 但不说明本轮为何仍可交付
- ❌ 省略 Design Review Before Handoff（section 5）
- ❌ DSL
performance.baseline 写 "none" 或留空不记录搜索过程
- ❌ DSL
performance.baseline 未逐步排查 HCCL 清单、aclnn 清单就直接写 "metric_only"
- ❌ DSL
performance.metric 缺少 kernel_bus_bandwidth_GBps（Phase 6 达标主指标）
- ❌ DSL
performance.metric 只写 latency_us 不包含 kernel_bus_bandwidth_GBps
- ❌ DSL
performance.metric 不区分 e2e_latency_us 和 kernel_latency_us（通信算子必须双指标）
- ❌ 用户提供伪代码时粗略浏览后直接照搬实现，不逐段拆解和 SHMEM 语义映射
- ❌ 将伪代码中的"共享变量""全局数组"直接当作 SHMEM 可寻址内存
