基于 CLI-Anything Harness 的 Dify Workflow DSL 命令行技能实战指南

本文以 skills/cli-anything-dify-workflow/SKILL.md 为核心骨架，结合 dify-workflow/agent-harness 下的 CLI 包装器源码、后端适配器与测试用例，系统讲解如何通过 cli-anything-dify-workflow 命令在本地对 Dify YAML/JSON DSL 工作流文件完成创建、检查、校验、编辑与导出等全生命周期操作，并深入剖析其"透传式包装器"的底层实现原理。读完本文，你将掌握 Dify 工作流 DSL 的命令行操作范式，并能理解 CLI-Anything 生态中 AI Agent 如何发现、加载并使用这类软件技能。

一、技能定位：一个面向 Dify DSL 的 CLI 包装器

cli-anything-dify-workflow 是 CLI-Anything 生态中针对 Dify 工作流 DSL 的命令行技能（Skill）。它并非重新实现 Dify 工作流引擎，而是对开源项目 dify-ai-workflow-tools 提供的 dify-workflow CLI 做了一层"包装器（wrapper）"封装，从而让 AI Agent 能够通过 CLI-Hub 发现它、加载它的技能元数据并使用它完成对本地 Dify 工作流文件的编辑。

按照 dify-workflow/agent-harness/DIFY_WORKFLOW.md 中的交互模型，完整的调用链路如下：

AI Agent
  -> cli-anything-dify-workflow
     -> installed dify-workflow CLI / dify_workflow Python package
        -> local Dify YAML/JSON DSL files

这条链路说明：上层是 AI Agent（或人类用户），中间是本技能提供的统一命令入口，真正的工作流 DSL 编写逻辑由上游 dify-workflow CLI 承担，最终所有操作都落在本地 Dify YAML/JSON DSL 文件上。

采用这种"包装器"设计的原因在该架构文档中也有说明：上游项目已经是一个成熟的 CLI，无需在 CLI-Anything 内部重写；本仓库遵循既有的包装器模式，把上游 CLI 通过统一的 cli_anything 命名空间暴露出来，并补齐 SKILL.md 技能元数据、统一 REPL 皮肤、CLI-Hub 注册集成以及包装器发现/转发行为的测试。

二、安装：两步走的前置依赖

技能的安装分为两步，顺序不能颠倒，因为包装器在运行时需要先解析到上游 CLI。

第一步：安装上游 Dify workflow CLI

python -m pip install "dify-ai-workflow-tools @ git+https://github.com/Akabane71/dify-workflow-cli.git@main"

上游项目提供了真正的 Dify DSL 工作流编写引擎。若上游项目日后发布到 PyPI，也可以把这一步替换为常规的 PyPI 安装（README.md 中明确给出了这一备选方案）。

第二步：安装 CLI-Anything 包装器

pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=dify-workflow/agent-harness

从 setup.py 可以看到该包的安装约束：

• python_requires=">=3.10"，即要求 Python 3.10 及以上版本；
• 运行依赖为 click>=8.0.0 与 prompt-toolkit>=3.0.0，前者支撑命令解析与透传，后者支撑交互式 REPL 皮肤；
• 通过 entry_points 注册了控制台脚本 cli-anything-dify-workflow，其入口函数为 cli_anything.dify_workflow.dify_workflow_cli:main；
• 通过 package_data 把 skills/*.md 打进包内，保证安装后技能元数据仍可被发现。

注意：包装器本身对上游 CLI 的可用性非常敏感。若 dify-workflow 命令不存在，且 dify_workflow Python 包也未安装，后端适配器会抛出带安装指引的 RuntimeError（详见下文"底层实现"部分），因此请务必先完成第一步安装。

三、基础用法：从查看指南到创建校验

安装完成后，即可通过统一的 cli-anything-dify-workflow 命令操作 Dify 工作流。该命令将参数原样转发给上游 dify-workflow CLI。以下为 skills/cli-anything-dify-workflow/SKILL.md 提供的完整用法示例：

# 查看上游使用指南
cli-anything-dify-workflow guide

# 列出支持的 Dify 节点类型
cli-anything-dify-workflow list-node-types

# 以 llm 模板创建一个 workflow 模式的新应用
cli-anything-dify-workflow create -o workflow.yaml --mode workflow --template llm

# 以 JSON 输出检查工作流文件
cli-anything-dify-workflow inspect workflow.yaml -j

# 以 JSON 输出校验工作流文件
cli-anything-dify-workflow validate workflow.yaml -j

# 编辑：向工作流追加一个名为 "Process" 的 code 节点
cli-anything-dify-workflow edit add-node -f workflow.yaml --type code --title "Process"

# 配置：为 app.yaml 设置 openai 提供商的 gpt-4o 模型
cli-anything-dify-workflow config set-model -f app.yaml --provider openai --name gpt-4o

值得强调的是 -j / --json-output 参数的优先级。SKILL.md 的 Agent Guidance 部分明确建议：当上游命令支持 JSON 输出时，优先使用它。这一建议对 AI Agent 尤其重要——结构化的 JSON 输出比人类友好的文本更易于 Agent 程序化解析，例如 inspect -j 的结果可以直接反序列化为 JSON 对象以提取节点拓扑信息。

在 test_full_e2e.py 中，可以看到这套用法的端到端验证逻辑：

• create -o <path> --template llm -j 应返回 {"status": "created"}；
• 随后对同一文件执行 validate -j 应返回 {"valid": true}；
• inspect <path> -j 的输出应以 { 开头，即 JSON 对象。

这说明"创建 → 校验 → 检查"是经过测试保障的标准工作流生命周期，Agent 可以放心地把这三步串联成一条自动化流水线。

四、命令组全景：十二个命令族的职责划分

SKILL.md 列出的命令组完整清单如下：

命令组	职责	子命令
guide	展示上游教程	—
list-node-types	列出支持的 Dify 节点类型	—
create	创建新的 Dify 应用	—
inspect	检查工作流文件	—
validate	校验工作流文件	—
checklist	运行检查清单	—
edit	工作流图变更操作	add-node、remove-node、update-node、add-edge、remove-edge、set-title
config	模型/对话配置变更操作	set-model、set-prompt、add-variable、set-opening、add-question、add-tool、remove-tool
export	导出 YAML 或 JSON	—
import	导入并规范化工作流文件	—
diff	比较两个工作流文件	—
layout	自动布局节点	—

从 dify_workflow_cli.py 的源码可以看到 edit 与 config 这两个多级命令组的实现方式：

• edit 组提供了 add-node、remove-node、update-node、add-edge、remove-edge、set-title 六个子命令，覆盖了 Dify 工作流图（graph）中节点（node）与边（edge）的增删改，以及标题修改；
• config 组提供了 set-model、set-prompt、add-variable、set-opening、add-question、add-tool、remove-tool 七个子命令，覆盖了 Chat/Agent/Completion 三类应用配置的常见修改场景。

整体上，这两组命令分别对应 Dify DSL 的两大构成：图结构（graph） 与 应用配置（app config）。export 与 import 负责格式转换与规范化，diff 负责版本对比，layout 负责可视化排版——十二个命令族合在一起，足以支撑一个 Dify 工作流文件从创建到发布的完整命令行工作流。

五、交互式 REPL：进入 Dify 上下文终端

除了单次命令调用，cli-anything-dify-workflow 还提供了一个轻量级的透传 REPL。当你直接运行 cli-anything-dify-workflow 而不带任何子命令时，会进入交互式会话（dify_workflow_cli.py 中，invoke_without_command=True 的入口会触发 repl 命令）。

REPL 会话中可以直接输入上游命令而无需再带二进制名，例如：

guide | list-node-types | create -o app.yaml --template llm

支持的内置指令包括：

• help：列出 wrapper 支持的命令及其说明（见 dify_workflow_cli.py 中的命令表）；
• quit / exit：退出会话，并打印定制的告别信息。

REPL 界面由统一的 repl_skin.py 提供——这是 CLI-Anything 所有包装器共享的"皮肤"组件，负责统一的品牌横幅、彩色提示符（带 ◆ 图标与 dify 上下文标记）、命令历史持久化（默认保存在 ~/.cli-anything-dify_workflow/history）、自动建议以及帮助列表渲染。它还会在启动横幅中向 AI Agent 展示技能安装命令与全局技能路径，帮助 Agent 发现配套的 SKILL.md。

六、底层实现：透传包装器的三处关键设计

1. 上游命令的后端解析（Backend Discovery）

utils/dify_workflow_backend.py 中的 require_dify_workflow_command() 实现了按优先级解析上游入口的逻辑：

1. 先通过 shutil.which("dify-workflow") 查找 PATH 中的可执行文件；
2. 若不存在，则回退检查 importlib.util.find_spec("dify_workflow")，发现已安装 Python 包时使用 python -m dify_workflow.cli 方式调用；
3. 两者皆无则抛出带安装指引的 RuntimeError。

这正是 SKILL.md Agent Guidance 中"若 dify-workflow 不在 PATH 上但 dify_workflow Python 包已安装，则回退到 python -m dify_workflow.cli"这一行为的源码出处。对应的单元测试见 test_core.py，它分别 mock 了三种解析场景，并验证 build_command 会把透传参数正确追加到解析结果之后（例如 build_command(["guide", "-j"]) 得到 ["dify-workflow", "guide", "-j"]）。

2. 参数透传机制（Pass-through）

dify_workflow_cli.py 中所有子命令都使用了一组特殊的 Click 上下文设置：

PASS_ARGS = {
    "ignore_unknown_options": True,
    "allow_extra_args": True,
}

ignore_unknown_options=True 让包装器不去校验上游的参数名，allow_extra_args=True 允许收集多余参数。随后 _forward() 将前缀（如 edit、add-node）与当前上下文中捕获的 args 拼接，交给 run_dify_workflow 以子进程方式执行，再把 stdout 回显给调用者。这就是"包装器不认识 --provider openai 也能正确转发"的原因——透传层只负责搬运，不负责理解。

3. 子进程执行与错误收敛（Subprocess Bridge）

run_dify_workflow()（dify_workflow_backend.py）使用 subprocess.run 捕获输出；返回码非零时，把 stderr（或 stdout）去空格后作为 RuntimeError 抛出，由 Click 层包装为 ClickException 展示。此外，_configure_stdio() 在模块加载时就把标准输出/错误重配置为 UTF-8 编码，保证在 Windows 等本地化环境下转发的输出依然可读（dify_workflow_cli.py）。

这套"后端解析 + 参数透传 + 子进程执行"的设计，使得包装器本身几乎不含业务逻辑，从而将维护成本降到最低，同时把出错信息清晰、稳定地暴露给上层 Agent。

七、测试策略与质量保障

该技能的测试分为两层（见 DIFY_WORKFLOW.md 的 Testing Strategy 小节）：

• test_core.py：不依赖上游 CLI 的纯单元测试，覆盖后端发现逻辑（PATH 命中、模块回退、安装指引报错、参数拼接）、包装器 --help 渲染、以及安装包元数据（README 两步安装说明、SKILL.md 中的 wrapper 行为描述）；
• test_full_e2e.py：要求上游 CLI 真实可用并响应 --help 的冒烟测试与工作流生命周期测试，验证 create → validate → inspect 的完整链路返回结构化 JSON 结果。

运行测试的方式（见 README.md）：

python -m pytest cli_anything/dify_workflow/tests/ -v

测试文件中还支持 CLI_ANYTHING_FORCE_INSTALLED=1 环境变量来强制要求使用 PATH 上的已安装二进制（test_full_e2e.py），便于在 CI 中严格验证安装产物。

八、Agent 使用指引与安全边界

综合 SKILL.md 的 Agent Guidance 与 README.md 的安全说明，使用该技能时有四条原则：

1. 优先 JSON 输出：上游命令支持 -j / --json-output 时优先使用，便于程序化解析与后续操作决策；
2. 明确职责边界：该包装器只做转发，真正的 Dify 工作流逻辑由上游项目提供，排查深层问题时应转向上游 dify-workflow CLI 及其文档；
3. 本地文件操作：所有操作均是对本地 Dify YAML/JSON DSL 文件的编辑，不涉及远端 Dify 平台调用；
4. 导入前复查：将生成的 YAML/JSON 导入生产 Dify 项目之前，应先人工（或 Agent 二次检查）审阅文件内容，确保节点拓扑与配置符合预期。

九、小结

cli-anything-dify-workflow 以极薄的透传层把成熟的上游 dify-workflow CLI 接入 CLI-Anything 生态：对 Agent 而言，它提供了可通过 CLI-Hub 发现、有 SKILL.md 元数据、带统一 REPL 皮肤的命令入口；对开发者而言，它展示了"包装器 Harness"这一复用型集成范式的完整实现——后端解析、参数透传、子进程桥接、单元测试与 E2E 测试双保险。掌握了本技能，你就能在纯命令行环境中完成 Dify 工作流文件的创建、检查、校验、图编辑、配置修改、导出、导入、对比与布局，为 AI Agent 驱动 Dify DSL 开发铺平道路。

延伸阅读：如果你想深入理解该技能在 CLI-Anything 中的定位，可继续阅读仓库根目录 README.md 了解整体生态；技能元数据本体位于 skills/cli-anything-dify-workflow/SKILL.md；架构说明见 dify-workflow/agent-harness/DIFY_WORKFLOW.md。