@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/channel-buffer.md

@@ -0,0 +1,36 @@
+# Channel 与 Buffer：明确槽位选择和实际访问
+
+`Channel` 是带独立读写游标的片上槽位池。`produce()` 选择写游标对应的 Tensor 并推进写游标，`consume()` 对读游标做同样的事。选择本身不读写数据、不等待，也不检查队列满空；返回值是共享存储的别名。
+
+## 核心写法：先选择，再对 Tensor 操作
+
+以下为设备 DSL 结构伪码；示例每轮各选择一次写槽位与读槽位，编译器分析后续操作的资源访问。
+
+```text
+from cannbotdsl import Channel, MemLoc, dtypes, mem_copy
+
+tiles = Channel(MemLoc.UB, (TILE_ROWS, TILE_COLS), dtypes.float32, depth=DEPTH)
+for task in 本核任务:
+    write_tile = tiles.produce()
+    mem_copy(write_tile, 当前任务的合法 GM 输入视图)
+
+    read_tile = tiles.consume()
+    对 read_tile 执行计算
+    mem_copy(当前任务的合法 GM 输出视图, read_tile)
+```
+
+`produce()` 与 `consume()` 从各自的零游标开始推进。实现需要保证任务、游标次数和实际访问对应；不能把一次 `consume()` 当作等待数据的动作。一个已选 Tensor 的多个视图仍指向同一槽位，后续槽位复用会覆盖其内容。
+
+## 槽位、视图与容量
+
+- `depth` 必须是正的编译期 Python 整数；`ChannelKind.CrossCore` 的每个 Channel 深度上限为 8。选择深度还需考虑容量与在途任务，不默认使用最大值。
+- 跨核交接时显式使用 `kind=ChannelKind.CrossCore`，并让实际读写操作可被编译器分析；手工同步的作用域见 [同步](synchronization.md)。
+- 先 `produce()/consume()` 取得 Tensor，再调用 `tile_slice` 或 `reinterpret`。创建视图不会再次推进游标。
+- 游标推进必须在 VF 外完成，再把选出的 Tensor 传入 VF。把选择放到寄存器循环内会被拒绝。
+- 动态逻辑 shape 要给出静态 `capacity`，并保证动态尺寸不超出分配；见 [Workspace](workspace.md)。
+
+`Buffer(MemLoc.UB, shape, dtype)` 声明单个片上 Tensor，适合私有临时量。显式空间视图需要绑定时，`make_buffer(view)` 与 `make_channel(views)` 复用已声明存储；不要同时在同一内存空间混用互斥的自动分配与显式空间管理方式。
+
+**反例：** 保存 `produce()` 的结果并认为它保存了数据快照；只推进游标却认为已经发布事件；消费前一任务却使用当前任务的尾块尺寸；把 Channel 直接传给要求 Tensor 的视图 API。
+
+**检查：** 0、1、`DEPTH + 1` 个任务和尾块；流水线启动与排空后读写游标次数一致；重复复用时任务索引、有效范围和数据对应。资源复用安全以实际访问与依赖为依据。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/compilation-launch.md

@@ -0,0 +1,144 @@
+# 编译与启动：复用程序，绑定本次数据
+
+使用 CANNBotDSL 的 `@host` 或显式 `cannbotdsl.compile` 接口，公共结构见 [整体实现](../overall-implementation.md)。编译描述明确静态配置与动态参数，程序调用传入本次数据。
+
+## 统一参数规约
+
+以下是本 skill 的生成约定；接口允许特化某个值，不代表每个调用值都应该成为编译参数。先判断该值是否改变生成代码或静态资源布局，再决定放置位置。
+
+| 类别 | 例子 | 放置与传递方式 |
+|---|---|---|
+| 编译配置 | tile 大小、Channel depth、静态 dtype/布局变体、容量上限 | 使用具名工厂参数，决定编译变体；在工厂内构造 Kernel、`TensorSpec` 等 |
+| 动态张量元数据 | 实际行数、受支持的行跨度 | 用 `Dim` 和 `TensorSpec` 声明范围，调用时绑定当前 Tensor；不为范围内的每个值生成变体 |
+| 运行时标量 | `scale`、实际 `block_num`、需要显式传递的有效长度 | 在 `@host` 签名及 compile 参数描述中声明类型，调用程序时传当前值 |
+| Host 配置 | 公开选项、校验策略 | 在 Host 处理；若选择不同编译变体，则将选择结果明确传给工厂 |
+
+- 同一个参数只维护一套含义与来源。由 Tensor shape 已表达的维度，除非设备接口需要，不再额外传一个可能不一致的标量。
+- `max_rows` 等支持上界是编译配置；本次 `rows` 是动态值。静态容量可以是有依据的具名常量，不能当作本次有效长度或启动核数。
+- 运行时标量用 `dtypes.float32`、`dtypes.int64` 等描述参数类型，不能用本次标量值代替类型描述。`Constexpr[T]` 只用于有意特化的参数；Kernel 构造配置也不应捕获本次 Tensor、stream 或启动核数。
+- 某个维度确实影响静态布局或代码生成时，可明确设为编译配置，并同步调整支持范围、编译变体；不能仅因它是整数就设为编译参数。
+
+## 显式编译与程序复用
+
+```text
+def build_program(column_count: int, max_rows: int, dtype):
+    按静态配置构造 host_entry 和 TensorSpec
+    return cannbotdsl.compile(host_entry, 对应参数描述)
+
+with build_program(column_count, MAX_ROWS, dtypes.float32) as program:
+    对每组满足同一编译契约的输入:
+        program(本次输入, 本次输出, 运行时标量)
+```
+
+`build_program` 是普通构建函数，不隐含缓存行为。编译返回的程序可重复调用；持有方在最后一次使用完成后释放。编译参数应显式表达所有影响生成代码与静态资源布局的配置，不捕获首次输入的 Tensor、workspace 或 stream。
+
+直接调用 `@host` 时由 DSL 管理编译和执行。显式编译时，底层编译产物缓存与 `ProviderCallable` 句柄复用分别处理；仅缓存输出对象不能代替程序复用。关闭句柄、清理编译缓存和释放 Tensor 各有不同生命周期，不要求算子增加统一清理接口。
+
+**检查：** 重复使用程序时，输入地址和值可以变化，shape、stride 与 dtype 仍满足声明契约；静态配置变化时取得相应程序；最后一次使用完成前保持资源有效。
+
+## 启动核数：Host 确定，Kernel 读取
+
+“运行时启动参数”指每次执行时由 Host 确定实际启动数量，再传给已编译程序的 `@host` 入口。公开 Python 入口在内部完成查询，业务调用方无需指定核数。`core_num` 或 `block_num` 都可以作为变量名，保持含义与传递关系清楚即可。
+
+下面演示按 AIC 逻辑 block 启动的路径。输入已校验为有效 NPU Tensor；`MAX_BLOCK_COUNT` 是当前实现的支持上限，来自调度记录容量、资源布局等约束，使用正整数具名常量定义。
+
+```python
+import torch
+from cannbotdsl import get_platform_info
+
+
+def _device_block_num(ref):
+    device_index = ref.device.index
+    if device_index is None:
+        device_index = torch.npu.current_device()
+    stream = torch.npu.current_stream(device_index)
+    info = get_platform_info(stream=stream)
+    available_cores = int(info.cube_core_num)
+    if not info.available or available_cores <= 0:
+        raise RuntimeError("no valid cube core capacity for the input stream")
+    return min(available_cores, MAX_BLOCK_COUNT)
+```
+
+查询和提交使用同一设备、同一 stream。纯 AIV 路径按其 launch 语义参考 `vector_core_num`；混合核路径确认逻辑 block 与核型的映射。这些有效核数字段已考虑 stream 配额。
+
+```text
+# 算子文件顶部
+from cannbotdsl.ops.arch import get_block_idx, get_block_num
+
+# 公开 Python 入口内部；实际核数不加入构建函数参数
+core_num = _device_block_num(x)
+program = build_program(静态配置)
+program(x, output, scale, core_num)
+
+# @host 入口：run(x, output, scale, core_num)
+op[core_num](x, output, scale)
+
+# Kernel 内按需读取 launch 信息，不再添加一个重复的核数实参
+block_idx = get_block_idx()
+block_num = get_block_num()
+使用 block_idx 与 block_num 划分本次任务
+```
+
+compile 参数描述中为 `core_num` 声明 `dtypes.int64`，实际值在 `program(...)` 调用时传入；编译缓存可复用于契约允许的不同核数。`MAX_BLOCK_COUNT` 是支持上限，不能直接代替本次查询结果。
+
+按核分配的 [Workspace](workspace.md) 使用同一个实际核数；存在 [调度记录](aicpu-load-balance-metadata.md) 时，其分核数量与 launch 一致。使用全 launch 屏障还须满足 [同步](synchronization.md) 的驻留与全员参与条件；任务少可以保留空任务核，不能只在启动处随意缩减核数。
+
+**反例：** 将开发设备核数写死在 launch 中；查询失败后用容量上限继续提交 NPU 计算；Host 与 Kernel 分别使用不一致的核数；只改变 launch 数量而复用旧的分核记录。
+
+## 动态维度同时描述 shape 与 stride
+
+下例为二维 ND Tensor，行数与行跨度动态，列连续。共享同一个 `rows` 约束输入输出行数一致；输入行间允许 padding，输出为连续布局。
+
+```python
+from cannbotdsl import Dim, TensorSpec, dtypes
+
+
+def row_specs(column_count: int, max_rows: int, max_row_stride: int):
+    rows = Dim("rows", min=1, max=max_rows)
+    row_stride = Dim("row_stride", min=column_count, max=max_row_stride)
+    input_spec = TensorSpec((rows, column_count), dtypes.float32,
+                            stride=(row_stride, 1))
+    output_spec = TensorSpec((rows, column_count), dtypes.float32)
+    return input_spec, output_spec
+```
+
+只有 Kernel 真正支持该 stride 范围时才声明此契约。`TensorSpec(storage_format="nz")` 使用逻辑 shape 与紧凑逻辑 stride，要求受支持的 dtype、rank 2/3 和正维度；不能把物理 NZ 字节布局直接填成逻辑 stride。
+
+列表输入按需使用 `TensorListSpec(element_spec, length)`：列表非空，元素模板仅支持 ND，各位置的动态维度独立绑定，同 dtype/rank 不代表不同元素 shape 必然相等。`Constexpr[T]` 是形参注解，调用时传原始 Python 值，不构造 `Constexpr(...)` 对象。
+
+## 参数多时按连续区间分组
+
+参数描述统一由构建函数维护。以下结构伪码假定入口已有两个相邻的临时张量参数；名字仅表示资源，不规定算法。逐个具名构造描述，再按签名中的连续区间分组：
+
+```text
+# 入口签名：run(x, scale, scratch_a, scratch_b, output, block_num)
+input_spec = TensorSpec(输入 shape, 输入 dtype, 必要的 stride)
+scratch_a_spec = TensorSpec(临时张量 A 的 shape, 对应 dtype)
+scratch_b_spec = TensorSpec(临时张量 B 的 shape, 对应 dtype)
+output_spec = TensorSpec(输出 shape, 输出 dtype, 必要的 stride)
+workspace_specs = (scratch_a_spec, scratch_b_spec)
+
+program = cannbotdsl.compile(
+    entry.run,
+    input_spec,
+    dtypes.float32,  # scale：保留它在输入与 workspace 之间的位置
+    *workspace_specs,
+    output_spec,
+    dtypes.int64,    # block_num
+)
+program(x, scale, scratch_a, scratch_b, output, block_num)
+```
+
+实际名字改成资源用途，如 `partial_sum_spec`；尺寸用语义参数和派生公式表达。可选参数按编译器支持方式明确描述，存在性影响编译结果时计入缓存键。
+
+**反例：** `specs[4] = float` 按数字补写类型；用一张参数编号表替代清楚的签名；将所有 Tensor 描述移到标量前面；把难以辨认的长元组分散到运行与导出入口。优先使用具名描述和直接排列，避免为简单接口增加只转发的包装层。
+
+## 可执行代码前要核实的三件事
+
+- 编译器将哪些 shape、stride、标量作为静态事实，哪些允许启动时传入。
+- 编译结果的参数顺序、类型和目标设备；进程内并发构建是否需要锁。
+- 启动是否异步、使用哪个 stream，以及输入和临时资源由谁保持存活。
+
+被编译的 Host 与 Kernel 保留可读取的 Python 源码。
+
+**检查：** 相同静态配置但输入值和地址不同；改变一个静态项；改变受支持的动态尺寸；连续调用及要求支持的并发调用。可记录命中键和实际启动尺寸，不能把“缓存命中”当成结果正确的证据。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/host-validation.md

@@ -0,0 +1,34 @@
+# Host 约束校验：先检查，再使用
+
+在分配资源、编译和启动之前，检查输入的类型、shape、dtype、device 与参数组合。只添加当前实现需要的约束，错误信息直接说明哪个参数不合法。
+
+## 简单示例
+
+下例只演示“二维 FP32、宽度为正”的检查顺序，适用于普通 Python eager 入口；这些条件是示例契约，不是通用 DSL 限制。
+
+```python
+import torch
+
+
+def validate_input(x):
+    if not isinstance(x, torch.Tensor):
+        raise TypeError("x must be a Tensor")
+    if x.ndim != 2:
+        raise ValueError("x must have rank 2")
+    if x.dtype != torch.float32:
+        raise TypeError("x must be FP32")
+    rows, columns = x.shape
+    if columns <= 0:
+        raise ValueError("x width must be positive")
+    return rows, columns
+```
+
+按算子契约补充支持的设备、多个输入是否同设备、stride 和标量范围；明确空输入是返回空输出还是拒绝。符号 shape/Fake 路径使用目标环境支持的符号约束表达，不能直接照搬 Python 条件判断。
+
+- `TensorSpec` 描述 dtype、维度关系与 stride；分组整除、可选输入依赖等语义条件仍需显式检查。
+- 设备数据中的索引、长度等值，在约定的设备校验路径处理，并明确错误如何传回；不要默认用 `.item()` 或 `.cpu()` 引入同步。任务表边界见 [AICPU metadata](aicpu-load-balance-metadata.md)。
+- 参数分类与启动核数的确定见 [编译与启动](compilation-launch.md)。
+
+**反例：** 检查 rank 前读取 `shape[1]`；检查除数为正前做取模；用无条件 `.contiguous()` 隐藏不支持的布局。
+
+**检查：** 合法输入正常通过；非 Tensor、错误 rank、错误 dtype、零宽度分别在使用相关数据前报错。按实际契约补充设备、布局和空输入边界。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/layout-tail.md

@@ -0,0 +1,53 @@
+# 布局与尾块：逻辑范围和物理地址分别计算
+
+同一 shape 可以对应不同 stride。以下结构只适用于有明确仿射 stride 的二维视图；ND/NZ 等分块格式须按其真实地址规则处理。
+
+## 核心结构：按输入跨度取数，按有效范围写回
+
+```text
+前提：base 指向视图的第一个逻辑元素；stride 单位为元素
+row_begin = row_tile * tile_rows
+col_begin = col_tile * tile_cols
+valid_rows = min(tile_rows, max(0, rows - row_begin))
+valid_cols = min(tile_cols, max(0, cols - col_begin))
+
+对 r in [0, tile_rows), c in [0, tile_cols):
+    valid = r < valid_rows 且 c < valid_cols
+    if valid:
+        offset = (row_begin + r) * row_stride + (col_begin + c) * col_stride
+        tile[r, c] = input[base + offset]
+    else:
+        tile[r, c] = 当前运算的填充值
+
+计算后只将有效输出写回；输出地址使用 output 自己的 stride
+```
+
+如果底层拿到的是 storage 基址，还需要包含视图的 storage offset，不能重复加或漏加。若硬件搬运要求完整块，必须证明对应物理分配可访问，或选择支持尾部的路径；运算 mask 不能阻止先发生的越界读取。
+
+## 视图与搬运使用不同接口
+
+```text
+from cannbotdsl import tile_slice, reinterpret, make_copy_engine, mem_copy
+
+gm_tile = tile_slice(gm_input, (TILE_ROWS, TILE_COLS), (row_tile, col_tile))
+# coord 是 tile 编号；实际尾块范围取 gm_tile.shape
+slot = l1_tiles.produce()
+nd_to_nz = make_copy_engine(format_transform="nd2nz")
+mem_copy(slot, gm_tile, engine=nd_to_nz)  # slot 已声明为容量足够的 NZ L1 Tensor
+```
+
+- `tile_slice` 保留父视图的跨度，尾块报告实际 extent；调用方仍要保证 tile 坐标在合法范围，不能依赖所有路径都做越界检查。
+- `reinterpret(..., offset=offset_bytes)` 的 offset 单位是**字节**，stride 单位是目标 dtype 的**元素**。它只重解释存储；改变 dtype 不做数值 cast，改变 `data_format` 不会转换原有数据。
+- `permute(gm_tensor, dims)` 为 GM 的 Identity/ND Tensor 创建零拷贝视图，不是片上 Tensor 或 Channel 的通用转置接口。
+- `make_copy_engine` 描述静态搬运方式；`mem_copy` 使用实际 Tensor 视图确定地址。UB 内的格式转换用 VF 实现，不能假定 DMA 支持所有方向的 ND/NZ 转换。
+- 分块格式的内侧 tile 边界还需满足 fractal 对齐。使用 ND2NZ 的 `dst_nd_arrangement="stack_m"` 时，合并后的运行时 `batch * rows` 必须不超过目标静态容量，不能只检查单个矩阵的 rows。
+
+| 运算 | 常用填充值 | 边界 |
+|---|---|---|
+| 求和 | 0 | 累加类型符合精度要求 |
+| 最大值 | 负无穷或类型允许的最小值 | 全无效行须有明确定义 |
+| 乘积 | 1 | 不应把填充元素算入计数 |
+
+**反例：** 用逻辑 `cols` 作为带 padding 输入的行跨度；最大值归约尾部填 0，导致全负输入结果错误；只 mask 写回，却先完整读取越界尾块。
+
+**检查：** 行跨度大于行宽、视图起点非零、单元素尾块、全负最大值输入、跨格式转换后逐元素的逻辑索引一致。Host 是否接受某种 stride 必须与 Kernel 真正支持的寻址一致。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/synchronization.md

@@ -0,0 +1,80 @@
+# 同步：为具体的数据依赖建立顺序
+
+每次同步要回答：哪次写入必须先完成，谁接着读取，哪个资源随后可以复用。事件、屏障、Channel 各自的作用域和内存可见性不能互相猜测替代。
+
+## 使用原则：作用域恰当，数量必要
+
+每个同步点都要对应具体的生产者、消费者或存储复用依赖，并选择能够覆盖该依赖的最小作用域。同步过多会限制计算与搬运重叠；同步不足会产生竞态，不能只按屏障数量判断好坏。
+
+| 实际依赖 | 使用原则 |
+|---|---|
+| 纯寄存器计算的值依赖 | 通过值传递表达，不额外添加内存或跨核屏障 |
+| VF 内重叠存储的读写顺序 | 核实后使用对应模式的 `reg.vmem_bar`，见 [VF](vf.md) |
+| MTE 与计算流水线之间的数据就绪 | 按生产与消费流水线配对事件，明确事件 ID 的复用时机 |
+| 跨核生产消费或多个消费者完成 | 使用支持该参与范围和内存可见性的跨核协议 |
+| 整个 launch 的阶段依赖 | 确实要求全体到达时使用全 launch 屏障，并满足驻留条件 |
+
+- 通知放在所保护的生产操作之后，等待放在首次依赖访问之前；可将不依赖结果的工作安排在等待之前，但不能提前读取数据。
+- 不在每次 load/store、每个 helper 首尾或每轮循环机械添加同步；已有同步仅在确实覆盖相同地址、参与者和代次的依赖时才可复用。
+- 局部依赖不升级为全局屏障；也不能用局部事件替代必要的跨核或全局同步。不要叠加多种同步“兜底”。
+- 合并或删除同步前，核对真实地址重叠、异步完成、事件配对和分支路径。数据就绪与允许覆盖可能是不同依赖，不能因为访问同一 Buffer 就删掉其中一个。
+
+**正例：** 同一流水线的一组生产操作共用一个已确认覆盖整组的完成事件，消费者在首次读取前等待；中间安排无关计算。
+
+**反例：** 每个独立向量运算后都全局同步；等待已经覆盖同一依赖后再加一组等价屏障；将共享槽位的“读完可覆盖”事件当成“新数据已写好”事件。
+
+**轻量检查：** 先逐点标出所保护的访问、作用域与配对关系；不能说明用途的同步先核实依据。改变同步后，只对受影响的复用、空任务或分支路径做必要的正确性验证，并复用 [生产代码](../production-code.md) 的短采样规则检查性能。不以单次运行成功证明不存在竞态。
+
+## 核心结构：区分数据就绪与允许覆盖
+
+下图式伪码适用于两个异步执行角色共享一个槽位；任务代次只是依赖标识，不假定 SDK 提供同名参数。
+
+```text
+生产者                                消费者
+等待 free(slot, 上一代)
+提交写入 data[slot]
+等待写入完成
+发布 ready(slot, 本代)  ------------>  等待 ready(slot, 本代)
+                                      提交读取 data[slot] 和计算
+                                      等待最后一次读取完成
+等待下一次 free        <------------  发布 free(slot, 本代)
+```
+
+将 `slot` 与任务代次绑定，可避免复用事件误匹配旧任务。实际 API 若用固定 flag，需要确认 flag 的初始化、等待/重置语义，以及再次发布前的消费顺序；不能直接把任意任务号映射到有限 flag。
+
+**反例：** 发出 DMA 就发布数据就绪；等待本核事件却假定跨核写入可见；用一次“结果完成”事件代替多个消费者各自的最后读取依赖。
+
+## 跨流水线事件：notify 与 wait 参数同序
+
+```text
+from cannbotdsl.ops.sync import PIPE, vec_sync_notify, vec_sync_wait
+
+向量侧提交 MTE2 读取到 UB
+vec_sync_notify(PIPE.MTE2, PIPE.V, LOAD_TO_VECTOR_EVENT)
+vec_sync_wait(PIPE.MTE2, PIPE.V, LOAD_TO_VECTOR_EVENT)
+向量侧读取 UB 并计算
+```
+
+两次调用都按“生产流水线、消费流水线、事件 ID”排列，wait 不能交换前两个参数。事件常量来自当前任务的资源规划，同一 ID 的再次使用要与已完成的配对一致。Cube 侧有对应的 `cube_sync_notify/cube_sync_wait`；单核内的流水线事件不能代替跨核同步。
+
+## 集体同步与资源复用
+
+```text
+from cannbotdsl import global_sync_all, channel_rewind
+
+if 本核有任务:
+    完成本核当前阶段
+# 所有参与核均到达，不能放在“有任务”分支内
+global_sync_all()
+# 只有下一阶段显式复用片上地址时才需要，且旧存储已无后续访问
+channel_rewind()
+进入下一阶段
+```
+
+`global_sync_all()` 用于整个 launch 的屏障。launch 必须满足单驻留波次要求：参与同步的核型有足够有效核数容纳全部 block；否则可能等待尚未被调度的 block。核数查询与选择规则见 [编译与启动](compilation-launch.md)。
+
+默认屏障使用固定的三个 flag ID；有重叠的手工协议时，使用 `flag_ids=(FUNNEL_IN, CROSS_BLOCK, FUNNEL_OUT)` 明确规划三个互不相同、位于 `[0, 15]` 的 ID，避免冲突。手工 block arrive/wait 配对必须保持相同 mode。
+
+`channel_rewind(reset_sync_id=True)` 声明地址、Buffer ID 和计数器分配阶段边界；它不插入硬件屏障、不释放仍被使用的存储。`reset_sync_id=False` 只保留该边界的计数器分配阶段，也不能替代同步。普通阶段衔接仅需建立实际依赖，无需机械调用 rewind。
+
+**检查：** 任务数小于核数、任务数非整除、慢消费者、重复槽位复用、分支事件配对，以及屏障的参与核和驻留条件。诊断记录具体等待的生产者与消费者。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/torch-registration.md

@@ -0,0 +1,66 @@
+# Torch 注册：复用公开入口的薄适配
+
+需要 `torch.ops`、Meta/Fake 或图模式接入时使用。公共计算与程序生命周期沿用 [整体实现](../overall-implementation.md)；新增 Torch 支持只增加 schema、注册和参数映射，Kernel 与编译参数契约的构建逻辑保持集中维护。
+
+Torch 注册装饰器由 PyTorch 提供；NPU dispatch、Meta/Fake 和图模式支持按实际 PyTorch 与设备后端核对。
+
+## 接入结构伪码
+
+以下描述职责与数据流，注册 API、dispatch key 和符号约束表达以目标 PyTorch 与设备后端版本为准。
+
+```text
+公开入口：operator(public_inputs, public_attributes) → public_outputs
+
+定义 schema:
+    参数名称、顺序、类型、默认值、可选性
+    返回数量与顺序、mutation 与 alias
+
+注册设备实现(schema_args):
+    显式映射 schema 参数到公开入口参数
+    return operator(映射后的参数)
+
+注册 Meta/Fake 实现(schema_args):
+    检查抽象执行环境可表达的元数据约束
+    output_specs = 从输入元数据与属性推导输出描述
+    return 按目标注册机制构造抽象输出
+```
+
+设备实现复用公开入口的校验、资源准备与程序调用。Meta/Fake 只描述输出，不调用公开计算入口、分配真实设备资源或读取设备数据。Meta 与 Fake 是不同接入机制，按目标环境选择，避免重复注册冲突。
+
+## 共享公开契约与输出描述
+
+| 对齐项 | 需要保持一致的内容 |
+|---|---|
+| 参数 | keyword 名称、默认值、可选性与标量含义；名称不同时显式映射 |
+| 返回 | Tensor 数量、顺序、可选结果及嵌套结构 |
+| 输出属性 | shape、dtype、stride 及对应抽象环境的 device 语义 |
+| 副作用 | 输入是否被修改、输出是否与输入共享存储 |
+
+输出推导复杂时，将其抽取为纯元数据函数，由真实分配与抽象描述共用。符号 shape 路径保留符号表达，使用该环境支持的约束检查；数据依赖的输出 shape 需要专门支持，不能读取设备值来补齐推导。
+
+### 核心例子：返回有效视图时保留真实 stride
+
+假设局部契约返回二维输出，但底层每行分配 `padded_cols` 个元素，只暴露前 `cols` 列：
+
+```text
+物理分配：storage.shape = (rows, padded_cols)，行连续
+真实返回：output = storage[:, :cols]
+共同描述：shape = (rows, cols)
+          stride = (padded_cols, 1)
+          dtype = 公开输出类型
+          与输入无 alias
+
+Meta/Fake 按共同描述构造抽象输出
+```
+
+若只按 `(rows, cols)` 构造普通连续 Tensor，抽象输出的行 stride 会变为 `cols`，与真实返回不一致。描述推导应来自实现采用的 padding 规则，而非复制输入属性。
+
+## 注册对象与图模式
+
+namespace、schema、注册对象生命周期和 dispatch key 按当前工程维护；导入后注册对象应在所需期间保持有效。设备实现直接委托公开入口，避免维护另一套计算或编译缓存。
+
+需要图模式时，按公开支持范围增加追踪接入，并保持参数、返回与副作用契约。自动求导和动态 shape 各自需要实现依据与验证；注册成功不自动提供这些能力。
+
+**反例：** 设备注册漏传非默认参数；schema 宣称函数式调用而实现修改输入；Meta/Fake 使用 `empty_like(input)` 描述不同布局的输出；图替换遗漏一个返回值；在注册文件复制 TensorSpec 或 Kernel 实现。
+
+**检查：** 直接调用与 dispatcher 调用在默认、非默认和可选参数下结果一致；真实与抽象输出的 shape、dtype、stride、结构及 alias 一致；仅对公开要求的图模式、符号 shape 和梯度路径执行相应验证。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/vf.md

@@ -0,0 +1,144 @@
+# VF：先写清寄存器内的计算和有效 lane
+
+适用于向量加载、逐元素操作、归约和类型转换。具体指令、向量宽度、mask 粒度及支持 dtype 以当前 DSL 和设备为准。下面的代码块为结构伪码；明确列出的 API 使用当前包的实际名称，中文步骤由具体实现填写。
+
+导入方式为 `from cannbotdsl import vf`，在设备 DSL 计算中使用上下文管理器，不使用 `@vf`：
+
+```text
+with vf(mode="simd"):
+    执行寄存器向量计算
+```
+
+## 条件执行：VF 内不写 if
+
+本 skill 要求 VF 区域及其展开的辅助逻辑不使用 `if/elif/else`，也不用条件表达式隐藏分支。能在 VF 外决定是否进入整个计算片段时，优先外置判断；逐 lane 的条件使用受支持的 mask/选择指令。
+
+按条件的作用范围选择结构，避免把所有判断都改成循环：
+
+| 条件控制的范围 | 推荐结构 |
+|---|---|
+| 是否执行整个 VF 片段 | 在 VF 外判断，片段内部保持顺序计算 |
+| 同一向量中哪些 lane 有效 | 使用指令支持的 mask 或选择操作；mask 不能保护不支持 masked load 的完整读取 |
+| VF 内某个片段是否执行一次 | 前两种结构不合适时，使用零次或一次的 `for` |
+
+**优先结构：在 VF 外决定是否执行整个片段。**
+
+```text
+if execute_fragment:
+    with vf(mode="simd"):
+        执行完整向量计算片段
+```
+
+必须在 VF 内按标量条件执行一段代码时，用执行零次或一次的 `for` 表达。循环上界是已规范化的整数 `execute_count`，在其条件可用的位置计算：条件为假取 0，为真取 1。它是整个片段的标量条件，不能直接把 lane mask 当循环次数。
+
+**正例：条件成立执行一次，自然结束。**
+
+```text
+# 文件顶部导入 vf、reg；VF 外准备标量循环次数
+execute_count = 将标量条件转换为受支持的整数 0 或 1
+with vf(mode="simd"):
+    for _ in range(0, execute_count):
+        完成一次条件向量计算
+    执行后续公共计算
+```
+
+**反例：直接分支，或用固定循环掩盖分支。**
+
+```text
+with vf(mode="simd"):
+    if condition:
+        执行条件计算
+
+with vf(mode="simd"):
+    for _ in range(1):
+        if not condition:
+            break
+        执行条件计算
+```
+
+`range(0, execute_count)` 本身保证最多一次，不在循环体内修改上界或依赖 `break` 退出。无论使用外置判断还是条件循环，被跳过的代码都不能是输出或后续输入的唯一初始化位置。实际整数转换和动态循环以 DSL 前端支持为准；这里的规则是生成约定，不宣称接口本身禁止所有分支。
+
+**检查：** 条件假时执行零次，条件真时恰好一次；两条路径都能继续公共计算，且不会读取未初始化结果。检查 VF 展开的 helper，避免间接带入分支。
+
+## 具体接口：计数 mask 与完整向量读取
+
+```text
+from cannbotdsl import vf, reg
+
+# tile 已在 VF 外从 Channel 选出，FP32 UB 起点/跨度满足指令对齐
+# backing allocation 覆盖所有完整向量读；VL 是已确认的 FP32 lane 数
+with vf(mode="simd"):
+    counter = reg.mask_counter(valid_elements)
+    for offset in range(0, padded_elements, VL):
+        mask, counter = reg.update_mask(counter, elem_bits=32)
+        values = reg.vload(tile, offset)
+        scaled = reg.vmuls(values, scale, mask=mask)
+        reg.vstore(tile, offset, scaled, mask)
+```
+
+`update_mask` 返回 mask 与剩余计数，循环中显式接回计数。满 mask 使用 `reg.create_mask(pattern="all", elem_bits=32)`。`reg.vload` 不接受 mask 参数，会读取完整向量；只限制运算/写回不能保护越界 load，因此 `padded_elements` 必须在实际分配范围内。
+
+`vload/vstore(post_update=True)` 将 offset 解释为每次访问后推进的元素步长；采用这种模式时不要再手动累加同一游标。`vload_unpack` 不应依赖 post-update 推进，使用显式地址偏移。Channel 的选择操作始终位于 VF 外。
+
+## 核心结构：一行归约，跨向量块累计
+
+前提：二维输入列连续、行跨度明确，输出为每行一个 FP32 和。`VL` 表示当前计算类型的 lane 数。
+
+```text
+对每个 row:
+    row_sum = FP32(0)                         # 每行重新初始化
+    对 col = 0, VL, 2*VL, ... 且 col < cols:
+        valid_lanes = min(VL, cols - col)
+        mask = lane_id < valid_lanes
+        values = 安全读取 input[row * row_stride + col] 的有效 lane
+        values = 转为 FP32；无效 lane 填 0
+        chunk_sum = 对有效 lane 做求和归约
+        row_sum = row_sum + chunk_sum
+    output[row * output_stride] = row_sum     # 每行只写最终结果
+```
+
+“安全读取”须落到当前指令支持的 masked load，或已分配且可访问的 padding。只对后续计算加 mask，不能保护前面的完整向量读。归约顺序与累计类型按误差要求选择，不保证与串行求和逐位一致。
+
+**反例：** `row_sum` 放在所有行外面；每个向量块覆盖同一个输出；最后一个块沿用满 mask；FP16 输入未经设计就在 FP16 中累计；用逻辑行宽跨越带 padding 的行。
+
+## 类型转换：分清数值转换和存储打包
+
+```text
+源地址按源元素类型与 source_stride 计算
+读取源元素 → 按指令要求 unpack 到计算 lane
+按舍入/溢出契约执行数值 cast
+按目标存储要求 pack → 以 target_stride 写入有效元素
+```
+
+cast 改变数值表示，pack/unpack 处理存储与 lane 布局，不能互相替代。不同宽度的类型可能对应不同有效 lane 数与 mask 粒度，须随指令确认；不要复制某个实现的固定向量步长。
+
+**检查：** 行宽为 `VL-1`、`VL`、`VL+1`，两行取不同常数以暴露累计状态泄漏；带行 padding；大幅值和抵消输入的误差；窄化转换的舍入、溢出和特殊值契约。诊断记录所用类型、步长和尾部有效数即可。
+
+## 内存屏障：只保护实际访问依赖
+
+这里所说的 `vmembar` 对应包接口 `reg.vmem_bar(mode)`，可用模式为 `"vst_vld"` 和 `"vld_vst"`。它用于 VF 内存访问顺序，不替代 MTE 与向量流水线之间的事件，也不替代跨核同步；作用域选择见 [同步](synchronization.md)。
+
+- 先确定哪些存储地址重叠，以及是写后读还是读后覆盖，再选择对应模式。在必要的依赖边界插入，不在每条寄存器算术、每个循环迭代或 VF 首尾机械添加。
+- 后续仍可直接使用已有寄存器值时，保留该值，避免无必要的 store → barrier → load。寄存器之间的值依赖不需要靠内存屏障表达。若地址互不重叠，或已有机制确实覆盖同一访问顺序，不重复添加。
+- 不为减少数量而跨越必需的读写依赖合并屏障；不能仅凭源码顺序或一次结果正确就认定屏障冗余。
+
+**正例：同一 VF 中，写回 scratch 后确需重新加载，且该依赖需要显式排序。**
+
+```text
+# scratch 的完整向量范围可访问，full_mask 覆盖写入和后续读取
+reg.vstore(scratch, offset, values, full_mask)
+reg.vmem_bar("vst_vld")
+reloaded = reg.vload(scratch, offset)
+使用 reloaded 继续计算
+```
+
+**反例：纯寄存器计算之间反复插入屏障。**
+
+```text
+scaled = reg.vmuls(values, scale, mask=mask)
+reg.vmem_bar("vst_vld")
+shifted = reg.vadds(scaled, bias, mask=mask)
+reg.vmem_bar("vst_vld")
+```
+
+`vld_vst` 用于需要保护的读后覆盖边界；不要把两种模式都插入来掩盖未分析的依赖。检查或调整屏障时，核对生成代码中的相关访存与屏障，再用覆盖该依赖的最小用例验证；普通命名、注释修改无需重复设备测试。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/workspace.md

@@ -0,0 +1,67 @@
+# Workspace：容量按物理布局算，复用按生命周期算
+
+这里管理计算临时存储。用于分轮、分核和任务描述的调度记录见 [AICPU metadata](aicpu-load-balance-metadata.md)；调度协议不放在 workspace 中重复定义。
+
+## 核心公式：带行 padding 的循环槽位
+
+假定每个槽位显式分配完整的 `rows × row_stride` 存储，列连续，`row_stride >= cols`，包括最后一行的 padding。
+
+```python
+def workspace_bytes(rows, cols, row_stride, item_bytes, depth, alignment_bytes):
+    if rows < 0 or cols < 0 or row_stride < cols:
+        raise ValueError("invalid physical shape")
+    if item_bytes <= 0 or depth <= 0 or alignment_bytes <= 0:
+        raise ValueError("invalid item size, depth, or alignment")
+    raw_slot_bytes = rows * row_stride * item_bytes
+    slot_bytes = ((raw_slot_bytes + alignment_bytes - 1) // alignment_bytes) * alignment_bytes
+    return depth * slot_bytes
+```
+
+槽位 `s` 的字节起点为 `s * slot_bytes`。分配基址也要满足对齐；仅将每个槽位尺寸对齐还不够。该公式不适用于任意非连续视图或分块格式。Host 计算结果在传给固定宽度接口前检查溢出与可用容量。
+
+## 区分 GM 临时张量与片上容量
+
+Host 用 Tensor 分配 GM workspace，并在编译入口为每个必要参数声明 `TensorSpec`。设备内的 `Buffer/Channel` 由片上资源规划管理；二者不能共用一个“总 workspace 字节数”替代各自容量检查。
+
+```text
+from cannbotdsl import Buffer, Channel, MemLoc, dtypes
+
+# 在设备 DSL 中，valid_rows 是合法的运行时 i64 尺寸
+scratch = Buffer(MemLoc.UB, (valid_rows, TILE_COLS), dtypes.float32,
+                 capacity=(MAX_TILE_ROWS, TILE_COLS))
+tiles = Channel(MemLoc.L1, (valid_rows, TILE_COLS), dtypes.float16,
+                capacity=(MAX_TILE_ROWS, TILE_COLS), depth=DEPTH)
+```
+
+`capacity` 是正的编译期整数元组，与逻辑 shape 同 rank；动态 shape 使用静态 backing stride。调用方保证 `0 < valid_rows <= MAX_TILE_ROWS`，空任务走显式空路径；`capacity` 不会自动截断超限访问。
+
+Host 可用 `get_mem_size("ub")`、`get_mem_size("l1")` 等查询单层片上容量，返回单位为字节；不可用时返回 0，应停止该配置的规划。评估占用须计入同时存活的全部资源、Channel 各槽位和布局对齐，查询结果不等于当前剩余可分配字节数。
+
+## 按核 workspace 使用实际启动数量
+
+需要每个 block 独立的临时空间时，Host 按本次 `core_num` 分配，编译描述允许该维度在支持范围内变化：
+
+```text
+# 编译描述；elements_per_block 是静态配置
+core_count = Dim("core_count", min=1, max=MAX_BLOCK_COUNT)
+scratch_spec = TensorSpec((core_count, elements_per_block), dtypes.float32)
+
+# Host 分配；同一个 core_num 继续传给 @host 的 launch 参数
+scratch = torch.empty((core_num, elements_per_block), dtype=torch.float32, device=x.device)
+```
+
+动态 shape 的 `Dim` 与独立的启动标量不会因名字相同就自动建立相等约束；Host 保证 `scratch.shape[0] == core_num`。只在实现需要按核存储时采用此结构，核数来源见 [编译与启动](compilation-launch.md)。
+
+## 复用条件：最后读者已完成
+
+```text
+阶段 A 写 scratch → 阶段 B 读 scratch → B 的最后读取完成
+                                            ↓
+                               阶段 C 才能覆盖同一存储
+```
+
+同一 stream 的有序执行可以建立相应依赖；多 stream 或多角色使用时需要额外证据。运行时提前返回不代表设备已经结束，资源释放须遵循当前执行环境的异步生命周期约定。
+
+**反例：** 使用 `rows * cols` 给带 padding 的搬运分配存储；用总任务数分配本可循环复用的私有槽位；按峰值在途槽位分配后却没有复用同步；不同阶段或不同 stream 同时写同一空间。
+
+**检查：** 最大 shape、尾块、对齐边界、多次调用和并发调用；确认每次读取前有效元素已初始化。零填充只用于算法需要的区域，不用整块清零掩盖未写输出。