chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/api/AnalysisPlan.md

@@ -0,0 +1,96 @@
+# AnalysisPlan
+
+推荐导入：`from chronaxis import AnalysisPlan`
+
+<a id="api-AnalysisPlan"></a>
+## `AnalysisPlan`
+
+保存一个会话的分析配置，以及静态检查得到的对象。
+
+通过from_dict或load_analysis_plan构建，依次保存输入来源、信号、派生计算、
+条件规则、窗口与指标。实例字段不能重新赋值；原配置及自由元数据
+保存为独立的只读快照，不保留调用者可变字典或列表的引用。
+
+bindings只描述“哪个信号来自哪里”，derived_expressions是已检查的
+表达式结构；二者不表示真实数据已经读取或能够直接运行。
+execution与outputs保存执行及输出声明，创建本类不会启动计算或发布文件。
+
+identity由配置和来源定位声明计算，用于区分计划；不能据此断言CSV内容、
+实际列、内存使用或分析结果已核实。各次构建的绑定和声明相互独立。
+
+```python
+AnalysisPlan(config_version: int, dataset: chronaxis.planning.models.DatasetPlan, sources: tuple[chronaxis.planning.models.SourcePlan, ...], signals: tuple[chronaxis.planning.models.SignalPlan, ...], derived: tuple[chronaxis.planning.models.DerivedPlan, ...], rules: tuple[chronaxis.planning.models.RulePlan, ...], windows: tuple[chronaxis.planning.models.WindowPlan, ...], calculations: tuple[chronaxis.planning.models.CalculationPlan, ...], presets: tuple[chronaxis.planning.preset_models.PresetSpec, ...], preset_bindings: tuple[tuple[chronaxis.planning.preset_models.RoleBinding, ...], ...], execution: chronaxis.planning.models.ExecutionPlan, outputs: chronaxis.planning.models.OutputPlan, bindings: chronaxis.core.declarations.DeclarationBindings, derived_expressions: tuple[chronaxis.core.expression.StaticExpression, ...], metadata: collections.abc.Mapping, raw_config: collections.abc.Mapping, base_dir: pathlib.Path, identity: str, message_calculations: tuple[chronaxis.planning.models.MessageCalculationPlan, ...] = (), sequences: tuple[chronaxis.planning.sequences.SequencePlan, ...] = (), intervals: 'IntervalPlan | None' = None, diagnostics: 'DiagnosticPlan | None' = None) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`config_version`|int|是|无|保存已加载配置的结构版本，当前为整数3。通常调用load_analysis_plan(path)或AnalysisPlan.from_dict(config)建立整个计划，不逐字段手工拼接。|
+|`dataset`|DatasetPlan|是|无|分析对象、会话和请求时间范围。|
+|`sources`|tuple[SourcePlan, ...]|是|无|已解析的来源配置，保持用户声明顺序。|
+|`signals`|tuple[SignalPlan, ...]|是|无|原字段与信号名称、类型、单位及有效期声明。|
+|`derived`|tuple[DerivedPlan, ...]|是|无|由已有信号计算的新信号，例如功率及其元数据。|
+|`rules`|tuple[RulePlan, ...]|是|无|已经检查的布尔条件和时序规则。|
+|`windows`|tuple[WindowPlan, ...]|是|无|已检查的活动或时间点窗口，以及所引用的规则。|
+|`calculations`|tuple[CalculationPlan, ...]|是|无|统计指标及其范围、计算口径、单位和缺失数据策略。|
+|`presets`|tuple[PresetSpec, ...]|是|无|原预设v1声明，冻结并保留生成参数。|
+|`preset_bindings`|tupletuple[[RoleBinding, ...], ...]|是|无|保存预设角色与实际信号的对应关系。加载计划时产生，外层元组与plan.presets顺序一致；内层每个RoleBinding保存contract（角色要求）、definition（选中的原信号定义）、resolution（explicit显式指定或semantic_unique唯一语义匹配）。没有预设时外层为()。使用zip(plan.presets, plan.preset_bindings)配对，再读取binding.definition.name等；见下方调用示例。|
+|`execution`|ExecutionPlan|是|无|计算方式、分批大小和资源预算声明，尚未实际执行。|
+|`outputs`|OutputPlan|是|无|结果表及清单的格式声明，尚未写出文件。|
+|`bindings`|DeclarationBindings|是|无|名称与来源之间的声明关系，不含实际读取的信号值。|
+|`derived_expressions`|tuple[StaticExpression, ...]|是|无|全部派生表达式的检查结果，已拒绝循环依赖。|
+|`metadata`|Mapping|是|无|调用者附加的只读元数据，不改变计算规则。|
+|`raw_config`|Mapping|是|无|解析时保存的内部只读配置快照，不是用户原文，省略字段也未必全部写回。字段可能为内部解析形式；需要可编辑的当前公共配置时使用config resolve。|
+|`base_dir`|Path|是|无|相对来源路径的解释基准，保存为绝对路径。|
+|`identity`|str|是|无|配置及来源定位声明的SHA-256哈希，不是文件内容哈希。|
+|`message_calculations`|tuple[MessageCalculationPlan, ...]|否|()|保存message_calculations配置解析后的逐消息计算项元组；空元组表示没有此类计算。与普通calculations分别执行。|
+|`sequences`|tuple[SequencePlan, ...]|否|()|保存sequences配置解析后的请求/响应配对元组；空元组表示不进行配对。|
+|`intervals`|'IntervalPlan &#124; None'|否|None|当前记录流的有限间隔声明。|
+|`diagnostics`|'DiagnosticPlan &#124; None'|否|None|分别声明追溯、完整性检查与现场留存。|
+
+# 从资料解压目录运行；此文件已定义所需来源、信号和预设。
+plan = load_analysis_plan("examples/preset-charge-minimal.yaml")
+for preset, bindings in zip(plan.presets, plan.preset_bindings):
+    for binding in bindings:
+        print(preset.id, binding.contract.role,
+              binding.definition.name, binding.resolution)
+# demo_preset mode mode explicit
+# demo_preset current current explicit
+```
+
+
+<a id="api-AnalysisPlan-from_dict"></a>
+### `AnalysisPlan.from_dict`
+
+复制配置字典，检查版本3的静态要求；新版本执行能力另行验证。
+
+```python
+AnalysisPlan.from_dict(config: dict, *, base_dir: Path | str | None=None) -> 'AnalysisPlan'
+```
+
+装饰器：`classmethod`, `public_errors`。
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`config`|dict[str, object]|是|无|位置或关键字。当前公开分析配置字典，含config_version=3、dataset、sources和signals；不接受未展开imports。目录声明会枚举文件名，缺省CAN元数据时读取DBC；不读取业务记录。见配置字段参考。|
+|`base_dir`|Path &#124; str &#124; None|否|None|仅关键字。相对来源路径的解释基准；默认None， 使用当前工作目录。传入Path或文本时转换为绝对路径。|
+
+#### 返回说明
+
+AnalysisPlan: 保存经过静态检查的来源、信号及计算节点。
+        raw_config和metadata是独立的只读快照；创建计划不读取分析数据。
+
+#### 异常说明
+
+PlanValidationError: 字段或版本不合法，名称冲突、表达式或引用错误，
+        输入模型不合规，或配置请求尚未接入的能力；错误保留配置位置。
+    OSError: 获取当前工作目录或转换路径时发生系统错误，可原样传播。
+
+#### 处理流程说明
+
+检查当前公开配置并展开节点，解析来源和信号；目录声明枚举文件名，缺省CAN元数据从DBC补全。随后检查引用、类型与单位，构造独立计划；不读取业务记录或执行分析。
+
+返回类型：'AnalysisPlan'。

chronaxis/guide/api/AnalysisResult.md

@@ -0,0 +1,398 @@
+# AnalysisResult
+
+推荐导入：`from chronaxis import AnalysisResult`
+
+<a id="api-AnalysisResult"></a>
+## `AnalysisResult`
+
+一次成功分析的结果对象。通常由AnalysisRunner.run返回；通过iter_*逐行读取，通过write发布，通过close或with释放资源。内部构造参数用于接管暂存，不建议业务调用者手工构造。
+
+```python
+AnalysisResult(spool: chronaxis.results.spool.ResultSpool, metadata: chronaxis.results.manifest.RunMetadata, table_format: str = 'csv', *, artifact_exports=None, owned_work=None)
+```
+
+
+
+<a id="api-AnalysisResult-__init__"></a>
+### `AnalysisResult.__init__`
+
+接管已经结束写入的结果暂存，并记录analysis_complete，表示计算完成、结果可供读取。正式输出目录仍由write生成。
+
+```python
+AnalysisResult.__init__(spool: ResultSpool, metadata: RunMetadata, table_format: str='csv', *, artifact_exports=None, owned_work=None)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`spool`|ResultSpool|是|无|位置或关键字。接管内部执行流程已经写完并排序的ResultSpool。普通调用使用AnalysisRunner.run(...)取得AnalysisResult，不需要手工创建spool；接管后由结果对象负责释放。|
+|`metadata`|RunMetadata|是|无|位置或关键字。此次运行的配置、实际输入、计算方式及观测信息；发布时写入运行清单。|
+|`table_format`|str|否|'csv'|位置或关键字。"csv"保留机器字段的CSV交换表，"jsonl"每行写一个完整JSON对象，"readable_csv"生成中文可读表格。低层构造器默认csv；普通配置与AnalysisRunner默认readable_csv。|
+|`artifact_exports`|ArtifactExportStore &#124; None|否|None|仅关键字。可选的信号表和报文导出文件仓，成功接管后由本结果负责关闭。|
+|`owned_work`|tuple[Path, tuple] &#124; None|否|None|仅关键字。本次私有根路径和创建时目录身份；须是spool直接父目录，None仅接管spool目录。|
+
+#### 返回说明
+
+None；初始化实例状态。
+
+#### 异常说明
+
+传入模型/表格式错误时拒绝构造；预算、暂存或内部清单写入失败可抛AnalysisError并保留cause。构造失败且仍有资源待关时，异常analysis_result_cleanup_owner提供close重试入口。一般调用者应取得AnalysisRunner.run返回的对象，避免自行接管spool。
+
+
+<a id="api-AnalysisResult-run_manifest"></a>
+### `AnalysisResult.run_manifest`
+
+返回当前状态快照，发布失败诊断路径另见manifest_path。
+
+```python
+AnalysisResult.run_manifest: dict
+```
+
+装饰器：`property`。
+
+读取属性，不使用调用括号。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+独立小型dict。
+
+#### 异常说明
+
+关闭后仍可查看诊断，不读文件。
+
+返回类型：dict。
+
+
+<a id="api-AnalysisResult-iter_events"></a>
+### `AnalysisResult.iter_events`
+
+创建独立事件流，不装入全量列表。
+
+```python
+AnalysisResult.iter_events() -> Iterator[SummaryEventRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+可关闭迭代器，逐行产生SummaryEventRow；使用try/finally关闭游标；外层AnalysisResult可用with管理，游标本身不支持with。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭，不能创建或继续读取游标。BudgetExceededError：无法为游标保留预算。OSError：创建或迭代期间读取暂存文件失败。ResultFormatError：迭代时发现行格式、类型或长度不合法。先关闭游标；不要将读取失败当成空结果。
+
+返回类型：Iterator[SummaryEventRow]。
+
+
+<a id="api-AnalysisResult-iter_sequences"></a>
+### `AnalysisResult.iter_sequences`
+
+逐行读取请求配对结果；未配置配对时返回可关闭空游标。
+
+```python
+AnalysisResult.iter_sequences() -> Iterator[SummarySequenceRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+可关闭迭代器，逐行产生SummarySequenceRow；使用try/finally关闭游标；外层AnalysisResult可用with管理，游标本身不支持with。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭，不能创建或继续读取游标。BudgetExceededError：无法为游标保留预算。OSError：创建或迭代期间读取暂存文件失败。ResultFormatError：迭代时发现行格式、类型或长度不合法。先关闭游标；不要将读取失败当成空结果。
+
+返回类型：Iterator[SummarySequenceRow]。
+
+
+<a id="api-AnalysisResult-iter_segments"></a>
+### `AnalysisResult.iter_segments`
+
+创建独立片段流，保留全部父事件关联。
+
+```python
+AnalysisResult.iter_segments() -> Iterator[SummarySegmentRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+可关闭迭代器，逐行产生SummarySegmentRow；使用try/finally关闭游标；外层AnalysisResult可用with管理，游标本身不支持with。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭，不能创建或继续读取游标。BudgetExceededError：无法为游标保留预算。OSError：创建或迭代期间读取暂存文件失败。ResultFormatError：迭代时发现行格式、类型或长度不合法。先关闭游标；不要将读取失败当成空结果。
+
+返回类型：Iterator[SummarySegmentRow]。
+
+
+<a id="api-AnalysisResult-iter_calculations"></a>
+### `AnalysisResult.iter_calculations`
+
+逐行读取计算摘要。检查scope区分会话、事件或片段，同时读取value、unit、status、reason及quality；select样本通过iter_selections读取。
+
+```python
+AnalysisResult.iter_calculations() -> Iterator[SummaryCalculationRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+可关闭迭代器，逐行产生SummaryCalculationRow；相关时间计算设置minimum_coverage大于0时产生带coverage_status的SummaryCoverageCalculationRow。用try/finally关闭游标，不能对游标使用with。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭，不能创建或继续读取游标。BudgetExceededError：无法为游标保留预算。OSError：创建或迭代期间读取暂存文件失败。ResultFormatError：迭代时发现行格式、类型或长度不合法。先关闭游标；不要将读取失败当成空结果。
+
+返回类型：Iterator[SummaryCalculationRow]。
+
+
+<a id="api-AnalysisResult-iter_contributions"></a>
+### `AnalysisResult.iter_contributions`
+
+逐行回查真实贡献与skip，原序号和新求值序号分别保留。
+
+```python
+AnalysisResult.iter_contributions() -> Iterator[SummaryContributionRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+独立有预算游标；逐行返回SummaryContributionRow。
+
+#### 异常说明
+
+ContributionsUnavailableError：outputs.contributions没有请求full，需要修改计划重新运行才有明细。ResultClosedError：结果已关。读取暂存时发生预算、格式或I/O错误会保留异常链；不是输入解码器重新执行。
+
+返回类型：Iterator[SummaryContributionRow]。
+
+
+<a id="api-AnalysisResult-iter_selections"></a>
+### `AnalysisResult.iter_selections`
+
+读取明确请求的真实样本选择行。
+
+```python
+AnalysisResult.iter_selections() -> Iterator[SummarySelectionRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+有预算游标，未请求为空。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭，不能创建或继续读取游标。BudgetExceededError：无法为游标保留预算。OSError：创建或迭代期间读取暂存文件失败。ResultFormatError：迭代时发现行格式、类型或长度不合法。先关闭游标；不要将读取失败当成空结果。
+
+返回类型：Iterator[SummarySelectionRow]。
+
+
+<a id="api-AnalysisResult-iter_input_trace"></a>
+### `AnalysisResult.iter_input_trace`
+
+读取显式请求的所需输入追溯。
+
+```python
+AnalysisResult.iter_input_trace() -> Iterator[SummaryInputRow]
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+逐行产生SummaryInputRow的可关闭游标。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭。AnalysisError：本次未生成输入追溯，需配置diagnostics.trace后重新运行。迭代期间可能传播ResultFormatError、BudgetExceededError和OSError。
+
+返回类型：Iterator[SummaryInputRow]。
+
+
+<a id="api-AnalysisResult-contributions_available"></a>
+### `AnalysisResult.contributions_available`
+
+说明本结果是否允许查询逐消息贡献，不将未生成和零行混为一谈。
+
+```python
+AnalysisResult.contributions_available: bool
+```
+
+装饰器：`property`。
+
+读取属性，不使用调用括号。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+bool；默认未配置逐消息指标仍允许原空游标。
+
+#### 异常说明
+
+无；关闭后可查看这项固定运行事实，但不能重新创建游标。
+
+返回类型：bool。
+
+
+<a id="api-AnalysisResult-write"></a>
+### `AnalysisResult.write`
+
+把暂存中的结果写到全新目录。所有文件完成后写入completed状态，再把临时目录重命名为正式目录；已有目标不会被覆盖。
+
+```python
+AnalysisResult.write(output_dir: str | Path) -> OutputManifest
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`output_dir`|str &#124; Path|是|无|位置或关键字。指定新建的结果目录，传str或Path，例如Path("results/run_01")。按本次输出位置填写；目录已存在时拒绝覆盖。完成后返回OutputManifest，结果对象仍需关闭。|
+
+#### 返回说明
+
+安装成功后的OutputManifest。
+
+#### 异常说明
+
+ResultClosedError：结果已关闭或正在关闭。AnalysisError：目标已存在、目标位于将清理的自有工作目录内、平台不支持安全发布、预算/格式/文件写入失败；原错误通过__cause__保留。修正输出位置或环境后，可向另一新目录重试，不会重读输入。
+
+#### 副作用说明
+
+发布到全新输出目录，不覆盖既有目录。失败时按retain_work决定是否保留本次临时目录；诊断可从异常及run_manifest查看。
+
+返回类型：OutputManifest。
+
+
+<a id="api-AnalysisResult-close"></a>
+### `AnalysisResult.close`
+
+关闭游标并释放资源；默认清理本次程序为本次运行创建的临时数据，retain_work为true时保留现场。原始输入及正式输出保留。
+
+```python
+AnalysisResult.close() -> None
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+None。可重复调用；失败后仍可重试未完成的清理。
+
+#### 异常说明
+
+先尝试关闭所有已取得的资源；文件句柄、暂存清理或预算释放失败时抛出首先发生的错误，后续错误作为补充诊断。确认占用已解除后再次调用close；close可重复，不能仅捕获异常后丢弃该结果对象。
+
+返回类型：None。
+
+
+<a id="api-AnalysisResult-__enter__"></a>
+### `AnalysisResult.__enter__`
+
+进入结果上下文，不再次执行输入读取。
+
+```python
+AnalysisResult.__enter__() -> 'AnalysisResult'
+```
+
+参数：无显式参数。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+返回当前对象本身。后续迭代或with语句使用的仍是同一个对象。
+
+#### 异常说明
+
+ResultClosedError为已关闭。
+
+返回类型：'AnalysisResult'。
+
+
+<a id="api-AnalysisResult-__exit__"></a>
+### `AnalysisResult.__exit__`
+
+退出上下文时释放资源，保留业务原异常。
+
+```python
+AnalysisResult.__exit__(exc_type, exc_value, traceback)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`exc_type`|type[BaseException] &#124; None|是|无|位置或关键字。with代码块抛出的异常类型；正常离开时为None，由Python传入。|
+|`exc_value`|BaseException &#124; None|是|无|位置或关键字。with代码块抛出的异常对象；正常离开时为None，由Python传入。|
+|`traceback`|TracebackType &#124; None|是|无|位置或关键字。异常发生时的调用栈；正常离开时为None，由Python传入，供异常继续传播。|
+
+#### 返回说明
+
+False，异常会继续传给调用者。
+
+#### 异常说明
+
+正常离开with时close失败会传播关闭错误；with内已有业务异常时保留该业务异常，关闭问题附加到诊断信息，避免掩盖真正失败原因。

chronaxis/guide/api/AnalysisRunner.md

@@ -0,0 +1,155 @@
+# AnalysisRunner
+
+推荐导入：`from chronaxis import AnalysisRunner`
+
+<a id="api-AnalysisRunner"></a>
+## `AnalysisRunner`
+
+配置单次分析的执行器。backend可覆盖计划设置；run创建独立资源，返回需关闭的AnalysisResult。通常复用执行器，分别管理每次结果。
+
+```python
+AnalysisRunner(backend=None)
+```
+
+
+
+<a id="api-AnalysisRunner-__init__"></a>
+### `AnalysisRunner.__init__`
+
+选择是否覆盖计划后端，不读取任何来源或配置文件。
+
+```python
+AnalysisRunner.__init__(backend=None)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`backend`|str &#124; None|否|None|位置或关键字。`"reference"`使用独立参考计算；`"numpy"`使用NumPy数组计算。None沿用计划中的选择。|
+
+#### 返回说明
+
+None；初始化实例状态。
+
+#### 异常说明
+
+TypeError为非文本覆盖；ValueError为未知后端。
+
+本函数直接报告的具体错误：
+
+- `TypeError`：AnalysisRunner backend需要reference、numpy或None。
+- `ValueError`：AnalysisRunner仅支持reference与numpy后端。
+
+
+<a id="api-AnalysisRunner-backend"></a>
+### `AnalysisRunner.backend`
+
+读取构造时的覆盖选择，不表示某个尚未运行计划的实际后端。
+
+```python
+AnalysisRunner.backend
+```
+
+装饰器：`property`。
+
+读取属性，不使用调用括号。
+
+
+#### 参数说明
+
+无。
+
+#### 返回说明
+
+None/reference/numpy。
+
+#### 异常说明
+
+无。
+
+
+<a id="api-AnalysisRunner-validate"></a>
+### `AnalysisRunner.validate`
+
+报告声明是否合法及执行路径是否已接入，不提前读取数据。
+
+```python
+AnalysisRunner.validate(plan)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|是|无|位置或关键字。提供已构建的AnalysisPlan：用load_analysis_plan("analysis.yaml")读取配置，或用AnalysisPlan.from_dict(config)解析Python字典；这里不接收文件名字符串。|
+
+#### 返回说明
+
+同一共享ValidationReport，保留实际字段/范围未验警告。
+
+#### 异常说明
+
+TypeError：plan不是AnalysisPlan或其execution不是合法执行模型。正常计划的静态问题通过ValidationReport.errors返回，执行能力看execution_ready；不读取输入，不能把空errors当作实际日志已验证。
+
+#### 副作用说明
+
+无来源I/O或目录创建。
+
+
+<a id="api-AnalysisRunner-explain"></a>
+### `AnalysisRunner.explain`
+
+列出真实依赖、各节点后端、历史需求及声明预算，不启动分析。
+
+```python
+AnalysisRunner.explain(plan)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|是|无|位置或关键字。提供已构建的AnalysisPlan：用load_analysis_plan("analysis.yaml")读取配置，或用AnalysisPlan.from_dict(config)解析Python字典；这里不接收文件名字符串。|
+
+#### 返回说明
+
+ExplainReport，plan_identity保原声明身份。
+
+#### 异常说明
+
+TypeError：plan不是AnalysisPlan或其execution类型不符。手工破坏带有明确类型的引用可能引发AttributeError/KeyError；重新使用from_dict/load_analysis_plan构造合法计划。函数不打开CSV/DBC，不测量实际耗时或内存。
+
+#### 副作用说明
+
+不读取CSV/DBC，也不测量实耗。
+
+
+<a id="api-AnalysisRunner-run"></a>
+### `AnalysisRunner.run`
+
+验证后执行一次真实分析，输入全关才返回独立AnalysisResult。
+
+```python
+AnalysisRunner.run(plan, work_dir=None)
+```
+
+#### 参数
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`plan`|AnalysisPlan|是|无|位置或关键字。提供已构建的AnalysisPlan：用load_analysis_plan("analysis.yaml")读取配置，或用AnalysisPlan.from_dict(config)解析Python字典；这里不接收文件名字符串。|
+|`work_dir`|str &#124; Path &#124; None|否|None|位置或关键字。本次运行独占的工作目录，用来保存中间文件。自行指定时要求尚不存在；不会覆盖旧目录。None让入口自动创建唯一目录。|
+
+#### 返回说明
+
+analysis_complete的AnalysisResult，由调用者close/上下文管理，write另行发布。
+
+#### 异常说明
+
+TypeError为错误plan；验证或运行错误为AnalysisError，保原cause和诊断；
+    KeyboardInterrupt/SystemExit原样传播。持续清理失败用runner_cleanup_owner.close恢复。
+
+#### 副作用说明
+
+创建本次新暂存；扫描来源一次、后续仅回读新history，不自动删除或发布文件。

chronaxis/guide/api/BatchJob.md

@@ -0,0 +1,19 @@
+# BatchJob
+
+推荐导入：`from chronaxis import BatchJob`
+
+<a id="api-BatchJob"></a>
+## `BatchJob`
+
+声明一个独立分析；同会话连续文件应包含在本任务的一个计划中。
+
+```python
+BatchJob(job_id: str, plan: chronaxis.planning.plan.AnalysisPlan | pathlib.Path) -> None
+```
+
+### 属性与数据字段
+
+|名称|数据类型|必填|省略时的值|用途、取值和效果|
+|---|---|---|---|---|
+|`job_id`|str|是|无|设置批量内唯一任务名称，例如test_a；用于结果目录及报告定位，不能与其他任务仅大小写不同。|
+|`plan`|AnalysisPlan &#124; Path|是|无|提供待运行的AnalysisPlan或pathlib.Path，例如Path("analysis.yaml")；直接构造BatchJob时不能传裸字符串。路径在任务真正启动时加载。|