Derpyu520/qq-bridge

해결하는 문제

이 프로젝트는 QQ 메시징과 DeepSeek Harness (DSH) 에이전트 프레임워크를 연결하여, 사용자가 QQ 개인 메시지 또는 그룹 채팅을 통해 AI 에이전트와 상호작용할 수 있도록 합니다. QQ 메시지를 DSH 세션으로 변환하고, 에이전트의 응답, 질문, 도구 승인을 다시 QQ 사용자에게 전달합니다.

작동 방식

이 브리지(다리)는 SnowLuma(OneBot v11 WebSocket 클라이언트)와 DSH Web API 사이의 미들웨어 역할을 합니다. 각 QQ 채팅(개인 또는 그룹)을 전용 "QQ 채팅" 워크스페이스 내의 고유한 DSH 세션에 매핑합니다.

주요 기술 구성 요소는 다음과 같습니다:

• 통신: SnowLuma를 통해 QQ에 WebSocket 연결하고, DSH에는 REST/Event-stream API 사용.
• MCP 통합: Model Context Protocol (MCP) 서버를 통합하여, 메시지 전송, 그룹 상태 확인, SSRF 보호를 갖춘 웹 검색과 같은 안전한 기능을 에이전트에 제공.
• 운영 모드: chat (표준 안전 채팅), closed-agent (소유자 전용 완전한 도구 접근), reserved (상태 기계를 사용한 활동 및 침묵 시뮬레이션된 그룹 멤버 행동) 등 여러 모드 지원.
• 상호작용 로직: 메시지 인용(답변), 슬래시 명령어(/reset 등), 시뮬레이션된 역할을 위한 다중 부분 메시지 분할 처리.

대상 사용자

• AI 에이전트를 QQ에 도입하고 싶은 DeepSeek Harness 사용자.
• 자율적으로 관찰하고 참여할 수 있는 "AI 시뮬레이션 그룹 멤버"를 개발하고 싶은 개발자.
• QQ를 통해 DSH 인스턴스를 원격으로 제어하고 싶은 고급 사용자.

주요 특징

• 다중 모드 운영: 표준 채팅, 소유자 전용 에이전트 제어, 자율 시뮬레이션 모드 간 전환 가능.
• 안전한 도구 사용: MCP를 통해 QQ 작업의 제한된 하위 집합만 사용하여 비승인된 계정 제어를 방지.
• 세션 관리: QQ ID와 DSH 세션 간의 매핑을 자동으로 관리하고 지속적으로 유지.
• 인터랙티브 피드백: 에이전트가 사용자에게 질문이나 도구 승인 요청을 할 경우, 이를 직접 QQ로 전달하여 실시간 결정 가능.
• 내장 콘솔: 실시간 모드 전환 및 역할 구성이 가능한 웹 기반 제어 패널 포함.