chronaxis 0.1.0.dev0__tar.gz

chronaxis-0.1.0.dev0/Docs/AI/README.md

@@ -0,0 +1,70 @@
+# 用 AI 编写 Chronaxis 分析
+
+[English guide](en/README.md)
+
+从这份README开始，再按[任务索引](tasks.json)选择相关示例，只读任务需要的说明。阅读源码中的指南无需先安装Chronaxis、生成文件或导出ZIP；保留仓库目录结构即可。独立资料ZIP使用同一正文，解压时保留完整目录结构。
+
+先向AI提供本README和[资料版本信息](../Current/documentation.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。范例是完整文件；保留 ../Current/examples/data 相对位置。示例工程数值只适用于合成输入。缺真实时间基准、工程阈值、编码、单位或方向依据时，指出哪项缺失以及它会改变什么结果。
+3. 写 Python，查 [公开 API 索引](../Current/public-api.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)及[完整字段参考](../Current/reference/configuration-schema.md)。条件必填、引用、时间单位和工程契约以完整规范及运行校验为准，不应把独立分片用作验证器。没有匹配项返回退出码1；先查正确的版本、名称或分支，不自动猜同义字段。
+
+在这份资料的目录运行（Windows/Python 3.12，已安装项目默认运行依赖）：
+
+```text
+python -m chronaxis config init --list
+python -m chronaxis validate ../Current/examples/conditional-energy.yaml --format json
+python -m chronaxis explain ../Current/examples/conditional-energy.yaml --format json
+python run_analysis.py ../Current/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-0.1.0.dev0/Docs/AI/en/README.md

@@ -0,0 +1,74 @@
+<a id="用-ai-编写-chronaxis-分析"></a>
+# Use AI to write a Chronaxis analysis
+
+Start with this README, select an example from the [task index](tasks.json), and read only the material needed for the task. Reading the guide in a source checkout requires no installation, generated files, or ZIP export; keep the repository layout intact. The standalone documentation ZIP uses the same text with its own complete directory layout.
+
+Give the AI this README and the [documentation version](../../Current/documentation.json), then supply examples, API descriptions, or field references as needed. Relative commands use the directory containing this README unless noted otherwise; installed users can use the working-directory example below. ASC and DBC paths inside a configuration are relative to that configuration file. Running an analysis requires the matching Chronaxis version; check it with `python -c "from importlib.metadata import version; print(version('chronaxis'))"`. The installed package includes the guide as ordinary files. `python -m chronaxis guide --language en` prints this English README path without writing or extracting anything. Open it directly; source documentation is also directly readable. Version metadata and synthetic examples do not establish that private logs have been verified.
+
+<a id="安装chronaxis及默认运行依赖"></a>
+### Use the installed guide directly
+
+Run these PowerShell commands from your own working directory. They read the installed guide and example directly and put results in your working directory, without copying or modifying the installed material:
+
+```powershell
+$guide = Split-Path (python -m chronaxis guide)
+python "$guide/lookup.py" --language en task CONDITION_ENERGY
+python "$guide/run_analysis.py" "$guide/examples/conditional-energy.yaml" result-energy
+```
+
+The relative commands below illustrate a source or standalone guide directory. For installed examples, use full input paths and your own output directory as above.
+
+## Install Chronaxis and its default dependencies
+
+Installing the local wheel installs the runtime dependencies for BLF, ASC, raw-message CSV, DBC decoding, decoded-signal CSV, and memory tasks. No `[can]` suffix is required. On Windows PowerShell, replace the wheel path with the actual file:
+
+```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
+```
+
+Use the same `.venv\Scripts\python.exe` for subsequent commands; activation is optional. This version declares and has been checked with `python-can==4.6.1`, `cantools==39.4.3`, and `natsort==8.4.0`, installed through the wheel's default dependencies. Do not install an arbitrary latest version to fix a missing module, or change signals, thresholds, or the DBC. Other dependency versions are not thereby verified; use the actual distribution's installation metadata. Prepare dependency wheels in advance for offline installation.
+
+`dependency_missing` means the environment lacks required CAN dependencies, not that a signal binding is wrong. Follow the local-wheel installation command in the error. Even if every signal's metadata is supplied manually and static validation passes, execution still needs the appropriate reading and decoding dependencies.
+
+<a id="我该读哪几份文件"></a>
+## Which files should I read?
+
+First read [from input to results](workflow.md) to choose a single analysis, preset, or independent batch.
+
+1. Search the [task index](tasks.json) for the requested task. Read that entry's example, applicability, and related fields. Start with BLF/ASC plus DBC for CAN tasks. Decoded CSV tables do not need a DBC. Do not mix configuration or internal functions from another release.
+2. Write YAML or JSON using integer `config_version: 3`. Examples are complete files; preserve the layout under `../../Current/examples/data`. Their engineering values apply only to the synthetic inputs. If the real time basis, thresholds, encoding, units, or direction are missing, explain which fact is missing and how it changes the result.
+3. For Python, consult the [public API index](../../Current/en/public-api.json), then the individual API page. Use `load_analysis_plan` for files and `AnalysisPlan.from_dict` for expanded dictionaries. Preset construction returns a `PlanFragment`, which cannot be passed directly to `run`. Inspect every task status after a batch returns.
+4. Load the configuration, validate declarations, inspect dependencies, run, and write the output. Commands are below; the [complete Python call](../run_analysis.py) provides the executable path. Report actual inputs, units, boundaries, quality, and unverified parts. Returning from calculation is not the same as publishing results.
+
+<a id="一个从输入到结果的任务"></a>
+## A complete task
+
+Query the material with standard Python from this README's directory instead of reading the whole specification:
+
+```text
+python ../lookup.py --language en task energy
+python ../lookup.py --language en api AnalysisRunner
+python ../lookup.py --language en field valid_for --schema analysis
+python ../lookup.py --language en field source_type --schema analysis --branch can_asc
+```
+
+Field tables identify their specification location and branch. See [semantics and diagnostics](semantics.md) and the [complete field reference](../../Current/en/reference/configuration-schema.md). Conditional requirements, references, time units, and engineering requirements depend on the complete specification and runtime validation. Individual field extracts are not standalone validators. A query without matches exits with code 1: check the version, name, or branch instead of inventing an equivalent field.
+
+On Windows with Python 3.12 and the package's default runtime dependencies installed:
+
+```text
+python -m chronaxis config init --list
+python -m chronaxis validate ../../Current/examples/conditional-energy.yaml --format json
+python -m chronaxis explain ../../Current/examples/conditional-energy.yaml --format json
+python ../run_analysis.py ../../Current/examples/conditional-energy.yaml result-energy
+```
+
+This example reads two continuous ASC volumes and decodes state, current, and voltage with a DBC. It requires `state == 0x2 and current >= 10` for strictly more than 60 seconds, then integrates over the entire qualifying event. The first activity lasts exactly 60 seconds and is excluded. The second crosses the file boundary, covers `[61,122)` seconds, and gives `4000 × 61 / 3600000 = 0.06777777777777777 kWh`. Integration starts at condition onset by default, including the first 60 seconds. `confirmed_ns=121000000001` is the strict-duration confirmation time, not the integration start. Use task `CONDITION_ENERGY`; `CHARGE` is not a replacement when its current comparison differs.
+
+The output directory must be new. Default `readable_csv` output places exact-second boundaries and `energy_kwh（kWh）` on the same row in `事件结果.csv` (event results). Check each metric's status and explanation. Discover actual file paths through `run_manifest.json.outputs`. To consume original interchange tables linked by `parent_id`, explicitly select `outputs.tables: csv` or `jsonl`. CLI and manifest `analysis_outcome` distinguish no observation, unknown conditions, conditions not met, insufficient duration, and detected events. No event does not mean zero energy.
+
+For your own data, replace paths, IDs, signals, and conditions using the actual DBC. Decoded tables can use task `CSV`. Do not treat synthetic thresholds as the user's production parameters.
+
+Validation and explanation establish declaration validity and supported execution paths. Loading may read DBC metadata or enumerate directories as needed, but it does not scan business records. Report success only after actual execution, publication, and cleanup finish. An independent example does not establish that another device has the same business meaning.

chronaxis-0.1.0.dev0/Docs/AI/en/semantics.md

@@ -0,0 +1,70 @@
+<a id="先决定什么能算再生成配置"></a>
+# Establish what can be calculated before generating configuration
+
+| Task | Facts to establish | How to decide |
+|---|---|---|
+| Identify inputs | BLF/ASC logs, DBC, channel, message, and signal; actual CSV headers and time units. | Joint analysis of different clocks needs a common origin, offset, or other explicit synchronization evidence. Both files starting at zero is insufficient. |
+| Bind names | Locate the original input field. `name` is its analysis name; `semantic_id` is optional business metadata. | If `BMS_I` is bound as `pack_current` with semantic ID `battery.current`, write `pack_current > 5`. A dotted semantic ID is not an object attribute. Require an explicit choice when multiple candidates match. |
+| Units and direction | Existing DBC conversion, physical unit, positive direction, and measurement point. | Converting decoded 2000 mA to 2 A needs only the additional unit conversion. Unit labels and `sign_convention` do not change values. There is no public `direction_factor`; same-unit `scale=-1` is not a general sign-flip mechanism. |
+| State codes | The business meaning of each code. | Whether 2 means charging depends on the equipment. Preserve numeric types for a user-supplied comparison such as `state == 0x2`. Use Boolean/enumeration mappings only when true/false or named states are needed. Unknown mapping codes do not mean nonzero=true. Without definitions, identify the missing facts rather than claiming a production-ready charging detector. |
+| Validity | `valid_for` is a positive duration. An explicit value wins; otherwise use three times this signal's `period`, obtaining a DBC message period at runtime where applicable. Do not guess without a basis. Explicit null is not omission. | With an update at 0 and `period=100ms`, the value remains valid at 0.299 s and becomes unknown at 0.300 s. An invalid update at 0.2 s makes it unknown from 0.2 s. Validity does not set a sample rate or create records. |
+| Conditions and statistics | Requested range, observed range, selected data, and `partial_policy`. | A fully observed, known-false condition may yield zero conditional integral. Minimum/maximum/mean of an empty selection are null. No observations or all-unknown input must not become a normal zero. Explain partial values together with `status`, `reason`, and `quality`. |
+| Events and segments | Two activities can merge into one surrounding segment without making their gap an activity. | `segments.parent_event_ids` may reference several `events.event_id` values in the same run. Link calculations using `scope` and `parent_id`, not row number or rule name alone. |
+| Timing and output | Batch size changes execution chunks only. Unknown response differs from decidable timeout. Actual-time integration differs from per-message accumulation. | Inspect dependencies, intervals, output units, and requested ranges in `explain`. `coverage_status` exists only for applicable result types and thresholds; it is not a numerical coverage ratio. Do not invent a `coverage` field. |
+| Business presets | Charging, for example, needs `mode`/`current` and `voltage` when energy is requested. Direction, units, and measurement point must meet role requirements. | Missing facts or two matching candidates do not authorize choosing the first. Explicit bindings still undergo role validation. Example thresholds and codes do not transfer automatically to another vehicle. |
+
+<a id="从报告定位错误"></a>
+## Diagnose using actual reports
+
+Record the user's required signals, conditions, scope, and outputs first. Request JSON from `validate`. For a constructed plan, inspect `valid`, `execution_ready`, `errors`, `warnings`, and `capability_status`. For loading failure, use the actual fields supplied in the single `error`, such as `code`, `source`, `path`, `line`, `column`, `message`, and `hint`. In `explain`, the validation report is under `validation`, with dependencies under `nodes` and `input_requirements`. Environment, I/O, or argument errors may produce only a nonzero exit code and stderr; missing JSON does not mean success.
+
+For example, string `config_version: "3"` is rejected. Change only that value to integer 3, preserve the calculation, and recheck. Do not remove a filter, extend validity, ignore unknown data, or reverse a sign to “fix” a diagnostic. If two correction rounds still fail, report the real error and unresolved facts rather than fabricate runnable output.
+
+```text
+python -m chronaxis config origins ../../Current/examples/analysis-imports.yaml --fields --format json
+python -m chronaxis config resolve ../../Current/examples/analysis-imports.yaml --defaults --format json
+python -m chronaxis validate ../../Current/examples/input-csv-minimal.yaml --format json
+python -m chronaxis explain ../../Current/examples/input-csv-minimal.yaml --format json
+```
+
+`origins` identifies the declaration supplying a field. `resolve` shows expanded configuration and defaults that can currently be determined; it must not invent a fixed period awaiting DBC lookup. `load_analysis_plan` resolves paths relative to the defining file; `AnalysisPlan.from_dict` takes an already expanded dictionary. Validation does not establish actual observation coverage, real units, or correct results. Deliver the version, inputs, key assumptions, checks actually performed, and unverified conditions.
+
+<a id="持续门槛与积分起点"></a>
+## Duration thresholds and integration starts
+
+For `condition_duration`, `minimum_duration: 60s` means reaching 60 seconds by default. For “more than 60 seconds,” add `duration_comparison: ">"`, not 60.1 seconds. Default `selection_origin: onset` includes the entire qualifying interval. Select `confirmed` only when the user asks to start after confirmation. An exactly 60-second activity produces an event in the default mode and no event in strict mode. Time precision is 1 ns. Actual-time strict comparison can confirm at threshold plus 1 ns; fixed/DBC mode waits for the next driving message that takes accumulated duration strictly past the threshold.
+
+<a id="资源不足时保留原任务"></a>
+## Preserve the task when resources are insufficient
+
+Sample minimum, maximum, and mean use chunked reductions within the shared memory budget; their result does not depend on chunk size. Do not add unrequested statistics for debugging. For a budget error, first inspect the named calculation, workspace, or read buffer instead of attributing every failure to machine RAM. If even the smallest statistical chunk does not fit, execution fails explicitly. Reducing read batches changes processing chunks, not conditions, validity, or retained input. Increase budgets only with an actual resource basis. Managed budget estimates and process RSS are different quantities.
+
+<a id="can通道连续文件与检查范围"></a>
+## CAN channels, continuous files, and check scope
+
+DBC mapping keys, explicit signal channels, per-message selectors, and raw-frame resampling channels all start at 1 in public configuration. Channel 1 in ASC is channel 1 in configuration; do not subtract 1. Signal/selector `channel` can be omitted when the source channel is unambiguous. The program converts internal zero-based numbering. For raw CSV, `reader.channel_origin` still describes whether the input column itself starts at 0 or 1. Migrate old zero-based configuration rather than editing the original log.
+
+Configuration paths are relative to the file containing that field, including shared definitions. Dictionary APIs use `base_dir`, defaulting to the current directory. `chronaxis explain PLAN --format json` shows plan information; `chronaxis config resolve PLAN --format json` shows expanded configuration. Files within one source are continuous in listed order, retaining candidate state across boundaries. Directory matching uses natural order. Sharing a folder does not prove sharing a session: use batch tasks for independent experiments, and do not invent offsets to concatenate them.
+
+ASC checks timestamp order only for required channels/IDs by default. The source's earliest and latest frame times are still collected during that same read. Required records moving backwards remain errors; full checks or raw-frame export require the whole source to be ordered. Do not add a separate full-file scan followed by automatic cleaning. A small difference of microseconds does not authorize changing the input.
+
+<a id="默认可读结果"></a>
+## Default readable results
+
+Omitting `outputs.tables` selects `readable_csv`: Chinese filenames and headers, exact seconds, and one row containing the metrics for each event or window. Discover actual files through `run_manifest.json.outputs`; do not hard-code `events.csv` or `calculations.csv`. Explicit `outputs.tables: csv` or `jsonl` selects the original interchange format and integer nanoseconds. Only the selected table format is produced.
+
+Readable tables retain calculation names and units. Empty cells are not zero. Each metric independently reports `完整` (complete), `部分有效` (partial), or `无法确定` (indeterminate), with its reason. Inspect interval status separately from metric status. Global `has_unknown` does not invalidate a complete calculation within a known interval. For no events, inspect manifest `result_messages`; do not create a false zero-energy result. Preserve the original analysis time coordinates without inventing dates or shifting to zero. Do not duplicate seconds and nanoseconds. Python iterators such as `iter_events` and `iter_calculations` continue to return original typed rows.
+
+<a id="独立批量的进程数"></a>
+## Process count for independent batch tasks
+
+Root-level batch `process_count` is a positive integer, default 1, limiting analysis worker processes. It excludes the scheduler and CAN reader subprocesses. `run_batch(plan, output, process_count=4)` and CLI `--process-count 4` override it. Only the Python API accepts `None` to inherit the plan; configuration rejects null and Booleans. Call from a Python script inside `if __name__ == "__main__":`. Ordinary `AnalysisRunner` has no such parameter. Continuous `paths` in one session are not split into independent processes.
+
+Each task has its own budgets and output. Cancellation prevents tasks that have not started; in-flight tasks finish and close. `report.close()` can retry remote cleanup. Unstarted tasks and worker crashes are not successes. Legacy `workers`, `max_workers`, and `--workers` are rejected.
+
+<a id="迁移数值与后端核对"></a>
+## Migrated numbers and backend comparisons
+
+Historical INI seconds accept scientific notation. Import preserves compact representation and checks representable durations; do not expand huge exponents for display. A rejection report is not a successfully generated analysis plan. Both backends must agree on event boundaries, statuses, and diagnostics. Compare floating-point metrics using their unit and agreed error tolerance, without requiring bitwise equality or attributing event/quality differences to rounding.
+
+Ordinary scalar calculations, including sample statistics, can return `coverage_status` when `minimum_coverage > 0`. It records the threshold decision, not a ratio, and does not change the equal weighting of `sample_mean`. Initial-edge `emit_initial` concerns the first known state, not an arbitrary first `True` anywhere in the analysis. A requested endpoint can produce a point event only when it is actually observed and satisfies the rule.

chronaxis-0.1.0.dev0/Docs/AI/en/tasks.json

@@ -0,0 +1,290 @@
+{
+  "device_label": "home",
+  "revision": 1,
+  "tasks": [
+    {
+      "id": "CAN",
+      "intent": "Integrate power from BLF / ASC messages",
+      "example": "../../Current/examples/analysis.yaml",
+      "requires": "Logs, channel, matching DBC, power unit, and clock.",
+      "check": "Check joules (J) and the actual observed range.",
+      "fields": [
+        "sources",
+        "signals",
+        "calculations"
+      ],
+      "templates": [
+        "can-blf",
+        "can-asc"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/analysis.yaml --format json"
+    },
+    {
+      "id": "CONDITION_ENERGY",
+      "intent": "Continuous BLF/ASC volumes: require multiple conditions for longer than a threshold, then integrate energy over the full qualifying interval in kWh",
+      "example": "../../Current/examples/conditional-energy.yaml",
+      "requires": "Raw ASC/BLF and matching DBC; target signals, codes, units, comparisons, continuous duration, and integration scope. Do not require types, units, or periods to be repeated when the DBC supplies them.",
+      "applicable": "Custom state and numeric conditions; inclusive or strict duration thresholds; integration from condition onset; optional energy unit. The example uses strict >60s, default onset, and actual elapsed time.",
+      "not_applicable": "For a direct sum using a fixed period per message, consult message_calculations. Use BATCH for independent files.",
+      "alternative": "charge_session applies only to its strict current > comparison, duration >= comparison, Wh/Ah outputs, and direction/measurement-point requirements. Do not choose it merely because a task mentions charging.",
+      "check": "Exactly 60 seconds produces no event. The cross-file 61-second interval is [61,122), giving 4000W*61s/3600000=0.06777777777777777kWh. Link parent_id to event_id and check status/reason. Do not replace strict comparison with 60.1 seconds.",
+      "fields": [
+        "sources",
+        "signals",
+        "rules",
+        "calculations"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/conditional-energy.yaml --format json"
+    },
+    {
+      "id": "CSV",
+      "intent": "Power table integrated using actual elapsed time",
+      "example": "../../Current/examples/input-csv-minimal.yaml",
+      "requires": "Time column, units, power column, and validity period.",
+      "check": "Compare with the hand-calculated 38 J.",
+      "fields": [
+        "sources",
+        "signals",
+        "calculations"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/input-csv-minimal.yaml --format json"
+    },
+    {
+      "id": "CHARGE",
+      "intent": "Charging activities, electric charge, and charging energy",
+      "example": "../../Current/examples/preset-charge-energy.yaml",
+      "requires": "Mode codes, positive current direction, terminal measurement point, voltage, thresholds, and duration. The teaching example uses ASC; for BLF replace the logs, DBC, and bindings with your own.",
+      "check": "Check each activity boundary and Wh/Ah result. Current exactly equal to current_min is excluded; duration exactly equal to minimum_duration qualifies. The default start is onset. Check applicability rather than matching only the word charging.",
+      "fields": [
+        "presets",
+        "signals"
+      ],
+      "templates": [
+        "charge-session"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "resolve_preset_roles",
+        "build_preset"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/preset-charge-energy.yaml --format json",
+      "applicable": "Mode equals the specified integer code and current is strictly greater than current_min. After reaching minimum_duration, calculate from condition onset. Outputs are Wh for energy and Ah for electric charge. Positive current means charging, and the measurement point is the battery-pack terminal.",
+      "not_applicable": "Do not directly apply charge_session when the task needs current >= threshold, a strict duration threshold, direct kWh output, another state combination, or unconfirmed preset direction/measurement-point requirements.",
+      "alternative": "Use CONDITION_ENERGY and ../../Current/examples/conditional-energy.yaml with an ordinary condition_duration rule and event-scope integral. Preserve the comparisons, duration comparison, and output unit. Ordinary U*I integration needs no extra direction/measurement-point metadata or 95% coverage threshold."
+    },
+    {
+      "id": "EVENT",
+      "intent": "Sustained activities, exit grouping, and event relationships",
+      "example": "../../Current/examples/window-merged.yaml",
+      "requires": "Condition, time units, window, and allowed gap.",
+      "check": "Preserve event boundaries; a segment may contain multiple parent_event_ids.",
+      "fields": [
+        "rules",
+        "windows"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/window-merged.yaml --format json"
+    },
+    {
+      "id": "ALARM",
+      "intent": "Alarm context and rising edges",
+      "example": "../../Current/examples/preset-fault-context.yaml",
+      "requires": "An explicitly defined Boolean alarm and before/after durations.",
+      "check": "Check point events separately from surrounding segments.",
+      "fields": [
+        "presets",
+        "windows"
+      ],
+      "templates": [
+        "fault-window"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/preset-fault-context.yaml --format json"
+    },
+    {
+      "id": "PAIR",
+      "intent": "Request/response pairs, timeout, and insufficient observation",
+      "example": "../../Current/examples/sequence-outcomes.yaml",
+      "requires": "Comparable request and response clocks, with explicit minimum and maximum delays.",
+      "check": "Unknown observations must not become a definite no-response outcome.",
+      "fields": [
+        "sequences",
+        "rules"
+      ],
+      "templates": [
+        "command-response"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/sequence-outcomes.yaml --format json"
+    },
+    {
+      "id": "ENCODING",
+      "intent": "Boolean and enumeration codes, and expression aliases",
+      "example": "../../Current/examples/signal-enum-minimal.yaml",
+      "requires": "Equipment code definitions; undefined codes must not use nonzero=true.",
+      "check": "Expressions reference bound names. Semantic IDs are not attribute paths.",
+      "fields": [
+        "signals",
+        "derived"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/signal-enum-minimal.yaml --format json"
+    },
+    {
+      "id": "UNITS",
+      "intent": "Conversions, units, and scales",
+      "example": "../../Current/examples/signal-number-conversion.yaml",
+      "requires": "Input/output units, existing decoder scaling, and direction declarations.",
+      "check": "Apply DBC scaling once. Unit labels alone do not convert values.",
+      "fields": [
+        "signals"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/signal-number-conversion.yaml --format json"
+    },
+    {
+      "id": "QUALITY",
+      "intent": "Expired data, zero values, and partial results",
+      "example": "../../Current/examples/quality.yaml",
+      "requires": "Period or validity, required observation range, and missing-data policy.",
+      "check": "Read status/reason/quality together with the value.",
+      "fields": [
+        "signals",
+        "execution",
+        "calculations"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/quality.yaml --format json"
+    },
+    {
+      "id": "BATCH",
+      "intent": "Run independent tasks in a batch",
+      "example": "../../Current/examples/batch-minimal.yaml",
+      "requires": "Independent input and output for each plan, without shared task state.",
+      "check": "Use batch run. process_count is a positive integer, default 1, overridable with --process-count. Inspect worker_process_count and each task worker_pid in batch_report. Continuous volumes belong in one task's paths.",
+      "fields": [
+        "jobs",
+        "process_count"
+      ],
+      "templates": [
+        "batch"
+      ],
+      "api": [
+        "load_batch_plan",
+        "run_batch",
+        "BatchReport"
+      ],
+      "verify": "python -m chronaxis batch run ../../Current/examples/batch-minimal.yaml --output new-batch"
+    },
+    {
+      "id": "IMPORT",
+      "intent": "Shared definitions, field origins, and relative paths",
+      "example": "../../Current/examples/analysis-imports.yaml",
+      "requires": "Both the main configuration and referenced shared-definition files.",
+      "check": "Use config origins --fields to inspect declaration origins.",
+      "fields": [
+        "imports"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/analysis-imports.yaml --format json"
+    },
+    {
+      "id": "EXPORT",
+      "intent": "Export raw messages around events",
+      "example": "../../Current/examples/export-can-minimal.yaml",
+      "requires": "A supported CAN source, explicit window, and new output directory.",
+      "check": "Check actual windows, output format, and manifest.",
+      "fields": [
+        "outputs",
+        "windows"
+      ],
+      "templates": [
+        "can-export"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/export-can-minimal.yaml --format json"
+    },
+    {
+      "id": "PYTHON",
+      "intent": "Load, publish, and close results in Python",
+      "example": "../../Current/examples/input-csv-minimal.yaml",
+      "requires": "The matching installed version, complete plan, and new result directory.",
+      "check": "Run ../run_analysis.py. Validate before execution, read rows, and close resources.",
+      "fields": [
+        "outputs"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner",
+        "AnalysisResult"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/input-csv-minimal.yaml --format json"
+    },
+    {
+      "id": "FIX",
+      "intent": "Correct configuration using diagnostics",
+      "example": "../../Current/examples/input-csv-minimal.yaml",
+      "requires": "The user's original intent, original files, and actual diagnostics.",
+      "check": "Fix field placement, types, or references. Do not remove conditions or change validity to suppress errors.",
+      "fields": [
+        "config_version"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "validate_analysis_plan",
+        "explain_analysis_plan",
+        "PlanValidationError"
+      ],
+      "verify": "python -m chronaxis validate ../../Current/examples/input-csv-minimal.yaml --format json"
+    }
+  ]
+}

chronaxis-0.1.0.dev0/Docs/AI/en/workflow.md

@@ -0,0 +1,41 @@
+<a id="从用户输入到结果"></a>
+# From the user's inputs to results
+
+| Task | Public entry point | Result and boundaries |
+|---|---|---|
+| Connect logs | BLF/ASC with the matching DBC; raw-message CSV with an explicit record format; decoded CSV with column declarations; memory input for controlled data. | Source identity, clocks, and entity scope are input requirements. Combine sources only when the available evidence supports it. |
+| Build an analysis | Version 3 YAML/JSON for a single task, with at most one level of shared definitions. Use `load_analysis_plan` for files and `AnalysisPlan.from_dict` for dictionaries. | Checks references, types, units, and clocks; may enumerate directories or read DBC metadata. This does not verify business meaning in actual records. |
+| Choose calculations | Use bound names in conditions, derived expressions, rules, windows, and `calculations`. Use `message_calculations` for per-message accumulation. | Activities and windows can have separate calculations. Integration method, interval basis, and quality affect results. |
+| Use business presets | Declare roles and parameters in a complete plan's `presets`. Python construction returns a `PlanFragment`. | Presets expand into ordinary declarations. Role validation does not determine engineering thresholds; a fragment is not a complete plan. |
+| Explain before running | `validate_analysis_plan`, `explain_analysis_plan`, then `AnalysisRunner.run`. | Explanation shows dependencies, time requirements, and budgets, not records already read. `run` calculates from real inputs and returns an `AnalysisResult`. |
+| Read or deliver results | Stream rows from `AnalysisResult`; close cursors after exhaustion or early exit. Call `write` with a new directory, then close the result. | Follow each row type's relationship keys and quality fields. Null is not zero. Failed publication is not delivery. |
+| Run independent tasks | `load_batch_plan`, `run_batch`, or `python -m chronaxis batch run`. | Each task is independent. Inspect individual statuses even after a normal return. Do not split one stateful session into independent tasks. |
+
+Evidence for final output publication in this version is limited to Windows / Python 3.12. Historical formats, channels, exports, and profiles have specific conditions. Retain capability restrictions reported by `validate`/`explain` rather than promising every historical path works. Example values are synthetic; platform behavior, budgets, speed, and real business results require their own verification.
+
+<a id="写配置前保留用户原意"></a>
+## Preserve the user's meaning before writing configuration
+
+Map the requirements already supplied by the user to configuration without asking them to reconfirm those facts. Consider: “state is `0x2`, current is at least `10A`, continuously for more than `60s`; integrate current times voltage over each qualifying interval, in `kWh`.”
+
+| Requirement to preserve | Configuration and handling |
+|---|---|
+| Signals and expression | Bind `BMS_ChrgSta`, `BMS_BatPackActCur`, and `BMS_BatPackActVol`. Calculate current times voltage; do not substitute another measurement point. |
+| Comparisons and logic | Use `state == 0x2 and current >= 10`, binding aliases to those signals. Preserve equality, inclusive `>=`, and logical AND. |
+| Continuously longer than 60 seconds | Use `condition_duration`, `minimum_duration: 60s`, and `duration_comparison: ">"`. Exactly 60 seconds does not qualify. Do not replace it with 60.1 seconds or omit continuity by merely filtering frames. |
+| Integration boundaries | “Within the qualifying interval” uses default `selection_origin: onset`, from first satisfaction to the interval end. Do not discard the first 60 seconds. Use `confirmed` only when explicitly requested. |
+| Unit | Confirm A and V from the DBC or established definitions, and request `kWh` output. Do not relabel a J or Wh value as kWh. |
+| File relationships and timing | Put continuous volumes in one source so state continues across files. Batch only independent tasks. Preserve the chosen actual, fixed, or DBC period; do not edit timestamps instead of configuring it correctly. |
+
+Aliases may be short, but explain their original signal mappings. Obtain facts from inputs, DBC metadata, matching examples, and the user's existing instructions. Ask only when a missing fact can change the result, such as an ambiguous signal match or uncertainty about whether files are continuous volumes or independent experiments. Use supported defaults and explain them where relevant; do not turn every optional field into a question.
+
+Ordinary expression integration does not require current direction or measurement-point metadata used only by a business preset. If the user specifies a raw-current comparison and product, do not add sign conversion merely to label the result “charging” or “discharging.” Ask about that interpretation only when the task actually needs it and the available information is insufficient.
+
+<a id="报错修复与核验范围"></a>
+## Fix errors within the task's scope
+
+For installation, missing dependencies, paths, or field errors, fix the actual cause while preserving the requested signals, condition, duration threshold, integration start, and unit. Do not add direction/measurement restrictions, a `95%` coverage threshold, extra minimum/maximum statistics, or change validity, thresholds, or timing just to make execution succeed. Do not automatically sort, deduplicate, filter, or rewrite input after backwards timestamps or similar data errors. Report the actual diagnostic and explain any proposed data treatment's effect on results.
+
+Read, calculate, and deliver only what the task needs. Once installation and entry-point validation pass, run the requested analysis. Contributions, tracing, raw-frame copies, additional statistics, and repeated scans that neither the user nor calculation needs must not be constructed, scanned, saved, or output. Explain empty results using their diagnostics; do not silently loosen conditions and rerun.
+
+Choose independent verification for a specific verification goal; it is not a prerequisite for every normal run. If you write a separate checker, explain whether it preserves original order, how it handles validity (TTL), invalid updates and boundaries, and which files, signals, and results it checks. A script that sorts records and holds the latest voltage forever is not equivalent to an analysis that preserves order and expires voltage. Similar total energy alone does not verify the entire feature. Checking only integration values does not establish event selection, cross-file state, or all quality rules. Investigate discrepancies rather than changing business conditions to fit a reference value.