@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/languages/triton-ascend/triton-ascend-interpolate.md

@@ -1,234 +0,0 @@
----
-id: skill-triton-ascend-interpolate
-title: "Triton Ascend Interpolation Patterns"
-type: skill
-vendor: ascend
-tags:
-- triton-ascend
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- triton-ascend
----
-# Triton-Ascend Interpolate 算子开发参考文档
-
-> 适用于 `interpolate` 算子及相关运算。
-
----
-
-## 一、算子特性与难点
-
-| 特性 | 说明 |
-|---|---|
-| **多模式支持** | nearest / bilinear / bicubic / area 四种插值模式 |
-| **坐标映射复杂** | `align_corners=True/False` 两套坐标公式 |
-| **边界处理敏感** | 边缘像素 clamp 逻辑直接影响精度 |
-| **模式间差异大** | nearest 简单，但 bicubic 涉及 4×4 邻域和权重函数 |
-
----
-
-## 二、核心问题与解决方案
-
-### 问题 1：坐标映射公式精度
-
-- **现象**：bilinear / bicubic 模式大面积数值不匹配，相对误差达 10%~200%。
-- **根因**：浮点除法顺序和整数除法截断导致坐标计算偏差。
-
-**PyTorch 正确公式：**
-
-- `align_corners=False`：`src = scale * (dst + 0.5) - 0.5`，其中 `scale = src_size / dst_size`（浮点除法）
-- `align_corners=True`：`src = dst * (src_size - 1) / (dst_size - 1)`
-
-**✅ 解决方案：在 host 端预计算 scale，避免 kernel 内重复除法。**
-
-```python
-# Host 端预计算
-inv_scale_h = float(torch.tensor(H_in / H_out, dtype=torch.float32))
-inv_scale_w = float(torch.tensor(W_in / W_out, dtype=torch.float32))
-
-# Kernel 内只做乘法和加减
-src_y = (h_out.to(tl.float32) + 0.5) * inv_scale_h - 0.5
-```
-
----
-
-### 问题 2：边界 Clamp 逻辑
-
-- **现象**：边缘像素值与 PyTorch 不一致。
-- **根因**：PyTorch 的 bilinear 插值对越界坐标有特殊处理——当 `y0 < 0` 时，`y0` 和 `y1` 都可能被调整为 0，且对应权重需重新计算。
-
-**✅ 解决方案：严格参考 PyTorch `upsample_bilinear2d` 的边界处理。**
-
-```python
-y0 = tl.cast(src_y, tl.int32)
-if src_y < 0.0:
-    y0 = y0 - 1  # floor 对负数需要调整
-y1 = y0 + 1
-
-# clamp 到有效范围
-if y0 < 0:
-    y0 = 0
-if y1 >= H_in:
-    y1 = H_in - 1
-if x0 < 0:
-    x0 = 0
-if x1 >= W_in:
-    x1 = W_in - 1
-```
-
----
-
-### 问题 3：Bicubic 权重函数系数
-
-- **现象**：bicubic 模式全部失败，误差极大。
-- **根因**：使用了错误的插值核函数。PyTorch 使用 **Keys' bi-cubic（A=-0.75）**，而非 Catmull-Rom。
-
-**✅ 解决方案：使用正确的 Keys' 权重公式。**
-
-```python
-A = -0.75
-
-# |t| <= 1
-wy = ((A + 2.0) * t_y - (A + 3.0)) * t_y * t_y + 1.0
-
-# 1 < |t| < 2
-wy = ((A * t_y - 5.0 * A) * t_y + 8.0 * A) * t_y - 4.0 * A
-```
-
----
-
-### 问题 4：Bicubic 权重归一化
-
-- **现象**：边界处像素值系统性偏差。
-- **根因**：边界 clamp 后，4×4 邻域中部分像素被重复计算，权重和不再为 1。
-
-**✅ 解决方案：累加实际使用的权重和，最后做归一化。**
-
-```python
-val = 0.0
-w_sum = 0.0
-for jj in range(4):
-    for ii in range(4):
-        pixel = tl.load(...)
-        weight = wy * wx
-        val += weight * pixel
-        w_sum += weight
-
-if w_sum != 0.0:
-    val = val / w_sum
-```
-
----
-
-### 问题 5：最近邻取整方式
-
-- **现象**：nearest 模式部分失败。
-- **根因**：PyTorch 的 nearest 使用 `floor(src + 0.5)` 等价于 round-to-nearest，但需确认 `align_corners` 的坐标映射。
-
-**✅ 解决方案：根据是否使用 size 参数选择不同的计算路径。**
-
-```python
-if use_size == 1:
-    src_yi = h_out * H_in // H_out  # 整数向下取整
-else:
-    src_yi = tl.cast(h_out.to(tl.float32) / scale_h, tl.int32)
-```
-
----
-
-### 问题 6：Triton JIT 语法限制
-
-| 限制 | 错误信息 | 解决方案 |
-|---|---|---|
-| **不支持 `break`** | `unsupported AST node type: Break` | 用 `range(block_start, block_end)` 替代 |
-| **不支持 `float(jj)`** | `float() argument must be a string or a real number` | 直接用 `jj`（循环变量在 Triton 中已是标量） |
-| **`tl.where` 对 int 类型问题** | 比较结果不正确 | 用 `if-else` 标量控制流替代 |
-
----
-
-### 问题 7：Ascend NPU 向量加载精度
-
-- **现象**：向量化后精度大面积失败。
-- **根因**：Ascend NPU 对分散向量加载（scattered vector load，即索引跨越不同行/通道）支持不佳，导致数据读取错误。
-
-**✅ 解决方案：采用标量循环 + 内部 tiling 策略。**
-
-```python
-# 每个 program 处理 BLOCK_SIZE 个像素，但每个像素用标量计算
-for block_start in range(pid * BLOCK_SIZE, num_outputs, tl.num_programs(0) * BLOCK_SIZE):
-    block_end = min(block_start + BLOCK_SIZE, num_outputs)
-    for idx in range(block_start, block_end):
-        # 标量处理每个像素
-        ...
-```
-
----
-
-## 三、验证策略
-
-| 阶段 | 方法 | 目的 |
-|---|---|---|
-| **单像素对比** | 手写 Python 逐像素计算 | 快速定位坐标 / 公式问题 |
-| **单 shape 验证** | 小 tensor（4×4 → 8×8） | 确认边界处理正确 |
-| **全量验证** | 73 个 shape 组合 | 覆盖所有模式和参数组合 |
-
----
-
-## 四、性能优化经验
-
-| 优化点 | 效果 | 注意事项 |
-|---|---|---|
-| **入参静态化（`tl.constexpr`）** | 编译期优化 | `mode`、`align_corners`、`scale` 等 |
-| **BLOCK_SIZE tiling** | 减少 kernel 启动开销 | 标量循环内每个 program 处理多个像素 |
-| **Host 端预计算** | 减少 kernel 内计算 | `scale`、`inv_scale` 在 host 计算后传入 |
-
----
-
-## 五、关键代码结构
-
-```python
-@triton.jit
-def interpolate_kernel(
-    x_ptr, y_ptr,
-    N, C, H_in, W_in, H_out, W_out,
-    mode: tl.constexpr,          # 静态化
-    align_corners: tl.constexpr,
-    use_size: tl.constexpr,
-    scale_h: tl.constexpr,
-    scale_w: tl.constexpr,
-    inv_scale_h: tl.constexpr,   # host 预计算
-    inv_scale_w: tl.constexpr,
-    BLOCK_SIZE: tl.constexpr,
-):
-    pid = tl.program_id(0)
-    num_outputs = N * C * H_out * W_out
-    # 标量循环处理 BLOCK_SIZE 像素
-    for block_start in range(pid * BLOCK_SIZE, num_outputs, tl.num_programs(0) * BLOCK_SIZE):
-        block_end = block_start + BLOCK_SIZE
-        if block_end > num_outputs:
-            block_end = num_outputs
-        for idx in range(block_start, block_end):
-            # 解码 (n, c, h, w)
-            # 根据 mode 分支处理
-            # 严格遵循 PyTorch 坐标映射和边界处理
-            ...
-```
-
----
-
-## 六、调试 Checklist
-
-- [ ] 坐标映射公式与 PyTorch 源码一致
-- [ ] 边界 clamp 逻辑处理负坐标（floor 对负数需调整）
-- [ ] bicubic 权重使用 Keys' bi-cubic（`A = -0.75`）
-- [ ] bicubic 边界处做权重归一化
-- [ ] 浮点除法在 host 端预计算
-- [ ] 避免 Triton JIT 不支持的语法（`break`、`continue`、`float()` 等）
-- [ ] Ascend NPU 避免分散向量加载，使用标量循环
-- [ ] 多 shape 全量验证通过后再做性能优化

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/languages/triton-ascend/triton-ascend-matmul.md

@@ -1,132 +0,0 @@
----
-id: skill-triton-ascend-matmul
-title: "Triton Ascend MatMul Optimization Patterns"
-type: skill
-vendor: ascend
-tags:
-- triton-ascend
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- triton-ascend
----
-# MatMul 算子优化
-
-> 适用于矩阵乘法及相关运算
-
-## Ascend 后端切分优化
-
-**关键原则**: 充分发挥带宽，算子行宽为 512B 的整数倍。
-
-以 fp16/bf16 为例（每个元素 2 字节）：
-
-### 切分配置（根据转置情况）
-
-1. **A、B 都不转置**
-   - 分块行宽分别为 K0 和 N0
-   - **推荐**: M0=128, K0=256, N0=256
-
-2. **A 不转置，B 转置**
-   - 分块行宽都是 K0
-   - **推荐**: K0=256, M0 和 N0 影响较小
-
-3. **A、B 都转置**
-   - 分块行宽分别为 M0 和 K0
-   - **推荐**: M0=256, K0=256, N0=128
-
-4. **A 转置，B 不转置**
-   - 分块行宽分别为 M0 和 N0
-   - **注意**: 左右矩阵均无法同时满足 512B 的整数倍，需根据实际情况调整
-
-### 为什么是 512B？
-
-- 512B = 256 个 fp16/bf16 元素（256 × 2 字节）
-- NPU 的最佳带宽对齐
-- 确保每次内存访问充分利用带宽
-
-## 固定核心数启动
-
-MatMul 算子使用 **CUBE核心数**（矩阵计算核心）。
-
-**关键**: 使用 `grid=(num_cores,)` 而非 `(NUM_BLOCKS,)`
-
-```python
-@triton.jit
-def matmul_kernel(
-    a_ptr, b_ptr, c_ptr,
-    M, N, K,
-    num_cores: tl.constexpr,
-    BLOCK_M: tl.constexpr,
-    BLOCK_N: tl.constexpr,
-    BLOCK_K: tl.constexpr,
-):
-    # 关键:使用固定核心数启动,每个核心处理多个块
-    pid = tl.program_id(0)  # 核心ID: 0~num_cores-1
-    NUM_BLOCKS_M = triton.cdiv(M, BLOCK_M)
-    NUM_BLOCKS_N = triton.cdiv(N, BLOCK_N)
-    NUM_BLOCKS = NUM_BLOCKS_M * NUM_BLOCKS_N
-
-    # 每个核心循环处理多个块
-    for block_idx in range(pid, NUM_BLOCKS, num_cores):
-        # 计算当前块的2D索引
-        block_m = block_idx // NUM_BLOCKS_N
-        block_n = block_idx % NUM_BLOCKS_N
-
-        # 初始化累加器
-        accumulator = tl.zeros((BLOCK_M, BLOCK_N), dtype=tl.float32)
-
-        # K维度循环
-        for k in range(0, K, BLOCK_K):
-            # 加载A块
-            a_offset = (block_m * BLOCK_M + tl.arange(0, BLOCK_M))[:, None] * K + \
-                       (k + tl.arange(0, BLOCK_K))[None, :]
-            a_mask = (block_m * BLOCK_M + tl.arange(0, BLOCK_M))[:, None] < M
-            a = tl.load(a_ptr + a_offset, mask=a_mask, other=0.0)
-
-            # 加载B块
-            b_offset = (k + tl.arange(0, BLOCK_K))[:, None] * N + \
-                       (block_n * BLOCK_N + tl.arange(0, BLOCK_N))[None, :]
-            b_mask = (block_n * BLOCK_N + tl.arange(0, BLOCK_N))[None, :] < N
-            b = tl.load(b_ptr + b_offset, mask=b_mask, other=0.0)
-
-            # 矩阵乘累加
-            accumulator += tl.dot(a, b)
-
-        # 存储结果
-        c_offset = (block_m * BLOCK_M + tl.arange(0, BLOCK_M))[:, None] * N + \
-                   (block_n * BLOCK_N + tl.arange(0, BLOCK_N))[None, :]
-        c_mask = ((block_m * BLOCK_M + tl.arange(0, BLOCK_M))[:, None] < M) & \
-                 ((block_n * BLOCK_N + tl.arange(0, BLOCK_N))[None, :] < N)
-        tl.store(c_ptr + c_offset, accumulator, mask=c_mask)
-
-class ModelNew(torch.nn.Module):
-    def __init__(self):
-        super().__init__()
-
-    def forward(self, a, b):
-    M, K = a.shape
-    K2, N = b.shape
-    assert K == K2
-    c = torch.empty((M, N), device=a.device, dtype=a.dtype)
-
-    num_cores = 20  # Ascend 910B4有20个AI Core
-    BLOCK_M, BLOCK_N, BLOCK_K = 128, 256, 256
-
-    # 关键:固定核心数启动,grid=(num_cores,)不是(NUM_BLOCKS,)
-    matmul_kernel[(num_cores,)](
-        a, b, c, M, N, K, num_cores,
-        BLOCK_M, BLOCK_N, BLOCK_K
-    )
-    return c
-```
-
-**关键点**:
-- 使用 `grid=(num_cores,)` 固定启动核心数(如20个)
-- 每个核心通过 `for block_idx in range(pid, NUM_BLOCKS, num_cores)` 循环处理多个块
-- 不要使用 `grid=(NUM_BLOCKS_M * NUM_BLOCKS_N,)` 为每个块启动一个程序

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/languages/triton-ascend/triton-ascend-reduce.md

@@ -1,87 +0,0 @@
----
-id: skill-triton-ascend-reduce
-title: "Triton Ascend Reduce Operator Patterns"
-type: skill
-vendor: ascend
-tags:
-- triton-ascend
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- triton-ascend
----
-# Reduce 算子优化
-
-> 适用于需要聚合多个值的归约操作
-
-## 适用算子
-
-**基础归约**: sum, mean, max, min, prod
-**归一化**: softmax, logsoftmax, layernorm, batchnorm
-**统计**: variance, std
-
-## 通用归约策略
-
-### 1. 块内归约 + 原子操作
-
-```python
-@triton.jit
-def reduction_kernel(input_ptr, output_ptr, n_elements, BLOCK_SIZE: tl.constexpr):
-    pid = tl.program_id(0)
-    offsets = pid * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
-    mask = offsets < n_elements
-    
-    # 加载数据
-    data = tl.load(input_ptr + offsets, mask=mask, other=0.0)
-    
-    # 块内归约
-    block_sum = tl.sum(data, axis=0)
-    
-    # 原子操作写回全局内存
-    tl.atomic_add(output_ptr, block_sum)
-```
-
-### 2. 减少规约精度损失
-
-**关键**: 如果需要在 FP16 或 BF16 的数据上执行计算性规约（除了max, min的规约计算），应在规约计算前将其强制转换为 FP32，以避免低精度累加带来的数值误差。
-
-```python
-# 错误：直接用 fp16/bf16 累加，精度损失大
-data = tl.load(input_ptr + offsets, mask=mask, other=0.0)  # data 为 fp16/bf16
-block_sum = tl.sum(data, axis=0)  # 低精度累加
-carry = carry + block_sum  # 低精度累加
-
-# 正确：在执行累加计算前转为 fp32，在 fp32 上完成规约
-data = tl.load(input_ptr + offsets, mask=mask, other=0.0)
-data = data.to(tl.float32)        # 强制提升为 fp32
-block_sum = tl.sum(data, axis=0)  # 高精度累加
-carry = carry + block_sum  # 高精度累加
-
-# 如果输出要求 fp16/bf16，在最终 store 前转回
-tl.store(output_ptr, block_sum.to(input_ptr.dtype.element_ty))
-```
-
-**原则**：
-- 在执行规约操作前 `.to(tl.float32)`
-- 如果涉及多次规约，累积多次规约结果的累加器对象精度应为`tl.float32`
-- 涉及计算的规约操作（除了max, min的规约操作）均在 FP32 上执行
-- 在最后 `tl.store` 前按需转回原始数据类型
-
-### 3. 数值稳定性处理
-
-**关键**: 对于涉及 exp 的操作（softmax、logsoftmax），必须减去最大值防止溢出。
-
-```python
-# 错误：错误：直接 exp 可能溢出
-scores = tl.math.exp2(x)
-
-# 正确：正确：减去最大值
-max_val = tl.max(x, axis=0)
-scores = tl.math.exp2(x - max_val)
-```

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/languages/triton-ascend/triton-ascend-sort-select.md

@@ -1,179 +0,0 @@
----
-id: skill-triton-ascend-sort-select
-title: "Triton Ascend Sort and Select Patterns"
-type: skill
-vendor: ascend
-tags:
-- triton-ascend
-evidence_level: spec
-applies_to:
-- ascend910b
-source:
-- path: local
-  anchor: AscendOpGenAgent/skills
-architectures:
-- ascend910b
-languages:
-- triton-ascend
----
-# Sort/Select 算子优化
-
-> 适用于需要迭代选择元素的算子：NMS、TopK、ArgSort 等
-
-## 核心约束
-
-Triton Ascend 不支持 `break`/`continue`/`return` 和 Python `if` 分支，必须用 `tl.where` + mask 实现条件逻辑。
-
-| 禁止语法 | 替代方案 | 说明 |
-|---------|---------|------|
-| `if cond:` | `tl.where(cond, a, b)` | 所有条件必须用 SIMD 友好的方式表达 |
-| `break`/`continue` | 用循环变量 + mask 控制 | 循环次数固定，用 mask 跳过无效迭代 |
-| `return` | 无法提前返回 | 所有路径必须执行到函数末尾 |
-| 标量条件赋值 `x = y if cond` | `x = tl.where(cond, y, x)` | 标量变量更新必须用 `tl.where` |
-
-### 1.2 迭代选择的标准模式
-
-对于需要"每次从剩余元素中选一个最优"的算法（如NMS），标准模式是：
-
-```python
-# 模式：selection-sort 风格的迭代选择
-for step in range(max_select):
-    # 1. 线性扫描找最优候选
-    best_idx = -1
-    best_score = threshold
-    for i in range(n_elements):
-        score = tl.load(scores_ptr + i)
-        higher = (score > best_score) & active
-        best_idx = tl.where(higher, i, best_idx)
-        best_score = tl.where(higher, score, best_score)
-
-    # 2. 检查是否找到有效候选
-    found = (best_idx != -1) & active
-
-    # 3. 记录结果（仅当 found 时）
-    tl.store(output_ptr + count, best_idx.to(tl.int32), mask=found)
-    count = tl.where(found, count + 1, count)
-
-    # 4. 标记已选（通过修改内存状态）
-    tl.store(scores_ptr + best_idx, sentinel_value, mask=found)
-
-    # 5. 根据选中元素更新其他元素状态（算子特定逻辑）
-    # ... 例如 NMS 中计算 IoU 并抑制重叠 box
-```
-
-**关键原则**：
-- 用**内存值**（如将 score 设为哨兵值）表示"已选/已抑制"状态，而非标量 flag
-- 用 `tl.where` 做所有条件选择，不用 Python `if`
-- 用 `mask=` 参数控制 `tl.load`/`tl.store` 的执行
-
----
-
-## 2. 算子特定实现
-
-### 2.1 NMS (Non-Maximum Suppression)
-
-#### 算法语义
-
-验证框架对比的是 PyTorch 参考实现（如 `30_NMS.py`），其语义通常包含：
-
-1. **先过滤**：只保留满足门槛条件的元素（如 `score > scores_threshold`）
-2. **再降序排序**：参考实现通常用 `torch.argsort(..., descending=True, stable=True)` 确定顺序
-3. **迭代选择**：按排序后的顺序遍历，若当前元素未被抑制则选中
-4. **依赖抑制**：选中后，根据算子特定规则抑制其他元素（如 NMS 的 IoU 阈值）
-5. **数量限制**：最多输出 `max_output_size` 个，达到即停止
-6. **输出格式**：输出张量前 `num_selected` 个有效，其余为 0 或哨兵值
-
-**关键：降序关系来自参考实现的排序步骤**。Triton kernel 中没有显式排序，而是通过迭代选择最高分来隐式复现降序语义。
-
-#### 参考实现
-
-```python
-@triton.jit
-def select_kernel(
-    values_ptr,           # 用于比较的值
-    selected_indices_ptr, # 输出：选中的原始索引
-    num_selected_ptr,     # 输出：实际选中数量
-    n_elements,
-    max_output_size: tl.constexpr,
-    threshold: tl.constexpr,
-):
-    pid = tl.program_id(0)
-    active = (pid == 0)
-    selected_count = 0
-
-    for step in range(max_output_size):
-        # 1. 线性扫描找最优候选
-        best_idx = -1
-        best_val = threshold
-        for i in range(n_elements):
-            val = tl.load(values_ptr + i)
-            better = (val > best_val) & active
-            best_idx = tl.where(better, i, best_idx)
-            best_val = tl.where(better, val, best_val)
-
-        # 2. 检查是否找到有效候选
-        found = (best_idx != -1) & active
-
-        # 3. 记录结果
-        tl.store(selected_indices_ptr + selected_count,
-                 best_idx.to(tl.int32), mask=found)
-        selected_count = tl.where(found, selected_count + 1, selected_count)
-
-        # 4. 标记已选，防止重复
-        tl.store(values_ptr + best_idx, sentinel_value, mask=found)
-
-        # 5. 算子特定逻辑：根据选中元素更新其他元素状态
-        #    - NMS：读取选中元素的数据，计算与其他元素的关系（如 IoU），
-        #            将满足条件的其他元素标记为已选/已抑制
-        #    - TopK：无需此步骤
-        #    - 其他算子：根据业务规则更新其他元素的值或标记
-
-    tl.store(num_selected_ptr, selected_count, mask=active)
-```
-
-**关键点**:
-- `grid=(1,)` 单核执行，顺序依赖算法天然难以并行
-- `best_idx = -1` 初始值，配合 `found = (best_idx != -1)` 判断是否找到有效元素
-- `mask=found` 保护所有依赖 `best_idx` 的 load/store，避免 -1 越界
-- 写入顺序自然为降序，与参考实现 `argsort(descending=True)` 语义一致
-
-## 算子特定扩展
-
-### NMS
-
-在通用模式阶段5加入：读取选中 box 坐标，计算与其他 box 的 IoU，将 IoU >= threshold 的 box 的 score 设为哨兵值（抑制）。
-
-**关键点**:
-- `scores_f32 = scores.float().contiguous()` 保证连续内存访问
-- 输出前 `num_selected` 个为原始索引（按 score 降序），其余为 0
-
-### TopK
-
-无抑制逻辑，阶段5为空。将哨兵值设为 `-float('inf')`。
-
-## 常见错误
-
-```python
-# 错误：Python if 分支
-if score > best_score:
-    best_idx = i
-
-# 正确：tl.where
-best_idx = tl.where(score > best_score, i, best_idx)
-```
-
-```python
-# 错误：标量 flag 累积
-keep = True
-for j in range(n):
-    if iou >= threshold:
-        keep = False
-
-# 正确：通过内存状态传递
-tl.store(scores_ptr + j, -1.0, mask=suppress)
-```
-
-```python
-# 错误：先收集所有保留元素再截断（破坏降序）
-# 正确：每次迭代只选一个，天然满足降序和数量限制
-```