有些事不亲手做一遍很难相信问题居然能这么离谱。前阵子我搭了一个AI Agent让它帮忙梳理订单系统的业务逻辑结果它给我输出了一堆用方括号和横线拼出来的方框图。图是能看懂但想拿给业务方评审想放进PPT想直接变成文档交付物完全不行。线对不齐、字号没法调、稍微复杂一点的交叉关系直接变成毛线团最要命的是——这个东西根本没法编辑改一个节点得重画全图。这篇文章就是围绕这个痛点展开的实战记录我如何让AI Agent不再输出示意级的方框图而是直接生成38种专业图表覆盖流程图、时序图、架构图、甘特图、热力图、桑基图等常见类型整个过程从路由设计、中间格式、代码接入一路聊到实测翻车和解决方案。如果你正在做Agent开发、AI工作流编排或者只是想让LLM输出更专业的结果这篇应该能给你一张完整的工程地图。1. 方框图之痛让Agent解释架构结果只得到一屏ASCII美术先还原一下当时的场景。我的Agent本身有工具调用能力也能读取代码库里的结构信息。我要求它分析这个模块的调用关系并输出一张架构图。它的确照做了但输出长这样------------------ ------------------ | API Gateway | ----- | Auth Service | ------------------ ------------------ | | v v ------------------ ------------------ | Order Service | ---- | Payment Service | ------------------ ------------------说句公道话这个图的信息量没问题调用关系、上下游依赖都表达清楚了。但它离可以交付差了十万八千里。问题集中在三个层面。第一排版完全不可控节点一多框线直接飞出屏幕第二无法二次编辑任何一个小改动都要推翻重来第三观感太工程师自嗨给业务方看的时候对方第一反应是你们内部文档这么随意的吗。真正让我决定重构方案的瞬间是我试图让它把这张图转成PlantUML或Mermaid时Agent反复输出语法错误——不是缺括号就是箭头格式不对折腾三轮才渲染成功。那一刻我意识到问题不在模型能力而在于我没有给Agent搭建一条从思考到专业图表的完整管线。此后我花了大概两周时间从零搭了一套图表生成体系。核心思路说起来不复杂让Agent输出结构化的图表描述由统一的中间层负责校验和路由最后交给专业渲染引擎出图。这套体系最终支持了38种图表类型也把图表生成从一个碰运气的事变成了稳定输出。2. 38种图表从哪里来按数据特征而不是名称做路由一开始我很天真以为只要在System Prompt里写一句你可以用Mermaid、ECharts、Graphviz等多种图表形式就能解决问题。结果发现Agent会在一条消息里同时混用三种图表的语法甚至自创语法。根本原因在于让LLM直接从想法跳到某个具体渲染器的代码跨步太大出错率必然高。所以我做了一次收敛给Agent一份固定的图表类型清单一共38种分成四大类。类别包含图表典型用途关系结构类思维导图、组织架构图、架构图、ER图、UML类图、网络拓扑图、鱼骨图、决策树、C4图、系统上下文图、依赖关系图、知识图谱梳理结构、展示层级、表达系统间关系过程流转类流程图、时序图、状态机图、甘特图、泳道图、部署图、状态流转图、用例图、活动图、交互流程图、发布流水线图、用户旅程图描述流程、步骤、时间线、状态变化数据可视化类柱状图、折线图、饼图、散点图、热力图、箱线图、雷达图、面积图、瀑布图、漏斗图、桑基图、树图、旭日图、词云、仪表盘、指标卡展示数据分布、趋势、占比、异常复合面板类多图看板、统计报表、组合面板多视角汇总适合做汇报首页有了这份清单之后下一步就是让Agent学会选型。我尝试过直接让Agent从38个名字里选一个效果很差——它经常根据名称的直觉选而不是根据数据特征选。比如看到时间序列数据它可能选柱状图而不是折线图看到占比关系它选饼图而不是环形图或旭日图。于是我换了一种思路把选图逻辑从名称选择变成特征匹配。在工具定义里我要求Agent先分析自己的输出内容提炼出几个关键特征数据是单维度还是多维度的是否存在时间序列核心关系是层级、依赖、流转还是占比需要表达的是流程步骤还是状态迁移受众是会看趋势还是看结构通过这种结构化追问Agent最终给出的图表类型稳定了很多。比如它要表达用户从进入页面到完成下单的步骤特征匹配会优先命中流程图或泳道图而不是架构图。这套逻辑和人的判断方式是一样的先想清楚要讲什么再决定用什么图表来讲。3. 中间格式设计Agent只产出ChartSpec渲染交给适配器定好了38种图表清单最关键的架构决策来了Agent直接输出Mermaid代码还是直接输出ECharts的option我当时在这两个方向上都做了实验结果都不理想。直接输出Mermaid语法错误非常多。Mermaid对缩进、箭头符号、节点ID的格式极其敏感模型在长文本生成中很容易丢一个引号或多一个空格。直接输出ECharts option就更头疼那是密密麻麻的JSON模型经常把type: bar写成type: bar甚至把数值字段写成带引号的字符串。最终的解法是设计一个中间层ChartSpec JSON。Agent只负责输出一种与具体渲染器无关的、对模型友好的结构再由工程侧把它翻译成Mermaid、ECharts、Graphviz等任意渲染器的代码。这个设计有三个明显好处。第一校验成本大幅下降ChartSpec是一个收敛的JSON Schema可以用程序逐字段检查第二切换渲染器时不用改Agent逻辑同一个ChartSpec今天用Mermaid出图明天可以换成Canvas渲染Agent那头完全无感第三幻觉被关进了笼子里模型只需要在限定字段里选值自由发挥空间被压缩到最小。一个典型的ChartSpec长这样{ chart_type: flowchart, title: 订单创建流程, direction: top_to_bottom, nodes: [ {id: start, label: 用户提交订单, type: start}, {id: check, label: 库存校验, type: decision}, {id: pay, label: 支付处理, type: process} ], edges: [ {from: start, to: check, label: }, {from: check, to: pay, label: 有库存} ] }不同图表类型有不同的Schema变体。时序图有participants和messages甘特图有tasks和milestones柱状图有x_axis、series、legend。整体上Schema设计遵循几个原则字段名要语义化让模型一看就懂比如用from/to而不是src/dst。可枚举的字段尽量给选项比如节点类型只允许start/end/process/decision/subprocess这几种。所有文字内容单独放不要和样式参数混在一起。考虑中文友好字段可以用英文但值允许中文模型处理中文标签没有压力。Schema定义好之后我对Agent的System Prompt做了重要调整核心变化就是把画图这个模糊目标替换成了非常具体的协议要求先判断图表类型再按对应Schema填充内容严格输出JSON不允许解释不允许Markdown代码块包裹。这几个限制词看着简单实测下来对输出格式的稳定性提升是决定性的。4. 接入Agent主循环function calling定义与渲染器实现当ChartSpec这个中间格式稳定之后剩下的工作就水到渠成了把它接进Agent的工具调用体系然后针对每种渲染器写适配器。我用的Agent框架支持function calling所以我把图表生成注册成两个独立的工具。第一个工具负责选型和生成ChartSpec第二个工具负责把ChartSpec渲染成目标格式。为什么拆成两个因为选型过程需要看数据内容而渲染过程只需要看ChartSpec——职责分离后每个工具的逻辑都清晰很多也方便单独调试和加缓存。先看第一个工具的function定义精简版{ name: generate_chart_spec, description: 根据内容特征生成38种专业图表之一的ChartSpec结构化描述, parameters: { type: object, properties: { chart_type: { type: string, enum: [flowchart, sequence_diagram, class_diagram, gantt, bar, line, heatmap, sankey, ...] }, reason: { type: string, description: 简述为什么选择这种图表类型帮助调试 }, spec: { type: object, description: 与chart_type对应的ChartSpec结构 } }, required: [chart_type, spec] } }这里有一个很容易被忽视但极其重要的字段reason。它不参与渲染只用于日志和调试。每次Agent选完图我都能看到它的思考轨迹——为什么选流程图而不是时序图为什么选桑基图而不是漏斗图。这些数据积累起来对后续优化Prompt和路由规则帮助巨大。第二个工具负责渲染它接收ChartSpec输出最终的SVG或HTML# renderer.py import json from mermaid_renderer import MermaidRenderer from echarts_renderer import EChartsRenderer from graphviz_renderer import GraphvizRenderer RENDERERS { flowchart: MermaidRenderer, sequence_diagram: MermaidRenderer, gantt: MermaidRenderer, state_diagram: MermaidRenderer, class_diagram: MermaidRenderer, bar: EChartsRenderer, line: EChartsRenderer, heatmap: EChartsRenderer, sankey: EChartsRenderer, architecture: GraphvizRenderer, network_topology: GraphvizRenderer, er_diagram: GraphvizRenderer, } def render_chart(spec_json: str) - str: spec json.loads(spec_json) chart_type spec[chart_type] renderer_cls RENDERERS.get(chart_type) if renderer_cls is None: raise ValueError(fUnsupported chart type: {chart_type}) renderer renderer_cls() return renderer.render(spec[spec])在MermaidRenderer内部其实就是把ChartSpec翻译成Mermaid语法字符串。这个过程是确定性的字符串拼接不需要任何模型参与所以永远不会出现语法错误# mermaid_renderer.py class MermaidRenderer: def render(self, spec): if spec.get(direction) left_to_right: lines [flowchart LR] else: lines [flowchart TD] for node in spec[nodes]: node_id node[id] label node[label] if node.get(type) start: lines.append(f {node_id}[{label}]:::start) elif node.get(type) decision: lines.append(f {node_id}{{{label}}}:::decision) else: lines.append(f {node_id}[{label}]) for edge in spec[edges]: arrow -- if edge.get(label): lines.append(f {edge[from]} --|{edge[label]}|-- {edge[to]}) else: lines.append(f {edge[from]} -- {edge[to]}) return \n.join(lines)EChartsRenderer的逻辑类似只不过输出的是ECharts的option对象然后通过服务端渲染服务转成SVG图片。这一层做出来后Agent生成一张专业图表的时间从看运气变成了稳定在3秒以内。5. 实测中的翻车现场格式幻觉、中文乱码与布局溢出工程化的世界从来没有一次成功这回事。这套系统上线之后我记录了一堆翻车场景每一个都是真实踩出来的基础值得拿出来讲。第一个高频问题是格式幻觉。即使我在工具定义里写明了spec字段类型是objectAgent依然会偶尔输出字符串形式的JSON或者把整个响应用Markdown的代码块包裹起来。解析阶段一遇到这类输出直接崩溃。后来我在工具描述里加了一句话直接输出JSON对象不要使用Markdown代码块不要返回字符串。 效果立竿见影格式错误率从大概15%降到了2%以下。第二个问题是中文乱码主要出现在Graphviz渲染出来的图里。Graphviz默认字体不支持中文节点标签只要带上中文生成的SVG全是方块。这是一个非常隐蔽的坑因为本地开发时可能撞上了有中文字体的环境但部署到容器里就露馅。解决方案是在GraphvizRenderer里显式指定字体# graphviz_renderer.py def render(self, spec): dot_lines [digraph G {] dot_lines.append( fontname\Microsoft YaHei\;) dot_lines.append( node [fontname\Microsoft YaHei\];) dot_lines.append( edge [fontname\Microsoft YaHei\];) # ... 继续拼接节点和边如果你的部署环境是纯Linux容器建议安装fonts-noto-cjk然后用Noto Sans CJK SC作为字体名。这个问题不解决所有中文图表都会变成天书。第三个问题是布局溢出。Agent有时会一口气把几十个节点塞进一张流程图Mermaid渲染出来的图横向铺满好几屏根本没法看。这不是模型的问题而是它的信息密度控制能力不足。我做了两个优化一是在Schema层面给nodes和edges加上最大数量限制超过就强制让Agent拆分二是引入自动分组机制当关系类图表的节点数超过15个时渲染层自动按模块前缀分组生成二级子图。第四个问题更微妙出现在ECharts类图表上。ECharts的数值类型要求很严格比如柱状图的value必须是number但Agent生成的JSON里经常把数字写成字符串或者把空值写成None。这个在Schema校验里能拦住但更推荐的做法是在渲染器里做一次宽容的强制类型转换def _to_number(value): if value is None or value : return 0 try: return float(value) except (ValueError, TypeError): return 0这类防御性转换虽然看着不优雅但在生产环境里异常管用能消掉一大批边界情况。我最终还在整个链路外面加了一层兜底如果ChartSpec校验失败或者渲染器抛异常Agent会自动收到一个错误信号并尝试用另一个图表类型重新生成。这个自动回退机制把端到端成功率从85%拉到了97%以上。6. 从会画图到能落地托管服务与MCP化扩展图表管线跑通以后我开始考虑一个现实问题这套能力除了在我本地Agent里能用怎么让团队其他成员、甚至其他项目也能复用最直接的办法是把它封装成一个独立的图表服务对外暴露HTTP接口。Agent不再直接依赖某个渲染器而是调用API。这个服务的核心接口很简单POST /api/chart/render Body: { spec: { ... } } Response: { format: svg, content: svg.../svg }在服务内部还是那张chart_type - Renderer的路由表。只是外面包了一层网络协议让任何语言写的Agent都能调用。部署的时候我用的是FastAPI因为它的类型校验和文档生成对这类接口特别友好。这个服务跑通之后我又顺手做了一个MCP工具版本。如果你在做Agent开发应该对MCPModel Context Protocol不陌生它本质上是一个标准化的工具接入协议让LLM应用能够统一调用外部能力。把图表服务包装成MCP工具后任何支持MCP的Agent都可以直接使用生成专业图表这个能力不需要关心ChartSpec细节。包装完之后我实测了几个场景。让Agent读一份数据库表结构它直接输出一张ER图让Agent梳理一份应急预案它输出泳道图让Agent分析一份销售数据它输出了组合看板——一个页面里同时包含折线趋势、柱状对比和饼图占比。这已经远远超出了最初告别方框图的目标进入用图表做叙事的层次。我也踩过MCP化的一个坑不要把整个38种图表全部暴露成一个工具模型一次性拿到38个枚举值容易懵。更合理的做法是按场景暴露多个小工具比如create_process_chart、create_data_chart、create_architecture_chart每个工具只负责对应类别下的图表。这个颗粒度更贴近人的使用习惯Agent也更容易准确选型。到这一步这套系统已经从一个内部实验变成了稳定运行的基础能力。回看整个过程最重要的经验是别指望AI Agent天然会输出专业图表你需要给它一条清晰的工程路径。路径的起点是一个合适的中间格式中间是确定的渲染器适配层最后用回退机制兜底。只要这三件事做扎实了无论是38种还是80种图表类型都只是路由表里多几行配置的事。最后分享一个我一直保留的小习惯每个图表生成请求都会记录chart_type、reason和最终渲染是否成功。隔一两周翻一次这些日志你能很快发现哪些场景下Agent总是选错图、哪些图表类型几乎没人用。产品迭代和Prompt优化都不应该靠感觉而是靠这些从真实请求里沉淀下来的数据。
有些事不亲手做一遍很难相信问题居然能这么离谱。前阵子我搭了一个AI Agent让它帮忙梳理订单系统的业务逻辑结果它给我输出了一堆用方括号和横线拼出来的方框图。图是能看懂但想拿给业务方评审想放进PPT想直接变成文档交付物完全不行。线对不齐、字号没法调、稍微复杂一点的交叉关系直接变成毛线团最要命的是——这个东西根本没法编辑改一个节点得重画全图。这篇文章就是围绕这个痛点展开的实战记录我如何让AI Agent不再输出示意级的方框图而是直接生成38种专业图表覆盖流程图、时序图、架构图、甘特图、热力图、桑基图等常见类型整个过程从路由设计、中间格式、代码接入一路聊到实测翻车和解决方案。如果你正在做Agent开发、AI工作流编排或者只是想让LLM输出更专业的结果这篇应该能给你一张完整的工程地图。1. 方框图之痛让Agent解释架构结果只得到一屏ASCII美术先还原一下当时的场景。我的Agent本身有工具调用能力也能读取代码库里的结构信息。我要求它分析这个模块的调用关系并输出一张架构图。它的确照做了但输出长这样------------------ ------------------ | API Gateway | ----- | Auth Service | ------------------ ------------------ | | v v ------------------ ------------------ | Order Service | ---- | Payment Service | ------------------ ------------------说句公道话这个图的信息量没问题调用关系、上下游依赖都表达清楚了。但它离可以交付差了十万八千里。问题集中在三个层面。第一排版完全不可控节点一多框线直接飞出屏幕第二无法二次编辑任何一个小改动都要推翻重来第三观感太工程师自嗨给业务方看的时候对方第一反应是你们内部文档这么随意的吗。真正让我决定重构方案的瞬间是我试图让它把这张图转成PlantUML或Mermaid时Agent反复输出语法错误——不是缺括号就是箭头格式不对折腾三轮才渲染成功。那一刻我意识到问题不在模型能力而在于我没有给Agent搭建一条从思考到专业图表的完整管线。此后我花了大概两周时间从零搭了一套图表生成体系。核心思路说起来不复杂让Agent输出结构化的图表描述由统一的中间层负责校验和路由最后交给专业渲染引擎出图。这套体系最终支持了38种图表类型也把图表生成从一个碰运气的事变成了稳定输出。2. 38种图表从哪里来按数据特征而不是名称做路由一开始我很天真以为只要在System Prompt里写一句你可以用Mermaid、ECharts、Graphviz等多种图表形式就能解决问题。结果发现Agent会在一条消息里同时混用三种图表的语法甚至自创语法。根本原因在于让LLM直接从想法跳到某个具体渲染器的代码跨步太大出错率必然高。所以我做了一次收敛给Agent一份固定的图表类型清单一共38种分成四大类。类别包含图表典型用途关系结构类思维导图、组织架构图、架构图、ER图、UML类图、网络拓扑图、鱼骨图、决策树、C4图、系统上下文图、依赖关系图、知识图谱梳理结构、展示层级、表达系统间关系过程流转类流程图、时序图、状态机图、甘特图、泳道图、部署图、状态流转图、用例图、活动图、交互流程图、发布流水线图、用户旅程图描述流程、步骤、时间线、状态变化数据可视化类柱状图、折线图、饼图、散点图、热力图、箱线图、雷达图、面积图、瀑布图、漏斗图、桑基图、树图、旭日图、词云、仪表盘、指标卡展示数据分布、趋势、占比、异常复合面板类多图看板、统计报表、组合面板多视角汇总适合做汇报首页有了这份清单之后下一步就是让Agent学会选型。我尝试过直接让Agent从38个名字里选一个效果很差——它经常根据名称的直觉选而不是根据数据特征选。比如看到时间序列数据它可能选柱状图而不是折线图看到占比关系它选饼图而不是环形图或旭日图。于是我换了一种思路把选图逻辑从名称选择变成特征匹配。在工具定义里我要求Agent先分析自己的输出内容提炼出几个关键特征数据是单维度还是多维度的是否存在时间序列核心关系是层级、依赖、流转还是占比需要表达的是流程步骤还是状态迁移受众是会看趋势还是看结构通过这种结构化追问Agent最终给出的图表类型稳定了很多。比如它要表达用户从进入页面到完成下单的步骤特征匹配会优先命中流程图或泳道图而不是架构图。这套逻辑和人的判断方式是一样的先想清楚要讲什么再决定用什么图表来讲。3. 中间格式设计Agent只产出ChartSpec渲染交给适配器定好了38种图表清单最关键的架构决策来了Agent直接输出Mermaid代码还是直接输出ECharts的option我当时在这两个方向上都做了实验结果都不理想。直接输出Mermaid语法错误非常多。Mermaid对缩进、箭头符号、节点ID的格式极其敏感模型在长文本生成中很容易丢一个引号或多一个空格。直接输出ECharts option就更头疼那是密密麻麻的JSON模型经常把type: bar写成type: bar甚至把数值字段写成带引号的字符串。最终的解法是设计一个中间层ChartSpec JSON。Agent只负责输出一种与具体渲染器无关的、对模型友好的结构再由工程侧把它翻译成Mermaid、ECharts、Graphviz等任意渲染器的代码。这个设计有三个明显好处。第一校验成本大幅下降ChartSpec是一个收敛的JSON Schema可以用程序逐字段检查第二切换渲染器时不用改Agent逻辑同一个ChartSpec今天用Mermaid出图明天可以换成Canvas渲染Agent那头完全无感第三幻觉被关进了笼子里模型只需要在限定字段里选值自由发挥空间被压缩到最小。一个典型的ChartSpec长这样{ chart_type: flowchart, title: 订单创建流程, direction: top_to_bottom, nodes: [ {id: start, label: 用户提交订单, type: start}, {id: check, label: 库存校验, type: decision}, {id: pay, label: 支付处理, type: process} ], edges: [ {from: start, to: check, label: }, {from: check, to: pay, label: 有库存} ] }不同图表类型有不同的Schema变体。时序图有participants和messages甘特图有tasks和milestones柱状图有x_axis、series、legend。整体上Schema设计遵循几个原则字段名要语义化让模型一看就懂比如用from/to而不是src/dst。可枚举的字段尽量给选项比如节点类型只允许start/end/process/decision/subprocess这几种。所有文字内容单独放不要和样式参数混在一起。考虑中文友好字段可以用英文但值允许中文模型处理中文标签没有压力。Schema定义好之后我对Agent的System Prompt做了重要调整核心变化就是把画图这个模糊目标替换成了非常具体的协议要求先判断图表类型再按对应Schema填充内容严格输出JSON不允许解释不允许Markdown代码块包裹。这几个限制词看着简单实测下来对输出格式的稳定性提升是决定性的。4. 接入Agent主循环function calling定义与渲染器实现当ChartSpec这个中间格式稳定之后剩下的工作就水到渠成了把它接进Agent的工具调用体系然后针对每种渲染器写适配器。我用的Agent框架支持function calling所以我把图表生成注册成两个独立的工具。第一个工具负责选型和生成ChartSpec第二个工具负责把ChartSpec渲染成目标格式。为什么拆成两个因为选型过程需要看数据内容而渲染过程只需要看ChartSpec——职责分离后每个工具的逻辑都清晰很多也方便单独调试和加缓存。先看第一个工具的function定义精简版{ name: generate_chart_spec, description: 根据内容特征生成38种专业图表之一的ChartSpec结构化描述, parameters: { type: object, properties: { chart_type: { type: string, enum: [flowchart, sequence_diagram, class_diagram, gantt, bar, line, heatmap, sankey, ...] }, reason: { type: string, description: 简述为什么选择这种图表类型帮助调试 }, spec: { type: object, description: 与chart_type对应的ChartSpec结构 } }, required: [chart_type, spec] } }这里有一个很容易被忽视但极其重要的字段reason。它不参与渲染只用于日志和调试。每次Agent选完图我都能看到它的思考轨迹——为什么选流程图而不是时序图为什么选桑基图而不是漏斗图。这些数据积累起来对后续优化Prompt和路由规则帮助巨大。第二个工具负责渲染它接收ChartSpec输出最终的SVG或HTML# renderer.py import json from mermaid_renderer import MermaidRenderer from echarts_renderer import EChartsRenderer from graphviz_renderer import GraphvizRenderer RENDERERS { flowchart: MermaidRenderer, sequence_diagram: MermaidRenderer, gantt: MermaidRenderer, state_diagram: MermaidRenderer, class_diagram: MermaidRenderer, bar: EChartsRenderer, line: EChartsRenderer, heatmap: EChartsRenderer, sankey: EChartsRenderer, architecture: GraphvizRenderer, network_topology: GraphvizRenderer, er_diagram: GraphvizRenderer, } def render_chart(spec_json: str) - str: spec json.loads(spec_json) chart_type spec[chart_type] renderer_cls RENDERERS.get(chart_type) if renderer_cls is None: raise ValueError(fUnsupported chart type: {chart_type}) renderer renderer_cls() return renderer.render(spec[spec])在MermaidRenderer内部其实就是把ChartSpec翻译成Mermaid语法字符串。这个过程是确定性的字符串拼接不需要任何模型参与所以永远不会出现语法错误# mermaid_renderer.py class MermaidRenderer: def render(self, spec): if spec.get(direction) left_to_right: lines [flowchart LR] else: lines [flowchart TD] for node in spec[nodes]: node_id node[id] label node[label] if node.get(type) start: lines.append(f {node_id}[{label}]:::start) elif node.get(type) decision: lines.append(f {node_id}{{{label}}}:::decision) else: lines.append(f {node_id}[{label}]) for edge in spec[edges]: arrow -- if edge.get(label): lines.append(f {edge[from]} --|{edge[label]}|-- {edge[to]}) else: lines.append(f {edge[from]} -- {edge[to]}) return \n.join(lines)EChartsRenderer的逻辑类似只不过输出的是ECharts的option对象然后通过服务端渲染服务转成SVG图片。这一层做出来后Agent生成一张专业图表的时间从看运气变成了稳定在3秒以内。5. 实测中的翻车现场格式幻觉、中文乱码与布局溢出工程化的世界从来没有一次成功这回事。这套系统上线之后我记录了一堆翻车场景每一个都是真实踩出来的基础值得拿出来讲。第一个高频问题是格式幻觉。即使我在工具定义里写明了spec字段类型是objectAgent依然会偶尔输出字符串形式的JSON或者把整个响应用Markdown的代码块包裹起来。解析阶段一遇到这类输出直接崩溃。后来我在工具描述里加了一句话直接输出JSON对象不要使用Markdown代码块不要返回字符串。 效果立竿见影格式错误率从大概15%降到了2%以下。第二个问题是中文乱码主要出现在Graphviz渲染出来的图里。Graphviz默认字体不支持中文节点标签只要带上中文生成的SVG全是方块。这是一个非常隐蔽的坑因为本地开发时可能撞上了有中文字体的环境但部署到容器里就露馅。解决方案是在GraphvizRenderer里显式指定字体# graphviz_renderer.py def render(self, spec): dot_lines [digraph G {] dot_lines.append( fontname\Microsoft YaHei\;) dot_lines.append( node [fontname\Microsoft YaHei\];) dot_lines.append( edge [fontname\Microsoft YaHei\];) # ... 继续拼接节点和边如果你的部署环境是纯Linux容器建议安装fonts-noto-cjk然后用Noto Sans CJK SC作为字体名。这个问题不解决所有中文图表都会变成天书。第三个问题是布局溢出。Agent有时会一口气把几十个节点塞进一张流程图Mermaid渲染出来的图横向铺满好几屏根本没法看。这不是模型的问题而是它的信息密度控制能力不足。我做了两个优化一是在Schema层面给nodes和edges加上最大数量限制超过就强制让Agent拆分二是引入自动分组机制当关系类图表的节点数超过15个时渲染层自动按模块前缀分组生成二级子图。第四个问题更微妙出现在ECharts类图表上。ECharts的数值类型要求很严格比如柱状图的value必须是number但Agent生成的JSON里经常把数字写成字符串或者把空值写成None。这个在Schema校验里能拦住但更推荐的做法是在渲染器里做一次宽容的强制类型转换def _to_number(value): if value is None or value : return 0 try: return float(value) except (ValueError, TypeError): return 0这类防御性转换虽然看着不优雅但在生产环境里异常管用能消掉一大批边界情况。我最终还在整个链路外面加了一层兜底如果ChartSpec校验失败或者渲染器抛异常Agent会自动收到一个错误信号并尝试用另一个图表类型重新生成。这个自动回退机制把端到端成功率从85%拉到了97%以上。6. 从会画图到能落地托管服务与MCP化扩展图表管线跑通以后我开始考虑一个现实问题这套能力除了在我本地Agent里能用怎么让团队其他成员、甚至其他项目也能复用最直接的办法是把它封装成一个独立的图表服务对外暴露HTTP接口。Agent不再直接依赖某个渲染器而是调用API。这个服务的核心接口很简单POST /api/chart/render Body: { spec: { ... } } Response: { format: svg, content: svg.../svg }在服务内部还是那张chart_type - Renderer的路由表。只是外面包了一层网络协议让任何语言写的Agent都能调用。部署的时候我用的是FastAPI因为它的类型校验和文档生成对这类接口特别友好。这个服务跑通之后我又顺手做了一个MCP工具版本。如果你在做Agent开发应该对MCPModel Context Protocol不陌生它本质上是一个标准化的工具接入协议让LLM应用能够统一调用外部能力。把图表服务包装成MCP工具后任何支持MCP的Agent都可以直接使用生成专业图表这个能力不需要关心ChartSpec细节。包装完之后我实测了几个场景。让Agent读一份数据库表结构它直接输出一张ER图让Agent梳理一份应急预案它输出泳道图让Agent分析一份销售数据它输出了组合看板——一个页面里同时包含折线趋势、柱状对比和饼图占比。这已经远远超出了最初告别方框图的目标进入用图表做叙事的层次。我也踩过MCP化的一个坑不要把整个38种图表全部暴露成一个工具模型一次性拿到38个枚举值容易懵。更合理的做法是按场景暴露多个小工具比如create_process_chart、create_data_chart、create_architecture_chart每个工具只负责对应类别下的图表。这个颗粒度更贴近人的使用习惯Agent也更容易准确选型。到这一步这套系统已经从一个内部实验变成了稳定运行的基础能力。回看整个过程最重要的经验是别指望AI Agent天然会输出专业图表你需要给它一条清晰的工程路径。路径的起点是一个合适的中间格式中间是确定的渲染器适配层最后用回退机制兜底。只要这三件事做扎实了无论是38种还是80种图表类型都只是路由表里多几行配置的事。最后分享一个我一直保留的小习惯每个图表生成请求都会记录chart_type、reason和最终渲染是否成功。隔一两周翻一次这些日志你能很快发现哪些场景下Agent总是选错图、哪些图表类型几乎没人用。产品迭代和Prompt优化都不应该靠感觉而是靠这些从真实请求里沉淀下来的数据。
