fcmd

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

特性

• 极速冷启动（< 100ms）：三层懒加载，重型依赖（Pillow/pymupdf/cryptography 等）仅在用到时导入
• DAG 任务调度：四种执行策略（sequential/thread/async/dependency）
• 组合 API 简洁：@fx.task 装饰器 + 自动依赖推断 + @fx.tool CLI 工具
• 基于 rich 的控制台渲染：彩色输出、表格与终端宽度自适应
• 便捷脚本模式：fcmd pymake b 一键调用
• YAML 编排：GitHub Actions 风格的 jobs/needs/matrix/if 任务图
• 零配置工具发现：fcmd/tools/ 下的模块自动注册为 CLI 子命令

安装

pip install fcmd          # 或 uv add fcmd

可选依赖（按需安装）：

要求 Python ≥ 3.13。

快速上手

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 自带 7 个内建命令（不通过 @fx.tool 注册）：

shell 补全安装：

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

工具列表

61 个工具（其中 11 个为 Python 模块工具——archivex/bumpversion/envdev/filecheck/gittool/lscalc/packtool/portcheck/pymake/screenshot/zipencrypt；其余 50 个为 DSL 声明式工具——纯 exec 与 compute 工具（clr/autofmt/dockercmd/sshcopyid/reseticoncache/piptool）及 action 原语工具（setenv/writefile/filedate/filerename/filelevel/folderback/taskkill/which/sysinfo）由 DSL 声明），按用途分组：

项目构建与发布

文件与目录

文本与编码

数据格式

多媒体（可选依赖）

系统与进程

开发环境

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

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.core.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

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.9", "3.10"]
      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.core.orchestration.yaml_loader import load_yaml
from fcmd.core.execution.executors import run

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

命令定义 DSL

exec 型简单命令无需编写 Python 模块，用 TOML 声明即可注册为工具。两种形态：单命令（[commands.<name>]，如内置的 clr）与多子命令（[commands.<tool>.<sub>]，如内置的 pymake/gittool/autofmt 纯 exec 子命令）。两级配置：包内 fcmd/commands/*.toml（出厂命令，按工具拆分为多个 TOML 文件）与 ${FCMD_HOME:-~/.fcmd}/commands.toml（用户自定义，同名可覆盖内置单命令；与 Python 模块工具重名时 Python 优先，多子命令形态逐子命令合并注册——同名子命令先注册者优先，用户仅可新增子命令）。

# ~/.fcmd/commands.toml
[commands.hello]
help = "向某人问好"
cmd = "echo 你好 {name} x{count}"
cwd = "/tmp"                     # 可选：工作目录（支持 {参数名} 插值）
timeout = 30                     # 可选：超时秒数
env = { LANG = "zh" }            # 可选：环境变量（值支持插值）
message = "同步完成: {name}"       # 可选：执行成功后打印的完成消息（支持插值，dry-run 不打印；目标被 when 守卫跳过时不打印）
fail_message = "同步失败"          # 可选：执行失败后打印的失败消息（支持插值，如修复提示）

[commands.hello.args.name]       # 无 default → positional 参数
help = "目标名字"

[commands.hello.args.count]
type = "int"                     # str(默认)/int/float/bool/path/choices/list
default = 1                      # 有 default → --count 选项（list 无 default → positional 多值）
help = "次数"

[commands.publish]               # {参数名:content} 文件内容插值：读取文件内容（展开 ~，utf-8，去首尾空白）替换进 cmd
help = "发布文件备注"
cmd = ["notes-cli", "publish", "--text", "{note:content}"]
[commands.publish.args.note]
type = "path"                    # content 插值仅支持 type=str/path 参数
default = "~/note.txt"

[commands.pkg.install]           # list 参数：独占占位符按元素展开（无 shell 每元素一个 token）
help = "批量安装"
cmd = ["pip", "install", "{packages}"]
[commands.pkg.install.args.packages]
type = "list"
help = "包名列表"

[commands.fmttool.lint]          # bool 参数 on：值为真时向 cmd 尾部追加固定 token
help = "检查并可选自动修复"
cmd = ["ruff", "check", "{target}"]
[commands.fmttool.lint.args.target]
type = "str"
default = "."
[commands.fmttool.lint.args.fix]
type = "bool"
default = false
on = ["--fix", "--unsafe-fixes"]

[commands.deploy.build]           # when 守卫：探针不满足 → SKIPPED（命令退出码 0）
help = "有代码变更才构建"
cmd = ["make", "build"]
when = {cmd = "git status --porcelain", expect = "nonempty"}  # 探针 cmd/path 二选一，支持 {参数名} 插值
allow_upstream_skip = true        # 上游被跳过时豁免执行（默认连坐跳过）

[commands.backup.files]           # 探针 expect：cmd 用 nonempty/empty/success/failure，path 用 exists/missing
help = "目录已备份则跳过"
cmd = ["robocopy", "{source}", "{dest}", "/mir"]
when = {path = "{dest}", expect = "missing"}  # path 探针支持插值与 ~ 展开

[commands.deploy.all]             # 聚合可声明 args：值经共享变量流入子任务插值
help = "构建并部署"
needs = ["build"]
[commands.deploy.all.args.tag]
type = "str"
default = "latest"

[commands.dockercmd.login]        # tty 透传：stdout/stderr 不捕获（交互式命令）
help = "登录 Docker 镜像仓库"
cmd = ["docker", "login", "--username", "{username}", "{registry}"]
tty = true                        # 密码提示可见可输入
message = "已登录镜像仓库: {registry} (用户: {username})"
[commands.dockercmd.login.args.username]
default = ""
default_env = ["USERNAME", "LOGNAME", "USER", "LNAME"]  # 值等于 default 时按链取第一个非空环境变量

[commands.setenv]                 # action 原语：进程内动作（fn 任务，非 subprocess）
help = "设置环境变量"
action = "setenv"                 # 内建动作名；参数 schema 来自动作实现签名（禁声明 args）
message = "环境变量 {name} 已设置"

[commands.pkg.u]                  # compute 计算原语：采集→计算→注入 exec 参数（输出管道）
help = "卸载包（支持通配符）"
cmd = ["pip", "uninstall", "-y", "{expanded}"]
[commands.pkg.u.args.packages]
type = "list"
[commands.pkg.u.compute]
action = "pip_expand"             # 计算动作：输入按实现签名取 CLI 变量，返回值注入 {expanded}
as = "expanded"                   # 空结果（空 list/空串）→ SKIPPED；同链同名只计算一次

[commands.sync]
help = "同步（跨平台示例）"
win.cmd = "robocopy src dst /mir"   # 字符串 → shell 执行
unix.cmd = ["rsync", "-a", "src/", "dst"]  # 数组 → 无 shell（注入面最小）
aliases = ["sy"]

# 多子命令形态：与 Python 模块同名的工具逐子命令合并注册
[commands.mytool.go]
help = "执行构建"
cmd = ["make", "build"]

[commands.mytool.all]
help = "聚合（needs 编排，无 cmd）"
needs = ["go"]
strategy = "thread"              # sequential/thread/async/dependency

fcmd hello world --count 3        # echo 你好 world x3
fcmd sy                           # 别名调用
fcmd mytool all                   # 聚合：先 go 后 all（thread 并行）

能力边界：单命令与多子命令 exec 形态（平台分支 / 参数（含 list 多值、bool on 固定 token 与 default_env 环境回退链） / 插值（含 {参数名:content} 文件内容插值） / cwd / env / timeout / when 守卫探针（支持参数插值与返回码判定）/ needs 聚合（含 allow_upstream_skip 豁免连坐）/ 聚合 args 共享插值 / tty 透传 / message 与 fail_message post-run 消息 / strategy / action 内建动作原语（进程内 fn 任务，参数 schema 来自动作实现签名）/ compute 计算原语（进程内计算动作返回值注入 exec 参数，输出管道形态））；matrix/if 条件编排属 YAML 编排的领地。

DSL 逻辑边界

判断一段命令逻辑能否迁入 DSL：

执行策略

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

开发

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

fcmd pymake tc                # 类型检查（pyrefly + ruff）
fcmd pymake t                 # 运行测试
fcmd pymake cov               # 测试 + 覆盖率
fcmd pymake chk               # 类型检查聚合（清理 + pyrefly + lint + fmt + test_fast）

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

目录结构

src/fcmd/
  core/          # 运行时内核：DAG、报告、执行引擎、工具注册、编排、忽略规则
    toolkit/     #   函数签名 → argparse 的 CLI 工具基座
    execution/   #   sequential/thread/async/dependency 四种执行器
    orchestration/  # YAML 编排与 if 条件求值
    models/      #   通用数据模型（含 PDF）
  cli/           # 仅入口、工具发现、内建命令与诊断辅助
    _builtins/   #   graph/info/completion/yaml/env/doctor/profiler
  tools/         # Python 实现的工具模块（自动发现）
    archive/ calc/ dev/ media/ net/
  dsl/           # TOML 命令定义与 action/compute 原语
    actions/     #   内建动作（文件、文本、媒体、系统、加密等）
  commands/      # 出厂 DSL 命令定义（*.toml）
  console.py     # rich 控制台薄封装

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

公共 API（import fcmd as fx）名称保持稳定；本版本（0.4.0）将原 fcmd.apis.* / fcmd.engine.* / fcmd.models.* / fcmd.orchestration.* 深路径统一收敛到 fcmd.core.*，不保留兼容 shim。

许可证

MIT