architecture-diagram

交互式架构图

构建可直接使用的单文件 HTML 页面，让工作坊参与者、客户或新团队成员能够逐步了解系统的工作方式——观看数据包在节点之间流动的动画，在侧边面板查看载荷详情，并切换不同模式（离线/在线、开发/生产、v1/v2）。整体风格偏暗色，以清晰易懂为先：节点边界明确，连线采用柔和的二次曲线，数据包只在当前步骤发光——不使用彩虹渐变。通过 assets/css-tokens.css 中的 CSS 令牌重新设置品牌样式。

---

何时使用此技能

情况	使用此技能？
“向我展示身份验证流程是如何运作的”（用于工作坊的交互式演示）	是
“在构建之前设计 RAG 流水线”（规划新服务）	是
“绘制我们的微服务及其通信方式”	是
“为入职文档可视化 CI/CD 流水线”	是
“展示数据如何流经我们的 ETL 流水线”	是
“绘制带工具调用的智能体多 Agent 系统”	是
“构建一个架构模型，方便我们与团队一起迭代”	是
“为 PR 绘制序列图”（静态，放在 Markdown 中）	否 — 直接使用 Mermaid 序列图更简单
“在幻灯片或 PDF 中添加图表”（静态，不需要交互）	否 — 此技能生成的是交互式 HTML，而非图片或幻灯片
“我只需要静态的方框和箭头拓扑图”（没有流程/步骤）	否 — Mermaid 流程图就足够了

关键区别在于交互性 + 按顺序展示数据流：如果你需要“点击查看并观察发生了什么”，就使用此技能；如果需要静态图像、幻灯片或内嵌图表，则改用 Mermaid。

---

思维模型

每张图都包含四个要素：

1. 节点 — 服务、数据存储、用户、队列、外部系统。每个节点都有一个角色（颜色）和元数据（技术栈、端口、部署目标）。
2. 流程 — 用户可选择的命名场景（例如 RAG Query、Direct Query、Ingest、Auth）。每个流程由一系列有序的步骤组成。
3. 步骤 — {from, to, color, title, route, payload, desc, chips}。每个步骤会点亮一条连线和一个目标节点。（color 和 title 为必填项——color 必须是 CSS 变量名，例如 --c-orch；其他值都会回退为品牌强调色；缺少 title 时会显示“—”。）如果步骤的 from === to，则会渲染为节点上方的环路（表示内部工作，例如“CI → CI：构建”）。
4. 模式 — 正交切换项（离线/在线、开发/生产、v1/v2）。模式可以：
   • 隐藏/显示整个节点（例如，Seed 仅在离线模式下存在）
   • 重命名节点（Qdrant → BigQuery）
   • 替换载荷内容、端口、身份验证标头、延迟标签

模式不是替代流程。流程描述的是场景（“用户提出问题”）；模式描述的是部署形态（“在 Docker 上”与“在 Cloud Run 上”）。

---

调用后的工作流

第 1 步 — 明确需求

如果用户上传了 SOLUTION.md、README、OpenAPI 规范或任何架构说明，提问之前请先阅读文档。提取以下信息：

• 服务名称、技术栈和端口
• 部署模式（如有）
• 命名的端点/操作及其用途（这些会成为流程）
• 每项操作涉及的内部服务调用链（这些会成为步骤）

然后只询问缺失的信息。不要询问文档中已有的信息。

如果没有文档，请简要询问用户：

• “我们要绘制什么系统？”
• “你想展示哪些主要流程？（例如登录、搜索、结账）”
• “需要切换哪些模式？（离线/在线、开发/生产、v1/v2）”
• “受众是谁？工作坊参与者、工程师还是客户？”

第 2 步 —— 先在纸上规划拓扑

编写代码之前，先在纸上画出草图（可以真的画，也可以在脑中或临时文件中构思）：有哪些服务、它们彼此之间的位置关系，以及哪些流程连接了哪些节点。避免连线交叉——这是提升可读性的最有效方法。布局技巧请参阅 references/flow-design-patterns.md。

快速规则：

• 将协调器/API 网关放在中间，依赖项向外展开
• 用户放在最左侧（入口），数据存储放在右侧（出口），服务放在中间
• 只读服务放在上方，写入密集型服务放在下方（符合直觉：数据向下流入这些服务）
• 将可选/单次运行的服务（种子任务、cron）放在角落

第 3 步 —— 根据模板构建

将 assets/template.html 复制到工作目录。这是一个可直接使用的完整模板：包含深色主题、侧边面板、播放器控件（播放/暂停/逐步播放）、键盘快捷键、动画 SVG 数据包和模式切换。只编辑以下区域（模板顶部的 EDIT THESE THINGS 注释是权威清单）：

1. <title> + <h1> —— 替换 {{SYSTEM_NAME}} 和标题文本。对于波兰语（或其他非英语）图表，也要设置 <html lang="pl">。
2. .modepick 按钮 —— 模式切换标签（如果只有一种模式，可以删除整个 .modepick；面板徽标和 O 键会相应调整）。可以使用三种或更多模式——按 O 键可循环切换。
3. .flowtabs —— 每个场景对应一个 .flowtab；data-flow 必须与一个 flows 键匹配。标签顺序对应键盘数字 1–9；无需同步任何其他内容。
4. .stage 中的 .node div —— 每个服务对应一个：data-id、data-role、style="left/top"、标签、技术和端口。
5. JS 中的 flows 对象 —— 每个场景对应一个条目，每个条目包含一个有序的 steps[] 数组。将 state.mode / state.flow 设为要优先显示的键（未知键会回退到第一个按钮，并记录警告）。

条件项：只有当你的角色与默认值不同时，才更新 .legend；只有要更改样式时，才重新设置 :root CSS 变量。编辑后，搜索文件中的 {{，检查是否有遗漏的 {{SYSTEM_NAME}}/{{FLOW_*}} 占位符——页面启动时也会自行检查，并在浏览器控制台输出所有残留占位符、未知节点 ID 或标签页/流程不匹配项（window.archValidate() 会返回相同的列表）。

不要重新设计 CSS、播放器、SVG 连线渲染器或侧边面板——它们都能正常工作。

第 4 步 —— 展示给用户之前先验证

生成后，请进行以下自查：

• 在脑中打开文件：每个流程的步骤顺序是否讲得通？（第 1 步负责铺垫，最后一步将结果交付给用户。）
• 连线是否有不必要的交叉？如果有，重新调整节点位置（试着将较晚出现的依赖项移离较早出现的依赖项）。
• 是否有流程中某个节点连续两步都作为 to？如果这是一个循环，则没有问题，但请检查描述是否解释了原因。
• 模式切换：选择不同模式之间差异最大的节点（通常是数据库），确认它所有依赖模式的字段都已填写（标签、技术、端口、数据包、芯片）。
• 是否生成了配套的 architecture.md？（必需——请参阅第 6 步。）

如果 puppeteer-core 和 Chrome/Chromium 二进制文件可用，运行 node references/screenshot.js architecture.html。该脚本会截取桌面和手机预览图，输出页面自身的完整性警告；如果图表引发 JavaScript 错误，则以非零状态码退出——若退出码非零，请先修复 HTML，再展示给用户。

步骤 5 — 输出文件

始终输出两个文件：

• architecture.html — 交互式图表
• architecture.md — 文本说明（组件、分步流程、模式差异、工作坊场景）

保存到当前工作目录。平台特定的覆盖规则：

• Claude.ai — 改为保存到 /mnt/user-data/outputs/
• Claude Code / Gemini CLI / OpenCode / Copilot CLI — 保存到当前工作目录（默认）

两个文件都应能独立使用——无需打开 HTML 就能阅读 Markdown，反之亦然。

步骤 6 — 呈现输出

告知用户文件的保存位置以及打开方式（在 macOS 上使用 open architecture.html，在 Linux 上使用 xdg-open architecture.html，也可以直接在浏览器中打开）。如果有 present_files（Claude.ai）可用，则先调用它显示 HTML，再显示 Markdown。

---

文件参考

文件	何时读取
assets/template.html	**始终读取。**这是复制并修改的起始模板。
assets/css-tokens.css	用户要求更改样式时读取（例如浅色主题、不同的品牌颜色）。这些独立的令牌可插入现有 CSS。
references/flow-design-patterns.md	从头规划新系统时读取。提供节点布局、流程命名、步骤排序和模式选择方面的启发式建议。
references/component-library.md	构建节点列表时读取。包含 User/API/DB/Queue/Cache/LLM/Cron/External 等节点的可复制片段，以及正确的角色和图标。
references/screenshot.js	想在向用户展示结果前进行抽查时读取。如果已安装 puppeteer-core，可使用 node 运行。
examples/rag-eskadra-bielik.json	参考示例：包含 5 个流程和离线/在线模式的真实 RAG 系统。可了解拓扑布局、离线/在线模式设计（按节点切换技术/端口）以及通过 step_outline 分解流程。载荷/标签约定见下方章节，而非示例。
examples/auth-oauth2.json	参考示例：包含开发/生产模式的 OAuth2 + 会话流程。展示重定向流程和外部 IdP 节点。
examples/event-driven.json	参考示例：使用 Kafka 的事件驱动微服务，展示异步扇出流程。
examples/cicd-pipeline.json	参考示例：使用 GitHub Actions 的 CI/CD 流水线，包含预发布/生产模式和回滚流程。
examples/agentic-tool-calling.json	参考示例：使用工具调用的 Agentic AI 系统，包含单 Agent 与多 Agent 模式。

examples/*.json 文件是规划规范，并非可直接使用的代码——它们是 JSON 大纲，需要转换为模板的 HTML 节点和内联 JS flows 对象。请参阅 references/flow-design-patterns.md →“示例 JSON → 模板映射”，了解逐字段转换方法。

---

快速参考 — 节点角色与颜色

在 template.html 的 CSS 变量中硬编码。每个节点选择一个：

角色	颜色	用途
user	薄荷绿 #46f9b8	浏览器、移动客户端、终端用户、CLI 用户
orch	天蓝色 #6aa9ff	API 网关、编排器、BFF、控制器
compute	洋红色 #ff6b8a	LLM、ML 模型、高成本计算
embed	琥珀色 #ffc14d	嵌入服务、转换器、预处理器
vector	紫罗兰色 #b388ff	数据库（任意类型）、向量存储、缓存、Blob 存储
seed	橙色 #ff9457	Cron、一次性任务、迁移、种子数据、计划任务

如果需要更多角色，请添加 CSS 变量。角色数量应 ≤ 6——超过此数量，图例会变成色盲噩梦。

例如，如果系统有两个不同的数据存储（Postgres + Redis），两者仍使用 vector，通过图标和标签加以区分，不要另设第 7 种颜色。

---

视觉状态 — 查看者在每个步骤中看到的内容

这是图表中最重要的教学机制。修改 JS 或 CSS 之前，请先理解它，否则你会破坏“点击一个流程标签页，就能看到完整路径”的直觉体验。

用户选择流程标签页并进入步骤 N 后，每个节点和连线都会被归为以下某种状态：

元素	状态	显示效果	条件
节点	active	完整光环 + 发光效果 + 步骤编号徽标	当前步骤的目标节点（例如步骤说明为“Orch → LLM”时的 LLM）
节点	active-from	柔和光环，不显示徽标	当前步骤的源节点
节点	participant	接近完整的不透明度，略微降低饱和度	在此流程的其他步骤中出现，但不在当前步骤中
节点	dimmed	25% 不透明度，颜色变淡	完全不属于此流程（例如 login 流程中的 seed）
节点	hidden	不可见	完全排除在当前模式之外（例如在线模式下的 seed 节点）
连线	active	鲜明的角色颜色、发光效果、数据包动画	当前步骤的连线
连线	preview	50% 不透明度的角色颜色，虚线	属于此流程，但不属于当前步骤 — 显示后续的完整路径
连线	muted	约 8% 不透明度	不属于此流程

participant 状态为何重要（以及 JS/CSS 实现中的注意事项）详见 references/flow-design-patterns.md → “The participant state”。简而言之，它能让查看者在第一次点击时就看到完整路径，而不必逐步操作来发现流程使用了哪些节点——这正是图表的核心目的。如果要添加节点状态，请确保 applyStep 和 CSS（.node.participant、.wire.preview）保持一致。

---

交互模型

图表支持五种交互方式，按查看者的熟悉程度从低到高排列：

交互方式	操作效果	使用者
点击流程标签页	跳转到该流程的第一个可播放步骤，并更新侧边面板	所有人
点击 Next/Prev（或按 →/←、Space）	前进/后退一步；到达末尾时，Play 会重新播放该流程	跟随演示操作的工作坊参与者
点击节点	跳转到该节点首次出现的步骤	想要探索的好奇查看者
拖动节点（鼠标/触控笔），或聚焦节点后按 Shift+方向键	在画布上重新定位节点；连线实时重绘；布局按浏览器保存	调整布局的用户 / 演示者
全屏（F）	画布铺满屏幕，控制栏位于顶部，流程标签页位于底部，侧边面板以叠加层显示；按 Escape 或再次点击同一按钮即可退出	工作坊演示者

点击节点与拖动节点。 5px 的移动阈值用于区分点击（跳转到步骤）和拖动（重新定位）。在触摸屏上，节点只能通过点击跳转，因此在节点上滑动仍会滚动页面。

修改此 skill 时，最容易漏掉的是节点点击功能。 以下三项缺一不可：

1. 在 .node 上设置 cursor: pointer（提供视觉提示——“可点击”）
2. 设置 :hover 状态以显示角色颜色（确认可交互）
3. 编写 JS 处理程序，在当前流程的步骤中执行 findIndex 并跳转到对应步骤

如果节点不属于当前流程（.dimmed 状态），点击它会使节点抖动，而不是毫无反应。静默忽略会带来糟糕的用户体验——查看者会以为页面坏了。

键盘无障碍支持：节点设有 tabIndex=0；按 Enter/Space 可触发与点击相同的操作；按 Shift+方向键可将节点移动一个网格单元。步骤更改会通过实时区域播报。可通过标签页下方的“shortcuts on”链接关闭单键快捷键（WCAG 2.1.4）。

添加功能时，别破坏这些交互。 这是查看者想到“等等，LLM 在哪里用到了？”并立即找到答案的唯一方式。否则，他们必须逐步操作全部 8 个步骤，才能弄清某个节点的作用。

快速参考 — 负载格式

侧边栏中的负载采用等宽字体，并使用最精简的语法高亮。内容应贴近实际但有所精简——展示结构，省略无关字段：

{
  payloadOffline:
`POST /ask
{
  "query": "Ile kosztuje parking?",
  "limit": 3,
  "temperature": 0.7
}`
  // avoid: full HTTP headers, User-Agent, 50-line bodies — show only the shape
}

缩进 4 个空格，不要使用制表符。使用 // comments 添加行内注释。

如果两个模式中的某个步骤相同，请使用 payload（单个键）。如果不同，请使用 payloadOffline + payloadOnline（也可以使用对应的模式名称：payload + 首字母大写的模式键，例如模式 prod → payloadProd）。同时存在时，模式专属键优先——这在“通用负载，某个模式覆盖它”的场景中很方便。chips / chipsOffline 也遵循相同规则。对象而非字符串会被格式化为易读的 JSON。

desc 仅接受内联 HTML：<em>、<strong>、<code>、<kbd>、<br>、<a href="https://…">。其他内容都会在渲染时被剥除（块级标签会被解包，脚本和 iframe 会被删除）——描述请控制在一到三句话。

---

快速参考 — 芯片（元数据徽标）

负载下方的芯片是简短的元数据标签。两种语义类型会自动设置样式：

• 延迟（匹配 /\d+\s*(?:ms|s|min)\b/）——显示秒表图标，例如 "~150ms"、"5-30s"、"timeout 120s"
• 大小/计数（匹配 /dim|×|loaded|rules|count/）——显示数据库图标，例如 "768 dim"、"38 loaded"、"×N"
• 其他——中性样式，例如 "COSINE"、"baseline"、"idempotent"、"UUID5"

每个步骤最多 3 个芯片。它们只是提示，并非规范。

---

命名约定

项目	约定	示例
JS 中的流程键	snake_case	ask、ask_direct、ingest_text
流程显示名称	"标题式大小写（METHOD /route）"	"RAG Query (POST /ask)"
节点 data-id	snake_case，简短	orch、vector、embed
模式键	snake_case，描述性名称	offline/online、dev/prod、v1/v2
步骤标题	根据工作坊语言使用波兰语或英语。同一文件中保持一致。	"Pytanie z UI" 或 "Question from UI"

常见陷阱

任何字符串中出现 </script> 都会导致一切失效。 如果某个 payload、desc、title 或 chip 中包含字符串 </script>（例如展示 HTML 片段），浏览器的 HTML 解析器会将其视为主 <script> 块的结束标签，从而导致所有 JS 失效。在模板字面量中将其转义为 <\/script> 或 </script>。</style> 和类似的结束标签也适用此规则。

页面会检查自身。 打开浏览器控制台（或运行 references/screenshot.js）：警告会列出步骤中未知的节点 ID、缺少 flows 条目的流程标签（反之亦然）、未知的 onlyMode / data-modes 值、缺少的 title / color，以及未替换的 {{PLACEHOLDERS}}。控制台干净才算“完成”。

内容安全策略。 模板自带一个 CSP <meta>，只允许内联脚本、样式和 Google Fonts。如果用户要求使用外部图片、脚本或字体，请扩展相应的指令（否则控制台会显示请求被拦截）。

源节点看起来失效。 如果某个步骤的源节点渲染为 dimmed 而不是 active-from，说明你破坏了参与者逻辑——请参阅“视觉状态”。

连线交叉。 这是由节点位置导致的，不是代码问题——调整节点位置即可修复。（模板会根据步骤索引自动让连线交替弯曲，这有帮助，但无法修复糟糕的布局。）

流程太多。 超过 6 个流程会让标签栏变得杂乱。如果有 8 个或更多流程，请将它们分组：每组绘制一张图（例如，将“读取流程”和“写入流程”分别放在两个 HTML 文件中）。

并非真正的模式。 如果切换项会改变整个拓扑结构（不同的服务、不同的协议），那就不是模式，而是第二套系统。请创建两个 HTML 文件。

静态截图有时胜过动态图。 如果图表最终会出现在 PDF 报告、幻灯片或打印讲义中，那么这项技能就不适合——请改用静态图表。这项技能适用于在浏览器中交互式查看。

忘记 .md 文件。 HTML 是展示亮点，但人们会在 GitHub 上阅读 .md 文件、将其粘贴到 Slack 中，并搜索其中的端点名称。务必同时生成两者。

波兰语还是英语。 应与工作坊使用的语言一致。双语环境通常在内部工作坊中使用波兰语，在面向客户的交付物中使用英语。不确定时请询问。

---

扩展模板

如果用户要求添加模板不支持的内容，以下是难度评级：

请求	难度	修改位置
新节点	简单	添加 .node div，通过 left/top 百分比设置位置
新流程	简单	在 flows 对象中添加条目
更换品牌颜色	较简单	修改 :root 中的 CSS 变量（参见 assets/css-tokens.css）
浅色主题	内置	点击月亮／太阳按钮或按 T。要将浅色设为默认主题，请将 class="light" 添加到 <body>。
拖放节点	内置	已支持——拖动任意节点（使用鼠标／触控笔），或对聚焦的节点按 Shift+Arrow；节点位置会吸附到 48px 网格，并保存在 localStorage 中（以页面标题 + 节点 ID 集合为键——请为每张图指定唯一标题）。
全屏模式	内置	按 F 或点击展开图标。控制栏、流程标签和侧边栏仍可访问；按 Escape 或点击按钮即可退出。
自身步骤（内部工作）	内置	当 from === to 时，步骤会在节点上方绘制一个环路。
三种或更多模式	较简单	在 .modepick 中添加按钮；添加 payload<Mode> / chips<Mode> / data-*-<mode> 字段。按 O 会自动循环切换所有模式。
重置布局	内置	按 R 或点击 ↻ 按钮（拖动后显示）。
进度条	内置	播放器下方的细条显示当前流程中的步骤位置。
流程备注行	内置	为流程设置 note（为 onlyMode 流程设置 onlineNote）；备注会显示在播放器下方。
减少动态效果	内置	遵循 prefers-reduced-motion：隐藏飞行数据包并收起过渡效果。
并行步骤（两条连线同时进行）	中等	将步骤组合为 {parallel: [step, step]}；播放器会同时推进两条连线
分支流程（if-then-else）	困难	目前流程是线性的。可以拆分为独立流程，也可以添加 branch 字段并提供用于选择分支的界面。
在 URL 中保存状态	较简单	基于哈希：#mode=online&flow=ask&step=3——在启动时解析，并在状态变化时更新

不要承诺模板不支持的功能，除非明确说明所需工作。

---

迭代建议

当用户反馈“图表太拥挤”或“第 5 步令人困惑”时：

• “太拥挤” → 拉开节点间距；可用宽度为 100%。相邻节点之间的水平间距不要小于 12%。
• “步骤令人困惑” → 步骤描述包含的内容太多。将其拆成两个步骤，或改写为只聚焦于一次交接（X 将 Y 发送给 Z，仅此而已）。
• “这与实际工作方式不符” → 询问实际的代码路径。不要猜测；如果图表描述的实际情况不正确，它就毫无价值。
• “让它更醒目” → 克制这种冲动。教学清晰度 > 视觉冲击力。或许可以添加一个强调元素（例如流程完成时让结果节点发光），但到此为止。
• “添加图例” → 图例已经存在。如果他们希望图例更大，请增大 .legend 的字体大小和间距。