Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
68 lines
2.3 KiB
Python
68 lines
2.3 KiB
Python
"""截断检测 DTO。
|
||
|
||
定义上下文截断检测的不可变值对象，包括截断候选与截断结果。所有 DTO 均为
|
||
``dataclass(frozen=True)``，仅依赖标准库，用于上下文长度超限时的截断
|
||
检测与降级策略决策。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class TruncationCandidate:
|
||
"""截断候选。
|
||
|
||
描述一个待截断的文本片段，包括文本内容、来源与长度，用于截断策略的
|
||
优先级排序。
|
||
|
||
字段：
|
||
text: 文本内容。
|
||
source: 来源（system_prompt | context_remark | user_message | ...）。
|
||
length: 文本长度。
|
||
"""
|
||
|
||
text: str
|
||
source: str
|
||
length: int
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 text / source 非空与 length 非负。
|
||
|
||
``text`` 与 ``source`` 必须非空，``length`` 必须非负，在构造时即
|
||
抛出 ``ValidationError``，避免空文本或负长度破坏截断策略排序（INV-8）。
|
||
"""
|
||
if not self.text:
|
||
raise ValidationError("text", "must not be empty")
|
||
if not self.source:
|
||
raise ValidationError("source", "must not be empty")
|
||
if self.length < 0:
|
||
raise ValidationError("length", "must not be negative")
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class TruncationResult:
|
||
"""截断结果。
|
||
|
||
描述截断检测的结果，包括是否发生截断、缺失内容与是否降级到持久化查询。
|
||
检测到截断时携带补全文本与长度信息（FR-28）。
|
||
|
||
字段：
|
||
is_truncated: 是否发生截断。
|
||
missing_content: 缺失内容（未截断时为 None）。
|
||
fallback_to_persistent: 是否降级到持久化查询（默认 False）。
|
||
completed_text: 补全后的文本（补全失败时为原始截断文本，未截断时为 None）。
|
||
original_length: 原始截断文本长度（未截断时为 None）。
|
||
completed_length: 补全后文本长度（未截断时为 None）。
|
||
"""
|
||
|
||
is_truncated: bool
|
||
missing_content: str | None = None
|
||
fallback_to_persistent: bool = False
|
||
completed_text: str | None = None
|
||
original_length: int | None = None
|
||
completed_length: int | None = None
|