chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/batch/process_transport.py

@@ -0,0 +1,149 @@
+"""传递独立计划快照和小型结果，保留工作进程中的失败清理责任。
+
+管道仅连接本次创建的可信子进程，不读取外部序列化对象。计划重建后核对身份，
+大型结果在子进程内写出并关闭。清理失败的进程暂停接活，由报告句柄远程重试。
+"""
+
+from dataclasses import replace
+import multiprocessing
+import os
+from pathlib import Path
+import signal
+from threading import Event
+
+from ..planning.plan import AnalysisPlan
+from ..planning.checks import json_value
+from .models import BatchJob, BatchJobResult, CleanupHandle
+from .process_tree import ProcessTree
+
+
+def job_packet(job):
+    """提取无活动资源的计划。参数: BatchJob。返回: 原生dict。异常: 配置转换错误。"""
+    if isinstance(job.plan, Path):
+        return dict(job_id=job.job_id, path=str(job.plan.absolute()))
+    return dict(job_id=job.job_id, config=json_value(job.plan.raw_config),
+                base_dir=str(job.plan.base_dir), identity=job.plan.identity)
+
+
+def restore_job(packet):
+    """恢复独立计划。参数: 本进程收到的声明。返回: BatchJob。异常: 重建或身份不一致。"""
+    if 'path' in packet:
+        return BatchJob(packet['job_id'], Path(packet['path']))
+    plan = AnalysisPlan.from_dict(packet['config'], base_dir=packet['base_dir'])
+    if plan.identity != packet['identity']:
+        raise ValueError('跨进程重建后的计划身份不一致')
+    return BatchJob(packet['job_id'], plan)
+
+
+def worker_main(connection):
+    """处理run/cleanup/close命令。参数: 私有管道。返回: None。异常: 断管退出，父进程负责树清理。"""
+    from .runner import _run_job, _diagnostics
+    # Ctrl+C只由调度主进程接收，正在写结果的工作进程继续完整收尾。
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    recovery = None
+    try:
+        while True:
+            command = connection.recv()
+            if command[0] == 'close':
+                if recovery is not None:
+                    recovery.close()
+                return
+            if command[0] == 'cleanup':
+                try:
+                    if recovery is not None:
+                        recovery.close()
+                    recovery = None
+                    connection.send(('cleaned', None))
+                except BaseException as error:
+                    connection.send(('cleanup_failed', _diagnostics(error)))
+                continue
+            if recovery is not None:
+                raise RuntimeError('存在未关闭资源的工作进程不能接收新任务')
+            _, packet, directory, backend = command
+            try:
+                job = restore_job(packet)
+                outcome = _run_job(job, Path(directory), backend, Event(), Event())
+            except BaseException as error:
+                outcome = BatchJobResult(packet['job_id'], 'failed',
+                    plan_path=packet.get('path'), error_type=type(error).__name__,
+                    error_message=str(error), error_chain=_diagnostics(error))
+            recovery = outcome.recovery
+            pending = recovery is not None and not recovery.closed
+            # 只发送冻结的纯结果字段；CleanupHandle的原资源必须留在拥有它的进程。
+            connection.send(('result', replace(outcome, recovery=None, worker_pid=os.getpid()), pending))
+    except EOFError:
+        if recovery is not None:
+            recovery.close()
+    finally:
+        connection.close()
+
+
+class ProcessWorker:
+    """保存一个可复用工作进程、私有管道及其后代的清理责任。"""
+
+    def __init__(self):
+        """启动等待命令的spawn进程。参数: 无。返回: 新对象。异常: 启动/树登记失败立即回收。"""
+        context = multiprocessing.get_context('spawn')
+        self.connection, child = context.Pipe()
+        self.process = context.Process(target=worker_main, args=(child,), daemon=False)
+        self.tree = None
+        self.closed = False
+        self.pending = False
+        try:
+            self.process.start()
+            self.tree = ProcessTree(self.process.pid)
+        except BaseException:
+            if self.process.pid is not None:
+                self.process.terminate()
+                self.process.join()
+            self.connection.close()
+            self.process.close()
+            raise
+        finally:
+            child.close()
+        self.pid = self.process.pid
+
+    def submit(self, job, directory, backend):
+        """发送独立任务。参数: job/目录/后端。返回: None。异常: 转换或通信错误。"""
+        self.connection.send(('run', job_packet(job), str(directory), backend))
+
+    def ready(self):
+        """查询结果或异常退出。参数: 无。返回: bool。异常: 原管道错误。"""
+        try:
+            return self.connection.poll() or not self.process.is_alive()
+        except (EOFError, OSError) as error:
+            raise ChildProcessError('分析工作进程管道已断开，PID=' + str(self.pid)) from error
+
+    def receive(self):
+        """取结果并挂远程恢复句柄。参数: 无。返回: BatchJobResult。异常: 进程死亡或协议错误。"""
+        if not self.connection.poll():
+            raise ChildProcessError('分析工作进程异常退出，PID=' + str(self.pid))
+        try:
+            kind, result, self.pending = self.connection.recv()
+        except EOFError as error:
+            raise ChildProcessError('分析工作进程断开，PID=' + str(self.pid)) from error
+        if kind != 'result' or not isinstance(result, BatchJobResult):
+            raise RuntimeError('批量工作进程返回无效结果')
+        return replace(result, recovery=CleanupHandle(self) if self.pending else None)
+
+    def close(self):
+        """重试远程清理后关闭进程树。参数: 无。返回: None。异常: 清理失败保留全部所有者。"""
+        if self.closed:
+            return
+        if self.process.is_alive():
+            if self.pending:
+                self.connection.send(('cleanup',))
+                kind, detail = self.connection.recv()
+                if kind != 'cleaned':
+                    raise RuntimeError('工作进程资源尚未关闭：' + '; '.join(detail))
+                self.pending = False
+            self.connection.send(('close',))
+            self.process.join()
+        else:
+            self.process.join()
+        # 工作进程已退出后关闭作业，清除故障残余的CAN读取后代。
+        if self.tree is not None:
+            self.tree.close()
+        self.connection.close()
+        self.process.close()
+        self.closed = True

chronaxis/batch/process_tree.py

@@ -0,0 +1,72 @@
+"""将批量工作进程及其CAN读取子进程纳入同一个Windows作业对象。
+
+主进程持有唯一作业句柄；工作进程先等待派发，归属登记成功后才运行用户计划。
+关闭作业会结束残余后代，避免工作进程异常退出留下读取进程。不修改旧读取器。
+"""
+
+import ctypes
+from ctypes import wintypes
+import os
+
+
+class _BasicLimits(ctypes.Structure):
+    """对应Windows基本作业限制结构；仅设置关闭句柄时结束整个作业。"""
+
+    _fields_ = [('per_process', ctypes.c_longlong), ('per_job', ctypes.c_longlong),
+                ('flags', wintypes.DWORD), ('min_ws', ctypes.c_size_t),
+                ('max_ws', ctypes.c_size_t), ('active_limit', wintypes.DWORD),
+                ('affinity', ctypes.c_size_t), ('priority', wintypes.DWORD),
+                ('scheduling', wintypes.DWORD)]
+
+
+class _ExtendedLimits(ctypes.Structure):
+    """对应Windows扩展作业限制，未使用的资源额度保持零值。"""
+
+    _fields_ = [('basic', _BasicLimits), ('io', ctypes.c_ulonglong * 6),
+                ('process_memory', ctypes.c_size_t), ('job_memory', ctypes.c_size_t),
+                ('peak_process', ctypes.c_size_t), ('peak_job', ctypes.c_size_t)]
+
+
+class ProcessTree:
+    """持有一个工作进程树的关闭责任；当前公开结果发布仅支持Windows。"""
+
+    def __init__(self, pid):
+        """登记实际PID。参数: pid已启动但尚未派发的进程。返回: 新对象。异常: 平台或系统错误。"""
+        if os.name != 'nt':
+            raise NotImplementedError('批量进程树清理目前只验收Windows')
+        api = ctypes.WinDLL('kernel32', use_last_error=True)
+        api.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
+        api.CreateJobObjectW.restype = wintypes.HANDLE
+        api.SetInformationJobObject.argtypes = [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD]
+        api.SetInformationJobObject.restype = wintypes.BOOL
+        api.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+        api.OpenProcess.restype = wintypes.HANDLE
+        api.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
+        api.AssignProcessToJobObject.restype = wintypes.BOOL
+        api.CloseHandle.argtypes = [wintypes.HANDLE]
+        api.CloseHandle.restype = wintypes.BOOL
+        self._api, self._handle = api, api.CreateJobObjectW(None, None)
+        if not self._handle:
+            raise ctypes.WinError(ctypes.get_last_error())
+        process = None
+        try:
+            limits = _ExtendedLimits()
+            limits.basic.flags = 0x2000  # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE；不授予后代脱离权限。
+            if not api.SetInformationJobObject(self._handle, 9, ctypes.byref(limits), ctypes.sizeof(limits)):
+                raise ctypes.WinError(ctypes.get_last_error())
+            process = api.OpenProcess(0x0101, False, pid)  # SET_QUOTA | TERMINATE，用于作业分配。
+            if not process or not api.AssignProcessToJobObject(self._handle, process):
+                raise ctypes.WinError(ctypes.get_last_error())
+        except BaseException:
+            self.close()
+            raise
+        finally:
+            if process:
+                api.CloseHandle(process)
+
+    def close(self):
+        """关闭树句柄，终止残余后代。参数: 无。返回: None。异常: 关闭失败仍保留句柄供重试。"""
+        if self._handle:
+            if not self._api.CloseHandle(self._handle):
+                raise ctypes.WinError(ctypes.get_last_error())
+            self._handle = None

chronaxis/batch/publication.py

@@ -0,0 +1,41 @@
+"""关闭批量汇总JSON后独占安装正式报告，保留各任务已发布的独立输出。
+
+报告只汇总状态、身份和错误，不合并指标或把失败会话当作零结果。沿现有结果
+发布的Windows平台范围使用不覆盖rename；其他平台明确拒绝，失败暂存保留。
+"""
+
+import json
+from pathlib import Path
+import platform
+from uuid import uuid4
+from .models import BatchReport
+
+
+def write_batch_report(report: BatchReport) -> Path:
+    """发布固定汇总文件。参数: report实际结果。返回: batch_report.json路径。
+
+    异常: 类型、只读路径、未支持平台、已有目标或原文件错误；关闭失败不安装正式文件。
+    副作用: 只写本批目录的唯一暂存文件，失败不删除任务结果或覆盖已有报告。
+    """
+    if not isinstance(report, BatchReport):
+        raise TypeError('需要BatchReport')
+    root = report.output_dir.absolute()
+    # 本函数也可独立调用；不能仅依赖调度器已经检查过模型中的路径。
+    if any(p.casefold() == 'refprojects' for p in (*root.parts, *root.resolve().parts)):
+        raise ValueError('批量报告不能位于RefProjects')
+    if platform.system() != 'Windows':
+        raise NotImplementedError('批量报告原子发布目前只验收Windows')
+    destination = root / 'batch_report.json'
+    try:
+        destination.lstat()
+    except FileNotFoundError:
+        pass
+    else:
+        raise FileExistsError('批量报告已存在，拒绝覆盖：' + str(destination))
+    temporary = root / ('.batch-report-' + uuid4().hex + '.incomplete.json')
+    # 编码、写入和真实close全部成功才安装；Windows rename在目标已存在时拒绝。
+    with temporary.open('x', encoding='utf-8', newline='') as stream:
+        json.dump(report.to_dict(), stream, ensure_ascii=False, allow_nan=False, indent=2)
+        stream.write('\n')
+    temporary.rename(destination)
+    return destination

chronaxis/batch/runner.py

@@ -0,0 +1,236 @@
+"""在外层多进程执行独立计划，复用公共AnalysisRunner完成分析、发布和关闭。
+
+每个任务拥有自己的RunSession、预算和目录；不拆分一个会话的时间轴，不共用
+活动、迟滞或配对状态。最多process_count个future在途，未开始的任务不读计划文件。
+取消或fail_fast停止派发，已经开始的任务正常完成关闭；不向工作进程注入异常。
+只承诺每任务原有预算及同时运行数，不承诺全进程RSS或固定进程数带来的性能收益。
+"""
+
+from dataclasses import replace
+import time
+import os
+from pathlib import Path
+from threading import Event
+from time import perf_counter
+
+from ..planning import load_analysis_plan
+from ..planning.plan import AnalysisPlan
+from ..runner import AnalysisRunner
+from ..results.spool import _cleanup_owner
+from .models import BatchJob, BatchJobResult, BatchReport, CleanupHandle
+
+
+def _new_root(value) -> Path:
+    """检查批量新目录。参数: value为str/Path。返回: 绝对Path。异常: 类型/已有/只读路径错误。"""
+    if not isinstance(value, (str, Path)):
+        raise TypeError('批量输出需要str或Path')
+    path = Path(value).absolute()
+    # 检查词法和实际路径；悬空链接也按已存在拒绝，不能跟随到其目标。
+    if any(p.casefold() == 'refprojects' for p in (*path.parts, *path.resolve().parts)):
+        raise ValueError('批量输出不能位于RefProjects')
+    try:
+        path.lstat()
+    except FileNotFoundError:
+        return path
+    raise FileExistsError('批量输出已存在：' + str(path))
+
+
+def _facts(job, plan=None) -> dict:
+    """区分配置和输入事实。参数: job原声明；plan可选已加载计划。返回: 字段dict。异常: 无。"""
+    loaded = plan if plan is not None else job.plan if isinstance(job.plan, AnalysisPlan) else None
+    result = dict(job_id=job.job_id, plan_path=str(job.plan.absolute()) if isinstance(job.plan, Path) else None)
+    if loaded is not None:
+        result.update(plan_identity=loaded.identity, dataset_id=loaded.dataset.dataset_id,
+                      entity_id=loaded.dataset.entity, session_id=loaded.dataset.session_id,
+                      memory_budget_bytes=loaded.execution.memory_budget_bytes)
+    return result
+
+
+def _diagnostics(error) -> tuple[str, ...]:
+    """保留有限异常链而不持有栈。参数: error原异常。返回: 文本tuple。异常: 原异常格式错误。"""
+    seen, details = set(), []
+    while error is not None and id(error) not in seen:
+        seen.add(id(error))
+        details.append(type(error).__name__ + ': ' + str(error))
+        details.extend(getattr(error, '__notes__', ()))
+        error = error.__cause__
+    return tuple(details)
+
+
+def _cancelled(job, reason) -> BatchJobResult:
+    """记录未启动取消。参数: job原声明；reason原因。返回: 取消结果。异常: 无，不读取计划。"""
+    return BatchJobResult(**_facts(job), status='cancelled', error_type='not_started', error_message=reason)
+
+
+def _report(root, jobs, results, process_count, fail_fast, cancelled, label, reason) -> BatchReport:
+    """补齐未启动项。参数: 原声明/结果及调度选项。返回: 完整报告。异常: 模型错误。"""
+    outcomes = tuple(_cancelled(job, reason) if value is None else value
+                     for job, value in zip(jobs, results))
+    # worker中的真实KeyboardInterrupt也属于取消请求，不只记录主线程的Event。
+    requested = cancelled or any(j.error_type in ('KeyboardInterrupt', 'SystemExit') for j in outcomes)
+    return BatchReport(root, outcomes, process_count, fail_fast, requested, label)
+
+
+def _run_job(job, directory, backend, stop, cancel) -> BatchJobResult:
+    """执行一个独立任务并关闭所有资源。
+
+    参数: job为BatchJob；directory为独占新子目录；backend为覆盖；stop/cancel为Event。
+    返回: 含实际发布和身份的最终结果；恢复失败保最高owner，不把异常栈留在结果中。
+    异常: 普通分析/发布/取消转换成该任务结果；无法构造结果的内部错误交由调度器收尾。
+    """
+    if stop.is_set() or cancel.is_set():
+        return _cancelled(job, '任务启动前已停止派发')
+    started = perf_counter()
+    plan = result = manifest = recovery = None
+    metadata = {'worker_pid': os.getpid()}
+    try:
+        # 路径计划到本任务实际开始才加载，未派发的坏文件不会影响其他任务。
+        plan = job.plan if isinstance(job.plan, AnalysisPlan) else load_analysis_plan(job.plan)
+        directory.mkdir(parents=True, exist_ok=False)
+        result = AnalysisRunner(backend).run(plan, work_dir=directory / 'work')
+        metadata.update(input_identity=result.metadata.input_identity, run_id=result.metadata.run_id)
+        manifest = result.write(directory / 'output')
+        metadata['output_dir'] = manifest.output_dir
+        result.close()
+        return BatchJobResult(**_facts(job, plan), **metadata, status='completed',
+                              elapsed_seconds=perf_counter() - started)
+    except BaseException as error:
+        # 结果已经返回后由本层负责close；未返回的运行恢复owner继续沿AnalysisRunner原协议。
+        if result is not None:
+            _cleanup_owner(result, error, 'batch_cleanup_owner', '批量任务结果')
+        owner = getattr(error, 'batch_cleanup_owner', None)
+        if owner is None:
+            owner = getattr(error, 'runner_cleanup_owner', None)
+        # AnalysisRunner可能保留已经成功关闭的恢复属性；只有仍实际持有资源才转交报告。
+        if owner is not None and not (getattr(owner, 'closed', False) or getattr(owner, '_closed', False)):
+            recovery = CleanupHandle(owner)
+        cancelled = isinstance(error, (KeyboardInterrupt, SystemExit))
+        # 资源耗尽或真实取消应停止新派发；普通业务失败由fail_fast决定是否停止。
+        if cancelled or isinstance(error, MemoryError):
+            stop.set()
+        return BatchJobResult(**_facts(job, plan), **metadata,
+                              status='cancelled' if cancelled else 'failed',
+                              error_type=type(error).__name__, error_message=str(error),
+                              error_chain=_diagnostics(error), recovery=recovery,
+                              elapsed_seconds=perf_counter() - started)
+
+
+def _pause():
+    """让出调度CPU等待下一次结果。参数: 无。返回: None。异常: 主进程取消。"""
+    time.sleep(0.01)
+
+
+class BatchRunner:
+    """通过有限spawn工作进程执行独立任务；同一任务的连续文件保持原顺序。"""
+
+    def __init__(self, process_count=1, *, fail_fast=False, backend=None):
+        """配置调度。参数: process_count正整数；fail_fast布尔；backend可选计算实现。
+
+        返回: None。异常: 参数不合法；构造时不启动进程或读取业务输入。
+        """
+        if type(process_count) is not int or process_count < 1:
+            raise ValueError('process_count需要正原生int')
+        if type(fail_fast) is not bool:
+            raise TypeError('fail_fast需要bool')
+        AnalysisRunner(backend)
+        self.process_count, self.fail_fast, self.backend = process_count, fail_fast, backend
+
+    def run(self, jobs, output_dir, *, cancel_event=None, device_label='pending') -> BatchReport:
+        """运行独立任务，原声明顺序返回报告。
+
+        参数: jobs为BatchJob tuple；output_dir全新目录；cancel_event可选threading.Event；
+            device_label为报告来源标签。返回: BatchReport，close可重试子进程内失败清理。
+        异常: 声明和路径错误在启动前拒绝；调度基础设施错误携带batch_report。
+        副作用: 启动最多process_count个工作进程，每任务独立发布；取消只阻止未派发任务。
+        """
+        from .process_transport import ProcessWorker
+        if type(jobs) is not tuple or any(not isinstance(j, BatchJob) for j in jobs):
+            raise TypeError('批量任务需要BatchJob tuple')
+        if len({j.job_id.casefold() for j in jobs}) != len(jobs):
+            raise ValueError('批量job_id不能重复，大小写冲突也拒绝')
+        if cancel_event is not None and not isinstance(cancel_event, Event):
+            raise TypeError('cancel_event需要threading.Event')
+        if type(device_label) is not str or not device_label.strip():
+            raise ValueError('device_label需要非空文本')
+        root = _new_root(output_dir)
+        root.mkdir(parents=True, exist_ok=False)
+        cancel = Event() if cancel_event is None else cancel_event
+        workers, free, active, last_job = [], [], {}, {}
+        results = [None] * len(jobs)
+        next_job, stopped, interrupted, infrastructure = 0, False, False, None
+        while next_job < len(jobs) or active:
+            try:
+                if cancel.is_set():
+                    stopped = True
+                # 先收齐本轮已完成结果再派发，避免观察到失败后继续启动下一任务。
+                for worker, index in list(active.items()):
+                    try:
+                        if not worker.ready():
+                            continue
+                        outcome = worker.receive()
+                    except Exception as error:
+                        outcome = BatchJobResult(**_facts(jobs[index]), status='failed',
+                            worker_pid=worker.pid, error_type=type(error).__name__,
+                            error_message=str(error), error_chain=_diagnostics(error))
+                        infrastructure = infrastructure or error
+                        stopped = True
+                    results[index] = outcome
+                    del active[worker]
+                    if self.fail_fast and outcome.status == 'failed':
+                        stopped = True
+                    if outcome.error_type in ('MemoryError', 'KeyboardInterrupt', 'SystemExit'):
+                        stopped = True
+                    if not worker.pending:
+                        free.append(worker)
+                while not stopped and next_job < len(jobs):
+                    if cancel.is_set():
+                        stopped = True
+                        break
+                    if free:
+                        worker = free.pop()
+                    elif len(workers) < min(self.process_count, len(jobs)):
+                        worker = ProcessWorker()
+                        workers.append(worker)
+                    else:
+                        break
+                    index = next_job
+                    try:
+                        worker.submit(jobs[index], root / jobs[index].job_id, self.backend)
+                    except Exception as error:
+                        results[index] = BatchJobResult(**_facts(jobs[index]), status='failed',
+                            worker_pid=worker.pid, error_type=type(error).__name__, error_message=str(error))
+                        infrastructure = infrastructure or error
+                        stopped = True
+                        break
+                    active[worker], last_job[worker] = index, index
+                    next_job += 1
+                if not active:
+                    # 所有工作进程若都因未完成清理而暂停，剩余任务不再派发。
+                    break
+                _pause()
+            except KeyboardInterrupt:
+                interrupted, stopped = True, True
+            except Exception as error:
+                infrastructure, stopped = infrastructure or error, True
+        # 在途任务已结束；持续关闭失败留远程owner，不因结束调度而丢掉恢复入口。
+        for worker in workers:
+            if worker.pending:
+                continue
+            try:
+                worker.close()
+            except BaseException as error:
+                index = last_job.get(worker)
+                if index is not None:
+                    results[index] = replace(results[index], status='failed',
+                        error_type=type(error).__name__, error_message=str(error),
+                        recovery=CleanupHandle(worker))
+                infrastructure = infrastructure or error
+        reason = '用户取消，尚未启动' if cancel.is_set() or interrupted else '失败或未完成清理后停止派发'
+        report = _report(root, jobs, results, self.process_count, self.fail_fast,
+                         cancel.is_set() or interrupted, device_label, reason)
+        report = replace(report, worker_process_count=len(workers))
+        if infrastructure is not None:
+            report = replace(report, infrastructure_error=type(infrastructure).__name__ + ': ' + str(infrastructure))
+            infrastructure.batch_report = report
+            raise infrastructure
+        return report

chronaxis/batch/templates.py

@@ -0,0 +1,42 @@
+"""把一个分析模板应用于明确输入集合，每个文件形成独立任务，不读取日志。
+
+路径按模板目录解释；输入目录按批量配置目录解释。复用已有自然序和4096文件限制，
+来源有多个候选时要求source，绝不把连续会话自动拆开。本入口由用户显式选择。
+"""
+from copy import deepcopy
+from pathlib import Path
+
+from ..configuration import load_configuration
+from ..configuration.imports import expand_document_imports
+from ..planning.checks import PlanValidationError, text_at
+from ..planning.input_paths import expand_source_files
+
+
+def template_jobs(raw, base):
+    """参数为批量对象和路径基准；返回独立BatchJob列表。配置错误抛PlanValidationError，不写文件。"""
+    from .models import BatchJob
+    from ..planning.plan import AnalysisPlan
+    path=base/Path(text_at(raw['template'],'$.template'))
+    path=path.absolute()
+    template=expand_document_imports(load_configuration(path)).data
+    sources=template.get('sources',[]) if type(template) is dict else []
+    if type(sources) is not list or any(type(source) is not dict for source in sources):
+        raise PlanValidationError('$.template','模板sources必须为来源对象数组')
+    selector=raw.get('source')
+    if selector is not None:selector=text_at(selector,'$.source',identifier=True)
+    candidates=[i for i,s in enumerate(sources) if selector is None or s.get('name',f'source_{i+1}')==selector]
+    if len(candidates)!=1:
+        raise PlanValidationError('$.source','模板必须能唯一确定要替换文件的来源；多来源时填写source')
+    index=candidates[0]
+    selected=sources[index]
+    if selected.get('source_type')=='memory':
+        raise PlanValidationError('$.source','目录批量模板不能替换内存来源')
+    files,shifts=expand_source_files(dict(paths=raw['inputs'],source_type=selected.get('source_type')),base,'$.inputs')
+    jobs=[]
+    for number,file in enumerate(files,1):
+        config=deepcopy(template);source=config['sources'][index]
+        for key in ('path','paths','offsets'):source.pop(key,None)
+        source['path']=str(file)
+        if shifts is not None:source['paths']=[dict(path=source.pop('path'),offset=shifts[number-1])]
+        jobs.append(BatchJob(f'job_{number}',AnalysisPlan.from_dict(config,base_dir=path.parent)))
+    return jobs

chronaxis/can_dependencies.py

@@ -0,0 +1,42 @@
+"""在真正使用 CAN 库时给出缺依赖诊断，已安装的库仍按需导入。
+
+输入为固定支持的模块名，输出为原模块；仅包装缺少模块的异常，其他导入错误
+继续原样报告。不安装依赖、不读取输入、不修改 reader/decoder 的调用顺序。
+"""
+from importlib import import_module
+
+
+CAN_INSTALL_HINT = (
+    '请在运行分析的同一个 Python 环境重新安装本地 wheel，默认会安装 CAN 依赖：'
+    'python -m pip install "./chronaxis-0.1.0.dev0-py3-none-any.whl"。'
+    '将文件路径替换为实际收到的安装包；离线时需备齐该 wheel 声明版本的依赖。'
+    '不要通过修改信号字段解决环境缺依赖，也不要仅安装未核实版本的 cantools。'
+)
+
+
+class CANDependencyError(ImportError):
+    """保留缺失模块名与机器码的 CAN 环境错误，不冒充配置值错误。"""
+
+    code = 'dependency_missing'
+
+    def __init__(self, module_name):
+        """保存缺项及安装建议。参数: module_name 为缺失模块名。返回: None。异常: 无。"""
+        self.module_name = module_name
+        self.hint = CAN_INSTALL_HINT
+        super().__init__(f'缺少 CAN 读取/解码依赖：{module_name}。{self.hint}')
+
+
+def import_can_dependency(module_name):
+    """按既有调用点导入实际需要的 CAN 库。
+
+    参数: module_name 为 can、cantools 或 natsort。
+    返回: 原 Python 模块。异常: CANDependencyError 表示模块或其依赖缺失；
+    其他 ImportError 原样传播，避免将损坏或不兼容安装误报成信号错误。
+    """
+    if module_name not in ('can', 'cantools', 'natsort'):
+        raise ValueError('不是已声明的 CAN 依赖')
+    try:
+        return import_module(module_name)
+    except ModuleNotFoundError as error:
+        # 间接依赖也可能缺失；保留具体名字供定位完整安装问题。
+        raise CANDependencyError(error.name or module_name) from error