codebuddy-matrix-channel

Ein Channel-Plugin (MCP-Server), das Matrix-Chats mit lokalen CodeBuddy-Code-Sitzungen von CodeBuddy Code verbindet.

Die Wirkung entspricht den in CodeBuddy integrierten Telegram-/Discord-/WeChat-Channels:

• Nachrichten in Matrix-Räumen senden → erscheinen als #matrix · @alice:matrix.org: Hallo in der CodeBuddy-Sitzung

• Antworten von CodeBuddy werden über das reply-Tool zurück in den Matrix-Raum gesendet

• Optional: Berechtigungsanfragen von CodeBuddy werden an den „Kontrollraum" weitergeleitet, wo du Tool-Aufrufe am Handy genehmigen/ablehnen kannst

Dieses Plugin basiert auf dem Channel-Erweiterungsmechanismus von CodeBuddy (siehe docs/cn/cli/channels.md und channels-reference.md) und erfordert keine Änderungen an CodeBuddy selbst.

1. Funktionsweise

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

Das Plugin wird als Unterprozess von CodeBuddy über stdio gestartet und kommuniziert über das MCP-Protokoll.

Related MCP server: mcacp

2. Installation

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

Für die Laufzeit wird Node >= 20 benötigt.

2.1 Schnellstart (Digitaler Avatar)

1. Installieren / Kompilieren

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

2. .env ausfüllen (minimaler funktionsfähiger Satz, siehe Abschnitt 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. Selbsttest (nach jeder Änderung an .env zuerst ausführen)

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

4. CodeBuddy anbinden: In der Projekt-.mcp.json registrieren (absoluter Pfad) und dann starten

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

5. Tägliche Nutzung

   • Im Gruppenchat @Avatar Aufgaben zuweisen → vertrauenswürdige Quellen/autorisierte Arbeiten werden automatisch ausgeführt; unbekannte Arbeiten erstellen zuerst einen Plan und warten im Kontrollraum auf dein approve.

   • Hochrisiko-Tools (Bash/Dateien schreiben usw.) fragen dich immer im Kontrollraum.

   • Du gibst Befehle im Kontrollraum (nur MATRIX_OWNER_ID wird akzeptiert):

     • approve (run / go, optional mit Raum-ID) → autorisiert Aufgaben in diesem Raum

     • yes <id> / no <id> → genehmigt / lehnt wartende Hochrisiko-Berechtigungsanfragen ab

Für verschlüsselte Gruppen ist MATRIX_E2EE=true erforderlich; wenn MATRIX_DEVICE_ID leer bleibt, wird automatisch aus /devices ausgewählt. Bei Fehlern die Geräte-ID aus „Einstellungen → Geräte" eintragen.

3. Konfiguration

Kopiere .env.example zu .env und fülle es aus:

cp .env.example .env

⚠️ Sicherheit: MATRIX_ALLOWLIST unbedingt konfigurieren (Prüfung nach Absender statt Raum, um Injektionen durch beliebige Mitglieder im Gruppenchat zu vermeiden). Leer lassen erlaubt allen, nur für lokale Tests geeignet.

4. Anbindung an CodeBuddy

Variante A: Entwicklungsphase (Markt-Whitelist umgehen)

Registriere dieses Plugin in der .mcp.json deines CodeBuddy-Projekts:

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

Dann CodeBuddy starten:

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

Nach dem Kompilieren kann die Ausführung mit node wie folgt geändert werden:

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

Variante B: Als Plugin verpacken (nach Einreichung im offiziellen Markt)

npm run build

Dann codebuddy-matrix-channel als Plugin veröffentlichen und anschließend verwenden:

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

5. Verwendung

1. Nach dem Start Nachrichten in erlaubten Matrix-Räumen senden; in der CodeBuddy-Sitzung erscheint #matrix · @du: ...

2. Nach Abschluss der Verarbeitung durch CodeBuddy erscheint die Antwort im Matrix-Raum

3. Wenn MATRIX_CONTROL_ROOM_ID konfiguriert ist: Bei Tool-Aufrufen, die eine Genehmigung erfordern (Bash / Write usw.), erhält der Kontrollraum eine Benachrichtigung (als m.notice-Systemnachricht gesendet, ohne Ungelesen/Erinnerungen auszulösen); mit yes <id> genehmigen / no <id> ablehnen

Parameter des reply-Tools

Beispiel: CodeBuddy eine Statusmeldung mit m.notice zurücksenden lassen: reply({ chat_id: "!abc:server", text: "Verarbeitet", msgtype: "m.notice" }).

health_check-Tool

Kann direkt in der CodeBuddy-Sitzung aufgerufen oder im /mcp-Health-Check ausgelöst werden; entspricht dem Konnektivitäts-/E2EE-Teil von npm run doctor und gibt JSON zurück:

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

Bei ok=false wird ein error-Feld mit der Fehlerursache angehängt (Verbindung/Authentifizierung/E2EE-Initialisierung).

6. Einschränkungen und Hinweise

• Ende-zu-Ende-verschlüsselte (E2EE) Räume: Standardmäßig werden nur unverschlüsselte Räume unterstützt. Zum Überbrücken verschlüsselter Räume MATRIX_E2EE=true setzen; das Plugin nutzt dann die in matrix-js-sdk integrierte Rust-Crypto (initRustCrypto), wobei das SDK automatisch „beim Empfang entschlüsseln, beim Senden verschlüsseln" übernimmt – kein eigenes Verschlüsselungsprotokoll nötig. Nach Aktivierung:

  • Verschlüsselte Nachrichten treffen als m.room.encrypted ein; nach der Entschlüsselung durch das SDK (Event.decrypted) wird der Typ zum echten Typ und das Plugin leitet sie an die Sitzung weiter;

  • Antworten an verschlüsselte Räume werden vom SDK automatisch verschlüsselt;

  • Schlüsselspeicherung (wichtig, versionsabhängig): Bei matrix-js-sdk 42.x hat das Rust-Crypto-Backend nur eine wasm/IndexedDB-Implementierung (@matrix-org/matrix-sdk-crypto-wasm), kein natives Node-Backend. Damit es unter Node läuft, injiziert das Plugin beim Start mit fake-indexeddb/auto einen globalen indexedDB-Shim in Node – dieser Shim ist rein speicherbasiert, daher:

    • Schlüssel existieren nur im Prozessspeicher; MATRIX_CRYPTO_DB erzeugt in dieser Version keine echte SQLite-Datei auf der Festplatte; nach einem Prozessneustart müssen Schlüssel neu ausgehandelt werden (beeinträchtigt Senden/Empfangen nicht, erfordert nur erneuten Schlüsselaustausch/Geräteverifizierung).

    • Echte Festplatten-Persistenz erfordert ein Upgrade auf eine matrix-js-sdk-Version mit nativem @matrix-org/matrix-sdk-crypto-nodejs-Backend oder eine zukünftige Version mit nodejs-Einstieg (dann den fake-indexeddb-Shim entfernen und das native Backend verwenden).

    • Hinweis: Das in den Abhängigkeiten bereits installierte @matrix-org/matrix-sdk-crypto-nodejs wird unter der aktuellen 42.2.0 nicht vom SDK aufgerufen und dient nur als Option für zukünftige Upgrades; der aktuelle Verschlüsselungskern arbeitet über wasm + fake-indexeddb-Speicher-Shim.

  • Beim ersten Betreten eines verschlüsselten Raums mit einem neuen Gerät wird empfohlen, im Matrix-Client das Gerät dieses Bots zu verifizieren (sonst kann der Gegenüber den Hinweis „nicht verifiziertes Gerät" sehen, Nachrichten funktionieren aber weiterhin normal).

• Medien: Standardmäßig wird nur der Nachrichtentext in die Sitzung überbrückt; mit MATRIX_DOWNLOAD_MEDIA werden Bilder/Dateien lokal heruntergeladen und als [file: Pfad] eingefügt, damit der Agent sie lesen kann.

• Berechtigungs-Relay hängt von der claude/channel/permission-Fähigkeit von CodeBuddy ab; wenn die CodeBuddy-Version diese nicht unterstützt, bleibt die Kern-Chat-Brücke davon unberührt.

7. Digitaler Avatar: Autorisierungsmodell des Managers (Kern-Szenario)

Behandle den Avatar als „Kollegen im Gruppenchat", der beliebig per @ beauftragt werden kann, aber vor der Zustimmung des Managers nichts wirklich ändert.

Szenario

• Kollegen erstellen mehrere Gruppen (z. B. #ProjektA, #Kundenservice), in denen gleichzeitig mehrere Avatar-Bots sein können. Kollegen beauftragen deinen Avatar per @ im Gruppenchat; nur bei @-Erwähnung wird reagiert (bei direkten Privatnachrichten immer).

• Nach Erhalt eines Auftrags:

  • Häufige / autorisierte Arbeiten (von deinen voreingestellten MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS oder im Rahmen von MATRIX_AUTHORIZED_WORK) → automatisch ausführen (sichere Tools).

  • Unbekannte Arbeiten (nicht im Autorisierungsbereich) → der Avatar erstellt zuerst einen Plan und eskaliert über request_approval an deinen Kontrollraum; erst nach deinem approve wird ausgeführt.

  • Hochrisiko-Operationen (MATRIX_HIGH_RISK_TOOLS, z. B. Bash / Dateien schreiben) → unabhängig von der Quelle immer bei dir anfragen.

Architektur-Ebenen

• MCP-Plugin = sichere Übertragung + harte Sperre (code-erzwungen, vertraut dem Modell nicht): @-Filter, Berechtigungsentscheidung allow/deny basiert nur auf verifizierbaren Fakten (ob Owner, ob vertrauenswürdige Quelle, ob Hochrisiko-Tool), Kontrollraum-Genehmigungen erkennen nur MATRIX_OWNER_ID.

• SKILL = Strategie-Gehirn (semantische Beurteilung, dem Agent überlassen): skills/matrix-avatar/SKILL.md leitet den Avatar bei der Unterscheidung „häufig vs. unbekannt"; bei Unbekanntem wechselt er in den Planungsmodus und ruft request_approval auf. Der Agent beantragt nur Genehmigungen, gibt sich nie selbst frei; Freigaben kommen nur von „vertrauenswürdigen Quellen des Managers" oder „Manager-approve".

Die im Plugin integrierten Channel-instructions enthalten diese Strategie bereits inline, sodass es auch ohne zusätzliche SKILL-Installation funktioniert; skills/matrix-avatar/SKILL.md steht dir zur Wiederverwendung/Feinabstimmung in CodeBuddy zur Verfügung.

Drei-Ebenen-Aufgabenstatus (pro Raum)

Kontrollraum-Befehle (nur für Manager MATRIX_OWNER_ID gültig)

• approve (oder run / go, optional mit Raum-ID, z. B. approve !projectA:server) → autorisiert die aktuelle Aufgabe in diesem Raum, der Avatar beginnt mit der Ausführung.

• yes <id> / no <id> → genehmigt / lehnt wartende Hochrisiko-Berechtigungsanfragen ab.

• Antworten anderer im Kontrollraum werden ignoriert.

Konfigurationsbeispiel (.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. Selbsttest (doctor)

Nach dem Ausfüllen der .env kann zuerst ein Selbsttest zur Bestätigung von Konfiguration, Konnektivität und E2EE-Status ausgeführt werden, bevor CodeBuddy gestartet wird:

npm run doctor

Der Selbsttest gibt die aktuelle Konfiguration aus (Token maskiert), prüft die Erreichbarkeit des Homeservers und die Gültigkeit der Anmeldedaten und versucht bei MATRIX_E2EE=true die Initialisierung der Rust-Crypto. Bei jedem Fehler wird eine klare Ursache angegeben und mit einem Exit-Code ungleich 0 beendet.

9. Verzeichnisstruktur

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