向量化优化 Skill

将用户的自然语言描述转化为 ./devkitai vectorization_workflow 命令并执行，对 C/C++ 源码进行 SVE/NEON 向量化优化。

目录结构

Vectorization-Optimization/
├── SKILL.md                       # 主 skill（核心规则，精简）
├── README.md                      # 本文件（用户文档）
├── references/                    # 子 skill / 详细参考
│   └── examples-guide.md          # 25 个典型示例（示例 0–24）
└── assets/                        # 检查清单 / 模板
    └── command-checklist.md       # 命令构建与执行前检查清单

能力概览

基于 DevKit 天秤源码优化工具，对 C/C++ 源码进行 SVE/NEON 双指令集扫描与 AI 辅助改写：

• 自动扫描源码中的可向量化循环
• 自动改写并验证功能与性能，验证失败的场景回退 AI 辅助改写
• 支持 4 种分析模式：单文件 / 火焰图 / 指定函数 / 全项目
• 输出优化后源码、HTML 报告和 git patch

触发条件

当用户提到以下关键词或意图时使用此 Skill：

• "向量化"、"SVE"、"NEON"、"ARM 优化"、"鲲鹏优化"
• "性能优化"、"循环优化"、"指令集优化"
• 要求优化 C/C++ 源码

命令格式

./devkitai vectorization_workflow --project-dir <项目路径> [其他可选参数]

• --project-dir 是唯一必填参数，缺失时必须向用户询问，不得猜测或编造路径。
• 其余参数均为可选，仅当用户自然语言中明确表达了对应意图时才添加。
• 严禁添加用户未提到的参数。
• 解析出的参数名必须且仅能来自参数映射表，严禁自行编造表外参数名。

参数映射

下表为命令可用的全部参数，且为唯一合法来源：

CLI 参数	必填	默认值	说明
--project-dir	是	—	项目源码根目录
--file-path	否	空	指定分析的 C/C++ 源文件路径
--flamegraph-path	否	空	火焰图 SVG 文件路径，用于热点函数分析
--funcs	否	空	指定分析的函数名列表，逗号分隔
--top	否	50	热点函数 Top N 数量，配合火焰图使用
--vectorization-path	否	空	天秤源码优化工具可执行文件路径
--simd-target	否	neon	目标指令集：neon 或 sve
--gcc-toolchain	否	空	Clang 所使用的 GCC 工具链根目录路径
--clang-resource-dir	否	空	Clang 资源目录路径（至 lib/clang/版本号，不含 include）
--disable-tool-patch-test	否	False	关闭工具补丁单元测试验证
--disable-strategy	否	False	关闭策略库加载
--tool-jobs	否	全并行	全项目模式天秤源码优化工具并行工作进程数，默认全并行
--max-workers	否	全并行	AI 补丁级并行工作线程数，默认全并行

参数填充规则

1. 只填用户明确提到的参数：用户说"优化项目 A"，就只填 --project-dir A。
2. --simd-target 是唯一例外：用户未提到指令集时默认填 neon；提到 SVE 填 sve，提到 NEON 填 neon。
3. 布尔型参数：仅在用户明确表达"关闭""不用""跳过""不验证"等意图时添加。
4. 数值型参数（--top、--tool-jobs、--max-workers）：仅在用户明确给出具体数字时添加，用户说"自动"或"默认"时不添加。
   • 值必须为正整数，否则提示并询问确认。
   • --top 仅火焰图模式有效，其余模式提示无效并忽略、继续执行。
   • --tool-jobs 仅全项目扫描模式有效，其余模式提示无效并忽略、继续执行。
   • 模糊并行度（有数字但无法区分指工具还是 AI）→ 停止询问用户确认。
5. 路径型参数：无法确定时向用户询问。
6. 项目根目录必须明确：只给文件路径但无法确认根目录到哪一层时，列出候选层级请用户确认。

禁止行为（红线规则）

以下行为严禁，违反将导致命令构建错误（详见 SKILL.md「禁止行为（红线规则）」章节，每条配 ✗/✓ 示例）：

1. 禁止自行发现并添加参数：不得扫描文件系统/目录寻找文件并自动添加路径参数
2. 历史参数须确认后使用：发现用户可能沿用历史会话参数时，必须提示并询问确认，不得直接带入
3. 禁止推断用户意图并落为参数：不得因"用户大概想要"而添加参数
4. 禁止自行补全缺失参数：缺失参数必须询问用户，不得自行猜测或补全
5. 禁止添加用户未提到的可选参数：用户只提到策略库 → 仅加 --disable-strategy，不加 --disable-tool-patch-test
6. 表述无法完全确认时必须询问：用户表述模糊无法确认具体值或所指时，停止询问用户（可列候选请用户选择），不得猜测填入

扫描模式识别

所有模式下 --project-dir 均为必要参数。

明确模式（用户明确说明了扫描模式）

模式	必要参数	无效参数	缺失/无效处理
单文件	--project-dir + --file-path	--top、--tool-jobs	缺文件→询问；提供无效参数→提示忽略，继续执行
全项目	--project-dir	--top（--tool-jobs 有效）	提供 --top→提示忽略，继续执行
火焰图	--project-dir + --flamegraph-path	--tool-jobs（--top 有效）	路径缺失或不确定→询问；提供 --tool-jobs→提示忽略
指定函数	--project-dir + --funcs	--top、--tool-jobs	缺函数名→询问；提供无效参数→提示忽略，继续执行

明确模式触发表达示例：单文件="优化这个文件 xxx.c"；火焰图="火焰图 xxx.svg"/"根据热点分析"；指定函数="优化函数 funcA, funcB"；全项目="优化整个项目"。

未明确模式（按参数推测）

• 仅 --file-path → 单文件；仅 --funcs → 指定函数；仅 --flamegraph-path → 火焰图；无定向参数 → 全项目（兜底）
• --file-path + --funcs 或 --file-path + --flamegraph-path → 不视为冲突，文件作为辅助参数共存
• --funcs + --flamegraph-path 并存 → 参数冲突，停止询问以哪个模式为准
• 前置检查 --top：有 --top 无 --flamegraph-path → 停止，询问提供火焰图或忽略 --top
• 前置检查 --tool-jobs：有 --tool-jobs 且有定向参数 → 停止，询问选全项目（忽略定向参数）或其他模式（忽略 --tool-jobs）

火焰图模式启用前提：仅当用户给出具体 SVG 路径时才启用；仅表达意图未给路径 → 提示指定路径，不猜测、不降级为其他模式。

指令集判断

• 用户提到 "SVE" → --simd-target sve
• 用户提到 "NEON" → --simd-target neon
• 用户未指定 → 默认 --simd-target neon

异常处理

参数缺失

缺失参数	处理方式
--project-dir 缺失	停止，向用户询问，不得猜测或使用默认值
根目录层级不明确	停止，列出候选层级请用户确认
--file-path 缺失	明确单文件模式但未给路径 → 询问文件路径
--flamegraph-path 缺失	明确火焰图模式但未给路径或不确定 → 询问 SVG 路径
--funcs 缺失	明确指定函数模式但未给函数名 → 询问函数名列表
数值参数未给值或非正整数	提示并询问确认，可一次性列出全部无效项

执行中异常

异常类型	含义	处理
FileNotFoundError	工具未生成结果或报告文件缺失	检查工具是否正确安装和配置
CalledProcessError	工具执行失败（非零返回码）	查看 stderr，检查工具参数和项目路径
RuntimeError: exhausted retries	LLM 连接重试耗尽	检查网络连接和 config.yaml 中的 API 配置
ValueError: CPU 不支持	服务器架构不匹配指令集	需换到支持对应指令集的 ARM 服务器
命令未找到 ./devkitai	二进制未安装或不在当前目录	检查 devkitai 是否已安装、工作目录是否正确

交互异常

• 未给项目路径 → 询问项目路径
• 要求用 AVX 等不支持的指令集 → 告知仅支持 SVE 和 NEON
• 要求优化非 C/C++ 项目 → 告知仅支持 C/C++ 源码
• 路径不存在 → 告知请用户确认
• 未明确模式 + --top 无火焰图 → 停止，提示"--top 必须配合火焰图使用"
• 未明确模式 + --funcs 与 --flamegraph-path 并存 → 停止，询问以哪个模式为准
• 未明确模式 + --tool-jobs 且有定向参数 → 停止，询问选全项目或其他模式
• 明确非火焰图模式 + --top → 提示无效忽略，继续执行
• 明确非全项目模式 + --tool-jobs → 提示无效忽略，继续执行
• 并行度模糊（有数字无工具/AI 指向词）→ 停止，询问指工具并行还是 AI 并行
• 数值参数值无效或未给值 → 提示并询问确认

失败或结果为空（不擅自重试）

执行失败或结果为空时，不得自动重试或自行修改参数重新执行：

1. 先分析：查看 workflow.log、stderr 与产物目录，定位原因
2. 再给方案：向用户说明原因并提出下一步处理方案
3. 征得同意后才执行：询问"是否按此方案继续尝试？"，只有用户明确同意后才可重新执行
4. 禁止擅自执行：用户未同意前不得再次调用 bash 工具、不得自行修改参数重跑

用户同意后按其认可方案继续；用户拒绝则停止，如实汇报当前状态与失败/空结果原因。

执行方式

• 使用 bash 工具执行命令
• 工作流可能运行数分钟到数十分钟，取决于项目规模和补丁数量
• 执行过程中可查看 {workspace}/workflow.log 跟踪进度（workspace 路径在命令执行时由工作流打印到终端）
• 用户可按 Ctrl+C 中断，第一次优雅终止，第二次强制退出
• 用户未提到的参数不要主动添加，使用默认值

执行后产物

产物	路径	说明
优化后源码	{workspace}/result/	补丁应用后的 C/C++ 源文件
HTML 报告	{workspace}/patch/*.html	源码 vs 优化代码对比 + 性能收益
git patch	{workspace}/patch/devkit-vectorization.patch	origin 与 result 的 unified diff
日志	{workspace}/workflow.log	全流程详细日志

{workspace} 路径在命令执行时由工作流打印到终端（格式为 [Done] 工作区: <路径>），从终端输出中提取。

主动查看 workflow.log 中的 Summary 和 Final Summary，向用户报告：

• 工具补丁通过数 / AI 补丁通过数 / 总计
• 每个补丁的性能提升百分比
• 失败/回退的补丁数量及原因

若执行失败或结果为空，不得擅自重试，先分析原因、给出处理方案并向用户征得同意后才可重新执行。

执行前两层校验

构建命令后，必须依次完成两层校验，全部通过后方可执行：

1. 边界场景定向检索（第一层）：检查当前场景是否匹配 SKILL.md 工作流程第 6 步索引表中的边界场景。若匹配，读取 references/examples-guide.md 中对应示例，确认处理方式一致；不匹配则跳过。常规正向场景（示例 0–9）无需定向检索，按需参考。
2. 检查清单逐项核对（第二层）：参照 assets/command-checklist.md 逐项核对，涵盖 10 个维度：参数来源核验（红线）、必填项、参数合法性、指令集、模式校验、数值校验、路径校验、布尔参数校验、执行前确认、失败/空结果处理。其中"参数来源核验（红线）"维度对应 SKILL.md「禁止行为（红线规则）」第 1–6 条，确保每个参数均来自用户当前对话的明确表述。

示例

完整示例共 25 个（示例 0–24），分两类：

• 边界场景示例（示例 10–24）：参数缺失、模式冲突、数值无效、模糊并行度、执行失败/结果为空重试等，需定向检索
• 常规正向场景示例（示例 0–9）：标准命令构建，参数从用户表述直接提取，按需参考

详见 references/examples-guide.md。