stack-diagram

stack-diagram

生成工程制图风格的架构图：在白色底板上展示真实徽标、带标签的分组框（类似云厂商的 VPC 图）、带等宽字体标签的直角箭头，并以冷色调方格纸为背景。单个自包含的 HTML 文件是唯一可信来源；PNG / TSX / artifact 均由它生成。

要求

• Python 3.9+（fetch_icons.py 和 build.py 仅使用标准库）
• 获取图标时需能访问图标来源（svgl.app、raw.githubusercontent.com、cdn.jsdelivr.net，以及用于 name=URL 的品牌官网或代码库）
• render_png.py 需要 Playwright + Chromium：pip install playwright && python3 -m playwright install --with-deps chromium

工作流

1. 确定内容（节点、分组、边）
2. 获取图标 — scripts/fetch_icons.py
3. 规划坐标 — 阅读 references/geometry.md
4. 根据 assets/template.html 构建 HTML — scripts/build.py
5. 交付前渲染 PNG 并查看
6. 按请求的格式交付

第 1 步 — 内容

根据用户提供的技术/服务列表，确定：

• 节点：每项技术对应一个节点（名称 + 简短的小写角色描述，例如 http server、sqlite db）
• 分组：将共享运行时、供应商或代码库的内容框在一起（例如，在云服务商分组框中包含一个运行时分组框；或为工具链创建一个单仓库分组框）。可以嵌套一层；更深的嵌套会显得杂乱。分组标签使用品牌本身的大小写格式（GitHub、npm）；模板会按原样显示。
• 边，分为三种：
  • 强调色实线 = 主要请求/数据流（一条连续路径效果最佳）
  • 中性色实线 = 次要内部连接
  • 中性色虚线 = 开发时/部署时关系（CI、git hooks、IaC 部署）

如果用户只提供了扁平的工具列表，请根据工具的用途推断合理的分组和流程；只有当某个工具含义模糊到无论如何绘制都会导致图表错误时，才提出问题。

Step 2 — 图标

python3 scripts/fetch_icons.py <icons-dir> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"

规格格式：name（将 name 用作 slug）、name:slug（使用不同的 slug）、name=URL（显式指定 URL）。脚本会按以下顺序尝试：svgl → devicon → gilbarbara/logos，写入文件和 manifest.json，并标记填充色为白色的图标。svgl（svgl.app）排在最前，因为它提供现代开发者品牌的最新官方标志（TanStack、Better Auth、Hono……）。如果某个标志有浅色/深色版本，浅色版本会保存为 <name>（两种主题中的图块都是白色），深色版本则保存为 <name>_dark，供组标签使用。svgl 仅按精确标题匹配，因此未匹配时会继续尝试下一个来源。它的 API 还提供 wordmark 变体——偶尔适用于较宽的组标签，但绝不用于图块。

以下规则比具体操作更重要：

• 绝不要重新着色标志。 用户会注意到。如果标志是白色的，或在白色图块上太浅，就将它放在深色图块上（tile dark 类），而不是改动其填充色。清单中的 white_fill 标记是一种启发式判断——白色填充可能只是彩色标志中的内部细节（tRPC、Ubuntu），因此使用深色图块前先查看 SVG。
• 只使用官方标志。 刻意不将 simple-icons 作为来源：它的字形是重新绘制的单色版本，用户一眼就能看出不对。当所有来源都未找到（FAIL）时，找到官方文件并以 name=URL 的格式传入——可在项目仓库（根目录中的 logo*.svg、docs/、assets/、public/）和项目网站（/logo.svg、/favicon.svg、/images/logo.svg）中查找。有些标志只存在于仓库中（Lefthook 的标志是 evilmartians/lefthook 根目录下的 logo_sign.svg）。
• 抽象概念使用图示，不用文字。 像“开发环境”“cron”“队列”“缓存”或“webhook 接收器”这样的节点没有品牌标志——使用 name:lucide/<icon> 格式选择 Lucide 线条图标（例如 devenv:lucide/terminal、cron:lucide/clock；可浏览 lucide.dev/icons）。不要在图块中放文字，也不要使用表情符号。
• 供应商的子产品（Cloudflare D1/R2/KV、AWS 数不尽的服务……）通常没有独立标志：直接在图块上复用供应商品牌标志，并用节点名称区分（“Cloudflare D1”/“sqlite db”）。
• 非品牌节点（用户、浏览器、互联网、设备、裸机服务器）：将字形从 assets/generic/ 复制到图标目录，并使用节点名称命名；也可以使用 name:lucide/<icon>——不要使用表情符号。这些不是品牌标志，因此可以将它们染成示意图的墨色（抓取脚本会自动处理 Lucide 图标）。
• 组标签图标以 14px 渲染——因此需要方形字形标志。Wordmark 和宽版组合标志在这么小的尺寸下会糊成一团；如果主图标是 wordmark，请另外获取品牌的方形图标用于标签（svgl 通常提供；否则使用项目自己的图标或 favicon 文件）。
• 组标签显示在组的色调背景上，而非白色图块上，因此在深色主题中，带黑色部分的标志会融入背景。如果 fetch_icons.py 保存了 <name>_dark，就在标签中使用模板的 lt/dk 配对；如果没有深色版本且标志带有黑色部分，就给标签的 <img> 添加 plate 类（仅在深色主题中显示白色底板）。
• 光栅标志（png/webp）也可以；构建脚本会将所有内容嵌入为 data URI，因此视图显示时无需加载任何内容。

Step 3 — 布局

阅读 references/geometry.md，了解坐标系、间距常量，以及——最重要的是——防止箭头穿过标签文字的边缘锚定规则。一句话概括：节点由图块加上其下方的文字组成；垂直箭头连接节点框的边界，绝不能从图块之间穿过文字。

步骤 4 — 构建

复制 assets/template.html，将示例 GROUPS / EDGES / NODES / header 部分替换为你自己的内容，然后内联资源。将 <html> 上的 lang 设为图表标签所用的语言（默认为 en；日语请用 ja，这样浏览器会选用日语字形变体）。模板已包含两个选项：深色变体（在 <html> 上设置 data-theme="dark"；图块仍为白色，以确保徽标清晰可见；组标签图标遵循步骤 2 的规则，箭头和图例色块则会自动使用对应的令牌），以及一条“部署到平台 X”的边，其中 X 是一个组，而非节点——将箭头指向组内最具代表性的节点，并为边添加标签（deploy），这样显示效果才正确。

python3 scripts/build.py my-diagram.html <icons-dir> out.html --fonts <skill>/assets/fonts

标记中的图标引用格式为 %%ICON_<name>%%；字体引用格式为 %%FONT_DISPLAY%%（Geist）/ %%FONT_JBM%%（JetBrains Mono）。如果有未解析的令牌，构建会明确报错。所有颜色和字体都应通过模板中已有的 CSS 自定义属性设置——调整令牌，不要改动散落各处的值。

步骤 5 — 检查效果

渲染并实际查看图像：

python3 scripts/render_png.py out.html check.png --selector .canvas --scale 2

如果图表包含日语文本，渲染主机需要安装日语字体，否则 CJK 字符会悄然使用中文字形变体（用户一眼就能看出来）。脚本会发出警告并打印修复方法；模板的字体栈已列出 Noto JP 字体。

查看时请检查：

• 没有箭头穿过标签文本；箭头尖端没有落在文本上
• 边标签清晰可读（它们带有纸张颜色的光晕——确认光晕正常显示）
• 每个图标都清晰可见（白底白图标是最常见的问题 → 使用深色图块），包括深色渲染中的组标签图标
• 组标签位于所属组的左上角，避开节点和边；每个组左右两侧的内边距一致
• 没有元素超出组框；画布边缘没有内容被裁切

修正并重新渲染，直到效果干净为止。这个循环成本很低；不要交付文字重叠的图表。

步骤 6 — 交付

• HTML（默认）：直接交付构建后的文件。文件自包含，可离线使用。
• PNG：始终通过无头 Chromium 对构建后的 HTML 截图生成（render_png.py，使用 --scale 2 可让文字更清晰）——绝不能用 matplotlib/PIL/独立 SVG 栅格化工具绘制另一张图；HTML 是唯一真实来源，浏览器的文字/SVG 渲染才能确保正确的显示效果。默认情况下，脚本会输出两种主题（out.png 浅色 + out-dark.png 深色），并使用直角（仅截图时会移除圆角半径）——除非用户只要求一种主题，否则两种都要交付；--single 会按文档原样截图。仅截取图表请指定 .canvas，截取整页请使用 --full-page。
• TSX：根据 references/tsx.md 转换（自包含的 React 组件，无依赖）。
• Artifact（环境提供 artifact 或页面发布工具时）：使用环境的 artifact 工具发布构建后的 HTML。所有内容都已内联为 data URI，因此 artifact 的网络受限沙箱不会造成问题。如果用户会在对话中反复调整图表，优先使用此方式；若用户还需要可粘贴到其他地方的内容，则同时提供 PNG。

如果用户要求多种格式，请先构建一次 HTML，再从中生成其他格式。

在页脚中注明实际使用的图标来源——取自 icons 目录中 manifest.json 每个条目的 source 字段（例如：icons: svgl / devicon / Lucide）。品牌徽标仍是其所有者的商标。除非用户要求移除，否则请保留模板中的 "made with stack-diagram" 链接，并将其放在来源说明之后；默认 PNG 只截取画布，因此不会包含此链接。