帮助 - Dify Docs

本文档由 AI 自动翻译。如有任何不准确之处，请参考英文原版。

difyctl 的帮助系统涵盖四个层面：顶层概览、单个命令或命令组的帮助、指南主题，以及上述所有内容的机器可读形式。所有帮助内容均输出到 stdout，并以退出码 0 结束。

获取帮助

以下四种调用方式都会显示相同的顶层概览：

difyctl
difyctl help
difyctl --help
difyctl -h

该概览列出每个命令及其简介、三个入门示例、全局标志，以及指南主题。若想查看同样的清单并附带指向本参考文档的链接，参见命令索引。

查看单个命令或命令组的帮助

在任意命令后追加 --help，或在命令前加上 help：

difyctl run app --help
difyctl help run app

单个命令的帮助会显示该命令的描述、用法行、参数、带默认值的标志以及示例。指定命令组而非具体命令，可列出该组的子命令：

difyctl auth --help

COMMANDS
  auth devices list    List active sessions for the current bearer
  auth devices revoke  Revoke one or all session devices
  auth list            List all authenticated contexts (host + account pairs)
  auth login           Sign in to Dify via OAuth device flow
  auth logout          Log out of the active Dify host
  auth whoami          Print the active subject's identity

若某个名称既不匹配命令、主题，也不匹配命令组，则会以 unknown help topic: <name> 报错，给出建议并返回退出码 1。

指南主题

长篇主题随 CLI 一同分发，通过 difyctl help <topic> 阅读：

主题	涵盖内容
`account`	上手引导。
`environment`	CLI 自身对 `DIFY_*` 环境变量的说明。
`agent`	用于驱动 `difyctl` 的 Agent 所遵循的跨命令约定。

这些主题已内置于 CLI 中。要了解 difyctl 实际读取哪些变量，参见环境变量。

机器可读帮助

每个帮助层面都接受 -o json 和 -o yaml。驱动 difyctl 的编码 Agent 主要用到其中两种：先用精简命令清单选定命令，再读取该命令的描述符获取参数和标志。完整文档则把跨命令约定和主题列表一并给出。

精简命令清单

在顶层帮助上加 --compact，每个命令只输出三个字段：command（命令路径）、description（一句话描述）和 effect 标签（read、write 或 destructive）。不含其他内容，因此整份清单足够小，选定命令前可一次读完：

difyctl help -o json --compact

清单的开头几项：

{
  "commands": [
    {
      "command": "auth devices list",
      "description": "List active sessions for the current bearer",
      "effect": "read"
    },
    {
      "command": "auth devices revoke",
      "description": "Revoke one or all session devices",
      "effect": "destructive"
    },
    {
      "command": "auth list",
      "description": "List all authenticated contexts (host + account pairs)",
      "effect": "read"
    },
    {
      "command": "auth login",
      "description": "Sign in to Dify via OAuth device flow",
      "effect": "write"
    }
  ]
}

--compact 只适用于顶层帮助，且必须搭配 -o json 或 -o yaml。用在单个命令的帮助上，或未指定结构化格式时，会作为用法错误失败，退出码为 2。

单个命令的描述符

选定命令后，其描述符会补齐清单中省略的全部信息。两种单命令帮助写法都会返回它：

difyctl help auth whoami -o json
difyctl auth whoami --help -o json

{
  "command": "auth whoami",
  "description": "Print the active subject's identity",
  "effect": "read",
  "args": [],
  "flags": [
    {
      "name": "json",
      "char": null,
      "type": "boolean",
      "default": false,
      "multiple": false,
      "options": null,
      "description": "emit JSON"
    }
  ],
  "examples": [
    "difyctl auth whoami",
    "difyctl auth whoami --json"
  ],
  "agentGuide": null
}

每个描述符都带有该命令的参数和标志（含类型与默认值）、示例、effect 标签，以及在有的情况下提供的 agentGuide 字符串（面向 Agent 的命令专属指引）。

完整文档

不加 --compact 时，顶层帮助会在一份文档中输出完整的命令全貌：

difyctl help -o json

该文档包含四个顶层键：

bin：可执行文件名，即 difyctl
contract：退出码、输出格式、错误输出的结构以及跨命令规则
commands：每个命令一个完整描述符
topics：各指南主题的名称和一句话摘要，正文通过 difyctl help <topic> 读取

退出码

退出码	含义
`0`	已打印帮助
`1`	未知的帮助主题或命令名称
`2`	在顶层 `-o json` 或 `-o yaml` 帮助之外使用 `--compact`

完整方案参见输出格式与退出码。

​获取帮助

​查看单个命令或命令组的帮助

​指南主题

​机器可读帮助

​精简命令清单

​单个命令的描述符

​完整文档

​退出码