scaffoldizr

Structurizr 工作区 - 使用 Scaffoldizr 创建

此技能可让 Agent 生成并使用 Structurizr 工作区，该工作区由 Scaffoldizr CLI tool 生成。

何时使用此技能

• 用户需要在给定的 Structurizr 工作区中创建或更新元素时。
• 用户需要创建架构图（利用 C4 模型）时。
• 用户需要验证现有的 Structurizr 工作区时。

通用说明

• 在根目录中搜索 ./architecture 文件夹。如果没有此文件夹，请提供使用 Scaffoldizr 创建文件夹的选项，并运行：

  scfz --dest <root_folder> \
    --workspaceName "<name>" \
    --workspaceDescription "<description>" \
    --workspaceScope "softwaresystem" \
    --systemName "<system name>" \
    --systemDescription "<system description>" \
    --authorName "<author name>" \
    --authorEmail "<author email>" \
    --shouldIncludeTheme "false"
  

  Scaffoldizr 将创建 ./architecture 文件夹及所有相关文件。

注意：如果 scfz 命令不可用，则表示尚未安装 Scaffoldizr CLI tool。请根据当前环境运行相应的安装脚本：

• macOS / Linux — 在终端中运行：

  curl -s https://formulamonks.github.io/scaffoldizr/assets/install.sh | sh
  

• Windows — 在 PowerShell 中运行：

  irm https://formulamonks.github.io/scaffoldizr/assets/install.ps1 | iex
  

如需了解更多详情，请参阅完整安装说明。

非交互式 CLI 用法（AI Agent 模式）

Scaffoldizr 支持非交互式执行：将生成器指定为子命令，并通过 CLI 标志传递所有提示词答案。这是 AI Agent 的首选方式，可完全避免交互式提示。

子命令路由

当 workspace.dsl 已存在时，可指定生成器子命令，绕过主菜单：

scfz <generator> [--flag "value"]

生成器名称采用 kebab-case 格式：external-system、software-system 等。

传递参数

所有提示问题都可以通过 CLI 标志回答，格式为 --parameter "value" 或 --parameter=value。

元素生成器参考

生成器	常用标志
system	--systemName、--systemDescription、--archetype
container	--systemName（父级）、--elementName、--containerDescription、--containerType、--containerTechnology
component	--elementName、--componentDescription、--componentTechnology
person	--elementName、--personDescription
external-system	--elementName、--extSystemDescription
view	--viewType、--viewName、--viewDescription、--dynamicScope、--systemName、--containerName、--step-N
constant	--constantName、--constantValue
archetype	--archetypeName、--archetypeBaseType、--archetypeDescription（可选）、--archetypeTechnology（可选）、--archetypeTags（可选）
theme	--themeAction "Add themes" --additionalThemes "<url1>,<url2>"

--viewType 标志接受 landscape、deployment 或 dynamic。对于其他视图类型（systemContext、container、component），请按照视图参考中的说明手动创建 DSL 文件。

• 所有相关文档文件都位于 ./architecture 文件夹中。
• 主入口文件为 ./architecture/workspace.dsl。
• ./architecture/workspace.json 是由 workspace.dsl 生成的编译输出。切勿直接读取或修改此文件，因为 Structurizr 下次运行时会覆盖它。要重新生成此文件，请运行 ./architecture/scripts/export.sh（Windows 上运行 export.ps1）。

文件夹内容

architecture 文件夹包含以下结构：

• ./architecture/archetypes：为其他元素提供基准或基础的元素。包含可重复使用的关系模式（例如，1_https_relationship.dsl）。
• ./architecture/containers/<system name>：软件系统的容器定义。每个软件系统都存放在独立文件夹中。
• ./architecture/components/<system name>/<container name>：软件系统的组件定义。每个软件系统及其各个容器都存放在独立文件夹中。
• ./architecture/decisions：记录关键架构决策的架构决策记录（ADR）。
• ./architecture/docs：工作区中引用的文档文件。
• ./architecture/environments：此文件夹包含部署视图的元素，用于创建和显示部署图。
• ./architecture/relationships：系统中不同元素的关系定义。
• ./architecture/systems：系统定义。此文件夹还包含用于引用人员元素的 _people.dsl，以及用于引用外部系统（不在实际图表范围内的系统）的 _external.dsl。
• ./architecture/views：用于渲染图表的视图定义，包括系统上下文视图。

图表中的关系

• Structurizr DSL 语言提供了 !include 指令，可用于引用其他文件和文件夹。如果引用中包含文件扩展名（例如 file.dsl），则会包含该路径下的文件。如果未包含扩展名，则会假定包含该文件夹中的所有文件。

工作区范围

• 根据工作区范围，你可以创建某些元素，也可能无法创建。工作区范围可以是 softwaresystem 或 landscape。

  1. 在这两种范围下，你都可以创建 archetype、constant、view、person、external system 和 relationship。
  2. 如果范围是 softwaresystem，则除了第 1 点列出的元素外，你只能创建 container 和 component。
  3. 如果范围是 landscape，则除了第 1 点列出的元素外，你只能创建 system。

• 检查 ./architecture/workspace.dsl 文件中的 workspace 块，确定当前工作区范围。例如：

workspace {
    ...
    configuration {
        scope softwaresystem  // <-- Here is where the scope is defined
    }
    ...
}

• 如果建议的操作与此规则冲突，务必提醒用户。

在工作区中创建新元素

⚠️ 重要提示 元素名称在工作区中必须唯一。创建新元素之前，务必检查是否已有同名元素。如果存在，请向用户建议一个替代名称。

原型

请参阅 原型 文档。

常量

请参阅 常量 文档。

软件系统

请参阅 软件系统 文档。

外部系统

请参阅 外部系统 文档。

容器

请参阅 容器 文档。

组件

请参阅 组件 文档。

关系

请参阅 关系 文档。

视图

请参阅 视图。

主题

使用 theme 生成器添加、移除或列出工作区主题。theme 生成器适用于 Landscape 和 SoftwareSystem 范围。

scfz theme \
  --themeAction "Add themes" \
  --additionalThemes "https://formulamonks.github.io/scaffoldizr/assets/scaffoldizr-shapes.json"

• --themeAction：「添加主题」|「移除主题」|「列出主题」
• --additionalThemes：要添加的主题 URL，以逗号分隔
• 颜色主题（Blue、Red、Green、Yellow）互斥——选择新的颜色主题会替换现有主题

使用 Structurizr CLI 命令与工作区交互

请参阅 CLI 命令 文档。

---

构建流程

• ./architecture/workspace.dsl 是唯一真实来源。所有架构更改都必须在 .dsl 文件中进行，绝不能修改 workspace.json。
• ./architecture/workspace.json 是编译生成的产物。Structurizr 每次运行都会覆盖它。⚠️ 请勿直接读取或修改 ./architecture/workspace.json ⚠️。任何手动编辑都会悄无声息地丢失。
• 要从 DSL 源文件重新生成 workspace.json，请运行导出脚本：
  • Linux/macOS：./architecture/scripts/export.sh
  • Windows：./architecture/scripts/export.ps1
• 使用 ./architecture/scripts/run.sh（或 run.ps1）启动 Structurizr Lite，并在 http://localhost:8080 查看图表。

错误排查

每当用户报告可视化 Structurizr 工作区时遇到错误，请先检查能否通过 Structurizr CLI 验证所报告的错误。点击此处了解更多信息。继续之前，请确保解决工具报告的所有问题。