| name | tilelang-pass-analyzer |
| description | TileLang Pass 功能分析与对比工具。触发条件：(1) 用户询问特定 pass 的功能、作用、原理、实现细节，关键词包括"XXpass是干什么的"、"介绍XXpass"、"XXpass的功能"、"XXpass怎么实现的"、"分析XXpass"；(2) 对比两个 pass 的差异、联系；(3) 查询某类 pass 列表；(4) 模糊匹配 pass 名称。支持精确匹配和模糊匹配，返回由浅入深的 Markdown 分析报告，包含伪代码、IR 变换示例、代码位置等。 |
TileLang Pass 分析工具
⭐ 核心约束：分阶段信息获取
严格遵守以下信息获取优先级：
| 查询阶段 | 信息来源 | 工具使用 |
|---|
| 首次回答 | ✅ 优先使用 reference 文件 | read(references/*.md) |
| 用户追问深入细节 | ✅ 读取源码补充 | read(src/transform/*.cc) |
执行规则：
用户首次提问 Pass 功能
↓
1. 立即读取 reference 文件（pass-registry-*.md / pass-classification.md）
↓
2. 基于 reference 信息生成报告（足够回答 90% 的查询）
↓
3. 仅在用户追问"具体实现"、"源码细节"、"某个函数逻辑"时才读取源码
禁止行为：
- ❌ 首次回答就读取
src/transform/*.cc 源码文件
- ❌ 忽略 reference 文件中的已有信息
- ❌ 过度深入分析辅助工具类（首次回答时）
- ❌ 首次回答就并行读取 reference 和源码
核心工作流程
Step 1: 解析用户意图
根据用户输入判断查询类型：
| 意图类型 | 关键词特征 | 处理方式 |
|---|
| 单 Pass 分析 | "XX pass 是做什么的"、"分析 XX pass"、"XX 的功能" | 查 registry → 分析代码 → 生成报告 |
| 双 Pass 对比 | "XX 和 YY 的区别"、"对比 XX YY"、"XX YY 的差异" | 生成对比报告（每节对比） |
| 双 Pass 联系 | "XX 和 YY 的联系"、"XX YY 的关系"、"XX YY 协作" | 生成联系报告（每节分析关系） |
| 分类查询 | "XX 类的 pass"、"内存相关 pass"、"Ascend pass 有哪些" | 查 classification → 列表报告 |
| 模糊匹配 | "sync 相关"、"vector pass"、"那个插入同步的" | 搜索 → 返回候选列表 |
Step 2: Pass 定位
精确匹配：
1. 读取 references/pass-registry-ascend.md 或 pass-registry-general.md
2. 根据名称获取：C++ 文件路径、Python 函数名、配置键
3. 定位到具体文件
模糊匹配策略：
1. 提取用户输入的关键词（去除 pass、transform 等通用词）
2. 在 registry 中搜索名称包含关键词的所有 pass
3. 返回候选列表（最多 5 个）：序号、名称、简述、分类
4. 提示用户选择序号或输入完整名称
分类查询：
1. 读取 references/pass-classification.md
2. 根据用户指定的分类（如"内存管理"、"同步"、"Ascend平台"）返回列表
3. 按子分类组织输出
Step 3: 代码分析（仅在用户追问深入时执行）
⚠️ 重要：首次提问时跳过此步骤，仅使用 reference 文件信息。
仅在用户追问以下问题时才执行此步骤：
- "某个函数的具体实现"
- "源码中的某个细节"
- "算法的具体逻辑"
- "某个配置项的作用"
按以下顺序分析 Pass 实现：
1. Python API 层
- 文件：
tilelang/transform/__init__.py
- 提取：函数签名、docstring、参数
2. C++ 实现层
- 文件：
src/transform/<pass_name>.cc
- 提取：
- 文件头注释
/*! \file ... */
- 主类名（通常继承
IRMutatorWithAnalyzer、StmtExprVisitor 等）
- 核心方法名（如
Substitute、VisitStmt、VisitExpr）
- 注册宏
TVM_REGISTER_PASS_CONFIG_OPTION 或 TVM_REGISTER_GLOBAL
3. 配置层
- 文件：
tilelang/transform/pass_config.py
- 提取：配置键名、默认值、描述
分析方法：
- 快速浏览文件头注释，理解 pass 目标
- 找到主类的 Substitute 或 VisitXxx 方法，理解核心逻辑
- 分析算法流程：遍历 → 匹配 → 变换 → 输出
- 查看 common/ 目录下的辅助工具类
Step 4: 报告生成
根据查询类型选择模板：
| 查询类型 | 模板选择 |
|---|
| 单 Pass 分析 | 使用【单 Pass 分析报告模板】 |
| 双 Pass 对比 | 使用【双 Pass 对比报告模板】 |
| 双 Pass 联系 | 使用【双 Pass 联系报告模板】 |
| 分类查询 | 使用【分类查询报告模板】 |
| 模糊匹配 | 使用【模糊匹配候选列表模板】 |
通用风格要求：
✅ 由浅入深：先一句话总结，再逐步展开细节
✅ 伪代码精简：不超过 10 行，每个关键步骤标注函数名和备注
✅ IR 示例清晰：简化结构，标注变化点
✅ 核心函数标识：指出函数名，不引用完整代码片段
✅ 伪 IR 说明：首次使用时标注"本示例为伪 IR"，真实 TIR 格式见 ir-examples.md
伪代码编写规范
格式模板：
输入: PrimFunc / IR Module
处理流程:
1. 遍历 IR 结构 → VisitStmt()
2. 匹配目标模式 → MatchPattern()
3. 执行变换操作 → TransformStmt()
输出: 变换后的 PrimFunc
- VisitStmt: 继承 IRMutatorWithAnalyzer，访问 Stmt 节点
- MatchPattern: 检查 buffer scope、op type 等属性
- TransformStmt: 根据规则生成新语句，可能涉及同步/地址映射等
编写规则：
- 每个关键步骤标注对应的 C++ 函数名
- 用
# [备注: ...] 说明该步骤的作用或决策依据
- 总行数不超过 10 行
- 输入/输出明确标注类型
IR 示例编写规范
参考 references/ir-examples.md 的格式。
基本格式：
**输入伪 IR：**
# 变换前状态（简要说明）
[简化 IR 结构]
**输出伪 IR：**
# 变换后状态（简要说明）
[简化 IR 结构，用 ← 标注变化点]
**变换要点：**
- [变化点1]
- [变化点2]
注意事项：
- 首次使用伪 IR 时，添加说明：
本示例为伪 IR 格式，真实 TIR 结构见 ir-examples.md
- 只保留关键元素，不超过 10 行
- 用
← 标注新增/修改，用 # [备注] 添加说明
报告模板
以下模板用于生成不同类型的 Pass 分析报告。
模板一：单 Pass 分析报告
# [Pass名称] 功能分析报告
## 一句话总结
> [核心功能概括，不超过 30 字]
## 功能详解
### 1. 作用与目的
[解决的问题和必要性]
### 2. 工作原理
输入: PrimFunc → 遍历 IR → 匹配模式 → 执行变换 → 输出: PrimFunc
核心函数: [函数名1]、[函数名2]
### 3. IR 变换示例
变换前: [简化IR] → 变换后: [简化IR，←标注变化]
要点: [变化点1]、[变化点2]
### 4. 使用场景与触发条件
| 项目 | 说明 |
| 适用平台 | Ascend 专用 / 通用 |
| 启用配置 | `配置键` (默认值) |
| 触发时机 | 编译阶段 |
### 5. Pass 关系与工作流
如需了解本 Pass 在 Pipeline 中的位置、与其他 Pass 的依赖关系，请使用 **tilelang-pass-workflow-analyzer** skill。
## 代码位置
| 组件 | 路径 | 核心元素 |
| Python API | `路径` | `函数名()` |
| C++ 实现 | `路径` | `类名::方法` |
| 配置项 | `路径` | `配置键` |
模板二：双 Pass 对比报告
# [Pass1] 与 [Pass2] 对比分析报告
## 一句话总结
> [共同点和核心差异，不超过 40 字]
## 功能对比
### 1. 作用与目的对比
| 维度 | [Pass1] | [Pass2] |
| 核心目标 | [简述] | [简述] |
| 解决问题 | [简述] | [简述] |
### 2. 工作原理对比
| Pass | 输入 | 处理 | 输出 |
| [Pass1] | ... | [函数名] | ... |
| [Pass2] | ... | [函数名] | ... |
关键差异: [差异点1]、[差异点2]
### 3. IR 变换对比
| Pass | 变换前 | 变换后 |
| [Pass1] | [IR] | [IR，←变化] |
| [Pass2] | [IR] | [IR，←变化] |
### 4. 使用场景对比
| 维度 | [Pass1] | [Pass2] |
| 适用平台 | ... | ... |
| 启用配置 | `key1` | `key2` |
### 5. 关系分析
执行顺序: [PassA] → [PassB] (原因: ...)
数据依赖: [Pass1] 提供 [数据] → [Pass2]
协作方式: 共同完成 [目标]
冲突限制: [限制条件]
## 代码位置对比
| Pass | Python API | C++ 实现 | 配置项 |
| [Pass1] | `路径` | `路径` | `key1` |
| [Pass2] | `路径` | `路径` | `key2` |
模板三：双 Pass 联系报告
# [Pass1] 与 [Pass2] 关系分析报告
## 一句话总结
> [协作关系概括]
## 关系分析
### 1. 作用与目的的联系
共同目标: [共同服务的目标]
分工协作: [Pass1] 负责 [职责1]，[Pass2] 负责 [职责2]
### 2. 工作原理的联系
数据流: [Pass1] → 输出: [数据] → [Pass2] 输入
依赖关系: [Pass1] 提供 [内容]，[Pass2] 需要 [内容]
### 3. IR 变换联系
Pass1 输出: ... (提供给 Pass2) → Pass2 输入: ... (来自 Pass1)
整体效果: [组合后的效果]
### 4. 执行顺序与触发
执行顺序: ... → [Pass1] → ... → [Pass2] → ...
顺序原因: [必须按此顺序的原因]
### 5. 协作场景
典型场景: [具体协作场景]
协作效果: [对比单独使用的效果]
## 代码位置
| Pass | Python API | C++ 实现 | 配置项 |
| [Pass1] | `路径` | `路径` | `key1` |
| [Pass2] | `路径` | `路径` | `key2` |
模板四：分类查询报告
# Pass 分类查询报告：[分类名称]
## 分类概述
> [该类 Pass 的共同特征]
## Pass 列表
### [子分类1]
| Pass 名称 | 功能简述 | 配置项 |
| [Pass1] | [描述] | `配置键` |
| [Pass2] | [描述] | `配置键` |
### [子分类2]
...
## 典型使用场景
场景1: [描述] → 推荐组合: [PassA]+[PassB]
模板五：模糊匹配候选列表
# Pass 匹配结果
根据关键词 "**[用户输入]**" 找到以下候选 Pass：
| 序号 | Pass 名称 | 功能简述 | 所属分类 |
| 1 | [Pass1] | [描述] | [分类] |
| 2 | [Pass2] | [描述] | [分类] |
| 3 | [Pass3] | [描述] | [分类] |
请选择你想了解的 Pass（输入序号 1-3 或完整名称）：
Reference 文件使用指南
本 skill 包含以下 reference 文件，按需查阅：
| 文件 | 用途 | 使用时机 |
| pass-registry-ascend.md | Ascend Pass 名称→路径 | 精确匹配 Ascend pass |
| pass-registry-general.md | 通用 Pass 名称→路径 | 精确匹配通用 pass |
| pass-classification.md | Pass 分类索引 | 分类查询 |
| ir-examples.md | IR 变换示例 | 编写 IR 示例 |
注意事项
- ⭐ 分阶段信息获取：首次回答只读 reference，追问细节才读源码
- 伪 IR 格式说明：首次使用时添加说明，后续无需重复
- 模糊匹配：最多返回 5 个候选，按相关性排序
- 双 Pass 报告：对比报告每节对比，联系报告每节分析关系
- 代码位置：尽量提供行号，核心元素指函数名、类名、配置键
- 分析深度：不深入分析辅助工具类，聚焦主类和核心方法
- Pass 工作流查询：
- 当用户询问 Pass 执行顺序、依赖关系、Pipeline 架构时，引导使用 tilelang-pass-workflow-analyzer skill
- 本 skill 专注于单个 Pass 的功能分析，不深入分析 Pass 之间的关系
