Community图像github.com

Excalidraw 架构图(EIP 符号)

用于创建 Excalidraw 格式的软件架构图,支持企业集成模式(EIP)符号,生成 .excalidraw 文件和预览 SVG,附带渲染检查。

Excalidraw 架构图(EIP 符号) 是什么?

此技能专为 AI Agent(如 Claude Code、Cursor、Codex)设计,用于将软件架构、消息流、事件驱动或微服务系统可视化。它基于“规范即源码”的原则,用户通过编写一个小的 JSON 规范(包含节点、边、分组)来描述架构,然后通过脚本 `scripts/eip_excalidraw.mjs` 生成符合 Hohpe & Woolf 符号的 Excalidraw 文件(.excalidraw)和预览 SVG(.svg)。该技能适用于绘制上下文级、流程级或端点级图表,并严格遵循企业集成模式(EIP),支持频道、路由器、转换器、端点、死信队列(DLQ)、Saga 等元素。它不适用于 UI 线框图、幻灯片或自由画板。技能还提供了详细的建模规则、审查清单和常见布局问题的修复建议,确保生成的图表准确易读。支持的平台包括任何能够调用 Node.js 脚本的 AI Agent 环境。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jamescarr/diagram-skill/tree/HEAD/skills/excalidraw-architecture

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Excalidraw 架构图(EIP 符号) 是做什么的?

一个图就是一个小型的 JSON 规范 —— 节点、边、分组 —— 外加一个生成器,它会按 Hohpe & Woolf 符号进行布局。规范是事实的来源;.excalidraw 文件和预览 .svg 是构建产物。

下面的 <skill-dir> 是此技能安装的目录 —— 例如 ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture 或 .agents/skills/excalidraw-architecture —— 以及在 https://github.com/jamescarr/diagram-skill 仓库中的 skills/excalidraw-architecture。

何时使用

  • 被要求绘制、描画、草图或可视化一个服务、事件或消息架构时。
  • 解释消息如何传输:使用哪个频道、哪个端点、失败时会发生什么。
  • 在上下文、流程或端点级别记录一个限界上下文的集成面。
  • 审查消息导向的设计时,需要让图表暴露缺少的死信队列、关联标识符或幂等性。

不要使用

  • UI 线框图、线框、幻灯片、自由画板。
  • 单个进程内的调用顺序图。
  • 交付物不是 .excalidraw 文件的任何内容。

工作流程

  1. 清点 —— 在绘图前列出:

    • 参与者:服务、外部系统、执行者、数据存储;
    • 频道:名称、点对点 vs 发布-订阅、键/分区/排序、持久性、死信队列;
    • 消息:名称(命令 = 祈使句、事件 = 过去时、文档 = 名词)和类型;
    • 每个服务的端点:网关、出箱/事务、消费者风格、竞争数量、幂等性、持久性、选择性;
    • 路由和转换步骤;
    • 请求-回复对:回复频道、关联、TTL;
    • 管理:线路检测、存储、控制总线。 如果对模式选择不明确,请阅读 enterprise-integration-patterns 技能(如果已安装)。
  2. 选择级别 —— context:执行者、服务、外部系统、代理作为 message-bus、rpc/data 边。flow(默认):一个端到端的业务流程,包含频道和 EIP 组件。endpoint:一个服务内部 —— 网关 → 出箱 → 频道,或消费者 → 幂等接收器 → 激活器。每个图只针对一个流程,最多 20 个节点;超过则按流程拆分。

  3. 编写规范 —— <name>.spec.json 放在图表所在目录旁(默认 docs/architecture/),参考下面的速查表。运行 node <skill-dir>/scripts/eip_excalidraw.mjs kinds 查看实时分类。

  4. 构建 —— node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json 会生成 <name>.excalidraw 和 <name>.svg。修复每个 error:(退出码 2);将 warning: 视为布局缺陷(--strict 会使警告以退出码 1 退出)。--check 仅验证布局而不写入文件。 添加 --png [OUT.png] 可以额外导出由 Excalidraw 本身渲染的 PNG(手绘风格、Excalifont 字体、场景嵌入文件中以便重新拖放回 excalidraw.com)—— 这是 README、文档或博客文章应嵌入的格式。它需要 Chrome 或 Chromium(CHROME 可覆盖查找路径)以及访问 esm.sh 的网络能力;通过 scripts/export_png.mjs 驱动浏览器。导出失败时退出码为 3,但场景仍会写入。

  5. 查看 —— 如果构建了 PNG 则 read <name>.png,否则 read <name>.svg:img;然后对照审查清单。

  6. 修复 —— 每次规范更改后重新构建:

    症状规范修改
    箭头穿过节点设置 route: "ortho" 或 "below",或固定 row
    标签与节点重叠缩短 message/label,或通过固定 row 将节点移开箭头
    箭头缩小该列间距中箭头过多:将箭头路由到 below/above,或固定 row 使较少竖线共享该列
    向后箭头混乱route: "above"
    回复箭头在整个图表下循环route: "ortho",或将回复频道放在请求频道旁边
    列拥挤添加 lanes,或拆分图表
    长节点标签将细节移到 sub
    组成员分散固定 col/row 使成员相邻
    框包含非成员固定 col/row 或使用 lanes 使组的成员形成连续块
  7. 交付 —— .spec.json、.excalidraw 和 .svg(如果构建了 PNG,还包括 .png)。说明规范是事实来源:编辑后重新生成。之后可以直接在 Excalidraw 中手动编辑,但重新构建会覆盖它们。

建模规则

每条规则都是图表必须能展示的主张;如果无法成立,则必须明确绘制例外情况。

  • 每个频道显示其种类标签和键/分区/排序标签(tags)。
  • 每个消费至少一次频道的消费者都带有 idempotent —— 或者图表说明为什么不。徽章只存在于应用族节点上,因此 Saga、路由器或聚合器在 sub 中说明其去重规则(dedupe by orderId)。
  • 每个消费者可能失败的频道都有一个 dead-letter-channel shadow;验证失败则获得 invalid-message-channel。未绘制或故意缺失的死信队列,需在频道的 sub 或 note 中说明。
  • 请求-回复 = 一条命令边,带有 reply_to 和 correlation,再加上一条虚线回复返回边。
  • 聚合器、散布-收集和 Saga 节点在 sub 中带有完成规则(计数/超时)。
  • 事务内的发布 = 一个 outbox 徽章或 outbox 节点,绝不能是提交后的裸发布。
  • 转换器位于限界上下文边界(框)上。
  • 竞争型消费者显示 competing:N;持久订阅带有 durable。
  • 线路检测是通往 message-store 的 tap 边。
  • 智能端点,哑管道:路由逻辑位于路由器节点中,绝不能隐含在频道内部。
  • 同步调用是 rpc 边,且是例外而非默认。
  • 跨越边界的内部记录需要一个 content-filter,或一个 claim-check 引用。

规范速查表

按 EIP 章节分类的节点 —— 完整的种类对照表在 references/spec.md:

章节种类使用场景
频道channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus消息在参与者之间移动;选择点对点 vs 发布-订阅,然后是失败频道。
消息message command-message document-message event-message消息本身是主题,而不是端点。
路由content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga一条消息有多个可能的目标,或需要重新组合部分。
转换message-translator envelope-wrapper content-enricher content-filter claim-check normalizer在跳转之间,有效载荷或其信封发生变化。
端点message-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapter服务如何连接到频道并消费它。
系统管理wire-tap detour message-history smart-proxy test-message channel-purger可观测性、探测和运维。
基础设施message-broker messaging-bridge outbox inbox代理本身、代理间链接、事务性发布/消费。
参与者和存储service external-system actor datastore message-store schema-registry note谁拥有频道末端;状态、模式和注释的存储位置。

徽章(仅应用族节点;药丸形状渲染简短文本):

分组徽章
端点gateway(消息网关)、mapper(消息映射器)、activator(服务激活器)、adapter(通道适配器)
消费polling(轮询消费者)、event-driven(事件驱动消费者)、competing / competing:N(竞争消费者,在最多三个盒子的堆栈上渲染 competing ×N)、dispatcher(消息调度器)、selective(选择性消费者)、durable(持久订阅者)
事务tx(事务客户端)、outbox(事务性出箱)、inbox(事务性收件箱)、idempotent(幂等接收器)
弹性bulkhead、retry、circuit-breaker —— 弹性模式,非 EIP

边:

边类型线条样式宽度箭头标记
message(无类型)实线 #1e1e1e2→ arrow无
message type: command实线2→ triangle«C»
message type: event实线2→ arrow«E»
message type: document实线2→ arrow«D»
message type: reply虚线2→ arrow«R»
rpc实线1→ arrow无
data点线1→ arrow无
tap点线1circle → arrow无
dlq虚线 #c92a2a1→ arrow无
control虚线 #868e961┤ bar无

边字段:from、to、kind、type、message、label、seq、route、correlation、reply_to、ttl、sequence、style、color。节点字段:id、kind、label、sub、badges、tags、group、lane、col、row、shadow、attach、link。

审查清单

  • 标题存在;它命名的是流程,而不是整个系统。
  • 每条箭头都标记了消息或调用。
  • 每个频道都带有其种类标签和键/分区标签。
  • 每个频道的死信队列决定可见。
  • 当超过 6 种种类出现时,存在图例。
  • 没有构建过程中留下的 warning:。
  • 分组框只包含其成员。
  • 最多 20 个节点。

技术栈映射

技术栈绘制为
Kafka topicpubsub-channel;消费者组 → competing:N;持久订阅 → durable
RabbitMQ queuep2p-channel;exchange → message-broker 或 content-based-router;DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
EventBridge rulecontent-based-router
Step Functionsprocess-manager 或 saga
Lambda consumerservice 带有 event-driven
数据库datastore;审计/重放副本 → message-store
合作伙伴 APIexternal-system,虚线

手动编辑

references/excalidraw-format.md 列出了 JSON 不变性约束,以保持手动编辑后 Excalidraw 的绑定、文本和框的有效性。

相关技能