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

package/assets/ops-direct-invoke/skills/cann-env-setup/evals/evals.json

@@ -0,0 +1,144 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "检查NPU驱动安装命令",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我有一台昇腾服务器，想检查NPU驱动是否已安装，应该用什么命令？",
+      "expected_output": "回复应说明使用 npu-smi info 命令检查驱动，并解释如何根据命令输出判断驱动是否已安装",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "配置环境变量永久生效",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我已经用离线安装包安装完CANN Toolkit和Ops，现在需要配置环境变量使其永久生效，应该怎么做？",
+      "expected_output": "回复应说明如何配置环境变量实现永久生效：通过 source set_env.sh 命令并将其写入 ~/.bashrc 文件",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "验证安装是否成功",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "CANN安装完成后，如何验证安装是否成功？",
+      "expected_output": "回复应提供至少一种验证 CANN 安装是否成功的方法",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 4,
+      "title": "离线安装顺序",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我需要安装CANN，但服务器没有网络，只有离线安装包Ascend-cann-toolkit_8.0.RC1_linux-aarch64.run和Ascend-cann-910b-ops_8.0.RC1_linux-aarch64.run。请问安装顺序是什么？",
+      "expected_output": "回复应明确说明安装顺序：先安装 Toolkit 包，再安装 Ops 包",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 5,
+      "title": "Conda在线安装CANN",
+      "config": {
+        "max_tokens": 120000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 140000,
+          "glm-5": 130000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我想用conda方式在线安装CANN，需要Python 3.10环境，具体步骤是什么？",
+      "expected_output": "回复应说明 conda 安装 CANN 的完整步骤：创建 conda 环境、添加昇腾 conda 源、使用 conda install 安装 cann-toolkit 和 ops 包",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 6,
+      "title": "安装前依赖检查",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "安装CANN之前需要检查哪些依赖？",
+      "expected_output": "回复应说明安装 CANN 前需要检查的依赖项，至少包括 Python 和 pip 是否已安装",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 7,
+      "title": "正向看护-多skill环境下正确触发目标skill",
+      "config": {
+        "max_tokens": 120000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 140000,
+          "glm-5": 130000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "distractor_skills": [
+          "npu-arch",
+          "ascendc-docs-search",
+          "ascendc-runtime-debug"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "我有一台昇腾服务器，需要做一遍CANN环境配置检查，确认驱动是否已安装、环境是否就绪，标准的排查流程是怎样的？",
+      "expected_output": "回复应说明使用 npu-smi info 命令检查驱动，并解释如何根据命令输出判断驱动是否已安装，给出完整的排查流程。即使在多个 skill 同时可用的环境下，也应正确识别并激活 cann-env-setup skill 而不是干扰 skill。",
+      "files": [],
+      "expectations": []
+    }
+  ],
+  "skill_name": "cann-env-setup"
+}

package/assets/ops-direct-invoke/skills/cann-env-setup/references/env_dependence.md

@@ -0,0 +1,77 @@
+# 环境依赖安装指南
+
+本文档提供 CANN 安装所需的必需软件安装命令。
+
+## 必需软件列表
+
+CANN 安装需要以下必需软件：
+- Python 3
+- pip
+
+## 安装命令
+
+### Ubuntu类系统
+
+```bash
+# 检查并安装 Python
+if ! command -v python3 &> /dev/null; then
+    apt-get update
+    apt-get install -y python3
+fi
+
+# 检查并安装 pip
+if ! command -v pip3 &> /dev/null; then
+    apt-get update
+    apt-get install -y python3-pip
+fi
+```
+
+### CentOS类系统
+
+```bash
+# 检查并安装Python
+if ! command -v python3 &> /dev/null; then
+    yum install -y python3
+fi
+
+# 检查并安装pip
+if ! command -v pip3 &> /dev/null; then
+    yum install -y python3-pip
+fi
+```
+## 验证安装
+
+安装完成后，使用以下命令验证软件是否安装成功：
+
+```bash
+# 检查Python
+python3 --version || python --version
+
+# 检查pip
+pip3 --version || pip --version
+```
+
+## 注意事项
+
+1. **Python版本要求**：CANN 支持 Python 3.7.x - 3.11.4
+2. **权限要求**：安装软件可能需要root权限或sudo权限
+3. **网络要求**：确保系统可以访问软件源
+4. **依赖关系**：某些软件可能需要额外的依赖包，安装过程中会自动处理
+
+## 常见问题
+
+### 1. 软件源无法访问
+- 检查网络连接
+- 配置国内镜像源（如华为云开源镜像站 https://mirrors.huaweicloud.com/ 、阿里云开源镜像站 https://developer.aliyun.com/mirror/ ，清华大学开源镜像站 https://mirrors.tuna.tsinghua.edu.cn/ 等）
+
+### 2. 权限不足
+- 使用 sudo 命令
+- 或切换到 root 用户
+
+### 3. 软件版本过旧
+- 某些系统默认软件源中的软件版本可能较旧
+- 可以考虑添加第三方源或手动编译安装
+
+## 参考链接
+
+- Python官网：https://www.python.org/

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: cannbot-dsl-best-practice
+description: "为 CANNBotDSL 算子提供整体实现、局部写法和生产代码最佳实践。当需要职责划分、Host 约束校验、Channel/同步/布局、注册与适配、编译启动、AICPU 负载均衡 metadata、VF 向量计算或命名建议时使用。"
+metadata:
+  category: implementation
+---
+
+# CANNBotDSL 实现最佳实践
+
+针对当前实现问题提供可应用的写法、选择依据和正反例。参考内容按主题组织，示例使用通用对象名，不要求某种算法、工程目录或特定实现存在。
+
+## 输入
+
+- 算子规格与设计资料：由调用方提供文件或目录，确定数学语义、执行路径和目标设备约束。
+- 当前实现代码与需要解决的组织或微模块问题。
+- 按需提供当前 Unit、测试用例和 Golden，用于说明本次能力边界与验证方法。
+
+## 输出
+
+针对当前问题给出代码组织或微模块写法建议，写明设计依据、适用前提、需核实的 API/设备事实，以及应执行的相关测试。调用方决定建议的记录位置和是否用于修改代码。
+
+## 参考选择
+
+| 问题或关键词 | 参考 | 解决的问题 |
+|---|---|---|
+| 整体结构、入口、Host、Kernel、@export、Native 导出、生命周期 | [整体实现](references/overall-implementation.md) | 公共骨架、导出与程序管理 |
+| 命名、常量、重复、注释、docstring、可读性 | [生产代码](references/production-code.md) | 清楚表达数据、单位与计算意图 |
+| Host 校验、非法输入、约束拦截、dtype、shape、参数组合 | [Host 约束校验](references/patterns/host-validation.md) | 在分配、编译和启动前拒绝非法元数据 |
+| Channel、Buffer、双缓冲、深度、slot | [Channel 与 Buffer](references/patterns/channel-buffer.md) | 存储选择、生命周期和复用 |
+| CrossCore、同步、事件、屏障、流水线交接 | [同步](references/patterns/synchronization.md) | 写入、可见、读取、复用顺序 |
+| VF、寄存器向量、mask、向量归约、cast、pack/unpack | [VF 向量计算](references/patterns/vf.md) | 向量操作链、尾部掩码、类型转换与累计状态 |
+| layout、stride、ND/NZ、视图、尾块、有效行 | [布局与尾块](references/patterns/layout-tail.md) | 物理跨度、格式转换与有效范围 |
+| workspace、临时存储、资源容量、别名、跨阶段复用 | [Workspace](references/patterns/workspace.md) | 分配、所有权、容量与生命周期 |
+| AICPU、负载均衡、metadata、调度协议、记录消费、任务成本、分核、分轮 | [AICPU 负载均衡 Metadata](references/patterns/aicpu-load-balance-metadata.md) | 设备侧调度、成本划分、记录生成与消费 |
+| Torch 注册、schema、Meta/Fake、dispatch、torch.ops | [Torch 注册](references/patterns/torch-registration.md) | 注册契约与真实计算一致 |
+| aclnn、参数映射、接口兼容、运行时适配 | [aclnn 适配](references/patterns/aclnn-adaptation.md) | 语义转换与接入职责 |
+| 编译、程序复用、特化、TensorSpec、launch | [编译与启动](references/patterns/compilation-launch.md) | 编译结果复用与本次输入绑定 |
+
+生成完整算子或设计其公共结构时，必须读取 [整体实现](references/overall-implementation.md)，落实其中的公共骨架与必备 `@export` 入口；生成或修改算子源码时读取 [生产代码](references/production-code.md)，应用代码规范与轻量检查规则。
+
+按问题含义选择内容；多个主题直接相关时组合读取。仅有命名问题时不需要读取全部计算参考，缓冲覆盖问题则同时涉及 Channel 与同步。
+
+## 应用原则
+
+1. 先确认当前问题和公开契约，再读取直接相关的参考。建议应指向具体代码位置，说明为什么适合这里。
+2. 示例只展示一个核心决策。将其中的维度、类型、资源上限换成当前契约；不要把示例选择推广成硬件默认值。
+3. `text` 代码块是结构伪码，其中的操作名不是 DSL API。落地前从当前源码、安装包或官方资料核实签名、同步语义和设备限制；不能把伪码当成已通过编译的代码。
+4. 每条建议附带能够暴露该问题的检查，例如跨步输入、尾块或缓冲复用。诊断信息和反例放在对应主题内，不要求独立探针或额外执行流程。
+5. 设计规定的设备计算和搬运由 DSL 完成；Host 处理元数据、分配、已确认的零拷贝视图和启动。独立 Golden 与诊断代码可使用 PyTorch，但不承担公开结果的补算。
+
+6. 区分设计强制承诺、允许选项与待定候选；在选项内调整实现，保留已交付行为并回归受影响能力。关键补证失败或改变强制执行域、通路、同步、复杂度等承诺时，向调用方记录失败证据与影响，不以数学等价替代设计完成，不自行修改冻结设计或调度回滚。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/overall-implementation.md

@@ -0,0 +1,226 @@
+# 整体实现：统一计算入口与必备导出入口
+
+每个生成算子保留有效的 `@export` 入口，使用 `cannbotdsl.aot.export`。运行与导出共用编译参数构造逻辑。公开 Python 入口负责输入校验和资源准备，`@host` 直接启动 `@kernel`。显式编译使用 `cannbotdsl.compile`，程序的创建、复用与释放由实际调用边界决定。
+
+## 公共结构
+
+```text
+公开 Python 入口 → 校验与资源准备 → @host → @kernel
+显式编译路径：cannbotdsl.compile(@host 入口, specs...) → ProviderCallable → 绑定本次参数并执行
+@export → 同一构建函数 → DSL Native 收集与发布
+```
+
+| 位置 | 职责 |
+|---|---|
+| `operator(...)` | 维护公开参数、错误行为、输出分配与返回结果 |
+| `build_program(...)` | 按需集中构造编译参数并返回编译程序 |
+| `Program.run(...)` / `@host` | 直接启动 Kernel |
+| `Kernel` / `@kernel` | 完成设备实现，按需用 `@jit` 组织计算片段 |
+| `export_operator()` / `@export` | 声明导出名称、枚举支持的编译变体 |
+
+这些职责可以放在一个文件中。workspace、metadata、状态、计算角色与阶段按算法需要添加；Torch 接入见 [Torch 注册](patterns/torch-registration.md)。
+
+## 公共结构伪码
+
+以下展示显式编译路径。中文步骤由当前算子填写；输入输出为同 shape 的二维连续 FP32 Tensor，行数动态、列数静态。支持集合与尺寸上界来自公开契约。
+
+```text
+import torch
+import cannbotdsl
+from cannbotdsl import Dim, Tensor, TensorSpec, dtypes, host, kernel
+from cannbotdsl.aot import export
+from cannbotdsl.ops.arch import get_block_idx, get_block_num
+
+@kernel
+class OperatorKernel:
+    def __init__(self, column_count):
+        self.column_count = column_count
+
+    def __call__(self, x: Tensor, output: Tensor, scale: float):
+        block_idx = get_block_idx()
+        block_num = get_block_num()
+        按需使用 block_idx 与 block_num 划分任务并完成设备实现
+
+class OperatorProgram:
+    def __init__(self, column_count):
+        self.column_count = column_count
+
+    @host
+    def run(self, x: Tensor, output: Tensor, scale: float, core_num: int):
+        op = OperatorKernel(self.column_count)
+        op[core_num](x, output, scale)
+
+def build_program(column_count: int, max_rows: int):
+    entry = OperatorProgram(column_count)
+    rows = Dim("rows", min=1, max=max_rows)
+    input_spec = TensorSpec((rows, column_count), dtypes.float32)
+    output_spec = TensorSpec((rows, column_count), dtypes.float32)
+    return cannbotdsl.compile(
+        entry.run, input_spec, output_spec,
+        dtypes.float32,  # scale
+        dtypes.int64,    # core_num
+    )
+
+def operator(x, scale):
+    校验输入布局、设备、scale 和公开支持范围
+    row_count, column_count = x.shape
+    core_num = _device_block_num(x)
+    output = torch.empty(x.shape, dtype=x.dtype, device=x.device)
+    with build_program(column_count, MAX_ROWS) as program:
+        program(x, output, float(scale), core_num)
+    return output
+
+@export("operator_name")
+def export_operator():
+    for column_count in SUPPORTED_COLUMN_COUNTS:
+        with build_program(column_count, MAX_ROWS):
+            pass
+```
+
+`_device_block_num` 见 [编译与启动](patterns/compilation-launch.md)。Host 将 `core_num` 用于 launch，Kernel 按需通过 `get_block_num()` 读取实际数量。
+
+示例的单次调用拥有程序句柄，并在执行结束后释放。需要连续复用时，将程序的创建和释放放到整组调用之外，每次传入当前 Tensor 与标量。普通 `build_program` 函数本身不缓存句柄；DSL 编译产物缓存与程序句柄复用是两个层次，运行时句柄复用不能使导出回调跳过实际的编译请求。
+
+## 装饰器与调用边界
+
+- 普通 Python 可以直接调用 `@host`；其编译与调用由 DSL 管理。需要显式动态参数规格时，使用 `cannbotdsl.compile`，第一个参数为 `@host` 函数或绑定方法。
+- `@host` 不返回计算结果，输出由传入的 Tensor 承接，公开 Python 入口组织返回值。
+- Kernel launch 直接写在 `@host` 源码体中；不能通过普通 Python helper 或 `@jit` 间接发起 launch。
+- `@jit` 组织 DSL 内部辅助计算，可由 `@host`、`@kernel`、`@jit` 调用并继承执行域。
+
+## 编译契约与可读性
+
+- **参数具名且同序：** 像上例一样列出 `input_spec`、`output_spec`，为标量类型标明形参名；specs、`run` 形参和调用实参逐项对应。
+- **配置直接表达：** 构建函数显式接收影响编译的配置；不捕获本次 Tensor、workspace 或 stream。参数分类和连续参数分组见 [编译与启动](patterns/compilation-launch.md)。
+- **静态与动态分开：** `column_count` 在本例中有意静态化，`max_rows` 是支持上界；实际行数由 Tensor 绑定，`scale` 与 `core_num` 在调用时传给 Host 入口。不要将本次核数写成固定默认值或塞入编译配置。统一分类与核数选择规则见 [编译与启动](patterns/compilation-launch.md)。
+- **尺寸有来源：** 静态尺寸与动态上界来自支持范围，派生尺寸用公式表达。共享逻辑维度复用同一个 `Dim`；需要的 stride 和 storage format 如实声明。
+- **避免位置补丁：** 不使用 `specs[4] = float`，也不为此另建参数编号表。参数少时直接排列，参数多时仅按签名中的连续职责区间分组。
+
+## 程序与导出的生命周期
+
+显式编译返回的 `ProviderCallable` 由持有方管理，在最后一次使用结束后通过上下文管理器或 `close()` 释放；关闭后不能继续调用。并发和异步路径按实际接口确认最后使用完成，不能提前释放程序或 Tensor。临时资源见 [Workspace](patterns/workspace.md)。
+
+**检查：** 参数顺序一致；动态尺寸在声明范围内；重复调用绑定本次数据；程序与临时资源在最后使用前有效。没有显式持有程序的调用方无需增加独立清理入口。
+
+`@export("name")` 装饰同步、无参数函数，导入时仅标记入口。`cannbotdsl.aot.build(collectors=..., target=..., output=...)` 发现并执行回调，收集其中实际发生的编译请求；直接调用回调只编译，不发布 Native 目录。输出路径应为新的目标目录。
+
+导出回调使用同一构建函数重新发起编译请求，底层编译产物可命中缓存。DSL 收集器在编译期间保存产物副本；回调通过上下文管理器关闭自己取得的程序句柄，发布临时资源由构建接口管理。运行时已持有的程序继续由其调用方管理，不在导出回调中清理。
+
+**导出检查：** 冷缓存和热缓存后构建均覆盖声明的变体；运行与导出参数契约一致；通过 DSL 的 Native 构建和注册接口验证产物实际可用，不能只检查装饰器存在。
+
+## Kernel 实现参考路由
+
+Kernel 按执行角色分为 CV 融合、单 C 和单 V。各路线共用公开入口、编译与启动结构，设备侧分别组织任务、资源和阶段依赖。
+
+| 路线 | 执行角色 | 结构重点 |
+|---|---|---|
+| CV 融合 | C 与 V 协同 | 阶段交接、在途任务窗口、槽位复用与排空 |
+| 单 C | C 侧执行 | 任务分配、资源准备、C 阶段调用与输出 |
+| 单 V | V 侧执行 | 任务分配、资源准备、VF 阶段调用与输出 |
+
+C 指 Cube/AIC，V 指 Vector/AIV；单 C、单 V 表示核型。所需角色由实现需求确定，核数查询见 [编译与启动](patterns/compilation-launch.md)。
+
+以下为结构伪码，计算阶段统一使用占位步骤。`inputs/outputs` 表示实际签名中的具名输入与输出，任务记录表示索引与资源的逻辑关联；落地时按契约展开，不默认引入容器或固定记录协议。资源的形状、类型、布局与构造参数由实现定义。所用导入放在算子源码顶部。
+
+### CV 融合：preload=2 的在途任务窗口
+
+使用两个任务槽组织阶段交接。`preload=2` 表示最多两个已发起、尚未回收的任务，当前消费任务计入窗口。每个槽位持有该任务所需的上下文与交接资源，任务完成后才能复用。
+
+```text
+# 算子源码顶部
+from cannbotdsl import kernel
+from cannbotdsl.ops.arch import get_block_idx, get_block_num
+
+PRELOAD = 2
+
+@kernel
+class CubeVectorKernel:
+    def __init__(self, preload=PRELOAD):
+        self.preload = preload
+        准备 C 与 V 各自需要的资源
+        按 preload 准备任务上下文与交接槽位
+
+    def __call__(self, inputs, outputs):
+        block_idx = get_block_idx()
+        block_num = get_block_num()
+        tasks = 分配给当前逻辑 block 的任务
+        task_count = 本 block 的任务数
+
+        # 启动：填入存在的任务。
+        for sequence in range(min(self.preload, task_count)):
+            slot = sequence % self.preload
+            将 tasks[sequence] 的上下文绑定到 slot
+            提交该任务的生产阶段
+
+        for sequence in range(task_count):
+            slot = sequence % self.preload
+            在消费前建立该任务的数据就绪依赖
+            执行消费阶段并提交该任务的输出
+            确认该槽位的最后访问完成，允许复用
+
+            next_sequence = sequence + self.preload
+            if next_sequence < task_count:
+                将 tasks[next_sequence] 的上下文绑定到 slot
+                提交下一任务的生产阶段
+```
+
+启动阶段填入至多两个任务；稳定阶段每回收一个槽位就补入一个任务；新任务发完后继续消费剩余任务，完成排空。任务数为 0 或 1 时只处理实际存在的任务。
+
+生产与消费阶段按数据依赖分配给 C/V 角色。本例适用于可组织成一次生产与消费交接的任务；更长的阶段链应按资源的完整存活区间安排推进与回收。任务上下文和交接数据必须使用一致的槽位，地址仍被计算或搬运访问时不得覆盖。
+
+槽位容量、数据就绪和允许覆盖是不同约束。使用 Channel 时，`produce()/consume()` 只选择槽位，不代表同步已经完成。同步依据实际访问建立；主调度条件位于 VF 外。资源与同步写法见 [Channel](patterns/channel-buffer.md)、[同步](patterns/synchronization.md)。
+
+### 单 C：任务与计算阶段
+
+```text
+# 算子源码顶部
+from cannbotdsl import kernel
+from cannbotdsl.ops.arch import get_block_idx, get_block_num
+
+@kernel
+class CubeKernel:
+    def __init__(self):
+        按静态配置准备 C 侧所需资源
+
+    def __call__(self, inputs, outputs):
+        block_idx = get_block_idx()
+        block_num = get_block_num()
+        task_count = 根据输入元数据确定任务数
+        for task_id in range(block_idx, task_count, block_num):
+            绑定当前任务的输入、输出与临时资源
+            准备输入并建立必要的数据就绪依赖
+            执行 C 侧计算阶段
+            提交当前任务的输出
+            在资源复用前确认最后访问完成
+```
+
+示例采用按 block 步进分配任务；有其他调度约束时采用对应的任务映射。计算阶段的内部循环与指令由实现填写，资源准备和同步仅保留实际需要的部分。
+
+### 单 V：任务与 VF 阶段
+
+```text
+# 算子源码顶部
+from cannbotdsl import kernel, vf
+from cannbotdsl.ops.arch import get_block_idx, get_block_num
+
+@kernel
+class VectorKernel:
+    def __init__(self):
+        按静态配置准备 V 侧所需资源
+
+    def __call__(self, inputs, outputs):
+        block_idx = get_block_idx()
+        block_num = get_block_num()
+        task_count = 根据输入元数据确定任务数
+        for task_id in range(block_idx, task_count, block_num):
+            在 VF 外绑定当前任务的输入、输出与临时资源
+            准备输入并建立必要的数据就绪依赖
+            with vf(mode="simd"):
+                执行 V 侧计算阶段
+            建立计算到输出的必要依赖并提交输出
+            在资源复用前确认最后访问完成
+```
+
+VF 只承接设备计算，资源选择和任务调度位于 VF 外。条件执行与内存屏障规则见 [VF](patterns/vf.md)。
+
+**检查：** 任务完整覆盖且不重复；空任务不访问无效资源；CV 覆盖 0、1、2、3 个任务与槽位回绕；任务上下文与数据一致；所有在途访问结束后才回收资源。设备执行记录按 [生产代码](production-code.md) 检查。

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

@@ -0,0 +1,34 @@
+# aclnn 适配：先对齐参数语义，再接真实接口
+
+适配层把公开契约映射到目标 SDK 接口。函数、描述对象和资源释放约定必须来自目标版本的头文件或官方资料，不能根据命名习惯假定某个 `aclnn*` 接口已经存在。
+
+## 核心例子：长度与累计偏移不是同一种参数
+
+假设公开契约接收每段长度，目标契约接收带末尾哨兵的累计偏移。二者虽可能都是一维整数张量，含义不同：
+
+```text
+公开 lengths:        [2, 0, 3]
+目标 offsets:        [0, 2, 2, 5]
+关系：offsets[0] = 0
+      offsets[i + 1] = offsets[i] + lengths[i]
+      offsets 的元素数 = lengths 的元素数 + 1
+```
+
+目标接口确实需要这一转换时，显式确定它在哪执行、输出谁持有以及整数范围。设备上的长度不能在适配 helper 中默认搬回 Host；设计要求的设备转换应进入 DSL 计算路径。若两端接受同一种表示，直接映射即可。
+
+**反例：** 将 lengths 指针按参数位置直接转发为 offsets；把缺省 scale 从公开语义的自动推导改成 SDK 的固定值；交换两个 dtype 相同但含义不同的参数。
+
+## 执行结构：按已核实的 SDK 契约展开
+
+```text
+公开参数 → 明确的目标参数顺序、类型、布局和默认值
+张量描述 → 指向正确的存储、shape、stride，并保留所需所有权
+若接口要求 workspace 查询：检查返回状态，再按查询结果准备存储
+提交执行 → 传入本次 stream；检查提交状态
+按接口约定维护描述对象、执行对象与存储的生命周期
+返回公开契约要求的输出顺序与 alias 关系
+```
+
+此结构不假定每个接口都有两阶段调用。查询失败不得继续执行；零 workspace 按真实接口约定处理。异步提交成功不代表设备完成，释放与复用依据实际资源约定；不能机械销毁所有对象或永久保留所有对象。
+
+**检查：** 不等长度与零长度段、非默认可选参数、多输出顺序、查询与提交失败、连续异步调用。将适配引入的真实转换成本计入性能评估，零拷贝视图须有 stride 与存储依据。布局细节见 [布局与尾块](layout-tail.md)。

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/patterns/aicpu-load-balance-metadata.md

@@ -0,0 +1,116 @@
+# AICPU 负载均衡 Metadata：把不均匀任务变成可消费的调度记录
+
+适用于设备上的长度、偏移等值决定任务数、分轮或分核的算子。Host 准备有界存储，AICPU 读取这些值并生成任务记录，AICore 消费记录完成计算。静态且均匀的任务可直接划分，无需为了结构一致增加 AICPU。
+
+下列片段是独立的算法伪码；记录字段和成本模型由当前算子定义，不是一套固定 ABI。
+
+## AICPU 声明接口
+
+```text
+from cannbotdsl.aicpu import aicpu_kernel, GmIn, GmOut, I32
+
+class ScheduleArgs:
+    lengths: GmIn(I32)
+    records: GmOut(I32)
+    record_capacity: I32
+
+@aicpu_kernel
+def build_schedule(args: ScheduleArgs):
+    校验容量、生成记录，并按当前契约返回状态
+```
+
+使用不带括号的 `@aicpu_kernel`，参数注解必须可取得实际参数结构类型；上述字段也需要保留实际类型描述对象，不用未解析的字符串注解代替。Host 验证使用 `run_host(...)`，源码检查使用 `generate_sources(launch_mode="interface")`。设备构建接口见下文；其结果是 AICPU launcher，不是 `ProviderCallable`，按 launcher 自身接口管理启动与生命周期。
+
+## 构建与启动：字段、地址、stream 分别明确
+
+```text
+from cannbotdsl.aicpu.toolchain import compile_aicpu_kernel
+from cannbotdsl.aicpu import current_raw_stream
+
+compiled = compile_aicpu_kernel(
+    build_schedule, workdir=BUILD_DIRECTORY,
+    launch_mode="interface", npu_arch=TARGET_ARCH,
+)
+compiled.launch(
+    current_raw_stream(device_id),
+    lengths=lengths.data_ptr(),
+    records=records.data_ptr(),
+    record_capacity=records.numel(),
+)
+```
+
+这一路径需要目标 CANN 工具链。传入全部参数结构字段；GM 字段传设备地址，标量按声明的宽度校验。`.launch()` 的返回值表示包装层提交结果，不承载设备函数的业务状态；业务失败写入约定的输出状态字段，并由消费方处理。
+
+生成源码和 Host 解释检查不能替代目标设备编译验证。
+
+## 1. 分轮：用容量不等式选择本轮工作量
+
+假设每个活动序列还有 `remaining[i]` 个 chunk，一个 chunk 占 `units_per_chunk` 个资源单位，本轮容量为 `slots`。
+
+```text
+usage(g) = sum(min(remaining[i], g) * units_per_chunk)
+
+while 仍有 remaining[i] > 0:
+    如果 usage(1) > slots：采用契约允许的分组策略，或报告容量不足
+    否则在 [1, max(remaining)] 找到满足 usage(g) <= slots 的最大 g
+    对每个活动序列 i：
+        记录 take[i] = min(remaining[i], g)
+        remaining[i] -= take[i]
+```
+
+在这一模型中 `usage` 单调，可二分查找。实现时先确认每轮至少能推进一个 chunk；不满足时不能继续寻找 `g=0`，否则可能死循环。不同资源成本需替换 usage 公式，不能套用相同常量。
+
+## 2. 分核：按估算成本划连续任务范围
+
+任务数相同不表示耗时相同。例如任务成本 `[8, 1, 1, 1, 1]`，两核按前 3 个和后 2 个分配，负载为 `10/2`；划为 `[0,1)` 与 `[1,5)`，负载为 `8/4`。
+
+下面的贪心方法每次靠近剩余平均成本，并给后续核至少留一个任务。假定成本非负、核数为正。
+
+```text
+active = min(task_count, core_count)
+start = 0; remaining_cost = sum(costs)
+所有核的范围初始化为空
+for core in [0, active):
+    remaining_cores = active - core
+    max_end = task_count - (remaining_cores - 1)
+    end = start + 1; segment_cost = costs[start]
+    if remaining_cores == 1:
+        end = task_count; segment_cost = remaining_cost
+    else:
+        while end < max_end:
+            before = abs(segment_cost * remaining_cores - remaining_cost)
+            after = abs((segment_cost + costs[end]) * remaining_cores - remaining_cost)
+            if after > before: break
+            segment_cost += costs[end]; end += 1
+    ranges[core] = [start, end)
+    remaining_cost -= segment_cost; start = end
+```
+
+这是可解释的启发式，不能宣称全局最优。成本模型应包括实际起步开销、迭代量和尾块差异，并用测量校准。若比较不同拆分候选，可先比较最大核成本，再比较总成本和任务数；保留完整获选记录，避免范围与任务表来自不同候选。
+
+**反例：** 仅按序列数量均分；估算成本忽略尾块；拆分后只更新任务数，未更新任务对应的输入区间与归并规则。
+
+## 3. 落记录：先计数，再检查容量，再写入
+
+以扁平记录为例：头部 `H` 个元素，`R+1` 个轮偏移，每轮 `F` 个字段，每个活动条目 `V` 个字段，共 `A` 个活动条目。
+
+```text
+第一遍：计算 R、A，以及生成期间所需 scratch 上限
+required_elements = H + (R + 1) + F * R + V * A
+检查乘加溢出、输出容量和 scratch 容量
+容量不足：写入调用方可识别的失败状态；不得消费不完整记录
+第二遍：用相同规则填写轮偏移、任务描述和分核范围
+记录有效长度与协议版本；全部字段有效后发布成功状态
+```
+
+状态区必须预先分配且所有失败路径都可写，不能在容量连头部都放不下时再向越界位置写错误。`H/F/V` 是当前记录协议定义的字段数。字节容量还要乘元素字节数并满足对齐要求。第一遍和第二遍必须使用相同输入、配置与舍入规则；输入值在两遍之间不得被并发修改。
+
+## 消费边界与检查
+
+- 记录中保存分核使用的 `core_count`；AICore 消费方通过 `get_block_num()` 取得实际启动数量，并在读取按核记录前确认两者一致。不一致时走约定的失败路径，不能静默返回未写输出。该数量指消费方的 AICore block 数。空任务范围不代表取消对应 block；核数变化须重算记录，见 [编译与启动](compilation-launch.md)。
+- 偏移单调且末尾等于有效条目数；所有核的范围在有效任务数内，完整覆盖且不重复。
+- 生产与消费放在能保证先后关系的同一 stream，或建立明确的跨 stream 依赖。最后写成功状态本身不是内存屏障。
+- 失败状态必须被实际消费路径处理，禁止继续算并返回未初始化结果。需要同步向 Host 报错时，明确状态读取和同步方式。
+- 缓存生成记录时，长度值变化可能改变全部调度；仅以指针或 shape 为键不够。Host 负责分配的容量问题见 [Workspace](workspace.md)。
+
+**检查：** 空任务、任务数小于核数、极端长短不均、容量恰好足够和差一个元素、零成本任务、相同 shape 但长度值改变。可记录任务数、每核估算成本与状态；诊断不再生成第二套调度记录。