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 が存在する場合があります。同僚はグループで @あなたのアバター に仕事を依頼します；@ された時のみ応答します（直接 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

セルフチェックは現在の設定（トークンはマスク表示）を出力し、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