Tilelang Pass Generate

TileLang-Ascend Pass 代码生成 Skill

1. 目标与边界

1.1 本 skill 负责（In Scope）

把已经定型的 Pass 设计文档（pass-design.md）落到代码上，覆盖：

• C++ 实现：src/transform/<pass_name>.cc
• Python 封装：tilelang/transform/__init__.py
• 配置键（可选）：tilelang/transform/pass_config.py
• Pipeline 接入：tilelang/engine/phase.py
• 最小冒烟验证：导入是否成功、Pipeline 是否仍然能跑通最小 example、跨文件命名是否一致

1.2 本 skill 不做（Out of Scope）

• ❌ 不生成 UT / ST 测试代码 —— 由后续单独的测试生成 skill 负责
• ❌ 不重做 Pass 定位与方案决策（属于 tilelang-pass-design）
• ❌ 不修改 TVM 原生 Pass

所有重大决策必须沿用 pass-design.md 已经写定的内容；如果设计文档里某项是「待确认」或缺失，则停下来回到 tilelang-pass-design 补齐，不在本 skill 里临时拍板。

完成代码生成后，提示用户调用「Pass 测试生成 skill（待创建）」补 UT/ST，不在本 skill 里偷跑。

2. 必需输入

设计文档 §5「测试方案」本 skill 不消费，仅作为下游测试 skill 的输入保留。

输入校验规则：

1. 若 pass-design.md 不存在 → 立即停止，引导用户使用 tilelang-pass-design
2. 若设计文档中 §2 / §3 / §4 任一关键章节出现「待确认」「待补充」「TODO」 → 立即停止，列出缺口并要求补齐
3. 若 Pass 名称、阶段归属、Pipeline 位置任何一项不明确 → 立即停止，要求用户先回到 design skill

3. 工作流程

「先骨架、再代码、最后冒烟」三段式流程，骨架阶段不可跳过。

[输入校验]
   ↓
[Phase A: 信息收集]
   ↓
[Phase B: 生成实现骨架文档 pass-impl-skeleton.md]   ← 框架设计文档
   ↓
[用户确认骨架]
   ↓
[Phase C: 落代码（C++ / Python / pass_config / phase.py）]
   ↓
[Phase D: 最小冒烟验证（不跑 UT/ST）]
   ↓
[Phase E: 收尾报告 + 引导补测试]

Phase A：信息收集

按以下顺序读取，禁止一上来就 grep 整个 src/transform/：

1. 设计文档：用户指定路径，或默认在当前目录 pass-design.md
2. 总体约束：.agents/skills/tilelang-pass-agents-guide.md
3. 实现模式：.agents/skills/tilelang-pass-design/references/pass-impl-patterns.md
4. Pipeline 现状：tilelang/engine/phase.py（确认插入位点的上下文与函数签名）
5. Python 封装现状：tilelang/transform/__init__.py（确认现有命名风格、_ffi_api 调用方式）
6. 相似 Pass 源码：pass-design.md §4.1 指定的参考 Pass，仅读 1–2 个最接近的实现，不得扫整目录

pass-design.md 决定目标行为；当前源码决定真实接口、顺序和约束。两者冲突时停止并修正 design，不能用设计文档覆盖已存在的 pipeline invariant。

Phase B：生成实现骨架文档（pass-impl-skeleton.md）

骨架文档是「代码层面的最后一次结构化对齐」。它比 pass-design.md 更落地，但又比真实代码更轻量，目的是在写代码前一次性把以下决策列清楚：

1. 改动文件清单：四个基础接入点（.cc / __init__.py / pass_config.py / phase.py） 加上 design 证明必需的 catalog、公共 header 或 OperationConfig supporting files
2. C++ 类骨架：类名、父类、成员变量、构造函数签名、所有要重写的 VisitStmt_ / VisitExpr_ 方法签名（不写实现体）
3. Substitute 入口流程：步骤化伪代码（读取 attrs → 构造 mutator → MutateFunc → 设置 attrs）
4. 辅助类/辅助函数清单（如 Detector、Analyzer、Rewriter 模式拆分）
5. Attr 与结构事实表：consumed / produced / invalidated facts、来源/消费者和缺失策略
6. 注册与配置键：TVM_REGISTER_GLOBAL 完整字符串、可选的 TVM_REGISTER_PASS_CONFIG_OPTION
7. Python 封装函数签名：参数、docstring 要点
8. Pipeline 接入点：phase.py 中 after X / before Y，以及不跨越的结构边界
9. 最小冒烟验证步骤：先跑哪一条命令（导入冒烟 / 编译冒烟 / 最小 example 能跑）

⚠️ 骨架文档不写测试用例。测试相关内容由后续独立 skill 负责，本骨架里仅在末尾留一行「测试待补由 Pass 测试生成 skill 处理」作为交棒标记。

骨架文档基于 templates/pass-impl-skeleton-template.md 填写，输出到 pass-impl-skeleton.md。完成后必须停下来等用户确认，再进入 Phase C。

骨架阶段禁止写完整 VisitStmt_ 函数体或修改实现文件。

Phase C：落代码

在用户确认骨架后，按以下顺序逐文件落地。每完成一个文件，立即做最小检查再走下一个（参见 §6 增量验证策略）。

本 skill 不写、不改 testing/python/ 下任何文件。 Catalog、公共 header 和 OperationConfig 等 supporting files 只有在骨架已证明必要时修改。

落代码硬约束

• 禁止脱离 pass-impl-patterns.md 模板：父类继承、Substitute 静态入口、CreatePrimFuncPass 调用方式必须与模板一致
• 禁止改动 tir.transform.* 等 TVM 原生 Pass（来自 tilelang-pass-agents-guide.md 约束 3）
• 禁止只改 .cc 不改 Python 封装（约束 4）
• 禁止把多种职责塞进一个 Pass（约束 4：功能正交）
• 配置默认值必须显式验证：从 C++ GetConfig、target defaults 和设计语义确认，不能从 “Ascend-specific” 推断为 False。例如 tl.ascend_vector_mask_reuse 默认 True，且只控制 reuse 策略，不关闭 Selection / Legalize。
• Attr 读取必须做 defined() 检查：缺失时按设计文档的策略处理（报错 / 跳过 / 默认值），不得静默崩溃
• C++ 注释保持最小：仅在 WHY 不直观时写一行（来自仓库总规约）

Phase D：最小冒烟验证

本 skill 不新建 UT/ST，但验证不能停在 import：

1. 命名与导入冒烟：

   python -c "import tilelang; from tilelang.transform import <Pass>; print(<Pass>())"

   验证 Python 封装、_ffi_api 注册、C++ 端 TVM_REGISTER_GLOBAL 字符串四方一致。
2. C++ 重建：修改编入 shared library 的 C++ 后必须重新构建；环境阻塞时明确报告，不能用 grep 代替。
3. 现有聚焦回归：至少运行一个能经过新行为的既有编译或行为测试；没有覆盖时报告永久测试缺口。
4. 跨文件一致性 grep：

   grep -n "<PassName>" src/transform/<pass>.cc tilelang/transform/__init__.py tilelang/engine/phase.py
   grep -n "tl.<pass_lower>" src/transform/<pass>.cc tilelang/transform/pass_config.py

本阶段不新建 UT/ST；既有聚焦测试属于必需验证，不是额外可选项。

若验证失败，按以下顺序定位：

• 编译错误 → 头文件缺失、TVM API 签名变化、命名空间问题
• 注册错误 → TVM_REGISTER_GLOBAL 字符串与 Python 调用名不一致
• Attr 读取错误 → 类型签名（Map<Var, ...> vs Map<Buffer, ...>）不匹配
• Pipeline 顺序错误 → 上游 attrs 未产生时本 Pass 已被调用

禁止失败后无脑加 try/except 把异常吞掉（仓库总规约：不要遮住问题）。

Phase E：收尾报告 + 引导补测试

参考 §7 模板输出报告，必须包含：

• 已生成 / 修改的实现侧文件
• 已跑过的冒烟项 与 未即时验证项
• 明确提示「UT/ST 待补，建议下一步使用 Pass 测试生成 skill」