dtflow 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

dtflow/__init__.py

@@ -42,7 +42,7 @@ from .tokenizers import (
     token_stats,
 )
 
-__version__ = "0.3.2"
+__version__ = "0.4.1"
 
 __all__ = [
     # core

dtflow/cli/commands.py

@@ -17,6 +17,7 @@ from ..pipeline import run_pipeline, validate_pipeline
 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"}
@@ -137,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: 采样方式（用于组内采样）
@@ -158,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())
@@ -787,6 +796,17 @@ def _generate_default_transform(field_names: List[str]) -> str:
     return "\n".join(lines) if lines else "        # 在这里定义输出字段"
 
 
+def _unwrap(obj: Any) -> Any:
+    """递归将 DictWrapper 转换为普通 dict"""
+    if hasattr(obj, "to_dict"):
+        return _unwrap(obj.to_dict())
+    if isinstance(obj, dict):
+        return {k: _unwrap(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_unwrap(v) for v in obj]
+    return obj
+
+
 def _execute_transform(
     input_path: Path,
     config_path: Path,
@@ -820,7 +840,8 @@ def _execute_transform(
         try:
             # 包装转换函数以支持属性访问（配置文件中定义的 Item 类）
             def wrapped_transform(item):
-                return transform_func(DictWrapper(item))
+                result = transform_func(DictWrapper(item))
+                return _unwrap(result)
 
             st = load_stream(str(input_path))
             if num:
@@ -917,7 +938,8 @@ def _execute_preset_transform(
         try:
             # 包装转换函数以支持属性访问
             def wrapped_transform(item):
-                return transform_func(DictWrapper(item))
+                result = transform_func(DictWrapper(item))
+                return _unwrap(result)
 
             st = load_stream(str(input_path))
             if num:
@@ -1006,7 +1028,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: 输出文件路径，不指定则覆盖原文件
 
@@ -1014,8 +1042,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)
 
@@ -1596,25 +1625,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)
 
@@ -1784,9 +1814,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))
@@ -1809,13 +1848,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:
         (清洗后的数据, 统计信息列表)
@@ -1843,20 +1882,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
 
@@ -1906,24 +1945,25 @@ def _clean_streaming(
     """
 
     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
@@ -2033,13 +2073,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)
@@ -2067,9 +2109,9 @@ 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):
@@ -2203,12 +2245,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)
@@ -2271,9 +2314,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())

dtflow/core.py

@@ -12,6 +12,7 @@ import orjson
 
 from .lineage import LineageTracker
 from .storage.io import load_data, save_data
+from .utils.field_path import get_field_with_spec
 
 
 def _fast_json_dumps(obj: Any) -> str:
@@ -393,16 +394,35 @@ class DataTransformer:
         item: Dict[str, Any],
         key: Union[None, str, List[str], Callable[[Any], Any]],
     ) -> Any:
-        """获取去重用的 key"""
+        """
+        获取去重用的 key。
+
+        支持字段路径语法：
+            - meta.source        嵌套字段
+            - messages[0].role   数组索引
+            - messages[-1].role  负索引
+            - messages.#         数组长度
+            - messages[*].role   展开所有元素（可加 :join/:unique 模式）
+        """
         if key is None:
             # 全量去重：使用快速 JSON 序列化
             return _fast_json_dumps(item)
         elif isinstance(key, str):
-            # 单字段
-            return item.get(key)
+            # 单字段（支持嵌套路径）
+            val = get_field_with_spec(item, key)
+            # 确保可哈希
+            if isinstance(val, list):
+                return tuple(val)
+            return val
         elif isinstance(key, list):
-            # 多字段组合
-            return tuple(item.get(k) for k in key)
+            # 多字段组合（每个字段都支持嵌套路径）
+            vals = []
+            for k in key:
+                v = get_field_with_spec(item, k)
+                if isinstance(v, list):
+                    v = tuple(v)
+                vals.append(v)
+            return tuple(vals)
         elif callable(key):
             # 自定义函数
             return key(DictWrapper(item))
@@ -506,9 +526,14 @@ class DataTransformer:
         item: Dict[str, Any],
         key: Union[str, Callable[[Any], str]],
     ) -> str:
-        """获取用于相似度比较的文本"""
+        """
+        获取用于相似度比较的文本。
+
+        支持字段路径语法（同 _get_dedupe_key）。
+        """
         if isinstance(key, str):
-            return str(item.get(key, ""))
+            val = get_field_with_spec(item, key, default="")
+            return str(val) if val else ""
         elif callable(key):
             return str(key(DictWrapper(item)))
         else:

dtflow/streaming.py

@@ -84,6 +84,8 @@ class StreamingTransformer:
         self._source_path = source_path
         self._total = total
         self._operations: List[Dict[str, Any]] = []
+        self._error_count = 0
+        self._first_error: Optional[str] = None
 
     @classmethod
     def load_stream(cls, filepath: str, batch_size: int = 10000) -> "StreamingTransformer":
@@ -194,17 +196,20 @@ class StreamingTransformer:
         Returns:
             新的 StreamingTransformer（惰性，不立即执行）
         """
+        # transform 是 1:1 转换，保留 total
+        new_st = StreamingTransformer(iter([]), self._source_path, total=self._total)
+        new_st._operations = self._operations + [{"type": "transform", "func": func}]
 
         def transformed_iterator():
             for item in self._iterator:
                 try:
                     yield func(item)
-                except Exception:
-                    pass  # 跳过错误
+                except Exception as e:
+                    new_st._error_count += 1
+                    if new_st._first_error is None:
+                        new_st._first_error = f"{type(e).__name__}: {e}"
 
-        # transform 是 1:1 转换，保留 total
-        new_st = StreamingTransformer(transformed_iterator(), self._source_path, total=self._total)
-        new_st._operations = self._operations + [{"type": "transform", "func": func}]
+        new_st._iterator = transformed_iterator()
         return new_st
 
     def head(self, n: int) -> "StreamingTransformer":
@@ -299,16 +304,21 @@ class StreamingTransformer:
         ext = path.suffix.lower()
 
         if ext == ".jsonl":
-            return self._save_jsonl(filepath, show_progress)
+            count = self._save_jsonl(filepath, show_progress)
         elif ext == ".csv":
-            return self._save_batched(filepath, "csv", batch_size, show_progress)
+            count = self._save_batched(filepath, "csv", batch_size, show_progress)
         elif ext == ".parquet":
-            return self._save_batched(filepath, "parquet", batch_size, show_progress)
+            count = self._save_batched(filepath, "parquet", batch_size, show_progress)
         elif ext in (".arrow", ".feather"):
-            return self._save_batched(filepath, "arrow", batch_size, show_progress)
+            count = self._save_batched(filepath, "arrow", batch_size, show_progress)
         else:
-            # 默认 JSONL
-            return self._save_jsonl(filepath, show_progress)
+            count = self._save_jsonl(filepath, show_progress)
+
+        # 打印错误摘要
+        if self._error_count > 0:
+            print(f"⚠️  跳过 {self._error_count} 条错误记录: {self._first_error}")
+
+        return count
 
     def _save_jsonl(self, filepath: str, show_progress: bool) -> int:
         """JSONL 逐行流式保存（使用 orjson）"""

dtflow/tokenizers.py

@@ -7,6 +7,8 @@ Token 统计模块
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
+from .utils.field_path import get_field_with_spec
+
 # 延迟导入，避免未安装时报错
 _tokenizer_cache = {}
 
@@ -290,7 +292,7 @@ def token_stats(
 
     Args:
         data: 数据列表
-        fields: 要统计的字段
+        fields: 要统计的字段，支持嵌套路径语法（如 meta.text, messages[-1].content）
         model: 模型名称或别名，如 "qwen2.5", "gpt-4" 等
         backend: 后端选择，None 则自动检测
 
@@ -307,7 +309,7 @@ def token_stats(
     for item in data:
         total = 0
         for field in fields:
-            value = item.get(field, "")
+            value = get_field_with_spec(item, field, default="")
             if value:
                 total += count_tokens(str(value), model=model, backend=backend)
         counts.append(total)
@@ -508,7 +510,7 @@ def messages_token_stats(
 
     Args:
         data: 数据列表
-        messages_field: messages 字段名
+        messages_field: messages 字段名，支持嵌套路径语法（如 conversation.messages）
         model: 模型名称或别名
         backend: 后端，None 则自动检测
 
@@ -538,7 +540,7 @@ def messages_token_stats(
 
     all_stats = []
     for item in data:
-        messages = item.get(messages_field, [])
+        messages = get_field_with_spec(item, messages_field, default=[])
         if messages:
             all_stats.append(_count_messages_tokens(messages, model=model, backend=_backend))
 

dtflow/utils/__init__.py

@@ -1,5 +1,23 @@
 """工具函数"""
 
 from .display import display_data, print_stats
+from .field_path import (
+    ExpandMode,
+    extract,
+    extract_with_spec,
+    get_field,
+    get_field_with_spec,
+    parse_field_spec,
+)
 
-__all__ = ["display_data", "print_stats"]
+__all__ = [
+    "display_data",
+    "print_stats",
+    # field_path
+    "get_field",
+    "get_field_with_spec",
+    "parse_field_spec",
+    "extract",
+    "extract_with_spec",
+    "ExpandMode",
+]

dtflow/utils/field_path.py

@@ -0,0 +1,274 @@
+"""
+字段路径解析模块
+
+支持的语法:
+    a.b.c        嵌套字段访问
+    a[0].b       数组索引访问
+    a[-1].b      负索引访问
+    a.#          数组长度
+    a[*].b       展开所有元素
+
+展开模式 (用于 [*]):
+    first   取第一个值（默认）
+    join    拼接为字符串（用 | 分隔）
+    unique  去重后排序拼接
+
+用法:
+    from dtflow.utils.field_path import get_field
+
+    # 基础用法
+    get_field(item, "meta.source")
+    get_field(item, "messages[0].role")
+    get_field(item, "messages[-1].content")
+    get_field(item, "messages.#")
+
+    # 展开模式
+    get_field(item, "messages[*].role")              # 默认取第一个
+    get_field(item, "messages[*].role", mode="join") # 拼接: "system|user|assistant"
+    get_field(item, "messages[*].role", mode="unique") # 去重: "assistant|system|user"
+
+    # 解析路径语法
+    path, mode = parse_field_spec("messages[*].role:unique")
+"""
+
+import re
+from typing import Any, List, Literal, Optional, Tuple, Union
+
+# 展开模式类型
+ExpandMode = Literal["first", "join", "unique"]
+
+# 路径段解析正则
+# 匹配: field, field[0], field[-1], field[*], field.#
+_SEGMENT_PATTERN = re.compile(
+    r"([a-zA-Z_\u4e00-\u9fff][a-zA-Z0-9_\u4e00-\u9fff]*)"  # 字段名（支持中文）
+    r"(?:\[(-?\d+|\*)\])?"  # 可选的索引 [0], [-1], [*]
+    r"|(#)"  # 或者长度操作符 #
+)
+
+
+def parse_field_spec(spec: str) -> Tuple[str, ExpandMode]:
+    """
+    解析字段规格，分离路径和展开模式
+
+    Args:
+        spec: 字段规格，如 "messages[*].role:unique"
+
+    Returns:
+        (path, mode) 元组
+
+    Examples:
+        >>> parse_field_spec("meta.source")
+        ('meta.source', 'first')
+        >>> parse_field_spec("messages[*].role:join")
+        ('messages[*].role', 'join')
+    """
+    if ":" in spec:
+        path, mode_str = spec.rsplit(":", 1)
+        if mode_str in ("first", "join", "unique"):
+            return path, mode_str  # type: ignore
+        # 冒号不是模式分隔符，可能是字段名的一部分
+        return spec, "first"
+    return spec, "first"
+
+
+def _parse_path(path: str) -> List[Union[str, int, Literal["*", "#"]]]:
+    """
+    解析路径字符串为段列表
+
+    Args:
+        path: 路径字符串，如 "messages[0].role" 或 "meta.source"
+
+    Returns:
+        段列表，如 ["messages", 0, "role"] 或 ["meta", "source"]
+    """
+    segments: List[Union[str, int, Literal["*", "#"]]] = []
+
+    # 按点分割，但保留方括号内容
+    parts = path.replace("][", "].[").split(".")
+
+    for part in parts:
+        if not part:
+            continue
+
+        # 检查是否是长度操作符
+        if part == "#":
+            segments.append("#")
+            continue
+
+        # 解析 field[index] 格式
+        match = re.match(r"([a-zA-Z_\u4e00-\u9fff][a-zA-Z0-9_\u4e00-\u9fff]*)?(?:\[(-?\d+|\*)\])?", part)
+        if match:
+            field_name, index = match.groups()
+
+            if field_name:
+                segments.append(field_name)
+
+            if index is not None:
+                if index == "*":
+                    segments.append("*")
+                else:
+                    segments.append(int(index))
+
+    return segments
+
+
+def _get_value_by_segments(
+    data: Any,
+    segments: List[Union[str, int, Literal["*", "#"]]],
+    mode: ExpandMode = "first",
+) -> Any:
+    """
+    根据段列表从数据中提取值
+
+    Args:
+        data: 源数据
+        segments: 路径段列表
+        mode: 展开模式
+
+    Returns:
+        提取的值
+    """
+    if not segments:
+        return data
+
+    current = data
+    i = 0
+
+    while i < len(segments):
+        seg = segments[i]
+
+        if current is None:
+            return None
+
+        # 长度操作符
+        if seg == "#":
+            if isinstance(current, (list, tuple, str)):
+                return len(current)
+            return None
+
+        # 展开操作符
+        if seg == "*":
+            if not isinstance(current, (list, tuple)):
+                return None
+
+            # 获取剩余路径
+            remaining = segments[i + 1 :]
+
+            # 对每个元素递归获取值
+            values = []
+            for item in current:
+                val = _get_value_by_segments(item, remaining, mode="first")
+                if val is not None:
+                    values.append(val)
+
+            # 根据模式处理结果
+            if not values:
+                return None
+
+            if mode == "first":
+                return values[0]
+            elif mode == "join":
+                return "|".join(str(v) for v in values)
+            elif mode == "unique":
+                unique_vals = sorted(set(str(v) for v in values))
+                return "|".join(unique_vals)
+
+            return values
+
+        # 字典字段访问
+        if isinstance(seg, str):
+            if isinstance(current, dict):
+                current = current.get(seg)
+            else:
+                return None
+
+        # 数组索引访问
+        elif isinstance(seg, int):
+            if isinstance(current, (list, tuple)):
+                try:
+                    current = current[seg]
+                except IndexError:
+                    return None
+            else:
+                return None
+
+        i += 1
+
+    return current
+
+
+def get_field(
+    data: dict,
+    path: str,
+    mode: ExpandMode = "first",
+    default: Any = None,
+) -> Any:
+    """
+    从字典中获取嵌套字段值
+
+    Args:
+        data: 源字典
+        path: 字段路径
+        mode: 展开模式（当路径包含 [*] 时生效）
+        default: 默认值（当路径不存在时返回）
+
+    Returns:
+        字段值或默认值
+
+    Examples:
+        >>> data = {"meta": {"source": "wiki"}, "messages": [{"role": "user"}, {"role": "assistant"}]}
+
+        # 嵌套字段
+        >>> get_field(data, "meta.source")
+        'wiki'
+
+        # 数组索引
+        >>> get_field(data, "messages[0].role")
+        'user'
+        >>> get_field(data, "messages[-1].role")
+        'assistant'
+
+        # 数组长度
+        >>> get_field(data, "messages.#")
+        2
+
+        # 展开所有元素
+        >>> get_field(data, "messages[*].role")
+        'user'
+        >>> get_field(data, "messages[*].role", mode="join")
+        'user|assistant'
+        >>> get_field(data, "messages[*].role", mode="unique")
+        'assistant|user'
+    """
+    if not path:
+        return default
+
+    segments = _parse_path(path)
+    result = _get_value_by_segments(data, segments, mode)
+
+    return result if result is not None else default
+
+
+def get_field_with_spec(data: dict, spec: str, default: Any = None) -> Any:
+    """
+    解析完整的字段规格并获取值
+
+    Args:
+        data: 源字典
+        spec: 字段规格，如 "messages[*].role:unique"
+        default: 默认值
+
+    Returns:
+        字段值
+
+    Examples:
+        >>> get_field_with_spec(data, "messages[*].role:join")
+        'user|assistant'
+    """
+    path, mode = parse_field_spec(spec)
+    return get_field(data, path, mode=mode, default=default)
+
+
+# 便捷别名
+extract = get_field
+extract_with_spec = get_field_with_spec

{dtflow-0.3.2.dist-info → dtflow-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dtflow
-Version: 0.3.2
+Version: 0.4.1
 Summary: A flexible data transformation tool for ML training formats (SFT, RLHF, Pretrain)
 Project-URL: Homepage, https://github.com/yourusername/DataTransformer
 Project-URL: Documentation, https://github.com/yourusername/DataTransformer#readme
@@ -301,6 +301,8 @@ dt.shuffle(seed=42)
 dt sample data.jsonl --num=10
 dt sample data.csv --num=100 --sample_type=head
 dt sample data.jsonl 1000 --by=category           # 分层采样
+dt sample data.jsonl 1000 --by=meta.source        # 按嵌套字段分层采样
+dt sample data.jsonl 1000 --by=messages.#         # 按消息数量分层采样
 
 # 数据转换 - 预设模式
 dt transform data.jsonl --preset=openai_chat
@@ -317,25 +319,30 @@ dt run pipeline.yaml --input=new_data.jsonl --output=result.jsonl
 
 # Token 统计
 dt token-stats data.jsonl --field=messages --model=gpt-4
+dt token-stats data.jsonl --field=messages[-1].content   # 统计最后一条消息
 dt token-stats data.jsonl --field=text --detailed
 
 # 数据对比
 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 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                 # 删除指定字段
 dt clean data.jsonl --strip                         # 去除字符串首尾空白
-dt clean data.jsonl --strip --drop-empty=text --min-len=text:10 -o clean.jsonl  # 组合使用
 
 # 数据去重
 dt dedupe data.jsonl                            # 全量精确去重
 dt dedupe data.jsonl --key=text                 # 按字段精确去重
+dt dedupe data.jsonl --key=meta.id              # 按嵌套字段去重
+dt dedupe data.jsonl --key=messages[0].content  # 按第一条消息内容去重
 dt dedupe data.jsonl --key=text --similar=0.8   # 相似度去重
 
 # 文件拼接
@@ -345,6 +352,44 @@ dt concat a.jsonl b.jsonl -o merged.jsonl
 dt stats data.jsonl
 ```
 
+### 字段路径语法
+
+CLI 命令中的字段参数支持嵌套路径语法，可访问深层嵌套的数据：
+
+| 语法 | 含义 | 示例 |
+|------|------|------|
+| `a.b.c` | 嵌套字段 | `meta.source` |
+| `a[0].b` | 数组索引 | `messages[0].role` |
+| `a[-1].b` | 负索引 | `messages[-1].content` |
+| `a.#` | 数组长度 | `messages.#` |
+| `a[*].b` | 展开所有元素 | `messages[*].role` |
+| `a[*].b:join` | 展开并用 `\|` 拼接 | `messages[*].role:join` |
+| `a[*].b:unique` | 展开去重后拼接 | `messages[*].role:unique` |
+
+支持字段路径的命令参数：
+
+| 命令 | 参数 | 示例 |
+|------|------|------|
+| `sample` | `--by=` | `--by=meta.source`、`--by=messages.#` |
+| `dedupe` | `--key=` | `--key=meta.id`、`--key=messages[0].content` |
+| `clean` | `--drop-empty=` | `--drop-empty=meta.source` |
+| `clean` | `--min-len=` | `--min-len=messages.#:2` |
+| `clean` | `--max-len=` | `--max-len=messages[-1].content:500` |
+| `token-stats` | `--field=` | `--field=messages[-1].content` |
+| `diff` | `--key=` | `--key=meta.uuid` |
+
+示例数据：
+```json
+{"meta": {"source": "wiki"}, "messages": [{"role": "user", "content": "hi"}, {"role": "assistant", "content": "hello"}]}
+```
+
+- `meta.source` → `"wiki"`
+- `messages[0].role` → `"user"`
+- `messages[-1].content` → `"hello"`
+- `messages.#` → `2`
+- `messages[*].role` → `"user"` (默认取第一个)
+- `messages[*].role:join` → `"user|assistant"`
+
 ### Pipeline 配置
 
 使用 YAML 配置文件定义可复现的数据处理流程：

{dtflow-0.3.2.dist-info → dtflow-0.4.1.dist-info}/RECORD

@@ -1,14 +1,14 @@
-dtflow/__init__.py,sha256=y9dtGAyVkhCMxND5BF6oYkvw-jLX4pSIFpOAcCGZZ18,2347
+dtflow/__init__.py,sha256=Gd9Us_BDXaxmMIGlz51E6OZDohqzweOrvB-2j8k3KVs,2347
 dtflow/__main__.py,sha256=7lKluJTruDPN4CKSK2mWLUxSUlVLtkrqXyRMjlGk7SY,10595
 dtflow/converters.py,sha256=gyy-K15zjzGBawFnZa8D9JX37JZ47rey2GhjKa2pxFo,22081
-dtflow/core.py,sha256=AeIomI38wfTR6lZjBHG2a3RcI06xVMF0VIB3N0P0ty8,27849
+dtflow/core.py,sha256=szm9qmRVe1Q97O18UTGz7xTsdV-V8L4D6Bl1bxBJCWk,28778
 dtflow/lineage.py,sha256=vQ06lxBHftu-Ma5HlISp3F2eiIvwagQSnUGaLeABDZY,12190
 dtflow/pipeline.py,sha256=zZaC4fg5vsp_30Fhbg75vu0yggsdvf28bWBiVDWzZ6Y,13901
 dtflow/presets.py,sha256=OP1nnM5NFk5Kli9FsXK0xAot48E5OQ6-VOIJT9ffXPg,5023
-dtflow/streaming.py,sha256=O8waTXDOEk_6ES_H3-TKTc3zyc-EC8DjOfgepAKV96A,21556
-dtflow/tokenizers.py,sha256=ToK_5O8PZeOtkeUHcMwkv7C650_OYbEziqaTnm1rPtY,17882
+dtflow/streaming.py,sha256=lYf9gi5U-3oqr7oEe5mENx1r-LtRb2YfGNq1fP3_sw4,21972
+dtflow/tokenizers.py,sha256=zxE6XZGjZ_DOGCjRSClI9xaAbFVf8FS6jwwssGoi_9U,18111
 dtflow/cli/__init__.py,sha256=QhZ-thgx9IBTFII7T_hdoWFUl0CCsdGQHN5ZEZw2XB0,423
-dtflow/cli/commands.py,sha256=SBI-BbtWUmLPS05fiOB_g2THNxeU7KAg9IUrK0l5K8M,82291
+dtflow/cli/commands.py,sha256=8t_HgFuFqGt1HXPpEDV47qB2fwMD5C6d9Bjj-VNb37I,84958
 dtflow/mcp/__init__.py,sha256=huEJ3rXDbxDRjsLPEvjNT2u3tWs6Poiv6fokPIrByjw,897
 dtflow/mcp/__main__.py,sha256=PoT2ZZmJq9xDZxDACJfqDW9Ld_ukHrGNK-0XUd7WGnY,448
 dtflow/mcp/cli.py,sha256=ck0oOS_642cNktxULaMRE7BJfMxsBCwotmCj3PSPwVk,13110
@@ -16,9 +16,10 @@ dtflow/mcp/docs.py,sha256=DI2Vf-eFo4chRP_bDLsv4Uc3kJt8_1emz8N-NBSVirM,8834
 dtflow/mcp/server.py,sha256=Nf0UlqDGhV55ndGuEglfr7VRjDWAC_9rRsNhdr0-ssM,4275
 dtflow/storage/__init__.py,sha256=C0jpWNQU808Ezz7lWneddABal3wILy8ijFUNiSKbHV4,362
 dtflow/storage/io.py,sha256=XNWLL10a7jgOjM1IfTN9kIuW23dwzFE1nnaw4E3LaiU,21885
-dtflow/utils/__init__.py,sha256=0m2xpYzUalb2zwnI902y8ouZloAweeYsnt-junmmW18,115
+dtflow/utils/__init__.py,sha256=f8v9HJZMWRI5AL64Vjr76Pf2Na_whOF9nJBKgPbXXYg,429
 dtflow/utils/display.py,sha256=OeOdTh6mbDwSkDWlmkjfpTjy2QG8ZUaYU0NpHUWkpEQ,5881
-dtflow-0.3.2.dist-info/METADATA,sha256=2hPiTeRUYRjzLP4W0z5ycYQEZpZY2klWmKCunxle_SA,16326
-dtflow-0.3.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-dtflow-0.3.2.dist-info/entry_points.txt,sha256=dadIDOK7Iu9pMxnMPBfpb4aAPe4hQbBOshpQYjVYpGc,44
-dtflow-0.3.2.dist-info/RECORD,,
+dtflow/utils/field_path.py,sha256=WcNA-LZh3H61a77FEzB_R7YAyyZl3M8ofdq05ytQGmI,7459
+dtflow-0.4.1.dist-info/METADATA,sha256=-rdgDNFMy3pPO5mpMcKlB_quxSlD9mUIoe_tIUXoPP4,18306
+dtflow-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dtflow-0.4.1.dist-info/entry_points.txt,sha256=dadIDOK7Iu9pMxnMPBfpb4aAPe4hQbBOshpQYjVYpGc,44
+dtflow-0.4.1.dist-info/RECORD,,