API gửi đi của kênh

Các Plugin kênh cung cấp hành vi gửi tin nhắn đi từ openclaw/plugin-sdk/channel-outbound. Sử dụng openclaw/plugin-sdk/channel-inbound để điều phối việc nhận/ngữ cảnh/điều phối xử lý.

Lõi chịu trách nhiệm về xếp hàng đợi, tính bền vững, chính sách thử lại chung, hook, biên nhận và công cụ message dùng chung. Plugin chịu trách nhiệm về các lệnh gọi gửi/sửa/xóa gốc, chuẩn hóa đích, luồng hội thoại của nền tảng, trích dẫn được chọn, cờ thông báo, trạng thái tài khoản và các tác dụng phụ dành riêng cho nền tảng.

Bộ điều hợp

Hầu hết Plugin định nghĩa một bộ điều hợp message:

   defineChannelMessageAdapter,  createMessageReceiptFromOutboundResults,} from "openclaw/plugin-sdk/channel-outbound"; export const demoMessageAdapter = defineChannelMessageAdapter({  id: "demo",  durableFinal: {    capabilities: {      text: true,      replyTo: true,      thread: true,      messageSendingHooks: true,    },  },  send: {    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {      const sent = await sendDemoMessage({        cfg,        to,        text,        accountId: accountId ?? undefined,        replyToId: replyToId ?? undefined,        threadId: threadId == null ? undefined : String(threadId),        signal,      });       return {        receipt: createMessageReceiptFromOutboundResults({          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],          kind: "text",          threadId: threadId == null ? undefined : String(threadId),          replyToId: replyToId ?? undefined,        }),      };    },  },});

Chỉ khai báo những khả năng mà cơ chế truyền tải gốc thực sự bảo toàn. Kiểm thử từng khả năng gửi, biên nhận, xem trước trực tiếp và xác nhận nhận đã khai báo bằng các trình trợ giúp hợp đồng được xuất từ đường dẫn con này.

Làm sạch văn bản thuần

Sử dụng sanitizeForPlainText(...) khi bộ điều hợp gửi đi cần chuyển đổi các thẻ định dạng HTML được hỗ trợ thành ký hiệu đánh dấu văn bản nhẹ. Mặc định giữ nguyên các dấu đánh dấu in đậm và gạch ngang theo kiểu trò chuyện hiện có. Chỉ truyền { style: "markdown" } khi kênh phân tích lại kết quả dưới dạng Markdown:

 const chatText = sanitizeForPlainText(text);const markdownText = sanitizeForPlainText(text, { style: "markdown" });

Kiểu Markdown sử dụng **bold** và ~~strikethrough~~; chữ nghiêng và mã nội tuyến giữ các dấu _italic_ và dấu nháy ngược trong cả hai kiểu. Chọn kiểu tại ranh giới kênh thay vì viết lại văn bản đánh dấu sau khi làm sạch.

Bằng chứng phân phối

Một MessageReceipt ghi lại kết quả do bộ điều hợp kênh trả về. Các mã định danh tin nhắn cụ thể của nền tảng cho thấy đường dẫn gửi của nền tảng đã chấp nhận tin nhắn; chúng không chứng minh rằng thiết bị của người nhận đã hiển thị hoặc đọc tin nhắn đó. Các biên nhận không có mã định danh tin nhắn của nền tảng chỉ là siêu dữ liệu biên nhận cục bộ. Các kênh có biên nhận đã đọc hoặc trạng thái phân phối đến thiết bị nên theo dõi những thông tin đó thông qua một đường dẫn riêng dành riêng cho kênh.

Nếu bộ điều hợp kênh có thể chứng minh rằng việc thử lại một lỗi không thể tạo bản sao của lần gửi hiển thị cho người nhận và chưa có lệnh gọi nào có khả năng hoàn tất bắt đầu, hãy ném new PlatformMessageNotDispatchedError("...", { cause: error }) từ openclaw/plugin-sdk/error-runtime. Khi đó, lõi có thể xóa bằng chứng cũ về lần thử gửi và thử lại ý định đã xếp hàng một cách an toàn. Chỉ bộ điều hợp sở hữu ranh giới điều phối cuối cùng mới được đưa ra khẳng định này. Tuyệt đối không sử dụng dấu hiệu này sau khi một lệnh gọi hoàn tất/gửi bắt đầu hoặc trả về kết quả không rõ ràng; đánh dấu sai có thể gửi trùng tin nhắn.

Các bộ điều hợp gửi đi hiện có

Nếu kênh đã có bộ điều hợp outbound tương thích, hãy dẫn xuất bộ điều hợp tin nhắn thay vì sao chép mã gửi:

 export const messageAdapter = createChannelMessageAdapterFromOutbound({  id: "demo",  outbound,  durableFinal: {    capabilities: {      text: true,      media: true,    },  },});

Gửi bền vững

Các trình trợ giúp gửi lúc chạy cũng nằm trong channel-outbound:

• sendDurableMessageBatch(...)
• withDurableMessageSendContext(...)
• deliverInboundReplyWithMessageSendContext(...)
• các trình trợ giúp truyền trực tuyến bản nháp/tiến trình như resolveChannelDraftStreamingChunking(...)

sendDurableMessageBatch(...) trả về một kết quả rõ ràng:

Sử dụng payloadOutcomes khi một lô kết hợp các tải trọng đã gửi, bị chặn và thất bại. Không suy ra việc hook hủy từ một kết quả phân phối trực tiếp cũ trống.

Chấp nhận phân phối trì hoãn

Sử dụng message.durableFinal.admitDeferredDelivery(...) khi một tài khoản đã phân giải không thể chấp nhận an toàn việc gửi đi hoặc phân phối trì hoãn do lõi quản lý. Lõi gọi hook này một cách đồng bộ trước công việc gửi đi trực tiếp, bao gồm cả các đường dẫn bỏ qua việc lưu bền hàng đợi, và gọi lại trước khi phát lại một ý định đã khôi phục. Ngữ cảnh bao gồm cfg, channel, to, accountId và phase là live hoặc recovery.

Trả về { status: "allowed" } để tiếp tục. Trả về { status: "permanent_rejection", reason } khi lượt phân phối không được phép lưu bền, gửi trực tiếp hoặc phát lại. Một lần từ chối trực tiếp sẽ thất bại trước khi tạo hàng đợi, chạy hook tin nhắn hoặc thực hiện công việc trên nền tảng. Một lần từ chối khi khôi phục đánh dấu bản ghi trong hàng đợi là thất bại và bỏ qua việc đối soát cũng như phát lại. Không cung cấp hook đồng nghĩa với được phép.

Hook là một quyết định chấp nhận đồng bộ, không phải đường dẫn gửi. Chỉ đọc cấu hình hoặc trạng thái lúc chạy đã được tải; không thực hiện I/O mạng, hệ thống tệp hay I/O bất đồng bộ khác. Các kiểm thử hợp đồng nên kiểm tra cả hai giai đoạn và cả hai biến thể kết quả thông qua ChannelMessageDurableFinalAdapter từ openclaw/plugin-sdk/channel-outbound.

Điều phối tương thích

Xây dựng việc điều phối phản hồi đầu vào thông qua dispatchChannelInboundReply(...) từ channel-inbound. Giữ việc phân phối qua nền tảng trong bộ điều hợp phân phối; sử dụng channel-outbound cho các bộ điều hợp tin nhắn, gửi bền vững, biên nhận, xem trước trực tiếp và các tùy chọn quy trình phản hồi.