nfcscript 0.0.13__tar.gz → 0.0.15__tar.gz

{nfcscript-0.0.13 → nfcscript-0.0.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.13
+Version: 0.0.15
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -36,13 +36,13 @@ nfcscript test_card.py -p COM21
 nfcscript test_card.py -r acr122u
 
 # 开启追踪层
-nfcscript test_card.py --trace-driver --trace-protocol
+nfcscript test_card.py --trace=protocol,debug
 
 # 设置日志级别
-nfcscript test_card.py --trace-level DEBUG
+nfcscript test_card.py --level=trace
 
 # 组合使用
-nfcscript test_card.py -p COM21 -r pn532 --trace-driver --trace-protocol --trace-level DEBUG
+nfcscript test_card.py -p COM21 -r pn532 --trace=protocol,debug --level=trace
 ```
 
 ### nfc-cli - 交互式命令行
@@ -120,13 +120,13 @@ from nfc import *
 connect()
 
 # 开启追踪
-trace.set_layer("DRIVER", True)
-trace.set_layer("PROTOCOL", True)
+trace.driver = True
+trace.protocol = True
 
 # 寻卡（自动切换协议解析器）
 card_info = active()
 ASSERT_IS_NOT_NONE(card_info, "未扫描到卡片")
-print(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
+trace.app(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
 
 # 创建卡片实例
 from nfctester.registry import CardRegistry
@@ -143,7 +143,7 @@ from nfc import *
 
 with session() as reader:
     card_info = reader.active()
-    print(card_info.uid)
+    trace.app(f"UID: {card_info.uid}")
 # 自动断开连接
 ```
 
@@ -181,14 +181,36 @@ with session() as reader:
 
 ### trace.py
 
+**简洁写法（推荐）：**
+
 | 函数 | 说明 |
 |------|------|
-| `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
-| `trace.set_level(level)` | 设置日志级别 |
-| `trace.set_parse(level)` | 设置解析级别 (0=关闭, 1=hex+摘要) |
-| `trace.add_sink(fn)` | 注册结构化 trace 事件回调 |
-| `trace.remove_sink(fn)` | 移除已注册的回调 |
-| `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
+| `trace.app(msg)` | 输出到 app 层 (level=50) |
+| `trace.debug(msg)` | 输出到 debug 层 (level=10) |
+| `trace.warning(msg)` | 输出到 warning 层 (level=30) |
+| `trace.error(msg)` | 输出到 error 层 (level=40) |
+| `trace.log(msg, layer="app")` | 通用文本日志，指定层 |
+
+**属性控制（推荐）：**
+
+| 属性 | 说明 |
+|------|------|
+| `trace.driver = True` | 启用 driver 层 |
+| `trace.protocol = True` | 启用 protocol 层 |
+| `trace.debug = False` | 禁用 debug 层 |
+| `trace.level = "warning"` | 设置最低日志级别 |
+| `trace.level = 30` | 或用数字 |
+
+```python
+# 简洁写法
+trace.app("UID: AA BB CC DD")
+trace.debug("[auth] Rt: 80 81")
+
+# 属性控制
+trace.driver = True
+trace.protocol = True
+trace.level = "debug"
+```
 
 ### assertions.py
 
@@ -211,7 +233,8 @@ with session() as reader:
 
 | 函数 | 说明 |
 |------|------|
-| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `PARSE_HEX(text)` | 解析纯 hex，返回 `list[int]` |
+| `PARSE_HEX_BITS(text, last_bits=None)` | 解析 hex + Verilog 位标记，返回 `tuple[list[int], int]` |
 | `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
 
 ### checksum.py
@@ -234,9 +257,8 @@ with session() as reader:
 |------|------|--------|
 | `NFC_PORT` | 串口号 | - |
 | `NFC_READER` | 读卡器类型 | - |
-| `NFC_TRACE_LEVEL` | 日志级别 | `INFO` |
-| `NFC_TRACE_DRIVER` | 开启 DRIVER 层追踪 | `false` |
-| `NFC_TRACE_PROTOCOL` | 开启 PROTOCOL 层追踪 | `false` |
+| `NFC_TRACE` | 启用的层 (逗号分隔) | - |
+| `NFC_TRACE_LEVEL` | 最低日志级别 | `warning` |
 | `NFC_CARD_PATH` | 外部卡片模块搜索路径 (分号分隔) | - |
 
 支持多层 `.env` 加载：从脚本目录向上搜索所有 `.env` 文件，按从外到内的顺序依次加载（内层覆盖外层同名变量）。
@@ -251,9 +273,8 @@ with session() as reader:
 ```
 NFC_PORT=COM20
 NFC_READER=pn532
-NFC_TRACE_LEVEL=DEBUG
-NFC_TRACE_DRIVER=true
-NFC_TRACE_PROTOCOL=true
+NFC_TRACE_LEVEL=warning
+NFC_TRACE=protocol,debug
 ```
 
 ## AI 编写脚本

{nfcscript-0.0.13 → nfcscript-0.0.15}/README.md

@@ -26,13 +26,13 @@ nfcscript test_card.py -p COM21
 nfcscript test_card.py -r acr122u
 
 # 开启追踪层
-nfcscript test_card.py --trace-driver --trace-protocol
+nfcscript test_card.py --trace=protocol,debug
 
 # 设置日志级别
-nfcscript test_card.py --trace-level DEBUG
+nfcscript test_card.py --level=trace
 
 # 组合使用
-nfcscript test_card.py -p COM21 -r pn532 --trace-driver --trace-protocol --trace-level DEBUG
+nfcscript test_card.py -p COM21 -r pn532 --trace=protocol,debug --level=trace
 ```
 
 ### nfc-cli - 交互式命令行
@@ -110,13 +110,13 @@ from nfc import *
 connect()
 
 # 开启追踪
-trace.set_layer("DRIVER", True)
-trace.set_layer("PROTOCOL", True)
+trace.driver = True
+trace.protocol = True
 
 # 寻卡（自动切换协议解析器）
 card_info = active()
 ASSERT_IS_NOT_NONE(card_info, "未扫描到卡片")
-print(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
+trace.app(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
 
 # 创建卡片实例
 from nfctester.registry import CardRegistry
@@ -133,7 +133,7 @@ from nfc import *
 
 with session() as reader:
     card_info = reader.active()
-    print(card_info.uid)
+    trace.app(f"UID: {card_info.uid}")
 # 自动断开连接
 ```
 
@@ -171,14 +171,36 @@ with session() as reader:
 
 ### trace.py
 
+**简洁写法（推荐）：**
+
 | 函数 | 说明 |
 |------|------|
-| `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
-| `trace.set_level(level)` | 设置日志级别 |
-| `trace.set_parse(level)` | 设置解析级别 (0=关闭, 1=hex+摘要) |
-| `trace.add_sink(fn)` | 注册结构化 trace 事件回调 |
-| `trace.remove_sink(fn)` | 移除已注册的回调 |
-| `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
+| `trace.app(msg)` | 输出到 app 层 (level=50) |
+| `trace.debug(msg)` | 输出到 debug 层 (level=10) |
+| `trace.warning(msg)` | 输出到 warning 层 (level=30) |
+| `trace.error(msg)` | 输出到 error 层 (level=40) |
+| `trace.log(msg, layer="app")` | 通用文本日志，指定层 |
+
+**属性控制（推荐）：**
+
+| 属性 | 说明 |
+|------|------|
+| `trace.driver = True` | 启用 driver 层 |
+| `trace.protocol = True` | 启用 protocol 层 |
+| `trace.debug = False` | 禁用 debug 层 |
+| `trace.level = "warning"` | 设置最低日志级别 |
+| `trace.level = 30` | 或用数字 |
+
+```python
+# 简洁写法
+trace.app("UID: AA BB CC DD")
+trace.debug("[auth] Rt: 80 81")
+
+# 属性控制
+trace.driver = True
+trace.protocol = True
+trace.level = "debug"
+```
 
 ### assertions.py
 
@@ -201,7 +223,8 @@ with session() as reader:
 
 | 函数 | 说明 |
 |------|------|
-| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `PARSE_HEX(text)` | 解析纯 hex，返回 `list[int]` |
+| `PARSE_HEX_BITS(text, last_bits=None)` | 解析 hex + Verilog 位标记，返回 `tuple[list[int], int]` |
 | `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
 
 ### checksum.py
@@ -224,9 +247,8 @@ with session() as reader:
 |------|------|--------|
 | `NFC_PORT` | 串口号 | - |
 | `NFC_READER` | 读卡器类型 | - |
-| `NFC_TRACE_LEVEL` | 日志级别 | `INFO` |
-| `NFC_TRACE_DRIVER` | 开启 DRIVER 层追踪 | `false` |
-| `NFC_TRACE_PROTOCOL` | 开启 PROTOCOL 层追踪 | `false` |
+| `NFC_TRACE` | 启用的层 (逗号分隔) | - |
+| `NFC_TRACE_LEVEL` | 最低日志级别 | `warning` |
 | `NFC_CARD_PATH` | 外部卡片模块搜索路径 (分号分隔) | - |
 
 支持多层 `.env` 加载：从脚本目录向上搜索所有 `.env` 文件，按从外到内的顺序依次加载（内层覆盖外层同名变量）。
@@ -241,9 +263,8 @@ with session() as reader:
 ```
 NFC_PORT=COM20
 NFC_READER=pn532
-NFC_TRACE_LEVEL=DEBUG
-NFC_TRACE_DRIVER=true
-NFC_TRACE_PROTOCOL=true
+NFC_TRACE_LEVEL=warning
+NFC_TRACE=protocol,debug
 ```
 
 ## AI 编写脚本

{nfcscript-0.0.13 → nfcscript-0.0.15}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nfcscript"
-version = "0.0.13"
+version = "0.0.15"
 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.13"
+current_version = "0.0.15"
 commit = true
 tag = true
 allow_dirty = true

{nfcscript-0.0.13 → nfcscript-0.0.15}/src/nfc/cli.py

@@ -19,20 +19,6 @@ def _find_dotenv_all(start_dir):
     chain.reverse()
     return chain
 
-def _parse_level(value: str) -> int:
-    """将字符串解析为解析级别，支持数字和别名"""
-    val = value.lower().strip()
-    if val in ("0", "false", "no", "off"):
-        return 0
-    if val in ("1", "simple", "summary"):
-        return 1
-    if val in ("2", "full", "tree"):
-        return 2
-    try:
-        return int(value)
-    except ValueError:
-        return 1
-
 def run_script(script_path):
     script_dir = os.path.dirname(os.path.abspath(script_path))
     cwd = os.getcwd()
@@ -55,11 +41,8 @@ def main():
     parser.add_argument("script", help="脚本文件路径")
     parser.add_argument("-p", "--port", default=None, help="串口号 (默认: NFC_PORT 环境变量或 COM20)")
     parser.add_argument("-r", "--reader", default=None, help="读卡器类型 (默认: NFC_READER 环境变量或 pn532)")
-    parser.add_argument("--trace-driver", action="store_true", help="开启 DRIVER 层追踪")
-    parser.add_argument("--trace-protocol", action="store_true", help="开启 PROTOCOL 层追踪")
-    parser.add_argument("--trace-parse", type=int, default=None, choices=[0, 1, 2],
-                        help="解析级别: 0=关闭 1=简单 2=复杂 (默认: NFC_TRACE_PARSE 或 1)")
-    parser.add_argument("--trace-level", default="INFO", help="日志级别 (默认: INFO)")
+    parser.add_argument("--trace", default=None, help="启用的层 (逗号分隔: driver,debug,protocol,warning,error,app,all)")
+    parser.add_argument("--level", default=None, help="最低日志级别 (trace/debug/warning/error/app, 默认: warning)")
 
     args, extra = parser.parse_known_args()
 
@@ -81,27 +64,23 @@ def main():
 
     from nfc import trace
 
-    trace_level = os.environ.get("NFC_TRACE_LEVEL", "INFO")
-    trace_driver = os.environ.get("NFC_TRACE_DRIVER", "").lower() in ("1", "true", "yes")
-    trace_protocol = os.environ.get("NFC_TRACE_PROTOCOL", "").lower() in ("1", "true", "yes")
-    trace_parse = os.environ.get("NFC_TRACE_PARSE", "1")
-    trace_width = os.environ.get("NFC_TRACE_WIDTH")
-
-    if args.trace_level != "INFO":
-        trace_level = args.trace_level
-    if args.trace_driver:
-        trace_driver = True
-    if args.trace_protocol:
-        trace_protocol = True
-    if args.trace_parse is not None:
-        trace_parse = str(args.trace_parse)
-
-    trace.set_level(trace_level)
-    trace.set_layer("DRIVER", trace_driver)
-    trace.set_layer("PROTOCOL", trace_protocol)
-    trace.set_parse(_parse_level(trace_parse))
-    if trace_width is not None:
-        os.environ["CRFT_TRACE_WIDTH"] = trace_width
+    # 解析 --trace: 启用指定层
+    trace_env = os.environ.get("NFC_TRACE", "")
+    trace_arg = args.trace or trace_env
+    if trace_arg:
+        trace.set_level("trace")  # 允许所有层可见
+        for name in trace_arg.split(","):
+            name = name.strip().lower()
+            if name == "all":
+                for layer in ["driver", "debug", "protocol", "warning", "error", "app"]:
+                    trace.set_layer(layer, True)
+            elif name:
+                trace.set_layer(name, True)
+
+    # 解析 --level: 最低级别过滤
+    level_env = os.environ.get("NFC_TRACE_LEVEL", "warning")
+    level_arg = args.level or level_env
+    trace.set_level(level_arg)
 
     run_script(args.script)
 

nfcscript-0.0.15/src/nfc/hex_util.py

@@ -0,0 +1,189 @@
+import re
+
+# 位标记正则：匹配 N'hXX 格式 (如 7'h26, 4'hC)
+BIT_PATTERN = re.compile(r"(\d+)\s*\'h\s*([0-9a-fA-F]+)")
+
+
+def PARSE_HEX(text: str) -> list[int]:
+    """
+    解析纯 hex 字符串为 list[int]。
+
+    Args:
+        text: 十六进制文本，支持空格分隔 (如 "AA BB CC" 或 "AABBCC")。
+
+    Returns:
+        list[int]: 解析后的字节列表。
+
+    Raises:
+        ValueError: 不合法的十六进制数据时抛出。
+
+    Examples:
+        >>> PARSE_HEX("AA BB CC")
+        [0xAA, 0xBB, 0xCC]
+        >>> PARSE_HEX("0011")
+        [0x00, 0x11]
+    """
+    # 去空格得到纯 hex
+    clean_hex = text.replace(" ", "").upper()
+
+    # 简单的合法性检查
+    if clean_hex:
+        try:
+            return list(bytes.fromhex(clean_hex))
+        except ValueError:
+            raise ValueError(f"不合法的十六进制数据: {clean_hex}")
+    return []
+
+
+def PARSE_HEX_BITS(text: str, last_bits: int | None = None) -> tuple[list[int], int]:
+    """
+    解析 hex 字符串为 tuple[list[int], int]，支持 Verilog 位标记。
+
+    支持格式:
+    - 纯 hex: "AA BB CC" → ([0xAA, 0xBB, 0xCC], 0)
+    - Verilog 标记: "AA 4'hBB" → ([0xAA, 0x0B], 4)
+    - 混合: "AA BB 7'h03" → ([0xAA, 0xBB, 0x03], 7)
+    - 手动指定: "AA BB", last_bits=4 → ([0xAA, 0xBB], 4)
+
+    Args:
+        text: 十六进制文本，支持空格分隔和 N'hXX 位标记。
+        last_bits: 可选的最后字节有效位数，与 Verilog 标记冲突时报错。
+
+    Returns:
+        tuple[list[int], int]: (字节列表, 最后字节有效位数)。
+
+    Raises:
+        ValueError: 不合法的十六进制数据、位标记冲突或多标记时报错。
+
+    Examples:
+        >>> PARSE_HEX_BITS("AA BB CC")
+        ([0xAA, 0xBB, 0xCC], 0)
+        >>> PARSE_HEX_BITS("AA 4'hBB")
+        ([0xAA, 0x0B], 4)
+        >>> PARSE_HEX_BITS("0011", last_bits=4)
+        ([0x00, 0x01], 4)
+        >>> PARSE_HEX_BITS("AA 4'hBB", last_bits=4)
+        ValueError: 冲突
+    """
+    # 冲突检测：只允许一个 Verilog 标记
+    matches = list(BIT_PATTERN.finditer(text))
+    if len(matches) > 1:
+        raise ValueError("只允许一个 Verilog 位标记")
+    if matches and last_bits is not None:
+        raise ValueError("last_bits 参数与 Verilog 位标记冲突")
+
+    bits = last_bits if last_bits is not None else 0
+
+    # 处理 Verilog 位标记
+    if matches:
+        m = matches[0]
+        n_bits = int(m.group(1))
+        bits = n_bits
+        # 按 bits 截断: 4'hCA → 0x0A
+        val = int(m.group(2), 16) & ((1 << n_bits) - 1)
+        hex_val = format(val, 'X')
+        if len(hex_val) % 2 != 0:
+            hex_val = '0' + hex_val
+        text = text[:m.start()] + hex_val + text[m.end():]
+
+    # 去空格得到纯 hex
+    clean_hex = text.replace(" ", "").upper()
+
+    # 解析 hex 数据
+    if clean_hex:
+        try:
+            data = list(bytes.fromhex(clean_hex))
+        except ValueError:
+            raise ValueError(f"不合法的十六进制数据: {clean_hex}")
+    else:
+        data = []
+
+    # last_bits 截断最后一个字节
+    if bits and data:
+        data[-1] = data[-1] & ((1 << bits) - 1)
+
+    return data, bits
+
+
+def FORMAT_HEX(data: int | bytes | list[int] | str, last_bits: int = 0) -> str:
+    """
+    格式化数据为带位标记的可视化格式。
+
+    支持输入类型: 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 = 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):
+        hex_str = bytes(data).hex().upper()
+    elif isinstance(data, str):
+        hex_str = data.replace(" ", "").upper()
+    else:
+        raise TypeError(f"不支持的输入类型: {type(data)}")
+
+    if not hex_str:
+        return ""
+
+    # 2. 如果是整字节 (无 last_bits)
+    if last_bits == 0:
+        return ' '.join(hex_str[i:i+2] for i in range(0, len(hex_str), 2))
+
+    # 3. 有 last_bits，处理最后一个字节
+    if len(hex_str) <= 2:
+        return f"{last_bits}'h{hex_str}"
+
+    prefix = hex_str[:-2]
+    last_byte = hex_str[-2:]
+    formatted_prefix = ' '.join(prefix[i:i+2] for i in range(0, len(prefix), 2))
+    return f"{formatted_prefix} {last_bits}'h{last_byte}"
+
+
+if __name__ == "__main__":
+    # --- 测试例程 ---
+    print("=== Hex 工具测试 ===")
+
+    # 测试用例: (data, last_bits, 类型名)
+    test_cases = [
+        ("AABB03", 7, "str"),
+        (0xAABB03, 7, "int"),
+        (b'\xAA\xBB\x03', 7, "bytes"),
+        ([0xAA, 0xBB, 0x03], 7, "list"),
+        ("FF", 4, "str"),
+        (0xFF, 4, "int"),
+        ("AABBCC", 0, "str"),
+        (0xAABBCC, 0, "int"),
+        (b'\xAA\xBB\xCC', 0, "bytes"),
+    ]
+
+    for data, b, typename in test_cases:
+        formatted = FORMAT_HEX(data, b)
+        print(f"输入: ({data}, {b}, {typename}) -> 格式化: {formatted}")
+
+        # 反向解析验证
+        if b:
+            parsed, bits = PARSE_HEX_BITS(formatted)
+            print(f"解析: {formatted} -> Hex: {parsed}, Bits: {bits}")
+        else:
+            parsed = PARSE_HEX(formatted)
+            print(f"解析: {formatted} -> Hex: {parsed}")
+        print("-" * 20)

{nfcscript-0.0.13 → nfcscript-0.0.15}/src/nfc/reader.py

@@ -28,14 +28,14 @@ class _NFCState:
         self._reader = CardReaderRegistry.create(reader_type, transport="serial", port=port)
         self._reader.open()
         self._connected = True
-        print(f"Connected to {reader_type.upper()} on port {port}")
+        _trace.log(f"Connected to {reader_type.upper()} on port {port}", layer="app")
 
     def disconnect(self):
         if self._connected and self._reader:
             self._reader.close()
             self._connected = False
             self._reader = None
-            print("Disconnected")
+            _trace.log("Disconnected", layer="app")
 
     def ensure_connected(self):
         ASSERT_IS_NOT_NONE(self._reader, msg="NFC driver not connected. Call connect() first.")
@@ -125,9 +125,9 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
             if not ignore_error:
                 ASSERT_EQUAL(expected_bcc, data[4], msg=f"CL{cl} BCC 校验失败: data={FORMAT_HEX(data)}")
             elif data[4] != expected_bcc:
-                print(f"Warning: CL{cl} BCC 校验失败")
+                _trace.log(f"Warning: CL{cl} BCC 校验失败", layer="warning")
 
-        print(f"cl{cl}.uid: {FORMAT_HEX(data)}")
+        _trace.log(f"cl{cl}.uid: {FORMAT_HEX(data)}", layer="app")
         has_next = (data[0] == 0x88)
         uid_to_select = data[0:5]
         sak_res = select(cl_level=cl, uid=uid_to_select)
@@ -137,7 +137,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
             if not ignore_error:
                 ASSERT_IS_NOT_NONE(sak_res, msg=f"CL{cl} SAK 选择失败")
             else:
-                print(f"Warning: CL{cl} SAK 选择失败")
+                _trace.log(f"Warning: CL{cl} SAK 选择失败", layer="warning")
 
         if has_next:
             full_uid.extend(data[1:4])

{nfcscript-0.0.13 → nfcscript-0.0.15}/src/nfc/trace.py

@@ -1,19 +1,66 @@
 """
 NFC Script Trace 模块
 
-提供日志追踪控制，包装 nfctester.trace 的功能。
+统一日志 API，包装 nfctester.trace 的 6 层日志系统。
+层: driver, debug, protocol, warning, error, app
+
+支持两种控制方式：
+1. 属性控制: trace.driver = True, trace.level = "warning"
+2. 方法控制: trace.set_layer("driver", True), trace.set_level("warning")
 """
 
 from typing import Callable
 from nfctester.trace import TraceEvent, trace as _trace
 
 
+def log(msg: str, layer: str = "app"):
+    """通用文本日志，指定层"""
+    _trace.log(msg, layer)
+
+
+def app(msg: str):
+    """输出到 app 层 (level=50)"""
+    _trace.app(msg)
+
+
+def debug(msg: str):
+    """输出到 debug 层 (level=10)"""
+    _trace.debug(msg)
+
+
+def warning(msg: str):
+    """输出到 warning 层 (level=30)"""
+    _trace.warning(msg)
+
+
+def error(msg: str):
+    """输出到 error 层 (level=40)"""
+    _trace.error(msg)
+
+
+def info(msg: str):
+    """输出 INFO 级别日志 (无层标签)"""
+    _trace.info(msg)
+
+
+# --- 属性控制 ---
+
+def __setattr__(name, value):
+    """属性控制: trace.driver = True"""
+    setattr(_trace, name, value)
+
+
+def __getattr__(name):
+    """属性获取: trace.driver"""
+    return getattr(_trace, name)
+
+
 def set_layer(layer: str, enable: bool = True):
     """
     开启或关闭追踪层。
 
     Args:
-        layer: 层级名称 ("DRIVER" 或 "PROTOCOL")
+        layer: 层级名称 ("driver", "debug", "protocol", "warning", "error", "app")
         enable: True 开启，False 关闭
     """
     _trace.set_layer(layer, enable)
@@ -21,10 +68,10 @@ def set_layer(layer: str, enable: bool = True):
 
 def set_level(level: str):
     """
-    设置日志级别。
+    设置最低日志级别。
 
     Args:
-        level: 级别名称 ("INFO", "DEBUG", "ERROR" 等)
+        level: 级别名称 ("trace", "debug", "warning", "error", "app")
     """
     _trace.set_level(level)
 
@@ -39,31 +86,6 @@ def set_parse(level: int = 1):
     _trace.set_parse(level)
 
 
-def info(msg: str):
-    """输出 INFO 级别日志"""
-    _trace.info(msg)
-
-
-def error(msg: str):
-    """输出 ERROR 级别日志"""
-    _trace.error(msg)
-
-
-def warning(msg: str):
-    """输出 WARNING 级别日志"""
-    _trace.warning(msg)
-
-
-def success(msg: str):
-    """输出 SUCCESS 级别日志"""
-    _trace.success(msg)
-
-
-def debug(msg: str):
-    """输出 DEBUG 级别日志"""
-    _trace.debug(msg)
-
-
 def add_sink(fn: Callable[[TraceEvent], None]):
     """
     注册结构化 trace 事件回调。