c4-diagram

C4 图

工作流

1. 选择 C4 级别 — 根据问题确定图表深度（见下表）
2. 选择工具 — 默认使用 Structurizr DSL；快速内联预览使用 Mermaid（见下表）
3. 生成图表 — 遵循图表规则，然后参考所选工具的 DSL 参考文档
4. 渲染 — 按照渲染回退顺序操作

C4 级别选择器

问题类型	C4 级别	Structurizr 视图类型
“展示整个组织／所有系统”	支持级别 — 系统全景图	systemLandscape（Mermaid 中没有对应项）
“这个系统做什么？”／“谁在使用它？”	级别 1 — 上下文	systemContext
“主要的服务／应用／数据库有哪些？”	级别 2 — 容器	container
“这个服务的内部结构是怎样的？”	级别 3 — 组件	component
“这个特定类／模块是如何工作的？”	级别 4 — 代码	无图表 — 级别 4 没有对应的 C4 图表

默认选择级别 2（容器） — 它适用于大多数“展示架构”的请求。利益相关者概览使用级别 1，深入了解单个服务则使用级别 3。

工具选择器

需求	使用
在聊天中快速内联预览	Mermaid → references/c4-mermaid.md
为文档／wiki 导出 PNG／SVG	Structurizr → references/c4-structurizr.md
从一个模型生成多个视图	Structurizr
组织范围的系统全景图	Structurizr（Mermaid 中没有对应的 C4 图表）
动态／编号交互流程	任一（C4Dynamic 或 Structurizr dynamic）
部署／基础设施视图	Structurizr（Mermaid C4Deployment 功能有限）
类／方法级细节（级别 4）	Mermaid classDiagram — Structurizr 中没有对应项
没有可用工具	Mermaid

除非用户明确要求快速预览 Mermaid，否则默认使用 Structurizr DSL。

图表规则

• 每个元素都必须包含：名称、类型（Person/System/Container/Component）和简要描述
• 容器和组件必须注明其技术（例如 “Node.js Express”、“PostgreSQL”）
• 每个关系都必须使用动作 + 协议标注（例如 “通过 gRPC 读取事件”，而不只是 “使用”）
• 在模型中为外部系统／人员标记 tags "External"
• 边界是隐式的：systemContext 和 container 视图会自动限定范围。使用 group 表示边界内的逻辑子分组
• 图表中的元素数量保持在约 12 个以内 — 如果更多，则拆分成多个图表

渲染

按顺序尝试，首次成功后停止。Structurizr CLI 不支持原生 svg／png 导出 — 始终先导出为 PlantUML／Mermaid／D2，再使用相应工具渲染。

1. CLI 可用（本地安装／Docker 提供的二进制文件为 structurizr.sh，或通过 Homebrew/Scoop 安装的 structurizr-cli）— 将 DSL 保存到 /tmp/<name>.dsl，然后：

   structurizr.sh export -workspace /tmp/<name>.dsl -format plantuml -output /tmp/structurizr-out/
   # render the .puml to SVG/PNG with `plantuml /tmp/structurizr-out/*.puml`
   

   将输出路径告知用户。

2. Docker 可用 — 将 DSL 保存到 /tmp/<name>.dsl，并提供给用户：

   # Active replacement (recommended):
   docker run -it --rm -p 8080:8080 -v /tmp:/usr/local/structurizr structurizr/structurizr local
   # Legacy (archived but functional):
   docker run -it --rm -p 8080:8080 -v /tmp:/usr/local/structurizr structurizr/lite
   

   指向 http://localhost:8080。

3. 两者都不可用 — 在带围栏的 dsl 代码块中输出 DSL。注意：粘贴到 https://playground.structurizr.com/ 可在线渲染。

---

→ Structurizr DSL 语法：references/c4-structurizr.md → Mermaid C4 语法：references/c4-mermaid.md

---

基准测试

场景：.benchmarks/scenarios/c4-diagram-001-container-view.md · 运行：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/c4-diagram-001-container-view.json

模型	不使用	使用	变化
claude-opus-4-8	67%	100%	+33%
claude-sonnet-4-6	100%	100%	+0%
claude-haiku-4-5	100%	100%	+0%

通过（运行于 2026-08-31）。Opus 提升 33（67→100）；sonnet/haiku 已达到上限。没有回归。门槛依据 .agents/skills/skill-optimizer/rules/release-gates.md。