fcmd

极速 Python 工具集应用：DAG 任务调度 + 组合 CLI。

特性

• 极速冷启动（< 100ms）：三层懒加载，核心模块零外部依赖
• DAG 任务调度：四种执行策略（sequential/thread/async/dependency）
• 组合 API 简洁：@fx.task 装饰器 + 自动依赖推断 + @fx.tool CLI 工具
• 纯 CLI（rich 增强）：彩色输出、表格、进度条
• 便捷脚本模式：fcmd pymake b 一键调用
• YAML 编排：GitHub Actions 风格的 jobs/needs/matrix/if 任务图
• 零配置工具发现：fcmd/cli/ 下的模块自动注册为 CLI 子命令

安装

pip install fcmd          # 或 uv add fcmd

可选依赖（按需安装）：

要求 Python ≥ 3.8。

快速上手

Python API

import fcmd as fx

@fx.task
def extract() -> list[int]: return [1, 2, 3]

@fx.task
def double(extract: list[int]) -> list[int]: return [x * 2 for x in extract]

graph = fx.graph(extract, double)  # double 自动依赖 extract
report = fx.run(graph)
print(report["double"])  # [2, 4, 6]

CLI

fcmd                   # 列出所有工具
fcmd pymake b          # 构建
fcmd pymake tc         # 类型检查
fcmd info pymake       # 查看 pymake 子命令
fcmd graph pymake tc   # 输出 DAG（Mermaid）
fcmd env               # 查看运行环境
fcmd doctor            # 诊断环境问题

内建命令

fcmd 自带 6 个内建命令（不通过 @fx.tool 注册）：

shell 补全安装：

eval "$(fcmd completion --shell bash)"       # bash
eval "$(fcmd completion --shell zsh)"         # zsh
fcmd completion --shell fish | source         # fish

工具列表

24 个工具模块，按用途分组：

项目构建与发布

文件与目录

多媒体（可选依赖）

系统与进程

开发环境

查看任意工具的子命令与字段详情：

fcmd info <tool>                 # 列出工具所有子命令
fcmd info <tool> <subcommand>    # 展示 ToolSpec 完整字段

任务定义 API

@fx.task —— Python 函数即任务

函数参数名即依赖名，fcmd 据此自动构建 DAG：

import fcmd as fx

@fx.task
def fetch() -> str:
    return "raw data"

@fx.task
def parse(fetch: str) -> list[str]:
    return fetch.split()

@fx.task
def save(parse: list[str]) -> None:
    # parse 自动依赖 fetch，save 自动依赖 parse
    ...

report = fx.run(fx.graph(fetch, parse, save))

@fx.tool —— 函数即 CLI 子命令

import fcmd
from fcmd.models import run_command

@fcmd.tool("gittool", subcommand="a", help="git add + commit")
def add_commit(message: str, amend: bool = False) -> None:
    """添加并提交。"""
    cmd = ["git", "add", "-A"]
    run_command(cmd, check=True)
    cmd = ["git", "commit", "-m", message]
    if amend:
        cmd.append("--amend")
    run_command(cmd, check=True)

CLI 参数映射规则：

• 无默认值参数 → 位置参数（message → message）
• 有默认值参数 → --name 选项（amend: bool = False → --amend）
• bool = False → --name（store_true）
• bool = True → --no-name（store_false，保留原参数名）
• X | None / Optional[X] → 自动解包为 X（兼容 Python 3.8 PEP 604 字符串注解）

cmd / aggregate 任务

无需 Python 函数，直接用命令或聚合依赖：

@fcmd.tool("mytool", subcommand="build", cmd=["uv", "build"], help="构建")
def _build() -> None: ...  # 函数体可空，cmd 优先执行

@fcmd.tool("mytool", subcommand="all", needs=["build", "test"], strategy="dependency")
def _all() -> None: ...  # aggregate：仅声明依赖

YAML 编排

GitHub Actions 风格的 jobs/needs/matrix/if：

# deploy.yaml
strategy: thread              # 图级默认策略
defaults:
  retry: {max_attempts: 3}
  timeout: 300
  env: {CI: "true"}

jobs:
  setup:
    cmd: ["git", "clone"]

  build:
    needs: [setup]
    cmd: ["uv", "build"]
    timeout: 120

  deploy:
    needs: [build]
    run: "twine upload dist/*"
    env: {TWINE_TOKEN: "..."}
    continue-on-error: true

  notify:
    needs: [build]
    if: "failure()"           # 仅 build 失败时执行
    cmd: ["python", "-m", "notify"]

  test:
    matrix:                    # 笛卡尔积展开为 4 个任务
      py: ["3.8", "3.9"]
      os: ["linux", "windows"]
    cmd: ["pytest"]

执行：

fcmd yaml deploy.yaml                  # 执行全部 jobs
fcmd yaml deploy.yaml build            # 仅执行 build 及其依赖
fcmd yaml deploy.yaml --dry-run        # 打印执行计划不执行
fcmd yaml deploy.yaml --strategy thread  # 覆盖执行策略

或 Python API：

from fcmd.yaml_loader import load_yaml
from fcmd.executors import run

graph = load_yaml("deploy.yaml")
report = run(graph, strategy="dependency")

执行策略

四种策略通过 fx.run(graph, strategy=...) 或 fcmd yaml --strategy ... 指定：

开发

git clone <repo-url>
cd fcmd
pip install -e fcmd[dev]      # 安装开发依赖（lint + test + office + prek + tox）

fcmd pymake tc                # 类型检查（pyrefly + ruff）
fcmd pymake t                 # 运行测试
fcmd pymake cov               # 测试 + 覆盖率
fcmd pymake all               # 全套流程（清理 + 构建 + 测试 + 类型检查）

工具链独立配置文件：ruff.toml / pyrefly.toml / pytest.ini / .coveragerc / .bumpversion.toml / uv.toml / .pre-commit-config.yaml。pyproject.toml 仅含项目元数据。

新增工具：在 src/fcmd/cli/ 下新建模块（非 _ 前缀、非 main），用 @fcmd.tool 装饰器注册即可，无需修改 main.py。可选在模块内定义 __tool_aliases__: list[str] 声明别名。

许可证

MIT