docs: 修复 QUICKSTART 易用性问题并补充构建 FAQ 与

MCONTRIBUTING.md+6-0

	@@ -38,6 +38,8 @@
38	│ ├── op_host # 算子信息库、Tiling、InferShape相关实现	38	│ ├── op_host # 算子信息库、Tiling、InferShape相关实现
39	│ │ ├── ${op_name}_def.cpp # 算子信息库定义文件	39	│ │ ├── ${op_name}_def.cpp # 算子信息库定义文件
40	│ │ ├── ${op_name}_tiling.cpp # 算子Tiling实现文件	40	│ │ ├── ${op_name}_tiling.cpp # 算子Tiling实现文件
		41	+ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # 可选，子场景 Tiling 实现，${sub_case} 表示子场景（如 arch35）
		42	+ │ │ ├── ${op_name}_tiling_${sub_case}.h # 可选，子场景 Tiling 实现头文件
41	│ │ └── CMakeLists.txt	43	│ │ └── CMakeLists.txt
42	│ ├── op_kernel # 算子Kernel目录	44	│ ├── op_kernel # 算子Kernel目录
43	│ │ ├── ${op_name}.cpp	45	│ │ ├── ${op_name}.cpp
	@@ -48,6 +50,10 @@
48	│ └── README.md # 算子说明文档	50	│ └── README.md # 算子说明文档
49	```	51	```
50		52
		53	+ 完整的算子目录结构（含各可选交付件）参见[项目目录结构](docs/zh/install/dir_structure.md#项目目录)。
		54	+
		55	+ > 说明：op_host 目录下参与编译的 Tiling 实现文件，文件名须包含 `_tiling` 标识（如 `${op_name}_tiling.cpp`、`${op_name}_tiling_${sub_case}.cpp`），否则不会被编译系统识别。针对子场景（如特定架构 arch35）拆分 Tiling 实现时，请遵循此命名规则。
		56	+
51	- 文档纠错	57	- 文档纠错
52		58
53	如果您在本项目中发现某些算子文档描述错误，欢迎您新建Issue进行反馈和修复。	59	如果您在本项目中发现某些算子文档描述错误，欢迎您新建Issue进行反馈和修复。

MCONTRIBUTING_en.md+6-0

	@@ -36,6 +36,8 @@ Developer contribution scenarios mainly include:
36	│ ├── op_host # operator definition, Tiling, InferShape related implementation	36	│ ├── op_host # operator definition, Tiling, InferShape related implementation
37	│ │ ├── ${op_name}_def.cpp # operator definition file	37	│ │ ├── ${op_name}_def.cpp # operator definition file
38	│ │ ├── ${op_name}_tiling.cpp # operator Tiling implementation file	38	│ │ ├── ${op_name}_tiling.cpp # operator Tiling implementation file
		39	+ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # Optional, sub-scenario Tiling implementation. ${sub_case} represents the sub-scenario (e.g., arch35)
		40	+ │ │ ├── ${op_name}_tiling_${sub_case}.h # Optional, sub-scenario Tiling implementation header file
39	│ │ └── CMakeLists.txt	41	│ │ └── CMakeLists.txt
40	│ ├── op_kernel # operator Kernel directory	42	│ ├── op_kernel # operator Kernel directory
41	│ │ ├── ${op_name}.cpp	43	│ │ ├── ${op_name}.cpp
	@@ -47,6 +49,10 @@ Developer contribution scenarios mainly include:
47	│ └── README.md # operator description document	49	│ └── README.md # operator description document
48	```	50	```
49		51
		52	+ For the complete operator directory structure (including optional deliverables), see [Project Directory](docs/en/install/dir_structure.md#project-directory).
		53	+
		54	+ > Note: Tiling implementation files under the op_host directory that participate in compilation must contain the `_tiling` identifier in the file name (e.g., `${op_name}_tiling.cpp`, `${op_name}_tiling_${sub_case}.cpp`); otherwise, they will not be recognized by the compilation system. When splitting Tiling implementations for sub-scenarios (e.g., a specific architecture such as arch35), follow this naming rule.
		55	+
50	- Document Correction	56	- Document Correction
51		57
52	If you discover certain operator document description errors in this project, we welcome you to create a new Issue for feedback and correction.	58	If you discover certain operator document description errors in this project, we welcome you to create a new Issue for feedback and correction.

Mdocs/QUICKSTART.md+9-7

	@@ -20,6 +20,8 @@
20		20
21	本阶段目的是快速体验项目标准流程，验证环境能否成功进行算子源码编译、打包、安装和运行。	21	本阶段目的是快速体验项目标准流程，验证环境能否成功进行算子源码编译、打包、安装和运行。
22		22
		23	+> 本指南以单算子编译过程为例，也支持编译整个算子库算子、离线编译等多种场景，更多编译参数说明参见[《build参数说明》](zh/install/build.md)，编译过程中的常见问题均可参考[《源码构建指南》](zh/install/compile.md)。
		24	+
23	### 1. 进入项目源码	25	### 1. 进入项目源码
24		26
25	- CANNLab云开发环境：	27	- CANNLab云开发环境：
	@@ -45,9 +47,7 @@
45		47
46	### 2. 编译AddExample算子	48	### 2. 编译AddExample算子
47		49
48	-本指南默认采用单算子编译：仅构建目标算子，编译时间短，适合快速入门与日常开发。通用命令格式：`bash build.sh --pkg --soc=<芯片版本> --ops=<算子名>`。	50	+通用命令格式：`bash build.sh --pkg --soc=<芯片版本> --ops=<算子名>`。
49	-
50	-> 若需编译整个算子库（省略`--ops`），请参阅 [build参数说明](zh/install/build.md)。
51		51
52	以AddExample算子为例，编译命令如下：	52	以AddExample算子为例，编译命令如下：
53		53
	@@ -92,9 +92,11 @@ export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_ras/op_api/lib:${L
92	以AddExample为例，其提供了简单算子样例`add_example/examples/test_aclnn_add_example.cpp`，运行该样例验证算子功能是否正常。	92	以AddExample为例，其提供了简单算子样例`add_example/examples/test_aclnn_add_example.cpp`，运行该样例验证算子功能是否正常。
93		93
94	```bash	94	```bash
95	-bash build.sh --run_example add_example eager cust --vendor_name=custom	95	+bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
96	```	96	```
97		97
		98	+> 注意：运行样例时需确保`--soc`参数与编译算子包时使用的`--soc`取值一致，否则可能报`error 161001`（如`aclnnXxxGetWorkspaceSize failed`）。如遇此错误，请回到[第2节](#2-编译addexample算子)核对`--soc`取值后重新编译安装。
		99	+
98	预期输出：打印算子`AddExample`的加法计算结果，表明算子已成功部署并正确执行。	100	预期输出：打印算子`AddExample`的加法计算结果，表明算子已成功部署并正确执行。
99		101
100	```bash	102	```bash
	@@ -155,7 +157,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
155	3. 重新验证：	157	3. 重新验证：
156		158
157	```bash	159	```bash
158	- bash build.sh --run_example add_example eager cust --vendor_name=custom	160	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
159	```	161	```
160		162
161	4. 成功标志：输出结果变成乘法结果。	163	4. 成功标志：输出结果变成乘法结果。
	@@ -214,7 +216,7 @@ __aicore__ inline void AddExample<T>::Compute(int32_t progress)
214	调用AddExample算子的example样例，生成可执行文件（test_aclnn_add_example），该文件位于项目`ops-ras/build`目录。	216	调用AddExample算子的example样例，生成可执行文件（test_aclnn_add_example），该文件位于项目`ops-ras/build`目录。
215		217
216	```bash	218	```bash
217	- bash build.sh --run_example add_example eager cust --vendor_name=custom	219	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
218	```	220	```
219		221
220	- 采集性能数据	222	- 采集性能数据
	@@ -263,7 +265,7 @@ int main() {
263	2. 重新执行验证命令：	265	2. 重新执行验证命令：
264		266
265	```bash	267	```bash
266	- bash build.sh --run_example add_example eager cust --vendor_name=custom	268	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
267	```	269	```
268		270
269	3. 观察算子输出结果是否符合预期。	271	3. 观察算子输出结果是否符合预期。

Mdocs/QUICKSTART_en.md+9-7

	@@ -20,6 +20,8 @@ This guide aims to help you quickly get started with CANN and the `ops-ras` oper
20		20
21	The purpose of this stage is to quickly experience the project standard process and verify whether the environment can successfully perform operator source code compilation, packaging, installation, and running.	21	The purpose of this stage is to quickly experience the project standard process and verify whether the environment can successfully perform operator source code compilation, packaging, installation, and running.
22		22
		23	+> This guide uses single operator compilation as an example. Compiling the entire operator library, offline compilation, and other scenarios are also supported. For more build parameter descriptions, see [build Parameter Description](en/install/build.md). For common issues during compilation, see [Source Code Build](en/install/compile.md).
		24	+
23	### 1. Enter the Project Source Code	25	### 1. Enter the Project Source Code
24		26
25	- CANNLab Cloud Development Environment:	27	- CANNLab Cloud Development Environment:
	@@ -45,9 +47,7 @@ The purpose of this stage is to **quickly experience the project standard proces
45		47
46	### 2. Compile the AddExample Operator	48	### 2. Compile the AddExample Operator
47		49
48	-This guide uses single operator compilation by default: only the target operator is built, the compilation time is short, and it is suitable for quick start and daily development. The general command format: `bash build.sh --pkg --soc=<chip version> --ops=<operator name>`.	50	+The general command format: `bash build.sh --pkg --soc=<chip version> --ops=<operator name>`.
49	-
50	-> If you need to compile the entire operator library (omit `--ops`), see [build Parameter Description](zh/install/build.md).
51		51
52	Taking the AddExample operator as an example, the compilation command is as follows:	52	Taking the AddExample operator as an example, the compilation command is as follows:
53		53
	@@ -92,9 +92,11 @@ The general running command format: `bash build.sh --run_example <operator name>
92	Taking AddExample as an example, it provides a simple operator sample `add_example/examples/test_aclnn_add_example.cpp`. Run this sample to verify whether the operator function is normal.	92	Taking AddExample as an example, it provides a simple operator sample `add_example/examples/test_aclnn_add_example.cpp`. Run this sample to verify whether the operator function is normal.
93		93
94	```bash	94	```bash
95	-bash build.sh --run_example add_example eager cust --vendor_name=custom	95	+bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
96	```	96	```
97		97
		98	+> Note: When running the sample, ensure that the `--soc` parameter is consistent with the `--soc` value used when compiling the operator package. Otherwise, `error 161001` may be reported (for example, `aclnnXxxGetWorkspaceSize failed`). If this error occurs, go back to [Section 2](#2-compile-the-addexample-operator) to check the `--soc` value, and then recompile and reinstall.
		99	+
98	Expected output: Print the addition calculation result of the operator `AddExample`, indicating that the operator has been successfully deployed and executed correctly.	100	Expected output: Print the addition calculation result of the operator `AddExample`, indicating that the operator has been successfully deployed and executed correctly.
99		101
100	```bash	102	```bash
	@@ -155,7 +157,7 @@ Repeat the steps in the [Compilation and Running](#i-compilation-and-running) se
155	3. Re-verify:	157	3. Re-verify:
156		158
157	```bash	159	```bash
158	- bash build.sh --run_example add_example eager cust --vendor_name=custom	160	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
159	```	161	```
160		162
161	4. Success Sign: The output result becomes the multiplication result.	163	4. Success Sign: The output result becomes the multiplication result.
	@@ -214,7 +216,7 @@ When the operator function verification is correct, you can collect operator per
214	Call the example sample of the AddExample operator to generate an executable file (test_aclnn_add_example), which is located in the project `ops-ras/build` directory.	216	Call the example sample of the AddExample operator to generate an executable file (test_aclnn_add_example), which is located in the project `ops-ras/build` directory.
215		217
216	```bash	218	```bash
217	- bash build.sh --run_example add_example eager cust --vendor_name=custom	219	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
218	```	220	```
219		221
220	- Collect Performance Data	222	- Collect Performance Data
	@@ -263,7 +265,7 @@ int main() {
263	2. Re-execute the verification command:	265	2. Re-execute the verification command:
264		266
265	```bash	267	```bash
266	- bash build.sh --run_example add_example eager cust --vendor_name=custom	268	+ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${soc_version}
267	```	269	```
268		270
269	3. Observe whether the operator output result meets expectations.	271	3. Observe whether the operator output result meets expectations.

Mdocs/en/install/compile.md+20-1

	@@ -263,4 +263,23 @@ Global Environment TearDown
263	[100%] Built target ras_op_host_ut	263	[100%] Built target ras_op_host_ut
264	```	264	```
265		265
266	-${n} indicates that n cases were executed, ${m} indicates m test suites, and ${x} indicates the time consumed to execute the cases, in milliseconds.	266	+${n} indicates that n cases were executed, ${m} indicates m test suites, and ${x} indicates the time consumed to execute the cases, in milliseconds.
		267	+
		268	+## FAQ
		269	+
		270	+### Insufficient permission error when installing the custom run package
		271	+
		272	+The default installation directory requires the current user to have read, write, and execute permissions. If a permission insufficient error is reported, choose one of the following methods:
		273	+
		274	+- It is recommended to install to an absolute path writable by the current user and load the environment variable script generated by the package:
		275	+
		276	+ ```bash
		277	+ ./build_out/cann-ops-ras-linux.run --install-path=/absolute/path/to/opp
		278	+ source /absolute/path/to/opp/vendors/custom_ras/bin/set_env.bash
		279	+ ```
		280	+
		281	+- If you must install to the system CANN directory, use `sudo -E` to retain the currently configured CANN environment variables:
		282	+
		283	+ ```bash
		284	+ sudo -E ./build_out/cann-ops-ras-linux.run
		285	+ ```

Mdocs/en/install/dir_structure.md+1-1

	@@ -40,7 +40,7 @@ The full directory hierarchy of the project is introduced as follows:
40	│ │ │ │ └── ...	40	│ │ │ │ └── ...
41	│ │ │ ├── ${op_name}_def.cpp # Operator information library, defines operator basic information such as name, input/output, data types, etc.	41	│ │ │ ├── ${op_name}_def.cpp # Operator information library, defines operator basic information such as name, input/output, data types, etc.
42	│ │ │ ├── ${op_name}_infershape.cpp # Optional, InferShape implementation, deduces output shape according to operator shape. If not configured, output shape is the same as input shape	42	│ │ │ ├── ${op_name}_infershape.cpp # Optional, InferShape implementation, deduces output shape according to operator shape. If not configured, output shape is the same as input shape
43	-│ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # Optional, Tiling optimization for certain sub-scenarios, ${sub_case} represents the sub-scenario. For example, ${op_name}_tiling_arch35 is optimization for arch35 architecture. If this file does not exist, it indicates that the operator has no specific Tiling strategy for the corresponding sub-scenario	43	+│ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # Optional, Tiling optimization for certain sub-scenarios, ${sub_case} represents the sub-scenario. For example, ${op_name}_tiling_arch35 is optimization for arch35 architecture. If this file does not exist, it indicates that the operator has no specific Tiling strategy for the corresponding sub-scenario. Note: The Tiling implementation file name must contain the `_tiling` identifier to be recognized by the compilation system and participate in compilation
44	│ │ │ ├── ${op_name}_tiling_${sub_case}.h # Optional, header file used for Tiling implementation in ${sub_case} sub-scenario	44	│ │ │ ├── ${op_name}_tiling_${sub_case}.h # Optional, header file used for Tiling implementation in ${sub_case} sub-scenario
45	│ │ │ ├── ${op_name}_tiling.cpp # Optional, if this file does not exist, it indicates that there is no Tiling implementation for the corresponding scenario (divides tensor into multiple small blocks, distinguishes data types for parallel computing)	45	│ │ │ ├── ${op_name}_tiling.cpp # Optional, if this file does not exist, it indicates that there is no Tiling implementation for the corresponding scenario (divides tensor into multiple small blocks, distinguishes data types for parallel computing)
46	│ │ │ ├── ${op_name}_tiling.h # Optional, header file used for Tiling implementation	46	│ │ │ ├── ${op_name}_tiling.h # Optional, header file used for Tiling implementation

Mdocs/zh/install/compile.md+20-1

	@@ -263,4 +263,23 @@ Global Environment TearDown
263	[100%] Built target ras_op_host_ut	263	[100%] Built target ras_op_host_ut
264	```	264	```
265		265
266	-\$\{n\}表示执行了n个用例，\$\{m\}表示m项测试，\$\{x\}表示执行用例消耗的时间，单位为毫秒。	266	+\$\{n\}表示执行了n个用例，\$\{m\}表示m项测试，\$\{x\}表示执行用例消耗的时间，单位为毫秒。
		267	+
		268	+## FAQ
		269	+
		270	+### 安装自定义run包报错权限不足
		271	+
		272	+默认安装目录需要当前用户具备读、写和执行权限。若提示权限不足，可选择以下一种方式：
		273	+
		274	+- 推荐安装到当前用户可写的绝对路径，并加载安装包生成的环境变量脚本：
		275	+
		276	+ ```bash
		277	+ ./build_out/cann-ops-ras-linux.run --install-path=/absolute/path/to/opp
		278	+ source /absolute/path/to/opp/vendors/custom_ras/bin/set_env.bash
		279	+ ```
		280	+
		281	+- 确需安装到系统CANN目录时，使用`sudo -E`保留当前已配置的CANN环境变量：
		282	+
		283	+ ```bash
		284	+ sudo -E ./build_out/cann-ops-ras-linux.run
		285	+ ```

Mdocs/zh/install/dir_structure.md+3-0

	@@ -76,6 +76,9 @@
76	│ │ │ └── aclnn${OpName}V2.md # 可选，V2版本接口文档	76	│ │ │ └── aclnn${OpName}V2.md # 可选，V2版本接口文档
77	│ │ ├── op_host # Host侧实现	77	│ │ ├── op_host # Host侧实现
78	│ │ │ ├── CMakeLists.txt # Host侧CMakeList文件	78	│ │ │ ├── CMakeLists.txt # Host侧CMakeList文件
		79	+│ │ │ ├── ${op_name}_tiling.cpp # 可选，Tiling实现(将张量划分为多个小块，区分数据类型进行并行计算)，若无该文件表明对应场景下无Tiling实现
		80	+│ │ │ ├── ${op_name}_tiling_${sub_case}.cpp # 可选，针对某些子场景下的Tiling优化，${sub_case}表示子场景，如${op_name}_tiling_arch35是针对arch35架构的优化，若无该文件表明该算子没有对应子场景的特定Tiling策略；注意：Tiling实现文件名须包含 `_tiling` 标识才会被编译系统识别并参与编译
		81	+│ │ │ ├── ${op_name}_tiling_${sub_case}.h # 可选，${sub_case}子场景下Tiling实现用的头文件
79	│ │ │ ├── ${op_name}_aicpu_infershape.cpp # 可选，AI CPU场景下的InferShape实现	82	│ │ │ ├── ${op_name}_aicpu_infershape.cpp # 可选，AI CPU场景下的InferShape实现
80	│ │ │ └── op_api # 算子aclnn实现文件目录	83	│ │ │ └── op_api # 算子aclnn实现文件目录
81	│ │ │ ├── aclnn_${op_name}.cpp # 算子aclnn接口实现文件	84	│ │ │ ├── aclnn_${op_name}.cpp # 算子aclnn接口实现文件