SuperAPI AI 工具集

modernize-map

编程与开发

查看项目

更新于 11-10 16:23

技能介绍

用途

该技能在已有领域评估的基础上再深入一层,回答“系统各部件如何连接”:依赖关系、数据流、入口点和业务流程,并生成一张可供工程师动手修改前参考的交互地图。

主要能力

  • 读取已有的依赖导出文件(--graph <file>,如编译器索引、MSBuild/Roslyn 图、NDepend、jdeps 导出、JSON/CSV/DOT/GraphML 调用图),将其节点和边映射进 topology.json,并抽样约十条边与源码核对。
  • 若本栈自带工具已安装,可运行并读取其机器可读输出(jdeps、Maven/Gradle 依赖报告、.NET 项目图、madge、dependency-cruiser、pydeps、go list -deps、cargo metadata)。
  • 否则编写一次性脚本(extract_topology.py 或 .sh)解析代码,提取:直接调用与分发器调用、经由配置联接的数据依赖、来自部署配置的入口点、死端候选(存在未解析动态调用时记为 observations),并对固定列源码(COBOL 8–72 列、RPG)先切片去注释行。
  • 超大约 2000 个源文件或 50 万行的大型系统按块(一个领域或顶层目录)处理,写入 analysis/$system/map/<chunk>.json,重跑跳过已存在块,最后合并为 topology.json。
  • 输出符合给定 schema 的 topology.json,含 system、root 树、edges(call/dispatch/read/write)、entryPoints、deadEnds、observations(3–7 条架构观察)、flows(2–4 条锚定非维护者角色的端到端业务流)。
  • 可选为叶子节点生成描述(55–90 词),超过 40 个节点时先用弹窗询问(全部、最大 40 个或不做;无弹窗时默认最大 40 个),以约 8 个为一批并行调用 legacy-analyst 子代理,返回文本后合并,并核对数字和名称均在包内。
  • 基于插件自带模板渲染 analysis/$system/TOPOLOGY.html:可缩放 circle-pack(领域为容器、模块按 LOC 定大小)、依赖边、搜索、节点侧栏、边类型开关、业务流回放;查看器自包含、可离线使用。
  • 另写小型 Mermaid 文件:call-graph.mmd、data-lineage.mmd、critical-path.mmd(每个约 40 条边以内,过密则收缩到领域级)。
  • 结尾刷新报告(build_report.py 为便利步骤,失败或缺 python3 时说明并继续)。

使用方式

代码位于 legacy/$system(常为符号链接),开始前先用 readlink 说明其指向;若不存在则停止,并提示改用 /code-modernization:modernize $system --source <path>。子代理在前台运行并等待结果。拓扑数据注入 HTML 的 script 块前需转义 <、>、& 以防止标签闭合逃逸。完成后提示用户打开 TOPOLOGY.html,尝试搜索模块、点击查看连接与描述、选择角色业务流;下一步为 /code-modernization:modernize-extract-rules $system。

适用场景与限制

适用于遗留系统现代化前的结构摸底、依赖梳理与数据血缘分析。大型代码库需分块运行;无源码时无法执行;死端判定需在全部入口与边类型入图后才可信,动态调用目标无法解析时只记录观察;数据存储标识不得包含凭据;未提供时长的遥测(p50/p99)仅在 assess 已采集时才写入 critical-path。