agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/memory/retrieval.py

@@ -0,0 +1,189 @@
+"""混合检索管线（长任务方案 §7.5 P2）。
+
+检索策略分层（可插拔，KsADK MemoryRecord 始终是公共协议）：
+
+.. code-block:: text
+
+    Tenant / ACL / Scope Filter   （Provider SQL 已完成）
+      -> Time / Status / TTL Filter（Coordinator.recall 已完成）
+      -> Keyword + Vector Search   （keyword：词项覆盖率；vector：可选注入）
+      -> Rerank                    （分数融合：coverage 为主，vector 加权）
+      -> Deduplicate / Diversity   （同 slot_key 只留最高分）
+      -> Token Budget Truncation   （按分数顺序装箱）
+
+本地 SQLite Provider 无向量索引，``vector_score`` 由外部注入（企业
+Memory Service / 向量库适配器提供）；缺失时退化为纯关键词管线，不阻塞。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Mapping, Protocol, Sequence
+
+from ksadk.memory.models import MemoryRecord
+
+#: 多样性控制：同 slot_key 保留的最高分条数。
+_PER_SLOT_LIMIT = 1
+
+
+class MemorySemanticScorer(Protocol):
+    """Optional semantic scoring boundary for a Memory Service or embedding backend.
+
+    Implementations return normalized scores in ``[0, 1]`` keyed by ``memory_id``.
+    The runtime treats the scorer as an optional enhancement: failures must degrade
+    to keyword retrieval instead of failing the conversation.
+    """
+
+    def score(
+        self, *, query: str, records: Sequence[MemoryRecord]
+    ) -> Mapping[str, float]: ...
+
+
+class MemoryReranker(Protocol):
+    """Optional second-stage reranker boundary.
+
+    A reranker receives the already filtered and cheaply ranked candidate set and
+    returns memory ids in preferred order.  It may be backed by a cross-encoder,
+    a managed rerank API or an organization-specific policy model.  The Harness
+    validates its output and degrades to the first-stage order on any failure.
+    """
+
+    def rerank(self, *, query: str, records: Sequence[MemoryRecord]) -> Sequence[str]: ...
+
+
+@dataclass(frozen=True)
+class RetrievalConfig:
+    """管线参数（Token 截断与多样性，避免硬编码全局常数）。"""
+
+    top_k: int = 8
+    max_tokens: int = 4000
+    #: vector 分数权重（0 = 纯关键词）。
+    vector_weight: float = 0.0
+    per_slot_limit: int = _PER_SLOT_LIMIT
+
+
+def keyword_coverage(query: str, content: str) -> float:
+    """查询词项在内容中的覆盖率（0~1；ASCII 词 + CJK 2-gram）。"""
+    terms = _query_terms(query)
+    if not terms:
+        return 0.0
+    lowered = content.lower()
+    hits = sum(1 for t in terms if t in lowered)
+    return round(hits / len(terms), 4)
+
+
+def _query_terms(query: str) -> list[str]:
+    from ksadk.memory.providers.local_sqlite import _keyword_query_terms
+
+    ascii_terms, cjk_terms = _keyword_query_terms(query)
+    terms = [t.lower() for t in ascii_terms]
+    # CJK 词项直接作为覆盖判据（provider 侧已做 2-gram 切分）。
+    terms.extend(cjk_terms)
+    return terms
+
+
+def rerank_records(
+    records: Sequence[MemoryRecord],
+    *,
+    query: str,
+    config: RetrievalConfig | None = None,
+    vector_score: Callable[[MemoryRecord], float] | None = None,
+) -> list[MemoryRecord]:
+    """Rerank + 去重/多样性 + Token 截断（§7.5 默认管线）。
+
+    分数 = (1-w) * keyword_coverage + w * vector_score；无 vector 注入时
+    w 强制为 0（退化为纯关键词）。排序后按 slot_key 去重（保留最高分），
+    最后按分数顺序做 Token 装箱截断。
+    """
+    cfg = config or RetrievalConfig()
+    weight = cfg.vector_weight if vector_score is not None else 0.0
+
+    scored: list[tuple[float, MemoryRecord]] = []
+    for record in records:
+        kw = keyword_coverage(query, record.content)
+        vec = vector_score(record) if vector_score is not None and weight > 0 else 0.0
+        score = round((1 - weight) * kw + weight * vec, 4)
+        # 综合重要性微调（同分时 importance 高者在前，不改变主序）。
+        scored.append((score + record.importance * 1e-6, record))
+    scored.sort(key=lambda pair: -pair[0])
+
+    # Deduplicate / Diversity：同 slot_key 只留最高分（slot_key 取 metadata）。
+    seen_slots: dict[str, int] = {}
+    diverse: list[MemoryRecord] = []
+    for score, record in scored:
+        slot = str(record.metadata.get("slot_key") or "")
+        if slot:
+            count = seen_slots.get(slot, 0)
+            if count >= cfg.per_slot_limit:
+                continue
+            seen_slots[slot] = count + 1
+        diverse.append(record)
+        if len(diverse) >= cfg.top_k:
+            break
+
+    return _box_by_tokens(diverse, cfg.max_tokens)
+
+
+def select_ranked_records(
+    records: Sequence[MemoryRecord],
+    *,
+    ranked_ids: Sequence[str],
+    top_k: int,
+    max_tokens: int,
+    per_slot_limit: int = _PER_SLOT_LIMIT,
+) -> list[MemoryRecord]:
+    """Validate a reranker order, preserve diversity and enforce the token budget.
+
+    Unknown ids, duplicate ids and omitted candidates are rejected.  Requiring a
+    full permutation prevents a faulty or compromised reranker from silently
+    dropping Memory facts.  Callers should catch ``ValueError`` and retain the
+    first-stage result.
+    """
+
+    by_id = {record.memory_id: record for record in records}
+    normalized = tuple(str(memory_id) for memory_id in ranked_ids)
+    if len(normalized) != len(set(normalized)):
+        raise ValueError("reranker returned duplicate memory ids")
+    if set(normalized) != set(by_id):
+        raise ValueError("reranker must return every candidate exactly once")
+
+    selected: list[MemoryRecord] = []
+    seen_slots: dict[str, int] = {}
+    for memory_id in normalized:
+        record = by_id[memory_id]
+        slot = str(record.metadata.get("slot_key") or "")
+        if slot:
+            count = seen_slots.get(slot, 0)
+            if count >= per_slot_limit:
+                continue
+            seen_slots[slot] = count + 1
+        selected.append(record)
+        if len(selected) >= top_k:
+            break
+    return _box_by_tokens(selected, max_tokens)
+
+
+def _box_by_tokens(records: list[MemoryRecord], max_tokens: int) -> list[MemoryRecord]:
+    """按顺序装箱（§10.6：Token 预算截断）。"""
+    from ksadk.context_engine.tokenizer import get_default_token_counter
+
+    counter = get_default_token_counter()
+    total = 0
+    out: list[MemoryRecord] = []
+    for record in records:
+        n = counter.count_text(record.content)
+        if total + n > max_tokens:
+            break
+        total += n
+        out.append(record)
+    return out
+
+
+__all__ = [
+    "MemoryReranker",
+    "MemorySemanticScorer",
+    "RetrievalConfig",
+    "keyword_coverage",
+    "rerank_records",
+    "select_ranked_records",
+]

ksadk/memory/store_adapter.py

@@ -0,0 +1,150 @@
+"""LangGraph Store → MemoryProvider 适配层（长任务方案 §7.6 / P3）。
+
+LangGraph ``BaseStore`` 语义映射到 KsADK MemoryProvider Protocol：
+
+- namespace = ``(tenant_id, workspace_id, scope, scope_id)``（作用域隔离）；
+- key = ``memory_id``；
+- value = MemoryRecord ``to_payload`` 形态的 dict（KsADK 公共协议，
+  Store 不感知 Harness 类型）。
+
+KsADK ``MemoryRecord`` 和权限语义始终是公共协议；更换 Backend 不改变
+HarnessSpec 与 RuntimeEvent（方案 §10 P3 验收）。
+
+Store API 是 async（``aput/aget/asearch/adelete``）；本适配器在同步
+Protocol 方法内用 :func:`asyncio.run` 驱动（事件循环已运行时抛明确错误，
+调用方应改走异步通道或独立线程）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import asdict
+from typing import Any
+
+from ksadk.memory.models import (
+    CoreMemoryRequest,
+    MemoryCapabilities,
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+)
+
+
+def _run(coro: Any) -> Any:
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    raise RuntimeError(
+        "LangGraphStoreAdapter 的同步方法不能在事件循环内调用"
+        "（请在线程/进程边界使用，或经 MemoryCoordinator 异步通道）"
+    )
+
+
+class LangGraphStoreAdapter:
+    """把 LangGraph ``BaseStore`` 适配为 MemoryProvider Protocol。"""
+
+    capabilities_def = MemoryCapabilities(
+        semantic_search=True,  # Store 按 value 匹配语义（视实现而定）
+        keyword_search=False,
+        metadata_filter=True,
+        versioned_update=False,
+        hard_delete=True,
+        ttl=False,
+        max_record_chars=8192,
+    )
+
+    def __init__(self, store: Any, *, tenant_id: str = "local") -> None:
+        self._store = store
+        self._tenant_id = tenant_id
+
+    # ---- namespace 映射 ----
+
+    def _ns(self, scope: str, scope_id: str) -> tuple[str, ...]:
+        return (self._tenant_id, "store", scope, scope_id)
+
+    # ---- MemoryProvider Protocol ----
+
+    def capabilities(self) -> MemoryCapabilities:
+        return self.capabilities_def
+
+    async def _aget(self, memory_id: str, ns: tuple[str, ...]) -> MemoryRecord | None:
+        item = await self._store.aget(ns, memory_id)
+        return MemoryRecord(**item.value) if item else None
+
+    def get(self, memory_id: str) -> MemoryRecord | None:
+        # Store get 需要 namespace；扫描本适配器管理的 scope 前缀不现实，
+        # 调用方（Coordinator）经 search 定位。此处按最近一次 search 缓存解析。
+        raise NotImplementedError("请经 search(memory_id 过滤) 定位记录")
+
+    async def search_async(
+        self, request: MemorySearchRequest
+    ) -> MemorySearchResult:
+        start = time.monotonic()
+        records: list[MemoryRecord] = []
+        for scope, scope_id in request.scopes:
+            items = await self._store.asearch(
+                self._ns(scope, scope_id), query=request.query or None,
+                limit=request.top_k,
+            )
+            for item in items:
+                try:
+                    records.append(MemoryRecord(**dict(item.value)))
+                except TypeError:
+                    continue
+        return MemorySearchResult(
+            status="ok",
+            records=records[: request.top_k],
+            error_code=None,
+            provider="langgraph-store",
+            latency_ms=int((time.monotonic() - start) * 1000),
+            accounting_accuracy="estimated",
+        )
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult:
+        return _run(self.search_async(request))
+
+    async def upsert_async(
+        self, record: MemoryRecord, *, expected_version: int | None
+    ) -> MemoryRecord:
+        if expected_version is not None:
+            existing = await self._aget(record.memory_id, self._ns(record.scope, record.scope_id))
+            if existing is not None and existing.version != expected_version:
+                raise RuntimeError(
+                    f"version_conflict:expected={expected_version},"
+                    f"actual={existing.version}"
+                )
+        payload = asdict(record)
+        payload["source_artifact_refs"] = list(record.source_artifact_refs)
+        payload["source_artifacts"] = [asdict(item) for item in record.source_artifacts]
+        payload["supersedes"] = list(record.supersedes)
+        await self._store.aput(self._ns(record.scope, record.scope_id), record.memory_id, payload)
+        return record
+
+    def upsert(self, record: MemoryRecord, *, expected_version: int | None) -> MemoryRecord:
+        return _run(self.upsert_async(record, expected_version=expected_version))
+
+    async def delete_async(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        ns = self._ns(request.scope, request.scope_id)
+        existing = await self._aget(request.memory_id, ns)
+        if existing is None:
+            return MemoryDeleteResult(status="ok", deleted=False, error_code="not_found")
+        if request.hard:
+            await self._store.adelete(ns, request.memory_id)
+        else:
+            deleted = {**asdict(existing), "status": "deleted"}
+            await self._store.aput(ns, request.memory_id, deleted)
+        return MemoryDeleteResult(status="ok", deleted=True, error_code=None)
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        return _run(self.delete_async(request))
+
+    def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]:
+        # Store 无常驻 Block 概念；Core Memory 交由 Coordinator 预算层。
+        return []
+
+
+__all__ = ["LangGraphStoreAdapter"]

ksadk/model_policy.py

@@ -7,8 +7,8 @@ from typing import Any, Mapping
 
 from ksadk.configs.settings import DEFAULT_MODEL_NAME
 
-DEFAULT_MULTIMODAL_MODEL = "kimi-k2.7-code"
-DEFAULT_FALLBACK_MODEL = "deepseek-v4-pro"
+DEFAULT_MULTIMODAL_MODEL = "deepseek-v4.1-flash"
+DEFAULT_FALLBACK_MODEL = "glm-5.3-flash"
 
 DEFAULT_MODEL_POLICY: dict[str, Any] = {
     "version": "v1",

ksadk/model_proxy/detect.py

@@ -44,6 +44,16 @@ class ModelCapabilities:
     preferred_protocol: str = "chat"  # "responses" | "chat":路由该走哪条
     checked_at: float = 0.0
     verdict: Verdict = "unknown"  # 最近一次探测结论
+    # --- 以下为 opt-in 贵探测,默认 None(未探),由 probe_extended_capability 按需填充 ---
+    # store/previous_response_id 服务端会话链是否真生效(2026-09 实测 deepseek 系
+    # 返回 200 但静默丢历史=假支持)。False 时客户端必须每次带全量历史。
+    store_supported: bool | None = None
+    # 该模型 reasoning_effort 的合法值集合(2026-09 实测 glm-5.3-flash 只认
+    # low/high/max,medium/none/xhigh 全 400;且不能按 family 前缀推断,逐模型实测)。
+    reasoning_effort_values: frozenset[str] | None = None
+    # 非流式响应里 reasoning item 是否稳定出现(2026-09 实测 glm-5.3-flash
+    # 同 effort 下约半数响应只有 message 没有 reasoning item;流式不受影响)。
+    reasoning_item_reliable: bool | None = None
 
 
 def _classify_responses_error(status: int, body: str) -> Verdict:
@@ -336,3 +346,247 @@ def _finalize(caps: ModelCapabilities) -> ModelCapabilities:
         # 因为转换层对 chat 模型是确定可用的,而直连 responses 在 unknown 下有风险
         caps.preferred_protocol = "chat"
     return caps
+
+
+# ---------------------------------------------------------------------------
+# Opt-in 贵探测:store 会话链 / reasoning_effort 值域 / reasoning item 可靠性
+# 这三个探测各需多次真实请求,默认不并入 probe_responses_capability,由调用方按需触发。
+# 全部遵循同一铁律:只在确凿证据下置 True/False,故障/超时/不确定一律留 None(未探)。
+# ---------------------------------------------------------------------------
+
+# reasoning_effort 候选值,覆盖 OpenAI/Codex 主流档 + glm 的 max。
+_EFFORT_CANDIDATES = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+
+
+def probe_extended_capability(
+    client: httpx.Client | httpx.AsyncClient,
+    base: str,
+    key: str,
+    model: str,
+    timeout: float = 60.0,
+):
+    """按需探测 store/reasoning 三项能力,返回填充了对应字段的 ModelCapabilities。
+
+    - ``store_supported``: store=true 拿 response_id,再用 previous_response_id
+      追问一个只有上一轮才知道的事实;答出=真支持,答不出=假支持(静默丢历史)。
+    - ``reasoning_effort_values``: 逐个候选值发最小请求,200=接受,400=拒绝;
+      其余(超时/5xx)不计入(故障≠值域缺失)。
+    - ``reasoning_item_reliable``: 非流式带 reasoning 请求,检查 output 是否含
+      reasoning item。单次缺席不足以判 False(可能模型本来没想),需 N 次全缺席才判。
+
+    按 client 类型分发:sync 返回 ModelCapabilities,async 返回 coroutine。
+    """
+    if isinstance(client, httpx.AsyncClient):
+        return _probe_extended_async(client, base, key, model, timeout)
+    if isinstance(client, httpx.Client):
+        return _probe_extended_sync(client, base, key, model, timeout)
+    raise TypeError(f"client 必须是 httpx.Client/AsyncClient,不是 {type(client).__name__}")
+
+
+def _reasoning_item_present(data: Any) -> bool:
+    if not isinstance(data, dict):
+        return False
+    return any(
+        isinstance(item, dict) and item.get("type") == "reasoning"
+        for item in data.get("output", [])
+    )
+
+
+def _post_json(client, url, payload, headers, timeout):
+    """统一 sync post + json 解析;返回 (status, data) 或 None(故障)。"""
+    try:
+        r = client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return None
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, None
+
+
+async def _post_json_async(client, url, payload, headers, timeout):
+    try:
+        r = await client.post(url, json=payload, headers=headers, timeout=timeout)
+    except (httpx.TimeoutException, httpx.ConnectError, httpx.HTTPError):
+        return None
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, None
+
+
+def _store_first_payload(model: str, marker: str) -> dict:
+    return {
+        "model": model,
+        "input": f"记住代号 {marker},只回 OK",
+        "max_output_tokens": 200,
+        "store": True,
+    }
+
+
+def _probe_store_sync(client, url, headers, model, timeout):
+    marker = "cobalt-9173"
+    first = _post_json(client, url, _store_first_payload(model, marker), headers, timeout)
+    if not first or first[0] != 200 or not isinstance(first[1], dict):
+        return None
+    rid = first[1].get("id")
+    if not rid:
+        return None
+    second = _post_json(
+        client,
+        url,
+        {"model": model, "input": "我刚才让你记的代号是什么?只回答代号",
+         "max_output_tokens": 200, "previous_response_id": rid},
+        headers,
+        timeout,
+    )
+    if not second or second[0] != 200 or not isinstance(second[1], dict):
+        return None
+    text = "".join(
+        c.get("text", "")
+        for item in second[1].get("output", [])
+        if isinstance(item, dict) and item.get("type") == "message"
+        for c in item.get("content", [])
+        if isinstance(c, dict)
+    )
+    return marker in text
+
+
+async def _probe_store_async(client, url, headers, model, timeout):
+    marker = "cobalt-9173"
+    first = await _post_json_async(
+        client, url, _store_first_payload(model, marker), headers, timeout
+    )
+    if not first or first[0] != 200 or not isinstance(first[1], dict):
+        return None
+    rid = first[1].get("id")
+    if not rid:
+        return None
+    second = await _post_json_async(
+        client,
+        url,
+        {"model": model, "input": "我刚才让你记的代号是什么?只回答代号",
+         "max_output_tokens": 200, "previous_response_id": rid},
+        headers,
+        timeout,
+    )
+    if not second or second[0] != 200 or not isinstance(second[1], dict):
+        return None
+    text = "".join(
+        c.get("text", "")
+        for item in second[1].get("output", [])
+        if isinstance(item, dict) and item.get("type") == "message"
+        for c in item.get("content", [])
+        if isinstance(c, dict)
+    )
+    return marker in text
+
+
+def _probe_effort_values_sync(client, url, headers, model, timeout):
+    accepted = set()
+    saw_any = False
+    for eff in _EFFORT_CANDIDATES:
+        res = _post_json(
+            client,
+            url,
+            {"model": model, "input": "hi", "max_output_tokens": 30,
+             "reasoning": {"effort": eff}},
+            headers,
+            timeout,
+        )
+        if res is None:
+            continue  # 故障,不计入
+        status, _ = res
+        saw_any = True
+        if status == 200:
+            accepted.add(eff)
+        # 400 = 明确拒绝该值,不计入 accepted
+    return frozenset(accepted) if saw_any else None
+
+
+async def _probe_effort_values_async(client, url, headers, model, timeout):
+    accepted = set()
+    saw_any = False
+    for eff in _EFFORT_CANDIDATES:
+        res = await _post_json_async(
+            client,
+            url,
+            {"model": model, "input": "hi", "max_output_tokens": 30,
+             "reasoning": {"effort": eff}},
+            headers,
+            timeout,
+        )
+        if res is None:
+            continue
+        status, _ = res
+        saw_any = True
+        if status == 200:
+            accepted.add(eff)
+    return frozenset(accepted) if saw_any else None
+
+
+def _probe_reasoning_reliable_sync(client, url, headers, model, timeout, trials=3):
+    """N 次非流式全缺席 reasoning item 才判 False;任一故障或出现就留 None/True。"""
+    absences = 0
+    for _ in range(trials):
+        res = _post_json(
+            client,
+            url,
+            {"model": model, "input": "9.11 和 9.9 哪个大?", "max_output_tokens": 600,
+             "reasoning": {"effort": "low"}},
+            headers,
+            timeout,
+        )
+        if res is None or res[0] != 200:
+            return None  # 故障,无法判定
+        if _reasoning_item_present(res[1]):
+            return True
+        absences += 1
+    return False if absences == trials else None
+
+
+async def _probe_reasoning_reliable_async(client, url, headers, model, timeout, trials=3):
+    absences = 0
+    for _ in range(trials):
+        res = await _post_json_async(
+            client,
+            url,
+            {"model": model, "input": "9.11 和 9.9 哪个大?", "max_output_tokens": 600,
+             "reasoning": {"effort": "low"}},
+            headers,
+            timeout,
+        )
+        if res is None or res[0] != 200:
+            return None
+        if _reasoning_item_present(res[1]):
+            return True
+        absences += 1
+    return False if absences == trials else None
+
+
+def _probe_extended_sync(client, base, key, model, timeout) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    caps.store_supported = _probe_store_sync(client, url, headers, model, timeout)
+    caps.reasoning_effort_values = _probe_effort_values_sync(
+        client, url, headers, model, timeout
+    )
+    caps.reasoning_item_reliable = _probe_reasoning_reliable_sync(
+        client, url, headers, model, timeout
+    )
+    return caps
+
+
+async def _probe_extended_async(client, base, key, model, timeout) -> ModelCapabilities:
+    caps = ModelCapabilities(checked_at=time.time(), verdict="unknown")
+    url = f"{base.rstrip('/')}/responses"
+    headers = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}
+    caps.store_supported = await _probe_store_async(client, url, headers, model, timeout)
+    caps.reasoning_effort_values = await _probe_effort_values_async(
+        client, url, headers, model, timeout
+    )
+    caps.reasoning_item_reliable = await _probe_reasoning_reliable_async(
+        client, url, headers, model, timeout
+    )
+    return caps

ksadk/model_proxy/server.py

@@ -248,9 +248,10 @@ def create_app(config: ProxyConfig) -> FastAPI:
 async def _chat_passthrough_stream(config: ProxyConfig, base: str, headers: dict, body: dict):
     """chat SSE 字节级透传(不转换),让前缀缓存/流式格式与直连一致。"""
     try:
+        stream_headers = {**headers, "Accept": "text/event-stream"}
         async with httpx.AsyncClient(timeout=config.timeout) as c:
             async with c.stream(
-                "POST", f"{base}/chat/completions", json=body, headers=headers
+                "POST", f"{base}/chat/completions", json=body, headers=stream_headers
             ) as r:
                 async for line in r.aiter_lines():
                     yield line + "\n"
@@ -275,10 +276,11 @@ async def _stream_gen(
     for e in s.start():
         yield e
     try:
+        stream_headers = {**headers, "Accept": "text/event-stream"}
         # 超时必须有界(config.timeout):无限超时的活动 SSE 会让 stop() 后线程仍存活
         async with httpx.AsyncClient(timeout=config.timeout) as c:
             async with c.stream(
-                "POST", f"{base}/chat/completions", json=chat_req, headers=headers
+                "POST", f"{base}/chat/completions", json=chat_req, headers=stream_headers
             ) as r:
                 config.emit(
                     "proxy.upstream",
@@ -444,13 +446,18 @@ class ProxyServer:
             # 应用层取消信号:让活动 SSE 的 _stream_gen 主动 break
             self._app.state.cancel_event.set()
         if self._server is not None:
-            # should_exit 触发主循环进入 shutdown;force_exit 让 shutdown 跳过等待
-            # connections/tasks 完成(活动 SSE 下不再无限等)。两者缺一:只 should_exit
-            # 会被活动连接卡死,只 force_exit 主循环根本不进 shutdown。
+            # Enter Uvicorn's normal shutdown so its lifespan task receives a
+            # shutdown event.  Setting force_exit here skips that event and
+            # makes every completed Studio turn print a CancelledError.
             self._server.should_exit = True
-            self._server.force_exit = True
         if self._thread is not None:
-            self._thread.join(timeout=5)
+            self._thread.join(timeout=3)
+            if self._thread.is_alive() and self._server is not None:
+                # The application cancel signal normally drains active SSE
+                # generators.  Keep a bounded last resort for a broken client
+                # or upstream that ignores cancellation.
+                self._server.force_exit = True
+                self._thread.join(timeout=2)
         if self._sock is not None:
             try:
                 self._sock.close()