주요 콘텐츠로 건너뛰기
AI 튜토리얼

ZCode 개발 튜토리얼: 데스크톱, 웹 및 터미널 AI 코딩 워크스테이션 구축

이 튜토리얼에서는 ZCode 개발 환경을 구축하고 Electron 데스크톱 앱, 웹 워크스테이션 및 Agent CLI를 실행하는 방법을 소개합니다. 또한 원격 리소스, 액세스 인증 및 배포 패키지를 구성하는 방법도 안내합니다.

약 17분 소요
ZCode 개발 튜토리얼: 데스크톱, 웹 및 터미널 AI 코딩 워크스테이션 구축

ZCode 알아보기

ZCode 프로젝트 로고

ZCode는 Electron 데스크톱 앱, 브라우저 인터페이스, 터미널 Agent를 제공하는 AI 프로그래밍 워크벤치입니다. 저장소는 workspace 형식으로 구성되어 클라이언트, 백엔드 서비스, 공유 UI, Agent CLI, TUI 및 런타임 소스 코드를 통합 관리합니다.

프로젝트는 세 가지 주요 개발 진입점을 제공합니다.

  • Desktop: Electron 데스크톱 앱이며 pnpm dev:desktop으로 시작합니다.
  • Web: 브라우저 워크벤치와 로컬 백엔드를 동시에 시작하며 pnpm dev:web을 사용합니다.
  • Agent CLI: 터미널 Agent 또는 TUI를 직접 개발하며 pnpm --filter @zcode/cli dev를 사용합니다.

또한 ZCode는 통합 명령줄 배포 패키지로 빌드할 수 있습니다. 설치 후 zcode를 실행하면 TUI로 진입하고, zcode --web을 실행하면 로컬 Web 워크벤치를 시작합니다.

주요 기능

  • 데스크톱, 브라우저, 터미널의 세 가지 사용 방식을 제공합니다.
  • Web 프런트엔드, HTTP/WebSocket 백엔드와 Agent를 로컬에서 완전한 작업 흐름으로 구성할 수 있습니다.
  • Desktop과 Web은 Agent CLI 런타임을 공유합니다.
  • SSH, WSL 등의 원격 워크스페이스 개발을 지원합니다.
  • React 컴포넌트, hooks, Zustand 상태, 프로토콜 타입, RPC 프레임워크, Agent 클라이언트 SDK를 공유합니다.
  • 데스크톱 설치 패키지와 통합 ZCode 명령줄 배포 패키지를 각각 빌드할 수 있습니다.
  • Web을 외부에 노출할 때 액세스 토큰을 자동으로 생성하며, 인증 토큰을 명시적으로 구성할 수도 있습니다.

개발 환경 준비

필수 도구 설치

시작하기 전에 다음 도구를 준비하세요. 구체적인 버전은 저장소 루트의 mise.toml을 기준으로 합니다.

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

저장소를 클론하고 루트 디렉터리로 이동한 뒤 권장 초기화 명령을 실행합니다.

pnpm bootstrap

pnpm bootstrap은 workspace 의존성을 설치하고, 데스크톱 로컬 실행 리소스를 준비하며, build:bootstrap을 실행합니다. Agent CLI와 런타임은 이미 apps/zcode-cli/에 있으므로 Git submodule을 추가로 초기화할 필요가 없습니다.

기본 bootstrap은 원격 리소스 준비를 건너뛰므로 로컬 데스크톱 개발에 더 적합합니다. SSH, WSL 또는 원격 배포 리소스가 필요한 경우에만 원격 리소스 관련 명령을 실행하세요.

필요에 따른 초기화 명령 선택

  • pnpm install: 의존성만 설치합니다.
  • pnpm prepare:desktop-runtime: 데스크톱 런타임 리소스를 준비하며, 기본적으로 원격 리소스 준비도 포함합니다.
  • pnpm prepare:remote-assets: 원격 런타임 리소스만 별도로 준비합니다.
  • pnpm bootstrap:with-remote: 의존성, 로컬 및 원격 리소스를 초기화하고 관련 패키지를 순차적으로 빌드하지만, 데스크톱 애플리케이션 bundle은 건너뜁니다.
  • pnpm build: 각 workspace 패키지의 빌드 스크립트를 재귀적으로 실행하며, 패키지 내부 리소스 준비 단계도 포함합니다.

데스크톱 버전 실행

초기화를 완료한 후 저장소 루트에서 Electron 데스크톱 앱을 시작합니다.

pnpm dev:desktop

pnpm dev:desktop은 기본적으로 pnpm dev:desktop:prod와 같으며, 프로덕션 서비스 구성을 사용합니다. 시작 스크립트는 로컬 런타임 리소스를 준비하고 데스크톱 Agent를 빌드한 다음 Electron과 소스 코드 감시를 시작합니다.

테스트 환경을 사용하려면 다음을 실행하세요.

pnpm dev:desktop:test

개발 데이터 분리

개발 데이터가 일상적인 사용 데이터와 섞이지 않도록 ZCODE_DATA_BASE_DIR를 사용해 별도의 데이터 기본 디렉터리를 지정할 수 있습니다. 애플리케이션 데이터는 해당 디렉터리 아래의 .zcode/에 기록됩니다.

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

이 방식은 macOS와 Linux에서 사용할 수 있습니다.

Web 워크벤치 실행

Web 프런트엔드 또는 백엔드 소스 코드를 수정할 때는 통합 개발 모드를 권장합니다.

pnpm dev:web

이 명령은 다음을 동시에 시작합니다.

  • Web 개발 서버. 기본 주소는 http://localhost:5173입니다.
  • 로컬 백엔드. 기본 주소는 http://localhost:3030입니다.

브라우저에서는 프런트엔드 주소에 접속해야 합니다. 개발 서버는 /ws 및 일반적인 /api 요청을 로컬 백엔드로 프록시하며, /api/v1/oauth/token은 현재 구성된 제품 서비스로 별도 프록시합니다.

백엔드 워크스페이스 지정

macOS 또는 Linux에서는 환경 변수를 사용해 Web 백엔드가 사용할 프로젝트 디렉터리를 지정할 수 있습니다.

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Agent 소스 코드를 수정한 경우 CLI와 해당 workspace 의존성을 다시 빌드한 후 서비스를 재시작해야 합니다.

pnpm --filter @zcode/cli... build

Agent CLI와 TUI 개발

터미널 인터페이스 또는 Agent를 주로 개발한다면 소스 코드 진입점을 직접 실행할 수 있습니다.

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

CLI와 해당 의존성을 빌드한 후에는 생성된 CommonJS 파일을 직접 실행할 수도 있습니다.

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

이 소스 코드 진입점은 Agent CLI를 직접 실행하며, 통합 배포 명령의 --web 분기를 실행하지 않습니다. Web 개발에는 pnpm dev:web을 사용하고, 통합 zcode 명령을 테스트하려면 명령줄 배포 패키지를 빌드하고 압축을 해제해야 합니다.

ZCode 명령줄 버전 사용

명령줄 배포 패키지는 TUI, Web, 백엔드와 Agent를 하나로 구성하며 모두 zcode를 통해 시작합니다. Electron에는 의존하지 않지만, 런타임에는 여전히 mise.toml의 요구 사항을 충족하는 Node.js가 필요합니다.

기본 명령

# 터미널 대화형 인터페이스 진입
zcode

# Web 워크벤치 시작
zcode --web

# 프로젝트와 포트를 지정하고 브라우저 자동 열기 비활성화
zcode --web --workspace /path/to/project --port 3030 --no-open

# 도움말 보기
zcode --help
zcode --web --help

Web 모드는 기본적으로 현재 디렉터리를 작업 디렉터리로 사용하고, 127.0.0.1에서 수신하며, 사용 가능한 포트를 자동으로 선택하고 브라우저를 엽니다. 기본적으로 액세스 토큰은 활성화되지 않습니다. 사용을 마친 후 터미널에서 Ctrl+C를 눌러 서비스를 중지할 수 있습니다.

LAN에서 액세스

다른 장치에서 액세스하려면 수신 주소를 0.0.0.0으로 변경하세요.

zcode --web --host 0.0.0.0

로컬 호스트가 아닌 주소에서 수신할 때 ZCode는 기본적으로 액세스 토큰을 생성합니다. 터미널 출력에 표시된 토큰 포함 링크를 사용해 서비스에 접속해야 합니다. --token으로 토큰을 지정하거나 --no-token으로 토큰 인증을 비활성화할 수도 있습니다.

일반 Web 서비스의 HTTP 진입점을 직접 시작할 때는 ZCODE_SERVER_AUTH_TOKEN으로 API 및 WebSocket 인증을 구성할 수 있습니다. 프로그램 인터페이스를 통해 서비스를 생성할 때는 authToken 옵션을 사용합니다.

환경 변수 구성

저장소 루트의 .env.example에는 서비스 주소와 빌드 구성 예시가 제공됩니다. 필요에 따라 .env로 복사하고, 로컬에서만 사용할 재정의 항목은 .env.local에 넣을 수 있습니다.

  • ZCODE_DATA_BASE_DIR: 애플리케이션 데이터 기본 디렉터리입니다. 데이터는 그 아래의 .zcode/에 기록됩니다.
  • ZCODE_SERVER_WORKSPACE: Web 백엔드 워크스페이스 경로를 지정합니다.
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: 로컬 Provider 구성 파일을 지정합니다. 설정하지 않으면 내장 구성을 사용합니다.
  • ZCODE_DIST_BASE_URL: 명령줄 설치 스크립트가 사용하는 다운로드 기본 주소입니다.

이러한 런타임 변수는 시작 명령의 환경에 직접 지정할 수도 있습니다. Desktop 개발 서비스 구성은 dev:desktop:test 및 dev:desktop:prod로 선택합니다.

SSH 및 WSL 원격 기능 개발

원격 워크스페이스 기능을 개발하기 전에 원격 리소스를 준비합니다.

pnpm bootstrap:with-remote
pnpm dev:desktop

원격 프로젝트에 연결할 때 리소스는 “로컬에서 다운로드 후 업로드”로 선택하세요. 개발 환경은 로컬 packages/desktop/mock-cdn과 로컬 빌드 산출물에서 리소스를 가져온 다음 SFTP를 통해 원격 호스트에 업로드하며, CDN에는 액세스하지 않습니다.

데스크톱 설치 패키지 빌드

다음 명령으로 데스크톱 버전을 빌드합니다.

pnpm bundle:desktop

기본 대상은 macOS arm64이며 출력 디렉터리는 packages/desktop/dist/입니다. 운영 체제와 CPU 아키텍처를 지정할 수도 있습니다.

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os는 mac, win, linux를 지원하고, --arch는 x64와 arm64를 지원합니다. 실제 패키징과 서명에는 대상 플랫폼에 해당하는 도구와 구성이 필요합니다.

macOS에서는 생성된 DMG를 열고 ZCode를 “응용 프로그램”으로 드래그하세요. 로컬에서 서명하지 않은 빌드가 처음 실행될 때 시스템에서 차단되면 다음을 실행할 수 있습니다.

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

명령줄 배포 패키지 빌드

명령줄 배포 패키지의 빌드 진입점은 pnpm build:zcode입니다. 빌드 전에 다운로드 기본 주소 ZCODE_DIST_BASE_URL을 설정해야 하며, --base-url을 통해 직접 전달할 수도 있습니다.

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# ZCODE_DIST_BASE_URL이 이미 설정된 경우
pnpm build:zcode

# 기존 빌드 결과를 재사용하고 다시 패키징만 수행
pnpm build:zcode --skip-build

# 선택 가능한 인자 확인
pnpm build:zcode --help

여기의 다운로드 주소는 자리 표시자 예시일 뿐이며, 정식 배포 시 실제 호스팅 주소로 교체해야 합니다. 빌드 스크립트는 CLI/TUI, 백엔드, Web을 차례로 처리하고 네이티브 라이브러리, worker 및 런타임 의존성을 수집한 다음 배포 패키지를 조립합니다.

기본 버전은 루트 디렉터리의 package.json에서 가져오며, 출력 디렉터리는 dist/zcode/입니다. 이 디렉터리에는 다음 항목이 포함됩니다.

  • releases/<version>/zcode-<version>.tar.gz: 실행 패키지
  • releases/<version>/sha256.txt: 검증용 해시
  • latest.json: 버전 인덱스
  • install.sh: 설치 스크립트

설치 스크립트는 기본적으로 런타임을 ~/.zcode/runtime에 설치하고, ~/.local/bin에 zcode 명령을 생성합니다. ZCODE_DIST_HOME 및 ZCODE_DIST_BIN_DIR을 각각 사용하여 이 두 위치를 변경할 수 있습니다.

로컬에서 배포 패키지 검증

파일을 업로드하거나 설치 스크립트를 실행하지 않고도 빌드 결과를 직접 압축 해제하여 실행할 수 있습니다.

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# TUI 시작
node dist/zcode/debug/zcode/bin/zcode.mjs

# Web 시작
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

이후 http://127.0.0.1:3030에 접속하면 동일한 백엔드가 호스팅하는 Web 페이지와 Agent의 전체 경로를 검증할 수 있습니다. 포트는 비어 있어야 합니다. pnpm dev:web이 해당 포트를 사용 중인 경우 --port로 다른 포트를 지정하세요.

고급 개발 권장 사항

  1. 해당 진입점 우선 사용: 데스크톱 기능에는 dev:desktop, 프런트엔드와 백엔드 연동에는 dev:web, Agent와 TUI에는 CLI workspace의 dev 명령을 사용하세요.
  2. Agent 수정 후 다시 빌드: Web 서비스가 모든 Agent 빌드 결과를 자동으로 반영하지는 않습니다. 수정 후 pnpm --filter @zcode/cli... build를 실행하고 서비스를 다시 시작해야 합니다.
  3. 테스트 데이터 격리: ZCODE_DATA_BASE_DIR을 사용하여 개발 시나리오별로 독립적인 데이터 디렉터리를 만드세요.
  4. 외부에 리슨할 때 인증 유지: --host 0.0.0.0을 사용한 후에는 자동 생성된 토큰을 유지하거나 --token을 명시적으로 설정하는 것을 우선하세요.
  5. 명령 출처 확인: pnpm build:zcode는 배포 패키지만 생성하며 시스템 PATH에 이미 있는 zcode를 교체하지 않습니다. macOS와 Linux에서는 command -v zcode, Windows에서는 where.exe zcode를 실행할 수 있습니다.
  6. 개발 검증과 배포 검증 구분: pnpm dev:web은 소스 코드 반복 개발에 적합하고, 압축 해제 후의 bin/zcode.mjs는 최종 통합 명령과 전체 배포 경로를 검증하는 데 더 적합합니다.

저장소 구조 한눈에 보기

  • packages/desktop: Electron Main, Host, Renderer 및 데스크톱 패키징
  • packages/web: Web 클라이언트
  • packages/server: HTTP, WebSocket 서비스 및 원격 연결
  • packages/zcode-server-cli: 독립 Server 시작 및 프로세스 관리
  • packages/ui: 공유 React 컴포넌트, hooks 및 Zustand 상태
  • packages/services: 비즈니스 서비스 및 영속화
  • packages/shared, packages/rpc, packages/client: 공유 프로토콜과 타입, RPC 프레임워크 및 Agent 클라이언트 SDK
  • packages/provider, packages/provider-node: Provider 공통 기능 및 Node.js 구현
  • apps/zcode-cli: Agent CLI, TUI, 런타임 및 도구
  • scripts, config, third-party: 빌드 유지 관리 스크립트, 내장 설정 및 서드파티 고지 자료

요약

ZCode는 데스크톱, Web, 백엔드 및 Agent CLI를 하나의 workspace에 통합합니다. 처음 개발할 때는 pnpm bootstrap부터 시작한 다음 목표에 따라 pnpm dev:desktop, pnpm dev:web 또는 CLI 소스 진입점을 선택하세요. 원격 workspace를 테스트하거나 정식 배포가 필요할 때는 원격 리소스를 준비한 뒤 해당 데스크톱 또는 명령줄 설치 패키지를 빌드하면 됩니다.