chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/__init__.py

@@ -0,0 +1,72 @@
+"""公开时间转换、分析计划、公共AnalysisRunner和流式结果入口。
+
+时间入口接收显式单位时间、日期或整数纳秒序列，返回转换诊断与参考结果。
+AnalysisPlan、load_analysis_plan、validate_analysis_plan和explain_analysis_plan提供配置构建、静态
+检查及依赖解释；访问这些名称时才加载计划模块及其数组来源依赖。
+直接导入时间或核心入口只需标准库，不加载CAN或DBC，也不创建文件和日志。
+预设入口校验角色并生成公共声明；结果入口提供有限暂存、流式读取和Windows原子发布。
+AnalysisRunner接收内存信号、独立信号CSV、BLF及显式格式的ASC/原始报文CSV；访问该名称才加载运行包装。
+BatchRunner或run_batch在外层调度独立计划，各任务使用独立状态和结果目录。
+BLF沿用sclicer-functions-v1旧读取链；新文本CAN使用can-text-v1独立入口。
+信号表及原帧导出可分别选择原始采样或连续量重采样，配置和边界见当前用户手册的输入与导出章节。
+具体配置和输入限制见当前用户手册。
+"""
+
+# 普通根包导入仍只加载标准库时间协议；计划、运行和结果入口按需加载。
+from .timebase import (
+    TimeConversion, TimeOverflowError, checked_add_ns, convert_time,
+    parse_datetime_ns, parse_duration, shift_times_reference, time_deltas_reference,
+)
+
+# 明确公开范围；没有隐式文件读取、后端回退或CAN依赖。
+__all__ = [
+    "TimeConversion", "TimeOverflowError", "checked_add_ns", "convert_time",
+    "parse_datetime_ns", "parse_duration", "shift_times_reference", "time_deltas_reference",
+    "AnalysisPlan", "PlanValidationError", "load_analysis_plan", "validate_analysis_plan", "explain_analysis_plan",
+    "PresetSpec", "PlanFragment", "build_preset", "resolve_preset_roles",
+    "AnalysisResult", "OutputManifest", "RunMetadata", "AnalysisError", "ResultClosedError",
+    "AnalysisRunner",
+    "BatchJob", "BatchJobResult", "BatchReport", "BatchRunner", "BatchPlan", "load_batch_plan", "run_batch",
+]
+
+
+def __getattr__(name: str):
+    """按公开名称加载计划接口，避免基础时间入口立即依赖数组模块。
+
+    参数:
+        name (str): Python请求的模块属性名，与配置表达式的属性访问无关。
+    返回:
+        公开名单中的类或函数对象。返回接口本身，不构造计划或打开分析输入。
+    异常:
+        AttributeError: 名称未在公开名单中。
+        ImportError等导入异常: 访问计划接口时所需依赖缺失或模块加载失败。
+    副作用:
+        导入planning及其依赖；不缓存任何会话输入或绑定。
+    """
+    # Python模块只公开列出的名称；配置表达式的属性访问仍由独立语法检查拒绝。
+    if name in ('BatchJob', 'BatchJobResult', 'BatchReport', 'BatchRunner', 'BatchPlan', 'load_batch_plan', 'run_batch'):
+        # 取得批量入口时才加载模型；普通根包和CLI帮助仍不加载数组或来源。
+        from . import batch
+        return getattr(batch, name)
+    if name == 'AnalysisRunner':
+        # 取得类本身不创建session或输入；validate/explain仍只消费冻结计划声明。
+        from .runner import AnalysisRunner
+        return AnalysisRunner
+    if name in ('AnalysisResult', 'OutputManifest', 'RunMetadata', 'AnalysisError', 'ResultClosedError'):
+        # 结果层只依赖标准库和核心模型，访问入口也不启动任何读取或发布。
+        from .results import AnalysisResult, OutputManifest, RunMetadata, AnalysisError, ResultClosedError
+        return {'AnalysisResult': AnalysisResult, 'OutputManifest': OutputManifest, 'RunMetadata': RunMetadata,
+                'AnalysisError': AnalysisError, 'ResultClosedError': ResultClosedError}[name]
+    if name in ('PresetSpec', 'PlanFragment', 'build_preset', 'resolve_preset_roles'):
+        # 预设是外部领域构建层，根包普通导入仍仅加载标准库时间协议。
+        from .presets import PresetSpec, PlanFragment, build_preset, resolve_preset_roles
+        return {'PresetSpec': PresetSpec, 'PlanFragment': PlanFragment, 'build_preset': build_preset,
+                'resolve_preset_roles': resolve_preset_roles}[name]
+    if name not in ('AnalysisPlan', 'PlanValidationError', 'load_analysis_plan', 'validate_analysis_plan', 'explain_analysis_plan'):
+        # Python正常未知模块属性行为，不静默补占位。
+        raise AttributeError(f'chronaxis没有公开属性{name!r}')
+    # 只有用户实际访问计划接口时加载数组来源依赖。
+    from .planning import AnalysisPlan, PlanValidationError, load_analysis_plan, validate_analysis_plan, explain_analysis_plan
+    # 固定映射返回具体能力，不用eval/getattr任意对象或缓存输入绑定。
+    return {'AnalysisPlan': AnalysisPlan, 'PlanValidationError': PlanValidationError, 'load_analysis_plan': load_analysis_plan,
+            'validate_analysis_plan': validate_analysis_plan, 'explain_analysis_plan': explain_analysis_plan}[name]

chronaxis/__main__.py

@@ -0,0 +1,12 @@
+"""将python -m chronaxis委托给同一个CLI入口。
+
+输入为进程参数，输出及退出码由cli.main定义。作为模块导入时不运行命令；
+实际执行只加载CLI，再由用户命令决定检查计划、运行发布或导入旧INI。
+本文件不另写计算逻辑、加载CAN或注册额外后台动作。
+"""
+
+from .cli import main
+
+if __name__ == '__main__':
+    # 两种入口共用解析与错误处理，SystemExit保主函数的真实退出码。
+    raise SystemExit(main())

chronaxis/analysis_cli.py

@@ -0,0 +1,181 @@
+"""把公共AnalysisRunner的检查、解释和实际分析接到CLI，提供文本和JSON报告。
+
+输入为解析后的命令参数，load_analysis_plan只读取指定JSON/YAML并按配置目录解释来源路径。
+validate和explain直接调用同一AnalysisRunner接口，不读取CSV、DBC或旧日志，不建立
+运行目录。序列化逐项选择公开报告字段，不遍历任意对象或另做一套配置校验。
+报告中的预算和有效期是声明，execution_ready不证明实际输入已核实。
+run先检查新输出与工作路径，再交给AnalysisRunner运行，在同一结果上write并关闭。
+只有真实关闭成功才打印成功摘要；失败保留原原因链和现存产物，不假报回滚。
+
+本模块仅在实际计划命令时加载；CLI帮助与参数错误仍只需要标准库。
+"""
+
+import json
+from pathlib import Path
+import sys
+
+# 这些接口只有计划命令实际执行时才加载；取得AnalysisRunner类不会创建运行会话。
+from . import AnalysisRunner, load_analysis_plan
+from .planning.checks import PlanValidationError
+from .results.errors import AnalysisError
+
+
+def validation_json(report) -> dict:
+    """保留公共校验报告的全部固定字段和未验证警告。
+
+    参数: report为AnalysisRunner.validate返回的ValidationReport。
+    返回: 原生JSON字典；元组和只读映射转换为列表和dict，不改变字段含义。
+    异常: 接口不符的编程错误原样传播，不靠反射补缺失属性。
+    """
+    # 显式白名单避免漏掉能力限制，也避免把内部状态或任意元数据输出到控制台。
+    return dict(valid=report.valid, errors=list(report.errors), warnings=list(report.warnings),
+                capability_status=dict(report.capability_status), execution_ready=report.execution_ready)
+
+
+def explanation_json(report) -> dict:
+    """将依赖、节点后端、历史需求和预算声明完整交给CLI使用者。
+
+    参数: report为AnalysisRunner.explain返回的ExplainReport。
+    返回: 固定JSON字典，节点保持原顺序，plan_identity保持原配置身份。
+    异常: 接口不符的编程错误原样传播；不推算实测峰值或来源观测范围。
+    """
+    # 各节点只含原公开报告字段；state_driver与数值后端沿原报告区别显示。
+    nodes = [dict(node_id=node.node_id, node_type=node.node_type, dependencies=list(node.dependencies),
+                  unit=node.unit, backend=node.backend) for node in report.nodes]
+    requirements = report.input_requirements
+    scopes = ([] if requirements is None else [dict(source=item.source, input_check=item.input_check,
+        time_scope=item.time_scope, required_aliases=list(item.required_aliases),
+        decode_frame_ids=list(item.decode_frame_ids), reasons=list(item.reasons)) for item in requirements.sources])
+    if report.intervals is not None and requirements is not None:
+        for item,scope in zip(requirements.sources,scopes):
+            scope['active']=item.active
+    output = dict(input_requirements=scopes, validation=validation_json(report.validation), plan_identity=report.plan_identity,
+                source_names=list(report.source_names), nodes=nodes,
+                history_ns=dict(report.history_ns), budget=dict(report.budget))
+    # 解释已解析的间隔声明，不推测DBC周期或输出第二时间轴。
+    if report.intervals is not None:
+        choices = {}
+        for name, choice in report.intervals.resolved:
+            choices[name] = dict(mode=choice.mode, step_ns=choice.step_ns, driver=choice.driver)
+        output['intervals'] = choices
+    if report.diagnostics is not None:
+        output['diagnostics'] = dict(trace=report.diagnostics.trace,
+            integrity=report.diagnostics.integrity, retain_work=report.diagnostics.retain_work)
+    return output
+
+
+def run_static(arguments) -> int:
+    """只加载配置并输出共享AnalysisRunner报告，不触碰来源或创建分析产物。
+
+    参数: arguments含command=validate或explain、plan路径和可选backend覆盖。
+    返回: 0表示静态有效且当前有执行路径，2表示报告中存在能力错误。
+    异常: 配置加载、依赖、JSON输出或取消错误向主CLI传播，由统一边界处理。
+    副作用: 只读取计划JSON、写stdout；来源路径按load_analysis_plan解释，不按CLI另猜。
+    """
+    # 只构建静态计划和无状态AnalysisRunner；这些步骤不验证来源文件是否存在或可读。
+    plan = load_analysis_plan(arguments.plan)
+    runner = AnalysisRunner(backend=arguments.backend)
+    # 两种命令使用相同有效计划，覆盖后端不会伪造新的配置或输入身份。
+    if arguments.command == 'validate':
+        validation = runner.validate(plan)
+        payload = validation_json(validation)
+    else:
+        report = runner.explain(plan)
+        validation = report.validation
+        payload = explanation_json(report)
+    # 人读输出复用同一计划及报告；机器格式保持明确字段，不重新解析输入。
+    if arguments.format=='json':
+        print(json.dumps(payload, ensure_ascii=False, allow_nan=False))
+    else:
+        from .configuration.explanation import validation_text, explanation_text
+        text=(validation_text(plan,validation) if arguments.command=='validate'
+              else explanation_text(plan,report,backend_override=arguments.backend))
+        print(text)
+    return 0 if validation.valid and validation.execution_ready and not validation.errors else 2
+
+
+def _new_output(arguments) -> Path:
+    """在扫描来源前拒绝已有输出、历史目录和必然冲突的工作路径。
+
+    参数: arguments包含output和可选work_dir，由argparse限定为路径文本。
+    返回: 绝对输出Path；不创建目录，工作目录实际分配仍归AnalysisRunner。
+    异常: FileExistsError或原lstat错误为文件失败；PlanValidationError为Ref或路径冲突。
+    """
+    output = Path(arguments.output).absolute()
+    # 同时检查词法与物理路径，不能借符号链接把新产物写进历史快照。
+    candidates = (output,) if arguments.work_dir is None else (output, Path(arguments.work_dir).absolute())
+    for path in candidates:
+        if any(part.casefold() == 'refprojects' for part in (*path.parts, *path.resolve().parts)):
+            raise PlanValidationError('$.cli.output', '运行输出和工作目录不能位于RefProjects')
+    if arguments.work_dir is not None:
+        work = Path(arguments.work_dir).absolute().resolve()
+        destination = output.resolve()
+        # AnalysisRunner会先建立work；若它位于output内部，随后发布必因output已存在而失败。
+        if work == destination or destination in work.parents:
+            raise PlanValidationError('$.cli.work_dir', '工作目录不能等于输出目录或位于输出目录内部')
+    for path in candidates:
+        try:
+            # 两个参数自身都必须全新，不能跟随已有的悬空工作链接创建其目标。
+            # 最终输出安装的竞态仍由原write检查，运行会话也保留原工作目录检查。
+            path.lstat()
+        except FileNotFoundError:
+            continue
+        raise FileExistsError('输出或工作目标已存在，拒绝使用：' + str(path))
+    return output
+
+
+def _cause_chain(error) -> tuple:
+    """取得有限且不重复的真实cause链，供诊断和致命异常判断共用。
+
+    参数: error为实际异常。返回: 最多16个原异常对象，保持外层到根因顺序。
+    异常: 无主动异常；不访问任意业务对象，不解析日志或重建错误。
+    """
+    chain, seen = [], set()
+    current = error
+    # 防御外部异常的cause循环；不因诊断无限遍历而阻塞清理或退出。
+    while current is not None and id(current) not in seen and len(chain) < 16:
+        seen.add(id(current))
+        chain.append(current)
+        current = current.__cause__
+    return tuple(chain)
+
+
+def run_analysis(arguments) -> int:
+    """复用真实分析和发布，成功关闭所有结果资源后才报告completed。
+
+    参数: arguments含plan、output、可选backend及work_dir；输出必须为全新目录。
+    返回: 成功0；已知分析/发布/关闭失败1，并说明输出可能已经发布。
+    异常: 配置/路径错误交主CLI分类；取消原样传播；MemoryError及已知编程错误
+        的直接或AnalysisError原因链继续抛出，不伪装成普通业务错误。
+    副作用: AnalysisRunner建立专用暂存并读来源，write按原合同安装新目录；不删除产物。
+    """
+    plan = load_analysis_plan(arguments.plan)
+    output = _new_output(arguments)
+    runner = AnalysisRunner(backend=arguments.backend)
+    try:
+        # 结果拥有其真实仓和资源；write不重新运行来源，退出上下文完成实际close。
+        with runner.run(plan, work_dir=arguments.work_dir) as result:
+            manifest = result.write(output)
+            summary = dict(status=manifest.status, run_id=manifest.run_id,
+                plan_identity=result.metadata.plan_hash, backend=result.metadata.backend,
+                output=str(manifest.output_dir), manifest=str(manifest.manifest_path),
+                row_counts=dict(manifest.row_counts), device_label=result.metadata.device_label)
+            if result.metadata.analysis_outcome is not None:
+                summary['analysis_outcome']=result.metadata.analysis_outcome.to_dict()
+            if result.table_format == 'readable_csv':
+                from .results.readable_format import outcome_messages
+                summary['result_files'] = [path.name for path in manifest.output_files]
+                summary['result_messages'] = outcome_messages(result.metadata.analysis_outcome)
+    except (AnalysisError, OSError) as error:
+        chain = _cause_chain(error)
+        # AnalysisRunner可能包装构造内存/编程错误；保留该公开异常及原cause，不归类普通失败。
+        if any(isinstance(item, (MemoryError, TypeError, AttributeError, AssertionError, NameError)) for item in chain):
+            raise
+        causes = ' <- '.join(type(item).__name__ + ': ' + str(item).replace('\n', ' ') for item in chain)
+        # 目录可能已安装后才发生close错误，非零退出不证明输出被撤销。
+        print('分析或发布失败（输出可能已发布，请核对目标目录 ' + str(output) + '）：' + causes,
+              file=sys.stderr)
+        return 1
+    # 本行在with真实退出之后，不能提前把analysis_complete当成发布和关闭成功。
+    print(json.dumps(summary, ensure_ascii=False, allow_nan=False))
+    return 0

chronaxis/batch/__init__.py

@@ -0,0 +1,14 @@
+"""公开独立批量任务模型和调度器，不自动创建进程或读取输入。
+
+每个BatchJob调用同一公共AnalysisRunner，输出单独发布，BatchReport只汇总状态和身份。
+调用者可设置process_count工作进程数、fail_fast和取消Event；在途任务完成关闭后才返回。
+"""
+
+from .models import BatchJob, BatchJobResult, BatchReport, BatchPlan
+from .runner import BatchRunner
+from .config import load_batch_plan
+from .api import run_batch
+from .publication import write_batch_report
+
+__all__ = ['BatchJob', 'BatchJobResult', 'BatchReport', 'BatchRunner', 'BatchPlan',
+           'load_batch_plan', 'run_batch', 'write_batch_report']

chronaxis/batch/api.py

@@ -0,0 +1,46 @@
+"""把冻结批量计划交给同一调度器并保存完整报告，不重新实现分析算法。
+
+正常返回的BatchReport包含所有独立任务的最终状态。调度或报告写出失败时，
+原异常保留batch_report，使调用方能访问已完成结果并重试未关闭的资源。
+"""
+
+from dataclasses import replace
+from .models import BatchPlan
+from .runner import BatchRunner
+from .publication import write_batch_report
+
+
+def run_batch(plan: BatchPlan, output_dir, *, process_count: int | None = None, cancel_event=None, device_label='pending'):
+    """运行并发布批量报告。
+
+    参数: plan为load_batch_plan取得的BatchPlan，规定本次独立任务及调度设置；process_count为可选正整数覆盖，None沿用计划；output_dir全新目录；cancel_event为可选Event；device_label为实际标签。
+    返回: BatchReport；failed/cancelled保留在报告，不伪装全部成功。
+    异常: TypeError为非BatchPlan或取消对象类型不符；ValueError为无效并发、后端或
+        任务声明；目录创建、调度、报告发布错误按原类型传播。单任务失败记录在jobs中，
+        不等于本函数抛错。已产生报告后发生基础设施错误时，异常的batch_report保存
+        当次实际报告，可检查已完成任务并调用close重试清理。
+    """
+    if not isinstance(plan, BatchPlan):
+        raise TypeError('run_batch需要BatchPlan')
+    if process_count is not None:
+        plan = replace(plan, process_count=process_count)
+    runner = BatchRunner(plan.process_count, fail_fast=plan.fail_fast, backend=plan.backend)
+    try:
+        report = runner.run(plan.jobs, output_dir, cancel_event=cancel_event, device_label=device_label)
+    except BaseException as error:
+        report = getattr(error, 'batch_report', None)
+        if report is not None:
+            report = replace(report, infrastructure_error=type(error).__name__ + ': ' + str(error))
+            error.batch_report = report
+            try:
+                write_batch_report(report)
+            except BaseException as diagnostic:
+                error.add_note('批量失败报告未发布: ' + type(diagnostic).__name__)
+        raise
+    try:
+        write_batch_report(report)
+    except BaseException as error:
+        # 已完成任务绝不因汇总文件失败而丢失，未清理资源仍可从原异常恢复。
+        error.batch_report = report
+        raise
+    return report

chronaxis/batch/cli.py

@@ -0,0 +1,48 @@
+"""从严格批量配置调用公共API，打印精简计数并保留完整逐任务报告。
+
+成功退出0、任一任务失败退出1、取消退出130；配置错误沿外层CLI退出2。
+输出失败保已完成任务，原异常恢复报告在传播前尝试关闭，不清除诊断文件。
+"""
+
+from dataclasses import replace
+import json
+import os
+import sys
+from ..planning.checks import PlanValidationError
+from ..results.spool import _cleanup_owner
+from .api import run_batch
+from .config import load_batch_plan
+from .runner import _new_root
+
+
+def run_batch_cli(arguments) -> int:
+    """执行真实批量入口。参数: argparse参数。返回: 0/1/130。异常: 外层CLI处理的原错或配置错。"""
+    plan = load_batch_plan(arguments.plan)
+    try:
+        if arguments.process_count is not None:
+            plan = replace(plan, process_count=arguments.process_count)
+        _new_root(arguments.output)
+    except ValueError as error:
+        raise PlanValidationError('$.cli', str(error)) from error
+    label = os.environ.get('CHRONAXIS_DEVICE_LABEL', '').strip() or 'pending'
+    try:
+        report = run_batch(plan, arguments.output, device_label=label)
+    except BaseException as error:
+        report = getattr(error, 'batch_report', None)
+        if report is not None:
+            _cleanup_owner(report, error, 'batch_report', '批量异常报告')
+        raise
+    # 一般失败已经清理完；持续故障再尝试，完整报告仍保存初始失败及恢复位置。
+    cleanup_failed = False
+    try:
+        report.close()
+    except Exception as error:
+        cleanup_failed = True
+        print('批量结果清理失败：' + type(error).__name__ + ': ' + str(error), file=sys.stderr)
+    document = report.to_dict()
+    print(json.dumps(dict(status=report.status, counts=document['counts'],
+        output=str(report.output_dir), report=str(report.output_dir/'batch_report.json'),
+        cleanup_pending=cleanup_failed, device_label=label), ensure_ascii=False, allow_nan=False))
+    if cleanup_failed or report.status == 'failed':
+        return 1
+    return 130 if report.status == 'cancelled' else 0

chronaxis/batch/config.py

@@ -0,0 +1,37 @@
+"""加载批量清单；显式jobs保存路径，template展开为每文件独立计划。
+
+JSON/YAML重复键、非有限值和错误定位沿用共享配置语法规则；实际独立计划到
+jobs在worker启动时加载；template在此时读取模板和必要DBC元数据，均不预读业务日志。
+"""
+
+from pathlib import Path
+from ..configuration import load_configuration, ConfigurationError
+from ..configuration.diagnostics import locate_error
+from ..planning.checks import PlanValidationError, configuration_error
+from .models import BatchPlan
+
+
+def load_batch_plan(path: str | Path) -> BatchPlan:
+    """读取批量YAML或JSON文件，建立独立任务及其调度设置。
+
+    参数:
+        path (str | Path): UTF-8批量配置路径；子计划相对路径以本文件目录为起点。
+    返回:
+        BatchPlan: 已检查批量结构的不可变计划；template已展开，jobs仍保存路径，均未读取业务输入。
+    异常:
+        PlanValidationError: 路径类型不合法、文件不可读、编码/语法错误或批量字段不合法。
+            先按错误字段路径修正批量或模板文件；jobs中的子计划错误在任务启动时记入任务报告。
+    副作用:
+        读取批量文件，template模式还读取模板与必要DBC、枚举输入集合；不创建输出目录。"""
+    if not isinstance(path, (str, Path)):
+        raise PlanValidationError('$', '批量配置路径必须为Path或文本')
+    target = Path(path).absolute()
+    try:
+        document = load_configuration(target)
+        return BatchPlan.from_dict(document.data, base_dir=target.parent)
+    except ConfigurationError as error:
+        raise configuration_error(error) from error
+    except PlanValidationError as error:
+        raise locate_error(error,document)
+    except (OSError, UnicodeError, ValueError, TypeError) as error:
+        raise PlanValidationError('$',str(error),'load_error',source=str(target)) from error

chronaxis/batch/models.py

@@ -0,0 +1,202 @@
+"""保存独立批量任务及其完成、失败和取消事实。
+
+输入是已构建计划或计划文件路径；输出保留任务、计划、会话和实际输入身份。
+模型不读取来源、不建立进程，也不将多个任务的数值结果相加。清理失败时只保留
+可显式重试的最高资源所有者，错误本身转成文本，避免长期保存异常栈和输入数组。
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from ..core.validation import require_identifier
+from ..planning.plan import AnalysisPlan
+
+
+class Closable(Protocol):
+    """表示已经存在、由调用者负责关闭的资源，不创建占位执行对象。"""
+
+    def close(self) -> None:
+        """关闭资源。参数: 无。返回: None。异常: 原关闭错误，可恢复后重试。"""
+        ...
+
+
+class CleanupHandle:
+    """只持有未关闭的最高所有者；关闭成功后撤销引用，重复关闭无副作用。"""
+
+    def __init__(self, owner: Closable):
+        """接管真实恢复对象。参数: owner有close方法。返回: 新句柄。异常: 无。"""
+        self._owner = owner
+
+    @property
+    def closed(self) -> bool:
+        """读取恢复是否完成。参数: 无。返回: bool。异常: 无。"""
+        return self._owner is None
+
+    def close(self) -> None:
+        """重试关闭，不在失败时丢所有者。参数: 无。返回: None。异常: 原关闭错误。"""
+        if self._owner is not None:
+            self._owner.close()
+            self._owner = None
+
+
+@dataclass(frozen=True)
+class BatchJob:
+    """声明一个独立分析；同会话连续文件应包含在本任务的一个计划中。"""
+
+    job_id: str  # 批量范围内唯一的简单标识，不用它拼接任意相对路径。
+    plan: AnalysisPlan | Path  # 冻结计划或文件路径；路径到真正启动时才加载。
+
+    def __post_init__(self):
+        """检查声明而不读文件。参数: 无。返回: None。异常: 名称或计划类型错误。"""
+        require_identifier(self.job_id, 'job_id')
+        if not isinstance(self.plan, (AnalysisPlan, Path)):
+            raise TypeError('BatchJob.plan需要AnalysisPlan或Path')
+
+
+@dataclass(frozen=True)
+class BatchPlan:
+    """保存批量配置；只关联独立计划路径，不能把一个会话拆成多个时间任务。"""
+
+    jobs: tuple[BatchJob, ...]  # 声明顺序就是最终清单顺序。
+    process_count: int = 1  # 工作进程上限，默认1；各任务仍有独立预算。
+    fail_fast: bool = False  # 默认继续其他独立任务。
+    backend: str | None = None  # 可选统一覆盖，不修改原计划文件。
+
+    def __post_init__(self):
+        """检查冻结声明。参数: 无。返回: None。异常: 类型、范围或重复任务错误；无I/O。"""
+        if type(self.jobs) is not tuple or any(not isinstance(j, BatchJob) for j in self.jobs):
+            raise TypeError('jobs需要BatchJob tuple')
+        if len({j.job_id.casefold() for j in self.jobs}) != len(self.jobs):
+            raise ValueError('批量job_id不能重复或仅大小写不同')
+        if type(self.process_count) is not int or self.process_count < 1:
+            raise ValueError('process_count需要正原生int')
+        if type(self.fail_fast) is not bool:
+            raise TypeError('fail_fast需要bool')
+        if self.backend is not None and (type(self.backend) is not str or self.backend not in ('reference', 'numpy')):
+            raise ValueError('backend需要reference、numpy或null')
+
+    @classmethod
+    def from_dict(cls, config, *, base_dir=None):
+        """检查批量配置；jobs只关联路径，template读取模板并展开文件集合。
+
+        参数: config原生dict；base_dir为计划路径相对基准，默认当前目录。
+        返回: 冻结BatchPlan。异常: PlanValidationError定位字段；不读取业务报文，模板可读取DBC元数据。
+        """
+        from ..planning.checks import object_at, array_at, text_at, model_at, PlanValidationError, number_at, choice_at
+        if type(config) is dict and ('workers' in config or 'max_workers' in config):
+            raise PlanValidationError('$.process_count', '请使用process_count设置分析工作进程数；workers/max_workers不再接受')
+        raw = object_at(config, '$', ('batch_version',), ('jobs', 'template', 'inputs', 'source', 'process_count', 'fail_fast', 'backend'))
+        choice_at(raw['batch_version'],(1,),'$.batch_version')
+        base, jobs = Path.cwd() if base_dir is None else Path(base_dir).absolute(), []
+        if 'template' in raw:
+            if 'jobs' in raw or 'inputs' not in raw:
+                raise PlanValidationError('$','template需要inputs且不能同时提供jobs')
+            from .templates import template_jobs
+            jobs=template_jobs(raw,base)
+        elif 'jobs' not in raw or 'inputs' in raw or 'source' in raw:
+            raise PlanValidationError('$','需要jobs，或template与inputs')
+        names=set()
+        for index, value in enumerate(array_at(raw.get('jobs', []), '$.jobs')):
+            path = '$.jobs[' + str(index) + ']'
+            item = object_at(value, path, ('plan',), ('name',))
+            job_id = text_at(item.get('name',f'job_{index+1}'), path + '.name', identifier=True)
+            if job_id.casefold() in names:
+                raise PlanValidationError(path+'.name','任务名称不能重复或仅大小写不同','duplicate_id',
+                    hint='为每个独立任务指定唯一name')
+            names.add(job_id.casefold())
+            target = Path(text_at(item['plan'], path + '.plan'))
+            if not target.is_absolute():
+                target = base / target
+            jobs.append(BatchJob(job_id, target.absolute()))
+        return model_at(cls, '$', tuple(jobs),
+            number_at(raw.get('process_count',1),'$.process_count',integer=True,minimum=1),
+            choice_at(raw.get('fail_fast',False),(False,True),'$.fail_fast'),
+            choice_at(raw.get('backend'),(None,'reference','numpy'),'$.backend'))
+
+
+@dataclass(frozen=True)
+class BatchJobResult:
+    """保存一个任务的最终状态；发布后关闭失败仍为failed，并保留已发布路径。"""
+
+    job_id: str  # 原任务身份。
+    status: str  # completed、failed或cancelled。
+    plan_path: str | None = None  # 路径计划的原绝对位置；内存计划无路径。
+    plan_identity: str | None = None  # 配置身份，不冒充实际输入内容身份。
+    dataset_id: str | None = None  # 无法加载计划时三项会话字段均为空。
+    entity_id: str | None = None
+    session_id: str | None = None
+    input_identity: str | None = None  # 只有实际分析返回后才记录。
+    run_id: str | None = None  # 同计划重跑仍有独立运行身份。
+    output_dir: Path | None = None  # 实际发布成功的目录，不预填未生成输出。
+    error_type: str | None = None  # 原异常类型或未启动取消原因。
+    error_message: str | None = None  # 原错误说明，不用成功值覆盖失败。
+    error_chain: tuple[str, ...] = ()  # cause链和清理notes，保留错误来源。
+    elapsed_seconds: float = 0.0  # 单任务墙钟秒，含发布及关闭，不宣称CPU耗时。
+    memory_budget_bytes: int | None = None  # 该任务的新分析层预算；不是整进程RSS。
+    worker_pid: int | None = None  # 实际执行任务的工作进程PID；未启动项为空。
+    recovery: CleanupHandle | None = field(default=None, repr=False, compare=False)
+
+    def __post_init__(self):
+        """拒绝伪成功状态。参数: 无。返回: None。异常: 非法状态或成功缺少事实。"""
+        if self.status not in ('completed', 'failed', 'cancelled'):
+            raise ValueError('批量任务状态无效')
+        if self.status == 'completed' and (self.output_dir is None or self.run_id is None):
+            raise ValueError('completed需要实际发布目录及运行身份')
+
+    def to_dict(self) -> dict:
+        """生成可保存的事实。参数: 无。返回: JSON对象。异常: 无；不序列化资源对象。"""
+        names = ('job_id', 'status', 'plan_path', 'plan_identity', 'dataset_id', 'entity_id',
+                 'session_id', 'input_identity', 'run_id', 'error_type', 'error_message',
+                 'elapsed_seconds', 'memory_budget_bytes', 'worker_pid')
+        result = {name: getattr(self, name) for name in names}
+        result.update(output_dir=None if self.output_dir is None else str(self.output_dir),
+                      error_chain=list(self.error_chain),
+                      cleanup_pending=self.recovery is not None and not self.recovery.closed)
+        return result
+
+
+@dataclass(frozen=True)
+class BatchReport:
+    """按原任务顺序汇总结果；每个任务数值表仍在各自目录，不跨口径归约。"""
+
+    output_dir: Path  # 本批新目录，已有目标不会被覆盖。
+    jobs: tuple[BatchJobResult, ...]  # 最终结果顺序不受工作进程完成先后影响。
+    process_count: int  # 本次配置的工作进程上限。
+    fail_fast: bool  # 是否在观察到失败后停止派发。
+    cancel_requested: bool  # 用户取消或KeyboardInterrupt是否曾被观察到。
+    device_label: str  # 调用方明确提供；缺省pending，不猜测机器。
+    worker_process_count: int = 0  # 本次实际启动的工作进程数，空批次为0。
+    infrastructure_error: str | None = None  # 调度或汇总基础设施错误，与任务业务失败分开。
+
+    @property
+    def status(self) -> str:
+        """汇总失败优先状态。参数: 无。返回: failed/cancelled/completed。异常: 无。"""
+        if self.infrastructure_error is not None or any(job.status == 'failed' for job in self.jobs):
+            return 'failed'
+        return 'cancelled' if any(job.status == 'cancelled' for job in self.jobs) else 'completed'
+
+    def to_dict(self) -> dict:
+        """输出身份和计数。参数: 无。返回: JSON对象。异常: 无。不合并指标值。"""
+        return dict(batch_version=1, status=self.status, output_dir=str(self.output_dir),
+                    process_count=self.process_count, executor='processes', worker_process_count=self.worker_process_count, fail_fast=self.fail_fast,
+                    cancel_requested=self.cancel_requested, device_label=self.device_label,
+                    infrastructure_error=self.infrastructure_error,
+                    budget_scope='per_task_new_analysis_layer',
+                    counts={s: sum(j.status == s for j in self.jobs)
+                            for s in ('completed', 'failed', 'cancelled')},
+                    jobs=[job.to_dict() for job in self.jobs])
+
+    def close(self) -> None:
+        """重试所有未完清理。参数: 无。返回: None。异常: 首个关闭错误，其他项仍尝试。"""
+        first = None
+        for job in self.jobs:
+            if job.recovery is not None:
+                try:
+                    job.recovery.close()
+                except BaseException as error:
+                    # 一项失败不能阻止其他独立任务释放资源；原句柄仍由本报告保留。
+                    if first is None:
+                        first = error
+        if first is not None:
+            raise first