Trình bày tin nhắn

• các phần văn bản
• văn bản ngữ cảnh/chân trang nhỏ
• đường phân cách
• nút
• menu chọn
• tiêu đề và sắc thái thẻ

​

Hợp đồng

import type {
  MessagePresentation,
  ReplyPayloadDelivery,
} from "openclaw/plugin-sdk/interactive-runtime";

type MessagePresentation = {
  title?: string;
  tone?: "neutral" | "info" | "success" | "warning" | "danger";
  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 MessagePresentationAction =
  | { type: "command"; command: string }
  | { type: "callback"; value: string };

type MessagePresentationButton = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
  url?: string;
  webApp?: { url: string };
  /** @deprecated Use webApp. Accepted for legacy JSON payloads only. */
  web_app?: { url: string };
  priority?: number;
  disabled?: boolean;
  reusable?: boolean;
  style?: "primary" | "secondary" | "success" | "danger";
};

type MessagePresentationOption = {
  label: string;
  action?: MessagePresentationAction;
  /** Legacy callback value. Prefer action for new controls. */
  value?: string;
};

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

• action.type: "command" chạy một lệnh slash gốc thông qua đường dẫn lệnh của lõi. Dùng mục này cho các nút và menu lệnh tích hợp.
• action.type: "callback" mang dữ liệu Plugin mờ thông qua đường dẫn tương tác của kênh. Plugin kênh không được diễn giải lại dữ liệu callback thành lệnh slash.
• value là giá trị callback mờ cũ. Các điều khiển mới nên dùng action để Plugin kênh có thể ánh xạ lệnh và callback mà không phải đoán từ văn bản.
• url là nút liên kết. Nó có thể tồn tại mà không có value.
• webApp mô tả nút ứng dụng web gốc của kênh. Telegram kết xuất mục này dưới dạng web_app và chỉ hỗ trợ trong cuộc trò chuyện riêng tư. web_app vẫn được chấp nhận trong payload JSON lỏng để tương thích, nhưng producer TypeScript nên dùng webApp.
• label là bắt buộc và cũng được dùng trong dự phòng văn bản.
• style mang tính gợi ý. Bộ kết xuất nên ánh xạ các kiểu không được hỗ trợ sang mặc định an toàn, không làm gửi thất bại.
• priority là tùy chọn. Khi một kênh quảng bá giới hạn hành động và phải loại bỏ điều khiển, lõi giữ các nút có độ ưu tiên cao hơn trước và giữ nguyên thứ tự ban đầu giữa các nút có cùng độ ưu tiên. Khi tất cả điều khiển đều vừa, thứ tự do tác giả đặt được giữ nguyên.
• disabled là tùy chọn. Kênh phải chọn tham gia bằng supportsDisabled; nếu không lõi hạ cấp điều khiển bị vô hiệu hóa thành văn bản dự phòng không tương tác.
• reusable là tùy chọn. Các kênh hỗ trợ callback gốc có thể tái sử dụng có thể giữ hành động khả dụng sau một tương tác thành công. Dùng nó cho các hành động lặp lại hoặc bất biến như làm mới, kiểm tra, hoặc thêm chi tiết; để trống cho các phê duyệt dùng một lần thông thường và hành động phá hủy.

• options[].action có cùng ý nghĩa lệnh/callback như action của nút.
• options[].value là giá trị ứng dụng được chọn kiểu cũ.
• placeholder mang tính gợi ý và có thể bị các kênh không hỗ trợ chọn gốc bỏ qua.
• Nếu một kênh không hỗ trợ menu chọn, văn bản dự phòng sẽ liệt kê các nhãn.

​

Ví dụ producer

{
  "title": "Deploy approval",
  "tone": "warning",
  "blocks": [
    { "type": "text", "text": "Canary is ready to promote." },
    { "type": "context", "text": "Build 1234, staging passed." },
    {
      "type": "buttons",
      "buttons": [
        { "label": "Approve", "value": "deploy:approve", "style": "success" },
        { "label": "Decline", "value": "deploy:decline", "style": "danger" }
      ]
    }
  ]
}

{
  "blocks": [
    { "type": "text", "text": "Release notes are ready." },
    {
      "type": "buttons",
      "buttons": [{ "label": "Open notes", "url": "https://example.com/release" }]
    }
  ]
}

{
  "blocks": [
    {
      "type": "buttons",
      "buttons": [{ "label": "Launch", "web_app": { "url": "https://example.com/app" } }]
    }
  ]
}

{
  "title": "Choose environment",
  "blocks": [
    {
      "type": "select",
      "placeholder": "Environment",
      "options": [
        { "label": "Canary", "value": "env:canary" },
        { "label": "Production", "value": "env:prod" }
      ]
    }
  ]
}

openclaw message send --channel slack \
  --target channel:C123 \
  --message "Deploy approval" \
  --presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Canary is ready."},{"type":"buttons","buttons":[{"label":"Approve","value":"deploy:approve","style":"success"},{"label":"Decline","value":"deploy:decline","style":"danger"}]}]}'

openclaw message send --channel telegram \
  --target -1001234567890 \
  --message "Topic opened" \
  --pin

{
  "pin": {
    "enabled": true,
    "notify": true,
    "required": false
  }
}

​

Hợp đồng bộ kết xuất

const adapter: ChannelOutboundAdapter = {
  deliveryMode: "direct",
  presentationCapabilities: {
    supported: true,
    buttons: true,
    selects: true,
    context: true,
    divider: true,
    limits: {
      actions: {
        maxActions: 25,
        maxActionsPerRow: 5,
        maxRows: 5,
        maxLabelLength: 80,
        maxValueBytes: 100,
        supportsStyles: true,
        supportsDisabled: false,
      },
      selects: {
        maxOptions: 25,
        maxLabelLength: 100,
        maxValueBytes: 100,
      },
      text: {
        maxLength: 2000,
        encoding: "characters",
        markdownDialect: "discord-markdown",
      },
    },
  },
  deliveryCapabilities: {
    pin: true,
  },
  renderPresentation({ payload, presentation, ctx }) {
    return renderNativePayload(payload, presentation, ctx);
  },
  async pinDeliveredMessage({ target, messageId, pin }) {
    await pinNativeMessage(target, messageId, { notify: pin.notify === true });
  },
};

type ChannelPresentationCapabilities = {
  supported?: boolean;
  buttons?: boolean;
  selects?: boolean;
  context?: boolean;
  divider?: boolean;
  limits?: {
    actions?: {
      maxActions?: number;
      maxActionsPerRow?: number;
      maxRows?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
      supportsStyles?: boolean;
      supportsDisabled?: boolean;
      supportsLayoutHints?: boolean;
    };
    selects?: {
      maxOptions?: number;
      maxLabelLength?: number;
      maxValueBytes?: number;
    };
    text?: {
      maxLength?: number;
      encoding?: "characters" | "utf8-bytes" | "utf16-units";
      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
      supportsEdit?: boolean;
    };
  };
};

​

Luồng kết xuất lõi

1. Chuẩn hóa payload trình bày.
2. Phân giải adapter gửi đi của kênh đích.
3. Đọc presentationCapabilities.
4. Áp dụng các giới hạn năng lực chung như số lượng hành động, độ dài nhãn và số lượng tùy chọn chọn khi adapter quảng bá chúng.
5. Gọi renderPresentation khi adapter có thể kết xuất payload.
6. Dự phòng về văn bản thận trọng khi adapter vắng mặt hoặc không thể kết xuất.
7. Gửi payload thu được qua đường dẫn giao hàng kênh bình thường.
8. Áp dụng siêu dữ liệu giao hàng như delivery.pin sau thông điệp gửi thành công đầu tiên.

​

Quy tắc hạ cấp

• title làm dòng đầu tiên
• các khối text như đoạn văn bình thường
• các khối context như dòng ngữ cảnh gọn
• các khối divider như dấu phân cách trực quan
• nhãn nút, bao gồm URL cho nút liên kết
• nhãn tùy chọn chọn

​

Khả năng hiển thị dự phòng của giá trị nút

• Các hành động có kiểu command kết xuất thành label: \command“ để người dùng có thể sao chép lệnh và chạy thủ công trong ô nhập của kênh.
• Các hành động có kiểu callback và trường value cũ kết xuất chỉ dưới dạng nhãn. Giá trị callback mờ không bị lộ trong văn bản dự phòng.
• Nút url / webApp kết xuất văn bản URL cùng với nhãn nút, vì URL hướng tới người dùng.
• Tùy chọn chọn kết xuất chỉ dưới dạng nhãn. Giá trị tùy chọn bên dưới không bị lộ trong văn bản dự phòng.

• Telegram với nút inline bị vô hiệu hóa sẽ gửi văn bản dự phòng.
• Một kênh không hỗ trợ menu chọn sẽ liệt kê các tùy chọn chọn dưới dạng văn bản.
• Nút chỉ có URL trở thành nút liên kết gốc hoặc dòng URL dự phòng.
• Lỗi ghim tùy chọn không làm thông điệp đã giao thất bại.

​

Ánh xạ nhà cung cấp

​

Presentation so với InteractiveReply

• văn bản
• nút
• lựa chọn

• tiêu đề
• sắc thái
• ngữ cảnh
• đường phân cách
• nút chỉ URL
• siêu dữ liệu phân phối chung thông qua ReplyPayload.delivery

• InteractiveReply, InteractiveReplyBlock, InteractiveReplyButton, InteractiveReplyOption, InteractiveReplySelectBlock, và InteractiveReplyTextBlock
• normalizeInteractiveReply(...)
• hasInteractiveReplyBlocks(...)
• interactiveReplyToPresentation(...)
• presentationToInteractiveReply(...)
• presentationToInteractiveControlsReply(...)
• resolveInteractiveTextFallback(...)
• reduceInteractiveReply(...)

• dùng buildApprovalPresentationFromActionDescriptors(...) thay cho buildApprovalInteractiveReplyFromActionDescriptors(...)
• dùng buildApprovalPresentation(...) thay cho buildApprovalInteractiveReply(...)
• dùng buildExecApprovalPresentation(...) thay cho buildExecApprovalInteractiveReply(...)

​

Ghim khi phân phối

• pin: true ghim tin nhắn đầu tiên được phân phối thành công.
• pin.notify mặc định là false.
• pin.required mặc định là false.
• Lỗi ghim tùy chọn sẽ hạ cấp và giữ nguyên tin nhắn đã gửi.
• Lỗi ghim bắt buộc làm phân phối thất bại.
• Tin nhắn được chia khúc ghim khúc đầu tiên được phân phối, không phải khúc cuối.

​

Danh sách kiểm tra cho tác giả Plugin

• Khai báo presentation từ describeMessageTool(...) khi kênh có thể kết xuất hoặc hạ cấp presentation ngữ nghĩa một cách an toàn.
• Thêm presentationCapabilities vào bộ thích ứng đi ra của runtime.
• Triển khai renderPresentation trong mã runtime, không phải mã thiết lập Plugin trên mặt phẳng điều khiển.
• Không đưa thư viện UI gốc vào các đường dẫn thiết lập/danh mục nóng.
• Khai báo giới hạn khả năng chung trên presentationCapabilities.limits khi đã biết.
• Giữ nguyên các giới hạn nền tảng cuối cùng trong bộ kết xuất và kiểm thử.
• Thêm kiểm thử dự phòng cho nút không được hỗ trợ, lựa chọn, nút URL, lặp tiêu đề/văn bản, và các lượt gửi kết hợp message với presentation.
• Thêm hỗ trợ ghim khi phân phối thông qua deliveryCapabilities.pin và pinDeliveredMessage chỉ khi nhà cung cấp có thể ghim id tin nhắn đã gửi.
• Không để lộ các trường thẻ/khối/thành phần/nút gốc theo nhà cung cấp mới thông qua lược đồ hành động tin nhắn dùng chung.

​

Tài liệu liên quan

• CLI tin nhắn
• Tổng quan SDK Plugin
• Kiến trúc Plugin
• Kế hoạch tái cấu trúc presentation cho kênh