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

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/API.md.templ

@@ -0,0 +1,67 @@
+# 执行能力与约束
+
+从计算、分支及调度方案中提取实际需要的能力，以目标设备资料与验证证据确定可行范围。
+
+## 能力映射
+
+| 阶段或步骤 | 所需计算、搬运或同步能力 | 输入输出与关键参数 | 类型、布局及执行限制 | 依据 | 结论 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+按实际需要描述布局表达、访问粒度、矩阵或向量计算、协作、原子性与可见性。固定要求与可变参数的表达条件分别记录。
+
+## 可行性证据与待验证项
+
+| 能力或组合链 | 资料及适用版本 | 已有验证与范围 | 最小补证场景及通过条件 | 后续依赖 | 失败后的设计调整 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+最小场景使用最终选用的类型、布局、角色与共享范围，给具体输入及期望数据。复杂链可从单个步骤逐步验证至组合链。资料支持、实现验证及设备行为证据分别说明。
+
+## 数据流与完成条件
+
+每条实际数据通路给源与目的的物理形状、步长、类型、偏移及前提，关联 Kernel.md 的装载、计算与存储步骤。跨角色或跨阶段传递说明完成、可见性及复用条件。
+
+```mermaid
+flowchart LR
+    Input[输入存储] --> Stage[计算阶段]
+    Stage --> Output[输出存储]
+```
+
+## 资源约束核对
+
+资源数量与容量引用 LaunchData.md，生命周期引用 Kernel.md。核对所选能力带来的格式填充、对齐、访问宽度和额外临时存储；变化同步更新资源计划与分支。
+
+## 操作职责核对
+
+沿结果产生路径核对检查、重排、初始化、计算及合并的归属，使每项数据操作都有设计依据和资源记录。
+
+## 参考示例：操作与数据通路
+
+下面保留从参考实现抽出的调用形态，说明数据通路需要核对的能力。`verified_copy_engine` 与矩阵步骤是待实例化的具名占位；实际选用时核对类型、布局、对齐、目标版本和完成条件。
+
+实际调用的签名与上下文约束，以目标版本的 DSL 源码或官方资料为依据，逐项核对搬运、矩阵计算与向量计算的使用条件。
+
+```python
+# 设计伪代码：按本算子选择，不要求全部使用。
+source = tile_slice(gm_input, tile_shape, tile_coord)  # tile 编号，而非元素偏移
+mem_copy(input_channel.produce(), source, engine=verified_copy_engine)
+local_input = input_channel.consume()
+
+# 需要矩阵阶段时：先记录 L1/L0A/L0B 的真实形状、转置和 Channel 深度，
+# 再以已验证的 matmul 参数替换下面抽象运算。
+# left = left_l0a.consume()
+# right = right_l0b.consume()
+# result = result_l0c.produce()
+# matmul(result, left, right, init=is_first_accumulation)
+
+# 需要寄存器向量链时：列 VF 签名、mask、读写宽度与 tail 处理。
+# 当前参考版本采用 with vf(mode="simd")；
+# Channel 先在 VF 外选槽，再将所选 Tensor 传入 VF。
+
+mem_copy(gm_output_tile, output_channel.consume())
+```
+
+片段中的 Channel 及缓冲按资源表预先定义，输出槽由前置计算写入后再消费。矩阵片段显式给目的对象，首次累加由初始化规则决定；当前步骤和后续写回之间的交接按生命周期核对。
+
+`make_copy_engine`/`CopyBlockMapping` 仅用于真正需要的格式变换或分块映射；`reinterpret`/`permute`/`tile_slice` 必须核对物理 stride 与容量；`matmul`、`vf` 和跨核同步只在算法需要时出现。对于每个被采用的调用，记录“为什么这个 API 能表达本步骤”和一个可执行的最小验证场景。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/DevView.md.templ

@@ -0,0 +1,67 @@
+# 开发视图
+
+## 交付职责
+
+按实际交付布局列对象职责，覆盖公开入口、调度、计算、独立参考结果及验证。共享配置、持有资源和释放位置与设计契约一致。
+
+| 文件或对象 | 职责及拥有者 | 输入与输出 | 生命周期 | 对应设计 |
+|---|---|---|---|---|
+| | | | | |
+
+## 调用与数据流
+
+从调用者、信息准备、配置选择、执行阶段到结果返回画流程图。边上标明参数、数据与资源的传递，跨阶段完成条件单独标注。
+
+## 共享逻辑与路径
+
+| 对象或阶段 | 共享定义 | 路径差异 | 对应分支及验证 |
+|---|---|---|---|
+| | | | |
+
+与 TemplatePartition.md 一一对应。运行、重复调用或导出契约有要求时，说明共享配置、产物和资源的拥有者及有效范围。
+
+## 开发与验证入口
+
+说明各职责的开发顺序与依赖、如何取得独立参考结果、运行路径用例和采集证据。关键能力待验证时给验证任务与通过条件。
+
+## 文件与调用链参考示例
+
+以下保留一种代码组织及调用链的表达方式，实际文件和对象由上述职责映射确定。
+
+```text
+<算子目录>/
+  <公开入口与 DSL 实现文件>
+  <独立 Golden 与测试文件>
+```
+
+```mermaid
+flowchart LR
+    Caller[调用者] --> Entry[公开入口]
+    Entry --> Factory[DSL 显式编译]
+    Factory --> Program[ProviderCallable]
+    Program --> Launcher[host 入口]
+    Launcher --> Kernel[DSL Kernel]
+    Kernel --> Output[输出]
+```
+
+## 参考示例：两种代码组织
+
+`flash_attn.py` 将配置/资源计划、Launcher、Kernel 阶段对象放在同一 Python 模块；`flash_kda.py` 还包含编译规格构造、公共 Host 包装和可选的图执行注册。下面只表达职责，不要求生成这些目录或注册接口：
+
+```text
+公开函数
+  ├─ 输入元数据校验与输出/Workspace 分配
+  ├─ 配置选择 + ResourcePlan（适用时）
+  ├─ 显式构建 → cannbotdsl.compile(@host 入口, specs...)
+  ├─ ProviderCallable(本次 Tensor 与运行时参数)
+  │    └─ Program.run @host
+  │         └─ @kernel __call__: block→task→tile
+  │              ├─ CopyIn: GM→Channel/Buffer
+  │              ├─ Compute: @jit 阶段 / 可选 VF、matmul
+  │              └─ CopyOut: Channel/Buffer→GM
+  └─ 返回输出
+
+独立 Golden / 黑盒、白盒、结构测试 → 只通过公开函数观察行为
+```
+
+该示例表达配置、构建、调度和计算的职责映射，具体对象由交付表确定。调用与导出路径存在时，说明配置共享、产物拥有者与释放位置；图注册及辅助记录按实际契约展开。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/HostLaunch.md.templ

@@ -0,0 +1,119 @@
+# 调度与启动方案
+
+## 1. 输入检查与输出所有权
+
+| 检查条件 | 合法域与依据 | 信息可获得的位置 | 失败行为 | 接口规则 |
+|---|---|---|---|---|
+| | | | | |
+
+逐输出给分配方、形状、类型、布局及别名约束，说明完整写入的条件。尺寸依赖数据值时，给尺寸生产、取得和后续消费的顺序。
+
+| 边界条件 | 各输出的形状及初始化 | 执行或提前完成的条件 | 完成与返回行为 |
+|---|---|---|---|
+| | | | |
+
+## 2. 配置选择
+
+说明判定信息、候选生成及筛选顺序、资源检查、路径选择和超限处置。各项选择关联 TemplatePartition.md 与 LaunchData.md 中的公式和支持域。
+
+## 3. 任务与坐标划分
+
+定义总任务数和执行单元数，给执行单元到任务区间、各任务到输出范围及内部工作项的公式。结合目标设备资源和负载均衡说明选取依据，证明覆盖完整及共享写入满足所有权协议。
+
+| 分支 | 任务数公式 | 执行单元数公式 | 单元到任务及输出范围 | 边界与不均衡处理 |
+|---|---|---|---|---|
+| | | | | |
+
+协作执行时，任务内部角色及汇合规则引用 Kernel.md；状态相互依赖的工作项遵守其推进顺序。
+
+## 4. 参数与布局准备
+
+按 LaunchData.md 的参数顺序列实际取值、形状关系、步长、容量、可选状态和初始化步骤。视图给共享地址依据，实际重排列入执行阶段并计入资源预算。
+
+## 5. 启动、阶段边界与生命周期
+
+| 阶段 | 任务范围及参数 | 前置完成条件 | 结果可见条件 | 临时资源有效期 | 失败处置 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+用流程图或算法伪代码说明配置、分配、启动、等待及返回关系。跨阶段依赖明确同步参与者与完成发布；资源保持有效至最后使用完成。
+
+调用、重复执行及导出契约有要求时，说明共享配置的范围、产物拥有者与释放时点。
+
+## 6. 操作职责
+
+| 公开入口至结果返回的操作 | 信息准备或计算职责 | 输入与输出 | 归属阶段及依据 |
+|---|---|---|---|
+| | | | |
+
+追踪所有会改变数据的操作，使计算、重排、初始化及合并都对应明确阶段、工作量和资源。
+
+## 参考示例：公开入口、构建与启动
+
+```text
+取得合法输入信息
+→ 生成与筛选候选配置
+→ 核对各内存池及临时存储
+→ 确定任务划分与阶段参数
+→ 启动、完成及返回
+```
+
+以下保留显式构建与启动的参考骨架，调用形态参考 `flash_kda.py`。本例与 Kernel.md 的一维、同形输出、带临时工作区示例对应；具名检查、分配、规格构造及边界函数是需要按设计展开的抽象操作。配置、参数规格与每次调用的顺序在本例中逐项对应。
+
+实际使用时，依据目标版本的 DSL 源码或官方资料核对程序构建、调用、持有与释放的生命周期约束。
+
+```python
+import cannbotdsl
+from cannbotdsl import Tensor, TensorSpec, dtypes, host
+
+
+class OperatorProgram:
+    def __init__(self, config, input_dtype, output_dtype, accumulator_dtype):
+        self.tile_elems = config.tile_elems
+        self.pipeline_depth = config.pipeline_depth
+        self.input_dtype = input_dtype
+        self.output_dtype = output_dtype
+        self.accumulator_dtype = accumulator_dtype
+
+    @host
+    def run(self, x: Tensor, out: Tensor, ws: Tensor, attr: int, block_dim: int):
+        op = OperatorKernel(
+            self.tile_elems, self.input_dtype, self.output_dtype,
+            self.accumulator_dtype, self.pipeline_depth,
+        )
+        op[block_dim](x, out, ws, attr)
+
+
+def build_program(config, input_meta, plan):
+    entry = OperatorProgram(
+        config, input_meta.dtype, output_dtype_from_contract(input_meta),
+        accumulator_dtype_from_contract(input_meta),
+    )
+    # 规格包含全部形状、类型、步长及工作区容量。
+    input_spec, output_spec, workspace_spec = make_tensor_specs(config, input_meta, plan)
+    return cannbotdsl.compile(
+        entry.run, input_spec, output_spec, workspace_spec,
+        dtypes.int64,  # attr
+        dtypes.int64,  # block_dim
+    )
+
+
+def public_op(x, *, attr):
+    check_interface(x, attr)
+    meta = metadata_of(x, attr)
+    out = allocate_output(output_shape(x, attr), output_dtype_from_contract(meta), x.device)
+    if boundary_completes_without_launch(meta):
+        return initialize_and_return_boundary_outputs(out, meta)
+    config, plan = select_config(meta, device_limits(x.device))
+    ws = allocate_workspace(plan.workspace_bytes, x.device)
+    block_dim = choose_blocks(x.shape, config, device_limits(x.device))
+    with build_program(config, meta, plan) as program:
+        program(x, out, ws, attr, block_dim)
+    return out
+```
+
+本例的 `@host` 参数与规格顺序均为 x、out、ws、attr、block_dim，计算入口接收 x、out、ws、attr，长度从一维输入形状取得。分块、深度与类型在构建时确定，attr 与 block_dim 在调用时绑定。边界函数逐输出遵循接口契约。
+
+实际路径的工作区、输出个数及参数变体以阶段参数表为准，修改时同步检查入口、规格与实参。跨阶段保持临时资源有效至最后使用完成。
+
+示例在单次调用内管理程序；重复调用的持有与释放位置由生命周期契约确定。构建、复用及缓存行为分别定义。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/InferShapeDtype.md.templ

@@ -0,0 +1,56 @@
+# 形状与数据类型推导
+
+## 逐输出形状
+
+| 输出 | 依赖的形状、属性或数据值 | 逐维公式及索引域 | 合法边界 | 尺寸信息可用阶段 |
+|---|---|---|---|---|
+| | | | | |
+
+对实际采用的广播、重排、切分或变长结构给具体维度关系与范围检查。值依赖形状说明生产者、取得时点和容量约束；接口中有效长度与物理容量分别定义。
+
+## 数值计算链
+
+按 Interface.md 的完整支持组合，展开输入、主要中间量、累计状态、最终输出的类型与精度。转换会影响结果时给明确位置。
+
+| 组合 ID | 运算或中间量 | 输入与输出类型 | 运算或累计精度 | 转换、舍入或溢出规则 |
+|---|---|---|---|---|
+| | | | | |
+
+浮点路径说明误差来源和稳定性条件；整数、布尔及索引路径说明范围与精确性要求。运算重排或近似变换给适用条件，并关联 Validation.md 的比较规则。
+
+## 逻辑布局到物理存储
+
+| 对象 | 逻辑形状 | 物理布局、步长及偏移 | 容量公式 | 视图或实际数据重排 |
+|---|---|---|---|---|
+| | | | | |
+
+视图给共享存储与地址范围依据；实际重排给执行阶段、两侧存储和额外开销。填充范围与有效数据范围分别标明，相关资源计入 LaunchData.md。
+
+## 推导代入
+
+选择正常输入及会改变边界或解释的输入，逐输出代入形状、类型和地址公式。动态维度路径另选一个维度关系变化的输入，核对参数绑定、输出范围与资源容量。
+
+| 输入形状、类型及属性 | 推导的输出 | 物理范围及容量 | 边界处置 | 对应验证用例 |
+|---|---|---|---|---|
+| | | | | |
+
+## 参考示例：形状与布局推导
+
+以下保留纯元信息形状与值依赖形状的推导示例，步骤函数均为数学或存储操作占位。`flash_kda.py` 提供由输入形状确定输出及填充工作区尺寸的参考；接口最终暴露实际有效范围。
+
+```python
+# 纯元数据：每个输出逐维推导。
+logical_shape = infer_from_shapes_and_attrs(input_shapes, attrs)
+physical_shape = align_for_kernel(logical_shape, tile_requirements)
+out_storage = allocate(physical_shape, inferred_output_dtype)
+physical_strides = storage_strides(out_storage)
+public_out = zero_copy_view(out_storage, logical_shape, strides=physical_strides)
+# physical_strides 从实际分配取得，证明偏移及有效范围。
+
+# 值依赖：设备阶段先产生尺寸/前缀信息。
+shape_meta = produce_shape_metadata_on_device(inputs)
+synchronize_or_split_launch(shape_meta)
+logical_shape = read_or_consume_metadata_under_supported_contract(shape_meta)
+```
+
+若运行环境不允许读取设备产生的尺寸到 Host，说明固定容量输出、显式长度返回或多阶段设备消费的接口选择。不能把“值依赖”伪装成纯 Host shape 推导。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/Interface.md.templ

@@ -0,0 +1,61 @@
+# 接口契约
+
+## 输入、属性与输出
+
+根据 spec.yaml 列出完整有序接口，说明必选、可选、默认值及返回关系。
+
+| 顺序 | 名称与类别 | 形状、数据类型与布局 | 默认值或可选条件 | 规格依据 |
+|---|---|---|---|---|
+| | | | | |
+
+## 支持组合
+
+一行对应一个完整的支持组合，包含全部输入、输出与约束。独立的类型集合按规格确定合法配对；转换及累加精度引用 InferShapeDtype.md 的计算链。
+
+| 组合 ID | 输入数据类型 | 输出数据类型 | 属性及布局条件 | 相关计算链 |
+|---|---|---|---|---|
+| | | | | |
+
+## 形状、布局与可选状态
+
+| 对象 | 维度及合法关系 | 物理布局与步长 | 对齐及容量 | 可选状态的表示 |
+|---|---|---|---|---|
+| | | | | |
+
+按支持域说明标量、广播、动态维度、非连续布局及可选输入的解释。可选状态采用可区分的契约；形状依赖数据值时，注明尺寸信息的生产与取得方式。
+
+## 合法性、所有权与边界
+
+| 条件 | 合法域 | 可判定阶段 | 输出或错误行为 | 规格依据 |
+|---|---|---|---|---|
+| | | | | |
+
+逐输出说明分配方、有效范围、输入输出别名及原地更新约束。临时资源给拥有者与生命周期。特殊边界逐输出定义形状、初始化值及是否需要执行；相关调度引用 HostLaunch.md。
+
+## 接口到执行阶段的映射
+
+| 公开对象或属性 | 阶段参数或派生量 | 推导依据 | 首次消费阶段 | 有效期 |
+|---|---|---|---|---|
+| | | | | |
+
+参数规格在 LaunchData.md 统一定义，实际取值与准备顺序在 HostLaunch.md 展开。根据可获得的信息安排检查；依赖数据值的条件在使用前完成相应验证。
+
+## 参考示例：入口校验
+
+```python
+# def <op>(...): ...  按接口表的实际顺序、可选关系及返回值实例化
+```
+
+`flash_kda.py` 的公开包装展示了用 shape、dtype、device、contiguous/stride 和属性做 Host 判定的做法。下面是类别示意，不是该算子的默认限制；实际允许域必须逐项从 spec 填入上表。
+
+```python
+def validate_public_inputs(x, y, attr):
+    require_rank(x, allowed_ranks)
+    require_dtype_pair(x.dtype, y.dtype, supported_combinations)
+    require_same_device(x, y)
+    require_layout_stride(x.shape, x.stride(), allowed_layouts)
+    require_attr(attr, allowed_attr_domain)
+    # 只检查 Host 可取得的元数据；设备 Tensor 值的约束交给设备路径。
+```
+
+此例的 require 系列是接口检查占位，实际合法条件与错误由上面的契约决定。可选对象的缺省表示及调用参数映射按阶段参数表核对。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/templates/design/Kernel.md.templ

@@ -0,0 +1,183 @@
+# 计算与同步方案
+
+从 Overview.md 的公式及 TemplatePartition.md 的路径推导实际计算。参数契约统一引用 LaunchData.md，目标能力及约束引用 API.md。
+
+## 1. 执行入口与参数
+
+| 阶段参数 | 来源 | 形状、类型及维度关系 | 固定配置或运行数据 | 首次消费位置 |
+|---|---|---|---|---|
+| | | | | |
+
+说明各阶段任务范围与调用变体，并核对实际参数顺序。
+
+## 2. 阶段与数据所有权
+
+画真实算法的数据流，列出每阶段的输入、计算或搬运、输出及完成条件。协作执行时展开每个角色的工作范围、共享对象和汇合协议。
+
+| 阶段及角色 | 工作项与读写范围 | 独占或共享对象 | 前置条件 | 完成发布与汇合责任 |
+|---|---|---|---|---|
+| | | | | |
+
+多个生产者或消费者共同使用一个结果时，给完成计数或等价协议、汇合方以及发布最终结果的条件。
+
+## 3. 坐标与边界
+
+写任务、工作项及局部坐标到每个输入输出逻辑和物理地址的公式，包含基址、步长及元素单位。展平或间接寻址时保留重建地址所需的信息。
+
+证明输出覆盖、所有权、有效范围与容量安全。任务编号、内部工作项编号和缓冲槽代次分别定义。
+
+## 4. 资源初始化与状态归属
+
+| 对象或状态 | 物理形状、类型及份数 | 所属任务或角色 | 初始化值与作用域 | 重置触发点 | 最后读取与复用条件 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+作用域按实际需要区分每次调用、执行单元、输出任务及内部工作项。累加前说明旧值从何而来；状态跨工作项保留时证明中途不会被其他阶段覆盖。资源量统一计入 LaunchData.md。
+
+## 5. 输入读取与数据重排
+
+给物理地址、步长、广播映射、有效范围、填充值及读完成条件。重排明确两侧布局、容量、元素偏移和消费时点。
+
+分块矩阵或向量操作按实际采用的粒度展开装载、物理格式、完整访问宽度及尾部处理。
+
+## 6. 有序计算链
+
+逐步实现数学公式，给输入输出、中间精度、转换及特殊边界；相关类型与舍入规则引用 InferShapeDtype.md。
+
+| 顺序 | 对应数学步骤 | 输入到输出 | 状态版本及精度 | 执行角色 | 完成与边界条件 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+递推或分块累加给旧状态、当前增量、新状态的位置与操作顺序，分别展开首次、后续及跳过工作项。矩阵分块结果拼接时给目的偏移与初始化范围。
+
+关键步骤给算法、规模相关工作量、临时存储及并行条件，关联 TemplatePartition.md 的选取依据。
+
+### 6.1 阶段成本与瓶颈
+
+按 references/stage-cost-model.md 定义公共成本模型，分支代入实际配置。计算量和搬运量由算法及物理数据流推导，时间估算注明设备参数与来源。
+
+| 阶段及执行资源 | 调用次数与作用域 | 每次计算量 | 各层搬运字节、重排与重复次数 | 时间组成及依据 | 串行依赖或争用 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+给各资源的累计占用、关键依赖及预计瓶颈。流水路径分析稳态推进间隔、填充和排空；任务划分分析最慢执行单元的负载。候选比较引用 TemplatePartition.md，观测与判定引用 Validation.md。
+
+## 7. 输出写回与完成
+
+逐输出给有效地址、尾部范围、别名读写次序、局部结果的最终合并及可见时点。共享写入给独占或受控合并依据。
+
+## 8. 流水与同步（按需）
+
+采用协作、异步推进或缓冲复用时，按 references/pipeline-design.md 推导实际机制。多个工作项交错推进时展开时序表与 warmup/steady/drain；顺序路径给阶段次序与实际复用条件。阶段数量、资源类型、状态及队列结构由当前算法确定。
+
+### 8.1 任务粒度与执行资源
+
+定义完整任务、阶段工作项和槽代次。列各角色的分工、共用资源上的发射顺序，以及状态的推进依赖。
+
+给各阶段所需的信息及取得方式。延迟消费时说明工作项描述及传递关系，包括实际需要的输出归属、有效范围、边界和状态标识。存在任务内递推时，首次、后续和末次以所属任务的有效范围判断。
+
+### 8.2 带索引的时序
+
+展开覆盖预填、实际槽复用及排空的小例子，每个阶段带具体任务或工作项索引。调度步表示依赖与预期重叠，实际耗时由证据或测量确定。
+
+| 调度步 | 各执行资源上的阶段与工作项 | 前置完成条件 | 读写对象及槽代次 | 发布与释放 |
+|---|---|---|---|---|
+| | | | | |
+
+给与表格对应的算法伪代码：warmup 的初始状态与实际预填量、steady 的等待和游标推进、drain 的剩余消费及最终释放。
+
+按本方案的实际阶段数及资源排布填写阶段索引、必要描述和发布/释放。说明各工作项如何推进、排空或重置发生在哪些边界，以及短任务的实际调度步；具体排布参考已确认适用的范式资料。
+
+### 8.3 生命周期与完成协议
+
+| 对象或队列 | 工作项到槽号及代次 | 写完成与可见条件 | 读者及最后读完成 | 允许复用条件 | 最大在途份数 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+每条同步边写生产者、消费者、作用域、初始及期望状态、发布和等待位置。槽选择、数据完成、可见性和复用分别定义；共享存储中的同步状态给布局与并发访问协议。
+
+对实际存在的中间结果队列、共享输入副本或累计状态分别计算最大在途份数，槽号映射与代次对应到各自的任务或工作项序号。累计状态存续到最终更新及输出所需的最后读取完成。
+
+### 8.4 边界与排布选择
+
+按实际机制覆盖任务少于预填量、空工作项、尾部、停止生产及错误后的消费或终止。每个等待都有可到达的发布方。
+
+存在不同可行排布时比较关键依赖、搬运量、在途状态及资源占用；深度与预填量由时序和容量共同确定，收益区分估算与实测。
+
+结合 §6.1 分析实际存在的资源争用、状态依赖及流水开销，给选择条件及验证观察。
+
+## 9. 分支实例化
+
+公共公式与阶段留在本文，各分支填写真实配置、坐标、资源及操作链。共同排布引用公共定义，差异同步更新参数、预算与验证。
+
+## 参考示例：单路径流式计算
+
+以下保留从 `flash_attn.py` 的阶段对象与 `flash_kda.py` 的任务循环抽取的接口示例，适用于一维 ND、单位步长、同形输出的路径。分块大小、类型及深度来自设计；`formula_step` 是需要展开的数学步骤占位，包含所需状态初始化与更新。工作区和累计对象按算法需要使用。
+
+实际使用时，依据目标版本的 DSL 源码或官方资料核对选槽、切片与视图语义；目标版本变化时重新核对相应条件。
+
+```python
+@kernel
+class OperatorKernel:
+    def __init__(self, tile_elems, input_dtype, output_dtype,
+                 accumulator_dtype, pipeline_depth):
+        self.tile_elems = tile_elems
+        self.input_ch = Channel(
+            MemLoc.UB, shape=(tile_elems,), dtype=input_dtype, depth=pipeline_depth
+        )
+        self.output_ch = Channel(
+            MemLoc.UB, shape=(tile_elems,), dtype=output_dtype, depth=pipeline_depth
+        )
+        self.acc = None
+        if accumulator_dtype is not None:
+            self.acc = Buffer(MemLoc.UB, (tile_elems,), accumulator_dtype)
+
+    @jit
+    def copy_in(self, gm_input, tile_id, valid):
+        # coord 是 tile 编号；元素起点为 tile_id * tile_elems。
+        gm_tile = tile_slice(gm_input, (self.tile_elems,), (tile_id,))
+        local = reinterpret(self.input_ch.produce(), shape=(valid,), stride=(1,))
+        mem_copy(local, gm_tile)
+
+    @jit
+    def compute(self, tile_id, valid, attr, workspace):
+        source = reinterpret(self.input_ch.consume(), shape=(valid,), stride=(1,))
+        target = reinterpret(self.output_ch.produce(), shape=(valid,), stride=(1,))
+        # 抽象数学步骤：先按状态作用域初始化，再计算有效元素。
+        formula_step(target, source, self.acc, workspace, tile_id, valid, attr)
+
+    @jit
+    def copy_out(self, gm_output, tile_id, valid):
+        gm_tile = tile_slice(gm_output, (self.tile_elems,), (tile_id,))
+        local = reinterpret(self.output_ch.consume(), shape=(valid,), stride=(1,))
+        mem_copy(gm_tile, local)
+
+    def __call__(self, gm_input: Tensor, gm_output: Tensor,
+                 workspace: Tensor, attr: int):
+        n = gm_input.shape[0]
+        block = get_block_idx()
+        blocks = get_block_num()
+        total_tiles = (n + self.tile_elems - 1) // self.tile_elems
+        for tile_id in range(block, total_tiles, blocks):
+            start = tile_id * self.tile_elems
+            valid = min(self.tile_elems, n - start)
+            self.copy_in(gm_input, tile_id, valid)
+            self.compute(tile_id, valid, attr, workspace)
+            self.copy_out(gm_output, tile_id, valid)
+```
+
+示例的槽选择位于计算区外，尾块通过保留原分配的有效视图读写。`tile_slice` 使用 tile 坐标，`reinterpret` 引用原分配与存储身份；实际访问始终落在已分配范围内。Channel 的选槽操作只推进独立游标，数据完成与复用由真实访问及同步机制保证。`formula_step` 展开后，按目标版本验证完整计算链及尾部行为。
+
+选择多阶段流水时用 §8 的实际角色调度替换上例顺序循环；给出任务索引与同步位置，并关联依赖编译器调度的机制证据。
+
+## 参考示例：多阶段或跨核路径
+
+`flash_kda.py` 在阶段间使用 workspace 与同步，`flash_attn.py` 也有分阶段计算和部分结果归并。需要时给出**实际**阶段及全局可见性证明：
+
+```text
+阶段 A: block 范围 A → 写 workspace[每个任务的唯一槽]
+边界: 所有生产者完成 → 设备可见性/屏障或单独 Launch
+阶段 B: block 范围 B → 读已初始化槽 → 归并 → 写最终输出
+```
+
+同一执行阶段内使用跨单元屏障时，核对参与者可同时驻留、完成通知与等待配对、状态命名空间及可见性；采用分阶段启动时给阶段边界。`channel_rewind` 示例的使用前提是相关槽无在途数据、所有参与者已经完成前一阶段。