codebuddy-matrix-channel

Мост для подключения Matrix к локальной сессии CodeBuddy Code (https://cnb.cool/codebuddy/codebuddy-code) через Channel-плагин (MCP-сервер).

Эффект аналогичен встроенным каналам CodeBuddy для Telegram / Discord / WeChat:

• Сообщение в комнате Matrix → появляется в сессии CodeBuddy в виде #matrix · @alice:matrix.org: привет

• Ответы CodeBuddy отправляются обратно в комнату Matrix через инструмент reply

• Опционально: запросы на разрешение от CodeBuddy пересылаются в «контрольную комнату», где можно одобрить/отклонить вызовы инструментов с телефона

Этот плагин основан на механизме расширения Channel от CodeBuddy (см. 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: на этапе разработки (в обход белого списка маркета)

Зарегистрируйте этот плагин в .mcp.json вашего проекта CodeBuddy:

{
  "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; плагин использует встроенный Rust crypto от matrix-js-sdk (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, плагин при запуске внедряет глобальный indexedDB через fake-indexeddb/auto — этот полифилл чисто в памяти, поэтому:

    • Ключи существуют только в памяти процесса, MATRIX_CRYPTO_DB в этой версии не создаёт реальный файл SQLite на диске; после перезапуска процесса ключи нужно пересогласовывать (не влияет на приём/отправку, просто требуется повторная пересылка ключей/проверка устройств).

    • Настоящее дисковое хранение требует обновления до версии matrix-js-sdk с нативным бэкендом @matrix-org/matrix-sdk-crypto-nodejs или будущей версии с поддержкой nodejs-входа (тогда можно убрать полифилл fake-indexeddb и использовать нативный бэкенд).

    • Обратите внимание: установленный в зависимостях @matrix-org/matrix-sdk-crypto-nodejs в текущей версии 42.2.0 не вызывается SDK, он лишь запасной вариант для будущего обновления; сейчас шифрование работает через wasm + полифилл fake-indexeddb в памяти.

  • При первом входе нового устройства в зашифрованную комнату рекомендуется проверить устройство этого бота в Matrix-клиенте (иначе собеседник может видеть предупреждение «непроверенное устройство», но сообщения всё равно будут приниматься/отправляться).

• Медиа: по умолчанию в сессию передаётся только текст сообщения; при включении MATRIX_DOWNLOAD_MEDIA изображения/файлы скачиваются локально и вставляются как [file: путь], чтобы агент мог их прочитать.

• Ретрансляция разрешений зависит от возможности claude/channel/permission в CodeBuddy; если версия CodeBuddy не поддерживает её, основной мост чата не затрагивается.

7. Цифровой аватар: модель авторизации владельца (основной сценарий)

Воспринимайте аватара как «коллегу в группе», которого можно свободно @упоминать для поручений, но он не изменит ничего по-настоящему, пока владелец не согласится.

Сценарий

• Коллеги создают несколько групп (например, #ПроектA, #Поддержка), в группах может быть несколько ботов-аватаров. Коллеги в группе @упоминают вашего аватара для поручений; он отвечает только при @упоминании (в личке отвечает всегда).

• После получения поручения:

  • Обычные / авторизованные задачи (от ваших предустановленных 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 = стратегический мозг (семантическое суждение, передаётся агенту): skills/matrix-avatar/SKILL.md направляет аватара в определении «обычное vs незнакомое», при незнакомом переходит в режим плана и вызывает request_approval. Агент только запрашивает одобрение, никогда не разрешает сам; разрешение исходит только из «предустановленных доверенных источников владельца» или «approve владельца».

Встроенные channel instructions плагина уже содержат эту стратегию, поэтому работа возможна и без дополнительной установки SKILL; skills/matrix-avatar/SKILL.md предоставляется для повторного использования/настройки в CodeBuddy.

Три уровня состояния задач (по комнатам)

Команды контрольной комнаты (действуют только для владельца 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 можно запустить самопроверку для подтверждения конфигурации, связи и состояния E2EE, а затем запустить CodeBuddy:

npm run doctor

Самопроверка выводит текущую конфигурацию (токен маскируется), проверяет доступность homeserver и действительность учётных данных, а при MATRIX_E2EE=true пытается инициализировать Rust crypto. Любая ошибка даёт явную причину и завершается ненулевым кодом выхода.

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