lvkit
LabVIEW VI 파일을 읽고, 렌더링하고, 문서화하며, 비교(diff)할 수 있습니다. LabVIEW 라이선스가 필요하지 않습니다.
lvkit은 .vi, .ctl, .lvclass, .lvlib, 및 .lvproj 파일을 직접 분석하여 질의 가능한 의존성 그래프(dependency graph)와 데이터 흐름 그래프(dataflow graph)로 만듭니다. 이 그래프로부터 블록 다이어그램을 렌더링하고, VI가 무엇을 하는지 설명하며, 문서를 생성하고, 두 버전을 비교할 수 있습니다. 이는 터미널에서, CI 환경에서, 또는 AI 에이전트를 통해 수행 가능합니다. 또한 VI의 Python 번역(transliteration)도 생성할 수 있지만, 이 경로는 실험적이며 VI마다 구현 정도가 다릅니다.
읽기만 하고, 쓰지 않습니다. lvkit은 오직 VI를 읽을 뿐입니다. 절대로 수정하거나, 재저장하거나, 편집하지 않습니다. 변환(convert)을 포함한 모든 기능은 소스를 분석하여 별도의 출력 파일에 작성합니다. 사용자의 .vi 파일은 절대 건드리지 않으며, LabVIEW가 여전히 해당 파일을 생성하는 유일한 도구로 남습니다.
독립적이고 클린룸 방식의 프로젝트 — NI와 제휴하지 않았습니다. 공개된 NI 문서, 오픈 소스 pylabview 파서, 그리고 VI 파일 관찰을 기반으로 구축되었으며, LabVIEW 설치나 NI의 비공개 사양에 의존하지 않습니다. 자세한 내용은 Cleanroom approach를 참조하십시오. 또한 NOTICE와 PROVENANCE.md도 확인해 주십시오.
목차
Quick Start
pip install lvkit
lvkit setup
전역 설치를 하려면: pipx install lvkit 또는 uv tool install lvkit을 사용하십시오. 모든 명령어는 python -m lvkit <명령어>로 실행됩니다.
lvkit은 언패킹된 VI 파일을 ~/.lvkit/cache에 캐시합니다 (환경 변수 LVKIT_CACHE_DIR로 재정의 가능). 관리되는 환경에서는 해당 폴더를 안티바이러스 동작 모니터링에서 제외할 수 있습니다. The lvkit cache를 참조하십시오.
lvkit setup은 .lvkit/ 해상도 저장소를 생성하고 AI 에이전트 스킬을 설치합니다:
- Claude Code (
CLAUDE.md / .claude/), Copilot (.github/copilot-instructions.md / .github/instructions/ / .github/skills/ / .github/prompts/ / .github/agents.md), 및 Codex (AGENTS.md / AGENTS.override.md / .agents/ / .codex/) 자동 감지
- 명시적으로 지정하려면
claude, copilot, codex, 또는 all을 전달합니다.
--no-skills를 사용하면 어떤 스킬도 설치하지 않고 .lvkit/ 저장소를 생성할 수 있습니다.
| Command | Description |
|---|
lvkit describe | 사람이 읽기 쉬운 VI 요약: 시그니처, 연산(operations), 데이터 흐름(dataflow), 구조체(structures) |
| ... | |
describe, render, diff, docs, 및 visualize는 그래프만으로 작동하며 의미론적 매핑이 필요하지 않습니다. 오직 generate만이 기본/vi.lib 매핑을 요구합니다. lvkit visualize를 사용하려면 pyvis 추가 설치가 필요합니다: pip install lvkit[visualize]. | |
기능 소개 (What you can do with it)
VI의 동작 설명 (Describe what a VI does)
A LabVIEW를 열지 않고도 사람이 읽을 수 있는 시그니처, 입력/출력, 연산 및 제어 흐름(control flow)을 확인합니다.
lvkit describe <path-to.vi> [--userlib <user.lib/>] [--verbose]
--verbose는 전체 넷리스트(netlist)를 추가하며, 이는 블록 다이어그램의 텍스트 투영본입니다.
블록 다이어그램 렌더링 (Render the block diagram)
VI의 블록 다이어그램을 충실하고 독립적인 SVG로 렌더링합니다. 노드, 와이어, 구조체 및 SubVI 아이콘 모두 파싱된 그래프에서 그려집니다. LabVIEW나 스크린샷이 필요 없습니다.
lvkit render <path-to.vi> [--format {svg,html}] [--theme {light,dark,auto}] [--userlib <user.lib/>]
--format html은 확대/축소 및 이동 기능과 라이트/다크 다이어그램 테마 토글이 있는 대화형 단일 VI 뷰어를 작성합니다. 노드에 마우스를 올리면 커넥터 패널과 문서를 볼 수 있습니다. 동일한 렌더러가 diff --format html 및 VS Code 확장 프로그램에서도 사용됩니다.
VI 두 버전 비교 (Diff two versions of a VI)
두 개의 .vi 파일 간의 변경 사항(추가/제거된 연산 및 구조체, 재배선된 연결, 변경된 상수)을 확인할 수 있습니다. 코드 리뷰나 CI에 유용합니다.
lvkit diff <vi-a> <vi-b> [--format {text,json,html}] [--open]
텍스트(기본값)는 stdout 또는 CI를 위한 간결하고 논리적인 변경 요약입니다. --format json은 스크립트나 AI 에이전트를 위해 UID와 연관된 변경 맵을 방출합니다. --format html (또는 --open)은 대화형 diff 뷰어를 작성합니다. 이 뷰어는 전/후 패널이 동기화되어 있으며, 변경 사항을 클릭하면 해당 부분이 강조 표시되고(spotlight), 깊은 링크가 가능합니다.
문서 생성 (Generate documentation)
.vi, .lvlib, 또는 .lvclass에 대한 상호 참조 HTML 문서를 생성하며, 여기에는 입력(inputs), 출력(outputs), 연산(operations), 배선 다이어그램(wiring diagrams)이 포함됩니다.
lvkit docs <input-path> <output-dir> [--userlib <user.lib/>]
Python 생성 (Generate Python) (실험적)
이는 lvkit의 가장 성숙도가 낮은 기능이며, 수동 수정이 필요할 가능성이 가장 높습니다. 이 기능은 그래프를 순회하며 .vi, .lvlib, 또는 .lvclass에 대한 Python 번역(transliteration)을 방출합니다. 이 번역 과정은 결정론적입니다 (같은 VI 입력 시 같은 Python 출력, LLM 사용 안 함). 하지만 커버리지는 점진적입니다: lvkit이 매핑할 수 없는 노드는 해당 노드가 실행될 위치에 raise NotImplementedError(...)로 대체되므로, 실제로 생성된 부분이 얼마나 많이 실행되는지 편차가 큽니다. 이러한 격차를 해결하고 출력을 정리하는 작업이 필요합니다 — Cleanroom approach를 참조하십시오.
lvkit generate <input-path> -o <output-dir> [--userlib <user.lib>]
변환할 수 없는 각 노드에 대해, generate는 warning: <VI path>: generate: <node>: <reason> [<kind>]를 출력하고, 해당 노드가 실행될 위치에 raise NotImplementedError("<reason>")를 작성하며, 노드의 출력값은 None으로 설정됩니다. lvkit unresolved는 동일한 격차들을 목록화합니다. generate는 모든 VI가 변환되면 0을 반환하고, 결과가 부분적일 때(격차가 있을 때)는 3을, VI를 작성할 수 없을 때는 1을 반환하며 종료됩니다.
작동 방식 (How it works)
lvkit은 LabVIEW 설치 없이도 VI 바이너리를 직접 읽습니다. 이 파이프라인은 세 단계로 구성되어 있습니다:
-
파싱(Parse) — VI 바이너리는 XML로 추출된 후(pylabview를 통해), 블록 다이어그램의 타입화된 표현(typed representation)으로 파싱됩니다: 노드, 와이어, 상수, 타입, 그리고 프런트 패널 터미널입니다.
-
그래프(Graph) — 로드된 모든 VI는 두 가지를 포착하는 그래프로 연결됩니다: 종속성 트리 (어떤 VI가 어떤 VI를 호출하는지)와 각 VI 내부의 데이터 흐름 (데이터가 연산 간에 어떻게 이동하는지). 이는 describe, render, diff, docs, 및 visualize 명령이 쿼리하는 내용이며, 의미론적 매핑(semantic mappings)은 필요하지 않습니다.
-
생성(Generate) — 그래프는 결정론적으로 순회되어 Python 소스, HTML 문서 또는 다이어그램을 생성합니다. 코드 생성은 순수한 AST (추상 구문 트리) 구성입니다: 동일한 VI를 입력하면 매 실행마다 동일한 출력이 나오며, LLM(대규모 언어 모델)이 필요하지 않습니다.
모든 명령어에 대한 전체 플래그 레벨 문서는 명령어 참조(command reference)를 참고하십시오.
lvkit의 VI가 읽을 수 없는 경우 실행이 중단되지 않습니다: 경고(VI당 하나 및 전체 요약)로 보고되지만, 명령어는 계속 진행되며 종료 코드가 어떻게 끝났는지 알려줍니다: 0은 완료, 1은 중지됨, 2는 사용 오류, 3은 부분적입니다. --fail-fast는 첫 번째 문제 발생 시 다중 VI 실행을 종료합니다. 문제점, 종료 코드 및 --fail-fast를 참조하십시오.
에디터 및 AI 통합 (Editor and AI integration)
CLI는 모든 터미널이나 CI 스크립트에서 독립적으로 작동합니다. 더 깊은 통합을 위해, lvkit은 세 가지 선택적 레이어를 제공합니다.
VS Code 확장(extension) — Marketplace의 LVKit에서 확인할 수 있습니다. .vi 파일을 열면
lvkit setup
lvkit setup claude
lvkit setup copilot
...
총 일곱 개의 워크플로우가 제공됩니다: lvkit, lvkit-describe, lvkit-query, lvkit-convert, lvkit-document, lvkit-review, lvkit-resolve.
MCP 서버 — AI 에이전트가 그래프를 로드하고, 와이어를 따라 이동하며, 여러 VI에 걸쳐 후속 질문을 해야 하는 대화형 IDE 세션용입니다:
{
"mcpServers": {
"lvkit": { "command": "uvx", "args": ["--from", "lvkit", "lvkit-mcp"] }
...
}
| 도구 | 설명 |
|---|
load | VI를 인메모리 그래프에 로드합니다. |
| ... | |
클린룸 접근 방식 (Cleanroom approach)
lvkit은 LabVIEW 소스 코드나 런타임에 접근할 수 없습니다. LabVIEW의 내장 프리미티브(primitives) 및 표준 라이브러리 VI는 의미론적으로 대체됩니다: 각 연산은 열려 있고 검사 가능한 JSON 데이터 파일(src/lvkit/data/primitives.json, src/lvkit/data/vilib/)에 있는 동등한 Python 구현으로 매핑됩니다.
이러한 매핑은 두 가지 공개 입력만을 통해 순전히 추론하여 얻은 lvkit 자체의 정의입니다:
- 공개된 NI 문서: ni.com에 공개적으로 게시되며, 로그인, 파트너 포털 또는 NDA 게이트가 필요하지 않은 페이지입니다.
- pylabview가 생성한 VI XML: VI 바이너리를 XML로 추출하는 오픈 소스 파서입니다. 이 XML이 lvkit의 유일한 형식 접근 창구이며, lvkit은 다른 방식으로 이를 볼 수 없습니다.
정의는 오픈 소스이며 완전히 검사 가능하며, 많은 정의에는 각 항목이 어떻게 추론되었는지(참고된 공개 문서, 관찰된 터미널 시그니처, verified/guess_reason 마커)를 기록하는 메모가 포함되어 있습니다. 이들은 권위적이지 않은 최선의 노력에 의한 추론이며—시간이 지나면서 틀렸다가 수정되기도 했습니다. 이러한 불완전성은 오직 공개 문서와 pylabview XML만을 사용하고, 어떠한 내부 또는 권위적인 NI 사양에도 접근할 수 없기 때문에 발생하는 직접적인 결과입니다.
커버리지는 점진적(incremental)입니다. lvkit generate가 매핑되지 않은 프리미티브 또는 vi.lib VI를 만나면, 해당 매핑을 추가할 수 있도록 진단 컨텍스트와 함께 오류를 발생시킵니다. describe, render, diff, docs, 그리고 visualize는 영향을 받지 않습니다. 이들은 시맨틱 매핑(semantic mappings)이 아닌 그래프로부터 작동하기 때문입니다.
출처 (Provenance)
lvkit은 오직 공개적으로 사용 가능한 정보만을 사용하여, 그리고 클린룸 방식(clean-room methods)으로 개발되었습니다. 이는 LabVIEW 또는 모든 NI 소프트웨어를 설치하거나 실행하지 않았으며, NI의 소스 코드, 내부 또는 비공개 사양, 기밀 또는 독점 자료 없이 구축되었습니다. LabVIEW의 동작에 대한 사실들은 그 자체로 사용되며, NI 문서나 작품은 복사되거나 재배포되지 않습니다. 프리미티브 글리프(primitive glyphs)는 절차적으로 그려지며, 배포된 데이터에는 NI 텍스트나 이미지가 포함되어 있지 않습니다. PROVENANCE.md를 참조하십시오.
상표권 (Trademarks)
프로젝트 로컬 해상도 저장소 (.lvkit/)
프로젝트 루트에 .lvkit/ 디렉터리를 사용하여 번들된 매핑을 보완할 수 있습니다. lvkit은 먼저 .lvkit/를 읽고, 실패 시(fallback) 자체 번들 데이터로 돌아갑니다.
lvkit setup --no-skills를 실행하여 README가 포함된 저장소를 생성하십시오. 이 README에는 프리미티브 및 vi.lib 매핑을 수동으로 추가하기 위한 파일 레이아웃과 JSON 형식이 문서화되어 있습니다.
lvkit generate가 알 수 없는 프리미티브 또는 vi.lib VI에 대해 경고를 표시할 때, 두 가지 옵션이 있습니다:
- 해결 (Resolve it) —
lvkit setup을 실행하여 해상도 스킬(resolve skills)을 설치하고 AI 에이전트가 매핑을 .lvkit/에 작성하도록 한 다음, 다시 생성합니다.
- 유지 (Leave it) — 생성된 Python 코드는 해당 노드에서
NotImplementedError를 발생시키고 다른 모든 곳에서는 정상적으로 실행됩니다.
개발 (Development)
uv sync
pytest
ruff check .
...
기여자 워크플로우, 코드 스타일, 프리미티브 또는 vi.lib 매핑을 추가하는 방법은 CLAUDE.md를 참조하십시오.
라이선스 (License)
Apache-2.0. LICENSE를 참조하십시오.
추가 자료 (Further reading)