| name | pypto-aicore-error-locator |
| description | 定位测试案例中出现 aicore error 时的问题 CCE 文件和问题代码行。当用户说"aicore error"、"定位 aicore error 的原因"、"帮我定位 aicore error 报错"时使用此技能。也适用于用户直接提供 CCE 文件希望定位问题代码行或映射到源码的场景。 |
AICore Error 定位器
此技能是总入口，根据用户输入自动分流到对应路径。
路径选择（总入口）
根据用户提供的输入，直接分流：
| 用户输入特征 | 分流到 | 说明 |
|---|
| 提供了 CCE 文件路径 + 问题代码行号 | quick-b | 直达源码映射 |
| 提供了 CCE 文件路径（无行号） | quick-a | 跳过步骤 1-3，从二分查找开始 |
| 未提供 CCE 文件 | 完整流程（下方） | 执行标准步骤 1-6 |
判断依据：用户消息中包含 CCE 文件路径（如 .cpp 文件），以及是否同时提供了行号。
完整流程
- 初始测试 — 问题复现，检查是否为该脚本可适用的 aicore error 场景
- 排除 machine 框架调度问题 — 判断问题在 kernel 代码还是 machine 调度框架
- 定位问题 CCE 文件 — 通过单个脚本完成追踪日志启用、重编、测试、日志分析和 CCE 文件验证
- 二分 CCE 文件找到问题代码行
4.1 准备二分查找 — 确定错误范围 + 获取初始范围
4.2 二分查找迭代
- 问题代码行映射到前端代码
5.1 CCE 行映射到前端源文件
5.2 输出最终结果
Pypto_Test 框架适配
重要：如果用户明确使用 Pypto_Test 框架，所有脚本调用必须追加 --use-pypto-test-framework 参数。判断依据（不区分大小写、不区分下划线 _ 和中划线 -）：
- 用户提到 "Pypto_Test"、"pypto test"、"PYTO_TEST"、"pypto-test" 等任意变体
- 测试命令中包含 pypto test 框架组件的导入或调用
- 用户明确说"使用框架"、"框架模式"
步骤 1：初始化默认信息与初始测试
使用以下默认值直接初始化：
- pypto_path: 当前工作目录（即 pypto 项目根目录）
- device_log_path:
{pypto_path}/device_log
- run_path:
{pypto_path}
- test_cmd: 从用户输入中提取（用户触发此技能时提供的测试命令或问题描述中包含的运行命令）
⚠️ 重要提示: 将 bash 运行命令超时时间设置为 1800000ms
初始测试 - 确认 aicore error 可复现
在修改任何代码之前，先运行一次测试，确认 aicore error 确实存在：
cd <run_path> && export ASCEND_GLOBAL_LOG_LEVEL=0 && <test_cmd>
cd -
⚠️ 重要提示：检查打屏输出，必须出现 aicore error。
- 如果未出现 aicore error：说明该问题不适用此定位方法（可能已修复或测试命令不正确），立即停止执行后续步骤！
- 如果出现 aicore error：确认问题可复现，继续执行后续步骤。
步骤 2：排除 machine 框架调度问题
通过单个脚本判断 aicore error 源于 kernel 代码还是 machine 调度框架。该脚本合并了原来的 2.1-2.4 子步骤（定位 aicore_entry.h → 注释 CallSubFuncTask → 运行测试 → 恢复文件），直接操作已安装的 pypto 包，无需重新编译安装。
python3 .agents/skills/pypto-aicore-error-locator/scripts/exclude_machine_framework.py \
--test-cmd <test_cmd> \
--run-path <run_path> \
[--use-pypto-test-framework]
⚠️ 重要提示：
- 使用 bash 运行命令超时时间为 1800000ms
- 若脚本退出码为 0（注释后无 aicore error）：问题在 kernel 代码中，继续执行后续步骤
- 若脚本退出码为 1（注释后仍有 aicore error）：问题在 machine 框架调度，停止执行后续步骤
- 若脚本退出码为 2（定位 aicore_entry.h 或 CallSubFuncTask 失败）：停止执行后续步骤，手动排查环境
步骤 3：定位问题 CCE 文件
通过单个脚本完成 3.1-3.7 的全部操作：启用追踪日志 → 条件重编译 → 运行测试 → 分析日志 → 定位并验证 CCE 文件。脚本内部自动处理并行编译错误（ld.lld: error: undefined），自动重试。
python3 .agents/skills/pypto-aicore-error-locator/scripts/locate_problem_cce.py \
--pypto-path <pypto_path> \
--test-cmd <test_cmd> \
--run-path <run_path> \
--device-log-path <device_log_path> \
[--use-pypto-test-framework]
⚠️ 重要提示：
- 使用 bash 运行命令超时时间为 1800000ms
- 若脚本退出码为 0：成功定位，输出
CCE_FILE=<path> 和 PROGRAM_JSON=<path>，记录这两个路径供步骤 4、5 使用
- 若脚本退出码为 1：未找到问题 CCE 文件，停止执行后续步骤
- 若脚本退出码为 2：并行编译错误无法自动修复（parallel_compile 已为 1 但仍报错），停止执行
步骤 4：二分 CCE 文件找到问题代码行
通过迭代注释缩小范围，精确定位到导致 aicore error 的具体代码行。
4.1 准备二分查找 — 确定错误范围 + 获取初始范围
单个脚本合并 4.1 和 4.2：先注释所有 T 操作行并测试确定错误是否在 T 操作中，再根据结果计算二分查找的初始范围。
python3 .agents/skills/pypto-aicore-error-locator/scripts/setup_binary_search.py <cce_file> <test_cmd> <run_path> [--use-pypto-test-framework]
⚠️ 重要提示:
cce_file 为步骤 3 脚本输出的 CCE_FILE 值- 记录输出的
ERROR_IN_T、LEFT、RIGHT 三个值供步骤 4.2 使用
- 若
ERROR_IN_T=True：后续二分查找范围仅限 T 操作行；若为 False：范围为除同步行外的所有行
4.2 执行二分查找迭代
⚠️ 此步骤需要多次迭代执行：每一步执行一条命令，根据输出结果更新 left/right 值后继续迭代，直至找到问题行。
根据步骤 4.1 的 LEFT 和 RIGHT 值，执行当前迭代：
python3 .agents/skills/pypto-aicore-error-locator/scripts/binary_search_iteration.py <cce_file> <test_cmd> <run_path> <left> <right> <error_in_t> [--use-pypto-test-framework]
记录输出的 NEXT_LEFT 和 NEXT_RIGHT 值。
判断逻辑:
- 如果
NEXT_LEFT 等于 NEXT_RIGHT，则已找到问题行（输出 FOUND <problem_line>），记录 problem_line 值用于步骤 5
- 否则，使用新的
NEXT_LEFT 和 NEXT_RIGHT 作为下一轮的 left 和 right，重复执行此步骤
⚠️ 重要提示:
cce_file 为步骤 3 脚本输出的 CCE_FILE 值<error_in_t> 为步骤 4.1 输出的 ERROR_IN_T 的值（True 或 False），必须传入字面量 True/False，不可传入变量名- 每次迭代仅执行一条命令（受超时限制），需要在多轮中逐步收敛
- 若未定位到问题代码行（left > right 异常），请说明原因，停止执行后续步骤
步骤 5：问题代码行映射到前端代码
将 CCE 问题行映射回前端源文件，便于开发者定位修复。
5.1 CCE 行映射到前端源文件
使用以下命令将 CCE 问题代码行映射到前端源代码：
python3 .agents/skills/pypto-aicore-error-locator/scripts/locate_source_line.py <cce_file> <program_json_path> <problem_line>
参数说明:
<cce_file>: 步骤 3 脚本输出的 CCE_FILE 值<program_json_path>: 步骤 3 脚本输出的 PROGRAM_JSON 值<problem_line>: 步骤 4.3 输出的问题代码行号
输出说明:
- 若匹配成功，将输出前端源代码文件路径和行号
- 若完全无法匹配，将说明原因，常见场景包括：
- 无法找到 funcHash 或无法解析 CCE 文件：CCE 文件中缺少
funcHash 标记或行号越界，脚本输出 ✗ 无法映射到源代码
- 框架自动生成代码：该代码行为框架自动生成（非前端用户编写的代码），无源码与之映射
- 操作数数量不一致：CCE 文件中的操作数与
program.json 中对应函数的操作数不匹配，脚本输出 CCE 文件与 program.json 操作数不一致。可能原因是 CCE 文件与 program.json 版本不一致，请重新运行测试生成新的 CCE 文件和 program.json 后重试
5.2 输出最终结果
汇总输出以下信息：
- 找到的 CCE 文件路径
- 问题代码行号
- 问题代码内容
- 前端源代码文件路径（如果步骤 5.1 映射成功）
- 前端源代码行号（如果步骤 5.1 映射成功）
- 前端源代码内容（如果步骤 5.1 映射成功）
恢复初始状态
定位完成后，使用单个脚本恢复步骤 3 修改的配置文件并重新编译安装 pypto：
python3 .agents/skills/pypto-aicore-error-locator/scripts/restore_initial_state.py --pypto-path <pypto_path>
脚本自动完成：恢复 tile_fwk_config.json 和 device_switch.h 的 .backup 备份 → 重新编译安装 pypto。
关键注意事项
- fixed 模式: 确保
fixed 模式启用以保持输出路径不变
- 路径规范: 所有路径必须使用绝对路径
- 默认路径: 步骤 1 使用默认值初始化，无需收集用户输入
- 停止条件: 遇到不适用的情况或定位失败时，立即停止执行并说明原因
- 并行编译问题: 步骤 3 脚本自动处理
ld.lld: error: undefined 错误（修改 parallel_compile 并重编），脚本内部完成重试；若退出码为 2 表示无法自动修复（parallel_compile 已为 1 仍报错），停止执行
- 步骤 2 无需重编: 步骤 2 直接修改安装路径下的
aicore_entry.h，无需重新编译安装 pypto
- 步骤 4.2 迭代执行: 二分查找因单次命令有超时限制，分解为多轮迭代执行，每轮执行一条命令
