joungmin
44d571f4ee
- docs/reference/260-in-app-tool-calling.md — 구현 후 동기화. 11 섹션 (모듈 지도 / 6 tool 표 / R 규칙 enforce / multi-turn 루프 / dispatcher / ConfirmGate / 2KB cap / LlmChatSession 두 구현 / UI 진입점 / 테스트 / known limitations). - docs/guides/ai-chat-using.md — 사용자 대상 how-to. 진입(🤖) / 대화 예시 / 확인 게이트 / 안전장치 / FAQ. - 후속 4건 Redmine 이슈 발행: #306 koreanLabel 필드 / #307 blank confirm skip / #308 category case-insensitive / #309 KGP deprecation. Refs #260
3.8 KiB
3.8 KiB
AI 코치와 대화하기 (사용자 가이드)
적용 버전: v0.4.0 이상 · Redmine #260 · 관련 레퍼런스: docs/reference/260-in-app-tool-calling.md
본 가이드는 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턴 평균 25초가 정상입니다. AI 가 도구를 호출하면 round trip 이 한 번 더 들어가 610초가 될 수 있어요.
Q. 도구 결과가 잘렸어요.
A. 모델 컨텍스트 보호를 위해 도구 결과는 2KB 로 제한됩니다. 잘림이 발생하면 AI 가 자동으로 단건 조회 (프로토콜 상세) 도구를 다시 부르도록 안내됩니다.