Run any Skill in Manus with one click

Get Started

shmem-ops-dev

Stars0

Forks0

UpdatedJuly 15, 2026 at 03:01

基于 SHMEM 的通信算子与通算融合算子端到端开发编排器，串联需求→设计→代码→编译→验证→性能全流程。关键词：基于SHMEM算子开发、端到端开发、算子开发、编排、工作流、通信算子、通算融合。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

hicann

hicann/shmem

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

File Explorer

7 files

SKILL.md

readonly

SHMEM 算子端到端开发编排

Skill类型：流程导向型（Phase 0–7 工作流，含子阶段 5.5 / 6.5，子技能串行编排）

⚠ Phase 0 启动门禁（用户 @ 指定本 skill 时 — 首读本节）

触发：用户 主动 @ / 引用 .agents/skills/shmem-ops-dev/SKILL.md 时，本 skill 生效（须在对话中引用后加载，不会自动注入）。

Fresh Session 无历史记忆：须在本会话重新 AskQuestion 五项；用户 @ 引用 skill 时 MUST 上溯记录 skills_root。

@ 指定后的首步（MUST，先于其它 Read/Shell/子 skill）：

Read 本 SKILL.md（已由用户指定）

Read references/askquestion-template.md

Read references/agent-execution-contract.md

Read references/shmem-repo-resolution.md（记录 skills_root 规则；Phase 1+ 读仓内文件前定位 SHMEM_REPO）

Read references/docker-exec-contract.md（用户指定 Docker 或需 NPU 编译/运行时）

按模板 verbatim 调用 AskQuestion

在 Phase 0 intake 完成前，MUST NOT 调用其它 Read/Grep/Shell/子 skill（例外：只读环境检测；若 docker_container 已指定，探测 MUST 在容器内执行，见 docker-exec-contract.md）。

五项必问（Fresh Session — 全部 MUST，零跳过）：每项 MUST 用 AskQuestion 确认；禁止因用户消息措辞、环境已 source、或 Agent 推断默认值而跳过任一项。

# 必问项
1 CANN 路径：A 沿用当前 shell / B 默认系统 / Other 粘贴 set_env.sh 路径（或选 C 后下一条消息提供）
2 构建模式：custom-ops 独立工程 / examples in-tree
3 是否需要 Torch 接入（Phase 5.5）
4 是否需要性能采集（Phase 6）
5 未达标时是否自动进入性能优化（Phase 6.5，最多 5 轮）

用户消息含 custom-ops、CANN 路径、Torch/性能表态 均不能 替代 AskQuestion。

完整清单：references/intake-checklist.md AskQuestion 固定模板：references/askquestion-template.md SHMEM 仓定位（读 docs/examples 前）：references/shmem-repo-resolution.md Skill 总索引：references/GUIDE.md 执行契约（禁止中断/Torch/性能表）：references/agent-execution-contract.md Docker 执行（用户指定容器时全部命令进容器）：references/docker-exec-contract.md

本 skill 编排九个专职子 skill，驱动 SHMEM 通信算子与通算融合算子从需求到可交付状态。

核心原则

中文写作：所有交付的 .md 文档（design.md、review-report.md、performance_report.md 等）必须使用中文撰写。仅 API 名称、代码片段、变量名、数学公式等技术术语保留英文原文，其余描述、分析、结论一律使用中文
阶段串行（含条件性子阶段）：需求确认 → 设计 → 用例生成 → 代码生成 → 编译正确性 → 代码走读 → Torch 接入 → 性能采集 → 达标进入最终交付；未达标且 performance_auto_optim: true 进入性能优化（Phase 6.5，最多 5 轮）→ 最终交付，严格顺序执行
子技能执行：每个阶段 MUST 调用对应子 skill，不得自行实现
阶段门控：前一阶段MUST检查全部通过后才进入下一阶段
设计驱动编码：代码生成依赖设计文档中的 Canonical DSL 和六类模块设计
先 correctness 再 performance：功能或正确性未通过时，不做性能优化
性能优化上限 5 轮：每轮记录假设、改动、正确性复测和性能结果
结果可视化：关键结果在聊天界面展示，不要仅输出路径。Phase 6/6.5 MUST 自动输出性能表（见 perf-chat-output-spec.md），不得等用户追问
目录结构强制：所有 .md 文档归入 docs/，所有 .cpp/.h 源文件归入 src/，测试脚本归入 scripts/。不得扁平散放
不静默修改核心库：只有 gap analysis 明确授权时才允许改 SHMEM 核心能力

可用子 Skill 清单

Skill	路径	职责
`shmem-ops-design`	`shmem-ops-design/SKILL.md`	将需求转化为 design.md（通信算子 / 通算融合，Canonical DSL + 契约）
`shmem-ops-testcase-gen`	`shmem-ops-testcase-gen/SKILL.md`	生成 case matrix、golden/checker、测试脚本
`shmem-ops-code-gen`	`shmem-ops-code-gen/SKILL.md`	根据 design.md 生成通信算子或通算融合算子代码、CMake、README
`shmem-ops-compile-debug`	`shmem-ops-compile-debug/SKILL.md`	编译、运行、失败分类和调试
`shmem-ops-code-review`	`shmem-ops-code-review/SKILL.md`	实现与设计一致性走读
`shmem-ops-correctness-eval`	`shmem-ops-correctness-eval/SKILL.md`	正确性契约验证和报告
`shmem-ops-torch-bind`	`shmem-ops-torch-bind/SKILL.md`	封装为 PyTorch CustomClass，生成 Python 测试并验证
`shmem-ops-performance-eval`	`shmem-ops-performance-eval/SKILL.md`	性能采集、baseline 对比、瓶颈分析
`shmem-ops-performance-optim`	`shmem-ops-performance-optim/SKILL.md`	性能优化迭代（最多 5 轮）

工作流总览

Phase 0       Phase 1       Phase 2         Phase 3        Phase 4            Phase 5       Phase 5.5       Phase 6
需求环境确认 ──▶ 设计文档 ──▶ 用例生成 ──▶ 代码生成 ──▶ 正确性验证 ──▶ 代码走读 ──▶ Torch 接入 ──▶ 性能采集
—              design     testcase-gen   code-gen    correctness-eval  code-review  torch-bind    performance-eval
                                                  │
         ┌────────────────────────────────────────┤
         │ 达标 ─────────────────────────────────▶ Phase 7 交付
         │ 未达标 + performance_auto_optim:false ─▶ Phase 7（仅报告差距）
         └ 未达标 + performance_auto_optim:true ─▶ Phase 6.5 性能优化（5 轮）
                                                        │
                                                        ├── torch_required:false ──▶ Phase 7 交付
                                                        └── torch_required:true  ──▶ Torch 回归门禁 ──▶ Phase 7 交付

输入: 算子需求 + 环境                            输出: 可交付算子 + Torch 扩展 + 测试 + 性能报告

Phase 6 仅在 meta.performance_required: true 时执行；Phase 6.5 仅在 未达标 且 meta.performance_auto_optim: true 时由编排器自动进入。

反模式清单（NEVER DO THESE）

Phase 0

❌ Fresh Session 因用户消息含 custom-ops/CANN 路径/Torch/性能表述而跳过五项 AskQuestion 任一项
❌ Fresh Session 未完成 Phase 0 五项 AskQuestion 就调用 Read/Grep/Shell 或子 skill
❌ 未 Read askquestion-template.md 就自行构造 AskQuestion（导致 CANN 出现不可输入的「C. 自定义」）
❌ ASCEND_HOME_PATH 未设置时静默 source /usr/local/Ascend/ascend-toolkit/set_env.sh（MUST 先询问用户选默认或自定义 CANN 路径，见 cann-env-resolution.md）
❌ 用户未明确要求时默认执行 Phase 5.5（Torch）、Phase 6（性能采集）或 Phase 6.5（性能优化）
❌ 用户已指定 Docker 容器，却在宿主机 shell 执行 custom-ops-entrypoints.md §1/§2/perf/torch_test_*.py（见 docker-exec-contract.md）
❌ 同一任务混用 docker exec 与宿主机裸命令（探测、编译、运行 MUST 统一在容器内）

Phase 1

❌ 跳过设计阶段直接写代码

Phase 2

❌ 跳过用例生成，直接进入代码生成

Phase 3

❌ 自行实现算子代码，不调用子 skill
❌ 用户未明确要求 in-tree 时，将算子创建在 examples/ 下（默认 custom-ops/<op_name>/）
❌ 暴露裸 cmake -S ... -B ... 给用户/Agent（MUST 使用封装脚本，见 build-test.md §2.4）
❌ custom-ops 新算子调用 aclshmemi_* 或使用已 deprecated 的 aclshmemx_barrier_all_vec（见 internal-api-boundary.md）

Phase 4

❌ correctness 失败时做性能优化
❌ 只手动设置 LD_LIBRARY_PATH=${PROJECT_ROOT}/build/lib，不 source ${SHMEM_REPO}/install/set_env.sh`（缺 bootstrap 插件和 driver 库，易出现 aclError / golden 全 FAIL）
❌ scripts/run.sh 写死 IPPORT=tcp://127.0.0.1:27010 和 SHMEM_UID_SESSION_ID=127.0.0.1:8899 且不检测端口占用（典型：address in use → 输出全 0 假 FAIL）
❌ 输出 bin 全 0 时不查 /root/shmem/log 就直接改 kernel（应先排查 shmem init / 端口 / 环境）
❌ custom-ops-entrypoints.md §0 + SHMEM build -examples 不带 -examples 后执行 make <op_name>（CMake 无该 executable target）
❌ 反复全量 build -examples 做增量调试（每次清空 build/ 和 install/）
❌ in_tree_example 模式下使用 custom-ops/<op>/scripts/run_case_matrix.py（MUST 路由到 examples/<op>/scripts/run.sh 或 example 实际测试入口）

Phase 5.5

❌ torch_required:true 时未自动生成全部算子 torch_test_*.py 或未 8PE 验证即进入 Phase 6
❌ 使用无范围约束的 pkill -f shmem 清理进程（MUST 使用 pgrep -f 'build/bin/<op_name>' 精确匹配；对外部进程先输出证据请求授权）

Phase 6

❌ 有可用 baseline（HCCL/aclnn）但不接入
❌ 编造硬件测试或 profiler 结果
❌ 性能脚本跑完后不在聊天自动输出结果，等用户说「输出性能」
❌ Phase 6 只报时延不报带宽对比表（MUST 输出带宽表+时延表）

Phase 6.5

❌ 将 block_dim=1 补齐到设计并发当作性能优化轮次
❌ 未经用户明确要求，性能优化超过 5 轮
❌ Phase 6.5 中 optim 自行修改代码或 design.md —— MUST 委托对应子 skill（design/code-gen）

通用

❌ 修改 SHMEM 核心库却无 gap analysis 授权
❌ 引用不存在的子 skill
❌ 遇编译/perf/baseline 失败自行停止，等用户说「继续」（MUST 自主修复重试，见 agent-execution-contract.md §1）

Phase 0：需求与环境确认

调用 Skill：—

目标：确认算子开发所需的最小信息集，包括开发环境和算子需求

Fresh Session 调用 AskQuestion 前 MUST Read：references/askquestion-template.md，禁止自行编造表单（尤其 CANN 第三固定选项）。

详细清单：references/intake-checklist.md（Agent MUST 在新会话首读）

启动门禁（Hard Gate — 新会话 MUST 遵守）

在 Phase 0 intake 完成前，Agent MUST NOT 调用任何工具，例外仅为 Step 0.1 所需的只读环境检测（echo $ASCEND_HOME_PATH、echo $CONDA_DEFAULT_ENV、which bisheng 等），且禁止在此阶段 Read 源码、Grep 代码库、Shell 编译/运行、或调用任何子 skill。

Fresh Session 五项必问（全部 MUST，零跳过） — MUST 用 AskQuestion 确认全部 5 项；用户消息或环境检测不得替代任何一项：

#	必问项	AskQuestion 建议标题	选项
1	CANN 路径	CANN 环境来源？	A. 沿用当前 shell / B. 默认系统安装；自定义见 checklist「CANN #1 提问方式」（Other 填路径或选 C 后下一条消息粘贴）
2	构建模式	算子放在哪个目录？	A. `custom-ops` 独立工程 / B. `examples` in-tree
3	Torch 接入	是否需要 PyTorch 接入（Phase 5.5）？	需要 / 不需要
4	性能采集	是否需要性能采集（Phase 6）？	需要 / 不需要
5	自动性能优化	Phase 6 未达标时是否自动进入 Phase 6.5？	是 / 否（`#4` 为否时本题无效）

五项全部经 AskQuestion 获用户选择后，方可进入 Phase 1 及后续工具调用。

Step 0.1：环境确认（MUST 在任何开发动作之前完成）

开发环境是所有后续阶段的前置依赖，必须首先确认。

CANN 环境

详细流程见 shmem-ops-compile-debug/references/cann-env-resolution.md。

自动检测流程（检测仅用于 AskQuestion 选项展示，不能代替 AskQuestion #1）：

检查 ASCEND_HOME_PATH 是否已设置，且 which bisheng 可用
Fresh Session：MUST AskQuestion #1（三项：沿用当前 / 默认系统 / 自定义）——禁止因 shell 已 source、消息含路径、或 Docker 有默认 CANN 而跳过
续聊同一会话：用户 已在本会话 通过 AskQuestion 确认 #1 且已记录 CANN_SET_ENV 时，无需重复 #1
若未设置或未 source：仍 MUST AskQuestion #1，禁止静默 source /usr/local/Ascend/...

MUST 询问时的选项（AskQuestion；自定义路径禁止假选项 C，见 checklist）：

选项	行为
A. 沿用当前 shell	展示 `ASCEND_HOME_PATH`，用户确认
B. 默认系统安装	展示候选路径，用户确认后才 `source`
Other（推荐）	用户在 Other 输入框粘贴 `set_env.sh` 绝对路径；题干 MUST 说明并给样例
C. 自定义（两步）	选 C 后 Agent MUST 等待用户下一条消息粘贴路径，收到前禁止 Phase 1

默认路径候选（探测后展示，不自动采用）：

/usr/local/Ascend/ascend-toolkit/set_env.sh
/usr/local/Ascend/cann/set_env.sh
$HOME/Ascend/cann/set_env.sh

自定义路径样例（询问时给出）：

/home/<用户名>/CANN/8.5.0/ascend-toolkit/set_env.sh
/home/<用户名>/CANN/9.0.beta/ascend-toolkit/set_env.sh

用户确认后记录 CANN_SET_ENV，并写入 design.md compile.cann_set_env（Phase 1 固化）。

激活方式（每个需编译/运行的 Shell 会话，含 docker exec 内）：

source "${CANN_SET_ENV}"    # Phase 0 AskQuestion #1 确认的路径

在每个需要编译或运行算子的 Shell 会话中，都必须先执行此激活命令。docker exec 内同样 MUST 使用已确认的 CANN_SET_ENV，不得硬编码未确认路径。

Docker（用户指定容器名时 — Hard Gate）：

记录 phase0_intake.docker_container（见 docker-exec-contract.md）
所有 build/run/perf/Torch/进程清理 MUST docker exec <container> bash -lc '...'，禁止宿主机裸跑
文件编辑可走工作区挂载；验证必须在容器内复现

Conda / Python 环境

自动检测流程：

检查当前是否已激活 conda 环境（echo $CONDA_DEFAULT_ENV）
若已激活（值非 base 且非空）：直接使用当前环境，无需询问用户
若未激活或为 base：MUST 向用户询问要使用的 conda 环境名称

激活方式：

conda activate <env_name>

在每个需要编译或运行算子的 Shell 会话中，都必须先激活 conda 环境。

SHMEM 仓库

路径规范：Skill 可与 SHMEM 仓分离部署。读仓内 docs/、examples/ 前见 shmem-repo-resolution.md。

自动检测流程（按顺序，命中即停）：

检查当前工作目录下是否同时存在 include/ 和 src/（如 shmem 根目录）→ 将当前目录作为 SHMEM_REPO
否则检查是否存在 shmem/ 子目录（含 include/、src/）→ 将 shmem/ 作为 SHMEM_REPO
以上均不满足 → 自动 clone：git clone https://gitcode.com/cann/shmem.git 到当前目录下，将 shmem/ 作为 SHMEM_REPO；clone 失败则 MUST 向用户确认后再重试
clone 完成后 MUST 执行 cd ${SHMEM_REPO} && bash scripts/build.sh -examples 完成首次构建

硬门禁：SHMEM 仓库不存在（无 include/ + src/）且 clone 失败时，MUST STOP，禁止进入 Phase 1。

PyTorch / torch_npu 依赖（Phase 5.5 前置）

在 conda 环境激活后执行：

python -c "import torch; import torch_npu; print(torch.__version__)"

若成功：记录 torch 和 torch_npu 版本，无需询问用户
若失败：MUST 向用户询问是否安装或切换到含 torch/torch_npu 的环境

SHMEM 构建产物

自动检测流程：

检查 ${SHMEM_REPO}/install/set_env.sh 是否存在
若存在：记录为 SHMEM 安装路径，编译/运行前 MUST source install/set_env.sh
若不存在：提示用户先执行 SHMEM 根目录 bash scripts/build.sh -examples（见 custom-ops-entrypoints.md §0），或询问已安装路径

in-tree example 编译约束（MUST 遵守）：

场景	正确命令	错误做法
首次编译算子（custom-ops）	custom-ops-entrypoints.md §1 编译	裸 `cmake -S custom-ops/<op>/ ...`
运行正确性（custom-ops）	custom-ops-entrypoints.md §2 或 `bash custom-ops/scripts/run.sh`	仅 `cd custom-ops/<op> && bash scripts/run.sh` 作为文档首选
性能采集（custom-ops）	`perf-workflow.md` §1 阶段 B	与 HCCL 同 shell 混跑
baseline 采集（custom-ops）	`perf-workflow.md` §1 阶段 A	在 SHMEM 之后同会话执行
性能对比（custom-ops）	`perf-workflow.md` §1 阶段 C	同会话内嵌启动 HCCL+SHMEM
分阶段采集	perf-workflow.md §1	一体混跑 HCCL+SHMEM
case matrix（custom-ops）	custom-ops-entrypoints.md §3 case matrix	裸 `python3 custom-ops/<op>/scripts/run_case_matrix.py`
Torch 编译（custom-ops）	custom-ops-entrypoints.md §4 Torch 编译	裸 cmake torch_binding
首次全量构建 SHMEM（in-tree）	`bash scripts/build.sh -examples`	不带 `-examples`
增量编译单 example	`cmake --build build --target <op_name> -j`	反复全量 build -examples
运行/测试前	`source install/set_env.sh`（SHMEM 原生）	只手动设 `LD_LIBRARY_PATH=build/lib`

SHMEM install 环境脚本会设置 SHMEM_HOME_PATH，并把以下路径加入 LD_LIBRARY_PATH：

$SHMEM_HOME_PATH/shmem/lib（含 libshmem.so 和 bootstrap 插件）
/usr/local/Ascend/driver/lib64/driver/
可选：$SHMEM_HOME_PATH/shmem/torch_binding/kernels

Agent 在容器/远程环境 MUST 自行执行编译和测试，不得只输出命令让用户代跑。

custom-ops（默认） 完整环境链见 custom-ops-entrypoints.md 与 perf-workflow.md。

in-tree example（仅用户明确要求时）：

source ${CANN_SET_ENV}
source ${SHMEM_REPO}/install/set_env.sh
cd ${SHMEM_REPO}/examples/<op_name> && bash scripts/run.sh <pe_size>

算子 scripts/run.sh 生成时 MUST 内联 env-setup.snippet.md 中的 setup_shmem_runtime_env（或见 test-structure-template.md §4 等价内联），在激活 SHMEM install 环境之后追加 build/lib 与 ${ASCEND_HOME_PATH}/lib64。禁止只用 build/lib 替代 install/set_env.sh；禁止从 skill 目录 source 任何脚本。

编译器（可选预检）

which bisheng

缺失时在 Phase 4 由 shmem-ops-compile-debug 再次检查并询问用户。

环境确认检查点

CANN 路径已确定（ASCEND_HOME_PATH 已设或用户已选择默认/自定义 CANN_SET_ENV）
source ${CANN_SET_ENV} 可正常执行且 bisheng 可用
Conda 环境已确定（自动检测或用户提供）
conda activate <env_name> 可正常执行
SHMEM 仓库路径已确定（自动检测或用户提供）
torch 和 torch_npu 可导入（或标记待 Phase 5.5 前补齐）
SHMEM ${SHMEM_REPO}/install/set_env.sh 存在（或标记待构建）

Step 0.2：算子需求收集

确认本次任务入口和算子需求：

输入形态	处理方式
只有自然语言需求	收集最小需求后进入 Phase 1
有伪代码或异构参考实现	进入 Phase 1，设计阶段归一化
已有 design.md	直接进入 Phase 1 质量门禁
用户说"继续开发"	按中断恢复矩阵从最早未完成阶段恢复

最小确认项：

op_name（可用作目录名和符号前缀）
功能语义（local compute、communication、final result）
目标 SoC 和 dtype

Step 0.2.1：构建模式确认（MUST — AskQuestion #2，不可跳过）

Fresh Session MUST 用 AskQuestion #2 确认构建模式，禁止因用户消息含 custom-ops/examples/独立编译/in-tree 而跳过。

确认项	选项 A	选项 B
构建模式	`independent_project` → `custom-ops/<op_name>/`	`in_tree_example` → `examples/<op_name>/`
编译入口	custom-ops-entrypoints.md §1 编译	同文件 §0 + SHMEM build -examples + 增量 target
运行/正确性	custom-ops-entrypoints.md §2 或 `custom-ops/scripts/run.sh`	`cd examples/<op> && bash scripts/run.sh`
case matrix	custom-ops-entrypoints.md §3 case matrix	—
性能	perf-workflow.md §1 阶段 B	—
Torch 编译	custom-ops-entrypoints.md §4 Torch 编译	`bash scripts/build.sh -examples -python_example`

记录到 design.md compile.build_mode 与 meta.op_root（仅在用户 AskQuestion 选择后写入，不得 Agent 预设）：

meta:
  build_mode: independent_project   # 默认；仅用户明确要求时改为 in_tree_example
  op_root: custom-ops/<op_name>     # 或 examples/<op_name>

Step 0.3：Torch 与性能确认（MUST — AskQuestion #3/#4/#5，不可跳过）

Fresh Session MUST 用 AskQuestion #3、#4、#5 确认 Torch 与性能，禁止因用户消息含「全流程」「端到端」「要/不要 Torch/性能」等措辞而跳过或擅自推断。

确认项	对应阶段	用户选择「需要/是」	用户选择「不需要/否」
Torch 接入（AskQuestion #3）	Phase 5.5	`meta.torch_required: true`	`meta.torch_required: false`，跳过 Phase 5.5
性能采集（AskQuestion #4）	Phase 6	`meta.performance_required: true`	`meta.performance_required: false`，跳过 Phase 6
未达标自动优化（AskQuestion #5）	Phase 6.5	`meta.performance_auto_optim: true`	`meta.performance_auto_optim: false`，未达标仅报告差距，不改 kernel

判定规则：

Fresh Session：MUST AskQuestion #3、#4、#5，无例外
AskQuestion #4 选「不需要」时，#5 仍须提问；若用户选「是」则 MUST 提示「须先开启性能采集」并视为 performance_auto_optim: false，或请用户改选 #4
「端到端」「全流程」不得自动推断 Torch=true、性能=true、自动优化=true
续聊同一会话：已在本会话 AskQuestion 确认过的项，无需重复

记录到 design.md meta（Phase 1 写入或 Phase 0 预填）：

meta:
  torch_required: true|false           # 默认不得擅自设为 true
  performance_required: true|false     # Phase 6；默认不得擅自设为 true
  performance_auto_optim: true|false   # Phase 6.5 自动分支；仅 performance_required:true 时生效

MUST检查

全部通过 → 进入 Phase 1

Phase 1：设计文档

调用 Skill：shmem-ops-design

执行内容

0. 将 phase0_intake 关键字段预填到 docs/design.md 的 meta（若 design.md 尚不存在则创建骨架）：
   - op_name → meta.op_name
   - build_mode → meta.build_mode
   - torch_required → meta.torch_required
   - performance_required → meta.performance_required
   - performance_auto_optim → meta.performance_auto_optim
   - shmem_repo → meta.shmem_repo
   - docker_container → meta.docker_container
   预填后调用 shmem-ops-design 补全其余设计内容，design skill 打开 design.md 即可直接读取已确认值
1. 如果无 design.md（完整），使用 shmem-ops-design 生成
2. 如果已有 design.md，读取并检查质量门禁
3. 设计文档必须包含：Canonical DSL、capability mapping、gap analysis、
   correctness invariants、compile/test/perf contract

MUST检查

Phase 1 的 design.md 门禁必须在进入 Phase 2 前完成。门禁结果中有任何 FAIL 或缺失 section，必须先修订 design.md 再继续，不允许带缺陷进入后续阶段。

全部通过 → 进入 Phase 2

Phase 2：测试用例生成

调用 Skill：shmem-ops-testcase-gen

执行内容

1. 读取 design.md 的 correctness contract 和 invariants
2. 生成 case matrix（smoke/contract/tail/repeats/gap/medium-scale）
3. 生成 gen_data.py、check_result.py、`scripts/run.sh`
4. 生成 golden 文件

MUST检查

case matrix 覆盖 XS/S/M/L 四档规模（来自 testcase-gen）
总 case 数 ≥ 20（来自 testcase-gen）
gen_data.py 可独立运行
check_result.py 返回明确退出码
golden 逻辑与 design.md 语义一致（来自 testcase-gen）
包含中等规模 case（集合通信≥256MB）
scripts/run.sh 内联 setup_shmem_runtime_env（来自 testcase-gen）
scripts/run.sh 通过 setup_shmem_dynamic_endpoints 避免固定端口（来自 testcase-gen）
scripts/run.sh 支持多 PE 启动（来自 testcase-gen）

全部通过 → 进入 Phase 3

Phase 3：代码生成

调用 Skill：shmem-ops-code-gen

执行内容

1. 读取通过门禁的 design.md
2. 选择模板和参考 example
3. 渐进式代码生成（lifecycle → transport → compute → scheduler）
4. 生成 README.md
5. 调用 shmem-ops-compile-debug 编译 + 2PE smoke（code-gen 步骤 5）：
   - compile-debug 执行构建并诊断；code-gen 根据诊断结果修复代码
   - 循环直到编译通过且 2PE smoke 运行通过

Phase 3 产出编译通过 + 2PE smoke PASS 的二进制。全量正确性验证在 Phase 4。

MUST检查

代码按 design 的 phase/transport/sync/partition 实现
目录结构符合规范：docs/ 含全部 .md、src/ 含全部 .cpp/.h、scripts/ 含全部测试脚本
main.cpp 不含复杂逻辑
README.md 覆盖编译、运行、校验入口
e2e_latency_us 口径包含输入到对称堆的拷贝（未预拷贝缩水）
编译成功（或记录环境阻塞；完整正确性在 Phase 4 验证）
同时 MUST 满足 shmem-ops-code-gen 的全部 P0 项（完整清单见 code-gen SKILL.md §MUST检查），P0 任一 FAIL 则禁止进入 Phase 4

全部通过 → 进入 Phase 4

Phase 4：正确性验证

调用 Skill：shmem-ops-correctness-eval

编译已在 Phase 3 完成（二进制 + 2PE smoke PASS）。Phase 4 直接执行全量 case matrix。

执行内容

1. 使用 shmem-ops-correctness-eval 执行全量 case matrix：
   - independent_project（custom-ops）：
     python3 ${SHMEM_REPO}/custom-ops/<op>/scripts/run_case_matrix.py
   - in_tree_example（examples）：
     cd ${SHMEM_REPO}/examples/<op> && bash scripts/run.sh <pe_size>
     （或 examples/<op>/scripts/run_case_matrix.py，若 testcase-gen 为其生成）
2. 失败分类：design bug → Phase 1；code bug → Phase 3（code-gen 局部修复 → compile-debug 增量编译 + 2PE smoke → 回到 Phase 4 全量复测，不重走 Phase 3 全流程）；test bug → Phase 2（修正 testcase-gen 产出后重新走 Phase 4）；env → 记录阻塞

MUST检查

编译成功
命令路径与 build_mode 匹配（independent_project → custom-ops/<op>/；in_tree_example → examples/<op>/，禁止 in-tree 模式使用 custom-ops 路径）
全部 case 通过（或分类标记未通过原因）
中等规模 case 已验证（或标记未满足）
invariants 已验证

全部通过 → 进入 Phase 5

Phase 5：实现与设计一致性走读

调用 Skill：shmem-ops-code-review（mode: interim）

执行内容

1. 读取 docs/correctness_report.md（全量 case 结果，code-review Section 2 的数据来源）
2. 对比 design.md 和实现代码
3. 逐项检查：CMake target、block_dim、transport API、tile/chunk/tail、offset、性能路径
4. 生成 docs/review-report.md（interim 模式：Section 1–2 完整，Section 3 待补齐）

MUST检查

interim 走读全部 PASS（P0 无 FAIL）
review-report.md Section 3 标注「待补齐」，无编造性能数据
无固定单核 launch（除非 design 明确要求）
无未接入的高性能 kernel

全部通过 → 判断 Phase 5.5 是否执行（见下）

torch_required: true 时：MUST 在本 Phase 结束后立即进入 Phase 5.5，为本批次全部算子生成 Torch 绑定与 torch_test_*.py，不得等待用户再次确认或说「继续」。

Phase 5.5：Torch 接入与验证（条件性）

用户在 Phase 0 MUST 通过 AskQuestion #3 确认 Torch 接入；Fresh Session 禁止跳过 #3，不得默认执行。

是否执行：读取 design.md DSL meta.torch_required：

值	动作
`true`（用户已确认需要）	MUST 执行本 Phase
`false`	跳过本 Phase，在交付摘要中记录跳过原因；若 `performance_required: true` 则进入 Phase 6，否则进入 Phase 7
未设置 / 未确认	停止，回到 Phase 0 Step 0.3 询问用户

设计阶段写入 meta.torch_required: true|false。

环境预检（`torch_required: true` 时 MUST 在调用 torch-bind 前执行）

python -c "import torch; import torch_npu; print(torch.__version__)" — 确认可导入
pip show shmem — 确认 SHMEM whl 已安装（Phase 0 检查过但当前环境可能已切换）
残留进程清理：MUST 以精确匹配方式清理本任务启动的进程（如 pgrep -f 'build/bin/<op_name>' 获取 PID 后 kill，或 pkill -f 'build/bin/<op_name>'）；禁止使用无范围约束的 pkill -f shmem（会误杀无关 SHMEM 作业、测试、服务及自身脚本）。对外部残留进程只输出 PID/端口证据并请求用户授权后再清理

任一失败 → 修复环境后重试，禁止跳过预检直接进入 torch-bind。

调用 Skill：shmem-ops-torch-bind（仅 torch_required: true 时）

执行内容

1. 读取 design.md 接口契约和算子源码
2. 生成 C++ Torch CustomClassHolder 封装代码（torch_bind_<op_name>.cpp）
3. 集成 CMake（链接 kernel target + torch + torch_npu）
4. 生成 Python 多 PE 测试脚本（torch_test_<op_name>.py）
5. 编译 Torch 扩展 .so（custom-ops → `shmem_custom_ops_torch.so` / in-tree → `aclshmem_torch.so`）
6. 运行 2-PE smoke + 8-PE 全量测试

MUST检查

torch_bind_<op_name>.cpp 包含 CustomClassHolder 子类和 REGISTER_SHMEM_OPS_CLASS 注册
compute() 包含 TORCH_CHECK（dtype、device、shape）
dtype dispatch 覆盖 design.md 声明的全部 dtype
Manager 类已存在（含 attr_init / finalize / malloc_tensor / malloc_like / free_tensor）
Torch .so 编译成功（产物名取决于 build_mode：custom-ops → shmem_custom_ops_torch.so，in-tree → aclshmem_torch.so）
torch_test_<op_name>.py 包含 fixed seed gen_data + multi-PE worker + golden 精度验证
Python 测试 2-PE smoke 通过（torch_required: true 时）
Python 测试 8-PE 通过（torch_required: true 时）
或 torch_required: false 且已记录跳过原因

全部通过（或已跳过）→ 进入 Phase 6

Phase 6：性能采集

是否执行：读取 design.md DSL meta.performance_required：

值	动作
`true`（用户已确认需要）	MUST 执行本 Phase
`false`	跳过本 Phase 及 Phase 6.5（无论 `performance_auto_optim`），在交付摘要中标注「未做性能验证」，直接进入 Phase 7
未设置 / 未确认	停止，回到 Phase 0 Step 0.3 询问用户

调用 Skill：shmem-ops-performance-eval（仅 performance_required: true 时）

执行内容

1. 读取 perf contract
2. 调用 `shmem-ops-code-gen` 为算子添加性能打点代码（`main.cpp` 添加 `--perf` flag + timing loop + `[PERF]` 输出；kernel 添加 `SHMEMI_PROF_START/END` 宏对；生成 `scripts/perf.sh`）
3. 选择 baseline（HCCL/aclnn/metric-only）；AllToAllV 无 aclnn 头文件时回退 HcclAlltoAllV
4. 调用 `shmem-ops-code-gen` 按选定 baseline API 生成 baseline C++ 代码（`baseline/src/<op>_baseline.cpp` + `baseline/CMakeLists.txt` + `baseline/scripts/run_baseline.sh`）；若 `metric_only` 则跳过 baseline 目录；然后调用 `shmem-ops-compile-debug` 编译（算子 + baseline）；最后调用 `shmem-ops-performance-eval` 运行采集 `[BASELINE_PERF]`
5. **分阶段采集**：[perf-workflow.md §1](../shmem-ops-performance-eval/references/perf-workflow.md)（A baseline → B SHMEM → C 离线）；**NEVER 同会话混跑**
6. 瓶颈分析
7. 聊天 **自动输出**：
   - **带宽表 + 时延表**（S 档 + L 档）
   - **禁止**仅贴单行 `[PERF]` 或只报时延
8. 达标判定：有 baseline 时默认 ≥ baseline **80%**；无 baseline 时通信算子带宽利用率 ≥ 20%

参考：baseline-compare-workflow.md、perf-chat-output-spec.md

MUST检查

baseline 已选择或记录搜索过程
baseline C++ 已实现且 [BASELINE_PERF] 已采集
性能数据已采集（S 档 + L 档）
聊天已输出 带宽表 + 时延表（含 kernel_bus_bandwidth_GBps、比值、目标、达标）
瓶颈已分析
docs/performance_report.md §3.5 对比表已填写
有 baseline 时：达标（≥ baseline 80%）→ Phase 7；未达标且 performance_auto_optim: true → 立即 Phase 6.5
无 baseline 时：满足指标 → Phase 7；不满足且 performance_auto_optim: true → 立即进入 Phase 6.5
未达标且 performance_auto_optim: false → 输出差距表后进入 Phase 7，不改 kernel

达标 → 进入 Phase 7（交付）；未达标且 performance_auto_optim: true → 立即进入性能优化

Phase 6.5：性能优化（最多 5 轮）

前置：meta.performance_required: true 且 meta.performance_auto_optim: true 且 Phase 6 未达标（≥ baseline 80% 或带宽利用率 ≥ 20%）。

调用 Skill：shmem-ops-performance-optim

执行内容

每轮（Round 1~5，进入后 MUST 跑满 5 轮）：
1. 瓶颈定位（OptimStep 1）
2. 基线锁定（OptimStep 2）
3. 输出修改意见（OptimStep 3），分类为设计级或代码级
4. 委托执行链：
   a. 设计级改动 → shmem-ops-design 修订 design.md（跳过 testcase-gen）
   b. 代码级改动 → shmem-ops-code-gen 修改代码
   c. shmem-ops-compile-debug 编译（compile-debug 只诊断不改代码，失败回 code-gen）
   d. shmem-ops-correctness-eval 正确性复测
5. 性能验证（OptimStep 4 → shmem-ops-performance-eval，固定 Round0 平台区 case）
6. 聊天自动输出：本轮 Δ% + 累计总览（perf-chat-output-spec §3）
7. 决策 keep / revert（OptimStep 5）

停止条件

已进入 Phase 6.5：已完成 5 轮（即使中途达标也 MUST 跑满 5 轮）
Phase 6 已达标且用户未要求优化：跳过 Phase 6.5
5 轮后仍未达标 → 输出差距和瓶颈，进入 Phase 7 交付
用户明确要求继续优化 → 可超过 5 轮

聊天输出（Hard Gate）

每轮结束：Round N 最优 vs R0 / vs 上轮 / vs baseline（kernel_bus_bandwidth_GBps Δ%）
5 轮结束：最终对比表（perf-chat-output-spec §4）
NEVER 只在最后一轮才报性能变化

完成 → 进入 Torch 回归门禁（如适用）→ Phase 7

Torch 回归门禁（Phase 6.5 → Phase 7 之间）

前置：meta.torch_required: true 且 Phase 5.5 已完成且 Phase 6.5 已完成（kernel 代码可能已被修改）。

调用 Skill：shmem-ops-torch-bind

执行内容：

重新编译 Torch 扩展（kernel 签名、buffer 大小、block_dim 可能已变化）
运行 torch_test_<op_name>.py 8PE 全量测试
若 Torch 回归 FAIL → 回 shmem-ops-code-gen 修复 Torch 绑定代码后重新编译测试，直到 PASS

MUST 检查：

Torch .so 重新编译成功（shmem_custom_ops_torch.so / aclshmem_torch.so）
torch_test_<op_name>.py 8PE 回归通过
或 torch_required: false 且已记录跳过原因

Phase 7：最终交付

调用 Skill：—

执行内容

输出最终交付摘要，并调用 shmem-ops-code-review（mode: final）更新 docs/review-report.md 的 Section 3/5/6。

交付摘要必须包含：

算子名称和 docs/design.md 路径
目录结构检查（docs/ 包含全部 .md、src/ 包含全部 .cpp/.h、scripts/ 包含全部测试脚本）
修改文件列表
编译命令（完整可复现）
测试命令（完整可复现）
正确性验证结果表
Torch 接入结果（Torch .so 路径、编译命令、torch_test_<op_name>.py 运行结果；若经过 Phase 6.5 则为优化后回归结果）
性能采集结果：S 档 + L 档 kernel_bus_bandwidth_GBps 对比（Phase 6 自动输出）
优化轮次摘要（如有 Phase 6.5）：每轮 kernel_bus_bandwidth_GBps Δ% 累计总览 + 最终对比表
未完成项、未验证项、环境阻塞或风险

不要只输出路径；关键结果必须在回复中摘要展示。

阶段间数据流

Phase 0 输出                Phase 1 输入
  op_name、env 确认   ────▶   需求语义、SoC、dtype

Phase 1 输出                Phase 2 输入
  design.md (完整)    ────▶   correctness contract、invariants

Phase 2 输出                Phase 3 输入           Phase 4 输入
  case matrix         ────────────────────────────▶   case matrix
  gen_data/checker    ────▶   模板参考
                                design.md      ────▶   design.md

Phase 3 输出                Phase 4 输入
  算子代码、CMake     ────▶   compile contract
  README.md                    test contract

Phase 4 输出                Phase 5 输入
  编译通过            ────▶   design.md vs 实现代码
  correctness PASS           docs/correctness_report.md

Phase 5 输出                Phase 5.5 输入
  走读 PASS           ────▶   design.md interface
                               算子源码

Phase 5.5 输出              Phase 6 输入
  Torch .so           ────▶   perf contract
  torch_test PASS              baseline 策略

Phase 6 输出                Phase 6.5/7 输入
  性能报告            ────▶   达标判断
  瓶颈分析                     优化或交付

状态跟踪表

Phase	前置条件	调用 Skill	关键产出物
0	无	—	op_name + 环境确认
1	Phase 0	`shmem-ops-design`	design.md（Canonical DSL + 契约）
2	Phase 1	`shmem-ops-testcase-gen`	case matrix + scripts
3	Phase 2	`shmem-ops-code-gen`	算子代码 + README
4	Phase 3	`shmem-ops-correctness-eval`	correctness PASS
5	Phase 4	`shmem-ops-code-review`（interim）	`docs/review-report.md`（阶段性）
5.5	Phase 5 + `torch_required: true`	`shmem-ops-torch-bind`	Torch .so + `torch_test_<op_name>.py`
5.5（跳过）	Phase 5 + `torch_required: false`	—	跳过记录
6	Phase 5.5 完成或跳过 + `performance_required: true`	`shmem-ops-performance-eval`	性能报告
6（跳过）	`performance_required: false`	—	跳过记录
6.5	Phase 6 未达标 + `performance_required: true` + `performance_auto_optim: true`	`shmem-ops-performance-optim`（分析）+ `shmem-ops-design` 或 `shmem-ops-code-gen`（改动）+ `shmem-ops-compile-debug` + `shmem-ops-correctness-eval` + `shmem-ops-performance-eval`	优化轮次记录
Torch 回归	Phase 6.5 完成 + `torch_required: true`	`shmem-ops-torch-bind`	Torch 回归 PASS（优化后）
7	Phase 6 达标或 6.5 完成或 Torch 回归完成	—	最终交付摘要

错误恢复

中断恢复矩阵

检测条件	判定阶段	恢复动作
无 design.md	Phase 1 未完成	使用 `shmem-ops-design` 生成
design.md 缺 Canonical DSL	Phase 1 未完成	修订设计并重跑门禁
无测试脚本	Phase 2 未完成	使用 `shmem-ops-testcase-gen`
有 design 无实现代码	Phase 3 未完成	使用 `shmem-ops-code-gen`
代码存在但编译失败	Phase 4 未完成	从编译调试恢复
编译通过但 correctness 未过	Phase 4 未完成	从正确性调试恢复
correctness 通过但无走读	Phase 5 未完成	执行 `shmem-ops-code-review`（interim）
走读通过但无 Torch 绑定	Phase 5.5 未完成（且 `torch_required: true`）	执行 `shmem-ops-torch-bind`
`torch_required: false` 已记录跳过	Phase 5.5 已跳过	若 `performance_required: true` 进入 Phase 6，否则 Phase 7
Torch 绑定通过或已跳过但无性能数据	Phase 6 未完成	执行性能采集
优化中 design.md 已修订但未重新生成代码	Phase 6.5 委托链中断	回 `shmem-ops-code-gen` 根据修订后的 design.md 重新生成
优化中代码已修改但编译失败	Phase 6.5 委托链中断	回 `shmem-ops-code-gen` 修复后重新编译
有性能数据但优化未完成	Phase 6.5 未完成	从下一轮优化继续
优化完成但无 Torch 回归	Torch 回归未完成（且 `torch_required: true`）	执行 Torch 回归门禁

编译/测试失败

由 shmem-ops-compile-debug 内部处理，持续修复直到正确性通过或确认为环境阻塞/设计缺陷。

name	shmem-ops-dev
description	基于 SHMEM 的通信算子与通算融合算子端到端开发编排器，串联需求→设计→代码→编译→验证→性能全流程。关键词：基于SHMEM算子开发、端到端开发、算子开发、编排、工作流、通信算子、通算融合。

#	必问项
1	CANN 路径：A 沿用当前 shell / B 默认系统 / Other 粘贴 `set_env.sh` 路径（或选 C 后下一条消息提供）
2	构建模式：`custom-ops` 独立工程 / `examples` in-tree
3	是否需要 Torch 接入（Phase 5.5）
4	是否需要性能采集（Phase 6）
5	未达标时是否自动进入性能优化（Phase 6.5，最多 5 轮）

shmem-ops-dev

More from this repository

More from this repository

SHMEM 算子端到端开发编排

⚠ Phase 0 启动门禁（用户 @ 指定本 skill 时 — 首读本节）

核心原则

可用子 Skill 清单

工作流总览

反模式清单（NEVER DO THESE）

Phase 0

Phase 1

Phase 2

Phase 3

Phase 4

Phase 5.5

Phase 6

Phase 6.5

通用

Phase 0：需求与环境确认

启动门禁（Hard Gate — 新会话 MUST 遵守）

Step 0.1：环境确认（MUST 在任何开发动作之前完成）

CANN 环境

Conda / Python 环境

SHMEM 仓库

PyTorch / torch_npu 依赖（Phase 5.5 前置）

SHMEM 构建产物

编译器（可选预检）

环境确认检查点

Step 0.2：算子需求收集

Step 0.2.1：构建模式确认（MUST — AskQuestion #2，不可跳过）

Step 0.3：Torch 与性能确认（MUST — AskQuestion #3/#4/#5，不可跳过）

MUST检查

Phase 1：设计文档

执行内容

MUST检查

Phase 2：测试用例生成

执行内容

MUST检查

Phase 3：代码生成

执行内容

MUST检查

Phase 4：正确性验证

执行内容

MUST检查

Phase 5：实现与设计一致性走读

执行内容

MUST检查

Phase 5.5：Torch 接入与验证（条件性）

环境预检（torch_required: true 时 MUST 在调用 torch-bind 前执行）

执行内容

MUST检查

Phase 6：性能采集

执行内容

MUST检查

Phase 6.5：性能优化（最多 5 轮）

执行内容

停止条件

聊天输出（Hard Gate）

Torch 回归门禁（Phase 6.5 → Phase 7 之间）

Phase 7：最终交付

执行内容

阶段间数据流

状态跟踪表

错误恢复

中断恢复矩阵

编译/测试失败

SHMEM 算子端到端开发编排

⚠ Phase 0 启动门禁（用户 @ 指定本 skill 时 — 首读本节）

核心原则

可用子 Skill 清单

工作流总览

反模式清单（NEVER DO THESE）

Phase 0

Phase 1

Phase 2

Phase 3

Phase 4

Phase 5.5

Phase 6

Phase 6.5

环境预检（`torch_required: true` 时 MUST 在调用 torch-bind 前执行）

环境预检（`torch_required: true` 时 MUST 在调用 torch-bind 前执行）