pf 统一 CLI 入口
================

所有工具通过 ``pf <tool> [command] [options]`` 调用。工具定义在 ``cli/configs/`` 目录下的 YAML 文件中。

基本用法
--------

.. code-block:: bash

   pf                         # 列出所有可用工具
   pf filedate                # 查看 filedate 工具帮助
   pf filedate add a.txt      # 调用 filedate 的 add 子命令
   pf gitt c                  # 调用 gittool 的 c 子命令
   pf pymake b                # 调用 pymake 的 b 别名

全局选项
--------

所有 YAML 工具支持以下全局选项：

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - 选项
     - 说明
   * - ``--dry-run``
     - 仅打印执行计划，不执行
   * - ``--quiet`` / ``-q``
     - 减少输出，不显示执行过程
   * - ``--strategy``
     - 执行策略（``sequential`` / ``thread`` / ``async`` / ``dependency``）
   * - ``--list``
     - 列出所有任务名后退出

默认 ``verbose`` 开启，显示执行过程（任务开始/命令/返回码/任务成功）。``--quiet`` 关闭。

YAML 配置工具
--------------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - 工具
     - 别名
     - 说明
   * - ``filedate``
     - ``fd``
     - 文件日期处理
   * - ``filelevel``
     - ``fl``
     - 文件等级重命名
   * - ``folderback``
     - ``fb``
     - 文件夹备份
   * - ``folderzip``
     - ``fz``
     - 文件夹压缩
   * - ``gittool``
     - ``gitt``
     - Git 执行工具
   * - ``lscalc``
     - ``ls``
     - LS-DYNA 计算工具
   * - ``packtool``
     - ``pack``
     - Python 打包工具
   * - ``pdftool``
     - ``pdf``
     - PDF 文件工具集
   * - ``piptool``
     - ``pip``
     - pip 包管理工具
   * - ``screenshot``
     - ``ss``
     - 截图工具
   * - ``sshcopyid``
     - ``ssh``
     - SSH 密钥部署工具
   * - ``autofmt``
     - ``af``
     - 自动格式化工具
   * - ``bumpversion``
     - ``bump``
     - 版本号自动管理工具

传统工具
--------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - 工具
     - 说明
   * - ``pymake``
     - 构建工具（替代 Makefile），如 ``pf pymake b`` 构建
   * - ``yamlrun``
     - YAML pipeline 执行器，``pf yamlrun pipeline.yaml``
   * - ``profiler``
     - 性能分析
   * - ``emlman``
     - 邮件管理
   * - ``reseticon``
     - 重置图标缓存

自定义工具
----------

在 ``cli/configs/`` 目录新建 ``<tool>.yaml`` 即可被 ``pf`` 自动发现：

.. code-block:: yaml

   # cli/configs/mytool.yaml
   strategy: sequential
   variables:
     MSG: "hello"
   cli:
     description: "我的工具"
     usage: "pf mytool [command]"
     subcommands:
       greet:
         help: "打招呼"
   jobs:
     greet:
       cmd: ["echo", "${MSG}"]

执行::

   pf mytool greet

CliRunner（编程式）
-------------------

``CliRunner`` 把多个 Graph 映射为命令行子命令，适合构建项目专属构建工具：

.. code-block:: python

   runner = px.CliRunner(
       strategy="sequential",
       description="My Build Tool",
       graphs={
           "clean": clean_graph,
           "build": build_graph,
           "test": test_graph,
       },
   )
   runner.run_cli()  # 解析 sys.argv 并执行

命令行::

   pf pymake clean
   pf pymake build --strategy thread
   pf pymake test --dry-run
   pf pymake --list
   pf pymake --quiet