renderizr

Renderizr — 将 Structurizr 工作区制作为一个可分享的文件

此技能可将 Structurizr 工作区——包括其中的视图、文档和决策日志——渲染为可浏览的静态网站，或制作为一个自包含的 HTML 文件。你可以将此文件上传为 Claude artifact，任何人都能打开，无需服务器，也无需联网。

Renderizr 会根据工作区中的所有内容（位置、样式、主题、形状和连线路径）使用自有引擎绘制图表，因此图表可以平移、缩放，动态视图也能像在 Structurizr 中那样播放动画。

何时使用此技能

• 用户想要查看架构模型，而不是阅读其源代码。
• 用户想要与没有 Structurizr 帐户、没有服务器、也没有 DSL 副本的人分享模型。
• 用户请求生成一个artifact、一个预览，或“发布图表”。
• 用户在一个包含 ./architecture 文件夹的代码库中工作——这类文件夹通常由 Scaffoldizr 创建——并希望从中生成输出。

不要使用此技能来编写或编辑模型：这是 Scaffoldizr 的工作。Renderizr 负责渲染工作区，其编辑模式（npx renderizr edit）允许用户在浏览器中调整视图布局；Agent 不会操作编辑模式。

一条命令

npx github:FormulaMonks/renderizr <workspace.json|url> --single-file --out <dir>

这会在 <dir> 中写入两个文件：

文件	内容	用途
artifact.html	不含自身 <html>、<head>、<body> 框架的页面	上传为 Claude artifact——宿主会提供文档框架
index.html	同一页面，作为完整的独立文档	从磁盘打开、通过电子邮件发送，或放入存储桶

两个文件都会内嵌所有样式表、脚本、字体、图标以及工作区本身。它们都不会发起任何网络请求。

用于 Claude artifact 时，请使用 artifact.html。 如果改为交付 index.html，文档就会嵌套在另一个文档中。

移除 --single-file，即可生成一个目录，其中包含 index.html 和 assets/，可用于部署到静态服务器或 GitHub Pages。

获取可渲染的工作区

Renderizr 接受 JSON，可以是本地路径，也可以是 URL。它不解析 DSL。

• 磁盘上已有 workspace.json——通常位于 ./architecture/workspace.json。直接使用即可。

• 只有 workspace.dsl——先使用 structurizr-cli 导出；它可以将 DSL 工作区导出为 JSON。在 Scaffoldizr 代码库中，./architecture/scripts/export.sh（或 export.ps1）可以代劳。

• URL——直接传入，例如 Big Bank plc 示例：

  npx github:FormulaMonks/renderizr \
    https://raw.githubusercontent.com/structurizr/structurizr/main/structurizr-export/src/test/resources/big-bank-plc.json \
    --single-file --out /tmp/big-bank
  

在 Scaffoldizr 代码库中，workspace.json 除了包含导出的模型，还保存视图布局：Renderizr 编辑模式和 Structurizr Local 会将布局保存到其中，而 Structurizr 的 merge 会在 DSL 发生变更时保留该布局。渲染此文件即可，切勿手动编辑。

推荐流程

1. 查找工作区。 检查 ./architecture/workspace.json。如果只有 workspace.dsl，请先导出并说明这一点；不要悄悄渲染过时的 JSON。覆盖保存包含布局的 workspace.json 会丢失布局：如果该文件已存在，请使用 merge -layout workspace.json 进行导出。

2. 渲染工作区，输出到临时目录，而不是代码库中，除非用户要求保留输出：

   npx github:FormulaMonks/renderizr ./architecture/workspace.json --single-file --out /tmp/renderizr-out
   

3. 交付前确认文件确实自包含——参见验证。只需运行一条命令，就能决定交付的 artifact 是正常打开，还是对接收者显示空白。

4. 交付 artifact.html。 说明文件名和大致大小；实际模型通常约为 1 MB。如果你自行将其发布为 Claude artifact，请声明 downloads 能力（例如 capabilities: {downloads: true}），这样读者就可以导出视图。

标志

完整参考见 flags。最重要的几个：

标志	作用
--single-file	生成一个自包含文档，以及 artifact.html。用于制品。
-o, --out <dir>	输出目录（默认值为 structurizr-output）
--base <path>	多文件构建的公共基础路径，例如项目 Pages 的 /repo-name/
--logo <path|url>	标题栏左上角的图片，嵌入为数据 URI
--font <family>	Google Web Font，在构建时获取并嵌入为 woff2

只有 --font 和远程 --logo 需要在构建时访问网络。不使用它们时，渲染完全离线。

注意事项

我们已针对该工具逐一验证以下事项：

• Node 20 是最低要求。 npx 使用 PATH 中排在最前面的 Node 运行，而它通常不是 shell 报告的那个版本。Renderizr 会检查并给出明确提示后退出，而不是等到构建过程中才报错。
• artifact.html 和 index.html 不能互换。 请参阅上表。
• 没有 downloads 的制品无法导出。 制品查看器只能通过 downloads 功能让页面保存文件。如果发布 artifact.html 时未声明该功能，页面就会隐藏导出按钮。
• Renderizr 会在写入前清空输出目录。 切勿将 --out 指向存放着要保留内容的目录。
• 输出中的 https:// 并不代表泄露。 渲染后的页面包含指向 structurizr.com、c4model.com 等网站的普通超链接。自包含指的是资源引用——<script src>、<link href>、<img src>——而这些引用都不存在。请检查正确的内容；参阅验证。
• 在 Renderizr 仓库的克隆目录中操作时有所不同。 使用 pnpm render <workspace> [flags]——尤其注意，不要使用 pnpm render -- <workspace> --flag，否则该标志会被当作第二个工作区传入。相反，pnpm dev 确实需要 --。这仅适用于仓库内部；npx 用户不受影响。

参考

• flags — 所有 CLI 标志、用途及其代价
• artifacts — Claude 制品的详细路径，包括大小和交付内容
• verifying — 交付前验证制品是否自包含