docs(readme): 重写首页 README，对齐 0.7.0 开源发布-cannbot-dsl-AtomGit

已合并

docs(readme): 重写首页 README，对齐 0.7.0 开源发布 #128

mayafei创建于 26 天前从mayafei/cannbot-dsl-md： readme/refresh 合入到 cann/cannbot-dsl： master

docs(readme): 重写首页 README，对齐 0.7.0 开源发布 #128

已合并

mayafei创建于 26 天前

从mayafei/cannbot-dsl-md readme/refresh合入到cann/cannbot-dsl master

共 3 个文件变更+276-73

MREADME.md+250-72

	@@ -1,12 +1,38 @@
1	# CANNBot-DSL	1	# CANNBot-DSL
2		2
3	-> 基于 CANNBot-DSL 的 Ascend NPU 复杂算子示例集合。	3	+> 基于 CANNBot-DSL 的 Ascend NPU 复杂算子样例集合，配套完整的文档站与精度测试。
4		4
5	-[📖 概述](#概述) · [📦 算子列表](#算子列表) · [📂 目录结构](#目录结构) · [🔥 更新日志](CHANGELOG.md) · [📜 许可证](#许可证)	5	+<sub><span style="color:#999999">当前为尝鲜版本，CANNBot-DSL 的 API 接口不保证兼容性，后续版本可能发生变更。</span></sub>
		6	+
		7	+[📖 概述](#概述) · [💻 软硬件配套](#软硬件配套说明) · [⚡️ 快速上手](#快速上手) · [📦 算子列表](#算子列表) · [📚 文档导航](#文档导航) · [📂 目录结构](#目录结构) · [🔥 更新日志](CHANGELOG.md) · [📜 许可证](LICENSE)
		8	+
		9	+<!-- TODO(发布后)：补顶部徽章行（许可证 / 文档站 / CANN 版本 / 所属 SIG）。 -->
		10	+<!-- TODO(发布后)：补语言切换入口（中文 \| English）。本次仅提供中文。 -->
6		11
7	---	12	---
8		13
9	-## 概述	14	+## 🔥 最新动态
		15	+
		16	+> 2026-09-30
		17	+>
		18	+> - ✅ 支持 DeepSeek V4.1：本仓算子集已覆盖相关算子，包括 [`indexer_prologue_qw`](samples/indexer_prologue_qw)、[`indexer_prologue_k`](samples/indexer_prologue_k)、[`attn_prologue`](samples/attn_prologue)、[`quant_lightning_indexer_dsl`](samples/quant_lightning_indexer_dsl)、[`quant_sparse_lightning_indexer_dsl`](samples/quant_sparse_lightning_indexer_dsl)、[`mixed_quant_sparse_flash_mla`](samples/mixed_quant_sparse_flash_mla)。
		19	+>
		20	+> - 🚀 新增 17 个算子样例，并更新既有算子适配最新 CANNBot-DSL。例如，[Sparse Flash Attention](samples/sparse_flash_attention) 相比 AscendC 版本，加速比最高达到 1.63 倍；[Qwen Sparse Attention](samples/qwen_sparse_attn) 相比 AscendC 版本，长 KV decode 场景平均加速比达到 1.23 倍。其余算子的详细信息见[算子列表](#算子列表)。
		21	+>
		22	+> - 🛠 支持样例运行与自定义算子的调试开发：CANNBot-DSL 0.7.0 版本发布，可直接通过 `python -m pip install cannbot-dsl` 安装；本仓样例可直接运行，自定义算子可通过 `net/native_package` 编译打包为 Native 算子包。使用说明见[快速上手](#快速上手)，打包方式见 [Native 打包说明](net/native_package/README.md)，接口与调试能力见 [API 文档](https://cannbot-dsl.gitcode.com/api/)。
		23	+
		24	+<!-- TODO(算子全量合入后)：本节只保留当前这批重大更新，跟随后续合入滚动替换，
		25	+ 顶部那行日期（现为 2026-09-30）需一并更新为最新一批的合入日期。
		26	+ 历史沿革由 CHANGELOG.md 承载，但其首节目前只记到 2026-09-29，且只收录了
		27	+ attn_prologue、batch_matmul、matmul_streamk、quant_batch_matmul_mxa8w4 四条；
		28	+ engram_gate、indexer_prologue_k、flash_mla_with_kvcache、quant_block_sparse_attn、
		29	+ flash_attn 的 metadata 变长序列支持、既有算子适配 0.7.0 的迁移，
		30	+ 以及 flash_kda_metadata / fused_recurrent_kda_snapshot 两个样例的撤并，均未收录，需补齐。 -->
		31	+
		32	+<!-- TODO(发布前)：第二条的「17 个」按 2026-09-29 与 2026-09-30 两批合入的新增算子计，
		33	+ metadata 算子计入其主算子（含 flash_attn_metadata）；「更新适配」的具体范围也需一并核实。 -->
		34	+
		35	+## 📌 概述
10		36
11	CANNBot 是 [CANN](https://hiascend.com/software/cann) 社区的 Infra 智能体层，用 Agent 完成 AscendC/PyPTO/TileLang/Triton 等各类语言的算子开发、模型迁移与推理优化，并延伸至图模式、Runtime 等更多 CANN 开发场景。	37	CANNBot 是 [CANN](https://hiascend.com/software/cann) 社区的 Infra 智能体层，用 Agent 完成 AscendC/PyPTO/TileLang/Triton 等各类语言的算子开发、模型迁移与推理优化，并延伸至图模式、Runtime 等更多 CANN 开发场景。
12		38
	@@ -14,82 +40,234 @@ CANNBot 是 [CANN](https://hiascend.com/software/cann) 社区的 Infra 智能体
14		40
15	![CANNBot 仓群结构](docs/figures/cannbot-repo-map.png)	41	![CANNBot 仓群结构](docs/figures/cannbot-repo-map.png)
16		42
17	-当前仓库中的 samples 使用 CANNBot 基于 CANNBot-DSL 生成，涵盖 VoxelConv、PointNet Set Abstraction、Flash Attention、Kimi Delta Attention 等复杂算子。本次开源样例代码，自定义开发、测试等功能将于近期发布，敬请期待。	43	+## 💻 软硬件配套说明
18		44
19	-项目面向 NPU ARCH 3510（Ascend 950PR / Ascend 950DT），详见 [算子列表](#算子列表)。	45	+\| 维度 \| 支持的版本 \|
		46	+\| :--- \| :--- \|
		47	+\| 昇腾产品 \| Ascend 950PR / Ascend 950DT（NPU ARCH 3510），见[硬件兼容性查询](https://www.hiascend.com/hardware/compatibility) \|
		48	+\| CPU 架构 \| x86_64 / aarch64 \|
		49	+\| 操作系统 \| CANN 支持的 Linux 发行版，见[硬件兼容性查询](https://www.hiascend.com/hardware/compatibility) \|
		50	+\| Python \| 3.10、3.11、3.12 \|
		51	+\| CANN \| 建议 9.2.0-beta.2，见 [CANN 安装部署](https://www.hiascend.com/cann/download) \|
		52	+\| CANNBot-DSL \| 0.7.0 \|
		53	+\| torch \| 2.7.1 / 2.9.0 / 2.10.0 / 2.11.0 / 2.12.0 \|
20		54
21	-## 算子列表	55	+> 上表口径截至 2026-09-30。CANN 版本以 [CANN 安装部署](https://www.hiascend.com/cann/download)为准。
22		56
23	-\| 算子 \| 公式 \| 文档 \|	57	+<!-- TODO(发布后)：`cannbot-dsl` 0.7.0 上架 pip 源后，复核本表版本号与「快速上手」中的安装命令。 -->
24	-\| :--- \| :--- \| :--- \|
25	-\| voxel_conv \| $C[N, Co, Ho, Wo] = \text{VoxelConv}(x, filter)$ \| [samples/voxel_conv](samples/voxel_conv) \|
26	-\| flash_attn \| $O = softmax(QK^T \cdot scale) V$ \| [samples/flash_attn](samples/flash_attn) \|
27	-\| qwen_sparse_attn \| `block_size=128` 的分块稀疏注意力 \| [samples/qwen_sparse_attn](samples/qwen_sparse_attn) \|
28	-\| flash_attn_fp8_fullquant \| FP8 全量化 Attention，支持 GQA 与分页 KV Cache \| [samples/flash_attn_fp8_fullquant](samples/flash_attn_fp8_fullquant) \|
29	-\| stem_indexer \| 稀疏 Attention 选块，包含 AICPU metadata \| [samples/stem_indexer](samples/stem_indexer) \|
30	-\| qsa_indexer \| 压缩 Key 稀疏索引，包含 AICPU metadata \| [samples/qsa_indexer](samples/qsa_indexer) \|
31	-\| indexer_prologue_qw \| MXFP8 Q GEMM、尾部 RoPE、MXFP4 量化，以及 BF16 W GEMM \| [samples/indexer_prologue_qw](samples/indexer_prologue_qw) \|
32	-\| attn_prologue \| MXFP8 QA/KV 投影、RMSNorm、QR 量化、QB 投影、RoPE 与 KV cache 更新 \| [samples/attn_prologue](samples/attn_prologue) \|
33	-\| flash_kda \| Kimi Delta Attention prefill 融合算子 \| [samples/flash_kda](samples/flash_kda) \|
34	-\| matmul \| $C[M,N] = A[M,K] @ B[N,K]^T$ \| [samples/matmul/matmul](samples/matmul/matmul) \|
35	-\| matmul_streamk \| $C[M,N] = A[M,K] @ B[K,N]$，DP + SK 混合调度 \| [samples/matmul/matmul](samples/matmul/matmul) \|
36	-\| batch_matmul \| $C[c\_batch, M, N] = A[a\_batch, M, K] @ B[b\_batch, N, K]^T$ \| [samples/matmul/batch_matmul](samples/matmul/batch_matmul) \|
37	-\| quant_matmul \| $C[M,N] = Dequant(A)[M,K] @ Dequant(B)[N,K]^T$ \| [samples/matmul/quant_matmul](samples/matmul/quant_matmul) \|
38	-\| quant_batch_matmul_mxa8w4 \| $C[M,N] = (A \cdot sa)[M,K] @ (B \cdot sb)[N,K]^T + bias$，MXFP8 激活 × MXFP4 权重 \| [samples/matmul/quant_matmul](samples/matmul/quant_matmul) \|
39	-\| grouped_matmul \| $y_i[m_i,n_i] = x_i[m_i,k_i] \times weight_i[k_i,n_i]$ \| [samples/grouped_matmul](samples/grouped_matmul) \|
40	-\| pointnet_sa \| $\text{feat}[K, D_{out}] = \max_{j} \text{MLP}(\text{points}[K, j, D_{in}])$ \| [samples/pointnet_sa](samples/pointnet_sa) \|
41	-\| rms_norm \| $y = x \cdot rstd \cdot \gamma$ \| [samples/rms_norm](samples/rms_norm) \|
42	-\| kv_compress_epilog \| KV Cache 压缩、量化与按槽位原地更新 \| [samples/kv_compress_epilog](samples/kv_compress_epilog) \|
43	-\| indexer_prologue_k \| Latent 投影、RMSNorm、RoPE 与 MXFP4 分页 cache 写入 \| [samples/indexer_prologue_k](samples/indexer_prologue_k) \|
44	-\| engram_gate \| Engram 残差门：双路 RMS、signed-sqrt sigmoid 门控与残差更新 \| [samples/engram_gate](samples/engram_gate) \|
45		58
46	-## 目录结构	59	+## ⚡️ 快速上手
47		60
48	-```text	61	+### 1. 安装 CANN
49	-├── samples/ # 算子实现与使用说明	62	+
50	-│ ├── voxel_conv/ # VoxelConv 卷积	63	+版本要求见[软硬件配套说明](#软硬件配套说明)。CANN 软件包为 Linux 版本，分 `x86_64` 与 `aarch64` 两种架构，下文以 `x86_64`、CANN 9.2.0-beta.2 为例。
51	-│ ├── flash_attn/ # Flash Attention	64	+
52	-│ ├── qwen_sparse_attn/ # Qwen 稀疏注意力（block_size=128）	65	+软件包可从 [CANN 安装部署](https://www.hiascend.com/cann/download)页面获取，也可直接从镜像 `wget` 下载（`aarch64` 机器把下面 URL 中的 `x86_64` 换成 `aarch64`）：
53	-│ ├── flash_attn_fp8_fullquant/ # FP8 全量化 Attention	66	+
54	-│ ├── stem_indexer/ # Stem Indexer 与 metadata	67	+```bash
55	-│ ├── qsa_indexer/ # QSA Indexer 与 metadata	68	+CANN_BASE=https://ascend.devcloud.huaweicloud.com/artifactory/cann-run/software/9.2.0-beta.2/x86_64
56	-│ ├── indexer_prologue_qw/ # Indexer prologue：Q 量化与 W GEMM	69	+
57	-│ ├── attn_prologue/ # MXFP8 attention prologue	70	+wget ${CANN_BASE}/Ascend-cann-toolkit_9.2.0-beta.2_linux-x86_64.run
58	-│ ├── flash_kda/ # Kimi Delta Attention，含 AICPU 调度 metadata	71	+wget ${CANN_BASE}/Ascend-cann-950-ops_9.2.0-beta.2_linux-x86_64.run
59	-│ ├── matmul/ # 矩阵乘
60	-│ │ ├── matmul/ # 非量化矩阵乘（基础调度 + Stream-K）
61	-│ │ ├── batch_matmul/ # 非量化批量矩阵乘（batch 维广播）
62	-│ │ └── quant_matmul/ # 量化矩阵乘（MXFP8/MXFP4、MXA8W4、HiFloat8 TT）
63	-│ ├── grouped_matmul/ # 非量化分组矩阵乘
64	-│ ├── pointnet_sa/ # PointNet Set Abstraction
65	-│ ├── rms_norm/ # RmsNorm 归一化
66	-│ └── kv_compress_epilog/ # KV Cache 压缩更新
67	-├── test/ # 测试
68	-│ ├── voxel_conv/
69	-│ ├── flash_attn/
70	-│ ├── flash_attn_fp8_fullquant/
71	-│ ├── stem_indexer/
72	-│ ├── qsa_indexer/
73	-│ ├── indexer_prologue_qw/
74	-│ ├── attn_prologue/
75	-│ ├── flash_kda/
76	-│ ├── matmul/
77	-│ │ ├── matmul/
78	-│ │ ├── batch_matmul/
79	-│ │ └── quant_matmul/
80	-│ ├── grouped_matmul/
81	-│ ├── pointnet_sa/
82	-│ ├── rms_norm/
83	-│ └── kv_compress_epilog/
84	-├── figures/
85	-└── README.md
86	```	72	```
87		73
88	-## 🔥 最新动态	74	+`${install_path}` 为安装路径，默认 `/usr/local/Ascend`：
89		75
90	-最新更新与历史记录详见 [CHANGELOG.md](CHANGELOG.md)。	76	+```bash
		77	+bash ./Ascend-cann-toolkit_9.2.0-beta.2_linux-x86_64.run --install --force --install-path=${install_path}
		78	+bash ./Ascend-cann-950-ops_9.2.0-beta.2_linux-x86_64.run --install --force --install-path=${install_path}
91		79
92	-## 相关信息	80	+source ${install_path}/ascend-toolkit/set_env.sh
		81	+```
93		82
94	-- [许可证](LICENSE)	83	+NPU 驱动与固件不在该镜像中，需从 [CANN 安装部署](https://www.hiascend.com/cann/download)页面获取并预先安装；机器上已有配套驱动与固件的可跳过此步。
95	-- 源文件头部包含完整的版权与许可声明，遵循 CANN Open Software License Agreement Version 2.0	84	+
		85	+### 2. 安装 CANNBot-DSL
		86	+
		87	+CANNBot-DSL 以 whl 包发布，编译器后端已包含在包内，安装后即可使用，无需再从源码构建。发行包名为 `cannbot-dsl`，导入名为 `cannbotdsl`：
		88	+
		89	+```bash
		90	+python -m pip install cannbot-dsl
		91	+```
		92	+
		93	+<!-- TODO(发布后)：`cannbot-dsl` 0.7.0 上架后复核本节命令与配套版本号（上架前公网仅 0.0.3 Alpha）。 -->
		94	+
		95	+安装完成后验证版本：
		96	+
		97	+```bash
		98	+python -c 'import cannbotdsl; print(cannbotdsl.__version__)'
		99	+```
		100	+
		101	+### 3. 运行一个算子
		102	+
		103	+以 `sparse_flash_attention` 为例，BSND、BF16，每个 Query token 选取 TOPK 个逻辑 KV token：
		104	+
		105	+```python
		106	+import math
		107	+import torch
		108	+import torch_npu
		109	+
		110	+from sparse_flash_attention import sparse_flash_attention
		111	+
		112	+B, S1, S2, N1, N2 = 1, 2, 16, 8, 1
		113	+D, DR, TOPK = 512, 64, 8
		114	+
		115	+query = torch.randn(B, S1, N1, D, dtype=torch.bfloat16).npu()
		116	+query_rope = torch.randn(B, S1, N1, DR, dtype=torch.bfloat16).npu()
		117	+key = torch.randn(B, S2, N2, D, dtype=torch.bfloat16).npu()
		118	+key_rope = torch.randn(B, S2, N2, DR, dtype=torch.bfloat16).npu()
		119	+
		120	+sparse_indices = torch.tensor(
		121	+ [[[[0, 2, 4, 6, 8, 10, 12, 14]],
		122	+ [[1, 3, 5, 7, 9, 11, 13, 15]]]],
		123	+ dtype=torch.int32,
		124	+).npu()
		125	+
		126	+output, softmax_max, softmax_sum = sparse_flash_attention(
		127	+ query=query,
		128	+ key=key,
		129	+ value=key, # MLA-absorb；当前 kernel 使用 key 参与 PV
		130	+ sparse_indices=sparse_indices,
		131	+ query_rope=query_rope,
		132	+ key_rope=key_rope,
		133	+ scale_value=1.0 / math.sqrt(D + DR),
		134	+ sparse_block_size=1,
		135	+ layout_query="BSND",
		136	+ layout_kv="BSND",
		137	+ sparse_mode=0,
		138	+ attention_mode=2,
		139	+ return_softmax_lse=True,
		140	+)
		141	+
		142	+print("output", tuple(output.shape))
		143	+print("softmax_max", tuple(softmax_max.shape))
		144	+print("softmax_sum", tuple(softmax_sum.shape))
		145	+```
		146	+
		147	+样例以目录为单位组织，运行前请切换到该样例所在目录，或把样例目录加入 `PYTHONPATH`：
		148	+
		149	+```bash
		150	+cd samples/sparse_flash_attention
		151	+python3 your_script.py
		152	+```
		153	+
		154	+运行成功时打印：
		155	+
		156	+```text
		157	+output (1, 2, 8, 512)
		158	+softmax_max (1, 1, 2, 8)
		159	+softmax_sum (1, 1, 2, 8)
		160	+```
		161	+
		162	+各算子的接口参数、数据类型约束与返回值说明，见[算子列表](#算子列表)中对应样例的 README。
		163	+
		164	+### 4. 运行精度测试
		165	+
		166	+```bash
		167	+python3 -m pytest test/sparse_flash_attention/test_sparse_flash_attention.py -v
		168	+```
		169	+
		170	+<!-- TODO(算子全量合入后)：补充「一次跑全部样例测试」的命令与耗时说明。 -->
		171	+
		172	+## 📦 算子列表
		173	+
		174	+本仓算子持续合入中，当前已开源算子如下：
		175	+
		176	+\| 样例 \| 接口 \| 说明 \|
		177	+\| :--- \| :--- \| :--- \|
		178	+\| [matmul/matmul](samples/matmul/matmul) \| `matmul()` \| A16W16 矩阵乘，`C[M,N] = A[M,K] × B[N,K]^T` \|
		179	+\| [matmul/matmul](samples/matmul/matmul) \| `matmul_streamk()` \| 同目录的 Stream-K（DPSK）实现，DP + SK 混合调度，适合小 M/N、大 K \|
		180	+\| [matmul/batch_matmul](samples/matmul/batch_matmul) \| `batch_matmul()` \| 批量矩阵乘，batch 维右对齐广播，支持 rank 2~6 \|
		181	+\| [matmul/quant_matmul](samples/matmul/quant_matmul) \| `npu_quant_matmul()` \| MXFP8 / MXFP4 全量化矩阵乘（`quant_batch_matmul_mx.py`） \|
		182	+\| [matmul/quant_matmul](samples/matmul/quant_matmul) \| `npu_quant_matmul()` \| per-tensor（TT）量化矩阵乘，支持 HiFloat8 / INT8 / FP8（`quant_batch_matmul_hif8_tt.py`） \|
		183	+\| [matmul/quant_matmul](samples/matmul/quant_matmul) \| `matmul_mix_quant()` \| MXA8W4：MXFP8 激活 × MXFP4 权重（`quant_batch_matmul_mxa8w4.py`） \|
		184	+\| [grouped_matmul](samples/grouped_matmul) \| `group_matmul()` \| 分组矩阵乘，支持 M 轴 / K 轴分组 \|
		185	+\| [flash_attn](samples/flash_attn) \| `flash_attn()`、`flash_attn_metadata()` \| Flash Attention，支持 GQA、变长序列与分页 KV Cache \|
		186	+\| [flash_attn_fp8_fullquant](samples/flash_attn_fp8_fullquant) \| `flash_attn_fp8_fullquant()` \| FP8 全量化 Attention，支持 GQA、分页 KV Cache 与 causal mask \|
		187	+\| [sparse_flash_attention](samples/sparse_flash_attention) \| `sparse_flash_attention()` \| Sparse Flash Attention（SFA），按 `sparse_indices` 选取参与计算的 KV token \|
		188	+\| [qwen_sparse_attn](samples/qwen_sparse_attn) \| `qwen_sparse_attn()` \| 固定 `block_size=128` 的分块稀疏注意力，含 AICPU metadata 规划 \|
		189	+\| [flash_mla_with_kvcache](samples/flash_mla_with_kvcache) \| `flash_mla_with_kvcache()`、`flash_mla_with_kvcache_metadata()` \| Flash MLA 推理，Q 为 TND、KV 走分页 cache \|
		190	+\| [quant_block_sparse_attn](samples/quant_block_sparse_attn) \| `quant_block_sparse_attn()`、`quant_block_sparse_attn_metadata()` \| FP8 量化块稀疏注意力，面向分页 prefill \|
		191	+\| [mixed_quant_sparse_flash_mla](samples/mixed_quant_sparse_flash_mla) \| `mixed_quant_sparse_flash_mla()` \| 混合量化稀疏 MLA：BF16 Q + FP8 原始 KV + 可选 FP4 压缩 KV \|
		192	+\| [mixed_quant_sparse_flash_mla_metadata](samples/mixed_quant_sparse_flash_mla_metadata) \| `mixed_quant_sparse_flash_mla_metadata()` \| MQSMLA 的 AICPU 分核调度，输出整行 / FlashDecode 分片计划 \|
		193	+\| [flash_kda](samples/flash_kda) \| `flash_kda()`、`flash_kda_metadata()` \| Kimi Delta Attention prefill 融合算子，含 AICPU 调度 metadata \|
		194	+\| [attn_prologue](samples/attn_prologue) \| `attn_prologue()` \| MXFP8 的 QA/KV 投影、RMSNorm、QR 量化、QB 投影、RoPE 与 KV cache 写回 \|
		195	+\| [indexer_prologue_qw](samples/indexer_prologue_qw) \| `indexer_prologue_qw()` \| MXFP8 Q GEMM、尾部 RoPE、MXFP4 量化，以及 BF16 W GEMM \|
		196	+\| [indexer_prologue_k](samples/indexer_prologue_k) \| `indexer_prologue_k()` \| Indexer K 路前处理：BF16 投影、RMSNorm、RoPE、MXFP4 量化与分页 cache 写入 \|
		197	+\| [qsa_indexer](samples/qsa_indexer) \| `qsa_indexer()`、`qsa_indexer_metadata()` \| 压缩 Key 稀疏索引，选高分压缩块并展开为 token 索引 \|
		198	+\| [stem_indexer](samples/stem_indexer) \| `stem_indexer()`、`stem_indexer_metadata()` \| 块级特征打分 + 动态 TopK 选择 Key Block \|
		199	+\| [quant_lightning_indexer_dsl](samples/quant_lightning_indexer_dsl) \| `quant_lightning_indexer()` \| MXFP4 Lightning Indexer（QLI），遍历上下文选 TopK token \|
		200	+\| [quant_lightning_indexer_metadata_dsl](samples/quant_lightning_indexer_metadata_dsl) \| `quant_lightning_indexer_metadata()` \| QLI 配套的 AICPU 调度算子 \|
		201	+\| [quant_sparse_lightning_indexer_dsl](samples/quant_sparse_lightning_indexer_dsl) \| `quant_sparse_lightning_indexer()` \| MXFP4 Sparse Lightning Indexer（QSLI），仅访问候选 Key 块 \|
		202	+\| [quant_sparse_lightning_indexer_metadata_dsl](samples/quant_sparse_lightning_indexer_metadata_dsl) \| `quant_sparse_lightning_indexer_metadata()` \| QSLI 配套的 AICPU 调度算子 \|
		203	+\| [kv_compress_epilog](samples/kv_compress_epilog) \| `kv_compress_epilog()` \| KV Cache 量化压缩与按槽位原地更新 \|
		204	+\| [rms_norm](samples/rms_norm) \| `rms_norm()` \| RMSNorm，`y = x · rstd · γ` \|
		205	+\| [engram_gate](samples/engram_gate) \| `engram_gate()` \| Engram 残差门：双路 RMS、加权点积与 signed-sqrt sigmoid 门控 \|
		206	+\| [pointnet_sa](samples/pointnet_sa) \| `pointnet_sa()` \| PointNet++ SA 层的 shared MLP + max-pool \|
		207	+\| [voxel_conv](samples/voxel_conv) \| `voxel_conv()` \| VoxelNet Convolutional Middle Layers \|
		208	+
		209	+<!-- TODO(算子全量合入后)：补全本表（不要漏掉后续合入的算子）。当前已知缺口：
		210	+ 1) scripts/ci/operator_list.yaml 与 test/test_config.yaml 登记的算子均已有对应样例目录，无缺口。
		211	+ 2) docs/examples/index.md 的样例索引仍滞后（仅 10 行），缺 batch_matmul、matmul_streamk、
		212	+ quant_matmul 的另两个实现、flash_attn_fp8_fullquant、sparse_flash_attention、qwen_sparse_attn、
		213	+ flash_mla_with_kvcache、quant_block_sparse_attn、mixed_quant_sparse_flash_mla 及其 metadata、
		214	+ indexer_prologue_qw、indexer_prologue_k、qsa_indexer、stem_indexer、QLI/QSLI 及其 metadata、
		215	+ engram_gate 等，需同步。
		216	+ 3) figures/ 下 17 张图均已被引用；但 attn_prologue、indexer_prologue_k、mixed_quant_sparse_flash_mla、
		217	+ qsa_indexer、quant_lightning_indexer_dsl、quant_sparse_lightning_indexer_dsl 等样例的 README
		218	+ 已给出性能数据，尚无对应性能对比图。
		219	+ 4) `flash_kda_metadata`、`fused_recurrent_kda_snapshot` 两个样例已在本轮撤并（前者的实现并入
		220	+ `samples/flash_kda/`，后者删除），CHANGELOG.md 中两者的历史条目保留未动，发布前需确认口径。 -->
		221	+
		222	+## 📚 文档导航
		223	+
		224	+接口文档发布在文档站 <https://cannbot-dsl.gitcode.com/api/>；算子样例、测试与仓库结构不另设站点页面，直接阅读仓内文件。
		225	+
		226	+\| 内容 \| 说明 \| 入口 \|
		227	+\| :--- \| :--- \| :--- \|
		228	+\| API 总览 \| Host / Kernel / AI CPU 三类公共接口，以及 AOT 编译与 Native 算子包发布 \| [/api/](https://cannbot-dsl.gitcode.com/api/) \|
		229	+\| Host API \| 数据描述（`TensorSpec` / `TensorListSpec` / `Dim`）与平台信息接口 \| [/api/host/](https://cannbot-dsl.gitcode.com/api/host/) \|
		230	+\| Kernel API \| 类型与视图、控制流、数据搬运、Cube 与寄存器计算、同步与缓存、系统变量 \| [/api/kernel/](https://cannbot-dsl.gitcode.com/api/kernel/) \|
		231	+\| AI CPU API \| AI CPU 侧调度接口 \| [/api/aicpu/](https://cannbot-dsl.gitcode.com/api/aicpu/) \|
		232	+\| 装饰器 \| `@host`、`@jit`、`@kernel` 等六个装饰器说明 \| [/api/decorators.html](https://cannbot-dsl.gitcode.com/api/decorators.html) \|
		233	+\| 接口清单 \| 全部接口的索引 \| [/api/api-list.html](https://cannbot-dsl.gitcode.com/api/api-list.html) \|
		234	+\| 算子样例 \| 各样例目录下的 README：接口签名、数据类型约束与运行方式 \| [samples/](samples/) \|
		235	+\| 精度测试 \| 与样例一一对应的 pytest 用例 \| [test/](test/) \|
		236	+\| Native 打包 \| 把 `samples/` 下的算子编译打包为 Native wheel \| [net/native_package/README.md](net/native_package/README.md) \|
		237	+\| 更新日志 \| 版本与算子变更记录 \| [CHANGELOG.md](CHANGELOG.md) \|
		238	+
		239	+<!-- TODO(文档站新增 API 分区后)：同步扩充本表。
		240	+ TODO：本仓暂不提供「复现与调试开发」的独立文档，`快速上手` 与各样例 README 覆盖复现步骤，
		241	+ 调试能力见 API 文档的 Kernel API 部分；待该指南成型后在本表补一行。 -->
		242	+<!-- TODO(托管支持 cleanUrls 后)：`/api/decorators.html`、`/api/api-list.html` 两个叶子页现带 `.html`。
		243	+ 站点 VitePress 配置为 `cleanUrls: true`，但托管层未做 rewrite，无后缀的叶子页冷启动会 404
		244	+ （目录页如 `/api/`、`/api/host/` 不受影响），故按可直接访问的形态书写；
		245	+ 托管侧补上 rewrite 后可去掉后缀。 -->
		246	+
		247	+## 📂 目录结构
		248	+
		249	+关键目录如下，详细目录参见[仓库结构](docs/guide/repository.md)。
		250	+
		251	+```bash
		252	+cannbot-dsl/
		253	+├── docs/ # 文档站源码（VitePress）
		254	+├── samples/ # 算子样例及各自的 README
		255	+├── test/ # 与样例对应的测试代码
		256	+├── figures/ # 样例 README 使用的性能对比图
		257	+├── net/ # Native 算子编译与 wheel 打包
		258	+└── scripts/ # CI 与合规检查脚本
		259	+```
		260	+
		261	+<!-- TODO：本节与 docs/guide/repository.md 的分工是「简版索引 / 详版说明」。
		262	+ 但两处集合目前不一致（repository.md 多列了 build.sh 与 requirements.txt、缺 net/ 与
		263	+ install_deps.sh），描述措辞也不同，需对齐。该文件不在本次改动范围内。 -->
		264	+
		265	+## 📝 相关信息
		266	+
		267	+- [更新日志](CHANGELOG.md)
		268	+- [参与贡献](docs/community/contributing.md)
		269	+- [许可证](LICENSE)：CANN Open Software License Agreement Version 2.0
		270	+
		271	+---
		272	+
		273	+欢迎通过 Issue 与合并请求参与项目建设。问题反馈与交流请使用 [GitCode 仓库](https://gitcode.com/cann/cannbot-dsl)的 Issues 与 Discussions。

Mdocs/.vitepress/theme/custom.css+8-0

	@@ -430,3 +430,11 @@
430	transform: none;	430	transform: none;
431	}	431	}
432	}	432	}
		433	+
		434	+/* 尝鲜版本提示：由 theme/index.ts 注入到 /api/** 各页正文之前 */
		435	+.preview-notice {
		436	+ margin: 0 0 20px;
		437	+ font-size: 13px;
		438	+ line-height: 1.7;
		439	+ color: var(--vp-c-text-3);
		440	+}

Mdocs/.vitepress/theme/index.ts+18-1

	@@ -1,4 +1,21 @@
1	import DefaultTheme from 'vitepress/theme'	1	import DefaultTheme from 'vitepress/theme'
		2	+import { h } from 'vue'
		3	+import { useData } from 'vitepress'
2	import './custom.css'	4	import './custom.css'
3		5
4	-export default DefaultTheme	6	+const PREVIEW_NOTICE =
		7	+ '当前为尝鲜版本，CANNBot-DSL 的 API 接口不保证兼容性，后续版本可能发生变更。'
		8	+
		9	+export default {
		10	+ extends: DefaultTheme,
		11	+ Layout() {
		12	+ const { page } = useData()
		13	+
		14	+ return h(DefaultTheme.Layout, null, {
		15	+ 'doc-before': () => {
		16	+ if (!page.value.relativePath.startsWith('api/')) return null
		17	+ return h('p', { class: 'preview-notice' }, PREVIEW_NOTICE)
		18	+ },
		19	+ })
		20	+ },
		21	+}