@ynhcj/xiaoyi-channel 0.0.231-next → 0.0.232-next

package/dist/src/conversation/cron-buffer.js

@@ -21,37 +21,55 @@
 //       · 宽限期结束无 announce（路径 B）→ 缓冲文本合并为一条 push 发出。
 //   - 120s 安全超时兜底：强制 flush 缓冲并关闭，防泄漏到下一个 run。
 //
-// 单槽设计：与原 __xyCronDetectedTs 全局单例假设一致（不隔离并发 cron job）。
+// 并发设计：按 jobId 隔离（Map<jobId, CronTurnState>）。openclaw 保证同一
+// job 的不同 run 不重叠（runningAtMs 拦截），jobId 是安全键；jobId 缺失时
+// 归入 `__unknown__` 桶。sendText 层无法直接拿到 jobId/runId（openclaw 不
+// 把 session 上下文传给 channel adapter），路由规则见 gateCronSendText：
+//   - announce 类（无 target，to === DEFAULT_PUSH_MARKER）→ 路由到处于
+//     agentEnded 宽限的 turn（多个时按 endedAt FIFO，匹配 openclaw 按 run
+//     完成顺序投递 announce）；
+//   - 中间消息（有真实 target）→ 恰好 1 个活跃 turn 时吞入缓冲；多活跃
+//     turn（真并发、无法归属）安全回退：不聚合，按普通 push 原样发送。
 import { logger } from "../utils/logger.js";
 import { pushBroadcast } from "./outbound-gateway.js";
+import { savePushData } from "../utils/pushdata-manager.js";
 /** 与 isCronActive 的 120s TTL 对齐：超时强制关闭，防崩溃泄漏到下一个 run。 */
 const CRON_SAFETY_TIMEOUT_MS = 120_000;
 /** run 结束后等待 announce 的宽限时间。 */
 const ANNOUNCE_GRACE_MS = 10_000;
 const MAX_BUFFERED_KEPT = 20;
-const _g = globalThis;
-if (_g.__xyCronTurn === undefined) {
-    _g.__xyCronTurn = null;
+/** jobId 缺失（无法归属）时的兜底桶。 */
+const UNKNOWN_JOB_KEY = "__unknown__";
+function normalizeKey(jobId) {
+    return jobId ?? UNKNOWN_JOB_KEY;
 }
-function getTurn() {
-    return _g.__xyCronTurn ?? null;
+const _g = globalThis;
+if (!(_g.__xyCronTurns instanceof Map)) {
+    _g.__xyCronTurns = new Map();
 }
-function setTurn(turn) {
-    _g.__xyCronTurn = turn;
+function getTurnRegistry() {
+    return _g.__xyCronTurns;
 }
-/** 关闭当前 cron turn（清理全部定时器）。 */
-export function closeCronTurn(reason) {
-    const turn = getTurn();
+/** 关闭指定 job 的 cron turn（清理全部定时器）。 */
+export function closeCronTurn(jobId, reason) {
+    const key = normalizeKey(jobId);
+    const turn = getTurnRegistry().get(key);
     if (!turn)
         return;
     clearTimeout(turn.safetyTimer);
     if (turn.graceTimer)
         clearTimeout(turn.graceTimer);
-    setTurn(null);
-    logger.log(`[CRON-BUFFER] Cron turn closed, reason=${reason}`);
+    getTurnRegistry().delete(key);
+    logger.log(`[CRON-BUFFER] Cron turn closed, jobId=${jobId ?? "-"}, reason=${reason}`);
 }
-/** 将缓冲文本合并为一条 push 发出（截断沿用 1000 字限制）。 */
-async function flushBufferedTexts(texts, config, reason) {
+/**
+ * 将缓冲文本合并为一条 push 发出（截断沿用 1000 字限制）。
+ * meta 必须由调用方在 closeCronTurn 之前从 turn 捕获传入 —— close 后
+ * turn 已从 registry 移除，flush 内部无法再读取 cron 元数据。
+ * 持久化用全文 merged（客户端 Trigger 回查看全文，不受截断影响）；
+ * savePushData 失败时 pushDataId="" 回落 kind:"text" 内联，行为同现状。
+ */
+async function flushBufferedTexts(texts, config, reason, meta) {
     const merged = texts.join("\n\n").trim();
     if (!merged) {
         logger.log(`[CRON-BUFFER] Nothing to flush (${reason})`);
@@ -62,14 +80,23 @@ async function flushBufferedTexts(texts, config, reason) {
         return;
     }
     const pushText = merged.length > 1000 ? merged.slice(0, 1000) : merged;
-    logger.log(`[CRON-BUFFER] Flushing merged text (${reason}), len=${pushText.length}`);
+    let pushDataId = "";
+    try {
+        pushDataId = await savePushData(merged, { cronJobId: meta?.jobId, cronTitle: meta?.jobTitle });
+    }
+    catch (err) {
+        logger.error(`[CRON-BUFFER] Failed to save pushData for flush (${reason}):`, err);
+    }
+    logger.log(`[CRON-BUFFER] Flushing merged text (${reason}), len=${pushText.length}, pushDataId=${pushDataId || "-"}`);
     try {
         await pushBroadcast({
             config,
             text: pushText,
             title: pushText.split("\n")[0].slice(0, 57),
             to: config.defaultSessionId || "",
-            pushDataId: "",
+            pushDataId,
+            cronJobId: meta?.jobId,
+            cronTitle: meta?.jobTitle,
         });
     }
     catch (err) {
@@ -80,36 +107,46 @@ async function flushBufferedTexts(texts, config, reason) {
  * cron turn 开始检测。由 provider.ts 在识别到 [cron:...] 首条消息时调用。
  * 同一 cron run 的每次模型调用都会重复触发检测 —— 此时仅刷新安全定时器，
  * 不重开 turn（避免 churn，也避免重置 agentEnded/缓冲状态）。
+ * 按 jobId 隔离：不同 job 并发触发时各自独立建 turn，后到 job 的 jobId
+ * 不再被覆盖丢弃。
  */
-export function notifyCronDetected(jobId) {
-    const existing = getTurn();
+export function notifyCronDetected(jobId, jobTitle) {
+    const key = normalizeKey(jobId);
+    const registry = getTurnRegistry();
+    const existing = registry.get(key);
     if (existing) {
-        // 同一 run 的重复检测：刷新安全定时器
+        // 同一 job 的重复检测：刷新安全定时器，回填缺失的 title
         clearTimeout(existing.safetyTimer);
-        existing.safetyTimer = armSafetyTimer();
+        existing.safetyTimer = armSafetyTimer(key);
         existing.startedAt = Date.now();
+        if (!existing.jobTitle && jobTitle)
+            existing.jobTitle = jobTitle;
         return;
     }
     const turn = {
         jobId,
+        jobTitle,
         startedAt: Date.now(),
+        endedAt: 0,
         agentEnded: false,
         bufferedTexts: [],
-        safetyTimer: armSafetyTimer(),
+        safetyTimer: armSafetyTimer(key),
     };
-    setTurn(turn);
-    logger.log(`[CRON-BUFFER] Cron turn opened, jobId=${jobId ?? "unknown"}`);
+    registry.set(key, turn);
+    logger.log(`[CRON-BUFFER] Cron turn opened, jobId=${jobId ?? "unknown"}, title=${jobTitle ?? "-"}`);
 }
-function armSafetyTimer() {
+function armSafetyTimer(key) {
     const timer = setTimeout(() => {
-        const turn = getTurn();
+        const turn = getTurnRegistry().get(key);
         if (!turn)
             return;
-        logger.warn(`[CRON-BUFFER] Safety timeout (${CRON_SAFETY_TIMEOUT_MS}ms) reached, agentEnded=${turn.agentEnded}, buffered=${turn.bufferedTexts.length}`);
+        logger.warn(`[CRON-BUFFER] Safety timeout (${CRON_SAFETY_TIMEOUT_MS}ms) reached, jobId=${turn.jobId ?? "-"}, agentEnded=${turn.agentEnded}, buffered=${turn.bufferedTexts.length}`);
         const flushed = turn.bufferedTexts.slice();
-        closeCronTurn("safety-timeout");
+        const meta = { jobId: turn.jobId, jobTitle: turn.jobTitle };
+        const config = turn.config;
+        closeCronTurn(turn.jobId, "safety-timeout");
         if (flushed.length > 0) {
-            void flushBufferedTexts(flushed, turn.config, "safety-timeout");
+            void flushBufferedTexts(flushed, config, "safety-timeout", meta);
         }
     }, CRON_SAFETY_TIMEOUT_MS);
     // 安全定时器不应阻止进程退出
@@ -118,51 +155,115 @@ function armSafetyTimer() {
 }
 /**
  * cron run 结束信号（lifecycle phase=end，由 index.ts 的 agent event
- * subscription 调用）。进入 announce 宽限期：
+ * subscription 调用，jobId 从 event.sessionKey 解析）。只结束该 job 的
+ * turn，进入 announce 宽限期：
  *   - 宽限期内 announce 到达 → 放行（见 gateCronSendText）；
  *   - 宽限期结束无 announce → 合并缓冲文本发一条（路径 B）。
+ * jobId 缺失（sessionKey 解析失败）时：若恰有 1 个活跃 turn，兼容旧单槽
+ * 行为结束之；多个活跃 turn 时无法归属，跳过并告警。
  */
-export function notifyCronAgentEnd() {
-    const turn = getTurn();
-    if (!turn)
+export function notifyCronAgentEnd(jobId) {
+    const key = normalizeKey(jobId);
+    const registry = getTurnRegistry();
+    const turn = registry.get(key);
+    if (!turn) {
+        if (!jobId) {
+            const actives = Array.from(registry.values()).filter((t) => !t.agentEnded);
+            if (actives.length === 1) {
+                startGrace(actives[0], key);
+                return;
+            }
+            if (actives.length > 1) {
+                logger.warn(`[CRON-BUFFER] notifyCronAgentEnd without jobId but ${actives.length} active turns — skipping (cannot attribute)`);
+            }
+        }
         return;
+    }
+    startGrace(turn, key);
+}
+function startGrace(turn, key) {
     turn.agentEnded = true;
+    turn.endedAt = Date.now();
     if (turn.graceTimer)
         clearTimeout(turn.graceTimer);
     turn.graceTimer = setTimeout(() => {
-        const t = getTurn();
+        const t = getTurnRegistry().get(key);
         if (!t)
             return;
-        logger.log(`[CRON-BUFFER] Announce grace expired, buffered=${t.bufferedTexts.length}`);
+        logger.log(`[CRON-BUFFER] Announce grace expired, jobId=${t.jobId ?? "-"}, buffered=${t.bufferedTexts.length}`);
         const flushed = t.bufferedTexts.slice();
-        closeCronTurn("announce-grace-expired");
+        const meta = { jobId: t.jobId, jobTitle: t.jobTitle };
+        const config = t.config;
+        closeCronTurn(t.jobId, "announce-grace-expired");
         if (flushed.length > 0) {
-            void flushBufferedTexts(flushed, t.config, "announce-grace-expired");
+            void flushBufferedTexts(flushed, config, "announce-grace-expired", meta);
         }
     }, ANNOUNCE_GRACE_MS);
     turn.graceTimer.unref?.();
-    logger.log(`[CRON-BUFFER] Cron agent ended, announce grace period (${ANNOUNCE_GRACE_MS}ms) started`);
+    logger.log(`[CRON-BUFFER] Cron agent ended, jobId=${turn.jobId ?? "-"}, announce grace period (${ANNOUNCE_GRACE_MS}ms) started`);
 }
 /**
- * sendText 闸门：
- * - "swallow"：cron turn 进行中（run 未结束），吞掉中间 sendText，文本入缓冲；
- * - "announce"：run 已结束（宽限期内），当前 sendText 是 announce 最终
- *   结果，放行（唯一一条，缓冲丢弃）；
- * - "none"：无 cron turn，正常发送。
+ * sendText 闸门。sendText 层拿不到 jobId/runId，只能凭 announceLike
+ * （to 是否为 DEFAULT_PUSH_MARKER，即是否有显式 target）做粗路由：
+ * - announceLike（无 target）：run 结束后的 announce 最终结果，路由到处于
+ *   agentEnded 宽限的 turn。多个 ended turn（两端几乎同时结束的窄竞态）按
+ *   endedAt FIFO，与 openclaw 按 run 完成顺序投递 announce 一致。
+ * - 非 announceLike（有 target）：run 期间的中间 sendText，吞入活跃 turn
+ *   缓冲。恰 1 个活跃 turn 正常吞；多活跃 turn（真并发、无法归属）安全回退
+ *   返回 "none"（不聚合、原样发送，宁可多推也不让 pushText/cronId 串台）。
+ * - "none"：无 cron turn 或无法归属，按普通 push 发送。
  */
-export function gateCronSendText(swallowedText, config) {
-    const turn = getTurn();
-    if (!turn)
-        return "none";
-    if (config)
-        turn.config = config;
-    if (turn.agentEnded)
-        return "announce";
-    if (swallowedText && swallowedText.trim()) {
-        turn.bufferedTexts.push(swallowedText.trim());
-        if (turn.bufferedTexts.length > MAX_BUFFERED_KEPT) {
-            turn.bufferedTexts.shift();
+export function gateCronSendText(swallowedText, announceLike, config) {
+    const registry = getTurnRegistry();
+    const turns = Array.from(registry.values());
+    if (turns.length === 0)
+        return { gate: "none", meta: null };
+    if (announceLike) {
+        const ended = turns.filter((t) => t.agentEnded).sort((a, b) => a.endedAt - b.endedAt);
+        if (ended.length > 0) {
+            const t = ended[0];
+            if (config)
+                t.config = config;
+            return {
+                gate: "announce",
+                meta: { jobId: t.jobId, jobTitle: t.jobTitle },
+                jobId: t.jobId,
+            };
         }
+        // run 未结束但发了一条无 target 的中间消息（罕见）：恰 1 活跃 turn 时吞入。
+        const active = turns.filter((t) => !t.agentEnded);
+        if (active.length === 1) {
+            const t = active[0];
+            if (config)
+                t.config = config;
+            if (swallowedText && swallowedText.trim()) {
+                t.bufferedTexts.push(swallowedText.trim());
+                if (t.bufferedTexts.length > MAX_BUFFERED_KEPT)
+                    t.bufferedTexts.shift();
+            }
+            return { gate: "swallow", meta: null, jobId: t.jobId };
+        }
+        // 多活跃 turn：无法归属，安全回退。
+        return { gate: "none", meta: null };
+    }
+    // 中间消息（有真实 target）
+    const active = turns.filter((t) => !t.agentEnded);
+    if (active.length === 1) {
+        const t = active[0];
+        if (config)
+            t.config = config;
+        if (swallowedText && swallowedText.trim()) {
+            t.bufferedTexts.push(swallowedText.trim());
+            if (t.bufferedTexts.length > MAX_BUFFERED_KEPT)
+                t.bufferedTexts.shift();
+        }
+        return { gate: "swallow", meta: null, jobId: t.jobId };
+    }
+    if (active.length === 0) {
+        // 所有 turn 均已结束：迟到/兜底的 sendText（如 message 工具结果晚于
+        // announce），按普通 push 发送，不再聚合。
+        return { gate: "none", meta: null };
     }
-    return "swallow";
+    // 多活跃 turn（真并发重叠）：无法归属，安全回退。
+    return { gate: "none", meta: null };
 }

package/dist/src/conversation/outbound-gateway.d.ts

@@ -18,6 +18,10 @@ export interface PushBroadcastParams {
     /** 目标会话标识（push 服务侧使用，可为空字符串）。 */
     to: string;
     pushDataId: string;
+    /** cron 推送时携带：任务 jobId（随 kind="data" 下发给客户端） */
+    cronJobId?: string;
+    /** cron 推送时携带：任务标题 */
+    cronTitle?: string;
 }
 export interface PushBroadcastResult {
     successCount: number;

package/dist/src/conversation/outbound-gateway.js

@@ -29,7 +29,7 @@ export async function sendWsFrame(params) {
  * 向所有已注册 pushId 广播推送通知（单 pushId 失败不影响其他）。
  */
 export async function pushBroadcast(params) {
-    const { config, text, title, to, pushDataId } = params;
+    const { config, text, title, to, pushDataId, cronJobId, cronTitle } = params;
     let pushIdList = [];
     try {
         pushIdList = await getAllPushIds();
@@ -45,7 +45,7 @@ export async function pushBroadcast(params) {
     let failureCount = 0;
     for (const pushId of pushIdList) {
         try {
-            await pushService.sendPush(text, title, undefined, to, pushDataId, pushId);
+            await pushService.sendPush(text, title, undefined, to, pushDataId, pushId, cronJobId, cronTitle);
             successCount++;
             logger.log(`[outbound-gateway] Push sent to pushId: ${pushId.substring(0, 20)}...`);
         }

package/dist/src/conversation/outbound-queue.d.ts

@@ -0,0 +1,35 @@
+export interface OutboundFrame {
+    /** 帧归属的 taskId（purge 的粒度）。 */
+    taskId: string;
+    /** 日志标签（帧用途描述）。 */
+    label: string;
+    /**
+     * 合并键：drain 取帧时，若队列后方存在同 key 帧，则跳过本帧。
+     * 仅 append:false 全量文本帧应设置（如 `partial:${taskId}`）。
+     */
+    coalesceKey?: string;
+    /** 发送前延迟（drain 内 sleep，阻塞后续帧）。 */
+    delayMs?: number;
+    /** 实际发送闭包（帧应在入队前完成组帧与上下文捕获）。 */
+    send: () => Promise<void>;
+}
+export declare class OutboundQueue {
+    private readonly sessionId;
+    private items;
+    private draining;
+    /** 当前 drain 循环的 Promise；空闲时为已 resolve 的 Promise。 */
+    private drainPromise;
+    private destroyed;
+    constructor(sessionId: string);
+    enqueue(frame: OutboundFrame): void;
+    /** 丢弃指定 taskId 的全部待发帧（steer/cancel 场景；在途帧无法撤回）。 */
+    purge(taskId: string): void;
+    /** 会话销毁：丢弃全部待发帧，后续入队直接丢弃。 */
+    destroy(): void;
+    /**
+     * 等待队列排空。等待期间新入队的帧也会被等到（循环检查）。
+     * drain 不 reject（帧级异常已内部捕获），此 Promise 不会失败。
+     */
+    whenIdle(): Promise<void>;
+    private drain;
+}

package/dist/src/conversation/outbound-queue.js

@@ -0,0 +1,96 @@
+// Outbound queue — 对话管理层的每会话出站队列。
+//
+// 收拢原散落在 reply-dispatcher processingLock / 各处直发中的时序职责：
+// 所有发往 xy server 的帧（partial/status/final/命令/工具注入）都经此队列
+// 串行发出，形成会话级唯一时序收口点。
+//
+// 设计要点：
+//   - drain 单飞串行：取帧 → coalescing 检查 → delayMs sleep → await send()。
+//     单帧异常只记日志，不阻塞后续帧。
+//   - coalescing 仅作用于 append:false 全量文本帧（自覆盖语义：同 key 只发
+//     最新一帧是安全的）；status/final/命令帧不传 coalesceKey，永不参与。
+//   - delayMs 在 drain 内 sleep，阻塞后续帧 —— 正是终态帧延迟想要的语义：
+//     让已发出的长正文先穿过下游服务端慢速管道（openclaw6.6 3e7b1aa/cdc4cdc）。
+//   - whenIdle() 等待队列排空，含等待期间新入队的帧。
+//   - 本模块只做时序，不组帧不感知 transport；send 闭包由调用方构造。
+import { logger } from "../utils/logger.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class OutboundQueue {
+    sessionId;
+    items = [];
+    draining = false;
+    /** 当前 drain 循环的 Promise；空闲时为已 resolve 的 Promise。 */
+    drainPromise = Promise.resolve();
+    destroyed = false;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    enqueue(frame) {
+        if (this.destroyed) {
+            logger.withContext(this.sessionId, frame.taskId).log(`[OUTBOUND-QUEUE] Queue destroyed, dropping frame: ${frame.label}`);
+            return;
+        }
+        this.items.push(frame);
+        if (!this.draining) {
+            this.draining = true;
+            this.drainPromise = this.drain();
+        }
+    }
+    /** 丢弃指定 taskId 的全部待发帧（steer/cancel 场景；在途帧无法撤回）。 */
+    purge(taskId) {
+        const before = this.items.length;
+        this.items = this.items.filter((f) => f.taskId !== taskId);
+        const dropped = before - this.items.length;
+        if (dropped > 0) {
+            logger.withContext(this.sessionId, taskId).log(`[OUTBOUND-QUEUE] Purged ${dropped} pending frame(s) for task`);
+        }
+    }
+    /** 会话销毁：丢弃全部待发帧，后续入队直接丢弃。 */
+    destroy() {
+        this.destroyed = true;
+        this.items = [];
+    }
+    /**
+     * 等待队列排空。等待期间新入队的帧也会被等到（循环检查）。
+     * drain 不 reject（帧级异常已内部捕获），此 Promise 不会失败。
+     */
+    async whenIdle() {
+        while (this.draining || this.items.length > 0) {
+            await this.drainPromise;
+        }
+    }
+    async drain() {
+        const log = logger.withContext(this.sessionId, "");
+        try {
+            while (this.items.length > 0) {
+                const frame = this.items.shift();
+                // coalescing：后方有同 key 帧时本帧可丢（全量帧自覆盖语义）。
+                if (frame.coalesceKey &&
+                    this.items.some((f) => f.coalesceKey === frame.coalesceKey)) {
+                    continue;
+                }
+                if (frame.delayMs && frame.delayMs > 0) {
+                    log.log(`[OUTBOUND-QUEUE] Delaying frame by ${frame.delayMs}ms: ${frame.label}`);
+                    await sleep(frame.delayMs);
+                }
+                try {
+                    await frame.send();
+                }
+                catch (err) {
+                    logger.withContext(this.sessionId, frame.taskId).error(`[OUTBOUND-QUEUE] Frame send failed: ${frame.label}`, err);
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+            // finally 期间可能有新帧入队（draining 已置 false 时 enqueue 会自启
+            // 新 drain；此处兜底：若 enqueue 发生在 draining=false 判定之前则补一轮）。
+            if (this.items.length > 0 && !this.draining) {
+                this.draining = true;
+                this.drainPromise = this.drain();
+            }
+        }
+    }
+}

package/dist/src/conversation/stream-assembler.d.ts

@@ -0,0 +1,52 @@
+export interface AssemblerSegment {
+    kind: "model" | "injected";
+    text: string;
+}
+export interface FinalizeResult {
+    /** 终帧应携带的全文本（可能为空字符串 —— 异常路径，调用方回退空帧语义）。 */
+    fullText: string;
+    /** 最后一轮模型调用的解析文本（canonical 优先），供跨任务结果消息使用。 */
+    resolvedLastText: string;
+    /** 权威文本与流式累计的对比诊断（无权威文本时为 "no-canonical"）。 */
+    diagnostic: "match" | "patched-tail" | "canonical-shorter" | "diverged" | "no-canonical";
+}
+export declare class StreamAssembler {
+    private segments;
+    /** 当前模型调用的流式累计文本（同一调用内递增）。 */
+    private currentModelText;
+    /** deliver(kind=final) 捕获的权威最终文本（最后一次模型调用的 canonical 文本）。 */
+    private canonicalFinalText;
+    /**
+     * onPartialReply 喂入。text 是当前模型调用的累计清洗文本（非增量）。
+     * 同一调用内 text 递增；跨调用时 text 刷新（!startsWith），此时把上一个
+     * 调用的完整文本锁存为 model 段。
+     */
+    onStreamText(text: string): {
+        fullText: string;
+        latched: boolean;
+    };
+    /**
+     * 工具注入非模型文本（如卡片 DSL）。先锁存当前模型文本（保持相对位置），
+     * 再把注入内容作为独立段压入。注入后所有全量帧自然携带该段，
+     * 客户端 append:false 整体替换不会抹掉注入内容。
+     */
+    injectArtifact(text: string): string;
+    /**
+     * deliver(kind=final) 喂入权威文本。调用方必须已排除 compaction 通知和
+     * ⚙️ 系统通知（它们不是答案文本）。
+     */
+    onFinalText(text: string): void;
+    /**
+     * onIdle 收口：计算终帧全文本。
+     * canonical 非空时替换 currentModelText；current 为空（已锁存/无流式）时
+     * 替换最后一个 model 段；完全没有 model 内容（ACP 纯 deliver 路径）时
+     * fullText 就是 canonical 本身。
+     */
+    finalize(): FinalizeResult;
+    /** 全文本：已锁存段以 "\n" 连接，再接当前模型文本。 */
+    getFullText(): string;
+    /** 是否有任何已装配内容（已锁存段或当前模型文本非空）。 */
+    hasContent(): boolean;
+    /** 新 turn 清空（dispatcher 创建时调用；终帧发出后也应复位）。 */
+    reset(): void;
+}

package/dist/src/conversation/stream-assembler.js

@@ -0,0 +1,122 @@
+// Stream assembler — 对话管理层的流式文本装配器。
+//
+// 收拢原 reply-dispatcher 闭包中的 prevModelText/currentModelText 拼接逻辑，
+// 升级为有序段模型：
+//   - model 段：一次模型调用的完整文本（onStreamText 跨调用边界时锁存）
+//   - injected 段：工具注入的非模型文本（如 display-a2ui-card 的卡片 DSL）
+//
+// 设计要点：
+//   - 段以 "\n" 连接，轮间换行符天然保留（锁存不带分隔符的 bug 在结构上消除）。
+//   - 权威文本修正：openclaw 在 message_end 发出的最终清洗文本不走
+//     onPartialReply，流式累计可能缺尾；deliver(kind=final) 提供 canonical
+//     文本，finalize() 时以它替换当前轮（或最后一个 model 段）。
+//   - 本类是纯逻辑，不做任何发送；发送由调用方经 outbound-queue 完成。
+const SEGMENT_SEPARATOR = "\n";
+export class StreamAssembler {
+    segments = [];
+    /** 当前模型调用的流式累计文本（同一调用内递增）。 */
+    currentModelText = "";
+    /** deliver(kind=final) 捕获的权威最终文本（最后一次模型调用的 canonical 文本）。 */
+    canonicalFinalText = "";
+    /**
+     * onPartialReply 喂入。text 是当前模型调用的累计清洗文本（非增量）。
+     * 同一调用内 text 递增；跨调用时 text 刷新（!startsWith），此时把上一个
+     * 调用的完整文本锁存为 model 段。
+     */
+    onStreamText(text) {
+        let latched = false;
+        if (this.currentModelText && !text.startsWith(this.currentModelText)) {
+            this.segments.push({ kind: "model", text: this.currentModelText });
+            latched = true;
+        }
+        this.currentModelText = text;
+        return { fullText: this.getFullText(), latched };
+    }
+    /**
+     * 工具注入非模型文本（如卡片 DSL）。先锁存当前模型文本（保持相对位置），
+     * 再把注入内容作为独立段压入。注入后所有全量帧自然携带该段，
+     * 客户端 append:false 整体替换不会抹掉注入内容。
+     */
+    injectArtifact(text) {
+        if (this.currentModelText) {
+            this.segments.push({ kind: "model", text: this.currentModelText });
+            this.currentModelText = "";
+        }
+        this.segments.push({ kind: "injected", text });
+        return this.getFullText();
+    }
+    /**
+     * deliver(kind=final) 喂入权威文本。调用方必须已排除 compaction 通知和
+     * ⚙️ 系统通知（它们不是答案文本）。
+     */
+    onFinalText(text) {
+        this.canonicalFinalText = text;
+    }
+    /**
+     * onIdle 收口：计算终帧全文本。
+     * canonical 非空时替换 currentModelText；current 为空（已锁存/无流式）时
+     * 替换最后一个 model 段；完全没有 model 内容（ACP 纯 deliver 路径）时
+     * fullText 就是 canonical 本身。
+     */
+    finalize() {
+        let resolvedLastText = this.currentModelText;
+        let diagnostic = "no-canonical";
+        const canonical = this.canonicalFinalText;
+        if (canonical) {
+            if (canonical === this.currentModelText) {
+                diagnostic = "match";
+            }
+            else if (canonical.startsWith(this.currentModelText)) {
+                diagnostic = "patched-tail";
+            }
+            else if (this.currentModelText.startsWith(canonical)) {
+                diagnostic = "canonical-shorter";
+            }
+            else {
+                diagnostic = "diverged";
+            }
+            resolvedLastText = canonical;
+            if (this.currentModelText) {
+                this.currentModelText = canonical;
+            }
+            else {
+                // current 已锁存或从未流式：替换最后一个 model 段；无 model 段则
+                // canonical 自成一段（ACP 纯 deliver 路径）。
+                for (let i = this.segments.length - 1; i >= 0; i--) {
+                    if (this.segments[i].kind === "model") {
+                        this.segments[i] = { kind: "model", text: canonical };
+                        return {
+                            fullText: this.getFullText(),
+                            resolvedLastText,
+                            diagnostic,
+                        };
+                    }
+                }
+                this.segments.push({ kind: "model", text: canonical });
+            }
+        }
+        return {
+            fullText: this.getFullText(),
+            resolvedLastText,
+            diagnostic,
+        };
+    }
+    /** 全文本：已锁存段以 "\n" 连接，再接当前模型文本。 */
+    getFullText() {
+        const parts = this.segments.map((s) => s.text);
+        if (this.currentModelText) {
+            parts.push(this.currentModelText);
+        }
+        return parts.join(SEGMENT_SEPARATOR);
+    }
+    /** 是否有任何已装配内容（已锁存段或当前模型文本非空）。 */
+    hasContent() {
+        return this.segments.length > 0 || this.currentModelText.length > 0;
+    }
+    /** 新 turn 清空（dispatcher 创建时调用；终帧发出后也应复位）。 */
+    reset() {
+        this.segments = [];
+        this.currentModelText = "";
+        this.canonicalFinalText = "";
+    }
+}