Menu
基于 SHMEM 的通信算子与通算融合算子端到端开发编排器，串联需求→设计→代码→编译→验证→性能全流程。关键词：基于SHMEM算子开发、端到端开发、算子开发、编排、工作流、通信算子、通算融合。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
根据 design.md 生成基于 SHMEM 的算子代码、CMake、README 和目录结构。关键词：基于SHMEM代码生成、算子实现、code-gen、kernel、CMake。
基于 SHMEM 的算子实现与设计一致性走读，生成 review-report.md。关键词：基于SHMEM代码走读、code review、design review、一致性检查、走读。
编译、运行和调试基于 SHMEM 的算子。关键词：基于SHMEM编译调试、compile、debug、build、运行、失败定位。
执行基于 SHMEM 的算子正确性契约验证并生成报告。关键词：基于SHMEM正确性验证、correctness、测试执行、精度验证。
基于 SHMEM 设计通信算子与通算融合算子，将需求转化为 design.md。关键词：基于SHMEM算子设计、算子设计、设计文档、design、Canonical DSL、capability mapping。
基于 SHMEM 的算子性能采集、baseline 对比、瓶颈分析和性能报告生成。关键词：基于SHMEM性能评估、性能采集、performance、baseline、bandwidth、性能报告。
| name | shmem-ops-dev |
| description | 基于 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独立工程 /examplesin-tree3 是否需要 Torch 接入（Phase 5.5） 4 是否需要性能采集（Phase 6） 5 未达标时是否自动进入性能优化（Phase 6.5，最多 5 轮） 用户消息含
custom-ops、CANN 路径、Torch/性能表态 均不能 替代 AskQuestion。完整清单：
references/intake-checklist.mdAskQuestion 固定模板：references/askquestion-template.mdSHMEM 仓定位（读 docs/examples 前）：references/shmem-repo-resolution.mdSkill 总索引：references/GUIDE.md执行契约（禁止中断/Torch/性能表）：references/agent-execution-contract.mdDocker 执行（用户指定容器时全部命令进容器）：references/docker-exec-contract.md
本 skill 编排九个专职子 skill，驱动 SHMEM 通信算子与通算融合算子从需求到可交付状态。
.md 文档（design.md、review-report.md、performance_report.md 等）必须使用中文撰写。仅 API 名称、代码片段、变量名、数学公式等技术术语保留英文原文，其余描述、分析、结论一律使用中文performance_auto_optim: true 进入性能优化（Phase 6.5，最多 5 轮）→ 最终交付，严格顺序执行.md 文档归入 docs/，所有 .cpp/.h 源文件归入 src/，测试脚本归入 scripts/。不得扁平散放| 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时由编排器 自动 进入。
askquestion-template.md 就自行构造 AskQuestion（导致 CANN 出现不可输入的「C. 自定义」）ASCEND_HOME_PATH 未设置时静默 source /usr/local/Ascend/ascend-toolkit/set_env.sh（MUST 先询问用户选默认或自定义 CANN 路径，见 cann-env-resolution.md）torch_test_*.py（见 docker-exec-contract.md）docker exec 与宿主机裸命令（探测、编译、运行 MUST 统一在容器内）examples/ 下（默认 custom-ops/<op_name>/）cmake -S ... -B ... 给用户/Agent（MUST 使用封装脚本，见 build-test.md §2.4）aclshmemi_* 或使用已 deprecated 的 aclshmemx_barrier_all_vec（见 internal-api-boundary.md）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）/root/shmem/log 就直接改 kernel（应先排查 shmem init / 端口 / 环境）-examples 后执行 make <op_name>（CMake 无该 executable target）build/ 和 install/）in_tree_example 模式下使用 custom-ops/<op>/scripts/run_case_matrix.py（MUST 路由到 examples/<op>/scripts/run.sh 或 example 实际测试入口）torch_required:true 时未自动生成全部算子 torch_test_*.py 或未 8PE 验证即进入 Phase 6pkill -f shmem 清理进程（MUST 使用 pgrep -f 'build/bin/<op_name>' 精确匹配；对外部进程先输出证据请求授权）block_dim=1 补齐到设计并发当作性能优化轮次调用 Skill：—
目标：确认算子开发所需的最小信息集，包括开发环境和算子需求
Fresh Session 调用 AskQuestion 前 MUST Read：references/askquestion-template.md，禁止自行编造表单（尤其 CANN 第三固定选项）。
详细清单：references/intake-checklist.md（Agent 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 及后续工具调用。
开发环境是所有后续阶段的前置依赖，必须首先确认。
详细流程见 shmem-ops-compile-debug/references/cann-env-resolution.md。
自动检测流程（检测仅用于 AskQuestion 选项展示，不能代替 AskQuestion #1）：
ASCEND_HOME_PATH 是否已设置，且 which bisheng 可用CANN_SET_ENV 时，无需重复 #1source /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）docker exec <container> bash -lc '...'，禁止宿主机裸跑自动检测流程：
echo $CONDA_DEFAULT_ENV）base 且非空）：直接使用当前环境，无需询问用户base：MUST 向用户询问要使用的 conda 环境名称激活方式：
conda activate <env_name>
在每个需要编译或运行算子的 Shell 会话中，都必须先激活 conda 环境。
路径规范：Skill 可与 SHMEM 仓分离部署。读仓内
docs/、examples/前见 shmem-repo-resolution.md。
自动检测流程（按顺序，命中即停）：
include/ 和 src/（如 shmem 根目录）→ 将当前目录作为 SHMEM_REPOshmem/ 子目录（含 include/、src/）→ 将 shmem/ 作为 SHMEM_REPOgit clone https://gitcode.com/cann/shmem.git 到当前目录下，将 shmem/ 作为 SHMEM_REPO；clone 失败则 MUST 向用户确认后再重试cd ${SHMEM_REPO} && bash scripts/build.sh -examples 完成首次构建硬门禁：SHMEM 仓库不存在（无
include/+src/）且 clone 失败时，MUST STOP，禁止进入 Phase 1。
在 conda 环境激活后执行：
python -c "import torch; import torch_npu; print(torch.__version__)"
torch 和 torch_npu 版本，无需询问用户torch/torch_npu 的环境自动检测流程：
${SHMEM_REPO}/install/set_env.sh 是否存在source install/set_env.shbash 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/kernelsAgent 在容器/远程环境 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 再次检查并询问用户。
ASCEND_HOME_PATH 已设 或 用户已选择默认/自定义 CANN_SET_ENV）source ${CANN_SET_ENV} 可正常执行且 bisheng 可用conda activate <env_name> 可正常执行torch 和 torch_npu 可导入（或标记待 Phase 5.5 前补齐）${SHMEM_REPO}/install/set_env.sh 存在（或标记待构建）确认本次任务入口和算子需求：
| 输入形态 | 处理方式 |
|---|---|
| 只有自然语言需求 | 收集最小需求后进入 Phase 1 |
| 有伪代码或异构参考实现 | 进入 Phase 1，设计阶段归一化 |
| 已有 design.md | 直接进入 Phase 1 质量门禁 |
| 用户说"继续开发" | 按中断恢复矩阵从最早未完成阶段恢复 |
最小确认项：
op_name（可用作目录名和符号前缀）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>
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 |
判定规则：
performance_auto_optim: false，或请用户改选 #4记录到 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 时生效
askquestion_completed: [1,2,3,4,5]performance_required:false 时记录为 performance_auto_optim:false）CANN_SET_ENV 已记录${SHMEM_REPO}/include/ 和 ${SHMEM_REPO}/src/ 存在，install/set_env.sh 已生成（不存在时自动 clone + build，clone 失败则 STOP）intake-checklist.md 记录格式）全部通过 → 进入 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
topology 含 deployment、拓扑类型、链路带宽（来自设计前确认）meta.build_mode 已确认（默认 independent_project；in-tree 须 Phase 0 用户明确要求）meta.torch_required 已确认（Phase 0 用户确认或明确表态，不得 Agent 擅自默认 true）meta.performance_required 已确认（为 false 时 Phase 6 跳过）meta.performance_auto_optim 已确认（为 false 时 Phase 6 未达标 不得擅自进入 Phase 6.5）Phase 1 的 design.md 门禁必须在进入 Phase 2 前完成。门禁结果中有任何 FAIL 或缺失 section，必须先修订 design.md 再继续，不允许带缺陷进入后续阶段。
全部通过 → 进入 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 文件
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
调用 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。
docs/ 含全部 .md、src/ 含全部 .cpp/.h、scripts/ 含全部测试脚本shmem-ops-code-gen 的全部 P0 项（完整清单见 code-gen SKILL.md §MUST检查），P0 任一 FAIL 则禁止进入 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 → 记录阻塞
build_mode 匹配（independent_project → custom-ops/<op>/；in_tree_example → examples/<op>/，禁止 in-tree 模式使用 custom-ops 路径）全部通过 → 进入 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 待补齐）
interim 走读全部 PASS（P0 无 FAIL）全部通过 → 判断 Phase 5.5 是否执行（见下）
torch_required: true 时：MUST 在本 Phase 结束后立即进入 Phase 5.5，为本批次全部算子生成 Torch 绑定与 torch_test_*.py，不得等待用户再次确认或说「继续」。
用户在 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 检查过但当前环境可能已切换）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 全量测试
torch_bind_<op_name>.cpp 包含 CustomClassHolder 子类和 REGISTER_SHMEM_OPS_CLASS 注册compute() 包含 TORCH_CHECK（dtype、device、shape）attr_init / finalize / malloc_tensor / malloc_like / free_tensor）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 精度验证torch_required: true 时）torch_required: true 时）torch_required: false 且已记录跳过原因全部通过（或已跳过）→ 进入 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
[BASELINE_PERF] 已采集docs/performance_report.md §3.5 对比表已填写performance_auto_optim: true → 立即 Phase 6.5performance_auto_optim: true → 立即进入 Phase 6.5performance_auto_optim: false → 输出差距表后进入 Phase 7，不改 kernel达标 → 进入 Phase 7（交付）；未达标且 performance_auto_optim: true → 立即进入性能优化
前置：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）
完成 → 进入 Torch 回归门禁（如适用）→ Phase 7
前置：meta.torch_required: true 且 Phase 5.5 已完成 且 Phase 6.5 已完成（kernel 代码可能已被修改）。
调用 Skill：shmem-ops-torch-bind
执行内容：
torch_test_<op_name>.py 8PE 全量测试shmem-ops-code-gen 修复 Torch 绑定代码后重新编译测试，直到 PASSMUST 检查：
shmem_custom_ops_torch.so / aclshmem_torch.so）torch_test_<op_name>.py 8PE 回归通过torch_required: false 且已记录跳过原因调用 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_test_<op_name>.py 运行结果；若经过 Phase 6.5 则为优化后回归结果）不要只输出路径；关键结果必须在回复中摘要展示。
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 内部处理，持续修复直到正确性通过或确认为环境阻塞/设计缺陷。