cannbot-dsl-op-design

根据算子规格编写分文件设计文档:数学语义、接口契约、形状与数据类型推导、算法与执行路径、任务调度、资源预算、同步及验证方案。当需要从算子规格形成方案或修订设计文档时使用。

SKILL.md

GitHub

算子方案设计

输入

  • 必需:算子规格文件,作为数学语义、接口、形状、数据类型、布局、边界、精度与确定性的依据;路径与文件名由调用方提供。
  • 按需:调用与导出契约、目标设备能力资料、已有设计、性能数据及测试证据,用于明确执行约束和资源生命周期。
  • 按需:调用方提供的范式资料(算法模型、语言适配层与能力约束),用于核对算法排布与适用前提;范式知识由调用方从其选定来源提供,本 Skill 不维护范式库、不产出范式文档。
  • 缺少依据的能力、容量或行为在相关设计位置记录待验证项、影响范围和确认方法。

输出

在调用方指定的设计输出目录生成主题文件,并按 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. 选择算法并分析随输入规模变化的工作量、数据搬运和临时存储;关键步骤使用明确的算法与索引公式。按 阶段成本与瓶颈分析 在 Kernel 定义阶段成本,在 TemplatePartition 比较候选并区分固定配置、运行参数与真正不同的执行路径。
  3. 在 LaunchData 中定义阶段参数、维度关系与资源预算,在 HostLaunch 中说明检查、分配、配置选择、任务划分和启动顺序。值依赖条件写清生产、验证与消费阶段。
  4. 在 Kernel 中用数学表达式、数据流、时序表和算法伪代码描述坐标、计算、数据所有权与完成条件。采用协作、异步推进或缓冲复用时,按 流水时序与同步契约 推导实际依赖与生命周期。存在多个工作项交错推进时,展开所选阶段数、执行资源和 warmup/steady/drain;状态版本及缓冲份数按实际对象推导。具体算法排布依据调用方提供的范式资料选择。
  5. 在 API 中记录方案需要的执行能力、适用限制与证据。在 Validation 中定义独立参考结果、比较规则、区分错误的输入和性能测量口径。关键未决项明确最小验证场景、通过条件、依赖步骤及失败后的设计调整。区分强制设计承诺、允许选项、示意伪码和待定候选;写明合法子域内哪些机制必须成立、哪些可随实现单元递增,并给出最终结构的验证依据。
  6. 跨文件核对公式、参数、任务范围、资源和验证。公共定义保留一份,分支引用并实例化差异;修改决策时更新定义位置及全部引用。
  7. 按语义与接口、路径与分支、执行与资源、验证与开发的顺序编排 INDEX。每个文件保留一个一级标题;需要汇总 DESIGN 时按索引顺序组织正文并统一标题层级,索引独立存放,参考资料独立引用。

各章节按实际机制展开:状态算法填写状态初值与重置规则,协作算法填写所有权与汇合协议,多个工作项交错推进的流水填写 warmup、steady、drain 时序。顺序算法给有序操作链与必要的资源复用条件。阶段数量、角色种类与缓冲结构由当前算法及目标能力确定。

设计正文记录经规格确认的契约、推导、决策及依据。生成时用具体公式、条件和参数替换填写说明与占位项。模板中的参考代码保留适用范围、来源和抽象占位说明;用于说明职责、索引和依赖,其调用形态与目标版本核对。可编译性与设备行为分别记录验证证据。

完成标准

核对关系 完成条件
规格 → 数学与接口 每个输出、合法数据类型组合及边界都有明确语义,非法输入有一致的处置
接口 → 阶段参数 名称、顺序、维度关系、布局、可选状态和实际取值逐项对应
公式 → 计算与状态 操作顺序、计算精度、初值、更新和最终输出一致
任务 → 所有权与同步 覆盖完整、写入冲突受控,每个等待都有可到达的完成发布
生命周期 → 资源预算 物理尺寸、副本、临时存储及在途版本完整计入,复用有最后读完成依据
阶段成本 → 排布与选择 调用次数、计算量和各层搬运量可推导;实际存在的资源争用、状态依赖与流水开销支撑瓶颈判断;估算与实测有各自依据
路径 → 验证 每条可达路径有合法的具体用例,关键错误变体能产生可观察差异
设计承诺 → 实现边界 强制承诺、实现选择与演进边界可区分;关键未决项有首次使用前的成功判据与失败影响,签名存在不能证明组合通路可实现
能力 → 可行性 关键机制有来源和适用边界,未决项有补证方法与后续依赖
文件 → 索引与汇总 链接、标题、路径条件与分支文件一致,汇总采用同一阅读顺序