mcpField
C
c4-structurizr

c4-structurizr

github.com/mercatorproj开发059 次安装4 周前更新
代码仓库

关于 c4-structurizr

c4-structurizr 是一项技能，可根据项目代码和文档生成有依据的 C4 架构模型。它指导开发者创建七种带样式的 PlantUML 视图、渲染 SVG 并验证结果。

主要功能

  1. 01盘点架构证据
  2. 02按需分析 AI 工作流
  3. 03选择七种架构视图
  4. 04生成带样式的 C4-PlantUML 文件
  5. 05渲染并验证 SVG 图表

适用场景

  1. 01记录项目系统架构
  2. 02将图表内容追溯至代码和配置
  3. 03梳理有证据支持的 AI 工作流路径

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mercatorproj/c4-structurizr --skill c4-structurizr

安装后在 Claude Code 中输入/c4-structurizr确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
README.md
LICENSE
agents/
openai.yaml
assets/
c4-style.puml
assets/c4-plantuml/
C4_Container.puml
C4_Component.puml
C4_Deployment.puml
C4_Context.puml
C4.puml
C4_Dynamic.puml
C4_Sequence.puml
references/
ai-workflow-analysis.md
view-catalog.md
model-analysis.md
scripts/
render_c4.py

详细介绍

C4 Structurizr

为一个核心系统生成有证据支撑的 C4 架构模型。生成七个 C4-PlantUML 文件，将其渲染为 SVG，并验证每张渲染后的图表均非空且可追溯到代码库。不要使用默认的 C4-PlantUML 样式。

工作流

  1. 确定目标项目。使用提供的项目路径；否则，根据当前仓库推断。如果项目或核心系统不明确，请停止并提出一个简洁的问题。

  2. 阅读 references/model-analysis.md。根据代码、配置、清单、基础设施文件、测试和现有文档，梳理人员、软件系统、容器、组件、外部系统、存储、队列、进程、部署和关系。

  3. 如果模型、配置、依赖项、提示词、Agent、工作流、运行时执行器、模型适配器、上下文存储或追踪存储显示存在 AI 工作流，也要阅读 references/ai-workflow-analysis.md，并在绘图前完成 AI 梳理。如果没有此类证据，则不要添加 AI 语义。

  4. 阅读 references/view-catalog.md。选择七种视图，其中包括特定于领域的动态流程和关键路径。如果某个视图缺乏证据支撑，请停止并报告缺失的证据，而不是凭空编造。

  5. 创建图表工作区。除非用户指定其他位置，否则在目标项目中使用 docs/architecture/structurizr/plantuml。将 assets/c4-style.puml 复制到该目录，并将 assets/c4-plantuml/ 复制到同级的 docs/architecture/tools/c4-plantuml 目录。如果目标目录布局不同，请确保包含路径有效，并告知用户资源文件的暂存位置。

  6. 生成七个名称简洁且有证据支撑的 .puml 文件。优先使用以下规范名称：system-landscape.puml、system-context.puml、container.puml、component.puml、dynamic-flow.puml、deployment.puml 和 critical-path.puml。如果使用特定于领域的后缀能提升清晰度，也可以使用；由 AI 驱动的系统可将基于模型的路径命名为 ai-critical-path.puml。

  7. 使用以下命令进行渲染：

    python "<skill-directory>/scripts/render_c4.py" --source "<diagram-directory>"

    需要 PNG 预览进行视觉检查时，添加 --preview。如果渲染器无法定位 plantuml.jar，则添加 --plantuml-jar "<path>"。

  8. 验证七个 SVG 文件均存在且非空，使用预期的白色背景和强调色，并包含清晰可读的文本。布局复杂时，查看预览。根据分析清单检查关系、元素类型、边界和关键路径顺序。对于 AI 系统，验证无需阅读 PlantUML 源码，就能从视觉上辨识运行时边界、Agent 与工作流的区别、执行器、模型网关、上下文和追踪路径。

  9. 报告图表目录、七个图表名称、渲染状态，以及支撑主要架构论点的代码路径。明确报告尚未解决的证据缺口。

图表源文件规则

  • 每个文件都以 @startuml <DiagramId> 开头，并以 @enduml 结尾。
  • 首先包含一个 C4-PlantUML 入口文件，然后再包含 !include c4-style.puml。
  • 在默认工作区中，使用 !include ../../tools/c4-plantuml/C4_Context.puml 这类包含路径。
  • 让 @startuml 的 id 与所需的输出文件名一致，因为 PlantUML 会使用该 id 作为 SVG 和 PNG 文件名。
  • 在每个视图中使用 SHOW_PERSON_OUTLINE() 和 HIDE_STEREOTYPE()。
  • 使用 left footer <b>... 作为图表标题。不要使用 PlantUML 的 title。
  • 根据 C4 粒度使用 Person、System、System_Ext、Container、ContainerDb、Container_Ext、ContainerDb_Ext、Component 和 Deployment_Node。
  • 为每个 Rel 和 RelIndex 关系添加 $tags="OfficialRelationship"。
  • 人员使用绿色，内部元素使用蓝色，通用外部系统使用灰色，边界使用蓝色实线，关系使用粗虚线，背景使用白色。可以追加项目专属的语义强调标签，但不得弱化基础样式值。
  • 仅对有证据支持的元素使用共享 AI 标签：AIWorkflow、AIAgent、AIExecutor、AIContext、AITrace、AIBoundary、AIFlow、ModelCall、AIContextFlow 和 AITraceFlow。在各视图中保持 AI 工作流语义一致，并在元素名称或描述中注明其角色，避免图表仅靠颜色传达信息。
  • 使用目标项目的领域和技术术语。不要在为其他项目生成的图表中放入 6S 专属实体。

不要用一次性的 PlantUML 样式替换生成的文件。如果 C4-PlantUML 宏或样式行为与预期结果不同，请检查暂存的 C4-PlantUML 资源，并在重新生成全部七个图表之前先测试一个图表。

评论

支持 Markdown