symtest-cli 1.3.0__tar.gz → 1.3.2__tar.gz

{symtest_cli-1.3.0/src/symtest_cli.egg-info → symtest_cli-1.3.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: symtest-cli
-Version: 1.3.0
+Version: 1.3.2
 Summary: Regression testing for CLI applications, with multi-step workflows and numerical file comparison.
-Home-page: https://github.com/ozil111/symtest
+Home-page: https://github.com/ozil111/symtest-cli
 Author: Xiaotong Wang
 Author-email: xiaotongwang98@gmail.com
-Project-URL: Documentation, https://github.com/ozil111/symtest/blob/main/docs/user_manual.md
-Project-URL: Source, https://github.com/ozil111/symtest
-Project-URL: Tracker, https://github.com/ozil111/symtest/issues
+Project-URL: Documentation, https://github.com/ozil111/symtest-cli/blob/main/docs/user_manual.md
+Project-URL: Source, https://github.com/ozil111/symtest-cli
+Project-URL: Tracker, https://github.com/ozil111/symtest-cli/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -53,11 +53,11 @@ Dynamic: summary
 
 > **Note:** This project was formerly known as `cli-test-framework`.
 > Since version 1.3.0 it is released as
-> [`symtest`](https://pypi.org/project/symtest/); the old package name is no
-> longer updated. Install with:
+> [`symtest-cli`](https://pypi.org/project/symtest-cli/); the old package name
+> is no longer updated. Install with:
 >
 > ```bash
-> pip install symtest
+> pip install symtest-cli
 > ```
 
 A feature-focused automated testing framework for command-line applications.
@@ -92,15 +92,15 @@ occur in real CLI and scientific-computing projects.
 Python 3.9 or newer is required.
 
 ```bash
-pip install symtest
+pip install symtest-cli
 ```
 
 YAML and the TUI are optional:
 
 ```bash
-pip install "symtest[yaml]"
-pip install "symtest[tui]"
-pip install "symtest[all]"
+pip install "symtest-cli[yaml]"
+pip install "symtest-cli[tui]"
+pip install "symtest-cli[all]"
 ```
 
 The default installation includes HDF5 and numerical comparison support.
@@ -298,6 +298,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
 
 ## Development
 

{symtest_cli-1.3.0 → symtest_cli-1.3.2}/README.md

@@ -4,11 +4,11 @@
 
 > **Note:** This project was formerly known as `cli-test-framework`.
 > Since version 1.3.0 it is released as
-> [`symtest`](https://pypi.org/project/symtest/); the old package name is no
-> longer updated. Install with:
+> [`symtest-cli`](https://pypi.org/project/symtest-cli/); the old package name
+> is no longer updated. Install with:
 >
 > ```bash
-> pip install symtest
+> pip install symtest-cli
 > ```
 
 A feature-focused automated testing framework for command-line applications.
@@ -43,15 +43,15 @@ occur in real CLI and scientific-computing projects.
 Python 3.9 or newer is required.
 
 ```bash
-pip install symtest
+pip install symtest-cli
 ```
 
 YAML and the TUI are optional:
 
 ```bash
-pip install "symtest[yaml]"
-pip install "symtest[tui]"
-pip install "symtest[all]"
+pip install "symtest-cli[yaml]"
+pip install "symtest-cli[tui]"
+pip install "symtest-cli[all]"
 ```
 
 The default installation includes HDF5 and numerical comparison support.
@@ -249,6 +249,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
 
 ## Development
 

{symtest_cli-1.3.0 → symtest_cli-1.3.2}/docs/design.md

@@ -259,7 +259,7 @@ load_test_cases() → _apply_test_case_filter() → setup_manager.setup_all()
 支持三种过滤方式（可组合）：
 - `test_case_filter`：按名称精确匹配
 - `test_case_tag_filter`：按 tags 匹配（交集逻辑）
-- `last_failed`：从 `.cli-test/last_run.json` 读取上次失败的用例名
+- `last_failed`：从 `.symtest/last_run.json` 读取上次失败的用例名
 
 **xfail 机制 `_apply_xfail_status()`**：
 
@@ -318,6 +318,8 @@ class TestCase:
     expected_failure: bool = False
     xfail_reason: str = ""
     xfail_quiet: bool = False
+    depends_on: List[str] = field(default_factory=list)
+    env: Dict[str, str] = field(default_factory=dict)
 ```
 
 两种模式：
@@ -328,6 +330,8 @@ class TestCase:
 - `tags`：标签过滤
 - `retry_count`：失败重试次数
 - `expected_failure` / `xfail_reason` / `xfail_quiet`：预期失败标记
+- `depends_on`：用例级依赖声明，支持 DAG 拓扑调度
+- `env`：case 级环境变量，注入该 case（序列模式为所有 step）的子进程，优先级高于 `setup` 与调度器注入
 
 ### 4.3 Assertions
 
@@ -426,7 +430,7 @@ class PathResolver:
 `--last-failed` 状态存储模块（`core/last_run_store.py`）：
 
 ```python
-# 存储位置: <workspace>/.cli-test/last_run.json
+# 存储位置: <workspace>/.symtest/last_run.json
 # {
 #   "case_name": {"status": "passed"},
 #   ...
@@ -448,8 +452,8 @@ class PathResolver:
 `--resume` 断点续跑模块（`core/sequence_state.py`）：
 
 ```python
-# 状态文件: <workspace>/.cli-test/sequence_state/<case_name>.json
-# 输出缓存: <workspace>/.cli-test/sequence_state/cache/<case_name>.step<N>.log
+# 状态文件: <workspace>/.symtest/sequence_state/<case_name>.json
+# 输出缓存: <workspace>/.symtest/sequence_state/cache/<case_name>.step<N>.log
 ```
 
 核心接口：
@@ -684,7 +688,7 @@ CaseManagerApp (Textual App)
   _update_history()          # 回归检测 + 更新 .symtest
        │
        ▼
-  _save_last_run()           # 写入 .cli-test/last_run.json
+  _save_last_run()           # 写入 .symtest/last_run.json
        │
        ▼
   setup_manager.teardown_all() # 逆序清理
@@ -699,14 +703,14 @@ CaseManagerApp (Textual App)
 ParallelConfigRunner.run_tests()
        │
        ▼
-  LPT 排序 (历史 avg_duration 优先，fallback 到 estimated_time 降序)
+  拓扑 LPT 排序 (depends_on 约束 + 历史 avg_duration 降序)
        │
        ▼
   _assign_relative_cpu_cores()  # 按权重比例分配 CPU 核心
        │
        ▼
   ┌──────────────────────────────────────┐
-  │  ThreadPoolExecutor.map():           │
+  │  DAG 调度 / 或直接并行 (无依赖时)    │
   │    AtomicSemaphore.acquire(cores)    │
   │    注入 OMP/MKL/NPROC 环境变量       │
   │    execute_single_test_case()        │
@@ -715,7 +719,45 @@ ParallelConfigRunner.run_tests()
   └──────────────────────────────────────┘
 ```
 
-### 7.3 文件比较流
+### 7.3 DAG 依赖调度流
+
+当 `TestCase.depends_on` 非空时，并行 runner 自动切换为 DAG 拓扑调度：
+
+```
+ParallelRunner.run_tests()
+       │
+       ▼
+  has_deps? ──No──► _run_tests_flat() (fast path)
+       │
+      Yes
+       ▼
+  _run_dag()
+       │
+       ├── 构建 dependents 邻接表 + in_degree 入度表
+       ├── 入度=0 的用例 → 就绪队列 → executor.submit()
+       │
+       ▼
+  ┌────────────────────────────────────────┐
+  │  as_completed() 循环:                   │
+  │    完成一个 future                       │
+  │    │                                     │
+  │    ├── passed/xfailed → 后继入度-1      │
+  │    │   └── 入度=0 → submit(后继)        │
+  │    │                                     │
+  │    └── failed/xpassed → cascade_skip    │
+  │        └── BFS 标记下游全部 skipped      │
+  └────────────────────────────────────────┘
+```
+
+**调度语义**：
+- 依赖"满足" = 状态为 `passed` 或 `xfailed`
+- 依赖"不满足" = 状态为 `failed` 或 `xpassed` → 下游全部 skip
+- `skipped` 不计入 `failed` 计数，报告中单独列出
+- 级联 skip：若 B 被 skip，则依赖 B 的 C 也自动 skip
+
+**顺序 runner**（`BaseRunner.run_tests()`）同样支持拓扑排序：`_topological_order()` 使用 Kahn 算法生成拓扑序列，按序执行，依赖失败时自动跳过下游。
+
+### 7.4 文件比较流
 
 ```
 symtest compare file1 file2 [options]
@@ -737,7 +779,7 @@ symtest compare file1 file2 [options]
   format_result(result, --output-format)  # text / json / html
 ```
 
-### 7.4 --resume 断点续跑流
+### 7.5 --resume 断点续跑流
 
 ```
 序列测试用例执行
@@ -781,14 +823,16 @@ symtest compare file1 file2 [options]
 | LPT 调度策略 | 长任务先启动，减少尾延迟；优先使用 `.symtest` 历史数据 |
 | 累计平均更新历史 | 直觉简单，随运行次数增多单次异常自然稀释 |
 | 回归检测在更新前执行 | 先与旧均值比较再更新，确保对比的是"历史基线" |
-| `.symtest` 隐藏文件 + `.cli-test/` 目录 | 不干扰用户目录视图，JSON 格式便于调试；状态文件统一管理 |
+| `.symtest/` 目录 | 不干扰用户目录视图，JSON 格式便于调试；状态文件统一管理 |
 | 环境变量注入 | 科学计算求解器常忽略 Python 级线程控制 |
+| case 级 env 通过 subprocess 注入 | 不改进程全局 `os.environ`，进程隔离、并行线程安全；优先级 `os.environ` < 调度器 < case env |
 | Comparator 工厂 + 插件发现 | 按文件类型创建比较器，workspace `comparators/` 目录自动发现插件 |
 | subprocess 隔离执行 | 每个 test case 独立子进程，保证测试间互不影响 |
 | xfail 机制 | 支持预期失败的测试（CI 中不阻塞流水线），意外通过时告警 |
 | --last-failed 覆写策略 | 只覆写本次执行的用例状态，避免子集运行时丢失未执行用例的状态 |
 | --resume 纯信任模型 | 不验证 artifact，由用户保证 workspace 未被修改，简化实现 |
 | retry_count 重试机制 | 应对偶发性网络抖动或竞态条件，首次失败后自动重试 |
+| DAG 依赖调度 | 基于 Kahn 拓扑 + 就绪队列，依赖满足后立即提交；依赖失败级联 skip 下游；无依赖时走 fast path 零开销 |
 | --update-baseline | 比较失败时自动将实际输出覆盖 baseline，适合批量更新基准 |
 | next_action_hint 结构化建议 | 失败结果附带下一步操作建议（update_baseline / update_expected / increase_timeout / investigate），便于 AI 消费 |
 | TUI 基于 Textual | 利用成熟的终端 UI 框架，提供交互式用例管理 |

{symtest_cli-1.3.0 → symtest_cli-1.3.2}/docs/design_en.md

@@ -259,7 +259,7 @@ load_test_cases() → _apply_test_case_filter() → setup_manager.setup_all()
 Supports three filter modes (combinable):
 - `test_case_filter`: exact name match
 - `test_case_tag_filter`: tag-based match (intersection logic)
-- `last_failed`: reads previously failed case names from `.cli-test/last_run.json`
+- `last_failed`: reads previously failed case names from `.symtest/last_run.json`
 
 **xfail mechanism `_apply_xfail_status()`**:
 
@@ -318,6 +318,7 @@ class TestCase:
     expected_failure: bool = False
     xfail_reason: str = ""
     xfail_quiet: bool = False
+    depends_on: List[str] = field(default_factory=list)
 ```
 
 Two modes:
@@ -426,7 +427,7 @@ Core interfaces:
 `--last-failed` state storage module (`core/last_run_store.py`):
 
 ```python
-# Storage location: <workspace>/.cli-test/last_run.json
+# Storage location: <workspace>/.symtest/last_run.json
 # {
 #   "case_name": {"status": "passed"},
 #   ...
@@ -448,8 +449,8 @@ Each run **overwrites** the status of executed cases; unexecuted cases retain th
 `--resume` step-level resume module (`core/sequence_state.py`):
 
 ```python
-# State file: <workspace>/.cli-test/sequence_state/<case_name>.json
-# Output cache: <workspace>/.cli-test/sequence_state/cache/<case_name>.step<N>.log
+# State file: <workspace>/.symtest/sequence_state/<case_name>.json
+# Output cache: <workspace>/.symtest/sequence_state/cache/<case_name>.step<N>.log
 ```
 
 Core interfaces:
@@ -684,7 +685,7 @@ Config file (JSON/YAML)
   _update_history()          # Regression detection + update .symtest
        │
        ▼
-  _save_last_run()           # Write .cli-test/last_run.json
+  _save_last_run()           # Write .symtest/last_run.json
        │
        ▼
   setup_manager.teardown_all() # Reverse cleanup
@@ -699,14 +700,14 @@ Config file (JSON/YAML)
 ParallelConfigRunner.run_tests()
        │
        ▼
-  LPT sort (historical avg_duration preferred, fallback to estimated_time desc)
+  Topology-constrained LPT sort (depends_on + historical avg_duration desc)
        │
        ▼
   _assign_relative_cpu_cores()  # Proportional CPU core assignment by weight
        │
        ▼
   ┌──────────────────────────────────────┐
-  │  ThreadPoolExecutor.map():           │
+  │  DAG scheduling / flat (no deps)     │
   │    AtomicSemaphore.acquire(cores)    │
   │    Inject OMP/MKL/NPROC env vars     │
   │    execute_single_test_case()        │
@@ -715,7 +716,47 @@ ParallelConfigRunner.run_tests()
   └──────────────────────────────────────┘
 ```
 
-### 7.3 File Comparison Flow
+### 7.3 DAG Dependency Scheduling Flow
+
+When `TestCase.depends_on` is non-empty, the parallel runner switches to DAG topology scheduling:
+
+```
+ParallelRunner.run_tests()
+       │
+       ▼
+  has_deps? ──No──► _run_tests_flat() (fast path)
+       │
+      Yes
+       ▼
+  _run_dag()
+       │
+       ├── Build dependents adjacency + in_degree table
+       ├── in_degree=0 cases → ready queue → executor.submit()
+       │
+       ▼
+  ┌────────────────────────────────────────┐
+  │  as_completed() loop:                   │
+  │    Complete one future                  │
+  │    │                                     │
+  │    ├── passed/xfailed → decrement       │
+  │    │   successor in-degree              │
+  │    │   └── in_degree=0 → submit()       │
+  │    │                                     │
+  │    └── failed/xpassed → cascade_skip    │
+  │        └── BFS mark all downstream      │
+  │            as skipped                    │
+  └────────────────────────────────────────┘
+```
+
+**Scheduling semantics**:
+- Dependency "satisfied" = status is `passed` or `xfailed`
+- Dependency "unsatisfied" = status is `failed` or `xpassed` → all downstream skipped
+- `skipped` is NOT counted as `failed`; listed separately in reports
+- Cascade skip: if B is skipped, C (which depends on B) is also skipped
+
+**Sequential runner** (`BaseRunner.run_tests()`) also supports topological ordering: `_topological_order()` uses Kahn's algorithm to generate a topological sequence, runs in order, and auto-skips downstream on dependency failure.
+
+### 7.4 File Comparison Flow
 
 ```
 symtest compare file1 file2 [options]
@@ -737,7 +778,7 @@ symtest compare file1 file2 [options]
   format_result(result, --output-format)  # text / json / html
 ```
 
-### 7.4 --resume Checkpoint Flow
+### 7.5 --resume Checkpoint Flow
 
 ```
 Sequence test case execution
@@ -781,7 +822,7 @@ Sequence test case execution
 | LPT scheduling strategy | Long tasks start first, reducing tail latency; prioritizes `.symtest` historical data |
 | Cumulative average history update | Simple and intuitive; single anomalies are naturally diluted over many runs |
 | Regression check before update | Compare against old average first, then update; ensures comparison is against the "historical baseline" |
-| `.symtest` hidden file + `.cli-test/` directory | Non-intrusive to the user's directory view; JSON format for easy debugging; state files centrally managed |
+| `.symtest/` directory | Non-intrusive to the user's directory view; JSON format for easy debugging; state files centrally managed |
 | Environment variable injection | Scientific computing solvers often ignore Python-level thread control |
 | Comparator factory + plugin discovery | Creates comparators by file type; workspace `comparators/` directory for auto-discovered plugins |
 | subprocess isolated execution | Each test case runs in an independent subprocess, ensuring tests don't affect each other |
@@ -789,6 +830,7 @@ Sequence test case execution
 | --last-failed overwrite strategy | Only overwrites status of executed cases; avoids losing state of unexecuted cases during subset runs |
 | --resume pure trust model | No artifact validation; user guarantees workspace is unchanged, simplifying implementation |
 | retry_count retry mechanism | Handles transient network glitches or race conditions; auto-retries on first failure |
+| 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 |

{symtest_cli-1.3.0 → symtest_cli-1.3.2}/docs/tui_and_config_split_design.md

@@ -683,8 +683,8 @@ tui = ["textual>=0.40.0"]
 ```
 
 ```bash
-pip install symtest[tui]   # 安装 TUI 依赖
-pip install symtest        # 核心包，不含 TUI
+pip install symtest-cli[tui]   # 安装 TUI 依赖
+pip install symtest-cli        # 核心包，不含 TUI
 ```
 
 ### 9.2 优雅降级
@@ -698,7 +698,7 @@ def run_tui(config_file, workspace):
     except ImportError:
         print(
             "TUI 功能需要安装 textual。请运行：\n"
-            "  pip install symtest[tui]\n"
+            "  pip install symtest-cli[tui]\n"
             "或：\n"
             "  pip install textual"
         )

{symtest_cli-1.3.0 → symtest_cli-1.3.2}/docs/user_manual.md

@@ -4,6 +4,7 @@
 
 - [安装](#安装)
 - [测试用例定义](#测试用例定义)
+- [Case 级环境变量](#case-级环境变量env)
 - [配置拆分机制](#配置拆分机制)
 - [配置继承](#配置继承)
 - [配置校验](#配置校验)
@@ -26,7 +27,7 @@
 ## 安装
 
 ```bash
-pip install symtest
+pip install symtest-cli
 ```
 
 要求：Python >= 3.9
@@ -34,13 +35,13 @@ pip install symtest
 YAML 支持需安装可选依赖：
 
 ```bash
-pip install "symtest[yaml]"
+pip install "symtest-cli[yaml]"
 ```
 
 一次安装 YAML 和 TUI 等全部可选功能：
 
 ```bash
-pip install "symtest[all]"
+pip install "symtest-cli[all]"
 ```
 
 HDF5 文件比较依赖 `h5py`（已随框架安装）。如需在无 HDF5 环境下使用其他比较功能，可单独卸载，但 HDF5 比较将不可用。
@@ -159,6 +160,78 @@ test_cases:
 }
 ```
 
+### 测试依赖（depends_on）
+
+当测试用例之间存在先后依赖时（例如 D 需要 A、B、C 先生成数据），通过 `depends_on` 声明依赖关系，框架会自动按 DAG 拓扑顺序调度：
+
+**并行模式**：A、B、C 并行执行，全部通过后 D 才被提交。依赖失败的用例会自动 skip 其下游（级联 skip）。
+
+**顺序模式**：框架按拓扑序重排用例，保证依赖在前的先执行，依赖失败时同样跳过下游。
+
+**JSON 示例**：
+
+```json
+{
+    "test_cases": [
+        { "name": "A", "command": "python", "args": ["gen_a.py"], "expected": {"return_code": 0} },
+        { "name": "B", "command": "python", "args": ["gen_b.py"], "expected": {"return_code": 0} },
+        { "name": "C", "command": "python", "args": ["gen_c.py"], "expected": {"return_code": 0} },
+        {
+            "name": "D", "command": "python", "args": ["merge.py"],
+            "depends_on": ["A", "B", "C"],
+            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
+        }
+    ]
+}
+```
+
+**YAML 示例**：
+
+```yaml
+test_cases:
+  - name: A
+    command: python
+    args: ["gen_a.py"]
+    expected: { return_code: 0 }
+
+  - name: B
+    command: python
+    args: ["gen_b.py"]
+    expected: { return_code: 0 }
+
+  - name: C
+    command: python
+    args: ["gen_c.py"]
+    expected: { return_code: 0 }
+
+  - name: D
+    command: python
+    args: ["merge.py"]
+    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，调度开销为零
+
 ### 字段说明
 
 | 字段 | 必填 | 说明 |
@@ -174,11 +247,69 @@ test_cases:
 | `expected_failure` | 否 | 标记为预期失败（xfail）。设为 `true` 时，失败计为 XFailed（不影响退出码），意外通过计为 XPassed（视作失败） |
 | `xfail_reason` | 否 | xfail 的原因说明，报告中将展示此文本（如 "Bug #42 尚未修复"） |
 | `xfail_quiet` | 否 | 设为 `true` 时，xfailed 状态下报告中不输出 Command Output（stdout/stderr 大段输出），仅保留命令、返回码、失败原因等元信息 |
+| `depends_on` | 否 | 依赖的测试用例名称列表（如 `["A", "B"]`）。当前用例必须等待所有依赖用例通过后才执行。依赖失败时自动 skip 当前用例及下游。支持并行和顺序两种 runner |
+| `env` | 否 | case 级环境变量字典（如 `{"UEL_SYSID_SCALE": "1.0"}`），仅在执行该 case（序列模式为所有 step）时注入子进程，见 [Case 级环境变量](#case-级环境变量env) |
 | `expected.return_code` | 否 | 期望返回码 |
 | `expected.output_contains` | 否 | 输出需包含的字符串列表 |
 | `expected.output_matches` | 否 | 输出需匹配的正则表达式（单个字符串） |
 | `expected.compare_files` | 否 | 文件比较断言列表，见下文 |
 
+## Case 级环境变量（env）
+
+通过 case 下与 `name` 同级的 `env` 字段，可为单个用例注入环境变量，仅在该用例（序列模式为所有 step）的子进程内生效，不影响其他用例。
+
+### JSON
+
+```json
+{
+    "name": "UEL 缩放测试",
+    "command": "solver",
+    "args": ["-i", "input.dat"],
+    "env": {
+        "UEL_SYSID_SCALE": "1.0",
+        "OMP_NUM_THREADS": "8"
+    },
+    "expected": { "return_code": 0 }
+}
+```
+
+### YAML
+
+```yaml
+- name: UEL 缩放测试
+  command: solver
+  args: ["-i", "input.dat"]
+  env:
+    UEL_SYSID_SCALE: "1.0"
+  expected: { return_code: 0 }
+```
+
+### 序列模式
+
+`env` 定义在 case 级（与 `steps` 同级），对该 case 的**所有 step** 生效：
+
+```json
+{
+    "name": "多步骤+环境变量",
+    "env": { "UEL_SYSID_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` 等断言共存。
@@ -515,7 +646,7 @@ TUI 依赖 `textual` 库，并作为按需安装的可选依赖提供：
 
 ```bash
 # 安装时附带 TUI 支持
-pip install "symtest[tui]"
+pip install "symtest-cli[tui]"
 
 # 或者在已有框架上单独安装 textual
 pip install textual
@@ -702,7 +833,7 @@ symtest run test_cases.json --error-analysis
 **xfail 语义**：标记为 `expected_failure` 的用例如果失败（`xfailed`），是预期行为，**不会**被 `--last-failed` 选中重跑。但如果 xfail 标记的用例意外通过（`xpassed`），则被视为真正失败，**会**被选中。
 
 **工作原理**：
-- 每次运行结束后，框架在 `<workspace>/.cli-test/last_run.json` 中记录每个用例的状态
+- 每次运行结束后，框架在 `<workspace>/.symtest/last_run.json` 中记录每个用例的状态
 - 记录采用**覆盖式更新**：本次跑到的用例用新结果覆盖旧结果，没跑到的保留原状态
 - 这意味着修好的 case 在下一次显示中不再是"failed"
 - 如果文件不存在（首次运行），`--last-failed` 会提示并正常运行全部用例
@@ -725,7 +856,7 @@ symtest run config.json
 `--resume` 针对**顺序步骤测试（sequence）**，跳过上次运行中已通过的步骤，直接从失败步骤继续执行。适合耗时长的多步骤用例——例如有限元分析中 step 1-3 通过了（各耗时几十秒甚至分钟），只有 step 4 的断言失败，`--resume` 可以跳过 1-3、只重跑 step 4。
 
 **工作原理**：
-- 每个步骤通过后，框架在 `<workspace>/.cli-test/sequence_state/<case_name>.json` 中记录步骤状态，并将输出缓存到 `cache/` 子目录
+- 每个步骤通过后，框架在 `<workspace>/.symtest/sequence_state/<case_name>.json` 中记录步骤状态，并将输出缓存到 `cache/` 子目录
 - 下次 `--resume` 时，计算配置哈希（所有步骤的 command/args/expected/timeout/retry_count 及 case 级 expected 的 SHA256）与已保存状态比对
 - 哈希匹配 → 跳过已通过的步骤，从缓存重建 `combined_output`（确保 case 级 `expected` 断言能正常执行）
 - 用例全部通过 → 自动删除状态文件和缓存，避免残留影响后续运行