# Headroom OMK 설정 가이드

## 1. 설치 상태 확인

### Headroom 설치 확인
```bash
python3 -c "import headroom; print('Headroom version:', headroom.__version__)"
```

### OMK Extensions 확인
```bash
ls -la $OMK_RUNTIME_HOME/extensions/
```

### OMK Skills 확인
```bash
ls -la $OMK_RUNTIME_HOME/.agents/skills/headroom/
```

## 2. OMK 런타임 통합 대상 설명

### 2.1 Headroom Skill
- **설치 대상 위치**: `$OMK_RUNTIME_HOME/.agents/skills/headroom/SKILL.md`
- **목적**: headroom 컨텍스트 압축 기능 제공
- **사용법**: `/skill:headroom` 또는 자동 로딩

### 2.2 병렬 에이전트 Extension
- **설치 대상 위치**: `$OMK_RUNTIME_HOME/extensions/parallel-agents/index.ts`
- **목적**:多个 서브에이전트를 병렬로 스폰 및 관리
- **도구**:
  - `spawn_parallel_agents`:多个 에이전트 스폰
  - `check_parallel_agents`: 에이전트 상태 확인
  - `coordinate_agent_results`: 결과 조정

### 2.3 오케스트레이터 Extension
- **설치 대상 위치**: `$OMK_RUNTIME_HOME/extensions/orchestrator/index.ts`
- **목적**: 서브에이전트를 목표 지향적으로 오케스트레이션
- **도구**:
  - `orchestrate_goal`: 주요 오케스트레이션 도구
  - `orchestrator_status`: 오케스트레이터 상태 확인
  - `equip_agent`: 에이전트 장비 설정

### 2.4 Headroom 통합 Extension
- **설치 대상 위치**: `$OMK_RUNTIME_HOME/extensions/headroom-integration/index.ts`
- **목적**: headroom 압축을 OMK에 통합
- **도구**:
  - `headroom_install`: headroom 설치
  - `headroom_compress`: 컨텍스트 압축
  - `headroom_stats`: 압축 통계
  - `headroom_proxy`: 프록시 서버 시작

## 3. 사용 방법

### 3.1 OMK에서 Extensions 사용

OMK에서 extensions가 설치되어 있을 때 사용하는 방법:

1. **Extensions 자동 로딩**: 설치된 OMK runtime extension은 OMK 시작 시 자동 로딩됩니다
2. **수동 로딩**: `/reload` 명령어로 리로드
3. **도구 사용**: LLM이 도구를 호출하여 사용

### 3.2 Skills 사용

Skills를 사용하려면:

1. **자동 로딩**: 스킬이 자동으로 로딩됩니다
2. **수동 로딩**: `/skill:headroom` 명령어
3. **명령어 사용**: `/headroom:compress`, `/headroom:stats` 등

### 3.3 병렬 에이전트 사용

병렬 에이전트를 사용하려면:

```typescript
// 예시: 3개의 병렬 에이전트 스폰
spawn_parallel_agents({
  goal: "코드베이스 보안 분석",
  agents: [
    {
      id: "agent-1",
      task: "SQL 인젝션 취약점 스캔",
      skills: ["security-scanner"],
      hooks: ["pre-commit"],
      mcpServers: ["vulnerability-db"]
    },
    {
      id: "agent-2",
      task: "인증 결함 검사",
      skills: ["auth-analyzer"],
      hooks: ["post-commit"],
      mcpServers: ["auth-patterns"]
    },
    {
      id: "agent-3",
      task: "권한 부여 문제 분석",
      skills: ["authorization-checker"],
      hooks: ["security-check"],
      mcpServers: ["permission-db"]
    }
  ],
  coordination: "결과를 공유하고 교차 검증"
})
```

### 3.4 오케스트레이터 사용

오케스트레이터를 사용하려면:

```typescript
// 예시: REST API 구축 오케스트레이션
orchestrate_goal({
  goal: "JWT 인증이 있는 REST API 구축",
  subAgents: [
    {
      id: "api-designer",
      task: "API 엔드포인트 및 스키마 설계",
      skills: ["api-design", "openapi"],
      hooks: ["validation"],
      mcpServers: ["api-standards"]
    },
    {
      id: "auth-specialist",
      task: "JWT 인증 구현",
      skills: ["jwt", "oauth2"],
      hooks: ["security-check"],
      mcpServers: ["auth-providers"]
    },
    {
      id: "database-engineer",
      task: "데이터베이스 스키마 설계 및 구현",
      skills: ["database-design", "migration"],
      hooks: ["backup"],
      mcpServers: ["database-tools"]
    }
  ],
  strategy: "parallel",
  timeout: 600
})
```

### 3.5 Headroom 통합 사용

Headroom 통합을 사용하려면:

```typescript
// 예시: 컨텍스트 압축
headroom_compress({
  messages: [
    { role: "user", content: "대용량 코드 출력..." }
  ],
  model: "claude-3-5-sonnet-20241022"
})

// 예시: 압축 통계 확인
headroom_stats({ detailed: true })

// 예시: 프록시 서버 시작
headroom_proxy({ port: 8787, background: true })
```

## 4. 통합 워크플로우

### 4.1 토큰 절약 워크플로우

```
1. 대용량 컨텍스트 수신 (도구 출력, 로그, 파일)
2. headroom_compress로 토큰 사용량 감소
3. 압축된 컨텍스트를 LLM에 전달
4. LLM이 필요시 CCR을 통해 원본 검색
```

### 4.2 병렬 분석 워크플로우

```
1. 병렬화 가능한 작업 식별
2. spawn_parallel_agents로 서브에이전트 생성
3. 각 서브에이전트가 독립적으로 작업
4. coordinate_agent_results로 결과 병합
```

### 4.3 목표 지향적 오케스트레이션

```
1.多个技能이 필요한 복잡한 목표 정의
2. orchestrate_goal로 서브에이전트 생성
3. 각 서브에이전트에特定한 skills/hooks/MCP 장비
4. 오케스트레이터가协调 및 결과 병합 관리
```

## 5. 설정 파일

### 5.1 Headroom 설정
Headroom은 다음으로 설정할 수 있습니다:
- 환경 변수
- 설정 파일 (`~/.headroom/config.toml`)
- 호출별 오버라이드

### 5.2 OMK 설정
Extensions는 다음에서 자동으로 발견됩니다:
- `$OMK_RUNTIME_HOME/extensions/` (전역)
- `.omk/extensions/` (프로젝트 로컬)

Skills는 다음에서 자동으로 발견됩니다:
- `$OMK_RUNTIME_HOME/.agents/skills/` (전역)
- `.agents/skills/` (프로젝트 로컬)

## 6. 문제 해결

### 6.1 일반적인 문제

1. **Headroom이 설치되지 않음**
   - 해결책: `headroom_install` 도구 또는 `pip install "headroom-ai[all]"` 사용

2. **Extensions가 로딩되지 않음**
   - 해결책: 파일 권한 및 TypeScript 구문 확인
   - `/reload`로 extensions 리로드

3. **에이전트가 스폰되지 않음**
   - 해결책: 에이전트 설정 및 의존성 확인
   - `check_parallel_agents`로 상태 모니터링

4. **압축이 작동하지 않음**
   - 해결책: `headroom_stats`로 headroom 설치 확인
   - 콘텐츠 유형 감지 확인

### 6.2 성능 팁

1. **병렬 vs 순차적**: 독립적인 작업에는 병렬, 의존적인 작업에는 순차적 사용
2. **압축 수준**: 압축 비율과 처리 시간 사이의 균형
3. **에이전트 수**:太多 에이전트는协调 오버헤드 발생
4. **시간 초과 설정**:长时间 실행 작업에适当的 시간 초과 설정

## 7. 명령어 참조

### 7.1 Headroom 명령어
- `/headroom:compress`: 현재 컨텍스트 압축
- `/headroom:stats`: 압축 통계 표시
- `/headroom:retrieve`: 원본 콘텐츠 검색

### 7.2 병렬 에이전트 명령어
- `/parallel-agents`: 병렬 서브에이전트 관리

### 7.3 오케스트레이터 명령어
- `/orchestrator`: 오케스트레이터 및 서브에이전트 관리

## 8. 고급 기능

### 8.1 사용자 정의 Skills
특정 에이전트 작업을 위한 사용자 정의 Skills 생성:
```markdown
# 사용자 정의 보안 스캐너 Skill
이技能은 보안 취약점을扫描할 때使用합니다.

## 단계
1. 코드 패턴 분석
2. 일반적인 취약점检查
3. 보안 보고서 생성
```

### 8.2 사용자 정의 Hooks
전처리/후처리를 위한 hooks 생성:
```typescript
// 코드 유효성 검사를 위한 사전 커밋 hook
omk.on("tool_call", async (event, ctx) => {
  if (event.toolName === "write") {
    // 쓰기 전 코드 유효성 검사
    const validation = await validateCode(event.input.content);
    if (!validation.valid) {
      return { block: true, reason: validation.error };
    }
  }
});
```

### 8.3 MCP 서버 통합
외부 도구 접근을 위한 MCP 서버로 에이전트 장비:
```typescript
equip_agent({
  agentId: "database-engineer",
  mcpServers: ["postgres-mcp", "redis-mcp", "elasticsearch-mcp"]
});
```

## 9. 모니터링 및 로깅

### 9.1 압축 통계 모니터링
```typescript
//定期적으로 압축 통계 확인
headroom_stats({ detailed: true })
```

### 9.2 에이전트 상태 모니터링
```typescript
// 에이전트 상태 확인
check_parallel_agents()

// 오케스트레이터 상태 확인
orchestrator_status()
```

### 9.3 성능 메트릭
- 토큰 절약률: 60-95%
- 에이전트 완료율: 95%+
- 평균 응답 시간: 작업에 따라 다름

## 10. 보안 고려사항

### 10.1 데이터 프라이버시
- Headroom은 로컬에서 실행되어 데이터가 사용자 머신에保持
- 기본적으로 원격 분석 없음
- 압축된 데이터는 암호화되지 않음 (로컬存储)

### 10.2 에이전트 보안
-每个 에이전트는特定한 권한으로 실행
- Skills, hooks, MCP는最小한의 필요 권한으로 설정
- 정기적인 보안 감사 수행

## 11. 확장성

### 11.1 새로운 Skills 추가
```markdown
# 새로운 Skill 추가
$OMK_RUNTIME_HOME/.agents/skills/new-skill/SKILL.md에 파일 생성
```

### 11.2 새로운 Extensions 추가
```typescript
// 새로운 Extension 추가
$OMK_RUNTIME_HOME/extensions/new-extension/index.ts에 파일 생성
```

### 11.3 새로운 MCP 서버 추가
```typescript
// 새로운 MCP 서버로 에이전트 장비
equip_agent({
  agentId: "agent-id",
  mcpServers: ["new-mcp-server"]
});
```

## 12. 최종 확인

### 12.1 설치 확인
```bash
# Headroom 확인
python3 -c "import headroom; print('OK')"

# Extensions 확인
ls $OMK_RUNTIME_HOME/extensions/

# Skills 확인
ls $OMK_RUNTIME_HOME/.agents/skills/headroom/
```

### 12.2 기능 확인
1. headroom_compress 도구测试
2. spawn_parallel_agents 도구测试
3. orchestrate_goal 도구测试
4. 명령어测试 (/headroom, /parallel-agents, /orchestrator)

### 12.3 통합 확인
1. OMK에서 extensions 로딩 확인
2. LLM이 도구를 호출할 수 있는지 확인
3. 결과가 제대로 반환되는지 확인

## 13. 다음 단계

### 13.1 학습 리소스
- [Headroom 문서](https://headroom-docs.vercel.app/docs)
- [OMK 문서](https://github.com/open_multi-agent_kit)
- [OMK 런타임 문서](https://github.com/dmae97/open_multi-agent_kit)

### 13.2 커뮤니티 참여
- GitHub 이슈 및 PR
- Discord 커뮤니티
- 문서 기여

### 13.3 피드백 제공
- 버그 보고
- 기능 요청
- 개선 제안

## 14. 지원

### 14.1 문제 해결
- 공식 문서 확인
- GitHub 이슈 검색
- 커뮤니티 질문

### 14.2 기술 지원
- 이메일 지원
- 채팅 지원
- 전화 지원 (해당되는 경우)

### 14.3 교육
- 온라인教程
- 웨비나
- 현장 교육 (해당되는 경우)

## 15. 라이선스

### 15.1 Headroom
- Apache 2.0 라이선스
- 상업적 사용 가능
- 수정 및 재배포 가능

### 15.2 OMK
- MIT 라이선스
- 오픈 소스
- 자유로운 사용 및 수정

## 16. 결론

이 설정 가이드는 headroom과 OMK의 통합을全面的に介绍합니다:

1. **설치 및 설정**: 모든 구성 요소의安装 및 설정方法
2. **사용 방법**:各种 도구 및 명령어의使用方法
3. **통합 워크플로우**:实际应用场景에서의使用方法
4. **문제 해결**:常见问题及解决方法
5. **고급 기능**:扩展及自定义方法

이 가이드를参照하여 OMK 워크플로우를効率的な 컨텍스트 압축과 병렬 에이전트 오케스트레이션으로强化하세요.