chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/cli.py

@@ -0,0 +1,193 @@
+"""提供计划检查、运行发布、独立批量与旧INI导入，复用各自公共接口。
+
+输入为命令行路径、模式及显式mapping；输出为新计划、原INI、迁移报告和简短
+JSON摘要。转换失败仍可保存原文与失败报告，绝不返回部分可运行计划。
+validate/explain只读取计划，输出共享AnalysisRunner报告，不打开数据/DBC或运行分析。
+run才调用同一AnalysisRunner执行、write发布并关闭结果；完整完成后才打印成功摘要。
+batch run调用同一批量API，打印状态计数，逐任务错误保存在batch_report.json。
+配置和参数错误退出2，文件/平台错误退出1，取消退出130，成功退出0。
+--help及参数错误只需标准库；实际命令执行时才加载对应计划或发布模块。
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import sys
+
+
+def _parser() -> argparse.ArgumentParser:
+    """定义已交付命令，未知命令和缺参数由argparse定位。
+
+    参数: 无。返回: ArgumentParser，不读取任何配置或来源。
+    异常: 原参数构造错误传播；解析时的帮助/坏参数分别SystemExit(0/2)。
+    """
+    parser = argparse.ArgumentParser(prog='chronaxis', description='Chronaxis计划检查、分析与旧INI导入')
+    commands = parser.add_subparsers(dest='command', required=True)
+    guide = commands.add_parser('guide', help='显示可直接阅读的AI指南路径')
+    guide.add_argument('--language', choices=('zh', 'en'), default='zh', help='阅读入口语言，默认zh；不写文件')
+    guide.add_argument('--output', help='可选：另存完整双语ZIP；父目录须存在，目标不能已存在')
+    configuration = commands.add_parser('config', help='初始化及检查配置文件')
+    configuration_actions = configuration.add_subparsers(dest='config_command', required=True)
+    initialize = configuration_actions.add_parser('init', help='从合成场景生成完整新目录')
+    initialize.add_argument('scene', nargs='?', help='场景名；用--list查看可选场景')
+    initialize.add_argument('--list', action='store_true', help='列出全部场景，不写文件')
+    initialize.add_argument('--output', help='全新目录；父目录须已存在')
+    initialize.add_argument('--style', choices=('minimal','annotated'), default='annotated', help='默认完整注释版')
+    convert = configuration_actions.add_parser('convert', help='当前JSON/YAML互转，保持类型和值；不保留注释')
+    convert.add_argument('input', help='当前分析、批量或INI映射配置')
+    convert.add_argument('--output', required=True, help='新.json/.yaml/.yml文件；相对路径配置须写同目录')
+    resolve = configuration_actions.add_parser('resolve', help='展开有效配置，固定绝对路径；可选显示实际默认')
+    resolve.add_argument('input', help='当前分析、批量或INI映射配置')
+    resolve.add_argument('--output', help='可选全新JSON/YAML文件；省略时输出到终端')
+    resolve.add_argument('--format', choices=('json','yaml'), help='终端默认yaml；文件由扩展名确定')
+    resolve.add_argument('--defaults', action='store_true', help='写出适用的执行、输出、信号与规则等默认值')
+    # 来源报告只按请求生成，不混入可重新加载的resolve输出。
+    origins = configuration_actions.add_parser('origins', help='查看定义来自哪个配置文件，不读取业务输入')
+    origins.add_argument('input', help='当前分析、批量或INI映射配置')
+    origins.add_argument('--fields', action='store_true', help='列所有显式叶字段；默认列来源、信号和派生定义')
+    origins.add_argument('--format', choices=('text','json'), default='text', help='默认中文文本，json用于机器读取')
+    # 静态命令只接受配置和明确后端，不提供输出目录等会误导为已运行的选项。
+    for name, help_text in (('validate', '检查配置、绑定和当前执行能力'),
+                            ('explain', '显示依赖、节点后端与预算声明')):
+        check = commands.add_parser(name, help=help_text)
+        check.add_argument('plan', help='分析计划YAML或JSON；来源相对路径按配置文件目录解释')
+        check.add_argument('--backend', choices=('reference', 'numpy'), default=None,
+                           help='显式覆盖本次后端；省略则沿用计划声明')
+        check.add_argument('--format', choices=('text','json'), default='text',
+                           help='默认显示易读说明；json用于程序读取')
+    # run只提供执行选择和新目录，数值、格式和业务声明继续来自同一个计划。
+    execute = commands.add_parser('run', help='分析计划并发布到全新输出目录')
+    execute.add_argument('plan', help='分析计划YAML或JSON')
+    execute.add_argument('--output', required=True, help='全新输出目录，不覆盖已有文件或目录')
+    execute.add_argument('--work-dir', default=None, help='可选全新工作目录；省略沿AnalysisRunner唯一专用暂存')
+    execute.add_argument('--backend', choices=('reference', 'numpy'), default=None,
+                         help='显式覆盖本次后端；省略沿用计划声明')
+    batch = commands.add_parser('batch', help='独立分析任务批量运行')
+    batch_actions = batch.add_subparsers(dest='batch_command', required=True)
+    batch_run = batch_actions.add_parser('run', help='执行批量YAML或JSON并保存逐任务状态')
+    batch_run.add_argument('plan', help='批量YAML或JSON，各任务计划路径相对此文件目录')
+    batch_run.add_argument('--output', required=True, help='全新批量输出目录')
+    batch_run.add_argument('--process-count', type=int, default=None, help='可选覆盖同时运行数，须为正整数')
+    legacy = commands.add_parser('legacy', help='旧配置迁移')
+    actions = legacy.add_subparsers(dest='legacy_command', required=True)
+    migrate = actions.add_parser('import', help='保留原INI，生成可校验计划及迁移报告')
+    migrate.add_argument('ini', help='原INI文件')
+    migrate.add_argument('--mode', required=True,
+        choices=('legacy_sum', 'sclicer_single', 'sclicer_start_only', 'sclicer_slope', 'sclicer_start_end'))
+    migrate.add_argument('--mapping', required=True, help='显式映射YAML或JSON，来源路径相对此文件目录')
+    migrate.add_argument('--output', required=True, help='新计划.json；原文/报告使用同名前缀，不覆盖已有目标')
+    return parser
+
+
+def _brief(result, files) -> dict:
+    """生成固定摘要，不将全部原字段或warnings输出到控制台。
+
+    参数: result为完整导入结果；files为已实际发布的固定路径模型。
+    返回: 原生JSON对象，三路径为绝对str，转换失败plan为None。
+    异常: 内部typed接口不符直接传播，不以自由反射吞掉错误。
+    """
+    issues = result.report.issues
+    return dict(status=result.report.status, plan=None if files.plan is None else str(files.plan),
+        original=str(files.original), report=str(files.report), device_label=result.report.device_label,
+        issue_count=len(issues), error_count=sum(item.level == 'error' for item in issues),
+        warning_count=sum(item.level == 'warning' for item in issues))
+
+
+def _issue_text(issue) -> str:
+    """将首个错误压缩为可跳转位置，完整事实留在迁移报告。
+
+    参数: issue为固定导入问题。返回: 一行文本，含来源/路径及存在的行列。
+    异常: 内部字段类型错误传播，不截掉报告中的原始消息。
+    """
+    location = issue.origin + ':' + issue.path
+    if issue.line is not None:
+        location += ':' + str(issue.line)
+        if issue.column is not None:
+            location += ':' + str(issue.column)
+    return location + ' [' + issue.code + '] ' + issue.message.replace('\n', ' ')
+
+
+def _run_import(arguments) -> int:
+    """调用真实两配置加载与计划最后发布，静态成功不代表数据运行通过。
+
+    参数: arguments为argparse已经校验的legacy import参数。
+    返回: 0为完整转换/发布成功，2为原配置整体拒绝且原文/报告已保存。
+    异常: 文件/平台/取消/资源错误原样向main传播，保发布器恢复owner。
+    """
+    from .migration import load_legacy_ini
+    from .migration.publication import write_legacy_import
+    # 环境未声明时只标pending；CLI不把当前文件位置猜成home或work。
+    label = os.environ.get('CHRONAXIS_DEVICE_LABEL', '').strip() or 'pending'
+    ini, mapping = Path(arguments.ini).absolute(), Path(arguments.mapping).absolute()
+    result = load_legacy_ini(ini, mapping, mode=arguments.mode, device_label=label)
+    files = write_legacy_import(result, arguments.output, source_paths=(ini, mapping))
+    print(json.dumps(_brief(result, files), ensure_ascii=False, allow_nan=False))
+    if result.plan is None:
+        issue = next((item for item in result.report.issues if item.level == 'error'), None)
+        print('导入失败：' + (_issue_text(issue) if issue is not None else '配置不能整体转换'), file=sys.stderr)
+        return 2
+    return 0
+
+
+def main(argv=None) -> int:
+    """执行共享CLI并给出固定退出码，完整事实保在报告和原异常中。
+
+    参数: argv为参数字符串序列或None（使用进程参数）。
+    返回: 0成功、2配置错误、1文件/平台错误、130取消。
+    异常: argparse帮助/参数错误按标准抛SystemExit；MemoryError及内部编程错误不伪装配置错误。
+    副作用: 导入读取两配置并发布；静态命令只读计划；run分析后发布到新目录。
+    """
+    arguments = _parser().parse_args(argv)
+    operation = {'legacy': '导入', 'guide': '资料读取'}.get(arguments.command, '计划')
+    try:
+        if arguments.command == 'guide':
+            # 默认只定位已经存在的README；显式output才生成独立副本。
+            from .user_guide import export_guide, guide_path
+            print(export_guide(arguments.output) if arguments.output else guide_path(arguments.language))
+            return 0
+        if arguments.command == 'config':
+            from .configuration.cli import run_configuration_cli
+            return run_configuration_cli(arguments)
+        if arguments.command == 'legacy':
+            return _run_import(arguments)
+        if arguments.command == 'batch':
+            from .batch.cli import run_batch_cli
+            return run_batch_cli(arguments)
+        # 帮助和参数错误先由argparse结束；只有实际计划命令才加载计划依赖。
+        from .analysis_cli import run_static, run_analysis
+        return run_analysis(arguments) if arguments.command == 'run' else run_static(arguments)
+    except KeyboardInterrupt:
+        # 发布器已尝试最小收尾并保恢复owner；CLI退出后系统还会关闭进程持有的FD。
+        if arguments.command == 'legacy':
+            message = '导入已取消；目标目录中的原文和迁移报告可用于核对已保存内容。'
+        elif arguments.command == 'run':
+            message = '分析已取消；输出可能已发布，请核对目标目录 ' + str(Path(arguments.output).absolute())
+        elif arguments.command == 'batch':
+            message = '批量操作已取消；请核对各任务结果和批量报告目录 ' + str(Path(arguments.output).absolute())
+        else:
+            message = '计划操作已取消。'
+        print(message, file=sys.stderr)
+        return 130
+    except NotImplementedError as error:
+        print(operation + '功能不可用：' + str(error), file=sys.stderr)
+        return 1
+    except OSError as error:
+        print(operation + '文件操作失败：' + str(error), file=sys.stderr)
+        return 1
+    except ValueError as error:
+        if arguments.command in ('run', 'batch'):
+            # run只把明确的配置异常归为2；未包装的内部ValueError仍保原异常传播。
+            from .planning.checks import PlanValidationError
+            if not isinstance(error, PlanValidationError):
+                raise
+        # 共享语法加载增加一层配置错误，仍沿有限原异常链区分真实文件失败。
+        from .analysis_cli import _cause_chain
+        file_error = any(isinstance(cause,OSError) for cause in _cause_chain(error))
+        if arguments.command in ('validate','explain') and arguments.format=='json':
+            from .planning.checks import PlanValidationError
+            if isinstance(error,PlanValidationError):
+                print(json.dumps(dict(valid=False,error=error.to_dict()),ensure_ascii=False,allow_nan=False))
+                return 1 if file_error else 2
+        print(operation + ('文件操作失败：' if file_error else '配置错误：') + str(error), file=sys.stderr)
+        return 1 if file_error else 2

chronaxis/configuration/__init__.py

@@ -0,0 +1,46 @@
+"""共享配置语法入口；只读指定文件，返回原生值和加载期位置，不读取业务输入。"""
+from pathlib import Path
+from types import MappingProxyType
+
+from .models import ConfigurationDocument, ConfigurationError, ConfigurationLocation, field_path_text
+from .json_parser import parse_json
+
+__all__=['ConfigurationDocument','ConfigurationError','ConfigurationLocation',
+         'field_path_text','parse_configuration','load_configuration']
+
+
+def parse_configuration(text, *, format, source='<configuration>'):
+    """解析显式格式文本。参数: str文本、json/yaml格式、显示来源。返回: 文档。异常: 语法或参数错误。
+
+    不替换环境变量或执行模板。UTF-8文件开头的BOM可选；字段原始字符串保留。
+    """
+    if type(text) is not str or type(source) is not str:
+        raise TypeError('配置内容和来源名称需要文本')
+    if type(format) is not str or format not in ('json','yaml'):
+        raise ConfigurationError(source,(),None,'unsupported_format','配置格式只支持json或yaml')
+    if text.startswith('\ufeff'):text=text[1:]
+    if format=='json':
+        data,locations=parse_json(text,source)
+    else:
+        from .yaml_parser import parse_yaml
+        data,locations=parse_yaml(text,source)
+    return ConfigurationDocument(data,source,format,MappingProxyType(locations))
+
+
+def load_configuration(path):
+    """按.json/.yaml/.yml加载UTF-8文件。返回: 文档。异常: 定位读取/语法错误；取消原样传播。
+
+    后缀不识别时不打开文件；读取结束即关闭句柄，再解析文本，不持有调用者输入文件。
+    """
+    if not isinstance(path,(str,Path)):
+        raise TypeError('配置路径需要Path或文本')
+    target=Path(path).absolute()
+    format={'.json':'json','.yaml':'yaml','.yml':'yaml'}.get(target.suffix.lower())
+    if format is None:
+        raise ConfigurationError(str(target),(),None,'unsupported_format','配置后缀需要.json、.yaml或.yml')
+    try:
+        with target.open('r',encoding='utf-8-sig') as stream:
+            text=stream.read()
+    except (OSError,UnicodeError) as error:
+        raise ConfigurationError(str(target),(),None,'load_error',str(error)) from error
+    return parse_configuration(text,format=format,source=str(target))

chronaxis/configuration/cli.py

@@ -0,0 +1,41 @@
+"""配置辅助命令；复用同一模板及配置入口，不执行分析。"""
+from .template_catalog import available_templates
+from .initialization import initialize_configuration
+
+
+def run_configuration_cli(arguments):
+    """执行已解析的配置命令。参数: argparse结果。返回: 退出码。异常: 配置/文件/取消上交CLI。
+
+    初始化显示实际入口与合成预期；可运行不代表适合真实设备。
+    """
+    if arguments.config_command=='origins':
+        from .origins import configuration_origins,render_origins
+        import json
+        report=configuration_origins(arguments.input,fields=arguments.fields)
+        print(json.dumps(report,ensure_ascii=False,indent=2) if arguments.format=='json' else render_origins(report),
+              end='\n' if arguments.format=='json' else '')
+        return 0
+    if arguments.config_command=='convert':
+        from .file_tools import convert_configuration
+        path=convert_configuration(arguments.input,arguments.output)
+        print('已转换：'+str(path)+'；配置类型和值保持，注释不保留。')
+        return 0
+    if arguments.config_command=='resolve':
+        from .resolution import resolve_configuration
+        result=resolve_configuration(arguments.input,output=arguments.output,format=arguments.format,defaults=arguments.defaults)
+        if arguments.output is None:print(result,end='')
+        else:print('已导出有效配置：'+str(result)+'；路径固定为原输入的绝对位置。')
+        return 0
+    if arguments.list:
+        if arguments.scene is not None or arguments.output is not None:
+            raise ValueError('--list不能同时指定场景或输出目录')
+        for template in available_templates():print(template.name+' — '+template.title)
+        return 0
+    if arguments.scene is None or arguments.output is None:
+        raise ValueError('初始化需要场景名和--output新目录；用--list查看场景')
+    path=initialize_configuration(arguments.scene,arguments.output,style=arguments.style)
+    template=next(t for t in available_templates() if t.name==arguments.scene)
+    print('已生成合成场景：'+str(path))
+    print('预期：'+template.expected)
+    print('真实使用前请核实单位、方向、有效期和阈值。')
+    return 0

chronaxis/configuration/diagnostics.py

@@ -0,0 +1,107 @@
+"""为配置错误附上原文位置与有限的上下文；成功计划不保存此处的文档对象。
+
+这里只消费已解析的原生值，不重新读取配置或来源。字段路径采用带引号键的
+JSON路径；不存在字段回指最近所属对象，不能给缺少的值捏造行列。
+"""
+import json
+import re
+
+from .models import field_path_text
+
+
+def field_path_parts(text):
+    """读取内部字段路径。参数: $开头文本。返回: tuple或无法定位时None。异常: 无。
+
+    引号键用标准JSON解码，不执行表达式；组合诊断如$.signals/derived不能冒充字段。
+    """
+    if not isinstance(text,str) or not text.startswith('$'):
+        return None
+    parts=[]
+    position=1
+    while position<len(text):
+        if text[position]=='.':
+            match=re.match(r'[^.\[\]/]+',text[position+1:])
+            if match is None:
+                return None
+            parts.append(match[0])
+            position+=len(match[0])+1
+        elif text[position:position+2]=='["':
+            try:
+                key,end=json.JSONDecoder().raw_decode(text,position+1)
+            except ValueError:
+                return None
+            if type(key) is not str or text[end:end+1]!=']':
+                return None
+            parts.append(key)
+            position=end+1
+        else:
+            match=re.match(r'\[(0|[1-9][0-9]*)\]',text[position:])
+            if match is None:
+                return None
+            parts.append(int(match[1]))
+            position+=len(match[0])
+    return tuple(parts)
+
+
+def child_path(path,key):
+    """追加一层真实键。参数: 字段路径/字符串键。返回: 无歧义路径。异常: 内部路径不合法。
+    """
+    return path+field_path_text((key,))[1:]
+
+
+def value_preview(value):
+    """只显示有限值摘要。参数: JSON原生值。返回: 最多180字符。异常: 无。
+
+    容器仅报类型/大小，防止错误输出整份配置、内存行或自由元数据。
+    """
+    if type(value) is dict:
+        return f'对象（{len(value)}个字段）'
+    if type(value) is list:
+        return f'数组（{len(value)}项）'
+    text=json.dumps(value,ensure_ascii=False,allow_nan=False)
+    return text if len(text)<=180 else text[:177]+'…'
+
+
+def locate_error(error,document):
+    """给计划异常补充有限诊断字段。参数: 计划异常/原文档。返回: 同一异常。异常: 无。
+
+    不保存document、原字典或位置表；只复制源码名、单一位置、对象名和短值。
+    """
+    # 导入器可能已经把异常定位到另一个文件；外层不得用主文件覆盖真实来源。
+    if error.source is not None:return error
+    parts=field_path_parts(error.path)
+    error.source=document.source
+    if parts is None:
+        error.refresh_text()
+        return error
+    error.location=document.location_for(parts)
+    current=document.data
+    name=None
+    labels={'signals':'信号','sources':'来源','rules':'规则','windows':'窗口',
+            'calculations':'计算项','sequences':'序列','jobs':'任务','presets':'预设'}
+    label=next((labels[part] for part in parts if part in labels),'对象')
+    # 从根走向出错字段，最近的命名对象比根dataset更能解释该处声明。
+    missing=False
+    for part in (*parts,None):
+        if type(current) is dict:
+            candidate=current.get('name')
+            if type(candidate) is str:
+                name=candidate[:120]
+        if part is None:
+            break
+        if type(current) is dict and type(part) is str and part in current:
+            current=current[part]
+        elif type(current) is list and type(part) is int and part<len(current):
+            current=current[part]
+        else:
+            missing=True
+            break
+    error.object_name=None if name is None else label+' '+name
+    error.value_preview='未提供' if missing else value_preview(current)
+    origin=document.origin_for(parts)
+    if origin is not None:
+        error.source=origin.source
+        error.path=field_path_text(origin.field_path)
+        error.location=origin.location
+    error.refresh_text()
+    return error

chronaxis/configuration/explanation.py

@@ -0,0 +1,233 @@
+"""把已验证的分析声明讲成人可阅读的步骤；不加载来源、不展开运行时数据。
+
+文本与JSON报告使用同一计划和能力报告。这里仅翻译已知术语、格式化精确时间，
+并从原始声明区分显式设置与默认设置，不建立另一套配置默认值或执行规则。
+"""
+from collections.abc import Mapping
+
+
+OPERATIONS={
+    'integral':'积分（按前值保持累计）',
+    'sample_mean':'样本均值（每个有效样本权重相同）',
+    'time_weighted_mean':'时间加权均值（按有效持续时间加权）',
+    'sample_minimum':'有效样本最小值','sample_maximum':'有效样本最大值',
+    'min_time':'有效时间区间内最小值','max_time':'有效时间区间内最大值',
+    'duration':'条件成立的累计时长','select':'选择符合条件的记录',
+}
+RULES={'condition_duration':'条件持续成立','rising_edge':'由假变真的上升沿',
+       'falling_edge':'由真变假的下降沿','start_only':'触发后保留固定窗口',
+       'window_delta':'回看窗口内变化量','debounce':'条件去抖','hysteresis':'进入与退出使用不同条件',
+       'start_end':'开始条件启动、结束条件停止'}
+SOURCES={'memory':'配置中的内存数据','signal_csv':'已解码信号CSV',
+         'can_blf':'CAN二进制BLF','can_asc':'CAN文本ASC','asc_or_blf':'CAN连续ASC/BLF','raw_can_csv':'原始CAN帧CSV'}
+
+
+def time_text(nanoseconds):
+    """无损显示纳秒时长。参数: 整数或None。返回: 带单位文本。异常: 无。"""
+    if nanoseconds is None:
+        return '未设置'
+    for divisor,unit in ((10**9,'s'),(10**6,'ms'),(1000,'us')):
+        if nanoseconds and nanoseconds%divisor==0:
+            return str(nanoseconds//divisor)+unit
+    return str(nanoseconds)+'ns'
+
+
+def _declared(plan,*parts):
+    """检查原声明是否包含字段。参数: 计划/路径。返回: bool。异常: 无；不取文件默认值。"""
+    current=plan.raw_config
+    for part in parts:
+        if isinstance(current,Mapping) and part in current:
+            current=current[part]
+        elif type(current) is tuple and type(part) is int and 0<=part<len(current):
+            current=current[part]
+        else:
+            return False
+    return True
+
+
+def _setting(plan,label,value,*parts):
+    """显示实际生效值及其来源。参数: 计划/标签/值/路径。返回: 文本。异常: 无。"""
+    if type(value) is bool:
+        value='开启' if value else '关闭'
+    source='配置指定' if _declared(plan,*parts) else '默认'
+    return f'{label}={value}（{source}）'
+
+
+def _scope(value):
+    """解释计算/输出范围。参数: 已校验范围文本。返回: 中文及具体ID。异常: 无。"""
+    if value=='session':
+        return '整个会话'
+    prefix,_,identifier=value.partition(':')
+    return ('每个事件 ' if prefix=='event' else '每个窗口片段 ')+identifier
+
+
+def _validation_lines(validation):
+    """保留报告中全部错误与限制。参数: ValidationReport。返回: 文本行。异常: 无。"""
+    lines=['静态检查通过：当前声明有可用执行路径。' if validation.valid and validation.execution_ready
+           else '静态检查未通过：请修正以下问题。']
+    lines.extend('错误：'+message for message in validation.errors)
+    lines.append('此检查尚未读取日志、信号表或DBC；未验证实际字段、数据覆盖和内存峰值。')
+    lines.extend('提示：'+message for message in validation.warnings)
+    return lines
+
+
+def validation_text(plan,validation):
+    """生成简短校验说明。参数: 已加载计划/同次报告。返回: 多行文本。异常: 无。"""
+    return '\n'.join([f'分析 {plan.dataset.dataset_id}：{len(plan.sources)}个来源，'
+        f'{len(plan.signals)}个信号，{len(plan.rules)}个事件规则，'
+        f'{len(plan.calculations)+len(plan.message_calculations)}个计算项。',
+        *_validation_lines(validation)])
+
+
+def _rule_lines(plan):
+    """说明事件、窗口和请求响应的有效声明。参数: 计划。返回: 文本行。异常: 内部模型不符。"""
+    lines=[]
+    rule_indices={item['name']:index for index,item in enumerate(plan.raw_config.get('rules',()))}
+    for rule in plan.rules:
+        index=rule_indices.get(rule.rule_id)
+        line=f'  {rule.rule_id}：{RULES[rule.rule_type]}；条件 {rule.condition.text}'
+        if rule.minimum_duration_ns is not None:
+            line+=('；持续严格超过 ' if rule.duration_comparison == '>' else '；至少持续 ')+time_text(rule.minimum_duration_ns)
+            line+='；统计从'+('首次成立' if rule.selection_origin=='onset' else '持续确认')+'时刻开始'
+        if rule.window_duration_ns is not None:
+            line+='；固定窗口 '+time_text(rule.window_duration_ns)
+        if rule.exit_condition is not None:
+            line+='；退出条件 '+rule.exit_condition.text
+        if rule.stability is not None:
+            line+='；进入稳定 '+time_text(rule.stability.enter_ns)+'，退出稳定 '+time_text(rule.stability.exit_ns)
+        if rule.window_delta is not None:
+            spec=rule.window_delta
+            line+=f'；回看 {time_text(spec.window_ns)}，门槛 {spec.threshold}，方向 {spec.direction}，单调约束 {spec.monotonic}'
+        if rule.start_end is not None:
+            line+='；等待上限 '+('不限制' if rule.start_end.timeout_ns is None else time_text(rule.start_end.timeout_ns))
+        # 开始/结束规则的首次策略存于专用规格；活动和稳定性规则没有该配置项。
+        if rule.rule_type not in ('condition_duration','debounce','hysteresis'):
+            emit=rule.start_end.emit_initial if rule.start_end is not None else rule.emit_initial
+            setting=_setting(plan,'首次已知条件触发',emit,'rules',index,'emit_initial')
+            line+='；'+(setting if index is not None else setting.replace('（默认）','（由预设展开）'))
+        lines.append(line)
+    for window in plan.windows:
+        merge={'none':'分别保留','overlap':'合并重叠片段','overlap_and_adjacent':'合并重叠或相邻片段',
+               'exit_delay':'按退出延迟合并'}[window.merge]
+        lines.append(f'  窗口 {window.window_id}：来自事件 {window.event}，向前 {time_text(window.pre_ns)}，'
+            f'向后 {time_text(window.post_ns)}，{merge}，退出延迟 {time_text(window.exit_delay_ns)}')
+    for sequence in plan.sequences:
+        lines.append(f'  序列 {sequence.sequence_id}：请求 {sequence.start_rule} → 响应 {sequence.response_rule}；'
+            f'允许延迟 [{time_text(sequence.min_delay_ns)}, {time_text(sequence.max_delay_ns)}]（包含两端）；'
+            f'最多等待 {sequence.max_pending} 个请求')
+    return lines or ['  未声明事件、窗口或请求响应序列。']
+
+
+def explanation_text(plan,report,*,backend_override=None):
+    """按输入→信号→事件→计算→输出说明同一有效计划。参数: 计划/报告/CLI后端。返回: 多行文本。
+
+    异常: 内部接口不符传播，不用默认文案掩盖未实现类型；无输入I/O。
+    """
+    dataset=plan.dataset
+    domain=dataset.domain
+    declared_domain=plan.raw_config['dataset'].get('domain',{})
+    start=declared_domain.get('start',time_text(domain.start_ns) if domain is not None else '')
+    end=declared_domain.get('end',time_text(domain.end_ns) if domain is not None else '')
+    lines=[f'分析 {dataset.dataset_id}：对象 {dataset.entity}，会话 {dataset.session_id}',
+        '请求范围：'+('整文件（没有时间筛选）' if domain is None else
+        f'[{start}, {end})，包含起点，不包含终点'),
+        '输入来源：']
+    for source in plan.sources:
+        config=source.config
+        if source.source_type=='memory':
+            paths='数据已在配置内声明'
+        elif source.source_type=='signal_csv':
+            paths='，'.join(map(str,config.paths))
+        elif source.source_type=='can_blf':
+            paths='，'.join(map(str,config.paths or (config.path,)))
+        else:
+            paths='，'.join(str(item.path) for item in config.inputs)
+        lines.append(f'  {source.name}：{SOURCES[source.source_type]}；{paths}；时间单位 {source.time_unit}，偏移 {time_text(config.offset_ns)}')
+        if source.source_type in ('can_blf','can_asc','asc_or_blf','raw_can_csv'):
+            lines.append(f'    通道 {config.channel + 1}，DBC {config.dbc_path}（缺省信号声明按需读取元数据，未读取报文）')
+    lines.append('输入信号：')
+    signal_paths={}
+    for index,raw in enumerate(plan.raw_config.get('signals',())):
+        if 'signals' in raw:
+            for child_index,child in enumerate(raw['signals']):
+                signal_paths[child['name']]=('signals',index,'signals',child_index)
+        else:
+            signal_paths[raw['name']]=('signals',index)
+    source_types={source.name:source.source_type for source in plan.sources}
+    for index,item in enumerate(plan.signals):
+        signal=item.definition
+        # 未读DBC时直说等待周期，不把None展示为没有有效期或假定无限保持。
+        validity = ('DBC周期的3倍（运行时确定）' if signal.valid_for_ns is None
+                    else time_text(signal.valid_for_ns))
+        location=f'{signal.source}.{signal.field}'
+        if source_types[signal.source] in ('can_blf','can_asc','asc_or_blf','raw_can_csv'):
+            # 人读说明沿用配置通道；内部规范键和机器报告仍保持0基模型合同。
+            from ..sources.can_spec import can_field_from_key
+            field=can_field_from_key(signal.field)
+            location=(f'{signal.source} 通道 {field.channel+1}，报文0x{field.frame_id:X}'
+                      f'（{field.frame_id}），信号 {field.signal}')
+        lines.append(f'  {signal.name} ← {location}；单位 {signal.unit}；'
+            f'有效期 valid_for={validity}；'
+            +_setting(plan,'样本策略','在有效期内沿用最近有效值（backward_hold）',
+                      *signal_paths.get(signal.name,('signals',index)),'sample_policy'))
+    lines.append('  有效期表示一个有效样本最多沿用多久；到期即未知，无效更新覆盖前值，缺口不补零。')
+    if plan.derived:
+        lines.append('派生信号：')
+        lines.extend(f'  {item.definition.name} = {item.definition.expr}；单位 {expression.root.unit}'
+                     for item,expression in zip(plan.derived,plan.derived_expressions))
+    lines.append('事件与时间窗口：')
+    lines.extend(_rule_lines(plan))
+    lines.append('计算项：')
+    for index,calculation in enumerate(plan.calculations):
+        signal='无单独信号' if calculation.signal is None else calculation.signal.text
+        condition='' if calculation.condition is None else '；筛选 '+calculation.condition.text
+        lines.append(f'  {calculation.calculation_id}：{OPERATIONS[calculation.operation]}；'
+            f'{_scope(calculation.scope)}；信号 {signal}；结果单位 {calculation.unit}{condition}；'
+            +_setting(plan,'有效覆盖门槛',calculation.minimum_coverage,'calculations',index,'minimum_coverage')
+            +f'，部分结果策略 {calculation.partial_policy}')
+    for calculation in plan.message_calculations:
+        lines.append(f'  {calculation.calculation_id}：逐消息累计；来源 {calculation.source}；'
+            f'表达式 {calculation.expr.text}；单位 {calculation.unit}；按原消息参数求值，不额外乘时间间隔')
+    if not plan.calculations and not plan.message_calculations:
+        lines.append('  未声明计算项。')
+    lines.append('计算间隔：')
+    choices=report.intervals.resolved if report.intervals is not None else ()
+    for name,choice in choices:
+        description={'actual':'采用实际记录时间差','fixed':'采用指定间隔 '+time_text(choice.step_ns),
+                     'dbc':'运行时从DBC读取周期'}[choice.mode]
+        lines.append(f'  {name}：{description}'+('；驱动信号 '+choice.driver if choice.driver else ''))
+    if not choices:
+        lines.append('  没有使用普通计算间隔的消费者。')
+    lines.append('  固定间隔或DBC周期不延长信号有效期；导出网格独立于计算间隔。')
+    lines.append('输出与默认设置：')
+    lines.append('  '+_setting(plan,'结果表格式',plan.outputs.tables,'outputs','tables')+'；清单格式 JSON')
+    contributions={'none':'关闭','full':'逐条保存'}[plan.outputs.contributions]
+    lines.append('  '+_setting(plan,'逐消息贡献明细',contributions,'outputs','contributions'))
+    for name,label,output in (('signal_csv','信号CSV导出',plan.outputs.signal_csv),
+                              ('can_frames','CAN帧导出',plan.outputs.can_frames)):
+        if output is None:
+            lines.append('  '+label+'：关闭（默认）')
+            continue
+        description='开启，范围 '+output.scope+('，窗口 '+output.window if output.window else '')
+        grid=output.spec.resampling if name=='signal_csv' else output.resampling
+        if name=='signal_csv':
+            description+='；信号 '+', '.join(output.spec.signals)
+        else:
+            description+='；来源 '+output.source+'，格式 '+output.spec.format
+        if grid is None:
+            description+='；保留原始采样，不重采样'
+        else:
+            description+='；独立导出网格 '+('运行时读取DBC周期' if grid.period_ns is None else time_text(grid.period_ns))
+        lines.append('  '+label+'：'+description)
+    backend=plan.execution.backend if backend_override is None else backend_override
+    lines.append('  执行后端='+backend+('（命令行覆盖）' if backend_override is not None else
+        '（配置指定）' if _declared(plan,'execution','backend') else '（默认）'))
+    for field,label in (('batch_rows','每批记录上限'),('memory_budget_bytes','分析层内存预算/字节'),
+                        ('result_buffer_rows','结果缓冲行数'),('spool_quota_bytes','暂存磁盘预算/字节')):
+        value=getattr(plan.execution,field)
+        lines.append('  '+_setting(plan,label,'未设置' if value is None else value,'execution',field))
+    for field,label in (('trace','详细追溯'),('integrity','完整性诊断'),('retain_work','保留现场')):
+        lines.append('  '+_setting(plan,label,getattr(plan.diagnostics,field),'diagnostics',field))
+    lines.append('检查结论：')
+    lines.extend(_validation_lines(report.validation))
+    return '\n'.join(lines)