Tilelang Design Review

TileLang-NPUIR 算子设计文档检视

1. 目标

对 Stage 1 产出的 DESIGN.md 进行风险优先的检视，生成一份 REVIEW.md。REVIEW.md 必须包含明确的 结论: 通过 或 结论: 不通过，以及不通过时的具体修改建议，供 conductor 决定是否进入 Stage 3 或回退 Stage 1 重新设计。

迁移任务（DESIGN.md 含 §0 源算子解读与迁移分析）必须额外执行维度 0：源算子理解与迁移分析——检视 Stage 1 是否真正读懂了源算子（语义 / 算法 / 优化手段）、硬件耦合性判定是否合理、NPU 重设计是否可行且语义保持。

所有任务必须执行维度 8：算法优化分析——检视 Stage 1 是否先完成了算法调研（§1.6.0 调研四问齐全：等价化简公式 / 在线算法 / 复杂度 / 硬件亲和；调研结论经独立复核成立，且选定算法实际驱动 §1.4 与 §1.6.1–§1.6.3），是否先数学等价地优化了公式（更少计算量 / 访存量，且等价性论证成立），循环 / 标量计算是否已完成向量化替代分析（替代不了的必须有充分理由，且与 §3/§6 一致），以及是否完成了向量化轴与核内数据布局决策（候选矩阵 + 量化取舍；I/O layout 是契约、核内布局是设计变量，弃选方案必须有量化理由）。

2. 输入

检视前必须用 Read 完整读取 DESIGN.md；迁移任务还必须用 Read 读取 source_op_path 指向的源算子代码；并用 Glob 核对 DESIGN.md 中引用的 examples/ 文件是否真实存在。

3. 检视维度（风险优先，按顺序）

优先识别会直接导致 Stage 3 编译/运行/精度失败的阻塞级问题，其次识别建议级问题。迁移任务检视维度 0–8（共 9 项），非迁移任务检视维度 1–8（共 8 项，维度 0 标记 n/a 不输出）。

维度 0：源算子理解与迁移分析（阻塞级，仅迁移任务）

检视方式：亲自 Read 源算子代码，与 DESIGN.md §0 逐项核对。不读源码的检视无效。

维度 1：API 可行性（阻塞级）

维度 2：内存层级规划（阻塞级；可机检子集：design_calc_check.py ub/l1/l0c_budget 复算——VP-2026-0009 混合字节口径类错误的机械拦截位）

维度 3：Tiling 策略（阻塞级；可机检子集：design_calc_check.py core_split 逻辑核数算术复算）

维度 4：技术约束检测（阻塞级）

维度 5：循环与同步（建议级）

维度 6：验证方案（阻塞级）

维度 7：完整性与一致性（建议级）

维度 8：算法优化分析（阻塞级，所有任务；可机检子集：verify_equiv.py 重跑〔等价性〕+ design_calc_check.py r3_metrics〔四口径存在性〕——机械结果与独立推演互补）⭐

检视方式：以 §1.6 为对象逐项核对，并交叉核对 §3.1 / §6 与 §1.6 的双向一致性。数学等价性由本维度独立推演核对，不轻信设计文档自述；调研结论（§1.6.0）同样由本维度独立复核——等价性推演、复杂度算术复算、负向断言对照设计 skill 的 algorithm-research.md 参考表复核。弃选/否决类论断（API 不支持 / 代价高 / 无先例）的前提同样必须亲自查证——打开其引用的 API 文档核对代价机制（如 repack 是核内 UB 级还是 GM 级），不得只复算数字而继承设计的前提。

4. 工作流程

Phase 1：读取与核对

1. Read DESIGN.md 全文。
2. 迁移任务（DESIGN.md 含 §0）：Read source_op_path 指向的源算子代码全文；§0 与源码不一致的项在维度 0 中逐条记录证据（源码行/语句 + DESIGN.md 章节）。
3. Glob 核对 §3.5.3 引用的 examples/ 路径是否存在。
4. 必要时 Grep tilelang/language/ 确认 API 是否有导出佐证（仅静态文本核对，不执行）。
5. 弃选论证查证（强制）：对 §1.6.1 否决项与 §1.6.3 弃选行涉及的每个 API——设计已附 docs/ 佐证的，亲自打开该文档核对限制条款与代价机制；未附佐证的，在 docs/Tilelang.language/ 全部子目录（含 创建操作/、索引与元素操作/、条件操作/、排序操作/、逻辑操作/、原子操作/ 等未映射目录）Glob/Grep 检索该 API。检索不到且设计声称"不存在"的，在维度 8 记录查证过程；检索得到但与设计论断矛盾的，维度 8 fail。另须对照 pattern-library（tilelang-op-optimize skill references/pattern-library/：layout/elementwise/attention.md 模式与实测代价、traps-*.md 陷阱、constants.md 硬件常数）：设计的代价类负向论断与实测条目矛盾（如"转置慢"vs 实测 µs 级、"跨步向量化无解"vs 已验证换轴模式）→ 维度 8 fail；代价类论断未引用 pattern-library 已有实测数据的，要求补证（该量已有实测则不再是"未实证假设"）。
6. 算法调研独立复核（强制）：Read tilelang-op-design skill 的 references/algorithm-candidates.md（R1/R2 候选表本体，条目含 known_impl/kb_links 实测指针），按算子族命中行核对 §1.6.0——① 候选覆盖（命中行候选是否全部评估、基线是否在表）；② 负向断言（"无在线变体/无化简公式/无更低复杂度算法"）逐条复核（对照候选表、源码证据、同类案例）；③ 复杂度表独立复算（重点：中间缓冲的 GM 往返是否漏计、口径是否自洽）；④ 亲和性淘汰依据核对（与弃选论证查证同口径；容量/带宽淘汰引用 constants.md 条目）；⑤ 互联网来源核对（若 §1.6.0 引用了互联网候选）：来源记录（URL/论文/仓库 + 访问日期）齐全，「有候选无来源记录」按证据缺失处理（同弃选论证查证口径）；不要求重新访问验证内容真实性。复核发现矛盾或漏候选 → 维度 8 fail 并附证据（候选表条目 / 源码语句 / 案例路径）。
7. 机械复核（D-1/D-5，强制——可机检部分不由 LLM 复核替代）：
   • 重跑等价性验证（DESIGN.md §1.6.1 含采纳优化项时）：python examples/{project}/{op}/verify_equiv.py——执行结果须与 §1.6.1 内嵌结果表一致且全部 EQUIV_PASS；脚本缺失、执行失败或与内嵌表不一致 → 维度 8 fail（等价性机器验证失效）；
   • 算术复算：python3 .agents/tools/design_calc_check.py --design <path>——逐项消费其 JSON 输出：ub/l1/l0c_budget fail → 维度 2 fail（VP-2026-0009 混合字节口径类错误由此拦截）；core_split fail → 维度 3 fail；r3_metrics fail → 维度 8 fail；skip 项（无法机械解析）转为人工复核并在维度内注明"机械跳过，人工已核"；
   • 两项机械结果摘要（含 skip 项）附入 REVIEW.md「机械复核」段——与维度 8 的"独立推演"互补而非替代。

Phase 2：逐维度检视

按 §3 的维度逐项检查（迁移任务 0–8，非迁移任务 1–8），每项标记 pass / warn / fail 并记录证据（DESIGN.md 章节号 + 源码证据 + 引用文件）。

Phase 3：结论判定

Phase 4：生成 REVIEW.md

按 §5 模板写入 examples/{project}/{op}/REVIEW.md。

Phase 5：任务复盘（Retrospective，自进化钩子）⭐

REVIEW.md 结论给出后（通过与不通过均写），向 examples/{project}/{op}/RETROSPECTIVE.md 追加复盘章节（先 Read 既有内容，整文件写回，只追加不覆盖历史章节）：

• 章节模板与字段规范（canonical）：tilelang-skill-evolution skill 的 references/retrospective-schema.md。两个标准表（Skill Flow Issues / Value Point Proposals）+ Transferable Lessons 小节。
• 复盘对象是检视流程自身，不是设计内容（设计问题已随 REVIEW.md 流转给 Stage 1，不得重复抄入复盘）：
  • 本次检视中发现自己无法核验的点（如某 API 文档缺失、某代价机制无实测数据可对照、pattern-library 未覆盖的关键常数）→ Skill Flow Issues；
  • 现有维度表无法覆盖的检查项缺口（如新的弃选论证错误形态、新的迁移源码陷阱）→ Value Point Proposals（P/R 类，target_doc 指向本 skill）；
  • 检视过程中亲手查证到的新 API 行为/代价实证（打开文档核对时发现的限制条款与实测矛盾）→ D 类（须带三件套）。
• 质量红线：无则如实写 none；单任务偶然现象不得写成通用规则。

5. REVIEW.md 模板

# {op} 设计文档检视报告

## 检视结论

结论: 通过
<!-- 或：结论: 不通过 -->

## 检视元信息
- 文档: examples/{project}/{op}/DESIGN.md
- 任务类型: 迁移 / 新算子开发
- 源算子: {source_op_path，仅迁移任务}
- 检视维度: {迁移任务：9 项（源算子理解与迁移分析 / API 可行性 / 内存层级 / Tiling / 技术约束 / 循环同步 / 验证方案 / 完整性 / 算法优化分析）；非迁移任务：8 项}
- 阻塞级问题数: {N}
- 建议级问题数: {N}

## 机械复核（D-1/D-5）

- verify_equiv 重跑: {PASS/EQUIV_FAIL/脚本缺失/不适用（无采纳优化项）——执行结果与 §1.6.1 内嵌表一致性结论}
- design_calc_check: {逐项粘贴 JSON checks 摘要（ub/l1/l0c_budget、core_split、r3_metrics 各 pass/fail/skip + 一句 detail；skip 项注明人工复核结论）}

## 检视详情

### 0. 源算子理解与迁移分析 — pass / warn / fail / n/a
{仅迁移任务输出本节；n/a 用于非迁移任务。说明与证据须包含：语义核对结论、算法步骤覆盖核对结论、优化手段识别核对结论、耦合性判定抽检结论、重设计可行性结论、§1–§7 与迁移决策一致性结论、golden 独立性结论}

### 1. API 可行性 — pass / warn / fail
{说明与证据}

### 2. 内存层级规划 — pass / warn / fail
{说明与证据}

### 3. Tiling 策略 — pass / warn / fail
{说明与证据}

### 4. 技术约束检测 — pass / warn / fail
{说明与证据}

### 5. 循环与同步 — pass / warn / fail
{说明与证据}

### 6. 验证方案 — pass / warn / fail
{说明与证据}

### 7. 完整性与一致性 — pass / warn / fail
{说明与证据}

### 8. 算法优化分析 — pass / warn / fail
{说明与证据须包含：§1.6 章节存在性、算法调研存在性与完整性（四问覆盖、基线候选、复杂度四口径核对结论）、调研结论正确性独立复核结论（等价性推演、复杂度复算、负向断言对照参考表复核、并列候选裁决路径）、调研→设计一致性（§1.4/§3.1/§6 与选定算法、迁移任务 §0 处置一致性与优化意图承接）、数学等价优化完整性（四要素逐项核对）、等价性论证独立推演结论、向量化替代覆盖完整性（与 §3.3/§6 交叉核对）、不可替代理由充分性结论、替代 API 佐证结论、向量化轴与布局决策完整性（候选矩阵/量化评分/弃选理由核对结论）、布局决策与 §3.3/§4/§6 一致性结论、与 §3.1/§6 一致性结论}

## 检视问题列表
<!-- 仅当「结论: 不通过」时出现本章节；通过时删除本章节 -->

### 问题 1: {问题标题}
- 严重程度: 阻塞 / 建议
- 位置: DESIGN.md §{X.Y}
- 问题描述: {具体描述；迁移类问题附源码证据（源码语句/行）}
- 修改建议: {可执行的修改建议，供 Stage 1 revision 使用}

### 问题 2: ...

6. 输出规则

1. REVIEW.md 必须写入 examples/{project}/{op}/REVIEW.md。
2. 结论行必须是字面量 结论: 通过 或 结论: 不通过（conductor 据此判定路由），不得用"基本通过"、"建议通过"等模糊表述。
3. 不通过时，每个阻塞级问题必须给出可执行的修改建议，作为 Stage 1 revision 模式的 design_error_summary 输入。
4. 通过时不得出现"检视问题列表"章节。
5. 不得修改 DESIGN.md。

7. 错误处理