diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b2681b4bf..fdb595fde 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -769,30 +769,131 @@ export default defineConfig({ text: '설정', items: [ { text: '설정 가이드', link: withBase('/ko/docs/manual/config/') }, + { text: '공통 설정', link: withBase('/ko/docs/manual/config/common') }, + { text: '기능 설정', collapsed: true, items: [ + { text: '채팅 모델', link: withBase('/ko/docs/manual/config/llm') }, + { text: '오디오 입출력', link: withBase('/ko/docs/manual/config/audio') }, + { text: '비전', link: withBase('/ko/docs/manual/config/vision') }, + { text: '웹 검색', link: withBase('/ko/docs/manual/config/web-search') }, + ] }, + { text: '서비스 제공자', collapsed: true, items: [ + { text: '채팅', collapsed: true, items: [ + { text: 'AIRI 공식 제공자', link: withBase('/ko/docs/manual/config/providers/consciousness/official') }, + { text: 'AIHubMix', link: withBase('/ko/docs/manual/config/providers/consciousness/aihubmix') }, + { text: 'Amazon Bedrock', link: withBase('/ko/docs/manual/config/providers/consciousness/amazon-bedrock') }, + { text: 'Anthropic', link: withBase('/ko/docs/manual/config/providers/consciousness/anthropic') }, + { text: 'Atlas Cloud', link: withBase('/ko/docs/manual/config/providers/consciousness/atlascloud') }, + { text: 'Azure AI Foundry', link: withBase('/ko/docs/manual/config/providers/consciousness/azure-ai-foundry') }, + { text: 'Azure OpenAI', link: withBase('/ko/docs/manual/config/providers/consciousness/azure-openai') }, + { text: 'BytePlus', link: withBase('/ko/docs/manual/config/providers/consciousness/byteplus') }, + { text: 'BytePlus Coding Plan', link: withBase('/ko/docs/manual/config/providers/consciousness/byteplus-coding-plan') }, + { text: 'Cerebras', link: withBase('/ko/docs/manual/config/providers/consciousness/cerebras') }, + { text: 'Comet API', link: withBase('/ko/docs/manual/config/providers/consciousness/comet-api') }, + { text: 'Google Gemini', link: withBase('/ko/docs/manual/config/providers/consciousness/google-gemini') }, + { text: 'xAI', link: withBase('/ko/docs/manual/config/providers/consciousness/xai') }, + { text: 'Cloudflare Workers AI', link: withBase('/ko/docs/manual/config/providers/consciousness/cloudflare-workers-ai') }, + { text: 'LM Studio (로컬 모델)', link: withBase('/ko/docs/manual/config/providers/consciousness/lm-studio') }, + { text: 'OpenPaths', link: withBase('/ko/docs/manual/config/providers/consciousness/openpaths') }, + { text: 'OpenRouter', link: withBase('/ko/docs/manual/config/providers/consciousness/openrouter') }, + { text: 'Ollama', link: withBase('/ko/docs/manual/config/providers/consciousness/ollama') }, + { text: 'DeepSeek', link: withBase('/ko/docs/manual/config/providers/consciousness/deepseek') }, + { text: 'OpenAI & 호환 API', link: withBase('/ko/docs/manual/config/providers/consciousness/openai') }, + { text: '302.AI', link: withBase('/ko/docs/manual/config/providers/consciousness/302ai') }, + { text: 'Fireworks.ai', link: withBase('/ko/docs/manual/config/providers/consciousness/fireworks') }, + { text: 'Featherless AI', link: withBase('/ko/docs/manual/config/providers/consciousness/featherless') }, + { text: 'Groq', link: withBase('/ko/docs/manual/config/providers/consciousness/groq') }, + { text: 'MiniMax', link: withBase('/ko/docs/manual/config/providers/consciousness/minimax') }, + { text: 'MiniMax Global', link: withBase('/ko/docs/manual/config/providers/consciousness/minimax-global') }, + { text: 'Mistral', link: withBase('/ko/docs/manual/config/providers/consciousness/mistral') }, + { text: 'Xiaomi MiMo', link: withBase('/ko/docs/manual/config/providers/consciousness/mimo') }, + { text: 'ModelScope', link: withBase('/ko/docs/manual/config/providers/consciousness/modelscope') }, + { text: 'Moonshot AI', link: withBase('/ko/docs/manual/config/providers/consciousness/moonshot') }, + { text: 'NVIDIA NIM', link: withBase('/ko/docs/manual/config/providers/consciousness/nvidia') }, + { text: 'n1n', link: withBase('/ko/docs/manual/config/providers/consciousness/n1n') }, + { text: 'Novita', link: withBase('/ko/docs/manual/config/providers/consciousness/novita') }, + { text: 'Perplexity', link: withBase('/ko/docs/manual/config/providers/consciousness/perplexity') }, + { text: 'Together.ai', link: withBase('/ko/docs/manual/config/providers/consciousness/together') }, + { text: 'Z.ai', link: withBase('/ko/docs/manual/config/providers/consciousness/zhipu') }, + { text: 'Volcengine Coding Plan', link: withBase('/ko/docs/manual/config/providers/consciousness/volcengine-coding-plan') }, + ] }, + { text: '음성 합성', collapsed: true, items: [ + { text: '공식 음성 합성 제공자', link: withBase('/ko/docs/manual/config/providers/speech/official') }, + { text: 'Alibaba Cloud Model Studio', link: withBase('/ko/docs/manual/config/providers/speech/alibaba-cloud-model-studio') }, + { text: '브라우저 (로컬)', link: withBase('/ko/docs/manual/config/providers/speech/browser-local') }, + { text: 'Comet API', link: withBase('/ko/docs/manual/config/providers/speech/comet-api') }, + { text: 'Deepgram', link: withBase('/ko/docs/manual/config/providers/speech/deepgram') }, + { text: '데스크톱 (로컬)', link: withBase('/ko/docs/manual/config/providers/speech/desktop-local') }, + { text: 'ElevenLabs', link: withBase('/ko/docs/manual/config/providers/speech/elevenlabs') }, + { text: 'Google Gemini', link: withBase('/ko/docs/manual/config/providers/speech/google-gemini') }, + { text: 'Bilibili / IndexTTS', link: withBase('/ko/docs/manual/config/providers/speech/index-tts') }, + { text: 'Kokoro TTS (로컬)', link: withBase('/ko/docs/manual/config/providers/speech/kokoro') }, + { text: 'Microsoft Azure Speech', link: withBase('/ko/docs/manual/config/providers/speech/azure-speech') }, + { text: 'MiniMax Speech (사용 불가)', link: withBase('/ko/docs/manual/config/providers/speech/minimax') }, + { text: 'Xiaomi MiMo', link: withBase('/ko/docs/manual/config/providers/speech/mimo') }, + { text: 'OpenAI & 호환 API', link: withBase('/ko/docs/manual/config/providers/speech/openai') }, + { text: 'OpenRouter', link: withBase('/ko/docs/manual/config/providers/speech/openrouter') }, + { text: 'Player2', link: withBase('/ko/docs/manual/config/providers/speech/player2') }, + { text: 'Volcano Engine', link: withBase('/ko/docs/manual/config/providers/speech/volcengine') }, + ] }, + { text: '전사', collapsed: true, items: [ + { text: '공식 전사 제공자', link: withBase('/ko/docs/manual/config/providers/transcription/official') }, + { text: 'Aliyun NLS', link: withBase('/ko/docs/manual/config/providers/transcription/aliyun') }, + { text: '브라우저 (로컬)', link: withBase('/ko/docs/manual/config/providers/transcription/browser-local') }, + { text: '브라우저 Web Speech API', link: withBase('/ko/docs/manual/config/providers/transcription/web-speech-api') }, + { text: 'Comet API', link: withBase('/ko/docs/manual/config/providers/transcription/comet-api') }, + { text: '데스크톱 (로컬)', link: withBase('/ko/docs/manual/config/providers/transcription/desktop-local') }, + { text: 'Xiaomi MiMo', link: withBase('/ko/docs/manual/config/providers/transcription/mimo') }, + { text: 'OpenAI & 호환 API', link: withBase('/ko/docs/manual/config/providers/transcription/openai') }, + ] }, + { text: 'Artistry', collapsed: true, items: [ + { text: 'ComfyUI (로컬 워크플로)', link: withBase('/ko/docs/manual/config/providers/artistry/comfyui') }, + { text: 'Nano Banana', link: withBase('/ko/docs/manual/config/providers/artistry/nanobanana') }, + { text: 'Replicate', link: withBase('/ko/docs/manual/config/providers/artistry/replicate') }, + ] }, + ] }, ], }, ], }, { - text: '기여하기', - icon: 'lucide:users', + text: '연동 서비스', + icon: 'lucide:plug', items: [ { - text: '기본 설정', + text: '게임', + items: [ + { text: 'Minecraft 에이전트', link: withBase('/ko/docs/integrations/minecraft') }, + { text: 'Factorio', link: withBase('/ko/docs/integrations/factorio') }, + ], + }, + { + text: '메시징 플랫폼', + items: [ + { text: 'Satori 봇', link: withBase('/ko/docs/integrations/satori') }, + { text: 'Telegram 봇', link: withBase('/ko/docs/integrations/telegram') }, + { text: 'Discord 봇', link: withBase('/ko/docs/integrations/discord') }, + { text: 'X / Twitter (사용 불가)', link: withBase('/ko/docs/integrations/x') }, + ], + }, + ], + }, + { + text: '개발자 가이드', + icon: 'lucide:code-2', + items: [ + { + text: '기여하기', items: [ { text: '개발 환경 설정과 사전 준비', link: withBase('/ko/docs/contributing/') }, { text: '데스크톱 앱', link: withBase('/ko/docs/contributing/tamagotchi') }, - { text: '웹 UI', link: withBase('/ko/docs/contributing/webui') }, + { text: '웹 앱', link: withBase('/ko/docs/contributing/webui') }, { text: '문서 사이트', link: withBase('/ko/docs/contributing/docs') }, ], }, { - text: '게임 & 소셜 플랫폼', + text: '데스크톱 디버깅', items: [ - { text: 'Minecraft', link: withBase('/ko/docs/contributing/services/minecraft') }, - { text: 'Satori 봇', link: withBase('/ko/docs/contributing/services/satori') }, - { text: 'Telegram 봇', link: withBase('/ko/docs/contributing/services/telegram') }, - { text: 'Discord 봇', link: withBase('/ko/docs/contributing/services/discord') }, + { text: '개발자 도구', link: withBase('/ko/docs/contributing/desktop-developer-tools') }, ], }, { diff --git a/docs/content/ko/docs/contributing/design-guidelines/index.md b/docs/content/ko/docs/contributing/design-guidelines/index.md index d34a143d3..f2e7ac2c0 100644 --- a/docs/content/ko/docs/contributing/design-guidelines/index.md +++ b/docs/content/ko/docs/contributing/design-guidelines/index.md @@ -3,3 +3,11 @@ title: 디자인 가이드라인 description: Project AIRI에 디자인으로 기여하는 방법 --- +::: warning 작업 진행 중 +이 섹션은 아직 작성 중입니다. +::: + +자세한 내용은 사이드바의 페이지를 참고하세요: + +- [리소스](./resources) +- [도구](./tools) diff --git a/docs/content/ko/docs/contributing/desktop-developer-tools.md b/docs/content/ko/docs/contributing/desktop-developer-tools.md new file mode 100644 index 000000000..d901bbeb9 --- /dev/null +++ b/docs/content/ko/docs/contributing/desktop-developer-tools.md @@ -0,0 +1,142 @@ +--- +title: 데스크톱 개발자 도구 +description: 데스크톱 버전의 설정 → 시스템 → 개발자 아래에 있는 진단·검증 도구 사용법을 안내합니다. +--- + +데스크톱 버전의 **시스템 → 개발자** 페이지에는 개발, 문제 해결, 실험적 기능 검증을 위한 도구가 모여 있습니다. 이 도구들은 일상적인 채팅이나 캐릭터 상호작용을 개선하지 않습니다. 설치 후에 따로 설정할 필요도 없습니다. 문제를 재현하거나, 기능을 개발하거나, 메인테이너에게 전달할 진단 정보를 수집할 때만 사용하세요. + +이 페이지는 데스크톱 앱만 다룹니다. 웹 앱에도 개발 페이지가 있지만, 사용 가능한 기능과 런타임 환경이 다릅니다. + +::: warning 무엇을 테스트하는지 알고 사용하세요 +일부 도구는 화면을 캡처하거나, 마이크를 사용하거나, 전역 단축키를 등록하거나, 추가 창을 열거나, 가공되지 않은 네트워크·플러그인 데이터를 표시합니다. 테스트가 끝나면 캡처 스트림을 중지하고 사용하지 않는 창을 닫으세요. API Key, 대화 내용, 화면 내용, WebSocket 데이터가 포함된 스크린샷을 공개적으로 공유하지 마세요. +::: + +## 페이지 열기와 도구 선택 + +데스크톱 앱에서 **설정 → 시스템 → 개발자**를 여세요. 상단에는 빠른 작업과 렌더링 스위치가, 그 아래에는 개별 진단 페이지로 가는 링크가 표시됩니다. + +조사하려는 대상에 따라 도구를 선택하세요: + +| 확인하려는 것 | 시작할 도구 | +| --- | --- | +| 페이지 오류, 요소 스타일, 네트워크 요청 | Open Developer Tools | +| Three.js 또는 VRM 렌더링 진단 | Lag Visualizer | +| 깨진 전환 애니메이션 | 애니메이션 스위치 | +| 키보드, 마우스, 디스플레이, 전역 단축키 동작 | useMagicKeys, 마우스/디스플레이 도구, Global Shortcut | +| 채팅 컨텍스트, WebSocket, 실시간 전사 | Context Flow, WebSocket Inspector, Aliyun Real-time Transcriber | +| 플러그인 발견, 로드, 언로드 | Plugin Host Debug | +| 실패한 업데이트나 예상치 못한 업데이트 소스 | Updater | +| 화면 공유, 비전 입력, 캡처 권한 | Screen Capture 또는 Vision Capture | + +## 빠른 작업과 렌더링 진단 + +### Open Developer Tools + +**Open**을 선택하면 Electron에 내장된 브라우저 개발자 도구가 실행됩니다. 콘솔 오류, 네트워크 요청, DOM, 성능 기록을 확인할 때 사용하세요. 인터페이스 문제를 조사할 때 보통 가장 좋은 출발점입니다. + +재현 가능한 문제라면 콘솔을 비우고 동작을 한 번만 반복한 뒤 관련된 오류만 저장하세요. 이슈나 풀 리퀘스트에 진단 정보를 첨부하기 전에 민감한 정보를 제거하세요. + +### Markdown Stress + +이 도구는 대량의 Markdown을 별도 창에 렌더링하여 긴 문단, 코드 블록, 표, 스크롤, 테마 스타일을 테스트합니다. 문서나 대화를 수정하지 않습니다. + +### IO Tracer + +IO Tracer는 상호작용 턴의 타이밍 구간을 ASR, LLM, Streaming Control, TTS, Playback 단계별로 보여줍니다. 음성·채팅 파이프라인에서 지연이나 누락된 단계를 찾을 때 사용하세요. 트레이스 데이터에는 문맥 정보가 포함될 수 있으므로 필요할 때만 열고, 전체 트레이스를 공유하는 일은 피하세요. + +### Lag Visualizer + +Lag Visualizer는 Stage Three 런타임을 추적합니다. 창 수명 주기, Three.js 렌더링 횟수와 리소스, VRM 프레임 업데이트 타이밍, fade-on-hover 히트 테스트, VRM 로드·해제 타이밍, 렌더러/리소스 스냅숏을 보고합니다. Three.js나 VRM 렌더링 문제에 사용하세요. 일반적인 페이지 전환, 롱 태스크, FPS 프로파일러는 아닙니다. + +### 스테이지·페이지 전환 애니메이션 + +**Disable Stage Transitions**는 스테이지를 전환할 때 사용하는 전체 애니메이션을 제거합니다. 테스트 중에 스테이지 전환을 변수에서 제외하려면 켜세요. **Use Page Specific Transitions**는 각 페이지의 고유 전환을 제어하며, **Disable Stage Transitions**가 켜져 있는 동안에는 사용할 수 없습니다. + +화면 깜빡임, 언로드되지 않는 페이지, 느린 전환을 조사할 때는 각 상태를 따로 테스트하세요. 테스트가 끝나면 원래 설정으로 되돌리세요. + +## 키보드, 마우스, 디스플레이 + +### useMagicKeys + +이 페이지는 키보드 단축키와 보조 키 상태를 표시하여 앱이 키 이벤트를 올바르게 받는지 확인할 수 있게 합니다. 일반 사용자용 설정은 없습니다. AIRI의 Spotlight 단축키를 변경하려면 대신 **설정 → 시스템 → 창 단축키**를 사용하세요. + +### useElectronWindowMouse, Displays, Relative Mouse + +이 도구들은 서로 다른 좌표계에서 포인터 위치를 표시합니다: + +- **useElectronWindowMouse**는 모든 디스플레이가 이루는 데스크톱 좌표 공간에서 포인터를 표시합니다. +- **Displays**는 연결된 디스플레이와 포인터의 현재 위치를 표시합니다. 다중 디스플레이, 배율, 외장 모니터 문제에 사용하세요. +- **Relative Mouse**는 AIRI 창을 기준으로 한 포인터 위치를 표시합니다. 창 내부의 히트 영역과 드래그를 테스트할 때 사용하세요. + +창 따라가기, 클릭 오프셋, 다중 디스플레이 위치 문제를 보고할 때는 디스플레이 배치, 배율, 주 디스플레이, 재현 단계를 함께 적어 주세요. + +### Widgets Calling + +Widgets Calling은 오버레이 위젯을 생성하고 위젯에 전달되는 컴포넌트 props의 유효성을 검사합니다. 데스크톱 오버레이와 컴포넌트 호출 개발을 위한 도구이며, 일반적인 AIRI 사용에는 필요하지 않습니다. + +### Beat Sync Visualizer + +Beat Sync Visualizer는 비트에 동기화된 V-motion 목표, 경로, Y/Z 스칼라 변화를 그래프로 표시합니다. **Hit beat**나 **Hit V sequence**로 테스트 비트를 주입하고 그 결과 모션을 살펴보세요. 이 페이지에는 오디오 입력이나 자동 비트 감지 경로가 없습니다. + +## 채팅, 실시간 서비스, 네트워킹 + +### Context Flow + +Context Flow는 채팅 파이프라인으로 들어오는 컨텍스트 업데이트와 서비스로 전송되는 채팅 스트림 이벤트를 보여줍니다. 플러그인, VS Code 등 외부 소스의 컨텍스트가 AIRI에 도달하는지 확인할 때 유용합니다. + +먼저 도구를 열고 가장 작은 재현을 수행한 다음, 입력 컨텍스트와 출력 이벤트를 시간순으로 비교하세요. 컨텍스트에는 파일명, 대화 내용, 그 밖의 사적인 정보가 포함될 수 있으므로 로그를 공유하기 전에 민감한 부분을 지우세요. + +### WebSocket Inspector + +WebSocket Inspector는 가공되지 않은 WebSocket 트래픽을 표시합니다. 연결 실패, 누락된 이벤트, 예상과 다른 형식의 메시지를 조사할 때 사용하세요. 문제와 관련된 몇 개의 프레임만 공유하고, 토큰, 사용자 콘텐츠, 주소 정보는 제거하세요. + +### Aliyun Real-time Transcriber + +이 페이지는 시스템 기본 마이크의 오디오를 Alibaba Cloud NLS로 전송하고 도착하는 대로 전사 결과를 표시합니다. 실시간 음성 인식 경로, 즉 기본 마이크 입력, 자격 증명, 네트워크 연결, 전사 출력을 검증합니다. 페이지에 입력 장치 선택기가 없으므로, 열기 전에 운영 체제에서 원하는 기본 마이크를 선택하세요. 녹음이 허용된 곳에서만 녹음하세요. + +## 플러그인, 업데이트, 시스템 기능 + +### Plugin Host Debug + +Plugin Host Debug는 플러그인이 발견·활성화·로드되었는지 보여주고, 개발자가 로드와 언로드 수명 주기를 제어할 수 있게 합니다. 동작하지 않는 플러그인이 있다면 발견 여부, 활성화 상태, 로드 오류, 언로드 후 이벤트나 인터페이스 상태가 남아 있는지 확인하세요. + +무언가를 바꾸기 전에 현재 상태와 오류를 기록하세요. 최소 재현 없이 플러그인을 반복해서 로드·언로드하면 원래 문제를 진단하기가 더 어려워질 수 있습니다. + +### Updater + +Updater는 현재 버전, 플랫폼, 아키텍처, 업데이트 채널, 업데이트 소스, 로그 위치, 업데이트 상태를 표시합니다. 업데이트를 수동으로 확인·다운로드·설치할 수도 있습니다. 실패한 업데이트, 예상치 못한 업데이트 소스, 플랫폼별 설치 문제를 조사할 때 사용하세요. + +일상적인 업데이트에는 **About** 창을 사용하는 편이 좋습니다. 업데이트 소스를 이해하고 신뢰할 수 있는 경우가 아니라면 재정의하지 마세요. + +## 화면·비전 캡처 + +### Screen Capture + +Screen Capture는 애플리케이션 창이나 디스플레이 전체를 캡처하여 비디오 또는 오디오 스트림을 만들 수 있습니다. 주로 화면 공유와 캡처 동작을 테스트하는 페이지입니다. + +처음 사용할 때 운영 체제가 화면 녹화 권한을 요청할 수 있습니다. macOS에서 AIRI가 목록에 없다면 **System Settings → Privacy & Security → Screen & System Audio Recording**에서 활성화하거나 추가한 뒤 AIRI를 재시작하고 다시 시도하세요. Windows와 Linux의 권한 프롬프트는 운영 체제, 데스크톱 환경, Electron 버전에 따라 다릅니다. + +도구에서 **Applications**는 애플리케이션 창을, **Displays**는 화면 전체를 나열합니다. 현재 구현은 **Devices** 탭에 외부 소스를 제공하지 않으므로 이 탭은 비어 있습니다. 디스플레이를 연결·해제하거나, 창을 열거나, 권한을 변경한 뒤에는 **Refetch**를 사용하세요. 중지한 뒤에는 미리보기가 닫혔는지 확인하여 스트림이 더 이상 시스템 리소스나 권한을 사용하지 않게 하세요. + +### Vision Capture + +Vision Capture는 화면 프레임을 캡처하고 비전 파이프라인을 통해 전송되는 페이로드를 보여줍니다. 비전 입력이 올바르게 캡처되어 다운스트림 기능에 도달하는지 확인할 때 사용하세요. 진단용 워크플로이며, 비전 제공자를 설정한 뒤 계속 켜 두어야 하는 전역 스위치가 아닙니다. + +화면 비전을 테스트하려면: + +1. **설정 → 제공자 → 비전**에서 비전 제공자의 자격 증명을 설정하세요. +2. **설정 → 모듈 → 비전**을 열고 설정한 제공자와 이미지 처리가 가능한 모델을 선택하세요. +3. **설정 → 시스템 → 개발자 → Vision Capture**를 열고 운영 체제의 화면 녹화 권한을 허용하세요. +4. 창이나 디스플레이를 선택한 뒤 **Start ticker**를 선택하여 프레임 캡처와 분석을 시작하세요. +5. 인식 결과를 AIRI의 대화 컨텍스트에 추가하고 싶을 때만 **Publish to character**를 활성화하세요. +6. 끝나면 **Stop ticker**를 선택하세요. 페이지를 벗어나도 캡처 루프가 중지됩니다. + +페이지가 권한 프롬프트에서 멈춰 있다면 운영 체제에서 권한을 허용하고, AIRI를 완전히 종료했다가 재시작한 뒤 도구를 다시 여세요. 개인 데스크톱, 알림, 다른 애플리케이션의 콘텐츠가 보이는 캡처는 절대 공개하지 마세요. + +## 전역 단축키 + +### Global Shortcut + +Global Shortcut은 시스템 전역 단축키 이벤트를 등록·해제·관찰합니다. **설정 → 시스템 → 창 단축키**에서 일상용으로 설정하는 Spotlight 단축키와는 다르며, 이 페이지는 개발과 검증을 위해 존재합니다. + +운영 체제나 다른 애플리케이션과 충돌하지 않는 키 조합을 선택하세요. 등록에 실패하면 해당 조합이 이미 사용 중인지 확인하세요. 테스트가 끝나면 단축키가 계속 키 입력을 가로채지 않도록 등록을 해제하세요. diff --git a/docs/content/ko/docs/contributing/docs.md b/docs/content/ko/docs/contributing/docs.md index 7adb05dfb..336ce20ad 100644 --- a/docs/content/ko/docs/contributing/docs.md +++ b/docs/content/ko/docs/contributing/docs.md @@ -1,20 +1,27 @@ --- -title: 문서 사이트 -description: Project AIRI에 기여하기 +title: 문서 사이트 개발 +description: VitePress 문서를 로컬에서 작성하고, 미리 보고, 검증하기 --- -### 문서 사이트 +문서 사이트는 `docs`에 있으며, 콘텐츠는 로케일별로 `docs/content/` 아래에 정리되어 있습니다. 저장소 루트에서 다음을 실행하세요: ```shell pnpm dev:docs ``` -::: tip +문서 사이트만 검증하려면 다음을 실행하세요: -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 +```shell +pnpm -F @proj-airi/docs typecheck +pnpm -F @proj-airi/docs build +``` + +영어 페이지를 추가할 때는 `docs/.vitepress/config.ts`의 `en` 사이드바에도 추가하세요. 그렇지 않으면 페이지가 URL로는 접근할 수 있지만 내비게이션에는 나타나지 않습니다. + +::: tip +[@antfu/ni](https://github.com/antfu-collective/ni)를 사용한다면 다음을 실행하세요: ```shell nr dev:docs ``` - ::: diff --git a/docs/content/ko/docs/contributing/index.md b/docs/content/ko/docs/contributing/index.md index b5e8a455e..ff7e94f36 100644 --- a/docs/content/ko/docs/contributing/index.md +++ b/docs/content/ko/docs/contributing/index.md @@ -1,50 +1,37 @@ --- -title: 기여하기 -description: Project AIRI에 기여하기 +title: 개발 환경 설정과 첫 기여 +description: Project AIRI를 로컬에서 실행하고 첫 Pull Request 제출하기 --- -안녕하세요! 이 프로젝트에 기여하는 데 관심을 가져 주셔서 감사합니다. 이 가이드가 첫걸음을 도와드릴 거예요. +안녕하세요! Project AIRI에 기여하는 데 관심을 가져 주셔서 감사합니다. 이 가이드는 로컬 개발 환경을 설정하고, 브랜치를 만들고, 첫 Pull Request를 제출하는 방법을 설명합니다. + +::: info 적용 범위 +이 섹션은 소스 코드, 문서, 디자인 리소스를 변경하려는 컨트리뷰터를 위한 내용입니다. AIRI를 사용하기만 하려면 사용자 매뉴얼부터 시작하세요. 앱에 내장된 디버깅 도구는 [개발자 도구](./desktop-developer-tools)를 참고하세요. +::: ## 사전 준비물 - [Git](https://git-scm.com/downloads) -- [Node.js 23+](https://nodejs.org/en/download/) -- [corepack](https://github.com/nodejs/corepack) -- [pnpm](https://pnpm.io/installation) +- [mise](https://mise.jdx.dev/installing-mise.html) 또는 `.tool-versions`를 읽는 다른 버전 관리자 +- [Corepack](https://github.com/nodejs/corepack) — 최신 Node.js 릴리스에 포함되어 있습니다 + +이 저장소는 [`.tool-versions`](https://github.com/moeru-ai/airi/blob/main/.tool-versions)에 Node.js 버전을 고정해 둡니다(현재 24.13.0). 시스템 패키지 매니저가 제공하는 버전에 의존하지 말고, 클론한 뒤 고정된 버전을 설치하세요.
Windows 설정 -0. [Visual Studio](https://visualstudio.microsoft.com/downloads/) 를 내려받고 다음 안내를 따르세요: https://rust-lang.github.io/rustup/installation/windows-msvc.html#walkthrough-installing-visual-studio-2022 - - > Visual Studio를 설치할 때 Windows SDK와 C++ 빌드 도구를 반드시 함께 설치하세요. - -1. PowerShell을 엽니다 -2. [`scoop`](https://scoop.sh/) 을 설치합니다 +1. PowerShell을 여세요. +2. [`scoop`](https://scoop.sh/)을 설치하세요. ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression ``` -3. `scoop`으로 `git`, Node.js, `rustup`, `msvc`를 설치합니다 +3. Scoop으로 Git과 mise를 설치하세요. ```powershell - scoop install git nodejs rustup - - # Rust 의존성용 - # crates나 apps/tamagotchi를 개발하지 않는다면 필요 없습니다 - scoop install main/rust-msvc - # Rust & Windows 전용 - rustup toolchain install stable-x86_64-pc-windows-msvc - rustup default stable-x86_64-pc-windows-msvc - ``` - -4. `corepack`으로 `pnpm`을 설치합니다 - - ```powershell - corepack enable - corepack prepare pnpm@latest --activate + scoop install git mise ```
@@ -52,18 +39,11 @@ description: Project AIRI에 기여하기
macOS 설정 -0. 터미널(또는 iTerm2, Ghostty, Kitty 등)을 엽니다 -1. `brew`로 `git`과 `node`를 설치합니다 +1. 터미널, iTerm2, Ghostty, Kitty 등 원하는 터미널을 여세요. +2. Homebrew로 Git과 mise를 설치하세요. ```shell - brew install git node - ``` - -2. `corepack`으로 `pnpm`을 설치합니다 - - ```shell - corepack enable - corepack prepare pnpm@latest --activate + brew install git mise ```
@@ -71,55 +51,38 @@ description: Project AIRI에 기여하기
Linux 설정 -0. 터미널을 엽니다 -1. [nodesource/distributions: NodeSource Node.js Binary Distributions](https://github.com/nodesource/distributions?tab=readme-ov-file#table-of-contents)를 따라 `node`를 설치합니다 -2. [Git](https://git-scm.com/downloads/linux) 안내를 따라 `git`을 설치합니다 -3. `corepack`으로 `pnpm`을 설치합니다 - - ```shell - corepack enable - corepack prepare pnpm@latest --activate - ``` -4. 데스크톱 버전 개발을 돕고 싶다면 다음 의존성이 필요합니다: - ```shell - sudo apt install \ - libssl-dev \ - libglib2.0-dev \ - libgtk-3-dev \ - libjavascriptcoregtk-4.1-dev \ - libwebkit2gtk-4.1-dev - ``` +1. 터미널을 여세요. +2. [Linux용 Git 설치 안내](https://git-scm.com/downloads/linux)를 따르세요. +3. [배포판에 맞는 패키지 또는 설치 방법](https://mise.jdx.dev/installing-mise.html)으로 mise를 설치하세요.
-## 이전에 이미 이 프로젝트에 기여한 적이 있다면 - -::: warning - -아직 이 저장소를 클론하지 않았다면 이 섹션은 건너뛰세요. +## 이전에 기여한 적이 있다면 +::: tip +아직 저장소를 클론하지 않았다면 이 섹션은 건너뛰세요. ::: -로컬 저장소가 업스트림 저장소와 최신 상태인지 확인하세요: +업스트림 변경 사항을 가져와 로컬 `main` 브랜치를 리베이스하세요: ```shell git fetch --all -git checkout main +git switch main git pull upstream main --rebase ``` -작업 브랜치가 있다면, 그 브랜치를 업스트림 저장소 기준으로 최신화하려면: +이미 작업 브랜치가 있다면 `main` 기준으로 최신화하세요: ```shell -git checkout +git switch git rebase main ``` ## 이 프로젝트를 포크하기 -[moeru-ai/airi](https://github.com/moeru-ai/airi) 페이지 오른쪽 위의 **Fork** 버튼을 클릭하세요. +[moeru-ai/airi](https://github.com/moeru-ai/airi) 저장소 페이지 오른쪽 위의 **Fork**를 클릭해 자신의 계정 아래에 복사본을 만드세요. -## 클론하기 +## 포크한 저장소 클론하기 ```shell git clone https://github.com//airi.git @@ -129,94 +92,89 @@ cd airi ## 작업 브랜치 만들기 ```shell -git checkout -b +git switch -c ``` ## 의존성 설치 -```shell -corepack enable -pnpm install +저장소 루트에서 `.tool-versions`에 기록된 Node.js 버전을 설치하고, 버전을 확인하고, Corepack을 활성화한 뒤 의존성을 설치하세요: -# Rust 의존성용 -# crates 나 apps/tamagotchi 를 개발하지 않는다면 필요 없습니다 -cargo fetch +```shell +mise install +mise exec -- node --version +mise exec -- corepack enable +mise exec -- pnpm install +``` + +출력된 Node.js 버전이 `.tool-versions`와 일치해야 합니다. 이후 예시는 [셸에서 mise가 활성화되어 있다고](https://mise.jdx.dev/dev-tools/shims.html) 가정합니다. 그렇지 않다면 패키지 매니저 명령을 `mise exec --`를 통해 실행하세요(예: `mise exec -- pnpm typecheck`). + +::: tip +패키지 매니저 명령을 간단하게 쓰고 싶다면 [@antfu/ni](https://github.com/antfu-collective/ni)를 선택적으로 설치할 수 있습니다: + +```shell +mise exec -- npm install --global @antfu/ni +``` + +설치하고 나면: + +- `pnpm install`, `npm install`, `yarn install` 대신 `ni`를 사용하세요. +- `pnpm run`, `npm run`, `yarn run` 대신 `nr`을 사용하세요. + +`ni`는 저장소가 사용하는 패키지 매니저를 감지합니다. +::: + +## 변경 사항 커밋하기 + +### 커밋하기 전에 검증하기 + +코드가 lint와 타입 검사를 통과하는지 확인하세요: + +```shell +pnpm lint +pnpm typecheck ``` ::: tip - -스크립트를 더 간단히 쓰기 위해 [@antfu/ni](https://github.com/antfu-collective/ni) 설치를 권장합니다. - -```shell -corepack enable -npm i -g @antfu/ni -``` - -설치하고 나면 - -- `pnpm install`, `npm install`, `yarn install` 대신 `ni`를 쓸 수 있습니다. -- `pnpm run`, `npm run`, `yarn run` 대신 `nr`을 쓸 수 있습니다. - -패키지 매니저가 무엇인지 신경 쓸 필요가 없습니다. `ni`가 알맞은 것을 골라 줍니다. -::: - -## 개발하고 싶은 애플리케이션 고르기 - -## 커밋 - -### 커밋하기 전에 - -::: warning - -lint(정적 검사기)와 TypeScript 컴파일러를 모두 통과했는지 확인해 주세요: - -```shell -pnpm lint && pnpm typecheck -``` - -::: - -::: tip - -[@antfu/ni](https://github.com/antfu-collective/ni)를 설치했다면 `nr`로 명령을 실행할 수 있습니다: +[@antfu/ni](https://github.com/antfu-collective/ni)를 설치했다면 다음을 실행하세요: ```shell nr lint && nr typecheck ``` - ::: -### 커밋 +### 커밋 만들기 ```shell -git add . +git add git commit -m "" ``` -### 포크한 저장소로 푸시 +### 브랜치 푸시하기 ```shell -git push origin -u +git push -u origin ``` -포크한 저장소에서 해당 브랜치를 확인할 수 있습니다. +이제 GitHub에서 해당 브랜치를 확인할 수 있습니다. ::: tip - -이 프로젝트에 처음 기여하는 것이라면 업스트림 저장소도 추가해야 합니다: +처음 기여하는 것이라면 Project AIRI 저장소를 `upstream` 원격으로 추가하세요: ```shell git remote add upstream https://github.com/moeru-ai/airi.git ``` - ::: ## Pull Request 만들기 -[moeru-ai/airi](https://github.com/moeru-ai/airi) 페이지로 이동해 **Pull requests** 탭을 클릭하고, **New pull request** 버튼을 누른 뒤 **Compare across forks** 링크를 클릭해 포크한 저장소를 선택하세요. +[moeru-ai/airi](https://github.com/moeru-ai/airi) 저장소 페이지를 여세요: -변경 사항을 검토한 뒤 **Create pull request** 버튼을 클릭합니다. +1. **Pull requests**를 클릭하세요. +2. **New pull request**를 클릭하세요. +3. **Compare across forks**를 클릭하세요. +4. 포크한 저장소와 작업 브랜치를 선택하세요. +5. 변경 사항을 검토한 뒤 **Create pull request**를 클릭하세요. -## 우와! 해내셨네요! +## 해내셨습니다! -축하합니다! 이 프로젝트에 첫 기여를 하셨습니다. 이제 메인테이너가 여러분의 Pull Request를 리뷰할 때까지 기다리시면 됩니다. +첫 기여를 제출하신 것을 축하합니다. 이제 프로젝트 메인테이너가 여러분의 Pull Request를 리뷰할 수 있습니다. diff --git a/docs/content/ko/docs/contributing/services/discord.md b/docs/content/ko/docs/contributing/services/discord.md deleted file mode 100644 index 022958995..000000000 --- a/docs/content/ko/docs/contributing/services/discord.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Discord 봇 -description: Project AIRI에 기여하기 ---- - -### Discord 봇 연동 - -```shell -cd integrations/discord-bot -``` - -`.env` 설정하기 - -```shell -cp .env .env.local -``` - -`.env.local`에서 인증 정보를 수정하세요. - -봇 실행하기 - -```shell -pnpm -F @proj-airi/discord-bot start -``` - -::: tip - -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 - -```shell -nr -F @proj-airi/discord-bot dev -``` - -::: diff --git a/docs/content/ko/docs/contributing/services/minecraft.md b/docs/content/ko/docs/contributing/services/minecraft.md deleted file mode 100644 index 578fa8c4b..000000000 --- a/docs/content/ko/docs/contributing/services/minecraft.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Minecraft -description: Project AIRI에 기여하기 ---- - -### Minecraft 에이전트 - -```shell -cd integrations/minecraft -``` - -Minecraft 클라이언트를 실행하고 원하는 포트로 월드를 개방한 뒤, 그 포트 번호를 `.env.local`에 입력하세요. - -`.env` 설정하기 - -```shell -cp .env .env.local -``` - -`.env.local`에서 인증 정보를 수정하세요. - -봇 실행하기 - -```shell -pnpm -F @proj-airi/minecraft-bot start -``` - -::: tip - -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 - -```shell -nr -F @proj-airi/minecraft-bot dev -``` - -::: diff --git a/docs/content/ko/docs/contributing/services/satori.md b/docs/content/ko/docs/contributing/services/satori.md deleted file mode 100644 index 6032dcefd..000000000 --- a/docs/content/ko/docs/contributing/services/satori.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Satori 봇 -description: Project AIRI에 기여하기 ---- - -### Satori 봇 - -```shell -cd integrations/satori-bot -``` - -`.env` 파일 설정하기: - -```shell -cp .env .env.local -``` - -`.env.local`에서 각종 키와 설정 정보를 수정하세요. - -봇 시작하기: - -```shell -pnpm -F @proj-airi/satori-bot dev -``` - -::: tip - -[@antfu/ni](https://github.com/antfu-collective/ni)를 쓰신다면 이렇게 할 수 있습니다: - -```shell -nr -F @proj-airi/satori-bot dev -``` - -::: diff --git a/docs/content/ko/docs/contributing/services/telegram.md b/docs/content/ko/docs/contributing/services/telegram.md deleted file mode 100644 index 03a87ea6c..000000000 --- a/docs/content/ko/docs/contributing/services/telegram.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Telegram 봇 -description: Project AIRI에 기여하기 ---- - -### Telegram 봇 연동 - -Postgres 데이터베이스가 필요합니다. - -```shell -cd integrations/telegram-bot -docker compose up -d -``` - -`.env` 설정하기 - -```shell -cp .env .env.local -``` - -`.env.local`에서 인증 정보를 수정하세요. - -데이터베이스 마이그레이션 - -```shell -pnpm -F @proj-airi/telegram-bot db:generate -pnpm -F @proj-airi/telegram-bot db:push -``` - -봇 실행하기 - -```shell -pnpm -F @proj-airi/telegram-bot start -``` - -::: tip - -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 - -```shell -nr -F @proj-airi/telegram-bot dev -``` - -::: diff --git a/docs/content/ko/docs/contributing/tamagotchi.md b/docs/content/ko/docs/contributing/tamagotchi.md index 4c4788c4e..4bf9d253e 100644 --- a/docs/content/ko/docs/contributing/tamagotchi.md +++ b/docs/content/ko/docs/contributing/tamagotchi.md @@ -1,20 +1,29 @@ --- -title: 데스크톱 -description: Project AIRI에 기여하기 +title: 데스크톱 개발 +description: Electron 데스크톱 앱 실행, 검사, 빌드 --- -### Stage Tamagotchi (데스크톱 버전) +데스크톱 앱은 `apps/stage-tamagotchi`에 있습니다. 저장소 루트에서 다음을 실행하세요: ```shell pnpm dev:tamagotchi ``` -::: tip +이 명령은 Electron 개발 환경을 시작합니다. 데스크톱 페이지를 변경하기 전에, 관련 공유 컴포넌트나 상태가 이미 `packages/stage-ui`에 있는지 확인하세요. 웹 앱과 데스크톱 앱이 함께 사용하는 로직은 보통 공유 패키지에 두어야 합니다. -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 +## 검증 + +```shell +pnpm -F @proj-airi/stage-tamagotchi typecheck +pnpm -F @proj-airi/stage-tamagotchi build +``` + +**System → Developer** 메뉴와 각 디버깅 도구의 용도는 [개발자 도구](./desktop-developer-tools)를 참고하세요. + +::: tip +[@antfu/ni](https://github.com/antfu-collective/ni)를 사용한다면 다음을 실행하세요: ```shell nr dev:tamagotchi ``` - ::: diff --git a/docs/content/ko/docs/contributing/webui.md b/docs/content/ko/docs/contributing/webui.md index 98fa70596..02ebf50cb 100644 --- a/docs/content/ko/docs/contributing/webui.md +++ b/docs/content/ko/docs/contributing/webui.md @@ -1,20 +1,31 @@ --- -title: 웹 UI -description: Project AIRI에 기여하기 +title: 웹 앱 개발 +description: AIRI 웹 앱 실행, 검사, 빌드 --- -### Stage Web ([airi.moeru.ai](https://airi.moeru.ai) 브라우저 버전) +웹 앱은 `apps/stage-web`에 있으며 [airi.moeru.ai](https://airi.moeru.ai)를 구동합니다. 저장소 루트에서 다음을 실행하세요: ```shell pnpm dev ``` -::: tip +더 명시적인 명령을 사용할 수도 있습니다: -[@antfu/ni](https://github.com/antfu-collective/ni) 사용자라면 이렇게 쓸 수 있습니다 +```shell +pnpm dev:web +``` + +## 검증 + +```shell +pnpm -F @proj-airi/stage-web typecheck +pnpm -F @proj-airi/stage-web build +``` + +::: tip +[@antfu/ni](https://github.com/antfu-collective/ni)를 사용한다면 다음을 실행하세요: ```shell nr dev ``` - ::: diff --git a/docs/content/ko/docs/integrations/discord.md b/docs/content/ko/docs/integrations/discord.md new file mode 100644 index 000000000..b5a1f5e28 --- /dev/null +++ b/docs/content/ko/docs/integrations/discord.md @@ -0,0 +1,64 @@ +--- +title: Discord 봇 +description: Discord 애플리케이션으로 AIRI를 음성·메시징 봇으로 실행하기 +--- + +Discord 봇은 Discord 서버의 텍스트 채널과 음성 채널에 연결됩니다. 텍스트 응답은 AIRI에서 선택한 채팅 제공자와 모델을 사용합니다. + +## 사전 준비 사항 + +- 저장소 루트에서 **pnpm i**로 의존성을 설치하세요. +- [Discord Developer Portal](https://discord.com/developers/home)에서 애플리케이션과 봇을 만드세요. +- 봇 설정에서 **Message Content Intent**를 활성화하세요. +- AIRI에서 동작하는 채팅 제공자와 모델을 설정하세요. + +::: warning 자격 증명 보안 +Bot Token과 AIRI Auth Token은 AIRI의 로컬 설정 또는 봇 서비스의 로컬 **.env.local** 파일에만 보관하세요. 이 자격 증명을 커밋하거나, 스크린샷에 포함하거나, 공유하지 마세요. +::: + +## 봇 서비스 설정 + +```bash +cp integrations/discord-bot/.env integrations/discord-bot/.env.local +``` + +데스크톱 버전에서 **설정 → 연결**을 여세요. **Auth Token**을 표시하고 복사하세요. 그런 다음 **integrations/discord-bot/.env.local**에 아래 값을 추가하세요: + +```env +AIRI_URL=ws://localhost:6121/ws +AIRI_TOKEN= +``` + +`DISCORD_TOKEN`은 시작 시점에 사용하는 선택적 대체값입니다. 비워 두고 서비스가 연결된 뒤 AIRI에서 Bot Token을 보낼 수 있습니다. 서비스는 `DISCORD_BOT_CLIENT_ID`, `OPENAI_MODEL`, `OPENAI_API_*`, `ELEVENLABS_*`를 사용하지 않습니다. Discord 텍스트 응답은 AIRI의 활성 채팅 설정을 사용합니다. + +Discord 음성 입력을 사용하려면 `OPENAI_STT_API_BASE_URL`, `OPENAI_STT_API_KEY`, `OPENAI_STT_MODEL`로 OpenAI 호환 전사 엔드포인트를 설정하세요. 텍스트 채널에는 이 값이 필요하지 않지만, 이 값 없이는 음성 전사가 완료되지 않습니다. + +## 서비스 시작 + +```bash +pnpm -F @proj-airi/discord-bot start +``` + +## AIRI에서 Discord 설정하기 + +1. **설정 → 모듈 → Discord**를 여세요. +2. **Bot Token**에 봇 토큰을 붙여넣으세요. +3. **Enable Discord Integration**을 켜세요. +4. **저장**을 클릭하세요. + +인증된 봇 서비스는 AIRI의 설정 채널을 통해 활성화 상태와 토큰을 전달받습니다. 서비스가 실행 중이 아니거나 서비스의 AIRI Auth Token이 없거나 잘못된 경우, 이 필드를 저장하는 것만으로는 Discord 봇이 시작되지 않습니다. + +## Discord에서 봇 설치 및 사용 + +1. Discord Developer Portal에서 `bot` 스코프로 **Guild Install**을 구성하고 봇을 서버에 설치하세요. `bot` 스코프는 기본적으로 `applications.commands`를 포함합니다. 사용하는 기능에 필요한 권한만 부여하세요: + - 텍스트 응답: **View Channels**와 **Send Messages**. + - 음성 입력: **View Channels**와 **Connect**. + - 음성 재생: **Speak**. +2. 텍스트 채팅은 봇에게 다이렉트 메시지를 보내거나 서버 채널에서 봇을 멘션하세요. 봇이 모든 서버 메시지에 응답하지는 않습니다. +3. 음성 입력은 음성 채널에 참여한 뒤 `/summon`을 실행하세요. 서비스는 봇이 로그인한 후 `/ping`과 `/summon`을 등록합니다. + +봇이 일부 채널에서만 동작하고 다른 채널에서는 동작하지 않으면, 채널 수준의 권한 재정의를 확인하세요. + +## 보안 참고 사항 + +봇의 접근 권한을 필요한 채널과 기능으로만 제한하세요. Bot Token을 분실했거나 유출됐다면 Discord Developer Portal에서 즉시 재설정하세요. diff --git a/docs/content/ko/docs/integrations/factorio.md b/docs/content/ko/docs/integrations/factorio.md new file mode 100644 index 000000000..92950f699 --- /dev/null +++ b/docs/content/ko/docs/integrations/factorio.md @@ -0,0 +1,30 @@ +--- +title: Factorio +description: 신뢰할 수 있는 Factorio 서버에 AIRI 연결하기 +--- + +Factorio 통합은 AIRI를 외부 게임 서비스에 연결합니다. 데스크톱 버전은 서버 주소, 포트, 플레이어 이름 설정을 제공합니다. 접속 가능한 Factorio 서버와 호환되는 서버 측 통합은 직접 준비해야 합니다. + +## 사전 준비 사항 + +- 접속 가능한 Factorio 서버. +- 계정과 서버 측 통합이 연결할 수 있도록 서버 관리자에게 받은 권한. +- 서버 주소, 포트, 게임 내 사용자 이름. + +::: warning 신뢰할 수 있는 서버에만 연결하세요 +이 통합은 게임 서버와 컨텍스트 및 행동 요청을 주고받습니다. 신뢰할 수 없는 공개 서버에서 사용하지 말고, 서버 주소, 토큰, 계정 정보를 공개 채팅, 스크린샷, 이슈에 노출하지 마세요. +::: + +## AIRI에서 설정하기 + +1. **설정 → 모듈 → Factorio**를 여세요. +2. **Factorio 통합**을 활성화하세요. +3. 서버 주소, 포트, 게임 내 사용자 이름을 입력하세요. 기본 포트는 `34197`입니다. +4. **저장**을 클릭하세요. **설정됨** 상태는 세 필드에 모두 값이 있다는 뜻일 뿐이며, 실제 연결은 서버와 서버 측 통합에 따라 달라집니다. + +## 문제 해결 + +- AIRI를 실행하는 기기가 서버 주소와 포트에 접근할 수 있는지 확인하세요. +- 방화벽, VPN, 서버 허용 목록이 연결을 차단하지 않는지 확인하세요. +- 사용자 이름이 서버의 플레이어 이름과 일치하는지 확인하세요. +- 설정을 저장했는데도 AIRI가 상호작용하지 못하면 서버 측 통합 로그를 확인하세요. 데스크톱 버전에는 바로 배포할 수 있는 Factorio 봇 서비스가 포함되어 있지 않습니다. diff --git a/docs/content/ko/docs/integrations/minecraft.md b/docs/content/ko/docs/integrations/minecraft.md new file mode 100644 index 000000000..e77e71853 --- /dev/null +++ b/docs/content/ko/docs/integrations/minecraft.md @@ -0,0 +1,46 @@ +--- +title: Minecraft 에이전트 +description: 신뢰할 수 있는 Minecraft 서버에서 AIRI의 로컬 게임 에이전트 실행하기 +--- + +Minecraft 통합은 Mineflayer를 사용해 AIRI를 Minecraft 서버에 연결합니다. 이를 통해 에이전트가 컨텍스트를 받고, 게임 내 행동을 수행하고, 상태를 보고할 수 있습니다. 이 통합은 로컬 개발과 유지보수 용도로 만들어졌습니다. 현재 구현은 Fabric 런타임으로 이전할 계획이므로, 이를 기반으로 새로운 장기 기능을 만들지 마세요. + +## 사전 준비 사항 + +- 저장소 루트에서 **pnpm i**로 의존성을 설치하세요. +- 접속 가능한 로컬 또는 신뢰할 수 있는 Minecraft 서버를 준비하세요. 연결 주소와 포트는 환경 설정에서 가져옵니다. +- AIRI에서 동작하는 채팅 제공자와 모델을 설정하고, Minecraft 에이전트가 사용할 OpenAI 호환 모델 설정을 준비하세요. + +::: warning 자격 증명 보안 +API Key, 서비스 주소, Minecraft 서버 자격 증명은 로컬 **.env.local** 파일에만 보관하세요. 이 값을 커밋하거나, 스크린샷에 포함하거나, 공유하지 마세요. +::: + +## 설정하기 + +```bash +cp integrations/minecraft/.env integrations/minecraft/.env.local +``` + +**integrations/minecraft/.env.local**을 편집해 필요한 Minecraft 서버, AIRI, 모델 서비스 설정을 입력하세요. + +데스크톱 버전에서 **설정 → 연결**을 여세요. **Auth Token**을 표시한 뒤 복사하세요. 그런 다음 아래 AIRI 채널 설정을 추가하세요: + +```env +AIRI_WS_BASEURL=ws://localhost:6121/ws +AIRI_CLIENT_NAME=minecraft-bot +AIRI_WS_TOKEN= +``` + +또한 서버와 모델 서비스에 필요한 `BOT_HOSTNAME`, `BOT_PORT` 값과 `OPENAI_API_BASEURL`, `OPENAI_API_KEY`, `OPENAI_MODEL`, `OPENAI_REASONING_MODEL` 값을 설정하세요. 기본값은 로컬 환경과 일치할 때만 그대로 두세요. + +## 시작하기 + +```bash +pnpm -F @proj-airi/minecraft-bot dev +``` + +시작한 후 터미널 출력에서 AIRI 인증이 성공했는지, 에이전트가 Minecraft 서버에 연결되었는지 확인하세요. `AIRI_WS_TOKEN`이 없거나 잘못되면 모듈이 AIRI에 등록되지 않습니다. + +## 보안 및 제한 사항 + +신뢰할 수 없는 공개 서버에 에이전트를 연결하지 마세요. 에이전트는 로컬 Minecraft 세션과 네트워크 연결을 제어합니다. 행동 계획이 격리된 환경에서 실행되더라도, 악의적인 서버는 예기치 않은 동작을 일으킬 수 있습니다. diff --git a/docs/content/ko/docs/integrations/satori.md b/docs/content/ko/docs/integrations/satori.md new file mode 100644 index 000000000..2dc111f0b --- /dev/null +++ b/docs/content/ko/docs/integrations/satori.md @@ -0,0 +1,34 @@ +--- +title: Satori 봇 +description: Koishi와 Satori 프로토콜을 통해 AIRI를 여러 메시징 플랫폼에 연결하기 +--- + +Satori 봇은 Koishi의 Satori 서비스를 통해 QQ, Telegram, Discord, Lark 같은 메시징 플랫폼에 연결됩니다. 현재의 독립 실행형 코어는 과도기적 구현으로 실험과 유지보수에 적합하며, 안정적인 AIRI Core 통합으로 간주해서는 안 됩니다. + +## 사전 준비 사항 + +- 저장소 루트에서 **pnpm i**로 의존성을 설치하세요. +- **server-satori** 플러그인이 활성화된 Koishi 인스턴스를 실행하세요. +- OpenAI 호환 API를 제공하는 모델 서비스를 준비하세요. + +::: warning 자격 증명 보안 +Satori 토큰, 메시징 플랫폼 자격 증명, 모델 API Key는 로컬 **.env.local** 파일에만 보관하세요. 이 값을 커밋하거나, 스크린샷에 포함하거나, 공유하지 마세요. +::: + +## 설정 + +```bash +cp integrations/satori-bot/.env integrations/satori-bot/.env.local +``` + +**integrations/satori-bot/.env.local**을 편집해 **SATORI_WS_URL**, **SATORI_API_BASE_URL**, 선택 사항인 **SATORI_TOKEN**, 그리고 LLM 주소·키·모델을 입력하세요. + +## 시작 + +```bash +pnpm -F @proj-airi/satori-bot dev +``` + +## 참고 사항 + +메시징 플랫폼 주소, 토큰, 모델 자격 증명은 민감한 정보입니다. **.env.local**을 커밋하거나 그 내용을 누구에게도 보내지 마세요. diff --git a/docs/content/ko/docs/integrations/telegram.md b/docs/content/ko/docs/integrations/telegram.md new file mode 100644 index 000000000..81fc594f2 --- /dev/null +++ b/docs/content/ko/docs/integrations/telegram.md @@ -0,0 +1,52 @@ +--- +title: Telegram 봇 +description: PostgreSQL과 모델 서비스를 사용해 AIRI를 Telegram 봇으로 실행하기 +--- + +Telegram 봇을 실행하려면 Telegram Bot Token, PostgreSQL 벡터 데이터베이스, 모델 서비스가 필요합니다. 저장소의 Compose 서비스는 pgvector 호환 모드로 pgvecto.rs 0.4.0이 포함된 PostgreSQL을 실행합니다. 봇은 소스에서 직접 실행하도록 만들어졌습니다. + +## 사전 준비 사항 + +- 저장소 루트에서 **pnpm i**로 의존성을 설치하세요. +- [@BotFather](https://t.me/BotFather)로 Telegram 봇을 만들고 토큰을 발급받으세요. +- 저장소의 PostgreSQL 벡터 서비스를 시작할 수 있도록 Docker를 준비하세요. +- 채팅 모델과 임베딩 모델 서비스를 준비하세요. + +::: warning 자격 증명 보안 +Telegram Bot Token, 데이터베이스 연결 정보, 모델 API Key는 로컬 **.env.local** 파일에만 보관하세요. 이 값을 커밋하거나, 스크린샷에 포함하거나, 공유하지 마세요. +::: + +## 설정하기 + +```bash +cp integrations/telegram-bot/.env integrations/telegram-bot/.env.local +``` + +**integrations/telegram-bot/.env.local**을 편집해 **TELEGRAM_BOT_TOKEN**, 데이터베이스 연결 정보, 채팅 모델과 임베딩 모델 설정을 입력하세요. 임베딩 서비스의 출력 크기는 `EMBEDDING_DIMENSION`과 일치해야 하며, 지원되는 값은 `768`, `1024`, `1536`입니다. + +## 데이터베이스 초기화 + +```bash +cd integrations/telegram-bot +docker compose up -d --wait pgvector +cd ../.. +pnpm -F @proj-airi/telegram-bot db:push +``` + +저장소의 Compose 파일은 PostgreSQL을 호스트 포트 `5433`으로 노출합니다. 이 서비스를 사용할 때는 다음과 같이 설정하세요: + +```env +DATABASE_URL=postgres://postgres:123456@localhost:5433/postgres +``` + +`pgvector`만 시작하면 선택 사항인 Grafana, Tempo, Prometheus, OpenTelemetry 서비스는 실행되지 않습니다. + +## 시작하기 + +```bash +pnpm -F @proj-airi/telegram-bot start +``` + +## 참고 사항 + +데이터베이스, Telegram 토큰, 모델 자격 증명은 민감한 정보입니다. **.env.local**을 커밋하지 마세요. 첫 배포 전에 데이터베이스 백업과 접근 제어 방안도 확인하세요. diff --git a/docs/content/ko/docs/integrations/x.md b/docs/content/ko/docs/integrations/x.md new file mode 100644 index 000000000..e2928527c --- /dev/null +++ b/docs/content/ko/docs/integrations/x.md @@ -0,0 +1,26 @@ +--- +title: X / Twitter (사용 불가) +description: AIRI X / Twitter 통합의 현재 구현 상태 +--- + +X / Twitter 통합은 AIRI 0.11.3에서 동작하지 않습니다. **설정 → 모듈 → X / Twitter**에 자격 증명 필드가 표시되고 **configured** 상태가 나타날 수 있지만, 현재 앱은 그 설정을 별도의 X 서비스에 전달할 수 없습니다. + +::: warning X 자격 증명을 입력하지 마세요 + +현재 버전에서는 API Key, API Secret, Access Token, Access Token Secret을 입력하지 마세요. **configured** 상태는 네 필드에 모두 값이 들어 있다는 뜻일 뿐, 서비스 연결이 동작한다는 것을 확인해 주지 않습니다. +::: + +## 현재 제한 사항 + +프로토콜 불일치를 조사하기 전에, 컨트리뷰터는 `ENABLE_AIRI=true`, `AIRI_URL=ws://localhost:6121/ws`, 그리고 **설정 → 연결 → Auth Token**과 일치하는 `AIRI_TOKEN`으로 외부 프로세스를 시작해야 합니다. 저장소에 커밋된 기본값은 AIRI 어댑터를 비활성화하고, 주소를 `http://localhost:3000`으로 지정하며, 토큰을 제공하지 않습니다. 이 설정을 바로잡으면 서비스가 연결될 수 있을 뿐, 아래에 설명한 호환되지 않는 설정 전달 흐름이 고쳐지는 것은 아닙니다. + +AIRI 모듈은 모듈 이름 `twitter`로 설정을 발행하지만, 외부 서비스는 `x`를 기대합니다. 채널 프로토콜도 서로 다릅니다. 서버는 설정을 `{ config }` 페이로드가 담긴 `module:configure`로 전달하지만, 서비스는 `ui:configure`를 수신 대기하며 `moduleName` 필드를 기대합니다. 또한 외부 서비스는 별도 프로세스로 실행되며 AIRI가 시작해 주지 않습니다. 따라서 모듈 이름만 고치거나 서비스를 수동으로 시작하는 것만으로는 이 폼이 동작하지 않습니다. + +지원되는 최종 사용자용 해결 방법은 없습니다. 구현을 조사하는 컨트리뷰터는 다음을 비교할 수 있습니다: + +- `packages/stage-ui/src/stores/modules/twitter.ts` +- `integrations/twitter-services/src/adapters/airi-adapter.ts` + +## 자격 증명 보안 + +이전에 자격 증명을 입력했다면 AIRI에서 제거하고, 유출됐을 가능성이 있다면 [X Developer Portal](https://developer.x.com/en/portal/dashboard)에서 교체하세요. X 자격 증명은 절대 커밋하거나, 스크린샷에 포함하거나, 공유하지 마세요. diff --git a/docs/content/ko/docs/manual/config/audio.md b/docs/content/ko/docs/manual/config/audio.md new file mode 100644 index 000000000..d41f1daed --- /dev/null +++ b/docs/content/ko/docs/manual/config/audio.md @@ -0,0 +1,41 @@ +--- +title: 음성 입력 및 출력 설정 +description: AIRI의 음성 합성(TTS)과 음성 인식(ASR/STT) 설정하기 +--- + +음성 합성(TTS)은 AIRI의 텍스트 응답을 소리 내어 읽어 주고, 음성 인식(ASR/STT)은 마이크 오디오를 텍스트로 변환합니다. 두 기능은 각각 독립적으로 설정할 수 있습니다. + +## 음성 합성(TTS) 설정 + +1. **설정 → 제공자 → 음성 합성**을 열고 제공자를 선택한 뒤 자격 증명을 입력하세요. +2. 제공자 플레이그라운드가 있다면 짧은 테스트 문장을 합성해 보세요. +3. **설정 → 모듈 → 음성 합성**을 열고 설정한 제공자, 모델, 음성을 선택하세요. + +제공자별 안내는 사이드바의 **서비스 제공자 → 음성 합성**을 참고하세요. 사용 중인 제공자가 OpenAI 음성 인터페이스를 구현한다면 [OpenAI Compatible API (TTS)](./providers/speech/openai.md)를 참고하세요. + +## 음성 인식(ASR/STT) 설정 + +1. **설정 → 제공자 → 전사**를 열고 제공자를 선택한 뒤 자격 증명을 입력하세요. +2. **설정 → 모듈 → 청각**을 열고 설정한 제공자와 모델을 선택하세요. +3. 올바른 마이크를 선택하고 **Start Monitoring**을 클릭한 뒤 짧은 문장을 말해 보세요. +4. 인식 결과 영역에 텍스트가 올바르게 표시되는지 확인하세요. + +제공자별 안내는 사이드바의 **서비스 제공자 → 전사**를 참고하세요. 사용 중인 제공자가 OpenAI 호환 전사 인터페이스를 지원한다면 [OpenAI Compatible API (ASR/STT)](./providers/transcription/openai.md)를 참고하세요. + +## FAQ + +### TTS 소리가 나지 않는 경우 + +음성 합성 제공자, 모델, 음성이 선택되어 있는지 확인하고, 시스템 출력 장치와 볼륨을 점검하세요. 플레이그라운드에서 오류가 표시되면 API Key, 계정 크레딧, 모델 기능을 확인하세요. + +### ASR이 텍스트를 생성하지 않는 경우 + +AIRI에 마이크 권한이 있는지, 청각 페이지에서 올바른 입력 장치가 선택되어 있는지 확인하세요. 실시간 인식 서비스의 경우 네트워크 장애나 브라우저/시스템 마이크 권한 회수로 인해 빈 결과가 나올 수도 있습니다. + +### 언어나 음성이 잘못된 경우 + +대상 언어를 제공자가 지원하는 모델과 음성을 선택하세요. 전사 언어, 지역, 모델 설정은 제공자 계정에 활성화된 기능과 일치해야 합니다. + +## 다음 단계 + +필드와 유효성 검사에 대한 자세한 내용은 [공통 설정 안내](./common.md)를 읽어 보세요. 제공자별 가이드는 **제공자 → 음성 합성**과 **제공자 → 전사** 아래에 있습니다. diff --git a/docs/content/ko/docs/manual/config/common.md b/docs/content/ko/docs/manual/config/common.md new file mode 100644 index 000000000..7aa5bcf2d --- /dev/null +++ b/docs/content/ko/docs/manual/config/common.md @@ -0,0 +1,45 @@ +--- +title: 일반 설정 안내 +description: AIRI의 제공자 설정 흐름, 필드, 확인 방법을 이해합니다 +--- + +이 페이지는 AIRI의 제공자 설정이 어떻게 동작하는지 설명합니다. 각 제공자의 API 엔드포인트, 계정 설정, 모델 선택은 해당 제공자별 가이드를 참고하세요. + +## 설정 과정 + +1. **설정 → 제공자**를 열고 **채팅**, **비전**, **음성 합성**, **전사**, **Artistry** 중 하나를 선택하세요. +2. 제공자를 선택하고 해당 설정 페이지에서 요구하는 자격 증명을 입력하세요. +3. 필요하다면 고급 설정을 펼쳐 제공자 문서에 나온 Base URL이나 다른 매개변수를 입력하세요. +4. 자동 유효성 검사가 끝날 때까지 기다리세요. 가능한 경우 **Ping API**나 제공자 플레이그라운드로 실제 요청을 테스트할 수 있습니다. +5. **설정 → 모듈** 아래의 해당 페이지에서 제공자와 모델 또는 음성을 선택하세요. + +::: warning 자격 증명 보안 +자격 증명과 제공자 설정은 현재 기기의 로컬 설정에 저장됩니다. API Key나 AccessKey Secret 같은 자격 증명을 스크린샷, 로그, 이슈, 채팅 메시지에 절대 노출하지 마세요. +::: + +## 공통 필드 + +| 필드 | 의미 | 안내 | +| --- | --- | --- | +| API Key | 제공자가 발급한 액세스 토큰 | 따옴표나 공백을 추가하지 말고 전체 키를 붙여넣으세요. | +| Base URL | 제공자 API의 루트 URL | 제공자 문서에서 다른 URL을 요구할 때만 변경하세요. `https://` 또는 `http://`를 포함한 전체 주소를 입력하세요. | +| 모델 | 채팅, 음성, 인식에 사용하는 모델 ID | AIRI의 목록에 있는 모델을 우선 사용하세요. 목록을 불러올 수 없고 필드가 직접 입력을 허용한다면, 제공자 문서에 나온 정확한 ID를 입력하세요. | +| 음성 | 음성 합성에 사용하는 음성 ID | 먼저 모델을 선택한 뒤, 해당 모델이 지원하는 음성을 선택하세요. | +| 리전 | 일부 클라우드 서비스가 사용하는 배포 리전 | 제공자 콘솔에 표시된 프로젝트 또는 리소스의 리전과 일치시키세요. | + +## 확인 결과 + +채팅 제공자 폼은 필수 필드의 유효성을 자동으로 검사합니다. **Ping API**를 제공하는 제공자는 실제 요청도 보낼 수 있으며, 이 과정에서 소량의 크레딧이 소모될 수 있습니다. 음성 제공자의 플레이그라운드는 가능한 경우 합성과 재생을 테스트합니다. 전사는 **설정 → 모듈 → 청각**에서 선택한 마이크로 테스트하세요. + +확인이 실패하면 다음 순서로 문제를 해결하세요. + +1. 계정이 서비스에 접근할 수 있고 사용 가능한 크레딧이나 할당량이 있는지 확인하세요. +2. API Key를 다시 복사하고, 앞뒤 공백이나 줄바꿈이 포함되지 않았는지 확인하세요. +3. 기본 Base URL을 복원하거나, 제공자의 공식 문서와 정확히 비교하세요. +4. 네트워크, 프록시, 방화벽이 제공자로의 접근을 허용하는지 확인하세요. +5. 제공자가 명시적으로 지원하는 모델을 선택하세요. 표시 이름을 모델 ID로 사용하지 마세요. + +## 다음 단계 + +- 텍스트 응답을 설정하려면 [채팅 모델 설정](./llm.md)을 읽어보세요. +- 음성 출력이나 마이크 입력을 설정하려면 [음성 입출력 설정](./audio.md)을 읽어보세요. diff --git a/docs/content/ko/docs/manual/config/index.md b/docs/content/ko/docs/manual/config/index.md index 87515357a..c27728d29 100644 --- a/docs/content/ko/docs/manual/config/index.md +++ b/docs/content/ko/docs/manual/config/index.md @@ -1,45 +1,56 @@ --- -title: 설정 가이드 -description: Project AIRI 사용법 +title: 제공자 설정 가이드 +description: Project AIRI의 채팅, 비전, 음성 합성, 전사, Artistry 제공자 설정하기 --- -## 설정 +AIRI와 대화하려면 최소 하나의 채팅 제공자와 채팅 모델을 설정해야 합니다. 음성 합성(TTS)은 음성 출력을, 자동 음성 인식(ASR/STT)은 마이크 입력을 추가합니다. 음성 입력과 출력은 선택 사항이며 서로 독립적으로 설정할 수 있습니다. -시스템 트레이에서 설정을 열어 더 자세히 커스터마이즈할 수 있습니다. 예를 들어 -AIRI의 테마 색상을 바꾸거나, Live2D(2D) 또는 VRM(3D, Grok Companion과 비슷한 형태) -같은 다른 모델로 전환할 수 있습니다. +## 최소 필수 설정하기 -