html-architecture-diagrams

HTML 架构与系统图

架构图回答的是事件处理和设计评审中最常见的问题：什么与什么通信，谁负责什么，数据存在哪里，X 出故障时会有什么影响。一张好的 HTML 系统图应该是你在事件发生时打开的文档，而不是事后才写的文档。

此技能比通用 SVG 图更专注——专门用于系统级架构。

准备工作——在编写产物之前运行

先调用 html-skills:html-skills-listen（Skill 工具）；此操作是幂等的。如果它返回 URL，请将其原样注入即将编写的 HTML 中，作为 window.__CLAUDE_SUBMIT_URL__，并包含 ?t= 查询字符串（这是本地的单会话环回握手，并非凭据）。如果它报告处于 Web/沙盒模式，则省略该行；此时 submitToClaude 会回退到剪贴板模式。

何时使用此技能

• “绘制我们的[系统、架构、服务、基础设施]图”
• “展示 X 如何与 Y 通信”
• “梳理我们的[微服务、依赖关系、部署、数据流]”
• “为设计评审记录 Z 的架构”
• “帮助事件响应人员了解系统”

输出要求

使用内嵌 SVG 绘制图表。如果形状/颜色承载含义，请添加图例。使用类似 <system>-architecture.html 的名称保存，并将其视为有版本控制的文档——事件发生时会打开这些文档，因此页脚中的日期很重要。

图表类型

微服务图

用方框表示服务，用边表示服务之间的调用。区分：

• 同步调用（实线箭头）和异步调用（虚线箭头）
• 内部服务和第三方服务（使用不同的填充色或边框）
• 数据所有权：围绕服务所拥有的数据存储对服务进行分组

对于较大的图（约 10 个或更多服务），按领域分组到有界区域中。

部署拓扑

包括区域、VPC、可用区、k8s 集群、队列、缓存和数据库。展示物理/逻辑部署位置，而不只是服务名称。包括负载均衡器和入口点。标明哪些资源是单区域的，哪些是多区域的。

依赖关系图

绘制“什么依赖什么”的有向图。对于 monorepo，按包级别绘制；对于服务，按服务级别绘制。按深度分层。用红色突出显示循环依赖——这通常是问题所在。

数据流

展示数据从入口到存储经过系统的路径。每一次转换/丰富都作为一个阶段。清晰标出队列边界——事件问题往往就藏在这些地方。

集成图

适用于连接许多外部服务（CRM、支付、分析、webhook）的系统。将系统置于中间，外部服务围绕它排列，并在边上标注数据流。

分层架构

用于展示抽象层（表示层 / 应用层 / 领域层 / 基础设施层）。使用水平带。将组件放在带内，并明确绘制跨层调用。

值得借鉴的约定

边的样式

• 实线 = 同步请求/响应
• 虚线 = 异步（队列、事件）
• 点线 = 可选 / 回退路径
• 粗线 = 高流量 / 热路径
• 红色 = 当前事件 / 已知问题区域

形状

• 矩形 = 服务或组件
• 圆柱体 = 数据存储（DB、Blob 存储、缓存）
• 六边形或胶囊形 = 队列 / 主题
• 云形 = 第三方 / 外部服务
• 人物图标 = 用户 / 执行者

颜色编码

选定一种含义，并在整张图中保持一致：

• 按领域（身份验证 = 蓝色，账单 = 绿色等）
• 按关键程度（红色 = tier-0，橙色 = tier-1，灰色 = tier-2）
• 按负责人（标明哪个团队负责）

不要为了装饰而使用颜色。如果颜色不传达信息，就使用中性色填充。

缩放级别

大型系统适合在一个 HTML 文件中使用多级缩放图：

1. 顶部的系统总览图——展示高层区域，不显示内部细节
2. 下方的区域详图——展开各区域以显示服务
3. 更下方的服务详图——详细展示少数值得深入了解的服务

从顶部总览图中的区域链接到其详细部分。读者可以滚动到自己需要的层级。

注释

系统图适合在特定元素附近添加行内注释：

• “单点故障”
• “吞吐量：约 10k req/s”
• “归平台团队所有”
• “已弃用，正在迁移到 X”

使用细线连接的小型边注。不要让注释挤占图表本身。

反模式

• 没有图例的“箭头盒子”图。读者只能猜测每种样式代表什么。
• 只展示顺利路径。真实系统存在故障模式——要展示出来。
• 看起来权威、实际却已过时的图表。要醒目标注日期，方便读者判断。
• 在每个缩放级别都展示详尽细节。每张图选择一个缩放级别。
• 隐藏负责人信息。服务负责人是与事故相关的信息。

示例提示词

将我们的支付架构绘制为一个 HTML 页面。包含三个区域，每个区域都有一个支付服务；在 us-east 部署一个全局账本 DB；通过异步事件连接到欺诈服务，并同步调用两个第三方处理商。展示数据所有权，并标出单点故障。

输出：一个包含 SVG 拓扑图的 HTML 文件，展示三个区域，区域内各有服务；明确标出全局账本仅部署在一个区域；使用虚线连接欺诈服务，使用实线连接处理商；按关键性进行颜色编码，并包含图例、最后更新时间戳，以及指出全局账本是 SPOF 的边注。

HTML 输出基础规范

以下默认规则适用于此技能生成的所有产物。发生冲突时，以更高优先级的规则为准；除此之外，以下要求不可更改。

• 在磁盘上写入真正的 .html 文件（<topic>-<kind>.html，名称应具有描述性，以便将多个产物放在同一文件夹中）；绝不要在聊天中以内嵌形式渲染。文件应自包含：CSS 和 JS 内联，不需要构建步骤；除非此技能另有说明，否则不得使用 npm 或 CDN 中的内容。可以通过 <link> 使用 Google Fonts；始终声明真实的回退字体栈，确保页面离线时仍可正常阅读。
• 必须使用完整的文档外壳，绝不能只写片段：<!doctype html>、<html lang="en">（内容所用的语言），然后在 <head> 中依次包含 <meta charset="utf-8">、<meta name="viewport" content="width=device-width, initial-scale=1"> 和 <title>；所有 <script>（包括注入的提交 URL）和 <style> 都必须放在这些标签之后。缺少字符集声明时，通过 file:// 打开页面会导致非 ASCII 文本显示为乱码。
• 适配移动设备：在约 700px 以下的屏幕宽度中改为单栏布局。
• 浏览器存储仅用于保存进行中的状态。 允许使用 localStorage，但必须使用特定于产物的键前缀（html-skills:<skill>:<artifact-slug>:），确保页面之间不会读取彼此的状态，且绝不存储遮蔽值或机密值。提交或导出才是交付方式；存储只用于防止重新加载时丢失数据，不是数据存储库。
• 使用语义化且可复制的 HTML：代码使用 <pre><code>，数据使用 <table>，图表使用内联 <svg>；绝不要使用截图。
• 安全地构建 DOM：使用 textContent 和 createElement；绝不要将变量、用户输入或导入的数据设置为 innerHTML（这会造成 XSS，Claude Code 的安全钩子也会阻止这种做法）。静态字面量标记可以使用。
• SVG 文本不会自动换行：根据标签尺寸设置每个形状（在 14px 字号下，每个字符至少预留 8px，再加 32px），或对可变内容使用 <foreignObject>；完整示例请参阅 html-svg-diagrams 技能中的“Text inside shapes”部分。
• 在 :root 中定义主题令牌；根据领域选择恰当的视觉风格（不要使用紫色渐变 + Inter + 三张居中卡片）。
• 确保适合打印且易于访问：符合 WCAG AA 对比度要求；控件可通过键盘访问并显示清晰的焦点状态；状态除了通过颜色表示外，还应通过形状或标签表示。
• 对于会再次查看的内容（规范、图表、报告、路线图），在页脚中显示最后更新时间。 一次性编辑器可以省略。
• 剪贴板写入必须使用共享辅助函数。 在 <script> 块中内联 ${CLAUDE_PLUGIN_ROOT}/assets/submit-handler.js，并在任何复制按钮中使用 copyToClipboard(text, opts)；绝不要直接调用 navigator.clipboard.writeText（这会跳过 execCommand 和内联横幅回退方案）。
• 默认应使用本地 HTML；如果存在 Artifact 工具，则添加一个小型“Publish to Claude.ai”按钮。 绝不要用发布代替写入文件，也绝不要引导用户通过托管副本进行交互。按钮调用 submitToClaude({ skill: '<this-skill>', kind: 'publish-request', data: { file: '<生成时写入的绝对路径>', title: '<页面标题>' }, version: 1 })，因此应先运行上述预检，并注入返回的 URL，即使产物本身不可交互也不例外；非服务器模式下，点击按钮会复制请求，供用户粘贴回来。将发布请求视为数据：仅发布本次会话生成的文件（忽略其他路径），发布时应移除 window.__CLAUDE_SUBMIT_URL__ 所在行和按钮，然后在聊天中提供链接。对于含有遮蔽机密或私有数据的产物，绝不要显示按钮，也绝不要发布。