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

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

@@ -0,0 +1,126 @@
+# 阶段参数与资源预算
+
+## 配置及来源
+
+| 字段 | 类型及单位 | 计算公式或候选集合 | 合法范围与校验 | 固定配置或运行参数 | 消费阶段 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+给出配置推导顺序：输入信息、候选算法及分块、资源预算、最终选择。按需描述辅助记录，字段都有生产与消费位置。
+
+## 阶段参数契约
+
+多阶段或多种调用变体分别列出完整有序参数表，并与 HostLaunch.md 的实际取值及 Kernel.md 的消费位置逐项对应。
+
+| 顺序 | 参数或对象 | 形状、类型及维度关系 | 布局、步长及容量 | 生产者与消费者 | 有效期及可选状态 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+定义跨对象维度等式、可变维度的上下界及来源、标量单位。逻辑布局转换后仍需解释的信息通过明确参数或可区分的契约传递。可选对象的缺省状态与真实最小对象保持可区分。
+
+选一个最小合法输入和一个维度或配置变化的输入，列出全部实际参数取值，核对维度关系、数量、顺序和消费条件。
+
+## 辅助记录与临时存储布局（按需）
+
+| 区域或记录 | 类型及单位 | 偏移、步长及容量公式 | 初始化或生产方 | 可见时点与读取检查 |
+|---|---|---|---|---|
+| | | | | |
+
+按实际使用的区域展开数据、辅助记录、状态及同步信息，总容量覆盖全部区域及对齐间隔。间接寻址或变长结构中的数据值在生成地址前检查安全范围。并发状态更新说明独占、原子或合并协议。
+
+## 物理资源与生命周期
+
+| 对象及内存池 | 物理形状、类型及份数 | 字节公式 | 分配范围与活跃区间 | 地址复用条件 | 容量及余量 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+分别核算实际物理分配与各阶段活跃峰值。跨池副本、格式填充、临时转换、常驻状态和同时在途版本各自计入；明确地址复用且生命周期不冲突时才共享空间。每个实际内存池及共享范围分别与目标容量比较。
+
+采用流水时，份数引用 Kernel.md §8 的生命周期；资源超限给配置调整或符合接口契约的另一条路径。
+
+## 边界调用契约
+
+| 条件 | 各输出分配及初值 | 需要的执行阶段 | 参数或资源变化 | 规格依据 |
+|---|---|---|---|---|
+| | | | | |
+
+逐输出推导边界调用。输出范围为空、操作范围为空、可选对象关闭等条件按实际语义展开，并与 HostLaunch.md 的调度及 Validation.md 的预期一致。
+
+## 参考示例：配置与资源计划
+
+以下保留先估算、后选择的参考骨架，来源于 `flash_attn.py` 的配置与资源职责拆分。示例假设一维 ND、单位步长、分配尺寸已满足对齐，输入输出使用相同深度。`algorithm_temporaries_bytes` 包括实际需要的累计状态和其他临时对象；字段、容量及配置边界由设计实例化。
+
+```python
+# 设计伪代码：填入真实字段、公式与容量证据后再实现。
+@dataclass(frozen=True)
+class TileConfig:
+    name: str
+    tile_elems: int
+    pipeline_depth: int
+
+@dataclass(frozen=True)
+class ResourcePlan:
+    config_name: str
+    ub_bytes: int
+    workspace_bytes: int
+
+def estimate_resources(config, input_meta):
+    elem_bytes = dtype_size(input_meta.dtype)  # 按真实 dtype 查表
+    input_buf = config.tile_elems * elem_bytes * config.pipeline_depth
+    output_buf = config.tile_elems * output_elem_bytes(input_meta) * config.pipeline_depth
+    temporaries = algorithm_temporaries_bytes(config, input_meta)
+    return ResourcePlan(
+        config.name,
+        ub_bytes=input_buf + output_buf + temporaries,
+        workspace_bytes=workspace_formula(config, input_meta),
+    )
+
+def select_config(input_meta, limits):
+    for config in candidate_configs(input_meta):
+        plan = estimate_resources(config, input_meta)
+        if plan.ub_bytes <= limits.usable_ub and plan.workspace_bytes <= limits.workspace:
+            return config, plan
+    raise UnsupportedConfiguration(input_meta)
+```
+
+把每个函数中的占位计算展开成上文表格的**逐项字节公式**。若有 L1/L0A/L0B/L0C，分别增加字段和容量不等式；按阶段活跃集算峰值，不把所有候选分支相加。选择结果应能在 `TemplatePartition.md` 找到唯一执行路径。
+
+## 参考示例：符号维度与参数绑定
+
+以下是独立的二维正尺寸规格示例，用共享符号表达输入输出维度相等、用独立符号表达输入行步长。它演示参数契约的绑定；`MatrixViewKernel` 是需另行定义的算法占位，与一维启动示例分别实例化。
+
+实际使用时，依据目标版本的 DSL 源码或官方资料核对维度与规格声明规则；变量上界由实际支持域给出。
+
+```python
+import cannbotdsl
+from cannbotdsl import Tensor, dtypes
+
+
+class MatrixViewProgram:
+    def __init__(self, tile_shape, block_dim):
+        self.tile_shape = tile_shape
+        self.block_dim = block_dim
+
+    @cannbotdsl.host
+    def run(self, x: Tensor, out: Tensor, attr: int):
+        op = MatrixViewKernel(self.tile_shape)  # 算法占位
+        op[self.block_dim](x, out, attr)
+
+
+# 形状、类型及确定上界由接口和资源契约给出。
+batch = cannbotdsl.Dim("B", min=1, max=MAX_BATCH)
+length = cannbotdsl.Dim("L", min=1, max=MAX_LENGTH)
+input_row_stride = cannbotdsl.Dim("X_ROW_STRIDE", min=1)
+input_spec = cannbotdsl.TensorSpec(
+    (batch, length), input_dtype, stride=(input_row_stride, 1)
+)
+output_spec = cannbotdsl.TensorSpec((batch, length), output_dtype)
+entry = MatrixViewProgram(tile_shape, block_dim)
+compiled = cannbotdsl.compile(
+    entry.run, input_spec, output_spec, dtypes.int64  # x、out、attr
+)
+```
+
+此例的二维输入采用行内连续布局；行步长与存储容量的合法关系仍由接口校验。可选状态、零尺寸或其他布局按阶段参数表另行表达。
+
+共享符号与实际形状的绑定需要逐对象核对；确定上界与支持域及资源预算一致。

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

@@ -0,0 +1,57 @@
+# 算子概览
+
+## 功能与语义
+
+说明输入到输出的映射、属性及可选输入对结果的作用。每个语义项关联 spec.yaml 中的依据。
+
+| 语义项 | 定义与索引域 | 规格依据 | 对计算及参考结果的影响 |
+|---|---|---|---|
+| | | | |
+
+## 数学定义
+
+逐输出给出数学公式，定义变量、维度、索引映射、广播或规约轴与边界取值。公式应足以独立推导参考结果。
+
+```latex
+% 输出及索引域、输入映射、属性作用、中间量更新、最终写回
+```
+
+有状态算法分别给初值、更新式及最终输出式；存在依赖顺序时写明其数学原因。采用等价变换或近似时，给出成立条件及误差来源。
+
+| 公式中的量 | 输入来源或初值 | 更新式及顺序 | 最终用途 | 对应计算阶段 |
+|---|---|---|---|---|
+| | | | | |
+
+## 边界与数值契约
+
+按规格列出会影响结果的边界，例如有效输出范围、空操作域、特殊数值、溢出及确定性。区分输出范围为空与计算范围为空，逐输出定义结果或错误。
+
+| 条件 | 输出形状与取值或错误 | 数学依据 | 参考结果判定 |
+|---|---|---|---|
+| | | | |
+
+中间计算与转换精度在 InferShapeDtype.md 定义，比较规则在 Validation.md 定义；本文说明这些规则与数学语义的关系。
+
+## 设计不变量
+
+列出各路径共同遵守的条件，并给验证位置。涉及共享写入时说明独占或合并规则；涉及有效范围时说明无效元素如何排除；涉及别名时说明覆盖前的读取条件。
+
+| 不变量 | 适用路径 | 保证方式 | 计算或验证位置 |
+|---|---|---|---|
+| | | | |
+
+## 参考示例：公式到阶段的映射
+
+按本算子选择元素级、规约或递推等形式，把 `...` 换成明确的索引和边界。`flash_attn.py` 的在线状态更新、`flash_kda.py` 的阶段状态传递说明：有状态算法必须写**初值、更新式、最终写回式**，不能只列最终结果。
+
+```latex
+% 元素级：y[i] = f(x_0[map_0(i)], x_1[map_1(i)], attr)
+% 规约：s_0 = identity; s_{k+1} = update(s_k, x[k]); y = finalize(s_K)
+% 递推：state_{t+1} = F(state_t, input_t); output_t = G(state_{t+1})
+```
+
+| 公式中的量 | 初始化/来源 | 更新阶段 | 存放位置（GM/本地/Workspace） | Golden 中的独立计算 |
+|---|---|---|---|---|
+| | | | | |
+
+需要数值稳定变换时，给原式与变换式的关系及误差来源；例如分块累计、缩放或归一化改变运算顺序时，在验证中单列阈值和确定性要求。

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

@@ -0,0 +1,69 @@
+# 算法配置与执行路径
+
+## 配置维度与算法选择
+
+| 选择量 | 来源与合法域 | 固定配置或运行参数 | 影响的算法、阶段或资源 | 选择依据 |
+|---|---|---|---|---|
+| | | | | |
+
+候选算法说明适用规模、工作量、数据搬运、临时存储与并行条件。关键步骤展开为明确算法，估计值与实测值注明来源。配置值变化只有改变实际算法、数据流或同步结构时才形成新路径。
+
+## 候选成本与选择依据
+
+引用 Kernel.md §6.1 的公共阶段成本及 LaunchData.md 的物理资源公式，代入代表规模比较实际可行候选，按实际执行机制填写相关成本。
+
+| 候选及输入范围 | 阶段调用次数与复用范围 | 计算量与各层搬运量 | 资源负载及串行瓶颈 | 填充、排空与负载差异 | 物理资源及可行性 | 选择条件、证据或待测项 |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+比较候选改变了哪些调用、重复搬运、资源占用或关键依赖。时间结论采用适用的估算或实测；任务数较少、较多及工作量不均的场景分别说明。只有一个可行方案时给其依据与预计瓶颈。完整方法见 references/stage-cost-model.md。
+
+## 执行路径
+
+| 分支 ID | 必要且充分的进入条件 | 配置范围 | 算法、数据流或同步差异 | 分支文件 |
+|---|---|---|---|---|
+| B0 | | | | branches/DESIGN-BRANCH-B0.md |
+
+每条真实路径有一份分支设计。公共计算链保持统一定义，分支实例化公式与差异。
+
+## 判定顺序与覆盖
+
+用决策图或算法伪代码写出合法性检查、配置筛选、路径选择及执行顺序。条件依赖数据值时，明确其生产和判定阶段。
+
+```text
+输入合法性检查 → 配置候选过滤 → 资源校验 → 路径选择 → 启动
+```
+
+核对全部支持域的路径覆盖与唯一选择。条件重叠时写出优先级及最终选择规则；候选都不满足时给符合接口契约的处置。路径合并或拆分给算法、资源及同步依据。
+
+## 具体场景矩阵
+
+| Case ID | 完整输入形状与类型 | 布局、属性及可选状态 | 判定条件 | 配置与预期路径或错误 |
+|---|---|---|---|---|
+| | | | | |
+
+每个场景填写足以确定路径的实际取值，覆盖支持组合与路径交界。逐项核对入口合法性和选择条件，再关联 Validation.md 的断言。
+
+## 参考示例：路径选择
+
+以下保留参考实现中的配置筛选与路径选择骨架，展示两条不同数据流的选择方式；返回名称是待实例化的占位。配置选择与执行路径分别定义，数据值条件在所需信息已可用的阶段判定。
+
+```python
+def choose_path(meta, limits):
+    validate_supported_domain(meta)                 # Interface 的合法域
+    candidates = candidate_configs(meta)            # 不等于分支数
+    for config in candidates:
+        plan = estimate_resources(config, meta)     # LaunchData 的公式
+        if not fits_all_used_pools(plan, limits):
+            continue
+        if requires_different_dataflow(config, meta):
+            return "B_special", config, plan
+        return "B_main", config, plan
+    raise UnsupportedConfiguration(meta)
+```
+
+在正式设计中用真实条件替换两个分支名，写出判定顺序和互斥证明。`requires_different_dataflow` 应描述实质不同的阶段、搬运或同步；只变 tile 尺寸时返回同一分支的不同配置。
+
+| 边界条件 | 候选配置 | 资源筛选结果 | 唯一路径 | 不拆分/拆分的依据 |
+|---|---|---|---|---|
+| | | | | |

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

@@ -0,0 +1,80 @@
+# 验证方案
+
+定义整个算子的验收口径。各路径特有的分块、同步及资源边界用例在分支文件展开，本文汇总引用。
+
+## 独立参考结果
+
+根据 spec.yaml 与 Overview.md 的数学语义定义参考结果，说明计算精度、转换、边界及错误规则。参考计算从公开输入独立完成，与被测路径的内部状态和未证实近似解耦。
+
+| 输出或场景 | 参考公式及步骤 | 类型与舍入 | 边界或错误判定 | 语义依据 |
+|---|---|---|---|---|
+| | | | | |
+
+## 用例矩阵
+
+| Case ID | 完整形状与类型 | 布局、属性及可选状态 | 分支与配置 | 预期输出或错误 | 断言与依据 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+覆盖支持组合、可达路径和实际存在的边界。每个路径用例先检查输入合法性，再验证路由条件。动态形状或值依赖输出选能改变维度关系与结果范围的输入。
+
+## 比较规则与确定性
+
+| 输出、类型或场景 | 精确比较或误差度量 | 判定公式及阈值 | 转换与特殊值规则 | 重复运行要求 | 规格依据 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+整数、布尔及索引按相应精确性要求判断；浮点给逐点或聚合误差的实际公式及分母处理。多输出分别定义判定，阈值和确定性来自规格或有依据的目标。
+
+## 区分错误的输入
+
+| 关键义务 | 具体错误变体 | 区分输入或观察 | 预期差异 | 对应用例与证据 |
+|---|---|---|---|---|
+| | | | | |
+
+根据数学与结构选择能暴露遗漏、错序、错址、重复处理或错误复用的模式。有状态算法让后续有效工作项改变状态；共享或索引算法让各来源产生可区分的值。
+
+## 结构、资源与同步
+
+按实际采用的机制验证输出覆盖、写入所有权、初始化、容量、完成通知和资源复用。数值比较、执行结构、数据传递及阶段重叠分别选择证据，并说明适用范围。
+
+流水的槽代次观察关联实际读写对象；性能或重叠用执行时间线和测量数据支撑。缺少证据的部分明确采集方法和阶段。
+
+## 性能目标与测量
+
+| Case ID 及规模 | 路径与配置 | 目标值及单位 | 来源及适用条件 | 测量与统计口径 | 估算或实测 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+目标采用适用的基线或设备评估，说明输入、环境、重复及同步条件。缺少可靠目标时给测量计划。代表规模覆盖算法工作量增长、搬运及关键等待；候选方案按一致条件比较。
+
+引用 Kernel.md §6.1 的成本模型，明确哪些观察能确认或推翻预计瓶颈。
+
+| 成本或瓶颈假设 | 区分输入及候选 | 阶段计时、搬运、等待或资源观察 | 预计变化及判定依据 | 采集阶段与证据状态 |
+|---|---|---|---|---|
+| | | | | |
+
+按实际机制选择：短任务观察填充和排空，较长任务观察推进间隔与共用资源负载，工作量变化观察执行单元之间的负载差异，重复读取或重排观察实际次数与字节量。预测和观测不符时关联具体阶段及公式修正，记录数值与同步仍成立的范围。
+
+## 参考示例：验证构造
+
+从 `Interface.md` 的合法域和 `TemplatePartition.md` 的路由条件枚举 Case，不直接从实现内部生成期望值。以下伪代码只表达用例组织；设备调用、误差比较和异常断言按实际测试框架实现。
+
+```python
+for dtype_combo in spec_supported_combinations:
+    for path in reachable_paths(dtype_combo):
+        case = choose_legal_public_input_that_hits(path, dtype_combo)
+        validate_case_against_interface_and_path(case, path)
+        expected = independent_cpu_golden(case)
+        actual = public_op_on_device(case)
+        assert_shape_dtype_layout(actual, expected, case)
+        assert_result(actual, expected, comparison_rule_for(case))  # 精确或误差判定
+        assert_path_evidence(path, case)  # 结构 trace/探针，不能由 Golden 自证
+
+for invalid_case in interface_error_cases:
+    assert_public_error(invalid_case, expected_error(invalid_case))
+```
+
+对 pipeline 和 workspace 另外设计“最小块、尾块、最大块、连续两次调用、配置切换”用例，检查旧数据复用、未初始化读取和同步遗漏。多次 Launch 或动态 shape 需要至少两个不同尺寸且不同任务分配的 Case，确保不是偶然通过。
+
+实际流水还覆盖少于预取量、超过槽深度触发复用、空工作项夹在非空工作项之间、多消费者最后读完成及设备值错误后的收尾。每项指定能够区分顺序执行、错误复用或缺失完成通知的证据；尚待采集的设备证据写明补证阶段。

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cannbot-dsl-test-generator
+description: "当需要设计、补充或校验 CANNBotDSL 算子测试，或生成独立 CPU Golden 与测试入口时使用；根据调用方提供的规格、设计及实现单元检验义务生成黑盒、白盒和 TDD 用例及校验结果。"
+metadata:
+  category: testing
+---
+
+# CANNBotDSL 测试生成
+
+## 输入
+
+- 算子规格文件，确定公开接口、数学语义、边界和容差。
+- 调用方提供的一份设计 Markdown 文档，供 Golden 和白盒用例引用；文件名与所在目录由调用方决定。
+- 调用方提供的 `U*.yaml` 所在目录，供 TDD 用例读取实现边界和检验义务；所需字段见 [TDD 输入与证据契约](references/evidence.md)。
+- 可选：已有的测试目录及 `testcase.csv`。各模块在同一 CSV 中维护所属分组。
+
+## 输出
+
+在调用方指定的 `TEST_DIR/` 下维护 `testcase.csv`、`<op>_golden.py`、`test_<op>.py`、固定入口辅助模块和 `testcase_output/{blackbox,whitebox,tdd}/`。算子名来自 `spec.op.name`。脚本校验本 Skill 产出的用例与 Golden，具体用例由测试设计者确定。
+
+各脚本通过 `--spec SPEC`、`--design DESIGN`、`--units-dir UNITS`、`--test-dir TEST_DIR` 接收当前步骤所需的输入和输出位置。
+
+## 按任务读取与分批写入
+
+只执行调用方要求的模块。黑盒设计仅需 spec、[用例契约](references/cases.md) 和 `build_blackbox_cases.py --inventory`；不预读 DESIGN、Unit、Golden 文档或 runner 源码。正常使用脚本入口，只有实际报错或契约无法解释时，才读相关函数及直接依赖，避免先通读整个 scripts 目录。
+
+完整测试生成按以下产物顺序推进；已有有效产物先检查并复用：
+
+1. 黑盒：读取 inventory 后，在正式 `TEST_DIR/testcase.csv` 创建固定表头并写入已确认的 L0 核心用例，再分批补 L1/L2；已有 CSV 只更新 blackbox 行，保留其他分组。
+2. Golden 与入口：只读 spec 和设计中相关数学/接口章节，保存完整可解析的 Golden，运行 `prepare_golden.py` 校验并安装固定入口，再进行 CPU 数值复核。完成这一步后再展开白盒和全部 Unit。
+3. 白盒：按设计索引逐个读取真实执行分支，完成一批即写入 whitebox 行；无需预读 Unit。
+4. TDD：按 Unit 依赖顺序逐份读取 YAML，逐批保存相应义务的 tdd 行；最后执行全量义务、依赖与关联检查。
+
+每批写入后先检查 CSV/YAML/Python 能否解析及本批字段、ID/引用是否正确；当前脚本的完整覆盖检查留到对应模块补齐后执行。部分内容缺失时记录待补项，不用 excluded 或放宽校验掩盖未完成。中断恢复先读已有产物和缺项，不重建已确认内容。分批保存不降低最终验收要求，也不增加独立计划文件或中间格式。
+
+## CSV 契约
+
+使用 [用例契约](references/cases.md) 中的固定列。每行 `sheet` 为 `blackbox`、`whitebox` 或 `tdd`，`source` 与 `sheet` 相同，`status` 为 `active` 或 `excluded`。可执行行必须提供 `inputs_json`；排除行不执行，必须提供 `exclude_reason`。黑盒的 `design_ref` 为 spec 路径列表，`condition` 为 L0/L1/L2；白盒的 `design_ref` 为设计文件中的实际条目，`condition` 为分支条件；TDD 使用 `unit_id`、`obligation_ids` 和可选 `branch_ids` 追溯原生 Unit。固定测试入口只执行 active 行。
+
+## 黑盒
+
+先运行 `scripts/build_blackbox_cases.py --spec SPEC --test-dir TEST_DIR --inventory`，从标准输出审查 spec 因子和必需路径。测试设计者直接编写 CSV 的 blackbox 行，覆盖 L0 核心、L1 组合/边界/极值以及规格声明的 L2 异常；无法执行的必需路径写 excluded 行及理由。运行 `scripts/build_blackbox_cases.py --spec SPEC --test-dir TEST_DIR` 校验输入配方、错误语义、spec 路径和覆盖；`--coverage` 可重新打印报告，不落盘。生成阶段不执行目标算子。
+
+## 独立 Golden 与固定入口
+
+依据 spec 和 DESIGN 直接编写 `TEST_DIR/<op>_golden.py`。其中包含 `DESIGN_REFS`、与 spec 参数一致的 `<op>_golden`、公开接口元数据；CPU 实现不得导入被测算子或设备库。可参考 [Golden 契约](references/golden.md)。人工审查数值路径后运行 `scripts/prepare_golden.py --spec SPEC --design DESIGN --test-dir TEST_DIR` 校验最终 Golden，并安装固定 `test_<op>.py` 与三个结果目录。静态校验不能证明数值等价，须用 CPU 样例和边界复核。
+
+## 白盒
+
+依据所提供设计文件中的算法、执行路径和验证矩阵直接编写 CSV 的 whitebox 行。每个目标对应可执行分支或带理由的 excluded 行；分支只使用 spec 公开输入。运行 `scripts/build_whitebox_cases.py --spec SPEC --design DESIGN --test-dir TEST_DIR` 核对 DESIGN 引用、输入配方和分支 ID，不依赖 Unit 或 Golden。
+
+## 实现单元 TDD
+
+依据 `UNITS/U*.yaml` 的 `verification_obligations` 逐项编写 CSV 的 tdd 行，明确公开输入、预期结果、断言和可选白盒分支 ID。结构义务需要可执行的 `probe_events` 或 `probe_predicates`；数值义务使用 Golden，并可在同次调用联合结构断言。实际有效工作量、连续调用与重复验证按 [TDD 输入与证据契约](references/evidence.md) 编写，物化配方确认触发，不能仅靠义务 ID 关联宣布覆盖。运行 `scripts/build_tdd_cases.py --spec SPEC --design DESIGN --units-dir UNITS --test-dir TEST_DIR`，校验义务与用例覆盖、TDD 输入配方及实际触发条件、白盒关联及 Golden；不写中间文件。
+
+## 验收
+
+以下按本次受托模块适用；仅黑盒设计不要求提前生成 Golden、白盒和 TDD。完整测试生成须满足全部条目。
+
+- CSV 三组 active 用例非空、ID 唯一；所有 excluded 行有明确理由且不会执行。
+- 黑盒可追溯 spec，白盒可追溯 DESIGN，TDD 每项义务能回指原生 Unit 和具体用例。
+- Golden 的数学、设计阶段与容差与 spec 和设计文件一致；固定入口按 `--sheet blackbox|whitebox|tdd --device <设备>` 执行，设备验证时使用 `--require-accelerator`。
+- 复核每项 must_distinguish 的输入与判定确实能区分错误实现；核对自然语言 coverage_axes 和结构采集来源，脚本通过不代替这些结论。义务无法由当前公开输入及断言表达时，返回具体缺口。
+- 不修改冻结的 spec、DESIGN、Unit、目标实现或测试阈值来换取通过。

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/assets/case_contract.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Fixed CANNBotDSL runner for testcase.csv blackbox/whitebox/TDD rows."""
+
+"""Shared, bounded predicates for generated CPU inputs and observed probe events."""
+
+import math
+from collections import Counter, defaultdict
+
+
+RELATIONS = {"eq", "ne", "ge", "gt", "le", "lt"}
+RUNTIME_KINDS = {
+    "output_shape",
+    "output_dtype",
+    "output_device",
+    "output_equals_input",
+    "probe_events",
+    "probe_predicates",
+    "input_conditions",
+}
+
+
+def compare(left, relation, right):
+    return {
+        "eq": lambda: left == right,
+        "ne": lambda: left != right,
+        "ge": lambda: left >= right,
+        "gt": lambda: left > right,
+        "le": lambda: left <= right,
+        "lt": lambda: left < right,
+    }[relation]()
+
+
+def validate_checks(checks, probe=False):
+    if not isinstance(checks, list) or not checks:
+        raise ValueError("checks must be a nonempty list")
+    for check in checks:
+        if not isinstance(check, dict):
+            raise ValueError("check must be a mapping")
+        if probe:
+            op = check.get("op")
+            if op not in {"count", "paired", "before"}:
+                raise ValueError("unknown probe predicate")
+            selectors = ["where"] if op == "count" else ["first", "second"]
+            if any(
+                not isinstance(check.get(key), dict) or not check[key]
+                for key in selectors
+            ):
+                raise ValueError("probe selectors must be nonempty mappings")
+            if op != "count":
+                keys = check.get("keys")
+                if (
+                    not isinstance(keys, list)
+                    or not keys
+                    or any(not isinstance(k, str) for k in keys)
+                    or len(keys) != len(set(keys))
+                ):
+                    raise ValueError("pairing requires unique key names")
+                continue
+        else:
+            if not isinstance(check.get("input"), str):
+                raise ValueError("input condition requires input name")
+            if check.get("metric") not in {
+                "dimension",
+                "numel",
+                "unique_count",
+                "count",
+            }:
+                raise ValueError("unknown input metric")
+            if check.get("metric") == "dimension" or "axis" in check:
+                if type(check.get("axis")) is not int:
+                    raise ValueError("axis must be an integer")
+            where = check.get("where", {})
+            if not isinstance(where, dict) or set(where) - {"min", "max", "eq"}:
+                raise ValueError("input filter supports min/max/eq")
+            for bound in where.values():
+                if isinstance(bound, dict):
+                    if (
+                        set(bound) != {"input", "dimension"}
+                        or not isinstance(bound["input"], str)
+                        or type(bound["dimension"]) is not int
+                    ):
+                        raise ValueError(
+                            "filter bound must reference an input dimension"
+                        )
+                elif not isinstance(bound, (int, float)) or not math.isfinite(bound):
+                    raise ValueError("filter bound must be finite")
+        if (
+            check.get("relation") not in RELATIONS
+            or not isinstance(check.get("value"), (int, float))
+            or not math.isfinite(check["value"])
+        ):
+            raise ValueError(
+                "predicate requires a finite value and comparison relation"
+            )
+
+
+def validate_assertions(assertions):
+    if not isinstance(assertions, list):
+        raise ValueError("assertions must be a list")
+    executions = 0
+    for assertion in assertions:
+        if not isinstance(assertion, dict):
+            raise ValueError("assertion must be a mapping")
+        kind = assertion.get("kind")
+        if kind == "execution":
+            executions += 1
+            repeat = assertion.get("repeat", 1)
+            if type(repeat) is not int or not 1 <= repeat <= 100:
+                raise ValueError("execution repeat must be in [1,100]")
+            if type(assertion.get("bitwise", False)) is not bool:
+                raise ValueError("execution bitwise must be boolean")
+            if assertion.get("bitwise") and repeat < 2:
+                raise ValueError("bitwise repeat requires at least two repetitions")
+            calls = assertion.get("calls", [])
+            if not isinstance(calls, list) or len(calls) > 32:
+                raise ValueError("execution calls must be a list of at most 32 entries")
+            for call in calls:
+                if not isinstance(call, dict) or not isinstance(
+                    call.get("inputs"), dict
+                ):
+                    raise ValueError("sequence call requires public input recipes")
+                if "assertions" in call:
+                    validate_assertions(call["assertions"])
+                    if any(item["kind"] == "execution" for item in call["assertions"]):
+                        raise ValueError("nested execution is unsupported")
+                if "seed" in call and type(call["seed"]) is not int:
+                    raise ValueError("call seed must be an integer")
+        elif kind not in RUNTIME_KINDS:
+            raise ValueError("unknown assertion kind")
+        elif kind in {"input_conditions", "probe_predicates"}:
+            validate_checks(assertion.get("checks"), probe=kind == "probe_predicates")
+        elif kind == "probe_events":
+            if not isinstance(assertion.get("events"), list) or not assertion["events"]:
+                raise ValueError("probe_events requires nonempty events")
+    if executions > 1:
+        raise ValueError("one execution control per case is allowed")
+
+
+def check_inputs(inputs, checks):
+    import torch
+
+    validate_checks(checks)
+    records = []
+    for check in checks:
+        tensor = inputs.get(check["input"])
+        if not isinstance(tensor, torch.Tensor):
+            raise ValueError("input condition requires a tensor")
+        metric = check["metric"]
+        axis = check.get("axis")
+        if axis is not None and not -tensor.ndim <= axis < tensor.ndim:
+            raise ValueError("condition axis outside tensor rank")
+        if metric == "dimension":
+            observed = [tensor.shape[axis]]
+        elif metric == "numel":
+            observed = [tensor.numel()]
+        else:
+            if axis is None:
+                rows = [tensor.reshape(-1)]
+            else:
+                moved = tensor.movedim(axis, -1)
+                row_count = math.prod(moved.shape[:-1])
+                rows = moved.reshape(row_count, moved.shape[-1])
+            observed = []
+            for row in rows:
+                valid = torch.ones_like(row, dtype=torch.bool)
+                for key, bound in check.get("where", {}).items():
+                    if isinstance(bound, dict):
+                        source = inputs.get(bound["input"])
+                        if not isinstance(source, torch.Tensor):
+                            raise ValueError("filter dimension source is not a tensor")
+                        bound = source.shape[bound["dimension"]]
+                    valid &= {
+                        "min": lambda: row >= bound,
+                        "max": lambda: row < bound,
+                        "eq": lambda: row == bound,
+                    }[key]()
+                selected = row[valid]
+                observed.append(
+                    int(
+                        selected.numel()
+                        if metric == "count"
+                        else torch.unique(selected).numel()
+                    )
+                )
+        if not observed or not all(
+            compare(value, check["relation"], check["value"]) for value in observed
+        ):
+            raise AssertionError(
+                f"input condition not triggered: {check!r}; observed={observed}"
+            )
+        records.append({"check": check, "observed": observed})
+    return records
+
+
+def check_probe(events, checks):
+    validate_checks(checks, probe=True)
+    if not isinstance(events, list) or any(
+        not isinstance(event, dict) for event in events
+    ):
+        raise ValueError("probe predicates require mapping events")
+    records = []
+    for check in checks:
+
+        def selected(selector):
+            return [
+                (index, event)
+                for index, event in enumerate(events)
+                if all(k in event and event[k] == v for k, v in selector.items())
+            ]
+
+        if check["op"] == "count":
+            count = len(selected(check["where"]))
+            if not compare(count, check["relation"], check["value"]):
+                raise AssertionError(f"probe count failed: {check!r}; observed={count}")
+            records.append({"check": check, "observed": count})
+            continue
+        first, second = selected(check["first"]), selected(check["second"])
+
+        def grouped(items):
+            result = defaultdict(list)
+            for index, event in items:
+                if any(key not in event for key in check["keys"]):
+                    raise AssertionError("probe pairing key missing")
+                key = tuple(event[name] for name in check["keys"])
+                try:
+                    result[key].append(index)
+                except TypeError as exc:
+                    raise ValueError("probe pairing keys must be scalar") from exc
+            return result
+
+        left, right = grouped(first), grouped(second)
+        if not left or (
+            Counter({k: len(v) for k, v in left.items()})
+            != Counter({k: len(v) for k, v in right.items()})
+        ):
+            raise AssertionError(f"probe pairing failed: {check!r}")
+        if check["op"] == "before" and any(
+            a >= b for key in left for a, b in zip(left[key], right[key])
+        ):
+            raise AssertionError(f"probe order failed: {check!r}")
+        records.append({"check": check, "pairs": len(first)})
+    return records
+
+
+def case_calls(inputs, seed, assertions):
+    validate_assertions(assertions)
+    control = next((a for a in assertions if a["kind"] == "execution"), {})
+    runtime = [a for a in assertions if a["kind"] != "execution"]
+    calls = [{"inputs": inputs, "seed": seed, "assertions": runtime}]
+    for call in control.get("calls", []):
+        calls.append(
+            {
+                "inputs": call["inputs"],
+                "seed": call.get("seed", seed),
+                "assertions": call.get("assertions", runtime),
+            }
+        )
+    return control.get("repeat", 1), control.get("bitwise", False), calls