Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
NebulaFlow는 노드 그래프 기반의 시각적 에디터로, 개발자 워크플로우를 설계하고 실행할 수 있게 합니다. VS Code, Electron 앱, 브라우저 등 다양한 환경을 지원하며, LLM 노드는 pi coding-agent SDK를 통해 상위 노드의 출력을 활용하여 프롬프트를 구성하고 실행합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기NebulaFlow는 노드 그래프 형태로 개발자 워크플로우를 설계하고 실행할 수 있는 시각적 에디터입니다. VS Code, 독립형 Electron 데스크톱 애플리케이션, 그리고 브라우저/WebSocket 타겟을 지원합니다.
참고
Electron 베타 버전 준비 완료: 독립형 데스크톱 타겟이 베타 테스트를 할 수 있도록 준비되었습니다. Windows 패키징과 핵심 에디터, IPC(Inter-Process Communication), 영속성(persistence), 로컬 실행, 그리고 pi 모델 디스커버리 플로우가 검증되었습니다. '베타' 상태라는 것은 테스트와 피드백에 적합하다는 의미이며, 아직 안정적인 프로덕션 릴리스는 아닙니다.
LLM 노드는 pi coding-agent SDK(@earendil-works/pi-agent-core + @earendil-works/pi-ai)를 통해 실행됩니다. 에디터는 상위 노드의 출력을 기반으로 프롬프트를 구성하고, 이를 pi의 PiAgent API로 실행합니다.
workflow/PiIntegration/은 모델 디스커버리, 프로바이더 인증, 사용자 정의 모델, 요청 라우팅을 위한 공유된 piModelRuntime을 소유합니다. - 인증: pi /login, ~/.pi/agent/auth.json, 또는 선택한 프로바이더의 표준 API-key 환경 변수를 사용합니다.NebulaFlow는 pi의 표준 설정 저장소를 사용합니다:
~/.pi/agent/settings.json: 전역 defaultProvider 및 defaultModel
.<workspace>/.pi/settings.json: pi 설정을 위한 프로젝트 오버라이드(override)
~/.pi/agent/auth.json: pi /login을 통해 생성된 API 키 및 OAuth 자격 증명
.~/.pi/agent/models.json: 사용자 정의 프로바이더 및 모델
.~/.pi/agent/models-store.json: 캐시된 동적 프로바이더 카탈로그.
LLM 노드 속성 에디터(Property Editor)에서 선택된 모델이 우선순위를 가집니다. 노드가 선택되지 않은 경우, NebulaFlow는 인증된 상태일 때 pi의 프로젝트/전역 기본값을 사용하고, 그 다음으로 인증된 내장 폴백(fallback)을 사용합니다. Model 콤보박스는 공유된 pi ModelRuntime을 통해 사용할 수 있는 모델들을 보여줍니다.
카테고리 레이블 표시: 사용자에게 보이는 카테고리 이름은 사이드바 노드 팔레트(WorkflowSidebar.tsx)에서 개선된 레이블로 매핑됩니다: llm → Agents, text-format → Text
@earendil-works/pi-agent-core)를 통해 실행됩니다.)), 업스트림 노드 출력을 기반으로 프롬프트를 구성하고 pi의 PiAgent를 통해 스레드 내에서 실행합니다.
API 덕분에 나중에 실행에서도 동일한 대화 내용을 재사용할 수 있습니다. - LLM 노드가 활성 threadID를 가지고 있을 때,
우측 사이드바에 작은 채팅 패널이 표시되어 해당 노드로 후속 메시지를 보낼 수 있습니다. 답장은 기존 어시스턴트 기록에 추가되고 Playbox로 스트리밍되며, 초안은 현재 실행 런(run)에 한정되고 워크플로우 재설정 시 지워집니다. - pi 도구(read, bash, edit, write, ls, find, grep)는 PiIntegration 모듈을 통해 LLM 노드에서 사용할 수 있습니다.
속성 편집기(Property Editor)에서 명령어(Command, 한 줄 코드)와 스크립트(Script, stdin을 통한 여러 줄 코드) 간 전환이 가능합니다.
스크립트 모드는 개행을 유지하며, here-docs나 임시 파일이 필요 없습니다.
Stdin 소스는 parents-all, parent-index, 또는 literal로 설정할 수 있으며, 선택적으로 코드 울타리(code fences)를 제거하고 CRLF를 정규화합니다.
Env 매핑은 부모 출력을 INPUT_1…N 또는 사용자 지정 이름으로 노출하며, 대용량 페이로드에는 stdin을 사용하십시오.
셸/플래그: bash/sh/zsh (set -e, set -u, set -o pipefail), pwsh (-NoProfile, -NonInteractive, 선택적 -ExecutionPolicy Bypass). - 안전성(Safety): 명령어 모드는 기본적으로 화이트리스트/샌티타이징을 사용합니다 (안전). 스크립트 모드는 stdin 의미론을 사용합니다. 고급 설정은 샌티타이징을 비활성화합니다 (작성 시 승인 사용).
실행(Execution): 스크립트 모드는 기본적으로 spawn(버퍼링)을 사용하며, 명령어 모드에서는 토글을 통해 spawn(버퍼링)을 사용할 수 있습니다. 출력은 집계되고 너무 클 경우 잘립니다.
승인(Approvals): 활성화된 경우, 우측 사이드바에 편집 가능한 스크립트/명령어와 구조화된 요약 정보(모드, 셸, 안전성, Stdin, 플래그)가 표시되어 승인하기 전에 확인할 수 있습니다.
노드 유형: CLI, LLM, Preview, Text Input, Loop Start/End, Accumulator, Variable, If/Else, Subflow, Subflow Input/Output
반복되는 노드 작업을 재사용 가능한 단위로 저장하는 사용자 정의 노드(Custom Nodes)
노드를 재사용 가능한 단위로 그룹화할 수 있는 서브플로우(Sub-Flows) 지원
독립적인 브라우저 사용을 위한 WebSocket bridge 서버를 통한 웹 전용 배포 대상
소형 화면 및 VSCode 환경 외에서의 반응형 레이아웃
순서가 지정된 엣지 기반의 그래프 실행, 미리보기용 토큰 카운팅, 중단(abortion) 지원
셸 노드 개선 사항:
작업 공간 지속성(Workspace persistence):
.nebulaflow/workflows/*.json사용자 정의 노드: .nebulaflow/nodes/*.json
워크플로우:
보안 보호 기능:
rm, sudo, chown 등) - 명령어 정제 및 중단 처리; 승인 가능; 고급 모드는 정제를 비활성화함VS Code ≥ 1.90.0 확장 프로그램 대상
Node.js ≥ 22.19.0 및 npm
macOS, Linux 또는 Windows
종속성 설치
git clone https://github.com/PriNova/nebulaflow
cd nebulaflow
npm install
한 번 빌드 (webview + 확장 프로그램)
npm run build
VS Code에서 확장 프로그램 실행
이 폴더를 VS Code에서 열기
실행 및 디버그:
webview 에셋 누락 메시지가 보이면 npm run build를 실행하거나, 런치 설정(launch config)을 통해 워처(watcher)를 시작한 후 다시 시도하세요.
일회성 빌드(One-shot builds):
Webview 전용:
npm run build:webview
확장 프로그램 전용:
npm run build:ext
Webview 전용:
webview 워치(VS Code 런치 설정에서 사용됨):
npm run watch:webview
타입 체크 (확장 프로그램 + webview 타입):
npm run typecheck
린트/포맷 (ESLint):
확인(Check):
npm run check
린트(Lint):
npm run lint
자동 수정(Auto-fix):
npm run lint:fix
확인:
Electron 타겟은 NebulaFlow를 VS Code가 필요 없는 독립형 데스크톱 애플리케이션으로 실행합니다. 이는 확장 프로그램 타겟과 동일한 워크플로우 에디터 및 실행 런타임을 사용합니다.
Windows 패키징은 현재 검증되었습니다. Linux와 macOS 타겟도 구성되어 있지만, 배포 전에 해당 네이티브 운영 체제에서 테스트해야 합니다.
의존성을 설치하고 webview와 Electron 메인 프로세스를 빌드한 다음, Electron을 시작하세요:
npm install
npm run start:electron
start:electron은 앱을 실행하기 전에 필요한 webview 및 Electron 빌드를 수행합니다.
npm run build:webview
npm run build:electron
컴파일된 Electron 파일은 dist/electron에 작성되며, 공유 렌더러 에셋은 dist/webviews에 작성됩니다.
Windows에서 이 명령을 실행하세요:
npm run pack:electron -- --win
아티팩트는 dist/release에 생성됩니다:
dist/release/win-unpacked/NebulaFlow.exe
— 직접적인 스모크 테스트를 위한 언패킹된 애플리케이션
dist/release/NebulaFlow Setup <version>.exe
— NSIS 인스톨러
대상 운영 체제에서 적절한 명령을 실행하세요:
# Linux AppImage
npm run pack:electron -- --linux
# macOS DMG
...
플랫폼 서명 및 인스톨러 요구 사항은 환경별로 다릅니다. 대상 운영 체제에서 빌드하는 것을 권장합니다.
베타 패키지를 배포하기 전에 다음을 실행하세요:
npm run check
npm run build
npm run build:web
...
그런 다음 dist/release/win-unpacked/NebulaFlow.exe를 시작하세요.
그리고 에디터, 워크플로우 저장소, 모델 검색, 그리고 로컬 워크플로우 작업을 검증합니다.
주요 스크립트:
npm run build
— VS Code 확장 및 공유 웹뷰 타입 체크 및 빌드
npm run build:web
— 독립형 브라우저 타겟 빌드
npm run start:electron
— 소스에서 Electron 앱 빌드 및 시작
npm run build:electron
— Electron 메인 및 프리로드 프로세스 컴파일
npm run pack:electron -- --win
— Windows 언패킹된 앱 및 설치 프로그램 생성
npm run pack:electron -- --linux
— Linux AppImage 생성
npm run pack:electron -- --mac
— macOS DMG 생성
npm run package:vsix
— VS Code 확장 빌드 및 패키징
npm run check
— TypeScript 및 ESLint 검사 실행
├ src/
│ └ extension.ts # 명령어 등록, 웹뷰 호스팅
├ workflow/
...
이 리포지토리는 workflow/ 디렉토리 내에서 수직 슬라이스(vertical slice) 스타일을 따릅니다:
Web (UI): 웹뷰 UI, 사용자 시작 액션 및 프로토콜 미러 - workflow/Web/components/ 아래의 웹 슬라이스들로 구성됩니다.
:sidebar/
(왼쪽/오른쪽 사이드바, PropertyEditor, 액션)
:graph/
(커스텀 엣지, 엣지 경로, 엣지 유효성 검사)
:nodes/
(LLM, CLI, 제어 흐름 등 노드 UI 컴포넌트)modals/
(도움말, 삭제 확인, 텍스트 에디터, 마크다운 미리보기)shared/
(재사용 가능한 UI: 마크다운, 복사 버튼, 실행 버튼, 로딩 로고)subflows/
(서브플로우 UI 컴포넌트)
@graph/*,@sidebar/*
,@modals/*
,@nodes/*
,@shared/*
.
실행 흐름:
사용자가 에디터를 열고 웹뷰에서 그래프를 편집합니다.
웹뷰는 확장 프로그램으로 메시지(저장, 로드, 실행, 토큰 수)를 전송합니다.
확장 프로그램은 노드를 안전한 순서로, 가능하다면 병렬로 검증하고 영속화하며 실행합니다.
상태/결과는 표시를 위해 웹뷰로 스트리밍됩니다.
워크플로우는 .nebulaflow/workflows/ 아래에 JSON 파일로 저장됩니다. (버전 관리 1.x)
사용자 정의 노드는 .nebulaflow/nodes/ 아래에 JSON 파일로 저장됩니다.
서브플로우는 .nebulaflow/subflows/ 아래에 JSON 파일로 저장됩니다.
확장 프로그램은 작업 공간 범위로 제한된 저장/로드 위치를 요청합니다.
CLI 노드:
오류는 VS Code 알림을 통해 표시되며, 오류/중단 시 실행이 중지됩니다.
LLM 노드가 인증된 모델을 사용할 수 없다고 보고하는 경우:
pi login을 실행하여 ~/.pi/agent/auth.json을 구성하거나, NebulaFlow를 시작하기 전에 선택한 제공업체의 API 키 환경 변수를 설정하십시오.npm run build를 실행하여 웹뷰 에셋이 로드되지 않는 경우에 대한 안내입니다.
또는 Run 및 Debug 구성을 시작합니다(워처를 시작함).
npm run typecheck및 진단 사항을 처리합니다.
npm run checkor npm run lint:fix
Run
TypeScript 엄격 모드; 확장 프로그램은 CommonJS를 사용하고 웹뷰는 ESM + React를 사용합니다.
ESLint를 통해 포맷팅 및 린팅을 수행합니다 (npm run check, npm run lint:fix). 핵심 헬퍼는 순수하게 유지하고, 부작용(side-effects)은 경계(웹뷰/애플리케이션/데이터 접근)에 배치합니다.
명시적인 타입 임포트와 작은 함수를 선호합니다.
Node.js 내장 모듈 임포트는 node: 프로토콜을 사용해야 합니다 (예: import * as fs from 'node:fs').