[Documentation|文档反馈]: 文档图片命名不符合规范——31 个图片使用中文名或大写字母（应为英文小写+下划线）-ops-ras-AtomGit

已开启

[Documentation|文档反馈]: 文档图片命名不符合规范——31 个图片使用中文名或大写字母（应为英文小写+下划线） #38

廖氏如神创建于 17 天前

廖氏如神

17 天前创建

问题描述

ops-ras 仓库文档中引用的图片，存在文件名不符合《文档写作规范》命名规则的情况，共 31 个图片文件（涉及 31 处引用）。问题类型分布：大写字母 7 个、中文 27 个。

规范依据

CANN 社区《文档写作规范》「图片」一节明确规定：

【规则】图片需要以英文小写命名，多个单词以**下划线（_）**连接，名称不宜过长，建议不超过50个字符。

具体清单（31 个）

#	文件名	问题类型	引用处数
1	`QK_transpose_diagram.png`	大写字母	1
2	`masked_QK_diagram.png`	大写字母	1
3	`Instruction_pipeline.png`	大写字母	1
4	`IR_call.png`	大写字母	1
5	`pertensor量化.png`	中文	1
6	`perchannel量化.png`	中文	1
7	`pertoken量化.png`	中文	1
8	`pergroup量化.png`	中文	1
9	`perblock量化.png`	中文	1
10	`QK转置图.png`	中文、大写字母	1
11	`遮挡QK图.png`	中文、大写字母	1
12	`sparsemode为0遮挡矩阵.png`	中文	1
13	`sparsemode为0遮挡矩阵1.png`	中文	1
14	`attenmask下三角.png`	中文	1
15	`sparsemode为0遮挡矩阵2.png`	中文	1
16	`attenmask_band形状矩阵.png`	中文	1
17	`sparsemode为0遮挡矩阵3.png`	中文	1
18	`sparsemode为0遮挡矩阵4.png`	中文	1
19	`sparsemode为1遮挡矩阵.png`	中文	1
20	`sparsemode为2遮挡矩阵.png`	中文	1
21	`attenmask压缩下三角.png`	中文	1
22	`sparsemode为3遮挡矩阵.png`	中文	1
23	`sparsemode为4遮挡矩阵.png`	中文	1
24	`sparsemode为5遮挡矩阵.png`	中文	1
25	`attenmask矩阵.png`	中文	1
26	`sparsemode为6遮挡矩阵.png`	中文	1
27	`sparsemode为7遮挡矩阵.png`	中文	1
28	`sparsemode为8遮挡矩阵.png`	中文	1
29	`指令流水图.png`	中文	1
30	`aclnn调用.png`	中文	1
31	`IR调用.png`	中文、大写字母	1

引用位置示例：

QK_transpose_diagram.png
- docs/en/context/sparse_mode_introduction.md:21
masked_QK_diagram.png
- docs/en/context/sparse_mode_introduction.md:25
Instruction_pipeline.png
- docs/en/debug/cann_sim.md:196

（完整引用位置可通过下方复现命令生成。）

影响分析

命名规则为规范中的明确条款，当前命名方式不符合；
中文文件名在跨平台、跨工具链场景下容易出现乱码或路径解析异常（URL 编码后变成一长串 %XX，可读性差）；
大写字母在大小写敏感的路径处理逻辑中可能不被正确识别，例如按扩展名或命名规律过滤资源的脚本；
同一仓库内命名风格不统一，加大批量检索与维护成本。

修复建议

按规范将文件名改为「全小写 + 下划线」，并同步更新所有引用：

中文文件名 → 改为对应的英文小写（如 IR调用.png → ir_invocation.png）
大写字母 → 全部小写（如 PTQ_interface.png → ptq_interface.png）
连字符 → 改为下划线（如 gitcode-fork.png → gitcode_fork.png）

注意：图片文件本身需要重命名（git mv），不能只改引用，否则会造成图片 404；重命名后需全仓检索确认无遗漏引用（含非 Markdown 文件中可能存在的路径字符串）。

问题复现方式

git clone --depth 1 https://gitcode.com/cann/ops-ras.git
cd ops-ras

# 列出所有图片引用中的非规范命名（含中文或大写字母）
grep -rnoE '!\[[^]]*\]\([^)]+\)' --include="*.md" . \
  | grep -oE '[^/()]+\.(png|jpg|jpeg|gif|svg)' \
  | sort -u | grep -E '[A-Z]|[\x{4e00}-\x{9fff}]'

# 确认引用总数
grep -rn '图片文件名' --include="*.md" . | wc -l

影响级别

L1：文档格式类问题——图片命名不符合规范，可能在大写敏感环境中造成资源加载异常，不影响功能正确性。

LiuZonggu成员

17 天前评论：

您好，我们已收到反馈，待分析确认后处理修复

L LiuZonggu成员

17 天前将 LiuZonggu 设为负责人

NUAA_wqy

6 小时前关联了pull request：[docs] 按规范重命名 31 个非规范图片文件并同步更新引用