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

package/assets/ops-direct-invoke/skills/cannbot-dsl-best-practice/references/production-code.md

@@ -0,0 +1,120 @@
+# 生产代码：清楚的结构与可检查的执行边界
+
+用于算子源码的生成与检查。整体入口与装饰器结构见 [整体实现](overall-implementation.md)；这里规定源码组织、局部写法和执行约束。算子源码只包含公开计算所需的实现与接入代码。
+
+## 源码布局与命名
+
+文件按“必要的模块说明 → 必要的 `__future__` 导入 → 标准库、第三方库、项目导入 → 常量 → 函数与类 → 注册/导出声明”组织。导入组之间留空行，所有 `import`、`from ... import ...` 在顶部完成；函数体、类体和文件中段不再导入，也不用动态导入绕过要求。
+
+Python 命名规则直接按下表使用：
+
+| 对象 | 规则 | 示例 |
+|---|---|---|
+| 变量、参数、函数、方法 | 小写单词以下划线分隔，即 `snake_case` | `valid_rows`、`workspace_bytes`、`validate_tiling` |
+| 类 | 单词首字母大写，即 `CapWords` | `OperatorKernel`、`OperatorProgram` |
+| 模块级常量 | 大写单词以下划线分隔 | `ALIGNMENT_BYTES`、`MAX_BLOCK_COUNT` |
+| 内部函数或属性 | 在正常名字前加一个下划线 | `_get_compiled_program` |
+| 与 Python 关键字冲突的名字 | 改用语义明确的名字，必要时在末尾加下划线 | `class_index`、`class_` |
+
+函数名表达动作，变量名表达数据含义；数量、字节和元素偏移要区分，例如 `row_count`、`workspace_bytes`、`row_offset_elements`。布尔量可用 `is_`、`has_`、`needs_` 表达判断。短循环中的 `row`、`col` 足够，不堆叠无意义前缀。
+
+避免单独使用易混淆的 `l`、`O`、`I`；避免用 `list`、`type`、`sum` 等名字遮蔽仍需使用的内置对象。实例方法首参使用 `self`，类方法首参使用 `cls`；双下划线特殊名称只用于 Python 已定义的协议。公开参数改名需考虑 keyword 调用契约，不能只为统一风格破坏现有接入。
+
+## 常量与数值语义
+
+### 数字具名，系数有来源
+
+Python 使用文件顶部的模块级常量承接“宏”的作用。协议字段、对齐单位、tile 支持集合、资源容量上限和必要的数学常量必须具名，注明必要的规格或接口来源。派生量保留公式，不能把计算结果写成无依据的数字。
+
+```text
+# 文件顶部；右侧从规格或实际接口取得
+ALIGNMENT_BYTES = 已确认的对齐要求
+MAX_BLOCK_COUNT = 当前实现支持的核数上限
+
+# 使用处
+padded_bytes = ((raw_bytes + ALIGNMENT_BYTES - 1) // ALIGNMENT_BYTES) * ALIGNMENT_BYTES
+```
+
+- 普通索引起点、计数递增、空长度判断中的 `0/1` 可直接使用；它们不属于隐藏业务含义的数字，无需制造 `ZERO/ONE`。
+- `scale` 等可变系数来自公开输入或规格规定的推导式。把任意系数改名为常量仍然属于硬编码；数学近似的系数和适用范围也必须有依据。
+- 固定支持范围可以声明为常量，并在入口检查；设备核数等环境事实按 [编译与启动](patterns/compilation-launch.md) 获取，不能固化开发机结果。
+
+### 位运算明确无符号类型与位宽
+
+有符号设备整数不直接参与 `& | ^ ~ << >>`。先确认非负范围、目标位宽和移位量，再使用包内已确认支持的显式无符号类型；掩码和其他操作数采用相容位宽。不能把负数直接转换为无符号值掩盖非法输入。
+
+普通 Python 的 `int` 没有固定无符号位宽；位编码应显式检查范围，按字段定义限制补码取反和移位结果。只是计算整除、取模或对齐时，优先写清楚的算术公式，不为微小优化改写成位技巧。二进制打包确需按位重解释时，明确单独的位编码契约。
+
+## 函数边界与条件校验
+
+同一语义的重复代码超过约 10 行时，考虑提取公共函数；这是检查提示，不是按行数强制拆分。优先复用校验、尺寸推导和重复计算片段，避免分支之间修复不同步。
+
+一个函数完成一个可命名的完整任务，保持参数和返回值明确。短而直观的代码可就地保留；不为一两行增加多层转发，不把参数塞进含义不明的字典，也不为表面相似但语义不同的代码强行抽象。Kernel launch 仍直接位于 `@host`，设备辅助计算按实际支持的 `@jit` 边界提取。
+
+将 tiling 合法性检查集中到 `validate_tiling(...)`，在资源分配、编译和启动前调用。选择策略复杂或需要复用时再提取 `select_tiling(...)`；固定简单配置无需多包一层。基本输入检查见 [Host 校验](patterns/host-validation.md)，同一可信边界内不重复检查。
+
+用提前报错保持正常路径平坦。以下普通 Python 示例检查正整数配置和容量，并指出具体的非法参数：
+
+```python
+def validate_tiling(tile_rows, tile_columns, item_bytes, capacity_bytes):
+    for name, value in (
+        ("tile_rows", tile_rows),
+        ("tile_columns", tile_columns),
+        ("item_bytes", item_bytes),
+        ("capacity_bytes", capacity_bytes),
+    ):
+        if type(value) is not int:
+            raise TypeError(f"{name} must be an integer, got {value!r}")
+        if value <= 0:
+            raise ValueError(f"{name} must be positive, got {value}")
+    required_bytes = tile_rows * tile_columns * item_bytes
+    if required_bytes > capacity_bytes:
+        raise ValueError(f"tile requires {required_bytes} bytes, capacity is {capacity_bytes}")
+```
+
+不要嵌套“检查通过后再检查下一项”的多层 `if/else`。解包、链式比较、集合成员判断、`all/any`、`zip/enumerate` 只在减少理解成本时使用；不同失败原因需要分别定位时保留明确的判断，不为缩短代码合成一个总条件。这些普通 Python 写法不能未经确认搬入 DSL 编译前端。VF 内条件执行见 [VF](patterns/vf.md)。
+
+## 注释与冗余代码
+
+源码默认不添加解释性注释，以命名、类型、表达式和函数边界表达实现。`#` 注释与模块、类、函数的 docstring 使用同一保留标准：仅保留必要的公开契约，或缺失后容易导致错误修改、且代码本身无法清楚表达的非显然约束。
+
+- 模块或公开入口确需说明时，只写最短的计算职责、外部契约或非显然限制；代码和签名已表达的内容省略。内部函数和类默认不写职责介绍或 docstring。
+- 删除实现说明，包括算法步骤、阶段划分、数据流、分支流程、变量用途、helper 职责、调用顺序及逐行翻译；不使用阶段标题、编号或大段分隔注释组织源码。实现方案与推导放在设计资料中。
+- 同步、缓冲复用、偏移单位、对齐及数值边界只有在省略说明会隐藏具体误用风险时才保留，不能按这些主题逐项补注释。保留时就近写一句必要条件或原因；同一事实只写一次。
+- 实验、日志、验证结果、性能记录、修改历史和已注释掉的旧代码从源码删除。许可证、工具指令等具有实际用途的注释按其用途保留。
+
+逐条检查现有注释：删掉后是否会遗漏必要的外部契约，或引入可指出的误用风险？两者都不会就删除；无法判断必要性时默认删除实现说明，不把它搬进 docstring 或另一个代码位置。
+
+删除恒真 `assert`、同一可信边界内重复且状态未变化的检查、不可达分支、无用变量，以及已确认不改变类型和数值语义的 `+ 0`、`* 1` 等运算。不要用无意义算术制造 Tensor 输出或触发设备执行。
+
+公开 Python 输入校验使用明确的 `TypeError/ValueError` 等异常，不依赖可被优化模式关闭的 `assert`。有实际作用的范围检查、跨边界校验和编译器约束要保留。删除浮点恒等式前确认 signed zero、NaN 和类型转换语义，不能仅按字面形式删代码。
+
+## 设备执行约束
+
+约束覆盖公开入口及其调用的 helper、注册与适配层。以实际是否下发额外设备任务为准；写在 Host 函数中的 Tensor 操作同样受约束。
+
+### Host 职责与设备计算
+
+- Host 负责 `shape/dtype/device/stride` 等元数据校验、Python 标量计算、资源分配、已确认的零拷贝视图和目标 Kernel 启动。
+- 设备数据的初始化、计算和必要布局处理由目标 DSL Kernel 完成；包装层不调用其他设备算子补算结果，不使用 `output + 0`、额外乘系数等后处理。
+- 普通输入与 tiling 校验只依赖元数据和 Host 参数；不通过 `.item()`、`.cpu()` 或设备 Tensor 转布尔值读取内容，避免引入数据回传与同步。
+
+### 分配、初始化与视图
+
+- 禁止用 `torch.full`、`torch.zeros/zeros_like`、`torch.ones/ones_like`、`Tensor.zero_()/fill_()` 等接口在目标 Kernel 外初始化设备数据；别名、helper 和 `torch.ops` 间接调用遵循同一规则。
+- 输出与 workspace 使用 `torch.empty/empty_like` 等未初始化分配接口，并确保实际分配路径不附带设备填充。分配所得内容不可直接读取；目标 Kernel 必须覆盖全部有效输出，在读取临时数据前完成所需写入，并满足跨核、跨阶段的数据依赖。
+- 必要的零值或常量填充在目标 Kernel 内完成，不额外启动初始化 Kernel，也不先在 CPU 构造数据再搬到设备绕过约束。
+- `view/reshape/contiguous/.to(...)` 等操作仅在已确认不发生数据复制或转换时保留。需要复制的布局调整、`clone`、dtype 转换，以及设备 Tensor 上的算术、比较和归约，不放在包装层执行；不能仅凭接口名称认定操作是零开销的。
+
+### 启动边界
+
+单 Kernel 实现的一次有效计算调用只启动目标 Kernel，不额外启动清零、填充、转换或其他辅助计算。独立 AICPU 计算和再次启动的 Kernel 均属于独立设备执行，不能因名称相同或封装在同一入口内而视为一次启动。
+
+目标 Kernel 内部的 C/V 协作、多核并行、数据搬运与必要同步按计算依赖组织，不属于额外算子启动；同步遵循 [同步](patterns/synchronization.md) 中的约束。
+
+## 轻量检查
+
+- 结合本次改动检查导入位置、命名、常量与系数来源、函数边界、tiling 校验、位运算及冗余代码。
+- 按“注释与冗余代码”的保留标准检查完整模块说明、类与函数 docstring 及本次涉及的注释块，删除实现说明；每条保留内容须能指出必要契约或具体误用风险。仅修改注释时保持执行语句不变；修改 docstring 前确认没有读取其内容的调用方或工具。
+- 沿公开入口检查直接调用和 helper，明确各操作属于元数据处理、分配、零拷贝视图还是设备执行；注册与适配层遵循相同边界。
+- 检查输出覆盖范围、workspace 首次读取前的写入及各执行分支的启动行为。接口语义不明确时先核实实现，不能仅凭名字或搜索结果认定满足约束。

package/assets/ops-direct-invoke/skills/cannbot-dsl-code-reviewer/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: cannbot-dsl-code-reviewer
+description: "检视调用方提供的 CANNBotDSL 算子代码，依据真实代码证据报告命名、魔数和结构可读性问题。当用户要求 DSL 代码审查、检视实现或复核 PR 时使用。"
+metadata:
+  category: review
+---
+
+# CANNBotDSL 代码检视
+
+## 输入
+
+- 调用方指定的算子源码文件、目录或 PR 差异。
+- 可选：算子规格、设计资料、Unit 和测试结果，用于理解代码职责与排除误报。
+
+## 输出
+
+在调用方指定的位置写可读性检视报告。每项发现包含文件、准确行号、最短必要代码片段、问题、分级、证据与修复建议；没有发现时也给出明确结论。报告格式参考 [报告写法](steps/report-write.md)。
+
+## 检视方法
+
+1. 实际阅读目标代码和必要的调用上下文，按 [可读性规则](references/readability-rules.md) 检查命名、魔数与结构风格。规则来自真实 DSL 算子检视语料，只提供判断线索。
+2. 按 [检视方法](core/methodology.md) 对候选问题检测、核实、判定。每条正反证据都引用真实代码行；缺少证据的候选不判为 FAIL。
+3. 报告使用 FAIL、SUSPICIOUS、待确认分级。语料外发现单独标注，不强行套入现有规则；需要作者判断时写清待确认事项。
+
+本 Skill 提供检视方法与报告内容。调用方安排执行角色、并行和报告路径。

package/assets/ops-direct-invoke/skills/cannbot-dsl-code-reviewer/core/methodology.md

@@ -0,0 +1,104 @@
+# CANNbot DSL 代码检视方法论
+
+检视代码并逐条核实候选时使用。执行角色和报告位置由调用方安排。
+
+## 三步法：检测 → 核实 → 判定
+
+**1. 检测**：按规则文档各原则的识别规程（提问/阅读规程）在算子文件里
+定位候选。
+
+**2. 核实（举证）**：Read 候选行上下文（前后 ≥10 行），对照原则的
+「举证要点」和「豁免思路」收集证据，按下方打分表累计置信度。判断
+涉及变量来源、跨层语义时，Grep/Read 相关定义与调用处综合判断。
+
+**3. 判定**：按置信度区间给出结论，附证据与代码片段。
+
+## 置信度打分
+
+对每个候选建立假设：
+- **原假设 H0**：该代码段无问题
+- **备择假设 H1**：该代码段存在规则所述问题
+- 置信度初始 0%
+
+### 正向证据（支持 H1，加分）
+
+| 证据类型 | 分值 | 分析动作 |
+|---------|------|---------|
+| 规范违反 | +40% | 对照规则条款识别到明确的违规模式 |
+| 上下文防御缺失 | +30% | 作用域内无防御代码（无注释说明意图/无常量化/无保护） |
+| 调用链风险 | +15% | Grep 分析被调函数内部逻辑后确认风险传导 |
+| 数据流风险 | +15% | 变量来源不明确、运算路径不可控 |
+| 领域关联 | +10% | 代码命中规则的 DSL 领域触发特征 |
+
+### 负向证据（支持 H0，减分）
+
+| 证据类型 | 分值 | 分析动作 |
+|---------|------|---------|
+| 防御存在 | -20% | 作用域内有显式防御：边界判断 / 非空校验 / const_expr 编译期保证 / 常量区已定义且注释充分 |
+| 上游校验 | -15% | 作用域外已有校验，且校验变量与风险变量相同或可证等价 |
+
+**设计原则**：负向证据单项分值低于正向证据——防止找到一条模糊防御就
+大幅扣分。真正充分的防御需要**多条负向证据叠加**才能将置信度降至安全
+区间，单条负向证据不应单独决定判定。
+
+### ⚠️ 证据强制引用要求
+
+每条正向/负向证据必须附可验证的代码引用，否则该条证据计 0 分：
+
+```
+格式: [文件路径]:[行号] [具体代码行内容]
+示例: quant_block_sparse_attn.py:69 DMA_BLOCK_BYTES = 32
+```
+
+- 声称"上游已校验" → 必须 Grep 找到校验语句，且确认校验变量与风险变量
+  是同一个（或经赋值链可证等价）；校验了"某个相关变量"不算数
+- 声称"编译期常量" → 必须引用 const_expr / 常量区定义行
+- 声称"Channel 自动同步" → 必须引用该 buffer 的 Channel(...) 声明行
+- **找不到对应代码 → 该证据计 0 分，禁止虚构举证**
+
+### 证据有效性校验（排除误报，满足任一即降级）
+
+- 负向证据累加 ≤ -50% → 不进入 FAIL
+- 上下文可证明不可能触发风险（如 const_expr 编译期已排除该分支）→ 排除
+
+## 结论分级
+
+置信度 = Σ 正向 + Σ 负向（负向为负数）
+
+| 结论 | 置信度 | 含义 |
+|------|--------|------|
+| FAIL | ≥80% (HIGH) | 明确违规 |
+| SUSPICIOUS | 70-80% (MED) | 可疑，需人工确认 |
+| 待确认 | 证据显示问题存在但修复方向依赖作者意图 | 语料中约 10% 属此类 |
+| PASS | <70% (LOW) | 证据不足，不判定违规（报告中只汇总） |
+
+## 严重度
+
+| severity | 适用 |
+|----------|------|
+| high | 误导性命名（名实冲突）、跨处联动的魔数（改动需散弹式多处修改） |
+| medium | 同概念多名、重复代码、职责堆积的规模问题、关键流程注释缺失、C++ 翻译痕迹 |
+| low | 缩写命名、死代码、注释语言混杂、风格偏离基线 |
+
+## 常见豁免（命中即重点收集负向证据，细则见规则文档各原则的豁免思路）
+
+- 读者群有共享约定的惯用名（同仓/文档有约定或全文一致）→ 非坏命名
+- 不随设计变化的恒真量（数学常数、有注释的硬件定值、公开枚举）→ 非魔数
+- 硬件布局/并发意图要求的对称写法或手工展开，且有注释说明 → 非重复
+- 有注释说明的 ABI 占位、防御性兜底 → 非死代码
+- 以文件/仓库多数派为基线的风格 → 非风格问题
+
+豁免判断按规则文档各原则的"豁免思路"（理由类别）执行，禁止靠背实例过关。
+
+## 代码片段格式要求
+
+FAIL / SUSPICIOUS / 待确认 必须附：
+- 准确行号（写入 findings 前重新核对）
+- **最短足以证明问题的真实代码片段**（通常 ≤6 行；复制原文，禁止改写）
+- 一句话问题描述 + 一句话修复建议
+- 证据清单压缩为一行：`+40 规范违反@1234 +30 防御缺失@549 -15 上游校验@213`
+
+## 条款边界
+
+每条规则有明确适用范围。对不上问题模式的候选 → PASS 并注明；语料外的
+新问题模式 → 报告中标注"语料外发现"，不强行归入现有规则。

package/assets/ops-direct-invoke/skills/cannbot-dsl-code-reviewer/references/readability-rules.md

@@ -0,0 +1,280 @@
+# 可读性规则（DSL-R01 ~ R10）
+
+语料来源：191 个人工检视问题中的 A 命名（~35%）、B 魔鬼数字（~15%）、
+D 结构风格（~20%）。本文档不是判定清单，而是**判定框架**：每条原则给出
+意图、识别规程（问什么、读什么）、举证要点、豁免思路、修复方向。
+
+**使用方法**：逐条原则对算子文件执行识别规程 → 对发现的候选按方法论
+置信度打分举证 → 判定。文档中的"常见形态"是语料中反复出现的例子，
+**用于帮助理解原则，不是穷举，更不是检测词表**——命中形态不必然违规，
+不命中形态也不必然合规；判定永远以原则和证据为准。
+
+---
+
+### DSL-R01 命名自注释
+
+**意图**：名字是读者理解代码的第一入口。当读者必须跳转到赋值/声明处
+才能理解一个名字时，阅读成本随跳转次数指数上升——这是语料中占比
+最高的问题。
+
+**识别**：通读代码，对每个变量/参数/函数名问：
+> "只看使用处，我能说出它是什么轴/哪个阶段/什么结构/什么单位吗？"
+
+答不上来即候选。常见形态（举例，非穷举）：
+- 过短缩写，语义全靠注释或上下文反推
+- 无领域限定的通用词（表位置/表状态/表结果的泛泛之词单独使用）
+- 用类型或容器当名字（dtype 缩写、buffer 直称）
+- 成组的单字母前缀别名，前缀本身无含义
+
+**举证**：引用使用处与赋值处，说明"理解使用处必须回看赋值"这一
+跳转真实存在。名字存活范围很小且语义就是右值本身时降级。
+
+**豁免思路**：读者群有共享约定的惯用名——判断依据是同仓/文档有
+明确约定或全文一致使用，而不是"看着眼熟"。
+
+**修复**：名字承载轴/阶段/结构/单位限定；统计量、奇偶半区、延迟线
+等用完整语义词；函数名预告返回内容的领域语义。
+
+---
+
+### DSL-R02 名实一致（不误导）
+
+**意图**：缩写名只是读不懂，误导名会让读者建立**错误**心智模型，
+顺着错误假设改代码——比 R01 危险得多。
+
+**识别**：对名字中含有的领域词（模式/结构/单位/状态词），核实变量
+真实语义是否与之相符。问：
+> "按名字理解，我会对这个变量的语义产生什么预期？实际语义符合吗？"
+
+常见形态：名含某领域词但语义是另一回事；名为布尔前缀但用整数
+赋值与判断（整数伪布尔）；函数名是"处理/解析/执行 + 泛词"，与函数
+体实际职责对不上。
+
+**举证**：给出名字的预期语义（依据领域常识）与代码实际语义的
+对照，两者冲突成立即 high。
+
+**豁免思路**：名字虽简但有就近注释消歧——降为 R01 low。
+
+**修复**：换真实语义的自注释名；布尔语义用真布尔；模式/状态用
+枚举而非裸值。
+
+---
+
+### DSL-R03 一名一义，一义一名
+
+**意图**：同一概念多种写法，读者要维护"它们是不是一回事"的映射；
+同一名字多种含义，读者每见一次都要重新消歧。
+
+**识别**：双向检查：
+1. 对核心领域概念（统计量/缩放/延迟线/分核结果等），收集文件内
+   所有指代它的名字——多于一个即候选（词序变体、缩写全词并存、
+   不同函数签名中同一缓冲的形参名不同）
+2. 对复用频率高的短名，核实各处的语义是否一致——一名多义同样
+   是问题
+
+**举证**：列出同概念的全部写法及其位置；或同一名字的多个语义
+及各自位置。
+
+**豁免思路**：跨层边界处故意的改名，且有注释给出映射（host 元
+数据字段 vs kernel 形参）。
+
+**修复**：每概念定一个标准名全文件统一；同仓算子间共用概念对齐。
+
+---
+
+### DSL-R04 字面量单一事实来源
+
+**意图**：会随设计调整联动的数，裸写 N 处就埋下 N 处漏改的雷
+（"散弹式修改"）。这条原则管的不是"字面量"本身，而是"改动时
+要同步改多处"这一事实。
+
+**识别**：对代码中的数值字面量，问两个问题（不预设数值范围）：
+1. **它会随设计调整而变吗？**（块宽、轮数、系数、格式参数会；
+   数学/硬件恒真不会）
+2. **它有多处联动吗？**（同一数值出现在多处；或改一处必须同步
+   改他处——深度、取模底数、循环步长的联动最典型）
+
+两问有一为是 → 必须命名。另查：常量区已命名的值，代码中仍裸写
+同值字面量且语义相关——这是"定义了却不用"，同一表达式两种写法
+并存是最有说服力的证据。
+
+**举证**：指出字面量的全部出现位置及联动关系；说明改值时需要
+改几处。错误消息字符串中嵌的数值也要查——常量改值后消息说谎。
+
+**豁免思路**：不随设计变化的恒真量（数学常数、硬件定值且有注释）、
+公开契约的一部分（有文档的枚举值）、语义自足的小局部量。
+
+**修复**：模块级命名常量，派生量用表达式（`HALF = BASE // 2`），
+关键常量带推导注释；联动参数单一来源——一处定义，深度/取模/
+循环全部引用；错误消息用 f-string 引用常量。注意"同值异义"：
+同一数值承担两种语义时应拆成两个常量，而不是共用一个。
+
+---
+
+### DSL-R05 无重复
+
+**意图**：重复不是"看着像"，是"改一处要同步改多处"的维护地雷；
+也是读码时的噪音。
+
+**识别**：结构同构判定——把标识符/常量换成占位符后仍相同的
+代码块即同构。常见形态（举例）：
+- 多个同构块散布（仅变量名/偏移不同）
+- 同一循环骨架反复出现，仅最内层操作不同
+- 仅以编号区分的手工展开（常伴随写死偏移与"展开数 == N"断言）
+- 仅按一个布尔转发给下划线同名函数的透传 wrapper
+
+判定**是否该抽象**：差异能否用参数/循环/分发表表达？抽象后是否
+损害硬件并发意图？
+
+**举证**：给出各同构实例的位置与占位符化后的相同骨架；说明
+差异可参数化。若展开是性能意图（ILP/bank 冲突避免），要求有
+注释说明——无注释的性能展开仍报。
+
+**豁免思路**：硬件布局/并发语义要求的对称写法，且有注释说明意图。
+
+**修复**：可参数化的差异提函数/提循环；编号展开改列表+循环；
+透传 wrapper 合并、差异进参数或进函数名。
+
+---
+
+### DSL-R06 规模可审阅
+
+**意图**：超出读者一次能建立心智模型的规模，检视和修改都会
+失真。规模问题的实质不是行数，是**职责堆积**。
+
+**识别**：问三个问题：
+1. 这个函数能用一句话说清职责吗？（函数体内同时做校验、推导、
+   分配、launch 编排等多种职责 → 该拆，无论行数）
+2. 这个类/文件有清晰的分段结构吗？（helper/kernel/校验/接口
+   边界）
+3. 量级是否明显越界？（参考量级，非硬阈值：函数百行级、公开
+   接口函数应短到只剩编排、文件数千行级、单类数百行级）
+
+**举证**：给出函数/类/文件的跨度与其内部职责清单——职责种类
+比行数更有说服力。
+
+**豁免思路**：无（规模问题总是真的，只是优先级不同）。
+
+**修复**：按职责分段/拆文件；校验段独立成文件；接口函数只留
+编排（校验调用→派生→分配→launch）。
+
+---
+
+### DSL-R07 无死代码与冗余操作
+
+**意图**：不改变行为的代码让读者为其虚构目的（"这段存在必有
+原因"），浪费理解成本。
+
+**识别**：对每段代码问"删掉它，行为会变吗？"不会变即候选。
+常见形态：恒等运算（加零/乘一/零乘项，常为编号对称性保留）；
+纯别名搬家（连续字段复制，直接引用原字段即可）；恒真/恒假的
+编译期断言；被后续无条件覆盖的赋值；与算子无关的历史注释/
+引用。
+
+**举证**：证明删除不改变数据流/控制流。覆盖性赋值要给出覆盖
+点的行号。
+
+**豁免思路**：有注释说明的 ABI 占位/防御性兜底；为对齐意图
+保留的恒等项且有注释。
+
+**修复**：删除已证实的冗余；别名改直接引用；复述实现的伪代码
+注释直接删除，必要的契约或非显然约束在相关代码附近简述。
+
+---
+
+### DSL-R08 注释即意图
+
+**意图**：注释解释代码未表达的原因和约束。`#` 注释及模块、类、
+函数 docstring 都属于检查范围，精简后仍能理解正确使用和修改代码
+必须遵守的条件。
+
+**识别**：
+1. 完整阅读模块说明、函数 docstring 和相关注释块。逐行翻译、
+   参数或类型复述、实验记录、临时日志路径、测试数量与修改历史
+   均为冗余候选；搬入 docstring 后仍按同一标准判断。
+2. 同一事实是否在模块、函数和调用处重复展开？区分重复叙述与
+   不同使用点确有必要的局部前提。
+3. 注释与当前代码是否一致，引用是否可核实？外部论文和稳定
+   接口文档可作为来源；过期符号与临时取证位置不能替代当前约束。
+4. 同步完成条件、资源复用时机、偏移单位、对齐及数值边界等
+   非显然原因是否在相关位置说明？明显的分支或阶段无需补注释。
+5. 自然语言说明是否遵循当前项目语言约定？API 名称、公式、
+   许可证文本与必要术语保留原样。
+
+**举证**：冗余给出具体行段及其重复的代码或说明；过期给出与当前
+实现的矛盾；缺失说明删去该约束可能导致的具体误用。行数和占比
+只能帮助定位，不能单独判为缺陷。
+
+**豁免思路**：许可证、公开接口契约和代码无法表达的正确性约束
+应保留；复杂约束确需多句时，以必要性判断，不机械限行。
+
+**修复**：删除复述与过期内容；将长篇说明收敛为当前契约和必要
+原因，并放在最相关的位置。详细推导及实验记录归入调用方提供的
+设计或验证资料，不要求额外文档路径。保持计算、同步、签名和
+执行语句不变；docstring 若被运行时或工具读取，先核实其用途。
+
+---
+
+### DSL-R09 风格以多数派为基线
+
+**意图**：风格的价值在于一致——同一文件/仓库内风格跳变处，
+往往是外部粘贴或多人拼合的痕迹，也是缺陷高发处。
+
+**识别**：不预设具体风格标准，先建立文件的"多数派基线"
+（空格、空行、换行对齐、错误消息格式），再找**系统性偏离**
+基线的区域：
+- 成片运算符/逗号无空格的区域（与全文风格断裂）
+- 连续空行、多余换行的聚集
+- 错误消息格式不一：首字母大小写、语言、前缀风格在同文件
+  内并存
+
+**举证**：给出基线形态与偏离形态的对照实例——证明偏离是
+"区域性的"而非个别笔误。
+
+**豁免思路**：无（偏离多数派基线本身即证据）。
+
+**修复**：以多数派为基线统一；错误消息统一首字母、语言与
+前缀风格。
+
+---
+
+### DSL-R10 用 Python 的方式写
+
+**意图**：语料的总体结论之一是 AI 生成代码带明显"C++ 翻译成
+Python"痕迹——同样的逻辑，用 Python 表达力写更短、更清楚、
+更少错。
+
+**识别**：找"用 C 思路写 Python"的模式（常见形态举例）：
+- 锯齿校验：成串单条件 if/raise，每对只查一个变量的一个
+  属性——表驱动（dict/元组列表 + 循环一次查多维）或多条件
+  合并是 Python 化写法
+- camelCase 标识符、单字母形参
+- 整数伪布尔（=1/=0 配合 !=0 判断）
+- 位运算代替除法对齐，且移位量与对齐常量是两个独立事实
+  来源（应整除引用常量，单一来源）
+- 手工索引循环搬运本可用切片/生成器/any/all 表达的逻辑
+
+**举证**：给出 C 思路写法与对应 Python 化写法的对照（可用
+同仓已有范例佐证——语料中的表驱动校验就是好例子）。
+
+**豁免思路**：性能/硬件语义要求的写法，有注释说明。
+
+**修复**：表驱动替代锯齿；snake_case；真布尔；除法对齐引用
+常量；善用生成器表达式与多条件合并。
+
+---
+
+## 语料溯源索引
+
+| 原则 | 语料类别 | 语料中的典型（仅溯源用，非检测词表） |
+|------|---------|-------------------------------------|
+| R01 | A | sm_ 前缀统计量、裸 col 循环变量、he/ho 奇偶寄存器 |
+| R02 | A | m_macro（实为当前合并最大值）、sp（实为缩放）、整数伪布尔 |
+| R03 | A | scale_p/p_scale 并存；sm_max/softmax_max 跨算子并存 |
+| R04 | B | 公式系数裸写；深度/取模/轮数三处联动；已定义常量仍裸写同值 |
+| R05 | D | 四路编号展开+UNROLL 断言；同形 chunk 循环十余处；透传 wrapper |
+| R06 | D | 超 3000 行文件、千行单类、232 行接口函数 |
+| R07 | D | 加零/零乘恒等项、十行字段搬家、被覆盖的兜底赋值 |
+| R08 | D | 同小节中英混杂、注释引用 C++ 成员、逐行"标量等价" |
+| R09 | D | band 区成片无空格、错误消息大小写并存 |
+| R10 | D | 20+ 对锯齿 if/raise、camelCase 形参、>>4 与 ALIGN=16 脱钩 |

package/assets/ops-direct-invoke/skills/cannbot-dsl-code-reviewer/steps/clause-review.md

@@ -0,0 +1,59 @@
+# 检视子 Agent prompt 模板（阶段1 派发时填入 {} 占位）
+
+---
+
+你是 CANNbot DSL 代码检视子 agent，负责**可读性规则线**。
+
+## 输入
+
+- 被检视算子文件：`{算子文件路径}`
+- 规则文档：`{skill_base}/references/readability-rules.md`
+- 方法论：`{skill_base}/core/methodology.md`
+{PR 模式追加}- diff 变更行区间：`{行区间列表}`（FAIL/SUSPICIOUS 必须
+  锚定在区间内；区间外发现标 `out_of_diff: true`）
+
+## 执行流程
+
+1. Read 方法论全文，掌握三步法与置信度打分
+2. Read 规则文档全文——它是判定框架：十条原则各有意图、识别规程、
+   举证要点、豁免思路
+3. 对每条原则依次执行：
+   - **识别**：按原则的识别规程（提问/阅读规程，不是 grep 清单）在
+     算子文件中找候选。"常见形态"只是帮助理解的例子，命中不必然
+     违规、不命中不必然合规；DSL API 语义不确定时，在算子文件的
+     import/docstring/同仓用法中找依据，仍不确定 → 待确认
+   - **核实**：Read 候选上下文，按方法论收集正/负向证据并打分；
+     每条证据必须能引用 `文件:行号+代码内容`，找不到计 0 分；
+     豁免判断按原则的豁免思路（理由类别），不按背实例
+   - **判定**：置信度 ≥80% FAIL / 70-80% SUSPICIOUS / 修复方向依赖
+     作者意图 → 待确认 / <70% PASS
+4. 十条原则之外发现的可读性问题：同样打分举证，标 `corpus: false`
+
+## 输出（文本返回，不写文件）
+
+```yaml
+file: "{算子文件路径}"
+findings:
+  - rule: "DSL-R01"
+    verdict: FAIL            # FAIL/SUSPICIOUS/NEEDS-CONFIRM
+    severity: high           # high/medium/low
+    confidence: 85
+    line: 1234
+    snippet: |               # 最短足以证明的真实片段（≤6 行，原文）
+      ...
+    description: "问题描述一句话"
+    evidence: "+40 规范违反@1234 +30 防御缺失@549 -15 上游校验@213"
+    suggestion: "修复建议一句话"
+  - rule: "DSL-R02"
+    verdict: PASS
+    note: "零候选 或 豁免成立的原因一句话"
+summary: "{N} FAIL / {M} SUSPICIOUS / {K} 待确认 / {J} PASS"
+```
+
+## 禁令
+
+- 禁止仅凭规则文档示例下结论，必须 Read 算子真实代码
+- 禁止把"常见形态"当检测词表——判定以原则和证据为准
+- 禁止虚构证据引用；证据找不到对应代码计 0 分
+- 禁止为凑数量把 low 当 medium、把风格当逻辑
+- 禁止修改任何文件（只读检视）

package/assets/ops-direct-invoke/skills/cannbot-dsl-code-reviewer/steps/report-write.md

@@ -0,0 +1,60 @@
+# 检视报告格式
+
+报告写入调用方指定的位置；文件名由调用方安排。
+
+**撰写三原则：清晰、可读、简洁。**
+- 结论先行，三句话说清"什么问题最多、最该先改什么"
+- 全部问题一张表，一行一条，不展开细节
+- 证据链一行压缩：`+40 规范违反@1234 -20 防御@1200 → 85%`
+- 代码片段只在"非看不可"时给，且只给最短足以证明的几行
+
+---
+
+```markdown
+# {算子名} CANNbot DSL 可读性检视报告
+
+- 文件：{路径}（{行数} 行）  日期：{YYYY-MM-DD}
+{PR 模式按需追加}- PR：{链接}
+
+## 结论
+
+{2-3 句：命中了哪几条原则、集中在什么段落、建议的整改优先级}
+
+## 问题清单
+
+按严重度排序，一行一条：
+
+| # | 严重度 | 规则 | 位置 | 问题（一句话） | 修复（一句话） | 置信度（证据链） |
+|---|--------|------|------|---------------|---------------|------------------|
+| 1 | high | R02 | :541 | `m_macro` 名含"宏块"实为当前合并最大值，误导 | 改 `current_max` | 85%（+40@541 +30@549 -15@213） |
+| 2 | medium | R04 | :1707 | preload 轮数 `% 3` 与 `depth=3` 三处写死联动 | 抽 `PIPELINE_DEPTH` 单一来源 | 80%（+40@1707 +40@880） |
+
+## 待确认
+
+| 位置 | 问题 | 需要作者确认 |
+|------|------|-------------|
+| :2086 | res_o 裸 buffer 的 vec_sync_all 是否必需 | 内存拓扑：生产/消费方是否同核 |
+
+## 豁免与说明
+
+{1-2 句：命中识别但豁免成立的典型；语料外发现条数}
+{PR 模式按需追加：附录"上下文观察"——out_of_diff 历史问题一行一条}
+
+## 附：结构化发现（机读用）
+
+```yaml
+findings: [ {真实发现，去除 PASS} ]
+```
+```
+
+---
+
+## 撰写要求
+
+- 问题清单一行一条，问题和修复各一句话；超过一行说明没抓住重点
+- 证据链格式：`+分值 类型@行号`，空格分隔，末尾 `→ 置信度%`
+- 只有当"一句话说不清、必须看代码才懂"时才在表格下方附最短片段
+  （≤6 行），并在表格该行标注 `[见下]`
+- 待确认表说明"需要作者确认什么"，不是罗列
+- 全零问题也出报告：结论写"未发现可读性问题"+ 豁免说明一句
+- 不写"检视过程""规则介绍"等元信息——读者是算子作者，不是技能用户