Molayo

© 2026 Molayo

GitHub요약2026. 05. 20. 19:06

probelabs/visor

요약

Visor는 YAML 설정을 통해 다단계 AI 파이프라인을 정의하고 오케스트레이션할 수 있는 오픈 소스 워크플로 엔진입니다. DAG 기반의 실행 엔진을 통해 AI 제공업체, MCP 도구, 셸 명령 등을 연결하며, CLI부터 Slack, GitHub Action까지 다양한 런타임 환경을 지원합니다.

핵심 포인트

  • YAML 기반의 선언적 파이프라인 정의 및 DAG 기반의 의존성 관리
  • CLI, GitHub Action, Slack, Telegram 등 8가지 다양한 런타임 모드 지원
  • Gemini, Claude, OpenAI 등 17가지 이상의 다양한 제공업체 및 도구 유형 지원
  • 실패 자동 복구, 조건부 라우팅, 병렬 실행 등 강력한 실행 엔진 기능 제공
  • YAML 네이티브 통합 테스트(fixtures, mocks, assertions) 내장

YAML 기반 파이프라인을 통해 체크(checks), MCP 도구(tools), 그리고 AI 제공업체(providers)를 오케스트레이션(orchestrate)하세요. GitHub Action, CLI, Slack 봇, Telegram 봇 또는 HTTP API로 실행할 수 있습니다.

Visor는 YAML을 통해 다단계 AI 파이프라인을 정의할 수 있는 오픈 소스 워크플로 엔진(workflow engine)입니다. 셸 명령(shell commands), AI 제공업체(AI providers), MCP 도구(MCP tools), HTTP 호출(HTTP calls), 그리고 커스텀 스크립트(custom scripts)를 의존성을 인식하는 DAG(Directed Acyclic Graph)로 연결한 다음, 터미널, CI, Slack, Telegram, Email, WhatsApp, Teams 또는 HTTP 엔드포인트에서 실행하세요.

기본 제공 기능:

YAML 기반 파이프라인— 단일 설정 파일에서 체크(checks), 변환(transforms), 라우팅(routing) 및 AI 프롬프트(prompts)를 정의합니다.
8가지 런타임 모드— CLI, GitHub Action, Slack 봇, Telegram 봇, Email, WhatsApp, Teams, HTTP 서버 — 동일한 설정으로 어떤 환경에서든 실행 가능합니다.
17가지 제공업체 유형— ai, command, script, mcp, utcp, http, claude-code, a2a, github, memory, workflow 등을 지원합니다.
AI 오케스트레이션(AI orchestration)— 멀티 제공업체(Gemini, Claude, OpenAI, Bedrock), 세션 재사용(session reuse), MCP/UTCP 도구 호출(tool calling), 재시도(retry) 및 폴백(fallback)을 지원합니다.
실행 엔진(Execution engine)— 의존성 DAG, 병렬 웨이브(parallel waves), forEach 팬아웃(fan-out), 조건부 라우팅(conditional routing), 실패 자동 복구(failure auto-remediation)를 제공합니다.
내장 테스트(Built-in testing)— 피스처(fixtures), 모크(mocks), 어설션(assertions)을 포함한 YAML 네이티브 통합 테스트를 지원합니다.

목표시작하기예시
PR에 대한 코드 리뷰가이드: Code Review Pipelinequick-start-tags.yaml
도구를 사용하는 AI 에이전트가이드: AI Agentai-custom-tools-simple.yaml
다단계 자동화워크플로 생성 가이드enhanced-config.yaml
채팅 어시스턴트 / 봇봇 통합teams-assistant.yaml
셸 명령 + AI 실행커맨드 제공업체ai-with-bash.yaml
MCP 도구 연결MCP 제공업체mcp-provider-example.yaml
UTCP를 통한 도구 호출UTCP 제공업체utcp-provider-example.yaml
API 통합 추가 (TDD)가이드: TDD Assistant Workflowsworkable.tests.yaml

처음이신가요? npx visor init을 실행하여 작동 가능한 설정을 생성한 다음, npx visor로 실행하세요.

  • 빠른 시작 (Quick Start)
  • AI 어시스턴트 프레임워크 (AI Assistant Framework)
  • 런타임 모드 (Runtime Modes)
  • PR 코멘트 명령어 (PR Comment Commands)
  • 핵심 개념 (Core Concepts)
  • 프로바이더 유형 (Provider Types)
  • 오케스트레이션 (Orchestration)
  • AI & MCP
  • GitHub 프로바이더 (GitHub Provider)
  • 템플릿 및 변환 (Templating & Transforms)
  • 경고 억제 (Suppressing Warnings)
  • 테스트 프레임워크 (Testing Framework)
  • SDK
  • 설정 (Configuration)
  • 관찰 가능성 (Observability)
  • 보안 (Security)
  • 엔터프라이즈 정책 엔진 (Enterprise Policy Engine)
  • 추가 읽을거리 (Further Reading)
  • 기여하기 (Contributing)
  • 라이선스 (License)

요구 사항: Node.js 18 이상 (CI 실행 시 Node 20 사용).

# 설치
npm i -D @probelabs/visor
# 스타터 설정 스캐폴딩 (템플릿 선택)
...

또는 설치 없이 일회성으로 실행: npx -y @probelabs/visor@latest --check all --output table

version: "1.0"
steps:
security:
...

# .github/workflows/visor.yml
name: Visor
on:
...

팁: 안정성을 위해 @v1으로 릴리스를 고정하세요. 최신 기능을 사용하려면 @nightly를 사용하세요.

Visor는 내장된 어시스턴트 프레임워크를 제공합니다. 이는 기술(skills), 도구(tools), 그리고 멀티 리포지토리 코드 탐색(multi-repo code exploration) 기능을 갖춘 AI 기반 어시스턴트를 구축할 수 있는 세 가지 조합 가능한 워크플로우(workflows)입니다. 단 한 줄의 코드로 이를 가져올 수 있습니다:

version: "1.0"
imports:
- visor://assistant.yaml
...
워크플로우 (Workflow)기능
assistant완전한 AI 어시스턴트 — 의도 라우팅 (intent routing), 동적 기술 활성화 (dynamic skill activation), 도구 오케스트레이션 (tool orchestration), 지식 주입 (knowledge injection), bash 명령어 제어
code-talk멀티 리포지토리 코드 탐색 — 질문을 리포지토리로 라우팅, 코드 체크아웃, 도구를 통한 탐색, 파일 참조 및 신뢰도 점수(confidence scoring)와 함께 답변 반환
intent-router경량 의도 분류 (intent classification) — 의도 선택, 질문 재작성, 기술/태그 선택

visor:// 프로토콜은 패키지에 포함된 번들 워크플로우로 해석되므로 별도의 네트워크 호출이 필요하지 않습니다.

더 알아보기: docs/assistant-workflows.md | 예시: code-talk-workflow · code-talk-as-tool · intent-router

Visor는 동일한 YAML 설정을 여러 환경(surfaces)에서 실행합니다:

모드 (Mode)실행 방법 (How to run)최적의 용도 (Best for)
CLIvisor --check all --output table로컬 개발 (Local dev), CI 파이프라인 (CI pipelines)
GitHub Actionuses: probelabs/visor@v1PR 리뷰 (PR reviews), 이슈 분류 (issue triage), 어노테이션 (annotations)
Slack botvisor --slack --config .visor.yaml팀 어시스턴트 (Team assistants), ChatOps
Telegram botvisor --telegram --config .visor.yaml개인용 어시스턴트 (Personal assistants), 그룹 봇 (group bots)
Email botvisor --email --config .visor.yaml이메일 어시스턴트 (Email assistants), 스레드 대화 (threaded conversations)
WhatsApp botvisor --whatsapp --config .visor.yamlWhatsApp 어시스턴트 (WhatsApp assistants), 고객 지원 (customer support)
Teams botvisor --teams --config .visor.yaml엔터프라이즈 어시스턴트 (Enterprise assistants), 팀 ChatOps
HTTP serverhttp_server: { enabled: true, port: 8080 }웹훅 (Webhooks), API 통합 (API integrations)

모든 봇 전송 방식(bot transports)에 대한 비교는 Bot Integrations를 참조하세요.

추가 모드:

TUI— 대화형 채팅 스타일의 터미널 UI (terminal UI): visor --tui

SDK— 프로그래밍 방식의 Node.js API: import { runChecks } from '@probelabs/visor/sdk'

Scheduler— 데이터베이스 기반 영속성(persistence)을 갖춘 cron 기반 실행

# CLI 예시
visor --check all --output table
visor --tags fast,local --max-parallelism 5
...

실행 모드 (Run modes): 모든 곳에서 기본값은 CLI 모드입니다. GitHub 전용 동작(댓글, 체크, 어노테이션)을 위해서는 --mode github-actions로 실행하거나, Action 내에서 mode: github-actions를 설정하세요. Action 내부에서 CLI 모드를 강제하려면 VISOR_MODE=cli를 사용하세요.

전체 CLI 참조 문서는 docs/commands.md를 참조하세요.

PR 또는 이슈의 댓글을 통해 리뷰와 어시스턴트 동작을 트리거하세요:

/review # 모든 체크 재실행
/review --check security # 특정 체크 재실행
/visor how does caching work? # 내장 어시스턴트에게 질문

더 알아보기: docs/commands.md

개념 (Concept)설명
단계 (Step) (또는 체크 (Check))작업 단위 — 셸 명령 (shell command), AI 호출 (AI call), HTTP 요청 (HTTP request), 스크립트 (script) 등.
프로바이더 (Provider)단계가 실행되는 방식: ai, command, script, mcp, utcp, http, claude-code, github, memory, workflow, …
depends_on실행 순서 — 독립적인 작업은 병렬로 실행되며, 의존적인 작업은 대기합니다.
forEach팬아웃 (Fan-out) — 출력을 배열 (array)로 변환하여 각 항목별로 의존 작업을 실행합니다.
라우팅 (Routing)on_fail, on_success, goto, retry — 루프 안전성 (loop safety)을 갖춘 조건부 흐름.
변환 (Transform)다운스트림 (downstream)으로 전달하기 전, Liquid 템플릿 (Liquid templates) 또는 JavaScript를 사용하여 출력을 재구성합니다.
스키마 (Schema)단계 출력(예: code-review)을 검증하는 JSON 스키마 (JSON Schema).
템플릿 (Template)검증된 출력을 PR 코멘트용 Markdown 또는 표 (table)로 렌더링합니다.
그룹 (Group)단계가 게시될 PR 코멘트 위치.
태그 (Tags)단계에 라벨을 붙이고 --tags fast,local로 필터링합니다.
이벤트 (Events)PR, 이슈 (issues), 코멘트 (comments), 웹훅 (webhooks) 또는 크론 스케줄 (cron schedules)에 따라 단계를 트리거합니다.
프로바이더 (Provider)설명사용 예시
ai멀티 프로바이더 AI (Gemini, Claude, OpenAI, Bedrock)코드 리뷰 (Code review), 분석 (analysis), 생성 (generation)
commandLiquid 템플릿이 적용된 셸 명령 (Shell commands)테스트 실행 (Run tests), 빌드 (build), 린트 (lint)
script보안 샌드박스 (secure sandbox) 내의 JavaScript데이터 변환 (Transform data), 커스텀 로직 (custom logic)
mcpMCP 도구 실행 (stdio/SSE/HTTP)외부 도구 통합 (External tool integration)
utcpUTCP 도구 실행 (HTTP/CLI/SSE)매뉴얼을 통한 직접적인 도구 호출 (Direct tool calling)
claude-codeMCP 도구를 포함한 Claude Code SDK심층 코드 분석 (Deep code analysis), 리팩터링 (refactoring)
httpHTTP 출력/웹훅 송신 (webhook sender)Slack 알림, CI 트리거
http_input웹훅 수신 (Webhook receiver)외부 이벤트 수락
http_clientHTTP API 클라이언트 (client)외부 API 호출
githubGitHub 작업 (labels, comments, checks)PR 라벨링, 리뷰 게시
memory키-값 저장소 (get/set/append/increment)단계 간 상태 유지 (State across steps)
workflow파일/URL로부터 가져온 재사용 가능한 서브 워크플로우 (sub-workflows)파이프라인 구성 (Compose pipelines)
human-input대화형 프롬프트 (TUI/Slack)승인 (Approvals), 사용자 입력 (user input)
log / logger

구조화된 로깅 (Structured logging) | 디버그 (Debug), 감사 추적 (audit trail) |
noop |
No-op 플레이스홀더 (No-op placeholder) | 오케스트레이션 노드 (Orchestration nodes) |
git-checkout |
Git 작업 (clone, checkout, worktree) | 멀티 리포 워크플로 (Multi-repo workflows) |

커스텀 프로바이더 (custom providers)를 구축하려면 docs/pluggable.md를 참조하세요.

의존성이 없는 단계들은 병렬 파동 (parallel waves) 형태로 실행됩니다. depends_on은 순서를 강제합니다:

steps:
fetch-data:
type: command
...

출력을 배열로 변환하고, 각 항목에 대해 종속 단계를 한 번씩 실행합니다:

steps:
list-services:
type: command
...

하위 단계에서 outputs_raw를 사용하여 모든 forEach 결과의 집계된 배열에 접근하세요:

summarize:
type: script
depends_on: [list-services]
...

더 알아보기: docs/foreach-dependency-propagation.md

단계는 재시도(retry)하거나, 복구(remediation)를 실행하거나, 실패 시 다른 단계로 점프할 수 있습니다:

version: "2.0"
routing:
max_loops: 5
...

더 알아보기: docs/failure-routing.md

steps:
security-scan:
type: command
...

사용 가능한 권한 함수: hasMinPermission(level), isOwner(), isMember(), isCollaborator(), isContributor(), isFirstTimer().

더 알아보기: docs/author-permissions.md

steps:
review:
type: ai
...

지원되는 프로바이더 (providers): Google Gemini, Anthropic Claude, OpenAI GPT, AWS Bedrock.

환경 변수를 통해 하나의 키를 설정하세요: GOOGLE_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY 또는 AWS 자격 증명.

AI 단계에 MCP 도구에 대한 액세스 권한을 부여하거나, MCP 도구를 직접 호출하세요:

# MCP 도구를 사용하는 AI 단계
steps:
analyze:
...

단계 전반에 걸쳐 AI 대화를 체이닝 (Chain) 하세요:

steps:
security:
type: ai
...

MCP 도구 및 서브 에이전트 (subagents)와 함께 Claude Code SDK를 완전히 통합합니다:

steps:
deep-review:
type: claude-code
...

더 알아보기: docs/claude-code.md · docs/mcp-provider.md · docs/advanced-ai.md

gh 명령어를 호출하지 않고도 네이티브 GitHub 작업 (labels, comments, checks)을 수행합니다:

steps:
apply-labels:
type: github
...

더 알아보기: docs/github-ops.md

단계는 프롬프트, 실행 명령, HTTP 바디 등에서 Liquid 템플릿을 사용할 수 있습니다:

steps:
  greet:
    type: command
    ...

사용 가능한 컨텍스트 (Available context): outputs, outputs_raw, inputs, pr, files, env, memory, branch, event, conversation.

의존 단계로 전달하기 전에 단계 출력값(step output)을 변환할 수 있습니다:

steps:
  fetch:
    type: command
    ...

steps:
  check:
    type: command
    ...

프롬프트 (Prompts)는 Liquid 변수에 완전히 접근 가능한 외부 파일에 저장할 수 있습니다:

steps:
  overview:
    type: ai
    ...

더 알아보기: docs/liquid-templates.md · docs/schema-templates.md

근처에 visor-disable 주석을 추가하여 특정 이슈를 억제 (Suppress)할 수 있습니다:

const testPassword = "demo123"; // visor-disable

더 알아보기: docs/suppressions.md

YAML 형식으로 Visor 설정에 대한 통합 테스트 (Integration tests)를 작성하고 실행하세요:

# .visor.tests.yaml
tests:
- name: "Security check finds issues"
  ...

visor test --progress compact # 테스트 실행
visor test --list # 테스트 케이스 목록 표시
visor test --only "Security*" # 테스트 필터링
...

문서: 시작하기 (Getting started) · DSL 참조 (DSL reference) · Fixtures & mocks · 단언 (Assertions) · 쿡북 (Cookbook)

Node.js에서 프로그래밍 방식으로 Visor를 실행하세요:

import { loadConfig, runChecks } from '@probelabs/visor/sdk';
const config = await loadConfig('.visor.yaml');
const result = await runChecks({
  ...
});

더 알아보기: docs/sdk.md

  • CLI
    --config 플래그를 사용하여 프로젝트 루트의 .visor.yaml을 지정할 수 있습니다. 내장된 기본값 (Built-in defaults)이 적용됩니다.
extends:
- default
- ./team-standards.yaml
...

장시간 실행 모드 (Slack, Telegram, Email, HTTP)는 실시간 설정 재로드 (Live config reload)를 지원합니다:

visor --slack --config .visor.yaml --watch # 파일 변경 시 자동 재로드
visor --telegram --config .visor.yaml --watch # 핫 리로드 (Hot reload)가 적용된 Telegram
visor --email --config .visor.yaml --watch # 핫 리로드가 적용된 Email
...

version: "1.0"
max_parallelism: 3 # 병렬 단계 (Concurrent steps)
max_ai_concurrency: 3 # 병렬 AI API 호출 (Concurrent AI API calls)
...

흔히 혼동하는 부분은 AI 설정을 어디에 두어야 하는가입니다. 가이드는 다음과 같습니다:

version: "1.0"
# ── 전역 기본값 (Global defaults, 최상위 레벨) ──────────────────────
ai_provider: google # 모든 단계에 대한 기본 AI 제공자 (Default AI provider)
...

흔한 실수:
system_prompt를

단계(step) 레벨에서 사용하는 경우 (무시됨 — ai_system_prompt를 사용하거나 ai: 블록 내부에 작성하세요).

최상위(Top-level) ai: 블록에서 사용하는 경우 (지원되지 않음 — ai_provider / ai_model을 사용하세요).

명령(command) 단계에서 parseJson을 사용하는 경우 (명령은 JSON을 자동으로 파싱합니다).

이러한 오류를 잡아내려면 visor validate를 실행하세요.

더 알아보기: docs/ai-configuration.md · docs/configuration.md

visor --output table # 터미널 친화적 (기본값)
visor --output json --output-file results.json
visor --output sarif --output-file results.sarif
...

telemetry:
  enabled: true
  sink: otlp

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces visor --check all

스팬(Span) 계층 구조: visor.run

→ engine.state.*

→ visor.check.*

→ visor.foreach.item

visor --debug # 상세 로깅 (Verbose logging)
visor --debug-server --debug-port 3456 # 라이브 웹 시각화 도구 (Live web visualizer)

빠른 디버깅 팁:

JavaScript 표현식(if, fail_if, transform_js)에서 log()를 사용하세요:

if: |
  log("Outputs:", outputs);
  outputs["fetch-data"]?.status === "ready"

객체를 검사하려면 Liquid의 json 필터를 사용하세요:

type: logger
message: "Outputs: {{ outputs | json }}"

TUI 모드 (visor --tui): Tab 키를 누르세요

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0