チャネル表示のリファクタリング計画

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ステータス

• ReplyPayload.presentation はセマンティックなメッセージ UI を保持する。
• ReplyPayload.delivery.pin は送信済みメッセージのピン留めリクエストを保持する。
• 共有メッセージアクションは、プロバイダー固有の components、blocks、buttons、card ではなく、presentation、delivery、pin を公開する。
• コアは、Plugin が宣言したアウトバウンド機能を通じて presentation をレンダリングするか、自動的に代替表現へフォールバックする。
• Discord、Slack、Telegram、Mattermost、MS Teams、Feishu のレンダラーは汎用契約を使用する。
• Discord チャネルの制御プレーンコードは、Carbon ベースの UI コンテナーをインポートしなくなった。

​

問題

• コアは buildCrossContextComponents を通じて、Discord 形状のクロスコンテキストレンダラーフックを所有している。
• Discord の channel.ts は DiscordUiContainer を通じてネイティブ Carbon UI をインポートできるため、実行時 UI 依存関係がチャネル Plugin の制御プレーンに入り込む。
• エージェントと CLI は、Discord の components、Slack の blocks、Telegram または Mattermost の buttons、Teams または Feishu の card などのネイティブペイロード回避口を公開している。
• ReplyPayload.channelData は、トランスポートヒントとネイティブ UI エンベロープの両方を保持している。
• 汎用の interactive モデルは存在するが、Discord、Slack、Teams、Feishu、LINE、Telegram、Mattermost ですでに使われているよりリッチなレイアウトより狭い。

​

目標

• コアは、宣言された機能からメッセージに最適なセマンティック presentation を決定する。
• 拡張は機能を宣言し、セマンティック presentation をネイティブトランスポートペイロードにレンダリングする。
• Web Control UI はチャットネイティブ UI から分離したままにする。
• ネイティブチャネルペイロードは、共有エージェントまたは CLI メッセージサーフェスを通じて公開しない。
• サポートされていない presentation 機能は、最適なテキスト表現へ自動的にフォールバックする。
• 送信済みメッセージのピン留めなどの配信動作は、presentation ではなく汎用配信メタデータである。

​

非目標

• buildCrossContextComponents の後方互換 shim は作らない。
• components、blocks、buttons、card の公開ネイティブ回避口は作らない。
• コアはチャネルネイティブ UI ライブラリをインポートしない。
• バンドル済みチャネル向けのプロバイダー固有 SDK シームは作らない。

​

目標モデル

type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger";

type MessagePresentation = {
  tone?: MessagePresentationTone;
  title?: string;
  blocks: MessagePresentationBlock[];
};

type MessagePresentationBlock =
  | { type: "text"; text: string }
  | { type: "context"; text: string }
  | { type: "divider" }
  | { type: "buttons"; buttons: MessagePresentationButton[] }
  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };

type MessagePresentationButton = {
  label: string;
  value?: string;
  url?: string;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  value: string;
};

• interactive テキストブロックは presentation.blocks[].type = "text" にマップされる。
• interactive ボタンブロックは presentation.blocks[].type = "buttons" にマップされる。
• interactive セレクトブロックは presentation.blocks[].type = "select" にマップされる。

​

配信メタデータ

type ReplyPayloadDelivery = {
  pin?:
    | boolean
    | {
        enabled: boolean;
        notify?: boolean;
        required?: boolean;
      };
};

• delivery.pin = true は、最初に正常配信されたメッセージをピン留めすることを意味する。
• notify のデフォルトは false。
• required のデフォルトは false。サポートされていないチャネルやピン留め失敗は、配信を継続することで自動的に代替動作へフォールバックする。
• 手動の pin、unpin、list-pins メッセージアクションは既存メッセージ用に残る。

​

実行時機能契約

type ChannelPresentationCapabilities = {
  supported: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  tones?: MessagePresentationTone[];
};

type ChannelDeliveryCapabilities = {
  pinSentMessage?: boolean;
};

type ChannelOutboundAdapter = {
  presentationCapabilities?: ChannelPresentationCapabilities;

  renderPresentation?: (params: {
    payload: ReplyPayload;
    presentation: MessagePresentation;
    ctx: ChannelOutboundSendContext;
  }) => ReplyPayload | null;

  deliveryCapabilities?: ChannelDeliveryCapabilities;

  pinDeliveredMessage?: (params: {
    cfg: OpenClawConfig;
    accountId?: string | null;
    to: string;
    threadId?: string | number | null;
    messageId: string;
    notify: boolean;
  }) => Promise<void>;
};

• 対象チャネルと実行時アダプターを解決する。
• presentation 機能を問い合わせる。
• レンダリング前にサポートされていないブロックを劣化させる。
• renderPresentation を呼び出す。
• レンダラーが存在しない場合、presentation をテキストフォールバックに変換する。
• 送信成功後、delivery.pin がリクエストされサポートされている場合は pinDeliveredMessage を呼び出す。

​

チャネルマッピング

• presentation をコンポーネント v2 と Carbon コンテナーへ、実行時専用モジュールでレンダリングする。
• アクセントカラーヘルパーは軽量モジュールに保持する。
• チャネル Plugin 制御プレーンコードから DiscordUiContainer のインポートを削除する。

• presentation を Block Kit にレンダリングする。
• エージェントと CLI の blocks 入力を削除する。

• テキスト、コンテキスト、区切り線をテキストとしてレンダリングする。
• ターゲットサーフェスで設定され許可されている場合、アクションとセレクトをインラインキーボードとしてレンダリングする。
• インラインボタンが無効な場合はテキストフォールバックを使用する。
• ACP トピックのピン留めを delivery.pin に移す。

• 設定されている場合、アクションをインタラクティブボタンとしてレンダリングする。
• その他のブロックはテキストフォールバックとしてレンダリングする。

• presentation を Adaptive Cards にレンダリングする。
• 手動の pin/unpin/list-pins アクションを保持する。
• 対象会話で Graph サポートが信頼できる場合は、任意で pinDeliveredMessage を実装する。

• presentation をインタラクティブカードにレンダリングする。
• 手動の pin/unpin/list-pins アクションを保持する。
• API 動作が信頼できる場合は、送信済みメッセージのピン留め向けに任意で pinDeliveredMessage を実装する。

• 可能な場合、presentation を Flex またはテンプレートメッセージにレンダリングする。
• サポートされていないブロックはテキストにフォールバックする。
• LINE UI ペイロードを channelData から削除する。

• presentation を保守的な書式のテキストに変換する。

​

リファクタリング手順

1. ui-colors.ts を Carbon ベース UI から分離し、extensions/discord/src/channel.ts から DiscordUiContainer を削除する Discord リリース修正を再適用する。
2. ReplyPayload、アウトバウンドペイロード正規化、配信サマリー、フックペイロードに presentation と delivery を追加する。
3. 狭い SDK/実行時サブパスに MessagePresentation スキーマとパーサーヘルパーを追加する。
4. メッセージ機能の buttons、cards、components、blocks をセマンティック presentation 機能に置き換える。
5. presentation レンダリングと delivery ピン留め用の実行時アウトバウンドアダプターフックを追加する。
6. クロスコンテキストコンポーネント構築を buildCrossContextPresentation に置き換える。
7. src/infra/outbound/channel-adapters.ts を削除し、チャネル Plugin 型から buildCrossContextComponents を削除する。
8. maybeApplyCrossContextMarker を変更し、ネイティブパラメーターではなく presentation をアタッチする。
9. Plugin ディスパッチ送信パスを更新し、セマンティック presentation と delivery メタデータのみを使用する。
10. エージェントと CLI のネイティブペイロードパラメーター components、blocks、buttons、card を削除する。
11. ネイティブメッセージツールスキーマを作成する SDK ヘルパーを削除し、presentation スキーマヘルパーに置き換える。
12. UI/ネイティブエンベロープを channelData から削除する。残る各フィールドがレビューされるまでは、トランスポートメタデータのみを保持する。
13. Discord、Slack、Telegram、Mattermost、MS Teams、Feishu、LINE のレンダラーを移行する。
14. メッセージ CLI、チャネルページ、Plugin SDK、機能クックブックのドキュメントを更新する。
15. Discord と影響を受けるチャネルエントリーポイントのインポートファンアウトプロファイリングを実行する。

​

テスト

• presentation 正規化テスト。
• サポートされていないブロック向けの presentation 自動劣化テスト。
• Plugin ディスパッチとコア配信パスのクロスコンテキストマーカーテスト。
• Discord、Slack、Telegram、Mattermost、MS Teams、Feishu、LINE、テキストフォールバックのチャネルレンダリングマトリクステスト。
• ネイティブフィールドがなくなったことを証明するメッセージツールスキーマテスト。
• ネイティブフラグがなくなったことを証明する CLI テスト。
• Carbon を対象にした Discord エントリーポイントのインポート遅延性回帰テスト。
• Telegram と汎用フォールバックを対象にした delivery ピン留めテスト。

​

未解決の質問

• delivery.pin は初回パスで Discord、Slack、MS Teams、Feishu にも実装すべきか、それともまず Telegram のみにすべきか。
• delivery は最終的に replyToId、replyToCurrent、silent、audioAsVoice などの既存フィールドも吸収すべきか、それとも送信後の動作に集中したままにすべきか。
• presentation は画像やファイル参照を直接サポートすべきか、それとも当面はメディアを UI レイアウトから分離したままにすべきか。

​

関連

• チャネル概要
• メッセージ presentation