@xmanrui/dsh-im 4.12.0 → 4.14.0

package/src/channels/feishu/bridge.mjs

@@ -56,6 +56,7 @@ import {
   workspacePathSnapshot,
 } from '../shared/workspace-command.mjs';
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
+import { createDeferredDeliveryCoordinator, deferredOutcomeText } from '../shared/deferred-delivery-coordinator.mjs';
 import { captureContextEnhancement, enhanceContextContent } from '../shared/context-enhancement.mjs';
 import { deliverOutboundArtifacts } from '../shared/semantic/artifact-delivery.mjs';
 import {
@@ -156,6 +157,77 @@ const ARCHIVED_COMMAND = /^\/archived(?:\s+(on|off))?$/i;
 /** Matches fast card commands that should not be queued behind a running task. */
 const CARD_COMMAND = /^\/(?:m(?:enu)?|new|help|status|compact|(?:sessionlist|sessions)(?:\s|$)|workspacelist|workspaces|wsl|watchlist|archived(?:\s+(on|off))?)$/i;
 
+// ── Step push (分步直推) limits ──────────────────────────────────────────────
+/** Feishu allows 5 msg/s per chat; step push stays well below that. */
+const STEP_PUSH_MIN_INTERVAL_MS = 250;
+/** One turn never pushes more step messages than this (熔断阈值). */
+const STEP_PUSH_MAX_MESSAGES_PER_TURN = 200;
+/** Excerpt bounds for step push message rendering. */
+const STEP_PUSH_SUMMARY_MAX_CHARS = 120;
+const STEP_PUSH_ARGUMENTS_MAX_CHARS = 400;
+const STEP_PUSH_ERROR_MAX_CHARS = 200;
+/** One post message carries at most this many UTF-8 bytes after its rich-text
+ *  content has been JSON encoded (Feishu caps rich-text requests at 30KB). */
+const STEP_PUSH_POST_CHUNK_MAX_BYTES = 24_000;
+
+/** Split one markdown answer into post-sized chunks at paragraph bounds,
+ *  budgeted by the encoded rich-text content rather than the source string.
+ *  This accounts for both CJK bytes and JSON escape expansion. */
+function splitStepPostMarkdown(text, limit = STEP_PUSH_POST_CHUNK_MAX_BYTES) {
+  const source = String(text ?? '');
+  const encodedBytes = (markdown) => Buffer.byteLength(JSON.stringify({
+    zh_cn: { content: [[{ tag: 'md', text: markdown }]] },
+  }), 'utf8');
+  if (encodedBytes(source) <= limit) return [source];
+  const chunks = [];
+  let remaining = source;
+  while (encodedBytes(remaining) > limit) {
+    let lo = 0;
+    let hi = remaining.length;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (encodedBytes(remaining.slice(0, mid)) <= limit) lo = mid;
+      else hi = mid - 1;
+    }
+    let cut = lo;
+    const preferFrom = Math.floor(cut * 0.6);
+    const softCut = remaining.lastIndexOf('\n\n', cut);
+    if (softCut >= preferFrom) {
+      cut = softCut;
+    } else {
+      const lineCut = remaining.lastIndexOf('\n', cut);
+      if (lineCut >= preferFrom) cut = lineCut;
+    }
+    if (cut <= 0) cut = lo;
+    // JavaScript indexes strings by UTF-16 code unit. Never split between a
+    // high and low surrogate, which would turn one emoji into two replacement
+    // characters across adjacent messages.
+    const before = remaining.charCodeAt(cut - 1);
+    const after = remaining.charCodeAt(cut);
+    if (before >= 0xD800 && before <= 0xDBFF && after >= 0xDC00 && after <= 0xDFFF) {
+      cut -= 1;
+    }
+    if (cut <= 0) {
+      throw new RangeError('Feishu step push post byte limit is too small');
+    }
+    chunks.push(remaining.slice(0, cut));
+    remaining = remaining.slice(cut).trimStart();
+  }
+  if (remaining) chunks.push(remaining);
+  return chunks;
+}
+/** Salient tool-argument fields for the intent summary, in priority order. */
+const STEP_PUSH_INTENT_FIELDS = [
+  'command', 'file_path', 'path', 'query', 'url', 'pattern', 'prompt', 'cmd',
+];
+/** Bounds the per-conversation step push send-state cache. */
+const MAX_STEP_PUSH_SEND_STATES = 512;
+/** Real clock used by step push throttling; tests inject a fake one. */
+const DEFAULT_STEP_PUSH_CLOCK = Object.freeze({
+  now: () => Date.now(),
+  delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+});
+
 /** Pretty-print a tool call's arguments for an approval card. */
 function operationArguments(toolCall) {
   const source = toolCall?.arguments;
@@ -246,6 +318,11 @@ function answerTextForDelivery(answer, artifacts) {
   return artifacts.length > 0 ? t('结果文件已生成。') : answer;
 }
 
+/** Collapse a step push excerpt into one tidy line. */
+function stepPushLine(value) {
+  return String(value ?? '').replace(/\s+/gu, ' ').trim();
+}
+
 function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
@@ -488,6 +565,12 @@ export class FeishuHarnessBridge {
   #groupResponseMode;
   /** When true, group replies that belong to a Feishu topic ask reply_in_thread. */
   #groupTopicReply = false;
+  /** When true, streaming turns push tool calls and interim notes as discrete messages. */
+  #stepPush = false;
+  /** Per-conversation step push state: key → { lastSentAt, count, breakerLogged }. */
+  #stepPushSendState = new Map();
+  /** Injectable clock for step push throttling (tests pass a fake one). */
+  #stepPushClock;
   /** Group chats this bot has seen; only these may use topic replies. */
   #groupChatIds = new Set();
   /** Anchor message id → whether its replies should stay in a Feishu topic. */
@@ -505,6 +588,7 @@ export class FeishuHarnessBridge {
   #cardKeys = new Map();
   /** The global event-mux watcher (one per bridge). */
   #eventWatcher = null;
+  #deferred;
   /** Serializes completion work per session without blocking unrelated sessions. */
   #eventTails = new Map();
   /** Coalesces baseline compensation and records whether a trailing pass is needed. */
@@ -531,6 +615,8 @@ export class FeishuHarnessBridge {
     botOpenId,
     groupResponseMode = FEISHU_GROUP_RESPONSE_MODES.ALL,
     groupTopicReply = false,
+    stepPush = false,
+    stepPushClock = null,
     repair,
     repairPollIntervalMs = REPAIR_POLL_INTERVAL_MS,
     repairLinkWaitMs = REPAIR_LINK_WAIT_MS,
@@ -558,6 +644,12 @@ export class FeishuHarnessBridge {
       || !Number.isFinite(cardDataTimeoutMs) || cardDataTimeoutMs <= 0) {
       throw new TypeError('Feishu timing values must be positive numbers');
     }
+    if (stepPushClock !== null
+      && (typeof stepPushClock !== 'object' || Array.isArray(stepPushClock)
+        || typeof stepPushClock.now !== 'function'
+        || typeof stepPushClock.delay !== 'function')) {
+      throw new TypeError('Feishu step push clock requires now and delay functions');
+    }
     this.#client = client;
     this.#channel = channel;
     this.#harness = harness;
@@ -571,6 +663,8 @@ export class FeishuHarnessBridge {
     this.#botOpenId = nonEmptyString(botOpenId);
     this.#groupResponseMode = normalizeFeishuGroupResponseMode(groupResponseMode);
     this.#groupTopicReply = groupTopicReply === true;
+    this.#stepPush = stepPush === true;
+    this.#stepPushClock = stepPushClock ?? DEFAULT_STEP_PUSH_CLOCK;
     this.#repair = repair ?? null;
     this.#repairPollIntervalMs = repairPollIntervalMs;
     this.#repairLinkWaitMs = repairLinkWaitMs;
@@ -581,10 +675,16 @@ export class FeishuHarnessBridge {
     this.#approvals = new HarnessApprovalQueue({ label: 'Feishu', logger });
     this.#signal = signal;
     ensureStatus(this.#status);
+    this.#deferred = createDeferredDeliveryCoordinator({
+      harness, state, signal, logger, watch: false,
+      deliver: (entry, outcome) => this.#deliverDeferredOutcome(entry, outcome),
+    });
     // Persisted watches must resume at runtime start, not on the first
     // message. Older hosts without the mux watcher simply skip this.
     if (typeof this.#harness?.watchHarnessEvents === 'function') {
-      queueMicrotask(() => this.#ensureEventWatcher());
+      queueMicrotask(() => {
+        this.#ensureEventWatcher();
+      });
     }
   }
 
@@ -596,6 +696,10 @@ export class FeishuHarnessBridge {
     this.#groupTopicReply = value === true;
   }
 
+  setStepPush(value) {
+    this.#stepPush = value === true;
+  }
+
   #isAddressed(event) {
     if (event?.message?.chat_type === 'p2p') return true;
     const mentions = Array.isArray(event?.message?.mentions) ? event.message.mentions : [];
@@ -631,10 +735,13 @@ export class FeishuHarnessBridge {
   /**
    * Record whether replies anchored on `messageId` should stay in a topic.
    * `asRoot` marks a main-feed question this bot will auto-open as a topic.
+   * The flag is keyed on the conversation shape alone: once a conversation is
+   * happening inside a topic, its replies belong to that topic whether the
+   * bot auto-opens topics (群话题回复) or the user maintains them manually.
    */
   #rememberTopicReply(messageId, key) {
     if (!nonEmptyString(messageId)) return;
-    this.#anchorTopicReply.set(messageId, this.#groupTopicReply && isTopicGroupKey(key));
+    this.#anchorTopicReply.set(messageId, isTopicGroupKey(key));
     if (this.#anchorTopicReply.size > 2048) {
       const oldest = this.#anchorTopicReply.keys().next().value;
       if (oldest !== undefined) this.#anchorTopicReply.delete(oldest);
@@ -647,8 +754,10 @@ export class FeishuHarnessBridge {
 
   /** Whether a reply anchored on `replyTo` must ask Feishu to keep it in a topic. */
   #replyInThreadFor(replyTo) {
-    return this.#groupTopicReply
-      && nonEmptyString(replyTo)
+    // Topic membership is decided by the conversation shape alone (see
+    // #rememberTopicReply): a manual-topic chat threads its replies even
+    // when the 群话题回复 switch is off.
+    return nonEmptyString(replyTo)
       && this.#anchorTopicReply.get(replyTo) === true;
   }
 
@@ -1128,6 +1237,7 @@ export class FeishuHarnessBridge {
     // Drain to a fixed point: awaited work can register compensation or
     // another serialized tail before it settles.
     for (;;) {
+      await this.#deferred.whenIdle();
       const tasks = [
         ...this.#queues.values(),
         ...[...this.#pendingInteractions.values()].flatMap((pending) => (
@@ -1141,6 +1251,7 @@ export class FeishuHarnessBridge {
       ];
       if (tasks.length === 0) return;
       await Promise.allSettled(tasks);
+      await this.#deferred.whenIdle();
       if (this.#queues.size === 0
         && this.#interactionTasks.size === 0
         && this.#commandTasks.size === 0
@@ -1166,7 +1277,7 @@ export class FeishuHarnessBridge {
     await this.#state.markSeen(messageId);
     this.#status.lastMessageAt = new Date().toISOString();
     this.#status.messagesReceived += 1;
-    const result = await runner(
+    let result = await runner(
       nonEmptyString(message.content) ?? '',
       this.#harness,
       this.#state,
@@ -1175,6 +1286,7 @@ export class FeishuHarnessBridge {
         signal: this.#signal,
         isDirect: event.message.chat_type === 'p2p',
         hasImages: hasInboundImages(message),
+        deferredDelivery: this.#deferred,
         hasFiles: hasInboundFiles(message),
         pendingInteraction: this.#hasPendingInteraction(key),
         control: { owner: this, key },
@@ -2831,7 +2943,7 @@ export class FeishuHarnessBridge {
    */
   async #handleStop(key, chatId, replyTo = null) {
     try {
-      const result = await runControlCommand(
+      let result = await runControlCommand(
         '/stop', this.#harness, this.#state, key, {
           signal: this.#signal,
           control: { owner: this, key },
@@ -2952,6 +3064,61 @@ export class FeishuHarnessBridge {
 
   // ── Watches: read-only session tracking + completion pushes ─────────────
 
+  // ── Deferred delivery (MODEL_REPLY_TIMEOUT → late result push) ──────────
+
+  async #deliverDeferredOutcome(entry, outcome) {
+    this.#rememberTopicReply(entry.replyToMessageId, entry.key);
+    if (entry.key === managedGroupKey(entry.chatId, entry.replyToMessageId)) {
+      this.#rememberTopicRoot(entry.replyToMessageId);
+    }
+    const text = deferredOutcomeText(outcome);
+    if (outcome.found) {
+      return this.#deliverDeferredText(entry.chatId, answerTextForDelivery(text, []), entry.replyToMessageId);
+    }
+    await this.#send(entry.chatId, text, { replyTo: entry.replyToMessageId });
+    return true;
+  }
+
+  async #deliverDeferredText(chatId, markdownText, replyToMessageId) {
+    if (this.#channel?.stream) {
+      try {
+        await this.#channel.stream(chatId, {
+          markdown: async (controller) => {
+            await controller.setContent(markdownText);
+          },
+        }, {
+          ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+          ...(this.#replyInThreadFor(replyToMessageId) ? {
+            replyInThread: true,
+            onReplyThreadId: async (threadId) => this.#registerTopicThreadId(
+              threadId,
+              replyToMessageId,
+              chatId,
+            ),
+          } : {}),
+        });
+        return true;
+      } catch (error) {
+        if (error?.deliveryOutcome === 'unknown') throw error;
+        this.#logger.warn?.(
+          '[dsh-feishu] deferred stream delivery failed; falling back to text:',
+          error.message,
+        );
+      }
+    }
+    try {
+      await this.#sendAnswerText(chatId, markdownText, {
+        deliveryId: `deferred-${Date.now()}`,
+        presentation: 'feishu-deferred-text',
+        ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+      });
+      return true;
+    } catch (error) {
+      this.#logger.warn?.('[dsh-feishu] deferred text delivery failed:', error.message);
+      throw error;
+    }
+  }
+
   #ensureEventWatcher() {
     if (this.#eventWatcher) return;
     if (typeof this.#harness?.watchHarnessEvents !== 'function') return;
@@ -2963,6 +3130,7 @@ export class FeishuHarnessBridge {
         onSessionEvent: (payload) => this.#onHarnessEvent(payload),
         onReconnect: () => {
           void this.#compensateMissedEvents();
+          void this.#deferred.resume();
         },
       });
       Promise.resolve(this.#eventWatcher).catch((error) => {
@@ -3321,6 +3489,7 @@ export class FeishuHarnessBridge {
         .some((key) => this.#failedWatchSeqs.has(`${key}\0${sessionId}`));
       if (needsBaseline || hasFailedDelivery) await this.#compensateSession(sessionId);
       await this.#deliverCompletion(sessionId, event);
+      await this.#deferred.onEvent({ sessionId, event });
     });
   }
 
@@ -3535,6 +3704,405 @@ export class FeishuHarnessBridge {
     };
   }
 
+  // ── Step push (分步直推) ──────────────────────────────────────────────────
+
+  /** One-line intent summary built from a tool call's JSON arguments. */
+  #stepIntentSummary(argumentsText) {
+    if (typeof argumentsText !== 'string' || !argumentsText.trim()) return null;
+    let source = null;
+    try {
+      const parsed = JSON.parse(argumentsText);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        for (const field of STEP_PUSH_INTENT_FIELDS) {
+          const value = parsed[field];
+          if (typeof value === 'string' && value.trim()) {
+            source = value;
+            break;
+          }
+          if (typeof value === 'number' && Number.isFinite(value)) {
+            source = String(value);
+            break;
+          }
+        }
+      }
+    } catch {
+      source = argumentsText;
+    }
+    if (source === null) return null;
+    return stepPushLine(source).slice(0, STEP_PUSH_SUMMARY_MAX_CHARS) || null;
+  }
+
+  /** Render one tool call as a rich-text post: headline + folded code block. */
+  #formatStepToolPost(update) {
+    const summary = this.#stepIntentSummary(update.arguments);
+    const name = stepPushLine(update.name) || t('工具');
+    const headline = `✅ ${name}${summary ? ` — ${summary}` : ''}`;
+    const detail = typeof update.arguments === 'string' && update.arguments
+      ? update.arguments.slice(0, STEP_PUSH_ARGUMENTS_MAX_CHARS)
+      : '';
+    const paragraphs = [[{ tag: 'text', text: headline }]];
+    if (detail) {
+      const language = /^\s*[[{]/.test(detail) ? 'JSON' : undefined;
+      paragraphs.push(language
+        ? [{ tag: 'code_block', language, text: detail }]
+        : [{ tag: 'code_block', text: detail }]);
+    }
+    return {
+      paragraphs,
+      fallbackText: detail ? `${headline}\n▸ ${detail}` : headline,
+    };
+  }
+
+  /**
+   * Push one step message through the conversation's serial step queue: the
+   * 250ms minimum interval guards Feishu's 5 QPS per-chat limit, and a turn
+   * past the message cap stays silent (circuit breaker) while the final
+   * answer still follows. Send failures are logged, never thrown — a flaky
+   * step message must never break the turn.
+   */
+  async #sendStepMessage(chatId, key, paragraphs, fallbackText, replyToMessageId = null, { billable = true } = {}) {
+    const state = this.#stepPushSendState.get(key)
+      ?? { lastSentAt: 0, count: 0, breakerLogged: false };
+    this.#stepPushSendState.set(key, state);
+    if (billable && state.count >= STEP_PUSH_MAX_MESSAGES_PER_TURN) {
+      if (!state.breakerLogged) {
+        state.breakerLogged = true;
+        this.#logger.warn?.(
+          `[dsh-feishu] step push hit ${STEP_PUSH_MAX_MESSAGES_PER_TURN} messages for this turn; staying silent until it ends`,
+        );
+      }
+      return;
+    }
+    this.#signal?.throwIfAborted();
+    const wait = state.lastSentAt + STEP_PUSH_MIN_INTERVAL_MS - this.#stepPushClock.now();
+    if (wait > 0) await this.#stepPushClock.delay(wait);
+    // /stop or shutdown during the wait window must not let the queued
+    // message land after the teardown has begun.
+    this.#signal?.throwIfAborted();
+    state.lastSentAt = this.#stepPushClock.now();
+    if (billable) state.count += 1;
+    this.#status.streamUpdates = (this.#status.streamUpdates ?? 0) + 1;
+    await this.#sendStepPost(chatId, replyToMessageId, paragraphs, fallbackText);
+  }
+
+  /**
+   * Rich-text (post) delivery for step messages. Degradation ladder:
+   * post（限流重试 ×2）→ 同话题纯文本回复 → 主界面纯文本。Returns
+   * `{ ok, messageId?, error? }` — callers decide whether a failure is
+   * tolerable (process notes: log and continue) or fatal (final answer:
+   * surface it).
+   */
+  async #sendStepPost(chatId, replyToMessageId, paragraphs, fallbackText) {
+    const content = JSON.stringify({ zh_cn: { content: paragraphs } });
+    if (!replyToMessageId) {
+      const sentId = await this.#send(chatId, fallbackText);
+      return { ok: true, messageId: typeof sentId === 'string' ? sentId : null };
+    }
+    const replyInThread = this.#replyInThreadFor(replyToMessageId);
+    let lastError = null;
+    // 1) 富文本 post；限流/瞬时失败重试两次（结构化 code 感知）。
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      try {
+        const response = await this.#replyStepMessage(
+          chatId, replyToMessageId, 'post', content, replyInThread,
+        );
+        return {
+          ok: true,
+          messageId: nonEmptyString(response?.data?.message_id) ?? null,
+        };
+      } catch (error) {
+        lastError = error;
+        if (attempt < 2 && this.#isRetriableSendError(error)) {
+          await new Promise((resolve) => setTimeout(resolve, 300 * (attempt + 1)));
+          continue;
+        }
+        break;
+      }
+    }
+    // 2) 明确降级：仅富文本格式被拒时，话题内纯文本回复仍然可用——
+    //    优先留在话题内，而不是直接漏到主界面。
+    try {
+      const response = await this.#replyStepMessage(
+        chatId, replyToMessageId, 'text', JSON.stringify({ text: fallbackText }), replyInThread,
+      );
+      return {
+        ok: true,
+        messageId: nonEmptyString(response?.data?.message_id) ?? null,
+      };
+    } catch (error) {
+      lastError = lastError ?? error;
+    }
+    // 3) 最后兜底：主界面纯文本。
+    this.#logger.warn?.(
+      '[dsh-feishu] step push post failed; falling back to main chat text:',
+      lastError?.message ?? String(lastError),
+    );
+    try {
+      const sentId = await this.#send(chatId, fallbackText);
+      return { ok: true, messageId: typeof sentId === 'string' ? sentId : null };
+    } catch (fallbackError) {
+      this.#logger.warn?.(
+        '[dsh-feishu] step push send failed:',
+        fallbackError?.message ?? String(fallbackError),
+      );
+      return { ok: false, error: lastError ?? fallbackError };
+    }
+  }
+
+  /** Reply with one msg_type; throws errors carrying the structured Feishu code. */
+  async #replyStepMessage(chatId, messageId, msgType, contentString, replyInThread) {
+    const response = await this.#client.im.v1.message.reply({
+      path: { message_id: messageId },
+      data: {
+        msg_type: msgType,
+        content: contentString,
+        ...(replyInThread ? { reply_in_thread: true } : {}),
+      },
+    });
+    if (response?.code && response.code !== 0) {
+      const error = new Error(`Feishu reply failed: ${response.msg || response.code}`);
+      // Preserve the structured code: rate-limit detection must not depend on
+      // the human-readable message surviving.
+      error.code = response.code;
+      error.feishuCode = response.code;
+      throw error;
+    }
+    const threadId = nonEmptyString(response?.data?.thread_id);
+    if (threadId) {
+      await this.#registerTopicThreadId(threadId, messageId, chatId);
+    }
+    return response;
+  }
+
+  /** Rate-limit / transient send errors are worth one more attempt. */
+  #isRetriableSendError(error) {
+    const structured = [error?.code, error?.feishuCode, error?.response?.data?.code]
+      .map((value) => String(value ?? ''));
+    return structured.some((code) => code === '230020' || code === '230006')
+      || /230020|230006/.test(error?.message ?? '');
+  }
+
+  /**
+   * 分步直推：`#answerWithStream` 流式分支在开关开启时的完整替代路径。
+   * 过程（工具调用、助手中间说明）与最终答案均以富文本 post 逐条直推
+   * （工具参数折叠为代码块）；post 失败走既有纯文本降级。
+   */
+  async #answerWithStepPush(event, key, message, { onAskComplete } = {}) {
+    const chatId = event.message.chat_id;
+    const messageId = event.message.message_id;
+    const text = message.content;
+    let askCompleted = false;
+    const markAskComplete = () => {
+      if (askCompleted) return;
+      askCompleted = true;
+      onAskComplete?.();
+    };
+    // 与流式分支一致的提示内容构造：图片与回复引用展开为富提示内容，已接受
+    // 的上下文增强按原样重放。直推分流发生在 `#answerWithStream` 构造之前，
+    // 这里就是本回合唯一一次构造（无重复的 prompt 往返）。
+    let content = hasInboundImages(message) || hasReplyReference(message)
+      ? await promptContentForInboundMessage(message, { signal: this.#signal })
+      : undefined;
+    const snapshot = this.#acceptedMessageIds.get(messageId);
+    let contextEnhanced = false;
+    if (snapshot) {
+      const originalContent = content ?? text;
+      content = enhanceContextContent(originalContent, snapshot, () => ({
+        channel: 'feishu',
+        senderId: senderOpenId(event),
+        chatId: event.message.chat_id,
+        threadId: event.message.thread_id,
+      }));
+      contextEnhanced = content !== originalContent;
+    }
+    // Every turn reopens the per-conversation circuit breaker.
+    const priorState = this.#stepPushSendState.get(key);
+    if (this.#stepPushSendState.size >= MAX_STEP_PUSH_SEND_STATES && !priorState) {
+      const oldest = this.#stepPushSendState.keys().next().value;
+      if (oldest !== undefined) this.#stepPushSendState.delete(oldest);
+    }
+    this.#stepPushSendState.set(key, {
+      lastSentAt: priorState?.lastSentAt ?? 0,
+      count: 0,
+      breakerLogged: false,
+    });
+
+    // 上下文注入动作在详细级别下也体现为一条步骤（注入细节可忽略）。
+    // 不计入工具/助手消息的熔断计数（规格口径：熔断只管「工具 + 助手」）。
+    if (contextEnhanced || content) {
+      await this.#sendStepMessage(
+        chatId, key,
+        [[{ tag: 'text', text: t('📎 已注入会话上下文') }]],
+        t('📎 已注入会话上下文'),
+        messageId,
+        { billable: false },
+      );
+    }
+
+    // 缓冲-确认策略：每步定稿的助手文本先进缓冲；工具调用或更大 step 的定稿
+    // 证明它是过程说明时才 flush 为 💬 消息。turn 结束时缓冲内剩余的即最终步
+    // ——不直推，改为最终答案的富文本 post 内容，避免同一句话重复出现。
+    let pendingStep = null;
+    const flushPendingStep = async () => {
+      if (!pendingStep) return;
+      const note = pendingStep;
+      pendingStep = null;
+      await this.#sendStepMessage(
+        chatId, key,
+        [[{ tag: 'md', text: `💬 ${note.text}` }]],
+        `💬 ${note.text}`,
+        messageId,
+      );
+    };
+    const completed = await askInWorkspaceSession({
+      deferredDelivery: () => ({ coordinator: this.#deferred, chatId, replyToMessageId: messageId }),
+      harness: this.#harness,
+      state: this.#state,
+      key,
+      text,
+      content,
+      contextEnhanced,
+      createOptions: { signal: this.#signal },
+      existsOptions: { signal: this.#signal },
+      askOptions: {
+        ...this.#interactionAskOptions(event, key, message.files),
+        progressMode: 'all',
+        onUpdate: async (update) => {
+          if (update.type === 'assistant-message') {
+            if (pendingStep && Number(update.step) > Number(pendingStep.step)) {
+              await flushPendingStep();
+            }
+            pendingStep = update;
+            return;
+          }
+          if (update.type === 'tool') {
+            await flushPendingStep();
+            const { paragraphs, fallbackText } = this.#formatStepToolPost(update);
+            await this.#sendStepMessage(chatId, key, paragraphs, fallbackText, messageId);
+            return;
+          }
+          if (update.type === 'status' && update.error) {
+            const name = stepPushLine(update.toolName) || t('工具');
+            const excerpt = stepPushLine(update.error).slice(0, STEP_PUSH_ERROR_MAX_CHARS);
+            await this.#sendStepMessage(
+              chatId, key,
+              [[{ tag: 'md', text: `⚠️ **${name}** — ${excerpt}` }]],
+              `⚠️ ${name} — ${excerpt}`,
+              messageId,
+            );
+          }
+          // text / status（无错误）保持静默：详细级直推完全取代简略级进度行。
+        },
+      },
+    });
+    markAskComplete();
+    const finalStepText = pendingStep ? pendingStep.text : null;
+    pendingStep = null;
+    const finalText = (typeof finalStepText === 'string' && finalStepText.trim())
+      ? finalStepText
+      : completed.answer;
+    const deliveryText = answerTextForDelivery(finalText, completed.artifacts ?? []);
+    let textReceipt;
+    let postDeliveryError = null;
+    try {
+      // 分步直推模式下最终答案以富文本 post（md 标签，GFM 全语法）推送；
+      // 超长答案按段落边界切分为多条 post（单条 content 上限 30KB）。
+      // 任一分段失败都视为最终答案失败——进入 catch 阶梯上抛，
+      // 决不允许「用户没收到答案、状态却记为已回复」。
+      const providerMessageIds = [];
+      const chunks = splitStepPostMarkdown(deliveryText);
+      let failedChunkIndex = -1;
+      for (let index = 0; index < chunks.length; index += 1) {
+        const chunk = chunks[index];
+        const result = await this.#sendStepPost(
+          chatId,
+          messageId,
+          [[{ tag: 'md', text: chunk }]],
+          chunk,
+        );
+        if (!result.ok) {
+          postDeliveryError ??= new Error(
+            result.error?.message ?? 'step push post delivery failed',
+            { cause: result.error },
+          );
+          failedChunkIndex = index;
+          break;
+        }
+        if (result.messageId) providerMessageIds.push(result.messageId);
+      }
+      if (postDeliveryError) {
+        postDeliveryError.failedChunkIndex = failedChunkIndex;
+        postDeliveryError.providerMessageIds = providerMessageIds;
+        postDeliveryError.remainingChunks = chunks.slice(failedChunkIndex);
+        throw postDeliveryError;
+      }
+      textReceipt = createDeliveryReceipt({
+        deliveryId: messageId,
+        presentation: 'feishu-step-push-post',
+        providerMessageIds,
+      });
+      this.#status.streamResponses = (this.#status.streamResponses ?? 0) + 1;
+    } catch (error) {
+      this.#status.streamErrors = (this.#status.streamErrors ?? 0) + 1;
+      this.#logger.warn?.('[dsh-feishu] step push post failed; sending final text:', error.message);
+      let textSendError = null;
+      const providerMessageIds = Array.isArray(error?.providerMessageIds)
+        ? [...error.providerMessageIds]
+        : [];
+      const remainingChunks = Array.isArray(error?.remainingChunks)
+        ? error.remainingChunks
+        : [deliveryText];
+      for (const chunk of remainingChunks) {
+        try {
+          const receipt = await this.#sendAnswerText(chatId, chunk, {
+            deliveryId: messageId,
+            presentation: 'feishu-step-push-text',
+            replyTo: messageId,
+          });
+          providerMessageIds.push(...receipt.providerMessageIds);
+        } catch (fallbackError) {
+          textSendError = channelDeliveryFailure(fallbackError);
+          this.#logger.warn?.(
+            '[dsh-feishu] fallback text delivery failed; continuing with result files:',
+            fallbackError,
+          );
+          break;
+        }
+      }
+      textReceipt = providerMessageIds.length > 0
+        ? createDeliveryReceipt({
+            deliveryId: messageId,
+            presentation: 'feishu-step-push-post-and-text',
+            providerMessageIds,
+          })
+        : undefined;
+      const delivery = await this.#deliverArtifacts(
+        chatId,
+        messageId,
+        completed.artifacts ?? [],
+        textReceipt,
+      );
+      const artifactDispatched = delivery.receipt.artifacts.some(
+        ({ outcome }) => outcome === 'sent' || outcome === 'unknown',
+      );
+      if (textSendError && !artifactDispatched && !delivery.failureNoticeVisible) {
+        throw textSendError;
+      }
+      if (textSendError && delivery.artifactSendErrors === 0) {
+        setLastMessageFailure(this.#status, textSendError);
+      }
+      this.#status.streamFallbacks = (this.#status.streamFallbacks ?? 0) + 1;
+      return { ...delivery, textDeliveryErrors: textSendError ? 1 : 0 };
+    }
+    const delivery = await this.#deliverArtifacts(
+      chatId,
+      messageId,
+      completed.artifacts ?? [],
+      textReceipt,
+    );
+    return { ...delivery, textDeliveryErrors: 0 };
+  }
+
   async #answerWithStream(event, key, message, { onAskComplete } = {}) {
     const chatId = event.message.chat_id;
     const messageId = event.message.message_id;
@@ -3545,6 +4113,13 @@ export class FeishuHarnessBridge {
       askCompleted = true;
       onAskComplete?.();
     };
+    // 分步直推：开关开启且通道支持流式卡时，在构造提示内容之前分流到完整替
+    // 代路径（`#answerWithStepPush` 自行构造一次，回复引用回合不做第二次
+    // promptContentForInboundMessage 往返）；关闭或无流式卡通道时与 main
+    // 零差异（含下方 `!this.#channel?.stream` 纯文本路径）。
+    if (this.#stepPush && this.#channel?.stream) {
+      return this.#answerWithStepPush(event, key, message, { onAskComplete });
+    }
     let content = hasInboundImages(message) || hasReplyReference(message)
       ? await promptContentForInboundMessage(message, { signal: this.#signal })
       : undefined;
@@ -3562,6 +4137,7 @@ export class FeishuHarnessBridge {
     }
     if (!this.#channel?.stream) {
       const { answer, artifacts = [] } = await askInWorkspaceSession({
+        deferredDelivery: () => ({ coordinator: this.#deferred, chatId, replyToMessageId: messageId }),
         harness: this.#harness,
         state: this.#state,
         key,
@@ -3632,6 +4208,7 @@ export class FeishuHarnessBridge {
             },
           };
           const completed = await askInWorkspaceSession({
+            deferredDelivery: () => ({ coordinator: this.#deferred, chatId, replyToMessageId: messageId }),
             harness: this.#harness,
             state: this.#state,
             key,
@@ -3701,6 +4278,7 @@ export class FeishuHarnessBridge {
 
       this.#logger.warn?.('[dsh-feishu] native stream unavailable; using text fallback:', error.message);
       const { answer, artifacts = [] } = await askInWorkspaceSession({
+        deferredDelivery: () => ({ coordinator: this.#deferred, chatId, replyToMessageId: messageId }),
         harness: this.#harness,
         state: this.#state,
         key,