lightclawbot 1.1.2 → 1.2.0-beta.0

package/dist/src/socket/reliable-emitter.js

@@ -1,32 +1,66 @@
 /**
- * LightClaw — 可靠发送器
+ * LightClaw — 可靠发送器（ReliableEmitter）
  *
- * 所有出站 socket.emit 都通过此模块，利用 Socket.IO 原生 ACK + timeout 机制：
- *   socket.timeout(ms).emit(event, data, (err, ...args) => { ... })
- * 超时由 Socket.IO 原生处理，回调第一个参数为 Error（超时）或 null（成功）。
+ * 解决的核心问题：
+ *   普通的 socket.emit 是「发完即忘」，网络抖动时消息可能悄无声息地丢失。
+ *   ReliableEmitter 在此基础上增加了「确认 + 重试」机制，确保消息最终送达。
  *
- * 未收到 ACK 则指数退避重试，断线期间暂停重试、重连后立即重发。
+ * 工作原理：
+ *   1. 发送时利用 NativeSocketClient 的 ACK + timeout 机制：
+ *      socket.timeout(ms).emit(event, data, (err, ...args) => { ... })
+ *      超时由 NativeSocketClient 内部处理，回调第一个参数为 Error（超时）或 null（成功）。
+ *   2. 未收到 ACK（超时或出错）则按「指数退避 + 随机抖动」策略安排重试。
+ *   3. 断线期间暂停所有重试计时器（pause），重连后立即重发所有待确认消息（resume）。
+ *   4. 每条消息注入 idempotencyKey，服务端/前端据此去重，防止重试导致重复处理。
+ *
+ * 生命周期：
+ *   new ReliableEmitter(getSocket, log)
+ *     → emitWithAck(...)   发送消息
+ *     → pause()            断线时调用
+ *     → resume()           重连时调用
+ *     → destroy()          销毁时调用（清理所有定时器）
+ *
+ * @format
  */
-import { EMIT_ACK_TIMEOUT, EMIT_MAX_RETRIES, EMIT_RETRY_BASE_DELAY, EMIT_RETRY_MAX_DELAY, EMIT_PENDING_MAX, } from "../config.js";
+import { EMIT_ACK_TIMEOUT, EMIT_MAX_RETRIES, EMIT_RETRY_BASE_DELAY, EMIT_RETRY_MAX_DELAY, EMIT_PENDING_MAX, } from '../config.js';
 // ============================================================
-// ReliableEmitter
+// ReliableEmitter 主类
 // ============================================================
 export class ReliableEmitter {
     getSocket;
     log;
+    /**
+     * 待确认消息队列。
+     * key = emitId（内部唯一标识），value = PendingMessage。
+     * 消息从入队到收到 ACK（或放弃）期间始终存在于此 Map 中。
+     */
     pending = new Map();
+    /**
+     * 是否处于暂停状态（断线中）。
+     * 暂停时：新消息入队但不发送；已有重试计时器全部清除。
+     * 恢复时：立即重发所有 pending 消息。
+     */
     paused = false;
+    /**
+     * 自增计数器，配合时间戳生成唯一的 emitId，防止高频调用时 ID 碰撞。
+     */
     idCounter = 0;
-    // 统计
+    /** 运行时统计，通过 getStats() 对外暴露 */
     stats = {
         totalEmitted: 0,
         totalConfirmed: 0,
         totalRetries: 0,
         totalFailed: 0,
     };
-    constructor(getSocket, log) {
+    /**
+     * 日志前缀。默认 `[ReliableEmitter]`；gateway 在创建实例时可注入
+     * 业务通道前缀（如 `[lightclawbot]`），使上游日志风格统一。
+     */
+    logPrefix;
+    constructor(getSocket, log, logPrefix = "[ReliableEmitter]") {
         this.getSocket = getSocket;
         this.log = log;
+        this.logPrefix = logPrefix;
     }
     // ----------------------------------------------------------
     // 公开 API
@@ -34,24 +68,35 @@ export class ReliableEmitter {
     /**
      * 可靠发送 — 带 ACK 确认 + 自动重试。
      *
-     * 每次调用都是独立的发送请求，不会因相同 msgId 被合并。
-     * msgId 仅用于日志追踪，内部使用自增 emitId 作为 pending key。
+     * 与普通 socket.emit 的区别：
+     *   - 每次发送都等待服务端 ACK 回调，超时则自动重试
+     *   - 断线期间消息不丢失，重连后自动补发
+     *   - 消息体自动注入 idempotencyKey，防止重试导致重复处理
      *
-     * @param event  Socket.IO 事件名
-     * @param data   消息体
-     * @param msgId  业务层消息 ID（仅用于日志追踪，可选）
-     * @returns true = server 已确认, false = 重试耗尽未确认
+     * 注意：每次调用都是独立的发送请求，不会因相同 msgId 被合并或去重。
+     * 内部使用自增 emitId 作为 pending Map 的 key、ACK 回路的 pendingKey 及 idempotencyKey。
+     * 业务层 msgId 保留在 data.msgId 中原样发送，同一条消息的所有重试保持相同，服务端用它识别消息身份。
+     *
+     * @param event  WebSocket 事件名（如 "message:private"）
+     * @param data   消息体对象，会被浅拷贝并注入 idempotencyKey
+     * @param msgId  业务层消息 ID，保留在 data.msgId 中不变，可选
+     * @returns      Promise<boolean>：true = 服务端已确认，false = 重试耗尽或被淘汰
      */
     emitWithAck(event, data, msgId) {
         // 每次调用生成唯一的内部 ID，确保同一 msgId 的多次 emit 不会互相覆盖
         const emitId = this.generateEmitId();
         this.stats.totalEmitted++;
-        // 队列满时淘汰最早的
+        // 队列满时淘汰最早的 pending 消息，防止内存无限增长
         this.evictIfNeeded();
         // 为消息体注入 idempotencyKey：
-        // 使用 emitId 作为值，确保同一次 emit 的所有重试都携带相同的 key，
-        // 前端据此去重，避免因 ACK 丢失重发导致用户收到重复消息。
+        //   - 使用 emitId 作为值，每次 emitWithAck 调用唯一
+        //   - 同一次 emit 的所有重试共用同一 emitId，服务端据此去重，避免 ACK 丢失重发导致重复处理
+        //   - idempotencyKey 同时作为 ACK 回路的 pendingKey（NativeSocket 优先取 data.idempotencyKey）
+        //   - 浅拷贝原始 data，不修改调用方传入的对象
+        //   - data.msgId 保持业务层原值不变，同一条消息的所有重试相同，服务端用它识别消息身份
         const enrichedData = { ...data, idempotencyKey: emitId };
+        // 统一的发送日志（含最终 payload），业务层无需再打
+        this.log?.info(`${this.logPrefix} emit: ${JSON.stringify(enrichedData)}`);
         return new Promise((resolve) => {
             const entry = {
                 id: emitId,
@@ -63,59 +108,87 @@ export class ReliableEmitter {
                 retryTimer: null,
                 resolve,
             };
+            // 入队：消息在收到 ACK 或放弃前始终保存在 pending Map 中
             this.pending.set(emitId, entry);
             if (this.paused) {
-                // 断线中，先挂着，resume 时统一重发
-                this.log?.info(`[ReliableEmitter] Queued while paused: emitId=${emitId}, msgId=${msgId}`);
+                // 断线中，等 resume 统一重发
+                this.log?.info(`${this.logPrefix} Queued while paused: emitId=${emitId}, msgId=${msgId}`);
                 return;
             }
+            // 正常状态：立即尝试发送
             this.doEmit(entry);
         });
     }
     /**
-     * 断线时调用 — 暂停所有重试计时器
+     * 断线时调用 — 暂停所有重试计时器。
+     *
+     * 调用后：
+     *   - 所有已安排的重试定时器被清除（retryTimer = null）
+     *   - 新的 emitWithAck 调用仍可入队，但不会立即发送
+     *   - 重试次数计数器不增加（断线等待不算重试）
+     *
+     * 幂等：重复调用无副作用。
      */
     pause() {
         if (this.paused)
             return;
         this.paused = true;
+        // 清除所有待执行的重试定时器，避免断线期间无效的发送尝试
         for (const entry of this.pending.values()) {
             if (entry.retryTimer) {
                 clearTimeout(entry.retryTimer);
                 entry.retryTimer = null;
             }
         }
-        this.log?.info(`[ReliableEmitter] Paused, ${this.pending.size} message(s) pending`);
+        this.log?.info(`${this.logPrefix} Paused, ${this.pending.size} message(s) pending`);
     }
     /**
-     * 重连时调用 — 立即重发所有待确认消息
+     * 重连时调用 — 立即重发所有待确认消息。
+     *
+     * 调用后：
+     *   - 解除暂停状态
+     *   - 遍历 pending Map，对每条消息立即调用 doEmit
+     *   - 断线期间新入队的消息也会在此时被发送
+     *
+     * 幂等：重复调用无副作用。
      */
     resume() {
         if (!this.paused)
             return;
         this.paused = false;
-        this.log?.info(`[ReliableEmitter] Resumed, re-emitting ${this.pending.size} pending message(s)`);
+        this.log?.info(`${this.logPrefix} Resumed, re-emitting ${this.pending.size} pending message(s)`);
         for (const entry of this.pending.values()) {
             this.doEmit(entry);
         }
     }
     /**
-     * 销毁 — 清除所有定时器，resolve 所有 pending 为 false
+     * 销毁 — 清除所有定时器，将所有 pending Promise resolve 为 false。
+     *
+     * 在 gateway 断开连接、插件卸载时调用，防止内存泄漏和悬空定时器。
+     * 调用后此实例不应再被使用。
      */
     destroy() {
         for (const entry of this.pending.values()) {
+            // 清除重试定时器，防止 destroy 后仍有定时器触发
             if (entry.retryTimer)
                 clearTimeout(entry.retryTimer);
+            // 将 Promise resolve 为 false，通知调用方消息未被确认
             entry.resolve(false);
         }
         this.pending.clear();
-        this.log?.info(`[ReliableEmitter] Destroyed`);
+        this.log?.info(`${this.logPrefix} Destroyed`);
     }
-    /** 当前待确认消息数 */
+    /**
+     * 当前待确认消息数（实时值）。
+     * 可用于监控队列积压情况，正常情况下应接近 0。
+     */
     get pendingCount() {
         return this.pending.size;
     }
-    /** 获取统计信息 */
+    /**
+     * 获取运行时统计信息的快照（浅拷贝，不影响内部状态）。
+     * 可用于监控面板、调试日志等场景。
+     */
     getStats() {
         return { ...this.stats, currentPending: this.pending.size };
     }
@@ -123,95 +196,160 @@ export class ReliableEmitter {
     // 内部方法
     // ----------------------------------------------------------
     /**
-     * 通过 socket.timeout(ms).emit(event, data, callback) 发送消息。
+     * 实际执行 socket.emit 的内部方法。
+     *
+     * 发送机制：
+     *   socket.timeout(EMIT_ACK_TIMEOUT).emit(event, data, callback)
+   *   - 超时由 NativeSocketClient 的 .timeout() 处理，无需手动 setTimeout
+     *   - 回调签名为 (err: Error | null)，err 非空表示超时或服务端返回错误
+     *   - socket.emit 是异步的，不会抛同步异常，无需 try-catch
      *
-     * - 超时由 Socket.IO 原生 .timeout() 处理，无需手动 setTimeout
-     * - 回调签名为 (err: Error | null, ...args)，err 非空说明超时或出错
-     * - socket.emit 是异步的，不会抛同步异常，无需 try-catch
+     * 调用时机：
+     *   - emitWithAck 首次发送（非暂停状态）
+     *   - resume 重连后补发
+     *   - scheduleRetry 定时器触发后重试
      */
     doEmit(entry) {
         const socket = this.getSocket();
         if (!socket?.connected) {
-            // socket 不可用，等 resume 时重发（不计重试次数）
+            // socket 不可用（断线或尚未连接），不计重试次数，等 resume() 时重发
             return;
         }
-        socket.timeout(EMIT_ACK_TIMEOUT).emit(entry.event, entry.data, (err) => {
-            // 已被 destroy 或 confirm
+        // 直接使用 entry.data 作为发送数据，字段职责说明：
+        //   - data.msgId：业务层消息 ID，同一条消息所有重试相同，服务端 ACK 通过 relatedMsgId 原样回传
+        //   - data.idempotencyKey：= emitId，每次 emitWithAck 调用唯一，仅用于服务端去重，不参与 ACK 匹配
+        //   - ACK 回路：NativeSocket 以 data.msgId 为 pendingKey 注册，服务端 ACK relatedMsgId = msgId，两者一致，回路正常闭合
+        const sendData = entry.data;
+        socket
+            .timeout(EMIT_ACK_TIMEOUT)
+            .emit(entry.event, sendData, (err) => {
+            // 防御性检查：消息可能在等待 ACK 期间被 destroy() 或 confirm() 移除
             if (!this.pending.has(entry.id))
                 return;
             if (err) {
-                // 超时或服务端回传了错误
+                // ACK 超时或服务端返回错误，安排下一次重试
                 this.log?.warn(`[ReliableEmitter] ACK error: emitId=${entry.id}, msgId=${entry.msgId}, err=${err.message}, retryCount=${entry.retryCount}`);
                 this.scheduleRetry(entry);
             }
             else {
-                this.log?.info(`[ReliableEmitter] ACK success: emitId=${entry.id}, msgId=${entry.msgId}, retryCount=${entry.retryCount}`);
-                // 服务端已确认
+                // 服务端已确认收到，从 pending 队列移除
+                // this.log?.info(
+                //   `[ReliableEmitter] ACK success: emitId=${entry.id}, msgId=${entry.msgId}, retryCount=${entry.retryCount}`,
+                // );
                 this.confirm(entry.id);
             }
         });
     }
+    /**
+     * 确认消息已送达，从 pending 队列移除并 resolve Promise 为 true。
+     * 幂等：若消息已被移除（重复 ACK 或已 destroy），直接返回。
+     */
     confirm(id) {
         const entry = this.pending.get(id);
         if (!entry)
-            return; // 已被 confirm 或 destroy
+            return; // 已被 confirm 或 destroy，幂等处理
+        // 清除可能存在的重试定时器（理论上 ACK 成功时不应有，但做防御性清理）
         if (entry.retryTimer) {
             clearTimeout(entry.retryTimer);
             entry.retryTimer = null;
         }
         this.pending.delete(id);
         this.stats.totalConfirmed++;
+        // 通知调用方：消息已被服务端确认
         entry.resolve(true);
     }
+    /**
+     * 安排下一次重试，使用指数退避 + 随机抖动策略。
+     *
+     * 重试流程：
+     *   1. 若当前处于暂停状态（断线），不安排重试，等 resume() 统一处理
+     *   2. 若重试次数已达上限（EMIT_MAX_RETRIES），放弃并 resolve false
+     *   3. 否则计算延迟时间，设置定时器，到期后调用 doEmit
+     */
     scheduleRetry(entry) {
-        // 断线中不重试
+        // 断线中不安排重试，等 resume() 时由 doEmit 统一重发
         if (this.paused)
             return;
         if (entry.retryCount >= EMIT_MAX_RETRIES) {
-            // 重试耗尽
+            // 重试次数耗尽，放弃该消息
             this.pending.delete(entry.id);
             this.stats.totalFailed++;
-            this.log?.error(`[ReliableEmitter] Gave up after ${entry.retryCount} retries: emitId=${entry.id}, msgId=${entry.msgId}, ` +
+            this.log?.error(`${this.logPrefix} Gave up after ${entry.retryCount} retries: emitId=${entry.id}, msgId=${entry.msgId}, ` +
                 `elapsed=${Date.now() - entry.createdAt}ms`);
+            // 通知调用方：消息最终未被确认
             entry.resolve(false);
             return;
         }
+        // 增加重试计数（先加后用，确保 getRetryDelay 收到正确的重试序号）
         entry.retryCount++;
         this.stats.totalRetries++;
         const delay = this.getRetryDelay(entry.retryCount);
-        this.log?.info(`[ReliableEmitter] Retry #${entry.retryCount} in ${delay}ms: emitId=${entry.id}, msgId=${entry.msgId}`);
+        this.log?.info(`${this.logPrefix} Retry #${entry.retryCount} in ${delay}ms: emitId=${entry.id}, msgId=${entry.msgId}`);
         entry.retryTimer = setTimeout(() => {
             entry.retryTimer = null;
+            // 定时器触发时再次检查是否断线（重试等待期间可能发生断线）
             if (this.paused)
-                return; // 重试期间断线了
+                return;
             this.doEmit(entry);
         }, delay);
     }
     /**
-     * 指数退避 + 随机抖动
-     * delay = min(base * 2^(retryCount-1) + jitter, maxDelay)
+     * 计算重试延迟时间（指数退避 + 随机抖动）。
+     *
+     * 公式：delay = min(base × 2^(retryCount-1) + jitter, maxDelay)
+     *
+     * 示例（base=1000ms, max=30000ms）：
+     *   第 1 次重试：~1000ms + jitter
+     *   第 2 次重试：~2000ms + jitter
+     *   第 3 次重试：~4000ms + jitter
+     *   第 4 次重试：~8000ms + jitter
+     *   第 5 次重试：~16000ms + jitter（若超过 maxDelay 则取 maxDelay）
+     *
+     * 随机抖动（0~1000ms）的作用：
+     *   防止多个客户端在同一时刻同时重试，避免服务端瞬间收到大量重试请求（惊群效应）。
+     *
+     * @param retryCount - 当前重试序号（从 1 开始）
      */
     getRetryDelay(retryCount) {
         const base = EMIT_RETRY_BASE_DELAY * Math.pow(2, retryCount - 1);
         const jitter = Math.random() * 1000;
         return Math.min(base + jitter, EMIT_RETRY_MAX_DELAY);
     }
-    /** 队列满时淘汰最早的 pending 消息 */
+    /**
+     * 队列容量保护：当 pending 消息数达到上限（EMIT_PENDING_MAX）时，
+     * 按 FIFO 顺序淘汰最早入队的消息，防止内存无限增长。
+     *
+     * 触发场景：网络长时间中断且消息持续入队时。
+     * Map 的迭代顺序与插入顺序一致，因此 values().next().value 即为最早的消息。
+     */
     evictIfNeeded() {
         while (this.pending.size >= EMIT_PENDING_MAX) {
+            // Map 按插入顺序迭代，第一个即为最早入队的消息
             const oldest = this.pending.values().next().value;
             if (!oldest)
                 break;
+            // 清除重试定时器，防止被淘汰后仍触发重试
             if (oldest.retryTimer)
                 clearTimeout(oldest.retryTimer);
             this.pending.delete(oldest.id);
             this.stats.totalFailed++;
-            this.log?.warn(`[ReliableEmitter] Evicted oldest pending: emitId=${oldest.id}, msgId=${oldest.msgId}`);
+            this.log?.warn(`${this.logPrefix} Evicted oldest pending: emitId=${oldest.id}, msgId=${oldest.msgId}`);
             oldest.resolve(false);
         }
     }
+    /**
+     * 生成 emitId，同时用作 pending Map 的 key、ACK 回路的 pendingKey 及 idempotencyKey。
+     *
+     * 格式：`_re_<16位毫秒时间戳>_<12位自增序号>`，例：`_re_0001776656562000_000000000042`
+     *
+     * 设计约束：
+     *   - 固定宽度十进制：保证字典序 == 生成顺序
+     *   - 每次 emitWithAck 调用生成唯一 id，同一次 emit 的所有重试共用同一 id
+     *   - 注入为 data.idempotencyKey，NativeSocket 优先取此字段作为 pendingKey
+     */
     generateEmitId() {
-        return `_re_${Date.now().toString(36)}_${(this.idCounter++).toString(36)}`;
+        const ts = Date.now().toString().padStart(16, "0");
+        const seq = (this.idCounter++).toString().padStart(12, "0");
+        return `_re_${ts}_${seq}`;
     }
 }
-//# sourceMappingURL=reliable-emitter.js.map

package/dist/src/streaming/delta-tracker.js

@@ -0,0 +1,140 @@
+/**
+ * LightClaw — 文本增量计算器 (DeltaTracker)
+ *
+ * 核心作用：
+ *   AI 引擎的 `onPartialReply` 回调输出的文本格式不确定 —— 有的模型输出全量快照（snapshot），
+ *   有的输出纯增量（delta），甚至可能在同一次对话中混合使用。
+ *   DeltaTracker 会自动检测模式，始终输出 **纯增量文本**，方便直接追加到流式推送中。
+ *
+ * 算法概述：
+ *   1. 维护 `{ latest, mode, lastEmitted, localSnapshot }` 状态
+ *   2. 新文本到达时，判断其与 `latest` 的关系：
+ *      - 如果新文本以 latest 为前缀 → snapshot 模式，截取增量
+ *      - 如果新文本与 latest 有较长公共前缀 → snapshot 模式（可能是局部重传）
+ *      - 如果上述均不满足 → delta 模式，直接追加
+ *   3. 各种边界处理：重复文本、前缀回退、模式切换等
+ */
+// ============================================================
+// 公共工具
+// ============================================================
+/** 计算两个字符串的最长公共前缀长度 */
+function longestCommonPrefixLength(a, b) {
+    const len = Math.min(a.length, b.length);
+    let i = 0;
+    while (i < len && a[i] === b[i]) {
+        i += 1;
+    }
+    return i;
+}
+// ============================================================
+// 核心 API
+// ============================================================
+/**
+ * 创建一个新的增量追踪器状态。
+ */
+export function createDeltaTrackerState() {
+    return {
+        latest: "",
+        mode: "unknown",
+        lastEmitted: "",
+        localSnapshot: undefined,
+    };
+}
+/**
+ * 将传入的文本（可能是快照或增量）转换为纯增量文本。
+ *
+ * @param state - 增量追踪器状态（会被就地修改）
+ * @param text  - AI 引擎传入的文本
+ * @returns 需要追加发送的增量文本；如果无新增量则返回 `undefined`
+ */
+export function toStreamDeltaText(state, text) {
+    if (typeof text !== "string" || text.length === 0)
+        return undefined;
+    const incoming = text;
+    const previous = state.latest;
+    const currentMode = state.mode ?? "unknown";
+    // ── 首次接收 ──
+    if (!previous) {
+        state.latest = incoming;
+        state.mode = "unknown";
+        state.lastEmitted = incoming;
+        state.localSnapshot = undefined;
+        return incoming;
+    }
+    // ── 完全相同 → 无增量 ──
+    if (incoming === previous) {
+        state.localSnapshot = undefined;
+        return undefined;
+    }
+    // ── 新文本以 previous 为前缀 → snapshot 模式 ──
+    if (incoming.startsWith(previous)) {
+        state.latest = incoming;
+        state.mode = "snapshot";
+        const delta = incoming.slice(previous.length);
+        state.localSnapshot = undefined;
+        if (delta.length > 0) {
+            state.lastEmitted = delta;
+            return delta;
+        }
+        return undefined;
+    }
+    // ── 部分公共前缀分析 ──
+    const commonLen = longestCommonPrefixLength(previous, incoming);
+    if (incoming.length - previous.length > 0 &&
+        commonLen > 0 &&
+        (currentMode === "snapshot" ||
+            commonLen >= Math.max(8, Math.floor(0.75 * previous.length)) ||
+            previous.length >= 64 ||
+            incoming.length >= 128 ||
+            incoming.length >= 2 * previous.length)) {
+        state.latest = incoming;
+        state.mode = "snapshot";
+        const delta = incoming.slice(commonLen);
+        state.localSnapshot = undefined;
+        if (delta.length > 0) {
+            state.lastEmitted = delta;
+            return delta;
+        }
+        return undefined;
+    }
+    // ── localSnapshot 追踪（delta 模式下的累计快照校验） ──
+    if (typeof state.localSnapshot === "string" && state.localSnapshot.length > 0) {
+        if (incoming === state.localSnapshot) {
+            return undefined;
+        }
+        if (incoming.startsWith(state.localSnapshot)) {
+            const delta = incoming.slice(state.localSnapshot.length);
+            state.latest = `${previous}${delta}`;
+            state.mode = "snapshot";
+            state.localSnapshot = incoming;
+            if (delta.length > 0) {
+                state.lastEmitted = delta;
+                return delta;
+            }
+            return undefined;
+        }
+        state.localSnapshot = undefined;
+    }
+    // ── 前缀回退（新文本是旧文本的前缀）→ 忽略 ──
+    if (previous.startsWith(incoming)) {
+        if (currentMode === "snapshot") {
+            state.latest = incoming;
+        }
+        state.localSnapshot = undefined;
+        return undefined;
+    }
+    // ── snapshot 模式下的重复增量检测 ──
+    if (currentMode === "snapshot" &&
+        typeof state.lastEmitted === "string" &&
+        incoming === state.lastEmitted &&
+        previous.endsWith(incoming)) {
+        state.localSnapshot = undefined;
+        return undefined;
+    }
+    // ── 兜底：视为 delta 模式，直接追加 ──
+    state.latest = `${previous}${incoming}`;
+    state.mode = "delta";
+    state.lastEmitted = incoming;
+    state.localSnapshot = incoming;
+    return incoming;
+}

package/dist/src/streaming/index.js

@@ -0,0 +1,12 @@
+/**
+ * LightClaw — 流式输出模块
+ *
+ * 统一导出流式输出相关的类型、工具和分发器。
+ *
+ * 使用方式：
+ *   import { createStreamReplyConfig } from "./streaming/index.js";
+ */
+// 增量计算器
+export { createDeltaTrackerState, toStreamDeltaText } from "./delta-tracker.js";
+// 真流式回复配置（dispatcher + replyOptions，用于 dispatchReplyFromConfig）
+export { createStreamReplyConfig } from "./stream-reply-sink.js";