본문으로 건너뛰기

JunkBox apps/jeevtrap 가이드

1. 애플리케이션 역할​

  • apps/jeevtrap는 Discord 기반 독립 실행형 툴킷 앱이며 선택적 로컬 음성 호출 인터페이스를 포함함.
  • /md, /북마크, /명령 세 기능을 제공함.
  • 공통 AI 호출은 shared-ai, 설정/로깅/DB는 shared-core, 로컬 음성 입력/STT/TTS는 shared-voice를 사용함.
  • 사용자 인증은 Discord interaction context를 사용하며 hub-api 공통 로그인 흐름을 사용하지 않음.
  • 공통 프롬프트 메타는 shared-core.masterdata.MasterDataService를 통해 hub-api 내부 master-data API에서 조회함.

2. 런타임 구성​

  • FastAPI 애플리케이션 엔트리포인트는 junkbox_jeevtrap.main:app임.
  • 상태 확인 경로는 /health임.
  • FastAPI lifespan 안에서 Discord 봇 런타임과 선택적 voice 런타임을 함께 시작하고 종료함.
  • Discord 런타임 엔트리포인트는 interfaces.discord.listeners.JeevtrapDiscordRuntime임.
  • Discord slash command 등록은 interfaces.discord.commands.register_command_tree()가 담당함.
  • voice 런타임 엔트리포인트는 interfaces.voice.runtime.JeevtrapVoiceRuntime임.
  • voice 런타임은 JEEVTRAP_VOICE_ENABLED=true일 때만 시작함.
  • voice 런타임은 blocking wake loop를 별도 thread에서 실행하며 FastAPI 이벤트 루프를 점유하지 않음.

2.1 레이어 구조​

  • interfaces/discord는 Discord UI 레이어임.
  • interfaces/voice는 로컬 음성 호출 인터페이스 레이어임.
  • services는 비즈니스 로직 레이어임.
  • repositories는 GitHub, Linkding, 명령 DB 접근 레이어임.
  • models는 Jeevtrap 전용 SQLModel 엔티티 레이어임.
  • scripts는 /명령에서 실행하는 패키지 내장 스크립트 레이어임.
  • discord.py 의존성은 interfaces/discord 내부에서만 사용함.
  • 마이크 입력, STT, TTS, 호출어 감지 구현은 interfaces/voice가 직접 소유하지 않고 shared-voice를 사용함.
  • 서비스 레이어는 discord.Interaction, Context 같은 Discord 객체를 입력이나 반환 타입으로 사용하지 않음.

2.2 로컬 개발 서버 연동​

  • jeevtrap는 18005 포트 기준 백엔드로 실행할 수 있음.
  • VS Code task는 jeevtrap:backend 단일 태스크를 사용하며, ENV_FILE=.env.local.jeevtrap와 uv run --package junkbox-jeevtrap uvicorn ... 형태로 패키지 의존성을 해석한 뒤 실행함.
  • 로컬 Jeevtrap 공통 환경값은 .env.jeevtrap, 로컬 전용 환경값은 .env.local.jeevtrap에 둠.
  • 로컬 Jeevtrap 런타임은 .env.shared, .env.jeevtrap, .env.local.jeevtrap 조합으로 설정을 로드함.
  • 로컬 Jeevtrap voice runtime은 JEEVTRAP_VOICE_ENABLED=True이면 함께 시작함.
  • 로컬 개발에서 AI 프롬프트 메타 조회는 hub-api 내부 master-data API에 의존하고, Discord UI 문구와 slash command 설명은 앱 내부 MessageCatalog를 사용함.
  • hub-api 로컬 백엔드는 18001 포트 기준으로 함께 실행되어야 함.
  • 로컬 AI 라우팅 파일은 apps/hub-api/var/master-data/ai-routing.yml 계열을 직접 사용함.
  • HUB_API_INTERNAL_TOKEN과 HUB_INTERNAL_BASE_URL이 유효하면 공통 메타를 shared-core 공통 master-data 소비 계층으로 조회함.
  • APP_PROFILE=local에서 내부 토큰이 비어 있으면 개발 편의용 local store fallback을 사용할 수 있음.
  • HUB_API_INTERNAL_TOKEN이 설정된 상태에서는 local store fallback을 사용하지 않고 HUB_INTERNAL_BASE_URL의 내부 API를 호출함.
  • Discord UI 문구는 앱 내부 MessageCatalog를 기준으로 하고, 프롬프트 메타는 hub-api 내부 master-data 메타 값을 기준으로 함.
  • hub-api가 내려가 있거나 HUB_INTERNAL_BASE_URL이 실제 리슨 포트와 맞지 않으면 프롬프트 메타 조회가 실패할 수 있음.
  • JEEVTRAP_DISCORD_TEST_GUILD_ID가 설정된 로컬 profile은 해당 테스트 길드에서 발생한 slash command와 멘션 메시지만 처리함.

2.3 운영 배포 기준​

  • 운영 컨테이너 기본 포트는 8005임.
  • 운영 이미지는 apps/jeevtrap 실행 코드와 패키지 스크립트를 함께 포함함.
  • 운영 jeevtrap는 WOL 브로드캐스트 전송을 위해 Docker host network로 실행함.
  • 운영 환경변수는 /sorc001/junkbox/env/.env.shared, /sorc001/junkbox/env/.env.jeevtrap, /sorc001/junkbox/env/.env.prod.jeevtrap를 함께 참조하고, 컨테이너 내부 ENV_FILE=/app/env/.env.prod.jeevtrap 기준으로 로딩함.
  • 운영 Jeevtrap 공통 환경값은 .env.jeevtrap, 운영 전용 환경값은 .env.prod.jeevtrap에 두며, 공통 prod profile env인 .env.prod는 로드하지 않음.
  • host network로 실행되는 운영 jeevtrap은 Docker DNS 서비스명 junkbox-hub를 사용할 수 없으므로 HUB_INTERNAL_BASE_URL을 호스트 네트워크에서 접근 가능한 hub-api 주소로 설정함.
  • host network로 실행되는 운영 jeevtrap은 Docker DNS 서비스명 postgres, litellm-proxy도 사용할 수 없으므로 DATABASE_URL, JEEVTRAP_LINKDING_DATABASE_URL, LITELLM_BASE_URL을 호스트 네트워크에서 접근 가능한 주소로 설정함.
  • 운영 jeevtrap의 DATABASE_URL과 JEEVTRAP_LINKDING_DATABASE_URL은 호스트에서 publish된 PostgreSQL 포트를 기준으로 127.0.0.1:5432 형태의 주소를 사용함.
  • 운영 jeevtrap의 LITELLM_BASE_URL은 호스트에서 publish된 LiteLLM proxy 포트를 기준으로 하며, 현재 운영 기준 값은 http://127.0.0.1:8083/v1임.
  • 운영 로그 볼륨은 /logs001/junkbox/jeevtrap 호스트 경로를 컨테이너 내부 /app/logs에 연결함.
  • 공통 애플리케이션 로그 파일 경로는 /app/logs/app.log임.
  • 운영 AI 라우팅 파일은 호스트 /sorc001/junkbox/master-data/ai-routing.yml를 컨테이너 내부 /app/var/master-data/ai-routing.yml로 마운트해서 사용함.
  • JEEVTRAP_DISCORD_TEST_GUILD_ID가 설정된 운영 profile은 해당 테스트 길드에서 발생한 slash command와 멘션 메시지를 처리하지 않음.
  • 운영 종료 명령용 SSH 비밀키는 호스트 키 파일을 컨테이너 내부 /run/secrets/jeevtrap_desktop_main_ssh_key에 read-only로 마운트해서 사용함.
  • 운영 이미지에는 bash, openssh-client, wakeonlan, PortAudio/ALSA/PulseAudio 연동 런타임 패키지를 포함함.
  • Docker Compose 서비스명은 junkbox-jeevtrap임.
  • 운영 compose에서 jeevtrap는 hub-api가 호스트 네트워크에서 접근 가능한 내부 master-data API를 제공하는 전제를 가짐.
  • 운영 compose는 voice runtime 활성화 시 사용할 수 있도록 PulseAudio/PipeWire socket과 cookie 마운트, PULSE_SERVER 설정을 포함함.
  • 운영 voice runtime은 JEEVTRAP_VOICE_ENABLED=False가 기본값임.

3. 설정 구조​

3.1 Jeevtrap 전용 설정 범주​

  • APP_PROFILE
  • LOG_LEVEL, LOG_DIAGNOSE_TOGGLE
  • DATABASE_URL
  • HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN
  • LITELLM_BASE_URL, LITELLM_API_KEY
  • JEEVTRAP_PORT
  • JEEVTRAP_VOICE_ENABLED
  • JEEVTRAP_VOICE_CONFIG_YAML_PATH
  • JEEVTRAP_DISCORD_TOKEN
  • JEEVTRAP_DISCORD_TEST_GUILD_ID
  • JEEVTRAP_GITHUB_TOKEN
  • JEEVTRAP_GITHUB_OWNER
  • JEEVTRAP_GITHUB_REPO
  • JEEVTRAP_GITHUB_BRANCH
  • JEEVTRAP_GITHUB_DEFAULT_DOCS_PATH
  • JEEVTRAP_LINKDING_DATABASE_URL
  • JEEVTRAP_LINKDING_OWNER_ID
  • JEEVTRAP_COMMAND_DEFAULT_TIMEOUT_SECONDS
  • JEEVTRAP_DISCORD_COMMAND_INTENT_DEBUG_REPLY
  • JEEVTRAP_TARGET_DESKTOP_MAIN_DISPLAY_NAME
  • JEEVTRAP_TARGET_DESKTOP_MAIN_MAC_ADDRESS
  • JEEVTRAP_TARGET_DESKTOP_MAIN_BROADCAST_IP
  • JEEVTRAP_TARGET_DESKTOP_MAIN_HOST
  • JEEVTRAP_TARGET_DESKTOP_MAIN_SSH_PORT
  • JEEVTRAP_TARGET_DESKTOP_MAIN_SSH_USER
  • JEEVTRAP_TARGET_DESKTOP_MAIN_SSH_KEY_PATH

3.2 설정 사용 원칙​

  • Jeevtrap local env 파일은 .env.jeevtrap.template을 기준으로 작성함.
  • .env.local.jeevtrap과 .env.prod.jeevtrap는 .env.shared, .env.jeevtrap와 함께 로드되며 .env.local, .env.prod를 참조하지 않음.
  • .env.jeevtrap는 Discord, GitHub, 공통 명령 target, 내부 토큰처럼 local/prod에서 공유하는 Jeevtrap 값을 보관함.
  • .env.local.jeevtrap과 .env.prod.jeevtrap는 Jeevtrap 실행 위치에 맞는 APP_PROFILE, LOG_LEVEL, LOG_DIAGNOSE_TOGGLE, DATABASE_URL, HUB_INTERNAL_BASE_URL, LITELLM_BASE_URL, JEEVTRAP_PORT, JEEVTRAP_VOICE_ENABLED, profile별 JEEVTRAP_* 값을 보관함.
  • .env.shared에는 profile과 무관하고 민감하지 않은 공통 기본값만 둠.
  • JEEVTRAP_LINKDING_DATABASE_URL은 SQLAlchemy async URL 형식 postgresql+asyncpg://...를 사용함.
  • JEEVTRAP_LINKDING_OWNER_ID는 Linkding DB 사용자 PK 기준 값임.
  • GitHub 토큰은 contents API 읽기/쓰기 권한이 있어야 함.
  • Discord 봇이 테스트 길드 기준으로 slash command 동기화와 로컬/운영 실행 분리를 적용하려면 JEEVTRAP_DISCORD_TEST_GUILD_ID를 사용함.
  • local profile은 테스트 길드만 허용하고 prod profile은 테스트 길드를 차단하며, 차단된 환경은 다른 실행 환경의 응답을 방해하지 않기 위해 무응답으로 무시함.
  • Discord 봇이 일반 평문 메시지를 해석하려면 Discord Developer Portal의 Message Content Intent와 봇 런타임 intent가 함께 활성화되어야 함.
  • JEEVTRAP_DISCORD_COMMAND_INTENT_DEBUG_REPLY=true이면 멘션 메시지를 인식했지만 실행 가능한 명령을 찾지 못한 경우 디버그 안내 메시지를 전송함.
  • JEEVTRAP_TARGET_DESKTOP_MAIN_SSH_KEY_PATH는 Windows OpenSSH Server에 등록된 공개키와 짝이 되는 비밀키 경로임.
  • 운영 JEEVTRAP_TARGET_DESKTOP_MAIN_SSH_KEY_PATH는 컨테이너 내부에서 접근 가능한 /run/secrets/jeevtrap_desktop_main_ssh_key 같은 마운트 경로를 사용함.
  • JEEVTRAP_VOICE_CONFIG_YAML_PATH는 로컬 기본값으로 apps/jeevtrap/var/voice.yml, 컨테이너 기본값으로 /app/apps/jeevtrap/var/voice.yml을 사용함.

3.3 Voice YAML 설정​

  • Jeevtrap voice runtime은 apps/jeevtrap/var/voice.yml을 기본 설정 파일로 사용함.
  • voice YAML은 호출어, 호출어 alias, 호출 성공 응답, 마이크 입력 장치, STT 모델, TTS provider를 정의함.
  • 현재 호출어 primary 값은 하이파이브임.
  • 호출어 alias는 하이 파이브, 하이파이브!, hi five, high five, High five, High five!, 하이파입, 하이파이 계열을 포함함.
  • 호출 성공 응답은 하이파이브!임.
  • STT provider는 faster_whisper이고 기본 모델은 CPU base + int8 조합임.
  • TTS provider는 supertonic이고 기본 언어는 ko, voice preset은 M1임.
  • audio.input_device는 PulseAudio/PipeWire pulse 장치를 기본으로 사용함.
  • 현재 voice runtime은 호출어 감지와 응답까지만 Jeevtrap에 연결되어 있으며, 명령 의도 판별과 실행 승인 플로우는 Discord 명령 흐름과 분리된 상태임.

4. 라우팅 및 Discord 명령 구조​

4.1 HTTP 라우팅​

  • GET /health
  • /health 응답은 discord_enabled, voice_enabled, port를 포함함.

4.2 Discord slash command​

  • /md
  • /북마크
  • /명령
  • slash command 이름, 설명, URL 옵션 설명은 앱 내부 MessageCatalog 값을 사용함.
  • Discord 명령 이름은 Discord command name 제약을 만족하는 카탈로그 값이어야 함.
  • /md의 영문 command name은 md를 사용함.
  • /북마크와 /명령의 command name은 한글 slash command 이름을 사용함.
  • slash command 실행은 JEEVTRAP_DISCORD_TEST_GUILD_ID와 APP_PROFILE 기준의 Discord guild guard를 먼저 통과해야 함.

4.3 Discord 평문 멘션 명령​

  • Jeevtrap 봇이 멘션된 일반 메시지만 평문 명령 인식 대상으로 처리함.
  • 멘션 메시지 실행은 JEEVTRAP_DISCORD_TEST_GUILD_ID와 APP_PROFILE 기준의 Discord guild guard를 먼저 통과해야 함.
  • 봇 멘션이 없는 일반 대화 메시지는 명령 인식 대상으로 보지 않음.
  • 멘션 제거 후 남은 사용자 문장을 AI 명령 의도 판별 입력으로 사용함.
  • AI가 실행 가능한 명령을 찾으면 기존 /명령과 같은 명령 확인 UI를 전송함.
  • 사용자가 확인 버튼을 누르면 연결된 명령 스크립트를 실행함.
  • AI가 실행 가능한 명령을 찾지 못하면 JEEVTRAP_DISCORD_COMMAND_INTENT_DEBUG_REPLY 설정에 따라 디버그 안내 메시지를 전송하거나 무응답으로 처리함.
  • 일상 대화, 잡담, 모호한 요청은 실행 가능한 명령 없음으로 판정하는 것을 기본 정책으로 함.

4.4 Discord UI 흐름​

  • /md는 모달 입력 -> 초안 생성 -> 승인/취소 -> 저장 경로 선택 -> GitHub 저장 흐름을 사용함.
  • 경로 선택 드롭다운은 docs/uncategorized를 항상 첫 옵션으로 포함하고, AI 추천 경로는 중복 제거 후 뒤에 배치함.
  • /북마크는 URL 입력 -> 중복 확인 -> 스크래핑/AI 분석 -> 저장/취소 흐름을 사용함.
  • /명령은 활성 명령 목록 조회 -> 선택 -> 확인 -> 실행 흐름을 사용함.
  • 평문 멘션 명령은 멘션 감지 -> AI 명령 의도 판별 -> 확인/디버그 안내 -> 실행 흐름을 사용함.
  • 버튼 라벨, 모달 제목, 입력 라벨, placeholder, embed field name, footer, 성공/실패 안내는 앱 내부 MessageCatalog의 한국어 문구를 사용함.
  • Discord decorator가 요구하는 초기 라벨도 앱 내부 카탈로그 값을 기준으로 사용함.
  • Jeevtrap UI 문구는 텍스트 DB 마스터데이터에 의존하지 않음.

5. 서비스 레이어 구조​

5.1 MarkdownGeneratorService​

  • 입력 초안과 요청자 정보를 받아 마크다운 초안을 생성함.
  • 공통 메타 AIBOT_MD_INSTRUCTION, AIBOT_MD_USER_TEMPLATE를 우선 사용함.
  • shared-ai의 DirectAiRunner에 JEEVTRAP_MD route key를 넘겨 structured output을 생성함.
  • 결과 DTO는 제목, 파일명, 마크다운, 추천 경로 목록을 포함함.
  • GitHub 저장은 GitHubRepository를 통해 수행함.

5.2 BookmarkProcessorService​

  • URL 중복 여부를 Linkding DB에서 먼저 확인함.
  • 대상 페이지를 HTTP로 스크래핑하고 본문을 텍스트로 정규화함.
  • 공통 메타 AIBOT_WEB_ANALYSIS_INSTRUCTION을 우선 사용함.
  • shared-ai의 DirectAiRunner에 JEEVTRAP_BOOKMARK route key를 넘겨 structured output을 생성함.
  • 결과 DTO는 원문 제목, 정제 제목, 요약, 태그 목록을 포함함.

5.3 CommandExecutorService​

  • jeevtrap.tb_command_m에서 활성 명령을 조회함.
  • 명령 실행 전 jeevtrap.tb_command_logs_n에 실행 로그를 생성함.
  • 현재 실행 방식은 SCRIPT만 지원함.
  • 패키지 내장 스크립트 경로는 classpath:/scripts/... 형태를 사용함.
  • 현재 내장 스크립트는 test-console-output.sh, wake-desktop.sh, shutdown-desktop.sh를 사용함.
  • target 해석은 현재 desktop-main 단일 타깃만 지원함.
  • 실행 로그에는 성공/실패 상태, 종료 코드, 표준 출력, 오류 메시지를 기록함.
  • slash command 메뉴에서 실행된 명령 로그의 request_channel_code는 DISCORD_SLASH를 사용함.
  • 평문 멘션에서 실행된 명령 로그의 request_channel_code는 DISCORD_MESSAGE를 사용함.
  • wake-desktop.sh는 wakeonlan으로 매직 패킷을 전송하며 SSH 설정을 사용하지 않음.
  • shutdown-desktop.sh는 SSH로 Windows OpenSSH Server에 접속해 고정 명령 shutdown /s /t 0을 실행함.

5.4 CommandIntentResolverService​

  • Discord 평문 멘션 메시지를 실행 가능한 Jeevtrap 명령으로 매핑하는 서비스임.
  • 활성 명령 목록과 사용자 요청 문장을 함께 LLM에 전달하고, structured output 결과를 기준으로 후보 명령을 선택함.
  • 공통 메타 AIBOT_COMMAND_INTENT_INSTRUCTION, AIBOT_COMMAND_INTENT_USER_TEMPLATE을 우선 사용함.
  • shared-ai의 DirectAiRunner에 JEEVTRAP_COMMAND_INTENT route key를 넘겨 명령 의도 판별 결과를 생성함.
  • 결과 DTO는 매칭 여부, 명령 ID, 신뢰도, 판정 근거를 포함함.
  • LLM이 낮은 확신도 또는 비명령성 요청으로 판단하면 실행 후보 없음으로 처리함.

6. 저장소 구조​

6.1 GitHubRepository​

  • GitHub contents API를 사용함.
  • 파일 존재 여부 확인 후 같은 경로가 있으면 suffix를 붙여 새 파일명을 계산할 수 있음.
  • 인증 실패 시 GitHub API 401 또는 403 오류를 그대로 상위로 전파함.

6.2 LinkdingRepository​

  • Linkding PostgreSQL DB에 직접 연결함.
  • bookmarks_bookmark, bookmarks_tag, bookmarks_bookmark_tags 테이블을 직접 사용함.
  • 북마크 저장은 중복 URL 검사 후 bookmark/tag/tag-link를 같은 트랜잭션 안에서 처리함.

6.3 CommandRepository​

  • jeevtrap.tb_command_m 활성 명령 조회를 담당함.
  • jeevtrap.tb_command_logs_n 실행 로그 생성과 상태 갱신을 담당함.

7. 데이터 구조​

7.1 Jeevtrap 스키마​

  • jeevtrap.tb_command_m은 명령 정의 테이블임.
  • jeevtrap.tb_command_logs_n은 명령 실행 로그 테이블임.
  • command_id, command_name, script_path, target_key, timeout_seconds, risk_level_code를 명령 정의 핵심 필드로 사용함.

7.2 외부 저장소​

  • /md는 GitHub repository contents API를 외부 저장소로 사용함.
  • /북마크는 Linkding PostgreSQL DB를 외부 저장소로 사용함.
  • AI 사용 로그는 Hub SQLite tb_ai_usage_logs_n에 기록됨.

8. 공통 AI 연계 구조​

8.1 DirectAiRunner 사용​

  • jeevtrap는 shared-ai의 DirectAiRunner만 사용함.
  • shared-ai는 provider 선택, route lookup, structured output 검증, usage log 기록을 공통 처리함.
  • jeevtrap 서비스는 프롬프트 조립과 도메인 후처리에만 집중함.

8.2 모델 라우팅​

  • /md는 JEEVTRAP_MD route key를 사용함.
  • /북마크는 JEEVTRAP_BOOKMARK route key를 사용함.
  • 평문 명령 의도 판별은 JEEVTRAP_COMMAND_INTENT route key를 사용함.
  • 현재 기본 라우팅은 JEEVTRAP_MD -> litellm:openrouter/deepseek/deepseek-v4-flash, JEEVTRAP_BOOKMARK -> litellm:openrouter/deepseek/deepseek-v4-flash, JEEVTRAP_COMMAND_INTENT -> litellm:openrouter/qwen/qwen-2.5-7b-instruct 구조를 사용함.
  • JEEVTRAP_COMMAND_INTENT는 짧은 명령 분류를 전제로 prompt_json structured output mode, 낮은 temperature, 낮은 top_p, 320 output token 예산을 사용함.
  • Jeevtrap AI 호출은 shared-ai의 공통 structured generation 경로를 사용하며, LiteLLM provider 어댑터가 response format 선택, JSON 파싱, Pydantic 검증, usage log 기록을 처리함.

9. 메시지 카탈로그 구조​

  • MessageCatalog는 Discord UI alias와 실제 한국어 문구의 매핑을 소유함.
  • MessageCatalog.get(alias)는 앱 내부 카탈로그에서 실제 문구를 조회함.
  • MessageCatalog.format(alias, *args)는 카탈로그 템플릿에 % 형식 인자를 적용함.
  • MessageCatalog는 Discord command tree 등록에 필요한 command name과 command description도 함께 보유함.
  • 버튼 라벨, 모달 제목, 입력 라벨, placeholder, embed field name, footer, 성공/실패 안내는 카탈로그에서 값을 찾지 못하면 alias 문자열을 반환함.
  • 운영 문구 정합성은 DB 메시지 등록이 아니라 카탈로그 상수와 공통 UI 표현 규칙으로 보장함.
  • aibot.md.*, aibot.bookmark.*, aibot.command-menu.*, aibot.command-intent.*는 Jeevtrap Discord UI 전용 alias 영역임.
  • 공통 버튼과 공통 상태 문구는 기존 앱 화면에서 쓰는 한국어 표현을 우선 맞춤.

10. 배포 및 운영 체크​

  • GitHub Actions selective build/deploy 구성은 junkbox-jeevtrap 서비스를 독립적으로 감지함.
  • GitHub Actions 배포 단계는 apps/hub-api/var/master-data/ai-routing.yml를 서버 배포 디렉터리로 전송한 뒤 /sorc001/junkbox/master-data/ai-routing.yml로 동기화함.
  • 운영 컨테이너는 host network에서 실행되므로 WOL 브로드캐스트는 호스트 네트워크 인터페이스 기준으로 전송됨.
  • 운영 컨테이너는 junkbox-hub에 depends_on을 가지므로 master-data 조회와 내부 API 접근 기준이 함께 배포되는 전제를 가짐.
  • /북마크 기능을 사용하려면 Linkding DB 접속 문자열과 owner id가 모두 유효해야 함.
  • /명령의 WOL 기능은 host network에서 브로드캐스트 패킷 전송이 가능해야 정상 동작함.
  • /명령의 종료 기능은 대상 Windows PC의 OpenSSH Server, 관리자 authorized keys 정책, 컨테이너 내부 SSH 키 마운트, 방화벽 포트 22 접근성이 유효해야 정상 동작함.
  • Discord 봇 실사용 전에는 애플리케이션 명령 동기화와 토큰 권한을 함께 확인해야 함.
  • Discord 평문 멘션 명령을 사용하려면 Discord Message Content Intent가 활성화되어 있어야 함.
  • Discord UI 메시지와 slash command 설명은 앱 내부 MessageCatalog에 등록되어 있어야 함.
  • voice runtime을 활성화하려면 JEEVTRAP_VOICE_ENABLED=True, 유효한 JEEVTRAP_VOICE_CONFIG_YAML_PATH, PulseAudio/PipeWire socket 접근, 오디오 장치 권한, Supertonic 모델 다운로드 가능성이 함께 충족되어야 함.
  • 운영 기본값은 JEEVTRAP_VOICE_ENABLED=False이며, 상시 STT 호출어 감지는 CPU와 메모리를 지속적으로 사용할 수 있음.

11. 관련 문서​

  • 프로젝트 전체 구조는 docs/junkbox/common/guide-jb-core.md를 따름.
  • 공통 설정, 로깅, DB 구조는 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • 공통 AI 런타임 구조는 docs/junkbox/libs/guide-lib-shared-ai.md를 따름.
  • 공통 음성 런타임 구조는 docs/junkbox/libs/guide-lib-shared-voice.md를 따름.
  • 공통 master-data API와 내부 API 제공자는 docs/junkbox/apps/guide-apps-hub-api.md를 따름.