企业官网建设流程全解析

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/api，key 在控制台统一管理，切换模型也不用改代码。

先拿到 key。打开控制台页面，登录后创建 API Key，复制出来形如sk-xxxxxxxx。这个 key 后面要写进 Claude Code 的配置里。

Claude Code 的配置方式取决于你用的是哪种接入形态。常见的有两种：一种是直接改 Claude Code 的 settings 文件，另一种是通过 CC Switch 这类多配置切换工具。这里给出 settings 的写法，路径按你的系统来：

macOS 和 Linux 下通常是~/.claude/settings.json，Windows 下是%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 填刚才复制的 key，Model ID 填你要用的模型标识。如果你用 CC Switch 管理多套配置，就在它的配置界面里新建一个 profile，把这三项填进去，切换时选这个 profile 即可。

如果你用的是 Codex 或 Cline 这类工具，配置位置不同但三件套一样。Codex 的auth.json里写base_url、api_key、model；Cline 的 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 graphviz

Ubuntu/Debian 下：

sudo apt-get install -y plantuml graphviz default-jre

Windows 下建议用 Scoop 或直接下载 plantuml.jar，确保java -version能输出 11 以上。装完验证：

plantuml -version

输出里会带版本号和 Graphviz 的路径。如果提示找不到 dot，说明 Graphviz 没进 PATH，重装或手动加环境变量。

渲染命令的核心参数是输出格式和字符集。生成 PNG：

plantuml -tpng -charset UTF-8 diagram.puml

生成 SVG：

plantuml -tsvg -charset UTF-8 diagram.puml

生成 PDF：

plantuml -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 包裹 - 抽象类标注 <<abstract>>，dataclass 标注 <<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/api，Key 填控制台生成的，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 下来都能看到最新的架构图。

这套流程跑顺之后，你会发现架构文档不再是负担，而是代码的副产品。代码改完，图自动更新，评审有据可依，新人上手也能先看图再读代码。