joungmin
41457ab96e
- 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
71 lines
4.5 KiB
Markdown
71 lines
4.5 KiB
Markdown
# AI 코치와 대화하기 (사용자 가이드)
|
|
|
|
> 적용 버전: **v0.4.0 이상** (warm-up 은 **v0.4.1+**) · Redmine #260 / #311 · 관련 레퍼런스: [도구 호출](../reference/260-in-app-tool-calling.md) · [Warm-up](../reference/311-llm-warmup.md)
|
|
>
|
|
> 본 가이드는 v0.3.0 의 [AI 도움 켜기·끄기](ai-help-onboarding.md) 가 끝났다는 전제에서 시작합니다. 모델이 단말에 준비되어 있어야 합니다.
|
|
|
|
v0.4.0 부터는 자유 문장으로 AI 코치에게 카탈로그를 묻거나, 습관을 추가하거나, 오늘의 체크인을 기록할 수 있습니다. 모든 처리는 단말에서 일어나며 입력 텍스트는 외부로 나가지 않습니다.
|
|
|
|
## 진입
|
|
|
|
1. **습관 목록** 화면 진입.
|
|
2. AppBar 의 🤖 (smart toy) 아이콘 탭.
|
|
- AI 도움이 꺼져 있으면 아이콘이 보이지 않습니다 — [AI 도움 켜기](ai-help-onboarding.md) 먼저 진행해주세요.
|
|
|
|
## 가능한 대화 예시
|
|
|
|
- "아침 햇빛 프로토콜이 뭐야?" → 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 가 자동으로 단건 조회 (`프로토콜 상세`) 도구를 다시 부르도록 안내됩니다.
|
|
|
|
## 관련 문서
|
|
|
|
- [AI 도움 켜기·끄기](ai-help-onboarding.md)
|
|
- 설계서: [docs/design/260-gemma-tool-calling/](../design/260-gemma-tool-calling/)
|
|
- 결정 기록: [docs/adr/0005-in-app-tool-calling-architecture.md](../adr/0005-in-app-tool-calling-architecture.md)
|
|
- API 레퍼런스: [docs/reference/260-in-app-tool-calling.md](../reference/260-in-app-tool-calling.md)
|
|
- 변경 이력: [CHANGELOG.md](../../CHANGELOG.md)
|