pyflowx/.trae/docs/iter-12-cli-visualization.md

迭代 12：CLI 可视化

本轮目标

1. pf graph <yaml> 命令 —— 终端 DAG 可视化
   • --format ascii（默认）：rich Tree 渲染分层结构 + 依赖关系表
   • --format mermaid：输出 Mermaid 语法（可粘贴到 mermaid.live）
   • --format list：仅列出任务名（与 yamlrun --list 一致）
   • --format deps：纯依赖关系表
   • --orientation：Mermaid 方向（TD/TB/BT/LR/RL）
2. pf yamlrun --progress —— 启用 rich 进度条（RichProgressMonitor）

改动文件清单

• src/pyflowx/cli/pf.py —— 新增 pf graph 命令、yamlrun --progress 选项
• tests/cli/test_pf_graph.py —— 新增 CLI 测试
• README.md —— 更新文档

关键设计

1. pf graph <yaml>

ASCII 默认渲染：用 rich.tree.Tree 按层分组，每层显示任务名。 再附 rich.table.Table 显示每个任务的硬依赖/软依赖/标签。

Mermaid 输出：复用 Graph.to_mermaid()，直接打印（不加颜色，便于复制）。

deps 表格：纯依赖关系表（无分层信息）。

list：与 yamlrun --list 行为一致。

2. pf yamlrun --progress

• 添加 --progress flag
• 启用时调用 run(graph, progress=True)
• 与 --quiet 互斥（quiet 时无进度条）

3. 路由

pf graph 作为新的子命令（与 yamlrun 同级），不通过 @px.tool 注册。

验收标准

• pf graph pipeline.yaml 默认 ASCII 渲染
• pf graph pipeline.yaml --format mermaid 输出 Mermaid 文本
• pf graph pipeline.yaml --format list 列出任务名
• pf graph pipeline.yaml --format deps 显示依赖表
• pf graph pipeline.yaml --orientation LR 自定义方向
• pf yamlrun pipeline.yaml --progress 启用进度条
• YAML 加载失败时显示错误信息并返回非零退出码
• 覆盖率 ≥ 95%
• ruff / pyrefly / pytest 全部通过

验证结果

• ruff：All checks passed（含 format）
• pyrefly：0 errors
• pytest：1271 passed（含 14 个新增 CLI 测试）
• 覆盖率：97.29%（yaml_loader.py 100%；cli/pf.py 按项目惯例 omit 不计入覆盖率）
• 冒烟测试：pf graph 三种格式（ASCII/Mermaid/list）+ pf yamlrun --progress 均通过
• 附加修复：yaml_loader._safe_load 包装 yaml.YAMLError 为 ValueError，统一错误处理

遗留事项

• 无