References

# Skill: 通用技术架构图绘制规范 v2.0（System-Agnostic Architecture Diagram Skill）

> **定位**：工具无关、系统无关、场景全覆盖的架构图绘制指令集。可加载于任意 AI Agent，指导其在任何技术领域（后端、前端、数据、云原生、安全、DevOps、AI/ML、IoT、区块链等）产出专业、一致、可读的架构图。
> **目标受众**：架构师、研发工程师、技术负责人。
> **回答的核心问题**：
> 1. 功能通过什么技术栈实现？如何选型？
> 2. 项目/服务的逻辑分层与物理结构是什么？
> 3. 服务、进程、任务、调用链路如何协作？
> 4. 稳定性、扩展性、安全性、可观测性如何保障？
> **推荐工具**：Excalidraw / Draw.io (diagrams.net) / PlantUML / SVG/HTML / Lucidchart。Agent 应根据场景自行选择最合适的工具，或按用户指定工具输出。

---

## 1. 核心原则

### 1.1 抽象化原则
- **禁止**在 Skill 规范中硬编码任何业务组件名（如"订单服务"、"Kafka"、"MySQL"）。所有节点使用**角色类型**描述（如"接入网关"、"计算引擎"、"持久化存储"），具体命名由场景上下文注入。
- 连线标注使用**动作/协议类型**（如"同步调用"、"异步事件"、"配置下发"），而非具体 API 路径或表名。

### 1.2 视角单一原则
- **一张图只回答一个问题**。禁止在同一张图中混合逻辑结构、物理部署、数据流、安全域、前端组件树。复杂系统必须拆分为多张图，通过统一图例和命名建立关联。

### 1.3 语义优先原则
- 形状、颜色、线条必须有**自解释性**。看图者无需图例也能猜出 80% 的语义。图例用于精确校准，而非补课。

### 1.4 约束可视化原则
- 架构约束（如"必须走 TLS"、"单线程处理"、"跨区延迟 > 100ms"）必须通过**视觉元素**（红色边框、注释框、线型粗细）直接表达，而非仅靠文字说明。

---

## 2. 七大架构视角（Viewpoint）

每张图必须在标题或左上角明确声明其视角。Agent 根据场景选择 1~2 个主视角，禁止贪多。

| 视角 | 回答的问题 | 该画的元素 | 不该画的元素 | 推荐布局 |
|------|-----------|-----------|-------------|---------|
| **逻辑视图（Logical）** | 系统分哪些功能模块？模块间如何协作？接口契约是什么？ | 子系统、服务、组件、领域边界、接口 | 机器 IP、端口号、具体软件版本、K8s Pod 名 | 分层堆叠、Hub-Spoke、树状 |
| **物理/部署视图（Deployment）** | 跑在什么上？如何分布？容灾拓扑？ | 节点、集群、区域、机房、容器/虚机框、负载均衡器 | 内部业务逻辑、方法调用链、数据库表结构 | 区域同心、分层堆叠、Hub-Spoke |
| **数据视图（Data）** | 数据从哪来？到哪去？如何转换？一致性策略？ | 数据源、数据目的地、ETL、缓存、格式转换、主从/副本 | 控制信号、审批流程、用户界面、业务状态机 | 流水线、分层堆叠 |
| **运行时/进程视图（Runtime）** | 运行起来后线程/进程/协程如何协作？调度策略？ | 进程、线程池、协程、执行器、调度队列、锁/信号量、批处理窗口 | 静态代码结构、数据库 ER 关系、部署机器名 | 分层堆叠、Hub-Spoke、流水线 |
| **安全视图（Security）** | 信任边界在哪？如何鉴权加密？攻击面？ | 防火墙、DMZ、TLS/加密通道、身份源、审计点、零信任代理 | 业务数据流细节、内部算法、缓存策略 | 区域同心、Hub-Spoke |
| **集成视图（Integration）** | 与外部系统如何对接？协议转换？防腐层？ | 外部系统、协议适配器、防腐层、消息格式、开放 API 边界 | 内部模块实现细节、数据库分片 | Hub-Spoke、分层堆叠 |
| **全景总览（Landscape）** | 本系统在整个产品/生态中的位置？ | 本系统黑盒 + 周边系统白盒 + 主要交互 + 方向箭头 | 内部任何展开细节 | Hub-Spoke、分层堆叠 |

---

## 3. 六大通用布局模式（Layout Primitives）

不再强制单一水平分层。Agent 应根据系统本质选择布局，复杂图可**局部混合**。

### 3.1 分层堆叠（Tier Stack）
- **特征**：水平条带，自上而下依赖，上层调用下层。
- **适用**：传统后端、单体应用、微服务分层、云原生控制平面。
- **规则**：
  - 默认 4~5 层：接入/交互 → 控制/治理 → 执行/计算 → 数据/资源 → 基础设施/观测。
  - 同层节点语义相近；层间连线体现依赖方向，避免循环箭头。
  - 层间距 ≥ 节点高度的 1.2 倍。

### 3.2 中心辐射（Hub-Spoke）
- **特征**：中心大节点，周围卫星节点均匀分布，所有交互经中心转发。
- **适用**：API Gateway、消息总线、特征平台、控制平面、星型网络。
- **规则**：
  - 中心节点使用较大体积或 3D 立方体，体现其协调地位。
  - 卫星节点到中心的连线标注"注册/发现"、"心跳"、"上报"。
  - 卫星节点之间**禁止直接连线**（否则退化为网状）。

### 3.3 流水线/链式（Pipeline）
- **特征**：从左到右阶段节点，阶段内可纵向扩展并行实例。
- **适用**：CI/CD、ETL、推理 Pipeline、编译链、流处理、审批流。
- **规则**：
  - 阶段之间用粗实线连接，标注数据格式或契约变更（如"JSON → Parquet"）。
  - 阶段内部用虚线框包裹多个并行执行器，标注"并发度 N"。
  - 支持旁路（Bypass）和回环（Retry/Feedback），用不同线型区分。

### 3.4 树状层级（Hierarchy）
- **特征**：根在上，枝叶向下展开，体现包含、继承、命名空间关系。
- **适用**：前端组件树、组织权限、目录结构、K8s 资源层级、类/模块依赖。
- **规则**：
  - 父子连线使用无箭头实线或空心箭头，体现"包含"而非"调用"。
  - 同层子节点等距排列，宽度递减体现层级深度。
  - 深层节点过多时，使用"..."折叠或指向子图。

### 3.5 区域同心（Concentric Zone）
- **特征**：从内到外信任度/敏感度递减，用同心矩形或圆形表示。
- **适用**：零信任安全、DMZ、网络隔离、分级保护、多环境（Dev/Test/Prod）。
- **规则**：
  - 最内层为核心域（高敏感），最外层为外部/不可信域。
  - 域间穿越必须使用**锯齿框防火墙**或**红色粗虚线**标注。
  - 每层标注信任等级或安全策略（如"L3 敏感数据 / mTLS 双向认证"）。

### 3.6 网状对等（Mesh / P2P）
- **特征**：节点均匀分布，彼此多对多连线，无绝对中心。
- **适用**：区块链、服务网格数据面、去中心化系统、联邦学习、Gossip 协议集群。
- **规则**：
  - 节点使用统一形状和大小，体现对等性。
  - 连线使用双线或双向箭头，体现"双向同步"或"共识通信"。
  - 关键路径（如共识 leader 选举）用高亮颜色或粗线突出。

### 3.7 布局组合规则
- 全局采用一种主布局，局部可嵌套另一种布局。
- 示例：整体为分层堆叠（后端架构），其中"执行引擎"层内部采用 Hub-Spoke 展示服务网格 Sidecar 代理关系。
- 禁止超过两种布局混合，避免视觉混乱。

---

## 4. 形状语义规范（跨工具统一）

以下形状语义必须在所有工具中保持一致。若某工具无原生形状，使用最接近的替代并统一图例说明。

| 形状 | 语义 | 推荐替代/工具映射 |
|------|------|------------------|
| **圆角矩形 / 矩形** | 通用服务、进程、应用实例、工作节点、无状态服务 | Excalidraw: Rectangle；Draw.io: Rectangle；SVG: `<rect rx="6">` |
| **立方体 / 3D Box** | 独立子系统、可部署单元、领域边界上下文、强内聚模块 | Excalidraw: 3D Box；Draw.io: 3D Box；SVG: 分层矩形/阴影体块 |
| **圆柱体** | 持久化存储、数据库、数据仓库、文件系统、对象存储、日志存储 | Excalidraw: Cylinder；Draw.io: Cylinder；SVG: 椭圆顶 + 矩形体 |
| **椭圆 / 圆角胶囊** | 中间状态、缓存、队列、缓冲区、配置中心、消息总线、注册中心 | Excalidraw: Ellipse；Draw.io: Ellipse / Capsule；SVG: `<ellipse>` 或圆角胶囊 |
| **菱形** | 决策点、路由网关、负载均衡器、过滤器、熔断器、准入控制 | Excalidraw: Diamond；Draw.io: Diamond；SVG: `<polygon>` |
| **六边形** | 微服务独立部署单元、DDD 限界上下文、可独立发布的模块 | Excalidraw: Hexagon；Draw.io: Hexagon；SVG: 六边形 polygon |
| **管道 / 横向圆柱** | 数据管道、流式处理通道、消息总线、ETL 链路、事件流 | Draw.io: Pipe；SVG: 横向圆角矩形 + 内部流动箭头；Excalidraw: 胶囊 + 注释 |
| **锯齿框 / 粗红线框** | 防火墙、安全边界、网闸、零信任隔离域、受控穿越点 | Draw.io: Firewall；SVG: 自定义锯齿 path；Excalidraw: 手绘粗框 + 红色描边 |
| **人形图标** | 终端用户、管理员、外部参与者、业务角色、人工审批节点 | Draw.io: Actor；Excalidraw: 简化人形；SVG: 人形轮廓 |
| **时钟 / 扇形** | 定时触发器、Cron 调度、超时检测、批处理窗口、心跳周期 | Draw.io: Clock；Excalidraw: 椭圆 + 内部指针；SVG: 圆形 + 指针 |
| **文档/页面图标** | 配置模板、契约文件、Schema、API 文档、Protobuf/IDL | Draw.io: Document；SVG: 折角文档；Excalidraw: 矩形 + 折角标记 |
| **云形 / 不规则形** | 外部第三方系统、SaaS、公有云服务、不可控外部依赖 | Excalidraw: Cloud；Draw.io: Cloud；SVG: 云形 path |
| **虚线矩形框** | 逻辑分组、子系统边界、部署域、命名空间、资源池、故障域 | Excalidraw: Dashed Rectangle；Draw.io: Dashed Rectangle / Container；SVG: `stroke-dasharray` 容器 |
| **纵向虚线带** | 多租户隔离、环境隔离（Dev/Test/Prod）、AZ 可用区、组织分区 | 贯穿全图的纵向虚线带，顶部标注分区名 |

---

## 5. 线条与连接规范

### 5.1 线条类型语义（强制遵守）

| 线条样式 | 语义 | 标注示例 | 线宽 |
|---------|------|---------|------|
| **实线 + 实心三角箭头** | 同步强依赖调用、直接请求、阻塞式 RPC/HTTP | `同步调用 / RPC` | 1.5~2px |
| **实线 + 空心箭头 / 普通线** | 单向数据流、读取关系、配置下发、主从同步 | `读取配置 / Pull` | 1~1.5px |
| **虚线 / 点线 + 箭头** | 异步事件、消息推送、回调、通知、心跳/监控信号 | `发布事件 / Async` | 1px |
| **虚线 + 空心箭头** | 弱依赖、可选依赖、降级路径、旁路调用 | `降级读取 / Cache-Aside` | 1px |
| **点划线 + 箭头** | 定时/周期触发、Cron、巡检、超时检测 | `定时触发 / 5min` | 1px |
| **双线 + 箭头** | 双向流、全双工通信、长连接、双向同步 | `双向流 / WebSocket` | 1.5px |
| **红色粗虚线** | 安全边界穿越、高危操作、跨域调用、特权访问 | `跨域访问 / mTLS` | 2~3px |
| **无箭头实线** | 聚合关系、包含关系、物理部署关联、父子层级 | `包含 / 部署于` | 1px |
| **回环箭头 / 带 ↻ 标记** | 重试机制、补偿事务、反馈控制、循环处理 | `重试 3次 / 指数退避` | 1px |

### 5.2 连线标注规范
- **每条跨层或跨域连线必须标注**。同层内部简单调用可省略，但建议在复杂图中统一标注。
- 标注格式：**动作 + 协议/机制**，如 `提交任务 / 异步消息`、`读取配置 / 长轮询`。
- 标注位置：靠近箭头中部，使用小字号（节点标题的 60%~70%），颜色使用**灰色 `#757575`** 或低饱和度色。
- 多条同类型连线可合并为一条并标注"聚合 N 路"，避免蜘蛛网。

### 5.3 动态行为的线条表达
- **流量粗细**：核心高频路径使用粗线（2~3px），边缘低频路径使用细线（1px）。
- **批量/聚合**：多条细线汇入一条粗线时，在汇合点标注「N:1 聚合」或「批处理」。
- **分叉/并行**：从一个节点引出多条等粗实线，标注「并行分发 / Fork-Join」。
- **时序编号**：在关键链路连线上标注 `① → ② → ③`，配合脚注说明每步的耗时/超时策略。

### 5.4 线条路由
- 优先使用**正交连线**（曼哈顿路由），保持横平竖直，减少斜线。
- 连线尽量不穿越节点主体；若必须穿越，使用半透明或细线降低干扰。
- 同层节点之间连线优先从**右侧出、左侧入**；跨层连线优先**上出下入**。

---

## 6. 颜色与填充规范

### 6.1 语义调色板（低饱和高区分）

采用低饱和度、高区分度配色，确保打印、投影、深色模式均可读。

| 语义角色 | 填充色（HEX） | 描边色（HEX） | 用途 |
|---------|--------------|--------------|------|
| **接入/交互层** | `#E3F2FD` | `#1976D2` | 网关、入口、前端、API 层、负载均衡 |
| **控制/治理层** | `#FFF3E0` | `#F57C00` | 调度器、配置中心、审批/流程引擎、服务注册发现 |
| **执行/计算层** | `#E8F5E9` | `#388E3C` | 业务服务、计算引擎、工作进程、函数实例 |
| **数据/存储层** | `#F3E5F5` | `#7B1FA2` | 数据库、缓存、文件系统、对象存储、消息队列 |
| **外部依赖/第三方** | `#FFF9C4` | `#FBC02D` | 第三方系统、外部 API、SaaS、云服务、客户端 |
| **观测/基础设施** | `#ECEFF1` | `#455A64` | 监控、日志、告警、注册中心、链路追踪、CI/CD 工具 |
| **安全/网络层** | `#FFEBEE` | `#D32F2F` | 防火墙、安全边界、加密通道、身份认证、审计 |
| **高亮/核心路径** | `#FFEBEE` | `#D32F2F` | 关键链路、主流程、需重点说明的节点、热点路径 |
| **多租户/环境分区** | `#F5F5F5` | `#9E9E9E` | Dev/Test/Prod 环境隔离带、可用区、组织分区 |

### 6.2 填充与描边规则
- **普通节点**：浅色填充 + 深色 1.5px 描边。
- **边界/分组框**：无填充或极浅灰填充 `#FAFAFA` + 深色虚线描边（2px）。
- **存储类节点**：顶部椭圆面使用略深同色填充，体现立体感。
- **安全边界/防火墙**：无填充 + 红色 2~3px 锯齿或粗虚线描边。
- **外部依赖**：可使用轻微渐变或阴影，与内部系统形成视觉隔离。
- **禁用高饱和纯色填充**（如纯红 `#FF0000`、纯绿 `#00FF00`），避免视觉疲劳和打印失真。

### 6.3 灰度可读性检查
- Agent 应自检：将配色转换为灰度后，相邻层级的节点是否仍能区分？若不能，调整亮度差 ≥ 20%。

---

## 7. 文字与排版规范

### 7.1 字体层级

| 元素 | 字号比例 | 字重 | 对齐方式 | 颜色 |
|------|---------|------|---------|------|
| 图表主标题 | 1.5x 基准 | Bold | 顶部居中 | `#212121` |
| 视角声明标签 | 1.1x 基准 | SemiBold | 左上角或标题旁 | `#757575` |
| 子系统/边界标题 | 1.2x 基准 | SemiBold | 边界框顶部居中或左上 | `#424242` |
| 节点名称 | 1.0x 基准 | Medium | 节点内部居中 | `#212121` |
| 节点内补充说明 | 0.8x 基准 | Regular | 节点内部底部居中 | `#757575` |
| 连线标注 | 0.7x 基准 | Regular | 沿连线居中或上方 | `#757575` |
| 注释框/脚注 | 0.7x 基准 | Regular | 左对齐或气泡指向 | `#616161` |
| 图例文字 | 0.7x 基准 | Regular | 左对齐 | `#616161` |

- **基准字号**：Excalidraw/Draw.io 中使用 14~16px；SVG 中使用 `14px` 基准；若做深色主题 HTML / SVG，总字号不降级、优先通过对比度与间距解决拥挤。
- **字体族**：统一使用无衬线字体（Inter, Segoe UI, Helvetica, Arial, PingFang SC, Microsoft YaHei, 或系统默认 sans-serif）。
- **中文场景**：确保中文字号不小于 12px，避免笔画粘连。

### 7.2 文字间距与换行
- 节点内文字**单行优先**；若必须换行，最多 2 行，行高 1.3~1.4。
- 节点内边距（Padding）：水平 ≥ 文字高度的 0.5 倍，垂直 ≥ 0.3 倍。
- 避免文字与边框粘连，保持呼吸感。

### 7.3 命名规范
- 节点名称采用"**形容词 + 角色**"或"**角色 + 类型**"结构，如"接入网关"、"任务调度器"、"分布式缓存"。
- **禁止**使用动词开头命名节点（节点是实体，不是动作）。错误示例：`处理数据`、`发送消息`。正确示例：`数据处理引擎`、`消息发送器`。
- 同类节点命名风格保持一致（如全部用"XX 层"、"XX 引擎"、"XX 池"、"XX 代理"）。
- 缩写首次出现应标注全称，如"LB（负载均衡）"、"CDC（变更数据捕获）"。

---

## 8. 布局与对齐规范

### 8.1 网格与间距
- 全局开启**网格对齐**（Grid Snap），推荐网格尺寸 10px 或 20px。
- **同层节点间距**：水平方向 ≥ 节点平均宽度的 0.5 倍；垂直方向 ≥ 节点平均高度的 0.8 倍。
- **层间距**：相邻逻辑层之间的垂直留白 ≥ 节点高度的 1.2 倍，确保连线标注有充足空间。
- **边界框内边距**：边界框与内部节点的间距 ≥ 节点高度的 0.5 倍。

### 8.2 对齐策略
- 同层节点**顶部对齐**或**中心对齐**，严禁参差不齐。
- 跨层节点尽量保持**垂直中心对齐**，形成清晰的"列"视觉。
- 多个并行执行单元使用**等宽等距水平排列**，体现对称与扩展性。
- 流水线阶段节点使用**等高等距水平排列**，阶段内并行节点纵向等距排列。

### 8.3 信息密度控制
- 单图节点数建议控制在 **7±2 个核心节点**（米勒定律）；复杂系统应拆分为"总览图 + 子域详图"。
- 总览图突出**分层与主链路**；详图突出**内部状态机、线程模型、数据转换细节**。
- 若节点过多，使用**泳道（Swimlane）**或**子图折叠**机制，或拆分为新图。

---

## 9. 架构要素的抽象表达模板

当绘制具体系统时，将实际组件映射到以下抽象角色，再套用对应形状与颜色。

### 9.1 接入与交互
- **入口网关 / 边缘代理**：统一入口、鉴权、路由、限流、SSL 终止 → 菱形或圆角矩形，接入层颜色。
- **终端 / 客户端**：用户设备、浏览器、移动端、上游系统 → 云形或外部矩形，外部依赖颜色。
- **界面 / 控制台 / Portal**：管理后台、可视化界面、配置 UI → 圆角矩形，接入层颜色。
- **API 暴露面 / BFF**：对外暴露的聚合层、Backend-for-Frontend → 六边形，接入层颜色。

### 9.2 控制与治理
- **调度器 / 编排器**：任务分发、依赖管理、DAG 调度、状态机 → 圆角矩形，控制层颜色。
- **配置中心 / 模板库**：动态配置、开关、模板、版本管理 → 椭圆或文档图标，控制层颜色。
- **流程引擎 / 规则引擎**：审批、工作流、业务规则、策略执行 → 圆角矩形或立方体，控制层颜色。
- **注册 / 发现中心**：服务注册、健康检查、元数据管理 → 椭圆或菱形，基础设施颜色。
- **网关控制面**：服务网格控制面、Ingress Controller → 圆角矩形，控制层颜色。

### 9.3 执行与计算
- **无状态服务 / 实例**：业务逻辑、API 服务、函数计算 → 矩形，执行层颜色。
- **计算引擎 / 执行器**：批处理、流处理、算法引擎、推理服务 → 立方体或矩形，执行层颜色。
- **工作节点 / 线程池 / 协程池**：具体执行单元、进程池、Worker → 嵌套矩形（内部小矩形阵列），执行层颜色。
- **代理 / 适配器 / Sidecar**：协议转换、数据清洗、服务网格代理 → 圆角矩形或六边形，执行层颜色。
- **定时任务 / Cron**：周期性执行、批处理窗口 → 时钟图标，执行层颜色。

### 9.4 数据与资源
- **关系型存储**：事务数据、元数据、强一致性数据 → 圆柱体，数据层颜色。
- **缓存 / 高速存储**：热点数据、会话、分布式锁、计数器 → 椭圆，数据层颜色。
- **消息队列 / 事件总线**：异步解耦、事件流、广播 → 椭圆或管道形，数据层颜色。
- **文件 / 对象存储**：日志、附件、大文件、冷数据 → 圆柱体或文件夹形，数据层颜色。
- **索引 / 检索引擎**：全文检索、日志检索、特征向量检索 → 圆柱体，数据层颜色。
- **数据管道 / ETL**：数据抽取、转换、加载、流式同步 → 管道形，数据层颜色。

### 9.5 观测与保障
- **监控中心 / 链路追踪**：指标采集、分布式追踪、性能剖析 → 虚线框内矩形，基础设施颜色。
- **告警 / 通知中心**：多渠道告警、事件升级、值班通知 → 圆角矩形，基础设施颜色。
- **日志 / 审计中心**：持久化日志、操作审计、合规存档 → 圆柱体，基础设施颜色。
- **混沌工程 / 演练**：故障注入、容灾演练 → 圆角矩形，基础设施颜色。

### 9.6 安全与网络
- **身份源 / IAM**：统一认证、SSO、OAuth、JWT 签发 → 圆角矩形，安全层颜色。
- **防火墙 / WAF / 网闸**：流量过滤、攻击防护、边界控制 → 锯齿框，安全层颜色。
- **加密通道 / TLS**：数据传输加密、证书管理 → 双线或带锁标记的连线，红色或安全层颜色。
- **审计点**：敏感操作记录、合规检查点 → 小圆点或菱形，安全层颜色。

---

## 10. 稳定性、扩展性、安全性的可视化表达

架构图必须回答"稳定性如何保障"，通过以下视觉手段表达：

### 10.1 冗余与扩展
- **多实例并列**：同一角色绘制 2~3 个相同小矩形横向排列，标注"实例 N"或"副本集"或"可横向扩展"。
- **负载均衡**：在入口与实例之间插入菱形，标注"分发策略 / 轮询|随机|一致性哈希"。
- **读写分离**：从存储节点引出两条线，分别标注"读副本"和"写主库"。

### 10.2 隔离与降级
- **分组边界**：使用虚线框将核心链路与非核心链路物理隔离，标注"核心域"和"非核心域"。
- **熔断/降级示意**：在调用线上添加红色虚线旁路，标注"降级路径 / 读取缓存"或"熔断 / 返回默认值"。
- **舱壁隔离**：使用纵向虚线带划分泳道，标注"租户 A / 租户 B"或"AZ-1 / AZ-2"。

### 10.3 可观测性
- **Watch / 探针**：从观测节点指向被观测节点的虚线，标注"健康检查 / TCP|HTTP"、"指标采集 / Prometheus"。
- **通知链路**：从任意节点指向告警中心的虚线，标注"异常事件 / 阈值触发"。
- **链路追踪注入**：在执行节点旁标注小标签「Trace ID 透传」，或在连线上标注「OpenTelemetry」。

### 10.4 数据一致性
- **主从 / 副本 / 分片**：存储节点内部画小矩形分区，或并列圆柱体，标注"主 / 从"、"副本 0..N"、"分片 Key"。
- **事务 / 补偿**：在跨节点调用上标注"Saga"、"TCC"或"最终一致 / 异步对账"。
- **缓存一致性**：在缓存与存储之间画双向线，标注"写穿透 / Write-Through"或"失效通知 / Cache Invalidation"。

### 10.5 安全机制
- **零信任代理**：在每个服务前放置小菱形或六边形，标注"mTLS / 身份校验"。
- **数据分级**：在数据节点旁标注标签「L1 公开 / L2 内部 / L3 敏感 / L4 机密」。
- **最小权限**：在连线旁标注"RBAC / 只读权限"或"临时凭证 / STS"。

---

## 11. 注释与辅助元素

### 11.1 注释框（Callout / Note）
- 用于解释关键决策、选型理由、约束条件、性能指标。
- 形状：气泡框或直角矩形，带指向箭头指向目标节点或连线。
- 样式：浅黄填充 `#FFFDE7` + 棕色描边 `#F9A825`，与主图形成区分但不过度突兀。
- 内容格式：「决策：{选择} → 原因：{理由} → 约束：{限制}」。
- 示例：「决策：选用异步消息队列 → 原因：峰值削峰，解耦上下游 → 约束：需保证幂等消费」。

### 11.2 图例（Legend）
- **每张图必须包含图例**，置于右下角或底部居中。
- 图例内容：形状语义示例（小图标+文字）、颜色语义色块、线型语义示例。
- 图例尺寸：占图幅的 5%~10%，不喧宾夺主。

### 11.3 缩略索引 / 图间导航
- 当存在多张图时，总览图（Landscape）中可在黑盒边界旁标注「详见图 2-逻辑视图」。
- 详图标题格式：「{系统名} - {视角}视图（图 N/M）」。

---

## 12. 架构图反模式（Anti-patterns）

Agent 必须自检并避免以下反模式：

| 反模式 | 后果 | 修正方法 |
|--------|------|---------|
| **上帝之图（God Diagram）** | 单图超过 20 个节点，信息过载无法阅读 | 按视角拆分为多张图，总览图只保留黑盒边界和主交互 |
| **形状语义混乱** | 圆柱体被用来画服务，矩形被用来画数据库 | 严格遵守形状语义表，必要时在图例中声明自定义映射 |
| **箭头方向循环** | 出现 A→B→C→A，逻辑矛盾或耦合过高 | 引入消息队列或事件总线打破循环，或拆分时序图说明 |
| **颜色泛滥** | 每个节点颜色都不同，失去分层意义 | 限制调色板为 5~6 个语义色，同层同色，跨层高对比 |
| **连线无标注** | 只有箭头不知道是什么协议或数据格式 | 强制要求关键连线标注「动作+机制」，同层内部可简化 |
| **边界框嵌套过深** | 三层以上虚线框嵌套，视觉破碎 | 最多两层嵌套，更深层级用新图展开或泳道替代 |
| **忽略观测链路** | 图中没有监控、告警、日志、探针 | 必须显式画出至少一条「Watch」虚线或观测节点 |
| **布局与语义矛盾** | 用分层堆叠画网状 P2P 系统，或用树状画流水线 | 根据系统本质选择布局，必要时局部混合 |
| **安全视图缺失** | 生产架构图没有防火墙、边界、加密标识 | 在物理视图或安全视图中强制添加安全边界元素 |
| **动态行为不可见** | 重试、降级、批处理、超时等运行时行为无视觉表达 | 使用回环箭头、红色旁路、时序编号、注释框表达 |

---

## 13. 多图一致性规范

当一套系统需要输出多张图时：

- **命名一致性**：同一组件在不同视角中必须使用**完全相同的名称**和**相同的形状**。
- **颜色一致性**：同一组件在不同视角中必须使用**相同的颜色**。
- **图例复用**：每张图右下角放置统一图例，说明形状、颜色、线型的语义。
- **缩略索引**：总览图（Landscape）中，可对黑盒边界标注「详见图 2-逻辑视图」，建立图间导航。
- **比例一致**：若多张图使用相同的网格/比例尺，确保节点大小在视觉上一致。
- **版本对齐**：多张图应标注同一版本号或日期，避免 viewers 看到不一致的迭代版本。

---

## 14. 场景裁剪指南（Agent 决策表）

Agent 不应每次都套用全部规范，而应根据**场景类型**裁剪子集：

| 场景类型 | 推荐视角 | 推荐布局 | 必用形状 | 可忽略 | 特殊要求 |
|---------|---------|---------|---------|--------|---------|
| 后端微服务系统 | 逻辑 + 运行时 + 部署 | 分层堆叠 + 局部 Hub-Spoke | 矩形、圆柱、椭圆、菱形、六边形 | 人形、时钟 | 必须画出注册中心、网关、配置中心 |
| 前端应用架构 | 逻辑 | 树状层级 | 矩形、六边形 | 圆柱、管道、云形 | 组件边界清晰，props/事件流标注 |
| 数据平台/数仓 | 数据 + 逻辑 | 流水线 + 分层堆叠 | 圆柱、管道、椭圆、文档 | 人形、六边形 | 必须标注数据格式转换、一致性策略 |
| 云原生/K8s 平台 | 部署 + 运行时 | 分层堆叠 + 区域同心 | 矩形、虚线框、云形、六边形 | 人形 | 必须画出控制面与数据面分离 |
| 零信任/安全架构 | 安全 + 逻辑 | 区域同心 | 锯齿框、双线、红色虚线、菱形 | 圆柱、管道 | 必须标注每层的信任等级和穿越协议 |
| CI/CD 工具链 | 逻辑 + 部署 | 流水线 | 矩形、管道、文档、时钟 | 圆柱、人形 | 必须标注触发条件和制品流转 |
| AI 训练/推理平台 | 数据 + 运行时 + 逻辑 | 流水线 + Hub-Spoke | 矩形、圆柱、管道、椭圆、立方体 | 人形 | 必须标注数据版本、模型仓库、资源调度 |
| 物联网/边缘计算 | 部署 + 运行时 + 集成 | Hub-Spoke + 区域同心 | 矩形、云形、时钟、锯齿框 | 树状 | 必须标注边缘-云端协同、离线策略 |
| 区块链/去中心化 | 逻辑 + 安全 | 网状对等 | 矩形、双线、锯齿框 | 分层堆叠 | 必须标注共识机制、加密链路 |
| 事件驱动/EDA | 逻辑 + 运行时 | Hub-Spoke + 分层堆叠 | 椭圆、管道、矩形、菱形 | 圆柱（除非需持久化） | 必须标注事件 Schema、订阅关系、顺序/乱序策略 |
| 多租户 SaaS | 逻辑 + 部署 + 安全 | 分层堆叠 + 纵向虚线带 | 矩形、纵向虚线带、锯齿框 | 人形 | 必须标注租户隔离级别、数据路由策略 |

---

## 15. 多工具适配与降级策略

Agent 加载本 Skill 后，应根据用户指定的工具或场景自动选择输出格式。若目标工具不支持某高级特性，按以下优先级降级：

### 15.1 Excalidraw
- **优势**：手绘风格，适合草图、评审、快速迭代、非正式分享。
- **适配要点**：
  - 使用其内置的 Rectangle、Cylinder、Diamond、Ellipse、Arrow；3D Box 可用组合形状或手绘近似。
  - 开启"Roughness" 0~1 之间保持轻微手绘感；颜色使用自定义 HEX。
  - 虚线框使用 Dashed Rectangle；锯齿框需手绘或导入自定义形状。
- **降级**：不支持锯齿框时，用红色粗虚线矩形替代。
- **导出**：`.excalidraw` JSON、PNG、SVG。

### 15.2 Draw.io (diagrams.net)
- **优势**：专业精确，适合正式文档、可编辑矢量图、打印。
- **适配要点**：
  - 使用"General"、"Software"、"Networking"形状库；严格对齐网格。
  - 利用"Container"实现虚线分组框；利用"Swimlane"实现纵向虚线带。
  - 防火墙/锯齿框使用 Networking 库中的 Firewall 形状。
  - 支持自定义调色板，可一次性导入本 Skill 的 HEX 色值。
- **降级**：几乎无降级需求，最完整的实现目标。
- **导出**：`.drawio`、SVG、PNG、PDF。

### 15.3 Draw.io 轻量源文件工作流
- **优势**：既能保留可编辑源文件，又能稳定导出 PNG/SVG/PDF，适合作为 Git 中长期维护的图资产。
- **适配要点**：
  - 优先保存 `.drawio` 源文件，再导出 PNG/SVG/PDF 给文档阅读者。
  - 用 Container / Swimlane 表示边界与分组；用统一样式表达颜色语义与线型。
  - 复杂布局、异形图元、安全边界、总线/管道形态尽量在同一工具内完成，不因为工具限制而牺牲语义。
- **降级**：
  - 当载体只允许纯文本时，退回 ASCII 草图说明骨架；不要把正式图需求降级成弱语义图元。
- **导出**：`.drawio`、SVG、PNG、PDF。

### 15.4 SVG / HTML
- **优势**：完全可控，适合交互式文档、网页嵌入、动画演示、程序动态生成。
- **适配要点**：
  - 使用 `<rect>`、`<circle>`、`<ellipse>`、`<path>`、`<polygon>`（六边形、菱形）、`<text>` 原生绘制。
  - 锯齿框使用自定义 `<path>` 绘制锯齿边缘；管道使用横向 `<rect>` + 内部流动箭头动画。
  - 通过 CSS 变量定义颜色语义（`--color-compute: #E8F5E9`），确保全局一致。
  - 利用 `<g>` 分组实现边界和整体变换；利用 `<defs>` 定义可复用形状模板。
- **降级**：无降级，SVG 是实现本 Skill 最完整的载体。
- **导出**：`.svg`、嵌入 HTML。

### 15.5 PlantUML
- **优势**：UML 生态完善，适合与代码仓库同步、生成规范文档。
- **适配要点**：
  - 使用 `component` 图或 `deployment` 图；用 `package` 表示边界；用 `database` 表示存储。
  - 用 `skinparam` 定制颜色、字体、线型；用 `rectangle` + `<<stereotype>>` 表达自定义形状语义。
  - 云形使用 `cloud`；人形使用 `actor`；节点使用 `node`。
- **降级**：
  - 不支持六边形原生语法 → 用 `rectangle` + `<<Bounded Context>>` 替代。
  - 不支持复杂填充 → 用单色填充替代渐变。
- **导出**：PNG、SVG、PDF。

### 15.6 工具选择决策
- **快速草图/评审** → Excalidraw
- **正式文档/可编辑交付** → Draw.io
- **Git 中长期维护的图资产** → Draw.io 或 PlantUML
- **网页交互/动态高亮** → SVG/HTML
- **复杂安全网络拓扑** → Draw.io 或 SVG
- **低保真讨论 / 纯文本约束说明** → ASCII 草图或结构化元素清单，正式图再回到 Draw.io / SVG

---

## 16. 绘图流程 Checklist（Agent 执行步骤）

在每次绘制架构图前，Agent 必须按以下步骤自检：

1. **【场景识别】** 这是什么类型的系统？（后端/前端/数据/云原生/安全/AI/IoT/区块链...）
2. **【视角选择】** 这张图要回答什么问题？选择了哪个视角？是否只聚焦 1~2 个视角？
3. **【布局选择】** 根据系统本质选择了哪种主布局？是否需要局部混合？
4. **【分层/分区确认】** 是否明确了逻辑层或安全域？每层/每域是否有代表性节点？
5. **【形状确认】** 每个节点是否使用了符合其抽象角色的标准形状？（参考形状语义表）
6. **【颜色确认】** 同层/同域节点颜色是否一致？跨层/跨域颜色是否有明确区分？是否通过灰度自检？
7. **【连线确认】** 同步/异步/控制/事件是否使用了正确的线型？关键连线是否标注了动作与协议？
8. **【边界确认】** 相关节点是否被适当的虚线框分组？边界标题是否清晰？嵌套是否不超过两层？
9. **【命名确认】** 所有节点是否使用"角色+类型"命名，无动词开头？缩写是否标注全称？
10. **【密度确认】** 单图节点是否超过 20 个？是否需要拆分为总览+子图？
11. **【稳定确认】** 是否通过并列实例、虚线框隔离、观测连线、降级路径表达了稳定性设计？
12. **【安全确认】** 若是生产架构，是否画出了安全边界、防火墙、加密通道或身份源？
13. **【动态确认】** 重试、降级、批处理、并行、时序是否通过线条粗细、回环箭头、编号表达？
14. **【工具确认】** 是否根据输出场景选择了合适的工具？不支持的功能是否按降级策略处理？
15. **【受众确认】** 图中信息是否足够回答"技术栈选型、项目结构、协作链路、稳定性保障"四个问题？
16. **【图例确认】** 是否包含图例？图例是否覆盖了本图使用的所有形状、颜色、线型？

---

## 17. 抽象示例框架（空白模板，供 Agent 填充）

以下为一个完全抽象的系统架构图文本骨架，Agent 应根据实际场景、视角、布局选择对应部分填充：

```
[图表标题: {系统名称} - {视角}视图]
[视角标签: {逻辑视图 | 部署视图 | 数据视图 | 运行时视图 | 安全视图 | 集成视图 | 全景总览}]

=== 若使用分层堆叠布局 ===

+-------------------------------------------------------------+
|  接入/交互层  [颜色: 浅蓝]  [形状: 菱形/矩形/六边形]          |
|  +--------------+  +--------------+  +--------------+       |
|  |  入口网关     |  |  管理控制台   |  |  API 暴露面   |       |
|  +------+-------+  +------+-------+  +------+-------+       |
+--------+-----------------+-----------------+----------------+
         | 同步调用        | 配置下发        | 请求转发
         v                 v                 v
+-------------------------------------------------------------+
|  控制/治理层  [颜色: 浅橙]  [形状: 矩形/椭圆/立方体]          |
|  +--------------+  +--------------+  +--------------+     |
|  |  任务调度器   |  |  流程/规则引擎|  |  配置中心     |     |
|  +------+-------+  +------+-------+  +------+-------+     |
+--------+-----------------+-----------------+-------------+
         | 任务分发        | 状态流转        | 订阅变更
         v                 v                 v
+-------------------------------------------------------------+
|  执行/计算层  [颜色: 浅绿]  [形状: 矩形/立方体]               |
|  +----------------------------------------------+          |
|  |  执行引擎边界 [虚线框]                        |          |
|  |  +--------+ +--------+ +--------+            |          |
|  |  |执行器A | |执行器B | |执行器C | ...        |          |
|  |  +----+---+ +----+---+ +----+---+            |          |
|  |       | 并行处理 |        | 批量提交          |          |
|  +-------+----------+--------+---------------+          |
+---------+----------+--------+----------------------------+
          |          |        |
          v          v        v
+-------------------------------------------------------------+
|  数据/资源层  [颜色: 浅紫]  [形状: 圆柱/椭圆/管道]            |
|  +--------------+  +--------------+  +--------------+     |
|  |  持久化存储   |  |  高速缓存     |  |  文件/对象存储|     |
|  +--------------+  +--------------+  +--------------+     |
+-------------------------------------------------------------+

侧边/底部基础设施层 [颜色: 浅灰蓝]:
  +--------------+      +--------------+
  |  监控/链路追踪 |<-----|  告警/通知中心 |
  +--------------+      +--------------+

=== 若使用流水线布局 ===

[触发器/时钟] ---> [阶段1: 采集/构建] ---> [阶段2: 转换/处理] ---> [阶段3: 验证/测试] ---> [阶段4: 部署/发布]
                      | 并行度 N          | 批处理窗口        | 策略检查
                      v                   v                 v
                   [执行器x3]          [执行器x2]        [执行器x1]

=== 若使用区域同心布局 ===

+----------------------------------------+  <-- 外部/不可信域 [浅黄]
|  +--------------------------------+    |
|  |  +------------------------+   |    |  <-- DMZ/边缘域 [浅橙]
|  |  |  +----------------+   |   |    |
|  |  |  |                |   |   |    |  <-- 核心域 [浅蓝/浅绿]
|  |  |  |   核心系统      |   |   |    |
|  |  |  |                |   |   |    |
|  |  |  +----------------+   |   |    |
|  |  |      [锯齿框防火墙]      |   |    |
|  |  +------------------------+   |    |
|  |         [锯齿框防火墙]          |    |
|  +--------------------------------+    |
|            [锯齿框防火墙]               |
+----------------------------------------+

=== 通用图例（右下角） ===
[矩形] = 服务/进程  [圆柱] = 存储  [椭圆] = 缓存/队列  [菱形] = 网关/决策
[实线箭头] = 同步调用  [虚线箭头] = 异步事件  [红色虚线] = 降级/安全穿越
```

---

## 18. 备注

- **本 Skill 的定位是"视觉语法"而非"业务模板"**。Agent 在理解业务架构后，应先用本规范在脑中（或文本描述中）构建"标准架构模型"，再映射到具体工具的语法。
- **面对不同受众时，可调整信息密度**：
  - 给 CTO/PM/业务方看时：突出分层、选型理由、外部依赖、成本结构。
  - 给研发工程师看时：增加协议、线程模型、数据格式、接口契约、错误处理策略。
  - 给运维/SRE 看时：增加部署边界、监控探针、故障域、扩缩容策略、回滚路径。
  - 给安全/合规看时：突出信任边界、数据分级、审计点、加密链路、准入控制。
- **颜色值仅为推荐**，Agent 可根据企业 VI 或用户偏好替换，但必须保持"同层同色系、跨层高对比"的原则，且通过灰度自检。
- **本 Skill 应随工具演进更新**：当 Excalidraw、Draw.io、SVG/HTML 等主力工具新增原生形状、布局或样式能力时，应及时更新映射表，降低手工降级频率。
- **禁止在 Skill 中植入具体技术栈偏好**（如"必须使用 Kubernetes"或"推荐 Redis"）。技术选型应由业务场景决定，Skill 只负责"如何画出选型结果"。