dtflow 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

dtflow/cli/commands.py

@@ -1,7 +1,7 @@
 """
 CLI 命令实现
 """
-import orjson
+
 import os
 import shutil
 import tempfile
@@ -9,13 +9,15 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Literal, Optional
 
+import orjson
+
 from ..core import DataTransformer, DictWrapper
-from ..presets import get_preset, list_presets
-from ..storage.io import load_data, save_data, sample_file
+from ..lineage import format_lineage_report, get_lineage_chain, has_lineage, load_lineage
 from ..pipeline import run_pipeline, validate_pipeline
-from ..lineage import load_lineage, format_lineage_report, has_lineage, get_lineage_chain
+from ..presets import get_preset, list_presets
+from ..storage.io import load_data, sample_file, save_data
 from ..streaming import load_stream
-
+from ..utils.field_path import get_field_with_spec
 
 # 支持的文件格式
 SUPPORTED_FORMATS = {".csv", ".jsonl", ".json", ".xlsx", ".xls", ".parquet", ".arrow", ".feather"}
@@ -92,9 +94,7 @@ def sample(
     # 分层采样模式
     if by:
         try:
-            sampled = _stratified_sample(
-                filepath, num, by, uniform, seed, type
-            )
+            sampled = _stratified_sample(filepath, num, by, uniform, seed, type)
         except Exception as e:
             print(f"错误: {e}")
             return
@@ -138,7 +138,12 @@ def _stratified_sample(
     Args:
         filepath: 文件路径
         num: 目标采样总数
-        stratify_field: 分层字段
+        stratify_field: 分层字段，支持嵌套路径语法：
+            - meta.source        嵌套字段
+            - messages[0].role   数组索引
+            - messages[-1].role  负索引
+            - messages.#         数组长度
+            - messages[*].role   展开所有元素（可加 :join/:unique 模式）
         uniform: 是否均匀采样（各组相同数量）
         seed: 随机种子
         sample_type: 采样方式（用于组内采样）
@@ -159,10 +164,13 @@ def _stratified_sample(
     if num <= 0 or num > total:
         num = total
 
-    # 按字段分组
+    # 按字段分组（支持嵌套路径语法）
     groups: Dict[Any, List[Dict]] = defaultdict(list)
     for item in data:
-        key = item.get(stratify_field, "__null__")
+        key = get_field_with_spec(item, stratify_field, default="__null__")
+        # 确保 key 可哈希
+        if isinstance(key, list):
+            key = tuple(key)
         groups[key].append(item)
 
     group_keys = list(groups.keys())
@@ -360,7 +368,7 @@ def _format_nested(
     if isinstance(value, dict):
         items = list(value.items())
         for i, (k, v) in enumerate(items):
-            is_last_item = (i == len(items) - 1)
+            is_last_item = i == len(items) - 1
             b = "└─ " if is_last_item else "├─ "
             c = "   " if is_last_item else "│  "
 
@@ -369,11 +377,12 @@ def _format_nested(
                 if isinstance(v, list):
                     # 检测是否为 messages 格式
                     is_messages = (
-                        v and isinstance(v[0], dict)
-                        and "role" in v[0] and "content" in v[0]
+                        v and isinstance(v[0], dict) and "role" in v[0] and "content" in v[0]
                     )
                     if is_messages:
-                        lines.append(f"{indent}{b}[green]{k}[/green]: ({len(v)} items) [dim]→ \\[role]: content[/dim]")
+                        lines.append(
+                            f"{indent}{b}[green]{k}[/green]: ({len(v)} items) [dim]→ \\[role]: content[/dim]"
+                        )
                     else:
                         lines.append(f"{indent}{b}[green]{k}[/green]: ({len(v)} items)")
                 else:
@@ -385,7 +394,7 @@ def _format_nested(
 
     elif isinstance(value, list):
         for i, item in enumerate(value):
-            is_last_item = (i == len(value) - 1)
+            is_last_item = i == len(value) - 1
             b = "└─ " if is_last_item else "├─ "
             c = "   " if is_last_item else "│  "
 
@@ -457,8 +466,8 @@ def _print_samples(
 
     try:
         from rich.console import Console
-        from rich.table import Table
         from rich.panel import Panel
+        from rich.table import Table
 
         console = Console()
 
@@ -475,12 +484,14 @@ def _print_samples(
             else:
                 info = f"采样: {len(samples)} 条 | 字段: {len(all_fields)} 个"
 
-            console.print(Panel(
-                f"[dim]{info}[/dim]\n[dim]字段: {field_names}[/dim]",
-                title=f"[bold]📊 {filename}[/bold]",
-                expand=False,
-                border_style="dim",
-            ))
+            console.print(
+                Panel(
+                    f"[dim]{info}[/dim]\n[dim]字段: {field_names}[/dim]",
+                    title=f"[bold]📊 {filename}[/bold]",
+                    expand=False,
+                    border_style="dim",
+                )
+            )
             console.print()
 
         # 简单数据用表格展示
@@ -514,7 +525,9 @@ def _print_samples(
 
             print(f"\n📊 {filename}")
             if total_count is not None:
-                print(f"   总行数: {total_count:,} | 采样: {len(samples)} 条 | 字段: {len(all_fields)} 个")
+                print(
+                    f"   总行数: {total_count:,} | 采样: {len(samples)} 条 | 字段: {len(all_fields)} 个"
+                )
             else:
                 print(f"   采样: {len(samples)} 条 | 字段: {len(all_fields)} 个")
             print(f"   字段: {', '.join(sorted(all_fields))}")
@@ -780,7 +793,7 @@ def _generate_default_transform(field_names: List[str]) -> str:
     for name in field_names[:5]:  # 最多显示 5 个字段
         safe_name, _ = _sanitize_field_name(name)
         lines.append(f'        "{name}": item.{safe_name},')
-    return "\n".join(lines) if lines else '        # 在这里定义输出字段'
+    return "\n".join(lines) if lines else "        # 在这里定义输出字段"
 
 
 def _execute_transform(
@@ -827,6 +840,7 @@ def _execute_transform(
         except Exception as e:
             print(f"错误: 转换失败 - {e}")
             import traceback
+
             traceback.print_exc()
         return
 
@@ -852,6 +866,7 @@ def _execute_transform(
     except Exception as e:
         print(f"错误: 转换失败 - {e}")
         import traceback
+
         traceback.print_exc()
         return
 
@@ -930,6 +945,7 @@ def _execute_preset_transform(
                 os.unlink(temp_path)
             print(f"错误: 转换失败 - {e}")
             import traceback
+
             traceback.print_exc()
         return
 
@@ -955,6 +971,7 @@ def _execute_preset_transform(
     except Exception as e:
         print(f"错误: 转换失败 - {e}")
         import traceback
+
         traceback.print_exc()
         return
 
@@ -998,7 +1015,13 @@ def dedupe(
 
     Args:
         filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-        key: 去重依据字段，多个字段用逗号分隔。不指定则全量去重
+        key: 去重依据字段，支持嵌套路径语法：
+            - meta.source        嵌套字段
+            - messages[0].role   数组索引
+            - messages[-1].content  负索引
+            - messages.#         数组长度
+            - messages[*].role:join  展开所有元素
+            多个字段用逗号分隔。不指定则全量去重
         similar: 相似度阈值（0-1），指定后启用相似度去重模式，需要指定 --key
         output: 输出文件路径，不指定则覆盖原文件
 
@@ -1006,8 +1029,9 @@ def dedupe(
         dt dedupe data.jsonl                       # 全量精确去重
         dt dedupe data.jsonl --key=text            # 按 text 字段精确去重
         dt dedupe data.jsonl --key=user,timestamp  # 按多字段组合精确去重
-        dt dedupe data.jsonl --key=text --similar=0.8   # 相似度去重
-        dt dedupe data.jsonl --output=clean.jsonl  # 指定输出文件
+        dt dedupe data.jsonl --key=meta.id         # 按嵌套字段去重
+        dt dedupe data.jsonl --key=messages[0].content   # 按第一条消息内容去重
+        dt dedupe data.jsonl --key=text --similar=0.8    # 相似度去重
     """
     filepath = Path(filename)
 
@@ -1132,8 +1156,13 @@ def concat(
 
     for filepath in file_paths:
         try:
-            # 只读取第一行来获取字段
-            first_row = load_stream(str(filepath)).head(1).collect()
+            # 只读取第一行来获取字段（根据格式选择加载方式）
+            if _is_streaming_supported(filepath):
+                first_row = load_stream(str(filepath)).head(1).collect()
+            else:
+                # 非流式格式（如 .json, .xlsx）使用全量加载
+                data = load_data(str(filepath))
+                first_row = data[:1] if data else []
             if not first_row:
                 print(f"警告: 文件为空 - {filepath}")
                 fields = set()
@@ -1207,7 +1236,13 @@ def concat(
 
 def _concat_streaming(file_paths: List[Path], output: str) -> int:
     """流式拼接多个文件"""
-    from ..streaming import StreamingTransformer, _stream_jsonl, _stream_csv, _stream_parquet, _stream_arrow
+    from ..streaming import (
+        StreamingTransformer,
+        _stream_arrow,
+        _stream_csv,
+        _stream_jsonl,
+        _stream_parquet,
+    )
 
     def generator():
         for filepath in file_paths:
@@ -1413,12 +1448,16 @@ def _truncate(v: Any, max_width: int) -> str:
     result = []
     for char in s:
         # CJK 字符范围
-        if '\u4e00' <= char <= '\u9fff' or '\u3000' <= char <= '\u303f' or '\uff00' <= char <= '\uffef':
+        if (
+            "\u4e00" <= char <= "\u9fff"
+            or "\u3000" <= char <= "\u303f"
+            or "\uff00" <= char <= "\uffef"
+        ):
             char_width = 2
         else:
             char_width = 1
         if width + char_width > max_width - 3:  # 预留 ... 的宽度
-            return ''.join(result) + "..."
+            return "".join(result) + "..."
         result.append(char)
         width += char_width
     return s
@@ -1429,7 +1468,11 @@ def _display_width(s: str) -> int:
     width = 0
     for char in s:
         # CJK 字符范围
-        if '\u4e00' <= char <= '\u9fff' or '\u3000' <= char <= '\u303f' or '\uff00' <= char <= '\uffef':
+        if (
+            "\u4e00" <= char <= "\u9fff"
+            or "\u3000" <= char <= "\u303f"
+            or "\uff00" <= char <= "\uffef"
+        ):
             width += 2
         else:
             width += 1
@@ -1441,26 +1484,28 @@ def _pad_to_width(s: str, target_width: int) -> str:
     current_width = _display_width(s)
     if current_width >= target_width:
         return s
-    return s + ' ' * (target_width - current_width)
+    return s + " " * (target_width - current_width)
 
 
 def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -> None:
     """打印统计信息"""
     try:
         from rich.console import Console
-        from rich.table import Table
         from rich.panel import Panel
+        from rich.table import Table
 
         console = Console()
 
         # 概览
-        console.print(Panel(
-            f"[bold]文件:[/bold] {filename}\n"
-            f"[bold]总数:[/bold] {total:,} 条\n"
-            f"[bold]字段:[/bold] {len(field_stats)} 个",
-            title="📊 数据概览",
-            expand=False,
-        ))
+        console.print(
+            Panel(
+                f"[bold]文件:[/bold] {filename}\n"
+                f"[bold]总数:[/bold] {total:,} 条\n"
+                f"[bold]字段:[/bold] {len(field_stats)} 个",
+                title="📊 数据概览",
+                expand=False,
+            )
+        )
 
         # 字段统计表
         table = Table(title="📋 字段统计", show_header=True, header_style="bold cyan")
@@ -1477,12 +1522,18 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
             # 构建统计信息字符串
             extra = []
             if "len_avg" in stat:
-                extra.append(f"长度: {stat['len_min']}-{stat['len_max']} (avg {stat['len_avg']:.0f})")
+                extra.append(
+                    f"长度: {stat['len_min']}-{stat['len_max']} (avg {stat['len_avg']:.0f})"
+                )
             if "avg" in stat:
                 if stat["type"] == "int":
-                    extra.append(f"范围: {int(stat['min'])}-{int(stat['max'])} (avg {stat['avg']:.1f})")
+                    extra.append(
+                        f"范围: {int(stat['min'])}-{int(stat['max'])} (avg {stat['avg']:.1f})"
+                    )
                 else:
-                    extra.append(f"范围: {stat['min']:.2f}-{stat['max']:.2f} (avg {stat['avg']:.2f})")
+                    extra.append(
+                        f"范围: {stat['min']:.2f}-{stat['max']:.2f} (avg {stat['avg']:.2f})"
+                    )
 
             table.add_row(
                 stat["field"],
@@ -1509,7 +1560,9 @@ def _print_stats(filename: str, total: int, field_stats: List[Dict[str, Any]]) -
             if unique_ratio > 0.9 and stat.get("unique", 0) > 100:
                 continue
 
-            console.print(f"\n[bold cyan]{stat['field']}[/bold cyan] 值分布 (Top {len(top_values)}):")
+            console.print(
+                f"\n[bold cyan]{stat['field']}[/bold cyan] 值分布 (Top {len(top_values)}):"
+            )
             max_count = max(c for _, c in top_values) if top_values else 1
             for value, count in top_values:
                 pct = count / total * 100
@@ -1559,25 +1612,26 @@ def clean(
 
     Args:
         filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-        drop_empty: 删除空值记录
+        drop_empty: 删除空值记录，支持嵌套路径语法
             - 不带值：删除任意字段为空的记录
             - 指定字段：删除指定字段为空的记录（逗号分隔）
-        min_len: 最小长度过滤，格式 "字段:长度"（如 text:10）
-        max_len: 最大长度过滤，格式 "字段:长度"（如 text:1000）
-        keep: 只保留指定字段（逗号分隔）
-        drop: 删除指定字段（逗号分隔）
+        min_len: 最小长度过滤，格式 "字段:长度"，字段支持嵌套路径
+        max_len: 最大长度过滤，格式 "字段:长度"，字段支持嵌套路径
+        keep: 只保留指定字段（逗号分隔，仅支持顶层字段）
+        drop: 删除指定字段（逗号分隔，仅支持顶层字段）
         strip: 去除所有字符串字段的首尾空白
         output: 输出文件路径，不指定则覆盖原文件
 
     Examples:
         dt clean data.jsonl --drop-empty                    # 删除任意空值记录
         dt clean data.jsonl --drop-empty=text,answer        # 删除指定字段为空的记录
+        dt clean data.jsonl --drop-empty=meta.source        # 删除嵌套字段为空的记录
         dt clean data.jsonl --min-len=text:10               # text 字段最少 10 字符
-        dt clean data.jsonl --max-len=text:1000             # text 字段最多 1000 字符
+        dt clean data.jsonl --min-len=messages.#:2          # 至少 2 条消息
+        dt clean data.jsonl --max-len=messages[-1].content:500  # 最后一条消息最多 500 字符
         dt clean data.jsonl --keep=question,answer          # 只保留这些字段
         dt clean data.jsonl --drop=metadata,timestamp       # 删除这些字段
         dt clean data.jsonl --strip                         # 去除字符串首尾空白
-        dt clean data.jsonl --drop-empty --strip -o out.jsonl
     """
     filepath = Path(filename)
 
@@ -1666,6 +1720,7 @@ def clean(
                 os.unlink(temp_path)
             print(f"错误: 清洗失败 - {e}")
             import traceback
+
             traceback.print_exc()
         return
 
@@ -1746,9 +1801,18 @@ def _is_empty_value(v: Any) -> bool:
 
 
 def _get_value_len(value: Any) -> int:
-    """获取值的长度"""
+    """
+    获取值的长度。
+
+    - str/list/dict: 返回 len()
+    - int/float: 直接返回该数值（用于 messages.# 这种返回数量的场景）
+    - None: 返回 0
+    - 其他: 转为字符串后返回长度
+    """
     if value is None:
         return 0
+    if isinstance(value, (int, float)):
+        return int(value)
     if isinstance(value, (str, list, dict)):
         return len(value)
     return len(str(value))
@@ -1771,13 +1835,13 @@ def _clean_data_single_pass(
     Args:
         data: 原始数据列表
         strip: 是否去除字符串首尾空白
-        empty_fields: 检查空值的字段列表，空列表表示检查所有字段，None 表示不检查
-        min_len_field: 最小长度检查的字段
+        empty_fields: 检查空值的字段列表（支持嵌套路径），空列表表示检查所有字段，None 表示不检查
+        min_len_field: 最小长度检查的字段（支持嵌套路径）
         min_len_value: 最小长度值
-        max_len_field: 最大长度检查的字段
+        max_len_field: 最大长度检查的字段（支持嵌套路径）
         max_len_value: 最大长度值
-        keep_fields: 只保留的字段列表
-        drop_fields: 要删除的字段集合
+        keep_fields: 只保留的字段列表（仅支持顶层字段）
+        drop_fields: 要删除的字段集合（仅支持顶层字段）
 
     Returns:
         (清洗后的数据, 统计信息列表)
@@ -1805,20 +1869,20 @@ def _clean_data_single_pass(
                     stats["drop_empty"] += 1
                     continue
             else:
-                # 检查指定字段
-                if any(_is_empty_value(item.get(f)) for f in empty_fields):
+                # 检查指定字段（支持嵌套路径）
+                if any(_is_empty_value(get_field_with_spec(item, f)) for f in empty_fields):
                     stats["drop_empty"] += 1
                     continue
 
-        # 3. 最小长度过滤
+        # 3. 最小长度过滤（支持嵌套路径）
         if min_len_field is not None:
-            if _get_value_len(item.get(min_len_field, "")) < min_len_value:
+            if _get_value_len(get_field_with_spec(item, min_len_field, default="")) < min_len_value:
                 stats["min_len"] += 1
                 continue
 
-        # 4. 最大长度过滤
+        # 4. 最大长度过滤（支持嵌套路径）
         if max_len_field is not None:
-            if _get_value_len(item.get(max_len_field, "")) > max_len_value:
+            if _get_value_len(get_field_with_spec(item, max_len_field, default="")) > max_len_value:
                 stats["max_len"] += 1
                 continue
 
@@ -1866,25 +1930,27 @@ def _clean_streaming(
     Returns:
         处理后的数据条数
     """
+
     def clean_filter(item: Dict) -> bool:
-        """过滤函数：返回 True 保留，False 过滤"""
+        """过滤函数：返回 True 保留，False 过滤（支持嵌套路径）"""
         # 空值过滤
         if empty_fields is not None:
             if len(empty_fields) == 0:
                 if any(_is_empty_value(v) for v in item.values()):
                     return False
             else:
-                if any(_is_empty_value(item.get(f)) for f in empty_fields):
+                # 支持嵌套路径
+                if any(_is_empty_value(get_field_with_spec(item, f)) for f in empty_fields):
                     return False
 
-        # 最小长度过滤
+        # 最小长度过滤（支持嵌套路径）
         if min_len_field is not None:
-            if _get_value_len(item.get(min_len_field, "")) < min_len_value:
+            if _get_value_len(get_field_with_spec(item, min_len_field, default="")) < min_len_value:
                 return False
 
-        # 最大长度过滤
+        # 最大长度过滤（支持嵌套路径）
         if max_len_field is not None:
-            if _get_value_len(item.get(max_len_field, "")) > max_len_value:
+            if _get_value_len(get_field_with_spec(item, max_len_field, default="")) > max_len_value:
                 return False
 
         return True
@@ -1908,7 +1974,9 @@ def _clean_streaming(
 
     # 如果需要 strip，先执行 strip 转换（在过滤之前，这样空值检测更准确）
     if strip:
-        st = st.transform(lambda x: {k: v.strip() if isinstance(v, str) else v for k, v in x.items()})
+        st = st.transform(
+            lambda x: {k: v.strip() if isinstance(v, str) else v for k, v in x.items()}
+        )
 
     # 执行过滤
     if empty_fields is not None or min_len_field is not None or max_len_field is not None:
@@ -1916,12 +1984,14 @@ def _clean_streaming(
 
     # 执行字段管理（如果没有 strip，也需要在这里处理）
     if keep_set is not None or drop_fields_set is not None:
+
         def field_transform(item):
             if keep_set is not None:
                 return {k: v for k, v in item.items() if k in keep_set}
             elif drop_fields_set is not None:
                 return {k: v for k, v in item.items() if k not in drop_fields_set}
             return item
+
         st = st.transform(field_transform)
 
     return st.save(output_path)
@@ -1972,6 +2042,7 @@ def run(
     except Exception as e:
         print(f"错误: {e}")
         import traceback
+
         traceback.print_exc()
 
 
@@ -1989,13 +2060,15 @@ def token_stats(
 
     Args:
         filename: 输入文件路径
-        field: 要统计的字段（默认 messages）
+        field: 要统计的字段（默认 messages），支持嵌套路径语法
         model: 分词器: cl100k_base (默认), qwen2.5, llama3, gpt-4 等
         detailed: 是否显示详细统计
 
     Examples:
         dt token-stats data.jsonl
         dt token-stats data.jsonl --field=text --model=qwen2.5
+        dt token-stats data.jsonl --field=conversation.messages
+        dt token-stats data.jsonl --field=messages[-1].content   # 统计最后一条消息
         dt token-stats data.jsonl --detailed
     """
     filepath = Path(filename)
@@ -2023,19 +2096,21 @@ def token_stats(
     print(f"   共 {total} 条数据")
     print(f"🔢 统计 Token (模型: {model}, 字段: {field})...")
 
-    # 检查字段类型并选择合适的统计方法
+    # 检查字段类型并选择合适的统计方法（支持嵌套路径）
     sample = data[0]
-    field_value = sample.get(field)
+    field_value = get_field_with_spec(sample, field)
 
     try:
         if isinstance(field_value, list) and field_value and isinstance(field_value[0], dict):
             # messages 格式
             from ..tokenizers import messages_token_stats
+
             stats = messages_token_stats(data, messages_field=field, model=model)
             _print_messages_token_stats(stats, detailed)
         else:
             # 普通文本字段
             from ..tokenizers import token_stats as compute_token_stats
+
             stats = compute_token_stats(data, fields=field, model=model)
             _print_text_token_stats(stats, detailed)
     except ImportError as e:
@@ -2044,6 +2119,7 @@ def token_stats(
     except Exception as e:
         print(f"错误: 统计失败 - {e}")
         import traceback
+
         traceback.print_exc()
 
 
@@ -2051,8 +2127,8 @@ def _print_messages_token_stats(stats: Dict[str, Any], detailed: bool) -> None:
     """打印 messages 格式的 token 统计"""
     try:
         from rich.console import Console
-        from rich.table import Table
         from rich.panel import Panel
+        from rich.table import Table
 
         console = Console()
 
@@ -2073,8 +2149,12 @@ def _print_messages_token_stats(stats: Dict[str, Any], detailed: bool) -> None:
             table.add_column("Token 数", justify="right")
             table.add_column("占比", justify="right")
 
-            total = stats['total_tokens']
-            for role, key in [("User", "user_tokens"), ("Assistant", "assistant_tokens"), ("System", "system_tokens")]:
+            total = stats["total_tokens"]
+            for role, key in [
+                ("User", "user_tokens"),
+                ("Assistant", "assistant_tokens"),
+                ("System", "system_tokens"),
+            ]:
                 tokens = stats.get(key, 0)
                 pct = tokens / total * 100 if total > 0 else 0
                 table.add_row(role, f"{tokens:,}", f"{pct:.1f}%")
@@ -2097,8 +2177,12 @@ def _print_messages_token_stats(stats: Dict[str, Any], detailed: bool) -> None:
             print(f"\n{'=' * 40}")
             print("📋 分角色统计")
             print(f"{'=' * 40}")
-            total = stats['total_tokens']
-            for role, key in [("User", "user_tokens"), ("Assistant", "assistant_tokens"), ("System", "system_tokens")]:
+            total = stats["total_tokens"]
+            for role, key in [
+                ("User", "user_tokens"),
+                ("Assistant", "assistant_tokens"),
+                ("System", "system_tokens"),
+            ]:
                 tokens = stats.get(key, 0)
                 pct = tokens / total * 100 if total > 0 else 0
                 print(f"{role}: {tokens:,} ({pct:.1f}%)")
@@ -2148,12 +2232,13 @@ def diff(
     Args:
         file1: 第一个文件路径
         file2: 第二个文件路径
-        key: 用于匹配的键字段（可选）
+        key: 用于匹配的键字段，支持嵌套路径语法（可选）
         output: 差异报告输出路径（可选）
 
     Examples:
         dt diff v1/train.jsonl v2/train.jsonl
         dt diff a.jsonl b.jsonl --key=id
+        dt diff a.jsonl b.jsonl --key=meta.uuid   # 按嵌套字段匹配
         dt diff a.jsonl b.jsonl --output=diff_report.json
     """
     path1 = Path(file1)
@@ -2216,9 +2301,9 @@ def _compute_diff(
     }
 
     if key:
-        # 基于 key 的精确匹配
-        dict1 = {item.get(key): item for item in data1 if item.get(key) is not None}
-        dict2 = {item.get(key): item for item in data2 if item.get(key) is not None}
+        # 基于 key 的精确匹配（支持嵌套路径）
+        dict1 = {get_field_with_spec(item, key): item for item in data1 if get_field_with_spec(item, key) is not None}
+        dict2 = {get_field_with_spec(item, key): item for item in data2 if get_field_with_spec(item, key) is not None}
 
         keys1 = set(dict1.keys())
         keys2 = set(dict2.keys())
@@ -2241,11 +2326,13 @@ def _compute_diff(
             else:
                 result["summary"]["modified"] += 1
                 if len(result["details"]["modified"]) < 10:
-                    result["details"]["modified"].append({
-                        "key": k,
-                        "before": dict1[k],
-                        "after": dict2[k],
-                    })
+                    result["details"]["modified"].append(
+                        {
+                            "key": k,
+                            "before": dict1[k],
+                            "after": dict2[k],
+                        }
+                    )
     else:
         # 基于哈希的比较
         def _hash_item(item):
@@ -2290,8 +2377,8 @@ def _print_diff_report(diff_result: Dict[str, Any], name1: str, name2: str) -> N
 
     try:
         from rich.console import Console
-        from rich.table import Table
         from rich.panel import Panel
+        from rich.table import Table
 
         console = Console()
 
@@ -2311,9 +2398,13 @@ def _print_diff_report(diff_result: Dict[str, Any], name1: str, name2: str) -> N
         if field_changes["added_fields"] or field_changes["removed_fields"]:
             console.print("\n[bold]📋 字段变化:[/bold]")
             if field_changes["added_fields"]:
-                console.print(f"  [green]+ 新增字段:[/green] {', '.join(field_changes['added_fields'])}")
+                console.print(
+                    f"  [green]+ 新增字段:[/green] {', '.join(field_changes['added_fields'])}"
+                )
             if field_changes["removed_fields"]:
-                console.print(f"  [red]- 删除字段:[/red] {', '.join(field_changes['removed_fields'])}")
+                console.print(
+                    f"  [red]- 删除字段:[/red] {', '.join(field_changes['removed_fields'])}"
+                )
 
     except ImportError:
         print(f"\n{'=' * 50}")