| name | spark-omnioperator-test-design-generator |
| description | 为Spark OMNI优化算子生成标准化测试设计文档。触发关键词：OMNI算子测试设计、OMNI算子测试、OMNI测试设计文档、omnioperator test design、omni TableWrite/TableRead/Filter/HashAggregate/Sort/HashJoin/Window算子测试设计 |
Spark OmniOperator 优化算子 — 测试设计文档生成
为指定算子生成标准化测试设计文档，穷举所有测试点，每条用例必须独立、具体、可执行。
适用场景
本技能在以下场景下激活：
- 为 Spark OMNI 优化算子（TableWrite、TableRead、Filter、HashAggregate、Sort、HashJoin、Window 等）生成标准化测试设计文档
- 对 OMNI 算子进行系统性测试点穷举，覆盖数据类型、边界值、场景、性能、可靠性、兼容性等维度
- 按标准化模板输出测试设计 Markdown 文档
输出文件：{OperatorName}_Test_Design_Document.md
输出目录：当前工作目录下的{OperatorName}_Test_Design/
参考文件
references/ 和 templates/ 目录提供参考文件，执行过程中按需加载：
算子速查卡映射表（仅加载目标算子对应的文件）：
执行协议（CRITICAL）
必须使用任务管理工具（todowrite 或 TaskCreate），在任务开始时创建并显示任务列表，随进度更新状态：
1. 收集算子信息
1.1 获取源码路径（必须询问用户）
1.2 扫描Spark源码（必须执行，不可跳过）
1.3 提取详设文档信息
2. ⏸️ 用户确认算子信息（必须展示源码扫描结果）
3. 生成测试设计文档框架（前4章）
4. 生成功能测试点（6种测试设计方法）
5. 生成其他测试类型（性能/可靠性/兼容性）
6. 用例统计与自检
6.1 自动统计用例数量（grep验证）
6.2 执行检视清单（逐项grep验证）
7. ⏸️ 用户最终确认
8. 输出最终文档
状态更新规则：
- 开始执行时设为
in_progress
- 完成时设为
completed
⏸️ 标记表示需要用户审批的检查点，不可跳过
流程
Phase 1: 算子定位与信息收集
流程概览：接收用户输入 → 源码扫描 → 详设文档提取 → 用户确认。
Step 1: 收集算子信息（源码扫描 + 详设文档提取）
接收用户输入：算子名称、输出目录（默认当前工作目录）、开发详设文档路径
Spark源码扫描（必须执行，不可跳过）
⚠️ 开发详设文档可能遗漏实现细节，源码扫描是验证和补充信息的唯一可靠来源。
源码位置：Spark 和 Gluten 源码位于工作目录根路径下（即 {workspace-root}/spark/ 和 {workspace-root}/Gluten/）。扫描前先用 ls 确认目录存在，不存在时询问用户实际路径。禁止直接报告"本地无源码"而不尝试查找。
| 源码组件 | 扫描内容 | 扫描文件路径 |
|---|
| 原生算子实现 | 核心逻辑、输入验证、异常处理 | {workspace-root}/spark/sql/core/src/main/scala/org/apache/spark/sql/execution/datasources/ |
| Omni算子实现 | 与原生算子的差异、数据类型支持 | {workspace-root}/Gluten/backends-omni/src/main/scala/org/apache/spark/sql/execution/datasources/ |
| 开关配置 | 配置项名称、默认值 | {workspace-root}/Gluten/shims/common/src/main/scala/org/apache/gluten/config/GlutenConfig.scala |
| 算子触发条件 | 触发/回退条件 | {workspace-root}/Gluten/backends-omni/src/main/scala/org/apache/gluten/extension/columnar/offload/ |
扫描输出（缺失项标记"未找到"）：
- 原生算子类名及关键方法
- Omni算子类名及触发条件
- 开关配置项（命名模式：
spark.omni.sql.columnar.{算子名} 或 spark.gluten.sql.columnar.{算子名}）
- 支持/不支持的数据类型列表
- 异常处理逻辑
开发详设文档提取：
从用户提供的开发详设文档中提取：
| 设计文档内容 | 提取要点 | 输出 |
|---|
| 算子功能描述 | 核心功能、设计目标、使用场景 | 测试范围定义 |
| 技术实现方案 | 算法选择、数据结构、关键流程 | 测试设计重点 |
| 边界条件说明 | 支持的输入范围、限制条件 | 边界值测试用例 |
| 性能优化点 | 优化策略、预期提升、影响因素 | 性能测试场景 |
| 已知问题 | 待解决问题、限制条件 | 风险规避测试 |
⚠️ 如果用户未提供详设文档，必须要求用户补充以下信息后方可继续：
- 算子核心功能与设计目标
- 支持的数据类型列表
- 已知限制与边界条件
- 性能优化策略（如有）
Step 2: ⏸️ 用户确认算子信息（强制检查点）
⚠️ 用户确认后方可进入 Phase 2，不可跳过。
按以下模板生成确认信息，通过AskUserQuestion的preview展示并确认：
📋 {算子名称} 信息确认
一、源码扫描结果
| 扫描项 | 扫描结果 | 来源文件 |
|---|
| 原生算子类名 | {如 InsertIntoHadoopFsRelationCommand} | {文件路径} |
| Omni算子类名 | {如 OmniInsertIntoHadoopFsRelationCommand} | {文件路径} |
| 开关配置项 | {如 spark.omni.sql.columnar.dataWritingCommand} | {文件路径} |
| 开关默认值 | {如 true} | {文件路径} |
| 支持的数据类型 | {源码中确认的类型列表} | {文件路径} |
| 不支持的数据类型 | {源码中确认的类型列表} | {文件路径} |
| 异常处理逻辑 | {触发异常的条件描述} | {文件路径} |
二、详设文档提取结果
| 类别 | 项目 | 内容 |
|---|
| 基础定位 | 算子名称 | {如 HashJoin} |
| 基础定位 | 数据流向 | {写入类 / 读取类} |
| 基础定位 | 功能语义 | {关联类 / 聚合类 / 排序类 / 过滤投影类 / 窗口类 / 写入类 / 扫描类 } |
| 基础定位 | Omni算子名称 | {如 OmniHashJoinExec} |
| 基础定位 | 开关配置 | {如 spark.omni.sql.columnar.hashjoin} |
| 基础定位 | 风险等级 | {极高 / 高 / 中} |
| 数据类型 | 支持的类型 | {如 INT, LONG, DOUBLE, STRING, DATE, DECIMAL...} |
| 数据类型 | 不支持的类型 | {如 BINARY, MAP, STRUCT...} |
| 数据类型 | 包含中文的类型 | {如 STRING, CHAR, VARCHAR} |
| 算子判断 | 支持类型→Omni算子出现 | {如 OmniHashJoinExec} |
| 算子判断 | 不支持类型→原生算子出现 | {如 HashJoinExec} |
| 算子特有 | {按算子类型展示} | {如 Join类→INNER/LEFT OUTER/...; Agg类→SUM/AVG/...; Write类→INSERT INTO/OVERWRITE} |
| 源码文档 | Spark源码扫描 | ✅ 已完成 / ❌ 未完成 |
| 源码文档 | 开发详设文档 | ✅ 已提供 / ❌ 未提供 |
三、信息一致性检查
| 检查项 | 源码扫描结果 | 详设文档结果 | 速查卡结果 | 一致性 |
|---|
| 支持数据类型 | {源码} | {详设} | {速查卡} | ✅一致 / ❌不一致 |
| 不支持数据类型 | {源码} | {详设} | {速查卡} | ✅一致 / ❌不一致 |
| 开关配置 | {源码} | {详设} | {速查卡} | ✅一致 / ❌不一致 |
四、差异项处理（如有不一致）
| 差异项 | 源码结果 | 详设文档结果 | 速查卡结果 | 用户确认结果 |
|---|
| {差异项1} | {内容} | {内容} | {内容} | {用户确认以哪个为准} |
⚠️ 不一致处理规则：
- 源码扫描结果 > 详设文档结果 > 速查卡结果（优先级从高到低）
- 如有不一致项，必须列出差异并让用户确认以哪个为准
- 速查卡中的数据类型列表可能包含通用配置，必须以详设文档或源码扫描结果为准
使用AskUserQuestion确认，选项提供"信息正确，继续"和"需要修正"（用户选"需要修正"时在Other中说明具体修正项）。
Phase 2: 生成测试设计文档
流程概览：生成文档框架 → 6种方法展开功能测试点 → 补充其他测试类型 → 自检 → 用户确认 → 输出。
Step 3: 生成测试设计文档框架（前4章）
读取模板，填充Phase 1确认的算子基础信息，生成测试设计文档前4章。
读取 test_design_document_template.md，按模板结构生成以下章节：
| # | 章节 | 核心内容 | 数据来源 |
|---|
| 1 | 概述 | 算子功能与测试范围 | Phase 1 定位结果 |
| 2 | 算子签名 | 名称/数据流向/开关/重要性 | Phase 1 定位结果 |
| 3 | 参考实现分析 | 原生算子/Omni算子/验证方法/SQL模式 | Phase 1 + 算子速查卡 |
| 4 | 输入因子 | 因子编号/分类/名称/可选值/权重 | 算子速查卡 |
自检（必须执行grep验证并展示输出）：
⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。
- 算子签名与定位信息是否一致 →
grep 验证算子名称/数据流向/开关配置
- 输入因子表是否完整 →
grep 对比速查卡因子数量与文档中因子数量
- 参考实现分析是否准确 →
grep 验证原生/Omni算子类名
Step 4: 生成功能测试点（6种测试设计方法）
按6种测试设计方法逐层展开功能测试点，每条用例必须独立、具体、可区分。
1. 等价类划分法（EC/IE）
- 加载算子速查卡中对应算子的输入因子表
- 对每个"极高"权重因子，按其可选值逐个生成有效等价类（EC）
- 对每个"极高"权重因子，生成无效等价类（IE）：非法输入、不支持类型、异常配置
- 对"高"权重因子，按核心取值生成有效等价类
- 对"中"权重因子，生成关键有效等价类
2. 边界值分析法（BV）
- 加载 data-type-reference.md 中数据类型矩阵
- 对每种支持的数据类型，生成边界值用例：最小值/最大值/零值/接近边界值/NULL
- ⚠️ CRITICAL：边界值用例禁止写具体数值，只写边界值描述
- ✅ 正确示例：
SHORT类型最小值写入、INT类型最大值写入、LONG类型零值写入
- ❌ 错误示例：
SHORT类型-32768写入、INT类型2147483647写入
- 边界值描述格式：
{数据类型}{边界值类型}写入，如 SHORT类型最小值写入
3. 场景法（SC）
- 加载算子速查卡中对应算子的测试场景清单
- 将每个场景编号展开为独立测试点
- 补充异常流程场景
4. 判定表法（DT）
- 识别多条件组合场景
- 列出所有条件取值组合
5. 正交试验法（OA）
- 选取"极高×极高"因子对，生成2-wise核心组合
- 选取"极高×极高×高"因子组合，生成3-wise高风险组合
6. 错误推测法（EG）
- 补充易错场景：类型溢出、空值处理、并发冲突、精度丢失等
自检（必须执行grep验证并展示输出）：
⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。
- 6种方法是否都已覆盖 →
grep -c "^| EC-\|^| IE-" / grep -c "^| BV-" / grep -c "^| SC-" / grep -c "^| DT-" / grep -c "^| OA-" / grep -c "^| EG-"
- 每种数据类型是否逐条展开（非合并为"各数据类型测试"）→
grep 检查是否存在"各数据类型"合并写法
- 边界值是否只写描述未写具体数值 →
grep "^| BV-.*[0-9]\{4,\}" 有输出则需修正
- 是否存在范围合并编号（如"054-065 异常分支测试"）→
grep "[0-9]\{3\}-[0-9]\{3\}" 检查
注意：本步骤自检的是第五章（测试设计方法）的展开是否完整，最终输出到第六章（功能测试点）时需要按"合并原则"进行精简。
Step 5: 生成其他测试类型（性能/可靠性/兼容性）
在功能测试点基础上，补充性能、可靠性、兼容性测试点。
- 性能测试：按 test-type-reference.md 性能测试节生成，重点覆盖TPC-DS场景、数据量级、数据类型下的端到端耗时对比
- 可靠性测试：按 test-type-reference.md 可靠性测试节生成，覆盖异常输入、资源限制、并发等场景
- 兼容性测试：按 test-type-reference.md 兼容性测试节生成，覆盖Spark版本、数据源、部署模式等维度
自检（必须执行grep验证并展示输出）：
⚠️ 读取参考文件 ≠ 执行检查。必须用grep命令验证并展示结果，禁止直接写结论。
- 三大测试类型是否都有规划 →
grep -c "^| P-" / grep -c "^| R-" / grep -c "^| C-" 均大于0
- 各维度是否逐条展开 →
grep 检查是否存在合并写法
- 性能测试是否包含TPC-DS场景 →
grep "TPC-DS" 检查
Step 6: 用例统计与自检
汇总用例统计，使用参考文档进行自检。
用例统计（必须自动统计）：
⚠️ CRITICAL：必须通过脚本或工具自动统计用例数量，禁止人工计数，避免统计错误。
统计维度：
- 按测试设计方法统计：等价类、边界值、场景法、判定表、正交试验、错误推测各多少条
- 按测试类型统计：功能、性能、可靠性、兼容性各多少条
- 按Level统计：Level0、Level1、Level2各多少条
- 总计：总用例数
统计方法：
- 使用
grep 等工具统计各章节的用例编号数量
- 验证统计结果与实际生成的用例数量一致
- 在文档中输出统计结果
自检清单（必须逐项执行）：
⚠️ CRITICAL：必须加载检视文档并逐项检查，记录检查结果。
| 检视项 | 检视文档 | 检视内容 | 检查方法 |
|---|
| 数据类型覆盖 | data-type-checklist.md | 支持类型是否逐类型展开？不支持类型回退是否覆盖？边界值是否覆盖？ | 加载检视文档，逐项勾选 |
| 算子场景覆盖 | 算子速查卡 | 速查卡中每个场景编号是否都有对应测试点？Level0是否100%覆盖？ | 对比速查卡场景编号与生成的测试点 |
| 测试类型覆盖 | test-type-checklist.md | 四大测试类型是否都有规划？各维度是否逐条展开？ | 加载检视文档，逐项勾选 |
| 穷举完整性 | — | 第五章是否存在范围合并编号？每条是否独立可区分？第六章是否按合并原则精简？ | 检查编号连续性和合并规则 |
| 边界值格式 | — | 边界值用例是否只写描述未写具体数值？ | 检查边界值用例是否包含数字 |
自检执行步骤（必须执行命令并展示输出）：
⚠️ CRITICAL：每一步都必须执行指定的 grep/bash 命令并展示输出。禁止跳过任何步骤，禁止直接写"✅通过"而不执行命令。
-
用例数量统计：执行以下命令并展示输出
grep -c "^| T-" {文档} / grep -c "^| P-" / grep -c "^| R-" / grep -c "^| C-"grep "^| T-.*Level0" {文档} | wc -l / Level1 / Level2- 根据统计结果写入文档 7.1/7.2 节，然后再次 grep 验证写入的数据与实际用例数一致
-
场景覆盖验证：对比速查卡 W-xxx 与文档测试点
grep "^| W-" {速查卡} | awk -F'|' '{print $2}' 提取速查卡场景编号grep "场景法" {文档} | grep -o "SC-[0-9]*" | sort -u 提取文档覆盖的场景- 逐一对比每个 W-xxx 是否有对应测试点，未覆盖的必须补充
-
边界值格式检查：
grep "^| BV-.*[0-9]{4,}" {文档} → 有输出则说明包含具体数值，必须修正为描述格式
-
数据类型/测试类型检视：重新加载 checklist 文件逐项勾选（读取 ≠ 检查）
-
生成自检报告：将以上命令输出和检查结果写入文档 7.4 节，格式：
- 用例统计验证表（grep结果 vs 文档记录）
- 场景覆盖验证表（速查卡编号 vs 测试点）
- 检视清单执行结果
- 问题汇总及修正记录
Step 7: ⏸️ 用户最终确认（强制检查点）
使用 AskUserQuestion 进行最终确认，不可直接输出最终文件。
⚠️ 用户确认后才可输出最终文件。如需修改，先修改再重新确认。
📋 {OperatorName} 测试设计文档已生成，请确认：
【算子定位】{OperatorName} → {数据流向} / {功能语义} / 风险等级：{Level}
【用例规划】
- 功能测试：XX条（Level0:XX, Level1:XX, Level2:XX）
- 性能测试：XX条（Level0:XX, Level1:XX）
- 可靠性测试：XX条（Level0:XX, Level1:XX）
- 兼容性测试：XX条（Level0:XX, Level1:XX）
- 总计：XX条
【自检摘要】
- 用例统计：grep验证 功能XX+性能XX+可靠性XX+兼容性XX=XX ✅/❌
- 场景覆盖：Level0 XX/XX ✅/❌ / Level1 XX/XX ✅/❌
- 边界值格式：无具体数值 ✅/❌
- 完整自检报告见文档 7.4 节
如需调整请告知，确认后将输出最终文档。
Step 8: 输出最终文档
用户在 Step 7 确认后，将完整测试设计文档写入输出目录。
输出文件：{OperatorName}_Test_Design/{OperatorName}_Test_Design_Document.md
重要约束
| 约束项 | 说明 |
|---|
| 逐条罗列（第五章） | 测试设计方法每条用例独占一行，禁止范围合并写法 |
| 具体可区分 | 去掉类型/模式标记后，步骤仍能与其他用例区分 |
| 边界值不写具体数值 | 边界值用例只写描述不写具体数值，如"SHORT类型最小值写入"而非"SHORT类型-32768写入" |
| 不写SQL语句 | 测试设计文档只写测试点，不写具体SQL实现 |
| 数据类型展开（第五章） | 支持的每种数据类型各一条用例，不合并 |
| 合并精简（第六章） | 边界值合并到数据类型，错误推测作为覆盖因子 |
| 用例统计自动统计 | 必须使用工具自动统计用例数量，禁止人工计数 |
| 覆盖因子格式统一 | 格式：主方法-具体点 | 次方法-具体点 |
| 检视清单必须执行 | 必须加载并执行data-type-checklist.md和test-type-checklist.md |
| 自检必须执行工具 | 禁止直接写结论，必须执行grep/bash命令并展示输出 |
输出格式规范
用例命名
- 格式：
{算子名}_{场景描述}，如 TableWrite_支持BOOLEAN类型写入
- 自检：去掉类型/模式标记后，步骤仍能与其他用例区分
测试范围
- 具体可执行，包含测试数据：
BOOLEAN类型(true/false/null)写入→SELECT验证结果正确
覆盖因子
⚠️ CRITICAL：覆盖因子格式必须统一，便于追溯和验证。
格式规范：
- 主要覆盖因子放在前面，次要覆盖因子作为补充
- 格式：
主方法-具体点 | 次方法-具体点
- 示例：
等价类-BOOLEAN | 边界值-true/false | 场景法-支持类型写入
覆盖因子类型：
等价类-{因子名}：等价类划分法覆盖的因子边界值-{边界类型}：边界值分析法覆盖的边界（如：最小值、最大值、零值）场景法-{场景名}：场景法覆盖的场景判定表-{条件组合}：判定表法覆盖的条件组合正交试验-{因子组合}：正交试验法覆盖的因子组合错误推测-{易错场景}：错误推测法覆盖的易错场景
自检：
- 覆盖因子是否与第五章的测试设计方法对应
- 覆盖因子是否完整反映了该用例的测试点
合并原则
- 边界值 → 合并到对应数据类型测试，不单独列
- 错误推测 → 不作为独立用例，作为覆盖因子
- 判定表/正交 → 场景化，作为覆盖因子
