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

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 内部处理，持续修复直到正确性通过或确认为环境阻塞/设计缺陷。

#	必问项
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

Más de este repositorio

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 前执行）