# 전역 설치
npm install -g fuxi-cli
# 이전의 tiangong-cli (업데이트가 중단되었으므로, 최신 fuxi-cli를 설치하세요)
...

# 저장소 클론
git clone https://github.com/chenjiamin/fuxi-cli.git
cd fuxi-cli
...

# 저장소 클론
git clone https://github.com/chenjiamin/fuxi-cli.git
cd fuxi-cli
...

# 프로덕션 이미지 구축 (코드와 의존성 모두 이미지에 포함)
docker build -f Dockerfile.prod -t fuxi-cli:latest .
# 이미지 실행 (코드 디렉터리 매핑 불필요, 이미지가 모든 내용을 포함함)
...

{
"useModelRouter": true, // 필수: 사용자 정의 모델 지원 활성화
"defaultModel": "qwen3-coder-flash", // 권장: 기본으로 사용되는 모델
...

{
"models": {
"deepseek-coder": {
...

{
"experimental": {"useModelRouter": true // 必须：与 config.json 配合启用自定义模型
...

# 模型切换
/model use qwen3-coder-flash
# 현재 모델 확인
...

# 대화형 생성 마법사 시작
/agents create -i
# 프롬프트에 따라 순차적으로 입력:
...

# 코드 리뷰 Agent 생성
/agents create code-review \
--title

- ✅ 순환 감지: A → B → A와 같은 순환 전이 방지
- ✅ 깊이 제한: 최대 전이 깊이 5단계
- ✅ 추적 메커니즘: 각 전이 체인에 고유한 correlation_id 부여

📚 **상세 문서**: 스마트 라우팅 시스템 | 에이전트 전이 시스템 | P2 기능 요약

다중 Agent 오케스트레이션 시스템으로, 미리 정의된 복잡한 실행 흐름을 지원하여 개발 효율성을 크게 향상시킵니다.

- 📋
**YAML 설정**: YAML 파일을 사용하여 워크플로우를 정의합니다 - 🔗
**순차 실행**: 단계별로 여러 Agent 작업을 순서대로 실행합니다 - ⚡
**병렬 실행**: 여러 Agent가 동시에 작동하여 시간을 절반으로 줄입니다 - 🎯
**조건부 실행**: `when` 표현식을 지원하여 실행 논리를 제어합니다 - 🔄
**오류 처리**: `continue`/`stop`/`retry` 전략 및 `min_success` 설정이 가능합니다 - 📊
**템플릿 변수**: 단계 간 데이터 전달 및 중첩 참조를 지원합니다 - 🏷️
**스마트 라우팅**: 트리거(trigger) 자동 매칭을 지원합니다

**병렬 실행의 장점**:

- ⚡
**속도 향상 50%**: 두 명의 검토자가 동시에 작업합니다 - 🎯
**다차원 분석**: 품질과 보안을 동시에 보장합니다 - 📊
**스마트 요약**: 전문 Agent가 중복 제거 및 문제 분류를 수행합니다 - 🔧
**원클릭 완료**: 검토, 요약, 수정까지 자동화됩니다

풍부한 변수 참조를 지원합니다:

**현재 상태**: ✅ 완료됨. WorkflowManager, WorkflowExecutor, CLI 통합, 병렬 실행, 전체 문서가 포함됩니다.

📚 **상세 문서**: Workflow 사용자 가이드 | 시스템 설계 | Workflow 개요

복잡한 작업을 체계적으로 처리할 수 있도록 '계획 후 실행'의 2단계 워크플로우를 구현했습니다.

- 🔒
**안전한 Plan 모드**: 읽기 전용(Read-only) 모드로, 분석만 하고 코드는 수정하지 않습니다 - 📋
**구조화된 계획**: 단계, 위험 평가, 테스트 전략을 포함합니다 - ✅
**스마트 종속성 검사**: 작업 간의 의존 관계를 자동으로 검증합니다 - ⚙️
**유연한 실행 모드**: 자동(auto_edit) 및 수동(default) 승인을 지원합니다 - 🚀
**일괄 실행**: `/todos execute-all` 명령어로 모든 작업을 한 번에 실행합니다.

모든 할 일 목록을 원클릭으로 실행하여 진행 상황을 추적할 수 있습니다.

**1. Plan 단계 (계획)**

**2. Todo 단계 (실행)**

| 모드 | 설명 | 적용 시나리오 |
|---|---|---|
`default` | 모든 작업에 확인이 필요함 | 핵심 비즈니스 로직, 데이터베이스 작업 |
`auto_edit` | 모든 작업을 자동으로 승인함 | UI 컴포넌트, 테스트 코드, 문서 |

- 🏗️
**기능 개발**: 먼저 아키텍처와 단계를 계획하고, 점진적으로 구현합니다 - 🔄
**코드 리팩토링**: 위험을 분석하고 안전한 리팩토링 단계를 수립합니다 - 📚
**코드베이스 학습**: Plan 모드를 사용하여 코드 구조를 분석합니다 - 💾
**데이터베이스 마이그레이션**: 상세한 마이그레이션 단계와 롤백 방안을 계획합니다.

**현재 상태**: ✅ 완료됨. Plan 모드, Todo 관리, 일괄 실행, 전체 문서가 포함됩니다.

GitHub Spec Kit에서 영감을 받은 구조화된 소프트웨어 개발 시스템으로, '의도 → 사양 → 방안 → 작업 → 구현' 과정을 재사용 및 검토 가능한 연결고리로 만듭니다.

- 🏛️
**Constitution 헌장**: 프로젝트 엔지니어링 원칙, 품질 표준, 아키텍처 가이드를 정의합니다 - 📋
**Specification 사양**: 비즈니스 요구사항을 문서화하며 WHAT과 WHY에 집중합니다 - 🏗️
**Technical Plan 기술 방안**: 기술 설계를 하며 다중 버전(v1, v2...)을 지원합니다 - ✅
**Task List 작업 목록**: 실행 가능한 작업을 정의하며 다중 변형(default, detailed...)을 지원합니다 - 🚀
**자동 실행**: 일괄 작업 실행, 종속성 분석, 진행 상황 추적 기능을 제공합니다.

# 1. 헌장 생성 (일회성)
/spec constitution --init
# 2. 비즈니스 사양 생성
...

- 🆕
**신규 기능 개발**: 완전한 요구사항 → 설계 → 구현 프로세스 - 🐛
**버그 수정**: 문제 사양화 및 체계적 해결 - 🔄
**코드 리팩토링**: 위험 평가, 안전한 리팩토링 - 📈
**아키텍처 업그레이드**: 다중 방안 비교 후 최적 선택

📚 **전체 단축키 목록**: 키보드 단축키 문서를 참조하세요.

- 🎭 Agents 사용자 가이드 - Agents 시스템 전체 사용 설명서
- 🚀 Agents 빠른 시작 - 5분 만에 숙달하는 가이드
- 🔄 Workflow 사용자 가이드 - Workflow 전체 사용 설명서
- 📋 Plan+Todo 사용자 매뉴얼 - Plan+Todo 전체 매뉴얼
- 📐 Spec 사양 주도 개발 - Spec-Driven Development 빠른 시작
- 🤖 새 모델 추가 방법 - 커스텀 모델 설정 가이드

- 📐 전체 아키텍처 설계 - 모든 기능의 설계 문서 인덱스
- 🎭 Agents 시스템 설계 - Agents 아키텍처 설계
- 🧭 지능형 라우팅 시스템 - 라우팅 기능 설계
- 🔄 Workflow 시스템 설계 - 워크플로우 아키텍처
- 📋 Plan+Todo 설계 - Plan+Todo 아키텍처 설계
- 📐 Spec 시스템 개요 - Spec-Driven Development 시스템 설계
- 🤖 모델 시스템 설계 - 범용 모델 지원 아키텍처

| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
`useModelRouter` | boolean | ✅ 필수 | 사용자 정의 모델 지원 활성화, 반드시 `true`여야 함 |
`defaultModel` | string | | 기본 모델 이름. `models` 내에 정의되어야 함 |
|
`models.<name>.provider` | string | ✅ 필수 | 제공사: `"openai"` (호환), `"gemini"`, `"claude"` |
`models.<name>.model` | string | ✅ 필수 | API 호출 시 실제 모델 이름 |
`models.<name>.apiKey` | string | | API 키 (환경 변수 사용 가능) |
`models.<name>.baseUrl` | string | ✅ 필수 | API 서버 주소 |
`metadata.providerName` | string | | 식별자: `"qwen"`, `"deepseek"` 등 |
|
`metadata.displayName` | string | ❌ 선택 | UI 표시 이름 |
`capabilities.maxOutputTokens` | number | | 최대 출력 토큰 수 |
`capabilities.supportsFunctionCalling` | boolean | | 도구 호출 지원 여부 (Qwen=true, DeepSeek=false) |
`capabilities.supportsMultimodal` | boolean | | 배열 형식 지원 여부 (Qwen=true, DeepSeek=false) |

| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
`experimental.useModelRouter` | boolean | ✅ 필수 | 반드시 설정해야 하며, config.json과 함께 사용자 정의 모델 사용을 위해 `true`로 설정해야 함 |
`security.auth.selectedType` | string | | 인증 유형: `"custom-model"` (사용자 정의 모델), `"api-key"` (Gemini) |
|
`model.name` | string | ❌ 선택 | 현재 모델. `/model use` 명령을 통해 자동 업데이트됨 |
`general.disableAutoUpdate` | boolean | ❌ 선택 | 자동 업데이트 비활성화 (권장: `true`) |
`mcpServers.<name>` | object | ❌ 선택 | MCP 서버 설정 (선택 사항) |
`trustedFolders` | array | ❌ 선택 | 신뢰하는 프로젝트 디렉토리 목록 |

**⚠️ 핵심 안내:**

`config.json`과 `settings.json`의 `useModelRouter` 모두 **반드시** `true`로 설정해야 합니다.

*   통이천문(通義千問)을 사용하려면
    `supportsFunctionCalling: true`를 설정해야 도구 기능을 사용할 수 있습니다. - DeepSeek은 반드시
    `supportsFunctionCalling: false`와 `supportsMultimodal: false`를 설정해야 합니다.
*   API 키는 환경 변수를 통해서도 제공 가능합니다:
    `QWEN_API_KEY`
    `DEEPSEEK_API_KEY`

`.gemini/agents/` 디렉토리를 생성하고 에이전트 파일을 추가하세요:

**코드 검토 에이전트** (`.gemini/agents/code_review.md`)

**디버깅 전문가 에이전트** (`.gemini/agents/debug_analyzer.md`)

`.gemini/settings.json`에서 라우팅을 구성하세요:

또는 환경 변수를 통해 설정할 수 있습니다:

Fuxi CLI는 Google Gemini CLI를 기반으로 개발되었으며, 기존 기능을 완벽하게 호환합니다. 저희는 강력한 성능을 유지하는 동시에, 국내 개발자들의 요구사항에 맞춰 다음과 같은 확장 기능을 추가했습니다:

| 확장 기능 | 원본 Gemini CLI | Fuxi CLI |
|---|---|---|
| 사용자 정의 모델 설정 | ❌ Gemini/OpenAI/Claude만 지원 | ✅ 임의의 OpenAI 호환 모델 지원 |
| ... | 
- ✅ Gemini CLI의 설정 파일 완벽 호환
- ✅ Gemini CLI의 명령어 완벽 호환
- ✅ Gemini CLI로 원활하게 전환 가능
- ✅ 동일한 `.gemini/` 설정 디렉토리 공유

두 프로젝트 모두 **Apache 2.0** 오픈소스 라이선스를 채택하여 자유롭게 사용하고 수정할 수 있습니다.

모든 형태의 기여를 환영합니다!

- 이 저장소 포크(Fork)
- 기능 브랜치 생성:
`git checkout -b feature/amazing-feature`

- 변경 사항 커밋:
`git commit -m 'Add amazing feature'`

- 브랜치 푸시:
`git push origin feature/amazing-feature`

- 풀 리퀘스트(Pull Request) 제출

본 프로젝트는 Apache License 2.0 오픈소스 라이선스를 채택했습니다.

Google Gemini CLI(Apache 2.0)를 기반으로 개발되었습니다.

- 우수한 기본 프레임워크를 제공해 주신 Google Gemini CLI 팀에 감사드립니다.
- 모든 기여자의 지원과 참여에 감사드립니다.
- 오픈소스 커뮤니티의 지속적인 추진에 감사드립니다.

**Fuxi CLI - AI 개발을 더욱 효율적으로 🚀**

이 프로젝트가 도움이 되었다면, 저희에게 별점(⭐️)을 부탁드립니다.