结果、错误与退出码

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

输出去向

命令的结果一律以 JSON 输出到 stdout，错误和通知则输出到 stderr：

错误：在终端中显示为文本；如果把 stderr 重定向到文件或交给其他程序（例如 2> errors.log），则以 JSON 输出。要让终端中的错误也以 JSON 显示，加上 --json。
通知（如 stream ended early: …）：始终是纯文本。

读取运行结果

run console_app 命令的结果包含应用的回答，以及后续操作要用到的 ID：

字段	内容
`text.answer`	聊天助手、旧版 Agent 应用、Chatflow 应用或文本生成应用的回复。运行 Workflow 应用时为空。
`outputs`	Workflow 应用的回答，键名对应输出节点的变量。Chatflow 应用会在这里再给出一次回复，并附上它返回的文件（如有）。
`run_id`	Workflow 或 Chatflow 应用的运行 ID，可传给 `describe run` 和 `get run node`。
`conversation_id`	聊天助手、旧版 Agent 应用或 Chatflow 应用的会话 ID，用 `--conversation-id` 传回即可继续会话。

判断运行如何结束

在脚本中，应读取结果的 status。运行无论是正常结束、中途暂停还是被截断，退出码都是 0，要靠 status 来区分：

ended：运行已结束。
suspended：运行在人工介入表单处暂停。结果的 hints 为每个操作按钮各给出一条命令，要填写表单，运行与你所选操作对应的那条即可。
incomplete：运行还没结束，结果就被截断了，例如你按下了 Ctrl+C。结果中只有截断前已收到的内容。Workflow 或 Chatflow 应用的运行仍会在服务器上继续，要查看它最终如何结束，把结果中的 run_id 传给 difyctl describe run。
failed（退出码 1）：运行失败或被停止，原因见 error.message。

运行失败时，结果和其他运行一样打印到 stdout，stderr 上没有任何输出。例如，运行 Workflow 应用时漏传了必填输入：

{
  "status": "failed",
  "text": {
    "answer": ""
  },
  "hints": [],
  "run_id": "f16c3509-ef54-4618-ae93-770724ab278d",
  "total_tokens": 0,
  "error": {
    "message": "topic is required in input form"
  }
}

解读错误信息

命令如果在产生结果之前就失败，stdout 上不会有任何输出，错误会打印到 stderr。下面是传入不存在的应用 ID 时，以 JSON 输出的错误：

{
  "error": {
    "code": "server_error",
    "message": "app not found",
    "http_status": 404,
    "method": "GET",
    "url": "https://dify.example.com/openapi/v1/apps/00000000-0000-4000-8000-000000000000",
    "server": {
      "code": "not_found",
      "message": "app not found",
      "status": 404
    }
  }
}

每个错误都带有 code 和 message，脚本要根据 code 走不同分支。根据失败原因，错误还可能带有以下字段：

hint：用一句话说明下一步可以怎么做，例如 run difyctl help get console_app。
http_status、method、url 和 server（服务器自身的错误）：错误由服务器返回时才会带有。遇到 server_error 时，根据 http_status 或 server.code 走不同分支，例如上例中的 404 和 not_found。
details：某个值没有通过 difyctl 自身的校验（input_invalid）时才会带有，列出每个校验失败的字段及其标志和原因，例如 "field": "--limit", "msg": "must be integer"。

在终端中，如果服务器给出了自己的错误码，错误的第一行会显示这个错误码，所以上例中找不到应用的错误显示为 not_found: app not found。脚本分支时要用 JSON 中的错误码，这里是 server_error。如果 message 说不清失败原因，加上 --verbose，错误中就会带上 raw_response，即服务器的完整响应。

退出码

每条命令退出时都会返回以下某个退出码：

退出码	含义	错误码
0	成功，包括暂停（`suspended`）或被截断（`incomplete`）的运行
1	运行失败，或其他各行未涵盖的错误，例如服务器错误或网络错误	`server_error`、`network_connection`、`keyring_unavailable`、`skill_missing`、`unknown`
2	`difyctl` 在发送前就拒绝了命令：标志未知、缺少必填标志，或值的类型不对	`usage_invalid_flag`、`usage_missing_arg`、`input_invalid`、`config_invalid_key`、`config_invalid_value`
4	未登录、登录已过期，或没有访问权限	`not_logged_in`、`auth_expired`、`access_denied`
6	服务器上没有这条命令，或 `difyctl` 无法获取服务器的命令列表	`unknown_op`、`catalog_unavailable`
7	触发了限流	`rate_limited`

退出码为 1 时，先看 stdout，运行失败的结果就输出在那里。其他错误都在 stderr 中。具体错误的解决方法，可到故障排查中查找。

重试失败的命令

读取类命令（如 get 和 describe）可放心重试。help 会在每条命令的描述旁显示它的标签：read、write 或 destructive。重试 write 或 destructive 命令前，先确认第一次是否已经生效，例如用对应的 get 或 describe 命令查看。运行类命令属于 write，重试会另起一次新的运行。遇到退出码 7 时，任何命令都可放心重试，运行类命令也不例外：被限流拒绝的命令在服务器上什么都没做。对于退出码 2 和 4，在解决标志写错、登录过期等问题之前，每次重试都会得到同样的退出码。

限流

命令以退出码 7 退出时，等待 1 分钟后再重试。每次登录默认每分钟最多可发送 60 次请求。要调整上限，在服务器上设置 OPENAPI_RATE_LIMIT_PER_TOKEN，设为 0 则关闭限流。

故障排查

错误信息	错误码	处理方法
`invalid bearer`	`auth_expired`	登录已过期或已失效。重新登录。
`not logged in: …`	`not_logged_in`	先登录。如果已经登录，将 `DIFY_CONFIG_DIR` 指向登录时所用的配置目录。
因情况而异，例如 `insufficient workspace role`	`access_denied`	你的工作空间角色或某项工作空间设置（例如谁可以安装集成）不允许此操作。
`no command or server operation named <words>`	`unknown_op`	用 `difyctl help` 核对命令。如果拼写无误，说明服务器的 Dify 版本没有这条命令。
`failed to fetch the catalog: …`	`catalog_unavailable`	确认服务器正在运行，且登录时用的地址正确。
`<method> <url> timed out after <ms>ms`	`network_connection`	调高 `http.timeout`。
`Internal Server Error`（HTTP 503），每条命令都出现	`server_error`	在服务器上将 `ENABLE_OAUTH_BEARER` 设为 `true`。

​输出去向

​读取运行结果

​判断运行如何结束

​解读错误信息

​退出码

​重试失败的命令

​限流

​故障排查