Web HUD 사용가이드
Web HUD 는 브라우저에서 JARVIS 와 대화하는 화면이다. 텍스트 대화만이 아니라 에이전트의 생각, 일정, 먼저 건네는 말, 음성까지 한 화면에서 보고 다룰 수 있도록 설계했다. jarvis --web 으로 서버를 띄우고 브라우저에서 http://localhost:7777 을 연다. Docker 로 띄울 때는 docker compose --profile web up -d 를 쓴다. 이 페이지는 화면 구성을 먼저 보이고, 이어서 대화, 승인, 모드, 세션처럼 사용자가 하려는 일 단위로 조작 방법을 정리한다.
화면 명세의 정본은 레포의 docs/view_spec.md 다.
화면 구성
헤더 오른쪽 탭으로 HUD, FLOW, SET 세 화면을 오간다. 기본인 HUD 화면은 가운데 리액터를 두고 왼쪽 열에 AGENDA, ACTIVITY, 오른쪽 열에 SESSIONS, CONVERSATION 카드를 둘렀으며, 아래에 입력 독이 있다.
┌──────────────────────────────────────────────────────────────┐
│ ≡ ● J.A.R.V.I.S. HUD FLOW SET │ 헤더
│ 2026.11.03 TUE 13:14:57 │
├───────────────┬──────────────────────────┬───────────────────┤
│ AGENDA │ │ SESSIONS │
│ UPCOMING │ ‹ 리액터(구체) › │ default NOW ⑂ │
│ OPEN LOOPS │ │ │
├───────────────┤ ● ACTIVE ├───────────────────┤
│ ACTIVITY │ "명언" / 마지막 줄 │ CONVERSATION │
│ │ │ USER / J.A.R.V.I.S│
│ │ │ 💭 SYS │
│ │ │ │
│ │ │ │
├───────────────┴──────────────────────────┴───────────────────┤
│ >_ [입력창 ] [SEND ⏎] │ 입력 독
└──────────────────────────────────────────────────────────────┘
| 영역 | 내용 |
|---|---|
| 헤더 | 왼쪽은 드로어 버튼 ≡(좁은 화면에서만), 가운데는 연결 점과 에이전트 이름, 그 아래 날짜와 시각(2026.11.03 TUE 13:14:57), 오른쪽은 화면 탭 HUD, FLOW, SET. 가운데 묶음은 창 가운데가 아니라 리액터 구체의 가로 중심에 맞춘다. 연결 점은 세션이 붙어 있으면 에이전트 색으로 깜빡이고, 소켓이 끊기면 빨갛게 멈춘다 |
| AGENDA | 예정 작업(스위치로 켜고 끄기)과 open loop(✓ done, ✕ dismiss). 접속, 사고, 턴 끝, 조작 직후, 1분마다 갱신 |
| ACTIVITY | 도구 시작과 끝, 승인, 💭, 🔔, 세션 전환, 오류, 서브 에이전트(↳ name) 로그. 최소 높이를 지킨다 |
| 리액터 | 상태가 구체와 링에 보인다. 대기는 천천히 돌고, 생각은 빨라지고, 실행은 눈금이 켜진다. 링 아래 상태 줄(ACTIVE, THINKING, LISTENING, SPEAKING 등)과 캡션(명언 또는 마지막 한 줄)이 붙는다. 클릭하면 듣기 시작해 말로 이어 가는 대화가 열리고, 읽는 중에 클릭하면 읽기를 멈춘다. 에이전트가 둘 이상이면 구체 양옆에 반투명 화살표 ‹ › 가 뜬다 |
| SESSIONS | + 새 세션, 이름 클릭으로 전환, 활성 세션의 ⑂ 분기, 비활성 세션에 마우스를 올리면 ✕ 삭제 |
| CONVERSATION | USER, 응답(마크다운, 링크는 글자만 보이고 긴 URL 은 도메인만), 💭(접힘, 클릭하면 해석 전문), 도구 흔적. 먼저 건네는 말, 대기 안내, 스케줄 알림은 에이전트 답과 같은 말풍선이고 실패 알림만 SYS 줄, THINKING 자리표시, 복원된 히스토리 |
열 안은 세로 flex 다. SESSIONS 나 CONVERSATION 헤더를 클릭하면 그 카드가 접히고 아래 카드가 자리를 채운다. 접힘 상태는 localStorage 에 남는다. 화면 폭이 860px 이하면 왼쪽 열이 드로어가 되고, 헤더의 ≡ 로 연다.
SET 화면은 왼쪽 열에 SYSTEM 과 DESKTOP(데스크톱 앱에서만), 오른쪽 열에 SETTINGS 폼을 두고, 그 아래 전체 폭에 EFFECTIVE CONFIG 를 둔다. 좁은 화면에서는 한 열로 쌓인다. SYSTEM 카드는 가동 시간, 모델, 세션, 토큰(In, Out, Cache), 비용, 최근 16턴 사용량 그래프, TOOLS 목록(🔒 는 승인 필요)을 보여준다.
화면 탭을 바꾸면 지금 화면의 카드가 살짝 뒤로 물러났다가 화면 밖으로 밀려 나간다. HUD 에서는 왼쪽 열 카드가 왼쪽으로, 오른쪽 열 카드가 오른쪽으로 나가고 리액터는 작아지며 사라진다. 이어서 다음 화면의 카드가 반대편에서 차례로 들어와 살짝 지나쳤다가 제자리에 맞춰진다. 탭 아래 밑줄 하나가 고른 탭으로 미끄러진다. 움직이는 동안 누른 탭은 모아 두었다가 마지막 것 하나만 반영한다. 페이지를 새로 열면 마지막으로 보던 화면을 움직임 없이 되살리고, 시스템 설정이 동작 줄이기(prefers-reduced-motion)면 바로 바뀐다.
대화하기
입력 독에 말을 적어 보내면 응답이 CONVERSATION 카드에 스트리밍으로 쌓인다.
- Enter 나 SEND 로 보낸다. 보내면 입력이 잠기고 THINKING 자리표시가 뜬다. 첫 이벤트가 오면 자리표시가 스트리밍 메시지로 바뀐다. 90초 안에 아무 이벤트가 없으면 자리표시를 지우고 대기 상태로 돌아간다
/로 시작하면 자동완성 팝업이 뜬다. ↑↓ 로 움직이고, Enter 나 Tab 으로 고르고, Esc 로 닫는다. 문장 중간의/명령도 하이라이트된다Ctrl+K로 중단한다. 스트림을 끝내고 입력을 돌려준다- 응답을 읽는 중이면
Esc로 읽기를 멈춘다 - 응답에 8줄 이상인 코드블록이 있으면 오른쪽 아티팩트 패널에 뜬다(COPY, ✕). 코드블록마다 COPY 버튼이 붙는다
- 입력은 한 줄이고 줄바꿈은 넣을 수 없다
승인하기
승인이 필요한 도구가 불리면 모달이 뜬다. ALLOW 는 이번만 허용하고, ALWAYS · 패턴 은 그 패턴을 규칙으로 저장하고, DENY 는 거부한다. ALWAYS 버튼은 서버가 패턴을 제안했을 때만 보인다. Enter 를 누르면 ALLOW 다.
같은 세션을 여러 탭에서 보고 있으면 모든 탭이 모달을 받는다. 한 탭이 답하면 나머지 모달은 닫히고 ACTIVITY 에 "다른 창에서 처리됨" 이 남는다. 120초 동안 답이 없으면 시간 초과로 거부한다(응답 문구).
음성으로 시작한 요청이거나 말로 이어 가는 대화 중이면 모달 대신 화면 아래쪽에 띠로 띄우고 승인을 음성으로 묻는다. 답을 들을 때까지 다시 듣는다(최대 20번). 띠의 버튼도 그대로 누를 수 있다.
모드 바꾸기
음성에는 모드 전환이 없다. 타이핑한 요청은 화면으로만 답하고, 구체 클릭, "Jarvis" 웨이크워드, 데스크톱 전역 단축키처럼 말로 시작한 요청은 답을 읽어 준 뒤 다시 들으며 대화를 이어 간다(Voice Interface). 모드는 /focus <작업> 으로 켜는 Focus 레이아웃 하나이고, 자세한 내용은 Mode에 있다. Focus 중에는 리액터 캡션이 한 줄로 줄고, 응답이 나오는 동안 CONVERSATION 띠가 빛난다. 띠를 누르면 전체 대화가 펼쳐진다.
세션을 다른 에이전트(예: KAREN)로 바꾸면 화면 색이 약 0.9초에 걸쳐 그 에이전트 색으로 섞인다.
에이전트 바꾸기
최상위 에이전트가 둘 이상이면 리액터 구체 양옆에 반투명 화살표가 뜬다. 화살표를 누르거나 구체를 좌우로 48px 이상 밀면 이전 또는 다음 에이전트로 바뀌고, 끝에서는 반대 끝으로 돈다. 짧게 누르면 그대로 클릭이라 듣기가 켜지거나 꺼진다. 옮겨 갈 곳은 그 에이전트의 열린 세션 중 맨 위(peer- 세션 제외)이고, 없으면 새 세션을 만든다.
바꾸면 링과 별, 입자 구, 워드마크가 한쪽으로 밀려 나가고, 새 세션이 붙어 색이 바뀐 뒤 새 에이전트의 구체가 반대편에서 들어온다. "Change to KAREN." 같은 문구도 읽는다. 바꾸지 못하면 구체가 나갔던 쪽에서 다시 돌아온다. 화살표에 마우스를 올리면 그 에이전트의 메인 색으로 빛나고, 그 에이전트가 일하는 중(서버의 agent_activity)이면 화살표가 맥박처럼 깜빡인다. Focus 모드 중과 에이전트가 하나일 때는 화살표를 숨긴다.
먼저 건네는 말 받기
먼저 건네는 말, 대기 안내, 스케줄 알림은 따로 표시하지 않고 에이전트의 보통 답과 같은 말풍선으로 보인다. 대화 기록에도 그 에이전트의 말로 남는다. "도움이 됐나요?" 라고 묻지 않는다.
그 뒤 사용자의 첫 말은 보통 메시지로 에이전트에 가고, 서버가 따로 그 말이 받아들임, 거절, 딴 얘기 중 무엇인지 분류해 배운다. 더 묻거나 이어 시키는 말도 받아들임이다.
말로 이어 가는 대화 중이면 먼저 건네는 말을 읽어 주고, 읽은 뒤 답을 듣는다. 대화 중이 아니면 서버가 speak 로 표시한 말만 읽는다. 사용자가 말하거나, 듣거나, 다른 말을 읽거나, 에이전트가 일하는 중이면 끊지 않고 끝난 뒤에 읽는다. 미룬 말은 가장 새것 하나만 둔다.
세션 다루기
SESSIONS 카드에서 세션을 만들고, 바꾸고, 분기하고, 지운다.
+로 새 세션을 만든다. 이름을 클릭해 전환하면 대화, 사용량, 아티팩트가 초기화되고 히스토리가 복원된다- ⑂ 로 활성 세션을 분기한다. Postgres 저장소에서는 빈 새 세션이 만들어진다
- ✕ 는 보고 있지 않은 세션에만 보인다. 확인을 받은 뒤 지운다
✕ 로 지운 세션은 되돌릴 수 없다.
접근 키 넣기
JARVIS_SECURITY__API_KEYS 가 설정돼 있으면 첫 연결이 4401 로 끊기고, 브라우저가 키를 한 번 묻는다. 입력한 키는 localStorage 에 저장된다. 묻는 창을 취소하면 상단 배너와 ACTIVITY 에 "접근 키 없음" 이 뜬다.
연결이 끊겼을 때
WS 가 끊기면 헤더의 연결 점이 빨갛게 바뀌고, 헤더 바로 아래에 연결 끊김 — 재연결 중... 배너가 뜨고 입력이 잠긴다. 재접속 간격은 1초에서 시작해 2배씩 늘고, 최대 10초에서 멈춘다. agent_error 와 error 가 오면 SYS 메시지를 띄우고 리액터 상태를 3초 동안 ERROR 로 둔다. AGENDA 나 TOOLS 요청이 실패하면 콘솔에 경고만 남긴다.
정적 파일과 캐시
Docker 에서는 nginx 가 정적 HTML 과 ES 모듈(src/jarvis/ui/web/static/)을 서빙하고, /api/*, /ws, /brand.js, /manifest.json 만 백엔드로 넘긴다. jarvis --web 으로 띄우면 백엔드가 정적 파일까지 직접 서빙한다. 세션을 바꾸면 WebSocket 을 다시 연결한다.
서비스 워커는 셸 파일을 네트워크 우선으로 받고, 연결이 끊겼을 때만 캐시를 쓴다. 버전 문자열이 없으므로 파일을 고치면 새로고침만으로 반영된다. manifest.json 과 아이콘이 있어 홈 화면에 추가할 수 있다. 브랜드 이름과 색은 /brand.js 로 내려온다.
화면 검증하기
화면을 고친 뒤 동작을 확인하는 방법은 두 가지다.
- 수동 시나리오 3개(Proactive Dialogue 와 피드백, 승인 기억, 절차 학습)는
scripts/e2e/hud-scenario.md에 있다 - 자동 e2e 는
uv run python scripts/e2e/launch_hud.py &로 스크립트 프로바이더 HUD 를 7799 포트에 띄운 뒤uv run --with playwright python scripts/e2e/hud_flow.py를 실행한다