프로젝트 소개
jev-chat-jarvis는 macOS용 WeChat 메시지 보조 도구입니다. WeChat에 상대방이 보낸 것으로 확인할 수 있는 텍스트 메시지가 나타나면 화면 콘텐츠와 로컬 모델을 분석하여 해당 문장의 실제 의도, 0~9 위험 등급, 행동 제안 및 후보 답변을 표시합니다.
이 도구는 읽기 전용으로 작동하며 WeChat에 코드를 주입하거나 hook을 사용하지 않고, 데이터베이스를 해독하지 않으며, 메시지를 자동으로 보내지도 않습니다. 사용자는 플로팅 패널에서 후보 내용을 복사하거나 “입력”을 클릭해 텍스트를 WeChat 입력 상자에 넣을 수 있으며, 최종 전송은 사용자가 직접 수행합니다.
핵심 기능
- 의도 및 위험 분석: 8가지 의도 유형의 제로샷 인식을 지원하고 위험 등급과 행동 제안을 제공합니다. 프로젝트 README의 22개 중국어 회귀 샘플 기준 의도 인식률은 86.4%입니다.
- 후보 답변 생성: 10가지 화법을 내장하고 있으며, 각 화법마다 신중한 답변과 편안한 답변 두 종류의 후보를 생성한 뒤 로컬 모델이 순위를 정합니다.
- 병렬 처리: 메시지 판단과 후보 생성을 동시에 시작할 수 있습니다. README에 제시된 M1 Pro 기준 소요 시간은 의도 분석 약 1.5초, 후보 생성 약 1.5~2초이며 실제 속도는 기기와 서비스에 따라 달라집니다.
- YOLO 감지 상자: 선택적으로 WeChat 창에서 OCR로 인식된 메시지를 표시하고, 상대방 메시지와 내 메시지를 구분하며 신뢰도를 보여 줍니다.
- 네이티브 플로팅 패널: 패널에 현재 채팅, 분석 상태, 처리 대기 중인 메시지, 컨텍스트, 의도, 인식률, 위험 등급, 행동 제안 및 후보 답변이 표시됩니다.
설치 및 최초 실행
방법 1: macOS 앱 다운로드
바로 사용하려면 Releases에서 macOS 압축 파일 다운로드 후 압축을 풀고 .app을 “응용 프로그램”으로 드래그하면 됩니다. 앱이 공증되지 않았으므로 처음 실행할 때는 Finder에서 앱을 마우스 오른쪽 버튼으로 클릭하고 “열기”를 선택해야 하며, 바로 더블 클릭하지 마세요.
macOS에 “손상되어 열 수 없습니다. 휴지통으로 이동해야 합니다”라는 메시지가 표시되는 경우, 일반적으로 브라우저에서 다운로드한 압축 파일에 격리 속성이 포함되어 있기 때문입니다. 앱을 바로 삭제하지 말고 터미널에서 다음을 실행하세요.
sudo xattr -r -d com.apple.quarantine /Applications/jev-jarvis.app앱 이름이 jev-jarvis 2.app처럼 변경된 경우 명령의 경로를 실제 경로로 바꾸세요.
방법 2: 소스 코드에서 실행
소스 코드에서 실행하기 전에 WeChat이 이미 실행 중이고 터미널 또는 실행 앱에 화면 기록 권한이 있는지 확인하세요. 프로젝트 디렉터리로 이동한 후 다음을 실행합니다.
./start.command프로젝트는 uv로 Python 환경을 관리합니다. 시스템에 사용 가능한 uv가 없으면 두 실행 진입점 모두 공식 설치 스크립트를 다운로드하여 실행하려고 시도하며, 실패하면 기존 Homebrew도 사용하려고 합니다. 설치 및 실행 로그 위치는 다음과 같습니다.
~/Library/Logs/jev-jarvis.logmacOS 권한 부여
처음 실행할 때 안내에 따라 “시스템 설정 > 개인정보 보호 및 보안”에서 jev-chat-jarvis에 “화면 기록” 권한을 부여한 다음, 권한을 적용하려면 앱을 종료하고 다시 여세요.
“입력” 기능에는 “손쉬운 사용” 권한도 필요합니다. 처음 “입력”을 클릭하면 일반적으로 시스템에서 권한 부여 안내가 표시됩니다. v0.3.1 이하 버전에서는 python3.12에도 해당 권한을 부여해야 합니다.
이 권한은 WeChat 창의 내용을 읽고, 입력 컨트롤을 찾고, 입력 작업을 수행하는 데 사용되며 도구가 메시지를 자동으로 보낸다는 의미는 아닙니다.
모델 및 키 구성
프로젝트에는 판단 계층과 생성 계층이 있으며 두 계층의 키는 모두 입력하지 않아도 됩니다.
- 판단 계층: TypeSafe Jev 키를 구성하지 않으면 로컬
decider-2b모델을 사용합니다. 최초 다운로드에는 약 7 GB가 필요합니다. - 생성 계층: 패키지 앱에 공유 키가 내장되어 있으므로 개인 키를 구성하지 않아도 후보 답변 생성을 시도할 수 있습니다.
그래픽 설정 사용
플로팅 창 오른쪽 위의 톱니바퀴 아이콘을 클릭하거나 메뉴 막대의 “J > 모델 설정…”을 통해 구성 창을 여세요. 설정 화면에서는 Jev, OpenAI 호환 및 Anthropic 호환 세 서비스의 주소, 키 및 모델을 편집할 수 있습니다.
“모델 목록 가져오기”를 클릭하여 서비스의 /models API에서 모델을 읽을 수 있으며, API가 지원되지 않거나 요청이 실패하면 직접 입력할 수도 있습니다. 모델을 선택한 후 “연결 테스트”를 클릭할 수 있습니다. 테스트는 아직 저장되지 않은 구성으로 고정된 인사말을 전송하며 WeChat 내용을 읽지는 않지만 소량의 서비스 비용이 발생할 수 있습니다.
구성을 저장한 후에는 반드시 앱을 종료하고 다시 열어야 하며, 현재 실행 중에는 구성이 즉시 전환되지 않습니다. 설정 창에서 편집하는 기본 파일은 다음과 같습니다.
$XDG_CONFIG_HOME/jev-jarvis/envXDG_CONFIG_HOME이 설정되지 않은 경우 실제 경로는 다음과 같습니다.
~/.config/jev-jarvis/env환경 파일 수동 생성
터미널에서 구성 파일을 생성할 수도 있습니다.
mkdir -p ~/.config/jev-jarvis
cat > ~/.config/jev-jarvis/env <<'ENV'
# 판단 계층(선택 사항): 비워 두면 로컬 decider-2b 사용
export TYPESAFE_API_KEY=""
# 생성 계층: 모든 OpenAI 호환 엔드포인트
export OPENAI_API_KEY="sk-내-key"
export OPENAI_BASE_URL="https://api.deepseek.com"
export OPENAI_MODEL="deepseek-chat"
# 일부 모델은 사고 모드를 꺼야 합니다
# export OPENAI_EXTRA_BODY='{"enable_thinking":false}'
ENV
chmod 600 ~/.config/jev-jarvis/env구성 우선순위는 환경 변수가 사용자 env 파일보다 높고, 사용자 env 파일이 프로젝트 .env보다 높습니다. 생성 계층에서는 OpenAI 구성이 Anthropic 구성보다 우선하며, 두 구성 모두 없을 때만 내장 공유 키를 사용합니다.
서비스 선택 시 주의 사항
- DeepSeek은
deepseek-chat을 사용할 수 있으며, README에서는 비교적 빠른 실측 선택으로 소개합니다. - 智谱은
glm-4-flash를 사용할 수 있으며 프로젝트에서 지원하는 구성 그룹에 맞춰 해당 변수를 입력하세요. - 로컬 Ollama에는
http://localhost:11434/v1을 입력하고, 키는ollama, 모델은 예를 들어qwen2.5:7b를 사용할 수 있습니다. - 가능하면 thinking 모델은 사용하지 마세요. README에서는 사고 과정이
max_tokens를 소진하여 후보 답변이 비어 있을 수 있다고 안내합니다. DeepSeek 사용 시에는deepseek-chat을 선택해야 합니다.
처음 사용하기
앱을 실행하고 WeChat을 연 후 WeChat 채팅 창을 사용할 수 있는 상태로 유지하세요. 도구는 창 콘텐츠와 Vision OCR을 통해 채팅 영역을 읽으며 시스템 화면을 직접 캡처하지 않으므로 플로팅 패널이 OCR을 방해하지 않습니다.
상대방이 보낸 것으로 명확히 인식되는 텍스트 메시지가 나타나면 패널에 현재 채팅과 분석 상태, 처리 중인 메시지 및 컨텍스트, 의도, 인식률, 위험 등급, 행동 제안, 화법별로 그룹화된 후보 답변이 차례로 표시됩니다.
각 후보의 왼쪽에는 로컬 순위 확률이 표시되고 오른쪽에는 “복사”와 “입력”이 제공됩니다. “복사”는 직접 붙여 넣을 때 사용하며, “입력”은 텍스트를 WeChat 입력 상자에 넣지만 전송 버튼을 자동으로 클릭하지는 않습니다.
사용 예시
예를 들어 상대방이 “이 요구 사항 오늘 좀 진행해 줘”라고 보내면 도구가 메시지를 판단 계층에 전달해 인식하고 위험 결과에 따라 행동 제안을 제공합니다. 이어 생성 계층이 여러 말투의 후보 답변을 병렬로 생성하고 로컬에서 순위를 정한 뒤 다시 배열합니다. 컨텍스트에 따라 하나를 선택하고 “복사” 또는 “입력”을 클릭한 다음 직접 확인하여 전송할 수 있습니다.
메시지 방향을 확인할 수 없는 경우, 예를 들어 텍스트가 좌우에 걸쳐 있거나 가운데에 위치한 경우 패널은 “방향 미확인”으로 표시하며 답변 대상으로 사용하지 않습니다. 상대방 메시지로 명확히 인식된 경우에만 판단과 생성이 실행됩니다.
고급 사용 팁
YOLO 감지 상자 켜기
환경 변수를 통해 시작할 때 감지 상자를 켤 수 있습니다.
JEV_BOXES=1실행 후에도 메뉴 막대에서 “YOLO 감지 상자”를 전환할 수 있습니다. 감지 상자는 약 1초마다 새로 고쳐집니다. 파란색 실선은 손쉬운 사용 인터페이스가 찾은 입력 컨트롤을 나타내고, 주황색 점선은 스크린샷 경계에 따라 추정한 입력 영역을 나타냅니다. 점선은 쓰기 가능한 컨트롤을 반드시 찾았다는 의미가 아닙니다.
화법 사용자 지정
JEV_TONES를 통해 화법을 추가하거나 덮어쓸 수 있습니다. 각 화법은 |로 구분하며 형식은 “이름=설명”입니다. 예시는 다음과 같습니다.
export JEV_TONES='프로 미루기=숙련된 미루기 전문가처럼 일을 깔끔하고 예의 있게 넘기는 방식'설명에는 필요한 말투와 어떤 스타일이 되면 안 되는지를 명확히 작성해야 합니다. 변경 후에는 앱을 다시 시작해야 합니다. 현재 설정 창에서는 JEV_TONES, JEV_BOXES 및 OPENAI_EXTRA_BODY를 수정하지 않습니다.
계층별 자체 테스트 및 문제 해결
소스 코드에서 실행할 때 감지, 판단, 생성 및 회귀 흐름을 각각 테스트할 수 있습니다.
uv run python src/perception.py
uv run python src/judge.py "이 요구 사항 오늘 좀 진행해 줘"
uv run python src/judge_zh_test.py
uv run python src/generate.py --check
uv run python -B -m unittest discover -s tests
uv run python probe/bootstrap_regression.py생성 계층의 --check는 자격 증명 파싱만 확인하며 실제 연결 테스트와는 다릅니다. 서비스가 텍스트를 생성할 수 있는지 확인하려면 설정 창의 “연결 테스트”를 사용하세요.
로그 확인 및 디스크 공간 확보
실행 후 첫 번째 메시지 처리가 느리다면 일반적으로 로컬 모델을 예열하는 과정 때문입니다. 최근 로그는 다음과 같이 확인할 수 있습니다.
tail -40 ~/Library/Logs/jev-jarvis.log로그에는 단계별 소요 시간이 포함되지만 메시지 본문은 포함되지 않으므로 문제를 보고할 때 개발자에게 제공하기에 적합합니다.
로컬 판단 모델 캐시는 약 7 GB를 차지하며 위치는 다음과 같습니다.
~/.cache/huggingface/hub/models--Mapika--decider-2b삭제하면 다음에 로컬 판단을 사용할 때 다시 다운로드됩니다. Python 가상 환경 위치는 다음과 같습니다.
~/Library/Application Support/jev-jarvis/venv앱을 삭제해도 이 환경은 자동으로 삭제되지 않으므로 필요할 때 수동으로 정리할 수 있습니다.
“입력” 기능의 제한
도구는 먼저 macOS 손쉬운 사용 인터페이스를 통해 입력하고 다시 읽어 확인합니다. 일부 WeChat 버전에서 입력 컨트롤을 제공하지 않으면 시각적 호환 경로를 시도합니다. 이 경로에서는 창, 입력 영역 및 제목을 다시 확인하고 WeChat을 활성화한 뒤 입력 영역을 클릭하여 텍스트를 입력하고 OCR로 확인합니다.
시각적 호환 경로를 사용할 때 도구가 마우스를 움직일 수 있으므로 입력하는 동안 키보드, 마우스를 조작하거나 채팅을 전환하지 마세요. 클립보드나 Cmd+V를 사용하지 않으며 전송 키를 자동으로 누르지도 않습니다. 줄 바꿈과 탭 문자는 공백으로 변환됩니다.
이미 초안이 감지되면 호환 경로가 중지되고 수동으로 “복사”를 사용하라는 안내가 표시됩니다. 창, 포커스 또는 세션이 변경되어도 중지됩니다. 시각적 경계와 OCR에서 잘못 판단할 수 있으므로 사용하기 전에 현재 채팅과 입력 상자의 내용을 확인해야 합니다.
알려진 제한
- 이미지와 이모티콘의 내용은 읽을 수 없습니다. 인용 답변은 일반 텍스트로 처리되며 공식 계정 카드는 메시지 분석 대상으로 인식될 수 있습니다.
- WeChat 전체 화면 레이아웃 또는 WeChat 버전 변경으로 인식이 작동하지 않을 수 있습니다. 관련 레이아웃 상수는
src/perception.py상단에 있습니다. - 여러 창이 있는 경우 기본 창 “微信” 또는 “WeChat”을 우선 인식합니다.
- 방향이 명확히 확인된 상대방 메시지만 답변 흐름을 실행하며 방향을 확인할 수 없는 메시지는 건너뜁니다.
- 어두운 테마, 여러 모니터 및 다양한 WeChat 버전에서 시각적 호환 입력 경로는 추가 검증이 필요합니다.
개인정보 및 사용 안내
프로젝트의 목적은 본인 기기와 본인 계정에 표시되는 화면 내용을 읽는 것입니다. 주입, 후킹, WeChat 데이터베이스 복호화 또는 메시지 자동 전송은 수행하지 않습니다. 본인 기기에서만 사용하고 WeChat 소프트웨어 라이선스 계약을 준수해 주세요. WeChat 업데이트로 레이아웃 인식이 작동하지 않을 수 있습니다. 문제가 발생하면 먼저 로그를 확인한 후 프로젝트 issue를 통해 제보할 수 있습니다.
요약
jev-chat-jarvis는 화면 OCR, 로컬 의도 판단, 위험도 분류, 답변 후보 생성 및 네이티브 플로팅 패널을 결합한 도구로, WeChat 메시지를 빠르게 이해하고 답변 부담을 줄이고 싶은 macOS 사용자에게 적합합니다. 설치 시 Gatekeeper, 화면 기록 및 손쉬운 사용 권한을 중점적으로 처리해야 합니다. 사용 시에는 개인정보 보호, 속도 및 비용을 고려해 로컬 모델, OpenAI 호환 서비스 또는 Anthropic 호환 서비스를 선택하고, 항상 전송 전에 내용을 직접 확인하세요.