@didim365/agent-cli-core 0.1.0

package/dist/docs/change_model/model_command_multi_provider_plan.md

@@ -0,0 +1,221 @@
+# /model 멀티 프로바이더 확장 기능 변경 계획서
+
+- 작성일: 2026-02-09
+- 대상: `didim` CLI (`@didim365/agent-cli`, `@didim365/agent-cli-core`)
+- 목적: `/model` 명령을 Gemini 전용에서 Claude/OpenAI 등 멀티 프로바이더
+  환경에서도 실사용 가능하도록 확장
+
+## 1. 배경
+
+현재 `/model` 명령은 존재하지만, 모델 선택 UI가 Gemini 모델 목록 중심으로
+구성되어 있어 Claude/OpenAI 사용 시 모델 전환 UX가 일관되지 않다.
+
+현행 코드 기준:
+
+- `/model` 명령 진입: `packages/cli/src/ui/commands/modelCommand.ts`
+- 모델 다이얼로그 UI: `packages/cli/src/ui/components/ModelDialog.tsx`
+- 프로바이더 선택: `LLM_PROVIDER` + `ENABLE_MULTI_PROVIDER`
+  (`packages/core/src/providers/providerSelector.ts`,
+  `packages/core/src/providers/gemini/featureFlag.ts`)
+- 모델 반영: `config.setModel()` (`packages/core/src/config/config.ts`)
+
+즉, 런타임 자체는 멀티 프로바이더 경로를 가지고 있으나, `/model`의 선택
+UX/검증/안내가 Gemini 편향 상태다.
+
+## 2. 목표
+
+1. `/model` 명령으로 현재 활성 프로바이더에 맞는 모델 목록을 선택할 수 있다.
+2. Claude/OpenAI 등 비-Gemini 프로바이더에서도 `/model` 변경이 즉시 반영된다.
+3. 환경변수 기반 프로바이더 선택(`LLM_PROVIDER`)과 충돌 없이 동작한다.
+4. 기존 Gemini UX(자동/수동/프리뷰) 회귀를 방지한다.
+
+## 3. 비목표
+
+1. 이번 범위에서 `--provider` CLI 옵션 신규 추가는 제외한다.
+2. 원격 모델 카탈로그를 실시간 조회하는 기능은 제외한다.
+3. Provider별 고급 파라미터(temperature preset, reasoning budget 등) 편집은
+   제외한다.
+
+## 4. 요구사항 정의
+
+### 4.1 기능 요구사항
+
+- `/model` 실행 시 현재 provider 컨텍스트를 인지한다.
+- provider별 모델 목록을 UI에 표시한다.
+- 모델 선택 시 `config.setModel()`을 통해 세션 모델을 갱신한다.
+- `Remember model` 동작(영구 저장/임시 저장)을 provider 독립적으로 유지한다.
+
+### 4.2 UX 요구사항
+
+- 다이얼로그 상단에 현재 provider를 명시한다. (예: `Provider: Claude`)
+- provider별 모델 목록 출처/제약을 안내한다. (예: "환경/배포에 따라 일부 모델은
+  실패 가능")
+- 모델이 비어있거나 설정이 불완전할 경우 명확한 에러 문구를 보여준다.
+
+### 4.3 호환성 요구사항
+
+- `ENABLE_MULTI_PROVIDER=false`에서는 기존 Gemini 중심 동작을 유지한다.
+- `ENABLE_MULTI_PROVIDER=true` + `LLM_PROVIDER=claude/openai/...`에서 provider
+  맞춤 목록으로 전환한다.
+
+## 5. 설계 방향
+
+## 5.1 핵심 설계 원칙
+
+1. **Provider 결정은 Core 정책 재사용**: CLI에서 provider를 임의 판단하지 않고
+   `selectProvider()` 결과를 우선 활용.
+2. **ModelDialog는 표시/선택에 집중**: provider 판별, 후보 모델 조립은 별도
+   유틸/서비스로 분리.
+3. **Gemini 특화 UX 보존**: Gemini는 기존 자동/수동/프리뷰 플로우를 유지, 타
+   provider는 단순 목록 선택 UX 우선.
+
+## 5.2 제안 컴포넌트 구조
+
+1. `ModelOptionService`(신규, CLI 레이어)
+
+- 입력: `config`, env(`ENABLE_MULTI_PROVIDER`, `LLM_PROVIDER`)
+- 출력: `ModelDialogViewModel`
+  - `providerName`
+  - `options[]`
+  - `selectedModel`
+  - `supportsAutoModel` 등
+
+2. `ModelDialog`(기존 확장)
+
+- `ModelOptionService` 결과를 렌더링
+- provider가 Gemini일 때 기존 main/manual 뷰 유지
+- provider가 비-Gemini일 때 provider 전용 단일 목록 뷰 표시
+
+3. provider별 기본 모델 목록 소스
+
+- 1차: 정적 카탈로그(코드 상수)로 시작
+- 2차(후속): 설정 파일/원격 조회 확장 가능하도록 인터페이스 유지
+
+## 5.3 모델 목록 소스(초기안)
+
+- Gemini: 기존 상수 재사용
+- Claude: Sonnet/Haiku 계열 기본값 제공
+- OpenAI: GPT 계열 기본값 제공
+- Didim/OpenAI-Compatible: 사용자가 설정 기반으로 커스텀 모델 입력 가능하도록
+  fallback 항목 제공
+
+## 6. 작업 절차
+
+## 6.1 사전작업
+
+1. 현행 `/model` 흐름 문서화
+
+- `modelCommand.ts -> ModelDialog.tsx -> config.setModel()` 흐름 재확인
+
+2. provider 선택 정책 고정
+
+- `selectProvider()` 우선순위(`LLM_PROVIDER > authType > key`)를 테스트 케이스로
+  명세
+
+3. 모델 카탈로그 초안 확정
+
+- provider별 기본 후보 모델 문자열 목록 확정
+
+## 6.2 본작업
+
+1. `ModelOptionService` 구현
+
+- provider 판별
+- provider별 옵션 구성
+- 현재 선택 모델 인덱스 계산
+
+2. `ModelDialog` 리팩터
+
+- Gemini 경로: 기존 UI 유지
+- Non-Gemini 경로: 공통 리스트 UI + provider 라벨
+- 저장 모드(`persistMode`) 동작 유지
+
+3. `/model` 설명/헬프 보강
+
+- Gemini 전용 표현을 provider-agnostic 문구로 수정
+
+4. 예외 처리 보강
+
+- provider 미설정/키 미설정/목록 없음 상태 메시지 추가
+
+## 6.3 사후작업
+
+1. 테스트 추가/보강
+2. 문서 반영 (`/model` 사용법, provider별 예시)
+3. 회귀 점검 (Gemini 기존 동작)
+
+## 7. 테스트 계획 (TDD)
+
+## 7.1 단위 테스트
+
+1. `ModelOptionService.test.ts`
+
+- `ENABLE_MULTI_PROVIDER=false` -> Gemini 옵션 반환
+- `ENABLE_MULTI_PROVIDER=true`, `LLM_PROVIDER=claude` -> Claude 옵션 반환
+- `LLM_PROVIDER=openai` -> OpenAI 옵션 반환
+- 미지원/비정상 상태 graceful fallback
+
+2. `ModelDialog.test.tsx`
+
+- provider별 렌더링 스냅샷
+- 선택 시 `config.setModel()` 호출 검증
+- `persistMode` 토글 시 `isTemporary` 인자 검증
+
+3. `modelCommand.test.ts`
+
+- `/model` 호출 시 dialog open 동작 유지
+
+## 7.2 통합 테스트
+
+- `useGeminiStream` 또는 AppContainer 경로에서 `/model` 선택 후 실제 요청 모델
+  반영 여부 검증
+- Claude/OpenAI provider mock으로 모델 전환 후 sendMessage 요청 모델값 확인
+
+## 7.3 수동 스모크
+
+1. Gemini 경로
+
+- `ENABLE_MULTI_PROVIDER=false` 상태에서 기존 `/model` UX 동일성 확인
+
+2. Claude 경로
+
+- `ENABLE_MULTI_PROVIDER=true LLM_PROVIDER=claude ANTHROPIC_API_KEY=...`
+- `/model`에서 Claude 모델 선택 후 프롬프트 요청 성공 확인
+
+3. OpenAI 경로
+
+- `ENABLE_MULTI_PROVIDER=true LLM_PROVIDER=openai OPENAI_API_KEY=...`
+- `/model`에서 OpenAI 모델 선택 후 프롬프트 요청 성공 확인
+
+## 8. 리스크 및 대응
+
+1. **리스크: Gemini UX 회귀**
+
+- 대응: Gemini 전용 뷰 경로를 유지하고 기존 테스트 스냅샷 보강
+
+2. **리스크: provider별 모델명 유효성 차이**
+
+- 대응: 실패 시 에러 메시지에 provider/model 명시, 추후 동적 카탈로그 확장 지점
+  확보
+
+3. **리스크: 설정 우선순위 혼선**
+
+- 대응: 문서에 `LLM_PROVIDER` 우선 정책 명시, `/model`에서 현재 provider 표시
+
+## 9. 완료 기준 (Definition of Done)
+
+1. `/model`이 Gemini/Claude/OpenAI 컨텍스트에서 각각 적절한 모델 목록을
+   표시한다.
+2. 선택된 모델이 실제 요청 경로에 반영된다.
+3. 기존 Gemini 모델 변경 흐름(자동/수동/프리뷰)이 회귀 없이 동작한다.
+4. 관련 테스트(단위+통합)가 통과한다.
+5. 사용자 문서에 provider별 `/model` 사용법이 추가된다.
+
+## 10. 산출물
+
+- 신규 문서: `docs/change_model/model_command_multi_provider_plan.md`
+- 예상 코드 변경 영역:
+  - `packages/cli/src/ui/components/ModelDialog.tsx`
+  - `packages/cli/src/ui/commands/modelCommand.ts`
+  - `packages/cli/src/ui/...` (신규 ModelOptionService 및 테스트)
+  - 필요 시 `packages/core/src/providers/providerSelector.ts` 연계 로직 참조

package/dist/docs/change_model/model_command_multi_provider_todolist.md

@@ -0,0 +1,206 @@
+# /model 멀티 프로바이더 확장 단계별 작업계획서
+
+- 작성일: 2026-02-09
+- 기준 설계서: `docs/change_model/model_command_multi_provider_plan.md`
+- 범위: `/model` 명령의 Gemini 전용 UX를 Claude/OpenAI 포함 멀티 프로바이더 UX로
+  확장
+
+## 0. 작업 원칙
+
+1. 기존 Gemini UX(자동/수동/프리뷰) 회귀 금지
+2. Provider 판별 로직은 Core 정책(`selectProvider`) 재사용
+3. 단계별 TDD: 테스트 선작성(RED) -> 구현(GREEN) -> 리팩터(REFACTOR)
+4. 플래그 오프(`ENABLE_MULTI_PROVIDER=false`) 경로는 완전 호환 유지
+
+## 1. 사전작업 (분석/고정)
+
+### 1.1 현행 흐름 고정
+
+- [ ] `/model` 호출 체인 재확인
+  - `packages/cli/src/ui/commands/modelCommand.ts`
+  - `packages/cli/src/ui/components/ModelDialog.tsx`
+  - `packages/core/src/config/config.ts` (`setModel`)
+- [ ] 멀티 프로바이더 활성 조건 고정
+  - `ENABLE_MULTI_PROVIDER=true`
+  - `LLM_PROVIDER=<provider>`
+
+완료 기준:
+
+- [ ] 현재 동작/제약사항이 문장으로 정리되어 리뷰 가능
+
+### 1.2 Provider/모델 후보 초안 확정
+
+- [ ] provider별 1차 모델 목록(정적 상수) 확정
+  - Gemini: 기존 상수 재사용
+  - Claude: 기본 Sonnet/Haiku 후보
+  - OpenAI: 기본 GPT 후보
+  - didim/openai-compatible: fallback(사용자 지정/기본값)
+- [ ] 모델명 실패 허용 정책 문구 확정(배포/권한 차이)
+
+완료 기준:
+
+- [ ] 코드 상수로 옮길 수 있는 목록이 확정됨
+
+## 2. 본작업 A - 도메인 로직 분리
+
+### 2.1 `ModelOptionService` 신규 추가
+
+대상(신규 제안):
+
+- `packages/cli/src/ui/services/modelOptionService.ts`
+- `packages/cli/src/ui/services/modelOptionService.test.ts`
+
+작업 항목:
+
+- [ ] `ModelDialogViewModel` 타입 정의
+  - `providerName`
+  - `selectedModel`
+  - `options[]`
+  - `mode` (gemini-main/manual or generic)
+- [ ] provider 판별 함수 구현
+  - `isMultiProviderEnabled()` + `selectProvider()` 기반
+- [ ] provider별 옵션 빌더 구현
+
+테스트(RED -> GREEN):
+
+- [ ] flag off -> Gemini 옵션
+- [ ] flag on + `LLM_PROVIDER=claude` -> Claude 옵션
+- [ ] flag on + `LLM_PROVIDER=openai` -> OpenAI 옵션
+- [ ] 비정상 상태 fallback 동작
+
+완료 기준:
+
+- [ ] 서비스 단독 테스트 통과
+- [ ] UI에서 재사용 가능한 순수 데이터 모델 반환
+
+## 3. 본작업 B - UI 확장
+
+### 3.1 `ModelDialog` 리팩터
+
+대상:
+
+- `packages/cli/src/ui/components/ModelDialog.tsx`
+- `packages/cli/src/ui/components/ModelDialog.test.tsx`
+
+작업 항목:
+
+- [ ] Gemini 경로: 기존 main/manual 2단 구조 유지
+- [ ] Non-Gemini 경로: provider 단일 목록 뷰 렌더링
+- [ ] 상단 provider 라벨 추가 (`Provider: Claude` 등)
+- [ ] 기존 `Remember model`/`Tab` 토글 동작 유지
+- [ ] 선택 시 `config.setModel(model, isTemporary)` 호출 유지
+
+테스트:
+
+- [ ] Gemini 기존 스냅샷 유지
+- [ ] Claude/OpenAI 렌더링 스냅샷 추가
+- [ ] 선택 이벤트 시 `setModel` 호출 인자 검증
+- [ ] persistMode true/false 분기 검증
+
+완료 기준:
+
+- [ ] UI 테스트 통과
+- [ ] Gemini 회귀 없음
+
+## 4. 본작업 C - 명령/문구/에러 처리 정리
+
+### 4.1 `/model` 명령 및 도움말 정리
+
+대상:
+
+- `packages/cli/src/ui/commands/modelCommand.ts`
+- `packages/cli/src/ui/constants/tips.ts`
+- 필요 시 `packages/cli/src/config/config.ts`의 안내 문구
+
+작업 항목:
+
+- [ ] Gemini 전용 표현을 provider-agnostic 문구로 변경
+- [ ] provider 미설정/키 누락 시 안내 메시지 개선
+
+테스트:
+
+- [ ] command 결과(`dialog: model`) 회귀 없음
+- [ ] 문구 스냅샷 업데이트
+
+완료 기준:
+
+- [ ] `/model` 관련 안내가 멀티 프로바이더 문맥과 일치
+
+## 5. 본작업 D - 통합 검증
+
+### 5.1 런타임 경로 검증
+
+통합 테스트/수동 스모크:
+
+- [ ] Gemini
+  - `ENABLE_MULTI_PROVIDER=false`
+  - `/model` 기존 동작 확인
+- [ ] Claude
+  - `ENABLE_MULTI_PROVIDER=true LLM_PROVIDER=claude ANTHROPIC_API_KEY=...`
+  - `/model`에서 Claude 모델 선택 후 요청 반영 확인
+- [ ] OpenAI
+  - `ENABLE_MULTI_PROVIDER=true LLM_PROVIDER=openai OPENAI_API_KEY=...`
+  - `/model`에서 OpenAI 모델 선택 후 요청 반영 확인
+
+권장 자동 검증 명령:
+
+- [ ] `npm test --workspace @didim365/agent-cli -- ModelDialog 관련 테스트`
+- [ ] `npm test --workspace @didim365/agent-cli-core -- providerSelector 관련 테스트`
+- [ ] `npm run typecheck --workspace @didim365/agent-cli`
+- [ ] `npm run typecheck --workspace @didim365/agent-cli-core`
+
+완료 기준:
+
+- [ ] 3개 provider 경로에서 `/model` 변경 반영 확인
+
+## 6. 사후작업 (문서/릴리즈 준비)
+
+### 6.1 문서 업데이트
+
+- [ ] 사용자 가이드에 `/model` 멀티 프로바이더 사용법 추가
+  - 실행 예시(Claude/OpenAI)
+  - 제한사항(모델 접근 권한/계정별 차이)
+- [ ] 본 작업결과서(working_history) 작성
+
+### 6.2 변경 요약/릴리즈 노트
+
+- [ ] 변경 파일 목록 정리
+- [ ] 마이그레이션 포인트 정리(없으면 명시)
+
+완료 기준:
+
+- [ ] 문서만 보고도 사용자가 `/model`로 provider별 모델 전환 가능
+
+## 7. 이슈 대응 체크리스트
+
+- [ ] `LLM_PROVIDER` 미설정인데 non-Gemini 기대하는 사용자 혼선
+- [ ] 모델 목록에 있으나 실제 호출 실패(권한/리전/계약)
+- [ ] Gemini preview 접근권한 로직과 non-Gemini 로직 충돌
+- [ ] 회귀: Footer/Tip 문구에서 "Gemini model" 고정 표현 누락 여부
+
+## 8. 단계 완료 게이트
+
+### Gate A (도메인 분리 완료)
+
+- [ ] `ModelOptionService` 테스트 통과
+
+### Gate B (UI 확장 완료)
+
+- [ ] `ModelDialog` 테스트 통과
+- [ ] Gemini 회귀 없음
+
+### Gate C (통합 완료)
+
+- [ ] Claude/OpenAI 스모크 통과
+- [ ] 타입체크/주요 테스트 통과
+
+### Gate D (문서 완료)
+
+- [ ] 사용 가이드/작업결과서 반영 완료
+
+## 9. 권장 커밋 단위
+
+1. `feat(cli): add model option service for multi-provider`
+2. `feat(cli): extend /model dialog for claude/openai`
+3. `test(cli): add provider-specific model dialog coverage`
+4. `docs: add /model multi-provider usage guide`