45f9e83edb
- .gitignore에 .archive/ 폴더 추가 - 기존 문서들 재구조화 및 v2로 업데이트 - 새로운 문서 카테고리 추가: - ai-memory: AI 메모리 시스템 관련 - architecture: 시스템 아키텍처 설계 - implementation: 구현 가이드 - philosophy: 프로젝트 철학 - research: 연구 자료 - skills-stats: 스킬 및 스탯 시스템 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
28 lines
2.9 KiB
Markdown
Executable File
28 lines
2.9 KiB
Markdown
Executable File
# Skillhub 플러그인 아키텍처 설계 요약
|
|
|
|
## 개요
|
|
이 문서는 제너럴 뉴스 콜렉터와 포맷 변환기 그리고 게시기 스킬을 플러그인 형태로 구성하는 시스템의 설계 내용을 요약합니다. 설계 목표는 초기에는 단일 프로세스 플러그인 구조로 시작하고 이후 필요에 따라 하이브리드 혹은 마이크로서비스 환경으로 자연스럽게 확장할 수 있는 유연성을 확보하는 것입니다.
|
|
|
|
## 핵심 설계 원칙
|
|
1. 모든 스킬은 Python 패키지로 배포되며 setuptools entry_points 기능을 활용해서 런타임에 동적으로 탐색됩니다.
|
|
2. 스킬 간 인터페이스는 추상 클래스 기반으로 고정하여 호출 방식이 일관되도록 합니다.
|
|
3. 각 스킬은 독립 가상 환경에 설치되어 의존성 충돌과 장애 전파를 방지합니다.
|
|
4. 파이프라인 정의 파일로 콜렉터, 포맷터, 퍼블리셔의 실행 순서를 선언합니다.
|
|
5. 스킬 패키지는 메타데이터에 지원 API 버전과 입출력 스키마 정보를 명확히 포함합니다.
|
|
|
|
## 데이터 스키마 검증
|
|
모든 데이터 모델은 Pydantic 클래스로 선언합니다. 스키마는 Python 코드 수준에서 검증되고, 필요 시 model.schema_json 메서드를 통해 JSON Schema 파일을 자동 생성하여 문서화합니다. 파이프라인 실행기는 단계별 입출력 객체가 예상한 타입인지 추가로 검사하여 불일치 시 즉시 예외를 발생시킵니다.
|
|
|
|
## 버전 관리 전략
|
|
Semantic Versioning을 적용합니다. 메이저 버전은 호환성을 끊는 변경에만 증가시키고 마이너 버전은 호환되는 기능 추가에, 패치 버전은 버그 수정에 사용합니다. skillhub 메타데이터의 api_version 필드는 런타임 호환 범위를 지정합니다. 동일한 스킬 이름이라도 버전이 다르면 별도 가상 환경에 설치되어 공존할 수 있습니다.
|
|
|
|
## 구현 단계 로드맵
|
|
1. skillhub-core 패키지에 인터페이스, 스키마, 로더, 가상 환경 관리 도구를 담아 우선 배포합니다.
|
|
2. 참조 스킬 세 가지를 작성합니다. 일반 뉴스 콜렉터, 요약 포맷 변환기, 이메일 퍼블리셔가 그 예입니다.
|
|
3. GitHub Actions에서 스키마 검증과 단위 테스트를 자동화합니다.
|
|
4. GitHub Organization에 registry.yaml 파일을 두고 초기에 승인된 스킬 메타데이터를 관리합니다.
|
|
5. 운영 환경에서는 파이프라인 정의 파일을 불러와 순차적으로 스킬을 실행하고 로그와 결과물을 외부 저장소로 보관합니다.
|
|
|
|
## 향후 확장 포인트
|
|
자연어 명령으로 스킬 조합을 자동 생성하거나 다른 프로그래밍 언어로 작성된 스킬을 통합해야 할 시점이 오면 LangGraph 같은 오케스트레이션 레이어를 추가합니다. 기존 플러그인 인터페이스는 그대로 유지되므로 변경 범위가 최소화됩니다.
|