chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/window_replay.py

@@ -0,0 +1,350 @@
+"""从已封存的新解码历史逐段计算一个窗口的表达式视图。
+
+输入为实际运行绑定、原保持上下文、已编译表达式及域内Interval，坐标为整数纳秒。
+先校验原历史身份，再打开独立状态与完整组游标；窗口前组只建立种子。
+每步按真实更新、依赖TTL、来源终点或窗口末端拆分，返回须close的点/连续视图帧。
+参考与NumPy分别调用既有独立表达式核，不物化完整样本、时间轴或帧列表。
+资源属于本回读对象；原历史、调用方lease和原state借用，不重读旧报文/DBC。
+提前停止不提供本次全文件EOF证明；运行绑定已有完整校验证据与部分回读分开。
+新层保守预算包含前瞻、种子、查询和输出，不能代表外部留存量或进程RSS。
+"""
+
+# 只组合已有封存历史、保持、表达式和精确边界，不实现新的数值或指标算法。
+import numpy as np
+from ..core.decoded_binding import DecodedBindings
+from ..core.expression import CompiledExpression
+from ..core.models import Interval
+from ..results.errors import ResultClosedError
+from .bindings import _fingerprint
+from .boundaries import BoundaryQueries
+from .expressions import ExpressionQueries
+from .history import DecodedHistoryStore, _metadata_bytes
+from .hold import HoldContext, HoldQueries
+from .state import LatestSignalState
+from .temporal_buffer import _BatchRegistry
+
+
+class WindowReplayFrame:
+    """拥有一个时刻的点视图、可选连续视图及本步workspace。
+
+    连续值适用于[time_ns,end_ns)，末点帧的两端相等且continuous_result为None。
+    点视图可能是保持值，只有ExpressionResult.actual_update才表示真实依赖更新。
+    两个子结果和链指针的预算在本帧close后释放，关闭过程中拒绝读取半关闭结果。
+    """
+
+    def __init__(self, owner, cost, time_ns, end_ns, point, continuous):
+        """接收已计账的表达式结果，暂不安装登记。
+
+        参数: owner为回读者；cost为本步bytes；time_ns/end_ns为整数ns；
+            point为点ExpressionResult，continuous为连续结果或None。
+        返回: 新帧。异常: 构造失败由调用方回收子结果和workspace。
+        """
+        # 本帧不复制数组或原样本；链指针及坐标包含在本步固定workspace内。
+        self._owner, self._cost, self._closed, self._closing = owner, cost, False, False
+        self._time, self._end, self._point, self._continuous = time_ns, end_ns, point, continuous
+        self._registry = self._previous = self._next = None
+
+    def _ensure_open(self):
+        """拒绝释放或部分关闭后的读取。
+
+        参数: 无。返回: None。异常: ResultClosedError。
+        """
+        if self._closed or self._closing:
+            raise ResultClosedError('窗口回读帧已关闭或正在关闭')
+
+    @property
+    def closed(self):
+        """读取资源完成状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def time_ns(self):
+        """读取当前点坐标。参数: 无。返回: int纳秒。异常: 关闭时拒绝。"""
+        self._ensure_open()
+        return self._time
+
+    @property
+    def end_ns(self):
+        """读取连续区间排除的右端。参数: 无。返回: int纳秒。异常: 关闭时拒绝。"""
+        self._ensure_open()
+        return self._end
+
+    @property
+    def point_result(self):
+        """读取当前点表达式结果，保留actual_update和原样本。
+
+        参数: 无。返回: ExpressionResult。异常: 关闭时拒绝。
+        """
+        self._ensure_open()
+        return self._point
+
+    @property
+    def continuous_result(self):
+        """读取左闭右开区间的值，末点没有连续面积。
+
+        参数: 无。返回: ExpressionResult或None。异常: 关闭时拒绝。
+        """
+        self._ensure_open()
+        return self._continuous
+
+    def _discard(self):
+        """解除完整或部分链登记，不再次扣账。
+
+        参数: 无。返回: None。异常: 登记取消仍在finally关闭字段。
+        """
+        try:
+            if self._registry is not None:
+                self._registry.discard(self)
+        finally:
+            # 预算已抵销时不能保留可再次释放的金额或大输出引用。
+            self._closed, self._cost = True, 0
+            self._owner = self._point = self._continuous = self._time = self._end = None
+
+    def close(self):
+        """关闭子结果后释放本步申请，取消前可重试、实际扣账后最小关闭。
+
+        参数: 无。返回: None，幂等。异常: 子关闭/预算/取消传播。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        # 每个子结果完成才清字段，保留尚未成功关闭的句柄供下一次close。
+        for name in ('_continuous', '_point'):
+            child = getattr(self, name)
+            if child is not None:
+                child.close()
+                setattr(self, name, None)
+        budget, cost = self._owner._budget, self._cost
+        before, released = budget.ram_bytes, False
+        try:
+            budget.release_ram(cost)
+            released = True
+        finally:
+            if released or budget.ram_bytes == before - cost:
+                self._discard()
+
+
+class HistoricalWindowReplay:
+    """以独立种子状态回读一个有限窗口，原调用方状态不变。
+
+    _front由完整组游标持有且计账，消费以后才请求下一组；不另存历史列表。
+    输出帧登记在固定头指针链中，先前帧在后续失败后仍可读取。
+    单线程推进失败不可重试；close可重试并关闭自有查询、状态和游标。
+    迭代完成仍须close，以便调用方保留最后帧；完成窗口不等于全文件重放到EOF。
+    """
+
+    def __init__(self, history: DecodedHistoryStore, context: HoldContext, bindings: DecodedBindings,
+                 compiled: CompiledExpression, interval: Interval, *, backend='numpy'):
+        """先预留元数据，再核对当前历史与绑定并创建独立回读资源。
+
+        参数: history为sealed新历史；context为原域与来源EOF事实；bindings为实际绑定；
+            compiled为该绑定的表达式；interval为域内含点端的窗口；backend为reference/numpy。
+        返回: 尚未读入种子的新回读者。
+        异常: 类型/域/来源身份/预算/构造取消；保留原异常，不关闭借用历史。
+            持续清理失败时，从异常的window_replay_cleanup_owner取得自有恢复句柄。
+        """
+        if (not isinstance(history, DecodedHistoryStore) or not isinstance(context, HoldContext)
+                or not isinstance(bindings, DecodedBindings) or not isinstance(compiled, CompiledExpression)
+                or not isinstance(interval, Interval)):
+            raise TypeError('窗口回读需要封存历史、保持上下文、实际绑定、编译表达式和Interval')
+        history._check('sealed')
+        if backend not in ('reference', 'numpy'):
+            raise ValueError('窗口回读backend需要reference或numpy')
+        if not context.domain.start_ns <= interval.start_ns <= interval.end_ns <= context.domain.end_ns:
+            raise ValueError('窗口回读范围必须位于原绑定domain内')
+        # 元数据估算只遍历已有冻结树；临时指纹容器和子owner另在申请之后创建。
+        cost = 65536 + len(bindings.sources) * 8192 + 16 * _metadata_bytes((context, interval, bindings.sources))
+        self._budget, self._fixed_cost = history.budget, 0
+        self._closed = self._closing = self._failed = self._done = self._seeded = False
+        self._history = self._compiled = self._interval = self._results = None
+        self._state = self._holds = self._expressions = self._boundaries = self._groups = None
+        self._front = None
+        self._cursor, self._backend = interval.start_ns, backend
+        before = self._budget.ram_bytes
+        try:
+            self._budget.reserve_ram(cost)
+            self._fixed_cost = cost
+            self._history, self._compiled, self._interval = history, compiled, interval
+            self._results = _BatchRegistry()
+            # 匹配实际历史而非同名来源；指纹临时树已由本固定申请覆盖。
+            if {proof.source for proof in bindings.sources} != set(history.validators):
+                raise ValueError('窗口运行绑定与当前历史来源不同')
+            for proof in bindings.sources:
+                validator = history.validators[proof.source]
+                completion = history.source_completions[proof.source]
+                given_completion = next((item for item in context.completions if item.source == proof.source), None)
+                # 封存SHA只证明历史字节；外来观测/EOF及最终批进度仍须对照实际typed事实。
+                # 完成事实缺源时以None拒绝；不创建全源缓存，也不把最后批计数当全源总量。
+                if (proof.history_sha256 != history.hashes[proof.source].hexdigest()
+                        or [proof.progress_count, proof.sample_count] != history.counts[proof.source]
+                        or proof.description_sha256 != _fingerprint(validator.description)
+                        or proof.request_sha256 != _fingerprint(validator.request)
+                        or proof.session_id != completion.session_id
+                        or proof.projected_aliases != validator.request.signal_names
+                        or proof.observation_start_ns != validator.description.observation_start_ns
+                        or proof.observation_end_ns != completion.observed_end_ns
+                        or proof.source_eof != completion.source_eof
+                        or given_completion != completion):
+                    raise ValueError('窗口运行绑定与当前封存历史身份不同')
+            # 当前固定费已覆盖真实投影元数据；回读只持实际样本别名，不补未读取声明的空状态。
+            self._state = LatestSignalState(self._budget, bindings.projected_signals, context.session_id)
+            self._holds = HoldQueries(self._state, context)
+            self._expressions = ExpressionQueries(self._holds, bindings, (compiled,))
+            self._boundaries = BoundaryQueries(self._expressions)
+            # 首步成功预留workspace后才打开组游标及真实FD，构造不读取任何历史记录。
+        except BaseException as exc:
+            # 尚未赋值的失败子构造通过原异常交出句柄，父owner继续持有它的关闭责任。
+            for name, recovery_name in (('_state', 'state_cleanup_owner'),
+                                        ('_holds', 'hold_queries_cleanup_owner'),
+                                        ('_expressions', 'expression_queries_cleanup_owner'),
+                                        ('_boundaries', 'boundary_queries_cleanup_owner')):
+                child = getattr(exc, recovery_name, None)
+                if child is not None:
+                    setattr(self, name, child)
+            if self._fixed_cost == 0 and self._budget.ram_bytes == before + cost:
+                self._fixed_cost = cost
+            try:
+                self.close()
+            except BaseException as cleanup:
+                exc.add_note(f'窗口回读初始化清理附加失败: {type(cleanup).__name__}')
+                # 瞬时取消只重试一次；持续失败仍保留所有未关闭子对象，不能丢失自有费用。
+                if not self._closed:
+                    try:
+                        self.close()
+                    except BaseException as retry:
+                        exc.add_note(f'窗口回读初始化清理重试失败: {type(retry).__name__}')
+                        if not self._closed:
+                            exc.window_replay_cleanup_owner = self
+                            exc.add_note('释放恢复后调用window_replay_cleanup_owner.close()')
+            raise
+
+    @property
+    def closed(self):
+        """读取owner是否完全关闭。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def failed(self):
+        """读取推进失败状态。参数: 无。返回: bool。异常: 无。"""
+        return self._failed
+
+    def _ensure_open(self):
+        """检查owner及借用历史仍可用，不允许故障后继续推进。
+
+        参数: 无。返回: None。异常: ResultClosedError。
+        """
+        if self._closed or self._closing or self._failed:
+            raise ResultClosedError('窗口回读已关闭、正在关闭或推进失败')
+        self._history._check('sealed')
+
+    def __iter__(self):
+        """返回当前独立回读者。参数: 无。返回: self。异常: 无。"""
+        return self
+
+    def _seed(self):
+        """逐个消费窗口前完整组，保留第一个未消费前瞻。
+
+        参数: 无。返回: None。异常: 真实历史/原子state错误传播，外层标失败。
+        """
+        self._groups = self._history.iter_groups()
+        self._front = next(self._groups, None)
+        while self._front is not None and self._front.time_ns < self._interval.start_ns:
+            self._state.apply(self._front)
+            # 上组已经提交state后才推进，原组预算不会早于消费释放。
+            self._front = next(self._groups, None)
+        self._seeded = True
+
+    def _query(self, *, point):
+        """在已预留本步空间内调用原独立后端查询。
+
+        参数: point为是否点视图。返回: 须close的ExpressionResult。
+        异常: 原保持/表达式/预算错误传播；数组shape=(1,), int64纳秒。
+        """
+        if self._backend == 'reference':
+            return self._expressions.query_reference(self._compiled, (self._cursor,), point=point)
+        return self._expressions.query_numpy(self._compiled, np.array([self._cursor], dtype=np.int64), point=point)
+
+    def __next__(self):
+        """先预算再读种子或消费更新，返回一个准确区间及当前点。
+
+        参数: 无。返回: WindowReplayFrame；末点连续视图为None。
+        异常: StopIteration表示窗口完成；任何推进故障标failed，先前输出保持。
+        """
+        self._ensure_open()
+        if self._done:
+            raise StopIteration
+        cost = 65536 + 32768 * len(self._state.definitions)
+        before, owned, frame = self._budget.ram_bytes, False, None
+        point = continuous = None
+        try:
+            self._budget.reserve_ram(cost)
+            owned = True
+            if not self._seeded:
+                self._seed()
+            if self._front is not None and self._front.time_ns == self._cursor:
+                self._state.apply(self._front)
+                self._front = next(self._groups, None)
+            right = self._interval.end_ns
+            if self._cursor < right:
+                boundary = self._boundaries.query_next(self._compiled, after_ns=self._cursor,
+                    next_group_ns=None if self._front is None else self._front.time_ns)
+                try:
+                    right = min(right, boundary.time_ns)
+                finally:
+                    boundary.close()
+            # 种子保持值也返回点视图，真实样本计数必须使用actual_update而非帧数。
+            point = self._query(point=True)
+            if self._cursor < right:
+                continuous = self._query(point=False)
+            frame = WindowReplayFrame(self, cost, self._cursor, right, point, continuous)
+            owned = False
+            self._results.add(frame)
+            if self._cursor == self._interval.end_ns:
+                self._done = True
+            else:
+                self._cursor = right
+            return frame
+        except BaseException:
+            self._failed = True
+            # 清理只作用于本次未交付结果，先前帧及调用方资源不会被撤销。
+            if frame is not None:
+                frame.close()
+            else:
+                try:
+                    if continuous is not None:
+                        continuous.close()
+                finally:
+                    if point is not None:
+                        point.close()
+            raise
+        finally:
+            # 已成功reserve后的返回取消也计入本步清理，未成功不会抵销其他owner。
+            if owned or frame is None and self._budget.ram_bytes == before + cost:
+                self._budget.release_ram(cost)
+
+    def close(self):
+        """按资源依赖关闭自有帧/查询/状态/游标，保留借用历史与原state。
+
+        参数: 无。返回: None，幂等。异常: 子关闭/预算取消，保留尚未完成句柄供重试。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        while self._results:
+            frame = next(iter(self._results))
+            frame.close()
+            self._results.discard(frame)
+        # 先关闭输出和查询，再释放种子状态与前瞻；每个完成以后才清本owner字段。
+        for name in ('_boundaries', '_expressions', '_holds', '_state', '_groups'):
+            child = getattr(self, name)
+            if child is not None:
+                child.close()
+                setattr(self, name, None)
+        cost, before, released = self._fixed_cost, self._budget.ram_bytes, False
+        try:
+            self._budget.release_ram(cost)
+            released = True
+        finally:
+            if released or self._budget.ram_bytes == before - cost:
+                self._closed, self._fixed_cost = True, 0
+                self._front = self._results = self._history = self._compiled = self._interval = None

chronaxis/execution/windows.py

@@ -0,0 +1,173 @@
+"""在分配窗口临时数组和片段元数据前申请预算，并拥有可关闭的查询结果。
+
+输入是caller已提供的完整有限Event tuple、WindowSpec和真实观测Interval。
+独立参考/NumPy内核仍分别扩展、分组、裁剪和计算覆盖，本层不重写数值算法。
+完整冻结输入元数据与N事件临时量在内核前预留，整个workspace由SegmentBatch保有到close。
+仅保守约束新查询层；caller预先物化的输入、外部另存引用和整个进程RSS另行说明。
+不把独立batch当作可跨批分组的流式输入，不读取旧链/历史、不发布公共AnalysisRunner。
+"""
+
+# 仅共享模型、预算和链式生命周期；两种数值执行入口保持独立。
+from ..core.models import Interval
+from ..core.temporal import Event
+from ..core.windows import WindowSpec
+from ..core.windows_reference import build_segments_reference
+from ..core.windows_numpy import build_segments_numpy
+from ..results.budget import ResourceBudget
+from ..results.errors import ResultClosedError
+from .history import _metadata_bytes
+from .temporal_buffer import _BatchRegistry
+
+
+class SegmentBatch:
+    """拥有一份完整窗口结果和预留成本，和其他已交付查询相互独立。
+
+父事件ID/状态/完整SourceRef由片段引用，workspace覆盖这些冻结元数据的存活。
+链指针放在本对象中，关闭不遗留随历史调用数增长的容器槽位。
+"""
+
+    def __init__(self, owner, cost, segments):
+        """在已预留成本中构造局部批，不负责登记。
+
+        参数: owner真实查询、cost bytes、segments独立内核生成的tuple。
+        返回: 新批。异常: 分配/取消由外层抵销成本，未发布不隐藏失败。
+        """
+        self._owner, self._cost, self._segments, self._closed = owner, cost, segments, False
+        self._registry = self._previous = self._next = None
+
+    @property
+    def closed(self):
+        """读取关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def segments(self):
+        """读取本查询全部片段。参数: 无。返回: Segment tuple。异常: ResultClosedError。"""
+        if self._closed:
+            raise ResultClosedError('窗口片段批已关闭')
+        return self._segments
+
+    def _discard(self):
+        """脱离登记并丢弃输出，不重复扣账。
+
+        参数: 无。返回: None。异常: 脱链取消传播，finally仍标closed并丢弃元数据。
+        """
+        try:
+            self._owner._results.discard(self)
+        finally:
+            self._closed, self._cost = True, 0
+            self._owner = self._segments = None
+
+    def close(self):
+        """释放输出成本，区分扣账前后取消，重复关闭幂等。
+
+        参数: 无。返回: None。异常: 预算/取消传播；已抵销时仍完成最小关闭。
+        """
+        if self._closed:
+            return
+        budget, cost = self._owner._budget, self._cost
+        before, released = budget.ram_bytes, False
+        try:
+            budget.release_ram(cost)
+            released = True
+        finally:
+            if released or budget.ram_bytes == before - cost:
+                self._discard()
+
+
+class WindowQueries:
+    """为完整有限窗口输入提供预算边界，自有批必须及时close。
+
+此owner无跨批活动/分组状态，每次build都要求该窗口的完整事件集合。
+数值或协议失败不改变先前输出，也不把一个查询当作下一查询的部分输入。
+"""
+
+    def __init__(self, budget: ResourceBudget, *, backend='numpy'):
+        """校验配置并申请固定生命周期开销后选择实际数值入口。
+
+        参数: 共享budget、reference或numpy后端。返回: 新owner。
+        异常: 类型/后端/预算/取消传播，申请返回取消也抵销固定成本。
+        """
+        if not isinstance(budget, ResourceBudget) or backend not in ('reference', 'numpy'):
+            raise TypeError('窗口查询需要ResourceBudget与reference/numpy后端')
+        self._budget, self._fixed_cost, self._closed = budget, 0, False
+        self._results = self._build = None
+        fixed, before = 65536, budget.ram_bytes
+        try:
+            budget.reserve_ram(fixed)
+            self._fixed_cost = fixed
+            self._results = _BatchRegistry()
+            self._build = build_segments_reference if backend == 'reference' else build_segments_numpy
+        except BaseException:
+            if self._fixed_cost == 0 and budget.ram_bytes == before + fixed:
+                self._fixed_cost = fixed
+            self.close()
+            raise
+
+    @property
+    def closed(self):
+        """读取关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def _ensure_open(self):
+        """拒绝关闭后执行。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed:
+            raise ResultClosedError('窗口查询已关闭')
+
+    def _construct(self, cost, segments):
+        """构造局部结果。参数: 已预留bytes/内核结果tuple。返回: SegmentBatch。异常: 分配/取消。"""
+        return SegmentBatch(self, cost, segments)
+
+    def build(self, events: tuple[Event, ...], spec: WindowSpec, observation: Interval) -> SegmentBatch:
+        """在预算门槛后执行一个完整窗口集合，保留全部真实父事件。
+
+        参数: 完整有序events、冻结spec及实际观测域observation，不用请求补EOF。
+        返回: 须close的SegmentBatch，空事件返回拥有成本的空批。
+        异常: typed协议/窗口归属/排序/时间溢出/预算/内核/交付取消均传播。
+        失败清理本次预留和局部登记，旧批仍可读；无数值状态变化，可再次合法查询。
+        """
+        self._ensure_open()
+        # 此前只做常数空间类型遍历；详细窗口校验中的集合/数值数组由下方预留覆盖。
+        if (type(events) is not tuple or any(not isinstance(event, Event) for event in events)
+                or not isinstance(spec, WindowSpec) or not isinstance(observation, Interval)):
+            raise TypeError('窗口查询需要完整Event tuple/WindowSpec/真实Interval')
+        # N端点/掩码/分组索引为一维数组；参考临时分组、父关联与稳定ID串同样预先计入。
+        # 元数据估算读取完整SourceRef子类字段；保留全workspace至close，不宣称精确RSS。
+        cost = 65536 + 8192 * len(events) + 16 * _metadata_bytes((events, spec, observation))
+        before, reserved, result = self._budget.ram_bytes, False, None
+        try:
+            self._budget.reserve_ram(cost)
+            reserved = True
+            segments = self._build(events, spec, observation)
+            result = self._construct(cost, segments)
+            self._results.add(result)
+            return result
+        except BaseException:
+            try:
+                if result is not None:
+                    result._discard()
+            finally:
+                if reserved or self._budget.ram_bytes == before + cost:
+                    self._budget.release_ram(cost)
+            raise
+
+    def close(self):
+        """关闭全部自有结果再抵销固定成本，支持关闭中断后重试。
+
+        参数: 无。返回: None，幂等。异常: 子结果/预算/取消传播，已扣账字段最小清理。
+        """
+        if self._closed:
+            return
+        # 结果已扣账但脱链取消时可留下closed孤儿，owner最终清理登记且不再次扣账。
+        while self._results:
+            result = next(iter(self._results))
+            result.close()
+            self._results.discard(result)
+        cost, before, released = self._fixed_cost, self._budget.ram_bytes, False
+        try:
+            self._budget.release_ram(cost)
+            released = True
+        finally:
+            if released or self._budget.ram_bytes == before - cost:
+                self._closed, self._fixed_cost = True, 0
+                self._results = self._build = None

chronaxis/guide/README.md

@@ -0,0 +1,70 @@
+# 用 AI 编写 Chronaxis 分析
+
+[English guide](en/README.md)
+
+从这份README开始，再按[任务索引](tasks.json)选择相关示例，只读任务需要的说明。阅读源码中的指南无需先安装Chronaxis、生成文件或导出ZIP；保留仓库目录结构即可。独立资料ZIP使用同一正文，解压时保留完整目录结构。
+
+先向AI提供本README和[资料版本信息](manifest.json)，再按需提供示例、接口或字段说明。未另行注明的相对命令以本README所在目录为起点；已安装环境使用下方工作目录示例；配置内部的ASC、DBC路径相对配置文件所在目录。运行分析需要安装匹配版本的Chronaxis，可用 `python -c "from importlib.metadata import version; print(version('chronaxis'))"` 核对。安装包已经附带普通指南文件，`python -m chronaxis guide`只显示中文README的路径，`--language en`选择英文，不写入或解压资料。源码指南同样直接阅读。资料版本与合成示例不代表私人日志已通过验证。
+
+### 在已安装环境中直接使用
+
+从自己的工作目录执行下列PowerShell命令。它直接读取安装目录的指南和示例，结果写到当前工作目录，不复制或修改安装资料：
+
+```powershell
+$guide = Split-Path (python -m chronaxis guide)
+python "$guide/lookup.py" task CONDITION_ENERGY
+python "$guide/run_analysis.py" "$guide/examples/conditional-energy.yaml" result-energy
+```
+
+下文的相对命令展示源码/独立指南目录用法；在安装环境执行时，也可像上面一样使用完整输入路径和自己的输出目录。
+
+## 安装Chronaxis及默认运行依赖
+
+普通安装本地 wheel 就会自动安装完整运行依赖，支持 BLF、ASC、原始报文 CSV、DBC 解码、已解码信号 CSV 和内存任务；无需添加 `[can]`。下面是在 Windows PowerShell 中创建环境并安装的完整命令；将 wheel 路径替换为实际收到的文件：
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install ".\chronaxis-0.1.0.dev0-py3-none-any.whl"
+.\.venv\Scripts\python.exe -m pip check
+```
+
+在后续命令中用同一个 `.venv\Scripts\python.exe`；无需激活环境。该版本声明并已验证的 CAN 依赖为 `python-can==4.6.1`、`cantools==39.4.3`、`natsort==8.4.0`，由 wheel 的默认依赖统一安装。不要为了消除缺模块错误单独安装任意最新版，也不要更改信号、阈值或 DBC。其他依赖版本不代表已验证支持；实际发布物以其安装元数据为准。本项目未声明发布到在线包索引，不能假定 `pip install chronaxis` 会取得这个包。离线安装须事先备齐依赖。
+
+`dependency_missing` 表示运行环境缺少 CAN 依赖，不是信号绑定内容错误；按错误中的本地 wheel 安装命令修复。即使全部信号元数据已经手填、静态校验通过，实际运行仍需要相应读取/解码依赖。
+
+## 我该读哪几份文件？
+
+第一次使用时先读[从输入到结果](workflow.md)，决定走单次计划、预设还是批量。
+
+1. 从 [任务索引](tasks.json) 找中文需求，只读命中条目的范例、适用条件和相关字段。先用 BLF/ASC＋DBC 场景；已解码信号表用 CSV，不需要 DBC。不要把别的发布版的配置或内部函数混进来。
+2. 写分析配置，使用 YAML 或 JSON，分析版本为整数 3。范例是完整文件；保留 examples/data 相对位置。示例工程数值只适用于合成输入。缺真实时间基准、工程阈值、编码、单位或方向依据时，指出哪项缺失以及它会改变什么结果。
+3. 写 Python，查 [公开 API 索引](api/index.json)，再读对应单个 API 文件。文件用 load_analysis_plan，已展开字典用 AnalysisPlan.from_dict。预设构建得到 PlanFragment，不能直接交给 run。批量返回时逐任务核对状态。
+4. 配置加载 → 检查声明 → 查看依赖 → 运行 → 写出结果。可用命令见下方；Python方式见 [完整调用](run_analysis.py)。报告实际输入、单位、边界、质量和未验证项。计算返回不代表发布完成。
+
+## 一个从输入到结果的任务
+
+需要具体参数时，用标准 Python 在本README所在目录查询，不用读取整份规范：
+
+```text
+python lookup.py task 持续
+python lookup.py api AnalysisRunner
+python lookup.py field valid_for --schema analysis
+python lookup.py field source_type --schema analysis --branch can_asc
+```
+
+字段表给出原规范位置及分支。参见[高风险语义与真实诊断](semantics.md)及[完整字段参考](fields/index.json)。条件必填、引用、时间单位和工程契约以完整规范及运行校验为准，不应把独立分片用作验证器。没有匹配项返回退出码1；先查正确的版本、名称或分支，不自动猜同义字段。
+
+在这份资料的目录运行（Windows/Python 3.12，已安装项目默认运行依赖）：
+
+```text
+python -m chronaxis config init --list
+python -m chronaxis validate examples/conditional-energy.yaml --format json
+python -m chronaxis explain examples/conditional-energy.yaml --format json
+python run_analysis.py examples/conditional-energy.yaml result-energy
+```
+
+这个例子连续读取两卷ASC，用DBC解码状态、电流和电压，要求`state == 0x2 and current >= 10`连续严格超过60秒，再对整个合格事件积分。恰好60秒的第一段被排除；第二段跨越分卷，实际区间为[61,122)秒，结果4000×61/3600000＝0.06777777777777777kWh。默认从条件开始时刻积分，包括最初60秒；`confirmed_ns=121000000001`表示严格超过60秒的确认时刻，不是积分起点。完整配置位于任务`CONDITION_ENERGY`；预设`CHARGE`采用不同电流比较时，不能替代这个任务。
+
+结果目录必须是新的。默认readable_csv在`事件结果.csv`同一行给出精确秒起止和energy_kwh（kWh），先检查每项指标的状态和说明；从run_manifest.json.outputs找到实际文件。原程序交换格式须显式设置outputs.tables为csv或jsonl，才按parent_id关联原表；CLI与清单中的`analysis_outcome`区分无观测、未知、条件未成立、时长不足和已有事件。没有事件不等于能量为0。换成自己的数据时按实际DBC替换路径、ID、信号和条件；已解码信号表仍可选`CSV`任务，不应用合成阈值替用户决定生产参数。
+
+分析命令和配置解释只证明声明和执行路径；加载按需可读 DBC 元数据、展开来源目录，不扫描业务记录。真实运行、输出和关闭完成后才报告成功。独立样例不能证明其他设备具有相同含义。

chronaxis/guide/api/AnalysisError.md

@@ -0,0 +1,14 @@
+# AnalysisError
+
+推荐导入：`from chronaxis import AnalysisError`
+
+<a id="api-AnalysisError"></a>
+## `AnalysisError`
+
+表示分析或结果交付失败；异常本身不承诺旧输出已回滚。
+
+```python
+class AnalysisError(RuntimeError)
+```
+
+继承关系：RuntimeError。下表列本类声明的字段；基类字段及其约束见对应类型链接。