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

package/assets/ops-direct-invoke/skills/cannbot-dsl-env-check/scripts/probe_compile_stage.py

@@ -0,0 +1,99 @@
+#!/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.
+# ----------------------------------------------------------------------------------------------------------
+
+"""按指定的 pipe stage 编译最小冒烟内核，判定 CANNBotDSL 的生成 / 编译能力。
+
+用法:
+    python3 probe_compile_stage.py translate   # DSL 翻译：bisheng 不运行
+    python3 probe_compile_stage.py compile     # DSL 编译：bisheng 运行，产出可加载 .so
+
+通过 `cannbotdsl.compile(@host 入口, specs...)` 获取 ProviderCallable，判定依据:
+    translate / transform -> program.so_path 为空，bisheng 不运行
+    compile               -> bisheng 运行，写出 .so
+
+输出:
+    stdout 末行 `RESULT=PASS:<说明>` 或 `RESULT=FAIL:<原因>`；失败另输出 `PROBE_ERROR=<错误码>`
+    stderr 保留完整异常堆栈；错误码记录失败阶段，不推断异常的根因
+    退出码 0 = PASS / 1 = FAIL
+"""
+
+import os
+import sys
+import traceback
+
+VALID_STAGES = ("translate", "compile")
+
+if len(sys.argv) < 2 or sys.argv[1] not in VALID_STAGES:
+    sys.stderr.write(f"用法: {sys.argv[0]} <{'|'.join(VALID_STAGES)}>\n")
+    sys.exit(2)
+
+stage = sys.argv[1]
+# 必须在 import cannbotdsl 之前设置：管线阶段由环境变量控制
+os.environ["CANNBOTDSL_PIPE_STAGE"] = stage
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+# probe_kernel.py 与本脚本同目录（均属本 skill 的 scripts/）
+sys.path.insert(0, HERE)
+
+
+def fail(code: str, msg: str) -> None:
+    print(f"PROBE_ERROR={code}")
+    print(f"RESULT=FAIL:{' '.join(msg.split())}")
+
+
+program = None
+failure = None
+phase = "CANNBOTDSL_IMPORT_FAILED"
+try:
+    import cannbotdsl
+
+    phase = "PROBE_INTERFACE_MISMATCH"
+    for name in ("compile", "host", "kernel", "Tensor", "TensorSpec"):
+        if not callable(getattr(cannbotdsl, name, None)):
+            raise RuntimeError(f"当前 cannbotdsl 缺少可调用接口 {name}")
+    from cannbotdsl import TensorSpec, dtypes
+    from probe_kernel import probe_entry
+
+    specs = (TensorSpec((1,), dtypes.float32),)
+    phase = "DSL_TRANSLATE_FAILED" if stage == "translate" else "DSL_COMPILE_FAILED"
+    program = cannbotdsl.compile(probe_entry, *specs)
+
+    phase = "PROBE_INTERFACE_MISMATCH"
+    so_path = program.so_path
+    if not callable(getattr(program, "close", None)):
+        raise RuntimeError("编译返回对象缺少 close()")
+
+    phase = "PROBE_ARTIFACT_INVALID"
+    if stage == "compile":
+        if not so_path or not os.path.isfile(so_path) or os.path.getsize(so_path) == 0:
+            raise RuntimeError("compile 阶段未产出非空 .so")
+        result = f"已生成 .so，size={os.path.getsize(so_path)}；未执行 DSL kernel"
+    else:
+        if so_path:
+            raise RuntimeError(f"translate 阶段不应产出 .so，却得到 {so_path}")
+        result = "so_path 为空（bisheng 未运行，符合 translate 语义）"
+except Exception as exc:
+    traceback.print_exc()
+    failure = (phase, f"{type(exc).__name__}: {exc}")
+finally:
+    if program is not None:
+        try:
+            program.close()
+        except Exception as exc:
+            traceback.print_exc()
+            if failure is None:
+                failure = ("PROBE_CLEANUP_FAILED", f"{type(exc).__name__}: {exc}")
+
+if failure is not None:
+    fail(*failure)
+    raise SystemExit(1)
+print(f"RESULT=PASS:{result}")

package/assets/ops-direct-invoke/skills/cannbot-dsl-env-check/scripts/probe_kernel.py

@@ -0,0 +1,33 @@
+#!/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.
+# ----------------------------------------------------------------------------------------------------------
+
+"""最小编译探针：仅验证 Host/Kernel 入口，不执行设备计算。
+
+保留一个 Tensor 参数以满足编译入口的张量契约；空 Kernel 不依赖
+内存分配、搬运或核信息 API。前端读取 AST，因此必须保留真实源文件。
+"""
+
+from cannbotdsl import Tensor, host, kernel
+
+
+@kernel
+class ProbeKernel:
+    def __init__(self):
+        pass
+
+    def __call__(self, a: Tensor):
+        pass
+
+
+@host
+def probe_entry(a: Tensor):
+    ProbeKernel()[1](a)

package/assets/ops-direct-invoke/skills/cannbot-dsl-env-check/tests/test_env_report.py

@@ -0,0 +1,90 @@
+#!/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.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Exercise environment probes without importing device libraries."""
+
+import importlib.util
+import subprocess
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/env_check.py"
+SPEC = importlib.util.spec_from_file_location("env_check", SCRIPT)
+env_check = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(env_check)
+
+
+class ProbeTests(unittest.TestCase):
+    def test_import_probe_is_independent_of_npu_probe(self):
+        response = subprocess.CompletedProcess(
+            [], 0, '{"module_file": "/wheel/module.py", "version": "1"}', ""
+        )
+        with patch.object(env_check, "run", return_value=response) as run:
+            result, context = env_check.check_l0()
+        self.assertEqual(result["status"], "PASS")
+        self.assertEqual(context["version"], "1")
+        statement = run.call_args.args[0][2]
+        self.assertIn("import json, cannbotdsl", statement)
+        self.assertNotIn("import torch", statement)
+
+    def test_runtime_probe_reports_devices(self):
+        response = subprocess.CompletedProcess(
+            [],
+            0,
+            '{"code": "OK", "visible_device_count": 1, "devices": [{"name": "test-npu"}]}',
+            "",
+        )
+        with patch.object(env_check, "run", return_value=response) as run:
+            result, context = env_check.check_l3()
+        self.assertEqual(result["status"], "PASS")
+        self.assertEqual(context["visible_device_count"], 1)
+        self.assertIn("import torch_npu", run.call_args.args[0][2])
+
+    def test_unavailable_runtime_keeps_diagnostic(self):
+        response = subprocess.CompletedProcess(
+            [], 13, '{"code": "NPU_UNAVAILABLE"}', ""
+        )
+        with patch.object(env_check, "run", return_value=response):
+            result, _ = env_check.check_l3()
+        self.assertEqual(result["code"], "NPU_UNAVAILABLE")
+        self.assertNotEqual(result["status"], "PASS")
+
+    def test_missing_tools_return_unavailable_inventory(self):
+        with (
+            patch.object(env_check.shutil, "which", return_value=None),
+            patch.dict(env_check.os.environ, {}, clear=True),
+        ):
+            inventory = env_check.inspect_host_npu()
+        self.assertEqual(inventory["source"], "unavailable")
+        self.assertIsNone(inventory["detected_count"])
+        self.assertTrue(inventory["warnings"])
+
+    def test_smi_deduplicates_devices_and_keeps_health(self):
+        outputs = [
+            subprocess.CompletedProcess([], 0, "0 first\n0 duplicate\n1 second\n", ""),
+            subprocess.CompletedProcess([], 0, "Health : OK\n", ""),
+            subprocess.CompletedProcess([], 0, "Health : Warning\n", ""),
+        ]
+        inventory = {
+            "source": "unavailable",
+            "detected_count": None,
+            "devices": [],
+            "warnings": [],
+        }
+        with (
+            patch.object(env_check.shutil, "which", return_value="/sbin/npu-smi"),
+            patch.object(env_check, "run", side_effect=outputs),
+        ):
+            env_check.inspect_npu_smi(inventory)
+        self.assertEqual(inventory["detected_count"], 2)
+        self.assertEqual([d["health"] for d in inventory["devices"]], ["OK", "Warning"])

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cannbot-dsl-op-design
+description: "根据算子 spec.yaml 编写分文件设计文档：数学语义、接口契约、形状与数据类型推导、算法与执行路径、任务调度、资源预算、同步及验证方案。当需要从算子规格形成方案或修订设计文档时使用。"
+---
+
+# 算子方案设计
+
+## 输入
+
+- 必需：算子的 `spec.yaml`，作为数学语义、接口、形状、数据类型、布局、边界、精度与确定性的依据。
+- 按需：调用与导出契约、目标设备能力资料、已有设计、性能数据及测试证据，用于明确执行约束和资源生命周期。
+- 缺少依据的能力、容量或行为在相关设计位置记录待验证项、影响范围和确认方法。
+
+## 输出
+
+在调用方指定的设计输出目录生成主题文件，并按 `templates/INDEX.md.templ` 生成独立索引：
+
+| 内容 | 文件 |
+|---|---|
+| 数学语义与设计不变量 | `Overview.md` |
+| 公开接口与合法输入域 | `Interface.md` |
+| 形状、数据类型与数值计算链 | `InferShapeDtype.md` |
+| 算法配置与执行路径 | `TemplatePartition.md` |
+| 阶段参数与资源预算 | `LaunchData.md` |
+| 调度、任务划分与启动顺序 | `HostLaunch.md` |
+| 计算阶段、状态与同步 | `Kernel.md` |
+| 执行能力、约束与可行性证据 | `API.md` |
+| 验证方案与开发职责 | `Validation.md`、`DevView.md` |
+| 各真实执行路径的具体设计 | `branches/DESIGN-BRANCH-<id>.md` |
+
+主题文件使用 `templates/design/` 的对应模板，分支文件使用 `templates/DESIGN-BRANCH.md.templ`。单路径也生成一份分支文件，分支 ID 用于文档引用。
+
+## 编写方法
+
+1. 在 Overview、Interface 和 InferShapeDtype 中确定公式、索引域、合法组合与逐输出边界行为。规格中的公式、文字或用例存在冲突时，列出来源及受影响场景并闭合解释。支持域调整须有规格依据。
+2. 选择算法并分析随输入规模变化的工作量、数据搬运和临时存储；关键步骤使用明确的算法与索引公式。按 [阶段成本与瓶颈分析](references/stage-cost-model.md) 在 Kernel 定义阶段成本，在 TemplatePartition 比较候选并区分固定配置、运行参数与真正不同的执行路径。
+3. 在 LaunchData 中定义阶段参数、维度关系与资源预算，在 HostLaunch 中说明检查、分配、配置选择、任务划分和启动顺序。值依赖条件写清生产、验证与消费阶段。
+4. 在 Kernel 中用数学表达式、数据流、时序表和算法伪代码描述坐标、计算、数据所有权与完成条件。采用协作、异步推进或缓冲复用时，按 [流水时序与同步契约](references/pipeline-design.md) 推导实际依赖与生命周期。存在多个工作项交错推进时，展开所选阶段数、执行资源和 warmup/steady/drain；状态版本及缓冲份数按实际对象推导。具体算法排布依据调用方提供的范式资料选择。
+5. 在 API 中记录方案需要的执行能力、适用限制与证据。在 Validation 中定义独立参考结果、比较规则、区分错误的输入和性能测量口径。关键未决项明确最小验证场景、通过条件、依赖步骤及失败后的设计调整。区分强制设计承诺、允许选项、示意伪码和待定候选；写明合法子域内哪些机制必须成立、哪些可随实现单元递增，并给出最终结构的验证依据。
+6. 跨文件核对公式、参数、任务范围、资源和验证。公共定义保留一份，分支引用并实例化差异；修改决策时更新定义位置及全部引用。
+7. 按语义与接口、路径与分支、执行与资源、验证与开发的顺序编排 INDEX。每个文件保留一个一级标题；需要汇总 DESIGN 时按索引顺序组织正文并统一标题层级，索引独立存放，参考资料独立引用。
+
+各章节按实际机制展开：状态算法填写状态初值与重置规则，协作算法填写所有权与汇合协议，多个工作项交错推进的流水填写 warmup、steady、drain 时序。顺序算法给有序操作链与必要的资源复用条件。阶段数量、角色种类与缓冲结构由当前算法及目标能力确定。
+
+设计正文记录经规格确认的契约、推导、决策及依据。生成时用具体公式、条件和参数替换填写说明与占位项。模板中的参考代码保留适用范围、来源和抽象占位说明；用于说明职责、索引和依赖，其调用形态与目标版本核对。可编译性与设备行为分别记录验证证据。
+
+## 完成标准
+
+| 核对关系 | 完成条件 |
+|---|---|
+| 规格 → 数学与接口 | 每个输出、合法数据类型组合及边界都有明确语义，非法输入有一致的处置 |
+| 接口 → 阶段参数 | 名称、顺序、维度关系、布局、可选状态和实际取值逐项对应 |
+| 公式 → 计算与状态 | 操作顺序、计算精度、初值、更新和最终输出一致 |
+| 任务 → 所有权与同步 | 覆盖完整、写入冲突受控，每个等待都有可到达的完成发布 |
+| 生命周期 → 资源预算 | 物理尺寸、副本、临时存储及在途版本完整计入，复用有最后读完成依据 |
+| 阶段成本 → 排布与选择 | 调用次数、计算量和各层搬运量可推导；实际存在的资源争用、状态依赖与流水开销支撑瓶颈判断；估算与实测有各自依据 |
+| 路径 → 验证 | 每条可达路径有合法的具体用例，关键错误变体能产生可观察差异 |
+| 设计承诺 → 实现边界 | 强制承诺、实现选择与演进边界可区分；关键未决项有首次使用前的成功判据与失败影响，签名存在不能证明组合通路可实现 |
+| 能力 → 可行性 | 关键机制有来源和适用边界，未决项有补证方法与后续依赖 |
+| 文件 → 索引与汇总 | 链接、标题、路径条件与分支文件一致，汇总采用同一阅读顺序 |

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/references/pipeline-design.md

@@ -0,0 +1,84 @@
+# 流水时序与同步契约
+
+采用协作、异步推进或缓冲复用时，按实际机制读取相关章节。执行资源、可见性机制与容量取自目标设备资料及验证。存在多个工作项交错推进时展开流水时序；顺序执行给有序操作链和复用条件。结论写入计算、参数、能力、验证及适用分支文件，公共内容保留一份，分支实例化差异。
+
+## 1. 定义任务、角色与状态
+
+从输出所有权定义完整任务，再定义各阶段推进的工作项。规约路径可用 `(输出任务, 输出块, 规约块)` 标识，实际字段由算法坐标决定。多级预取或计算队列分别定义工作项序号、槽号和代次。
+
+各阶段保留重建其输入、输出和完成条件所需的信息。延迟消费时传递相应工作项描述，包括实际需要的输出归属、内部序号、有效范围、边界与状态标识。存在任务内递推时，首次与末次由所属任务的有效工作范围判断。实际采用的任务、工作项、队列槽和状态槽分别编号。
+
+每个阶段给执行角色、工作范围与共享对象。共用执行资源的阶段写清发射顺序，并发需要目标能力依据。多个角色协作时明确各自的读写范围、完成发布、汇合方及结果对后续阶段可见的条件。
+
+状态按任务和输出范围归属，给旧状态、当前增量、新状态的位置与版本，以及各版本的最后读取者。初始化与重置区分调用、执行单元、输出任务和内部工作项；交错调度计算同时在途状态份数。
+
+例如递推 `A_j = alpha_j * A_(j-1) + B_j`，应保留旧 A 并先缩放再加入 B，或单独产生 B 后合并。首次、后续及跳过工作项分别定义转移；公式、操作链与时序实现相同的状态更新。相互依赖的工作项遵守递推顺序。
+
+## 2. 推导执行时序
+
+先列数据依赖与资源冲突，再安排各阶段。按 [阶段成本与瓶颈分析](stage-cost-model.md) 比较关键等待、搬运量、临时存储、在途状态及规模变化，说明选择依据。阶段耗时缺少证据时保留可推导的调用次数、计算量、字节量和资源负载，给测量计划。
+
+多个工作项交错推进时，在 Kernel 的流水章节展开一个覆盖 warmup、实际复用及 drain 的小例子，阶段名带具体任务与工作项索引。有状态算法覆盖多个实际有效的工作项。阶段数量、资源类型、发射顺序和深度依据当前算法推导。
+
+| 调度步 | 各资源上的阶段与工作项 | 前置完成条件 | 读写对象、槽号与代次 | 发布或释放 |
+|---|---|---|---|---|
+| 按实际排布展开 | 阶段名与工作项索引 | 谁完成什么后可推进 | 对应资源定义 | 对应同步边 |
+
+调度步表达先后和预期重叠，同一行的动作无需具有相同硬件周期。说明重叠由哪些独立资源或异步能力支持，以及仍然串行的依赖。
+
+给与时序表对应的算法伪代码：
+
+- warmup：初始状态、可用槽、实际预填量及任务数不足时的处理。
+- steady：各角色的工作项索引、等待、发射、完成发布、游标推进及复用。
+- drain：停止生产条件、剩余消费、最终输出及最后释放。
+- 边界与失败：按算法语义处理零任务、空工作项、尾部和错误后的消费或终止。
+
+说明流水在任务边界继续推进的条件、必须排空或重置的边界，以及排空需要的剩余阶段数。资源份数、最大阶段延迟与预填工作项数各自有推导。
+
+## 3. 从生命周期推导深度与同步
+
+每个实际存在的队列、可复用对象或累计状态按最大同时占用且尚未释放的版本数确定份数，再检查容量。预填量由排布、依赖与可用槽共同决定。
+
+| 对象或队列 | 工作项到槽号及代次 | 生产与写完成 | 读者及最后读完成 | 允许复用条件 | 最大在途份数 |
+|---|---|---|---|---|---|
+| 每个实际对象 | 初值、轮转及重置范围 | 数据何时可见 | 多消费者逐项列出 | 完成条件及确认方 | 深度依据 |
+
+槽选择、数据写完成、读者可见性及允许覆盖分别定义。每条同步边给生产者、消费者、共享范围、初始与期望状态、发布和等待位置、内存可见性条件及复用规则。不同存储层级的完成协议分别建模。
+
+共享存储中的同步状态说明偏移、步长、对齐与并发访问。错误和空工作项也有完整完成协议，给消费者的可观察状态、继续消费或排空条件；并发错误报告采用有依据的原子更新或独占状态加合并。
+
+参考机制核对：Channel 的 `produce()`、`consume()` 选择槽并推进各自游标，选择本身不初始化、等待或检查满空。所选对象的实际访问参与同步推导。使用该机制时核对目标版本、kind、角色、访问范围与生成同步；游标选择发生在向量计算区外，选中对象传入计算区。该接口示例用于说明需要核对的语义，实际方案按所用机制给完成条件。
+
+## 4. 核对数据通路与物理资源
+
+每条实际搬运或计算链记录逻辑形状、物理布局和步长、偏移、填充、类型以及源目的存储位置。分块矩阵链展开装载、转置含义、初始化与累加、结果交接；向量链按实际访问宽度核对掩码及尾部容量。
+
+布局转换的两侧、跨存储层级的副本与临时对象分别记账。分块结果拼接时给目的偏移、步长与有效范围；数据类型引用数值计算链。
+
+LaunchData 汇总物理分配、对齐填充、所有在途版本、常驻状态与临时存储。实际分配总量与阶段活跃峰值分别计算；共享空间给明确地址复用与不冲突生命周期依据。每池及每共享范围给容量、保留量、余量与超限处置。
+
+临时存储的各区域给类型、偏移、容量与初始化方，总容量与调度分配和计算地址公式一致。
+
+## 5. 参数绑定与边界契约
+
+接口、调度与各计算阶段采用完整的有序参数表，明确形状关系、布局、原始容量及可选状态。占位对象采用与真实最小对象可区分的契约。
+
+逻辑坐标到地址覆盖基址、分组偏移及分块偏移；间接寻址按实际算法展开。可变维度范围与规格支持域、资源上界一致。能力限制与规格合法域冲突时明确受影响输入及可行路径。
+
+逐输出定义边界形状、初始化、执行及返回条件。输出范围与操作范围分别推导；影响地址的数据值在使用前验证到安全范围。
+
+## 6. 关键机制验证与设计调整
+
+最小验证场景使用最终的类型、布局、角色与共享范围。复杂链从读取、重排、角色传递或单次计算逐步验证到组合链，每一步给具体输入、期望数据及新增机制。
+
+API 文件记录资料、适用版本、已验证范围、补证条件、依赖步骤及失败后的设计调整。缺少关键证据的方案注明可行性前提与影响范围。
+
+原型结果只支持其条件与覆盖范围。改变执行角色、算法复杂度、数据通路或同步方案时，同步更新原定义、参数、预算和验证。
+
+## 7. 区分错误的验收证据
+
+为关键义务给具体错误变体、能暴露它的公开输入或结构观察及预期差异。根据实际语义选择异值、边界、顺序或重复模式，避免输入对称性掩盖错误；状态算法让后续有效工作项改变累计结果。
+
+数值由独立参考结果判定；结构与传递由实际执行或生成产物支撑；槽协议的观察关联真实访问；重叠与性能由时间线或测量数据支撑。每类证据说明证明范围和待补部分。
+
+实际流水按机制覆盖少于预填量、触发槽复用、空工作项与尾部、多角色读者、连续配置变化及错误收尾。代表规模检查算法增长和关键等待，绝对目标采用可靠来源。

package/assets/ops-direct-invoke/skills/cannbot-dsl-op-design/references/stage-cost-model.md

@@ -0,0 +1,77 @@
+# 阶段成本与瓶颈分析
+
+用于算法与配置选择、流水排布及性能验证。调用次数、计算量与搬运量从规格、算法和物理数据流推导；时间估算需要适用的设备参数或测量依据。公共阶段模型写入 Kernel，候选比较写入 TemplatePartition，物理资源引用 LaunchData，观测与判定写入 Validation，分支代入差异。
+
+## 1. 工作量与调用次数
+
+先定义输出任务、内部工作项、执行单元分配及有效范围。总有效项数为 `N = sum_g L_g`；分别统计每调用、每执行单元、每输出任务、每工作项和内部循环的操作次数。固定初始化与末次输出单独计数。
+
+| 阶段 | 执行资源 | 调用次数及作用域 | 每次计算量 | 各层读取/写入字节量 | 转换、重排或内循环次数 | 串行依赖与复用范围 |
+|---|---|---|---|---|---|---|
+| 实际阶段 | 占用的资源及共享关系 | 由任务与循环推导 | 有效与实际执行量 | 物理路线分别记录 | 调用位置及次数 | 哪些状态或输入跨项保留 |
+
+有效计算量与实际执行量分别推导；对齐、填充、完整访问宽度和固定分块可能增加执行量。字节量按每条真实搬运边计数，区分外部存储、片上层级和布局转换两侧。中间结果写一次、读一次各自计入相应资源负载。
+
+共享输入按实际保留范围计算读取次数。一个外层项在内部循环中再次装载、转换或复制时，展开实际重复次数；明确动态尾部、可跳过项及不同任务长度如何改变成本。物理存储与搬运量均采用实际步长、填充和类型。
+
+## 2. 阶段时间及依据
+
+阶段成本拆为固定准备、计算、搬运或转换、发布等待及收尾。标注哪些分量占用同一资源而串行，哪些可在独立资源上重叠。每次耗时 t_i 与资源占用 t_ir 分别记录，需要时按不同有效范围分类。
+
+给定计算量 F、搬运量 B 及适用的有效吞吐 P、带宽 W，可构造计算与搬运下界 `F/P`、`B/W`。已证实可重叠的分量用最大值形成下界，必须串行的分量沿依赖链相加。设备峰值只提供理想下界；实际估算使用有来源且条件一致的有效值，并列出未建模的等待。
+
+缺少耗时证据时，保留确定的 F、B、调用次数、依赖和资源冲突，给采集方法及预计变化。测得值记录输入、配置、版本、目标设备、执行单元数、同步范围和统计口径。
+
+## 3. 稳态推进间隔与关键依赖
+
+选定一个推进单位，例如每进入一个有效工作项。设 a_ir 为该推进单位对资源 r 的操作次数，t_ir 为每次占用时间，m_r 为可独立分配的同类资源数。均匀且可独立分配的情况下：
+
+```text
+resource_load[r] = sum_i(a_ir * t_ir) / m_r
+tau_lower_bound >= max_r(resource_load[r])
+```
+
+资源实例之间的工作不能独立分配，或任务负载不均时，按具体实例分别求负载并取最大值。多个阶段共用一个计算单元、搬运通路或存储带宽时合并记账；阶段名称分别列出仍可能形成同一资源瓶颈。
+
+对循环携带依赖，列旧状态产生到下次可用的依赖链；其延迟为 L、跨越 d 个推进单位时，稳态间隔还满足 `tau >= L/d`。同一任务的递推、共享输入的复用与有限槽等待都需核对。候选排布的 tau 取满足资源、依赖和容量约束的可行值；下界是否能达到由具体时序及证据判断。
+
+相互独立的资源可重叠，同一资源的占用累计。阶段调用的顺序写法只能支撑发射次序，实际重叠还需独立推进能力及时间线依据。
+
+## 4. 填充、排空与执行单元负载
+
+对近似等成本且进入稳态的长任务流，可用以下估算结构：
+
+```text
+T_unit(N) ≈ T_setup + T_first_item + (N-1)*tau + T_finish + T_variation
+T_total ≈ max_unit(T_unit) + T_global_finalize
+```
+
+N>0；T_first_item 从第一个工作项进入到该项最后阶段完成，包含初始填充。T_finish 只含最后一项计算完成后尚需的输出完成、汇合或资源收尾；最后一项经过流水的延迟已计入 T_first_item。T_variation 表示不同项成本、等待及局部边界的影响。零项调用依据边界路径计算。
+
+短流、变成本工作项或分段重置采用具体时序求和与资源冲突分析。流水的排空范围由所选排布中尚未完成的阶段和对象推导，调度步数与物理时间分别计算。
+
+任务边界持续推进时计入跨任务同时持有的输入、结果和状态。边界必须排空或重置时，按实际次数累计填充及收尾。分析同一配置在少量工作项和较多工作项下的收益差异。
+
+多执行单元分别列有效工作量、内部循环次数及预计时间；较长任务、尾部和不同有效范围可能造成分配差异。总时间以关键执行单元和最终汇合为依据，候选比较同时报告总工作量与最大单元负载。
+
+## 5. 候选比较与资源约束
+
+对实际可行的算法、分块或排布填写代表输入并代入公共模型：
+
+| 候选 | 阶段次数与重复搬运 | 各资源负载及递推约束 | 填充/排空与最大单元负载 | 物理分配及可行性 | 预计瓶颈、选择条件与依据 |
+|---|---|---|---|---|---|
+| 具体方案与配置 | 可推导的计算量、字节量 | 推进间隔的限制因素 | 短流与长流分别分析 | 各池容量、所有副本和状态 | 估算、实测或待测项 |
+
+增加槽份数后，重新计算物理资源、可在途项数与等待；收益取决于原先是否受复用等待限制及资源余量。改变分块或任务划分后，重新计算重复次数、尾部成本和最慢执行单元负载。候选在相同语义、合法输入与测量条件下比较。
+
+## 6. 验证瓶颈假设
+
+根据实际存在的瓶颈与执行机制选择输入及观测：
+
+- 工作项较少与较多：检查填充/排空占比、长流推进间隔。
+- 单项计算量或搬运量改变：核对阶段时间随 F 或 B 的变化及共用资源占用。
+- 相同有效输出但任务划分不同：检查重复读取、转换次数、各单元负载与收尾次数。
+- 槽份数或排布候选变化：检查复用等待是否减少、物理容量是否满足以及其他资源负载是否成为限制。
+- 不同有效范围与任务长度：检查尾部、条件跳过、分配差异及最终汇合。
+
+实现阶段采集总时延、可用的阶段或资源时间线、实际搬运/转换次数及等待观察。总时延单项变化支持的结论有边界，关键归因由相应资源或执行结构证据支撑。预测与观测不符时定位公式遗漏、重复操作、依赖或调度开销，并同步修订成本、选择依据与验证结论。

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

@@ -0,0 +1,119 @@
+# {OP} · 分支 {BRANCH_ID} 设计
+
+实例化 TemplatePartition.md 中的一条真实执行路径。公共语义及参数定义引用全局文件，本文件给具体公式、配置及差异。
+
+## 0. 分支定位
+
+| 项目 | 本分支内容 |
+|---|---|
+| 必要且充分的进入条件 | |
+| 支持的类型、形状、布局及可选状态 | |
+| 固定配置与运行参数 | |
+| 算法、数据通路及同步差异 | |
+| 验证 Case ID | |
+
+## 1. 配置与阶段参数
+
+| 字段或参数 | 具体值或公式 | 来源及合法关系 | 消费阶段 | 有效期 |
+|---|---|---|---|---|
+| | | | | |
+
+参数顺序与 LaunchData.md 保持一致，代入本分支的完整调用。给资源不满足时的配置调整或路径选择。
+
+## 2. 分块与任务范围
+
+定义总任务数、执行单元数、任务映射、分块及有效范围。正常及边界输入代入公式，证明输入地址安全、输出覆盖和写入所有权。
+
+| 量 | 公式及单位 | 具体输入代入 | 与资源或接口的关系 |
+|---|---|---|---|
+| | | | |
+
+## 3. 阶段与数据流
+
+| 阶段及角色 | 工作范围及输入持有者 | 计算或搬运 | 输出与消费方 | 完成发布及汇合条件 |
+|---|---|---|---|---|
+| | | | | |
+
+协作、跨阶段临时存储及数据值验证按实际需要展开，初始化、可见性和失败路径具体落到阶段。
+
+## 4. 资源与状态
+
+| 对象及内存池 | 物理形状、类型及份数 | 字节公式 | 初始化值与作用域 | 活跃区间及复用条件 |
+|---|---|---|---|---|
+| | | | | |
+
+代入实际分配与每池峰值，核对容量、保留量及余量。跨池副本、填充、临时对象和在途状态各自计入，复用给共享地址与最后读完成依据。
+
+## 5. 有序计算链
+
+### 5.1 初始化
+
+给配置、参数、资源与状态的初值及重置触发点。状态拥有者与作用域引用 Kernel.md 并实例化。
+
+### 5.2 输入与布局
+
+展开坐标到物理地址、步长、有效范围、填充及消费前完成条件。
+
+### 5.3 计算
+
+| 顺序 | 数学步骤 | 输入到输出 | 类型及状态版本 | 执行角色 | 边界条件 |
+|---|---|---|---|---|---|
+| | | | | | |
+
+给精度与转换顺序，状态算法展开首次、后续及跳过工作项的转移。关键算法说明规模相关工作量及临时存储。
+
+引用 Kernel.md §6.1 的成本定义，代入本分支的阶段调用次数、有效计算量、物理搬运量及内循环重复次数。给瓶颈、适用规模与候选选择的关系，时间依据可追溯到 TemplatePartition.md。
+
+### 5.4 输出
+
+给有效地址、尾部范围、别名次序、局部结果合并及最终可见时点。
+
+### 5.5 时序与同步
+
+引用 Kernel.md §8，实例化任务与工作项索引、槽代次及完成条件。排布变化时给时序表、warmup/steady/drain 伪代码和生命周期。顺序路径给执行次序与复用条件。
+
+采用工作项交错推进时，代入本分支的阶段延迟、实际缓冲份数、预填和排空范围；按实际对象验证描述传递、初始化与最终释放，并说明资源负载及预计推进间隔。
+
+## 6. 属性与动态信息
+
+| 值 | 生产与取得阶段 | 影响的公式或阶段 | 合法检查与可见性 |
+|---|---|---|---|
+| | | | |
+
+## 7. 数值与确定性
+
+实例化 InferShapeDtype.md 的计算链，逐输出关联 Validation.md 的比较规则。边界调用与输出初始化符合公开接口。
+
+## 8. 分支验证
+
+| Case ID | 完整触发输入 | 参考结果或错误 | 比较断言 | 结构、资源或同步证据 |
+|---|---|---|---|---|
+| | | | | |
+
+覆盖本分支的正常与独有边界，并给关键错误变体及可观察差异。待验证机制明确最小场景、通过条件、依赖步骤与失败后的设计调整。
+
+## 9. 参考示例：任务映射的实例化
+
+以下保留任务映射的算法骨架。`task_to_coords`、`coord_to_offset` 和 `valid_extent` 是数学映射占位，实例化为本分支的真实坐标、步长与范围公式。计算、资源和同步对应上文阶段契约。
+
+```python
+# 设计伪代码：该分支的 block/task/tile 映射。
+block = get_block_idx()
+blocks = get_block_num()
+for task in range(block, total_tasks, blocks):
+    logical_coord = task_to_coords(task, logical_shape)
+    tile_start = coord_to_offset(logical_coord, input_strides)
+    valid = valid_extent(logical_coord, logical_shape, tile_shape)
+    # CopyIn: GM 地址、stride、padding 和读完成条件
+    # Compute: 公式步骤、累计状态、dtype/Cast 和特殊值
+    # CopyOut: 输出物理地址、mask 与写入所有权
+```
+
+将各阶段注释展开为 §5 的有序操作链。规约、扫描或递推补状态初值、更新顺序与最终写回；多输出分别给所有权。流水或协作路径核对工作项推进、完成通知及复用条件。
+
+## 10. 反例与资源代入
+按本分支实际边界选代表输入，逐项代入 §2 的坐标及 §4 的资源公式。列出有效范围、所有权、同步或参数检查的具体错误变体及对应观察。
+
+| 输入 | task/block/tile 推导 | 有效读写范围 | 峰值与容量 | 检测越界/竞态的证据 |
+|---|---|---|---|---|
+| | | | | |

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

@@ -0,0 +1,34 @@
+# {OP} 设计索引
+
+## 文件目录
+
+在此用 text 代码块列出实际输出目录树，包含本索引、主题文件和 branches/ 下的真实分支；仅在存在时列出 DESIGN.md 及上游资料。每个文件标注一句职责。
+
+以下章节给出设计阅读与汇总顺序。按实际文档标题替换链接文字，分支占位项展开为本次所有真实路径；生成后删除填写说明和未替换的占位项。
+
+## 1. 语义与接口
+
+- [算子概览](Overview.md)
+- [接口契约](Interface.md)
+- [形状与数据类型推导](InferShapeDtype.md)
+
+## 2. 执行路径与分支
+
+- [算法配置与执行路径](TemplatePartition.md)
+- [{分支 ID 与职责}](branches/DESIGN-BRANCH-{id}.md)
+
+## 3. 执行与资源
+
+- [阶段参数与资源预算](LaunchData.md)
+- [调度与启动方案](HostLaunch.md)
+- [计算与同步方案](Kernel.md)
+- [执行能力与约束](API.md)
+
+## 4. 验证与开发
+
+- [验证方案](Validation.md)
+- [开发视图](DevView.md)
+
+## 参考资料（按需保留）
+
+链接实际使用的 spec、需求或环境资料，注明其作用。它们作为设计依据独立引用，不列入上述设计正文的汇总章节。