| 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}"
在每个需要编译或运行算子的 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 再次检查并询问用户。
环境确认检查点
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 而跳过。
记录到 design.md compile.build_mode 与 meta.op_root（仅在用户 AskQuestion 选择后写入，不得 Agent 预设）：
meta:
build_mode: independent_project
op_root: custom-ops/<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
performance_required: true|false
performance_auto_optim: true|false
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检查
全部通过 → 进入 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检查
全部通过 → 进入 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检查
全部通过 → 进入 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检查
全部通过 → 判断 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检查
全部通过（或已跳过）→ 进入 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检查
达标 → 进入 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 检查：
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 内部处理，持续修复直到正确性通过或确认为环境阻塞/设计缺陷。
