npm - @didim365/agent-cli-core - Versions diffs - 0.1.1 → 0.1.2 - Mend

@didim365/agent-cli-core 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1076) hide show

package/dist/docs/00_project/ai_adapter/04-integration-design.md DELETED Viewed

@@ -1,1934 +0,0 @@
-# 04. DidimAIStudio 연동 설계
-## 4.1 개요
-### 4.1.1 목적
-Gemini CLI의 Multi-LLM Provider Adapter 설계를 DidimAIStudio 솔루션과 연동하여
-다음 목표를 달성합니다:
-1.  **프로바이더 통합**: 두 시스템의 LLM 프로바이더 지원을 통합
-2.  **설정 공유**: 모델 설정 및 API 키를 일관되게 관리
-3.  **기능 재사용**: DidimAIStudio의 13+ 프로바이더 지원을 gemini-cli에서 활용
-4.  **양방향 통신**: CLI ↔ 서버 간 원활한 데이터 교환
-### 4.1.2 DidimAIStudio 솔루션 구조
-> **소스코드 경로**: `/DidimAIStudio` **인프라 구성**:
-> `/DidimAIStudio/infra/compose/docker-compose.base.yml`
-DidimAIStudio는 마이크로서비스 아키텍처로 구성되어 있으며, Gemini CLI 연동에
-핵심적인 서비스는 다음과 같습니다:
-#### 핵심 서비스
-| 서비스               | 포트 | 역할                                      | 소스 경로                    |
-| -------------------- | ---- | ----------------------------------------- | ---------------------------- |
-| **scenario-gateway** | 8008 | API 게이트웨이, API-Key 인증, 요청 라우팅 | `/services/scenario-gateway` |
-| **agents**           | 8003 | LLM 실행 엔진, 시나리오/워크플로우 처리   | `/services/agents`           |
-#### 관련 서비스
-| 서비스        | 포트 | 역할               |
-| ------------- | ---- | ------------------ |
-| auth          | 8000 | 사용자 인증/인가   |
-| models        | 8001 | 모델 프로파일 관리 |
-| indexing      | 8002 | 문서 인덱싱/RAG    |
-| cloud-storage | 8006 | 파일 스토리지      |
-| mcp-tools     | 8007 | MCP 도구 서버      |
-### 4.1.3 시스템 비교
-| 구분           | Gemini CLI                  | DidimAIStudio                   |
-| -------------- | --------------------------- | ------------------------------- |
-| **역할**       | 클라이언트 CLI              | 서버 마이크로서비스             |
-| **언어**       | TypeScript                  | Python                          |
-| **프레임워크** | Node.js + Ink               | FastAPI + LangGraph             |
-| **프로바이더** | Gemini (+ 어댑터 확장 예정) | 13+ (OpenAI, Claude, Gemini 등) |
-| **스트리밍**   | AsyncGenerator              | SSE (Server-Sent Events)        |
-| **설정 저장**  | 환경변수 + 로컬 파일        | Database + 환경변수             |
-| **게이트웨이** | -                           | scenario-gateway (API-Key 인증) |
-### 4.1.4 연동 범위
-**In Scope (1차)**:
-- 공통 타입 시스템 정의
-- scenario-gateway를 통한 API 연동
-- 메시지 형식 변환
-- 프로바이더 설정 동기화
-- 토큰 사용량 추적 통합
-**Out of Scope (향후)**:
-- 실시간 양방향 동기화
-- 분산 트레이싱 통합
-- 공유 메모리 시스템
-## 4.2 연동 아키텍처
-### 4.2.1 전체 구조
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                              User                                        │
-└─────────────────────────────────┬───────────────────────────────────────┘
-                                  │
-                    ┌─────────────┴─────────────┐
-                    │                           │
-                    ▼                           ▼
-┌───────────────────────────────┐   ┌───────────────────────────────────┐
-│         Gemini CLI            │   │     DidimAIStudio Web App         │
-│       (Terminal Client)       │   │        (Browser Client)           │
-└───────────────┬───────────────┘   └─────────────────┬─────────────────┘
-                │                                     │
-                │                                     │
-                ▼                                     │
-┌───────────────────────────────────────────────────────────────────────┐
-│                         Integration Layer                              │
-│  ┌─────────────────────────────────────────────────────────────────┐  │
-│  │                    DidimAIStudioAdapter                          │  │
-│  │                    (gemini-cli 내부)                             │  │
-│  │                                                                  │  │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
-│  │  │   Request    │  │   Response   │  │   Stream     │           │  │
-│  │  │  Converter   │  │  Converter   │  │  Adapter     │           │  │
-│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
-│  └─────────────────────────────────────────────────────────────────┘  │
-└───────────────────────────────────┬───────────────────────────────────┘
-                                    │
-                                    │ HTTP/SSE
-                                    ▼
-┌───────────────────────────────────────────────────────────────────────┐
-│                 DidimAIStudio Solution (Microservices)                 │
-│                                                                        │
-│  ┌─────────────────────────────────────────────────────────────────┐  │
-│  │              scenario-gateway (Port 8008)                        │  │
-│  │              API-Key 인증 게이트웨이                              │  │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
-│  │  │  /invoke     │  │ /invoke/sse  │  │/invoke/sse/  │           │  │
-│  │  │  (REST)      │  │ (Streaming)  │  │  improved    │           │  │
-│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
-│  │            ↓              ↓              ↓                       │  │
-│  │  ┌─────────────────────────────────────────────────┐            │  │
-│  │  │ - API-Key 검증 (ApiKeyAuthMiddleware)           │            │  │
-│  │  │ - IP 검증, Rate Limiting                        │            │  │
-│  │  │ - x-thread-id 헤더 처리 (새 Thread vs 기존)     │            │  │
-│  │  │ - WebSocket Key (qa_id) 발급                    │            │  │
-│  │  └─────────────────────────────────────────────────┘            │  │
-│  └──────────────────────────────┬──────────────────────────────────┘  │
-│                                 │ HTTP/SSE                             │
-│                                 ▼                                      │
-│  ┌─────────────────────────────────────────────────────────────────┐  │
-│  │                  agents (Port 8003)                              │  │
-│  │                  LLM 실행 엔진                                    │  │
-│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │  │
-│  │  │ /v1/invoke   │  │/v1/invoke/sse│  │/v1/websocket │           │  │
-│  │  │              │  │ /improved    │  │   -keys      │           │  │
-│  │  └──────────────┘  └──────────────┘  └──────────────┘           │  │
-│  │                                    │                             │  │
-│  │  ┌─────────────────────────────────▼───────────────────────────┐│  │
-│  │  │                  LangGraph Runtime                           ││  │
-│  │  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐    ││  │
-│  │  │  │ OpenAI │ │ Claude │ │ Gemini │ │Bedrock │ │ vLLM   │... ││  │
-│  │  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘    ││  │
-│  │  └─────────────────────────────────────────────────────────────┘│  │
-│  └─────────────────────────────────────────────────────────────────┘  │
-└───────────────────────────────────────────────────────────────────────┘
-```
-### 4.2.2 서비스 간 통신 흐름
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                    요청 흐름 (Request Flow)                               │
-├──────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  ┌─────────────┐                                                        │
-│  │ Gemini CLI  │                                                        │
-│  │ (Request)   │                                                        │
-│  └──────┬──────┘                                                        │
-│         │                                                               │
-│         │ POST /api/v1/invoke/sse                                       │
-│         │ Headers: Authorization: Bearer <API-KEY>                       │
-│         │          x-thread-id: <thread-id> (optional)                  │
-│         │ Body: { "chat": "사용자 메시지" }                              │
-│         ▼                                                               │
-│  ┌─────────────────────────────────────────────────────────────────┐   │
-│  │              scenario-gateway (:8008)                            │   │
-│  │                                                                  │   │
-│  │  1. API-Key 검증 (ApiKeyAuthMiddleware)                         │   │
-│  │  2. passport_data 추출 (user_id, my_scenario_id)                │   │
-│  │  3. x-thread-id 헤더 확인:                                       │   │
-│  │     - 없음: 새 Thread + qa_id 생성 (POST /v1/websocket-keys)    │   │
-│  │     - 있음: 기존 Thread에 qa_id 발급 (/v1/websocket-keys/with-thread-id) │
-│  │  4. AgentsInvokeRequest 구성                                     │   │
-│  └──────────────────────────────┬──────────────────────────────────┘   │
-│                                 │                                       │
-│         POST http://agents:8003/v1/invoke/sse                          │
-│         Body: {                                                         │
-│           "scenario_my_page_id": 123,                                  │
-│           "user_id": "user-uuid",                                       │
-│           "thread_id": "thread-uuid",                                   │
-│           "qa_id": "qa-uuid",                                          │
-│           "message": "사용자 메시지",                                   │
-│           "attachments": null                                          │
-│         }                                                               │
-│                                 ▼                                       │
-│  ┌─────────────────────────────────────────────────────────────────┐   │
-│  │                    agents (:8003)                                │   │
-│  │                                                                  │   │
-│  │  1. 시나리오 조회 (scenario_my_page_id)                         │   │
-│  │  2. LangGraph 워크플로우 실행                                   │   │
-│  │  3. SSE 스트리밍 응답 생성                                      │   │
-│  └─────────────────────────────────────────────────────────────────┘   │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
-```
-### 4.2.3 연동 모드
-#### 모드 A: Direct Provider (기본)
-gemini-cli가 직접 LLM API를 호출합니다.
-```
-Gemini CLI ──► Provider Adapter ──► LLM API (OpenAI/Claude/Gemini)
-```
-**사용 시나리오**: 단독 CLI 사용, 빠른 응답 필요
-**설정**:
-```typescript
-// 환경변수 또는 config에서 설정
-LLM_PROVIDER=gemini  // gemini | claude | openai | vllm
-GEMINI_API_KEY=...
-```
-> ⚠️ **Direct 모드 구현 상태**: 현재 `03-technical-design.md`의 GeminiAdapter,
-> ClaudeAdapter, OpenAIAdapter 설계에 해당합니다. DidimAIStudioAdapter와는
-> 별개의 코드 경로입니다.
-#### 모드 B: Gateway Mode (DidimAIStudio 연동)
-gemini-cli가 DidimAIStudio를 통해 LLM API를 호출합니다.
-```
-Gemini CLI ──► DidimAIStudioAdapter ──► scenario-gateway ──► agents ──► LLM API
-```
-**사용 시나리오**:
-- DidimAIStudio의 고급 기능 활용 (에이전트 워크플로우, 메모리)
-- 중앙 집중식 API 키 관리
-- 사용량 추적 및 비용 관리
-**설정**:
-```typescript
-// 환경변수 또는 config에서 설정
-LLM_PROVIDER=didim
-DIDIM_BASE_URL=http://localhost:8008
-DIDIM_API_KEY=...
-```
-> ⚠️ **엔드포인트 선택 (M2 관련)**:
->
-> - `/api/v1/invoke/sse`: 기본 SSE 스트리밍
-> - `/api/v1/invoke/sse/improved`: LangGraph 세분화 SSE (권장)
->
-> 현재 어댑터는 **`/api/v1/invoke/sse/improved`를 사용**합니다.
-### 4.2.4 데이터 흐름
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                          Request Flow                                    │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  ┌─────────────┐     ┌─────────────────┐     ┌─────────────────────┐    │
-│  │ User Input  │────▶│ LlmGenerateReq  │────▶│ ScenarioSSERequestDTO│    │
-│  │ (CLI)       │     │ (gemini-cli)    │     │ (scenario-gateway)  │    │
-│  └─────────────┘     └─────────────────┘     └───────────┬─────────┘    │
-│                                                          │              │
-│                                                          ▼              │
-│                                              ┌─────────────────────┐    │
-│                                              │ AgentsInvokeRequest │    │
-│                                              │ (agents service)    │    │
-│                                              └───────────┬─────────┘    │
-│                                                          │              │
-│                                                          ▼              │
-│                                              ┌─────────────────────┐    │
-│                                              │ LangGraph Runtime   │    │
-│                                              │ Processing          │    │
-│                                              └─────────────────────┘    │
-│                                                          │              │
-├─────────────────────────────────────────────────────────────────────────┤
-│                          Response Flow                                   │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                          │              │
-│                                                          ▼              │
-│  ┌─────────────┐     ┌─────────────────┐     ┌─────────────────────┐    │
-│  │ CLI Output  │◀────│ LlmStreamEvent  │◀────│ SSE Events          │    │
-│  │ (Stream)    │     │ (gemini-cli)    │     │ (message_partial,   │    │
-│  └─────────────┘     └─────────────────┘     │ message_complete,   │    │
-│                                              │ done, error)        │    │
-│                                              └─────────────────────┘    │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-## 4.3 공통 타입 시스템
-### 4.3.1 DidimAIStudio 실제 DTO 구조
-> **소스 참조**: `/services/scenario-gateway/app/dto/agents_dto.py`
-#### scenario-gateway 입력 DTO
-```python
-# ScenarioSSERequestDTO - Gemini CLI → scenario-gateway
-class ScenarioSSERequestDTO(BaseModel):
-    chat: str  # 채팅 메시지 (1-10000자)
-```
-#### agents 서비스 요청 DTO
-```python
-# AgentsInvokeRequest - scenario-gateway → agents
-class AgentsInvokeRequest(BaseModel):
-    scenario_my_page_id: int      # 시나리오 마이페이지 ID
-    user_id: str                  # 사용자 ID
-    thread_id: str                # 대화 흐름 구분 ID
-    qa_id: str                    # 질문-응답 단위 ID
-    message: str                  # 사용자 메시지 (1-50000자)
-    attachments: Optional[List[str]]  # 첨부파일 URL 목록
-```
-#### agents 서비스 응답 DTO
-```python
-# AgentsInvokeResponse - agents → scenario-gateway
-class AgentsInvokeResponse(BaseModel):
-    qa_id: str                    # 질문-응답 단위 ID
-    message: Optional[str]        # 텍스트 응답
-    attachments: Optional[List[str]]  # 첨부파일 URL 목록
-    status: Optional[str]         # success|error|processing|timeout
-    error_code: Optional[str]     # 오류 코드
-```
-### 4.3.2 타입 매핑 테이블
-#### 메시지 타입
-| Gemini CLI             | DidimAIStudio             | 설명        |
-| ---------------------- | ------------------------- | ----------- |
-| `LlmMessage`           | `BaseMessage` (LangChain) | 기본 메시지 |
-| `LlmTextContent`       | `message: str`            | 텍스트 내용 |
-| `LlmImageContent`      | `attachments: List[str]`  | 이미지 URL  |
-| `LlmToolCallContent`   | `ToolCall` (LangGraph)    | 도구 호출   |
-| `LlmToolResultContent` | `ToolMessage` (LangGraph) | 도구 결과   |
-#### 요청/응답 타입
-| Gemini CLI            | DidimAIStudio (scenario-gateway) | DidimAIStudio (agents) | 비고                  |
-| --------------------- | -------------------------------- | ---------------------- | --------------------- |
-| `LlmGenerateRequest`  | `ScenarioSSERequestDTO`          | `AgentsInvokeRequest`  | ⚠️ chat 필드만 전달됨 |
-| `LlmGenerateResponse` | SSE `done` event                 | `AgentsInvokeResponse` |                       |
-| `LlmStreamEvent`      | SSE Events                       | SSE Events             |                       |
-| `LlmTokenUsage`       | `token_summary`                  | `total_tokens`         |                       |
-> ⚠️ **제한사항**:
->
-> - `LlmGenerateRequest`의 `messages[]`, `tools[]`, `systemInstruction`은 현재
->   gateway API로 전달 불가
-> - Multi-turn 컨텍스트는 서버 측 thread 관리에 의존
-#### SSE 이벤트 타입 매핑
-| Gemini CLI `LlmStreamEvent.type` | DidimAIStudio SSE Event | 설명           | 비고                |
-| -------------------------------- | ----------------------- | -------------- | ------------------- |
-| `content_delta`                  | `message`, `content`    | 텍스트 청크    |                     |
-| `content_delta`                  | `message_partial`       | 토큰 스트리밍  | improved SSE        |
-| `content_delta` (metadata)       | `message_metadata`      | 실행 컨텍스트  | improved SSE        |
-| `content_delta` (metadata)       | `process`               | 노드 진행 상황 | improved SSE        |
-| `message_end`                    | `done`                  | 응답 완료      | threadId, qaId 포함 |
-| `error`                          | `error`                 | 에러 발생      |                     |
-> ⚠️ **tool_call_delta 미지원**: 현재 gateway API는 tool 정보를 입/출력하지
-> 않으므로 `tool_call_delta` 이벤트는 발생하지 않습니다.
-#### 완료 상태 매핑
-| Gemini CLI `LlmStopReason` | DidimAIStudio SSE Event  |
-| -------------------------- | ------------------------ |
-| `end_turn`                 | `done` event             |
-| `max_tokens`               | `done` with truncation   |
-| `tool_use`                 | `process` (tool_start)   |
-| `content_filter`           | `error` (CONTENT_FILTER) |
-| `error`                    | `error` event            |
-### 4.3.3 공통 인터페이스 정의
-#### TypeScript (gemini-cli)
-```typescript
-// packages/core/src/providers/didim/types.ts
-/**
- * DidimAIStudio 연동을 위한 공통 타입
- * 실제 DidimAIStudio DTO 구조 기반
- */
-// scenario-gateway 입력 (POST /api/v1/invoke/sse)
-export interface ScenarioSSERequestDTO {
-  chat: string; // 채팅 메시지 (1-10000자)
-}
-// agents 서비스 요청 (내부 통신용, scenario-gateway → agents)
-export interface AgentsInvokeRequest {
-  scenario_my_page_id: number; // 시나리오 마이페이지 ID
-  user_id: string; // 사용자 ID
-  thread_id: string; // 대화 흐름 구분 ID
-  qa_id: string; // 질문-응답 단위 ID
-  message: string; // 사용자 메시지
-  attachments?: string[] | null; // 첨부파일 URL 목록
-}
-// agents 서비스 응답
-export interface AgentsInvokeResponse {
-  qa_id: string;
-  message?: string | null;
-  attachments?: string[] | null;
-  status?: 'success' | 'error' | 'processing' | 'timeout';
-  error_code?: string | null;
-}
-// WebSocket Key 생성 DTO
-export interface WebSocketKeyCreateDTO {
-  user_id: string;
-  scenario_my_page_id?: number;
-}
-// WebSocket Key 응답 DTO
-export interface WebSocketKeyResponseDTO {
-  id: number;
-  user_id: string;
-  scenario_my_page_id?: number;
-  thread_id: string; // 스레드 ID
-  qa_id: string; // QA ID
-  created_at: string;
-  updated_at: string;
-}
-// SSE 이벤트 타입
-export type DidimSSEEventType =
-  | 'message' // 기본 메시지 청크
-  | 'content' // 콘텐츠 청크
-  | 'message_partial' // 토큰 스트리밍 (improved)
-  | 'message_complete' // 메시지 완료 (improved)
-  | 'message_metadata' // 실행 컨텍스트 (improved)
-  | 'process' // 노드 진행 상황 (improved)
-  | 'done' // 응답 완료
-  | 'error'; // 에러
-// SSE 청크 데이터
-export interface SSEChatChunk {
-  chunk?: string;
-  scenario_id?: string;
-  thread_id?: string;
-}
-// SSE 완료 데이터
-export interface SSEDoneData {
-  message: string;
-  scenario_id: string;
-  thread_id: string;
-  qa_id: string;
-}
-// SSE 에러 데이터
-export interface SSEErrorData {
-  error: string;
-  error_code?: string;
-}
-// 채팅 응답 (비스트리밍)
-export interface ChatResponse {
-  response: string;
-  scenario_id: string;
-  thread_id: string;
-  timestamp: string;
-}
-```
-#### Python (DidimAIStudio) - 신규 연동 API용
-```python
-# services/agents/app/schemas/integration/gemini_cli.py
-from pydantic import BaseModel
-from typing import Optional, Union, List, Dict, Any
-from enum import Enum
-class LlmStopReason(str, Enum):
-    END_TURN = "end_turn"
-    MAX_TOKENS = "max_tokens"
-    STOP_SEQUENCE = "stop_sequence"
-    TOOL_USE = "tool_use"
-    CONTENT_FILTER = "content_filter"
-    ERROR = "error"
-class LlmTextContent(BaseModel):
-    type: str = "text"
-    text: str
-class LlmImageContent(BaseModel):
-    type: str = "image"
-    source: Dict[str, str]  # type, mediaType, data
-class LlmToolCallContent(BaseModel):
-    type: str = "tool_call"
-    id: str
-    name: str
-    arguments: Dict[str, Any]
-class LlmMessage(BaseModel):
-    role: str  # user, assistant, system, tool
-    content: List[Union[LlmTextContent, LlmImageContent, LlmToolCallContent]]
-    name: Optional[str] = None
-    tool_call_id: Optional[str] = None
-class LlmGenerateRequest(BaseModel):
-    """Gemini CLI 요청 형식"""
-    model: str
-    messages: List[LlmMessage]
-    system_instruction: Optional[str] = None
-    tools: Optional[List[Dict]] = None
-    tool_choice: Optional[str] = None
-    temperature: Optional[float] = None
-    max_tokens: Optional[int] = None
-    stop_sequences: Optional[List[str]] = None
-    top_p: Optional[float] = None
-    top_k: Optional[int] = None
-class LlmTokenUsage(BaseModel):
-    prompt_tokens: int
-    completion_tokens: int
-    total_tokens: int
-    cached_tokens: Optional[int] = None
-class LlmGenerateResponse(BaseModel):
-    """Gemini CLI 응답 형식"""
-    id: str
-    content: List[Union[LlmTextContent, LlmToolCallContent]]
-    model: str
-    stop_reason: LlmStopReason
-    usage: LlmTokenUsage
-    raw_response: Optional[Dict] = None
-```
-## 4.4 어댑터 구현
-### 4.4.1 DidimAIStudio 실제 API 엔드포인트
-> **소스 참조**:
->
-> - `/services/scenario-gateway/app/api/v1/endpoints/scenario_api.py`
-> - `/services/agents/app/api/v1/router.py`
-#### scenario-gateway 엔드포인트 (Port 8008)
-| 메서드 | 경로                          | 설명                      |
-| ------ | ----------------------------- | ------------------------- |
-| POST   | `/api/v1/invoke`              | 비스트리밍 채팅 요청      |
-| POST   | `/api/v1/invoke/sse`          | SSE 스트리밍 채팅         |
-| POST   | `/api/v1/invoke/sse/improved` | LangGraph 호환 세분화 SSE |
-| GET    | `/health`                     | 헬스 체크                 |
-| GET    | `/metrics`                    | Prometheus 메트릭         |
-#### agents 엔드포인트 (Port 8003) - 내부 통신
-| 메서드 | 경로                                | 설명                     |
-| ------ | ----------------------------------- | ------------------------ |
-| POST   | `/v1/invoke`                        | 비스트리밍 실행          |
-| POST   | `/v1/invoke/sse`                    | SSE 스트리밍 실행        |
-| POST   | `/v1/invoke/sse/improved`           | 세분화 SSE 스트리밍      |
-| POST   | `/v1/websocket-keys`                | 새 Thread + qa_id 생성   |
-| POST   | `/v1/websocket-keys/with-thread-id` | 기존 Thread에 qa_id 발급 |
-| POST   | `/v1/chats`                         | 채팅 종료 (토큰 집계)    |
-| GET    | `/v1/scenarios`                     | 시나리오 조회            |
-| GET    | `/v1/threads`                       | Thread 조회              |
-### 4.4.2 DidimAIStudio 어댑터 (gemini-cli)
-```typescript
-// packages/core/src/providers/didim/adapter.ts
-import { BaseAdapter, AdapterConfig } from '../baseAdapter';
-import {
-  LlmGenerateRequest,
-  LlmGenerateResponse,
-  LlmStream,
-  LlmStreamEvent,
-  ProviderCapabilities,
-} from '../types';
-import {
-  ScenarioSSERequestDTO,
-  ChatResponse,
-  SSEDoneData,
-  SSEErrorData,
-  DidimSSEEventType,
-} from './types';
-import { DidimTypeConverter } from './converter';
-export interface DidimAdapterConfig extends AdapterConfig {
-  baseUrl: string; // scenario-gateway URL (예: http://localhost:8008)
-  apiKey: string; // API Key (Bearer 토큰)
-  threadId?: string; // 기존 대화 스레드 ID (선택적)
-}
-export class DidimAIStudioAdapter extends BaseAdapter {
-  readonly providerName = 'didim-aistudio';
-  /**
-   * Capabilities - 실제 scenario-gateway API 지원 범위 기반
-   *
-   * ⚠️ 제한사항:
-   * - Tool/Attachment는 현재 ScenarioSSERequestDTO(chat만 수신)로 전달 불가
-   * - Embedding/TokenCount는 사후 추정값만 제공 (사전 API 없음)
-   * - System message는 시나리오 설정에 포함되어야 함 (요청 시 전달 불가)
-   */
-  readonly capabilities: ProviderCapabilities = {
-    supportsStreaming: true,
-    supportsToolCalls: false, // ⚠️ 현재 gateway API로 tool 정보 전달 불가
-    supportsImageInput: false, // ⚠️ attachments는 gateway 내부에서만 처리
-    supportsImageGeneration: false,
-    supportsEmbedding: false, // ⚠️ Didim API에 사전 embedding endpoint 없음
-    supportsTokenCount: false, // ⚠️ 사전 token count API 없음 (추정값만 가능)
-    supportsSystemMessage: false, // ⚠️ 시나리오 설정에 포함, 요청 시 전달 불가
-    maxContextLength: 200_000, // 시나리오에 설정된 모델에 따라 다름
-    maxOutputTokens: 32_768,
-  };
-  private converter: DidimTypeConverter;
-  private config: DidimAdapterConfig;
-  private currentThreadId?: string;
-  constructor(config: DidimAdapterConfig) {
-    super(config);
-    this.config = config;
-    this.converter = new DidimTypeConverter();
-    this.currentThreadId = config.threadId;
-  }
-  /**
-   * ⚠️ 알려진 제한사항 (H3):
-   * - ScenarioSSERequestDTO가 "chat" 필드만 받으므로, 마지막 사용자 메시지만 전송됨
-   * - 시스템 메시지, 이전 대화 히스토리, 도구 컨텍스트는 전달되지 않음
-   * - Multi-turn 품질은 DidimAIStudio 서버 측 thread 관리에 의존
-   *
-   * TODO: 전용 API 확장 시 LlmGenerateRequest 전체를 전달하도록 개선
-   */
-  async generateContent(
-    request: LlmGenerateRequest,
-    options?: GenerateOptions,
-  ): Promise<LlmGenerateResponse> {
-    // 마지막 사용자 메시지만 추출 (API 제약으로 인한 제한)
-    const chatMessage = this.converter.extractLastUserMessage(request);
-    const response = await fetch(`${this.config.baseUrl}/api/v1/invoke`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.config.apiKey}`,
-        ...(this.currentThreadId && { 'x-thread-id': this.currentThreadId }),
-      },
-      body: JSON.stringify({ chat: chatMessage }),
-      signal: options?.signal,
-    });
-    if (!response.ok) {
-      throw new Error(`Didim AI generation failed: ${response.statusText}`);
-    }
-    const data: ChatResponse = await response.json();
-    // thread_id 저장 (다음 요청에 사용)
-    this.currentThreadId = data.thread_id;
-    return this.converter.toChatResponseToLlm(data, request.model);
-  }
-  async generateContentStream(
-    request: LlmGenerateRequest,
-    options?: GenerateOptions,
-  ): Promise<LlmStream> {
-    this.validateRequest(request);
-    return this.createSSEStream(request, options);
-  }
-  async countTokens(request: LlmGenerateRequest): Promise<LlmTokenCount> {
-    // DidimAIStudio는 응답 시 토큰 정보 제공
-    // 사전 카운트는 추정값 사용
-    const text = this.converter.extractText(request);
-    return { totalTokens: Math.ceil(text.length / 4) };
-  }
-  private async *createSSEStream(
-    request: LlmGenerateRequest,
-    options?: GenerateOptions,
-  ): LlmStream {
-    const chatMessage = this.converter.extractLastUserMessage(request);
-    const response = await fetch(
-      `${this.config.baseUrl}/api/v1/invoke/sse/improved`,
-      {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${this.config.apiKey}`,
-          Accept: 'text/event-stream',
-          ...(this.currentThreadId && { 'x-thread-id': this.currentThreadId }),
-        },
-        body: JSON.stringify({ chat: chatMessage }),
-        signal: options?.signal,
-      },
-    );
-    if (!response.ok) {
-      throw new Error(`SSE connection failed: ${response.statusText}`);
-    }
-    const reader = response.body?.getReader();
-    if (!reader) {
-      throw new Error('No response body');
-    }
-    const decoder = new TextDecoder();
-    let buffer = '';
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        // 완전한 SSE 이벤트 추출 (\n\n로 구분)
-        while (buffer.includes('\n\n')) {
-          const eventEnd = buffer.indexOf('\n\n');
-          const completeEvent = buffer.substring(0, eventEnd);
-          buffer = buffer.substring(eventEnd + 2);
-          if (completeEvent.trim()) {
-            const event = this.parseSSEEvent(completeEvent);
-            if (event) {
-              // thread_id 저장
-              if (event.threadId) {
-                this.currentThreadId = event.threadId;
-              }
-              yield this.converter.toStreamEvent(event);
-            }
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-  /**
-   * SSE 이벤트 파싱 (M1 개선)
-   * - 다중 data: 라인 지원
-   * - event: 없는 기본 이벤트 처리
-   * - \r\n 및 \n 구분자 모두 처리
-   */
-  private parseSSEEvent(eventText: string): ParsedSSEEvent | null {
-    // \r\n과 \n 모두 지원
-    const lines = eventText.replace(/\r\n/g, '\n').split('\n');
-    let eventType: string | null = null;
-    const dataLines: string[] = [];
-    let eventId: string | null = null;
-    for (const line of lines) {
-      if (line.startsWith('event:')) {
-        eventType = line.substring(6).trim();
-      } else if (line.startsWith('data:')) {
-        // 다중 data: 라인 수집
-        dataLines.push(line.substring(5).trim());
-      } else if (line.startsWith('id:')) {
-        eventId = line.substring(3).trim();
-      }
-    }
-    // data 라인들을 줄바꿈으로 결합
-    const data = dataLines.join('\n');
-    // event: 없이 data:만 있는 SSE도 처리 (기본 이벤트)
-    if (!data) return null;
-    if (!eventType) eventType = 'message'; // 기본 이벤트 타입
-    try {
-      const parsed = JSON.parse(data);
-      return {
-        eventType,
-        data: parsed,
-        eventId,
-        // H1 수정: data에서 threadId 추출
-        threadId: parsed.thread_id || parsed.threadId,
-        qaId: parsed.qa_id || parsed.qaId,
-      };
-    } catch {
-      return { eventType, data: { chunk: data }, eventId };
-    }
-  }
-}
-interface ParsedSSEEvent {
-  eventType: string;
-  data: any;
-  eventId: string | null;
-  threadId?: string; // H1: data에서 추출된 threadId
-  qaId?: string; // data에서 추출된 qaId
-}
-```
-### 4.4.3 타입 변환기 (gemini-cli)
-```typescript
-// packages/core/src/providers/didim/converter.ts
-import {
-  LlmGenerateRequest,
-  LlmGenerateResponse,
-  LlmMessage,
-  LlmStreamEvent,
-  LlmStopReason,
-  LlmTextContent,
-  LlmTokenUsage,
-} from '../types';
-import {
-  ChatResponse,
-  SSEDoneData,
-  SSEErrorData,
-  DidimSSEEventType,
-} from './types';
-export class DidimTypeConverter {
-  /**
-   * 마지막 사용자 메시지 추출
-   */
-  extractLastUserMessage(request: LlmGenerateRequest): string {
-    const userMessages = request.messages.filter((m) => m.role === 'user');
-    if (userMessages.length === 0) return '';
-    const lastMessage = userMessages[userMessages.length - 1];
-    const texts = lastMessage.content
-      .filter((c): c is LlmTextContent => c.type === 'text')
-      .map((c) => c.text);
-    return texts.join('\n');
-  }
-  /**
-   * 전체 텍스트 추출 (토큰 카운트용)
-   */
-  extractText(request: LlmGenerateRequest): string {
-    const texts: string[] = [];
-    for (const message of request.messages) {
-      for (const content of message.content) {
-        if (content.type === 'text') {
-          texts.push((content as LlmTextContent).text);
-        }
-      }
-    }
-    return texts.join('\n');
-  }
-  /**
-   * 첨부 파일 URL 추출
-   */
-  extractAttachments(messages: LlmMessage[]): string[] {
-    const attachments: string[] = [];
-    for (const message of messages) {
-      for (const content of message.content) {
-        if (content.type === 'image' && content.source?.type === 'url') {
-          attachments.push(content.source.data);
-        }
-      }
-    }
-    return attachments;
-  }
-  /**
-   * ChatResponse → LlmGenerateResponse 변환
-   */
-  toChatResponseToLlm(
-    response: ChatResponse,
-    model: string,
-  ): LlmGenerateResponse {
-    return {
-      id: response.thread_id,
-      content: [{ type: 'text', text: response.response }],
-      model,
-      stopReason: 'end_turn' as LlmStopReason,
-      usage: {
-        promptTokens: 0,
-        completionTokens: 0,
-        totalTokens: 0,
-      },
-    };
-  }
-  /**
-   * SSE 이벤트 → LlmStreamEvent 변환
-   */
-  toStreamEvent(event: {
-    eventType: string;
-    data: any;
-    eventId: string | null;
-  }): LlmStreamEvent {
-    const { eventType, data } = event;
-    switch (eventType) {
-      case 'message':
-      case 'content':
-      case 'message_partial':
-        // 텍스트 청크
-        return {
-          type: 'content_delta',
-          delta: { text: data.chunk || data.message || '' },
-        };
-      case 'message_complete':
-        // 도구 완료 또는 메시지 완료
-        if (data.process_name) {
-          return {
-            type: 'tool_call_delta',
-            delta: {
-              toolCall: {
-                type: 'tool_call',
-                id: data.id || 'unknown',
-                name: data.process_name,
-                arguments: data.process_output || {},
-              },
-            },
-          };
-        }
-        return {
-          type: 'content_delta',
-          delta: { text: data.message || '' },
-        };
-      case 'message_metadata':
-        // 실행 컨텍스트 (improved SSE)
-        return {
-          type: 'content_delta',
-          delta: {},
-          metadata: {
-            langgraphNode: data.langgraph_node,
-            step: data.step,
-            model: data.model,
-          },
-        };
-      case 'process':
-        // 노드 진행 상황
-        return {
-          type: 'content_delta',
-          delta: {},
-          metadata: {
-            processName: data.process_name,
-            processType: data.process_type,
-          },
-        };
-      case 'done':
-        // 응답 완료
-        const doneData = data as SSEDoneData;
-        return {
-          type: 'message_end',
-          usage: {
-            promptTokens: 0,
-            completionTokens: 0,
-            totalTokens: 0,
-          },
-          threadId: doneData.thread_id,
-          qaId: doneData.qa_id,
-        };
-      case 'error':
-        // 에러
-        const errorData = data as SSEErrorData;
-        return {
-          type: 'error',
-          error: {
-            type: errorData.error_code || 'unknown',
-            message: errorData.error,
-          },
-        };
-      default:
-        return {
-          type: 'content_delta',
-          delta: {},
-        };
-    }
-  }
-}
-```
-### 4.4.4 기존 API 활용 방안 (DidimAIStudio)
-> **핵심**: Gemini CLI는 scenario-gateway의 기존 API를 그대로 활용합니다. 별도의
-> `/gemini-cli` 전용 API를 만들지 않고, 기존 `/api/v1/invoke/sse` 엔드포인트를
-> 사용합니다.
-#### 기존 API 흐름 (scenario_api.py)
-```python
-# /services/scenario-gateway/app/api/v1/endpoints/scenario_api.py
-# 현재 구조:
-# POST /api/v1/invoke/sse
-#   1. API-Key 인증 (ApiKeyAuthMiddleware)
-#   2. passport_data에서 user_id, my_scenario_id 추출
-#   3. x-thread-id 헤더 확인 → WebSocket Key 생성/조회
-#   4. AgentsInvokeRequest 구성
-#   5. agents 서비스 호출 (http://agents:8003/v1/invoke/sse)
-#   6. SSE 스트리밍 응답 전달
-@router.post("/invoke/sse")
-async def scenario_request_sse(
-    request_data: ScenarioSSERequestDTO,  # { "chat": "메시지" }
-    request: Request,
-    x_thread_id: str = Header(None, alias="x-thread-id"),
-    x_dooray_info_key: str = Header(None, alias="x-dooray-info-key")
-):
-    # ... 기존 구현 활용
-```
-#### Gemini CLI 연동 시 추가 고려사항
-1. **API-Key 발급**: Gemini CLI 사용자에게 DidimAIStudio API-Key 발급
-2. **시나리오 매핑**: 사용자별 기본 시나리오 설정 또는 CLI에서 지정
-3. **응답 포맷**: 기존 SSE 응답을 그대로 사용하되, gemini-cli에서 파싱
-#### 옵션: Gemini CLI 전용 API (선택적 확장)
-```python
-# /services/scenario-gateway/app/api/v1/endpoints/gemini_cli_api.py (선택적)
-from fastapi import APIRouter, Depends, HTTPException
-from fastapi.responses import StreamingResponse
-from typing import AsyncGenerator
-import json
-from app.schemas.integration.gemini_cli import (
-    LlmGenerateRequest,
-    LlmGenerateResponse,
-    LlmStreamEvent,
-)
-from app.service.integration.gemini_cli_service import GeminiCLIService
-from app.core.auth import get_api_key_user
-router = APIRouter(prefix="/api/v1/gemini-cli", tags=["gemini-cli"])
-@router.post("/generate")
-async def generate_content(
-    request: LlmGenerateRequest,
-    current_user = Depends(get_api_key_user),
-    service: GeminiCLIService = Depends()
-) -> LlmGenerateResponse:
-    """
-    Gemini CLI 호환 콘텐츠 생성 API (비스트리밍)
-    LlmGenerateRequest 형식을 직접 받아 처리
-    """
-    return await service.generate(request, current_user)
-@router.post("/generate/stream")
-async def generate_content_stream(
-    request: LlmGenerateRequest,
-    current_user = Depends(get_api_key_user),
-    service: GeminiCLIService = Depends()
-) -> StreamingResponse:
-    """
-    Gemini CLI 호환 콘텐츠 생성 API (스트리밍)
-    LlmStreamEvent 형식으로 응답
-    """
-    async def event_generator() -> AsyncGenerator[str, None]:
-        async for event in service.generate_stream(request, current_user):
-            yield f"data: {json.dumps(event.dict())}\n\n"
-        yield "data: [DONE]\n\n"
-    return StreamingResponse(
-        event_generator(),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-        }
-    )
-```
-### 4.4.5 연동 서비스 (DidimAIStudio - 선택적 확장용)
-```python
-# /services/scenario-gateway/app/service/integration/gemini_cli_service.py
-from typing import AsyncGenerator
-import uuid
-import httpx
-import json
-from app.schemas.integration.gemini_cli import (
-    LlmGenerateRequest,
-    LlmGenerateResponse,
-    LlmStreamEvent,
-    LlmTokenUsage,
-    LlmTextContent,
-    LlmStopReason,
-)
-from app.dto.agents_dto import AgentsInvokeRequest, AgentsInvokeResponse
-from app.service.integration.gemini_cli_converter import GeminiCLIConverter
-# 내부 agents 서비스 URL
-AGENTS_URL_SSE = "http://agents:8003/v1/invoke/sse/improved"
-class GeminiCLIService:
-    def __init__(self, converter: GeminiCLIConverter):
-        self.converter = converter
-    async def generate(
-        self,
-        request: LlmGenerateRequest,
-        user
-    ) -> LlmGenerateResponse:
-        """비스트리밍 콘텐츠 생성"""
-        # 스트리밍으로 전체 응답 수집
-        full_content = ""
-        total_tokens = 0
-        async for event in self.generate_stream(request, user):
-            if event.type == "content_delta" and event.delta:
-                full_content += event.delta.get("text", "")
-            if event.usage:
-                total_tokens = event.usage.total_tokens
-        return LlmGenerateResponse(
-            id=str(uuid.uuid4()),
-            content=[LlmTextContent(type="text", text=full_content)],
-            model=request.model,
-            stop_reason=LlmStopReason.END_TURN,
-            usage=LlmTokenUsage(
-                prompt_tokens=0,
-                completion_tokens=0,
-                total_tokens=total_tokens
-            )
-        )
-    async def generate_stream(
-        self,
-        request: LlmGenerateRequest,
-        user
-    ) -> AsyncGenerator[LlmStreamEvent, None]:
-        """스트리밍 콘텐츠 생성"""
-        # Gemini CLI 요청 → AgentsInvokeRequest 변환
-        agents_request = self.converter.to_agents_request(request, user)
-        # agents 서비스 스트리밍 호출
-        async with httpx.AsyncClient(timeout=200.0) as client:
-            async with client.stream(
-                "POST",
-                AGENTS_URL_SSE,
-                json=agents_request.model_dump(),
-                headers={"Content-Type": "application/json"}
-            ) as response:
-                response.raise_for_status()
-                buffer = ""
-                async for chunk in response.aiter_bytes():
-                    buffer += chunk.decode('utf-8', errors='ignore')
-                    while '\n\n' in buffer:
-                        event_end = buffer.find('\n\n')
-                        complete_event = buffer[:event_end]
-                        buffer = buffer[event_end + 2:]
-                        if complete_event.strip():
-                            event = self._parse_sse_event(complete_event)
-                            if event:
-                                yield self.converter.to_stream_event(event)
-    async def count_tokens(
-        self,
-        request: LlmGenerateRequest,
-        user
-    ) -> int:
-        """토큰 수 계산"""
-        text = self.converter.extract_text(request)
-        return len(text) // 4
-    def _parse_sse_event(self, event_text: str) -> dict | None:
-        """SSE 이벤트 파싱"""
-        lines = event_text.split('\n')
-        event_type = None
-        data = None
-        for line in lines:
-            if line.startswith('event: '):
-                event_type = line[7:]
-            elif line.startswith('data: '):
-                try:
-                    data = json.loads(line[6:])
-                except json.JSONDecodeError:
-                    data = {"chunk": line[6:]}
-        if event_type and data:
-            return {"event_type": event_type, "data": data}
-        return None
-```
-### 4.4.6 변환기 (DidimAIStudio - 선택적 확장용)
-```python
-# /services/scenario-gateway/app/service/integration/gemini_cli_converter.py
-from typing import List, Dict, Any, Optional
-import uuid
-from app.schemas.integration.gemini_cli import (
-    LlmGenerateRequest,
-    LlmMessage,
-    LlmStreamEvent,
-    LlmStopReason,
-)
-from app.dto.agents_dto import AgentsInvokeRequest
-class GeminiCLIConverter:
-    """Gemini CLI ↔ DidimAIStudio 형식 변환"""
-    def to_agents_request(
-        self,
-        request: LlmGenerateRequest,
-        user
-    ) -> AgentsInvokeRequest:
-        """LlmGenerateRequest → AgentsInvokeRequest"""
-        # 마지막 사용자 메시지 추출
-        last_message = self._extract_last_user_message(request.messages)
-        # 첨부 파일 추출
-        attachments = self._extract_attachments(request.messages)
-        return AgentsInvokeRequest(
-            scenario_my_page_id=user.default_scenario_id,
-            user_id=str(user.id),
-            thread_id=str(uuid.uuid4()),
-            qa_id=str(uuid.uuid4()),
-            message=last_message,
-            attachments=attachments if attachments else None
-        )
-    def to_stream_event(self, event: dict) -> LlmStreamEvent:
-        """SSE 이벤트 → LlmStreamEvent"""
-        event_type = event.get("event_type")
-        data = event.get("data", {})
-        handlers = {
-            "message": self._handle_message,
-            "content": self._handle_message,
-            "message_partial": self._handle_partial,
-            "message_complete": self._handle_complete,
-            "message_metadata": self._handle_metadata,
-            "process": self._handle_process,
-            "done": self._handle_done,
-            "error": self._handle_error,
-        }
-        handler = handlers.get(event_type, self._handle_unknown)
-        return handler(data)
-    def extract_text(self, request: LlmGenerateRequest) -> str:
-        """요청에서 전체 텍스트 추출"""
-        texts = []
-        for message in request.messages:
-            for content in message.content:
-                if content.type == "text":
-                    texts.append(content.text)
-        return "\n".join(texts)
-    # === Private Methods ===
-    def _extract_last_user_message(
-        self,
-        messages: List[LlmMessage]
-    ) -> str:
-        """마지막 사용자 메시지 추출"""
-        user_messages = [m for m in messages if m.role == "user"]
-        if not user_messages:
-            return ""
-        last = user_messages[-1]
-        texts = [c.text for c in last.content if c.type == "text"]
-        return "\n".join(texts)
-    def _extract_attachments(
-        self,
-        messages: List[LlmMessage]
-    ) -> List[str]:
-        """이미지 URL 등 첨부 파일 추출"""
-        attachments = []
-        for message in messages:
-            for content in message.content:
-                if content.type == "image":
-                    if content.source.get("type") == "url":
-                        attachments.append(content.source["data"])
-        return attachments
-    def _handle_message(self, data: dict) -> LlmStreamEvent:
-        """message/content 이벤트 처리"""
-        chunk = data.get("chunk", data.get("message", ""))
-        return LlmStreamEvent(
-            type="content_delta",
-            delta={"text": str(chunk)}
-        )
-    def _handle_partial(self, data: dict) -> LlmStreamEvent:
-        """message_partial 이벤트 처리 (토큰 스트리밍)"""
-        return LlmStreamEvent(
-            type="content_delta",
-            delta={"text": data.get("message", "")}
-        )
-    def _handle_complete(self, data: dict) -> LlmStreamEvent:
-        """message_complete 이벤트 처리"""
-        if data.get("process_name"):
-            # 도구 완료
-            return LlmStreamEvent(
-                type="tool_call_delta",
-                delta={
-                    "toolCall": {
-                        "type": "tool_call",
-                        "id": str(uuid.uuid4()),
-                        "name": data.get("process_name", "unknown"),
-                        "arguments": {}
-                    }
-                }
-            )
-        return self._handle_message(data)
-    def _handle_metadata(self, data: dict) -> LlmStreamEvent:
-        """message_metadata 이벤트 처리"""
-        return LlmStreamEvent(
-            type="content_delta",
-            delta={},
-            metadata={
-                "langgraph_node": data.get("langgraph_node"),
-                "step": data.get("step"),
-                "model": data.get("model")
-            }
-        )
-    def _handle_process(self, data: dict) -> LlmStreamEvent:
-        """process 이벤트 처리"""
-        return LlmStreamEvent(
-            type="content_delta",
-            delta={},
-            metadata={
-                "process_name": data.get("process_name"),
-                "process_type": data.get("process_type")
-            }
-        )
-    def _handle_done(self, data: dict) -> LlmStreamEvent:
-        """done 이벤트 처리"""
-        return LlmStreamEvent(
-            type="message_end",
-            usage={
-                "promptTokens": 0,
-                "completionTokens": 0,
-                "totalTokens": data.get("total_tokens", 0)
-            },
-            thread_id=data.get("thread_id"),
-            qa_id=data.get("qa_id")
-        )
-    def _handle_error(self, data: dict) -> LlmStreamEvent:
-        """error 이벤트 처리"""
-        return LlmStreamEvent(
-            type="error",
-            error={
-                "type": data.get("error_code", "unknown"),
-                "message": data.get("error", "Unknown error")
-            }
-        )
-    def _handle_unknown(self, data: dict) -> LlmStreamEvent:
-        """알 수 없는 이벤트 처리"""
-        return LlmStreamEvent(type="content_delta", delta={})
-```
-## 4.5 설정 및 인증
-### 4.5.1 gemini-cli 설정
-```typescript
-// packages/core/src/providers/didim/config.ts
-export interface DidimIntegrationConfig {
-  enabled: boolean;
-  baseUrl: string; // scenario-gateway URL (예: http://localhost:8008)
-  apiKey: string; // DidimAIStudio API-Key (시나리오별 발급)
-  threadId?: string; // 기존 대화 스레드 ID (선택적)
-  // 선택적 설정
-  timeout?: number;
-  retries?: number;
-  // 모드 선택
-  mode: 'direct' | 'gateway'; // direct: 직접 API, gateway: DidimAI 경유
-}
-// 환경 변수
-// DIDIM_AI_ENABLED=true
-// DIDIM_AI_BASE_URL=http://scenario-gateway:8008  # 또는 외부 URL
-// DIDIM_AI_API_KEY=your-scenario-api-key         # 시나리오별 API-Key
-// DIDIM_AI_MODE=gateway
-```
-### 4.5.2 settings.json 확장
-```json
-{
-  "provider": {
-    "default": "gemini",
-    "gemini": { ... },
-    "claude": { ... },
-    "didim-aistudio": {
-      "enabled": true,
-      "baseUrl": "http://scenario-gateway:8008",
-      "apiKey": "${DIDIM_AI_API_KEY}",
-      "mode": "gateway"
-    }
-  }
-}
-```
-### 4.5.3 API-Key 기반 인증
-DidimAIStudio는 시나리오별 API-Key 인증을 사용합니다.
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                        API-Key 인증 흐름                                 │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  1. API-Key 발급                                                        │
-│     DidimAIStudio 웹 UI → 시나리오 설정 → API-Key 생성                  │
-│                                                                          │
-│  2. API-Key 구조 (JWT)                                                  │
-│     {                                                                    │
-│       "user_id": "user-uuid",                                           │
-│       "api_key_metadata": {                                             │
-│         "my_scenario_id": 123,                                          │
-│         ...                                                             │
-│       },                                                                │
-│       ...                                                               │
-│     }                                                                   │
-│                                                                          │
-│  3. 요청 시 헤더                                                        │
-│     Authorization: Bearer <API-KEY>                                     │
-│                                                                          │
-│  4. 인증 처리 (scenario-gateway)                                        │
-│     ApiKeyAuthMiddleware → passport_data 추출 → request.state 저장      │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-### 4.5.4 DidimAIStudio 환경 변수 (참고)
-```python
-# /services/scenario-gateway/app/config/environment.py
-class Settings(BaseSettings):
-    # 서비스 설정
-    app_name: str = "Scenario Gate Service"
-    app_version: str = "1.0.0"
-    host: str = "0.0.0.0"
-    port: int = 8008
-    # 환경
-    app_env: str = "development"  # development, production
-    debug: bool = True
-    # CORS
-    cors_allow_origins: List[str] = ["*"]
-    cors_allow_credentials: bool = True
-    cors_allow_methods: List[str] = ["*"]
-    cors_allow_headers: List[str] = ["*"]
-    # Redis
-    redis_url: str = "redis://cache:6379/0"
-    # 동기화 간격
-    stategraph_sync_interval: int = 60
-    ip_whitelist_sync_interval: int = 60
-```
-## 4.6 프로바이더 매핑
-### 4.6.1 프로바이더 ID 매핑
-```typescript
-// packages/core/src/providers/didim/providerMapping.ts
-/**
- * Gemini CLI 프로바이더 ID ↔ DidimAIStudio 프로바이더 ID 매핑
- */
-export const PROVIDER_MAPPING = {
-  // Gemini CLI → DidimAIStudio
-  gemini: 'google',
-  claude: 'anthropic',
-  openai: 'openai',
-  gpt: 'openai',
-  // DidimAIStudio 전용
-  bedrock: 'bedrock',
-  azure: 'azure_openai',
-  mistral: 'mistral',
-  groq: 'groq',
-  naver: 'naver',
-  vllm: 'vllm',
-  together: 'together',
-  cohere: 'cohere',
-  fireworks: 'fireworks',
-  huggingface: 'huggingface',
-};
-/**
- * 모델 이름에서 프로바이더 추론
- */
-export function detectProvider(modelName: string): string {
-  const name = modelName.toLowerCase();
-  if (name.includes('gpt-') || name.includes('o1-')) return 'openai';
-  if (name.includes('claude')) return 'anthropic';
-  if (name.includes('gemini')) return 'google';
-  if (name.includes('mistral')) return 'mistral';
-  if (name.includes('llama')) return 'meta';
-  if (name.includes('command')) return 'cohere';
-  return 'unknown';
-}
-```
-### 4.6.2 토큰 필드 매핑 통합
-```python
-# app/service/chat/provider_manager.py (확장)
-class ProviderManager:
-    TOKEN_FIELD_MAPPING = {
-        # 기존 매핑...
-        # Gemini CLI 호환 매핑 추가
-        "gemini_cli": {
-            "input": "usage.promptTokens",
-            "output": "usage.completionTokens",
-            "total": "usage.totalTokens"
-        }
-    }
-    def normalize_for_gemini_cli(self, usage: dict) -> dict:
-        """DidimAI 토큰 사용량을 Gemini CLI 형식으로 변환"""
-        return {
-            "promptTokens": usage.get("input_tokens", 0),
-            "completionTokens": usage.get("output_tokens", 0),
-            "totalTokens": usage.get("total_tokens", 0),
-        }
-```
-## 4.7 에러 처리
-### 4.7.1 에러 코드 매핑
-```typescript
-// packages/core/src/providers/didim/errorMapping.ts
-import { LlmError, LlmErrorType } from '../errors';
-/**
- * DidimAIStudio 에러 코드 → Gemini CLI 에러 타입 매핑
- */
-export const ERROR_CODE_MAPPING: Record<string, LlmErrorType> = {
-  AUTH_FAILED: LlmErrorType.AUTHENTICATION,
-  RATE_LIMITED: LlmErrorType.RATE_LIMIT,
-  MODEL_OVERLOADED: LlmErrorType.MODEL_OVERLOADED,
-  CONTEXT_TOO_LONG: LlmErrorType.CONTEXT_LENGTH_EXCEEDED,
-  CONTENT_FILTERED: LlmErrorType.CONTENT_FILTER,
-  TIMEOUT: LlmErrorType.TIMEOUT,
-  NETWORK_ERROR: LlmErrorType.NETWORK,
-  INVALID_REQUEST: LlmErrorType.INVALID_REQUEST,
-};
-export function mapDidimErrorToLlmError(
-  errorCode: string,
-  message: string,
-): LlmError {
-  const errorType = ERROR_CODE_MAPPING[errorCode] || LlmErrorType.UNKNOWN;
-  return new LlmError(errorType, message, 'didim-aistudio');
-}
-```
-### 4.7.2 폴백 전략
-```typescript
-// packages/core/src/providers/didim/fallback.ts
-export interface FallbackConfig {
-  enabled: boolean;
-  fallbackProvider: string; // 'gemini' | 'claude' | 'openai'
-  maxRetries: number;
-  retryableErrors: LlmErrorType[];
-}
-export const DEFAULT_FALLBACK_CONFIG: FallbackConfig = {
-  enabled: true,
-  fallbackProvider: 'gemini',
-  maxRetries: 2,
-  retryableErrors: [
-    LlmErrorType.RATE_LIMIT,
-    LlmErrorType.MODEL_OVERLOADED,
-    LlmErrorType.TIMEOUT,
-    LlmErrorType.NETWORK,
-  ],
-};
-```
-## 4.8 테스트 전략
-### 4.8.1 단위 테스트
-```typescript
-// packages/core/src/providers/didim/converter.test.ts
-import { describe, it, expect } from 'vitest';
-import { DidimTypeConverter } from './converter';
-describe('DidimTypeConverter', () => {
-  const converter = new DidimTypeConverter();
-  describe('toLlmToDidimInput', () => {
-    it('should convert text message correctly', () => {
-      const request: LlmGenerateRequest = {
-        model: 'gemini-2.5-pro',
-        messages: [
-          {
-            role: 'user',
-            content: [{ type: 'text', text: 'Hello' }],
-          },
-        ],
-      };
-      const result = converter.toLlmToDidimInput(request, {
-        scenarioMyPageId: 1,
-        userId: 'user-1',
-        threadId: 'thread-1',
-        qaId: 'qa-1',
-      });
-      expect(result.message).toBe('Hello');
-      expect(result.scenario_my_page_id).toBe(1);
-    });
-    it('should extract attachments from image content', () => {
-      const request: LlmGenerateRequest = {
-        model: 'gemini-2.5-pro',
-        messages: [
-          {
-            role: 'user',
-            content: [
-              { type: 'text', text: 'What is this?' },
-              {
-                type: 'image',
-                source: {
-                  type: 'url',
-                  mediaType: 'image/png',
-                  data: 'https://example.com/image.png',
-                },
-              },
-            ],
-          },
-        ],
-      };
-      const result = converter.toLlmToDidimInput(request, {
-        scenarioMyPageId: 1,
-        userId: 'user-1',
-        threadId: 'thread-1',
-        qaId: 'qa-1',
-      });
-      expect(result.attachments).toContain('https://example.com/image.png');
-    });
-  });
-  describe('fromDidimOutputToStreamEvent', () => {
-    it('should convert MESSAGE_PARTIAL to content_delta', () => {
-      const output: DidimSSEOutput = {
-        scenario_my_page_id: 1,
-        user_id: 'user-1',
-        thread_id: 'thread-1',
-        qa_id: 'qa-1',
-        status: 'MESSAGE_PARTIAL',
-        content: 'Hello',
-        delta: true,
-      };
-      const result = converter.fromDidimOutputToStreamEvent(output);
-      expect(result.type).toBe('content_delta');
-      expect(result.delta?.text).toBe('Hello');
-    });
-    it('should convert COMPLETE to message_end with usage', () => {
-      const output: DidimSSEOutput = {
-        scenario_my_page_id: 1,
-        user_id: 'user-1',
-        thread_id: 'thread-1',
-        qa_id: 'qa-1',
-        status: 'COMPLETE',
-        total_tokens: 150,
-      };
-      const result = converter.fromDidimOutputToStreamEvent(output);
-      expect(result.type).toBe('message_end');
-      expect(result.usage?.totalTokens).toBe(150);
-    });
-  });
-});
-```
-### 4.8.2 통합 테스트
-```typescript
-// packages/core/src/providers/didim/adapter.integration.test.ts
-import { describe, it, expect, beforeAll } from 'vitest';
-import { DidimAIStudioAdapter } from './adapter';
-describe('DidimAIStudioAdapter Integration', () => {
-  let adapter: DidimAIStudioAdapter;
-  beforeAll(() => {
-    // 테스트 환경 설정
-    adapter = new DidimAIStudioAdapter({
-      apiKey: process.env.DIDIM_AI_API_KEY || '',
-      baseUrl: process.env.DIDIM_AI_BASE_URL || 'http://localhost:8000',
-      scenarioMyPageId: 1,
-      userId: 'test-user',
-    });
-  });
-  it('should generate content via DidimAIStudio', async () => {
-    const request: LlmGenerateRequest = {
-      model: 'gpt-4',
-      messages: [
-        {
-          role: 'user',
-          content: [{ type: 'text', text: 'Say hello' }],
-        },
-      ],
-    };
-    const response = await adapter.generateContent(request);
-    expect(response.content).toBeDefined();
-    expect(response.content.length).toBeGreaterThan(0);
-  });
-  it('should stream content via DidimAIStudio', async () => {
-    const request: LlmGenerateRequest = {
-      model: 'gpt-4',
-      messages: [
-        {
-          role: 'user',
-          content: [{ type: 'text', text: 'Count from 1 to 5' }],
-        },
-      ],
-    };
-    const events: LlmStreamEvent[] = [];
-    const stream = await adapter.generateContentStream(request);
-    for await (const event of stream) {
-      events.push(event);
-    }
-    expect(events.length).toBeGreaterThan(0);
-    expect(events.some((e) => e.type === 'message_end')).toBe(true);
-  });
-});
-```
-## 4.9 구현 일정
-> **참고**: DidimAIStudio 연동은 Phase 3 (프로바이더 확장) 이후에 진행됩니다.
-> 전체 Multi-LLM 어댑터 리팩토링은 05-implementation-plan.md 참조
-### Phase 1: 기반 작업 (3일)
-| 작업                                              | 담당       | 일정  |
-| ------------------------------------------------- | ---------- | ----- |
-| DidimAIStudio API 분석 (scenario-gateway, agents) | gemini-cli | 0.5일 |
-| 공통 타입 정의 (TypeScript)                       | gemini-cli | 1일   |
-| 에러 매핑 정의                                    | gemini-cli | 0.5일 |
-| API-Key 발급 및 테스트 환경 구성                  | 공통       | 1일   |
-### Phase 2: 어댑터 구현 (5일)
-| 작업                               | 담당       | 일정  |
-| ---------------------------------- | ---------- | ----- |
-| DidimAIStudioAdapter 구현          | gemini-cli | 2일   |
-| DidimTypeConverter 구현 (SSE 파싱) | gemini-cli | 1.5일 |
-| SSE 스트리밍 테스트                | gemini-cli | 0.5일 |
-| 기존 API 호환성 검증               | 공통       | 1일   |
-### Phase 3: 테스트 및 통합 (4일)
-| 작업                                    | 담당       | 일정 |
-| --------------------------------------- | ---------- | ---- |
-| 단위 테스트 작성                        | gemini-cli | 1일  |
-| 통합 테스트 작성 (Docker 환경)          | 공통       | 1일  |
-| E2E 테스트 (scenario-gateway ↔ agents) | 공통       | 1일  |
-| 문서화 및 예제 작성                     | 공통       | 1일  |
-### 선택적 확장: Gemini CLI 전용 API (1주)
-| 작업                                   | 담당          | 일정 |
-| -------------------------------------- | ------------- | ---- |
-| `/api/v1/gemini-cli/*` 엔드포인트 추가 | DidimAIStudio | 2일  |
-| GeminiCLIService 구현                  | DidimAIStudio | 2일  |
-| 통합 테스트                            | 공통          | 1일  |
-### 총 예상 기간: 2주 (기본) ~ 3주 (전용 API 포함)
-## 4.10 향후 확장
-### 4.10.1 단기 확장 (1-2개월)
-1. **양방향 동기화**: 설정 변경 시 실시간 동기화
-2. **분산 트레이싱**: OpenTelemetry 기반 통합 트레이싱
-3. **공유 메모리**: 대화 히스토리 공유
-### 4.10.2 장기 확장 (3-6개월)
-1. **플러그인 시스템**: gemini-cli에서 DidimAI 에이전트 직접 호출
-2. **워크플로우 연동**: LangGraph 워크플로우를 CLI에서 실행
-3. **통합 대시보드**: 사용량, 비용, 성능 통합 모니터링
----
-## 4.11 서버 측 문맥 관리 및 제약사항 (리뷰 피드백 C 반영)
-### 4.11.1 문맥 관리 아키텍처 차이
-Gemini CLI(기본 모드)와 DidimAIStudio 연동 모드는 대화 문맥(히스토리) 관리
-방식이 근본적으로 다릅니다:
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                     문맥 관리 방식 비교                                    │
-├──────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  [기본 모드: 클라이언트 측 관리]                                          │
-│  ┌─────────────┐    전체 히스토리 전송    ┌──────────────┐               │
-│  │ Gemini CLI  │ ───────────────────────▶ │ LLM API      │               │
-│  │ (히스토리   │                          │ (Stateless)  │               │
-│  │  로컬 저장) │ ◀─────────────────────── │              │               │
-│  └─────────────┘    응답                  └──────────────┘               │
-│                                                                          │
-│  [Gateway 모드: 서버 측 관리]                                            │
-│  ┌─────────────┐   마지막 메시지만 전송   ┌──────────────┐               │
-│  │ Gemini CLI  │ ───────────────────────▶ │ DidimAI      │               │
-│  │ (로컬 사본) │   + thread_id 헤더       │ Studio       │               │
-│  │             │                          │ (thread에    │               │
-│  │             │ ◀─────────────────────── │  히스토리    │               │
-│  └─────────────┘    응답 + thread_id      │  서버 저장)  │               │
-│                                                                          │
-└──────────────────────────────────────────────────────────────────────────┘
-```
-### 4.11.2 알려진 제약사항
-> ⚠️ **중요**: 아래 제약사항들은 DidimAIStudio Gateway 모드 사용 시 적용됩니다.
-| 제약사항                 | 설명                                                            | 영향                                          |
-| ------------------------ | --------------------------------------------------------------- | --------------------------------------------- |
-| **단방향 동기화**        | CLI 로컬 히스토리 조작(삭제/수정)이 서버 thread에 반영되지 않음 | 로컬에서 대화 삭제해도 서버는 이전 문맥 유지  |
-| **히스토리 전송 불가**   | `extractLastUserMessage()`로 마지막 메시지만 전송               | 시스템 메시지, 이전 대화가 직접 전달되지 않음 |
-| **서버 의존적 문맥**     | Multi-turn 품질은 DidimAIStudio의 thread 관리에 의존            | 서버 측 thread 만료/삭제 시 문맥 손실 가능    |
-| **도구 컨텍스트 미전달** | `tools[]` 정보가 gateway API로 전달되지 않음                    | 시나리오에 사전 정의된 도구만 사용 가능       |
-### 4.11.3 UX 안내 메시지 설계 (권고사항 2 반영)
-DidimAIStudio 연동 시 사용자에게 서버 측 문맥 관리 특성을 인지시키기 위한 UX
-장치:
-```typescript
-// packages/cli/src/views/DidimModeIndicator.tsx
-const DIDIM_MODE_NOTICES = {
-  // 세션 시작 시 표시 (한 번만)
-  sessionStart: `
-    ℹ️  DidimAIStudio 모드로 연결되었습니다.
-    • 대화 히스토리는 서버에서 관리됩니다.
-    • 로컬에서 히스토리를 수정해도 서버에 반영되지 않습니다.
-  `,
-  // 새 thread 시작 시
-  newThread: (threadId: string) => `
-    🔗 새 대화 스레드가 시작되었습니다: ${threadId.substring(0, 8)}...
-  `,
-  // 기존 thread 연결 시
-  resumeThread: (threadId: string) => `
-    🔗 기존 대화를 이어갑니다: ${threadId.substring(0, 8)}...
-    (서버에 저장된 대화 문맥이 적용됩니다)
-  `,
-  // 로컬 히스토리 삭제 시도 시 경고
-  localDeleteWarning: `
-    ⚠️  로컬 히스토리만 삭제됩니다.
-    서버의 대화 기록은 유지되며, 다음 질문 시 이전 문맥이 적용될 수 있습니다.
-  `,
-};
-// 사용 예시
-function renderSessionStart(): React.ReactNode {
-  const { provider } = useProviderContext();
-  if (provider === 'didim') {
-    return (
-      <Box marginBottom={1}>
-        <Text color="cyan">{DIDIM_MODE_NOTICES.sessionStart}</Text>
-      </Box>
-    );
-  }
-  return null;
-}
-```
-### 4.11.4 향후 해결 방안 (Out of Scope)
-아래 항목들은 현재 설계 범위 외이며, 향후 확장으로 고려됩니다:
-1. **양방향 동기화 API**: CLI ↔ DidimAIStudio 간 히스토리 동기화 프로토콜
-2. **Thread 관리 CLI 명령어**: `gemini thread list`, `gemini thread delete <id>`
-3. **오프라인 모드 전환**: 서버 연결 불가 시 자동으로 기본 모드로 fallback