name: arch-view description: 当用户要求“生成架构视图”、“显示服务依赖图”、“映射请求流”、“显示事件拓扑”、“按域分组服务”、“可视化架构”或提及跨仓库架构分析、服务映射或架构可视化时，应使用此技能。 version: 1.0.0

架构视图

通过使用并行子代理聚合所有仓库的 catalog-info.yaml 元数据，生成跨仓库的架构视图。

目的

创建可视化的架构表示（Mermaid 图表、Markdown 表格），展示服务如何组合在一起、请求如何流经网关、事件如何传播以及服务如何按域/团队分组。

何时使用

在以下情况触发此技能：

用户要求“显示服务依赖图”或“映射架构”
用户想了解“服务如何连接”
用户询问“请求流”或“事件拓扑”
用户想“按域/团队分组服务”
用户提及“跨仓库架构”或“系统架构”

工作流程

阶段 1：发现仓库

查找要分析的所有仓库：

检查 repos/ 目录 - 本地克隆的仓库
可选地从 GitHub 获取 - 使用 gh repo list Astrabit-CPT 获取完整列表
过滤活跃仓库 - 跳过已归档或模板仓库

阶段 2：并行元数据收集

使用子代理并行读取每个仓库的 catalog-info.yaml：

对于每个仓库：
  启动子代理，指令为：“从 [repo_path] 读取 catalog-info.yaml 并返回解析后的内容”

并行处理策略：

同时启动 5-10 个子代理
收集所有结果
优雅处理缺失的元数据（跳过或标记为缺失）

阶段 3：聚合并构建模型

将所有元数据组合成统一模型：

aggregated = {
    "components": {},  # 名称 -> 目录信息
    "dependencies": set(),  # (来源，目标) 元组
    "gateways": [],
    "services": [],
    "workers": [],
    "domains": {},  # 域 -> [组件]
    "events": {
        "producers": {},  # 主题 -> [生产者]
        "consumers": {},  # 主题 -> [消费者]
    },
    "routes": [],  # 网关路由
}

阶段 4：生成请求的视图

根据用户请求，生成相应的视图：

视图	命令/触发词	输出
服务依赖图	“dependency graph”, “show dependencies”	Mermaid 图
请求流映射	“request flows”, “how requests flow”	Mermaid 流程图
事件拓扑	“event topology”, “event map”	Mermaid 图
服务分组	“group services”, “services by domain”	Markdown 表格
完整架构	“architecture view”, “full architecture”	所有视图组合

视图模板

服务依赖图

graph TD
    Gateway[api-gateway<br/>类型: 网关] --> Auth[auth-service<br/>类型: 服务]
    Gateway --> Users[user-service<br/>类型: 服务]
    Gateway --> Orders[order-service<br/>类型: 服务]
    Users --> DB[(user-db<br/>类型: 数据库)]
    Auth --> Redis[(redis<br/>类型: 缓存)]
    Orders --> OrdersDB[(order-db<br/>类型: 数据库)]
    Orders --> Worker[order-processor<br/>类型: 工作器]

生成逻辑：

节点：来自 catalog-info.yaml 的所有组件
边：来自 dependsOn 关系
形状：数据库节点使用 [(名称)]，其他使用 [名称]
标签：包含 名称 和 类型

请求流映射

flowchart LR
    Client[客户端] --> Gateway[api-gateway]
    Gateway -->|/api/users/*| Users[user-service]
    Gateway -->|/api/auth/*| Auth[auth-service]
    Gateway -->|/api/orders/*| Orders[order-service]
    Users --> DB[(user-db)]
    Auth --> Redis[(redis)]

生成逻辑：

从网关组件（类型：网关）开始
通过 routes 查找下游服务
将路由路径作为边标签
跟踪服务对数据库的依赖

事件拓扑

graph LR
    Orders[order-service] -->|order.placed| Kafka1[Kafka: order-placed]
    Orders -->|order.cancelled| Kafka2[Kafka: order-cancelled]
    Kafka1 --> User[user-service]
    Kafka1 --> Notif[notification-service]
    Kafka2 --> User
    Worker[order-processor] -->|order.processed| Kafka3[Kafka: order-processed]
    Kafka1 --> Worker

生成逻辑：

节点：服务（来自 eventProducers）和 Kafka 主题（来自 topic 字段）
边：生产者 → 主题，主题 → 消费者
标签：边上的主题名称

服务分组

按域分组：

域	服务	所有者
trading	order-service, trade-service, order-processor	trading-team
platform	api-gateway, user-service, auth-service	platform-team
shared	shared-utils, shared-types	platform-team

按类型分组：

类型	服务
gateway	api-gateway
service	user-service, auth-service, order-service
worker	order-processor, notification-worker
library	shared-utils, shared-types

生成逻辑：

按 spec.domain 字段分组
显示每个域的所有者
统计每个分组的服务数量

脚本

aggregate-metadata.py

从仓库收集所有 catalog-info.yaml 文件：

# 从 repos 目录聚合
python skills/arch-view/scripts/aggregate-metadata.py repos/

# 输出为 JSON
python skills/arch-view/scripts/aggregate-metadata.py repos/ --format json

# 输出摘要
python skills/arch-view/scripts/aggregate-metadata.py repos/ --summary

generate-mermaid.py

将聚合的元数据转换为 Mermaid 图表：

# 生成所有视图
python skills/arch-view/scripts/generate-mermaid.py aggregated.json

# 生成特定视图
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view dependency
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view request-flow
python skills/arch-view/scripts/generate-mermaid.py aggregated.json --view events

使用子代理

启动子代理并行读取元数据：

为提高效率，同时启动多个子代理：

子代理 1: "读取 repos/api-gateway/catalog-info.yaml 并返回解析后的 YAML"
子代理 2: "读取 repos/user-service/catalog-info.yaml 并返回解析后的 YAML"
子代理 3: "读取 repos/order-service/catalog-info.yaml 并返回解析后的 YAML"
... (对所有仓库继续)

收集结果并聚合。

提示： 限制为 5-10 个并发子代理，以免使系统过载。

输出格式

将结果呈现为：

摘要 - 发现内容的快速概览
可视化图表 - 在支持的查看器中渲染的 Mermaid 图
表格 - 分组和列表
缺失的元数据 - 缺少 catalog-info.yaml 的仓库列表

示例输出结构

# 架构视图

## 摘要
- 总仓库数：15
- 具有元数据的组件：12
- 缺失元数据：3
- 网关：1
- 服务：8
- 工作器：2
- 库：1

## 服务依赖图
[Mermaid 图表]

## 请求流映射
[Mermaid 图表]

## 事件拓扑
[Mermaid 图表]

## 服务分组
[Markdown 表格]

## 缺失的元数据
以下仓库缺少 catalog-info.yaml：
- repo-a
- repo-b
- repo-c

架构视图生成器Skill arch-view

架构视图

目的

何时使用

工作流程

阶段 1：发现仓库

阶段 2：并行元数据收集

阶段 3：聚合并构建模型

阶段 4：生成请求的视图

视图模板

服务依赖图

请求流映射

事件拓扑

服务分组

脚本

aggregate-metadata.py

generate-mermaid.py

使用子代理

输出格式

示例输出结构

附加资源

参考文件

脚本