intent-hub 0.1.0

package/README_ko.md

@@ -0,0 +1,577 @@
+# Intent Hub
+
+**팀 기반 LLM 협업 플랫폼 - 시맨틱 충돌 해결 시스템**
+
+> 여러 개발자가 AI 코딩 에이전트를 동시에 사용하면 코드 충돌이 발생합니다. Intent Hub는 이 문제를 **시맨틱 레벨**에서 조율하여 - 충돌이 발생하기 전에 해결합니다.
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║   ██╗███╗   ██╗████████╗███████╗███╗   ██╗████████╗           ║
+║   ██║████╗  ██║╚══██╔══╝██╔════╝████╗  ██║╚══██╔══╝           ║
+║   ██║██╔██╗ ██║   ██║   █████╗  ██╔██╗ ██║   ██║              ║
+║   ██║██║╚██╗██║   ██║   ██╔══╝  ██║╚██╗██║   ██║              ║
+║   ██║██║ ╚████║   ██║   ███████╗██║ ╚████║   ██║              ║
+║   ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝  ╚═══╝   ╚═╝              ║
+║                         HUB                                   ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+[English](README.md) | 한국어
+
+---
+
+## 목차
+
+- [문제 상황](#문제-상황)
+- [해결책](#해결책)
+- [빠른 시작](#빠른-시작)
+- [LLM 에이전트를 위한 설치 가이드](#llm-에이전트를-위한-설치-가이드)
+- [팀 협업 가이드](#팀-협업-가이드)
+- [통합 방법](#통합-방법)
+- [작동 원리](#작동-원리)
+- [설정](#설정)
+
+---
+
+## 문제 상황
+
+AI 코딩 어시스턴트(Cursor, GitHub Copilot, OpenCode 등)를 사용하는 현대 팀에서:
+
+- **앨리스**가 AI에게 "OAuth 로그인 구현해줘"라고 요청
+- **밥**이 AI에게 "세션 관리 추가해줘"라고 요청
+- 두 AI가 동시에 `src/auth/*`를 수정
+- **결과**: 머지 충돌, 작업 손실, 좌절
+
+기존의 파일 레벨 락은 작동하지 않습니다:
+1. AI 에이전트들은 서로의 존재를 모름
+2. 시맨틱 겹침이 항상 파일 기반이 아님
+3. "auth"와 "session"이 같은 파일을 건드리지 않아도 개념적으로 연관됨
+
+## 해결책
+
+Intent Hub는 **시맨틱 락**을 도입합니다 - 파일 레벨이 아닌 도메인 레벨(`auth`, `payment`, `user`)에서 잠금을 수행합니다.
+
+```
+┌─────────────┐     WebSocket      ┌─────────────┐
+│   앨리스의   │◄──────────────────►│             │
+│   AI 에이전트 │                   │   Intent    │
+├─────────────┤                    │    Hub      │
+│    밥의      │◄──────────────────►│   서버      │
+│   AI 에이전트 │                   │             │
+├─────────────┤                    │  (중앙      │
+│   캐롤의     │◄──────────────────►│   조율기)   │
+│   AI 에이전트 │                   │             │
+└─────────────┘                    └─────────────┘
+```
+
+### 주요 기능
+
+- **스마트 의도 분석**: LLM 기반으로 각 개발자가 무엇을 하려는지 이해
+- **시맨틱 도메인 잠금**: 파일이 아닌 개념적 영역을 잠금
+- **LLM 협상**: 충돌 발생 시 AI 에이전트들이 해결책을 협상
+- **자동 해결**: 호환 가능한 변경사항은 자동으로 진행
+- **인간 에스컬레이션**: 호환 불가능한 변경은 개발자에게 결정 요청
+
+---
+
+## 빠른 시작
+
+### 🚀 Live Share 모드 (팀 권장)
+
+**VS Code Live Share처럼** - 한 명이 호스트하고, 다른 사람들은 링크로 참여. 네트워크 설정 불필요!
+
+```bash
+# 1. 설치
+git clone https://github.com/your-org/intent-hub.git && cd intent-hub
+bun install && bun run build
+
+# 2. Live Share 모드로 시작
+bun run packages/hub/dist/cli.js --share --llm=openai
+
+# 출력:
+# ╔═══════════════════════════════════════════════════════════════╗
+# ║                    🔗 SHARE YOUR SESSION                      ║
+# ╠═══════════════════════════════════════════════════════════════╣
+# ║  Team members can connect using:                              ║
+# ║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
+# ╚═══════════════════════════════════════════════════════════════╝
+
+# 3. 이 URL을 팀원들에게 공유하세요!
+```
+
+끝! 팀원들은 공유된 URL로 연결 - 방화벽/NAT 설정 필요 없음.
+
+---
+
+### 필수 조건
+
+- [Bun](https://bun.sh/) v1.1.0 이상
+- Node.js 20+ (호환성용)
+
+### 설치
+
+```bash
+git clone https://github.com/your-org/intent-hub.git
+cd intent-hub
+bun install
+bun run build
+```
+
+### 허브 서버 시작
+
+```bash
+# 🌐 Live Share 모드 (원격 팀용)
+bun run packages/hub/dist/cli.js --share
+
+# 🏠 로컬 모드 (같은 네트워크만)
+bun run packages/hub/dist/cli.js
+
+# OpenAI 사용
+OPENAI_API_KEY=sk-xxx bun run packages/hub/dist/cli.js --share --llm=openai
+
+# Anthropic 사용
+ANTHROPIC_API_KEY=sk-ant-xxx bun run packages/hub/dist/cli.js --share --llm=anthropic
+```
+
+### 서버 옵션
+
+```
+사용법:
+  intent-hub [options]
+
+옵션:
+  --port=<number>           포트 번호 (기본값: 9876)
+  --host=<string>           바인딩 호스트 (기본값: 0.0.0.0)
+  --mode=<mode>             서버 모드: simple | smart (기본값: smart)
+  --llm=<provider>          LLM 제공자: openai | anthropic | mock (기본값: mock)
+  --api-key=<key>           LLM 제공자 API 키 (또는 환경변수 사용)
+  --no-negotiate            자동 협상 비활성화
+  --dashboard               웹 대시보드 활성화
+  --share                   Live Share 모드 활성화 (공개 URL, 네트워크 설정 불필요)
+  --tunnel=<provider>       터널 제공자: auto | localtunnel | cloudflared (기본값: auto)
+  --help                    도움말 표시
+
+환경변수:
+  OPENAI_API_KEY       OpenAI API 키
+  ANTHROPIC_API_KEY    Anthropic API 키
+```
+
+---
+
+## LLM 에이전트를 위한 설치 가이드
+
+> 이 섹션은 Claude Code, OpenCode, Cursor 등의 AI 코딩 에이전트가 Intent Hub를 설치할 때 참고하는 가이드입니다.
+
+### 빠른 설치 (npx)
+
+**한 줄 명령어로 공유 세션 시작:**
+
+```bash
+# Live Share로 Intent Hub 시작 (권장)
+npx intent-hub --share
+
+# OpenAI로 스마트 분석 사용
+OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai
+```
+
+끝! 출력된 URL을 팀원들에게 공유하세요.
+
+---
+
+### Step 0: 사용자에게 환경 확인
+
+사용자에게 확인하세요:
+- **LLM 제공자**: OpenAI API 키 있나요? Anthropic API 키? 아니면 테스트용 mock?
+
+### Step 1: 허브 서버 시작
+
+**방법 A: npx (권장 - 설치 불필요):**
+```bash
+# Live Share로 빠른 시작
+npx intent-hub --share
+
+# OpenAI 사용
+OPENAI_API_KEY=sk-xxx npx intent-hub --share --llm=openai
+
+# Anthropic 사용
+ANTHROPIC_API_KEY=sk-ant-xxx npx intent-hub --share --llm=anthropic
+```
+
+**방법 B: 전역 설치:**
+```bash
+npm install -g intent-hub
+intent-hub --share --llm=openai
+```
+
+**방법 C: 소스에서 빌드:**
+```bash
+git clone https://github.com/anthropic-for-korea/intent-hub.git
+cd intent-hub && bun install && bun run build
+bun run packages/hub/dist/cli.js --share
+```
+
+### Step 2: URL 공유
+
+`--share`로 서버를 시작하면 출력됨:
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    🔗 SHARE YOUR SESSION                      ║
+╠═══════════════════════════════════════════════════════════════╣
+║  Team members can connect using:                              ║
+║  wss://intent-hub-a1b2c3d4.loca.lt                            ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+이 URL을 복사해서 팀원들에게 공유하세요!
+
+### Step 3: 에이전트 클라이언트 연결
+
+각 팀원의 AI 에이전트가 연결:
+
+```typescript
+import { HubClient } from '@anthropic-for-korea/intent-hub-agent';
+
+const client = new HubClient({
+  hubUrl: 'wss://intent-hub-a1b2c3d4.loca.lt',  // 공유받은 URL
+  userId: 'unique-user-id',
+  username: '사용자이름',
+  projectPath: '/path/to/project',
+});
+
+client.connect();
+```
+
+### 문제 해결
+
+| 증상 | 원인 | 해결책 |
+|------|------|--------|
+| 연결 실패 | 서버 미실행 | `npx intent-hub --share` 실행 |
+| 터널 에러 | 네트워크 문제 | cloudflared 설치 후 `--tunnel=cloudflared` 시도 |
+| LLM 에러 | API 키 없음 | `OPENAI_API_KEY` 또는 `ANTHROPIC_API_KEY` 환경변수 설정 |
+
+---
+
+## 팀 협업 가이드
+
+### 팀에서 Intent Hub 사용하기
+
+Intent Hub는 팀 전체가 함께 사용할 때 진정한 가치를 발휘합니다.
+
+#### 아키텍처
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        팀 서버                                │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │              Intent Hub Server                         │  │
+│  │              (ws://team-server:9876)                   │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ WebSocket
+          ┌───────────────────┼───────────────────┐
+          │                   │                   │
+          ▼                   ▼                   ▼
+    ┌──────────┐       ┌──────────┐       ┌──────────┐
+    │ 개발자 A  │       │ 개발자 B  │       │ 개발자 C  │
+    │ Claude   │       │ OpenCode │       │ Cursor   │
+    │ Code     │       │          │       │          │
+    └──────────┘       └──────────┘       └──────────┘
+```
+
+#### 설정 방법
+
+**1. 팀 서버에서 허브 실행:**
+
+```bash
+# 팀 서버에서 백그라운드로 실행
+nohup bun run packages/hub/dist/cli.js \
+  --llm=openai \
+  --dashboard \
+  --host=0.0.0.0 \
+  > intent-hub.log 2>&1 &
+```
+
+**2. 각 개발자의 AI 에이전트 설정:**
+
+개발자들은 자신이 사용하는 AI 에이전트(Claude Code, OpenCode, Cursor 등)에게 다음과 같이 요청하면 됩니다:
+
+> "Intent Hub에 연결해줘. 허브 서버 주소는 ws://team-server:9876이고, 내 이름은 [사용자이름]이야."
+
+또는 프로젝트 설정 파일에 추가:
+
+```json
+// .intent-hub.json (프로젝트 루트에 생성)
+{
+  "hubUrl": "ws://team-server:9876",
+  "autoConnect": true
+}
+```
+
+#### LLM을 통한 설치 요청 방법
+
+팀원들에게 다음과 같이 안내하세요:
+
+> **"Claude Code / OpenCode / Cursor에게 이렇게 말해:"**
+> 
+> "Intent Hub 클라이언트를 설치하고 ws://team-server:9876에 연결해줘.
+> 내 userId는 'my-unique-id'이고 이름은 '홍길동'이야.
+> GitHub: https://github.com/your-org/intent-hub"
+
+AI 에이전트가 알아서:
+1. 필요한 패키지 설치
+2. 설정 파일 생성
+3. 허브 서버에 연결
+4. 테스트 수행
+
+#### 협업 워크플로우
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        협업 시나리오                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. 앨리스: "OAuth 로그인 구현해줘"                                │
+│     └─> Intent Hub: auth/oauth 도메인 잠금 획득 ✓                 │
+│                                                                 │
+│  2. 밥: "세션 관리 추가해줘"                                       │
+│     └─> Intent Hub: auth 도메인 충돌 감지!                        │
+│         └─> 밥의 AI에게 알림: "앨리스가 auth 작업 중입니다.         │
+│             다른 작업을 먼저 하거나 기다려주세요."                   │
+│                                                                 │
+│  3. 캐롤: "결제 시스템 리팩토링해줘"                                │
+│     └─> Intent Hub: payment 도메인 잠금 획득 ✓                    │
+│         (auth와 무관하므로 동시 진행 가능)                         │
+│                                                                 │
+│  4. 앨리스 작업 완료                                              │
+│     └─> Intent Hub: auth/oauth 잠금 해제                         │
+│         └─> 밥의 AI에게 알림: "이제 auth 작업 가능합니다"           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### 팀 규모별 권장 설정
+
+| 팀 규모 | 서버 위치 | LLM 설정 | 비고 |
+|---------|----------|----------|------|
+| 1-3명 | 로컬 (개발자 중 한 명) | Mock 또는 OpenAI | 간단한 설정 |
+| 4-10명 | 전용 팀 서버 | OpenAI 또는 Anthropic | 안정적인 연결 필요 |
+| 10명+ | 클라우드 (AWS/GCP) | OpenAI + 고가용성 | 프로덕션 수준 |
+
+---
+
+## 통합 방법
+
+### OpenCode와 통합 (Hooks)
+
+```typescript
+import { createIntentHubHooks } from '@intent-hub/agent';
+
+const hooks = createIntentHubHooks({
+  hubUrl: 'ws://localhost:9876',
+  userId: 'alice',
+  username: 'Alice',
+  projectPath: '/path/to/project',
+  onNotification: (event, data) => {
+    console.log(`[IntentHub] ${event}:`, data);
+  },
+});
+
+// AI 에이전트의 도구 훅에서:
+// Pre-tool 훅 - 액션이 허용되는지 확인
+const result = await hooks.preToolUse({
+  toolName: 'edit',
+  toolInput: { filePath: 'src/auth/login.ts', content: '...' },
+  sessionId: 'session-123',
+  userId: 'alice',
+  username: 'Alice',
+});
+
+if (!result.allow) {
+  console.log(result.message); // 다른 사용자가 도메인을 잠금 중
+}
+
+// 사용자가 프롬프트를 제출할 때
+const promptResult = await hooks.onUserPromptSubmit('Google OAuth 로그인 추가');
+if (promptResult.message) {
+  console.log(promptResult.message); // 잠긴 도메인에 대한 경고
+}
+```
+
+### 프로그래매틱 사용
+
+```typescript
+import { HubClient } from '@intent-hub/agent';
+
+const client = new HubClient({
+  hubUrl: 'ws://localhost:9876',
+  userId: 'alice',
+  username: 'Alice',
+  projectPath: '/path/to/project',
+  onConnected: (sessionId) => {
+    console.log('연결됨:', sessionId);
+  },
+  onMessage: (message) => {
+    switch (message.type) {
+      case 'hub:lock:acquired':
+        console.log('잠금 획득:', message.payload.domains);
+        break;
+      case 'hub:lock:blocked':
+        console.log('차단됨:', message.payload.blockedBy);
+        break;
+      case 'hub:negotiation:start':
+        console.log('협상 시작:', message.payload.participants);
+        break;
+      case 'hub:decision:required':
+        console.log('결정 필요:', message.payload.question);
+        break;
+    }
+  },
+});
+
+client.connect();
+
+// 사용자가 프롬프트를 줄 때 의도 제출
+client.submitIntent('Google OAuth 로그인 구현');
+```
+
+---
+
+## 작동 원리
+
+### 1. 의도 제출
+
+개발자가 AI에게 작업을 요청하면:
+```
+사용자: "Google OAuth 로그인 추가해줘"
+```
+
+에이전트가 이 의도를 Intent Hub에 제출:
+```typescript
+client.submitIntent('Google OAuth 로그인 추가해줘');
+```
+
+### 2. 스마트 분석
+
+Intent Hub가 LLM을 사용해 의도 분석:
+```json
+{
+  "domain": "auth",
+  "subdomain": "oauth",
+  "affectedFiles": ["src/auth/oauth.ts", "src/auth/providers/google.ts"],
+  "semanticTags": ["login", "oauth", "google", "authentication"],
+  "estimatedScope": "medium"
+}
+```
+
+### 3. 충돌 감지
+
+시스템이 시맨틱 충돌 확인:
+
+| 시나리오 | 결과 |
+|----------|------|
+| 겹침 없음 | **승인** - 즉시 진행 |
+| 같은 도메인, 다른 서브도메인 | **경고** - 주의하며 진행 가능 |
+| 같은 도메인, 같은 서브도메인 | **차단** 또는 **협상** |
+
+### 4. 해결
+
+**자동 승인:**
+```
+앨리스: auth/oauth  ✓
+캐롤: payment       ✓  (다른 도메인)
+```
+
+**차단:**
+```
+앨리스: auth/oauth  ✓
+밥: auth/session    ⚠️  (같은 도메인 - 앨리스 완료까지 대기)
+```
+
+**협상 (활성화 시):**
+```
+앨리스: auth/oauth
+밥: auth/session
+→ LLM들이 논의 후 제안: "앨리스가 OAuth 먼저, 밥은 이후에 세션 작업"
+→ 양쪽 사용자에게 계획 알림
+```
+
+---
+
+## 시맨틱 도메인
+
+Intent Hub는 작업을 자동으로 시맨틱 도메인으로 분류합니다:
+
+| 도메인 | 트리거 |
+|--------|--------|
+| `auth` | `/auth/`, `login`, `oauth`, `session`, `jwt` |
+| `user` | `/user/`, `profile`, `account` |
+| `payment` | `/payment/`, `checkout`, `stripe`, `billing` |
+| `api` | `/api/`, `route`, `endpoint` |
+| `ui` | `.tsx`, `.jsx`, `/component` |
+| `database` | `/db/`, `migration`, `schema` |
+| `config` | `config`, `.env` |
+| `test` | `.test.`, `.spec.`, `/test/` |
+
+프로젝트 구조에 따라 커스텀 도메인 설정 가능합니다.
+
+---
+
+## 설정
+
+### 허브 서버 설정
+
+```typescript
+interface SmartHubServerOptions {
+  port: number;                    // WebSocket 포트
+  host?: string;                   // 바인딩 주소 (기본값: 0.0.0.0)
+  llmProvider: LLMProvider;        // OpenAI, Anthropic, 또는 Mock
+  orchestratorConfig?: {
+    useLLMAnalysis?: boolean;      // 의도 분석에 LLM 사용
+    autoNegotiate?: boolean;       // 충돌 자동 협상
+    conflictThreshold?: 'low' | 'medium' | 'high';
+  };
+}
+```
+
+### 에이전트 설정
+
+```typescript
+interface IntentHubHooksConfig {
+  hubUrl: string;                  // 허브 WebSocket URL
+  userId: string;                  // 고유 사용자 식별자
+  username: string;                // 표시 이름
+  projectPath: string;             // 프로젝트 루트 경로
+  autoConnect?: boolean;           // 생성 시 자동 연결 (기본값: true)
+  onNotification?: (event: string, data: unknown) => void;
+}
+```
+
+---
+
+## 로드맵
+
+- [x] **MVP 1**: 기본 도메인 잠금
+- [x] **MVP 2**: LLM 기반 의도 분석 & 협상
+- [x] **MVP 3**: OpenCode 통합 훅
+- [ ] **MVP 4**: 팀 가시성 웹 대시보드
+- [ ] **MVP 5**: 히스토리 & 분석
+- [ ] **MVP 6**: VS Code 확장
+
+---
+
+## 기여하기
+
+1. 저장소 포크
+2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`)
+3. 변경사항 커밋 (`git commit -m 'Add amazing feature'`)
+4. 브랜치에 푸시 (`git push origin feature/amazing-feature`)
+5. Pull Request 열기
+
+## 라이선스
+
+MIT License - 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
+
+---
+
+Intent Hub 팀이 사랑을 담아 만들었습니다. AI 협업이 인간 협업만큼 (혹은 더) 매끄러워야 하니까요.