技能使用指南

system-diagrammer（系统图表生成器）Skill是什么？

系统图表生成器Skill（system-diagrammer）基于Mermaid.js，一条命令即可生成C4上下文图与序列图，输出兼容GitHub与Notion的代码块。本文讲清安装思路、参数用法、竞品对比与典型场景，帮产品与研发快速补齐架构图。

系统图表生成器Skillsystem-diagrammer
9 个章节 约 13 分钟阅读 AI 智能生成

系统图表生成器Skill：一条命令，把需求文档里的系统架构画成可渲染的图

  • 它是什么：一个基于 Mermaid.js 的 AI 技能，专门用命令行快速生成 C4 上下文图与序列图，直接输出可粘贴到 GitHub、Notion 的 mermaid 代码块。
  • 它解决什么：写 PRD、技术规范时"图比文字难产"的问题——不用打开画图软件拖拽，也不用背 Mermaid 语法。
  • 怎么用：一行命令 + 几个参数（--type、--title、--nodes 或 --steps），就能拿到结果。
  • 最适合谁：产品经理、后端/架构同学、技术文档维护者，以及需要在评审会上快速补图的团队。
  • 注意：目前详情明确支持的图类型为 C4 上下文图与序列图；具体安装入口与费用政策请以官方说明为准。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：系统图表生成器Skill 技能英文名：system-diagrammer 技能ID：12834

它的定位非常聚焦：快速为产品需求文档（PRDs）或技术规范创建架构图，输出是兼容 GitHub 和 Notion 的 Mermaid.js 代码。换句话说，它不需要你成为绘图工具高手，只需要你能用一句话说清楚"系统里有哪些角色和模块"“一次请求按什么顺序流转”。

它主要解决三类痛点：

  1. 画图成本高于写文档：文字半小时写完，配图还要再花半小时找工具、对齐方框、调箭头。
  2. 图与文档不同步：图片是二进制文件，改一次要重画，评审后经常"文档更新了、图还是旧的"。
  3. 格式不通用：导出的 PNG 在 Notion 里糊、在 GitHub 里没法 diff，协作时只能靠截图沟通。

一键安装的思路与步骤

"一键安装"的核心逻辑是：把技能装进你的 AI 工作环境（Agent 的技能目录），之后用自然语言或命令行都能调用它。由于技能详情中未给出具体的安装命令与市场链接，以下为通用流程，具体入口、命令与权限要求请以官方说明为准：

  1. 确认安装前提：你的 AI 开发环境支持「技能（Skill）」机制，技能会被放在项目内的 .agent/skills/ 目录下；同时环境中具备 Python 运行能力，因为该技能的调用方式是 python .../diagram.py。
  2. 找到技能：在技能市场/技能库中用英文名 system-diagrammer、中文名「系统图表生成器」或技能ID 12834 检索。
  3. 安装到项目：按平台指引完成安装，安装后应能在项目中看到脚本路径 .agent/skills/system-diagrammer/scripts/diagram.py。
  4. 验证是否生效：在项目根目录执行一条最小命令，例如生成一张只有两个节点的小图，确认终端返回一个 mermaid 代码块：
python .agent/skills/system-diagrammer/scripts/diagram.py --type c4 --title "测试系统" --nodes "用户, 服务"
  1. 把图用起来：将返回的 mermaid 代码块粘贴到 PRD、Notion 页面或 GitHub 的 Markdown 文件中，平台会自动渲染成图。

提示：脚本路径是相对路径，命令需要在项目根目录执行，否则会提示找不到文件。

该技能的主要功能和特点

  • C4 上下文图生成：通过 --type c4 指定图类型，用 --nodes 传入以英文逗号分隔的系统角色/模块清单，一条命令得到系统全景图，适合放在 PRD 开头讲清"系统边界"。
  • 序列图生成：通过 --type sequence 指定类型，用 --steps 按 A->B:消息 的格式描述交互步骤，逗号分隔，自动生成带时序的流程图，适合讲登录、下单、支付等关键链路。
  • 输出即代码块：脚本直接返回一个可直接使用的 mermaid 代码块，复制粘贴即可渲染，不需要二次转换格式。
  • GitHub / Notion 双兼容：这两个平台都原生支持 Mermaid 渲染，因此产出物可以嵌进仓库文档、Issue、Wiki 和知识库页面。
  • 文本化、可版本管理：图以文本形式存在，可以随文档一起提交、diff、回滚——这是相对导出的图片文件最大的差异点。
  • 无需记忆绘图语法：普通 Mermaid 需要记住 graph TD、sequenceDiagram、participant 等语法，这个技能把语法层封装成参数，你只需要提供业务信息。

和普通工具比强在哪：draw.io 这类工具强在自由拖拽，弱在"图和文档两套系统"；手写 Mermaid 强在灵活，弱在语法门槛。这个技能站在中间：用参数化的极简输入换取了"零语法 + 文本化"的双重收益。

如何使用该技能？

整体流程可以拆成 5 步：

第 1 步：明确要表达什么图 讲系统由哪些部分构成 → 用 C4 上下文图；讲一次操作按什么顺序发生 → 用序列图。

第 2 步：准备素材 C4 图准备"节点清单"；序列图准备"交互步骤列表"，每条按 发起方->接收方:消息内容 书写。

第 3 步：执行命令

C4 上下文图（高级视角）示例：

python .agent/skills/system-diagrammer/scripts/diagram.py --type c4 --title "电子商务系统" --nodes "用户, Web应用, API网关, 订单服务, 数据库"

序列图（流程流）示例：

python .agent/skills/system-diagrammer/scripts/diagram.py --type sequence --title "登录流程" --steps "用户->Web:点击登录, Web->API:POST /login, API->DB:验证用户, DB->API:用户找到, API->Web:返回令牌"

第 4 步：读懂输出 脚本返回一个 mermaid 代码块。把它整块复制，不要只复制中间的行，保留代码块标记才能被平台识别为图表。

第 5 步：放置与迭代 粘贴进 PRD 或 Notion 页面后检查渲染效果；如果节点名或消息文案有歧义，回到第 2 步微调参数再执行一次即可——整个过程仍然是秒级。

参数速查：--type 决定图类型；--title 是图标题；--nodes 接收以英文逗号分隔的节点；--steps 接收以英文逗号分隔的交互步骤，单步格式为 A->B:消息。参数值建议用引号包裹，避免空格和特殊符号被命令行截断。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
system-diagrammer（本技能） AI 技能：命令行生成 Mermaid 架构图 C4 上下文图、序列图，输出 Mermaid 代码块 需安装技能 + Python 环境，记住两条命令即可 PRD/技术规范快速补图、评审前临时出图 优势：零语法、命令即图、文本可版本管理；不足：图类型目前聚焦 C4 与序列图，复杂定制仍要回到 Mermaid 层
手写 Mermaid.js 文本绘图语言 支持流程图、时序图、类图、状态图等多种图 需学习语法与渲染规则，无环境成本 需要精细控制的长期文档 优势：灵活度最高；不足：语法学习曲线陡，写错一处整图不渲染
PlantUML 老牌文本 UML 工具 UML 全家桶（类图、组件图、部署图等） 通常需 Java 环境与渲染服务 传统软件工程建模 优势：UML 覆盖完整；不足：GitHub/Notion 原生渲染支持弱，协作链路长
draw.io 等图形化白板 拖拽式画图工具 任意图形、自由排版 零代码，但需手动布局与对齐 汇报材料、一次性示意图 优势：视觉自由度高；不足：非文本化，难 diff、难 review，改一次要重画

选型建议：如果图要"活着"（跟着文档迭代、能被 review）、且主要表达系统边界与调用顺序，本技能的性价比最高；如果需要高度定制或非 C4/序列类型的图，可以在本技能产出初稿后回到 Mermaid 层二次编辑。

该技能的典型应用场景与实际体验情况

场景一：产品经理写 PRD 时的系统全景图 痛点是 PRD 里"用户—应用—网关—服务—数据库"的关系全靠文字描述，研发容易理解偏差。使用方式是用 --type c4 --nodes "用户, Web应用, API网关, 订单服务, 数据库" 直接生成一张上下文图放在文档开头。 实际体验：上手门槛极低，只要能把系统拆成几个名词就能出图；效果上，图例清晰度取决于节点命名是否统一（建议全文档使用同一套叫法）。

场景二：技术方案评审前的关键链路序列图 痛点是登录、支付这类流程口头讲十分钟，不如一张时序图。用 --type sequence --steps "用户->Web:点击登录, Web->API:POST /login, ..." 描述步骤即可。 实际体验：这类图对"步骤拆分粒度"敏感——步骤拆得太粗信息不足，拆得太细图会很长。建议单张图控制在一条主链路上，分支另起一张。

场景三：新人 onboarding 文档与仓库 Wiki 把架构图和流程图以 Mermaid 代码块形式写进仓库文档，新人 clone 下来就能看到最新版本。 实际体验：这是文本化图最大的红利——图跟着代码走，不会出现"文档里的图还是去年的"；注意在 GitHub 上需在支持 Mermaid 渲染的 Markdown 场景中查看。

场景四：需求评审会现场补图 评审中有人问"这个订单到底经过哪些服务？"，当场执行一条命令投屏。 实际体验：速度是这个技能的核心竞争力；由于参数都在一条命令里，改节点、改标题的成本几乎为零。

通用注意事项：节点名与消息文案尽量简洁、避免过多特殊符号，以实际渲染结果为准；命令需在项目根目录执行；--nodes 与 --steps 均以英文逗号分隔，参数值建议加引号。

该技能能为用户带来的价值

  • 效率提升：从"打开工具—拖方框—连线—调样式—导出"的多步操作，压缩为"一条命令 + 一次粘贴"。原先需要十几到几十分钟的配图工作，可以缩短到几十秒量级，尤其适合频繁改稿的文档场景。
  • 门槛降低：不需要学习 Mermaid 语法，也不需要绘图软件技能，产品、运营、测试同学都能独立出图，减少"等架构师有空帮我画个图"的排队。
  • 协作质量提升：图以文本形式存在，可以进代码仓库、可以被 review、可以 diff，架构图和文档天然同源，降低沟通中的理解偏差。
  • 长期资产化：架构图不再是散落在各处的截图，而是随 PRD、技术规范沉淀的结构化文本，团队规模变大后依然可检索、可复用。
  • 格式兼容性收益：一次产出同时满足 GitHub 与 Notion 两大协作场景，省去"同一张图导两个版本"的重复劳动。

常见问题 FAQ

Q1：这个技能怎么安装？需要什么环境？ 在支持技能机制的 AI 开发环境中，通过技能市场或技能库检索 system-diagrammer（技能ID 12834）安装即可，安装后脚本位于 .agent/skills/system-diagrammer/scripts/diagram.py。由于调用方式为 python ...，环境中需要有 Python。具体安装入口与命令请以官方说明为准。

Q2：它是收费的吗？ 技能详情中未涉及定价信息，是否收费、是否有免费额度需以官方说明为准。技能本身输出的是 Mermaid 代码文本，不依赖额外的付费渲染服务。

Q3：生成的图能直接在 GitHub 和 Notion 里显示吗？ 可以。技能的输出就是一个 mermaid 代码块，而 GitHub 与 Notion 都支持 Mermaid 渲染，复制粘贴到对应文档中即可自动成图。若页面未渲染，请检查是否完整保留了代码块标记。

Q4：它支持哪些图类型？能画类图或 ER 图吗？ 按技能详情，目前明确提供的是 C4 上下文图（--type c4）与 序列图（--type sequence）两类。其他图类型未在详情中说明，建议以官方说明为准；若需要其他类型，可在本技能产出的 Mermaid 代码基础上自行扩展。

Q5：和手写 Mermaid、draw.io 相比怎么选？ 追求"快、零语法、可版本管理"，选本技能；需要精细控制样式和排版，选手写 Mermaid 或 draw.io。实践中最省力的组合是：用本技能一分钟出初稿，再在 Mermaid 层做少量定制。