你在 README 里想画个调用时序图，第一反应是截图贴进去。结果下一个同事提了 PR，图没变，但 diff 里永远只有一张二进制，谁也看不出改了哪根线。这种事我踩过太多次，后来干脆能不配图就不配。
更尴尬的是图片在很多渠道根本渲染不出来。Slack 里贴的图有时被拦，邮件网关把附件当垃圾，提交信息里的截图直接变成一串不可读的引用。图本来是为了让人秒懂，最后反而制造了信息断层。
还有个隐性成本常被忽略：图片进仓库就是二进制，CI 缓存、clone 体积、LFS 配额全被它吃掉。文本图是零成本的，它跟你的 .md 没有任何区别。
plantuml-ascii 就是一个反过来想问题的技能。它不让你生成 PNG，而是让 PlantUML 把图渲染成纯文本 ASCII 字符画，直接塞进代码块里。Smithery 上把它挂在 github/plantuml-ascii 之下，归类在 Design，下载量已经破了兩万。
一句话结论先放上：如果你的图主要活在终端、Git 提交、PR 描述或者邮件里，这个技能值得装；如果你要的是给客户看的精致架构图，它帮不上忙。下面把为什么这么判断讲清楚。
使用场景
最适合它的场景其实就一类：图必须能跟着文本一起被版本控制、被 grep、被 diff。比如开源项目的 CONTRIBUTING 文档，或者你给同事写的排查步骤，里面夹一张时序图，对方复制粘贴就能跑。
具体落地的场合比你想象的多。提交信息里贴一张组件调用图，后人 git log 一眼就能回溯设计意图；故障复盘的运行手册写在 Wiki 里，图跟着文字走，重构时顺手就改；给不用 GitHub 的同事发邮件，纯文本图也不会被网关吞掉。
你甚至不用自己记这些命令。跟 agent 说一句“给这个接口画个调用图，放 README 里”，它读完 SKILL.md 就会自己选 -utxt 出文本，而不是默认去生成一张图。这种“该出文本时出文本”的判断，本来就是人类顺手做的，现在被固化进了技能。
最有价值的是 on-call 场景。半夜告警，你在一张纯文本部署图旁写清楚排查路径，值班的人不用开任何绘图工具，终端里直接看、直接照着查。图在这里不是装饰，是操作手册的一部分。
它支持的格式分两种，差距比你想的大。
# 纯 ASCII，全用 +-| 这种基础字符
plantuml -txt diagram.puml
# Unicode 增强版，用 ┌─┐│▶ 这类制表符，观感好很多
plantuml -utxt diagram.puml
同样是那段 Alice 和 Bob 的对话，纯 ASCII 出来的效果是方角描边，Unicode 版则会用圆角方框和箭头连线。我自己的习惯是默认用 -utxt，除非目标环境明确只认 ASCII，比如某些老终端或纯文本邮件网关。
源文件就是标准的 PlantUML 写法，没有任何特殊语法，技能只是帮你决定该用哪个渲染开关：
@startuml
actor User
participant "Web App" as App
database "Database" as DB
User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml
跑完命令会产出 diagram.atxt（纯 ASCII）或 diagram.utxt（Unicode 版），文件名后缀就是这么来的。你把它 cat 出来粘进文档即可，不需要任何图片托管。
技术架构与设计决策
理解这个技能的关键，是它根本没有发明新的图描述语言。PlantUML 本来就能把同一份 .puml 源文件渲染成 PNG、SVG，或者文本。文本模式只是换了一个后端渲染器，前面那套 @startuml 到 @enduml 的 DSL 一点没动。
所以技能真正的价值不在渲染引擎，而在“决策层”。它帮 agent 判断：当前上下文该出图还是出文本？出文本的话用 -txt 还是 -utxt？这种判断人类随手就做了，但写在 prompt 里交给模型，能省掉一堆来回确认。
我一开始以为它就是个薄封装，看了 SKILL.md 才发现它把七类 UML 全列进来了，而且都能在文本模式跑通：
-
时序图 -
类图 -
活动图 -
状态图 -
组件图 -
用例图 -
部署图
组件图和部署图在终端里意外地好用，因为节点关系本来就用方括号和箭头表达，转成字符画几乎没有信息损耗。
它的安装也不挑平台。macOS 走 brew install plantuml，Ubuntu 用 apt-get install plantuml，再不济直接下官方的 plantuml.jar 用 java -jar 跑。技能把这条路径也写进了文档，等于顺手把环境配置的坑替你填了。
命令行还留了不少工程化余地。用 -o ./output 指定产物目录，传 -charset UTF-8 处理非 ASCII 文件名，或者一次性把整个 ./diagrams/ 目录批量渲染。SKILL.md 甚至给了 Ant 任务的接入示例，意味着你能在文档构建阶段自动把图生成成文本，而不是手动维护。
值得点破一件事：PlantUML 的文本渲染后端其实存在很多年了，社区里一直有人这么用。这个技能真正的贡献不是技术突破，而是把“判断格式再加渲染开关”打包成一个 agent 可调用的单元，让你不用记住 -txt 和 -utxt 这两个冷门参数。
-txt 和 -utxt 之间也有取舍。纯 ASCII 在任何终端都稳，但丑；Unicode 制表符好看，却要求查看端支持 UTF-8 等宽字体，老终端或某些日志系统会把它打成乱码。我一般内部文档用 -utxt，凡是可能进日志或邮件的，退回到 -txt。
输出也能直接进管道。.atxt 和 .utxt 就是普通文本文件，你能 cat、能 sed、能喂给任何 CLI 工具二次处理。图像做不到这点，它必须先被某个程序重新识别成结构才能动。
洞察与反思
用了几天，我先说它真的不行的地方，省得你白高兴。复杂图在 ASCII 下会塌。类图里一长串带类型的字段、活动图里嵌套的判定分支，一旦标签超过十个字符，字符画的列对齐就崩了，读起来比看源码还累。技能自己也在 Tips 里承认这点，建议复杂场景直接换 Mermaid 或 Graphviz。我给自己定了个经验线：节点不超过八个、标签英文且短于十个字符，文本图就清晰；超出这个量，宁可换图像。组件图天然符合，所以它是文本模式的最佳主场。
中文标签是另一个暗坑。等宽字体下中文字符通常占两个英文字符宽，但 PlantUML 的 ASCII 渲染器按单宽算，结果框线会错位。我试过在节点名里写中文，出来的图右边整条线歪掉。短期解法是标签全用英文，中文放到文档正文解释。-charset UTF-8 能解决文件编码，但救不了列宽对齐，这点别指望。
顺带一提，文本图对读屏软件友好。视障同事用屏幕阅读器能逐行听出节点和箭头，图片则必须依赖手写的 alt 文本，而大多数人根本不写。这也是“可追踪”之外，文本模式少有人提的一个加分项。
它的隐藏亮点反而是部署图和组件图。这种“方框加箭头”的结构在字符画里还原度极高，你一眼就能看懂服务之间谁调谁。比起在 Wiki 里维护一张随时过期的架构 PNG，我更愿意在代码仓库里放一张 .utxt，它跟着代码走，重构时顺手就改了。
把它和几个替代方案放一起看，边界就清楚了：
| 维度 | plantuml-ascii | Mermaid | Graphviz | Asciiflow |
|---|---|---|---|---|
| 终端直接可读 | 是 | 否 | 否 | 是 |
| 版本控制友好 | 高 | 中 | 高 | 低 |
| UML 表达力 | 中 | 中 | 高 | 低 |
| 上手成本 | 低 | 低 | 高 | 极低 |
| 复杂图保真度 | 低 | 高 | 高 | 低 |
Mermaid 赢在 GitHub 原生渲染，你写个代码块它就给你出图，但那张图本质还是图片，diff 照样看不出改了啥。Graphviz 表达力最强，代价是 DOT 语法陡。Asciiflow 是纯手绘 ASCII 的工具，适合画小框图，干不了 UML 语义。plantuml-ascii 卡在中间：比手绘规整，比图像可追踪，代价是放弃了复杂场景。
什么时候该果断放弃它？图要放进客户演示的幻灯片，图像模式才拿得出手；图有几十个节点还带循环依赖，直接上 Graphviz；只是想快速画个草图跟人讨论，Asciiflow 手拖更顺。文本模式不是万能钥匙，它只守住“可追踪”这一条线。
资源地址
-
Smithery 技能页: https://smithery.ai/skills/github/plantuml-ascii -
PlantUML 官网: https://plantuml.com -
PlantUML JAR 下载: https://github.com/plantuml/plantuml/releases
总结
这个技能不适合拿去给客户做交付物，它解决的是另一个问题：让图能像代码一样被管理。只要你的图要跟着代码一起走，不论是仓库终端还是 PR 描述，它都是目前最省心的方案。一行 plantuml -utxt 把图变成纯文本，既能 grep 搜索，也能 diff 比对，复制粘贴照样跑得通。只在 GitHub 里画图的前端工程师其实不需要它，Mermaid 代码块已经够顺。它是给那些图要跨出 Git 进终端和邮件的人准备的。
我的建议很直接，分两种情况：
-
团队内部文档、README、提交说明：默认出 .utxt，可读性够用，又不丢可追踪性 -
图一旦超过中等复杂度，或者节点要塞中文标签：立刻切 Mermaid 或 Graphviz，别跟 ASCII 对齐较劲
这个取舍点会随 PlantUML 版本演进微调，但“简单图用文本、复杂图用图像”的分界线短期内不会变。