kkprotocol 0.1.0__py3-none-any.whl

kkprotocol/fields.py

@@ -0,0 +1,167 @@
+# -*- coding: utf-8 -*-
+"""字段规则：用字段类代替字典，获得完整的 IDE 智能提示。
+
+三种写法都支持（推荐第一种）：
+
+1. 工厂方法，最短且有类型提示::
+
+       Field.u8("header", fixed=0x55)
+       Field.u16("ser")
+       Field.raw("data", "{len.val}-10")
+       Field.checksum("crc", 2, group="{len}{ver}{data}")
+
+2. 完整构造::
+
+       Field(key="header", length=1, fmt="B", fixed=0x55)
+
+3. 旧式字典（兼容既有代码）::
+
+       {"key": "header", "len": 1, "fmt": "B", "fixed": 0x55}
+
+字段属性说明：
+
+``key``
+    字段名，帧内唯一。
+``length``
+    长度。取值：``int``、``"10"``、表达式 ``"{len.val}-10"``、
+    回调 ``callable(fields) -> int``，或 ``None`` 表示“取到帧尾为止”
+    （只能用于分隔符定界，长度定界下编译期就会报错）。
+    表达式里 ``{字段.属性}`` 的属性只能是 ``val``（数值）、``len``/``bytes``
+    （该字段实际字节数）。
+``fmt``
+    ``struct`` 格式串，必须只解析出一个值；为空表示字段值就是原始 ``bytes``。
+    多字节数值请显式带字节序前缀（``!``/``<``），避免原生对齐差异。
+``fixed``
+    期望常量。``int`` 与解析值比较，``bytes`` 与原始字节比较，``None`` 表示不校验。
+``group``
+    校验字段专用：参与校验的字段模板，如 ``"{len}{ver}{data}"``。
+    给出了 ``group`` 就自动视为校验字段，``crc`` 可省略；省略 ``group`` 时
+    校验它前面所有字段。
+``crc``
+    显式标记为校验字段（配合 ``crc_imp`` 使用）。
+``desc``
+    仅注释用，方便阅读规则表。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional, Union
+
+__all__ = ["Field"]
+
+
+@dataclass(frozen=True)
+class Field:
+    """一个字段的声明式规则。"""
+
+    key: str
+    length: Optional[Union[int, str, Callable[[Dict[str, Any]], int]]] = 0
+    fmt: str = ""
+    fixed: Any = None
+    group: Optional[str] = None
+    crc: bool = False
+    desc: str = ""
+
+    # ------------------------------------------------------------------ 工厂
+    @classmethod
+    def u8(cls, key: str, *, fixed: Optional[int] = None, desc: str = "") -> "Field":
+        """1 字节无符号整数。"""
+        return cls(key=key, length=1, fmt="B", fixed=fixed, desc=desc)
+
+    @classmethod
+    def u16(
+        cls,
+        key: str,
+        *,
+        fixed: Optional[int] = None,
+        little_endian: bool = False,
+        desc: str = "",
+    ) -> "Field":
+        """2 字节无符号整数，默认大端。"""
+        return cls(
+            key=key, length=2, fmt="<H" if little_endian else "!H", fixed=fixed, desc=desc
+        )
+
+    @classmethod
+    def u32(
+        cls,
+        key: str,
+        *,
+        fixed: Optional[int] = None,
+        little_endian: bool = False,
+        desc: str = "",
+    ) -> "Field":
+        """4 字节无符号整数，默认大端。"""
+        return cls(
+            key=key, length=4, fmt="<I" if little_endian else "!I", fixed=fixed, desc=desc
+        )
+
+    @classmethod
+    def u64(
+        cls,
+        key: str,
+        *,
+        fixed: Optional[int] = None,
+        little_endian: bool = False,
+        desc: str = "",
+    ) -> "Field":
+        """8 字节无符号整数，默认大端。"""
+        return cls(
+            key=key, length=8, fmt="<Q" if little_endian else "!Q", fixed=fixed, desc=desc
+        )
+
+    @classmethod
+    def raw(
+        cls,
+        key: str,
+        length: Optional[Union[int, str, Callable[[Dict[str, Any]], int]]] = 0,
+        *,
+        fixed: Optional[bytes] = None,
+        desc: str = "",
+    ) -> "Field":
+        """原始字节字段（不做 struct 解包，值即 bytes）。"""
+        return cls(key=key, length=length, fmt="", fixed=fixed, desc=desc)
+
+    @classmethod
+    def rest(cls, key: str, *, desc: str = "") -> "Field":
+        """“取到帧尾为止”的字段（仅分隔符定界可用，行协议常用）。"""
+        return cls(key=key, length=None, fmt="", desc=desc)
+
+    @classmethod
+    def checksum(
+        cls,
+        key: str,
+        length: Union[int, str] = 2,
+        *,
+        group: Optional[str] = None,
+        fmt: Optional[str] = None,
+        desc: str = "",
+    ) -> "Field":
+        """校验字段（CRC/累加和等），校验算法由 ``crc_imp`` 提供。
+
+        ``fmt`` 省略时按 ``length`` 自动选（1 字节 ``B``、2 字节 ``!H``、
+        4 字节 ``!I``、8 字节 ``!Q``，其他情况按原始字节处理）。
+        """
+        if fmt is None:
+            fmt = {1: "B", 2: "!H", 4: "!I", 8: "!Q"}.get(
+                length if isinstance(length, int) else -1, ""
+            )
+        return cls(key=key, length=length, fmt=fmt, group=group, crc=True, desc=desc)
+
+    # ------------------------------------------------------------------ 兼容
+    @classmethod
+    def from_dict(cls, rule: Dict[str, Any]) -> "Field":
+        """把旧式字典规则转成字段类（内部编译也走这里）。"""
+        if not isinstance(rule, dict):
+            raise TypeError("规则必须是 dict 或 Field，实际 {}".format(type(rule).__name__))
+        spec_len = rule["len"] if "len" in rule else rule.get("length", 0)
+        return cls(
+            key=rule.get("key"),
+            length=spec_len,
+            fmt=rule.get("fmt") or "",
+            fixed=rule.get("fixed"),
+            group=rule.get("group"),
+            crc=bool(rule.get("crc", False)),
+            desc=rule.get("desc", ""),
+        )

kkprotocol/frame.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+"""解析结果：字段值与整帧。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+__all__ = ["FieldValue", "Frame"]
+
+
+@dataclass(frozen=True)
+class FieldValue:
+    """单个字段的解析结果。
+
+    ``raw`` 是字段原始字节（定界模式下为**反转义后**的字节），``val`` 是 ``fmt``
+    解出的值；``fmt`` 为空时 ``val`` 就是 ``raw`` 本身。
+    """
+
+    key: str
+    raw: bytes
+    val: Any
+
+    @property
+    def length(self) -> int:
+        """该字段实际占用的字节数。"""
+        return len(self.raw)
+
+    def __len__(self) -> int:
+        return len(self.raw)
+
+    def __int__(self) -> int:
+        if not isinstance(self.val, int):
+            raise TypeError("字段 {} 的值不是整数（fmt 为空时值为 bytes）".format(self.key))
+        return int(self.val)
+
+    def __repr__(self) -> str:  # pragma: no cover - 调试展示
+        return "FieldValue(key={!r}, len={}, val={!r})".format(self.key, len(self.raw), self.val)
+
+
+@dataclass(frozen=True)
+class Frame:
+    """一帧完整数据的解析结果。
+
+    * ``raw``：解析器交给规则的字节（定界模式下已去掉定界符并完成反转义）
+    * ``wire``：这一帧在流中实际占用的字节（含定界符与转义字节），便于抓包比对
+    * ``framing``：本帧使用的定界方式，``"length"`` 或 ``"delimiter"``
+    * ``device_id``：该帧携带的设备标识（由 ``device_field`` 指定字段得出），
+      未配置 ``device_field`` 时为 ``None``
+    * ``device_mismatch``：与已绑定设备号不一致（仅在 ``enforce_device_id=False`` 时还会返回）
+    * ``learned_device``：本帧是否触发了设备号自动学习
+    """
+
+    raw: bytes
+    fields: Dict[str, FieldValue] = field(default_factory=dict)
+    wire: Optional[bytes] = None
+    framing: str = "length"
+    device_id: Any = None
+    device_mismatch: bool = False
+    learned_device: bool = False
+
+    def __getitem__(self, key: str) -> FieldValue:
+        return self.fields[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.fields
+
+    def __len__(self) -> int:
+        return len(self.raw)
+
+    def keys(self):
+        return self.fields.keys()
+
+    def value(self, key: str, default: Any = None) -> Any:
+        """取字段值；字段不存在时返回 default。"""
+        fv = self.fields.get(key)
+        return default if fv is None else fv.val
+
+    def raw_of(self, key: str) -> bytes:
+        """取字段原始字节。"""
+        return self.fields[key].raw
+
+    # ------------------------------------------------------------------ 整帧字节
+    def to_bytes(self, wire: bool = True) -> bytes:
+        """整帧字节。
+
+        ``wire=True``（默认）返回这一帧在流里实际占用的字节：长度定界就是
+        ``55 AA ...`` 的原文，分隔符定界还包含首尾标志位和转义字节。
+        ``wire=False`` 返回交给规则解析的净帧字节（已去定界符、已反转义）。
+        """
+        if wire and self.wire is not None:
+            return self.wire
+        return self.raw
+
+    def to_hex(self, sep: str = " ", upper: bool = True, wire: bool = True) -> str:
+        """整帧的十六进制字符串，默认形如 ``"55 AA 00 59 02 00 ..."``。
+
+        ``sep=""`` 得到 ``"55AA00590200..."``，``upper=False`` 得到小写。
+        """
+        data = self.to_bytes(wire)
+        text = data.hex() if not sep else data.hex(sep)
+        return text.upper() if upper else text
+
+    def __bytes__(self) -> bytes:
+        return self.to_bytes()
+
+    def as_dict(self) -> Dict[str, Any]:
+        """{字段名: 值} 的扁平字典，便于直接消费。"""
+        return {k: v.val for k, v in self.fields.items()}
+
+    def __repr__(self) -> str:  # pragma: no cover - 调试展示
+        return "Frame(framing={}, len={}, fields={})".format(
+            self.framing, len(self.raw), list(self.fields)
+        )

kkprotocol/frame_codec.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""兼容旧导入路径（v1 的 ``kkprotocol.frame_codec``）。
+
+新代码请直接 ``from kkprotocol import ...``；这个模块只做转发，
+并把旧类名 ``AbstractProtocolBaseFilter`` 映射到 ``AbstractFrameCodec``。
+"""
+
+from __future__ import annotations
+
+from .codec import AbstractFrameCodec, CodecStats
+from .compiler import CompiledField, compile_rules
+from .errors import FrameCodecError, FrameRuleError
+from .fields import Field
+from .frame import FieldValue, Frame
+from .framing import (
+    AUTO_FRAMING,
+    DELIMITER_FRAMING,
+    LENGTH_FRAMING,
+    DelimiterFraming,
+    escape_bytes,
+    find_end_delimiter,
+    unescape_bytes,
+    wrap_frame,
+)
+from .length import LengthExpr
+
+# 旧类名兼容
+AbstractProtocolBaseFilter = AbstractFrameCodec
+
+__all__ = [
+    "AbstractFrameCodec",
+    "AbstractProtocolBaseFilter",
+    "AUTO_FRAMING",
+    "CodecStats",
+    "CompiledField",
+    "DELIMITER_FRAMING",
+    "DelimiterFraming",
+    "Field",
+    "FieldValue",
+    "Frame",
+    "FrameCodecError",
+    "FrameRuleError",
+    "LENGTH_FRAMING",
+    "LengthExpr",
+    "compile_rules",
+    "escape_bytes",
+    "find_end_delimiter",
+    "unescape_bytes",
+    "wrap_frame",
+]

kkprotocol/framing.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""定界方式：长度前缀定界 与 分隔符定界（含字节转义 / 透明传输）。
+
+两种定界的本质区别：
+
+* ``length``（长度定界）：先读长度字段，再按长度取字节。净荷里出现任何字节都
+  无害，**不需要转义**；但长度字段一旦被破坏，整条流会跟着错位。
+* ``delimiter``（分隔符定界）：按特殊字节（如 ``0x7E``）切帧。净荷里若出现同样的
+  字节会误判帧边界，因此**必须转义**；此时长度字段只能作为“参考值/校验项”，
+  不能当作切帧依据（转义会让线上长度和净荷长度不一致）。
+
+``auto`` 模式会先用长度定界尝试解析，失败再试分隔符定界，命中一次后锁定策略。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Mapping, Optional, Union
+
+from .errors import FrameRuleError
+
+__all__ = [
+    "LENGTH_FRAMING",
+    "DELIMITER_FRAMING",
+    "AUTO_FRAMING",
+    "FRAMING_MODES",
+    "DelimiterFraming",
+    "escape_bytes",
+    "unescape_bytes",
+    "find_end_delimiter",
+    "wrap_frame",
+]
+
+LENGTH_FRAMING = "length"
+DELIMITER_FRAMING = "delimiter"
+AUTO_FRAMING = "auto"
+FRAMING_MODES = frozenset({LENGTH_FRAMING, DELIMITER_FRAMING, AUTO_FRAMING})
+
+
+def _check_byte(name: str, value: int) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or not 0 <= value <= 0xFF:
+        raise FrameRuleError("{} 必须是 0..255 的整数，实际 {!r}".format(name, value))
+
+
+@dataclass(frozen=True)
+class DelimiterFraming:
+    """分隔符定界配置。
+
+    :param end: 帧尾定界字节（必须）
+    :param start: 帧头定界字节，可省略。``start == end`` 表示首尾共用一个标志
+        （PPP/HDLC 风格）；两者都配置时，帧内容取两者之间。
+    :param escape: 转义字节；``None`` 表示不做转义
+    :param escape_xor: 转义字节后一字节与原始字节的异或值（PPP/HDLC 为 0x20）
+    :param escape_map: 显式映射（原始字节 -> 转义后第二字节），用于 SLIP 这类
+        非异或方案；未命中的字节仍按 ``escape_xor`` 还原
+    """
+
+    end: int
+    start: Optional[int] = None
+    escape: Optional[int] = None
+    escape_xor: int = 0x20
+    escape_map: Optional[Mapping[int, int]] = None
+
+    _map: Dict[int, int] = field(init=False, repr=False, compare=False, default_factory=dict)
+    _reverse: Dict[int, int] = field(init=False, repr=False, compare=False, default_factory=dict)
+    _targets: frozenset = field(init=False, repr=False, compare=False, default_factory=frozenset)
+
+    def __post_init__(self) -> None:
+        _check_byte("end", self.end)
+        if self.start is not None:
+            _check_byte("start", self.start)
+        if self.escape is not None:
+            _check_byte("escape", self.escape)
+        _check_byte("escape_xor", self.escape_xor)
+
+        if self.escape is not None and self.escape in (self.end, self.start):
+            raise FrameRuleError("转义字节不能与定界符相同（会造成歧义）")
+
+        forward: Dict[int, int] = {}
+        reverse: Dict[int, int] = {}
+        if self.escape_map:
+            for original, second in self.escape_map.items():
+                _check_byte("escape_map 键", original)
+                _check_byte("escape_map 值", second)
+                if second in reverse:
+                    raise FrameRuleError("escape_map 中第二字节 {!r} 重复".format(second))
+                forward[original] = second
+                reverse[second] = original
+
+        targets = set()
+        if self.escape is not None:
+            for value in (self.start, self.end, self.escape):
+                if value is not None:
+                    targets.add(value)
+            for target in list(targets):
+                second = reverse.get(target, target ^ self.escape_xor)
+                if second in targets and reverse.get(second) != target:
+                    raise FrameRuleError(
+                        "转义后字节 {:#04x} 与定界/转义字节冲突，请显式提供 escape_map".format(second)
+                    )
+
+        object.__setattr__(self, "_map", forward)
+        object.__setattr__(self, "_reverse", reverse)
+        object.__setattr__(self, "_targets", frozenset(targets))
+
+    # ------------------------------------------------------------------ 查询
+    @property
+    def targets(self) -> frozenset:
+        """必须被转义的字节集合（帧头/帧尾/转义字节自身）。"""
+        return self._targets
+
+    @property
+    def reversed_map(self) -> Dict[int, int]:
+        """转义后第二字节 -> 原始字节。"""
+        return self._reverse
+
+    def second_byte(self, original: int) -> int:
+        """原始字节转义后跟在转义字节后面的那一字节。"""
+        return self._map.get(original, original ^ self.escape_xor)
+
+
+def escape_bytes(data: Union[bytes, bytearray], spec: DelimiterFraming) -> bytes:
+    """按配置转义（发送方向）。"""
+    if spec.escape is None:
+        return bytes(data)
+    targets = spec.targets
+    escape = spec.escape
+    out = bytearray()
+    for byte in data:
+        if byte in targets:
+            out.append(escape)
+            out.append(spec.second_byte(byte))
+        else:
+            out.append(byte)
+    return bytes(out)
+
+
+def unescape_bytes(data: Union[bytes, bytearray], spec: DelimiterFraming) -> bytes:
+    """按配置反转义。遇到悬空转义字节（帧被截断）或非法转义序列抛 ``ValueError``。"""
+    if spec.escape is None:
+        return bytes(data)
+    escape = spec.escape
+    reverse = spec.reversed_map
+    xor = spec.escape_xor
+    out = bytearray()
+    index = 0
+    size = len(data)
+    while index < size:
+        byte = data[index]
+        if byte == escape:
+            if index + 1 >= size:
+                raise ValueError("帧以转义字节 0x{:02X} 结尾，数据被截断".format(escape))
+            second = data[index + 1]
+            original = reverse.get(second)
+            out.append(second ^ xor if original is None else original)
+            index += 2
+        else:
+            out.append(byte)
+            index += 1
+    return bytes(out)
+
+
+def find_end_delimiter(
+    buf: Union[bytes, bytearray], start: int, spec: DelimiterFraming
+) -> Optional[int]:
+    """从 start 起找第一个**未被转义**的帧尾定界字节，返回其下标。"""
+    end = spec.end
+    escape = spec.escape
+    index = start
+    size = len(buf)
+    if escape is None:
+        found = bytes(buf[index:]).find(bytes([end]))
+        return None if found < 0 else index + found
+    while index < size:
+        byte = buf[index]
+        if byte == escape:
+            index += 2
+            continue
+        if byte == end:
+            return index
+        index += 1
+    return None
+
+
+def wrap_frame(payload: Union[bytes, bytearray], spec: DelimiterFraming) -> bytes:
+    """发送方向：把净荷按分隔符/转义规则封装成线上字节（便于构造测试与设备下行）。"""
+    body = escape_bytes(payload, spec)
+    if spec.start is not None:
+        return bytes([spec.start]) + body + bytes([spec.end])
+    return body + bytes([spec.end])

kkprotocol/length.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""长度表达式：``{len.val}-1-1-2-4-2`` 的编译与求值。
+
+用 AST 白名单求值，**不使用 eval**，因此表达式无法执行任意代码。
+编译期做常量折叠（``-1-1-2-4-2`` 折叠成 ``-10``），解析期只剩一次减法。
+"""
+
+from __future__ import annotations
+
+import ast
+import itertools
+import re
+from typing import Any, Dict, Tuple
+
+from .errors import FrameInvalid, FrameRuleError
+
+__all__ = ["LengthExpr"]
+
+_REF_RE = re.compile(r"\{\s*([A-Za-z_]\w*)\s*\.\s*([A-Za-z_]\w*)\s*\}")
+_GROUP_REF_RE = re.compile(r"\{\s*([A-Za-z_]\w*)\s*\}")
+_LEN_ATTRS = frozenset({"len", "length", "bytes", "raw"})
+
+_BIN_OPS = {
+    ast.Add: lambda a, b: a + b,
+    ast.Sub: lambda a, b: a - b,
+    ast.Mult: lambda a, b: a * b,
+    ast.FloorDiv: lambda a, b: a // b,
+    ast.Mod: lambda a, b: a % b,
+}
+
+
+def _eval_ast(node: ast.AST, values: Dict[str, int]) -> int:
+    if isinstance(node, ast.Constant):
+        return int(node.value)
+    if isinstance(node, ast.Name):
+        return values[node.id]
+    if isinstance(node, ast.UnaryOp):
+        if isinstance(node.op, ast.USub):
+            return -_eval_ast(node.operand, values)
+        return _eval_ast(node.operand, values)
+    if isinstance(node, ast.BinOp):
+        op = _BIN_OPS[type(node.op)]
+        try:
+            return op(_eval_ast(node.left, values), _eval_ast(node.right, values))
+        except ZeroDivisionError:
+            raise FrameInvalid("长度表达式除零") from None
+    raise FrameRuleError(  # pragma: no cover - 编译期已拦截
+        "长度表达式含不支持的语法节点 {}".format(type(node).__name__)
+    )
+
+
+def _fold(node: ast.AST) -> ast.AST:
+    """编译期常量折叠。"""
+    if isinstance(node, ast.BinOp):
+        left = _fold(node.left)
+        right = _fold(node.right)
+        if isinstance(left, ast.Constant) and isinstance(right, ast.Constant):
+            return ast.Constant(value=_BIN_OPS[type(node.op)](left.value, right.value))
+        return ast.BinOp(left=left, op=node.op, right=right)
+    if isinstance(node, ast.UnaryOp) and isinstance(node.operand, ast.Constant):
+        value = node.operand.value
+        return ast.Constant(value=-value if isinstance(node.op, ast.USub) else value)
+    return node
+
+
+class LengthExpr:
+    """一个已编译的长度表达式。"""
+
+    __slots__ = ("source", "_tree", "_names", "_refs")
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+        names: Dict[str, Tuple[str, str]] = {}
+        counter = itertools.count()
+
+        def _replace(match: "re.Match[str]") -> str:
+            token = "_v{}".format(next(counter))
+            names[token] = (match.group(1), match.group(2))
+            return token
+
+        expr = _REF_RE.sub(_replace, source)
+        if not names:
+            raise FrameRuleError(
+                "长度 {!r} 既不是整数也不是含 {{字段.属性}} 的表达式".format(source)
+            )
+        try:
+            tree = ast.parse(expr, mode="eval")
+        except SyntaxError as exc:
+            raise FrameRuleError("长度表达式 {!r} 语法错误: {}".format(source, exc.msg)) from exc
+        self._check(tree)
+        try:
+            folded = _fold(tree.body)
+        except ZeroDivisionError:
+            raise FrameRuleError("长度表达式 {!r} 含常量除零".format(source)) from None
+        self._tree = ast.Expression(body=folded)
+        self._names = names
+        self._refs = tuple((token, key, attr) for token, (key, attr) in names.items())
+
+    # ------------------------------------------------------------------ 校验
+    @property
+    def refs(self) -> Tuple[Tuple[str, str], ...]:
+        return tuple(self._names.values())
+
+    @staticmethod
+    def _check(node: ast.AST) -> None:
+        if isinstance(node, ast.Expression):
+            LengthExpr._check(node.body)
+            return
+        if isinstance(node, ast.Constant):
+            if isinstance(node.value, bool) or not isinstance(node.value, int):
+                raise FrameRuleError("长度表达式只允许整数常量，发现 {!r}".format(node.value))
+            return
+        if isinstance(node, ast.Name):
+            return
+        if isinstance(node, ast.UnaryOp):
+            if not isinstance(node.op, (ast.USub, ast.UAdd)):
+                raise FrameRuleError("长度表达式不支持的运算符 {}".format(type(node.op).__name__))
+            LengthExpr._check(node.operand)
+            return
+        if isinstance(node, ast.BinOp):
+            if type(node.op) not in _BIN_OPS:
+                raise FrameRuleError(
+                    "长度表达式不支持的运算符 {}（只允许 + - * // %，除法请用 //）".format(
+                        type(node.op).__name__
+                    )
+                )
+            LengthExpr._check(node.left)
+            LengthExpr._check(node.right)
+            return
+        raise FrameRuleError("长度表达式含不支持的语法节点 {}".format(type(node).__name__))
+
+    # ------------------------------------------------------------------ 求值
+    def evaluate(self, fields: Dict[str, Any]) -> int:
+        values: Dict[str, int] = {}
+        for token, key, attr in self._refs:
+            fv = fields.get(key)
+            if fv is None:  # pragma: no cover - 编译期已保证只引用前置字段
+                raise FrameInvalid("长度表达式引用了未解析字段 {!r}".format(key))
+            if attr == "val":
+                val = fv.val
+                if isinstance(val, bool) or not isinstance(val, int):
+                    raise FrameInvalid(
+                        "长度表达式引用了字段 {!r} 的 val，但它不是整数".format(key)
+                    )
+                values[token] = int(val)
+            else:
+                values[token] = len(fv.raw)
+        result = _eval_ast(self._tree.body, values)
+        if isinstance(result, bool) or not isinstance(result, int):  # pragma: no cover
+            raise FrameInvalid("长度表达式 {!r} 结果不是整数".format(self.source))
+        return result