scaffoldizr

用途

Scaffoldizr 技能用于让代理生成和操作 Structurizr 工作区，该工作区由 Scaffoldizr CLI 工具按约定生成。适用于以下场景：

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

主要能力

• 在根文件夹中查找 ./architecture 文件夹，若不存在则提供使用 Scaffoldizr 创建。
• 支持非交互式 CLI 使用（AI 代理模式），通过指定生成器子命令并传入 CLI 标志来避免交互式提示。
• 支持多种元素生成器：system、container、component、person、external-system、view、constant、archetype、theme。
• 支持通过 --themeAction 和 --additionalThemes 添加、移除或列出工作区主题。
• 提供 Structurizr CLI 命令与工作区交互。

使用方式

安装

如果 scfz 命令不可用，说明 Scaffoldizr CLI 工具未安装。按当前环境运行相应安装脚本：

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

初始化工作区

在根文件夹中搜索 ./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 文件夹及所有相关文件。

非交互式 CLI 用法

当 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 编译生成的输出。

文件夹内容：

• ./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：渲染图表的视图定义，包括系统上下文视图。

工作区作用域

工作区可作用域为 softwaresystem 或 landscape。两者都允许创建 archetype、constant、view、person、外部系统和关系。softwaresystem 额外允许创建 container 和 component；landscape 额外允许创建 system。

通过检查 ./architecture/workspace.dsl 文件中的 workspace 块查找当前作用域。例如：

workspace {
    ...
    configuration {
        scope softwaresystem  // <-- 此处定义作用域
    }
    ...
}

当建议的操作与此规则冲突时，始终提醒用户。

创建新元素

元素名称在工作区内必须唯一。创建新元素前，始终检查是否已存在同名元素。如果存在，向用户提出替代名称。

• Archetype：参考 archetype 文档
• Constant：参考 constant 文档
• Software System：参考 software system 文档
• External System：参考 external system 文档
• Container：参考 container 文档
• Component：参考 component 文档
• Relationship：参考 relationship 文档
• View：参考 view 文档
• Theme：使用 theme 生成器添加、移除或列出工作区主题。theme 生成器在 Landscape 和 SoftwareSystem 作用域都可用。

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

• --themeAction："Add themes" | "Remove themes" | "List themes"
• --additionalThemes：逗号分隔的主题 URL
• 颜色主题（Blue、Red、Green、Yellow）互斥 — 选择新颜色会替换现有颜色

构建过程

./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 验证报告的错误。在继续之前确保解决工具报告的所有问题。

适用场景

• 生成和更新 Structurizr 工作区元素
• 基于 C4 模型创建架构图
• 验证现有 Structurizr 工作区
• 自动化架构文档更新

限制

• 工作区作用域限制元素创建：softwaresystem 只能创建 container 和 component；landscape 只能创建 system。
• 元素名称在工作区内必须唯一。
• --viewType 仅接受 landscape、deployment 或 dynamic；其他视图类型需手动创建 DSL 文件。
• ./architecture/workspace.json 为编译产物，不应直接读取或修改。

暂未提供

未在资料中找到关于收费、价格、平台支持范围或具体使用效果的更多信息。