codebuddy-matrix-channel

Matrix 채팅을 CodeBuddy Code 로컬 세션의 **Channel 플러그인(MCP 서버)**에 연결합니다.

효과는 CodeBuddy에 내장된 Telegram / Discord / WeChat channel과 동일합니다:

• Matrix 방에서 메시지 전송 → #matrix · @alice:matrix.org: 안녕하세요 형태로 CodeBuddy 세션에 표시

• CodeBuddy의 답변은 reply 도구를 통해 Matrix 방으로 전송

• 선택 사항: CodeBuddy의 권한 요청 프롬프트를 "컨트롤 룸"으로 전달하여, 휴대폰에서 도구 호출을 승인/거부

이 플러그인은 CodeBuddy의 Channel 확장 메커니즘(docs/cn/cli/channels.md 및 channels-reference.md 참조)을 기반으로 하며, CodeBuddy 본체를 수정할 필요가 없습니다.

1. 작동 원리

Matrix 房间  ──(matrix-js-sdk 收消息)──▶  matrix-channel (本插件)
                                              │  notifications/claude/channel
                                              ▼
                                        CodeBuddy Code 会话
                                              │  reply 工具 / 权限请求
                                              ▼
                                        matrix-channel ──(sendText)──▶ Matrix 房间

플러그인은 CodeBuddy가 stdio로 시작하는 하위 프로세스로 실행되며, MCP 프로토콜로 통신합니다.

Related MCP server: mcacp

2. 설치

cd matrix-channel
npm install
npm run build        # 编译到 dist/（也可直接用 tsx 运行，无需构建）

실행 환경은 Node >= 20이 필요합니다.

2.1 빠른 시작(디지털 아바타)

1. 설치 / 컴파일

   cd matrix-channel && npm install && npm run build

2. .env 작성(최소 구성, 자세한 내용은 3절 참조)

   MATRIX_HOMESERVER=https://im.yiq.pub
   MATRIX_ACCESS_TOKEN=<从 Element：设置 → 帮助 → 高级 → 访问令牌 复制>
   MATRIX_USER_ID=@evlon-ai:im.yiq.pub
   MATRIX_ALLOWLIST=@evlon:im.yiq.pub           # 防 prompt 注入，必填
   MATRIX_OWNER_ID=@evlon:im.yiq.pub            # 分身管理者=你，审批权只认此身份
   MATRIX_CONTROL_ROOM_ID=!<控制室房间ID>:im.yiq.pub
   MATRIX_MENTION_REQUIRED=true                 # 群里只响应 @分身
   # 可选：MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS / MATRIX_AUTHORIZED_WORK

3. 자체 점검(.env를 수정할 때마다 먼저 실행)

   npm run doctor      # 期望：连接 ✅、账号 ✅、E2EE ✅

4. CodeBuddy 연결: 프로젝트 .mcp.json에 등록(절대 경로) 후 시작

   codebuddy --channels server:matrix --dangerously-load-development-channels

5. 일상 사용

   • 그룹에서 @아바타로 작업 지시 → 신뢰할 수 있는 출처/승인된 작업은 자동 실행, 낯선 작업은 먼저 계획을 세우고 컨트롤 룸에서 approve를 기다립니다.

   • 고위험 도구(Bash/파일 쓰기 등)는 항상 컨트롤 룸에서 승인을 요청합니다.

   • 컨트롤 룸에서 명령(MATRIX_OWNER_ID만 인식):

     • approve(run / go, 방 ID를 붙일 수 있음) → 해당 방의 작업 승인

     • yes <id> / no <id> → 대기 중인 고위험 권한 요청 승인 / 거부

암호화 그룹은 MATRIX_E2EE=true 필요; MATRIX_DEVICE_ID를 비워두면 /devices에서 자동 선택, 오류가 발생하면 "설정 → 기기"의 기기 ID를 입력하세요.

3. 설정

.env.example을 .env로 복사하고 작성:

cp .env.example .env

⚠️ 보안: MATRIX_ALLOWLIST를 반드시 설정하세요(방이 아닌 발신자 기준으로 검증, 그룹 채팅에서 임의 멤버의 세션 주입 방지). 비워두면 모든 사용자 허용, 로컬 테스트 전용입니다.

4. CodeBuddy 연결

방법 A: 개발 기간(마켓 화이트리스트 우회)

이 플러그인을 CodeBuddy 프로젝트 .mcp.json에 등록:

{
  "mcpServers": {
    "matrix": {
      "command": "npx",
      "args": ["tsx", "/绝对路径/matrix-channel/src/index.ts"]
    }
  }
}

그런 다음 CodeBuddy 시작:

codebuddy --channels server:matrix --dangerously-load-development-channels

컴파일 후 node로 실행하려면:

"args": ["node", "/绝对路径/matrix-channel/dist/index.js"]

방법 B: 플러그인으로 패키징(공식 마켓에 제출 후)

npm run build

그런 다음 codebuddy-matrix-channel을 플러그인으로 게시하고, 이후에는:

codebuddy --channels plugin:matrix-channel@<你的市场>

5. 사용

1. 시작 후, 허용된 Matrix 방에서 메시지를 보내면 CodeBuddy 세션에 #matrix · @당신: ...이 표시됩니다.

2. CodeBuddy가 처리를 완료하면 답변이 Matrix 방에 표시됩니다.

3. MATRIX_CONTROL_ROOM_ID를 설정한 경우: CodeBuddy가 승인이 필요한 도구(Bash / Write 등)를 호출하면 컨트롤 룸에 알림이 전송됩니다(m.notice 시스템 알림으로 전송, 읽지 않음/알림 트리거 없음). yes <id>로 허용 / no <id>로 거부

reply 도구 매개변수

예: CodeBuddy가 m.notice로 상태 알림을 보내도록 하려면: reply({ chat_id: "!abc:server", text: "처리 완료", msgtype: "m.notice" }).

health_check 도구

CodeBuddy 세션에서 직접 호출하거나 /mcp 건강 검사에서 트리거할 수 있으며, npm run doctor의 연결성/E2EE 부분과 동일합니다. JSON 반환:

{ "ok": true, "userId": "@alice:matrix.org", "e2ee": true, "cryptoReady": true }

ok=false일 때 error 필드에 실패 원인(연결/인증/E2EE 초기화)이 포함됩니다.

6. 제한 사항 및 주의 사항

• 종단 간 암호화(E2EE) 방: 기본적으로 암호화되지 않은 방만 지원합니다. 암호화된 방을 연결하려면 MATRIX_E2EE=true로 설정하면, 플러그인이 matrix-js-sdk 내장 Rust crypto(initRustCrypto)를 재사용하여 SDK가 "수신 시 복호화, 전송 시 암호화"를 자동으로 처리합니다. 암호화 프로토콜을 직접 구현할 필요가 없습니다. 활성화 후:

  • 암호화된 메시지는 m.room.encrypted로 도착하고, SDK가 복호화(Event.decrypted)를 완료하면 실제 유형으로 변경된 후 플러그인이 세션에 전달합니다.

  • 암호화된 방으로 보내는 답변은 SDK가 자동으로 암호화합니다.

  • 키 저장(중요, 버전 관련): matrix-js-sdk 42.x에서 Rust crypto 백엔드는 wasm/IndexedDB 구현(@matrix-org/matrix-sdk-crypto-wasm)만 있으며, Node 네이티브 백엔드가 없습니다. Node에서 실행하기 위해 플러그인은 시작 시 fake-indexeddb/auto로 Node에 전역 indexedDB 폴리필을 주입합니다. 이 폴리필은 순수 메모리이므로:

    • 키는 실제로 프로세스 메모리에만 존재하며, MATRIX_CRYPTO_DB는 이 버전에서 실제 SQLite 파일을 생성하지 않습니다. 프로세스를 다시 시작하면 키를 다시 협상해야 합니다(송수신에는 영향 없음, 키 전달/기기 검증만 다시 수행).

    • 실제 디스크 영속화는 @matrix-org/matrix-sdk-crypto-nodejs 네이티브 백엔드가 포함된 matrix-js-sdk 버전으로 업그레이드하거나, 향후 nodejs 엔트리를 지원하는 버전(그때 fake-indexeddb 폴리필을 제거하고 네이티브 백엔드로 전환)이 필요합니다.

    • 참고: 의존성에 이미 설치된 @matrix-org/matrix-sdk-crypto-nodejs는 현재 42.2.0에서 SDK가 호출하지 않으며, 향후 업그레이드를 위한 대비책일 뿐입니다. 현재 암호화 핵심은 wasm + fake-indexeddb 메모리 폴리필로 작동합니다.

  • 새 기기가 암호화된 방에 처음 들어갈 때, Matrix 클라이언트에서 이 bot의 기기를 검증하는 것이 좋습니다(그렇지 않으면 상대방이 "검증되지 않은 기기" 알림을 볼 수 있지만, 메시지는 정상적으로 송수신됩니다).

• 미디어: 기본적으로 메시지 텍스트만 세션에 연결합니다. MATRIX_DOWNLOAD_MEDIA를 활성화하면 이미지/파일을 로컬에 다운로드하고 [file: 경로]로 주입하여 Agent가 읽을 수 있게 합니다.

• 권한 중계는 CodeBuddy의 claude/channel/permission 기능에 의존합니다. CodeBuddy 버전이 지원하지 않으면 핵심 채팅 연결에는 영향이 없습니다.

7. 디지털 아바타: 관리자 승인 모델(핵심 시나리오)

아바타를 "그룹의 동료"로 취급하여, 자유롭게 @로 작업을 지시할 수 있지만 관리자가 승인하기 전에는 실제로 아무것도 변경하지 않습니다.

시나리오

• 동료가 여러 그룹(예: #프로젝트A, #고객센터)을 만들고, 그룹에 여러 아바타 bot이 있을 수 있습니다. 동료가 그룹에서 @당신의 아바타로 작업을 지시합니다. @멘션된 경우에만 응답(직접 DM은 항상 응답).

• 작업 지시 수신 후:

  • 일반 / 승인된 작업(사전 설정된 MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS 출처, 또는 MATRIX_AUTHORIZED_WORK 설명 범위에 속함) → 자동 실행(안전한 도구).

  • 낯선 작업(승인 범위 밖) → 아바타가 먼저 계획을 세우고, request_approval을 호출하여 컨트롤 룸으로 에스컬레이션합니다. approve로 응답해야 실행합니다.

  • 고위험 작업(MATRIX_HIGH_RISK_TOOLS, 예: Bash / 파일 쓰기) → 출처와 관계없이 항상 승인 요청.

아키텍처 계층

• MCP 플러그인 = 안전한 전송 + 하드 게이트(코드로 강제, 모델 신뢰 안 함): @ 필터, 권한 판정 allow/deny는 검증 가능한 사실(owner 여부, 신뢰할 수 있는 출처 여부, 고위험 도구 여부)만 기준으로 하며, 컨트롤 룸 승인은 MATRIX_OWNER_ID만 인식합니다.

• SKILL = 정책 두뇌(의미 판단, Agent에 위임): skills/matrix-avatar/SKILL.md는 아바타가 "일반 vs 낯선"을 판단하도록 안내하며, 낯선 경우 계획 모드로 전환하고 request_approval을 호출합니다. Agent는 승인만 요청하고 스스로 승인하지 않습니다. 승인은 "관리자의 신뢰할 수 있는 출처 사전 설정" 또는 "관리자 approve"에서만 나옵니다.

플러그인 내장 channel instructions에 이 정책이 인라인되어 있으므로, SKILL을 추가로 설치하지 않아도 작동합니다. skills/matrix-avatar/SKILL.md는 CodeBuddy에서 재사용/미세 조정할 수 있도록 제공됩니다.

3단계 작업 상태(방별)

컨트롤 룸 명령(관리자 MATRIX_OWNER_ID만 유효)

• approve(또는 run / go, 선택적으로 방 ID, 예: approve !projectA:server) → 해당 방의 현재 작업 승인, 아바타가 실행 시작.

• yes <id> / no <id> → 대기 중인 고위험 권한 요청 승인 / 거부.

• 다른 사람의 컨트롤 룸 응답은 무시됩니다.

설정 예시(.env)

MATRIX_OWNER_ID=@you:matrix.org
MATRIX_TRUSTED_SENDERS=@alice:matrix.org,@bob:matrix.org
MATRIX_TRUSTED_ROOMS=!projectA:server
MATRIX_AUTHORIZED_WORK=回答产品问题、总结会议纪要、起草文档
MATRIX_MENTION_REQUIRED=true
MATRIX_HIGH_RISK_TOOLS=Bash,Write,Edit,MultiEdit,NotebookEdit

8. 자체 점검(doctor)

.env를 작성한 후, CodeBuddy를 시작하기 전에 자체 점검을 실행하여 설정, 연결성, E2EE 상태를 확인할 수 있습니다:

npm run doctor

자체 점검은 현재 설정(token 마스킹), homeserver 연결 가능 여부와 자격 증명 유효성을 확인하고, MATRIX_E2EE=true일 때 Rust crypto 초기화를 시도합니다. 항목이 실패하면 명확한 원인을 출력하고 0이 아닌 종료 코드로 종료합니다.

9. 디렉터리 구조

matrix-channel/
├── src/
│   ├── config.ts     # 环境变量 / 白名单 / 授权配置读取与校验
│   ├── matrix.ts     # Matrix 客户端封装（连接、@提及过滤、收/发、下载媒体、E2EE、自检）
│   ├── index.ts      # MCP 服务：channel 通知、授权硬闸、reply / request_approval 工具、控制室审批
│   └── doctor.ts     # `npm run doctor` 自检入口
├── skills/
│   └── matrix-avatar/
│       └── SKILL.md  # 分身行为策略（语义判断：常用 vs 陌生）
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md