VIRGO

Discord 추가하기

작성 기준
50a34893e3086a6012fd136d5e4a492a9066c5bc
제품 소스
adapters/discord/README.md, adapters/discord/adapter.json, cli/management-cli.ts, runtime/agent-management.ts
provider 문서
discord.com/…/getting-started, discord.com/…/gateway

이 가이드는 고정된 문서를 그대로 옮긴 것이 아니라 이 사이트가 직접 쓴 글입니다. 위의 제품 커밋을 기준으로 작성했으며, 인용한 모든 제품 경로가 그 커밋에 실제로 있는지 확인했습니다.

provider 포털 단계는 각 provider의 공식 문서를 따릅니다. 문서 끝에 링크가 있으며, provider가 소유한 부분은 그 문서를 따르세요.

Discord 추가하기

Discord는 Virgo에 포함된 채팅 adapter입니다. Discord Gateway v10, Bot API v10, 네이티브 정체성, 정확한 회신 주소, 반응 상태, 첨부 전송을 담당합니다. 두 번째 라우팅 정책을 만들지 않고, 봇마다 Seat을 만들지도, Seat마다 봇을 두지도 않습니다.

아직 읽지 않았다면 채팅 앱을 Virgo에 연결하기를 먼저 보세요. 특히, 이미 운영 중인 설치본에 adapter를 등록하는 것은 adapter add로 지원됩니다. 그래서 아래 단계는 준비해 둘 서술자가 아니라 그 명령에서 끝납니다.

시작하기 전에

  • 이미 운영 중이고 Hub에 닿을 수 있는 Virgo 설치본.
  • 여러분이 관리하는 Discord 서버. 기존 서버든 새 서버든 상관없습니다.
  • Discord 개발자 포털의 애플리케이션과 봇. Discord 공식 문서를 따라 만드세요. Virgo가 애플리케이션이나 봇을 대신 만들지 않습니다.

최소 권한

사용할 guild에 봇을 설치하고, 원하는 기능에 실제로 필요한 채널 권한만 부여하세요.

  • View Channels
  • Send Messages
  • Read Message History
  • Add Reactions
  • Attach Files

Administrator 권한은 주지 마세요.

Message Content intent를 켜세요. Virgo의 Gateway 클라이언트는 Guilds, Guild Messages, Direct Messages, 메시지 반응, Message Content를 요청합니다. 애플리케이션이 심사 규모에 이르면 Discord가 특권 intent 승인을 요구할 수 있습니다.

봇 토큰을 비공개로 보관하기

봇 토큰은 Virgo의 자격 증명 저장소에 넣고 id로 참조하세요. 서술자에는 credential:...만 들어가며 토큰 자체는 절대 들어가지 않습니다.

봇 토큰을 virgo.config.json이나 명령줄, Git 파일, Hub 메시지에 절대 넣지 마세요.

필요한 서술자

모두 자리표시자입니다. 모든 값을 여러분의 것으로 바꾸세요. 아래 ID들은 Discord snowflake 모양이지만 실제 값이 아닙니다.

{
  "id": "discord-main",
  "kind": "discord",
  "session": "discord-session",
  "vsp": "vsp:/your-account:your-space/discord/bot",
  "credential": "credential:discord/main",
  "applicationId": "000000000000000001",
  "botUserId": "000000000000000002",
  "targetVsp": "vsp:/your-account:your-space/your-repo/lead",
  "gatewayPort": "adapter-port:discord/gateway",
  "reactionStatePort": "adapter-port:discord/reactions",
  "artifactPort": "adapter-port:artifacts/managed",
  "allowedGuildIds": ["000000000000000003"],
  "allowedChannelIds": ["000000000000000004"],
  "defaultRoute": {
    "guildId": "000000000000000003",
    "channelId": "000000000000000004"
  },
  "accessNotificationRoute": {
    "guildId": "000000000000000003",
    "channelId": "000000000000000004"
  },
  "maximumInboundAttachmentBytes": 10000000,
  "maximumOutboundAttachmentBytes": 10000000,
  "access": {
    "administrators": ["discord.user:000000000000000007"]
  }
}

targetVsp는 받아들여진 메시지가 가는 곳입니다. allowedChannelIds에는 상위 채널을 적을 수 있고, 그 Discord thread 안의 메시지도 범위에 남습니다. defaultRoute는 기본 아웃바운드 대화이고, accessNotificationRoute는 승인 요청이 공지되는 곳입니다.

두 바이트 상한을 명시적으로 설정하세요. Discord 자체 업로드 한도는 계정과 guild, 등급, provider 실험에 따라 다릅니다. 따라서 설정한 숫자는 Virgo의 수용 상한이지 보편적인 Discord 한도에 대한 주장이 아닙니다.

발신자와 관리자

principal은 discord.user:<user-id>입니다. 바뀔 수 있는 사용자명과 표시 이름은 진단용일 뿐입니다. 봇 작성자, webhook, Discord 시스템 메시지 유형, 그리고 설정된 봇 자신은 라우팅 파서에 들어가지 않습니다.

Discord는 approval 접근이 기본입니다. 위 서술자처럼 access.mode를 설정하지 않으면, 새 발신자의 첫 메시지는 관리자가 결정할 때까지 보류됩니다. approval이 기본인데 요청을 공지할 accessNotificationRoute가 없는 서술자는 설치가 거부하므로 그 필드는 사실상 필수이며, 예시에도 들어 있습니다.

access.administrators에 적힌 관리자가 /virgo-access approve <requestId> 또는 /virgo-access deny <requestId>로 대기 중인 요청을 결정합니다. 관리자가 한 명도 없으면 첫 메시지를 승인할 주체가 없습니다.

이미 있는 설치본에 등록하기

새 설치본을 만들 때는 install이 위 서술자를 --adapters와 --host-settings로 받습니다. 설치본이 이미 있다면 지원되는 경로는 adapter add입니다.

adapter add --file /absolute/path/to/discord.json
adapter list
adapter remove discord-main

경로는 절대 경로여야 합니다. 이미 목록에 있는 id는 교체되지 않고 충돌로 거부되며, 새 항목만 준비되고, 그다음 목록 전체를 부팅이 검증하는 방식 그대로 검증합니다. 그래서 추가가 시작되지 않을 구성을 남길 수 없습니다. 서술자의 credentialBinding은 별도의 단계가 아니라 같은 작업 안에서 등록됩니다. adapter list는 각 항목이 지칭하는 자격 증명 참조와 함께 목록을 되읽으며, 비밀 자체는 보여 주지 않습니다.

다음 Host 시작에서 활성화됩니다. 동작 중인 Host는 부팅할 때 가지고 있던 adapter를 유지하고, 네이티브 agent 세션은 계속 돌아갑니다.

Discord 봇을 쓰려고 Hub를 다시 설치하지 마세요.

무엇이 검증되었고 무엇이 아직인가

한 정규 경로에서 이 adapter가 이미 존재하던 설치본에 적재되어 Gateway READY까지 도달했습니다. 검증은 현재 거기까지입니다. agent가 adapter를 통해 자신의 Seat을 claim하는 것, 사람의 메시지가 인바운드로 도착하는 것, 그에 상응하는 회신이 돌아 나가는 것은 아직 검증되지 않았습니다. 아직 그것들을 전제로 계획하지 마세요.

소스 테스트와 구성 검증도 현장 검증이 아닙니다. 격리된 설치본에서 다음 사슬을 순서대로 확인합니다.

  1. 릴리스에 adapters/discord/adapter.json과 정확한 모듈 바이트가 들어 있는지.
  2. Host가 설정된 인스턴스를 부팅하고 /users/@me가 기대한 봇 id를 증명하는지.
  3. Gateway READY/RESUMED, heartbeat ACK, 지속된 시퀀스 복구가 동작하는지.
  4. 사람의 메시지가 Hub 인가와 선택된 또는 기본 Seat에 도달하는지.
  5. 명시적으로 추가한 수신자가 더해지는 방식으로 같은 요청을 받는지.
  6. agent의 각 회신이 원래 guild·채널·thread·메시지로 간결한 [Virgo · Seat · VSP] 라벨과 함께 돌아가는지.
  7. 첨부 업로드와 다운로드, 반응 추가·교체·제거, 재시작 replay, 그리고 봇·webhook·시스템· 자기 메시지 거부가 Discord에서 관찰되는지.

파일과 반응

들어오는 첨부는 Gateway 커서가 확인되기 전에 Discord CDN에서 내려받은 뒤, 참여자 ACL과 보존 메타데이터와 함께 관리 artifact 저장소에 기록됩니다. 만료된 다운로드, 크기가 바뀐 것, 상한을 넘는 payload, 신뢰할 수 없는 URL은 거부됩니다.

반응은 provider의 추가·자기 반응 제거 경로를 씁니다. adapter는 메시지마다 자신이 마지막에 남긴 반응을 정확히 보존하므로, 재시작 뒤에도 자기가 아는 이모지만 제거합니다. 전체 삭제 경로는 절대 호출하지 않습니다.

문제 해결과 제거

  • 인바운드 메시지가 없습니다. Message Content intent, 봇이 그 guild에 있는지, 채널이 allowedChannelIds에 있는지 확인하세요.
  • 메시지는 오는데 답이 없습니다. provider 문제가 아니라 접근이나 라우팅 문제입니다. 접근 모드와, 관리자 결정을 기다리는 요청이 있는지 확인하세요.
  • 첨부가 거부됩니다. payload를 설정된 인바운드 상한과 비교하세요. 구속력이 있는 것은 설정된 상한입니다.
  • 제거. Discord에서 봇의 접근을 회수하고 자격 증명을 폐기하세요. 기존 설치본의 구성에서는 adapter remove <id>로 빼내며, Host는 다음 시작부터 그것을 제공하지 않습니다.

오늘 검증된 것

adapter 소스는 통합되어 있고 구성이 검증됩니다. 그것으로 봇 자격 증명이나 외부 게시, 실제 설치, Discord 현장 검증을 주장하지는 않습니다. 날짜가 붙은 입장은 가용성과 증거를 보세요.

프로토콜 참고 자료: Gateway, Gateway 이벤트, 메시지, 인증.