Rencana refaktor presentasi saluran

# Status

Diimplementasikan untuk agen bersama, CLI, kemampuan Plugin, dan permukaan pengiriman keluar:

• ReplyPayload.presentation membawa UI pesan semantik.
• ReplyPayload.delivery.pin membawa permintaan penyematan pesan terkirim.
• Aksi pesan bersama mengekspos presentation, delivery, dan pin, bukan components, blocks, buttons, atau card native penyedia.
• Inti merender atau menurunkan otomatis presentasi melalui kemampuan keluar yang dideklarasikan Plugin.
• Perender Discord, Slack, Telegram, Mattermost, MS Teams, dan Feishu memakai kontrak generik.
• Kode bidang kontrol saluran Discord tidak lagi mengimpor kontainer UI yang didukung Carbon.

Dokumentasi kanonis sekarang berada di Presentasi Pesan. Simpan rencana ini sebagai konteks implementasi historis; perbarui panduan kanonis untuk perubahan kontrak, perender, atau perilaku fallback.

# Masalah

UI saluran saat ini terbagi di beberapa permukaan yang tidak kompatibel:

• Inti memiliki hook perender lintas-konteks berbentuk Discord melalui buildCrossContextComponents.
• channel.ts Discord dapat mengimpor UI Carbon native melalui DiscordUiContainer, yang menarik dependensi UI runtime ke bidang kontrol Plugin saluran.
• Agen dan CLI mengekspos celah keluar payload native seperti components Discord, blocks Slack, buttons Telegram atau Mattermost, dan card Teams atau Feishu.
• ReplyPayload.channelData membawa petunjuk transport dan amplop UI native.
• Model interactive generik sudah ada, tetapi lebih sempit daripada tata letak yang lebih kaya yang sudah digunakan oleh Discord, Slack, Teams, Feishu, LINE, Telegram, dan Mattermost.

Ini membuat inti menyadari bentuk UI native, melemahkan kelambatan runtime Plugin, dan memberi agen terlalu banyak cara khusus penyedia untuk mengekspresikan maksud pesan yang sama.

# Tujuan

• Inti menentukan presentasi semantik terbaik untuk sebuah pesan dari kemampuan yang dideklarasikan.
• Ekstensi mendeklarasikan kemampuan dan merender presentasi semantik menjadi payload transport native.
• UI Kontrol Web tetap terpisah dari UI native obrolan.
• Payload saluran native tidak diekspos melalui permukaan pesan agen bersama atau CLI.
• Fitur presentasi yang tidak didukung otomatis diturunkan ke representasi teks terbaik.
• Perilaku pengiriman seperti menyematkan pesan terkirim adalah metadata pengiriman generik, bukan presentasi.

# Bukan tujuan

• Tidak ada shim kompatibilitas mundur untuk buildCrossContextComponents.
• Tidak ada celah keluar native publik untuk components, blocks, buttons, atau card.
• Tidak ada impor inti dari pustaka UI native saluran.
• Tidak ada seam SDK khusus penyedia untuk saluran bawaan.

# Model target

Tambahkan field presentation milik inti ke ReplyPayload.

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 menjadi subset dari presentation selama migrasi:

• Blok teks interactive dipetakan ke presentation.blocks[].type = "text".
• Blok tombol interactive dipetakan ke presentation.blocks[].type = "buttons".
• Blok pilihan interactive dipetakan ke presentation.blocks[].type = "select".

Skema agen eksternal dan CLI sekarang menggunakan presentation; interactive tetap menjadi helper parser/perender legacy internal untuk produsen balasan yang sudah ada.

# Metadata pengiriman

Tambahkan field delivery milik inti untuk perilaku kirim yang bukan UI.

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

Semantik:

• delivery.pin = true berarti sematkan pesan pertama yang berhasil dikirim.
• notify default ke false.
• required default ke false; saluran yang tidak didukung atau kegagalan penyematan otomatis diturunkan dengan melanjutkan pengiriman.
• Aksi pesan manual pin, unpin, dan list-pins tetap ada untuk pesan yang sudah ada.

Pengikatan topik ACP Telegram saat ini harus dipindahkan dari channelData.telegram.pin = true ke delivery.pin = true.

# Kontrak kemampuan runtime

Tambahkan hook perender presentasi dan pengiriman ke adaptor keluar runtime, bukan Plugin saluran bidang kontrol.

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>;
};

Perilaku inti:

• Selesaikan saluran target dan adaptor runtime.
• Minta kemampuan presentasi.
• Turunkan blok yang tidak didukung sebelum merender.
• Panggil renderPresentation.
• Jika tidak ada perender, konversi presentasi menjadi fallback teks.
• Setelah pengiriman berhasil, panggil pinDeliveredMessage saat delivery.pin diminta dan didukung.

# Pemetaan saluran

Discord:

• Render presentation ke komponen v2 dan kontainer Carbon di modul khusus runtime.
• Simpan helper warna aksen di modul ringan.
• Hapus impor DiscordUiContainer dari kode bidang kontrol Plugin saluran.

Slack:

• Render presentation ke Block Kit.
• Hapus input blocks agen dan CLI.

Telegram:

• Render teks, konteks, dan pembatas sebagai teks.
• Render aksi dan pilihan sebagai papan tombol inline saat dikonfigurasi dan diizinkan untuk permukaan target.
• Gunakan fallback teks saat tombol inline dinonaktifkan.
• Pindahkan penyematan topik ACP ke delivery.pin.

Mattermost:

• Render aksi sebagai tombol interaktif saat dikonfigurasi.
• Render blok lain sebagai fallback teks.

MS Teams:

• Render presentation ke Adaptive Cards.
• Pertahankan aksi manual pin/unpin/list-pins.
• Secara opsional implementasikan pinDeliveredMessage jika dukungan Graph andal untuk percakapan target.

Feishu:

• Render presentation ke kartu interaktif.
• Pertahankan aksi manual pin/unpin/list-pins.
• Secara opsional implementasikan pinDeliveredMessage untuk penyematan pesan terkirim jika perilaku API andal.

LINE:

• Render presentation ke pesan Flex atau templat jika memungkinkan.
• Gunakan fallback ke teks untuk blok yang tidak didukung.
• Hapus payload UI LINE dari channelData.

Saluran polos atau terbatas:

• Konversi presentasi menjadi teks dengan pemformatan konservatif.

# Langkah refaktor

1. Terapkan ulang perbaikan rilis Discord yang memisahkan ui-colors.ts dari UI yang didukung Carbon dan menghapus DiscordUiContainer dari extensions/discord/src/channel.ts.
2. Tambahkan presentation dan delivery ke ReplyPayload, normalisasi payload keluar, ringkasan pengiriman, dan payload hook.
3. Tambahkan skema MessagePresentation dan helper parser di subpath SDK/runtime yang sempit.
4. Ganti kemampuan pesan buttons, cards, components, dan blocks dengan kemampuan presentasi semantik.
5. Tambahkan hook adaptor keluar runtime untuk perender presentasi dan penyematan pengiriman.
6. Ganti konstruksi komponen lintas-konteks dengan buildCrossContextPresentation.
7. Hapus src/infra/outbound/channel-adapters.ts dan hapus buildCrossContextComponents dari tipe Plugin saluran.
8. Ubah maybeApplyCrossContextMarker agar melampirkan presentation, bukan parameter native.
9. Perbarui jalur kirim plugin-dispatch agar hanya memakai presentasi semantik dan metadata pengiriman.
10. Hapus parameter payload native agen dan CLI: components, blocks, buttons, dan card.
11. Hapus helper SDK yang membuat skema alat pesan native, dan gantikan dengan helper skema presentasi.
12. Hapus amplop UI/native dari channelData; simpan hanya metadata transport hingga setiap field tersisa ditinjau.
13. Migrasikan perender Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, dan LINE.
14. Perbarui dokumentasi untuk CLI pesan, halaman saluran, SDK Plugin, dan cookbook kemampuan.
15. Jalankan profiling fanout impor untuk Discord dan entrypoint saluran yang terdampak.

Langkah 1-11 dan 13-14 diimplementasikan dalam refaktor ini untuk kontrak agen bersama, CLI, kemampuan Plugin, dan adaptor keluar. Langkah 12 tetap menjadi tahap pembersihan internal yang lebih dalam untuk amplop transport channelData privat penyedia. Langkah 15 tetap menjadi validasi lanjutan jika kita menginginkan angka fanout impor terkuantifikasi di luar gate tipe/tes.

# Tes

Tambahkan atau perbarui:

• Tes normalisasi presentasi.
• Tes penurunan otomatis presentasi untuk blok yang tidak didukung.
• Tes penanda lintas-konteks untuk plugin dispatch dan jalur pengiriman inti.
• Tes matriks perender saluran untuk Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE, dan fallback teks.
• Tes skema alat pesan yang membuktikan field native sudah hilang.
• Tes CLI yang membuktikan flag native sudah hilang.
• Regresi kelambatan impor entrypoint Discord yang mencakup Carbon.
• Tes penyematan pengiriman yang mencakup Telegram dan fallback generik.

# Pertanyaan terbuka

• Haruskah delivery.pin diimplementasikan untuk Discord, Slack, MS Teams, dan Feishu pada tahap pertama, atau hanya Telegram terlebih dahulu?
• Haruskah delivery pada akhirnya menyerap field yang sudah ada seperti replyToId, replyToCurrent, silent, dan audioAsVoice, atau tetap berfokus pada perilaku pascakirim?
• Haruskah presentasi mendukung gambar atau referensi file secara langsung, atau media harus tetap terpisah dari tata letak UI untuk saat ini?

# Terkait

• Ikhtisar saluran
• Presentasi pesan