Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
43 lines
1.3 KiB
Python
43 lines
1.3 KiB
Python
"""流式事件 DTO。
|
||
|
||
定义 ``AgentRunPort.streamAgentRun`` 返回的流式事件类型，替代原
|
||
``AsyncIterator[Any]`` 的弱类型签名（CON-019）。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Any
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class StreamEvent:
|
||
"""Agent 运行流式事件。
|
||
|
||
封装从 Redis Stream 读取的事件，供下游 SSE 渲染或事件重放使用。
|
||
|
||
字段：
|
||
event_type: 事件类型（如 ``messages`` / ``tool_call``）。
|
||
payload: 事件负载字典，结构由事件类型决定。
|
||
seq: Redis Stream 消息 ID，用于分页与去重。
|
||
|
||
关联约束：CON-019（端口返回类型不得使用 ``Any``）。
|
||
"""
|
||
|
||
event_type: str
|
||
payload: dict[str, Any]
|
||
seq: str
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 event_type 与 seq 非空。
|
||
|
||
``event_type`` 与 ``seq`` 必须非空，在构造时即抛出 ``ValidationError``，
|
||
避免空事件类型或空序列号导致事件渲染与去重失效（INV-8 / CON-019）。
|
||
"""
|
||
if not self.event_type:
|
||
raise ValidationError("event_type", "must not be empty")
|
||
if not self.seq:
|
||
raise ValidationError("seq", "must not be empty")
|