# Kamibot — 전체 기능 상세 문서

> 카미봇은 3,200만 명 이상의 사용자가 이용하는 대규모 한국어 Discord 봇입니다. AI 대화, TTS(음성 합성), 이모지 업스케일링, AI 그림 생성, 서버 관리, 파일 공유, 가변 음성 채널 등 다양한 기능을 무료로 제공합니다.

- 웹사이트: [https://kamibot.app](https://kamibot.app)
- 대시보드: [https://kamibot.app/dashboard/](https://kamibot.app/dashboard/)
- 도움말: [https://help.kamibot.app](https://help.kamibot.app)
- 클라우드 파일: [https://cloud.kamibot.app](https://cloud.kamibot.app)
- 지원 서버: [https://discord.gg/kamibot](https://discord.gg/kamibot)
- 봇 초대: [https://kamibot.app/](https://kamibot.app/) (프로필에서 "서버에 추가")
- 개발자: Kamilake (카미)
- 탄생일: 2022년 9월 13일, 본격 활동 시작 2024년
- 가격: 무료
- 요약 문서: [llms.txt](https://kamibot.app/llms.txt)

## 목차

1. [AI 대화](#1-ai-대화-chatgpt-연동)
2. [TTS (텍스트 음성 변환)](#2-tts-텍스트-음성-변환)
3. [이모지 업스케일링](#3-이모지-업스케일링)
4. [AI 그림 생성](#4-ai-그림-생성-stable-diffusion)
5. [파일 공유](#5-파일-공유)
6. [서버 관리 도구](#6-서버-관리-도구)
7. [가변 음성 채널](#7-가변-음성-채널)
8. [키워드 알림](#8-키워드-알림)
9. [유튜브 알림](#9-유튜브-알림)
10. [채팅 스크린샷](#10-채팅-스크린샷)
11. [컨텍스트 메뉴 명령어](#11-컨텍스트-메뉴-명령어)
12. [채널 전용 기능](#12-채널-전용-기능)
13. [자동 임베드 및 변환 기능](#13-자동-임베드-및-변환-기능)
14. [환영 및 온보딩](#14-환영-및-온보딩)
15. [유동닉 (익명 채팅)](#15-유동닉-익명-채팅)
16. [메시지 프록시](#16-메시지-프록시)
17. [설정 시스템](#17-설정-시스템)
18. [웹 대시보드 및 API](#18-웹-api)
19. [개인정보 보호정책](#21-개인정보-보호정책)
20. [필요 권한](#22-필요-권한)

---

## 1. AI 대화 (ChatGPT 연동)

카미봇은 LLM(대규모 언어 모델) 기반 AI 대화 기능을 제공합니다.

### 사용 방법
- **멘션**: 아무 채널에서 카미봇을 @멘션하면 AI가 응답합니다.
- **AI 전용 채널**: 서버 설정에서 AI 채팅 전용 채널을 지정하면 멘션 없이 대화할 수 있습니다.
- **답장**: 카미봇의 응답에 답장하면 대화를 이어갈 수 있습니다.
- **스레드**: 스레드 내에서 대화하면 맥락이 유지됩니다.

### 특징
- 다중 LLM 프로바이더 지원 (LlmProviderRegistry를 통한 OpenAI 등)
- Function Calling 지원 (최대 25회 반복 도구 호출)
  - 서버 관리 작업 수행 (DM 전송, 모더레이션 액션)
  - Python 스크립트 실행 (사용자 확인 버튼 포함)
- `!`, `:`, `.`으로 시작하는 메시지는 AI가 무시합니다.

---

## 2. TTS (텍스트 음성 변환)

음성 채널에서 채팅 메시지를 자동으로 읽어주는 기능입니다.

### 명령어
- `/tts` — TTS 활성화/비활성화

### 음성 엔진
- AWS Polly
- Google Cloud TTS
- Microsoft Edge TTS
- Naver TTS

### 기능 상세
- **자동 읽기**: TTS가 활성화된 채널에서 보내는 모든 메시지를 자동으로 음성으로 변환합니다.
- **목소리 선택**: `/설정` 명령의 SelectMenu에서 원하는 TTS 목소리를 선택할 수 있습니다.
- **입퇴장 알림**: 음성 채널에 사용자가 입장하거나 퇴장할 때 TTS로 알려줍니다.
- **자동 시작**: 설정된 채널에서 사용자가 입장하면 TTS가 자동으로 시작됩니다.
- **다중 채널 지원**: 부계정(서브봇)을 활용하여 여러 음성 채널에서 동시에 TTS를 사용할 수 있습니다.

### 설정 옵션
- TTS 목소리 변경
- 입퇴장 알림 on/off
- 알림 스타일 설정
- TTS 자동 시작 채널 지정

---

## 3. 이모지 업스케일링

이모지 하나만 포함된 메시지를 감지하여 큰 이미지로 변환합니다.

### 동작 방식
- 사용자가 이모지 1개만 포함된 메시지를 보내면, 카미봇이 웹후크를 통해 해당 이모지를 큰 이미지로 다시 전송합니다.
- 서버 설정에서 이 기능을 on/off할 수 있습니다.

### 관련 기능
- **이모지 업로드 채널**: 전용 채널에 이미지를 업로드하면 서버 이모지로 자동 추가됩니다.
- **이모지 경고 설명**: 카미봇의 경고 리액션에 대한 설명을 제공합니다.

---

## 4. AI 그림 생성 (Stable Diffusion)

### 슬래시 명령어
`/sd` — Stable Diffusion 기반 AI 그림 생성

### 옵션
| 옵션 | 설명 |
|------|------|
| `키1` ~ `키18` | 프롬프트 키워드 (자동완성 지원) |
| `스텝` | 생성 스텝 수 |
| `이미지-개수` | 생성할 이미지 수 |
| `시드` | 랜덤 시드 값 |
| `네거티브-프롬프트` | 제외할 요소 |
| `해상도` | 출력 해상도 |

### AI 툴킷 채널
- AI 툴킷 전용 채널에 사진을 업로드하면 AI가 자동으로 인식하여 그림을 생성합니다.
- SDXL txt2img, SD1.5 img2img 지원

---

## 5. 파일 공유

### 대용량 파일 업로드
`/upload` (`/업로드`) — Nitro 없이 최대 100GB 파일 업로드
- 웹 업로드 링크를 제공하여 브라우저에서 파일을 업로드합니다.
- 업로드된 파일은 클라우드(https://cloud.kamibot.app)에서 접근 가능합니다.

### 일괄 다운로드
`/다운로드` — 채널의 사진과 첨부파일을 일괄 다운로드
- **옵션**: 지정 범위, 최근 24시간, 최근 2000개 메시지
- **범위 지정**: `선택 / 범위 지정` 컨텍스트 메뉴로 시작/끝 메시지를 지정할 수 있습니다.
- ZIP 파일로 NAS WebDAV를 통해 다운로드 링크를 제공합니다.

---

## 6. 서버 관리 도구

### 메시지 삭제
`/clear` (`/청소`) — 메시지 일괄 삭제
- **빠른 삭제**: `/clear count:숫자`로 즉시 삭제
- **고급 삭제 UI**: 옵션 없이 실행하면 SelectMenu 기반 필터링 UI 제공
  - 채널 선택
  - 삭제할 메시지 수 지정
  - 특정 사용자 메시지만 삭제
  - 기간 필터링
- 삭제 전 확인 Modal이 표시됩니다.

### 서버 통계
`/통계` — 서버 대화량 분석
- **서브커맨드**: 이번주 서버 대화량, 채널별 대화량, 스티커 사용량, 오래된 이모지 찾기
- 최소 1주일 이상의 데이터가 필요합니다.
- 그래프 형태로 시각화됩니다.

### 오늘의 베스트 멤버
- 오늘 가장 많은 메시지를 보낸 사용자에게 초록색 역할을 자동 부여합니다.
- 매일 오전 4시에 초기화됩니다.

### 멤버 추적
- 멤버 입퇴장, 닉네임 변경, 역할 변경, 밴 등을 로깅합니다.

---

## 7. 가변 음성 채널

사용자가 트리거 채널에 입장하면 자동으로 새 음성 채널을 생성하고, 모두 퇴장하면 삭제합니다.

### 기능
- **자동 생성**: 트리거 채널 입장 시 새 음성 채널 생성
- **방장 권한**: 입장한 사용자에게 채널 관리 권한 부여
- **채널 이름 변경**: 버튼 → Modal로 채널 이름 변경
- **채널 잠금/해제**: 버튼으로 입장 잠금/해제
- **TTS 활성화**: 버튼으로 가변 채널에서 TTS 시작
- **음악 정지**: 버튼으로 음악 재생 정지

---

## 8. 키워드 알림

`/키워드알림` — 카카오톡 스타일 키워드 알림

### 사용 방법
- `/키워드알림 옵션:추가 키워드:단어` — 키워드 등록
- `/키워드알림 옵션:삭제 키워드:단어` — 키워드 삭제
- 키워드 자동완성을 지원합니다.

### 동작 방식
- 등록한 키워드가 포함된 메시지가 서버에 올라오면 DM으로 알림을 받습니다.
- 자신이 보낸 메시지는 알림하지 않습니다.

---

## 9. 유튜브 알림

`/구독알림` — 유튜브 채널 새 동영상 알림 설정

### 동작 방식
- YouTube PubSubHubbub 프로토콜을 사용하여 실시간 알림을 제공합니다.
- 설정한 채널에 새 동영상이 업로드되면 Discord 채널에 알림 메시지를 전송합니다.

---

## 10. 채팅 스크린샷

`/스크린샷` — 채팅 내용을 스크롤캡처

### 기능
- 지정한 수의 메시지를 캡처하여 이미지로 생성합니다.
- 프로필 익명화 옵션을 제공합니다.
- Modal로 캡처할 메시지 수를 입력합니다.

---

## 11. 컨텍스트 메뉴 명령어

메시지나 사용자를 우클릭하여 사용하는 명령어입니다.

### 사용자 컨텍스트 메뉴
| 명령어 | 설명 |
|--------|------|
| `사용자 정보 보기` | 프로필 사진, 배너, 가입일, TTS 설정 등 상세 정보 표시 |

### 메시지 컨텍스트 메뉴
| 명령어 | 설명 |
|--------|------|
| `나에게 보내기` | 선택한 메시지를 DM으로 전송 |
| `원본 보기` | 메시지 원본 텍스트, 스티커 URL 등 표시 |
| `선택 / 범위 지정` | 다운로드 범위의 시작/끝 메시지 지정 |

---

## 12. 채널 전용 기능

서버 설정에서 채널에 특수 기능을 부여할 수 있습니다.

| 채널 타입 | 기능 | 설명 |
|-----------|------|------|
| AI 채팅 | `LLM` | 멘션 없이 AI와 대화할 수 있는 전용 채널 |
| AI 툴킷 | `AI_TOOLKIT` | 사진 업로드 시 AI가 자동으로 그림 변환 |
| 유동닉 | `YUDONGNICK` | 익명 게시판 스타일 — IP 형식 닉네임으로 웹후크 메시지 전송 |
| 번역 | `TRANSLATE` | 메시지를 Papago로 자동 번역하여 웹후크로 전송 |
| 이모지 업로드 | `EMOTE_UPLOAD` | 이미지 업로드 시 서버 이모지로 자동 추가 |
| 가변 음성 채널 | `VCHANNEL` | 입장 시 자동 음성 채널 생성 트리거 |

---

## 13. 자동 임베드 및 변환 기능

사용자가 별도 명령 없이 자동으로 동작하는 기능들입니다.

### Twitter/X 임베드 개선
- `x.com` 또는 `twitter.com` URL이 포함된 메시지를 감지하여 임베드가 개선된 URL로 웹후크 메시지를 전송합니다.

### BOOTH 임베드
- `booth.pm` URL이 포함된 메시지를 감지하여 상품 정보 임베드와 한국어 번역을 제공합니다.

### 미디어 변환
- 첨부파일의 문서/이미지 포맷을 자동으로 변환합니다.
- 상세 안내: https://help.kamibot.app/media_converter/

### 번역 채널
- 번역 전용 채널에서 메시지를 Papago로 자동 번역하여 웹후크로 전송합니다.

---

## 14. 환영 및 온보딩

### 환영 메시지
- 새 멤버가 서버에 입장하면 gRPC를 통해 커스텀 환영 이미지를 생성하고 환영 메시지를 전송합니다.

### VRChat 온보딩
- VRChat 연동 가입 절차를 제공합니다 (Modal, SelectMenu, 버튼 기반).

### 퇴장 설문조사
- 멤버가 서버를 퇴장하면 서버 주인에게 DM으로 퇴장 사유 설문(Poll)을 전송합니다.

### 튜토리얼
- 카미봇의 주요 기능 채널을 자동으로 생성하는 가이드를 제공합니다.
- `/help`에서 "카미봇 채널 자동 생성"을 선택하면 버튼 하나로 가변 음성, TTS, AI 채팅, AI 툴킷, 이모지 업로드, 비밀 채팅, 익명 채팅 채널을 자동 생성합니다.

---

## 15. 유동닉 (익명 채팅)

유동닉 전용 채널에서 익명 게시판 스타일로 채팅할 수 있습니다.

### 동작 방식
- 유동닉 채널에서 메시지를 보내면 IP 스타일 닉네임(예: `ㅇㅇ (123.456)`)으로 웹후크 메시지가 전송됩니다.
- 원본 메시지는 삭제됩니다.

### 기능
- **IP 초기화**: 설정 UI에서 유동 IP를 초기화할 수 있습니다.
- **닉네임 변경**: Modal을 통해 표시 닉네임을 변경할 수 있습니다.

---

## 16. 메시지 프록시

설정된 채널 쌍 간에 메시지를 양방향으로 미러링합니다.

### 기능
- 웹후크를 사용하여 메시지를 복제합니다.
- 메시지 수정 및 삭제도 동기화됩니다.

---

## 17. 설정 시스템

`/설정` — 카미봇의 모든 설정을 관리하는 대시보드

### 설정 범위
- **개인 설정**: TTS 목소리, 알림 설정 등
- **채널 설정**: 채널별 기능 활성화/비활성화, 전용 채널 타입 지정
- **서버 설정**: 서버 전체 기능 설정

### 웹 대시보드
- https://kamibot.app/dashboard/ 에서 Discord OAuth2 로그인 후 웹에서도 설정을 관리할 수 있습니다.

---

## 18. 웹 API

카미봇은 웹 대시보드를 위한 REST API를 제공합니다.

### 주요 엔드포인트
| 엔드포인트 | 설명 |
|-----------|------|
| `GET /api/guilds` | 사용자의 길드 목록 |
| `GET /api/guilds/{guildId}/settings` | 길드 설정 조회 |
| `PUT /api/guilds/{guildId}/settings` | 길드 설정 변경 |
| `GET /api/guilds/{guildId}/channels` | 길드 채널 목록 |
| `GET /api/guilds/{guildId}/channels/{channelId}/settings` | 채널 설정 조회 |
| `PUT /api/guilds/{guildId}/channels/{channelId}/settings` | 채널 설정 변경 |
| `GET /api/users/@me` | 현재 사용자 정보 |
| `GET /api/users/@me/tts/actors` | TTS 목소리 목록 |
| `GET /api/users/@me/keywords` | 키워드 알림 목록 |
| `POST /api/cloud/*` | 클라우드 파일 업로드 |
| `GET /api/kamibot/status` | 봇 상태 정보 |
| `GET /api/health` | 헬스 체크 |

### 인증
- Discord OAuth2를 통한 인증
- 콜백 URL: `/api/auth/discord`
- 세션 기반 인증 (Tomcat 세션 DB 저장)

---

## 19. 개인정보 보호정책

- 최소한의 데이터만 수집합니다.
- 수집된 데이터는 7일 또는 재부팅 시 삭제됩니다.
- 사용자는 언제든지 데이터 삭제를 요청할 수 있습니다.
- 지원 서버([https://discord.gg/kamibot](https://discord.gg/kamibot))에서 문의 가능합니다.

---

## 20. 필요 권한

카미봇을 서버에 초대할 때 다음 권한이 필요합니다:
- 역할 관리
- 웹후크 관리
- 메시지 읽기/보내기
- 스레드 관리
- 음성 채널 연결/말하기
- 메시지 기록 보기
- 파일 첨부
- 임베드 링크
- 외부 이모지 사용
- 리액션 추가
- 메시지 관리 (삭제 기능용)

---

## 21. 후원

카미봇은 무료로 운영되며, [https://kamibot.app/donate](https://kamibot.app/donate) 에서 후원할 수 있습니다.