codebuddy-matrix-channel

把 Matrix 聊天桥接到 CodeBuddy Code 本地会话的 Channel 插件（MCP 服务器）。

效果等同于 CodeBuddy 内置的 Telegram / Discord / 微信 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。同事在群里 @你的分身 派活；只在被 @ 时才响应（直接私聊总响应）。

• 收到派活后：

  • 常用 / 已授权工作（来自你预设的 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 中复用/微调。

三层任务状态（按房间）

控制室命令（仅管理者 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

自检会打印当前配置（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