feat(diagnostics): add Triton Anchor compile diagnostics

[skwmw01]

背景

当前 Triton / Sophgo 算子编译失败时，报错信息长且难以定位到具体 pass、MLIR
op 或阶段。该 PR 增加 Triton Anchor 诊断能力，用于在编译失败时快速定位问
题。

主要变更

• 新增 PassDiagnostic，支持 TTIR、triton-linalg、sophgo-pplir 逐
  pass 诊断。
• 新增 triton-anchor-diagnose CLI，并注册为 console_scripts entry
  point。
• 支持三类入口：
• 已有 .ttir/.mlir 文件诊断
• --python 辅助模式生成 TTIR 后诊断
• TRITON_ANCHOR_DIAGNOSE_ON_ERROR=1 python your_kernel.py 自动 hook 真
  实编译链路
• Sophgo 后端在 TTIR / Linalg / PPLIR / ppl-compile / CMake / .so /
  runtime launch / result mismatch 失败时自动输出诊断。
• 增加失败样例、单测和文档。

验证

• python -m pytest python/triton_anchor/tests/test_diagnostics.py -q
• 运行失败样例可定位到具体 pass / stage / location / op。

兼容性

• 默认不开 TRITON_ANCHOR_DIAGNOSE_ON_ERROR 时不影响正常编译流程。
• 诊断输出仅在失败或显式开启时生成。
• 本 PR 不包含编译产物、诊断日志、临时输出目录。

[github-actions]

Codex AI 自动审查

Codex AI 自动审查仅供参考且不阻塞合入；本地确定性 CI 检查结果才是合入门禁。

审查摘要

• Codex AI 审查结论：警告
• 本地确定性 CI 检查：已通过；Codex AI 自动审查只提供补充意见，不改变门禁结果。
• 合入建议：修复自动 hook 缺失后再合入，并在实际 Sophgo JIT 中复测至少一个 pass 失败和一个外部阶段失败；其余 CLI 核心功能和本地确定性 CI 检查通过，但当前证据不能支持自动诊断承诺。

本次变更新增了可运行的逐 pass 诊断核心、CLI、公共导出和打包入口。定向验证确认 TTIR 成功、非法 IR parse 和 Python frontend 失败均能生成预期诊断，本地确定性 CI 检查也成功完成构建、安装和既有冒烟测试。主要缺陷是贡献者声明的 Sophgo JIT 自动 hook 没有出现在实际 diff 或调用链中，导致环境变量对常规 JIT 编译无效。

贡献者目标与实现情况

• 判断：部分实现
• 贡献者目标：为 Triton Anchor 编译失败提供逐 pass/逐阶段诊断 CLI，并在 Sophgo JIT 失败时按环境变量自动输出诊断产物。
• 预期效果：用户可通过 CLI 诊断已有 IR 或 Python kernel；设置 TRITON_ANCHOR_DIAGNOSE_ON_ERROR=1 后，真实 Sophgo JIT 在 TTIR、Linalg、PPLIR、ppl-compile、CMake/.so、运行时和结果不匹配失败时自动输出对应诊断，默认关闭时不改变正常编译。
• 当前实现情况：显式 CLI 和逐 pass 诊断核心已实现并可运行，公开导出和安装入口已同步；但实际 diff 未将环境变量和诊断对象接入真实 Sophgo JIT、运行时或结果比较路径，因此自动诊断及其宣称的阶段覆盖未实现。
• 判断依据：
  • FILE-007 和 FILE-008 实现了文件输入、--python 输入、TTIR/triton-linalg/Sophgo PPLIR 逐 pass 诊断及结构化 summary。
  • FILE-010 注册了 triton-anchor-diagnose console_scripts，本地确定性 CI 检查已成功构建并安装 wheel。
  • 仓库内对 TRITON_ANCHOR_DIAGNOSE_ON_ERROR 的非文档引用仅出现在三个故障样例；真实 Sophgo JIT 编译链路未调用 PassDiagnostic 或 StageDiagnostic。
  • FILE-001 和 FILE-002 声称真实 Sophgo JIT 会自动覆盖多个失败阶段，但这些后端、运行时和测试 hook 不在本次 diff 中。

需要处理的问题

1. [中风险] 环境变量未接入真实 Sophgo JIT 编译链路

• 问题类型：正确性错误
• 代码定位：docs/diagnostics.md:204
• 这段代码负责：向用户承诺真实 Sophgo JIT 失败会自动触发诊断的接口契约。
• 核心证据：本次 diff 只新增 CLI、诊断类和手工调用诊断 API 的故障样例。仓库搜索显示 TRITON_ANCHOR_DIAGNOSE_ON_ERROR 的非文档引用仅在三个样例中；FILE-006 仅导出诊断类，FILE-007 仅在显式 CLI 调用时创建 PassDiagnostic。已检查的 Sophgo JIT stage 注册仍直接调用原 TTIR、Linalg、PPLIR 和 so 函数，未读取该环境变量或调用诊断对象。
• 影响：用户设置环境变量后，常规 fngrid 编译失败仍只得到原始错误，不会生成所承诺的失败 pass/stage、IR 快照或 summary.json；ppl-compile、CMake/.so、runtime 和结果不匹配诊断同样不可达。
• 建议：在实际 Sophgo 编译、runtime launch 和结果比较错误路径中读取环境变量并调用诊断 API，保留原始异常语义；为每个自动捕获阶段添加真实 JIT 集成测试。若这些改动不属于本 PR，应删除自动 hook 与外部阶段覆盖的声明。

可点击代码定位

链接固定到本次测试提交，便于提交者修复和审核者核对代码功能；已验证行号的问题链接到具体行，仅能确认文件的问题链接到文件并标注行号待核对。

• 问题 1：docs/diagnostics.md:L204

验证情况

• 验证内容与结果：
  • 本地确定性 CI 检查在合并提交上成功完成前端构建、wheel 安装、冒烟、后端 smoke、FlagGems 采样和编译性能检查。
  • 新增诊断单测 11 项全部通过。
  • 真实 CLI --python 成功路径执行了 TTIR 7 个 mandatory passes，并生成逐 pass 快照和 summary。
  • 真实 Python frontend 故障样例与非法 MLIR 输入均生成对应 pre-pass 诊断文件。
  • 静态调用链审查确认 TRITON_ANCHOR_DIAGNOSE_ON_ERROR 未被真实 Sophgo JIT 生产路径消费，足以确认自动 hook 功能缺失。
  • Codex 执行的验证或诊断命令执行失败，现有记录尚不足以完成稳定性或根因归因。
  • 验证新增诊断核心和 CLI 单元行为执行成功。
• 限制与未覆盖：
  • 失败记录尚不足以完成稳定性或根因归因。
  • 尚未执行：在真实 Sophgo fngrid 编译中设置 TRITON_ANCHOR_DIAGNOSE_ON_ERROR=1，分别强制 TTIR/Linalg 或 PPLIR pass 失败，断言自动生成 summary、失败 pass 和 before IR。
  • 尚未执行：对 ppl-compile 非零退出、CMake/.so 失败、runtime launch 异常和 assert_close 不匹配分别注入可控故障，断言 StageDiagnostic 的命令、返回码或上下文摘要被写入。
  • 尚未执行：在具备可加载 Sophgo 后端绑定的环境中运行 FILE-005，确认真实 sophgo-pplir pass 失败的 location/op 映射与 summary 内容。

剩余风险

• 未在当前环境实际执行 Sophgo PPLIR、ppl-compile、CMake/.so、runtime launch 或结果不匹配的诊断路径；这些路径当前也没有本次 diff 中的自动 hook 集成。

变更文件

查看变更文件

文件	类型	改动说明	影响
docs/diagnostics.md	新增	新增面向用户的诊断使用文档，描述 CLI、诊断产物和多个 Sophgo 自动诊断阶段。	向用户承诺 CLI 与真实 Sophgo JIT 自动诊断能力；其中自动 hook 的说明会误导实际编译失败排查。
ops-diagnose-cli/docs/T2.1-implementation-and-test-results.md	新增	新增实现和测试结果文档，记录诊断模块、故障样例及声称的 Sophgo 自动 hook 集成。	作为实现与测试记录，宣称外部 Sophgo 后端、driver 和测试断言已经接入；该记录扩大了本次 diff 实际未覆盖的能力范围。
ops-diagnose-cli/test/anchor_diag_bad_frontend_kernel.py	新增	新增使用不存在 Triton builtin 的 frontend 故障 kernel，并在环境变量开启时手工调用 CLI。	提供 Python frontend 失败的可执行示例，验证显式诊断入口可写出 pre-pass 诊断。
ops-diagnose-cli/test/anchor_diag_bad_kernels.py	新增	新增 inline asm 故障 kernel，手工依次运行 TTIR 与 triton-linalg 逐 pass 诊断。	提供 triton-linalg lowering 失败样例，但它在脚本内直接构造并运行 PassDiagnostic，不验证真实 JIT 自动 hook。
ops-diagnose-cli/test/anchor_diag_bad_pplir_kernel.py	新增	新增 C 维 broadcast PPLIR 故障 kernel，手工运行 TTIR、triton-linalg 和 sophgo-pplir 诊断。	提供 Sophgo PPLIR 失败样例和方言加载辅助逻辑，但同样是显式调用诊断 API，不覆盖正常 JIT stage 的自动捕获。
python/triton_anchor/__init__.py	修改	从包顶层导出 PassDiagnostic 和 StageDiagnostic。	使新增诊断类成为包顶层公共 API，但不会自行注册或启动 JIT 错误 hook。
python/triton_anchor/diagnose.py	新增	新增 triton-anchor-diagnose CLI，支持 IR 文件和 --python 输入、三种 pipeline 选择及 pre-pass 诊断写入。	提供可安装 CLI 的参数解析、输入加载、前端错误产物和退出码约定。
python/triton_anchor/diagnostics.py	新增	新增 PassDiagnostic、StageDiagnostic、TTIR/triton-linalg/Sophgo PPLIR pass descriptor 与 stderr 捕获实现。	实现逐 pass 快照、首个失败记录、位置提取和外部阶段诊断数据结构，是 CLI 的核心功能；其 API 仅由显式调用方使用。
python/triton_anchor/tests/test_diagnostics.py	新增	新增 11 个诊断单元测试，主要通过 fake libtriton 和 fake Sophgo passes 验证逐 pass 结果与 CLI 输出。	覆盖诊断核心的模拟 pass、位置提取、CLI 成功和 pre-pass 错误路径，但未覆盖真实 Sophgo JIT hook 或外部阶段失败。
setup.py	修改	新增 triton-anchor-diagnose console_scripts 注册。	安装 wheel 后会暴露 triton-anchor-diagnose 命令，同时保留原 adapter entry point。

---

• 测试提交：bde050a0bdf0
• Codex 自动审查状态：完成；结论：警告
• 查看完整 Codex AI 自动审查报告