消息生命周期重构

概述

消息生命周期重构是将分散的 channel turn、回复分发、预览流式和出站投递助手统一为一个持久化消息生命周期的目标设计。核心思想：将 receive 和 send 作为基本原语，reply 只是出站消息上的一个关系，turn 是入站处理的便利封装而非投递的所有者。

核心要点

• 四个核心概念：receive（入站生命周期）、send（出站生命周期）、live（预览/编辑/进度/流式状态）、state（持久化意图存储、收据、幂等性、恢复、锁、去重）
• 持久化优先：一旦 core 决定可见出站消息应存在，意图必须在平台发送前持久化；平台收据在成功后提交
• 消息关系类型：reply、followup、broadcast、system（approval/task/hook/cron/subagent/cli 等）
• Origin 元数据：区分 OpenClaw 自产消息（如 gateway_failure）和用户/外部消息，防止 bot 房间回声重入
• 收据（Receipt）：一等公民，包含所有平台消息 ID，支持后续编辑、删除、预览最终化和去重
• 持久化策略：required（失败关闭）、best_effort（降级）、disabled（旧版直接发送）
• 迁移分 8 个阶段：内部消息域 → 持久化发送核心 → channel turn 桥接 → 准备好的分发器桥接 → 统一 live 生命周期 → 公共 SDK → 所有发送者 → 废弃 turn

配置/使用

新核心模型（目标 API）：

// 发送上下文
await core.messages.withSendContext(message, async (ctx) => {
  const rendered = await ctx.render();
  if (ctx.preview?.canFinalizeInPlace) {
    return await ctx.edit(ctx.preview.receipt, rendered);
  }
  return await ctx.send(rendered);
});

持久化意图状态机：pending → sending → committing → sent（或 unknown_after_send → 协调 → 重试/失败）

失败分类：transient（重试）、rate_limit（重试）、auth/permission（不重试）、invalid_payload（有 fallback 才重试）、not_found（live 降级为新发）

公共 SDK 目标入口：

import { defineChannelMessageAdapter } from "openclaw/plugin-sdk/channel-message";

相关页面

• messages — 当前消息处理流水线
• streaming — 流式输出与分块
• progress-drafts — 进度草稿
• retry — 重试策略
• queue — 命令队列模式