Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(feishu): keep replies in step with the turn

zhujiad1fe4f637d66
diff --git a/deeptutor/partners/channels/feishu.py b/deeptutor/partners/channels/feishu.py
index 725d1006f..75ed741f3 100644
--- a/deeptutor/partners/channels/feishu.py
+++ b/deeptutor/partners/channels/feishu.py
@@ -3,7 +3,7 @@
import asyncio
import base64
from collections import OrderedDict
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from http import HTTPStatus
import importlib.util
import inspect
@@ -288,6 +288,26 @@ def _extract_post_text(content_json: dict) -> str:
return text
+async def _shutdown_ws_client(client: Any, ws_loop: asyncio.AbstractEventLoop) -> None:
+ """Cancel the SDK WebSocket client's tasks and close its connection.
+
+ ``lark.ws.Client`` has no ``stop()``: its ``start()`` ends in a module-level
+ ``_select()`` that never returns, so a reloaded or disabled channel used to
+ keep a live connection receiving events under a closed-over channel object.
+ Cancelling the loop's tasks makes ``start()`` return to the listener thread.
+ """
+ for task in asyncio.all_tasks(ws_loop):
+ if task is not asyncio.current_task() and not task.done():
+ task.cancel()
+ conn = getattr(client, "_conn", None)
+ if conn is None:
+ return
+ try:
+ await conn.close()
+ except Exception as e: # noqa: BLE001 - teardown is best effort
+ logger.debug("Error closing Feishu WebSocket connection: {}", e)
+
+
class FeishuConfig(DeliveryOverrides, StreamingSupport):
"""Feishu/Lark channel configuration using WebSocket long connection."""
@@ -301,6 +321,40 @@ class FeishuConfig(DeliveryOverrides, StreamingSupport):
react_emoji: str = "THUMBSUP"
group_policy: Literal["open", "mention"] = "mention"
+ # Group chats keep the bot's answer (and its narration/progress) threaded
+ # under the triggering message so one chatty turn does not flood the main
+ # timeline. A p2p chat has no such problem — there a thread is just a panel
+ # the reader has to open — so p2p always gets a plain reply, whatever this
+ # is set to.
+ reply_in_thread: bool = Field(
+ default=True,
+ description=(
+ "Deliver group-chat replies inside the message's thread; "
+ "single chats always get a plain reply."
+ ),
+ )
+
+ # Reasoning output never reaches a channel, so a thinking-heavy turn shows
+ # nothing until the first answer token. The notice is a short message
+ # ("🤔 正在思考…") that is deleted again as soon as the answer starts.
+ thinking_notice: bool = Field(
+ default=True,
+ description=(
+ "Post a brief 'thinking…' notice while the model reasons, removed "
+ "once the answer starts arriving."
+ ),
+ )
+
+ # CardKit renders streamed text with a client-side typewriter effect whose
+ # pace comes from ``streaming_config``. The platform defaults (1 character
+ # per 70 ms ≈ 14 chars/s) sit far below an LLM's output rate, so the card
+ # kept typing long after the turn had finished. Keep the pace ahead of the
+ # model; set either value to 0 to fall back to the platform defaults.
+ # https://open.feishu.cn/document/cardkit-v1/streaming-updates-openapi-overview
+ stream_print_frequency_ms: int = Field(default=30, ge=0, le=2000)
+ stream_print_step: int = Field(default=6, ge=0, le=500)
+ stream_print_strategy: Literal["fast", "delay"] = "fast"
+
_STREAM_ELEMENT_ID = "streaming_md"
@@ -315,6 +369,15 @@ class _FeishuStreamBuf:
last_edit: float = 0.0
stream_id: str | None = None
reply_to_message_id: str | None = None
+ # When the first delta of this segment arrived, so the card's live/closed
+ # logs can show how far behind the reader the stream actually ran.
+ started_at: float = field(default_factory=time.monotonic)
+ updates: int = 0
+ # Card creation failures used to be retried on *every* delta (two blocking
+ # API calls each, no backoff), which turned a reply into a slow dribble.
+ # Count them and give up on live streaming for the segment instead.
+ create_failures: int = 0
+ stream_disabled: bool = False
@dataclass
@@ -345,7 +408,14 @@ class FeishuChannel(BaseChannel):
name = "feishu"
display_name = "Feishu"
- _STREAM_EDIT_INTERVAL = 0.5 # throttle between CardKit streaming updates
+ # One CardKit content update costs a round trip (~0.5s on a warm
+ # connection, ~2s cold). Coalescing already sends the full text each time,
+ # so a slower cadence keeps the serial outbound lane ahead of the model
+ # instead of queueing updates behind it.
+ _STREAM_EDIT_INTERVAL = 1.0
+ _STREAM_CREATE_RETRY_INTERVAL = 3.0 # min seconds between card-creation retries
+ _MAX_STREAM_CREATE_FAILURES = 3 # then fall back to buffered delivery
+ _MAX_THINKING_NOTICES = 50 # notices awaiting their answer, per channel
_MAX_CONFIRMED_STREAMS = 1000
_WORKING_REACTION_TTL = 60 * 60
_MAX_WORKING_REACTIONS = 1000
@@ -354,6 +424,7 @@ class FeishuChannel(BaseChannel):
_MODEL_PAGE_SIZE = 6
_MODEL_PICKER_TTL = 60 * 60
_MAX_MODEL_PICKERS = 100
+ _WS_SHUTDOWN_TIMEOUT = 3.0
@classmethod
def default_config(cls) -> dict[str, Any]:
@@ -367,6 +438,7 @@ class FeishuChannel(BaseChannel):
self._client: Any = None
self._ws_client: Any = None
self._ws_thread: threading.Thread | None = None
+ self._ws_loop: asyncio.AbstractEventLoop | None = None
self._processed_message_ids: OrderedDict[str, None] = OrderedDict() # Ordered dedup cache
self._stream_bufs: dict[str, _FeishuStreamBuf] = {}
self._confirmed_streams: OrderedDict[str, None] = OrderedDict()
@@ -374,6 +446,8 @@ class FeishuChannel(BaseChannel):
self._reaction_cleanup_tasks: dict[tuple[str, str], asyncio.Task[None]] = {}
self._reaction_expiry_tasks: dict[str, asyncio.Task[None]] = {}
self._model_pickers: OrderedDict[str, _ModelPicker] = OrderedDict()
+ # chat_id → message id of the "thinking…" notice awaiting an answer.
+ self._thinking_notices: OrderedDict[str, str] = OrderedDict()
self._model_picker_lock = Lock()
self._loop: asyncio.AbstractEventLoop | None = None
@@ -427,6 +501,17 @@ class FeishuChannel(BaseChannel):
import lark_oapi as lark
from lark_oapi.core.const import FEISHU_DOMAIN, LARK_DOMAIN
+ from deeptutor.partners.channels.lark_http import install_keep_alive
+
+ # Every sync call would otherwise open a new connection (DNS + TCP +
+ # TLS ≈ 2s per call on a remote host), which the serial outbound lane
+ # pays per message. Verified before it is installed.
+ if not install_keep_alive():
+ logger.warning(
+ "Feishu keep-alive HTTP transport unavailable; every API call "
+ "will pay a fresh connection"
+ )
+
ws_module = lark.ws.client
self._running = True
@@ -492,13 +577,17 @@ class FeishuChannel(BaseChannel):
ws_loop = asyncio.new_event_loop()
asyncio.set_event_loop(ws_loop)
+ self._ws_loop = ws_loop
# Patch the module-level loop used by lark's ws Client.start()
_lark_ws_client.loop = ws_loop
+ ws_client = self._ws_client
try:
while self._running:
try:
self.set_setup_state("connecting")
- self._ws_client.start()
+ ws_client.start()
+ except asyncio.CancelledError:
+ break
except Exception as e:
logger.warning("Feishu WebSocket error: {}", e)
self.set_setup_state(
@@ -508,6 +597,14 @@ class FeishuChannel(BaseChannel):
if self._running:
time.sleep(5)
finally:
+ # ``start()`` leaves ping/receive tasks pending; close them and
+ # the socket before the loop dies so Feishu sees this listener
+ # go away instead of keeping a zombie connection.
+ try:
+ ws_loop.run_until_complete(_shutdown_ws_client(ws_client, ws_loop))
+ except Exception as e: # noqa: BLE001 - teardown is best effort
+ logger.debug("Error shutting down Feishu WebSocket: {}", e)
+ self._ws_loop = None
ws_loop.close()
self._ws_thread = threading.Thread(target=run_ws, daemon=True)
@@ -521,15 +618,46 @@ class FeishuChannel(BaseChannel):
while self._running:
await asyncio.sleep(1)
+ def _request_ws_shutdown(self) -> None:
+ """Ask the listener thread's WebSocket client to drop its connection.
+
+ Safe to call from any thread; the SDK's ``start()`` returns once its
+ tasks are cancelled, which lets ``run_ws`` finish and close the socket.
+ """
+ ws_loop = self._ws_loop
+ ws_client = self._ws_client
+ if ws_loop is None or ws_client is None or ws_loop.is_closed():
+ return
+ try:
+ ws_loop.call_soon_threadsafe(
+ lambda: ws_loop.create_task(_shutdown_ws_client(ws_client, ws_loop))
+ )
+ except RuntimeError:
+ return
+
async def stop(self) -> None:
"""
- Stop the Feishu bot.
+ Stop the Feishu bot and release its WebSocket long connection.
- Notice: lark.ws.Client does not expose stop method, simply exiting the program will close the client.
+ Notice: lark.ws.Client does not expose stop; the listener loop is ended
+ by cancelling the SDK's pending tasks and closing its connection, so a
+ reload does not leave a second listener subscribed to the same app.
Reference: https://github.com/larksuite/oapi-sdk-python/blob/v2_main/lark_oapi/ws/client.py#L86
"""
self._running = False
+ self._request_ws_shutdown()
+ thread = self._ws_thread
+ if thread is not None and thread.is_alive():
+ loop = asyncio.get_running_loop()
+ await loop.run_in_executor(None, thread.join, self._WS_SHUTDOWN_TIMEOUT)
+ if thread.is_alive():
+ logger.warning(
+ "Feishu WebSocket listener still running after {}s",
+ self._WS_SHUTDOWN_TIMEOUT,
+ )
+ self._ws_thread = None
+ self._ws_client = None
self._confirmed_streams.clear()
cleanup_tasks = [
*self._reaction_cleanup_tasks.values(),
@@ -1142,6 +1270,94 @@ class FeishuChannel(BaseChannel):
return None, f"[{msg_type}: download failed]"
+ @staticmethod
+ def _is_group_chat(receive_id: str) -> bool:
+ """Group chats are addressed by ``oc_`` chat id; p2p chats by ``ou_`` open id."""
+ return str(receive_id).startswith("oc_")
+
+ def _thread_reply_enabled(self, receive_id: str) -> bool:
+ """Whether this outbound message belongs inside a Feishu thread."""
+ enabled = bool(getattr(self.config, "reply_in_thread", True))
+ return enabled and self._is_group_chat(receive_id)
+
+ # ── thinking notice ─────────────────────────────────────────────
+
+ def _post_notice_sync(self, receive_id: str, content: str) -> str | None:
+ """Post the "thinking…" notice and return its message id.
+
+ Kept separate from ``_send_message_sync`` so the retraction has an id
+ to work with without widening that method's contract.
+ """
+ from lark_oapi.api.im.v1 import CreateMessageRequest, CreateMessageRequestBody
+
+ try:
+ request = (
+ CreateMessageRequest.builder()
+ .receive_id_type("chat_id" if self._is_group_chat(receive_id) else "open_id")
+ .request_body(
+ CreateMessageRequestBody.builder()
+ .receive_id(receive_id)
+ .msg_type("text")
+ .content(json.dumps({"text": content}, ensure_ascii=False))
+ .build()
+ )
+ .build()
+ )
+ response = self._client.im.v1.message.create(request)
+ if not response.success():
+ logger.debug(
+ "Feishu thinking notice rejected: code={}, msg={}",
+ response.code,
+ response.msg,
+ )
+ return None
+ message_id = getattr(getattr(response, "data", None), "message_id", None)
+ return message_id if isinstance(message_id, str) and message_id else "posted"
+ except Exception as e:
+ logger.debug("Error posting Feishu thinking notice: {}", e)
+ return None
+
+ def _delete_message_sync(self, message_id: str) -> bool:
+ from lark_oapi.api.im.v1 import DeleteMessageRequest
+
+ try:
+ request = DeleteMessageRequest.builder().message_id(message_id).build()
+ response = self._client.im.v1.message.delete(request)
+ if response.success():
+ return True
+ logger.debug(
+ "Failed to retract Feishu notice {}: code={}, msg={}",
+ message_id,
+ response.code,
+ response.msg,
+ )
+ except Exception as e:
+ logger.debug("Error retracting Feishu notice {}: {}", message_id, e)
+ return False
+
+ def _remember_thinking_notice(self, chat_id: str, message_id: str) -> None:
+ self._thinking_notices[chat_id] = message_id
+ self._thinking_notices.move_to_end(chat_id)
+ while len(self._thinking_notices) > self._MAX_THINKING_NOTICES:
+ self._thinking_notices.popitem(last=False)
+
+ async def _post_thinking_notice(self, chat_id: str, content: str) -> None:
+ """Show the reader that the turn is alive before any answer text exists."""
+ if not bool(getattr(self.config, "thinking_notice", True)) or not self._client:
+ return
+ loop = asyncio.get_running_loop()
+ message_id = await loop.run_in_executor(None, self._post_notice_sync, chat_id, content)
+ if message_id:
+ self._remember_thinking_notice(chat_id, message_id)
+
+ async def _retract_thinking_notice(self, chat_id: str) -> None:
+ """Remove the notice once real output exists (best effort)."""
+ message_id = self._thinking_notices.pop(chat_id, None)
+ if not message_id or not self._client:
+ return
+ loop = asyncio.get_running_loop()
+ await loop.run_in_executor(None, self._delete_message_sync, message_id)
+
def _send_message_sync(
self,
receive_id_type: str,
@@ -1149,6 +1365,8 @@ class FeishuChannel(BaseChannel):
msg_type: str,
content: str,
reply_to_message_id: str | None = None,
+ *,
+ reply_in_thread: bool | None = None,
) -> bool:
"""Send a message as a real Feishu reply when its source is known."""
from lark_oapi.api.im.v1 import (
@@ -1158,6 +1376,12 @@ class FeishuChannel(BaseChannel):
ReplyMessageRequestBody,
)
+ use_thread = (
+ self._thread_reply_enabled(receive_id)
+ if reply_in_thread is None
+ else bool(reply_in_thread)
+ )
+
try:
if reply_to_message_id:
request = (
@@ -1167,7 +1391,7 @@ class FeishuChannel(BaseChannel):
ReplyMessageRequestBody.builder()
.msg_type(msg_type)
.content(content)
- .reply_in_thread(True)
+ .reply_in_thread(use_thread)
.build()
)
.build()
@@ -1223,17 +1447,60 @@ class FeishuChannel(BaseChannel):
# ── CardKit streaming (send_delta) ───────────────────────────────
+ def _streaming_config(self) -> dict[str, Any] | None:
+ """Client-side typewriter pace for streamed text, or ``None`` for defaults.
+
+ Feishu prints streamed markdown character by character; without an
+ explicit ``streaming_config`` the pace is 1 char per 70 ms, which no
+ model-generated answer can be rendered at. Clients older than 7.23
+ ignore these parameters and keep their own defaults.
+ """
+ frequency = int(getattr(self.config, "stream_print_frequency_ms", 0) or 0)
+ step = int(getattr(self.config, "stream_print_step", 0) or 0)
+ if frequency <= 0 or step <= 0:
+ return None
+ strategy = str(getattr(self.config, "stream_print_strategy", "fast") or "fast")
+ return {
+ "print_frequency_ms": {"default": frequency},
+ "print_step": {"default": step},
+ "print_strategy": strategy if strategy in {"fast", "delay"} else "fast",
+ }
+
def _create_streaming_card_sync(
- self, receive_id_type: str, chat_id: str, reply_to_message_id: str | None = None
+ self,
+ receive_id_type: str,
+ chat_id: str,
+ reply_to_message_id: str | None = None,
+ initial_text: str = "",
) -> str | None:
- """Create a CardKit streaming card, send it to chat, return card_id."""
+ """Create a CardKit streaming card, send it to chat, return card_id.
+
+ ``initial_text`` rides along in the card JSON so the first chunk of the
+ reply is visible with the card itself: creating an empty entity and then
+ pushing the same text costs one extra round trip (~0.5–2s depending on
+ the connection), and the reader waits for it.
+ """
from lark_oapi.api.cardkit.v1 import CreateCardRequest, CreateCardRequestBody
+ card_config: dict[str, Any] = {
+ "wide_screen_mode": True,
+ "update_multi": True,
+ "streaming_mode": True,
+ }
+ streaming_config = self._streaming_config()
+ if streaming_config is not None:
+ card_config["streaming_config"] = streaming_config
card_json = {
"schema": "2.0",
- "config": {"wide_screen_mode": True, "update_multi": True, "streaming_mode": True},
+ "config": card_config,
"body": {
- "elements": [{"tag": "markdown", "content": "", "element_id": _STREAM_ELEMENT_ID}]
+ "elements": [
+ {
+ "tag": "markdown",
+ "content": initial_text,
+ "element_id": _STREAM_ELEMENT_ID,
+ }
+ ]
},
}
try:
@@ -1361,7 +1628,7 @@ class FeishuChannel(BaseChannel):
meta = metadata or {}
stream_key = self._stream_key(chat_id, meta)
loop = asyncio.get_running_loop()
- rid_type = "chat_id" if chat_id.startswith("oc_") else "open_id"
+ rid_type = "chat_id" if self._is_group_chat(chat_id) else "open_id"
inbound_message_id = str(meta.get("message_id") or "").strip() or None
if meta.get("_stream_end"):
@@ -1397,12 +1664,22 @@ class FeishuChannel(BaseChannel):
self._confirm_stream_delivery(stream_key)
if reply_to_message_id:
await self._finish_reaction(reply_to_message_id)
+ logger.info(
+ "Feishu streaming card {} closed for {}: {} chars, {} updates, "
+ "{:.1f}s after the first delta",
+ buf.card_id,
+ stream_key,
+ len(buf.text),
+ buf.updates,
+ time.monotonic() - buf.started_at,
+ )
return
logger.warning(
"Feishu streaming card {} final update failed, falling back to regular card",
buf.card_id,
)
delivered = True
+ await self._retract_thinking_notice(chat_id)
for chunk in self._split_elements_by_table_limit(self._build_card_elements(buf.text)):
card = json.dumps(
{"config": {"wide_screen_mode": True}, "elements": chunk},
@@ -1437,25 +1714,54 @@ class FeishuChannel(BaseChannel):
now = time.monotonic()
if buf.card_id is None:
+ if buf.stream_disabled:
+ # Live streaming gave up on this segment; ``_stream_end``
+ # delivers the buffered text as a regular card instead.
+ return
+ if buf.create_failures and (now - buf.last_edit) < self._STREAM_CREATE_RETRY_INTERVAL:
+ return
card_id = await loop.run_in_executor(
None,
self._create_streaming_card_sync,
rid_type,
chat_id,
buf.reply_to_message_id,
+ buf.text,
)
if card_id:
buf.card_id = card_id
+ # The card was created carrying this text, so the sequence is
+ # already at the first content push.
buf.sequence = 1
- await loop.run_in_executor(
- None, self._stream_update_text_sync, card_id, buf.text, 1
+ buf.create_failures = 0
+ buf.updates += 1
+ buf.last_edit = now
+ # Real output is on screen now — drop the "thinking…" notice.
+ await self._retract_thinking_notice(chat_id)
+ logger.info(
+ "Feishu streaming card {} live for {} after {:.1f}s ({} chars queued)",
+ card_id,
+ stream_key,
+ now - buf.started_at,
+ len(buf.text),
)
+ else:
+ buf.create_failures += 1
buf.last_edit = now
+ if buf.create_failures >= self._MAX_STREAM_CREATE_FAILURES:
+ buf.stream_disabled = True
+ logger.warning(
+ "Feishu live streaming disabled for {} after {} card-creation "
+ "failures; the reply will be delivered as a regular card",
+ stream_key,
+ buf.create_failures,
+ )
elif (now - buf.last_edit) >= self._STREAM_EDIT_INTERVAL:
buf.sequence += 1
await loop.run_in_executor(
None, self._stream_update_text_sync, buf.card_id, buf.text, buf.sequence
)
+ buf.updates += 1
buf.last_edit = now
def _prune_model_pickers(self) -> None:
@@ -1813,12 +2119,19 @@ class FeishuChannel(BaseChannel):
return
try:
- receive_id_type = "chat_id" if msg.chat_id.startswith("oc_") else "open_id"
+ receive_id_type = "chat_id" if self._is_group_chat(msg.chat_id) else "open_id"
loop = asyncio.get_running_loop()
metadata = msg.metadata or {}
origin_message_id = str(metadata.get("message_id") or "").strip() or None
reply_to_message_id = str(msg.reply_to or origin_message_id or "").strip() or None
+ if metadata.get("_thinking_notice"):
+ await self._post_thinking_notice(msg.chat_id, msg.content)
+ return
+ if not metadata.get("_progress"):
+ # The answer (or any final output) supersedes the placeholder.
+ await self._retract_thinking_notice(msg.chat_id)
+
picker_message_id = str(metadata.get("_feishu_model_picker_message_id") or "")
if picker_message_id:
completed = bool(metadata.get("_feishu_model_switch_success"))
diff --git a/deeptutor/partners/channels/lark_http.py b/deeptutor/partners/channels/lark_http.py
new file mode 100644
index 000000000..20f8c97a1
--- /dev/null
+++ b/deeptutor/partners/channels/lark_http.py
@@ -0,0 +1,79 @@
+"""Keep-alive HTTP transport for the lark-oapi *sync* client.
+
+``lark_oapi.core.http.transport.Transport.execute`` issues every synchronous
+call through the module-level ``requests.request()``, which builds a fresh
+``Session`` — and therefore a fresh DNS lookup, TCP connection and TLS
+handshake — for every single API call. Measured from a host outside the Feishu
+region, that is ~2.0s per call:
+
+ card.create 3.2s (first call also fetches a tenant token)
+ card_element.content 2.0s
+ …average 2.03s
+
+The channel pays that serially per outbound message, so a streaming card's
+first frame (create + send + first text) took ~6s and every later update ~2s,
+which is what made Feishu trail the reply (see the partner outbound lane).
+
+Reusing one session per worker thread keeps the connection warm and drops the
+average to ~0.68s (≈0.55s once warm) — measured on the same host:
+
+ card.create 1.65s → 0.55s
+ card_element.content 2.0s → 0.55s
+
+Only the sync transport is touched; the SDK's async transport uses httpx and
+the WebSocket client keeps its own long-lived connection.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+import requests
+
+_SESSIONS = threading.local()
+_INSTALLED = False
+_LOCK = threading.Lock()
+
+
+def _session() -> requests.Session:
+ """One keep-alive session per thread (urllib3 pools are per session)."""
+ session = getattr(_SESSIONS, "session", None)
+ if session is None:
+ session = requests.Session()
+ _SESSIONS.session = session
+ return session
+
+
+class _KeepAliveRequests:
+ """Drop-in stand-in for the ``requests`` module used by the SDK transport."""
+
+ def request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
+ return _session().request(method, url, **kwargs)
+
+ def __getattr__(self, name: str) -> Any:
+ # Exceptions, codes, … stay reachable for callers that poke the module.
+ return getattr(requests, name)
+
+
+def install_keep_alive() -> bool:
+ """Route lark-oapi's sync HTTP calls through reusable connections.
+
+ Idempotent; returns False when the SDK (or the expected internals) are
+ unavailable, in which case the SDK keeps its per-call behaviour.
+ """
+ global _INSTALLED
+ with _LOCK:
+ if _INSTALLED:
+ return True
+ try:
+ import lark_oapi.core.http.transport as transport
+ except Exception:
+ return False
+ if not isinstance(getattr(transport, "requests", None), _KeepAliveRequests):
+ transport.requests = _KeepAliveRequests()
+ _INSTALLED = True
+ return True
+
+
+__all__ = ["install_keep_alive"]
diff --git a/deeptutor/services/partners/runtime.py b/deeptutor/services/partners/runtime.py
index 10bc415ad..6476497d5 100644
--- a/deeptutor/services/partners/runtime.py
+++ b/deeptutor/services/partners/runtime.py
@@ -64,6 +64,11 @@ _MAX_IMAGE_BYTES = 8 * 1024 * 1024
_MAX_MEDIA_BYTES = 10 * 1024 * 1024
_TOOL_HINT_MAX_CHARS = 120
+# Channels that post the "thinking…" notice and retract it when the answer
+# starts arriving. Opt-in: a channel that cannot retract would leave it behind.
+_THINKING_NOTICE_CHANNELS = frozenset({"feishu"})
+_THINKING_NOTICES = {"zh": "🤔 正在思考…", "en": "🤔 Thinking…"}
+
@dataclass(frozen=True, slots=True)
class PartnerTurnOptions:
@@ -493,6 +498,19 @@ class PartnerRunner:
wants_stream = is_im and send_progress and bool(msg.metadata.get("_wants_stream"))
_config, llm_token = activate_llm_selection(selection)
+ logger.info(
+ "Partner %s turn %s on %s: live streaming %s",
+ self.partner_id,
+ turn_id or "-",
+ msg.channel,
+ "on" if wants_stream else "off",
+ )
+ # Reasoning tokens are never delivered to channels, so a
+ # thinking-heavy turn looks like a dead bot until the first answer
+ # token. Give the reader a notice they can watch, and let the
+ # channel retract it once the answer starts arriving.
+ if is_im and send_progress and msg.channel in _THINKING_NOTICE_CHANNELS:
+ await self._publish_thinking_notice(msg)
if options.conversation_history is None:
context.runtime.model_history = store.model_history(
session_key=msg.session_key,
@@ -1097,6 +1115,27 @@ class PartnerRunner:
)
)
+ async def _publish_thinking_notice(self, msg: InboundMessage) -> None:
+ """Post a short "thinking…" placeholder before the first answer token.
+
+ Only channels that can retract it (see ``_THINKING_NOTICE_CHANNELS``)
+ are targeted, so a channel that would leave the notice behind is
+ unaffected.
+ """
+ notice = _THINKING_NOTICES[self._language()]
+ await self.bus.publish_outbound(
+ OutboundMessage(
+ channel=msg.channel,
+ chat_id=msg.chat_id,
+ content=notice,
+ metadata={
+ "_progress": True,
+ "_thinking_notice": True,
+ **_thread_delivery_meta(msg),
+ },
+ )
+ )
+
async def _publish_stream_delta(
self, msg: InboundMessage, turn_id: str, call_id: str, delta: str
) -> None:
diff --git a/tests/services/partners/test_channel_streaming.py b/tests/services/partners/test_channel_streaming.py
index ca610126b..f350fce27 100644
--- a/tests/services/partners/test_channel_streaming.py
+++ b/tests/services/partners/test_channel_streaming.py
@@ -160,7 +160,9 @@ class TestFeishuStreaming:
await ch.send_delta("oc_1", "Hello", _meta("s1"))
ch._create_streaming_card_sync.assert_called_once()
- ch._stream_update_text_sync.assert_called_with("card-1", "Hello", 1)
+ # The first text rides along with the card, so it needs no extra push.
+ assert ch._create_streaming_card_sync.call_args.args[-1] == "Hello"
+ ch._stream_update_text_sync.assert_not_called()
await ch.send_delta("oc_1", "", _meta("s1", end=True))
# Final text update then streaming_mode close, with growing sequence.
diff --git a/tests/services/partners/test_feishu_reply_delivery.py b/tests/services/partners/test_feishu_reply_delivery.py
index 5e32b63c0..87052da8e 100644
--- a/tests/services/partners/test_feishu_reply_delivery.py
+++ b/tests/services/partners/test_feishu_reply_delivery.py
@@ -23,8 +23,10 @@ def _response(*, ok: bool = True, data: object | None = None) -> SimpleNamespace
)
-def _channel() -> FeishuChannel:
- channel = FeishuChannel({"enabled": True, "appId": "app", "appSecret": "secret"}, MessageBus())
+def _channel(**config: object) -> FeishuChannel:
+ channel = FeishuChannel(
+ {"enabled": True, "appId": "app", "appSecret": "secret", **config}, MessageBus()
+ )
message = SimpleNamespace(create=MagicMock(return_value=_response()))
message.reply = MagicMock(return_value=_response())
reaction = SimpleNamespace(
@@ -75,6 +77,71 @@ def test_uncertain_reply_transport_error_does_not_send_duplicate() -> None:
channel._client.im.v1.message.create.assert_not_called()
+def test_single_chat_reply_is_not_threaded() -> None:
+ """A p2p thread is a panel the reader has to open for no benefit."""
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+
+ assert channel._send_message_sync("open_id", "ou_user", "text", '{"text":"hi"}', "om_user")
+
+ request = channel._client.im.v1.message.reply.call_args.args[0]
+ assert request.request_body.reply_in_thread is False
+
+
+def test_group_threading_can_be_switched_off() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel(reply_in_thread=False)
+
+ assert channel._send_message_sync("chat_id", "oc_group", "text", '{"text":"hi"}', "om_user")
+
+ request = channel._client.im.v1.message.reply.call_args.args[0]
+ assert request.request_body.reply_in_thread is False
+
+
+def test_group_threading_is_on_by_default() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+
+ assert channel.config.reply_in_thread is True
+ assert channel._send_message_sync("chat_id", "oc_group", "text", '{"text":"hi"}', "om_user")
+
+ request = channel._client.im.v1.message.reply.call_args.args[0]
+ assert request.request_body.reply_in_thread is True
+
+
+async def test_streaming_card_follows_the_thread_setting() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ channel._stream_update_text_sync = MagicMock(return_value=True)
+
+ await channel.send_delta("ou_user", "Narration", {"_stream_id": "n", "message_id": "om_user"})
+
+ request = channel._client.im.v1.message.reply.call_args.args[0]
+ assert request.request_body.msg_type == "interactive"
+ assert request.request_body.reply_in_thread is False
+
+
+async def test_p2p_answer_is_a_plain_reply() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+
+ await channel.send(
+ OutboundMessage(
+ channel="feishu",
+ chat_id="ou_user",
+ content="Answer",
+ metadata={"message_id": "om_user"},
+ )
+ )
+
+ request = channel._client.im.v1.message.reply.call_args.args[0]
+ assert request.paths["message_id"] == "om_user"
+ assert request.request_body.reply_in_thread is False
+ channel._client.im.v1.message.create.assert_not_called()
+
+
def test_reaction_receipt_is_deleted_by_its_own_id() -> None:
pytest.importorskip("lark_oapi")
channel = _channel()
diff --git a/tests/services/partners/test_feishu_stream_resilience.py b/tests/services/partners/test_feishu_stream_resilience.py
new file mode 100644
index 000000000..30043dcec
--- /dev/null
+++ b/tests/services/partners/test_feishu_stream_resilience.py
@@ -0,0 +1,147 @@
+"""Feishu live streaming: tuned typewriter pace, bounded retries, released WS.
+
+The card path used to (a) run at Feishu's default 1 character / 70 ms typewriter
+pace, so a finished answer kept typing for a long time, and (b) retry card
+creation on *every* delta when the API rejected it, turning the reply into a
+slow dribble. Both are bounded here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from deeptutor.partners.bus.events import OutboundMessage
+from deeptutor.partners.bus.queue import MessageBus
+from deeptutor.partners.channels.base import deliver_outbound
+from deeptutor.partners.channels.feishu import FeishuChannel, _shutdown_ws_client
+
+
+def _response(*, ok: bool = True, data: object | None = None) -> SimpleNamespace:
+ return SimpleNamespace(
+ success=lambda: ok,
+ data=data,
+ code=0 if ok else 500,
+ msg="ok" if ok else "unavailable",
+ get_log_id=lambda: "log-1",
+ )
+
+
+def _channel(**config: object) -> FeishuChannel:
+ channel = FeishuChannel(
+ {"enabled": True, "appId": "app", "appSecret": "secret", **config}, MessageBus()
+ )
+ message = SimpleNamespace(
+ create=MagicMock(return_value=_response()),
+ reply=MagicMock(return_value=_response()),
+ )
+ card = SimpleNamespace(
+ create=MagicMock(return_value=_response(data=SimpleNamespace(card_id="card-1")))
+ )
+ card_element = SimpleNamespace(content=MagicMock(return_value=_response()))
+ channel._client = SimpleNamespace(
+ im=SimpleNamespace(v1=SimpleNamespace(message=message)),
+ cardkit=SimpleNamespace(v1=SimpleNamespace(card=card, card_element=card_element)),
+ )
+ return channel
+
+
+def _message(content: str, **metadata: object) -> OutboundMessage:
+ return OutboundMessage(
+ channel="feishu",
+ chat_id="oc_group",
+ content=content,
+ metadata={"message_id": "om_user", "_stream_id": "turn:1", **metadata},
+ )
+
+
+def _created_card_config(channel: FeishuChannel) -> dict:
+ request = channel._client.cardkit.v1.card.create.call_args.args[0]
+ return json.loads(request.request_body.data)["config"]
+
+
+def test_streaming_card_tunes_the_client_typewriter_pace() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+
+ assert channel._create_streaming_card_sync("chat_id", "oc_group") == "card-1"
+
+ config = _created_card_config(channel)
+ assert config["streaming_mode"] is True
+ # Feishu's defaults are 70 ms per character; keep the card ahead of the model.
+ assert config["streaming_config"] == {
+ "print_frequency_ms": {"default": 30},
+ "print_step": {"default": 6},
+ "print_strategy": "fast",
+ }
+
+
+def test_zero_print_tuning_falls_back_to_platform_defaults() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel(stream_print_step=0)
+
+ channel._create_streaming_card_sync("chat_id", "oc_group")
+
+ assert "streaming_config" not in _created_card_config(channel)
+
+
+async def test_repeated_card_creation_failures_stop_hammering_the_api() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ channel._STREAM_CREATE_RETRY_INTERVAL = 0
+ channel._client.cardkit.v1.card.create.return_value = _response(ok=False)
+
+ for _ in range(10):
+ await deliver_outbound(channel, _message("x", _stream_delta=True))
+
+ assert channel._client.cardkit.v1.card.create.call_count == channel._MAX_STREAM_CREATE_FAILURES
+
+
+async def test_degraded_stream_still_delivers_the_full_answer() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ channel._STREAM_CREATE_RETRY_INTERVAL = 0
+ channel._client.cardkit.v1.card.create.return_value = _response(ok=False)
+
+ await deliver_outbound(channel, _message("Hello ", _stream_delta=True))
+ await deliver_outbound(channel, _message("world", _stream_delta=True))
+ await deliver_outbound(channel, _message("", _stream_end=True, _stream_final=True))
+
+ assert channel._client.im.v1.message.reply.call_count == 1
+ body = channel._client.im.v1.message.reply.call_args.args[0].request_body.content
+ assert "Hello world" in body
+
+
+async def test_ws_shutdown_cancels_sdk_tasks_and_closes_the_connection() -> None:
+ loop = asyncio.get_running_loop()
+ connection = SimpleNamespace(close=AsyncMock())
+ client = SimpleNamespace(_conn=connection)
+ parked = asyncio.create_task(asyncio.sleep(3600))
+
+ await _shutdown_ws_client(client, loop)
+
+ with pytest.raises(asyncio.CancelledError):
+ await parked
+ connection.close.assert_awaited_once()
+
+
+async def test_stop_releases_the_websocket_listener(monkeypatch) -> None:
+ channel = _channel()
+ requested = MagicMock()
+ monkeypatch.setattr(channel, "_request_ws_shutdown", requested)
+ channel._ws_client = SimpleNamespace()
+ channel._ws_thread = SimpleNamespace(is_alive=lambda: False)
+
+ await channel.stop()
+
+ requested.assert_called_once()
+ assert channel._ws_client is None
+ assert channel._ws_thread is None
diff --git a/tests/services/partners/test_feishu_thinking_notice.py b/tests/services/partners/test_feishu_thinking_notice.py
new file mode 100644
index 000000000..ea5b2886e
--- /dev/null
+++ b/tests/services/partners/test_feishu_thinking_notice.py
@@ -0,0 +1,154 @@
+"""The "thinking…" placeholder: shown while the model reasons, then retracted."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from deeptutor.partners.bus.events import OutboundMessage
+from deeptutor.partners.bus.queue import MessageBus
+from deeptutor.partners.channels.feishu import FeishuChannel
+from deeptutor.partners.channels.manager import coalesce_progress_messages
+
+
+def _response(*, ok: bool = True, data: object | None = None) -> SimpleNamespace:
+ return SimpleNamespace(
+ success=lambda: ok,
+ data=data,
+ code=0 if ok else 500,
+ msg="ok" if ok else "unavailable",
+ get_log_id=lambda: "log-1",
+ )
+
+
+def _channel(**config: object) -> FeishuChannel:
+ channel = FeishuChannel(
+ {"enabled": True, "appId": "app", "appSecret": "secret", **config}, MessageBus()
+ )
+ message = SimpleNamespace(
+ create=MagicMock(return_value=_response(data=SimpleNamespace(message_id="om_notice"))),
+ reply=MagicMock(return_value=_response()),
+ delete=MagicMock(return_value=_response()),
+ )
+ card = SimpleNamespace(
+ create=MagicMock(return_value=_response(data=SimpleNamespace(card_id="card-1")))
+ )
+ card_element = SimpleNamespace(content=MagicMock(return_value=_response()))
+ channel._client = SimpleNamespace(
+ im=SimpleNamespace(v1=SimpleNamespace(message=message)),
+ cardkit=SimpleNamespace(v1=SimpleNamespace(card=card, card_element=card_element)),
+ )
+ return channel
+
+
+def _notice(content: str = "🤔 正在思考…") -> OutboundMessage:
+ return OutboundMessage(
+ channel="feishu",
+ chat_id="oc_group",
+ content=content,
+ metadata={"_progress": True, "_thinking_notice": True, "message_id": "om_user"},
+ )
+
+
+async def test_notice_is_posted_and_retracted_once_the_card_is_live() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+
+ await channel.send(_notice())
+
+ create = channel._client.im.v1.message.create.call_args.args[0]
+ assert create.request_body.msg_type == "text"
+ assert json.loads(create.request_body.content)["text"] == "🤔 正在思考…"
+ assert channel._thinking_notices["oc_group"] == "om_notice"
+
+ await channel.send_delta("oc_group", "Hello", {"_stream_id": "s", "message_id": "om_user"})
+
+ delete = channel._client.im.v1.message.delete.call_args.args[0]
+ assert delete.paths["message_id"] == "om_notice"
+ assert "oc_group" not in channel._thinking_notices
+
+
+async def test_final_answer_retracts_a_leftover_notice() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ await channel.send(_notice())
+
+ await channel.send(
+ OutboundMessage(channel="feishu", chat_id="oc_group", content="Answer", metadata={})
+ )
+
+ assert channel._client.im.v1.message.delete.call_args.args[0].paths == {
+ "message_id": "om_notice"
+ }
+ assert not channel._thinking_notices
+
+
+async def test_notice_is_opt_out() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel(thinking_notice=False)
+
+ await channel.send(_notice())
+
+ channel._client.im.v1.message.create.assert_not_called()
+ assert not channel._thinking_notices
+
+
+async def test_failed_retraction_is_tolerated() -> None:
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ channel._client.im.v1.message.delete.return_value = _response(ok=False)
+ await channel.send(_notice())
+
+ await channel.send(
+ OutboundMessage(channel="feishu", chat_id="oc_group", content="Answer", metadata={})
+ )
+
+ assert not channel._thinking_notices, "a failed retraction must not wedge the state"
+
+
+async def test_progress_coalescer_keeps_the_notice_on_its_own() -> None:
+ """The notice has its own lifecycle, so it never merges with narration."""
+ bus = MessageBus()
+ await bus.publish_outbound(_notice())
+ await bus.publish_outbound(
+ OutboundMessage(
+ channel="feishu",
+ chat_id="oc_group",
+ content="先看你的场景…",
+ metadata={"_progress": True},
+ )
+ )
+
+ first, pending = coalesce_progress_messages(bus, await bus.consume_outbound())
+
+ assert first.content == "🤔 正在思考…"
+ assert first.metadata["_thinking_notice"] is True
+ assert [p.content for p in pending] == ["先看你的场景…"]
+
+
+async def test_notice_posts_do_not_block_the_loop() -> None:
+ """Posting runs in a worker thread like every other SDK call."""
+ pytest.importorskip("lark_oapi")
+ channel = _channel()
+ started = asyncio.Event()
+
+ def slow_create(_request: object) -> SimpleNamespace:
+ started.set()
+ return _response(data=SimpleNamespace(message_id="om_notice"))
+
+ channel._client.im.v1.message.create = MagicMock(side_effect=slow_create)
+
+ await asyncio.wait_for(channel.send(_notice()), timeout=2)
+
+ assert started.is_set()
+ assert isinstance(channel._client.im.v1.message.create, MagicMock)
diff --git a/tests/services/partners/test_lark_keep_alive.py b/tests/services/partners/test_lark_keep_alive.py
new file mode 100644
index 000000000..824156208
--- /dev/null
+++ b/tests/services/partners/test_lark_keep_alive.py
@@ -0,0 +1,81 @@
+"""lark-oapi sync calls must reuse connections instead of reconnecting per call."""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+from deeptutor.partners.channels import lark_http
+
+
[email protected](autouse=True)
+def _restore_transport():
+ """Leave the SDK transport as we found it after each test."""
+ lark_oapi_transport = pytest.importorskip("lark_oapi.core.http.transport")
+ original = lark_oapi_transport.requests
+ original_installed = lark_http._INSTALLED
+ yield
+ lark_oapi_transport.requests = original
+ lark_http._INSTALLED = original_installed
+
+
+def test_install_routes_the_sdk_transport_through_the_shim() -> None:
+ lark_oapi_transport = pytest.importorskip("lark_oapi.core.http.transport")
+ lark_http._INSTALLED = False
+
+ assert lark_http.install_keep_alive() is True
+
+ shim = lark_oapi_transport.requests
+ assert isinstance(shim, lark_http._KeepAliveRequests)
+ # Idempotent: a second call keeps the same shim (and its warm sessions).
+ assert lark_http.install_keep_alive() is True
+ assert lark_oapi_transport.requests is shim
+ # Non-request attributes still resolve against the real requests module.
+ import requests
+
+ assert shim.exceptions is requests.exceptions
+
+
+def test_shim_reuses_one_session_per_thread(monkeypatch) -> None:
+ pytest.importorskip("lark_oapi")
+ calls: list[tuple[str, str]] = []
+
+ class FakeSession:
+ def request(self, method: str, url: str, **kwargs: object) -> str:
+ calls.append((method, url))
+ return "response"
+
+ sessions: list[FakeSession] = []
+
+ def fake_session() -> FakeSession:
+ session = FakeSession()
+ sessions.append(session)
+ return session
+
+ monkeypatch.setattr(lark_http.requests, "Session", fake_session)
+ monkeypatch.setattr(lark_http._SESSIONS, "session", None, raising=False)
+
+ shim = lark_http._KeepAliveRequests()
+ assert shim.request("POST", "https://open.feishu.cn/a") == "response"
+ assert shim.request("POST", "https://open.feishu.cn/b") == "response"
+
+ assert calls == [
+ ("POST", "https://open.feishu.cn/a"),
+ ("POST", "https://open.feishu.cn/b"),
+ ]
+ main_session = lark_http._session()
+ assert len(sessions) == 1, "one keep-alive session per thread"
+ assert sessions[0] is main_session
+
+ seen: list[object] = []
+
+ def worker() -> None:
+ seen.append(lark_http._session())
+
+ thread = threading.Thread(target=worker)
+ thread.start()
+ thread.join()
+
+ assert len(seen) == 1, "the worker thread builds its own session"
+ assert seen[0] is not main_session
diff --git a/tests/services/partners/test_partner_runtime.py b/tests/services/partners/test_partner_runtime.py
index 7ad23d019..ee8017a93 100644
--- a/tests/services/partners/test_partner_runtime.py
+++ b/tests/services/partners/test_partner_runtime.py
@@ -42,6 +42,42 @@ def _muted_progress_config() -> PartnerConfig:
class TestTurnExecution:
+ @pytest.mark.asyncio
+ async def test_feishu_turn_announces_thinking_before_any_output(
+ self, partners_root, fake_orchestrator
+ ):
+ """Reasoning never reaches a channel, so the reader gets a placeholder."""
+ fake_orchestrator.script = finish("done")
+ runner = _runner(partners_root, PartnerConfig(name="Ada", language="zh"))
+
+ await runner.process_message(_msg(channel="feishu"))
+
+ notice = await runner.bus.outbound.get()
+ assert notice.content == "🤔 正在思考…"
+ assert notice.metadata["_thinking_notice"] is True
+ assert notice.metadata["_progress"] is True
+
+ @pytest.mark.asyncio
+ async def test_web_turn_never_announces_thinking(self, partners_root, fake_orchestrator):
+ fake_orchestrator.script = finish("done")
+ runner = _runner(partners_root, PartnerConfig(name="Ada", language="zh"))
+
+ await runner.process_message(_msg(channel="web"))
+
+ assert runner.bus.outbound.empty()
+
+ @pytest.mark.asyncio
+ async def test_muted_progress_suppresses_the_thinking_notice(
+ self, partners_root, fake_orchestrator
+ ):
+ fake_orchestrator.script = finish("done")
+ config = PartnerConfig(name="Ada", channels={"feishu": {"sendProgress": False}})
+ runner = _runner(partners_root, config)
+
+ await runner.process_message(_msg(channel="feishu"))
+
+ assert runner.bus.outbound.empty()
+
@pytest.mark.asyncio
async def test_model_history_and_request_header_survive_partner_turns(
self, partners_root, fake_orchestrator, monkeypatch