거북이경보 거북이경보

🐢 거북이경보 (Turtle Alert)

"어휴~ 거북이되겠다~" 잔소리형 자세 교정 알림 앱 (macOS 메뉴바 상주)

📥 다운로드

사용자라면 👉 설치 가이드 에서 한 페이지로 정리된 안내를 확인하세요.

칩 바로 다운로드
🍎 Apple Silicon (M1/M2/M3/M4) TurtleAlert-arm64.dmg
💻 Intel Mac TurtleAlert-x64.dmg

📦 전체 릴리즈 보기

📑 목차

1. 개요

항목 값
앱 이름 거북이경보
프로젝트명 turtle-alert
플랫폼 macOS (Electron)
타입 메뉴바 상주 앱 (창 없음, Dock 숨김)
설치 위치 /Applications/거북이경보.app
실행 스크립트 pnpm dev
저장소 project-hh-org/turtle-alert
이슈/건의 GitHub Issues

2. 주요 기능

2-1. 자세 교정 알림

2-2. 자세 감시 AI (v0.4.0~)

2-3. 메뉴바 UI

2-4. 데이터 영구 저장

2-5. 새 버전 알림 (v0.7.0~)

3. 스트레칭 종류

이모지 이름 설명
🧘 목 좌우 스트레칭 고개를 천천히 좌우로 기울여 10초씩 유지
💪 어깨 으쓱 어깨를 귀까지 올렸다 떨어뜨리기 (5회)
🐢 고개 뒤로 턱을 뒤로 당겨 이중턱 만들고 10초 유지
🙆 가슴 펴기 양손 깍지 끼고 가슴 활짝 펴기
👀 눈 운동 20-20-20 규칙 (6m 밖 20초 바라보기)
🔄 허리 비틀기 의자에 앉은 채 상체 좌우 비틀기
🤚 손목 스트레칭 손가락 당겨 손목 스트레칭
🚶 일어서기 자리에서 일어나 30초 제자리 걸음

4. 파일 구조

turtle-alert/
├── main.js              # Electron 메인 프로세스 (트레이, 타이머, 알림)
├── lib.js               # 앱 코어 로직 (타이머, 알림, 자세 감시 통합)
├── lib/
│   ├── posture-detector.js  # 자세 판정 순수 로직 (캘리브레이션, 8가지 감지)
│   └── posture-capture.js   # 카메라/TensorFlow.js 의존 함수
├── __tests__/           # Vitest 테스트 (커버리지 80%+)
├── package.json         # 프로젝트 설정 + electron-builder 설정
├── assets/
│   ├── icon.svg         # 원본 아이콘 (SVG)
│   └── icon.png         # 앱 아이콘 (512x512 PNG, 자동 icns 변환)
└── dist/                # 빌드 결과물 (.app, .dmg, .zip)

5. 기술 스택

영역 기술
런타임 Electron 41
저장소 electron-store
AI TensorFlow.js + MoveNet (로컬 추론)
카메라 imagesnap (macOS CLI)
빌드 electron-builder
테스트 Vitest + v8 coverage (80%+)
패키지 매니저 pnpm

6. 개발 히스토리

v0.7.0 / v0.7.1 — 새 버전 알림 (업데이트 체커)

  1. 앱 시작 시 GitHub Releases 확인 — 새 버전이 올라와있으면 트레이 메뉴 최상단에 "🆕 새 버전 vX.Y.Z 받기" 항목이 추가되고 알림을 한 번 띄움
  2. 실패는 조용히 — 네트워크 오류 / rate limit 은 사용자에게 영향 없음
  3. 자동 설치 아님 — Apple Developer 서명이 없어 풀 자동 업데이트는 제약이 크므로, 클릭 한 번으로 릴리즈 페이지를 여는 반자동 방식만 도입
  4. v0.7.1: 주기 폴링(6시간마다)을 제거하고 앱 시작 시 1회 확인으로 단순화 — 메뉴바 앱 특성상 주기 폴링의 이득이 복잡도 대비 크지 않다고 판단

v0.6.1 — AI 백엔드 초기화 추가 (v0.6.0 후속 픽스)

  1. AI 자세 검사 백엔드 누락 해결 — v0.6.0 에서 @mediapipe/pose 는 추가했지만 실제로는 @tensorflow/tfjs-backend-cpu 도 빠져있어 createDetector 단계에서 "No backend found in registry" 로 실패하던 문제. 백엔드 패키지 추가 + tf.setBackend('cpu') / tf.ready() 명시 호출

v0.6.0 — AI 모델 로드 버그 수정 + Finder 한글 표시

  1. AI 자세 검사 로드 실패 수정 — @mediapipe/pose 가 프로덕션 빌드에서 누락되어 트레이에서 AI 자세 검사를 켤 때 "TensorFlow.js 모델을 불러올 수 없습니다" 에러가 나던 문제 해결. 자세한 원인과 디버깅 과정은 site/2026-04-24-ai-posture-mediapipe.md 참고
  2. Finder 앱 이름 한글 표시 — macOS SIGTRAP 회피를 위해 번들명을 영문(TurtleAlert) 으로 두되, CFBundleDisplayName + .lproj 로컬라이제이션으로 Finder/Dock/메뉴바 표시를 거북이경보 한글로 복원

v0.5.x — 릴리즈 파이프라인 + imagesnap 번들

  1. imagesnap 바이너리 번들 — 사용자가 brew install imagesnap 을 따로 하지 않아도 스냅샷/AI 기능 동작 (v0.5.1)
  2. 한 줄 릴리즈 자동화 — pnpm release:tag 스크립트로 버전 bump → 태그 push → CI 자동 빌드·배포 (v0.5.0)
  3. 고정 자산명 — 릴리즈 자산을 TurtleAlert-arm64.dmg / TurtleAlert-x64.dmg 로 고정하여 releases/latest/download/ 영구 링크 보장
  4. 취약점 대응 — @xmldom/xmldom 을 ≥0.8.13 으로 pnpm override
  5. UX 개선 — 감시 모드 분리(알림만 / AI 자세 검사), AI 감시 간격 선택(20초~5분), 스트레칭 27종 확대, 캘리브레이션 제거 후 절대 기준 전환

v0.4.0 — 자세 감시 AI + 캘리브레이션

  1. TensorFlow.js MoveNet 기반 실시간 자세 분석 기능 추가
  2. 기준 자세 캘리브레이션 — 절대 임계값 → 본인 기준 편차 방식으로 전환
  3. 8가지 자세 감지 — 거북목, 어깨 기울어짐, 고개 전방 돌출, 고개 회전, 화면에 너무 가까움, 고개 기울어짐, 한쪽으로 기울어짐, 구부정한 자세
  4. 상단바 깜빡임 효과 — 알림 발생 시 🚨 5초 깜빡임
  5. 모듈 분리 — 순수 판정 로직(posture-detector.js)과 카메라 의존 함수(posture-capture.js) 분리
  6. 테스트 커버리지 80%+ 달성 (Vitest + v8)

v0.3.1 — macOS 크래시 수정

  1. macOS 26.2 한글 productName SIGTRAP 회피 (productName 영문 고정)
  2. Electron 41 트레이 아이콘 크래시 회피 및 afterPack 훅 추가

v0.2.0 — 자세 스냅샷 기능

  1. imagesnap 기반 자세 스냅샷 촬영 기능 추가
  2. 스냅샷 자동 정리 — 보관 기간 경과 시 자동 삭제
  3. 연속 촬영 실패 시 자동 비활성화 (3회 연속 실패)

v0.1.0 — 초기 버전

  1. Next.js 웹 앱으로 시작 → 브라우저 필요
  2. Electron 전환 → 창 기반 네이티브 앱
  3. 메뉴바 전용 앱으로 간소화 → 창 제거, 트레이만 남김
  4. 이름 변경: Alert or Turtle → 거북이경보
  5. 아이콘 추가: 귀여운 거북이 + 빨간 경보 표시
  6. 프로젝트명 변경: alert-or-turtle → turtle-alert

7. 빌드 & 배포

개발 실행

pnpm install
pnpm dev

macOS 앱 빌드

칩셋별 개별 빌드 (용량 ↓)

npx electron-builder --mac --x64 --arm64 --publish never

유니버설 빌드 (한 파일로 통합, 용량 ↑)

npx electron-builder --mac --universal --publish never

빌드 결과:

응용 프로그램에 설치

cp -R "dist/mac-arm64/TurtleAlert.app" /Applications/

Spotlight(Cmd+Space)에서 "거북이경보" 검색 후 실행.

GitHub Release (권장: 한 줄)

pnpm release:tag patch    # 0.5.0 -> 0.5.1 (또는 minor / major / 0.6.0)

스크립트가 version bump → 커밋 → 태그 → push까지 처리하면, CI(release.yml)가 자동으로 빌드 + GitHub Release 생성 + 자산 업로드를 진행합니다.

자산명은 TurtleAlert-arm64.dmg, TurtleAlert-x64.dmg (버전 없음)로 고정되어 설치 가이드의 releases/latest/download/ 링크가 다음 릴리즈에서도 그대로 작동합니다.

로컬 빌드/업로드 (디버깅용):

gh release create vX.Y.Z --title "거북이경보 vX.Y.Z" --notes "..."
pnpm release    # 빌드 + rename + 업로드

📝 참고