feat(engine): #873 dual-Claw event contract + SseAdapter/BufferAdapter + chat.py SSE delegate + im_llm EngineCore thin-shell (gray-gated)
- app/core/engine_event.py (#880): EngineEvent dataclass + make_* factories, single construction entry, byte-compatible wire with legacy ChatPage.tsx - app/core/claw_adapters.py (#884): SseAdapter (hot frames zero-metadata, terminal keeps trace_id) + BufferAdapter (assemble() preserves __media__) - app/api/chat.py (#881): /messages/stream now delegates to SseAdapter; wire bytes unchanged (46B delta / done+message_id) - app/api/im_llm.py (#883): IM_USE_ENGINE_CORE gray gate; _call_engine_core reuses EngineCore via BufferAdapter (default OFF, preserves media fast-path) - app/api/chat_service.py: capture 3 container-ahead fixes (stray import asyncio removed, logger.info format, LiteLLM master key)
This commit is contained in:
QihuAI Design committed
1 parent
34648e4810
commit
037c965c26
5 files changed
+752
-21
No files matched your search
@@ -0,0 +1,294 @@
|
||||
"""双 Claw 适配器（#873 · P0）。
|
||||
|
||||
单引擎原则:
|
||||
能力只在 EngineCore(`_send_message_core`) 实现一次；
|
||||
Adapter 只做「引擎事件 → 通道」的搬运，不含任何业务判断。
|
||||
|
||||
┌──────────────┐ on_event(EngineEvent) ┌──────────────┐
|
||||
│ EngineCore │ ────────────────────────► │ ClawAdapter │
|
||||
└──────────────┘ └──────┬───────┘
|
||||
│
|
||||
┌───────────────────────┴────────────────────────┐
|
||||
▼ ▼
|
||||
SseAdapter (Web Claw) BufferAdapter (IM Bot Claw)
|
||||
逐帧 `data: {...}\\n\\n` 缓冲装配 → 整条 str | 媒体 dict
|
||||
|
||||
历史教训（#866）:
|
||||
IM 侧曾出现「第二份实现」，一次全量部署就把它冲掉、能力静默回退。
|
||||
因此两个 Claw 的差异必须、且只能收敛在本文件的两个 Adapter 里。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from app.core.engine_event import (
|
||||
CLAW_IM,
|
||||
CLAW_WEB,
|
||||
DELTA,
|
||||
DONE,
|
||||
ERROR,
|
||||
REASONING,
|
||||
STEP,
|
||||
Diagnosis,
|
||||
EngineEvent,
|
||||
from_wire,
|
||||
make_error,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
__all__ = ["BaseClawAdapter", "SseAdapter", "BufferAdapter"]
|
||||
|
||||
# 单条回复的软上限：防止异常循环把内存/微信消息撑爆
|
||||
_MAX_ASSEMBLED_CHARS = 20000
|
||||
_MEDIA_RE = re.compile(r'<(img|video)[^>]*\ssrc="([^"]+)"', re.IGNORECASE)
|
||||
|
||||
|
||||
class BaseClawAdapter:
|
||||
"""Adapter 基类。实例可直接当作 `on_event` 回调传给 EngineCore。"""
|
||||
|
||||
claw: str = ""
|
||||
|
||||
def __init__(self, *, trace_id: str = "", tenant_id: str = ""):
|
||||
self.trace_id = trace_id or ""
|
||||
self.tenant_id = tenant_id or ""
|
||||
self._seq = 0
|
||||
self.counts: Dict[str, int] = {}
|
||||
|
||||
# -- 供 EngineCore 直接 await adapter(event) -----------------------
|
||||
async def __call__(self, event: Any) -> None:
|
||||
await self.emit(event)
|
||||
|
||||
async def emit(self, event: Any) -> None:
|
||||
ev = self._normalize(event)
|
||||
if ev is None:
|
||||
return
|
||||
self.counts[ev.type] = self.counts.get(ev.type, 0) + 1
|
||||
try:
|
||||
await self._handle(ev)
|
||||
except Exception as exc: # Adapter 永不把异常反噬引擎
|
||||
logger.warning("[claw:%s] emit failed: %s", self.claw, exc, exc_info=True)
|
||||
|
||||
# -- 子类实现 -------------------------------------------------------
|
||||
async def _handle(self, ev: EngineEvent) -> None:
|
||||
raise NotImplementedError
|
||||
|
||||
# -- 归一化 ---------------------------------------------------------
|
||||
def _normalize(self, event: Any) -> Optional[EngineEvent]:
|
||||
ev = from_wire(event)
|
||||
if ev is None:
|
||||
logger.warning("[claw:%s] drop malformed event: %r", self.claw, event)
|
||||
return None
|
||||
self._seq += 1
|
||||
if not ev.seq:
|
||||
ev.seq = self._seq
|
||||
if not ev.trace_id:
|
||||
ev.trace_id = self.trace_id
|
||||
if not ev.tenant_id:
|
||||
ev.tenant_id = self.tenant_id
|
||||
if not ev.claw:
|
||||
ev.claw = self.claw
|
||||
return ev
|
||||
|
||||
|
||||
# =====================================================================
|
||||
# Web Claw —— SSE 逐帧
|
||||
# =====================================================================
|
||||
class SseAdapter(BaseClawAdapter):
|
||||
"""把引擎事件序列化为 SSE 帧并入队，由路由的 event_gen 逐帧 yield。
|
||||
|
||||
行为与改造前的 chat.py 内联实现逐字节一致：
|
||||
`data: ` + json.dumps(wire, ensure_ascii=False) + `\\n\\n`
|
||||
"""
|
||||
|
||||
claw = CLAW_WEB
|
||||
_SENTINEL = {"type": "__end__"}
|
||||
# 仅用于内部可观测(#876)，默认不上线 —— 见 _thin()
|
||||
_META_KEYS = ("seq", "trace_id", "tenant_id", "claw")
|
||||
|
||||
def __init__(self, queue: "Optional[asyncio.Queue]" = None, *, wire_meta: bool = False, **kw):
|
||||
super().__init__(**kw)
|
||||
self.queue: asyncio.Queue = queue if queue is not None else asyncio.Queue()
|
||||
self.wire_meta = wire_meta
|
||||
self._closed = False
|
||||
|
||||
def _thin(self, ev: EngineEvent, wire: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""裁剪线上元数据。
|
||||
|
||||
why: delta 是最热的帧，一次长回复有上千个。实测带全量元数据会让
|
||||
单帧从 46B 膨胀到 117B(2.5x)，2000 帧即多传 ~140KB 纯噪音，
|
||||
而前端根本不消费这些键。故默认剥离，只在终帧留 trace_id ——
|
||||
单帧成本可忽略，却是线上排障唯一的抓手。
|
||||
"""
|
||||
if self.wire_meta:
|
||||
return wire
|
||||
for k in self._META_KEYS:
|
||||
wire.pop(k, None)
|
||||
if ev.is_terminal() and ev.trace_id:
|
||||
wire["trace_id"] = ev.trace_id
|
||||
return wire
|
||||
|
||||
async def _handle(self, ev: EngineEvent) -> None:
|
||||
await self.queue.put(self._thin(ev, ev.to_wire()))
|
||||
|
||||
async def emit_error(self, message: str, *, diagnosis: Any = None) -> None:
|
||||
await self.emit(make_error(message, diagnosis=diagnosis))
|
||||
|
||||
async def close(self) -> None:
|
||||
"""通知 frames() 结束。幂等。"""
|
||||
if self._closed:
|
||||
return
|
||||
self._closed = True
|
||||
await self.queue.put(dict(self._SENTINEL))
|
||||
|
||||
@staticmethod
|
||||
def frame(wire: Dict[str, Any]) -> str:
|
||||
return "data: " + json.dumps(wire, ensure_ascii=False) + "\n\n"
|
||||
|
||||
async def frames(self):
|
||||
"""异步生成 SSE 帧文本，直到收到哨兵。"""
|
||||
while True:
|
||||
wire = await self.queue.get()
|
||||
if not isinstance(wire, dict):
|
||||
continue
|
||||
if wire.get("type") == "__end__":
|
||||
break
|
||||
yield self.frame(wire)
|
||||
|
||||
|
||||
# =====================================================================
|
||||
# IM Bot Claw —— 缓冲装配
|
||||
# =====================================================================
|
||||
class BufferAdapter(BaseClawAdapter):
|
||||
"""累积引擎事件，最后一次性装配为可直接推送给 IM 的回复。
|
||||
|
||||
IM 通道（微信/iLink）没有流式能力，也没有卡片 UI：
|
||||
* delta 累积成正文；
|
||||
* reasoning 默认丢弃（思维链不该刷屏微信），可用 keep_reasoning 打开；
|
||||
* step 里的 error 级 diagnosis 降级成文本尾注，用户至少知道「哪一步炸了」；
|
||||
* done 的 content 优先于累积的 delta（引擎已做最终裁剪/落库）。
|
||||
"""
|
||||
|
||||
claw = CLAW_IM
|
||||
|
||||
def __init__(self, *, keep_reasoning: bool = False, keep_diagnosis: bool = True, **kw):
|
||||
super().__init__(**kw)
|
||||
self.keep_reasoning = keep_reasoning
|
||||
self.keep_diagnosis = keep_diagnosis
|
||||
self._delta_parts: List[str] = []
|
||||
self._reasoning_parts: List[str] = []
|
||||
self.steps: List[Dict[str, Any]] = []
|
||||
self.done: Optional[Dict[str, Any]] = None
|
||||
self.error: Optional[str] = None
|
||||
self.error_diagnosis: Optional[Diagnosis] = None
|
||||
self.used_skills: List[Any] = []
|
||||
self.used_mcp: List[Any] = []
|
||||
self.generating: bool = False
|
||||
|
||||
async def _handle(self, ev: EngineEvent) -> None:
|
||||
if ev.type == DELTA:
|
||||
self._delta_parts.append(ev.content)
|
||||
elif ev.type == REASONING:
|
||||
if self.keep_reasoning:
|
||||
self._reasoning_parts.append(ev.content)
|
||||
elif ev.type == STEP:
|
||||
self._record_step(ev)
|
||||
elif ev.type == DONE:
|
||||
wire = ev.to_wire()
|
||||
self.done = wire
|
||||
self.used_skills = wire.get("used_skills") or []
|
||||
self.used_mcp = wire.get("used_mcp") or []
|
||||
self.generating = bool(wire.get("generating"))
|
||||
if wire.get("process_steps"):
|
||||
self.steps = list(wire["process_steps"])
|
||||
elif ev.type == ERROR:
|
||||
self.error = str(ev.extra.get("message") or ev.content or "未知错误")
|
||||
self.error_diagnosis = ev.diagnosis
|
||||
|
||||
def _record_step(self, ev: EngineEvent) -> None:
|
||||
step = ev.extra.get("step")
|
||||
if not isinstance(step, dict):
|
||||
return
|
||||
idx = ev.extra.get("index")
|
||||
if isinstance(idx, int) and 0 <= idx < len(self.steps):
|
||||
self.steps[idx] = step
|
||||
else:
|
||||
self.steps.append(step)
|
||||
|
||||
# -- 装配 -----------------------------------------------------------
|
||||
@property
|
||||
def text(self) -> str:
|
||||
"""当前累积正文（done 优先）。"""
|
||||
if self.done and isinstance(self.done.get("content"), str) and self.done["content"]:
|
||||
return self.done["content"]
|
||||
return "".join(self._delta_parts)
|
||||
|
||||
def assemble(self) -> "str | dict":
|
||||
"""产出最终回复：媒体则给结构化 dict，否则给纯文本。
|
||||
|
||||
返回的 dict 契约必须与 im_llm 媒体快路径一致：
|
||||
{"__media__": True, "media_type": "image"|"video", "url": "..."}
|
||||
—— im_bot_user.py 依赖它做微信内联发图/发视频。
|
||||
"""
|
||||
body = self.text
|
||||
|
||||
media = self._extract_media(body)
|
||||
if media is not None:
|
||||
return media
|
||||
|
||||
if not body:
|
||||
if self.error:
|
||||
return self._render_failure()
|
||||
if self.generating:
|
||||
return "（内容正在生成中，请稍后在平台「AI 聊天」查看结果）"
|
||||
return "（未生成有效回复，请换个说法再试一次）"
|
||||
|
||||
notes = self._diagnosis_notes()
|
||||
if notes:
|
||||
body = body.rstrip() + "\n\n" + "\n".join(notes)
|
||||
if self.error:
|
||||
body = body.rstrip() + "\n\n" + self._render_failure()
|
||||
if self.generating:
|
||||
body = body.rstrip() + "\n\n（媒体正在后台生成，稍后可在平台「AI 聊天」查看）"
|
||||
|
||||
if len(body) > _MAX_ASSEMBLED_CHARS:
|
||||
body = body[:_MAX_ASSEMBLED_CHARS] + "\n…（内容过长已截断）"
|
||||
return body
|
||||
|
||||
# -- 内部 -----------------------------------------------------------
|
||||
@staticmethod
|
||||
def _extract_media(body: str) -> Optional[Dict[str, Any]]:
|
||||
s = (body or "").strip()
|
||||
if not (s.startswith("<img") or s.startswith("<video")):
|
||||
return None
|
||||
m = _MEDIA_RE.search(s)
|
||||
if not m:
|
||||
return None
|
||||
return {
|
||||
"__media__": True,
|
||||
"media_type": "image" if m.group(1).lower() == "img" else "video",
|
||||
"url": m.group(2),
|
||||
}
|
||||
|
||||
def _diagnosis_notes(self) -> List[str]:
|
||||
"""把失败步骤的结构化诊断降级成文本尾注（IM 无卡片 UI）。"""
|
||||
if not self.keep_diagnosis:
|
||||
return []
|
||||
notes: List[str] = []
|
||||
for step in self.steps:
|
||||
if not isinstance(step, dict):
|
||||
continue
|
||||
diag = Diagnosis.from_dict(step.get("diagnosis"))
|
||||
if diag is not None and diag.severity == "error":
|
||||
notes.append(diag.to_text())
|
||||
# 去重保序
|
||||
return list(dict.fromkeys(notes))
|
||||
|
||||
def _render_failure(self) -> str:
|
||||
if self.error_diagnosis is not None:
|
||||
return self.error_diagnosis.to_text()
|
||||
return f"⚠️ 生成中断：{self.error}"
|
||||
@@ -0,0 +1,349 @@
|
||||
"""双 Claw 引擎事件契约（#873 · P0）。
|
||||
|
||||
why:
|
||||
平台有且只有两个 Claw 出口 —— Web Claw(SSE 逐帧) 与 IM Bot Claw(整条推送)。
|
||||
在此之前，引擎事件是「散落在 chat_service 里的裸 dict」：
|
||||
|
||||
* 构造点分散，字段全靠记忆，漏一个键前端就静默不渲染；
|
||||
* 没有 trace_id / tenant_id / claw 标签，可观测(#876)无处落脚；
|
||||
* 失败只有一句人话字符串，前端靠 result.includes('失败') 猜错误 —— 极脆。
|
||||
|
||||
本模块把事件收敛为「唯一构造入口」：所有事件必须经 make_* 工厂产出，
|
||||
再由 to_wire() 统一序列化。新增字段一律「非空才输出」，
|
||||
保证既有前端(ChatPage.tsx)零改动。
|
||||
|
||||
线格式契约（authoritative —— 前端已消费，禁止破坏）:
|
||||
|
||||
delta -> {"type":"delta", "content": str}
|
||||
reasoning -> {"type":"reasoning", "content": str}
|
||||
step -> {"type":"step", "step": {...}, "index"?: int}
|
||||
done -> {"type":"done", "message_id", "conversation_id", "content",
|
||||
"process_steps", "used_skills", "used_mcp", "generating"}
|
||||
error -> {"type":"error", "message": str}
|
||||
|
||||
step 对象契约（AiProcessBlock 消费）:
|
||||
|
||||
thinking -> {"type":"thinking", "text": str}
|
||||
skill -> {"type":"skill", "name": str, "args": dict, "result": str}
|
||||
mcp -> {"type":"mcp", "server": str, "name": str, "args": dict, "result": str}
|
||||
|
||||
附加(新增，前端可选消费): "diagnosis": {...}, "phase": "start|ok|fail"
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
__all__ = [
|
||||
"SCHEMA_VERSION",
|
||||
"DELTA", "REASONING", "STEP", "DONE", "ERROR", "EVENT_TYPES",
|
||||
"STEP_THINKING", "STEP_SKILL", "STEP_MCP", "STEP_AGENT", "STEP_KB", "STEP_MEDIA",
|
||||
"PHASE_START", "PHASE_OK", "PHASE_FAIL",
|
||||
"CLAW_WEB", "CLAW_IM",
|
||||
"SEV_INFO", "SEV_WARN", "SEV_ERROR",
|
||||
"Diagnosis", "EngineEvent",
|
||||
"make_delta", "make_reasoning", "make_step", "make_done", "make_error",
|
||||
"from_wire",
|
||||
]
|
||||
|
||||
SCHEMA_VERSION = 1
|
||||
|
||||
# ---- 事件类型（线格式 type 值，前端已硬编码，禁止改名）----
|
||||
DELTA = "delta"
|
||||
REASONING = "reasoning"
|
||||
STEP = "step"
|
||||
DONE = "done"
|
||||
ERROR = "error"
|
||||
EVENT_TYPES = frozenset({DELTA, REASONING, STEP, DONE, ERROR})
|
||||
|
||||
# ---- step 子类（前端按此选图标 / 渲染分支）----
|
||||
STEP_THINKING = "thinking"
|
||||
STEP_SKILL = "skill"
|
||||
STEP_MCP = "mcp"
|
||||
STEP_AGENT = "agent" # 新增：外部 Agent 调用
|
||||
STEP_KB = "kb" # 新增：知识库检索
|
||||
STEP_MEDIA = "media" # 新增：媒体生成
|
||||
|
||||
# ---- 执行阶段 ----
|
||||
PHASE_START = "start"
|
||||
PHASE_OK = "ok"
|
||||
PHASE_FAIL = "fail"
|
||||
|
||||
# ---- Claw 通道标签（可观测 #876 的核心维度）----
|
||||
CLAW_WEB = "web"
|
||||
CLAW_IM = "im"
|
||||
|
||||
# ---- 诊断严重级 ----
|
||||
SEV_INFO = "info"
|
||||
SEV_WARN = "warn"
|
||||
SEV_ERROR = "error"
|
||||
|
||||
_SEV_ICON = {SEV_INFO: "ℹ️", SEV_WARN: "⚠️", SEV_ERROR: "❌"}
|
||||
|
||||
|
||||
@dataclass
|
||||
class Diagnosis:
|
||||
"""结构化诊断。
|
||||
|
||||
取代「把失败原因塞进 result 字符串、前端再 includes('失败') 猜」的旧做法：
|
||||
* Web Claw 可据此渲染诊断卡片（图标/配色/重试按钮）；
|
||||
* IM Bot Claw 无卡片 UI，用 to_text() 降级为纯文本行。
|
||||
"""
|
||||
|
||||
code: str = "" # 机器可读，如 "MCP_TIMEOUT" / "SKILL_NOT_FOUND"
|
||||
severity: str = SEV_INFO # info | warn | error
|
||||
summary: str = "" # 一句话结论（面向用户）
|
||||
detail: str = "" # 细节（可含技术信息，前端折叠展示）
|
||||
hint: str = "" # 可执行建议
|
||||
retryable: bool = False # 是否值得重试
|
||||
|
||||
def to_dict(self) -> Dict[str, Any]:
|
||||
return {
|
||||
"code": self.code,
|
||||
"severity": self.severity,
|
||||
"summary": self.summary,
|
||||
"detail": self.detail,
|
||||
"hint": self.hint,
|
||||
"retryable": self.retryable,
|
||||
}
|
||||
|
||||
def to_text(self) -> str:
|
||||
"""IM Bot Claw 的纯文本降级渲染。"""
|
||||
icon = _SEV_ICON.get(self.severity, "•")
|
||||
lines = [f"{icon} {self.summary or self.code or '执行提示'}"]
|
||||
if self.detail:
|
||||
lines.append(self.detail)
|
||||
if self.hint:
|
||||
lines.append(f"建议：{self.hint}")
|
||||
return "\n".join(lines)
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, d: Any) -> "Optional[Diagnosis]":
|
||||
if isinstance(d, Diagnosis):
|
||||
return d
|
||||
if not isinstance(d, dict):
|
||||
return None
|
||||
return cls(
|
||||
code=str(d.get("code") or ""),
|
||||
severity=str(d.get("severity") or SEV_INFO),
|
||||
summary=str(d.get("summary") or ""),
|
||||
detail=str(d.get("detail") or ""),
|
||||
hint=str(d.get("hint") or ""),
|
||||
retryable=bool(d.get("retryable")),
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class EngineEvent:
|
||||
"""引擎事件的唯一表示。禁止在业务代码里手搓等价 dict —— 用 make_* 工厂。"""
|
||||
|
||||
type: str
|
||||
content: str = ""
|
||||
seq: int = 0
|
||||
ts: float = field(default_factory=time.time)
|
||||
trace_id: str = ""
|
||||
tenant_id: str = ""
|
||||
claw: str = ""
|
||||
diagnosis: Optional[Diagnosis] = None
|
||||
# extra 承载各事件类型的专属键(message_id / step / process_steps ...)，
|
||||
# 序列化时平铺到顶层，以保持与既有线格式逐字节兼容。
|
||||
extra: Dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
# -- 谓词 ---------------------------------------------------------
|
||||
def is_terminal(self) -> bool:
|
||||
return self.type in (DONE, ERROR)
|
||||
|
||||
def is_text_chunk(self) -> bool:
|
||||
return self.type in (DELTA, REASONING)
|
||||
|
||||
# -- 序列化 -------------------------------------------------------
|
||||
def to_wire(self) -> Dict[str, Any]:
|
||||
"""序列化为通道线格式。
|
||||
|
||||
兼容铁律：既有键原样输出；新增键(seq/ts/claw/trace_id/tenant_id/diagnosis)
|
||||
一律「非空才输出」，既不撑大帧体积，也不触发前端未知分支。
|
||||
"""
|
||||
wire: Dict[str, Any] = {"type": self.type}
|
||||
|
||||
if self.type in (DELTA, REASONING):
|
||||
wire["content"] = self.content
|
||||
elif self.content:
|
||||
wire["content"] = self.content
|
||||
|
||||
for key, val in self.extra.items():
|
||||
wire[key] = val
|
||||
|
||||
if self.seq:
|
||||
wire["seq"] = self.seq
|
||||
if self.claw:
|
||||
wire["claw"] = self.claw
|
||||
if self.trace_id:
|
||||
wire["trace_id"] = self.trace_id
|
||||
if self.tenant_id:
|
||||
wire["tenant_id"] = self.tenant_id
|
||||
if self.diagnosis is not None:
|
||||
wire["diagnosis"] = self.diagnosis.to_dict()
|
||||
return wire
|
||||
|
||||
def to_text(self) -> str:
|
||||
"""无结构 UI 时(IM Bot)的降级文本；返回空串表示「本事件无需展示」。"""
|
||||
if self.type in (DELTA, DONE):
|
||||
return self.content
|
||||
if self.type == ERROR:
|
||||
if self.diagnosis is not None:
|
||||
return self.diagnosis.to_text()
|
||||
return f"❌ {self.extra.get('message') or self.content or '执行失败'}"
|
||||
if self.type == STEP and self.diagnosis is not None:
|
||||
return self.diagnosis.to_text()
|
||||
return ""
|
||||
|
||||
|
||||
# =====================================================================
|
||||
# 工厂 —— 唯一构造入口
|
||||
# =====================================================================
|
||||
def _ctx(kw: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""抽出通用上下文字段，避免每个工厂重复列参数。"""
|
||||
return {
|
||||
"seq": int(kw.pop("seq", 0) or 0),
|
||||
"trace_id": str(kw.pop("trace_id", "") or ""),
|
||||
"tenant_id": str(kw.pop("tenant_id", "") or ""),
|
||||
"claw": str(kw.pop("claw", "") or ""),
|
||||
}
|
||||
|
||||
|
||||
def make_delta(content: str, **kw) -> EngineEvent:
|
||||
"""正文增量。"""
|
||||
return EngineEvent(type=DELTA, content=content or "", **_ctx(kw))
|
||||
|
||||
|
||||
def make_reasoning(content: str, **kw) -> EngineEvent:
|
||||
"""思维链增量。"""
|
||||
return EngineEvent(type=REASONING, content=content or "", **_ctx(kw))
|
||||
|
||||
|
||||
def make_step(
|
||||
kind: str,
|
||||
*,
|
||||
name: str = "",
|
||||
text: str = "",
|
||||
server: str = "",
|
||||
args: Optional[Dict[str, Any]] = None,
|
||||
result: str = "",
|
||||
phase: str = "",
|
||||
index: Optional[int] = None,
|
||||
diagnosis: Any = None,
|
||||
**kw,
|
||||
) -> EngineEvent:
|
||||
"""过程步骤（思考 / 技能 / MCP / Agent / KB / 媒体）。
|
||||
|
||||
index 用于「原地更新同一步骤」：先发 phase=start 占位，
|
||||
执行完再用同一 index 发 phase=ok|fail 覆盖，前端即得到实时进度。
|
||||
"""
|
||||
step: Dict[str, Any] = {"type": kind}
|
||||
if kind == STEP_THINKING:
|
||||
step["text"] = text or name or ""
|
||||
else:
|
||||
if name:
|
||||
step["name"] = name
|
||||
if server:
|
||||
step["server"] = server
|
||||
if text:
|
||||
step["text"] = text
|
||||
step["args"] = args or {}
|
||||
step["result"] = result or ""
|
||||
if phase:
|
||||
step["phase"] = phase
|
||||
|
||||
diag = Diagnosis.from_dict(diagnosis) if diagnosis is not None else None
|
||||
if diag is not None:
|
||||
step["diagnosis"] = diag.to_dict()
|
||||
# result 为空时前端会判定为「运行中」，故失败必须给出可读 result 兜底
|
||||
if not step["result"] and diag.severity == SEV_ERROR:
|
||||
step["result"] = diag.to_text()
|
||||
|
||||
extra: Dict[str, Any] = {"step": step}
|
||||
if isinstance(index, int) and index >= 0:
|
||||
extra["index"] = index
|
||||
|
||||
return EngineEvent(type=STEP, diagnosis=diag, extra=extra, **_ctx(kw))
|
||||
|
||||
|
||||
def make_done(
|
||||
*,
|
||||
message_id: Any = None,
|
||||
conversation_id: Any = None,
|
||||
content: str = "",
|
||||
process_steps: Optional[list] = None,
|
||||
used_skills: Optional[list] = None,
|
||||
used_mcp: Optional[list] = None,
|
||||
generating: bool = False,
|
||||
**kw,
|
||||
) -> EngineEvent:
|
||||
"""终帧。字段集必须与既有 done 帧完全一致。"""
|
||||
extra = {
|
||||
"message_id": message_id,
|
||||
"conversation_id": conversation_id,
|
||||
"content": content or "",
|
||||
"process_steps": process_steps or [],
|
||||
"used_skills": used_skills or [],
|
||||
"used_mcp": used_mcp or [],
|
||||
"generating": bool(generating),
|
||||
}
|
||||
return EngineEvent(type=DONE, content=content or "", extra=extra, **_ctx(kw))
|
||||
|
||||
|
||||
def make_error(message: str, *, diagnosis: Any = None, **kw) -> EngineEvent:
|
||||
"""错误终帧。"""
|
||||
diag = Diagnosis.from_dict(diagnosis) if diagnosis is not None else None
|
||||
return EngineEvent(
|
||||
type=ERROR,
|
||||
diagnosis=diag,
|
||||
extra={"message": message or ""},
|
||||
**_ctx(kw),
|
||||
)
|
||||
|
||||
|
||||
def from_wire(payload: Any) -> Optional[EngineEvent]:
|
||||
"""把遗留裸 dict 提升为 EngineEvent（迁移期双向兼容的关键）。
|
||||
|
||||
chat_service.py 里仍有直接 await on_event({...}) 的老代码，
|
||||
Adapter 收到后一律经此函数归一化，之后全链路只面对 EngineEvent。
|
||||
"""
|
||||
if isinstance(payload, EngineEvent):
|
||||
return payload
|
||||
if not isinstance(payload, dict):
|
||||
return None
|
||||
|
||||
d = dict(payload)
|
||||
etype = str(d.pop("type", "") or "")
|
||||
if not etype:
|
||||
return None
|
||||
|
||||
content = d.pop("content", "")
|
||||
if not isinstance(content, str):
|
||||
# done 帧的 content 理论上是 str；异常类型保留原值到 extra，避免丢数据
|
||||
d["content"] = content
|
||||
content = ""
|
||||
|
||||
diag = Diagnosis.from_dict(d.pop("diagnosis", None))
|
||||
seq = d.pop("seq", 0)
|
||||
trace_id = d.pop("trace_id", "")
|
||||
tenant_id = d.pop("tenant_id", "")
|
||||
claw = d.pop("claw", "")
|
||||
d.pop("ts", None)
|
||||
|
||||
# done 帧的 content 需回填到 extra，才能在 to_wire() 时原样吐回
|
||||
if etype == DONE:
|
||||
d["content"] = content
|
||||
|
||||
return EngineEvent(
|
||||
type=etype,
|
||||
content=content,
|
||||
seq=int(seq or 0),
|
||||
trace_id=str(trace_id or ""),
|
||||
tenant_id=str(tenant_id or ""),
|
||||
claw=str(claw or ""),
|
||||
diagnosis=diag,
|
||||
extra=d,
|
||||
)
|
||||
Reference in new issue
Block a user