feat(cli): rich 深度集成 — 执行生命周期 ✓/✗/▸/○ 符号 + dry-run + 命令输出

.trae/docs/iter-01-typer-rich-migration.md

@@ -0,0 +1,62 @@
+# 迭代 01: typer/rich 迁移
+
+## 本轮目标
+
+采用 typer + rich 简化 CLI 设计, 提高显示效果:
+1. 修复 Python 3.8 兼容性测试失败
+2. 全量重写 tools.py 为 typer 内核 (保留 @px.tool 装饰器 API)
+3. 重写 pf.py 为 rich 驱动主入口
+4. rich 深度集成 (执行生命周期/错误/工具列表/dry-run)
+5. 放弃 Python 3.8/3.9 支持 (requires-python >=3.10)
+
+## 改动文件清单
+
+### 依赖与配置
+- `pyproject.toml`: requires-python >=3.10, 添加 typer>=0.24.0 + rich>=13.7.0 依赖, ruff target-version=py310, pyrefly python-version=3.10
+- `tox.ini`: envlist 改为 py310-py314
+
+### 核心重写
+- `src/pyflowx/tools.py`: 全量重写 — argparse → typer.Typer; _make_dispatcher 构建命令 dispatcher; _build_typer_app 单命令/多命令路由; _execute_dag DAG 编排; standalone_mode=False + 捕获 typer._click 异常处理退出码; _handle_list_rich rich 表格 --list
+- `src/pyflowx/cli/pf.py`: 重写 — rich Panel+Table 工具列表 (含别名/说明列), --help/-h/--version/-V 全局选项, 未知工具模糊匹配建议 (difflib), rich Console stderr 错误
+
+### rich 深度集成
+- `src/pyflowx/executors.py`: _make_verbose_callback 用 ✓/✗/▸/○ 符号 + 颜色替代 [verbose] 前缀; _print_dry_run rich styled
+- `src/pyflowx/command.py`: 执行命令/返回码用 rich Console + 颜色 (green=0/red=非0)
+
+### Python 3.10+ 现代化
+- `src/pyflowx/graph.py`: 移除 graphlib_backport, 直接 import graphlib
+- `src/pyflowx/task.py`: Union → X|Y, typing.ContextManager → contextlib.AbstractContextManager
+- `src/pyflowx/storage.py`: 同上
+- `src/pyflowx/command.py`: typing.List → list, Union → X|Y
+- `src/pyflowx/cli/emlmanager.py`: zip() 加 strict= 参数
+- `src/pyflowx/executors.py`: zip() 加 strict=True
+
+### 测试
+- `tests/test_tools.py`: 全量重写 (84 测试) — 覆盖 typer 内核 (_make_dispatcher/_build_typer_app/_execute_dag/退出码三态)
+- `tests/test_runner.py`: verbose 断言更新 (✓ 替代 [verbose])
+
+## 关键决策与依据
+
+1. **保留 @px.tool 装饰器 API**: 用户既有 ops/ 模块全部使用 @px.tool, 改 API 会破坏所有工具. 内部替换 argparse→typer, 外部 API 不变.
+
+2. **standalone_mode=False**: typer 默认 standalone_mode=True 会 sys.exit() 退出进程, 测试中无法捕获. 用 False + 手动捕获 typer._click 异常 (NoArgsIsHelpError/ClickException/Abort) 处理退出码.
+
+3. **typer._click 私有导入**: typer 内置 click (typer._click) 与公共 click 是两套独立类层次, 必须从 typer._click.exceptions 导入 NoArgsIsHelpError/ClickException 才能捕获.
+
+4. **--list 预处理而非 typer callback**: typer 的 no_args_is_help=True 在多命令工具中会拦截 --list (要求先给 subcommand). 在 run_tool 中预处理 --list (任意位置出现即列出任务) 绕过此限制.
+
+5. **单命令 vs 多命令**: 单命令工具 (仅 subcommand=None) 用 callback(invoke_without_command=True), no_args_is_help=False; 多命令工具用各 subcommand 注册为 command, no_args_is_help=True.
+
+6. **legacy 工具不迁移**: emlmanager.py 是 Web 应用 (sqlite3+threading+HTTP), profiler.py 用 runpy.run_path, 均不适配 @px.tool DAG 模型. 保留 pf._run_legacy() 路由是更简方案.
+
+## 验证结果
+
+- ruff check: 0 errors
+- ruff format: 96 files already formatted
+- pyrefly: 0 errors (12 suppressed)
+- pytest: 1003 passed
+- coverage: 97.00% (门槛 95%)
+
+## 遗留事项
+
+- 无

src/pyflowx/command.py

@@ -12,10 +12,14 @@ import os
 import subprocess
 from typing import Any, cast
 
+from rich.console import Console
+
 from .task import TaskSpec
 
 __all__ = ["run_command"]
 
+_cmd_console = Console()
+
 
 def run_command(spec: TaskSpec[Any]) -> Any:  # noqa: PLR0912
     """执行 ``spec.cmd`` 指定的命令（list / shell 字符串 / 可调用对象）。
@@ -39,9 +43,9 @@ def run_command(spec: TaskSpec[Any]) -> Any:  # noqa: PLR0912
     if callable(cmd) and not isinstance(cmd, (list, str)):
         name = getattr(cmd, "__name__", "callable")
         if verbose:
-            print(f"[verbose] 执行可调用命令: {name}", flush=True)
+            _cmd_console.print(f"[cyan]▸[/cyan] 执行可调用命令: [bold]{name}[/bold]")
             if cwd is not None:
-                print(f"[verbose] 工作目录: {cwd}", flush=True)
+                _cmd_console.print(f"  [dim]工作目录: {cwd}[/dim]")
         try:
             return cmd()
         except Exception as e:
@@ -58,9 +62,9 @@ def run_command(spec: TaskSpec[Any]) -> Any:  # noqa: PLR0912
         label = "Shell 命令"
 
     if verbose:
-        print(f"[verbose] {verb}: {cmd_str}", flush=True)
+        _cmd_console.print(f"[cyan]▸[/cyan] {verb}: [bold]{cmd_str}[/bold]")
         if cwd is not None:
-            print(f"[verbose] 工作目录: {cwd}", flush=True)
+            _cmd_console.print(f"  [dim]工作目录: {cwd}[/dim]")
 
     # 合并环境变量
     run_env: dict[str, str] | None = None
@@ -87,7 +91,8 @@ def run_command(spec: TaskSpec[Any]) -> Any:  # noqa: PLR0912
         raise RuntimeError(f"{label}执行异常: {cmd_str}: {e}") from e
 
     if verbose:
-        print(f"[verbose] 返回码: {result.returncode}", flush=True)
+        style = "green" if result.returncode == 0 else "red"
+        _cmd_console.print(f"[{style}]返回码: {result.returncode}[/{style}]")
 
     if result.returncode == 0:
         if not verbose and result.stdout:

src/pyflowx/executors.py

@@ -52,6 +52,8 @@ from collections.abc import Awaitable, Callable, Mapping
 from datetime import datetime
 from typing import Any, Literal, cast
 
+from rich.console import Console
+
 from .context import build_call_args, describe_injection
 from .errors import TaskFailedError, TaskTimeoutError
 from .graph import Graph
@@ -61,6 +63,9 @@ from .task import TaskEvent, TaskHooks, TaskResult, TaskSpec, TaskStatus
 
 logger = logging.getLogger(__name__)
 
+# verbose 模式输出用的 Console (不抢占用户 stdout, 仅格式化)
+_verbose_console = Console()
+
 # 进程池复用：同一次 run() 内的 process 任务共享一个 ProcessPoolExecutor。
 # 模块级缓存避免每次任务都创建/销毁进程池的开销。
 # run() 结束后通过 _shutdown_process_pool() 关闭（shutdown(wait=False) +
@@ -724,23 +729,22 @@ class DependencyRunner:
 # 公共 API
 # ---------------------------------------------------------------------- #
 def _make_verbose_callback(on_event: EventCallback | None) -> EventCallback:
-    """包装 on_event 回调, 在 verbose 模式下打印任务生命周期。"""
+    """包装 on_event 回调, 在 verbose 模式下用 rich 打印任务生命周期。"""
 
     def _verbose_callback(event: TaskEvent) -> None:
         dur = f" ({event.duration:.3f}s)" if event.duration is not None else ""
         if event.status == TaskStatus.RUNNING:
-            print(f"[verbose] 任务 {event.task!r} 开始执行...", flush=True)
+            _verbose_console.print(f"[cyan]▸[/cyan] [bold]{event.task!r}[/bold] 开始执行...")
         elif event.status == TaskStatus.SUCCESS:
-            print(f"[verbose] 任务 {event.task!r} 成功{dur}", flush=True)
+            _verbose_console.print(f"[green]✓[/green] [bold]{event.task!r}[/bold] 成功[dim]{dur}[/dim]")
         elif event.status == TaskStatus.FAILED:
             err = f": {event.error}" if event.error else ""
-            print(
-                f"[verbose] 任务 {event.task!r} 失败{dur} (尝试 {event.attempts} 次){err}",
-                flush=True,
+            _verbose_console.print(
+                f"[red]✗[/red] [bold]{event.task!r}[/bold] 失败[dim]{dur} (尝试 {event.attempts} 次)[/dim][red]{err}[/red]"
             )
         elif event.status == TaskStatus.SKIPPED:
             reason = f" ({event.reason})" if event.reason else ""
-            print(f"[verbose] 任务 {event.task!r} 跳过{reason}", flush=True)
+            _verbose_console.print(f"[yellow]○[/yellow] [bold]{event.task!r}[/bold] 跳过[dim]{reason}[/dim]")
         if on_event is not None:
             on_event(event)
 
@@ -841,11 +845,11 @@ def run(
 
 def _print_dry_run(graph: Graph, layers: list[list[str]]) -> None:
     """打印执行计划但不运行任何任务。"""
-    print(f"Dry run: {len(graph)} tasks, {len(layers)} layers")
+    _verbose_console.print(f"[bold]Dry run:[/bold] [cyan]{len(graph)}[/cyan] tasks, [cyan]{len(layers)}[/cyan] layers")
     for idx, layer in enumerate(layers, 1):
-        print(f"  Layer {idx}: {layer}")
+        _verbose_console.print(f"  [dim]Layer {idx}:[/dim] {layer}")
         for name in layer:
-            print(f"    - {describe_injection(graph.resolved_spec(name))}")
+            _verbose_console.print(f"    [cyan]-[/cyan] {describe_injection(graph.resolved_spec(name))}")
 
 
 def _drive_sequential(

tests/test_runner.py

@@ -281,23 +281,23 @@ class TestCliRunnerVerbose:
         runner = px.CliRunner(aliases={"echo": _echo_graph()})
         _ = runner.run(["echo"])
         captured = capsys.readouterr()
-        # verbose 模式下应打印任务生命周期
-        assert "[verbose]" in captured.out
+        # verbose 模式下应打印任务生命周期 (✓ = 成功标记)
+        assert "✓" in captured.out
 
     def test_quiet_flag_disables_verbose(self, capsys: pytest.CaptureFixture[str]) -> None:
         """--quiet 应关闭 verbose 输出."""
         runner = px.CliRunner(aliases={"echo": _echo_graph()})
         _ = runner.run(["echo", "--quiet"])
         captured = capsys.readouterr()
-        # quiet 模式下不应有 [verbose] 前缀的输出
-        assert "[verbose]" not in captured.out
+        # quiet 模式下不应有 verbose 生命周期输出
+        assert "✓" not in captured.out
 
     def test_verbose_false_constructor_disables_verbose(self, capsys: pytest.CaptureFixture[str]) -> None:
         """构造时 verbose=False 应关闭 verbose 输出."""
         runner = px.CliRunner(aliases={"echo": _echo_graph()}, verbose=False)
         _ = runner.run(["echo"])
         captured = capsys.readouterr()
-        assert "[verbose]" not in captured.out
+        assert "✓" not in captured.out
 
     def test_verbose_prints_command_for_cmd_task(self, capsys: pytest.CaptureFixture[str]) -> None:
         """verbose 模式下 cmd 任务应打印执行的命令."""