nfcscript 0.0.16__tar.gz → 0.0.17__tar.gz

{nfcscript-0.0.16 → nfcscript-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.16
+Version: 0.0.17
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14

{nfcscript-0.0.16 → nfcscript-0.0.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nfcscript"
-version = "0.0.16"
+version = "0.0.17"
 description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -24,9 +24,6 @@ testpaths = ["tests"]
 [tool.uv]
 package = true
 
-[tool.uv.sources]
-nfctester = { workspace = true }
-
 [dependency-groups]
 dev = [
     "pytest",
@@ -34,7 +31,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.16"
+current_version = "0.0.17"
 commit = true
 tag = true
 allow_dirty = true

{nfcscript-0.0.16 → nfcscript-0.0.17}/src/nfc/nfc_cli.py

@@ -172,13 +172,13 @@ def main():
         parser.error("需要指定卡片类型 (-c/--card) 或使用 --list-cards 查看可用类型")
 
     try:
-        connect(port=args.port, reader_type=args.reader)
+        reader.connect(port=args.port, reader_type=args.reader)
     except Exception as e:
         print(f"连接读卡器失败: {e}")
         sys.exit(1)
 
     try:
-        card = CardRegistry.create(args.card, reader=get_reader())
+        card = CardRegistry.create(args.card, reader=reader.target)
         methods = _get_methods(card)
 
         print(f"已连接卡片: {args.card}")
@@ -220,7 +220,7 @@ def main():
                 print(f"错误: {e}")
 
     finally:
-        close()
+        reader.close()
         print("已断开连接")
 
 

{nfcscript-0.0.16 → nfcscript-0.0.17}/src/nfc/reader.py

@@ -1,5 +1,10 @@
+import atexit
 import os
+import sys
 from contextlib import contextmanager
+from typing import Any
+
+from dotenv import load_dotenv
 from nfctester.drivers.card_reader import CardInfo, TransceiveBits
 from nfctester.registry import CardReaderRegistry
 from nfctester.trace import trace as _trace
@@ -7,44 +12,104 @@ from .assertions import ASSERT_EQUAL, ASSERT_IS_NOT_NONE, ASSERT_LEN
 from .checksum import GET_BCC
 from .hex_util import FORMAT_HEX
 
+_DOTENV_LOADED = False
+
+
+def _find_dotenv_all(start_dir: str) -> list[str]:
+    """从起始目录逐级向上搜索所有 .env 文件"""
+    chain = []
+    path = start_dir
+    while True:
+        env_path = os.path.join(path, ".env")
+        if os.path.exists(env_path):
+            chain.append(env_path)
+        parent = os.path.dirname(path)
+        if parent == path:
+            break
+        path = parent
+    chain.reverse()
+    return chain
+
+
+def _load_env_configs() -> None:
+    """按需加载当前目录及上级目录的 .env 文件"""
+    global _DOTENV_LOADED
+    if not _DOTENV_LOADED:
+        try:
+            cwd = os.getcwd()
+            for env_path in _find_dotenv_all(cwd):
+                load_dotenv(env_path, override=False)
+        except Exception:
+            pass
+        _DOTENV_LOADED = True
+
+
+# ─── 轻量读卡器门面单例 ───────────────────────────────────────────────────
 
-class _NFCState:
-    """单例状态管理，封装读卡器生命周期"""
+class _ReaderFacade:
+    """
+    读卡器单例门面对象 (`reader`)。
+    
+    统一维护读卡器连接状态，提供 `reader.rf = True / False` 属性控制，
+    并将所有属性与方法调用优先路由到当前模块顶层函数，或透传到底层 CardReader 实例。
+    """
+
+    def __init__(self) -> None:
+        self._target: Any = None
+        self._connected: bool = False
+
+    @property
+    def rf(self) -> bool:
+        """获取射频场状态。"""
+        return getattr(get_reader(), "rf_field", False)
+
+    @rf.setter
+    def rf(self, value: bool) -> None:
+        """设置射频场开关 (True / False)。"""
+        get_reader().rf_field = bool(value)
 
-    _instance = None
+    @property
+    def rf_field(self) -> bool:
+        """获取射频场状态 (rf 别名)。"""
+        return self.rf
 
-    def __new__(cls):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-            cls._instance._reader = None
-            cls._instance._connected = False
-        return cls._instance
+    @rf_field.setter
+    def rf_field(self, value: bool) -> None:
+        """设置射频场开关 (rf 别名)。"""
+        self.rf = value
 
     @property
-    def reader(self):
-        return self._reader
+    def mf_crypto(self) -> bool:
+        """获取 Mifare 硬件加密状态。"""
+        return getattr(get_reader(), "mf_crypto", False)
 
-    def connect(self, port: str = "COM20", reader_type: str = "pn532"):
-        self._reader = CardReaderRegistry.create(reader_type, transport="serial", port=port)
-        self._reader.open()
-        self._connected = True
-        _trace.log(f"Connected to {reader_type.upper()} on port {port}", layer="app")
+    @property
+    def target(self) -> Any:
+        """获取当前连接的底层 CardReader 实例。"""
+        return get_reader()
 
-    def disconnect(self):
-        if self._connected and self._reader:
-            self._reader.close()
-            self._connected = False
-            self._reader = None
-            _trace.log("Disconnected", layer="app")
+    def __getattr__(self, name: str) -> Any:
+        # 1. 优先路由到当前模块的顶层函数（如 reader.active -> active）
+        mod = sys.modules[__name__]
+        if hasattr(mod, name) and not name.startswith("_"):
+            return getattr(mod, name)
+        # 2. 其次透传给底层 CardReader 驱动实例（如 reader.mf_auth -> _target.mf_auth）
+        return getattr(self.target, name)
 
-    def ensure_connected(self):
-        ASSERT_IS_NOT_NONE(self._reader, msg="NFC driver not connected. Call connect() first.")
+    def __enter__(self):
+        get_reader()
+        return self
 
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
 
-_state = _NFCState()
 
+reader = _ReaderFacade()
 
-def connect(port: str = None, reader_type: str = None):
+
+# ─── 模块级顶层函数（单一事实来源） ──────────────────────────────────────────
+
+def connect(port: str = None, reader_type: str = None) -> None:
     """
     连接并初始化读卡器。
 
@@ -55,6 +120,7 @@ def connect(port: str = None, reader_type: str = None):
     Raises:
         ValueError: 未提供 port 或 reader_type 且环境变量未设置。
     """
+    _load_env_configs()
     if port is None:
         port = os.environ.get("NFC_PORT")
     if reader_type is None:
@@ -63,18 +129,53 @@ def connect(port: str = None, reader_type: str = None):
         raise ValueError("未指定串口，请通过 -p 参数、connect(port=...) 或 NFC_PORT 环境变量配置")
     if reader_type is None:
         raise ValueError("未指定读卡器类型，请通过 -r 参数、connect(reader_type=...) 或 NFC_READER 环境变量配置")
-    _state.connect(port, reader_type)
+
+    if reader._connected and reader._target is not None:
+        disconnect()
+
+    reader._target = CardReaderRegistry.create(reader_type, transport="serial", port=port)
+    reader._target.open()
+    reader._connected = True
+    _trace.log(f"Connected to {reader_type.upper()} on port {port}", layer="app")
+
+
+def disconnect() -> None:
+    """断开与读卡器的连接并释放资源。"""
+    if reader._connected and reader._target is not None:
+        try:
+            reader._target.rf_field = False
+        except Exception:
+            pass
+        try:
+            reader._target.close()
+        except Exception:
+            pass
+        reader._connected = False
+        reader._target = None
+        _trace.log("Disconnected", layer="app")
+
+
+def close() -> None:
+    """断开与读卡器的连接 (disconnect 别名)。"""
+    disconnect()
 
 
-def get_reader():
+def get_reader() -> Any:
     """
-    获取当前连接的读卡器实例，供 Card 类使用。
+    获取当前连接的读卡器实例，若未连接则尝试从环境变量自动连接。
 
     Returns:
         reader: 当前连接的读卡器实例。
     """
-    _state.ensure_connected()
-    return _state.reader
+    if not reader._connected or reader._target is None:
+        _load_env_configs()
+        port = os.environ.get("NFC_PORT")
+        reader_type = os.environ.get("NFC_READER")
+        if port and reader_type:
+            connect(port, reader_type)
+        else:
+            ASSERT_IS_NOT_NONE(reader._target, msg="NFC driver not connected. Call connect() first.")
+    return reader._target
 
 
 def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int = 0x26) -> CardInfo | None:
@@ -94,11 +195,10 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
               - 'atq' (list[int]): 卡片的 ATQ (Answer To Request)。
               - 'sak' (int):   卡片的 SAK (Select Acknowledge)。
     """
-    _state.ensure_connected()
-    reader = _state.reader
+    rdr = get_reader()
 
     if not low_layer:
-        return reader.active()
+        return rdr.active()
 
     # 手动底层寻卡流程
     # 1. REQA
@@ -109,6 +209,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
 
     # 2. 抗冲突与选择
     full_uid = []
+    sak = 0
     for cl in [1, 2, 3]:
         res = anticoll(cl_level=cl, nvb=0x20)
         if not res.data:
@@ -153,30 +254,35 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
     return info
 
 
-def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> list[int]:
+def transceive(data: list[int] | bytes, tx_crc: bool = True, rx_crc: bool = True) -> list[int]:
     """
     使用底层帧交互方式发送数据。
 
     Args:
-        data: 要发送的字节列表。
+        data: 要发送的字节列表或 bytes。
         tx_crc: 发送时是否自动添加 CRC。False 则原样发送。
         rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
 
     Returns:
         list[int]: 接收到的数据字节列表。
     """
-    _state.ensure_connected()
-    reader = _state.reader
-    res = reader.transceive(data, tx_crc=tx_crc, rx_crc=rx_crc)
+    rdr = get_reader()
+    raw_list = list(data) if isinstance(data, (bytes, bytearray)) else data
+    res = rdr.transceive(raw_list, 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) -> TransceiveBits:
+def transceive_bits(
+    data: list[int] | bytes,
+    last_tx_bits: int = 0,
+    tx_crc: bool = True,
+    rx_crc: bool = True,
+) -> TransceiveBits:
     """
     使用底层帧交互方式发送数据，并支持对最后一个字节进行位控制。
 
     Args:
-        data: 要发送的字节列表。
+        data: 要发送的字节列表或 bytes。
         last_tx_bits: 最后一个字节实际发送的有效位数 (1-7)，0 表示发送完整字节。
         tx_crc: 发送时是否自动添加 CRC。False 则原样发送。
         rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
@@ -184,9 +290,9 @@ def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True,
     Returns:
         TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
-    _state.ensure_connected()
-    reader = _state.reader
-    res = reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    rdr = get_reader()
+    raw_list = list(data) if isinstance(data, (bytes, bytearray)) else data
+    res = rdr.transceive(raw_list, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
     return res if res else TransceiveBits(data=[], bits=0)
 
 
@@ -273,33 +379,24 @@ def select(cl_level: int, uid: list[int]) -> list[int]:
     return transceive(cmd, tx_crc=True, rx_crc=True)
 
 
-def field_on():
+def field_on() -> None:
     """
-    开启 PN532 的 RF 场。
+    开启读卡器的 RF 场。
 
     Raises:
         AssertionError: 未连接读卡器时抛出。
     """
-    _state.ensure_connected()
-    _state.reader.rf_field = True
+    get_reader().rf_field = True
 
 
-def field_off():
+def field_off() -> None:
     """
-    关闭 PN532 的 RF 场。
+    关闭读卡器的 RF 场。
 
     Raises:
         AssertionError: 未连接读卡器时抛出。
     """
-    _state.ensure_connected()
-    _state.reader.rf_field = False
-
-
-def close():
-    """
-    断开与 PN532 读卡器的连接。
-    """
-    _state.disconnect()
+    get_reader().rf_field = False
 
 
 @contextmanager
@@ -308,8 +405,8 @@ def session(port: str = None, reader_type: str = None):
     上下文管理器，自动管理连接生命周期。
 
     用法:
-        with session("COM20") as reader:
-            card_info = reader.active()
+        with session("COM20") as r:
+            card_info = r.active()
     """
     if port is None:
         port = os.environ.get("NFC_PORT")
@@ -319,8 +416,44 @@ def session(port: str = None, reader_type: str = None):
         raise ValueError("未指定串口，请通过 session(port=...) 或 NFC_PORT 环境变量配置")
     if reader_type is None:
         raise ValueError("未指定读卡器类型，请通过 session(reader_type=...) 或 NFC_READER 环境变量配置")
-    _state.connect(port, reader_type)
+    connect(port, reader_type)
     try:
-        yield _state.reader
+        yield reader
     finally:
-        _state.disconnect()
+        disconnect()
+
+
+def _atexit_cleanup() -> None:
+    """进程退出时的 atexit 安全清理钩子：先关闭物理 RF 场，再关闭串口。"""
+    if reader._connected and reader._target is not None:
+        try:
+            reader._target.rf_field = False
+        except Exception:
+            pass
+        try:
+            reader._target.close()
+        except Exception:
+            pass
+
+
+atexit.register(_atexit_cleanup)
+
+
+__all__ = [
+    "reader",
+    "connect",
+    "disconnect",
+    "get_reader",
+    "active",
+    "transceive",
+    "transceive_bits",
+    "reqa",
+    "wupa",
+    "halt",
+    "anticoll",
+    "select",
+    "field_on",
+    "field_off",
+    "close",
+    "session",
+]

{nfcscript-0.0.16 → nfcscript-0.0.17}/src/nfcscript.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.16
+Version: 0.0.17
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14

{nfcscript-0.0.16 → nfcscript-0.0.17}/tests/test_reader.py

@@ -1,60 +1,70 @@
 """reader 模块测试 (connect / get_reader / active / transceive / session 等)"""
+import os
+import sys
 import pytest
-from unittest.mock import MagicMock, patch, PropertyMock
+from unittest.mock import MagicMock, patch
+import nfc
 from nfc import reader
 from nfctester.drivers.card_reader import CardInfo, TransceiveBits
+from nfctester.registry import CardReaderRegistry
 
 
 @pytest.fixture(autouse=True)
 def reset_state():
     """每个测试前重置全局状态"""
-    reader._state._reader = None
-    reader._state._connected = False
+    reader._target = None
+    reader._connected = False
     yield
-    reader._state._reader = None
-    reader._state._connected = False
+    reader._target = None
+    reader._connected = False
 
 
 def _mock_reader():
     mock = MagicMock()
     mock.transceive.return_value = TransceiveBits(data=[0xAA, 0xBB], bits=8)
     mock.active.return_value = CardInfo(uid=[0x01, 0x02, 0x03, 0x04], atq=[0x44, 0x00], sak=0x00)
+    mock.rf_field = False
+    mock.mf_crypto = False
     return mock
 
 
 class TestConnect:
 
-    @patch.object(reader.CardReaderRegistry, "create")
+    @patch.object(CardReaderRegistry, "create")
     def test_connect_with_params(self, mock_create):
-        mock_reader = _mock_reader()
-        mock_create.return_value = mock_reader
-        reader.connect(port="COM99", reader_type="pn532")
+        mock_rdr = _mock_reader()
+        mock_create.return_value = mock_rdr
+        nfc.connect(port="COM99", reader_type="pn532")
         mock_create.assert_called_once_with("pn532", transport="serial", port="COM99")
-        mock_reader.open.assert_called_once()
-        assert reader._state._connected is True
+        mock_rdr.open.assert_called_once()
+        assert reader._connected is True
 
-    @patch.object(reader.CardReaderRegistry, "create")
+    @patch.object(CardReaderRegistry, "create")
     def test_connect_from_env(self, mock_create, monkeypatch):
         monkeypatch.setenv("NFC_PORT", "COM10")
         monkeypatch.setenv("NFC_READER", "pn532")
         mock_create.return_value = _mock_reader()
-        reader.connect()
+        nfc.connect()
         mock_create.assert_called_once_with("pn532", transport="serial", port="COM10")
 
-    def test_connect_no_port_raises(self):
+    def test_connect_no_port_raises(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(ValueError, match="未指定串口"):
-            reader.connect(reader_type="pn532")
+            nfc.connect(reader_type="pn532")
 
-    def test_connect_no_reader_type_raises(self):
+    def test_connect_no_reader_type_raises(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(ValueError, match="未指定读卡器类型"):
-            reader.connect(port="COM99")
+            nfc.connect(port="COM99")
 
-    @patch.object(reader.CardReaderRegistry, "create")
+    @patch.object(CardReaderRegistry, "create")
     def test_connect_overrides_env(self, mock_create, monkeypatch):
         monkeypatch.setenv("NFC_PORT", "COM10")
         monkeypatch.setenv("NFC_READER", "clrc663")
         mock_create.return_value = _mock_reader()
-        reader.connect(port="COM99", reader_type="pn532")
+        nfc.connect(port="COM99", reader_type="pn532")
         mock_create.assert_called_once_with("pn532", transport="serial", port="COM99")
 
 
@@ -62,123 +72,128 @@ class TestGetReader:
 
     def test_get_reader_when_connected(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        assert reader.get_reader() is mock
-
-    def test_get_reader_when_not_connected(self):
+        reader._target = mock
+        reader._connected = True
+        assert nfc.get_reader() is mock
+        assert reader.target is mock
+
+    def test_get_reader_when_not_connected(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(AssertionError):
-            reader.get_reader()
+            nfc.get_reader()
 
 
 class TestTransceive:
 
     def test_transceive_returns_data(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        result = reader.transceive([0x30, 0x00])
+        reader._target = mock
+        reader._connected = True
+        result = nfc.transceive([0x30, 0x00])
         assert result == [0xAA, 0xBB]
         mock.transceive.assert_called_once_with([0x30, 0x00], tx_crc=True, rx_crc=True)
 
     def test_transceive_no_crc(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        reader.transceive([0x30], tx_crc=False, rx_crc=False)
+        reader._target = mock
+        reader._connected = True
+        nfc.transceive([0x30], tx_crc=False, rx_crc=False)
         mock.transceive.assert_called_once_with([0x30], tx_crc=False, rx_crc=False)
 
     def test_transceive_empty_result(self):
         mock = _mock_reader()
         mock.transceive.return_value = None
-        reader._state._reader = mock
-        reader._state._connected = True
-        result = reader.transceive([0x30])
+        reader._target = mock
+        reader._connected = True
+        result = nfc.transceive([0x30])
         assert result == []
 
-    def test_transceive_not_connected(self):
+    def test_transceive_not_connected(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(AssertionError):
-            reader.transceive([0x30])
+            nfc.transceive([0x30])
 
 
 class TestTransceiveBits:
 
     def test_transceive_bits_returns_result(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        result = reader.transceive_bits([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
+        reader._target = mock
+        reader._connected = True
+        result = nfc.transceive_bits([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
         assert result is not None
         assert result.data == [0xAA, 0xBB]
 
     def test_transceive_bits_passes_params(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        reader.transceive_bits([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
+        reader._target = mock
+        reader._connected = True
+        nfc.transceive_bits([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
         mock.transceive.assert_called_once_with([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
 class TestReqa:
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_reqa_default(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x44, 0x00], bits=8)
-        result = reader.reqa()
+        result = nfc.reqa()
         mock_tb.assert_called_once_with([0x26], last_tx_bits=7, tx_crc=False, rx_crc=False)
         assert result is not None
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_reqa_custom_cmd(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x44, 0x00], bits=8)
-        reader.reqa(cmd=0x20)
+        nfc.reqa(cmd=0x20)
         mock_tb.assert_called_once_with([0x20], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
 class TestWupa:
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_wupa(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x44, 0x00], bits=8)
-        result = reader.wupa()
+        result = nfc.wupa()
         mock_tb.assert_called_once_with([0x52], last_tx_bits=7, tx_crc=False, rx_crc=False)
         assert result is not None
 
 
 class TestHalt:
 
-    @patch.object(reader, "transceive")
+    @patch("nfc.reader.transceive")
     def test_halt(self, mock_ts):
         mock_ts.return_value = []
-        result = reader.halt()
+        result = nfc.halt()
         mock_ts.assert_called_once_with([0x50, 0x00], tx_crc=True, rx_crc=True)
 
 
 class TestSelect:
 
-    @patch.object(reader, "transceive")
+    @patch("nfc.reader.transceive")
     def test_select_cl1(self, mock_ts):
         mock_ts.return_value = [0x08]
-        result = reader.select(cl_level=1, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
+        result = nfc.select(cl_level=1, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
         mock_ts.assert_called_once_with(
             [0x93, 0x70, 0x04, 0x12, 0x34, 0x56, 0x61],
             tx_crc=True, rx_crc=True
         )
         assert result == [0x08]
 
-    @patch.object(reader, "transceive")
+    @patch("nfc.reader.transceive")
     def test_select_cl2(self, mock_ts):
         mock_ts.return_value = [0x08]
-        reader.select(cl_level=2, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
+        nfc.select(cl_level=2, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
         mock_ts.assert_called_once_with(
             [0x95, 0x70, 0x04, 0x12, 0x34, 0x56, 0x61],
             tx_crc=True, rx_crc=True
         )
 
-    @patch.object(reader, "transceive")
+    @patch("nfc.reader.transceive")
     def test_select_cl3(self, mock_ts):
         mock_ts.return_value = [0x08]
-        reader.select(cl_level=3, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
+        nfc.select(cl_level=3, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
         mock_ts.assert_called_once_with(
             [0x97, 0x70, 0x04, 0x12, 0x34, 0x56, 0x61],
             tx_crc=True, rx_crc=True
@@ -186,28 +201,28 @@ class TestSelect:
 
     def test_select_invalid_cl(self):
         with pytest.raises(ValueError, match="Invalid CL level"):
-            reader.select(cl_level=4, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
+            nfc.select(cl_level=4, uid=[0x04, 0x12, 0x34, 0x56, 0x61])
 
 
 class TestAnticoll:
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_anticoll_cl1(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x04, 0x12, 0x34, 0x56, 0x61], bits=40)
-        result = reader.anticoll(cl_level=1)
+        result = nfc.anticoll(cl_level=1)
         mock_tb.assert_called_once_with([0x93, 0x20], last_tx_bits=0, tx_crc=False, rx_crc=False)
         assert result is not None
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_anticoll_cl2(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x04, 0x12, 0x34, 0x56, 0x61], bits=40)
-        reader.anticoll(cl_level=2)
+        nfc.anticoll(cl_level=2)
         mock_tb.assert_called_once_with([0x95, 0x20], last_tx_bits=0, tx_crc=False, rx_crc=False)
 
-    @patch.object(reader, "transceive_bits")
+    @patch("nfc.reader.transceive_bits")
     def test_anticoll_with_uid_prefix(self, mock_tb):
         mock_tb.return_value = TransceiveBits(data=[0x04, 0x12, 0x34, 0x56, 0x61], bits=40)
-        reader.anticoll(cl_level=1, uid_prefix=[0x04, 0x12, 0x34, 0x56])
+        nfc.anticoll(cl_level=1, uid_prefix=[0x04, 0x12, 0x34, 0x56])
         mock_tb.assert_called_once_with(
             [0x93, 0x20, 0x04, 0x12, 0x34, 0x56],
             last_tx_bits=0, tx_crc=False, rx_crc=False
@@ -218,58 +233,99 @@ class TestFieldControl:
 
     def test_field_on(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        reader.field_on()
+        reader._target = mock
+        reader._connected = True
+        nfc.field_on()
         assert mock.rf_field is True
 
     def test_field_off(self):
         mock = _mock_reader()
-        reader._state._reader = mock
-        reader._state._connected = True
-        reader.field_off()
+        reader._target = mock
+        reader._connected = True
+        nfc.field_off()
         assert mock.rf_field is False
 
 
 class TestSession:
 
-    @patch.object(reader._state, "disconnect")
-    @patch.object(reader._state, "connect")
+    @patch("nfc.reader.disconnect")
+    @patch("nfc.reader.connect")
     def test_session_yields_reader(self, mock_connect, mock_disconnect):
         mock_rdr = _mock_reader()
 
         def fake_connect(port="COM20", reader_type="pn532"):
-            reader._state._reader = mock_rdr
-            reader._state._connected = True
+            reader._target = mock_rdr
+            reader._connected = True
 
         mock_connect.side_effect = fake_connect
 
-        with reader.session(port="COM99", reader_type="pn532") as r:
-            assert r is mock_rdr
+        with nfc.session(port="COM99", reader_type="pn532") as r:
+            assert r is reader
         mock_disconnect.assert_called_once()
 
-    def test_session_no_port_raises(self):
+    def test_session_no_port_raises(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(ValueError, match="未指定串口"):
-            with reader.session(reader_type="pn532"):
+            with nfc.session(reader_type="pn532"):
                 pass
 
-    def test_session_no_reader_type_raises(self):
+    def test_session_no_reader_type_raises(self, monkeypatch):
+        monkeypatch.delenv("NFC_PORT", raising=False)
+        monkeypatch.delenv("NFC_READER", raising=False)
         with pytest.raises(ValueError, match="未指定读卡器类型"):
-            with reader.session(port="COM99"):
+            with nfc.session(port="COM99"):
                 pass
 
 
 class TestGetSelCmd:
 
     def test_cl1(self):
-        assert reader._get_sel_cmd(1) == 0x93
+        from nfc.reader import _get_sel_cmd
+        assert _get_sel_cmd(1) == 0x93
 
     def test_cl2(self):
-        assert reader._get_sel_cmd(2) == 0x95
+        from nfc.reader import _get_sel_cmd
+        assert _get_sel_cmd(2) == 0x95
 
     def test_cl3(self):
-        assert reader._get_sel_cmd(3) == 0x97
+        from nfc.reader import _get_sel_cmd
+        assert _get_sel_cmd(3) == 0x97
 
     def test_invalid(self):
+        from nfc.reader import _get_sel_cmd
         with pytest.raises(ValueError):
-            reader._get_sel_cmd(4)
+            _get_sel_cmd(4)
+
+
+class TestReaderSingletonProxy:
+
+    @patch.object(CardReaderRegistry, "create")
+    def test_reader_rf_property_and_lazy_connect(self, mock_create, monkeypatch):
+        monkeypatch.setenv("NFC_PORT", "COM10")
+        monkeypatch.setenv("NFC_READER", "pn532")
+        mock_rdr = _mock_reader()
+        mock_create.return_value = mock_rdr
+
+        # reader.rf triggers auto-connect
+        reader.rf = True
+        assert mock_rdr.rf_field is True
+        assert reader.rf is True
+        assert reader.rf_field is True
+        assert reader.mf_crypto is False
+
+    @patch.object(CardReaderRegistry, "create")
+    def test_reader_delegates_to_functions_and_target(self, mock_create, monkeypatch):
+        monkeypatch.setenv("NFC_PORT", "COM10")
+        monkeypatch.setenv("NFC_READER", "pn532")
+        mock_rdr = _mock_reader()
+        mock_create.return_value = mock_rdr
+
+        # reader.active calls active()
+        card = reader.active()
+        assert card is not None
+        assert card.uid == [0x01, 0x02, 0x03, 0x04]
+
+        # reader.custom_method delegates to mock_rdr
+        mock_rdr.custom_method = MagicMock(return_value="OK")
+        assert reader.custom_method() == "OK"