codebuddy-matrix-channel

Un plugin de canal (servidor MCP) que conecta Matrix por chat con las sesiones locales de CodeBuddy Code.

El efecto es equivalente a los canales integrados de Telegram / Discord / WeChat de CodeBuddy:

• Enviar un mensaje en una sala de Matrix → aparece en la sesión de CodeBuddy como #matrix · @alice:matrix.org: hola

• Las respuestas de CodeBuddy se envían de vuelta a la sala de Matrix mediante la herramienta reply

• Opcional: reenviar las solicitudes de permiso de CodeBuddy a la "sala de control" para aprobar/rechazar llamadas de herramientas desde el móvil

Este plugin se basa en el mecanismo de extensión Channel de CodeBuddy (ver docs/cn/cli/channels.md y channels-reference.md), sin necesidad de modificar CodeBuddy en sí.

1. Cómo funciona

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

El plugin se inicia como subproceso por CodeBuddy mediante stdio y se comunica a través del protocolo MCP.

Related MCP server: mcacp

2. Instalación

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

Se requiere Node >= 20 en tiempo de ejecución.

2.1 Inicio rápido (avatar digital)

1. Instalar / compilar

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

2. Rellenar .env (conjunto mínimo viable, ver sección 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. Autocomprobación (ejecutar cada vez que se modifique .env)

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

4. Conectar con CodeBuddy: registrar en el .mcp.json del proyecto (ruta absoluta) y luego iniciar

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

5. Uso diario

   • @mencionar al avatar en el grupo para asignar tareas → las fuentes de confianza/trabajos autorizados se ejecutan automáticamente; los trabajos desconocidos primero generan un plan y entran en la sala de control esperando tu approve.

   • Las herramientas de alto riesgo (Bash/escritura de archivos, etc.) siempre requieren tu aprobación en la sala de control.

   • Tú das órdenes en la sala de control (solo se reconoce MATRIX_OWNER_ID):

     • approve (run / go, puede ir seguido del ID de sala) → autoriza la tarea de esa sala

     • yes <id> / no <id> → aprobar / rechazar las solicitudes de permiso de alto riesgo en espera

Para grupos cifrados se necesita MATRIX_E2EE=true; si MATRIX_DEVICE_ID se deja vacío, se seleccionará automáticamente desde /devices; si da error, rellena el ID de dispositivo de «Configuración → Dispositivos».

3. Configuración

Copia .env.example como .env y rellénalo:

cp .env.example .env

⚠️ Seguridad: configura obligatoriamente MATRIX_ALLOWLIST (se valida por remitente, no por sala, para evitar que cualquier miembro del grupo inyecte contenido en la sesión). Dejarlo vacío permite a todos, solo para pruebas locales.

4. Conexión con CodeBuddy

Método A: período de desarrollo (omitiendo la lista blanca del mercado)

Registra este plugin en el .mcp.json de tu proyecto CodeBuddy:

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

Luego inicia CodeBuddy:

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

Tras compilar, se puede ejecutar con node cambiando a:

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

Método B: empaquetar como plugin (tras enviarlo al mercado oficial)

npm run build

Luego publica codebuddy-matrix-channel como plugin y úsalo con:

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

5. Uso

1. Tras iniciar, envía un mensaje en una sala de Matrix permitida y aparecerá #matrix · @tú: ... en la sesión de CodeBuddy

2. Cuando CodeBuddy termine de procesar, la respuesta aparecerá en la sala de Matrix

3. Si se ha configurado MATRIX_CONTROL_ROOM_ID: cuando CodeBuddy llame a herramientas que requieren aprobación (Bash / Write, etc.), la sala de control recibirá un aviso (enviado como notificación de sistema m.notice, sin activar no leídos/alertas); responde yes <id> para permitir / no <id> para rechazar

Parámetros de la herramienta reply

Por ejemplo, haz que CodeBuddy responda con una nota de estado usando m.notice: reply({ chat_id: "!abc:server", text: "procesado", msgtype: "m.notice" }).

Herramienta health_check

Se puede invocar directamente en la sesión de CodeBuddy, o activarla en la comprobación de salud de /mcp; equivale a la parte de conectividad/E2EE de npm run doctor y devuelve JSON:

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

Cuando ok=false se incluye el campo error explicando el motivo del fallo (conexión/autenticación/inicialización E2EE).

6. Limitaciones y notas

• Salas con cifrado de extremo a extremo (E2EE): por defecto solo se admiten salas sin cifrar. Para conectar salas cifradas, pon MATRIX_E2EE=true; el plugin reutiliza el crypto Rust integrado de matrix-js-sdk (initRustCrypto), y el SDK se encarga automáticamente de «descifrar al recibir, cifrar al enviar» — no es necesario implementar el protocolo de cifrado. Al activarlo:

  • Los mensajes cifrados llegan como m.room.encrypted; tras ser descifrados por el SDK (evento Event.decrypted), el tipo cambia al real y el plugin los envía a la sesión;

  • Las respuestas enviadas a salas cifradas son cifradas automáticamente por el SDK;

  • Almacenamiento de claves (importante, depende de la versión): en matrix-js-sdk 42.x, el backend crypto Rust solo tiene una implementación wasm/IndexedDB (@matrix-org/matrix-sdk-crypto-wasm), sin backend nativo de Node. Para que funcione en Node, el plugin inyecta un shim global indexedDB en Node al iniciar usando fake-indexeddb/auto — este shim es puramente en memoria, por lo tanto:

    • Las claves solo existen realmente en la memoria del proceso; MATRIX_CRYPTO_DB no generará un archivo SQLite real en disco en esta versión; tras reiniciar el proceso, las claves deben renegociarse (no afecta al envío/recepción, solo requiere rehacer el reenvío de claves/verificación de dispositivos).

    • La persistencia real en disco requiere actualizar a una versión de matrix-js-sdk que incluya el backend nativo @matrix-org/matrix-sdk-crypto-nodejs, o una versión futura que admita la entrada nodejs (en ese caso, se elimina el shim fake-indexeddb y se usa el backend nativo).

    • Nota: el @matrix-org/matrix-sdk-crypto-nodejs ya instalado en las dependencias no es invocado por el SDK en la versión actual 42.2.0; solo sirve como alternativa para futuras actualizaciones; el núcleo de cifrado actual funciona con wasm + el shim de memoria fake-indexeddb.

  • Cuando un dispositivo nuevo entra por primera vez en una sala cifrada, se recomienda verificar el dispositivo de este bot en el cliente de Matrix (de lo contrario, la otra parte podría ver el aviso de "dispositivo no verificado", aunque los mensajes seguirán enviándose y recibiéndose con normalidad).

• Medios: por defecto solo se conecta el texto del mensaje a la sesión; al activar MATRIX_DOWNLOAD_MEDIA, las imágenes/archivos se descargan localmente y se inyectan como [file: ruta], para que el Agente pueda leerlos.

• Relevo de permisos: depende de la capacidad claude/channel/permission de CodeBuddy; si la versión de CodeBuddy no la admite, el puente de chat principal no se ve afectado.

7. Avatar digital: modelo de autorización del administrador (escenario principal)

Trata al avatar como un «colega en el grupo»: se le puede asignar trabajo con @ libremente, pero no modificará nada realmente sin el consentimiento del administrador.

Escenario

• Los colegas crean varios grupos (p. ej. #ProyectoA, #Atención al cliente), donde puede haber varios bots avatar simultáneamente. Los colegas @mencionan a tu avatar en el grupo para asignar trabajo; solo responde cuando es @mencionado (en mensajes directos siempre responde).

• Al recibir una asignación:

  • Trabajo habitual / autorizado (de MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS preconfigurados, o dentro del ámbito descrito en MATRIX_AUTHORIZED_WORK) → ejecución automática (herramientas seguras).

  • Trabajo desconocido (fuera del ámbito autorizado) → el avatar primero genera un plan, llama a request_approval para escalarlo a tu sala de control; solo se ejecuta cuando respondes approve.

  • Operaciones de alto riesgo (MATRIX_HIGH_RISK_TOOLS, como Bash / escritura de archivos) → independientemente del origen, siempre requieren tu aprobación.

Arquitectura en capas

• Plugin MCP = transporte seguro + compuerta dura (impuesta por código, no se confía en el modelo): el filtro de @, la decisión de permisos allow/deny se basan únicamente en hechos verificables (si es owner, si es fuente de confianza, si es herramienta de alto riesgo), y la aprobación en la sala de control solo reconoce MATRIX_OWNER_ID.

• SKILL = cerebro de políticas (juicio semántico, delegado al Agente): skills/matrix-avatar/SKILL.md guía al avatar para juzgar «habitual vs desconocido»; cuando es desconocido, entra en modo plan y llama a request_approval. El Agente solo solicita aprobación, nunca se autoautoriza; la autorización solo proviene de «los ajustes de fuentes de confianza del administrador» o del approve del administrador.

Las instructions del canal integradas en el plugin ya incluyen esta política, por lo que funciona sin instalar el SKILL adicionalmente; skills/matrix-avatar/SKILL.md está disponible para que lo reutilices/ajustes en CodeBuddy.

Estados de tarea en tres niveles (por sala)

Comandos de la sala de control (solo válidos para el administrador MATRIX_OWNER_ID)

• approve (o run / go, opcionalmente seguido del ID de sala, p. ej. approve !projectA:server) → autoriza la tarea actual de esa sala y el avatar comienza a ejecutarla.

• yes <id> / no <id> → aprobar / rechazar las solicitudes de permiso de alto riesgo en espera.

• Las respuestas de otras personas en la sala de control se ignoran.

Ejemplo de configuración (.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. Autocomprobación (doctor)

Tras rellenar .env, puedes ejecutar la autocomprobación para confirmar la configuración, la conectividad y el estado E2EE antes de iniciar CodeBuddy:

npm run doctor

La autocomprobación imprime la configuración actual (token enmascarado), verifica que el homeserver sea accesible y que las credenciales sean válidas, e intenta inicializar el crypto Rust cuando MATRIX_E2EE=true. Si falla cualquier elemento, se indica claramente el motivo y se termina con código de salida distinto de 0.

9. Estructura de directorios

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