@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ascendc-docs-search/scripts/find_api_doc.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+# find_api_doc.sh — 结构无关的 Ascend C API 文档查找工具
+#
+# 用途：在 $ASC_DEVKIT_DIR/docs/zh/api/ 下搜索 API 文档，不假设子目录结构。
+#       适用于 health check、ST 测试，以及作为 agent find 命令的参考实现。
+#
+# 用法：find_api_doc.sh <APIName> [APIName2 ...]
+# 输出：每行一个匹配的文档路径（相对于 $ASC_DEVKIT_DIR）
+# 退出码：0=找到，1=未找到，2=环境错误
+
+set -euo pipefail
+
+ASC_DEVKIT_DIR="${ASC_DEVKIT_DIR:-}"
+
+if [ -z "$ASC_DEVKIT_DIR" ]; then
+  echo "Error: ASC_DEVKIT_DIR is not set" >&2
+  exit 2
+fi
+
+if [ ! -d "$ASC_DEVKIT_DIR/docs/zh/api/" ]; then
+  echo "Error: $ASC_DEVKIT_DIR/docs/zh/api/ not found" >&2
+  exit 2
+fi
+
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <APIName> [APIName2 ...]" >&2
+  echo "Searches $ASC_DEVKIT_DIR/docs/zh/api/ for matching .md files" >&2
+  exit 2
+fi
+
+found=0
+for api in "$@"; do
+  while IFS= read -r path; do
+    printf '%s\n' "${path#$ASC_DEVKIT_DIR/}"
+    found=1
+  done < <(find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "${api}*.md" -type f 2>/dev/null | sort)
+done
+
+if [ "$found" -eq 0 ]; then
+  echo "No API docs found for: $*" >&2
+  exit 1
+fi
+
+exit 0

package/assets/ops-direct-invoke/skills/ascendc-env-check/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ascendc-env-check
+description: Ascend C 算子开发环境检查技能。用于：(1) 通过 npu-smi 查询 NPU 设备信息（设备列表、状态、资源使用），(2) 检查 CANN 环境配置（CANN Toolkit、Ops、自定义算子包），(3) 验证开发依赖是否完整，(4) 运行时检测当前设备 NPU 架构。触发关键词：环境检查、NPU设备、npu-smi、CANN安装、设备查询、资源监控、检查CANN环境变量、NPU架构、npu arch。
+---
+
+# Ascend C 环境检查
+
+快速检查开发环境配置和 NPU 设备状态。
+
+## 工作流程
+
+```
+环境检查
+    │
+    ├─ NPU 设备检查
+    │   └─ npu-smi info -m / scripts/npu_info.sh
+    │
+    ├─ CANN 环境检查
+    │   └─ scripts/check_env.sh
+    │
+    └─ NPU 架构检测
+        └─ scripts/get_npu_arch.py
+```
+
+## NPU 设备检查
+
+### 快速命令
+
+```bash
+# 查看设备详细信息（包含设备列表）
+npu-smi info
+
+# 监控设备资源
+npu-smi info -t usages -i <device_id>
+```
+
+### 脚本工具
+
+```bash
+# 综合 NPU 信息（推荐）
+bash scripts/npu_info.sh
+```
+
+详细命令参数见 [npu_commands.md](references/npu_commands.md)，npu-smi 不可用时的回退方案见 [asys_commands.md](references/asys_commands.md)
+
+## CANN 环境检查
+
+```bash
+# 完整环境检查（推荐）
+bash scripts/check_env.sh
+```
+
+### 检查项
+
+| 检查项 | 说明 | 必需 |
+|--------|------|------|
+| ASCEND_HOME_PATH | CANN Toolkit 路径 | 是 |
+| CANN 版本 | 检测版本号及运行时依赖基线 | 建议确认 |
+| ASCEND_OPP_PATH | CANN Ops 路径 | 运行时必需 |
+| 自定义算子包 | op_api 库 | 运行自定义算子必需 |
+| CANN 工具 | msprof/cannsim | 可选 |
+| Simulator状态 | 检查必要的模拟器状态 | KirinX90、Kirin9030 等 Kirin 平台开发必需 |
+
+> ⚠️ **注意**：官方环境变量为 `ASCEND_HOME_PATH`，不是 `ASCEND_HOME`。部分旧文档或示例代码可能使用 `ASCEND_HOME`，这是错误用法。
+
+详细环境配置见 [env_config_guide.md](references/env_config_guide.md)，版本配套关系见其中「CANN 版本兼容性」章节
+
+## NPU 架构检测
+
+**前置条件**：先 source CANN 安装目录下的 `set_env.sh`（asys 与 DSMI 库依赖其 PATH / LD_LIBRARY_PATH）。
+
+**重要**：npu-smi 的 Chip Name 作为 short-soc-version **不可信**（A3 机型误报 `Ascend910`，issue #587），禁止用于芯片型号识别。
+
+```bash
+# 人读报告（含用途注释与证据链）
+python3 scripts/get_npu_arch.py
+
+# 仅输出裸 NpuArch 数值（如 3510）
+python3 scripts/get_npu_arch.py --raw
+
+# 机器可读 JSON（键名：full_soc / full_soc_source / npu_arch / npu_arch_source / short_soc / ccec_aiv_version / variant_dir / ini_path / npu_count / warnings）
+python3 scripts/get_npu_arch.py --json
+```
+
+**获取链**：
+
+| 获取项 | 优先来源 | 备选来源 |
+|---|---|---|
+| full-soc-version（如 `Ascend950PR_9579`） | asys `info -r=hardware` Chip Info | DSMI `dsmi_get_chip_info` |
+| NpuArch（如 `3510`） | asys Arch Info | ini 文件（full-soc-version 精确匹配） |
+| short-soc-version / CCE_AIV_version / variant_dir | ini 文件 | — |
+
+- short-soc-version（如 `Ascend950`）用于算子原型定义文件 `xxx算子_def.cpp` 的 `AddConfig()` 第一个参数（如 `this->AICore().AddConfig("ascend950", aicConfig)`）
+- variant_dir（如 `dav_c310`）决定读CANN安装目录下源码时只看 `**/dav_c310/` 下的文件
+- ini 匹配按 `SoC_version=` 字段精确匹配，禁止文件名/前缀模糊匹配
+
+**依赖**：Ascend driver 和 CANN toolkit。
+
+## 诊断脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `scripts/npu_info.sh` | NPU 设备信息综合查询 |
+| `scripts/check_env.sh` | CANN 环境配置检查 |
+| `scripts/get_npu_arch.py` | 运行时检测当前设备 NPU 架构 |
+
+也可直接调用 `_npu_info.py` Python 脚本获取结构化数据，支持 `--json`（完整 JSON 输出）、`--list`（设备 ID 列表）、`--health`（健康状态）等参数。
+
+## Kirin 平台开发
+
+Kirin 系列芯片（KirinX90、Kirin9030等以 Kirin 开头的平台）是端侧 AI 处理器，当前主要支持使用模拟器 Simulator 的开发方式，需要注意环境检查结果中的 Simulator 支持情况，**如不支持则环境检查结论是不支持 Kirin 平台开发，需要强调并告知用户。**
+
+当前 Kirin 开发使用的 CANN 版本和服务器有差异，Kirin 系列芯片开发，需要安装对应的 mobile-station 版本的 CANN 才有 Kirin 的 Simulator。
+
+详细内容（mobile-station CANN 的安装方法、常见问题）见 [kirin_platform_guide.md](references/kirin_platform_guide.md)
+
+## 常见问题
+
+- **NPU 不可见**：先执行 `npu-smi info -m` 检查设备映射表，再排查驱动是否安装正确
+- **算子运行失败**：**优先**运行 `check_env.sh` 检查环境配置是否完整，并检查关键环境变量（`ASCEND_HOME_PATH`、`ASCEND_OPP_PATH`）是否已正确设置
+- **确认是否有进程占用 NPU**：使用 `npu-smi info -t usages -i <device_id>` 查看运行中的进程；注意空闲设备仍会有少量 HBM 被驱动占用（正常现象），不应误判为设备被占用
+
+详细排查见 [troubleshooting.md](references/troubleshooting.md)

package/assets/ops-direct-invoke/skills/ascendc-env-check/evals/evals.json

@@ -0,0 +1,211 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "NPU设备信息查询",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "如何查看NPU设备的详细信息，应该使用什么命令？",
+      "expected_output": "回复应说明使用 npu-smi info 查看NPU设备列表和状态（设备数、健康、温度、功耗、HBM 等），推荐使用 npu_info.sh 脚本进行综合查询；并说明芯片型号不从 npu-smi 获取（npu-smi 的 Chip Name 作为 short-soc-version 不可信，issue #587），应使用 get_npu_arch.py 获取芯片型号",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "NPU架构检测",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "如何查看当前昇腾设备的NPU架构信息？",
+      "expected_output": "1. 回复应推荐使用 `scripts/get_npu_arch.py` 检测 NPU 架构，并说明运行前需先 source CANN 安装目录下的 `set_env.sh`。\n2. 回复应说明脚本报告的关键字段及其用途：full-soc-version（完整芯片型号，如 Ascend950PR_9579）、NpuArch（如 3510）、short-soc-version（如 Ascend950，用作算子原型定义文件 `xxx算子_def.cpp` 的 `AddConfig()` 第一个参数）、CCE_AIV_version 与 variant_dir（如 dav_c310）。\n3. 回复应说明获取链：full-soc-version 优先 asys `info -r=hardware` 的 Chip Info、备选 DSMI `dsmi_get_chip_info`；NpuArch 优先 asys Arch Info、备选 ini 文件按 `SoC_version=` 精确匹配。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "环境变量配置注意点",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "配置CANN环境变量的时候有什么需要注意的地方？ASCEND_HOME_PATH和ASCEND_HOME有什么区别？",
+      "expected_output": "回复应指出官方环境变量为 ASCEND_HOME_PATH，并说明部分旧文档中使用的 ASCEND_HOME 是错误用法，不应混淆",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 4,
+      "title": "NPU不可见故障排查",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "disabled": true,
+        "eval_mode": "text"
+      },
+      "prompt": "我的昇腾服务器上看不到NPU设备，npu-smi info没有输出设备信息，怎么排查？",
+      "expected_output": "回复应提供NPU设备不可见的排查思路；可能会先输出当前环境的NPU设备状态再给出排查建议",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 5,
+      "title": "算子运行失败排查",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "disabled": true,
+        "eval_mode": "text"
+      },
+      "prompt": "我开发的算子在昇腾NPU上运行失败了，怎么排查是不是环境配置的问题？",
+      "expected_output": "回复应建议优先运行 check_env.sh 检查环境配置是否完整，并检查关键环境变量是否已正确设置",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 6,
+      "title": "正向看护-多skill环境下正确触发目标skill",
+      "config": {
+        "max_tokens": 180000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "cann-env-setup",
+          "npu-arch",
+          "ascendc-runtime-debug",
+          "ascendc-docs-search"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我有一台昇腾服务器，想对NPU设备进行环境检查和设备查询，查看设备的详细信息和资源使用情况，应该用什么命令？",
+      "expected_output": "1. 回复应说明使用 `npu-smi info` 查看 NPU 设备信息（设备数、健康、资源使用）。\n2. 回复应推荐使用 `scripts/npu_info.sh` 做 NPU 设备信息综合查询。\n3. 回复应说明芯片型号由 `get_npu_arch.py` 获取（asys Chip Info 优先、DSMI 兜底），不应依赖 `npu-smi` 的 Chip Name。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 7,
+      "title": "npu-smi 结构化子命令查询",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text",
+        "timeout": 900
+      },
+      "prompt": "我想在脚本里自动获取 NPU 的温度和功耗，但直接解析 `npu-smi info` 的输出经常因为格式变化而失效。有没有更稳定的方法？",
+      "expected_output": "1. 回复应推荐使用 `npu-smi info -t <type> -i <device_id>` 结构化子命令替代解析 `npu-smi info` 主表格。\n2. 回复应说明 `-t` 子命令返回 key:value 格式、比主表格更稳定（主表格列宽与字段名随驱动版本变化）。\n3. 回复应说明获取数据的第一步是用 `npu-smi info -m` 确认设备 ID（设备 ID 不一定是 0）、列出常用 type（如 temp、power、memory、usages、common、health），并提醒芯片型号不可从 npu-smi 获取（Chip Name 作为 short-soc-version 不可信，issue #587），应使用 `get_npu_arch.py`。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 8,
+      "title": "npu-smi 已变更/废弃命令",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我以前的脚本里用了 `npu-smi top` 和 `npu-smi health` 命令，现在好像不能用了？还有 `npu-smi release` 和 `npu-smi lock` 呢？",
+      "expected_output": "回复应说明 `npu-smi top` 已被 `npu-smi info -t usages -i <device_id>` 替代，`npu-smi health` 已被 `npu-smi info -t health -i <device_id>` 替代。`npu-smi release`、`npu-smi lock/unlock`、`npu-smi perf` 等命令在新版本中可能已不存在。应建议通过 `npu-smi --help` 和 `npu-smi info --help` 查询当前版本支持的命令。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 9,
+      "title": "脚本中可靠获取 NPU 信息",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我需要写一个 Python 脚本来自动收集 NPU 设备信息（温度、功耗、使用率等），有什么可靠的方法可以避免硬编码 npu-smi 命令？",
+      "expected_output": "回复应推荐编写 Python 脚本来调用 npu-smi 结构化子命令，说明可通过 `npu-smi info --help` 动态发现可用子命令，优先使用 `npu-smi info -t common` 批量获取数据，避免硬编码命令列表。应给出使用示例。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 10,
+      "title": "Kirin 平台开发环境检查",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我要在 KirinX90 设备上开发端侧算子，环境检查结果里的 Simulator 状态是什么意思？怎么判断当前环境支不支持 Kirin 平台开发？",
+      "expected_output": "回复应说明 Kirin 系列芯片（KirinX90、Kirin9030 等以 Kirin 开头的平台）是端侧 AI 处理器，主要通过模拟器 Simulator 进行开发；应检查环境检查结果中的 Simulator 支持情况，如不支持则环境检查结论为不支持 Kirin 平台开发，需要强调并告知用户；Kirin 开发需要安装 mobile-station 版本的 CANN 才有对应的 Kirin Simulator。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 11,
+      "title": "Python 结构化获取 NPU 信息",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我写自动化脚本要读取 NPU 设备的健康状态和设备 ID 列表，不想解析 npu-smi 的文本输出，仓库里有没有现成的 Python 工具能直接拿到结构化数据？",
+      "expected_output": "回复应推荐调用 _npu_info.py Python 脚本获取结构化 NPU 数据，并说明支持 --json（完整 JSON 输出）、--list（设备 ID 列表）、--health（健康状态）等参数。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 12,
+      "title": "确认 NPU 是否被进程占用",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我用 npu-smi 看到某块卡有 HBM 占用，怀疑被别的进程占用了，怎么确认到底有没有进程在用这块卡？空闲的设备显示少量 HBM 占用正常吗？",
+      "expected_output": "回复应说明使用 npu-smi info -t usages -i <device_id> 查看设备上运行中的进程；并指出空闲设备仍会有少量 HBM 被驱动占用，这是正常现象，不应误判为设备被进程占用。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 13,
+      "title": "CANN 环境检查清单与关键配置项",
+      "config": {
+        "max_tokens": 200000,
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text",
+        "timeout": 900
+      },
+      "prompt": "我要在一台新昇腾服务器上运行自定义算子，跑之前想系统检查一遍 CANN 环境。请先加载 ascendc-env-check 技能并阅读其 SKILL.md 与 references/env_config_guide.md 后回答（不需要真的执行环境检查脚本）：1）做完整 CANN 环境检查应该用哪个脚本？2）检查清单中 ASCEND_HOME_PATH 与 ASCEND_OPP_PATH 分别属于哪个包、在什么场景下必需？3）运行自定义算子时 op_api 库的路径与 LD_LIBRARY_PATH 应如何检查和配置？CANN 版本检查要确认哪些信息——版本号与运行时依赖基线分别从哪个文件的哪个字段读取？此外还有哪些可选的 CANN 工具？",
+      "expected_output": "1. 回复应推荐运行 `bash scripts/check_env.sh` 做完整 CANN 环境检查。\n2. 回复应说明重点检查项 ASCEND_HOME_PATH（CANN Toolkit 路径，编译+运行必需）与 ASCEND_OPP_PATH（CANN Ops 路径，运行时必需）。\n3. 回复应说明运行自定义算子所必需的 op_api 库（`vendors/<vendor_name>/op_api/lib`）检查项、CANN 版本及 `required_package_runtime_version` 运行时依赖基线，以及可选 CANN 工具 msprof/cannsim。",
+      "expectations": [],
+      "files": []
+    }
+  ],
+  "skill_name": "ascendc-env-check"
+}

package/assets/ops-direct-invoke/skills/ascendc-env-check/references/asys_commands.md

@@ -0,0 +1,64 @@
+# asys 命令速查
+
+> **芯片型号识别的首选工具**（npu-smi 的 Chip Name 作为 short-soc-version 不可信，issue #587）；
+> 同时作为 npu-smi 不可用时的设备查询回退工具。
+> 路径：`$ASCEND_HOME_PATH/tools/ascend_system_advisor/asys/asys`
+
+## 设备健康检查
+
+```bash
+# 检查所有设备健康状态
+asys health
+
+# 检查指定设备（-d 后接 Device ID）
+asys health -d 0
+```
+
+> `-d` 参数指定的是 **Device ID**（从 0 开始），不是 Card ID。
+
+**设备可用性判断**：
+
+| 状态 | 可用性 |
+|------|--------|
+| Healthy | 可用 |
+| Warning | 可用 |
+| 其他 | 不可用 |
+
+## 设备状态查询
+
+```bash
+# 查看设备状态（芯片型号、温度、功耗、HBM、AI Core 等）
+asys info -r status
+
+# 查看指定设备（-d 后接 Device ID）
+asys info -r status -d 0
+```
+
+## 硬件信息（芯片识别核心来源）
+
+```bash
+# 查看主机和设备硬件信息（CPU、NPU 数量、PCIe 等）
+asys info -r hardware
+```
+
+关键输出字段：
+
+| 字段 | 用途 |
+|------|------|
+| Chip Info | 芯片完整型号（full-soc-version，如 `Ascend 950PR_9579 V100`） |
+| Arch Info | NpuArch（如 `2201`；部分 asys 版本无此字段，回退 ini） |
+| NPU Count | 设备数 |
+
+## 软件信息
+
+```bash
+# 查看主机和设备软件版本（驱动、固件、runtime 等）
+asys info -r software
+```
+
+## 诊断
+
+```bash
+# 硬件诊断（支持 910B/910_93/950）
+asys diagnose
+```

package/assets/ops-direct-invoke/skills/ascendc-env-check/references/env_config_guide.md

@@ -0,0 +1,96 @@
+# 环境变量配置指南
+
+本文档基于官方资料整理，提供 Ascend C 算子开发的环境变量配置方法。
+
+## 配置流程
+
+### 场景1: 仅编译算子（无需 NPU）
+
+```bash
+source /usr/local/Ascend/cann/set_env.sh  # root
+# 或
+source $HOME/Ascend/cann/set_env.sh       # 非root
+```
+
+### 场景2: 运行内置算子
+
+```bash
+# 先 source CANN Toolkit
+source /usr/local/Ascend/cann/set_env.sh
+
+# 安装 CANN Ops（如未安装）
+./Ascend-cann-${soc_name}-ops_*.run --install --install-path=${install_path}
+source ${install_path}/cann/set_env.sh  # 重新 source 使 ASCEND_OPP_PATH 生效
+```
+
+### 场景3: 运行自定义算子
+
+```bash
+source /usr/local/Ascend/cann/set_env.sh
+./build_out/<your_operator_package>.run  # 安装自定义算子包
+
+# 配置动态库路径（vendor_name 为编译时的 --vendor_name 参数）
+export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}/op_api/lib:$LD_LIBRARY_PATH
+```
+
+## 环境变量说明
+
+| 环境变量 | 所属包 | 配置方式 | 必需场景 |
+|---------|--------|---------|---------|
+| ASCEND_HOME_PATH | CANN Toolkit | `source set_env.sh` | 编译+运行 |
+| ASCEND_OPP_PATH | CANN Ops | 由 set_env.sh 自动设置 | 仅运行 |
+| LD_LIBRARY_PATH | 自定义算子包 | `export ...` | 运行自定义算子 |
+| ASCEND_CUSTOM_OPP_PATH | asc-devkit 算子包 | `source set_env.bash` | asc-devkit 生成 |
+
+**注意**：不要手动 export ASCEND_OPP_PATH，应使用官方 set_env.sh 脚本。
+
+## 常见错误
+
+### 错误1: 手动 export ASCEND_OPP_PATH
+**问题**: 遗漏其他必要环境变量，导致错误 561107。  
+**解决**: `source /usr/local/Ascend/cann/set_env.sh`
+
+### 错误2: 混淆包类型
+- **CANN Toolkit**: 基础包，编译+运行必需
+- **CANN Ops**: 运行态依赖，提供算子库
+- **自定义算子包**: 开发者编译生成，追加安装到 vendors 目录
+
+### 错误3: 未配置 LD_LIBRARY_PATH
+**问题**: 运行自定义算子时报错 561003（Kernel查找失败）。  
+**解决**: `export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}/op_api/lib:$LD_LIBRARY_PATH`
+
+## CANN 版本兼容性
+
+CANN 版本需与固件驱动、子包版本配套使用，无通用最低/最高版本要求。具体配套关系以官方 Release Notes 为准。
+
+### 版本信息来源
+
+| 信息 | 来源路径 |
+|------|---------|
+| CANN 版本号 | `$ASCEND_HOME_PATH/compiler/version.info` 中的 `Version` 字段 |
+| 运行时依赖基线 | 同文件中的 `required_package_runtime_version` 字段 |
+| 全量子包依赖 | 同文件中的 `required_package_*` 系列字段 |
+
+可通过 `check_env.sh` 自动检测并展示上述信息。
+
+### 官方配套关系查询
+
+- CANN 与 Ascend HDK 版本配套关系、组合包配套关系等，请查阅官方 Release Notes：https://www.hiascend.com/cann/document
+- 版本下载与快速安装：https://www.hiascend.com/cann/download
+
+### 常见版本问题
+
+| 问题 | 原因 | 解决方法 |
+|------|------|---------|
+| CANN 与驱动不配套 | 固件驱动版本与 CANN 版本不匹配 | 查阅 Release Notes 配套关系表，升级驱动或 CANN |
+| 子包版本不一致 | runtime/metadef/opbase 等子包版本不匹配 | 检查 `version.info` 中 `required_package_*` 字段，重新安装配套版本 |
+| API 不可用 | 当前 CANN 版本不支持该 API | 查阅 API 文档中的版本要求说明 |
+
+## 验证环境
+
+```bash
+bash scripts/check_env.sh
+```
+
+检查项：ASCEND_HOME_PATH、CANN 版本、ASCEND_OPP_PATH、算子安装、调试配置
+

package/assets/ops-direct-invoke/skills/ascendc-env-check/references/kirin_platform_guide.md

@@ -0,0 +1,11 @@
+# Kirin 平台开发指南
+
+Kirin 系列芯片（KirinX90、Kirin9030等以 Kirin 开头的平台）是端侧 AI 处理器，当前主要支持使用模拟器 Simulator 的开发方式，需要注意环境检查结果中的 Simulator 支持情况。
+
+当前 Kirin 开发使用的 CANN 版本和服务器有差异，Kirin 系列芯片开发，需要安装对应的 mobile-station 版本的 CANN 才有 Kirin 的 Simulator。
+
+## 参考资料
+
+- [cann-recipes-harmony-infer](https://gitcode.com/cann/cann-recipes-harmony-infer) - 鸿蒙端侧推理实践（含完整工程样例）
+- [quick_install.md](https://gitcode.com/cann/cann-recipes-harmony-infer/blob/master/docs/quick_install.md) - 环境安装指南
+- [ascendc_develop_guide.md](https://gitcode.com/cann/cann-recipes-harmony-infer/blob/master/docs/ascendc_develop_guide.md) - Ascend C 开发指南

package/assets/ops-direct-invoke/skills/ascendc-env-check/references/npu_commands.md

@@ -0,0 +1,114 @@
+# NPU 命令速查
+
+## 推荐原则
+
+> **优先使用结构化子命令（`-t` + key:value 格式），避免直接解析 `npu-smi info` 主表格输出。**
+>
+> 原因：`npu-smi info` 主表格的格式随驱动版本变化（列宽、换行、字段名等），脚本解析极易失效。`-t` 子命令返回稳定的 key:value 格式，更适合自动化处理。
+
+## 查询可用命令
+
+npu-smi 支持的命令随驱动版本变化，**请以 `--help` 输出为准**。
+
+```bash
+# 查看 npu-smi 顶层命令
+npu-smi --help
+
+# 查看 info 子命令和可用 -t type
+npu-smi info --help
+```
+
+## 稳定命令
+
+以下命令在不同版本中相对稳定：
+
+### 查看设备映射
+
+```bash
+# 获取 NPU ID 与芯片的映射关系（固定格式，脚本友好）
+npu-smi info -m
+```
+
+输出示例：
+
+```
+NPU ID    Chip ID    Chip Logic ID    Chip Name
+  5         0           0               Ascend 910B3
+```
+
+> ⚠️ **Chip Name 作为 short-soc-version 不可信**（A3 机型误报 `Ascend910`，issue #587），禁止用于芯片型号识别。芯片型号使用 `get_npu_arch.py`（asys Chip Info 优先，DSMI 兜底）。
+
+### 结构化查询（key:value 格式）
+
+```bash
+# 第一步：通过 info -m 确认设备 ID
+npu-smi info -m
+
+# 第二步：将 <device_id> 替换为实际 ID 进行查询
+npu-smi info -t <type> -i <device_id>
+```
+
+常用 type（请以 `npu-smi info --help` 输出为准）：
+
+| type | 说明 |
+|------|------|
+| `health` | 健康状态 |
+| `temp` | 温度 |
+| `power` | 功耗 |
+| `memory` | 内存容量/时钟 |
+| `usages` | 使用率（AICore、HBM 等） |
+| `common` | 批量获取（温度、功耗、AICore、HBM 等） |
+
+> ⚠️ 部分 type 在特定设备上可能不支持（返回 "This device does not support querying ..."）。
+
+### 输出格式
+
+`-t` 子命令返回 key:value 格式：
+
+```
+NPU ID                         : 5
+Chip Count                     : 1
+Health                         : OK
+Chip ID                        : 0
+```
+
+### 主表格输出（人类阅读用）
+
+```bash
+npu-smi info
+```
+
+返回表格格式：
+
+```
++------+---------------+--------+--------+--------+
+| ID   | Name          | Health | Power  | Temp   |
++------+---------------+--------+--------+--------+
+| 5    | Ascend910B3   | OK     | 125W   | 39C    |
++------+---------------+--------+--------+--------+
+```
+
+> ⚠️ **警告**：此表格格式在不同驱动版本下可能变化，**禁止在脚本中通过 awk/regex 解析此格式**。
+
+## 脚本自动化
+
+在脚本中自动获取 NPU 信息时，推荐编写 **Python 脚本** 调用结构化子命令，避免硬编码命令列表：
+
+```python
+# 获取完整设备信息（JSON 格式）
+python3 scripts/_npu_info.py --json
+
+# 列出所有设备 ID
+python3 scripts/_npu_info.py --list
+
+# 查看设备健康状态
+python3 scripts/_npu_info.py --health
+```
+
+脚本内部通过 `npu-smi info --help` **动态发现** 当前环境支持的子命令，优先使用 `npu-smi info -t common` 批量获取数据，比逐个调用 `-t` 子命令更高效。
+
+## 设备 ID 映射
+
+- 设备 ID 从 `npu-smi info -m` 第一列获取，**不一定是 0**
+- 芯片 ID（chip_id）可能与设备 ID 不同
+- 多卡环境注意配置 `ASCEND_DEVICE_ID` 环境变量