SuperAPI AI 工具集

modernize-preflight

编程与开发

查看项目

更新于 11-10 16:24

技能介绍

modernize-preflight 是一个代码现代化流程中的前置检查技能,用于判断当前环境是否能够分析并最终现代化指定系统($system),并在其它命令遇到问题之前,明确告诉用户需要先修复什么。资料指出,若跳过此检查,现代化工作往往会在后期以混乱的方式失败:缺少分析工具会导致指标静默退化,缺少构建工具链会导致测试无法运行,源码不完整会导致依赖图错误。

用途与设计原则

该技能强调一次性给出完整的就绪报告,而不是遇到第一个错误就停止。因此它要求即使某项早期检查失败,也要继续运行所有检查。它假定代码位于 legacy/$system:这可能是副本,也可能是指向代码真实位置的符号链接,且从不为用户复制代码。若 $ARGUMENTS 包含 --source <path>(绝对或相对目录),技能会检查该路径存在、不是文件系统根目录或用户主目录,然后仅在 legacy/$system 尚不存在时创建链接(Windows 上使用 junction)。若 legacy/$system 已存在且指向别处,则只说明情况、不做更改。技能明确规定:绝不修改 legacy/$system 下的任何内容。

检查项

Check 0 — 询问人类:通过 ask_question 弹窗(而非聊天文本)提出且仅提出五个问题:代码范围(完整系统还是更大代码库的一个切片,外部依赖与破坏消费者是否可接受)、本地构建与测试能力及 CI 流水线大致耗时、是否存在组织特有的构建或依赖机制及其文档位置、是否有人尝试过现代化及失败原因、本轮中不允许修改的内容。每个问题需提供选项(含「不知道」),允许自由输入。答案需原文写入 PREFLIGHT.md 的 Answers 节,不转述、不省略限定条件;未回答的问题记录为待人工填写的开放项。弹窗打开期间可并行执行其它检查。

Check 1 — 检测栈:依据文件扩展名和清单文件指纹识别语言、构建系统、部署与配置描述符,并报告粗略文件分布。

Check 2 — 分析工具:检查 scc(或 cloc)、python3(3.8 及以上,Windows 上可能是 python 或 py -3)、lizard 的可用性、版本以及缺失时的影响,并提供各平台的安装一行命令。

Check 3 — 构建工具链:先查看构建定义(CI 或流水线定义如 azure-pipelines.yml、Jenkinsfile、.github/workflows/、.gitlab-ci.yml、build JCL procs、Makefile,以及源码上方的构建配置),引用固定版本与依赖来源,标记一切非标准机制。随后进行分级冒烟测试:Level 1 对任一栈做单文件语法编译;Level 2 对有构建系统的栈,按 CI 的方式恢复并构建一个完整的小项目。冒烟测试失败被视为该命令最有价值的输出,需报告实际错误并诊断原因。若给出了 $target_stack,需在 legacy/$system 之外的临时目录中用其真实包管理器和测试框架创建最小项目、恢复、构建、运行一个通过的测试,然后删除;无法在本地构建的目标本身即是一项发现。

Check 4 — 源码完整性:查找被引用但缺失的 include(copybook、头文件、导入)、部署与配置描述符(JCL、CICS CSD、web.xml 或路由配置、cron 与调度器定义)、数据定义(DDL、schema、记录布局、ORM 映射)以及仅有二进制而无源码的产物。

Check 5 — 可选上下文:是否有 APM MCP 服务器连接或批量日志与运行时导出可用(用于 assess 的运行时叠加);legacy/$system 是否在 git 下并有真实历史(变更频率可强化风险排序)。

Check 6 — 范围边界:解析符号链接后,查找 legacy/$system 之上的仓库、解决方案或反应堆根,以及内部伸向外部的清单或 include。若是,需双向报告:出站(内部依赖外部源码,map 与 delta catalog 会静默遗漏)与入站(外部依赖内部,即影响半径,就地迁移会破坏每个外部消费者,需明确决策:过渡期保持新旧消费者均可构建、扩大范围包含消费者、或计划中断)。若 $system 是独立仓库,一行说明即可。

Check 7 — 源码是否受编辑保护:只读检查项目与用户的 .agents/settings.json、.claude/settings.local.json 中的 permissions.deny 列表,查找覆盖 legacy/ 下所有内容的 replace_file_content 规则;若 legacy/$system 是符号链接,规则还须覆盖链接的真实目标。只报告规则所在文件与规则本身,不引用其它内容。状态只能是 ✅ 或 ⚠️,不改变任何命令的判定。⚠️ 时给出建议的项目 .agents/settings.json 片段。资料同时提示:权限规则只覆盖特定文件工具与可识别的 shell 命令,硬性保证来自操作系统(只读挂载或阻止 shell 写入的沙箱)。

输出与判定

技能将结果写入 analysis/$system/PREFLIGHT.md,以 Answers 节和 Check 6 发现开头,因为下游命令(尤其是 brief)会读取这两项。随后是每个检查一行的表格(✅/⚠️/❌、发现内容及修复建议),再给出各命令的 Ready / Ready-with-gaps / Not ready 判定:assess、map、extract-rules 需 Check 1–2 大体为绿且缺失 include 少;brief 只需发现类产物(同栈升级还需 DELTA_CATALOG.md),无需工具;transform、reimagine 还需目标栈的 Check 3 为绿,遗留工具链为红属于 Ready-with-gaps 而非 Not-ready,等价性将回退到记录轨迹;harden 需 Check 2 及发现的栈相关 SAST 工具;uplift 需目标版本的 Check 3 为绿,并在看起来是版本升级时考虑源运行时是否存在、生态迁移工具是否安装、Check 6 是否发现入站消费者。表格也会打印在会话中,最后给出最重要的一项修复建议与下一步命令 /code-modernization:modernize-assess $system。