name: repo-metadata description: 当用户要求“生成仓库元数据”、“创建catalog-info.yaml”、“添加仓库元数据”、“记录仓库结构”或提及为服务目录或架构文档生成结构化元数据时，应使用此技能。 version: 1.0.0
仓库元数据
使用行业标准约定（基于Backstage目录格式）为仓库生成结构化的catalog-info.yaml元数据。此元数据支持跨仓库的架构分析和服务目录功能。
目的
创建和维护描述仓库在更广泛架构中角色的catalog-info.yaml文件。此元数据用于整个组织的架构视图、依赖关系图和服务分组。
何时使用
在以下情况触发此技能：
- 用户要求“生成仓库元数据”或“创建catalog-info.yaml”
- 用户希望为服务目录记录仓库
- 用户需要为跨仓库架构分析准备仓库
- 用户提及“服务目录”或“组件元数据”
元数据模式
catalog-info.yaml文件遵循Backstage约定，并包含Astrabit特定的扩展：
apiVersion: astrabit.io/v1
kind: Component
metadata:
name: service-name # 必填：唯一标识符
description: 简要描述
tags:
- backend
- user-management
spec:
# 服务分类
type: service # 必填：service, gateway, worker, library, frontend, database
category: backend # 更广泛的类别
domain: trading # 业务领域
owner: platform-team # 负责团队
# 依赖项（上游）
dependsOn:
- component: auth-service
type: service
- component: user-db
type: database
# 提供的API
providesApis:
- name: User API
type: REST
definition: ./openapi.yaml
# 消费的API
consumesApis:
- name: Auth API
providedBy: auth-service
# 产生的事件
eventProducers:
- name: user-events
type: kafka
topic: user.created
schema: avro
# 消费的事件
eventConsumers:
- name: order-events
type: kafka
topic: order.placed
group: user-service-group
# HTTP路由（用于网关/服务）
routes:
- path: /api/users/*
methods: [GET, POST, PUT, DELETE]
handler: this
- path: /api/auth/*
methods: [POST]
forwardsTo: auth-service
# 基础设施
runtime: nodejs # nodejs, python, go, java等
framework: nestjs # nestjs, fastapi, spring等
生成工作流
阶段1：分析仓库
收集有关仓库的信息：
-
使用现有分析脚本：
python skills/repo-docs/scripts/analyze-repo-structure.py /path/to/repo python skills/repo-docs/scripts/find-integration-points.py /path/to/repo -
阅读现有文档：
- 检查
INTEGRATIONS.md- 包含上游/下游关系 - 检查
ARCHITECTURE.md- 包含服务角色和依赖项 - 检查
README.md- 包含基本描述和技术栈
- 检查
-
从代码中检测：
- 从文件扩展名和包文件中检测语言
- 从依赖项中检测框架
- 从导入模式中检测集成点
阶段2：生成元数据
基于分析，使用检测到的值生成catalog-info.yaml：
| 字段 | 检测方法 |
|---|---|
name |
仓库名称或package.json中的name字段 |
description |
README标题/描述或从代码生成 |
type |
从代码模式推断（网关有路由，工作者只有消费者） |
runtime |
从包文件（package.json，pyproject.toml，go.mod） |
framework |
从依赖项（nestjs，fastapi，spring-boot等） |
dependsOn |
从集成点扫描 |
eventProducers |
从kafka.producer或类似模式 |
eventConsumers |
从@KafkaListener，@EventListener或类似模式 |
routes |
从@Controller，@GetMapping，路由器定义 |
阶段3：呈现和优化
以表格格式向用户呈现生成的元数据：
生成的catalog-info.yaml：
| 字段 | 值 | 来源 |
|-------|-------|--------|
| name | user-service | 仓库名称 |
| type | service | 检测到：有路由和消费者 |
| runtime | nodejs | package.json |
| framework | nestjs | 依赖项 |
| domain | unknown | ❌ 需要输入 |
| owner | unknown | ❌ 需要输入 |
| dependsOn | auth-service, user-db | 集成扫描 |
提示用户查看并填写缺失的字段（标记为❌）。
阶段4：写入元数据文件
将catalog-info.yaml写入仓库根目录。
阶段5：更新相关文档
提供更新相关文档以引用新元数据文件：
- 在
README.md中添加指向catalog-info.yaml的链接 - 更新
INTEGRATIONS.md以与元数据保持一致
服务类型检测
| 类型 | 指标 |
|---|---|
| gateway | 有routes且包含forwardsTo，处理外部请求，业务逻辑最少 |
| service | 同时有providesApis和consumesApis，有业务逻辑 |
| worker | 只有eventConsumers，没有HTTP路由，后台处理 |
| library | 不消费API，只提供API，共享工具 |
| frontend | package.json中有type: frontend，有构建产物 |
| database | 包含迁移、模式，没有应用代码 |
脚本使用
使用scripts/generate-metadata.py自动化元数据生成：
# 从当前目录生成
python skills/repo-metadata/scripts/generate-metadata.py
# 从特定仓库生成
python skills/repo-metadata/scripts/generate-metadata.py /path/to/repo
# 以JSON格式输出以供检查
python skills/repo-metadata/scripts/generate-metadata.py --format json
脚本功能：
- 运行仓库结构分析
- 扫描集成点
- 读取现有文档
- 输出
catalog-info.yaml内容
附加资源
参考文件
references/schema.md- 完整的catalog-info.yaml模式参考references/detection-patterns.md- 检测服务特征的模式
示例模板
examples/catalog-info-template.yaml- 包含所有字段的完整模板examples/catalog-info-gateway.yaml- 网关服务示例examples/catalog-info-worker.yaml- 工作者服务示例examples/catalog-info-library.yaml- 共享库示例
质量检查清单
在最终确定元数据之前，请验证：
- [ ]
name在整个组织中唯一 - [ ]
type正确分类服务 - [ ]
domain和owner已填写（非自动检测） - [ ]
dependsOn列出所有上游依赖项 - [ ]
eventProducers和eventConsumers完整 - [ ] 如果这是网关/服务，则路由已记录
- [ ] 文件是有效的YAML
- [ ] 文件位于仓库根目录（
catalog-info.yaml）