docs/OPENCODE_COMPARISON.md

# OpenCode vs opencode-api 기능 비교 분석

> 분석일: 2026-01-28
>
> 원본 TypeScript OpenCode와 Python opencode-api의 기능 비교 및 클론 계획

---

## 개요

| 항목 | 원본 TypeScript OpenCode | Python opencode-api |
|-----|-------------------------|---------------------|
| 용도 | 개발자용 AI 코딩 에이전트 CLI | 교육 플랫폼용 웹 API |
| 런타임 | Bun | Python 3.11+ / FastAPI |
| 아키텍처 | Namespace 패턴, 이벤트 기반 | 클래스 기반, 직접 호출 |
| 경로 | `/packages/opencode/src/` | `/opencode-api/src/opencode_api/` |

---

## 현재 구현 상태 (약 20-25%)

| 영역 | 원본 기능 수 | Python 구현 | 비율 |
|-----|-------------|------------|------|
| Session | 13 기능 | 4 기능 | **31%** |
| Provider | 21 프로바이더 | 4 프로바이더 | **19%** |
| Tool | 24 도구 | 5 도구 | **21%** |
| Server | 15 라우트 그룹 | 5 라우트 모듈 | **33%** |
| 기타 (MCP, LSP, Permission, Snapshot, Plugin) | 5 시스템 | 0 시스템 | **0%** |

---

## 1. Session 관리

### 구현 상태

| 기능 | 원본 파일 | Python 파일 | 상태 |
|-----|----------|------------|------|
| 세션 생성/조회/수정/삭제 | `session/index.ts` | `session/session.py` | ✅ 구현됨 |
| 메시지 파트 시스템 | `message-v2.ts` | `message.py` | ⚠️ 간소화됨 |
| 메시지 스트리밍 | `processor.ts` + `llm.ts` | `prompt.py` | ✅ 구현됨 |
| 세션 압축 (Compaction) | `compaction.ts` | - | ❌ 미구현 |
| 스냅샷/되돌리기 | `revert.ts` + `Snapshot` | - | ❌ 미구현 |
| 세션 요약 | `summary.ts` | - | ❌ 미구현 |
| 세션 공유 | `share/share-next.ts` | - | ❌ 미구현 |
| 세션 포크 | `Session.fork()` | - | ❌ 미구현 |
| 비용 계산 | `Session.getUsage()` | 기본 토큰만 | ⚠️ 간소화됨 |
| 세션 상태 | `status.ts` | - | ❌ 미구현 |
| 재시도 로직 | `retry.ts` | - | ❌ 미구현 |

### 미구현 기능 상세

#### 세션 압축 (Compaction)
- **원본 위치**: `session/compaction.ts`
- **기능**: 대화가 길어지면 이전 메시지를 요약하여 컨텍스트 윈도우 관리
- **중요도**: 🔴 높음 (긴 대화 시 필수)

#### 세션 요약 (Summary)
- **원본 위치**: `session/summary.ts`
- **기능**: 파일 변경 통계 계산 (additions, deletions, files)
- **중요도**: 🟡 중간

#### 스냅샷/되돌리기
- **원본 위치**: `session/revert.ts`, `snapshot/index.ts`
- **기능**: Git 기반 스냅샷으로 세션 상태 되돌리기
- **중요도**: 🟡 중간 (교육 플랫폼에서는 낮음)

---

## 2. Provider (LLM 통합)

### 구현 상태

| 프로바이더 | 원본 | Python | 상태 |
|-----------|------|--------|------|
| Anthropic Claude | ✅ | ✅ `anthropic.py` | ✅ 구현됨 |
| OpenAI | ✅ | ✅ `openai.py` | ✅ 구현됨 |
| Google Gemini | ✅ | ✅ `gemini.py` | ✅ 구현됨 |
| LiteLLM | ❌ | ✅ `litellm.py` | ✅ Python 전용 |
| Amazon Bedrock | ✅ | ❌ | ❌ 미구현 |
| Azure OpenAI | ✅ | ❌ | ❌ 미구현 |
| Google Vertex | ✅ | ❌ | ❌ 미구현 |
| OpenRouter | ✅ | ❌ | ❌ 미구현 |
| GitHub Copilot | ✅ | ❌ | ❌ 미구현 |
| xAI/Grok | ✅ | ❌ | ❌ 미구현 |
| Mistral | ✅ | ❌ | ❌ 미구현 |
| Groq | ✅ | ❌ | ❌ 미구현 |
| DeepInfra | ✅ | ❌ | ❌ 미구현 |
| Cerebras | ✅ | ❌ | ❌ 미구현 |
| Cohere | ✅ | ❌ | ❌ 미구현 |
| Together AI | ✅ | ❌ | ❌ 미구현 |
| Perplexity | ✅ | ❌ | ❌ 미구현 |
| GitLab | ✅ | ❌ | ❌ 미구현 |
| Cloudflare | ✅ | ❌ | ❌ 미구현 |
| SAP AI Core | ✅ | ❌ | ❌ 미구현 |

### 추가 프로바이더 구현 방법
- LiteLLM을 통해 대부분의 프로바이더를 쉽게 추가 가능
- `provider/litellm.py` 확장으로 OpenRouter, Groq, Mistral 등 지원

---

## 3. Tool System

### 구현 상태

| 도구 | 원본 파일 | Python 파일 | 상태 |
|-----|----------|------------|------|
| Tool 추상화 | `tool/tool.ts` | `tool/tool.py` | ✅ 구현됨 |
| Tool 레지스트리 | `registry.ts` | `__init__.py` | ⚠️ 간소화됨 |
| **Question** | `question.ts` | `question.py` | ✅ 구현됨 |
| **WebSearch** | `websearch.ts` (Exa) | `websearch.py` (DuckDuckGo) | ⚠️ 다른 백엔드 |
| **WebFetch** | `webfetch.ts` | `webfetch.py` | ✅ 구현됨 |
| **Todo** | `todo.ts` | `todo.py` | ✅ 구현됨 |
| **Skill** | `skill.ts` | `skill.py` | ⚠️ 기본 구현 |
| **Bash** | `bash.ts` | - | ❌ 미구현 |
| **Edit** | `edit.ts` | - | ❌ 미구현 |
| **Write** | `write.ts` | - | ❌ 미구현 |
| **Read** | `read.ts` | - | ❌ 미구현 |
| **Glob** | `glob.ts` | - | ❌ 미구현 |
| **Grep** | `grep.ts` | - | ❌ 미구현 |
| **Ls** | `ls.ts` | - | ❌ 미구현 |
| **Task** | `task.ts` | - | ❌ 미구현 |
| **Batch** | `batch.ts` | - | ❌ 미구현 |
| **CodeSearch** | `codesearch.ts` | - | ❌ 미구현 |
| **LSP** | `lsp.ts` | - | ❌ 미구현 |
| **Plan** | `plan.ts` | - | ❌ 미구현 |
| **Apply Patch** | `apply_patch.ts` | - | ❌ 미구현 |
| **MultiEdit** | `multiedit.ts` | - | ❌ 미구현 |

### 미구현 핵심 도구 상세

#### Bash 도구
- **기능**: 셸 명령 실행, 타임아웃, 권한 검사
- **보안 고려**: 교육 플랫폼에서는 E2B 샌드박스 또는 코드 인터프리터 대안 필요
- **중요도**: 🔴 높음 (코드 실행 필요 시)

#### Edit/Write 도구
- **기능**: 파일 편집/생성, 퍼지 매칭, LSP 진단
- **구현 방안**: Supabase Storage 또는 E2B 샌드박스 활용
- **중요도**: 🔴 높음 (코드 작성 기능 필요 시)

#### Read/Glob/Grep 도구
- **기능**: 파일 읽기, 패턴 검색, 내용 검색
- **구현 방안**: 제한된 파일 시스템 또는 가상 환경
- **중요도**: 🟡 중간

#### Task 도구
- **기능**: 서브에이전트 위임
- **중요도**: 🟡 중간 (복잡한 작업 분할 시)

---

## 4. Server/API

### 구현 상태

| 엔드포인트 | 원본 | Python | 상태 |
|-----------|------|--------|------|
| `/session` | `routes/session.ts` | `routes/session.py` | ✅ 구현됨 |
| `/session/{id}/message` (SSE) | 통합 | `routes/session.py` | ✅ 구현됨 |
| `/session/{id}/abort` | 통합 | `routes/session.py` | ✅ 구현됨 |
| `/provider` | `routes/provider.ts` | `routes/provider.py` | ✅ 구현됨 |
| `/event` (SSE) | `server.ts` | `routes/event.py` | ⚠️ 기본 구현 |
| `/question` | `routes/question.ts` | `routes/question.py` | ✅ 구현됨 |
| `/agent` | - | `routes/agent.py` | ✅ Python 전용 |
| `/project` | `routes/project.ts` | - | ❌ 미구현 |
| `/config` | `routes/config.ts` | - | ❌ 미구현 |
| `/mcp` | `routes/mcp.ts` | - | ❌ 미구현 |
| `/permission` | `routes/permission.ts` | - | ❌ 미구현 |
| `/file` | `routes/file.ts` | - | ❌ 미구현 |
| `/pty` | `routes/pty.ts` | - | ❌ 미구현 |
| `/tui` | `routes/tui.ts` | - | ❌ 미구현 |
| `/experimental` | `routes/experimental.ts` | - | ❌ 미구현 |
| `/global` | `routes/global.ts` | - | ❌ 미구현 |

---

## 5. 기타 주요 시스템

| 시스템 | 원본 위치 | Python | 상태 |
|-------|----------|--------|------|
| **MCP** | `mcp/index.ts` | - | ❌ 미구현 |
| **LSP** | `lsp/index.ts` | - | ❌ 미구현 |
| **Plugin** | `plugin/index.ts` | - | ❌ 미구현 |
| **Permission** | `permission/index.ts` | - | ❌ 미구현 |
| **Snapshot** | `snapshot/index.ts` | - | ❌ 미구현 |
| **ACP** | `acp/` | - | ❌ 미구현 |
| **Worktree** | `worktree/index.ts` | - | ❌ 미구현 |
| **Scheduler** | `scheduler/index.ts` | - | ❌ 미구현 |

---

## 구현 우선순위

### 🟢 바로 구현 가능 (난이도: 낮음)

| 순위 | 기능 | 설명 | 예상 작업량 |
|-----|------|------|-----------|
| 1 | 추가 LLM 프로바이더 | LiteLLM 확장 (OpenRouter, Groq 등) | 1-2시간 |
| 2 | 세션 제목 자동 생성 | 첫 메시지로 제목 생성 | 1시간 |
| 3 | 웹 검색 개선 | Exa API로 전환 | 2시간 |
| 4 | 비용 계산 | models.dev 연동 | 2-3시간 |

### 🟡 중간 난이도

| 순위 | 기능 | 설명 | 예상 작업량 |
|-----|------|------|-----------|
| 5 | 세션 압축 (Compaction) | 컨텍스트 관리 | 4-6시간 |
| 6 | 세션 포크 | 대화 분기 | 2-3시간 |
| 7 | Read 도구 | 파일 읽기 (Storage) | 3-4시간 |
| 8 | Glob/Grep 도구 | 파일 검색 | 4-5시간 |

### 🔴 고난이도 (설계 변경 필요)

| 순위 | 기능 | 설명 | 예상 작업량 |
|-----|------|------|-----------|
| 9 | Edit/Write 도구 | 파일 수정 (샌드박스) | 1-2일 |
| 10 | Bash 도구 | 코드 실행 (보안) | 1-2일 |
| 11 | MCP 통합 | 외부 서버 연결 | 2-3일 |
| 12 | Snapshot/Revert | 되돌리기 | 1-2일 |

### ❌ 교육 플랫폼에 부적합

- CLI/TUI 인터페이스
- 로컬 파일 시스템 직접 접근
- PTY (터미널) 기능
- Git Worktree 관리

---

## 구현 체크리스트

### Phase 1: 기본 개선
- [ ] 추가 LLM 프로바이더 (LiteLLM 확장)
- [ ] 세션 제목 자동 생성
- [ ] 웹 검색 개선 (Exa API)
- [ ] 비용 계산 (models.dev)

### Phase 2: 세션 고급 기능
- [ ] 세션 압축 (Compaction)
- [ ] 세션 포크
- [ ] 세션 상태 관리

### Phase 3: 도구 확장
- [ ] Read 도구
- [ ] Glob 도구
- [ ] Grep 도구
- [ ] Ls 도구

### Phase 4: 고급 기능 (선택적)
- [ ] Edit/Write 도구 (샌드박스 환경)
- [ ] Bash 도구 (코드 인터프리터)
- [ ] MCP 기본 지원
- [ ] Task 도구 (서브에이전트)

---

## 참고 자료

### 원본 OpenCode 주요 파일
- Session: `/packages/opencode/src/session/`
- Provider: `/packages/opencode/src/provider/`
- Tool: `/packages/opencode/src/tool/`
- Server: `/packages/opencode/src/server/`

### Python API 주요 파일
- Session: `/opencode-api/src/opencode_api/session/`
- Provider: `/opencode-api/src/opencode_api/provider/`
- Tool: `/opencode-api/src/opencode_api/tool/`
- Routes: `/opencode-api/src/opencode_api/routes/`