FilesLast commitLast update
2 months ago
1 month ago
3 months ago
3 months ago
2 months ago
README

changwei-op-dev — 长尾算子开发 skill

端到端 AscendC(昇腾 NPU)算子开发与自测的主导手册。加载 SKILL.md 即被它一路带着, 从「写算子 → 代码检视 → 出包 → 生成用例 → 功能/泛化/性能/精度验证 → 转测交付件 → 转测前终检」 把一个算子完整做好并验过,且不重踩前人的坑。本文件是目录入口:讲清干什么、怎么组织、怎么读。 详细流程与铁律以 SKILL.md 为准。


一、这个 skill 干什么

  • 对象:长尾算子族——foreach / scatter·index / lamb·optim / norm / 各类 activation,多为移植到 arch35(Ascend950,DAV_3510,regbase)。
  • 按 LLM agent 高效准确工作排布(非按知识主题堆文档):见下「双轴」。
  • 核心价值:把真金白银踩出来的坑固化成流程,并把关键红线做成机器守卫脚本——让后人不再重踩、且红线靠机器卡而非靠记性。

二、双轴导航(纵轴流水 gate + 横轴速查表)

  • 纵轴 · 流水(0→7):每步先过 GATE(红线+本步决策 checklist) 再动手,how 部分直接给"抄哪个算子"。锚定检查到该发生的时刻。
  • 横轴 · 速查表 references/lookup/:随时按需查,不用读完厚 manual。
    • reference-op-map.md —— 模式→抄哪个工作算子(注:真正的参照是活代码仓,本表只是缓存;表里没有就"先搜仓再动手",别硬造)。
    • error-index.md —— 拿实际报错串 grep→根因→修法。
    • red-lines.md —— 所有红线一处,每步 GATE 回链。

四条铁律(① freshness ② golden 只能竞品接口/拼接 ③ 转测表只 PASS/不涉及 ④ A5 不碰 A2)——正文见 SKILL.md 铁律区;全量红线(R1-R8)见 references/lookup/red-lines.md。此处不复述,避免多源。

步 GATE(动手前必确认) 做什么 指导
0 环境 GPU 连接就绪? 激活 CANN(A 本地 NPU)+ B 竞品 GPU 就绪自检 pipeline/step0-env.md
1 需求 A2 支持面核实? A5 相对 A2 有无差异?(有→step3 必 soc 隔离) 01(六节)+03 spec pipeline/step1-requirement.md
2 设计 范式选型?(查参照算子地图) 算法→arch35/tiling → 02 pipeline/step2-design.md
3 开发 R2 不碰 A2 / R6 校验用宏 / regbase 必 VEC_SCOPE kernel/tiling/host+通路+检视 pipeline/step3-develop.md
4 出包 freshness build.sh --pkg→装 vendor pipeline/step4-build-deploy.md
5 验证 R7 通路先于泛化; 每腿守 freshness 通路→泛化→精度三方→性能→DFX pipeline/step5-verify.md
6 交付件 7 项齐? 01-07 逐条产出 pipeline/step6-deliverables.md
7 终检 先跑机器守卫脚本(失败即停) + 人工 gate 放行 pipeline/step7-final-check.md
0 环境 → 1 需求 → 2 设计 → 3 开发 → 4 出包 → 5 验证(通路→泛化→精度→性能→DFX) → 6 交付件 → 7 终检
                       ▲                    │
                       └── 发现问题 ↺ 回 3 修 → 重出包 → 重验(每次守 freshness) ─┘

竞品 GPU 环境(5.2 精度 + 5.3 性能 共享前置):真源 = ops-competitor-profiling 的 competitor-environment.json(在 my_skills 仓),别硬编码;scripts/check_gpu_env.sh 非阻断醒目告警。


三、目录结构

changwei-op-dev/
├── SKILL.md                         # 薄导航总入口(权威):四铁律 + 双轴 + 0→7 GATE 流水表
├── README.md                        # 本文件
├── references/
│   ├── pipeline/     〔纵轴·流水各步 GATE→配方→verify〕step0…step7(8 个)
│   ├── lookup/       〔🆕 横轴·速查表〕
│   │   ├── reference-op-map.md       #   模式→抄哪个算子(缓存;真源是活代码仓)
│   │   ├── error-index.md            #   报错串→根因→修法
│   │   └── red-lines.md              #   红线汇总(每步 GATE 回链)
│   ├── manuals/      〔厚手册·详细方法〕
│   │   ├── development.md            #   写内核/host + §3 arch35 双代/A2-A5 隔离
│   │   ├── verification.md           #   TTK/批驱动/G-N 铁律/三方精度逐步
│   │   └── handover-deliverables.md  #   7 交付件规范 + 06/07 xlsx 填法 + golden 铁律
│   ├── crosscut/     〔横切·铁律+知识库〕freshness / op-family-lessons / common-issues
│   └── lesson-intake.md             〔治理〕固化经验唯一流程(五步:含⑤登记触发点挂钩)
├── templates/                       # 交付件模板 01/02/06/07
└── scripts/
    ├── analyze_lesson.py             # 经验归属只读分析器(辅助 lesson-intake ③)
    ├── check_valid_macros.sh         # 🆕 守卫 R6:校验禁裸 OP_LOGE
    ├── check_a2_soc_isolation.sh     # 🆕 守卫 R2:A5 差异必 soc 隔离
    ├── check_a2_untouched.sh         # 🆕 守卫 R2:A2 flat 内核 vs HEAD 无污染
    ├── check_arch35_config.py        # (已知 ascendc_config 非 binary 闸门,见 common-issues)
    ├── check_gpu_env.sh              # 竞品 GPU 就绪自检
    └── gen_func_xlsx.py              # 泛化功能 xlsx 报告

🚧 治理 + 守红线的两层保证

  • 固化经验走唯一机制:谁提"固化/记下来"→ agent 必须加载 references/lesson-intake.md 五步执行(价值门禁→分类→定 canonical 归属→写单源正文→⑤登记触发点挂钩:内容单源不丢、触发多钩真用)。禁直接手插 references/。
  • 守红线靠机器不靠记性:能被 grep/diff 判定的红线做成 scripts/check_*.sh,step7 终检硬跑、失败即停(check_valid_macros/check_a2_soc_isolation/check_a2_untouched 均已在真实算子验证过:过正确码、抓违规)。markdown GATE 提高主动守的概率,机器守卫给强制力,判不了的(算法对错)靠强制 golden/三方验证兜底。

四、修改历史

日期 变更 载体
2026-06-30 初版骨架:族坑清单、arch35 config 自查、功能 xlsx op-family-lessons.md、scripts/*
2026-07-01 验证流水成文 verification.md
2026-07-12 开发阶段成文:arch35 双代接线/CMake 路由/对齐 A2 development.md
2026-07-13 常见问题大扩充:定位 6 招 + 全症状/根因/修法 + §G 上库门禁 common-issues.md
2026-07-19 大重构为流水导航式:SKILL 薄入口 + references 三层 + 8 薄 step + 4 模板 全量
2026-07-20 竞品 GPU 环境接入(配置驱动) + 经验固化治理机制(lesson-intake + 只读分析器) step0/check_gpu_env.sh/lesson-intake.md
2026-07-21 双轴重排(按 LLM agent 效率/准确性):新增横轴 lookup/ 三速查表(参照算子地图/错误串索引/红线汇总);四条铁律(加 A5 不碰 A2);step 改 GATE→配方→verify;lesson-intake 升级五步(加⑤触发挂钩:内容单源+触发多钩);新增 3 个红线守卫脚本 + step7 硬跑 gate;认知修正(参照靠搜活代码仓非 curated 表、守红线靠机器守卫非文档) SKILL/README/lookup/scripts/step3/step5/step7/lesson-intake
2026-07-23 新增检查项:infershape 必须双挂 InferShape+InferDataType(漏 InferDataType→GE 输出 dtype 推导缺失/推错;量化·多输出算子尤甚,拷模板易漏)——canonical development §7-8 + 三触发钩(step3 GATE / step7 gate 10b / §7 检视清单);纠正 step4 binary 闸门=def AddConfig(ascendc_config.json 已废弃) development §7 / step3 / step7 / step4
2026-07-23 公共文档写作规范单源化:新增 handover §8(上开源仓 README/aclnn/op_list/op_api_list 写作规范——区分内部交付件 vs 公共文档两受众;通用规则指向 CANN 权威源守单源不重写;README 章节对齐官方模板含参考资源可选;长尾特有坑:确定性三取值/描述别抄兄弟/产品差异移表下/torch 接口独立判定)。订正 README 五节→6 节、07 .md→.xlsx;补 op_list/op_api_list 条目模板;挂钩 step6 GATE + step7 gate-9/9a + 上库前过 asc-doc-checker handover §8 / step6 / step7 / SKILL / templates
2026-07-23 资料细节补进流水 + 常犯错误自查册:①step3 加公共文档写作钩(接口定型即同步写 README/aclnn)→ handover §8,使资料细节在写文档时刻被遇见。②新增 lookup/recurring-mistakes.md——changwei 真栽过的跟头按流水阶段(全程纪律/开发/出包/验证/交付)成可勾册,薄索引指回 canonical(common-issues/op-family/freshness/red-lines/error-index/全局 memory,守单源不重抄);首次纳入 5 条 skill 原无的工作纪律(别为迎合红测试改码/别陷研究死循环/别替 Claude 碰 NPU 设备/always-verify-latest/fork PR 单 commit)。挂钩 SKILL 横轴 + step3/5/6 GATE + step7 gate-11 lookup/recurring-mistakes / SKILL / step3 / step5 / step6 / step7
2026-07-23 三算子(mml/gnsq/nzv)资料过新流水试验 + 自查册补 2 复现坑:试验验证流水有效(mml README stub+NLL 描述扩散3处/gnsq H1 拼写 Qunat+beta 默认值抄 gamma/nzv 资料缺失,全 hit)。沉淀 2 条新复现坑进 §8.3+册:"抄相邻行/兄弟忘改"泛化(原仅 op_list 描述→加 README/aclnn 参数默认值/dtype,gnsq beta 抄 gamma 案例) + 产品支持表 x/× 混用统一 ×(mml/gnsq 都犯)。深内容落 §8.3,册交付段挂薄钩 handover §8.3 / lookup/recurring-mistakes
2026-07-23 自查册补"已开发算子 op_list 说明别留占位符":占位符"暂无AscendC实现,欢迎贡献"只留给真未实现算子;算子已开发就要替换成本算子真实功能描述(别因 54 个兄弟都留就跟着留——mml 已开发就该改)。mml op_list/op_api_list 描述已修正(NLL→multilabel margin loss + 占位符→功能描述) handover §8.3 / lookup/recurring-mistakes
2026-0723 nzv/mml/gnsq 检视意见沉淀 5 条进 §8.3+自查册:①公共README调用说明只呈现aclnn+GE图模式(不呈现torch/tf,归转测06/07) ②公共文档无冗余空格(中文/英文/数字/符号间,产品名除外) ③列表项(计算公式)下内容缩进2空格 ④产品支持表6个产品齐+按CANN包维度写 ⑤新增产品支持同步刷op_api_list确定性列 handover §8.3 / lookup/recurring-mistakes
2026-07-23 nzv/mml/gnsq 检视闭环再沉淀 4 条:①确定性值必核实实现(别照抄兄弟;查 tiling isDeterministicKey+确定/非确定双实现,内核无条件 SetAtomicAdd=非确定→只写"默认非确定性实现",mml 反例) ②产品支持 √/× 权威判据(canndev op_info_cfg 逐 SOC [Op] 段 + npu-hardware-params SOC↔产品名映射) ③arch35 支持面/dtype 看 op_info_cfg 实机非 IR proto 宽松契约 + proto Type/def Int 是 CANN 两层约定别乱修 ④A5 逐字 mirror A2 已评审代码不引偏离改(tf_plugin 反例) handover §8.3 / development §3 / red-lines R2 / recurring-mistakes

近期主线:从「写完出包」→「上库门禁」→「流水导航重构」→「双轴重排 + 机器守卫红线」——薄入口带走 0→7,红线做成脚本硬卡,经验单源+触发挂钩确保不丢且真被用。