자동 캡처 IPC
문서 · 홍보용 스크린샷을 손으로 찍지 않으려고 만든 개발자용 기능입니다. 로컬 REST 요청 하나로 화면을 바꾸고 창을 PNG 로 저장합니다. 화면 갤러리 의 그림 10장이 이 방법으로 찍혔습니다.
- 로컬 앱 서버에
POST /api/screens/...요청 - 서버(
server/routes/screens.js)가 Electron 창에screens:gotoIPC 메시지를 보냄 - preload(
electron/preload.cjs)의window.electron.screens.onGoto가 renderer 로 전달 - renderer(
client/src/App.jsx)가 해당 화면으로 바꾸는 store 동작을 실행 - 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 문을 함께 고쳐야 새 화면이 늘어납니다.
POST /api/screens/goto
섹션 제목: “POST /api/screens/goto”화면만 바꾸고 바로 응답합니다. 언제 찍을지는 호출하는 쪽이 정합니다.
| body 필드 | 형식 | 설명 |
|---|---|---|
screen |
string | 필수. 화면 이름 |
privacyMode |
boolean | 개인정보 가리기 켜기 · 끄기 |
curl -X POST http://127.0.0.1:3001/api/screens/goto \ -H "Origin: http://localhost" -H "Content-Type: application/json" \ -d '{"screen":"dashboard"}'POST /api/screens/batch-capture
섹션 제목: “POST /api/screens/batch-capture”화면 목록을 차례로 돌며 찍습니다.
| body 필드 | 형식 | 설명 |
|---|---|---|
screens |
string[] | 필수. 찍을 화면 이름 순서 |
dir |
string | 필수. 저장할 절대 경로. 없으면 만듦 |
settleMs |
number | 화면을 바꾼 뒤 찍기 전 대기. 기본 500 |
prefix |
string | 파일 이름 앞부분. 영문 · 숫자 · _.- 32자까지, 어기면 무시 |
privacyMode |
boolean | true 면 찍는 동안 개인정보를 가리고 끝나면 끔 |
파일 이름은 <prefix><순번 두 자리>-<화면 이름>.png 입니다. 캡처하다 실패한 항목도 순번을 쓰고, 목록에 없는 화면 이름은 건너뜁니다.
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 }] }POST /api/capture
섹션 제목: “POST /api/capture”화면을 바꾸지 않고 지금 창을 한 장 찍습니다. 인자는 body 가 아니라 주소 뒤 query 로 넘깁니다.
| query | 설명 |
|---|---|
name |
파일 이름 (확장자 제외). 영문 · 숫자 · _- 외 글자는 _ 로 바뀜, 64자까지. 기본 capture-<시각> |
dir |
저장할 경로(상대 경로는 앱 서버 기준). 생략하면 앱 소스 기준 docs/ui-design/refs |
개인정보 가리기
섹션 제목: “개인정보 가리기”privacyMode 를 켜면 body 에 privacy-mode 클래스가 붙습니다. data-privacy="mask" 가 붙은 요소는 6px, mask-strong 은 12px 로 흐려집니다. 프로젝트 이름 · 경로 · 채팅 말풍선 · 대시보드 이름표에 붙어 있습니다. 새 화면에 개인정보가 보이면 그 요소에 data-privacy 를 붙입니다.
창 밖에서 찍기: scripts/snap.ps1
섹션 제목: “창 밖에서 찍기: scripts/snap.ps1”REST 와 별개인 Windows 용 PowerShell 스크립트입니다. 제목이 AgentManager 로 시작하는 창(DevTools 제외)을 찾아 PrintWindow 로 찍습니다. 다른 창에 가려져 있어도 찍힙니다.
powershell -File scripts/snap.ps1 -Out shots\now.png-Out 을 생략하면 codex-images\debug-actual.png 에 저장합니다. 창을 못 찾으면 NO_WINDOW 를 찍고 종료 코드 1 로 끝납니다.