chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/planning/dbc_defaults.py

@@ -0,0 +1,88 @@
+"""仅在信号省略类型/单位或enum映射时读取DBC元数据，不读取报文。
+
+每次计划编译按DBC路径共用一次加载；结果冻结为已有SignalDefinition字段。
+数值信号不会因存在VAL表而变成文字枚举。重新加载配置才重新推导默认值。
+"""
+from .checks import PlanValidationError
+from ..legacy.binding import dbc_candidates
+from ..can_dependencies import CANDependencyError, import_can_dependency
+
+
+def _numeric_dtype(signal):
+    """按解码后的数值范围选类型；有浮点缩放就使用float64，不丢弃小数。"""
+    if signal.is_float or type(signal.scale) is not int or type(signal.offset) is not int:
+        return 'float64'
+    low = -(2**(signal.length-1)) if signal.is_signed else 0
+    high = 2**(signal.length-1)-1 if signal.is_signed else 2**signal.length-1
+    limits = sorted((low*signal.scale+signal.offset, high*signal.scale+signal.offset))
+    if -(2**63) <= limits[0] and limits[1] < 2**63:
+        return 'int64'
+    if 0 <= limits[0] and limits[1] < 2**64:
+        return 'uint64'
+    raise ValueError('DBC缩放后的整数超出64位，请显式选择dtype并核对数值范围')
+
+
+def _enum_choices(signal):
+    """把DBC原码表转换到既有解码值域，不对实际记录再施加一次DBC缩放。"""
+    if not signal.choices:
+        raise ValueError('DBC没有该信号的枚举表，请提供choices或选择数值dtype')
+    result = []
+    for code, label in signal.choices.items():
+        value = signal.conversion.raw_to_scaled(code, decode_choices=False)
+        # 核心枚举编码保持int/bool/str契约；不把浮点物理值截断成整数码。
+        if type(value) is not int or signal.is_float:
+            raise ValueError('DBC枚举缩放产生浮点值，当前枚举编码不支持；请使用数值dtype，不会截断或重复缩放')
+        text = str(label)
+        if not text:
+            raise ValueError('DBC枚举标签为空，请提供明确choices')
+        result.append([value,text])
+    return result
+
+
+class DBCDefaults:
+    """一次计划编译内的临时数据库缓存，显式完整声明不打开DBC。"""
+    def __init__(self):
+        """创建空缓存，不访问磁盘。"""
+        self.databases = {}
+
+    def fill(self, raw, config, field, path):
+        """参数为信号配置、CAN来源和定位；返回补默认值的独立dict，错误定位到信号。"""
+        result = dict(raw)
+        # 手工映射已明确标签类型，可以直接得出逻辑dtype，不读取DBC作第二次猜测。
+        choices = result.get('choices')
+        if 'dtype' not in result and type(choices) is list and choices:
+            if all(type(pair) is list and len(pair)==2 and type(pair[1]) is str for pair in choices):
+                result['dtype']='enum'
+            elif all(type(pair) is list and len(pair)==2 and type(pair[1]) is bool for pair in choices):
+                result['dtype']='bool'
+        needed = [key for key in ('dtype','unit') if key not in result]
+        if result.get('dtype') == 'enum' and 'choices' not in result:
+            needed.append('choices')
+        if not needed:
+            return result
+        try:
+            key = str(config.dbc_path)
+            if key not in self.databases:
+                cantools = import_can_dependency('cantools')
+                self.databases[key] = cantools.database.load_file(key)
+            candidates = dbc_candidates(self.databases[key],field.frame_id,(field.signal,),field.is_extended,field.is_fd)
+            signals = [next(s for s in message.signals if s.name==field.signal) for message in candidates]
+            for name in needed:
+                if name == 'dtype':
+                    values = [_numeric_dtype(signal) for signal in signals]
+                elif name == 'unit':
+                    # 无单位定义时标未知，不冒称已核实为V/A或无量纲。
+                    values = [signal.unit or ('1' if result.get('dtype') in ('enum','bool') else 'unknown') for signal in signals]
+                else:
+                    values = [_enum_choices(signal) for signal in signals]
+                if any(value != values[0] for value in values[1:]):
+                    raise ValueError(f'候选DBC的{name}不同，请补充帧类型或显式{name}')
+                result[name] = values[0]
+        except CANDependencyError as error:
+            # 这是来源的安装环境缺项，不要求用户反复修改当前信号字段。
+            raise PlanValidationError('$.sources', str(error), error.code,
+                hint=error.hint, object_name='来源 ' + config.name) from error
+        except Exception as error:
+            # 不吞文件/解析错误，不用猜测值替代无法读取的元数据。
+            raise PlanValidationError(path,'无法从DBC补充信号声明：'+str(error)) from error
+        return result

chronaxis/planning/export_options.py

@@ -0,0 +1,247 @@
+"""解释独立的信号CSV和CAN报文输出选项，默认均关闭。
+
+只构造已实现低层导出的类型化规格；不加载DBC、不读取输入或输出文件。
+信号分类使用明确别名，报文重建用明确原字段，范围引用既有会话或窗口。
+日期规则按用户确认检查，未支持的选项严格拒绝，不让schema接受空实现。
+"""
+
+from dataclasses import dataclass
+
+from ..core.types import SignalDType
+from ..results.signal_exports import SignalCSVExportSpec
+from ..results.signal_grid import SignalGridSpec
+from ..results.frame_exports import FrameExportSpec
+from ..results.frame_rebuild import FrameGridSpec
+from ..results.frame_patch import FrameRebuildRule
+from .checks import (PlanValidationError,array_at,choice_at,coordinate_at,duration_at,model_at,object_at,text_at)
+from ..core.validation import require_identifier
+
+
+@dataclass(frozen=True)
+class SignalCSVOutput:
+    """保存信号表输出规格及范围，不拥有运行时历史或文件。"""
+
+    spec: SignalCSVExportSpec
+    scope: str = 'session'
+    window: str | None = None
+    period_driver: str | None = None  # 仅DBC信号网格，已解析的原始报文别名。
+
+    def __post_init__(self):
+        """校验冻结声明，typed构造同样受约束。参数: 字段。返回: None。异常: 类型/范围错。
+        """
+        if type(self.spec) is not SignalCSVExportSpec:
+            raise TypeError('signal_csv需要SignalCSVExportSpec')
+        _typed_scope(self.scope,self.window)
+        if self.period_driver is not None:
+            require_identifier(self.period_driver,'signal_csv.resampling.period.driver')
+        if (self.period_driver is not None)!=(self.spec.resampling is not None and self.spec.resampling.period_ns is None):
+            raise ValueError('DBC信号网格需要已解析驱动，固定网格不能附带驱动')
+
+
+@dataclass(frozen=True)
+class CANFramesOutput:
+    """保存一个来源的原始/重建帧输出规格，与信号表的网格和开关独立。"""
+
+    source: str
+    spec: FrameExportSpec
+    scope: str = 'session'
+    window: str | None = None
+    resampling: FrameGridSpec | None = None
+    rules: tuple[FrameRebuildRule,...] = ()
+
+    def __post_init__(self):
+        """校验来源、独立规格和重建规则。参数: 字段。返回: None。异常: 类型/范围错。
+        """
+        require_identifier(self.source,'can_frames.source'); _typed_scope(self.scope,self.window,allow_all=True)
+        if type(self.spec) is not FrameExportSpec or self.resampling is not None and type(self.resampling) is not FrameGridSpec:
+            raise TypeError('can_frames需要冻结帧规格与可选网格')
+        if type(self.rules) is not tuple or len(self.rules)>4096 or any(type(r) is not FrameRebuildRule for r in self.rules):
+            raise TypeError('重建规则需要有限FrameRebuildRule tuple')
+        if self.rules and self.resampling is None:
+            raise ValueError('未启用重采样不能配置重建规则')
+        identities={(r.channel,r.frame_id,r.is_extended,r.is_fd) for r in self.rules}
+        if len(identities)!=len(self.rules) or self.resampling is not None and not self.rules and self.resampling.unknown_policy!='nearest':
+            raise ValueError('重建规则重复或没有可执行规则')
+
+
+def _typed_scope(scope,window,*,allow_all=False):
+    """核typed范围与窗口配对。参数: scope/window。返回: None。异常: 不支持或组合错误。
+    """
+    if scope not in ('session','segments') or scope=='session' and window is not None:
+        raise ValueError('导出范围错误')
+    if scope=='segments' and not (allow_all and window is None):
+        require_identifier(window,'exports.window')
+
+
+def require_export_options(plan):
+    """核typed选项引用当前来源/信号/窗口，不读DBC。参数: plan。返回: None。异常: 声明或引用错误。
+    """
+    windows={w.window_id for w in plan.windows}; definitions={s.definition.name:s.definition for s in plan.signals}
+    for export_type,expected in (('signal_csv',SignalCSVOutput),('can_frames',CANFramesOutput)):
+        option=getattr(plan.outputs,export_type)
+        if option is None:
+            continue
+        if type(option) is not expected:
+            raise TypeError(export_type+'需要冻结typed输出声明')
+        option.__post_init__()
+        if option.scope=='segments' and not ((export_type=='can_frames') and (option.window is None)) and option.window not in windows:
+            raise ValueError('导出窗口未在当前计划声明')
+        if export_type=='signal_csv':
+            if any(name not in definitions for name in option.spec.signals):
+                raise ValueError('导出信号未在当前计划声明')
+            if option.spec.resampling is not None and any(definitions[name].dtype not in
+                    (SignalDType.FLOAT64,SignalDType.INT64,SignalDType.UINT64) for name in option.spec.resampling.continuous):
+                raise ValueError('状态/枚举信号不能线性插值')
+            if option.period_driver is not None:
+                _signal_grid_driver(definitions,plan.sources,option.spec.resampling.continuous,option.period_driver,'$.outputs.signal_csv')
+        else:
+            source=next((s for s in plan.sources if s.name==option.source),None)
+            if source is None or source.source_type not in ('can_blf','can_asc','asc_or_blf','raw_can_csv'):
+                raise ValueError('报文导出需要本计划CAN来源')
+            _require_frame_direction(source)
+            if any(rule.channel!=source.config.channel for rule in option.rules):
+                raise ValueError('重建报文通道与来源不同')
+
+
+def _scope(raw,path,windows,*,allow_all=False):
+    """核会话或单个显式窗口引用。参数: raw/path/windows。返回: (scope,window)。异常: 配置错。
+    """
+    scope=choice_at(raw.get('scope','session'),('session','segments'),path+'.scope')
+    window=raw.get('window')
+    if scope=='session' and window is not None:
+        raise PlanValidationError(path+'.window','session范围不能同时指定窗口')
+    if scope=='segments' and not (allow_all and 'window' not in raw):
+        window=text_at(window,path+'.window',identifier=True)
+        if window not in {item.window_id for item in windows}:
+            raise PlanValidationError(path+'.window','未知窗口：'+window)
+    return scope,window
+
+
+def _grid(raw,path):
+    """解析显式单位的全局网格。参数: raw/path。返回: period/origin/max_gap整数ns。异常: 时间错。
+    """
+    return (duration_at(raw['period'],path+'.period',positive=True),
+        coordinate_at(raw.get('origin','0s'),path+'.origin'),duration_at(raw['max_gap'],path+'.max_gap',positive=True))
+
+
+def _signal_grid_driver(definitions,sources,continuous,driver,path):
+    """同一信号网格使用一个明确DBC周期；多报文不能擅自选最快周期。
+
+    参数: 有限定义/来源/连续量/可选驱动/路径。返回: 唯一原始别名。异常: 类型/格式/歧义。
+    """
+    from ..sources.can_spec import can_field_from_key
+    source_types={source.name:source.source_type for source in sources}
+    candidates={}
+    for name in continuous:
+        definition=definitions[name]
+        if source_types[definition.source] not in ('can_blf','can_asc','asc_or_blf','raw_can_csv'):
+            raise PlanValidationError(path+'.resampling.period','已解析信号不能选择DBC周期')
+        field=can_field_from_key(definition.field)
+        candidates.setdefault((definition.source,field.channel,field.frame_id,field.is_extended,field.is_fd),name)
+    if driver is not None:
+        if type(driver) is not str or driver not in continuous:
+            raise PlanValidationError(path+'.resampling.period.driver','驱动须属于本次连续原始信号')
+        return driver
+    if len(candidates)!=1:
+        raise PlanValidationError(path+'.resampling.period.driver','多个报文周期需要明确指定驱动信号')
+    return next(iter(candidates.values()))
+
+
+def parse_signal_output(value,signals,windows,*,sources=()):
+    """核显式信号选择及连续量分类。参数: value、当前信号/窗口。返回: SignalCSVOutput或None。异常: 定位配置错。
+    """
+    if value is None:
+        return None
+    path='$.outputs.signal_csv'
+    raw=object_at(value,path,('signals',),('scope','window','resampling'))
+    names=tuple(array_at(raw['signals'],path+'.signals'))
+    definitions={s.definition.name:s.definition for s in signals}
+    if any(type(n) is not str or n not in definitions for n in names):
+        raise PlanValidationError(path+'.signals','导出信号必须为已定义的原信号别名')
+    grid=None;driver=None
+    if raw.get('resampling') is not None:
+        res=object_at(raw['resampling'],path+'.resampling',('continuous','period','max_gap'),('origin',))
+        continuous=tuple(array_at(res['continuous'],path+'.resampling.continuous'))
+        if any(type(n) is not str or n not in definitions or definitions[n].dtype not in
+                (SignalDType.FLOAT64,SignalDType.INT64,SignalDType.UINT64) for n in continuous):
+            raise PlanValidationError(path+'.resampling.continuous','连续量必须为当前已定义的数值信号，状态/枚举不能插值')
+        if type(res['period']) is dict:
+            period_choice=object_at(res['period'],path+'.resampling.period',('mode',),('driver',))
+            if 'driver' in period_choice and type(period_choice['driver']) is not str:
+                raise PlanValidationError(path+'.resampling.period.driver','显式driver必须为信号名称')
+            if period_choice['mode']!='dbc':raise PlanValidationError(path+'.resampling.period.mode','网格对象需dbc，固定周期使用带单位数值')
+            driver=_signal_grid_driver(definitions,sources,continuous,period_choice.get('driver'),path)
+            period=None
+            origin=coordinate_at(res.get('origin','0s'),path+'.resampling.origin')
+            gap=duration_at(res['max_gap'],path+'.resampling.max_gap',positive=True)
+        else:
+            period,origin,gap=_grid(res,path+'.resampling')
+        grid=model_at(SignalGridSpec,path+'.resampling',continuous,period,origin,gap)
+    spec=model_at(SignalCSVExportSpec,path,names,grid)
+    scope,window=_scope(raw,path,windows)
+    return SignalCSVOutput(spec,scope,window,driver)
+
+
+def _require_frame_direction(source):
+    """只有原帧导出/重建需要收发方向；分析可保留未知方向。"""
+    if source.source_type == 'raw_can_csv' and any(
+            'is_rx' not in item.layout.fields for item in source.config.inputs):
+        raise PlanValidationError('$.outputs.can_frames',
+            '原始报文导出或重建需要收发方向，请在CSV字段映射中提供is_rx；普通分析可以省略')
+
+
+def parse_frame_output(value,sources,windows):
+    """核帧来源、日期和可选重建规则。参数: value、当前来源/窗口。返回: CANFramesOutput或None。异常: 定位配置错。
+    """
+    if value is None:
+        return None
+    path='$.outputs.can_frames'
+    raw=object_at(value,path,('format',),('source','scope','window','resampling','output_offset',
+        'source_time_reference','capture_date','timezone_offset_minutes'))
+    from .input_defaults import source_reference
+    source=source_reference(raw,sources,path,can_only=True)
+    declared=next((s for s in sources if s.name==source),None)
+    if declared is None or declared.source_type not in ('can_blf','can_asc','asc_or_blf','raw_can_csv'):
+        raise PlanValidationError(path+'.source','报文导出需要当前已支持的CAN来源')
+    _require_frame_direction(declared)
+    reference=raw.get('source_time_reference','epoch' if declared.config.timebase.time_type.value=='absolute' else 'relative')
+    spec=model_at(FrameExportSpec,path,choice_at(raw['format'],('asc','blf'),path+'.format'),
+        coordinate_at(raw.get('output_offset','0s'),path+'.output_offset'),reference,
+        raw.get('capture_date'),raw.get('timezone_offset_minutes'))
+    scope,window=_scope(raw,path,windows,allow_all=True)
+    grid=None; rules=[]
+    if raw.get('resampling') is not None:
+        res=object_at(raw['resampling'],path+'.resampling',('period','max_gap','messages'),
+            ('origin','unknown_policy','max_distance'))
+        if type(res['period']) is dict:
+            choice=object_at(res['period'],path+'.resampling.period',('mode',),())
+            if (choice['mode']!='dbc'):
+                raise PlanValidationError(path+'.resampling.period','按各报文DBC周期重采样时，period.mode必须为dbc')
+            period=None
+            origin=coordinate_at(res.get('origin','0s'),path+'.resampling.origin')
+            gap=duration_at(res['max_gap'],path+'.resampling.max_gap',positive=True)
+        else:
+            period,origin,gap=_grid(res,path+'.resampling')
+        distance=duration_at(res['max_distance'],path+'.resampling.max_distance',positive=False) if 'max_distance' in res else None
+        grid=model_at(FrameGridSpec,path+'.resampling',period,origin,gap,res.get('unknown_policy','passthrough'),distance)
+        for index,item in enumerate(array_at(res['messages'],path+'.resampling.messages')):
+            where=f'{path}.resampling.messages[{index}]'
+            item=object_at(item,where,('frame_id','continuous'),('channel','is_extended','is_fd','protected','same_time_policy'))
+            # 省略表示自动识别；显式null不能悄悄取得默认行为。
+            for flag in ('is_extended','is_fd'):
+                if flag in item and type(item[flag]) is not bool:
+                    raise PlanValidationError(where+'.'+flag,'填写时需要bool；自动识别请省略该项')
+            from .channels import channel_index
+            channel = channel_index(item['channel'],where+'.channel') if 'channel' in item else declared.config.channel
+            rule=model_at(FrameRebuildRule,where,channel,item['frame_id'],
+                tuple(array_at(item['continuous'],where+'.continuous')),item.get('is_extended'),item.get('is_fd'),
+                tuple(array_at(item.get('protected',[]),where+'.protected')),item.get('same_time_policy','error'))
+            if rule.channel!=declared.config.channel:
+                raise PlanValidationError(where+'.channel','重建规则通道必须匹配来源的DBC通道')
+            rules.append(rule)
+        identities=[(r.channel,r.frame_id,r.is_extended,r.is_fd) for r in rules]
+        if len(rules)>4096 or len(set(identities))!=len(rules):
+            raise PlanValidationError(path+'.resampling.messages','报文规则重复或超过4096项')
+        if not rules and grid.unknown_policy!='nearest':
+            raise PlanValidationError(path+'.resampling.messages','重建需明确报文清单或未知报文最近邻策略')
+    return CANFramesOutput(source,spec,scope,window,grid,tuple(rules))

chronaxis/planning/input_defaults.py

@@ -0,0 +1,62 @@
+"""补齐来源的常用声明，只有唯一候选时自动选择引用。
+
+输入为已检查JSON结构的配置；输出独立字典或来源名称。不打开数据/DBC，
+不改输入值和时间戳。相对时间缺省采用来源专属基准，不声称多来源已经同步。
+"""
+
+# 仅用路径后缀识别自描述的CAN文件；格式正文仍由原读取器严格检查。
+from pathlib import Path
+from .checks import PlanValidationError, array_at, object_at, text_at
+
+
+def source_defaults(raw, index, *, inferred_type=None):
+    """补来源名、ASC/BLF格式及时间默认值，不修改调用方字典。
+
+    参数: raw为单来源字典，index为零基来源序号；inferred_type为已编译来源类型。
+    返回: 新字典；已有计划的调用方可避免重复展开目录。
+    异常: PlanValidationError表示未知格式、显式空时间或非法名称。
+    """
+    # 自动名只作当前计划内定位，重名由原来源解析器统一拒绝。
+    result = dict(raw)
+    path = f'$.sources[{index}]'
+    result.setdefault('name', f'source_{index + 1}')
+    name = text_at(result['name'], path + '.name', identifier=True)
+    if inferred_type is not None and ('source_type' not in result or result['source_type'] == 'asc_or_blf'):
+        result['source_type'] = inferred_type
+    if inferred_type is None and ('source_type' not in result or result['source_type'] == 'asc_or_blf'):
+        # 这里只识别明确文件后缀；目录展开由文件输入节点实施，CSV必须声明含义。
+        paths = [result['path']] if 'path' in result else array_at(result.get('paths', []), path + '.paths')
+        suffixes = {Path(text_at(item, f'{path}.paths[{i}]')).suffix.lower() for i, item in enumerate(paths)}
+        if not paths or not suffixes <= {'.asc', '.blf'}:
+            raise PlanValidationError(path + '.source_type',
+                '无法唯一识别ASC/BLF格式；CSV或内存输入请明确source_type')
+        result['source_type'] = ('can_asc' if suffixes == {'.asc'} else
+            'can_blf' if suffixes == {'.blf'} and 'offsets' not in result else 'asc_or_blf')
+    # 不用“or {}”吞掉显式null；用户输入的错误必须仍然报出。
+    clock = dict(object_at(result.get('time', {}), path + '.time', (),
+                          ('time_type', 'unit', 'origin', 'offset', 'timezone', 'timezone_offset_minutes')))
+    clock.setdefault('time_type', 'relative')
+    if result['source_type'] in ('can_blf', 'can_asc', 'asc_or_blf', 'memory'):
+        clock.setdefault('unit', 's')
+    if clock['time_type'] == 'relative':
+        # 缺省基准带来源名，不让独立采集的来源因共同默认字符串而被视为已同步。
+        clock.setdefault('origin', '__source_' + name)
+    result['time'] = clock
+    return result
+
+
+def source_reference(raw, sources, path, *, can_only=False):
+    """取显式来源名，或选择唯一适用来源；多候选不选第一项。
+
+    参数: raw为含可选source的对象，sources为来源计划序列，path为对象位置，
+        can_only限定原始CAN来源。返回: 来源名称字符串。
+    异常: PlanValidationError表示无候选、多候选或非法显式名称。
+    """
+    if 'source' in raw:
+        # 显式null/空串不表示自动，原名称检查仍生效。
+        return text_at(raw['source'], path + '.source', identifier=True)
+    candidates = [item.name for item in sources if not can_only or
+                  item.source_type in ('can_blf', 'can_asc', 'asc_or_blf', 'raw_can_csv')]
+    if len(candidates) != 1:
+        raise PlanValidationError(path + '.source', '请指定source；适用来源：' + ', '.join(candidates))
+    return candidates[0]

chronaxis/planning/input_paths.py

@@ -0,0 +1,124 @@
+"""将文件、目录或通配符展开为有序输入，不读取报文内容。
+
+明确文件列表保持用户顺序；每个目录或通配符内部采用自然排序。
+只枚举显式请求的目录，不递归追踪子目录；递归必须通过**通配符提出。
+展开最多4096项，空匹配及无效路径报配置错误，不悄悄跳过缺失目录。
+"""
+
+from glob import iglob
+from pathlib import Path
+import re
+
+from .checks import PlanValidationError, absolute_path, array_at, coordinate_at, object_at, text_at
+
+# 明确后缀的文件只做词法定位，保持现有静态配置不访问业务文件的行为。
+FILE_SUFFIXES = frozenset(('.asc', '.blf', '.csv', '.txt'))
+SOURCE_SUFFIXES = {'can_blf': {'.blf'}, 'can_asc': {'.asc'},
+                   'raw_can_csv': {'.csv', '.txt'}, 'signal_csv': {'.csv', '.txt'}}
+MAX_INPUT_FILES = 4096
+
+
+def natural_path_key(path):
+    """产生稳定自然序键，使file2排在file10前。
+
+    参数: path为Path。返回: 数字/文字分段键及原路径平局键。
+    异常: 无主动异常；不访问文件系统。
+    """
+    text = str(path)
+    # 类型标签避免数字与文字直接比较；补原文本使01/1及大小写平局可复现。
+    parts = tuple((1, int(part)) if part.isdigit() else (0, part.casefold())
+                  for part in re.split(r'(\d+)', text))
+    return parts, text.casefold(), text
+
+
+def expand_source_files(raw, base, where):
+    """按声明展开来源路径；目录只取该来源支持的格式。
+
+    参数: raw为来源字典，base为配置文件目录，where为来源错误位置。
+    返回: (绝对Path元组, 可选逐文件偏移字符串元组)。异常: PlanValidationError表示缺项、空匹配或超限；
+        OSError由目录读取产生并转换为带配置位置的错误。
+    副作用: 仅目录/通配符声明枚举文件名；明确文件不stat、不读数据内容。
+    """
+    if ('path' in raw) == ('paths' in raw):
+        raise PlanValidationError(where, 'path与paths必须且只能提供一个')
+    key = 'path' if 'path' in raw else 'paths'
+    value = raw[key]
+    entries = [value] if type(value) in (str, dict) else array_at(value, where + '.' + key)
+    if not entries:
+        raise PlanValidationError(where + '.' + key, '至少需要一个输入文件或目录')
+    allowed = SOURCE_SUFFIXES.get(raw.get('source_type'), {'.asc', '.blf'})
+    result, shifts, has_shifts = [], [], False
+    for index, entry in enumerate(entries):
+        location = f'{where}.{key}[{index}]'
+        # 文件自己的偏移跟在同一条声明内，展开目录时该偏移作用于其中各文件。
+        shift = '0s'
+        if type(entry) is dict:
+            item = object_at(entry, location, ('path',), ('offset',))
+            text = text_at(item['path'], location + '.path')
+            if 'offset' in item:
+                coordinate_at(item['offset'], location + '.offset')
+                shift = item['offset']
+                has_shifts = True
+        else:
+            text = text_at(entry, location)
+        target = absolute_path(text, base, location)
+        # 仅*和?启动通配符模式，普通文件名中的方括号保持字面含义。
+        wildcard = any(char in text for char in '*?')
+        # 常规文件不访问磁盘；目录名像文件时可用末尾分隔符明确目录含义。
+        if not wildcard and target.suffix.lower() in FILE_SUFFIXES and not text.endswith(('/', '\\')):
+            selected = [target]
+        else:
+            selected = []
+            try:
+                candidates = (Path(item) for item in iglob(str(target), recursive='**' in text)) if wildcard else target.iterdir()
+                for candidate in candidates:
+                    if candidate.suffix.lower() in allowed and candidate.is_file():
+                        selected.append(candidate)
+                        if len(result) + len(selected) > MAX_INPUT_FILES:
+                            raise PlanValidationError(location, '输入文件超过4096项')
+            except OSError as error:
+                raise PlanValidationError(location, '无法枚举输入目录：' + str(error)) from error
+            if not selected:
+                raise PlanValidationError(location, '目录或通配符没有匹配的输入文件')
+            selected.sort(key=natural_path_key)
+        # 不重排显式列表、不合并不同声明项，也不因内容相同而删除真实文件。
+        result.extend(selected)
+        shifts.extend([shift] * len(selected))
+        if len(result) > MAX_INPUT_FILES:
+            raise PlanValidationError(location, '输入文件超过4096项')
+    if has_shifts and 'offsets' in raw:
+        raise PlanValidationError(where, '文件内offset与来源offsets不能同时填写')
+    return tuple(result), tuple(shifts) if has_shifts else None
+
+
+def expand_input_paths(raw, base, where):
+    """只取展开文件路径，供无需文件偏移的调用方使用。
+
+    参数: 来源配置、基准目录、错误位置。返回: Path元组。
+    异常: 与expand_source_files一致；目录扫描只执行一次。
+    """
+    return expand_source_files(raw, base, where)[0]
+
+
+def source_path_fields(source, where='$.sources'):
+    """枚举文件声明中的路径文字，供转换/导入工具固定路径基准。
+
+    参数: source为来源字典，where为错误位置。返回: (容器,键)迭代器。
+    异常: PlanValidationError为错误结构。不扫描目录，不改变offset或其他元数据。
+    """
+    for key in ('path', 'paths'):
+        if key not in source:
+            continue
+        value = source[key]
+        if type(value) is str:
+            yield source, key
+            continue
+        # 每项可以是路径文字或带自己偏移的文件声明，工具不能把对象转成字符串。
+        entries = [value] if type(value) is dict else array_at(value, where + '.' + key)
+        for index, item in enumerate(entries):
+            if type(item) is dict:
+                object_at(item, f'{where}.{key}[{index}]', ('path',), ('offset',))
+                yield item, 'path'
+            else:
+                text_at(item, f'{where}.{key}[{index}]')
+                yield entries, index