AI 튜토리얼

Lancer 입문 튜토리얼: 추적 가능한 병렬 AI 데스크톱 작업 공간 구축

이 튜토리얼에서는 Lancer의 핵심 기능을 소개하고, 환경 점검, 종속 항목 설치, 모델 연결 및 첫 세션 생성을 단계별로 안내합니다. 또한 광선 UI, 동영상 도구, 검증 테스트와 macOS 빌드 시 주의 사항도 설명합니다.

2026년 11월 2일약 13분 소요

Lancer 입문 튜토리얼: 추적 가능한 병렬 AI 데스크톱 작업 공간 구축

Lancer란

Lancer는 pi-gui와 pi를 기반으로 개발된 데스크톱 AI 작업 공간입니다. 대화, 병렬 분기, 실행 과정과 결과 파일을 하나의 인터페이스에 통합하여 작업의 생성, 분할부터 전달까지 전체 과정을 추적할 수 있도록 돕습니다.

중요: Lancer는 현재 Alpha 단계이며 macOS Apple Silicon이 주요 검증 플랫폼입니다. Linux와 Windows에는 패키징 설정이 있지만, 모든 네이티브 기능이 검증되었다는 의미는 아닙니다. 소스 코드 압축 파일은 더블 클릭하여 바로 실행할 수 있는 데스크톱 설치 패키지가 아닙니다.

핵심 기능

세션과 모듈형 작업

일반 세션은 독립적으로 실행할 수 있습니다. 모듈 세션은 단계, 모델, Skill, 목표 및 결과물 요구 사항을 구성할 수 있어, 단계가 명확하고 결과 검수가 필요한 복잡한 작업에 적합합니다.

병렬 분기와 결과 집계

하나의 어시스턴트가 여러 세션을 관리할 수 있습니다. 작업은 하위 분기와 손자 분기로 파생될 수 있으며, 각 분기가 완료되면 결과를 상위 세션으로 반환하여 집계합니다. 이러한 구조는 병렬 연구, 방안 비교 및 다단계 콘텐츠 제작에 적합합니다.

GitTree 작업 이벤트 그래프

화면 오른쪽의 GitTree는 여러 세션 흐름, 분기, 병합 및 결과물 노드를 동시에 표시하거나 현재 세션에 집중할 수 있습니다. 단, GitTree가 표현하는 것은 작업 이벤트 그래프이며, 모든 노드가 실제 Git 커밋을 의미하는 것은 아닙니다.

실행 피드백과 광선 효과

활성 버블과 과정 행에는 움직이는 테두리가 표시되고, 모델 출력과 결과물 작업은 해당 노드로 같은 색상의 광선을 보냅니다. 이러한 시각적 피드백은 현재 실행 중인 작업과 결과 흐름을 보여 줍니다.

모델, 계정 및 더우바오 인계

Lancer는 pi를 통해 구독 계정, API 키 및 사용자 지정 엔드포인트에 연결하고 모델 브랜드와 게이트웨이를 পৃথ도로 관리합니다. macOS에서는 이미 열려 있는 더우바오 App 세션을 연결하여 응답과 동영상을 받을 수도 있습니다. 더우바오 인계에는 로컬 손쉬운 사용 권한이 필요하며, 데스크톱 버전 더우바오의 인터페이스 업데이트가 호환성에 영향을 줄 수 있습니다.

동영상 분석 워크플로

동영상 워크플로는 동영상을 다운로드하거나 수신하고, 주요 프레임을 추출하며, 근거가 포함된 분석 및 인계 파일을 생성할 수 있습니다. 그러나 현재 자동 복제 결과가 템플릿과 1:1로 일치한다고 보장할 수는 없습니다. 더우바오 인계, 모델 분석, 코드 애니메이션 및 최종 편집은 서로 다른 단계이므로 각각 별도로 검수해야 합니다.

설치 전 준비

시작하기 전에 개발 환경이 다음 요구 사항을 충족하는지 확인하세요.

Node.js >=22.19.0且 <26, Node.js 24 권장.
pnpm 10.34.9.
Git.
macOS에는 Xcode Command Line Tools가 필요합니다.
Linux에는 Python 3, make, C++ 컴파일러, 그래픽 데스크톱 환경 및 Electron에 필요한 시스템 런타임 라이브러리가 필요합니다.
Windows의 네이티브 종속성에는 Python과 C++ 워크로드가 포함된 Visual Studio Build Tools가 필요할 수 있지만, 현재 버전에서는 Windows 네이티브 동작이 아직 완전히 검증되지 않았습니다.

macOS에 명령줄 도구가 없으면 다음을 실행할 수 있습니다.

xcode-select --install

Debian 또는 Ubuntu에서는 다음 명령으로 Linux 컴파일 종속성을 설치할 수 있습니다.

sudo apt-get install build-essential python3

소스에서 설치하고 실행하기

소스 코드를 새 디렉터리에 압축 해제하거나 복제한 다음 저장소 루트 디렉터리로 이동하여 다음 명령을 순서대로 실행하세요.

npx --yes pnpm@10.34.9 run doctor
npx --yes pnpm@10.34.9 install --frozen-lockfile
npx --yes pnpm@10.34.9 dev

이 명령은 pnpm 10.34.9를 고정하여 사용하므로 corepack enable을 실행할 필요가 없고 pnpm을 전역 설치할 필요도 없습니다. 시스템에 같은 버전이 이미 설치되어 있다면 명령 접두사를 pnpm으로 바꿔도 됩니다.

종속성을 다운로드하려면 네트워크 연결이 필요합니다. 설치 중 종속성 스크립트를 건너뛰면 Electron 바이너리 파일이 없을 수 있습니다. 네트워크에서 Electron 다운로드 소스에 접근할 수 있는지 확인한 후 다음을 실행하세요.

npx --yes pnpm@10.34.9 run setup:electron
npx --yes pnpm@10.34.9 dev

Electron 설치 문제를 해결하기 위해 모든 종속성 스크립트를 무차별적으로 허용하거나 비활성화하지 말고, 먼저 설치 로그와 네트워크 오류를 확인하세요.

첫 구성 완료

Lancer를 시작하고 설정으로 이동합니다.
지원되는 모델 계정, 제공업체 또는 사용자 지정 엔드포인트를 연결합니다. 소스 코드에는 개인 자격 증명이 포함되어 있지 않습니다.
작업 공간을 추가하거나 선택합니다.
일반 세션을 만들거나, 작업에 따라 단계, 모델, Skill, 목표 및 결과물 요구 사항이 포함된 모듈 세션을 만듭니다.
작업을 실행한 후 GitTree에서 세션 흐름, 파생 분기, 집계 및 결과물 노드를 확인합니다.

환경 변수로 인터페이스 언어를 지정할 수 있습니다.

LANCER_LOCALE=zh-CN npx --yes pnpm@10.34.9 dev

영어 인터페이스를 사용하려면 값을 en으로 설정하세요.

선택적 환경 설정 불러오기

선택적 설정은 저장소의 .env.example에 기록되어 있지만 데스크톱 시작 스크립트는 이 파일을 자동으로 읽지 않습니다. macOS 또는 Linux에서는 템플릿을 복사한 뒤 현재 터미널에서 불러올 수 있습니다.

cp .env.example .env.local
set -a
. ./.env.local
set +a
npx --yes pnpm@10.34.9 dev

PowerShell 사용자는 다음과 같이 환경 변수를 하나씩 설정할 수 있습니다.

$env:LANCER_LOCALE = "en"

실제 모델 계정은 애플리케이션 설정에서 연결해야 합니다. API 키, 인증 파일, 비공개 엔드포인트, 실제 대화 또는 세션 녹화 파일을 공개 저장소에 커밋하지 마세요.

동영상 도구 구성

대화 인터페이스만 사용할 때는 미디어 도구가 필요하지 않습니다. 동영상 다운로드, 주요 프레임 추출 및 미디어 분석 과정을 실행하려면 실행 가능한 FFmpeg, FFprobe 및 yt-dlp가 필요합니다.

pnpm run doctor --media

이러한 도구가 PATH에 없다면 FFMPEG, FFPROBE 및 YT_DLP 환경 변수로 절대 경로를 지정하거나 사용자 데이터 디렉터리의 video-learn-tools.json에 경로를 구성할 수 있습니다.

진단 명령은 각 도구의 버전 명령을 실제로 실행하므로 파일 누락뿐 아니라 “실행 파일은 있지만 동적 라이브러리가 누락된” 손상된 설치도 식별할 수 있습니다. 전체 검증 전에 다음과 같이 수동으로 확인할 수 있습니다.

ffmpeg -version
ffprobe -version

실행 확인, 빌드 및 테스트

수정 사항을 제출하거나 소스 코드 상태를 평가할 때 다음 확인을 실행할 수 있습니다.

pnpm check
pnpm build
pnpm audit:dependencies
pnpm verify:install-copy
pnpm verify:release-config
pnpm --filter @lancer/desktop run test:e2e:core

개발 중에는 데스크톱 리로드도 확인할 수 있습니다.

pnpm --filter @lancer/desktop run test:dev:reload

Core 테스트는 격리된 데이터를 사용해 실제 Electron 인터페이스를 실행하지만, Core 테스트 통과만으로 실제 모델, 네이티브 권한, 설치 패키지, 성능 또는 모든 플랫폼의 호환성이 검증되었다고 볼 수는 없습니다. 미디어 관련 테스트에는 FFmpeg와 FFprobe가 정상적으로 실행되어야 합니다.

Lancer Light UI만 별도로 재사용하기

모델 또는 버블과 작업 트리를 연결하는 광선 효과만 필요하다면 Lancer Light UI를 내보낼 수 있습니다. Electron, CLI 또는 모델 서비스에 의존하지 않으며 단일 흐름, 분기 병합 및 여러 세션 병렬 실행 예제를 제공합니다.

pnpm export:light-ui /absolute/new/lancer-light-ui
cd /absolute/new/lancer-light-ui
npm install && npm run dev

내보내기 경로는 대상 컴퓨터의 절대 경로로 바꿔야 합니다. 자세한 내용은 저장소의 Light UI README에서 확인할 수 있습니다.

macOS에서 로컬 애플리케이션 빌드

소스 패키지에는 더블 클릭하여 바로 실행할 수 있는 .app이 포함되어 있지 않으며, 독립 애플리케이션 다운로드도 아직 제공되지 않습니다. 종속성을 설치한 후 다음 로컬 빌드 스크립트를 실행할 수 있습니다.

bash scripts/build-mac-lancer.sh --skip-install --dir

로컬 설치 패키지를 만들려면 먼저 영구 서명 인증서를 구성해야 합니다. 스크립트는 인증서를 자동으로 만들거나 임시 서명으로 전환하거나 공증을 수행하지 않습니다. 빌드 결과는 별도의 apps/desktop/release-local-*/ 디렉터리에 저장됩니다.

후보 애플리케이션을 확인한 후 --install을 추가하여 /Applications에 설치할 수 있습니다.

bash scripts/build-mac-lancer.sh --skip-install --dir --install

설치 프로그램은 기존 애플리케이션이 정상적으로 종료되었는지 확인하고, 서명을 검사하며 복구 가능한 이전 버전을 보존합니다. 세션 데이터는 삭제하지 않습니다. 공개 배포에는 여전히 Developer ID, 공증 및 초기화된 컴퓨터에서의 검수가 필요하며, 로컬 서명만으로 공개 배포 인증이 완료되었다고 볼 수 없습니다.

고급 사용 및 보안 권장 사항

실행 데이터 위치 이해하기

세션 및 계정 데이터는 pi의 ~/.pi/agent를 사용합니다. macOS에서 Lancer 인터페이스 상태는 ~/Library/Application Support/Lancer에 있습니다. 소스 코드를 다른 디렉터리에 복사해도 이러한 실행 데이터가 격리되지는 않습니다. 완전히 격리된 수동 테스트가 필요하면 별도의 운영 체제 사용자를 사용하세요.

복잡한 작업을 위한 분기 설계

연구, 분석, 구현 및 검수를 서로 다른 하위 분기로 나눈 다음 상위 세션에서 집계할 수 있습니다. GitTree를 사용할 때는 노드를 코드 커밋으로 간주하기보다 작업 이벤트와 결과물 관계로 이해해야 합니다.

동영상 과정을 별도로 검수하기

동영상 프로젝트에서는 인계 입력, 모델 분석, 코드 애니메이션 및 최종 편집을 각각 확인해야 합니다. 한 단계가 성공했다고 해서 최종 작품이 참고 템플릿과 완전히 일치하도록 자동 생성될 것이라고 판단하지 마세요.

감사 가능한 소스 후보 패키지 내보내기

소스 배포를 준비할 때 새 후보 디렉터리와 SHA-256 목록을 내보낼 수 있습니다.

pnpm export:source /absolute/path/to/new/lancer-source

이 명령은 .git, 로컬 세션 결과물, 키 파일 및 빌드 출력을 제외하지만 현재 작업 공간, 과거 스크린샷과 녹화 파일은 보존합니다. 내보내기에 성공했다고 해서 바로 공개 배포할 수 있는 것은 아니며, 자료 사용 권한과 민감한 내용을 수동으로 검토해야 합니다.

자주 묻는 질문

Corepack에서 권한 오류가 발생함: 고정 버전의 npx --yes pnpm@10.34.9 명령을 사용하면 전역 shim을 수정할 필요가 없습니다.
Electron이 올바르게 설치되지 않음: 네트워크와 설치 오류를 확인한 다음 run setup:electron을 실행하세요.
Linux에서 make 또는 컴파일러가 없다고 표시됨: 먼저 Python 3, make 및 C++ 빌드 도구를 설치한 후 종속성을 다시 설치하세요.
동영상 도구 확인에 실패함: pnpm doctor --media를 실행하고 실행 파일과 해당 동적 라이브러리를 모두 사용할 수 있는지 확인하세요.
모델을 사용할 수 없음: 설정에서 지원되는 계정 또는 제공업체를 연결하세요. 소스 코드에는 개인 인증 정보가 포함되어 있지 않습니다.

요약

Lancer는 병렬 AI 세션, 재귀적 분기, 진행 피드백 및 산출물 파일을 하나의 데스크톱 작업 공간에서 관리합니다. 이 튜토리얼에 따라 환경 점검, 소스 코드 실행, 계정 연결 및 미디어 도구 구성을 완료하면 추적 가능한 작업 흐름을 구축할 수 있습니다. 프로젝트는 아직 Alpha 단계이므로 프로덕션 사용, 크로스 플랫폼 호환성, Doubao 인수 및 동영상 복제 결과를 별도로 검증해야 합니다.