# Skill 인터페이스 정의 ## 1. 개요 각 컴포넌트를 **OpenClaw Skill**로 노출한다. 이 인터페이스는 Skills(Step 1)와 On-Cluster Agent(Step 2~3) 간의 **계약(contract)**이다. > Agent(OpenClaw/Nanobot)가 이 Skill들을 워크플로로 호출한다. --- ## 2. Skill 목록 | Skill 이름 | 역할 | 해당 컴포넌트 | |-----------|------|-------------| | `helm_diff` | 두 버전 간 Structured Diff JSON 생성 | Helm Diff Engine | | `breaking_change_check` | Diff JSON에서 Breaking Change 판단 | Breaking Change Rule Engine | | `generate_upgrade_doc` | 업그레이드 주의사항 Markdown 문서 생성 (항상 실행) | LLM Summarizer | | `update_docs_file` | CUSTOM-README.md에 업그레이드 주의사항 섹션 추가 | Docs Updater | | `create_pr` | GitHub PR 생성 | Git PR Bot | | `deploy_validate` | test namespace에 배포 후 health 검증 **(Phase 2, 미구현)** | Deploy Validator | --- ## 3. Skill 상세 정의 ## 2.1 공통 에러 스키마 모든 Skill은 실패 시 아래 형식으로 에러를 반환한다. ```json { "error": { "code": "ERR_HELM_PULL" , "message": "helm pull failed", "retryable": true, "details": { "exit_code": 1 } } } ``` - `retryable=true`인 경우에만 자동 재시도를 수행한다. ## 2.2 Idempotency / Retry 정책 - **read-only Skill**(helm_diff, breaking_change_check, generate_upgrade_doc)는 안전 재시도 가능. - **side-effect Skill**(update_docs_file, create_pr, deploy_validate)은 idempotency key를 사용한다. - `create_pr`는 동일 key 요청 시 기존 PR URL을 반환해야 한다. ## 2.3 Auth/Secret 전달 - 토큰/시크릿은 **env var 또는 K8s Secret**으로 주입한다. - 입력 payload에 직접 포함하지 않는다. ### 3.1 `helm_diff` ```yaml name: helm_diff description: > 두 버전의 Helm Chart를 비교하여 Structured Diff JSON을 생성한다. values, templates, CRD, dependencies 변경사항을 포함한다. input: chart: string # 차트 이름 (예: "airflow") repo: string # Helm repo 이름 또는 URL (repo 기반일 때만) chart_path: string # 로컬 차트 경로 (dip-catalog 구조) from_version: string # 기존 버전 (예: "1.2.3") to_version: string # 신규 버전 (예: "1.3.0") values_override: object # 사용자 정의 values (선택, dip-catalog은 custom-values.yaml 기본) output: chart: string from_version: string to_version: string generated_at: string # ISO 8601 timestamp values: object # Values Diff templates: object # Template Diff crd: object # CRD Diff dependencies: object # Dependency Diff errors: array # 부분 실패 정보 ``` ### 3.2 `breaking_change_check` ```yaml name: breaking_change_check description: > Structured Diff JSON을 입력받아 Breaking Change 여부를 코드 기반으로 판단한다. LLM을 사용하지 않으며 결과는 완전히 deterministic하다. input: diff_json: object # helm_diff 출력 (Structured Diff JSON) output: breaking: boolean severity: string # critical / high / medium / warning reasons: array # Breaking 사유 목록 warnings: array # 비중단 경고 목록 ``` ### 3.3 `generate_upgrade_doc` ```yaml name: generate_upgrade_doc description: > Structured Diff JSON과 Breaking Change 결과를 기반으로 업그레이드 주의사항 Markdown을 생성한다. 항상 실행된다. breaking=true면 LLM 상세 가이드, breaking=false면 템플릿 기반 간단 요약. input: diff_json: object # helm_diff 출력 breaking_result: object # breaking_change_check 출력 docs_context: object # CUSTOM-README.md 내용 (dip-catalog) max_tokens: integer # LLM 입력 최대 토큰 수 (기본: 50000) output: markdown: string # 생성된 Markdown 문서 truncated: boolean # 토큰 제한으로 입력이 잘렸는지 여부 ``` ### 3.4 `update_docs_file` ```yaml name: update_docs_file description: > CUSTOM-README.md에 업그레이드 주의사항 섹션을 추가한다. CUSTOM-README.md는 배포 관련 정보를 담는 문서로, 업그레이드 주의사항의 적합한 위치다. BUILD-README.md는 chart_updater의 carry-over로만 관리된다. input: repo_path: string # 로컬 Git 저장소 경로 docs_file: string # 문서 파일 경로 (예: "manifests/helm///CUSTOM-README.md") version: string # 삽입할 버전 표기 (예: "1.2.3 → 1.3.0") content: string # 삽입할 Markdown 내용 overwrite: boolean # 기존 버전 섹션 덮어쓰기 여부 (기본: false) output: success: boolean file_path: string already_existed: boolean ``` ### 3.5 `create_pr` ```yaml name: create_pr description: > Helm Chart 업그레이드를 위한 GitHub PR을 생성한다. branch 생성, commit, PR 생성을 포함한다. input: chart: string # 차트 이름 from_version: string to_version: string repo_path: string # 로컬 Git 저장소 경로 doc_content: string # upgrade.md에 삽입할 내용 breaking: boolean # PR label 결정에 사용 severity: string # PR label 결정에 사용 output: pr_url: string branch_name: string labels: array ``` ### 3.6 `deploy_validate` (Phase 2A+) ```yaml name: deploy_validate description: > Ephemeral test namespace에 Helm Chart를 배포하고 health를 검증한다. 성공/실패 결과와 Pod 상태를 반환한다. input: chart: string repo: string version: string values_override: object namespace: string # test namespace (예: "helm-test-airflow") timeout: integer # 초 단위, 기본 300 output: success: boolean dry_run_passed: boolean pod_status: object # { running: int, pending: int, failed: int } events: array # 비정상 K8s events logs: string # 실패 시 관련 Pod 로그 ``` --- ## 4. Agent 워크플로 호출 순서 Agent(OpenClaw/Nanobot)가 Skill들을 등록하고, 아래 순서를 워크플로로 정의한다. ```yaml # 개념적 호출 순서 (실제 워크플로 정의는 implementation/02-agent.md 참고) 1. helm_diff(chart, repo, from_version, to_version) ↓ 2. breaking_change_check(diff_json, custom_values) # custom-values.yaml 기준 판단 ↓ 3. generate_upgrade_doc(diff_json, breaking_result) # 항상 실행 │ breaking=true → LLM 상세 가이드 생성 │ breaking=false → 템플릿 기반 간단 요약 ↓ 4. update_docs_file( repo_path, docs_file="manifests/helm///CUSTOM-README.md", # to_version으로 경로 결정 version=" → ", content= ) # 항상 실행 ↓ 5. create_pr(chart, from_version, to_version, ...) # 항상 실행 │ breaking=true → label: needs-review │ breaking=false → label: auto-update ↓ exit 0 (항상) # Phase 2 (미구현): 6. deploy_validate(chart, repo, to_version, namespace) ``` --- ## 5. 버전 관리 이 인터페이스는 **명시적 버전**을 관리한다. ```yaml skill_interface_version: "1.0" ``` Skill 입출력 변경 시: - **하위 호환 변경** (필드 추가): 마이너 버전 증가 - **Breaking 변경** (필드 삭제/타입 변경): 메이저 버전 증가 + 마이그레이션 가이드 작성 --- ## 6. 관련 문서 - [01-helm-diff-engine.md](01-helm-diff-engine.md) — `helm_diff` 구현 설계 - [02-breaking-change-rules.md](02-breaking-change-rules.md) — `breaking_change_check` 구현 설계 - [03-llm-summarizer.md](03-llm-summarizer.md) — `generate_upgrade_doc`, `create_pr` 구현 설계 - [05-on-cluster-agent.md](05-on-cluster-agent.md) — Agent가 이 인터페이스를 Skills로 사용하는 방법