활성화 계약
사용자가 기능을 설명하거나 버그를 재현하는 음성 해설이 포함된 비디오를 원할 때, 또는 스크린샷만으로는 흐름(타이밍, 시퀀스, 변경되는 상태)을 보여주기에 충분하지 않을 때 로드합니다. 단일 정적 상태의 경우 스크린샷으로 충분하므로 녹화하지 마십시오.
CLI는 C:\Users\DESARROLLADORES\Documents\personal\ai-video-evidence (node bin/narrate.mjs)에 있습니다. Node 22+, PATH에 ffmpeg/ffprobe, Google Chrome, 그리고 pip install edge-tts가 필요합니다.
엄격한 규칙
- 먼저 스크립트(
narration.json)를 작성하고 검증한 후 녹화하십시오. 절대 수동으로 녹화하고 나레이션을 입히지 마십시오. - 하나의 장면 = 하나의 아이디어와 한두 개의 문장입니다. 음성은 해당 장면의 화면에 무엇이 있는지 설명해야 하며, 다음에 올 내용을 절대 설명해서는 안 됩니다.
- 나레이션 언어는 대상 청중(일반적으로 Trip2 PR의 경우 스페인어)에 맞춥니다. 기본 음성은
es-CO-SalomeNeural입니다. 남성 음성은es-CO-GonzaloNeural입니다. - 비밀번호를 절대 입력하지 마십시오. 인증이 필요한 앱의 경우 사용자가
narrate login <url>을 실행하여 로그인합니다.browser.storageState가 저장된 파일을 가리키도록 하십시오. 녹화 후 해당 파일을 삭제하고 git에서 제외하십시오. - 사용자가 확인한 테스트 데이터만 사용하십시오. 새 레코드에는
QA_접두사를 붙입니다. 기존 레코드를 편집하거나 삭제하지 마십시오. - 출력 파일을 git에서 제외하십시오(
out/,pr-assets/). - 비결정적 흐름(LLM, 비동기 작업)의 경우: 녹화된 프레임에서 결과를 확인하십시오. 앱이 나레이션과 다르게 동작했다면 다시 녹화하십시오. 음성이 화면 내용과 모순되는 비디오를 절대 제공하지 마십시오.
결정 게이트
| 상황 | 조치 |
|---|---|
| 버그 리포트 | assets/bug-template.json: 컨텍스트 → 단계 → 실제 결과(빨간색 콜아웃) → 예상 결과(초록색) → 증거 → 영향 |
| 기능 / PR 데모 | assets/feature-template.json: 해결하는 문제 → 둘러보기 → 엣지 케이스 |
| 백엔드 대기 또는 느린 로딩 | "speedup": 4를 사용하여 자체 장면으로 분리합니다. 나레이션 이후 부분만 가속됩니다. |
네이티브 <select> 팝업, OS 대화상자, 또는 앱이 사용자의 실제 Ego 세션(Trip2 로그인 상태)을 필요로 하는 경우 | "recorder": "gdigrab" (Windows 전용). 실행 전: 사용자가 Ego에서 앱에 로그인하고, 모니터 1을 비워두며, 러너가 요청할 때 Ego 작업 공간을 narrate-<name>으로 전환할 준비를 합니다. (Ego는 Agent 창을 숨깁니다. 러너가 Win32로 창을 올리지만 Ego는 선택된 공간만 표시합니다.) 무인 실행 = playwright 사용 |
gdigrab 스크립트가 call/actionsModule 또는 waitForResponse를 사용하는 경우 | 지원하지 않음 (검증 오류): 실제 백엔드나 로컬 서버(examples/bug-demo/server.mjs)를 사용하고 UI 결과에 대해 waitFor를 사용하십시오. |
| gdigrab 실행이 "화면에 표시되지 않음" 오류로 실패하는 경우 | 작업 공간 창이 숨겨져 있거나 가려져 있습니다. 사용자에게 Ego에서 공간을 선택하고 다시 실행하도록 요청하십시오. 사용자 자신의 공간이나 탭을 요구하거나 재사용하지 마십시오. |
| 모의 객체(mocking) 또는 복잡한 단계가 필요한 경우 | async (page, ctx) 함수를 내보내는 actionsModule을 사용하고, { "call": "name" }으로 호출합니다. |
| 버그 증거 단계 | 첫 번째 실행에서 out/<name>/evidence.json (실패한 응답, 콘솔 오류)을 읽고 실제 요청/상태를 evidencia 콜아웃에 넣습니다. |
실행 단계
- 작업 옆에 일치하는 템플릿을 복사하고(Trip2:
pr-assets/<name>.json)title,baseUrl, 장면, 선택자를 채웁니다. node bin/narrate.mjs validate <file>을 실행하고 보고된 모든 경로를 수정합니다.- 앱에 세션이 필요한 경우:
playwright의 경우 사용자에게node bin/narrate.mjs login <url> --save pr-assets/state.json을 실행하도록 요청한 다음browser.storageState를 설정합니다.gdigrab의 경우 사용자는 미리 Ego에서 앱에 로그인합니다(Trip2 경로:baseUrl= 로컬 Trip2 URL,recorder: "gdigrab", 짧은 장면,call없음). node bin/narrate.mjs run <file>(또는tts,record,assemble을 별도로 실행하거나assemble만으로 다시 녹화하지 않고 재렌더링할 수 있습니다).- 결과를 확인합니다:
ffmpeg -ss <t> -frames:v 1로 장면 시작 시점의 프레임을 추출(scenes.json)하여 확인합니다.volumedetect로 오디오를 확인합니다.evidence.json을 읽습니다(gdigrab에서는 비어 있음). gdigrab의 경우 프레임에 페이지 외에 데스크탑, 작업 표시줄 또는 다른 창이 없는지 확인합니다. <name>.mp4(H.264 + AAC + 소프트 자막) 및<name>.srt를 전달합니다. Trip2 PR의 경우trip2-pr-delivery를 따릅니다. 아티팩트는pr-assets/에 있으며, PR에 첨부되고 설명에 나열됩니다.
액션 참조
goto (baseUrl 기준 상대 경로), click, hover, check (선택자), fill/select {selector, value}, press {key, selector?}, scroll {selector? | y?}, wait (밀리초), waitFor (선택자 또는 {selector, state, timeoutMs}), waitForResponse (URL 하위 문자열, 장면에서 이미 본 응답도 허용), overlay {kind: actual|expected|info, title?, text | html, durationMs?}, screenshot (이름), call (actionsModule의 내보내기). 선택자는 Playwright 로케이터입니다(#id, text=Guardar, role=button[name="Guardar"]). recorder: "gdigrab"를 사용하는 경우 선택자는 그대로 Ego로 전달됩니다: 원시 CSS, text=..., loc=role:button[name='Guardar'], @ref. call과 waitForResponse는 거부됩니다. check, scroll {selector} 및 waitFor는 원시 CSS 선택자에 대해 page.evaluate/waitForFunction을 사용합니다.
장면 필드: id (슬러그), say, chapter {title, description?, durationMs?}, actions, speedup. 최상위 레벨: title, baseUrl, recorder (playwright | gdigrab), gdigrab {framerate: 25, drawMouse: true, tab: "new"}, viewport (Playwright 전용), tts {engine: edge|deepgram|sapi, voice, rate, fallback}, browser {channel, headless, locale, storageState}, captions, showActions, gapMs, actionsModule, output.
출력 계약
반환: 비디오 경로 및 재생 시간, SRT 경로, 사용된 TTS 엔진(및 모든 대체 엔진), 시작 시간이 포함된 장면 목록, evidence.json이 캡처한 내용, 그리고 표시할 수 없었던 모든 것(네이티브 팝업, 불안정한 단계).
참조
assets/bug-template.json,assets/feature-template.json— 스크립트 뼈대.- 저장소
README.md— 설치, 명령어, 동기화 작동 방식. examples/bug-demo/— 모의 백엔드(narration.json, Playwright)와 gdigrab 변형(narration-ego.json+server.mjs)이 포함된 완전한 작동 예제.