Move directory
This commit is contained in:
wbsong111
@@ -0,0 +1,242 @@
|
||||
# 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/<chart>/<version>/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/<chart>/<to_version>/CUSTOM-README.md", # to_version으로 경로 결정
|
||||
version="<from_version> → <to_version>",
|
||||
content=<markdown>
|
||||
) # 항상 실행
|
||||
↓
|
||||
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로 사용하는 방법
|
||||
Reference in New Issue
Block a user