h-lab/docs/shortform-queue-skill-portable.md

shortform-queue 스킬 이식 가이드 (다른 PC용)

이 파일 하나만 가져가면 된다. 새 PC의 Claude Code에게 이렇게 말하면 끝:

이 md 읽고 shortform-queue 스킬 등록해줘

Claude에게: 설치 절차

1. 아래 "SKILL.md 전문"을 그대로 스킬 파일로 저장한다.
   • h-lab 저장소가 있는 PC면(권장): <h-lab 루트>/.claude/skills/shortform-queue/SKILL.md — 사실 repo에 이미 포함되어 있으니 clone/pull만 됐다면 이 단계는 불필요.
   • repo 없이 전역으로 쓰려면: ~/.claude/skills/shortform-queue/SKILL.md
2. 저장 후 사용자에게 "스킬 등록 완료, '숏폼 큐 돌려줘' 또는 '1단계만 돌려줘'로 실행 가능"이라고 알린다.
3. 아래 "PC별 확인사항"을 점검하고, 경로가 다르면 SKILL.md 안의 경로를 그 PC에 맞게 고친다.

PC별 확인사항 (스킬이 돌아가기 위한 전제)

항목	내용
h-lab 저장소	git clone https://h-git.tolag.shop/hehihoho3/h-lab.git — 스킬이 localhost:8088 서버를 띄워야 함
JDK 21	SKILL.md의 JAVA_HOME=D:\Development\app\JDK\jdk-21.0.5는 원래 PC 경로. 새 PC의 JDK 21 경로로 수정
DB 시크릿	git-ignored src/main/resources/application-local.yml 필요 — 원래 PC에서 복사해올 것 (없으면 서버 기동 실패: "Failed to determine suitable jdbc url")
크롬 + Claude in Chrome 확장	브라우저 자동화(Opal 조작)에 필수. opal.google 사이트 권한 허용
구글 로그인	Opal은 구글 계정 로그인 필요 — 크롬에 로그인돼 있어야 함

SKILL.md 전문

---
name: shortform-queue
description: h-lab 숏폼 큐의 대기 작업을 구글 Opal "숏폼 생성기"로 실행하고 결과를 DB에 저장. "숏폼 큐 돌려줘", "/shortform-queue", "숏폼 돌려줘", "1단계만 돌려줘" 요청 시 사용.
---

# 숏폼 큐 실행 (Opal 브라우저 대행)

h-lab(localhost:8088)의 PENDING 작업을 Opal로 실행해 결과를 저장한다.
h-lab 서버가 꺼져 있으면 먼저 `.\gradlew.bat bootRun`(JAVA_HOME=D:\Development\app\JDK\jdk-21.0.5)으로 띄운다.
서버 시크릿은 git-ignored `application-local.yml` — 이 워크트리에 없으면 메인 워크트리(`D:\Development\InteliJ_repository\h-lab\src\main\resources\`)에서 복사.

## 모드 선택

| 요청 | 앱 | URL | 출력 형식 |
|------|-----|-----|----------|
| "숏폼 큐 돌려줘" (기본) | 숏폼 생성기 (풀버전) | `https://opal.google/edit/1w3mThvSpI3_skt4p4OAN3-M6-tnqz0HN` | `N=====` 구간 5개 + cuts JSON |
| "1단계만 돌려줘", "숏폼 1단계" | 숏폼 생성기 1단계 | `https://opal.google/edit/1Z9zXUiBAjKKOJ08zXxAmE9Neliq86SEw` | `{"candidates":[...]}` JSON 하나 |

사용자가 Opal URL을 직접 주면 그 URL 우선. 파서(ShortformOutputParser)는 두 형식 모두 인식한다(88179bb) — 어느 모드든 저장하면 DONE + 클립 5개.

## 절차 (공통)

1. **큐 조회**: `GET http://localhost:8088/api/shortform/jobs?status=PENDING` → 비어있으면 "대기 작업 없음" 보고 후 종료.
2. **Opal 접속**: 크롬 자동화로 모드에 맞는 편집 화면 접속. 로그인 풀려 있으면 사용자에게 로그인 요청.
3. 각 PENDING 작업마다:
   a. 캔버스의 **YouTube Video 노드 클릭** → 우측 패널 URL 입력창을 비우고(전체선택 ctrl+a 후 덮어쓰기) 작업의 youtubeUrl 입력 → **Apply** (썸네일이 해당 영상으로 바뀌는지 확인).
   b. Preview 패널의 새로고침(리셋) 아이콘 → **Start** 클릭.
   c. **완료 폴링** 및 **추출**: 모드별 절차(아래) 참조.
   e. **저장**: 브라우저 fetch는 HTTPS→HTTP라 차단됨 — 추출 텍스트를 파일로 옮겨 셸에서 `POST http://localhost:8088/api/shortform/jobs/{id}/result` body `{"rawText": "<Output 원문>", "step1Text": "<Step 1 원문>"}`. PowerShell은 UTF-8 바이트로 전송(`[Text.Encoding]::UTF8.GetBytes`), 응답 한글이 깨져 보이는 건 PS 5.1 표시 문제이므로 검증은 curl로. 응답의 clips가 5개 미만이면 원문과 함께 보고.
4. **에러 처리**: 특정 Step 노드가 빨간 표시로 실패하면 Preview 리셋 → Start로 1회 재실행. 재실패 시 해당 작업은 건너뛰고 사유를 보고(저장하지 않음 — PENDING 유지). 프롬프트 노드 끝에 중복 YouTube Video 칩이 생겼는지 확인(2026-08-03에 이 원인으로 ID 3이 항상 실패했음).
5. **보고**: 처리한 작업 수, 성공/실패 목록, h-lab `/shortform` 링크로 요약.

## 풀버전 모드 (기본)

- **완료 폴링**: 40~60초 간격 스크린샷. "Thinking... Step N" 진행 표시가 사라지고 Output(1===== 형식)이 렌더링되면 완료. 전체 4~5분 소요(Step 3 다섯 개가 각 ~90초 병렬).
- **Output 추출**: 앱 UI는 접근성 트리에 안 잡힌다. javascript_tool로 `document.getElementById('opal-app').contentDocument`에서 shadow DOM을 재귀 관통해 `"cuts"`를 포함한 **가장 긴** innerText를 찾는다. 텍스트가 크면 window 변수에 저장 후 900자 단위로 나눠 회수한다.
- **Step 1 결과 추출**: Console 탭에서 "Step 1: 하이라이트 후보 구간 추출" 항목을 UI 클릭으로 펼친 뒤(lazy 렌더라 JS로 details.open만 하면 내용이 안 붙을 수 있음 — 안 되면 화면 좌표 클릭), shadow DOM 관통으로 `"candidates"`를 포함한 **가장 짧은** innerText(Model Response 부분)를 회수한다.

## 1단계 모드

- 노드 3개뿐: YouTube Video → Step 1(하이라이트 후보 5개) → Generate HTML. 전체 **~1분**이면 끝난다(10초 간격 폴링, "Thinking... Step 1: N%"가 사라지고 candidates JSON이 렌더링되면 완료).
- **추출**: shadow DOM 관통으로 `"candidates"`를 포함한 **가장 긴** innerText 하나만 회수(~2KB, 통짜 회수 가능). Console 추출 불필요 — Output 자체가 Step 1 결과다.
- **저장**: rawText와 step1Text에 **같은 텍스트**를 넣는다.

## 주의

- Opal은 무료 실험 서비스 — 일일 사용량 제한이 있으니 큐가 많으면 사용자에게 몇 개까지 돌릴지 확인.
- Opal 앱 구조(노드 구성·프롬프트)가 바뀌어 보이면 조작을 멈추고 사용자에게 보고.
- 쿠키 배너가 뜨면 "나중에"(거절)를 선택.