AstrBot 전용 컴패니언 플러그인 – “나는 영원히 당신 곁에 있을게”

개요 – 오픈소스 챗봇 프레임워크 AstrBot을 위한 플러그인으로, 장기적이고 성격 기반의 “컴패니언” 레이어를 추가합니다. 이 플러그인은 지속적인 라이프스타일 컨텍스트(상태, 일정, 관계, 꿈, 건강 등)를 유지하며, 이를 사용하여 개인 채팅, 그룹 채팅 또는 선택적 스탠드얼론 웹 UI를 통해 반응형 답변과 능동적 메시지(인사, 알림, 이미지 게시, 음성 메시지 등)를 생성합니다.

---

핵심 아이디어

AstrBot은 이미 수신된 메시지에 답하는 기본 “페르소나”를 제공합니다. 이 플러그인은 그 페르소나를 대체하지 않으며, 다음과 같은 캐릭터의 살아있는 시뮬레이션을 통해 이를 보완합니다:

• 일일 상태, 일정, 위치, 날씨, 건강, 배고픔 및 선택적 주기적 기분을 유지합니다.
• 주요 사용자(“메인 컴패니언”) 및 부차적 사용자와의 관계를 추적하며, 애정 수준, 상호작용 단계, 최근 주제 등을 저장합니다.
• 시뮬레이션된 생활 이벤트, 시간 창, 토큰 제한, 권한 확인을 기반으로 능동적 행동(텍스트, 이미지, 음성, 톡톡, 스크린 캡처 등)을 생성합니다.
• 디버깅과 투명성을 위해 모든 결정(메시지 전송 또는 차단 이유, 토큰 사용량, 감사 추적)을 로그로 기록합니다.
• 이미지 생성, 콘텐츠 제작, ComfyUI, 현실 세계 디바이스 상호작용 등의 선택적 모듈로 확장할 수 있습니다.

---

주요 기능

영역	플러그인 기능
생활 연속성	일일 상태(에너지, 기분, 수면, 건강, 배고픔), 상세 일정, 위치, 날씨, 음력, 선택적 주기적 시뮬레이션.
개인 채팅 컴패니언	개인화된 인사, 미완료 주제 기억, 경량 사용자 프로필, 속도 제한된 능동적 연락, 사용자별 설정 가능한 톤.
능동적 행동	텍스트, 사진, 음성, 톡톡, 스크린 캡처, 외부 도구 호출, 분할 메시지, 인용 트리거 전송.
그룹 채팅 이해	허용된 그룹을 관찰하고, 그룹 분위기를 형성하며, 멤버, 속어, 주제 스레드, 단기 기억, 관계 그래프를 추적하고, 적절한 시점에 코멘트를 삽입할 수 있습니다.
멀티모달	개인 채팅 이미지 처리, GIF 프레임 추출, 이미지 인용, 전달 병합, 이미지 생성(연결된 이미지 플러그인 via), TTS, 철회된 메시지의 단기 기억.
콘텐츠 라이프	뉴스, AI 일일 보고서, 능동적 웹 검색, B-site 하이라이트, 꿈 기록, 일기 항목, 메모; 어댑터가 존재할 경우 QQ 공간과 동기화 가능.
성장 및 기억	스킬 진행도, 개인 비창의적 목표, 자기 타임라인, 관계 관찰, 메모리 어시스턴트 통합.
관리 및 진단	비주얼 “컴패니언 패널”, 모델 라우팅, 토큰 및 잔액 개요, 설정 마이그레이션, 능동적 행동 감사, 내장 FAQ.

---

선택적 확장 (별도 설치)

• astrbot_plugin_image_companion – 이미지 생성(텍스트-투-이미지) 및 관련 명령어.
• astrbot_plugin_content_companion – 창의적 글쓰기, 스토리/앨범 관리.
• astrbot_plugin_comfyui – 이미지 생성을 위한 로컬 ComfyUI 워크플로.
• astrbot_plugin_reality_companion – 카메라/오디오 디바이스 상호작용(현실 세계의 “당신 곁에 있을게”).
• “메모리”, “함께”, “스크린”, “라이브스트림” 등 추가 컴패니언으로 각각 집중된 기능 세트를 추가합니다.

---

설치

방법	단계
플러그인 마켓 (AstrBot WebUI)	astrbot_plugin_private_companion 검색, 설치, AstrBot 재시작.
Git 설치	AstrBot 플러그인 매니저에서 Git에서 설치 선택 후 https://github.com/menglimi/astrbot_plugin_private_companion 입력.
ZIP 업로드	python scripts/build_plugin_package.py로 패키지 빌드(dist/astrbot_plugin_private_companion‑vX.Y.Z.zip 생성) 후 WebUI를 통해 업로드.
수동 복사	리포지토리를 <AstrBot data>/plugins/astrbot_plugin_private_companion으로 클론.
스탠드얼론 WebUI (선택)	설정에서 enable_standalone_webui 활성화, 액세스 토큰 설정 후 http://127.0.0.1:6190/ 접근.

---

빠른 시작 체크리스트 (약 10분)

1. 컴패니언 패널 열기 → 플러그인이 오류 없이 로드되는지 확인.
2. 세계 지식 설정 – 메인 AstrBot 페르소나를 지정하고 추가 캐릭터 또는 세계 설명 추가.
3. 모델 페이지 – 낮은 지연 시간 작업을 위한 빠른 모델, 일정/관계 추론을 위한 복잡한 모델, (이미지 플러그인이 있는 경우) 비주얼 모델 선택.
4. 기본 설정 입력 – 봇 이름, 시간대, 방해 금지 시간, 주요 사용자 ID.
5. 개인 채팅 탭에서 주요 사용자를 메인 사용자로 표시.
6. 개인 채팅에서 陪伴 状态 전송; 봇의 현재 상태, 일정, 다음 능동 후보가 표시되어야 함.
7. (선택) 그룹 채팅 관찰 활성화, 그룹을 화이트리스트에 추가하고 陪伴群 状态로 테스트.
8. 필요에 따라 추가 기능(이미지, 음성, 스크린 캡처, 뉴스 등)을 점차 활성화.

---

작동 방식 (고수준 흐름)

• 수동 응답 – 메시지가 도착하면, 플러그인은 계층적 컨텍스트(페르소나 → 시간 → 관계 → 콘텐츠 → 전송 전 확인)를 구성하고 LLM 제공자에게 전달하기 전에 자체 프롬프트를 추가합니다.
• 능동 후보 – 생활 이벤트, 일정 항목, 알림, 날씨 변화, 뉴스 등이 후보 행동을 생성합니다. 각 후보는 다음을 거칩니다:
  1. 시간 창 및 가치 점수화
  2. 사용자/관계/방해 금지 확인
  3. 페르소나 수준 결정
  4. 텍스트 생성 / 외부 도구 실행
  5. 최종 감사(중복 감지, 프라이버시 가드, 토큰 예산)
  6. 전송 → 로그 → 메모리 업데이트
• 상태 및 일정 – JSON(기본) 또는 SQLite(선택)에 저장됩니다. 플러그인은 각 상호작용 후 상태를 업데이트하며, 패널을 통해 내보내기/가져오기 가능합니다.
• 관계 엔진 – 8단계 애정 단계 + 메인 사용자를 위한 “독점적 유대”; 7단계 상호작용 강도; 자동 감쇠, 상한, 설정 가능한 “사과” 복구 로직.
• 멀티 페르소나 모드 (기본 비활성) – 각 페르소나는 독립적인 상태, 일정, 일기, 토큰 회계를 가집니다.

---

설정 하이라이트

• 토큰 제한 – 하드 제한은 모든 새로운 LLM 작업을 중단; 소프트 제한은 낮은 우선순위 백그라운드 작업(뉴스, 이미지 생성 등)을 스로틀링합니다.
• 모델 라우팅 – 빠른/복잡한/창의적/비주얼 모델을 작업별로 할당 가능; 모델이 누락된 경우 AstrBot 기본값으로 폴백.
• 이미지 생성 – 일일 의상, 사용자 요청 생성, 편집 또는 자동 “생활 이벤트” 이미지; 여러 백엔드(온라인 API, ComfyUI, SDGen) 지원 및 자동 폴백.
• TTS – 텍스트-투-스피치는 응답과 함께 전송하거나 별도의 음성 메시지로 전송 가능; Fish-Audio 모델 및 선택적 MiMo 음성 클론 통합 지원.
• 프라이버시 및 안전 – 플러그인은 성인 콘텐츠를 저장하거나 전달하지 않습니다; 관계 기반 권한은 프라이버시 또는 디바이스 액세스의 에스컬레이션을 방지합니다.

---

도움 받기

• 위키 – https://vue.syuan.org (설치, 설정, FAQ)
• 이슈 – 리포지토리의 GitHub Issues 페이지
• QQ 그룹 – 1097283005
• 스폰서 – 제공된 애발전 링크를 통한 선택적 지원(기능에 영향 없음).

---

요약

astrbot_plugin_private_companion은 AstrBot을 위한 완전한 기능과 확장 가능한 컴패니언 레이어로, 챗봇에게 영구적인 “생활”, 관계 기억, 능동적 행동을 부여하면서도 모든 것을 감사 가능하고 설정 가능하게 유지합니다. AstrBot 플러그인 마켓을 통해 설치하고 메인 사용자와 모델을 설정하면, 봇은 인사를 시작하고, 과거 대화를 기억하며, 일일 상태 업데이트를 게시하고, (추가 모듈을 활성화하면) 이미지, 음성 메시지를 생성하고, 심지어 현실 세계 디바이스와 상호작용합니다. 모든 행동은 JSON/SQLite 상태 파일에 의해 구동되며, 내장 웹 패널을 통해 검사하거나 조정할 수 있습니다.