---
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
```

---

## 伪代码编写规范

**格式模板：**
```python
# 伪代码示例 (精简版)

输入: PrimFunc / IR Module
处理流程:
  1. 遍历 IR 结构 → VisitStmt()           # [备注: 深度优先遍历每个语句]
  2. 匹配目标模式 → MatchPattern()        # [备注: 检查是否为特定 op/buffer 类型]
  3. 执行变换操作 → TransformStmt()       # [备注: 生成新的 IR，保持语义等价]
输出: 变换后的 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 分析报告

```markdown
# [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 对比报告

```markdown
# [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 联系报告

```markdown
# [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` |
```

---

### 模板四：分类查询报告

```markdown
# Pass 分类查询报告：[分类名称]

## 分类概述
> [该类 Pass 的共同特征]

## Pass 列表

### [子分类1]
| Pass 名称 | 功能简述 | 配置项 |
| [Pass1] | [描述] | `配置键` |
| [Pass2] | [描述] | `配置键` |

### [子分类2]
...

## 典型使用场景
场景1: [描述] → 推荐组合: [PassA]+[PassB]
```

---

### 模板五：模糊匹配候选列表

```markdown
# 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 示例 |

---

## 注意事项

1. **⭐ 分阶段信息获取**：首次回答只读 reference，追问细节才读源码
2. **伪 IR 格式说明**：首次使用时添加说明，后续无需重复
3. **模糊匹配**：最多返回 5 个候选，按相关性排序
4. **双 Pass 报告**：对比报告每节对比，联系报告每节分析关系
5. **代码位置**：尽量提供行号，核心元素指函数名、类名、配置键
6. **分析深度**：不深入分析辅助工具类，聚焦主类和核心方法
7. **Pass 工作流查询**：
   - 当用户询问 Pass 执行顺序、依赖关系、Pipeline 架构时，引导使用 **tilelang-pass-workflow-analyzer** skill
   - 本 skill 专注于单个 Pass 的功能分析，不深入分析 Pass 之间的关系