symtest-cli 1.4.0__tar.gz → 1.5.0__tar.gz

{symtest_cli-1.4.0/src/symtest_cli.egg-info → symtest_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: symtest-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: Regression testing for CLI applications, with multi-step workflows and numerical file comparison.
 Home-page: https://github.com/ozil111/symtest-cli
 Author: Xiaotong Wang

{symtest_cli-1.4.0 → symtest_cli-1.5.0}/docs/design.md

@@ -155,14 +155,11 @@ PathResolver 解析（系统命令直通、shell builtin 平台包装、复合
 → 超时 kill 整个进程组
 → 返回附带 `next_action_hint` 的结构化结果。
 
-当前实现的上述行为仍聚合在一处；1.4 将按 §10 宪法重排为
-Executor / Validator / Orchestration 三段（迁移明细见 docs/design_1_4.md）。
-
 ### 4.6 断言与文件比较集成
 
 - `compare_files` 是一等断言，经 ComparatorFactory 按类型分发（详见 §6）
 - 所有断言可选；未声明的字段不做校验
-- `--error-analysis` 为 CSV/H5 数值比较提供流式误差统计：`total_numeric_cells` / `mismatched_cells` / `max_abs_error` / `max_rel_error` / `mean_abs_error` / `rms_abs_error`
+- `--error-analysis` 为 CSV/H5 数值比较提供流式误差统计：`total_numeric_cells` / `mismatched_cells` / `max_abs_error` / `max_rel_error` / `mean_abs_error` / `rms_abs_error`；幅值统计（max/mean/rms）覆盖全体参与比较的数值单元格（含通过格），mean/rms 以 `total_numeric_cells` 为分母。`--error-analysis-all` 额外对通过用例输出统计，除此之外两者行为一致
 
 ## 5. 运行时状态持久化（`.symtest/`）
 
@@ -178,24 +175,57 @@ Executor / Validator / Orchestration 三段（迁移明细见 docs/design_1_4.md
 
 ## 6. 文件比较子系统
 
-### 6.1 比较器分层
+### 6.1 三泳道比较器架构
+
+所有比较器共享根契约 `ComparatorBase.compare(ctx) -> ComparisonResult`：
+框架构建 `CompareContext`（workspace / actual / baseline / params / error_analysis）；
+`actual`/`baseline` 以及插件 `path_params` 声明的构造参数在**比较器构造之前**
+按 workspace 统一解析，插件不得自行对 CWD resolve。配置单一事实源：
+比较器配置只存在于构造器捕获的实例状态，`ctx` 仅承载调用级上下文。
+三条泳道职责互斥：
+
+| 泳道 | 基类 | 契约 | verdict 归属 | 内置实例 |
+|---|---|---|---|---|
+| 文件泳道 | `FileComparator` | `read_content` + `compare_content`（两文件模型，行列窗口、line N 偏移、chunk_size、similarity 均属本泳道） | 插件 | text / json / csv / xml / h5 / binary |
+| 数据泳道 | `ExtractorComparator` | `extract(ctx) -> {channel: ChannelData}`；框架逐通道跑 `compare_numeric`，per-channel 容差（`channels` / `default_channel`），聚合 `ChannelResult` | **框架**（容差语义对 AI 消费端可预期） | script_extract、extractor 插件 |
+| 自主泳道 | 直接继承根 | `compare(ctx)` 全权判定 | 插件 | script、hourglass 式分析插件 |
+
+- 文本系共享 difflib 行级基底，json / csv / xml 为其结构化特化；h5 面向科学数据集；binary 流式分块 + LCS 相似度
+- 统一返回 `ComparisonResult`（identical / differences / error / error_stats / command_output / channels），支持 text / json / html 渲染
+- 数据泳道插件可通过 `ChannelData.extra_stats` 附带自定义误差指标，存放在独立命名空间（`ChannelResult.extra_stats`），不可覆盖框架规范指标；但 verdict 仍由框架容差持有——需要自定 verdict 的走自主泳道
+
+### 6.2 通道协议（数据泳道）
+
+- 通道判定：`identical = all(channels.passed)`；差异 position 带通道前缀（`channel S33`）；`error_stats` 按通道名嵌套
+- 内置 `script_extract` 类型：子进程执行用户脚本（零改动接入），脚本 stdout 输出约定 JSON：
+
+```json
+{"channels": {"S11": {"expected": [...], "actual": [...], "extra_stats": {...}}}}
+```
 
-- 文本系比较器共享 difflib 行级基底，json / csv / xml 为其结构化特化（键对齐 / 列结构 / DOM 对齐）
-- h5 面向科学数据集；binary 流式分块 + LCS 相似度；script 委托外部脚本
-- 统一返回 ComparisonResult（identical / differences / error / script command_output），支持 text / json / html 渲染；支持行列窗口范围参数截取后比较
+  非零退出、超时、畸形 JSON 一律判为比较 error（绝不静默通过）；`actual`/`baseline` 按惯例以 baseline 在前的顺序追加为尾部 argv 槽位（可缺省）
+- 结果粒度：一条 compareSpec = 一条断言；`ComparisonResult.channels` 携带通道级子结果，报告逐通道展示 pass/fail + stats；JSON 输出中通道 differences 按 per-channel 配额截断
 
-### 6.2 工厂与插件发现
+### 6.3 工厂与插件发现
 
-- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script`；工厂按类型分发，支持动态注册与全局 reset（测试用）
+- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script` / `script_extract`；工厂按类型分发，支持动态注册与全局 reset（测试用）
 - 插件发现四处来源：内置 `*_comparator.py` 自动发现、`workspace/comparators/` 自动扫描、`--plugin-dir` CLI 参数、`CLITEST_PLUGIN_DIRS` 环境变量（供进程模式 worker 使用）
-- 命名约定：`*_comparator.py` + `*Comparator` 类名
+- 命名约定：`*_comparator.py` + `*Comparator` 类名；可用类属性 `comparator_type` 显式指定类型名（如 `script_extract`）；抽象基类自动跳过注册
+- 配置传递与严格校验：`actual`/`baseline`/`type`/`options` 之外的键转发给比较器构造函数（kwargs）；构造器参数是**严格**的——未声明的键（拼写错误）在构造时大声失败并给出支持参数清单。`options` 是框架持有的插件配置命名空间（并入构造参数，显式顶层键优先），核心 schema 不为单个插件增加专属字段；`channels`/`default_channel` 属数据泳道框架结构
 
-### 6.3 script 比较协议（对外契约）
+### 6.4 script 比较协议（自主泳道对外契约）
 
-- 子进程方式执行 `<interpreter> <script> <actual> <baseline>`
+- 子进程方式执行 `<interpreter> <script> <baseline> <actual>`（文件槽位可缺省）
 - 默认 exit code 0 → 通过；可选 `pass_pattern` / `fail_pattern` 正则匹配 stdout 细化判定
 - 超时可配
 
+### 6.5 插件公共 API
+
+`symtest.file_comparator` 包导出：`ComparatorBase` / `CompareContext` /
+`FileComparator` / `ExtractorComparator` / `ChannelData` / `ChannelResult` /
+`compare_numeric` / `NumericComparisonStats` / `parse_data_filter`。
+数据泳道插件只需依赖 `ExtractorComparator` + `ChannelData`，数值判定全部复用框架核心。
+
 ## 7. TUI 子系统
 
 基于 Textual 的终端交互界面：App + Controller（load / create / update /
@@ -213,7 +243,7 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 | 新配置格式 | `BaseRunner` | 支持新的测试定义格式（如 XML、TOML） |
 | 自定义 Setup | `BaseSetup` | 数据库初始化、服务启停等 |
 | 自定义断言 | 扩展 `Assertions` | 特定业务校验逻辑 |
-| 新比较器 | `BaseComparator` | 支持新的文件格式比较，放入 `comparators/` 目录自动发现 |
+| 新比较器 | `FileComparator` / `ExtractorComparator` / `ComparatorBase` | 按泳道选择基类（文件格式 / 数据提取+通道 / 全权分析），放入 `comparators/` 目录自动发现 |
 | 新 Runner | `ParallelRunner` / `BaseRunner` | 自定义并行调度策略 |
 | TUI 扩展 | `CaseController` / Widgets | 扩展终端管理界面 |
 
@@ -252,7 +282,6 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 > **地位与效力**：本节自 Symtest 1.4 Phase 0 评审定稿，是本项目的核心架构契约，
 > 对所有后续 feature 具有最高约束力——任何功能需求先对照本宪法确定归属，再写代码。
 > 修订宪法必须在变更说明中显式指出所放宽/违反的条款及理由。
-> 定稿前的演进推导见开发阶段文档 docs/design_1_4.md。
 
 ### 10.1 数据流主线
 
@@ -373,16 +402,3 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
   `reporter`；
 - guard 测试纳入常规回归套件（`python tests\run_all.py`），违规即失败；
 - 冲突裁决次序：guard 测试 > 本节文字 > 个人偏好。
-
-### 10.6 现状差距与收敛路径
-
-定稿时刻（1.4 Phase 0）现行实现与本宪法的已知偏差如下，将在 1.4 对应 Phase 内
-逐项收敛（迁移明细见 docs/design_1_4.md）：
-
-| 现状 | 违反 | 收敛 |
-|---|---|---|
-| `execution.py::validate_result` 住在执行层 | 原则 2 | Phase 2 迁入 `validation/validator.py` |
-| `next_action_hint` 在 execution 层构造 | 原则 5 | Phase 2 迁入 `reporting/diagnosis.py` |
-| retry 循环在 executor 内部 | 原则 2 / 4 | Phase 2 上移编排层 |
-| Validator 侧 update_baseline 写文件 | 原则 3 | Phase 2 改为 runner 独立 accept 步骤 |
-| `parse_test_cases` TUI mode 后门 | 原则 6 | Phase 2 拆除，单一解析器 |

{symtest_cli-1.4.0 → symtest_cli-1.5.0}/docs/design_en.md

@@ -164,10 +164,6 @@ stdout / stderr / returncode / duration) → assertions (return_code / contains
 matches / compare_files) → retries on failure up to `retry_count` → kills the
 whole process group on timeout → structured result with `next_action_hint`.
 
-Today these behaviors are aggregated in one place; 1.4 rearranges them into
-Executor / Validator / Orchestration per the §10 Constitution (migration details
-in docs/design_1_4.md).
-
 ### 4.6 Assertions and File Comparison Integration
 
 - `compare_files` is a first-class assertion dispatched via ComparatorFactory (see §6)
@@ -266,8 +262,7 @@ TUI side itself (§10 Principle 6).
 > project's core architectural contract with supreme authority over all future
 > features — resolve ownership against this constitution before writing any code.
 > Amending it requires explicitly naming the clause being relaxed/waived and the
-> rationale in the change description. Pre-ratification evolution history lives in
-> the development-phase document docs/design_1_4.md.
+> rationale in the change description.
 
 ### 10.1 Data Flow Spine
 
@@ -398,17 +393,3 @@ architecture guard tests enforced by CI:
 - Guard tests are part of the regular regression suite
   (`python tests\run_all.py`); violations fail the build;
 - Conflict resolution order: guard tests > this text > personal preference.
-
-### 10.6 Current Gap to This Constitution
-
-Known deviations of the current implementation from this constitution as of
-ratification (1.4 Phase 0). Each item converges during the corresponding 1.4
-phase (migration details in docs/design_1_4.md):
-
-| Current state | Violated | Convergence |
-|---|---|---|
-| `execution.py::validate_result` lives in the execution layer | Principle 2 | Phase 2: move to `validation/validator.py` |
-| `next_action_hint` built in the execution layer | Principle 5 | Phase 2: move to `reporting/diagnosis.py` |
-| Retry loop inside the executor | Principles 2 / 4 | Phase 2: lift to orchestration |
-| update_baseline writes files inside validation | Principle 3 | Phase 2: runner-side independent accept step |
-| `parse_test_cases` TUI-mode back door | Principle 6 | Phase 2: remove; single parser |

{symtest_cli-1.4.0 → symtest_cli-1.5.0}/docs/user_manual.md

@@ -48,7 +48,7 @@ HDF5 文件比较依赖 `h5py`（已随框架安装）。如需在无 HDF5 环
 
 ## 测试用例定义
 
-> **Schema v2（1.4）**：配置采用分层 DSL——执行相关字段（`command`、`args`、`timeout`、`retry_count`、`env`、`steps`）位于 `execution` 块，调度相关字段（`depends_on`、`resources`）位于 `scheduling` 块，`expected` 保持在顶层。旧的扁平布局已移除，可使用 `symtest migrate` 迁移。
+> **Schema v2（1.4）**：配置采用分层 DSL——执行相关字段（`command`、`args`、`timeout`、`retry_count`、`env`、`steps`）位于 `execution` 块，调度相关字段（`depends_on`、`resources`）位于 `scheduling` 块，`expected` 保持在顶层。旧的扁平布局已移除，可使用 `symtest migrate` 迁移。迁移会递归处理整棵 `import` 树：默认为每个文件生成 `<stem>.v2<ext>` 副本并自动重写父文件中的 import 路径；`--in-place` 则原地覆盖所有文件（与 `--output` 互斥）。
 
 ### JSON 格式
 
@@ -275,6 +275,13 @@ test_cases:
 | `expected.output_matches` | 否 | 输出需匹配的正则表达式（单个字符串） |
 | `expected.compare_files` | 否 | 文件比较断言列表，见下文 |
 
+### execution 二选一（互斥）
+
+`execution` 有两种形态，**二选一**且互斥，同时声明两种形态属于配置错误：
+
+- **单命令形态**：`command` + `args`（`timeout` / `retry_count` / `env` 可选）
+- **序列形态**：`steps`（列表，每个 step 为 `command + args + expected`）；`command` / `args` 不得与 `steps` 并存
+
 ## Case 级环境变量（env）
 
 通过 `execution` 内与 `command`、`steps` 同级的 `env` 字段，可为单个用例注入环境变量，仅在该用例（序列模式为所有 step）的子进程内生效，不影响其他用例。
@@ -1788,12 +1795,12 @@ CSV 比较按行列结构逐单元格比对；数值单元格在容差范围内
 |---|---|
 | `total_numeric_cells` | 参与数值比较的单元格总数 |
 | `mismatched_cells` | 超出容差的单元格数 |
-| `max_abs_error` | 最大绝对误差及其位置 |
-| `max_rel_error` | 最大相对误差及其位置 |
-| `mean_abs_error` | 平均绝对误差 |
-| `rms_abs_error` | 均方根绝对误差（RMSE） |
+| `max_abs_error` | 全体数值单元格中的最大绝对误差及其位置 |
+| `max_rel_error` | 全体数值单元格中的最大相对误差及其位置 |
+| `mean_abs_error` | 全体数值单元格的平均绝对误差（分母为 `total_numeric_cells`） |
+| `rms_abs_error` | 全体数值单元格的均方根绝对误差（RMSE，分母为 `total_numeric_cells`） |
 
-统计是**流式**计算的，不依赖差异截断，覆盖全体数值单元格。默认仅失败的比较输出统计，通过的比较不输出。
+统计是**流式**计算的，不依赖差异截断，幅值统计（max/mean/rms）覆盖**全体**参与比较的数值单元格（含在容差内通过的单元格），可用于观察通过格离容差的余量；非有限值（NaN/inf）单元格不参与幅值统计。两个参数的统计口径完全一致，区别仅在于：默认仅失败的比较输出统计，通过的比较不输出。
 
 如需让**通过**的用例也输出统计信息（例如用于监控容差余量），可改用 `--error-analysis-all`（它会隐含启用 `--error-analysis`）：
 
@@ -1965,11 +1972,31 @@ class MySetup(BaseSetup):
 
 ### 自定义文件比较器
 
-框架支持三种方式扩展比较能力：
+#### 三泳道架构（v2）
+
+比较器插件体系围绕根契约 `ComparatorBase.compare(ctx) -> ComparisonResult` 组织，
+按判定权归属分为三条泳道：
+
+| 泳道 | 基类 | 适用场景 | verdict 归属 |
+|---|---|---|---|
+| **文件泳道** | `FileComparator` | 比较两个同类文件（text/json/csv/xml/h5/binary 内置即此类） | 插件 |
+| **数据泳道** | `ExtractorComparator` | 从任意上游（文件/求解器输出/跨文件整理）提取数值数据，**复用框架数值核心**做通道化容差判定 | **框架** |
+| **自主泳道** | 直接继承 `ComparatorBase` | 独特判定逻辑（阈值组合、标签解析、渐近分析等） | 插件 |
+
+选型决策：
 
-#### 方式一：工作区插件目录（推荐）
+- 数据本来就是 `(expected, actual)` 数值数组、只需 rtol/atol 判定 → **数据泳道**（可享受通道、per-channel 容差、统一 error_stats 与报告渲染）
+- 需要自定 verdict（比如"主分量紧、EAS 分量松"的组合判定、符号/渐近检查）→ **自主泳道**
+- 只是想让现成脚本快速接入 → 优先考虑内置 `script`（自定判定）或 `script_extract`（框架容差判定），零 Python 插件代码
 
-在 workspace 下创建 `comparators/` 目录，放入 `*_comparator.py` 文件（命名与内置比较器一致），框架会在首次使用时自动发现并注册其中的 `*Comparator` 类。
+**路径解析约定**：`actual`/`baseline` 以及插件用 `path_params` 类属性声明的路径参数，
+由框架在**比较器构造之前**统一按 workspace 解析为绝对路径——构造器捕获的状态
+（`self.script`、`self.cwd` 等）持有的已是解析后的绝对路径。插件内部
+**禁止**对 CWD 做 `Path.resolve()`——并行/process 模式下 CWD 不可靠。
+
+#### 插件发现方式（三种泳道通用）
+
+在 workspace 下创建 `comparators/` 目录，放入 `*_comparator.py` 文件，框架会在首次使用时自动发现并注册其中的 `*Comparator` 类。
 
 ```
 your-workspace/
@@ -1986,26 +2013,148 @@ symtest run test_config.json --plugin-dir ./extra_plugins
 
 插件也会通过环境变量 `CLITEST_PLUGIN_DIRS` 自动继承到 process 模式子进程。
 
-**插件开发注意事项**：
-- 继承 `symtest.file_comparator.BaseComparator`
+**命名约定**：
+- 文件名必须以 `_comparator.py` 结尾（如 `my_analysis_comparator.py`）
 - 类名必须以 `Comparator` 结尾（如 `MyAnalysisComparator`）
-- 注册的 type 名 = 类名去掉 `Comparator` 再小写（如 `myanalysis`）
-- 推荐重写 `compare_files(file1, file2, **kwargs)` 方法而非 `read_content`/`compare_content`（若比较器不使用两文件模型）
-- 通过 `from symtest.file_comparator import ComparisonResult, Difference` 构造结构化结果
-- `extra_kwargs` 自动从 config `compareSpec` 透传
+- 注册的 type 名 = 类名去掉 `Comparator` 再小写（如 `myanalysis`）；也可用类属性 `comparator_type = "my_analysis"` 显式指定
+- 抽象基类（未实现全部抽象方法）自动跳过注册
 
-在配置中直接使用注册的类型名：
+在配置中直接使用注册的类型名。比较器构造参数是**严格**的：`actual`/`baseline`/
+`type` 以外的键会透传给插件构造函数，但插件未声明的参数（如拼写错误
+`pass_threhsold`）会在构造时**大声失败**（错误信息包含比较器类型名与支持的
+参数清单），绝不静默回退到默认值。插件自有配置建议放入 `options` 命名空间
+（其条目并入构造参数，显式顶层键优先），避免向核心 schema 增加插件专属字段：
 
 ```json
 {
   "type": "myanalysis",
   "actual": "optional_for_plugins",
   "baseline": "optional_for_plugins",
-  "param1": "value1"
+  "options": {"param1": "value1", "param2": 42}
+}
+```
+
+#### 数据泳道：通道提取器插件
+
+适用场景：一个脚本/插件产出多通道数据（如 CSV 的不同列、不同物理量），
+每通道需要独立的容差与误差分析。插件只负责"提取"，判定完全由框架完成。
+
+```python
+# comparators/uel_stress_comparator.py
+import numpy as np
+from symtest.file_comparator import (
+    ExtractorComparator, ChannelData, CompareContext,
+)
+
+class UelStressComparator(ExtractorComparator):
+    path_params = ("uel_csv", "ref_csv")   # 由框架按 workspace 解析
+
+    def __init__(self, uel_csv="", ref_csv="", **kwargs):
+        super().__init__(**kwargs)
+        self.uel_csv = uel_csv
+        self.ref_csv = ref_csv
+
+    def extract(self, ctx: CompareContext):
+        uel = np.loadtxt(self.uel_csv, delimiter=",")
+        ref = np.loadtxt(self.ref_csv, delimiter=",")
+        return {
+            "S11": ChannelData(expected=ref[:, 0], actual=uel[:, 0]),
+            "S33": ChannelData(
+                expected=ref[:, 2], actual=uel[:, 2],
+                extra_stats={"hydrostatic_shift": float(uel[:, 2].mean())},
+            ),
+        }
+```
+
+配置（per-channel 容差按名路由，未声明的通道用 `default_channel`）：
+
+```json
+{
+  "type": "uelstress",
+  "uel_csv": "out/uel.csv",
+  "ref_csv": "out/native.csv",
+  "channels": {
+    "S33": {"atol": 600.0, "data_filter": "abs>1e-12"}
+  },
+  "default_channel": {"rtol": 1e-5, "atol": 1e-8}
 }
 ```
 
-#### 方式二：内置 `script` 类型比较器
+**判定与结果语义**：
+- 每通道独立跑 `compare_numeric`（对称容差 `|a-b| <= max(rtol*max(|a|,|b|), atol)`）
+- `identical = 所有通道全过`；一条 compareSpec 仍是一条断言
+- 差异 position 带通道前缀（`channel S33`）；`error_stats` 按通道名嵌套
+- 报告逐通道展示 pass/fail、容差与统计；JSON 输出中通道差异按 per-channel 配额截断
+- 自定义误差指标通过 `ChannelData.extra_stats` 附带，存放在**独立命名空间**
+  （`ChannelResult.extra_stats`），不可能覆盖框架规范指标（`max_abs_error`、
+  `total` 等）；报告逐通道分别渲染两个命名空间
+- verdict 不可由插件干预——需要自定 verdict 请走自主泳道
+
+#### 数据泳道：内置 `script_extract` 类型（零改动脚本接入）
+
+现成分析脚本无需包装成 Python 插件：脚本以子进程执行，向 stdout 打印约定
+JSON，各通道即进入上述框架判定管线。
+
+```json
+{
+  "type": "script_extract",
+  "script": "extract_channels.py",
+  "args": ["--frame", "10"],
+  "cwd": "case/subdir",
+  "channels": {"S33": {"atol": 600.0}},
+  "default_channel": {"rtol": 1e-5, "atol": 1e-8},
+  "timeout": 600
+}
+```
+
+**stdout JSON 协议**：
+
+```json
+{
+  "channels": {
+    "S11": {"expected": [1.0, 2.0], "actual": [1.0, 2.0]},
+    "S33": {"expected": [...], "actual": [...], "extra_stats": {"asymmetry": 2e-13}}
+  }
+}
+```
+
+**错误语义**：非零退出码、超时、畸形 JSON、缺 `channels` 键或通道缺
+`expected`/`actual` 数组 → 一律判为比较 error（绝不静默通过）。
+`actual`/`baseline`（若配置）以 baseline 在前的顺序追加为脚本尾部参数，可缺省。
+
+#### 自主泳道：全权判定插件
+
+适用场景：独特判定逻辑。插件实现 `compare(ctx)` 并直接返回结果。
+
+```python
+# comparators/my_analysis_comparator.py
+from symtest.file_comparator import ComparatorBase, CompareContext, ComparisonResult, Difference
+
+class MyAnalysisComparator(ComparatorBase):
+    path_params = ("script", "case_dir")
+
+    def __init__(self, script="", case_dir=None, pass_threshold=1e-6):
+        super().__init__()   # 参数严格：未声明/拼错的配置键在构造时报错
+        self.script = script      # 构造前已由框架按 workspace 解析
+        self.case_dir = case_dir
+        self.pass_threshold = pass_threshold
+
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        result = ComparisonResult(
+            file1=ctx.baseline,   # 无文件输入时保持 None，不伪造空串
+            file2=ctx.actual,
+        )
+        # ... 执行分析、解析指标 ...
+        result.identical = True  # 或 False + differences
+        result.error_stats = {"full_rel": 8e-8}   # 自由 dict，报告通用渲染
+        return result
+```
+
+`ctx` 字段（仅调用级上下文）：`workspace` / `actual` / `baseline`（可空，
+无文件输入时为 `None`）/ `params`（文件泳道窗口参数）/ `error_analysis`。
+比较器配置的唯一权威在构造器捕获的实例状态中——`ctx` 不携带配置副本。
+
+#### 内置 `script` 类型比较器（自主泳道开箱即用）
 
 适用于独立分析脚本快速接入，无需编写比较器类：
 
@@ -2028,8 +2177,8 @@ symtest run test_config.json --plugin-dir ./extra_plugins
 | 参数 | 必填 | 默认值 | 说明 |
 |---|---|---|---|
 | `script` | 是 | — | 脚本路径（相对 workspace 或绝对） |
-| `actual` | 否 | — | 传给脚本的第一个文件参数 |
-| `baseline` | 否 | — | 传给脚本的第二个文件参数 |
+| `actual` | 否 | — | 传给脚本的文件参数（尾部第二位） |
+| `baseline` | 否 | — | 传给脚本的文件参数（尾部第一位） |
 | `cwd` | 否 | — | 脚本工作目录 |
 | `interpreter` | 否 | `sys.executable` | Python 解释器 |
 | `pass_exit_code` | 否 | `0` | 判定为通过的退出码 |
@@ -2045,15 +2194,15 @@ symtest run test_config.json --plugin-dir ./extra_plugins
 
 脚本的 stdout 和 stderr 会完整捕获到 `Comparator Output` 区块中，在报告渲染时限 20 行展示。
 
-#### 方式三：手动注册（编程方式）
+#### 手动注册（编程方式）
 
 ```python
-from symtest.file_comparator import ComparatorFactory
-from symtest.file_comparator.base_comparator import BaseComparator
+from symtest.file_comparator import ComparatorFactory, ComparatorBase, CompareContext
+from symtest.file_comparator.result import ComparisonResult
 
-class FooComparator(BaseComparator):
-    # 实现 read_content / compare_content 等方法
-    pass
+class FooComparator(ComparatorBase):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        ...
 
 ComparatorFactory.register_comparator("foo", FooComparator)
 
@@ -2063,7 +2212,7 @@ comparator = ComparatorFactory.create_comparator("foo")
 
 #### 专用插件示例：hourglass 切线刚度分析
 
-`examples/plugins/hourglass_tangent_comparator.py` 是一个完整的工作区插件示例，展示了如何将专用的 `analyze_*_tangent.py` 分析脚本接入框架：
+`examples/plugins/hourglass_tangent_comparator.py` 是一个完整的自主泳道工作区插件示例，展示了如何将专用的 `analyze_*_tangent.py` 分析脚本接入框架：
 
 ```json
 {
@@ -2078,6 +2227,7 @@ comparator = ComparatorFactory.create_comparator("foo")
 **特点**：
 - 通过 subprocess 调分析脚本（**零改动** analyze 代码），捕获 stdout 后用正则解析 `RESULT:` 行和 `full_rel`/`aa_rel`/`hh_rel`/`asymmetry` 等数值指标
 - 构造结构化 `ComparisonResult`：`identical` 基于 `full_rel < pass_threshold` 判定；`differences` 列出超限指标；`error_stats` 包含全部数值
+- `path_params` 声明 `script`/`case_dir`，路径由框架按 workspace 解析
 - 脚本 stdout 进入 `Comparator Output` 区块
 
 使用方法：将插件文件复制到 workspace 的 `comparators/` 目录下即可自动发现，无需改框架代码。