Files

joungmin 41457ab96e [08-Documenter] #311 설계서 Approved + reference + 사용자 가이드 FAQ

- docs/design/311-llm-warmup/ 3파일 상태 Draft → Approved (v0.4.1)
- docs/reference/311-llm-warmup.md 신규 (상태 머신, API, UI binding,
  마이크로카피, 테스트)
- docs/guides/ai-chat-using.md 헤더 + FAQ 2건 추가 (warmup 인지/회복)

Refs #311

2026-06-15 13:25:38 +09:00

4.5 KiB

Raw Permalink Blame History

AI 코치와 대화하기 (사용자 가이드)

적용 버전: v0.4.0 이상 (warm-up 은 v0.4.1+) · Redmine #260 / #311 · 관련 레퍼런스: 도구 호출 · Warm-up

본 가이드는 v0.3.0 의 AI 도움 켜기·끄기 가 끝났다는 전제에서 시작합니다. 모델이 단말에 준비되어 있어야 합니다.

v0.4.0 부터는 자유 문장으로 AI 코치에게 카탈로그를 묻거나, 습관을 추가하거나, 오늘의 체크인을 기록할 수 있습니다. 모든 처리는 단말에서 일어나며 입력 텍스트는 외부로 나가지 않습니다.

진입

습관 목록 화면 진입.
AppBar 의 🤖 (smart toy) 아이콘 탭.
- AI 도움이 꺼져 있으면 아이콘이 보이지 않습니다 — AI 도움 켜기 먼저 진행해주세요.

가능한 대화 예시

"아침 햇빛 프로토콜이 뭐야?" → AI 가 카탈로그에서 찾아 한국어로 요약.
"수면 관련 습관 추천해줘" → 카테고리 검색 결과를 보여주고 어떤 것부터 시작할지 제안.
"아침 햇빛 보기 습관 추가해줘" → 확인 다이얼로그가 떠야 추가됩니다 (아래 §확인 게이트).
"오늘 햇빛 체크해줘" → 같은 식의 확인 다이얼로그.
"내 스트릭 어때?" → 현재 연속일수 + 5-tier 보상 등급 안내.

확인 게이트 (destructive actions)

다음 작업은 사용자의 명시적 확인 없이는 절대 수행되지 않습니다:

습관 추가 (add_habit)
체크 기록 (log_tracker_entry)

확인 다이얼로그가 뜨면:

수행 — 작업 진행
취소 — 작업 중단 (대화에는 🛠 습관 추가 → 취소됨 라벨이 남습니다)
바깥 영역 탭 = 취소

안전장치

한 대화당 최대 4번의 도구 호출 — 무한 루프 방지.
8 turn 도달 시 "대화가 길어졌어요" 안내 — 오른쪽 위 ↻ 로 새 대화 시작 권장 (이전 기록은 비워짐).
AI 가 잘못된 인자로 도구를 호출하면 검증 오류 메시지를 모델에게 돌려주고, AI 가 다시 시도합니다. 앱이 죽지 않습니다.
"술 끊기" 같은 회피 표현은 R7 규칙으로 자동 거부 + 긍정 프레임 제안 ("맑은 정신을 즐긴다" 등).
활성 build 습관 3개 / break 습관 1개 초과 시 R3 규칙으로 거부 — 기존 습관을 정리해야 추가 가능.
같은 날짜의 같은 습관에 두 번 체크하면 중복 안내 — 덮어쓰려면 기존 항목 삭제 후 다시 시도.

자주 묻는 질문

Q. 대화 기록은 어디에 저장되나요? A. 메모리만 — 화면을 떠나거나 ↻ 를 누르면 사라집니다. 단말에 저장되지 않습니다.

Q. AI 가 같은 도구를 계속 호출하면? A. 4 회를 넘기면 자동으로 멈추고 "도구 호출 루프가 너무 길어 중단했습니다" 안내가 뜹니다.

Q. 응답이 너무 느린 것 같아요. A. 단말 모델이라 1턴 평균 2~~5초가 정상입니다. AI 가 도구를 호출하면 round trip 이 한 번 더 들어가 6~~10초가 될 수 있어요.

Q. ChatScreen 진입 시 입력창에 "AI 준비 중…" 이 떠요. A. v0.4.1 부터 모델을 백그라운드로 미리 시동합니다 (warm-up). 첫 진입 시 한 번만 보이고 평균 2~8초 안에 사라집니다. 그동안 메시지를 미리 타이핑해도 되고, send 버튼만 비활성 상태로 기다립니다. 다시 진입하면 즉시 사용 가능합니다.

Q. "AI 모델 파일을 찾을 수 없어요." / "AI 를 시작하지 못했어요." 가 떠요. A. 파일을 못 찾는 경우는 [설정으로 가기] 로 이동해 재다운로드, 일시적 시작 실패는 [다시 시도] 로 회복합니다. 설정에서 다운로드를 완료하고 돌아오면 자동으로 다시 시도합니다.

Q. 도구 결과가 잘렸어요. A. 모델 컨텍스트 보호를 위해 도구 결과는 2KB 로 제한됩니다. 잘림이 발생하면 AI 가 자동으로 단건 조회 (프로토콜 상세) 도구를 다시 부르도록 안내됩니다.

4.5 KiB Raw Permalink Blame History