AKO4PTO：CANN PTO 算子 Agentic 调优工作区与迭代方法论全指南-平芜编程栈

AKO4PTO：CANN PTO 算子 Agentic 调优工作区与迭代方法论全指南

【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址: https://gitcode.com/cann/pto-isa

导读：本文围绕当前仓库中agents/skills/pto-costmodel-agentic-kernel-optimization/技能包，系统讲解面向 PTO（Parallel Tile Operation）算子的 Agent 自动调优方案 AKO4PTO。你将掌握一套「多项目隔离工作区 + 一轮一假设 + 瓶颈分类 + 远程 Ascend benchmark + 逐轮留痕」的完整调优工程方法论，覆盖 PTO-DSL（Python）与 PTO-tile-lib（C++）两种算子形态，并学会如何联动 costmodel 指令级 cycle 仿真指导参数搜索、如何按固定协议记录迭代并生成总结图表。

1. AKO4PTO 是什么：一套为"Agent 调优"设计的多项目工作区

AKO4PTO（Agentic Kernel Optimization for PTO）是 CANN pto-isa 仓库中用于PTO 算子性能调优的多项目工作区。它不是一个自动改代码的"黑盒工具"，而是一套流程化、可留痕、可复现的调优工程框架，专门面向 Agent（LLM 驱动）或人工开发者对 Ascend 上的 PTO kernel 做迭代式性能优化。

其设计目标明确写在 README.md 中：

不污染原始pto-kernels目录——原始代码只读，所有修改都在隔离副本中进行；
不同算子使用独立项目目录——每个算子一个项目，互不干扰，便于对比和回滚；
在各自项目的隔离副本中修改代码——workspace/下存放可编辑副本，原目录保持纯净；
通过远程 Ascend 环境做 benchmark 验证——性能数据必须在真实硬件上跑出来，而不是靠理论推断；
对每一轮调优保留完整记录——runs/iter-XXX/存档 files.txt、patch.diff、notes.md，任何一轮都可回溯。

1.1 目录结构说明

AKO4PTO/ ├── projects/ # 每个算子一个独立项目目录（运行时按需创建） ├── project_template/ # 新建算子项目时复制的模板（已入库，见下文） ├── task.md # 所有项目共用的任务流程（优化规则与迭代协议） ├── remote.md # 共享的远程登录、同步、执行 benchmark 流程 ├── context/ # 可选的共享参考资料 └── README.md # 工作区总说明与最小使用流程

模板目录 project_template/ 已在仓库中固化，包含：

模板文件	作用
TASK_REQUIREMENTS.md	记录当前任务的附加要求（默认 shape、优先规模、禁改文件、行为约束、关注指标）
ITERATIONS.md	每轮追加一行的简约摘要表（Iter / Hypothesis / Changes / Baseline / PTO / Correct / Result）
runs/_template/notes.md	单轮详细记录模板（Pre-Edit / Changes / Post-Run / Analysis / Next）
runs/_template/files.txt	本轮修改文件列表模板
workspace/README.md	工作区使用原则：只在这里改代码，不直接改原始`pto-kernels`，一个项目只服务一个算子

1.2 建议阅读顺序

README.md → task.md → remote.md → project_template/。即：先理解工作区哲学，再理解任务流程，再理解远程环境准备，最后看模板如何落地。

2. 最小使用流程：五步跑通一个算子项目

按 README.md 的"最小使用流程"，为一个算子建立可调优项目只需 5 步：

为当前算子在projects/下创建一个独立项目目录；
从project_template/复制TASK_REQUIREMENTS.md、ITERATIONS.md、workspace/、runs/、context/；
将原始pto-kernels复制到projects/<operator_name>/workspace/pto-kernels；
具体执行统一按顶层task.md，远程连接和环境配置按remote.md；
在项目自己的workspace/pto-kernels中修改代码，每轮结束后把记录写入runs/iter-XXX/并同步更新ITERATIONS.md。

使用 Agent 自动寻优时：用户进入 AKO4PTO 根目录后，直接让 Agent 按顶层task.md行事即可，无需手工创建目录——task.md 第 4 步要求 Agent自动创建项目工作区。

3. 与 costmodel 的联动：用指令级 cycle 仿真指导优化

AKO4PTO 不是孤立运行，它依赖同级 skillpto-costmodel-query-pto-cycles（见 SKILL.md），在优化迭代中查询单条 PTO ISA 指令的仿真 cycles：

python3 tools/query_pto_cycles.py TMATMUL half half float --m 128 --k 64 --n 128 # => [CYCLE] TMATMUL.float<half,half>_128x64x128 actual=262

该 skill 的能力边界要清楚：

支持：单条 PTO ISA 指令级 cycles 仿真（TMATMUL、TADD、TEXP 等），纯 CPU 运行，不需要真实硬件；
不支持：算子级（多指令组合）仿真。

在 AKO4PTO 迭代中的典型用法：

对比不同 tile 参数下的指令 cycle 开销；
验证优化假设（如"更大 tile 的 TMATMUL 每 FLOP cycle 更低"）；
指导参数搜索方向，减少盲目试错。

其底层原理可从源码得到印证：当编译时定义__COSTMODEL宏后，pto-inst.hpp 会自动将所有 PTO 指令替换为 costmodel 版本，指令执行时通过 trace.hpp 中的BeginPtoInstr/EndPtoInstr记录周期，用户通过GetLastPtoInstrCycles()查询（trace.hpp 中ResetTrace与GetLastPtoInstrCycles的实现）。目前 costmodel 仅支持 A2/A3 平台（__NPU_ARCH__=2201），仿真结果仅反映该平台性能特征。仓库还提供了 pipeline 级算子仿真工具 Perf-Sim（见 perf-sim-user-guide_zh.md），用于评估 kernel 的 pipeline 利用率与总周期。

4. 适用范围：PTO-DSL 与 PTO-tile-lib 双场景

task.md 明确本技能适用于PTO-DSL（Python）和PTO-tile-lib（C++）两种场景，两者的构建、调参、benchmark、正确性判定方式完全不同：

维度	PTO-DSL (Python)	PTO-tile-lib (C++)
构建方式	Python JIT（`wrapper._build()`）	CMake +`make -j16`+ Bisheng
调参方式	Python 环境变量 / kernel 参数	C++ 模板参数、`.h`常量、`.cpp`内部参数
Benchmark	Python benchmark 脚本 →`report.json`	编译二进制 →`report.csv`（duration_us, TFLOPS）
代码位置	`workspace/pto-kernels/`下`.py`	`workspace/kernel/`下`.cpp`/`.hpp`
正确性	`report.json`中`correctness.passes`	内置`ResultCmp`输出 "test success"/"test failed"
典型算子	`flash_attention_score`、`ffn`等	`fa_performance`等

Agent 会根据用户提供的算子源码自动判断场景：

含.pykernel 定义 +pto_kernels/ptodsl相关导入 →PTO-DSL；
含CMakeLists.txt+.cpp/.hpp+ PTO tile 宏 →PTO-tile-lib。

判断后需向用户确认结果。

5. 首要原则：瓶颈驱动的硬件优化，而非代码整理

task.md 开篇即强调：PTO 算子优化不是通用代码整理，而是面向硬件的瓶颈消除过程。

每一次优化动手前必须能回答四个问题，否则不要改代码：

当前瓶颈是什么；
为什么这个改动能在 Ascend 上有效；
预期改善哪个指标；
如何保证正确性。

一个好的 PTO 优化是：正确的、可衡量的、可重复的、瓶颈驱动的、有硬件依据的、足够可维护以保留下来。不追求巧妙、复杂或理论上优雅。

6. 主流程：从确认算子到收尾的八步

task.md 规定按以下顺序执行：

步骤 1：确认优化算子

必须向用户确认要优化的算子：用户直接给出源码路径，或 Agent 扫描已知路径列出候选。确认后快速浏览源码并自动判断 DSL/tile-lib 类型，向用户确认判断结果。

步骤 2：确认优化 Case

必须确认具体 case 配置：Shape（如S=32768, HEAD_SIZE=128, BATCH=1）、Dtype（如float16、bfloat16）、是否 causal mask 及其他特殊配置。多 case 时列出可选项让用户选择。

步骤 3：确认远程环境和 Costmodel

确认三点：远程服务器连接方式（使用哪个 connect skill）；是否使用 costmodel 及其工具路径；算子在远程的部署路径（如果已有）。

步骤 4：自动创建项目工作区

Agent 自动执行，无需用户手动操作：

# 从 project_template/ 复制基础结构 mkdir -p projects/<operator_name>/ cp -r project_template/* projects/<operator_name>/ # 创建必要目录 mkdir -p projects/<operator_name>/{context,runs,workspace} # 复制算子源码到隔离工作区 # PTO-DSL: 复制到 workspace/pto-kernels/ # PTO-tile-lib: 复制到 workspace/kernel/ cp -r <source_path> projects/<operator_name>/workspace/<pto-kernels|kernel>/

创建完成后自动生成TASK_REQUIREMENTS.md（含算子名、case 配置、可调参数等），并向用户确认是否需要修改context/参考资料与TASK_REQUIREMENTS.md。

步骤 5：读取任务上下文

开跑前阅读TASK_REQUIREMENTS.md、context/、远程连接 skill 及workspace/下所有目标算子源码，至少明确下表信息：

维度	PTO-DSL	PTO-tile-lib
入口函数	kernel spec 路径	入口模板函数（如`LaunchTFA<...>`）
可调参数	Python 环境变量 / kernel 参数	C++ 模板参数 /`.h`常量 /`.cpp`内部参数
benchmark 命令	Python benchmark 脚本	`./fa_performance --npu=0 --cases="..."`
正确性判定	`report.json`中 passes 字段	"test success" / "test failed"
性能指标	`report.json`中 duration_ms / TFLOPS	`report.csv`中 duration_us / TFLOPS
构建命令	`wrapper._build()`	`cmake + make -j16`

步骤 6：打通远程链路

远程环境首次接入时，第一优先级不是调优，而是把环境带到"可以稳定跑 benchmark"。满足以下 gate 才进入真正的性能迭代：

PTO-DSL：

SSH 连接成功；
远程工作目录已建立，隔离工作区已上传；
已确认远程 Python 路径和版本；
至少成功跑出一份有效report.json，确认 baseline 和 pto 都 benchmark ok + correctness passes。

PTO-tile-lib：

SSH 连接成功；
远程工作目录已建立；
远程已安装 Bisheng 编译器、CANN、ACL runtime；
至少成功完成一次完整构建（cmake + make）；
至少成功跑出一份有效结果：构建无错误 + "test success" +report.csv有有效数据。

任一项不满足，本轮视为"环境打通轮"，优先修环境，不要急着改 kernel。

步骤 7：跑 torch_npu Baseline

优化迭代开始前必须先跑一份 PyTorch 标准实现（如torch.nn.functional.scaled_dot_product_attention）的 baseline 性能数据，作为最终对比参照：

使用与优化 case 相同的 shape、dtype 配置；
至少 warmup 5 次 + 10 次计时；
记录 avg、min、max duration 和 TFLOPS；
记入ITERATIONS.md的 torch_npu baseline 部分。

步骤 8：进入性能迭代

每次新会话开始调优前必须：了解当前最佳结果、了解最近失败的假设、从当前已知最佳状态继续而非盲目从头开始，并参考context/和TASK_REQUIREMENTS.md，然后按下面的优化规则与迭代协议执行。

7. 构建与运行流程

7.1 PTO-DSL（Python）

# 构建 python3 -c "from pto_kernels import <kernel>; wrapper._build()" # Benchmark python3 bench_<kernel>.py --case "<shape_config>"

7.2 PTO-tile-lib（C++）

# 构建 cd workspace/kernel/ rm -rf build && mkdir build && cd build python3 ../scripts/generate_cases.py --cases "<case_config>" --qk-preload <N> cmake -DRUN_MODE=npu -DSOC_VERSION=Ascend910B1 .. make -j16 # Benchmark python3 ../scripts/gen_data.py --cases "<case_config>" ./fa_performance --npu=0 --cases "<case_config>"

8. 优化规则：让每一轮迭代有纪律、有依据

8.1 一轮一假设

每轮迭代只测试一个假设，所有代码/参数修改必须服务于同一个假设。多改动混在一起会让结果无法归因。

8.2 正确性先于性能

每轮严格按顺序：修改代码/参数 → 构建 → 跑正确性测试 → 只有通过后才跑性能测试。

正确性不通过 → 性能结果无效，记录并终止本轮；
不允许放宽容差（除非用户明确批准）；
不允许修改 benchmark workload 或验证逻辑来"提分"。

8.3 可编辑范围

默认只允许修改算子 kernel 源码和紧密相关的参数配置。除非明确有 bug，否则不得修改 benchmark 脚本、运行 harness、测试逻辑、正确性阈值、workload shapes。永远不要通过让 benchmark 变简单来"提分"。

8.4 强制瓶颈分类

每次改代码之前，必须将当前瓶颈归类为以下之一：

类别	说明
GMEM traffic bound	全局内存带宽瓶颈
UB / tile buffer pressure	UB 缓冲压力
small-transfer inefficiency	小包传输低效
compute under-utilization	算力利用不足
AIC/AIV imbalance	Cube/vector 不平衡
pipeline bubble / poor overlap	流水线气泡 / overlap 不足
barrier / wait / sync overhead	同步开销过大
register pressure / occupancy loss	寄存器压力 / 占用率下降
bad tile shape	tile 形状不佳
dependency chain too long	依赖链过长
CV FIFO pressure	Cube-Vector FIFO 拥塞
unknown	未知——必须先检查代码和 profiling 数据

8.5 Ascend 硬件检查清单

每轮开始前逐项检查：

Tile shape：分块合理性、计算单元填充率、tail 开销、UB 用量；
GM ↔ UB 搬运：总搬运次数、冗余 reload/store-back、连续性、复用率；
小包风险：碎片化 copy、每 tile 输出是否太小、shape 是否破坏传输效率；
Barrier / wait / sync：数量、是否不必要地串行化；
UB 压力：tile buffer + FIFO buffer + 临时 buffer 总占用；
Pipeline overlap：各阶段 overlap 是否充分；
AIC / AIV 平衡：cube 和 vector 侧负载是否平衡；
瓶颈转移风险：是否只是转移了瓶颈而非消除。

8.6 优化优先级（从高到低）

消除不必要的数据搬运——减少冗余 GM load/store，提高 UB 复用；
修正不合理的 tile shape——改善 tile 维度以提升利用率和搬运效率；
减少小包传输低效——合并或批量化小包传输；
改善 load/compute/store overlap——改善稳态 pipeline overlap；
减少 barrier/wait 开销——删除可证明无用的 barrier；
降低 UB / 寄存器压力——缩短 live range，减少不利于 overlap 的临时 buffer；
改善指令组织——重组计算以改善 AIC/AIV 平衡；
微调只在以上问题都解决后进行。

8.7 高风险变更

以下变更属于高风险，必须额外说明理由：

更大的 tile 可能导致 UB 爆炸或编译失败；
修改 FIFO 大小可能改变 kernel 语义；
删除 barrier 前缺少依赖证明；
指令重排可能改变数值行为；
没有硬件理由的"可能更快"的改动。

8.8 禁止行为

一轮中做多个不相关的改动；
跳过正确性测试；
从单次噪声测量中声称胜利；
修改 benchmark workload 或弱化验证逻辑来提高数字；
没有瓶颈证据就做大规模重写；
多次失败后继续随机 trial-and-error；
隐藏失败的实验；
为代码美观而优化，而非针对硬件瓶颈；
仅基于理论推理就宣布成功。

8.9 三轮失败规则

如果连续 3 轮没有实质性收益，必须停止盲目的局部微调：

重新检查当前瓶颈分类；
检查之前的轮次是否在攻击症状而非根因；
寻找不同的优化方向；
优先考虑结构性变化；
可以通过上网搜寻相关资料参考。

模板 TASK_REQUIREMENTS.md 的 Hints 部分也内置了同样的兜底指令：连续 3 轮无进展时，重读remote.md、检查ITERATIONS.md历史轮次、搜索外部优化思路、重新评估方向后再继续。

9. 迭代协议：一轮一记录，全程可复现

9.1 迭代编号

"为验证性能而进行的代码修改或参数调整" + "一次构建和 benchmark 执行" = 一轮迭代。编号按顺序递增0, 1, 2, ...，iter-0 为 baseline。

9.2 每轮必须保存的产物

每轮完成后在projects/<operator_name>/runs/iter-XXX/下保存三个文件（runs/README.md 规定不允许缺失）：

files.txt——本轮修改的文件列表（调参类迭代写"环境变量调参，无源文件修改"）；
patch.diff——本轮代码 diff；
notes.md——本轮详细记录（Pre-Edit / Changes / Post-Run / Analysis / Next）。

并在ITERATIONS.md追加一行简约摘要。

9.3 patch.diff 记录规则

代码修改类迭代：标准diff -u格式；
调参类迭代：

# 本轮为调参类迭代 # 参数变更： - PARAM=old_value + PARAM=new_value # 基于 iter-XXX 的配置

9.4 Benchmark 纪律

相同 workload：前后对比必须使用相同 case；
可重复性：重要性能结果必须多次运行；
噪声处理：数据有噪声标记为inconclusive；
胜利判定：正确性通过 + 相同 workload + 改善可重复 + 收益大于噪声。

9.5 结果判定

kept：结果正确，且优于当前已知最好结果；
neutral：结果正确，但没有优于当前前沿结果；
failure：结果错误、编译失败，或本轮实验无效；
inconclusive：数据波动较大，重跑确认。

10. notes.md 记录要求：结构化沉淀每一轮

project_template/runs/_template/notes.md 给出了严格的字段模板，按时间线分为五段：

Pre-Edit（改代码前填写）

Kernel：目标算子名和当前配置；
Current bottleneck；
Evidence；
Hypothesis；
Why it should help on Ascend；
Expected improved metric；
Main risk。

Changes（改完代码后填写）

修改类型：代码修改 / 模板参数调整 / 环境变量 / 构建配置；
修改的文件：列出所有修改文件路径；
具体变更：每个参数的旧值→新值，或代码修改的具体内容；
完整参数快照：本轮所有参数配置（方便复现）。模板示例给出了典型快照格式：

BASE_M1=16, BASE_N1=64, BASE_K1=64, BLOCK_DIM1=8 BASE_M2=16, BASE_N2=64, BASE_K2=64, BLOCK_DIM2=8 RELU_BLOCK_DIM=8

Post-Run（跑完 benchmark 后填写）

Correctness：pass / fail；
Performance：写明具体数值（duration、TFLOPS 等）；
Stability：stable / noisy；
Result：kept / neutral / failure。

Analysis

详细分析为什么有效或失败（含与上一轮/最佳轮对比、硬件层面成因）。

下一轮准备尝试什么，给出具体方向和理由。

环境打通轮额外记录

远程环境版本信息、构建是否成功、首次有效结果路径、主要坑点。

11. 收尾要求：总结对照图

优化结束后必须生成一张总结对照图（PNG），风格参考projects/flash_attention/summary.png，保存到projects/<operator_name>/summary_chart.png。图表为上下双图结构：

上半部分 — 提升倍数折线图：

Y 轴：相对于初始 PTO 的 speedup 倍数（x）；
折线：每轮实际 speedup（绿色）+ best frontier（橙色）；
散点标记：绿色=kept、蓝色=neutral、红色叉=failure；
阶段背景色：不同优化阶段用不同颜色背景区分（如 baseline / costmodel-guided / 参数验证 / fine-tune）；
里程碑标注：关键提升点标注具体改动内容；
顶部摘要：总迭代数、kept/neutral/failure 统计、最终 speedup、与 torch_npu 的对比。

下半部分 — 绝对延迟柱状图：

Y 轴：duration（us 或 ms，必要时 log scale）；
柱状图颜色区分：灰色=baseline、绿色=kept、蓝色=neutral、红色=failure；
torch_npu 参考线（紫色虚线）；
每根柱标注具体数值。

底部：文字说明 torch_npu / PTO initial / PTO best 数值和关键结论。

迭代精简：若总迭代数 >10，X 轴只展示关键迭代（baseline、每次 kept、典型 failure、最终 best），将连续的 neutral/failure 压缩为代表的一两个。

12. 远程环境 Bring-Up：把远程 Ascend 带到可稳定 benchmark

remote.md 覆盖两种情况的远程环境准备：已有环境的快速复用、空环境的从零 bring-up。它只负责环境准备和排障，调优流程以 task.md 为准。

注意：<user>、<remote_ip>、<path_to>由用户在每次会话开始时提供，不要硬编码。

12.1 工作流九步

1. 确认 SSH

ssh -o BatchMode=yes <user>@<remote_ip> "echo ssh_key_ok"

2. 本地准备工作区先在本地确保external/src/下四个依赖库齐全（pto-dsl、PTOAS、pto-isa、ops-transformer），缺失则执行bash scripts/bootstrap_workspace.sh，这样上传时external/src/一并传到远程，避免远程 git clone 受网络影响。

3. 上传工作区（远程目录结构与本地保持一致）：

# 首选 scp -r projects/<operator_name>/workspace/pto-kernels <user>@<remote_ip>:<path_to>/AKO4PTO/projects/<operator_name>/workspace/ # 备选（增量同步） rsync -avz projects/<operator_name>/workspace/pto-kernels/ <user>@<remote_ip>:<path_to>/AKO4PTO/projects/<operator_name>/workspace/pto-kernels/

4. 识别远程 Python

which python3 && python3 --version

不要假设系统python3满足 PTO 依赖，不要替换系统 Python；
如果远程默认是 Python 3.9，优先使用用户态 Python 3.11（如~/.local/miniforge3/envs/pto-py311/bin/python）；
一旦选定解释器，后续所有操作固定使用，不和系统 Python 混用。

5. 快速复用（已有环境）先做最小校验，不要急着安装任何东西：

cd <path_to>/AKO4PTO/projects/<operator_name>/workspace/pto-kernels bash scripts/source_env.sh <python_exec> scripts/check_env.py --strict <python_exec> -c "import mlir.ir; from mlir.dialects import pto; print('mlir_ok')" <python_exec> -c "import torch, torch_npu; print(torch.npu.is_available())" ptoas --version <python_exec> -m pto_kernels.bench.runner <target_spec>

全部通过 → 复用成功，直接进入调优；任一步失败 → 进入完整 bring-up（步骤 6 起）。

6. 确认远程依赖源码上传后确认external/src/pto-dsl external/src/PTOAS external/src/pto-isa external/src/ops-transformer四个目录，缺失则远程执行bash scripts/bootstrap_workspace.sh。注意：bootstrap_workspace.sh需要远程能访问 GitHub / GitCode，超过 10 秒无响应 → 在本地补全后重新 scp 上传external/src/。

7. 安装 Python 依赖

<python_pip> install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt <python_pip> install -i https://pypi.tuna.tsinghua.edu.cn/simple torch-npu==2.8.0.post2 --extra-index-url https://download.pytorch.org/whl/cpu <python_pip> install -i https://pypi.tuna.tsinghua.edu.cn/simple numpy PyYAML mpmath 'pybind11<3' decorator

10 秒超时规则：远程pip install或任何下载命令超过10 秒无响应，立即 Ctrl-C，切换为"本地下载 + scp 上传"：
pip download -i https://pypi.tuna.tsinghua.edu.cn/simple <package> -d /tmp/wheels/ scp -r /tmp/wheels/ <user>@<remote_ip>:<path_to>/wheels/ <python_pip> install --no-index --find-links <path_to>/wheels/ <package>

8. 加载环境 + 检查 ptoas/mlir

bash scripts/source_env.sh ptoas --version <python_exec> -c "import mlir.ir; from mlir.dialects import pto; print('mlir_ok')"

失败时通常需手动补环境变量：

export PATH=<py311_bin>:<ptoas_cli_bin>:$PATH export LD_LIBRARY_PATH=<py311_lib>:<mlir__mlir_libs>:<ptoas_cli_lib>:/usr/local/Ascend/cann-*/aarch64-linux/lib64:$LD_LIBRARY_PATH

注意：mlir/_mlir_libs和ptoasCLI 的lib目录往往都必须放进LD_LIBRARY_PATH。

9. 环境自检 + benchmark 验证执行与步骤 5 相同的完整校验序列（check_env.py --strict→ mlir → torch_npu → ptoas → bisheng），然后跑一次目标 benchmark（<python_exec> -m pto_kernels.bench.runner <target_spec>）。环境是否可用以 task.md 里的 gate 为准。

12.2 常见排障对照

现象	检查方向
SSH 要密码	检查本地私钥、远程`authorized_keys`、登录用户名
已有环境跑不通	先确认仓库路径、Python 路径、`source_env.sh`是否成功、`check_env.py --strict`，只有确认不可修复才转完整 bring-up
`torch_npu`导入失败	Ascend 环境是否加载、Python 路径是否正确、`torch_npu`是否装到正确的解释器
`torch.npu.is_available()`为 False	`LD_LIBRARY_PATH`是否含 CANN`aarch64-linux/lib64`，`source_env.sh`是否提前退出
`import mlir.ir`失败	`ptoas`wheel 是否装到当前解释器，`LD_LIBRARY_PATH`是否含`mlir/_mlir_libs`
`ptoas --version`通过但编译失败	`PATH`和`LD_LIBRARY_PATH`是否含 ptoas CLI 的 bin/lib
远程下载超过 10 秒无响应	不要重试，本地`pip download`→ scp 上传 → 远程`pip install --no-index --find-links`离线安装

13. 落地到当前仓库：你可以怎么用

本技能包已完整入库，路径为 agents/skills/pto-costmodel-agentic-kernel-optimization/。你在使用时可参考：

想理解调优纪律：精读 task.md 的"优化规则"与"迭代协议"两节；
想准备远程环境：按 remote.md 的九步工作流执行；
想快速启动新算子项目：直接复制 project_template/ 到projects/<operator_name>/；
想验证单条指令 cycle：按 pto-costmodel-query-pto-cycles skill 使用查询脚本，其仿真机制可追溯到 trace.hpp 的BeginPtoInstr/EndPtoInstr/GetLastPtoInstrCycles与 perf-sim-user-guide_zh.md 的 pipeline 级仿真；
想了解 PTO 指令集背景：可对照 PTO-Virtual-ISA-Manual_zh.md 与 docs/isa/README.md 中的指令说明（如 TMATMUL、TADD、TEXP 等），理解待调优指令的语义与约束。

最后提醒：AKO4PTO 的结论标准始终是"正确 + 可衡量 + 可重复"。优化是过程，留痕是纪律，而 benchmark 数据（report.json / report.csv 中的 duration 与 TFLOPS）才是唯一的裁判。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考