콘텐츠로 이동

자동 캡처 IPC

문서 · 홍보용 스크린샷을 손으로 찍지 않으려고 만든 개발자용 기능입니다. 로컬 REST 요청 하나로 화면을 바꾸고 창을 PNG 로 저장합니다. 화면 갤러리 의 그림 10장이 이 방법으로 찍혔습니다.

  1. 로컬 앱 서버에 POST /api/screens/... 요청
  2. 서버(server/routes/screens.js)가 Electron 창에 screens:goto IPC 메시지를 보냄
  3. preload(electron/preload.cjs)의 window.electron.screens.onGoto 가 renderer 로 전달
  4. renderer(client/src/App.jsx)가 해당 화면으로 바꾸는 store 동작을 실행
  5. batch 요청이면 서버가 기다렸다가 webContents.capturePage() 로 PNG 저장

Electron 안에서 돌 때만 동작합니다. 개발용 단독 서버에서는 503 을 돌려줍니다.

  • 이 PC 에서 보낸 요청만 받습니다. 터널 경유 헤더(cf-connecting-ip · x-forwarded-for · x-real-ip)나 토큰(x-cm-token · ?token=)이 붙으면 403 입니다.
  • Origin 헤더가 꼭 있어야 하고 localhost · 127.0.0.1 · [::1] 이어야 합니다. curl 에서는 -H "Origin: http://localhost" 를 붙입니다.
  • batch-capture 의 dir 은 절대 경로여야 합니다. /api/capture 의 dir 은 상대 경로면 앱 서버 기준으로 풀립니다. 둘 다 .. 를 쓸 수 없습니다. Windows · System32 · Program Files · ProgramData 같은 시스템 경로는 거부합니다.
이름 바뀌는 화면
overview Overview
dashboard Dashboard
settings Settings
tools Tools 패널
diagnostics Diagnostics 패널
close-all-modals 열린 창 모두 닫기
select-first-project 첫 번째 프로젝트 화면
tools-in-project 첫 번째 프로젝트 + Tools 패널
chat-with-preview 첫 번째 프로젝트 + README.md 미리보기
terminal-open 첫 번째 프로젝트 + 터미널 칸 추가
split-mode 첫 번째 프로젝트로 Split 모드
debug-open 첫 번째 프로젝트 + 디버그 패널

목록에 없는 이름은 400 (batch 에서는 그 항목만 실패)입니다. 서버의 SUPPORTED_SCREENS 와 renderer 의 switch 문을 함께 고쳐야 새 화면이 늘어납니다.

화면만 바꾸고 바로 응답합니다. 언제 찍을지는 호출하는 쪽이 정합니다.

body 필드 형식 설명
screen string 필수. 화면 이름
privacyMode boolean 개인정보 가리기 켜기 · 끄기
Terminal window
curl -X POST http://127.0.0.1:3001/api/screens/goto \
-H "Origin: http://localhost" -H "Content-Type: application/json" \
-d '{"screen":"dashboard"}'

화면 목록을 차례로 돌며 찍습니다.

body 필드 형식 설명
screens string[] 필수. 찍을 화면 이름 순서
dir string 필수. 저장할 절대 경로. 없으면 만듦
settleMs number 화면을 바꾼 뒤 찍기 전 대기. 기본 500
prefix string 파일 이름 앞부분. 영문 · 숫자 · _.- 32자까지, 어기면 무시
privacyMode boolean true 면 찍는 동안 개인정보를 가리고 끝나면 끔

파일 이름은 <prefix><순번 두 자리>-<화면 이름>.png 입니다. 캡처하다 실패한 항목도 순번을 쓰고, 목록에 없는 화면 이름은 건너뜁니다.

Terminal window
curl -X POST http://127.0.0.1:3001/api/screens/batch-capture \
-H "Origin: http://localhost" -H "Content-Type: application/json" \
-d '{"screens":["overview","dashboard","settings"],"dir":"D:/shots","privacyMode":true}'

응답:

{ "ok": true, "dir": "D:/shots", "results": [
{ "screen": "overview", "ok": true, "path": "D:/shots/00-overview.png", "bytes": 123456 }
] }

화면을 바꾸지 않고 지금 창을 한 장 찍습니다. 인자는 body 가 아니라 주소 뒤 query 로 넘깁니다.

query 설명
name 파일 이름 (확장자 제외). 영문 · 숫자 · _- 외 글자는 _ 로 바뀜, 64자까지. 기본 capture-<시각>
dir 저장할 경로(상대 경로는 앱 서버 기준). 생략하면 앱 소스 기준 docs/ui-design/refs

privacyMode 를 켜면 body 에 privacy-mode 클래스가 붙습니다. data-privacy="mask" 가 붙은 요소는 6px, mask-strong 은 12px 로 흐려집니다. 프로젝트 이름 · 경로 · 채팅 말풍선 · 대시보드 이름표에 붙어 있습니다. 새 화면에 개인정보가 보이면 그 요소에 data-privacy 를 붙입니다.

REST 와 별개인 Windows 용 PowerShell 스크립트입니다. 제목이 AgentManager 로 시작하는 창(DevTools 제외)을 찾아 PrintWindow 로 찍습니다. 다른 창에 가려져 있어도 찍힙니다.

Terminal window
powershell -File scripts/snap.ps1 -Out shots\now.png

-Out 을 생략하면 codex-images\debug-actual.png 에 저장합니다. 창을 못 찾으면 NO_WINDOW 를 찍고 종료 코드 1 로 끝납니다.