step3. 파일 편집하기

플러그인 개발 중 주로 편집하는 파일과 각 파일의 역할을 확인합니다.

진행 순서

1. 플러그인 프로젝트의 기본 구조를 확인합니다.
2. config.yaml에서 플러그인 정보와 액션 실행 방식을 선언합니다.
3. requirements.txt에 필요한 Python 의존성을 추가합니다.
4. plugin/<action>.py 파일에서 플러그인 로직을 구현합니다.
5. 상태 보고 API로 진행률과 실행 로그를 남깁니다.

1. 플러그인 구조 확인하기

플러그인 개발 중 주로 편집하는 파일은 세 개입니다.

plugin/
├── plugin/<action>.py    # ① 로직 구현 (upload.py / export.py / inference.py …)
├── config.yaml           # ② 플러그인 정보와 액션 선언
└── requirements.txt      # ③ 파이썬 의존성

2. config.yaml 작성하기

config.yaml은 플러그인의 명세 파일입니다.

플러그인을 게시할 때 이 파일을 기준으로 이름, 코드, 버전, 카테고리, 액션 정보가 등록됩니다.

name: My Export            # 화면 표시 이름
code: my-export            # 고유 식별자 (변경 금지)
version: 0.1.0             # 게시 버전 — 게시할 때마다 이 값이 기준
category: export
description: 우리 회사 포맷 익스포트

actions:
  export:
    entrypoint: plugin.export.MyExportAction   # 실행할 클래스 위치
    method: job

주요 설정 항목

3. requirements.txt 작성하기

requirements.txt는 플러그인이 사용하는 외부 라이브러리 목록입니다.

첫 줄의 synapse-sdk는 지우지 마세요. 실행 환경에 자동 설치되므로, IDE에서만 설치하고 requirements.txt에 빠뜨리면 실제 실행에서 ImportError가 발생할 수 있습니다.

synapse-sdk
pandas
opencv-python

4. 로직 구현 파일 작성하기

로직 구현 파일에서는 카테고리마다 SDK가 제공하는 베이스 클래스를 상속하고, 정해진 메서드만 구현합니다.

데이터 조회, 파일 전송, 진행률 집계 같은 공통 처리는 SDK가 담당합니다. 개발자는 변환/처리 로직에 집중하면 됩니다.

상태 보고 API 사용하기

구현 중 상태 보고는 다음 API를 사용합니다. 이 값이 사용자 화면의 진행률과 로그로 표시됩니다.

...set_progress(현재, 전체, step=...)   # 진행률
...log_message('처리 중입니다')          # 사용자에게 보이는 로그
...log_dev_event(msg, data={...})       # 개발자용 상세 로그 (문제 추적용)