Files
universal-web-api/app/core/parsers/base.py
T
2026-11-02 22:54:14 +08:00

181 lines
5.4 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""
app/core/parsers/base.py - 响应解析器基类
定义网络响应解析的标准接口(支持增量响应)
"""
from abc import ABC, abstractmethod
from typing import Dict, List, Optional, Any
class ResponseParser(ABC):
"""
响应解析器抽象基类
职责:
- 解析网络拦截到的原始响应体
- 支持增量响应(流式传输)
- 提取文本内容和图片
"""
# ============ 抽象方法(子类必须实现)============
@abstractmethod
def parse_chunk(self, raw_response: str) -> Dict[str, Any]:
"""
解析单次响应数据(增量)
Args:
raw_response: 原始响应体(字符串)
Returns:
{
"content": str, # 本次增量的文本内容
"images": List[Dict], # 本次增量的图片(可选)
"done": bool, # 是否为最后一块数据
"error": Optional[str] # 解析错误信息
}
注意:
- content 为空字符串表示本次无新增文本
- images 为空列表表示本次无新增图片
- done=True 表示流式传输结束
- error 不为 None 表示解析失败
"""
pass
@abstractmethod
def reset(self):
"""
重置解析器状态
用于新一轮对话开始时清空累积状态
"""
pass
def _prepare_incremental_raw_response(self, raw_response: str) -> str:
"""
Return the append-only delta for a full raw response snapshot.
Network listeners usually pass a growing full body to parsers. When the
browser replaces that snapshot with another response of the same or
greater length, slicing by length alone loses content. This helper
preserves the fast append path and resets parser state when the new
snapshot is not a prefix extension of the previous one.
"""
if not isinstance(raw_response, str):
raw_response = str(raw_response)
previous = getattr(self, "_last_raw_response", "")
try:
previous_len = int(getattr(self, "_last_raw_length", 0) or 0)
except Exception:
previous_len = 0
if previous_len > 0 and previous:
if raw_response == previous:
return ""
if raw_response.startswith(previous):
new_data = raw_response[len(previous):]
else:
self.reset()
new_data = raw_response
else:
new_data = raw_response
self._last_raw_length = len(raw_response)
self._last_raw_response = raw_response
return new_data
# ============ 可选覆盖方法 ============
def validate_response(self, raw_response: str) -> bool:
"""
验证响应格式是否匹配此解析器
Args:
raw_response: 原始响应体
Returns:
True 表示格式匹配,False 表示不匹配
"""
try:
result = self.parse_chunk(raw_response)
return result.get("error") is None
except Exception:
return False
def should_abort_on_error(self) -> bool:
"""
当 parse_chunk 返回 error 时,是否应立即终止当前工作流。
默认仅记录并继续,交给具体解析器按需升级为硬失败。
"""
return False
def should_fallback_to_dom_when_no_visible_content(self) -> bool:
"""
网络流存在但长期拿不到可见正文时,是否优先回退 DOM 监听。
适用于网络协议里混入推理/中间态,而页面真实正文由前端二次拼装的站点。
"""
return False
def should_require_explicit_done(self) -> bool:
"""Whether a stream must expose its protocol-level completion event."""
return False
def should_wait_for_replacement_stream_on_incomplete_capture(self) -> bool:
"""Whether an incomplete captured response may be followed by another stream."""
return False
def get_media_generation_state(
self,
raw_response: str = "",
parse_result: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
"""
提取通用的媒体生成状态。
返回约定:
{
"pending": bool,
"media_type": "image" | "audio" | "video" | "",
"hint_text": str,
"wait_timeout_seconds": float | int | None,
}
通用工作流层只消费这些字段,不关心站点私有协议细节。
"""
return {}
# ============ 元数据接口 ============
@classmethod
def get_id(cls) -> str:
"""解析器唯一标识符"""
return cls.__name__.lower().replace('parser', '')
@classmethod
def get_name(cls) -> str:
"""解析器显示名称"""
return cls.__name__
@classmethod
def get_description(cls) -> str:
"""解析器描述"""
return "未提供描述"
@classmethod
def get_supported_patterns(cls) -> List[str]:
"""
返回此解析器支持的 URL 匹配模式
Returns:
URL 子串列表(用于 page.listen.start())
"""
return []
__all__ = ['ResponseParser']