尧图网站建设 
如果你维护过超过 50 个类的业务项目大概率经历过这样的场景架构评审前通宵改 PPT 里的架构图一边改一边发现“这个类上周明明删了图里怎么还在”或者接手旧项目时想看类之间的关系打开 IDE 的继承关系面板面对密密麻麻的线和箭头根本看不出业务模块边界。这类问题的本质不是“画图能力”不够而是“图和代码严重脱节”。图是文档代码是事实文档一旦落后于事实就会变成误导。更麻烦的是很多团队把画类图、画流程图当成纯手工活类库结构改完了流程图没人同步更新最后图只存在于第一次评审的会议纪要里。这篇文章要聊的就是怎么用 AI 和自动化脚本把“维护类库结构”和“绘制流程图”这两件事从手工劳动变成半自动甚至全自动任务。核心思路只有一句话让代码成为图表的唯一数据源让 AI 负责把代码翻译成图和文档。读完这篇文章你会得到一套可以直接跑起来的最小工程一个用 Python AST 扫描代码生成类依赖关系的脚本一个把依赖关系渲染成类图的渲染链路以及一套让 AI 根据项目上下文生成业务流程图的工作流。你可以把它直接接入到自己的项目里解决“图与代码不同步”的问题。1. 这篇文章真正要解决的问题先说你最关心的AI 自动生成流程图和类库节点到底能省下什么很多人第一反应是“省画图时间”。这个判断不够准确。如果只是画图Draw.io、ProcessOn、Visio 已经足够快手动画一张 20 个节点的流程图也就半小时。真正贵的不是第一次画图而是后续的维护。业务系统是持续变化的。今天加一个订单状态明天拆一个支付服务后天把用户模块重构掉。每次代码变化类图就要动一次流程图就要改一遍。这种“持续同步”的成本远高于“第一次画图”的成本。大多数团队的图之所以过时就是因为没人愿意承担这个持续成本。所以这篇文章要解决的核心问题有两个代码类库结构变化后如何快速更新类图和依赖图业务逻辑复杂到很难用文字讲清楚时如何让 AI 辅助输出准确的流程图这两个问题分别对应两条技术路径代码侧用 Python AST 扫描源码自动提取类、方法、依赖关系再通过 Mermaid 或 PlantUML 渲染成图。文档侧把代码结构、注释、接口定义喂给大模型让 AI 先生成结构化描述再转换成流程图而不是让 AI 直接凭空画图。这两条路径合在一起就是“AI 自动生成类库节点、流程图”的完整实践。它不是要取代架构师的设计能力而是把重复劳动交给脚本和大模型让人把精力放在判断和决策上。什么样的读者最适合读这篇一类是被“图文档维护”折磨的后端开发和技术负责人一类是需要在技术方案里频繁画架构图、时序图、流程图的开发者还有一类是刚接触 AI 编程、想知道大模型在“代码可视化”方向上到底能干什么的新手。2. 核心概念类库节点、流程图和 AI 生成的本质2.1 类库节点到底是什么“节点”这个词在不同场景下含义差别很大。在本文的场景里类库节点指的是类依赖图中的一个元素它可以是一个类、一个接口、一个抽象类、一个包也可以是一个微服务模块。比如一个订单系统可能有User、Order、Payment这些类。它们之间通过继承、组合、方法参数、返回值产生关联。把这些类和关联画出来就是一张类图。类图中的每一个方框就是“节点”每一条连线就是“边”。在低代码平台或者工作流引擎里节点又指流程中的一个步骤比如“发起审批”“调用接口”“条件判断”。这种节点和类库节点的区别在于前者描述的是运行时行为后者描述的是静态代码结构。本文两种都会涉及类图解决静态结构可视化流程图解决业务行为可视化。2.2 流程图的价值在于“发现结构”流程图不是画得好看就有用它的价值在于帮人快速理解一个过程的完整路径。比如一个退款流程从用户发起申请到风控校验到原路退回到通知用户中间可能有 6 到 8 个节点。如果只用文字描述很容易漏掉异常分支。画成流程图漏分支的情况会明显减少。但流程图也有一个致命问题如果图里的流程和真实代码里的流程不一致它就会误导人。很多团队画的“业务流程图”其实和代码实现是两套东西——流程图描述的是理想设计代码实现的是真实逻辑。AI 能帮上忙的地方恰恰是把“真实逻辑”转换成“可视化的图”而不是再画一张理想化设计图。2.3 AI 自动生成的三个层次这里需要澄清一个误区AI 生成图并不是让 AI 直接用画布工具一笔一笔画。更常见的做法有三个层次层次做法适用场景自动化程度第一层AI 根据代码或需求文本输出 Mermaid / PlantUML / DOT 文本快速出草图、文档插图高第二层脚本解析代码生成结构化 JSON再按模板渲染成图类图、依赖图、架构图最高第三层AI 先输出结构化 JSON再由渲染器生成图业务流程图、状态机中高这里真正重要的判断是AI 不擅长精确画图但擅长把非结构化信息转换成结构化描述。所以正确的姿势是让 AI 输出结构化的图描述语言或者输出节点和连线的 JSON然后用专门工具渲染。这样即使 AI 输出的内容不够完美也方便人工修改而且修改成本远低于重画。3. 环境准备与前置条件这套工作流涉及代码扫描、图渲染和 AI 调用三部分。下面给出最小环境建议版本以实际安装为准本文重点演示通用思路。3.1 基础环境操作系统Windows / macOS / Linux 均可示例命令以 Linux/macOS 风格为主。Python3.9 或以上主要用标准库ast做代码解析不需要额外安装第三方依赖。Node.js16 或以上用于运行 Mermaid CLI 渲染工具。Java11 或以上PlantUML 可选使用。3.2 依赖安装Mermaid 渲染需要安装mermaid-js/mermaid-cli它本质上是 Puppeteer 调用浏览器渲染图表所以首次运行会下载 Chromium网络环境需要能正常访问 npm 仓库。npm install -g mermaid-js/mermaid-cliPlantUML 方式需要下载 plantuml.jar 和 Graphviz。如果你已经有 Java 环境PlantUML 是备选方案不是必须。# 可选PlantUML 方式 wget https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jarAI 调用部分本文不绑定具体厂商。你可以选择任何支持对话补全的大模型 API也可以在本地部署开源模型。为了安全和隐私如果项目代码属于公司内部资产建议优先使用公司内部的私有化模型服务不要把核心代码直接粘贴到公网模型的对话窗口里。3.3 目录结构规划为了演示清晰我设计一个最小示例项目project/ ├── app/ │ ├── models/ │ │ ├── __init__.py │ │ ├── user.py │ │ └── order.py │ ├── services/ │ │ ├── __init__.py │ │ ├── user_service.py │ │ └── order_service.py │ └── main.py ├── scripts/ │ ├── scan_class_deps.py │ └── generate_class_diagram.py ├── docs/ │ ├── class_diagram.mmd │ └── class_diagram.png └── README.md这个结构不算大但足够演示“扫描代码 - 生成依赖 JSON - 渲染类图”的完整链路。4. 生成类库节点与类图的核心流程拆解先说整体流程再给代码。4.1 流程总览整个自动生成类图分为四步用 Python 的ast模块解析目标目录下的所有.py文件。提取每个文件中的类名、方法名、继承关系以及方法参数和返回值里引用的其他类。把提取结果整理成class_deps.json作为中间结构。读取 JSON按模板生成 Mermaid 的classDiagram语法文本再调用mmdc渲染成 PNG。为什么要有中间 JSON 这一步因为如果 AI 或者后续工具要介入统一操作 JSON 比直接改图代码要容易得多。人也可以直接打开 JSON 检查依赖关系对不对改完再重新生成图。4.2 用 AST 解析代码结构Python 的ast是标准库不需要额外安装。它的作用是把 Python 源码解析成抽象语法树然后我们可以遍历树节点找出ClassDef和FunctionDef。这里已经出现第一个坑AST 只能解析语法层面的依赖解析不了动态调用。比如一个方法里obj get_obj()然后obj.call()AST 看不出obj是什么类型。所以这种工具适合生成“静态结构图”不适合生成“调用链图”。在实际项目中静态结构图已经足够解决大多数文档问题。4.3 从 JSON 到图描述语言有了 JSON 之后生成 Mermaid 图代码就是纯粹的模板拼接。每一对“类 A 依赖类 B”的关系对应 Mermaid 里的一行A -- B。继承关系用|--表示。这里要控制节点数量。如果一个项目有几百个类全画出来会变成一团乱麻。合理的做法是只画指定包或者指定层级的类或者只显示public方法、核心字段避免“节点爆炸”。这是一个非常容易踩坑的地方。4.4 流程图让 AI 先生成结构化描述类图是代码侧自动生成的典型场景。对于业务流程图代码结构往往不能直接反映业务流程需要结合注释、需求文档和接口定义来理解。这时候 AI 的价值更大。推荐的 pattern 是不给 AI 一个空白的“请你画图”指令而是提供足够的上下文并让它输出 JSON 而不是直接画 Mermaid 图。比如给它一段接口代码和注释让它提取“节点列表”和“连线列表”然后再由渲染脚本把 JSON 转成 Mermaid。这样做的优势是JSON 便于修改、便于版本对比也便于嵌套到自己的文档流水线里。5. 完整示例代码实现下面给出可以直接运行的代码。示例用的是 Python 和 Node.js 混合方式核心逻辑集中在两个 Python 脚本和一个 shell 渲染脚本里。5.1 示例源码一个简单电商模块先准备一个极简的源码目录方便扫描脚本展示效果。# 文件路径app/models/user.py class User: def __init__(self, user_id: int, name: str): self.user_id user_id self.name name def get_display_name(self) - str: return self.name# 文件路径app/models/order.py class Order: def __init__(self, order_id: str, user_id: int, amount: float): self.order_id order_id self.user_id user_id self.amount amount def get_order_info(self) - dict: return {order_id: self.order_id, amount: self.amount}# 文件路径app/services/user_service.py from app.models.user import User class UserService: def create_user(self, user_id: int, name: str) - User: return User(user_id, name) def get_user(self, user_id: int) - User: # 简化逻辑实际项目中这里会查询数据库 return User(user_id, demo)# 文件路径app/services/order_service.py from app.models.order import Order from app.services.user_service import UserService class OrderService: def __init__(self): self.user_service UserService() def create_order(self, user_id: int, amount: float) - Order: user self.user_service.get_user(user_id) order_id fORDER_{user.user_id}_{amount} return Order(order_id, user.user_id, amount)这个示例虽然简单但类与类之间的关系已经足够体现UserService依赖UserOrderService依赖UserService和Order。5.2 扫描脚本提取类、方法和依赖# 文件路径scripts/scan_class_deps.py import ast import json import os import sys from collections import defaultdict def get_imported_names(tree): 收集当前文件里 import 进来的名字用于判断类型归属。 imported {} for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: local_name alias.asname or alias.name.split(.)[0] imported[local_name] alias.name elif isinstance(node, ast.ImportFrom): module node.module or for alias in node.names: local_name alias.asname or alias.name imported[local_name] f{module}.{alias.name} return imported def extract_class_info(file_path, tree): 提取单个文件中的类信息。 imported get_imported_names(tree) class_info {} for node in ast.walk(tree): if not isinstance(node, ast.ClassDef): continue deps set() bases [] methods [] # 父类 for base in node.bases: if isinstance(base, ast.Name): bases.append(base.id) if base.id in imported: deps.add(imported[base.id]) else: deps.add(base.id) # 方法和方法中的类型标注 for item in node.body: if isinstance(item, ast.FunctionDef): methods.append(item.name) all_args list(item.args.args) list(item.args.kwonlyargs) for arg in all_args: if arg.annotation and isinstance(arg.annotation, ast.Name): deps.add(arg.annotation.id) if item.returns and isinstance(item.returns, ast.Name): deps.add(item.returns.id) class_info[node.name] { file: file_path, bases: bases, methods: methods, deps: sorted(deps), } return class_info def scan_directory(source_dir): 递归扫描目录下所有 .py 文件。 result {} for root, _, files in os.walk(source_dir): for file_name in files: if not file_name.endswith(.py): continue file_path os.path.join(root, file_name) with open(file_path, r, encodingutf-8) as f: source f.read() try: tree ast.parse(source) except SyntaxError as e: print(f跳过 {file_path}: 语法错误 {e}) continue info extract_class_info(file_path, tree) if info: result.update(info) return result def main(): source_dir sys.argv[1] if len(sys.argv) 1 else app output sys.argv[2] if len(sys.argv) 2 else docs/class_deps.json os.makedirs(os.path.dirname(output), exist_okTrue) scan_result scan_directory(source_dir) # 统一成 {class_name: {deps: []}} 格式方便后续渲染 simple_result {} for class_name, info in scan_result.items(): simple_result[class_name] { file: info[file], bases: info[bases], methods: info[methods], deps: info[deps], } with open(output, w, encodingutf-8) as f: json.dump(simple_result, f, ensure_asciiFalse, indent2) print(f扫描完成共发现 {len(simple_result)} 个类结果已写入 {output}) if __name__ __main__: main()这段脚本有两个关键点get_imported_names是为了把from app.models.user import User这种导入映射成app.models.user.User这样依赖关系能看出业务模块边界。类型标注里ast.Name才能拿到类名如果是list[str]这种下标类型需要额外处理但示例足够说明原理。5.3 生成 Mermaid 类图脚本# 文件路径scripts/generate_class_diagram.py import json import os import sys def load_deps(json_path): with open(json_path, r, encodingutf-8) as f: return json.load(f) def generate_mermaid_class_diagram(deps): lines [] lines.append(classDiagram) # 先声明所有类节点 for class_name in deps: lines.append(f class {class_name}) # 继承关系 for class_name, info in deps.items(): for base in info.get(bases, []): lines.append(f {base} |-- {class_name}) # 依赖关系 for class_name, info in deps.items(): for dep in info.get(deps, []): if dep class_name: continue # 避免重复输出 edge f {class_name} -- {dep} if edge not in lines: lines.append(edge) return \n.join(lines) def main(): json_path sys.argv[1] if len(sys.argv) 1 else docs/class_deps.json output_path sys.argv[2] if len(sys.argv) 2 else docs/class_diagram.mmd deps load_deps(json_path) mermaid_code generate_mermaid_class_diagram(deps) os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: f.write(mermaid_code) print(f类图代码已生成: {output_path}) print(mermaid_code) if __name__ __main__: main()这一步生成的.mmd文件就是 Mermaid 的文本语言。它既可以直接被 GitHub 渲染也可以通过 CLI 转成图片。5.4 渲染脚本把.mmd转成 PNG#!/usr/bin/env bash # 文件路径scripts/render_mermaid.sh set -euo pipefail INPUT_FILE${1:-docs/class_diagram.mmd} OUTPUT_FILE${2:-docs/class_diagram.png} if ! command -v mmdc /dev/null; then echo 未找到 mmdc请先执行: npm install -g mermaid-js/mermaid-cli exit 1 fi mkdir -p $(dirname $OUTPUT_FILE) mmdc \ -i $INPUT_FILE \ -o $OUTPUT_FILE \ -b white \ --width 1200 echo 渲染完成: $OUTPUT_FILE如果你不想用 Node.js 环境也可以把generate_class_diagram.py改成输出 PlantUML 格式然后用 Java Graphviz 渲染。Mermaid 的好处是生态广GitHub 原生支持团队协作时可以直接在 PR 里看到图的变化。5.5 让 AI 生成流程图 JSON 的示例类图已经打通了接下来是业务流程图。这里用一个 prompt 示例告诉你怎么让 AI 输出结构化 JSON而不是直接画图。假设你有这样一段业务描述用户下单后系统先校验库存如果库存不足返回失败如果库存充足创建订单并扣减库存然后调用支付接口支付成功后发送通知支付失败则回滚库存。你可以把这个需求描述发给大模型并在 prompt 中明确要求请把下面的业务过程拆解为流程图节点和连线只输出 JSON不要输出任何解释。 JSON 格式要求如下 { nodes: [ {id: 1, label: 用户下单, type: start}, {id: 2, label: 校验库存, type: condition} ], edges: [ {from: 1, to: 2, label: } ] } 业务过程用户下单后系统先校验库存如果库存不足返回失败如果库存充足创建订单并扣减库存然后调用支付接口支付成功后发送通知支付失败则回滚库存。得到 JSON 后再用一个简单的渲染脚本转成 Mermaid# 文件路径scripts/flow_json_to_mermaid.py import json import sys def convert_to_mermaid_flowchart(data): lines [] lines.append(flowchart TD) for node in data.get(nodes, []): node_id node[id] label node.get(label, node_id) shape [ if node.get(type) ! condition else { close ] if shape [ else } lines.append(f {node_id}{shape}{label}{close}) for edge in data.get(edges, []): label edge.get(label, ) if label: lines.append(f {edge[from]} --|{label}| {edge[to]}) else: lines.append(f {edge[from]} -- {edge[to]}) return \n.join(lines) def main(): input_path sys.argv[1] if len(sys.argv) 1 else docs/flow.json output_path sys.argv[2] if len(sys.argv) 2 else docs/flow.mmd with open(input_path, r, encodingutf-8) as f: data json.load(f) mmd convert_to_mermaid_flowchart(data) with open(output_path, w, encodingutf-8) as f: f.write(mmd) print(mmd) if __name__ __main__: main()这个脚本的价值在于把 AI 的输出规范到固定格式让流程图渲染这件事不再依赖 AI 的“临场发挥”。6. 运行结果与效果验证6.1 生成类依赖 JSON在项目根目录执行python scripts/scan_class_deps.py app docs/class_deps.json正常情况下终端输出扫描完成共发现 4 个类结果已写入 docs/class_deps.json打开docs/class_deps.json内容类似{ Order: { file: app/models/order.py, bases: [], methods: [get_order_info], deps: [] }, OrderService: { file: app/services/order_service.py, bases: [], methods: [create_order], deps: [app.services.user_service.UserService, app.models.order.Order] }, User: { file: app/models/user.py, bases: [], methods: [get_display_name], deps: [] }, UserService: { file: app/services/user_service.py, bases: [], methods: [create_user, get_user], deps: [app.models.user.User] } }验证这一步的关键点OrderService的依赖里同时出现了UserService和Order说明 type annotation 和 return annotation 都被正确识别了。如果你的类之间是通过构造方法注入的可能还需要额外处理__init__方法里的赋值语句但 AST 的基本思路不变。6.2 生成 Mermaid 类图文本python scripts/generate_class_diagram.py docs/class_deps.json docs/class_diagram.mmd生成的.mmd文件内容大概是这样classDiagram class Order class OrderService class User class UserService UserService |-- OrderService OrderService -- app.services.user_service.UserService OrderService -- app.models.order.Order UserService -- app.models.user.User这里注意一个细节UserService |-- OrderService这行其实是错误的因为示例里OrderService并没有继承UserService只是在构造方法里组合了它。这是因为扫描脚本暂时把“类名出现在另一个类的方法体里”也归为依赖了。在实际使用中你需要判断父类关系用继承边方法参数和返回值用依赖边构造方法注入属于组合关系。三者的语义不同最好分开输出。6.3 渲染 PNGbash scripts/render_mermaid.sh docs/class_diagram.mmd docs/class_diagram.png成功后会看到docs/class_diagram.png生成。打开图片应该能看到 4 个类节点以及它们之间的连线。如果渲染失败优先检查mmdc是否安装成功。首次运行是否下载 Chromium 失败。.mmd文件里的类名是否包含空格或特殊字符。6.4 验证 AI 流程图的输出把包含 JSON 的回答保存为docs/flow.json然后执行python scripts/flow_json_to_mermaid.py docs/flow.json docs/flow.mmd如果 AI 输出的 JSON 结构合法你会得到一份 Mermaid 的flowchart TD文本。再调用mmdc渲染成 PNG就能直接用在文档里。7. 常见问题与排查思路问题现象可能原因排查方式解决方案扫描脚本报SyntaxError源码包含 Python 2 语法或动态执行代码查看具体报错文件和行号在解析前过滤掉不兼容文件或者改用ast.parse时捕获异常并跳过生成的类图缺少某些类之间的连线AST 只能解析静态类型识别不了动态类型检查该依赖是否来自getattr、eval、反射调用在脚本里加入手动补充配置比如manual_deps字典类太多生成的图成为“蜘蛛网”全部节点一次性渲染没有做层级过滤检查 JSON 中的类数量增加--include-packages参数只渲染指定包下的类渲染 PNG 时中文乱码Mermaid 默认字体不支持中文字符查看浏览器控制台或 mmdc 日志配置puppeteerConfigFile指定系统中文字体AI 生成的 JSON 不符合格式Prompt 里没有给严格的 schema 示例检查大模型输出中是否夹杂解释文本在 prompt 中强调“只输出 JSON”并在代码里增加格式校验mmdc命令找不到Node.js 全局环境未配置执行npm ls -g mermaid-js/mermaid-cli重新执行全局安装或改用npx mmdc类名带泛型或内部类Mermaid 渲染失败类名包含等特殊符号检查.mmd文件具体报错位置对类名做转义或重命名这里我想重点说两个容易踩的坑第一个是AST 的静态局限。如果你的业务代码大量使用了property、__getattr__、functools.lru_cache这样的装饰器AST 看到的只是装饰器表达式看不到运行时的依赖关系。所以这类工具定位应该是“辅助文档生成”而不是“精确的运行时分析”。要精确分析运行时对象关系应该用sys.setprofile、coverage或者pytest的插桩方式但那是另一个话题了。第二个是不要让 AI 直接把流程图代码写死。AI 生成 Mermaid 图代码时经常会出现节点 id 不统一、连线指向不存在的节点、条件分支缺少汇聚节点等问题。更稳妥的做法是先让它输出 JSON用脚本校验后再渲染。这样即使 AI 出错错误也是可定位的而不是隐藏在图形中的一个错位箭头。8. 最佳实践与工程建议8.1 图和代码同源但要人审最重要的一条原则图不是独立存在的文档它是代码的可视化投影。代码改了图就应该重新生成。所以建议把扫描脚本和生成脚本放进项目根目录并提供一个Makefile或者 npm script一键更新所有图表。但“自动生成”不代表“无人审核”。类图能反映代码结构却反映不了代码设计是否合理。比如一个类依赖了十几个其他类图会清楚地把它画出来但要不要重构、怎么拆分仍然需要人做判断。AI 和脚本的价值是把事实摆到眼前决策依然是人来做。8.2 控制节点粒度避免大爆炸图实际项目中一个模块可能包含 200 个类。如果全部渲染生成的图没有人能看懂。更合理的做法是分层展示包层级图只展示包和包之间的依赖粒度最粗。核心类图只展示models、services、controllers里的核心类过滤掉 DTO、VO、工具类。变更影响图在重构时只看本次变更涉及的类以及它们直接依赖的类。控制粒度的实现方式可以在扫描脚本里增加黑白名单# 在 scan_class_deps.py 中添加过滤逻辑 INCLUDE_PACKAGES [app.models, app.services] EXCLUDE_CLASSES {BaseModel, MixinA, MixinB} def should_include(class_name, file_path): if class_name in EXCLUDE_CLASSES: return False return any(pkg in file_path for pkg in INCLUDE_PACKAGES)8.3 用命名规范辅助 AI 理解代码AI 生成流程图时对类名、方法名、注释的质量非常敏感。如果方法都叫process、handle、doSomethingAI 很难从方法名推断出业务含义。反过来如果方法名是validateStockAndCreateOrder、rollbackInventory、notifyPaymentResultAI 几乎不需要额外解释就能画出准确的流程。所以从工程角度看让 AI 生成好文档的前提是代码本身有清晰的命名和注释。这不只是给 AI 看的也是给人看的。如果你准备在团队里推广这套工作流建议先从统一命名规范开始。8.4 流程图的“生成 JSON - 渲染”模式无论是 AI 生成流程图还是脚本生成类图尽量让中间产物是 JSON 或者结构化配置而不是直接生成最终图片。原因有三个JSON 可以 diff方便在 code review 中看到流程图的变化。JSON 可以复用同一个结构可以渲染成 Mermaid、PlantUML、DOT甚至表格。JSON 便于人工修改和合并AI 生成的 JSON 即使不完美也比从头改图代码要快。这意味着你的渲染逻辑应该和数据结构解耦。先定义好“节点 连线”的数据结构再分别实现不同渲染器的适配。8.5 注意代码安全与权限边界如果你把自己的业务代码作为 prompt 发送给公网大模型需要格外谨慎。规范的做法是涉及核心业务逻辑的源码优先使用私有化部署的模型或企业版 API。发送给模型之前进行脱敏处理类名、方法名可以保留但数据库连接串、密钥、客户信息必须去掉。在团队协作中把“代码转图”做成内部工具而不是让每个人都去调公网接口。8.6 把图表生成接入 CI更进一步你可以在 CI 里增加一个图表生成任务。每次合并代码后重新扫描代码并生成类图如果类图发生变化就把新的 PNG 提交到文档仓库或者在 PR 里创建一条评论贴上 diff 后的图表。这个做法看起来简单但效果很好。它逼着开发者一改代码就看到结构变化图的时效性不再是靠个人自觉而是靠流水线保证。9. 总结与后续学习方向这篇文章围绕“AI 自动生成类库节点、流程图”展开核心结论可以归纳为三条第一用 Python AST 扫描代码、用 JSON 作为中间格式、用 Mermaid 渲染可以低成本地把“维护类图”变成“代码提交后的自动任务”。这套链路不依赖任何重型框架核心代码不到 200 行。第二AI 在生成流程图时真正有价值的不是直接出图而是把需求文本、代码注释、接口定义转换成结构化的节点和连线 JSON。通过flow_json_to_mermaid.py这样的脚本可以让 AI 的输出直接进入渲染流程同时保留人工修改和 diff 的能力。第三这类工具解决的是“同步成本”问题而不是“设计能力”问题。它不能让烂代码变好也不能替代架构师的分析但它能让图和代码永远保持一致避免团队被过时文档误导。如果你想把这套方案用于自己的项目建议按这个顺序实践先跑通scan_class_deps.py和generate_class_diagram.py拿到自己项目的类图。再选一个核心业务流程用 AI 生成 JSON 流程图跑通flow_json_to_mermaid.py。最后把脚本接入 CI让每次代码变更都自动更新图表。后续可以深入的方向包括用tree-sitter解析 Java、Go、TypeScript 代码用大模型语义分析自动生成架构决策记录把生成的图嵌入 Confluence、语雀或者内部文档平台以及在 Mermaid 基础上叠加交互能力让节点可以点击跳转到源码文件。建议先把这篇文章里提供的最小工程跑一遍再考虑扩展。等真正用起来之后你会发现“手写类库、手动画图”这件事确实可以成为历史了。 AI自动生成类库节点与流程图：让代码与图表同步的实践
如果你维护过超过 50 个类的业务项目大概率经历过这样的场景架构评审前通宵改 PPT 里的架构图一边改一边发现“这个类上周明明删了图里怎么还在”或者接手旧项目时想看类之间的关系打开 IDE 的继承关系面板面对密密麻麻的线和箭头根本看不出业务模块边界。这类问题的本质不是“画图能力”不够而是“图和代码严重脱节”。图是文档代码是事实文档一旦落后于事实就会变成误导。更麻烦的是很多团队把画类图、画流程图当成纯手工活类库结构改完了流程图没人同步更新最后图只存在于第一次评审的会议纪要里。这篇文章要聊的就是怎么用 AI 和自动化脚本把“维护类库结构”和“绘制流程图”这两件事从手工劳动变成半自动甚至全自动任务。核心思路只有一句话让代码成为图表的唯一数据源让 AI 负责把代码翻译成图和文档。读完这篇文章你会得到一套可以直接跑起来的最小工程一个用 Python AST 扫描代码生成类依赖关系的脚本一个把依赖关系渲染成类图的渲染链路以及一套让 AI 根据项目上下文生成业务流程图的工作流。你可以把它直接接入到自己的项目里解决“图与代码不同步”的问题。1. 这篇文章真正要解决的问题先说你最关心的AI 自动生成流程图和类库节点到底能省下什么很多人第一反应是“省画图时间”。这个判断不够准确。如果只是画图Draw.io、ProcessOn、Visio 已经足够快手动画一张 20 个节点的流程图也就半小时。真正贵的不是第一次画图而是后续的维护。业务系统是持续变化的。今天加一个订单状态明天拆一个支付服务后天把用户模块重构掉。每次代码变化类图就要动一次流程图就要改一遍。这种“持续同步”的成本远高于“第一次画图”的成本。大多数团队的图之所以过时就是因为没人愿意承担这个持续成本。所以这篇文章要解决的核心问题有两个代码类库结构变化后如何快速更新类图和依赖图业务逻辑复杂到很难用文字讲清楚时如何让 AI 辅助输出准确的流程图这两个问题分别对应两条技术路径代码侧用 Python AST 扫描源码自动提取类、方法、依赖关系再通过 Mermaid 或 PlantUML 渲染成图。文档侧把代码结构、注释、接口定义喂给大模型让 AI 先生成结构化描述再转换成流程图而不是让 AI 直接凭空画图。这两条路径合在一起就是“AI 自动生成类库节点、流程图”的完整实践。它不是要取代架构师的设计能力而是把重复劳动交给脚本和大模型让人把精力放在判断和决策上。什么样的读者最适合读这篇一类是被“图文档维护”折磨的后端开发和技术负责人一类是需要在技术方案里频繁画架构图、时序图、流程图的开发者还有一类是刚接触 AI 编程、想知道大模型在“代码可视化”方向上到底能干什么的新手。2. 核心概念类库节点、流程图和 AI 生成的本质2.1 类库节点到底是什么“节点”这个词在不同场景下含义差别很大。在本文的场景里类库节点指的是类依赖图中的一个元素它可以是一个类、一个接口、一个抽象类、一个包也可以是一个微服务模块。比如一个订单系统可能有User、Order、Payment这些类。它们之间通过继承、组合、方法参数、返回值产生关联。把这些类和关联画出来就是一张类图。类图中的每一个方框就是“节点”每一条连线就是“边”。在低代码平台或者工作流引擎里节点又指流程中的一个步骤比如“发起审批”“调用接口”“条件判断”。这种节点和类库节点的区别在于前者描述的是运行时行为后者描述的是静态代码结构。本文两种都会涉及类图解决静态结构可视化流程图解决业务行为可视化。2.2 流程图的价值在于“发现结构”流程图不是画得好看就有用它的价值在于帮人快速理解一个过程的完整路径。比如一个退款流程从用户发起申请到风控校验到原路退回到通知用户中间可能有 6 到 8 个节点。如果只用文字描述很容易漏掉异常分支。画成流程图漏分支的情况会明显减少。但流程图也有一个致命问题如果图里的流程和真实代码里的流程不一致它就会误导人。很多团队画的“业务流程图”其实和代码实现是两套东西——流程图描述的是理想设计代码实现的是真实逻辑。AI 能帮上忙的地方恰恰是把“真实逻辑”转换成“可视化的图”而不是再画一张理想化设计图。2.3 AI 自动生成的三个层次这里需要澄清一个误区AI 生成图并不是让 AI 直接用画布工具一笔一笔画。更常见的做法有三个层次层次做法适用场景自动化程度第一层AI 根据代码或需求文本输出 Mermaid / PlantUML / DOT 文本快速出草图、文档插图高第二层脚本解析代码生成结构化 JSON再按模板渲染成图类图、依赖图、架构图最高第三层AI 先输出结构化 JSON再由渲染器生成图业务流程图、状态机中高这里真正重要的判断是AI 不擅长精确画图但擅长把非结构化信息转换成结构化描述。所以正确的姿势是让 AI 输出结构化的图描述语言或者输出节点和连线的 JSON然后用专门工具渲染。这样即使 AI 输出的内容不够完美也方便人工修改而且修改成本远低于重画。3. 环境准备与前置条件这套工作流涉及代码扫描、图渲染和 AI 调用三部分。下面给出最小环境建议版本以实际安装为准本文重点演示通用思路。3.1 基础环境操作系统Windows / macOS / Linux 均可示例命令以 Linux/macOS 风格为主。Python3.9 或以上主要用标准库ast做代码解析不需要额外安装第三方依赖。Node.js16 或以上用于运行 Mermaid CLI 渲染工具。Java11 或以上PlantUML 可选使用。3.2 依赖安装Mermaid 渲染需要安装mermaid-js/mermaid-cli它本质上是 Puppeteer 调用浏览器渲染图表所以首次运行会下载 Chromium网络环境需要能正常访问 npm 仓库。npm install -g mermaid-js/mermaid-cliPlantUML 方式需要下载 plantuml.jar 和 Graphviz。如果你已经有 Java 环境PlantUML 是备选方案不是必须。# 可选PlantUML 方式 wget https://github.com/plantuml/plantuml/releases/download/v1.2024.7/plantuml-1.2024.7.jarAI 调用部分本文不绑定具体厂商。你可以选择任何支持对话补全的大模型 API也可以在本地部署开源模型。为了安全和隐私如果项目代码属于公司内部资产建议优先使用公司内部的私有化模型服务不要把核心代码直接粘贴到公网模型的对话窗口里。3.3 目录结构规划为了演示清晰我设计一个最小示例项目project/ ├── app/ │ ├── models/ │ │ ├── __init__.py │ │ ├── user.py │ │ └── order.py │ ├── services/ │ │ ├── __init__.py │ │ ├── user_service.py │ │ └── order_service.py │ └── main.py ├── scripts/ │ ├── scan_class_deps.py │ └── generate_class_diagram.py ├── docs/ │ ├── class_diagram.mmd │ └── class_diagram.png └── README.md这个结构不算大但足够演示“扫描代码 - 生成依赖 JSON - 渲染类图”的完整链路。4. 生成类库节点与类图的核心流程拆解先说整体流程再给代码。4.1 流程总览整个自动生成类图分为四步用 Python 的ast模块解析目标目录下的所有.py文件。提取每个文件中的类名、方法名、继承关系以及方法参数和返回值里引用的其他类。把提取结果整理成class_deps.json作为中间结构。读取 JSON按模板生成 Mermaid 的classDiagram语法文本再调用mmdc渲染成 PNG。为什么要有中间 JSON 这一步因为如果 AI 或者后续工具要介入统一操作 JSON 比直接改图代码要容易得多。人也可以直接打开 JSON 检查依赖关系对不对改完再重新生成图。4.2 用 AST 解析代码结构Python 的ast是标准库不需要额外安装。它的作用是把 Python 源码解析成抽象语法树然后我们可以遍历树节点找出ClassDef和FunctionDef。这里已经出现第一个坑AST 只能解析语法层面的依赖解析不了动态调用。比如一个方法里obj get_obj()然后obj.call()AST 看不出obj是什么类型。所以这种工具适合生成“静态结构图”不适合生成“调用链图”。在实际项目中静态结构图已经足够解决大多数文档问题。4.3 从 JSON 到图描述语言有了 JSON 之后生成 Mermaid 图代码就是纯粹的模板拼接。每一对“类 A 依赖类 B”的关系对应 Mermaid 里的一行A -- B。继承关系用|--表示。这里要控制节点数量。如果一个项目有几百个类全画出来会变成一团乱麻。合理的做法是只画指定包或者指定层级的类或者只显示public方法、核心字段避免“节点爆炸”。这是一个非常容易踩坑的地方。4.4 流程图让 AI 先生成结构化描述类图是代码侧自动生成的典型场景。对于业务流程图代码结构往往不能直接反映业务流程需要结合注释、需求文档和接口定义来理解。这时候 AI 的价值更大。推荐的 pattern 是不给 AI 一个空白的“请你画图”指令而是提供足够的上下文并让它输出 JSON 而不是直接画 Mermaid 图。比如给它一段接口代码和注释让它提取“节点列表”和“连线列表”然后再由渲染脚本把 JSON 转成 Mermaid。这样做的优势是JSON 便于修改、便于版本对比也便于嵌套到自己的文档流水线里。5. 完整示例代码实现下面给出可以直接运行的代码。示例用的是 Python 和 Node.js 混合方式核心逻辑集中在两个 Python 脚本和一个 shell 渲染脚本里。5.1 示例源码一个简单电商模块先准备一个极简的源码目录方便扫描脚本展示效果。# 文件路径app/models/user.py class User: def __init__(self, user_id: int, name: str): self.user_id user_id self.name name def get_display_name(self) - str: return self.name# 文件路径app/models/order.py class Order: def __init__(self, order_id: str, user_id: int, amount: float): self.order_id order_id self.user_id user_id self.amount amount def get_order_info(self) - dict: return {order_id: self.order_id, amount: self.amount}# 文件路径app/services/user_service.py from app.models.user import User class UserService: def create_user(self, user_id: int, name: str) - User: return User(user_id, name) def get_user(self, user_id: int) - User: # 简化逻辑实际项目中这里会查询数据库 return User(user_id, demo)# 文件路径app/services/order_service.py from app.models.order import Order from app.services.user_service import UserService class OrderService: def __init__(self): self.user_service UserService() def create_order(self, user_id: int, amount: float) - Order: user self.user_service.get_user(user_id) order_id fORDER_{user.user_id}_{amount} return Order(order_id, user.user_id, amount)这个示例虽然简单但类与类之间的关系已经足够体现UserService依赖UserOrderService依赖UserService和Order。5.2 扫描脚本提取类、方法和依赖# 文件路径scripts/scan_class_deps.py import ast import json import os import sys from collections import defaultdict def get_imported_names(tree): 收集当前文件里 import 进来的名字用于判断类型归属。 imported {} for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: local_name alias.asname or alias.name.split(.)[0] imported[local_name] alias.name elif isinstance(node, ast.ImportFrom): module node.module or for alias in node.names: local_name alias.asname or alias.name imported[local_name] f{module}.{alias.name} return imported def extract_class_info(file_path, tree): 提取单个文件中的类信息。 imported get_imported_names(tree) class_info {} for node in ast.walk(tree): if not isinstance(node, ast.ClassDef): continue deps set() bases [] methods [] # 父类 for base in node.bases: if isinstance(base, ast.Name): bases.append(base.id) if base.id in imported: deps.add(imported[base.id]) else: deps.add(base.id) # 方法和方法中的类型标注 for item in node.body: if isinstance(item, ast.FunctionDef): methods.append(item.name) all_args list(item.args.args) list(item.args.kwonlyargs) for arg in all_args: if arg.annotation and isinstance(arg.annotation, ast.Name): deps.add(arg.annotation.id) if item.returns and isinstance(item.returns, ast.Name): deps.add(item.returns.id) class_info[node.name] { file: file_path, bases: bases, methods: methods, deps: sorted(deps), } return class_info def scan_directory(source_dir): 递归扫描目录下所有 .py 文件。 result {} for root, _, files in os.walk(source_dir): for file_name in files: if not file_name.endswith(.py): continue file_path os.path.join(root, file_name) with open(file_path, r, encodingutf-8) as f: source f.read() try: tree ast.parse(source) except SyntaxError as e: print(f跳过 {file_path}: 语法错误 {e}) continue info extract_class_info(file_path, tree) if info: result.update(info) return result def main(): source_dir sys.argv[1] if len(sys.argv) 1 else app output sys.argv[2] if len(sys.argv) 2 else docs/class_deps.json os.makedirs(os.path.dirname(output), exist_okTrue) scan_result scan_directory(source_dir) # 统一成 {class_name: {deps: []}} 格式方便后续渲染 simple_result {} for class_name, info in scan_result.items(): simple_result[class_name] { file: info[file], bases: info[bases], methods: info[methods], deps: info[deps], } with open(output, w, encodingutf-8) as f: json.dump(simple_result, f, ensure_asciiFalse, indent2) print(f扫描完成共发现 {len(simple_result)} 个类结果已写入 {output}) if __name__ __main__: main()这段脚本有两个关键点get_imported_names是为了把from app.models.user import User这种导入映射成app.models.user.User这样依赖关系能看出业务模块边界。类型标注里ast.Name才能拿到类名如果是list[str]这种下标类型需要额外处理但示例足够说明原理。5.3 生成 Mermaid 类图脚本# 文件路径scripts/generate_class_diagram.py import json import os import sys def load_deps(json_path): with open(json_path, r, encodingutf-8) as f: return json.load(f) def generate_mermaid_class_diagram(deps): lines [] lines.append(classDiagram) # 先声明所有类节点 for class_name in deps: lines.append(f class {class_name}) # 继承关系 for class_name, info in deps.items(): for base in info.get(bases, []): lines.append(f {base} |-- {class_name}) # 依赖关系 for class_name, info in deps.items(): for dep in info.get(deps, []): if dep class_name: continue # 避免重复输出 edge f {class_name} -- {dep} if edge not in lines: lines.append(edge) return \n.join(lines) def main(): json_path sys.argv[1] if len(sys.argv) 1 else docs/class_deps.json output_path sys.argv[2] if len(sys.argv) 2 else docs/class_diagram.mmd deps load_deps(json_path) mermaid_code generate_mermaid_class_diagram(deps) os.makedirs(os.path.dirname(output_path), exist_okTrue) with open(output_path, w, encodingutf-8) as f: f.write(mermaid_code) print(f类图代码已生成: {output_path}) print(mermaid_code) if __name__ __main__: main()这一步生成的.mmd文件就是 Mermaid 的文本语言。它既可以直接被 GitHub 渲染也可以通过 CLI 转成图片。5.4 渲染脚本把.mmd转成 PNG#!/usr/bin/env bash # 文件路径scripts/render_mermaid.sh set -euo pipefail INPUT_FILE${1:-docs/class_diagram.mmd} OUTPUT_FILE${2:-docs/class_diagram.png} if ! command -v mmdc /dev/null; then echo 未找到 mmdc请先执行: npm install -g mermaid-js/mermaid-cli exit 1 fi mkdir -p $(dirname $OUTPUT_FILE) mmdc \ -i $INPUT_FILE \ -o $OUTPUT_FILE \ -b white \ --width 1200 echo 渲染完成: $OUTPUT_FILE如果你不想用 Node.js 环境也可以把generate_class_diagram.py改成输出 PlantUML 格式然后用 Java Graphviz 渲染。Mermaid 的好处是生态广GitHub 原生支持团队协作时可以直接在 PR 里看到图的变化。5.5 让 AI 生成流程图 JSON 的示例类图已经打通了接下来是业务流程图。这里用一个 prompt 示例告诉你怎么让 AI 输出结构化 JSON而不是直接画图。假设你有这样一段业务描述用户下单后系统先校验库存如果库存不足返回失败如果库存充足创建订单并扣减库存然后调用支付接口支付成功后发送通知支付失败则回滚库存。你可以把这个需求描述发给大模型并在 prompt 中明确要求请把下面的业务过程拆解为流程图节点和连线只输出 JSON不要输出任何解释。 JSON 格式要求如下 { nodes: [ {id: 1, label: 用户下单, type: start}, {id: 2, label: 校验库存, type: condition} ], edges: [ {from: 1, to: 2, label: } ] } 业务过程用户下单后系统先校验库存如果库存不足返回失败如果库存充足创建订单并扣减库存然后调用支付接口支付成功后发送通知支付失败则回滚库存。得到 JSON 后再用一个简单的渲染脚本转成 Mermaid# 文件路径scripts/flow_json_to_mermaid.py import json import sys def convert_to_mermaid_flowchart(data): lines [] lines.append(flowchart TD) for node in data.get(nodes, []): node_id node[id] label node.get(label, node_id) shape [ if node.get(type) ! condition else { close ] if shape [ else } lines.append(f {node_id}{shape}{label}{close}) for edge in data.get(edges, []): label edge.get(label, ) if label: lines.append(f {edge[from]} --|{label}| {edge[to]}) else: lines.append(f {edge[from]} -- {edge[to]}) return \n.join(lines) def main(): input_path sys.argv[1] if len(sys.argv) 1 else docs/flow.json output_path sys.argv[2] if len(sys.argv) 2 else docs/flow.mmd with open(input_path, r, encodingutf-8) as f: data json.load(f) mmd convert_to_mermaid_flowchart(data) with open(output_path, w, encodingutf-8) as f: f.write(mmd) print(mmd) if __name__ __main__: main()这个脚本的价值在于把 AI 的输出规范到固定格式让流程图渲染这件事不再依赖 AI 的“临场发挥”。6. 运行结果与效果验证6.1 生成类依赖 JSON在项目根目录执行python scripts/scan_class_deps.py app docs/class_deps.json正常情况下终端输出扫描完成共发现 4 个类结果已写入 docs/class_deps.json打开docs/class_deps.json内容类似{ Order: { file: app/models/order.py, bases: [], methods: [get_order_info], deps: [] }, OrderService: { file: app/services/order_service.py, bases: [], methods: [create_order], deps: [app.services.user_service.UserService, app.models.order.Order] }, User: { file: app/models/user.py, bases: [], methods: [get_display_name], deps: [] }, UserService: { file: app/services/user_service.py, bases: [], methods: [create_user, get_user], deps: [app.models.user.User] } }验证这一步的关键点OrderService的依赖里同时出现了UserService和Order说明 type annotation 和 return annotation 都被正确识别了。如果你的类之间是通过构造方法注入的可能还需要额外处理__init__方法里的赋值语句但 AST 的基本思路不变。6.2 生成 Mermaid 类图文本python scripts/generate_class_diagram.py docs/class_deps.json docs/class_diagram.mmd生成的.mmd文件内容大概是这样classDiagram class Order class OrderService class User class UserService UserService |-- OrderService OrderService -- app.services.user_service.UserService OrderService -- app.models.order.Order UserService -- app.models.user.User这里注意一个细节UserService |-- OrderService这行其实是错误的因为示例里OrderService并没有继承UserService只是在构造方法里组合了它。这是因为扫描脚本暂时把“类名出现在另一个类的方法体里”也归为依赖了。在实际使用中你需要判断父类关系用继承边方法参数和返回值用依赖边构造方法注入属于组合关系。三者的语义不同最好分开输出。6.3 渲染 PNGbash scripts/render_mermaid.sh docs/class_diagram.mmd docs/class_diagram.png成功后会看到docs/class_diagram.png生成。打开图片应该能看到 4 个类节点以及它们之间的连线。如果渲染失败优先检查mmdc是否安装成功。首次运行是否下载 Chromium 失败。.mmd文件里的类名是否包含空格或特殊字符。6.4 验证 AI 流程图的输出把包含 JSON 的回答保存为docs/flow.json然后执行python scripts/flow_json_to_mermaid.py docs/flow.json docs/flow.mmd如果 AI 输出的 JSON 结构合法你会得到一份 Mermaid 的flowchart TD文本。再调用mmdc渲染成 PNG就能直接用在文档里。7. 常见问题与排查思路问题现象可能原因排查方式解决方案扫描脚本报SyntaxError源码包含 Python 2 语法或动态执行代码查看具体报错文件和行号在解析前过滤掉不兼容文件或者改用ast.parse时捕获异常并跳过生成的类图缺少某些类之间的连线AST 只能解析静态类型识别不了动态类型检查该依赖是否来自getattr、eval、反射调用在脚本里加入手动补充配置比如manual_deps字典类太多生成的图成为“蜘蛛网”全部节点一次性渲染没有做层级过滤检查 JSON 中的类数量增加--include-packages参数只渲染指定包下的类渲染 PNG 时中文乱码Mermaid 默认字体不支持中文字符查看浏览器控制台或 mmdc 日志配置puppeteerConfigFile指定系统中文字体AI 生成的 JSON 不符合格式Prompt 里没有给严格的 schema 示例检查大模型输出中是否夹杂解释文本在 prompt 中强调“只输出 JSON”并在代码里增加格式校验mmdc命令找不到Node.js 全局环境未配置执行npm ls -g mermaid-js/mermaid-cli重新执行全局安装或改用npx mmdc类名带泛型或内部类Mermaid 渲染失败类名包含等特殊符号检查.mmd文件具体报错位置对类名做转义或重命名这里我想重点说两个容易踩的坑第一个是AST 的静态局限。如果你的业务代码大量使用了property、__getattr__、functools.lru_cache这样的装饰器AST 看到的只是装饰器表达式看不到运行时的依赖关系。所以这类工具定位应该是“辅助文档生成”而不是“精确的运行时分析”。要精确分析运行时对象关系应该用sys.setprofile、coverage或者pytest的插桩方式但那是另一个话题了。第二个是不要让 AI 直接把流程图代码写死。AI 生成 Mermaid 图代码时经常会出现节点 id 不统一、连线指向不存在的节点、条件分支缺少汇聚节点等问题。更稳妥的做法是先让它输出 JSON用脚本校验后再渲染。这样即使 AI 出错错误也是可定位的而不是隐藏在图形中的一个错位箭头。8. 最佳实践与工程建议8.1 图和代码同源但要人审最重要的一条原则图不是独立存在的文档它是代码的可视化投影。代码改了图就应该重新生成。所以建议把扫描脚本和生成脚本放进项目根目录并提供一个Makefile或者 npm script一键更新所有图表。但“自动生成”不代表“无人审核”。类图能反映代码结构却反映不了代码设计是否合理。比如一个类依赖了十几个其他类图会清楚地把它画出来但要不要重构、怎么拆分仍然需要人做判断。AI 和脚本的价值是把事实摆到眼前决策依然是人来做。8.2 控制节点粒度避免大爆炸图实际项目中一个模块可能包含 200 个类。如果全部渲染生成的图没有人能看懂。更合理的做法是分层展示包层级图只展示包和包之间的依赖粒度最粗。核心类图只展示models、services、controllers里的核心类过滤掉 DTO、VO、工具类。变更影响图在重构时只看本次变更涉及的类以及它们直接依赖的类。控制粒度的实现方式可以在扫描脚本里增加黑白名单# 在 scan_class_deps.py 中添加过滤逻辑 INCLUDE_PACKAGES [app.models, app.services] EXCLUDE_CLASSES {BaseModel, MixinA, MixinB} def should_include(class_name, file_path): if class_name in EXCLUDE_CLASSES: return False return any(pkg in file_path for pkg in INCLUDE_PACKAGES)8.3 用命名规范辅助 AI 理解代码AI 生成流程图时对类名、方法名、注释的质量非常敏感。如果方法都叫process、handle、doSomethingAI 很难从方法名推断出业务含义。反过来如果方法名是validateStockAndCreateOrder、rollbackInventory、notifyPaymentResultAI 几乎不需要额外解释就能画出准确的流程。所以从工程角度看让 AI 生成好文档的前提是代码本身有清晰的命名和注释。这不只是给 AI 看的也是给人看的。如果你准备在团队里推广这套工作流建议先从统一命名规范开始。8.4 流程图的“生成 JSON - 渲染”模式无论是 AI 生成流程图还是脚本生成类图尽量让中间产物是 JSON 或者结构化配置而不是直接生成最终图片。原因有三个JSON 可以 diff方便在 code review 中看到流程图的变化。JSON 可以复用同一个结构可以渲染成 Mermaid、PlantUML、DOT甚至表格。JSON 便于人工修改和合并AI 生成的 JSON 即使不完美也比从头改图代码要快。这意味着你的渲染逻辑应该和数据结构解耦。先定义好“节点 连线”的数据结构再分别实现不同渲染器的适配。8.5 注意代码安全与权限边界如果你把自己的业务代码作为 prompt 发送给公网大模型需要格外谨慎。规范的做法是涉及核心业务逻辑的源码优先使用私有化部署的模型或企业版 API。发送给模型之前进行脱敏处理类名、方法名可以保留但数据库连接串、密钥、客户信息必须去掉。在团队协作中把“代码转图”做成内部工具而不是让每个人都去调公网接口。8.6 把图表生成接入 CI更进一步你可以在 CI 里增加一个图表生成任务。每次合并代码后重新扫描代码并生成类图如果类图发生变化就把新的 PNG 提交到文档仓库或者在 PR 里创建一条评论贴上 diff 后的图表。这个做法看起来简单但效果很好。它逼着开发者一改代码就看到结构变化图的时效性不再是靠个人自觉而是靠流水线保证。9. 总结与后续学习方向这篇文章围绕“AI 自动生成类库节点、流程图”展开核心结论可以归纳为三条第一用 Python AST 扫描代码、用 JSON 作为中间格式、用 Mermaid 渲染可以低成本地把“维护类图”变成“代码提交后的自动任务”。这套链路不依赖任何重型框架核心代码不到 200 行。第二AI 在生成流程图时真正有价值的不是直接出图而是把需求文本、代码注释、接口定义转换成结构化的节点和连线 JSON。通过flow_json_to_mermaid.py这样的脚本可以让 AI 的输出直接进入渲染流程同时保留人工修改和 diff 的能力。第三这类工具解决的是“同步成本”问题而不是“设计能力”问题。它不能让烂代码变好也不能替代架构师的分析但它能让图和代码永远保持一致避免团队被过时文档误导。如果你想把这套方案用于自己的项目建议按这个顺序实践先跑通scan_class_deps.py和generate_class_diagram.py拿到自己项目的类图。再选一个核心业务流程用 AI 生成 JSON 流程图跑通flow_json_to_mermaid.py。最后把脚本接入 CI让每次代码变更都自动更新图表。后续可以深入的方向包括用tree-sitter解析 Java、Go、TypeScript 代码用大模型语义分析自动生成架构决策记录把生成的图嵌入 Confluence、语雀或者内部文档平台以及在 Mermaid 基础上叠加交互能力让节点可以点击跳转到源码文件。建议先把这篇文章里提供的最小工程跑一遍再考虑扩展。等真正用起来之后你会发现“手写类库、手动画图”这件事确实可以成为历史了。