过去这段时间AI Agent 领域最热的关键词已经不只是“写代码”“做分析”而是大量出现了一个词Skill。从 Claude Code 到 Codex再到各类开源 Agent 框架Skill 都成了让 AI 更“懂行”的核心玩法。而在众多 Skill 里有一类特别吸引眼球一句话画出系统架构图。之前我在做项目梳理时经常卡在“给新同学讲架构”这个环节。画图工具用了一堆Visio 太重draw.io 要手动拖拽ProcessOn 免费版又有数量限制。后来接触到 AI Agent Skill 的方案后发现只要把架构描述说清楚AI 就能自动生成一张可编辑、可维护的架构图。这篇文章就把这套玩法的原理、Skill 编写方式、完整代码和常见坑位一次讲清楚。无论你是后端开发、架构师还是刚接触 AI Agent 的初学者这篇文章都会给你一套可以直接复用的思路。1. 背景与核心概念Skill 到底是什么1.1 从“AI 会聊天”到“AI 能干活”很多人第一次用 ChatGPT、Claude 这类助手时会觉得 AI 很聪明但不够稳定。同一个问题换个问法答案就不一样让它做一个稍微复杂一点的任务它很容易在中途“跑偏”。这是因为通用大模型本身是一个“语言模型”它擅长的是根据上下文预测下一个词语而不是严格地按流程执行任务。所谓“能干活的 AI”本质上是在大模型外面套了一层工程壳给它明确的角色设定、给它工具、给它步骤、给它示例它才能把任务拆解并执行到位。Skill技能就是这层工程壳的一种标准化形态。1.2 Skill 的精确定义Skill 在 AI Agent 生态里通常指一套结构化指令 示例 可选脚本/工具的集合。它把一个特定领域的工作流固化下来让 Agent 在遇到相关任务时能按照约定好的方式去思考、去调用工具、去输出结果。用一句话概括Skill 是给 Agent 写的“岗位说明书 操作手册”。以“系统架构图 Skill”为例一个完整的 Skill 至少要回答这些问题什么场景下触发用户说“帮我画个架构图”按照什么步骤做先确认系统边界再梳理组件再画连线输出什么格式SVG、DrawIO XML还是 Mermaid有哪些规则要遵守节点命名规范、层级不超过几层、颜色语义有哪些示例可以参考给 2 到 3 个标杆案例Agent 接到用户请求时会先判断这个请求是否符合某个 Skill 的触发条件如果符合就加载这个 Skill 的说明文件按照里面的步骤和约束去执行。1.3 Skill 和 Agent 的区别这个区别是很多初学者最容易混淆的。我把它们比作“员工”和“公司制度”的关系维度Agent智能体Skill技能本质一个能自主决策、执行任务的 AI 实体一组针对特定任务的指令和工具集合是否独立运行是Agent 可以自己规划任务否Skill 需要被 Agent 加载执行持久性有一定“记忆”和上下文无状态每次加载时重新读取类比一个能干的员工员工手里的标准作业指导书换句话说一个 Agent 可以同时挂载多个 Skill。比如同一个 Agent 既能写代码代码生成 Skill又能画架构图架构图 Skill还能做日志分析日志分析 Skill。Skill 之间彼此独立互不干扰。1.4 为什么“系统架构图 Skill”最近很火原因有三个架构图是刚需开发、汇报、文档、面试、答辩几乎每个技术场景都需要架构图。通用画图工具效率低手动拖拽、调整布局、统一配色非常耗时改一版需求往往要重画。大模型 Skill 补齐了稳定性和专业性给 AI 一套架构图生成规则它就能稳定地输出符合规范的结果而不是每次瞎画。所以这一波热词里“archify skill”“drawio skill”“ppt skill”爆火不是偶然说明大家都发现了“专业场景 Skill”的巨大价值。2. 环境准备搭建 Skill 运行环境2.1 环境选型Skill 本身是“说明文件 脚本”它需要一个宿主环境来运行。目前常见的宿主有三种Claude Code / Codex 等命令行 Agent 工具直接在终端里对话Agent 能读写本地文件、执行脚本最适合开发场景。OpenClaw / Dify / Coze 等 Agent 平台图形化界面适合配置复杂工作流但部分平台对本地文件操作支持较弱。自研 Agent 框架LangGraph、AutoGen 等适合二次开发灵活度高但需要自己实现 Skill 加载逻辑。本文以“命令行 Agent 本地脚本 SVG 输出”为例原因是这套方案最容易复现不依赖特定云平台也不受在线服务限制。2.2 我使用的环境说明为了避免误导先说明我这里的测试环境操作系统macOS / Linux 均可Windows 需要调整脚本路径语法语言环境Python 3.10 以上Agent 工具支持 Skill 机制的 CLI Agent 工具Claude Code、Codex CLI 等均可图表输出标准 SVG 文件 PNG 预览可选具体版本不写死因为此类工具迭代非常快。本文重点演示 Skill 的编写思路和完整代码版本差异一般不影响核心逻辑。2.3 确认 Skill 目录结构大多数 Agent 工具都约定了一个 Skill 目录规则。我们以一个典型的 Agent Skills 目录结构为例~/.claude/skills/ # 或者其他 Agent 的 skills 目录 └── architecture-diagram/ # Skill 名称建议使用小写中划线 ├── SKILL.md # Skill 说明文件Agent 会优先读取 ├── scripts/ # 辅助脚本 │ └── render_arch.py # 根据描述生成 SVG 架构图 └── examples/ # 示例输出供 Agent 参考 └── order-system.svg如果你的 Agent 工具没有内置 Skill 机制也可以把这段逻辑做成一个自部署的提示词模板 脚本工具本质是一样的。2.4 验证运行环境先执行一个最简单的 Python 脚本确保环境正常python3 --version如果能输出版本号说明 Python 环境没有大问题。接下来我们继续创建一个临时目录用于存放 Skill 文件mkdir -p ~/.claude/skills/architecture-diagram cd ~/.claude/skills/architecture-diagram3. 画架构图 Skill 的原理拆解3.1 两条技术路线对比在动手写代码之前要先想清楚一个问题AI 应该用什么格式“画”架构图目前主流的方案有三类方案优点缺点适用场景Mermaid语法简单GitHub/Notion 原生支持复杂布局不灵活连线容易乱快速记录、简单流程Graphviz DOT自动布局能力强大语法繁琐样式调整麻烦自动化生成、大量节点SVG完全可控支持任意布局和样式生成复杂度高需要代码辅助正式架构图、高质量输出我选择 SVG。理由很简单架构图最终要给人看要放到 PPT 和文档里SVG 无限缩放、可编辑、可嵌入网页、可以用脚本精确控制每个节点位置。相比之下Mermaid 更适合画流程图而不是正式架构图。3.2 Skill 的整体工作流程这套 Skill 的工作流程分三层理解层Agent 读取用户的一句话描述提取核心组件、依赖关系和外部系统。结构化层Agent 按照固定 JSON Schema 输出一份“架构描述”文件。渲染层Python 脚本读取 JSON 文件自动计算布局生成 SVG 架构图。为什么不让 AI 直接生成 SVG因为大模型直接输出 SVG 时节点坐标全靠“蒙”经常重叠、超出画布。而先输出结构化的 JSON再由脚本做布局计算既利用了 AI 的语义理解能力又利用了程序的计算能力稳定性和可维护性都高很多。3.3 架构描述 JSON 的设计为了让 Agent 稳定输出我们需要定义一份严格的 JSON 格式。下面是一个最小可用的 Schema{ title: 订单系统架构图, layers: [ { name: 接入层, components: [Web 前端, 移动端] }, { name: 应用层, components: [订单服务, 用户服务, 支付服务] }, { name: 数据层, components: [MySQL, Redis] } ], connections: [ [Web 前端, 订单服务], [订单服务, MySQL], [订单服务, Redis] ] }这个结构有四个字段title图的标题显示在顶部。layers分层结构每层有一个名称和组件列表。架构图按层布局同一层的组件水平排列层与层之间垂直排列。connections连线关系数组里每个元素是一个二元组表示“从 A 到 B 有一条连线”。其实还可以扩展externalSystems、descriptions等字段但保持最小结构能让 Agent 更容易遵循。3.4 为什么用“分层”而不是“自由布局”系统架构图最经典的表达方式就是分层用户体验层接入层应用服务层数据存储层基础设施层分层布局的优势很明显阅读顺序自然从上到下就是一次请求的流转路径。布局算法简单同一层组件水平排列即可不需要复杂的力导向算法。视觉上更专业符合大多数架构图读者的阅读习惯。渲染脚本的核心逻辑就是按层从上到下排列层内组件从左到右排列。4. 完整实战从零创建一个架构图 Skill4.1 创建项目结构先创建 Skill 目录和子目录mkdir -p ~/.claude/skills/architecture-diagram/{scripts,examples}创建完成后目录结构如下architecture-diagram/ ├── SKILL.md ├── scripts/ │ └── render_arch.py └── examples/4.2 编写 SKILL.md 说明文件这是整个 Skill 的灵魂。Agent 读到这个文件后才能知道自己的任务是“画架构图”而不是随便聊聊。--- name: architecture-diagram description: 根据用户的一句话系统描述生成分层系统架构图SVG 格式。 --- # Architecture Diagram Skill 当用户要求“画架构图”、“画系统图”、“输出系统架构图”时使用本 Skill。 ## 执行步骤 1. 解析用户提供的系统描述提取系统名称、各层组件、组件之间的依赖关系。 2. 如果用户描述不清晰必须主动追问直到确认以下信息 - 系统包含哪些主要组件 - 组件之间谁调用谁 - 是否需要区分外部系统和内部系统 3. 按照下面的 JSON Schema 生成架构描述保存为 arch.json。 4. 调用渲染脚本 bash python3 scripts/render_arch.py arch.json output.svg检查 SVG 是否生成成功然后向用户展示结果。JSON Schema只允许输出以下结构的 JSON不要添加多余字段{ title: string, layers: [ { name: string, components: [string] } ], connections: [ [string, string] ] }规则组件名称要简洁优先使用业务名词而不是技术名词如“订单服务”而不是“OrderService_Core_Impl_2024”。层数量控制在 3 到 6 层超过 6 层时合并相关组件。连线只表达核心依赖不要把 20 条细节调用关系全部画出来。每个组件必须有至少一条连线否则删除该组件或补充连线。所有输出和解释使用中文。示例用户说画一个电商系统架构图包含前端、网关、订单、库存、支付、MySQL 和 Redis。合理的 JSON 如下{ title: 电商系统架构图, layers: [ {name: 客户端层, components: [Web 前端, 移动端]}, {name: 网关层, components: [API 网关]}, {name: 服务层, components: [订单服务, 库存服务, 支付服务]}, {name: 数据层, components: [MySQL, Redis]} ], connections: [ [Web 前端, API 网关], [移动端, API 网关], [API 网关, 订单服务], [API 网关, 库存服务], [API 网关, 支付服务], [订单服务, MySQL], [订单服务, Redis], [库存服务, MySQL], [支付服务, MySQL] ] }## 错误处理 - 如果 render_arch.py 执行报错先检查 JSON 是否缺少字段再检查 Python 脚本是否能正常运行。 - 如果 SVG 中节点重叠提示用户减少同一层的组件数量。这里有一个细节值得注意SKILL.md 里包含一个完整示例。示例是 Skill 稳定性的关键。大模型本质上在做模式匹配你给的例子越接近真实场景它输出就越稳定。4.3 编写核心渲染脚本接下来是重头戏渲染脚本。这个脚本读取 JSON计算布局输出 SVG。#!/usr/bin/env python3 # -*- coding: utf-8 -*- # 文件路径scripts/render_arch.py 读取架构描述 JSON生成分层系统架构图 SVG。 用法 python3 render_arch.py arch.json output.svg import json import sys import xml.etree.ElementTree as ET from xml.sax.saxutils import escape # 画布配置 CANVAS_WIDTH 1200 CANVAS_HEIGHT 800 PADDING 60 LAYER_GAP 80 COMPONENT_GAP 40 COMPONENT_WIDTH 180 COMPONENT_HEIGHT 60 HEADER_HEIGHT 80 # 颜色配置 BG_COLOR #FFFFFF LAYER_BG_COLOR #F8FAFC LAYER_BORDER_COLOR #E2E8F0 COMPONENT_BG_START #3B82F6 COMPONENT_BG_END #2563EB COMPONENT_TEXT_COLOR #FFFFFF TITLE_COLOR #1E293B LAYER_TITLE_COLOR #475569 LINE_COLOR #94A3B8 # SVG 命名空间让输出的 SVG 能在浏览器正常显示 SVG_NS http://www.w3.org/2000/svg ET.register_namespace(, SVG_NS) def create_svg_root(title, width, height): 创建 SVG 根元素。 svg ET.Element(f{{{SVG_NS}}}svg, { width: str(width), height: str(height), viewBox: f0 0 {width} {height}, xmlns: SVG_NS, font-family: Arial, PingFang SC, Microsoft YaHei, sans-serif, }) # 顶部标题 title_text ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(width / 2), y: 40, text-anchor: middle, font-size: 24, font-weight: bold, fill: TITLE_COLOR, }) title_text.text title return svg def draw_layer(svg, y, height, name): 绘制分层背景。 rect ET.SubElement(svg, f{{{SVG_NS}}}rect, { x: str(PADDING), y: str(y), width: str(CANVAS_WIDTH - 2 * PADDING), height: str(height), fill: LAYER_BG_COLOR, stroke: LAYER_BORDER_COLOR, stroke-width: 1.5, rx: 12, }) # 层名称 label ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(PADDING 16), y: str(y 28), font-size: 16, font-weight: bold, fill: LAYER_TITLE_COLOR, }) label.text name return rect def add_component(svg, x, y, name): 在指定位置绘制一个组件节点带渐变背景。 # 定义渐变不同组件使用不同颜色方便区分 gradient_id fgrad_{abs(hash(name)) % 10000} defs svg.find(f{{{SVG_NS}}}defs) if defs is None: defs ET.SubElement(svg, f{{{SVG_NS}}}defs) # 根据组件名选择颜色简单起见按哈希选色 colors [ (#3B82F6, #2563EB), (#10B981, #059669), (#F59E0B, #D97706), (#EF4444, #DC2626), (#8B5CF6, #6D28D9), (#EC4899, #DB2777), ] idx abs(hash(name)) % len(colors) c1, c2 colors[idx] linear_gradient ET.SubElement(defs, f{{{SVG_NS}}}linearGradient, { id: gradient_id, x1: 0%, y1: 0%, x2: 100%, y2: 100%, }) stop1 ET.SubElement(linear_gradient, f{{{SVG_NS}}}stop, { offset: 0%, style: fstop-color:{c1};stop-opacity:1, }) stop2 ET.SubElement(linear_gradient, f{{{SVG_NS}}}stop, { offset: 100%, style: fstop-color:{c2};stop-opacity:1, }) # 圆角矩形节点 rect ET.SubElement(svg, f{{{SVG_NS}}}rect, { x: str(x), y: str(y), width: str(COMPONENT_WIDTH), height: str(COMPONENT_HEIGHT), rx: 10, fill: furl(#{gradient_id}), stroke: #FFFFFF, stroke-width: 2, }) # 组件名称文字 text ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(x COMPONENT_WIDTH / 2), y: str(y COMPONENT_HEIGHT / 2 6), text-anchor: middle, font-size: 14, font-weight: bold, fill: COMPONENT_TEXT_COLOR, }) text.text name def draw_connection(svg, x1, y1, x2, y2): 绘制连线带箭头。 line ET.SubElement(svg, f{{{SVG_NS}}}line, { x1: str(x1), y1: str(y1), x2: str(x2), y2: str(y2), stroke: LINE_COLOR, stroke-width: 2, }) # 箭头标记 marker_id arrowhead defs svg.find(f{{{SVG_NS}}}defs) if defs is None: defs ET.SubElement(svg, f{{{SVG_NS}}}defs) marker ET.SubElement(defs, f{{{SVG_NS}}}marker, { id: marker_id, markerWidth: 10, markerHeight: 7, refX: 10, refY: 3.5, orient: auto, }) polygon ET.SubElement(marker, f{{{SVG_NS}}}polygon, { points: 0 0, 10 3.5, 0 7, fill: LINE_COLOR, }) line.set(marker-end, furl(#{marker_id})) def calc_layout(arch): 根据 layers 计算每个组件的位置。 返回 { 组件名: (x, y) } 字典。 positions {} layers arch.get(layers, []) # 动态计算画布高度 estimated_height HEADER_HEIGHT len(layers) * (COMPONENT_HEIGHT LAYER_GAP) PADDING canvas_height max(CANVAS_HEIGHT, estimated_height) current_y HEADER_HEIGHT LAYER_GAP // 2 for layer in layers: components layer.get(components, []) count len(components) # 计算整层总宽度 total_width count * COMPONENT_WIDTH (count - 1) * COMPONENT_GAP start_x (CANVAS_WIDTH - total_width) / 2 # 层背景高度 layer_height COMPONENT_HEIGHT 40 # 绘制层背景留到渲染阶段这里先记录每层 y 位置 layer[_y] current_y layer[_height] layer_height for i, comp in enumerate(components): x start_x i * (COMPONENT_WIDTH COMPONENT_GAP) y current_y 30 positions[comp] (x, y) current_y layer_height LAYER_GAP return positions, canvas_height def render(arch): 生成 SVG 字符串。 positions, canvas_height calc_layout(arch) svg_root create_svg_root(arch.get(title, 系统架构图), CANVAS_WIDTH, canvas_height) # 注意create_svg_root 里没有画背景先补一个 bg ET.SubElement(svg_root, f{{{SVG_NS}}}rect, { x: 0, y: 0, width: str(CANVAS_WIDTH), height: str(canvas_height), fill: BG_COLOR, }) # 先画连线放在节点下层避免遮挡文字 for conn in arch.get(connections, []): src conn[0] dst conn[1] if src not in positions or dst not in positions: continue x1, y1 positions[src] x2, y2 positions[dst] # 起点组件底部中心 line_x1 x1 COMPONENT_WIDTH / 2 line_y1 y1 COMPONENT_HEIGHT # 终点组件顶部中心 line_x2 x2 COMPONENT_WIDTH / 2 line_y2 y2 # 如果终点在起点上方则使用起点顶部、终点底部反向依赖 if y2 y1: line_y1 y1 line_y2 y2 COMPONENT_HEIGHT draw_connection(svg_root, line_x1, line_y1, line_x2, line_y2) # 画层背景 for layer in arch.get(layers, []): y layer.get(_y, 0) h layer.get(_height, 0) draw_layer(svg_root, y, h, layer.get(name, )) # 画组件节点 for layer in arch.get(layers, []): for comp in layer.get(components, []): x, y positions[comp] add_component(svg_root, x, y, comp) # 转成字符串 ET.indent(svg_root, space ) return ET.tostring(svg_root, encodingunicode, methodxml) def main(): if len(sys.argv) 3: print(用法: python3 render_arch.py 架构描述.json 输出.svg) sys.exit(1) input_path sys.argv[1] output_path sys.argv[2] with open(input_path, r, encodingutf-8) as f: arch json.load(f) svg_str render(arch) with open(output_path, w, encodingutf-8) as f: f.write(svg_str) print(f架构图已生成: {output_path}) if __name__ __main__: main()这个脚本的核心逻辑分三块calc_layout计算每个组件的坐标按分层布局同层组件水平居中排列。draw_connection绘制组件之间的连线使用 SVG 的 marker 画箭头。add_component绘制带渐变背景的组件节点不同组件使用不同颜色。需要说明的是这个脚本为了保持篇幅可读性做了不少简化。实际项目中你还可以优化节点之间的折线、组件描述文字、自动调整画布高度、外部系统边界框等。4.4 创建示例架构描述创建一个测试文件examples/ecommerce.json{ title: 电商系统架构图, layers: [ { name: 客户端层, components: [Web 前端, 移动端] }, { name: 网关层, components: [API 网关] }, { name: 服务层, components: [订单服务, 库存服务, 支付服务] }, { name: 数据层, components: [MySQL, Redis] } ], connections: [ [Web 前端, API 网关], [移动端, API 网关], [API 网关, 订单服务], [API 网关, 库存服务], [API 网关, 支付服务], [订单服务, MySQL], [订单服务, Redis], [库存服务, MySQL], [支付服务, MySQL] ] }4.5 运行与验证第一步手动运行脚本验证逻辑cd ~/.claude/skills/architecture-diagram python3 scripts/render_arch.py examples/ecommerce.json examples/ecommerce.svg看到输出架构图已生成: examples/ecommerce.svg用浏览器打开 SVG 文件你会看到一张完整的分层架构图顶部是标题下面依次是客户端层、网关层、服务层、数据层组件之间有带箭头的连线。如果 SVG 文件可以正常显示说明脚本逻辑没问题。4.6 在 Agent 中测试完整流程现在打开你的 Agent 工具Claude Code 或 Codex CLI进入 Skill 目录输入帮我画一个订单系统的架构图包括小程序、Web 管理后台、订单服务、用户服务、消息队列、MySQL 和 Redis。Agent 读取 SKILL.md 后会按步骤执行解析描述提取组件。生成arch.json。调用渲染脚本。输出output.svg。你就能在目录下看到新生成的 SVG 文件。如果运气好一次成功如果没成功就需要进入排查环节。5. 常见问题与排查思路自己在本地折腾这套 Skill 时一定会遇到各种报错。我把高频问题整理成了表格方便你排查问题现象常见原因解决思路Python 报错ModuleNotFoundError: No module named xmlPython 环境异常或版本过低使用 Python 3.10 以上版本SVG 打开后是空白SVG 的 XML 标签生成失败检查render_arch.py中ET.tostring是否有异常组件名变成department_123这类怪名字Agent 没有遵守 SKILL.md 的命名规范在 SKILL.md 示例中补充“不良命名”反例组件重叠严重同一层组件数量过多超出画布宽度减少组件数量或增加画布宽度连线从组件中间穿过连线算法没有考虑折线改用正交折线先垂直后水平Skill 不触发SKILL.md 的description没有覆盖用户的表达方式在 description 中增加更多触发词如“系统图”“模块图”“部署架构”Agent 输出的是 Mermaid 而不是 SVGAgent 没有严格遵循 Skill 指令在 SKILL.md 中增加“禁止输出 Mermaid必须使用 SVG”的规则中文乱码SVG 字体不支持中文在 SVG 根元素中设置font-family并确保系统安装了中文字体5.1 Agent 不触发 Skill 怎么办这是最常见的问题。很多 Agent 不是“知道了 Skill 路径就会主动用”而是每次都会扫描所有 Skill 的description字段判断当前用户请求是否匹配。解决方案把触发条件写得更宽泛。--- name: architecture-diagram description: 架构图、系统图、模块图、部署架构图、技术架构图、业务架构图、拓扑图、调用链图。当用户要求“画/生成/输出”以上任意一种图时立即使用该Skill。 ---5.2 连线交叉太多怎么办架构图里连线交叉是难免的但可以通过两个策略减少在 SKILL.md 中要求 Agent 尽量让连线只发生在相邻层之间。在渲染脚本中把跨层连线改成“从组件右侧或左侧绕行”的正交路径。5.3 组件太多放不下怎么办如果一个层有 8 个以上组件横向排列会非常拥挤。这时候可以在 SKILL.md 中增加规则超过 6 个组件时需要对组件进行合并或分组。比如“订单服务、库存服务、支付服务、用户服务、营销服务、物流服务、评价服务、优惠券服务”这 8 个服务可以合并为两组核心交易服务订单、库存、支付和支撑服务用户、营销、物流、评价、优惠券。6. 最佳实践与工程建议6.1 让 Skill 输出可解释、可追溯我们在使用这个 Skill 时强烈建议让 Agent 在生成 JSON 之后、渲染 SVG 之前先输出一份“架构理解说明”。比如我理解您的系统包含以下核心组件 1. 客户端层小程序、Web 管理后台 2. 网关层API 网关负责统一鉴权和路由 3. 服务层订单服务、用户服务、消息队列 4. 数据层MySQL业务数据、Redis缓存 连线关系小程序 → API 网关 → 订单服务 → MySQL 与 Redis这一步看起来多余但很有用。它相当于让 AI“复述需求”能很大程度避免理解偏差。如果 AI 理解错了你可以在渲染前叫停。6.2 把 arch.json 变成可编辑的中间产物很多时候AI 生成的结果不可能一次完美。我们会人工调整架构。如果中间结果是 JSON 而不是直接 SVN修改成本就更低。建议流程是Agent 生成arch.json。你审查 JSON手动调整组件名、层级、连线。运行脚本生成 SVG。把 SVG 嵌入文档或导入 Figma、PPT。这个流程里JSON 是“源文件”SVG 是“产物”。只要保留源文件后续改架构就只是改一行 JSON 的事而不是重新画图。6.3 统一颜色语义在真实项目中架构图的颜色是有业务含义的。比如蓝色自研核心服务绿色第三方服务或外部依赖橙色中间件/消息队列红色可能存在风险或高负债模块建议在 SKILL.md 里把这些颜色规则写进去。这样无论谁触发AI 画出来的图风格都统一。6.4 考虑多 Agent 协作场景架构图 Skill 不只是给“画图”用的。它还可以作为其他 Agent 的“工具”。比如代码分析 Agent 发现某个服务调用链特别长于是调用架构图 Skill 自动输出当前系统的调用拓扑图。运维 Agent 在故障排查时调用架构图 Skill 画出当前请求链路帮助定位瓶颈。这种情况下Skill 的输入不只是用户的一句话而是另一个 Agent 传递的结构化数据。所以在设计 JSON Schema 时要尽量考虑这种可编程调用场景字段命名要稳定注释要写清楚。6.5 安全与权限边界如果你的 Agent 能读写本地文件那么 Skill 脚本实际上拥有操作你电脑文件系统的权限。需要注意几点渲染脚本只应该读指定的 JSON 文件、写指定的 SVG 文件不要提供任意文件删除或覆盖功能。不要让 Agent 使用eval()或exec()执行用户输入的代码——尤其是当用户输入可能来自不可信来源时。如果 Skill 需要联网比如调用某个图片托管服务要遵循最小权限原则只对需要的域名发起请求。6.6 性能优化方向当前渲染脚本使用纯 Python 和 XML 元素树实际上几百个节点也毫无压力。但如果你想做更复杂的架构图可能需要考虑布局算法升级从简单分层升级为“分层 同层排序”减少连线交叉。缓存机制当架构 JSON 不变时不重复渲染 SVG。多格式输出在生成 SVG 的同时调用rsvg-convert或Inkscape导出 PNG 用于文档预览。7. 总结与下一步学习建议这篇文章从 Skill 的基本概念开始解释了为什么“一句话画出系统架构图”是可行的本质上不是让 AI 直接画图而是让 AI 先结构化理解需求再通过脚本进行精确渲染。亲手搭完这套 Skill 后你应该已经掌握了Skill 的目录结构和 SKILL.md 编写方法。架构图从 JSON 描述到 SVG 渲染的完整流程。分层布局的坐标计算思路。常见问题和排查手段。架构图 Skill 在真实项目中的最佳实践边界。接下来如果你还想继续深入有几个方向值得研究Mermaid / DrawIO 兼容输出在渲染脚本中增加输出格式参数一次生成多种格式方便在不同文档平台使用。动态系统拓扑把 Skill 和监控系统打通根据实时调用链数据自动生成架构拓扑图。多 Skill 协同结合“日志分析 Skill”和“架构图 Skill”自动定位系统瓶颈并生成问题链路图。这套思路最值钱的地方不是脚本本身而是**“AI 负责语义理解脚本负责精确计算”的分工模式**。把这个模式迁移到 PPT 生成、数据库设计、接口文档生成等场景你会打开一片新天地。如果这篇文章对你有帮助建议收藏备用也欢迎在评论区分享你写 Skill 时遇到的有趣问题。 AI Agent Skill 实战：一句话生成专业系统架构图
过去这段时间AI Agent 领域最热的关键词已经不只是“写代码”“做分析”而是大量出现了一个词Skill。从 Claude Code 到 Codex再到各类开源 Agent 框架Skill 都成了让 AI 更“懂行”的核心玩法。而在众多 Skill 里有一类特别吸引眼球一句话画出系统架构图。之前我在做项目梳理时经常卡在“给新同学讲架构”这个环节。画图工具用了一堆Visio 太重draw.io 要手动拖拽ProcessOn 免费版又有数量限制。后来接触到 AI Agent Skill 的方案后发现只要把架构描述说清楚AI 就能自动生成一张可编辑、可维护的架构图。这篇文章就把这套玩法的原理、Skill 编写方式、完整代码和常见坑位一次讲清楚。无论你是后端开发、架构师还是刚接触 AI Agent 的初学者这篇文章都会给你一套可以直接复用的思路。1. 背景与核心概念Skill 到底是什么1.1 从“AI 会聊天”到“AI 能干活”很多人第一次用 ChatGPT、Claude 这类助手时会觉得 AI 很聪明但不够稳定。同一个问题换个问法答案就不一样让它做一个稍微复杂一点的任务它很容易在中途“跑偏”。这是因为通用大模型本身是一个“语言模型”它擅长的是根据上下文预测下一个词语而不是严格地按流程执行任务。所谓“能干活的 AI”本质上是在大模型外面套了一层工程壳给它明确的角色设定、给它工具、给它步骤、给它示例它才能把任务拆解并执行到位。Skill技能就是这层工程壳的一种标准化形态。1.2 Skill 的精确定义Skill 在 AI Agent 生态里通常指一套结构化指令 示例 可选脚本/工具的集合。它把一个特定领域的工作流固化下来让 Agent 在遇到相关任务时能按照约定好的方式去思考、去调用工具、去输出结果。用一句话概括Skill 是给 Agent 写的“岗位说明书 操作手册”。以“系统架构图 Skill”为例一个完整的 Skill 至少要回答这些问题什么场景下触发用户说“帮我画个架构图”按照什么步骤做先确认系统边界再梳理组件再画连线输出什么格式SVG、DrawIO XML还是 Mermaid有哪些规则要遵守节点命名规范、层级不超过几层、颜色语义有哪些示例可以参考给 2 到 3 个标杆案例Agent 接到用户请求时会先判断这个请求是否符合某个 Skill 的触发条件如果符合就加载这个 Skill 的说明文件按照里面的步骤和约束去执行。1.3 Skill 和 Agent 的区别这个区别是很多初学者最容易混淆的。我把它们比作“员工”和“公司制度”的关系维度Agent智能体Skill技能本质一个能自主决策、执行任务的 AI 实体一组针对特定任务的指令和工具集合是否独立运行是Agent 可以自己规划任务否Skill 需要被 Agent 加载执行持久性有一定“记忆”和上下文无状态每次加载时重新读取类比一个能干的员工员工手里的标准作业指导书换句话说一个 Agent 可以同时挂载多个 Skill。比如同一个 Agent 既能写代码代码生成 Skill又能画架构图架构图 Skill还能做日志分析日志分析 Skill。Skill 之间彼此独立互不干扰。1.4 为什么“系统架构图 Skill”最近很火原因有三个架构图是刚需开发、汇报、文档、面试、答辩几乎每个技术场景都需要架构图。通用画图工具效率低手动拖拽、调整布局、统一配色非常耗时改一版需求往往要重画。大模型 Skill 补齐了稳定性和专业性给 AI 一套架构图生成规则它就能稳定地输出符合规范的结果而不是每次瞎画。所以这一波热词里“archify skill”“drawio skill”“ppt skill”爆火不是偶然说明大家都发现了“专业场景 Skill”的巨大价值。2. 环境准备搭建 Skill 运行环境2.1 环境选型Skill 本身是“说明文件 脚本”它需要一个宿主环境来运行。目前常见的宿主有三种Claude Code / Codex 等命令行 Agent 工具直接在终端里对话Agent 能读写本地文件、执行脚本最适合开发场景。OpenClaw / Dify / Coze 等 Agent 平台图形化界面适合配置复杂工作流但部分平台对本地文件操作支持较弱。自研 Agent 框架LangGraph、AutoGen 等适合二次开发灵活度高但需要自己实现 Skill 加载逻辑。本文以“命令行 Agent 本地脚本 SVG 输出”为例原因是这套方案最容易复现不依赖特定云平台也不受在线服务限制。2.2 我使用的环境说明为了避免误导先说明我这里的测试环境操作系统macOS / Linux 均可Windows 需要调整脚本路径语法语言环境Python 3.10 以上Agent 工具支持 Skill 机制的 CLI Agent 工具Claude Code、Codex CLI 等均可图表输出标准 SVG 文件 PNG 预览可选具体版本不写死因为此类工具迭代非常快。本文重点演示 Skill 的编写思路和完整代码版本差异一般不影响核心逻辑。2.3 确认 Skill 目录结构大多数 Agent 工具都约定了一个 Skill 目录规则。我们以一个典型的 Agent Skills 目录结构为例~/.claude/skills/ # 或者其他 Agent 的 skills 目录 └── architecture-diagram/ # Skill 名称建议使用小写中划线 ├── SKILL.md # Skill 说明文件Agent 会优先读取 ├── scripts/ # 辅助脚本 │ └── render_arch.py # 根据描述生成 SVG 架构图 └── examples/ # 示例输出供 Agent 参考 └── order-system.svg如果你的 Agent 工具没有内置 Skill 机制也可以把这段逻辑做成一个自部署的提示词模板 脚本工具本质是一样的。2.4 验证运行环境先执行一个最简单的 Python 脚本确保环境正常python3 --version如果能输出版本号说明 Python 环境没有大问题。接下来我们继续创建一个临时目录用于存放 Skill 文件mkdir -p ~/.claude/skills/architecture-diagram cd ~/.claude/skills/architecture-diagram3. 画架构图 Skill 的原理拆解3.1 两条技术路线对比在动手写代码之前要先想清楚一个问题AI 应该用什么格式“画”架构图目前主流的方案有三类方案优点缺点适用场景Mermaid语法简单GitHub/Notion 原生支持复杂布局不灵活连线容易乱快速记录、简单流程Graphviz DOT自动布局能力强大语法繁琐样式调整麻烦自动化生成、大量节点SVG完全可控支持任意布局和样式生成复杂度高需要代码辅助正式架构图、高质量输出我选择 SVG。理由很简单架构图最终要给人看要放到 PPT 和文档里SVG 无限缩放、可编辑、可嵌入网页、可以用脚本精确控制每个节点位置。相比之下Mermaid 更适合画流程图而不是正式架构图。3.2 Skill 的整体工作流程这套 Skill 的工作流程分三层理解层Agent 读取用户的一句话描述提取核心组件、依赖关系和外部系统。结构化层Agent 按照固定 JSON Schema 输出一份“架构描述”文件。渲染层Python 脚本读取 JSON 文件自动计算布局生成 SVG 架构图。为什么不让 AI 直接生成 SVG因为大模型直接输出 SVG 时节点坐标全靠“蒙”经常重叠、超出画布。而先输出结构化的 JSON再由脚本做布局计算既利用了 AI 的语义理解能力又利用了程序的计算能力稳定性和可维护性都高很多。3.3 架构描述 JSON 的设计为了让 Agent 稳定输出我们需要定义一份严格的 JSON 格式。下面是一个最小可用的 Schema{ title: 订单系统架构图, layers: [ { name: 接入层, components: [Web 前端, 移动端] }, { name: 应用层, components: [订单服务, 用户服务, 支付服务] }, { name: 数据层, components: [MySQL, Redis] } ], connections: [ [Web 前端, 订单服务], [订单服务, MySQL], [订单服务, Redis] ] }这个结构有四个字段title图的标题显示在顶部。layers分层结构每层有一个名称和组件列表。架构图按层布局同一层的组件水平排列层与层之间垂直排列。connections连线关系数组里每个元素是一个二元组表示“从 A 到 B 有一条连线”。其实还可以扩展externalSystems、descriptions等字段但保持最小结构能让 Agent 更容易遵循。3.4 为什么用“分层”而不是“自由布局”系统架构图最经典的表达方式就是分层用户体验层接入层应用服务层数据存储层基础设施层分层布局的优势很明显阅读顺序自然从上到下就是一次请求的流转路径。布局算法简单同一层组件水平排列即可不需要复杂的力导向算法。视觉上更专业符合大多数架构图读者的阅读习惯。渲染脚本的核心逻辑就是按层从上到下排列层内组件从左到右排列。4. 完整实战从零创建一个架构图 Skill4.1 创建项目结构先创建 Skill 目录和子目录mkdir -p ~/.claude/skills/architecture-diagram/{scripts,examples}创建完成后目录结构如下architecture-diagram/ ├── SKILL.md ├── scripts/ │ └── render_arch.py └── examples/4.2 编写 SKILL.md 说明文件这是整个 Skill 的灵魂。Agent 读到这个文件后才能知道自己的任务是“画架构图”而不是随便聊聊。--- name: architecture-diagram description: 根据用户的一句话系统描述生成分层系统架构图SVG 格式。 --- # Architecture Diagram Skill 当用户要求“画架构图”、“画系统图”、“输出系统架构图”时使用本 Skill。 ## 执行步骤 1. 解析用户提供的系统描述提取系统名称、各层组件、组件之间的依赖关系。 2. 如果用户描述不清晰必须主动追问直到确认以下信息 - 系统包含哪些主要组件 - 组件之间谁调用谁 - 是否需要区分外部系统和内部系统 3. 按照下面的 JSON Schema 生成架构描述保存为 arch.json。 4. 调用渲染脚本 bash python3 scripts/render_arch.py arch.json output.svg检查 SVG 是否生成成功然后向用户展示结果。JSON Schema只允许输出以下结构的 JSON不要添加多余字段{ title: string, layers: [ { name: string, components: [string] } ], connections: [ [string, string] ] }规则组件名称要简洁优先使用业务名词而不是技术名词如“订单服务”而不是“OrderService_Core_Impl_2024”。层数量控制在 3 到 6 层超过 6 层时合并相关组件。连线只表达核心依赖不要把 20 条细节调用关系全部画出来。每个组件必须有至少一条连线否则删除该组件或补充连线。所有输出和解释使用中文。示例用户说画一个电商系统架构图包含前端、网关、订单、库存、支付、MySQL 和 Redis。合理的 JSON 如下{ title: 电商系统架构图, layers: [ {name: 客户端层, components: [Web 前端, 移动端]}, {name: 网关层, components: [API 网关]}, {name: 服务层, components: [订单服务, 库存服务, 支付服务]}, {name: 数据层, components: [MySQL, Redis]} ], connections: [ [Web 前端, API 网关], [移动端, API 网关], [API 网关, 订单服务], [API 网关, 库存服务], [API 网关, 支付服务], [订单服务, MySQL], [订单服务, Redis], [库存服务, MySQL], [支付服务, MySQL] ] }## 错误处理 - 如果 render_arch.py 执行报错先检查 JSON 是否缺少字段再检查 Python 脚本是否能正常运行。 - 如果 SVG 中节点重叠提示用户减少同一层的组件数量。这里有一个细节值得注意SKILL.md 里包含一个完整示例。示例是 Skill 稳定性的关键。大模型本质上在做模式匹配你给的例子越接近真实场景它输出就越稳定。4.3 编写核心渲染脚本接下来是重头戏渲染脚本。这个脚本读取 JSON计算布局输出 SVG。#!/usr/bin/env python3 # -*- coding: utf-8 -*- # 文件路径scripts/render_arch.py 读取架构描述 JSON生成分层系统架构图 SVG。 用法 python3 render_arch.py arch.json output.svg import json import sys import xml.etree.ElementTree as ET from xml.sax.saxutils import escape # 画布配置 CANVAS_WIDTH 1200 CANVAS_HEIGHT 800 PADDING 60 LAYER_GAP 80 COMPONENT_GAP 40 COMPONENT_WIDTH 180 COMPONENT_HEIGHT 60 HEADER_HEIGHT 80 # 颜色配置 BG_COLOR #FFFFFF LAYER_BG_COLOR #F8FAFC LAYER_BORDER_COLOR #E2E8F0 COMPONENT_BG_START #3B82F6 COMPONENT_BG_END #2563EB COMPONENT_TEXT_COLOR #FFFFFF TITLE_COLOR #1E293B LAYER_TITLE_COLOR #475569 LINE_COLOR #94A3B8 # SVG 命名空间让输出的 SVG 能在浏览器正常显示 SVG_NS http://www.w3.org/2000/svg ET.register_namespace(, SVG_NS) def create_svg_root(title, width, height): 创建 SVG 根元素。 svg ET.Element(f{{{SVG_NS}}}svg, { width: str(width), height: str(height), viewBox: f0 0 {width} {height}, xmlns: SVG_NS, font-family: Arial, PingFang SC, Microsoft YaHei, sans-serif, }) # 顶部标题 title_text ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(width / 2), y: 40, text-anchor: middle, font-size: 24, font-weight: bold, fill: TITLE_COLOR, }) title_text.text title return svg def draw_layer(svg, y, height, name): 绘制分层背景。 rect ET.SubElement(svg, f{{{SVG_NS}}}rect, { x: str(PADDING), y: str(y), width: str(CANVAS_WIDTH - 2 * PADDING), height: str(height), fill: LAYER_BG_COLOR, stroke: LAYER_BORDER_COLOR, stroke-width: 1.5, rx: 12, }) # 层名称 label ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(PADDING 16), y: str(y 28), font-size: 16, font-weight: bold, fill: LAYER_TITLE_COLOR, }) label.text name return rect def add_component(svg, x, y, name): 在指定位置绘制一个组件节点带渐变背景。 # 定义渐变不同组件使用不同颜色方便区分 gradient_id fgrad_{abs(hash(name)) % 10000} defs svg.find(f{{{SVG_NS}}}defs) if defs is None: defs ET.SubElement(svg, f{{{SVG_NS}}}defs) # 根据组件名选择颜色简单起见按哈希选色 colors [ (#3B82F6, #2563EB), (#10B981, #059669), (#F59E0B, #D97706), (#EF4444, #DC2626), (#8B5CF6, #6D28D9), (#EC4899, #DB2777), ] idx abs(hash(name)) % len(colors) c1, c2 colors[idx] linear_gradient ET.SubElement(defs, f{{{SVG_NS}}}linearGradient, { id: gradient_id, x1: 0%, y1: 0%, x2: 100%, y2: 100%, }) stop1 ET.SubElement(linear_gradient, f{{{SVG_NS}}}stop, { offset: 0%, style: fstop-color:{c1};stop-opacity:1, }) stop2 ET.SubElement(linear_gradient, f{{{SVG_NS}}}stop, { offset: 100%, style: fstop-color:{c2};stop-opacity:1, }) # 圆角矩形节点 rect ET.SubElement(svg, f{{{SVG_NS}}}rect, { x: str(x), y: str(y), width: str(COMPONENT_WIDTH), height: str(COMPONENT_HEIGHT), rx: 10, fill: furl(#{gradient_id}), stroke: #FFFFFF, stroke-width: 2, }) # 组件名称文字 text ET.SubElement(svg, f{{{SVG_NS}}}text, { x: str(x COMPONENT_WIDTH / 2), y: str(y COMPONENT_HEIGHT / 2 6), text-anchor: middle, font-size: 14, font-weight: bold, fill: COMPONENT_TEXT_COLOR, }) text.text name def draw_connection(svg, x1, y1, x2, y2): 绘制连线带箭头。 line ET.SubElement(svg, f{{{SVG_NS}}}line, { x1: str(x1), y1: str(y1), x2: str(x2), y2: str(y2), stroke: LINE_COLOR, stroke-width: 2, }) # 箭头标记 marker_id arrowhead defs svg.find(f{{{SVG_NS}}}defs) if defs is None: defs ET.SubElement(svg, f{{{SVG_NS}}}defs) marker ET.SubElement(defs, f{{{SVG_NS}}}marker, { id: marker_id, markerWidth: 10, markerHeight: 7, refX: 10, refY: 3.5, orient: auto, }) polygon ET.SubElement(marker, f{{{SVG_NS}}}polygon, { points: 0 0, 10 3.5, 0 7, fill: LINE_COLOR, }) line.set(marker-end, furl(#{marker_id})) def calc_layout(arch): 根据 layers 计算每个组件的位置。 返回 { 组件名: (x, y) } 字典。 positions {} layers arch.get(layers, []) # 动态计算画布高度 estimated_height HEADER_HEIGHT len(layers) * (COMPONENT_HEIGHT LAYER_GAP) PADDING canvas_height max(CANVAS_HEIGHT, estimated_height) current_y HEADER_HEIGHT LAYER_GAP // 2 for layer in layers: components layer.get(components, []) count len(components) # 计算整层总宽度 total_width count * COMPONENT_WIDTH (count - 1) * COMPONENT_GAP start_x (CANVAS_WIDTH - total_width) / 2 # 层背景高度 layer_height COMPONENT_HEIGHT 40 # 绘制层背景留到渲染阶段这里先记录每层 y 位置 layer[_y] current_y layer[_height] layer_height for i, comp in enumerate(components): x start_x i * (COMPONENT_WIDTH COMPONENT_GAP) y current_y 30 positions[comp] (x, y) current_y layer_height LAYER_GAP return positions, canvas_height def render(arch): 生成 SVG 字符串。 positions, canvas_height calc_layout(arch) svg_root create_svg_root(arch.get(title, 系统架构图), CANVAS_WIDTH, canvas_height) # 注意create_svg_root 里没有画背景先补一个 bg ET.SubElement(svg_root, f{{{SVG_NS}}}rect, { x: 0, y: 0, width: str(CANVAS_WIDTH), height: str(canvas_height), fill: BG_COLOR, }) # 先画连线放在节点下层避免遮挡文字 for conn in arch.get(connections, []): src conn[0] dst conn[1] if src not in positions or dst not in positions: continue x1, y1 positions[src] x2, y2 positions[dst] # 起点组件底部中心 line_x1 x1 COMPONENT_WIDTH / 2 line_y1 y1 COMPONENT_HEIGHT # 终点组件顶部中心 line_x2 x2 COMPONENT_WIDTH / 2 line_y2 y2 # 如果终点在起点上方则使用起点顶部、终点底部反向依赖 if y2 y1: line_y1 y1 line_y2 y2 COMPONENT_HEIGHT draw_connection(svg_root, line_x1, line_y1, line_x2, line_y2) # 画层背景 for layer in arch.get(layers, []): y layer.get(_y, 0) h layer.get(_height, 0) draw_layer(svg_root, y, h, layer.get(name, )) # 画组件节点 for layer in arch.get(layers, []): for comp in layer.get(components, []): x, y positions[comp] add_component(svg_root, x, y, comp) # 转成字符串 ET.indent(svg_root, space ) return ET.tostring(svg_root, encodingunicode, methodxml) def main(): if len(sys.argv) 3: print(用法: python3 render_arch.py 架构描述.json 输出.svg) sys.exit(1) input_path sys.argv[1] output_path sys.argv[2] with open(input_path, r, encodingutf-8) as f: arch json.load(f) svg_str render(arch) with open(output_path, w, encodingutf-8) as f: f.write(svg_str) print(f架构图已生成: {output_path}) if __name__ __main__: main()这个脚本的核心逻辑分三块calc_layout计算每个组件的坐标按分层布局同层组件水平居中排列。draw_connection绘制组件之间的连线使用 SVG 的 marker 画箭头。add_component绘制带渐变背景的组件节点不同组件使用不同颜色。需要说明的是这个脚本为了保持篇幅可读性做了不少简化。实际项目中你还可以优化节点之间的折线、组件描述文字、自动调整画布高度、外部系统边界框等。4.4 创建示例架构描述创建一个测试文件examples/ecommerce.json{ title: 电商系统架构图, layers: [ { name: 客户端层, components: [Web 前端, 移动端] }, { name: 网关层, components: [API 网关] }, { name: 服务层, components: [订单服务, 库存服务, 支付服务] }, { name: 数据层, components: [MySQL, Redis] } ], connections: [ [Web 前端, API 网关], [移动端, API 网关], [API 网关, 订单服务], [API 网关, 库存服务], [API 网关, 支付服务], [订单服务, MySQL], [订单服务, Redis], [库存服务, MySQL], [支付服务, MySQL] ] }4.5 运行与验证第一步手动运行脚本验证逻辑cd ~/.claude/skills/architecture-diagram python3 scripts/render_arch.py examples/ecommerce.json examples/ecommerce.svg看到输出架构图已生成: examples/ecommerce.svg用浏览器打开 SVG 文件你会看到一张完整的分层架构图顶部是标题下面依次是客户端层、网关层、服务层、数据层组件之间有带箭头的连线。如果 SVG 文件可以正常显示说明脚本逻辑没问题。4.6 在 Agent 中测试完整流程现在打开你的 Agent 工具Claude Code 或 Codex CLI进入 Skill 目录输入帮我画一个订单系统的架构图包括小程序、Web 管理后台、订单服务、用户服务、消息队列、MySQL 和 Redis。Agent 读取 SKILL.md 后会按步骤执行解析描述提取组件。生成arch.json。调用渲染脚本。输出output.svg。你就能在目录下看到新生成的 SVG 文件。如果运气好一次成功如果没成功就需要进入排查环节。5. 常见问题与排查思路自己在本地折腾这套 Skill 时一定会遇到各种报错。我把高频问题整理成了表格方便你排查问题现象常见原因解决思路Python 报错ModuleNotFoundError: No module named xmlPython 环境异常或版本过低使用 Python 3.10 以上版本SVG 打开后是空白SVG 的 XML 标签生成失败检查render_arch.py中ET.tostring是否有异常组件名变成department_123这类怪名字Agent 没有遵守 SKILL.md 的命名规范在 SKILL.md 示例中补充“不良命名”反例组件重叠严重同一层组件数量过多超出画布宽度减少组件数量或增加画布宽度连线从组件中间穿过连线算法没有考虑折线改用正交折线先垂直后水平Skill 不触发SKILL.md 的description没有覆盖用户的表达方式在 description 中增加更多触发词如“系统图”“模块图”“部署架构”Agent 输出的是 Mermaid 而不是 SVGAgent 没有严格遵循 Skill 指令在 SKILL.md 中增加“禁止输出 Mermaid必须使用 SVG”的规则中文乱码SVG 字体不支持中文在 SVG 根元素中设置font-family并确保系统安装了中文字体5.1 Agent 不触发 Skill 怎么办这是最常见的问题。很多 Agent 不是“知道了 Skill 路径就会主动用”而是每次都会扫描所有 Skill 的description字段判断当前用户请求是否匹配。解决方案把触发条件写得更宽泛。--- name: architecture-diagram description: 架构图、系统图、模块图、部署架构图、技术架构图、业务架构图、拓扑图、调用链图。当用户要求“画/生成/输出”以上任意一种图时立即使用该Skill。 ---5.2 连线交叉太多怎么办架构图里连线交叉是难免的但可以通过两个策略减少在 SKILL.md 中要求 Agent 尽量让连线只发生在相邻层之间。在渲染脚本中把跨层连线改成“从组件右侧或左侧绕行”的正交路径。5.3 组件太多放不下怎么办如果一个层有 8 个以上组件横向排列会非常拥挤。这时候可以在 SKILL.md 中增加规则超过 6 个组件时需要对组件进行合并或分组。比如“订单服务、库存服务、支付服务、用户服务、营销服务、物流服务、评价服务、优惠券服务”这 8 个服务可以合并为两组核心交易服务订单、库存、支付和支撑服务用户、营销、物流、评价、优惠券。6. 最佳实践与工程建议6.1 让 Skill 输出可解释、可追溯我们在使用这个 Skill 时强烈建议让 Agent 在生成 JSON 之后、渲染 SVG 之前先输出一份“架构理解说明”。比如我理解您的系统包含以下核心组件 1. 客户端层小程序、Web 管理后台 2. 网关层API 网关负责统一鉴权和路由 3. 服务层订单服务、用户服务、消息队列 4. 数据层MySQL业务数据、Redis缓存 连线关系小程序 → API 网关 → 订单服务 → MySQL 与 Redis这一步看起来多余但很有用。它相当于让 AI“复述需求”能很大程度避免理解偏差。如果 AI 理解错了你可以在渲染前叫停。6.2 把 arch.json 变成可编辑的中间产物很多时候AI 生成的结果不可能一次完美。我们会人工调整架构。如果中间结果是 JSON 而不是直接 SVN修改成本就更低。建议流程是Agent 生成arch.json。你审查 JSON手动调整组件名、层级、连线。运行脚本生成 SVG。把 SVG 嵌入文档或导入 Figma、PPT。这个流程里JSON 是“源文件”SVG 是“产物”。只要保留源文件后续改架构就只是改一行 JSON 的事而不是重新画图。6.3 统一颜色语义在真实项目中架构图的颜色是有业务含义的。比如蓝色自研核心服务绿色第三方服务或外部依赖橙色中间件/消息队列红色可能存在风险或高负债模块建议在 SKILL.md 里把这些颜色规则写进去。这样无论谁触发AI 画出来的图风格都统一。6.4 考虑多 Agent 协作场景架构图 Skill 不只是给“画图”用的。它还可以作为其他 Agent 的“工具”。比如代码分析 Agent 发现某个服务调用链特别长于是调用架构图 Skill 自动输出当前系统的调用拓扑图。运维 Agent 在故障排查时调用架构图 Skill 画出当前请求链路帮助定位瓶颈。这种情况下Skill 的输入不只是用户的一句话而是另一个 Agent 传递的结构化数据。所以在设计 JSON Schema 时要尽量考虑这种可编程调用场景字段命名要稳定注释要写清楚。6.5 安全与权限边界如果你的 Agent 能读写本地文件那么 Skill 脚本实际上拥有操作你电脑文件系统的权限。需要注意几点渲染脚本只应该读指定的 JSON 文件、写指定的 SVG 文件不要提供任意文件删除或覆盖功能。不要让 Agent 使用eval()或exec()执行用户输入的代码——尤其是当用户输入可能来自不可信来源时。如果 Skill 需要联网比如调用某个图片托管服务要遵循最小权限原则只对需要的域名发起请求。6.6 性能优化方向当前渲染脚本使用纯 Python 和 XML 元素树实际上几百个节点也毫无压力。但如果你想做更复杂的架构图可能需要考虑布局算法升级从简单分层升级为“分层 同层排序”减少连线交叉。缓存机制当架构 JSON 不变时不重复渲染 SVG。多格式输出在生成 SVG 的同时调用rsvg-convert或Inkscape导出 PNG 用于文档预览。7. 总结与下一步学习建议这篇文章从 Skill 的基本概念开始解释了为什么“一句话画出系统架构图”是可行的本质上不是让 AI 直接画图而是让 AI 先结构化理解需求再通过脚本进行精确渲染。亲手搭完这套 Skill 后你应该已经掌握了Skill 的目录结构和 SKILL.md 编写方法。架构图从 JSON 描述到 SVG 渲染的完整流程。分层布局的坐标计算思路。常见问题和排查手段。架构图 Skill 在真实项目中的最佳实践边界。接下来如果你还想继续深入有几个方向值得研究Mermaid / DrawIO 兼容输出在渲染脚本中增加输出格式参数一次生成多种格式方便在不同文档平台使用。动态系统拓扑把 Skill 和监控系统打通根据实时调用链数据自动生成架构拓扑图。多 Skill 协同结合“日志分析 Skill”和“架构图 Skill”自动定位系统瓶颈并生成问题链路图。这套思路最值钱的地方不是脚本本身而是**“AI 负责语义理解脚本负责精确计算”的分工模式**。把这个模式迁移到 PPT 生成、数据库设计、接口文档生成等场景你会打开一片新天地。如果这篇文章对你有帮助建议收藏备用也欢迎在评论区分享你写 Skill 时遇到的有趣问题。