Files

T

Antigravity Agent c24165b8bc refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조

에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게
[공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류.
문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인).

- Topic_Programming → Domain_Programming (내부 구조 보존)
- Topic_Graphic → Domain_Design
- Topic_Business → Domain_Product
- Topic_General → Domain_General
- _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning),
  Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing)
- 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서)
- 빈 폴더 정리 (memory/procedures)
- 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-11 11:05:56 +09:00

9.5 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

Workflow.json (Frontend Format)

🎯 한 줄 통찰 (One-line insight)

ComfyUI의 시각적 편집 상태와 노드 간의 논리적 연결을 Litegraph 표준에 따라 완벽하게 보존하여, 인간의 재편집과 기계적 실행 사이의 가교 역할을 수행하는 전제 상태(Full State) 스냅샷 [1, 2].

🧠 핵심 개념 (Core concepts)

Litegraph 표준 준수: ComfyUI 웹 인터페이스의 캔버스 레이아웃을 정의하는 라이브러리인 Litegraph 형식을 따르며, 시각적 렌더링에 필요한 모든 데이터를 포함한다 [1, 2].
시각적 메타데이터(Visual Metadata): 노드의 좌표(pos), 크기(size), 그룹 구성, 색상, 노드의 축소(collapsed) 또는 고정(pinned) 상태 등의 정보를 상세히 기록한다 [1, 3, 4].
명시적 링크 구조(Explicit Links): 노드 간의 연결을 별도의 links 배열 내에서 고유 ID를 가진 명시적 객체로 관리하여 그래프의 시각적 연결성을 유지한다 [2, 3, 5].
노드 식별자(Node Identification): 각 노드는 주로 숫자 형태의 고유 문자열 ID(예: "1", "2")로 식별되며, 이는 그래프 탐색 및 UI 렌더링의 기준이 된다 [1, 2, 6].

🧩 추출된 패턴 (Extracted patterns)

Full UI Export 패턴: 단순히 실행 로직만 저장하는 것이 아니라, 사용자가 작업하던 환경을 그대로 복구할 수 있도록 캔버스의 모든 상태를 캡처하는 방식이다 [7, 8].
Metadata Embedding 패턴: 생성된 PNG 이미지의 tEXt 또는 zTXt 청크에 Frontend JSON 데이터를 주입하여 이미지 자체가 워크플로우 백업 파일 역할을 하도록 설계되었다 [9-11].
역방향 실행 모델(Execution Model Inversion): JSON 내에 수많은 노드가 존재하더라도 실행 엔진은 출력 노드(Save Image 등)부터 역추적하여 필요한 노드만 실행하며, 사용되지 않는 노드는 성능에 영향을 주지 않고 보존된다 [12].

📖 세부 내용 (Details)

Frontend Format인 workflow.json은 ComfyUI의 기본 저장 형식으로, 사용자가 웹 인터페이스에서 워크플로우를 저장하거나 공유할 때 주로 사용된다 [1, 2, 13].

1. 주요 데이터 구조

nodes: 워크플로우를 구성하는 개별 노드들의 배열이다. 각 노드 객체는 클래스 타입(type), 좌표(pos), 크기(size), 실행 순서(order), 모드(mode, 활성/우회 등), 그리고 위젯 설정값(widgets_values)을 포함한다 [4, 14].
links: 노드 사이의 와이어(Wire) 연결을 정의하는 최상위 배열이다. 각 링크는 보통 6개의 요소를 가진 배열이나 객체 형태로, 소스 노드 ID, 소스 슬롯, 타겟 노드 ID, 타겟 슬롯 정보를 담고 있다 [5].
groups: 캔버스 상에서 노드들을 논리적으로 묶어주는 시각적 그룹 정보를 저장한다 [4].

2. API Format(Backend)과의 차이점

Frontend Format은 사용자 인터페이스 정보를 모두 포함하기 때문에 파일 크기가 상대적으로 크며, 백엔드 실행 엔진이 직접 해석하기에는 부적절한 구조를 가지고 있다 [1, 3, 15]. 반면 API Format은 UI 메타데이터를 제거하고 노드 입력 내에 링크 정보를 직접 임베딩하여 실행 최적화에 집중한다 [1, 16, 17].

3. 상호 운용성 및 한계

이미지 기반 로딩: PNG 이미지에 포함된 메타데이터를 통해 워크플로우를 즉시 복구할 수 있으나, 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 메타데이터가 손실될 위험이 있다 [9, 11, 18].
버전 호환성: ComfyUI는 지속적으로 업데이트되므로, 구버전의 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다 [18].
종속성 문제: JSON 파일 자체에는 모델 가중치나 커스텀 노드의 코드가 포함되지 않으므로, 로컬 환경에 해당 노드나 모델이 없을 경우 'Red Box' 오류가 발생한다 [19, 20].

⚖️ 모순 및 업데이트 (Contradictions & updates)

파일 확장자 혼용: 소스에 따라 API 전용 포맷을 workflow_api.json으로, 프론트엔드 포맷을 workflow.json으로 명확히 구분하기도 하지만, 일반적인 대화에서는 모두 '워크플로우 JSON'으로 통칭되기도 한다 [1, 21].
메타데이터 취약성: PNG에 임베딩된 JSON은 압축 소프트웨어나 네트워크 전송 시 소실될 수 있다는 점이 지속적으로 지적된다 [11, 18].

🛠️ 적용 사례 (Applied in summary)

comfyui-workflow-to-api-converter-endpoint: 클라이언트 측의 자바스크립트 로직을 파이썬으로 변환하여, 프론트엔드 형식의 JSON을 API 형식으로 서버 사이드에서 변환하는 기능을 제공한다 (커밋 bc85382 참조) [15, 22, 23].
ComfyUI-to-Python-Extension: 프론트엔드 워크플로우 메타데이터를 포함한 스크립트를 생성하여, 저장된 이미지에서 워크플로우를 재임포트할 수 있도록 지원한다 [24, 25].
ComfyUI-WorkflowGenerator: LLM을 통해 생성된 논리적 구조를 최종적으로 실행 가능한 Frontend JSON 또는 API JSON 포맷으로 빌드하는 WorkflowBuilder 노드를 포함한다 [26, 27].

✅ 검증 상태 및 신뢰도

상태: draft
검증 단계: conceptual (공식 문서 및 다수의 오픈소스 프로젝트에서 핵심 규격으로 사용됨)
출처 신뢰도: B (공식 문서 및 기술 블로그, GitHub 리포지토리를 통한 교차 검증 완료)
중복 검사 결과: 신규 생성

상위/유사 개념

[아키텍처/기반 기술]

Litegraph Standard
- 연결 이유: Frontend JSON 포맷의 구조적 근간이 되는 라이브러리 규격임 [1].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 배치 및 링크 렌더링 원리.
Workflow.api.json (Backend Format)
- 연결 이유: Frontend JSON에서 UI 정보를 제거하고 실행 효율성을 극대화한 대응 포맷임 [1, 3].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 시각적 표현과 논리적 실행 구조의 분리.

[구현/활용 도구]

ComfyUI Manager
- 연결 이유: JSON 내의 class_type을 분석하여 누락된 커스텀 노드를 설치해주는 필수 관리 도구임 [20].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 종속성 관리 및 환경 복구 프로세스.
Workflow Extractor
- 연결 이유: 이미지 메타데이터에 숨겨진 Frontend JSON을 추출하는 전문 도구임 [28, 29].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 보존 및 데이터 복구 기술.

심층 후속 질문 (Deeper Research Questions)

Frontend JSON의 order 필드가 실제 백엔드의 실행 순서와 항상 일치하는가? [14]
PNG 이미지의 tEXt 청크와 zTXt 청크 중 어느 방식이 워크플로우 데이터 저장에 더 유리한가? [11]
comfyui-workflow-to-api-converter-endpoint는 서브그래프(Subgraph)가 포함된 복잡한 프론트엔드 JSON을 어떻게 처리하는가? [23, 30]
노드 ID가 문자열로 저장될 때와 숫자로 저장될 때의 시스템 처리 차이는 무엇인가? [4, 6]
모델 해싱(Model Hashing) 기술이 JSON의 포터빌리티(Portability) 문제를 어떻게 해결하는가? [31]
LLM이 생성한 논리적 다이어그램을 표준 V1.0 스키마에 맞게 검증하는 구체적인 메커니즘은 무엇인가? [26, 32]

실무 적용 맥락 (Practical Application Contexts)

Implementation: 커스텀 앱에서 워크플로우를 로드할 때, 우선 Frontend 포맷으로 불러와 사용자에게 시각적으로 보여준 뒤 실행 시점에만 API 포맷으로 변환하여 요청한다 [33].
System Design: 버전 관리 시스템(Git)에 워크플로우를 저장할 때, 시각적 변경 사항을 추적하기 위해 Frontend 포맷을 유지하는 것이 유리하다 [34].
Operation / Maintenance: 사용자가 공유한 이미지에서 워크플로우를 복원할 수 없는 경우, exiftool 등을 사용해 메타데이터 존재 여부를 선제적으로 확인한다 [29, 35].
Learning Path: 초보자는 시각적 노드 연결 방식을 통해 논리 구조를 익히고, 숙련자는 JSON의 widgets_values를 직접 수정하여 자동화 스크립트를 작성한다 [13, 36].

인접 주변 주제 (Adjacent Topics)

Custom Nodes
- 확장 방향: JSON 내의 type 필드가 실제 파이썬 클래스와 매핑되는 방식 연구.
JSON Schema v1.0
- 확장 방향: 워크플로우 파일의 구조적 무결성을 검증하는 기술적 명세 확인 [14].

📝 변경 이력 (Change history)

2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine based on 18 sources.

9.5 KiB Raw Blame History