docs: 优化 README 结构，功能示例合并至 examples(#168)-oam-tools-AtomGit

已合并

docs: 优化 README 结构，功能示例合并至 examples(#168) #443

sinat_31531339创建于 7月21日从sinat_31531339/oam-tools： docs/issue-168-readme 合入到 cann/oam-tools： master

docs: 优化 README 结构，功能示例合并至 examples(#168) #443

已合并

sinat_31531339创建于 7月21日

从sinat_31531339/oam-tools docs/issue-168-readme合入到cann/oam-tools master

共 4 个文件变更+327-256

MREADME.md+54-124

	@@ -22,12 +22,12 @@ OAM-Tools（Operations, Administration, and Maintenance）是华为 CANN 的开
22		22
23	OAM-Tools 包含四大核心组件，协同覆盖昇腾 AI 处理器的运维全场景：	23	OAM-Tools 包含四大核心组件，协同覆盖昇腾 AI 处理器的运维全场景：
24		24
25	-\| 组件 \| 功能定位 \| 核心能力 \|	25	+\| 组件 \| 功能定位 \| 核心能力 \| 文档 \| 运行示例 \|
		zhangjie7月25日级别：提示问题：删除了指向华为官方在线文档的外部链接，仅保留本地文档链接。影响：如果本地文档更新不及时，用户可能无法获取最新官方信息。修复建议：建议在本地文档链接旁保留官方在线文档链接，或确保本地文档与官方同步。 sinat_31531339 9 天前评论： 9 天前评论：
26	-\| --- \| --- \| --- \|	26	+\| --- \| --- \| --- \| --- \| --- \|
27	-\| asys（故障信息收集） \| 一键式故障信息采集与诊断 \| 故障信息收集、业务复跑+信息收集、软硬件/Device 状态展示、健康检查、综合检测、组件检测、trace/coredump/stackcore/coretrace/UB 文件解析、实时堆栈导出、AI Core Error 故障信息解析、性能数据采集 \|	27	+\| asys（故障信息收集） \| 一键式故障信息采集与诊断 \| 故障信息收集、业务复跑+信息收集、软硬件/Device 状态展示、健康检查、综合检测、组件检测、trace/coredump/stackcore/coretrace/UB 文件解析、实时堆栈导出、AI Core Error 故障信息解析、性能数据采集 \| [用户指南](./docs/zh/asys/README.md) \| [示例](./examples/README.md#asys故障信息收集与诊断) \|
28	-\| msaicerr（AI Core Error 分析） \| AI Core Error 问题定位 \| AI Core Error 问题分析、Dump 文件解析与数据类型转换、运行环境检查 \|	28	+\| msaicerr（AI Core Error 分析） \| AI Core Error 问题定位 \| AI Core Error 问题分析、Dump 文件解析与数据类型转换、运行环境检查 \| [用户指南](./docs/zh/msaicerr/README.md) \| [示例](./examples/README.md#msaicerrai-core-error-分析) \|
29	-\| msprof（性能调优） \| AI 任务性能采集与分析 \| 采集 AI 任务运行性能数据、AI 处理器系统数据、Host 侧系统数据、msproftx 数据；支持动态/延迟采集；提供 ACL/Ascend Graph/acl.json/环境变量多种采集方式 \|	29	+\| msprof（性能调优） \| AI 任务性能采集与分析 \| 采集 AI 任务运行性能数据、AI 处理器系统数据、Host 侧系统数据、msproftx 数据；支持动态/延迟采集；提供 ACL/Ascend Graph/acl.json/环境变量多种采集方式 \| [用户指南](./docs/zh/profiling/README.md) \| [示例](./examples/README.md#msprof性能调优) \|
30	-\| hccl_test（HCCL 性能测试） \| 集合通信功能与性能测试 \| 分布式训练/推理场景下，基于 HCCL 单算子 API 测试集合通信的功能正确性与性能 \|	30	+\| hccl_test（HCCL 性能测试） \| 集合通信功能与性能测试 \| 分布式训练/推理场景下，基于 HCCL 单算子 API 测试集合通信的功能正确性与性能 \| [用户指南](./docs/zh/hccl_test/README.md) \| — \|
31		31
32	## 🏗️ 项目架构	32	## 🏗️ 项目架构
33		33
	@@ -57,32 +57,6 @@ oam-tools/
57	└── version.cmake # 版本与依赖声明	57	└── version.cmake # 版本与依赖声明
58	```	58	```
59		59
60	-## 🚀 快速开始
61	-
62	-### 1. 环境安装
63	-
64	-请先参考[快速安装指南](./docs/zh/quick_install.md)完成 CANN 软件包与编译依赖的安装。
65	-
66	-### 2. 编译构建
67	-
68	-编译前请先根据 CANN 安装路径加载环境变量：
69	-
70	-```bash
71	-source <CANN安装路径>/set_env.sh
72	-```
73	-
74	-> root 用户默认路径为 `/usr/local/Ascend/cann`；非 root 用户默认为 `${HOME}/Ascend/cann`；指定路径安装时为 `${install_path}/cann`。
75	-
76	-```bash
77	-bash build.sh
78	-```
79	-
80	-### 3. 安装到 CANN 目录
81	-
82	-```bash
83	-./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full
84	-```
85	-
86	## 🧩 支持的硬件环境	60	## 🧩 支持的硬件环境
87		61
88	在搭建环境之前，请先确认硬件在本工具的支持范围内，若无昇腾设备也可以通过 docker 方式编译构建（详见[快速安装](./docs/zh/quick_install.md#方式2docker部署)）。	62	在搭建环境之前，请先确认硬件在本工具的支持范围内，若无昇腾设备也可以通过 docker 方式编译构建（详见[快速安装](./docs/zh/quick_install.md#方式2docker部署)）。
	@@ -100,8 +74,45 @@ bash build.sh
100	> - "910C"是商用别称。自 CANN 8.5.0 起，ops 包统一命名为 `Ascend-cann-A3-ops_*`，请勿在包名中拼写为 `910c`、`910_c`、`910_93` 等形式。	74	> - "910C"是商用别称。自 CANN 8.5.0 起，ops 包统一命名为 `Ascend-cann-A3-ops_*`，请勿在包名中拼写为 `910c`、`910_c`、`910_93` 等形式。
101	> - 其它芯片暂不支持，欢迎提交 issue 反馈。CANN ops 包名拼接规则与下载详见[快速安装](./docs/zh/quick_install.md#方式3手动安装)。	75	> - 其它芯片暂不支持，欢迎提交 issue 反馈。CANN ops 包名拼接规则与下载详见[快速安装](./docs/zh/quick_install.md#方式3手动安装)。
102		76
		77	+## 🚀 快速开始：从零编译到验证
		78	+
		79	+以下为 root 用户默认安装路径下从零跑通的最短路径，四步即可得到可用的工具。第三方库定制、离线编译、调试构建等完整参数，以及分组件的测试验证方式，见后续的「源码编译」与「安装与验证」章节。
		80	+
		81	+### 1. 安装依赖
		82	+
		83	+参考[快速安装指南](./docs/zh/quick_install.md)完成 CANN 软件包与编译依赖的安装。
		84	+
		85	+### 2. 编译
		86	+
		87	+```bash
		88	+# 非 root 用户将 /usr/local 替换为 ${HOME}
		89	+source /usr/local/Ascend/cann/set_env.sh
		90	+bash build.sh
		91	+```
		92	+
		93	+编译产物为 `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run`（`<arch>` 为 `x86_64` 或 `aarch64`）。
		94	+
		95	+### 3. 安装
		96	+
		97	+```bash
		98	+./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full
		99	+```
		100	+
		101	+### 4. 验证
		102	+
		103	+重新加载环境变量后调用 asys，能正常打印帮助信息即表示安装成功：
		104	+
		105	+```bash
		106	+source /usr/local/Ascend/cann/set_env.sh
		107	+asys -h
		108	+```
		109	+
		110	+需要在真实环境中跑通各组件功能，见[运行示例](./examples/README.md)。
		111	+
103	## 🔧 源码编译	112	## 🔧 源码编译
104		113
		114	+### 加载环境变量
		115	+
105	编译前请先根据 CANN 安装路径加载环境变量：	116	编译前请先根据 CANN 安装路径加载环境变量：
106		117
107	```bash	118	```bash
	@@ -110,6 +121,8 @@ source <CANN安装路径>/set_env.sh
110		121
111	> root 用户默认路径为 `/usr/local/Ascend/cann`；非 root 用户默认为 `${HOME}/Ascend/cann`；指定路径安装时为 `${install_path}/cann`。	122	> root 用户默认路径为 `/usr/local/Ascend/cann`；非 root 用户默认为 `${HOME}/Ascend/cann`；指定路径安装时为 `${install_path}/cann`。
112		123
		124	+### 执行编译
		125	+
113	执行以下命令进行编译：	126	执行以下命令进行编译：
114		127
115	```bash	128	```bash
	@@ -122,6 +135,8 @@ bash build.sh
122	bash build.sh --cann_3rd_lib_path=${third_party_path}	135	bash build.sh --cann_3rd_lib_path=${third_party_path}
123	```	136	```
124		137
		138	+### 编译参数与依赖说明
		139	+
125	- `--cann_3rd_lib_path`：第三方库存储目录，默认值为 `./third_party`。若本地不存在第三方库，编译脚本将自动从 gitcode 开源仓库下载各第三方库源码。	140	- `--cann_3rd_lib_path`：第三方库存储目录，默认值为 `./third_party`。若本地不存在第三方库，编译脚本将自动从 gitcode 开源仓库下载各第三方库源码。
126	- 编译过程中会自动下载闭源二进制包，该包含有保证功能正常运行所需的库及头文件，且仅提供 release 版本，即使编译选项指定为 debug，也只会下载 release 版本的 tar 包。	141	- 编译过程中会自动下载闭源二进制包，该包含有保证功能正常运行所需的库及头文件，且仅提供 release 版本，即使编译选项指定为 debug，也只会下载 release 版本的 tar 包。
127	- 闭源二进制包按分支拉取：不指定时，编译脚本会依据当前 git 提交自动探测所属发布分支（从 `master` 拉出的分支拉 master 包，从 9.1.0 线拉出的分支拉 9.1.0 包），探测不出时回退 `master`。也可通过 `--bundle_branch=<NAME>` 显式指定分支，个人分支探测不准时建议显式指定。当前 OBS 上提供包的分支为 `master` 与 `9.1.0`；指定其它分支会在配置阶段报错。	142	- 闭源二进制包按分支拉取：不指定时，编译脚本会依据当前 git 提交自动探测所属发布分支（从 `master` 拉出的分支拉 master 包，从 9.1.0 线拉出的分支拉 9.1.0 包），探测不出时回退 `master`。也可通过 `--bundle_branch=<NAME>` 显式指定分支，个人分支探测不准时建议显式指定。当前 OBS 上提供包的分支为 `master` 与 `9.1.0`；指定其它分支会在配置阶段报错。
	@@ -166,11 +181,11 @@ bash build.sh -u --component msprof
166	\| --- \| --- \| --- \| --- \|	181	\| --- \| --- \| --- \| --- \|
167	\| `asys` \| asys Python UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[环境变量配置](./docs/zh/quick_install.md#环境变量配置) \| `bash build.sh -u --component asys` \|	182	\| `asys` \| asys Python UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[环境变量配置](./docs/zh/quick_install.md#环境变量配置) \| `bash build.sh -u --component asys` \|
168	\| `msaicerr` \| msaicerr Python UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[环境变量配置](./docs/zh/quick_install.md#环境变量配置) \| `bash build.sh -u --component msaicerr` \|	183	\| `msaicerr` \| msaicerr Python UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[环境变量配置](./docs/zh/quick_install.md#环境变量配置) \| `bash build.sh -u --component msaicerr` \|
169	-\| `msprof` \| msprof C++ gtest UT \| [源码编译](#-源码编译)、[离线编译环境准备](./docs/zh/quick_install.md#离线编译环境准备) \| `bash build.sh -u --component msprof --ut` \|	184	+\| `msprof` \| msprof C++ gtest UT \| [源码编译](#执行编译)、[离线编译环境准备](./docs/zh/quick_install.md#离线编译环境准备) \| `bash build.sh -u --component msprof --ut` \|
170	-\| `install` \| 安装包安装 ST \| [源码编译](#-源码编译)、[安装](#安装) \| `bash build.sh -u --component install --st` \|	185	+\| `install` \| 安装包安装 ST \| [源码编译](#执行编译)、[安装](#安装) \| `bash build.sh -u --component install --st` \|
171	-\| `upgrade` \| 安装包升级 ST \| [源码编译](#-源码编译)、[安装](#安装) \| `bash build.sh -u --component upgrade --st` \|	186	+\| `upgrade` \| 安装包升级 ST \| [源码编译](#执行编译)、[安装](#安装) \| `bash build.sh -u --component upgrade --st` \|
172	-\| `uninstall` \| 安装包卸载 ST \| [源码编译](#-源码编译)、[安装](#安装) \| `bash build.sh -u --component uninstall --st` \|	187	+\| `uninstall` \| 安装包卸载 ST \| [源码编译](#执行编译)、[安装](#安装) \| `bash build.sh -u --component uninstall --st` \|
173	-\| `all` \| 全部可用 UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[源码编译](#-源码编译) \| `bash build.sh -u` \|	188	+\| `all` \| 全部可用 UT + ST \| [环境准备](./docs/zh/quick_install.md#环境准备)、[源码编译](#执行编译) \| `bash build.sh -u` \|
174		189
175	> `install`、`upgrade`、`uninstall` 仅包含 ST，用例依赖 `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run`。推荐通过上表中的 `build.sh -u --component ... --st` 运行，脚本会先完成构建打包；若直接执行 `scripts/run_tests.sh`，需先确保 `build_out/` 下已有可用 `.run` 包。	190	> `install`、`upgrade`、`uninstall` 仅包含 ST，用例依赖 `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run`。推荐通过上表中的 `build.sh -u --component ... --st` 运行，脚本会先完成构建打包；若直接执行 `scripts/run_tests.sh`，需先确保 `build_out/` 下已有可用 `.run` 包。
176		191
	@@ -180,100 +195,15 @@ UT 测试用例编译输出目录为 `build`，如果想清除历史编译记录
180	rm -rf build_out/ build/	195	rm -rf build_out/ build/
181	```	196	```
182		197
183	-## ▶️ 功能运行示例
184	-
185	-完成安装后，工具会被释放到 CANN 安装目录下的 `tools/` 子目录（root 用户默认在 `/usr/local/Ascend/cann/tools/`）。运行示例前请先加载环境变量：
186	-
187	-```bash
188	-# root 用户默认路径；非 root 用户将 /usr/local 替换为 ${HOME}
189	-source /usr/local/Ascend/cann/set_env.sh
190	-# 指定路径安装时：source ${install_path}/cann/set_env.sh
191	-```
192	-
193	-> 执行上方命令后，`${ASCEND_INSTALL_PATH}` 即为 CANN 安装目录：
194	->
195	-> - root 用户默认：`/usr/local/Ascend/cann`
196	-> - 非 root 用户默认：`${HOME}/Ascend/cann`
197	-> - 指定路径安装：`${install_path}/cann`
198	-
199	-### asys（故障信息收集 / 诊断）
200	-
201	-`src/asys/` 目录下同时存在 `asys.py` 和指向它的软链接 `asys`（`src/asys/asys -> ./asys.py`），CMake 通过 `install(DIRECTORY ${ASYS_DIR} ...)` 将整个目录原样拷贝，软链接也会保留。因此安装后两种调用都能直接用：
202	-
203	-```bash
204	-# 形式一：显式 python3 调用 .py
205	-python3 ${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys.py -h
206	-
207	-# 形式二：直接调用软链接 asys（asys.py 自带 #!/usr/bin/env python3 shebang）
208	-${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys -h
209	-```
210	-
211	-asys 的子命令在 `src/asys/cmdline/cmd_parser.py` 的 `Command` 枚举中定义，包含 `info / health / collect / launch / diagnose / analyze / config / profiling`。在环境变量加载生效后，可以直接以 asys 调用：
212	-
213	-```bash
214	-# 采集主机与 device 的软硬件信息（不依赖待诊断任务，通常作为环境自检）
215	-asys info -r="status" -d=0
216	-
217	-# 体检 device 健康状态
218	-asys health
219	-
220	-# 采集环境中已存在的运维信息并打包到指定输出目录
221	-asys collect --output <output_dir>
222	-```
223	-
224	-### msaicerr（AI Core Error 分析）
225	-
226	-msaicerr 入口为 `src/msaicerr/msaicerr.py`，安装后位于 `${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py`。
227	-
228	-```bash
229	-# 1) 解析一个已有的 AI Core Error 报告路径，结果输出到 <output_dir>
230	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0
231	-
232	-# 2) 解析单个 dump 文件（dtype 取值参见 -h 输出）
233	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16
234	-
235	-# 3) 检测当前环境是否具备运行 msaicerr 所需的条件（仅依赖 device 编号）
236	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -e -dev 0
237	-
238	-# 完整参数说明
239	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -h
240	-```
241	-
242	-### msprof（性能调优）
243	-
244	-msprof 由 C++ 侧 collector（`basic`、`dvvp`）和 `msprof` Python wheel（分析脚本）组成。`bash build.sh` 完成后，wheel（`msprof-0.0.1-py3-none-any.whl`）会被拷贝到 `src/msprof/collector/dvvp/msprofbin/` 并打包进 `.run` 安装包；安装时自动解包到 `${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/` 目录下，无需手动 `pip install`。
245	-
246	-分析脚本由 msprof collector 流水线内部调用（入口为 `profiler_tool/analysis/msprof/msprof.py`），不会在 `PATH` 中注册独立的命令行命令。如需手动运行分析脚本，可直接以 python3 调用安装目录下的入口：
247	-
248	-```bash
249	-python3 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h
250	-```
251	-
252	-C++ 侧 collector 一般作为 CANN profiler 流水线的内置组件被调用，开发者无需直接执行；回归通过 `bash build.sh -u --component msprof` 运行 gtest 用例（产物 `build/test/ut/msprof/msprofbin/msprof_bin_utest`）。
253	-
254	## 🅿️ Pre-commit	198	## 🅿️ Pre-commit
255		199
256	pre-commit 是一个用于管理和维护 Git 预提交钩子（hooks）的框架，通过在代码提交前自动化执行代码检查、格式化和安全扫描，确保代码质量并统一团队规范，显著减少 CI/CD 流水线失败并提升协作效率。	200	pre-commit 是一个用于管理和维护 Git 预提交钩子（hooks）的框架，通过在代码提交前自动化执行代码检查、格式化和安全扫描，确保代码质量并统一团队规范，显著减少 CI/CD 流水线失败并提升协作效率。
257	本仓已配置 pre-commit，用户可以参考 CANN 社区的[pre-commit 配置指导书中第 3 章节](https://gitcode.com/cann/infrastructure/blob/main/docs/SC/pre-commit/pre-commit%E9%85%8D%E7%BD%AE%E6%8C%87%E5%AF%BC%E4%B9%A6.md#3-%E7%A4%BE%E5%8C%BA%E8%B4%A1%E7%8C%AE%E8%80%85%E4%BD%BF%E7%94%A8pre-commit%E8%83%BD%E5%8A%9B)安装 pre-commit。OAT 检查工具已改用 Python 版本 oat-py（通过 `pip install oat-py>=1.0.0` 安装），无需配置 Java/Maven 环境；首次运行时 pre-commit 会为各 hook 创建隔离的虚拟环境，耗时稍长。	201	本仓已配置 pre-commit，用户可以参考 CANN 社区的[pre-commit 配置指导书中第 3 章节](https://gitcode.com/cann/infrastructure/blob/main/docs/SC/pre-commit/pre-commit%E9%85%8D%E7%BD%AE%E6%8C%87%E5%AF%BC%E4%B9%A6.md#3-%E7%A4%BE%E5%8C%BA%E8%B4%A1%E7%8C%AE%E8%80%85%E4%BD%BF%E7%94%A8pre-commit%E8%83%BD%E5%8A%9B)安装 pre-commit。OAT 检查工具已改用 Python 版本 oat-py（通过 `pip install oat-py>=1.0.0` 安装），无需配置 Java/Maven 环境；首次运行时 pre-commit 会为各 hook 创建隔离的虚拟环境，耗时稍长。
258		202
259	-## 📚 相关文档
260	-
261	-### 组件用户指南
262	-
263	-\| 组件 \| 文档链接 \| 说明 \|
264	-\| --- \| --- \| --- \|
265	-\| asys \| [asys 工具用户指南](https://hiascend.com/document/redirect/CannCommunityasys) \| 故障信息收集、业务复跑+故障信息收集、软硬件和 Device 状态信息展示、健康检查、综合检测、组件检测、trace/coredump/stackcore/coretrace/UB 文件解析、实时堆栈导出、环境配置、AI Core Error 故障信息解析等 \|
266	-\| msaicerr \| [msaicerr 工具用户指南](https://hiascend.com/document/redirect/CannCommunitymsaicerr) \| 分析 AI Core Error 问题、解析 Dump 文件、检查环境等 \|
267	-\| msprof \| [性能调优工具用户指南](https://www.hiascend.com/document/redirect/CannCommunityToolProfiling) \| 采集和分析昇腾 AI 处理器上 AI 任务各运行阶段的关键性能指标，定位软、硬件性能瓶颈 \|
268	-\| hccl_test \| [HCCL 性能测试工具用户指南](https://www.hiascend.com/document/redirect/CannCommunityToolHcclTest) \| 分布式训练或推理场景下，测试集合通信的功能与性能 \|
269	-
270	-### 其他文档
271	-
272	-- [快速安装指南](./docs/zh/quick_install.md)
273	-- [环境变量参考](https://hiascend.com/document/redirect/CannCommunityEnvRef)
274	-
275	## ℹ️ 相关信息	203	## ℹ️ 相关信息
276		204
		205	+- [快速安装指南](./docs/zh/quick_install.md)：CANN 软件包与编译依赖的安装
		206	+- [环境变量参考](https://hiascend.com/document/redirect/CannCommunityEnvRef)
277	- [贡献指南](CONTRIBUTING.md)：社区贡献流程与规范	207	- [贡献指南](CONTRIBUTING.md)：社区贡献流程与规范
278	- [安全声明](SECURITY.md)	208	- [安全声明](SECURITY.md)
279	- [许可证](LICENSE)	209	- [许可证](LICENSE)

MREADME_en.md+57-125

	@@ -22,12 +22,14 @@ OAM-Tools (Operations, Administration, and Maintenance) is an open-source operat
22		22
23	OAM-Tools includes four core components that collaboratively cover the full O&M scenario for Ascend AI processors:	23	OAM-Tools includes four core components that collaboratively cover the full O&M scenario for Ascend AI processors:
24		24
25	-\| Component \| Purpose \| Key Capabilities \|	25	+\| Component \| Purpose \| Key Capabilities \| Documentation \| Examples \|
26	-\| --- \| --- \| --- \|	26	+\| --- \| --- \| --- \| --- \| --- \|
27	-\| asys (Fault Information Collection) \| One-click fault information collection and diagnosis \| Fault information collection, business rerun with info collection, software/hardware & Device status display, health check, comprehensive detection, component detection, trace/coredump/stackcore/coretrace/UB file parsing, real-time stack export, AI Core Error fault info parsing, performance data collection \|	27	+\| asys (Fault Information Collection) \| One-click fault information collection and diagnosis \| Fault information collection, business rerun with info collection, software/hardware & Device status display, health check, comprehensive detection, component detection, trace/coredump/stackcore/coretrace/UB file parsing, real-time stack export, AI Core Error fault info parsing, performance data collection \| [User Guide](./docs/zh/asys/README.md) \| [Examples](./examples/README_en.md#asys-fault-information-collection-and-diagnosis) \|
		L L lwx125555519 天前这里的链接，等英文的手册上线后要修改成对应的英文链接。 sinat_31531339 9 天前评论： 9 天前评论：
28	-\| msaicerr (AI Core Error Analysis) \| AI Core Error problem localization \| AI Core Error problem analysis, Dump file parsing and data type conversion, runtime environment check \|	28	+\| msaicerr (AI Core Error Analysis) \| AI Core Error problem localization \| AI Core Error problem analysis, Dump file parsing and data type conversion, runtime environment check \| [User Guide](./docs/zh/msaicerr/README.md) \| [Examples](./examples/README_en.md#msaicerr-ai-core-error-analysis) \|
29	-\| msprof (Performance Tuning) \| AI task performance collection and analysis \| Collect AI task runtime performance data, AI processor system data, Host-side system data, msproftx data; support dynamic/delayed collection; provide ACL/Ascend Graph/acl.json/environment variable collection methods \|	29	+\| msprof (Performance Tuning) \| AI task performance collection and analysis \| Collect AI task runtime performance data, AI processor system data, Host-side system data, msproftx data; support dynamic/delayed collection; provide ACL/Ascend Graph/acl.json/environment variable collection methods \| [User Guide](./docs/zh/profiling/README.md) \| [Examples](./examples/README_en.md#msprof-performance-tuning) \|
30	-\| hccl_test (HCCL Performance Test) \| Collective communication functionality and performance testing \| Test collective communication functionality and performance based on HCCL single-operator API in distributed training/inference scenarios \|	30	+\| hccl_test (HCCL Performance Test) \| Collective communication functionality and performance testing \| Test collective communication functionality and performance based on HCCL single-operator API in distributed training/inference scenarios \| [User Guide](./docs/zh/hccl_test/README.md) \| — \|
		31	+
		32	+> Component user guides are currently available in Chinese only (`docs/zh/`); English translations are in progress.
31		33
32	## 🏗️ Project Architecture	34	## 🏗️ Project Architecture
33		35
	@@ -57,32 +59,6 @@ oam-tools/
57	└── version.cmake # Version and dependency declaration	59	└── version.cmake # Version and dependency declaration
58	```	60	```
59		61
60	-## 🚀 Quick Start
61	-
62	-### 1. Environment Installation
63	-
64	-Please refer to the [Quick Installation Guide](./docs/en/quick_install.md) to complete the installation of CANN software packages and build dependencies.
65	-
66	-### 2. Build
67	-
68	-Load the environment variables from your CANN installation path before building:
69	-
70	-```bash
71	-source <CANN_install_path>/set_env.sh
72	-```
73	-
74	-> Default path is `/usr/local/Ascend/cann` for root users, `${HOME}/Ascend/cann` for non-root users, and `${install_path}/cann` for custom installation paths.
75	-
76	-```bash
77	-bash build.sh
78	-```
79	-
80	-### 3. Install to CANN Directory
81	-
82	-```bash
83	-./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full
84	-```
85	-
86	## 🧩 Supported Hardware	62	## 🧩 Supported Hardware
87		63
88	Before setting up the environment, confirm that your hardware is within the supported scope. If you do not have Ascend devices, you can still build via Docker (see [Quick Installation](docs/en/quick_install.md#method-2-docker-deployment)).	64	Before setting up the environment, confirm that your hardware is within the supported scope. If you do not have Ascend devices, you can still build via Docker (see [Quick Installation](docs/en/quick_install.md#method-2-docker-deployment)).
	@@ -100,8 +76,45 @@ Before setting up the environment, confirm that your hardware is within the supp
100	> - "910C" is a commercial alias. Since CANN 8.5.0, the ops package is uniformly named `Ascend-cann-A3-ops_*`. Do not use `910c`, `910_c`, or `910_93` in the package name.	76	> - "910C" is a commercial alias. Since CANN 8.5.0, the ops package is uniformly named `Ascend-cann-A3-ops_*`. Do not use `910c`, `910_c`, or `910_93` in the package name.
101	> - Other chips are not yet supported — please open an issue. The full ops package naming convention and download instructions are in [Quick Installation](docs/en/quick_install.md#method-3-manual-installation).	77	> - Other chips are not yet supported — please open an issue. The full ops package naming convention and download instructions are in [Quick Installation](docs/en/quick_install.md#method-3-manual-installation).
102		78
		79	+## 🚀 Quick Start: From Source to a Verified Install
		80	+
		81	+The shortest path from zero to a working install, using the default root installation path — four steps to a usable toolkit. For third-party library customization, offline builds, debug builds and other full build options, plus per-component test verification, see the "Source Code Compilation" and "Installation and Verification" sections below.
		82	+
		83	+### 1. Install Dependencies
		84	+
		85	+Follow the [Quick Installation Guide](./docs/en/quick_install.md) to install the CANN software packages and build dependencies.
		86	+
		87	+### 2. Build
		88	+
		89	+```bash
		90	+# For non-root users, replace /usr/local with ${HOME}
		91	+source /usr/local/Ascend/cann/set_env.sh
		92	+bash build.sh
		93	+```
		94	+
		95	+The build produces `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run` (`<arch>` is `x86_64` or `aarch64`).
		96	+
		97	+### 3. Install
		98	+
		99	+```bash
		100	+./build_out/cann-oam-tools_<cann_version>_linux-<arch>.run --full
		101	+```
		102	+
		103	+### 4. Verify
		104	+
		105	+Reload the environment variables and invoke asys — printing the help output means the installation succeeded:
		106	+
		107	+```bash
		108	+source /usr/local/Ascend/cann/set_env.sh
		109	+asys -h
		110	+```
		111	+
		112	+To exercise each component in a real environment, see the [usage examples](./examples/README_en.md).
		113	+
103	## 🔧 Source Code Compilation	114	## 🔧 Source Code Compilation
104		115
		116	+### Loading Environment Variables
		117	+
105	Load the environment variables from your CANN installation path before compiling:	118	Load the environment variables from your CANN installation path before compiling:
106		119
107	```bash	120	```bash
	@@ -110,6 +123,8 @@ source <CANN_install_path>/set_env.sh
110		123
111	> Default path is `/usr/local/Ascend/cann` for root users, `${HOME}/Ascend/cann` for non-root users, and `${install_path}/cann` for custom installation paths.	124	> Default path is `/usr/local/Ascend/cann` for root users, `${HOME}/Ascend/cann` for non-root users, and `${install_path}/cann` for custom installation paths.
112		125
		126	+### Running the Build
		127	+
113	Run the following command to compile the project:	128	Run the following command to compile the project:
114		129
115	```bash	130	```bash
	@@ -122,6 +137,8 @@ To specify a third-party library path, use the `--cann_3rd_lib_path` parameter:
122	bash build.sh --cann_3rd_lib_path=${third_party_path}	137	bash build.sh --cann_3rd_lib_path=${third_party_path}
123	```	138	```
124		139
		140	+### Build Parameters and Dependencies
		141	+
125	Parameters:	142	Parameters:
126	- `--cann_3rd_lib_path`: The directory for storing third-party libraries. The default value is `./third_party`. If third-party libraries do not exist locally, the build script automatically downloads the source code of each third-party library from the gitcode open source repository.	143	- `--cann_3rd_lib_path`: The directory for storing third-party libraries. The default value is `./third_party`. If third-party libraries do not exist locally, the build script automatically downloads the source code of each third-party library from the gitcode open source repository.
127	- The build process automatically downloads closed-source binary packages that contain the libraries and header files required for normal operation. Only release versions are provided. Even if the build option specifies debug, only the release version tar package is downloaded.	144	- The build process automatically downloads closed-source binary packages that contain the libraries and header files required for normal operation. Only release versions are provided. Even if the build option specifies debug, only the release version tar package is downloaded.
	@@ -167,11 +184,11 @@ The `--component` options map to the test scope and setup documentation as follo
167	\| --- \| --- \| --- \| --- \|	184	\| --- \| --- \| --- \| --- \|
168	\| `asys` \| asys Python UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Environment Variable Configuration](docs/en/quick_install.md#environment-variable-configuration) \| `bash build.sh -u --component asys` \|	185	\| `asys` \| asys Python UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Environment Variable Configuration](docs/en/quick_install.md#environment-variable-configuration) \| `bash build.sh -u --component asys` \|
169	\| `msaicerr` \| msaicerr Python UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Environment Variable Configuration](docs/en/quick_install.md#environment-variable-configuration) \| `bash build.sh -u --component msaicerr` \|	186	\| `msaicerr` \| msaicerr Python UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Environment Variable Configuration](docs/en/quick_install.md#environment-variable-configuration) \| `bash build.sh -u --component msaicerr` \|
170	-\| `msprof` \| msprof C++ gtest UT \| [Source Code Compilation](#-source-code-compilation), [Offline Build Environment Preparation](docs/en/quick_install.md#offline-build-environment-preparation) \| `bash build.sh -u --component msprof --ut` \|	187	+\| `msprof` \| msprof C++ gtest UT \| [Source Code Compilation](#running-the-build), [Offline Build Environment Preparation](docs/en/quick_install.md#offline-build-environment-preparation) \| `bash build.sh -u --component msprof --ut` \|
171	-\| `install` \| Package installation ST \| [Source Code Compilation](#-source-code-compilation), [Installation](#installation) \| `bash build.sh -u --component install --st` \|	188	+\| `install` \| Package installation ST \| [Source Code Compilation](#running-the-build), [Installation](#installation) \| `bash build.sh -u --component install --st` \|
172	-\| `upgrade` \| Package upgrade ST \| [Source Code Compilation](#-source-code-compilation), [Installation](#installation) \| `bash build.sh -u --component upgrade --st` \|	189	+\| `upgrade` \| Package upgrade ST \| [Source Code Compilation](#running-the-build), [Installation](#installation) \| `bash build.sh -u --component upgrade --st` \|
173	-\| `uninstall` \| Package uninstallation ST \| [Source Code Compilation](#-source-code-compilation), [Installation](#installation) \| `bash build.sh -u --component uninstall --st` \|	190	+\| `uninstall` \| Package uninstallation ST \| [Source Code Compilation](#running-the-build), [Installation](#installation) \| `bash build.sh -u --component uninstall --st` \|
174	-\| `all` \| All available UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Source Code Compilation](#-source-code-compilation) \| `bash build.sh -u` \|	191	+\| `all` \| All available UT + ST \| [Environment Preparation](docs/en/quick_install.md#environment-preparation), [Source Code Compilation](#running-the-build) \| `bash build.sh -u` \|
175		192
176	> `install`, `upgrade`, and `uninstall` contain ST only and depend on `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run`. Use the `build.sh -u --component ... --st` commands in the table so the package is built first. If you run `scripts/run_tests.sh` directly, make sure a usable `.run` package already exists under `build_out/`.	193	> `install`, `upgrade`, and `uninstall` contain ST only and depend on `build_out/cann-oam-tools_<cann_version>_linux-<arch>.run`. Use the `build.sh -u --component ... --st` commands in the table so the package is built first. If you run `scripts/run_tests.sh` directly, make sure a usable `.run` package already exists under `build_out/`.
177		194
	@@ -181,101 +198,16 @@ The UT test case compilation output directory is `build`. To clear historical bu
181	rm -rf build_out/ build/	198	rm -rf build_out/ build/
182	```	199	```
183		200
184	-## ▶️ Usage Examples
185	-
186	-After installation, the tools are extracted to the `tools/` subdirectory under the CANN installation directory (root user default: `/usr/local/Ascend/cann/tools/`). Load the environment variables before running any example:
187	-
188	-```bash
189	-# Root user default path; for non-root users, replace /usr/local with ${HOME}
190	-source /usr/local/Ascend/cann/set_env.sh
191	-# For a custom install path: source ${install_path}/cann/set_env.sh
192	-```
193	-
194	-> After running the commands above, `${ASCEND_INSTALL_PATH}` is set to the CANN installation directory:
195	->
196	-> - Root user default: `/usr/local/Ascend/cann`
197	-> - Non-root user default: `${HOME}/Ascend/cann`
198	-> - Custom installation path: `${install_path}/cann`
199	-
200	-### asys (Fault Information Collection / Diagnosis)
201	-
202	-The `src/asys/` directory contains both `asys.py` and a symlink `asys` pointing to it (`src/asys/asys -> ./asys.py`). CMake copies the whole directory as-is via `install(DIRECTORY ${ASYS_DIR} ...)`, so the symlink is preserved. After installation, both forms work directly:
203	-
204	-```bash
205	-# Form 1: explicit python3 call on the .py file
206	-python3 ${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys.py -h
207	-
208	-# Form 2: call the symlink asys directly (asys.py has a #!/usr/bin/env python3 shebang)
209	-${ASCEND_INSTALL_PATH}/tools/ascend_system_advisor/asys/asys -h
210	-```
211	-
212	-The asys subcommands are defined in the `Command` enum in `src/asys/cmdline/cmd_parser.py`, and include `info / health / collect / launch / diagnose / analyze / config / profiling`. Once the environment variables have taken effect, you can call asys directly:
213	-
214	-```bash
215	-# Collect host and device software/hardware info (does not depend on the task under diagnosis; usually used as an environment self-check)
216	-asys info -r="status" -d=0
217	-
218	-# Check device health status
219	-asys health
220	-
221	-# Collect existing O&M information in the environment and package it to the specified output directory
222	-asys collect --output <output_dir>
223	-```
224	-
225	-### msaicerr (AI Core Error Analysis)
226	-
227	-The msaicerr entry point is `src/msaicerr/msaicerr.py`, installed at `${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py`.
228	-
229	-```bash
230	-# 1) Parse an existing AI Core Error report path, output results to <output_dir>
231	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0
232	-
233	-# 2) Parse a single dump file (dtype values: see -h output)
234	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16
235	-
236	-# 3) Check whether the current environment meets the requirements for running msaicerr (only depends on the device id)
237	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -e -dev 0
238	-
239	-# Full parameter description
240	-python3 ${ASCEND_INSTALL_PATH}/tools/msaicerr/msaicerr.py -h
241	-```
242	-
243	-### msprof (Performance Tuning)
244	-
245	-msprof consists of the C++ side collectors (`basic`, `dvvp`) and the `msprof` Python wheel (analysis scripts). After `bash build.sh` completes, the wheel (`msprof-0.0.1-py3-none-any.whl`) is copied to `src/msprof/collector/dvvp/msprofbin/` and packaged into the `.run` installation package. It is automatically unpacked to `${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/` during installation, so no manual `pip install` is required.
246	-
247	-The analysis scripts are called internally by the msprof collector pipeline (entry point: `profiler_tool/analysis/msprof/msprof.py`) and do not register a standalone command-line command in `PATH`. To run the analysis script manually, call the entry point in the installation directory with python3:
248	-
249	-```bash
250	-python3 ${ASCEND_INSTALL_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h
251	-```
252	-
253	-The C++ side collectors are generally invoked as built-in components of the CANN profiler pipeline, so developers do not need to execute them directly. For regression, run the gtest cases via `bash build.sh -u --component msprof` (output artifact: `build/test/ut/msprof/msprofbin/msprof_bin_utest`).
254	-
255	## 🅿️ Pre-commit	201	## 🅿️ Pre-commit
256		202
257	Pre-commit is a framework for managing and maintaining Git pre-commit hooks. By automatically executing code checks, formatting, and security scans before code submission, pre-commit ensures code quality and unifies team standards. This significantly reduces CI/CD pipeline failures and improves collaboration efficiency.	203	Pre-commit is a framework for managing and maintaining Git pre-commit hooks. By automatically executing code checks, formatting, and security scans before code submission, pre-commit ensures code quality and unifies team standards. This significantly reduces CI/CD pipeline failures and improves collaboration efficiency.
258		204
259	This repository has configured pre-commit. Users can refer to [Chapter 3 of the pre-commit configuration guide](https://gitcode.com/cann/infrastructure/blob/main/docs/SC/pre-commit/pre-commit%E9%85%8D%E7%BD%AE%E6%8C%87%E5%AF%BC%E4%B9%A6.md#3-%E7%A4%BE%E5%8C%BA%E8%B4%A1%E7%8C%AE%E8%80%85%E4%BD%BF%E7%94%A8pre-commit%E8%83%BD%E5%8A%9B) in the CANN community to install pre-commit. The OAT check tool has switched to the Python version oat-py (installed via `pip install oat-py>=1.0.0`), eliminating the need for Java/Maven environment configuration. The first run takes slightly longer as pre-commit creates isolated virtual environments for each hook.	205	This repository has configured pre-commit. Users can refer to [Chapter 3 of the pre-commit configuration guide](https://gitcode.com/cann/infrastructure/blob/main/docs/SC/pre-commit/pre-commit%E9%85%8D%E7%BD%AE%E6%8C%87%E5%AF%BC%E4%B9%A6.md#3-%E7%A4%BE%E5%8C%BA%E8%B4%A1%E7%8C%AE%E8%80%85%E4%BD%BF%E7%94%A8pre-commit%E8%83%BD%E5%8A%9B) in the CANN community to install pre-commit. The OAT check tool has switched to the Python version oat-py (installed via `pip install oat-py>=1.0.0`), eliminating the need for Java/Maven environment configuration. The first run takes slightly longer as pre-commit creates isolated virtual environments for each hook.
260		206
261	-## 📚 Related Documentation
262	-
263	-### Component User Guides
264	-
265	-\| Component \| Documentation Link \| Description \|
266	-\| --- \| --- \| --- \|
267	-\| asys \| [asys Tool User Guide](https://hiascend.com/document/redirect/CannCommunityasys) \| Fault information collection, business rerun with fault information collection, software/hardware and Device status information display, health check, comprehensive detection, component detection, trace/coredump/stackcore/coretrace/UB file parsing, real-time stack export, environment configuration, AI Core Error fault information parsing \|
268	-\| msaicerr \| [msaicerr Tool User Guide](https://hiascend.com/document/redirect/CannCommunitymsaicerr) \| Analyzing AI Core Error issues, parsing Dump files, checking environments \|
269	-\| msprof \| [Performance Tuning Tool User Guide](https://www.hiascend.com/document/redirect/CannCommunityToolProfiling) \| Collect and analyze key performance indicators of AI tasks running on Ascend AI processors at various running stages, enabling quick identification of software and hardware performance bottlenecks \|
270	-\| hccl_test \| [HCCL Performance Test Tool User Guide](https://www.hiascend.com/document/redirect/CannCommunityToolHcclTest) \| Testing collective communication functionality and performance in distributed training or inference scenarios \|
271	-
272	-### Other Documentation
273	-
274	-- [Quick Installation Guide](docs/en/quick_install.md)
275	-- [Environment Variable Reference](https://hiascend.com/document/redirect/CannCommunityEnvRef)
276	-
277	## ℹ️ Related Information	207	## ℹ️ Related Information
278		208
279	-- [Contributing Guide](CONTRIBUTING_en.md)	209	+- [Quick Installation Guide](./docs/en/quick_install.md): Installation of CANN software packages and build dependencies
		210	+- [Environment Variable Reference](https://hiascend.com/document/redirect/CannCommunityEnvRef)
		211	+- [Contributing Guide](CONTRIBUTING_en.md): Community contribution process and standards
280	- [Security Statement](SECURITY_en.md)	212	- [Security Statement](SECURITY_en.md)
281	- [License](LICENSE)	213	- [License](LICENSE)

Mexamples/README.md+107-7

	@@ -1,9 +1,109 @@
1	-# 简介	1	+# 功能运行示例
2		2
3	-本项目提供不同场景的调用样例，搭建完环境后，可以根据实际场景尝试运行：	3	+本目录提供 OAM-Tools 各组件的开箱即用调用样例。完成[编译](../README.md#执行编译)与[安装](../README.md#安装)后，即可参考本文在真实环境中运行示例，快速验证工具功能。
4		4
5	-\| 样例 \| 说明 \|	5	+## 目录
6	-\| ------ \|------ \|	6	+
7	-\| asys信息 \| 使用asys基础命令，入门首选 \|	7	+- [环境准备](#环境准备)
8	-\| msaicerr环境检测 \| 运行内置sample算子验证软硬件环境，装完即跑 \|	8	+- [一键运行脚本](#一键运行脚本)
9	-\| msprof系统采集 \| 采集5秒系统级CPU/内存性能数据，装完即跑 \|	9	+- [asys（故障信息收集与诊断）](#asys故障信息收集与诊断)
		10	+- [msaicerr（AI Core Error 分析）](#msaicerrai-core-error-分析)
		11	+- [msprof（性能调优）](#msprof性能调优)
		12	+
		13	+## 环境准备
		14	+
		15	+完成安装后，工具会被释放到 CANN 安装目录下的 `tools/` 子目录（root 用户默认在 `/usr/local/Ascend/cann/tools/`）。运行示例前请先加载环境变量：
		16	+
		17	+```bash
		18	+# root 用户默认路径；非 root 用户将 /usr/local 替换为 ${HOME}
		19	+source /usr/local/Ascend/cann/set_env.sh
		20	+# 指定路径安装时：source ${install_path}/cann/set_env.sh
		21	+```
		22	+
		23	+> 执行上方命令后，`${ASCEND_HOME_PATH}` 即为 CANN 安装目录：
		24	+>
		25	+> - root 用户默认：`/usr/local/Ascend/cann`
		26	+> - 非 root 用户默认：`${HOME}/Ascend/cann`
		27	+> - 指定路径安装：`${install_path}/cann`
		28	+
		29	+## 一键运行脚本
		30	+
		zhangjie7月25日级别：严重问题：文档引用了 deploy.sh、asys/run.sh 等脚本，但 PR diff 中未包含这些文件的创建。影响：用户按照文档执行 bash deploy.sh 等命令时会因找不到文件而失败。修复建议：在本 PR 中补充提交这些脚本文件，或移除对不存在脚本的引用。 sinat_31531339 9 天前评论： 9 天前评论：
		31	+本目录下为各场景预置了可直接执行的脚本，加载环境变量后即可运行：
		32	+
		33	+\| 脚本 \| 说明 \|
		34	+\| --- \| --- \|
		35	+\| [`asys/run.sh`](./asys/run.sh) \| 使用 asys 基础命令体检 device 健康状态，入门首选 \|
		36	+\| [`msaicerr/run.sh`](./msaicerr/run.sh) \| 运行内置 sample 算子检测软硬件环境是否具备 msaicerr 运行条件，装完即跑 \|
		37	+\| [`msprof/run.sh`](./msprof/run.sh) \| 采集 5 秒系统级 CPU/内存性能数据，装完即跑 \|
		38	+\| [`deploy.sh`](./deploy.sh) \| 依次执行上述三个脚本，一键跑通全部样例 \|
		39	+
		40	+```bash
		41	+# 一键运行全部样例
		42	+bash deploy.sh
		43	+
		44	+# 或单独运行某个组件的样例
		45	+bash asys/run.sh
		46	+```
		47	+
		48	+以下章节按组件展开更多命令示例。
		49	+
		50	+## asys（故障信息收集与诊断）
		51	+
		52	+`src/asys/` 目录下同时存在 `asys.py` 和指向它的软链接 `asys`（`src/asys/asys -> ./asys.py`），CMake 通过 `install(DIRECTORY ${ASYS_DIR} ...)` 将整个目录原样拷贝，软链接也会保留。因此安装后两种调用都能直接用：
		53	+
		54	+```bash
		55	+# 形式一：显式 python3 调用 .py
		56	+python3 ${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys.py -h
		57	+
		58	+# 形式二：直接调用软链接 asys（asys.py 自带 #!/usr/bin/env python3 shebang）
		59	+${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys -h
		60	+```
		61	+
		62	+asys 的子命令在 `src/asys/cmdline/cmd_parser.py` 的 `Command` 枚举中定义，包含 `info / health / collect / launch / diagnose / analyze / config / profiling`。在环境变量加载生效后，可以直接以 asys 调用：
		J J jinyingqi25 天前问题：新增示例说明环境变量加载后可以直接执行 `asys info`、`asys health` 等命令，但本 PR 保留的前文只验证了安装目录下的 `${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys` 可执行；仓内安装清单仅将 asys 安装到 `tools/ascend_system_advisor/asys`，未看到将该目录加入 PATH 的配置，旧 README 也明确要求先将 `<asys_bin>` 加入 PATH 后才能直接执行 `asys`。严重程度：major 影响：用户按文档复制命令时可能直接报 `asys: command not found`，导致 asys 示例无法运行，英文版同步文档也会有同类可执行性问题。修改建议：将示例命令改为使用完整路径 `${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys ...`，或在示例前显式补充 `export PATH=${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys:$PATH`，并同步修正 `examples/README_en.md`。 sinat_31531339 9 天前评论： 9 天前评论：
		63	+
		64	+```bash
		65	+# 采集主机与 device 的软硬件信息（不依赖待诊断任务，通常作为环境自检）
		66	+asys info -r="status" -d=0
		67	+
		68	+# 体检 device 健康状态
		69	+asys health
		70	+
		71	+# 采集环境中已存在的运维信息并打包到指定输出目录
		72	+asys collect --output <output_dir>
		73	+```
		74	+
		75	+更多用法详见 [asys 工具用户指南](../docs/zh/asys/README.md)。
		76	+
		77	+## msaicerr（AI Core Error 分析）
		78	+
		79	+msaicerr 入口为 `src/msaicerr/msaicerr.py`，安装后位于 `${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py`。
		80	+
		81	+```bash
		82	+# 1) 解析一个已有的 AI Core Error 报告路径，结果输出到 <output_dir>
		83	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0
		84	+
		85	+# 2) 解析单个 dump 文件（dtype 取值参见 -h 输出）
		86	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16
		87	+
		88	+# 3) 检测当前环境是否具备运行 msaicerr 所需的条件（仅依赖 device 编号）
		89	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -e -dev 0
		90	+
		91	+# 完整参数说明
		92	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -h
		93	+```
		94	+
		95	+更多用法详见 [msaicerr 工具用户指南](../docs/zh/msaicerr/README.md)。
		96	+
		97	+## msprof（性能调优）
		98	+
		99	+msprof 由 C++ 侧 collector（`basic`、`dvvp`）和 `msprof` Python wheel（分析脚本）组成。`bash build.sh` 完成后，wheel（`msprof-0.0.1-py3-none-any.whl`）会被拷贝到 `src/msprof/collector/dvvp/msprofbin/` 并打包进 `.run` 安装包；安装时自动解包到 `${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/` 目录下，无需手动 `pip install`。
		100	+
		101	+分析脚本由 msprof collector 流水线内部调用（入口为 `profiler_tool/analysis/msprof/msprof.py`），不会在 `PATH` 中注册独立的命令行命令。如需手动运行分析脚本，可直接以 python3 调用安装目录下的入口：
		102	+
		103	+```bash
		104	+python3 ${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h
		105	+```
		106	+
		107	+C++ 侧 collector 一般作为 CANN profiler 流水线的内置组件被调用，开发者无需直接执行；回归通过 `bash build.sh -u --component msprof` 运行 gtest 用例（产物 `build/test/ut/msprof/msprofbin/msprof_bin_utest`）。
		108	+
		109	+更多用法详见[性能调优工具用户指南](../docs/zh/profiling/README.md)。

Aexamples/README_en.md+109-0

@@ -0,0 +1,109 @@
	1	+# Usage Examples
	2	+
	3	+This directory provides ready-to-run examples for each OAM-Tools component. After completing the [build](../README_en.md#running-the-build) and [installation](../README_en.md#installation), follow this document to run the examples in a real environment and quickly verify tool functionality.
	4	+
	5	+## Table of Contents
	6	+
	7	+- [Environment Preparation](#environment-preparation)
	8	+- [One-Click Scripts](#one-click-scripts)
	9	+- [asys (Fault Information Collection and Diagnosis)](#asys-fault-information-collection-and-diagnosis)
	10	+- [msaicerr (AI Core Error Analysis)](#msaicerr-ai-core-error-analysis)
	11	+- [msprof (Performance Tuning)](#msprof-performance-tuning)
	12	+
	13	+## Environment Preparation
	14	+
	15	+After installation, the tools are extracted to the `tools/` subdirectory under the CANN installation directory (root user default: `/usr/local/Ascend/cann/tools/`). Load the environment variables before running any example:
	16	+
	17	+```bash
	18	+# Root user default path; for non-root users, replace /usr/local with ${HOME}
	19	+source /usr/local/Ascend/cann/set_env.sh
	20	+# For a custom install path: source ${install_path}/cann/set_env.sh
	21	+```
	22	+
	23	+> After running the command above, `${ASCEND_HOME_PATH}` points to the CANN installation directory:
	24	+>
	25	+> - Root user default: `/usr/local/Ascend/cann`
	26	+> - Non-root user default: `${HOME}/Ascend/cann`
	27	+> - Custom install path: `${install_path}/cann`
	28	+
	29	+## One-Click Scripts
	30	+
	31	+This directory ships ready-to-execute scripts for each scenario. Run them once the environment variables are loaded:
	32	+
	33	+\| Script \| Description \|
	34	+\| --- \| --- \|
	35	+\| [`asys/run.sh`](./asys/run.sh) \| Check device health status with basic asys commands — the recommended starting point \|
	36	+\| [`msaicerr/run.sh`](./msaicerr/run.sh) \| Run the built-in sample operator to check whether the software/hardware environment meets msaicerr requirements; runs right after installation \|
	37	+\| [`msprof/run.sh`](./msprof/run.sh) \| Collect 5 seconds of system-level CPU/memory performance data; runs right after installation \|
	38	+\| [`deploy.sh`](./deploy.sh) \| Run the three scripts above in sequence to exercise all examples at once \|
	39	+
	40	+```bash
	41	+# Run all examples at once
	42	+bash deploy.sh
	43	+
	44	+# Or run the example for a single component
	45	+bash asys/run.sh
	46	+```
	47	+
	48	+The sections below expand on the command examples for each component.
	49	+
	50	+## asys (Fault Information Collection and Diagnosis)
	51	+
	52	+The `src/asys/` directory contains both `asys.py` and a symlink `asys` pointing to it (`src/asys/asys -> ./asys.py`). CMake copies the whole directory verbatim via `install(DIRECTORY ${ASYS_DIR} ...)`, preserving the symlink. Both invocation forms therefore work after installation:
	53	+
	54	+```bash
	55	+# Form 1: explicit python3 call
	56	+python3 ${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys.py -h
	57	+
	58	+# Form 2: call the symlink directly (asys.py has a #!/usr/bin/env python3 shebang)
	59	+${ASCEND_HOME_PATH}/tools/ascend_system_advisor/asys/asys -h
	60	+```
	61	+
	62	+The asys subcommands are defined in the `Command` enum in `src/asys/cmdline/cmd_parser.py`: `info / health / collect / launch / diagnose / analyze / config / profiling`. Once the environment variables take effect, you can invoke `asys` directly:
	63	+
	64	+```bash
	65	+# Collect host and device software/hardware info (independent of any task under diagnosis; typically an environment self-check)
	66	+asys info -r="status" -d=0
	67	+
	68	+# Check device health status
	69	+asys health
	70	+
	71	+# Collect existing O&M information and package it to the specified output directory
	72	+asys collect --output <output_dir>
	73	+```
	74	+
	75	+For more usage, see the [asys Tool User Guide](../docs/zh/asys/README.md).
	76	+
	77	+## msaicerr (AI Core Error Analysis)
	78	+
	79	+The msaicerr entry point is `src/msaicerr/msaicerr.py`, installed at `${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py`.
	80	+
	81	+```bash
	82	+# 1) Parse an existing AI Core Error report directory, output results to <output_dir>
	83	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -p <report_dir> -out <output_dir> -dev 0
	84	+
	85	+# 2) Parse a single dump file (for dtype values, see the -h output)
	86	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -d <dump_file> -out <output_dir> -dtype float16
	87	+
	88	+# 3) Check whether the current environment meets msaicerr requirements (only needs the device id)
	89	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -e -dev 0
	90	+
	91	+# Full parameter description
	92	+python3 ${ASCEND_HOME_PATH}/tools/msaicerr/msaicerr.py -h
	93	+```
	94	+
	95	+For more usage, see the [msaicerr Tool User Guide](../docs/zh/msaicerr/README.md).
	96	+
	97	+## msprof (Performance Tuning)
	98	+
	99	+msprof consists of the C++ collectors (`basic`, `dvvp`) and the `msprof` Python wheel (analysis scripts). After `bash build.sh` completes, the wheel (`msprof-0.0.1-py3-none-any.whl`) is copied to `src/msprof/collector/dvvp/msprofbin/` and packaged into the `.run` installer; it is unpacked to `${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/` at install time, so no manual `pip install` is needed.
	100	+
	101	+The analysis scripts are invoked internally by the msprof collector pipeline (entry point `profiler_tool/analysis/msprof/msprof.py`) and do not register a standalone command in `PATH`. To run an analysis script manually, call the installed entry point with python3:
	102	+
	103	+```bash
	104	+python3 ${ASCEND_HOME_PATH}/tools/profiler/profiler_tool/analysis/msprof/msprof.py -h
	105	+```
	106	+
	107	+The C++ collectors are normally invoked as built-in components of the CANN profiler pipeline and developers do not need to run them directly; regression is covered by `bash build.sh -u --component msprof`, which runs the gtest cases (artifact `build/test/ut/msprof/msprofbin/msprof_bin_utest`).
	108	+
	109	+For more usage, see the [Performance Tuning Tool User Guide](../docs/zh/profiling/README.md).