zeta4lab-code

터미널에서 실행하는 AI 코딩 에이전트 (TypeScript)

개요

zeta4lab-code는 Qwen Code를 기반으로 zeta4lab 제품 방향에 맞게 브랜딩, CLI 명령, 한국어 UI, 모델 설정, 개발 워크플로를 정리한 코딩 에이전트입니다. 실행 명령은 z4code입니다.

주요 특징

• 터미널 중심 워크플로: 대화형 TUI와 -p/--prompt 기반 비대화형 실행
• 다중 모델 프로바이더: OpenAI 호환 API, Anthropic, Google Gemini, Alibaba Cloud Coding Plan 등 지원
• 개발 도구 통합: 파일 편집, 셸 실행, Git 작업, MCP 서버, 확장, 훅 지원
• 세션 재개: 이전 대화 이어가기와 세션 요약 기반 재개 지원
• IDE 보조 도구: VS Code companion 패키지 포함
• SDK/채널 패키지: TypeScript, Python, Java SDK와 Telegram, Weixin, DingTalk, Feishu 채널 패키지 포함

설치

전제 조건

Node.js 22 이상이 필요합니다.

node --version

NPM

npm install -g @zeta4lab/zeta4lab-code

소스에서 실행

git clone https://github.com/zeta4lab/z4code.git
cd z4code
npm install
npm run build
npm run bundle
node dist/cli.js

빠른 시작

# 대화형 실행
z4code

# 단일 프롬프트 실행
z4code -p "이 프로젝트 구조를 요약해줘"

# 이전 세션 재개
z4code --resume

대화형 세션 안에서는 다음 명령을 주로 사용합니다.

/help
/auth
/model
/mcp
/extensions
/doctor

인증과 모델 설정

대화형 세션에서 /auth를 실행해 인증 방식을 설정할 수 있습니다.

지원하는 주요 방식:

• API Key: OpenAI 호환 API, Anthropic, Gemini, OpenRouter, ModelScope, 자체 호스팅 엔드포인트 등
• Alibaba Cloud Coding Plan: Coding Plan 전용 엔드포인트와 API 키 사용

여러 모델을 자주 전환한다면 ~/.z4code/settings.json의 modelProviders에 프로바이더 목록을 정의하는 방식을 권장합니다.

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "env": {
    "DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus"
  }
}

주요 명령

| 명령 | 설명 | | ---------------------- | ---------------------- | | z4code | 대화형 CLI 실행 | | z4code -p "<prompt>" | 비대화형 프롬프트 실행 | | z4code --resume | 이전 세션 선택 후 재개 | | z4code --continue | 최근 세션 이어가기 | | z4code mcp | MCP 서버 관리 | | z4code extensions | 확장 관리 | | z4code serve | 로컬 HTTP daemon 실행 |

개발

npm install
npm run dev

npm run dev는 TypeScript 소스에서 CLI를 직접 실행합니다. packages/core와 packages/cli 변경은 별도 빌드 없이 반영됩니다.

빌드

npm run build
npm run bundle

npm run build는 각 패키지의 TypeScript를 dist/로 컴파일합니다. npm run bundle은 빌드 결과를 단일 dist/cli.js로 번들링합니다.

테스트

패키지별 Vitest 설정을 사용하므로 테스트는 해당 패키지 디렉토리에서 실행합니다.

cd packages/core && npx vitest run src/path/to/file.test.ts
cd packages/cli && npx vitest run src/path/to/file.test.ts

통합 테스트는 루트에서 실행합니다.

npm run test:integration:cli:sandbox:none
npm run test:integration:interactive:sandbox:none

검사

npm run format
npm run lint
npm run build
npm run typecheck

패키지 구조

| 패키지 | 설명 | | ------------------------------- | ------------------------------- | | packages/cli | z4code CLI와 TUI | | packages/core | 에이전트 코어, 모델, 도구, 설정 | | packages/sdk-typescript | TypeScript SDK | | packages/sdk-python | Python SDK | | packages/sdk-java | Java SDK | | packages/acp-bridge | ACP bridge 공통 모듈 | | packages/webui | 웹 UI 패키지 | | packages/web-templates | 웹 템플릿 패키지 | | packages/vscode-ide-companion | VS Code companion | | packages/zed-extension | Zed extension | | packages/channels/* | 외부 채널 연동 패키지 |

Upstream 정책

zeta4lab-code는 QwenLM/qwen-code의 단순 동기화 fork가 아니라 zeta4lab 제품 기준 저장소입니다. upstream 변경은 전체 merge/rebase 대상이 아니라 필요한 수정만 선별해서 가져오는 참고 소스로 취급합니다.

자세한 기준은 upstream sync strategy를 참조하세요.

문서

| 문서 | 설명 | | ------------------------------------------------------------------------------------------ | ------------------------- | | docs/index.md | 사용자/개발자 문서 진입점 | | docs/users/configuration/auth.md | 인증 설정 | | docs/users/configuration/model-providers.md | 모델 프로바이더 설정 | | docs/plans/upstream-sync-strategy.md | upstream 선별 도입 정책 |

라이선스

Commercial License. 이 저장소의 소스 코드와 배포물은 별도 서면 계약 또는 제타포랩(zeta4lab)이 명시적으로 부여한 허가 없이 복제, 수정, 배포, 재판매, SaaS 제공, 상업적 이용을 할 수 없습니다.

자세한 조건은 LICENSE를 확인하세요.

연락처

• 개인사업자명: 제타포랩(zeta4lab)
• 사업자번호: 570-35-01460
• 이메일: [email protected]
• 웹사이트: https://zeta4.net
• 실험/데모: https://exp.zeta4.net
• GitHub: zeta4lab/z4code