Delete custom_nodes/dolphin_nodes/HANDOFF.md

custom_nodes/dolphin_nodes/HANDOFF.md

@@ -1,192 +0,0 @@
-# Dolphin ComfyUI 노드 프로젝트 — 인수인계
-
-## 프로젝트 목적
-ComfyUI에서 **이미지 1장(또는 텍스트 서사) + 로라 + 필수동작**을 넣으면
-**4개의 연속된 5초 비디오 클립(총 20초)** 을 만드는 커스텀 노드 세트.
-
-비디오 체인은 WAN 2.2 Lightning 기반: `First`(clip1) + `Extend`×3(clip2~4 이어붙이기),
-각 클립마다 TripleKSampler(base/high/low 3스테이지)로 샘플링.
-
----
-
-## 현재 쓰는 파일 (7개 노드 + 워크플로우)
-
-### 노드 코드 (커스텀 노드 폴더에 넣기)
-1. **`__init__.py`** — 아래 5개 노드를 등록. 각 등록은 개별 try/except.
-2. **`wan_resizer.py`** — `WanNativeResize_Dolphin`. 이미지를 WAN 해상도(480/720/1080P)로 비율 유지 리사이즈 + 정렬(16배수). (원본 그대로, 수정 안 함)
-3. **`promp_logic_v32_story.py`** — `DolphinMultiActionPromptNode_V32`. 텍스트 서사 → LLM이 4샷 프롬프트로 분배. JSON 강제 + 폴백. 모델 프리셋 드롭다운 있음.
-4. **`arch_logic_v16.py`** — `DolphinArchitectV16`. 클립별 LoRA를 model에만 적용(CLIP 로라 연산 제거로 속도↑) → TripleKSampler 공급. 트리거 통합 1출력. 해시 캐싱.
-5. **`dolphin_director.py`** — `DolphinCinematicDirector`. ⚠️ **사실상 고장난 죽은 코드** (2026-07-03 확인). `_llm_split()`는 아무것도 반환하지 않고 호출되지도 않음, `direct()`는 `mode`/LLM 호출을 무시하고 `clips = [master_story] * 4`로 하드코딩, 로라도 전혀 적용 안 함. `__init__.py`엔 등록돼 있지만 실사용 금지 — 쓰려면 사실상 재작성 필요.
-6. **`dolphin_vision_director.py`** — `DolphinVisionDirector`. **최신 주력 노드**. 이미지 직접 인식(VLM) + 필수동작 N샷 분배(`num_clips`) + 클립당 로라 4개(개별 웨이트, on/off 토글) + 트리거 자동 추출/주입.
-7. **`dolphin_prompt_director.py`** — `DolphinPromptDirector` (2026-07-21 신설). `DolphinVisionDirector`와 **완전히 같은 비전+LLM 프롬프트 엔진**을 쓰되 `MODEL`/로라 관련을 전부 제거하고 프롬프트 문자열(`c1~c4_prompt`)만 뽑는 버전. 로직 중복을 피하려고 `DolphinVisionDirector`를 내부에서 인스턴스화해 `_vision_analyze`/`_plan_shots`/`_local_split`/`_build_final` 등 로라를 안 건드리는 순수 메서드만 위임 호출 — 프롬프트 정책(연속성 규칙 등)을 고치면 `dolphin_vision_director.py` 한 곳만 고치면 이 노드에도 자동 반영됨. 로라/모델 적용은 `DolphinArchitectV16` 같은 별도 노드에서 처리한다는 전제.
-
-### 워크플로우 JSON
-- **`0705_vision2.json`** — **현재 실사용 중인 최신 워크플로우** (2026-07-03 기준). VisionDirector + JoyCaption(`JC` 노드) 로컬 캡션 우선 사용, `Model Loader`(f9a6f9ae 서브그래프)에서 lightx2v rank256 + SVI_v2_PRO rank128 사전 적용 → DolphinVisionDirector에서 클립별 PENISLORA(rank32) 패치 → ModelSamplingSD3 → NAG → TripleKSamplerWan22LightningAdvanced(First/Extend). 61개 노드, 서브그래프 16개.
-- `0705_vision.json` — vision2 이전 버전.
-- `0705_director.json` — CinematicDirector(텍스트) 버전. 위 5번 참고 — 노드 자체가 고장나 있어 이 워크플로우도 실동작 안 함.
-- `0705_optimized.json` — V32 + Architect V16 분리형 버전.
-(원본은 사용자가 처음 올린 `0705.json`. API 키는 vision/director/optimized 등 배포용 JSON에선 비워두는 게 원칙이나, `0705_vision2.json`은 사용자 로컬 작업본이라 실키가 들어있음 — 아래 "미해결" 참고.)
-
----
-
-## DolphinVisionDirector 상세 (주력 노드)
-
-### 입력
-- `image` (IMAGE) — WanNativeResize 출력에서
-- `model_base / model_high / model_low` (MODEL) — Model Loader에서
-- `essential_actions` — **필수 동작만** 콤마로. LLM이 이걸 N샷으로 분배.
-- `num_clips` (2026-07-03 추가) — `"4 (20s)"`/`"3 (15s)"`/`"2 (10s)"`, 기본 4. 실제 렌더링/저장될 클립 수를 여기서 단일 결정 (아래 "클립 개수 중앙 제어" 참고).
-- `character_name` (AUTO면 LLM이 작명), `artistic_vibe`, `pacing`, `detail_level`
-- `inject_triggers`(토글), `use_vision`(토글)
-- `openrouter_api_key`
-- `vlm_preset` + `vlm_model` — 비전 모델 (기본 Qwen2.5-VL 72B)
-- `llm_preset` + `llm_model` — 텍스트 분배 모델 (기본 DeepSeek V3.2)
-- `creativity`, `seed`
-- 로라: **`c{1..4}_lora_{1..3}`** (드롭다운) + **`c{1..4}_w_{1..3}`** (웨이트 문자열 `"base, high, low"`)
-- `manual_triggers`
-
-### 출력 (23개, 2026-07-03 기준)
-- `c1_base, c1_high, c1_low, c1_prompt` × 4클립 (16개) — `num_clips`보다 큰 클립은 base/high/low가 `ExecutionBlocker(None)`
-- `triggers` — 사용된 모든 로라 트리거 통합
-- `scene_analysis` — VLM이 이미지에서 읽은 앵커
-- `debug_info`
-- `c1_is_final, c2_is_final, c3_is_final, c4_is_final` (2026-07-03 추가) — `c == num_clips`인 클립만 True. 각 단계별 VideoCombine의 `save_output` 입력에 연결해서 선택한 길이만 저장되게 함.
-
-### 로라 웨이트 규칙 (스크린샷의 Triple Lora Matrix 방식 채택)
-- 로라당 웨이트를 `"base, high, low"` 한 줄로. 예: `0.3, 0.8, 0.0`
-- 값 부족 시 마지막 값으로 채움 (`1.0`→전부 1.0, `0.5, 0.7`→base 0.5/high·low 0.7)
-- **스테이지 분리 로라 지원**: WAN 2.2에서 HIGH 로라는 `0.3, 0.8, 0.0`(low=0), LOW 로라는 `0.0, 0.0, 0.4`(base·high=0)로 나눠 씀. 검증 완료.
-- 웨이트 0인 스테이지는 그 로라를 안 붙임.
-
-### 프롬프트 설계 (사용자 요구 반영 완료)
-- **동작 순서 보존**: essential_actions는 시간순. 뒤 동작은 clip3 후반~clip4에만 (front-loading 금지).
-- **묘사 배제**: 환경/조명/의상/분위기 다 빼고 **동작(신체 움직임)만**.
-- **타임코드 제거**: `[0-1s]` 방식은 WAN I2V에서 노이즈라 뺌.
-- **슬로우모션 방지**: (1) 5초를 연속 동작으로 채움 (2) 속도 어휘(swiftly/rapidly/explosively) (3) "real-time speed, no slow motion, no freeze" 명시.
-- master_scene은 비움(묘사 안 함).
-- 비전 역할은 "묘사"가 아니라 "앵커(캐릭터 상태/자세/환경) 추출"로 좁혀 장황함 억제.
-
----
-
-## 모델 프리셋 (OpenRouter, NSFW/무삭제 대응)
-
-### 텍스트 LLM (4샷 분배용)
-- `deepseek/deepseek-v3.2` (기본, 무삭제+JSON안정+한국어 좋음) ← 추천
-- `deepseek/deepseek-chat-v3-0324`
-- `anthracite-org/magnum-v4-72b` (표현 자연스러움)
-- `thedrummer/cydonia-24b-v4.1` (경량)
-- `cognitivecomputations/dolphin-mistral-24b-venice-edition:free` (무료)
-- custom 선택 시 텍스트 필드값 사용
-
-### 비전 VLM (이미지 인식용)
-- `qwen/qwen2.5-vl-72b-instruct` (기본, 특수상황 강함) ← 추천
-- `qwen/qwen2.5-vl-32b-instruct` (+ `:free` 무료)
-- `mistralai/mistral-small-3.1-24b-instruct` (Pixtral)
-- `google/gemma-3-27b-it`
-
-이미지 전송: ComfyUI IMAGE 텐서 → JPEG base64 data URI → OpenRouter `image_url` content block. (PIL 필요, ComfyUI 기본 포함)
-
----
-
-## 미해결 / 다음에 할 수 있는 것
-
-### 다음 세션 최우선 확인 사항 (2026-07-03 세션 종료 시점)
-1. **`lightning_steps` 8→4 수정 실사용 검증** — 슬로우모션 증상의 유력 원인으로 지목하고 고쳤지만(아래 3번 상세), 아직 실제 렌더로 개선 확인 안 함. ComfyUI는 이미 재시작됨(코드 변경 반영 완료), 워크플로우만 새로고침해서 한 번 돌려볼 것.
-2. **`num_clips`/`Extend range` 관계 숙지** — `num_clips`가 이제 유일한 클립 개수 컨트롤. "Extend range"(Fast Groups Bypasser) 토글은 **절대 건드리지 말 것**(구 방식과 충돌).
-3. ~~`openrouter_api_key` 평문 제거~~ **완료(2026-07-21)** — 아래 6번 참고.
-4. **git 저장소 신설(2026-07-21)** — `dolphin_nodes`에 로컬 git 초기화 + 현재 상태 전체(코드/워크플로우/`old/`/`.bak_*`) 첫 커밋 완료. 앞으로 파일 수정 전 `.bak_*`/`_v조` 파일 복사하는 습관은 그만두고 `git commit`으로 대체할 것. `old/` 폴더와 17개 `.bak_*` 파일은 이제 git 히스토리로도 안전하게 보존돼 있으니, 폴더 정리(삭제)는 다음 세션에서 사용자 확인 후 진행 가능.
-
-1. **NSFW 비전 모델 (해결)** — `0705_vision2.json`은 로컬 JoyCaption(`JC` 노드, `vision_caption` 입력)으로 OpenRouter VLM을 우회 중. `use_vision` 위젯은 **재확인 결과 이미 `true`(ON)로 켜져 있음** — JoyCaption이 성공하면 `vision_caption`을 우선 쓰고 VLM 호출 자체가 안 일어나지만, JoyCaption이 실패/빈 응답이면 이제 안전망으로 OpenRouter VLM 폴백이 작동함. 실행 로그(`debug_info`)에서도 `vlm=vision ok (local caption node)`로 정상 확인됨.
-   - 클라우드 무삭제+이미지 동시지원 모델은 여전히 드묾(Qwen2.5-VL이 그나마 관대). 완전 로컬 VLM 전환은 대안 B로 남아있음(현재는 JoyCaption 로컬 캡션으로 사실상 우회 중이라 급하지 않음).
-
-2. **로라 드롭다운 검색/필터** — 노드 코드로 불가. ComfyUI 프론트엔드 기능이라 ComfyUI 업데이트로 해결하거나 rgthree-comfy 설치 필요.
-
-3. **슬로우모션/연기 일관성**:
-   - **클립 "안"의 슬로우모션 (2026-07-03 원인 특정, 수정 적용함 — 실사용 검증 아직)**: 로라 파일명(`Wan_2_2_I2V_A14B_HIGH/LOW_lightx2v_4step_lora_...`, 그 외 D:/sd/models/loras의 다른 Lightning 로라들도 전부 "4step/4steps")이 전부 **총 4스텝 증류**를 명시하는데, 워크플로우의 TripleKSampler 4개(clip1~4, node 532/484/480/1077) 전부 `lightning_steps=8`(HIGH 4 + LOW 4, 50% 지점 분할)로 설정돼 있었음 — 증류 스텝의 **정확히 2배**. 증류된 Lightning 모델에 계산보다 많은 스텝을 쓰면 스케줄을 벗어나서 동작이 억눌리고 뭉개지는(슬로우모션처럼 보이는) 현상이 흔함. **`lightning_steps`를 4개 노드 전부 8→4로 변경 완료**(��업: `0705_vision2.json.bak_20260703_before_lightningsteps`). 나머지 값(sigma_shift=5, switch_strategy="50% of steps" 등)은 그대로 — 2 HIGH + 2 LOW로 재분배됨. **다음 세션에서 실제 렌더로 개선 여부 확인 필요**.
-     - 참고로 조사 중 "외부 ModelSamplingSD3 서브그래프(shift=5) + TripleKSampler 자체 내부 sigma_shift=5 이중 적용" 가설도 검토했으나, `comfy/model_sampling.py`의 `set_parameters()`가 매번 새 model_sampling 객체로 완전히 덮어쓰는 방식이라 **이중 적용해도 누적 안 됨**(같은 값으로 두 번 걸면 한 번 건 것과 동일) — 이건 범인 아님, 낭비적이지만 무해한 중복이라 안 건드림.
-   - **클립 "사이" 연속성(2026-07-03 해결)**: `_plan_shots` 시스템 프롬프트에 rule 3 "INTER-CLIP CONTINUITY" 추가 — clip_N이 clip_(N-1) 끝난 자세/모멘텀에서 이어서 시작하도록 명시. I2V 프레임 체인(마지막 프레임 그대로 다음 클립 시작)은 원래도 있었지만, 텍스트 프롬프트가 그 연속성을 언급 안 해서 "따로 노는 동작"처럼 보일 수 있었던 gap을 메움. 실사용 검증은 아직 안 함 — 다음 세션에서 4클립 이어보고 확인 필요.
-
-4. **동일 로라 중복 로딩** — 4클립 같은 로라면 4번 패치(클립별 유연성 위한 의도적 트레이드오프). 캐싱 최적화 가능하나 미적용.
-
-5. `dolphin_director.py`(텍스트 버전) — 위 "현재 쓰는 파일" 참고, 로라 방식 통일 이전에 **노드 자체가 동작하지 않음**. 재작성하거나 `__init__.py`에서 등록 제거할지 결정 필요.
-
-6. **`0705_vision2.json` 워크플로우 정리 항목 (2026-07-03 감사)**:
-   - ~~`use_vision` OFF → ON 권장~~ **재확인 결과 이미 `true`로 바뀌어 있었음** (핸드오프 기록이 낡았던 것, 실제 위젯값 재확인 완료).
-   - ~~죽은 `StringConcatenate` 노드(id 1062)~~ **이미 삭제돼 있음** (재확인 완료).
-   - ~~`openrouter_api_key` 위젯에 여전히 실키가 평문 저장돼 있음~~ **해결됨(2026-07-21)**: 키를 Windows User 환경변수 `OPENROUTER_API_KEY`로 옮기고, `0705_vision2.json` + 모든 `.bak_*` + `v30.json` + 중복본(`0705_vision2 (1).json`)에서 키 문자열 전부 제거 후 git 커밋(그래서 git 히스토리에도 안 들어감). `resolve_api_key()`가 위젯 비어있으면 자동으로 env var 사용. ComfyUI도 새 env var 반영을 위해 재시작함 — **다음 세션에서 debug_info가 `vlm=no api key`로 뜨진 않는지만 확인하면 끝**.
-   - `triggers` 출력 포트 미연결(디버깅용, 급하지 않음).
-
-7. **검증 완료 (2026-07-03) — 더 이상 의심 안 해도 됨**:
-   - **로라 인젝션 체인 전수 확인**: `Model Loader`(553) → `DolphinVisionDirector`(1086) → `ModelSamplingSD3` → `NAG` → `TripleKSamplerWan22LightningAdvanced`(First/Extend) 까지 4클립 전부 끊김/교차배선 없이 연결됨. 파일 경로 전부 실재, weight 0/None 오류 없음. 실행 로그(`comfyui_restart_log.txt`)에도 트리거워드 `PENISLORA` 주입 확인됨.
-   - **lightx2v는 이미 rank256으로 적용 중** (HIGH/LOW 둘 다, weight 1.0), SVI_v2_PRO rank128과 스택. `model_base`(stage1)엔 lightx2v 미적용(의도된 설계 — stage1은 non-lightning 풀스텝), `model_high`/`model_low`(stage2/3)에만 적용.
-   - PENISLORA HIGH(e320)/LOW(e496)는 rank32 (안전텐서 텐서 shape로 직접 확인).
-
----
-
-## 최근 수정 이력 (dolphin_vision_director.py)
-
-### 2026-07-03 세션
-- **`_plan_shots` 에러 삼킴 버그 수정**: LLM 4샷 분배 API 호출 실패 시 실제 원인(HTTP 코드/본문, 예외 타입, 불완전 JSON)이 `last` 변수에만 담기고 버려져서 `debug_info`엔 항상 "⚠️ plan failed"만 찍혔음. 이제 원인이 그대로 `debug_info`/콘솔에 남음.
-- **API 키 환경변수 폴백 추가**: `resolve_api_key()` 함수 — `openrouter_api_key` 위젯이 비어있으면 `OPENROUTER_API_KEY` 환경변수 사용. 기존 위젯에 키가 있으면 동작 그대로(하위호환), 워크플로우 JSON에 실키를 안 박아둬도 되게 하려는 목적.
-- **클립 간 물리적 연속성 규칙 추가** (`_plan_shots` 시스템 프롬프트): 새 rule 3 "INTER-CLIP CONTINUITY" — clip_N은 clip_(N-1)이 끝난 정확한 신체 위치/모멘텀에서 이어서 시작(단, "continuing from" 같은 연결 문구를 텍스트에 직접 쓰는 건 금지 — 물리적 일관성만 지키고 "동작만 쓴다" 규칙과 안 부딪히게). 기존 rule 2(clip_1은 이미지 속 자세에서 시작)는 clip_1에만 적용됐던 걸 clip_2~4로 확장한 셈. 규칙 번호 3~8이 4~9로 밀림(내부 상호참조도 전부 갱신됨).
-- **미사용 데드코드 제거**: `_fallback_name_deterministic` (호출부 없음, 주석에도 "미사용"이라 표시돼 있었음).
-- **백업**: 위 변경 전 버전을 `old/dolphin_vision_director_pre_continuity_20260702.py`에 저장.
-- **`0705_vision2.json` 전수 감사** + **���라 인젝션 체인 전수 검증** — 상세는 위 "미해결" 6번/7번 항목 참고.
-- **ComfyUI 재시작 완료**: 기존 프로세스(PID 5452) 종료 후 동일 실행 옵션(`--enable-dynamic-vram --use-sage-attention --output-directory D:\sd\output`)으로 재기동, `dolphin_nodes` 에러 없이 로드 확인, `DolphinVisionDirector` API 등록 확인. 재시작 로그는 `comfyui_restart_log.txt`(stdout) / `comfyui_restart_log.txt.err`(stderr, 진행상황 대부분 여기).
-- 문법 컴파일(`py_compile`) 확인 완료. **아직 실제 4클립 생성 재실행으로 rule 3 효과는 검증 안 함** — 다음 세션 우선 확인 사항.
-
-### 2026-07-03 세션 (이어서) — 메모리 정리 / 클립 개수 중앙 제어 / 속도 실험
-
-**1. VRAM 정리 자동화 (해결)**
-- 증상: 워크플로우 실행 후 VRAM이 절반쯤 계속 점유된 채 안 비워짐. 원인은 버그가 아니라 ComfyUI의 정상 캐싱 동작(다음 실행 빠르게 하려고 마지막 쓴 모델을 VRAM에 남겨둠) — 다만 이걸 강제로 비워주는 노드가 그래프에 없었음.
-- 이미 설치돼 있던 `comfyui_memory_cleanup` 커스텀 노드(`VRAMCleanup`, 표시명 "🎈VRAM-Cleanup")를 최종 저장 노드(`VHS_VideoCombine` id 487)의 출력에 연결(node 1092, `offload_model=True, offload_cache=True`) → 렌더 끝나면 자동으로 `unload_all_models()` + `soft_empty_cache()` 실행됨. 위치는 First-I2V bypass 그룹 박스 안에 잘못 들어갔던 걸 나중에 밖으로 재배치함(그룹 좌표 [3450, -509]로 이동, 어떤 그룹에도 안 걸리게).
-- 트레이드오프: 다음 생성 시작 시 모델을 디스크에서 다시 로드해야 해서 첫 스텝 전 로딩 시간이 늘어남.
-
-**2. 클립 개수(10s/15s/20s) 중앙 제어 — `DolphinVisionDirector`가 단일 컨트롤 포인트 (해결)**
-- 처음엔 워크플로우에 이미 있던 "Extend range"(rgthree `Fast Groups Bypasser`, node 332) 토글로 clip3/4 렌더를 스킵하는 방식을 검토했으나, 이 노드는 **순수 프론트엔드 전용**(백엔드 미등록, `RgthreeBaseVirtualNode`)이라 다른 노드가 프로그래밍적으로 제어 불가 + `num_clips`와 별도로 수동 동기화해야 하는 문제가 있어서 폐기.
-- 대신 `DolphinVisionDirector`에 `num_clips` 위젯(`"4 (20s)"`/`"3 (15s)"`/`"2 (10s)"`, 기본 4, 하위호환) 추가. `_split_actions_to_clips`/`_plan_shots`(LLM 시스템 프롬프트+JSON 스키마)/`_local_split`(폴백) 전부 클립 개수에 맞춰 동적으로 동작하도록 일반화(마지막 동작=마지막 클립 규칙, 연속성 규칙 모두 N클립 대응). num_clips보다 큰 클립 인덱스는 essential_actions 배분에서 제외되고, 마지막 실사용 클립 내용을 반복해서 채움(안전장치).
-- **실제 렌더 스킵은 ComfyUI 네이티브 `ExecutionBlocker`로 구현** (`from comfy_execution.graph_utils import ExecutionBlocker`): `num_clips`보다 큰 클립의 `c{N}_base/high/low` 출력에 `ExecutionBlocker(None)`을 반환 → 그 아래 `ModelSamplingSD3→NAG→TripleKSampler→해당 클립 VideoCombine` 체인 전체가 연산 없이 자동 스킵됨(서브그래프 내부는 안 건드림 — DolphinVisionDirector가 top-level에서 서브그래프 인스턴스로 모델을 넘기는 구조라 출력 쪽만 바꾸면 됨).
-- **정확한 길이만 저장**: 새 BOOLEAN 출력 4개 `c1_is_final~c4_is_final`(RETURN_TYPES/NAMES 19→23개로 확장, `direct()`가 `c == n_clips`로 계산) 추가 → 각 단계별 `VHS_VideoCombine`(1091=5s/456=10s/464=15s/487=20s)의 `save_output` 위젯을 입력으로 변환(convert widget to input, `frame_rate`가 이미 이렇게 돼있던 패턴 재사용)해서 연결. 실행되지만 최종이 아닌 중간 클립은 미리보기로만 남고, `num_clips`가 선택한 길이 딱 하나만 디스크에 저장됨. 각 VideoCombine 파일명도 `_5s/_10s/_15s/_20s` 접미사로 구분해둠(예전엔 `Wan2`라는 구분 안 되는 접두사였음).
-- "Extend range" 노드는 이제 완전히 불필요 — **토글을 절대 건드리지 말 것**(건드리면 옛날 bypass 방식과 새 ExecutionBlocker 로직이 충돌해서 혼란스러운 결과 가능). 삭제할지는 미결정, 일단 놔둠.
-- 백업 다수: `0705_vision2.json.bak_20260703_before_vramcleanup`, `..._before_torchcompile`, `..._before_numclips`, `..._before_isfinal_wiring`, `..._before_torchcompile_revert`, `..._before_lightningsteps`.
-
-**3. 속도 실험 — 둘 다 실익 없어서 원복/포기**
-- **torch.compile**: `TorchCompileModel` 노드 3개(base/high/low, 클립당 1회만 컴파일되게 Model Loader 출력 쪽에 배치)로 테스트 → 실행 로그에 `torch._dynamo hit config.recompile_limit (8)` 반복(원인: `attention_sage`와 WAN 모델 forward의 `tensor_shape` 속성 접근이 dynamo가 추적하기 어려운 커스텀 텐서 서브클래스라 매번 재컴파일 필요 → 8회 만에 조용히 eager 폴백). 컴파일 이득 0, 오히려 실패 컴파일 시도로 시간 낭비 ��� **노드 3개 제거, 원래 직결 배선 복원함**.
-- **SageAttention 3 (Blackwell/RTX5090 전용, FP4 텐서코어, 논문상 RTX5090 5x/비디오모델 end-to-end 약 3x)**: 소스 빌드 시도했으나 순서대로 3개 문제 부딪힘 — ① PyTorch(cu130)와 시스템 nvcc(12.8) 메이저 버전 불일치(→ `torch.utils.cpp_extension._check_cuda_version` 몽키패치로 우회 성공) ② Windows `MAX_PATH`(260자) 초과로 CUTLASS 헤더를 못 찾음(→ `C:\sage3build`처럼 짧은 경로로 재클론해서 해결) ③ **CUTLASS 템플릿(`BlockScaledConfig::LayoutSF`/`SfAtom`)에서 MSVC C2061 컴파일 에러** — CUTLASS 버전을 sageattn3 코드 작성 시점(2026-01-14 커밋)까지 맞춰봐도 동일 에러 재현, 패키지 PyPI 분류자도 `"Operating System :: Unix"`라 애초에 Linux/GCC 전용 개발로 보임 → **MSVC 템플릿 2단계 name lookup 호환성 문제로 결론, 빌드 포기**. 빌드 흔적(`C:\sage3build`, 스크래치 클론) 삭제 완료, `sageattn3`은 site-packages에 설치 안 됨(ComfyUI 환경 무변경).
-  - 참고: KJNodes(`comfyui-kjnodes`)의 `PathchSageAttentionKJ` 노드(`KJNodes/experimental` 카테고리)가 `sageattn3` 모드를 이미 지원하므로, 나중에 WSL2 등 Linux 환경에서 별도로 빌드에 성공하면 **ComfyUI 코어를 안 건드리고** 이 노드만 워크플로우에 추가해서 바로 쓸 수 있음(다만 WSL에서 빌드한 건 Windows 네이티브 Python엔 못 씀 — ComfyUI 자체를 WSL로 옮기는 게 아니라면 의미 없음, 별도의 큰 결정 필요).
-  - 현재 상태: 기존 `sageattention` v2.2.0(cu130torch2.9.0 빌드) 그대로 유지, `--use-sage-attention` 플래그로 정상 작동 중. RTX 5090(sm_120) 전용 커널은 없지만(v2는 sm80/89/90까지) 크래시 없이 잘 돎.
-
-### 3대 버그 수정
-- **① 캐릭터 이름 AUTO로 샘**: 비전 앵커로 동양/서양 판단해 작명하도록 프롬프트 강화 + `_fallback_name()` 안전장치(LLM이 AUTO/빈값 반환 시 앵커 키워드로 이름 선택).
-- **② 마지막 동작을 처음부터 함**: `_split_actions_to_clips()`가 동작을 코드에서 클립별로 미리 배정(마지막 동작은 반드시 clip4), LLM엔 배정표를 못박아 전달. 순서 위반이 최우선 금지 규칙.
-- **③ 트리거워드 안 들어감**: `triggers` 출력 부활 + 클립별 로라 트리거 디버그(`_last_trig_dbg`) 콘솔 출력.
-
-### 비전 진단 강화 (사용자가 "비전 작동 의심" 제기 후)
-- `tensor_to_base64`: PIL/None/인코딩 실패를 명확한 콘솔 에러로. 성공 시 이미지 크기 로그.
-- `_vision_analyze`: VLM 응답 원문/HTTP 에러/빈 응답을 콘솔에 출력.
-- `direct` STEP1: use_vision OFF / no key / no image / encode fail 각각 구체적 debug_v 메시지.
-- **debug_info 출력만 봐도 비전 실패 원인 파악 가능**:
-  - `vlm=no api key` → 키 미입력 (사용자 증상의 유력 원인)
-  - `vlm=vision OFF` → 토글 꺼짐
-  - `vlm=no image` → IMAGE 미연결
-  - `vlm=vision HTTP 400` → VLM 거부(슬러그 오타/NSFW 거부)
-  - `vlm=vision empty response` → 빈 응답
-  - `vlm=vision ok` → 정상
-
-### 진단 결론
-"씬 묘사 없음 + AUTO + 바로 동작" 증상 = 비전+LLM 실패 후 로컬 폴백. **가장 유력한 원인은 openrouter_api_key 미입력**(워크플로우에서 보안상 비워둠). 다음 실행 시 debug_info 확인 필요.
-
-### 프롬프트 정책 (확정)
-- 타임코드([0-1s]) 제거 (WAN 노이즈). 대신 연속동작+속도어휘로 슬로우모션 방지.
-- 묘사(환경/조명/의상) 배제, 동작만. master_scene 비움.
-- 동작 순서 보존, 마지막 동작은 clip4.
-
----
-
-## 중요 참고
-- **git 저장소 있음 (2026-07-21부터)**: `dolphin_nodes` 자체가 로컬 git 저장소(`git init` 완료, 원격 없음/로컬 전용). 상위 ComfyUI 저장소의 `.gitignore`가 `custom_nodes/`를 통째로 무시해서 이 폴더는 별도 독립 저장소로 관리. `.gitignore`는 `__pycache__/`, 런타임 로그, `dolphin_tags_cache.json`, `.claude/settings.local.json` 제외. 커밋 전 `git status`/`git diff`로 확인 습관화, 새 `.bak_*` 파일 만드는 대신 `git commit` 사용.
-- **위젯 이름이 바뀌면** 기존 저장 워크플로우의 로라 설정이 초기화될 수 있음. VisionDirector는 최근 `_h_clip` 헤더 제거 + `c{c}_lora_{n}` 이름으로 변경됨.
-- 모든 노드: `INPUT_TYPES`의 required 순서 = 함수 시그니처 순서 (ComfyUI 규칙). 수정 시 AST로 일치 검증할 것.
-- 워크플로우 편집 후엔 항상 무결성 체크: dangling_in / backref_mismatch / slot_oob 전부 0이어야 함. (단, `outputs[].links`에 참조된 링크 id가 top-level `links`에도 서브그래프 `definitions.subgraphs[].links`에도 없는 "유령 출력링크"는 정상적으로 존재할 수 있음 — 과거 편집 잔재로, ComfyUI가 로드시 무시하는 것으로 보임. `0705_vision2.json`의 negative prompt 노드(817)/서브그래프(553)에 ~1700개 있었���데 실행엔 지장 없었음.)
-- 원본 `0705.json`의 UUID 노드들은 subgraph (First/Extend/Encode 등). `definitions.subgraphs[]`에 정의가 있고, 인스턴스 노드의 `type` 필드가 그 서브그래프의 `id`(UUID)와 일치.
-- **`0705_vision2.json` LoRA/모델 체인 구조** (디버깅 시 참고): `Model Loader`(553, "f9a6f9ae..." 서브그래프)에서 GGUF 베이스 로드 + lightx2v(rank256) + SVI_v2_PRO(rank128)를 미리 적용해 `MODEL`(slot0, =model_high, lightx2v 있음)/`MODEL_1`(slot1, =model_low, lightx2v 있음)/`MODEL_2`(slot4, =model_base, lightx2v **없음** — stage1은 non-lightning 풀스텝이라 SVI만 적용) 3종을 출력 → `DolphinVisionDirector`가 클립별 캐릭터 로라를 추가 패치 → 클립마다 `ModelSamplingSD3` 서브그래프 → `NAG`(WanVideoNAG) 서브그래프 → `First`/`Extend` 서브그래프 내부 `TripleKSamplerWan22LightningAdvanced`로 도달. 클립1=786/787/453(First), 클립2=791/792/462(Extend), 클립3=793/794/463(Extend), 클립4=1070/1071/1080(Extend) — 각각 ModelSamplingSD3/NAG/샘플러 순. (444는 별개의 "Encode" 서브그래프로 이미지→latent 변환만 담당, 이 모델 체인과 무관.)