Agent-Skills.md

Agent Skills: Store 研发商店模块架构指南

Store 研发商店模块架构指南，涵盖插件/模板/镜像管理、版本发布、审核流程、商店市场、扩展点机制。当用户开发研发商店功能、发布插件、管理模板或实现扩展点时使用。

UncategorizedID: tencentblueking/bk-ci/store-module-architecture

Repository

tencentblueking/bk-ci
TencentBlueKingLicense: NOASSERTION
2,498520

Install this agent skill to your local

pnpm dlx add-skill https://github.com/TencentBlueKing/bk-ci/tree/HEAD/ai/skills/store-module-architecture

Skill Files

Browse the full folder contents for store-module-architecture.

Download Skill

Loading file tree…

ai/skills/store-module-architecture/SKILL.md

Skill Metadata

Name
store-module-architecture
Description
Store 研发商店模块架构指南，涵盖插件/模板/镜像管理、版本发布、审核流程、商店市场、扩展点机制。当用户开发研发商店功能、发布插件、管理模板或实现扩展点时使用。

Store 研发商店模块架构指南

模块定位: Store 是 BK-CI 的研发商店模块，负责管理流水线插件（Atom）、流水线模板（Template）、容器镜像（Image）等可复用组件的发布、审核、安装、统计等全生命周期管理。

一、模块整体结构

1.1 子模块划分

src/backend/ci/core/store/
├── api-store/               # API 接口定义层
│   └── src/main/kotlin/com/tencent/devops/store/
│       ├── api/
│       │   ├── atom/            # 插件相关接口（25+ 文件）
│       │   ├── common/          # 通用接口（40+ 文件）
│       │   ├── container/       # 容器相关接口
│       │   ├── image/           # 镜像相关接口
│       │   └── template/        # 模板相关接口
│       ├── constant/            # 常量和消息码
│       └── pojo/                # 数据对象（100+ 文件）
│           ├── app/             # 应用相关
│           ├── atom/            # 插件相关
│           ├── common/          # 通用对象
│           ├── image/           # 镜像相关
│           └── template/        # 模板相关
│
├── biz-store/               # 业务逻辑层
│   └── src/main/kotlin/com/tencent/devops/store/
│       ├── atom/                # 插件业务
│       │   ├── dao/             # 插件数据访问
│       │   ├── factory/         # 工厂类
│       │   ├── resources/       # API 实现
│       │   └── service/         # 插件服务
│       ├── common/              # 通用业务
│       │   ├── dao/             # 通用数据访问（60+ 文件）
│       │   ├── handler/         # 处理器链
│       │   ├── resources/       # API 实现
│       │   └── service/         # 通用服务
│       ├── image/               # 镜像业务
│       └── template/            # 模板业务
│
├── model-store/             # 数据模型层（JOOQ 生成）
└── boot-store/              # Spring Boot 启动模块

1.2 Store 组件类型

| 类型 | 枚举值 | 说明 | 核心表 | |------|--------|------|--------| | 插件（Atom） | ATOM | 流水线可执行插件 | T_ATOM | | 模板（Template） | TEMPLATE | 流水线模板 | T_TEMPLATE | | 镜像（Image） | IMAGE | 容器构建镜像 | T_IMAGE |

二、核心概念

2.1 插件（Atom）模型

┌─────────────────────────────────────────────────────────────────────────┐
│                         插件模型                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      T_ATOM（插件主表）                           │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │  ATOM_CODE  │  │    NAME     │  │   VERSION   │              │   │
│  │  │ (插件标识)   │  │ (插件名称)   │  │ (版本号)     │              │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │   │
│  │  │ ATOM_STATUS │  │ CLASS_TYPE  │  │ LATEST_FLAG │              │   │
│  │  │ (插件状态)   │  │ (插件大类)   │  │ (最新版本)   │              │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│         ┌────────────────────┼────────────────────┐                     │
│         ▼                    ▼                    ▼                     │
│  ┌───────────────┐   ┌───────────────┐   ┌───────────────┐             │
│  │ T_ATOM_ENV_   │   │ T_ATOM_       │   │ T_ATOM_       │             │
│  │     INFO      │   │   FEATURE     │   │ VERSION_LOG   │             │
│  │ (执行环境信息) │   │ (特性配置)    │   │ (版本日志)     │             │
│  └───────────────┘   └───────────────┘   └───────────────┘             │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

2.2 插件核心字段

| 字段 | 类型 | 说明 | |------|------|------| | ID | String | 插件版本 ID（UUID） | | ATOM_CODE | String | 插件唯一标识（不变） | | NAME | String | 插件名称 | | VERSION | String | 版本号（如 1.0.0） | | ATOM_STATUS | Int | 插件状态 | | CLASS_TYPE | String | 插件大类（marketBuild 等） | | JOB_TYPE | String | 适用 Job 类型（AGENT/AGENT_LESS） | | OS | String | 支持的操作系统 | | CLASSIFY_ID | String | 分类 ID | | LATEST_FLAG | Boolean | 是否最新版本 | | DEFAULT_FLAG | Boolean | 是否默认插件 | | PUBLISHER | String | 发布者 | | REPOSITORY_HASH_ID | String | 代码库 HashId |

2.3 插件状态流转

enum class AtomStatusEnum(val status: Int) {
    INIT(0),              // 初始化
    COMMITTING(1),        // 提交中
    BUILDING(2),          // 构建中
    BUILD_FAIL(3),        // 构建失败
    TESTING(4),           // 测试中
    AUDITING(5),          // 审核中
    AUDIT_REJECT(6),      // 审核驳回
    RELEASED(7),          // 已发布
    GROUNDING_SUSPENSION(8), // 上架中止
    UNDERCARRIAGING(9),   // 下架中
    UNDERCARRIAGED(10),   // 已下架
}

┌─────────────────────────────────────────────────────────────────┐
│                     插件状态流转图                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  INIT ──► COMMITTING ──► BUILDING ──► TESTING ──► AUDITING     │
│                              │                        │          │
│                              ▼                        ▼          │
│                         BUILD_FAIL              AUDIT_REJECT     │
│                                                       │          │
│                                                       ▼          │
│                                                   RELEASED       │
│                                                       │          │
│                                                       ▼          │
│                                              UNDERCARRIAGING     │
│                                                       │          │
│                                                       ▼          │
│                                              UNDERCARRIAGED      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2.4 插件分类

// 插件大类
enum class AtomTypeEnum(val type: Int) {
    SELF_DEVELOPED(0),    // 自研
    THIRD_PARTY(1),       // 第三方
}

// Job 类型
enum class JobTypeEnum(val type: String) {
    AGENT("AGENT"),           // 有构建环境
    AGENT_LESS("AGENT_LESS"), // 无构建环境
}

三、核心数据库表

3.1 插件相关表

| 表名 | 说明 | 核心字段 | |------|------|----------| | T_ATOM | 插件主表 | ATOM_CODE, NAME, VERSION, ATOM_STATUS, LATEST_FLAG | | T_ATOM_ENV_INFO | 插件执行环境 | ATOM_ID, PKG_PATH, LANGUAGE, TARGET | | T_ATOM_FEATURE | 插件特性 | ATOM_CODE, VISIBILITY_LEVEL, YAML_FLAG, QUALITY_FLAG | | T_ATOM_BUILD_INFO | 插件构建信息 | LANGUAGE, SCRIPT, SAMPLE_PROJECT_PATH | | T_ATOM_VERSION_LOG | 版本日志 | ATOM_ID, RELEASE_TYPE, CONTENT | | T_ATOM_LABEL_REL | 插件标签关联 | ATOM_ID, LABEL_ID | | T_ATOM_OFFLINE | 插件下架记录 | ATOM_CODE, EXPIRE_TIME, STATUS |

3.2 模板相关表

| 表名 | 说明 | 核心字段 | |------|------|----------| | T_TEMPLATE | 模板主表 | TEMPLATE_CODE, TEMPLATE_NAME, VERSION, TEMPLATE_STATUS | | T_TEMPLATE_CATEGORY_REL | 模板分类关联 | TEMPLATE_ID, CATEGORY_ID | | T_TEMPLATE_LABEL_REL | 模板标签关联 | TEMPLATE_ID, LABEL_ID |

3.3 镜像相关表

| 表名 | 说明 | 核心字段 | |------|------|----------| | T_IMAGE | 镜像主表 | IMAGE_CODE, IMAGE_NAME, VERSION, IMAGE_STATUS | | T_IMAGE_CATEGORY_REL | 镜像分类关联 | IMAGE_ID, CATEGORY_ID | | T_IMAGE_LABEL_REL | 镜像标签关联 | IMAGE_ID, LABEL_ID |

3.4 通用表

| 表名 | 说明 | |------|------| | T_CLASSIFY | 分类表 | | T_CATEGORY | 范畴表 | | T_LABEL | 标签表 | | T_STORE_MEMBER | 组件成员表 | | T_STORE_PROJECT_REL | 组件项目关联表 | | T_STORE_COMMENT | 评论表 | | T_STORE_COMMENT_REPLY | 评论回复表 | | T_STORE_COMMENT_PRAISE | 评论点赞表 | | T_STORE_STATISTICS | 统计表 | | T_STORE_APPROVE | 审批表 | | T_STORE_SENSITIVE_API | 敏感 API 表 | | T_STORE_SENSITIVE_CONF | 敏感配置表 |

3.5 容器编译环境表

| 表名 | 说明 | |------|------| | T_APPS | 编译环境信息表 | | T_APP_ENV | 编译环境变量表 | | T_APP_VERSION | 编译环境版本表 | | T_CONTAINER | 容器信息表 | | T_BUILD_RESOURCE | 构建资源表 |

四、分层架构

┌─────────────────────────────────────────────────────────────────────────┐
│                              请求入口                                    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         API 层 (api-store)                               │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐    │
│  │UserMarket    │ │ServiceAtom   │ │UserTemplate  │ │UserImage     │    │
│  │AtomResource  │ │Resource      │ │Resource      │ │Resource      │    │
│  │(用户插件管理) │ │(服务间调用)   │ │(模板管理)     │ │(镜像管理)    │    │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                     │
│  │UserAtom      │ │OpAtom        │ │UserStore     │                     │
│  │ReleaseRes    │ │Resource      │ │MemberRes     │                     │
│  │(插件发布)     │ │(运维管理)     │ │(成员管理)     │                     │
│  └──────────────┘ └──────────────┘ └──────────────┘                     │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       业务层 (biz-store)                                 │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      插件服务 (atom/service/)                     │   │
│  │  MarketAtomService       - 插件市场服务                           │   │
│  │  AtomReleaseService      - 插件发布服务                           │   │
│  │  AtomService             - 插件基础服务                           │   │
│  │  MarketAtomEnvService    - 插件环境服务                           │   │
│  │  MarketAtomArchiveService - 插件归档服务                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      通用服务 (common/service/)                   │   │
│  │  StoreCommentService     - 评论服务                               │   │
│  │  StoreMemberService      - 成员管理服务                           │   │
│  │  StoreProjectService     - 项目关联服务                           │   │
│  │  StoreStatisticService   - 统计服务                               │   │
│  │  StoreApproveService     - 审批服务                               │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      处理器链 (common/handler/)                   │   │
│  │  StoreCreateHandlerChain   - 创建处理器链                         │   │
│  │  StoreUpdateHandlerChain   - 更新处理器链                         │   │
│  │  StoreDeleteHandlerChain   - 删除处理器链                         │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         DAO 层 (biz-store/dao)                           │
│  AtomDao (59KB) | MarketAtomDao (31KB) | StoreProjectRelDao (25KB)       │
│  StoreBaseQueryDao (20KB) | MarketAtomEnvInfoDao | ...                  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      数据层 (model-store + MySQL)                        │
│  数据库：devops_ci_store（共 50+ 张表）                                  │
└─────────────────────────────────────────────────────────────────────────┘

五、核心类速查

5.1 API 接口层

| 类名 | 路径前缀 | 职责 | |------|----------|------| | UserMarketAtomResource | /user/market/atom | 用户插件市场操作 | | UserAtomReleaseResource | /user/market/atom/release | 插件发布 | | ServiceAtomResource | /service/atoms | 服务间插件查询 | | ServiceMarketAtomResource | /service/market/atom | 服务间市场插件 | | OpAtomResource | /op/market/atom | 运维插件管理 | | UserTemplateResource | /user/market/template | 模板管理 | | UserMarketImageResource | /user/market/image | 镜像管理 | | UserStoreMemberResource | /user/store/member | 成员管理 |

5.2 Service 层

| 类名 | 职责 | |------|------| | MarketAtomService | 插件市场核心服务 | | AtomReleaseService | 插件发布流程 | | AtomService | 插件基础操作 | | MarketAtomEnvService | 插件执行环境 | | MarketAtomArchiveService | 插件归档 | | AtomCooperationService | 插件协作 | | AtomNotifyService | 插件通知 |

5.3 DAO 层

| 类名 | 文件大小 | 职责 | |------|----------|------| | AtomDao | 59KB | 插件主表访问（最大） | | MarketAtomDao | 31KB | 市场插件访问 | | StoreProjectRelDao | 25KB | 项目关联访问 | | StoreBaseQueryDao | 20KB | 基础查询 | | MarketAtomEnvInfoDao | 13KB | 插件环境访问 |

六、核心流程

6.1 插件发布流程

开发者提交发布请求
    │
    ▼
UserAtomReleaseResource.createAtom()
    │
    ▼
AtomReleaseService.handleAtomRelease()
    │
    ├─► 参数校验
    │   ├─► 校验插件代码唯一性
    │   ├─► 校验版本号格式
    │   └─► 校验代码库权限
    │
    ├─► 创建插件记录
    │   ├─► atomDao.create()
    │   └─► 状态设为 INIT
    │
    ├─► 触发构建流水线
    │   └─► 调用 Process 模块构建插件包
    │
    ├─► 构建完成回调
    │   ├─► 更新状态为 TESTING
    │   └─► 上传插件包到制品库
    │
    ├─► 提交审核
    │   └─► 状态设为 AUDITING
    │
    └─► 审核通过
        ├─► 状态设为 RELEASED
        └─► 更新 LATEST_FLAG

6.2 插件安装流程

用户安装插件到项目
    │
    ▼
UserMarketAtomResource.installAtom()
    │
    ▼
MarketAtomService.installAtom()
    │
    ├─► 权限校验
    │   └─► 检查用户是否有项目权限
    │
    ├─► 检查插件可见性
    │   └─► 检查项目是否在可见范围内
    │
    ├─► 创建关联记录
    │   └─► storeProjectRelDao.create()
    │
    └─► 更新统计数据
        └─► 增加安装量

6.3 处理器链模式

Store 模块使用责任链模式处理组件的创建、更新、删除：

// 创建处理器链
class StoreCreateHandlerChain {
    private val handlers = listOf(
        StoreCreateParamCheckHandler,    // 参数校验
        StoreCreatePreBusHandler,        // 前置业务处理
        StoreCreateDataPersistHandler,   // 数据持久化
        StoreCreatePostBusHandler        // 后置业务处理
    )
    
    fun handle(context: StoreContext) {
        handlers.forEach { it.handle(context) }
    }
}

七、与其他模块的关系

7.1 依赖关系

┌─────────────────────────────────────────────────────────────────┐
│                    Store 模块依赖关系                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│                  ┌───────────────┐                               │
│                  │     store     │                               │
│                  └───────┬───────┘                               │
│                          │                                       │
│       ┌──────────────────┼──────────────────┐                   │
│       ▼                  ▼                  ▼                   │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐               │
│  │  project  │    │repository │    │artifactory│               │
│  │ (项目信息) │    │ (代码库)   │    │ (制品库)   │               │
│  └───────────┘    └───────────┘    └───────────┘               │
│                                                                  │
│  被依赖：                                                        │
│  - process（流水线使用插件）                                      │
│  - worker（构建机执行插件）                                       │
└─────────────────────────────────────────────────────────────────┘

7.2 服务间调用示例

// Process 模块获取插件信息
// 注意：projectCode 是 T_PROJECT.english_name
client.get(ServiceAtomResource::class).getAtomByCode(
    atomCode = atomCode,
    username = userId
)

// 获取插件执行环境
client.get(ServiceMarketAtomEnvResource::class).getAtomEnv(
    projectCode = projectId,  // english_name
    atomCode = atomCode,
    atomVersion = version
)

// 获取项目可用的插件列表
client.get(ServiceMarketAtomResource::class).getProjectElements(
    projectCode = projectId
)

八、插件开发规范

8.1 插件目录结构

my-atom/
├── task.json           # 插件配置文件
├── README.md           # 插件说明
├── src/                # 源代码
│   └── main.py         # 入口文件
├── requirements.txt    # Python 依赖
└── logo.png            # 插件图标

8.2 task.json 配置

{
  "atomCode": "myAtom",
  "execution": {
    "language": "python",
    "packagePath": "src/",
    "target": "main.py"
  },
  "input": {
    "param1": {
      "label": "参数1",
      "type": "vuex-input",
      "required": true
    }
  },
  "output": {
    "output1": {
      "type": "string",
      "description": "输出参数"
    }
  }
}

8.3 插件开发语言支持

| 语言 | 说明 | |------|------| | Python | 推荐，有完善的 SDK | | NodeJS | 支持 | | Java | 支持 | | Golang | 支持 |

九、开发规范

9.1 新增组件类型

  1. 在 StoreTypeEnum 添加新类型
  2. 创建对应的主表和关联表
  3. 创建 DAO、Service、Resource 层代码
  4. 在处理器链中注册新类型的处理器

9.2 插件查询示例

// 根据插件代码查询最新版本
val atom = atomDao.getLatestAtomByCode(
    dslContext = dslContext,
    atomCode = atomCode
)

// 查询项目可用的插件
val atoms = atomDao.getProjectAtoms(
    dslContext = dslContext,
    projectCode = projectId,  // english_name
    classifyCode = classifyCode
)

// 查询插件执行环境
val envInfo = marketAtomEnvInfoDao.getMarketAtomEnvInfo(
    dslContext = dslContext,
    atomId = atomId
)

十、常见问题

Q: atomCode 和 atomId 的区别？ A: atomCode 是插件唯一标识（不变），atomId 是具体版本的 ID（每个版本不同）。

Q: 如何判断插件是否可用？ A: 检查 ATOM_STATUS = 7（RELEASED）且 LATEST_FLAG = true。

Q: 插件如何关联到项目？ A: 通过 T_STORE_PROJECT_REL 表关联，STORE_CODE 存储 atomCode。

Q: 如何获取插件的执行环境？ A: 查询 T_ATOM_ENV_INFO 表，根据 ATOM_ID 获取 PKG_PATH、TARGET 等信息。

版本: 1.0.0 | 更新日期: 2025-12-11