nfcscript 0.0.8__tar.gz → 0.0.10__tar.gz

{nfcscript-0.0.8 → nfcscript-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.8
+Version: 0.0.10
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -167,7 +167,7 @@ with session() as reader:
 |------|------|
 | `connect(port, reader_type)` | 连接读卡器 |
 | `get_reader()` | 获取当前读卡器实例 |
-| `active(ll, ignore_error)` | 寻卡，返回 uid/atq/sak |
+| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 uid/atq/sak |
 | `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
 | `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
 | `reqa()` | ISO14443-A REQA |
@@ -253,6 +253,16 @@ NFC_TRACE_DRIVER=true
 NFC_TRACE_PROTOCOL=true
 ```
 
+## AI 编写脚本
+
+本目录下 `SKILL.md` 提供了 DSL 的完整 API 参考和 few-shot 示例，可直接用于 AI Agent 生成 NFC 脚本。
+
+**使用方式**：在 AI 对话中引用该文件，例如：
+```
+@nfcscript/SKILL.md
+```
+Agent 会基于 SKILL.md 中的 API 签名、few-shot 示例和约定生成正确的脚本代码。
+
 ## 开发
 
 ```bash

{nfcscript-0.0.8 → nfcscript-0.0.10}/README.md

@@ -157,7 +157,7 @@ with session() as reader:
 |------|------|
 | `connect(port, reader_type)` | 连接读卡器 |
 | `get_reader()` | 获取当前读卡器实例 |
-| `active(ll, ignore_error)` | 寻卡，返回 uid/atq/sak |
+| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 uid/atq/sak |
 | `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
 | `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
 | `reqa()` | ISO14443-A REQA |
@@ -243,6 +243,16 @@ NFC_TRACE_DRIVER=true
 NFC_TRACE_PROTOCOL=true
 ```
 
+## AI 编写脚本
+
+本目录下 `SKILL.md` 提供了 DSL 的完整 API 参考和 few-shot 示例，可直接用于 AI Agent 生成 NFC 脚本。
+
+**使用方式**：在 AI 对话中引用该文件，例如：
+```
+@nfcscript/SKILL.md
+```
+Agent 会基于 SKILL.md 中的 API 签名、few-shot 示例和约定生成正确的脚本代码。
+
 ## 开发
 
 ```bash

{nfcscript-0.0.8 → nfcscript-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nfcscript"
-version = "0.0.8"
+version = "0.0.10"
 description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -34,7 +34,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.8"
+current_version = "0.0.10"
 commit = true
 tag = true
 allow_dirty = true

{nfcscript-0.0.8 → nfcscript-0.0.10}/src/nfc/assertions.py

@@ -19,6 +19,17 @@ def _get_stack_trace() -> str:
     return "\n".join(chain)
 
 def ASSERT_LEN(data: Any, expected_len: int, msg: str | None = None) -> None:
+    """
+    断言数据长度等于期望值。
+
+    Args:
+        data: 待检查的数据。
+        expected_len: 期望的长度。
+        msg: 失败时的自定义错误消息。
+
+    Raises:
+        AssertionError: 长度不匹配时抛出。
+    """
     actual_len = len(data)
     if actual_len != expected_len:
         error_msg = (
@@ -33,6 +44,17 @@ def ASSERT_LEN(data: Any, expected_len: int, msg: str | None = None) -> None:
         raise AssertionError(error_msg)
 
 def ASSERT_EQUAL(expected: Any, actual: Any, msg: str | None = None) -> None:
+    """
+    断言两个值相等。
+
+    Args:
+        expected: 期望值。
+        actual: 实际值。
+        msg: 失败时的自定义错误消息。
+
+    Raises:
+        AssertionError: 值不相等时抛出。
+    """
     if actual != expected:
         error_msg = (
             f"\nAssertion Failed: {msg}\n" if msg else ""
@@ -45,6 +67,16 @@ def ASSERT_EQUAL(expected: Any, actual: Any, msg: str | None = None) -> None:
         raise AssertionError(error_msg)
 
 def ASSERT_IS_NONE(value: Any, msg: str | None = None) -> None:
+    """
+    断言值为 None。
+
+    Args:
+        value: 待检查的值。
+        msg: 失败时的自定义错误消息。
+
+    Raises:
+        AssertionError: 值不为 None 时抛出。
+    """
     if value is not None:
         error_msg = (
             f"\nAssertion Failed: {msg}\n" if msg else ""
@@ -56,6 +88,19 @@ def ASSERT_IS_NONE(value: Any, msg: str | None = None) -> None:
         raise AssertionError(error_msg)
 
 def ASSERT_IS_NOT_NONE(value: T | None, msg: str | None = None) -> TypeGuard[T]:
+    """
+    断言值不为 None。
+
+    Args:
+        value: 待检查的值。
+        msg: 失败时的自定义错误消息。
+
+    Returns:
+        TypeGuard[T]: 值不为 None 时返回 True。
+
+    Raises:
+        AssertionError: 值为 None 时抛出。
+    """
     if value is None:
         error_msg = (
             f"\nAssertion Failed: {msg}\n" if msg else ""

nfcscript-0.0.10/src/nfc/bits.py

@@ -0,0 +1,42 @@
+from .hex_util import FORMAT_HEX
+
+def BITS_UPDATE(val: int, mask: int, data: int) -> int:
+    """
+    更新寄存器中的特定位域 (Read-Modify-Write)。
+
+    Args:
+        val: 当前寄存器的原始值。
+        mask: 预移位的位掩码 (例如: 0x20)。
+        data: 已移位对齐的新数值 (例如: 0x20, 即 1 << 5)。
+
+    Returns:
+        int: 更新后的寄存器值。
+    """
+    assert (data & ~mask) == 0, f"Data {FORMAT_HEX(data)} contains bits outside mask {FORMAT_HEX(mask)}"
+    return (val & ~mask) | (data & mask)
+
+def BITS_SET(val: int, mask: int) -> int:
+    """
+    将寄存器中的指定位强制置 1 (OR 操作)。
+
+    Args:
+        val: 当前寄存器的原始值。
+        mask: 想要置 1 的位掩码。
+
+    Returns:
+        int: 置位后的寄存器值。
+    """
+    return val | mask
+
+def BITS_RESET(val: int, mask: int) -> int:
+    """
+    将寄存器中的指定位强制清 0 (AND-NOT 操作)。
+
+    Args:
+        val: 当前寄存器的原始值。
+        mask: 想要清 0 的位掩码。
+
+    Returns:
+        int: 清位后的寄存器值。
+    """
+    return val & ~mask

{nfcscript-0.0.8 → nfcscript-0.0.10}/src/nfc/checksum.py

@@ -3,8 +3,16 @@ from .hex_util import FORMAT_HEX
 
 def GET_BCC(data: list[int]) -> int:
     """
-    计算 BCC: data[0]^data[1]^data[2]^data[3]
-    :param data: 4字节的UID数据
+    计算 BCC: data[0]^data[1]^data[2]^data[3]。
+
+    Args:
+        data: 4 字节的 UID 数据。
+
+    Returns:
+        int: 异或校验值。
+
+    Raises:
+        AssertionError: 输入数据长度不为 4 时抛出。
     """
     ASSERT_LEN(data, 4, msg=f"计算BCC时输入数据长度应为4: {FORMAT_HEX(data)}")
     return data[0] ^ data[1] ^ data[2] ^ data[3]

nfcscript-0.0.10/src/nfc/delay.py

@@ -0,0 +1,9 @@
+import time
+
+def DELAY_MS(ms: int) -> None:
+    """毫秒级延时。
+
+    Args:
+        ms: 延时毫秒数。
+    """
+    time.sleep(ms / 1000.0)

{nfcscript-0.0.8 → nfcscript-0.0.10}/src/nfc/hex_util.py

@@ -5,25 +5,43 @@ BIT_PATTERN = re.compile(r"(\d+)\s*\'h\s*([0-9a-fA-F]+)")
 
 def PARSE_HEX(text: str) -> tuple[str, int]:
     """
-    解析文本 -> (纯十六进制字符串, 最后字节有效位数)
-    支持: "AA BB 7'h03" -> ("AABB03", 7)
+    解析带位标记的 hex 字符串。
+
+    Args:
+        text: 十六进制文本。
+
+    Returns:
+        tuple[str, int]: (纯十六进制字符串, 最后字节有效位数)。
+
+    Raises:
+        ValueError: 不合法的十六进制数据时抛出。
+
+    Examples:
+        >>> PARSE_HEX("AA BB 7'h03")
+        ('AABB03', 7)
+        >>> PARSE_HEX("FF 4'h0C")
+        ('FF0C', 4)
+        >>> PARSE_HEX("AABBCC")
+        ('AABBCC', 0)
     """
     last_bits = 0
     cleaned = text.strip()
 
-    # 查找所有位标记
+    # 查找所有位标记，从右往左替换避免偏移
     matches = list(BIT_PATTERN.finditer(cleaned))
     if matches:
         last_match = matches[-1]
         last_bits = int(last_match.group(1))
-        hex_val = last_match.group(2)
-        
-        # 替换位标记为纯 hex
-        cleaned = cleaned[:last_match.start()] + hex_val + cleaned[last_match.end():]
+
+        for m in reversed(matches):
+            hex_val = m.group(2)
+            if len(hex_val) % 2 != 0:
+                hex_val = "0" + hex_val
+            cleaned = cleaned[:m.start()] + hex_val + cleaned[m.end():]
 
     # 去空格得到纯 hex
     clean_hex = cleaned.replace(" ", "")
-    
+
     # 简单的合法性检查
     if clean_hex:
         try:
@@ -35,17 +53,31 @@ def PARSE_HEX(text: str) -> tuple[str, int]:
 
 def FORMAT_HEX(data: int | bytes | list[int] | str, last_bits: int = 0) -> str:
     """
-    格式化数据为带位标记的可视化格式
-    支持输入类型: int, bytes, list[int], str (纯 hex)
-    示例:
-        FORMAT_HEX(0xAABB03, 7)        -> "AA BB 7'h03"
-        FORMAT_HEX("AABB03", 7)        -> "AA BB 7'h03"
-        FORMAT_HEX(b'\xaa\xbb\x03', 7) -> "AA BB 7'h03"
-        FORMAT_HEX([0xAA, 0xBB, 0x03], 7) -> "AA BB 7'h03"
+    格式化数据为带位标记的可视化格式。
+
+    支持输入类型: int, bytes, list[int], str (纯 hex)。
+
+    Args:
+        data: 待格式化的数据。
+        last_bits: 最后一个字节的有效位数 (1-7)，0 表示整字节。
+
+    Returns:
+        str: 格式化后的字符串。
+
+    Raises:
+        TypeError: 不支持的输入类型时抛出。
+
+    Examples:
+        >>> FORMAT_HEX(0xAABB03, 7)
+        "AA BB 7'h03"
+        >>> FORMAT_HEX([0xAA, 0xBB, 0x03])
+        'AA BB 03'
+        >>> FORMAT_HEX("AABB", 4)
+        "AA 4'hBB"
     """
     # 1. 统一转换为纯十六进制字符串
     if isinstance(data, int):
-        hex_str = hex(data)[2:].upper()
+        hex_str = data.to_bytes(max(1, (data.bit_length() + 7) // 8)).hex().upper()
     elif isinstance(data, bytes):
         hex_str = data.hex().upper()
     elif isinstance(data, list):

{nfcscript-0.0.8 → nfcscript-0.0.10}/src/nfc/nfc_cli.py

@@ -8,6 +8,25 @@ from nfc import *
 from nfctester.registry import CardRegistry
 
 
+def cli_collect(**lengths):
+    """
+    标记方法参数为 list 收集模式。
+
+    用法:
+        @cli_collect(key=6, uid=4)  # key 固定 6，uid 固定 4，剩余自动收集
+        @cli_collect(data=6)       # data 固定 6
+        @cli_collect()             # 回退到最后一个参数收集剩余
+
+    CLI 调用示例:
+        mf_auth 4 0 01 02 03 04 05 06 07 08 09 10
+        # → block=4, key_type=0, key=[1..6], uid=[7..10]
+    """
+    def decorator(func):
+        func._cli_collect = lengths
+        return func
+    return decorator
+
+
 def _load_external_cards(paths):
     """加载外部卡片模块，触发 @CardRegistry.register() 注册"""
     for path in paths:
@@ -82,36 +101,43 @@ def _call_method(method, args_str):
     params = list(sig.parameters.keys())
 
     if not args_str:
-        # 无参数调用
         return method()
 
-    # 解析参数
-    raw_args = args_str.split()
-    parsed = []
-    for i, raw in enumerate(raw_args):
-        parsed.append(_parse_value(raw))
+    parsed = [_parse_value(raw) for raw in args_str.split()]
 
     # 跳过 self
     if params and params[0] == "self":
         params = params[1:]
 
-    # 处理 bytes 参数：将多个连续值合并为 bytes
-    final_args = []
-    i = 0
-    while i < len(parsed):
-        if i < len(params):
-            param = sig.parameters[params[i] if params[0] != "self" else params[i]]
-            annotation = param.annotation
-            if annotation is bytes or (isinstance(annotation, type) and issubclass(annotation, bytes)):
-                # 收集剩余参数作为 bytes
-                remaining = [x for x in parsed[i:] if isinstance(x, (int, bytes))]
-                if remaining and all(isinstance(x, int) for x in remaining):
-                    final_args.append(bytes(remaining))
-                elif remaining:
-                    final_args.append(b"".join(x if isinstance(x, bytes) else bytes([x]) for x in remaining))
-                break
-        final_args.append(parsed[i])
-        i += 1
+    cli_collect_meta = getattr(method, '_cli_collect', None)
+
+    if cli_collect_meta:
+        # 装饰器模式：标记的按长度取，未标记的取单个值
+        # 无长度标记 (None) 的 list 参数收集剩余
+        final_args = []
+        i = 0
+        for param_name in params:
+            if param_name in cli_collect_meta:
+                length = cli_collect_meta[param_name]
+                if length is not None:
+                    final_args.append(parsed[i:i + length])
+                    i += length
+                else:
+                    # 不定长，收集剩余
+                    final_args.append(parsed[i:])
+                    break
+            else:
+                final_args.append(parsed[i])
+                i += 1
+    else:
+        # 回退模式：最后一个参数收集多余值为 list
+        if len(parsed) <= len(params):
+            # 参数刚好或不够，直接传
+            final_args = parsed
+        else:
+            # 有剩余，最后一个参数收集多余值
+            final_args = parsed[:len(params) - 1]
+            final_args.append(parsed[len(params) - 1:])
 
     return method(*final_args)
 
@@ -179,7 +205,7 @@ def main():
 
                 result = _call_method(methods[cmd_name], args_str)
                 if result is not None:
-                    if isinstance(result, bytes):
+                    if isinstance(result, list):
                         print(f"→ {FORMAT_HEX(result)}")
                     elif isinstance(result, bool):
                         print(f"→ {'OK' if result else 'FAIL'}")

{nfcscript-0.0.8 → nfcscript-0.0.10}/src/nfc/reader.py

@@ -1,6 +1,6 @@
 import os
 from contextlib import contextmanager
-from nfctester.drivers.card_reader import CardInfo, TransceiveResult
+from nfctester.drivers.card_reader import CardInfo, TransceiveBits
 from nfctester.registry import CardReaderRegistry
 from .assertions import ASSERT_EQUAL, ASSERT_IS_NOT_NONE, ASSERT_LEN
 from .checksum import GET_BCC
@@ -76,28 +76,27 @@ def get_reader():
     return _state.reader
 
 
-def active(ll: bool = False, ignore_error: bool = False, reqa_cmd: int = 0x26) -> CardInfo | None:
+def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int = 0x26) -> CardInfo | None:
     """
     寻卡操作，检测并激活目标卡片。
 
     Args:
-        ll: 如果为 True，则执行底层抗冲突流程以兼容非标卡；
-            如果为 False，则使用读卡器原生 active()。
+        low_layer: 如果为 True，由 nfcscript 执行底层抗冲突流程以兼容非标卡；
+            如果为 False，则使用读卡器驱动层原生 active()。
         ignore_error: 如果为 True，当 BCC 或 SAK 校验失败时，记录警告而不停止执行。
-        reqa_cmd: 底层寻卡时使用的 REQA 命令字节，默认 0x26。
-                  仅在 ll=True 时生效。
+        reqa_cmd: 底层寻卡时使用的 REQA 命令字节，默认 0x26。仅 low_layer=True 时生效。
 
     Returns:
         CardInfo: 包含卡片信息的数据类，失败时返回 None。
               属性说明:
-              - 'uid' (bytes): 卡片的 UID。
-              - 'atq' (bytes): 卡片的 ATQ (Answer To Request)。
+              - 'uid' (list[int]): 卡片的 UID。
+              - 'atq' (list[int]): 卡片的 ATQ (Answer To Request)。
               - 'sak' (int):   卡片的 SAK (Select Acknowledge)。
     """
     _state.ensure_connected()
     reader = _state.reader
 
-    if not ll:
+    if not low_layer:
         return reader.active()
 
     # 手动底层寻卡流程
@@ -129,7 +128,7 @@ def active(ll: bool = False, ignore_error: bool = False, reqa_cmd: int = 0x26) -
 
         print(f"cl{cl}.uid: {FORMAT_HEX(data)}")
         has_next = (data[0] == 0x88)
-        uid_to_select = list(data[0:5])
+        uid_to_select = data[0:5]
         sak_res = select(cl_level=cl, uid=uid_to_select)
 
         # SAK 校验
@@ -147,7 +146,7 @@ def active(ll: bool = False, ignore_error: bool = False, reqa_cmd: int = 0x26) -
             sak = sak_res[0] if sak_res else 0
             break
 
-    return CardInfo(uid=bytes(full_uid), atq=bytes(atq), sak=sak)
+    return CardInfo(uid=full_uid, atq=atq, sak=sak)
 
 
 def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> list[int]:
@@ -156,95 +155,137 @@ def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> lis
 
     Args:
         data: 要发送的字节列表。
-        tx_crc: 发送时是否自动添加 CRC。
-        rx_crc: 接收时是否自动校验 CRC。
+        tx_crc: 发送时是否自动添加 CRC。False 则原样发送。
+        rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
 
     Returns:
         list[int]: 接收到的数据字节列表。
     """
     _state.ensure_connected()
     reader = _state.reader
-    res = reader.transceive(bytes(data), tx_crc=tx_crc, rx_crc=rx_crc)
-    return list(res.data) if res and res.data else []
+    res = reader.transceive(data, tx_crc=tx_crc, rx_crc=rx_crc)
+    return res.data if res and res.data else []
 
 
-def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveResult | None:
+def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveBits | None:
     """
     使用底层帧交互方式发送数据，并支持对最后一个字节进行位控制。
 
     Args:
         data: 要发送的字节列表。
-        last_tx_bits: 最后一个字节实际发送的有效位数 (1-7)，
-                      0 表示发送完整字节。
-        tx_crc: 发送时是否自动添加 CRC。
-        rx_crc: 接收时是否自动校验 CRC。
+        last_tx_bits: 最后一个字节实际发送的有效位数 (1-7)，0 表示发送完整字节。
+        tx_crc: 发送时是否自动添加 CRC。False 则原样发送。
+        rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
 
     Returns:
-        TransceiveResult | None: 包含 data 和 rx_bits 属性，失败返回 None。
+        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
     """
     _state.ensure_connected()
     reader = _state.reader
-    return reader.transceive_bits(bytes(data), last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    return reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
 
 
-def reqa(cmd: int = 0x26) -> TransceiveResult | None:
-    """ISO14443-A REQA (7 bits)"""
-    # REQA: 0x26，短帧，仅发送 7 bits，响应无 CRC
+def reqa(cmd: int = 0x26) -> TransceiveBits | None:
+    """
+    ISO14443-A REQA (7 bits)。
+
+    Args:
+        cmd: REQA 命令字节，默认 0x26。
+
+    Returns:
+        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+    """
     return transceive_bits([cmd], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
-def wupa() -> TransceiveResult | None:
-    """ISO14443-A WUPA (7 bits)"""
-    # WUPA: 0x52，短帧，仅发送 7 bits，响应无 CRC
+def wupa() -> TransceiveBits | None:
+    """
+    ISO14443-A WUPA (7 bits)。
+
+    Returns:
+        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+    """
     return transceive_bits([0x52], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
 def halt() -> list[int] | None:
-    """ISO14443-A HALT (Standard Frame)"""
-    # HALT: 0x50 0x00 + CRC
+    """
+    ISO14443-A HALT (Standard Frame)。
+
+    Returns:
+        list[int] | None: 返回响应数据，失败返回 None。
+    """
     return transceive([0x50, 0x00], tx_crc=True, rx_crc=True)
 
 
 def _get_sel_cmd(cl_level: int) -> int:
-    """根据 CL 级别获取 ISO14443-A SEL 命令字节"""
+    """
+    根据 CL 级别获取 ISO14443-A SEL 命令字节。
+
+    Args:
+        cl_level: CL 级别，1/2/3。
+
+    Returns:
+        int: 对应的 SEL 命令字节 (0x93/0x95/0x97)。
+
+    Raises:
+        ValueError: CL 级别不在 1/2/3 范围内。
+    """
     sel_map = {1: 0x93, 2: 0x95, 3: 0x97}
     if cl_level not in sel_map:
         raise ValueError(f"Invalid CL level: {cl_level}, must be 1, 2, or 3")
     return sel_map[cl_level]
 
 
-def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveResult | None:
+def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveBits | None:
     """
-    ISO14443-A ANTICOLL (Anti-collision)
-    :param cl_level: 1 (0x93), 2 (0x95), or 3 (0x97)
-    :param nvb: Number of Valid Bits，定义了包含 SEL 和 NVB 在内的有效位数
-    :param uid_prefix: 已知的部分 UID (0-4 字节)
-    :return: TransceiveResult 包含 data 和 rx_bits 属性
+    ISO14443-A ANTICOLL (Anti-collision)。
+
+    Args:
+        cl_level: CL 级别，1 (0x93), 2 (0x95), 或 3 (0x97)。
+        nvb: Number of Valid Bits，定义了包含 SEL 和 NVB 在内的有效位数。
+        uid_prefix: 已知的部分 UID (0-4 字节)。
+
+    Returns:
+        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
     """
     cmd = [_get_sel_cmd(cl_level), nvb] + uid_prefix
-    # 抗冲突响应无 CRC
     return transceive_bits(cmd, last_tx_bits=0, tx_crc=False, rx_crc=False)
 
 
 def select(cl_level: int, uid: list[int]) -> list[int] | None:
     """
-    ISO14443-A SELECT (Standard Frame)
-    :param cl_level: 1 (0x93), 2 (0x95), or 3 (0x97)
-    :param uid: 完整 5 字节 UID (包含 BCC)
+    ISO14443-A SELECT (Standard Frame)。
+
+    Args:
+        cl_level: CL 级别，1 (0x93), 2 (0x95), 或 3 (0x97)。
+        uid: 完整 5 字节 UID (包含 BCC)。
+
+    Returns:
+        list[int] | None: 返回响应数据，失败返回 None。
     """
     cmd = [_get_sel_cmd(cl_level), 0x70] + uid
-    # 选择帧需带 CRC
     return transceive(cmd, tx_crc=True, rx_crc=True)
 
 
 def field_on():
-    """开启 PN532 的 RF 场。"""
+    """
+    开启 PN532 的 RF 场。
+
+    Raises:
+        AssertionError: 未连接读卡器时抛出。
+    """
     _state.ensure_connected()
     _state.reader.rf_field = True
 
 
 def field_off():
-    """关闭 PN532 的 RF 场。"""
+    """
+    关闭 PN532 的 RF 场。
+
+    Raises:
+        AssertionError: 未连接读卡器时抛出。
+    """
     _state.ensure_connected()
     _state.reader.rf_field = False