Dify Harness

Dify Harness 是一个面向 Agent 的 Dify 工作流辅助包。它会安装两部分：

• difyctl：本机命令行，用于登录 Dify、同步工作流、运行和查看 trace。
• dify-skills：给 Codex、Claude Code 等 Agent 使用的 Dify 操作说明。

用户通常不需要记住大量 difyctl 命令。完成安装和登录后，直接让 Agent 帮你查询、编辑、调试和发布 Dify 工作流即可。

安装

在你的项目目录中运行：

npx @hqc1214/dify-harness install --scope project

默认情况下，安装器会调用 npx skills 进入交互式选择，让你选择要安装到哪个 Agent。

如果需要自动化安装，或明确指定 Agent：

npx @hqc1214/dify-harness install --agent codex --scope project
npx @hqc1214/dify-harness install --agent claude-code --scope global

安装完成后检查：

npx @hqc1214/dify-harness doctor
difyctl version

如果 macOS/Linux 下提示找不到 difyctl，把下面这行加入你的 shell 配置：

export PATH="$HOME/.dify-harness/bin:$PATH"

Windows 安装器会写入用户级 PATH。已经打开的旧终端可能需要重开后才能直接使用 difyctl。

登录 Dify

登录由人手动执行。不要把 Dify 密码交给 Agent。

difyctl login --base-url <DIFY_BASE_URL> --email <EMAIL> --password '<PASSWORD>'
difyctl whoami
difyctl status

whoami 和 status 能正常显示账号与 workspace 后，就可以回到 Agent 对话中提出需求。

如何让 Agent 使用

安装 skill 并登录后，直接用自然语言描述你要做的事。Agent 会根据 dify-skills 选择合适的 difyctl 命令和工作流编辑流程。

常见问法：

查询类

• “帮我查询当前 Dify 实例里有哪些 workflow app，并找到名字包含 质检 的项目。”
• “帮我查询某个插件的 provider、tool 和 schema，判断能不能接入这个工作流。”
• “帮我查看 app <app_id> 最近一次执行 trace，定位失败节点和错误原因。”

编辑类

• “帮我新建一个 Dify 工作流：输入录音和话术文档，输出质检报告。”
• “基于 app <app_id> 的现有 draft，增加一个规则判断节点，并写回草稿。”
• “帮我把这个工作流拆成更清晰的节点，避免一个 LLM 节点承担太多职责。”

调优类

• “这是输入文件和期望输出，请运行 draft，结合 trace 反复调优，直到输出满足要求。”
• “这个工作流输出不稳定，请根据节点 trace 找出问题，并调整提示词或节点结构。”
• “帮我比较多次运行结果，判断失败是输入问题、插件问题，还是工作流 DSL 问题。”

运维类

• “确认这个工作流可以发布后，发布一个版本，版本名用 qc-v1。”
• “帮我查询已发布版本和最近 published run 的执行结果。”
• “帮我验证 published 版本是否和 draft 调试结果一致。”

使用边界

• 登录、密码输入和 npm 发布等账号操作由人手动完成。
• Agent 可以帮助你操作 Dify 工作流，但发布会影响线上应用；涉及发布时请明确授权。
• workflow YAML、插件 schema、trace 分析等细节由 dify-skills 负责，不需要在 README 中学习完整命令手册。