diff --git a/.gitignore b/.gitignore
index e31dddb..d3c2d30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,4 +25,5 @@ test_output.txt
 .coverage
 case/
 *.egg-info/
-.symtest
\ No newline at end of file
+.symtest
+.venv/
\ No newline at end of file
diff --git a/MANIFEST.in b/MANIFEST.in
index bf2f3b9..ef39e29 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,4 +1,5 @@
 include README.md
 include LICENSE
 recursive-include docs *
-recursive-include tests * 
\ No newline at end of file
+recursive-include skill *
+recursive-include tests *
\ No newline at end of file
diff --git a/README.md b/README.md
index a91fa20..12fce49 100644
--- a/README.md
+++ b/README.md
@@ -30,8 +30,8 @@ one JSON or YAML configuration:
 - **Verify results** — return codes, output text and regular expressions, plus
   text, JSON, CSV, XML, HDF5, binary, and custom-script file comparisons.
 - **Manage large suites** — split configurations with `import`, reuse templates
-  with `extends`, filter by name or tag, and inspect cases across files in the
-  optional TUI.
+  with `extends`, filter by name or tag, and locate cases across files with
+  `symtest find`.
 - **Iterate and integrate** — parallel execution, `--last-failed`, step-level
   `--resume`, runtime history, structured reports, and JUnit XML output.
 
@@ -46,11 +46,10 @@ Python 3.9 or newer is required.
 pip install symtest-cli
 ```
 
-YAML and the TUI are optional:
+YAML support is optional:
 
 ```bash
 pip install "symtest-cli[yaml]"
-pip install "symtest-cli[tui]"
 pip install "symtest-cli[all]"
 ```
 
@@ -155,7 +154,7 @@ symtest run solver_tests.json -t long_case --resume
 `--resume` deliberately trusts that workspace artifacts have not changed
 between runs.
 
-## Large test suites and the optional TUI
+## Large test suites and cross-file search
 
 Large suites can be divided into sub-configurations:
 
@@ -168,12 +167,12 @@ Large suites can be divided into sub-configurations:
 }
 ```
 
-The optional TUI provides one searchable view across imported files. It is
-intended as an aid for locating cases and reviewing scenario coverage in large
-projects, rather than a requirement for normal test execution.
+`symtest find` auto-expands all `import` references and searches across the
+unified case set (substring / fuzzy / regex modes), making it easy to locate
+cases and review scenario coverage in large projects:
 
 ```bash
-symtest tui main_config.json
+symtest find main_config.json "login"
 ```
 
 ## Parallel execution and resources
@@ -249,9 +248,9 @@ requirement for using the framework.
 - [User manual](docs/user_manual_en.md)
 - [Design document](docs/design_en.md)
 - [Plugin examples](examples/plugins/README.md)
-- [AI Skill template](examples/skill/) — import framework knowledge into AI coding
-  assistants so they can author test cases, acceptance criteria,
-  and TDD workflows directly
+- [Official AI Skill](skill/) — install this skill into AI coding assistants
+  so they can author test cases, acceptance criteria, and TDD workflows
+  directly — the recommended entry point for new users
 
 ## Development
 
diff --git a/README_cn.md b/README_cn.md
index 7243519..6200dec 100644
--- a/README_cn.md
+++ b/README_cn.md
@@ -25,7 +25,7 @@ CLI Test Framework 使用一份 JSON 或 YAML 配置，同时描述执行流程
 - **验证结果**：支持返回码、输出文本、正则表达式，以及 text、JSON、CSV、XML、
   HDF5、二进制和自定义脚本文件比较。
 - **管理大型测试集**：通过 `import` 拆分配置、通过 `extends` 复用模板、按名称或
-  标签筛选，并可在可选 TUI 中跨文件查看用例。
+  标签筛选，并可用 `symtest find` 跨文件定位用例。
 - **迭代与集成**：支持并行执行、`--last-failed`、步骤级 `--resume`、耗时历史、
   结构化报告和 JUnit XML。
 
@@ -39,11 +39,10 @@ CLI Test Framework 使用一份 JSON 或 YAML 配置，同时描述执行流程
 pip install symtest-cli
 ```
 
-YAML 和 TUI 均为可选能力：
+YAML 为可选能力：
 
 ```bash
 pip install "symtest-cli[yaml]"
-pip install "symtest-cli[tui]"
 pip install "symtest-cli[all]"
 ```
 
@@ -143,7 +142,7 @@ symtest run solver_tests.json -t long_case --resume
 
 `--resume` 明确信任两次运行之间的工作区产物未被修改。
 
-## 大型测试集与可选 TUI
+## 大型测试集与跨文件搜索
 
 大型测试集可以拆分为多个子配置：
 
@@ -156,11 +155,11 @@ symtest run solver_tests.json -t long_case --resume
 }
 ```
 
-可选 TUI 能在所有导入文件之上提供统一的可搜索视图，主要用于大型项目中定位用例和
-辅助检查场景覆盖情况，并不是日常执行测试的必要组件。
+`symtest find` 会自动展开全部 `import` 引用，在统一展开后的用例集上执行搜索
+（子串 / 模糊 / 正则三种模式），便于大型项目中定位用例和检查场景覆盖：
 
 ```bash
-symtest tui main_config.json
+symtest find main_config.json "login"
 ```
 
 ## 并行执行与资源
@@ -232,7 +231,7 @@ compare-files data1.json data2.json --json-compare-mode key-based --json-key-fie
 - [中文使用说明](docs/user_manual.md)
 - [中文设计文档](docs/design.md)
 - [插件示例](examples/plugins/README.md)
-- [AI Skill 模板](examples/skill/) — 可将框架知识导入 AI 编程助手，
+- [官方 AI Skill](skill/) — 可将框架知识导入 AI 编程助手（推荐的入门方式），
   让 AI 直接使用框架编写测试用例、验收标准和 TDD 工作流
 
 ## 开发
diff --git a/docs/design.md b/docs/design.md
index 2bf9b0e..773c533 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -10,8 +10,8 @@
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  CLI 入口层    symtest run / tui / validate / schema /       │
-│                compare-files（+ TUI 交互界面）                │
+│  CLI 入口层    symtest run / find / validate / schema /      │
+│                compare-files                                  │
 └───────────────────────────┬─────────────────────────────────┘
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
@@ -32,7 +32,7 @@
 └─────────────────────────────────────────────────────────────┘
 ```
 
-框架分为四层：**CLI 入口层**（含 TUI）、**Runner / Comparator 业务层**、**Config 管线层**、**Core 基础层**。
+框架分为四层：**CLI 入口层**、**Runner / Comparator 业务层**、**Config 管线层**、**Core 基础层**。
 
 层与层不是自由组合：跨层数据流与依赖方向受 §10「核心架构宪法」约束，
 新增 feature 请先对照宪法确定归属。
@@ -49,14 +49,13 @@
 | `runners/` | Config/JSON/YAML × 顺序/并行 的薄封装运行器 |
 | `file_comparator/` | 比较器家族 + 工厂 + workspace 插件发现（详见 §6） |
 | `utils/` | 路径解析、报告生成、JUnit XML 输出 |
-| `tui/` | Textual 交互式用例管理（详见 §7） |
 
 ### 2.1 入口点
 
 | 命令 | 映射 |
 |---|---|
 | `symtest run` | `symtest.cli:run_tests` |
-| `symtest tui` | `symtest.tui.app:run_tui` |
+| `symtest find` | `symtest.commands.find:run_find` |
 | `symtest validate` | `symtest.cli:run_validate` |
 | `symtest schema` | `symtest.cli:run_schema` |
 | `symtest compare` | `symtest.cli:run_compare` |
@@ -155,14 +154,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,33 +174,68 @@ 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 的走自主泳道
 
-- 文本系比较器共享 difflib 行级基底，json / csv / xml 为其结构化特化（键对齐 / 列结构 / DOM 对齐）
-- h5 面向科学数据集；binary 流式分块 + LCS 相似度；script 委托外部脚本
-- 统一返回 ComparisonResult（identical / differences / error / script command_output），支持 text / json / html 渲染；支持行列窗口范围参数截取后比较
+### 6.2 通道协议（数据泳道）
+
+- 通道判定：`identical = all(channels.passed)`；差异 position 带通道前缀（`channel S33`）；`error_stats` 按通道名嵌套
+- 内置 `script_extract` 类型：子进程执行用户脚本（零改动接入），脚本 stdout 输出约定 JSON：
+
+```json
+{"channels": {"S11": {"expected": [...], "actual": [...], "extra_stats": {...}}}}
+```
 
-### 6.2 工厂与插件发现
+  非零退出、超时、畸形 JSON 一律判为比较 error（绝不静默通过）；`actual`/`baseline` 按惯例以 baseline 在前的顺序追加为尾部 argv 槽位（可缺省）
+- 结果粒度：一条 compareSpec = 一条断言；`ComparisonResult.channels` 携带通道级子结果，报告逐通道展示 pass/fail + stats；JSON 输出中通道 differences 按 per-channel 配额截断
 
-- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script`；工厂按类型分发，支持动态注册与全局 reset（测试用）
-- 插件发现四处来源：内置 `*_comparator.py` 自动发现、`workspace/comparators/` 自动扫描、`--plugin-dir` CLI 参数、`CLITEST_PLUGIN_DIRS` 环境变量（供进程模式 worker 使用）
-- 命名约定：`*_comparator.py` + `*Comparator` 类名
+### 6.3 工厂与插件发现
 
-### 6.3 script 比较协议（对外契约）
+- `file_type` 取值：`text` / `json` / `csv` / `xml` / `h5` / `binary` / `script` / `script_extract`；工厂按类型分发，支持动态注册与全局 reset（测试用）
+- 插件发现四处来源：内置 `*_comparator.py` 自动发现、`workspace/comparators/` 自动扫描、`--plugin-dir` CLI 参数、`CLITEST_PLUGIN_DIRS` 环境变量（用户声明的输入；框架只读，进程模式 worker 经进程池 initializer 显式接收插件目录，框架从不修改 `os.environ`）
+- 命名约定：`*_comparator.py` + `*Comparator` 类名；可用类属性 `comparator_type` 显式指定类型名（如 `script_extract`）；抽象基类自动跳过注册
+- 配置传递与严格校验：`actual`/`baseline`/`type`/`options` 之外的键转发给比较器构造函数（kwargs）；构造器参数是**严格**的——未声明的键（拼写错误）在构造时大声失败并给出支持参数清单。`options` 是框架持有的插件配置命名空间（并入构造参数，显式顶层键优先），核心 schema 不为单个插件增加专属字段；`channels`/`default_channel` 属数据泳道框架结构
 
-- 子进程方式执行 `<interpreter> <script> <actual> <baseline>`
+### 6.4 script 比较协议（自主泳道对外契约）
+
+- 子进程方式执行 `<interpreter> <script> <baseline> <actual>`（文件槽位可缺省）
 - 默认 exit code 0 → 通过；可选 `pass_pattern` / `fail_pattern` 正则匹配 stdout 细化判定
 - 超时可配
 
-## 7. TUI 子系统
+### 6.5 插件公共 API
+
+`symtest.file_comparator` 包导出：`ComparatorBase` / `CompareContext` /
+`FileComparator` / `ExtractorComparator` / `ChannelData` / `ChannelResult` /
+`compare_numeric` / `NumericComparisonStats` / `parse_data_filter`。
+数据泳道插件只需依赖 `ExtractorComparator` + `ChannelData`，数值判定全部复用框架核心。
 
-基于 Textual 的终端交互界面：App + Controller（load / create / update /
-delete / run_single / save 业务动作）+ 列表 / 编辑两屏 + 表格封装、多模式搜索条
-（名称 / 命令 / 标签）、expected 编辑器、steps 编辑器。
+## 7. 用例搜索命令（find）
 
-快捷键：`q` / Ctrl+Q 退出、`r` 刷新、`e` 编辑、`f` 单跑、`/` 搜索、`a` 新增、`d` 删除、`s` 保存。
+替代已移除的 TUI 搜索能力：`symtest find` 走与 runner 完全相同的加载路径
+（`load_config` 自动展开 import + 继承解析，`parse_test_cases` 全系统唯一
+解析器），在展开后的用例集上按三种模式匹配（子串 / 模糊 / 正则，字段覆盖
+name / command / args / tags / description），支持叠加标签过滤与 JSON 输出
+（供 AI / 脚本消费）。退出码沿用 grep 语义：有匹配 0、无匹配 1、错误 2。
 
-TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处理（§10 原则 6）。
+原 TUI 的另一职责（给不习惯写配置的同事提供图形化定义/修改用例）由官方
+skill（仓库根 `skill/`）承担：AI 编程助手按 skill 知识直接生成/修改
+JSON/YAML 配置，学习成本更低且无交互界面维护负担。
 
 ## 8. 扩展点
 
@@ -213,9 +244,8 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 | 新配置格式 | `BaseRunner` | 支持新的测试定义格式（如 XML、TOML） |
 | 自定义 Setup | `BaseSetup` | 数据库初始化、服务启停等 |
 | 自定义断言 | 扩展 `Assertions` | 特定业务校验逻辑 |
-| 新比较器 | `BaseComparator` | 支持新的文件格式比较，放入 `comparators/` 目录自动发现 |
+| 新比较器 | `FileComparator` / `ExtractorComparator` / `ComparatorBase` | 按泳道选择基类（文件格式 / 数据提取+通道 / 全权分析），放入 `comparators/` 目录自动发现 |
 | 新 Runner | `ParallelRunner` / `BaseRunner` | 自定义并行调度策略 |
-| TUI 扩展 | `CaseController` / Widgets | 扩展终端管理界面 |
 
 ## 9. 设计决策
 
@@ -241,7 +271,7 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 | DAG 依赖调度 | 基于 Kahn 拓扑 + 就绪队列，依赖满足后立即提交；依赖失败级联 skip 下游；无依赖时走 fast path 零开销 |
 | --update-baseline | 比较失败时自动将实际输出覆盖 baseline，适合批量更新基准 |
 | next_action_hint 结构化建议 | 失败结果附带下一步操作建议（update_baseline / update_expected / increase_timeout / investigate），便于 AI 消费 |
-| TUI 基于 Textual | 利用成熟的终端 UI 框架，提供交互式用例管理 |
+| 移除 TUI，由官方 skill + `symtest find` 替代 | TUI 的两大职责均有更轻替代：定义/修改用例由 AI 编程助手按官方 skill 完成，跨文件搜索由复用同一解析管线的 `find` 命令覆盖；移除后砍掉 textual 重依赖与交互界面维护负担 |
 | JUnit XML 输出 | 兼容 GitLab CI / Jenkins / CircleCI 等主流 CI 系统的测试报告格式 |
 | Logging 统一化 | 通过 `logging` 模块集中管理，CLI 入口激活控制台输出，库用户按需启用 |
 
@@ -252,7 +282,6 @@ TUI 与 runner 共用同一解析器；宽松的展示形态在 TUI 侧自行处
 > **地位与效力**：本节自 Symtest 1.4 Phase 0 评审定稿，是本项目的核心架构契约，
 > 对所有后续 feature 具有最高约束力——任何功能需求先对照本宪法确定归属，再写代码。
 > 修订宪法必须在变更说明中显式指出所放宽/违反的条款及理由。
-> 定稿前的演进推导见开发阶段文档 docs/design_1_4.md。
 
 ### 10.1 数据流主线
 
@@ -330,10 +359,10 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 
 #### 原则 6 — 核心模型不依赖表现层
 
-`core` 绝对不能 import：`cli` / `tui` / `reporter` / AI-specific adapter。
+`core` 绝对不能 import：`cli` / `reporter` / AI-specific adapter。
 
-解析器全系统唯一：TUI 与 runner 使用同一 parser，不允许存在 "TUI mode 后门"
-（如 workspace=None 时放宽校验）；宽松形态由 TUI 侧自行处理。
+解析器全系统唯一：不允许存在宽松解析后门（如 workspace=None 时放宽校验）；
+宽松形态由调用方先 normalize 再调用。
 
 ### 10.3 模块依赖方向
 
@@ -348,7 +377,7 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 - `execution` 与 `validation` 互不 import；
 - `executor` 不得 import `assertions` / validation 侧模块；
 - `validator` 不得启动被测进程（见原则 3）；
-- `core` 不得 import `cli` / `tui` / `reporter`。
+- `core` 不得 import `cli` / `reporter`。
 
 ### 10.4 违宪归属速查
 
@@ -369,20 +398,7 @@ Reporter 的合法输入只能是 Result 类型；`next_action_hint` 属于 resu
 宪法不是纯文档约定，配套 architecture guard 测试并由 CI 强制：
 
 - 断言 import 图：如 `execution/executor.py` 的 import 不得出现
-  `assertions` / `validation`；`core/**` 不得 import `cli` / `tui` /
+  `assertions` / `validation`；`core/**` 不得 import `cli` /
   `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 拆除，单一解析器 |
diff --git a/docs/design_en.md b/docs/design_en.md
index 71acdeb..969ccff 100644
--- a/docs/design_en.md
+++ b/docs/design_en.md
@@ -13,8 +13,8 @@
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  CLI Entry Layer    symtest run / tui / validate / schema /  │
-│                     compare-files (+ TUI interface)          │
+│  CLI Entry Layer    symtest run / find / validate / schema / │
+│                     compare-files                             │
 └───────────────────────────┬─────────────────────────────────┘
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
@@ -37,7 +37,7 @@
 └─────────────────────────────────────────────────────────────┘
 ```
 
-The framework is divided into four layers: **CLI Entry Layer** (including TUI),
+The framework is divided into four layers: **CLI Entry Layer**,
 **Runner / Comparator Business Layer**, **Config Pipeline Layer**, and
 **Core Foundation Layer**.
 
@@ -57,14 +57,13 @@ Responsibilities by package (file-level details and public APIs live in source):
 | `runners/` | Thin wrapper runners: Config/JSON/YAML × sequential/parallel |
 | `file_comparator/` | Comparator family + factory + workspace plugin discovery (see §6) |
 | `utils/` | Path resolution, report generation, JUnit XML output |
-| `tui/` | Interactive Textual case management (see §7) |
 
 ### 2.1 Entry Points
 
 | Command | Mapping |
 |---|---|
 | `symtest run` | `symtest.cli:run_tests` |
-| `symtest tui` | `symtest.tui.app:run_tui` |
+| `symtest find` | `symtest.commands.find:run_find` |
 | `symtest validate` | `symtest.cli:run_validate` |
 | `symtest schema` | `symtest.cli:run_schema` |
 | `symtest compare` | `symtest.cli:run_compare` |
@@ -164,10 +163,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)
@@ -208,17 +203,21 @@ guarantees they are unmodified.
 - Default exit code 0 → pass; optional `pass_pattern` / `fail_pattern` regexes refine the verdict on stdout
 - Timeout configurable
 
-## 7. TUI Subsystem
-
-Textual-based terminal UI: App + Controller (load / create / update / delete /
-run_single / save actions) + list/edit screens + table wrapper, multi-mode
-search bar (name / command / tag), expected editor, steps editor.
+## 7. Case Search Command (find)
 
-Key bindings: `q` / Ctrl+Q quit, `r` refresh, `e` edit, `f` run single, `/`
-search, `a` add, `d` delete, `s` save.
+Replaces the search capability of the retired TUI: `symtest find` goes through
+exactly the same loading path as the runners (`load_config` auto-expands
+imports + resolves inheritance; `parse_test_cases` is the single system-wide
+parser), then matches cases in three modes (substring / fuzzy / regex, across
+name / command / args / tags / description) with optional tag filtering and
+JSON output (for AI / scripts). Exit codes follow grep semantics: 0 = match,
+1 = no match, 2 = error.
 
-TUI and runners share the same parser; relaxed display shapes are handled on the
-TUI side itself (§10 Principle 6).
+The TUI's other responsibility (graphical case authoring/editing for people
+unfamiliar with writing configs) is now covered by the official skill
+(`skill/` at the repository root): AI coding assistants author/modify
+JSON/YAML configs directly from skill knowledge, with lower learning cost and
+no interactive UI maintenance burden.
 
 ## 8. Extension Points
 
@@ -229,7 +228,6 @@ TUI side itself (§10 Principle 6).
 | Custom assertions | Extend `Assertions` | Specific business validation logic |
 | New comparator | `BaseComparator` | Support new file formats; place in `comparators/` for auto-discovery |
 | New Runner | `ParallelRunner` / `BaseRunner` | Custom parallel scheduling strategies |
-| TUI extensions | `CaseController` / Widgets | Extend the terminal management interface |
 
 ## 9. Design Decisions
 
@@ -254,7 +252,7 @@ TUI side itself (§10 Principle 6).
 | DAG dependency scheduling | Kahn topology + ready queue; submits dependents immediately once deps are satisfied; cascade-skips downstream on dep failure; zero-overhead fast path when no deps declared |
 | --update-baseline | Automatically overwrites baseline files with actual output on comparison failure; ideal for batch baseline updates |
 | next_action_hint structured suggestions | Failed results include actionable suggestions (update_baseline / update_expected / increase_timeout / investigate), convenient for AI consumption |
-| TUI based on Textual | Leverages a mature terminal UI framework for interactive case management |
+| TUI removed; replaced by official skill + `symtest find` | Both TUI responsibilities have lighter replacements: case authoring/editing is done by AI assistants via the official skill; cross-file search is covered by the `find` command reusing the same parsing pipeline; removes the heavy textual dependency and interactive-UI maintenance burden |
 | JUnit XML output | Compatible with GitLab CI / Jenkins / CircleCI and other major CI system test report formats |
 | Centralized logging | All diagnostic messages go through Python's `logging` module; CLI entry activates console output; library users enable as needed |
 
@@ -266,8 +264,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
 
@@ -351,11 +348,11 @@ to result consumers (diagnosis) and must not exist in the execution layer.
 
 #### Principle 6 — The core model does not depend on presentation
 
-`core` must never import: `cli` / `tui` / `reporter` / AI-specific adapters.
+`core` must never import: `cli` / `reporter` / AI-specific adapters.
 
-One parser for the whole system: TUI and runners use the same parser; a "TUI
-mode back door" (e.g., relaxed validation when workspace=None) is forbidden;
-relaxed shapes are handled on the TUI side itself.
+One parser for the whole system: no relaxed-parsing back door is allowed
+(e.g., relaxed validation when workspace=None); relaxed shapes are normalized
+by the caller before invoking the parser.
 
 ### 10.3 Module Dependency Direction
 
@@ -370,7 +367,7 @@ Forbidden:
 - `execution` and `validation` must not import each other;
 - the `executor` must not import `assertions` / validation-side modules;
 - the `validator` must not launch the process under test (see Principle 3);
-- `core` must not import `cli` / `tui` / `reporter`.
+- `core` must not import `cli` / `reporter`.
 
 ### 10.4 Ownership Quick Reference
 
@@ -394,21 +391,7 @@ architecture guard tests enforced by CI:
 
 - Assert the import graph: e.g., imports of `execution/executor.py` must not
   contain `assertions` / `validation`; `core/**` must not import `cli` /
-  `tui` / `reporter`;
+  `reporter`;
 - 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 |
diff --git a/docs/tui_and_config_split_design.md b/docs/tui_and_config_split_design.md
deleted file mode 100644
index 26d88fd..0000000
--- a/docs/tui_and_config_split_design.md
+++ /dev/null
@@ -1,818 +0,0 @@
-# 测试用例管理增强设计文档（配置拆分 + TUI 管理器）
-
-> 本文档描述为解决「测试案例增多导致配置文件过大、不易维护」问题而设计的两项增强能力：
-> **方案 B — 配置拆分机制**（治本，缓解文件膨胀）与 **方案 A — TUI 管理器**（治标，提供可视化 CRUD）。
-
-## 目录
-
-- [1. 背景与目标](#1-背景与目标)
-- [2. 现状分析](#2-现状分析)
-- [3. 总体架构](#3-总体架构)
-- [4. 方案 B：配置拆分机制](#4-方案-b配置拆分机制)
-- [5. 方案 A：TUI 管理器](#5-方案-atui-管理器)
-- [6. 模块结构](#6-模块结构)
-- [7. 数据流](#7-数据流)
-- [8. CLI 集成](#8-cli-集成)
-- [9. 依赖管理](#9-依赖管理)
-- [10. 技术难点与风险](#10-技术难点与风险)
-- [11. 实施阶段与工作量](#11-实施阶段与工作量)
-- [12. 兼容性与回退策略](#12-兼容性与回退策略)
-
----
-
-## 1. 背景与目标
-
-### 1.1 问题
-
-随着被测项目的规模增长，单个测试配置文件（`test_cases.json` / `test_cases.yaml`）中的用例数量可能达到数十甚至数百条。每条用例又包含 `command`、`args`、`expected`（嵌套 dict）、`steps`、`resources`、`tags` 等字段，导致：
-
-- **文件过长**：动辄上千行，人工浏览、定位、修改成本高。
-- **易冲突**：多人协作时合并冲突频繁。
-- **复用困难**：不同测试套件之间无法共享用例片段。
-- **编辑易错**：手工编辑大段 JSON/YAML 容易出现缩进、逗号、字段缺失等语法错误。
-
-### 1.2 目标
-
-| 目标 | 对应方案 |
-|---|---|
-| 从结构上拆分大配置文件，按模块/标签组织用例 | 方案 B（配置拆分） |
-| 提供可视化界面浏览、编辑、运行用例 | 方案 A（TUI） |
-| 不破坏现有 CLI 用法，向后兼容 | 两者皆需 |
-| 最小化对核心代码的侵入 | 两者皆需 |
-| 保持核心包轻量，TUI 依赖可选安装 | 方案 A |
-
----
-
-## 2. 现状分析
-
-### 2.1 现有读写闭环
-
-框架已具备完整的配置读写能力，这是两项增强方案的共同基础：
-
-```
-配置文件 (JSON/YAML)
-    │  JSONRunner/YAMLRunner.load_test_cases()
-    │  → json.load / yaml.safe_load
-    ▼
-config dict  (含 "test_cases" 列表)
-    │  core.config_loader.parse_test_cases()
-    ▼
-List[TestCase]  (dataclass)
-    │  run_single_test() / _run_sequence()
-    ▼
-results dict
-```
-
-### 2.2 关键复用点
-
-| 能力 | 现状 | 对增强方案的意义 |
-|---|---|---|
-| `TestCase` / `TestCaseStep` 数据模型 | dataclass，字段清晰 | 可直接映射为 TUI 表格列 / 表单字段 |
-| `TestCase.to_dict()` | 已实现，对象 → dict | TUI 保存写回配置文件几乎零成本 |
-| `parse_test_cases()` | 已实现，dict → `List[TestCase]` | TUI 读取配置已有完整逻辑 |
-| 配置格式 | 纯 JSON/YAML，顶层 `test_cases` 数组 | 结构简单，拆分与 TUI 展示均不复杂 |
-| CLI 入口 | `cli.py` 用 argparse subparsers | 可无缝新增 `tui` 子命令 |
-
-### 2.3 `TestCase` 数据模型回顾
-
-```python
-@dataclass
-class TestCaseStep:
-    command: str
-    args: List[str]
-    expected: Dict[str, Any]
-    timeout: Optional[float] = None
-
-@dataclass
-class TestCase:
-    name: str
-    command: str = ""
-    args: List[str] = field(default_factory=list)
-    expected: Dict[str, Any] = field(default_factory=dict)
-    description: str = ""
-    timeout: Optional[float] = None
-    resources: Optional[Dict[str, Any]] = None
-    steps: Optional[List[TestCaseStep]] = None
-    tags: List[str] = field(default_factory=list)
-
-    def to_dict(self) -> Dict[str, Any]: ...
-```
-
-两种模式：
-- **单命令模式**：`command` + `args` + `expected`
-- **步骤序列模式**：`steps` 列表，每步含 `command` + `args` + `expected` + `timeout`
-
----
-
-## 3. 总体架构
-
-两项方案在架构上互补，且都遵循「只做展示/组织层，复用核心读写逻辑」的原则：
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                      用户交互层                           │
-│   symtest run      symtest tui      symtest validate  │
-│      (现有)          (新增 A)           (新增 B 辅助)      │
-└─────────┬───────────────┬───────────────────┬────────────┘
-          │               │                   │
-┌─────────▼───────────────▼───────────────────▼────────────┐
-│                   管理增强层 (新增)                        │
-│  ┌─────────────────────┐   ┌──────────────────────────┐  │
-│  │ config_io.py (B)    │   │ tui/ (A)                 │  │
-│  │  配置读写封装        │   │  app / screens / widgets │  │
-│  │  导入展开            │   │  依赖 config_io          │  │
-│  └──────────┬──────────┘   └────────────┬─────────────┘  │
-└─────────────┼───────────────────────────┼────────────────┘
-              │                           │
-┌─────────────▼───────────────────────────▼────────────────┐
-│                      核心层 (复用，不改动)                 │
-│  parse_test_cases()  │  TestCase.to_dict()               │
-│  BaseRunner / Runners│  Assertions / Execution           │
-└──────────────────────────────────────────────────────────┘
-```
-
-**设计原则**：
-1. 管理增强层**只做读写封装与展示**，不重新实现解析/断言/执行逻辑。
-2. 核心层 `parse_test_cases()` 与 `TestCase.to_dict()` 不需要修改。
-3. 配置拆分在「加载时展开」为标准 config dict，对 Runner 完全透明。
-
----
-
-## 4. 方案 B：配置拆分机制
-
-### 4.1 设计目标
-
-让用户可以把一个大配置文件拆成多个小文件，按模块/功能/标签组织，运行时自动合并加载。**不改 Runner，不改 `parse_test_cases`**，仅在「文件 → config dict」这一步做展开。
-
-### 4.2 拆分方式：显式导入（import 引用）
-
-主配置文件通过 `import` 字段引用子文件：
-
-```json
-// main_config.json
-{
-  "setup": {
-    "environment_variables": { "PYTHONPATH": "./src" }
-  },
-  "test_cases": [
-    { "import": "cases/text_tests.json" },
-    { "import": "cases/json_tests.json" },
-    { "import": "cases/h5_tests.yaml" }
-  ]
-}
-```
-
-子文件结构与主文件中的 `test_cases` 元素一致，即子文件顶层就是 `test_cases` 数组：
-
-```json
-// cases/text_tests.json
-{
-  "test_cases": [
-    {
-      "name": "text_identical",
-      "command": "python",
-      "args": ["./compare_text.py"],
-      "expected": { "return_code": 0 }
-    }
-  ]
-}
-```
-
-**展开规则**：加载主配置时，遇到 `test_cases` 中带 `import` 键的元素，递归读取子文件，把子文件的 `test_cases` 内联展开替换 `import` 元素。
-
-### 4.3 展开算法
-
-```
-function load_and_expand(config_path, workspace):
-    raw = json.load / yaml.safe_load(config_path)
-    
-    # 1. 合并 setup（如果有）
-    setup = raw.get("setup", {})
-    
-    # 2. 展开 test_cases
-    expanded_cases = []
-    for item in raw.get("test_cases", []):
-        if "import" in item:
-            sub_path = resolve_relative_to(config_path, item["import"])
-            sub_raw = load_and_expand(sub_path, workspace)  # 递归
-            sub_setup = sub_raw.get("setup", {})
-            merge_setup(setup, sub_setup)
-            expanded_cases.extend(sub_raw["test_cases"])
-        else:
-            expanded_cases.append(item)
-    
-    return { "setup": setup, "test_cases": expanded_cases }
-```
-
-**循环引用保护**：维护一个已加载文件路径集合，遇到重复路径时抛出明确错误。
-
-**路径解析**：`import` 路径相对于**主配置文件所在目录**解析，不相对于 cwd。
-
-### 4.4 配置校验辅助命令
-
-新增 `validate` 子命令，在不运行测试的情况下检查配置：
-
-```bash
-symtest validate test_cases.json
-symtest validate ./test_suite/
-```
-
-校验内容：
-- JSON/YAML 语法正确性
-- 必填字段完整性（`name`、`command`、`args`、`expected`）
-- `import` 引用的文件是否存在
-- 循环引用检测
-
-### 4.5 与 Runner 的集成方式
-
-**关键决策：在 Runner 加载配置时做展开，而非修改 `parse_test_cases`。**
-
-两种集成路径（择一）：
-
-| 路径 | 做法 | 侵入性 |
-|---|---|---|
-| **路径 1（推荐）**：在 `BaseRunner.load_test_cases()` 调用 `load_and_expand()` 替代直接 `json.load` | 改动集中在各 Runner 的 `load_test_cases`，一行替换 | 低 |
-| 路径 2：在 `cli.py` 展开后写临时文件传给 Runner | 不改 Runner，但产生临时文件 | 中 |
-
-推荐**路径 1**，因为 `JSONRunner.load_test_cases()` 和 `YAMLRunner.load_test_cases()` 当前实现就是「读文件 → 调 `parse_test_cases`」，只需在「读文件」后插入展开步骤。
-
----
-
-## 5. 方案 A：TUI 管理器
-
-### 5.1 技术选型
-
-| 候选 | 评估 |
-|---|---|
-| **Textual**（推荐） | 基于 rich，现代 TUI 框架，支持 CSS 样式、组件化、虚拟滚动表格；SSH 友好；与 CLI 框架定位一致 |
-| prompt_toolkit | 更底层，稳定但开发量大 |
-| curses | 太底层，跨平台性差（Windows 支持弱） |
-| tkinter / PyQt | GUI 方案，不支持 SSH，依赖重，与 CLI 定位不符 |
-| Streamlit / Gradio | Web UI，需起服务，不适合纯终端场景 |
-
-**选型结论：Textual**。理由：
-1. 与 CLI 框架定位高度一致。
-2. SSH/远程开发友好（用户多为开发者）。
-3. 组件丰富（DataTable、Input、TabbedContent 等），开发效率高。
-4. 依赖可控，可作为可选依赖安装。
-
-### 5.2 界面设计
-
-#### 主界面 — 用例列表
-
-```
-┌─ CLI Test Framework - Case Manager ──────────────────────┐
-│ File: test_cases.json          [15 cases]  [tag: All   ]  │
-├──────────────────────────────────────────────────────────┤
-│ Search: [json_exact                    ]  [3 matches    ]  │
-├──────────────────────────────────────────────────────────┤
-│ #  │ Name           │ Command      │ Tags      │ Timeout │
-│────┼────────────────┼──────────────┼───────────┼─────────│
-│▶2  │ json_exact     │ python ./co..│ json      │ -       │
-│ 3  │ h5_comparison  │ python ./co..│ h5        │ 30.0    │
-│ 5  │ json_partial   │ python ./co..│ json,fuzz │ 5.0     │
-├──────────────────────────────────────────────────────────┤
-│ [/]fuzzy  [a]dd  [e]dit  [d]elete  [u]plicate  [r]un  [F6]save  [^Q]quit│
-└──────────────────────────────────────────────────────────┘
-```
-
-功能：
-- 表格展示所有 case，列：序号、名称、命令、标签、超时、模式（单命令/序列）
-- 顶部状态栏：当前文件、用例数、tag 过滤下拉
-- **搜索栏**：实时模糊搜索，搜索所有字段（name / command / args / tags / description）
-- 底部快捷键栏，`/` 键快速聚焦搜索框
-
-#### 编辑界面 — 表单
-
-单命令模式：
-```
-┌─ Edit Test Case ─────────────────────────────────────────┐
-│ Name:     [json_exact                          ]          │
-│ Command:  [python                              ]          │
-│ Args:     [./compare_json.py, --strict         ]          │
-│ Timeout:  [                                     ]          │
-│ Tags:     [json, exact                          ]          │
-│ Description:                                              │
-│ [Compare two JSON files with exact matching             ] │
-│                                                          │
-│ ── Expected ─────────────────────────────────────────── │
-│ return_code:      [0      ]                              │
-│ output_contains:  [+ Add string]                         │
-│   • "success"  [x]                                       │
-│   • "done"     [x]                                       │
-│ output_matches:   [.*regex.*]  (optional)                │
-│ compare_files:   [+ Add file pair]                       │
-│                                                          │
-│ [Save]  [Cancel]  [Switch to Sequence Mode]              │
-└──────────────────────────────────────────────────────────┘
-```
-
-步骤序列模式：
-```
-┌─ Edit Test Case (Sequence) ──────────────────────────────┐
-│ Name: [multi_step_pipeline              ]                 │
-│ Tags: [pipeline                         ]                 │
-│                                                          │
-│ ── Steps ─────────────────────────────────────────────  │
-│ Step 1/3  [Edit] [Delete] [↑] [↓]                        │
-│   command: python ./step1.py                             │
-│ Step 2/3  [Edit] [Delete] [↑] [↓]                        │
-│   command: python ./step2.py                             │
-│ Step 3/3  [Edit] [Delete] [↑] [↓]                        │
-│   command: python ./step3.py                             │
-│ [+ Add Step]                                             │
-│                                                          │
-│ [Save]  [Cancel]  [Switch to Single Command Mode]        │
-└──────────────────────────────────────────────────────────┘
-```
-
-#### 运行结果面板
-
-选中单条 case 按 `r` 运行后，底部弹出结果面板：
-```
-┌─ Run Result: json_exact ─────────────────────────────────┐
-│ Status: PASSED   Return code: 0   Duration: 1.23s        │
-├──────────────────────────────────────────────────────────┤
-│ Output:                                                  │
-│ Comparing files...                                       │
-│ Files are identical.                                     │
-│                                                          │
-│ [Close]                                                  │
-└──────────────────────────────────────────────────────────┘
-```
-
-### 5.3 功能清单
-
-| 功能 | 说明 |
-|---|---|
-| 列表浏览 | DataTable 虚拟滚动，支持数百条 case |
-| **模糊搜索** | `/` 键聚焦搜索框，实时模糊搜索所有字段（name / command / args / tags / description）；搜索结果高亮、显示匹配数、上下导航跳转 |
-| tag 过滤 | 按 tag 下拉选择过滤，与搜索条件叠加 |
-| 列排序 | 点击列表头按该列排序（升序/降序切换） |
-| 新增 | 弹出空表单，填完后追加到列表 |
-| 编辑 | 弹出预填表单，保存后更新 |
-| 删除 | 选中后确认删除 |
-| 复制 | 选中后复制为新 case（名称加 `_copy` 后缀） |
-| 上下移动 | 调整 case 在列表中的顺序 |
-| 单条运行 | 调用 `execute_single_test_case` 执行，显示结果 |
-| 批量运行 | 可选：选中多条后运行，复用现有 Runner |
-| 保存 | 写回原配置文件（利用 `to_dict()` + `json.dump` / `yaml.dump`） |
-| 另存为 | 保存到新文件 |
-| 切换模式 | 单命令 ↔ 步骤序列（切换时清空对应字段并提示） |
-| 未保存提示 | 有改动未保存时退出/切换文件时提示确认 |
-
-### 5.3.1 搜索功能深入设计
-
-搜索的设计目标是**不低于 VS Code Ctrl+F 的使用体验**。具体实现如下：
-
-#### 搜索模式
-
-支持三种模式，通过 `Tab` 切换：
-
-| 模式 | 快捷键 | 说明 | 示例 |
-|---|---|---|---|
-| 子串匹配（默认） | - | 大小写不敏感，任意位置匹配 | `json` 匹配 `json_exact`、`compare_json`、`MyJsonTest` |
-| 模糊匹配 | `Alt+F` | 字符级模糊，容忍拼写差异和缩写 | `jexc` 匹配 `json_exact`、`jsont` 匹配 `json_test` |
-| 正则匹配 | `Alt+R` | 完整正则，大小写敏感可选 | `json.*h5`、`^(text\|json)_` |
-
-#### 模糊匹配算法
-
-使用 **双阶段匹配**，在搜索性能和结果质量间取得平衡：
-
-1. **初筛（filtering）**：对每个 case 展开所有可搜索字段为一个文本 blob，对所有 blob 做字符级模糊匹配。使用基于 N-gram（1-gram + 2-gram）的评分，快速粗筛。
-2. **精排（scoring）**：对候选结果按匹配质量排序：
-   - **连续子串匹配** > 分隔字符匹配 > 非连续匹配
-   - name 字段匹配权重 > command 字段 > 其他字段
-   - 匹配位置越靠前得分越高
-
-```python
-# 模糊匹配评分伪代码
-def fuzzy_score(query: str, candidate_fields: dict) -> float:
-    score = 0.0
-    field_weights = {"name": 2.0, "command": 1.5, "description": 1.0,
-                     "tags": 1.0, "args": 0.5}
-    
-    for field_name, text in candidate_fields.items():
-        weight = field_weights.get(field_name, 0.5)
-        # N-gram overlap score
-        score += weight * ngram_similarity(query, text.lower())
-    
-    return score
-```
-
-#### 搜索字段
-
-默认搜索所有以下字段（可配置开关单个字段）：
-
-| 字段 | 权重 | 可禁用 |
-|---|---|---|
-| `name` | 2.0 | ✓ |
-| `command` | 1.5 | ✓ |
-| `args` | 0.5 | ✓ |
-| `tags` | 1.0 | ✓ |
-| `description` | 1.0 | ✓ |
-
-#### 搜索结果导航
-
-- 搜索结果自动过滤表格，仅显示匹配的行。
-- 匹配的文本在表格中**高亮显示**。
-- 搜索栏右侧显示「第 N/M 个匹配」。
-- `Enter` / `Shift+Enter` 在匹配结果间上下跳转。
-- `Esc` 清空搜索，恢复完整列表。
-- 搜索历史：`↑` / `↓` 在搜索框中浏览最近 10 条搜索词。
-
-#### 交互布局
-
-```
-┌─ CLI Test Framework - Case Manager ──────────────────────┐
-│ File: test_cases.json          [15→3]  [tag: All       ]  │
-├──────────────────────────────────────────────────────────┤
-│ Search: [json_▌                          ] [模糊]  [3/3]  │
-│  模式: [子串] [模糊(F)] [正则(R)]  大小写: [Aa]           │
-├──────────────────────────────────────────────────────────┤
-│ #  │ Name           │ Command      │ Tags      │ Timeout │
-│────┼────────────────┼──────────────┼───────────┼─────────│
-│▶2  │ json_exact     │ python ./co..│ json      │ -       │
-│ 3  │ h5_comparison  │ python ./co..│ h5,**json**│ 30.0  │
-│ 5  │ json_partial   │ python ./co..│ json,fuzz │ 5.0     │
-├──────────────────────────────────────────────────────────┤
-│ [/]fuzzy  [a]dd  [e]dit  [d]elete  [u]plicate  [r]un  [F6]save  [^Q]quit│
-└──────────────────────────────────────────────────────────┘
-```
-
-搜索栏展开时显示第二行（模式切换），平时收起只显示一行以节省空间。
-
-### 5.4 `expected` 字段编辑策略
-
-`expected` 是嵌套 dict，key 不固定。采用「已知 key 固定表单 + 未知 key 自定义扩展」策略：
-
-| 已知 key | 编辑方式 |
-|---|---|
-| `return_code` | 数字输入框 |
-| `output_contains` | 字符串列表（动态增删） |
-| `output_matches` | 文本输入框（正则） |
-| `compare_files` | 文件对列表（actual / baseline / type 三元组） |
-
-未知 key 通过「自定义键值对」区域添加，值为字符串或 JSON 文本。
-
----
-
-## 6. 模块结构
-
-### 6.1 新增目录结构
-
-```
-src/symtest/
-├── config/                    ← 新增（方案 B）
-│   ├── __init__.py
-│   ├── config_io.py           # 配置读写封装
-│   └── import_expander.py     # import 引用展开
-├── tui/                       ← 新增（方案 A）
-│   ├── __init__.py
-│   ├── app.py                 # Textual App 主入口
-│   ├── screens/
-│   │   ├── __init__.py
-│   │   ├── case_list.py       # 列表主界面
-│   │   └── case_editor.py     # 编辑表单界面
-│   ├── widgets/
-│   │   ├── __init__.py
-│   │   ├── case_table.py      # 测试用例表格组件
-│   │   ├── expected_editor.py # expected dict 编辑组件
-│   │   ├── steps_editor.py    # steps 序列编辑组件
-│   │   └── search_bar.py      # 模糊搜索栏组件
-│   └── controllers/
-│       ├── __init__.py
-│       └── case_controller.py # 协调 config_io 与 TUI 状态
-├── cli.py                     # 修改：新增 tui / validate 子命令
-└── ...（现有模块不变）
-```
-
-### 6.2 模块职责
-
-| 模块 | 职责 | 依赖 |
-|---|---|---|
-| `config/config_io.py` | 统一的配置读写入口：读文件 → 展开 → 返回 config dict；写 config dict → 文件 | `import_expander` |
-| `config/import_expander.py` | 递归展开 `import` 引用，处理循环引用 | 无（纯逻辑） |
-| `tui/app.py` | Textual App 实例，管理 Screen 切换、全局状态 | textual |
-| `tui/screens/case_list.py` | 列表主界面 Screen | `case_table`、`search_bar`、`case_controller` |
-| `tui/screens/case_editor.py` | 编辑表单 Screen（单命令 + 序列两种模式） | `expected_editor`、`steps_editor` |
-| `tui/widgets/case_table.py` | DataTable 封装，支持过滤排序 | textual |
-| `tui/widgets/search_bar.py` | 模糊搜索栏，支持多字段实时搜索 | textual |
-| `tui/widgets/expected_editor.py` | `expected` 嵌套 dict 编辑组件 | textual |
-| `tui/widgets/steps_editor.py` | `steps` 列表编辑组件 | textual |
-| `tui/controllers/case_controller.py` | 协调 config_io 与 TUI：持有 `List[TestCase]`、处理 CRUD、保存 | `config.config_io`、`core.test_case` |
-
-### 6.3 与现有模块的复用关系
-
-```
-tui/controllers/case_controller.py
-    ├── 读: config.config_io.load_config() → config dict
-    │         → core.config_loader.parse_test_cases() → List[TestCase]
-    └── 写: List[TestCase] → [tc.to_dict() for tc in ...]
-              → config dict → config.config_io.save_config()
-```
-
-**关键：TUI 层不直接调用 `parse_test_cases`，而是通过 `config_io` 拿到 config dict 后复用 `parse_test_cases`。保存时通过 `to_dict()` 重建 config dict 再写回。**
-
----
-
-## 7. 数据流
-
-### 7.1 配置拆分加载流（方案 B）
-
-```
-用户传入 config_file
-       │
-       ▼
-config_io.load_config(config_file, workspace)
-       │
-       └── json.load / yaml.safe_load → raw config dict
-             │
-             └── import_expander.expand(raw, config_path)
-                   ├── 遍历 test_cases
-                   ├── 遇到 {"import": "..."} → 递归 load_config
-                   └── 内联展开
-       │
-       ▼
-展开后的 config dict  (标准结构，与原格式一致)
-       │
-       ▼
-Runner.load_test_cases() → parse_test_cases() → List[TestCase]
-       (Runner 对拆分过程完全无感知)
-```
-
-### 7.2 TUI 编辑流（方案 A）
-
-```
-启动 TUI
-       │
-       ▼
-config_io.load_config(file) → config dict
-       │
-       ▼
-parse_test_cases(config, workspace, path_resolver) → List[TestCase]
-       │
-       ▼
-CaseController 持有 List[TestCase]
-       │
-       ├── 展示 → case_table widget
-       │
-       ├── 用户编辑 → 更新内存中的 TestCase 对象
-       │
-       ├── 单条运行 → execute_single_test_case(tc, workspace) → 结果面板
-       │
-       └── 保存:
-             List[TestCase]
-               │ [tc.to_dict() for tc in cases]
-               ▼
-             config dict {"test_cases": [...], "setup": ...}
-               │
-               ▼
-             config_io.save_config(config_dict, file_path)
-               │
-               ▼
-             json.dump / yaml.dump → 文件
-```
-
-### 7.3 配置校验流（validate 命令）
-
-```
-symtest validate <path>
-       │
-       ▼
-config_io.load_config(path) → config dict  (含展开)
-       │
-       ├── 检查 JSON/YAML 语法 ✓
-       ├── 检查必填字段 ✓
-       ├── 检查 import 引用存在性 ✓
-       └── 循环引用检测 ✓
-       │
-       ▼
-输出校验报告:
-  ✓ Loaded 15 test cases from 3 files
-  ✓ All required fields present
-  ✓ No circular imports detected
-  
-  Files:
-    - main_config.json (5 cases)
-    - cases/text_tests.json (6 cases)
-    - cases/json_tests.json (4 cases)
-```
-
----
-
-## 8. CLI 集成
-
-### 8.1 新增子命令
-
-在 `cli.py` 的 `create_parser()` 中新增：
-
-```python
-# ---- TUI command (方案 A) ----
-tui_parser = subparsers.add_parser('tui', help='Launch interactive TUI for managing test cases')
-tui_parser.add_argument('config_file', help='Path to the test configuration file (JSON or YAML)')
-tui_parser.add_argument('--workspace', '-w', help='Working directory')
-
-# ---- Validate command (方案 B 辅助) ----
-validate_parser = subparsers.add_parser('validate', help='Validate test configuration without running')
-validate_parser.add_argument('config_file', help='Path to config file or directory')
-validate_parser.add_argument('--workspace', '-w', help='Working directory')
-```
-
-### 8.2 `run` 命令增强
-
-`run` 命令的 `config_file` 参数支持带 `import` 引用的主配置文件：
-
-```bash
-# 现有用法（不变）
-symtest run test_cases.json
-symtest run test_cases.yaml
-
-# 新增：带 import 的主配置
-symtest run main_config.json
-```
-
-### 8.3 `main()` 分发
-
-```python
-if args.command == 'run':
-    success = run_tests(args)
-    sys.exit(0 if success else 1)
-elif args.command == 'compare':
-    success = run_compare(args)
-    sys.exit(0 if success else 1)
-elif args.command == 'tui':
-    from .tui.app import run_tui  # 延迟导入，避免未安装 textual 时报错
-    run_tui(args.config_file, args.workspace)
-elif args.command == 'validate':
-    from .config.config_io import validate_config
-    validate_config(args.config_file, args.workspace)
-else:
-    parser.print_help()
-    sys.exit(1)
-```
-
-**注意 `tui` 子命令的延迟导入**：`from .tui.app import run_tui` 放在 `elif` 分支内部，确保未安装 textual 时其他命令不受影响。
-
-### 8.4 使用示例
-
-```bash
-# 方案 B：配置拆分
-symtest run main_config.json          # 自动展开 import
-symtest validate main_config.json     # 校验配置
-
-# 方案 A：TUI 管理
-symtest tui test_cases.json           # 打开 TUI 编辑
-symtest tui test_cases.yaml -w ./proj # 指定工作目录
-
-# 组合使用：拆分配置 + TUI
-symtest tui main_config.json          # TUI 中编辑主配置（含 import 引用）
-```
-
----
-
-## 9. 依赖管理
-
-### 9.1 可选依赖
-
-在 `pyproject.toml` / `setup.py` 中新增 extras：
-
-```toml
-[project.optional-dependencies]
-tui = ["textual>=0.40.0"]
-```
-
-```bash
-pip install symtest-cli[tui]   # 安装 TUI 依赖
-pip install symtest-cli        # 核心包，不含 TUI
-```
-
-### 9.2 优雅降级
-
-当用户执行 `symtest tui` 但未安装 textual 时，给出友好提示：
-
-```python
-def run_tui(config_file, workspace):
-    try:
-        import textual
-    except ImportError:
-        print(
-            "TUI 功能需要安装 textual。请运行：\n"
-            "  pip install symtest-cli[tui]\n"
-            "或：\n"
-            "  pip install textual"
-        )
-        sys.exit(1)
-    # 正常启动 TUI ...
-```
-
-### 9.3 方案 B 无额外依赖
-
-配置拆分机制仅使用标准库（`json`、`pathlib`、`os`）和已有的 `yaml`，不引入新依赖。
-
----
-
-## 10. 技术难点与风险
-
-| 难点 | 说明 | 应对 |
-|---|---|---|
-| `expected` 嵌套 dict 编辑 | key 不固定，含 `return_code`、`output_contains`、`output_matches`、`compare_files` 等 | 已知 key 固定表单 + 未知 key 动态键值对；`compare_files` 做专门的三元组编辑组件 |
-| `steps` 序列模式编辑 | 一个 case 内多步，每步又有完整 command/args/expected | 分步编辑：先选步骤再进步骤编辑表单；支持上下移动、增删 |
-| 单命令 ↔ 序列模式切换 | 字段结构不同，切换会丢失数据 | 切换前提示确认，保留可保留字段（name/tags/description） |
-| Textual 版本兼容 | Textual 仍在 0.x，API 可能变化 | 锁定最低版本 `>=0.40.0`，CI 中固定测试版本 |
-| 配置拆分循环引用 | A import B，B import A | 维护已加载路径集合，检测到循环抛出明确错误 |
-| `import` 路径解析基准 | 相对 cwd 还是相对配置文件 | **相对配置文件所在目录**，更符合直觉 |
-| setup 合并冲突 | 多文件各有 setup.environment_variables | 后加载覆盖先加载（文档明确说明）；同名变量冲突时 warning |
-| 大量 case 性能 | 数百条 case 的 TUI 渲染 | Textual DataTable 支持虚拟滚动，性能可接受 |
-| 保存格式一致性 | 读 YAML 存 JSON 或反之 | 保持原文件扩展名，按扩展名选择 dumper；另存为时按目标扩展名 |
-
----
-
-## 11. 实施阶段与工作量
-
-### 11.1 推荐实施顺序
-
-**方案 B 优先**（投入产出比高，且为方案 A 提供基础）：
-
-```
-阶段 1: 方案 B — 配置拆分
-  ├── import_expander.py
-  ├── config_io.py
-  ├── validate 子命令
-  ├── run 命令集成（支持 import 展开）
-  └── 测试
-
-阶段 2: 方案 A — TUI 管理器
-  ├── config_io 复用（已在阶段 1 完成）
-  ├── case_controller.py
-  ├── case_table + search_bar widgets
-  ├── case_list screen
-  ├── case_editor screen
-  ├── expected_editor / steps_editor widgets
-  ├── tui 子命令 + 优雅降级
-  └── 测试
-```
-
-### 11.2 工作量估算
-
-| 模块 | 估算 |
-|---|---|
-| **方案 B** | |
-| `import_expander.py` | 1 天 |
-| `config_io.py`（读写封装 + 展开集成） | 0.5 天 |
-| `validate` 子命令 + `run` 集成 | 0.5 天 |
-| 测试（含循环引用、展开、合并） | 1 天 |
-| **方案 B 小计** | **3 天** |
-| **方案 A** | |
-| `case_controller.py` + TUI 脚手架 | 0.5 天 |
-| 列表主界面（case_table + 搜索栏 + 过滤排序） | 1.5 天 |
-| 搜索栏（子串/模糊/正则三种模式 + 高亮导航） | 1 天 |
-| 编辑表单（单命令模式 + expected 编辑器） | 1.5 天 |
-| 序列模式编辑（steps_editor） | 1 天 |
-| 单条运行 + 结果面板 | 0.5 天 |
-| `tui` 子命令 + 可选依赖 + 优雅降级 | 0.5 天 |
-| 测试 | 1 天 |
-| **方案 A 小计** | **7.5 天** |
-| **合计** | **约 10.5 天** |
-
----
-
-## 12. 兼容性与回退策略
-
-### 12.1 向后兼容
-
-| 方面 | 兼容性 |
-|---|---|
-| 现有 `run` 命令用法 | ✅ 完全兼容，单文件配置行为不变 |
-| 现有配置文件格式 | ✅ 完全兼容，无 `import` 字段时按原逻辑加载 |
-| `parse_test_cases()` | ✅ 不修改，接收的仍是展开后的标准 config dict |
-| `TestCase.to_dict()` | ✅ 不修改 |
-| Python API（`JSONRunner` / `YAMLRunner` 直接使用） | ✅ 兼容，`load_test_cases` 内部改用 `config_io` 但返回结构不变 |
-| 现有测试 | ✅ 不受影响 |
-
-### 12.2 回退策略
-
-- **方案 B**：如果配置拆分出现问题，用户只需把所有用例放回单文件即可，`config_io` 对无 `import` 的配置与原逻辑等价。
-- **方案 A**：TUI 完全可选，不安装 textual 不影响任何现有功能。用户可随时回退到手工编辑配置文件。
-
-### 12.3 渐进式采用
-
-用户无需一次性迁移所有配置：
-1. 先用 `validate` 命令校验现有配置无问题。
-2. 逐步把大文件中的用例拆到子文件，用 `import` 引用。
-3. 需要可视化编辑时安装 `[tui]` extra 并使用 `symtest tui`。
-
----
-
-## 附录：设计决策汇总
-
-| 决策 | 原因 |
-|---|---|
-| 配置拆分在加载时展开，不改 `parse_test_cases` | 保持核心层纯净，Runner 对拆分无感知 |
-| `import` 路径相对配置文件目录解析 | 比相对 cwd 更符合直觉，配置可移植 |
-| TUI 选 Textual 而非 GUI | 与 CLI 框架定位一致，SSH 友好 |
-| TUI 依赖设为可选 extras | 保持核心包轻量 |
-| `tui` 子命令延迟导入 textual | 未安装时不影响其他命令 |
-| `expected` 用已知 key 固定表单 + 未知 key 动态扩展 | 平衡易用性与灵活性 |
-| 单命令/序列模式可切换 | 适应不同用例复杂度 |
-| 方案 B 优先实施 | 投入产出比高，且为 TUI 提供配置读写基础 |
diff --git a/docs/user_manual.md b/docs/user_manual.md
index 429bd8c..fbfbe82 100644
--- a/docs/user_manual.md
+++ b/docs/user_manual.md
@@ -8,7 +8,7 @@
 - [配置拆分机制](#配置拆分机制)
 - [配置继承](#配置继承)
 - [配置校验](#配置校验)
-- [TUI 交互式管理器](#tui-交互式管理器)
+- [跨文件搜索用例](#跨文件搜索用例find)
 - [运行测试](#运行测试)
 - [项目入口脚本](#项目入口脚本)
 - [占位符（变量替换）](#占位符变量替换)
@@ -38,7 +38,7 @@ YAML 支持需安装可选依赖：
 pip install "symtest-cli[yaml]"
 ```
 
-一次安装 YAML 和 TUI 等全部可选功能：
+一次安装 YAML 等全部可选功能：
 
 ```bash
 pip install "symtest-cli[all]"
@@ -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 格式
 
@@ -195,7 +195,7 @@ test_cases:
             "name": "D",
             "execution": { "command": "python", "args": ["merge.py"] },
             "scheduling": { "depends_on": ["A", "B", "C"] },
-            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
+            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "h5"}]}
         }
     ]
 }
@@ -233,7 +233,7 @@ test_cases:
       return_code: 0
       compare_files:
         - file: output.h5
-          type: hdf5
+          type: h5
 ```
 
 **调度语义**：
@@ -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）的子进程内生效，不影响其他用例。
@@ -616,10 +623,6 @@ symtest run config.json --var solver=/path/to/solver
 - `abstract` 用例不计入可执行用例数
 - `extends` 用例跳过必填字段检查（内容来自父类）
 
-### TUI 编辑限制
-
-> **注意**：TUI 目前不支持编辑继承用例。继承后的展开用例在 TUI 中可正常查看和运行，但请直接编辑 JSON/YAML 源文件来进行修改。
-
 ## 配置校验
 
 `validate` 命令在不运行测试的情况下检查配置文件的正确性，适合在 CI 流水线中做配置合法性检查。
@@ -670,127 +673,32 @@ symtest validate test_cases.json --output-format json
   [FAIL] Import target not found: /project/cases/nonexistent.json
 ```
 
-## TUI 交互式管理器
-
-当大型测试项目把用例拆分到多个 JSON/YAML 子配置后，跨文件定位用例和检查场景覆盖会逐渐困难。TUI（Terminal User Interface）在所有导入配置之上提供统一视图，用于浏览、全局搜索、辅助检查覆盖场景，并可按需编辑或运行用例。它是大型测试集的辅助工具，不是日常执行测试的必需组件。
+## 跨文件搜索用例（find）
 
-### 安装
+大型测试项目把用例拆分到多个 JSON/YAML 子配置后，跨文件定位用例和检查场景覆盖会逐渐困难。`symtest find` 自动展开主配置的全部 `import` 引用，在统一展开后的用例集上执行搜索，是轻量、可脚本化的定位方式。
 
-TUI 依赖 `textual` 库，并作为按需安装的可选依赖提供：
+### 用法
 
 ```bash
-# 安装时附带 TUI 支持
-pip install "symtest-cli[tui]"
-
-# 或者在已有框架上单独安装 textual
-pip install textual
-```
+# 默认子串模式（大小写不敏感），同时匹配 name/command/args/tags/description
+symtest find main_config.json "login"
 
-如果未安装 `textual` 就直接执行 `symtest tui`，框架会给出友好的安装提示。
+# 正则模式
+symtest find main_config.json "log.*in" --mode regex
 
-### 启动
+# 模糊模式（容忍拼写差异与缩写，按相关度排序）
+symtest find main_config.json "lgin" --mode fuzzy
 
-```bash
-# 打开 TUI 编辑测试用例
-symtest tui test_cases.json
-
-# YAML 文件同样支持
-symtest tui test_cases.yaml
+# 与标签过滤叠加（可多次使用，OR 关系）
+symtest find main_config.json "login" --tag smoke
 
-# 指定工作目录
-symtest tui test_cases.json --workspace /path/to/project
-
-# 打开带 import 的主配置文件（自动展开子文件中的所有用例）
-symtest tui main_config.json
+# 输出 JSON（适合 AI/脚本消费）
+symtest find main_config.json "login" --output-format json
 ```
 
-TUI 启动时会自动通过[配置拆分机制](#配置拆分机制)展开 `import` 引用，将所有用例加载到界面中统一管理。
-
-### 界面概览
-
-TUI 启动后显示**用例列表主界面**：
-
-- **顶部状态栏**：当前文件名、用例总数
-- **搜索栏**：`/` 键聚焦搜索框，支持子串/模糊/正则三种模式
-- **用例表格**：六列（序号、名称、命令、标签、超时、模式），支持键盘导航
-- **底部快捷键栏**：显示所有可用操作
-
-### 快捷键
-
-| 快捷键 | 功能 |
-|---|---|
-| `a` | 新增用例 |
-| `e` | 编辑选中的用例 |
-| `d` | 删除选中的用例 |
-| `u` | 复制选中的用例（名称追加 `_copy` 后缀） |
-| `r` | 运行选中的用例，显示执行结果 |
-| `F6` / `Ctrl+S` | 保存修改到文件 |
-| `/` | 聚焦搜索框 |
-| `Esc` | 清除搜索，恢复完整列表 |
-| `Alt+S` | 切换子串搜索模式（大小写不敏感） |
-| `Alt+F` | 切换模糊搜索模式（容忍拼写差异和缩写） |
-| `Alt+R` | 切换正则搜索模式 |
-| `q` / `Ctrl+Q` | 退出 |
-| `↑` / `↓` / `j` / `k` | 上下移动光标 |
-
-搜索时会同时匹配 `name`、`command`、`args`、`tags`、`description` 等字段，匹配结果在表格中高亮显示。
-
-### 编辑用例
-
-选中用例后按 `e` 进入编辑界面。编辑界面根据用例类型有两种模式：
-
-#### 单命令模式
+不提供搜索词时列出全部用例。文本输出列为：序号、名称、命令、标签、超时、模式（`single` 单命令 / `steps` 步骤序列）。
 
-编辑表单包含以下字段：
-
-| 字段 | 说明 |
-|---|---|
-| `Name` | 用例名称（必填） |
-| `Command` | 要执行的命令 |
-| `Args` | 命令参数，每行一个 |
-| `Tags` | 标签列表，每行一个 |
-| `Description` | 用例描述 |
-| `Timeout` | 超时秒数 |
-| Expected | 期望断言的嵌套子表单（见下文） |
-
-#### 步骤序列模式
-
-当用例包含多个有序步骤时，切换到此模式。每个步骤有独立的 `Command`、`Args`、`Expected` 和 `Timeout`，支持添加、删除、编辑和上下移动步骤。
-
-两种模式可通过编辑界面内的快捷键切换，切换时会提示确认以免丢失数据。
-
-### `expected` 字段编辑
-
-`expected` 字段是一个嵌套字典，编辑器提供结构化输入：
-
-| 字段 | 输入方式 |
-|---|---|
-| `return_code` | 数字输入框 |
-| `output_contains` | 多行文本输入，一行一个匹配字符串 |
-| `output_matches` | 正则表达式文本输入 |
-| `compare_files` | 每行一个 JSON 对象，如 `{"actual":"out.txt","baseline":"base.txt","type":"text"}` |
-
-除上述已知字段外，还支持通过 `+ Add` 按钮添加自定义 key=value 对，value 为字符串或 JSON 文本。更多含义见[测试用例定义](#测试用例定义)。
-
-### 运行用例
-
-在列表中选中某条用例，按 `r` 即可实时调用框架执行引擎运行该用例。运行结束后弹出结果面板，显示：
-
-- 通过/失败状态
-- 返回码
-- 耗时
-- 命令输出（stdout/stderr）
-
-结果面板仅展示、不修改配置文件。
-
-### 保存
-
-对用例的任何增删改操作都在**内存中**进行，不会立即写入磁盘。
-
-- 按 `F6` 或 `Ctrl+S` **保存**：将当前全部用例写回原配置文件。
-- 通过 `save_as` 可**另存为**新文件（通过界面菜单操作）。
-
-退出 TUI 时如有未保存的修改，会弹出确认提示。
+退出码沿用 grep 语义：有匹配返回 `0`，无匹配返回 `1`，配置加载失败返回 `2`，可直接用于脚本判断。
 
 ## 运行测试
 
@@ -1788,12 +1696,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 +1873,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 插件代码
+
+**路径解析约定**：`actual`/`baseline` 以及插件用 `path_params` 类属性声明的路径参数，
+由框架在**比较器构造之前**统一按 workspace 解析为绝对路径——构造器捕获的状态
+（`self.script`、`self.cwd` 等）持有的已是解析后的绝对路径。插件内部
+**禁止**对 CWD 做 `Path.resolve()`——并行/process 模式下 CWD 不可靠。
 
-#### 方式一：工作区插件目录（推荐）
+#### 插件发现方式（三种泳道通用）
 
-在 workspace 下创建 `comparators/` 目录，放入 `*_comparator.py` 文件（命名与内置比较器一致），框架会在首次使用时自动发现并注册其中的 `*Comparator` 类。
+在 workspace 下创建 `comparators/` 目录，放入 `*_comparator.py` 文件，框架会在首次使用时自动发现并注册其中的 `*Comparator` 类。
 
 ```
 your-workspace/
@@ -1984,28 +1912,150 @@ your-workspace/
 symtest run test_config.json --plugin-dir ./extra_plugins
 ```
 
-插件也会通过环境变量 `CLITEST_PLUGIN_DIRS` 自动继承到 process 模式子进程。
+也可通过环境变量 `CLITEST_PLUGIN_DIRS` 声明额外插件目录（框架只读取该变量，从不修改进程环境变量）；process 模式下框架通过进程池 initializer 把插件目录显式传给子进程，无需环境变量中转。
 
-**插件开发注意事项**：
-- 继承 `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}
 }
 ```
 
-#### 方式二：内置 `script` 类型比较器
+#### 数据泳道：通道提取器插件
+
+适用场景：一个脚本/插件产出多通道数据（如 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}
+}
+```
+
+**判定与结果语义**：
+- 每通道独立跑 `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 +2078,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 +2095,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 +2113,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 +2128,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/` 目录下即可自动发现，无需改框架代码。
diff --git a/docs/user_manual_en.md b/docs/user_manual_en.md
index 9a86f88..415b55e 100644
--- a/docs/user_manual_en.md
+++ b/docs/user_manual_en.md
@@ -8,7 +8,7 @@
 - [Configuration Splitting](#configuration-splitting)
 - [Configuration Inheritance](#configuration-inheritance)
 - [Configuration Validation](#configuration-validation)
-- [TUI Interactive Manager](#tui-interactive-manager)
+- [Cross-File Case Search](#cross-file-case-search-find)
 - [Running Tests](#running-tests)
 - [Project Entry Script](#project-entry-script)
 - [Placeholders (Variable Substitution)](#placeholders-variable-substitution)
@@ -38,7 +38,7 @@ YAML support is available as an optional dependency:
 pip install "symtest-cli[yaml]"
 ```
 
-Install YAML, TUI, and all other optional features together:
+Install YAML and all other optional features together:
 
 ```bash
 pip install "symtest-cli[all]"
@@ -48,7 +48,7 @@ HDF5 file comparison depends on `h5py` (installed with the framework). If you ne
 
 ## Test Case Definition
 
-> **Schema v2 (1.4)**: The config uses a layered DSL — execution-related fields (`command`, `args`, `timeout`, `retry_count`, `env`, `steps`) live in the `execution` block, scheduling-related fields (`depends_on`, `resources`) live in the `scheduling` block, and `expected` stays at the top level. The old flat layout was removed; use `symtest migrate` to migrate.
+> **Schema v2 (1.4)**: The config uses a layered DSL — execution-related fields (`command`, `args`, `timeout`, `retry_count`, `env`, `steps`) live in the `execution` block, scheduling-related fields (`depends_on`, `resources`) live in the `scheduling` block, and `expected` stays at the top level. The old flat layout was removed; use `symtest migrate` to migrate. Migration recursively covers the whole `import` tree: by default each file gets a `<stem>.v2<ext>` copy with import paths rewritten automatically; `--in-place` overwrites all files in place (mutually exclusive with `--output`).
 
 ### JSON Format
 
@@ -275,6 +275,13 @@ test_cases:
 | `expected.output_matches` | No | Regex pattern the output must match (single string) |
 | `expected.compare_files` | No | File comparison assertions list, see below |
 
+### execution — pick one form (mutually exclusive)
+
+`execution` has two forms, **choose exactly one**; declaring both is a configuration error:
+
+- **Single-command form**: `command` + `args` (with optional `timeout` / `retry_count` / `env`)
+- **Steps form**: `steps` (a list; each step is `command + args + expected`); `command` / `args` must not be declared alongside `steps`
+
 ### File Comparison Assertions (compare_files)
 
 Declare one or more file comparison rules in `expected.compare_files`. The framework automatically uses the corresponding comparator to diff the actual output file against the baseline after command execution. The test passes only when all comparisons pass; these coexist with `return_code`, `output_contains`, and other assertions.
@@ -616,10 +623,6 @@ The `setup` block uses only global `--var` substitution (no case-level variables
 - `abstract` cases are not counted as executable
 - `extends` cases skip required-field checks (content comes from parent)
 
-### TUI Editing Limitation
-
-> **Note**: The TUI does not currently support editing inherited cases. Expanded inherited cases can be viewed and run in the TUI, but please edit the JSON/YAML source files directly to make modifications.
-
 ## Configuration Validation
 
 The `validate` command checks configuration file correctness without running tests, suitable for CI pipeline config validation.
@@ -670,127 +673,38 @@ On error:
   [FAIL] Import target not found: /project/cases/nonexistent.json
 ```
 
-## TUI Interactive Manager
-
-When a large project splits cases across many JSON/YAML sub-configurations, locating cases and reviewing scenario coverage across files becomes difficult. The TUI (Terminal User Interface) provides one view over all imported configurations for browsing, global search, and coverage review, with editing and case execution available when needed. It is an aid for large suites, not a requirement for normal test execution.
+## Cross-File Case Search (find)
 
-### Installation
+When a large project splits cases across many JSON/YAML sub-configurations,
+locating cases and reviewing scenario coverage across files becomes difficult.
+`symtest find` automatically expands all `import` references of the main
+config and searches over the unified, expanded case set — a lightweight,
+scriptable way to locate cases.
 
-The TUI depends on the `textual` library and is provided as an optional, on-demand dependency:
+### Usage
 
 ```bash
-# Install with TUI support
-pip install "symtest-cli[tui]"
-
-# Or install textual separately on top of an existing framework
-pip install textual
-```
+# Default substring mode (case-insensitive); matches name/command/args/tags/description
+symtest find main_config.json "login"
 
-If `textual` is not installed and you run `symtest tui`, the framework displays a friendly installation prompt.
+# Regex mode
+symtest find main_config.json "log.*in" --mode regex
 
-### Launching
+# Fuzzy mode (tolerates typos and abbreviations, ranked by relevance)
+symtest find main_config.json "lgin" --mode fuzzy
 
-```bash
-# Open TUI to edit test cases
-symtest tui test_cases.json
-
-# YAML files are also supported
-symtest tui test_cases.yaml
+# Combined with tag filtering (repeatable, OR relationship)
+symtest find main_config.json "login" --tag smoke
 
-# Specify working directory
-symtest tui test_cases.json --workspace /path/to/project
-
-# Open a main config with imports (auto-expands all cases from sub-files)
-symtest tui main_config.json
+# JSON output (for AI/scripts)
+symtest find main_config.json "login" --output-format json
 ```
 
-The TUI auto-expands `import` references via the [Configuration Splitting](#configuration-splitting) mechanism at startup, loading all cases into the interface for unified management.
-
-### Interface Overview
-
-The TUI shows the **Test Case List main screen** on startup:
-
-- **Top status bar**: Current filename, total case count
-- **Search bar**: Press `/` to focus the search box; supports substring/fuzzy/regex modes
-- **Case table**: Six columns (Index, Name, Command, Tags, Timeout, Mode); keyboard-navigable
-- **Bottom shortcut bar**: Shows all available actions
-
-### Keyboard Shortcuts
-
-| Shortcut | Function |
-|---|---|
-| `a` | Add a new test case |
-| `e` | Edit selected test case |
-| `d` | Delete selected test case |
-| `u` | Duplicate selected test case (name gets `_copy` suffix) |
-| `r` | Run selected test case and display results |
-| `F6` / `Ctrl+S` | Save changes to file |
-| `/` | Focus search box |
-| `Esc` | Clear search, restore full list |
-| `Alt+S` | Toggle substring search mode (case-insensitive) |
-| `Alt+F` | Toggle fuzzy search mode (tolerates typos and abbreviations) |
-| `Alt+R` | Toggle regex search mode |
-| `q` / `Ctrl+Q` | Quit |
-| `↑` / `↓` / `j` / `k` | Move cursor up/down |
-
-Search matches against `name`, `command`, `args`, `tags`, `description` and other fields simultaneously; matches are highlighted in the table.
-
-### Editing a Test Case
-
-Select a case and press `e` to enter edit mode. The edit form has two modes based on the case type:
-
-#### Single-Command Mode
+Omitting the pattern lists all cases. Text output columns: index, name,
+command, tags, timeout, mode (`single` / `steps`).
 
-The edit form includes the following fields:
-
-| Field | Description |
-|---|---|
-| `Name` | Case name (required) |
-| `Command` | Command to execute |
-| `Args` | Command arguments, one per line |
-| `Tags` | Tag list, one per line |
-| `Description` | Case description |
-| `Timeout` | Timeout in seconds |
-| Expected | Nested sub-form for expected assertions (see below) |
-
-#### Step Sequence Mode
-
-When a case contains multiple ordered steps, switch to this mode. Each step has its own `Command`, `Args`, `Expected`, and `Timeout`. Supports adding, deleting, editing, and reordering steps.
-
-Switch between modes via keyboard shortcuts within the edit interface; a confirmation prompt appears to prevent data loss.
-
-### Editing the `expected` Field
-
-The `expected` field is a nested dictionary; the editor provides structured input:
-
-| Field | Input Method |
-|---|---|
-| `return_code` | Numeric input box |
-| `output_contains` | Multi-line text input, one match string per line |
-| `output_matches` | Regex text input |
-| `compare_files` | One JSON object per line, e.g., `{"actual":"out.txt","baseline":"base.txt","type":"text"}` |
-
-Beyond the known fields above, you can add custom key=value pairs via the `+ Add` button (value is a string or JSON text). See [Test Case Definition](#test-case-definition) for more details.
-
-### Running a Test Case
-
-Select a case in the list and press `r` to invoke the framework execution engine and run it in real time. A result panel pops up showing:
-
-- Pass/fail status
-- Return code
-- Duration
-- Command output (stdout/stderr)
-
-The result panel is display-only and does not modify the config file.
-
-### Saving
-
-All add/edit/delete operations on test cases are performed **in memory** and are not immediately written to disk.
-
-- Press `F6` or `Ctrl+S` to **save**: writes all current cases back to the original config file.
-- Use `save_as` to **save as** a new file (via the interface menu).
-
-Unsaved changes prompt a confirmation dialog when quitting the TUI.
+Exit codes follow grep semantics: 0 = match found, 1 = no match,
+2 = config loading error — convenient for scripting.
 
 ## Running Tests
 
@@ -1963,11 +1877,35 @@ class MySetup(BaseSetup):
 
 ### Custom File Comparator
 
-The framework supports three ways to extend comparison capabilities:
+#### Three-Lane Architecture (v2)
+
+The comparator plugin system is organized around the root contract
+`ComparatorBase.compare(ctx) -> ComparisonResult`, split by verdict ownership
+into three lanes:
+
+| Lane | Base class | Use case | Verdict owned by |
+|---|---|---|---|
+| **File lane** | `FileComparator` | Comparing two same-kind files (built-in text/json/csv/xml/h5/binary) | Plugin |
+| **Data lane** | `ExtractorComparator` | Extracting numeric data from any upstream (files / solver output / cross-file aggregation), reusing the framework numeric core for per-channel tolerance verdicts | **Framework** |
+| **Autonomous lane** | extend `ComparatorBase` directly | Custom verdict logic (composite thresholds, label parsing, sign/asymptotic checks) | Plugin |
+
+Selection guide:
 
-#### Method 1: Workspace Plugin Directory (Recommended)
+- Data is already `(expected, actual)` numeric arrays needing only rtol/atol → **data lane** (channels, per-channel tolerances, unified error_stats and report rendering)
+- Custom verdict needed (e.g. "tight on main components, loose on EAS components", sign checks) → **autonomous lane**
+- Just want to wire an existing script in quickly → built-in `script` (custom verdict) or `script_extract` (framework tolerance verdict), zero plugin code
 
-Create a `comparators/` directory under your workspace and place `*_comparator.py` files inside (following the same naming convention as built-in comparators). The framework auto-discovers and registers the `*Comparator` classes on first use.
+**Path resolution convention**: `actual`/`baseline` and any constructor params
+declared in the plugin's `path_params` class attribute are resolved against
+the workspace by the framework **before the comparator is constructed** —
+constructor-captured state (`self.script`, `self.cwd`, ...) already holds
+absolute paths. Plugins must
+**never** resolve paths against CWD — it is unreliable under parallel/process
+execution.
+
+#### Plugin Discovery (common to all lanes)
+
+Create a `comparators/` directory under your workspace and place `*_comparator.py` files inside. The framework auto-discovers and registers the `*Comparator` classes on first use.
 
 ```
 your-workspace/
@@ -1984,26 +1922,155 @@ symtest run test_config.json --plugin-dir ./extra_plugins
 
 Plugins are also automatically inherited by process-mode child processes via the `CLITEST_PLUGIN_DIRS` environment variable.
 
-**Plugin development notes**:
-- Inherit from `symtest.file_comparator.BaseComparator`
+**Naming conventions**:
+- File name must end with `_comparator.py` (e.g., `my_analysis_comparator.py`)
 - Class name must end with `Comparator` (e.g., `MyAnalysisComparator`)
-- The registered type name = class name without `Comparator`, lowercased (e.g., `myanalysis`)
-- Prefer overriding the `compare_files(file1, file2, **kwargs)` method over `read_content`/`compare_content` (if your comparator doesn't use the two-file model)
-- Construct structured results via `from symtest.file_comparator import ComparisonResult, Difference`
-- `extra_kwargs` are auto-passed from the config `compareSpec`
-
-Use the registered type name directly in your config:
+- The registered type name = class name without `Comparator`, lowercased (e.g., `myanalysis`); a `comparator_type = "my_analysis"` class attribute overrides it
+- Abstract base classes (with unimplemented abstract methods) are skipped automatically
+
+Use the registered type name directly in your config. Comparator constructor
+parameters are **strict**: keys other than `actual`/`baseline`/`type` are
+forwarded to the plugin constructor, but a parameter the plugin does not
+declare (e.g. a typo like `pass_threhsold`) **fails loudly** at construction
+(the error names the comparator type and its supported parameters) — it never
+silently falls back to defaults. Plugin-owned configuration should go into
+the `options` namespace (entries merged into constructor kwargs; explicit
+top-level keys take precedence), keeping the core schema generic:
 
 ```json
 {
   "type": "myanalysis",
   "actual": "optional_for_plugins",
   "baseline": "optional_for_plugins",
-  "param1": "value1"
+  "options": {"param1": "value1", "param2": 42}
 }
 ```
 
-#### Method 2: Built-in `script` Type Comparator
+#### Data Lane: Channel Extractor Plugin
+
+Use case: one script/plugin produces multi-channel data (e.g. different CSV
+columns, different physical quantities), each channel needing independent
+tolerances and error analysis. The plugin only EXTRACTS; the framework
+owns the verdict entirely.
+
+```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-resolved by framework
+
+    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())},
+            ),
+        }
+```
+
+Config (per-channel tolerances routed by name; unlisted channels use `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}
+}
+```
+
+**Verdict and result semantics**:
+- Each channel runs `compare_numeric` independently (symmetric tolerance `|a-b| <= max(rtol*max(|a|,|b|), atol)`)
+- `identical = all channels pass`; one compareSpec is still one assertion
+- Difference positions carry the channel prefix (`channel S33`); `error_stats` nests by channel name
+- The report shows per-channel pass/fail, tolerances and stats; channel differences are trimmed per channel in JSON output
+- Custom error metrics ride along via `ChannelData.extra_stats`, kept in a SEPARATE namespace (`ChannelResult.extra_stats`) that can never overwrite framework canonical metrics (`max_abs_error`, `total`, ...); the report renders both namespaces per channel
+- The verdict itself cannot be altered by the plugin — custom verdicts belong to the autonomous lane
+
+#### Data Lane: Built-in `script_extract` Type (Zero-Modification Script Access)
+
+Existing analysis scripts need no Python plugin wrapper: the script runs as a
+subprocess and prints a JSON channel payload on stdout; each channel then
+enters the framework-owned tolerance pipeline described above.
+
+```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 protocol**:
+
+```json
+{
+  "channels": {
+    "S11": {"expected": [1.0, 2.0], "actual": [1.0, 2.0]},
+    "S33": {"expected": [...], "actual": [...], "extra_stats": {"asymmetry": 2e-13}}
+  }
+}
+```
+
+**Error semantics**: non-zero exit code, timeout, malformed JSON, a missing
+`channels` key, or a channel missing `expected`/`actual` arrays → always a
+comparison error (never a silent pass). `actual`/`baseline` (if configured)
+are appended as trailing script arguments with baseline first; both optional.
+
+#### Autonomous Lane: Full-Verdict Plugin
+
+Use case: custom verdict logic. The plugin implements `compare(ctx)` and
+returns the result directly.
+
+```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__()   # strict: undeclared/misspelled config keys fail loudly
+        self.script = script      # workspace-resolved by the framework before construction
+        self.case_dir = case_dir
+        self.pass_threshold = pass_threshold
+
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        result = ComparisonResult(
+            file1=ctx.baseline,   # stays None when there is no file input — no fake ""
+            file2=ctx.actual,
+        )
+        # ... run analysis, parse metrics ...
+        result.identical = True  # or False + differences
+        result.error_stats = {"full_rel": 8e-8}   # free-form dict, generic rendering
+        return result
+```
+
+`ctx` fields (invocation-level context only): `workspace` / `actual` /
+`baseline` (`None` when absent) / `params` (file-lane window ranges) /
+`error_analysis`.  The single authoritative copy of comparator configuration
+lives in constructor-captured state — `ctx` never duplicates it.
+
+#### Built-in `script` Type Comparator (Autonomous Lane Out of the Box)
 
 For quickly integrating standalone analysis scripts without writing a comparator class:
 
@@ -2026,8 +2093,8 @@ For quickly integrating standalone analysis scripts without writing a comparator
 | Parameter | Required | Default | Description |
 |---|---|---|---|
 | `script` | Yes | — | Script path (relative to workspace or absolute) |
-| `actual` | No | — | First file argument passed to the script |
-| `baseline` | No | — | Second file argument passed to the script |
+| `actual` | No | — | File argument passed to the script (trailing second slot) |
+| `baseline` | No | — | File argument passed to the script (trailing first slot) |
 | `cwd` | No | — | Script working directory |
 | `interpreter` | No | `sys.executable` | Python interpreter |
 | `pass_exit_code` | No | `0` | Exit code considered a pass |
@@ -2043,15 +2110,15 @@ For quickly integrating standalone analysis scripts without writing a comparator
 
 The script's stdout and stderr are fully captured in the `Comparator Output` section, displayed up to 20 lines in the rendered report.
 
-#### Method 3: Manual Registration (Programmatic)
+#### Manual Registration (Programmatic)
 
 ```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):
-    # Implement read_content / compare_content etc.
-    pass
+class FooComparator(ComparatorBase):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        ...
 
 ComparatorFactory.register_comparator("foo", FooComparator)
 
@@ -2061,7 +2128,7 @@ comparator = ComparatorFactory.create_comparator("foo")
 
 #### Specialized Plugin Example: Hourglass Tangent Stiffness Analysis
 
-`examples/plugins/hourglass_tangent_comparator.py` is a complete workspace plugin example demonstrating how to integrate a dedicated `analyze_*_tangent.py` analysis script into the framework:
+`examples/plugins/hourglass_tangent_comparator.py` is a complete autonomous-lane workspace plugin example demonstrating how to integrate a dedicated `analyze_*_tangent.py` analysis script into the framework:
 
 ```json
 {
@@ -2076,6 +2143,7 @@ comparator = ComparatorFactory.create_comparator("foo")
 **Features**:
 - Calls the analysis script via subprocess (**zero changes** to analyze code), parses `RESULT:` lines and numerical metrics like `full_rel`/`aa_rel`/`hh_rel`/`asymmetry` from stdout using regex
 - Constructs a structured `ComparisonResult`: `identical` determined by `full_rel < pass_threshold`; `differences` lists exceeded metrics; `error_stats` contains all numeric values
+- `path_params` declares `script`/`case_dir`, resolved against the workspace by the framework
 - Script stdout goes into the `Comparator Output` section
 
 Usage: copy the plugin file into your workspace's `comparators/` directory for auto-discovery — no framework code changes needed.
diff --git a/examples/plugins/README.md b/examples/plugins/README.md
index 065a013..961d563 100644
--- a/examples/plugins/README.md
+++ b/examples/plugins/README.md
@@ -4,28 +4,38 @@
 
 CLI Test Framework 支持通过**工作区插件目录**扩展比较器能力。将 `*_comparator.py` 文件放入 workspace 的 `comparators/` 目录，框架会在首次运行时自动发现并注册。
 
+比较器插件体系（v2）围绕根契约 `ComparatorBase.compare(ctx) -> ComparisonResult` 组织，
+按判定权归属分为**三条泳道**：
+
+| 泳道 | 基类 | 适用场景 | verdict 归属 |
+|---|---|---|---|
+| 文件泳道 | `FileComparator` | 比较两个同类文件（text/json/csv/xml/h5/binary 内置即此类） | 插件 |
+| 数据泳道 | `ExtractorComparator` | 提取数值数据（可多通道），框架按 per-channel 容差判定 | **框架** |
+| 自主泳道 | 直接继承 `ComparatorBase` | 独特判定逻辑（阈值组合、标签解析、渐近分析等） | 插件 |
+
 ## 快速开始
 
 1. 在 workspace 下创建 `comparators/` 目录。
-2. 新建 `your_comparator.py`，实现一个以 `*Comparator` 结尾的类，继承 `BaseComparator`。
+2. 新建 `your_comparator.py`，按泳道选择基类，实现一个以 `*Comparator` 结尾的类。
 3. 在用例配置的 `compare_files` 中使用你的类型名。
 
-### 最简示例
+### 最简示例（自主泳道）
 
 **comparators/hello_comparator.py**:
 
 ```python
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator.result import ComparisonResult, Difference
+from symtest.file_comparator.base_comparator import BaseComparator, CompareContext
+from symtest.file_comparator.result import ComparisonResult
 
 class HelloComparator(BaseComparator):
     """最简自定义比较器：永远通过。"""
 
-    def read_content(self, file_path, **kwargs):
-        return None
-
-    def compare_content(self, content1, content2):
-        return True, [], False
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        result = ComparisonResult(
+            file1=str(ctx.baseline or ""), file2=str(ctx.actual or "")
+        )
+        result.identical = True
+        return result
 ```
 
 **配置使用**:
@@ -38,32 +48,76 @@ class HelloComparator(BaseComparator):
 }
 ```
 
-注册的 type 名 = 类名去掉 `Comparator` 再小写（此处 `HelloComparator` → `hello`）。
+注册的 type 名 = 类名去掉 `Comparator` 再小写（此处 `HelloComparator` → `hello`）；
+也可用类属性 `comparator_type` 显式指定。
+
+> v2 breaking 说明：根基类不再有 `read_content`/`compare_content` 抽象方法，
+> 也不要再覆写 `compare_files`——唯一契约是 `compare(ctx)`。
 
 ## 开发规范
 
-### 基类接口
+### 根契约与上下文
 
-`BaseComparator` 提供三个核心方法：
+`ComparatorBase` 的唯一抽象方法是 `compare(ctx)`。`CompareContext` 字段：
 
-| 方法 | 说明 |
+| 字段 | 说明 |
 |---|---|
-| `read_content(file_path, ...)` | 读取文件内容，返回适合比较的数据结构 |
-| `compare_content(content1, content2)` | 比较两个内容对象，返回 `(identical, differences, truncated)` |
-| `compare_files(file1, file2, **kwargs)` | 高层入口，编排读取→比较→构造结果 |
+| `workspace` | workspace 根目录 |
+| `actual` / `baseline` | 命令输出 / 基准文件路径（无文件输入时为 `None`，构造前已按 workspace 解析） |
+| `params` | 调用级参数（文件泳道窗口范围）；**不携带比较器配置副本** |
+| `error_analysis` | 是否启用误差统计（`--error-analysis`） |
+
+**路径解析**：`actual`/`baseline` 以及插件 `path_params` 类属性声明的路径参数
+由框架在**构造之前**按 workspace 解析——构造器捕获的状态已是绝对路径。
+插件内部**禁止**对 CWD 做 `Path.resolve()`。
 
-对于不使用"两个文件对比"模型的比较器（如分析脚本），推荐**重写 `compare_files` 方法**，绕过文件 I/O：
+**严格配置**：构造器参数显式声明；未声明/拼错的配置键在构造时大声失败
+（错误含比较器类型名与支持参数清单）。自由参数仅限插件显式 `**params` opt-in。
+插件自有配置建议放 `options` compareSpec 键（并入构造参数，顶层键优先）。
+
+### 数据泳道：通道提取器
+
+只需实现 `extract(ctx)`，返回 `{channel_name: ChannelData}`，判定全部由框架完成：
 
 ```python
-def compare_files(self, file1=None, file2=None, **kwargs):
-    result = ComparisonResult(file1=file1 or "", file2=file2 or "")
-    # 你的专用逻辑...
-    result.identical = True
-    result.command_output = capture_stdout  # 可选
-    return result
+import numpy as np
+from symtest.file_comparator import ExtractorComparator, ChannelData, CompareContext
+
+class MyExtractor(ExtractorComparator):
+    path_params = ("ref_csv", "actual_csv")
+
+    def __init__(self, ref_csv="", actual_csv=""):
+        super().__init__()
+        self.ref_csv, self.actual_csv = ref_csv, actual_csv
+
+    def extract(self, ctx):
+        ref = np.loadtxt(self.ref_csv, delimiter=",")
+        act = np.loadtxt(self.actual_csv, delimiter=",")
+        return {
+            "S11": ChannelData(expected=ref[:, 0], actual=act[:, 0]),
+            "S33": ChannelData(
+                expected=ref[:, 2], actual=act[:, 2],
+                extra_stats={"note": "自定义误差指标并入 stats"},
+            ),
+        }
+```
+
+配置（per-channel 容差按名路由，未声明通道用 `default_channel`）：
+
+```json
+{
+    "type": "myextractor",
+    "ref_csv": "out/ref.csv",
+    "actual_csv": "out/act.csv",
+    "channels": {"S33": {"atol": 600.0, "data_filter": "abs>1e-12"}},
+    "default_channel": {"rtol": 1e-5, "atol": 1e-8}
+}
 ```
 
-### 结果构造
+结果语义：`identical = 所有通道全过`；差异 position 带通道前缀；
+`error_stats` 按通道名嵌套；报告逐通道展示 pass/fail。
+
+### 结果构造（自主泳道）
 
 使用 `ComparisonResult` 和 `Difference` 构造结构化结果：
 
@@ -84,15 +138,18 @@ result.command_output = "stdout from subprocess"  # 在报告中渲染
 return result
 ```
 
-### 配置参数透传
+### 配置参数（严格校验）
 
-配置 `compareSpec` 中 `actual`/`baseline`/`type`/`start_line`/`end_line`/`start_column`/`end_column` 之外的所有字段都会作为 `**kwargs` 透传给你的比较器构造函数：
+配置 `compareSpec` 中 `actual`/`baseline`/`type` 之外的键会作为
+`**kwargs` 传给你的比较器构造函数，但**参数是严格的**：构造器未声明的键
+（如拼写错误 `pass_threhsold`）会抛出带类型名与支持参数清单的
+`TypeError`，绝不静默回退到默认值。插件自有配置推荐放 `options`
+命名空间（并入构造参数，显式顶层键优先）：
 
 ```json
 {
     "type": "myanalysis",
-    "param1": "value1",
-    "param2": 42
+    "options": {"param1": "value1", "param2": 42}
 }
 ```
 
@@ -100,38 +157,32 @@ return result
 
 ```python
 class MyAnalysisComparator(BaseComparator):
-    def __init__(self, param1="", param2=0, encoding="utf-8", **kwargs):
-        super().__init__(encoding=encoding, **kwargs)
+    def __init__(self, param1="", param2=0):
+        super().__init__()   # 根类不再接收/忽略任意 kwargs
         self.param1 = param1
         self.param2 = param2
 ```
 
-## 内置 `script` 类型
-
-如果不想写 Python 类，可以用内置的 `script` 类型快速接入外部脚本。
+## 零改动脚本接入
 
-配置示例：
+不想写 Python 类时的两种内置方式：
 
-```json
-{
-    "type": "script",
-    "script": "analyze_xxx.py",
-    "actual": "output.txt",
-    "baseline": "baseline.txt",
-    "pass_pattern": "RESULT: PASS",
-    "timeout": 600
-}
-```
+| 类型 | 判定归属 | 协议 |
+|---|---|---|
+| `script` | 脚本（exit code + pass/fail pattern） | 子进程执行，exit 0 → 通过 |
+| `script_extract` | 框架（per-channel 容差） | 子进程执行，stdout 打印 JSON：`{"channels": {name: {"expected": [...], "actual": [...]}}}` |
 
-完整参数见 `docs/user_manual.md` 自定义文件比较器章节。
+`script_extract` 的错误语义：非零退出码、超时、畸形 JSON 一律判为比较 error
+（绝不静默通过）。完整协议见 `docs/user_manual.md` 自定义文件比较器章节。
 
 ## hourglass_tangent 示例
 
-`hourglass_tangent_comparator.py` 是一个完整的专用比较器范例，展示了：
+`hourglass_tangent_comparator.py` 是一个完整的自主泳道范例，展示了：
 
 - subprocess 调用外部分析脚本（零改动）
 - 正则解析 stdout 提取结构化数值
 - 构造 diffs + error_stats + command_output 的完整结果
+- `path_params` 声明路径参数由框架解析
 
 使用方法：
 
diff --git a/examples/plugins/hourglass_tangent_comparator.py b/examples/plugins/hourglass_tangent_comparator.py
index af3e486..8005b84 100644
--- a/examples/plugins/hourglass_tangent_comparator.py
+++ b/examples/plugins/hourglass_tangent_comparator.py
@@ -1,15 +1,24 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-专用 hourglass 切线刚度比较器（workspace 插件范例）。
+专用 hourglass 切线刚度比较器（workspace 插件范例，自主泳道）。
 
 通过 subprocess 调用 ``analyze_*_tangent.py`` 分析脚本，捕获其 stdout，
 用正则解析 RESULT 判定 + 数值指标（full_rel / aa_rel / hh_rel 等），
 构造框架标准的 ComparisonResult，享受 diffs / error_stats / 报告渲染全套设施。
 
+**泳道定位**：本插件拥有自己的判定逻辑（阈值 + RESULT 标签），属于
+**自主泳道**（直接继承 ``ComparatorBase``，实现 ``compare(ctx)``）。
+若只需要框架标准容差判定（rtol/atol），请改用数据泳道（继承
+``ExtractorComparator``）或内置 ``script_extract`` 类型。
+
 **零改动 analyze 脚本**：subprocess 调用时 ``sys.argv[0]`` 天然指向脚本路径，
 ``run_hg_analysis`` 内部的 case_dir 推断正确。
 
+**路径解析**：``path_params`` 声明 ``script`` / ``case_dir`` 为路径参数，
+框架在调用 ``compare()`` 前统一按 workspace 解析相对路径——插件内部
+不得自行对 CWD 做 ``Path.resolve()``。
+
 使用方式：
     1. 将本文件复制到你的 workspace 的 ``comparators/`` 目录下。
     2. 在配置中写：
@@ -22,7 +31,7 @@
          "timeout": 600
        }
 
-    3. script 路径相对于 workspace 解析；case_dir 为 subprocess 的工作目录。
+    3. script / case_dir 路径相对于 workspace 解析（框架负责）。
 
 判定逻辑：
     - 退出码 2 → error (文件缺失/解析失败)
@@ -33,21 +42,20 @@
 
 from __future__ import annotations
 
-import os
 import re
 import subprocess
 import sys
-from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 # When loaded as a workspace plugin, the framework package is importable
 # because the worker process inherits the same Python environment.
 # Use a guarded import for documentation/testing outside a full runtime.
 try:
-    from symtest.file_comparator.base_comparator import BaseComparator
+    from symtest.file_comparator.base_comparator import ComparatorBase, CompareContext
     from symtest.file_comparator.result import ComparisonResult, Difference
 except ImportError:  # pragma: no cover
-    BaseComparator = object  # type: ignore
+    ComparatorBase = object  # type: ignore
+    CompareContext = None  # type: ignore
     ComparisonResult = None  # type: ignore
     Difference = None  # type: ignore
 
@@ -127,22 +135,26 @@ def _parse_stdout(stdout: str) -> Dict[str, Any]:
     return data
 
 
-class HourglassTangentComparator(BaseComparator):  # type: ignore
+class HourglassTangentComparator(ComparatorBase):  # type: ignore
     """Work against an ``analyze_*_tangent.py`` script and report structured results.
 
-    Constructor parameters (forwarded from the config ``compareSpec``):
+    Autonomous-lane plugin: implements ``compare(ctx)`` directly and owns its
+    verdict.  Constructor parameters are forwarded from the config
+    ``compareSpec``; ``script`` / ``case_dir`` are workspace-resolved by the
+    framework (declared in ``path_params``).
 
     :param script:       Path to the ``analyze_*_tangent.py`` script (required).
     :param case_dir:     Working directory for the subprocess (script resolves
                          its own ``case_dir`` from ``sys.argv[0]``, but the
                          process cwd must contain the case files).
     :param pass_threshold: If ``full_rel < pass_threshold``, treat as PASS
-                           (default ``1e-6``).
+                         (default ``1e-6``).
     :param interpreter:  Python interpreter (default ``sys.executable``).
     :param timeout:      Subprocess timeout in seconds (default 600).
-    :param encoding:     File encoding (unused, kept for interface consistency).
     """
 
+    path_params = ("script", "case_dir")
+
     def __init__(
         self,
         script: str = "",
@@ -150,45 +162,25 @@ def __init__(
         pass_threshold: float = 1e-6,
         interpreter: Optional[str] = None,
         timeout: int = 600,
-        encoding: str = "utf-8",
-        **kwargs,
     ):
-        super().__init__(encoding=encoding, **kwargs)
-        self.script = script
-        self.case_dir = case_dir
+        super().__init__()
+        self.script = script      # workspace-resolved by the framework (path_params)
+        self.case_dir = case_dir  # workspace-resolved by the framework (path_params)
         self.pass_threshold = pass_threshold
         self.interpreter = interpreter or sys.executable
         self.timeout = timeout
 
-    # ------------------------------------------------------------------
-    # Abstract method stubs (not used)
-    # ------------------------------------------------------------------
-    def read_content(self, file_path, **kwargs):
-        return None
-
-    def compare_content(self, content1, content2):
-        return True, [], False
-
     # ------------------------------------------------------------------
     # Core comparison
     # ------------------------------------------------------------------
-    def compare_files(  # type: ignore[override]
-        self,
-        file1=None,
-        file2=None,
-        **kwargs,
-    ):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:  # type: ignore[override]
         """Execute the hourglass analysis script and parse results."""
         result = ComparisonResult(
-            file1=file1 or "",
-            file2=file2 or "",
+            file1=ctx.baseline,
+            file2=ctx.actual,
         )
 
         try:
-            cwd = self.case_dir
-            if cwd and not Path(cwd).is_absolute():
-                cwd = str(Path(cwd).resolve())
-
             cmd = [self.interpreter, self.script]
 
             self.logger.info("Executing hourglass analysis: %s", " ".join(cmd))
@@ -197,7 +189,7 @@ def compare_files(  # type: ignore[override]
                 capture_output=True,
                 text=True,
                 timeout=self.timeout,
-                cwd=cwd,
+                cwd=self.case_dir,
             )
 
             stdout = proc.stdout or ""
diff --git a/examples/skill-migration/SKILL.md b/examples/skill-migration/SKILL.md
index a945a25..6d80bc1 100644
--- a/examples/skill-migration/SKILL.md
+++ b/examples/skill-migration/SKILL.md
@@ -42,8 +42,15 @@ old config → symtest migrate → new schema → symtest validate → manual re
    symtest migrate old.json --output new.json
    ```
    Default output is `<stem>.v2<ext>` (e.g. `old.json` → `old.v2.json`).
-   `migrate` is a mechanical field move; it does not expand imports, resolve
-   paths, or validate required fields.
+   `migrate` recursively follows the whole `import` tree as a mechanical
+   field move; it never expands (inlines) imports, resolves paths, or
+   validates required fields:
+   - Default: every file in the tree gets a `<stem>.v2<ext>` copy and import
+     paths in migrated parents are rewritten to the `.v2` names, so the
+     migrated tree is self-consistent for `symtest validate`.
+   - `--in-place`: every file in the tree is overwritten in place (file
+     names, formats and import paths unchanged; mutually exclusive with
+     `--output`).
 
 2. **Validate the result**:
    ```bash
@@ -77,8 +84,10 @@ old config → symtest migrate → new schema → symtest validate → manual re
 - Idempotent: input already containing `execution` is passed through
   unchanged (deep copy).
 - JSON/YAML in → same format out (chosen by output file extension).
-- Import entries are preserved as-is (not expanded) so the migrated project
-  keeps its file split; each imported file must be migrated separately.
+- Imports are followed recursively (never expanded inline) so the migrated
+  project keeps its file split: default mode writes `<stem>.v2<ext>` copies
+  with import paths rewritten; `--in-place` overwrites every file in place
+  (originals are not kept).
 - Unknown top-level fields are preserved verbatim — `symtest validate` and
   this skill's checklist decide whether they are still meaningful.
 
diff --git a/examples/skill-migration/references/migration_checklist.md b/examples/skill-migration/references/migration_checklist.md
index 85c43a1..589c38f 100644
--- a/examples/skill-migration/references/migration_checklist.md
+++ b/examples/skill-migration/references/migration_checklist.md
@@ -69,8 +69,10 @@ will run before their dependencies).
 
 ## 6. Import structures
 
-- `migrate` does NOT follow imports: every imported sub-file must be migrated
-  on its own. List all files reachable via `import` and migrate each.
+- `migrate` follows imports recursively: default mode writes `<stem>.v2<ext>`
+  copies and rewrites import paths; `--in-place` overwrites each file in
+  place. Verify every file reachable via `import` was migrated (the command
+  prints one output path per migrated file).
 - Import-level `tags` injection still works in v2; confirm split files no
   longer rely on v1-only top-level case fields.
 - Circular imports remain an error (validation stage), unchanged.
diff --git a/examples/skill/assets/templates/my_analysis_comparator.py b/examples/skill/assets/templates/my_analysis_comparator.py
deleted file mode 100644
index e962095..0000000
--- a/examples/skill/assets/templates/my_analysis_comparator.py
+++ /dev/null
@@ -1,71 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-@file my_analysis_comparator.py
-@brief Minimal, runnable workspace plugin template for symtest-cli
-@details Copy this file into <workspace>/comparators/ and adapt the logic.
-         It is auto-discovered and registered as type "myanalysis" (class
-         name minus the "Comparator" suffix, lowercased).
-"""
-
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator import ComparisonResult
-from symtest.file_comparator.result import Difference
-
-
-class MyAnalysisComparator(BaseComparator):
-    """
-    @brief Analysis-style comparator that does not use the two-file model.
-    @details Overrides compare_files() directly. The framework constructs it
-             with verbose / error_analysis plus every extra kwarg from the
-             config compareSpec, so __init__ must forward **kwargs to super.
-    """
-
-    def __init__(self, pass_threshold=1e-6, **kwargs):
-        # IMPORTANT: forward **kwargs so the framework's verbose=,
-        # error_analysis= and config extra params never break construction.
-        super().__init__(**kwargs)
-        self.pass_threshold = pass_threshold
-
-    # BaseComparator declares read_content / compare_content as abstract
-    # methods, so they must be implemented even if compare_files overrides
-    # everything (otherwise the class cannot be instantiated).
-    def read_content(self, file_path, start_line=0, end_line=None,
-                     start_column=0, end_column=None):
-        raise NotImplementedError(
-            "MyAnalysisComparator uses compare_files directly; "
-            "read_content/compare_content are not used."
-        )
-
-    def compare_content(self, content1, content2):
-        raise NotImplementedError(
-            "MyAnalysisComparator uses compare_files directly; "
-            "read_content/compare_content are not used."
-        )
-
-    def compare_files(self, file1, file2, **kwargs):
-        """
-        @param file1 str: baseline file path (as in assertions.py)
-        @param file2 str: actual output file path
-        @return ComparisonResult: structured result consumed by the report.
-        """
-        result = ComparisonResult(file1=str(file1), file2=str(file2))
-
-        # TODO: replace with real analysis logic (read file1/file2, run
-        # subprocess, compute metrics, etc.).
-        metrics = {"max_error": 0.0}
-        max_error = metrics["max_error"]
-        identical = max_error < self.pass_threshold
-
-        result.identical = identical
-        result.differences = [
-            Difference(
-                position="max_error",
-                expected=f"<{self.pass_threshold}",
-                actual=str(max_error),
-                diff_type="content",
-            )
-        ] if not identical else []
-        result.error_stats = metrics  # optional, shown in report
-        result.command_output = None  # optional: subprocess stdout -> report
-        return result
diff --git a/examples/skill/references/user_manual.md b/examples/skill/references/user_manual.md
deleted file mode 100644
index 429bd8c..0000000
--- a/examples/skill/references/user_manual.md
+++ /dev/null
@@ -1,2154 +0,0 @@
-# CLI Test Framework 使用说明书
-
-## 目录
-
-- [安装](#安装)
-- [测试用例定义](#测试用例定义)
-- [Case 级环境变量](#case-级环境变量env)
-- [配置拆分机制](#配置拆分机制)
-- [配置继承](#配置继承)
-- [配置校验](#配置校验)
-- [TUI 交互式管理器](#tui-交互式管理器)
-- [运行测试](#运行测试)
-- [项目入口脚本](#项目入口脚本)
-- [占位符（变量替换）](#占位符变量替换)
-- [标签过滤](#标签过滤)
-- [Setup 模块](#setup-模块)
-- [并行测试](#并行测试)
-- [顺序步骤测试](#顺序步骤测试)
-- [资源感知调度](#资源感知调度)
-- [历史记录与回归检测](#历史记录与回归检测)
-- [JUnit XML 报告](#junit-xml-报告)
-- [日志配置](#日志配置)
-- [文件比较](#文件比较)
-- [扩展开发](#扩展开发)
-- [运行框架自带测试](#运行框架自带测试)
-
-## 安装
-
-```bash
-pip install symtest-cli
-```
-
-要求：Python >= 3.9
-
-YAML 支持需安装可选依赖：
-
-```bash
-pip install "symtest-cli[yaml]"
-```
-
-一次安装 YAML 和 TUI 等全部可选功能：
-
-```bash
-pip install "symtest-cli[all]"
-```
-
-HDF5 文件比较依赖 `h5py`（已随框架安装）。如需在无 HDF5 环境下使用其他比较功能，可单独卸载，但 HDF5 比较将不可用。
-
-## 测试用例定义
-
-> **Schema v2（1.4）**：配置采用分层 DSL——执行相关字段（`command`、`args`、`timeout`、`retry_count`、`env`、`steps`）位于 `execution` 块，调度相关字段（`depends_on`、`resources`）位于 `scheduling` 块，`expected` 保持在顶层。旧的扁平布局已移除，可使用 `symtest migrate` 迁移。
-
-### JSON 格式
-
-```json
-{
-    "test_cases": [
-        {
-            "name": "测试名称",
-            "execution": {
-                "command": "echo",
-                "args": ["Hello"],
-                "timeout": 60,
-                "retry_count": 0
-            },
-            "scheduling": {
-                "resources": {
-                    "cpu_cores": 2,
-                    "estimated_time": 300,
-                    "min_memory_mb": 1024,
-                    "priority": 5
-                }
-            },
-            "expected": {
-                "return_code": 0,
-                "output_contains": ["Hello"],
-                "output_matches": ".*regex.*",
-                "compare_files": [
-                    {
-                        "actual": "output.txt",
-                        "baseline": "baseline.txt",
-                        "type": "text"
-                    }
-                ]
-            }
-        },
-        {
-            "name": "已知失败的测试",
-            "execution": {
-                "command": "echo",
-                "args": ["should_fail"]
-            },
-            "expected_failure": true,
-            "xfail_reason": "Bug #42 尚未修复",
-            "expected": { "return_code": 1 }
-        }
-    ]
-}
-```
-
-### YAML 格式
-
-```yaml
-test_cases:
-  - name: 测试名称
-    execution:
-      command: echo
-      args: ["Hello"]
-      timeout: 60
-      retry_count: 0
-    scheduling:
-      resources:
-        cpu_cores: 2
-        estimated_time: 300
-        min_memory_mb: 1024
-        priority: 5
-    expected:
-      return_code: 0
-      output_contains:
-        - "Hello"
-      output_matches: ".*regex.*"
-      compare_files:
-        - actual: output.txt
-          baseline: baseline.txt
-          type: text
-
-  - name: 已知失败的测试
-    execution:
-      command: echo
-      args: ["should_fail"]
-    expected_failure: true
-    xfail_reason: "Bug #42 尚未修复"
-    xfail_quiet: true
-    expected:
-      return_code: 1
-```
-
-### 预期失败（xfail）
-
-当存在已知缺陷导致某用例无法通过时，可标记 `expected_failure: true`，框架会区分"预期中的失败"与"意外的通过"：
-
-| 场景 | 状态 | 退出码影响 | 说明 |
-|---|---|---|---|
-| xfail 标记 + 确实失败 | `xfailed` | 不计数为失败 | 报告展示 `xfail_reason`，详情照常输出（可通过 `xfail_quiet` 抑制 Command Output） |
-| xfail 标记 + 意外通过 | `xpassed` | **计入失败** | 报告高亮提示"移除 xfail 标记" |
-
-这与 pytest 的 xfail 语义一致。搭配 `--last-failed` 时，xfailed 不会进入重跑集，xpassed 会进入。
-
-```json
-{
-    "name": "已知Bug",
-    "execution": {
-        "command": "solver",
-        "args": ["--input", "bug_case.dat"]
-    },
-    "expected_failure": true,
-    "xfail_reason": "Bug #42: 边界条件处理错误，预计 v2.1 修复",
-    "expected": { "return_code": 1 }
-}
-```
-
-当 xfailed 用例的输出非常冗长（如数百行求解器日志）且重复出现，干扰报告阅读时，可添加 `xfail_quiet: true` 让报告 **只保留原因和命令，不输出 Command Output**。其余元信息（Description、Expected、Command、Return Code、Error Message、Compare Failures、Step Results 等）照常展示：
-
-```json
-{
-    "name": "已知Bug（静默模式）",
-    "execution": {
-        "command": "solver",
-        "args": ["--input", "bug_case.dat"]
-    },
-    "expected_failure": true,
-    "xfail_reason": "Bug #42: 边界条件处理错误，预计 v2.1 修复",
-    "xfail_quiet": true,
-    "expected": { "return_code": 1 }
-}
-```
-
-### 测试依赖（depends_on）
-
-当测试用例之间存在先后依赖时（例如 D 需要 A、B、C 先生成数据），通过 `depends_on` 声明依赖关系，框架会自动按 DAG 拓扑顺序调度：
-
-**并行模式**：A、B、C 并行执行，全部通过后 D 才被提交。依赖失败的用例会自动 skip 其下游（级联 skip）。
-
-**顺序模式**：框架按拓扑序重排用例，保证依赖在前的先执行，依赖失败时同样跳过下游。
-
-**JSON 示例**：
-
-```json
-{
-    "test_cases": [
-        { "name": "A", "execution": { "command": "python", "args": ["gen_a.py"] }, "expected": {"return_code": 0} },
-        { "name": "B", "execution": { "command": "python", "args": ["gen_b.py"] }, "expected": {"return_code": 0} },
-        { "name": "C", "execution": { "command": "python", "args": ["gen_c.py"] }, "expected": {"return_code": 0} },
-        {
-            "name": "D",
-            "execution": { "command": "python", "args": ["merge.py"] },
-            "scheduling": { "depends_on": ["A", "B", "C"] },
-            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
-        }
-    ]
-}
-```
-
-**YAML 示例**：
-
-```yaml
-test_cases:
-  - name: A
-    execution:
-      command: python
-      args: ["gen_a.py"]
-    expected: { return_code: 0 }
-
-  - name: B
-    execution:
-      command: python
-      args: ["gen_b.py"]
-    expected: { return_code: 0 }
-
-  - name: C
-    execution:
-      command: python
-      args: ["gen_c.py"]
-    expected: { return_code: 0 }
-
-  - name: D
-    execution:
-      command: python
-      args: ["merge.py"]
-    scheduling:
-      depends_on: [A, B, C]
-    expected:
-      return_code: 0
-      compare_files:
-        - file: output.h5
-          type: hdf5
-```
-
-**调度语义**：
-
-| 依赖状态 | 下游行为 |
-|---|---|
-| `passed` 或 `xfailed` | 依赖"满足"，下游正常执行 |
-| `failed` 或 `xpassed` | 依赖"不满足"，下游标记为 `skipped`，并级联 skip |
-| 存在循环依赖 | 配置校验阶段报错，禁止运行 |
-
-`skipped` 不计入 `failed` 计数，在报告摘要中单独显示 `Skipped: N`。
-
-**约束**：
-- 依赖名称必须在同配置文件的 `test_cases` 中存在
-- 不允许自依赖（`depends_on: ["self"]`）
-- 不允许循环依赖（A → B → A）
-- 与 `steps` 模式互不影响——`depends_on` 是用例级概念，`steps` 是用例内步骤级概念
-- 无依赖时走 fast path，调度开销为零
-
-### 字段说明
-
-| 字段 | 必填 | 说明 |
-|---|---|---|
-| `name` | 是 | 测试用例名称 |
-| `execution.command` | 是 | 要执行的命令（支持带参数的命令字符串，如 `python ./run.py`，框架会自动拆分并解析路径） |
-| `execution.args` | 否 | 命令参数列表 |
-| `description` | 否 | 测试用例描述 |
-| `execution.timeout` | 否 | 超时秒数，默认 3600，设 `null` 无限制 |
-| `execution.retry_count` | 否 | 失败自动重试次数，默认 0（不重试）。单命令模式作用于整个 case，步骤模式可作用于每个 step。重试后通过会在结果中标记 `flaky: true` |
-| `tags` | 否 | 标签列表，用于批量过滤（如 `["smoke", "fast"]`） |
-| `scheduling.resources` | 否 | 资源配置，见[资源感知调度](#资源感知调度) |
-| `expected_failure` | 否 | 标记为预期失败（xfail）。设为 `true` 时，失败计为 XFailed（不影响退出码），意外通过计为 XPassed（视作失败） |
-| `xfail_reason` | 否 | xfail 的原因说明，报告中将展示此文本（如 "Bug #42 尚未修复"） |
-| `xfail_quiet` | 否 | 设为 `true` 时，xfailed 状态下报告中不输出 Command Output（stdout/stderr 大段输出），仅保留命令、返回码、失败原因等元信息 |
-| `scheduling.depends_on` | 否 | 依赖的测试用例名称列表（如 `["A", "B"]`）。当前用例必须等待所有依赖用例通过后才执行。依赖失败时自动 skip 当前用例及下游。支持并行和顺序两种 runner |
-| `execution.env` | 否 | case 级环境变量字典（如 `{"MYAPP_SCALE": "1.0"}`），定义在 `execution` 内，仅在执行该 case（序列模式为所有 step）时注入子进程，见 [Case 级环境变量](#case-级环境变量env) |
-| `expected.return_code` | 否 | 期望返回码 |
-| `expected.output_contains` | 否 | 输出需包含的字符串列表 |
-| `expected.output_matches` | 否 | 输出需匹配的正则表达式（单个字符串） |
-| `expected.compare_files` | 否 | 文件比较断言列表，见下文 |
-
-## Case 级环境变量（env）
-
-通过 `execution` 内与 `command`、`steps` 同级的 `env` 字段，可为单个用例注入环境变量，仅在该用例（序列模式为所有 step）的子进程内生效，不影响其他用例。
-
-### JSON
-
-```json
-{
-    "name": "case 级环境变量示例",
-    "execution": {
-        "command": "solver",
-        "args": ["-i", "input.dat"],
-        "env": {
-            "MYAPP_SCALE": "1.0",
-            "OMP_NUM_THREADS": "8"
-        }
-    },
-    "expected": { "return_code": 0 }
-}
-```
-
-### YAML
-
-```yaml
-- name: case 级环境变量示例
-  execution:
-    command: solver
-    args: ["-i", "input.dat"]
-    env:
-      MYAPP_SCALE: "1.0"
-  expected: { return_code: 0 }
-```
-
-### 序列模式
-
-`env` 定义在 `execution` 内（与 `steps` 同级），对该 case 的**所有 step** 生效：
-
-```json
-{
-    "name": "多步骤+环境变量",
-    "execution": {
-        "env": { "MYAPP_SCALE": "1.0" },
-        "steps": [
-            { "command": "python", "args": ["./step1.py"], "expected": { "return_code": 0 } },
-            { "command": "python", "args": ["./step2.py"], "expected": { "return_code": 0 } }
-        ]
-    }
-}
-```
-
-### 语义
-
-| 决策点 | 行为 |
-|---|---|
-| 生效方式 | 通过子进程 `env` 注入，不修改进程全局 `os.environ`，天然进程隔离、线程安全 |
-| 优先级 | `os.environ`（含 `setup.environment_variables`）< 调度器注入（`OMP/MKL/NPROC`）< **case `env`（最高）**，即 case env 可覆盖调度器的 `OMP_NUM_THREADS` |
-| 作用范围 | 仅当前 case，不污染其他 case（区别于全局 `setup.environment_variables`） |
-| 占位符 | 自动支持，`"env": {"SCALE": "{scale}"}` 会被 `variables`/`--var` 替换 |
-| 继承（extends） | 自动支持，`env` 为 dict，深合并、子类覆盖父类同名 key |
-| 值类型 | 字符串；数字/布尔在解析时自动 `str()` 化 |
-
-### 文件比较断言（compare_files）
-
-在 `expected` 中通过 `compare_files` 可声明一条或多条文件比较规则，框架会在命令执行后自动用对应的比较器对比实际产出文件与基线文件。所有比较通过才算用例通过，可与 `return_code`、`output_contains` 等断言共存。
-
-每个比较规则的字段：
-
-| 字段 | 必填 | 说明 |
-|---|---|---|
-| `actual` | 是 | 测试命令产出的文件路径（相对路径按 workspace 解析） |
-| `baseline` | 是 | 基线/参考文件路径（相对路径按 workspace 解析） |
-| `type` | 否 | 比较器类型：`text`、`json`、`csv`、`xml`、`h5`、`binary`；省略时按扩展名自动识别 |
-| `start_line` | 否 | 起始行号（1-based），仅比较该行及之后的内容 |
-| `end_line` | 否 | 结束行号（1-based），比较到该行为止 |
-| `start_column` | 否 | 起始列号（1-based），仅比较该列及之后的内容 |
-| `end_column` | 否 | 结束列号（1-based），比较到该列为止 |
-| 其他 | 否 | 透传给对应比较器的参数，如 `rtol`、`atol`、`encoding`、`tables`、`data_filter` 等 |
-
-```json
-"expected": {
-    "return_code": 0,
-    "compare_files": [
-        {
-            "actual": "result.h5",
-            "baseline": "baseline/result.h5",
-            "type": "h5",
-            "rtol": 1e-5,
-            "atol": 1e-8,
-            "tables": ["/stress", "/displacement"]
-        },
-        {
-            "actual": "summary.csv",
-            "baseline": "baseline/summary.csv"
-        }
-    ]
-}
-```
-
-## 配置拆分机制
-
-当测试项目规模增长、用例数量达到数十甚至数百条时，单个配置文件可能变得难以维护。配置拆分机制允许将大文件按模块/功能拆分为多个子文件，通过 `import` 引用组装，运行时自动合并加载。
-
-### 主配置文件
-
-在主配置文件中，通过 `"import"` 字段引用子文件。`import` 是 `test_cases` 数组中的一个特殊元素，框架会在加载时将其**展开替换**为子文件的测试用例：
-
-```json
-{
-    "setup": {
-        "environment_variables": {
-            "PYTHONPATH": "./src"
-        }
-    },
-    "test_cases": [
-        {
-            "name": "内联测试用例",
-            "execution": {
-                "command": "echo",
-                "args": ["hello"]
-            },
-            "expected": { "return_code": 0 }
-        },
-        { "import": "cases/text_tests.json", "tags": ["text"] },
-        { "import": "cases/json_tests.yaml" },
-        { "import": "cases/h5_tests.json", "tags": ["h5", "fast"] }
-    ]
-}
-```
-
-> **注意**：`import` 路径相对**主配置文件所在目录**解析，不相对当前工作目录（cwd）。这保证了配置文件的可移植性——无论从哪个目录运行测试，拆分关系都不受影响。
-
-### 子文件格式
-
-子文件结构与主文件一致，顶层同样是 `test_cases` 数组（可包含 `setup`）：
-
-```json
-{
-    "test_cases": [
-        {
-            "name": "text_identical",
-            "execution": {
-                "command": "python",
-                "args": ["./compare_text.py"]
-            },
-            "expected": { "return_code": 0 },
-            "tags": ["text"]
-        },
-        {
-            "name": "text_diff",
-            "execution": {
-                "command": "python",
-                "args": ["./compare_text.py", "--mode", "diff"]
-            },
-            "expected": { "return_code": 1 },
-            "tags": ["text"]
-        }
-    ]
-}
-```
-
-### Import 级标签（Tags）
-
-当一个子文件中的所有用例都标记有相同的标签（如 `"text"`）时，无需在每个 case 里重复编写 `tags`。可以直接在 `import` 条目上添加 `tags`，框架会自动将标签注入到该文件导入的每一条用例：
-
-```json
-{ "import": "cases/text_tests.json", "tags": ["text", "fast"] }
-```
-
-**合并规则**：
-
-| 场景 | 结果 |
-|---|---|
-| import 有 tags，子用例无 tags | 子用例继承 import 的所有 tags |
-| import 有 tags，子用例也有 tags | 合并去重，import 的 tags 在前，子用例自有的在后 |
-| import 无 tags | 行为不变，向后兼容 |
-
-> 嵌套 import（子文件内部继续 import 其他文件）也适用此规则——外层 import 的 tags 会注入到**所有**递推展开后的用例上。
-
-### 工作原理
-
-1. **加载时展开**：Runner 在读取配置文件后、解析 `TestCase` 对象前，自动执行 import 展开。对 Runner 和执行引擎**完全透明**，无需修改测试用例或 Runner 代码。
-2. **递归展开**：子文件内可以继续 `import` 其他文件，支持多层嵌套。
-3. **循环引用保护**：框架维护已加载文件路径集合，检测到循环引用时抛出明确错误。
-4. **向后兼容**：不含 `import` 字段的配置文件行为与之前完全一致，零迁移成本。
-
-### 跨格式支持
-
-主配置为 JSON 时可以 import YAML 子文件，反之亦然。框架根据子文件扩展名（`.json` / `.yaml` / `.yml`）自动选择解析器。
-
-### Setup 合并规则
-
-如果主文件和子文件都定义了 `setup`，它们会深度合并（deep merge）：
-- **同名变量冲突**：子文件的 `setup` 覆盖主文件的同名字段。
-- **环境变量**：合并为一个字典，子文件优先。
-
-```json
-// 主文件 setup
-{ "environment_variables": { "BASE": "from_main", "OVERRIDE": "from_main" } }
-
-// 子文件 setup
-{ "environment_variables": { "SUB_KEY": "from_sub", "OVERRIDE": "from_sub" } }
-
-// 合并结果
-{ "environment_variables": {
-    "BASE": "from_main",
-    "SUB_KEY": "from_sub",
-    "OVERRIDE": "from_sub"  // 子文件覆盖
-} }
-```
-
-### 渐进式迁移
-
-无需一次性迁移所有配置：
-1. 先用 `validate` 命令确认现有配置无问题（见[配置校验](#配置校验)）
-2. 逐步将大文件中的部分用例移到子文件，用 `import` 引用
-3. 内联用例与 import 引用可在同一个 `test_cases` 数组中混合使用
-
-## 配置继承
-
-当多个测试用例结构高度相似（仅路径、参数等少量不同），可以用 `extends` + `abstract` + `variables` 消除重复配置。
-
-### 语法
-
-用例支持三个继承相关的新字段：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `abstract` | `boolean` | 设为 `true` 时为模板（基类），不参与执行 |
-| `extends` | `string` | 继承目标用例的 `name`，支持链式继承 |
-| `variables` | `object` | 用例级占位符变量，用于 `{key}` 替换 |
-
-### 基本用法
-
-```json
-{
-  "test_cases": [
-    {
-      "name": "_base_echo",
-      "abstract": true,
-      "execution": {
-        "command": "echo",
-        "args": ["{msg}"]
-      },
-      "expected": {
-        "output_contains": ["{msg}"]
-      },
-      "variables": {
-        "msg": "hello"
-      }
-    },
-    {
-      "name": "test_hello",
-      "extends": "_base_echo"
-    },
-    {
-      "name": "test_world",
-      "extends": "_base_echo",
-      "variables": {
-        "msg": "world"
-      }
-    }
-  ]
-}
-```
-
-展开后 `test_hello` 继承基类的全部字段（`execution.command`、`execution.args`、`expected`），占位符 `{msg}` 被 `variables.msg` 替换为 `"hello"`。`test_world` 覆盖 `variables.msg` 为 `"world"`。
-
-### 合并规则
-
-继承采用 **dict 深合并、list 整体替换** 策略：
-
-- **dict 字段**（如 `expected`、`variables`）：递归合并，子类字段覆盖父类同名 key
-- **list 字段**（如 `args`、`steps`、`tags`）：子类整列表替换父类，不追加
-
-```json
-{
-  "name": "_base",
-  "abstract": true,
-  "expected": {
-    "return_code": 0,
-    "output_contains": ["base"]
-  },
-  "tags": ["a", "b"],
-  "extends": "_base",
-  "expected": {
-    "output_contains": ["child"]
-  },
-  "tags": ["c"]
-}
-```
-
-合并结果：`expected.return_code` = `0`（来自父类），`expected.output_contains` = `["child"]`（子类整列表替换），`tags` = `["c"]`（整列表替换）。
-
-`abstract` 字段取子类自身值（默认 `false`），不会从父类继承，防止子类意外成为抽象模板。
-
-### 链式继承
-
-支持多层继承（A → B → C）：
-
-```json
-{
-  "name": "_A", "abstract": true,
-  "execution": { "command": "python", "args": ["-c"] }, "expected": {},
-  "variables": {"a": "1"}
-}
-{
-  "name": "_B", "abstract": true, "extends": "_A",
-  "expected": {"output_contains": ["b"]},
-  "variables": {"b": "2"}
-}
-{
-  "name": "C", "extends": "_B",
-  "variables": {"c": "3"},
-  "execution": { "args": ["print('{a} {b} {c}')"] }
-}
-```
-
-加载时自动检测循环继承并报错。
-
-### 变量替换优先级
-
-占位符替换分为两层：
-
-1. **用例级 `variables`**：从继承链一路深合并（子类覆盖父类），先应用到合并后的用例内容
-2. **全局 `--var`**：通过 CLI 传入（`--var KEY=VALUE`），在用例级变量之后叠加，**同名 key 全局优先级更高**
-
-```bash
-symtest run config.json --var solver=/path/to/solver
-```
-
-`setup` 区块仅使用全局 `--var` 替换（无用例级变量）。
-
-### validate 检查
-
-`symtest validate` 对继承配置做额外校验：
-
-- `extends` 目标是否存在
-- 是否形成循环继承链
-- `abstract` 用例不计入可执行用例数
-- `extends` 用例跳过必填字段检查（内容来自父类）
-
-### TUI 编辑限制
-
-> **注意**：TUI 目前不支持编辑继承用例。继承后的展开用例在 TUI 中可正常查看和运行，但请直接编辑 JSON/YAML 源文件来进行修改。
-
-## 配置校验
-
-`validate` 命令在不运行测试的情况下检查配置文件的正确性，适合在 CI 流水线中做配置合法性检查。
-
-### 用法
-
-```bash
-# 校验单个配置文件
-symtest validate test_cases.json
-
-# 校验带 import 的主配置（自动展开并检查所有子文件）
-symtest validate main_config.json
-
-# 指定工作目录
-symtest validate test_cases.json --workspace /path/to/project
-
-# 输出 JSON 格式（适合 AI/脚本解析）
-symtest validate test_cases.json --output-format json
-```
-
-### 校验内容
-
-| 检查项 | 说明 |
-|---|---|
-| 语法正确性 | JSON/YAML 格式是否合法（加载时隐式检查） |
-| 必填字段 | 每条用例是否包含 `name`、`execution.command`、`execution.args`、`expected`（序列模式检查每个 step） |
-| import 引用 | 被引用的子文件是否存在 |
-| 循环引用 | import 链中是否存在 A→B→A 的循环 |
-
-### 输出示例
-
-成功时：
-```
-  [OK] Loaded 15 test cases from 3 file(s)
-  [OK] All required fields present
-  [OK] No circular imports detected
-
-  Files:
-    - /project/main_config.json
-    - /project/cases/text_tests.json
-    - /project/cases/json_tests.yaml
-```
-
-有错误时：
-```
-  [OK] Loaded 3 test cases from 1 file(s)
-  [FAIL] case 'bad_case': missing required field 'expected'
-  [FAIL] Import target not found: /project/cases/nonexistent.json
-```
-
-## TUI 交互式管理器
-
-当大型测试项目把用例拆分到多个 JSON/YAML 子配置后，跨文件定位用例和检查场景覆盖会逐渐困难。TUI（Terminal User Interface）在所有导入配置之上提供统一视图，用于浏览、全局搜索、辅助检查覆盖场景，并可按需编辑或运行用例。它是大型测试集的辅助工具，不是日常执行测试的必需组件。
-
-### 安装
-
-TUI 依赖 `textual` 库，并作为按需安装的可选依赖提供：
-
-```bash
-# 安装时附带 TUI 支持
-pip install "symtest-cli[tui]"
-
-# 或者在已有框架上单独安装 textual
-pip install textual
-```
-
-如果未安装 `textual` 就直接执行 `symtest tui`，框架会给出友好的安装提示。
-
-### 启动
-
-```bash
-# 打开 TUI 编辑测试用例
-symtest tui test_cases.json
-
-# YAML 文件同样支持
-symtest tui test_cases.yaml
-
-# 指定工作目录
-symtest tui test_cases.json --workspace /path/to/project
-
-# 打开带 import 的主配置文件（自动展开子文件中的所有用例）
-symtest tui main_config.json
-```
-
-TUI 启动时会自动通过[配置拆分机制](#配置拆分机制)展开 `import` 引用，将所有用例加载到界面中统一管理。
-
-### 界面概览
-
-TUI 启动后显示**用例列表主界面**：
-
-- **顶部状态栏**：当前文件名、用例总数
-- **搜索栏**：`/` 键聚焦搜索框，支持子串/模糊/正则三种模式
-- **用例表格**：六列（序号、名称、命令、标签、超时、模式），支持键盘导航
-- **底部快捷键栏**：显示所有可用操作
-
-### 快捷键
-
-| 快捷键 | 功能 |
-|---|---|
-| `a` | 新增用例 |
-| `e` | 编辑选中的用例 |
-| `d` | 删除选中的用例 |
-| `u` | 复制选中的用例（名称追加 `_copy` 后缀） |
-| `r` | 运行选中的用例，显示执行结果 |
-| `F6` / `Ctrl+S` | 保存修改到文件 |
-| `/` | 聚焦搜索框 |
-| `Esc` | 清除搜索，恢复完整列表 |
-| `Alt+S` | 切换子串搜索模式（大小写不敏感） |
-| `Alt+F` | 切换模糊搜索模式（容忍拼写差异和缩写） |
-| `Alt+R` | 切换正则搜索模式 |
-| `q` / `Ctrl+Q` | 退出 |
-| `↑` / `↓` / `j` / `k` | 上下移动光标 |
-
-搜索时会同时匹配 `name`、`command`、`args`、`tags`、`description` 等字段，匹配结果在表格中高亮显示。
-
-### 编辑用例
-
-选中用例后按 `e` 进入编辑界面。编辑界面根据用例类型有两种模式：
-
-#### 单命令模式
-
-编辑表单包含以下字段：
-
-| 字段 | 说明 |
-|---|---|
-| `Name` | 用例名称（必填） |
-| `Command` | 要执行的命令 |
-| `Args` | 命令参数，每行一个 |
-| `Tags` | 标签列表，每行一个 |
-| `Description` | 用例描述 |
-| `Timeout` | 超时秒数 |
-| Expected | 期望断言的嵌套子表单（见下文） |
-
-#### 步骤序列模式
-
-当用例包含多个有序步骤时，切换到此模式。每个步骤有独立的 `Command`、`Args`、`Expected` 和 `Timeout`，支持添加、删除、编辑和上下移动步骤。
-
-两种模式可通过编辑界面内的快捷键切换，切换时会提示确认以免丢失数据。
-
-### `expected` 字段编辑
-
-`expected` 字段是一个嵌套字典，编辑器提供结构化输入：
-
-| 字段 | 输入方式 |
-|---|---|
-| `return_code` | 数字输入框 |
-| `output_contains` | 多行文本输入，一行一个匹配字符串 |
-| `output_matches` | 正则表达式文本输入 |
-| `compare_files` | 每行一个 JSON 对象，如 `{"actual":"out.txt","baseline":"base.txt","type":"text"}` |
-
-除上述已知字段外，还支持通过 `+ Add` 按钮添加自定义 key=value 对，value 为字符串或 JSON 文本。更多含义见[测试用例定义](#测试用例定义)。
-
-### 运行用例
-
-在列表中选中某条用例，按 `r` 即可实时调用框架执行引擎运行该用例。运行结束后弹出结果面板，显示：
-
-- 通过/失败状态
-- 返回码
-- 耗时
-- 命令输出（stdout/stderr）
-
-结果面板仅展示、不修改配置文件。
-
-### 保存
-
-对用例的任何增删改操作都在**内存中**进行，不会立即写入磁盘。
-
-- 按 `F6` 或 `Ctrl+S` **保存**：将当前全部用例写回原配置文件。
-- 通过 `save_as` 可**另存为**新文件（通过界面菜单操作）。
-
-退出 TUI 时如有未保存的修改，会弹出确认提示。
-
-## 运行测试
-
-### 命令行
-
-```bash
-# 运行 JSON 测试
-symtest run test_cases.json
-
-# 运行 YAML 测试
-symtest run test_cases.yaml
-
-# 运行带 import 拆分的主配置（自动展开子文件）
-symtest run main_config.json
-
-# 指定工作目录
-symtest run test_cases.json --workspace /path/to/project
-
-# 并行运行
-symtest run test_cases.json --parallel --workers 4
-
-# 指定并行模式
-symtest run test_cases.json --parallel --execution-mode process
-
-# 只运行指定用例
-symtest run test_cases.json -t test_name_1 -t test_name_2
-
-# 按标签过滤
-symtest run test_cases.json --tag smoke
-symtest run test_cases.json --tag smoke --tag regression
-
-# 同时按名称和标签过滤（AND 关系）
-symtest run test_cases.json -t test_name_1 --tag smoke
-
-# 详细输出
-symtest run test_cases.json --verbose
-
-# 调试模式
-symtest run test_cases.json --debug
-
-# 输出格式
-symtest run test_cases.json --output-format json|html|text
-
-# 启用历史记录（智能调度 + 回归检测）
-symtest run test_cases.json --history-dir ./hist
-
-# 自定义回归检测阈值（默认 1.5 倍）
-symtest run test_cases.json --history-dir ./hist --regression-threshold 2.0
-
-# 输出 JUnit XML 报告（可供 Jenkins/GitLab CI 等工具解析）
-symtest run test_cases.json --junit-xml report.xml
-
-# 只运行上次失败的用例（每次运行时覆盖式更新）
-symtest run test_cases.json --last-failed
-
-# 断点续跑：跳过已通过的步骤，从失败步骤继续
-symtest run test_cases.json --resume
-symtest run test_cases.json --resume -t long_pipeline
-
-# 比较失败时更新基线文件（交互运行需输入 yes）
-symtest run test_cases.json --update-baseline
-
-# 非交互环境必须显式确认
-symtest run test_cases.json --update-baseline --yes
-
-# 启用误差分析（数值比较时输出全量统计）
-symtest run test_cases.json --error-analysis
-```
-
-### 只运行上次失败的用例（--last-failed）
-
-`--last-failed` 自动过滤出上一次运行中**真正失败**的用例（`failed`、`timeout` 和 `xpassed`），适合 AI 迭代修复场景：修复一轮代码后，只需验证上次失败的用例，无需全量重跑（有限元全量可能几小时）。
-
-**xfail 语义**：标记为 `expected_failure` 的用例如果失败（`xfailed`），是预期行为，**不会**被 `--last-failed` 选中重跑。但如果 xfail 标记的用例意外通过（`xpassed`），则被视为真正失败，**会**被选中。
-
-**工作原理**：
-- 每次运行结束后，框架在 `<workspace>/.symtest/last_run.json` 中记录每个用例的状态
-- 记录采用**覆盖式更新**：本次跑到的用例用新结果覆盖旧结果，没跑到的保留原状态
-- 这意味着修好的 case 在下一次显示中不再是"failed"
-- 如果文件不存在（首次运行），`--last-failed` 会提示并正常运行全部用例
-
-```bash
-# 第一次：全量运行 10 个用例，3 个失败
-symtest run config.json
-
-# 修复代码后，只重跑那 3 个失败的
-symtest run config.json --last-failed
-
-# 如果 3 个全过，再跑一次全量确认
-symtest run config.json
-```
-
-**与 `-t` 的交互**：`--last-failed` 与 `-t`/`--tag` 可以同时使用，效果叠加（AND 关系）。
-
-### 断点续跑（--resume）
-
-`--resume` 针对**顺序步骤测试（sequence）**，跳过上次运行中已通过的步骤，直接从失败步骤继续执行。适合耗时长的多步骤用例——例如有限元分析中 step 1-3 通过了（各耗时几十秒甚至分钟），只有 step 4 的断言失败，`--resume` 可以跳过 1-3、只重跑 step 4。
-
-**工作原理**：
-- 每个步骤通过后，框架在 `<workspace>/.symtest/sequence_state/<case_name>.json` 中记录步骤状态，并将输出缓存到 `cache/` 子目录
-- 下次 `--resume` 时，计算配置哈希（所有步骤的 command/args/expected/timeout/retry_count 及 case 级 expected 的 SHA256）与已保存状态比对
-- 哈希匹配 → 跳过已通过的步骤，从缓存重建 `combined_output`（确保 case 级 `expected` 断言能正常执行）
-- 用例全部通过 → 自动删除状态文件和缓存，避免残留影响后续运行
-- 哈希不匹配（配置有改动）→ 自动全量重跑，并丢弃旧状态
-
-**信任模型**：`--resume` **不校验工作区产物**（输入文件、前置步骤生成的文件等）。使用 `--resume` 即表示用户确认输入文件未被修改。如果怀疑工作区被污染，应不带 `--resume` 全量重跑。
-
-```bash
-# 首次全量运行，long_pipeline 的 step 4 失败（总耗时 72s）
-symtest run config.json
-
-# 修复后只重跑 long_pipeline，跳过 step 1-3（仅耗时 ~0.14s）
-symtest run config.json -t long_pipeline --resume
-
-# 全部通过后，跑一次全量确认无回归
-symtest run config.json
-```
-
-**与 `-t` 的交互**：`--resume` 通常与 `-t` 组合使用，先定位到单个失败用例再断点续跑。不带 `-t` 时，所有已存在状态的序列用例都会尝试续跑。
-
-**限制**：
-- 仅对序列步骤用例（`steps` 模式）生效，单命令模式忽略
-- 状态文件的配置哈希会因任何 step 的 command/args/expected/timeout/retry_count 或 case 级 expected 变化而失效
-- 缓存输出主要用于重建 `combined_output`，报告中的 `output` 字段仍只包含失败步骤的输出
-
-### 自动更新基线文件（--update-baseline）
-
-在进行算法改进或参数调整后，你可能期望输出结果发生变化（且新结果更正确）。`--update-baseline` 会自动用实际产出覆盖基线文件，免去手动复制粘贴。
-
-```bash
-# 交互运行会先要求输入 yes
-symtest run config.json --update-baseline
-
-# 自动化或 CI 中显式确认
-symtest run config.json --update-baseline --yes
-```
-
-**行为**：
-- 交互运行必须输入完整的 `yes` 才会开始测试
-- 非交互环境不会等待输入，必须同时传入 `--yes`
-- 文件比较失败时，`actual` 文件被复制到 `baseline` 路径
-- 该条断言视为**通过**，用例状态为 `passed`
-- 报告中显示 `Baseline Updated` 计数和更新的文件列表
-- 文本报告与 JSON 报告均会列出所有被更新的 baseline 路径
-
-> **注意**：确认发生在测试执行前，而实际被更新的文件只有比较后才能确定。请将基线纳入版本控制，并审查报告中的 `Baseline Updated` 列表。Python API 中显式传入 `update_baseline=True` 视为调用方已经确认。
-
-### 配置校验 JSON 输出
-
-`validate` 命令新增 `--output-format json`，输出机器可读的 JSON 报告，适合 AI/脚本自动检查配置合法性：
-
-```bash
-symtest validate config.json --output-format json
-```
-
-输出示例：
-```json
-{
-  "valid": false,
-  "errors": ["[main_config.json] case 'bad_case': missing required field 'expected'"],
-  "summary": {"files": 1, "cases": 3, "files_loaded": ["/project/main_config.json"]}
-}
-```
-
-### Python API
-
-```python
-from symtest.runners import JSONRunner, YAMLRunner, ParallelJSONRunner
-
-# 顺序运行
-runner = JSONRunner(
-    config_file="test_cases.json",
-    workspace="/path/to/project",    # 可选，默认项目根目录
-    test_case_filter=["test_1"],     # 可选，只运行指定用例
-    test_case_tag_filter=["smoke"],  # 可选，只运行包含指定标签的用例
-    history_dir="./hist",            # 可选，启用历史记录与回归检测
-    regression_threshold=2.0,        # 可选，回归阈值倍数，默认 1.5
-    update_baseline=False,           # 可选，比较失败时自动更新基线，默认 False
-    last_failed=False,               # 可选，只运行上次失败的用例，默认 False
-    resume=False,                    # 可选，断点续跑序列用例，默认 False
-)
-success = runner.run_tests()
-
-# YAML 格式
-runner = YAMLRunner(config_file="test_cases.yaml")
-
-# 并行运行（JSON）
-runner = ParallelJSONRunner(
-    config_file="test_cases.json",
-    max_workers=4,                   # 可选，默认 CPU 核心数
-    execution_mode="thread",         # "thread" 或 "process"
-    test_case_filter=["test_1"],
-    history_dir="./hist",            # 可选，启用历史记录与智能调度
-    regression_threshold=2.0,        # 可选，回归阈值倍数，默认 1.5
-    update_baseline=False,           # 可选
-    last_failed=False,               # 可选
-    resume=False,                    # 可选，断点续跑序列用例
-)
-success = runner.run_tests()
-
-# 并行运行（YAML）
-from symtest.runners import ParallelYAMLRunner
-runner = ParallelYAMLRunner(
-    config_file="test_cases.yaml",
-    max_workers=4,
-    execution_mode="thread",
-)
-success = runner.run_tests()
-```
-
-### 获取结果
-
-```python
-runner.run_tests()
-
-# 汇总
-runner.results["total"]
-runner.results["passed"]
-runner.results["failed"]
-runner.results["xfailed"]      # 预期失败（不影响退出码）
-runner.results["xpassed"]      # 意外通过（计入失败）
-runner.results["updated"]   # 被 --update-baseline 更新的基线文件数
-
-# 详情 — 每个结果字典包含以下字段
-for detail in runner.results["details"]:
-    print(detail["name"])                     # 用例名称
-    print(detail["status"])                   # "passed" / "failed" / "xfailed" / "xpassed" / "timeout"
-    print(detail.get("message", ""))          # 失败原因
-    print(detail.get("duration"))             # 耗时（秒）
-    print(detail.get("xfail_reason", ""))     # xfail 原因（仅 xfailed/xpassed 状态）
-    print(detail.get("expected"))             # 期望断言（注册的验收标准）
-    print(detail.get("description"))          # 用例描述
-    print(detail.get("tags"))                 # 标签列表
-    print(detail.get("failure_kind"))         # 失败类型：return_code/output_contains/
-                                              #   output_matches/file_compare/timeout/
-                                              #   execution_error
-    print(detail.get("attempts", 1))          # 尝试次数（含重试）
-    print(detail.get("flaky", False))         # 是否重试后才通过
-    print(detail.get("attempt_history", []))  # 每次尝试的状态历史
-    print(detail.get("failed_step"))          # 步骤序列中的失败步骤号
-    print(detail.get("step_results", []))     # 每个步骤的详细结果
-    print(detail.get("compare_failures", [])) # 文件比较失败的结构化详情
-    print(detail.get("baseline_updated", [])) # 被更新的基线文件列表
-```
-
-**结果字典关键字段说明**：
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `status` | str | 四态之一：`passed`（通过）、`failed`（失败）、`xfailed`（预期失败）、`xpassed`（意外通过）、`timeout`（超时） |
-| `xfail_reason` | str | xfail 原因文本（来自配置中的 `xfail_reason` 字段），仅在 `xfailed`/`xpassed` 状态时有值 |
-| `expected` | dict | 注册的期望断言（含 return_code、output_contains、compare_files 等），方便回查验收标准 |
-| `description` | str | 测试用例的描述文本 |
-| `failure_kind` | str | 失败类型枚举，AI/脚本可据此选择修复策略 |
-| `attempts` | int | 总尝试次数（含重试），`1` 表示一次通过 |
-| `flaky` | bool | 重试后才通过时为 `true` |
-| `attempt_history` | list | 每次尝试的 `{attempt, status, message, duration}` |
-| `step_results` | list | 步骤序列每个 step 的 `{step, name, status, message, duration, command}` |
-| `compare_failures` | list | 每个失败的文件比较的结构化信息（含 `diff_summary`、`differences`、`error_stats`、`actual`/`baseline` 路径、容差参数） |
-| `baseline_updated` | list | `--update-baseline` 覆盖的基线文件路径列表 |
-
-## 项目入口脚本
-
-如果你的测试项目结构复杂（需要预设环境变量、定制报告路径等），直接使用 `symtest run` 命令行可能不够灵活。此时可以创建一个项目入口脚本（如 `test.py` 或 `run_tests.py`），在 Python 代码中调用框架 API。
-
-### 何时直接用 CLI
-
-| 场景 | 推荐方式 |
-|---|---|
-| 简单项目、单个配置文件 | `symtest run config.json --workers 4` |
-| 一次性运行、无特殊环境需求 | `symtest run config.yaml --tag smoke` |
-| CI 流水线 | `symtest run config.json --junit-xml report.xml` |
-
-### 何时包一层入口脚本
-
-| 场景 | 推荐方式 |
-|---|---|
-| 需要预设环境变量（如注入 venv PATH） | 入口脚本 |
-| 需要同时输出多种格式报告（文本 + JUnit XML） | 入口脚本 |
-| 团队共享固定运行参数（workers、history-dir 等） | 入口脚本 |
-| 需要根据配置文件扩展名自动选择 JSON/YAML runner | 入口脚本 |
-| Windows 下 console-script 命令（如 `compare-files`）找不到的问题 | 入口脚本（注入 venv Scripts 到 PATH） |
-
-### 入口脚本示例
-
-框架提供了开箱即用的示例脚本 `examples/full_runner_example.py`，可复制到你的项目根目录直接使用或按需修改。它支持以下所有 CLI 参数：
-
-| 参数 | 说明 |
-|---|---|
-| `config`（位置参数） | 测试配置文件路径（自动识别 .json / .yaml） |
-| `--test-target` / `-t` | 按名称过滤用例 |
-| `--tag` | 按标签过滤用例（OR 关系） |
-| `--last-failed` | 只运行上次失败的用例 |
-| `--resume` | 断点续跑序列用例 |
-| `--update-baseline` | 比较失败时更新基线；交互运行需要二次确认 |
-| `--yes` / `-y` | 跳过基线更新确认，供自动化或 CI 使用 |
-| `--junit-xml` | JUnit XML 报告输出路径 |
-| `--report` | 文本报告输出路径，默认 `test_report.txt` |
-| `--workers` / `-w` | 并行工作线程数，默认 4 |
-| `--execution-mode` | thread 或 process |
-| `--workspace` | 工作目录，默认脚本所在目录 |
-| `--var` | 模板变量替换，格式 `KEY=VALUE` |
-| `--verbose` / `-v` | 详细输出（DEBUG 级别日志） |
-
-### 快速上手
-
-1. 复制 `examples/full_runner_example.py` 到你的项目根目录，重命名为 `run_tests.py`
-2. 如果使用了虚拟环境且需要 console-script 命令，取消文件中 venv PATH 注入代码的注释
-3. 按团队习惯修改默认参数（如 `--workers` 默认值、`--history-dir` 默认路径）
-4. 运行测试：
-
-```bash
-# 全量运行
-python run_tests.py test_cases.json --workers 4
-
-# 只跑上次失败的用例
-python run_tests.py test_cases.json --last-failed
-
-# CI 中输出 JUnit 报告
-python run_tests.py test_cases.json --junit-xml report.xml
-```
-
-### Windows 下 WinError 2 问题
-
-如果你的测试用例 `command` 字段引用了 console-script 命令（例如 `compare-files`、`symtest` 等通过 pip 安装的入口点），在 Windows 下直接双击运行脚本或通过未激活的环境启动时，子进程可能找不到这些可执行文件，报错：
-
-```
-FileNotFoundError: [WinError 2] 系统找不到指定的文件。
-```
-
-这是因为这些命令以 `.exe` 包装器的形式存在于 `venv/Scripts/` 目录下，而子进程的 PATH 中没有该目录。
-
-**解决方案**：在入口脚本的最顶部（`main()` 函数开头或文件级）将 venv 的 `Scripts` 目录前置到 `PATH` 环境变量：
-
-```python
-import os
-
-venv_scripts = os.path.abspath(os.path.join(
-    os.path.dirname(__file__), "..", ".venv", "Scripts"))
-if os.path.isdir(venv_scripts):
-    os.environ["PATH"] = venv_scripts + os.pathsep + os.environ.get("PATH", "")
-```
-
-示例脚本 `examples/full_runner_example.py` 中已包含此段代码（默认注释），按需取消注释并调整路径即可。
-
-## 占位符（变量替换）
-
-当同一个配置文件需要在不同环境下使用不同参数（如求解器路径、模型文件路径等）时，可以用 `{变量名}` 占位符编写配置，运行时通过 `--var` 或 `variables` 参数传入实际值。
-
-### 编写含占位符的配置
-
-JSON：
-
-```json
-{
-    "test_cases": [
-        {
-            "name": "求解器测试",
-            "execution": {
-                "command": "{solver}",
-                "args": ["--input", "{model}", "--output", "{output}"]
-            },
-            "expected": { "return_code": 0 }
-        }
-    ]
-}
-```
-
-YAML：
-
-```yaml
-test_cases:
-  - name: 求解器测试
-    execution:
-      command: "{solver}"
-      args: ["--input", "{model}", "--output", "{output}"]
-    expected:
-      return_code: 0
-```
-
-占位符 `{变量名}` 可出现在配置文件的任意字符串值中，包括 `command`、`args`、`name`、`expected.output_contains` 等。支持同一个字符串中使用多个占位符，如 `"{solver} --input {model}"`。
-
-> **安全设计**：只有 `variables` 字典中存在的 key 才会被替换。`{xxx}` 若无匹配不会报错，而是原样保留。因此 `expected.output_matches` 中的正则模式（如 `{2,}`、`\d{4}`）不受影响。
-
-### 用法
-
-#### CLI
-
-```bash
-# 单个变量
-symtest run test_cases.json --var solver=/opt/solver/bin/solver.exe
-
-# 多个变量
-symtest run test_cases.json --var solver=/opt/solver/bin/solver.exe --var model=./data/model.dat
-
-# 与并行模式、标签过滤等组合使用
-symtest run test_cases.json --var solver=solver.exe --parallel --workers 4 --tag smoke
-```
-
-`--var` 格式为 `KEY=VALUE`，可多次使用。等号分隔，key 和 value 两侧的空格会被自动去除。
-
-#### Python API
-
-```python
-from symtest.runners import JSONRunner, YAMLRunner, ParallelJSONRunner, ParallelYAMLRunner
-
-# 顺序运行
-runner = JSONRunner(
-    config_file="test_cases.json",
-    variables={
-        "solver": "/opt/solver/bin/solver.exe",
-        "model": "./data/model.dat",
-        "output": "./results/output.dat",
-    },
-)
-success = runner.run_tests()
-
-# 并行运行
-runner = ParallelJSONRunner(
-    config_file="test_cases.json",
-    variables={"solver": "/opt/solver/bin/solver.exe"},
-)
-success = runner.run_tests()
-
-# YAML 同样支持
-runner = YAMLRunner(
-    config_file="test_cases.yaml",
-    variables={"solver": "/opt/solver/bin/solver.exe"},
-)
-success = runner.run_tests()
-```
-
-### 适用场景
-
-| 场景 | 示例 |
-|---|---|
-| 不同求解器版本测试 | `--var solver=v1.0/solver.exe` ↔ `--var solver=v2.0/solver.exe` |
-| 不同输入数据 | `--var model=case_1.dat` ↔ `--var model=case_2.dat` |
-| CI/CD 环境适配 | 本地 `/opt/solver.exe`，CI `/runner/solver.exe` |
-| 多平台路径 | Windows `--var solver=C:\solver.exe`，Linux `--var solver=/opt/solver.exe` |
-
-## 标签过滤
-
-通过标签（tags）可以对测试用例进行分类，并在运行时按标签批量过滤。标签过滤与名称过滤可同时使用，满足 AND 关系（两个条件都必须满足）。
-
-### 在测试用例中定义标签
-
-JSON：
-
-```json
-{
-    "test_cases": [
-        {
-            "name": "快速测试",
-            "execution": {
-                "command": "echo",
-                "args": ["hello"]
-            },
-            "tags": ["smoke", "fast"],
-            "expected": { "return_code": 0 }
-        },
-        {
-            "name": "完整回归测试",
-            "execution": {
-                "command": "python",
-                "args": ["long_test.py"]
-            },
-            "tags": ["regression", "slow"],
-            "expected": { "return_code": 0 }
-        }
-    ]
-}
-```
-
-YAML：
-
-```yaml
-test_cases:
-  - name: 快速测试
-    execution:
-      command: echo
-      args: ["hello"]
-    tags: ["smoke", "fast"]
-    expected:
-      return_code: 0
-```
-
-`tags` 是可选字段，不指定则默认为空列表。每个用例可以有多个标签。
-
-### 运行时过滤
-
-```bash
-# 只运行带 "smoke" 标签的用例
-symtest run test_cases.json --tag smoke
-
-# 运行带 "smoke" 或 "regression" 标签的用例（OR 关系）
-symtest run test_cases.json --tag smoke --tag regression
-
-# 同时按名称和标签过滤（AND 关系）
-symtest run test_cases.json -t alpha --tag fast
-```
-
-### Python API
-
-```python
-runner = JSONRunner(
-    config_file="test_cases.json",
-    test_case_tag_filter=["smoke"],     # 只运行含 smoke 标签的用例
-)
-success = runner.run_tests()
-
-# 结合名称过滤
-runner = JSONRunner(
-    config_file="test_cases.json",
-    test_case_filter=["alpha", "beta"],
-    test_case_tag_filter=["fast"],
-)
-success = runner.run_tests()
-```
-
-## Setup 模块
-
-Setup 模块在测试前执行初始化、测试后执行清理。
-
-### 环境变量（配置文件方式）
-
-JSON：
-
-```json
-{
-    "setup": {
-        "environment_variables": {
-            "TEST_ENV": "development",
-            "API_URL": "http://localhost:8080"
-        }
-    },
-    "test_cases": [...]
-}
-```
-
-YAML：
-
-```yaml
-setup:
-  environment_variables:
-    TEST_ENV: "development"
-    API_URL: "http://localhost:8080"
-test_cases:
-  [...]
-```
-
-配置文件中的环境变量会在测试前设置、测试后恢复原值。
-
-### 自定义 Setup 插件
-
-```python
-from symtest import BaseSetup, JSONRunner
-
-class DatabaseSetup(BaseSetup):
-    def setup(self):
-        # 初始化操作
-        pass
-
-    def teardown(self):
-        # 清理操作（即使测试失败也会执行）
-        pass
-
-runner = JSONRunner("test_cases.json")
-runner.setup_manager.add_setup(DatabaseSetup({"connection": "test_db"}))
-success = runner.run_tests()
-```
-
-多个插件按添加顺序执行 setup，按逆序执行 teardown。
-
-### 执行顺序
-
-1. 加载配置文件中的 setup 配置（环境变量等）
-2. 执行所有 setup 插件的 `setup()`（按添加顺序）
-3. 运行测试
-4. 执行所有 setup 插件的 `teardown()`（逆序，保证执行）
-
-## 并行测试
-
-```python
-from symtest.runners import ParallelJSONRunner
-
-runner = ParallelJSONRunner(
-    config_file="test_cases.json",
-    max_workers=4,                # 最大并发数，默认 CPU 核心数
-    execution_mode="thread"       # "thread" 或 "process"
-)
-success = runner.run_tests()
-
-# 回退到顺序执行
-runner.run_tests_sequential()
-```
-
-**线程模式**：共享内存，支持资源感知调度（见下节）。  
-**进程模式**：进程隔离，不支持资源调度。
-
-## 顺序步骤测试
-
-一个测试用例可包含多个有序步骤，某步失败则跳过后续步骤（fail-fast）。
-
-### JSON
-
-```json
-{
-    "test_cases": [
-        {
-            "name": "多步骤测试",
-            "execution": {
-                "steps": [
-                    {
-                        "command": "echo",
-                        "args": ["step1"],
-                        "expected": { "return_code": 0 }
-                    },
-                    {
-                        "command": "echo",
-                        "args": ["step2"],
-                        "expected": { "return_code": 0 },
-                        "retry_count": 2
-                    }
-                ]
-            }
-        }
-    ]
-}
-```
-
-### YAML
-
-```yaml
-test_cases:
-  - name: 多步骤测试
-    execution:
-      steps:
-        - command: echo
-          args: ["step1"]
-          expected:
-            return_code: 0
-        - command: echo
-          args: ["step2"]
-          expected:
-            return_code: 0
-```
-
-每个 step 支持 `command`、`args`、`expected`、`timeout`、`retry_count` 字段。
-
-**失败输出瘦身**：当序列中某一步失败时，结果字典的 `output` 字段**仅包含失败步骤的输出**——不会拼接前面成功步骤的大量输出。这大幅减少了失败报告的体积，适合 AI 快速诊断失败的步骤。
-
-**步骤详情**：通过 `detail["step_results"]` 可查看每个步骤的独立状态（即使全部通过），方便了解整个序列的执行流程。
-
-**失败标记**：失败时结果中 `failed_step` 字段标注失败步骤编号，如 "Failed at step 2/3"。
-
-**断点续跑**：序列用例失败后，可通过 `--resume` 跳过已通过的步骤，直接从失败步骤继续执行，大幅节省长耗时用例的迭代成本。详见[断点续跑](#断点续跑resume)。
-
-### Case 级别 expected（顺序步骤）
-
-当所有步骤都执行通过后，可以在 case 级别定义额外的 `expected` 断言，对所有步骤产生的文件做统一的验证（如文件比较）。Case 级别的 `expected` 字段格式与单命令模式完全一致，支持 `return_code`、`output_contains`、`output_matches`、`compare_files`。
-
-```json
-{
-    "name": "多步骤+文件对比",
-    "execution": {
-        "steps": [
-            {
-                "command": "python",
-                "args": ["./generate.py", "output.csv"],
-                "expected": { "return_code": 0 }
-            },
-            {
-                "command": "python",
-                "args": ["./process.py", "output.csv"],
-                "expected": { "return_code": 0, "output_contains": ["Done"] }
-            }
-        ]
-    },
-    "expected": {
-        "compare_files": [
-            {
-                "actual": "output.csv",
-                "baseline": "baseline/output.csv",
-                "type": "csv",
-                "rtol": 0.02,
-                "start_line": 93,
-                "end_line": 99
-            }
-        ]
-    }
-}
-```
-
-> **注意**：case 级别的 `expected` 只在所有 step 通过后才执行。如果某个 step 失败，case 级断言不会运行。case 级断言失败时，错误消息包含 "Case-level assertion failed" 前缀以便区分。
-
-## 资源感知调度
-
-仅线程模式生效。通过 `scheduling.resources` 字段配置，框架自动管理 CPU 核心分配。
-
-```json
-{
-    "name": "Heavy_Simulation",
-    "execution": {
-        "command": "solver",
-        "args": ["-i", "input.dat"],
-        "timeout": 36000
-    },
-    "scheduling": {
-        "resources": {
-            "cpu_cores": 4,
-            "estimated_time": 18000,
-            "min_memory_mb": 16000,
-            "priority": 10
-        }
-    },
-    "expected": { "return_code": 0 }
-}
-```
-
-| 字段 | 说明 |
-|---|---|
-| `cpu_cores` | 所需 CPU 核心数，默认 1。框架用信号量控制分配，超限任务排队等待 |
-| `estimated_time` | 预估耗时（秒），用于 LPT 调度（长任务优先启动） |
-| `min_memory_mb` | 预估内存（MB），目前仅用于日志警告 |
-| `priority` | 优先级 0-10，目前仅用于信息标注 |
-
-框架行为：
-- 自动检测 CPU 核心数，预留 2 核给系统
-- 任务启动时自动注入 `OMP_NUM_THREADS`、`MKL_NUM_THREADS`、`NPROC` 环境变量，防止求解器线程失控
-- 按 `estimated_time` 降序调度（LPT 策略）；若启用 `--history-dir`，优先使用历史 `avg_duration` 排序
-
-## 历史记录与回归检测
-
-通过 `--history-dir` 指定一个目录，框架会在该目录下维护一个 `.symtest` 文件，记录每个 case 的历史运行时间。
-
-### 工作原理
-
-1. **首次运行**：目录下没有 `.symtest`，自动创建空文件，排序仍使用配置中的 `estimated_time`
-2. **后续运行**：读取 `.symtest` 中的历史数据，优先使用 `avg_duration` 做调度排序
-3. **回归检测**：每次运行结束后，如果某 case 耗时超过历史均值的阈值倍数（默认 1.5），打印警告
-
-### CLI 用法
-
-```bash
-# 启用历史记录
-symtest run test_cases.json --history-dir ./hist
-
-# 自定义回归阈值（超过 2 倍均值才警告）
-symtest run test_cases.json --history-dir ./hist --regression-threshold 2.0
-```
-
-### Python API
-
-```python
-from symtest.runners import JSONRunner, ParallelJSONRunner
-
-# 顺序运行 + 历史记录
-runner = JSONRunner(
-    config_file="test_cases.json",
-    history_dir="./hist",
-    regression_threshold=2.0,  # 可选，默认 1.5
-)
-success = runner.run_tests()
-
-# 并行运行 + 历史记录（调度排序也会使用历史数据）
-runner = ParallelJSONRunner(
-    config_file="test_cases.json",
-    history_dir="./hist",
-)
-success = runner.run_tests()
-```
-
-### .symtest 文件格式
-
-```json
-{
-  "version": 1,
-  "cases": {
-    "case_name_1": {
-      "avg_duration": 3.5,
-      "last_duration": 3.2,
-      "run_count": 5
-    }
-  }
-}
-```
-
-| 字段 | 说明 |
-|---|---|
-| `avg_duration` | 累计平均耗时（秒），用于调度排序和回归基线 |
-| `last_duration` | 最近一次运行耗时 |
-| `run_count` | 历史运行次数 |
-
-### 回归警告示例
-
-当某 case 运行时间超过历史均值的阈值倍数时：
-
-```
-⚠ WARNING: Case 'heavy_simulation' regressed: 18.2s vs avg 10.5s (1.73x slower)
-```
-
-### 不启用历史记录
-
-不传 `--history-dir` 时行为与之前完全一致，不创建任何额外文件。
-
-### 清零历史记录（--update-history）
-
-当算法重构或环境变化导致历史耗时数据不再有代表性时，`--update-history`
-会清除本次运行涉及的 case 在 `.symtest` 中的历史记录，让本次运行成为
-新的回归检测基线。
-
-```bash
-# 清除历史后本次运行成为新基线（需搭配 --history-dir）
-symtest run config.json --history-dir ./hist --update-history
-```
-
-**行为**：
-- 清除 `.symtest` 中**本次运行涉及的 case** 的历史条目
-- 未参与本次运行的 case 的历史数据保留不动
-- 本次运行的回归检测不会产生误报（无历史基线可比）
-- 本次通过 case 的耗时会被记录为全新起点
-- 报告中显示 `History Reset` 计数
-
-> **注意**：需搭配 `--history-dir` 使用。清零范围仅限本次运行的 case，不影响其他 case 的历史数据。
-
-## JUnit XML 报告
-
-通过 `--junit-xml` 可在运行测试的同时输出 JUnit 格式的 XML 报告，兼容 Jenkins、GitLab CI、CircleCI 等 CI 工具。
-
-### CLI 用法
-
-```bash
-symtest run test_cases.json --junit-xml report.xml
-```
-
-`--junit-xml` 是补充输出，与 `--output-format`（text/json/html）并存，不影响控制台报告。
-
-### Python API
-
-```python
-from symtest import write_junit_xml
-
-runner.run_tests()
-write_junit_xml(runner.results, "report.xml", suite_name="my_suite")
-```
-
-状态映射：`passed` 记为通过；`failed` 记为 failure（断言失败）或 error（执行错误）；`timeout` 记为 error；`xfailed` 记为 **skipped**（预期失败，不影响构建）；`xpassed` 记为 **failure**（意外通过，视为构建失败）。每个 testcase 元素附带命令输出与失败原因。
-
-## 日志配置
-
-框架所有诊断与状态信息都通过 Python 标准 `logging` 模块输出，统一挂在 `symtest` 命名空间下。日志默认写入 **stderr**，因此 `stdout` 始终保持干净，可安全配合 `--output-format json` 做机器可读输出。
-
-### 命令行控制日志级别
-
-`run` 与 `compare` 子命令均支持：
-
-| 选项 | 说明 |
-|---|---|
-| `--verbose` / `-v` | 详细输出，日志级别提升至 DEBUG |
-| `--debug` | 调试模式，同样提升至 DEBUG，并在出错时打印完整堆栈 |
-
-默认级别为 INFO，仅显示关键进度与错误；加 `--verbose` 或 `--debug` 后会输出命令输出、调度细节等 DEBUG 级信息。
-
-```bash
-# 详细模式（含命令输出等 DEBUG 信息）
-symtest run test_cases.json --verbose
-
-# 调试模式（出错时打印堆栈）
-symtest run test_cases.json --debug
-```
-
-### 库使用方式
-
-作为库被 import 时，框架默认只挂载 `NullHandler`，不产生任何输出（符合库的礼貌日志规范）。需要看到日志时，调用 `setup_console_logging()` 启用控制台输出：
-
-```python
-import logging
-from symtest.logging_config import setup_console_logging, get_logger
-
-# 启用控制台日志（stderr），可指定级别
-setup_console_logging(level=logging.DEBUG)
-
-logger = get_logger(__name__)   # 自动归入 symtest 命名空间
-logger.info("自定义日志信息")
-```
-
-### 输出到日志文件
-
-框架未内置 `--log-file` 选项，但可借助 Python 标准 `logging` 自行为 `symtest` logger 添加文件处理器：
-
-```python
-import logging
-from symtest.logging_config import get_logger
-
-file_handler = logging.FileHandler("run.log", encoding="utf-8")
-file_handler.setLevel(logging.DEBUG)
-file_handler.setFormatter(
-    logging.Formatter("%(asctime)s %(levelname)-7s %(name)s %(message)s")
-)
-
-# 给框架根 logger 加文件处理器，所有子 logger 都会继承
-logging.getLogger("symtest").addHandler(file_handler)
-```
-
-上述代码既适用于库调用，也可放在脚本中配合 `symtest` 一起使用。控制台与文件处理器可并存。
-
-## 文件比较
-
-框架提供独立的文件比较能力，支持文本、JSON、CSV、XML、HDF5、二进制等多种格式。既可通过命令行工具使用，也可在测试用例的 `expected.compare_files` 中自动调用（见[文件比较断言](#文件比较断言compare_files)）。
-
-### 命令行工具
-
-有两种等价的调用方式，参数完全一致：
-
-```bash
-# 独立命令
-compare-files <file1> <file2> [选项]
-
-# symtest 子命令
-symtest compare <file1> <file2> [选项]
-```
-
-### 通用选项
-
-| 选项 | 说明 |
-|---|---|
-| `--file-type` | 文件类型：`auto`（默认）、`text`、`json`、`csv`、`xml`、`h5`、`binary` |
-| `--start-line` | 起始行号（1-based），默认 1 |
-| `--end-line` | 结束行号（1-based） |
-| `--start-column` | 起始列号（1-based），默认 1 |
-| `--end-column` | 结束列号（1-based） |
-| `--encoding` | 文本编码，默认 `utf-8` |
-| `--output-format` | 输出格式：`text`、`json`、`html` |
-| `--verbose` / `-v` | 详细输出 |
-| `--debug` | 调试模式 |
-| `--num-threads` | 并行线程数，默认 4 |
-
-### 文本文件比较
-
-```bash
-compare-files file1.txt file2.txt --start-line 10 --end-line 20
-```
-
-### JSON 文件比较
-
-```bash
-# 精确比较（默认）
-compare-files data1.json data2.json
-
-# 按 key 字段比较
-compare-files data1.json data2.json --json-compare-mode key-based --json-key-field id
-```
-
-| 选项 | 说明 |
-|---|---|
-| `--json-compare-mode` | `exact`（默认）或 `key-based` |
-| `--json-key-field` | key-based 模式的匹配字段，支持逗号分隔多字段 |
-
-### CSV 文件比较
-
-```bash
-# 基本比较
-compare-files data1.csv data2.csv
-
-# 自定义分隔符与数值容差
-compare-files data1.csv data2.csv --csv-delimiter ';' --csv-rtol 1e-4 --csv-atol 1e-6
-
-# TSV 文件（自动识别为 csv 类型）
-compare-files data1.tsv data2.tsv
-
-# 数据过滤（只比较满足条件的数值单元格）
-compare-files data1.csv data2.csv --csv-data-filter '>1e-6'
-compare-files data1.csv data2.csv --csv-data-filter 'abs>1e-9'
-compare-files data1.csv data2.csv --csv-data-filter '<=0.01'
-```
-
-| 选项 | 说明 |
-|---|---|
-| `--csv-rtol` | 数值相对容差，默认 1e-5 |
-| `--csv-atol` | 数值绝对容差，默认 1e-8 |
-| `--csv-delimiter` | 字段分隔符，默认 `,` |
-| `--csv-quotechar` | 引用字符，默认 `"` |
-| `--csv-data-filter` | 数据过滤表达式：`>`, `>=`, `<`, `<=`, `==`，支持 `abs` 前缀。只比较两个文件中**都满足**条件的数值单元格 |
-
-CSV 比较按行列结构逐单元格比对；数值单元格在容差范围内视为相等。`--csv-data-filter` 过滤后，不满足条件的数值单元格对不会报差异。差异报告包含行数、列数不匹配与单元格不一致，最多列出 10 条。
-
-#### 误差分析（--error-analysis）
-
-默认情况下，CSV 和 HDF5 比较器在发现 10 条差异后停止报告。当需要了解**全体数值单元格**的统计特征时，可通过 `--error-analysis` 启用流式全量统计。
-
-启用后，每个失败的文件比较会在报告的 Compare Failures 区块中附加 `error_stats` 信息：
-
-| 统计量 | 说明 |
-|---|---|
-| `total_numeric_cells` | 参与数值比较的单元格总数 |
-| `mismatched_cells` | 超出容差的单元格数 |
-| `max_abs_error` | 最大绝对误差及其位置 |
-| `max_rel_error` | 最大相对误差及其位置 |
-| `mean_abs_error` | 平均绝对误差 |
-| `rms_abs_error` | 均方根绝对误差（RMSE） |
-
-统计是**流式**计算的，不依赖差异截断，覆盖全体数值单元格。默认仅失败的比较输出统计，通过的比较不输出。
-
-如需让**通过**的用例也输出统计信息（例如用于监控容差余量），可改用 `--error-analysis-all`（它会隐含启用 `--error-analysis`）：
-
-```bash
-# 对所有用例（含通过的）输出误差统计
-symtest run config.json --error-analysis-all
-```
-
-启用后，每个**通过**的用例会在 Detailed Results 区块中以 `error_stats (baseline vs actual):` 的形式列出上述统计量（与失败用例的 `error_stats` 字段一致）。通过用例的统计也同时写入 `--output json` 的 `assertion_results[].error_stats`，便于程序化消费。仅当 `--error-analysis-all` 启用时才会对通过用例产生额外输出，未启用时行为不变。
-
-**CLI 用法**：
-
-```bash
-# 启用误差分析
-symtest run config.json --error-analysis
-
-# 启用误差分析并对通过的用例也输出统计
-symtest run config.json --error-analysis-all
-
-# 与比较参数组合使用
-symtest run config.json --error-analysis --csv-rtol 1e-4 --csv-data-filter '>0'
-```
-
-**Python API**：
-
-```python
-# 在比较器中启用
-comparator = ComparatorFactory.create_comparator(
-    "csv", rtol=1e-5, atol=1e-8, error_analysis=True
-)
-result = comparator.compare_files("data1.csv", "data2.csv")
-print(result.error_stats)  # dict 或 None
-
-# 通过 Assertions.compare_files 启用
-from symtest.core.assertions import Assertions
-cf_result = Assertions.compare_files(
-    "actual.csv", "baseline.csv",
-    file_type="csv", rtol=1e-5, atol=1e-8,
-    error_analysis=True,
-)
-print(cf_result["error_stats"])
-```
-
-> **注意**：`--error-analysis` 仅对数值型比较器（CSV、HDF5）生效，文本/JSON/XML/二进制比较器忽略此参数。未启用时行为不变，无额外开销。
-
-### XML 文件比较
-
-```bash
-# 结构化比较（标签、属性、文本、子元素）
-compare-files config1.xml config2.xml
-
-# HTML 文件（自动识别为 xml 类型）
-compare-files page1.html page2.html
-```
-
-XML 比较按 DOM 结构递归比对标签、属性、文本内容与子元素数量。差异报告定位到具体路径（如 `/root/item[0]/@id`），最多列出 10 条。
-
-### HDF5 文件比较
-
-```bash
-# 比较指定表
-compare-files data1.h5 data2.h5 --h5-table table1,table2
-
-# 用正则匹配表名
-compare-files data1.h5 data2.h5 --h5-table-regex "result_.*"
-
-# 逗号分隔多个正则
-compare-files data1.h5 data2.h5 --h5-table-regex "table1,table2,table3"
-
-# 数值容差
-compare-files data1.h5 data2.h5 --h5-rtol 1e-5 --h5-atol 1e-8
-
-# 数据过滤（只比较满足条件的数据）
-compare-files data1.h5 data2.h5 --h5-data-filter '>1e-6'
-compare-files data1.h5 data2.h5 --h5-data-filter 'abs>1e-9'
-compare-files data1.h5 data2.h5 --h5-data-filter '<=0.01'
-
-# 禁止自动展开 group 路径
-compare-files data1.h5 data2.h5 --h5-table group1 --h5-no-expand-path
-```
-
-| 选项 | 说明 |
-|---|---|
-| `--h5-table` | 指定表名，逗号分隔 |
-| `--h5-table-regex` | 正则匹配表名，逗号分隔多个模式 |
-| `--h5-structure-only` | 只比较结构，不比较内容 |
-| `--h5-show-content-diff` | 显示内容差异详情 |
-| `--h5-rtol` | 相对容差，默认 1e-5 |
-| `--h5-atol` | 绝对容差，默认 1e-8 |
-| `--h5-data-filter` | 数据过滤表达式：`>`, `>=`, `<`, `<=`, `==`，支持 `abs` 前缀 |
-| `--h5-no-expand-path` | 禁止自动展开 group 路径下的子项 |
-
-### 二进制文件比较
-
-```bash
-compare-files binary1.bin binary2.bin --similarity --chunk-size 16384
-```
-
-| 选项 | 说明 |
-|---|---|
-| `--similarity` | 计算相似度指数 |
-| `--chunk-size` | 读取块大小，默认 8192 |
-
-### Python API
-
-```python
-from symtest.file_comparator import ComparatorFactory
-
-# 文本比较
-comparator = ComparatorFactory.create_comparator("text", encoding="utf-8", verbose=True)
-result = comparator.compare_files("file1.txt", "file2.txt")
-
-# JSON 比较
-comparator = ComparatorFactory.create_comparator("json", compare_mode="key-based", key_field="id")
-result = comparator.compare_files("data1.json", "data2.json")
-
-# CSV 比较
-comparator = ComparatorFactory.create_comparator("csv", rtol=1e-5, atol=1e-8, delimiter=",")
-result = comparator.compare_files("data1.csv", "data2.csv")
-
-# CSV 比较（启用误差分析）
-comparator = ComparatorFactory.create_comparator("csv", rtol=1e-5, atol=1e-8, delimiter=",", error_analysis=True)
-result = comparator.compare_files("data1.csv", "data2.csv")
-print(result.error_stats)  # 全量数值统计
-
-# XML 比较
-comparator = ComparatorFactory.create_comparator("xml", encoding="utf-8")
-result = comparator.compare_files("config1.xml", "config2.xml")
-
-# HDF5 比较
-comparator = ComparatorFactory.create_comparator("h5", tables=["table1"], rtol=1e-5)
-result = comparator.compare_files("data1.h5", "data2.h5")
-
-# 结果
-result.identical   # bool
-result.differences # list
-```
-
-## 扩展开发
-
-### 自定义 Runner
-
-```python
-from symtest.core.base_runner import BaseRunner
-
-class CustomRunner(BaseRunner):
-    def load_test_cases(self):
-        # 加载测试用例到 self.test_cases
-        pass
-
-    def run_single_test(self, test_case):
-        # 执行单个测试，返回结果字典
-        pass
-```
-
-### 自定义 Setup 插件
-
-```python
-from symtest import BaseSetup
-
-class MySetup(BaseSetup):
-    def setup(self):
-        # self.config 可获取传入的配置字典
-        pass
-
-    def teardown(self):
-        pass
-```
-
-### 自定义文件比较器
-
-框架支持三种方式扩展比较能力：
-
-#### 方式一：工作区插件目录（推荐）
-
-在 workspace 下创建 `comparators/` 目录，放入 `*_comparator.py` 文件（命名与内置比较器一致），框架会在首次使用时自动发现并注册其中的 `*Comparator` 类。
-
-```
-your-workspace/
-├── comparators/
-│   └── my_analysis_comparator.py   # 由框架自动发现
-└── test_config.json
-```
-
-可通过 CLI `--plugin-dir` 参数指定额外插件目录（支持多次使用）：
-
-```bash
-symtest run test_config.json --plugin-dir ./extra_plugins
-```
-
-插件也会通过环境变量 `CLITEST_PLUGIN_DIRS` 自动继承到 process 模式子进程。
-
-**插件开发注意事项**：
-- 继承 `symtest.file_comparator.BaseComparator`
-- 类名必须以 `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` 透传
-
-在配置中直接使用注册的类型名：
-
-```json
-{
-  "type": "myanalysis",
-  "actual": "optional_for_plugins",
-  "baseline": "optional_for_plugins",
-  "param1": "value1"
-}
-```
-
-#### 方式二：内置 `script` 类型比较器
-
-适用于独立分析脚本快速接入，无需编写比较器类：
-
-```json
-{
-  "type": "script",
-  "script": "analyze_xxx.py",
-  "actual": "output.txt",
-  "baseline": "baseline.txt",
-  "cwd": ".",
-  "pass_pattern": "RESULT: PASS",
-  "fail_pattern": "RESULT: (MISMATCH|FAILED)",
-  "pass_exit_code": 0,
-  "timeout": 600
-}
-```
-
-**参数说明**：
-
-| 参数 | 必填 | 默认值 | 说明 |
-|---|---|---|---|
-| `script` | 是 | — | 脚本路径（相对 workspace 或绝对） |
-| `actual` | 否 | — | 传给脚本的第一个文件参数 |
-| `baseline` | 否 | — | 传给脚本的第二个文件参数 |
-| `cwd` | 否 | — | 脚本工作目录 |
-| `interpreter` | 否 | `sys.executable` | Python 解释器 |
-| `pass_exit_code` | 否 | `0` | 判定为通过的退出码 |
-| `pass_pattern` | 否 | — | stdout 必须匹配此正则才判定为通过 |
-| `fail_pattern` | 否 | — | stdout 匹配此正则则强制判定为失败（优先级最高） |
-| `timeout` | 否 | `3600` | 超时秒数 |
-
-**判定逻辑**：
-1. `fail_pattern` 匹配 → 失败（优先级最高）
-2. `pass_pattern` 设置但不匹配 → 失败
-3. `pass_pattern` 匹配 → 使用退出码判定
-4. 无 pattern → 直接使用退出码判定
-
-脚本的 stdout 和 stderr 会完整捕获到 `Comparator Output` 区块中，在报告渲染时限 20 行展示。
-
-#### 方式三：手动注册（编程方式）
-
-```python
-from symtest.file_comparator import ComparatorFactory
-from symtest.file_comparator.base_comparator import BaseComparator
-
-class FooComparator(BaseComparator):
-    # 实现 read_content / compare_content 等方法
-    pass
-
-ComparatorFactory.register_comparator("foo", FooComparator)
-
-# 之后即可在 compare_files 断言或命令行 --file-type foo 中使用
-comparator = ComparatorFactory.create_comparator("foo")
-```
-
-#### 专用插件示例：hourglass 切线刚度分析
-
-`examples/plugins/hourglass_tangent_comparator.py` 是一个完整的工作区插件示例，展示了如何将专用的 `analyze_*_tangent.py` 分析脚本接入框架：
-
-```json
-{
-  "type": "hourglass_tangent",
-  "script": "case/.../analyze_case01_tangent.py",
-  "case_dir": "case/.../case01",
-  "pass_threshold": 1e-6,
-  "timeout": 600
-}
-```
-
-**特点**：
-- 通过 subprocess 调分析脚本（**零改动** analyze 代码），捕获 stdout 后用正则解析 `RESULT:` 行和 `full_rel`/`aa_rel`/`hh_rel`/`asymmetry` 等数值指标
-- 构造结构化 `ComparisonResult`：`identical` 基于 `full_rel < pass_threshold` 判定；`differences` 列出超限指标；`error_stats` 包含全部数值
-- 脚本 stdout 进入 `Comparator Output` 区块
-
-使用方法：将插件文件复制到 workspace 的 `comparators/` 目录下即可自动发现，无需改框架代码。
-
-> **更多插件开发指导**：参见 `examples/plugins/README.md`。entry points (`pip install` 即生效) 将在后续迭代中支持。
-
-### 断言与文件比较
-
-`Assertions` 类提供静态断言方法，`expected` 中的校验均由其完成：
-
-```python
-from symtest.core.assertions import Assertions
-
-Assertions.return_code_equals(actual_code, 0)
-Assertions.contains(output, "expected text")
-Assertions.matches(output, r".*regex.*")
-Assertions.compare_files("actual.txt", "baseline.txt", file_type="text", workspace="/ws")
-
-# 启用误差分析（仅 CSV/H5 生效）
-Assertions.compare_files("actual.h5", "baseline.h5", file_type="h5", workspace="/ws", rtol=1e-5, error_analysis=True)
-```
-
-`compare_files` 会自动按扩展名识别类型（`.h5/.hdf5/.hdf`→h5、`.json`→json、`.csv/.tsv`→csv、`.xml/.html/.htm`→xml、`.txt/.log/.out/.py`→text、其余→binary），相对路径按 `workspace` 解析，额外参数（含 `error_analysis`）透传给比较器。
-
-成功时返回结构化字典（含 `identical`、`actual`、`baseline`、`diff_summary`、`differences` 等字段），失败时抛出 `ValidationError(AssertionError)`，携带 `failure_kind` 和 `compare_failures` 列表。
-
-## 运行框架自带测试
-
-项目自带统一测试入口 `tests/run_all.py`，通过 `--scope` 选择测试范围（test target），并可用 `--extra` 透传任意 pytest 参数。
-
-### 测试范围
-
-| scope | 说明 | 对应目录 |
-|---|---|---|
-| `unit` | 单元测试（core、runners 等） | `tests/unit` |
-| `integration` | 集成测试（文件比较、并行、路径处理等） | `tests/integration` |
-| `e2e` | 端到端测试（用户流程） | `tests/e2e` |
-| `all` | 运行上述全部范围（默认） | 三者合集 |
-
-> 注：`tests/demos/` 下的脚本为手动/交互演示，不纳入 scope 运行，需单独执行。
-
-### 用法
-
-```bash
-# 运行全部测试（默认）
-python tests/run_all.py
-
-# 开发者也可一次安装全部可选与测试依赖
-pip install -e ".[dev]"
-
-# 只运行单元测试
-python tests/run_all.py --scope unit
-
-# 只运行集成测试
-python tests/run_all.py --scope integration
-
-# 只运行端到端测试
-python tests/run_all.py --scope e2e
-
-# 透传 pytest 参数，例如按关键字过滤
-python tests/run_all.py --scope integration --extra "-k h5"
-
-# 透传多个 pytest 参数
-python tests/run_all.py --scope unit --extra "-v -k assertions"
-```
-
-`--extra` 接收的字符串会经 `shlex` 拆分后追加到 pytest 命令行。脚本通过当前解释器（`sys.executable -m pytest`）调用 pytest，确保使用激活的环境而非 PATH 中首个 `pytest`。
-
-测试环境需先激活你的 Python 环境（如 conda）：
-
-```bash
-conda activate <你的环境名>
-python tests/run_all.py
-```
diff --git a/pyproject.toml b/pyproject.toml
index 9787c3b..d38dffa 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,3 +1,47 @@
 [build-system]
-requires = ["setuptools", "wheel"]
+requires = ["setuptools>=61", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[project]
+name = "symtest-cli"
+version = "1.5.1"
+description = "Regression testing for CLI applications, with multi-step workflows and numerical file comparison."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Xiaotong Wang", email = "xiaotongwang98@gmail.com" },
+]
+requires-python = ">=3.9"
+dependencies = [
+    "h5py>=3.11.0,<4.0.0",
+    "numpy>=1.21.0; python_version<'3.12'",
+    "numpy>=1.26.0; python_version>='3.12'",
+]
+
+[project.optional-dependencies]
+yaml = ["PyYAML>=6.0"]
+all = ["PyYAML>=6.0"]
+dev = [
+    "PyYAML>=6.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ozil111/symtest-cli"
+Documentation = "https://github.com/ozil111/symtest-cli/blob/main/docs/user_manual.md"
+Source = "https://github.com/ozil111/symtest-cli"
+Tracker = "https://github.com/ozil111/symtest-cli/issues"
+
+[project.scripts]
+symtest = "symtest.cli:main"
+# Backward-compatible alias for users of the old cli-test-framework.
+cli-test = "symtest.cli:main"
+compare-files = "symtest.commands.compare:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
diff --git a/requirements.txt b/requirements.txt
index 87ef52a..87a645c 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,6 @@
+numpy>=1.26.0
+h5py>=3.11.0,<4.0.0
+PyYAML
 pytest
 pytest-asyncio
 pytest-cov
-PyYAML
-textual>=0.40.0
diff --git a/setup.py b/setup.py
deleted file mode 100644
index 38f98cd..0000000
--- a/setup.py
+++ /dev/null
@@ -1,75 +0,0 @@
-from setuptools import setup, find_packages
-import os
-import re
-
-# Read the contents of the README file
-this_directory = os.path.abspath(os.path.dirname(__file__))
-with open(os.path.join(this_directory, 'README.md'), encoding='utf-8') as f:
-    long_description = f.read()
-
-
-def read_version():
-    """Single source of truth: __version__ in symtest/__init__.py."""
-    init_path = os.path.join(this_directory, "src", "symtest", "__init__.py")
-    with open(init_path, encoding="utf-8") as f:
-        match = re.search(r'^__version__ = ["\']([^"\']+)["\']', f.read(), re.MULTILINE)
-    if not match:
-        raise RuntimeError("Unable to find __version__ in symtest/__init__.py")
-    return match.group(1)
-
-
-setup(
-    name="symtest-cli",
-    version=read_version(),
-    author="Xiaotong Wang",
-    author_email="xiaotongwang98@gmail.com",
-    description="Regression testing for CLI applications, with multi-step workflows and numerical file comparison.",
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    url="https://github.com/ozil111/symtest-cli",
-    packages=find_packages(where="src"),
-    package_dir={"": "src"},
-    install_requires=[
-        "h5py>=3.11.0,<4.0.0",
-        "numpy>=1.21.0; python_version<'3.12'",
-        "numpy>=1.26.0; python_version>='3.12'",
-    ],
-    extras_require={
-        "yaml": ["PyYAML>=6.0"],
-        "tui": ["textual>=0.40.0"],
-        "all": [
-            "PyYAML>=6.0",
-            "textual>=0.40.0",
-        ],
-        "dev": [
-            "PyYAML>=6.0",
-            "textual>=0.40.0",
-            "pytest>=7.0",
-            "pytest-asyncio>=0.21.0",
-            "pytest-cov>=4.0",
-        ],
-    },
-    entry_points={
-        'console_scripts': [
-            'symtest=symtest.cli:main',
-            # Backward-compatible alias for users of the old cli-test-framework.
-            'cli-test=symtest.cli:main',
-            'compare-files=symtest.commands.compare:main',
-        ],
-    },
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: MIT License",
-        "Operating System :: OS Independent",
-        "Development Status :: 4 - Beta",
-        "Intended Audience :: Developers",
-        "Topic :: Software Development :: Testing",
-        "Topic :: Software Development :: Libraries :: Python Modules",
-    ],
-    python_requires='>=3.9',
-    project_urls={
-        'Documentation': 'https://github.com/ozil111/symtest-cli/blob/main/docs/user_manual.md',
-        'Source': 'https://github.com/ozil111/symtest-cli',
-        'Tracker': 'https://github.com/ozil111/symtest-cli/issues',
-    },
-)
diff --git a/examples/skill/SKILL.md b/skill/SKILL.md
similarity index 62%
rename from examples/skill/SKILL.md
rename to skill/SKILL.md
index 5b19783..3e44cfc 100644
--- a/examples/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -4,11 +4,13 @@ description: >-
   This skill should be used when writing functional tests for CLI programs,
   defining acceptance criteria, or using the symtest-cli / symtest framework.
   It covers JSON/YAML test case authoring, multi-step sequence tests,
-  numerical golden file comparison (HDF5/CSV/XML), parallel execution, and
-  targeted re-runs with --last-failed and --resume. Trigger when the task
-  involves creating test configurations for command-line tools, writing
-  acceptance specs as structured assertions, or running regression tests
-  with symtest.
+  numerical golden file comparison (HDF5/CSV/XML), comparator plugin
+  development (three-lane architecture: file / data-channel / autonomous),
+  parallel execution, and targeted re-runs with --last-failed and --resume.
+  Trigger when the task involves creating test configurations for
+  command-line tools, writing acceptance specs as structured assertions,
+  authoring custom comparator plugins, or running regression tests with
+  symtest.
 ---
 
 # CLI Test Framework (symtest-cli)
@@ -32,6 +34,8 @@ legacy configs with `symtest migrate`.
 - Writing functional/regression tests for CLI programs
 - Defining machine-readable acceptance criteria for a feature
 - Comparing numerical output files (HDF5, CSV) against golden baselines
+- Authoring custom comparator plugins (data-channel extractors, analysis
+  comparators) or wiring existing analysis scripts into comparisons
 - Setting up parallel test execution or CI integration
 
 ## Core Workflows
@@ -51,7 +55,7 @@ legacy configs with `symtest migrate`.
    - `return_code` — expected exit code (default 0).
    - `output_contains` — list of strings that must appear in stdout.
    - `output_matches` — regex pattern for stdout.
-   - `compare_files` — file comparison assertions (see Workflow 3).
+   - `compare_files` — file comparison assertions (see Workflow 2).
 4. Add metadata: `tags` for filtering, `description` for context. Put
    `timeout` for long-running commands and `retry_count` for flaky tests
    inside `execution`; declare `depends_on`/`resources` in `scheduling`.
@@ -66,7 +70,8 @@ legacy configs with `symtest migrate`.
 
 For all available fields and their meanings, consult
 `references/field_reference.md`. For complete usage details (setup plugins,
-TUI, resource scheduling, etc.), consult `references/user_manual.md`.
+case search via `symtest find`, resource scheduling, etc.), consult
+`references/user_manual.md`.
 
 ### Workflow 2: Numerical Golden File Testing
 
@@ -88,15 +93,13 @@ starting point.
    ]
    ```
 2. Choose the comparator `type`: `text`, `json`, `csv`, `xml`, `h5`, `binary`,
-   or `script`. Omit `type` to auto-detect by file extension.
-   If the `type` is not one of the above, it refers to a **user-defined
-   comparator**. User-defined comparators are loaded from
+   `script`, or `script_extract`. Omit `type` to auto-detect by file
+   extension. If the `type` is not one of the above, it refers to a
+   **user-defined comparator**. User-defined comparators are loaded from
    `<workspace>/comparators/*_comparator.py`. When troubleshooting a
    custom `type`, check that directory first — verify the plugin file
    exists and its class imports succeed (use `from symtest.file_comparator...`,
-   not other package names). To author a new one, start from
-   `assets/templates/my_analysis_comparator.py` (see
-   `references/user_manual.md` → "Custom File Comparator").
+   not other package names). To author a new one, see Workflow 3.
 3. Set numerical tolerance: `rtol` (relative) and `atol` (absolute).
 4. Use `--error-analysis` to get full statistics (max error, RMSE, etc.) on
    failure.
@@ -106,6 +109,60 @@ starting point.
    ```
    Always review updated baselines and keep them in version control.
 
+### Workflow 3: Authoring Comparator Plugins
+
+Custom comparators follow a **three-lane architecture** around the root
+contract `ComparatorBase.compare(ctx) -> ComparisonResult`. Choose the lane
+by verdict ownership:
+
+1. **Data lane** (`ExtractorComparator`) — plain numeric arrays compared with
+   rtol/atol. The plugin only EXTRACTS per-channel data
+   (`extract(ctx) -> {name: ChannelData}`); the framework owns the verdict
+   with per-channel tolerances (`channels` / `default_channel` config keys).
+   Start from `assets/templates/my_channel_extractor.py`. For existing
+   scripts with zero plugin code, use the built-in `script_extract` type:
+   the script prints a JSON channel payload on stdout (protocol and error
+   semantics in `assets/templates/extract_channels_script.py`).
+2. **Autonomous lane** (extend `ComparatorBase` directly) — custom verdict
+   logic (composite thresholds, label parsing, sign/asymptotic checks).
+   Implement `compare(ctx)`; populate `identical` / `differences` /
+   `error_stats` / `command_output`. Start from
+   `assets/templates/my_analysis_comparator.py`.
+3. **File lane** (`FileComparator`) — only for comparing two same-kind files
+   (the built-in text/json/csv/xml/h5/binary comparators); rarely needed in
+   workspaces.
+
+Hard rules for all lanes:
+
+- **Strict configuration**: declare constructor parameters explicitly.
+  Unknown/misspelled compareSpec keys fail loudly at construction (the error
+  names the comparator type and its supported parameters). Free-form config
+  is an explicit plugin opt-in (its own `**params` catch-all), never a
+  framework default. Put plugin-owned config under the `options` compareSpec
+  key to keep the core schema generic.
+- **Path ownership**: declare path-like constructor params in the
+  `path_params` class attribute; the framework resolves them against the
+  workspace BEFORE construction, so constructor state already holds absolute
+  paths. NEVER resolve paths against `os.getcwd()` (unreliable under
+  parallel/process execution).
+- **One source of truth**: comparator configuration lives only in
+  constructor-captured state; `CompareContext` carries invocation-level
+  context (workspace, actual/baseline, window ranges), never a second copy
+  of configuration.
+- **Naming**: file `*_comparator.py`, class `*Comparator`; optional
+  `comparator_type` class attribute overrides the registered type name;
+  abstract base classes are never registered.
+- **Result semantics**: data-lane plugins cannot alter pass/fail
+  (framework-owned). Plugin metrics ride along via `ChannelData.extra_stats`
+  — a SEPARATE namespace that can never overwrite canonical stats
+  (`max_abs_error`, `total`, ...). Channel results are rendered exclusively
+  from `ComparisonResult.channels`. Custom VERDICT requires the autonomous
+  lane; autonomous comparators without file inputs leave
+  `file1`/`file2` as `None` (no fake empty strings).
+
+Full details (config examples, JSON protocol, result semantics, report
+rendering): `references/user_manual.md` → "Custom File Comparator".
+
 ## Decision Guide
 
 ### JSON vs YAML config
@@ -118,6 +175,8 @@ starting point.
   (`execution.command` form).
 - **Step sequence** (`execution.steps`): multiple ordered commands, fail-fast.
   Use when output of step N is input to step N+1.
+- The two forms are mutually exclusive: declaring both `command`/`args` and
+  `steps` in one `execution` block is a configuration error.
 
 ### When to use `import` (config splitting)
 - When the config grows large (>30 cases) or cases naturally group by module.
@@ -213,7 +272,7 @@ For a complete project entry script with all CLI options, copy and adapt
 - `references/field_reference.md` — Quick field lookup table for test case
   configuration. Consult this when filling in or verifying config fields.
 - `references/user_manual.md` — Complete framework manual covering all
-  features (setup plugins, TUI, resource scheduling, history, custom
+  features (setup plugins, resource scheduling, history, custom
   comparators, extension development). Consult for advanced or uncommon
   features not covered in this file.
 
@@ -225,6 +284,11 @@ For a complete project entry script with all CLI options, copy and adapt
 - `assets/templates/test_cases_golden_file.json` — Numerical golden file test
   with HDF5/CSV comparison.
 - `assets/templates/my_analysis_comparator.py` — Minimal runnable template
-  for a user-defined custom comparator plugin.
+  for an autonomous-lane custom comparator plugin (custom verdict).
+- `assets/templates/my_channel_extractor.py` — Data-lane channel extractor
+  template (framework-owned per-channel tolerance verdict).
+- `assets/templates/extract_channels_script.py` — Script template for the
+  built-in `script_extract` type (JSON channel payload protocol, zero plugin
+  code).
 - `assets/full_runner_example.py` — Full project entry script with all CLI
   options, report generation, and JUnit XML output.
diff --git a/examples/skill/assets/full_runner_example.py b/skill/assets/full_runner_example.py
similarity index 96%
rename from examples/skill/assets/full_runner_example.py
rename to skill/assets/full_runner_example.py
index 3a4eb78..a31bcea 100644
--- a/examples/skill/assets/full_runner_example.py
+++ b/skill/assets/full_runner_example.py
@@ -39,6 +39,9 @@
   # 启用误差分析（CSV/HDF5 数值比较的统计信息）
   python run_tests.py test_cases.json --error-analysis
 
+  # 启用误差分析，并对通过的用例也输出统计（隐含 --error-analysis）
+  python run_tests.py test_cases.json --error-analysis-all
+
   # 输出 JUnit XML 供 Jenkins/GitLab CI 解析
   python run_tests.py test_cases.json --junit-xml report.xml
 """
@@ -195,6 +198,13 @@ def main():
              "total_numeric_cells、mismatched_cells、"
              "max_abs/rel_error、mean/rms_abs_error",
     )
+    parser.add_argument(
+        "--error-analysis-all",
+        action="store_true",
+        default=False,
+        help="同 --error-analysis，且对通过的用例也在报告中输出误差统计"
+             "（隐含启用 --error-analysis）",
+    )
 
     # ---- 输出 ----
     parser.add_argument(
@@ -317,6 +327,7 @@ def main():
         variables=variables,
         plugin_dirs=args.plugin_dir,
         error_analysis=args.error_analysis,
+        error_analysis_all=args.error_analysis_all,
     )
 
     # ---- 运行测试 ----
diff --git a/skill/assets/templates/extract_channels_script.py b/skill/assets/templates/extract_channels_script.py
new file mode 100644
index 0000000..f7747fb
--- /dev/null
+++ b/skill/assets/templates/extract_channels_script.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+@file extract_channels_script.py
+@brief Zero-modification script template for the built-in "script_extract" type
+@details The framework runs this script as a subprocess and parses the JSON
+         channel payload printed on stdout.  No Python plugin class needed.
+
+Companion config example::
+
+    {
+      "type": "script_extract",
+      "script": "extract_channels_script.py",
+      "args": [],
+      "channels": {"S33": {"atol": 600.0}},
+      "default_channel": {"rtol": 1e-5, "atol": 1e-8},
+      "timeout": 600
+    }
+
+Protocol contract:
+- Print EXACTLY ONE JSON document on stdout:
+    {"channels": {"<name>": {"expected": [...], "actual": [...],
+                             "extra_stats": {...}  # optional
+                             }}}
+- Exit code MUST be 0.  Non-zero exit, timeout, malformed JSON, missing
+  "channels" key, or a channel missing expected/actual arrays all become
+  comparison ERRORS (never a silent pass).
+- Extra stdout lines (progress logs) are fine; only stdout is parsed, so
+  print the JSON last and keep it on a single line (json.dumps default).
+- If the compareSpec declares "actual"/"baseline", they arrive as trailing
+  argv slots with baseline FIRST: sys.argv[-2] = baseline, sys.argv[-1] = actual.
+- Tolerances come from the config (per-channel overrides in "channels",
+  fallback in "default_channel") — the script never judges pass/fail itself.
+"""
+
+import json
+import sys
+
+
+def load_numeric_column(path, column):
+    """Example loader: one numeric column from a whitespace-delimited file."""
+    values = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            parts = line.split()
+            if parts:
+                values.append(float(parts[column]))
+    return values
+
+
+def main():
+    # Trailing file slots (optional in the config): baseline first, then actual.
+    baseline_path = sys.argv[-2] if len(sys.argv) >= 2 else None
+    actual_path = sys.argv[-1] if len(sys.argv) >= 2 else None
+
+    # TODO: replace with real extraction — read solver output, ODB, HDF5,
+    # or whatever upstream data the test produces.
+    expected = load_numeric_column(baseline_path, column=0)  # reference data
+    actual = load_numeric_column(actual_path, column=0)      # command output
+
+    payload = {
+        "channels": {
+            "col1": {
+                "expected": expected,
+                "actual": actual,
+                # Optional plugin-defined metrics (free-form dict), merged
+                # into this channel's stats in the report:
+                # "extra_stats": {"max_gradient": 0.12},
+            },
+        }
+    }
+    # Print the JSON document LAST on stdout — the framework parses it.
+    print(json.dumps(payload))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skill/assets/templates/my_analysis_comparator.py b/skill/assets/templates/my_analysis_comparator.py
new file mode 100644
index 0000000..408dcc7
--- /dev/null
+++ b/skill/assets/templates/my_analysis_comparator.py
@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+@file my_analysis_comparator.py
+@brief Autonomous-lane workspace plugin template for symtest-cli (v2 contract)
+@details Copy this file into <workspace>/comparators/ and adapt the logic.
+         Auto-discovered and registered as type "myanalysis" (class name minus
+         the "Comparator" suffix, lowercased) — or set a `comparator_type`
+         class attribute to override the name.
+
+Autonomous lane = the plugin OWNS the verdict (e.g. composite thresholds,
+label parsing, sign/asymptotic checks).  If your data is plain numeric
+arrays compared with rtol/atol, use the data lane instead
+(see my_channel_extractor.py / the built-in "script_extract" type).
+
+v2 contract notes (breaking vs. pre-2.x):
+- Implement `compare(self, ctx) -> ComparisonResult`; do NOT override
+  `compare_files`, and do NOT implement `read_content`/`compare_content`
+  (they no longer exist on the root class).
+- `ctx` carries invocation context only: workspace / actual / baseline /
+  params (window ranges) / error_analysis.  Comparator configuration lives
+  ONLY in constructor state (single source of truth).
+- Declare path-like constructor params in `path_params`; the framework
+  resolves them against the workspace BEFORE construction.  Never resolve
+  paths against CWD.
+- Constructor parameters are STRICT: unknown/misspelled compareSpec keys
+  fail loudly at construction.  Opt into free-form config only explicitly
+  (your own `**params` catch-all).
+"""
+
+from symtest.file_comparator.base_comparator import BaseComparator, CompareContext
+from symtest.file_comparator.result import ComparisonResult, Difference
+
+
+class MyAnalysisComparator(BaseComparator):
+    """
+    @brief Analysis-style comparator that owns its verdict.
+    @details Constructor parameters are strict — a misspelled config key
+             (e.g. "pass_threhsold") fails construction instead of silently
+             using the default.
+    """
+
+    # Constructor params holding filesystem paths (framework-resolved).
+    path_params = ("script", "case_dir")
+
+    def __init__(self, script="", case_dir=None, pass_threshold=1e-6):
+        super().__init__()
+        self.script = script
+        self.case_dir = case_dir  # already workspace-resolved via path_params
+        self.pass_threshold = pass_threshold
+
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        """
+        @param ctx CompareContext: invocation context (paths resolved).
+        @return ComparisonResult: structured result consumed by the report.
+        """
+        result = ComparisonResult(
+            file1=str(ctx.baseline or ""),
+            file2=str(ctx.actual or ""),
+        )
+
+        # TODO: replace with real analysis logic — read ctx.actual /
+        # ctx.baseline, run a subprocess (self.script, cwd=self.case_dir),
+        # parse metrics from stdout, etc.
+        metrics = {"max_error": 0.0}
+        max_error = metrics["max_error"]
+        identical = max_error < self.pass_threshold
+
+        result.identical = identical
+        result.differences = [
+            Difference(
+                position="max_error",
+                expected=f"<{self.pass_threshold}",
+                actual=str(max_error),
+                diff_type="content",
+            )
+        ] if not identical else []
+        result.error_stats = metrics  # free-form dict; rendered generically
+        result.command_output = None  # optional: subprocess stdout -> report
+        return result
diff --git a/skill/assets/templates/my_channel_extractor.py b/skill/assets/templates/my_channel_extractor.py
new file mode 100644
index 0000000..56f37c2
--- /dev/null
+++ b/skill/assets/templates/my_channel_extractor.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+@file my_channel_extractor.py
+@brief Data-lane (channel) workspace plugin template for symtest-cli (v2 contract)
+@details Copy this file into <workspace>/comparators/ and adapt the extraction
+         logic.  Auto-discovered and registered as type "mychannelextractor".
+
+Data lane = the plugin only EXTRACTS per-channel numeric data; the FRAMEWORK
+owns the verdict via per-channel tolerances (config `channels` /
+`default_channel`) using the shared numeric core.  Benefits: uniform error
+stats, per-channel pass/fail in reports, predictable semantics for AI
+consumers.  If you need a custom verdict, use the autonomous lane instead
+(see my_analysis_comparator.py).
+
+Companion config example::
+
+    {
+      "type": "mychannelextractor",
+      "ref_csv": "out/reference.csv",
+      "actual_csv": "out/actual.csv",
+      "channels": {
+        "S33": {"atol": 600.0, "data_filter": "abs>1e-12"}
+      },
+      "default_channel": {"rtol": 1e-5, "atol": 1e-8}
+    }
+
+No-plugin alternative: if your data comes from an existing script, the
+built-in "script_extract" type runs it as a subprocess and parses a JSON
+channel payload from stdout — see extract_channels_script.py.
+"""
+
+from symtest.file_comparator.base_comparator import CompareContext
+from symtest.file_comparator.extractor_comparator import ChannelData, ExtractorComparator
+
+
+class MyChannelExtractorComparator(ExtractorComparator):
+    """
+    @brief Extracts named channels of (expected, actual) numeric arrays.
+    @details Implement `extract(ctx)` only.  Constructor parameters are
+             strict: `channels` / `default_channel` / `rtol` / `atol` are
+             consumed by the base class; plugin params (ref_csv, actual_csv)
+             are declared here.  Unknown compareSpec keys fail loudly.
+    """
+
+    # Constructor params holding filesystem paths (framework-resolved).
+    path_params = ("ref_csv", "actual_csv")
+
+    def __init__(self, ref_csv="", actual_csv="", **params):
+        # NOTE: `**params` here is an explicit opt-in for free-form user
+        # configuration; drop it if your extractor declares all its options.
+        super().__init__(**params)
+        self.ref_csv = ref_csv      # already workspace-resolved
+        self.actual_csv = actual_csv
+
+    def extract(self, ctx: CompareContext):
+        """
+        @return dict: {channel_name: ChannelData(expected, actual, extra_stats)}
+        @raises Exception: failures become ComparisonResult.error (never a
+                silent pass).
+        """
+        ref = self._load(self.ref_csv)
+        act = self._load(self.actual_csv)
+
+        return {
+            "S11": ChannelData(expected=ref[:, 0], actual=act[:, 0]),
+            "S22": ChannelData(expected=ref[:, 1], actual=act[:, 1]),
+            "S33": ChannelData(
+                expected=ref[:, 2],
+                actual=act[:, 2],
+                # Optional plugin-defined error metrics, merged into this
+                # channel's stats and rendered by the report.
+                extra_stats={"hydrostatic_shift": float(act[:, 2].mean())},
+            ),
+        }
+
+    @staticmethod
+    def _load(path):
+        import numpy as np
+        data = np.loadtxt(path, delimiter=",")
+        # Guarantee 2-D (rows x columns) so per-channel column indexing works
+        # even for single-column files, where loadtxt returns a 1-D array.
+        return data.reshape(-1, 1) if data.ndim == 1 else data
diff --git a/examples/skill/assets/templates/test_cases_golden_file.json b/skill/assets/templates/test_cases_golden_file.json
similarity index 100%
rename from examples/skill/assets/templates/test_cases_golden_file.json
rename to skill/assets/templates/test_cases_golden_file.json
diff --git a/examples/skill/assets/templates/test_cases_simple.json b/skill/assets/templates/test_cases_simple.json
similarity index 100%
rename from examples/skill/assets/templates/test_cases_simple.json
rename to skill/assets/templates/test_cases_simple.json
diff --git a/examples/skill/assets/templates/test_cases_simple.yaml b/skill/assets/templates/test_cases_simple.yaml
similarity index 100%
rename from examples/skill/assets/templates/test_cases_simple.yaml
rename to skill/assets/templates/test_cases_simple.yaml
diff --git a/examples/skill/assets/templates/test_cases_steps.json b/skill/assets/templates/test_cases_steps.json
similarity index 100%
rename from examples/skill/assets/templates/test_cases_steps.json
rename to skill/assets/templates/test_cases_steps.json
diff --git a/examples/skill/references/field_reference.md b/skill/references/field_reference.md
similarity index 100%
rename from examples/skill/references/field_reference.md
rename to skill/references/field_reference.md
diff --git a/skill/references/user_manual.md b/skill/references/user_manual.md
new file mode 100644
index 0000000..415b55e
--- /dev/null
+++ b/skill/references/user_manual.md
@@ -0,0 +1,2220 @@
+# CLI Test Framework User Manual
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Test Case Definition](#test-case-definition)
+- [Case-Level Environment Variables](#case-level-environment-variables-env)
+- [Configuration Splitting](#configuration-splitting)
+- [Configuration Inheritance](#configuration-inheritance)
+- [Configuration Validation](#configuration-validation)
+- [Cross-File Case Search](#cross-file-case-search-find)
+- [Running Tests](#running-tests)
+- [Project Entry Script](#project-entry-script)
+- [Placeholders (Variable Substitution)](#placeholders-variable-substitution)
+- [Tag Filtering](#tag-filtering)
+- [Setup Module](#setup-module)
+- [Parallel Testing](#parallel-testing)
+- [Sequential Step Testing](#sequential-step-testing)
+- [Resource-Aware Scheduling](#resource-aware-scheduling)
+- [History & Regression Detection](#history--regression-detection)
+- [JUnit XML Report](#junit-xml-report)
+- [Logging Configuration](#logging-configuration)
+- [File Comparison](#file-comparison)
+- [Extension Development](#extension-development)
+- [Running Framework Tests](#running-framework-tests)
+
+## Installation
+
+```bash
+pip install symtest-cli
+```
+
+Requirement: Python >= 3.9
+
+YAML support is available as an optional dependency:
+
+```bash
+pip install "symtest-cli[yaml]"
+```
+
+Install YAML and all other optional features together:
+
+```bash
+pip install "symtest-cli[all]"
+```
+
+HDF5 file comparison depends on `h5py` (installed with the framework). If you need to use other comparison features without HDF5, you can uninstall it separately, but HDF5 comparison will become unavailable.
+
+## Test Case Definition
+
+> **Schema v2 (1.4)**: The config uses a layered DSL — execution-related fields (`command`, `args`, `timeout`, `retry_count`, `env`, `steps`) live in the `execution` block, scheduling-related fields (`depends_on`, `resources`) live in the `scheduling` block, and `expected` stays at the top level. The old flat layout was removed; use `symtest migrate` to migrate. Migration recursively covers the whole `import` tree: by default each file gets a `<stem>.v2<ext>` copy with import paths rewritten automatically; `--in-place` overwrites all files in place (mutually exclusive with `--output`).
+
+### JSON Format
+
+```json
+{
+    "test_cases": [
+        {
+            "name": "Test Name",
+            "execution": {
+                "command": "echo",
+                "args": ["Hello"],
+                "timeout": 60,
+                "retry_count": 0
+            },
+            "scheduling": {
+                "resources": {
+                    "cpu_cores": 2,
+                    "estimated_time": 300,
+                    "min_memory_mb": 1024,
+                    "priority": 5
+                }
+            },
+            "expected": {
+                "return_code": 0,
+                "output_contains": ["Hello"],
+                "output_matches": ".*regex.*",
+                "compare_files": [
+                    {
+                        "actual": "output.txt",
+                        "baseline": "baseline.txt",
+                        "type": "text"
+                    }
+                ]
+            }
+        },
+        {
+            "name": "Known Failure Test",
+            "execution": {
+                "command": "echo",
+                "args": ["should_fail"]
+            },
+            "expected_failure": true,
+            "xfail_reason": "Bug #42 not yet fixed",
+            "expected": { "return_code": 1 }
+        }
+    ]
+}
+```
+
+### YAML Format
+
+```yaml
+test_cases:
+  - name: Test Name
+    execution:
+      command: echo
+      args: ["Hello"]
+      timeout: 60
+      retry_count: 0
+    scheduling:
+      resources:
+        cpu_cores: 2
+        estimated_time: 300
+        min_memory_mb: 1024
+        priority: 5
+    expected:
+      return_code: 0
+      output_contains:
+        - "Hello"
+      output_matches: ".*regex.*"
+      compare_files:
+        - actual: output.txt
+          baseline: baseline.txt
+          type: text
+
+  - name: Known Failure Test
+    execution:
+      command: echo
+      args: ["should_fail"]
+    expected_failure: true
+    xfail_reason: "Bug #42 not yet fixed"
+    xfail_quiet: true
+    expected:
+      return_code: 1
+```
+
+### Expected Failure (xfail)
+
+When a known defect prevents a test case from passing, you can mark `expected_failure: true`. The framework distinguishes between "expected failures" and "unexpected passes":
+
+| Scenario | Status | Exit Code Impact | Description |
+|---|---|---|---|
+| xfail + indeed failed | `xfailed` | Not counted as failure | Report shows `xfail_reason`; details displayed normally (can suppress Command Output via `xfail_quiet`) |
+| xfail + unexpectedly passed | `xpassed` | **Counted as failure** | Report highlights "remove xfail marker" |
+
+This is consistent with pytest's xfail semantics. When used with `--last-failed`, xfailed cases are excluded from rerun; xpassed cases are included.
+
+```json
+{
+    "name": "KnownBug",
+    "execution": {
+        "command": "solver",
+        "args": ["--input", "bug_case.dat"]
+    },
+    "expected_failure": true,
+    "xfail_reason": "Bug #42: Boundary condition error, fix expected in v2.1",
+    "expected": { "return_code": 1 }
+}
+```
+
+When xfailed case output is extremely verbose (e.g., hundreds of lines of solver logs) and repetitive, add `xfail_quiet: true` to keep **only the reason and command, omitting Command Output** from the report. Other metadata (Description, Expected, Command, Return Code, Error Message, Compare Failures, Step Results, etc.) is still displayed normally:
+
+```json
+{
+    "name": "KnownBug (quiet mode)",
+    "execution": {
+        "command": "solver",
+        "args": ["--input", "bug_case.dat"]
+    },
+    "expected_failure": true,
+    "xfail_reason": "Bug #42: Boundary condition error, fix expected in v2.1",
+    "xfail_quiet": true,
+    "expected": { "return_code": 1 }
+}
+```
+
+### Test Dependencies (depends_on)
+
+When test cases have ordering dependencies (e.g., D requires A, B, and C to generate data first), declare them via `depends_on`. The framework automatically schedules execution in DAG topological order:
+
+**Parallel mode**: A, B, and C run concurrently. D is submitted only after all three pass. If a dependency fails, its downstream cases are auto-skipped (cascade skip).
+
+**Sequential mode**: The framework reorders cases topologically, ensuring dependencies run first. Downstream cases are skipped on dependency failure.
+
+**JSON example**:
+
+```json
+{
+    "test_cases": [
+        { "name": "A", "execution": { "command": "python", "args": ["gen_a.py"] }, "expected": {"return_code": 0} },
+        { "name": "B", "execution": { "command": "python", "args": ["gen_b.py"] }, "expected": {"return_code": 0} },
+        { "name": "C", "execution": { "command": "python", "args": ["gen_c.py"] }, "expected": {"return_code": 0} },
+        {
+            "name": "D",
+            "execution": { "command": "python", "args": ["merge.py"] },
+            "scheduling": { "depends_on": ["A", "B", "C"] },
+            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
+        }
+    ]
+}
+```
+
+**YAML example**:
+
+```yaml
+test_cases:
+  - name: A
+    execution:
+      command: python
+      args: ["gen_a.py"]
+    expected: { return_code: 0 }
+
+  - name: B
+    execution:
+      command: python
+      args: ["gen_b.py"]
+    expected: { return_code: 0 }
+
+  - name: C
+    execution:
+      command: python
+      args: ["gen_c.py"]
+    expected: { return_code: 0 }
+
+  - name: D
+    execution:
+      command: python
+      args: ["merge.py"]
+    scheduling:
+      depends_on: [A, B, C]
+    expected:
+      return_code: 0
+      compare_files:
+        - file: output.h5
+          type: hdf5
+```
+
+**Scheduling semantics**:
+
+| Dependency Status | Downstream Behavior |
+|---|---|
+| `passed` or `xfailed` | Dependency "satisfied", downstream runs normally |
+| `failed` or `xpassed` | Dependency "unsatisfied", downstream marked `skipped` with cascade skip |
+| Circular dependency | Configuration validation error, execution blocked |
+
+`skipped` is NOT counted as `failed`; shown separately as `Skipped: N` in the report summary.
+
+**Constraints**:
+- Dependency names must exist in the same config file's `test_cases`
+- Self-dependency is not allowed (`depends_on: ["self"]`)
+- Circular dependencies are not allowed (A → B → A)
+- `depends_on` and `steps` are independent—`depends_on` is a case-level concept, `steps` is an intra-case step-level concept
+- Zero-overhead fast path when no dependencies are declared
+
+### Field Descriptions
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Test case name |
+| `execution.command` | Yes | Command to execute (supports commands with arguments as a single string, e.g., `python ./run.py`; the framework auto-splits and resolves the path) |
+| `execution.args` | No | List of command arguments |
+| `description` | No | Test case description |
+| `execution.timeout` | No | Timeout in seconds, default 3600; set `null` for no limit |
+| `execution.retry_count` | No | Number of automatic retries on failure, default 0 (no retry). In single-command mode, applies to the entire case; in step mode, applies per step. If a case passes after retry, results are marked `flaky: true` |
+| `tags` | No | Tag list for batch filtering (e.g., `["smoke", "fast"]`) |
+| `scheduling.resources` | No | Resource configuration, see [Resource-Aware Scheduling](#resource-aware-scheduling) |
+| `expected_failure` | No | Mark as expected failure (xfail). When `true`, failure is counted as XFailed (no exit code impact); unexpected pass is counted as XPassed (treated as failure) |
+| `xfail_reason` | No | Reason text for xfail, displayed in the report (e.g., "Bug #42 not yet fixed") |
+| `xfail_quiet` | No | When `true`, suppress Command Output (stdout/stderr) for xfailed cases in the report; only command, return code, and failure reason metadata retained |
+| `scheduling.depends_on` | No | List of test case names this case depends on (e.g., `["A", "B"]`). The case will wait until all dependencies pass before executing. On dependency failure, the case and its downstream are auto-skipped. Works with both parallel and sequential runners |
+| `execution.env` | No | Case-level environment variable mapping (e.g. `{"MYAPP_SCALE": "1.0"}`), defined inside `execution`, injected into the subprocess only when this case runs (all steps in sequence mode). See [Case-Level Environment Variables](#case-level-environment-variables-env) |
+| `expected.return_code` | No | Expected return code |
+| `expected.output_contains` | No | List of strings the output must contain |
+| `expected.output_matches` | No | Regex pattern the output must match (single string) |
+| `expected.compare_files` | No | File comparison assertions list, see below |
+
+### execution — pick one form (mutually exclusive)
+
+`execution` has two forms, **choose exactly one**; declaring both is a configuration error:
+
+- **Single-command form**: `command` + `args` (with optional `timeout` / `retry_count` / `env`)
+- **Steps form**: `steps` (a list; each step is `command + args + expected`); `command` / `args` must not be declared alongside `steps`
+
+### File Comparison Assertions (compare_files)
+
+Declare one or more file comparison rules in `expected.compare_files`. The framework automatically uses the corresponding comparator to diff the actual output file against the baseline after command execution. The test passes only when all comparisons pass; these coexist with `return_code`, `output_contains`, and other assertions.
+
+Fields for each comparison rule:
+
+| Field | Required | Description |
+|---|---|---|
+| `actual` | Yes | Path to the file produced by the test command (relative paths resolved against workspace) |
+| `baseline` | Yes | Path to the baseline/reference file (relative paths resolved against workspace) |
+| `type` | No | Comparator type: `text`, `json`, `csv`, `xml`, `h5`, `binary`; auto-detected by extension if omitted |
+| `start_line` | No | Starting line number (1-based), compare from this line onward |
+| `end_line` | No | Ending line number (1-based), compare up to this line |
+| `start_column` | No | Starting column number (1-based), compare from this column onward |
+| `end_column` | No | Ending column number (1-based), compare up to this column |
+| Others | No | Passed through to the corresponding comparator, e.g., `rtol`, `atol`, `encoding`, `tables`, `data_filter` |
+
+```json
+"expected": {
+    "return_code": 0,
+    "compare_files": [
+        {
+            "actual": "result.h5",
+            "baseline": "baseline/result.h5",
+            "type": "h5",
+            "rtol": 1e-5,
+            "atol": 1e-8,
+            "tables": ["/stress", "/displacement"]
+        },
+        {
+            "actual": "summary.csv",
+            "baseline": "baseline/summary.csv"
+        }
+    ]
+}
+```
+
+## Case-Level Environment Variables (env)
+
+Use the `env` field inside `execution` (same level as `command` and `steps`) to inject environment variables into a single case's subprocess. The variables apply only to that case (all steps in sequence mode) and do not affect other cases.
+
+### JSON
+
+```json
+{
+    "name": "Case-level env test",
+    "execution": {
+        "command": "solver",
+        "args": ["-i", "input.dat"],
+        "env": {
+            "MYAPP_SCALE": "1.0",
+            "OMP_NUM_THREADS": "8"
+        }
+    },
+    "expected": { "return_code": 0 }
+}
+```
+
+### YAML
+
+```yaml
+- name: Case-level env test
+  execution:
+    command: solver
+    args: ["-i", "input.dat"]
+    env:
+      MYAPP_SCALE: "1.0"
+  expected: { return_code: 0 }
+```
+
+### Sequence Mode
+
+`env` is defined inside `execution` (same level as `steps`) and applies to **all steps** of that case:
+
+```json
+{
+    "name": "multi-step with env",
+    "execution": {
+        "env": { "MYAPP_SCALE": "1.0" },
+        "steps": [
+            { "command": "python", "args": ["./step1.py"], "expected": { "return_code": 0 } },
+            { "command": "python", "args": ["./step2.py"], "expected": { "return_code": 0 } }
+        ]
+    }
+}
+```
+
+### Semantics
+
+| Aspect | Behavior |
+|---|---|
+| Injection mechanism | Injected via subprocess `env`, never mutates the global `os.environ`; process-isolated and thread-safe |
+| Precedence | `os.environ` (incl. `setup.environment_variables`) < scheduler-injected (`OMP/MKL/NPROC`) < **case `env` (highest)** — case env can override `OMP_NUM_THREADS` |
+| Scope | Current case only, no cross-case pollution (unlike global `setup.environment_variables`) |
+| Placeholders | Auto-supported; `"env": {"SCALE": "{scale}"}` is substituted via `variables`/`--var` |
+| Inheritance (extends) | Auto-supported; `env` is a dict, deep-merged with child keys overriding parent |
+| Value type | Strings; numeric/boolean values are coerced with `str()` at parse time |
+
+## Configuration Splitting
+
+When a test project grows to dozens or even hundreds of test cases, a single config file becomes hard to maintain. The configuration splitting mechanism lets you break a large file into multiple sub-files by module/feature and assemble them via `import` references, which are merged at load time automatically.
+
+### Main Configuration File
+
+In the main config file, reference sub-files via the `"import"` field. `import` is a special element in the `test_cases` array; the framework **expands and replaces** it with the sub-file's test cases at load time:
+
+```json
+{
+    "setup": {
+        "environment_variables": {
+            "PYTHONPATH": "./src"
+        }
+    },
+    "test_cases": [
+        {
+            "name": "Inline Test Case",
+            "execution": {
+                "command": "echo",
+                "args": ["hello"]
+            },
+            "expected": { "return_code": 0 }
+        },
+        { "import": "cases/text_tests.json", "tags": ["text"] },
+        { "import": "cases/json_tests.yaml" },
+        { "import": "cases/h5_tests.json", "tags": ["h5", "fast"] }
+    ]
+}
+```
+
+> **Note**: `import` paths are resolved relative to the **directory of the main config file**, not the current working directory (cwd). This ensures portability — split relationships are unaffected regardless of which directory tests are run from.
+
+### Sub-File Format
+
+Sub-files have the same structure as the main file, with a top-level `test_cases` array (and optional `setup`):
+
+```json
+{
+    "test_cases": [
+        {
+            "name": "text_identical",
+            "execution": {
+                "command": "python",
+                "args": ["./compare_text.py"]
+            },
+            "expected": { "return_code": 0 },
+            "tags": ["text"]
+        },
+        {
+            "name": "text_diff",
+            "execution": {
+                "command": "python",
+                "args": ["./compare_text.py", "--mode", "diff"]
+            },
+            "expected": { "return_code": 1 },
+            "tags": ["text"]
+        }
+    ]
+}
+```
+
+### Import-Level Tags
+
+When all cases in a sub-file share the same tags (e.g., `"text"`), there is no need to repeat `tags` in every case. Simply add `tags` to the `import` entry, and the framework automatically injects them into every case imported from that file:
+
+```json
+{ "import": "cases/text_tests.json", "tags": ["text", "fast"] }
+```
+
+**Merge Rules**:
+
+| Scenario | Result |
+|---|---|
+| import has tags, sub-case has none | Sub-case inherits all import tags |
+| import has tags, sub-case also has tags | Merged and deduplicated; import tags first, sub-case's own tags after |
+| import has no tags | Behavior unchanged, backward compatible |
+
+> Nested imports (sub-files that further import other files) also follow this rule — outer import tags are injected into **all** recursively expanded cases.
+
+### How It Works
+
+1. **Expanded at load time**: The Runner automatically expands imports after reading the config file and before parsing `TestCase` objects. Completely transparent to the Runner and execution engine — no changes to test cases or Runner code needed.
+2. **Recursive expansion**: Sub-files can continue to `import` other files, supporting multiple nesting levels.
+3. **Circular reference protection**: The framework maintains a set of loaded file paths and raises a clear error when circular references are detected.
+4. **Backward compatible**: Config files without `import` fields behave exactly as before — zero migration cost.
+
+### Cross-Format Support
+
+A JSON main config can import YAML sub-files, and vice versa. The framework auto-selects the parser based on the sub-file extension (`.json` / `.yaml` / `.yml`).
+
+### Setup Merge Rules
+
+If both the main file and sub-file define `setup`, they are deep-merged:
+- **Same-name variable conflicts**: Sub-file `setup` overrides the main file's same-name fields.
+- **Environment variables**: Merged into one dict, with sub-file taking priority.
+
+```json
+// Main file setup
+{ "environment_variables": { "BASE": "from_main", "OVERRIDE": "from_main" } }
+
+// Sub-file setup
+{ "environment_variables": { "SUB_KEY": "from_sub", "OVERRIDE": "from_sub" } }
+
+// Merged result
+{ "environment_variables": {
+    "BASE": "from_main",
+    "SUB_KEY": "from_sub",
+    "OVERRIDE": "from_sub"  // sub-file overrides
+} }
+```
+
+### Incremental Migration
+
+No need to migrate everything at once:
+1. Run `validate` to confirm existing configs are correct (see [Configuration Validation](#configuration-validation))
+2. Gradually move parts of a large file into sub-files and reference them with `import`
+3. Inline cases and `import` references can coexist in the same `test_cases` array
+
+## Configuration Inheritance
+
+When many test cases are structurally similar (differing only in paths, parameters, etc.), use `extends` + `abstract` + `variables` to eliminate duplicate configuration.
+
+### Syntax
+
+Test cases support three new inheritance-related fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `abstract` | `boolean` | When `true`, acts as a template (base class) and is not executed |
+| `extends` | `string` | Name of the base test case to inherit from; supports chained inheritance |
+| `variables` | `object` | Case-level placeholder variables for `{key}` substitution |
+
+### Basic Usage
+
+```json
+{
+  "test_cases": [
+    {
+      "name": "_base_echo",
+      "abstract": true,
+      "execution": {
+        "command": "echo",
+        "args": ["{msg}"]
+      },
+      "expected": {
+        "output_contains": ["{msg}"]
+      },
+      "variables": {
+        "msg": "hello"
+      }
+    },
+    {
+      "name": "test_hello",
+      "extends": "_base_echo"
+    },
+    {
+      "name": "test_world",
+      "extends": "_base_echo",
+      "variables": {
+        "msg": "world"
+      }
+    }
+  ]
+}
+```
+
+When expanded, `test_hello` inherits all fields from the base (`execution.command`, `execution.args`, `expected`), and the placeholder `{msg}` is replaced by `variables.msg` → `"hello"`. `test_world` overrides `variables.msg` to `"world"`.
+
+### Merge Rules
+
+Inheritance uses a **deep merge for dicts, full replacement for lists** strategy:
+
+- **dict fields** (e.g., `expected`, `variables`): Recursively merged; subclass fields override parent's same-name keys
+- **list fields** (e.g., `args`, `steps`, `tags`): Subclass replaces parent's entire list; no appending
+
+```json
+{
+  "name": "_base",
+  "abstract": true,
+  "expected": {
+    "return_code": 0,
+    "output_contains": ["base"]
+  },
+  "tags": ["a", "b"],
+  "extends": "_base",
+  "expected": {
+    "output_contains": ["child"]
+  },
+  "tags": ["c"]
+}
+```
+
+Merged result: `expected.return_code` = `0` (from parent), `expected.output_contains` = `["child"]` (subclass replaces entire list), `tags` = `["c"]` (entire list replaced).
+
+The `abstract` field takes the subclass's own value (default `false`) and is **not inherited** from the parent, preventing subclasses from accidentally becoming abstract templates.
+
+### Chained Inheritance
+
+Multi-level inheritance is supported (A → B → C):
+
+```json
+{
+  "name": "_A", "abstract": true,
+  "execution": { "command": "python", "args": ["-c"] }, "expected": {},
+  "variables": {"a": "1"}
+}
+{
+  "name": "_B", "abstract": true, "extends": "_A",
+  "expected": {"output_contains": ["b"]},
+  "variables": {"b": "2"}
+}
+{
+  "name": "C", "extends": "_B",
+  "variables": {"c": "3"},
+  "execution": { "args": ["print('{a} {b} {c}')"] }
+}
+```
+
+Circular inheritance is automatically detected at load time and reported as an error.
+
+### Variable Substitution Priority
+
+Placeholder substitution has two layers:
+
+1. **Case-level `variables`**: Deep-merged from the inheritance chain (subclass overrides parent), applied first to the merged case content
+2. **Global `--var`**: Passed via CLI (`--var KEY=VALUE`), applied after case-level variables; **global takes priority when keys conflict**
+
+```bash
+symtest run config.json --var solver=/path/to/solver
+```
+
+The `setup` block uses only global `--var` substitution (no case-level variables).
+
+### validate Checks
+
+`symtest validate` performs additional checks on inherited configurations:
+
+- Whether the `extends` target exists
+- Whether a circular inheritance chain exists
+- `abstract` cases are not counted as executable
+- `extends` cases skip required-field checks (content comes from parent)
+
+## Configuration Validation
+
+The `validate` command checks configuration file correctness without running tests, suitable for CI pipeline config validation.
+
+### Usage
+
+```bash
+# Validate a single config file
+symtest validate test_cases.json
+
+# Validate a main config with imports (auto-expands and checks all sub-files)
+symtest validate main_config.json
+
+# Specify working directory
+symtest validate test_cases.json --workspace /path/to/project
+
+# Output JSON format (for AI/script parsing)
+symtest validate test_cases.json --output-format json
+```
+
+### What Gets Checked
+
+| Check | Description |
+|---|---|
+| Syntax correctness | Whether JSON/YAML is valid (implicitly checked on load) |
+| Required fields | Whether each case has `name`, `execution.command`, `execution.args`, `expected` (each step in sequence mode) |
+| Import references | Whether referenced sub-files exist |
+| Circular references | Whether an A→B→A cycle exists in the import chain |
+
+### Output Examples
+
+On success:
+```
+  [OK] Loaded 15 test cases from 3 file(s)
+  [OK] All required fields present
+  [OK] No circular imports detected
+
+  Files:
+    - /project/main_config.json
+    - /project/cases/text_tests.json
+    - /project/cases/json_tests.yaml
+```
+
+On error:
+```
+  [OK] Loaded 3 test cases from 1 file(s)
+  [FAIL] case 'bad_case': missing required field 'expected'
+  [FAIL] Import target not found: /project/cases/nonexistent.json
+```
+
+## Cross-File Case Search (find)
+
+When a large project splits cases across many JSON/YAML sub-configurations,
+locating cases and reviewing scenario coverage across files becomes difficult.
+`symtest find` automatically expands all `import` references of the main
+config and searches over the unified, expanded case set — a lightweight,
+scriptable way to locate cases.
+
+### Usage
+
+```bash
+# Default substring mode (case-insensitive); matches name/command/args/tags/description
+symtest find main_config.json "login"
+
+# Regex mode
+symtest find main_config.json "log.*in" --mode regex
+
+# Fuzzy mode (tolerates typos and abbreviations, ranked by relevance)
+symtest find main_config.json "lgin" --mode fuzzy
+
+# Combined with tag filtering (repeatable, OR relationship)
+symtest find main_config.json "login" --tag smoke
+
+# JSON output (for AI/scripts)
+symtest find main_config.json "login" --output-format json
+```
+
+Omitting the pattern lists all cases. Text output columns: index, name,
+command, tags, timeout, mode (`single` / `steps`).
+
+Exit codes follow grep semantics: 0 = match found, 1 = no match,
+2 = config loading error — convenient for scripting.
+
+## Running Tests
+
+### Command Line
+
+```bash
+# Run JSON tests
+symtest run test_cases.json
+
+# Run YAML tests
+symtest run test_cases.yaml
+
+# Run a main config with import splitting (auto-expands sub-files)
+symtest run main_config.json
+
+# Specify working directory
+symtest run test_cases.json --workspace /path/to/project
+
+# Run in parallel
+symtest run test_cases.json --parallel --workers 4
+
+# Specify parallel mode
+symtest run test_cases.json --parallel --execution-mode process
+
+# Run only specified cases
+symtest run test_cases.json -t test_name_1 -t test_name_2
+
+# Filter by tag
+symtest run test_cases.json --tag smoke
+symtest run test_cases.json --tag smoke --tag regression
+
+# Filter by name and tag simultaneously (AND relationship)
+symtest run test_cases.json -t test_name_1 --tag smoke
+
+# Verbose output
+symtest run test_cases.json --verbose
+
+# Debug mode
+symtest run test_cases.json --debug
+
+# Output format
+symtest run test_cases.json --output-format json|html|text
+
+# Enable history (smart scheduling + regression detection)
+symtest run test_cases.json --history-dir ./hist
+
+# Custom regression threshold (default 1.5x)
+symtest run test_cases.json --history-dir ./hist --regression-threshold 2.0
+
+# Output JUnit XML report (consumable by Jenkins/GitLab CI etc.)
+symtest run test_cases.json --junit-xml report.xml
+
+# Run only last-failed cases (overwritten on each run)
+symtest run test_cases.json --last-failed
+
+# Resume: skip passed steps, continue from failed step
+symtest run test_cases.json --resume
+symtest run test_cases.json --resume -t long_pipeline
+
+# Update baseline files on comparison failure (type yes interactively)
+symtest run test_cases.json --update-baseline
+
+# Non-interactive environments must confirm explicitly
+symtest run test_cases.json --update-baseline --yes
+
+# Enable error analysis (full stats output for numerical comparisons)
+symtest run test_cases.json --error-analysis
+```
+
+### Run Only Last-Failed Cases (--last-failed)
+
+`--last-failed` automatically filters to cases that **truly failed** in the previous run (`failed`, `timeout`, and `xpassed`). Ideal for AI iterative fixing scenarios: after fixing one round of code, only verify the previously failed cases without a full rerun (a full FEM run could take hours).
+
+**xfail semantics**: Cases marked `expected_failure` that fail (`xfailed`) are _expected behavior_ and are **not** selected by `--last-failed` for rerun. However, if an xfail-marked case unexpectedly passes (`xpassed`), it is treated as a true failure and **is** selected.
+
+**How it works**:
+- After each run, the framework records each case's status in `<workspace>/.symtest/last_run.json`
+- Recording uses **overwrite-update**: cases run this time get new results overwriting old ones; un-run cases retain their previous status
+- This means a fixed case won't show as "failed" in the next display
+- If the file doesn't exist (first run), `--last-failed` warns and runs all cases normally
+
+```bash
+# First run: all 10 cases, 3 fail
+symtest run config.json
+
+# After fixing code, rerun only those 3 failures
+symtest run config.json --last-failed
+
+# If all 3 pass, run once more to confirm no regressions
+symtest run config.json
+```
+
+**Interaction with `-t`**: `--last-failed` and `-t`/`--tag` can be used together; effects stack (AND relationship).
+
+### Resume (--resume)
+
+`--resume` is for **sequential step tests (sequence)**. It skips steps that passed in the previous run and continues directly from the failed step. Ideal for long-running multi-step cases — for example, in an FEM analysis where steps 1-3 passed (each taking tens of seconds or minutes), only step 4's assertion failed. `--resume` skips 1-3 and reruns only step 4.
+
+**How it works**:
+- After each step passes, the framework records step status in `<workspace>/.symtest/sequence_state/<case_name>.json` and caches output to the `cache/` subdirectory
+- On the next `--resume`, a config hash (SHA256 of every step's command/args/expected/timeout/retry_count plus case-level expected) is computed and compared against saved state
+- Hash match → skip passed steps, rebuild `combined_output` from cache (so case-level `expected` assertions run correctly)
+- All steps pass → state file and cache automatically deleted to avoid stale data affecting subsequent runs
+- Hash mismatch (config changed) → full rerun automatically, old state discarded
+
+**Trust model**: `--resume` does **not verify workspace artifacts** (input files, files generated by prior steps, etc.). Using `--resume` means the user confirms input files are unmodified. If workspace contamination is suspected, rerun fully without `--resume`.
+
+```bash
+# First full run, long_pipeline step 4 fails (total 72s)
+symtest run config.json
+
+# After fixing, rerun only long_pipeline, skipping steps 1-3 (~0.14s only)
+symtest run config.json -t long_pipeline --resume
+
+# After all pass, do one full run to confirm no regressions
+symtest run config.json
+```
+
+**Interaction with `-t`**: `--resume` is typically used with `-t` to first isolate a single failed case then resume from it. Without `-t`, all sequence cases with existing state will attempt to resume.
+
+**Limitations**:
+- Only applies to sequential step cases (`steps` mode); single-command mode ignored
+- The state file's config hash is invalidated by any change to a step's command/args/expected/timeout/retry_count or case-level expected
+- Cached output is primarily for rebuilding `combined_output`; the `output` field in the report still contains only the failed step's output
+
+### Auto-Update Baseline Files (--update-baseline)
+
+After algorithm improvements or parameter adjustments, you may expect output to change (and the new results to be more correct). `--update-baseline` automatically overwrites baseline files with actual output, avoiding manual copy-paste.
+
+```bash
+# Interactive runs ask you to type yes before execution
+symtest run config.json --update-baseline
+
+# Explicit confirmation for automation or CI
+symtest run config.json --update-baseline --yes
+```
+
+**Behavior**:
+- Interactive runs start only after the user types the full word `yes`
+- Non-interactive runs do not wait for input and require `--yes`
+- When file comparison fails, the `actual` file is copied to the `baseline` path
+- That assertion is treated as **passed**; the case status is `passed`
+- The report shows a `Baseline Updated` count and lists updated files
+- Both text and JSON reports list all updated baseline paths
+
+> **Note**: Confirmation happens before test execution, while the files to update are only known after comparison. Keep baselines under version control and review the report's `Baseline Updated` list. Passing `update_baseline=True` through the Python API is treated as explicit confirmation by the caller.
+
+### Configuration Validation JSON Output
+
+The `validate` command has a `--output-format json` option that produces machine-readable JSON reports, suitable for AI/script-based config validation:
+
+```bash
+symtest validate config.json --output-format json
+```
+
+Output example:
+```json
+{
+  "valid": false,
+  "errors": ["[main_config.json] case 'bad_case': missing required field 'expected'"],
+  "summary": {"files": 1, "cases": 3, "files_loaded": ["/project/main_config.json"]}
+}
+```
+
+### Python API
+
+```python
+from symtest.runners import JSONRunner, YAMLRunner, ParallelJSONRunner
+
+# Sequential run
+runner = JSONRunner(
+    config_file="test_cases.json",
+    workspace="/path/to/project",    # Optional, defaults to project root
+    test_case_filter=["test_1"],     # Optional, run only specified cases
+    test_case_tag_filter=["smoke"],  # Optional, run only cases with specified tags
+    history_dir="./hist",            # Optional, enable history & regression detection
+    regression_threshold=2.0,        # Optional, regression threshold multiplier, default 1.5
+    update_baseline=False,           # Optional, auto-update baseline on comparison failure, default False
+    last_failed=False,               # Optional, run only last-failed cases, default False
+    resume=False,                    # Optional, resume sequence cases from last failed step, default False
+)
+success = runner.run_tests()
+
+# YAML format
+runner = YAMLRunner(config_file="test_cases.yaml")
+
+# Parallel run (JSON)
+runner = ParallelJSONRunner(
+    config_file="test_cases.json",
+    max_workers=4,                   # Optional, defaults to CPU core count
+    execution_mode="thread",         # "thread" or "process"
+    test_case_filter=["test_1"],
+    history_dir="./hist",            # Optional, enable history & smart scheduling
+    regression_threshold=2.0,        # Optional, regression threshold multiplier, default 1.5
+    update_baseline=False,           # Optional
+    last_failed=False,               # Optional
+    resume=False,                    # Optional, resume sequence cases
+)
+success = runner.run_tests()
+
+# Parallel run (YAML)
+from symtest.runners import ParallelYAMLRunner
+runner = ParallelYAMLRunner(
+    config_file="test_cases.yaml",
+    max_workers=4,
+    execution_mode="thread",
+)
+success = runner.run_tests()
+```
+
+### Getting Results
+
+```python
+runner.run_tests()
+
+# Summary
+runner.results["total"]
+runner.results["passed"]
+runner.results["failed"]
+runner.results["xfailed"]      # Expected failure (no exit code impact)
+runner.results["xpassed"]      # Unexpected pass (counted as failure)
+runner.results["updated"]      # Number of baseline files updated by --update-baseline
+
+# Details — each result dict contains the following fields
+for detail in runner.results["details"]:
+    print(detail["name"])                     # Case name
+    print(detail["status"])                   # "passed" / "failed" / "xfailed" / "xpassed" / "timeout"
+    print(detail.get("message", ""))          # Failure reason
+    print(detail.get("duration"))             # Duration (seconds)
+    print(detail.get("xfail_reason", ""))     # xfail reason (only for xfailed/xpassed status)
+    print(detail.get("expected"))             # Expected assertions (registered acceptance criteria)
+    print(detail.get("description"))          # Case description
+    print(detail.get("tags"))                 # Tag list
+    print(detail.get("failure_kind"))         # Failure type: return_code/output_contains/
+                                              #   output_matches/file_compare/timeout/
+                                              #   execution_error
+    print(detail.get("attempts", 1))          # Number of attempts (including retries)
+    print(detail.get("flaky", False))         # Whether it passed only after retry
+    print(detail.get("attempt_history", []))  # Status history for each attempt
+    print(detail.get("failed_step"))          # Failed step number in step sequence
+    print(detail.get("step_results", []))     # Detailed results for each step
+    print(detail.get("compare_failures", [])) # Structured file comparison failure details
+    print(detail.get("baseline_updated", [])) # List of updated baseline file paths
+```
+
+**Key Result Dictionary Fields**:
+
+| Field | Type | Description |
+|---|---|---|
+| `status` | str | One of five states: `passed`, `failed`, `xfailed` (expected failure), `xpassed` (unexpected pass), `timeout` |
+| `xfail_reason` | str | xfail reason text (from `xfail_reason` in config); only present for `xfailed`/`xpassed` status |
+| `expected` | dict | Registered expected assertions (return_code, output_contains, compare_files, etc.) for reviewing acceptance criteria |
+| `description` | str | Test case description text |
+| `failure_kind` | str | Failure type enum; AI/scripts can choose repair strategies accordingly |
+| `attempts` | int | Total attempts (including retries); `1` means passed on first try |
+| `flaky` | bool | `true` if the case passed only after retry |
+| `attempt_history` | list | Per-attempt `{attempt, status, message, duration}` |
+| `step_results` | list | Per-step `{step, name, status, message, duration, command}` |
+| `compare_failures` | list | Structured info for each failed file comparison (includes `diff_summary`, `differences`, `error_stats`, `actual`/`baseline` paths, tolerance params) |
+| `baseline_updated` | list | Paths of baseline files overwritten by `--update-baseline` |
+
+## Project Entry Script
+
+If your test project has a complex structure (requiring preset environment variables, customized report paths, etc.), using `symtest run` directly may not be flexible enough. You can create a project entry script (e.g., `test.py` or `run_tests.py`) that calls the framework API from Python code.
+
+### When to Use CLI Directly
+
+| Scenario | Recommendation |
+|---|---|
+| Simple project, single config file | `symtest run config.json --workers 4` |
+| One-off run, no special environment needs | `symtest run config.yaml --tag smoke` |
+| CI pipeline | `symtest run config.json --junit-xml report.xml` |
+
+### When to Wrap in an Entry Script
+
+| Scenario | Recommendation |
+|---|---|
+| Need to set environment variables (e.g., inject venv PATH) | Entry script |
+| Need to output multiple report formats simultaneously (text + JUnit XML) | Entry script |
+| Team-shared fixed run parameters (workers, history-dir, etc.) | Entry script |
+| Need to auto-select JSON/YAML runner by config file extension | Entry script |
+| Windows console-script commands (e.g., `compare-files`) not found | Entry script (inject venv Scripts into PATH) |
+
+### Entry Script Example
+
+The framework provides an out-of-the-box example script `examples/full_runner_example.py`. Copy it to your project root and use it directly or customize as needed. It supports all the following CLI parameters:
+
+| Parameter | Description |
+|---|---|
+| `config` (positional) | Test config file path (auto-detects .json / .yaml) |
+| `--test-target` / `-t` | Filter cases by name |
+| `--tag` | Filter cases by tag (OR relationship) |
+| `--last-failed` | Run only last-failed cases |
+| `--resume` | Resume sequence cases from last failed step |
+| `--update-baseline` | Update baselines on comparison failure; requires interactive confirmation |
+| `--yes` / `-y` | Skip the baseline confirmation for automation or CI |
+| `--junit-xml` | JUnit XML report output path |
+| `--report` | Text report output path, default `test_report.txt` |
+| `--workers` / `-w` | Number of parallel workers, default 4 |
+| `--execution-mode` | thread or process |
+| `--workspace` | Working directory, defaults to script directory |
+| `--var` | Template variable substitution, format `KEY=VALUE` |
+| `--verbose` / `-v` | Verbose output (DEBUG-level logging) |
+
+### Quick Start
+
+1. Copy `examples/full_runner_example.py` to your project root, rename to `run_tests.py`
+2. If you use a virtual environment and need console-script commands, uncomment the venv PATH injection code in the file
+3. Adjust default parameters for your team's preference (e.g., `--workers` default value, `--history-dir` default path)
+4. Run tests:
+
+```bash
+# Full run
+python run_tests.py test_cases.json --workers 4
+
+# Only last-failed cases
+python run_tests.py test_cases.json --last-failed
+
+# CI with JUnit report
+python run_tests.py test_cases.json --junit-xml report.xml
+```
+
+### Windows WinError 2 Issue
+
+If your test case `command` field references console-script commands (e.g., `compare-files`, `symtest` — entry points installed via pip), running the script via double-click or from an unactivated environment on Windows may cause subprocesses to fail finding these executables:
+
+```
+FileNotFoundError: [WinError 2] The system cannot find the file specified.
+```
+
+This is because these commands exist as `.exe` wrappers in `venv/Scripts/` and that directory is not in the subprocess PATH.
+
+**Solution**: At the very top of your entry script (beginning of `main()` or at file level), prepend the venv `Scripts` directory to the `PATH` environment variable:
+
+```python
+import os
+
+venv_scripts = os.path.abspath(os.path.join(
+    os.path.dirname(__file__), "..", ".venv", "Scripts"))
+if os.path.isdir(venv_scripts):
+    os.environ["PATH"] = venv_scripts + os.pathsep + os.environ.get("PATH", "")
+```
+
+This code is already included in the example script `examples/full_runner_example.py` (commented out by default). Uncomment and adjust the path as needed.
+
+## Placeholders (Variable Substitution)
+
+When the same config file needs different parameters in different environments (e.g., solver path, model file path, etc.), use `{variable_name}` placeholders in the config and pass actual values via `--var` or `variables` at runtime.
+
+### Writing Configs with Placeholders
+
+JSON:
+
+```json
+{
+    "test_cases": [
+        {
+            "name": "Solver Test",
+            "execution": {
+                "command": "{solver}",
+                "args": ["--input", "{model}", "--output", "{output}"]
+            },
+            "expected": { "return_code": 0 }
+        }
+    ]
+}
+```
+
+YAML:
+
+```yaml
+test_cases:
+  - name: Solver Test
+    execution:
+      command: "{solver}"
+      args: ["--input", "{model}", "--output", "{output}"]
+    expected:
+      return_code: 0
+```
+
+Placeholders `{variable_name}` can appear in any string value in the config file, including `command`, `args`, `name`, `expected.output_contains`, etc. Multiple placeholders in the same string are supported, e.g., `"{solver} --input {model}"`.
+
+> **Safety design**: Only keys present in the `variables` dictionary are replaced. Unmatched `{xxx}` is left as-is without error. Therefore, regex patterns in `expected.output_matches` (like `{2,}`, `\d{4}`) are unaffected.
+
+### Usage
+
+#### CLI
+
+```bash
+# Single variable
+symtest run test_cases.json --var solver=/opt/solver/bin/solver.exe
+
+# Multiple variables
+symtest run test_cases.json --var solver=/opt/solver/bin/solver.exe --var model=./data/model.dat
+
+# Combined with parallel mode, tag filtering, etc.
+symtest run test_cases.json --var solver=solver.exe --parallel --workers 4 --tag smoke
+```
+
+`--var` format is `KEY=VALUE`, usable multiple times. Separated by `=`; whitespace around key and value is auto-trimmed.
+
+#### Python API
+
+```python
+from symtest.runners import JSONRunner, YAMLRunner, ParallelJSONRunner, ParallelYAMLRunner
+
+# Sequential run
+runner = JSONRunner(
+    config_file="test_cases.json",
+    variables={
+        "solver": "/opt/solver/bin/solver.exe",
+        "model": "./data/model.dat",
+        "output": "./results/output.dat",
+    },
+)
+success = runner.run_tests()
+
+# Parallel run
+runner = ParallelJSONRunner(
+    config_file="test_cases.json",
+    variables={"solver": "/opt/solver/bin/solver.exe"},
+)
+success = runner.run_tests()
+
+# YAML also supported
+runner = YAMLRunner(
+    config_file="test_cases.yaml",
+    variables={"solver": "/opt/solver/bin/solver.exe"},
+)
+success = runner.run_tests()
+```
+
+### Use Cases
+
+| Scenario | Example |
+|---|---|
+| Different solver versions | `--var solver=v1.0/solver.exe` vs `--var solver=v2.0/solver.exe` |
+| Different input data | `--var model=case_1.dat` vs `--var model=case_2.dat` |
+| CI/CD environment adaptation | Local `/opt/solver.exe`, CI `/runner/solver.exe` |
+| Cross-platform paths | Windows `--var solver=C:\solver.exe`, Linux `--var solver=/opt/solver.exe` |
+
+## Tag Filtering
+
+Tags allow classifying test cases and batch-filtering them at runtime. Tag filtering and name filtering can be used simultaneously (AND relationship — both conditions must be met).
+
+### Defining Tags in Test Cases
+
+JSON:
+
+```json
+{
+    "test_cases": [
+        {
+            "name": "Quick Test",
+            "execution": {
+                "command": "echo",
+                "args": ["hello"]
+            },
+            "tags": ["smoke", "fast"],
+            "expected": { "return_code": 0 }
+        },
+        {
+            "name": "Full Regression Test",
+            "execution": {
+                "command": "python",
+                "args": ["long_test.py"]
+            },
+            "tags": ["regression", "slow"],
+            "expected": { "return_code": 0 }
+        }
+    ]
+}
+```
+
+YAML:
+
+```yaml
+test_cases:
+  - name: Quick Test
+    execution:
+      command: echo
+      args: ["hello"]
+    tags: ["smoke", "fast"]
+    expected:
+      return_code: 0
+```
+
+`tags` is optional; defaults to an empty list if not specified. Each case can have multiple tags.
+
+### Runtime Filtering
+
+```bash
+# Run only cases with the "smoke" tag
+symtest run test_cases.json --tag smoke
+
+# Run cases with "smoke" or "regression" tags (OR relationship)
+symtest run test_cases.json --tag smoke --tag regression
+
+# Combine name and tag filtering (AND relationship)
+symtest run test_cases.json -t alpha --tag fast
+```
+
+### Python API
+
+```python
+runner = JSONRunner(
+    config_file="test_cases.json",
+    test_case_tag_filter=["smoke"],     # Run only cases with the smoke tag
+)
+success = runner.run_tests()
+
+# Combine with name filtering
+runner = JSONRunner(
+    config_file="test_cases.json",
+    test_case_filter=["alpha", "beta"],
+    test_case_tag_filter=["fast"],
+)
+success = runner.run_tests()
+```
+
+## Setup Module
+
+The Setup module performs initialization before tests and cleanup after tests.
+
+### Environment Variables (Config File Approach)
+
+JSON:
+
+```json
+{
+    "setup": {
+        "environment_variables": {
+            "TEST_ENV": "development",
+            "API_URL": "http://localhost:8080"
+        }
+    },
+    "test_cases": [...]
+}
+```
+
+YAML:
+
+```yaml
+setup:
+  environment_variables:
+    TEST_ENV: "development"
+    API_URL: "http://localhost:8080"
+test_cases:
+  [...]
+```
+
+Environment variables in the config file are set before tests and restored to their original values after tests.
+
+### Custom Setup Plugin
+
+```python
+from symtest import BaseSetup, JSONRunner
+
+class DatabaseSetup(BaseSetup):
+    def setup(self):
+        # Initialization operations
+        pass
+
+    def teardown(self):
+        # Cleanup operations (executed even if tests fail)
+        pass
+
+runner = JSONRunner("test_cases.json")
+runner.setup_manager.add_setup(DatabaseSetup({"connection": "test_db"}))
+success = runner.run_tests()
+```
+
+Multiple plugins execute `setup()` in addition order and `teardown()` in reverse order.
+
+### Execution Order
+
+1. Load setup configuration from config file (environment variables, etc.)
+2. Execute `setup()` for all setup plugins (in addition order)
+3. Run tests
+4. Execute `teardown()` for all setup plugins (in reverse order, guaranteed to execute)
+
+## Parallel Testing
+
+```python
+from symtest.runners import ParallelJSONRunner
+
+runner = ParallelJSONRunner(
+    config_file="test_cases.json",
+    max_workers=4,                # Maximum concurrency, defaults to CPU core count
+    execution_mode="thread"       # "thread" or "process"
+)
+success = runner.run_tests()
+
+# Fallback to sequential execution
+runner.run_tests_sequential()
+```
+
+**Thread mode**: Shared memory, supports resource-aware scheduling (see next section).  
+**Process mode**: Process isolation, does not support resource scheduling.
+
+## Sequential Step Testing
+
+A test case can contain multiple ordered steps. If any step fails, subsequent steps are skipped (fail-fast).
+
+### JSON
+
+```json
+{
+    "test_cases": [
+        {
+            "name": "Multi-step Test",
+            "execution": {
+                "steps": [
+                    {
+                        "command": "echo",
+                        "args": ["step1"],
+                        "expected": { "return_code": 0 }
+                    },
+                    {
+                        "command": "echo",
+                        "args": ["step2"],
+                        "expected": { "return_code": 0 },
+                        "retry_count": 2
+                    }
+                ]
+            }
+        }
+    ]
+}
+```
+
+### YAML
+
+```yaml
+test_cases:
+  - name: Multi-step Test
+    execution:
+      steps:
+        - command: echo
+          args: ["step1"]
+          expected:
+            return_code: 0
+        - command: echo
+          args: ["step2"]
+          expected:
+            return_code: 0
+```
+
+Each step supports `command`, `args`, `expected`, `timeout`, and `retry_count` fields.
+
+**Failure output trimming**: When a step fails in the sequence, the `output` field in the result dictionary **contains only the failed step's output** — not the concatenated output of all prior successful steps. This significantly reduces failure report size, ideal for AI quick diagnosis of failed steps.
+
+**Step details**: View each step's individual status via `detail["step_results"]` (even if all passed), making it easy to understand the entire sequence's execution flow.
+
+**Failure marking**: On failure, the `failed_step` field indicates the failed step number, e.g., "Failed at step 2/3".
+
+**Resume**: After a sequence case fails, use `--resume` to skip already-passed steps and continue from the failed step, dramatically reducing iteration cost for long-running cases. See [Resume](#resume---resume) for details.
+
+### Case-Level expected (Sequential Steps)
+
+After all steps have passed, you can define additional case-level `expected` assertions to perform unified validation (e.g., file comparison) on files produced by all steps. The case-level `expected` field format is identical to single-command mode, supporting `return_code`, `output_contains`, `output_matches`, and `compare_files`.
+
+```json
+{
+    "name": "Multi-step + File Comparison",
+    "execution": {
+        "steps": [
+            {
+                "command": "python",
+                "args": ["./generate.py", "output.csv"],
+                "expected": { "return_code": 0 }
+            },
+            {
+                "command": "python",
+                "args": ["./process.py", "output.csv"],
+                "expected": { "return_code": 0, "output_contains": ["Done"] }
+            }
+        ]
+    },
+    "expected": {
+        "compare_files": [
+            {
+                "actual": "output.csv",
+                "baseline": "baseline/output.csv",
+                "type": "csv",
+                "rtol": 0.02,
+                "start_line": 93,
+                "end_line": 99
+            }
+        ]
+    }
+}
+```
+
+> **Note**: Case-level `expected` only runs after all steps pass. If any step fails, case-level assertions are not executed. When a case-level assertion fails, the error message includes a "Case-level assertion failed" prefix to distinguish it.
+
+## Resource-Aware Scheduling
+
+Only effective in thread mode. Configured via the `scheduling.resources` field; the framework automatically manages CPU core allocation.
+
+```json
+{
+    "name": "Heavy_Simulation",
+    "execution": {
+        "command": "solver",
+        "args": ["-i", "input.dat"],
+        "timeout": 36000
+    },
+    "scheduling": {
+        "resources": {
+            "cpu_cores": 4,
+            "estimated_time": 18000,
+            "min_memory_mb": 16000,
+            "priority": 10
+        }
+    },
+    "expected": { "return_code": 0 }
+}
+```
+
+| Field | Description |
+|---|---|
+| `cpu_cores` | Required CPU core count, default 1. The framework uses semaphores to control allocation; tasks exceeding the limit wait in queue |
+| `estimated_time` | Estimated duration (seconds), used for LPT scheduling (long tasks start first) |
+| `min_memory_mb` | Estimated memory (MB), currently used for log warnings only |
+| `priority` | Priority 0-10, currently used for informational labeling only |
+
+Framework behavior:
+- Automatically detects CPU core count, reserving 2 cores for the system
+- Automatically injects `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `NPROC` environment variables when a task starts, preventing solver thread runaway
+- Schedules by `estimated_time` in descending order (LPT strategy); if `--history-dir` is enabled, prefers historical `avg_duration` for ordering
+
+## History & Regression Detection
+
+Use `--history-dir` to specify a directory where the framework maintains a `.symtest` file recording each case's historical run times.
+
+### How It Works
+
+1. **First run**: No `.symtest` in the directory; an empty file is auto-created; ordering still uses `estimated_time` from the config
+2. **Subsequent runs**: Reads historical data from `.symtest`, preferring `avg_duration` for scheduling order
+3. **Regression detection**: After each run, if any case's duration exceeds the historical average by the threshold multiplier (default 1.5), a warning is printed
+
+### CLI Usage
+
+```bash
+# Enable history
+symtest run test_cases.json --history-dir ./hist
+
+# Custom regression threshold (warn only if 2x the average)
+symtest run test_cases.json --history-dir ./hist --regression-threshold 2.0
+```
+
+### Python API
+
+```python
+from symtest.runners import JSONRunner, ParallelJSONRunner
+
+# Sequential run + history
+runner = JSONRunner(
+    config_file="test_cases.json",
+    history_dir="./hist",
+    regression_threshold=2.0,  # Optional, default 1.5
+)
+success = runner.run_tests()
+
+# Parallel run + history (scheduling also uses historical data)
+runner = ParallelJSONRunner(
+    config_file="test_cases.json",
+    history_dir="./hist",
+)
+success = runner.run_tests()
+```
+
+### .symtest File Format
+
+```json
+{
+  "version": 1,
+  "cases": {
+    "case_name_1": {
+      "avg_duration": 3.5,
+      "last_duration": 3.2,
+      "run_count": 5
+    }
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `avg_duration` | Cumulative average duration (seconds), used for scheduling and regression baseline |
+| `last_duration` | Most recent run duration |
+| `run_count` | Historical run count |
+
+### Regression Warning Example
+
+When a case's runtime exceeds the historical average by the threshold multiplier:
+
+```
+⚠ WARNING: Case 'heavy_simulation' regressed: 18.2s vs avg 10.5s (1.73x slower)
+```
+
+### Without History
+
+When `--history-dir` is not provided, behavior is identical to before — no extra files are created.
+
+### Reset History (--update-history)
+
+When algorithm refactoring or environment changes make historical duration data no longer representative, `--update-history` clears the history entries for the cases involved in this run from `.symtest`, making this run the new baseline for regression detection.
+
+```bash
+# Clear history and make this run the new baseline (requires --history-dir)
+symtest run config.json --history-dir ./hist --update-history
+```
+
+**Behavior**:
+- Clears the history entries in `.symtest` for **the cases involved in this run**
+- History data for cases not in this run is preserved
+- No false positives from regression detection in this run (no historical baseline for comparison)
+- The durations of passing cases in this run are recorded as a fresh starting point
+- The report shows a `History Reset` count
+
+> **Note**: Must be used with `--history-dir`. Reset scope is limited to the cases run this time; other cases' history data is unaffected.
+
+## JUnit XML Report
+
+Use `--junit-xml` to output a JUnit-format XML report alongside test execution, compatible with Jenkins, GitLab CI, CircleCI, and other CI tools.
+
+### CLI Usage
+
+```bash
+symtest run test_cases.json --junit-xml report.xml
+```
+
+`--junit-xml` is a supplementary output, coexisting with `--output-format` (text/json/html) without affecting the console report.
+
+### Python API
+
+```python
+from symtest import write_junit_xml
+
+runner.run_tests()
+write_junit_xml(runner.results, "report.xml", suite_name="my_suite")
+```
+
+Status mapping: `passed` → pass; `failed` → failure (assertion failure) or error (execution error); `timeout` → error; `xfailed` → **skipped** (expected failure, no build impact); `xpassed` → **failure** (unexpected pass, treated as build failure). Each testcase element includes command output and failure reason.
+
+## Logging Configuration
+
+All framework diagnostic and status information is output through Python's standard `logging` module, unified under the `symtest` namespace. Logs are written to **stderr** by default, keeping `stdout` clean for safe use with `--output-format json` for machine-readable output.
+
+### CLI Log Level Control
+
+Both `run` and `compare` subcommands support:
+
+| Option | Description |
+|---|---|
+| `--verbose` / `-v` | Verbose output; log level raised to DEBUG |
+| `--debug` | Debug mode; also raised to DEBUG, and prints full stack traces on error |
+
+Default level is INFO, showing only key progress and errors; adding `--verbose` or `--debug` outputs command output, scheduling details, and other DEBUG-level information.
+
+```bash
+# Verbose mode (includes command output etc. at DEBUG level)
+symtest run test_cases.json --verbose
+
+# Debug mode (prints stack trace on error)
+symtest run test_cases.json --debug
+```
+
+### Library Usage
+
+When imported as a library, the framework only attaches a `NullHandler` by default, producing no output (following the polite library logging convention). To see logs, call `setup_console_logging()` to enable console output:
+
+```python
+import logging
+from symtest.logging_config import setup_console_logging, get_logger
+
+# Enable console logging (stderr), with optional level
+setup_console_logging(level=logging.DEBUG)
+
+logger = get_logger(__name__)   # Automatically under symtest namespace
+logger.info("Custom log message")
+```
+
+### Output to Log File
+
+The framework does not have a built-in `--log-file` option, but you can use Python's standard `logging` to add a file handler for the `symtest` logger:
+
+```python
+import logging
+from symtest.logging_config import get_logger
+
+file_handler = logging.FileHandler("run.log", encoding="utf-8")
+file_handler.setLevel(logging.DEBUG)
+file_handler.setFormatter(
+    logging.Formatter("%(asctime)s %(levelname)-7s %(name)s %(message)s")
+)
+
+# Add file handler to framework root logger; all child loggers inherit it
+logging.getLogger("symtest").addHandler(file_handler)
+```
+
+The above code works both for library usage and in scripts alongside `symtest`. Console and file handlers can coexist.
+
+## File Comparison
+
+The framework provides standalone file comparison capabilities, supporting text, JSON, CSV, XML, HDF5, binary, and more formats. Usable via command-line tools or automatically invoked in test case `expected.compare_files` (see [File Comparison Assertions](#file-comparison-assertions-compare_files)).
+
+### Command Line Tools
+
+Two equivalent invocation methods with identical parameters:
+
+```bash
+# Standalone command
+compare-files <file1> <file2> [options]
+
+# symtest subcommand
+symtest compare <file1> <file2> [options]
+```
+
+### Common Options
+
+| Option | Description |
+|---|---|
+| `--file-type` | File type: `auto` (default), `text`, `json`, `csv`, `xml`, `h5`, `binary` |
+| `--start-line` | Start line number (1-based), default 1 |
+| `--end-line` | End line number (1-based) |
+| `--start-column` | Start column number (1-based), default 1 |
+| `--end-column` | End column number (1-based) |
+| `--encoding` | Text encoding, default `utf-8` |
+| `--output-format` | Output format: `text`, `json`, `html` |
+| `--verbose` / `-v` | Verbose output |
+| `--debug` | Debug mode |
+| `--num-threads` | Number of parallel threads, default 4 |
+
+### Text File Comparison
+
+```bash
+compare-files file1.txt file2.txt --start-line 10 --end-line 20
+```
+
+### JSON File Comparison
+
+```bash
+# Exact comparison (default)
+compare-files data1.json data2.json
+
+# Compare by key field
+compare-files data1.json data2.json --json-compare-mode key-based --json-key-field id
+```
+
+| Option | Description |
+|---|---|
+| `--json-compare-mode` | `exact` (default) or `key-based` |
+| `--json-key-field` | Matching field for key-based mode, supports comma-separated multi-field |
+
+### CSV File Comparison
+
+```bash
+# Basic comparison
+compare-files data1.csv data2.csv
+
+# Custom delimiter and numerical tolerance
+compare-files data1.csv data2.csv --csv-delimiter ';' --csv-rtol 1e-4 --csv-atol 1e-6
+
+# TSV files (auto-detected as csv type)
+compare-files data1.tsv data2.tsv
+
+# Data filtering (compare only numeric cells matching the condition)
+compare-files data1.csv data2.csv --csv-data-filter '>1e-6'
+compare-files data1.csv data2.csv --csv-data-filter 'abs>1e-9'
+compare-files data1.csv data2.csv --csv-data-filter '<=0.01'
+```
+
+| Option | Description |
+|---|---|
+| `--csv-rtol` | Relative tolerance for numerics, default 1e-5 |
+| `--csv-atol` | Absolute tolerance for numerics, default 1e-8 |
+| `--csv-delimiter` | Field delimiter, default `,` |
+| `--csv-quotechar` | Quote character, default `"` |
+| `--csv-data-filter` | Data filter expression: `>`, `>=`, `<`, `<=`, `==`; supports `abs` prefix. Only compares numeric cells that **both files** satisfy the condition for |
+
+CSV comparison compares cell by cell in row-column structure; numeric cells within tolerance are considered equal. After `--csv-data-filter` filtering, numeric cell pairs that don't satisfy the condition won't report differences. The difference report includes row/column count mismatches and cell inconsistencies, listing up to 10 entries.
+
+#### Error Analysis (--error-analysis)
+
+By default, CSV and HDF5 comparators stop reporting after finding 10 differences. When you need statistical insight into **all numeric cells**, enable streaming full statistics via `--error-analysis`.
+
+When enabled, each failed file comparison appends `error_stats` to the Compare Failures section of the report:
+
+| Statistic | Description |
+|---|---|
+| `total_numeric_cells` | Total number of numeric cells compared |
+| `mismatched_cells` | Number of cells exceeding tolerance |
+| `max_abs_error` | Maximum absolute error and its location |
+| `max_rel_error` | Maximum relative error and its location |
+| `mean_abs_error` | Mean absolute error |
+| `rms_abs_error` | Root-mean-square absolute error (RMSE) |
+
+Statistics are computed **in streaming fashion**, independent of the difference truncation, covering all numeric cells. By default only failed comparisons output statistics; passed comparisons do not.
+
+To also output statistics for **passed** cases (e.g. to monitor tolerance headroom), use `--error-analysis-all` instead (it implicitly enables `--error-analysis`):
+
+```bash
+# Output error statistics for all cases (including passed ones)
+symtest run config.json --error-analysis-all
+```
+
+When enabled, each **passed** case lists the above statistics in the Detailed Results section as `error_stats:`. For passed cases the statistics are also written to the `assertion_results[].error_stats` field of the `--output json` report for programmatic consumption. Statistics for passed cases are produced only when `--error-analysis-all` is enabled; otherwise behavior is unchanged.
+
+**CLI Usage**:
+
+```bash
+# Enable error analysis
+symtest run config.json --error-analysis
+
+# Enable error analysis and also output statistics for passed cases
+symtest run config.json --error-analysis-all
+
+# Combine with comparison parameters
+symtest run config.json --error-analysis --csv-rtol 1e-4 --csv-data-filter '>0'
+```
+
+**Python API**:
+
+```python
+# Enable in comparator
+comparator = ComparatorFactory.create_comparator(
+    "csv", rtol=1e-5, atol=1e-8, error_analysis=True
+)
+result = comparator.compare_files("data1.csv", "data2.csv")
+print(result.error_stats)  # dict or None
+
+# Enable via Assertions.compare_files
+from symtest.core.assertions import Assertions
+cf_result = Assertions.compare_files(
+    "actual.csv", "baseline.csv",
+    file_type="csv", rtol=1e-5, atol=1e-8,
+    error_analysis=True,
+)
+print(cf_result["error_stats"])
+```
+
+> **Note**: `--error-analysis` only applies to numeric comparators (CSV, HDF5); text/JSON/XML/binary comparators ignore this parameter. When disabled, behavior is unchanged with no overhead.
+
+### XML File Comparison
+
+```bash
+# Structural comparison (tags, attributes, text, child elements)
+compare-files config1.xml config2.xml
+
+# HTML files (auto-detected as xml type)
+compare-files page1.html page2.html
+```
+
+XML comparison recursively compares tags, attributes, text content, and child element counts by DOM structure. The difference report locates specific paths (e.g., `/root/item[0]/@id`), listing up to 10 entries.
+
+### HDF5 File Comparison
+
+```bash
+# Compare specified tables
+compare-files data1.h5 data2.h5 --h5-table table1,table2
+
+# Use regex to match table names
+compare-files data1.h5 data2.h5 --h5-table-regex "result_.*"
+
+# Comma-separated multiple regex patterns
+compare-files data1.h5 data2.h5 --h5-table-regex "table1,table2,table3"
+
+# Numerical tolerance
+compare-files data1.h5 data2.h5 --h5-rtol 1e-5 --h5-atol 1e-8
+
+# Data filtering (compare only data matching the condition)
+compare-files data1.h5 data2.h5 --h5-data-filter '>1e-6'
+compare-files data1.h5 data2.h5 --h5-data-filter 'abs>1e-9'
+compare-files data1.h5 data2.h5 --h5-data-filter '<=0.01'
+
+# Disable automatic group path expansion
+compare-files data1.h5 data2.h5 --h5-table group1 --h5-no-expand-path
+```
+
+| Option | Description |
+|---|---|
+| `--h5-table` | Specify table names, comma-separated |
+| `--h5-table-regex` | Regex pattern for table names, comma-separated multi-pattern |
+| `--h5-structure-only` | Compare structure only, not content |
+| `--h5-show-content-diff` | Show content difference details |
+| `--h5-rtol` | Relative tolerance, default 1e-5 |
+| `--h5-atol` | Absolute tolerance, default 1e-8 |
+| `--h5-data-filter` | Data filter expression: `>`, `>=`, `<`, `<=`, `==`; supports `abs` prefix |
+| `--h5-no-expand-path` | Disable automatic expansion of sub-items under group paths |
+
+### Binary File Comparison
+
+```bash
+compare-files binary1.bin binary2.bin --similarity --chunk-size 16384
+```
+
+| Option | Description |
+|---|---|
+| `--similarity` | Calculate similarity index |
+| `--chunk-size` | Read chunk size, default 8192 |
+
+### Python API
+
+```python
+from symtest.file_comparator import ComparatorFactory
+
+# Text comparison
+comparator = ComparatorFactory.create_comparator("text", encoding="utf-8", verbose=True)
+result = comparator.compare_files("file1.txt", "file2.txt")
+
+# JSON comparison
+comparator = ComparatorFactory.create_comparator("json", compare_mode="key-based", key_field="id")
+result = comparator.compare_files("data1.json", "data2.json")
+
+# CSV comparison
+comparator = ComparatorFactory.create_comparator("csv", rtol=1e-5, atol=1e-8, delimiter=",")
+result = comparator.compare_files("data1.csv", "data2.csv")
+
+# CSV comparison (with error analysis)
+comparator = ComparatorFactory.create_comparator("csv", rtol=1e-5, atol=1e-8, delimiter=",", error_analysis=True)
+result = comparator.compare_files("data1.csv", "data2.csv")
+print(result.error_stats)  # Full numeric statistics
+
+# XML comparison
+comparator = ComparatorFactory.create_comparator("xml", encoding="utf-8")
+result = comparator.compare_files("config1.xml", "config2.xml")
+
+# HDF5 comparison
+comparator = ComparatorFactory.create_comparator("h5", tables=["table1"], rtol=1e-5)
+result = comparator.compare_files("data1.h5", "data2.h5")
+
+# Results
+result.identical   # bool
+result.differences # list
+```
+
+## Extension Development
+
+### Custom Runner
+
+```python
+from symtest.core.base_runner import BaseRunner
+
+class CustomRunner(BaseRunner):
+    def load_test_cases(self):
+        # Load test cases into self.test_cases
+        pass
+
+    def run_single_test(self, test_case):
+        # Execute a single test, return result dictionary
+        pass
+```
+
+### Custom Setup Plugin
+
+```python
+from symtest import BaseSetup
+
+class MySetup(BaseSetup):
+    def setup(self):
+        # self.config gives access to the passed config dict
+        pass
+
+    def teardown(self):
+        pass
+```
+
+### Custom File Comparator
+
+#### Three-Lane Architecture (v2)
+
+The comparator plugin system is organized around the root contract
+`ComparatorBase.compare(ctx) -> ComparisonResult`, split by verdict ownership
+into three lanes:
+
+| Lane | Base class | Use case | Verdict owned by |
+|---|---|---|---|
+| **File lane** | `FileComparator` | Comparing two same-kind files (built-in text/json/csv/xml/h5/binary) | Plugin |
+| **Data lane** | `ExtractorComparator` | Extracting numeric data from any upstream (files / solver output / cross-file aggregation), reusing the framework numeric core for per-channel tolerance verdicts | **Framework** |
+| **Autonomous lane** | extend `ComparatorBase` directly | Custom verdict logic (composite thresholds, label parsing, sign/asymptotic checks) | Plugin |
+
+Selection guide:
+
+- Data is already `(expected, actual)` numeric arrays needing only rtol/atol → **data lane** (channels, per-channel tolerances, unified error_stats and report rendering)
+- Custom verdict needed (e.g. "tight on main components, loose on EAS components", sign checks) → **autonomous lane**
+- Just want to wire an existing script in quickly → built-in `script` (custom verdict) or `script_extract` (framework tolerance verdict), zero plugin code
+
+**Path resolution convention**: `actual`/`baseline` and any constructor params
+declared in the plugin's `path_params` class attribute are resolved against
+the workspace by the framework **before the comparator is constructed** —
+constructor-captured state (`self.script`, `self.cwd`, ...) already holds
+absolute paths. Plugins must
+**never** resolve paths against CWD — it is unreliable under parallel/process
+execution.
+
+#### Plugin Discovery (common to all lanes)
+
+Create a `comparators/` directory under your workspace and place `*_comparator.py` files inside. The framework auto-discovers and registers the `*Comparator` classes on first use.
+
+```
+your-workspace/
+├── comparators/
+│   └── my_analysis_comparator.py   # Auto-discovered by the framework
+└── test_config.json
+```
+
+You can specify additional plugin directories via the CLI `--plugin-dir` parameter (usable multiple times):
+
+```bash
+symtest run test_config.json --plugin-dir ./extra_plugins
+```
+
+Plugins are also automatically inherited by process-mode child processes via the `CLITEST_PLUGIN_DIRS` environment variable.
+
+**Naming conventions**:
+- File name must end with `_comparator.py` (e.g., `my_analysis_comparator.py`)
+- Class name must end with `Comparator` (e.g., `MyAnalysisComparator`)
+- The registered type name = class name without `Comparator`, lowercased (e.g., `myanalysis`); a `comparator_type = "my_analysis"` class attribute overrides it
+- Abstract base classes (with unimplemented abstract methods) are skipped automatically
+
+Use the registered type name directly in your config. Comparator constructor
+parameters are **strict**: keys other than `actual`/`baseline`/`type` are
+forwarded to the plugin constructor, but a parameter the plugin does not
+declare (e.g. a typo like `pass_threhsold`) **fails loudly** at construction
+(the error names the comparator type and its supported parameters) — it never
+silently falls back to defaults. Plugin-owned configuration should go into
+the `options` namespace (entries merged into constructor kwargs; explicit
+top-level keys take precedence), keeping the core schema generic:
+
+```json
+{
+  "type": "myanalysis",
+  "actual": "optional_for_plugins",
+  "baseline": "optional_for_plugins",
+  "options": {"param1": "value1", "param2": 42}
+}
+```
+
+#### Data Lane: Channel Extractor Plugin
+
+Use case: one script/plugin produces multi-channel data (e.g. different CSV
+columns, different physical quantities), each channel needing independent
+tolerances and error analysis. The plugin only EXTRACTS; the framework
+owns the verdict entirely.
+
+```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-resolved by framework
+
+    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())},
+            ),
+        }
+```
+
+Config (per-channel tolerances routed by name; unlisted channels use `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}
+}
+```
+
+**Verdict and result semantics**:
+- Each channel runs `compare_numeric` independently (symmetric tolerance `|a-b| <= max(rtol*max(|a|,|b|), atol)`)
+- `identical = all channels pass`; one compareSpec is still one assertion
+- Difference positions carry the channel prefix (`channel S33`); `error_stats` nests by channel name
+- The report shows per-channel pass/fail, tolerances and stats; channel differences are trimmed per channel in JSON output
+- Custom error metrics ride along via `ChannelData.extra_stats`, kept in a SEPARATE namespace (`ChannelResult.extra_stats`) that can never overwrite framework canonical metrics (`max_abs_error`, `total`, ...); the report renders both namespaces per channel
+- The verdict itself cannot be altered by the plugin — custom verdicts belong to the autonomous lane
+
+#### Data Lane: Built-in `script_extract` Type (Zero-Modification Script Access)
+
+Existing analysis scripts need no Python plugin wrapper: the script runs as a
+subprocess and prints a JSON channel payload on stdout; each channel then
+enters the framework-owned tolerance pipeline described above.
+
+```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 protocol**:
+
+```json
+{
+  "channels": {
+    "S11": {"expected": [1.0, 2.0], "actual": [1.0, 2.0]},
+    "S33": {"expected": [...], "actual": [...], "extra_stats": {"asymmetry": 2e-13}}
+  }
+}
+```
+
+**Error semantics**: non-zero exit code, timeout, malformed JSON, a missing
+`channels` key, or a channel missing `expected`/`actual` arrays → always a
+comparison error (never a silent pass). `actual`/`baseline` (if configured)
+are appended as trailing script arguments with baseline first; both optional.
+
+#### Autonomous Lane: Full-Verdict Plugin
+
+Use case: custom verdict logic. The plugin implements `compare(ctx)` and
+returns the result directly.
+
+```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__()   # strict: undeclared/misspelled config keys fail loudly
+        self.script = script      # workspace-resolved by the framework before construction
+        self.case_dir = case_dir
+        self.pass_threshold = pass_threshold
+
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        result = ComparisonResult(
+            file1=ctx.baseline,   # stays None when there is no file input — no fake ""
+            file2=ctx.actual,
+        )
+        # ... run analysis, parse metrics ...
+        result.identical = True  # or False + differences
+        result.error_stats = {"full_rel": 8e-8}   # free-form dict, generic rendering
+        return result
+```
+
+`ctx` fields (invocation-level context only): `workspace` / `actual` /
+`baseline` (`None` when absent) / `params` (file-lane window ranges) /
+`error_analysis`.  The single authoritative copy of comparator configuration
+lives in constructor-captured state — `ctx` never duplicates it.
+
+#### Built-in `script` Type Comparator (Autonomous Lane Out of the Box)
+
+For quickly integrating standalone analysis scripts without writing a comparator class:
+
+```json
+{
+  "type": "script",
+  "script": "analyze_xxx.py",
+  "actual": "output.txt",
+  "baseline": "baseline.txt",
+  "cwd": ".",
+  "pass_pattern": "RESULT: PASS",
+  "fail_pattern": "RESULT: (MISMATCH|FAILED)",
+  "pass_exit_code": 0,
+  "timeout": 600
+}
+```
+
+**Parameter Descriptions**:
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `script` | Yes | — | Script path (relative to workspace or absolute) |
+| `actual` | No | — | File argument passed to the script (trailing second slot) |
+| `baseline` | No | — | File argument passed to the script (trailing first slot) |
+| `cwd` | No | — | Script working directory |
+| `interpreter` | No | `sys.executable` | Python interpreter |
+| `pass_exit_code` | No | `0` | Exit code considered a pass |
+| `pass_pattern` | No | — | stdout must match this regex to be considered a pass |
+| `fail_pattern` | No | — | stdout matching this regex forces a failure (highest priority) |
+| `timeout` | No | `3600` | Timeout in seconds |
+
+**Judgment Logic**:
+1. `fail_pattern` match → failure (highest priority)
+2. `pass_pattern` set but not matched → failure
+3. `pass_pattern` matched → use exit code to judge
+4. No pattern → directly use exit code to judge
+
+The script's stdout and stderr are fully captured in the `Comparator Output` section, displayed up to 20 lines in the rendered report.
+
+#### Manual Registration (Programmatic)
+
+```python
+from symtest.file_comparator import ComparatorFactory, ComparatorBase, CompareContext
+from symtest.file_comparator.result import ComparisonResult
+
+class FooComparator(ComparatorBase):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
+        ...
+
+ComparatorFactory.register_comparator("foo", FooComparator)
+
+# Then usable in compare_files assertions or CLI --file-type foo
+comparator = ComparatorFactory.create_comparator("foo")
+```
+
+#### Specialized Plugin Example: Hourglass Tangent Stiffness Analysis
+
+`examples/plugins/hourglass_tangent_comparator.py` is a complete autonomous-lane workspace plugin example demonstrating how to integrate a dedicated `analyze_*_tangent.py` analysis script into the framework:
+
+```json
+{
+  "type": "hourglass_tangent",
+  "script": "case/.../analyze_case01_tangent.py",
+  "case_dir": "case/.../case01",
+  "pass_threshold": 1e-6,
+  "timeout": 600
+}
+```
+
+**Features**:
+- Calls the analysis script via subprocess (**zero changes** to analyze code), parses `RESULT:` lines and numerical metrics like `full_rel`/`aa_rel`/`hh_rel`/`asymmetry` from stdout using regex
+- Constructs a structured `ComparisonResult`: `identical` determined by `full_rel < pass_threshold`; `differences` lists exceeded metrics; `error_stats` contains all numeric values
+- `path_params` declares `script`/`case_dir`, resolved against the workspace by the framework
+- Script stdout goes into the `Comparator Output` section
+
+Usage: copy the plugin file into your workspace's `comparators/` directory for auto-discovery — no framework code changes needed.
+
+> **More plugin development guidance**: See `examples/plugins/README.md`. Entry points (pip install → just works) will be supported in a future iteration.
+
+### Assertions & File Comparison
+
+The `Assertions` class provides static assertion methods; all checks in `expected` are performed by it:
+
+```python
+from symtest.core.assertions import Assertions
+
+Assertions.return_code_equals(actual_code, 0)
+Assertions.contains(output, "expected text")
+Assertions.matches(output, r".*regex.*")
+Assertions.compare_files("actual.txt", "baseline.txt", file_type="text", workspace="/ws")
+
+# Enable error analysis (CSV/H5 only)
+Assertions.compare_files("actual.h5", "baseline.h5", file_type="h5", workspace="/ws", rtol=1e-5, error_analysis=True)
+```
+
+`compare_files` auto-detects type by extension (`.h5/.hdf5/.hdf`→h5, `.json`→json, `.csv/.tsv`→csv, `.xml/.html/.htm`→xml, `.txt/.log/.out/.py`→text, everything else→binary); relative paths are resolved against `workspace`; extra parameters (including `error_analysis`) are passed through to the comparator.
+
+On success, returns a structured dict (with `identical`, `actual`, `baseline`, `diff_summary`, `differences`, etc.); on failure, raises `ValidationError(AssertionError)` carrying `failure_kind` and a `compare_failures` list.
+
+## Running Framework Tests
+
+The project includes a unified test entry point `tests/run_all.py`. Use `--scope` to select the test range and `--extra` to pass arbitrary pytest arguments.
+
+### Test Scopes
+
+| Scope | Description | Corresponding Directory |
+|---|---|---|
+| `unit` | Unit tests (core, runners, etc.) | `tests/unit` |
+| `integration` | Integration tests (file comparison, parallel, path handling, etc.) | `tests/integration` |
+| `e2e` | End-to-end tests (user workflows) | `tests/e2e` |
+| `all` | Run all of the above (default) | All three combined |
+
+> Note: Scripts under `tests/demos/` are manual/interactive demos, not included in scope runs; they must be executed separately.
+
+### Usage
+
+```bash
+# Run all tests (default)
+python tests/run_all.py
+
+# Developers can install all optional and test dependencies at once
+pip install -e ".[dev]"
+
+# Run unit tests only
+python tests/run_all.py --scope unit
+
+# Run integration tests only
+python tests/run_all.py --scope integration
+
+# Run end-to-end tests only
+python tests/run_all.py --scope e2e
+
+# Pass pytest arguments, e.g., filter by keyword
+python tests/run_all.py --scope integration --extra "-k h5"
+
+# Pass multiple pytest arguments
+python tests/run_all.py --scope unit --extra "-v -k assertions"
+```
+
+`--extra` accepts a string that is split via `shlex` and appended to the pytest command line. The script invokes pytest through the current interpreter (`sys.executable -m pytest`), ensuring the activated environment is used rather than the first `pytest` found on PATH.
+
+Activate your Python environment (e.g. conda) before running tests:
+
+```bash
+conda activate <your-env>
+python tests/run_all.py
+```
diff --git a/src/symtest/__init__.py b/src/symtest/__init__.py
index 49f83a1..083db62 100644
--- a/src/symtest/__init__.py
+++ b/src/symtest/__init__.py
@@ -16,10 +16,18 @@
     setup_console_logging(level=logging.DEBUG)
 """
 
-__version__ = "1.4.0"
 __author__ = "Xiaotong Wang"
 __email__ = "xiaotongwang98@gmail.com"
 
+try:
+    # Version is managed in pyproject.toml ([project] version).
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    __version__ = _pkg_version("symtest-cli")
+except PackageNotFoundError:
+    # Fallback when running from source without installing the package.
+    __version__ = "0.0.0"
+
 # Import main classes for convenient access
 from .runners.json_runner import JSONRunner
 from .runners.parallel_json_runner import ParallelJSONRunner
diff --git a/src/symtest/cli.py b/src/symtest/cli.py
index b8c7ee0..6a4190c 100644
--- a/src/symtest/cli.py
+++ b/src/symtest/cli.py
@@ -15,6 +15,7 @@
 from pathlib import Path
 
 from .logging_config import setup_console_logging
+from .reporting.diagnosis import attach_next_action_hints
 from .runners import JSONRunner, ParallelJSONRunner, ParallelYAMLRunner, YAMLRunner
 from .utils.report_generator import ReportGenerator
 from .utils.junit_xml_writer import write_junit_xml
@@ -77,7 +78,7 @@ def create_parser():
   symtest run test_cases.json
   symtest run test_cases.json --parallel --workers 4
   symtest run test_cases.yaml --workspace /path/to/project
-  symtest tui test_cases.json
+  symtest find main_config.json "login"
   symtest validate main_config.json
   symtest migrate old.json --output new.json
   symtest compare file1.json file2.json
@@ -140,32 +141,33 @@ def create_parser():
                                 '(can be used multiple times). '
                                 'The workspace/comparators/ directory is always auto-detected.')
 
-    # ---- TUI command ----
-    tui_parser = subparsers.add_parser(
-        'tui', help='Launch interactive TUI for managing test cases'
+    # ---- Find command ----
+    find_parser = subparsers.add_parser(
+        'find', help='Search test cases across all imported configurations '
+                     '(auto-expands import references)'
     )
-    tui_parser.add_argument(
+    find_parser.add_argument(
         'config_file', help='Path to the test configuration file (JSON or YAML)'
     )
-    tui_parser.add_argument(
-        '--workspace', '-w', help='Working directory'
+    find_parser.add_argument(
+        'pattern', nargs='?', default='',
+        help='Search pattern (empty pattern lists all cases)'
     )
-    tui_parser.add_argument(
-        '--update-baseline', action='store_true',
-        help='On comparison failure, overwrite baseline files with actual output'
+    find_parser.add_argument(
+        '--mode', choices=['substring', 'fuzzy', 'regex'], default='substring',
+        help='Search mode (default: substring, case-insensitive)'
     )
-    tui_parser.add_argument(
-        '--yes', '-y', action='store_true',
-        help='Confirm baseline updates without prompting'
+    find_parser.add_argument(
+        '--tag', action='append', default=None,
+        help='Only show cases with matching tag (exact match, can be used '
+             'multiple times)'
     )
-    tui_parser.add_argument(
-        '--history-dir',
-        help='Directory for .symtest runtime history (enables regression detection per case)'
+    find_parser.add_argument(
+        '--workspace', '-w', help='Working directory'
     )
-    tui_parser.add_argument(
-        '--update-history', action='store_true',
-        help='Clear .symtest runtime history for run-involved cases before '
-             'recording this run (requires --history-dir)'
+    find_parser.add_argument(
+        '--output-format', choices=['text', 'json'], default='text',
+        help='Output format (default: text)'
     )
 
     # ---- Validate command ----
@@ -207,6 +209,12 @@ def create_parser():
         '--output', '-o',
         help='Output path (default: <stem>.v2<ext>, e.g. old.json -> old.v2.json)',
     )
+    migrate_parser.add_argument(
+        '--in-place', action='store_true',
+        help='Migrate the config and every file it imports recursively, '
+             'overwriting each file in place (originals are not kept; '
+             'mutually exclusive with --output)',
+    )
 
     # ---- Compare command ----
     compare_parser = subparsers.add_parser('compare', help='Compare two files')
@@ -396,6 +404,15 @@ def run_tests(args):
         # Output results using ReportGenerator and honor --output-format
         if hasattr(runner, 'results'):
             results = runner.results
+
+            # ── Reporting 装配点（原则 5）：next_action_hint 在报告输出前
+            # 按 failure_kind 填充，orchestration 只产出失败结论 ──
+            attach_next_action_hints(
+                results,
+                update_baseline=bool(getattr(args, 'update_baseline', False)),
+                config_path=str(config_file),
+            )
+
             output_format = getattr(args, 'output_format', 'text')
 
             if output_format == 'json':
@@ -470,21 +487,11 @@ def run_compare(args):
     return bool(exit_code == 0)
 
 
-def run_tui(args):
-    """Launch the TUI manager."""
-    from .tui.app import run_tui as _run_tui
-
-    if not _confirm_baseline_update(args):
-        return False
+def run_find(args):
+    """Search test cases across imported configurations."""
+    from .commands.find import run_find as _run_find
 
-    update_baseline = getattr(args, 'update_baseline', False)
-    history_dir = getattr(args, 'history_dir', None)
-    update_history = getattr(args, 'update_history', False)
-    _run_tui(args.config_file, args.workspace,
-             update_baseline=update_baseline,
-             history_dir=history_dir,
-             update_history=update_history)
-    return True
+    return _run_find(args)
 
 
 def run_validate(args):
@@ -547,6 +554,19 @@ def run_migrate(args) -> bool:
     return _run_migrate(args)
 
 
+def _to_exit_code(result) -> int:
+    """Single exit-code conversion point for all sub-command handlers.
+
+    Handlers return either a bool (``False`` = failure → 1) or an int exit
+    code directly (commands with richer semantics, e.g. ``find``:
+    0 = match, 1 = no match, 2 = error). No branch in ``main`` should
+    convert codes itself.
+    """
+    if isinstance(result, bool):
+        return 0 if result else 1
+    return int(result)
+
+
 def main():
     """Main entry point for the CLI"""
     parser = create_parser()
@@ -559,27 +579,22 @@ def main():
     setup_console_logging(level=level)
 
     if args.command == 'run':
-        success = run_tests(args)
         # 0 = all passed, 1 = test failures, 2 = config/framework errors
-        sys.exit(0 if success else 1)
-    elif args.command == 'tui':
-        success = run_tui(args)
-        if success is False:
-            sys.exit(1)
+        sys.exit(_to_exit_code(run_tests(args)))
+    elif args.command == 'find':
+        # grep-style exit codes: 0 = match, 1 = no match, 2 = error
+        sys.exit(_to_exit_code(run_find(args)))
     elif args.command == 'validate':
-        success = run_validate(args)
         # 0 = valid, 1 = validation errors found
-        sys.exit(0 if success else 1)
+        sys.exit(_to_exit_code(run_validate(args)))
     elif args.command == 'schema':
         run_schema()
         sys.exit(0)
     elif args.command == 'migrate':
-        success = run_migrate(args)
         # 0 = migrated, 1 = input/format errors
-        sys.exit(0 if success else 1)
+        sys.exit(_to_exit_code(run_migrate(args)))
     elif args.command == 'compare':
-        success = run_compare(args)
-        sys.exit(0 if success else 1)
+        sys.exit(_to_exit_code(run_compare(args)))
     else:
         parser.print_help()
         sys.exit(1)
diff --git a/src/symtest/commands/compare.py b/src/symtest/commands/compare.py
index e660c28..6aaddc1 100644
--- a/src/symtest/commands/compare.py
+++ b/src/symtest/commands/compare.py
@@ -14,6 +14,7 @@
 import logging
 from pathlib import Path
 from ..file_comparator.factory import ComparatorFactory
+from ..file_comparator.base_comparator import CompareContext
 from ..file_comparator.result import ComparisonResult
 
 logger = logging.getLogger("symtest.commands.compare")
@@ -144,15 +145,25 @@ def run_comparison(args, logger=None):
         file_type = detect_file_type(file1_path)
         logger.info(f"Auto-detected file type: {file_type}")
 
-    # Prepare comparator kwargs
+    # Prepare comparator kwargs — strictly scoped per type.  Comparators
+    # declare explicit constructor parameters, so universal knobs
+    # (encoding / chunk_size / num_threads) are only sent to types that
+    # actually accept them.  'verbose' is a framework-owned logging knob
+    # consumed by the factory.
     comparator_kwargs = {
-        "encoding": args.encoding,
-        "chunk_size": args.chunk_size,
         "verbose": args.verbose or args.debug,
-        "num_threads": args.num_threads
     }
-    
+
+    if file_type in ("text", "json", "csv", "xml", "h5"):
+        comparator_kwargs["encoding"] = args.encoding
+    if file_type in ("text", "json", "binary"):
+        comparator_kwargs["chunk_size"] = args.chunk_size
+
     # Add file type specific arguments
+    if file_type == "binary":
+        comparator_kwargs["num_threads"] = args.num_threads
+        comparator_kwargs["similarity"] = args.similarity
+
     if file_type == "json":
         comparator_kwargs["compare_mode"] = args.json_compare_mode
         if args.json_key_field:
@@ -180,20 +191,21 @@ def run_comparison(args, logger=None):
         if args.h5_data_filter:
             comparator_kwargs["data_filter"] = args.h5_data_filter
         comparator_kwargs["expand_path"] = args.h5_expand_path
-    
-    if file_type == "binary":
-        comparator_kwargs["similarity"] = args.similarity
 
     # Create comparator and perform comparison
     comparator = ComparatorFactory.create_comparator(file_type, **comparator_kwargs)
-    result = comparator.compare_files(
-        file1_path,
-        file2_path,
-        start_line,
-        end_line,
-        start_column,
-        end_column
+    # CLI semantics: file1 = first file (baseline slot), file2 = second (actual slot)
+    ctx = CompareContext(
+        actual=str(file2_path),
+        baseline=str(file1_path),
+        params={
+            "start_line": start_line,
+            "end_line": end_line,
+            "start_column": start_column,
+            "end_column": end_column,
+        },
     )
+    result = comparator.compare(ctx)
 
     # Output result
     output = format_result(result, args.output_format)
diff --git a/src/symtest/commands/find.py b/src/symtest/commands/find.py
new file mode 100644
index 0000000..1bea0be
--- /dev/null
+++ b/src/symtest/commands/find.py
@@ -0,0 +1,244 @@
+"""symtest find — search test cases across all imported configurations.
+
+Replaces the search capability of the retired TUI: loads the config through
+the same pipeline as the runners (import expansion + inheritance resolution
+via ``load_config``), parses cases with the single system-wide parser, then
+matches each case across name / command / args / tags / description using
+one of three modes:
+
+- ``substring`` (default): case-insensitive substring
+- ``regex``: case-insensitive regular expression (invalid pattern simply
+  matches nothing, never raises; the pattern is compiled once per search)
+- ``fuzzy``: bigram-overlap scoring with field weights, results ranked by
+  score
+
+An empty pattern lists all cases in every mode (consistent semantics).
+
+Exit codes (grep semantics): 0 = matches found, 1 = no match, 2 = error
+(config unreadable / unparseable).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Pattern, Tuple
+
+from ..config.config_io import load_config
+from ..core.config_loader import parse_test_cases
+from ..core.test_case import TestCase
+
+logger = logging.getLogger("symtest.commands.find")
+
+# ---------------------------------------------------------------------------
+# Search helpers (moved verbatim from the retired TUI CaseController)
+# ---------------------------------------------------------------------------
+
+# Field weights for fuzzy scoring (higher = more important).
+_FIELD_WEIGHTS: Dict[str, float] = {
+    "name": 2.0,
+    "command": 1.5,
+    "tags": 1.0,
+    "description": 1.0,
+    "args": 0.5,
+}
+
+# Default searchable fields and their extractors
+_SEARCH_FIELDS = [
+    ("name", lambda tc: tc.name),
+    ("command", lambda tc: tc.command),
+    ("args", lambda tc: " ".join(tc.args)),
+    ("tags", lambda tc: ",".join(tc.tags)),
+    ("description", lambda tc: tc.description or ""),
+]
+
+
+def _substring_match(query: str, case: TestCase) -> bool:
+    """Case-insensitive substring match across all searchable fields."""
+    q = query.lower()
+    for _field_name, extractor in _SEARCH_FIELDS:
+        if q in extractor(case).lower():
+            return True
+    return False
+
+
+def _regex_match(pattern: Pattern[str], case: TestCase) -> bool:
+    """Compiled-pattern search across all searchable fields.
+
+    Compilation happens once per search in :func:`search_cases`; this
+    function only applies the already-compiled pattern.
+    """
+    for _field_name, extractor in _SEARCH_FIELDS:
+        if pattern.search(extractor(case)):
+            return True
+    return False
+
+
+def _fuzzy_score(query: str, case: TestCase) -> float:
+    """N-gram overlap scorer; higher = better match."""
+    q = query.lower()
+    q_bigrams = {q[i: i + 2] for i in range(len(q) - 1)} if len(q) >= 2 else {q}
+    if not q_bigrams:
+        return 0.0
+
+    total = 0.0
+    for field_name, extractor in _SEARCH_FIELDS:
+        text = extractor(case).lower()
+        text_bigrams = {text[i: i + 2] for i in range(len(text) - 1)}
+        if not text_bigrams:
+            continue
+        overlap = len(q_bigrams & text_bigrams) / len(q_bigrams)
+        total += _FIELD_WEIGHTS.get(field_name, 0.5) * overlap
+    return total
+
+
+def _fuzzy_match(query: str, cases: List[TestCase], threshold: float = 0.15) -> List[int]:
+    """Return indices of cases whose fuzzy score meets *threshold*."""
+    scored: List[Tuple[int, float]] = []
+    for i, tc in enumerate(cases):
+        s = _fuzzy_score(query, tc)
+        if s >= threshold:
+            scored.append((i, s))
+    scored.sort(key=lambda x: -x[1])
+    return [idx for idx, _ in scored]
+
+
+def search_cases(
+    cases: List[TestCase],
+    query: str,
+    mode: str = "substring",
+    tags: Optional[List[str]] = None,
+) -> List[int]:
+    """Return sorted list of indices for cases matching *query*.
+
+    Parameters
+    ----------
+    cases:
+        Parsed TestCase list.
+    query:
+        Search term. An empty term short-circuits to all cases in every
+        mode (consistent semantics, no matcher run).
+    mode:
+        ``"substring"`` (default), ``"fuzzy"``, or ``"regex"``.
+    tags:
+        Optional tag filter (OR relationship), applied after the query match.
+    """
+    if not query:
+        indices = list(range(len(cases)))
+    elif mode == "fuzzy":
+        indices = _fuzzy_match(query, cases)
+    elif mode == "regex":
+        try:
+            pattern = re.compile(query, re.IGNORECASE)
+        except re.error:
+            pattern = None
+        indices = (
+            [i for i, tc in enumerate(cases) if _regex_match(pattern, tc)]
+            if pattern is not None
+            else []
+        )
+    else:  # substring (default)
+        indices = [i for i, tc in enumerate(cases) if _substring_match(query, tc)]
+
+    if tags:
+        indices = [i for i in indices if any(t in cases[i].tags for t in tags)]
+
+    return indices
+
+
+# ---------------------------------------------------------------------------
+# CLI handler
+# ---------------------------------------------------------------------------
+
+
+def _case_summary(index: int, tc: TestCase) -> Dict[str, Any]:
+    """Build the display/JSON summary dict for one matched case."""
+    return {
+        "index": index + 1,
+        "name": tc.name,
+        "command": tc.command,
+        "args": list(tc.args),
+        "tags": list(tc.tags),
+        "description": tc.description or "",
+        "timeout": tc.timeout,
+        "mode": "steps" if tc.steps else "single",
+    }
+
+
+def _display_width(text: str) -> int:
+    """Terminal display width: CJK full/wide chars count as 2 columns."""
+    return sum(2 if unicodedata.east_asian_width(ch) in "WF" else 1 for ch in text)
+
+
+def _print_table(rows: List[Dict[str, Any]]) -> None:
+    """Print matched cases as aligned columns (the retired TUI table layout)."""
+    headers = ["#", "Name", "Command", "Tags", "Timeout", "Mode"]
+
+    def fmt(row: Dict[str, Any]) -> List[str]:
+        return [
+            str(row["index"]),
+            row["name"],
+            row["command"],
+            ",".join(row["tags"]),
+            "-" if row["timeout"] is None else str(row["timeout"]),
+            row["mode"],
+        ]
+
+    cells = [headers] + [fmt(r) for r in rows]
+    widths = [max(_display_width(c[i]) for c in cells) for i in range(len(headers))]
+
+    def pad(cell: str, width: int) -> str:
+        return cell + " " * (width - _display_width(cell))
+
+    for i, row in enumerate(cells):
+        line = "  ".join(pad(cell, widths[j]) for j, cell in enumerate(row)).rstrip()
+        print(line)
+        if i == 0:
+            print("  ".join("-" * w for w in widths))
+
+
+def run_find(args) -> int:
+    """CLI entry for ``symtest find``.
+
+    Returns
+    -------
+    int
+        0 = matches found, 1 = no match, 2 = error.
+    """
+    workspace_path = Path(args.workspace) if args.workspace else Path.cwd()
+    config_file = (workspace_path / args.config_file).resolve()
+
+    try:
+        config = load_config(config_file)
+        cases = parse_test_cases(config)
+    except Exception as e:
+        logger.error("Failed to load configuration: %s", e)
+        return 2
+
+    logger.info("Loaded %d test case(s) from %s", len(cases), config_file)
+
+    matched = search_cases(
+        cases,
+        args.pattern,
+        mode=getattr(args, "mode", "substring"),
+        tags=getattr(args, "tag", None),
+    )
+
+    if not matched:
+        print(f"No test cases match pattern '{args.pattern}'.")
+        return 1
+
+    rows = [_case_summary(i, cases[i]) for i in matched]
+
+    if getattr(args, "output_format", "text") == "json":
+        print(json.dumps(rows, indent=2, ensure_ascii=False))
+    else:
+        print(f"\n{len(matched)}/{len(cases)} test case(s) match "
+              f"'{args.pattern}' in {config_file.name}:\n")
+        _print_table(rows)
+        print()
+
+    return 0
diff --git a/src/symtest/commands/migrate.py b/src/symtest/commands/migrate.py
index e053f80..7827c02 100644
--- a/src/symtest/commands/migrate.py
+++ b/src/symtest/commands/migrate.py
@@ -1,7 +1,17 @@
 """``symtest migrate`` 子命令实现（1.4 Phase 4 迁移设计第一层）。
 
 确定性转换：加载 v1 配置 → ``config.migrate.migrate_config`` 机械映射 →
-按输出扩展名写出 JSON/YAML。不做 import 展开（``expand=False``）、
+按输出扩展名写出 JSON/YAML。
+
+支持递归迁移整棵 ``import`` 树（两阶段：先把全部文件加载并迁移到内存，
+任一失败则不写任何文件，全部成功后才统一写盘）：
+
+- 默认模式：每个文件写出 ``<stem>.v2<ext>`` 兄弟副本（原文件不动），
+  并把已迁移配置中的 import 路径重写为对应的 ``.v2`` 文件名，
+  迁移产物整棵树自洽、可直接 ``symtest validate``；
+- ``--in-place``：整树原地覆盖（文件名/格式/import 路径全不变），
+  默认关闭，开启即接受覆盖风险；与 ``--output`` 互斥。
+
 不做路径解析、不校验必填 —— 校验归 ``symtest validate``，人工判断项归
 迁移复查 Skill（见 examples/skill-migration）。
 """
@@ -10,8 +20,10 @@
 
 import logging
 from pathlib import Path
+from typing import Any, Dict, List, Tuple
 
-from ..config.config_io import load_config, save_config
+from ..config.config_io import save_config
+from ..config.import_expander import _load_raw_config
 from ..config.migrate import migrate_config
 
 logger = logging.getLogger("symtest.commands.migrate")
@@ -24,12 +36,74 @@ def _resolve(path_str: str, workspace: Path) -> Path:
     return path.resolve()
 
 
+def _collect_import_tree(entry_path: Path) -> List[Path]:
+    """DFS 后序收集入口文件及全部 import 子文件。
+
+    - processed 集合保证菱形 import（同一文件被多个父文件引用）只收集一次；
+    - 递归栈检测真循环 import 并抛 RuntimeError；
+    - 子文件缺失抛 FileNotFoundError；
+    - 返回顺序保证子文件先于引用它的父文件。
+    """
+    ordered: List[Path] = []
+    processed: set = set()
+
+    def _walk(path: Path, stack: Tuple[str, ...]) -> None:
+        canonical = str(path.resolve())
+        if canonical in processed:
+            return
+        if canonical in stack:
+            raise RuntimeError(
+                f"Circular import detected: {canonical} "
+                f"(chain: {' -> '.join(stack + (canonical,))})"
+            )
+        config = _load_raw_config(path)
+        for item in config.get("test_cases", []) or []:
+            if isinstance(item, dict) and "import" in item:
+                sub_path = (path.parent / str(item["import"])).resolve()
+                if not sub_path.exists():
+                    raise FileNotFoundError(
+                        f"Imported config file not found: {sub_path} "
+                        f"(referenced from {path})"
+                    )
+                _walk(sub_path, stack + (canonical,))
+        processed.add(canonical)
+        ordered.append(path)
+
+    _walk(entry_path, ())
+    return ordered
+
+
+def _v2_sibling(import_path: str) -> str:
+    """'cases/sub.json' -> 'cases/sub.v2.json'（纯字符串变换，保留原分隔符）。"""
+    sep_idx = max(import_path.rfind("/"), import_path.rfind("\\"))
+    if sep_idx >= 0:
+        directory, filename = import_path[: sep_idx + 1], import_path[sep_idx + 1:]
+    else:
+        directory, filename = "", import_path
+    stem, dot, ext = filename.rpartition(".")
+    if not dot or not stem:
+        # 无扩展名（或 .gitignore 类隐藏名）：直接追加后缀
+        return f"{directory}{filename}.v2"
+    return f"{directory}{stem}.v2.{ext}"
+
+
+def _rewrite_import_paths(config: Dict[str, Any]) -> Dict[str, Any]:
+    """把 config 中 import 条目的路径改写为 .v2 兄弟名（就地修改并返回）。
+
+    import 条目中的其他字段（如 tags）原样保留。
+    """
+    for item in config.get("test_cases", []) or []:
+        if isinstance(item, dict) and "import" in item:
+            item["import"] = _v2_sibling(str(item["import"]))
+    return config
+
+
 def run_migrate(args) -> bool:
-    """CLI 壳：load_config(expand=False) → migrate_config → save_config。
+    """CLI 壳：收集 import 树 → 整树 migrate_config → 按模式统一写盘。
 
     Returns
     -------
-    True 成功；输入不存在/加载失败/输出格式不支持返回 False。
+    True 成功；输入不存在/加载失败/循环 import/输出格式不支持返回 False。
     """
     workspace = Path(getattr(args, "workspace", None) or Path.cwd()).resolve()
 
@@ -38,26 +112,49 @@ def run_migrate(args) -> bool:
         logger.error("Configuration file not found: %s", input_path)
         return False
 
+    in_place = getattr(args, "in_place", False)
+    output_arg = getattr(args, "output", None)
+    if in_place and output_arg:
+        logger.error("--output cannot be combined with --in-place")
+        return False
+
     try:
-        config = load_config(input_path, expand=False)
-        migrated = migrate_config(config)
+        files = _collect_import_tree(input_path)
+        # 第一阶段：整树加载并迁移到内存，任一失败则不写任何文件
+        pending: List[Tuple[Path, Dict[str, Any]]] = [
+            (f, migrate_config(_load_raw_config(f))) for f in files
+        ]
     except Exception as exc:
         logger.error("Migration failed: %s", exc)
         return False
 
-    output_arg = getattr(args, "output", None)
-    if output_arg:
-        output_path = _resolve(output_arg, workspace)
+    if output_arg and not in_place:
+        entry_output = _resolve(output_arg, workspace)
     else:
         # 默认输出 <stem>.v2<原扩展名>，如 old.json → old.v2.json
-        output_path = input_path.parent / f"{input_path.stem}.v2{input_path.suffix}"
+        entry_output = input_path.parent / f"{input_path.stem}.v2{input_path.suffix}"
 
+    written: List[Path] = []
     try:
-        save_config(migrated, output_path)
+        # 第二阶段：统一写盘
+        for src, migrated in pending:
+            if in_place:
+                target = src
+            else:
+                # import 路径指向 .v2 子副本（--output 仅移动入口文件位置，
+                # 隐含假设输出与入口同目录，否则需手工核对相对路径）
+                _rewrite_import_paths(migrated)
+                if src == input_path:
+                    target = entry_output
+                else:
+                    target = src.parent / f"{src.stem}.v2{src.suffix}"
+            save_config(migrated, target)
+            written.append(target)
     except ValueError as exc:
         logger.error("%s", exc)
         return False
 
-    logger.info("Migrated config written to: %s", output_path)
-    print(str(output_path))
+    for target in written:
+        logger.info("Migrated config written to: %s", target)
+        print(str(target))
     return True
diff --git a/src/symtest/config/config_schema.py b/src/symtest/config/config_schema.py
index 08c1d5b..1840392 100644
--- a/src/symtest/config/config_schema.py
+++ b/src/symtest/config/config_schema.py
@@ -95,33 +95,67 @@
             "description": (
                 "One file comparison rule. actual/baseline are required for built-in "
                 "file-type comparators (text/csv/json/xml/h5/binary). "
-                "They are optional for script or custom (plugin) comparator types. "
-                "Keys other than those listed below are forwarded to the comparator "
-                "as kwargs (e.g. rtol, atol, encoding, tables, data_filter, "
-                "pass_threshold, pass_pattern)."
+                "They are optional for script, script_extract, or custom (plugin) "
+                "comparator types. "
+                "Other keys are forwarded to the comparator constructor as kwargs "
+                "(e.g. rtol, atol, encoding, tables, data_filter, pass_threshold, "
+                "pass_pattern) and are STRICT: a parameter the comparator does not "
+                "declare fails construction loudly. Use 'options' for plugin-owned "
+                "configuration. Framework resolves actual/baseline and plugin "
+                "path_params-declared paths against the workspace before the "
+                "comparator is constructed."
             ),
             "properties": {
                 "actual": {
                     "type": "string",
-                    "description": "File produced by the test command. Optional when type is 'script' or a workspace plugin.",
+                    "description": "File produced by the test command. Optional when type is 'script', 'script_extract', or a workspace plugin.",
                 },
                 "baseline": {
                     "type": "string",
-                    "description": "Golden/reference file. Optional when type is 'script' or a workspace plugin.",
+                    "description": "Golden/reference file. Optional when type is 'script', 'script_extract', or a workspace plugin.",
                 },
                 "type": {
                     "type": "string",
                     "description": (
-                        "Comparator type. Built-ins: text, json, csv, xml, h5, binary, script. "
+                        "Comparator type. Built-ins: text, json, csv, xml, h5, binary, "
+                        "script, script_extract. "
                         "Custom (workspace plugin) comparator types are also allowed. "
                         "Omit to auto-detect from the actual file extension."
                     ),
                 },
+                "options": {
+                    "type": "object",
+                    "additionalProperties": True,
+                    "description": (
+                        "Plugin-owned configuration namespace. Entries are merged "
+                        "into the comparator constructor kwargs (explicit top-level "
+                        "keys take precedence). Preferred over adding plugin-specific "
+                        "top-level keys; unknown parameters fail loudly at "
+                        "construction, so typos are reported instead of silently "
+                        "falling back to defaults."
+                    ),
+                },
+                "channels": {
+                    "type": "object",
+                    "description": (
+                        "Per-channel tolerance overrides for data-lane comparators "
+                        "(script_extract / extractor plugins). Maps channel name to "
+                        "{'rtol':…, 'atol':…, 'data_filter':…}. Channels not listed "
+                        "use default_channel."
+                    ),
+                },
+                "default_channel": {
+                    "type": "object",
+                    "description": (
+                        "Default tolerance spec {'rtol':…, 'atol':…, 'data_filter':…} "
+                        "applied to channels not listed in 'channels'."
+                    ),
+                },
                 "start_line": {"type": "integer", "minimum": 1, "description": "Only compare from this line (1-based)."},
                 "end_line": {"type": "integer", "minimum": 1, "description": "Only compare up to this line (1-based)."},
                 "start_column": {"type": "integer", "minimum": 1, "description": "Only compare from this column (1-based)."},
                 "end_column": {"type": "integer", "minimum": 1, "description": "Only compare up to this column (1-based)."},
-                "script": {"type": "string", "description": "Path to the analysis script (script / custom comparator types)."},
+                "script": {"type": "string", "description": "Path to the analysis script (script / script_extract / custom comparator types)."},
                 "case_dir": {"type": "string", "description": "Working directory for the analysis script."},
                 "cwd": {"type": "string", "description": "Working directory for script execution (alias for case_dir)."},
                 "pass_threshold": {"type": "number", "description": "Numeric threshold below which the comparison is considered a pass."},
@@ -164,11 +198,24 @@
         },
         "executionSpec": {
             "type": "object",
-            "additionalProperties": False,
             "description": (
                 "Execution semantics (v2): single-command shorthand "
                 "(command/args/timeout/retry_count/env) OR the full steps form "
-                "(steps[]) — 二选一. Case-level env applies to all steps."
+                "(steps[]) — 二选一，由 oneOf 强制互斥. Case-level env applies "
+                "to all steps. Declaring both forms is a schema violation."
+            ),
+            "oneOf": [
+                {"$ref": "#/$defs/commandExecution"},
+                {"$ref": "#/$defs/stepsExecution"},
+            ],
+        },
+        "commandExecution": {
+            "type": "object",
+            "required": ["command", "args"],
+            "additionalProperties": False,
+            "description": (
+                "Single-command shorthand form: requires command + args; "
+                "the steps form must not be declared alongside."
             ),
             "properties": {
                 "command": {
@@ -201,12 +248,41 @@
                         "and scheduler-injected environment variables."
                     ),
                 },
+            },
+        },
+        "stepsExecution": {
+            "type": "object",
+            "required": ["steps"],
+            "additionalProperties": False,
+            "description": (
+                "Full steps form: requires steps; command/args must not be "
+                "declared alongside."
+            ),
+            "properties": {
                 "steps": {
                     "type": "array",
                     "minItems": 1,
                     "items": {"$ref": "#/$defs/step"},
                     "description": "Steps run in order with fail-fast semantics.",
                 },
+                "timeout": {
+                    "type": ["number", "null"],
+                    "description": "Timeout in seconds (default 3600); null = no limit.",
+                },
+                "retry_count": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Retries after the first failure; passing after retry marks the result flaky.",
+                },
+                "env": {
+                    "type": "object",
+                    "additionalProperties": {"type": ["string", "number", "boolean"]},
+                    "description": (
+                        "Case-level environment variables injected into every "
+                        "step (subprocess). Overrides setup-level and "
+                        "scheduler-injected environment variables."
+                    ),
+                },
             },
         },
         "schedulingSpec": {
diff --git a/src/symtest/config/normalize.py b/src/symtest/config/normalize.py
new file mode 100644
index 0000000..15e4ae3
--- /dev/null
+++ b/src/symtest/config/normalize.py
@@ -0,0 +1,43 @@
+"""Draft 配置规范化（宽松形态归一，1.4 原则 6 的 DSL 层配套）。
+
+core parser 全系统唯一且只接受 canonical TestCase；半成品/草稿配置
+（v1 迁移输出等）先经 ``normalize_draft_config`` 补齐
+必填字段缺省值，再调用严格 ``core.config_loader.parse_test_cases``。
+
+本模块属于 ``config`` 层（DSL 规范化），不在 ``core`` 内 —— core 不提供
+任何宽松解析形态。
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict
+
+
+def normalize_draft_config(config: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize half-finished draft cases into canonical config dicts.
+
+    为缺字段的 case 补齐 canonical 必填项的缺省值（深拷贝，不改动入参）：
+
+    - case 级：``name`` / ``execution`` / ``expected``；
+    - 单命令形态：``execution.command`` / ``execution.args``；
+    - steps 形态：每个 step 的 ``command`` / ``args`` / ``expected``。
+
+    ``import`` 引用项原样跳过（由 import 展开管线处理）。
+    """
+    normalized = copy.deepcopy(config)
+    for case in normalized.get("test_cases", []):
+        if not isinstance(case, dict) or "import" in case:
+            continue
+        case.setdefault("name", "")
+        execution = case.setdefault("execution", {})
+        if "steps" in execution:
+            for step in execution.get("steps", []):
+                if isinstance(step, dict):
+                    step.setdefault("command", "")
+                    step.setdefault("args", [])
+                    step.setdefault("expected", {})
+        else:
+            execution.setdefault("command", "")
+            execution.setdefault("args", [])
+        case.setdefault("expected", {})
+    return normalized
diff --git a/src/symtest/core/base_runner.py b/src/symtest/core/base_runner.py
index 9d38c36..0ab8bbf 100644
--- a/src/symtest/core/base_runner.py
+++ b/src/symtest/core/base_runner.py
@@ -51,10 +51,16 @@ def __init__(self, config_file: str, workspace: Optional[str] = None,
         self.resume = resume
 
         # --- workspace plugin directories ---
-        resolved_plugin_dirs: List[str] = list(plugin_dirs) if plugin_dirs else []
+        # Resolve every dir against the parent CWD here, so process workers
+        # receive absolute paths via the pool initializer and never have to
+        # resolve anything against their own CWD.
+        resolved_plugin_dirs: List[str] = (
+            [str(Path(d).resolve()) for d in plugin_dirs] if plugin_dirs else []
+        )
         default_plugin_dir = self.workspace / "comparators"
         if default_plugin_dir.is_dir() and str(default_plugin_dir.resolve()) not in resolved_plugin_dirs:
             resolved_plugin_dirs.append(str(default_plugin_dir.resolve()))
+        self.plugin_dirs = resolved_plugin_dirs
         ComparatorFactory.set_plugin_dirs(resolved_plugin_dirs)
         self.results: Dict[str, Any] = {
             "total": 0,
@@ -176,7 +182,6 @@ def run_tests(self) -> bool:
                             "description": case.description or None,
                             "tags": case.tags or [],
                         }
-                        self._fill_hint_command(skip_result, case.name)
                         self.results["details"].append(skip_result)
                         logger.warning("⊘ Test %d skipped: %s", i, case.name)
                         logger.warning("  Reason: %s", skip_result["message"])
@@ -191,7 +196,6 @@ def run_tests(self) -> bool:
                 result["expected"] = case.expected if case.expected else None
                 result["description"] = case.description or None
                 result["tags"] = case.tags or []
-                self._fill_hint_command(result, case.name)
 
                 self.results["details"].append(result)
                 duration = result.get("duration", 0)
@@ -298,23 +302,6 @@ def _topological_order(self) -> List[TestCase]:
 
         return result
 
-    def _fill_hint_command(self, result: Dict[str, Any], case_name: str) -> None:
-        """Fill in the concrete CLI command inside ``next_action_hint``.
-
-        The execution layer attaches the hint with ``command=None`` because it
-        does not know the config file path; the runner does.
-        """
-        hint = result.get("next_action_hint")
-        if not hint or hint.get("command"):
-            return
-        config = str(self.config_path)
-        if hint.get("action") == "update_baseline":
-            hint["command"] = (
-                f'symtest run "{config}" --update-baseline -t "{case_name}"'
-            )
-        else:
-            hint["command"] = f'symtest run "{config}" -t "{case_name}"'
-
     def _apply_xfail_status(self, result: Dict[str, Any], case: "TestCase") -> None:
         """Apply xfail (expected failure) status mapping to a test result.
 
diff --git a/src/symtest/core/config_loader.py b/src/symtest/core/config_loader.py
index fa3411c..c3b81a5 100644
--- a/src/symtest/core/config_loader.py
+++ b/src/symtest/core/config_loader.py
@@ -17,7 +17,7 @@
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from .test_case import TestCase, TestCaseStep
+from .test_case import TestCase, TestStep
 from ..utils.path_resolver import resolve_paths
 
 logger = logging.getLogger("symtest.core.config_loader")
@@ -94,8 +94,6 @@ def parse_test_cases(
     config: Dict[str, Any],
     workspace: Optional[Path] = None,
     path_resolver: Any = None,
-    *,
-    strict: bool = True,
 ) -> List[TestCase]:
     """Parse ``config['test_cases']`` (Schema v2) into ``TestCase`` objects.
 
@@ -106,11 +104,9 @@ def parse_test_cases(
     When *workspace* and *path_resolver* are provided (Runner mode),
     command/args paths are resolved.
 
-    Required-field validation is controlled by the explicit *strict* flag
-    (1.4 原则 6：拆除隐式 TUI 后门).  Runners use the default ``strict=True``;
-    the TUI passes ``strict=False`` explicitly and owns the relaxed form
-    (missing fields get sensible defaults and raw values are kept as-is for
-    display purposes).
+    解析器全系统唯一且只接受 canonical TestCase：必填字段缺失即抛
+    ``ValueError``（1.4 原则 6：无宽松模式后门）。编辑半成品的
+    宽松形态由调用方（如迁移命令）先 normalize 后再调用本函数。
     """
     cases: List[TestCase] = []
     resolve = workspace is not None and path_resolver is not None
@@ -122,8 +118,16 @@ def parse_test_cases(
 
         # Normalize both modes to a single ``steps`` list.  A single-command
         # shorthand becomes a single-element list; a sequence case uses its
-        # ``execution.steps`` directly.
+        # ``execution.steps`` directly.  Declaring both forms is ambiguous
+        # (Schema v2 oneOf 互斥) and is rejected outright instead of being
+        # silently resolved.
         is_sequence = "steps" in execution
+        if is_sequence and ("command" in execution or "args" in execution):
+            raise ValueError(
+                f"Test case '{case.get('name', 'unnamed')}': 'execution' "
+                f"declares both 'steps' and 'command'/'args' — the two forms "
+                f"are mutually exclusive (choose one)"
+            )
         if is_sequence:
             step_configs: List[Dict[str, Any]] = list(execution.get("steps", []))
         else:
@@ -135,15 +139,14 @@ def parse_test_cases(
                 "retry_count": execution.get("retry_count", 0),
             }]
 
-        steps: List[TestCaseStep] = []
+        steps: List[TestStep] = []
         for step in step_configs:
-            if strict:
-                step_required = ["command", "args", "expected"]
-                if not all(field in step for field in step_required):
-                    raise ValueError(
-                        f"Step in test case '{case.get('name', 'unnamed')}' "
-                        f"is missing required fields"
-                    )
+            step_required = ["command", "args", "expected"]
+            if not all(field in step for field in step_required):
+                raise ValueError(
+                    f"Step in test case '{case.get('name', 'unnamed')}' "
+                    f"is missing required fields"
+                )
             if resolve:
                 executable, resolved_args = _split_and_resolve(
                     step["command"], step["args"], workspace, path_resolver
@@ -151,7 +154,7 @@ def parse_test_cases(
             else:
                 executable = step.get("command", "")
                 resolved_args = step.get("args", [])
-            steps.append(TestCaseStep(
+            steps.append(TestStep.from_flat(
                 command=executable,
                 args=resolved_args,
                 expected=step["expected"] if "expected" in step else step.get("expected", {}),
@@ -175,14 +178,13 @@ def parse_test_cases(
             ))
         else:
             # ── Single-command mode: execution shorthand fields → steps[0] ──
-            if strict:
-                missing = [f for f in ("name", "execution", "expected") if f not in case]
-                missing += [f for f in ("command", "args") if f not in execution]
-                if missing:
-                    raise ValueError(
-                        f"Test case {case.get('name', 'unnamed')} "
-                        f"is missing required fields"
-                    )
+            missing = [f for f in ("name", "execution", "expected") if f not in case]
+            missing += [f for f in ("command", "args") if f not in execution]
+            if missing:
+                raise ValueError(
+                    f"Test case {case.get('name', 'unnamed')} "
+                    f"is missing required fields"
+                )
             cases.append(TestCase(
                 name=case.get("name", ""),
                 steps=None,
diff --git a/src/symtest/core/orchestration/sequence.py b/src/symtest/core/orchestration/sequence.py
index fad6e62..a848ec7 100644
--- a/src/symtest/core/orchestration/sequence.py
+++ b/src/symtest/core/orchestration/sequence.py
@@ -7,7 +7,8 @@
   （executor 参数仍可注入，保持 monkeypatch 支持）；
 - case 级判定经由 ``validation.validator.validate_result``（只读），
   ``--update-baseline`` 经由 ``orchestration.accept`` accept 步骤；
-- ``next_action_hint`` 由 ``reporting.diagnosis`` 生成。
+- 结果只携带 ``failure_kind``；``next_action_hint`` 由表现层装配点
+  （``reporting.diagnosis.attach_next_action_hint``）填充（原则 5）。
 """
 from __future__ import annotations
 
@@ -20,22 +21,21 @@
 from ..validation.assertions import ValidationError  # noqa: F401  (legacy except 兼容)
 from .accept import apply_baseline_accept
 from .single import execute_single_test_case
-from ...reporting.diagnosis import build_next_action_hint
 
 logger = logging.getLogger("symtest.core.orchestration.sequence")
 
 
 # ---------------------------------------------------------------------------
-# Step helper (duck-typed access for TestCaseStep / dict)
+# Step helper (duck-typed access for TestStep / dict)
 # ---------------------------------------------------------------------------
 
 def _step_attr(step: Any, key: str, default: Any = None) -> Any:
-    """Get attribute from a ``TestCaseStep``（dict 支持已在 Phase 3 移除）。"""
+    """Get attribute from a ``TestStep``（dict 支持已在 Phase 3 移除）。"""
     return getattr(step, key, default)
 
 
 # ---------------------------------------------------------------------------
-# Shared sequence execution (TestCaseStep list → result dict)
+# Shared sequence execution (TestStep list → result dict)
 # ---------------------------------------------------------------------------
 
 def execute_sequence(
@@ -54,7 +54,7 @@ def execute_sequence(
 ) -> Dict[str, Any]:
     """Execute a sequence test case (fail-fast).
 
-    ``steps`` must be a list of ``TestCaseStep`` objects（v2：dict 形态已在
+    ``steps`` must be a list of ``TestStep`` objects（v2：dict 形态已在
     Schema v2 落地后移除，跨进程路径由 process_worker 重建为对象）。
 
     Parameters
@@ -101,7 +101,6 @@ def execute_sequence(
     failed_step = None
     step_results: List[Dict[str, Any]] = []
     case_assertion_results: List[Dict[str, Any]] = []
-    case_hint: Optional[Dict[str, Any]] = None
 
     prefix = f"{print_prefix} " if print_prefix else ""
 
@@ -289,9 +288,6 @@ def execute_sequence(
                     all_passed = False
                     failed_step = len(steps) + 1  # synthetic step number
                     case_assertion_results = case_vr.assertion_results
-                    case_hint = build_next_action_hint(
-                        case_vr.failure_kind, update_baseline=update_baseline,
-                    )
                     last_result = {
                         "name": case_name,
                         "status": "failed",
@@ -317,9 +313,6 @@ def execute_sequence(
             all_passed = False
             failed_step = len(steps) + 1  # synthetic step number
             case_assertion_results = getattr(exc, "assertion_results", [])
-            case_hint = build_next_action_hint(
-                getattr(exc, "failure_kind", None), update_baseline=update_baseline,
-            )
             last_result = {
                 "name": case_name,
                 "status": "failed",
@@ -374,10 +367,12 @@ def execute_sequence(
     else:
         slim_output = ""
 
-    # ── assertion_results / next_action_hint resolution ──
+    # ── assertion_results resolution ──
     # Case-level assertion data takes precedence; otherwise propagate the
     # failed step's data so sequence results honor the same contract as
-    # single-command results.
+    # single-command results.  ``next_action_hint`` is left None here: the
+    # presentation layer (reporting attach point) builds it from
+    # ``failure_kind``（原则 5 单向流）.
     if case_assertion_results:
         assertion_results = case_assertion_results
     elif not all_passed and last_result is not None:
@@ -385,13 +380,6 @@ def execute_sequence(
     else:
         assertion_results = []
 
-    if case_hint is not None:
-        next_action_hint = case_hint
-    elif not all_passed and last_result is not None:
-        next_action_hint = last_result.get("next_action_hint")
-    else:
-        next_action_hint = None
-
     command_summary = " -> ".join(
         f"{_step_attr(s, 'command')} {' '.join(_step_attr(s, 'args'))}".strip()
         for s in steps
@@ -412,5 +400,5 @@ def execute_sequence(
         "attempts": last_result.get("attempts", 1) if last_result else 1,
         "flaky": last_result.get("flaky", False) if last_result else False,
         "assertion_results": assertion_results,
-        "next_action_hint": next_action_hint,
+        "next_action_hint": None,
     }
diff --git a/src/symtest/core/orchestration/single.py b/src/symtest/core/orchestration/single.py
index 6950514..797fcac 100644
--- a/src/symtest/core/orchestration/single.py
+++ b/src/symtest/core/orchestration/single.py
@@ -8,7 +8,8 @@
 - 判定交给 ``validation.validator.validate_result``（只读）；
 - ``--update-baseline`` 写盘改为本层独立 accept 步骤
   （``accept.apply_baseline_accept``）；
-- ``next_action_hint`` 由 ``reporting.diagnosis`` 生成（原则 5）。
+- 结果只携带 ``failure_kind``；``next_action_hint`` 由表现层装配点
+  （``reporting.diagnosis.attach_next_action_hint``）填充（原则 5）。
 
 Phase 3 Schema v2：``case`` 只接受 ``ExecutionSpec``，期望规格由调用方
 显式传入（``expectation``），不再回落读取旧 dict 形态。
@@ -24,7 +25,6 @@
 from ..validation.validator import _trim_compare_failures, validate_result
 from ..validation.assertions import ValidationError
 from .accept import apply_baseline_accept
-from ...reporting.diagnosis import build_next_action_hint
 
 logger = logging.getLogger("symtest.core.orchestration.single")
 
@@ -58,14 +58,12 @@ def _execute_command_once(
     if exec_result.error is not None:
         result.message = f"Execution error: {exec_result.error}"
         result.failure_kind = "execution_error"
-        result.next_action_hint = build_next_action_hint("execution_error")
     elif exec_result.timed_out:
         result.status = "timeout"
         result.failure_kind = "timeout"
         result.message = (
             f"Timeout reached! Killed after {exec_result.timeout_limit} seconds."
         )
-        result.next_action_hint = build_next_action_hint("timeout")
     else:
         try:
             vr = validate_result(
@@ -78,18 +76,13 @@ def _execute_command_once(
             result.compare_failures = _trim_compare_failures(exc.compare_failures)
             result.baseline_updated = list(exc.baseline_updated)
             result.assertion_results = list(exc.assertion_results)
-            result.next_action_hint = build_next_action_hint(
-                exc.failure_kind, update_baseline=update_baseline,
-            )
         except AssertionError as exc:
             # Legacy AssertionError catch for backward compatibility
             result.message = str(exc)
             result.failure_kind = result.failure_kind or "unknown"
-            result.next_action_hint = build_next_action_hint(result.failure_kind)
         except Exception as exc:
             result.message = f"Execution error: {str(exc)}"
             result.failure_kind = "execution_error"
-            result.next_action_hint = build_next_action_hint("execution_error")
         else:
             if vr.passed:
                 result.status = "passed"
@@ -99,9 +92,6 @@ def _execute_command_once(
                 result.failure_kind = vr.failure_kind
                 result.compare_failures = _trim_compare_failures(vr.compare_failures)
                 result.assertion_results = vr.assertion_results
-                result.next_action_hint = build_next_action_hint(
-                    vr.failure_kind, update_baseline=update_baseline,
-                )
                 # ── accept 步骤（原则 3：写盘在编排层，不在 Validator） ──
                 if update_baseline and vr.failure_kind == "file_compare":
                     accepted = apply_baseline_accept(vr, workspace)
@@ -111,7 +101,6 @@ def _execute_command_once(
                         result.failure_kind = None
                         result.compare_failures = []
                         result.assertion_results = accepted
-                        result.next_action_hint = None
 
     result.duration = time.perf_counter() - start_time
     return result.to_dict()
diff --git a/src/symtest/core/parallel_runner.py b/src/symtest/core/parallel_runner.py
index 53457ee..6b51a4c 100644
--- a/src/symtest/core/parallel_runner.py
+++ b/src/symtest/core/parallel_runner.py
@@ -8,10 +8,22 @@
 from .base_runner import BaseRunner
 from .test_case import TestCase
 from .process_worker import run_test_in_process
+from ..file_comparator.factory import ComparatorFactory
 
 logger = logging.getLogger("symtest.core.parallel_runner")
 
 
+def _init_process_worker(plugin_dirs):
+    """ProcessPoolExecutor initializer: register plugin dirs in each worker.
+
+    Replaces the old ``os.environ`` back-channel — plugin directories are
+    passed explicitly through ``initargs`` and registered before any task
+    runs, so the lazy ``_load_comparators()`` in the worker discovers the
+    same workspace plugins as the parent.
+    """
+    ComparatorFactory.set_plugin_dirs(plugin_dirs or [])
+
+
 class AtomicSemaphore:
     """
     支持原子级多令牌获取的信号量，消除逐个 acquire 导致的部分占有死锁。
@@ -129,12 +141,7 @@ def run_tests(self) -> bool:
             
             start_time = time.time()
             
-            if self.execution_mode == "process":
-                executor_class = ProcessPoolExecutor
-            else:
-                executor_class = ThreadPoolExecutor
-            
-            with executor_class(max_workers=self.max_workers) as executor:
+            with self._make_executor() as executor:
                 self._run_dag(executor)
             
             end_time = time.time()
@@ -163,20 +170,30 @@ def run_tests(self) -> bool:
             # 确保teardown总是被执行
             self.setup_manager.teardown_all()
     
+    def _make_executor(self):
+        """Create the executor for the configured execution mode.
+
+        Process mode registers ``_init_process_worker`` as the pool
+        initializer so each spawned worker receives the plugin directories
+        explicitly (no ``os.environ`` back-channel).
+        """
+        if self.execution_mode == "process":
+            return ProcessPoolExecutor(
+                max_workers=self.max_workers,
+                initializer=_init_process_worker,
+                initargs=(self.plugin_dirs,),
+            )
+        return ThreadPoolExecutor(max_workers=self.max_workers)
+
     def _run_tests_flat(self) -> bool:
         """Original flat submission (no depends_on), kept for backward compat."""
         logger.info("Starting parallel test execution... Total tests: %d", self.results["total"])
         logger.info("Execution mode: %s, Max workers: %s", self.execution_mode, self.max_workers or "auto")
         logger.info("=" * 50)
-        
+
         start_time = time.time()
-        
-        if self.execution_mode == "process":
-            executor_class = ProcessPoolExecutor
-        else:
-            executor_class = ThreadPoolExecutor
-            
-        with executor_class(max_workers=self.max_workers) as executor:
+
+        with self._make_executor() as executor:
             # 提交所有测试任务
             if self.execution_mode == "process":
                 # 进程模式：使用独立的工作器函数（v2 wire dict，含 env）
@@ -382,7 +399,6 @@ def _case_command_str(case: Optional[TestCase]) -> str:
     def _update_results_skipped(self, result: Dict[str, Any], test_index: int, case_name: str) -> None:
         """Thread-safe result update for skipped cases (no xfail processing)."""
         with self.lock:
-            self._fill_hint_command(result, case_name)
             self.results["details"].append(result)
             logger.warning("⊘ Test %d skipped: %s", test_index, case_name)
             if result.get("message"):
@@ -400,7 +416,6 @@ def _update_results(self, result: Dict[str, Any], test_index: int, case: TestCas
             # Apply xfail status mapping before counting
             self._apply_xfail_status(result, case)
 
-            self._fill_hint_command(result, case.name)
             self.results["details"].append(result)
             duration = result.get("duration", 0)
             status = result["status"]
diff --git a/src/symtest/core/process_worker.py b/src/symtest/core/process_worker.py
index fa142dc..40ed6b6 100644
--- a/src/symtest/core/process_worker.py
+++ b/src/symtest/core/process_worker.py
@@ -3,7 +3,7 @@
 用于多进程并行测试执行，避免序列化问题
 
 Phase 3 Schema v2：跨进程传递 v2 wire dict（``TestCase.to_dict()`` 输出），
-本模块负责将其重建为 ``ExecutionSpec`` / ``TestCaseStep`` 对象后进入编排层。
+本模块负责将其重建为 ``ExecutionSpec`` / ``TestStep`` 对象后进入编排层。
 """
 
 import logging
@@ -11,17 +11,17 @@
 
 from .orchestration.sequence import execute_sequence
 from .orchestration.single import execute_single_test_case
-from .test_case import ExecutionSpec, TestCaseStep
+from .test_case import ExecutionSpec, TestStep
 
 logger = logging.getLogger("symtest.core.process_worker")
 
 
 def _spec_from_v2(case_data: Dict[str, Any]) -> ExecutionSpec:
-    """v2 wire dict（case.to_dict()）→ ExecutionSpec（含 TestCaseStep 重建）。"""
+    """v2 wire dict（case.to_dict()）→ ExecutionSpec（含 TestStep 重建）。"""
     execution = case_data.get("execution") or {}
     if "steps" in execution:
         steps = [
-            TestCaseStep(
+            TestStep.from_flat(
                 command=s["command"],
                 args=s["args"],
                 expected=s.get("expected") or {},
diff --git a/src/symtest/core/result.py b/src/symtest/core/result.py
index 43511eb..5ab2a38 100644
--- a/src/symtest/core/result.py
+++ b/src/symtest/core/result.py
@@ -1,7 +1,7 @@
 """TestResult：Execution + Validation + 编排元数据的组合类型（1.4 v2）。
 
 ``to_dict()`` 产出与 1.3 完全一致的 ``TestResultData`` wire format ——
-runner / reporter / TUI / CLI 消费的结果 JSON 结构逐位保持，本类型只是
+runner / reporter / CLI 消费的结果 JSON 结构逐位保持，本类型只是
 编排层内部的结构化表示。
 """
 from dataclasses import dataclass, field
diff --git a/src/symtest/core/test_case.py b/src/symtest/core/test_case.py
index 45bde15..e4383ab 100644
--- a/src/symtest/core/test_case.py
+++ b/src/symtest/core/test_case.py
@@ -8,34 +8,26 @@
 
 形态说明：
 - ``to_dict()`` 输出 v2 分层配置形态（execution/expected/scheduling），
-  可直接写入配置文件（TUI 保存路径即消费方）；
-- 构造函数保留平铺关键字参数作为 legacy 语义归一入口（TUI 编辑路径、
-  迁移等价性测试的 legacy 侧复用它）；
+  可直接写入配置文件；
+- 构造路径唯一：DSL 平铺关键字参数（配置解析、迁移
+  等价性测试共用同一入口）；子 Spec 是内部数据结构，不是构造参数；
 - ``case.command`` / ``case.expected`` / ``case.env`` ... 等属性直通访问器
-  映射到子 Spec，使现有 ``case.xxx`` 访问点零改动。
+  是唯一的公开读写接口，映射到子 Spec；
+- 序列步骤为 :class:`TestStep`（execution + expectation 分层）；
+  ``TestStep.from_flat`` 是 DSL 平铺字段的归一入口。
 """
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
 
-@dataclass
-class TestCaseStep:
-    """A single step within a sequence test case."""
-    __test__ = False
-    command: str
-    args: List[str]
-    expected: Dict[str, Any]
-    timeout: Optional[float] = None
-    retry_count: int = 0
-
-
 @dataclass
 class ExecutionSpec:
     """执行语义：一个执行单元（case 或 step）要执行什么。
 
     纯数据，不包含任何判定语义（expected 属于 ExpectationSpec）。
-    ``steps`` 非 None 表示 sequence 模式（steps 为原子"执行+判定"对列表）；
-    为 None 表示单命令模式，由 ``command/args/timeout/retry_count`` 描述。
+    ``steps`` 非 None 表示 sequence 模式（steps 为 ``TestStep`` 列表，
+    每项是原子"执行+判定"对）；为 None 表示单命令模式，由
+    ``command/args/timeout/retry_count`` 描述。
     """
     __test__ = False
     name: str = ""
@@ -44,7 +36,7 @@ class ExecutionSpec:
     timeout: Optional[float] = None
     retry_count: int = 0
     env: Dict[str, str] = field(default_factory=dict)
-    steps: Optional[List[TestCaseStep]] = None
+    steps: Optional[List["TestStep"]] = None
 
 
 @dataclass
@@ -59,6 +51,81 @@ class ExpectationSpec:
     assertions: Dict[str, Any] = field(default_factory=dict)
 
 
+@dataclass
+class TestStep:
+    """序列中的一个原子步骤：execution + expectation 分层（1.4 v2 模型）。
+
+    DSL 形态不变（step dict：``command/args/expected/timeout/retry_count``），
+    由 parser / ``from_flat`` 负责归一；本类型提供平铺直通访问器，使
+    duck-typing 消费点（``_step_attr``、``compute_config_hash`` 等）零改动。
+    """
+    __test__ = False
+    execution: ExecutionSpec
+    expectation: ExpectationSpec
+
+    @classmethod
+    def from_flat(
+        cls,
+        command: str,
+        args: List[str],
+        expected: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        retry_count: int = 0,
+    ) -> "TestStep":
+        """DSL 平铺字段 → 分层 TestStep（parser / wire dict 重建入口）。"""
+        return cls(
+            execution=ExecutionSpec(
+                command=command, args=args,
+                timeout=timeout, retry_count=retry_count,
+            ),
+            expectation=ExpectationSpec(assertions=expected if expected else {}),
+        )
+
+    # ── execution 直通访问器 ─────────────────────────────────────────────
+
+    @property
+    def command(self) -> str:
+        return self.execution.command
+
+    @command.setter
+    def command(self, value: str) -> None:
+        self.execution.command = value
+
+    @property
+    def args(self) -> List[str]:
+        return self.execution.args
+
+    @args.setter
+    def args(self, value: List[str]) -> None:
+        self.execution.args = value
+
+    @property
+    def timeout(self) -> Optional[float]:
+        return self.execution.timeout
+
+    @timeout.setter
+    def timeout(self, value: Optional[float]) -> None:
+        self.execution.timeout = value
+
+    @property
+    def retry_count(self) -> int:
+        return self.execution.retry_count
+
+    @retry_count.setter
+    def retry_count(self, value: int) -> None:
+        self.execution.retry_count = value
+
+    # ── expectation 直通访问器 ───────────────────────────────────────────
+
+    @property
+    def expected(self) -> Dict[str, Any]:
+        return self.expectation.assertions
+
+    @expected.setter
+    def expected(self, value: Dict[str, Any]) -> None:
+        self.expectation.assertions = value if value else {}
+
+
 @dataclass
 class SchedulingSpec:
     """调度语义：什么时候、以什么资源执行（原则 4：编排层消费）。"""
@@ -92,7 +159,7 @@ def __init__(
         description: str = "",
         timeout: Optional[float] = None,
         resources: Optional[Dict[str, Any]] = None,
-        steps: Optional[List[TestCaseStep]] = None,
+        steps: Optional[List["TestStep"]] = None,
         tags: Optional[List[str]] = None,
         retry_count: int = 0,
         expected_failure: bool = False,
@@ -100,14 +167,13 @@ def __init__(
         xfail_quiet: bool = False,
         depends_on: Optional[List[str]] = None,
         env: Optional[Dict[str, str]] = None,
-        execution: Optional[ExecutionSpec] = None,
-        expectation: Optional[ExpectationSpec] = None,
-        scheduling: Optional[SchedulingSpec] = None,
     ) -> None:
         """构造 TestCase。
 
-        平铺关键字参数（v1 形态）在 ``execution/expectation/scheduling``
-        未显式给出时归一存入对应子 Spec；显式传入子 Spec 时平铺参数被忽略。
+        构造路径唯一：DSL 平铺关键字参数归一存入对应子 Spec。
+        传入 ``execution=`` / ``expectation=`` / ``scheduling=`` 会被
+        TypeError 拒绝——子 Spec 是内部数据结构，不是构造参数，
+        不存在"平铺参数被静默忽略"的第二语义。
         """
         self.name = name
         self.description = description
@@ -116,7 +182,7 @@ def __init__(
         self.xfail_reason = xfail_reason
         self.xfail_quiet = xfail_quiet
 
-        self.execution = execution if execution is not None else ExecutionSpec(
+        self.execution = ExecutionSpec(
             name=name,
             command=command,
             args=args if args is not None else [],
@@ -125,10 +191,10 @@ def __init__(
             env=env if env else {},
             steps=steps,
         )
-        self.expectation = expectation if expectation is not None else ExpectationSpec(
+        self.expectation = ExpectationSpec(
             assertions=expected if expected else {},
         )
-        self.scheduling = scheduling if scheduling is not None else SchedulingSpec(
+        self.scheduling = SchedulingSpec(
             depends_on=depends_on if depends_on else [],
             resources=resources,
         )
@@ -176,11 +242,11 @@ def env(self, value: Dict[str, str]) -> None:
         self.execution.env = value
 
     @property
-    def steps(self) -> Optional[List[TestCaseStep]]:
+    def steps(self) -> Optional[List["TestStep"]]:
         return self.execution.steps
 
     @steps.setter
-    def steps(self, value: Optional[List[TestCaseStep]]) -> None:
+    def steps(self, value: Optional[List["TestStep"]]) -> None:
         self.execution.steps = value
 
     # ── expectation / scheduling 直通访问器 ─────────────────────────────
@@ -213,7 +279,7 @@ def resources(self, value: Optional[Dict[str, Any]]) -> None:
     # ── 统一步骤访问（单命令模式返回单元素列表） ─────────────────────────
 
     @property
-    def all_steps(self) -> List[TestCaseStep]:
+    def all_steps(self) -> List["TestStep"]:
         """Return the unified list of steps regardless of mode.
 
         Single-command cases yield a single-element list; sequence cases yield
@@ -222,7 +288,7 @@ def all_steps(self) -> List[TestCaseStep]:
         """
         if self.execution.steps is not None:
             return self.execution.steps
-        return [TestCaseStep(
+        return [TestStep.from_flat(
             command=self.execution.command,
             args=self.execution.args,
             expected=self.expectation.assertions,
diff --git a/src/symtest/core/validation/assertions.py b/src/symtest/core/validation/assertions.py
index 97ca021..e179255 100644
--- a/src/symtest/core/validation/assertions.py
+++ b/src/symtest/core/validation/assertions.py
@@ -10,6 +10,7 @@
 from typing import Any, Dict, List, Optional
 
 from ...file_comparator.factory import ComparatorFactory
+from ...file_comparator.base_comparator import CompareContext
 
 logger = logging.getLogger("symtest.core.validation.assertions")
 
@@ -61,6 +62,9 @@ def _build_diff_summary(result: Any) -> Dict[str, Any]:
     - ``total_differences``
     - ``max_rel_error`` / ``max_abs_error`` (for cells that are numeric)
     - ``max_rel_error_at`` / ``max_abs_error_at`` (position string)
+
+    Data-lane results additionally carry per-channel ``channels``; each
+    channel contributes a ``passed`` flag and its own error stats.
     """
     differences = getattr(result, "differences", []) or []
     summary: Dict[str, Any] = {
@@ -87,6 +91,19 @@ def _build_diff_summary(result: Any) -> Dict[str, Any]:
                 summary["max_rel_error_at"] = pos
         except (ValueError, TypeError):
             pass
+
+    channels = getattr(result, "channels", None)
+    if channels:
+        summary["channels"] = {
+            ch.name: {
+                "passed": bool(ch.passed),
+                "rtol": ch.rtol,
+                "atol": ch.atol,
+                "max_abs_error": (ch.stats or {}).get("max_abs_error"),
+                "max_rel_error": (ch.stats or {}).get("max_rel_error"),
+            }
+            for ch in channels
+        }
     return summary
 
 
@@ -156,8 +173,10 @@ def compare_files(
         if baseline_path and workspace and not os.path.isabs(baseline_path):
             baseline_path = os.path.join(workspace, baseline_path)
 
-        # Auto-detect file type from extension
-        if not file_type:
+        # Auto-detect file type from extension (covers omitted type AND an
+        # explicit "auto" — never let "auto" degrade to a silent guess inside
+        # the factory when the file paths are available right here).
+        if not file_type or file_type == "auto":
             if not actual_path:
                 raise ValidationError(
                     "File type cannot be auto-detected: 'actual' path is empty. "
@@ -184,6 +203,19 @@ def compare_files(
         if "end_column" in method_params and method_params["end_column"] is not None:
             method_params["end_column"] = max(0, int(method_params["end_column"]) - 1)
 
+        # Plugin configuration namespace: "options" is framework-owned
+        # structure; its entries are merged into constructor kwargs.
+        # Explicit top-level keys take precedence (legacy compatibility).
+        options = comparator_kwargs.pop("options", None)
+        if options is not None:
+            if not isinstance(options, dict):
+                raise ValidationError(
+                    f"'options' must be an object of comparator parameters, "
+                    f"got: {type(options).__name__}",
+                    failure_kind="file_compare",
+                )
+            comparator_kwargs = {**options, **comparator_kwargs}
+
         # Collect tolerances for reporting (before they're consumed by factory)
         reported_kwargs = {
             k: v for k, v in comparator_kwargs.items()
@@ -191,13 +223,27 @@ def compare_files(
         }
 
         try:
+            # Lifecycle: the factory resolves path_params-declared parameters
+            # against the workspace BEFORE construction, so constructor-captured
+            # state (self.script, self.cwd, ...) already holds absolute paths.
             comparator = ComparatorFactory.create_comparator(
                 file_type,
-                verbose=True,  # always include diff details in the assertion message
+                workspace=workspace,
                 error_analysis=error_analysis,
                 **comparator_kwargs,
             )
-            result = comparator.compare_files(baseline_path, actual_path, **method_params)
+
+            ctx = CompareContext(
+                workspace=workspace,
+                actual=actual_path or None,
+                baseline=baseline_path or None,
+                # Invocation-level parameters only (file-lane window ranges).
+                # Comparator configuration lives solely in comparator state —
+                # one authoritative source per configuration value.
+                params=method_params,
+                error_analysis=error_analysis,
+            )
+            result = comparator.compare(ctx)
 
             # Build structured response
             diff_summary = _build_diff_summary(result)
@@ -215,6 +261,10 @@ def compare_files(
                 ),
                 "error_stats": result.error_stats,
                 "command_output": result.command_output,
+                "channels": (
+                    [ch.to_dict() for ch in result.channels]
+                    if result.channels else []
+                ),
             }
 
             if result.error:
diff --git a/src/symtest/core/validation/validator.py b/src/symtest/core/validation/validator.py
index cff1766..2c1fbbb 100644
--- a/src/symtest/core/validation/validator.py
+++ b/src/symtest/core/validation/validator.py
@@ -20,6 +20,9 @@
 # The text report already limits display to 5; this prevents large CSV/H5 diffs
 # from blowing up AI context windows.
 DEFAULT_MAX_DIFFERENCES = 50
+# Per-channel quota for data-lane results: one noisy channel must not crowd
+# out the others in AI-consumed JSON output.
+DEFAULT_MAX_CHANNEL_DIFFERENCES = 10
 
 
 def _trim_compare_failures(
@@ -32,20 +35,42 @@ def _trim_compare_failures(
     output previously carried the full list — which could reach megabytes for
     large CSV/H5 comparisons.  This function caps the retained differences so
     that AI consumers get a representative sample without context-window blowup.
+
+    For data-lane results the embedded ``channels`` entries get their own
+    per-channel difference quota so a single noisy channel cannot crowd out
+    the others.
     """
     if not compare_failures:
         return compare_failures
     trimmed: List[Dict[str, Any]] = []
     for cf in compare_failures:
         diffs = cf.get("differences", [])
+        changed = False
         if len(diffs) > max_diffs:
-            cf_copy = dict(cf)
-            cf_copy["differences"] = diffs[:max_diffs]
-            cf_copy["differences_truncated"] = True
-            cf_copy["differences_total"] = len(diffs)
-            trimmed.append(cf_copy)
-        else:
-            trimmed.append(cf)
+            cf = dict(cf)
+            cf["differences"] = diffs[:max_diffs]
+            cf["differences_truncated"] = True
+            cf["differences_total"] = len(diffs)
+            changed = True
+
+        channels = cf.get("channels")
+        if channels:
+            trimmed_channels = []
+            for ch in channels:
+                ch_diffs = ch.get("differences", [])
+                if len(ch_diffs) > DEFAULT_MAX_CHANNEL_DIFFERENCES:
+                    if not changed:
+                        cf = dict(cf)
+                        changed = True
+                    ch = dict(ch)
+                    ch["differences"] = ch_diffs[:DEFAULT_MAX_CHANNEL_DIFFERENCES]
+                    ch["differences_truncated"] = True
+                    ch["differences_total"] = len(ch_diffs)
+                trimmed_channels.append(ch)
+            if changed:
+                cf["channels"] = trimmed_channels
+
+        trimmed.append(cf)
     return trimmed
 
 
@@ -64,9 +89,22 @@ def _dispatch_file_compare(
     baseline_path = spec.get("baseline", "")
     file_type = spec.get("type", None)
 
+    # "options" is the framework-owned plugin configuration namespace; its
+    # entries are merged into constructor kwargs.  Explicit top-level keys
+    # take precedence (legacy compatibility).
+    options = spec.get("options")
+    if options is not None and not isinstance(options, dict):
+        raise ValidationError(
+            f"'options' must be an object of comparator parameters, "
+            f"got: {type(options).__name__}",
+            failure_kind="file_compare",
+        )
     # All remaining keys are forwarded as comparator kwargs
-    known_keys = {"actual", "baseline", "type"}
-    comparator_kwargs = {k: v for k, v in spec.items() if k not in known_keys}
+    known_keys = {"actual", "baseline", "type", "options"}
+    comparator_kwargs = {
+        **(options or {}),
+        **{k: v for k, v in spec.items() if k not in known_keys},
+    }
 
     try:
         cf_result = assertions.compare_files(
@@ -81,6 +119,7 @@ def _dispatch_file_compare(
             "assertion": "compare_files",
             "passed": True,
             "error_stats": cf_result.get("error_stats"),
+            "channels": cf_result.get("channels", []),
             "compare_failures": [],
             "baseline_updated": [],
             "message": "",
diff --git a/src/symtest/file_comparator/__init__.py b/src/symtest/file_comparator/__init__.py
index 0d3fff6..95c74b3 100644
--- a/src/symtest/file_comparator/__init__.py
+++ b/src/symtest/file_comparator/__init__.py
@@ -1,10 +1,44 @@
 """
 File comparison module for symtest.
-This module provides functionality for comparing different types of files.
+
+Public plugin contract (v2, three lanes):
+- ``ComparatorBase``      — root contract: ``compare(ctx) -> ComparisonResult``
+- ``CompareContext``      — invocation context (paths resolved by framework)
+- ``FileComparator``      — file lane (read_content/compare_content two-file model)
+- ``ExtractorComparator`` — data lane (extract channels, framework owns verdict)
+- ``ChannelData`` / ``ChannelResult`` — channel payload / per-channel sub-result
+- ``compare_numeric`` / ``NumericComparisonStats`` / ``parse_data_filter`` —
+  shared numeric core, public API for data-lane plugins
 """
 
 from .factory import ComparatorFactory
-from .result import ComparisonResult
-from .base_comparator import BaseComparator
+from .result import ComparisonResult, Difference, ChannelResult
+from .base_comparator import ComparatorBase, CompareContext
+from .file_comparator_base import FileComparator
+from .extractor_comparator import ExtractorComparator, ChannelData
+from .numeric_compare import (
+    compare_numeric,
+    NumericComparisonStats,
+    parse_data_filter,
+)
+
+# Historical alias: BaseComparator now names the root contract class
+# ComparatorBase.  (Breaking: the legacy two-file template moved to
+# FileComparator; plugins overriding compare_files must migrate.)
+BaseComparator = ComparatorBase
 
-__all__ = ['ComparatorFactory', 'ComparisonResult', 'BaseComparator']
\ No newline at end of file
+__all__ = [
+    'ComparatorFactory',
+    'ComparisonResult',
+    'Difference',
+    'ChannelResult',
+    'ChannelData',
+    'ComparatorBase',
+    'BaseComparator',
+    'CompareContext',
+    'FileComparator',
+    'ExtractorComparator',
+    'compare_numeric',
+    'NumericComparisonStats',
+    'parse_data_filter',
+]
diff --git a/src/symtest/file_comparator/base_comparator.py b/src/symtest/file_comparator/base_comparator.py
index 5467286..716346d 100644
--- a/src/symtest/file_comparator/base_comparator.py
+++ b/src/symtest/file_comparator/base_comparator.py
@@ -3,120 +3,126 @@
 
 """
 @file base_comparator.py
-@brief Base abstract class for file comparison operations
+@brief Root comparator contract: ``compare(ctx) -> ComparisonResult``
 @author Xiaotong Wang
 @date 2025
+
+Plugin contract v2 (three lanes, breaking change vs. the legacy two-file
+``BaseComparator``):
+
+- :class:`~symtest.file_comparator.file_comparator_base.FileComparator`
+  — **file lane**: two-file comparison; implements ``read_content`` /
+  ``compare_content`` (text/json/csv/xml/h5/binary).
+- :class:`~symtest.file_comparator.extractor_comparator.ExtractorComparator`
+  — **data lane**: plugin extracts ``{channel: ChannelData}``; verdict is
+  owned by the framework via per-channel numeric tolerance.
+- direct subclasses — **autonomous lane**: the plugin owns the verdict and
+  returns a fully populated ``ComparisonResult`` (``script`` comparator,
+  analysis-style plugins such as ``hourglass_tangent``).
+
+All lanes share the same invocation convention: the framework builds a
+:class:`CompareContext` and calls :meth:`ComparatorBase.compare`.  Path-like
+constructor parameters listed in ``path_params`` are resolved relative to the
+workspace by the framework *before* the comparator is constructed — plugins
+must not resolve paths against ``os.getcwd()`` themselves.
+
+**Configuration invariant (single source of truth)**: comparator
+configuration lives ONLY in constructor-captured instance state; it is
+normalized/resolved by the framework before construction.
+:class:`CompareContext` carries invocation-level context, never a second
+mutable copy of comparator configuration.
+
+**Strict configuration**: comparator constructors declare their parameters
+explicitly; unknown/misspelled parameters fail loudly at construction
+(factory raises a ``TypeError`` identifying the comparator type and its
+supported parameters).  A comparator may opt into free-form configuration by
+declaring its own ``**params`` catch-all — silence is always an explicit
+design choice of the plugin, never a framework default.
 """
 
 from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
 import logging
-from pathlib import Path
-from .result import ComparisonResult, Difference
+from typing import Any, Dict, Optional
+
+from .result import ComparisonResult
+
 
-class BaseComparator(ABC):
+@dataclass
+class CompareContext:
     """
-    @brief Base abstract class for all file comparators
-    @details This class defines the interface and common functionality for all file comparators.
-             It provides basic file comparison operations and logging capabilities.
+    @brief Invocation context handed to every comparator's ``compare()``.
+    @details Carries *invocation-level* context only.  Comparator
+             configuration (script paths, tolerances, thresholds, ...) is
+             owned by the comparator's constructor state — resolved and
+             validated before construction.  A configuration value must have
+             exactly one authoritative source.
+
+    @param workspace str|None: Workspace root; the framework already resolved
+           ``actual``/``baseline`` and ``path_params``-declared constructor
+           parameters against it before construction.
+    @param actual str|None: Path produced by the test command (``None`` for
+           comparators without a two-file input — never faked with "").
+    @param baseline str|None: Golden/reference path (``None`` when absent).
+    @param params dict: Invocation-level parameters for the file lane
+           (``start_line``/``end_line``/``start_column``/``end_column``,
+           already converted to 0-based).  Deliberately does NOT duplicate
+           comparator configuration.
+    @param error_analysis bool: Whether streaming error statistics were
+           requested (``--error-analysis``).
     """
-    
-    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False, **kwargs):
-        """
-        @brief Initialize the base comparator
-        @param encoding str: File encoding to use (default: "utf-8")
-        @param chunk_size int: Size of chunks for reading large files (default: 8192)
-        @param verbose bool: Enable verbose logging (default: False)
-        """
-        self.encoding = encoding
-        self.chunk_size = chunk_size
-        self.logger = logging.getLogger(f"file_comparator.{self.__class__.__name__}")
-        if verbose:
-            self.logger.setLevel(logging.DEBUG)
-    
-    @abstractmethod
-    def read_content(self, file_path, start_line=0, end_line=None, start_column=0, end_column=None):
-        """
-        @brief Read file content with specified range
-        @param file_path Path: Path to the file to read
-        @param start_line int: Starting line number (0-based)
-        @param end_line int: Ending line number (0-based, None for end of file)
-        @param start_column int: Starting column number (0-based)
-        @param end_column int: Ending column number (0-based, None for end of line)
-        @return object: File content in a format suitable for comparison
-        """
-        pass
+    workspace: Optional[str] = None
+    actual: Optional[str] = None
+    baseline: Optional[str] = None
+    params: Dict[str, Any] = field(default_factory=dict)
+    error_analysis: bool = False
+
+
+class ComparatorBase(ABC):
+    """
+    @brief Root abstract class for all comparators (all three lanes).
+    @details Deliberately minimal: only members that genuinely apply to every
+             lane live here.  File-specific concerns (encoding, chunk size,
+             window ranges) belong to :class:`FileComparator` and below.
+
+             The only contract is :meth:`compare`.  Subclasses declare
+             ``path_params`` so the framework can resolve workspace-relative
+             path arguments *before construction*; plugins never resolve
+             paths themselves.
+    """
+
+    #: Constructor parameter names that hold filesystem paths.  The framework
+    #: resolves each of them relative to the workspace (when not absolute)
+    #: before invoking the constructor.  ``actual``/``baseline`` are always
+    #: resolved and need not be listed here.
+    path_params: tuple = ()
+
+    #: Explicit comparator type name override (factory registration).
+    #: ``None`` falls back to the class-name convention (trailing
+    #: ``Comparator`` suffix stripped, lowercased).
+    comparator_type: Optional[str] = None
+
+    def __init__(self):
+        """Initialize shared infrastructure (per-class logger only)."""
+        self.logger = logging.getLogger(
+            f"file_comparator.{type(self).__name__}"
+        )
 
     @abstractmethod
-    def compare_content(self, content1, content2):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:
         """
-        @brief Compare two content objects and return comparison details
-        @param content1 object: First content object to compare
-        @param content2 object: Second content object to compare
-        @return tuple: (bool, list, bool) - (identical, differences, truncated)
+        @brief Run the comparison and return a fully populated result.
+        @param ctx CompareContext: Invocation context (paths already resolved).
+        @return ComparisonResult: Result with ``identical``/``differences`` and
+                optionally ``error``/``error_stats``/``channels``/
+                ``command_output`` populated.  ``file1``/``file2`` are ``None``
+                when the comparison has no two-file input.
         """
-        pass
 
-    def compare_files(self, file1, file2, start_line=0, end_line=None, start_column=0, end_column=None):
-        """
-        @brief Compare two files with the specified parameters
-        @param file1 Path: Path to the first file
-        @param file2 Path: Path to the second file
-        @param start_line int: Starting line number (0-based)
-        @param end_line int: Ending line number (0-based, None for end of file)
-        @param start_column int: Starting column number (0-based)
-        @param end_column int: Ending column number (0-based, None for end of line)
-        @return ComparisonResult: Result object containing comparison details
-        """
-        result = ComparisonResult(
-            file1=str(file1),
-            file2=str(file2),
-            start_line=start_line,
-            end_line=end_line,
-            start_column=start_column,
-            end_column=end_column
-        )
-        
-        try:
-            self.logger.info(f"Comparing files: {file1} and {file2}")
-            
-            # Record file metadata
-            file1_path = Path(file1)
-            file2_path = Path(file2)
-            result.file1_size = file1_path.stat().st_size
-            result.file2_size = file2_path.stat().st_size
-            
-            # Read content with specified ranges
-            self.logger.debug(f"Reading content from files")
-            content1 = self.read_content(file1, start_line, end_line, start_column, end_column)
-            content2 = self.read_content(file2, start_line, end_line, start_column, end_column)
-            
-            # Compare content
-            self.logger.debug(f"Comparing content")
-            identical, differences, truncated = self.compare_content(content1, content2)
-            
-            # Adjust line numbers in differences to reflect original file line numbers
-            # compare_content reports positions relative to the sliced content (1-based),
-            # but we need to offset by start_line to reflect positions in the original file
-            if start_line > 0:
-                import re
-                for diff in differences:
-                    if diff.position and isinstance(diff.position, str):
-                        # Position format is "line N"
-                        match = re.match(r'^line (\d+)$', diff.position)
-                        if match:
-                            original_line = int(match.group(1)) + start_line
-                            diff.position = f"line {original_line}"
-            
-            # Update result
-            result.identical = identical
-            result.differences = differences
-            result.truncated = truncated
-            result.error_stats = getattr(self, "_error_stats", None)
-
-            return result
-            
-        except Exception as e:
-            self.logger.error(f"Error during comparison: {str(e)}")
-            result.error = str(e)
-            result.identical = False
-            return result
\ No newline at end of file
+
+# Historical import-path alias: plugins written against the old API used
+# ``from symtest.file_comparator.base_comparator import BaseComparator``.
+# The name now refers to the same root contract; the *interface* change
+# (read_content/compare_content → compare, strict constructor parameters)
+# is the intentional breaking part.
+BaseComparator = ComparatorBase
diff --git a/src/symtest/file_comparator/binary_comparator.py b/src/symtest/file_comparator/binary_comparator.py
index 12d1a30..34836fe 100644
--- a/src/symtest/file_comparator/binary_comparator.py
+++ b/src/symtest/file_comparator/binary_comparator.py
@@ -10,10 +10,10 @@
 
 import difflib
 import hashlib
-from .base_comparator import BaseComparator
+from .file_comparator_base import FileComparator
 from .result import Difference
 
-class BinaryComparator(BaseComparator):
+class BinaryComparator(FileComparator):
     """
     @brief Comparator for binary files with efficient byte-level comparison
     @details This class implements binary file comparison with support for:
@@ -23,17 +23,17 @@ class BinaryComparator(BaseComparator):
              - File hash calculation
     """
     
-    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False, similarity=False, num_threads=4, **kwargs):
+    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False, similarity=False, num_threads=4):
         """
         @brief Initialize the binary comparator
         @param encoding str: File encoding (not used for binary files)
         @param chunk_size int: Size of chunks for reading large files
-        @param verbose bool: Enable verbose logging
+        @param verbose bool: Debug logging of this comparator's own logger
         @param similarity bool: Enable similarity index calculation
         @param num_threads int: Number of threads for parallel processing
-        @param **kwargs: Additional parameters (ignored)
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
         """
-        super().__init__(encoding=encoding, chunk_size=chunk_size, verbose=verbose, **kwargs)
+        super().__init__(encoding=encoding, chunk_size=chunk_size, verbose=verbose)
         self.similarity = similarity
         self.num_threads = num_threads
 
diff --git a/src/symtest/file_comparator/csv_comparator.py b/src/symtest/file_comparator/csv_comparator.py
index b597ecc..5fdd55c 100644
--- a/src/symtest/file_comparator/csv_comparator.py
+++ b/src/symtest/file_comparator/csv_comparator.py
@@ -27,21 +27,20 @@ class CsvComparator(TextComparator):
              - Configurable delimiter and quote character
     """
     
-    def __init__(self, encoding="utf-8", delimiter=",", quotechar='"', chunk_size=8192, verbose=False, rtol=1e-5, atol=1e-8, data_filter=None, error_analysis=False, **kwargs):
+    def __init__(self, encoding="utf-8", delimiter=",", quotechar='"', chunk_size=8192, rtol=1e-5, atol=1e-8, data_filter=None, error_analysis=False):
         """
         @brief Initialize CSV comparator with configuration
         @param encoding str: File encoding (default: utf-8)
         @param delimiter str: CSV field delimiter (default: comma)
         @param quotechar str: Character used for quoting fields (default: double quote)
         @param chunk_size int: Size of chunks for reading large files
-        @param verbose bool: Enable verbose output
         @param rtol float: Relative tolerance for numerical comparison (default: 1e-5)
         @param atol float: Absolute tolerance for numerical comparison (default: 1e-8)
         @param data_filter str: Data filter expression applied before numeric comparison
         @param error_analysis bool: Enable streaming error statistics over ALL numeric cells
-        @param **kwargs: Additional parameters (ignored)
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
         """
-        super().__init__(encoding=encoding, chunk_size=chunk_size, verbose=verbose, **kwargs)
+        super().__init__(encoding=encoding, chunk_size=chunk_size)
         self.delimiter = delimiter
         self.quotechar = quotechar
         self.rtol = rtol
@@ -102,7 +101,9 @@ def compare_content(self, content1, content2):
         """
         self._error_stats = None  # Reset per comparison
 
-        if content1 == content2:
+        # Fast path only when stats are not requested; with error_analysis we
+        # must still traverse all numeric cells to build the statistics.
+        if content1 == content2 and not self.error_analysis:
             return True, [], False
             
         differences = []
diff --git a/src/symtest/file_comparator/extractor_comparator.py b/src/symtest/file_comparator/extractor_comparator.py
new file mode 100644
index 0000000..793ef8c
--- /dev/null
+++ b/src/symtest/file_comparator/extractor_comparator.py
@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+@file extractor_comparator.py
+@brief Data-lane comparator: plugin extracts channels, framework owns verdict
+@author Xiaotong Wang
+@date 2026
+
+Data-lane plugins (positioned like the built-in csv/h5 comparators) implement
+:meth:`ExtractorComparator.extract` to turn arbitrary upstream inputs (files,
+solver output, cross-file aggregates) into per-channel ``(expected, actual)``
+numeric arrays.  The framework then runs the shared numeric core
+(:func:`~symtest.file_comparator.numeric_compare.compare_numeric`) per channel
+and aggregates the verdict — plugins never decide pass/fail themselves, so the
+tolerance semantics stay predictable for AI/report consumers.
+
+Config mapping (compareSpec passthrough)::
+
+    {
+      "type": "my_extractor",
+      "inputs": {"ref": "baseline.csv"},          # free-form, plugin-defined
+      "channels": {"S33": {"atol": 600.0}},       # per-channel overrides
+      "default_channel": {"rtol": 1e-5, "atol": 1e-8}
+    }
+
+Custom error metrics (user requirement: unique analysis schemes) are supported
+via ``ChannelData.extra_stats`` — a free-form dict merged into the channel
+statistics.  Verdicts, however, always come from the framework tolerances;
+plugins that must own the verdict belong in the autonomous lane instead.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .base_comparator import ComparatorBase, CompareContext
+from .numeric_compare import compare_numeric, parse_data_filter
+from .result import ChannelResult, ComparisonResult, Difference
+
+
+@dataclass
+class ChannelData:
+    """
+    @brief One channel of extracted numeric data.
+    @param expected: NumPy-compatible expected/reference values (baseline side)
+    @param actual: NumPy-compatible actual values (command-output side)
+    @param extra_stats: Optional plugin-defined metrics merged into the
+           channel's ``stats`` dict (unique error-analysis schemes).
+    """
+    expected: Any
+    actual: Any
+    extra_stats: Optional[Dict[str, Any]] = None
+
+
+class ExtractorComparator(ComparatorBase):
+    """
+    @brief Abstract base for data-lane (channel) comparators.
+    @details Subclasses implement :meth:`extract`; this class owns per-channel
+             tolerance routing, numeric comparison and result aggregation.
+    """
+
+    def __init__(self, channels=None, default_channel=None,
+                 rtol: float = 1e-5, atol: float = 1e-8):
+        """
+        @param channels dict|None: ``{channel_name: {"rtol":…, "atol":…,
+               "data_filter":…}}`` overrides; unset keys fall back to
+               ``default_channel``.
+        @param default_channel dict|None: Tolerance spec applied to channels
+               not listed in ``channels``.
+        @param rtol float: Final fallback relative tolerance (default 1e-5).
+        @param atol float: Final fallback absolute tolerance (default 1e-8).
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
+        """
+        super().__init__()
+        self.channel_specs: Dict[str, Dict[str, Any]] = dict(channels or {})
+        self.default_spec: Dict[str, Any] = dict(default_channel or {})
+        self.rtol = rtol
+        self.atol = atol
+
+    @abstractmethod
+    def extract(self, ctx: CompareContext) -> Dict[str, ChannelData]:
+        """
+        @brief Extract per-channel numeric data from the upstream inputs.
+        @param ctx CompareContext: Invocation context (paths resolved).
+        @return dict: ``{channel_name: ChannelData}``
+        @raises Exception: Extraction failures propagate; the framework turns
+                them into ``ComparisonResult.error``.
+        """
+
+    # ------------------------------------------------------------------
+    # Framework-owned comparison pipeline
+    # ------------------------------------------------------------------
+    def compare(self, ctx: CompareContext) -> ComparisonResult:  # type: ignore[override]
+        result = ComparisonResult(
+            file1=ctx.baseline,
+            file2=ctx.actual,
+        )
+        try:
+            channels_data = self.extract(ctx)
+            if not channels_data:
+                raise ValueError(
+                    f"{self.__class__.__name__}.extract() returned no channels"
+                )
+        except Exception as exc:
+            self.logger.error("Channel extraction failed: %s", exc)
+            result.error = f"Channel extraction failed: {exc}"
+            result.identical = False
+            result.command_output = getattr(self, "_last_command_output", None)
+            return result
+
+        channel_results = []
+        aggregated_differences = []
+        error_stats: Dict[str, Any] = {}
+
+        for name, data in channels_data.items():
+            spec = self._spec_for(name)
+            rtol = spec.get("rtol", self.rtol)
+            atol = spec.get("atol", self.atol)
+            filter_func = parse_data_filter(spec.get("data_filter"), logger=self.logger)
+
+            try:
+                res = compare_numeric(
+                    data.expected, data.actual,
+                    rtol=rtol, atol=atol,
+                    filter_func=filter_func, collect_stats=True,
+                )
+            except Exception as exc:
+                # e.g. size mismatch between expected/actual arrays
+                self.logger.error("Channel '%s' comparison failed: %s", name, exc)
+                diff = Difference(
+                    position=f"channel {name}",
+                    expected="comparable numeric arrays",
+                    actual=str(exc),
+                    diff_type="channel_error",
+                )
+                channel_results.append(ChannelResult(
+                    name=name, passed=False, rtol=rtol, atol=atol,
+                    stats={"error": str(exc)}, differences=[diff],
+                ))
+                aggregated_differences.append(diff)
+                continue
+
+            # Framework-owned canonical stats and plugin-owned extra_stats
+            # are kept in SEPARATE namespaces: a plugin must never be able to
+            # overwrite canonical metrics such as max_abs_error.
+            stats: Dict[str, Any] = {
+                "total": res.total,
+                "mismatched": res.mismatched,
+                "max_abs_error": res.max_abs_error,
+                "max_rel_error": res.max_rel_error,
+                "mean_abs_error": res.mean_abs_error,
+                "rms_abs_error": res.rms_abs_error,
+            }
+
+            passed = res.mismatched == 0
+            differences = []
+            if not passed:
+                diff = Difference(
+                    position=f"channel {name}",
+                    expected=f"within rtol={rtol:g}, atol={atol:g}",
+                    actual=(
+                        f"{res.mismatched}/{res.total} values mismatched "
+                        f"(max_abs={self._fmt(res.max_abs_error)}, "
+                        f"max_rel={self._fmt(res.max_rel_error)})"
+                    ),
+                    diff_type="channel_mismatch",
+                )
+                differences.append(diff)
+                aggregated_differences.append(diff)
+
+            channel_results.append(ChannelResult(
+                name=name, passed=passed, rtol=rtol, atol=atol,
+                stats=stats, extra_stats=data.extra_stats,
+                differences=differences,
+            ))
+            error_stats[name] = stats
+
+        result.channels = channel_results
+        result.identical = all(ch.passed for ch in channel_results)
+        result.differences = aggregated_differences
+        result.error_stats = error_stats or None
+        result.command_output = getattr(self, "_last_command_output", None)
+        return result
+
+    def _spec_for(self, name: str) -> Dict[str, Any]:
+        """Resolve the tolerance spec for a channel (declared -> default)."""
+        return dict(self.default_spec) | dict(self.channel_specs.get(name, {}))
+
+    @staticmethod
+    def _fmt(value) -> str:
+        """Format an optional float for difference messages."""
+        if value is None:
+            return "n/a"
+        if isinstance(value, float) and (np.isinf(value) or np.isnan(value)):
+            return str(value)
+        return f"{value:.6g}"
diff --git a/src/symtest/file_comparator/factory.py b/src/symtest/file_comparator/factory.py
index ea53a48..a4dcf0b 100644
--- a/src/symtest/file_comparator/factory.py
+++ b/src/symtest/file_comparator/factory.py
@@ -3,13 +3,27 @@
 
 """
 @file factory.py
-@brief Factory class for creating file comparators based on file type
+@brief Factory class for creating comparators based on type
 @author Xiaotong Wang
 @date 2025
+
+Comparator construction lifecycle (single, shared by every discovery path)::
+
+    resolve type name → comparator class
+        → resolve plugin path params against workspace   (BEFORE construction)
+        → instantiate with strict, validated parameters
+        → configure framework-owned logging (verbose)
+        → comparator.compare(ctx)
+
+Path resolution happens *before* the constructor runs so that constructor-
+captured state (``self.script``, ``self.cwd``, ``self.case_dir``, ...) already
+holds workspace-resolved absolute paths.  Plugins must never resolve paths
+against the process CWD.
 """
 
 import importlib
 import importlib.util
+import inspect
 import os
 import pkgutil
 import logging
@@ -18,60 +32,208 @@
 logger = logging.getLogger("symtest.file_comparator.factory")
 
 _ENV_VAR = "CLITEST_PLUGIN_DIRS"
+_COMPARATOR_SUFFIX = "Comparator"
+
+
+def _type_name_from_class(class_name: str) -> str:
+    """Convention-based fallback: strip ONLY a trailing ``Comparator`` suffix.
+
+    ``FooComparator -> foo``; ``ScriptExtractComparator -> scriptextract``
+    (use an explicit ``comparator_type`` class attribute for names containing
+    underscores, e.g. ``"script_extract"``).
+    """
+    if class_name.endswith(_COMPARATOR_SUFFIX):
+        return class_name[:-len(_COMPARATOR_SUFFIX)].lower()
+    return class_name.lower()
+
 
 class ComparatorFactory:
     """
-    @brief Factory class for creating file comparators
-    @details This class manages the creation and registration of different types of file comparators.
-             It provides a centralized way to create appropriate comparators based on file type
-             and automatically discovers and registers comparator classes via plugin scanning.
+    @brief Factory class for creating comparators
+    @details Manages creation and registration of comparator classes, with
+             automatic plugin discovery.  All discovery paths (built-in module
+             scan and workspace plugin directories) share the same
+             registration rules via :meth:`_register_comparator_class`.
     """
     _comparators = {}
     _initialized = False
     _plugin_dirs = []
 
+    # ------------------------------------------------------------------
+    # Registration (single entry point for every discovery path)
+    # ------------------------------------------------------------------
     @staticmethod
     def register_comparator(file_type, comparator_class):
         """
-        @brief Register a new comparator class for a specific file type
-        @param file_type str: Type of file the comparator handles
+        @brief Register a comparator class for a specific type name
+        @param file_type str: Type name the comparator handles
         @param comparator_class class: Comparator class to register
         """
         ComparatorFactory._comparators[file_type.lower()] = comparator_class
 
     @staticmethod
-    def create_comparator(file_type, **kwargs):
+    def _register_comparator_class(attr, module_name):
+        """Shared registration rules for ALL discovery paths.
+
+        A class is registered only when it:
+        - is a concrete (non-abstract) class defined in ``module_name``;
+        - its name ends with ``Comparator``.
+
+        Type-name priority: explicit ``comparator_type`` class attribute
+        (validated, lowercased) > suffix-stripped class-name convention.
+
+        :returns: the registered type name, or ``None`` when skipped.
         """
-        @brief Create a comparator instance for the specified file type
-        @param file_type str: Type of file to compare
-        @param **kwargs: Additional arguments to pass to the comparator
-        @return BaseComparator: An instance of the appropriate comparator class
-        @details Creates and returns a comparator instance based on the file type.
-                 If no specific comparator is found, falls back to TextComparator
-                 for text files or BinaryComparator for other types.
+        if not (isinstance(attr, type)
+                and attr.__module__ == module_name
+                and attr.__name__.endswith(_COMPARATOR_SUFFIX)):
+            return None
+        if inspect.isabstract(attr):
+            # Abstract bases (ComparatorBase / FileComparator /
+            # ExtractorComparator) are contracts, not instantiable types.
+            return None
+
+        explicit = getattr(attr, "comparator_type", None)
+        if explicit is not None:
+            if not isinstance(explicit, str) or not explicit.strip():
+                logger.warning(
+                    "Ignoring invalid comparator_type %r on %s (must be a "
+                    "non-empty string); falling back to class-name convention",
+                    explicit, attr.__name__,
+                )
+                type_name = _type_name_from_class(attr.__name__)
+            else:
+                type_name = explicit.strip().lower()
+        else:
+            type_name = _type_name_from_class(attr.__name__)
+
+        ComparatorFactory.register_comparator(type_name, attr)
+        return type_name
+
+    # ------------------------------------------------------------------
+    # Construction lifecycle
+    # ------------------------------------------------------------------
+    @staticmethod
+    def get_comparator_class(file_type):
+        """
+        @brief Return the comparator class for a type name (no instantiation).
+        @details 'auto'/'text' resolve to TextComparator ('auto' is normally
+                 resolved from the file extension by the assertion/CLI layer
+                 before reaching the factory).  Unknown types fail LOUDLY with
+                 the list of available types — a typo in the compareSpec
+                 ``type`` field must never silently degrade to another
+                 comparator (that would produce wrong "passing" results).
         """
         if not ComparatorFactory._initialized:
             ComparatorFactory._load_comparators()
 
         comparator_class = ComparatorFactory._comparators.get(file_type.lower())
-        if not comparator_class:
-            if file_type.lower() in ['auto', 'text']:
+        if comparator_class is None:
+            if file_type.lower() in ("auto", "text"):
                 from .text_comparator import TextComparator
-                return TextComparator(**kwargs)
-            else:
-                from .binary_comparator import BinaryComparator
-                return BinaryComparator(**kwargs)
+                return TextComparator
+            raise ValueError(
+                f"Unknown comparator type '{file_type}'. "
+                f"Available types: {ComparatorFactory.get_available_comparators()}. "
+                f"Unknown types fail loudly — check the compareSpec 'type' for typos."
+            )
+        return comparator_class
 
-        return comparator_class(**kwargs)
+    @staticmethod
+    def resolve_plugin_params(comparator_class, params, workspace=None):
+        """Resolve plugin-declared path parameters against the workspace.
 
+        Must run BEFORE ``comparator_class(**params)`` so constructor-captured
+        state already holds absolute paths.  Only parameters listed in the
+        class's ``path_params`` attribute are touched; ``actual``/``baseline``
+        are resolved separately by the assertion layer.
+        """
+        resolved = dict(params or {})
+        if workspace:
+            for name in getattr(comparator_class, "path_params", ()) or ():
+                value = resolved.get(name)
+                if isinstance(value, str) and value and not os.path.isabs(value):
+                    # normpath keeps separators consistent with the platform
+                    resolved[name] = os.path.normpath(os.path.join(workspace, value))
+        return resolved
+
+    @staticmethod
+    def _accepts_param(cls, name):
+        """Whether ``cls.__init__`` accepts ``name`` (or **kwargs)."""
+        try:
+            sig = inspect.signature(cls.__init__)
+        except (TypeError, ValueError):
+            return False
+        for param in sig.parameters.values():
+            if param.name == "self":
+                continue
+            if param.name == name or param.kind is inspect.Parameter.VAR_KEYWORD:
+                return True
+        return False
+
+    @staticmethod
+    def create_comparator(file_type, workspace=None, verbose=False,
+                          error_analysis=False, **kwargs):
+        """
+        @brief Create a comparator instance (resolve → instantiate lifecycle).
+        @param file_type str: Comparator type name ('auto' detects by extension
+               at the assertion layer; here it falls back like legacy code).
+        @param workspace str|None: Workspace root; ``path_params``-declared
+               parameters are resolved against it BEFORE construction.
+        @param verbose bool: Framework-owned logging knob; configures the
+               comparator's logger level, never stored as comparator config.
+        @param error_analysis bool: Forwarded to the constructor only when the
+               comparator declares the parameter (numeric comparators).
+        @param **kwargs: Comparator configuration.  Unknown parameters fail
+               loudly with a TypeError identifying the comparator type —
+               configuration typos must never fall back to defaults.
+        """
+        comparator_class = ComparatorFactory.get_comparator_class(file_type)
+
+        params = ComparatorFactory.resolve_plugin_params(
+            comparator_class, kwargs, workspace,
+        )
+        # Framework-injected knobs are not comparator configuration.
+        params.pop("verbose", None)
+        params.pop("error_analysis", None)
+        if error_analysis and ComparatorFactory._accepts_param(
+                comparator_class, "error_analysis"):
+            params["error_analysis"] = True
+
+        try:
+            comparator = comparator_class(**params)
+        except TypeError as exc:
+            supported = sorted(
+                p for p in inspect.signature(comparator_class.__init__).parameters
+                if p != "self"
+            )
+            raise TypeError(
+                f"Invalid configuration for comparator type '{file_type}' "
+                f"({comparator_class.__name__}): {exc}. "
+                f"Supported parameters: {supported}. "
+                f"Unknown parameters fail loudly — check the compareSpec for typos."
+            ) from exc
+
+        if verbose:
+            comparator.logger.setLevel(logging.DEBUG)
+        return comparator
+
+    # ------------------------------------------------------------------
+    # Plugin discovery
+    # ------------------------------------------------------------------
     @staticmethod
     def set_plugin_dirs(dirs):
-        """Persist workspace-level plugin directories and expose them via env var.
+        """Register workspace-level plugin directories.
 
         Thread-pool runners share ``_plugin_dirs`` in-process.  Process-pool
-        runners (``spawn``) pick up the plugin paths from ``CLITEST_PLUGIN_DIRS``
-        so that the lazy ``_load_comparators()`` in each worker discovers the
-        same workspace plugins.
+        runners (``spawn``) receive the same list explicitly via the pool
+        ``initializer`` (see ``parallel_runner``) — the framework NEVER
+        mutates ``os.environ``.
+
+        ``CLITEST_PLUGIN_DIRS`` remains a user-facing *input*: when set by
+        the user in the environment, ``_load_comparators()`` reads it as an
+        extra discovery source.  The framework only reads it, never writes
+        or deletes it.
 
         :param dirs: Iterable of absolute or relative directory paths.
         """
@@ -84,7 +246,6 @@ def set_plugin_dirs(dirs):
                 deduped.append(resolved)
                 seen.add(resolved)
         ComparatorFactory._plugin_dirs = deduped
-        os.environ[_ENV_VAR] = os.pathsep.join(deduped)
         if ComparatorFactory._initialized:
             ComparatorFactory._load_from_dirs(deduped)
 
@@ -92,23 +253,25 @@ def set_plugin_dirs(dirs):
     def _load_comparators():
         """
         @brief Load and register all available comparators
-        @details Automatically discovers and registers comparator classes from the package.
-                 This includes both built-in comparators and any additional comparators
-                 that follow the naming convention '*_comparator.py'.
+        @details Automatically discovers comparator classes from the package
+                 and from workspace plugin directories.  Both paths share the
+                 registration rules in :meth:`_register_comparator_class`.
         """
         package_dir = Path(__file__).parent
         for module_info in pkgutil.iter_modules([str(package_dir)]):
             if module_info.name.endswith('_comparator') and module_info.name != 'base_comparator':
                 try:
                     module = importlib.import_module(f".{module_info.name}", package=__package__)
-
                     for attr_name in dir(module):
                         attr = getattr(module, attr_name)
-                        if (isinstance(attr, type) and
-                            attr.__module__ == module.__name__ and
-                            attr_name.endswith('Comparator')):
-                            type_name = attr_name.lower().replace('comparator', '')
-                            ComparatorFactory.register_comparator(type_name, attr)
+                        type_name = ComparatorFactory._register_comparator_class(
+                            attr, module.__name__,
+                        )
+                        if type_name:
+                            logger.debug(
+                                "Registered built-in comparator '%s' -> %s",
+                                type_name, attr_name,
+                            )
                 except ImportError as e:
                     logger.warning("Failed to import comparator module %s: %s", module_info.name, e)
 
@@ -156,11 +319,10 @@ def _load_from_dirs(dirs):
 
                     for attr_name in dir(module):
                         attr = getattr(module, attr_name)
-                        if (isinstance(attr, type)
-                                and attr.__module__ == module.__name__
-                                and attr_name.endswith("Comparator")):
-                            type_name = attr_name.lower().replace("comparator", "")
-                            ComparatorFactory.register_comparator(type_name, attr)
+                        type_name = ComparatorFactory._register_comparator_class(
+                            attr, module.__name__,
+                        )
+                        if type_name:
                             logger.info(
                                 "Registered workspace plugin '%s' -> %s from %s",
                                 type_name, attr_name, py_file,
@@ -182,10 +344,11 @@ def get_available_comparators():
 
     @staticmethod
     def reset():
-        """Reset all internal state (for testing)."""
+        """Reset all internal state (for testing).
+
+        Never touches ``os.environ`` — ``CLITEST_PLUGIN_DIRS`` belongs to
+        the user's environment, not to framework state.
+        """
         ComparatorFactory._comparators = {}
         ComparatorFactory._initialized = False
         ComparatorFactory._plugin_dirs = []
-        if _ENV_VAR in os.environ:
-            del os.environ[_ENV_VAR]
-
diff --git a/src/symtest/file_comparator/file_comparator_base.py b/src/symtest/file_comparator/file_comparator_base.py
new file mode 100644
index 0000000..10bda03
--- /dev/null
+++ b/src/symtest/file_comparator/file_comparator_base.py
@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+@file file_comparator_base.py
+@brief File-lane comparator: two-file model (read + compare template method)
+@author Xiaotong Wang
+@date 2025
+
+This class hosts the legacy two-file template that used to live on the root
+``BaseComparator``.  Only file-lane comparators (text/json/csv/xml/h5/binary)
+implement ``read_content``/``compare_content``; autonomous-lane and data-lane
+plugins are no longer forced to provide empty stubs for them.
+"""
+
+from abc import abstractmethod
+import logging
+from pathlib import Path
+
+from .base_comparator import ComparatorBase, CompareContext
+from .result import ComparisonResult
+
+
+class FileComparator(ComparatorBase):
+    """
+    @brief Abstract base for two-file comparison (file lane).
+    @details Template method :meth:`compare_files` orchestrates
+             read -> compare -> result assembly, including the line-window
+             position offsetting for text-style comparators.  Subclasses
+             implement :meth:`read_content` and :meth:`compare_content`.
+    """
+
+    def __init__(self, encoding: str = "utf-8", chunk_size: int = 8192,
+                 verbose: bool = False):
+        """
+        @brief Initialize file-lane state.
+        @param encoding str: Text decoding for file reads (default "utf-8").
+        @param chunk_size int: Chunk size for large-file reads (default 8192).
+        @param verbose bool: Raises THIS comparator's own logger to DEBUG.
+               File-lane justified (byte/hex/text diff tracing); it touches
+               only the comparator's named logger, never global logging
+               policy.  The factory also accepts ``verbose`` for any lane.
+        """
+        super().__init__()
+        self.encoding = encoding
+        self.chunk_size = chunk_size
+        if verbose:
+            self.logger.setLevel(logging.DEBUG)
+
+    @abstractmethod
+    def read_content(self, file_path, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Read file content with specified range
+        @param file_path Path: Path to the file to read
+        @param start_line int: Starting line number (0-based)
+        @param end_line int: Ending line number (0-based, None for end of file)
+        @param start_column int: Starting column number (0-based)
+        @param end_column int: Ending column number (0-based, None for end of line)
+        @return object: File content in a format suitable for comparison
+        """
+
+    @abstractmethod
+    def compare_content(self, content1, content2):
+        """
+        @brief Compare two content objects and return comparison details
+        @param content1 object: First content object to compare
+        @param content2 object: Second content object to compare
+        @return tuple: (bool, list, bool) - (identical, differences, truncated)
+        """
+
+    def compare(self, ctx: CompareContext) -> ComparisonResult:  # type: ignore[override]
+        """
+        @brief Compare ``ctx.baseline`` vs ``ctx.actual`` via the file template.
+        @details Method-level window parameters (``start_line``/``end_line``/
+                 ``start_column``/``end_column``, already converted to 0-based
+                 by the assertion layer) are consumed from ``ctx.params``;
+                 everything else was forwarded to the constructor.
+        """
+        params = dict(ctx.params or {})
+        method_params = {}
+        for key in ("start_line", "end_line", "start_column", "end_column"):
+            if key in params:
+                method_params[key] = params.pop(key)
+        return self.compare_files(ctx.baseline, ctx.actual, **method_params)
+
+    def compare_files(self, file1, file2, start_line=0, end_line=None, start_column=0, end_column=None):
+        """
+        @brief Compare two files with the specified parameters
+        @param file1 Path: Path to the first file (baseline slot)
+        @param file2 Path: Path to the second file (actual slot)
+        @param start_line int: Starting line number (0-based)
+        @param end_line int: Ending line number (0-based, None for end of file)
+        @param start_column int: Starting column number (0-based)
+        @param end_column int: Ending column number (0-based, None for end of line)
+        @return ComparisonResult: Result object containing comparison details
+        """
+        result = ComparisonResult(
+            file1=str(file1) if file1 else "",
+            file2=str(file2) if file2 else "",
+            start_line=start_line,
+            end_line=end_line,
+            start_column=start_column,
+            end_column=end_column
+        )
+
+        try:
+            self.logger.info(f"Comparing files: {file1} and {file2}")
+
+            # Record file metadata
+            file1_path = Path(file1)
+            file2_path = Path(file2)
+            result.file1_size = file1_path.stat().st_size
+            result.file2_size = file2_path.stat().st_size
+
+            # Read content with specified ranges
+            self.logger.debug(f"Reading content from files")
+            content1 = self.read_content(file1, start_line, end_line, start_column, end_column)
+            content2 = self.read_content(file2, start_line, end_line, start_column, end_column)
+
+            # Compare content
+            self.logger.debug(f"Comparing content")
+            identical, differences, truncated = self.compare_content(content1, content2)
+
+            # Adjust line numbers in differences to reflect original file line numbers
+            # compare_content reports positions relative to the sliced content (1-based),
+            # but we need to offset by start_line to reflect positions in the original file
+            if start_line > 0:
+                import re
+                for diff in differences:
+                    if diff.position and isinstance(diff.position, str):
+                        # Position format is "line N"
+                        match = re.match(r'^line (\d+)$', diff.position)
+                        if match:
+                            original_line = int(match.group(1)) + start_line
+                            diff.position = f"line {original_line}"
+
+            # Update result
+            result.identical = identical
+            result.differences = differences
+            result.truncated = truncated
+            result.error_stats = getattr(self, "_error_stats", None)
+
+            return result
+
+        except Exception as e:
+            self.logger.error(f"Error during comparison: {str(e)}")
+            result.error = str(e)
+            result.identical = False
+            return result
diff --git a/src/symtest/file_comparator/h5_comparator.py b/src/symtest/file_comparator/h5_comparator.py
index 82a9bb3..70a31e1 100644
--- a/src/symtest/file_comparator/h5_comparator.py
+++ b/src/symtest/file_comparator/h5_comparator.py
@@ -1,12 +1,12 @@
-from .base_comparator import BaseComparator
+from .file_comparator_base import FileComparator
 import h5py
 import numpy as np
 import logging
 import re
 from .numeric_compare import compare_numeric, parse_data_filter
 
-class H5Comparator(BaseComparator):
-    def __init__(self, tables=None, table_regex=None, structure_only=False, show_content_diff=False, debug=False, rtol=1e-5, atol=1e-8, expand_path=True, data_filter=None, error_analysis=False, **kwargs):
+class H5Comparator(FileComparator):
+    def __init__(self, tables=None, table_regex=None, structure_only=False, show_content_diff=False, debug=False, rtol=1e-5, atol=1e-8, expand_path=True, data_filter=None, error_analysis=False, encoding="utf-8", verbose=False):
         """
         Initialize H5 comparator
         :param tables: List of table names to compare. If None, compare all tables
@@ -19,8 +19,11 @@ def __init__(self, tables=None, table_regex=None, structure_only=False, show_con
         :param expand_path: If True, expand group paths to compare all sub-items. Defaults to True.
         :param data_filter: String filter expression for data comparison (e.g., '>1e-6', 'abs>1e-9')
         :param error_analysis: Enable streaming error statistics over ALL numeric cells
+        :param encoding: Text encoding for attribute values
+        :param verbose: Debug logging of this comparator's own logger
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
         """
-        super().__init__(**kwargs)
+        super().__init__(encoding=encoding, verbose=verbose)
         self.tables = tables
         self.table_regex = table_regex
         self.structure_only = structure_only
@@ -33,8 +36,9 @@ def __init__(self, tables=None, table_regex=None, structure_only=False, show_con
         self.error_analysis = error_analysis
         self._error_stats = None
         
-        # Set debug level if verbose is enabled
-        if kwargs.get('verbose', False) or debug:
+        # Set debug level if debug mode is enabled (verbose is handled by
+        # the file-lane base constructor / factory).
+        if debug:
             self.logger.setLevel(logging.DEBUG)
             
         self.logger.debug(f"Initialized H5Comparator with structure_only={structure_only}, show_content_diff={show_content_diff}, rtol={rtol}, atol={atol}, expand_path={expand_path}, data_filter={data_filter}")
@@ -470,6 +474,8 @@ def compare_content(self, content1, content2):
                             identical = False
 
         # ── Store error stats ──
+        # Mean / RMS use total numeric cells as the denominator (stats cover
+        # ALL compared cells, matching ones included).
         if self.error_analysis and _ea_total > 0:
             self._error_stats = {
                 "total_numeric_cells": _ea_total,
@@ -478,8 +484,8 @@ def compare_content(self, content1, content2):
                 "max_abs_error_at": _ea_max_abs_at,
                 "max_rel_error": _ea_max_rel,
                 "max_rel_error_at": _ea_max_rel_at,
-                "mean_abs_error": _ea_sum_abs / _ea_mismatched if _ea_mismatched > 0 else 0.0,
-                "rms_abs_error": (np.sqrt(_ea_sum_sq / _ea_mismatched) if _ea_mismatched > 0 else 0.0),
+                "mean_abs_error": _ea_sum_abs / _ea_total,
+                "rms_abs_error": np.sqrt(_ea_sum_sq / _ea_total),
             }
 
         return identical, differences, False
diff --git a/src/symtest/file_comparator/json_comparator.py b/src/symtest/file_comparator/json_comparator.py
index 24f5a52..55ee397 100644
--- a/src/symtest/file_comparator/json_comparator.py
+++ b/src/symtest/file_comparator/json_comparator.py
@@ -22,17 +22,16 @@ class JsonComparator(TextComparator):
              - Detailed difference reporting with path information
     """
     
-    def __init__(self, encoding="utf-8", chunk_size=8192, verbose=False, key_field=None, compare_mode="exact", **kwargs):
+    def __init__(self, encoding="utf-8", chunk_size=8192, key_field=None, compare_mode="exact"):
         """
         @brief Initialize the JSON comparator
         @param encoding str: File encoding
         @param chunk_size int: Chunk size for reading files
-        @param verbose bool: Enable verbose logging
         @param key_field str or list: Field name(s) to use as key for comparing JSON objects in lists
         @param compare_mode str: Comparison mode: 'exact' (default) or 'key-based'
-        @param **kwargs: Additional parameters (ignored)
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
         """
-        super().__init__(encoding=encoding, chunk_size=chunk_size, verbose=verbose, **kwargs)
+        super().__init__(encoding=encoding, chunk_size=chunk_size)
         self.key_field = key_field
         self.compare_mode = compare_mode
 
diff --git a/src/symtest/file_comparator/numeric_compare.py b/src/symtest/file_comparator/numeric_compare.py
index 1659703..6c37299 100644
--- a/src/symtest/file_comparator/numeric_compare.py
+++ b/src/symtest/file_comparator/numeric_compare.py
@@ -143,45 +143,48 @@ def compare_numeric(expected, actual, rtol=1e-5, atol=1e-8,
     # Flat indices (within the original array) of kept positions.
     keep_idx = np.flatnonzero(keep)
 
-    if mismatched == 0:
-        return NumericComparisonStats(
-            total=total,
-            mismatched=0,
-            mismatch_mask=np.zeros(expected.size, dtype=bool),
-            max_abs_error=None,
-            max_abs_error_index=None,
-            max_rel_error=None,
-            max_rel_error_index=None,
-            mean_abs_error=0.0,
-            rms_abs_error=0.0,
-            sum_abs_error=0.0,
-            sum_sq_abs_error=0.0,
-        )
-
-    # ── Error statistics (over mismatched cells only) ──
-    mism_abs_err = abs_err[mismatch]
-    mism_expected = exp_keep[mismatch]
-
-    sum_abs = float(np.sum(mism_abs_err))
-    sum_sq = float(np.sum(mism_abs_err ** 2))
-
-    max_abs_error = float(np.max(mism_abs_err))
-    max_abs_keep_pos = int(np.argmax(mism_abs_err))
-    max_abs_error_index = int(keep_idx[mismatch][max_abs_keep_pos])
-
-    # Relative error: inf when reference value is zero but error is non-zero (CSV semantics).
-    ref_abs = np.abs(mism_expected)
-    rel_err = np.full(mism_abs_err.shape, np.inf)
-    nonzero = ref_abs > 0
-    with np.errstate(invalid="ignore"):
-        rel_err[nonzero] = mism_abs_err[nonzero] / ref_abs[nonzero]
-
-    max_rel_error = float(np.max(rel_err))
-    max_rel_keep_pos = int(np.argmax(rel_err))
-    max_rel_error_index = int(keep_idx[mismatch][max_rel_keep_pos])
-
-    mean_abs_error = sum_abs / mismatched if mismatched > 0 else 0.0
-    rms_abs_error = np.sqrt(sum_sq / mismatched) if mismatched > 0 else 0.0
+    # ── Error statistics (over ALL kept numeric cells, matching ones included) ──
+    # Non-finite cells (NaN / inf) are excluded from magnitude statistics;
+    # identical NaN / inf pairs contribute zero error by definition.
+    finite = np.isfinite(exp_keep) & np.isfinite(act_keep)
+    stat_idx = keep_idx[finite]
+    stat_abs_err = abs_err[finite]
+    stat_expected = exp_keep[finite]
+    n_stat = int(np.sum(finite))
+
+    if n_stat > 0:
+        sum_abs = float(np.sum(stat_abs_err))
+        sum_sq = float(np.sum(stat_abs_err ** 2))
+
+        max_abs_error = float(np.max(stat_abs_err))
+        max_abs_stat_pos = int(np.argmax(stat_abs_err))
+        max_abs_error_index = int(stat_idx[max_abs_stat_pos])
+
+        # Relative error: inf when reference value is zero but error is non-zero;
+        # zero when the reference is zero and the values agree exactly.
+        ref_abs = np.abs(stat_expected)
+        rel_err = np.full(stat_abs_err.shape, np.inf)
+        nonzero = ref_abs > 0
+        with np.errstate(invalid="ignore"):
+            rel_err[nonzero] = stat_abs_err[nonzero] / ref_abs[nonzero]
+        rel_err[~nonzero & (stat_abs_err == 0)] = 0.0
+
+        max_rel_error = float(np.max(rel_err))
+        max_rel_stat_pos = int(np.argmax(rel_err))
+        max_rel_error_index = int(stat_idx[max_rel_stat_pos])
+
+        mean_abs_error = sum_abs / total
+        rms_abs_error = np.sqrt(sum_sq / total)
+    else:
+        # No finite cells: magnitudes are undefined.
+        sum_abs = 0.0
+        sum_sq = 0.0
+        max_abs_error = None
+        max_abs_error_index = None
+        max_rel_error = None
+        max_rel_error_index = None
+        mean_abs_error = 0.0
+        rms_abs_error = 0.0
 
     # Build full-length mismatch mask (True where values differ beyond tolerance).
     mismatch_mask = np.zeros(expected.size, dtype=bool)
@@ -195,7 +198,7 @@ def compare_numeric(expected, actual, rtol=1e-5, atol=1e-8,
         max_abs_error_index=max_abs_error_index,
         max_rel_error=max_rel_error,
         max_rel_error_index=max_rel_error_index,
-        mean_abs_error=mean_abs_error,
+        mean_abs_error=float(mean_abs_error),
         rms_abs_error=float(rms_abs_error),
         sum_abs_error=sum_abs,
         sum_sq_abs_error=sum_sq,
diff --git a/src/symtest/file_comparator/result.py b/src/symtest/file_comparator/result.py
index 7c98cd3..5b6bb7c 100644
--- a/src/symtest/file_comparator/result.py
+++ b/src/symtest/file_comparator/result.py
@@ -60,12 +60,72 @@ def to_dict(self):
             "diff_type": self.diff_type
         }
 
+class ChannelResult:
+    """
+    @brief Per-channel numeric comparison sub-result (data lane)
+    @details Produced by :class:`~symtest.file_comparator.extractor_comparator.ExtractorComparator`
+             for every channel returned by ``extract()``.  One ``ComparisonResult``
+             aggregates all channels; ``identical`` is True only when every
+             channel passed its own tolerance.
+    """
+
+    def __init__(self, name, passed, rtol=1e-5, atol=1e-8, stats=None,
+                 extra_stats=None, differences=None):
+        """
+        @param name str: Channel name (as returned by the extractor)
+        @param passed bool: Whether this channel passed its tolerance
+        @param rtol float: Relative tolerance applied to this channel
+        @param atol float: Absolute tolerance applied to this channel
+        @param stats dict|None: Framework-owned canonical statistics
+               (compare_numeric summary).  Never overridable by plugins.
+        @param extra_stats dict|None: Plugin-owned metrics in a SEPARATE
+               namespace — plugins cannot overwrite canonical stats.
+        @param differences list: Difference objects (positions carry the
+               channel name as prefix)
+        """
+        self.name = name
+        self.passed = passed
+        self.rtol = rtol
+        self.atol = atol
+        self.stats = stats
+        self.extra_stats = extra_stats
+        self.differences = differences or []
+
+    def __str__(self):
+        verdict = "PASS" if self.passed else "FAIL"
+        line = f"channel '{self.name}': {verdict} (rtol={self.rtol:g}, atol={self.atol:g})"
+        if self.stats:
+            mism = self.stats.get("mismatched")
+            total = self.stats.get("total")
+            if mism is not None and total is not None:
+                line += f", {mismatched_str(mism, total)}"
+        return line
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "passed": self.passed,
+            "rtol": self.rtol,
+            "atol": self.atol,
+            "stats": self.stats,
+            "extra_stats": self.extra_stats,
+            "differences": [d.to_dict() for d in self.differences],
+        }
+
+
+def mismatched_str(mismatched, total):
+    """Tiny formatter shared by ChannelResult string rendering."""
+    return f"{mismatched}/{total} values mismatched"
+
+
 class ComparisonResult:
     """
     @brief Represents the result of a file comparison
     @details This class encapsulates all information about a file comparison,
              including file paths, comparison range, differences found,
              and additional metadata like file sizes and similarity index.
+             Data-lane comparators additionally populate ``channels`` with
+             per-channel sub-results.
     """
     
     def __init__(self, file1=None, file2=None, start_line=0, end_line=None, 
@@ -94,6 +154,7 @@ def __init__(self, file1=None, file2=None, start_line=0, end_line=None,
         self.truncated = False  # Whether differences were truncated due to max_diffs limit
         self.error_stats = None  # Optional error statistics from streaming numerical analysis
         self.command_output = None  # Optional subprocess stdout captured by script/custom comparators
+        self.channels = []  # Optional list[ChannelResult] for data-lane (channel) comparisons
     
     def __str__(self):
         """
@@ -114,6 +175,10 @@ def __str__(self):
                 lines.append("... more differences not shown")
             if self.similarity is not None:
                 lines.append(f"Similarity Index: {self.similarity:.2f}")
+            if self.channels:
+                lines.append("Channels:")
+                for ch in self.channels:
+                    lines.append(f"  - {ch}")
         return "\n".join(lines)
     
     def _get_range_str(self):
@@ -161,6 +226,7 @@ def to_dict(self):
             "truncated": self.truncated,
             "error_stats": self.error_stats,
             "command_output": self.command_output,
+            "channels": [ch.to_dict() for ch in self.channels],
         }
     
     def to_html(self):
diff --git a/src/symtest/file_comparator/script_comparator.py b/src/symtest/file_comparator/script_comparator.py
index 5675114..6a17f7a 100644
--- a/src/symtest/file_comparator/script_comparator.py
+++ b/src/symtest/file_comparator/script_comparator.py
@@ -3,30 +3,27 @@
 
 """
 @file script_comparator.py
-@brief Built-in script comparator – delegates comparison to an external script
+@brief Built-in script comparator – autonomous lane, delegates verdict to an external script
 @author Xiaotong Wang
 @date 2025
 """
 
-import logging
 import re
 import subprocess
 import sys
-from pathlib import Path
 from typing import List, Optional
 
-from .base_comparator import BaseComparator
+from .base_comparator import ComparatorBase, CompareContext
 from .result import ComparisonResult, Difference
 
-logger = logging.getLogger("symtest.file_comparator.script")
 
-
-class ScriptComparator(BaseComparator):
-    """Run an external script as a comparison step.
+class ScriptComparator(ComparatorBase):
+    """Run an external script as a comparison step (autonomous lane).
 
     The script is invoked as a subprocess.  By default exit code 0 signals
     *pass*.  Optionally, ``pass_pattern`` / ``fail_pattern`` regexes can be
-    used to refine the verdict from ``stdout``.
+    used to refine the verdict from ``stdout``.  The plugin owns the verdict —
+    for framework-owned numeric tolerance use the ``script_extract`` type.
 
     Configuration example::
 
@@ -35,6 +32,8 @@ class ScriptComparator(BaseComparator):
          "fail_pattern": "(MISMATCH|FAILED)"}
     """
 
+    path_params = ("script", "cwd")
+
     def __init__(
         self,
         script: str = "",
@@ -45,53 +44,35 @@ def __init__(
         pass_pattern: Optional[str] = None,
         fail_pattern: Optional[str] = None,
         timeout: int = 3600,
-        encoding: str = "utf-8",
-        **kwargs,
     ):
-        super().__init__(encoding=encoding, **kwargs)
-        self.script = script
-        self.cwd = cwd
-        self.args = args or []
+        super().__init__()
+        self.script = script      # workspace-resolved by the framework (path_params)
+        self.cwd = cwd            # workspace-resolved by the framework (path_params)
+        self.args = list(args) if args else []
         self.interpreter = interpreter or sys.executable
         self.pass_exit_code = pass_exit_code
         self.pass_pattern = re.compile(pass_pattern) if pass_pattern else None
         self.fail_pattern = re.compile(fail_pattern) if fail_pattern else None
         self.timeout = timeout
 
-    # ------------------------------------------------------------------
-    # Abstract method stubs (not used by this comparator)
-    # ------------------------------------------------------------------
-    def read_content(self, file_path, **kwargs):
-        return None
-
-    def compare_content(self, content1, content2):
-        return True, [], False
-
     # ------------------------------------------------------------------
     # Core comparison
     # ------------------------------------------------------------------
-    def compare_files(  # type: ignore[override]
-        self,
-        file1=None,
-        file2=None,
-        **kwargs,
-    ):
+    def compare(self, ctx: CompareContext) -> ComparisonResult:  # type: ignore[override]
         """Execute the external script and evaluate its output."""
         result = ComparisonResult(
-            file1=str(file1) if file1 else "",
-            file2=str(file2) if file2 else "",
+            file1=ctx.baseline,
+            file2=ctx.actual,
         )
 
         try:
             cmd = [self.interpreter, self.script, *self.args]
-            if file1:
-                cmd.append(str(file1))
-            if file2:
-                cmd.append(str(file2))
-
-            cwd = self.cwd
-            if cwd and not Path(cwd).is_absolute():
-                cwd = str(Path(cwd).resolve())
+            # Trailing file slots, baseline first (historical convention:
+            # compare_files(file1=baseline, file2=actual) → argv[-2:]).
+            if ctx.baseline:
+                cmd.append(str(ctx.baseline))
+            if ctx.actual:
+                cmd.append(str(ctx.actual))
 
             self.logger.info("Executing script: %s", " ".join(cmd))
             proc = subprocess.run(
@@ -99,7 +80,7 @@ def compare_files(  # type: ignore[override]
                 capture_output=True,
                 text=True,
                 timeout=self.timeout,
-                cwd=cwd,
+                cwd=self.cwd,
             )
 
             stdout = proc.stdout or ""
diff --git a/src/symtest/file_comparator/script_extract_comparator.py b/src/symtest/file_comparator/script_extract_comparator.py
new file mode 100644
index 0000000..cdf14b3
--- /dev/null
+++ b/src/symtest/file_comparator/script_extract_comparator.py
@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+@file script_extract_comparator.py
+@brief Built-in ``script_extract`` comparator: zero-modification script to channel pipeline
+@author Xiaotong Wang
+@date 2026
+
+Lets an existing analysis script feed the data lane without writing a Python
+plugin.  The script is executed as a subprocess and must print a JSON document
+on stdout::
+
+    {
+      "channels": {
+        "S11":  {"expected": [...], "actual": [...], "extra_stats": {"k": v}},
+        "S33":  {"expected": [...], "actual": [...]}
+      }
+    }
+
+Each channel then goes through the standard per-channel tolerance pipeline
+(``channels`` / ``default_channel`` compareSpec keys).  Exit code 0 is
+required; any non-zero exit, timeout, or malformed JSON becomes a comparison
+error (never a silent pass).
+
+Config example::
+
+    {
+      "type": "script_extract",
+      "script": "extract_channels.py",
+      "args": ["--frame", "10"],
+      "cwd": "case/subdir",
+      "timeout": 600,
+      "channels": {"S33": {"atol": 600.0}},
+      "default_channel": {"rtol": 1e-5, "atol": 1e-8}
+    }
+"""
+
+import json
+import subprocess
+import sys
+from typing import Dict
+
+from .base_comparator import CompareContext
+from .extractor_comparator import ChannelData, ExtractorComparator
+
+
+class ScriptExtractComparator(ExtractorComparator):
+    """
+    @brief Run an external script and route its JSON channel output through
+           the framework-owned numeric pipeline.
+    @details Inherits per-channel verdict logic from
+             :class:`ExtractorComparator`; this class only handles the
+             subprocess invocation and JSON protocol parsing.
+    """
+
+    comparator_type = "script_extract"  # factory type name (convention would yield "scriptextract")
+    path_params = ("script", "cwd")
+
+    def __init__(self, script: str = "", args=None, cwd: str = None,
+                 interpreter: str = None, timeout: int = 3600,
+                 channels=None, default_channel=None):
+        """
+        @param script str: Path to the extraction script (required).
+        @param args list: Extra CLI arguments passed to the script.
+        @param cwd str: Working directory for the subprocess (workspace-
+               resolved by the framework BEFORE construction via
+               ``path_params``).
+        @param interpreter str: Python interpreter (default ``sys.executable``).
+        @param timeout int: Subprocess timeout in seconds (default 3600).
+        @note Parameters are strict: unknown/misspelled config keys fail loudly.
+        """
+        super().__init__(channels=channels, default_channel=default_channel)
+        self.script = script      # workspace-resolved by the framework
+        self.args = list(args) if args else []
+        self.cwd = cwd            # workspace-resolved by the framework
+        self.interpreter = interpreter or sys.executable
+        self.timeout = timeout
+
+    def extract(self, ctx: CompareContext) -> Dict[str, ChannelData]:
+        """
+        @brief Execute the script and parse its JSON channel payload.
+        @raises ValueError: On non-zero exit, timeout, or malformed payload.
+        """
+        if not self.script:
+            raise ValueError("script_extract: 'script' parameter is required")
+
+        cmd = [self.interpreter, self.script, *self.args]
+        # Trailing positional slots carry the framework-resolved file paths,
+        # baseline first (same convention as the script comparator); scripts
+        # that take no file inputs simply ignore them.
+        if ctx.baseline:
+            cmd.append(str(ctx.baseline))
+        if ctx.actual:
+            cmd.append(str(ctx.actual))
+
+        self.logger.info("Executing extraction script: %s", " ".join(cmd))
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                cwd=self.cwd,
+            )
+        except subprocess.TimeoutExpired:
+            raise ValueError(
+                f"script_extract: script timed out after {self.timeout}s: {self.script}"
+            )
+
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        self._last_command_output = stdout + ("\n" + stderr if stderr else "")
+
+        if proc.returncode != 0:
+            tail = (stderr.strip() or stdout.strip())[-500:]
+            raise ValueError(
+                f"script_extract: script exited with code {proc.returncode}: {self.script}"
+                + (f" — {tail}" if tail else "")
+            )
+
+        try:
+            payload = json.loads(stdout)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"script_extract: script stdout is not valid JSON ({exc}). "
+                f"Expected {{\"channels\": {{name: {{expected: [...], actual: [...]}}}}}}. "
+                f"stdout head: {stdout[:200]!r}"
+            )
+
+        return self._parse_payload(payload)
+
+    def _parse_payload(self, payload) -> Dict[str, ChannelData]:
+        """Validate the JSON document shape and build ChannelData entries."""
+        if not isinstance(payload, dict) or not isinstance(
+                payload.get("channels"), dict) or not payload["channels"]:
+            raise ValueError(
+                "script_extract: JSON payload must contain a non-empty "
+                "'channels' object mapping channel names to "
+                "{'expected': [...], 'actual': [...], 'extra_stats': {...}}"
+            )
+
+        channels: Dict[str, ChannelData] = {}
+        for name, spec in payload["channels"].items():
+            if not isinstance(spec, dict) or "expected" not in spec or "actual" not in spec:
+                raise ValueError(
+                    f"script_extract: channel '{name}' must provide "
+                    f"'expected' and 'actual' arrays"
+                )
+            extra = spec.get("extra_stats")
+            if extra is not None and not isinstance(extra, dict):
+                raise ValueError(
+                    f"script_extract: channel '{name}' extra_stats must be an object"
+                )
+            channels[str(name)] = ChannelData(
+                expected=spec["expected"],
+                actual=spec["actual"],
+                extra_stats=extra,
+            )
+        return channels
diff --git a/src/symtest/file_comparator/text_comparator.py b/src/symtest/file_comparator/text_comparator.py
index 45ea084..e626eb0 100644
--- a/src/symtest/file_comparator/text_comparator.py
+++ b/src/symtest/file_comparator/text_comparator.py
@@ -10,10 +10,10 @@
 
 import difflib
 import re
-from .base_comparator import BaseComparator
+from .file_comparator_base import FileComparator
 from .result import Difference
 
-class TextComparator(BaseComparator):
+class TextComparator(FileComparator):
     """
     @brief Comparator for text files with line-by-line comparison
     @details This class implements text file comparison using Python's difflib
diff --git a/src/symtest/reporting/__init__.py b/src/symtest/reporting/__init__.py
index 6baec8e..57abc3f 100644
--- a/src/symtest/reporting/__init__.py
+++ b/src/symtest/reporting/__init__.py
@@ -1,10 +1,17 @@
 """Reporting / result-consumer 层（原则 5）。
 
 ``diagnosis.build_next_action_hint`` 是 result consumer：只消费失败结论，
-不参与执行与判定。
+不参与执行与判定。``attach_next_action_hint(s)`` 是表现层装配点：orchestration
+只产出 ``failure_kind``，hint 在 CLI 报告装配阶段填充。
 """
-from .diagnosis import build_next_action_hint
+from .diagnosis import (
+    attach_next_action_hint,
+    attach_next_action_hints,
+    build_next_action_hint,
+)
 
 __all__ = [
     "build_next_action_hint",
+    "attach_next_action_hint",
+    "attach_next_action_hints",
 ]
diff --git a/src/symtest/reporting/diagnosis.py b/src/symtest/reporting/diagnosis.py
index 4d44892..b33e9e9 100644
--- a/src/symtest/reporting/diagnosis.py
+++ b/src/symtest/reporting/diagnosis.py
@@ -1,8 +1,8 @@
 """失败诊断（next_action_hint，原则 5：result consumer）。
 
 自 1.3 ``core/execution.py::_build_next_action_hint`` 原样搬入（公开化命名）。
-``command`` 字段留 ``None``：本层不知道 config 文件路径，由 runner 填充
-（见 ``BaseRunner._fill_hint_command``）。
+``command`` 字段由装配点填充（``attach_next_action_hint(s)``，CLI 报告
+装配阶段 / 表现层调用），orchestration 只产出 ``failure_kind``。
 """
 from typing import Any, Dict, Optional
 
@@ -82,3 +82,66 @@ def build_next_action_hint(
             "'expected' in this result."
         ),
     }
+
+
+def _hint_command(
+    case_name: str,
+    config_path: Optional[str],
+    *,
+    is_update_baseline: bool,
+) -> str:
+    """Build the concrete re-run CLI command inside a hint."""
+    base = f'symtest run "{config_path}"'
+    if is_update_baseline:
+        base += " --update-baseline"
+    return f'{base} -t "{case_name}"'
+
+
+def attach_next_action_hint(
+    result: Dict[str, Any],
+    *,
+    update_baseline: bool = False,
+    config_path: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Reporting 装配点：按 ``failure_kind`` 为单个失败结果填充 hint。
+
+    Orchestration 只产出 ``failure_kind``（原则 5 单向流）；本函数在结果
+    装配/输出阶段（CLI 报告输出前）调用，为 ``failure_kind``
+    非空的结果构建结构化建议并填充具体 CLI 命令。已带 hint 的结果只补
+    command 字段（幂等）。
+
+    Returns:
+        填充后的 hint；结果无失败结论时为 ``None``。
+    """
+    hint = result.get("next_action_hint")
+    if hint is None:
+        failure_kind = result.get("failure_kind")
+        if not failure_kind:
+            return None
+        hint = build_next_action_hint(failure_kind, update_baseline=update_baseline)
+        result["next_action_hint"] = hint
+    if hint and not hint.get("command") and config_path is not None:
+        # 与 1.3 runner 行为一致：--update-baseline 标志只由 hint 的 action
+        # 决定（update_baseline 形态仅在未开启 --update-baseline 时出现）。
+        hint["command"] = _hint_command(
+            result.get("name", ""), config_path,
+            is_update_baseline=(hint.get("action") == "update_baseline"),
+        )
+    return hint
+
+
+def attach_next_action_hints(
+    results: Dict[str, Any],
+    *,
+    update_baseline: bool = False,
+    config_path: Optional[str] = None,
+) -> None:
+    """对整次运行的 ``results``（含 ``details`` 列表）批量装配 hint。
+
+    CLI 报告输出前的唯一装配点，覆盖顺序 / 并行 / skip 全部路径；
+    passed / skipped 结果无 ``failure_kind``，天然不产生 hint。
+    """
+    for detail in results.get("details", []):
+        attach_next_action_hint(
+            detail, update_baseline=update_baseline, config_path=config_path,
+        )
diff --git a/src/symtest/tui/__init__.py b/src/symtest/tui/__init__.py
deleted file mode 100644
index cc72ad4..0000000
--- a/src/symtest/tui/__init__.py
+++ /dev/null
@@ -1,11 +0,0 @@
-"""
-TUI Manager for interactive test case CRUD.
-
-Provides a Textual-based terminal UI for browsing, editing and running
-test cases. Relies on :mod:`symtest.config.config_io` for
-configuration I/O and :mod:`symtest.core` for execution.
-
-Usage::
-
-    symtest tui test_cases.json
-"""
diff --git a/src/symtest/tui/app.py b/src/symtest/tui/app.py
deleted file mode 100644
index b87a09b..0000000
--- a/src/symtest/tui/app.py
+++ /dev/null
@@ -1,90 +0,0 @@
-"""Textual App entry point for the TUI manager.
-
-Usage::
-
-    from symtest.tui.app import run_tui
-    run_tui("test_cases.json", workspace="/path/to/project")
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Optional
-
-from textual.app import App, ComposeResult
-from textual.binding import Binding
-
-from .controllers.case_controller import CaseController
-from .screens.case_list import CaseListScreen
-
-
-class CaseManagerApp(App):
-    """Terminal UI for browsing / editing / running test cases."""
-
-    TITLE = "CLI Test Framework - Case Manager"
-
-    BINDINGS = [
-        Binding("ctrl+q", "quit", "Quit", show=True, priority=True),
-        Binding("q", "quit", "Quit", show=True, priority=True),
-    ]
-
-    CSS = """
-    Screen {
-        background: $surface;
-    }
-    """
-
-    def __init__(self, config_file: str, workspace: Optional[str] = None,
-                 update_baseline: bool = False,
-                 history_dir: Optional[str] = None,
-                 update_history: bool = False):
-        super().__init__()
-        self._config_file = config_file
-        self._workspace = workspace
-        self._controller = CaseController()
-        self._controller.update_baseline = update_baseline
-        self._controller.history_dir = history_dir
-        self._controller.update_history = update_history
-
-    def on_mount(self) -> None:
-        try:
-            count = self._controller.load(self._config_file, self._workspace)
-            self.notify(f"Loaded {count} test cases from {Path(self._config_file).name}")
-        except Exception as e:
-            self.notify(f"Failed to load config: {e}", severity="error")
-
-        self.push_screen(CaseListScreen(self._controller))
-
-
-# ---------------------------------------------------------------------------
-# Public entry point
-# ---------------------------------------------------------------------------
-
-
-def run_tui(config_file: str, workspace: Optional[str] = None,
-            update_baseline: bool = False,
-            history_dir: Optional[str] = None,
-            update_history: bool = False) -> None:
-    """Launch the TUI manager.
-
-    Safe to call without installing textual — raises :exc:`ImportError`
-    with a friendly message if textual is not available.
-    """
-    try:
-        import textual  # noqa: F401 — verify textual is importable
-    except ImportError:
-        import sys
-
-        print(
-            "TUI 功能需要安装 textual。请运行：\n"
-            "  pip install symtest-cli[tui]\n"
-            "或：\n"
-            "  pip install textual"
-        )
-        sys.exit(1)
-
-    app = CaseManagerApp(config_file, workspace,
-                         update_baseline=update_baseline,
-                         history_dir=history_dir,
-                         update_history=update_history)
-    app.run()
diff --git a/src/symtest/tui/controllers/__init__.py b/src/symtest/tui/controllers/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/src/symtest/tui/controllers/case_controller.py b/src/symtest/tui/controllers/case_controller.py
deleted file mode 100644
index 9e5f75b..0000000
--- a/src/symtest/tui/controllers/case_controller.py
+++ /dev/null
@@ -1,326 +0,0 @@
-"""Bridge between config I/O and the TUI: CRUD, search, run."""
-
-from __future__ import annotations
-
-import copy
-import logging
-import re
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-from ...core.test_case import TestCase, TestCaseStep
-from ...core.orchestration.single import execute_single_test_case
-from ...core.orchestration.sequence import execute_sequence
-from ...core.config_loader import parse_test_cases
-from ...config.config_io import load_config, save_config
-
-logger = logging.getLogger("symtest.tui.controller")
-
-# ---------------------------------------------------------------------------
-# Search helpers
-# ---------------------------------------------------------------------------
-
-# Field weights for fuzzy scoring (higher = more important).
-_FIELD_WEIGHTS: Dict[str, float] = {
-    "name": 2.0,
-    "command": 1.5,
-    "tags": 1.0,
-    "description": 1.0,
-    "args": 0.5,
-}
-
-# Default searchable fields and their extractors
-_SEARCH_FIELDS = [
-    ("name", lambda tc: tc.name),
-    ("command", lambda tc: tc.command),
-    ("args", lambda tc: " ".join(tc.args)),
-    ("tags", lambda tc: ",".join(tc.tags)),
-    ("description", lambda tc: tc.description or ""),
-]
-
-
-def _substring_match(query: str, case: TestCase) -> bool:
-    """Case-insensitive substring match across all searchable fields."""
-    q = query.lower()
-    for _field_name, extractor in _SEARCH_FIELDS:
-        if q in extractor(case).lower():
-            return True
-    return False
-
-
-def _regex_match(query: str, case: TestCase) -> bool:
-    """Regex search across all searchable fields (case-insensitive)."""
-    try:
-        pattern = re.compile(query, re.IGNORECASE)
-    except re.error:
-        return False
-    for _field_name, extractor in _SEARCH_FIELDS:
-        if pattern.search(extractor(case)):
-            return True
-    return False
-
-
-def _fuzzy_score(query: str, case: TestCase) -> float:
-    """N-gram overlap scorer; higher = better match."""
-    q = query.lower()
-    q_bigrams = {q[i : i + 2] for i in range(len(q) - 1)} if len(q) >= 2 else {q}
-    if not q_bigrams:
-        return 0.0
-
-    total = 0.0
-    for field_name, extractor in _SEARCH_FIELDS:
-        text = extractor(case).lower()
-        text_bigrams = {text[i : i + 2] for i in range(len(text) - 1)}
-        if not text_bigrams:
-            continue
-        overlap = len(q_bigrams & text_bigrams) / len(q_bigrams)
-        total += _FIELD_WEIGHTS.get(field_name, 0.5) * overlap
-    return total
-
-
-def _fuzzy_match(query: str, cases: List[TestCase], threshold: float = 0.15) -> List[int]:
-    """Return indices of cases whose fuzzy score meets *threshold*."""
-    scored: List[Tuple[int, float]] = []
-    for i, tc in enumerate(cases):
-        s = _fuzzy_score(query, tc)
-        if s >= threshold:
-            scored.append((i, s))
-    scored.sort(key=lambda x: -x[1])
-    return [idx for idx, _ in scored]
-
-
-# ---------------------------------------------------------------------------
-# CaseController
-# ---------------------------------------------------------------------------
-
-
-class CaseController:
-    """Holds test cases in memory and bridges config_io ↔ TUI."""
-
-    def __init__(self):
-        self._cases: List[TestCase] = []
-        self._file_path: Optional[Path] = None
-        self._workspace: Optional[str] = None
-        self._dirty = False
-        self._setup: Dict[str, Any] = {}
-        self._update_baseline: bool = False
-        self._history_dir: Optional[str] = None
-        self._update_history: bool = False
-
-    # -- properties ----------------------------------------------------------
-
-    @property
-    def cases(self) -> List[TestCase]:
-        return self._cases
-
-    @property
-    def file_path(self) -> Optional[Path]:
-        return self._file_path
-
-    @property
-    def file_name(self) -> str:
-        return self._file_path.name if self._file_path else "(untitled)"
-
-    @property
-    def workspace(self) -> Optional[str]:
-        return self._workspace
-
-    @property
-    def dirty(self) -> bool:
-        return self._dirty
-
-    @property
-    def case_count(self) -> int:
-        return len(self._cases)
-
-    @property
-    def update_baseline(self) -> bool:
-        return self._update_baseline
-
-    @update_baseline.setter
-    def update_baseline(self, value: bool) -> None:
-        self._update_baseline = value
-
-    @property
-    def history_dir(self) -> Optional[str]:
-        return self._history_dir
-
-    @history_dir.setter
-    def history_dir(self, value: Optional[str]) -> None:
-        self._history_dir = value
-
-    @property
-    def update_history(self) -> bool:
-        return self._update_history
-
-    @update_history.setter
-    def update_history(self, value: bool) -> None:
-        self._update_history = value
-
-    # -- load / save ---------------------------------------------------------
-
-    def load(self, file_path: str, workspace: Optional[str] = None) -> int:
-        """Load config from *file_path*, parse test cases, return case count."""
-        path = Path(file_path).resolve()
-        config = load_config(path)
-
-        # Store setup for later re-serialisation
-        self._setup = config.get("setup", {})
-        self._file_path = path
-        self._workspace = workspace
-
-        # Parse test cases via unified entry point. TUI owns the relaxed
-        # form explicitly (1.4 原则 6)：no path resolution for display and
-        # strict=False so incomplete cases get sensible defaults.
-        self._cases = parse_test_cases(config, strict=False)
-        self._dirty = False
-        return len(self._cases)
-
-    def save(self, file_path: Optional[str] = None) -> None:
-        """Persist cases to the current file (or *file_path* if given)."""
-        target = Path(file_path) if file_path else self._file_path
-        if target is None:
-            raise ValueError("No file path set for save.")
-
-        config: Dict[str, Any] = {"test_cases": []}
-        if self._setup:
-            config["setup"] = self._setup
-        config["test_cases"] = [tc.to_dict() for tc in self._cases]
-
-        save_config(config, target)
-
-        if file_path:
-            self._file_path = Path(file_path).resolve()
-
-        self._dirty = False
-
-    def save_as(self, file_path: str) -> None:
-        """Save to a different file."""
-        self.save(file_path=file_path)
-
-    # -- CRUD ----------------------------------------------------------------
-
-    def get_case(self, index: int) -> TestCase:
-        return self._cases[index]
-
-    def add_case(self, case: TestCase) -> int:
-        """Append *case*; return its index."""
-        self._cases.append(case)
-        self._dirty = True
-        return len(self._cases) - 1
-
-    def update_case(self, index: int, case: TestCase) -> None:
-        self._cases[index] = case
-        self._dirty = True
-
-    def delete_case(self, index: int) -> None:
-        del self._cases[index]
-        self._dirty = True
-
-    def duplicate_case(self, index: int) -> int:
-        """Deep-copy case at *index*, append '_copy' to name."""
-        original = self._cases[index]
-        new_case = copy.deepcopy(original)
-        new_case.name = original.name + "_copy"
-        return self.add_case(new_case)
-
-    def move_case(self, from_idx: int, to_idx: int) -> None:
-        """Move case from *from_idx* to *to_idx*."""
-        if from_idx == to_idx:
-            return
-        case = self._cases.pop(from_idx)
-        self._cases.insert(to_idx, case)
-        self._dirty = True
-
-    def swap_cases(self, i: int, j: int) -> None:
-        self._cases[i], self._cases[j] = self._cases[j], self._cases[i]
-        self._dirty = True
-
-    # -- search --------------------------------------------------------------
-
-    def search(
-        self,
-        query: str,
-        mode: str = "substring",
-        tag: Optional[str] = None,
-    ) -> List[int]:
-        """Return sorted list of indices for cases matching *query*.
-
-        Parameters
-        ----------
-        query:
-            Search term.
-        mode:
-            ``"substring"`` (default), ``"fuzzy"``, or ``"regex"``.
-        tag:
-            Optional tag filter (exact match).
-        """
-        if mode == "fuzzy":
-            indices = _fuzzy_match(query, self._cases)
-        elif mode == "regex":
-            indices = [i for i, tc in enumerate(self._cases) if _regex_match(query, tc)]
-        else:  # substring (default)
-            indices = [i for i, tc in enumerate(self._cases) if _substring_match(query, tc)]
-
-        # Apply tag filter
-        if tag:
-            indices = [i for i in indices if tag in self._cases[i].tags]
-
-        return indices
-
-    def get_all_tags(self) -> List[str]:
-        """Collect unique tags across all cases, sorted."""
-        tags: set = set()
-        for tc in self._cases:
-            tags.update(tc.tags)
-        return sorted(tags)
-
-    # -- run ----------------------------------------------------------------
-
-    def run_case(self, index: int) -> Dict[str, Any]:
-        """Execute a single test case and return the result dict."""
-        case = self._cases[index]
-        if case.steps:
-            # Sequence mode — use execute_sequence (consistent with Runner)
-            result = execute_sequence(
-                case_name=case.name,
-                steps=case.steps,
-                workspace=self._workspace,
-                update_baseline=self._update_baseline,
-            )
-        else:
-            # Single-command mode — ExecutionSpec + expectation 直供编排层
-            result = execute_single_test_case(
-                case.execution,
-                self._workspace,
-                expectation=case.expected,
-                update_baseline=self._update_baseline,
-            )
-        self._record_history(case.name, result)
-        return result
-
-    def _record_history(self, case_name: str, result: Dict[str, Any]) -> None:
-        """Per-case history recording with optional reset support."""
-        if not self._history_dir:
-            return
-        from pathlib import Path as _Path
-        from ...core.history_store import load_history, save_history, reset_cases, update_case
-
-        history_dir = str((_Path(self._workspace or ".") / self._history_dir).resolve())
-        history = load_history(history_dir)
-
-        if self._update_history:
-            cleared = reset_cases(history, {case_name})
-            if cleared:
-                logger.info("History reset: cleared '%s'", case_name)
-
-        if result.get("status") == "passed":
-            update_case(history, case_name, result.get("duration", 0))
-        save_history(history_dir, history)
-
-    @staticmethod
-    def create_empty_case(mode: str = "single") -> TestCase:
-        """Create a blank TestCase."""
-        if mode == "sequence":
-            return TestCase(name="new_case", steps=[])
-        return TestCase(name="new_case", command="", args=[], expected={}, tags=[])
diff --git a/src/symtest/tui/screens/__init__.py b/src/symtest/tui/screens/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/src/symtest/tui/screens/case_editor.py b/src/symtest/tui/screens/case_editor.py
deleted file mode 100644
index 9a47fc5..0000000
--- a/src/symtest/tui/screens/case_editor.py
+++ /dev/null
@@ -1,282 +0,0 @@
-"""Screen for editing a single test case (both single-cmd and sequence modes)."""
-
-from __future__ import annotations
-
-from textual import on
-from textual.screen import Screen
-from textual.widgets import Input, TextArea, Static, Button, Header, Footer, Label
-from textual.containers import Horizontal, Vertical, Container, ScrollableContainer
-from textual.message import Message
-
-from ...core.test_case import TestCase
-from ..widgets.expected_editor import ExpectedEditor
-from ..widgets.steps_editor import StepsEditor
-
-
-class CaseEditorScreen(Screen):
-    """Full-screen form for creating / editing a test case."""
-
-    DEFAULT_CSS = """
-    CaseEditorScreen {
-        align: center middle;
-    }
-    CaseEditorScreen #editor-container {
-        width: 90%;
-        height: 90%;
-        border: solid $primary;
-        padding: 1 2;
-    }
-    CaseEditorScreen #editor-fields {
-        height: 1fr;
-    }
-    CaseEditorScreen #editor-footer {
-        height: auto;
-        margin-top: 1;
-        align-horizontal: right;
-    }
-    CaseEditorScreen Input {
-        width: 100%;
-        margin-bottom: 1;
-    }
-    CaseEditorScreen Label {
-        margin-top: 1;
-    }
-    CaseEditorScreen #case-tags {
-        width: 100%;
-    }
-    CaseEditorScreen #case-description {
-        height: 3;
-        margin-bottom: 1;
-    }
-    CaseEditorScreen #case-timeout {
-        width: 15;
-    }
-    CaseEditorScreen #case-env {
-        height: 3;
-        margin-bottom: 1;
-    }
-    CaseEditorScreen #mode-indicator {
-        color: $accent;
-        text-style: bold;
-    }
-    """
-
-    class Saved(Message):
-        """Emitted when user saves, carrying the TestCase."""
-
-        def __init__(self, case: TestCase):
-            super().__init__()
-            self.case = case
-
-    class Cancelled(Message):
-        """Emitted when user cancels editing."""
-
-    def __init__(self, case: TestCase | None = None):
-        super().__init__()
-        self._case: TestCase | None = case
-        self._is_sequence = case is not None and case.steps is not None
-
-    def compose(self):
-        yield Header()
-        yield Vertical(
-            ScrollableContainer(
-                Label("Name:", id="name-label"),
-                Input(placeholder="test_case_name", id="case-name"),
-                Label("Mode:", id="mode-label"),
-                Static("Single Command", id="mode-indicator"),
-                Label("Command:", id="cmd-label"),
-                Input(placeholder="python", id="case-command"),
-                Label("Args (space-separated):", id="args-label"),
-                Input(placeholder="./script.py --flag", id="case-args"),
-                Label("Tags (comma-separated):", id="tags-label"),
-                Input(placeholder="tag1, tag2", id="case-tags"),
-                Label("Description:", id="desc-label"),
-                TextArea("", id="case-description"),
-                Label("Timeout (seconds):", id="timeout-label"),
-                Input(placeholder="", id="case-timeout"),
-                Label("Retry count:", id="retry-label"),
-                Input(placeholder="0", id="case-retry-count"),
-                Label("Environment variables (one per line, KEY=VALUE):", id="env-label"),
-                TextArea("", id="case-env"),
-                ExpectedEditor(id="expected-editor"),
-                StepsEditor(id="steps-editor"),
-                id="editor-fields",
-            ),
-            Horizontal(
-                Button("Save", id="btn-save", variant="primary"),
-                Button("Cancel", id="btn-cancel"),
-                Button("Switch to Sequence", id="btn-switch-mode"),
-                id="editor-footer",
-            ),
-            id="editor-container",
-        )
-        yield Footer()
-
-    def on_mount(self) -> None:
-        if self._case is None:
-            self._case = TestCase(name="new_case", command="", args=[], expected={}, tags=[])
-            self._is_sequence = False
-        else:
-            self._is_sequence = self._case.steps is not None
-
-        self._populate_form()
-        self._update_mode_visibility()
-
-    # -- populate / collect --------------------------------------------------
-
-    def _populate_form(self) -> None:
-        if self._case is None:
-            return
-        tc = self._case
-
-        self.query_one("#case-name", Input).value = tc.name
-        self.query_one("#case-command", Input).value = tc.command
-        self.query_one("#case-args", Input).value = " ".join(tc.args) if tc.args else ""
-        self.query_one("#case-tags", Input).value = ",".join(tc.tags) if tc.tags else ""
-        self.query_one("#case-description", TextArea).text = tc.description or ""
-        self.query_one("#case-timeout", Input).value = str(tc.timeout) if tc.timeout else ""
-        self.query_one("#case-retry-count", Input).value = str(tc.retry_count) if tc.retry_count else ""
-        self.query_one("#case-env", TextArea).text = self._format_env_text(tc.env)
-
-        self.query_one("#expected-editor", ExpectedEditor).load(tc.expected or {})
-
-        if self._is_sequence and tc.steps:
-            self.query_one("#steps-editor", StepsEditor).load(tc.steps)
-
-        self.query_one("#mode-indicator", Static).update(
-            "Sequence Mode" if self._is_sequence else "Single Command"
-        )
-        switch_btn = self.query_one("#btn-switch-mode", Button)
-        switch_btn.label = "Switch to Sequence" if not self._is_sequence else "Switch to Single"
-
-    def _collect_case(self) -> TestCase:
-        name = self.query_one("#case-name", Input).value.strip() or "unnamed"
-        tags_text = self.query_one("#case-tags", Input).value
-        tags = [t.strip() for t in tags_text.split(",") if t.strip()]
-
-        timeout_text = self.query_one("#case-timeout", Input).value.strip()
-        timeout = float(timeout_text) if timeout_text else None
-
-        retry_text = self.query_one("#case-retry-count", Input).value.strip()
-        retry_count = int(retry_text) if retry_text else 0
-
-        description = self.query_one("#case-description", TextArea).text.strip()
-        env = self._parse_env_text(self.query_one("#case-env", TextArea).text)
-
-        if self._is_sequence:
-            steps = self.query_one("#steps-editor", StepsEditor).to_steps()
-            expected = self.query_one("#expected-editor", ExpectedEditor).to_dict()
-            return TestCase(
-                name=name,
-                steps=steps,
-                expected=expected,
-                description=description or "",
-                timeout=timeout,
-                resources=self._case.resources if self._case else None,
-                tags=tags,
-                retry_count=retry_count,
-                env=env,
-            )
-        else:
-            command = self.query_one("#case-command", Input).value.strip()
-            args_text = self.query_one("#case-args", Input).value.strip()
-            args = args_text.split() if args_text else []
-            expected = self.query_one("#expected-editor", ExpectedEditor).to_dict()
-
-            return TestCase(
-                name=name,
-                command=command,
-                args=args,
-                expected=expected,
-                description=description or "",
-                timeout=timeout,
-                resources=self._case.resources if self._case else None,
-                tags=tags,
-                retry_count=retry_count,
-                env=env,
-            )
-
-    @staticmethod
-    def _format_env_text(env: dict | None) -> str:
-        """Serialize an ``env`` dict to ``KEY=VALUE`` lines."""
-        if not env:
-            return ""
-        return "\n".join(f"{k}={v}" for k, v in env.items())
-
-    @staticmethod
-    def _parse_env_text(text: str) -> dict:
-        """Parse ``KEY=VALUE`` lines into a dict, skipping blanks/comments.
-
-        Invalid lines (no ``=`` or empty key) are ignored silently so the
-        editor stays forgiving; a malformed line is simply not exported.
-        """
-        result: dict = {}
-        for line in text.splitlines():
-            line = line.strip()
-            if not line or line.startswith("#"):
-                continue
-            if "=" not in line:
-                continue
-            key, _, value = line.partition("=")
-            key = key.strip()
-            if not key:
-                continue
-            result[key] = value.strip()
-        return result
-
-    def _update_mode_visibility(self) -> None:
-        """Show/hide fields based on current mode."""
-        cmd_label = self.query_one("#cmd-label", Label)
-        args_label = self.query_one("#args-label", Label)
-        cmd_input = self.query_one("#case-command", Input)
-        args_input = self.query_one("#case-args", Input)
-        expected = self.query_one("#expected-editor", ExpectedEditor)
-        steps = self.query_one("#steps-editor", StepsEditor)
-        mode_label = self.query_one("#mode-label", Label)
-        mode_indicator = self.query_one("#mode-indicator", Static)
-        switch_btn = self.query_one("#btn-switch-mode", Button)
-
-        if self._is_sequence:
-            mode_label.display = True
-            mode_indicator.display = True
-            cmd_label.display = False
-            args_label.display = False
-            cmd_input.display = False
-            args_input.display = False
-            expected.display = True
-            steps.display = True
-            switch_btn.label = "Switch to Single"
-        else:
-            mode_label.display = False
-            mode_indicator.display = True
-            cmd_label.display = True
-            args_label.display = True
-            cmd_input.display = True
-            args_input.display = True
-            expected.display = True
-            steps.display = False
-            switch_btn.label = "Switch to Sequence"
-
-    # -- button handlers -----------------------------------------------------
-
-    @on(Button.Pressed, "#btn-save")
-    def _on_save(self) -> None:
-        try:
-            case = self._collect_case()
-        except Exception as e:
-            self.notify(f"Error: {e}", severity="error")
-            return
-        self.post_message(self.Saved(case))
-        self.dismiss()
-
-    @on(Button.Pressed, "#btn-cancel")
-    def _on_cancel(self) -> None:
-        self.post_message(self.Cancelled())
-        self.dismiss()
-
-    @on(Button.Pressed, "#btn-switch-mode")
-    def _on_switch_mode(self) -> None:
-        self._is_sequence = not self._is_sequence
-        mode_label = self.query_one("#mode-indicator", Static)
-        mode_label.update("Sequence Mode" if self._is_sequence else "Single Command")
-        self._update_mode_visibility()
diff --git a/src/symtest/tui/screens/case_list.py b/src/symtest/tui/screens/case_list.py
deleted file mode 100644
index 16ff8ef..0000000
--- a/src/symtest/tui/screens/case_list.py
+++ /dev/null
@@ -1,255 +0,0 @@
-"""Main screen: case table + search bar + status."""
-
-from __future__ import annotations
-
-from textual.screen import Screen
-from textual.widgets import Header, Footer, Static
-from textual.containers import Horizontal, Container
-from textual.binding import Binding
-
-from ..controllers.case_controller import CaseController
-from ..widgets.case_table import CaseTable
-from ..widgets.search_bar import SearchBar
-from .case_editor import CaseEditorScreen
-
-
-class CaseListScreen(Screen):
-    """Primary TUI screen showing the test case table."""
-
-    BINDINGS = [
-        Binding("/", "focus_search", "Search", show=True),
-        Binding("escape", "clear_search", "Clear search", show=True),
-        Binding("a", "add_case", "Add", show=True),
-        Binding("e", "edit_case", "Edit", show=True),
-        Binding("d", "delete_case", "Delete", show=True),
-        Binding("u", "duplicate_case", "Dup", show=True),
-        Binding("r", "run_case", "Run", show=True),
-        Binding("f6", "save_file", "Save", show=True),
-        Binding("ctrl+s", "save_file", "Save", show=False),
-        Binding("ctrl+q", "quit", "Quit", show=True),
-        Binding("q", "quit", "Quit", show=True),
-        Binding("n", "next_match", "Next", show=False),
-        Binding("shift+enter", "prev_match", "Prev", show=False),
-        Binding("up", "cursor_up", "", show=False),
-        Binding("down", "cursor_down", "", show=False),
-        Binding("alt+f", "toggle_fuzzy", "", show=False),
-        Binding("alt+r", "toggle_regex", "", show=False),
-        Binding("alt+s", "toggle_substring", "", show=False),
-    ]
-
-    DEFAULT_CSS = """
-    CaseListScreen {
-        align: center middle;
-    }
-    CaseListScreen #status-bar {
-        height: 1;
-        padding: 0 1;
-        background: $panel;
-    }
-    CaseListScreen #status-bar Static {
-        width: 1fr;
-    }
-    """
-
-    def __init__(self, controller: CaseController):
-        super().__init__()
-        self._ctrl = controller
-        self._filtered_indices: list[int] = list(range(len(controller.cases)))
-        self._cur_match: int = 0
-        self._current_tag: str | None = None
-
-    def compose(self):
-        yield Header()
-        yield SearchBar(id="main-search")
-        yield CaseTable(id="main-table")
-        yield Container(
-            Horizontal(
-                Static(f"File: {self._ctrl.file_name}", id="status-file"),
-                Static(f"{self._ctrl.case_count} cases", id="status-count"),
-                Static("Tag: All", id="status-tag"),
-                Static("", id="status-dirty"),
-                id="status-inner",
-            ),
-            id="status-bar",
-        )
-        yield Footer()
-
-    def on_mount(self) -> None:
-        self._refresh_table()
-        self._update_status()
-
-    # -- table refresh -------------------------------------------------------
-
-    def _refresh_table(self) -> None:
-        table = self.query_one("#main-table", CaseTable)
-        table.refresh_rows(self._ctrl.cases, self._filtered_indices)
-
-    def _update_status(self) -> None:
-        self.query_one("#status-count", Static).update(
-            f"{len(self._filtered_indices)}/{self._ctrl.case_count} cases"
-        )
-        tag_label = self.query_one("#status-tag", Static)
-        tag_label.update(f"Tag: {self._current_tag or 'All'}")
-        dirty = self._ctrl.dirty
-        self.query_one("#status-dirty", Static).update(
-            "[MODIFIED]" if dirty else ""
-        )
-
-    # -- search handling -----------------------------------------------------
-
-    def on_search_bar_search_changed(self, event: SearchBar.SearchChanged) -> None:
-        sb = self.query_one("#main-search", SearchBar)
-        self._filtered_indices = self._ctrl.search(
-            event.query, event.mode, self._current_tag
-        )
-        self._cur_match = 0
-        sb.set_match_count(len(self._filtered_indices), 0)
-        self._refresh_table()
-        self._update_status()
-        # Select first match
-        if self._filtered_indices:
-            table = self.query_one("#main-table", CaseTable)
-            table.select_row_by_index(self._filtered_indices[0])
-            self._cur_match = 1
-            sb.set_match_count(len(self._filtered_indices), 1)
-
-    def on_search_bar_search_navigated(self, event: SearchBar.SearchNavigated) -> None:
-        sb = self.query_one("#main-search", SearchBar)
-        table = self.query_one("#main-table", CaseTable)
-        if event.delta > 0:
-            table.select_next_match()
-        else:
-            table.select_prev_match()
-        # Update current match display
-        if self._filtered_indices and table.cursor_coordinate.row < len(self._filtered_indices):
-            self._cur_match = table.cursor_coordinate.row + 1
-            sb.set_match_count(len(self._filtered_indices), self._cur_match)
-
-    # -- actions -------------------------------------------------------------
-
-    def action_focus_search(self) -> None:
-        sb = self.query_one("#main-search", SearchBar)
-        sb.query_one("#search-input").focus()
-
-    def action_clear_search(self) -> None:
-        self.query_one("#main-search", SearchBar).clear()
-        self._filtered_indices = list(range(len(self._ctrl.cases)))
-        self._refresh_table()
-        self._update_status()
-
-    def action_add_case(self) -> None:
-        self.app.push_screen(
-            CaseEditorScreen(),
-            callback=self._on_editor_done,
-        )
-
-    def action_edit_case(self) -> None:
-        idx = self._get_current_case_index()
-        if idx is None:
-            self.notify("No case selected", severity="warning")
-            return
-        case = self._ctrl.get_case(idx)
-        self.app.push_screen(
-            CaseEditorScreen(case),
-            callback=lambda msg: self._on_editor_done(msg, original_idx=idx),
-        )
-
-    def action_delete_case(self) -> None:
-        idx = self._get_current_case_index()
-        if idx is None:
-            self.notify("No case selected", severity="warning")
-            return
-        case_name = self._ctrl.get_case(idx).name
-        self._ctrl.delete_case(idx)
-        self.notify(f"Deleted: {case_name}")
-        self._refresh_filtered()
-        self._update_status()
-
-    def action_duplicate_case(self) -> None:
-        idx = self._get_current_case_index()
-        if idx is None:
-            self.notify("No case selected", severity="warning")
-            return
-        new_idx = self._ctrl.duplicate_case(idx)
-        self.notify(f"Duplicated as: {self._ctrl.get_case(new_idx).name}")
-        self._refresh_filtered()
-        self._update_status()
-
-    def action_run_case(self) -> None:
-        idx = self._get_current_case_index()
-        if idx is None:
-            self.notify("No case selected", severity="warning")
-            return
-        case = self._ctrl.get_case(idx)
-        self.notify(f"Running: {case.name}...")
-        try:
-            result = self._ctrl.run_case(idx)
-            status_icon = "[OK]" if result["status"] == "passed" else "[FAIL]"
-            # Build rich status line with new result fields
-            parts = [f"{status_icon} {case.name}"]
-            parts.append(f"rc={result.get('return_code')}")
-            parts.append(f"{result.get('duration', 0):.2f}s")
-            # Failure kind
-            if result.get("failure_kind"):
-                parts.append(f"kind={result['failure_kind']}")
-            # Flaky / attempts
-            if result.get("flaky"):
-                parts.append(f"flaky ({result.get('attempts', 1)} attempts)")
-            elif result.get("attempts", 1) > 1:
-                parts.append(f"{result['attempts']} attempts")
-            # Failed step (sequence)
-            if result.get("failed_step"):
-                parts.append(f"step={result['failed_step']}")
-            self.notify(
-                " | ".join(parts),
-                severity="information" if result["status"] == "passed" else "error",
-            )
-            # Show error message separately for failed cases
-            if result["status"] != "passed" and result.get("message"):
-                self.notify(f"[ERROR] {result['message']}", severity="error")
-            # Show baseline updates
-            if result.get("baseline_updated"):
-                for bu in result["baseline_updated"]:
-                    self.notify(f"[BASELINE UPDATED] {bu}", severity="information")
-        except Exception as e:
-            self.notify(f"Run error: {e}", severity="error")
-
-    def action_save_file(self) -> None:
-        try:
-            self._ctrl.save()
-            self.notify(f"Saved to {self._ctrl.file_name}")
-            self._update_status()
-        except Exception as e:
-            self.notify(f"Save error: {e}", severity="error")
-
-    def action_toggle_fuzzy(self) -> None:
-        self.query_one("#main-search", SearchBar).action_toggle_fuzzy()
-
-    def action_toggle_regex(self) -> None:
-        self.query_one("#main-search", SearchBar).action_toggle_regex()
-
-    def action_toggle_substring(self) -> None:
-        self.query_one("#main-search", SearchBar).action_toggle_substring()
-
-    # -- helpers -------------------------------------------------------------
-
-    def _get_current_case_index(self) -> int | None:
-        table = self.query_one("#main-table", CaseTable)
-        return table.get_selected_index()
-
-    def _refresh_filtered(self) -> None:
-        sb = self.query_one("#main-search", SearchBar)
-        self._filtered_indices = self._ctrl.search(
-            sb.query, sb.mode, self._current_tag
-        )
-        self._refresh_table()
-        self._update_status()
-
-    def _on_editor_done(self, msg, original_idx=None) -> None:
-        if isinstance(msg, CaseEditorScreen.Saved):
-            if original_idx is not None:
-                self._ctrl.update_case(original_idx, msg.case)
-            else:
-                self._ctrl.add_case(msg.case)
-            self._refresh_filtered()
-            self._update_status()
diff --git a/src/symtest/tui/widgets/__init__.py b/src/symtest/tui/widgets/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/src/symtest/tui/widgets/case_table.py b/src/symtest/tui/widgets/case_table.py
deleted file mode 100644
index 2f7803e..0000000
--- a/src/symtest/tui/widgets/case_table.py
+++ /dev/null
@@ -1,113 +0,0 @@
-"""DataTable wrapper for displaying test cases."""
-
-from __future__ import annotations
-
-from textual.widgets import DataTable
-from textual.coordinate import Coordinate
-
-from ...core.test_case import TestCase
-
-
-class CaseTable(DataTable):
-    """DataTable pre-configured for test case display."""
-
-    DEFAULT_CSS = """
-    CaseTable {
-        height: 1fr;
-        min-height: 5;
-    }
-    """
-
-    COLUMNS = ("#", "Name", "Command", "Tags", "Timeout", "Mode")
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(cursor_type="row", zebra_stripes=True, *args, **kwargs)
-        self._case_indices: list[int] = []
-        self._all_tags: list[str] = []
-        self._filtered_tag: str | None = None
-
-    def on_mount(self) -> None:
-        for col in self.COLUMNS:
-            self.add_column(col, key=col.lower())
-
-    # -- public API ----------------------------------------------------------
-
-    def refresh_rows(self, cases: list[TestCase], indices: list[int]) -> None:
-        """Clear table and repopulate with the cases at *indices*."""
-        self.clear()
-        self._case_indices = list(indices)
-        for i, ci in enumerate(indices):
-            tc = cases[ci]
-            mode = "seq" if tc.steps else "cmd"
-            tags = ",".join(tc.tags) if tc.tags else "-"
-            timeout = str(tc.timeout) if tc.timeout else "-"
-            self.add_row(
-                str(i + 1),
-                tc.name,
-                self._truncate(tc.command, 30),
-                tags,
-                timeout,
-                mode,
-                key=str(ci),
-            )
-
-    def get_selected_index(self) -> int | None:
-        """Return the case index of the currently selected row."""
-        if self.row_count == 0:
-            return None
-        row_key = self.coordinate_to_cell_key(self.cursor_coordinate)
-        if row_key is not None:
-            return int(str(row_key.row_key.value))
-        return None
-
-    def select_row_by_index(self, case_index: int) -> None:
-        """Move cursor to the row corresponding to *case_index*."""
-        try:
-            row_key = self._row_key_for_case(case_index)
-            if row_key is not None:
-                self.move_cursor(row=row_key)
-        except Exception:
-            pass
-
-    def select_next_match(self) -> int | None:
-        """Move down one row; return new selected case index."""
-        if self.row_count == 0:
-            return None
-        cr = self.cursor_coordinate
-        new_row = min(cr.row + 1, self.row_count - 1)
-        self.move_cursor(row=new_row)
-        return self.get_selected_index()
-
-    def select_prev_match(self) -> int | None:
-        """Move up one row; return new selected case index."""
-        if self.row_count == 0:
-            return None
-        cr = self.cursor_coordinate
-        new_row = max(cr.row - 1, 0)
-        self.move_cursor(row=new_row)
-        return self.get_selected_index()
-
-    # -- tag filter ----------------------------------------------------------
-
-    def set_all_tags(self, tags: list[str]) -> None:
-        self._all_tags = list(tags)
-
-    @property
-    def filtered_tag(self) -> str | None:
-        return self._filtered_tag
-
-    # -- helpers -------------------------------------------------------------
-
-    @staticmethod
-    def _truncate(text: str, max_len: int) -> str:
-        if len(text) <= max_len:
-            return text
-        return text[: max_len - 2] + ".."
-
-    def _row_key_for_case(self, case_index: int) -> object | None:
-        """Find the row key for a given *case_index*."""
-        for i in range(self.row_count):
-            key = self.coordinate_to_cell_key(Coordinate(i, 0))
-            if key is not None and str(key.row_key.value) == str(case_index):
-                return key.row_key
-        return None
diff --git a/src/symtest/tui/widgets/expected_editor.py b/src/symtest/tui/widgets/expected_editor.py
deleted file mode 100644
index 0cf581e..0000000
--- a/src/symtest/tui/widgets/expected_editor.py
+++ /dev/null
@@ -1,159 +0,0 @@
-"""Widget for editing a test case's ``expected`` dict.
-
-Provides structured inputs for known keys (return_code, output_contains,
-output_matches, compare_files) and a free-form area for custom key-value pairs.
-
-Uses an internal ``_data`` dict so that ``load()`` / ``to_dict()`` work
-even when the widget is not mounted (e.g. in tests).
-"""
-
-from __future__ import annotations
-
-import copy
-import json
-from typing import Any, Dict
-
-from textual.widgets import Input, TextArea, Static
-from textual.containers import Vertical
-from textual.message import Message
-
-
-class ExpectedEditor(Vertical):
-    """Nested-dict editor for the ``expected`` field of a test case."""
-
-    DEFAULT_CSS = """
-    ExpectedEditor {
-        height: auto;
-        border: solid $primary;
-        padding: 1;
-    }
-    ExpectedEditor Static.label {
-        color: $text-muted;
-        height: 1;
-        margin-top: 1;
-    }
-    ExpectedEditor #expected-return-code {
-        width: 10;
-    }
-    ExpectedEditor #expected-output-contains {
-        height: 3;
-    }
-    ExpectedEditor #expected-custom {
-        height: 4;
-    }
-    """
-
-    class Changed(Message):
-        """Emitted whenever the expected dict is modified."""
-
-    _KNOWN_KEYS = {"return_code", "output_contains", "output_matches", "compare_files"}
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self._data: Dict[str, Any] = {}
-
-    def compose(self):
-        yield Static("─ Expected ─", classes="label")
-        yield Static("return_code:", classes="label")
-        yield Input(placeholder="0", id="expected-return-code")
-        yield Static("output_contains (one per line):", classes="label")
-        yield TextArea("", id="expected-output-contains")
-        yield Static("output_matches (regex):", classes="label")
-        yield Input(placeholder=".*", id="expected-output-matches")
-        yield Static(
-            "compare_files (one JSON per line: {actual, baseline, type, start_line?, end_line?, start_column?, end_column?}):",
-            classes="label",
-        )
-        yield TextArea("", id="expected-compare-files")
-        yield Static("Custom key-value pairs (key=value, one per line):", classes="label")
-        yield TextArea("", id="expected-custom")
-
-    def on_mount(self) -> None:
-        """Populate UI from internal data on mount."""
-        self._sync_to_ui()
-
-    # -- public API ----------------------------------------------------------
-
-    def load(self, expected: Dict[str, Any]) -> None:
-        """Populate the editor from an *expected* dict."""
-        self._data = copy.deepcopy(expected)
-        if self.is_mounted:
-            self._sync_to_ui()
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Reconstruct the expected dict from the current widget values."""
-        if self.is_mounted:
-            self._sync_from_ui()
-        return copy.deepcopy(self._data)
-
-    # -- internal sync -------------------------------------------------------
-
-    def _sync_to_ui(self) -> None:
-        """Push internal ``_data`` into the widget children."""
-        rc = self._data.get("return_code")
-        self.query_one("#expected-return-code", Input).value = str(rc) if rc is not None else ""
-
-        oc = self._data.get("output_contains", [])
-        self.query_one("#expected-output-contains", TextArea).text = "\n".join(oc)
-
-        om = self._data.get("output_matches", "")
-        self.query_one("#expected-output-matches", Input).value = om
-
-        cf = self._data.get("compare_files", [])
-        cf_lines = [json.dumps(item, ensure_ascii=False) for item in cf]
-        self.query_one("#expected-compare-files", TextArea).text = "\n".join(cf_lines)
-
-        custom_lines = [
-            f"{k}={json.dumps(v, ensure_ascii=False)}"
-            for k, v in self._data.items()
-            if k not in self._KNOWN_KEYS
-        ]
-        self.query_one("#expected-custom", TextArea).text = "\n".join(custom_lines)
-
-    def _sync_from_ui(self) -> None:
-        """Pull widget children values into ``_data``."""
-        self._data = {}
-
-        rc_text = self.query_one("#expected-return-code", Input).value.strip()
-        if rc_text:
-            try:
-                self._data["return_code"] = int(rc_text)
-            except ValueError:
-                self._data["return_code"] = rc_text
-
-        oc_text = self.query_one("#expected-output-contains", TextArea).text.strip()
-        if oc_text:
-            self._data["output_contains"] = [
-                line for line in oc_text.splitlines() if line.strip()
-            ]
-
-        om_text = self.query_one("#expected-output-matches", Input).value.strip()
-        if om_text:
-            self._data["output_matches"] = om_text
-
-        cf_text = self.query_one("#expected-compare-files", TextArea).text.strip()
-        if cf_text:
-            cf_list = []
-            for line in cf_text.splitlines():
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    cf_list.append(json.loads(line))
-                except json.JSONDecodeError:
-                    pass
-            if cf_list:
-                self._data["compare_files"] = cf_list
-
-        custom_text = self.query_one("#expected-custom", TextArea).text.strip()
-        if custom_text:
-            for line in custom_text.splitlines():
-                line = line.strip()
-                if "=" not in line:
-                    continue
-                key, _, value = line.partition("=")
-                key = key.strip()
-                try:
-                    self._data[key] = json.loads(value.strip())
-                except (json.JSONDecodeError, ValueError):
-                    self._data[key] = value.strip()
diff --git a/src/symtest/tui/widgets/search_bar.py b/src/symtest/tui/widgets/search_bar.py
deleted file mode 100644
index dd0d82e..0000000
--- a/src/symtest/tui/widgets/search_bar.py
+++ /dev/null
@@ -1,160 +0,0 @@
-"""Search bar widget with multi-mode search (substring / fuzzy / regex).
-
-Emits :class:`SearchChanged` when the query text or mode changes, and
-:class:`SearchNavigated` when the user cycles through matches.
-"""
-
-from __future__ import annotations
-
-from textual import on
-from textual.widgets import Input, Static
-from textual.containers import Horizontal
-from textual.message import Message
-
-
-class SearchBar(Horizontal):
-    """A search bar with mode toggle and result count."""
-
-    DEFAULT_CSS = """
-    SearchBar {
-        height: auto;
-        padding: 0 1;
-        margin-bottom: 1;
-    }
-    SearchBar #search-input {
-        width: 40;
-    }
-    SearchBar #search-mode {
-        width: 12;
-        padding: 0 1;
-        color: $text-muted;
-    }
-    SearchBar #search-count {
-        width: auto;
-        padding: 0 1;
-        color: $text-muted;
-    }
-    """
-
-    # Maps keyboard modifiers to modes
-    _MODES = {
-        0: "substring",
-        2: "regex",   # Alt pressed
-        4: "fuzzy",   # Ctrl pressed → fuzzy mode
-    }
-
-    class SearchChanged(Message):
-        """Emitted when search query or mode changes."""
-
-        def __init__(self, query: str, mode: str):
-            super().__init__()
-            self.query = query
-            self.mode = mode
-
-    class SearchNavigated(Message):
-        """Emitted to jump to match N."""
-
-        def __init__(self, delta: int):
-            super().__init__()
-            self.delta = delta
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self._query = ""
-        self._mode: str = "substring"
-        self._match_count = 0
-        self._history: list[str] = []
-        self._history_idx = -1
-
-    def compose(self):
-        yield Input(placeholder="Search...", id="search-input")
-        yield Static("[子串]", id="search-mode")
-        yield Static("", id="search-count")
-
-    # -- mode toggle via key bindings ----------------------------------------
-
-    def _handle_mode_toggle(self, mode: str, label: str) -> None:
-        if self._mode != mode:
-            self._mode = mode
-            self.query_one("#search-mode", Static).update(label)
-            self.post_message(self.SearchChanged(self._query, self._mode))
-
-    def action_toggle_substring(self) -> None:
-        self._handle_mode_toggle("substring", "[子串]")
-
-    def action_toggle_fuzzy(self) -> None:
-        self._handle_mode_toggle("fuzzy", "[模糊]")
-
-    def action_toggle_regex(self) -> None:
-        self._handle_mode_toggle("regex", "[正则]")
-
-    # -- input handling ------------------------------------------------------
-
-    @on(Input.Changed, "#search-input")
-    def _on_input_changed(self, event: Input.Changed) -> None:
-        self._query = event.value.strip()
-        self.post_message(self.SearchChanged(self._query, self._mode))
-
-    @on(Input.Submitted, "#search-input")
-    def _on_input_submitted(self, _event: Input.Submitted) -> None:
-        # Add to history (dedup, keep last 10)
-        if self._query and (not self._history or self._history[-1] != self._query):
-            self._history.append(self._query)
-            if len(self._history) > 10:
-                self._history.pop(0)
-        self._history_idx = -1
-        self.post_message(self.SearchNavigated(1))
-
-    # -- public API ----------------------------------------------------------
-
-    def set_match_count(self, total: int, current: int = 0) -> None:
-        """Update the match counter display."""
-        self._match_count = total
-        label = f"{current}/{total}" if total > 0 else ""
-        self.query_one("#search-count", Static).update(label)
-
-    def clear(self) -> None:
-        """Reset search bar."""
-        inp = self.query_one("#search-input", Input)
-        inp.clear()
-        self._query = ""
-        self._match_count = 0
-        self.query_one("#search-count", Static).update("")
-
-    def history_previous(self) -> None:
-        """Cycle to previous history entry."""
-        if not self._history:
-            return
-        if self._history_idx == -1:
-            self._history_idx = len(self._history) - 1
-        elif self._history_idx > 0:
-            self._history_idx -= 1
-        text = self._history[self._history_idx]
-        inp = self.query_one("#search-input", Input)
-        inp.value = text
-        self._query = text
-        self.post_message(self.SearchChanged(self._query, self._mode))
-
-    def history_next(self) -> None:
-        if not self._history or self._history_idx == -1:
-            return
-        self._history_idx += 1
-        if self._history_idx >= len(self._history):
-            self._history_idx = -1
-            inp = self.query_one("#search-input", Input)
-            inp.value = ""
-            self._query = ""
-        else:
-            text = self._history[self._history_idx]
-            inp = self.query_one("#search-input", Input)
-            inp.value = text
-            self._query = text
-        self.post_message(self.SearchChanged(self._query, self._mode))
-
-    @property
-    def query(self) -> str:
-        return self._query
-
-    @property
-    def mode(self) -> str:
-        return self._mode
diff --git a/src/symtest/tui/widgets/steps_editor.py b/src/symtest/tui/widgets/steps_editor.py
deleted file mode 100644
index 5dfc812..0000000
--- a/src/symtest/tui/widgets/steps_editor.py
+++ /dev/null
@@ -1,243 +0,0 @@
-"""Widget for editing a test case's ``steps`` list (sequence mode).
-
-Uses an internal ``_steps`` list so that ``load()`` / ``to_steps()`` work
-even when the widget is not mounted.
-"""
-
-from __future__ import annotations
-
-import copy
-import json
-from typing import Any, List
-
-from textual.widgets import Input, TextArea, Static, Button
-from textual.containers import Vertical, Horizontal
-from textual.message import Message
-from textual.app import ComposeResult
-
-from ...core.test_case import TestCaseStep
-
-
-class StepsEditor(Vertical):
-    """Editor for the ``steps`` sequence of a test case."""
-
-    DEFAULT_CSS = """
-    StepsEditor {
-        height: auto;
-        border: solid $primary;
-        padding: 1;
-    }
-    StepsEditor #steps-list {
-        height: auto;
-        min-height: 3;
-    }
-    StepsEditor .step-row {
-        height: auto;
-        padding: 1 0;
-        border-bottom: solid $panel;
-    }
-    StepsEditor .step-row Static {
-        width: 1fr;
-    }
-    StepsEditor .step-header {
-        color: $accent;
-        padding-bottom: 1;
-    }
-    StepsEditor #step-editor {
-        height: auto;
-        margin-top: 1;
-        border: solid $surface;
-        padding: 1;
-    }
-    StepsEditor #step-confirm {
-        margin-top: 1;
-    }
-    """
-
-    class Changed(Message):
-        """Emitted whenever steps are modified."""
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self._steps: List[TestCaseStep] = []
-        self._editing_idx: int = -1  # -1 = new step
-
-    def compose(self) -> ComposeResult:
-        yield Static("─ Steps ─", classes="label")
-        yield Vertical(id="steps-list")
-        yield Static("", id="step-editor-status")
-        yield Static("Command:", classes="label")
-        yield Input(placeholder="python", id="step-cmd")
-        yield Static("Args (space-separated):", classes="label")
-        yield Input(placeholder="./script.py --flag", id="step-args")
-        yield Static("Expected (JSON):", classes="label")
-        yield TextArea('{"return_code": 0}', id="step-expected")
-        yield Static("Timeout (seconds):", classes="label")
-        yield Input(placeholder="", id="step-timeout")
-        yield Static("Retry count:", classes="label")
-        yield Input(placeholder="0", id="step-retry-count")
-        yield Horizontal(
-            Button("Save Step", id="step-save", variant="primary"),
-            Button("Cancel", id="step-cancel"),
-            id="step-confirm",
-        )
-        yield Horizontal(
-            Button("+ Add Step", id="step-add", variant="success"),
-            id="step-actions",
-        )
-
-    def on_mount(self) -> None:
-        self._refresh_list()
-
-    # -- public API ----------------------------------------------------------
-
-    def load(self, steps: List[TestCaseStep]) -> None:
-        """Populate the editor with *steps*."""
-        self._steps = copy.deepcopy(steps)
-        self._editing_idx = -1
-        if self.is_mounted:
-            self._refresh_list()
-            self._clear_edit_form()
-
-    def to_steps(self) -> List[TestCaseStep]:
-        if self.is_mounted:
-            # Pull any in-progress edit from UI into steps before returning
-            pass  # edits are applied immediately via buttons
-        return copy.deepcopy(self._steps)
-
-    # -- internal -----------------------------------------------------------
-
-    def _refresh_list(self) -> None:
-        container = self.query_one("#steps-list", Vertical)
-        container.remove_children()
-        for i, step in enumerate(self._steps):
-            args_str = " ".join(step.args) if step.args else ""
-            exp_preview = json.dumps(step.expected, ensure_ascii=False)
-            if len(exp_preview) > 40:
-                exp_preview = exp_preview[:37] + "..."
-            timeout_str = f", timeout={step.timeout}s" if step.timeout else ""
-            retry_str = f", retry={step.retry_count}" if step.retry_count else ""
-
-            row = Horizontal(
-                Static(f"[Step {i+1}/{len(self._steps)}]"),
-                Static(f"cmd: {step.command}"),
-                Static(f"args: {args_str[:30]}"),
-                Static(f"exp: {exp_preview}"),
-                Button("Edit", id=f"step-edit-{i}"),
-                Button("Del", id=f"step-del-{i}"),
-                Button("↑", id=f"step-up-{i}"),
-                Button("↓", id=f"step-down-{i}"),
-                classes="step-row",
-            )
-            container.mount(row)
-
-    def _clear_edit_form(self) -> None:
-        self._editing_idx = -1
-        if not self.is_mounted:
-            return
-        self.query_one("#step-cmd", Input).value = ""
-        self.query_one("#step-args", Input).value = ""
-        self.query_one("#step-expected", TextArea).text = '{"return_code": 0}'
-        self.query_one("#step-timeout", Input).value = ""
-        self.query_one("#step-retry-count", Input).value = ""
-        status = self.query_one("#step-editor-status", Static)
-        status.update("")
-
-    def _edit_step(self, idx: int) -> None:
-        self._editing_idx = idx
-        step = self._steps[idx]
-        self.query_one("#step-cmd", Input).value = step.command
-        self.query_one("#step-args", Input).value = " ".join(step.args)
-        self.query_one("#step-expected", TextArea).text = json.dumps(
-            step.expected, ensure_ascii=False
-        )
-        self.query_one("#step-timeout", Input).value = str(step.timeout) if step.timeout else ""
-        self.query_one("#step-retry-count", Input).value = str(step.retry_count) if step.retry_count else ""
-        status = self.query_one("#step-editor-status", Static)
-        status.update(f"Editing Step {idx+1}")
-
-    def _save_current_step(self) -> None:
-        cmd = self.query_one("#step-cmd", Input).value.strip()
-        if not cmd:
-            self.notify("Command cannot be empty", severity="error")
-            return
-
-        args_text = self.query_one("#step-args", Input).value.strip()
-        args = args_text.split() if args_text else []
-
-        try:
-            expected = json.loads(self.query_one("#step-expected", TextArea).text)
-        except json.JSONDecodeError:
-            self.notify("Expected must be valid JSON", severity="error")
-            return
-
-        timeout_text = self.query_one("#step-timeout", Input).value.strip()
-        timeout = float(timeout_text) if timeout_text else None
-
-        retry_text = self.query_one("#step-retry-count", Input).value.strip()
-        retry_count = int(retry_text) if retry_text else 0
-
-        new_step = TestCaseStep(
-            command=cmd, args=args, expected=expected, timeout=timeout, retry_count=retry_count,
-        )
-
-        if self._editing_idx >= 0:
-            self._steps[self._editing_idx] = new_step
-        else:
-            self._steps.append(new_step)
-
-        self._clear_edit_form()
-        self._refresh_list()
-        self.post_message(self.Changed())
-
-    def _delete_step(self, idx: int) -> None:
-        del self._steps[idx]
-        if self._editing_idx == idx:
-            self._clear_edit_form()
-        elif self._editing_idx > idx:
-            self._editing_idx -= 1
-        self._refresh_list()
-        self.post_message(self.Changed())
-
-    def _move_step(self, idx: int, direction: int) -> None:
-        new_idx = idx + direction
-        if 0 <= new_idx < len(self._steps):
-            self._steps[idx], self._steps[new_idx] = self._steps[new_idx], self._steps[idx]
-            if self._editing_idx == idx:
-                self._editing_idx = new_idx
-            elif self._editing_idx == new_idx:
-                self._editing_idx = idx
-            self._refresh_list()
-            self.post_message(self.Changed())
-
-    # -- button handlers -----------------------------------------------------
-
-    def on_button_pressed(self, event: Button.Pressed) -> None:
-        bid = str(event.button.id)
-
-        if bid == "step-add":
-            self._clear_edit_form()
-
-        elif bid == "step-save":
-            self._save_current_step()
-
-        elif bid == "step-cancel":
-            self._clear_edit_form()
-
-        elif bid and bid.startswith("step-edit-"):
-            idx = int(bid.split("-")[-1])
-            if 0 <= idx < len(self._steps):
-                self._edit_step(idx)
-
-        elif bid and bid.startswith("step-del-"):
-            idx = int(bid.split("-")[-1])
-            if 0 <= idx < len(self._steps):
-                self._delete_step(idx)
-
-        elif bid and bid.startswith("step-up-"):
-            idx = int(bid.split("-")[-1])
-            self._move_step(idx, -1)
-
-        elif bid and bid.startswith("step-down-"):
-            idx = int(bid.split("-")[-1])
-            self._move_step(idx, 1)
diff --git a/src/symtest/utils/report_generator.py b/src/symtest/utils/report_generator.py
index 995df1c..c555909 100644
--- a/src/symtest/utils/report_generator.py
+++ b/src/symtest/utils/report_generator.py
@@ -15,6 +15,73 @@ def _format_flaky_label(detail: dict) -> str:
     return ""
 
 
+def _render_message_lines(prefix: str, message: str, cont_indent: str) -> str:
+    """Render a possibly multi-line message: first line gets ``prefix``,
+    continuation lines are indented with ``cont_indent`` so IDE
+    indentation-based folding stays intact."""
+    lines = str(message).splitlines() or [""]
+    out = f"{prefix}{lines[0]}\n"
+    for line in lines[1:]:
+        out += f"{cont_indent}{line}\n"
+    return out
+
+
+def _render_stats(es: dict, indent: str) -> str:
+    """Render an error_stats dict as flat ``key: value`` lines.
+
+    Used for autonomous/file-lane comparators.  Channel results are NEVER
+    inferred from dictionary shape — they are rendered exclusively from the
+    structured ``channels`` list (see :func:`_render_channels`).
+    """
+    out = ""
+    for key, val in es.items():
+        if isinstance(val, float):
+            out += f"{indent}{key}: {val:.6g}\n"
+        else:
+            out += f"{indent}{key}: {val}\n"
+    return out
+
+
+def _render_channels(channels: list, indent: str) -> str:
+    """Render a channels sub-result list (from serialized ChannelResult dicts).
+
+    ``channels`` is the ONLY authoritative structured channel source; each
+    entry renders its framework-owned canonical ``stats`` and its
+    plugin-owned ``extra_stats`` in separate blocks.
+    """
+    out = ""
+    for ch in channels:
+        verdict = "PASS" if ch.get("passed") else "FAIL"
+        out += (
+            f"{indent}channel '{ch.get('name')}': {verdict} "
+            f"(rtol={ch.get('rtol', 0):g}, atol={ch.get('atol', 0):g})\n"
+        )
+        stats = ch.get("stats")
+        if stats:
+            for key, val in stats.items():
+                if isinstance(val, float):
+                    out += f"{indent}  {key}: {val:.6g}\n"
+                else:
+                    out += f"{indent}  {key}: {val}\n"
+        extra = ch.get("extra_stats")
+        if extra:
+            out += f"{indent}  extra_stats:\n"
+            for key, val in extra.items():
+                if isinstance(val, float):
+                    out += f"{indent}    {key}: {val:.6g}\n"
+                else:
+                    out += f"{indent}    {key}: {val}\n"
+        diffs = ch.get("differences", [])
+        for d in diffs[:3]:
+            out += (
+                f"{indent}  {d.get('position')}: "
+                f"expected={d.get('expected')}, actual={d.get('actual')}\n"
+            )
+        if len(diffs) > 3:
+            out += f"{indent}  ... and {len(diffs) - 3} more\n"
+    return out
+
+
 class ReportGenerator:
     def __init__(self, results: dict, file_path: str):
         self.results = results
@@ -62,19 +129,22 @@ def generate_report(self) -> str:
             if detail.get('description'):
                 report += f"   Description: {detail['description']}\n"
             if detail.get('message') and status != 'passed':
-                report += f"   -> {detail['message']}\n"
+                report += _render_message_lines("   -> ", detail['message'], "      ")
 
             # ── Error analysis for PASSED cases (--error-analysis-all) ──
+            # Channel results are rendered only from the structured
+            # ``channels`` list; error_stats is the flat fallback.
             if status == 'passed' and self.results.get('error_analysis_all'):
                 for ar in detail.get('assertion_results', []):
-                    es = ar.get('error_stats')
-                    if es:
-                        report += "   error_stats:\n"
-                        for key, val in es.items():
-                            if isinstance(val, float):
-                                report += f"     {key}: {val:.6g}\n"
-                            else:
-                                report += f"     {key}: {val}\n"
+                    channels = ar.get('channels')
+                    if channels:
+                        report += "   channels:\n"
+                        report += _render_channels(channels, indent="     ")
+                    else:
+                        es = ar.get('error_stats')
+                        if es:
+                            report += "   error_stats:\n"
+                            report += _render_stats(es, indent="     ")
 
         # 添加失败案例的详细输出信息（含 xfailed、xpassed、timeout 等非通过状态）
         failed_tests = [detail for detail in self.results['details'] if detail['status'] != 'passed']
@@ -130,15 +200,19 @@ def generate_report(self) -> str:
                                 report += f"    max_rel_error: {ds['max_rel_error']:.6g} at {ds.get('max_rel_error_at')}\n"
                             if ds.get('max_abs_error') is not None:
                                 report += f"    max_abs_error: {ds['max_abs_error']:.6g} at {ds.get('max_abs_error_at')}\n"
-                        # ── Error analysis (full-dataset streaming stats) ──
-                        es = cf.get('error_stats')
-                        if es:
-                            report += "    error_stats:\n"
-                            for key, val in es.items():
-                                if isinstance(val, float):
-                                    report += f"      {key}: {val:.6g}\n"
-                                else:
-                                    report += f"      {key}: {val}\n"
+                        # ── Channel sub-results (data-lane comparators) —
+                        #    authoritative structured source; when present,
+                        #    flat error_stats is not rendered separately.
+                        channels = cf.get('channels')
+                        if channels:
+                            report += "    channels:\n"
+                            report += _render_channels(channels, indent="      ")
+                        else:
+                            # Error analysis (full-dataset streaming stats)
+                            es = cf.get('error_stats')
+                            if es:
+                                report += "    error_stats:\n"
+                                report += _render_stats(es, indent="      ")
                         diffs = cf.get('differences', [])
                         if diffs:
                             report += "    sample differences:\n"
@@ -169,7 +243,7 @@ def generate_report(self) -> str:
                         status_icon = "✓" if sr.get('status') == 'passed' else "✗"
                         report += f"  {status_icon} Step {sr.get('step')}: {sr.get('status')} ({sr.get('duration', 0):.2f}s)\n"
                         if sr.get('message'):
-                            report += f"     -> {sr['message']}\n"
+                            report += _render_message_lines("     -> ", sr['message'], "        ")
 
                 # 添加 baseline_updated 信息
                 baseline_updated = failed_test.get('baseline_updated', [])
diff --git a/tests/README.md b/tests/README.md
index 3b3bb5d..5973a92 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,24 +1,14 @@
 ## Tests Structure
 
-- `unit/`: core and runner unit tests (`core/`, `runners/`, `tui/`).
+- `unit/`: core and runner unit tests (`core/`, `runners/`, `commands/`).
 - `integration/`: end-to-end style checks (file_compare, parallel, path_handling, etc).
 - `demos/`: manual/interactive scripts, not run in CI by default.
 
-### TUI Tests (`unit/tui/`)
-
-| File | Coverage |
-|------|----------|
-| `test_search_functions.py` | Search helpers: substring, regex, fuzzy match/scoring |
-| `test_case_controller.py` | `CaseController`: init, load/save, CRUD, search, tags, dirty flag, `_parse_from_dict` |
-| `test_widgets_data.py` | `StepsEditor`/`ExpectedEditor` data layer: load/to_steps/to_dict, deep copy, roundtrip |
-| `test_app.py` | `run_tui` error handling, `CaseManagerApp` construction, CLI arg parsing |
-
 ## Run Commands
 
 - Run all configured scopes: `python -m tests.run_all --scope all`
 - Unit only: `python -m tests.run_all --scope unit`
 - Integration only: `python -m tests.run_all --scope integration`
-- TUI tests only: `python -m pytest tests/unit/tui/ -v`
 - Filter with pytest args: `python -m tests.run_all --scope integration --extra "-k h5"`
 
 `demos/` scripts are standalone (e.g., `python tests/demos/h5_filter_demo.py`).
diff --git a/tests/integration/file_compare/test_csv_compare.py b/tests/integration/file_compare/test_csv_compare.py
index d2c3f73..8073418 100644
--- a/tests/integration/file_compare/test_csv_compare.py
+++ b/tests/integration/file_compare/test_csv_compare.py
@@ -2,12 +2,12 @@
 
 
 def compare_csv(file1, file2, **kwargs):
-    comparator = ComparatorFactory.create_comparator("csv", **kwargs)
     compare_kwargs = {
-        key: kwargs[key]
+        key: kwargs.pop(key)
         for key in ("start_line", "end_line", "start_column", "end_column")
         if key in kwargs
     }
+    comparator = ComparatorFactory.create_comparator("csv", **kwargs)
     return comparator.compare_files(file1, file2, **compare_kwargs)
 
 
diff --git a/tests/integration/file_compare/test_text_compare.py b/tests/integration/file_compare/test_text_compare.py
index aefe137..3e467fd 100644
--- a/tests/integration/file_compare/test_text_compare.py
+++ b/tests/integration/file_compare/test_text_compare.py
@@ -2,8 +2,15 @@
 
 
 def compare_text(file1, file2, **kwargs):
+    # Window parameters are invocation-level: routed to compare_files, not
+    # the (strict) comparator constructor.
+    compare_kwargs = {
+        key: kwargs.pop(key)
+        for key in ("start_line", "end_line", "start_column", "end_column")
+        if key in kwargs
+    }
     comparator = ComparatorFactory.create_comparator("text", **kwargs)
-    return comparator.compare_files(file1, file2, **kwargs)
+    return comparator.compare_files(file1, file2, **compare_kwargs)
 
 
 def test_text_identical(tmp_path):
diff --git a/tests/integration/parallel/test_parallel_runner.py b/tests/integration/parallel/test_parallel_runner.py
index cf97241..3cded15 100644
--- a/tests/integration/parallel/test_parallel_runner.py
+++ b/tests/integration/parallel/test_parallel_runner.py
@@ -84,6 +84,69 @@ def test_thread_vs_process_mode(self):
         self.assertTrue(process_success)
         self.assertEqual(thread_runner.results["passed"], process_runner.results["passed"])
 
+    def test_process_mode_discovers_workspace_plugins(self):
+        """Process workers discover workspace plugins via the pool initializer
+        (explicit initargs — the framework never writes os.environ)."""
+        comparators_dir = os.path.join(self.temp_dir, "comparators")
+        os.makedirs(comparators_dir)
+        plugin_code = (
+            "from symtest.file_comparator.base_comparator import ComparatorBase\n"
+            "from symtest.file_comparator.result import ComparisonResult\n"
+            "\n"
+            "class AlwaysPassComparator(ComparatorBase):\n"
+            "    def compare(self, ctx):\n"
+            "        result = ComparisonResult(\n"
+            "            file1=str(ctx.baseline or ''),\n"
+            "            file2=str(ctx.actual or ''),\n"
+            "        )\n"
+            "        result.identical = True\n"
+            "        return result\n"
+        )
+        with open(os.path.join(comparators_dir, "always_pass_comparator.py"),
+                  "w", encoding="utf-8") as f:
+            f.write(plugin_code)
+
+        # Contents deliberately differ: the plugin always passes, so the case
+        # only succeeds if the WORKER actually registered the plugin type.
+        file_a = os.path.join(self.temp_dir, "a.txt")
+        file_b = os.path.join(self.temp_dir, "b.txt")
+        for path, content in ((file_a, "AAA"), (file_b, "BBB")):
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+        config_file = os.path.join(self.temp_dir, "plugin_config.json")
+        test_config = {
+            "test_cases": [
+                {
+                    "name": "plugin_case",
+                    "execution": {
+                        "command": f'"{sys.executable}" -c "print(\'ok\')"',
+                        "args": [],
+                    },
+                    "expected": {
+                        "return_code": 0,
+                        "compare_files": [
+                            {
+                                "actual": "b.txt",
+                                "baseline": "a.txt",
+                                "type": "alwayspass",
+                            }
+                        ],
+                    },
+                }
+            ]
+        }
+        with open(config_file, "w", encoding="utf-8") as f:
+            json.dump(test_config, f, ensure_ascii=False, indent=2)
+
+        runner = ParallelJSONRunner(
+            config_file, self.temp_dir, max_workers=2, execution_mode="process"
+        )
+        success = runner.run_tests()
+
+        self.assertTrue(success)
+        self.assertEqual(runner.results["passed"], 1)
+
     def test_max_workers_configuration(self):
         for max_workers in [1, 2, 4]:
             with self.subTest(max_workers=max_workers):
diff --git a/tests/integration/test_sequence.py b/tests/integration/test_sequence.py
index c3ffd82..5f103af 100644
--- a/tests/integration/test_sequence.py
+++ b/tests/integration/test_sequence.py
@@ -8,7 +8,7 @@
 
 from symtest.runners.json_runner import JSONRunner
 from symtest.runners.yaml_runner import YAMLRunner
-from symtest.core.test_case import TestCase, TestCaseStep
+from symtest.core.test_case import TestCase, TestStep
 
 
 class TestSequenceLoadJSON(unittest.TestCase):
@@ -279,18 +279,18 @@ def tearDown(self):
         self.temp_dir.cleanup()
 
 
-class TestTestCaseStepDataclass(unittest.TestCase):
-    """Test TestCaseStep and TestCase with steps field."""
+class TestTestStepDataclass(unittest.TestCase):
+    """Test TestStep and TestCase with steps field."""
 
     def test_test_case_step_creation(self):
-        step = TestCaseStep(command="echo", args=["hello"], expected={"return_code": 0})
+        step = TestStep.from_flat(command="echo", args=["hello"], expected={"return_code": 0})
         self.assertEqual(step.command, "echo")
         self.assertEqual(step.timeout, None)
 
     def test_test_case_with_steps(self):
         steps = [
-            TestCaseStep(command="echo", args=["a"], expected={"return_code": 0}),
-            TestCaseStep(command="echo", args=["b"], expected={"return_code": 0}, timeout=5),
+            TestStep.from_flat(command="echo", args=["a"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["b"], expected={"return_code": 0}, timeout=5),
         ]
         case = TestCase(name="seq", steps=steps)
         self.assertEqual(case.command, "")  # default for sequence mode
@@ -299,8 +299,8 @@ def test_test_case_with_steps(self):
 
     def test_test_case_to_dict_with_steps(self):
         steps = [
-            TestCaseStep(command="echo", args=["a"], expected={"return_code": 0}),
-            TestCaseStep(command="echo", args=["b"], expected={"return_code": 0}, retry_count=2),
+            TestStep.from_flat(command="echo", args=["a"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["b"], expected={"return_code": 0}, retry_count=2),
         ]
         case = TestCase(name="seq", steps=steps, retry_count=3)
         d = case.to_dict()
diff --git a/tests/unit/commands/test_find.py b/tests/unit/commands/test_find.py
new file mode 100644
index 0000000..5f1a7b0
--- /dev/null
+++ b/tests/unit/commands/test_find.py
@@ -0,0 +1,344 @@
+"""Tests for the ``symtest find`` command (search helpers + CLI handler).
+
+Search helpers were moved verbatim from the retired TUI CaseController; the
+test cases below are the ported originals plus new CLI-level coverage
+(exit codes, tag filter, JSON output).
+"""
+
+import json
+import re
+
+import pytest
+
+from symtest.commands.find import (
+    _substring_match,
+    _regex_match,
+    _fuzzy_score,
+    _fuzzy_match,
+    search_cases,
+    run_find,
+)
+from symtest.core.test_case import TestCase
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _tc(**kwargs) -> TestCase:
+    """Shorthand to create a TestCase with defaults."""
+    defaults = {
+        "name": "test",
+        "command": "",
+        "args": [],
+        "expected": {},
+        "tags": [],
+        "description": "",
+    }
+    defaults.update(kwargs)
+    return TestCase(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# _substring_match
+# ---------------------------------------------------------------------------
+
+
+class TestSubstringMatch:
+    def test_match_in_name(self):
+        assert _substring_match("hello", _tc(name="hello_world"))
+
+    def test_match_case_insensitive(self):
+        assert _substring_match("HELLO", _tc(name="hello_world"))
+
+    def test_match_in_command(self):
+        assert _substring_match("python", _tc(command="python3"))
+
+    def test_match_in_args(self):
+        assert _substring_match("script", _tc(args=["run", "script.py"]))
+
+    def test_match_in_tags(self):
+        assert _substring_match("smoke", _tc(tags=["smoke", "regression"]))
+
+    def test_match_in_description(self):
+        assert _substring_match("important", _tc(description="An important test"))
+
+    def test_no_match(self):
+        assert not _substring_match("xyz123", _tc(name="hello"))
+
+    def test_empty_query_matches_all(self):
+        """Empty string is contained in every string."""
+        assert _substring_match("", _tc(name="hello"))
+
+    def test_query_with_dot_literal(self):
+        """Dot is a literal char, not a regex wildcard in substring mode."""
+        assert _substring_match("test_case", _tc(name="my_test_case_extra"))
+
+
+# ---------------------------------------------------------------------------
+# _regex_match
+# ---------------------------------------------------------------------------
+
+
+class TestRegexMatch:
+    """``_regex_match`` consumes a compiled pattern (compiled once per
+    search in ``search_cases``)."""
+
+    @staticmethod
+    def _pat(query):
+        return re.compile(query, re.IGNORECASE)
+
+    def test_simple_regex(self):
+        assert _regex_match(self._pat(r"test\d"), _tc(name="test1"))
+
+    def test_regex_case_insensitive(self):
+        assert _regex_match(self._pat(r"HELLO"), _tc(name="hello_world"))
+
+    def test_regex_in_command(self):
+        assert _regex_match(self._pat(r"python\d"), _tc(command="python3"))
+
+    def test_regex_in_tags(self):
+        assert _regex_match(self._pat(r"smoke|reg"), _tc(tags=["smoke_test"]))
+
+    def test_regex_no_match(self):
+        assert not _regex_match(self._pat(r"test\d"), _tc(name="hello"))
+
+    def test_full_match_pattern(self):
+        """^ and $ anchors should work."""
+        assert _regex_match(self._pat(r"^hello$"), _tc(name="hello"))
+        assert not _regex_match(self._pat(r"^hello$"), _tc(name="hello_world"))
+
+    def test_multiline_description(self):
+        assert _regex_match(self._pat(r"line2"), _tc(description="line1\nline2\nline3"))
+
+
+# ---------------------------------------------------------------------------
+# _fuzzy_score
+# ---------------------------------------------------------------------------
+
+
+class TestFuzzyScore:
+    def test_exact_match_scores_high(self):
+        score = _fuzzy_score("hello", _tc(name="hello"))
+        assert score > 0.5
+
+    def test_no_match_scores_zero(self):
+        score = _fuzzy_score("xyz", _tc(name="abcdef"))
+        assert score == 0.0
+
+    def test_partial_overlap(self):
+        score = _fuzzy_score("hel", _tc(name="hello"))
+        assert score > 0.0
+
+    def test_name_weights_more_than_args(self):
+        score_name = _fuzzy_score("script", _tc(name="script_runner"))
+        score_args = _fuzzy_score("script", _tc(name="other", args=["script.py"]))
+        assert score_name > score_args
+
+    def test_two_char_partial_overlap(self):
+        """Two-char prefix matches first bigram."""
+        score = _fuzzy_score("he", _tc(name="hello"))
+        assert score > 0.0
+
+    def test_empty_query_scores_zero(self):
+        score = _fuzzy_score("", _tc(name="hello"))
+        assert score == 0.0
+
+    def test_score_is_non_negative(self):
+        score = _fuzzy_score("zxy", _tc(name="abc"))
+        assert score >= 0.0
+
+
+# ---------------------------------------------------------------------------
+# _fuzzy_match
+# ---------------------------------------------------------------------------
+
+
+class TestFuzzyMatch:
+    def test_returns_matching_indices(self):
+        cases = [
+            _tc(name="hello_world"),
+            _tc(name="goodbye"),
+            _tc(name="hello_again"),
+        ]
+        indices = _fuzzy_match("hello", cases)
+        assert 0 in indices
+        assert 2 in indices
+        assert 1 not in indices
+
+    def test_returns_sorted_by_score(self):
+        cases = [
+            _tc(name="abc"),
+            _tc(name="document", description="test_and_more"),
+            _tc(name="test_and_more"),
+        ]
+        indices = _fuzzy_match("test", cases)
+        # Case[2] matches in name (weight 2.0) > Case[1] matches only in desc (weight 1.0)
+        assert indices[0] == 2
+
+    def test_threshold_filters_low_scores(self):
+        cases = [
+            _tc(name="hello"),
+            _tc(name="h_xx_e_xx_l_xx_l_xx_o"),  # Low bigram overlap
+        ]
+        indices = _fuzzy_match("hello", cases, threshold=0.5)
+        assert 0 in indices
+        assert 1 not in indices
+
+    def test_low_threshold_includes_more(self):
+        cases = [_tc(name="hello"), _tc(name="zzz")]
+        indices = _fuzzy_match("hello", cases, threshold=0.0)
+        assert len(indices) >= 1
+
+    def test_empty_cases(self):
+        assert _fuzzy_match("hello", []) == []
+
+    def test_all_below_threshold(self):
+        cases = [_tc(name="a"), _tc(name="b")]
+        indices = _fuzzy_match("xyz", cases, threshold=0.5)
+        assert indices == []
+
+
+# ---------------------------------------------------------------------------
+# search_cases (tag filter + mode dispatch)
+# ---------------------------------------------------------------------------
+
+
+class TestSearchCases:
+    def test_substring_mode_default(self):
+        cases = [_tc(name="login_test"), _tc(name="logout_test")]
+        assert search_cases(cases, "login") == [0]
+
+    def test_invalid_regex_matches_nothing(self):
+        """Malformed regex should not raise, just match nothing."""
+        cases = [_tc(name="hello")]
+        assert search_cases(cases, "[unclosed", mode="regex") == []
+
+    def test_empty_query_lists_all_in_every_mode(self):
+        """Empty pattern short-circuits: same semantics for all modes."""
+        cases = [_tc(name="a"), _tc(name="b")]
+        for mode in ("substring", "fuzzy", "regex"):
+            assert search_cases(cases, "", mode=mode) == [0, 1]
+
+    def test_regex_mode(self):
+        cases = [_tc(name="case1"), _tc(name="case2")]
+        assert search_cases(cases, r"case\d", mode="regex") == [0, 1]
+
+    def test_fuzzy_mode_ranks_by_score(self):
+        cases = [_tc(name="hello"), _tc(name="hexlo")]
+        indices = search_cases(cases, "hello", mode="fuzzy")
+        assert indices[0] == 0
+
+    def test_tag_filter_narrows_results(self):
+        cases = [_tc(name="a", tags=["smoke"]), _tc(name="b", tags=["regression"])]
+        assert search_cases(cases, "", tags=["smoke"]) == [0]
+
+    def test_tag_filter_or_relationship(self):
+        cases = [
+            _tc(name="a", tags=["smoke"]),
+            _tc(name="b", tags=["regression"]),
+            _tc(name="c", tags=["other"]),
+        ]
+        assert search_cases(cases, "", tags=["smoke", "regression"]) == [0, 1]
+
+    def test_tag_filter_applies_after_query(self):
+        cases = [
+            _tc(name="login_a", tags=["smoke"]),
+            _tc(name="login_b", tags=["other"]),
+        ]
+        assert search_cases(cases, "login", tags=["smoke"]) == [0]
+
+
+# ---------------------------------------------------------------------------
+# CLI handler (run_find)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def config_file(tmp_path):
+    cfg = {
+        "test_cases": [
+            {
+                "name": "login_ok",
+                "execution": {"command": "echo", "args": ["login"], "timeout": 30},
+                "expected": {"return_code": 0},
+                "tags": ["smoke"],
+            },
+            {
+                "name": "logout_ok",
+                "execution": {"command": "echo", "args": ["logout"]},
+                "expected": {"return_code": 0},
+                "tags": ["regression"],
+            },
+        ],
+    }
+    path = tmp_path / "cases.json"
+    path.write_text(json.dumps(cfg), encoding="utf-8")
+    return path
+
+
+def _args(config_file, pattern, **extra):
+    import argparse
+
+    return argparse.Namespace(
+        config_file=str(config_file),
+        pattern=pattern,
+        mode=extra.get("mode", "substring"),
+        tag=extra.get("tag"),
+        workspace=extra.get("workspace"),
+        output_format=extra.get("output_format", "text"),
+    )
+
+
+class TestRunFind:
+    def test_match_returns_zero(self, config_file, capsys):
+        assert run_find(_args(config_file, "login")) == 0
+        out = capsys.readouterr().out
+        assert "login_ok" in out
+        assert "logout_ok" not in out
+
+    def test_no_match_returns_one(self, config_file, capsys):
+        assert run_find(_args(config_file, "zzz_nonexistent")) == 1
+        out = capsys.readouterr().out
+        assert "No test cases match" in out
+
+    def test_empty_pattern_lists_all(self, config_file, capsys):
+        assert run_find(_args(config_file, "")) == 0
+        out = capsys.readouterr().out
+        assert "login_ok" in out
+        assert "logout_ok" in out
+
+    def test_missing_config_returns_two(self, tmp_path, capsys):
+        assert run_find(_args(tmp_path / "nope.json", "login")) == 2
+
+    def test_tag_filter(self, config_file, capsys):
+        assert run_find(_args(config_file, "", tag=["smoke"])) == 0
+        out = capsys.readouterr().out
+        assert "login_ok" in out
+        assert "logout_ok" not in out
+
+    def test_json_output(self, config_file, capsys):
+        assert run_find(_args(config_file, "login", output_format="json")) == 0
+        rows = json.loads(capsys.readouterr().out)
+        assert len(rows) == 1
+        assert rows[0]["name"] == "login_ok"
+        assert rows[0]["command"] == "echo"
+        assert rows[0]["tags"] == ["smoke"]
+        assert rows[0]["timeout"] == 30
+        assert rows[0]["mode"] == "single"
+
+    def test_import_expansion(self, tmp_path, capsys):
+        """find auto-expands import references before searching."""
+        sub = tmp_path / "sub.json"
+        sub.write_text(json.dumps({"test_cases": [
+            {"name": "deep_case",
+             "execution": {"command": "echo", "args": ["hi"]},
+             "expected": {"return_code": 0}},
+        ]}), encoding="utf-8")
+        main = tmp_path / "main.json"
+        main.write_text(json.dumps({"test_cases": [{"import": "sub.json"}]}),
+                        encoding="utf-8")
+
+        assert run_find(_args(main, "deep_case")) == 0
+        assert "deep_case" in capsys.readouterr().out
diff --git a/tests/unit/core/test_architecture_guard.py b/tests/unit/core/test_architecture_guard.py
index 54e4e16..7c5e4c7 100644
--- a/tests/unit/core/test_architecture_guard.py
+++ b/tests/unit/core/test_architecture_guard.py
@@ -5,9 +5,8 @@
   expected 的存在 —— Phase 2 唯一验收标准）；
 - 原则 3：validation 只允许 import execution 的 result 类型（读取执行事实），
   不得 import 编排层；
-- 原则 6：core 不得 import cli / tui / commands / runners（表现层）。
-  注：``symtest.reporting.diagnosis`` 是唯一例外 —— 它是 result consumer
-  工具，被 orchestration 调用以填充 wire format 的 next_action_hint 字段。
+- 原则 6：core 不得 import cli / commands / runners / reporting
+  （表现层与 result consumer）。
 """
 import re
 from pathlib import Path
@@ -78,8 +77,9 @@ class TestCoreDoesNotImportPresentation:
     """原则 6：核心模型不依赖表现层。"""
 
     def test_core_has_no_presentation_imports(self):
-        forbidden_abs = ("symtest.cli", "symtest.tui", "symtest.commands", "symtest.runners")
-        forbidden_rel = ("cli", "tui", "commands", "runners")
+        forbidden_abs = ("symtest.cli", "symtest.commands",
+                         "symtest.runners", "symtest.reporting")
+        forbidden_rel = ("cli", "commands", "runners", "reporting")
         offenders = []
         for f in _py_files(SRC / "core"):
             for mod in _imports(f):
@@ -101,6 +101,6 @@ def test_reporting_import_graph_is_leaf(self):
             for mod in _imports(f):
                 norm = mod.lstrip(".")
                 if norm.startswith(("core", "execution", "validation",
-                                    "orchestration", "runners", "tui", "cli")):
+                                    "orchestration", "runners", "cli")):
                     offenders.append(f"{f.relative_to(SRC)}: {mod}")
         assert not offenders, f"reporting 依赖越界: {offenders}"
diff --git a/tests/unit/core/test_assertions.py b/tests/unit/core/test_assertions.py
index d314b55..86b5cbe 100644
--- a/tests/unit/core/test_assertions.py
+++ b/tests/unit/core/test_assertions.py
@@ -5,7 +5,9 @@
 
 import pytest
 
-from symtest.core.validation.assertions import Assertions, _detect_file_type
+from symtest.core.validation.assertions import (
+    Assertions, ValidationError, _detect_file_type,
+)
 from symtest.core.validation.assertions import Assertions as AS  # alias for dispatch tests
 from symtest.core.validation.validator import validate_result, _dispatch_file_compare
 from symtest.core.execution.result import ExecutionResult
@@ -134,14 +136,26 @@ def test_compare_files_does_not_override_absolute_paths():
 # ---------------------------------------------------------------------------
 
 def test_compare_files_passes_kwargs_to_comparator():
-    """rtol/atol are forwarded to the H5 comparator (should not error)."""
+    """rtol/atol are forwarded to comparators that declare them (csv)."""
     with tempfile.TemporaryDirectory() as d:
-        a, b = _write_two(d, "a.txt", "b.txt", "same\n")
-        # rtol / atol are H5-specific; TextComparator ignores unknown kwargs
-        result = Assertions.compare_files(a, b, file_type="text", rtol=1e-5, atol=1e-8)
+        a, b = _write_two(d, "a.csv", "b.csv", "same\n")
+        # rtol / atol are declared by the csv comparator
+        result = Assertions.compare_files(a, b, file_type="csv", rtol=1e-5, atol=1e-8)
         assert result["identical"]
 
 
+def test_compare_files_unknown_kwargs_fail_loudly():
+    """Strict configuration: a misspelled/unknown parameter must fail loudly
+    identifying the comparator type, never silently fall back to defaults."""
+    with tempfile.TemporaryDirectory() as d:
+        a, b = _write_two(d, "a.txt", "b.txt", "same\n")
+        with pytest.raises(ValidationError) as exc_info:
+            Assertions.compare_files(a, b, file_type="text", rtol=1e-5)
+        message = str(exc_info.value)
+        assert "TextComparator" in message
+        assert "rtol" in message
+
+
 # ---------------------------------------------------------------------------
 # validate_result – compare_files branch
 # ---------------------------------------------------------------------------
@@ -172,6 +186,7 @@ def test_validate_result_compare_files_passes():
                 "assertion": "compare_files",
                 "passed": True,
                 "error_stats": None,
+                "channels": [],
                 "compare_failures": [],
                 "baseline_updated": [],
                 "message": "",
diff --git a/tests/unit/core/test_case_env.py b/tests/unit/core/test_case_env.py
index 778ae3c..98948ac 100644
--- a/tests/unit/core/test_case_env.py
+++ b/tests/unit/core/test_case_env.py
@@ -14,7 +14,7 @@
 from symtest.core.config_loader import parse_test_cases
 from symtest.core.orchestration.sequence import execute_sequence
 from symtest.core.orchestration.single import execute_single_test_case
-from symtest.core.test_case import ExecutionSpec, TestCaseStep
+from symtest.core.test_case import ExecutionSpec, TestStep
 
 
 # ---------------------------------------------------------------------------
@@ -178,12 +178,12 @@ class TestEnvSequence:
 
     def test_env_applied_to_all_steps(self):
         steps = [
-            TestCaseStep(
+            TestStep.from_flat(
                 command=sys.executable,
                 args=["-c", "import os;print('S='+os.environ.get('SCALE','?'))"],
                 expected={"return_code": 0, "output_contains": ["S=1.0"]},
             ),
-            TestCaseStep(
+            TestStep.from_flat(
                 command=sys.executable,
                 args=["-c", "import os;print('S='+os.environ.get('SCALE','?'))"],
                 expected={"return_code": 0, "output_contains": ["S=1.0"]},
@@ -200,43 +200,10 @@ def test_hash_differs_when_env_differs(self):
         from symtest.core.sequence_state import compute_config_hash
 
         steps = [
-            TestCaseStep(command="echo", args=["a"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["a"], expected={"return_code": 0}),
         ]
         h1 = compute_config_hash(steps, None, {"SCALE": "1.0"})
         h2 = compute_config_hash(steps, None, {"SCALE": "2.0"})
         h3 = compute_config_hash(steps, None, None)
         assert h1 != h2
         assert h1 != h3
-
-
-# ---------------------------------------------------------------------------
-# TUI editor helpers
-# ---------------------------------------------------------------------------
-
-class TestTuiEnvHelpers:
-    """Round-trip of the TUI editor's ``KEY=VALUE`` env helpers."""
-
-    def _helpers(self):
-        from symtest.tui.screens.case_editor import CaseEditorScreen
-
-        return CaseEditorScreen._format_env_text, CaseEditorScreen._parse_env_text
-
-    def test_format_and_parse_roundtrip(self):
-        fmt, parse = self._helpers()
-        env = {"UEL_SYSID_SCALE": "1.0", "OMP_NUM_THREADS": "8"}
-        text = fmt(env)
-        assert parse(text) == env
-
-    def test_format_empty_env(self):
-        fmt, parse = self._helpers()
-        assert fmt({}) == ""
-        assert fmt(None) == ""
-
-    def test_parse_skips_blanks_and_comments(self):
-        _, parse = self._helpers()
-        text = "# comment\n\nA=1\n  B = 2  \ninvalid-line\nC=\n"
-        assert parse(text) == {"A": "1", "B": "2", "C": ""}
-
-    def test_parse_ignores_line_without_equals(self):
-        _, parse = self._helpers()
-        assert parse("no_equals_here\nA=1") == {"A": "1"}
diff --git a/tests/unit/core/test_config_loader.py b/tests/unit/core/test_config_loader.py
index 75f0ba0..f49e57a 100644
--- a/tests/unit/core/test_config_loader.py
+++ b/tests/unit/core/test_config_loader.py
@@ -8,7 +8,7 @@
     substitute_placeholders,
     parse_test_cases,
 )
-from symtest.core.test_case import TestCaseStep
+from symtest.core.test_case import TestStep
 from symtest.core.orchestration.sequence import execute_sequence
 from symtest.core.validation.result import ValidationResult
 
@@ -369,9 +369,9 @@ def _failed_result(name="step"):
 
 
 def _steps(*specs):
-    """Build TestCaseStep objects from (command, args, expected) tuples."""
+    """Build TestStep objects from (command, args, expected) tuples."""
     return [
-        TestCaseStep(command=cmd, args=args, expected=expected)
+        TestStep.from_flat(command=cmd, args=args, expected=expected)
         for cmd, args, expected in specs
     ]
 
diff --git a/tests/unit/core/test_config_loader_new_features.py b/tests/unit/core/test_config_loader_new_features.py
index 406161a..aad292a 100644
--- a/tests/unit/core/test_config_loader_new_features.py
+++ b/tests/unit/core/test_config_loader_new_features.py
@@ -4,15 +4,16 @@
 import pytest
 
 from symtest.core.orchestration.sequence import execute_sequence
-from symtest.core.test_case import TestCaseStep
+from symtest.core.test_case import TestStep
 from symtest.core.validation.assertions import ValidationError
 from symtest.core.validation.result import ValidationResult
+from symtest.reporting.diagnosis import attach_next_action_hint
 
 
 def _steps(*specs):
-    """Build TestCaseStep objects from (command, args, expected) tuples."""
+    """Build TestStep objects from (command, args, expected) tuples."""
     return [
-        TestCaseStep(command=cmd, args=args, expected=expected)
+        TestStep.from_flat(command=cmd, args=args, expected=expected)
         for cmd, args, expected in specs
     ]
 
@@ -124,16 +125,13 @@ def test_step_results_truncates_on_failure(self):
 
 
 class TestSequenceStructuredDiagnostics:
-    """Sequence results propagate assertion_results / next_action_hint."""
+    """Sequence results propagate assertion_results; hint 由装配层按 failure_kind 填充."""
 
-    def test_failed_step_propagates_hint_and_assertions(self):
+    def test_failed_step_propagates_assertions_and_failure_kind(self):
         failed = _failed_result("s2")
         failed["assertion_results"] = [
             {"assertion": "return_code", "passed": False, "message": "rc mismatch"}
         ]
-        failed["next_action_hint"] = {
-            "action": "update_expected", "command": None, "reason": "r",
-        }
         steps = _steps(
             ("e1", ["a"], {"return_code": 0}),
             ("e2", ["b"], {"return_code": 0}),
@@ -145,7 +143,10 @@ def test_failed_step_propagates_hint_and_assertions(self):
             result = execute_sequence("case", steps)
             assert result["status"] == "failed"
             assert result["assertion_results"] == failed["assertion_results"]
-            assert result["next_action_hint"] == failed["next_action_hint"]
+            # Orchestration 只产 failure_kind；hint 由 reporting 装配点填充
+            assert result["failure_kind"] == "return_code"
+            assert result["next_action_hint"] is None
+            assert attach_next_action_hint(result)["action"] == "update_expected"
 
     def test_case_level_failure_builds_hint(self):
         steps = _steps(("echo", ["x"], {"return_code": 0}))
@@ -171,7 +172,9 @@ def test_case_level_failure_builds_hint(self):
             assert result["assertion_results"] == [
                 {"assertion": "compare_files", "passed": False}
             ]
-            assert result["next_action_hint"]["action"] == "update_baseline"
+            assert result["failure_kind"] == "file_compare"
+            assert result["next_action_hint"] is None
+            assert attach_next_action_hint(result)["action"] == "update_baseline"
 
     def test_passed_sequence_uses_case_level_assertion_results(self):
         steps = _steps(("echo", ["x"], {"return_code": 0}))
diff --git a/tests/unit/core/test_execution_new_features.py b/tests/unit/core/test_execution_new_features.py
index bd0197e..4bd212b 100644
--- a/tests/unit/core/test_execution_new_features.py
+++ b/tests/unit/core/test_execution_new_features.py
@@ -9,7 +9,10 @@
 from symtest.core.validation.validator import validate_result
 from symtest.core.execution.result import ExecutionResult
 from symtest.core.execution.executor import _trim_output, DEFAULT_OUTPUT_MAX_CHARS
-from symtest.reporting.diagnosis import build_next_action_hint
+from symtest.reporting.diagnosis import (
+    attach_next_action_hint,
+    build_next_action_hint,
+)
 
 
 class TestRetryFeatures:
@@ -218,9 +221,13 @@ def test_assertion_failure_attaches_hint(self, case, expectation):
             )
             result = execute_single_test_case(case, expectation=expectation)
             assert result["status"] == "failed"
-            hint = result["next_action_hint"]
+            # Orchestration only produces failure_kind; the hint is filled by
+            # the reporting attach point (principle 5).
+            assert result["next_action_hint"] is None
+            assert result["failure_kind"] == "return_code"
+            hint = attach_next_action_hint(result)
             assert hint["action"] == "update_expected"
-            assert hint["command"] is None  # filled by the runner layer
+            assert hint["command"] is None  # filled when config_path is given
             assert hint["reason"]
 
     def test_execution_error_attaches_hint(self, case, expectation):
@@ -228,7 +235,8 @@ def test_execution_error_attaches_hint(self, case, expectation):
             result = execute_single_test_case(case, expectation=expectation)
             assert result["status"] == "failed"
             assert result["failure_kind"] == "execution_error"
-            assert result["next_action_hint"]["action"] == "investigate"
+            hint = attach_next_action_hint(result)
+            assert hint["action"] == "investigate"
 
     def test_timeout_attaches_hint(self, case, expectation):
         case.timeout = 1
@@ -242,7 +250,9 @@ def test_timeout_attaches_hint(self, case, expectation):
         with patch("subprocess.Popen", return_value=mock_proc):
             result = execute_single_test_case(case, expectation=expectation)
             assert result["status"] == "timeout"
-            assert result["next_action_hint"]["action"] == "increase_timeout"
+            assert result["failure_kind"] == "timeout"
+            hint = attach_next_action_hint(result)
+            assert hint["action"] == "increase_timeout"
             # PID 99999 is harmless even if killpg() is called;
             # mock_proc.kill is also safe. Assertions above verify
             # the result format remains correct.
@@ -259,8 +269,8 @@ def test_passed_case_has_no_hint(self, case, expectation):
             assert result["next_action_hint"] is None
 
 
-class TestRunnerHintCommandFilling:
-    """Runners fill the concrete symtest command into next_action_hint."""
+class TestAttachHintCommandFilling:
+    """The reporting attach point fills the concrete symtest command."""
 
     def _make_failed_result(self, action):
         return {
@@ -270,38 +280,32 @@ def _make_failed_result(self, action):
         }
 
     def test_update_baseline_command(self):
-        from symtest.runners.json_runner import JSONRunner
-
-        runner = JSONRunner(config_file="cfg.json")
         result = self._make_failed_result("update_baseline")
-        runner._fill_hint_command(result, "case_a")
+        attach_next_action_hint(result, config_path="cfg.json")
         cmd = result["next_action_hint"]["command"]
-        assert cmd == (
-            f'symtest run "{runner.config_path}" --update-baseline -t "case_a"'
-        )
+        assert cmd == 'symtest run "cfg.json" --update-baseline -t "case_a"'
 
     def test_rerun_command_for_other_actions(self):
-        from symtest.runners.json_runner import JSONRunner
-
-        runner = JSONRunner(config_file="cfg.json")
         result = self._make_failed_result("update_expected")
-        runner._fill_hint_command(result, "case_a")
+        attach_next_action_hint(result, config_path="cfg.json")
         cmd = result["next_action_hint"]["command"]
-        assert cmd == f'symtest run "{runner.config_path}" -t "case_a"'
+        assert cmd == 'symtest run "cfg.json" -t "case_a"'
 
     def test_existing_command_not_overwritten(self):
-        from symtest.runners.json_runner import JSONRunner
-
-        runner = JSONRunner(config_file="cfg.json")
         result = self._make_failed_result("update_baseline")
         result["next_action_hint"]["command"] = "custom"
-        runner._fill_hint_command(result, "case_a")
+        attach_next_action_hint(result, config_path="cfg.json")
         assert result["next_action_hint"]["command"] == "custom"
 
     def test_no_hint_is_noop(self):
-        from symtest.runners.json_runner import JSONRunner
-
-        runner = JSONRunner(config_file="cfg.json")
         result = {"name": "ok", "status": "passed", "next_action_hint": None}
-        runner._fill_hint_command(result, "ok")  # should not raise
+        attach_next_action_hint(result, config_path="cfg.json")  # should not raise
         assert result["next_action_hint"] is None
+
+    def test_builds_hint_from_failure_kind(self):
+        """Orchestration only sets failure_kind; the attach point builds the hint."""
+        result = {"name": "case_b", "status": "failed", "failure_kind": "file_compare"}
+        attach_next_action_hint(result, config_path="cfg.json")
+        hint = result["next_action_hint"]
+        assert hint["action"] == "update_baseline"
+        assert hint["command"] == 'symtest run "cfg.json" --update-baseline -t "case_b"'
diff --git a/tests/unit/core/test_model_v2.py b/tests/unit/core/test_model_v2.py
index 053fa8f..a95578f 100644
--- a/tests/unit/core/test_model_v2.py
+++ b/tests/unit/core/test_model_v2.py
@@ -1,8 +1,8 @@
 """Phase 1 unit tests for the TestCase v2 layered model.
 
-Covers: 分层构造（metadata + Execution/Expectation/Scheduling Spec）、
-平铺关键字参数归一、属性直通访问器、单命令归一为单元素 steps、
-Spec 边界（execution 不携带 expected）、to_dict / to_execution_dict 形态。
+Covers: 平铺关键字参数构造（唯一构造路径）、子 Spec 归一、属性直通访问器、
+单命令归一为单元素 steps、Spec 边界（execution 不携带 expected）、
+to_dict / to_execution_dict 形态。
 """
 import copy
 
@@ -13,7 +13,7 @@
     ExpectationSpec,
     SchedulingSpec,
     TestCase,
-    TestCaseStep,
+    TestStep,
 )
 
 
@@ -64,17 +64,16 @@ def test_defaults_are_empty_not_none(self):
         assert tc.scheduling.depends_on == []
         assert tc.scheduling.resources is None
 
-    def test_explicit_specs_take_precedence(self):
-        """显式传入子 Spec 时平铺参数被忽略。"""
+    def test_spec_kwargs_rejected(self):
+        """构造路径唯一：子 Spec 不是构造参数，显式传入直接 TypeError。"""
         spec = ExecutionSpec(command="explicit")
-        tc = TestCase(name="t", command="ignored", execution=spec)
-        assert tc.execution is spec
-        assert tc.command == "explicit"
+        with pytest.raises(TypeError):
+            TestCase(name="t", execution=spec)
 
     def test_sequence_mode(self):
         steps = [
-            TestCaseStep(command="a", args=[], expected={"return_code": 0}),
-            TestCaseStep(command="b", args=[], expected={}),
+            TestStep.from_flat(command="a", args=[], expected={"return_code": 0}),
+            TestStep.from_flat(command="b", args=[], expected={}),
         ]
         tc = TestCase(name="seq", steps=steps)
         assert tc.execution.steps is steps
@@ -115,7 +114,7 @@ def test_execution_passthrough_write(self):
         tc.timeout = 5
         tc.retry_count = 3
         tc.env = {"A": "B"}
-        tc.steps = [TestCaseStep(command="s", args=[], expected={})]
+        tc.steps = [TestStep.from_flat(command="s", args=[], expected={})]
         assert tc.execution.command == "ls"
         assert tc.execution.args == ["-l"]
         assert tc.execution.timeout == 5
@@ -180,7 +179,7 @@ def test_is_single_command_true_for_flat_case(self):
         assert TestCase(name="t", command="echo").is_single_command is True
 
     def test_sequence_all_steps_returns_steps_list(self):
-        steps = [TestCaseStep(command="s", args=[], expected={})]
+        steps = [TestStep.from_flat(command="s", args=[], expected={})]
         tc = TestCase(name="t", steps=steps)
         assert tc.all_steps == steps
 
@@ -197,7 +196,7 @@ def test_execution_spec_has_no_expected_field(self):
 
     def test_step_carries_its_own_expected(self):
         """steps 是"执行+判定"原子对，step 级 expected 属于 step。"""
-        step = TestCaseStep(command="a", args=[], expected={"return_code": 0})
+        step = TestStep.from_flat(command="a", args=[], expected={"return_code": 0})
         spec = ExecutionSpec(steps=[step])
         assert spec.steps[0].expected == {"return_code": 0}
 
@@ -233,7 +232,7 @@ def test_to_dict_sequence_mode_keeps_steps(self):
         tc = TestCase(
             name="seq",
             steps=[
-                TestCaseStep(command="a", args=["1"], expected={}, timeout=5.0),
+                TestStep.from_flat(command="a", args=["1"], expected={}, timeout=5.0),
             ],
         )
         assert tc.to_dict()["execution"]["steps"] == [
@@ -243,7 +242,7 @@ def test_to_dict_sequence_mode_keeps_steps(self):
 
     def test_to_dict_sequence_mode_omits_command_args(self):
         """steps 模式下 execution 省略 command/args（二选一）。"""
-        tc = TestCase(name="seq", steps=[TestCaseStep(command="a", args=[], expected={})])
+        tc = TestCase(name="seq", steps=[TestStep.from_flat(command="a", args=[], expected={})])
         execution = tc.to_dict()["execution"]
         assert "command" not in execution
         assert "args" not in execution
@@ -285,10 +284,10 @@ def test_to_execution_dict_bridge_removed(self):
         assert not hasattr(tc, "to_execution_dict")
 
     def test_deepcopy_works(self):
-        """TUI duplicate_case 依赖 deepcopy。"""
+        """TestCase 支持深拷贝（调用方复制用例的通用前提）。"""
         tc = TestCase(
             name="t",
-            steps=[TestCaseStep(command="a", args=[], expected={})],
+            steps=[TestStep.from_flat(command="a", args=[], expected={})],
         )
         clone = copy.deepcopy(tc)
         clone.name = "clone"
diff --git a/tests/unit/core/test_orchestration_accept.py b/tests/unit/core/test_orchestration_accept.py
index 3ff7624..843e954 100644
--- a/tests/unit/core/test_orchestration_accept.py
+++ b/tests/unit/core/test_orchestration_accept.py
@@ -13,7 +13,10 @@
 from symtest.core.orchestration.single import execute_single_test_case
 from symtest.core.test_case import ExecutionSpec
 from symtest.core.validation.validator import validate_result
-from symtest.reporting.diagnosis import build_next_action_hint
+from symtest.reporting.diagnosis import (
+    attach_next_action_hint,
+    build_next_action_hint,
+)
 
 
 def _exec(output="", return_code=0, name="t"):
@@ -162,7 +165,9 @@ def test_without_update_baseline_fails(self):
 
             assert result["status"] == "failed"
             assert result["failure_kind"] == "file_compare"
-            assert result["next_action_hint"]["action"] == "update_baseline"
+            # Orchestration 只产 failure_kind；hint 由 reporting 装配点填充
+            assert result["next_action_hint"] is None
+            assert attach_next_action_hint(result)["action"] == "update_baseline"
             with open(os.path.join(d, "baseline.txt")) as f:
                 assert f.read() == "old\n"
 
@@ -178,6 +183,9 @@ def test_comparator_error_stays_failed_even_with_update_baseline(self):
             )
 
             assert result["status"] == "failed"
-            assert result["next_action_hint"]["action"] == "investigate"
+            assert result["next_action_hint"] is None
+            assert attach_next_action_hint(
+                result, update_baseline=True,
+            )["action"] == "investigate"
             with open(os.path.join(d, "baseline.txt")) as f:
                 assert f.read() == "old\n"
diff --git a/tests/unit/core/test_process_worker.py b/tests/unit/core/test_process_worker.py
index 0113e41..5058976 100644
--- a/tests/unit/core/test_process_worker.py
+++ b/tests/unit/core/test_process_worker.py
@@ -1,7 +1,7 @@
 from unittest.mock import patch
 
 from symtest.core import process_worker
-from symtest.core.test_case import TestCase, TestCaseStep
+from symtest.core.test_case import TestCase, TestStep
 
 
 def passed_result(name="case", output="ok\n"):
@@ -65,8 +65,8 @@ def test_run_sequence_in_process_aggregates_successful_steps():
     case = TestCase(
         name="sequence",
         steps=[
-            TestCaseStep(command="echo", args=["one"], expected={"return_code": 0}),
-            TestCaseStep(command="echo", args=["two"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["one"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["two"], expected={"return_code": 0}),
         ],
     ).to_dict()
 
@@ -87,9 +87,9 @@ def test_run_sequence_in_process_stops_on_first_failure():
     case = TestCase(
         name="sequence",
         steps=[
-            TestCaseStep(command="echo", args=["one"], expected={"return_code": 0}),
-            TestCaseStep(command="tool", args=["fail"], expected={"return_code": 0}),
-            TestCaseStep(command="echo", args=["three"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["one"], expected={"return_code": 0}),
+            TestStep.from_flat(command="tool", args=["fail"], expected={"return_code": 0}),
+            TestStep.from_flat(command="echo", args=["three"], expected={"return_code": 0}),
         ],
     ).to_dict()
 
diff --git a/tests/unit/core/test_sequence_state.py b/tests/unit/core/test_sequence_state.py
index 721bed2..5855583 100644
--- a/tests/unit/core/test_sequence_state.py
+++ b/tests/unit/core/test_sequence_state.py
@@ -6,7 +6,7 @@
     save_sequence_state,
     save_step_output,
 )
-from symtest.core.test_case import TestCaseStep
+from symtest.core.test_case import TestStep
 
 
 def test_config_hash_is_stable_for_mapping_key_order():
@@ -36,14 +36,14 @@ def test_config_hash_preserves_argument_order():
 
 
 def test_config_hash_covers_step_controls_and_case_expected():
-    step = TestCaseStep(
+    step = TestStep.from_flat(
         command="solver",
         args=["model.dat"],
         expected={"return_code": 0},
         timeout=10,
         retry_count=1,
     )
-    changed_timeout = TestCaseStep(
+    changed_timeout = TestStep.from_flat(
         command="solver",
         args=["model.dat"],
         expected={"return_code": 0},
diff --git a/tests/unit/file_comparator/test_error_analysis.py b/tests/unit/file_comparator/test_error_analysis.py
index 3912a34..5ed96f0 100644
--- a/tests/unit/file_comparator/test_error_analysis.py
+++ b/tests/unit/file_comparator/test_error_analysis.py
@@ -1,4 +1,5 @@
 """Unit tests for error_analysis streaming statistics in CSV/H5 comparators."""
+import math
 import os
 import tempfile
 
@@ -43,13 +44,34 @@ def test_error_analysis_accumulates_stats(self):
         assert stats["mean_abs_error"] >= 0.0
 
     def test_error_analysis_all_matching(self):
-        """When all numeric cells match, stats show zero mismatches."""
+        """When all numeric cells match, stats cover all cells with zero errors."""
         cmp = CsvComparator(error_analysis=True)
         content1 = [["1.0", "2.0"], ["3.0", "4.0"]]
         content2 = [["1.0", "2.0"], ["3.0", "4.0"]]
         identical, diffs, truncated = cmp.compare_content(content1, content2)
         assert identical
-        assert cmp._error_stats is None  # no stats when identical (compare_content returns early)
+        assert cmp._error_stats is not None
+        stats = cmp._error_stats
+        assert stats["total_numeric_cells"] == 4
+        assert stats["mismatched_cells"] == 0
+        assert stats["max_abs_error"] == pytest.approx(0.0, abs=1e-12)
+        assert stats["mean_abs_error"] == pytest.approx(0.0, abs=1e-12)
+        assert stats["rms_abs_error"] == pytest.approx(0.0, abs=1e-12)
+
+    def test_error_analysis_stats_over_all_cells(self):
+        """Magnitude stats cover ALL cells; mean/rms divide by total, not mismatches."""
+        cmp = CsvComparator(error_analysis=True)
+        # Cell 1 matches exactly (0.0 error), cell 2 differs by 3.0.
+        content1 = [["1.0", "2.0"]]
+        content2 = [["1.0", "5.0"]]
+        identical, diffs, truncated = cmp.compare_content(content1, content2)
+        stats = cmp._error_stats
+        assert stats["total_numeric_cells"] == 2
+        assert stats["mismatched_cells"] == 1
+        assert stats["max_abs_error"] == pytest.approx(3.0, abs=1e-9)
+        # Old semantics: mean over mismatched only = 3.0; now over all cells = 1.5.
+        assert stats["mean_abs_error"] == pytest.approx(1.5, abs=1e-9)
+        assert stats["rms_abs_error"] == pytest.approx(3.0 / math.sqrt(2), abs=1e-9)
 
     def test_error_analysis_tracks_max_abs_error(self):
         """Verify max_abs_error tracks the largest absolute difference."""
diff --git a/tests/unit/file_comparator/test_extractor_channels.py b/tests/unit/file_comparator/test_extractor_channels.py
new file mode 100644
index 0000000..4dc637d
--- /dev/null
+++ b/tests/unit/file_comparator/test_extractor_channels.py
@@ -0,0 +1,253 @@
+"""Unit tests for the data-lane channel pipeline (ExtractorComparator).
+
+Covers per-channel tolerance routing, framework-owned verdict aggregation,
+extra_stats merging, channel-position prefixes, and error handling.
+"""
+import numpy as np
+import pytest
+from pathlib import Path
+
+from symtest.file_comparator.base_comparator import CompareContext
+from symtest.file_comparator.extractor_comparator import (
+    ChannelData,
+    ExtractorComparator,
+)
+
+
+class FakeExtractor(ExtractorComparator):
+    """Deterministic extractor for tests."""
+
+    def __init__(self, channels_data=None, **kwargs):
+        super().__init__(**kwargs)
+        self._channels_data = channels_data or {}
+
+    def extract(self, ctx):
+        return self._channels_data
+
+
+def _ctx(**kw):
+    return CompareContext(**kw)
+
+
+class TestChannelRouting:
+    def test_per_channel_tolerance_override(self):
+        """A channel-specific atol overrides default_channel."""
+        # diff = 0.5: fails rtol=1e-5/atol=1e-8, passes atol=1.0
+        data = {"S11": ChannelData(expected=np.array([1.0]), actual=np.array([1.5]))}
+        cmp = FakeExtractor(
+            channels_data=data,
+            channels={"S11": {"atol": 1.0}},
+            default_channel={"rtol": 1e-5, "atol": 1e-8},
+        )
+        result = cmp.compare(_ctx())
+        assert result.identical is True
+        assert result.channels[0].atol == 1.0
+
+    def test_unlisted_channel_uses_default(self):
+        data = {
+            "S11": ChannelData(expected=np.array([1.0]), actual=np.array([1.0])),
+            "S22": ChannelData(expected=np.array([2.0]), actual=np.array([2.0])),
+        }
+        cmp = FakeExtractor(
+            channels_data=data,
+            channels={"S11": {"atol": 1.0}},
+            default_channel={"rtol": 1e-5, "atol": 1e-8},
+        )
+        result = cmp.compare(_ctx())
+        by_name = {ch.name: ch for ch in result.channels}
+        assert by_name["S11"].atol == 1.0
+        assert by_name["S22"].atol == 1e-8
+
+    def test_default_rtol_atol_fallback(self):
+        data = {"S11": ChannelData(expected=np.array([1.0]), actual=np.array([1.0]))}
+        cmp = FakeExtractor(channels_data=data, rtol=1e-3, atol=1e-2)
+        result = cmp.compare(_ctx())
+        assert result.channels[0].rtol == 1e-3
+        assert result.channels[0].atol == 1e-2
+
+
+class TestAggregation:
+    def test_all_channels_pass(self):
+        data = {
+            "S11": ChannelData(expected=np.array([1.0, 2.0]), actual=np.array([1.0, 2.0])),
+            "S33": ChannelData(expected=np.array([3.0]), actual=np.array([3.0])),
+        }
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        assert result.identical is True
+        assert all(ch.passed for ch in result.channels)
+        assert result.differences == []
+
+    def test_any_channel_failure_fails_result(self):
+        data = {
+            "S11": ChannelData(expected=np.array([1.0]), actual=np.array([1.0])),
+            "S33": ChannelData(expected=np.array([1.0]), actual=np.array([500.0])),
+        }
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        assert result.identical is False
+        by_name = {ch.name: ch for ch in result.channels}
+        assert by_name["S11"].passed is True
+        assert by_name["S33"].passed is False
+        assert len(result.differences) == 1
+        assert result.differences[0].position == "channel S33"
+        assert result.differences[0].diff_type == "channel_mismatch"
+
+    def test_error_stats_keyed_by_channel(self):
+        data = {
+            "S11": ChannelData(expected=np.array([1.0]), actual=np.array([1.0])),
+            "S33": ChannelData(expected=np.array([1.0]), actual=np.array([2.0])),
+        }
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        assert set(result.error_stats.keys()) == {"S11", "S33"}
+        assert result.error_stats["S11"]["mismatched"] == 0
+        assert result.error_stats["S33"]["mismatched"] == 1
+
+    def test_stats_summary_fields(self):
+        data = {"S11": ChannelData(expected=np.array([1.0, 2.0]), actual=np.array([1.5, 2.0]))}
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        stats = result.channels[0].stats
+        for key in ("total", "mismatched", "max_abs_error", "max_rel_error",
+                    "mean_abs_error", "rms_abs_error"):
+            assert key in stats
+        assert stats["total"] == 2
+
+
+class TestExtraStats:
+    def test_extra_stats_in_separate_namespace(self):
+        """Plugin-defined metrics live in ChannelResult.extra_stats, never
+        merged into framework-owned canonical stats."""
+        data = {
+            "S33": ChannelData(
+                expected=np.array([1.0]),
+                actual=np.array([1.0]),
+                extra_stats={"asymmetry": 1.5e-13, "verdict": "PASS"},
+            ),
+        }
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        ch = result.channels[0]
+        # Canonical stats untouched by plugin metrics
+        assert "asymmetry" not in ch.stats
+        assert "verdict" not in ch.stats
+        assert ch.stats["max_abs_error"] is not None or ch.stats["total"] == 1
+        # Plugin metrics ride along in their own namespace
+        assert ch.extra_stats["asymmetry"] == 1.5e-13
+        assert ch.extra_stats["verdict"] == "PASS"
+        # Serialized shape keeps the namespaces distinct
+        d = ch.to_dict()
+        assert d["extra_stats"]["asymmetry"] == 1.5e-13
+        assert "asymmetry" not in d["stats"]
+
+    def test_extra_stats_cannot_overwrite_canonical_stats(self):
+        """A plugin providing canonical-looking keys must NOT overwrite
+        framework-owned metrics."""
+        data = {
+            "S33": ChannelData(
+                expected=np.array([1.0]),
+                actual=np.array([900.0]),  # canonical max_abs_error = 899.0
+                extra_stats={"max_abs_error": 123.0, "total": 999},
+            ),
+        }
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        ch = result.channels[0]
+        assert ch.stats["max_abs_error"] == pytest.approx(899.0)
+        assert ch.stats["total"] == 1
+        assert ch.extra_stats["max_abs_error"] == 123.0
+        assert ch.extra_stats["total"] == 999
+
+
+class TestErrorHandling:
+    def test_size_mismatch_is_channel_error(self):
+        data = {"S11": ChannelData(expected=np.array([1.0, 2.0]), actual=np.array([1.0]))}
+        cmp = FakeExtractor(channels_data=data)
+        result = cmp.compare(_ctx())
+        assert result.identical is False
+        ch = result.channels[0]
+        assert ch.passed is False
+        assert ch.differences[0].diff_type == "channel_error"
+
+    def test_extract_failure_becomes_result_error(self):
+        class BoomExtractor(FakeExtractor):
+            def extract(self, ctx):
+                raise RuntimeError("solver output missing")
+
+        cmp = BoomExtractor()
+        result = cmp.compare(_ctx())
+        assert result.identical is False
+        assert "solver output missing" in result.error
+        assert result.channels == []
+
+    def test_empty_channels_is_error(self):
+        cmp = FakeExtractor(channels_data={})
+        result = cmp.compare(_ctx())
+        assert result.identical is False
+        assert "no channels" in result.error
+
+
+class TestDataFilter:
+    def test_channel_data_filter_excludes_cells(self):
+        """data_filter routes small-magnitude cells out of the comparison."""
+        data = {"U": ChannelData(
+            expected=np.array([1.0, 1e-12]),
+            actual=np.array([1.0, 5e-12]),  # second cell differs but is filtered out
+        )}
+        cmp = FakeExtractor(
+            channels_data=data,
+            default_channel={"data_filter": "abs>1e-6"},
+        )
+        result = cmp.compare(_ctx())
+        assert result.identical is True
+        assert result.channels[0].stats["total"] == 1
+
+
+class TestAssertionsIntegration:
+    def test_compare_files_resolves_path_params(self, tmp_path, monkeypatch):
+        """Assertions.compare_files resolves path_params against workspace
+        BEFORE construction: constructor-captured state already holds the
+        absolute path (single source of truth — ctx.params carries no copy)."""
+        from symtest.file_comparator.factory import ComparatorFactory
+        from symtest.core.validation.assertions import Assertions
+
+        captured = {}
+
+        class PathParamExtractor(FakeExtractor):
+            path_params = ("data_file",)
+
+            def __init__(self, data_file="", **kwargs):
+                super().__init__(**kwargs)
+                # Constructor-captured state must already be workspace-resolved.
+                self.data_file = data_file
+
+            def extract(self, ctx):
+                captured["ctor_data_file"] = self.data_file
+                captured["ctx_params"] = dict(ctx.params)
+                values = [float(x) for x in Path(self.data_file).read_text().split()]
+                return {"v": ChannelData(expected=values, actual=values)}
+
+        monkeypatch.setattr(
+            ComparatorFactory, "_comparators",
+            {**ComparatorFactory._comparators, "pathparam": PathParamExtractor},
+        )
+
+        data_file = tmp_path / "values.txt"
+        data_file.write_text("1.0 2.0 3.0\n", encoding="utf-8")
+
+        response = Assertions.compare_files(
+            actual_path=None,
+            baseline_path=None,
+            file_type="pathparam",
+            workspace=str(tmp_path),
+            data_file="values.txt",  # workspace-relative
+        )
+        assert response["identical"] is True
+        resolved = captured["ctor_data_file"]
+        assert Path(resolved).is_absolute()
+        assert Path(resolved) == data_file
+        # ctx.params is invocation-level only — no configuration copy.
+        assert "data_file" not in captured["ctx_params"]
+        assert response["channels"][0]["name"] == "v"
+        assert response["channels"][0]["passed"] is True
diff --git a/tests/unit/file_comparator/test_numeric_compare.py b/tests/unit/file_comparator/test_numeric_compare.py
index d741895..ca7af18 100644
--- a/tests/unit/file_comparator/test_numeric_compare.py
+++ b/tests/unit/file_comparator/test_numeric_compare.py
@@ -12,8 +12,9 @@ def test_exact_equality():
     assert res.total == 3
     assert res.mismatched == 0
     assert np.all(~res.mismatch_mask)
-    assert res.max_abs_error is None
-    assert res.max_rel_error is None
+    # Stats cover ALL cells: zero errors everywhere.
+    assert res.max_abs_error == pytest.approx(0.0, abs=1e-12)
+    assert res.max_rel_error == pytest.approx(0.0, abs=1e-12)
 
 
 def test_within_rtol():
@@ -171,7 +172,8 @@ def test_collect_stats_false_all_filtered_out():
 def test_no_mismatch_collect_stats_true():
     res = compare_numeric([1.0, 2.0], [1.0, 2.0], collect_stats=True)
     assert res.mismatched == 0
-    assert res.max_abs_error is None
+    # Stats cover ALL cells: zero errors everywhere, denominators = total.
+    assert res.max_abs_error == pytest.approx(0.0, abs=1e-12)
     assert res.mean_abs_error == 0.0
     assert res.rms_abs_error == 0.0
 
diff --git a/tests/unit/file_comparator/test_plugin_lifecycle.py b/tests/unit/file_comparator/test_plugin_lifecycle.py
new file mode 100644
index 0000000..7b9aa0d
--- /dev/null
+++ b/tests/unit/file_comparator/test_plugin_lifecycle.py
@@ -0,0 +1,420 @@
+"""Regression tests for the comparator construction lifecycle (v2.1).
+
+Acceptance coverage:
+1. path_params are workspace-resolved BEFORE comparator construction
+2. constructor-captured state (self.script / self.cwd / self.case_dir)
+   contains resolved absolute paths
+3. behaviour is independent of the process CWD
+4. hourglass-style plugins keep working without plugin-side .resolve()
+5. abstract comparator classes are never registered
+6. explicit comparator_type wins over the class-name convention
+7. the convention fallback strips ONLY the trailing Comparator suffix
+8. built-in and workspace discovery share identical registration rules
+9. unknown/misspelled comparator parameters fail loudly
+10. the "options" config namespace merges into constructor kwargs with
+    top-level keys taking precedence
+"""
+import importlib.util
+import json
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from symtest.core.validation.assertions import Assertions, ValidationError
+from symtest.core.validation.validator import _dispatch_file_compare
+from symtest.file_comparator.base_comparator import ComparatorBase, CompareContext
+from symtest.file_comparator.extractor_comparator import ExtractorComparator
+from symtest.file_comparator.factory import (
+    ComparatorFactory,
+    _type_name_from_class,
+)
+from symtest.file_comparator.result import ComparisonResult
+from symtest.file_comparator.script_extract_comparator import (
+    ScriptExtractComparator,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_factory():
+    ComparatorFactory.reset()
+    yield
+    ComparatorFactory.reset()
+
+
+def _register_type(type_name, cls):
+    ComparatorFactory.register_comparator(type_name, cls)
+
+
+# ---------------------------------------------------------------------------
+# 1–3: path_params resolved before construction, CWD-independent
+# ---------------------------------------------------------------------------
+
+class TestPathParamsResolvedBeforeConstruction:
+    def test_script_extract_ctor_state_is_workspace_resolved(self, tmp_path):
+        (tmp_path / "scripts").mkdir()
+        (tmp_path / "cases" / "case01").mkdir(parents=True)
+
+        cmp = ComparatorFactory.create_comparator(
+            "script_extract",
+            workspace=str(tmp_path),
+            script="scripts/extract.py",
+            cwd="cases/case01",
+        )
+        assert isinstance(cmp, ScriptExtractComparator)
+        # Constructor-captured state already holds ABSOLUTE paths.
+        assert cmp.script == str(tmp_path / "scripts" / "extract.py")
+        assert cmp.cwd == str(tmp_path / "cases" / "case01")
+
+    def test_resolution_independent_of_process_cwd(self, tmp_path, monkeypatch):
+        (tmp_path / "scripts").mkdir()
+        other_cwd = tmp_path / "unrelated"
+        other_cwd.mkdir()
+        monkeypatch.chdir(other_cwd)  # process CWD must not matter
+
+        workspace = tmp_path / "ws"
+        workspace.mkdir()
+        cmp = ComparatorFactory.create_comparator(
+            "script_extract",
+            workspace=str(workspace),
+            script="scripts/extract.py",
+        )
+        assert cmp.script == str(workspace / "scripts" / "extract.py")
+
+    def test_resolved_script_actually_executes_from_other_cwd(
+            self, tmp_path, monkeypatch):
+        """End-to-end: a workspace-relative script/cwd executes correctly even
+        when the process CWD is somewhere unrelated."""
+        ws = tmp_path / "ws"
+        (ws / "scripts").mkdir(parents=True)
+        (ws / "cases" / "case01").mkdir(parents=True)
+        script = ws / "scripts" / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json
+            print(json.dumps({"channels": {
+                "A": {"expected": [1.0], "actual": [1.0]}
+            }}))
+        """), encoding="utf-8")
+
+        monkeypatch.chdir(tmp_path)  # CWD is NOT the workspace
+        cmp = ComparatorFactory.create_comparator(
+            "script_extract",
+            workspace=str(ws),
+            script="scripts/extract.py",
+            cwd="cases/case01",
+        )
+        result = cmp.compare(CompareContext())
+        assert result.error is None
+        assert result.identical is True
+
+    def test_script_comparator_ctor_state_is_workspace_resolved(self, tmp_path):
+        cmp = ComparatorFactory.create_comparator(
+            "script",
+            workspace=str(tmp_path),
+            script="scripts/analyze.py",
+            cwd="cases/case01",
+        )
+        assert cmp.script == str(tmp_path / "scripts" / "analyze.py")
+        assert cmp.cwd == str(tmp_path / "cases" / "case01")
+
+    def test_hourglass_plugin_ctor_state_is_workspace_resolved(
+            self, tmp_path, monkeypatch):
+        """The example plugin receives workspace-resolved script/case_dir in
+        constructor state — proving removal of plugin-side Path.resolve() is
+        safe now that the framework resolves before construction."""
+        plugin_file = (
+            Path(__file__).resolve().parent.parent.parent.parent
+            / "examples" / "plugins" / "hourglass_tangent_comparator.py"
+        )
+        spec = importlib.util.spec_from_file_location(
+            "hourglass_lifecycle_test", str(plugin_file)
+        )
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        cls = module.HourglassTangentComparator
+
+        monkeypatch.setitem(
+            ComparatorFactory._comparators, "hourglass_tangent", cls
+        )
+        cmp = ComparatorFactory.create_comparator(
+            "hourglass_tangent",
+            workspace=str(tmp_path),
+            script="case/analyze_tangent.py",
+            case_dir="case/case01",
+        )
+        assert cls.path_params == ("script", "case_dir")
+        assert cmp.script == str(tmp_path / "case" / "analyze_tangent.py")
+        assert cmp.case_dir == str(tmp_path / "case" / "case01")
+
+    def test_absolute_paths_not_touched(self, tmp_path):
+        absolute = str(tmp_path / "scripts" / "extract.py")
+        cmp = ComparatorFactory.create_comparator(
+            "script_extract", workspace=str(tmp_path / "other"),
+            script=absolute,
+        )
+        assert cmp.script == absolute
+
+
+# ---------------------------------------------------------------------------
+# 5–8: discovery / registration rules
+# ---------------------------------------------------------------------------
+
+class TestDiscoveryRules:
+    def test_abstract_classes_not_registered(self):
+        ComparatorFactory._load_comparators()
+        available = ComparatorFactory.get_available_comparators()
+        # Abstract lane bases must never appear as instantiable types.
+        assert "extractor" not in available
+        assert "file" not in available
+        assert "comparatorbase" not in available
+
+    def test_explicit_comparator_type_wins(self, tmp_path):
+        plugin = tmp_path / "win_comparator.py"
+        plugin.write_text(textwrap.dedent("""
+            from symtest.file_comparator.base_comparator import ComparatorBase
+            from symtest.file_comparator.result import ComparisonResult
+
+            class WinComparator(ComparatorBase):
+                comparator_type = "my_explicit_name"
+                def compare(self, ctx):
+                    return ComparisonResult()
+        """), encoding="utf-8")
+        ComparatorFactory.set_plugin_dirs([tmp_path])
+        assert "my_explicit_name" in ComparatorFactory.get_available_comparators()
+        # Convention-derived name must NOT exist alongside the explicit one
+        assert "win" not in ComparatorFactory.get_available_comparators()
+
+    def test_suffix_only_convention_fallback(self):
+        # Only the trailing "Comparator" suffix is stripped.
+        assert _type_name_from_class("TextComparator") == "text"
+        assert _type_name_from_class("H5Comparator") == "h5"
+        assert _type_name_from_class("HourglassTangentComparator") == "hourglasstangent"
+        # 'comparator' occurring earlier in the name is preserved
+        assert _type_name_from_class("XComparatorComparator") == "xcomparator"
+
+    def test_invalid_explicit_comparator_type_falls_back(self, tmp_path):
+        plugin = tmp_path / "bad_type_comparator.py"
+        plugin.write_text(textwrap.dedent("""
+            from symtest.file_comparator.base_comparator import ComparatorBase
+            from symtest.file_comparator.result import ComparisonResult
+
+            class BadTypeComparator(ComparatorBase):
+                comparator_type = 123  # invalid: not a string
+                def compare(self, ctx):
+                    return ComparisonResult()
+        """), encoding="utf-8")
+        ComparatorFactory.set_plugin_dirs([tmp_path])
+        # Falls back to the class-name convention instead of registering garbage
+        assert "badtype" in ComparatorFactory.get_available_comparators()
+        assert "123" not in ComparatorFactory.get_available_comparators()
+
+    def test_builtin_and_workspace_share_registration_rules(self, tmp_path):
+        """The same class registered through both discovery paths yields the
+        same type name and both honour abstract filtering."""
+        # Built-in path: abstract ExtractorComparator is skipped
+        ComparatorFactory._load_comparators()
+        assert "extractor" not in ComparatorFactory.get_available_comparators()
+
+        # Workspace path: an abstract class in a plugin dir is skipped too
+        plugin = tmp_path / "abstract_plugin_comparator.py"
+        plugin.write_text(textwrap.dedent("""
+            from symtest.file_comparator.extractor_comparator import (
+                ExtractorComparator,
+            )
+
+            class StillAbstract(ExtractorComparator):
+                '''Does not implement extract() — stays abstract.'''
+        """), encoding="utf-8")
+        ComparatorFactory.set_plugin_dirs([tmp_path])
+        assert "stillabstract" not in ComparatorFactory.get_available_comparators()
+
+    def test_registration_helper_returns_type_name(self):
+        class HelperCheckedComparator(ComparatorBase):
+            def compare(self, ctx):
+                return ComparisonResult()
+
+        name = ComparatorFactory._register_comparator_class(
+            HelperCheckedComparator, HelperCheckedComparator.__module__,
+        )
+        assert name == "helperchecked"
+
+
+# ---------------------------------------------------------------------------
+# 11: unknown comparator TYPE fails loudly (no silent fallback)
+# ---------------------------------------------------------------------------
+
+class TestUnknownTypeFailsLoudly:
+    def test_unknown_type_raises_with_available_types(self):
+        """A typo'd 'type' (e.g. 'cvs') must raise, naming the available types —
+        never silently degrade to another comparator."""
+        ComparatorFactory._load_comparators()
+        with pytest.raises(ValueError, match="Unknown comparator type 'cvs'"):
+            ComparatorFactory.get_comparator_class("cvs")
+
+    def test_unknown_type_create_comparator_raises(self):
+        with pytest.raises(ValueError, match="Available types"):
+            ComparatorFactory.create_comparator("cvs")
+
+    def test_auto_and_text_still_resolve_to_text(self):
+        """'auto'/'text' keep their documented TextComparator mapping;
+        'auto' is normally resolved from the extension upstream."""
+        from symtest.file_comparator.text_comparator import TextComparator
+        assert ComparatorFactory.get_comparator_class("auto") is TextComparator
+        assert ComparatorFactory.get_comparator_class("text") is TextComparator
+
+    def test_unknown_type_via_assertions_is_validation_error(self):
+        """Through the assertion layer an unknown type surfaces as a
+        ValidationError (failure_kind=file_compare), not a wrong pass."""
+        with pytest.raises(ValidationError, match="Unknown comparator type"):
+            Assertions.compare_files("a.bin", "b.bin", file_type="cvs")
+
+    def test_registration_helper_skips_foreign_and_abstract(self):
+        class ForeignComparator(ComparatorBase):
+            def compare(self, ctx):
+                return ComparisonResult()
+
+        # Foreign module classes are skipped
+        assert ComparatorFactory._register_comparator_class(
+            ForeignComparator, "some.other.module",
+        ) is None
+        # Abstract classes are skipped
+        assert ComparatorFactory._register_comparator_class(
+            ExtractorComparator, ExtractorComparator.__module__,
+        ) is None
+
+
+# ---------------------------------------------------------------------------
+# 9: strict configuration
+# ---------------------------------------------------------------------------
+
+class TestStrictConfiguration:
+    def test_unknown_param_fails_loudly_at_factory(self, tmp_path):
+        with pytest.raises(TypeError) as exc_info:
+            ComparatorFactory.create_comparator(
+                "script_extract",
+                workspace=str(tmp_path),
+                script="s.py",
+                timeut=600,  # typo of 'timeout'
+            )
+        message = str(exc_info.value)
+        assert "ScriptExtractComparator" in message
+        assert "timeut" in message
+        assert "timeout" in message  # supported params are listed
+
+    def test_unknown_param_fails_loudly_via_assertion(self, tmp_path):
+        (tmp_path / "a.txt").write_text("same\n", encoding="utf-8")
+        (tmp_path / "b.txt").write_text("same\n", encoding="utf-8")
+        with pytest.raises(ValidationError) as exc_info:
+            Assertions.compare_files(
+                "a.txt", "b.txt", workspace=str(tmp_path),
+                file_type="text", rtol=1e-5,  # text comparator has no rtol
+            )
+        assert "TextComparator" in str(exc_info.value)
+
+    def test_declared_params_still_work(self, tmp_path):
+        cmp = ComparatorFactory.create_comparator(
+            "script_extract",
+            workspace=str(tmp_path),
+            script="s.py",
+            timeout=42,
+            channels={"A": {"atol": 1.0}},
+            default_channel={"rtol": 1e-3},
+        )
+        assert cmp.timeout == 42
+        assert cmp.channel_specs == {"A": {"atol": 1.0}}
+        assert cmp.default_spec == {"rtol": 1e-3}
+
+
+# ---------------------------------------------------------------------------
+# Autonomous comparators without two-file inputs (no fake "" paths)
+# ---------------------------------------------------------------------------
+
+class TestNoFileInputs:
+    def test_autonomous_result_has_none_file_paths(self):
+        """Autonomous comparators must not fake file1=""/file2="" — absent
+        inputs stay None through construction, str() and serialization."""
+        class NoFileComparator(ComparatorBase):
+            def compare(self, ctx):
+                return self._analyze()
+
+            def _analyze(self):
+                result = ComparisonResult()
+                result.identical = True
+                result.error_stats = {"energy_ratio": 0.98}
+                return result
+
+        result = NoFileComparator().compare(CompareContext())
+        assert result.file1 is None
+        assert result.file2 is None
+        # No obsolete two-file worldview leakage into string rendering
+        assert "None" not in str(result)
+        # Serialization carries explicit nulls, not empty strings
+        d = result.to_dict()
+        assert d["file1"] is None
+        assert d["file2"] is None
+
+    def test_script_comparator_without_files(self, tmp_path):
+        (tmp_path / "s.py").write_text("print('PASS')\n", encoding="utf-8")
+        cmp = ComparatorFactory.create_comparator(
+            "script", workspace=str(tmp_path), script="s.py",
+        )
+        result = cmp.compare(CompareContext())
+        assert result.identical is True
+        assert result.file1 is None
+        assert result.file2 is None
+        assert result.to_dict()["file1"] is None
+
+
+# ---------------------------------------------------------------------------
+# 10: "options" namespace merge
+# ---------------------------------------------------------------------------
+
+class TestOptionsNamespace:
+    def test_options_merged_with_top_level_precedence(self, tmp_path, monkeypatch):
+        captured = {}
+
+        class OptionsProbe(ComparatorBase):
+            def __init__(self, from_options="", from_top="", timeout=0):
+                super().__init__()
+                self.from_options = from_options
+                self.from_top = from_top
+                self.timeout = timeout
+
+            def compare(self, ctx):
+                captured.update(
+                    from_options=self.from_options,
+                    from_top=self.from_top,
+                    timeout=self.timeout,
+                )
+                result = ComparisonResult()
+                result.identical = True
+                return result
+
+        monkeypatch.setitem(
+            ComparatorFactory._comparators, "optionsprobe", OptionsProbe
+        )
+        spec = {
+            "type": "optionsprobe",
+            "options": {
+                "from_options": "opt",
+                "from_top": "should_be_overridden",
+                "timeout": 7,
+            },
+            "from_top": "top_wins",
+        }
+        result = _dispatch_file_compare(spec, str(tmp_path), Assertions())
+        assert result["passed"] is True
+        assert captured["from_options"] == "opt"
+        assert captured["from_top"] == "top_wins"  # top-level precedence
+        assert captured["timeout"] == 7
+
+    def test_invalid_options_type_fails_loudly(self):
+        spec = {
+            "type": "text",
+            "actual": "a.txt",
+            "baseline": "b.txt",
+            "options": "not-a-dict",
+        }
+        with pytest.raises(ValidationError) as exc_info:
+            _dispatch_file_compare(spec, None, Assertions())
+        assert "'options'" in str(exc_info.value)
diff --git a/tests/unit/file_comparator/test_script_comparator.py b/tests/unit/file_comparator/test_script_comparator.py
index 02c0b7d..8b50d40 100644
--- a/tests/unit/file_comparator/test_script_comparator.py
+++ b/tests/unit/file_comparator/test_script_comparator.py
@@ -5,6 +5,7 @@
 
 import pytest
 
+from symtest.file_comparator.base_comparator import CompareContext
 from symtest.file_comparator.script_comparator import ScriptComparator
 
 
@@ -24,18 +25,18 @@ def mock_fail():
 class TestScriptComparatorPass:
     def test_exit_code_zero_is_pass(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass)
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is True
         assert "PASS" in (result.command_output or "")
 
     def test_pass_pattern_match(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass, pass_pattern=r"PASS")
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is True
 
     def test_pass_pattern_no_match_is_fail(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass, pass_pattern=r"NO_MATCH")
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is False
         assert any("pass_pattern_missing" == d.diff_type for d in result.differences)
 
@@ -43,14 +44,14 @@ def test_pass_pattern_no_match_is_fail(self, mock_pass):
 class TestScriptComparatorFail:
     def test_nonzero_exit_is_fail(self, mock_fail):
         cmp = ScriptComparator(script=mock_fail)
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is False
         assert any("exit_code_mismatch" == d.diff_type for d in result.differences)
 
     def test_fail_pattern_override(self, mock_fail):
         """fail_pattern match forces fail regardless of exit code."""
         cmp = ScriptComparator(script=mock_fail, fail_pattern=r"MISMATCH")
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is False
         assert any("fail_pattern_match" == d.diff_type for d in result.differences)
 
@@ -59,7 +60,7 @@ def test_fail_pattern_ignores_pass(self, mock_pass):
         cmp = ScriptComparator(
             script=mock_pass, fail_pattern=r"PASS",
         )
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is False
         assert any("fail_pattern_match" == d.diff_type for d in result.differences)
 
@@ -67,17 +68,17 @@ def test_fail_pattern_ignores_pass(self, mock_pass):
 class TestScriptComparatorEdge:
     def test_command_output_captured(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass)
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.command_output is not None
         assert "PASS" in result.command_output
 
     def test_args_forwarded(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass, args=["alpha", "beta"])
-        result = cmp.compare_files()
+        result = cmp.compare(CompareContext())
         assert result.identical is True
 
     def test_file_args_forwarded(self, mock_pass):
         cmp = ScriptComparator(script=mock_pass)
-        result = cmp.compare_files(file1="f1.txt", file2="f2.txt")
+        result = cmp.compare(CompareContext(actual="f2.txt", baseline="f1.txt"))
         assert result.identical is True
         assert "f1.txt" in (result.command_output or "")
diff --git a/tests/unit/file_comparator/test_script_extract.py b/tests/unit/file_comparator/test_script_extract.py
new file mode 100644
index 0000000..fb7f8f8
--- /dev/null
+++ b/tests/unit/file_comparator/test_script_extract.py
@@ -0,0 +1,187 @@
+"""Unit tests for the built-in script_extract comparator (JSON protocol).
+
+Covers: valid channel payloads, pass/fail verdicts (framework-owned),
+extra_stats passthrough, error handling (non-zero exit, malformed JSON,
+empty channels, timeout), and the baseline-first trailing file-arg convention.
+"""
+import json
+import sys
+import textwrap
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from symtest.file_comparator.base_comparator import CompareContext
+from symtest.file_comparator.script_extract_comparator import ScriptExtractComparator
+
+
+class TestValidPayloads:
+    def test_pass(self, tmp_path):
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json, sys
+            print(json.dumps({"channels": {
+                "S11": {"expected": [1.0, 2.0], "actual": [1.0, 2.0]}
+            }}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.error is None
+        assert result.identical is True
+        assert [ch.name for ch in result.channels] == ["S11"]
+        assert result.channels[0].passed is True
+
+    def test_fail_with_channel_prefix(self, tmp_path):
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json
+            print(json.dumps({"channels": {
+                "S33": {"expected": [1.0], "actual": [900.0]}
+            }}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert result.differences[0].position == "channel S33"
+        assert result.error_stats["S33"]["mismatched"] == 1
+
+    def test_extra_stats_passthrough(self, tmp_path):
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json
+            print(json.dumps({"channels": {
+                "K": {"expected": [1.0], "actual": [1.0],
+                      "extra_stats": {"asymmetry": 2e-13}}
+            }}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        ch = result.channels[0]
+        # Plugin metrics live in the separate extra_stats namespace
+        assert ch.extra_stats["asymmetry"] == 2e-13
+        assert "asymmetry" not in ch.stats
+
+    def test_per_channel_tolerance_routing(self, tmp_path):
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json
+            print(json.dumps({"channels": {
+                "S33": {"expected": [1.0], "actual": [1.5]}
+            }}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(
+            script=str(script), channels={"S33": {"atol": 1.0}},
+        )
+        result = cmp.compare(CompareContext())
+        assert result.identical is True
+
+    def test_command_output_captured(self, tmp_path):
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json
+            print("loading data...")
+            print(json.dumps({"channels": {"A": {"expected": [1], "actual": [1]}}}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert "loading data..." in result.command_output
+
+    def test_trailing_file_args_baseline_first(self, tmp_path):
+        """baseline then actual are appended as trailing argv slots."""
+        captured = {}
+
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json, sys
+            captured = {"argv": sys.argv[1:]}
+            print(json.dumps({"channels": {"A": {"expected": [1], "actual": [1]}}}))
+            import pathlib
+            pathlib.Path(__file__).with_suffix(".argv").write_text(json.dumps(captured))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext(actual="out.dat", baseline="ref.dat"))
+
+        assert result.identical is True
+        captured = json.loads(script.with_suffix(".argv").read_text())
+        assert captured["argv"] == ["ref.dat", "out.dat"]
+
+    def test_script_reads_input_file_content(self, tmp_path):
+        """End-to-end: script reads files and emits per-channel arrays."""
+        ref = tmp_path / "ref.csv"
+        out = tmp_path / "out.csv"
+        ref.write_text("1.0\n2.0\n", encoding="utf-8")
+        out.write_text("1.0\n2.5\n", encoding="utf-8")
+
+        script = tmp_path / "extract.py"
+        script.write_text(textwrap.dedent("""
+            import json, sys
+            baseline, actual = sys.argv[-2], sys.argv[-1]
+            def load(p):
+                return [float(x) for x in open(p).read().split()]
+            print(json.dumps({"channels": {
+                "col1": {"expected": load(baseline), "actual": load(actual)}
+            }}))
+        """), encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext(actual=str(out), baseline=str(ref)))
+        assert result.identical is False  # 2.0 vs 2.5 beyond default tolerance
+
+
+class TestErrorHandling:
+    def test_nonzero_exit_is_error(self, tmp_path):
+        script = tmp_path / "fail.py"
+        script.write_text("import sys; sys.exit(3)", encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "exited with code 3" in result.error
+
+    def test_malformed_json_is_error(self, tmp_path):
+        script = tmp_path / "badjson.py"
+        script.write_text("print('not json')", encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "not valid JSON" in result.error
+
+    def test_missing_channels_key_is_error(self, tmp_path):
+        script = tmp_path / "nochan.py"
+        script.write_text('import json; print(json.dumps({"data": []}))', encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "'channels'" in result.error
+
+    def test_empty_channels_is_error(self, tmp_path):
+        script = tmp_path / "emptychan.py"
+        script.write_text('import json; print(json.dumps({"channels": {}}))', encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "non-empty" in result.error
+
+    def test_channel_missing_arrays_is_error(self, tmp_path):
+        script = tmp_path / "badchan.py"
+        script.write_text(
+            'import json; print(json.dumps({"channels": {"A": {"expected": [1]}}}))',
+            encoding="utf-8",
+        )
+        cmp = ScriptExtractComparator(script=str(script))
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "channel 'A'" in result.error
+
+    def test_timeout_is_error(self, tmp_path):
+        script = tmp_path / "slow.py"
+        script.write_text("import time; time.sleep(30)", encoding="utf-8")
+        cmp = ScriptExtractComparator(script=str(script), timeout=1)
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "timed out" in result.error
+
+    def test_missing_script_param_is_error(self):
+        cmp = ScriptExtractComparator()
+        result = cmp.compare(CompareContext())
+        assert result.identical is False
+        assert "'script' parameter is required" in result.error
diff --git a/tests/unit/file_comparator/test_workspace_plugins.py b/tests/unit/file_comparator/test_workspace_plugins.py
index 50c3fb8..e94329e 100644
--- a/tests/unit/file_comparator/test_workspace_plugins.py
+++ b/tests/unit/file_comparator/test_workspace_plugins.py
@@ -9,8 +9,33 @@
 from symtest.file_comparator.factory import ComparatorFactory
 
 
+# Minimal autonomous-lane plugin body: implements the v2 root contract
+# (compare(ctx) -> ComparisonResult).  The legacy read_content/compare_content
+# stubs are no longer required — that is exactly what the v2 breaking change
+# removed.
+_PLUGIN_BODY = """
+from symtest.file_comparator.base_comparator import BaseComparator
+from symtest.file_comparator.result import ComparisonResult
+
+class {cls}(BaseComparator):
+    def compare(self, ctx):
+        result = ComparisonResult(
+            file1=str(ctx.baseline or ""),
+            file2=str(ctx.actual or ""),
+        )
+        result.identical = True
+        return result
+"""
+
+
+def _write_plugin(tmpd: str, filename: str, cls: str) -> Path:
+    plugin_file = Path(tmpd) / filename
+    plugin_file.write_text(_PLUGIN_BODY.format(cls=cls), encoding="utf-8")
+    return plugin_file
+
+
 class TestWorkspacePluginDiscovery:
-    """Test set_plugin_dirs, _load_from_dirs, and env var cross-process."""
+    """Test set_plugin_dirs, _load_from_dirs, and env-var input discovery."""
 
     def teardown_method(self):
         ComparatorFactory.reset()
@@ -18,36 +43,14 @@ def teardown_method(self):
     def test_set_plugin_dirs_and_discovery(self):
         """A *_comparator.py in a plugin dir is auto-registered."""
         with tempfile.TemporaryDirectory() as tmpd:
-            plugin_file = Path(tmpd) / "demo_comparator.py"
-            plugin_file.write_text("""
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator.result import ComparisonResult
-
-class DemoComparator(BaseComparator):
-    def read_content(self, fp, **kw):
-        return None
-    def compare_content(self, c1, c2):
-        return True, [], False
-""", encoding="utf-8")
-
+            _write_plugin(tmpd, "demo_comparator.py", "DemoComparator")
             ComparatorFactory.set_plugin_dirs([tmpd])
             assert "demo" in ComparatorFactory.get_available_comparators()
 
     def test_env_var_discovery(self):
         """Plugin dirs in CLITEST_PLUGIN_DIRS env var are discovered."""
         with tempfile.TemporaryDirectory() as tmpd:
-            plugin_file = Path(tmpd) / "envtest_comparator.py"
-            plugin_file.write_text("""
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator.result import ComparisonResult
-
-class EnvtestComparator(BaseComparator):
-    def read_content(self, fp, **kw):
-        return None
-    def compare_content(self, c1, c2):
-        return True, [], False
-""", encoding="utf-8")
-
+            _write_plugin(tmpd, "envtest_comparator.py", "EnvtestComparator")
             ComparatorFactory.reset()
             os.environ["CLITEST_PLUGIN_DIRS"] = tmpd
             try:
@@ -58,18 +61,7 @@ def compare_content(self, c1, c2):
     def test_set_plugin_dirs_before_init(self):
         """Calling set_plugin_dirs before first create_comparator still works."""
         with tempfile.TemporaryDirectory() as tmpd:
-            plugin_file = Path(tmpd) / "early_comparator.py"
-            plugin_file.write_text("""
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator.result import ComparisonResult
-
-class EarlyComparator(BaseComparator):
-    def read_content(self, fp, **kw):
-        return None
-    def compare_content(self, c1, c2):
-        return True, [], False
-""", encoding="utf-8")
-
+            _write_plugin(tmpd, "early_comparator.py", "EarlyComparator")
             ComparatorFactory.reset()
             ComparatorFactory.set_plugin_dirs([tmpd])
             # set_plugin_dirs before create_comparator should NOT trigger load yet
@@ -83,22 +75,26 @@ def test_empty_dirs_no_error(self):
         ComparatorFactory.get_available_comparators()  # must not raise
 
     def test_reset_clears_everything(self):
-        """reset() clears comparators, initialized flag, plugin_dirs, env var."""
+        """reset() clears comparators, initialized flag and plugin_dirs;
+        it never touches os.environ (CLITEST_PLUGIN_DIRS is user-owned)."""
         with tempfile.TemporaryDirectory() as tmpd:
-            plugin_file = Path(tmpd) / "reset_test_comparator.py"
-            plugin_file.write_text("""
-from symtest.file_comparator.base_comparator import BaseComparator
-from symtest.file_comparator.result import ComparisonResult
-
-class ResetTestComparator(BaseComparator):
-    def read_content(self, fp, **kw):
-        return None
-    def compare_content(self, c1, c2):
-        return True, [], False
-""", encoding="utf-8")
-
+            _write_plugin(tmpd, "reset_test_comparator.py", "ResetTestComparator")
             ComparatorFactory.set_plugin_dirs([tmpd])
             assert "resettest" in ComparatorFactory.get_available_comparators()
             ComparatorFactory.reset()
             assert "resettest" not in ComparatorFactory.get_available_comparators()
+
+    def test_framework_never_writes_environ(self):
+        """set_plugin_dirs / discovery must not mutate os.environ.
+
+        Process workers receive plugin dirs via the pool initializer —
+        the framework has no business writing to the process environment.
+        """
+        with tempfile.TemporaryDirectory() as tmpd:
+            _write_plugin(tmpd, "noenv_comparator.py", "NoenvComparator")
+            environ_before = dict(os.environ)
+            ComparatorFactory.set_plugin_dirs([tmpd])
+            ComparatorFactory.get_available_comparators()
+            ComparatorFactory.reset()
+            assert os.environ == environ_before
             assert "CLITEST_PLUGIN_DIRS" not in os.environ
diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py
index f3a109a..e0d95f5 100644
--- a/tests/unit/test_cli.py
+++ b/tests/unit/test_cli.py
@@ -635,17 +635,16 @@ def fake_run(args):
             cli.main()
         assert exc.value.code == 1
 
-    def test_main_tui(self, monkeypatch):
-        called = []
-
-        def fake_tui(args):
-            called.append("tui")
+    def test_main_find_match(self, monkeypatch):
+        def fake_find(args):
+            return 0
 
-        monkeypatch.setattr(cli, "run_tui", fake_tui)
-        monkeypatch.setattr("sys.argv", ["symtest", "tui", "cases.json"])
+        monkeypatch.setattr(cli, "run_find", fake_find)
+        monkeypatch.setattr("sys.argv", ["symtest", "find", "cases.json", "login"])
 
-        cli.main()
-        assert "tui" in called
+        with pytest.raises(SystemExit) as exc:
+            cli.main()
+        assert exc.value.code == 0
 
     def test_main_validate_success(self, monkeypatch):
         def fake_validate(args):
@@ -790,14 +789,27 @@ def test_validate_subcommand(self):
         assert args.config_file == "config.json"
         assert args.workspace == "/ws"
 
-    def test_tui_accepts_baseline_confirmation(self):
+    def test_find_subcommand(self):
         parser = cli.create_parser()
         args = parser.parse_args([
-            "tui", "config.json", "--update-baseline", "--yes",
+            "find", "main.json", "login",
+            "--mode", "regex", "--tag", "smoke",
+            "--workspace", "/ws", "--output-format", "json",
         ])
-        assert args.command == "tui"
-        assert args.update_baseline is True
-        assert args.yes is True
+        assert args.command == "find"
+        assert args.config_file == "main.json"
+        assert args.pattern == "login"
+        assert args.mode == "regex"
+        assert args.tag == ["smoke"]
+        assert args.workspace == "/ws"
+        assert args.output_format == "json"
+
+    def test_find_pattern_optional(self):
+        """Empty pattern lists all cases (substring matches everything)."""
+        parser = cli.create_parser()
+        args = parser.parse_args(["find", "main.json"])
+        assert args.command == "find"
+        assert args.pattern == ""
 
     def test_compare_subcommand(self):
         parser = cli.create_parser()
diff --git a/tests/unit/test_migrate.py b/tests/unit/test_migrate.py
index dfd59a2..145c7ee 100644
--- a/tests/unit/test_migrate.py
+++ b/tests/unit/test_migrate.py
@@ -8,6 +8,8 @@
     legacy config ──migrate──▶ new config ──new parser──▶ Normalized B
                                        断言 A == B
 
+3. 递归 import 树迁移：默认 .v2 副本 + 路径重写，--in-place 原地覆盖。
+
 语料：tests/fixtures/migration/v1/（tests/ 与 examples/ 存量 v1 配置的原件拷贝）。
 """
 
@@ -19,8 +21,9 @@
 
 from symtest.commands.migrate import run_migrate
 from symtest.config.migrate import migrate_case, migrate_config
+from symtest.config.normalize import normalize_draft_config
 from symtest.core.config_loader import parse_test_cases
-from symtest.core.test_case import TestCase, TestCaseStep
+from symtest.core.test_case import TestCase, TestStep
 
 V1_FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "migration" / "v1"
 
@@ -166,7 +169,7 @@ def _legacy_case_to_testcase(case):
     steps = None
     if "steps" in case:
         steps = [
-            TestCaseStep(
+            TestStep.from_flat(
                 command=s.get("command", ""),
                 args=s.get("args", []),
                 expected=s.get("expected", {}),
@@ -227,11 +230,12 @@ def test_migration_equivalence_invariant(path):
     # A 侧：legacy dict 经 TestCase 平铺 kwargs 构造（legacy 语义）→ to_dict()
     side_a = [_legacy_case_to_testcase(tc).to_dict() for tc in v1_cases]
 
-    # B 侧：migrate(legacy) 经生产 parse_test_cases → to_dict()
+    # B 侧：migrate(legacy) → draft normalize（迁移不补必填，宽松形态由
+    # DSL 层 normalize 承担）→ 生产 parse_test_cases → to_dict()
     migrated = migrate_config({"test_cases": v1_cases})
     side_b = [
         tc.to_dict()
-        for tc in parse_test_cases(migrated, strict=False)
+        for tc in parse_test_cases(normalize_draft_config(migrated))
     ]
 
     assert side_a == side_b
@@ -293,3 +297,194 @@ def test_migrate_unsupported_output_format_fails(self, tmp_path):
         assert run_migrate(
             self._args(src, output=tmp_path / "out.txt", workspace=str(tmp_path))
         ) is False
+
+
+# ---------------------------------------------------------------------------
+# 递归 import 树迁移（默认 .v2 副本 + 路径重写 / --in-place 原地覆盖）
+# ---------------------------------------------------------------------------
+
+def _v1_case(name):
+    return {
+        "name": name,
+        "command": "echo",
+        "args": [name],
+        "expected": {"return_code": 0},
+    }
+
+
+class TestRunMigrateTree:
+    def _args(self, config, output=None, workspace=None, in_place=False):
+        return argparse.Namespace(
+            config_file=str(config),
+            output=str(output) if output else None,
+            workspace=workspace,
+            in_place=in_place,
+        )
+
+    @staticmethod
+    def _read(path):
+        if path.suffix.lower() in (".yaml", ".yml"):
+            import yaml
+            return yaml.safe_load(path.read_text(encoding="utf-8"))
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def _three_level_tree(self, tmp_path):
+        """main.json -> sub.json -> subsub.json 三层 v1 import 树。"""
+        (tmp_path / "subsub.json").write_text(
+            json.dumps({"test_cases": [_v1_case("leaf")]}), encoding="utf-8")
+        (tmp_path / "sub.json").write_text(json.dumps({
+            "test_cases": [{"import": "subsub.json"}, _v1_case("mid")],
+        }), encoding="utf-8")
+        (tmp_path / "main.json").write_text(json.dumps({
+            "test_cases": [
+                {"import": "sub.json", "tags": ["api"]},
+                _v1_case("root"),
+            ],
+        }), encoding="utf-8")
+
+    def test_default_mode_migrates_whole_tree(self, tmp_path):
+        self._three_level_tree(tmp_path)
+        assert run_migrate(
+            self._args(tmp_path / "main.json", workspace=str(tmp_path))
+        ) is True
+
+        main_v2 = tmp_path / "main.v2.json"
+        sub_v2 = tmp_path / "sub.v2.json"
+        subsub_v2 = tmp_path / "subsub.v2.json"
+        for p in (main_v2, sub_v2, subsub_v2):
+            assert p.exists()
+
+        # 父文件 import 路径已重写为 .v2 名，tags 等其他字段保留
+        migrated_main = self._read(main_v2)
+        assert migrated_main["test_cases"][0]["import"] == "sub.v2.json"
+        assert migrated_main["test_cases"][0]["tags"] == ["api"]
+        assert migrated_main["test_cases"][1]["execution"]["command"] == "echo"
+        migrated_sub = self._read(sub_v2)
+        assert migrated_sub["test_cases"][0]["import"] == "subsub.v2.json"
+        assert self._read(subsub_v2)["test_cases"][0]["execution"]["args"] == ["leaf"]
+
+        # 原文件保持 v1 未动
+        for name in ("main.json", "sub.json", "subsub.json"):
+            for tc in self._read(tmp_path / name)["test_cases"]:
+                if "import" not in tc:
+                    assert "execution" not in tc
+
+    def test_in_place_overwrites_tree(self, tmp_path):
+        self._three_level_tree(tmp_path)
+        assert run_migrate(
+            self._args(tmp_path / "main.json",
+                       workspace=str(tmp_path), in_place=True)
+        ) is True
+
+        # 原文件原地变为 v2，import 路径不变，不产生 .v2 副本
+        migrated_main = self._read(tmp_path / "main.json")
+        assert migrated_main["test_cases"][0]["import"] == "sub.json"
+        assert migrated_main["test_cases"][1]["execution"]["command"] == "echo"
+        assert self._read(tmp_path / "sub.json")["test_cases"][0]["import"] \
+            == "subsub.json"
+        assert self._read(tmp_path / "subsub.json")["test_cases"][0] \
+            ["execution"]["args"] == ["leaf"]
+        assert not (tmp_path / "main.v2.json").exists()
+
+    def test_diamond_import_migrated_once(self, tmp_path):
+        (tmp_path / "d.json").write_text(
+            json.dumps({"test_cases": [_v1_case("shared")]}), encoding="utf-8")
+        for name in ("b.json", "c.json"):
+            (tmp_path / name).write_text(json.dumps(
+                {"test_cases": [{"import": "d.json"}]}), encoding="utf-8")
+        (tmp_path / "main.json").write_text(json.dumps({
+            "test_cases": [{"import": "b.json"}, {"import": "c.json"}],
+        }), encoding="utf-8")
+
+        assert run_migrate(
+            self._args(tmp_path / "main.json",
+                       workspace=str(tmp_path), in_place=True)
+        ) is True
+        # 菱形引用不误报循环，d.json 已迁移
+        assert self._read(tmp_path / "d.json")["test_cases"][0] \
+            ["execution"]["command"] == "echo"
+
+    def test_circular_import_writes_nothing(self, tmp_path):
+        (tmp_path / "a.json").write_text(
+            json.dumps({"test_cases": [{"import": "b.json"}]}), encoding="utf-8")
+        (tmp_path / "b.json").write_text(
+            json.dumps({"test_cases": [{"import": "a.json"}]}), encoding="utf-8")
+        snapshot = {p.name: p.read_text(encoding="utf-8") for p in tmp_path.iterdir()}
+
+        assert run_migrate(
+            self._args(tmp_path / "a.json", workspace=str(tmp_path))
+        ) is False
+        # 两阶段保证：任一失败不写任何文件
+        assert {p.name: p.read_text(encoding="utf-8") for p in tmp_path.iterdir()} \
+            == snapshot
+
+    def test_missing_import_writes_nothing(self, tmp_path):
+        (tmp_path / "main.json").write_text(
+            json.dumps({"test_cases": [{"import": "ghost.json"}]}),
+            encoding="utf-8")
+        before = (tmp_path / "main.json").read_text(encoding="utf-8")
+
+        assert run_migrate(
+            self._args(tmp_path / "main.json", workspace=str(tmp_path))
+        ) is False
+        assert (tmp_path / "main.json").read_text(encoding="utf-8") == before
+        assert not (tmp_path / "main.v2.json").exists()
+
+    def test_sub_without_test_cases_writes_nothing(self, tmp_path):
+        (tmp_path / "sub.json").write_text(
+            json.dumps({"setup": {}}), encoding="utf-8")
+        (tmp_path / "main.json").write_text(
+            json.dumps({"test_cases": [{"import": "sub.json"}]}),
+            encoding="utf-8")
+
+        assert run_migrate(
+            self._args(tmp_path / "main.json", workspace=str(tmp_path))
+        ) is False
+        assert not (tmp_path / "main.v2.json").exists()
+        assert not (tmp_path / "sub.v2.json").exists()
+
+    def test_output_and_in_place_conflict(self, tmp_path):
+        src = tmp_path / "old.json"
+        src.write_text(json.dumps({"test_cases": []}), encoding="utf-8")
+        assert run_migrate(self._args(
+            src, output=tmp_path / "new.json",
+            workspace=str(tmp_path), in_place=True,
+        )) is False
+        assert not (tmp_path / "new.json").exists()
+        assert json.loads(src.read_text(encoding="utf-8")) == {"test_cases": []}
+
+    def test_in_place_idempotent_on_v2_tree(self, tmp_path):
+        self._three_level_tree(tmp_path)
+        assert run_migrate(
+            self._args(tmp_path / "main.json",
+                       workspace=str(tmp_path), in_place=True)
+        ) is True
+        first_pass = {p.name: p.read_text(encoding="utf-8") for p in tmp_path.iterdir()}
+        assert run_migrate(
+            self._args(tmp_path / "main.json",
+                       workspace=str(tmp_path), in_place=True)
+        ) is True
+        assert {p.name: p.read_text(encoding="utf-8") for p in tmp_path.iterdir()} \
+            == first_pass
+
+    def test_mixed_json_yaml_tree(self, tmp_path):
+        (tmp_path / "sub.yaml").write_text(
+            "test_cases:\n"
+            "  - name: y\n"
+            "    command: echo\n"
+            "    args: []\n"
+            "    expected: {}\n",
+            encoding="utf-8",
+        )
+        (tmp_path / "main.json").write_text(
+            json.dumps({"test_cases": [{"import": "sub.yaml"}]}),
+            encoding="utf-8")
+
+        assert run_migrate(
+            self._args(tmp_path / "main.json", workspace=str(tmp_path))
+        ) is True
+        assert (tmp_path / "sub.v2.yaml").exists()
+        assert self._read(tmp_path / "sub.v2.yaml")["test_cases"][0] \
+            ["execution"]["command"] == "echo"
+        assert self._read(tmp_path / "main.v2.json")["test_cases"][0]["import"] \
+            == "sub.v2.yaml"
diff --git a/tests/unit/tui/__init__.py b/tests/unit/tui/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/tests/unit/tui/conftest.py b/tests/unit/tui/conftest.py
deleted file mode 100644
index b2a4083..0000000
--- a/tests/unit/tui/conftest.py
+++ /dev/null
@@ -1,73 +0,0 @@
-"""Async fixtures for TUI run_test() tests."""
-
-import pytest
-from pathlib import Path
-from unittest.mock import patch
-
-from symtest.core.test_case import TestCase, TestCaseStep
-from symtest.tui.controllers.case_controller import CaseController
-
-
-@pytest.fixture
-def sample_cases():
-    """Return a list of sample TestCase objects for testing."""
-    return [
-        TestCase(name="echo_hello", command="echo", args=["hello"],
-                 expected={"return_code": 0}, tags=["smoke"], description="A simple echo test"),
-        TestCase(name="python_script", command="python", args=["-c", "print('hi')"],
-                 expected={"output_contains": ["hi"]}, tags=["regression"], description=""),
-        TestCase(
-            name="multi_step",
-            steps=[
-                TestCaseStep(command="echo", args=["step1"], expected={"return_code": 0}),
-                TestCaseStep(command="echo", args=["step2"], expected={"return_code": 0}),
-            ],
-            tags=["seq"], description="A sequence test case",
-        ),
-    ]
-
-
-@pytest.fixture
-def sample_config(tmp_path, sample_cases):
-    """Create a temporary JSON config file with sample cases."""
-    import json
-    config = tmp_path / "cases.json"
-    config_content = {
-        "test_cases": [
-            {
-                "name": "echo_hello",
-                "execution": {"command": "echo", "args": ["hello"]},
-                "expected": {"return_code": 0},
-                "tags": ["smoke"],
-                "description": "A simple echo test",
-            },
-            {
-                "name": "python_script",
-                "execution": {"command": "python", "args": ["-c", "print('hi')"]},
-                "expected": {"output_contains": ["hi"]},
-                "tags": ["regression"],
-                "description": "",
-            },
-            {
-                "name": "multi_step",
-                "execution": {
-                    "steps": [
-                        {"command": "echo", "args": ["step1"], "expected": {"return_code": 0}},
-                        {"command": "echo", "args": ["step2"], "expected": {"return_code": 0}},
-                    ],
-                },
-                "tags": ["seq"],
-                "description": "A sequence test case",
-            },
-        ],
-    }
-    config.write_text(json.dumps(config_content), encoding="utf-8")
-    return config
-
-
-@pytest.fixture
-def loaded_controller(sample_config):
-    """Return a CaseController loaded with sample cases."""
-    ctrl = CaseController()
-    ctrl.load(str(sample_config))
-    return ctrl
diff --git a/tests/unit/tui/test_app.py b/tests/unit/tui/test_app.py
deleted file mode 100644
index 72b7e46..0000000
--- a/tests/unit/tui/test_app.py
+++ /dev/null
@@ -1,106 +0,0 @@
-"""Tests for TUI app entry point and CLI integration."""
-
-import sys
-import io
-import argparse
-from unittest.mock import patch
-
-import pytest
-
-from symtest.tui.app import run_tui, CaseManagerApp
-from symtest.tui.controllers.case_controller import CaseController
-
-
-# ---------------------------------------------------------------------------
-# run_tui — missing textual
-# ---------------------------------------------------------------------------
-
-
-class TestRunTuiMissingTextual:
-    def test_exits_with_friendly_message(self, monkeypatch):
-        """When textual is not installed, print help and exit(1)."""
-        # Remove the real textual from sys.modules so the import fails
-        monkeypatch.setitem(sys.modules, "textual", None)
-
-        # We need to force ImportError on import textual
-        import builtins
-        original_import = builtins.__import__
-
-        def fake_import(name, *args, **kwargs):
-            if name == "textual" or name.startswith("textual."):
-                raise ImportError("No module named 'textual'")
-            return original_import(name, *args, **kwargs)
-
-        monkeypatch.setattr(builtins, "__import__", fake_import)
-
-        buf = io.StringIO()
-        monkeypatch.setattr(sys, "stdout", buf)
-
-        with pytest.raises(SystemExit) as exc:
-            run_tui("dummy.json")
-
-        assert exc.value.code == 1
-        output = buf.getvalue()
-        assert "TUI" in output or "textual" in output.lower()
-
-
-# ---------------------------------------------------------------------------
-# CaseManagerApp construction
-# ---------------------------------------------------------------------------
-
-
-class TestCaseManagerApp:
-    def test_app_creates_controller(self):
-        app = CaseManagerApp("test_config.json")
-        assert isinstance(app._controller, CaseController)
-        assert app._config_file == "test_config.json"
-        assert app._workspace is None
-
-    def test_app_with_workspace(self):
-        app = CaseManagerApp("config.yaml", workspace="/tmp")
-        assert app._workspace == "/tmp"
-
-    def test_app_title(self):
-        app = CaseManagerApp("config.json")
-        assert "Case Manager" in app.TITLE
-
-
-# ---------------------------------------------------------------------------
-# CLI argument parsing for TUI subcommand
-# ---------------------------------------------------------------------------
-
-
-class TestTuiCLIArgs:
-    """Test that the 'tui' subcommand is properly registered in the parser."""
-
-    def _build_parser(self):
-        """Replicate the parser setup from cli.py (the relevant parts)."""
-        parser = argparse.ArgumentParser(prog="symtest")
-        subparsers = parser.add_subparsers(dest="command")
-
-        tui_parser = subparsers.add_parser(
-            "tui", help="Launch interactive TUI for managing test cases"
-        )
-        tui_parser.add_argument(
-            "config_file", help="Path to the test configuration file (JSON or YAML)"
-        )
-        tui_parser.add_argument("--workspace", "-w", help="Working directory")
-        return parser
-
-    def test_tui_with_config_file(self):
-        parser = self._build_parser()
-        args = parser.parse_args(["tui", "cases.json"])
-        assert args.command == "tui"
-        assert args.config_file == "cases.json"
-        assert args.workspace is None
-
-    def test_tui_with_workspace(self):
-        parser = self._build_parser()
-        args = parser.parse_args(["tui", "cases.yaml", "--workspace", "/home/project"])
-        assert args.config_file == "cases.yaml"
-        assert args.workspace == "/home/project"
-
-    def test_tui_with_short_workspace_flag(self):
-        parser = self._build_parser()
-        args = parser.parse_args(["tui", "config.json", "-w", "/tmp/ws"])
-        assert args.workspace == "/tmp/ws"
diff --git a/tests/unit/tui/test_case_controller.py b/tests/unit/tui/test_case_controller.py
deleted file mode 100644
index 3393405..0000000
--- a/tests/unit/tui/test_case_controller.py
+++ /dev/null
@@ -1,433 +0,0 @@
-"""Tests for CaseController — CRUD, search, tags, load, save."""
-
-from pathlib import Path
-import tempfile
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from symtest.core.test_case import TestCase, TestCaseStep
-from symtest.core.config_loader import parse_test_cases
-from symtest.tui.controllers.case_controller import CaseController
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _tc(**kwargs) -> TestCase:
-    defaults = {"name": "tc", "command": "echo", "args": ["hi"],
-                "expected": {}, "tags": [], "description": ""}
-    defaults.update(kwargs)
-    return TestCase(**defaults)
-
-
-def _seq_tc(steps=None, **kwargs) -> TestCase:
-    defaults = {"name": "seq_tc", "steps": steps or [],
-                "description": "", "tags": []}
-    defaults.update(kwargs)
-    return TestCase(**defaults)
-
-
-def _step(cmd="echo", args=None, expected=None) -> TestCaseStep:
-    return TestCaseStep(command=cmd,
-                        args=args or [],
-                        expected=expected or {})
-
-
-# ---------------------------------------------------------------------------
-# Initialisation
-# ---------------------------------------------------------------------------
-
-
-class TestControllerInit:
-    def test_initial_state(self):
-        ctrl = CaseController()
-        assert ctrl.cases == []
-        assert ctrl.case_count == 0
-        assert ctrl.file_path is None
-        assert ctrl.workspace is None
-        assert ctrl.dirty is False
-        assert ctrl.file_name == "(untitled)"
-
-
-# ---------------------------------------------------------------------------
-# Load / Save
-# ---------------------------------------------------------------------------
-
-
-class TestControllerLoad:
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    def test_load_single_cmd_cases(self, mock_load):
-        mock_load.return_value = {
-            "test_cases": [
-                {"name": "tc1", "execution": {"command": "echo", "args": ["hi"]},
-                 "expected": {"return_code": 0}, "tags": ["smoke"]},
-                {"name": "tc2", "execution": {"command": "ls", "args": ["-la"]},
-                 "expected": {}, "tags": []},
-            ]
-        }
-        ctrl = CaseController()
-        count = ctrl.load("dummy.json")
-        assert count == 2
-        assert ctrl.case_count == 2
-        assert ctrl.file_name == "dummy.json"
-        assert ctrl.dirty is False
-
-        assert ctrl.cases[0].name == "tc1"
-        assert ctrl.cases[0].command == "echo"
-        assert ctrl.cases[0].tags == ["smoke"]
-
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    def test_load_sequence_cases(self, mock_load):
-        mock_load.return_value = {
-            "test_cases": [
-                {"name": "multi_step",
-                 "execution": {
-                     "steps": [
-                         {"command": "echo", "args": ["1"], "expected": {}},
-                         {"command": "echo", "args": ["2"], "expected": {}},
-                     ],
-                 },
-                 "tags": ["seq"]},
-            ]
-        }
-        ctrl = CaseController()
-        ctrl.load("seq.json")
-        assert ctrl.case_count == 1
-        assert ctrl.cases[0].steps is not None
-        assert len(ctrl.cases[0].steps) == 2
-        assert ctrl.cases[0].steps[0].command == "echo"
-
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    def test_load_preserves_setup(self, mock_load):
-        mock_load.return_value = {
-            "setup": {"workspace": "/tmp"},
-            "test_cases": [{"name": "tc1", "execution": {"command": "echo", "args": []},
-                            "expected": {}}],
-        }
-        ctrl = CaseController()
-        ctrl.load("with_setup.json")
-        # Setup is stored internally for re-serialisation
-        assert ctrl._setup == {"workspace": "/tmp"}
-
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    def test_load_stores_workspace(self, mock_load):
-        mock_load.return_value = {"test_cases": []}
-        ctrl = CaseController()
-        ctrl.load("d.json", workspace="/my/workspace")
-        assert ctrl.workspace == "/my/workspace"
-
-
-class TestControllerSave:
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    @patch("symtest.tui.controllers.case_controller.save_config")
-    def test_save_writes_cases(self, mock_save, mock_load):
-        mock_load.return_value = {
-            "test_cases": [
-                {"name": "tc1", "execution": {"command": "echo", "args": []},
-                 "expected": {}, "tags": []},
-            ]
-        }
-        ctrl = CaseController()
-        ctrl.load("dummy.json")
-        mock_save.reset_mock()
-
-        ctrl.add_case(_tc(name="new_case"))
-        ctrl.save()
-
-        mock_save.assert_called_once()
-        args = mock_save.call_args[0]
-        config_dict = args[0]
-        assert len(config_dict["test_cases"]) == 2
-        assert ctrl.dirty is False
-
-    @patch("symtest.tui.controllers.case_controller.load_config")
-    @patch("symtest.tui.controllers.case_controller.save_config")
-    def test_save_as_new_path(self, mock_save, mock_load):
-        mock_load.return_value = {"test_cases": []}
-        ctrl = CaseController()
-        ctrl.load("original.json")
-        mock_save.reset_mock()
-
-        ctrl.save_as("new_path.json")
-        mock_save.assert_called_once()
-        assert ctrl.file_name == "new_path.json"
-
-    def test_save_without_file_path_raises(self):
-        ctrl = CaseController()
-        with pytest.raises(ValueError, match="No file path"):
-            ctrl.save()
-
-
-# ---------------------------------------------------------------------------
-# CRUD
-# ---------------------------------------------------------------------------
-
-
-class TestControllerCRUD:
-    @pytest.fixture
-    def ctrl(self):
-        c = CaseController()
-        c._cases = [
-            _tc(name="tc0"),
-            _tc(name="tc1"),
-            _tc(name="tc2"),
-        ]
-        c._dirty = False
-        return c
-
-    def test_get_case(self, ctrl):
-        assert ctrl.get_case(1).name == "tc1"
-
-    def test_get_case_out_of_range_raises(self, ctrl):
-        with pytest.raises(IndexError):
-            ctrl.get_case(10)
-
-    def test_add_case(self, ctrl):
-        idx = ctrl.add_case(_tc(name="new"))
-        assert idx == 3
-        assert ctrl.case_count == 4
-        assert ctrl.dirty is True
-
-    def test_update_case(self, ctrl):
-        new_tc = _tc(name="updated")
-        ctrl.update_case(1, new_tc)
-        assert ctrl.cases[1].name == "updated"
-        assert ctrl.dirty is True
-
-    def test_delete_case(self, ctrl):
-        ctrl.delete_case(1)
-        assert ctrl.case_count == 2
-        assert ctrl.cases[0].name == "tc0"
-        assert ctrl.cases[1].name == "tc2"
-        assert ctrl.dirty is True
-
-    def test_duplicate_case(self, ctrl):
-        new_idx = ctrl.duplicate_case(0)
-        assert ctrl.case_count == 4
-        assert ctrl.cases[new_idx].name == "tc0_copy"
-        # Should be a deep copy, not the same object
-        assert ctrl.cases[new_idx] is not ctrl.cases[0]
-        assert ctrl.dirty is True
-
-    def test_move_case_forward(self, ctrl):
-        ctrl.move_case(0, 2)
-        assert [tc.name for tc in ctrl.cases] == ["tc1", "tc2", "tc0"]
-
-    def test_move_case_backward(self, ctrl):
-        ctrl.move_case(2, 0)
-        assert [tc.name for tc in ctrl.cases] == ["tc2", "tc0", "tc1"]
-
-    def test_move_case_noop(self, ctrl):
-        ctrl.move_case(1, 1)
-        assert [tc.name for tc in ctrl.cases] == ["tc0", "tc1", "tc2"]
-        # No-op should NOT set dirty
-        assert ctrl.dirty is False
-
-    def test_swap_cases(self, ctrl):
-        ctrl.swap_cases(0, 2)
-        assert [tc.name for tc in ctrl.cases] == ["tc2", "tc1", "tc0"]
-        assert ctrl.dirty is True
-
-
-# ---------------------------------------------------------------------------
-# Search
-# ---------------------------------------------------------------------------
-
-
-class TestControllerSearch:
-    @pytest.fixture
-    def ctrl(self):
-        c = CaseController()
-        c._cases = [
-            _tc(name="alpha", command="echo", args=["a"], tags=["smoke"],
-                description="first test"),
-            _tc(name="beta", command="python", args=["-c", "pass"],
-                tags=["regression"], description="second test"),
-            _tc(name="gamma", command="echo", args=["g"],
-                tags=["smoke", "slow"], description=""),
-        ]
-        return c
-
-    def test_substring_search(self, ctrl):
-        indices = ctrl.search("echo")
-        assert indices == [0, 2]
-
-    def test_substring_search_in_name(self, ctrl):
-        indices = ctrl.search("alpha")
-        assert indices == [0]
-
-    def test_substring_search_in_description(self, ctrl):
-        indices = ctrl.search("first")
-        assert indices == [0]
-
-    def test_substring_search_no_match(self, ctrl):
-        indices = ctrl.search("nonexistent")
-        assert indices == []
-
-    def test_fuzzy_search(self, ctrl):
-        indices = ctrl.search("alpha", mode="fuzzy")
-        assert 0 in indices
-
-    def test_regex_search(self, ctrl):
-        indices = ctrl.search(r"^echo$", mode="regex")
-        assert indices == [0, 2]
-
-    def test_search_with_tag_filter(self, ctrl):
-        indices = ctrl.search("echo", tag="slow")
-        assert indices == [2]
-
-    def test_search_tag_filter_no_match(self, ctrl):
-        indices = ctrl.search("echo", tag="regression")
-        assert indices == []
-
-    def test_empty_query_matches_all(self, ctrl):
-        indices = ctrl.search("")
-        assert len(indices) == 3
-
-    def test_invalid_regex_returns_empty(self, ctrl):
-        indices = ctrl.search("[unclosed", mode="regex")
-        # Invalid regex causes each _regex_match to return False
-        assert indices == []
-
-
-# ---------------------------------------------------------------------------
-# Tags
-# ---------------------------------------------------------------------------
-
-
-class TestControllerTags:
-    def test_get_all_tags(self):
-        ctrl = CaseController()
-        ctrl._cases = [
-            _tc(name="a", tags=["smoke", "fast"]),
-            _tc(name="b", tags=["slow"]),
-            _tc(name="c", tags=["smoke", "regression"]),
-        ]
-        tags = ctrl.get_all_tags()
-        assert tags == ["fast", "regression", "slow", "smoke"]
-
-    def test_get_all_tags_empty(self):
-        ctrl = CaseController()
-        ctrl._cases = []
-        assert ctrl.get_all_tags() == []
-
-    def test_get_all_tags_no_tags(self):
-        ctrl = CaseController()
-        ctrl._cases = [_tc(name="a", tags=[])]
-        assert ctrl.get_all_tags() == []
-
-
-# ---------------------------------------------------------------------------
-# Create Empty Case
-# ---------------------------------------------------------------------------
-
-
-class TestCreateEmptyCase:
-    def test_single_mode(self):
-        tc = CaseController.create_empty_case("single")
-        assert tc.name == "new_case"
-        assert tc.command == ""
-        assert tc.args == []
-        assert tc.expected == {}
-        assert tc.steps is None
-
-    def test_sequence_mode(self):
-        tc = CaseController.create_empty_case("sequence")
-        assert tc.name == "new_case"
-        assert tc.steps == []
-        assert tc.command == ""
-
-    def test_default_is_single(self):
-        tc = CaseController.create_empty_case()
-        assert tc.steps is None
-        assert tc.command == ""
-
-
-# ---------------------------------------------------------------------------
-# Dirty flag
-# ---------------------------------------------------------------------------
-
-
-class TestDirtyFlag:
-    def test_load_resets_dirty(self):
-        ctrl = CaseController()
-        ctrl._dirty = True
-        with patch("symtest.tui.controllers.case_controller.load_config",
-                   return_value={"test_cases": []}):
-            ctrl.load("dummy.json")
-        assert ctrl.dirty is False
-
-    def test_save_resets_dirty(self):
-        ctrl = CaseController()
-        ctrl._file_path = Path("/tmp/test.json")
-        ctrl._dirty = True
-        with patch("symtest.tui.controllers.case_controller.save_config"):
-            ctrl.save()
-        assert ctrl.dirty is False
-
-
-# ---------------------------------------------------------------------------
-# Parse from dict (static method)
-# ---------------------------------------------------------------------------
-
-
-class TestParseFromDict:
-    """TUI 侧显式宽松形态（1.4 原则 6：strict=False，非隐式 workspace 嗅探）。"""
-
-    def test_single_cmd_case(self):
-        result = parse_test_cases({"test_cases": [
-            {"name": "simple", "execution": {"command": "echo", "args": ["hello"]},
-             "expected": {"return_code": 0}, "tags": ["demo"]},
-        ]}, strict=False)
-        assert len(result) == 1
-        tc = result[0]
-        assert tc.name == "simple"
-        assert tc.command == "echo"
-        assert tc.steps is None
-        assert tc.tags == ["demo"]
-
-    def test_sequence_case(self):
-        result = parse_test_cases({"test_cases": [
-            {"name": "seq",
-             "execution": {
-                 "steps": [
-                     {"command": "step1", "args": ["a"], "expected": {}},
-                     {"command": "step2", "args": ["b"], "expected": {"return_code": 1}},
-                 ],
-             }},
-        ]}, strict=False)
-        assert len(result) == 1
-        tc = result[0]
-        assert tc.name == "seq"
-        assert tc.steps is not None
-        assert len(tc.steps) == 2
-        assert tc.steps[1].command == "step2"
-        assert tc.steps[1].expected == {"return_code": 1}
-
-    def test_missing_fields_get_defaults(self):
-        result = parse_test_cases({"test_cases": [
-            {"name": "minimal"},
-        ]}, strict=False)
-        tc = result[0]
-        assert tc.command == ""
-        assert tc.args == []
-        assert tc.expected == {}
-        assert tc.tags == []
-        assert tc.description == ""
-
-    def test_empty_list(self):
-        assert parse_test_cases({"test_cases": []}) == []
-
-    def test_step_timeout(self):
-        result = parse_test_cases({"test_cases": [
-            {"name": "with_timeout",
-             "execution": {
-                 "steps": [{"command": "sleep", "args": ["10"], "expected": {},
-                            "timeout": 30.0}],
-             }},
-        ]}, strict=False)
-        tc = result[0]
-        assert tc.steps[0].timeout == 30.0
diff --git a/tests/unit/tui/test_search_functions.py b/tests/unit/tui/test_search_functions.py
deleted file mode 100644
index db5f2e0..0000000
--- a/tests/unit/tui/test_search_functions.py
+++ /dev/null
@@ -1,187 +0,0 @@
-"""Tests for TUI search helper functions."""
-
-import pytest
-
-from symtest.core.test_case import TestCase
-from symtest.tui.controllers.case_controller import (
-    _substring_match,
-    _regex_match,
-    _fuzzy_score,
-    _fuzzy_match,
-)
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _tc(**kwargs) -> TestCase:
-    """Shorthand to create a TestCase with defaults."""
-    defaults = {
-        "name": "test",
-        "command": "",
-        "args": [],
-        "expected": {},
-        "tags": [],
-        "description": "",
-    }
-    defaults.update(kwargs)
-    return TestCase(**defaults)
-
-
-# ---------------------------------------------------------------------------
-# _substring_match
-# ---------------------------------------------------------------------------
-
-
-class TestSubstringMatch:
-    def test_match_in_name(self):
-        assert _substring_match("hello", _tc(name="hello_world"))
-
-    def test_match_case_insensitive(self):
-        assert _substring_match("HELLO", _tc(name="hello_world"))
-
-    def test_match_in_command(self):
-        assert _substring_match("python", _tc(command="python3"))
-
-    def test_match_in_args(self):
-        assert _substring_match("script", _tc(args=["run", "script.py"]))
-
-    def test_match_in_tags(self):
-        assert _substring_match("smoke", _tc(tags=["smoke", "regression"]))
-
-    def test_match_in_description(self):
-        assert _substring_match("important", _tc(description="An important test"))
-
-    def test_no_match(self):
-        assert not _substring_match("xyz123", _tc(name="hello"))
-
-    def test_empty_query_matches_all(self):
-        """Empty string is contained in every string."""
-        assert _substring_match("", _tc(name="hello"))
-
-    def test_query_with_dot_literal(self):
-        """Dot is a literal char, not a regex wildcard in substring mode."""
-        assert _substring_match("test_case", _tc(name="my_test_case_extra"))
-
-
-# ---------------------------------------------------------------------------
-# _regex_match
-# ---------------------------------------------------------------------------
-
-
-class TestRegexMatch:
-    def test_simple_regex(self):
-        assert _regex_match(r"test\d", _tc(name="test1"))
-
-    def test_regex_case_insensitive(self):
-        assert _regex_match(r"HELLO", _tc(name="hello_world"))
-
-    def test_regex_in_command(self):
-        assert _regex_match(r"python\d", _tc(command="python3"))
-
-    def test_regex_in_tags(self):
-        assert _regex_match(r"smoke|reg", _tc(tags=["smoke_test"]))
-
-    def test_regex_no_match(self):
-        assert not _regex_match(r"test\d", _tc(name="hello"))
-
-    def test_invalid_regex_returns_false(self):
-        """Malformed regex should not raise, just return False."""
-        assert not _regex_match(r"[unclosed", _tc(name="hello"))
-
-    def test_full_match_pattern(self):
-        """^ and $ anchors should work."""
-        assert _regex_match(r"^hello$", _tc(name="hello"))
-        assert not _regex_match(r"^hello$", _tc(name="hello_world"))
-
-    def test_multiline_description(self):
-        assert _regex_match(r"line2", _tc(description="line1\nline2\nline3"))
-
-
-# ---------------------------------------------------------------------------
-# _fuzzy_score
-# ---------------------------------------------------------------------------
-
-
-class TestFuzzyScore:
-    def test_exact_match_scores_high(self):
-        score = _fuzzy_score("hello", _tc(name="hello"))
-        assert score > 0.5
-
-    def test_no_match_scores_zero(self):
-        score = _fuzzy_score("xyz", _tc(name="abcdef"))
-        assert score == 0.0
-
-    def test_partial_overlap(self):
-        score = _fuzzy_score("hel", _tc(name="hello"))
-        assert score > 0.0
-
-    def test_name_weights_more_than_args(self):
-        score_name = _fuzzy_score("script", _tc(name="script_runner"))
-        score_args = _fuzzy_score("script", _tc(name="other", args=["script.py"]))
-        assert score_name > score_args
-
-    def test_two_char_partial_overlap(self):
-        """Two-char prefix matches first bigram."""
-        score = _fuzzy_score("he", _tc(name="hello"))
-        assert score > 0.0
-
-    def test_empty_query_scores_zero(self):
-        score = _fuzzy_score("", _tc(name="hello"))
-        assert score == 0.0
-
-    def test_score_is_non_negative(self):
-        score = _fuzzy_score("zxy", _tc(name="abc"))
-        assert score >= 0.0
-
-
-# ---------------------------------------------------------------------------
-# _fuzzy_match
-# ---------------------------------------------------------------------------
-
-
-class TestFuzzyMatch:
-    def test_returns_matching_indices(self):
-        cases = [
-            _tc(name="hello_world"),
-            _tc(name="goodbye"),
-            _tc(name="hello_again"),
-        ]
-        indices = _fuzzy_match("hello", cases)
-        assert 0 in indices
-        assert 2 in indices
-        assert 1 not in indices
-
-    def test_returns_sorted_by_score(self):
-        cases = [
-            _tc(name="abc"),
-            _tc(name="document", description="test_and_more"),
-            _tc(name="test_and_more"),
-        ]
-        indices = _fuzzy_match("test", cases)
-        # Case[2] matches in name (weight 2.0) > Case[1] matches only in desc (weight 1.0)
-        assert indices[0] == 2
-
-    def test_threshold_filters_low_scores(self):
-        cases = [
-            _tc(name="hello"),
-            _tc(name="h_xx_e_xx_l_xx_l_xx_o"),  # Low bigram overlap
-        ]
-        indices = _fuzzy_match("hello", cases, threshold=0.5)
-        assert 0 in indices
-        assert 1 not in indices
-
-    def test_low_threshold_includes_more(self):
-        cases = [_tc(name="hello"), _tc(name="zzz")]
-        indices = _fuzzy_match("hello", cases, threshold=0.0)
-        assert len(indices) >= 1
-
-    def test_empty_cases(self):
-        assert _fuzzy_match("hello", []) == []
-
-    def test_all_below_threshold(self):
-        cases = [_tc(name="a"), _tc(name="b")]
-        indices = _fuzzy_match("xyz", cases, threshold=0.5)
-        assert indices == []
diff --git a/tests/unit/tui/test_tui_run_test.py b/tests/unit/tui/test_tui_run_test.py
deleted file mode 100644
index 80b5207..0000000
--- a/tests/unit/tui/test_tui_run_test.py
+++ /dev/null
@@ -1,384 +0,0 @@
-"""TUI tests using Textual's app.run_test() async Pilot.
-
-These tests exercise widgets and screens in a real (but headless) Textual app.
-Requires: textual, pytest-asyncio.
-"""
-
-import pytest
-
-from symtest.tui.app import CaseManagerApp
-from symtest.tui.screens.case_list import CaseListScreen
-from symtest.tui.screens.case_editor import CaseEditorScreen
-from symtest.tui.widgets.search_bar import SearchBar
-from symtest.tui.widgets.case_table import CaseTable
-from symtest.tui.widgets.steps_editor import StepsEditor
-from symtest.tui.widgets.expected_editor import ExpectedEditor
-from symtest.core.test_case import TestCase, TestCaseStep
-
-
-# =============================================================================
-# App construction & basic mount
-# =============================================================================
-
-
-class TestAppConstruction:
-    """Test that the app can be constructed and mounted via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_app_starts_and_shows_case_list(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            # App should have mounted and pushed a CaseListScreen
-            assert isinstance(pilot.app.screen, CaseListScreen)
-            # Case table should be populated
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            assert table.row_count > 0
-
-    @pytest.mark.asyncio
-    async def test_app_with_workspace(self, sample_config):
-        app = CaseManagerApp(str(sample_config), workspace="/tmp/test_ws")
-        async with app.run_test() as pilot:
-            assert isinstance(pilot.app.screen, CaseListScreen)
-
-    @pytest.mark.asyncio
-    async def test_app_title_set(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test():
-            assert "Case Manager" in app.TITLE
-
-
-# =============================================================================
-# CaseListScreen — search
-# =============================================================================
-
-
-class TestCaseListSearch:
-    """Test search bar interaction in CaseListScreen via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_search_filters_table(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            original_rows = table.row_count
-
-            # Focus search and type query
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-            search_input = search_bar.query_one("#search-input")
-            search_input.focus()
-            await pilot.press("e", "c", "h", "o")  # type "echo"
-
-            # This should filter to only matching cases
-            await pilot.pause()
-
-            # After search, the table should have filtered results
-            screen = pilot.app.screen
-            assert isinstance(screen, CaseListScreen)
-            # filtered_indices should be ≤ original
-            assert len(screen._filtered_indices) <= original_rows
-
-    @pytest.mark.asyncio
-    async def test_search_clear_restores_all(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            original_rows = table.row_count
-
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-            search_input = search_bar.query_one("#search-input")
-            search_input.focus()
-            await pilot.press("z", "z", "z", "n", "o", "m", "a", "t", "c", "h")
-
-            await pilot.pause()
-
-            # Clear search
-            screen = pilot.app.screen
-            screen.action_clear_search()
-            await pilot.pause()
-
-            assert len(screen._filtered_indices) == original_rows
-
-    @pytest.mark.asyncio
-    async def test_toggle_search_mode_fuzzy(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-
-            # Toggle to fuzzy mode
-            screen = pilot.app.screen
-            screen.action_toggle_fuzzy()
-            await pilot.pause()
-
-            assert search_bar.mode == "fuzzy"
-
-    @pytest.mark.asyncio
-    async def test_toggle_search_mode_regex(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-
-            screen = pilot.app.screen
-            screen.action_toggle_regex()
-            await pilot.pause()
-
-            assert search_bar.mode == "regex"
-
-
-# =============================================================================
-# CaseListScreen — CRUD actions
-# =============================================================================
-
-
-class TestCaseListActions:
-    """Test CRUD actions via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_add_case_opens_editor(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            screen = pilot.app.screen
-            screen.action_add_case()
-            await pilot.pause()
-
-            # Should have pushed CaseEditorScreen
-            assert isinstance(pilot.app.screen, CaseEditorScreen)
-
-    @pytest.mark.asyncio
-    async def test_delete_case(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            screen = pilot.app.screen
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            original_count = len(pilot.app.screen._ctrl.cases)
-
-            # Ensure cursor is on first row
-            assert table.row_count > 0
-
-            screen.action_delete_case()
-            await pilot.pause()
-
-            assert len(screen._ctrl.cases) == original_count - 1
-
-    @pytest.mark.asyncio
-    async def test_edit_case_opens_editor_with_data(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            screen = pilot.app.screen
-            screen.action_edit_case()
-            await pilot.pause()
-
-            # Should have pushed CaseEditorScreen with pre-populated data
-            assert isinstance(pilot.app.screen, CaseEditorScreen)
-
-    @pytest.mark.asyncio
-    async def test_duplicate_case(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            screen = pilot.app.screen
-            original_count = len(screen._ctrl.cases)
-
-            screen.action_duplicate_case()
-            await pilot.pause()
-
-            assert len(screen._ctrl.cases) == original_count + 1
-            # The duplicated case's name should end with "_copy"
-            last_case = screen._ctrl.cases[-1]
-            assert "_copy" in last_case.name
-
-
-# =============================================================================
-# CaseEditorScreen — construction & compose
-# =============================================================================
-
-
-class TestCaseEditorScreen:
-    """Test CaseEditorScreen via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_compose_new_case(self, sample_config):
-        """App mounting a CaseEditorScreen for a new case."""
-        app = CaseManagerApp(str(sample_config))
-
-        async with app.run_test() as pilot:
-            # Push editor for new case
-            pilot.app.push_screen(CaseEditorScreen())
-            await pilot.pause()
-
-            assert isinstance(pilot.app.screen, CaseEditorScreen)
-
-    @pytest.mark.asyncio
-    async def test_compose_with_existing_case(self, sample_config):
-        """App mounting a CaseEditorScreen with an existing case."""
-        app = CaseManagerApp(str(sample_config))
-        existing_case = TestCase(
-            name="existing_test",
-            command="python",
-            args=["-m", "test"],
-            expected={"return_code": 0},
-            tags=["smoke"],
-        )
-
-        async with app.run_test() as pilot:
-            pilot.app.push_screen(CaseEditorScreen(existing_case))
-            await pilot.pause()
-
-            assert isinstance(pilot.app.screen, CaseEditorScreen)
-
-    @pytest.mark.asyncio
-    async def test_cancel_dismisses_editor(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-
-        async with app.run_test() as pilot:
-            pilot.app.push_screen(CaseEditorScreen())
-            await pilot.pause()
-
-            # Press Cancel button
-            await pilot.click("#btn-cancel")
-            await pilot.pause()
-
-            # Should be back to CaseListScreen
-            assert isinstance(pilot.app.screen, CaseListScreen)
-
-    @pytest.mark.asyncio
-    async def test_switch_mode_button(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-
-        async with app.run_test() as pilot:
-            pilot.app.push_screen(CaseEditorScreen())
-            await pilot.pause()
-
-            # Click the switch mode button
-            await pilot.click("#btn-switch-mode")
-            await pilot.pause()
-
-            editor = pilot.app.screen
-            assert editor._is_sequence is True
-
-
-# =============================================================================
-# StepsEditor in mounted context
-# =============================================================================
-
-
-class TestStepsEditorMounted:
-    """Test StepsEditor widget when mounted via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_load_refreshes_list(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-
-        async with app.run_test() as pilot:
-            pilot.app.push_screen(CaseEditorScreen())
-            await pilot.pause()
-
-            # Switch to sequence mode
-            await pilot.click("#btn-switch-mode")
-            await pilot.pause()
-
-            steps_editor = pilot.app.screen.query_one("#steps-editor", StepsEditor)
-            assert steps_editor._steps == []
-
-            # Load steps via the widget API
-            steps = [
-                TestCaseStep(command="step1", args=["a"], expected={}),
-                TestCaseStep(command="step2", args=["b"], expected={"return_code": 0}),
-            ]
-            steps_editor.load(steps)
-
-            assert len(steps_editor._steps) == 2
-
-
-# =============================================================================
-# ExpectedEditor in mounted context
-# =============================================================================
-
-
-class TestExpectedEditorMounted:
-    """Test ExpectedEditor widget when mounted via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_load_syncs_to_ui(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-
-        async with app.run_test() as pilot:
-            pilot.app.push_screen(CaseEditorScreen())
-            await pilot.pause()
-
-            expected_editor = pilot.app.screen.query_one("#expected-editor", ExpectedEditor)
-            # Load some data
-            expected_editor.load({
-                "return_code": 0,
-                "output_contains": ["hello"],
-            })
-
-            # to_dict should reflect loaded data
-            result = expected_editor.to_dict()
-            assert result["return_code"] == 0
-            assert result["output_contains"] == ["hello"]
-
-
-# =============================================================================
-# CaseTable widget
-# =============================================================================
-
-
-class TestCaseTableMounted:
-    """Test CaseTable widget when mounted via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_columns_initialised(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            assert table.row_count > 0
-            # 6 columns: #, Name, Command, Tags, Timeout, Mode
-            assert len(table.columns) == 6
-
-    @pytest.mark.asyncio
-    async def test_cursor_movement(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            table = pilot.app.screen.query_one("#main-table", CaseTable)
-            assert table.row_count > 0
-
-            # First row should be selectable
-            idx = table.get_selected_index()
-            assert idx is not None
-            # Index should be within valid range
-            assert 0 <= idx < len(pilot.app.screen._ctrl.cases)
-
-
-# =============================================================================
-# SearchBar widget
-# =============================================================================
-
-
-class TestSearchBarMounted:
-    """Test SearchBar widget when mounted via run_test."""
-
-    @pytest.mark.asyncio
-    async def test_input_changes_emit_message(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-            search_input = search_bar.query_one("#search-input")
-            search_input.focus()
-            await pilot.press("t", "e", "s", "t")
-
-            await pilot.pause()
-            assert search_bar.query == "test"
-
-    @pytest.mark.asyncio
-    async def test_clear_resets_state(self, sample_config):
-        app = CaseManagerApp(str(sample_config))
-        async with app.run_test() as pilot:
-            search_bar = pilot.app.screen.query_one("#main-search", SearchBar)
-            search_input = search_bar.query_one("#search-input")
-            search_input.focus()
-            await pilot.press("q", "u", "e", "r", "y")
-
-            await pilot.pause()
-            assert search_bar.query == "query"
-
-            search_bar.clear()
-            assert search_bar.query == ""
diff --git a/tests/unit/tui/test_widgets_data.py b/tests/unit/tui/test_widgets_data.py
deleted file mode 100644
index f9f1853..0000000
--- a/tests/unit/tui/test_widgets_data.py
+++ /dev/null
@@ -1,188 +0,0 @@
-"""Tests for TUI widget data models — StepsEditor._steps, ExpectedEditor._data.
-
-These tests exercise the internal data layer of widgets without requiring
-the Textual app to be running.  ``load()`` / ``to_steps()`` / ``to_dict()``
-work against the internal state even when the widget is not mounted.
-"""
-
-import copy
-import pytest
-
-from symtest.core.test_case import TestCaseStep
-from symtest.tui.widgets.steps_editor import StepsEditor
-from symtest.tui.widgets.expected_editor import ExpectedEditor
-
-
-def _step(cmd="echo", args=None, expected=None, timeout=None, retry_count=0):
-    return TestCaseStep(
-        command=cmd,
-        args=args or [],
-        expected=expected or {},
-        timeout=timeout,
-        retry_count=retry_count,
-    )
-
-
-# ---------------------------------------------------------------------------
-# StepsEditor data layer
-# ---------------------------------------------------------------------------
-
-
-class TestStepsEditorData:
-    """Test StepsEditor._steps and its load/to_steps methods (no mount)."""
-
-    def test_initial_state_empty(self):
-        editor = StepsEditor()
-        assert editor._steps == []
-        assert editor.to_steps() == []
-
-    def test_load_and_to_steps_roundtrip(self):
-        editor = StepsEditor()
-        original = [
-            _step("echo", ["hello"], {"return_code": 0}),
-            _step("python", ["-c", "print(1)"], {"output_contains": ["1"]}),
-        ]
-        editor.load(original)
-        result = editor.to_steps()
-        assert len(result) == 2
-        assert result[0].command == "echo"
-        assert result[0].args == ["hello"]
-        assert result[1].command == "python"
-
-    def test_load_creates_deep_copy(self):
-        editor = StepsEditor()
-        original = [_step("echo", ["hello"])]
-        editor.load(original)
-        # Modify original — should not affect editor
-        original[0].args.append("world")
-        assert editor.to_steps()[0].args == ["hello"]
-
-    def test_to_steps_creates_deep_copy(self):
-        editor = StepsEditor()
-        editor.load([_step("echo", ["hello"])])
-        result = editor.to_steps()
-        result[0].args.append("world")
-        assert editor._steps[0].args == ["hello"]
-
-    def test_empty_steps_list(self):
-        editor = StepsEditor()
-        editor.load([])
-        assert editor.to_steps() == []
-
-    def test_steps_with_timeout(self):
-        editor = StepsEditor()
-        editor.load([_step("sleep", timeout=10.0)])
-        result = editor.to_steps()
-        assert result[0].timeout == 10.0
-
-    def test_steps_with_retry_count(self):
-        editor = StepsEditor()
-        editor.load([_step("flaky", retry_count=3)])
-        result = editor.to_steps()
-        assert result[0].retry_count == 3
-
-    def test_steps_default_retry_count(self):
-        editor = StepsEditor()
-        editor.load([_step("stable")])
-        result = editor.to_steps()
-        assert result[0].retry_count == 0
-
-    def test_steps_with_empty_args(self):
-        editor = StepsEditor()
-        editor.load([_step("echo")])
-        result = editor.to_steps()
-        assert result[0].args == []
-
-    def test_editing_idx_initial(self):
-        editor = StepsEditor()
-        assert editor._editing_idx == -1
-
-    def test_load_resets_editing_idx(self):
-        editor = StepsEditor()
-        editor._editing_idx = 3
-        editor.load([_step("echo")])
-        assert editor._editing_idx == -1
-
-
-# ---------------------------------------------------------------------------
-# ExpectedEditor data layer
-# ---------------------------------------------------------------------------
-
-
-class TestExpectedEditorData:
-    """Test ExpectedEditor._data and its load/to_dict methods (no mount)."""
-
-    def test_initial_state_empty(self):
-        editor = ExpectedEditor()
-        assert editor._data == {}
-        assert editor.to_dict() == {}
-
-    def test_load_and_to_dict_roundtrip(self):
-        editor = ExpectedEditor()
-        original = {
-            "return_code": 0,
-            "output_contains": ["hello", "world"],
-            "output_matches": r"\d+",
-        }
-        editor.load(original)
-        result = editor.to_dict()
-        assert result == original
-
-    def test_load_creates_deep_copy(self):
-        editor = ExpectedEditor()
-        original = {"output_contains": ["hello"]}
-        editor.load(original)
-        original["output_contains"].append("world")
-        assert editor.to_dict()["output_contains"] == ["hello"]
-
-    def test_to_dict_creates_deep_copy(self):
-        editor = ExpectedEditor()
-        editor.load({"return_code": 0})
-        result = editor.to_dict()
-        result["extra"] = "should_not_persist"
-        assert "extra" not in editor._data
-
-    def test_load_complex_expected(self):
-        editor = ExpectedEditor()
-        original = {
-            "return_code": 1,
-            "output_contains": ["ok"],
-            "output_matches": r"^done$",
-            "compare_files": [
-                {"actual": "a.txt", "baseline": "b.txt", "type": "text"},
-            ],
-        }
-        editor.load(original)
-        result = editor.to_dict()
-        assert result["return_code"] == 1
-        assert result["compare_files"][0]["type"] == "text"
-
-    def test_load_empty_dict(self):
-        editor = ExpectedEditor()
-        editor.load({})
-        assert editor.to_dict() == {}
-
-    def test_load_custom_keys(self):
-        editor = ExpectedEditor()
-        original = {
-            "return_code": 0,
-            "custom_key": "custom_value",
-            "nested": {"a": 1},
-        }
-        editor.load(original)
-        result = editor.to_dict()
-        assert result["custom_key"] == "custom_value"
-        assert result["nested"] == {"a": 1}
-
-    def test_load_multiple_times_overwrites(self):
-        editor = ExpectedEditor()
-        editor.load({"return_code": 0})
-        editor.load({"return_code": 1})
-        assert editor.to_dict() == {"return_code": 1}
-
-    def test_to_dict_when_not_mounted_does_not_sync(self):
-        """When not mounted, to_dict returns the internal _data as-is."""
-        editor = ExpectedEditor()
-        editor._data = {"return_code": 42}
-        result = editor.to_dict()
-        assert result["return_code"] == 42
diff --git a/tests/unit/utils/test_report_generator.py b/tests/unit/utils/test_report_generator.py
index 703d296..dd513ef 100644
--- a/tests/unit/utils/test_report_generator.py
+++ b/tests/unit/utils/test_report_generator.py
@@ -125,6 +125,183 @@ def test_error_analysis_all_disabled_omits_stats_for_passed():
     assert "error_stats" not in report
 
 
+# ── channel sub-results (data-lane comparators) ──
+
+def _make_failed_detail_with_channels():
+    """构造一个带通道子结果的失败用例 detail dict（extractor 比较器形态）"""
+    return {
+        "name": "channel_case",
+        "status": "failed",
+        "failure_kind": "file_compare",
+        "compare_failures": [
+            {
+                "actual": "out.dat",
+                "baseline": "ref.dat",
+                "type": "my_extractor",
+                "diff_summary": {"total_differences": 1},
+                "error_stats": {
+                    "S11": {"total": 4, "mismatched": 0, "max_abs_error": 1e-9},
+                    "S33": {"total": 4, "mismatched": 2, "max_abs_error": 543.0},
+                },
+                "channels": [
+                    {
+                        "name": "S11",
+                        "passed": True,
+                        "rtol": 1e-5,
+                        "atol": 1e-8,
+                        "stats": {"total": 4, "mismatched": 0, "max_abs_error": 1e-9},
+                        "differences": [],
+                    },
+                    {
+                        "name": "S33",
+                        "passed": False,
+                        "rtol": 1e-5,
+                        "atol": 600.0,
+                        "stats": {"total": 4, "mismatched": 2, "max_abs_error": 543.0},
+                        "differences": [
+                            {"position": "channel S33", "expected": "within rtol=1e-05, atol=600",
+                             "actual": "2/4 values mismatched", "diff_type": "channel_mismatch"},
+                        ],
+                    },
+                ],
+                "differences": [
+                    {"position": "channel S33", "expected": "within rtol=1e-05, atol=600",
+                     "actual": "2/4 values mismatched", "diff_type": "channel_mismatch"},
+                ],
+            }
+        ],
+    }
+
+
+def test_channel_results_rendered_per_channel():
+    """失败报告应逐通道展示 pass/fail、容差与统计"""
+    generator = ReportGenerator(
+        {
+            "total": 1, "passed": 0, "failed": 1,
+            "details": [_make_failed_detail_with_channels()],
+        },
+        "unused.txt",
+    )
+    report = generator.generate_report()
+    assert "channels:" in report
+    assert "channel 'S11': PASS" in report
+    assert "channel 'S33': FAIL" in report
+    assert "atol=600" in report
+    assert "max_abs_error: 543" in report
+    assert "channel S33" in report
+
+
+def test_nested_autonomous_error_stats_not_treated_as_channels():
+    """自主比较器的嵌套 error_stats（{group: {...}}）不得被猜测为通道结果：
+    不渲染通道块，仅做通用扁平渲染。"""
+    detail = {
+        "name": "autonomous_nested",
+        "status": "failed",
+        "compare_failures": [
+            {
+                "actual": "out.dat",
+                "baseline": "ref.dat",
+                "type": "my_analysis",
+                "diff_summary": {},
+                # Channel-SHAPED nested dict from an autonomous comparator —
+                # must NOT be interpreted as channel output.
+                "error_stats": {
+                    "geometry": {"max_deviation": 0.5, "elements": 1024},
+                    "solver": {"iterations": 42, "converged": False},
+                },
+                "channels": [],  # explicitly no channel results
+                "differences": [],
+            }
+        ],
+    }
+    generator = ReportGenerator(
+        {
+            "total": 1, "passed": 0, "failed": 1,
+            "details": [detail],
+        },
+        "unused.txt",
+    )
+    report = generator.generate_report()
+    # Flat generic rendering — no channel inference from dict shape
+    assert "channel '" not in report
+    assert "channels:" not in report
+    assert "error_stats:" in report
+    assert "geometry:" in report
+    assert "solver:" in report
+    assert "iterations" in report
+
+
+def test_flat_error_stats_rendered_when_no_channels():
+    """无通道结果时，扁平 error_stats 走通用渲染（fallback 规则）。"""
+    detail = {
+        "name": "flat_stats",
+        "status": "failed",
+        "compare_failures": [
+            {
+                "actual": "out.dat",
+                "baseline": "ref.dat",
+                "type": "csv",
+                "diff_summary": {},
+                "error_stats": {
+                    "total_numeric_cells": 4,
+                    "mismatched_cells": 1,
+                    "max_abs_error": 0.25,
+                },
+                "channels": [],
+                "differences": [],
+            }
+        ],
+    }
+    generator = ReportGenerator(
+        {
+            "total": 1, "passed": 0, "failed": 1,
+            "details": [detail],
+        },
+        "unused.txt",
+    )
+    report = generator.generate_report()
+    assert "error_stats:" in report
+    assert "total_numeric_cells: 4" in report
+    assert "max_abs_error: 0.25" in report
+    assert "channel '" not in report
+
+
+def test_channel_results_rendered_for_passed_with_error_analysis_all():
+    """--error-analysis-all 时通过用例也应渲染通道子结果"""
+    detail = {
+        "name": "ok_channels",
+        "status": "passed",
+        "assertion_results": [
+            {
+                "assertion": "compare_files",
+                "passed": True,
+                "error_stats": None,
+                "channels": [
+                    {
+                        "name": "U1",
+                        "passed": True,
+                        "rtol": 1e-5,
+                        "atol": 1e-8,
+                        "stats": {"total": 10, "mismatched": 0},
+                        "differences": [],
+                    },
+                ],
+            }
+        ],
+    }
+    generator = ReportGenerator(
+        {
+            "total": 1, "passed": 1, "failed": 0,
+            "error_analysis_all": True,
+            "details": [detail],
+        },
+        "unused.txt",
+    )
+    report = generator.generate_report()
+    assert "channel 'U1': PASS" in report
+    assert "total: 10" in report
+
+
 # ── xfail_quiet ──
 
 def _make_xfailed_detail(*, xfail_quiet=True):