architecture-diagrams

架构图技能

目标

将基础设施源文件或声明的 DS_CATALOG_V1 数据模型转换为易于阅读的架构图，用于评审、ADR 和设计讨论。保留调用方选择的输出格式以及源的权威边界。

基础设施输入包括 Terraform、Bicep、ARM 模板、shell 脚本、Kubernetes 清单以及 Docker 或 Compose 文件。目录输入使用 data-catalog（持久化数据目录技能）中声明的实体和关系。它不会从 SQL 或 ORM 文件推断数据模型。

此技能用于记录基础设施拓扑和数据模型。若要记录软件系统，即其容器、组件，以及周围的人员和系统，请改用 c4-architecture 技能。

成功标准

• 图中仅包含已确认的源范围。
• 基础设施源保留现有的解析和关系处理行为。
• 目录图保留已声明的实体 ID、端点、基数、端点最小值、联接键、置信度和证据依据，不得臆造关系。
• ASCII 或 Mermaid 输出由调用方偏好决定。
• 推断和假设的目录关系与已确认的关系在视觉上保持明显区别。

限制

• 将图视为源权威信息的视图，而非其自身的语义权威。
• 阅读 catalog-erd.md，了解 DS_CATALOG_V1 输入、多重性映射、置信度呈现、目录输出约定以及 Functional Planner 兼容边界。
• 不得将 SQL DDL、Prisma、SQLAlchemy 或其他 ORM 解析为目录输入。
• 不得为目录联接键呈现主键、外键或唯一性标记；目录声明的是字段名称，而非数据库键角色。
• 可行性研究互操作配置文件和下游需求映射应保留在各自所属的工作流中。

停止规则

• 基础设施边界不明确时，停止并询问范围。
• 遇到不支持的目录版本、未解析的端点、未知基数、缺失或无效的端点最小值、未知置信度值或格式错误的联接键声明时，停止并报告，不得猜测或部分呈现。
• 无法确定输出偏好时，在生成图表前停止。

输出格式

此技能可生成 ASCII 块图或 Mermaid 图。两者都不是默认格式：调用方或周围上下文会为每张图选择输出格式。如果调用方未说明偏好，请在生成前询问想要哪种格式。

图表类型取决于源类型。基础设施源使用 ASCII 约定或 Mermaid 约定，呈现为 ASCII 块图或 Mermaid 流程图。目录源则按照 catalog-erd.md 呈现为 ASCII 实体行或 Mermaid erDiagram。无论哪种情况，不同格式中的结构、边界和关系都必须保持一致。

偏好约定

架构图格式选择不限于 ADR。独立使用时，请查阅根状态文件 .copilot-tracking/architecture-diagrams/state.json。如果该文件不存在，请在选定格式时创建。

{
  "userPreferences": {
    "diagramFormat": "mermaid"
  },
  "repoVisibility": "private"
}

userPreferences.diagramFormat 的值必须为 ascii 或 mermaid。repoVisibility 字段为可选字段，在周围工作流需要区分公共和私有仓库时可使用。解析顺序如下：

1. 明确请求或调用方状态。
2. 根状态文件 .copilot-tracking/architecture-diagrams/state.json。
3. 如果独立请求未提供偏好，请询问一次，并将答案保存到根状态文件，以便日后复用。

工作流

绘制图表时，请遵循以下顺序：

1. 发现。确定相关基础设施文件或声明的目录，以及架构范围。如果范围不明确，请询问应包含哪些文件夹、服务或实体。
2. 解析。对于基础设施，提取服务、数据存储、网络组件、入口点和部署单元。对于目录，执行 scripts/render_catalog_erd.py，或遵循 catalog-erd.md，不得添加推断出的语义。
3. 关系映射。对于基础设施，按正确方向连接组件。对于目录，保留精确声明的端点、基数、端点最小值、连接键、置信度和依据。
4. 生成。按照调用方选择的格式渲染最终图表，清晰标示边界或实体，并附上简洁的图例。

ASCII 约定

使用一致的方框表示法和对齐方式：

+------------------+      +------------------+
|   Service Name   |----->|   Service Name   |
+------------------+      +------------------+

为提高可读性，请遵循以下约定：

• 方框标签应简短具体。
• 箭头应对齐，并尽可能每行只表示一种关系。
• 使用清晰命名的边界，避免过于繁杂的装饰。
• 对类似组件使用相同的方框形状。

箭头类型

箭头	含义
---->	数据流或依赖
<--->	双向连接
- - >	可选或有条件的资源

分组与边界

当相关组件共享网络、账户或部署域时，将它们分组到更大的边界内。

强边界使用完整方框：

+-----------------------------------------------+
|  Resource Group                               |
|                                               |
|  +-------------+        +-------------+       |
|  |   VNet      |------->|   Subnet    |       |
|  +-------------+        +-------------+       |
|                                               |
+-----------------------------------------------+

次级或嵌套边界使用带标签的边界：

:--- Virtual Network ---------------------------:
:                                               :
:  +-------------+        +-------------+       :
:  |   Subnet A  |------->|   Subnet B  |       :
:  +-------------+        +-------------+       :
:                                               :
:-----------------------------------------------:

Mermaid 约定

调用方选择 Mermaid 输出时，请使用 flowchart 绘制结构、边界和关系与 ASCII 图相同的 mermaid 围栏代码块。

• 对于自上而下的拓扑，使用 flowchart TB；当主要流程从左向右时，使用 flowchart LR。
• 将每个组件声明为带有简短具体标签的节点，例如 lb["Load Balancer"]；数据存储使用 [("...")]。
• 将共享网络、账户或部署域的组件放在 subgraph 块内，例如 VNet、子网或资源组。
• 使用 --> 表示数据流或依赖，使用 <--> 表示双向连接，使用 -. optional .-> 表示可选或有条件的连接。
• 节点标识符应保持稳定且使用小写；标签仅用于人类可读的名称。

flowchart TB
    subgraph rg["Resource Group"]
        lb["Load Balancer"]
        subgraph subnet["App Subnet"]
            vm1["VM 1"]
            vm2["VM 2"]
        end
        db[("SQL Database")]
    end
    lb --> vm1
    lb --> vm2
    vm1 --> db
    vm2 --> db

布局指南

• 将外部或公共服务放在顶部。
• 将计算层或应用层放在中间。
• 将数据存储放在底部。
• 按网络边界（例如 VNet 或子网）对组件分组。
• 当方向明确时，让主要流程从上到下。

资源识别启发式规则

读取基础设施来源时，请提取：

• 资源类型和名称
• 网络关联，包括 VNet、子网、专用终结点或入口设置
• 配置中显式声明的依赖项，以及通过引用隐含的依赖项
• 部署关系，例如容器注册表、服务网格或工作负载放置

输出格式约定

每个基础设施图都使用以下结构：

## <Name> Architecture

[diagram in the selected format]

### Legend
[Arrow meanings from this diagram; reference the arrow types above]

### Key Relationships
[Notable connections and dependencies]

标题应使用标题式大小写，并遵循 <Name> Architecture 模式。图例应解释任何特殊符号，“关键关系”部分应聚焦于最重要的依赖项或数据流。

目录图使用 catalog-erd.md 中定义的对应 ## <Engagement> Data Model 约定；图例应说明多重性和置信度，“关键关系”部分应包含每个已声明关系及其依据。

示例：AKS 平台架构

## AKS Platform Architecture

+===============================================================+
|  Resource Group                                               |
|  :--- Virtual Network ------------------------------------:   |
|  :  +------------------+        +------------------+      :   |
|  :  |   NAT Gateway    |------->|   AKS Cluster    |      :   |
|  :  +------------------+        +--------+---------+      :   |
|  :                              +--------v---------+      :   |
|  :                              |       ACR        |      :   |
| :                              +------------------+      : |
|:----------------------------------------------------------:|
|      +------------------+        +------------------+      |
|     | Log Analytics    |<-------|  App Insights    |          |
|     +------------------+        +------------------+          |
+===============================================================+

### Legend
See the arrow types above. Additional symbols: `====` primary boundary, `:---:` secondary boundary.

### Key Relationships
* AKS pulls images from ACR through the network boundary.
* NAT Gateway provides egress for AKS workloads.

相同架构的 Mermaid 表示形式具有相同的结构、边界和关系：

## AKS Platform Architecture

```mermaid
flowchart TB
    subgraph rg["Resource Group"]
        subgraph vnet["Virtual Network"]
            nat["NAT Gateway"]
            aks["AKS Cluster"]
            acr["ACR"]
        end
        appinsights["App Insights"]
        logs[("Log Analytics")]
    end
    nat --> aks
    aks --> acr
    appinsights --> logs
```

### Legend
See the arrow types above; `subgraph` blocks denote network or resource boundaries.

### Key Relationships
* AKS pulls images from ACR through the network boundary.
* NAT Gateway provides egress for AKS workloads.

编写指南

• 如果架构范围不明确，请提出一两个澄清问题。
• 从发现阶段进入解析或生成阶段时，请说明当前工作流阶段。
• 定稿前，请展示一份草图，并简要总结其中包含的资源。
• 如果重要的推断决策会影响图表（例如隐式依赖），请注明。
• 将图表视为基础设施来源的静态表示，而非运行时执行视图。
• 将输出聚焦于单一架构范围，以确保内容清晰易读。