【合入来源】

如有社区issue，请关联issue链接
请勿携带内部流程信息（需求链接、问题单、内部issue等）

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

Fixes https://gitcode.com/Ascend/pytorch/issues/3471

【修改方案】

请描述修改内容的具体实现，涉及哪些组件之间进行交互，可以用1、2、3、...进行罗列
如果是需求或者重构类的PR，需要补充详细设计文档（说明上下游组件关系、时序图、类图、DFX能力等内容）

1. 新增 NPU Inductor Python Wrapper Planned Fast Launch 实验模块，并通过 TORCHINDUCTOR_NPU_FAST_LAUNCH 环境变量控制启用，默认关闭。
2. 在 NPU Triton backend 初始化阶段调用 patch_fast_launch()，运行时 patch NPUPythonWrapperCodeGen 的初始化、Triton header 和 kernel call 生成逻辑，以及 TritonCompileResultNpu.make_launcher()；patch 支持重复调用幂等，并在批量属性替换失败时回滚已应用的修改。
3. 对 triton=True、非 C++ Wrapper、非 graph partition 子图且未启用 compile-time autotune 的 callsite 生成 metadata 和单槽调用缓存；首次调用惰性绑定，普通 autotuner 创建 BoundFastLaunch，grouped autotuner 直接缓存原 autotuner.run。C++ Wrapper、graph partition 子图、非 Triton kernel 和 compile-time autotune 继续使用原生成路径。
4. 在保留原 Triton launcher 的基础上附加 kernel name、kernel stub 及 owner、最终 ABI 参数类型、动态 grid resolver、SIMT/shared memory、FFTS 和隐藏资源需求等元数据；元数据提取失败时保留原 launcher 行为。
5. 新增 launcher 稳定性判断和运行时路由：普通 autotuner 必要时先通过原 NPUCachingAutotuner.run 完成 autotune、coordinate descent 和 store cubin 生命周期，再将唯一且稳定的 best launcher 提升为 PlannedFastLaunch；grouped autotuner 继续使用其自身的原 autotuner.run 完整入口；profiler、benchmark_run、runtime kwargs、dump_fx_graph、check_accuracy、triton_interpret、dump_launch_params 等普通 autotuner 完整入口场景继续使用原 NPUCachingAutotuner.run。plan 已建立后如检测到活动 launch hook，仅本次调用已选中的原 launcher，hook 清空后恢复 planned path。
6. 新增 schema/ABI、参数类别、stream、grid、workspace、sync lock、device print、FFTS 和 backend 可用性校验；不支持的稳定 launcher 使用负缓存并复用原 launcher，动态 grid 等单次可恢复错误回退原路径，进入 C++ backend 后的异常不重放 kernel，避免重复提交。
7. 新增 C++ FastLaunchPlan 及 pybind11 内部接口：创建 plan 时保存 kernel name、kernel stub 的 Python 引用和裸指针、归一化 ABI 参数类别、SIMT/shared-memory、force-SIMT 与 FFTS 状态/地址，并预计算隐藏字段、参数字段和 grid 字段的 offset 及 packed buffer 总长度；Python 侧通过 plan._owner 额外持有产生 stub 的 binary owner。每次调用不复用参数缓冲区，而是新建 PackedLaunch：当前 stream 单独保存为 rtStream_t，并依据当前 grid 和 canonical args（Tensor data_ptr、标量及 best_runtime_blocks 补入参数）重新分配和填充 packed args buffer；非 SIMT 分支调用 rtKernelLaunch，SIMT 分支在提交时检查并调用弱符号 rtKernelLaunchWithFlagV2，均经 OpCommand.SetCustomHandler(...).Run() 提交。
8. 通过 torch_npu/csrc/inductor/CMakeLists.txt 将 fast launch C++ 源文件纳入 INDUCTOR_SRCS；该实现仅在非 BUILD_LIBTORCH 的 CPython 扩展构建中编译生效，并在 torch_npu._C 初始化时注册内部类型 _NPUInductorFastLaunchPlan 及 _npu_inductor_make_fast_launch_plan、_npu_inductor_fast_launch_with_plan 两个内部函数。
9. 新增 Python 单元测试、patch/回滚测试和静态结构测试，覆盖默认关闭、代码生成路由、launcher promotion、schema 冲突、负缓存、动态 grid、profiler、FFTS、隐藏资源、backend 异常及 C++ packed layout 等场景。

组件交互链路：

torch.compile → NPU Triton backend 初始化 →（环境变量开启时）patch_fast_launch → Python Wrapper codegen/launcher metadata → callsite 首次调用惰性绑定。

• grouped autotuner 继续执行其自身的原 autotuner.run；普通 autotuner 的 full-entry 场景继续执行原 NPUCachingAutotuner.run。
• 普通场景进入 BoundFastLaunch，必要时先执行原 NPUCachingAutotuner.run 完成 autotune/coordinate-descent/store-cubin 生命周期，再由 build_planned_fast_launch 调用 torch_npu._C._npu_inductor_make_fast_launch_plan 创建 C++ plan，并在 Python 侧封装为 PlannedFastLaunch；稳态调用通过 torch_npu._C._npu_inductor_fast_launch_with_plan → OpCommand.SetCustomHandler(...).Run() → rtKernelLaunch/rtKernelLaunchWithFlagV2 提交。不满足 plan 条件的调用继续使用原完整入口或原 launcher。

【资料变更】

请确认是否涉及资料变更。如涉及，需要在PR中体现，并简要说明修改内容。如不涉及，需填写“不涉及”

涉及。

新增 torch_npu/_inductor/docs/npu_inductor_fast_launch_zh.md，说明 Planned Fast Launch 的功能边界、前置条件、环境变量启用方式、最小示例、launcher 生命周期、ABI 支持范围、plan 创建条件、grid/stream 校验、回退与负缓存行为，以及关闭和故障处理方法。

【接口变更】

请确认是否涉及跨代码仓或者客户面可见的接口变更。如涉及，需要详细说明接口以及对应的变更内容，同时需要在资料中体现。如不涉及，需填写“不涉及”

涉及。

1. 新增用户可见环境变量 TORCHINDUCTOR_NPU_FAST_LAUNCH，默认关闭；值经去空白并忽略大小写后为 1、true、yes、on 或 y 时启用。该变量须在首次加载 NPU Triton backend 前设置，推荐在导入 PyTorch/torch_npu 前设置；运行中修改不会补装或撤销 patch，需要重启 Python 进程并重新编译 Wrapper。
2. 在非 BUILD_LIBTORCH 的 torch_npu._C Python 扩展中新增 3 个内部 Python 可见符号（均非用户 API）：
   • _NPUInductorFastLaunchPlan：无公开构造器，作为 plan 的内部持有类型；
   • _npu_inductor_make_fast_launch_plan；
   • _npu_inductor_fast_launch_with_plan。
3. FastLaunchPlan 位于 C++ 匿名命名空间，不新增客户可直接调用的 C++ plan API；现有模型代码及 torch.compile(..., backend="inductor") 调用方式不变。

【功能验证】

说明测试场景，测试方法。如果本次测试方式与常规单元测试不同，请详细说明您的测试步骤
新增/变更内容是否已新增/适配UT测试用例看护，并补充测试自验证截图

已新增以下 UT 看护：

1. test_npu_fast_launch.py：覆盖环境变量关闭、codegen schema 完整/不完整、plan 生命周期与 binary owner、FFTS ABI、隐藏资源拒绝、warmup 后 promotion、负缓存、profiler、launch hook metadata、动态 grid、backend 异常不重放、launcher 变化和 runtime block 参数等场景。
2. test_npu_fast_launch_patch.py：覆盖默认关闭时不解析 patch 目标、patch 只安装一次、代码生成路由、launcher metadata 附加，以及 patch 操作失败后的逆序回滚。
3. test_npu_fast_launch_static.py：覆盖 fast launch 仅通过 runtime patch 接入、package lazy import、C++ backend 保留 OpCommand 和运行时校验、仅暴露 planned launch 接口，以及 packed argument layout 预计算。

本地执行：

python -m unittest discover -s test/_inductor/experimental/python_wrapper_fast_launch -p "test_*.py" -v

执行结果：共 30 个测试，全部通过。
当前自验证为隔离单元测试和静态结构测试，未执行 NPU/CANN 实机功能及性能测试。
当前 HEAD 已通过文档门禁（markdownlint、链接有效性、资源存在性和标签闭合检查）；本次推送后尚未确认完整 PR CI。

【CheckList】
PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常（当前 HEAD 尚未确认完整 PR CI）