1. 架构师为什么需要从 Python 源码自动生成 UML 类图和时序图接手一个跑了三年的 Python 项目最头疼的不是改 bug而是没人说得清模块之间到底怎么调用。文档停留在两年前的 Confluence 页面代码里已经多了十几个 service 和一堆 dataclass。评审新模块时同事问「这个 OrderService 和 PaymentService 的依赖方向是什么」你只能现场翻代码翻完发现继承链有三层。UML 类图和时序图就是解决这类问题的通用语言。类图回答「系统里有哪些对象、它们怎么关联」时序图回答「一次请求从入口到落库中间经过了谁」。传统做法是打开 draw.io 或 PlantUML 手画一个中等规模的电商模块画完要小半天而且代码一改图就过期。Claude Code 在这里的价值不是「帮你画图」而是把「读代码 → 提取结构 → 生成 PlantUML 文本 → 渲染成图」这条链路自动化。你给它一个 Python 文件或一个目录它能用 AST 静态分析出类、属性、方法、继承和组合关系再按 PlantUML 语法输出.puml文件最后调用本地plantuml命令渲染成 PNG/SVG。整个过程可复制、可重跑代码变了重新执行一次就行。这篇面向两类场景一是逆向旧项目把没有文档的存量代码补出类图二是评审新模块在 PR 阶段就生成时序图让评审有图可看。下面会给出可直接复制的提示词模板、PlantUML 渲染配置、逐条验证动作以及如何把 Claude Code 的 endpoint 改到 TaoToken 统一调用避免每个项目单独配 key。适合谁写过 Python、知道ast模块大概能干什么、但不想手写解析器的后端架构师以及需要给团队输出设计文档、又不想维护 draw.io 源文件的技术负责人。如果你只是偶尔画一张图手写 PlantUML 更快但如果你要覆盖几十个模块、还要随代码更新自动化才划算。核心检索词先明确Claude Code 生成 UML 类图、Python 源码逆向时序图、PlantUML 自动渲染这三个是全文的主线。下面从环境准备开始一步步把链路跑通。2. TaoToken 前置准备把 Claude Code 的 endpoint 统一到一处Claude Code 默认走官方 endpoint但团队里多人多项目时每个项目单独配 key、单独管额度很麻烦。TaoToken 提供统一的 API 入口把 Claude Code 的请求指向https://taotoken.net/apikey 在控制台统一管理切换模型也不用改代码。先拿到 key。打开控制台页面登录后创建 API Key复制出来形如sk-xxxxxxxx。这个 key 后面要写进 Claude Code 的配置里。Claude Code 的配置方式取决于你用的是哪种接入形态。常见的有两种一种是直接改 Claude Code 的 settings 文件另一种是通过 CC Switch 这类多配置切换工具。这里给出 settings 的写法路径按你的系统来macOS 和 Linux 下通常是~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json。文件内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三个字段缺一不可Base URL 指向 TaoToken 的 API 地址Auth Token 填刚才复制的 keyModel ID 填你要用的模型标识。如果你用 CC Switch 管理多套配置就在它的配置界面里新建一个 profile把这三项填进去切换时选这个 profile 即可。如果你用的是 Codex 或 Cline 这类工具配置位置不同但三件套一样。Codex 的auth.json里写base_url、api_key、modelCline 的 MCP 配置里写baseUrl、apiKey、model。核心就是 Base URL Key Model ID任何工具都逃不出这三项。配好之后验证一下。在终端里执行claude --version能输出版本号说明 Claude Code 本身装好了。然后随便问一句让它读当前目录的文件比如claude 列出当前目录下所有 .py 文件如果返回了文件列表说明请求已经通过 TaoToken 走通了。如果报 401多半是 key 填错或没生效如果报连接失败检查 Base URL 有没有多写斜杠或漏了/api。这里提醒一句TaoToken 是统一调用入口不是让你绕过什么。它的作用是让团队在一个地方管 key、看用量、切模型省去每个项目单独配的重复劳动。接入文档里有各工具的详细配置示例遇到不确定的字段可以去对照。3. 可复制配置PlantUML 渲染环境与 Claude Code 提示词模板环境分两块一块是 PlantUML 渲染器本身一块是 Claude Code 的提示词。先把渲染器装好否则生成的.puml只是文本看不到图。PlantUML 依赖 Java 和 Graphviz。macOS 下用 Homebrew 一条命令brew install plantuml graphvizUbuntu/Debian 下sudo apt-get install -y plantuml graphviz default-jreWindows 下建议用 Scoop 或直接下载 plantuml.jar确保java -version能输出 11 以上。装完验证plantuml -version输出里会带版本号和 Graphviz 的路径。如果提示找不到 dot说明 Graphviz 没进 PATH重装或手动加环境变量。渲染命令的核心参数是输出格式和字符集。生成 PNGplantuml -tpng -charset UTF-8 diagram.puml生成 SVGplantuml -tsvg -charset UTF-8 diagram.puml生成 PDFplantuml -tpdf -charset UTF-8 diagram.puml-charset UTF-8必须加否则中文标题和注释会乱码。输出文件名默认和.puml同名只是扩展名不同。接下来是 Claude Code 的提示词模板。直接复制下面这段把{{目标路径}}换成你的 Python 文件或目录你是一个 Python 架构分析助手。请对 {{目标路径}} 做以下事情 1. 用 AST 静态分析提取所有类定义包括类名、父类、属性含类型注解、方法含参数和返回类型。 2. 识别类之间的关系继承inheritance、组合composition、聚合aggregation、依赖dependency。 3. 生成 PlantUML 类图代码要求 - 使用 startuml / enduml 包裹 - 抽象类标注 abstractdataclass 标注 dataclass - 可见性用 - # 表示 public/protected/private - 跳过 __str__、__repr__ 等魔术方法保留 __init__ - 中文注释保留 4. 把结果写入 class_diagram.puml然后执行 plantuml -tpng -charset UTF-8 class_diagram.puml 渲染。 5. 如果渲染失败输出 plantuml 的 stderr 内容不要静默跳过。时序图的提示词换一个角度重点是调用链请阅读 {{目标路径}} 中的入口函数如 Flask/FastAPI 路由或 main 函数 追踪一次完整请求的调用链生成 PlantUML 时序图 - participant 按调用顺序排列数据库用 database 关键字消息队列用 queue - 每个跨服务调用标注 HTTP 方法或消息类型 - 异常分支用 note over 标注 - 输出到 sequence_diagram.puml 并渲染为 PNG这两段提示词的关键在于「要求它输出可渲染的文件并执行渲染命令」而不是只把 PlantUML 文本贴在对话里。Claude Code 有文件写入和命令执行能力让它直接落盘再渲染你拿到的是图而不是一段需要手动复制的代码。如果你用 CC Switch 管理配置确保当前 profile 指向 TaoToken这样提示词里的模型调用走统一入口。Cline 的 MCP 配置同理Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 按需选。4. 验证请求与成功结果从 Python 源码到类图、时序图配置就绪后拿一个真实的 Python 文件跑一遍。假设你有一个order_service.py里面定义了Order、OrderItem、Payment几个 dataclass 和一个OrderService类。在项目根目录启动 Claude Code把第 3 节的类图提示词贴进去目标路径填order_service.py。执行后你会看到它先输出分析过程然后写入class_diagram.puml最后调用 plantuml 渲染。打开生成的.puml文件内容大致是这样startuml skinparam backgroundColor #FEFEFE skinparam class { BackgroundColor #E3F2FD BorderColor #1565C0 FontName Microsoft YaHei } title 订单模块类图 class Order dataclass { id: int user_id: int total_amount: float status: OrderStatus -- create_from_cart(cart: ShoppingCart): bool cancel(): bool ship(tracking_no: str): bool } class OrderItem dataclass { product_id: int quantity: int price: float -- subtotal(): float } class Payment dataclass { order_id: int amount: float method: PaymentMethod -- pay(processor: PaymentProcessor): bool } Order 1 *-- 0..* OrderItem : contains Order 1 o-- 0..1 Payment : paid_by enduml渲染成功后同目录下会出现class_diagram.png。用图片查看器打开能看到类框、属性、方法和关系箭头。如果中文显示正常、继承箭头方向正确说明链路通了。时序图验证换一个入口。找一个 FastAPI 或 Flask 的路由函数比如app.post(/orders)把时序图提示词贴进去。生成的.puml里会有actor、participant、database这些元素箭头按调用顺序排列。渲染出的 PNG 能直观看到「前端 → 网关 → 订单服务 → 库存服务 → 数据库」的完整链路。验证成功的三个标志一是.puml文件里类名和实际代码一致没有凭空捏造的类二是关系箭头方向正确继承是--|组合是*--三是渲染出的图中文不乱码、布局不重叠。如果这三点都满足说明 Claude Code 的 AST 分析和 PlantUML 渲染都工作正常。实测下来一个 500 行左右的 Python 模块从贴提示词到拿到 PNG 大约 30 秒。比手画快得多而且改完代码重跑一次就同步了。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth接入和渲染过程中最容易踩的几类报错逐个对照。401 Unauthorized。这是 key 或 Base URL 的问题。先检查settings.json里的ANTHROPIC_AUTH_TOKEN是不是完整复制了有没有多余空格。再确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意结尾没有斜杠路径里有/api。如果用的是 CC Switch检查当前激活的 profile 是不是你配的那个。401 基本就是这三处之一。local proxy failed。这个报错通常出现在 Claude Code 尝试连接 endpoint 时。先确认网络能访问taotoken.net用curl -I https://taotoken.net/api看返回码。如果返回 200 或 401 都说明网络通问题在配置如果超时检查本机网络设置。注意不要在任何配置里写代理地址TaoToken 是直连入口不需要额外代理层。reading choices 相关报错。这类错误一般出现在模型返回格式不符合预期时比如你用的 Model ID 写错了或者该模型不支持当前请求格式。检查ANTHROPIC_MODEL字段确认填的是 TaoToken 支持的模型标识。如果换了模型还是报错去接入文档里核对当前可用的 Model ID 列表。OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 流程如果你用的是 API Key 模式需要在配置里明确走 token 认证。检查 settings 里有没有残留的 OAuth 配置项删掉它们只保留ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL三项。如果用的是 Codex 的auth.json确认字段名是api_key而不是oauth_token。PlantUML 渲染失败。如果 Claude Code 报告 plantuml 命令找不到说明 PATH 没配好。在终端里执行which plantuml确认路径然后把该路径加到系统 PATH。如果报 Graphviz 的 dot 找不到重装 graphviz 并确认dot -V能输出版本。中文乱码就加-charset UTF-8这个参数不能省。生成的图缺类或缺关系。这通常是 AST 分析的边界情况比如动态创建的类、__getattr__返回的属性、或者跨文件的继承。解决办法是在提示词里明确目标目录而不是单个文件让 Claude Code 扫描整个包。如果还缺手动在.puml里补几行PlantUML 文本本身就是可编辑的。排查顺序建议先确认 key 和 Base URL 正确再确认模型 ID 可用最后确认 plantuml 和 graphviz 装好。这三层都过了基本不会有大问题。6. 把 UML 生成接入日常流程从一次性脚本到持续同步跑通单次生成只是起点。真正省时间的是把它变成日常流程的一部分。第一种用法是 pre-commit 钩子。在.git/hooks/pre-commit里加一段每次提交前对改动的 Python 文件重新生成类图把.puml和.png一起提交。这样代码和文档永远同步评审时直接看图。第二种用法是 CI 流水线。在 GitHub Actions 或 GitLab CI 里加一个 job用 Claude Code 的 CLI 模式跑生成脚本把产出的图作为 artifact 上传。PR 里就能看到这次改动对架构的影响。第三种用法是评审辅助。新模块提 PR 时让作者附上时序图。评审人不用逐行读代码先看图确认调用链合理再针对具体实现提意见。这比纯代码评审效率高很多。如果你团队用 Coding Plan 做长期编码和 Agent 任务可以把 UML 生成作为一个固定 skill 挂进去每次涉及架构变更时自动触发。模型对话页面适合临时验证某个模块的结构接入文档里有各场景的配置说明。最后给一个实用技巧生成的.puml文件不要只留在本地提交到仓库的docs/uml/目录。PlantUML 是纯文本diff 友好改了什么关系一眼能看出来。配合 CI 自动渲染团队任何人 clone 下来都能看到最新的架构图。这套流程跑顺之后你会发现架构文档不再是负担而是代码的副产品。代码改完图自动更新评审有据可依新人上手也能先看图再读代码。